# 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