merge: align dev branch with main
This commit is contained in:
Developer
@@ -1,95 +1,90 @@
|
||||
## MODIFIED Requirements
|
||||
# Tool Instance Management Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Launch, monitor, and manage development tool instances in Docker containers.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Tool Instance Creation
|
||||
|
||||
The system SHALL create and launch tool instances from repositories.
|
||||
|
||||
#### Scenario: Launch tool
|
||||
- GIVEN an authenticated user with a project and repository
|
||||
- WHEN they create a tool instance
|
||||
- THEN:
|
||||
1. A unique subdomain is generated: `{tool-name}-{tool-id}.hq.local`
|
||||
2. The Docker Compose template is rendered with project values
|
||||
3. `docker compose up -d` is executed
|
||||
4. Container ID and status are stored
|
||||
|
||||
### Requirement: Tool Lifecycle
|
||||
|
||||
The system SHALL manage tool lifecycle operations.
|
||||
|
||||
#### Scenario: Stop tool
|
||||
- GIVEN a running tool instance
|
||||
- WHEN the user stops it
|
||||
- THEN `docker compose stop` is executed
|
||||
- AND status is updated to "stopped"
|
||||
|
||||
#### Scenario: Start tool
|
||||
- GIVEN a stopped tool instance
|
||||
- WHEN the user starts it
|
||||
- THEN `docker compose start` is executed
|
||||
- AND status is updated to "running"
|
||||
|
||||
#### Scenario: Delete tool
|
||||
- GIVEN a tool instance
|
||||
- WHEN the user deletes it
|
||||
- THEN the container and volumes are removed
|
||||
- AND the database record is deleted
|
||||
|
||||
### Requirement: Traefik Integration
|
||||
|
||||
The system SHALL auto-generate Traefik labels for routing.
|
||||
|
||||
#### Scenario: Route generation
|
||||
- GIVEN a running tool instance
|
||||
- THEN these labels are set:
|
||||
- `traefik.enable=true`
|
||||
- `traefik.http.routers.{tool_id}.rule=Host(\`{subdomain}.hq.local\`)`
|
||||
- `traefik.http.routers.{tool_id}.entrypoints=web`
|
||||
- `traefik.http.services.{tool_id}.loadbalancer.server.port={port}`
|
||||
|
||||
### Requirement: Status Monitoring
|
||||
The system SHALL track tool status with startup and health states.
|
||||
|
||||
#### Scenario: Status check with health details
|
||||
- **GIVEN** a tool instance
|
||||
- **WHEN** status is queried
|
||||
- **THEN** the real-time container status is returned:
|
||||
- `pending`: Instance created, container not yet started
|
||||
- `starting`: Container is running, readiness probe in progress
|
||||
- `running`: Container is running and probe passed (or terminal tool)
|
||||
- `unhealthy`: Container is running but probe failed/timed out
|
||||
- `stopped`: Container was stopped by user
|
||||
- `error`: Container failed to start or crashed
|
||||
The system SHALL track tool status.
|
||||
|
||||
## ADDED Requirements
|
||||
#### Scenario: Status check
|
||||
- GIVEN a tool instance
|
||||
- WHEN status is queried
|
||||
- THEN the real-time container status is returned:
|
||||
- pending, building, running, stopped, error
|
||||
|
||||
### Requirement: Health check endpoint enhancement
|
||||
The system SHALL provide detailed health information through the health check endpoint.
|
||||
### Requirement: Log Access
|
||||
|
||||
#### Scenario: Health check with container and tunnel status
|
||||
- **GIVEN** a running instance
|
||||
- **WHEN** `GET /instances/{id}/health` is called
|
||||
- **THEN** the response includes:
|
||||
- `healthy`: boolean - overall health
|
||||
- `container_status`: "running", "exited", "restarting", or "not_found"
|
||||
- `tunnel_status`: "healthy", "unreachable", "error_response", or "not_applicable"
|
||||
- `tunnel_status_code`: HTTP status code or null
|
||||
- `probe_status`: "passed", "failed", "pending", or "not_configured"
|
||||
- `last_probe_output`: string or null
|
||||
The system SHALL provide access to container logs.
|
||||
|
||||
### Requirement: Smart tunnel recreation
|
||||
The system SHALL only allow tunnel recreation when the tunnel itself is broken.
|
||||
#### Scenario: View logs
|
||||
- GIVEN a tool instance
|
||||
- WHEN logs are requested
|
||||
- THEN the last 100 lines are returned
|
||||
- AND live streaming is available via WebSocket
|
||||
|
||||
#### Scenario: Recreate tunnel for unreachable tunnel
|
||||
- **GIVEN** an instance with `tunnel_status: "unreachable"`
|
||||
- **WHEN** the recreate tunnel endpoint is called
|
||||
- **THEN** the tunnel is recreated
|
||||
- **AND** the new URL is returned
|
||||
## Dependencies
|
||||
|
||||
#### Scenario: Block recreation for application errors
|
||||
- **GIVEN** an instance with `tunnel_status: "error_response"` (e.g., HTTP 502)
|
||||
- **WHEN** the recreate tunnel endpoint is called
|
||||
- **THEN** the request is rejected with 400 Bad Request
|
||||
- **AND** the error message explains the tunnel is working but the application is returning errors
|
||||
- tool-types (tool definitions)
|
||||
- git-repo (repository access)
|
||||
- project-management (project context)
|
||||
- Docker runtime
|
||||
- Traefik reverse proxy
|
||||
|
||||
### Requirement: Clone mode instance creation
|
||||
The system SHALL support creating tool instances with a clone mode that clones the repository into the instance directory.
|
||||
## Quality Gates
|
||||
|
||||
#### Scenario: Create instance in clone mode
|
||||
- **GIVEN** an authenticated user with a repository that has an SSH key and remote URL
|
||||
- **WHEN** they create an instance with `clone_mode: "clone"` and `branch: "main"`
|
||||
- **THEN** the system clones the repository into the instance directory
|
||||
- **AND** the compose file uses the clone path as `REPO_PATH`
|
||||
- **AND** the instance record stores `clone_mode="clone"` and `branch="main"`
|
||||
|
||||
#### Scenario: Create instance in mount mode
|
||||
- **GIVEN** an authenticated user with a repository
|
||||
- **WHEN** they create an instance with `clone_mode: "mount"` (or omit the field)
|
||||
- **THEN** the compose file uses the host repository path as `REPO_PATH`
|
||||
- **AND** the instance record stores `clone_mode="mount"`
|
||||
|
||||
### Requirement: SSH key mounting for git operations
|
||||
The system SHALL mount the repository's SSH key into clone-mode containers for git operations.
|
||||
|
||||
#### Scenario: Start clone-mode instance
|
||||
- **GIVEN** a clone-mode instance with an associated SSH key
|
||||
- **WHEN** the instance is started
|
||||
- **THEN** the SSH key is decrypted and written to `instance_dir/.ssh/`
|
||||
- **AND** the `.ssh` directory is mounted into the container
|
||||
- **AND** the container can perform git push/pull operations
|
||||
|
||||
### Requirement: Dirty check on clone deletion
|
||||
The system SHALL check for uncommitted changes before deleting a clone-mode instance.
|
||||
|
||||
#### Scenario: Delete clean clone
|
||||
- **GIVEN** a clone-mode instance with no uncommitted changes
|
||||
- **WHEN** the user requests deletion
|
||||
- **THEN** the instance is deleted successfully
|
||||
|
||||
#### Scenario: Delete dirty clone with confirmation
|
||||
- **GIVEN** a clone-mode instance with uncommitted changes
|
||||
- **WHEN** the user requests deletion
|
||||
- **THEN** the system returns a warning with change details
|
||||
- **AND** the user must confirm deletion
|
||||
|
||||
#### Scenario: Force delete dirty clone
|
||||
- **GIVEN** a clone-mode instance with uncommitted changes
|
||||
- **WHEN** the user requests deletion with `force=true`
|
||||
- **THEN** the instance is deleted regardless of uncommitted changes
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
None.
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
|
||||
Reference in New Issue
Block a user