@bongos/core 1.17.0

package/modules/onboarding/onboarding-state.js

@@ -0,0 +1,532 @@
+// GDS onboarding state machine — V3.R75 (#294).
+//
+// New builders shouldn't have to track where they are in onboarding. This
+// module ticks off a small checklist for them as events fire on the server:
+//
+//   1. auth_complete        — Device Flow OR web auth callback completed.
+//   2. pick_disciplines     — the builder chose the kind of work they want
+//                              (any mix of engineer/artist/ideator) via the
+//                              hall's discipline picker (PATCH /me/disciplines).
+//   3. first_start          — the builder ran /builder-start (GET claimable).
+//   4. first_claim          — they claimed their first task.
+//   5. ship_three           — they shipped THREE tasks. Clears at the same
+//                              threshold that auto-promotes a Xenos to Thetes
+//                              (db.THETES_GRADUATION_THRESHOLD / #692), so the
+//                              checklist's graduation == the xenos→thetes
+//                              promotion. The live "N of 3" counter the hall
+//                              renders comes from shapeForApi(state, {shipCount})
+//                              — the stage itself is binary.
+//   6. graduated            — all five above cleared. Terminal stage. Fires a
+//                              one-time team-chat broadcast on transition.
+//
+// History:
+//   * A 'first_vote_received' stage sat after first_ship until 2026-05-30 — it
+//     gated graduation on a peer upvote (too much to ask of a newcomer). Removed
+//     and 'pick_disciplines' added in its place (migration 059).
+//   * A 'primer_read' stage sat after auth_complete until #766 — it made
+//     newcomers read the citizen's primer before working. Removed (migration
+//     072): the Xenos path is now purely action-based. The primer page stays
+//     for Metic+ citizens; only the newcomer requirement is gone.
+//   * 'first_ship' (one ship) was renamed to 'ship_three' (three ships) in #766
+//     so the checklist finishes exactly when the builder becomes a Thetes.
+//
+// Why a separate file from src/bongos/onboarding.js: that module is the V3.R79
+// FRICTION ANALYZER (transcript-side feedback-without-asking pipeline). Same
+// "onboarding" word, totally different responsibility. Keeping them apart is
+// the future-proofing — they'll grow independently. The CLAUDE.md handoff for
+// this task explicitly notes "extend OR new file — check first"; new file is
+// the right call here.
+//
+// The state machine is a thin convenience wrapper over the
+// builder_onboarding_state table (migration 045). Three operations matter:
+//
+//   * markStage(client, builderId, stage)
+//       Idempotent. Upserts the builder's row if missing, appends the stage to
+//       completed_stages[] if not already there, advances current_stage to the
+//       next uncompleted one in canonical order, and sets completed_at when
+//       the transition is to 'graduated'. Returns { state, justGraduated }.
+//
+//   * getState(client, builderId)
+//       Read the builder's row, returning null if missing (some legacy state
+//       where the backfill row was never created — caller treats that as
+//       "nothing done yet").
+//
+//   * broadcastGraduation(builder)
+//       Fire-and-forget Discord post. Same shape as builders.js fireDiscordBroadcast
+//       — best-effort, non-blocking, dry-run-aware.
+//
+// markStage takes a pg client (NOT a pool) so callers can run it inside the
+// transaction that created the underlying event (e.g. shipTask's BEGIN/COMMIT
+// block). When the caller has no transaction handy, it passes the pool — the
+// queries are short enough that a single round trip per stage is cheap.
+
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Canonical stage order. The first stage that ISN'T in completed_stages is
+// the one rendered to the builder as "next up". markStage uses this order to
+// advance current_stage and to detect graduation (all six prior cleared).
+const STAGES = [
+  'auth_complete',
+  'pick_disciplines',
+  'first_start',
+  'first_claim',
+  'ship_three',
+];
+
+const GRADUATED = 'graduated';
+const ALL_STAGES = [...STAGES, GRADUATED];
+
+// The pre-auth, INFORMATIONAL step that sits AHEAD of auth_complete (task 470).
+// The state machine's first ENGINE stage is auth_complete, but the genuine
+// first action a newcomer takes is "obtain the repo" — clone it locally, or open
+// the hosted dev box where it is already cloned. That step is manual/external
+// (there is no server event for it) and intentionally NOT a member of STAGES, so
+// it never gates graduation, never advances current_stage, and never appears in
+// shapeForApi's tracked checklist. It exists purely so the system's own model of
+// "the path into the city" begins where the path really begins. The hall renders
+// it as a static lead-in line on the displayed checklist; the auth_complete hint
+// above also surfaces the same clone instruction.
+const PRE_AUTH_STEP = {
+  id: 'obtain_repo',
+  label: 'Obtain the repo',
+  hint: 'Clone the project to thy machine — or open thy hosted dev box, where it is already cloned. The build commands live inside the repo, so this comes first.',
+  informational: true,
+};
+
+// How many shipped tasks the terminal 'ship_three' stage requires. Kept in
+// lockstep with db.THETES_GRADUATION_THRESHOLD (#692 / ADR 0034) so the
+// checklist's graduation coincides with the xenos→thetes promotion. Used only
+// to render the "N of 3" counter in shapeForApi — the stage clears server-side
+// in db.shipTask, which owns the authoritative threshold check.
+const SHIP_GRADUATION_TARGET = 3;
+
+// Human-readable label per stage. Echoed back from the API so the UI doesn't
+// have to mirror this list in JS. The Mediterranean tone matches the rest of
+// the hall ("Bear the seal", not "Sign in") — see modules/hall-ui/public/style.css
+// vocabulary and the builders.js welcome line.
+const STAGE_LABELS = {
+  auth_complete:    'Bear the city\'s seal',
+  pick_disciplines: 'Choose thy craft — engineer, artist, or ideator',
+  first_start:      'Survey the works on offer',
+  first_claim:      'Claim thy first work',
+  ship_three:       'Ship three works — and rise to Thetes',
+  graduated:        'Welcomed as a full citizen',
+};
+
+// Optional short hint shown on the locked stage tile. Empty hints render as
+// just the label — keep these concise.
+//
+// auth_complete's hint surfaces the clone/obtain-repo instruction (task 470).
+// The very first real action into the city is getting the project onto the
+// machine you'll build from — the /builder-* commands live INSIDE the repo, so
+// nothing (not even sign-in via the CLI) can happen before it exists. The
+// onboarding model never named that step, so the hint now points at it ahead of
+// the sign-in itself. See PRE_AUTH_STEP below for the standalone representation.
+const STAGE_HINTS = {
+  auth_complete:    'First obtain the repo — clone it (or open thy hosted dev box, where it is already cloned) — then sign in via GitHub Device Flow or the web sign-in.',
+  pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
+  first_start:      'Run /builder-start to see claimable works.',
+  first_claim:      'Claim a task with /builder-claim N.',
+  ship_three:       'Carry three tasks through with /builder-ship — the third makes thee a Thetes.',
+  graduated:        '',
+};
+
+function isKnownStage(stage) {
+  return typeof stage === 'string' && ALL_STAGES.includes(stage);
+}
+
+// ---- displayed checklist ("The Path into the City") --------------------------
+//
+// The DISPLAYED checklist is deliberately split from the graduation engine
+// above. STAGES (and nextStage/markStage/graduation) are untouched, so the
+// xenos->thetes promotion stays driven SOLELY by ship-count (#692) and the
+// graduation broadcast timing is unchanged. The list below is purely what the
+// hall renders — a short, action-only orientation path for a brand-new Xenos.
+// Every step auto-detects (#777, per Lars: no manual ticks — "the city watches"):
+//
+//   1. box_connect      — cleared the moment the builder PROPERLY connects to
+//                         their dev box, i.e. a running `claude` process is seen
+//                         on the box. Backed by builder_boxes.first_connected_at
+//                         (stamped write-once by boxes.bumpActivity on the first
+//                         claude_active=true heartbeat); passed in as
+//                         `boxConnected` (boxes.hasEverConnected). FIRST because
+//                         nothing else can happen until the box works — its hint
+//                         points the newcomer at the welcome panel's setup steps
+//                         (#823). `source: 'box'`.
+//   2. join_discord     — cleared by a live Discord link (discord.linked). The
+//                         hall's "Connect Discord & join" button runs the
+//                         existing OAuth flow (auto-join + rank role); linking
+//                         clears the step. `source: 'discord'`.
+//   3. pick_disciplines — the real engine stage, cleared by the craft picker.
+//   4. cli_setup        — cleared once the builder has authenticated the GDS CLI
+//                         (ran /builder-setup, or the box-connect bootstrap — both
+//                         mint a source='cli' session). Detected via
+//                         db.hasCliSession; passed in as `cliAuthed`. Distinct
+//                         from box_connect: connecting gets Claude running on the
+//                         box; setup signs the GDS in so /builder-* works (Lars,
+//                         #823: "both have a place"). `source: 'cli'`.
+//   5. ship_three       — the real engine stage. Auto, live "N of 3" counter,
+//                         clears at 3 ships (= the xenos->thetes promotion).
+//
+// The old 'auth_complete' (GitHub web sign-in) is intentionally NOT shown — a
+// builder signed in with GitHub to even reach this page, so it's redundant.
+// 'first_start'/'first_claim' are also dropped from display (implied by shipping)
+// to keep the list short. All three still fire server-side and keep driving the
+// graduation engine; they're simply not rendered.
+
+// The displayed checklist, in product order. `source` tells shapeForApi how to
+// derive `cleared` for each step. NONE of these are members of STAGES, so none
+// affect nextStage/graduation — they are display-only.
+const DISPLAY_STEPS = [
+  { id: 'box_connect',      source: 'box' },
+  { id: 'join_discord',     source: 'discord' },
+  { id: 'pick_disciplines', source: 'stage' },
+  { id: 'cli_setup',        source: 'cli' },
+  { id: 'ship_three',       source: 'stage' },
+];
+
+const DISPLAY_LABELS = {
+  box_connect:      'Connect to thy dev box',
+  join_discord:     'Join the Discord server',
+  pick_disciplines: 'Choose thy craft — engineer, artist, or ideator',
+  cli_setup:        'Run /builder-setup on thy dev box',
+  ship_three:       'Ship three works — and rise to Thetes',
+};
+
+const DISPLAY_HINTS = {
+  box_connect:      'Follow the steps in the welcome scroll above to get Claude running on thy dev box — this ticks itself the moment thou art connected.',
+  join_discord:     'Connect Discord — thou art auto-joined to the city\'s server and given thy rank.',
+  pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
+  cli_setup:        'Sign the GDS in on thy dev box with /builder-setup — this ticks itself once thou art signed in.',
+  ship_three:       'Carry three tasks through with /builder-ship — the third makes thee a Thetes.',
+};
+
+// Pick the first uncompleted stage from STAGES (canonical order), or
+// GRADUATED if all six are done. Mirrors the migration 045 backfill CASE so
+// app-layer behaviour matches DB-layer reconstruction.
+function nextStage(completedStages) {
+  const have = new Set(Array.isArray(completedStages) ? completedStages : []);
+  for (const s of STAGES) {
+    if (!have.has(s)) return s;
+  }
+  return GRADUATED;
+}
+
+// Has the builder cleared this stage? A stage counts as cleared when EITHER
+// it's in completed_stages[] OR the builder's current_stage is past it in
+// canonical order. The OR matters for legacy/backfill rows: a builder who
+// shipped before R75 landed has completed_stages = ['auth_complete',
+// 'first_claim', 'ship_three'] but current_stage skipped ahead (migration 045
+// parked them at the last gate; migration 059 grandfathers those to
+// 'graduated') — and we don't want to retroactively gate them on a stage they
+// never had the chance to clear (e.g. pick_disciplines).
+function hasCleared(state, stage) {
+  if (!state) return false;
+  if (!STAGES.includes(stage)) return false;
+  if (Array.isArray(state.completed_stages) && state.completed_stages.includes(stage)) {
+    return true;
+  }
+  const stageIdx = STAGES.indexOf(stage);
+  const current = state.current_stage;
+  if (current === GRADUATED) return true;
+  const currentIdx = STAGES.indexOf(current);
+  return currentIdx > stageIdx;
+}
+
+// Express middleware factory. Refuses the request when the builder hasn't
+// cleared `stage`. Always bypasses for builders who have cleared
+// `bypassAfter` (default: 'ship_three') — once they've graduated, the
+// onboarding gates are done with them. Returns a 403 with a structured
+// body the CLI can render as friendly guidance instead of "forbidden".
+//
+// Usage:
+//   router.get('/some-gated-route',
+//     auth.requireBuilder,
+//     onboardingState.requireStageCleared(pool, 'first_claim'),
+//     handler);
+//
+// `pool` is taken as a constructor arg so this module stays test-friendly
+// (the unit tests can inject a mock pool/client). General-purpose middleware:
+// the primer gate that once used it was removed in #766, but the helper stays
+// so future onboarding stages can gate routes without re-deriving the logic.
+function requireStageCleared(pool, stage, { bypassAfter = 'ship_three' } = {}) {
+  if (!STAGES.includes(stage)) {
+    throw new Error(`requireStageCleared: unknown stage "${stage}"`);
+  }
+  return async function stageGate(req, res, next) {
+    try {
+      const builderId = req.builder && req.builder.id;
+      if (!builderId) {
+        // Shouldn't happen — caller forgot requireBuilder upstream. Fail
+        // loud so it's caught in dev rather than silently allowing.
+        return res.fail('stage_gate_misconfigured', { status: 500, message: 'requireStageCleared called without requireBuilder upstream' });
+      }
+      const state = await getState(pool, builderId);
+      if (hasCleared(state, bypassAfter)) return next();
+      if (hasCleared(state, stage)) return next();
+      const currentStage = (state && state.current_stage) || STAGES[0];
+      return res.fail('stage_required', 403, { required_stage: stage, required_stage_label: STAGE_LABELS[stage], required_stage_hint: STAGE_HINTS[stage], current_stage: currentStage, current_stage_label: STAGE_LABELS[currentStage], current_stage_hint: STAGE_HINTS[currentStage], what_to_do: `Clear "${STAGE_LABELS[stage]}" before continuing — ${STAGE_HINTS[stage]}` });
+    } catch (err) {
+      console.error('[gds] requireStageCleared failed:', err);
+      // Fail open on infra errors — onboarding plumbing must never block a
+      // builder if the DB query itself errors out. The cost of a missed
+      // gate is small; the cost of bricking the API is large.
+      return next();
+    }
+  };
+}
+
+// Read the state row for a builder. Returns null when the row doesn't exist
+// (older builders pre-migration-045 who haven't had any event fire yet —
+// markStage will create the row on the next event).
+async function getState(clientOrPool, builderId) {
+  if (!Number.isFinite(Number(builderId))) return null;
+  const { rows } = await clientOrPool.query(
+    `SELECT builder_id, current_stage, completed_stages, started_at, completed_at
+       FROM builder_onboarding_state
+      WHERE builder_id = $1`,
+    [builderId]
+  );
+  if (rows.length === 0) return null;
+  return rows[0];
+}
+
+// Idempotent. Records that `stage` has been cleared for `builderId`. Creates
+// the row on first call (started_at = now()). If the stage is already in
+// completed_stages, this is a no-op (no DB write). When the new state's
+// completed_stages contains all six STAGES, current_stage flips to
+// 'graduated' and completed_at is set.
+//
+// Returns:
+//   { state, justGraduated, alreadyCleared }
+//
+//   state          — the updated row (or the existing row if no change)
+//   justGraduated  — true iff this call transitioned current_stage to
+//                    'graduated' (used by the caller to fire the broadcast)
+//   alreadyCleared — true iff `stage` was already in completed_stages
+//
+// The function is safe to call from inside an in-progress transaction by
+// passing the client; it doesn't BEGIN/COMMIT itself.
+async function markStage(clientOrPool, builderId, stage) {
+  if (!Number.isFinite(Number(builderId))) {
+    return { state: null, justGraduated: false, alreadyCleared: false };
+  }
+  if (!STAGES.includes(stage)) {
+    // 'graduated' isn't a stage you mark directly — it's the consequence of
+    // marking the last STAGE. Anything else is a programmer error and we
+    // throw so it's loud in dev, but in prod the caller wraps in try/catch
+    // so onboarding failures never block the underlying event.
+    throw new Error(`onboarding-state: unknown stage "${stage}"`);
+  }
+
+  // Insert-or-update in one statement. ON CONFLICT lets us upsert. The
+  // array_append is conditional on the stage not already being in the array
+  // — a CASE expression keeps the write idempotent without a separate read.
+  //
+  // For determining current_stage / completed_at we need the post-update
+  // completed_stages to apply the nextStage logic. The simplest correct
+  // shape is: read first inside the txn (to know what to write), write the
+  // computed result. That's two round trips per event — fine for a
+  // user-facing event rate (<<1/sec).
+  const existing = await getState(clientOrPool, builderId);
+  if (existing) {
+    const already = Array.isArray(existing.completed_stages)
+      && existing.completed_stages.includes(stage);
+    if (already) {
+      return { state: existing, justGraduated: false, alreadyCleared: true };
+    }
+    const completed = [...existing.completed_stages, stage];
+    const next = nextStage(completed);
+    const justGraduated = next === GRADUATED && existing.current_stage !== GRADUATED;
+    const { rows } = await clientOrPool.query(
+      `UPDATE builder_onboarding_state
+          SET completed_stages = $2,
+              current_stage    = $3,
+              completed_at     = CASE WHEN $4::boolean THEN now() ELSE completed_at END
+        WHERE builder_id = $1
+        RETURNING builder_id, current_stage, completed_stages, started_at, completed_at`,
+      [builderId, completed, next, justGraduated]
+    );
+    return { state: rows[0], justGraduated, alreadyCleared: false };
+  }
+
+  // No row yet — create it with the single stage already cleared.
+  const completed = [stage];
+  const next = nextStage(completed); // can't be GRADUATED from one stage
+  const { rows } = await clientOrPool.query(
+    `INSERT INTO builder_onboarding_state (builder_id, current_stage, completed_stages, started_at)
+       VALUES ($1, $2, $3, now())
+     ON CONFLICT (builder_id) DO NOTHING
+     RETURNING builder_id, current_stage, completed_stages, started_at, completed_at`,
+    [builderId, next, completed]
+  );
+  if (rows.length === 0) {
+    // Lost an insert race — re-read and recurse once. The recursion can't
+    // loop because the row now exists, so the next call lands in the
+    // existing-row branch above.
+    return markStage(clientOrPool, builderId, stage);
+  }
+  return { state: rows[0], justGraduated: false, alreadyCleared: false };
+}
+
+// Fire-and-forget Discord broadcast on graduation. Mirrors fireDiscordBroadcast in
+// src/bongos/routes/builders.js — kept as a local copy here so this module
+// stays self-contained (the rank-change broadcast lives next to its router;
+// the graduation broadcast lives next to its state machine). Outbound moved
+// from Google Chat to Discord #ship-news per ADR 0032 / #607 (scripts/chat/
+// is inbound-only now). CHAT_DRY_RUN=1 still short-circuits for the smoke path
+// (the name is a legacy artifact — it gates all broadcast transports, not just Chat).
+//
+// builder is the row from db.getBuilderById — we use display_name or
+// github_login for the name.
+function broadcastGraduation(builder) {
+  const who = (builder && (builder.display_name || builder.github_login)) || 'a builder';
+  // "Citizens of <worldName>" from the branding pack (via the doorway), never a
+  // hardcoded host brand (ADR 0062 §3) — a non-OTB instance greets its own world.
+  const worldName = (() => { try { return require('../../src/module-api').branding().identity?.worldName || 'the city'; } catch { return 'the city'; } })();
+  const text = `Citizens of ${worldName} — ${who} has completed onboarding.`;
+  if (process.env.CHAT_DRY_RUN === '1') {
+    console.log(`[gds] [broadcast dry-run] would post: ${text}`);
+    return;
+  }
+  try {
+    execFile(
+      'node',
+      ['scripts/discord/post.js', text],
+      { cwd: REPO_ROOT, timeout: 10_000 },
+      (err, _stdout, stderr) => {
+        if (err) {
+          console.log('[gds] graduation broadcast failed (non-blocking):', err.message);
+          if (stderr) console.log('[gds] discord stderr:', stderr.toString().trim());
+        }
+      }
+    );
+  } catch (e) {
+    console.log('[gds] graduation broadcast spawn failed (non-blocking):', e && e.message);
+  }
+}
+
+// Helper for routes: mark a stage and, on graduation, kick off the Discord
+// broadcast. Swallows errors so onboarding plumbing never breaks an
+// underlying event. Returns the markStage result (or null on failure).
+async function safeMarkStage(clientOrPool, builderId, stage, builderForBroadcast = null) {
+  try {
+    const result = await markStage(clientOrPool, builderId, stage);
+    if (result.justGraduated && builderForBroadcast) {
+      broadcastGraduation(builderForBroadcast);
+    }
+    return result;
+  } catch (err) {
+    console.log(
+      `[gds] onboarding markStage(${builderId}, ${stage}) failed (non-blocking):`,
+      err && err.message
+    );
+    return null;
+  }
+}
+
+// Build the per-stage "detail" line. Only the terminal 'ship_three' stage has
+// one: a live "N of 3" counter so the builder watches their progress toward
+// Thetes with each ship. `shipCount` is the builder's shipped-task count
+// (passed by the route); null means "not supplied" → no counter rendered.
+function stageDetail(stageId, shipCount) {
+  if (stageId !== 'ship_three') return '';
+  if (shipCount == null || !Number.isFinite(Number(shipCount))) return '';
+  const n = Math.min(Math.max(0, Number(shipCount)), SHIP_GRADUATION_TARGET);
+  return `${n} of ${SHIP_GRADUATION_TARGET} works shipped`;
+}
+
+// Shape the API response for one builder. Used by GET /builders/:id/onboarding
+// and embedded in the /me payload. When the row is missing (legacy builder,
+// no event fired yet), we synthesize a "nothing cleared" view so the client
+// never gets null.
+//
+// Returns the DISPLAYED checklist (DISPLAY_STEPS), not the raw engine STAGES —
+// see the displayed-checklist block above for why they're split. `graduated`
+// and `current_stage` still reflect the engine (so the welcome panel's
+// dismissal index and the panel-hide-on-graduation behaviour are unchanged).
+//
+// opts.shipCount     — the builder's count of successfully shipped tasks. Drives
+//                      the 'ship_three' step's live "N of 3" counter. Omit/null
+//                      → the counter isn't rendered.
+// opts.discordLinked — whether the builder has a live Discord link. Clears the
+//                      'join_discord' step (the OAuth flow sets the link).
+// opts.boxConnected  — whether the builder's dev box has ever reported a live
+//                      Claude process (boxes.hasEverConnected → first_connected_at).
+//                      Clears the 'box_connect' step (#823).
+// opts.cliAuthed     — whether the builder has ever authenticated the GDS CLI
+//                      (db.hasCliSession). Clears the 'cli_setup' step.
+function shapeForApi(state, { shipCount = null, discordLinked = false, boxConnected = false, cliAuthed = false } = {}) {
+  const completed   = new Set((state && state.completed_stages) || []);
+  const currentReal = (state && state.current_stage) || STAGES[0];
+  const graduated   = currentReal === GRADUATED;
+
+  // Per-step cleared resolution, by `source`. 'stage' mirrors hasCleared (in
+  // completed_stages, OR the engine advanced past it). 'discord'/'box'/'cli'
+  // derive from live signals passed by the route. A graduated builder has cleared
+  // everything by definition (keeps the displayed list coherent even though the
+  // panel hides on graduation — a roster/profile read could still surface this).
+  const stepCleared = (step) => {
+    if (graduated) return true;
+    if (step.source === 'discord') return !!discordLinked;
+    if (step.source === 'box') return !!boxConnected;
+    if (step.source === 'cli') return !!cliAuthed;
+    // 'stage'
+    if (completed.has(step.id)) return true;
+    const i = STAGES.indexOf(step.id);
+    const c = STAGES.indexOf(currentReal);
+    return i >= 0 && c > i;
+  };
+
+  const display = DISPLAY_STEPS.map((step) => ({
+    id: step.id,
+    source: step.source,
+    label: DISPLAY_LABELS[step.id],
+    hint: DISPLAY_HINTS[step.id],
+    detail: stageDetail(step.id, shipCount),
+    cleared: stepCleared(step),
+  }));
+
+  // is_current = the first uncleared DISPLAYED step, so the hall highlights
+  // exactly one "do this next". None is current once graduated.
+  const firstGap = display.find((s) => !s.cleared);
+  for (const s of display) {
+    s.is_current = !graduated && !!firstGap && s.id === firstGap.id;
+  }
+  const clearedCount = display.filter((s) => s.cleared).length;
+
+  return {
+    current_stage: currentReal,
+    completed_stages: (state && state.completed_stages) || [],
+    started_at: state ? state.started_at : null,
+    completed_at: state ? state.completed_at : null,
+    progress: { cleared: clearedCount, total: DISPLAY_STEPS.length },
+    stages: display,
+    graduated,
+  };
+}
+
+module.exports = {
+  STAGES,
+  GRADUATED,
+  ALL_STAGES,
+  PRE_AUTH_STEP,
+  SHIP_GRADUATION_TARGET,
+  STAGE_LABELS,
+  STAGE_HINTS,
+  DISPLAY_STEPS,
+  DISPLAY_LABELS,
+  DISPLAY_HINTS,
+  isKnownStage,
+  nextStage,
+  hasCleared,
+  getState,
+  markStage,
+  safeMarkStage,
+  broadcastGraduation,
+  shapeForApi,
+  requireStageCleared,
+};