Changeset 0.28.0.1 (#173)

2026-03-11 14:45:37 +00:00
parent 93c72daadf
commit 58313f7e31
57 changed files with 5139 additions and 3206 deletions
--- a/docs/ICD/workspaces.md
+++ b/docs/ICD/workspaces.md
@@ -0,0 +1,137 @@
+# Workspaces & Git
+
+The **Workspace** is a virtual filesystem for the editor surface.
+Each workspace has a root directory, file operations, optional Git
+integration, and full-text indexing for code search.
+
+### Workspace CRUD
+
+```
+GET    /workspaces                  → { "data": [...] }
+POST   /workspaces                  ← { "name", "owner_type", "owner_id" }
+GET    /workspaces/:id              → workspace object
+PATCH  /workspaces/:id              ← partial update
+DELETE /workspaces/:id
+```
+
+Workspace object:
+
+```json
+{
+  "id": "uuid",
+  "name": "my-project",
+  "owner_type": "user|project",
+  "owner_id": "uuid",
+  "status": "active|archived",
+  "storage_bytes": 1048576,
+  "file_count": 42,
+  "created_at": "...",
+  "updated_at": "..."
+}
+```
+
+### File Operations
+
+All paths are relative to the workspace root.
+
+```
+GET    /workspaces/:id/files?path=/           → { "files": [entries] }
+GET    /workspaces/:id/files/read?path=/a.md  → { "content": "...", "size": 123 }
+PUT    /workspaces/:id/files/write            ← { "path": "/a.md", "content": "..." }
+DELETE /workspaces/:id/files/delete            ← { "path": "/a.md" }
+POST   /workspaces/:id/files/mkdir             ← { "path": "/src" }
+```
+
+File entry:
+
+```json
+{
+  "name": "main.go",
+  "path": "/src/main.go",
+  "is_dir": false,
+  "size": 4096,
+  "modified": "..."
+}
+```
+
+### Archive
+
+**Download** (tar.gz of entire workspace):
+
+```
+GET /workspaces/:id/archive/download
+```
+
+**Upload** (restore from tar.gz):
+
+```
+POST /workspaces/:id/archive/upload
+Content-Type: multipart/form-data
+```
+
+### Reconcile, Stats, Index
+
+**Reconcile** (sync filesystem state with DB metadata):
+
+```
+POST /workspaces/:id/reconcile
+```
+
+**Stats:**
+
+```
+GET /workspaces/:id/stats
+```
+
+Returns `{ "file_count", "storage_bytes", "indexed_files", ... }`.
+
+**Index status:**
+
+```
+GET /workspaces/:id/index-status
+```
+
+Returns indexing progress for full-text search.
+
+### Git Integration
+
+All Git operations are workspace-scoped.
+
+```
+POST /workspaces/:id/git/clone     ← { "url", "branch", "credential_id" }
+POST /workspaces/:id/git/pull
+POST /workspaces/:id/git/push
+GET  /workspaces/:id/git/status    → { "files": [{ "path", "status" }] }
+GET  /workspaces/:id/git/diff      → { "diff": "..." }
+POST /workspaces/:id/git/commit    ← { "message", "files": [...] }
+GET  /workspaces/:id/git/log       → { "commits": [...] }
+GET  /workspaces/:id/git/branches  → { "branches": [...], "current": "main" }
+POST /workspaces/:id/git/checkout  ← { "branch": "feature-x" }
+```
+
+### Git Credentials
+
+User-owned, encrypted credential storage for Git operations.
+Encrypted with the user's UEK (same as BYOK keys — admins cannot
+recover).
+
+```
+POST   /git-credentials             ← { "name", "auth_type", "token"|"username"+"password"|"ssh_key" }
+GET    /git-credentials             → { "data": [GitCredentialSummary] }
+DELETE /git-credentials/:id
+```
+
+`auth_type`: `https_pat`, `https_basic`, or `ssh_key`.
+
+Summary response (never exposes encrypted data):
+
+```json
+{
+  "id": "uuid",
+  "name": "GitHub PAT",
+  "auth_type": "https_pat",
+  "created_at": "..."
+}
+```
+
+---