138 lines
3.1 KiB
Markdown
138 lines
3.1 KiB
Markdown
# 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": "..."
|
|
}
|
|
```
|
|
|
|
---
|