headquarter/openspec/changes/tool-instances/tasks.md

Tool Instances - Tasks

Phase 1: Backend Model & Database

• Task 1.1: Create ToolInstance model

  • Create src/models/tool_instance.py
  • Fields: id, name, display_name, tool_type_id, repository_id, project_id, owner_id, status, container_id, compose_path, url, port, timestamps
  • Add relationship to ToolType and GitRepository
  • Add to models/__init__.py

• Task 1.2: Create Alembic migration

  • Generate migration for tool_instances table
  • Add indexes for owner_id, repository_id, status

Phase 2: Backend Docker Service

• Task 2.1: Create Docker service

  • Create src/services/docker.py
  • Function: render_compose_template(template, variables)
  • Function: execute_compose_command(compose_path, action)
  • Function: get_container_status(container_id)
  • Function: get_container_logs(container_id, tail=100)
  • Error handling and cleanup

• Task 2.2: Create instance directory structure

  • Base path: data/instances/{instance_id}/
  • Render compose file to docker-compose.yml
  • Ensure directory exists and is writable

Phase 3: Backend API

• Task 3.1: Create instances API module

  • Create src/api/tool_instances.py
  • Import required dependencies

• Task 3.2: Implement create instance endpoint

  • POST /projects/{id}/repositories/{id}/instances
  • Validate tool_type_id exists
  • Generate unique instance name
  • Render compose template
  • Save to database (status: pending)
  • Return instance metadata

• Task 3.3: Implement list instances endpoint

  • GET /projects/{id}/repositories/{id}/instances
  • Filter by repository
  • Include tool type info

• Task 3.4: Implement get instance endpoint

  • GET /projects/{id}/repositories/{id}/instances/{id}
  • Include real-time status from Docker

• Task 3.5: Implement lifecycle endpoints

  • POST .../start - execute docker compose up
  • POST .../stop - execute docker compose stop
  • POST .../restart - execute docker compose restart
  • Update status in database

• Task 3.6: Implement delete instance endpoint

  • DELETE /projects/{id}/repositories/{id}/instances/{id}
  • Execute docker compose down -v
  • Remove instance directory
  • Delete database record

• Task 3.7: Implement user sessions endpoint

  • GET /users/me/sessions
  • Return all running instances for current user
  • Include tool type icon and names

• Task 3.8: Register router

  • Add tool_instances router to main.py

Phase 4: Frontend State Management

• Task 4.1: Create session store

  • Create src/state/sessions.ts
  • Define Session interface
  • Create atom for sessions list
  • Add helper functions

• Task 4.2: Create sessions API client

  • Create src/api/sessions.ts
  • Functions: list, create, start, stop, restart, delete, getStatus
  • TypeScript interfaces

Phase 5: Frontend Components

• Task 5.1: Update AppShell with sessions

  • Add "Sessions" section in navigation
  • Show active sessions with icons
  • Status indicators (green dot)
  • Click opens tool URL

• Task 5.2: Create LaunchToolDialog

  • Select tool type from dropdown
  • Enter display name (optional)
  • Create instance on submit
  • Show creation progress

• Task 5.3: Create InstanceList component

  • List instances for a repository
  • Show status, name, tool type
  • Action buttons: start/stop/restart/delete
  • Open URL button

• Task 5.4: Create InstanceCard component

  • Compact card showing instance info
  • Status badge
  • Quick actions

Phase 6: Frontend Pages

• Task 6.1: Add instances to repository page

  • Add "Instances" tab or section
  • Show InstanceList
  • Add "Launch Tool" button

• Task 6.2: Create sessions dropdown

  • Add to header or nav
  • Quick access to active sessions
  • Show status indicators

Phase 7: Integration & Polish

• Task 7.1: Add instance status polling

  • Poll status every 5 seconds
  • Update session store
  • Reflect in UI

• Task 7.2: Add error handling

  • Docker failures
  • Template rendering errors
  • Network errors

• Task 7.3: Add loading states

  • Creating instance
  • Starting/stopping
  • Deleting

Phase 8: Quality Gates

• Task 8.1: Backend tests

  • ruff check
  • mypy check
  • pytest

• Task 8.2: Frontend tests

  • typecheck
  • lint
  • build

• Task 8.3: Manual testing

  • Create instance
  • Start/stop/restart
  • Delete
  • Navigation updates
  • Status polling