fix: disable native touch panning on mobile terminal and archive specs
- Change mobile terminal CSS to use touch-action: none and overscroll-behavior: none so the custom touch handler owns swipes - Archive completed/partial OpenSpec specs to openspec/changes/archive/2026-06-14-completed-specs-archive/ - Regenerate project maps Quality gates: npm run typecheck, npm run lint (apps/web)
This commit is contained in:
Developer
@@ -1,114 +1,13 @@
|
||||
# openspec/specs (index)
|
||||
dir: openspec/specs
|
||||
# specs (index)
|
||||
dir: specs
|
||||
|
||||
## role
|
||||
Contains formal specification documents defining requirements, APIs, algorithms, and test strategies for core platform features across configuration management, container orchestration, terminal I/O, and tool definition systems.
|
||||
Defines formal specifications and requirements for core system features including container configuration, terminal I/O, and build tooling.
|
||||
## parent
|
||||
index: openspec/.pi-map.index.md
|
||||
map: openspec/.pi-map.md
|
||||
index: ./.pi-map.index.md
|
||||
map: ./.pi-map.md
|
||||
## children
|
||||
- openspec/specs/api-documentation
|
||||
index: openspec/specs/api-documentation/.pi-map.index.md
|
||||
map: openspec/specs/api-documentation/.pi-map.md
|
||||
- openspec/specs/auth-oauth
|
||||
index: openspec/specs/auth-oauth/.pi-map.index.md
|
||||
map: openspec/specs/auth-oauth/.pi-map.md
|
||||
- openspec/specs/database-models
|
||||
index: openspec/specs/database-models/.pi-map.index.md
|
||||
map: openspec/specs/database-models/.pi-map.md
|
||||
- openspec/specs/docker-infrastructure
|
||||
index: openspec/specs/docker-infrastructure/.pi-map.index.md
|
||||
map: openspec/specs/docker-infrastructure/.pi-map.md
|
||||
- openspec/specs/frontend-foundation
|
||||
index: openspec/specs/frontend-foundation/.pi-map.index.md
|
||||
map: openspec/specs/frontend-foundation/.pi-map.md
|
||||
- openspec/specs/git-repo
|
||||
index: openspec/specs/git-repo/.pi-map.index.md
|
||||
map: openspec/specs/git-repo/.pi-map.md
|
||||
- openspec/specs/instance-proxy
|
||||
index: openspec/specs/instance-proxy/.pi-map.index.md
|
||||
map: openspec/specs/instance-proxy/.pi-map.md
|
||||
- openspec/specs/instance-runtime-health
|
||||
index: openspec/specs/instance-runtime-health/.pi-map.index.md
|
||||
map: openspec/specs/instance-runtime-health/.pi-map.md
|
||||
- openspec/specs/instance-startup-health
|
||||
index: openspec/specs/instance-startup-health/.pi-map.index.md
|
||||
map: openspec/specs/instance-startup-health/.pi-map.md
|
||||
- openspec/specs/mobile-list-detail
|
||||
index: openspec/specs/mobile-list-detail/.pi-map.index.md
|
||||
map: openspec/specs/mobile-list-detail/.pi-map.md
|
||||
- openspec/specs/mobile-navigation
|
||||
index: openspec/specs/mobile-navigation/.pi-map.index.md
|
||||
map: openspec/specs/mobile-navigation/.pi-map.md
|
||||
- openspec/specs/mobile-repo-workspace
|
||||
index: openspec/specs/mobile-repo-workspace/.pi-map.index.md
|
||||
map: openspec/specs/mobile-repo-workspace/.pi-map.md
|
||||
- openspec/specs/mobile-tools-navigation
|
||||
index: openspec/specs/mobile-tools-navigation/.pi-map.index.md
|
||||
map: openspec/specs/mobile-tools-navigation/.pi-map.md
|
||||
- openspec/specs/opencode-web-server
|
||||
index: openspec/specs/opencode-web-server/.pi-map.index.md
|
||||
map: openspec/specs/opencode-web-server/.pi-map.md
|
||||
- openspec/specs/project-management
|
||||
index: openspec/specs/project-management/.pi-map.index.md
|
||||
map: openspec/specs/project-management/.pi-map.md
|
||||
- openspec/specs/readiness-probe-integration
|
||||
index: openspec/specs/readiness-probe-integration/.pi-map.index.md
|
||||
map: openspec/specs/readiness-probe-integration/.pi-map.md
|
||||
- openspec/specs/repo-clone-mode
|
||||
index: openspec/specs/repo-clone-mode/.pi-map.index.md
|
||||
map: openspec/specs/repo-clone-mode/.pi-map.md
|
||||
- openspec/specs/session-lifecycle-ux
|
||||
index: openspec/specs/session-lifecycle-ux/.pi-map.index.md
|
||||
map: openspec/specs/session-lifecycle-ux/.pi-map.md
|
||||
- openspec/specs/sessions-hub
|
||||
index: openspec/specs/sessions-hub/.pi-map.index.md
|
||||
map: openspec/specs/sessions-hub/.pi-map.md
|
||||
- openspec/specs/smart-tunnel-recovery
|
||||
index: openspec/specs/smart-tunnel-recovery/.pi-map.index.md
|
||||
map: openspec/specs/smart-tunnel-recovery/.pi-map.md
|
||||
- openspec/specs/ssh-keys
|
||||
index: openspec/specs/ssh-keys/.pi-map.index.md
|
||||
map: openspec/specs/ssh-keys/.pi-map.md
|
||||
- openspec/specs/tool-config-management
|
||||
index: openspec/specs/tool-config-management/.pi-map.index.md
|
||||
map: openspec/specs/tool-config-management/.pi-map.md
|
||||
- openspec/specs/tool-instances
|
||||
index: openspec/specs/tool-instances/.pi-map.index.md
|
||||
map: openspec/specs/tool-instances/.pi-map.md
|
||||
- openspec/specs/tool-port-configuration
|
||||
index: openspec/specs/tool-port-configuration/.pi-map.index.md
|
||||
map: openspec/specs/tool-port-configuration/.pi-map.md
|
||||
- openspec/specs/tool-terminal
|
||||
index: openspec/specs/tool-terminal/.pi-map.index.md
|
||||
map: openspec/specs/tool-terminal/.pi-map.md
|
||||
- openspec/specs/tool-terminal-startup-command
|
||||
index: openspec/specs/tool-terminal-startup-command/.pi-map.index.md
|
||||
map: openspec/specs/tool-terminal-startup-command/.pi-map.md
|
||||
- openspec/specs/tool-type-port-visibility
|
||||
index: openspec/specs/tool-type-port-visibility/.pi-map.index.md
|
||||
map: openspec/specs/tool-type-port-visibility/.pi-map.md
|
||||
- openspec/specs/tool-type-single-interface
|
||||
index: openspec/specs/tool-type-single-interface/.pi-map.index.md
|
||||
map: openspec/specs/tool-type-single-interface/.pi-map.md
|
||||
- openspec/specs/tool-types
|
||||
index: openspec/specs/tool-types/.pi-map.index.md
|
||||
map: openspec/specs/tool-types/.pi-map.md
|
||||
- openspec/specs/tool-types-definition
|
||||
index: openspec/specs/tool-types-definition/.pi-map.index.md
|
||||
map: openspec/specs/tool-types-definition/.pi-map.md
|
||||
- openspec/specs/traefik-deployment
|
||||
index: openspec/specs/traefik-deployment/.pi-map.index.md
|
||||
map: openspec/specs/traefik-deployment/.pi-map.md
|
||||
- openspec/specs/tunnel-health-monitoring
|
||||
index: openspec/specs/tunnel-health-monitoring/.pi-map.index.md
|
||||
map: openspec/specs/tunnel-health-monitoring/.pi-map.md
|
||||
- openspec/specs/user-config
|
||||
index: openspec/specs/user-config/.pi-map.index.md
|
||||
map: openspec/specs/user-config/.pi-map.md
|
||||
- openspec/specs/user-profile
|
||||
index: openspec/specs/user-profile/.pi-map.index.md
|
||||
map: openspec/specs/user-profile/.pi-map.md
|
||||
-
|
||||
## files
|
||||
- config-profile-multi-repo-mounts.md
|
||||
- home-path-expansion.md
|
||||
@@ -116,8 +15,8 @@ map: openspec/.pi-map.md
|
||||
- terminal-responsiveness.md
|
||||
- tool-definition-manifest.md
|
||||
## links
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
index: specs/.pi-map.index.md
|
||||
map: specs/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
# openspec/specs
|
||||
dir: openspec/specs
|
||||
# specs
|
||||
dir: specs
|
||||
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
index: specs/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Contains formal specification documents defining requirements, APIs, algorithms, and test strategies for core platform features across configuration management, container orchestration, terminal I/O, and tool definition systems.
|
||||
Defines formal specifications and requirements for core system features including container configuration, terminal I/O, and build tooling.
|
||||
## files
|
||||
- config-profile-multi-repo-mounts.md | Specifies requirements, API contracts, and test strategy for supporting multiple directory mappings per git repository mount in configuration profiles
|
||||
- home-path-expansion.md | Specifies requirements for expanding `~` and `$HOME` in container mount paths during Docker compose generation based on manifest user configuration.
|
||||
@@ -12,7 +12,7 @@ Contains formal specification documents defining requirements, APIs, algorithms,
|
||||
- terminal-responsiveness.md | Specification document for a high-performance web terminal I/O pipeline rewrite targeting sub-frame latency with event-driven PTY reading, output batching, flow control, and WebGL rendering. | dep: asyncio, pty, docker, WebSocket, xterm.js, WebGL, TypeScript, Python
|
||||
- tool-definition-manifest.md | Specifies a declarative manifest system for defining tool containers without Dockerfiles, including compilation to Docker/Compose, versioning, permission policies, and backward compatibility. | dep: Docker, Docker Compose, JSON Schema, database (PostgreSQL with JSONB), Alembic, Python/FastAPI (implied by paths)
|
||||
## arch
|
||||
Specification-driven development pattern using Markdown-based RFCs/ADRs that separate design documentation from implementation, covering behavioral contracts, edge cases, and verification strategies before coding.
|
||||
Document-driven specification pattern with Markdown-based RFCs covering API contracts, algorithms, and test strategies for cross-functional alignment before implementation.
|
||||
## tags
|
||||
mounts, docker, specifies, mount, manifest, requirements, home, path
|
||||
## symbols
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/api-documentation (index)
|
||||
dir: openspec/specs/api-documentation
|
||||
|
||||
## role
|
||||
Defines OpenAPI specification, health monitoring, and developer onboarding requirements for the FastAPI-based system.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/api-documentation/.pi-map.index.md
|
||||
map: openspec/specs/api-documentation/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/api-documentation
|
||||
dir: openspec/specs/api-documentation
|
||||
|
||||
index: openspec/specs/api-documentation/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines OpenAPI specification, health monitoring, and developer onboarding requirements for the FastAPI-based system.
|
||||
## files
|
||||
- spec.md | Define API documentation, health monitoring, and developer onboarding requirements for a FastAPI-based system. | dep: FastAPI, Pydantic v2, Swagger UI, Database, Redis
|
||||
## arch
|
||||
Specification-driven documentation using Markdown-based requirements with FastAPI-native patterns (OpenAPI, health endpoints, auto-generated docs).
|
||||
## tags
|
||||
fastapi, spec, define, api, documentation, health, monitoring, developer
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,94 +0,0 @@
|
||||
# API Documentation Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Provide comprehensive API documentation and health monitoring endpoints.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: OpenAPI/Swagger Documentation
|
||||
|
||||
The system SHALL auto-generate API documentation.
|
||||
|
||||
#### Scenario: API docs access
|
||||
- GIVEN the running API server
|
||||
- WHEN visiting `/docs`
|
||||
- THEN Swagger UI displays:
|
||||
- All available endpoints
|
||||
- Request/response schemas
|
||||
- Authentication requirements
|
||||
- Example requests and responses
|
||||
|
||||
### Requirement: Health Check Endpoints
|
||||
|
||||
The system SHALL provide health monitoring endpoints.
|
||||
|
||||
#### Scenario: General health check
|
||||
- GIVEN the running API server
|
||||
- WHEN visiting `/health`
|
||||
- THEN it returns:
|
||||
- Overall service status
|
||||
- Database connectivity status
|
||||
- Redis connectivity status
|
||||
- Disk space status
|
||||
- Uptime information
|
||||
|
||||
#### Scenario: Database health check
|
||||
- GIVEN the running API server
|
||||
- WHEN visiting `/health/db`
|
||||
- THEN it returns:
|
||||
- Database connection status
|
||||
- Response time
|
||||
- Connection pool status
|
||||
|
||||
### Requirement: API Setup Documentation
|
||||
|
||||
The system SHALL document API setup and configuration.
|
||||
|
||||
#### Scenario: Developer onboarding
|
||||
- GIVEN a new developer
|
||||
- WHEN they read `apps/api/README.md`
|
||||
- THEN they find:
|
||||
- Setup instructions
|
||||
- Environment variables
|
||||
- Running tests
|
||||
- Common commands
|
||||
- Architecture overview
|
||||
|
||||
### Requirement: Architecture Decision Records
|
||||
|
||||
The system SHALL document significant architectural decisions.
|
||||
|
||||
#### Scenario: Auth decision record
|
||||
- GIVEN the codebase
|
||||
- THEN an ADR SHALL exist documenting:
|
||||
- Why httpOnly cookies were chosen
|
||||
- Alternatives considered
|
||||
- Trade-offs and risks
|
||||
- Decision date and participants
|
||||
|
||||
### Requirement: Endpoint Documentation
|
||||
|
||||
The system SHALL document all API endpoints.
|
||||
|
||||
#### Scenario: Endpoint coverage
|
||||
- GIVEN the API codebase
|
||||
- THEN every endpoint SHALL have:
|
||||
- Pydantic request/response models
|
||||
- Docstrings with descriptions
|
||||
- Response status codes
|
||||
- Authentication requirements
|
||||
|
||||
## Dependencies
|
||||
|
||||
- FastAPI (auto-generates OpenAPI)
|
||||
- Pydantic v2
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `/docs` endpoint loads successfully
|
||||
- `/health` returns 200 with valid JSON
|
||||
- `/health/db` returns database status
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/auth-oauth (index)
|
||||
dir: openspec/specs/auth-oauth
|
||||
|
||||
## role
|
||||
Defines authentication and authorization requirements for OAuth2/OIDC integration with Authentik identity provider
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/auth-oauth/.pi-map.index.md
|
||||
map: openspec/specs/auth-oauth/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/auth-oauth
|
||||
dir: openspec/specs/auth-oauth
|
||||
|
||||
index: openspec/specs/auth-oauth/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines authentication and authorization requirements for OAuth2/OIDC integration with Authentik identity provider
|
||||
## files
|
||||
- spec.md | Specifies OAuth2/OIDC authentication requirements using Authentik with secure session handling, token refresh, and logout functionality | dep: Authentik OIDC provider, Database (User model), pytest, mypy, ruff
|
||||
## arch
|
||||
Specification-driven contract using markdown-based OpenAPI-style documentation for security requirements, session lifecycle, and token management patterns
|
||||
## tags
|
||||
spec, specifies, oauth2, oidc, authentication, requirements, authentik, secure
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,78 +0,0 @@
|
||||
# Authentication Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Manage user authentication via Authentik OAuth with secure session handling.
|
||||
## Requirements
|
||||
### Requirement: OAuth2/OIDC Flow
|
||||
The system SHALL support OAuth2/OIDC authentication via Authentik with fully configurable endpoints and SHALL validate Authentik-issued tokens via JWKS before creating local sessions.
|
||||
|
||||
#### Scenario: User login
|
||||
- GIVEN a user clicks the login button
|
||||
- WHEN the frontend redirects to Authentik authorization endpoint
|
||||
- THEN the redirect URI SHALL be constructed from environment-configured domains
|
||||
- AND the Authentik authorize URL SHALL be read from environment variables
|
||||
|
||||
#### Scenario: Token exchange and validation
|
||||
- GIVEN Authentik has redirected with authorization code
|
||||
- WHEN the callback endpoint receives the code
|
||||
- THEN it exchanges the code for provider tokens at the configured token URL
|
||||
- AND verifies token signature using the configured JWKS URL
|
||||
- AND validates the issuer and audience from environment configuration
|
||||
- AND upserts the local user account
|
||||
- AND mints internal access and refresh tokens
|
||||
|
||||
### Requirement: Session Security
|
||||
The system SHALL protect sessions using httpOnly cookies and SHALL apply secure cookie defaults by environment.
|
||||
|
||||
#### Scenario: Cookie attributes in production
|
||||
- GIVEN successful authentication in production
|
||||
- WHEN cookies are set
|
||||
- THEN access_token cookie SHALL be httpOnly
|
||||
- AND access_token cookie SHALL have Secure flag
|
||||
- AND access_token cookie SHALL have SameSite=strict
|
||||
- AND refresh_token cookie SHALL have the same attributes
|
||||
|
||||
#### Scenario: Cookie attributes in localhost development
|
||||
- GIVEN successful authentication in localhost development
|
||||
- WHEN cookies are set
|
||||
- THEN access_token cookie SHALL be httpOnly
|
||||
- AND access_token cookie SHALL have Secure=false
|
||||
- AND access_token cookie SHALL have SameSite=lax
|
||||
- AND refresh_token cookie SHALL have the same attributes
|
||||
|
||||
### Requirement: Token Refresh
|
||||
The system SHALL support automatic token refresh with server-side refresh token storage, rotation, and revocation.
|
||||
|
||||
#### Scenario: Access token expiration
|
||||
- GIVEN a user has an expired access token
|
||||
- WHEN the user makes an authenticated request that can refresh
|
||||
- THEN the system validates the refresh token against non-expired, non-revoked DB state
|
||||
- AND rotates the refresh token
|
||||
- AND issues a new internal access token
|
||||
|
||||
#### Scenario: Refresh token reuse detection
|
||||
- GIVEN a refresh token has already been rotated or revoked
|
||||
- WHEN it is presented again to the refresh endpoint
|
||||
- THEN the system rejects the request with unauthorized status
|
||||
- AND invalidates the token chain for the session
|
||||
|
||||
### Requirement: Session Termination
|
||||
The system SHALL support explicit logout with refresh token invalidation.
|
||||
|
||||
#### Scenario: User logout
|
||||
- GIVEN an authenticated user
|
||||
- WHEN the user clicks logout
|
||||
- THEN all auth cookies are cleared
|
||||
- AND the refresh token is invalidated in server-side storage
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Authentik OIDC provider configured
|
||||
- Database models: User
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/database-models (index)
|
||||
dir: openspec/specs/database-models
|
||||
|
||||
## role
|
||||
Defines the database schema, SQLAlchemy 2.0 async ORM models, and migration infrastructure for the Headquarter platform's six core entities.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/database-models/.pi-map.index.md
|
||||
map: openspec/specs/database-models/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/database-models
|
||||
dir: openspec/specs/database-models
|
||||
|
||||
index: openspec/specs/database-models/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the database schema, SQLAlchemy 2.0 async ORM models, and migration infrastructure for the Headquarter platform's six core entities.
|
||||
## files
|
||||
- spec.md | Define database schema and SQLAlchemy 2.0 async models for the Headquarter platform with six core entities, Alembic migrations, and seeding. | dep: PostgreSQL, SQLAlchemy 2.0, asyncpg, Alembic, Fernet, pytest, mypy, ruff
|
||||
## arch
|
||||
Specification-driven architecture using SQLAlchemy 2.0 async declarative models with Alembic for migrations, seeding support, and strict separation between schema definition and implementation.
|
||||
## tags
|
||||
alembic, spec, define, database, schema, sqlalchemy, async, models
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,127 +0,0 @@
|
||||
# Database Models Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the database schema and models for the Headquarter platform using SQLAlchemy 2.0 async style.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: User Model
|
||||
|
||||
The system SHALL store user information.
|
||||
|
||||
#### Scenario: User record
|
||||
- GIVEN user authentication
|
||||
- THEN the User model SHALL have:
|
||||
- id: UUID primary key
|
||||
- email: Unique email address
|
||||
- name: Display name
|
||||
- authentik_id: External Authentik identifier
|
||||
- avatar_url: Local avatar path (optional)
|
||||
- created_at: Timestamp
|
||||
- updated_at: Timestamp
|
||||
|
||||
### Requirement: Project Model
|
||||
|
||||
The system SHALL organize work into projects.
|
||||
|
||||
#### Scenario: Project record
|
||||
- GIVEN project creation
|
||||
- THEN the Project model SHALL have:
|
||||
- id: UUID primary key
|
||||
- name: Project name
|
||||
- description: Project description (optional)
|
||||
- owner_id: Reference to User
|
||||
- default_ssh_key_id: Reference to SSHKey (optional)
|
||||
- created_at: Timestamp
|
||||
- updated_at: Timestamp
|
||||
|
||||
### Requirement: GitRepository Model
|
||||
|
||||
The system SHALL track git repositories.
|
||||
|
||||
#### Scenario: Repository record
|
||||
- GIVEN repository creation
|
||||
- THEN the GitRepository model SHALL have:
|
||||
- id: UUID primary key
|
||||
- name: Repository name
|
||||
- path: Filesystem path to bare repo
|
||||
- project_id: Reference to Project
|
||||
- owner_id: Reference to User
|
||||
- is_mirror: Boolean (cloned vs created)
|
||||
- remote_url: Source URL (for mirrors)
|
||||
- last_push: Timestamp (optional)
|
||||
- created_at: Timestamp
|
||||
|
||||
### Requirement: SSHKey Model
|
||||
|
||||
The system SHALL manage SSH keys.
|
||||
|
||||
#### Scenario: SSH key record
|
||||
- GIVEN SSH key generation
|
||||
- THEN the SSHKey model SHALL have:
|
||||
- id: UUID primary key
|
||||
- name: Key identifier
|
||||
- public_key: OpenSSH format public key
|
||||
- private_key_encrypted: Fernet-encrypted private key
|
||||
- user_id: Reference to User
|
||||
- project_id: Reference to Project (optional, for project-level keys)
|
||||
- created_at: Timestamp
|
||||
|
||||
### Requirement: UserConfig Model
|
||||
|
||||
The system SHALL store user preferences.
|
||||
|
||||
#### Scenario: Configuration record
|
||||
- GIVEN user preferences
|
||||
- THEN the UserConfig model SHALL have:
|
||||
- id: UUID primary key
|
||||
- user_id: Reference to User
|
||||
- config: JSONB key-value storage
|
||||
- created_at: Timestamp
|
||||
- updated_at: Timestamp
|
||||
|
||||
### Requirement: Alembic Migrations
|
||||
|
||||
The system SHALL version database schema changes.
|
||||
|
||||
#### Scenario: Migration setup
|
||||
- GIVEN the database models
|
||||
- THEN Alembic SHALL:
|
||||
- Be initialized with `alembic init`
|
||||
- Have an initial migration creating all tables
|
||||
- Support async operations with `asyncpg`
|
||||
- Be runnable via `make migrate`
|
||||
|
||||
### Requirement: Database Seeding
|
||||
|
||||
The system SHALL provide development data.
|
||||
|
||||
#### Scenario: Development setup
|
||||
- GIVEN a fresh database
|
||||
- WHEN running the seed script
|
||||
- THEN a test user is created
|
||||
- AND sample data is available for development
|
||||
|
||||
## Relationships
|
||||
|
||||
- User owns Projects (1:N)
|
||||
- Project has GitRepositories (1:N)
|
||||
- User has SSHKeys (1:N)
|
||||
- User has UserConfig (1:1)
|
||||
- Project optionally has default SSHKey (N:1)
|
||||
|
||||
## Dependencies
|
||||
|
||||
- PostgreSQL 15+
|
||||
- SQLAlchemy 2.0+
|
||||
- asyncpg
|
||||
- Alembic
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- All migrations run successfully
|
||||
- Models use SQLAlchemy 2.0 async style
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/docker-infrastructure (index)
|
||||
dir: openspec/specs/docker-infrastructure
|
||||
|
||||
## role
|
||||
Defines Docker-based infrastructure specifications for multi-service development and production deployment environments.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/docker-infrastructure/.pi-map.index.md
|
||||
map: openspec/specs/docker-infrastructure/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/docker-infrastructure
|
||||
dir: openspec/specs/docker-infrastructure
|
||||
|
||||
index: openspec/specs/docker-infrastructure/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines Docker-based infrastructure specifications for multi-service development and production deployment environments.
|
||||
## files
|
||||
- spec.md | Define Docker-based infrastructure specifications for a multi-service development and production deployment environment | dep: Docker, Docker Compose, Make, Python 3.11, Node.js 20+, nginx, Traefik, Vite, Authentik, Redis, PostgreSQL
|
||||
## arch
|
||||
Infrastructure-as-code specification using Docker containerization with environment-specific configurations for development and production deployments.
|
||||
## tags
|
||||
docker, spec, define, infrastructure, specifications, multi, service, development
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,114 +0,0 @@
|
||||
# Docker Infrastructure Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Provide a complete Docker-based development environment with all required services.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Docker Compose Setup
|
||||
|
||||
The system SHALL provide Docker Compose configurations for both development and traefik deployment.
|
||||
|
||||
#### Scenario: Development compose file
|
||||
- GIVEN the development environment
|
||||
- THEN `docker-compose.yml` SHALL define all platform services for local development
|
||||
|
||||
#### Scenario: Traefik compose file
|
||||
- GIVEN the production deployment
|
||||
- THEN `docker-compose.traefik.yml` SHALL define all platform services behind Traefik
|
||||
- AND no ports SHALL be exposed directly (all traffic through Traefik)
|
||||
|
||||
### Requirement: Multi-Stage API Dockerfile
|
||||
|
||||
The system SHALL build the API using a multi-stage Docker build.
|
||||
|
||||
#### Scenario: API container build
|
||||
- GIVEN the API source code
|
||||
- WHEN building the Docker image
|
||||
- THEN `apps/api/Dockerfile` SHALL:
|
||||
- Use Python 3.11+ base image
|
||||
- Install dependencies in a builder stage
|
||||
- Copy only necessary files to production stage
|
||||
- Run as non-root user
|
||||
- Expose port 8000
|
||||
|
||||
### Requirement: Web Frontend Dockerfile
|
||||
|
||||
The system SHALL build the web frontend for production deployment.
|
||||
|
||||
#### Scenario: Web container build
|
||||
- GIVEN the frontend source code
|
||||
- WHEN building the Docker image
|
||||
- THEN `apps/web/Dockerfile` SHALL:
|
||||
- Use Node.js 20+ base image
|
||||
- Install dependencies
|
||||
- Build the production bundle with Vite
|
||||
- Serve via nginx or similar
|
||||
- Run as non-root user
|
||||
|
||||
### Requirement: Environment Configuration
|
||||
|
||||
The system SHALL document all required environment variables for both development and traefik deployment modes.
|
||||
|
||||
#### Scenario: Environment setup
|
||||
- GIVEN a new developer or operator
|
||||
- WHEN they set up the project
|
||||
- THEN `.env.example` SHALL document all variables for both modes
|
||||
- AND variables SHALL include:
|
||||
- Database connection strings
|
||||
- Redis connection strings
|
||||
- Authentik configuration
|
||||
- JWT secrets
|
||||
- Docker volume paths
|
||||
- Domain configuration for traefik mode
|
||||
- External service URLs
|
||||
|
||||
### Requirement: Service Health Checks
|
||||
|
||||
The system SHALL provide health checks for all services.
|
||||
|
||||
#### Scenario: Health verification
|
||||
- GIVEN running services
|
||||
- WHEN health checks are performed
|
||||
- THEN each service reports healthy status
|
||||
- AND unhealthy services are restarted automatically
|
||||
|
||||
### Requirement: Makefile Commands
|
||||
|
||||
The system SHALL provide common operational commands.
|
||||
|
||||
#### Scenario: Developer workflow
|
||||
- GIVEN the project repository
|
||||
- WHEN a developer runs make commands
|
||||
- THEN these commands work:
|
||||
- `make up` - Start all services
|
||||
- `make down` - Stop all services
|
||||
- `make logs` - View service logs
|
||||
- `make migrate` - Run database migrations
|
||||
- `make test` - Run test suites
|
||||
- `make lint` - Run linting
|
||||
|
||||
### Requirement: Persistent Storage
|
||||
|
||||
The system SHALL persist git repositories across container restarts.
|
||||
|
||||
#### Scenario: Repository storage
|
||||
- GIVEN the Docker setup
|
||||
- THEN a dedicated volume SHALL mount at `/data/repos`
|
||||
- AND repositories persist across container restarts
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Docker 24.0+
|
||||
- Docker Compose 2.20+
|
||||
- Make
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `docker-compose config` validates without errors
|
||||
- All services start successfully with `make up`
|
||||
- Health checks pass for all services
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/frontend-foundation (index)
|
||||
dir: openspec/specs/frontend-foundation
|
||||
|
||||
## role
|
||||
Defines the frontend foundation specification for a modern React 18+ TypeScript application with Vite tooling, routing, styling, and authentication patterns.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/frontend-foundation/.pi-map.index.md
|
||||
map: openspec/specs/frontend-foundation/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/frontend-foundation
|
||||
dir: openspec/specs/frontend-foundation
|
||||
|
||||
index: openspec/specs/frontend-foundation/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the frontend foundation specification for a modern React 18+ TypeScript application with Vite tooling, routing, styling, and authentication patterns.
|
||||
## files
|
||||
- spec.md | Define a specification for a modern React 18+ TypeScript frontend with Vite, React Router, Tailwind CSS, authenticated routing, responsive layout, and dashboard/tool workshop features. | dep: React 18+, TypeScript 5+, Vite, React Router, Tailwind CSS, Axios
|
||||
## arch
|
||||
Specification-driven architecture using Vite for build tooling, React Router for client-side routing with authenticated route guards, Tailwind CSS for utility-first styling, and a modular dashboard/tool workshop layout pattern.
|
||||
## tags
|
||||
react, vite, spec, define, specification, modern, typescript, frontend
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,160 +0,0 @@
|
||||
# Frontend Foundation Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Provide a modern React frontend with TypeScript, routing, and responsive layout.
|
||||
## Requirements
|
||||
### Requirement: React Application Setup
|
||||
The system SHALL use React 18+ with TypeScript and SHALL provide a runnable application source structure in `apps/web/src`.
|
||||
|
||||
#### Scenario: Frontend build
|
||||
- GIVEN the frontend codebase
|
||||
- THEN it SHALL:
|
||||
- Use React 18+ with TypeScript 5+
|
||||
- Use Vite as the build tool
|
||||
- Support Hot Module Replacement (HMR)
|
||||
- Output optimized production builds
|
||||
- Include a concrete entrypoint, app composition, and route tree
|
||||
|
||||
### Requirement: Client-Side Routing
|
||||
The system SHALL implement client-side routing with authenticated route guards and explicit not-found handling.
|
||||
|
||||
#### Scenario: Navigation
|
||||
- GIVEN the frontend application
|
||||
- THEN React Router SHALL:
|
||||
- Define routes for all foundation pages
|
||||
- Support protected routes (require authentication)
|
||||
- Handle 404 errors
|
||||
- Support route parameters for feature pages
|
||||
|
||||
#### Scenario: Protected routes
|
||||
- GIVEN an unauthenticated user
|
||||
- WHEN they access a protected route
|
||||
- THEN they are redirected to login flow
|
||||
- AND post-auth navigation returns them to an authenticated landing route
|
||||
|
||||
### Requirement: Styling Framework
|
||||
|
||||
The system SHALL use Tailwind CSS for styling.
|
||||
|
||||
#### Scenario: UI components
|
||||
- GIVEN the frontend codebase
|
||||
- THEN Tailwind CSS SHALL:
|
||||
- Provide utility-first styling
|
||||
- Support custom theme configuration
|
||||
- Include responsive design utilities
|
||||
- Support dark mode
|
||||
|
||||
### Requirement: Layout Component
|
||||
The system SHALL provide a consistent application layout for authenticated screens across desktop and mobile sizes.
|
||||
|
||||
#### Scenario: Application shell
|
||||
- GIVEN the frontend application
|
||||
- THEN a Layout component SHALL:
|
||||
- Display a header with user info and logout
|
||||
- Display sidebar navigation on desktop
|
||||
- Show main content area
|
||||
- Collapse sidebar into a mobile menu toggle on small viewports
|
||||
|
||||
#### Scenario: Navigation links
|
||||
- GIVEN the sidebar navigation
|
||||
- THEN it SHALL include links to:
|
||||
- Dashboard
|
||||
- Projects
|
||||
- Repositories
|
||||
- SSH Keys
|
||||
- Settings
|
||||
|
||||
### Requirement: Responsive Design
|
||||
|
||||
The system SHALL support mobile devices.
|
||||
|
||||
#### Scenario: Mobile viewport
|
||||
- GIVEN a mobile device
|
||||
- WHEN the app loads
|
||||
- THEN:
|
||||
- A hamburger menu replaces the sidebar
|
||||
- Content adapts to screen width
|
||||
- Touch targets are appropriately sized
|
||||
|
||||
### Requirement: Loading States
|
||||
The system SHALL handle asynchronous operations gracefully during auth bootstrap and dashboard fetches.
|
||||
|
||||
#### Scenario: Data fetching
|
||||
- GIVEN a page loading data
|
||||
- THEN:
|
||||
- Loading states are shown while requests are in flight
|
||||
- Errors are shown with retry affordance
|
||||
- Initial auth-check loading prevents protected-layout flicker
|
||||
|
||||
### Requirement: HTTP Client Configuration
|
||||
The system SHALL configure HTTP requests for cookie-based auth and unauthorized-session recovery.
|
||||
|
||||
#### Scenario: API communication
|
||||
- GIVEN the frontend application
|
||||
- THEN Axios/fetch SHALL:
|
||||
- Send credentials (cookies) with requests
|
||||
- Handle 401 responses by redirecting to login
|
||||
- Set appropriate content-type headers
|
||||
- Support request/response interception in a shared client module
|
||||
|
||||
### Requirement: Dashboard Page
|
||||
|
||||
The system SHALL provide a dashboard overview.
|
||||
|
||||
#### Scenario: Dashboard view
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they visit the dashboard
|
||||
- THEN they see:
|
||||
- Total repository count
|
||||
- Total project count
|
||||
- Recent activity
|
||||
- Quick action buttons
|
||||
|
||||
### Requirement: Tool Interface Type Dropdown
|
||||
The tool workshop SHALL provide a dropdown for selecting a single interface type.
|
||||
|
||||
#### Scenario: Interface type dropdown
|
||||
- GIVEN the tool workshop page
|
||||
- WHEN a user creates or edits a tool type
|
||||
- THEN the interface type field is a dropdown (not checkboxes)
|
||||
- AND the options are "web" and "terminal"
|
||||
- AND only one option can be selected
|
||||
|
||||
### Requirement: Conditional Port Fields
|
||||
The tool workshop SHALL conditionally show or hide port-related fields based on the selected interface type.
|
||||
|
||||
#### Scenario: Web tool shows port fields
|
||||
- GIVEN a tool type with interface type "web"
|
||||
- WHEN the user views the tool editor
|
||||
- THEN the Default Port field is visible and required
|
||||
- AND port-related config fields are shown
|
||||
|
||||
#### Scenario: Terminal tool hides port fields
|
||||
- GIVEN a tool type with interface type "terminal"
|
||||
- WHEN the user views the tool editor
|
||||
- THEN the Default Port field is hidden
|
||||
- AND port-related config fields are hidden or disabled
|
||||
|
||||
#### Scenario: Changing interface type updates visibility
|
||||
- GIVEN a user changes interface type from "web" to "terminal"
|
||||
- WHEN the change is applied
|
||||
- THEN port fields are immediately hidden
|
||||
- AND any port value is preserved but not validated
|
||||
|
||||
## Dependencies
|
||||
|
||||
- React 18+
|
||||
- TypeScript 5+
|
||||
- Vite
|
||||
- React Router
|
||||
- Tailwind CSS
|
||||
- Axios
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
- `npm run build` must succeed
|
||||
- Frontend handles 401 responses correctly
|
||||
- Responsive design works on mobile
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/git-repo (index)
|
||||
dir: openspec/specs/git-repo
|
||||
|
||||
## role
|
||||
Defines the specification for a bare git repository management service that coordinates on-disk git storage with database-backed metadata.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/git-repo/.pi-map.index.md
|
||||
map: openspec/specs/git-repo/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/git-repo
|
||||
dir: openspec/specs/git-repo
|
||||
|
||||
index: openspec/specs/git-repo/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the specification for a bare git repository management service that coordinates on-disk git storage with database-backed metadata.
|
||||
## files
|
||||
- spec.md | Specifies requirements for managing bare git repositories on disk with database metadata, including creation, SSH key association, cloning, listing, deletion, and duplicate prevention. | dep: Database models (GitRepository, Project, User), Docker volume for repo storage
|
||||
## arch
|
||||
Domain-driven specification pattern with clear separation between storage concerns (filesystem git operations) and metadata concerns (database records), using SSH key-based access control and duplicate prevention logic.
|
||||
## tags
|
||||
spec, specifies, requirements, managing, bare, git, repositories, disk
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,84 +0,0 @@
|
||||
# Git Repository Management Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Manage git repositories as bare repos on disk with metadata in database.
|
||||
## Requirements
|
||||
### Requirement: Repository Creation
|
||||
|
||||
The system SHALL allow creating new bare git repositories with an optional SSH key association.
|
||||
|
||||
#### Scenario: Create repository
|
||||
- GIVEN an authenticated user with a project
|
||||
- WHEN they create a new repository
|
||||
- THEN a bare repo is initialized on disk at `/data/repos/{user_id}/{project_id}/{repo_name}.git`
|
||||
- AND metadata is stored in the database
|
||||
|
||||
#### Scenario: Create repository with SSH key
|
||||
- **GIVEN** an authenticated user with a project
|
||||
- **WHEN** they create a new repository with `ssh_key_id`
|
||||
- **THEN** a bare repo is initialized on disk
|
||||
- **AND** the SSH key association is stored in the database
|
||||
|
||||
### Requirement: Repository SSH key assignment
|
||||
The system SHALL allow associating an SSH key with a GitRepository for clone operations and container git access.
|
||||
|
||||
#### Scenario: Assign SSH key at repository creation
|
||||
- **GIVEN** an authenticated user creating a repository
|
||||
- **WHEN** they provide an `ssh_key_id`
|
||||
- **THEN** the repository is associated with that SSH key
|
||||
|
||||
#### Scenario: Update repository SSH key
|
||||
- **GIVEN** an authenticated user with an existing repository
|
||||
- **WHEN** they call `PATCH /repositories/{id}/ssh-key` with a new `ssh_key_id`
|
||||
- **THEN** the repository's SSH key association is updated
|
||||
|
||||
### Requirement: Repository Cloning
|
||||
|
||||
The system SHALL support cloning external repositories.
|
||||
|
||||
#### Scenario: Clone repository
|
||||
- GIVEN an authenticated user with a project
|
||||
- WHEN they provide a remote URL
|
||||
- THEN the system clones as a bare mirror
|
||||
- AND stores it in the structured path
|
||||
|
||||
### Requirement: Repository Listing
|
||||
|
||||
The system SHALL list all user repositories.
|
||||
|
||||
#### Scenario: List repositories
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they view the repositories page
|
||||
- THEN all their repos are listed with name, path, and last push date
|
||||
|
||||
### Requirement: Repository Deletion
|
||||
The system SHALL remove repository records when their owning project is deleted through authorized project deletion flow.
|
||||
|
||||
#### Scenario: Cascade repository cleanup
|
||||
- GIVEN a project with associated repositories
|
||||
- WHEN the project owner deletes the project
|
||||
- THEN repository records for that project are removed
|
||||
- AND repository listing no longer includes removed records
|
||||
|
||||
### Requirement: Duplicate Prevention
|
||||
|
||||
The system SHALL prevent duplicate repository names per project.
|
||||
|
||||
#### Scenario: Duplicate name
|
||||
- GIVEN a project with a repo named "frontend"
|
||||
- WHEN the user tries to create another "frontend" repo
|
||||
- THEN the system rejects with a validation error
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Database models: GitRepository, Project, User
|
||||
- Docker volume for repo storage
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/instance-proxy (index)
|
||||
dir: openspec/specs/instance-proxy
|
||||
|
||||
## role
|
||||
Defines the API contract for a secure proxy service that routes HTTP/WebSocket traffic to running tool instances with owner-scoped access control.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/instance-proxy/.pi-map.index.md
|
||||
map: openspec/specs/instance-proxy/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/instance-proxy
|
||||
dir: openspec/specs/instance-proxy
|
||||
|
||||
index: openspec/specs/instance-proxy/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the API contract for a secure proxy service that routes HTTP/WebSocket traffic to running tool instances with owner-scoped access control.
|
||||
## files
|
||||
- spec.md | Specifies API requirements for an HTTP/WebSocket proxy endpoint that forwards requests to running tool instances with owner-based access control
|
||||
## arch
|
||||
Specification-driven API design using markdown-based OpenAPI-style documentation with WebSocket upgrade support, reverse proxy patterns, and owner-based authorization middleware.
|
||||
## tags
|
||||
spec, specifies, api, requirements, http, websocket, proxy, endpoint
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,41 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Proxy endpoint exists for running instances
|
||||
The API SHALL expose an endpoint that forwards HTTP requests to a running tool instance.
|
||||
|
||||
#### Scenario: Access running instance
|
||||
- **WHEN** an authenticated user sends a GET request to `/instances/{id}/proxy/`
|
||||
- **THEN** the request is forwarded to the instance's container
|
||||
- **AND** the response is returned to the user
|
||||
|
||||
#### Scenario: Access instance subpath
|
||||
- **WHEN** an authenticated user sends a request to `/instances/{id}/proxy/api/status`
|
||||
- **THEN** the request is forwarded to `{container_url}/api/status`
|
||||
- **AND** the response is returned to the user
|
||||
|
||||
### Requirement: Only instance owner can access proxy
|
||||
The proxy endpoint SHALL verify that the authenticated user owns the instance before forwarding.
|
||||
|
||||
#### Scenario: Owner accesses instance
|
||||
- **WHEN** the instance owner requests `/instances/{id}/proxy/`
|
||||
- **THEN** the request is forwarded to the instance
|
||||
|
||||
#### Scenario: Non-owner attempts access
|
||||
- **WHEN** a user who does not own the instance requests `/instances/{id}/proxy/`
|
||||
- **THEN** the API returns 403 Forbidden
|
||||
|
||||
### Requirement: Proxy handles WebSocket upgrades
|
||||
The proxy endpoint SHALL support WebSocket upgrade requests for real-time features.
|
||||
|
||||
#### Scenario: WebSocket connection to instance
|
||||
- **WHEN** a user sends a request with `Upgrade: websocket` header
|
||||
- **THEN** the API establishes a bidirectional WebSocket connection to the instance
|
||||
- **AND** messages are relayed between user and instance
|
||||
|
||||
### Requirement: Frontend uses proxy URL for instance access
|
||||
The frontend SHALL link to the proxy endpoint instead of the internal container URL.
|
||||
|
||||
#### Scenario: User clicks Open button
|
||||
- **WHEN** a user clicks "Open" on a running instance
|
||||
- **THEN** a new tab opens to `/instances/{id}/proxy/`
|
||||
- **AND** the proxied instance content is displayed
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/instance-runtime-health (index)
|
||||
dir: openspec/specs/instance-runtime-health
|
||||
|
||||
## role
|
||||
Defines health monitoring and container state synchronization requirements for container lifecycle management.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/instance-runtime-health/.pi-map.index.md
|
||||
map: openspec/specs/instance-runtime-health/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/instance-runtime-health
|
||||
dir: openspec/specs/instance-runtime-health
|
||||
|
||||
index: openspec/specs/instance-runtime-health/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines health monitoring and container state synchronization requirements for container lifecycle management.
|
||||
## files
|
||||
- spec.md | Specification document defining health monitoring, polling, and container state synchronization requirements for a container/instance management system | dep: Docker, HTTP tunneling, REST API
|
||||
## arch
|
||||
Specification-driven design using requirement-based documentation with polling-based health checks and state reconciliation patterns.
|
||||
## tags
|
||||
container, spec, specification, document, defining, health, monitoring, polling
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,57 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Runtime health endpoint
|
||||
The system SHALL provide a health endpoint that checks both container and tunnel health.
|
||||
|
||||
#### Scenario: Full health check
|
||||
- **GIVEN** a running web-enabled instance
|
||||
- **WHEN** `GET /instances/{id}/health` is called
|
||||
- **THEN** the response includes:
|
||||
- `container_status`: "running", "exited", "restarting", or "not_found"
|
||||
- `container_health`: "healthy", "unhealthy", or null (if no Docker healthcheck)
|
||||
- `tunnel_status`: "healthy", "unreachable", or "error_response"
|
||||
- `tunnel_status_code`: the HTTP status code from the tunnel URL, or null
|
||||
- `probe_status`: "passed", "failed", "pending", or "not_configured"
|
||||
- `healthy`: true only if container is running AND tunnel is healthy
|
||||
|
||||
#### Scenario: Health check for terminal-only instance
|
||||
- **GIVEN** a running terminal-only instance
|
||||
- **WHEN** `GET /instances/{id}/health` is called
|
||||
- **THEN** the response includes `container_status: "running"`
|
||||
- **AND** `tunnel_status: "not_applicable"`
|
||||
- **AND** `healthy: true` if container is running
|
||||
|
||||
### Requirement: Continuous health polling
|
||||
The system SHALL support periodic health checks from the frontend.
|
||||
|
||||
#### Scenario: Frontend health polling
|
||||
- **GIVEN** active instances in the UI
|
||||
- **WHEN** the frontend polls health every 30 seconds
|
||||
- **THEN** the health status is displayed as a badge
|
||||
- **AND** the badge shows "tunnel error" only when tunnel is unreachable
|
||||
- **AND** the badge shows "app error" when tunnel returns 502/503/504
|
||||
- **AND** the badge shows "starting" when container is up but probe is pending
|
||||
|
||||
### Requirement: Container state synchronization
|
||||
The system SHALL update instance status when container state changes unexpectedly.
|
||||
|
||||
#### Scenario: Container crashes
|
||||
- **GIVEN** an instance with status "running"
|
||||
- **WHEN** the container exits (crash or OOM)
|
||||
- **AND** a health check is performed
|
||||
- **THEN** the instance status is updated to "error"
|
||||
- **AND** the container exit code and logs are captured
|
||||
|
||||
#### Scenario: Container stopped externally
|
||||
- **GIVEN** an instance with status "running"
|
||||
- **WHEN** the container is stopped via docker command outside the system
|
||||
- **AND** a health check is performed
|
||||
- **THEN** the instance status is updated to "stopped"
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
None.
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
None.
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/instance-startup-health (index)
|
||||
dir: openspec/specs/instance-startup-health
|
||||
|
||||
## role
|
||||
Defines behavioral specifications for container health verification during tool instance startup lifecycle.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/instance-startup-health/.pi-map.index.md
|
||||
map: openspec/specs/instance-startup-health/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/instance-startup-health
|
||||
dir: openspec/specs/instance-startup-health
|
||||
|
||||
index: openspec/specs/instance-startup-health/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines behavioral specifications for container health verification during tool instance startup lifecycle.
|
||||
## files
|
||||
- spec.md | Defines requirements for container startup verification, readiness probe execution, and health monitoring for a tool instance management system using Docker Compose | dep: docker compose, docker ps, readiness probes, tunnels, health endpoints, database
|
||||
## arch
|
||||
Specification-driven validation using Markdown-based requirements documentation with Docker Compose integration patterns.
|
||||
## tags
|
||||
spec, defines, requirements, container, startup, verification, readiness, probe
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,83 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Container startup verification
|
||||
The system SHALL verify that containers reach a running state before marking instances as "running".
|
||||
|
||||
#### Scenario: Container starts successfully
|
||||
- **WHEN** `docker compose up` completes
|
||||
- **THEN** the system polls `docker ps` every 2 seconds for up to 30 seconds
|
||||
- **AND** when the container state is "running", the instance status becomes "starting"
|
||||
- **AND** the readiness probe begins execution
|
||||
|
||||
#### Scenario: Container fails to start
|
||||
- **WHEN** `docker compose up` completes
|
||||
- **AND** the container exits within 30 seconds
|
||||
- **THEN** the instance status becomes "error"
|
||||
- **AND** the container exit code is stored in the error message
|
||||
|
||||
#### Scenario: Container stays in restarting loop
|
||||
- **WHEN** `docker compose up` completes
|
||||
- **AND** the container remains in "restarting" state after 30 seconds
|
||||
- **THEN** the instance status becomes "error"
|
||||
- **AND** the error message indicates the container is stuck restarting
|
||||
|
||||
### Requirement: Readiness probe execution
|
||||
The system SHALL execute readiness probes for web-enabled tool instances before marking them as "running".
|
||||
|
||||
#### Scenario: Probe succeeds
|
||||
- **GIVEN** a tool instance with status "starting"
|
||||
- **AND** the tool type has a readiness probe configured
|
||||
- **WHEN** the probe command returns exit code 0 within the timeout
|
||||
- **THEN** the instance status becomes "running"
|
||||
- **AND** the tunnel is created (for web tools)
|
||||
|
||||
#### Scenario: Probe times out
|
||||
- **GIVEN** a tool instance with status "starting"
|
||||
- **AND** the tool type has a readiness probe configured
|
||||
- **WHEN** the probe does not succeed within the configured timeout (default 30s)
|
||||
- **THEN** the instance status becomes "unhealthy"
|
||||
- **AND** the tunnel is still created (the container is running)
|
||||
- **AND** the last probe output is stored for diagnostics
|
||||
|
||||
#### Scenario: Terminal tool skips probe
|
||||
- **GIVEN** a tool instance for a terminal-only tool type
|
||||
- **WHEN** the container reaches "running" state
|
||||
- **THEN** the instance status immediately becomes "running"
|
||||
- **AND** no readiness probe is executed
|
||||
|
||||
### Requirement: Container health monitoring
|
||||
The system SHALL check container health in addition to tunnel health.
|
||||
|
||||
#### Scenario: Container is healthy
|
||||
- **GIVEN** a running instance
|
||||
- **WHEN** the health endpoint is queried
|
||||
- **THEN** the response includes `container_status: "running"`
|
||||
- **AND** the response includes `container_health: "healthy"` if Docker healthcheck exists
|
||||
|
||||
#### Scenario: Container has crashed
|
||||
- **GIVEN** a running instance
|
||||
- **WHEN** the container exits or is stopped externally
|
||||
- **AND** the health endpoint is queried
|
||||
- **THEN** the response includes `container_status: "exited"`
|
||||
- **AND** the response includes `healthy: false`
|
||||
- **AND** the instance status in the database is updated to "error"
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### 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
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
None.
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-list-detail (index)
|
||||
dir: openspec/specs/mobile-list-detail
|
||||
|
||||
## role
|
||||
Defines mobile UI specification for a configuration management system with list/detail views and CRUD operations.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/mobile-list-detail/.pi-map.index.md
|
||||
map: openspec/specs/mobile-list-detail/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-list-detail
|
||||
dir: openspec/specs/mobile-list-detail
|
||||
|
||||
index: openspec/specs/mobile-list-detail/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines mobile UI specification for a configuration management system with list/detail views and CRUD operations.
|
||||
## files
|
||||
- spec.md | Defines mobile UI requirements for a configuration management system with list views, detail views, editing, and CRUD operations for tool types and config profiles.
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirements documentation for mobile list-detail UI pattern with editing capabilities.
|
||||
## tags
|
||||
views, spec, defines, mobile, requirements, configuration, management, system
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,64 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Mobile list view for configuration items
|
||||
The mobile view SHALL display configuration items (tool types, config profiles) as a scrollable list of cards.
|
||||
|
||||
#### Scenario: Viewing tool types list
|
||||
- **WHEN** user navigates to Tool Workshop on mobile
|
||||
- **THEN** a list of tool type cards is displayed, each showing name and brief description
|
||||
|
||||
#### Scenario: Viewing config profiles list
|
||||
- **WHEN** user navigates to Config Profiles on mobile
|
||||
- **THEN** a list of profile cards is displayed, each showing name and description
|
||||
|
||||
#### Scenario: Empty state
|
||||
- **WHEN** the list has no items
|
||||
- **THEN** an empty state message is shown with a "Create" button
|
||||
|
||||
### Requirement: Item detail view
|
||||
Tapping a list item SHALL navigate to a detail view showing all configuration fields in read-only format.
|
||||
|
||||
#### Scenario: Viewing tool type details
|
||||
- **WHEN** user taps a tool type in the list
|
||||
- **THEN** a detail page opens showing all tool type fields (name, description, port, template, etc.)
|
||||
|
||||
#### Scenario: Viewing config profile details
|
||||
- **WHEN** user taps a config profile in the list
|
||||
- **THEN** a detail page opens showing all profile fields (env vars, mounts, includes, etc.)
|
||||
|
||||
### Requirement: Detail-to-edit navigation
|
||||
The detail view SHALL provide an "Edit" button that navigates to a full-screen edit form.
|
||||
|
||||
#### Scenario: Entering edit mode
|
||||
- **WHEN** user taps "Edit" on the detail view
|
||||
- **THEN** a full-screen edit form opens with all fields editable
|
||||
|
||||
#### Scenario: Saving changes
|
||||
- **WHEN** user modifies fields and taps "Save"
|
||||
- **THEN** changes are saved and the view returns to the detail page with updated data
|
||||
|
||||
#### Scenario: Canceling edit
|
||||
- **WHEN** user taps "Cancel" or back button
|
||||
- **THEN** changes are discarded and the view returns to the detail page
|
||||
|
||||
### Requirement: List item actions
|
||||
Each list item SHALL support swipe-to-delete and a quick actions menu.
|
||||
|
||||
#### Scenario: Deleting item
|
||||
- **WHEN** user swipes left on a list item and taps "Delete"
|
||||
- **THEN** a confirmation dialog appears, and upon confirmation the item is deleted
|
||||
|
||||
#### Scenario: Quick actions
|
||||
- **WHEN** user taps a "More" button on a list item
|
||||
- **THEN** an action sheet appears with options: Edit, Duplicate, Delete
|
||||
|
||||
### Requirement: Create new item
|
||||
A floating action button (FAB) on the list view SHALL open a creation form.
|
||||
|
||||
#### Scenario: Creating new item
|
||||
- **WHEN** user taps the FAB (+) on the list view
|
||||
- **THEN** a full-screen creation form opens
|
||||
|
||||
#### Scenario: Saving new item
|
||||
- **WHEN** user fills the form and taps "Save"
|
||||
- **THEN** the item is created and the view returns to the list with the new item visible
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-navigation (index)
|
||||
dir: openspec/specs/mobile-navigation
|
||||
|
||||
## role
|
||||
Defines mobile navigation UI requirements for grouped bottom navigation with expandable submenu behavior.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/mobile-navigation/.pi-map.index.md
|
||||
map: openspec/specs/mobile-navigation/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-navigation
|
||||
dir: openspec/specs/mobile-navigation
|
||||
|
||||
index: openspec/specs/mobile-navigation/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines mobile navigation UI requirements for grouped bottom navigation with expandable submenu behavior.
|
||||
## files
|
||||
- spec.md | Defines requirements for grouped bottom navigation with submenu behavior on mobile
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirement documentation with behavioral state definitions for mobile-responsive interaction patterns.
|
||||
## tags
|
||||
spec, defines, requirements, grouped, bottom, navigation, submenu, behavior
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,16 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Bottom navigation grouping
|
||||
The mobile bottom navigation SHALL support grouping related pages under a single navigation item that opens a sub-menu.
|
||||
|
||||
#### Scenario: Tools group navigation
|
||||
- **WHEN** user views the mobile bottom navigation
|
||||
- **THEN** a "Tools" item is visible that groups Tool Workshop and Config Profiles
|
||||
|
||||
#### Scenario: Opening grouped menu
|
||||
- **WHEN** user taps a grouped navigation item
|
||||
- **THEN** a bottom sheet or menu opens showing the grouped pages
|
||||
|
||||
#### Scenario: Active state for grouped items
|
||||
- **WHEN** user is on a page within a group
|
||||
- **THEN** the group's navigation item shows as active
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-repo-workspace (index)
|
||||
dir: openspec/specs/mobile-repo-workspace
|
||||
|
||||
## role
|
||||
Defines functional requirements and user interaction specifications for the mobile repository workspace interface.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/mobile-repo-workspace/.pi-map.index.md
|
||||
map: openspec/specs/mobile-repo-workspace/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-repo-workspace
|
||||
dir: openspec/specs/mobile-repo-workspace
|
||||
|
||||
index: openspec/specs/mobile-repo-workspace/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines functional requirements and user interaction specifications for the mobile repository workspace interface.
|
||||
## files
|
||||
- spec.md | Define mobile UI requirements for a repository workspace featuring file tree navigation, editor, git, and terminal views
|
||||
## arch
|
||||
Specification-driven design using modular view decomposition (file tree, editor, git, terminal) with responsive mobile UX patterns.
|
||||
## tags
|
||||
spec, define, mobile, requirements, repository, workspace, featuring, tree
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,83 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: File tree as primary view
|
||||
The mobile Repo Workspace SHALL display the file tree as the primary view with repository and branch selectors at the top.
|
||||
|
||||
#### Scenario: Viewing file tree
|
||||
- **WHEN** user navigates to a project's workspace on mobile
|
||||
- **THEN** a file tree is displayed showing folders and files in the repository
|
||||
|
||||
#### Scenario: Repository selection
|
||||
- **WHEN** user taps the repository selector dropdown
|
||||
- **THEN** a list of available repositories is shown for selection
|
||||
|
||||
#### Scenario: Branch selection
|
||||
- **WHEN** user taps the branch selector dropdown
|
||||
- **THEN** a list of branches is shown for selection
|
||||
|
||||
### Requirement: File tree interactions
|
||||
The file tree SHALL support folder expansion, file opening, and git status indicators.
|
||||
|
||||
#### Scenario: Expanding folder
|
||||
- **WHEN** user taps a folder in the tree
|
||||
- **THEN** the folder expands to show its contents, or collapses if already expanded
|
||||
|
||||
#### Scenario: Opening file
|
||||
- **WHEN** user taps a file in the tree
|
||||
- **THEN** the file opens in the editor view
|
||||
|
||||
#### Scenario: Git status indicators
|
||||
- **WHEN** files have git status (modified, staged, untracked)
|
||||
- **THEN** visual indicators (colors/icons) are shown next to affected files
|
||||
|
||||
### Requirement: Bottom tab navigation
|
||||
The mobile workspace SHALL provide bottom tabs for switching between File Tree, Editor, Git, and Terminal views.
|
||||
|
||||
#### Scenario: Switching to Editor tab
|
||||
- **WHEN** user taps the "Editor" tab
|
||||
- **THEN** the editor view is shown with the currently selected file (or empty state)
|
||||
|
||||
#### Scenario: Switching to Git tab
|
||||
- **WHEN** user taps the "Git" tab
|
||||
- **THEN** the git view is shown with status, commit form, and file lists
|
||||
|
||||
#### Scenario: Switching to Terminal tab
|
||||
- **WHEN** user taps the "Terminal" tab
|
||||
- **THEN** the terminal view is shown for the current repository
|
||||
|
||||
### Requirement: Editor view
|
||||
The editor view SHALL provide a full-screen code editing experience with syntax highlighting.
|
||||
|
||||
#### Scenario: Editing file
|
||||
- **WHEN** user opens a file and modifies it
|
||||
- **THEN** syntax highlighting is applied and changes can be saved
|
||||
|
||||
#### Scenario: Editor toolbar
|
||||
- **WHEN** viewing the editor
|
||||
- **THEN** a toolbar shows file name, save button, undo/redo buttons
|
||||
|
||||
### Requirement: Git view
|
||||
The git view SHALL show repository status and allow committing changes.
|
||||
|
||||
#### Scenario: Viewing git status
|
||||
- **WHEN** user opens the Git tab
|
||||
- **THEN** modified, staged, and untracked files are listed separately
|
||||
|
||||
#### Scenario: Staging files
|
||||
- **WHEN** user toggles a file's checkbox
|
||||
- **THEN** the file is staged or unstaged accordingly
|
||||
|
||||
#### Scenario: Committing changes
|
||||
- **WHEN** user enters a commit message and taps "Commit"
|
||||
- **THEN** staged files are committed with the provided message
|
||||
|
||||
### Requirement: Terminal view
|
||||
The terminal view SHALL provide a full-screen terminal for the repository's tool instance.
|
||||
|
||||
#### Scenario: Terminal for repository
|
||||
- **WHEN** user opens the Terminal tab
|
||||
- **THEN** a terminal is shown connected to the repository's active tool instance
|
||||
|
||||
#### Scenario: No active instance
|
||||
- **WHEN** no tool instance is running for the repository
|
||||
- **THEN** a message is shown with a button to start a new session
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-tools-navigation (index)
|
||||
dir: openspec/specs/mobile-tools-navigation
|
||||
|
||||
## role
|
||||
Defines the specification for mobile bottom navigation UI behavior and interaction patterns for the Tools menu.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/mobile-tools-navigation/.pi-map.index.md
|
||||
map: openspec/specs/mobile-tools-navigation/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/mobile-tools-navigation
|
||||
dir: openspec/specs/mobile-tools-navigation
|
||||
|
||||
index: openspec/specs/mobile-tools-navigation/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the specification for mobile bottom navigation UI behavior and interaction patterns for the Tools menu.
|
||||
## files
|
||||
- spec.md | Defines mobile UI requirements for a grouped "Tools" bottom navigation with a bottom sheet menu and active state indication
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirements documentation with behavioral state definitions for UI components.
|
||||
## tags
|
||||
bottom, spec, defines, mobile, requirements, grouped, tools, navigation
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,27 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tools bottom sheet navigation
|
||||
The mobile bottom navigation SHALL provide access to both Tool Workshop and Config Profiles through a grouped "Tools" entry.
|
||||
|
||||
#### Scenario: Opening Tools menu
|
||||
- **WHEN** user taps the "Tools" item in the mobile bottom navigation
|
||||
- **THEN** a bottom sheet slides up showing "Tool Workshop" and "Config Profiles" options
|
||||
|
||||
#### Scenario: Navigating to Tool Workshop
|
||||
- **WHEN** user taps "Tool Workshop" in the bottom sheet
|
||||
- **THEN** the bottom sheet closes and the app navigates to the Tool Workshop page
|
||||
|
||||
#### Scenario: Navigating to Config Profiles
|
||||
- **WHEN** user taps "Config Profiles" in the bottom sheet
|
||||
- **THEN** the bottom sheet closes and the app navigates to the Config Profiles page
|
||||
|
||||
#### Scenario: Closing bottom sheet without selection
|
||||
- **WHEN** user taps outside the bottom sheet or swipes down
|
||||
- **THEN** the bottom sheet closes without navigation
|
||||
|
||||
### Requirement: Active state indication
|
||||
The "Tools" bottom nav item SHALL indicate when either Tool Workshop or Config Profiles is the active page.
|
||||
|
||||
#### Scenario: Active page indication
|
||||
- **WHEN** user is viewing Tool Workshop or Config Profiles
|
||||
- **THEN** the "Tools" item in the bottom nav appears active/highlighted
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/opencode-web-server (index)
|
||||
dir: openspec/specs/opencode-web-server
|
||||
|
||||
## role
|
||||
Defines the specification for a web-based terminal server container that provides browser-accessible development tools via tmux and ranger.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/opencode-web-server/.pi-map.index.md
|
||||
map: openspec/specs/opencode-web-server/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/opencode-web-server
|
||||
dir: openspec/specs/opencode-web-server
|
||||
|
||||
index: openspec/specs/opencode-web-server/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the specification for a web-based terminal server container that provides browser-accessible development tools via tmux and ranger.
|
||||
## files
|
||||
- spec.md | Specifies requirements for OpenCode containers to run a web terminal server on port 3000 with tmux and ranger, exposed through tunnels and UI buttons
|
||||
## arch
|
||||
Container-based microservice specification with tunnel-based networking exposure and UI integration points for embedded terminal access.
|
||||
## tags
|
||||
spec, specifies, requirements, opencode, containers, run, web, terminal
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,42 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: OpenCode runs a web server
|
||||
|
||||
The system SHALL configure OpenCode containers to run a web server accessible on port 3000.
|
||||
|
||||
#### Scenario: OpenCode container starts
|
||||
- **GIVEN** an OpenCode tool instance
|
||||
- **WHEN** the container starts
|
||||
- **THEN** a web server is running on port 3000 inside the container
|
||||
- **AND** the server serves a web terminal interface
|
||||
- **AND** the container has `tmux` installed
|
||||
- **AND** the container has `ranger` installed
|
||||
|
||||
### Requirement: OpenCode exposes web interface
|
||||
|
||||
The system SHALL mark OpenCode as having both terminal and web interfaces.
|
||||
|
||||
#### Scenario: OpenCode instance created
|
||||
- **GIVEN** a new OpenCode instance
|
||||
- **WHEN** the instance list is displayed
|
||||
- **THEN** both "Open" and "Terminal" buttons are shown
|
||||
|
||||
### Requirement: OpenCode web terminal uses correct port
|
||||
|
||||
The system SHALL use port 3000 when creating tunnels for OpenCode instances.
|
||||
|
||||
#### Scenario: Tunnel created for OpenCode
|
||||
- **GIVEN** an OpenCode instance with `default_port: 3000`
|
||||
- **WHEN** the instance starts and creates a tunnel
|
||||
- **THEN** the tunnel targets `http://container-name:3000`
|
||||
|
||||
### Requirement: OpenCode web terminal displays properly
|
||||
|
||||
The system SHALL serve a functional web terminal interface for OpenCode.
|
||||
|
||||
#### Scenario: User opens OpenCode web UI
|
||||
- **GIVEN** a running OpenCode instance
|
||||
- **WHEN** the user clicks the "Open" button
|
||||
- **THEN** a new tab opens with the OpenCode web interface
|
||||
- **AND** the interface shows a terminal connected to the OpenCode process
|
||||
- **AND** the user can run `tmux` and `ranger` commands
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/project-management (index)
|
||||
dir: openspec/specs/project-management
|
||||
|
||||
## role
|
||||
Defines requirements for a project management system that groups repositories with ownership, access control, and SSH key management.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/project-management/.pi-map.index.md
|
||||
map: openspec/specs/project-management/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/project-management
|
||||
dir: openspec/specs/project-management
|
||||
|
||||
index: openspec/specs/project-management/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines requirements for a project management system that groups repositories with ownership, access control, and SSH key management.
|
||||
## files
|
||||
- spec.md | Defines requirements for a project management system that groups repositories with ownership, access control, and SSH key management. | dep: Project, User, GitRepository, SSHKey, git-repo, ssh-keys
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirements documentation.
|
||||
## tags
|
||||
project, management, ssh, spec, defines, requirements, system, groups
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,87 +0,0 @@
|
||||
# Project Management Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Organize repositories into projects for grouping related work.
|
||||
## Requirements
|
||||
### Requirement: Project Creation
|
||||
The system SHALL allow authenticated users to create new projects and SHALL assign the creator as project owner.
|
||||
|
||||
#### Scenario: Create project
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they create a project with name and description
|
||||
- THEN a project record is created
|
||||
- AND the user is set as owner
|
||||
|
||||
#### Scenario: Reject unauthenticated creation
|
||||
- GIVEN a request without a valid authenticated session
|
||||
- WHEN it attempts to create a project
|
||||
- THEN the system responds with unauthorized status
|
||||
|
||||
### Requirement: Project Listing
|
||||
The system SHALL list projects owned by the authenticated user, including related repositories and default SSH key metadata.
|
||||
|
||||
#### Scenario: List projects
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they view the projects page
|
||||
- THEN all their projects are listed with associated repositories
|
||||
|
||||
#### Scenario: Ownership-scoped listing
|
||||
- GIVEN multiple users with separate projects
|
||||
- WHEN one user requests their project list
|
||||
- THEN only that user's projects are returned
|
||||
|
||||
### Requirement: Project Updates
|
||||
The system SHALL support updating project details for project owners only.
|
||||
|
||||
#### Scenario: Update project
|
||||
- GIVEN a project owner
|
||||
- WHEN they update the name or description
|
||||
- THEN the changes are persisted
|
||||
|
||||
#### Scenario: Non-owner update denied
|
||||
- GIVEN a user who is not the project owner
|
||||
- WHEN they attempt to update project details
|
||||
- THEN the system responds with forbidden status
|
||||
|
||||
### Requirement: Project Deletion
|
||||
The system SHALL support cascading project deletion for project owners.
|
||||
|
||||
#### Scenario: Delete project
|
||||
- GIVEN a project owner
|
||||
- WHEN they delete a project
|
||||
- THEN all associated repositories are deleted
|
||||
- AND all associated SSH keys are removed
|
||||
- AND the project record is deleted
|
||||
|
||||
#### Scenario: Non-owner deletion denied
|
||||
- GIVEN a user who is not the project owner
|
||||
- WHEN they attempt to delete the project
|
||||
- THEN the system responds with forbidden status
|
||||
|
||||
### Requirement: Default SSH Key
|
||||
The system SHALL allow project owners to set a default SSH key per project and SHALL validate ownership for selected keys.
|
||||
|
||||
#### Scenario: Set default key
|
||||
- GIVEN a project with SSH keys
|
||||
- WHEN the owner selects a default key
|
||||
- THEN it's used for git operations in that project
|
||||
|
||||
#### Scenario: Reject foreign key assignment
|
||||
- GIVEN a project owner
|
||||
- WHEN they try setting a default SSH key that does not belong to their allowed scope
|
||||
- THEN the system rejects the request with validation error
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Database models: Project, User, GitRepository, SSHKey
|
||||
- git-repo (for cascading delete)
|
||||
- ssh-keys (for default key)
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/readiness-probe-integration (index)
|
||||
dir: openspec/specs/readiness-probe-integration
|
||||
|
||||
## role
|
||||
Defines requirements for container readiness probe configuration, execution, and result storage during instance startup
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/readiness-probe-integration/.pi-map.index.md
|
||||
map: openspec/specs/readiness-probe-integration/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/readiness-probe-integration
|
||||
dir: openspec/specs/readiness-probe-integration
|
||||
|
||||
index: openspec/specs/readiness-probe-integration/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines requirements for container readiness probe configuration, execution, and result storage during instance startup
|
||||
## files
|
||||
- spec.md | Defines requirements for container readiness probe configuration, execution, and result storage during instance startup | dep: docker, container orchestration, health endpoint, logging system
|
||||
## arch
|
||||
Specification-driven documentation pattern using markdown-based requirements definition with no executable code architecture
|
||||
## tags
|
||||
spec, defines, requirements, container, readiness, probe, configuration, execution
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,51 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Readiness probe configuration
|
||||
The system SHALL use tool type readiness probe configuration during instance startup.
|
||||
|
||||
#### Scenario: Web tool with custom probe
|
||||
- **GIVEN** a tool type with `readiness_probe` configured as:
|
||||
- `command: "curl -f http://localhost:8080/api/health"`
|
||||
- `timeout: 60`
|
||||
- `interval: 5`
|
||||
- **WHEN** an instance of this type starts
|
||||
- **THEN** the system executes the probe command inside the container
|
||||
- **AND** retries every 5 seconds for up to 60 seconds
|
||||
- **AND** the instance remains in "starting" status until probe succeeds
|
||||
|
||||
#### Scenario: Web tool with default probe
|
||||
- **GIVEN** a web-enabled tool type with no `readiness_probe` configured
|
||||
- **WHEN** an instance of this type starts
|
||||
- **THEN** the system uses the default probe: `curl -f http://localhost:{port}`
|
||||
- **AND** retries every 2 seconds for up to 30 seconds
|
||||
|
||||
#### Scenario: Probe command execution
|
||||
- **GIVEN** a readiness probe command
|
||||
- **WHEN** the system executes it inside the container
|
||||
- **THEN** it runs via `docker exec {container_id} sh -c "{command}"`
|
||||
- **AND** stdout/stderr are captured for diagnostics
|
||||
- **AND** exit code 0 indicates success
|
||||
|
||||
### Requirement: Probe result storage
|
||||
The system SHALL store readiness probe results for diagnostics.
|
||||
|
||||
#### Scenario: Successful probe logged
|
||||
- **GIVEN** a readiness probe that succeeds
|
||||
- **WHEN** the probe returns exit code 0
|
||||
- **THEN** the success is logged with timestamp
|
||||
- **AND** the instance status changes to "running"
|
||||
|
||||
#### Scenario: Failed probe logged
|
||||
- **GIVEN** a readiness probe that fails or times out
|
||||
- **WHEN** the probe reaches timeout
|
||||
- **THEN** the failure is logged with last stdout/stderr output
|
||||
- **AND** the instance status changes to "unhealthy"
|
||||
- **AND** the probe output is available via the health endpoint
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
None.
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
None.
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/repo-clone-mode (index)
|
||||
dir: openspec/specs/repo-clone-mode
|
||||
|
||||
## role
|
||||
Defines the contract for host-side git repository cloning operations to enable containerized tools to work with local code.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/repo-clone-mode/.pi-map.index.md
|
||||
map: openspec/specs/repo-clone-mode/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/repo-clone-mode
|
||||
dir: openspec/specs/repo-clone-mode
|
||||
|
||||
index: openspec/specs/repo-clone-mode/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the contract for host-side git repository cloning operations to enable containerized tools to work with local code.
|
||||
## files
|
||||
- spec.md | Specifies requirements for host-side git repository cloning with SSH key preparation and dirty state detection for containerized tool instances. | dep: GitRepository, ToolInstance, SSHKey, Docker Compose, Git, pytest, mypy, ruff, npm
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirements documentation with SSH key management and dirty-state detection concerns.
|
||||
## tags
|
||||
git, spec, specifies, requirements, host, side, repository, cloning
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,59 +0,0 @@
|
||||
# Repository Clone Mode Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Support host-side repository cloning for tool instances, enabling isolated development environments with full git history and SSH key access for container git operations.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Host-side repository cloning
|
||||
The system SHALL clone repositories on the host filesystem before container startup when clone mode is selected.
|
||||
|
||||
#### Scenario: Clone repository with branch selection
|
||||
- **GIVEN** a repository with a remote URL and SSH key
|
||||
- **WHEN** an instance is created in clone mode with branch="feature-x"
|
||||
- **THEN** the system runs `git clone --branch feature-x <remote_url> <instance_dir>/repo-clone/`
|
||||
- **AND** the clone includes full history
|
||||
|
||||
#### Scenario: Clone repository with default branch
|
||||
- **GIVEN** a repository with a remote URL and SSH key
|
||||
- **WHEN** an instance is created in clone mode without specifying a branch
|
||||
- **THEN** the system defaults to branch="main"
|
||||
- **AND** runs `git clone --branch main <remote_url> <instance_dir>/repo-clone/`
|
||||
|
||||
### Requirement: SSH key preparation for containers
|
||||
The system SHALL decrypt and prepare SSH keys for container mounting.
|
||||
|
||||
#### Scenario: Prepare SSH key files
|
||||
- **GIVEN** a repository with an associated SSH key
|
||||
- **WHEN** a clone-mode instance is started
|
||||
- **THEN** the private key is decrypted and written to `instance_dir/.ssh/id_ed25519` with mode 600
|
||||
- **AND** the public key is written to `instance_dir/.ssh/id_ed25519.pub`
|
||||
- **AND** an SSH config is written to `instance_dir/.ssh/config` with `StrictHostKeyChecking no`
|
||||
|
||||
### Requirement: Repository dirty state detection
|
||||
The system SHALL detect uncommitted changes in cloned repositories.
|
||||
|
||||
#### Scenario: Detect clean repository
|
||||
- **GIVEN** a cloned repository with no changes
|
||||
- **WHEN** dirty state is checked
|
||||
- **THEN** the result indicates no uncommitted changes
|
||||
|
||||
#### Scenario: Detect dirty repository
|
||||
- **GIVEN** a cloned repository with modified files
|
||||
- **WHEN** dirty state is checked
|
||||
- **THEN** the result indicates uncommitted changes with file details
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Database models: GitRepository, ToolInstance, SSHKey
|
||||
- Docker Compose volume mounting
|
||||
- Git installed on host and in containers
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/session-lifecycle-ux (index)
|
||||
dir: openspec/specs/session-lifecycle-ux
|
||||
|
||||
## role
|
||||
Defines user experience requirements for session lifecycle management interactions
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/session-lifecycle-ux/.pi-map.index.md
|
||||
map: openspec/specs/session-lifecycle-ux/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/session-lifecycle-ux
|
||||
dir: openspec/specs/session-lifecycle-ux
|
||||
|
||||
index: openspec/specs/session-lifecycle-ux/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines user experience requirements for session lifecycle management interactions
|
||||
## files
|
||||
- spec.md | Defines software requirements for session management UI behaviors including stop confirmation dialogs and immediate deletion updates
|
||||
## arch
|
||||
Specification-driven requirements documentation using behavioral scenario descriptions with explicit user flow states and UI feedback expectations
|
||||
## tags
|
||||
spec, defines, software, requirements, session, management, behaviors, including
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,34 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Stopping a session requires confirmation
|
||||
The system SHALL display a confirmation dialog before stopping a running session.
|
||||
|
||||
#### Scenario: User initiates stop
|
||||
- **WHEN** user clicks the "Stop" button on a running session
|
||||
- **THEN** a confirmation dialog appears asking "Are you sure you want to stop this session?"
|
||||
- **AND** the dialog provides "Cancel" and "Stop" options
|
||||
|
||||
#### Scenario: User confirms stop
|
||||
- **WHEN** user clicks "Stop" in the confirmation dialog
|
||||
- **THEN** the session stops
|
||||
- **AND** the dialog closes
|
||||
|
||||
#### Scenario: User cancels stop
|
||||
- **WHEN** user clicks "Cancel" in the confirmation dialog
|
||||
- **THEN** the dialog closes
|
||||
- **AND** the session remains running
|
||||
|
||||
### Requirement: Deleted sessions disappear from UI immediately
|
||||
The system SHALL update the frontend state immediately after a session is successfully deleted.
|
||||
|
||||
#### Scenario: Delete session
|
||||
- **WHEN** user deletes a session
|
||||
- **AND** the delete API call returns success
|
||||
- **THEN** the session is removed from the visible list
|
||||
- **AND** no page reload is required
|
||||
|
||||
#### Scenario: Delete session failure
|
||||
- **WHEN** user deletes a session
|
||||
- **AND** the delete API call fails
|
||||
- **THEN** the session remains in the list
|
||||
- **AND** an error message is displayed
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/sessions-hub (index)
|
||||
dir: openspec/specs/sessions-hub
|
||||
|
||||
## role
|
||||
Defines technical specifications for a centralized user session management feature that enables viewing, filtering, and terminating active sessions across devices.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/sessions-hub/.pi-map.index.md
|
||||
map: openspec/specs/sessions-hub/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/sessions-hub
|
||||
dir: openspec/specs/sessions-hub
|
||||
|
||||
index: openspec/specs/sessions-hub/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines technical specifications for a centralized user session management feature that enables viewing, filtering, and terminating active sessions across devices.
|
||||
## files
|
||||
- spec.md | Defines technical specifications for a "Sessions Hub" feature including requirements, API endpoints, UI layouts, state management, and quality gates for managing user sessions in a web application. | dep: REST API, TypeScript, React/frontend framework (implied by UI specs and quality gates), polling-based state management, Pydantic/BaseModel
|
||||
## arch
|
||||
Specification-driven design using structured documentation with hierarchical sections (requirements, API, UI, state, quality gates) to enforce contract-first development between frontend and backend teams.
|
||||
## tags
|
||||
sessions, spec, defines, technical, specifications, hub, feature, including
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,115 +0,0 @@
|
||||
# Sessions Hub Specification
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
1. **Sessions Tab**: Navigation item between Dashboard and Projects
|
||||
2. **Active Sessions Display**: Show all running sessions with actions
|
||||
3. **Last Session**: Prominently show last created/accessed session
|
||||
4. **Quick Create**: Create sessions for any project from Sessions page
|
||||
5. **Session Persistence**: Save last_session_id in user config
|
||||
6. **Badge**: Show active session count in navigation
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
1. **Performance**: Load sessions in < 500ms
|
||||
2. **Real-time**: Badge updates with active count
|
||||
3. **Responsive**: Works on mobile and desktop
|
||||
|
||||
## API Specification
|
||||
|
||||
### Existing Endpoints Used
|
||||
|
||||
- `GET /users/me/sessions` - List all user sessions
|
||||
- `POST /projects/{id}/repositories/{id}/instances` - Create instance
|
||||
- `GET /projects` - List projects for selector
|
||||
- `GET /projects/{id}/repositories` - List repos for selector
|
||||
- `GET /tool-types` - List tool types for selector
|
||||
- `GET /users/me/config` - Get user config (with last_session_id)
|
||||
- `PATCH /users/me/config` - Update user config (last_session_id)
|
||||
|
||||
### User Config Schema Update
|
||||
|
||||
```python
|
||||
class UserConfigUpdate(BaseModel):
|
||||
theme: Optional[str] = None
|
||||
default_editor: Optional[str] = None
|
||||
git_user_name: Optional[str] = None
|
||||
git_user_email: Optional[str] = None
|
||||
last_session_id: Optional[str] = None # NEW
|
||||
```
|
||||
|
||||
## UI Specification
|
||||
|
||||
### Sessions Page Layout
|
||||
|
||||
```
|
||||
+------------------------------------------+
|
||||
| Sessions [New Session]|
|
||||
+------------------------------------------+
|
||||
| |
|
||||
| Last Session |
|
||||
| +--------------------------------------+ |
|
||||
| | VS Code Server - My Project [Open] | |
|
||||
| | Running on port 8080 | |
|
||||
| +--------------------------------------+ |
|
||||
| |
|
||||
| Active Sessions (3) |
|
||||
| +----------+ +----------+ +----------+ |
|
||||
| | Session 1| | Session 2| | Session 3| |
|
||||
| | Running | | Running | | Running | |
|
||||
| | [Open] | | [Open] | | [Open] | |
|
||||
| +----------+ +----------+ +----------+ |
|
||||
| |
|
||||
| Recent Sessions |
|
||||
| - Session 4 (stopped) |
|
||||
| - Session 5 (stopped) |
|
||||
| |
|
||||
+------------------------------------------+
|
||||
```
|
||||
|
||||
### Navigation Badge
|
||||
|
||||
```
|
||||
[Dashboard] [Sessions (3)] [Projects] ...
|
||||
```
|
||||
|
||||
Badge shows count of sessions with status === "running".
|
||||
|
||||
### Create Session Dialog
|
||||
|
||||
```
|
||||
+------------------------------------------+
|
||||
| Create New Session |
|
||||
+------------------------------------------+
|
||||
| Project: [Dropdown] |
|
||||
| Repository: [Dropdown] |
|
||||
| Tool Type: [Dropdown] |
|
||||
| Name: [Input] |
|
||||
| |
|
||||
| [Cancel] [Create] |
|
||||
+------------------------------------------+
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### Sessions Context (existing)
|
||||
Already polls `/users/me/sessions` every 10s. Use this for:
|
||||
- Active session count (badge)
|
||||
- Active sessions list
|
||||
- Recent sessions list
|
||||
|
||||
### User Config (existing)
|
||||
Add `last_session_id` field. Update:
|
||||
- On session creation
|
||||
- On session open/resume
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- TypeScript compilation passes
|
||||
- ESLint passes
|
||||
- All sessions load correctly
|
||||
- Badge updates with active count
|
||||
- Last session persists across reloads
|
||||
- Create session works from Sessions page
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/smart-tunnel-recovery (index)
|
||||
dir: openspec/specs/smart-tunnel-recovery
|
||||
|
||||
## role
|
||||
Defines health check classification requirements to distinguish infrastructure tunnel failures from application-level errors and specify their respective UI behaviors and automated recovery procedures.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/smart-tunnel-recovery/.pi-map.index.md
|
||||
map: openspec/specs/smart-tunnel-recovery/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/smart-tunnel-recovery
|
||||
dir: openspec/specs/smart-tunnel-recovery
|
||||
|
||||
index: openspec/specs/smart-tunnel-recovery/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines health check classification requirements to distinguish infrastructure tunnel failures from application-level errors and specify their respective UI behaviors and automated recovery procedures.
|
||||
## files
|
||||
- spec.md | Specifies requirements for classifying tunnel failures versus application errors in a health check system with different UI behaviors and recovery actions.
|
||||
## arch
|
||||
Specification-driven requirements document using scenario-based behavioral specification with clear separation between failure domains (tunnel vs. application), state-based recovery actions, and conditional UI response patterns.
|
||||
## tags
|
||||
spec, specifies, requirements, classifying, tunnel, failures, versus, application
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,45 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tunnel failure classification
|
||||
The system SHALL distinguish tunnel failures from application errors when determining whether to recreate a tunnel.
|
||||
|
||||
#### Scenario: Tunnel is broken
|
||||
- **GIVEN** a running instance with a tunnel URL
|
||||
- **WHEN** the health check receives one of:
|
||||
- Connection refused (ECONNREFUSED)
|
||||
- Connection timeout (ETIMEDOUT)
|
||||
- DNS resolution failure (ENOTFOUND)
|
||||
- Empty response
|
||||
- **THEN** the tunnel status is "unreachable"
|
||||
- **AND** the frontend shows a "tunnel error" badge
|
||||
- **AND** the "Recreate Tunnel" button is enabled
|
||||
|
||||
#### Scenario: Application returns error
|
||||
- **GIVEN** a running instance with a tunnel URL
|
||||
- **WHEN** the health check receives HTTP 502, 503, or 504
|
||||
- **THEN** the tunnel status is "error_response"
|
||||
- **AND** the frontend shows an "app error" badge
|
||||
- **AND** the "Recreate Tunnel" button is NOT shown
|
||||
- **AND** the status code is displayed for diagnostics
|
||||
|
||||
#### Scenario: Application is healthy
|
||||
- **GIVEN** a running instance with a tunnel URL
|
||||
- **WHEN** the health check receives HTTP 200-399
|
||||
- **THEN** the tunnel status is "healthy"
|
||||
- **AND** no error badge is shown
|
||||
|
||||
#### Scenario: Tunnel recreates successfully
|
||||
- **GIVEN** an instance with a broken tunnel (status "unreachable")
|
||||
- **WHEN** the user clicks "Recreate Tunnel"
|
||||
- **THEN** the old cloudflared process is stopped
|
||||
- **AND** a new cloudflared process is started
|
||||
- **AND** the instance URL is updated
|
||||
- **AND** the tunnel status becomes "healthy" (after verification)
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
None.
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
None.
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/ssh-keys (index)
|
||||
dir: openspec/specs/ssh-keys
|
||||
|
||||
## role
|
||||
Defines security requirements for SSH key generation, storage, and access control for Git operations.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/ssh-keys/.pi-map.index.md
|
||||
map: openspec/specs/ssh-keys/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/ssh-keys
|
||||
dir: openspec/specs/ssh-keys
|
||||
|
||||
index: openspec/specs/ssh-keys/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines security requirements for SSH key generation, storage, and access control for Git operations.
|
||||
## files
|
||||
- spec.md | Specifies requirements for generating, managing, and securing Ed25519 SSH keys for git operations with project-scoped access control. | dep: SSHKey, User, Project, cryptography, pytest, mypy, ruff, npm
|
||||
## arch
|
||||
Specification-driven security policy using Ed25519 cryptography with project-scoped RBAC for multi-tenant key isolation.
|
||||
## tags
|
||||
project, spec, specifies, requirements, generating, managing, securing, ed25519
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,62 +0,0 @@
|
||||
# SSH Key Management Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate and manage SSH keys for git operations with external providers.
|
||||
## Requirements
|
||||
### Requirement: Key Generation
|
||||
|
||||
The system SHALL generate Ed25519 SSH key pairs.
|
||||
|
||||
#### Scenario: Generate key
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they request a new SSH key
|
||||
- THEN an Ed25519 key pair is generated
|
||||
- AND the private key is encrypted with Fernet
|
||||
- AND the public key is stored in OpenSSH format
|
||||
|
||||
### Requirement: Key Association
|
||||
The system SHALL only allow project default-key assignment using keys valid for the authenticated owner's project scope.
|
||||
|
||||
#### Scenario: Valid default key assignment
|
||||
- GIVEN a project owner and an eligible SSH key
|
||||
- WHEN the owner sets the key as default for the project
|
||||
- THEN the project stores that key reference
|
||||
|
||||
#### Scenario: Invalid default key assignment
|
||||
- GIVEN a project owner
|
||||
- WHEN the owner attempts to set an ineligible SSH key as project default
|
||||
- THEN the system responds with validation failure
|
||||
|
||||
### Requirement: Key Display
|
||||
|
||||
The system SHALL display public keys for copying.
|
||||
|
||||
#### Scenario: Copy public key
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they view their SSH keys
|
||||
- THEN each public key is displayed in OpenSSH format
|
||||
- AND a copy button is available
|
||||
|
||||
### Requirement: Key Deletion
|
||||
|
||||
The system SHALL support key removal.
|
||||
|
||||
#### Scenario: Delete key
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they delete an SSH key
|
||||
- THEN it's removed from the database
|
||||
- AND the key files are deleted
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Database models: SSHKey, User, Project
|
||||
- cryptography library for key generation
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-config-management (index)
|
||||
dir: openspec/specs/tool-config-management
|
||||
|
||||
## role
|
||||
Defines requirements for a tool configuration management system with runtime fields, split-pane UI, JSON editors, and validation.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-config-management/.pi-map.index.md
|
||||
map: openspec/specs/tool-config-management/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-config-management
|
||||
dir: openspec/specs/tool-config-management
|
||||
|
||||
index: openspec/specs/tool-config-management/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines requirements for a tool configuration management system with runtime fields, split-pane UI, JSON editors, and validation.
|
||||
## files
|
||||
- spec.md | Defines requirements for a tool configuration system with runtime fields, split-pane UI, JSON editors, and validation
|
||||
## arch
|
||||
Specification-driven architecture using markdown-based requirements documentation with UI/UX patterns for split-pane interfaces, JSON schema validation, and runtime field configuration.
|
||||
## tags
|
||||
spec, defines, requirements, tool, configuration, system, runtime, fields
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,53 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tool config supports runtime fields
|
||||
The system SHALL support additional configuration fields for tool instances: `start_command`, `port`, `working_directory`, `environment_variables`, and `volumes`.
|
||||
|
||||
#### Scenario: Create config with runtime fields
|
||||
- **WHEN** user creates a tool config with start_command="npm start", port=3000, working_directory="/app"
|
||||
- **THEN** the config is saved with all fields populated
|
||||
|
||||
#### Scenario: Environment variables as JSON
|
||||
- **WHEN** user sets environment_variables to {"NODE_ENV": "production", "API_KEY": "secret"}
|
||||
- **THEN** the system stores and returns the config with the JSON object preserved
|
||||
|
||||
#### Scenario: Volumes as JSON
|
||||
- **WHEN** user sets volumes to [{"host": "/data", "container": "/app/data", "mode": "rw"}]
|
||||
- **THEN** the system stores and returns the config with the JSON array preserved
|
||||
|
||||
### Requirement: Split-pane UI for tool configs
|
||||
The system SHALL present tool configs in a split-pane layout with a list on the left and detail/edit panel on the right.
|
||||
|
||||
#### Scenario: Browse tool configs
|
||||
- **WHEN** user navigates to /tool-configs
|
||||
- **THEN** the left panel displays a scrollable list of all tool configs grouped by tool type
|
||||
|
||||
#### Scenario: Select config to edit
|
||||
- **WHEN** user clicks on a config in the left panel
|
||||
- **THEN** the right panel displays the config details in an editable form
|
||||
|
||||
#### Scenario: Create new config
|
||||
- **WHEN** user clicks "New Config" button
|
||||
- **THEN** a blank form appears in the right panel for creating a new config
|
||||
|
||||
### Requirement: JSON editor for complex fields
|
||||
The system SHALL provide user-friendly editors for JSON fields (environment_variables and volumes) that validate JSON syntax.
|
||||
|
||||
#### Scenario: Valid JSON input
|
||||
- **WHEN** user enters valid JSON in the environment_variables field
|
||||
- **THEN** the form accepts the input and shows a green indicator
|
||||
|
||||
#### Scenario: Invalid JSON input
|
||||
- **WHEN** user enters invalid JSON in the environment_variables field
|
||||
- **THEN** the form shows a red error indicator and prevents saving
|
||||
|
||||
### Requirement: Config validation
|
||||
The system SHALL validate tool config fields before saving.
|
||||
|
||||
#### Scenario: Invalid port number
|
||||
- **WHEN** user enters port=70000
|
||||
- **THEN** the system rejects the config with error "Port must be between 1 and 65535"
|
||||
|
||||
#### Scenario: Missing required fields
|
||||
- **WHEN** user attempts to save a config without key or tool_type_id
|
||||
- **THEN** the system rejects the config with error "Key is required"
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-instances (index)
|
||||
dir: openspec/specs/tool-instances
|
||||
|
||||
## role
|
||||
Defines requirements for managing tool instances with health monitoring, tunnel connectivity, clone mode, and SSH key operations.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-instances/.pi-map.index.md
|
||||
map: openspec/specs/tool-instances/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-instances
|
||||
dir: openspec/specs/tool-instances
|
||||
|
||||
index: openspec/specs/tool-instances/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines requirements for managing tool instances with health monitoring, tunnel connectivity, clone mode, and SSH key operations.
|
||||
## files
|
||||
- spec.md | Define modified and added requirements for a tool instance management system including status monitoring, health checks, tunnel management, clone mode operations, and SSH key handling
|
||||
## arch
|
||||
Specification-driven requirements document using structured markdown with sections for status, health checks, tunnels, clone mode, and SSH keys.
|
||||
## tags
|
||||
management, spec, define, modified, added, requirements, tool, instance
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,95 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### 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
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Health check endpoint enhancement
|
||||
The system SHALL provide detailed health information through the health check endpoint.
|
||||
|
||||
#### 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
|
||||
|
||||
### Requirement: Smart tunnel recreation
|
||||
The system SHALL only allow tunnel recreation when the tunnel itself is broken.
|
||||
|
||||
#### 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
|
||||
|
||||
#### 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
|
||||
|
||||
### Requirement: Clone mode instance creation
|
||||
The system SHALL support creating tool instances with a clone mode that clones the repository into the instance directory.
|
||||
|
||||
#### 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.
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-port-configuration (index)
|
||||
dir: openspec/specs/tool-port-configuration
|
||||
|
||||
## role
|
||||
Defines validation requirements for tool port configurations including default ports, compose template exposure, and multi-interface support.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-port-configuration/.pi-map.index.md
|
||||
map: openspec/specs/tool-port-configuration/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-port-configuration
|
||||
dir: openspec/specs/tool-port-configuration
|
||||
|
||||
index: openspec/specs/tool-port-configuration/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines validation requirements for tool port configurations including default ports, compose template exposure, and multi-interface support.
|
||||
## files
|
||||
- spec.md | Defines requirements for tool type validation including default ports, compose template port exposure, and multiple interface support
|
||||
## arch
|
||||
Specification-driven requirements document using markdown-based declarative specification pattern.
|
||||
## tags
|
||||
spec, defines, requirements, tool, type, validation, including, default
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,38 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tool types must define a default port
|
||||
|
||||
The system SHALL require all tool types to specify a `default_port`.
|
||||
|
||||
#### Scenario: Creating tool type without port
|
||||
- **GIVEN** a user creating a new tool type
|
||||
- **WHEN** they omit the `default_port` field
|
||||
- **THEN** the system rejects the request with a 422 error
|
||||
|
||||
#### Scenario: Creating tool type with port
|
||||
- **GIVEN** a user creating a new tool type with `default_port: 3000`
|
||||
- **WHEN** the request is submitted
|
||||
- **THEN** the tool type is created successfully
|
||||
|
||||
### Requirement: Tool type port must be exposed in compose template
|
||||
|
||||
The system SHALL validate that the compose template exposes the port defined in `default_port`.
|
||||
|
||||
#### Scenario: Port mismatch
|
||||
- **GIVEN** a tool type with `default_port: 8443`
|
||||
- **WHEN** the compose template only exposes port `3000`
|
||||
- **THEN** the system rejects with an error indicating the port mismatch
|
||||
|
||||
#### Scenario: Port exposed correctly
|
||||
- **GIVEN** a tool type with `default_port: 8443`
|
||||
- **WHEN** the compose template exposes port `8443` via `ports: ["8443:8443"]`
|
||||
- **THEN** the tool type is accepted
|
||||
|
||||
### Requirement: Tool types support multiple interfaces
|
||||
|
||||
The system SHALL allow tool types to specify multiple interfaces.
|
||||
|
||||
#### Scenario: Tool with web and terminal interfaces
|
||||
- **GIVEN** a tool type with `interfaces: ["terminal", "web"]`
|
||||
- **WHEN** an instance is created
|
||||
- **THEN** the instance shows both "Open" (web) and "Terminal" buttons in the UI
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-terminal-startup-command (index)
|
||||
dir: openspec/specs/tool-terminal-startup-command
|
||||
|
||||
## role
|
||||
Defines requirements for pre-shell initialization commands in terminal tool configurations.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-terminal-startup-command/.pi-map.index.md
|
||||
map: openspec/specs/tool-terminal-startup-command/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-terminal-startup-command
|
||||
dir: openspec/specs/tool-terminal-startup-command
|
||||
|
||||
index: openspec/specs/tool-terminal-startup-command/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines requirements for pre-shell initialization commands in terminal tool configurations.
|
||||
## files
|
||||
- spec.md | Specifies requirements for adding an optional `startup_command` field to terminal tool types that executes before the interactive shell in new terminal sessions. | dep: tool-types-definition, tool-terminal
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirements documents with field extension patterns for tool type schemas.
|
||||
## tags
|
||||
terminal, tool, types, spec, specifies, requirements, adding, optional
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,66 +0,0 @@
|
||||
# Terminal Startup Command Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Allow tool type authors to define a startup command that executes for each new terminal session.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Terminal tool types can define a startup command
|
||||
|
||||
The system SHALL allow tool types to specify a `startup_command` that runs before the interactive shell for each new terminal session.
|
||||
|
||||
#### Scenario: Tool type with startup command
|
||||
- **GIVEN** a tool type with `interface_type` = "terminal" and `startup_command` = "cd /workspace && ls"
|
||||
- **WHEN** a user opens a terminal session to an instance of this tool type
|
||||
- **THEN** the startup command executes before the interactive shell starts
|
||||
- **AND** the user sees the output of the startup command in the terminal
|
||||
|
||||
#### Scenario: Tool type without startup command
|
||||
- **GIVEN** a tool type with `interface_type` = "terminal" and no `startup_command`
|
||||
- **WHEN** a user opens a terminal session
|
||||
- **THEN** the interactive shell starts immediately without any startup execution
|
||||
|
||||
#### Scenario: Startup command failure does not block shell
|
||||
- **GIVEN** a tool type with `startup_command` = "exit 1"
|
||||
- **WHEN** a user opens a terminal session
|
||||
- **THEN** the startup command runs and fails
|
||||
- **AND** the interactive shell still starts afterward
|
||||
|
||||
### Requirement: Startup command is stored on the tool type
|
||||
|
||||
The system SHALL persist `startup_command` as a field on the `tool_types` table.
|
||||
|
||||
#### Scenario: Create tool type with startup command
|
||||
- **GIVEN** a user creating a tool type
|
||||
- **WHEN** they provide `startup_command` = "source /etc/profile"
|
||||
- **THEN** the tool type is created with the startup command stored
|
||||
|
||||
#### Scenario: Update tool type startup command
|
||||
- **GIVEN** an existing tool type with a startup command
|
||||
- **WHEN** an admin updates `startup_command` to a new value
|
||||
- **THEN** the tool type is updated
|
||||
- **AND** new terminal sessions use the updated startup command
|
||||
|
||||
### Requirement: Startup command is optional
|
||||
|
||||
The system SHALL treat `startup_command` as an optional field on tool types.
|
||||
|
||||
#### Scenario: Create tool type without startup command
|
||||
- **GIVEN** a user creating a terminal tool type
|
||||
- **WHEN** they omit `startup_command`
|
||||
- **THEN** the tool type is created successfully
|
||||
- **AND** terminal sessions start normally without a startup command
|
||||
|
||||
## Dependencies
|
||||
|
||||
- tool-types-definition (model and API)
|
||||
- tool-terminal (session execution)
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-terminal (index)
|
||||
dir: openspec/specs/tool-terminal
|
||||
|
||||
## role
|
||||
Defines the specification for a browser-based terminal interface that enables secure, real-time access to running Docker containers via WebSocket connections.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-terminal/.pi-map.index.md
|
||||
map: openspec/specs/tool-terminal/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-terminal
|
||||
dir: openspec/specs/tool-terminal
|
||||
|
||||
index: openspec/specs/tool-terminal/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines the specification for a browser-based terminal interface that enables secure, real-time access to running Docker containers via WebSocket connections.
|
||||
## files
|
||||
- spec.md | Specifies requirements for a browser-based WebSocket terminal system for accessing running Docker containers with session management, I/O streaming, and access control. | dep: tool-instances, auth-oauth, xterm.js, ptyprocess
|
||||
## arch
|
||||
WebSocket-based streaming architecture with session management, bidirectional I/O streaming, and access control for containerized environments.
|
||||
## tags
|
||||
spec, specifies, requirements, browser, websocket, terminal, system, accessing
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,95 +0,0 @@
|
||||
# Web Terminal Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Provide browser-based terminal access to running tool containers.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: WebSocket Terminal
|
||||
|
||||
The system SHALL provide terminal sessions via WebSocket.
|
||||
|
||||
#### Scenario: Open terminal
|
||||
- GIVEN a running tool instance
|
||||
- WHEN the user opens the terminal
|
||||
- THEN a WebSocket connection is established
|
||||
- AND a shell is spawned in the container via `docker exec`
|
||||
|
||||
#### Scenario: Open terminal with startup command
|
||||
- GIVEN a running tool instance with a tool type that has `startup_command` set
|
||||
- WHEN the user opens the terminal
|
||||
- THEN a WebSocket connection is established
|
||||
- AND the startup command is executed before the interactive shell
|
||||
- AND the shell is spawned in the container via `docker exec`
|
||||
|
||||
#### Scenario: Open terminal without startup command
|
||||
- GIVEN a running tool instance with a tool type that has no `startup_command`
|
||||
- WHEN the user opens the terminal
|
||||
- THEN a WebSocket connection is established
|
||||
- AND the shell spawns directly without any startup execution
|
||||
|
||||
### Requirement: Terminal I/O
|
||||
|
||||
The system SHALL stream terminal I/O via WebSocket.
|
||||
|
||||
#### Scenario: Command execution
|
||||
- GIVEN an active terminal session
|
||||
- WHEN the user types a command
|
||||
- THEN stdin is forwarded to the container shell
|
||||
- AND stdout/stderr is streamed back to the browser
|
||||
|
||||
### Requirement: Terminal Resize
|
||||
|
||||
The system SHALL support terminal resize events.
|
||||
|
||||
#### Scenario: Resize terminal
|
||||
- GIVEN an active terminal session
|
||||
- WHEN the browser window is resized
|
||||
- THEN the terminal dimensions (COLS, ROWS) are updated
|
||||
- AND the shell receives the new size
|
||||
|
||||
### Requirement: Session Management
|
||||
|
||||
The system SHALL manage terminal sessions.
|
||||
|
||||
#### Scenario: Multiple sessions
|
||||
- GIVEN a running tool instance
|
||||
- WHEN multiple terminals are opened
|
||||
- THEN each has an independent session
|
||||
|
||||
#### Scenario: Cleanup
|
||||
- GIVEN an active terminal session
|
||||
- WHEN the user disconnects
|
||||
- THEN the session is cleaned up
|
||||
- AND the shell process is terminated
|
||||
|
||||
#### Scenario: Reset terminal session runs startup command
|
||||
- GIVEN an active terminal session
|
||||
- WHEN the user resets the session
|
||||
- THEN a new shell is spawned
|
||||
- AND the startup command executes before the new interactive shell
|
||||
|
||||
### Requirement: Access Control
|
||||
|
||||
The system SHALL restrict terminal access.
|
||||
|
||||
#### Scenario: Unauthorized access
|
||||
- GIVEN a tool instance owned by user A
|
||||
- WHEN user B tries to access the terminal
|
||||
- THEN the connection is rejected with 403
|
||||
|
||||
## Dependencies
|
||||
|
||||
- tool-instances (running containers)
|
||||
- auth-oauth (authentication)
|
||||
- xterm.js frontend library
|
||||
- ptyprocess for pseudo-TTY
|
||||
|
||||
## Quality Gates
|
||||
|
||||
- `pytest` must pass
|
||||
- `mypy .` must pass
|
||||
- `ruff check .` must pass
|
||||
- `npm run typecheck` must pass
|
||||
- `npm run lint` must pass
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-type-port-visibility (index)
|
||||
dir: openspec/specs/tool-type-port-visibility
|
||||
|
||||
## role
|
||||
Defines validation rules for conditionally showing or hiding port configuration fields based on whether a tool type requires network port settings.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-type-port-visibility/.pi-map.index.md
|
||||
map: openspec/specs/tool-type-port-visibility/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-type-port-visibility
|
||||
dir: openspec/specs/tool-type-port-visibility
|
||||
|
||||
index: openspec/specs/tool-type-port-visibility/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines validation rules for conditionally showing or hiding port configuration fields based on whether a tool type requires network port settings.
|
||||
## files
|
||||
- spec.md | Defines requirements for conditional port configuration visibility and validation based on a tool type's `requires_port` flag
|
||||
## arch
|
||||
Specification-driven validation pattern using a single markdown specification file to declaratively define conditional UI visibility and form validation requirements.
|
||||
## tags
|
||||
port, spec, defines, requirements, conditional, configuration, visibility, validation
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,50 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Port Configuration Visibility
|
||||
The system SHALL control whether port configuration is relevant for a tool type.
|
||||
|
||||
#### Scenario: Web tool requires port
|
||||
- GIVEN a tool type with `requires_port` = true
|
||||
- WHEN the tool type is displayed in the UI
|
||||
- THEN port configuration fields are shown
|
||||
- AND default_port is validated as required
|
||||
|
||||
#### Scenario: Terminal tool does not require port
|
||||
- GIVEN a tool type with `requires_port` = false
|
||||
- WHEN the tool type is displayed in the UI
|
||||
- THEN port configuration fields are hidden
|
||||
- AND default_port validation is skipped
|
||||
- AND port_override in tool configs is not shown
|
||||
|
||||
### Requirement: Port Validation Based on requires_port
|
||||
The API SHALL validate port fields conditionally based on requires_port.
|
||||
|
||||
#### Scenario: Validate port for web tools
|
||||
- GIVEN a tool type with `requires_port` = true
|
||||
- WHEN creating or updating without a default_port
|
||||
- THEN the system returns 400 Bad Request
|
||||
|
||||
#### Scenario: Skip port validation for terminal tools
|
||||
- GIVEN a tool type with `requires_port` = false
|
||||
- WHEN creating or updating without a default_port
|
||||
- THEN the request succeeds
|
||||
- AND default_port defaults to 0 or null
|
||||
|
||||
### Requirement: UI Conditional Rendering
|
||||
The frontend SHALL conditionally render port-related UI elements.
|
||||
|
||||
#### Scenario: Hide port in tool list
|
||||
- GIVEN a terminal tool type
|
||||
- WHEN displayed in the tool workshop list
|
||||
- THEN port information is not shown
|
||||
|
||||
#### Scenario: Hide port in editor
|
||||
- GIVEN a terminal tool type being edited
|
||||
- WHEN the editor form is rendered
|
||||
- THEN the Default Port field is hidden
|
||||
- AND the readiness probe fields are shown (still relevant)
|
||||
|
||||
#### Scenario: Show port for web tools
|
||||
- GIVEN a web tool type being edited
|
||||
- WHEN the editor form is rendered
|
||||
- THEN the Default Port field is visible and required
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-type-single-interface (index)
|
||||
dir: openspec/specs/tool-type-single-interface
|
||||
|
||||
## role
|
||||
Defines specification requirements for a tool type system that enforces single interface constraints, validates allowed values, and handles legacy data migration.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-type-single-interface/.pi-map.index.md
|
||||
map: openspec/specs/tool-type-single-interface/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-type-single-interface
|
||||
dir: openspec/specs/tool-type-single-interface
|
||||
|
||||
index: openspec/specs/tool-type-single-interface/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines specification requirements for a tool type system that enforces single interface constraints, validates allowed values, and handles legacy data migration.
|
||||
## files
|
||||
- spec.md | Defines requirements for enforcing single interface types, validating allowed values, and migrating legacy data for a tool type system
|
||||
## arch
|
||||
Specification-driven architecture using markdown-based requirements documentation with validation rules, allowed value constraints, and data migration patterns for backward compatibility.
|
||||
## tags
|
||||
spec, defines, requirements, enforcing, single, interface, types, validating
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,39 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Single Interface Type Enforcement
|
||||
The system SHALL enforce that each tool type has exactly one interface type.
|
||||
|
||||
#### Scenario: Create with single interface
|
||||
- GIVEN a tool type creation request with `interface_type` = "web"
|
||||
- WHEN the request is processed
|
||||
- THEN the tool type is created successfully
|
||||
- AND the interface type is stored as a single string
|
||||
|
||||
#### Scenario: Reject multiple interfaces
|
||||
- GIVEN a legacy request with `interfaces` array
|
||||
- WHEN the request is processed
|
||||
- THEN the system returns 400 Bad Request
|
||||
- AND the error message indicates that `interface_type` (string) should be used instead
|
||||
|
||||
### Requirement: Interface Type Validation
|
||||
The system SHALL validate that interface_type is one of the allowed values.
|
||||
|
||||
#### Scenario: Valid interface types
|
||||
- GIVEN interface_type values "web" or "terminal"
|
||||
- WHEN a tool type is created or updated
|
||||
- THEN the request is accepted
|
||||
|
||||
#### Scenario: Invalid interface type
|
||||
- GIVEN interface_type value "ssh"
|
||||
- WHEN a tool type is created or updated
|
||||
- THEN the system returns 400 Bad Request
|
||||
|
||||
### Requirement: Data Migration
|
||||
The system SHALL migrate existing tool types from interfaces array to single interface_type.
|
||||
|
||||
#### Scenario: Migrate existing records
|
||||
- GIVEN existing tool types with interfaces = ["web"] or ["terminal"]
|
||||
- WHEN the migration runs
|
||||
- THEN each record gets interface_type = interfaces[0]
|
||||
- AND requires_port is set based on the interface type
|
||||
- AND the old interfaces column is removed
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-types-definition (index)
|
||||
dir: openspec/specs/tool-types-definition
|
||||
|
||||
## role
|
||||
Defines requirements for a tool type management system with CRUD API, Docker template validation, and variable substitution for development environments.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-types-definition/.pi-map.index.md
|
||||
map: openspec/specs/tool-types-definition/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-types-definition
|
||||
dir: openspec/specs/tool-types-definition
|
||||
|
||||
index: openspec/specs/tool-types-definition/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines requirements for a tool type management system with CRUD API, Docker template validation, and variable substitution for development environments.
|
||||
## files
|
||||
- spec.md | Defines requirements for a tool type management system with CRUD API, Docker template validation, and variable substitution for development environments. | dep: REST API, Docker Compose, YAML parser, authentication/authorization system, database ORM
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirements documentation with Docker template patterns and variable substitution mechanisms for environment configuration.
|
||||
## tags
|
||||
spec, defines, requirements, tool, type, management, system, crud
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,144 +0,0 @@
|
||||
## 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
|
||||
- `category`: string (e.g., "editor", "notebook")
|
||||
- `interface_type`: single string — "web" or "terminal"
|
||||
- `requires_port`: boolean indicating if port/tunnel configuration is needed
|
||||
- `compose_template`: Docker Compose YAML string
|
||||
- `dockerfile_template`: Dockerfile string
|
||||
- `definition_type`: string — "compose" or "dockerfile"
|
||||
- `required_variables`: list of required template variables
|
||||
- `startup_command`: optional text — command to run before interactive shell for terminal sessions
|
||||
- `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 `interface_type` is "web" or "terminal"
|
||||
- AND validates `requires_port` is boolean
|
||||
- AND validates the compose template YAML (if definition_type is "compose")
|
||||
- AND validates all required variables are present in template
|
||||
- AND accepts optional `startup_command` field
|
||||
- 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 accepts optional `startup_command` field
|
||||
- AND returns 200 OK with updated tool type
|
||||
|
||||
#### Scenario: Get tool type includes startup command
|
||||
- GIVEN an authenticated user
|
||||
- WHEN they GET /api/tool-types/{id}
|
||||
- THEN the response includes `startup_command` if set
|
||||
|
||||
#### 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
|
||||
|
||||
### Requirement: Port requirement indication
|
||||
The system SHALL allow tool types to indicate whether they require port configuration.
|
||||
|
||||
#### Scenario: Web tool requires port
|
||||
- GIVEN a tool type with `interface_type` = "web"
|
||||
- WHEN the tool type is created or updated
|
||||
- THEN `requires_port` SHALL default to true
|
||||
- AND port-related configuration is shown in the UI
|
||||
|
||||
#### Scenario: Terminal tool does not require port
|
||||
- GIVEN a tool type with `interface_type` = "terminal"
|
||||
- WHEN the tool type is created or updated
|
||||
- THEN `requires_port` SHALL default to false
|
||||
- AND port-related configuration is hidden in the UI
|
||||
|
||||
### Requirement: Single interface validation
|
||||
The system SHALL enforce that each tool type has exactly one interface type.
|
||||
|
||||
#### Scenario: Invalid interface type
|
||||
- GIVEN a tool type creation request with `interface_type` = "invalid"
|
||||
- WHEN the request is processed
|
||||
- THEN the system returns 400 Bad Request
|
||||
- AND the error message indicates valid values are "web" or "terminal"
|
||||
|
||||
#### Scenario: Missing interface type
|
||||
- GIVEN a tool type creation request without `interface_type`
|
||||
- WHEN the request is processed
|
||||
- THEN the system returns 400 Bad Request
|
||||
- AND the error message indicates interface_type is required
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-types (index)
|
||||
dir: openspec/specs/tool-types
|
||||
|
||||
## role
|
||||
Defines specifications for a database-driven tool type management system that replaces hardcoded tool definitions with configurable, migratable records.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tool-types/.pi-map.index.md
|
||||
map: openspec/specs/tool-types/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tool-types
|
||||
dir: openspec/specs/tool-types
|
||||
|
||||
index: openspec/specs/tool-types/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines specifications for a database-driven tool type management system that replaces hardcoded tool definitions with configurable, migratable records.
|
||||
## files
|
||||
- spec.md | Defines modified requirements for a tool type management system with database-stored definitions, Docker Compose template validation, and migration of built-in tools to regular records. | dep: database, docker compose validation, migration system
|
||||
## arch
|
||||
Specification-driven design using markdown-based requirements docs with Docker Compose validation rules and migration patterns for built-in to dynamic tool type conversion.
|
||||
## tags
|
||||
database, spec, defines, modified, requirements, tool, type, management
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,42 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Tool Type Model
|
||||
|
||||
The system SHALL store tool type definitions in the database without built-in vs custom distinction.
|
||||
|
||||
#### Scenario: Create tool type
|
||||
- GIVEN an admin user
|
||||
- WHEN they define a new tool type
|
||||
- THEN the following fields are stored:
|
||||
- name: Tool identifier
|
||||
- description: Human-readable description
|
||||
- docker_compose_template: Compose file template
|
||||
- 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")
|
||||
|
||||
#### 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: 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.
|
||||
|
||||
### Requirement: Template Validation
|
||||
|
||||
The system SHALL validate Docker Compose templates.
|
||||
|
||||
#### Scenario: Invalid template
|
||||
- GIVEN an invalid Docker Compose template
|
||||
- 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
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/traefik-deployment (index)
|
||||
dir: openspec/specs/traefik-deployment
|
||||
|
||||
## role
|
||||
Defines requirements and documentation standards for Traefik reverse proxy deployment using Docker Compose.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/traefik-deployment/.pi-map.index.md
|
||||
map: openspec/specs/traefik-deployment/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/traefik-deployment
|
||||
dir: openspec/specs/traefik-deployment
|
||||
|
||||
index: openspec/specs/traefik-deployment/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines requirements and documentation standards for Traefik reverse proxy deployment using Docker Compose.
|
||||
## files
|
||||
- spec.md | Specifies requirements for Traefik Docker Compose deployment configuration and environment variable documentation | dep: Traefik, Docker Compose, Authentik, OIDC
|
||||
## arch
|
||||
Specification-driven configuration with environment-based parameterization and infrastructure-as-code patterns.
|
||||
## tags
|
||||
traefik, spec, specifies, requirements, docker, compose, deployment, configuration
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,31 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Traefik Docker Compose
|
||||
|
||||
The system SHALL provide a `docker-compose.traefik.yml` for deployment behind an existing Traefik reverse proxy.
|
||||
|
||||
#### Scenario: Service labels
|
||||
- GIVEN the traefik deployment configuration
|
||||
- WHEN services are started
|
||||
- THEN `docker-compose.traefik.yml` SHALL define Traefik Docker labels for each service
|
||||
- AND all routing rules SHALL use configurable domain names
|
||||
|
||||
#### Scenario: Environment variables
|
||||
- GIVEN the traefik deployment configuration
|
||||
- WHEN configuring the deployment
|
||||
- THEN all domain names SHALL be configurable via environment variables
|
||||
- AND the proxy web name SHALL be configurable via environment variable
|
||||
|
||||
### Requirement: Environment Configuration
|
||||
|
||||
The system SHALL document all required environment variables for traefik deployment.
|
||||
|
||||
#### Scenario: Required variables
|
||||
- GIVEN a new deployment
|
||||
- WHEN setting up environment variables
|
||||
- THEN `.env.example` SHALL document:
|
||||
- `API_DOMAIN` - domain for API service
|
||||
- `WEB_DOMAIN` - domain for web frontend
|
||||
- `AUTHENTIK_DOMAIN` - domain for Authentik instance
|
||||
- `PROXY_WEB_NAME` - name for web proxy service
|
||||
- All Authentik OIDC configuration variables
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tunnel-health-monitoring (index)
|
||||
dir: openspec/specs/tunnel-health-monitoring
|
||||
|
||||
## role
|
||||
Defines behavioral specifications for health monitoring and automatic recovery of cloudflared tunnel connections to ensure high availability.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/tunnel-health-monitoring/.pi-map.index.md
|
||||
map: openspec/specs/tunnel-health-monitoring/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/tunnel-health-monitoring
|
||||
dir: openspec/specs/tunnel-health-monitoring
|
||||
|
||||
index: openspec/specs/tunnel-health-monitoring/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines behavioral specifications for health monitoring and automatic recovery of cloudflared tunnel connections to ensure high availability.
|
||||
## files
|
||||
- spec.md | Defines requirements for monitoring and recreating cloudflared tunnels for running instances | dep: cloudflared, HTTP health checks, UI components
|
||||
## arch
|
||||
Specification-driven requirements document using markdown-based behavioral specification pattern with no executable code, focusing on system-level observability and self-healing tunnel infrastructure.
|
||||
## tags
|
||||
cloudflared, spec, defines, requirements, monitoring, recreating, tunnels, running
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,35 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: System monitors tunnel health
|
||||
The system SHALL periodically check if active tunnel URLs are reachable and mark them as erroneous if not.
|
||||
|
||||
#### Scenario: Healthy tunnel
|
||||
- **WHEN** a tunnel health check is performed on a running instance
|
||||
- **THEN** the system receives an HTTP 2xx response
|
||||
- **AND** the instance status remains "running"
|
||||
|
||||
#### Scenario: Broken tunnel
|
||||
- **WHEN** a tunnel health check is performed on a running instance
|
||||
- **AND** the response is not HTTP 2xx or the request fails
|
||||
- **THEN** the instance is marked with tunnel_error status
|
||||
- **AND** a visual error indicator is displayed in the UI
|
||||
|
||||
### Requirement: Users can recreate broken tunnels
|
||||
The system SHALL allow users to regenerate a temporary tunnel for a running instance without restarting the instance.
|
||||
|
||||
#### Scenario: Recreate tunnel
|
||||
- **WHEN** user clicks "Recreate Tunnel" button on an instance with a broken tunnel
|
||||
- **THEN** the system stops the existing cloudflared process
|
||||
- **AND** starts a new cloudflared tunnel
|
||||
- **AND** updates the instance URL
|
||||
- **AND** the new URL is displayed in the UI
|
||||
|
||||
#### Scenario: Recreate tunnel success
|
||||
- **WHEN** tunnel recreation completes successfully
|
||||
- **THEN** the error indicator is removed
|
||||
- **AND** the instance shows as healthy
|
||||
|
||||
#### Scenario: Recreate tunnel failure
|
||||
- **WHEN** tunnel recreation fails
|
||||
- **THEN** the error indicator remains
|
||||
- **AND** an error message is displayed to the user
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/user-config (index)
|
||||
dir: openspec/specs/user-config
|
||||
|
||||
## role
|
||||
Defines data models and API contracts for a user-configurable preferences system with JSONB storage and theme integration.
|
||||
## parent
|
||||
index: openspec/specs/.pi-map.index.md
|
||||
map: openspec/specs/.pi-map.md
|
||||
## children
|
||||
-
|
||||
## files
|
||||
- spec.md
|
||||
## links
|
||||
index: openspec/specs/user-config/.pi-map.index.md
|
||||
map: openspec/specs/user-config/.pi-map.md
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
@@ -1,19 +0,0 @@
|
||||
# openspec/specs/user-config
|
||||
dir: openspec/specs/user-config
|
||||
|
||||
index: openspec/specs/user-config/.pi-map.index.md
|
||||
|
||||
## role
|
||||
Defines data models and API contracts for a user-configurable preferences system with JSONB storage and theme integration.
|
||||
## files
|
||||
- spec.md | Defines specifications for a user configuration system that stores JSONB key-value preferences, supports specific config keys, and integrates with frontend theme application. | dep: UserConfig, User, auth-oauth, pytest, mypy, ruff, npm
|
||||
## arch
|
||||
Specification-driven architecture using markdown-based API documentation with JSONB schema definitions for flexible key-value storage.
|
||||
## tags
|
||||
user, spec, defines, specifications, configuration, system, stores, jsonb
|
||||
## symbols
|
||||
-
|
||||
## workflows
|
||||
-
|
||||
## dirty
|
||||
-
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user