@bongos/core 1.17.0

package/tests/next_number.mjs

@@ -0,0 +1,154 @@
+// tests/next_number.mjs
+//
+// V4.R26 / #964 — deterministic next-free ADR + migration numbers. The collision
+// class this kills: parallel sessions each scanned their own (stale) local tree
+// and picked the same "next" number (triple ADR-0044), and the claim-time DB
+// counter drifted from the committed files (handed already-applied numbers; sits
+// ahead of migrations/ today). next-number.js computes max(origin/main ∪ local)+1
+// from the AUTHORITATIVE committed set. These tests pin the pure core + the
+// fail-open facade with injected git/fs, so there is NO real git/DB dependency.
+//
+// Run:  node tests/next_number.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { parseNumbers, nextFree, computeNextNumbers, nextNumbers, padAdr, padMig } =
+  require('../scripts/gds/next-number.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- parseNumbers ----------------------------------------------------------
+t('parseNumbers: ADR 4-digit prefixes only', () => {
+  const set = parseNumbers(['0057-x.md', '0001-y.md', 'README.md', '0044-z.md'], /^(\d{4})-.*\.md$/);
+  assert.deepEqual([...set].sort((a, b) => a - b), [1, 44, 57]);
+});
+
+t('parseNumbers: migration 3+ digit prefixes only', () => {
+  const set = parseNumbers(['093_a.sql', '020_b.sql', 'notes.txt', '100_c.sql'], /^(\d{3,})_.*\.sql$/);
+  assert.deepEqual([...set].sort((a, b) => a - b), [20, 93, 100]);
+});
+
+// ---- nextFree --------------------------------------------------------------
+t('nextFree: max + 1', () => {
+  assert.equal(nextFree(new Set([1, 44, 57])), 58);
+  assert.equal(nextFree(new Set([93])), 94);
+});
+
+t('nextFree: empty set uses the start floor', () => {
+  assert.equal(nextFree(new Set(), 1), 1);
+  assert.equal(nextFree(new Set(), 3), 3);
+});
+
+t('nextFree: holes are NOT filled — next is always above the max (sequential append)', () => {
+  // migrations/ has a 092 hole today (091, 093). Next must be 094, not 092.
+  assert.equal(nextFree(new Set([91, 93])), 94);
+});
+
+// ---- computeNextNumbers (the pure union) -----------------------------------
+t('computeNextNumbers: unions committed + local, classifies by dir', () => {
+  const r = computeNextNumbers({
+    committedPaths: ['docs/adr/0057-a.md', 'migrations/093_b.sql', 'migrations/091_c.sql'],
+    localPaths: ['docs/adr/0058-wip.md', 'migrations/094_wip.sql'],
+  });
+  // local wip ADR 0058 + migration 094 must count → next is 0059 / 095.
+  assert.equal(r.adr, 59);
+  assert.equal(r.migration, 95);
+  assert.equal(r.highestAdr, 58);
+  assert.equal(r.highestMigration, 94);
+});
+
+t('computeNextNumbers: a stale local tree behind origin/main still yields the true next (collision-kill)', () => {
+  // The bug scenario: my local tree only knows ADR 0044, but origin/main already
+  // has 0057. Reading BOTH means I pick 0058, not a colliding 0045.
+  const r = computeNextNumbers({
+    committedPaths: ['docs/adr/0057-shipped-by-someone-else.md'],
+    localPaths: ['docs/adr/0044-my-stale-copy.md'],
+  });
+  assert.equal(r.adr, 58);
+});
+
+t('computeNextNumbers: ignores non-matching files (README, index, .keep)', () => {
+  const r = computeNextNumbers({
+    committedPaths: ['docs/adr/README.md', 'docs/adr/0010-x.md', 'migrations/.keep'],
+    localPaths: [],
+  });
+  assert.equal(r.adr, 11);
+  assert.equal(r.migration, 1, 'no migration files → sequence floor');
+});
+
+t('computeNextNumbers: counts NAMESPACED core_/<key>_ migrations too (ADR 0108 §5 — no reuse)', () => {
+  // Once core migrations are core_-prefixed, a bare-only regex would UNDERCOUNT them and hand
+  // out an already-used number. The allocator must count both bare and namespaced forms.
+  const r = computeNextNumbers({
+    committedPaths: ['migrations/187_a.sql', 'migrations/core_188_b.sql'],
+    localPaths: ['migrations/core_190_wip.sql'],
+  });
+  assert.equal(r.migration, 191, 'a prefixed core_190 must count → next 191, not 188');
+  assert.equal(r.highestMigration, 190);
+});
+
+// ---- nextNumbers facade (injected git + fs) --------------------------------
+function fakeGit(treeByRef) {
+  // treeByRef: { 'origin/main': [paths] | Error, 'HEAD': [paths] | Error }
+  return (args) => {
+    // args = ['ls-tree','-r','--name-only', <ref>, '--', ...dirs]
+    const ref = args[3];
+    const v = treeByRef[ref];
+    if (v instanceof Error || v === undefined) throw v || new Error(`no ref ${ref}`);
+    return v.join('\n');
+  };
+}
+const fakeReadDir = (byDir) => (p) => {
+  const key = Object.keys(byDir).find((d) => p.endsWith(d));
+  if (!key) throw new Error('ENOENT');
+  return byDir[key];
+};
+
+t('nextNumbers: prefers origin/main, unions local, source=origin/main', () => {
+  const r = nextNumbers({
+    runGit: fakeGit({ 'origin/main': ['docs/adr/0057-a.md', 'migrations/093_b.sql'] }),
+    readDir: fakeReadDir({ 'docs/adr': ['0057-a.md'], migrations: ['093_b.sql', '094_local_wip.sql'] }),
+  });
+  assert.equal(r.source, 'origin/main');
+  assert.equal(r.degraded, false);
+  assert.equal(r.adr, 58);
+  assert.equal(r.migration, 95, 'local wip 094 counts → next 095');
+});
+
+t('nextNumbers: falls back to HEAD when origin/main is unreachable, flags degraded', () => {
+  const r = nextNumbers({
+    runGit: fakeGit({ 'origin/main': new Error('unknown revision'), HEAD: ['migrations/090_x.sql'] }),
+    readDir: fakeReadDir({ 'docs/adr': [], migrations: ['090_x.sql'] }),
+  });
+  assert.equal(r.source, 'HEAD');
+  assert.equal(r.degraded, true);
+  assert.equal(r.migration, 91);
+});
+
+t('nextNumbers: total git failure falls back to local-only, still does not throw', () => {
+  const r = nextNumbers({
+    runGit: fakeGit({}), // every ref throws
+    readDir: fakeReadDir({ 'docs/adr': ['0003-x.md'], migrations: ['001_y.sql'] }),
+  });
+  assert.equal(r.source, 'local-only');
+  assert.equal(r.degraded, true);
+  assert.equal(r.adr, 4);
+  assert.equal(r.migration, 2);
+});
+
+// ---- padding ---------------------------------------------------------------
+t('padAdr / padMig: 4-digit ADR, 3-digit migration', () => {
+  assert.equal(padAdr(58), '0058');
+  assert.equal(padMig(94), '094');
+  assert.equal(padMig(100), '100'); // does not truncate above the pad width
+});
+
+console.log(`\nnext_number: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/oauth_secret.mjs

@@ -0,0 +1,60 @@
+// tests/oauth_secret.mjs — DB-free unit tests for the verified OAuth-secret
+// placement helper (scripts/gds/oauth-secret.js, BONGOS-V1 goal 35 / task 1979).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const oauth = require('../scripts/gds/oauth-secret.js');
+
+test('validateClientSecret rejects empty / placeholder / truncated; accepts a real 40-char secret', () => {
+  assert.equal(oauth.validateClientSecret('').ok, false);
+  assert.equal(oauth.validateClientSecret('   ').ok, false);
+  assert.equal(oauth.validateClientSecret('xxxxxxxxxxxx').ok, false);           // placeholder
+  assert.equal(oauth.validateClientSecret('changeme').ok, false);
+  // the exact standup failure: a 26-char truncated secret must be REJECTED
+  const truncated = 'a'.repeat(26);
+  const r = oauth.validateClientSecret(truncated);
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /too short|truncat/i);
+  // a real GitHub OAuth client secret (40 hex chars) passes
+  assert.equal(oauth.validateClientSecret('0123456789abcdef0123456789abcdef01234567').ok, true);
+  // whitespace/quotes in the middle → bad paste
+  assert.equal(oauth.validateClientSecret('0123456789abcdef 0123456789abcdef012345').ok, false);
+});
+
+test('validateClientId rejects empty / too-short; accepts a classic 20-char id and an App id', () => {
+  assert.equal(oauth.validateClientId('').ok, false);
+  assert.equal(oauth.validateClientId('short').ok, false);
+  assert.equal(oauth.validateClientId('0123456789abcdef0123').ok, true);         // classic 20 hex
+  assert.equal(oauth.validateClientId('Iv1.0123456789abcdef').ok, true);          // GitHub App id
+});
+
+test('fillOAuthEnv rewrites the prefixed lines in place and leaves others intact', () => {
+  const body = [
+    '# comment',
+    'CLOUDBONGOS_GITHUB_CLIENT_ID=',
+    'CLOUDBONGOS_GITHUB_CLIENT_SECRET=',
+    'GDS_BRANDING_FILE=config/branding.neutral.json',
+    'PORT=3003',
+    'PGDATABASE=demo',
+  ].join('\n');
+  const out = oauth.fillOAuthEnv(body, { prefix: 'CLOUDBONGOS', clientId: 'Iv1.abc0123456789def', clientSecret: '0123456789abcdef0123456789abcdef01234567' });
+  assert.match(out, /^CLOUDBONGOS_GITHUB_CLIENT_ID=Iv1\.abc0123456789def$/m);
+  assert.match(out, /^CLOUDBONGOS_GITHUB_CLIENT_SECRET=0123456789abcdef0123456789abcdef01234567$/m);
+  assert.match(out, /^PORT=3003$/m);                 // untouched
+  assert.match(out, /^GDS_BRANDING_FILE=config\/branding\.neutral\.json$/m); // untouched
+  assert.equal(out.split('\n').length, body.split('\n').length); // no line added/removed
+});
+
+test('fillOAuthEnv THROWS when the target key line is absent (never silently no-ops)', () => {
+  const body = 'OTHER_GITHUB_CLIENT_ID=\nPORT=3003\n';
+  assert.throws(() => oauth.fillOAuthEnv(body, { prefix: 'CLOUDBONGOS', clientId: 'x'.repeat(20) }), /no "CLOUDBONGOS_GITHUB_CLIENT_ID=" line/);
+});
+
+test('portFromEnv reads PORT; parseHealthzAuth reads auth_configured', () => {
+  assert.equal(oauth.portFromEnv('PORT=3007\nPGDATABASE=x'), 3007);
+  assert.equal(oauth.portFromEnv('no port here'), null);
+  assert.equal(oauth.parseHealthzAuth('{"ok":true,"auth_configured":true}').authConfigured, true);
+  assert.equal(oauth.parseHealthzAuth('{"ok":true,"auth_configured":false}').authConfigured, false);
+  assert.equal(oauth.parseHealthzAuth('not json').parseError, true);
+});

package/tests/onboard.mjs

@@ -0,0 +1,70 @@
+// tests/onboard.mjs — DB-free unit tests for the `bongos onboard` CLI pure core
+// (scripts/gds/onboard.js, BONGOS-V1 goal 35 / task 1982). The interactive shell is
+// exercised by hand; the sequence + the human-step values are pinned here.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const ob = require('../scripts/gds/onboard.js');
+
+test('onboardPlan is the canonical sequence: name+address first, brand last, four legs automated around the human steps', () => {
+  const plan = ob.onboardPlan();
+  const keys = plan.map((s) => s.key);
+  assert.equal(keys[0], 'name-address');
+  assert.equal(keys[keys.length - 1], 'brand');
+  // the irreducibly-human steps (must be UI-first prompts)
+  const human = plan.filter((s) => s.kind === 'human').map((s) => s.key);
+  assert.deepEqual(human, ['github-repo', 'oauth-app', 'first-sign-in']);
+  // the DNS preflight comes BEFORE provision (task 1980: before the address step)
+  assert.ok(keys.indexOf('dns-preflight') < keys.indexOf('provision'), 'dns preflight precedes provision');
+  // OAuth secret placement comes after the OAuth app + before first sign-in
+  assert.ok(keys.indexOf('oauth-app') < keys.indexOf('oauth-place'), 'app before place');
+  assert.ok(keys.indexOf('oauth-place') < keys.indexOf('first-sign-in'), 'place before sign-in');
+});
+
+test('onboardPlan(adopt): same sequence + human steps, but the scaffold-leg labels branch (task 2046)', () => {
+  const green = ob.onboardPlan();
+  const adopt = ob.onboardPlan('adopt');
+  // identical skeleton: same keys + same human steps
+  assert.deepEqual(adopt.map((s) => s.key), green.map((s) => s.key));
+  assert.deepEqual(adopt.filter((s) => s.kind === 'human').map((s) => s.key), green.filter((s) => s.kind === 'human').map((s) => s.key));
+  // only the github-repo / init / scaffold labels differ, reflecting --adopt
+  const label = (plan, key) => plan.find((s) => s.key === key).label;
+  assert.match(label(adopt, 'github-repo'), /EXISTING/);
+  assert.match(label(adopt, 'init'), /--adopt/);
+  assert.match(label(adopt, 'scaffold'), /Layer/i);
+  assert.match(label(green, 'github-repo'), /empty/i); // greenfield unchanged
+  assert.doesNotMatch(label(green, 'init'), /--adopt/);
+});
+
+test('oauthAppInstructions pins the apex callback + homepage and points at ACCOUNT Developer settings', () => {
+  const oa = ob.oauthAppInstructions('mercury.example.com');
+  assert.equal(oa.homepageUrl, 'https://mercury.example.com');
+  assert.equal(oa.callbackUrl, 'https://mercury.example.com/api/gds/auth/web/callback');
+  assert.match(oa.location, /ACCOUNT/);
+  assert.match(oa.location, /Developer settings/);
+});
+
+test('buildInitSpec maps answers to a STANDALONE init spec (domain → origin + provisioning shape)', () => {
+  const spec = ob.buildInitSpec({
+    productName: 'Mercury', repoOwner: 'acme', repoName: 'mercury', firstAdmin: 'acme', slug: 'mercury', domain: 'mercury.example.com',
+  });
+  assert.equal(spec.identity.productName, 'Mercury');
+  assert.equal(spec.repo.owner, 'acme');
+  assert.equal(spec.repo.name, 'mercury');
+  assert.equal(spec.firstAdmin, 'acme');
+  assert.equal(spec.domains.publicOrigin, 'https://mercury.example.com');
+  assert.equal(spec.provisioning.shape, 'standalone');
+  assert.equal(spec.provisioning.slug, 'mercury');
+});
+
+test('buildInitSpec without a domain still defaults a standalone provisioning shape by slug', () => {
+  const spec = ob.buildInitSpec({ productName: 'X', repoOwner: 'o', repoName: 'x', slug: 'x' });
+  assert.equal(spec.provisioning.shape, 'standalone');
+  assert.equal(spec.provisioning.domain, null);
+  assert.equal(spec.domains, undefined);
+});
+
+test('healthzUrl', () => {
+  assert.equal(ob.healthzUrl('mercury.example.com'), 'https://mercury.example.com/healthz');
+});

package/tests/onboarding_gate.mjs

@@ -0,0 +1,267 @@
+// tests/onboarding_gate.mjs
+//
+// V3.R13 (#237) — Unit tests for the onboarding stage gate.
+//
+// Covers two surfaces:
+//   - hasCleared(state, stage): the OR check — completed_stages OR
+//     current_stage past the named stage in canonical order. This is the
+//     load-bearing function for backfilled-builder bypass.
+//   - requireStageCleared(pool, stage, opts): the Express middleware. We
+//     drive it with a stub pool + fake req/res and assert on the response
+//     shape (or that next() was called).
+//
+// Pure unit tests — no live DB. The DB-touching path is exercised by the
+// post-deploy smoke and by the existing onboarding_state.mjs harness.
+//
+// Run:  node tests/onboarding_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const onboarding = require('../modules/onboarding/onboarding-state.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+let passed = 0;
+let failed = 0;
+
+function t(name, fn) {
+  try {
+    const r = fn();
+    if (r && typeof r.then === 'function') {
+      return r.then(
+        () => { passed += 1; console.log(`  ok   ${name}`); },
+        (err) => { failed += 1; console.log(`  FAIL ${name}\n       ${err.message}`); }
+      );
+    }
+    passed += 1; console.log(`  ok   ${name}`);
+  } catch (err) {
+    failed += 1; console.log(`  FAIL ${name}\n       ${err.message}`);
+  }
+}
+
+// ---------- hasCleared ----------
+
+t('hasCleared: null state → false for any stage', () => {
+  assert.equal(onboarding.hasCleared(null, 'pick_disciplines'), false);
+  assert.equal(onboarding.hasCleared(undefined, 'ship_three'), false);
+});
+
+t('hasCleared: stage in completed_stages → true', () => {
+  const state = { completed_stages: ['auth_complete', 'pick_disciplines'], current_stage: 'first_start' };
+  assert.equal(onboarding.hasCleared(state, 'pick_disciplines'), true);
+});
+
+t('hasCleared: current_stage past target → true (backfill rescue)', () => {
+  // A pre-existing shipper carries ship_three in completed_stages WITHOUT
+  // pick_disciplines. Migrations grandfather such legacy rows to
+  // current_stage='graduated'; hasCleared should treat them as past every
+  // earlier stage so a gate doesn't lock out anyone who shipped before the
+  // reshaped path landed.
+  const backfilled = {
+    completed_stages: ['auth_complete', 'first_claim', 'ship_three'],
+    current_stage: 'graduated',
+  };
+  assert.equal(onboarding.hasCleared(backfilled, 'pick_disciplines'), true);
+  assert.equal(onboarding.hasCleared(backfilled, 'first_start'), true);
+  assert.equal(onboarding.hasCleared(backfilled, 'ship_three'), true);
+});
+
+t('hasCleared: graduated bypasses everything', () => {
+  const grad = { completed_stages: [], current_stage: 'graduated' };
+  assert.equal(onboarding.hasCleared(grad, 'pick_disciplines'), true);
+  assert.equal(onboarding.hasCleared(grad, 'ship_three'), true);
+});
+
+t('hasCleared: fresh newcomer cleared nothing → false for pick_disciplines', () => {
+  const fresh = { completed_stages: ['auth_complete'], current_stage: 'pick_disciplines' };
+  assert.equal(onboarding.hasCleared(fresh, 'pick_disciplines'), false);
+  assert.equal(onboarding.hasCleared(fresh, 'ship_three'), false);
+  // But auth_complete IS cleared.
+  assert.equal(onboarding.hasCleared(fresh, 'auth_complete'), true);
+});
+
+t('hasCleared: unknown stage → false (defensive)', () => {
+  const state = { completed_stages: ['auth_complete'], current_stage: 'pick_disciplines' };
+  assert.equal(onboarding.hasCleared(state, 'not_a_real_stage'), false);
+});
+
+// ---------- requireStageCleared ----------
+
+function fakeReq(builderId) {
+  return { builder: builderId == null ? null : { id: builderId } };
+}
+
+function fakeRes() {
+  const res = { _status: 200, _body: null, _sent: false };
+  res.status = function (code) { this._status = code; return this; };
+  res.json = function (body) { this._body = body; this._sent = true; return this; };
+  attachFail({}, res, () => {}); // install res.fail(), exactly as the router does (task 1991)
+  return res;
+}
+
+// Stub pool that returns whatever state we set up for the test.
+function stubPool(stateForBuilderId) {
+  return {
+    query: async (_sql, params) => {
+      const id = params && params[0];
+      const state = stateForBuilderId[id];
+      return { rows: state ? [state] : [] };
+    },
+  };
+}
+
+// The primer gate that once used requireStageCleared was removed in #766, but
+// the middleware stays as general-purpose infrastructure. These tests exercise
+// it against the still-live 'first_claim' stage to prove the mechanism.
+t('requireStageCleared: calls next() when stage cleared', async () => {
+  const state = { builder_id: 1, completed_stages: ['auth_complete', 'pick_disciplines', 'first_start', 'first_claim'], current_stage: 'ship_three' };
+  const pool = stubPool({ 1: state });
+  const gate = onboarding.requireStageCleared(pool, 'first_claim');
+  const req = fakeReq(1);
+  const res = fakeRes();
+  let called = false;
+  await gate(req, res, () => { called = true; });
+  assert.equal(called, true, 'next() should have been called');
+  assert.equal(res._sent, false, 'res should not have been written');
+});
+
+t('requireStageCleared: 403 when stage not cleared and not past bypassAfter', async () => {
+  const state = { builder_id: 2, completed_stages: ['auth_complete'], current_stage: 'pick_disciplines' };
+  const pool = stubPool({ 2: state });
+  const gate = onboarding.requireStageCleared(pool, 'first_claim');
+  const req = fakeReq(2);
+  const res = fakeRes();
+  let called = false;
+  await gate(req, res, () => { called = true; });
+  assert.equal(called, false, 'next() should NOT have been called');
+  assert.equal(res._status, 403);
+  assert.equal(res._body.error.code, 'stage_required');
+  assert.equal(res._body.error.details.required_stage, 'first_claim');
+  assert.match(res._body.error.details.what_to_do, /builder-claim/i);
+});
+
+t('requireStageCleared: bypasses when past ship_three (default bypass)', async () => {
+  // A graduated builder carries ship_three in completed_stages. The bypass
+  // kicks in via hasCleared(state, 'ship_three') → true.
+  const state = {
+    builder_id: 3,
+    completed_stages: ['auth_complete', 'first_claim', 'ship_three'],
+    current_stage: 'graduated',
+  };
+  const pool = stubPool({ 3: state });
+  const gate = onboarding.requireStageCleared(pool, 'first_claim');
+  const req = fakeReq(3);
+  const res = fakeRes();
+  let called = false;
+  await gate(req, res, () => { called = true; });
+  assert.equal(called, true, 'graduated builder should bypass the gate');
+});
+
+t('requireStageCleared: 403 when no state row (true newcomer)', async () => {
+  const pool = stubPool({}); // empty — no row for builder 4
+  const gate = onboarding.requireStageCleared(pool, 'first_claim');
+  const req = fakeReq(4);
+  const res = fakeRes();
+  let called = false;
+  await gate(req, res, () => { called = true; });
+  assert.equal(called, false);
+  assert.equal(res._status, 403);
+  assert.equal(res._body.error.details.current_stage, 'auth_complete');
+});
+
+t('requireStageCleared: 500 when called without requireBuilder upstream', async () => {
+  const pool = stubPool({});
+  const gate = onboarding.requireStageCleared(pool, 'first_claim');
+  const req = fakeReq(null);
+  const res = fakeRes();
+  await gate(req, res, () => { throw new Error('next() must not be called'); });
+  assert.equal(res._status, 500);
+  assert.equal(res._body.error.code, 'stage_gate_misconfigured');
+});
+
+t('requireStageCleared: fails open on DB error', async () => {
+  const pool = {
+    query: async () => { throw new Error('connection refused'); },
+  };
+  const gate = onboarding.requireStageCleared(pool, 'first_claim');
+  const req = fakeReq(5);
+  const res = fakeRes();
+  let called = false;
+  await gate(req, res, () => { called = true; });
+  // Onboarding plumbing must never brick the API — DB error should fall
+  // through to the handler.
+  assert.equal(called, true, 'gate should fail open on DB error');
+});
+
+t('requireStageCleared: throws at construction time for unknown stage', () => {
+  assert.throws(
+    () => onboarding.requireStageCleared({}, 'not_a_stage'),
+    /unknown stage/i
+  );
+});
+
+// ---------- printOnboardingNudge (CLI helper) ----------
+// Lives in scripts/gds/cli-lib.js. Quick sanity that it doesn't print for
+// graduated builders or those who reached ship_three, and DOES print for
+// newcomers.
+const cliLib = require('../scripts/gds/cli-lib.js');
+
+function captureStdout(fn) {
+  const lines = [];
+  const orig = console.log;
+  console.log = (...args) => lines.push(args.join(' '));
+  try { fn(); } finally { console.log = orig; }
+  return lines.join('\n');
+}
+
+t('printOnboardingNudge: silent for graduated', () => {
+  const out = captureStdout(() => {
+    cliLib.printOnboardingNudge({ onboarding: { graduated: true, current_stage: 'graduated', completed_stages: [] } });
+  });
+  assert.equal(out, '');
+});
+
+t('printOnboardingNudge: silent past ship_three', () => {
+  const out = captureStdout(() => {
+    cliLib.printOnboardingNudge({ onboarding: {
+      graduated: false,
+      current_stage: 'ship_three',
+      completed_stages: ['auth_complete', 'first_claim', 'ship_three'],
+      stages: [],
+    }});
+  });
+  assert.equal(out, '');
+});
+
+t('printOnboardingNudge: prints for newcomer at pick_disciplines', () => {
+  const out = captureStdout(() => {
+    cliLib.printOnboardingNudge({ onboarding: {
+      graduated: false,
+      current_stage: 'pick_disciplines',
+      completed_stages: ['auth_complete'],
+      stages: [
+        { id: 'auth_complete', label: 'Bear the city\'s seal', cleared: true, is_current: false },
+        { id: 'pick_disciplines', label: 'Choose thy craft — creative or engineering', cleared: false, is_current: true },
+      ],
+    }});
+  });
+  assert.match(out, /^Next: /, 'should start with Next:');
+  assert.match(out, /craft/i, 'should mention choosing a craft');
+});
+
+t('printOnboardingNudge: silent when no onboarding payload', () => {
+  const out = captureStdout(() => {
+    cliLib.printOnboardingNudge({});
+    cliLib.printOnboardingNudge(null);
+    cliLib.printOnboardingNudge(undefined);
+  });
+  assert.equal(out, '');
+});
+
+// ---------- summary ----------
+
+Promise.resolve().then(() => setTimeout(() => {
+  console.log(`\n${passed} passed, ${failed} failed`);
+  process.exit(failed === 0 ? 0 : 1);
+}, 100));