# 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": "..."
}
```

---