Fusion
b40eb3e88c
Backend: - Add cloudflare_tunnel.py service for creating/deleting tunnels via Cloudflare API - Add public_url and tunnel_id fields to ToolInstance model - Update start_instance to create Cloudflare tunnel after container starts - Update stop_instance to delete tunnel before stopping container - Update delete_instance to cleanup tunnel before deletion - Update restart_instance to recreate tunnel on restart - Create Alembic migration 0011 for tunnel fields - Add Cloudflare config settings (API token, zone ID, account ID, base domain) Infrastructure: - Add cloudflared service to docker-compose.traefik.yml - Mount shared cloudflared_config volume between API and cloudflared containers - Add Cloudflare env vars to API service Frontend: - Update instance Open button to handle both full URLs and proxy paths The instance URL is now set to the Cloudflare tunnel public URL when available, falling back to the API proxy path if tunnel creation fails.
OpenSpec Integration
This project uses OpenSpec as the single source of truth for requirements, specifications, and task tracking.
Philosophy
Specs live in the repo. They provide:
- Living documentation of system behavior
- Context for AI agents implementing features
- Reviewable intent before code changes
- Traceability from requirements to implementation
Structure
openspec/
├── README.md # This file
├── specs/ # Living specifications
│ ├── docker-infrastructure/ # Phase 1: Docker, Make, env
│ ├── database-models/ # Phase 1: SQLAlchemy, Alembic
│ ├── auth-oauth/ # Phase 1: Authentication
│ ├── user-profile/ # Phase 1: Profiles
│ ├── git-repo/ # Phase 1: Repositories
│ ├── ssh-keys/ # Phase 1: SSH keys
│ ├── project-management/ # Phase 1: Projects
│ ├── user-config/ # Phase 1: Preferences
│ ├── frontend-foundation/ # Phase 1: React frontend
│ ├── api-documentation/ # Phase 1: OpenAPI, health
│ ├── tool-types/ # Phase 2: Tool definitions
│ ├── tool-instances/ # Phase 2: Container management
│ └── tool-terminal/ # Phase 2: Web terminal
└── changes/ # Proposed changes (auto-generated)
Spec-to-PRD Mapping
OpenSpec specs map directly to PRD user stories:
Phase 1: Foundation
| Spec | PRD Story | Description |
|---|---|---|
docker-infrastructure |
US-001 | Docker Compose, Makefiles, environment setup |
database-models |
US-002 | SQLAlchemy models, Alembic migrations |
auth-oauth |
US-003 | Authentik OAuth, httpOnly cookies, JWT |
user-profile |
US-004 | Profile CRUD, avatar upload |
git-repo |
US-005 | Repository creation, cloning, management |
ssh-keys |
US-006 | Ed25519 key generation, encryption |
project-management |
US-007 | Projects, organization, cascading delete |
user-config |
US-008 | Preferences, JSONB storage |
frontend-foundation |
US-009 | React, TypeScript, Tailwind, routing |
api-documentation |
US-010 | OpenAPI/Swagger, health checks, ADRs |
Phase 2: Tool Runtime
| Spec | PRD Story | Description |
|---|---|---|
tool-types |
US-011 | Docker Compose templates, built-in tools |
tool-types |
US-012 | ToolInstance model, schema |
tool-types |
US-013 | Template engine, Jinja2 rendering |
tool-instances |
US-014 | Tool spawning, Docker integration |
tool-instances |
US-015 | Traefik routes, subdomain generation |
tool-terminal |
US-016 | WebSocket terminal, xterm.js |
tool-instances |
US-017 | Status monitoring, log streaming |
tool-instances |
US-018 | Frontend tool management UI |
tool-instances |
US-019 | Config inheritance, env vars |
| All Phase 2 | US-020 | Integration, documentation |
Workflow
1. Propose Changes
When you want to build something, start with OpenSpec:
# Propose a new change (creates proposal, design, tasks)
npx @fission-ai/openspec@latest propose "add repository templates feature"
This creates:
openspec/changes/add-repo-templates/
├── .openspec.yaml # Change metadata
├── proposal.md # What & why
├── design.md # How (technical decisions)
├── tasks.md # Implementation steps
└── specs/ # Updated spec deltas
└── git-repo/
└── spec.md # Modified requirements
2. Review the Proposal
Read the generated artifacts:
proposal.md- Understand what and whydesign.md- Review technical approachtasks.md- See implementation breakdownspecs/- Review requirement changes
3. Implement Tasks
OpenSpec tasks are the unit of work. Each task from tasks.md is implemented directly:
# Apply the change (implements tasks sequentially)
npx @fission-ai/openspec@latest apply add-repo-templates
Or implement manually by reading tasks.md and working through each task.
4. Complete the Change
When all tasks are done:
# Archive the completed change
npx @fission-ai/openspec@latest archive add-repo-templates
Commands Reference
OpenSpec
# Propose a change
npx @fission-ai/openspec@latest propose "description"
# List active changes
npx @fission-ai/openspec@latest list
# Apply a change (implements tasks)
npx @fission-ai/openspec@latest apply <change-id>
# Archive completed change
npx @fission-ai/openspec@latest archive <change-id>
# Explore existing specs
npx @fission-ai/openspec@latest explore
# Check change status
npx @fission-ai/openspec@latest status --change <change-id>
Quality Gates
All changes must:
- Update specs first if requirements change
- Pass backend tests:
pytest,mypy .,ruff check . - Pass frontend tests:
npm run typecheck,npm run lint - Maintain spec-code alignment (specs reflect actual behavior)
Rules
- Specs are source of truth - Code implements specs, not the other way around
- Changes flow through OpenSpec - Every feature starts as an OpenSpec proposal
- Living documentation - Update specs when behavior changes
- Review intent first - Review spec deltas before reviewing code diffs
Integration with AGENTS.md
This project follows the workflow defined in AGENTS.md:
- Read OpenSpec specs for context
- Use superpowers skills for planning
- Implement tasks from OpenSpec changes
- Verify against quality gates
Dependencies
- OpenSpec CLI -
npx @fission-ai/openspec@latest