merge: align dev branch with main

openspec/specs/tool-types/spec.md

@@ -1,8 +1,14 @@
-## MODIFIED Requirements
+# Tool Type Definition Specification
+
+## Purpose
+
+Define and register tool types using Docker Compose templates for launching development tools.
+
+## Requirements
 
 ### Requirement: Tool Type Model
 
-The system SHALL store tool type definitions in the database without built-in vs custom distinction.
+The system SHALL store tool type definitions in the database.
 
 #### Scenario: Create tool type
 - GIVEN an admin user
@@ -14,18 +20,32 @@ The system SHALL store tool type definitions in the database without built-in vs
   - icon: Visual identifier
   - category: Tool category
   - default_env_vars: Default environment variables
-  - default_port: **Required** primary port the tool listens on
-  - interfaces: List of supported interfaces ("web", "terminal")
+  - default_ports: Exposed ports
 
-#### Scenario: Tool type without port rejected
-- GIVEN a user creating a tool type without `default_port`
-- WHEN the request is submitted
-- THEN the system rejects with a 422 validation error
+### Requirement: Template Variables
+
+The system SHALL support template variable substitution.
+
+#### Scenario: Variable substitution
+- GIVEN a Docker Compose template
+- WHEN it's rendered for a tool instance
+- THEN these variables are substituted:
+  - `{{REPO_PATH}}`: Path to the git repository
+  - `{{WORKSPACE_DIR}}`: Working directory inside container
+  - `{{USER_ID}}`: User identifier
+  - `{{PROJECT_ID}}`: Project identifier
+  - `{{TOOL_ID}}`: Tool instance identifier
 
 ### Requirement: Built-in Tools
 
-**Reason**: Built-in tools are now regular preconfigured tool types in the database, not special privileged types.
-**Migration**: Built-in tool types (code-server, jupyter-notebook, opencode) are seeded as regular database records during migration. They can be edited or deleted like any other tool type.
+The system SHALL include default tool types.
+
+#### Scenario: Built-in tools
+- GIVEN a fresh installation
+- THEN these tool types are pre-configured:
+  - code-server: VS Code in browser
+  - jupyter-notebook: Jupyter notebooks
+  - opencode: OpenCode agent environment
 
 ### Requirement: Template Validation
 
@@ -36,7 +56,12 @@ The system SHALL validate Docker Compose templates.
 - WHEN a user tries to create/update a tool type
 - THEN the system rejects with validation errors
 
-#### Scenario: Port not exposed in template
-- GIVEN a tool type with `default_port: 8443`
-- WHEN the compose template does not expose port 8443
-- THEN the system rejects with a validation error indicating the port mismatch
+## Dependencies
+
+- Database models: ToolType
+
+## Quality Gates
+
+- `pytest` must pass
+- `mypy .` must pass
+- `ruff check .` must pass