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
2026-05-14 17:35:20 +02:00
parent 1539a67883
commit 78aaddb2b5
41 changed files with 1585 additions and 0 deletions
@@ -0,0 +1,243 @@
+# Headquarter Project Specsheet
+
+> Canonical project state document. Updated after each completed FN task.
+> Last updated: 2026-05-14
+
+## Project Overview
+
+Headquarter is a hosted workspace and tool-orchestration platform where authenticated users create Git-backed projects and spawn containerized development tools (OpenCode, code-server) via HTTPS subdomains.
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Frontend | React 19 + Vite 6 + TypeScript 5 |
+| Backend | FastAPI + SQLAlchemy 2.0 (async) + Pydantic v2 |
+| Database | PostgreSQL 17 + Alembic migrations |
+| Auth | Authentik OIDC (planned) |
+| Runtime | Docker Compose (local dev + Portainer production) |
+| Routing | Traefik reverse proxy with subdomain routing |
+| Monorepo | pnpm workspace |
+
+## Completed Features
+
+### FN-002: Monorepo Scaffold ✅
+- Root tooling (Makefile, package.json, pnpm-workspace.yaml)
+- React frontend skeleton (apps/web/)
+- FastAPI backend skeleton (apps/api/)
+- Docker Compose local development stack
+- Deployment skeleton for Portainer + Traefik
+- CI/CD workflow (GitHub Actions)
+
+### FN-019: Architecture & Specification ✅
+- Enhanced docs/architecture.md (18 sections)
+- docs/mvp-scope.md with milestones and dependency order
+- docs/project-brief.md
+- docs/development.md
+- docs/deployment.md
+- docs/tool-manifest-spec.md
+
+### FN-003: Tool Registry ✅
+- Manifest-driven tool registry (JSON schema)
+- In-memory registry with built-in manifests
+- FastAPI CRUD routes for tool definitions
+- OpenCode and code-server built-in definitions
+- Registry loaded at application startup
+
+### FN-011: Git Provider Model ✅
+- Git provider abstraction (GitHub, GitLab, Gitea, Forgejo, generic)
+- SSH key pair generation (Ed25519)
+- Encrypted private key storage
+- Credential model and storage interface
+- Repository connection model and manager
+- Local Git operations interface
+- Alembic migration for repository_connection table
+- Full test coverage
+
+### FN-004: Backend Foundation (Partial) ✅
+- Domain models: User, Project, Repository, Workspace, ToolDefinition, ToolInstance, Config, Secret, AccessRoute, RepositoryConnection
+- Alembic migrations
+- API routers for all entities
+- Database configuration with async SQLAlchemy
+- Encryption utilities (Fernet)
+- Auth dependencies structure
+
+### FN-049: CI / Testing ✅
+- GitHub Actions workflow
+- Frontend: lint, typecheck, test (Vitest)
+- Backend: lint (ruff), typecheck (mypy), test (pytest)
+- PostgreSQL service container for backend tests
+
+## OpenSpec Changes (Ready for Implementation)
+
+### FN-005: Frontend Foundation 📋
+**Location:** `openspec/changes/frontend-foundation/`
+**Status:** All artifacts complete (proposal, design, specs, tasks)
+**Dependencies:** FN-002, FN-019
+**Tasks:** 46 total
+**Key deliverables:**
+- Authentik OIDC auth flow with PKCE
+- Dashboard shell with responsive navigation
+- Project CRUD UI
+- Typed API client
+- Auth-guarded routes
+
+### FN-006: Deployment Config 📋
+**Location:** `openspec/changes/deployment-config/`
+**Status:** All artifacts complete (proposal, design, specs, tasks)
+**Dependencies:** FN-002
+**Tasks:** 27 total
+**Key deliverables:**
+- Traefik label generator service
+- Production Docker Compose stack
+- Portainer deployment guide
+- Dynamic subdomain routing
+
+### FN-009: Config & Secrets 📋
+**Location:** `openspec/changes/config-secrets/`
+**Status:** All artifacts complete (proposal, design, specs, tasks)
+**Dependencies:** FN-004, FN-005
+**Tasks:** 31 total
+**Key deliverables:**
+- Config management UI (global/user/project/instance scopes)
+- Encrypted secret storage UI
+- Runtime injection into tool containers
+- Scope-based access control
+
+### FN-010: code-server Spawn 📋
+**Location:** `openspec/changes/codeserver-spawn/`
+**Status:** All artifacts complete (proposal, design, specs, tasks)
+**Dependencies:** FN-003, FN-006, FN-009
+**Tasks:** 38 total
+**Key deliverables:**
+- Tool spawn API endpoint
+- code-server manifest refinement
+- Frontend spawn UI
+- Container lifecycle management (start/stop/status)
+- Traefik auth proxy integration
+
+### FN-008: OpenCode POC 📋
+**Location:** `openspec/changes/opencode-poc/`
+**Status:** All artifacts complete (proposal, design, specs, tasks)
+**Dependencies:** FN-003, FN-006, FN-009
+**Tasks:** 25 total
+**Key deliverables:**
+- OpenCode manifest with web terminal config
+- Containerized terminal environment
+- Health reporting mechanism
+- Web terminal interface
+
+## Dependency Graph
+
+```
+FN-002 (Scaffold) ✅
+   │
+   ├──> FN-019 (Architecture) ✅ ──> FN-004 (Backend) ✅
+   │                                  │
+   │                                  ├──> FN-003 (Tool Registry) ✅
+   │                                  │       │
+   │                                  │       ├──> FN-010 (code-server) 📋
+    │                                  │       └──> FN-008 (OpenCode) 📋
+   │                                  │
+   │                                  ├──> FN-011 (Git Provider) ✅
+   │                                  │
+   │                                  └──> FN-009 (Config/Secrets) 📋
+   │                                          │
+   │                                          └──> FN-010, FN-008 (runtime)
+   │
+   └──> FN-005 (Frontend) 📋 ───────> FN-009 (UI)
+
+FN-006 (Deployment) 📋 runs in parallel with FN-004/FN-005
+```
+
+## Critical Path
+
+FN-002 ✅ → FN-019 ✅ → FN-004 ✅ → FN-003 ✅ → FN-010/FN-008 📋
+
+## Next Recommended Task
+
+**FN-005: Frontend Foundation** - This unblocks user-facing features and enables parallel work on FN-009 (Config/Secrets UI).
+
+## Database Schema
+
+### Existing Tables
+- `users` - User accounts (Authentik OIDC)
+- `projects` - User projects with slug
+- `repositories` - Git repository metadata
+- `repository_connections` - Provider-specific connections with SSH keys
+- `workspaces` - Project workspaces
+- `tool_definitions` - Manifest-driven tool definitions
+- `tool_instances` - Running/spawned tool instances
+- `configs` - Key-value config storage (scoped)
+- `secrets` - Encrypted secret storage (scoped)
+- `access_routes` - Traefik routing rules
+
+## API Endpoints
+
+### Implemented Routers
+- `/api/v1/users` - User management
+- `/api/v1/projects` - Project CRUD
+- `/api/v1/repositories` - Repository management
+- `/api/v1/workspaces` - Workspace management
+- `/api/v1/tool-definitions` - Tool registry CRUD
+- `/api/v1/tool-instances` - Tool instance lifecycle
+- `/api/v1/configs` - Config management
+- `/api/v1/secrets` - Secret management
+- `/api/v1/access-routes` - Routing rules
+- `/api/v1/tools` - Tool registry (manifest-driven)
+- `/health` - Health check
+
+## Open Questions (from mvp-scope.md)
+
+1. **Admin role in MVP:** Do we need a basic admin role for global config management?
+2. **User slug derivation:** Display name, email local-part, or dedicated slug column?
+3. **Provider adapter coverage:** Which Git providers get concrete adapters in MVP?
+4. **Auto-deploy-key registration:** Automatic via provider APIs or manual copy-paste?
+5. **Container image trust:** Allow-list or any image reference?
+6. **Billing or resource quotas:** Usage limiting needed in MVP?
+
+## File Structure
+
+```
+headquarter/
+├── apps/
+│   ├── web/              # React frontend (skeleton)
+│   └── api/              # FastAPI backend (models + routers)
+├── docs/                 # Architecture, scope, development docs
+├── deploy/               # Portainer/Traefik deployment examples
+├── openspec/             # Spec-driven workflow
+│   ├── config.yaml       # Project context for AI
+│   ├── changes/          # Active changes
+│   │   ├── frontend-foundation/    # FN-005
+│   │   ├── deployment-config/      # FN-006
+│   │   ├── config-secrets/         # FN-009
+│   │   ├── codeserver-spawn/       # FN-010
+│   │   └── opencode-poc/           # FN-008
+│   └── specs/            # Project specsheets
+│       └── project-specsheet.md
+├── docker-compose.yml    # Local development stack
+├── docker-compose.traefik.yml
+├── Makefile              # Common workflows
+└── package.json          # Root monorepo scripts
+```
+
+## Test Status
+
+- **Frontend:** Vitest configured, basic App.test.tsx passing
+- **Backend:** pytest configured, tests for git provider, credentials, operations
+- **CI:** GitHub Actions runs on PR/push to main
+
+## Definition of MVP Done
+
+1. ✅ Monorepo scaffold complete
+2. ✅ Architecture documented
+3. ✅ Backend models and migrations
+4. ✅ Tool registry with manifests
+5. ✅ Git provider abstraction
+6. 📋 Frontend auth and navigation (spec ready)
+7. 📋 Config/secrets UI and runtime injection (spec ready)
+8. 📋 code-server spawn flow (spec ready)
+9. 📋 OpenCode terminal environment (spec ready)
+10. 📋 Production deployment stack (spec ready)
+11. ⏳ All tests passing
+12. ⏳ Documentation consistent with implementation