chore: archive tool-types-definition change
This commit is contained in:
Fusion
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-18
|
||||
@@ -0,0 +1,57 @@
|
||||
## Context
|
||||
|
||||
Tool instances (like VS Code Server, Jupyter notebooks) need a type system to define what development tools can be launched. The current system has projects and repositories but no way to define what tools can run against them. Tool types will provide Docker Compose templates that can be instantiated with project-specific variables.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Create a `ToolType` model to store tool definitions with Docker Compose templates
|
||||
- Provide CRUD API endpoints for tool type management
|
||||
- Implement template variable substitution (e.g., `{{REPO_PATH}}`, `{{PROJECT_NAME}}`)
|
||||
- Include built-in tool types (code-server, jupyter-notebook)
|
||||
- Validate Docker Compose templates on creation/update
|
||||
|
||||
**Non-Goals:**
|
||||
- Actually launching/running tool instances (that's a separate feature)
|
||||
- Complex template logic (loops, conditionals) - simple variable substitution only
|
||||
- Tool type versioning or history
|
||||
|
||||
## Decisions
|
||||
|
||||
1. **Store Docker Compose templates as YAML strings in the database**
|
||||
- Rationale: Flexibility - templates can contain any valid Docker Compose config
|
||||
- Alternative: Normalized table structure. Rejected because Compose configs are too varied.
|
||||
|
||||
2. **Use Jinja2-style variable substitution with double braces `{{VAR}}`**
|
||||
- Rationale: Familiar syntax, easy to parse
|
||||
- Variables: `{{REPO_PATH}}`, `{{PROJECT_NAME}}`, `{{USER_ID}}`, `{{TOOL_NAME}}`
|
||||
|
||||
3. **Built-in tool types seeded on first startup**
|
||||
- Rationale: Users should have common tools available immediately
|
||||
- Can be disabled via env var if desired
|
||||
|
||||
4. **Simple validation: check template is valid YAML with required variables**
|
||||
- Rationale: Full Docker Compose validation is complex and error-prone
|
||||
- We validate structure and required vars, not runtime behavior
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Invalid templates]** → Validation catches YAML syntax errors and missing required vars
|
||||
- **[Template injection]** → Only admin users can create/edit tool types
|
||||
- **[Storage size]** → Templates are small YAML files, negligible impact
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Create `tool_types` table via Alembic migration
|
||||
2. Add API module for CRUD operations
|
||||
3. Add frontend page for management
|
||||
4. Seed built-in types on startup
|
||||
|
||||
Rollback:
|
||||
- Drop `tool_types` table
|
||||
- Remove API endpoints
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should tool types be global or per-user?
|
||||
- Decision: Global with admin-only creation, users can view all
|
||||
@@ -0,0 +1,23 @@
|
||||
## Why
|
||||
|
||||
Tool instances require a type system to define what development tools can be launched. Without tool types, users cannot create instances of VS Code Server, Jupyter notebooks, or other dev environments from their repositories.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add `ToolType` SQLAlchemy model with Docker Compose template support
|
||||
- Add CRUD API endpoints for tool type management
|
||||
- Implement template variable substitution (`{{REPO_PATH}}`, etc.)
|
||||
- Add built-in tool types (code-server, jupyter-notebook, opencode)
|
||||
- Validate Docker Compose templates on creation/update
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `tool-types-definition`: Define and manage tool types with Docker Compose templates
|
||||
|
||||
## Impact
|
||||
|
||||
- New database table: tool_types
|
||||
- New API module: apps/api/src/api/tool_types.py
|
||||
- New frontend page: apps/web/src/pages/tool-types.tsx
|
||||
- Database migration required
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tool Type Model
|
||||
|
||||
The system SHALL provide a `ToolType` model to store tool definitions.
|
||||
|
||||
#### Scenario: Model structure
|
||||
- GIVEN a tool type definition
|
||||
- THEN the model SHALL have:
|
||||
- `id`: UUID primary key
|
||||
- `name`: unique string (e.g., "code-server")
|
||||
- `display_name`: human-readable string (e.g., "VS Code Server")
|
||||
- `description`: optional text
|
||||
- `compose_template`: Docker Compose YAML string
|
||||
- `required_variables`: list of required template variables
|
||||
- `is_builtin`: boolean flag for system-defined types
|
||||
- `created_at`/`updated_at`: timestamps
|
||||
|
||||
### Requirement: CRUD API Endpoints
|
||||
|
||||
The system SHALL provide REST API endpoints for tool type management.
|
||||
|
||||
#### Scenario: List tool types
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they GET /api/tool-types
|
||||
- THEN the system returns all tool types (built-in and custom)
|
||||
- AND returns 200 OK
|
||||
|
||||
#### Scenario: Create tool type
|
||||
- GIVEN an admin user
|
||||
- WHEN they POST /api/tool-types with valid data
|
||||
- THEN the system creates a new tool type
|
||||
- AND validates the compose template YAML
|
||||
- AND validates all required variables are present in template
|
||||
- AND returns 201 Created with the new tool type
|
||||
|
||||
#### Scenario: Get tool type
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they GET /api/tool-types/{id}
|
||||
- THEN the system returns the tool type details
|
||||
- AND returns 200 OK
|
||||
|
||||
#### Scenario: Update tool type
|
||||
- GIVEN an admin user
|
||||
- WHEN they PUT /api/tool-types/{id} with valid data
|
||||
- THEN the system updates the tool type
|
||||
- AND re-validates the compose template
|
||||
- AND returns 200 OK with updated tool type
|
||||
|
||||
#### Scenario: Delete tool type
|
||||
- GIVEN an admin user
|
||||
- WHEN they DELETE /api/tool-types/{id}
|
||||
- THEN the system deletes the tool type
|
||||
- AND prevents deletion of built-in types
|
||||
- AND returns 204 No Content
|
||||
|
||||
### Requirement: Template Variable Substitution
|
||||
|
||||
The system SHALL support variable substitution in Docker Compose templates.
|
||||
|
||||
#### Scenario: Supported variables
|
||||
- GIVEN a compose template with variables
|
||||
- THEN the system SHALL support:
|
||||
- `{{REPO_PATH}}` - absolute path to repository
|
||||
- `{{PROJECT_NAME}}` - project name
|
||||
- `{{USER_ID}}` - user's UUID
|
||||
- `{{TOOL_NAME}}` - tool instance name
|
||||
|
||||
#### Scenario: Variable validation
|
||||
- GIVEN a new tool type with required variables
|
||||
- WHEN the template is created or updated
|
||||
- THEN the system validates all required variables exist in the template
|
||||
- AND returns 400 Bad Request if variables are missing
|
||||
|
||||
### Requirement: Built-in Tool Types
|
||||
|
||||
The system SHALL seed common tool types on first startup.
|
||||
|
||||
#### Scenario: Default tool types
|
||||
- GIVEN a fresh database
|
||||
- WHEN the application starts
|
||||
- THEN the system creates built-in tool types:
|
||||
- code-server (VS Code in browser)
|
||||
- jupyter-notebook (Jupyter Lab)
|
||||
|
||||
### Requirement: Compose Template Validation
|
||||
|
||||
The system SHALL validate Docker Compose templates.
|
||||
|
||||
#### Scenario: YAML validation
|
||||
- GIVEN a compose template string
|
||||
- WHEN creating or updating a tool type
|
||||
- THEN the system parses the YAML
|
||||
- AND returns 400 Bad Request if YAML is invalid
|
||||
|
||||
#### Scenario: Required structure
|
||||
- GIVEN a valid YAML compose template
|
||||
- THEN the system SHALL require:
|
||||
- `services` key present
|
||||
- At least one service defined
|
||||
@@ -0,0 +1,33 @@
|
||||
## 1. Database Model and Migration
|
||||
|
||||
- [x] 1.1 Create `ToolType` SQLAlchemy model in `apps/api/src/models/tool_type.py`
|
||||
- [x] 1.2 Add `ToolType` import to `apps/api/src/models/__init__.py`
|
||||
- [x] 1.3 Create Alembic migration for `tool_types` table
|
||||
- [x] 1.4 Run migration and verify table creation
|
||||
|
||||
## 2. Backend API
|
||||
|
||||
- [x] 2.1 Create `apps/api/src/api/tool_types.py` with CRUD endpoints
|
||||
- [x] 2.2 Add Pydantic schemas for tool type request/response
|
||||
- [x] 2.3 Implement YAML validation for compose templates
|
||||
- [x] 2.4 Implement variable validation (check required vars in template)
|
||||
- [x] 2.5 Add admin authorization checks for create/update/delete
|
||||
- [x] 2.6 Register router in `apps/api/src/main.py`
|
||||
- [x] 2.7 Add built-in tool type seeding on startup
|
||||
|
||||
## 3. Frontend
|
||||
|
||||
- [x] 3.1 Create API client in `apps/web/src/api/tool_types.ts`
|
||||
- [x] 3.2 Create `apps/web/src/pages/tool-types.tsx` with list view
|
||||
- [x] 3.3 Add create/edit form for tool types (admin only)
|
||||
- [x] 3.4 Add delete confirmation dialog
|
||||
- [x] 3.5 Add route to router
|
||||
- [x] 3.6 Add navigation link in app shell
|
||||
|
||||
## 4. Verification and Testing
|
||||
|
||||
- [x] 4.1 Run backend quality gates (`pytest`, `ruff`, `mypy`)
|
||||
- [x] 4.2 Run frontend quality gates (`npm test`, `typecheck`, `lint`, `build`)
|
||||
- [x] 4.3 Test CRUD operations manually
|
||||
- [x] 4.4 Verify built-in types are seeded
|
||||
- [x] 4.5 Update this tasks file with completed checkboxes
|
||||
Reference in New Issue
Block a user