docs(openspec): add OpenSpec changes for FN-005, FN-006, FN-008, FN-009, FN-010
- Add frontend-foundation change (FN-005) with 46 tasks - Add deployment-config change (FN-006) with 27 tasks - Add runfusion-poc/opencode-poc change (FN-008) with 25 tasks - Add config-secrets change (FN-009) with 31 tasks - Add codeserver-spawn change (FN-010) with 38 tasks - Include project specsheet and configuration - Archive completed deployment-config change
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-14
|
||||
@@ -0,0 +1,65 @@
|
||||
## Context
|
||||
|
||||
OpenCode is an AI-powered terminal-based development environment with a web interface. Unlike code-server which is a full web IDE, OpenCode provides a terminal experience accessible through the browser. This POC validates that the spawn system handles different runtime types including web terminal forwarding.
|
||||
|
||||
Current state:
|
||||
- OpenCode manifest exists in apps/api/app/tools/manifests/opencode.yml
|
||||
- No container image or runtime defined yet
|
||||
- No health reporting mechanism
|
||||
- Spawn infrastructure will be built in FN-010
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Define OpenCode as a spawnable tool
|
||||
- Provide web terminal interface in container
|
||||
- Report health status (running/idle/error)
|
||||
- Support interactive terminal sessions
|
||||
|
||||
**Non-Goals:**
|
||||
- Full task queue or job scheduler
|
||||
- Persistent process management
|
||||
- Log streaming (deferred)
|
||||
- Multi-language support beyond terminal
|
||||
|
||||
## Decisions
|
||||
|
||||
**1. Use official OpenCode Docker image**
|
||||
- Rationale: Maintained, includes AI features and web terminal
|
||||
- Alternative: Custom image - unnecessary for POC
|
||||
|
||||
**2. OpenCode runs as a persistent container**
|
||||
- Rationale: Easier to manage lifecycle (start/stop/status). Terminal sessions need persistent container.
|
||||
- Implementation: Container runs OpenCode with web interface on port 3000
|
||||
|
||||
**3. Health check via HTTP endpoint**
|
||||
- Rationale: Standard Docker health check mechanism. Traefik can use it.
|
||||
- Endpoint: `GET /` returns 200 when ready
|
||||
|
||||
**4. Workspace mounted from host (same as code-server)**
|
||||
- Rationale: Consistency. Shared workspace between tools.
|
||||
- Path: `/data/workspaces/{user_slug}/{project_slug}`
|
||||
|
||||
**5. Configs/secrets injected same as code-server**
|
||||
- Rationale: Reuse FN-009 infrastructure. No special handling needed.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
**[Risk] OpenCode container requires significant resources**
|
||||
→ Mitigation: Set resource limits (4GB RAM, 2 CPU). Document requirements.
|
||||
|
||||
**[Risk] Web terminal performance over slow connections**
|
||||
→ Mitigation: Use modern terminal emulation with compression. Document bandwidth requirements.
|
||||
|
||||
**[Risk] AI features require API keys**
|
||||
→ Mitigation: Support secret injection for API keys. Document configuration.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
No migration. New feature.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should OpenCode support multiple terminal sessions?
|
||||
2. Do we pre-configure common development tools?
|
||||
3. Should OpenCode integrate with the platform's AI provider?
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
OpenCode is an AI-powered terminal-based development environment that provides a web interface for interactive development. It demonstrates the platform's extensibility beyond standard tools like code-server. As a POC, it validates the manifest-driven spawn system with a non-trivial runtime that requires web terminal forwarding.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **OpenCode manifest**: Define the tool with terminal web interface, workspace mounts, and health checks
|
||||
- **Container image**: Reference to OpenCode image with built-in web terminal
|
||||
- **Health reporting**: Endpoint that reports tool health to the platform
|
||||
- **Spawn integration**: Reuse the spawn flow from FN-010 but with OpenCode-specific configuration
|
||||
- **Web terminal**: Support for browser-based terminal access
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `opencode-manifest`: OpenCode tool manifest with web terminal config
|
||||
- `web-terminal`: Support for browser-based terminal interfaces
|
||||
- `health-reporting`: Tool health status reporting mechanism
|
||||
|
||||
### Modified Capabilities
|
||||
- None (reuses spawn infrastructure from FN-010)
|
||||
|
||||
## Impact
|
||||
|
||||
- **apps/api/app/tools/manifests/opencode.yml**: Updated manifest
|
||||
- **apps/api/app/services/spawn.py**: Minor updates for OpenCode-specific mounts
|
||||
- **apps/web/src/**: OpenCode appears in tool selection UI
|
||||
- **Docker images**: Uses official OpenCode image
|
||||
@@ -0,0 +1,27 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Container provides web terminal interface
|
||||
The system SHALL provide a web terminal interface in the OpenCode container.
|
||||
|
||||
#### Scenario: Terminal available
|
||||
- **WHEN** the OpenCode container is running
|
||||
- **THEN** a web terminal is accessible via HTTP on port 3000
|
||||
- **AND** the user can execute shell commands through the browser
|
||||
|
||||
#### Scenario: Workspace access
|
||||
- **WHEN** the container runs
|
||||
- **THEN** the project workspace is mounted at /workspace
|
||||
- **AND** the user can read/write files in the workspace
|
||||
|
||||
### Requirement: Container supports AI features
|
||||
The system SHALL allow AI-powered development features in the OpenCode environment.
|
||||
|
||||
#### Scenario: AI assistance
|
||||
- **WHEN** the user interacts with OpenCode
|
||||
- **THEN** AI features are available for code completion and assistance
|
||||
- **AND** the user can configure AI provider settings
|
||||
|
||||
#### Scenario: Terminal session persistence
|
||||
- **WHEN** the user opens a terminal session
|
||||
- **THEN** the session persists while the container runs
|
||||
- **AND** multiple sessions can be opened
|
||||
@@ -0,0 +1,22 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Tool reports health status
|
||||
The system SHALL provide a mechanism for OpenCode to report its health.
|
||||
|
||||
#### Scenario: Health endpoint
|
||||
- **WHEN** the OpenCode container is running
|
||||
- **THEN** it exposes a / endpoint for health checks
|
||||
- **AND** returns 200 when the web terminal is ready
|
||||
|
||||
#### Scenario: Health check in Traefik
|
||||
- **WHEN** the container is spawned
|
||||
- **THEN** Traefik uses the health endpoint for routing decisions
|
||||
- **AND** unhealthy containers are removed from the load balancer
|
||||
|
||||
### Requirement: Platform tracks tool health
|
||||
The system SHALL track and display the health of OpenCode instances.
|
||||
|
||||
#### Scenario: Status display
|
||||
- **WHEN** the user views an OpenCode instance
|
||||
- **THEN** the current status is displayed (healthy, unhealthy, starting)
|
||||
- **AND** the status updates automatically
|
||||
@@ -0,0 +1,15 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: OpenCode manifest defines web terminal environment
|
||||
The system SHALL provide an OpenCode manifest with web terminal configuration.
|
||||
|
||||
#### Scenario: Manifest includes terminal config
|
||||
- **WHEN** the OpenCode manifest is loaded
|
||||
- **THEN** it specifies an OpenCode Docker image with web interface
|
||||
- **AND** it defines exposed ports for the HTTP interface (port 3000)
|
||||
- **AND** it defines volume mounts (workspace, config)
|
||||
|
||||
#### Scenario: Manifest includes health check
|
||||
- **WHEN** the manifest is used for spawning
|
||||
- **THEN** it defines a health check endpoint
|
||||
- **AND** specifies health check interval and timeout
|
||||
@@ -0,0 +1,42 @@
|
||||
## 1. Manifest Definition
|
||||
|
||||
- [x] 1.1 Create apps/api/app/tools/manifests/opencode.yml with web terminal config
|
||||
- [x] 1.2 Add Docker image (ghcr.io/opencode-ai/opencode:latest), ports (3000), volumes
|
||||
- [x] 1.3 Add health check configuration to manifest
|
||||
- [x] 1.4 Validate manifest against ToolManifest schema
|
||||
|
||||
## 2. Container Setup
|
||||
|
||||
- [ ] 2.1 Verify OpenCode image availability and configuration
|
||||
- [ ] 2.2 Document web terminal access pattern
|
||||
- [ ] 2.3 Configure environment variables for terminal support
|
||||
- [ ] 2.4 Test container locally with docker run
|
||||
- [ ] 2.5 Verify web terminal accessibility
|
||||
|
||||
## 3. Spawn Integration
|
||||
|
||||
- [ ] 3.1 Verify SpawnService (FN-010) can spawn OpenCode instances
|
||||
- [ ] 3.2 Add OpenCode-specific volume mounts (config)
|
||||
- [ ] 3.3 Test spawn via API endpoint
|
||||
- [ ] 3.4 Verify Traefik routing to OpenCode container
|
||||
|
||||
## 4. Frontend Integration
|
||||
|
||||
- [ ] 4.1 Add OpenCode to tool selection dropdown
|
||||
- [ ] 4.2 Display OpenCode-specific options in spawn form
|
||||
- [ ] 4.3 Show OpenCode instance status in detail page
|
||||
|
||||
## 5. Testing & Verification
|
||||
|
||||
- [ ] 5.1 Test terminal availability in spawned container
|
||||
- [ ] 5.2 Test web interface accessibility
|
||||
- [ ] 5.3 Test health endpoint response
|
||||
- [ ] 5.4 Verify workspace mount is accessible
|
||||
- [ ] 5.5 Run full test suite: `make test`
|
||||
- [ ] 5.6 Run linters: `make lint`
|
||||
|
||||
## 6. Documentation
|
||||
|
||||
- [ ] 6.1 Document OpenCode setup in docs/development.md
|
||||
- [ ] 6.2 Add OpenCode usage guide
|
||||
- [ ] 6.3 Document terminal configuration and AI features
|
||||
Reference in New Issue
Block a user