feat: workspace backend foundation (PR-1)
- Add workspaces table migration (2026_06_01_add_workspaces) - Create Workspace model with repo_id, user_id, branch, path, status - Add workspace_id nullable FK to ToolInstance - Create GitService for clone/fetch/pull/branch_exists_remotely - Create WorkspaceManager for create/delete/sync lifecycle - Create workspace CRUD API with 409 handling for duplicates and instances - Wire workspace routes into FastAPI app - 17 tests passing (8 unit + 9 integration), 1 skipped Quality gates: ruff clean
This commit is contained in:
@@ -0,0 +1,504 @@
|
||||
# Design: Workspace-Based Tool Instances
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Phase | **Design** |
|
||||
| Based on | [Spec](spec.md) |
|
||||
| Next | Tasks |
|
||||
|
||||
## Decision: No Migration
|
||||
|
||||
Existing tool instances will be left as-is. Users will create new workspaces and new tool instances. Old instances remain functional but read-only (no migration path). This simplifies the implementation significantly.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Frontend │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
|
||||
│ │ Sidebar │ │Workspaces│ │Create WS │ │Start Tool │ │
|
||||
│ │ (new) │ │ List │ │ Flow │ │Modal │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Backend API │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
|
||||
│ │Workspace CRUD│ │Workspace Sync│ │Instance Start (refact)│ │
|
||||
│ │ /workspaces │ │ /sync │ │ /start │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────────┼──────────────────────────────┐ │
|
||||
│ │ GitService │ WorkspaceService │ │
|
||||
│ │ (clone, fetch, pull) │ (create, delete, sync) │ │
|
||||
│ └───────────────────────────┼──────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────────────┼──────────────────────────────┐ │
|
||||
│ │ Docker Compose │ File System │ │
|
||||
│ │ (mount workspace path) │ /data/working-copies/... │ │
|
||||
│ └───────────────────────────┴──────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Backend Design
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
apps/api/src/
|
||||
├── api/
|
||||
│ ├── workspaces.py # NEW: Workspace CRUD endpoints
|
||||
│ └── tool_instances.py # MODIFIED: use workspace_id
|
||||
├── models/
|
||||
│ ├── workspace.py # NEW: Workspace model
|
||||
│ └── tool_instance.py # MODIFIED: add workspace_id
|
||||
├── services/
|
||||
│ ├── workspace_manager.py # NEW: Workspace lifecycle
|
||||
│ ├── git_service.py # NEW: Git operations (clone, fetch, pull)
|
||||
│ └── docker.py # EXISTING: mount workspace path
|
||||
└── alembic/versions/
|
||||
└── 2026_06_01_add_workspaces.py # NEW migration
|
||||
```
|
||||
|
||||
### Model: Workspace
|
||||
|
||||
```python
|
||||
class Workspace(Base):
|
||||
__tablename__ = "workspaces"
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
|
||||
name: Mapped[str] = mapped_column(String(255), nullable=False)
|
||||
repo_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("git_repositories.id"), nullable=False)
|
||||
user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
|
||||
branch: Mapped[str] = mapped_column(String(255), nullable=False, default="main")
|
||||
path: Mapped[str] = mapped_column(String(2048), nullable=False)
|
||||
status: Mapped[str] = mapped_column(String(16), nullable=False, default="ready")
|
||||
last_sync_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
|
||||
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=datetime.now)
|
||||
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=datetime.now, onupdate=datetime.now)
|
||||
|
||||
__table_args__ = (
|
||||
UniqueConstraint("repo_id", "name", name="uq_workspace_repo_name"),
|
||||
)
|
||||
```
|
||||
|
||||
### Service: WorkspaceManager
|
||||
|
||||
```python
|
||||
class WorkspaceManager:
|
||||
"""Manages workspace lifecycle: create, delete, sync, validate."""
|
||||
|
||||
BASE_PATH = "/data/working-copies"
|
||||
|
||||
async def create(
|
||||
self,
|
||||
repo: GitRepository,
|
||||
user_id: uuid.UUID,
|
||||
name: str,
|
||||
branch: str = "main",
|
||||
) -> Workspace:
|
||||
"""Clone repo to workspace path and create DB record."""
|
||||
path = f"{self.BASE_PATH}/{repo.id}/{name}"
|
||||
# Clone repo
|
||||
await GitService.clone(repo.remote_url, branch, path)
|
||||
# Create record
|
||||
workspace = Workspace(...)
|
||||
return workspace
|
||||
|
||||
async def delete(
|
||||
self,
|
||||
workspace: Workspace,
|
||||
force: bool = False,
|
||||
) -> None:
|
||||
"""Delete workspace and all associated tool instances."""
|
||||
instances = await self._get_running_instances(workspace)
|
||||
if instances and not force:
|
||||
raise WorkspaceHasInstancesError(instances)
|
||||
|
||||
# Stop and delete all instances
|
||||
for instance in instances:
|
||||
await self._stop_and_delete_instance(instance)
|
||||
|
||||
# Delete directory
|
||||
shutil.rmtree(workspace.path, ignore_errors=True)
|
||||
|
||||
# Delete record
|
||||
await session.delete(workspace)
|
||||
|
||||
async def sync(self, workspace: Workspace) -> SyncResult:
|
||||
"""Fetch remote and detect deleted branches."""
|
||||
result = await GitService.fetch(workspace.path)
|
||||
if not GitService.branch_exists_remotely(workspace.path, workspace.branch):
|
||||
return SyncResult(branch_deleted=True)
|
||||
|
||||
await GitService.pull(workspace.path, workspace.branch)
|
||||
workspace.last_sync_at = datetime.now()
|
||||
return SyncResult(branch_deleted=False)
|
||||
```
|
||||
|
||||
### Service: GitService
|
||||
|
||||
```python
|
||||
class GitService:
|
||||
"""Git operations for workspace management."""
|
||||
|
||||
@staticmethod
|
||||
async def clone(remote_url: str, branch: str, path: str) -> None:
|
||||
"""Clone a repo to the given path."""
|
||||
cmd = ["git", "clone", "--branch", branch, "--single-branch", remote_url, path]
|
||||
# Run via asyncio subprocess
|
||||
|
||||
@staticmethod
|
||||
async def fetch(path: str) -> None:
|
||||
"""Fetch from origin."""
|
||||
cmd = ["git", "-C", path, "fetch", "origin"]
|
||||
|
||||
@staticmethod
|
||||
async def pull(path: str, branch: str) -> None:
|
||||
"""Pull latest changes."""
|
||||
cmd = ["git", "-C", path, "pull", "origin", branch]
|
||||
|
||||
@staticmethod
|
||||
def branch_exists_remotely(path: str, branch: str) -> bool:
|
||||
"""Check if a branch exists on the remote."""
|
||||
cmd = ["git", "-C", path, "ls-remote", "--heads", "origin", branch]
|
||||
# Return True if output is not empty
|
||||
```
|
||||
|
||||
### API: Workspaces
|
||||
|
||||
```python
|
||||
router = APIRouter(prefix="/projects/{project_id}/repositories/{repo_id}/workspaces")
|
||||
|
||||
@router.post("/")
|
||||
async def create_workspace(
|
||||
project_id: uuid.UUID,
|
||||
repo_id: uuid.UUID,
|
||||
data: CreateWorkspaceRequest,
|
||||
user_id: uuid.UUID = Depends(get_current_user_id),
|
||||
session: AsyncSession = Depends(get_db_session),
|
||||
) -> WorkspaceResponse:
|
||||
repo = await get_repo(repo_id, user_id, session)
|
||||
workspace = await WorkspaceManager().create(repo, user_id, data.name, data.branch)
|
||||
session.add(workspace)
|
||||
await session.commit()
|
||||
return workspace
|
||||
|
||||
@router.delete("/{workspace_id}")
|
||||
async def delete_workspace(
|
||||
workspace_id: uuid.UUID,
|
||||
force: bool = Query(False),
|
||||
user_id: uuid.UUID = Depends(get_current_user_id),
|
||||
session: AsyncSession = Depends(get_db_session),
|
||||
) -> dict:
|
||||
workspace = await get_workspace(workspace_id, user_id, session)
|
||||
try:
|
||||
await WorkspaceManager().delete(workspace, force=force)
|
||||
except WorkspaceHasInstancesError as exc:
|
||||
raise HTTPException(
|
||||
status_code=409,
|
||||
detail={
|
||||
"message": "Workspace has running tool instances",
|
||||
"instances": [{"id": str(i.id), "name": i.name} for i in exc.instances],
|
||||
},
|
||||
)
|
||||
return {"status": "deleted"}
|
||||
|
||||
@router.post("/{workspace_id}/sync")
|
||||
async def sync_workspace(
|
||||
workspace_id: uuid.UUID,
|
||||
user_id: uuid.UUID = Depends(get_current_user_id),
|
||||
session: AsyncSession = Depends(get_db_session),
|
||||
) -> SyncResult:
|
||||
workspace = await get_workspace(workspace_id, user_id, session)
|
||||
result = await WorkspaceManager().sync(workspace)
|
||||
if result.branch_deleted:
|
||||
raise HTTPException(
|
||||
status_code=409,
|
||||
detail={
|
||||
"message": f"Branch '{workspace.branch}' was deleted from remote",
|
||||
"branch_deleted": True,
|
||||
},
|
||||
)
|
||||
return result
|
||||
```
|
||||
|
||||
### Updated: Instance Start
|
||||
|
||||
```python
|
||||
@router.post("/{instance_id}/start")
|
||||
async def start_instance(
|
||||
instance_id: uuid.UUID,
|
||||
data: StartInstanceRequest,
|
||||
user_id: uuid.UUID = Depends(get_current_user_id),
|
||||
session: AsyncSession = Depends(get_db_session),
|
||||
) -> dict:
|
||||
instance = await get_instance(instance_id, user_id, session)
|
||||
|
||||
# Get workspace
|
||||
workspace = await session.get(Workspace, instance.workspace_id)
|
||||
if not workspace:
|
||||
raise HTTPException(400, "Workspace not found")
|
||||
|
||||
# Mount workspace path instead of repo path
|
||||
repo_path = workspace.path
|
||||
|
||||
# Generate compose with workspace mount
|
||||
compose_content = generate_compose(workspace, instance, tool_type)
|
||||
|
||||
# ... rest of start logic
|
||||
```
|
||||
|
||||
## Frontend Design
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
apps/web/src/
|
||||
├── pages/
|
||||
│ ├── workspaces.tsx # NEW: Workspaces list page
|
||||
│ └── workspace-detail.tsx # NEW: Workspace detail page
|
||||
├── components/
|
||||
│ ├── workspace-card.tsx # NEW: Workspace card component
|
||||
│ ├── workspace-create-form.tsx # NEW: Create workspace form
|
||||
│ ├── start-tool-modal.tsx # NEW: Start tool on workspace modal
|
||||
│ └── sidebar.tsx # MODIFIED: add Workspaces nav
|
||||
├── hooks/
|
||||
│ ├── use-workspaces.ts # NEW: Workspace data hook
|
||||
│ └── use-workspace-actions.ts # NEW: Workspace CRUD actions
|
||||
├── api/
|
||||
│ └── workspaces.ts # NEW: Workspace API client
|
||||
└── types/
|
||||
└── workspace.ts # NEW: Workspace types
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
```typescript
|
||||
export interface Workspace {
|
||||
id: string;
|
||||
name: string;
|
||||
repo_id: string;
|
||||
repo_name: string;
|
||||
project_name: string;
|
||||
user_id: string;
|
||||
branch: string;
|
||||
path: string;
|
||||
status: "ready" | "syncing" | "error";
|
||||
last_sync_at: string | null;
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
instance_count: number;
|
||||
}
|
||||
|
||||
export interface CreateWorkspaceRequest {
|
||||
name: string;
|
||||
branch: string;
|
||||
}
|
||||
|
||||
export interface SyncResult {
|
||||
branch_deleted: boolean;
|
||||
pulled: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### Component: WorkspaceCard
|
||||
|
||||
```tsx
|
||||
export function WorkspaceCard({
|
||||
workspace,
|
||||
onStartTool,
|
||||
onSync,
|
||||
onDelete,
|
||||
}: WorkspaceCardProps) {
|
||||
return (
|
||||
<article className="card workspace-card">
|
||||
<div className="workspace-header">
|
||||
<h4>{workspace.name}</h4>
|
||||
<span className={`status-badge ${workspace.status}`}>
|
||||
{workspace.status}
|
||||
</span>
|
||||
</div>
|
||||
<div className="workspace-meta">
|
||||
<p>{workspace.project_name} / {workspace.repo_name}</p>
|
||||
<p><Icon name="branch" /> {workspace.branch}</p>
|
||||
{workspace.instance_count > 0 && (
|
||||
<p>{workspace.instance_count} active tool{workspace.instance_count > 1 ? "s" : ""}</p>
|
||||
)}
|
||||
</div>
|
||||
<div className="workspace-actions">
|
||||
<button onClick={() => onStartTool(workspace)}>
|
||||
<Icon name="play" /> Start Tool
|
||||
</button>
|
||||
<button onClick={() => onSync(workspace)}>
|
||||
<Icon name="refresh" /> Sync
|
||||
</button>
|
||||
<button onClick={() => onDelete(workspace)} className="danger">
|
||||
<Icon name="delete" /> Delete
|
||||
</button>
|
||||
</div>
|
||||
</article>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Component: Sidebar (updated)
|
||||
|
||||
```tsx
|
||||
const navItems = [
|
||||
{ path: "/dashboard", label: "Dashboard", icon: "home" },
|
||||
{ path: "/projects", label: "Projects", icon: "folder" },
|
||||
{ path: "/workspaces", label: "Workspaces", icon: "workspace" },
|
||||
{ path: "/settings", label: "Settings", icon: "settings" },
|
||||
];
|
||||
```
|
||||
|
||||
### Hook: useWorkspaceActions
|
||||
|
||||
```typescript
|
||||
export function useWorkspaceActions(options: { onRefresh: () => Promise<void> }) {
|
||||
const [loadingId, setLoadingId] = useState<string | null>(null);
|
||||
|
||||
const handleDelete = useCallback(async (workspace: Workspace, force = false) => {
|
||||
setLoadingId(workspace.id);
|
||||
try {
|
||||
await deleteWorkspace(workspace.repo_id, workspace.id, force);
|
||||
await options.onRefresh();
|
||||
} catch (err) {
|
||||
const error = err as AxiosError<{ detail?: { instances?: Array<{id: string, name: string}> } }>;
|
||||
if (error.response?.status === 409 && !force) {
|
||||
const instances = error.response.data?.detail?.instances || [];
|
||||
const confirmed = confirm(
|
||||
`This workspace has ${instances.length} running tool instance(s):\n` +
|
||||
instances.map(i => `- ${i.name}`).join("\n") +
|
||||
`\n\nDelete workspace and all instances?`
|
||||
);
|
||||
if (confirmed) {
|
||||
await handleDelete(workspace, true);
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
setLoadingId(null);
|
||||
}
|
||||
}, [options.onRefresh]);
|
||||
|
||||
const handleSync = useCallback(async (workspace: Workspace) => {
|
||||
setLoadingId(workspace.id);
|
||||
try {
|
||||
const result = await syncWorkspace(workspace.repo_id, workspace.id);
|
||||
await options.onRefresh();
|
||||
return result;
|
||||
} catch (err) {
|
||||
const error = err as AxiosError<{ detail?: { branch_deleted?: boolean; message?: string } }>;
|
||||
if (error.response?.status === 409 && error.response.data?.detail?.branch_deleted) {
|
||||
const confirmed = confirm(
|
||||
`${error.response.data.detail.message}\n\nDelete this workspace?`
|
||||
);
|
||||
if (confirmed) {
|
||||
await handleDelete(workspace, true);
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
setLoadingId(null);
|
||||
}
|
||||
}, [options.onRefresh, handleDelete]);
|
||||
|
||||
return { loadingId, handleDelete, handleSync };
|
||||
}
|
||||
```
|
||||
|
||||
## Compose Template Updates
|
||||
|
||||
### Workspace Mount
|
||||
|
||||
All compose templates will mount the workspace path instead of the repo path:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
image: ${IMAGE_TAG}
|
||||
container_name: ${INSTANCE_NAME}
|
||||
volumes:
|
||||
- ${WORKSPACE_PATH}:/workspace
|
||||
working_dir: /workspace
|
||||
# ... rest of config
|
||||
```
|
||||
|
||||
The `${WORKSPACE_PATH}` variable replaces `${REPO_PATH}` in all templates.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | HTTP Status | Frontend Behavior |
|
||||
|---|---|---|
|
||||
| Workspace name not unique per repo | 409 | Show inline validation error |
|
||||
| Workspace has running instances | 409 | Show confirmation dialog |
|
||||
| Branch deleted from remote | 409 | Show confirmation dialog to delete workspace |
|
||||
| Repo not found | 404 | Show error toast |
|
||||
| Git clone failed | 500 | Show error toast with git stderr |
|
||||
| Workspace path missing | 500 | Show error toast |
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **Git clone** is synchronous and slow; run in background with status polling
|
||||
- **Workspace list** should include `instance_count` via subquery (not N+1)
|
||||
- **Sync** is fast (fetch only), but pull may be slow; run async
|
||||
- **Delete with instances** stops instances sequentially; consider parallel
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Workspace paths must be validated to prevent path traversal
|
||||
- Users can only access their own workspaces
|
||||
- Git credentials (SSH keys) must be available during clone
|
||||
- Workspace directories must have correct ownership for container users
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Backend
|
||||
- Unit: WorkspaceManager.create, delete, sync
|
||||
- Unit: GitService.clone, fetch, pull, branch_exists_remotely
|
||||
- Integration: Create workspace → start tool → verify mount
|
||||
- Integration: Delete workspace with running instances
|
||||
- Integration: Sync with deleted branch
|
||||
|
||||
### Frontend
|
||||
- Component: WorkspaceCard renders correctly
|
||||
- Component: Create form validates name uniqueness
|
||||
- Hook: useWorkspaceActions handles 409 confirmation
|
||||
- E2E: Create workspace → start tool → delete workspace
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Auto-sync on schedule
|
||||
- Workspace sharing between users
|
||||
- Git push/pull/branch UI
|
||||
- Pre-created default workspaces
|
||||
- Read-only workspace mode
|
||||
- Workspace backup/restore
|
||||
|
||||
## Files Changed
|
||||
|
||||
### New Files
|
||||
- `apps/api/src/models/workspace.py`
|
||||
- `apps/api/src/api/workspaces.py`
|
||||
- `apps/api/src/services/workspace_manager.py`
|
||||
- `apps/api/src/services/git_service.py`
|
||||
- `apps/api/alembic/versions/2026_06_01_add_workspaces.py`
|
||||
- `apps/web/src/pages/workspaces.tsx`
|
||||
- `apps/web/src/pages/workspace-detail.tsx`
|
||||
- `apps/web/src/components/workspace-card.tsx`
|
||||
- `apps/web/src/components/workspace-create-form.tsx`
|
||||
- `apps/web/src/components/start-tool-modal.tsx`
|
||||
- `apps/web/src/hooks/use-workspaces.ts`
|
||||
- `apps/web/src/hooks/use-workspace-actions.ts`
|
||||
- `apps/web/src/api/workspaces.ts`
|
||||
- `apps/web/src/types/workspace.ts`
|
||||
|
||||
### Modified Files
|
||||
- `apps/api/src/models/tool_instance.py` (add workspace_id)
|
||||
- `apps/api/src/api/tool_instances.py` (use workspace path)
|
||||
- `apps/web/src/components/sidebar.tsx` (add nav item)
|
||||
- `apps/web/src/pages/dashboard.tsx` (add workspaces section)
|
||||
- `apps/web/src/api/sessions.ts` (add workspace endpoints)
|
||||
@@ -0,0 +1,103 @@
|
||||
# Explore: Working Copies
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Currently, tool instances mount repositories directly. Each tool instance either:
|
||||
- **Mount mode**: Bind-mounts the shared repo path (`/data/repos/<repo>`) read-only
|
||||
- **Clone mode**: Clones the repo into the instance directory
|
||||
|
||||
This has several problems:
|
||||
1. **Mount mode**: Read-only, so users can't edit files in the tool
|
||||
2. **Clone mode**: Creates a full copy per instance, wasting disk space
|
||||
3. **UI complexity**: The create-instance form must ask "mount or clone?" and handle branch selection
|
||||
4. **No persistence**: Clone-mode repos live inside the instance directory and are lost on delete
|
||||
5. **Race conditions**: Multiple instances mounting the same repo can conflict
|
||||
|
||||
## Proposed Solution: Working Copies
|
||||
|
||||
Introduce a **Workspace** as a first-class entity: a persistent, writable local clone of a repository that lives independently of any tool instance. Tool instances are then *started on* a working copy, which is mounted into the container.
|
||||
|
||||
### Naming Candidates
|
||||
|
||||
| Name | Pros | Cons |
|
||||
|---|---|---|
|
||||
| Workspace | Common in IDEs; implies a working area | Conflicts with existing docs/features/workspace.md |
|
||||
| **Workspace** | Common in IDEs (VS Code, JetBrains); implies a working area | May conflict with existing "workspace" terminology in docs |
|
||||
| **Checkout** | Git-native term; implies a working tree | Too specific to git; implies a single commit/branch |
|
||||
| **Sandbox** | Implies isolation and experimentation | Suggests throwaway/ephemeral, not persistent |
|
||||
| **Dev Copy** | Simple and descriptive | Informal; "copy" still implies duplication |
|
||||
| **Project Clone** | Clear relationship to project+repo | Clunky; two words |
|
||||
| **Branch** | Git-native; each working copy is effectively a branch workspace | Too git-specific; may confuse with git branches |
|
||||
|
||||
**Decision: "Workspace"** — chosen by user despite existing docs/features/workspace.md. The existing workspace.md will be superseded/renamed to avoid confusion. — it's the most precise term. In SVN/Git parlance, a "working copy" is exactly what we want: a local, writable copy of a repository that you work on. The term is established enough that developers understand it, but not so overloaded in our domain that it conflicts.
|
||||
|
||||
### Entity Model
|
||||
|
||||
```
|
||||
Project
|
||||
└── GitRepository (the canonical repo, read-only source)
|
||||
└── WorkingCopy (writable local clone, 1+ per repo)
|
||||
└── ToolInstance (mounts the working copy)
|
||||
```
|
||||
|
||||
A Workspace:
|
||||
- Has a `name` (auto-generated or user-defined)
|
||||
- Has a `path` on disk (under `/data/working-copies/<repo-id>/<copy-name>`)
|
||||
- Has a `branch` (the branch it's currently on)
|
||||
- Has a `status` (ready, syncing, error)
|
||||
- Belongs to a `GitRepository`
|
||||
- Belongs to a `User`
|
||||
- Has many `ToolInstance`s
|
||||
|
||||
### User Flow
|
||||
|
||||
1. User navigates to **Working Copies** in the sidebar
|
||||
2. Sees list of working copies (or creates one from a repo)
|
||||
3. Clicks "New Workspace" → selects repo + branch → named copy created
|
||||
4. From a working copy, clicks "Start Tool" → selects tool type → instance starts with working copy mounted
|
||||
5. Multiple tool instances can share the same working copy (e.g., terminal + code-server side by side)
|
||||
|
||||
### Benefits
|
||||
|
||||
1. **Writable by default**: Working copies are clones, so tools can edit files
|
||||
2. **Shared across instances**: Multiple tools can mount the same working copy
|
||||
3. **Persistent**: Survives instance deletion
|
||||
4. **Simplified UI**: No more "mount vs clone" decision; tool creation is just "pick a working copy"
|
||||
5. **Git operations**: Working copies can support git push/pull/branch from the UI
|
||||
6. **Disk efficient**: One clone per working copy, not one per instance
|
||||
|
||||
### Open Questions
|
||||
|
||||
1. Should working copies auto-sync with the canonical repo?
|
||||
2. Should we support multiple working copies per repo (e.g., one per branch)?
|
||||
3. How do we handle merge conflicts if the canonical repo changes?
|
||||
4. Should working copies be scoped to a user or to a project?
|
||||
5. What happens to tool instances when a working copy is deleted?
|
||||
6. Should we pre-create a default working copy when a repo is added?
|
||||
|
||||
### Migration Path
|
||||
|
||||
Existing tool instances that use clone_mode can be migrated:
|
||||
- On first access, extract the cloned repo from the instance directory
|
||||
- Move it to `/data/working-copies/...`
|
||||
- Create a WorkingCopy record pointing to it
|
||||
- Update the instance to mount the working copy path
|
||||
|
||||
Mount-mode instances can be converted on restart:
|
||||
- Create a working copy from the canonical repo
|
||||
- Switch the instance to mount the working copy instead
|
||||
|
||||
### Scope for This Change
|
||||
|
||||
This change focuses on:
|
||||
- [ ] Creating the WorkingCopy entity and database table
|
||||
- [ ] Adding a Working Copies section to the UI (sidebar nav + list view)
|
||||
- [ ] Updating tool instance creation to select a working copy instead of repo+clone_mode
|
||||
- [ ] Updating compose generation to mount the working copy path
|
||||
- [ ] Migrating existing clone_mode instances to use working copies
|
||||
|
||||
Out of scope (future changes):
|
||||
- [ ] Auto-sync with canonical repo
|
||||
- [ ] Git operations UI (push/pull/branch)
|
||||
- [ ] Working copy sharing between users
|
||||
- [ ] Pre-create default working copies
|
||||
@@ -0,0 +1,132 @@
|
||||
# Proposal: Workspace-Based Tool Instances
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Phase | **Proposal** |
|
||||
| Based on | [Explore](explore.md) |
|
||||
| Next | Spec |
|
||||
|
||||
## Decisions from Explore
|
||||
|
||||
| Decision | Value |
|
||||
|---|---|
|
||||
| **Name** | "Workspace" (supersedes existing workspace.md) |
|
||||
| **Scope** | Unlimited workspaces per repository |
|
||||
| **Auto-create** | No — explicit creation only |
|
||||
| **Default branch** | Main/master or user-selected at creation time |
|
||||
| **Delete with running instances** | Allowed with confirmation; stops and deletes all associated tool instances |
|
||||
| **Name uniqueness** | Unique per project+repo (derived from project and repo names) |
|
||||
| **Deleted remote branch** | On sync/update, detect and ask for confirmation to delete local workspace/branch |
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The current tool instance creation requires users to choose between "mount" (read-only) and "clone" (writable but ephemeral) modes. This is confusing and leads to either:
|
||||
- **Mount mode**: Tools open files read-only, frustrating editing
|
||||
- **Clone mode**: Each instance clones the repo, wasting disk space and losing work on deletion
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Introduce **Workspaces** as first-class entities: persistent, writable local clones of a repository that exist independently of tool instances. Users create workspaces explicitly, then start tool instances *on* a workspace.
|
||||
|
||||
### Entity Relationship
|
||||
|
||||
```
|
||||
Project
|
||||
└── GitRepository (canonical source)
|
||||
└── Workspace (writable clone, unlimited per repo)
|
||||
└── ToolInstance (mounts workspace path)
|
||||
```
|
||||
|
||||
### Key Behaviors
|
||||
|
||||
1. **Workspace Creation**: User selects a repository → picks a branch → names the workspace → clone is created on disk
|
||||
2. **Tool Instance Creation**: User selects a workspace → picks a tool type → instance starts with workspace mounted
|
||||
3. **Multiple Tools per Workspace**: Several tool instances can share the same workspace (e.g., terminal + code-server)
|
||||
4. **Persistence**: Workspaces survive tool instance deletion
|
||||
5. **No Auto-Create**: Users must explicitly create workspaces; no magic default workspace
|
||||
|
||||
### UI Changes
|
||||
|
||||
- **New sidebar entry**: "Workspaces" (between "Projects" and "Settings")
|
||||
- **Workspaces page**: List of all workspaces with repo/branch/status info
|
||||
- **Create workspace flow**: Repo picker → branch picker → name input
|
||||
- **Start tool from workspace**: Tool picker modal from workspace card
|
||||
- **Simplified tool creation**: Remove "clone mode" / "mount mode" toggle; always use workspace
|
||||
|
||||
### Database Changes
|
||||
|
||||
New table: `workspaces`
|
||||
- `id` (UUID, PK)
|
||||
- `name` (string, user-defined)
|
||||
- `repo_id` (UUID, FK → git_repositories)
|
||||
- `user_id` (UUID, FK → users)
|
||||
- `branch` (string)
|
||||
- `path` (string, absolute disk path)
|
||||
- `status` (enum: ready, syncing, error)
|
||||
- `created_at`, `updated_at`
|
||||
|
||||
Updated: `tool_instances`
|
||||
- Add `workspace_id` (UUID, FK → workspaces, nullable for migration)
|
||||
- Remove `clone_mode` (deprecated)
|
||||
- Remove `branch` (moved to workspace)
|
||||
|
||||
### File System Layout
|
||||
|
||||
```
|
||||
/data/working-copies/
|
||||
└── {repo-id}/
|
||||
└── {workspace-name}/
|
||||
└── .git/
|
||||
└── [repo files]
|
||||
```
|
||||
|
||||
### Migration Strategy
|
||||
|
||||
Existing `clone_mode` instances:
|
||||
- Extract cloned repo from instance directory
|
||||
- Move to `/data/working-copies/{repo-id}/{instance-name}/`
|
||||
- Create Workspace record
|
||||
- Update instance to reference workspace
|
||||
- Remove `clone_mode` flag
|
||||
|
||||
Existing `mount_mode` instances:
|
||||
- On next start, create a workspace from the canonical repo
|
||||
- Switch instance to use workspace
|
||||
- Remove `clone_mode` flag
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Auto-sync with canonical repo
|
||||
- Git push/pull/branch UI
|
||||
- Workspace sharing between users
|
||||
- Pre-created default workspaces
|
||||
- Read-only workspace mode
|
||||
|
||||
## Risks
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| Existing users with many clone_mode instances | One-time migration on instance restart |
|
||||
| Disk space from many workspaces | User-managed; can delete workspaces |
|
||||
| Workspace deleted while instances are running | Allowed with confirmation; cascade-delete tool instances |
|
||||
| Name collisions for workspace names | Unique per project+repo; derived from project and repo names |
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] User can create a workspace from any repository
|
||||
- [ ] User can create unlimited workspaces per repository
|
||||
- [ ] Tool instances mount the workspace path, not the canonical repo path
|
||||
- [ ] Multiple tool instances can share one workspace
|
||||
- [ ] Workspaces persist after tool instance deletion
|
||||
- [ ] Existing clone_mode instances migrate to workspace on restart
|
||||
- [ ] UI no longer shows "mount vs clone" toggle
|
||||
- [ ] New sidebar navigation "Workspaces" exists
|
||||
|
||||
## Open Questions for Spec
|
||||
|
||||
1. ~~Should workspace deletion cascade-delete associated tool instances, or block?~~ **Answered**: Allowed with confirmation; cascade-delete tool instances
|
||||
2. ~~Should workspace names be unique per-repo or globally unique?~~ **Answered**: Unique per project+repo; derived from project and repo names
|
||||
3. ~~How do we handle the case where a workspace's branch is deleted from the remote?~~ **Answered**: On sync/update, detect and ask for confirmation to delete local workspace/branch
|
||||
4. Should we validate the repo path exists before creating a workspace?
|
||||
@@ -0,0 +1,261 @@
|
||||
# Spec: Workspace-Based Tool Instances
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Phase | **Spec** |
|
||||
| Based on | [Proposal](proposal.md) |
|
||||
| Next | Design |
|
||||
|
||||
## Overview
|
||||
|
||||
Workspaces are persistent, writable local clones of Git repositories. Users create workspaces explicitly, then start tool instances on them. This replaces the current "mount vs clone" decision with a simple "pick a workspace" flow.
|
||||
|
||||
## Decisions
|
||||
|
||||
| Decision | Value |
|
||||
|---|---|
|
||||
| **Name** | "Workspace" |
|
||||
| **Scope** | Unlimited per repository |
|
||||
| **Auto-create** | No — explicit creation only |
|
||||
| **Delete with instances** | Allowed with confirmation; stops and deletes all associated tool instances |
|
||||
| **Name uniqueness** | Unique per project+repo; derived from project and repo names |
|
||||
| **Deleted remote branch** | On sync/update, detect and ask for confirmation to delete local workspace/branch |
|
||||
|
||||
## Database Schema
|
||||
|
||||
### New Table: `workspaces`
|
||||
|
||||
```sql
|
||||
CREATE TABLE workspaces (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
name VARCHAR(255) NOT NULL,
|
||||
repo_id UUID NOT NULL REFERENCES git_repositories(id) ON DELETE CASCADE,
|
||||
user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
branch VARCHAR(255) NOT NULL DEFAULT 'main',
|
||||
path VARCHAR(2048) NOT NULL,
|
||||
status VARCHAR(16) NOT NULL DEFAULT 'ready',
|
||||
last_sync_at TIMESTAMP WITH TIME ZONE,
|
||||
created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
|
||||
updated_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
|
||||
|
||||
UNIQUE (repo_id, name)
|
||||
);
|
||||
|
||||
CREATE INDEX idx_workspaces_repo_id ON workspaces(repo_id);
|
||||
CREATE INDEX idx_workspaces_user_id ON workspaces(user_id);
|
||||
CREATE INDEX idx_workspaces_status ON workspaces(status);
|
||||
```
|
||||
|
||||
### Updated Table: `tool_instances`
|
||||
|
||||
```sql
|
||||
ALTER TABLE tool_instances
|
||||
ADD COLUMN workspace_id UUID REFERENCES workspaces(id) ON DELETE SET NULL,
|
||||
ADD COLUMN clone_mode VARCHAR(16); -- deprecated, nullable for migration
|
||||
|
||||
-- Drop existing clone_mode column after all instances are migrated
|
||||
-- ALTER TABLE tool_instances DROP COLUMN clone_mode;
|
||||
```
|
||||
|
||||
Note: `tool_instances.branch` remains for now but is deprecated; the canonical branch lives on the workspace.
|
||||
|
||||
## Backend API
|
||||
|
||||
### Workspaces API
|
||||
|
||||
```
|
||||
GET /projects/{project_id}/repositories/{repo_id}/workspaces
|
||||
→ List workspaces for a repository
|
||||
|
||||
POST /projects/{project_id}/repositories/{repo_id}/workspaces
|
||||
→ Create a new workspace
|
||||
Body: { name: string, branch: string }
|
||||
|
||||
GET /projects/{project_id}/repositories/{repo_id}/workspaces/{workspace_id}
|
||||
→ Get workspace details
|
||||
|
||||
PATCH /projects/{project_id}/repositories/{repo_id}/workspaces/{workspace_id}
|
||||
→ Update workspace (rename, change branch)
|
||||
Body: { name?: string, branch?: string }
|
||||
|
||||
DELETE /projects/{project_id}/repositories/{repo_id}/workspaces/{workspace_id}
|
||||
→ Delete workspace (with ?force=true to skip confirmation)
|
||||
→ Stops and deletes all associated tool instances
|
||||
|
||||
POST /projects/{project_id}/repositories/{repo_id}/workspaces/{workspace_id}/sync
|
||||
→ Sync workspace with remote (detect deleted branches)
|
||||
```
|
||||
|
||||
### Tool Instances API (Updated)
|
||||
|
||||
```
|
||||
POST /projects/{project_id}/repositories/{repo_id}/instances
|
||||
Body: { tool_type_id, workspace_id, display_name?, config_profile_id? }
|
||||
→ Create instance on workspace
|
||||
|
||||
POST /projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/start
|
||||
→ Start instance (creates workspace if mount_mode, migrates if clone_mode)
|
||||
```
|
||||
|
||||
### Instance Start Logic
|
||||
|
||||
```python
|
||||
def start_instance(instance, workspace_id=None):
|
||||
if instance.clone_mode == "clone":
|
||||
# Migrate: extract clone to workspace
|
||||
workspace = migrate_clone_to_workspace(instance)
|
||||
instance.workspace_id = workspace.id
|
||||
instance.clone_mode = None
|
||||
elif instance.workspace_id:
|
||||
# Already using a workspace
|
||||
workspace = get_workspace(instance.workspace_id)
|
||||
else:
|
||||
# Legacy mount_mode: create workspace on first start
|
||||
workspace = create_workspace_from_repo(instance.repo)
|
||||
instance.workspace_id = workspace.id
|
||||
|
||||
# Mount workspace path into container
|
||||
mount_path = workspace.path
|
||||
# ... rest of start logic
|
||||
```
|
||||
|
||||
## Frontend Routes
|
||||
|
||||
```
|
||||
/workspaces → Workspaces list page
|
||||
/workspaces/new → Create workspace flow
|
||||
/workspaces/{id} → Workspace detail page
|
||||
/workspaces/{id}/tools → Start tool on workspace
|
||||
```
|
||||
|
||||
## UI Components
|
||||
|
||||
### Sidebar Navigation
|
||||
|
||||
```
|
||||
Projects
|
||||
└── [project list]
|
||||
Workspaces (NEW)
|
||||
└── All Workspaces
|
||||
└── [recent workspaces]
|
||||
Settings
|
||||
```
|
||||
|
||||
### Workspaces Page
|
||||
|
||||
- Grid/list of workspace cards
|
||||
- Each card shows: name, repo, branch, status, active instances count
|
||||
- Actions: Start Tool, Sync, Settings, Delete
|
||||
|
||||
### Create Workspace Flow
|
||||
|
||||
1. **Repo picker**: Select from existing repositories
|
||||
2. **Branch picker**: Select branch (default: repo's default branch)
|
||||
3. **Name input**: Auto-suggested as `{project-name}-{repo-name}-{branch}` but editable
|
||||
4. **Create**: Clone repo to `/data/working-copies/{repo-id}/{name}/`
|
||||
|
||||
### Start Tool from Workspace
|
||||
|
||||
1. **Tool picker**: Select tool type
|
||||
2. **Config**: Optional config profile
|
||||
3. **Create**: Instance created with workspace mounted
|
||||
|
||||
## File System Layout
|
||||
|
||||
```
|
||||
/data/working-copies/
|
||||
└── {repo-id}/
|
||||
└── {workspace-name}/
|
||||
└── .git/
|
||||
└── [repo files]
|
||||
```
|
||||
|
||||
## Workspace Lifecycle
|
||||
|
||||
### Creation
|
||||
|
||||
1. Validate name uniqueness per repo
|
||||
2. Clone repo: `git clone --branch {branch} {remote_url} {path}`
|
||||
3. Set status to `ready`
|
||||
4. Return workspace record
|
||||
|
||||
### Deletion
|
||||
|
||||
1. Check for running tool instances
|
||||
2. If instances exist and no `?force=true`:
|
||||
- Return 409 Conflict with `{ instances: [...] }`
|
||||
- Frontend shows confirmation dialog
|
||||
3. If confirmed:
|
||||
- Stop all associated instances
|
||||
- Delete all associated instances
|
||||
- Delete workspace directory
|
||||
- Delete workspace record
|
||||
|
||||
### Sync
|
||||
|
||||
1. Fetch from remote: `git fetch origin`
|
||||
2. Check if workspace branch still exists on remote
|
||||
3. If branch deleted:
|
||||
- Return 409 with `{ branch_deleted: true }`
|
||||
- Frontend asks: "Branch '{branch}' was deleted. Delete this workspace?"
|
||||
4. If branch exists:
|
||||
- Pull changes: `git pull origin {branch}`
|
||||
- Update `last_sync_at`
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Existing clone_mode Instances
|
||||
|
||||
```python
|
||||
def migrate_clone_to_workspace(instance):
|
||||
# Find the cloned repo inside the instance directory
|
||||
clone_path = find_clone_in_instance_dir(instance)
|
||||
|
||||
# Create workspace
|
||||
workspace = Workspace(
|
||||
name=f"{instance.name}-migrated",
|
||||
repo_id=instance.repository_id,
|
||||
user_id=instance.owner_id,
|
||||
branch=instance.branch or "main",
|
||||
path=f"/data/working-copies/{instance.repository_id}/{instance.name}-migrated",
|
||||
)
|
||||
|
||||
# Move clone to workspace path
|
||||
move(clone_path, workspace.path)
|
||||
|
||||
return workspace
|
||||
```
|
||||
|
||||
### Existing mount_mode Instances
|
||||
|
||||
On first start after deployment:
|
||||
1. Create workspace from canonical repo
|
||||
2. Update instance to use workspace
|
||||
3. Remove clone_mode flag
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Database migration creates `workspaces` table
|
||||
- [ ] Database migration adds `workspace_id` to `tool_instances`
|
||||
- [ ] API endpoints for CRUD operations on workspaces
|
||||
- [ ] Workspace creation clones repo to `/data/working-copies/...`
|
||||
- [ ] Workspace deletion stops and deletes associated tool instances
|
||||
- [ ] Workspace sync detects deleted branches and asks for confirmation
|
||||
- [ ] Tool instance creation accepts `workspace_id` instead of `clone_mode`
|
||||
- [ ] Tool instance start mounts workspace path into container
|
||||
- [ ] Frontend has "Workspaces" sidebar entry
|
||||
- [ ] Frontend workspaces list page
|
||||
- [ ] Frontend create workspace flow
|
||||
- [ ] Frontend start tool from workspace
|
||||
- [ ] Existing clone_mode instances migrate on restart
|
||||
- [ ] Existing mount_mode instances create workspace on restart
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- [ ] Backend tests: workspace CRUD, sync, deletion with instances
|
||||
- [ ] Frontend tests: workspace list, create, start tool
|
||||
- [ ] Integration tests: instance creation with workspace
|
||||
- [ ] ruff clean
|
||||
- [ ] TypeScript compilation clean
|
||||
@@ -0,0 +1,138 @@
|
||||
# Tasks: Workspace-Based Tool Instances
|
||||
|
||||
## Status
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| Phase | **Tasks** |
|
||||
| Based on | [Design](design.md) |
|
||||
| Next | Apply |
|
||||
|
||||
## PR Breakdown
|
||||
|
||||
### PR-1: Backend Foundation
|
||||
**Scope**: Database migration, models, services, API endpoints for workspaces
|
||||
**Est. lines**: ~800 backend, ~300 tests
|
||||
**Files touched**: 8 new, 2 modified
|
||||
|
||||
**Tasks**:
|
||||
1. [ ] Create Alembic migration for `workspaces` table + `workspace_id` on `tool_instances`
|
||||
2. [ ] Create `Workspace` model (`apps/api/src/models/workspace.py`)
|
||||
3. [ ] Add `workspace_id` to `ToolInstance` model (nullable FK)
|
||||
4. [ ] Create `GitService` (`apps/api/src/services/git_service.py`) — clone, fetch, pull, branch_exists_remotely
|
||||
5. [ ] Create `WorkspaceManager` (`apps/api/src/services/workspace_manager.py`) — create, delete, sync
|
||||
6. [ ] Create workspace API router (`apps/api/src/api/workspaces.py`) — CRUD + sync endpoints
|
||||
7. [ ] Add workspace routes to FastAPI app (`apps/api/src/main.py`)
|
||||
8. [ ] Write unit tests for GitService
|
||||
9. [ ] Write integration tests for workspace CRUD
|
||||
10. [ ] Write integration tests for delete-with-instances (409 behavior)
|
||||
11. [ ] Write integration tests for sync-with-deleted-branch (409 behavior)
|
||||
|
||||
### PR-2: Backend Integration
|
||||
**Scope**: Tool instance creation/start uses workspace instead of repo path
|
||||
**Est. lines**: ~400 backend, ~200 tests
|
||||
**Files touched**: 3 modified
|
||||
|
||||
**Tasks**:
|
||||
1. [ ] Update `create_instance` endpoint to accept `workspace_id` instead of `clone_mode`
|
||||
2. [ ] Update `start_instance` to mount workspace path (`workspace.path`) instead of repo path
|
||||
3. [ ] Update compose generation to use `WORKSPACE_PATH` variable
|
||||
4. [ ] Update `tool_instances.py` compose template rendering
|
||||
5. [ ] Write integration tests for instance creation with workspace
|
||||
6. [ ] Write integration tests for instance start with workspace mount
|
||||
7. [ ] Verify old mount_mode instances still work (backward compat)
|
||||
|
||||
### PR-3: Frontend Core
|
||||
**Scope**: Workspaces UI — list, create, card, actions
|
||||
**Est. lines**: ~1,200 frontend, ~400 tests
|
||||
**Files touched**: 10 new, 2 modified
|
||||
|
||||
**Tasks**:
|
||||
1. [ ] Create workspace types (`apps/web/src/types/workspace.ts`)
|
||||
2. [ ] Create workspace API client (`apps/web/src/api/workspaces.ts`)
|
||||
3. [ ] Create `useWorkspaces` hook (`apps/web/src/hooks/use-workspaces.ts`)
|
||||
4. [ ] Create `useWorkspaceActions` hook (`apps/web/src/hooks/use-workspace-actions.ts`)
|
||||
5. [ ] Create `WorkspaceCard` component (`apps/web/src/components/workspace-card.tsx`)
|
||||
6. [ ] Create `WorkspaceCreateForm` component (`apps/web/src/components/workspace-create-form.tsx`)
|
||||
7. [ ] Create `StartToolModal` component (`apps/web/src/components/start-tool-modal.tsx`)
|
||||
8. [ ] Create `WorkspacesPage` (`apps/web/src/pages/workspaces.tsx`)
|
||||
9. [ ] Update `Sidebar` to add Workspaces nav item
|
||||
10. [ ] Update router/routes to include `/workspaces`
|
||||
11. [ ] Write component tests for WorkspaceCard
|
||||
12. [ ] Write hook tests for useWorkspaceActions
|
||||
13. [ ] Write tests for create form validation
|
||||
|
||||
### PR-4: Frontend Integration
|
||||
**Scope**: Update existing flows to use workspaces, dashboard integration
|
||||
**Est. lines**: ~600 frontend, ~200 tests
|
||||
**Files touched**: 5 modified
|
||||
|
||||
**Tasks**:
|
||||
1. [ ] Update `CreateSessionForm` to use workspace picker instead of repo+clone_mode
|
||||
2. [ ] Update `SessionsPage` dashboard to show workspaces section
|
||||
3. [ ] Update `SessionCard` to show workspace name instead of clone mode
|
||||
4. [ ] Update `useInstanceActions` to pass `workspace_id` on create
|
||||
5. [ ] Remove clone_mode/mount_mode UI toggles
|
||||
6. [ ] Update types to remove deprecated `clone_mode` field
|
||||
7. [ ] Write integration tests for full create-workspace → start-tool flow
|
||||
8. [ ] Write tests for dashboard workspaces section
|
||||
|
||||
## Acceptance Criteria (All PRs)
|
||||
|
||||
- [ ] User can create a workspace from any repository
|
||||
- [ ] User can create unlimited workspaces per repository
|
||||
- [ ] Workspace names are unique per repo
|
||||
- [ ] Tool instances mount the workspace path
|
||||
- [ ] Multiple tool instances can share one workspace
|
||||
- [ ] Workspaces persist after tool instance deletion
|
||||
- [ ] Deleting a workspace with running instances shows confirmation, stops and deletes instances
|
||||
- [ ] Syncing a workspace with a deleted remote branch shows confirmation
|
||||
- [ ] UI no longer shows "mount vs clone" toggle
|
||||
- [ ] New sidebar navigation "Workspaces" exists
|
||||
- [ ] All existing tests still pass
|
||||
- [ ] ruff clean
|
||||
- [ ] TypeScript compilation clean
|
||||
|
||||
## Implementation Order
|
||||
|
||||
```
|
||||
PR-1 (Backend Foundation)
|
||||
→ PR-2 (Backend Integration)
|
||||
→ PR-3 (Frontend Core)
|
||||
→ PR-4 (Frontend Integration)
|
||||
```
|
||||
|
||||
Each PR depends on the previous. No parallel work.
|
||||
|
||||
## Verification Steps per PR
|
||||
|
||||
### PR-1
|
||||
```bash
|
||||
cd apps/api
|
||||
alembic upgrade head
|
||||
pytest tests/unit/test_git_service.py tests/integration/test_workspaces.py -v
|
||||
python -m ruff check src/services/git_service.py src/services/workspace_manager.py src/api/workspaces.py
|
||||
```
|
||||
|
||||
### PR-2
|
||||
```bash
|
||||
cd apps/api
|
||||
pytest tests/integration/test_tool_instances_with_workspace.py -v
|
||||
python -m ruff check src/api/tool_instances.py
|
||||
```
|
||||
|
||||
### PR-3
|
||||
```bash
|
||||
cd apps/web
|
||||
npm run test -- --run workspaces
|
||||
npx tsc --noEmit
|
||||
npx eslint src/pages/workspaces.tsx src/components/workspace-*.tsx
|
||||
```
|
||||
|
||||
### PR-4
|
||||
```bash
|
||||
cd apps/web
|
||||
npm run test -- --run sessions create-session
|
||||
npx tsc --noEmit
|
||||
npx eslint src/pages/sessions.tsx src/components/create-session-form.tsx
|
||||
```
|
||||
Reference in New Issue
Block a user