# 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.

#### 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: Log Access

The system SHALL provide access to container logs.

#### 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

## Dependencies

- tool-types (tool definitions)
- git-repo (repository access)
- project-management (project context)
- Docker runtime
- Traefik reverse proxy

## Quality Gates

- `pytest` must pass
- `mypy .` must pass
- `ruff check .` must pass
- `npm run typecheck` must pass
- `npm run lint` must pass