merge: align dev branch with main

2026-06-03 08:51:02 +00:00
parent 51a399c775
commit b39d6ce5f4
319 changed files with 30221 additions and 9221 deletions
@@ -0,0 +1,96 @@
+# Capability: Tool Workshop
+
+## Overview
+
+The Tool Workshop is the unified interface for defining, configuring, and managing development tools. It consolidates tool type management, tool configuration, and config folder management into a single powerful interface.
+
+## Functional Requirements
+
+### FR-1: Tool Type Definition
+- Users can create new tool types with either Docker Compose or Dockerfile
+- Tool types specify: name, display name, description, category, interfaces, port, definition type, template
+- Built-in tool types can be viewed but not edited
+- Tool types can be deleted (with cascade deletion of associated configs)
+
+### FR-2: Tool Configuration
+- Users can create tool configurations per tool type
+- Configs can be global (all projects) or project-scoped
+- Configs support: key-value pairs (env/file), port override, start command, working directory, environment variables, volumes
+- Configs are mounted into containers when instances are created
+
+### FR-3: Config Folder Management
+- Users can create named collections of configuration files
+- Each folder has a default mount path in containers
+- Folders can be activated/deactivated
+- Folders support per-project overrides
+- Active folders are automatically mounted into new instances
+
+### FR-4: Readiness Probes
+- Tool types can define a readiness probe command
+- Instance creation waits for the probe to succeed
+- Probes have configurable timeout and check interval
+- Failed probes mark instances as "failed" with logs
+
+### FR-5: Instance Integration
+- Instance creation uses tool type definition (compose or dockerfile)
+- Instance creation applies tool configs (env vars, files, volumes)
+- Instance creation mounts active config folders
+- Instance creation executes readiness probe
+- Instance status reflects probe result
+
+## Non-Functional Requirements
+
+### NFR-1: Performance
+- Tool Workshop page loads in < 2 seconds
+- Config folder operations complete in < 500ms
+- Instance creation with dockerfile build completes in < 5 minutes
+
+### NFR-2: Usability
+- UI is intuitive for both technical and non-technical users
+- Clear validation messages for all fields
+- Progressive disclosure of advanced options
+- Responsive design for mobile devices
+
+### NFR-3: Security
+- Users can only access their own tool types, configs, and folders
+- File paths in config folders are sanitized (no path traversal)
+- Dockerfile builds run in isolated context
+- Config values are never logged or exposed
+
+## State Diagram
+
+```
+┌─────────────┐
+│   DRAFT     │
+└──────┬──────┘
+       │ Create
+       ▼
+┌─────────────┐     Edit     ┌─────────────┐
+│   ACTIVE    │◀────────────▶│   UPDATED   │
+└──────┬──────┘              └─────────────┘
+       │
+       │ Delete
+       ▼
+┌─────────────┐
+│  DELETED    │
+└─────────────┘
+```
+
+## API Specification
+
+See `design.md` for complete endpoint list.
+
+## UI Specification
+
+See `design.md` for complete UI mockups.
+
+## Acceptance Criteria
+
+- [ ] User can create a tool type with dockerfile and start an instance
+- [ ] User can create a tool type with compose and start an instance
+- [ ] User can create config folders and mount them into instances
+- [ ] User can set project overrides on config folders
+- [ ] Readiness probes wait for tools to be ready before marking running
+- [ ] Failed readiness probes show clear error messages
+- [ ] All new fields are persisted and retrieved correctly
+- [ ] UI is responsive and intuitive