Changeset 0.21.1 (#86)
This commit is contained in:
976
docs/DESIGN-0.21.0.md
Normal file
976
docs/DESIGN-0.21.0.md
Normal file
@@ -0,0 +1,976 @@
|
||||
# Design — v0.21.x: Workspaces + Extension Surfaces
|
||||
|
||||
**Status:** Planning
|
||||
**Depends on:** v0.20.0 (notifications), v0.17.2 (CM6), v0.11.0 (extension foundation)
|
||||
**Feeds into:** v0.22.0 (smart routing), v0.23.0 (multi-participant channels)
|
||||
|
||||
---
|
||||
|
||||
## Guiding Principle
|
||||
|
||||
The **workspace** is a platform primitive — not an editor-mode concept. Even in
|
||||
pure chat mode, uploading a zip, having the AI operate on real files at real
|
||||
paths, and downloading the result as an archive is a first-class workflow. Every
|
||||
surface (chat, editor, article, future modes) benefits from workspace access.
|
||||
|
||||
This changes the layering: workspace infrastructure lands first as foundational
|
||||
storage, then surfaces consume it.
|
||||
|
||||
---
|
||||
|
||||
## Release Decomposition
|
||||
|
||||
```
|
||||
v0.21.0 Workspace Storage (platform primitive)
|
||||
│
|
||||
v0.21.1 Workspace Tools + Channel/Project Binding
|
||||
│
|
||||
v0.21.2 Workspace Indexing + Semantic Search
|
||||
│
|
||||
v0.21.3 Surface Infrastructure + REPL
|
||||
│
|
||||
v0.21.4 Git Integration
|
||||
│
|
||||
v0.21.5 Editor Surface (Development Mode)
|
||||
│
|
||||
v0.21.6 Article Surface + Document Output Pipeline
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## v0.21.0 — Workspace Storage
|
||||
|
||||
Pure backend. No tools, no UI, no surfaces. Just the storage primitive with
|
||||
full CRUD API and archive support.
|
||||
|
||||
### Data Model
|
||||
|
||||
**`workspaces` table**
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| `id` | UUID | PK |
|
||||
| `owner_type` | TEXT | `user`, `project`, `channel`, `team` |
|
||||
| `owner_id` | UUID | FK polymorphic |
|
||||
| `name` | TEXT | display name |
|
||||
| `root_path` | TEXT | PVC-relative path: `workspaces/{id}` |
|
||||
| `max_bytes` | BIGINT | quota (NULL = system default) |
|
||||
| `status` | TEXT | `active`, `archived`, `deleting` |
|
||||
| `created_at` | TIMESTAMPTZ | |
|
||||
| `updated_at` | TIMESTAMPTZ | |
|
||||
|
||||
Index: `(owner_type, owner_id)` — lookup workspace(s) for a given owner.
|
||||
|
||||
**`workspace_files` table** (metadata index — filesystem is source of truth)
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| `id` | UUID | PK |
|
||||
| `workspace_id` | UUID | FK → workspaces |
|
||||
| `path` | TEXT | relative path from workspace root: `src/main.go` |
|
||||
| `is_directory` | BOOLEAN | |
|
||||
| `content_type` | TEXT | MIME type (detected or inferred) |
|
||||
| `size_bytes` | BIGINT | 0 for dirs |
|
||||
| `sha256` | TEXT | content hash (NULL for dirs) |
|
||||
| `created_at` | TIMESTAMPTZ | |
|
||||
| `updated_at` | TIMESTAMPTZ | |
|
||||
|
||||
Index: `UNIQUE (workspace_id, path)` — one entry per path.
|
||||
Index: `(workspace_id, content_type)` — filter by type.
|
||||
|
||||
Design note: the DB index is a metadata cache. The PVC filesystem is the source
|
||||
of truth. Syncing happens on write operations and optionally via a reconcile
|
||||
endpoint. This avoids the complexity of fsnotify while keeping queries fast.
|
||||
|
||||
### Filesystem Layout (PVC)
|
||||
|
||||
```
|
||||
/data/storage/
|
||||
attachments/ # existing (v0.12.0)
|
||||
processing/ # existing extraction queue
|
||||
workspaces/ # NEW
|
||||
{workspace_id}/
|
||||
.workspace.json # metadata: owner, quotas, created_at
|
||||
files/ # actual file tree root
|
||||
src/
|
||||
main.go
|
||||
README.md
|
||||
```
|
||||
|
||||
Why a separate `files/` subdirectory: keeps workspace metadata (`.workspace.json`,
|
||||
future `.git/` in v0.21.4) out of the user's file namespace.
|
||||
|
||||
### Store Interface
|
||||
|
||||
```go
|
||||
type WorkspaceStore interface {
|
||||
// CRUD
|
||||
Create(ctx context.Context, w *models.Workspace) error
|
||||
GetByID(ctx context.Context, id string) (*models.Workspace, error)
|
||||
Update(ctx context.Context, id string, patch models.WorkspacePatch) error
|
||||
Delete(ctx context.Context, id string) error
|
||||
|
||||
// Ownership lookup
|
||||
GetByOwner(ctx context.Context, ownerType, ownerID string) (*models.Workspace, error)
|
||||
ListByOwner(ctx context.Context, ownerType, ownerID string) ([]models.Workspace, error)
|
||||
|
||||
// File index
|
||||
UpsertFile(ctx context.Context, f *models.WorkspaceFile) error
|
||||
DeleteFile(ctx context.Context, workspaceID, path string) error
|
||||
DeleteFilesByPrefix(ctx context.Context, workspaceID, prefix string) error
|
||||
GetFile(ctx context.Context, workspaceID, path string) (*models.WorkspaceFile, error)
|
||||
ListFiles(ctx context.Context, workspaceID, prefix string, recursive bool) ([]models.WorkspaceFile, error)
|
||||
|
||||
// Stats
|
||||
GetDiskUsage(ctx context.Context, workspaceID string) (int64, error)
|
||||
}
|
||||
```
|
||||
|
||||
### Workspace FS (Filesystem Operations)
|
||||
|
||||
Separate from the store — this operates on PVC, not DB.
|
||||
|
||||
```go
|
||||
type WorkspaceFS struct {
|
||||
basePath string // e.g. /data/storage/workspaces
|
||||
store WorkspaceStore // for metadata sync
|
||||
}
|
||||
|
||||
// File CRUD — all paths relative to workspace root
|
||||
func (fs *WorkspaceFS) ReadFile(ctx context.Context, w *models.Workspace, path string) (io.ReadCloser, int64, error)
|
||||
func (fs *WorkspaceFS) WriteFile(ctx context.Context, w *models.Workspace, path string, r io.Reader, size int64) error
|
||||
func (fs *WorkspaceFS) DeleteFile(ctx context.Context, w *models.Workspace, path string) error
|
||||
func (fs *WorkspaceFS) Mkdir(ctx context.Context, w *models.Workspace, path string) error
|
||||
func (fs *WorkspaceFS) Stat(ctx context.Context, w *models.Workspace, path string) (*models.WorkspaceFile, error)
|
||||
func (fs *WorkspaceFS) ListDir(ctx context.Context, w *models.Workspace, prefix string, recursive bool) ([]models.WorkspaceFile, error)
|
||||
|
||||
// Tree: returns full file listing with sizes (for file tree UI)
|
||||
func (fs *WorkspaceFS) Tree(ctx context.Context, w *models.Workspace) ([]models.WorkspaceFile, error)
|
||||
|
||||
// Archive operations
|
||||
func (fs *WorkspaceFS) ExtractArchive(ctx context.Context, w *models.Workspace, r io.Reader, format string) (int, error)
|
||||
func (fs *WorkspaceFS) CreateArchive(ctx context.Context, w *models.Workspace, format string) (io.ReadCloser, error)
|
||||
|
||||
// Maintenance
|
||||
func (fs *WorkspaceFS) Reconcile(ctx context.Context, w *models.Workspace) error // sync FS → DB index
|
||||
func (fs *WorkspaceFS) Destroy(ctx context.Context, w *models.Workspace) error // rm -rf + DB cleanup
|
||||
```
|
||||
|
||||
WriteFile updates the DB index (upsert workspace_files) after successful write.
|
||||
DeleteFile removes the DB row. Reconcile walks the FS and patches any drift.
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```
|
||||
POST /api/v1/workspaces # create workspace
|
||||
GET /api/v1/workspaces/:id # get metadata
|
||||
PATCH /api/v1/workspaces/:id # update name/quota
|
||||
DELETE /api/v1/workspaces/:id # delete (async cleanup)
|
||||
|
||||
GET /api/v1/workspaces/:id/files?path=&recursive= # list files
|
||||
GET /api/v1/workspaces/:id/files/read?path= # read file content
|
||||
PUT /api/v1/workspaces/:id/files/write?path= # write file (body = content)
|
||||
DELETE /api/v1/workspaces/:id/files?path= # delete file/dir
|
||||
POST /api/v1/workspaces/:id/files/mkdir?path= # create directory
|
||||
|
||||
POST /api/v1/workspaces/:id/archive/upload # upload + extract zip/tar.gz
|
||||
GET /api/v1/workspaces/:id/archive/download?format= # download as zip/tar.gz
|
||||
|
||||
POST /api/v1/workspaces/:id/reconcile # force FS → DB sync
|
||||
GET /api/v1/workspaces/:id/stats # disk usage, file count
|
||||
```
|
||||
|
||||
### Security
|
||||
|
||||
- Workspace access inherits from owner: if you can access the project/channel,
|
||||
you can access its workspace.
|
||||
- Path traversal guard: all paths are cleaned and must resolve within the
|
||||
workspace root. Symlinks are rejected.
|
||||
- File size limit: configurable per-workspace `max_bytes` with system default
|
||||
(`WORKSPACE_MAX_BYTES`, default 500MB).
|
||||
- Archive extraction bomb protection: max files (10,000), max total extracted
|
||||
size (workspace quota), max single file (100MB).
|
||||
|
||||
### Migrations
|
||||
|
||||
- `xxx_workspace_tables.sql` (Postgres + SQLite): `workspaces`, `workspace_files`
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] `models.Workspace`, `models.WorkspaceFile`, `models.WorkspacePatch` structs
|
||||
- [ ] `WorkspaceStore` interface in `store/interfaces.go`
|
||||
- [ ] Postgres implementation: `store/postgres/workspace.go`
|
||||
- [ ] SQLite implementation: `store/sqlite/workspace.go`
|
||||
- [ ] `WorkspaceFS` in new `server/workspace/` package
|
||||
- [ ] Path traversal validation (must not escape workspace root)
|
||||
- [ ] Archive extract (zip, tar.gz) with bomb protection
|
||||
- [ ] Archive create (zip, tar.gz)
|
||||
- [ ] MIME type detection on write (`net/http.DetectContentType` + extension fallback)
|
||||
- [ ] Workspace CRUD handlers (6 endpoints)
|
||||
- [ ] File CRUD handlers (5 endpoints)
|
||||
- [ ] Archive handlers (2 endpoints)
|
||||
- [ ] Reconcile + stats handlers (2 endpoints)
|
||||
- [ ] `Stores.Workspaces` wired in `store/postgres/stores.go` + `store/sqlite/stores.go`
|
||||
- [ ] Integration tests: workspace CRUD, file CRUD, archive round-trip, path traversal rejection
|
||||
- [ ] PVC directory creation on startup (`/data/storage/workspaces/`)
|
||||
|
||||
---
|
||||
|
||||
## v0.21.1 — Workspace Tools + Channel/Project Binding
|
||||
|
||||
Make workspaces useful in chat mode. AI can operate on files through tool calls.
|
||||
Channels and projects get workspace bindings.
|
||||
|
||||
### Tools (category: `workspace`)
|
||||
|
||||
**`workspace_ls`** — list files in workspace
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/",
|
||||
"recursive": false
|
||||
}
|
||||
```
|
||||
|
||||
Returns: array of `{ path, is_directory, content_type, size_bytes }`.
|
||||
|
||||
**`workspace_read`** — read a file
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.go"
|
||||
}
|
||||
```
|
||||
|
||||
Returns: file content as text (with truncation guard for large files, e.g. 50KB
|
||||
soft limit with "file truncated" indicator). Binary files return a base64
|
||||
summary or "binary file, N bytes" message.
|
||||
|
||||
**`workspace_write`** — create or overwrite a file
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.go",
|
||||
"content": "package main\n\nfunc main() {\n}\n"
|
||||
}
|
||||
```
|
||||
|
||||
Returns: confirmation with path and size. Creates parent directories
|
||||
automatically.
|
||||
|
||||
**`workspace_rm`** — delete a file or directory
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/old_module/",
|
||||
"recursive": false
|
||||
}
|
||||
```
|
||||
|
||||
Returns: confirmation. Recursive required for non-empty directories.
|
||||
|
||||
**`workspace_mv`** — rename or move a file
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "src/old.go",
|
||||
"destination": "src/new.go"
|
||||
}
|
||||
```
|
||||
|
||||
**`workspace_patch`** — apply a text diff/patch to a file
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "src/main.go",
|
||||
"operations": [
|
||||
{ "find": "oldFunction()", "replace": "newFunction()" },
|
||||
{ "find": "// TODO: remove", "replace": "" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The `find`/`replace` approach (same pattern as `str_replace` in many AI
|
||||
coding tools) is more reliable for LLMs than unified diffs. Each operation's
|
||||
`find` string must match exactly once in the file.
|
||||
|
||||
### Channel Workspace Binding
|
||||
|
||||
**Schema change:** `channels` table gains optional `workspace_id` FK.
|
||||
|
||||
**Behavior:**
|
||||
- When a workspace is bound to a channel, workspace tools are injected into
|
||||
the tool set for that channel's completions (same pattern as KB tools via
|
||||
persona binding).
|
||||
- New channel setting: "Workspace" toggle in channel settings.
|
||||
- Creating a workspace from channel settings auto-binds it.
|
||||
|
||||
**Archive upload flow (chat mode):**
|
||||
1. User uploads a zip/tar.gz to a channel with a workspace.
|
||||
2. Upload handler detects archive MIME type + workspace binding.
|
||||
3. Extracts into workspace (not attachment store).
|
||||
4. Workspace tools become available for AI to operate on files.
|
||||
5. User or AI can call archive download to get results.
|
||||
|
||||
Non-archive files still go to attachment store as before (backward compatible).
|
||||
|
||||
### Project Workspace Binding
|
||||
|
||||
**Schema change:** `projects` table gains optional `workspace_id` FK.
|
||||
|
||||
**Behavior:**
|
||||
- Project detail panel gets a "Files" tab showing workspace file tree.
|
||||
- All channels in a project inherit the project workspace (unless the channel
|
||||
has its own).
|
||||
- Workspace resolution: channel workspace > project workspace (same override
|
||||
pattern as persona/KB resolution).
|
||||
|
||||
### Frontend
|
||||
|
||||
- Channel settings: workspace toggle, create/bind workspace.
|
||||
- Project detail panel: Files tab with tree view (reusable component for
|
||||
editor surface later).
|
||||
- Chat bar: workspace indicator when active (similar to KB indicator).
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] `workspace_ls` tool implementation
|
||||
- [ ] `workspace_read` tool with text truncation guard + binary detection
|
||||
- [ ] `workspace_write` tool with auto-mkdir
|
||||
- [ ] `workspace_rm` tool with recursive guard
|
||||
- [ ] `workspace_mv` tool
|
||||
- [ ] `workspace_patch` tool with find/replace operations
|
||||
- [ ] Tool registration in `workspace` category
|
||||
- [ ] Tool injection in completion handler when workspace bound
|
||||
- [ ] `channels.workspace_id` column (migration, both dialects)
|
||||
- [ ] `projects.workspace_id` column (migration, both dialects)
|
||||
- [ ] Archive-to-workspace upload handler (detect archive + workspace → extract)
|
||||
- [ ] Workspace resolution: channel → project fallback
|
||||
- [ ] Channel settings UI: workspace toggle
|
||||
- [ ] Project detail panel: Files tab
|
||||
- [ ] Chat bar: workspace indicator
|
||||
- [ ] Integration tests: tool execution, workspace resolution, archive upload flow
|
||||
- [ ] Update `ExecutionContext` with workspace ID
|
||||
|
||||
---
|
||||
|
||||
## v0.21.2 — Workspace Indexing + Semantic Search
|
||||
|
||||
Embed text files in workspace for semantic search. Reuses the existing
|
||||
`knowledge/` chunker and embedder — they're already decoupled from KB-specific
|
||||
concerns.
|
||||
|
||||
### Data Model
|
||||
|
||||
**`workspace_chunks` table**
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| `id` | UUID | PK |
|
||||
| `workspace_id` | UUID | FK → workspaces |
|
||||
| `file_id` | UUID | FK → workspace_files |
|
||||
| `chunk_index` | INT | ordinal within file |
|
||||
| `content` | TEXT | chunk text |
|
||||
| `token_count` | INT | estimated |
|
||||
| `embedding` | vector(3072) / JSON | pgvector or JSON text (SQLite) |
|
||||
| `metadata` | JSONB / JSON | extensible: line_start, heading, etc. |
|
||||
|
||||
Index: pgvector IVFFlat on `embedding` (Postgres), app-level cosine (SQLite).
|
||||
Index: `(file_id)` — re-index on file change.
|
||||
|
||||
### Indexing Pipeline
|
||||
|
||||
```
|
||||
file write/upload
|
||||
→ is text file? (same textMIMETypes + code extensions)
|
||||
→ extract content (already in memory from write, or read from FS)
|
||||
→ chunk (reuse knowledge.SplitText with configurable ChunkConfig)
|
||||
→ embed (reuse knowledge.Embedder)
|
||||
→ store in workspace_chunks (DELETE old chunks for file_id, INSERT new)
|
||||
→ update workspace_files.sha256 (content-addressed skip on no-change)
|
||||
```
|
||||
|
||||
**Code-aware MIME types** (extend `textMIMETypes`):
|
||||
|
||||
The existing KB ingester recognizes `text/plain`, `text/markdown`, `text/csv`,
|
||||
`text/html`. For workspace indexing, we also recognize source code by extension:
|
||||
|
||||
```go
|
||||
var indexableExtensions = map[string]bool{
|
||||
".go": true, ".py": true, ".js": true, ".ts": true, ".jsx": true,
|
||||
".tsx": true, ".rs": true, ".c": true, ".cpp": true, ".h": true,
|
||||
".hpp": true, ".java": true, ".rb": true, ".php": true, ".swift": true,
|
||||
".kt": true, ".scala": true, ".sh": true, ".bash": true, ".zsh": true,
|
||||
".sql": true, ".yaml": true, ".yml": true, ".toml": true, ".json": true,
|
||||
".xml": true, ".css": true, ".scss": true, ".less": true,
|
||||
".md": true, ".txt": true, ".csv": true, ".html": true, ".htm": true,
|
||||
".dockerfile": true, ".tf": true, ".hcl": true, ".proto": true,
|
||||
".graphql": true, ".vue": true, ".svelte": true,
|
||||
".pl": true, ".pm": true, // Perl
|
||||
".lua": true, ".zig": true, ".nim": true, ".ex": true, ".exs": true,
|
||||
}
|
||||
```
|
||||
|
||||
**Content-addressed skip:** if `workspace_files.sha256` matches the new write,
|
||||
skip re-chunking and re-embedding. This makes bulk operations (archive extract)
|
||||
efficient — only changed files get re-indexed.
|
||||
|
||||
**Background indexing:** file writes trigger async indexing (same goroutine
|
||||
pattern as KB ingestion with semaphore). The write API returns immediately; the
|
||||
`workspace_files` row gets an `index_status` column: `pending`, `indexing`,
|
||||
`ready`, `error`, `skipped` (binary/non-text).
|
||||
|
||||
### Code-Aware Chunking
|
||||
|
||||
For source code, the default chunker works reasonably well but we add a
|
||||
code-specific separator hierarchy:
|
||||
|
||||
```go
|
||||
func CodeChunkConfig() ChunkConfig {
|
||||
return ChunkConfig{
|
||||
ChunkSize: 1500, // larger chunks for code (functions can be long)
|
||||
ChunkOverlap: 200,
|
||||
Separators: []string{"\n\nfunc ", "\n\nclass ", "\n\ndef ", "\n\n", "\n", " "},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is a simple heuristic — it splits on function/class boundaries when
|
||||
possible, falling back to paragraph and line boundaries. It doesn't require
|
||||
an AST parser and handles most languages well enough for search.
|
||||
|
||||
### Search Tool
|
||||
|
||||
**`workspace_search`** — semantic search across workspace files
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "database connection pooling",
|
||||
"top_k": 10,
|
||||
"file_pattern": "*.go"
|
||||
}
|
||||
```
|
||||
|
||||
Returns: array of `{ file_path, chunk_content, score, line_hint }`.
|
||||
|
||||
The `file_pattern` is optional glob filtering (applied post-search on the
|
||||
`workspace_files.path` join). `line_hint` is approximate line number from
|
||||
chunk metadata.
|
||||
|
||||
### Workspace Store Extensions
|
||||
|
||||
```go
|
||||
// Added to WorkspaceStore interface
|
||||
InsertChunks(ctx context.Context, chunks []models.WorkspaceChunk) error
|
||||
DeleteChunksByFile(ctx context.Context, fileID string) error
|
||||
SimilaritySearch(ctx context.Context, workspaceID string, embedding []float64, topK int) ([]models.WorkspaceChunkResult, error)
|
||||
UpdateFileIndexStatus(ctx context.Context, fileID, status string) error
|
||||
```
|
||||
|
||||
### `workspace_files` Schema Addition
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| `index_status` | TEXT | `pending`, `indexing`, `ready`, `error`, `skipped` |
|
||||
| `chunk_count` | INT | number of chunks after indexing |
|
||||
|
||||
### Indexing Configuration
|
||||
|
||||
- **Per-workspace toggle:** `workspaces.indexing_enabled` (default: `true`
|
||||
when embedding role is configured, `false` otherwise).
|
||||
- **System setting:** `WORKSPACE_INDEXING_ENABLED` env var (global kill switch).
|
||||
- **Concurrency:** shared semaphore with KB ingestion (don't overwhelm the
|
||||
embedding provider).
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] `workspace_chunks` table (Postgres + SQLite migrations)
|
||||
- [ ] `workspace_files.index_status` and `chunk_count` columns
|
||||
- [ ] `WorkspaceChunk`, `WorkspaceChunkResult` model structs
|
||||
- [ ] Store methods: `InsertChunks`, `DeleteChunksByFile`, `SimilaritySearch`, `UpdateFileIndexStatus`
|
||||
- [ ] Postgres implementation with pgvector
|
||||
- [ ] SQLite implementation with app-level cosine
|
||||
- [ ] `workspace.Indexer` — reuses `knowledge.SplitText` + `knowledge.Embedder`
|
||||
- [ ] Indexable type detection: MIME type + extension map
|
||||
- [ ] Code-aware chunk config
|
||||
- [ ] Content-addressed skip (sha256 check)
|
||||
- [ ] Background indexing goroutine with semaphore
|
||||
- [ ] `workspace_search` tool
|
||||
- [ ] `workspace_search` glob filtering on file path
|
||||
- [ ] Hook indexer into `WorkspaceFS.WriteFile` and `ExtractArchive`
|
||||
- [ ] Workspace index status endpoint: `GET /api/v1/workspaces/:id/index-status`
|
||||
- [ ] Integration tests: index pipeline, semantic search, content-addressed skip
|
||||
- [ ] Notification on index complete/error (reuse notification service)
|
||||
|
||||
---
|
||||
|
||||
## v0.21.3 — Surface Infrastructure + REPL
|
||||
|
||||
Pure UI architecture. No workspace dependency. Can develop in parallel with
|
||||
v0.21.0–v0.21.2 on the frontend side.
|
||||
|
||||
### Surface Registration API
|
||||
|
||||
Extends the existing `ctx.*` extension API from v0.11.0.
|
||||
|
||||
```js
|
||||
Extensions.register({
|
||||
id: 'my-mode',
|
||||
init(ctx) {
|
||||
ctx.surfaces.register('my-surface', {
|
||||
label: 'My Mode',
|
||||
icon: 'code', // lucide icon name
|
||||
regions: ['surface-main', 'sidebar-content'],
|
||||
activate() { /* take over regions */ },
|
||||
deactivate() { /* restore regions */ }
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Region Management
|
||||
|
||||
```js
|
||||
ctx.ui.replace(regionId, element) // saves current content, swaps in element
|
||||
ctx.ui.restore(regionId) // restores saved content
|
||||
```
|
||||
|
||||
Regions are DOM containers identified by `data-surface-region` attributes.
|
||||
`replace()` detaches the current children (preserved in memory, not destroyed),
|
||||
inserts the new element. `restore()` re-attaches the saved children.
|
||||
|
||||
This is critical for CM6 — editor instances preserve state across mode switches
|
||||
because the DOM nodes aren't destroyed, just detached.
|
||||
|
||||
### Surface Regions
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ [surface-header] │
|
||||
├──────────────┬───────────────────────────────────┤
|
||||
│ │ │
|
||||
│ [sidebar- │ [surface-main] │
|
||||
│ content] │ (chat messages / editor / │
|
||||
│ │ article / custom) │
|
||||
│ │ │
|
||||
│ ├───────────────────────────────────┤
|
||||
│ │ [surface-footer] │
|
||||
│ │ (chat input / editor toolbar) │
|
||||
└──────────────┴───────────────────────────────────┘
|
||||
```
|
||||
|
||||
The sidebar-nav region (mode selector) is managed by the surface system itself,
|
||||
not by individual extensions.
|
||||
|
||||
### Mode Selector
|
||||
|
||||
Appears in the sidebar below the brand logo, above chat history, when ≥1
|
||||
extension surface is registered. Shows icon buttons for each mode. Chat is
|
||||
always the first (default) mode.
|
||||
|
||||
```
|
||||
[💬] [</>] [📄] ← mode selector (chat, editor, article)
|
||||
──────────────
|
||||
Chat History... ← sidebar-content (replaced per mode)
|
||||
```
|
||||
|
||||
### Events
|
||||
|
||||
```js
|
||||
Events.on('surface.activated', ({ surface, previous }) => { ... });
|
||||
Events.on('surface.deactivated', ({ surface }) => { ... });
|
||||
```
|
||||
|
||||
### REPL / Debug Console (#70)
|
||||
|
||||
Fourth tab in debug modal (Ctrl+Shift+L). See roadmap for full spec:
|
||||
|
||||
- `AsyncFunction` wrapper for top-level `await`
|
||||
- Injected globals: `API`, `Events`, `Extensions`, `DebugLog`, `Surfaces`
|
||||
- Pretty-print results (collapsible JSON, red errors with stack)
|
||||
- Command history: ↑/↓ with `sessionStorage`
|
||||
- Tab-completion on live object graphs
|
||||
- Event label hints on `Events.publish('`/`Events.on('`
|
||||
- Multi-line: Shift+Enter for newline, Enter to run
|
||||
- Admin-gated OR `?debug=1` URL param
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] `data-surface-region` attributes on index.html containers
|
||||
- [ ] `surfaces.js` — SurfaceRegistry: register, activate, deactivate, getCurrent
|
||||
- [ ] `ctx.ui.replace()` / `ctx.ui.restore()` with DOM preservation
|
||||
- [ ] `ctx.surfaces.register()` API for extensions
|
||||
- [ ] Mode selector component in sidebar
|
||||
- [ ] Chat as default surface (implicit, always registered)
|
||||
- [ ] `surface.activated` / `surface.deactivated` EventBus events
|
||||
- [ ] REPL tab: AsyncFunction wrapper, global injection
|
||||
- [ ] REPL tab: pretty-print results
|
||||
- [ ] REPL tab: command history (sessionStorage)
|
||||
- [ ] REPL tab: tab-completion on object graphs
|
||||
- [ ] REPL tab: event label hints
|
||||
- [ ] REPL tab: admin gate
|
||||
- [ ] REPL tab: toolbar (clear, copy, help)
|
||||
- [ ] Mobile: mode selector collapses to hamburger/bottom nav
|
||||
- [ ] Integration with extension loader (surfaces from manifest)
|
||||
- [ ] Documentation in EXTENSIONS.md §6 update
|
||||
|
||||
---
|
||||
|
||||
## v0.21.4 — Git Integration
|
||||
|
||||
Layer git operations onto workspace. A workspace can optionally track a git
|
||||
remote. Credentials go through the vault.
|
||||
|
||||
### Schema Changes
|
||||
|
||||
**`workspaces` table additions:**
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| `git_remote_url` | TEXT | nullable — HTTPS or SSH URL |
|
||||
| `git_branch` | TEXT | nullable — default branch after clone |
|
||||
| `git_credential_id` | UUID | nullable — FK to git_credentials |
|
||||
| `git_last_sync` | TIMESTAMPTZ | nullable — last pull/push |
|
||||
|
||||
**`git_credentials` table:**
|
||||
|
||||
| Column | Type | Notes |
|
||||
|--------|------|-------|
|
||||
| `id` | UUID | PK |
|
||||
| `user_id` | UUID | FK → users (owner) |
|
||||
| `name` | TEXT | display name: "GitHub PAT", "GitLab token" |
|
||||
| `auth_type` | TEXT | `https_pat`, `https_basic`, `ssh_key` |
|
||||
| `encrypted_data` | BYTEA | AES-256-GCM (same vault pattern as BYOK) |
|
||||
| `created_at` | TIMESTAMPTZ | |
|
||||
|
||||
Encrypted data contains: `{ "token": "..." }` for PAT, `{ "username": "...",
|
||||
"password": "..." }` for basic, `{ "private_key": "...", "passphrase": "..." }`
|
||||
for SSH.
|
||||
|
||||
### Git Operations (server-side)
|
||||
|
||||
Uses `os/exec` calling `git` binary (not a Go git library — keeps binary size
|
||||
down and avoids CGO). The git binary is already in the Docker image for other
|
||||
purposes.
|
||||
|
||||
```go
|
||||
type GitOps struct {
|
||||
fs *WorkspaceFS
|
||||
credentials CredentialResolver // vault decryption
|
||||
}
|
||||
|
||||
func (g *GitOps) Clone(ctx context.Context, w *models.Workspace, url, branch string, credID string) error
|
||||
func (g *GitOps) Pull(ctx context.Context, w *models.Workspace) error
|
||||
func (g *GitOps) Push(ctx context.Context, w *models.Workspace, message string) error
|
||||
func (g *GitOps) Status(ctx context.Context, w *models.Workspace) (*GitStatus, error)
|
||||
func (g *GitOps) Diff(ctx context.Context, w *models.Workspace, path string) (string, error)
|
||||
func (g *GitOps) Commit(ctx context.Context, w *models.Workspace, message string, paths []string) error
|
||||
func (g *GitOps) Log(ctx context.Context, w *models.Workspace, n int) ([]GitLogEntry, error)
|
||||
func (g *GitOps) BranchList(ctx context.Context, w *models.Workspace) ([]string, string, error)
|
||||
func (g *GitOps) Checkout(ctx context.Context, w *models.Workspace, branch string) error
|
||||
```
|
||||
|
||||
Credential injection: temporary `.git-credentials` file or `GIT_ASKPASS` script
|
||||
created for the duration of the operation, then securely wiped. SSH keys use
|
||||
`GIT_SSH_COMMAND` with a temp key file.
|
||||
|
||||
### Git Tools (category: `workspace`)
|
||||
|
||||
**`git_status`** — show working tree status
|
||||
**`git_diff`** — show diff for file or all changes
|
||||
**`git_commit`** — stage and commit files
|
||||
**`git_log`** — recent commit history
|
||||
**`git_branch`** — list/switch branches
|
||||
|
||||
These are only injected when the workspace has `git_remote_url` set.
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```
|
||||
POST /api/v1/workspaces/:id/git/clone # { url, branch, credential_id }
|
||||
POST /api/v1/workspaces/:id/git/pull
|
||||
POST /api/v1/workspaces/:id/git/push
|
||||
GET /api/v1/workspaces/:id/git/status
|
||||
GET /api/v1/workspaces/:id/git/diff?path=
|
||||
POST /api/v1/workspaces/:id/git/commit # { message, paths }
|
||||
GET /api/v1/workspaces/:id/git/log?n=
|
||||
GET /api/v1/workspaces/:id/git/branches
|
||||
POST /api/v1/workspaces/:id/git/checkout # { branch }
|
||||
|
||||
# Credential management
|
||||
POST /api/v1/git-credentials # create
|
||||
GET /api/v1/git-credentials # list (user-scoped)
|
||||
DELETE /api/v1/git-credentials/:id # delete
|
||||
```
|
||||
|
||||
### Post-Operation Hooks
|
||||
|
||||
After `clone`, `pull`, `checkout`: trigger workspace reconcile (sync FS → DB
|
||||
index) and re-index changed files (v0.21.2). This ensures the file tree and
|
||||
search index stay current after git operations.
|
||||
|
||||
### Frontend
|
||||
|
||||
- Workspace settings: git remote URL, credential picker, clone button.
|
||||
- Git credential management in user Settings.
|
||||
- Future (editor surface): git status indicators in file tree, commit UI.
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] `git_credentials` table (Postgres + SQLite migrations)
|
||||
- [ ] `workspaces` git columns (migration)
|
||||
- [ ] `GitCredentialStore` interface + both implementations
|
||||
- [ ] Vault integration for credential encryption/decryption
|
||||
- [ ] `workspace.GitOps` with exec-based git operations
|
||||
- [ ] Credential injection: temp `.git-credentials` / `GIT_SSH_COMMAND`
|
||||
- [ ] Clone with depth option (shallow clone for large repos)
|
||||
- [ ] Pull, push, status, diff, commit, log, branch, checkout
|
||||
- [ ] Post-operation reconcile + re-index hook
|
||||
- [ ] Git tool implementations (5 tools)
|
||||
- [ ] Git API endpoints (9 endpoints)
|
||||
- [ ] Credential CRUD endpoints (3 endpoints)
|
||||
- [ ] Workspace settings UI: git config section
|
||||
- [ ] User Settings: git credentials management
|
||||
- [ ] Integration tests: clone, commit, push/pull cycle
|
||||
- [ ] `.gitignore` respect in workspace indexing (skip ignored files)
|
||||
- [ ] Security: reject `file://` and local path URLs in clone
|
||||
|
||||
---
|
||||
|
||||
## v0.21.5 — Editor Surface (Development Mode)
|
||||
|
||||
The IDE-like experience. Built entirely as a browser-tier extension consuming
|
||||
workspace primitives from v0.21.0–v0.21.4 and surface infrastructure from
|
||||
v0.21.3.
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ [surface-header] workspace name | branch | status │
|
||||
├──────────────┬───────────────────┬───────────────────┤
|
||||
│ File Tree │ Code Editor │ AI Chat Panel │
|
||||
│ (sidebar) │ (CM6, main) │ (resizable) │
|
||||
│ │ │ │
|
||||
│ 📁 src/ │ 1│ package main │ You: refactor │
|
||||
│ 📄 main.go│ 2│ │ the handler... │
|
||||
│ 📄 util.go│ 3│ func main() { │ │
|
||||
│ 📁 tests/ │ 4│ ... │ AI: I'll update │
|
||||
│ 📄 go.mod │ 5│ } │ main.go... │
|
||||
│ │ │ │
|
||||
├──────────────┴───────────────────┴───────────────────┤
|
||||
│ [surface-footer] file: src/main.go | Ln 4, Col 12 │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
**File Tree** (sidebar-content region)
|
||||
- Tree view backed by `workspace_ls` API (or cached from `Tree()`)
|
||||
- File icons by extension/MIME type
|
||||
- Click to open in editor
|
||||
- Right-click context menu: rename, delete, new file, new folder
|
||||
- Git status indicators (if git-enabled): modified, staged, untracked
|
||||
- Drag-drop file reorder (within folders)
|
||||
|
||||
**Code Editor** (surface-main region)
|
||||
- CM6 `codeEditor()` factory (already exists from v0.17.2)
|
||||
- Language auto-detection from file extension
|
||||
- Tab bar for multiple open files
|
||||
- Modified indicator (dot on tab)
|
||||
- Save: Ctrl/Cmd+S → `workspace_write` API
|
||||
- Auto-save on tab switch / mode switch (configurable)
|
||||
|
||||
**AI Chat Panel** (split pane, resizable)
|
||||
- Reuses the existing chat rendering pipeline
|
||||
- Same channel context — conversation history carries over between modes
|
||||
- Workspace tools auto-injected
|
||||
- Tool call results update the editor live (if the modified file is open)
|
||||
|
||||
**Status Bar** (surface-footer region)
|
||||
- Current file path
|
||||
- Cursor position (line, column)
|
||||
- Language mode
|
||||
- Encoding
|
||||
- Git branch (if applicable)
|
||||
|
||||
### Extension Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "editor-mode",
|
||||
"name": "Development",
|
||||
"version": "1.0.0",
|
||||
"type": "browser",
|
||||
"surfaces": [{
|
||||
"id": "editor",
|
||||
"label": "Editor",
|
||||
"icon": "code-2",
|
||||
"regions": ["surface-main", "surface-footer", "sidebar-content", "surface-header"]
|
||||
}],
|
||||
"permissions": ["workspace"]
|
||||
}
|
||||
```
|
||||
|
||||
### Live Update on Tool Calls
|
||||
|
||||
When the AI calls `workspace_write` or `workspace_patch` and the target file
|
||||
is open in the editor, the editor content updates live. Implementation:
|
||||
|
||||
1. Tool call completes → workspace write handler fires EventBus event
|
||||
`workspace.file.changed` with `{ workspaceId, path }`.
|
||||
2. Editor surface subscribes to this event.
|
||||
3. On match (file is open), fetch fresh content from API and update CM6
|
||||
state via `view.dispatch({ changes })`.
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] `editor-mode` extension directory structure
|
||||
- [ ] File tree component (tree view, icons, context menu)
|
||||
- [ ] Tab bar component (open files, modified indicator)
|
||||
- [ ] Split pane layout (editor + chat, resizable divider)
|
||||
- [ ] CM6 editor integration with language detection
|
||||
- [ ] Save flow: Ctrl/Cmd+S → API → DB index update
|
||||
- [ ] Auto-save on tab/mode switch
|
||||
- [ ] Live update on `workspace.file.changed` event
|
||||
- [ ] Status bar: file, cursor, language, branch
|
||||
- [ ] Surface registration via manifest
|
||||
- [ ] Git status indicators in file tree (if v0.21.4 landed)
|
||||
- [ ] Mobile: single-pane mode (editor or chat, toggle)
|
||||
- [ ] Keyboard shortcuts: Ctrl+P (quick open), Ctrl+Shift+F (workspace search)
|
||||
- [ ] Quick open: fuzzy file finder using `workspace_files` index
|
||||
|
||||
---
|
||||
|
||||
## v0.21.6 — Article Surface + Document Output Pipeline
|
||||
|
||||
Writing-focused surface. The conversation is secondary — the document is the
|
||||
artifact.
|
||||
|
||||
### Document Output Pipeline
|
||||
|
||||
Before article mode, we need a way for extensions to produce downloadable
|
||||
output. This is the pipeline:
|
||||
|
||||
```
|
||||
extension generates content
|
||||
→ POST /api/v1/workspaces/:id/files/write (save to workspace)
|
||||
→ or POST /api/v1/workspaces/:id/export (convert + save)
|
||||
→ user downloads from workspace or gets direct download link
|
||||
```
|
||||
|
||||
Export endpoint supports format conversion (markdown → HTML, markdown → PDF via
|
||||
pandoc if available, markdown → DOCX). This is a stretch goal — initial version
|
||||
just saves to workspace and lets users download the raw file.
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ [surface-header] Document Title [Export ▾] │
|
||||
├──────────────┬───────────────────────────────────────┤
|
||||
│ Outline │ Rich Text Editor (CM6 markdown) │
|
||||
│ │ │
|
||||
│ § Intro │ # My Article │
|
||||
│ § Methods │ │
|
||||
│ § Data │ Compelling introduction paragraph │
|
||||
│ § Analysis│ about the topic at hand... │
|
||||
│ § Results │ │
|
||||
│ § Discussion│ ## Methods │
|
||||
│ │ │
|
||||
│──────────────│ ### Data Collection │
|
||||
│ AI Assistant │ │
|
||||
│ │ We gathered data from... │
|
||||
│ "Expand the │ │
|
||||
│ methods │ │
|
||||
│ section..." │ │
|
||||
├──────────────┴───────────────────────────────────────┤
|
||||
│ [surface-footer] Words: 1,234 | Reading: ~5 min │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Components
|
||||
|
||||
**Outline** (sidebar-content, top section)
|
||||
- Auto-generated from heading structure in document
|
||||
- Click to scroll to section
|
||||
- Drag to reorder sections
|
||||
|
||||
**AI Assistant** (sidebar-content, bottom section)
|
||||
- Lightweight chat interface for document-focused prompts
|
||||
- Tools: `workspace_read`, `workspace_write`, `workspace_search`
|
||||
- Additional article tools:
|
||||
- `suggest_outline` — propose structure for a topic
|
||||
- `expand_section` — flesh out a heading with content
|
||||
- `check_citations` — verify URLs are reachable (via url_fetch)
|
||||
|
||||
**Rich Text Editor** (surface-main)
|
||||
- CM6 `noteEditor()` factory (from v0.17.3) with enhanced live preview
|
||||
- Heading decorations, blockquotes, code blocks, links
|
||||
- Focus mode: dim everything except current section
|
||||
|
||||
**Export** (surface-header dropdown)
|
||||
- Download as Markdown (.md)
|
||||
- Download as HTML (rendered)
|
||||
- Download as PDF (if pandoc available)
|
||||
- Copy to clipboard (markdown)
|
||||
|
||||
### Checklist
|
||||
|
||||
- [ ] `article-mode` extension directory structure
|
||||
- [ ] Outline component (auto-generated from headings, click-to-scroll)
|
||||
- [ ] Sidebar split: outline (top) + AI assistant (bottom)
|
||||
- [ ] Rich text editor with enhanced markdown live preview
|
||||
- [ ] Export dropdown: markdown, HTML, PDF
|
||||
- [ ] Article-specific tools: `suggest_outline`, `expand_section`
|
||||
- [ ] Focus mode (dim non-active sections)
|
||||
- [ ] Word count + reading time in status bar
|
||||
- [ ] Surface registration via manifest
|
||||
- [ ] Auto-save document to workspace
|
||||
- [ ] Mobile: outline collapses to top dropdown
|
||||
|
||||
---
|
||||
|
||||
## Cross-Cutting Concerns
|
||||
|
||||
### Migration Strategy
|
||||
|
||||
Each sub-release gets its own migration file(s), both Postgres and SQLite.
|
||||
Migrations run on backend startup (existing pattern). Numbering continues
|
||||
from v0.20.0's last migration.
|
||||
|
||||
### Test Strategy
|
||||
|
||||
- Backend integration tests against both Postgres and SQLite for every store
|
||||
method and handler (existing CI matrix pattern).
|
||||
- Workspace FS tests: use a temp directory, not the real PVC.
|
||||
- Tool execution tests: mock workspace with pre-populated files.
|
||||
- Surface tests: manual testing + REPL verification (surface infrastructure
|
||||
is frontend-only, no backend tests).
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
- Channels without workspaces work exactly as before.
|
||||
- Projects without workspaces work exactly as before.
|
||||
- Archive uploads to channels without workspaces go to attachment store.
|
||||
- Workspace tools only appear when a workspace is bound.
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
Each sub-release updates:
|
||||
- `VERSION` → `0.21.N`
|
||||
- `CHANGELOG.md` — detailed entry
|
||||
- `ARCHITECTURE.md` — workspace section, surface system section
|
||||
- `EXTENSIONS.md` — §6 update for surface implementation
|
||||
- `ROADMAP.md` — mark completed items
|
||||
|
||||
### Deployment
|
||||
|
||||
- PVC: ensure `workspaces/` directory is created at startup
|
||||
(same pattern as `attachments/` directory creation).
|
||||
- Git binary: verify `git` is in the Docker image (add to Dockerfile
|
||||
if not present).
|
||||
- Embedding role: workspace indexing gracefully degrades when no embedding
|
||||
model is configured (files still work, search doesn't).
|
||||
- Quota defaults: `WORKSPACE_MAX_BYTES=524288000` (500MB),
|
||||
`WORKSPACE_MAX_FILES=10000`.
|
||||
127
docs/ROADMAP.md
127
docs/ROADMAP.md
@@ -78,7 +78,19 @@ v0.19.2 Project Persona Default + Archive + Reorder ✅
|
||||
│
|
||||
v0.20.0 Notifications + @mention Routing + Multi-model ✅
|
||||
│
|
||||
v0.21.0 Extension Surfaces + Modes (depends on CM6 from v0.17.2)
|
||||
v0.21.0 Workspace Storage Primitive ✅
|
||||
│
|
||||
┌───────┴──────────────┐
|
||||
│ │
|
||||
v0.21.1 Workspace v0.21.3 Surface Infra
|
||||
Tools + Bindings + REPL (parallel)
|
||||
│ │
|
||||
v0.21.2 Workspace v0.21.5 Editor Surface
|
||||
Indexing + Search (Development Mode)
|
||||
│ │
|
||||
v0.21.4 Git v0.21.6 Article Surface
|
||||
Integration + Document Output
|
||||
└───────┬──────────────┘
|
||||
│
|
||||
v0.22.0 Smart Routing + Provider Extensions
|
||||
│
|
||||
@@ -300,7 +312,7 @@ step runs in Docker (esbuild → single IIFE bundle). No change to dev
|
||||
experience for non-editor code — the rest of `src/js/` stays vanilla.
|
||||
|
||||
Depends on: nothing (frontend-only). Prerequisite for: extension surfaces
|
||||
(v0.21.0 editor mode). See [DESIGN-CM6.md](DESIGN-CM6.md) for full spec.
|
||||
(v0.21.5 editor surface). See [DESIGN-CM6.md](DESIGN-CM6.md) for full spec.
|
||||
|
||||
**Build Pipeline**
|
||||
- [x] `src/editor/` directory: `package.json`, `build.mjs`, `index.mjs`, language/theme modules
|
||||
@@ -654,35 +666,96 @@ Depends on: v0.19.2 (Projects complete), EventBus + WebSocket hub (v0.9.x),
|
||||
|
||||
---
|
||||
|
||||
## v0.21.0 — Extension Surfaces + Modes
|
||||
## v0.21.x — Workspace Platform + Extension Surfaces
|
||||
|
||||
Depends on: extension foundation (v0.11.0), CodeMirror 6 (v0.17.2).
|
||||
See [EXTENSIONS.md §6](EXTENSIONS.md#6-surfaces-modes).
|
||||
Seven-release series decomposing workspace storage, tools, indexing, git,
|
||||
surface infrastructure, and editor/article modes. Full specification in
|
||||
[DESIGN-0.21.0.md](DESIGN-0.21.0.md).
|
||||
|
||||
_(Shifted from v0.18.0 — no content changes)_
|
||||
Depends on: file storage (v0.12.0), extension foundation (v0.11.0),
|
||||
CodeMirror 6 (v0.17.2), knowledge base embedding pipeline (v0.14.0).
|
||||
|
||||
- [ ] Surface registration and activation API
|
||||
- [ ] Mode selector in sidebar (below brand, above chat history)
|
||||
- [ ] `ctx.ui.replace()` / `ctx.ui.restore()` for region management
|
||||
### v0.21.0 — Workspace Storage Primitive ✅
|
||||
|
||||
Pure backend foundation. Workspaces as a polymorphic platform primitive
|
||||
owned by users, projects, channels, or teams. Dual-layer storage: PVC
|
||||
filesystem (source of truth) + DB metadata index (queryable cache).
|
||||
|
||||
- [x] `workspaces` table: polymorphic owner (user/project/channel/team), root_path, max_bytes quota, status
|
||||
- [x] `workspace_files` table: metadata index (path, MIME type, size, sha256, is_directory)
|
||||
- [x] `WorkspaceStore` interface: CRUD, file index (upsert/delete/list/prefix), ownership lookup, stats
|
||||
- [x] Postgres + SQLite store implementations with upsert-on-conflict for file index
|
||||
- [x] `workspace.FS` package: read, write (atomic via temp+rename), delete, mkdir, stat, list, reconcile (FS→DB sync)
|
||||
- [x] `workspace.Archive`: zip/tar.gz extract + create with archive bomb protection (10K file limit, 100MB single file, quota enforcement), common-prefix stripping
|
||||
- [x] Content type detection: extension-based (40+ source code types) with http.DetectContentType fallback
|
||||
- [x] SHA256 computed during write via tee reader (enables content-addressed skip in v0.21.2)
|
||||
- [x] Path traversal guards: cleanPath + absPath validation, symlink rejection
|
||||
- [x] 15 API endpoints: workspace CRUD, file CRUD, archive upload/download, reconcile, stats
|
||||
- [x] Owner-based authorization: user=self, channel=owner, project=member, team=member
|
||||
- [x] Unit tests: path cleaning, traversal detection, MIME detection, unsafe path filtering, write/read round-trip, delete, mkdir
|
||||
|
||||
### v0.21.1 — Workspace Tools + Channel/Project Binding
|
||||
|
||||
Make workspaces useful in chat mode via tool calls.
|
||||
|
||||
- [ ] Workspace tools (category: workspace): `workspace_ls`, `workspace_read` (50KB soft limit), `workspace_write` (auto-mkdir), `workspace_rm` (recursive guard), `workspace_mv`, `workspace_patch` (find/replace)
|
||||
- [ ] `channels.workspace_id` FK, `projects.workspace_id` FK
|
||||
- [ ] Workspace resolution: channel workspace → project workspace (override pattern)
|
||||
- [ ] Archive upload flow: detect archive MIME + workspace binding → extract to workspace
|
||||
- [ ] Frontend: channel settings workspace toggle, project Files tab with tree view, chat bar workspace indicator
|
||||
|
||||
### v0.21.2 — Workspace Indexing + Semantic Search
|
||||
|
||||
Embed text files for semantic search. Reuses `knowledge.SplitText` + `knowledge.Embedder`.
|
||||
|
||||
- [ ] `workspace_chunks` table: workspace_id, file_id, chunk_index, content, embedding, metadata
|
||||
- [ ] `workspace_files` additions: index_status, chunk_count
|
||||
- [ ] Indexable types: text MIME types + 30+ code extensions
|
||||
- [ ] Code-aware chunking: larger chunks (1500 chars), function/class boundary separators
|
||||
- [ ] Content-addressed skip: sha256 check before re-chunking/re-embedding
|
||||
- [ ] Background indexing: async goroutine with shared semaphore
|
||||
- [ ] `workspace_search` tool: semantic search with optional glob filtering
|
||||
|
||||
### v0.21.3 — Surface Infrastructure + REPL
|
||||
|
||||
Pure UI architecture. No workspace dependency (parallel development).
|
||||
|
||||
- [ ] Surface registration: `ctx.surfaces.register()` with label, icon, regions, activate/deactivate
|
||||
- [ ] Region management: `ctx.ui.replace()` / `ctx.ui.restore()` for CM6 state preservation
|
||||
- [ ] Mode selector in sidebar when ≥1 extension surface registered
|
||||
- [ ] `surface.activated` / `surface.deactivated` events
|
||||
- [ ] Editor mode (extension: file tree + CM6 code editor + AI chat split pane)
|
||||
- [ ] Article mode (extension: outline + rich text + AI assistant panel)
|
||||
- [ ] Document generation output storage: extension → attachment → download pipeline _(prerequisite for editor/article output)_
|
||||
- [ ] REPL console ([#70](https://git.gobha.me/xcaliber/chat-switchboard/issues/70)): fourth debug modal tab, AsyncFunction wrapper, injected globals, command history, tab-completion, admin-gated
|
||||
|
||||
**REPL / Debug Console** ([#70](https://git.gobha.me/xcaliber/chat-switchboard/issues/70))
|
||||
- [ ] Fourth tab in debug modal (Ctrl+Shift+L): `[ Console | Network | State | REPL ⚠ ]`
|
||||
- [ ] `AsyncFunction` wrapper for top-level `await` — injects `API`, `Events`, `Extensions`, `DebugLog` as globals
|
||||
- [ ] Pretty-print results: collapsible JSON (reuse State tab renderer), errors in red with stack
|
||||
- [ ] Command history: ↑/↓ navigation, `sessionStorage` (not `localStorage` — no stale credentials across sessions)
|
||||
- [ ] Tab-completion on live object graphs: walk `Object.getOwnPropertyNames` + prototype chain, own-first sort
|
||||
- [ ] Event label hints: secondary completion when typing `Events.publish('` or `Events.on('` — sourced from routeTable constants
|
||||
- [ ] Every executed command echoed as `REPL:EXEC` entry in Console tab (trace of what ran)
|
||||
- [ ] Toolbar: Clear (output only), Copy session (full transcript), Help (available globals guide)
|
||||
- [ ] Multi-line input: Shift+Enter for newline, Enter to run
|
||||
- [ ] Access gate: admin-role only (same `isAdmin` check as admin panel) OR `?debug=1` URL param
|
||||
- [ ] _Nice-to-have_: snippets library dropdown ("List channels", "Show current user", "Ping WebSocket", "List loaded extensions")
|
||||
- [ ] _Nice-to-have_: method signature tooltip from `fn.toString()` parsing on autocomplete selection
|
||||
- [ ] Files: `index.html` (tab markup), `debug.js` (ReplRunner object), `debug.css` (output, input, suggestion dropdown)
|
||||
### v0.21.4 — Git Integration
|
||||
|
||||
Layer git operations onto workspaces.
|
||||
|
||||
- [ ] `workspaces` additions: git_remote_url, git_branch, git_credential_id, git_last_sync
|
||||
- [ ] `git_credentials` table: auth_type (https_pat/https_basic/ssh_key), encrypted_data (AES-256-GCM)
|
||||
- [ ] Git operations via exec: clone, pull, push, status, diff, commit, log, branch, checkout
|
||||
- [ ] Workspace tools (git-aware): `git_status`, `git_diff`, `git_commit`, `git_log`, `git_branch`
|
||||
- [ ] Post-operation hooks: clone/pull/checkout trigger reconcile + re-index changed files
|
||||
|
||||
### v0.21.5 — Editor Surface (Development Mode)
|
||||
|
||||
IDE-like experience. Browser-tier extension consuming workspace primitives.
|
||||
|
||||
- [ ] Layout: file tree (sidebar), code editor (CM6, main), AI chat panel (resizable split), status bar
|
||||
- [ ] File tree: workspace_ls backed, git status indicators, context menu, drag-drop
|
||||
- [ ] Code editor: CM6 codeEditor() factory, language auto-detection, tab bar, Ctrl+S save
|
||||
- [ ] AI chat panel: same channel context, workspace tools auto-injected, live update via EventBus
|
||||
- [ ] Keyboard shortcuts: Ctrl+P quick open, Ctrl+Shift+F workspace search
|
||||
|
||||
### v0.21.6 — Article Surface + Document Output Pipeline
|
||||
|
||||
Writing-focused surface. Document is artifact, conversation is secondary.
|
||||
|
||||
- [ ] Document output pipeline: write → workspace → export (markdown → HTML/PDF/DOCX via pandoc)
|
||||
- [ ] Layout: outline (sidebar top), AI assistant (sidebar bottom), rich text editor (CM6 markdown, main)
|
||||
- [ ] Outline: auto-generated from headings, click-to-scroll, drag to reorder
|
||||
- [ ] AI assistant: lightweight chat with article-specific tools (suggest_outline, expand_section, check_citations)
|
||||
- [ ] Rich text editor: CM6 noteEditor() with enhanced live preview, focus mode
|
||||
- [ ] Export: download as markdown/HTML/PDF, copy to clipboard
|
||||
|
||||
---
|
||||
|
||||
@@ -721,7 +794,7 @@ The channel foundation for workflows and real-time collaboration. Today
|
||||
channels are single-user direct chats. This release makes channels a
|
||||
shared space that multiple actors can inhabit.
|
||||
|
||||
Depends on: extension surfaces (v0.21.0), WebSocket infrastructure (already exists).
|
||||
Depends on: extension surfaces (v0.21.3), WebSocket infrastructure (already exists).
|
||||
|
||||
_(Shifted from v0.20.0 — no content changes)_
|
||||
|
||||
|
||||
Reference in New Issue
Block a user