feat: scaffold codespace backend

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 15:07:54 +08:00
commit 411ed1f8ba
43 changed files with 4428 additions and 0 deletions
@@ -0,0 +1,88 @@
+# 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`) |
+
+## 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"
+```
+
+The server is started through an explicit `http.Server{Handler: router}` — it does not use `gin.Engine.Run()`.
+
+## 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'
+```