gondolier — implementation plan

gondolier — implementation plan

Status: Active. Phases are ordered by dependency — each phase depends on the previous being done.

Phase 1: Skeleton + shunt fork

Set up the Go module, Workers config, and the shunt fork with interface-based abstractions.

• go.mod — git.rbtr.dev/laputacloudco/gondolier
• Basic stub packages (engine, tenant, forgejo, scheduler, api)
• .forgejo/workflows/ci.yaml — vet, test, build, merge-queue gate
• .github/pull_request_template.md
• .github/CODEOWNERS
• .github/dependabot.yml
• .github/lsp.json
• .gitignore — Go-specific ignores
• cmd/gondolier/main.go — stub binary
• Create shunt fork at git.rbtr.dev/laputacloudco/shunt
  • Abstract forge package: extract HTTP client into ForgeClient interface
  • Abstract metrics package: extract metrics collection, make HTTP handler optional
  • Engine uses forge.ForgeClient instead of *forge.Client
  • Nil guards around e.cfg.Metrics calls
• wrangler.toml — Workers config for Go
• .gitignore

Phase 2: Database schema + crypto

Set up Supabase migrations and the encryption package.

• Migration 001: tenants, forge_connections, managed_repos, audit_log
• Crypto package: envelope AES-GCM, master key from Cloudflare Secrets
• Workers I/O interface definitions

Phase 3: Engine integration

Wire the shunt engine into Workers through our I/O layer.

• Workers-compatible forge client (uses fetch API, implements ForgeClient)
• Workers-compatible gitops.Stager (API-based staging via Forgejo API)
• No-op checkpoint store (state re-derived from forge API)
• Engine wrapper that calls Reconcile()

Phase 4: Scheduler

Cron trigger + Durable Objects for per-tenant leasing.

• Durable Object: per-(tenant, repo) lease
• Cron Worker: iterate tenants, acquire lease, run tick, release lease
• KV rate limiter per (tenant, forge_instance)
• Timeout handling: partial results, retry next tick

Phase 5: API

REST API endpoints for tenant management and queue inspection.

• API key authentication
• Tenant CRUD
• Forge connection management (PAT paste, OAuth redirect)
• Managed repo management
• Queue state endpoint
• Audit log endpoint
• Error handling, pagination, validation

Phase 6: Notifications + polish

• Webhook notification on bounce
• Resend email (v2)
• Basic HTML UI (Go templates)
• PostHog analytics
• Documentation

Open decisions (not blocking implementation)

• OAuth vs PAT for forge onboarding: implement both, default to PAT paste
• Web UI: Go templates (phase 6) vs separate SPA (deferred)
• Billing: Stripe integration (deferred until revenue)
• API key format: UUID? base64? random bytes?