@bongos/core 1.17.1 → 1.17.3

package/modules/provisioning/migrations/provisioning_001_tables.sql

@@ -0,0 +1,160 @@
+-- provisioning_001_tables.sql — the `provisioning` module's DB slice (ADR 0111 §1,
+-- task #1942 / BONGOS-V1 goal 32). Instance hosting + domains: the web-tier REQUEST
+-- + STATE surface for standing up + operating a Cloud Bongos instance's own infra.
+--
+-- These three tables mirror the dev-box lifecycle ledger (migrations 067/070), one
+-- layer up — a whole INSTANCE instead of a builder's box:
+--   • provisioning_instances — one row per instance being provisioned/operated.
+--   • provisioning_intents    — the trust-boundary-safe request queue (the box_intents
+--                               analogue): the web tier only ENQUEUES; the control-plane
+--                               runner (scripts/gds/provision.js, task P3) drains it. The
+--                               web process holds NO cloud tokens (ADR 0111 §2 / ADR 0016).
+--   • provisioning_events     — an append-only audit ledger of provisioning actions
+--                               (direct control-plane infra mutations are project-state
+--                               changes too — CLAUDE.md hard rule — so they get a row).
+--
+-- Module migrations are ADDITIVE and NAMESPACED: every object lives under the
+-- provisioning_ prefix, there is no down-migration, and the file itself is
+-- provisioning_-prefixed (ADR 0108 §5) so its stem can never collide with a core /
+-- instance / other-module migration across repos. `scripts/migrate.sh` discovers +
+-- applies this ONLY when the provisioning module is enabled in config/modules.json.
+--
+-- Idempotent: safe to re-run.
+
+-- ---------------------------------------------------------------------------
+-- provisioning_instances — one row per instance an owner is provisioning/operating.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_instances (
+  id                bigserial PRIMARY KEY,
+
+  -- The owner (a builder in THIS GDS) who requested + operates this instance.
+  owner_builder_id  bigint NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+
+  -- A DNS/db-safe slug naming the instance (e.g. 'mercury'). The stable key an
+  -- owner + the port reference it by; also the base for its DB name + hostname.
+  slug              text NOT NULL UNIQUE,
+
+  -- The target repo/ref this instance runs (e.g. 'owner/repo'). Advisory metadata
+  -- the runner reads; NULL until supplied.
+  target_ref        text,
+
+  -- Hosting shape (ADR 0111 §3/§6). Cheapest-first DNA:
+  --   co-tenant  — a process + DB on an EXISTING box (the cloudbongos.com model, $0 extra)
+  --   dedicated  — its own DigitalOcean droplet (only when justified)
+  hosting_shape     text NOT NULL DEFAULT 'co-tenant'
+    CHECK (hosting_shape IN ('co-tenant', 'dedicated')),
+
+  -- Bring-your-own-domain first (ADR 0111 §4): the apex/host the owner already owns
+  -- (or a delegated zone). NULL until supplied. Registrar PURCHASE is deferred.
+  domain            text,
+
+  -- The instance's own database name (createdb <db_name>; GDS-only migrate).
+  db_name           text,
+
+  -- Allocated port for a co-tenant process (NULL for a dedicated droplet / unallocated).
+  port              int,
+
+  -- The droplet size tier for a dedicated shape (a SIZE_CATALOG slug); NULL co-tenant.
+  tier              text,
+
+  -- Lifecycle state machine (mirrored in modules/provisioning/provisioning.js
+  -- INSTANCE_STATES):
+  --   requested    — the owner asked; a 'provision' intent is (or will be) enqueued
+  --   provisioning — the control-plane runner is standing it up
+  --   active        — running + serving
+  --   tearing_down  — a 'teardown' intent is being executed
+  --   torn_down     — fully de-provisioned
+  --   error         — a provisioning op failed; needs operator attention
+  status            text NOT NULL DEFAULT 'requested'
+    CHECK (status IN ('requested', 'provisioning', 'active',
+                      'tearing_down', 'torn_down', 'error')),
+
+  -- Monthly cost estimate (USD) for visibility (ADR 0111 §6). Co-tenant = 0;
+  -- dedicated = the tier's SIZE_CATALOG monthly rate. NOT a bill — just visibility.
+  cost_estimate_usd numeric(10,4) NOT NULL DEFAULT 0,
+
+  error_note        text,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  provisioned_at    timestamptz,
+  torn_down_at      timestamptz
+);
+CREATE INDEX IF NOT EXISTS idx_provisioning_instances_owner
+  ON provisioning_instances (owner_builder_id);
+CREATE INDEX IF NOT EXISTS idx_provisioning_instances_status
+  ON provisioning_instances (status);
+
+-- ---------------------------------------------------------------------------
+-- provisioning_intents — the provision / teardown request queue (the
+-- trust-boundary-safe bridge between the web process and the control plane).
+-- The web side only ever RECORDS a request here; scripts/gds/provision.js (task
+-- P3, the sole holder of the DO/Cloudflare tokens) drains it. The web process
+-- stays powerless over infra — it can ask, never act (ADR 0111 §2 / ADR 0016).
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_intents (
+  id            bigserial PRIMARY KEY,
+  instance_id   bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+
+  -- Only the two SAFE, owner/Archon-initiated ops are queueable from the web:
+  -- 'provision' (stand up) and 'teardown' (an explicit tear-down the owner/Archon
+  -- asked for). No implicit destructive op is ever queued.
+  action        text NOT NULL CHECK (action IN ('provision', 'teardown')),
+
+  -- pending  → waiting for the runner to pick it up
+  -- running  → the runner claimed it and is doing the control-plane work
+  -- done     → the op succeeded
+  -- error    → the op failed (last_error carries why); the row is no longer "open"
+  --            so the partial unique index below lets a fresh intent (retry) through.
+  state         text NOT NULL DEFAULT 'pending'
+    CHECK (state IN ('pending', 'running', 'done', 'error')),
+
+  -- Who asked. 'api:self' for an owner's own request; 'api:archon:<id>' for an
+  -- Archon force action; a runner/control-plane tag otherwise. Audit only.
+  requested_by  text,
+
+  -- Retry accounting. The runner bumps attempts each claim; a small cap (enforced
+  -- in the runner, not here) stops a poison intent from looping forever.
+  attempts      int NOT NULL DEFAULT 0,
+  last_error    text,
+
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  resolved_at   timestamptz
+);
+
+-- At most ONE open (pending|running) intent per instance — a repeated request
+-- collides here and the route returns the already-open intent instead of piling
+-- up a redundant queue. Resolved (done|error) rows are exempt, so a retry after a
+-- failure is always allowed (mirrors ux_box_intents_open).
+CREATE UNIQUE INDEX IF NOT EXISTS ux_provisioning_intents_open
+  ON provisioning_intents (instance_id)
+  WHERE state IN ('pending', 'running');
+
+-- The runner's hot path: "oldest pending intent". A partial index keeps it tiny
+-- (it only ever indexes the unresolved tail, not the full history).
+CREATE INDEX IF NOT EXISTS idx_provisioning_intents_pending
+  ON provisioning_intents (created_at)
+  WHERE state = 'pending';
+
+-- ---------------------------------------------------------------------------
+-- provisioning_events — append-only audit/log of provisioning actions. The HTTP
+-- audit_log captures only API mutations; the real provisioning ops run on the
+-- control-plane runner, so they record here (like box_events for the box lifecycle).
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_events (
+  id                bigserial PRIMARY KEY,
+  instance_id       bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+  owner_builder_id  bigint REFERENCES builders(id) ON DELETE SET NULL,
+  -- request | provision | active | teardown | torn_down | cost | error | ...
+  event             text NOT NULL,
+  detail            text,
+  cost_usd          numeric(10,4),
+  -- Who/what triggered it: 'api:self' | 'api:archon:<id>' | 'runner' | ...
+  actor             text,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_provisioning_events_instance
+  ON provisioning_events (instance_id, created_at DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('provisioning_001_tables')
+  ON CONFLICT (version) DO NOTHING;

package/modules/provisioning/migrations/provisioning_002_standalone_shape.sql

@@ -0,0 +1,11 @@
+-- provisioning_002_standalone_shape.sql — widen provisioning_instances.hosting_shape
+-- to allow 'standalone' (ADR 0108 / ADR 0111, BONGOS-V1 goal 32/35, task 1978).
+--
+-- A standalone instance runs from its OWN repo checkout with a pinned @cloudbongos/core
+-- npm dep (the ADR 0108 destination model), distinct from the co-tenant shape (which
+-- shares the control-plane checkout) and dedicated (its own droplet). Widening a CHECK
+-- enum is ADDITIVE — it only permits MORE values; no existing row changes, no data is
+-- lost — so it is safe under the module-owned-migration rule (ADR 0083 §Decision #5).
+ALTER TABLE provisioning_instances DROP CONSTRAINT IF EXISTS provisioning_instances_hosting_shape_check;
+ALTER TABLE provisioning_instances ADD CONSTRAINT provisioning_instances_hosting_shape_check
+  CHECK (hosting_shape IN ('co-tenant', 'dedicated', 'standalone'));

package/modules/provisioning/migrations/provisioning_003_github_app_manifest.sql

@@ -0,0 +1,95 @@
+-- provisioning_003_github_app_manifest.sql — the GitHub App Manifest onboarding flow
+-- (ADR 0133, BONGOS-V1 goal 35 / criterion 165, task 2080).
+--
+-- WHY. The last human friction in greenfield onboarding was: the owner had to hand-
+-- create a GitHub OAuth App, generate a client secret, and hand it to the box
+-- (oauth-secret.js). GitHub has NO API to create an OAuth App — but it DOES have the
+-- GitHub App *Manifest* flow: the owner clicks ONE pre-filled link, approves on GitHub,
+-- and GitHub returns a temporary `code` we exchange (control-plane-side) for the
+-- client_id + client_secret automatically. The secret never touches the browser/chat.
+--
+-- The flow spans TWO processes across the trust boundary (ADR 0111 §2 / ADR 0016):
+--   • the web tier mints a one-time `state` token + stores the row (this table), and
+--     its public callback stores GitHub's `code` when the owner returns;
+--   • the control-plane runner (scripts/gds/provision.js — the sole token-holder)
+--     drains rows in status 'code_received', exchanges the code for creds, and places
+--     them in /etc/<slug>/web.env (the oauth-secret.js path), then verifies /healthz.
+-- Because the two processes don't share memory, the state/code lease is DB-backed (the
+-- merge_lease / builder_sessions expires_at pattern), NOT the in-memory deviceFlows map.
+--
+-- Additive + idempotent + namespaced (ADR 0108 §5). Applied only when the provisioning
+-- module is enabled (config/modules.json). Safe to re-run.
+
+-- ---------------------------------------------------------------------------
+-- (1) Widen provisioning_intents.action so the manifest conversion can ride the
+--     existing intent queue if ever needed. Today the runner drains manifests by
+--     scanning this table's status (drainOAuthManifests) — but widening the CHECK
+--     keeps a future intent-driven path open and keeps INTENT_ACTIONS in lockstep.
+--     Widening a CHECK enum is additive (permits MORE values; no row changes).
+-- ---------------------------------------------------------------------------
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_action_check;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_action_check
+  CHECK (action IN ('provision', 'teardown', 'oauth-manifest'));
+
+-- ---------------------------------------------------------------------------
+-- (2) provisioning_oauth_manifests — one row per GitHub-App-Manifest onboarding
+--     attempt for an instance. The `state` is the one-time CSRF token round-tripped
+--     through GitHub; `github_code` is GitHub's temporary conversion code (single-use,
+--     ~1h GitHub-side TTL) the control-plane runner exchanges for the client creds.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS provisioning_oauth_manifests (
+  id            bigserial PRIMARY KEY,
+  instance_id   bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+
+  -- The one-time CSRF `state` token minted by the web tier (crypto.randomBytes hex),
+  -- carried to GitHub in the manifest POST and returned on the callback. UNIQUE so a
+  -- callback maps to exactly one attempt. Unguessable (256-bit) — it is the callback's
+  -- only authorization (GitHub redirects the browser back unauthenticated).
+  state         text NOT NULL UNIQUE,
+
+  -- Lifecycle:
+  --   pending        — link minted; awaiting the owner's click + GitHub's redirect back
+  --   code_received  — GitHub redirected back with a `code`; awaiting the control-plane runner
+  --   converting     — the runner claimed the row and is exchanging the code with GitHub
+  --   done           — creds fetched + placed in web.env; /healthz auth_configured verified
+  --   error          — conversion or placement failed (last_error carries why)
+  --   expired        — the `state` TTL passed before the owner completed the round-trip
+  status        text NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'code_received', 'converting', 'done', 'error', 'expired')),
+
+  -- GitHub's temporary manifest-conversion code. Written by the web-tier callback;
+  -- consumed by the runner (POST /app-manifests/{code}/conversions). NEVER the secret
+  -- itself — only the short-lived code is web-tier-visible; the client_secret is fetched
+  -- by the control plane and written straight to web.env, never stored here.
+  github_code   text,
+
+  -- The GitHub App id + slug GitHub assigned once converted (audit; the App the owner
+  -- created for their instance's sign-in). Filled by the runner on success.
+  app_id        bigint,
+  app_slug      text,
+
+  -- The builder who initiated the attempt (the signed-in owner on the mothership).
+  requested_by  bigint REFERENCES builders(id) ON DELETE SET NULL,
+
+  -- Runner retry accounting (a poison conversion never loops forever) + last error.
+  attempts      int NOT NULL DEFAULT 0,
+  last_error    text,
+
+  -- The `state` token's TTL — the owner must complete the GitHub round-trip before this.
+  expires_at    timestamptz NOT NULL,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now(),
+  resolved_at   timestamptz
+);
+
+-- The runner's hot path: "oldest manifest awaiting conversion" (status='code_received').
+-- A partial index keeps it tiny (only the unresolved tail).
+CREATE INDEX IF NOT EXISTS idx_provisioning_oauth_manifests_ready
+  ON provisioning_oauth_manifests (created_at)
+  WHERE status = 'code_received';
+
+CREATE INDEX IF NOT EXISTS idx_provisioning_oauth_manifests_instance
+  ON provisioning_oauth_manifests (instance_id, created_at DESC);
+
+INSERT INTO schema_migrations (version) VALUES ('provisioning_003_github_app_manifest')
+  ON CONFLICT (version) DO NOTHING;

package/modules/provisioning/module.json

@@ -0,0 +1,17 @@
+{
+  "key": "provisioning",
+  "title": "Instance provisioning",
+  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state — it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
+  "coreVersion": "^1.14.0",
+  "default": false,
+  "author": "Off the Boats",
+  "origin": "Off the Boats (the first Cloud Bongos instance, amazonprimea.com)",
+  "license": "AGPL-3.0",
+  "maintainer": "Off the Boats maintainers",
+  "contributes": {
+    "routes": ["provisioning"],
+    "migrations": true
+  },
+  "provides": ["provisioning.instanceState"],
+  "consumes": []
+}

package/modules/provisioning/onboard-plan.js

@@ -0,0 +1,37 @@
+// modules/provisioning/onboard-plan.js — the CANONICAL onboarding step sequence.
+//
+// Goal 35 / criterion 165 names the sequence as the source of truth: "The canonical
+// step sequence is the source of truth; skill/CLI/hall are forms over it." This file
+// is that ONE source. The CLI (`bongos onboard`, scripts/gds/onboard.js), the branded
+// /create landing page, and the hall's new-project wizard all read it — via a direct
+// require (the CLI) or the public GET /provisioning/onboard-plan route (the web) — so
+// the sequence can never drift between the forms (task 2085, anti-drift).
+//
+// PURE — no I/O, no core imports. Safe to require from a script, a route, or a test.
+//
+// Each step: { key, kind: 'auto' | 'human', label }. `kind: 'human'` marks the
+// irreducibly-manual owner actions (create the GitHub repo, wire GitHub sign-in, first
+// sign-in) that every form renders UI-first; `kind: 'auto'` steps the flow performs.
+// The sequence branches at exactly ONE leg — scaffold — into greenfield (`bongos init`,
+// a fresh empty repo) vs brownfield (`bongos init --adopt`, LAYER onto an existing repo;
+// ADR 0121 §Decision 1 / task 2046). Every other leg is identical, so `mode` only
+// relabels the github-repo / init / scaffold steps.
+function onboardPlan(mode = 'greenfield') {
+  const adopt = mode === 'adopt';
+  return [
+    { key: 'name-address', kind: 'auto', label: 'Decide name + address (interview)' },
+    { key: 'github-repo', kind: 'human', label: adopt ? 'Use your EXISTING GitHub repository' : 'Create the empty GitHub repository' },
+    { key: 'dns-preflight', kind: 'auto', label: 'DNS token preflight — before the address step (task 1980)' },
+    { key: 'init', kind: 'auto', label: adopt ? 'bongos init --adopt — LAYER onto the existing repo (pre-flight + accept)' : 'bongos init — scaffold the instance config' },
+    { key: 'scaffold', kind: 'auto', label: adopt ? 'Layer config + pinned @bongos/core onto the existing repo (no clobber)' : 'Scaffold the standalone repo (own repo + pinned @bongos/core)' },
+    { key: 'provision', kind: 'auto', label: 'Provision core + DB + address + service (standalone, task 1978)' },
+    { key: 'seed-version', kind: 'auto', label: 'Seed the first version (V1) so the instance can take tasks immediately (task 2119)' },
+    { key: 'oauth-app', kind: 'human', label: 'Wire GitHub sign-in — one-click GitHub App (task 2080), or a manual OAuth app' },
+    { key: 'oauth-place', kind: 'auto', label: 'Place the OAuth secret — auto via the Manifest flow, or verified manual (task 1979)' },
+    { key: 'first-sign-in', kind: 'human', label: 'First sign-in (seats the founding Archon)' },
+    { key: 'verify', kind: 'auto', label: 'Verify /healthz auth_configured' },
+    { key: 'brand', kind: 'auto', label: 'Brand the instance look' },
+  ];
+}
+
+module.exports = { onboardPlan };