# codespace

A runnable Go backend MVP skeleton that manages local workspaces, file operations through an abstract filesystem, and OpenCode processes.

## V1 scope

- Workspace creation, lookup, and deletion backed by local directories.
- File read/write/list/mkdir/remove/rename/stat through a `FileSystem` interface with path-escape protection.
- OpenCode process start/stop/restart/status per workspace.
- HTTP API using [Gin](https://github.com/gin-gonic/gin) for routing with JSON responses.
- Explicit `http.Server` composition with configurable timeouts and max header bytes.

### Not implemented in v1

Docker, authentication, Git integration, LSP, AI Agent orchestration, web frontend, and full watcher/WebSocket event streaming are out of scope for the first version.

## Run

```sh
make run
```

The server listens on `:8080` by default. Override via `configs/config.yaml` or environment variables:

| Variable | Description |
|---|---|
| `CODESPACE_ADDR` | Listen address |
| `CODESPACE_WORKSPACE_ROOT` | Workspace root directory |
| `CODESPACE_OPENCODE_COMMAND` | OpenCode binary path |
| `CODESPACE_READ_TIMEOUT` | HTTP read timeout (e.g. `15s`) |
| `CODESPACE_WRITE_TIMEOUT` | HTTP write timeout (e.g. `15s`) |
| `CODESPACE_IDLE_TIMEOUT` | HTTP idle timeout (e.g. `60s`) |
| `CODESPACE_MAX_HEADER_BYTES` | Max header bytes (e.g. `1048576`) |
| `CODESPACE_LOG_LEVEL` | Log level (`debug`, `info`, `warn`, `error`) |
| `CODESPACE_LOG_FORMAT` | Log format (`json`, `text`) |

## Test

```sh
make test
```

## Configuration

`configs/config.yaml`:

```yaml
server:
  addr: ":8080"
  readTimeout: "15s"
  writeTimeout: "15s"
  idleTimeout: "60s"
  maxHeaderBytes: 1048576
workspace:
  root: "./workspaces"
process:
  opencodeCommand: "opencode"
log:
  level: "info"
  format: "json"
```

The server is started through an explicit `http.Server{Handler: router}` — it does not use `gin.Engine.Run()`.

## Logging

codespace uses the Go standard library `log/slog` for application logs. Default output is JSON to stdout.

```yaml
log:
  level: "info"
  format: "json"
```

Environment overrides:

- `CODESPACE_LOG_LEVEL` (`debug`, `info`, `warn`, `error`)
- `CODESPACE_LOG_FORMAT` (`json`, `text`)

All application logs must go through `log/slog`. Do not use `fmt.Print*`, `log.Printf`, `gin.Logger()`, or third-party logging libraries in server runtime code.

## API examples

Health check:

```sh
curl -s http://localhost:8080/healthz
```

Create a workspace:

```sh
curl -s -X POST http://localhost:8080/api/workspaces \
  -H 'Content-Type: application/json' \
  -d '{"id":"user1"}'
```

Write a file:

```sh
curl -s -X PUT http://localhost:8080/api/workspaces/user1/files/write \
  -H 'Content-Type: application/json' \
  -d '{"path":"main.go","content":"package main\n"}'
```

Read a file:

```sh
curl -s 'http://localhost:8080/api/workspaces/user1/files/read?path=main.go'
```