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

## Phase 1: Backend Foundation

### 1.1 Database Migrations
- [x] 1.1.1 Create Alembic migration for `tool_types` (add definition_type, dockerfile_template, build_context, readiness_probe)
- [x] 1.1.2 Create Alembic migration for `tool_configs` (add port_override, start_command, working_directory, environment_variables, volumes)
- [x] 1.1.3 Create Alembic migration for `config_folders` (new table)
- [x] 1.1.4 Add CHECK constraints (definition_type enum, port range)
- [x] 1.1.5 Add indexes for config_folders
- [ ] 1.1.6 Run migrations locally and verify with test data

### 1.2 Model Updates
- [x] 1.2.1 Update `ToolType` model with new fields
- [x] 1.2.2 Update `ToolConfig` model with new fields
- [x] 1.2.3 Create `ConfigFolder` model
- [x] 1.2.4 Add Pydantic schemas for ConfigFolder (create, update, response)
- [x] 1.2.5 Update Pydantic schemas for ToolType (add new fields)
- [x] 1.2.6 Update Pydantic schemas for ToolConfig (add new fields)
- [x] 1.2.7 Add validation schemas (port range, JSON structure, definition_type enum)

### 1.3 Config Folder API
- [x] 1.3.1 Create `api/config_folders.py` router
- [x] 1.3.2 Implement `GET /config-folders` (list with filtering by project)
- [x] 1.3.3 Implement `POST /config-folders` (create)
- [x] 1.3.4 Implement `PUT /config-folders/{id}` (update name, mount_path, files)
- [x] 1.3.5 Implement `DELETE /config-folders/{id}` (delete)
- [x] 1.3.6 Implement `POST /config-folders/{id}/overrides` (add project override)
- [x] 1.3.7 Implement `PUT /config-folders/{id}/overrides/{project_id}` (update override)
- [x] 1.3.8 Implement `DELETE /config-folders/{id}/overrides/{project_id}` (remove override)
- [x] 1.3.9 Add validation: 10MB size limit per folder
- [x] 1.3.10 Add ownership checks (user can only access own folders)

### 1.4 Tool Type API Updates
- [x] 1.4.1 Update `POST /tool-types` to accept definition_type, dockerfile_template, build_context, readiness_probe
- [x] 1.4.2 Update `PUT /tool-types/{id}` to handle new fields
- [ ] 1.4.3 Add `GET /tool-types/{id}/validate` endpoint (syntax validation)
- [x] 1.4.4 Update tool type response schemas
- [x] 1.4.5 Update seed function to set definition_type="compose" for built-in types

### 1.5 Tool Config API Updates
- [x] 1.5.1 Update `POST /tool-configs` to accept new fields
- [x] 1.5.2 Update `PUT /tool-configs/{id}` to handle new fields
- [x] 1.5.3 Update `GET /tool-configs` to return new fields
- [x] 1.5.4 Add `GET /tool-configs/defaults/{tool_type_id}` endpoint
- [x] 1.5.5 Add validation for port_override range
- [x] 1.5.6 Add validation for environment_variables JSON structure
- [x] 1.5.7 Add validation for volumes JSON structure (source/target/type)

## Phase 2: Instance Creation Enhancement

### 2.1 Docker Build Service
- [ ] 2.1.1 Create `services/docker_build.py` for Dockerfile builds
- [ ] 2.1.2 Implement `build_image(instance_dir, dockerfile, tag)` function
- [ ] 2.1.3 Handle build context file writing
- [ ] 2.1.4 Add build output streaming/logging
- [ ] 2.1.5 Handle build failures with clear error messages

### 2.2 Compose Generation for Dockerfile Tools
- [ ] 2.2.1 Create compose template for dockerfile-built images
- [ ] 2.2.2 Integrate build service into instance creation flow
- [ ] 2.2.3 Update `render_compose_template` to handle both paths

### 2.3 Config Folder Mounting
- [ ] 2.3.1 Implement `write_config_folder_files(instance_dir, folders)` function
- [ ] 2.3.2 Resolve config folders for user + project
- [ ] 2.3.3 Generate volume mounts in compose file for config folders
- [ ] 2.3.4 Apply project overrides during resolution
- [ ] 2.3.5 Write config folder files to `instance_dir/volumes/`

### 2.4 Readiness Probe Service
- [ ] 2.4.1 Create `services/readiness_probe.py`
- [ ] 2.4.2 Implement `execute_probe(container_id, probe_config)` function
- [ ] 2.4.3 Implement polling loop with timeout and interval
- [ ] 2.4.4 Store probe output/logs on instance
- [ ] 2.4.5 Update instance status based on probe result ("running" or "failed")
- [ ] 2.4.6 Handle probe command failures gracefully

### 2.5 Instance Creation Integration
- [ ] 2.5.1 Update `create_instance` endpoint to use new fields
- [ ] 2.5.2 Integrate dockerfile build path into creation flow
- [ ] 2.5.3 Integrate config folder mounting
- [ ] 2.5.4 Integrate readiness probe execution
- [ ] 2.5.5 Apply port_override if specified
- [ ] 2.5.6 Apply start_command if specified
- [ ] 2.5.7 Apply working_directory if specified
- [ ] 2.5.8 Apply environment_variables from ToolConfig
- [ ] 2.5.9 Apply volumes from ToolConfig
- [ ] 2.5.10 Test end-to-end instance creation with all new features

## Phase 3: Frontend UI

### 3.1 API Client Updates
- [ ] 3.1.1 Update `api/tool_types.ts` with new fields and endpoints
- [ ] 3.1.2 Update `api/tool_configs.ts` with new fields
- [ ] 3.1.3 Create `api/config_folders.ts` with all CRUD operations
- [ ] 3.1.4 Update TypeScript types/interfaces

### 3.2 Tool Workshop Layout
- [ ] 3.2.1 Create `pages/tool-workshop.tsx` (replaces tool-configs and tool-types)
- [ ] 3.2.2 Implement split-pane layout (sidebar + main content)
- [ ] 3.2.3 Create sidebar navigation tree (Tool Types / Config Folders)
- [ ] 3.2.4 Implement tab switching (Tool Types / Configs / Config Folders)
- [ ] 3.2.5 Add responsive design (collapsible sidebar on mobile)
- [ ] 3.2.6 Update App.tsx routing

### 3.3 Tool Type Builder
- [ ] 3.3.1 Create `components/ToolTypeBuilder.tsx`
- [ ] 3.3.2 Implement definition type selector (Compose vs Dockerfile)
- [ ] 3.3.3 Create compose template editor (textarea with YAML highlighting)
- [ ] 3.3.4 Create dockerfile editor (textarea with Dockerfile highlighting)
- [ ] 3.3.5 Add build context file manager
- [ ] 3.3.6 Add readiness probe configuration (command, timeout, interval)
- [ ] 3.3.7 Add validation feedback (syntax check)
- [ ] 3.3.8 Implement create/update/delete operations

### 3.4 Config Editor Enhancement
- [ ] 3.4.1 Update config form with new fields
- [ ] 3.4.2 Add port override input (integer, 1-65535)
- [ ] 3.4.3 Add start command input
- [ ] 3.4.4 Add working directory input
- [ ] 3.4.5 Create environment variables editor (key-value table)
- [ ] 3.4.6 Create volumes editor (source/target/type table)
- [ ] 3.4.7 Add JSON validation for env vars and volumes
- [ ] 3.4.8 Implement tabbed sections (Basic / Runtime / Advanced)

### 3.5 Config Folder Manager
- [ ] 3.5.1 Create `components/ConfigFolderManager.tsx`
- [ ] 3.5.2 Implement folder list view
- [ ] 3.5.3 Create folder editor (name, description, mount_path)
- [ ] 3.5.4 Create file manager (add/edit/delete files with path and content)
- [ ] 3.5.5 Implement file content editor (textarea with syntax highlighting)
- [ ] 3.5.6 Create project override manager
- [ ] 3.5.7 Add active/inactive toggle
- [ ] 3.5.8 Show folder size indicator

### 3.6 Navigation Updates
- [ ] 3.6.1 Update header/navigation to link to `/tool-workshop`
- [ ] 3.6.2 Remove old `/tool-configs` and `/tool-types` routes (or redirect)
- [ ] 3.6.3 Update breadcrumb navigation if applicable

## Phase 4: Integration & Testing

### 4.1 Backend Testing
- [ ] 4.1.1 Test config folder CRUD operations
- [ ] 4.1.2 Test config folder project overrides
- [ ] 4.1.3 Test tool type creation with dockerfile
- [ ] 4.1.4 Test tool type creation with compose
- [ ] 4.1.5 Test readiness probe execution (success case)
- [ ] 4.1.6 Test readiness probe execution (timeout case)
- [ ] 4.1.7 Test instance creation with config folders mounted
- [ ] 4.1.8 Test instance creation with port override
- [ ] 4.1.9 Test instance creation with volumes
- [ ] 4.1.10 Test 10MB size limit enforcement

### 4.2 Frontend Testing
- [ ] 4.2.1 Test Tool Workshop page load
- [ ] 4.2.2 Test tool type creation flow
- [ ] 4.2.3 Test config folder creation and file management
- [ ] 4.2.4 Test config editor with all new fields
- [ ] 4.2.5 Test responsive layout on mobile
- [ ] 4.2.6 Test form validation (port range, JSON structure)

### 4.3 End-to-End Testing
- [ ] 4.3.1 Create a new tool type with dockerfile, start instance
- [ ] 4.3.2 Create a new tool type with compose, start instance
- [ ] 4.3.3 Create config folder, mount into instance, verify files present
- [ ] 4.3.4 Add project override, verify different files in different projects
- [ ] 4.3.5 Test readiness probe with failing command (should mark failed)
- [ ] 4.3.6 Test readiness probe with succeeding command (should mark running)

### 4.4 Quality Gates
- [ ] 4.4.1 Run backend linting (ruff)
- [ ] 4.4.2 Run backend type checking (mypy)
- [ ] 4.4.3 Run frontend type checking (tsc)
- [ ] 4.4.4 Run frontend linting (eslint)
- [ ] 4.4.5 Build frontend and verify no errors
- [ ] 4.4.6 Run existing tests to ensure no regressions
- [ ] 4.4.7 Verify backward compatibility (existing instances still work)

## Phase 5: Documentation & Deployment

### 5.1 Documentation
- [ ] 5.1.1 Update API documentation (OpenAPI/Swagger annotations)
- [ ] 5.1.2 Add tool workshop user guide
- [ ] 5.1.3 Document config folder usage
- [ ] 5.1.4 Document readiness probe configuration
- [ ] 5.1.5 Add example dockerfile and compose templates

### 5.2 Migration & Deployment
- [ ] 5.2.1 Verify database migrations run cleanly on existing data
- [ ] 5.2.2 Update seed data for built-in tool types (add definition_type)
- [ ] 5.2.3 Test fresh install (no existing data)
- [ ] 5.2.4 Commit all changes with conventional commit messages
- [ ] 5.2.5 Create comprehensive PR description

## Quality Gates Summary

**Before completing this change:**
- All migrations must run successfully
- Backend linting and type checking must pass
- Frontend build must succeed with no errors
- All new API endpoints must be tested
- At least one end-to-end test for each new feature
- No regressions in existing instance creation flow
- Documentation updated