@bongos/core 1.18.3 → 1.18.18

package/tests/upgrade.mjs

@@ -796,6 +796,145 @@ t('runUpgrade: no managed restart + no --health-url proceeds but flags the bump
   assert.ok(logs.some((m) => /not confirmed serving/.test(m)), logs.join('\n'));
 });
 
+// ---- regenerateNavDocs (ADR 0147 / task 1002314) ----------------------------
+t('regenerateNavDocs: default set is the whole-file nav docs (session-index only)', () => {
+  assert.deepEqual(u.NAV_WHOLE_FILE_GENERATORS, ['gen-session-index.js']);
+});
+
+t('regenerateNavDocs: spawns each generator from the CORE against the INSTANCE root (cwd + CLOUDBONGOS_INSTANCE_ROOT), ok when all succeed', () => {
+  const calls = [];
+  const run = (cmd, args, opts) => { calls.push({ cmd, arg0: args[0], cwd: opts && opts.cwd, env: opts && opts.env }); return { status: 0 }; };
+  const fsImpl = { existsSync: () => true };
+  const res = u.regenerateNavDocs({ instanceDir: '/inst', coreRoot: '/core', generators: ['gen-session-index.js'] }, run, fsImpl);
+  assert.equal(res.ok, true);
+  assert.deepEqual(res.ran, ['gen-session-index.js']);
+  assert.deepEqual(res.failed, []);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].cwd, '/inst', 'runs with cwd = the instance dir');
+  assert.equal(calls[0].env.CLOUDBONGOS_INSTANCE_ROOT, '/inst', 'sets the instance-root env so the generator writes into the instance');
+  assert.equal(calls[0].arg0, join('/core', 'scripts', 'gds', 'gen-session-index.js'), 'spawns the generator from the CORE package');
+});
+
+t('regenerateNavDocs: a MISSING generator is recorded as failed but the others still run (best-effort)', () => {
+  const spawned = [];
+  const run = (_cmd, args) => { spawned.push(args[0]); return { status: 0 }; };
+  const fsImpl = { existsSync: (p) => !String(p).endsWith('gen-missing.js') };
+  const res = u.regenerateNavDocs({ instanceDir: '/inst', coreRoot: '/core', generators: ['gen-missing.js', 'gen-session-index.js'] }, run, fsImpl);
+  assert.equal(res.ok, false);
+  assert.deepEqual(res.ran, ['gen-session-index.js']);
+  assert.equal(res.failed.length, 1);
+  assert.equal(res.failed[0].gen, 'gen-missing.js');
+  assert.equal(spawned.length, 1, 'the missing generator is not spawned; the present one still is');
+});
+
+t('regenerateNavDocs: a generator that exits nonzero is LOUD-failed (ok:false) without aborting the rest', () => {
+  const run = (_cmd, args) => ({ status: String(args[0]).endsWith('gen-boom.js') ? 2 : 0 });
+  const fsImpl = { existsSync: () => true };
+  const res = u.regenerateNavDocs({ instanceDir: '/inst', coreRoot: '/core', generators: ['gen-boom.js', 'gen-session-index.js'] }, run, fsImpl);
+  assert.equal(res.ok, false);
+  assert.deepEqual(res.ran, ['gen-session-index.js']);
+  assert.equal(res.failed.length, 1);
+  assert.equal(res.failed[0].gen, 'gen-boom.js');
+  assert.match(res.failed[0].reason, /exited 2/);
+});
+
+// ---- healDocAssets (task 1002441) -------------------------------------------
+// An upgrade replaces node_modules wholesale, so it WIPES the two gitignored, core-scoped
+// generated doc assets (atlas.json + the diagram .svg/.png renders) and the new tarball carries
+// only the .mmd sources. These pin that the upgrade puts them back.
+
+// A fake core tree. `renders` controls whether each .mmd already has its .svg + .png beside it.
+function docAssetFs({ atlas = true, sources = ['01-a.mmd', '02-b.mmd'], renders = true } = {}) {
+  const present = new Set();
+  if (atlas) present.add(join('/core', 'modules', 'hall-ui', 'public', 'atlas.json'));
+  present.add(join('/core', 'scripts', 'gds', 'gen-atlas.js'));
+  present.add(join('/core', 'scripts', 'render-diagrams.sh'));
+  if (renders) {
+    for (const s of sources) {
+      const base = join('/core', 'docs', 'onboarding', 'diagrams', s.replace(/\.mmd$/, ''));
+      present.add(`${base}.svg`); present.add(`${base}.png`);
+    }
+  }
+  return { existsSync: (p) => present.has(String(p)), readdirSync: () => sources, _present: present };
+}
+
+t('missingDocAssets: a freshly-upgraded core (only .mmd sources, no atlas.json) reports BOTH groups missing', () => {
+  const fsImpl = docAssetFs({ atlas: false, renders: false });
+  assert.deepEqual(u.missingDocAssets('/core', fsImpl), ['atlas', 'diagrams']);
+});
+
+t('missingDocAssets: a fully-generated core reports nothing missing (steady state — no work)', () => {
+  assert.deepEqual(u.missingDocAssets('/core', docAssetFs()), []);
+});
+
+t('missingDocAssets: only atlas.json gone → only the atlas group', () => {
+  assert.deepEqual(u.missingDocAssets('/core', docAssetFs({ atlas: false })), ['atlas']);
+});
+
+t('missingDocAssets: a half-rendered diagram set (one .mmd lacking its .png) counts as missing', () => {
+  const fsImpl = docAssetFs();
+  fsImpl._present.delete(join('/core', 'docs', 'onboarding', 'diagrams', '02-b.png'));
+  assert.deepEqual(u.missingDocAssets('/core', fsImpl), ['diagrams']);
+});
+
+t('missingDocAssets: a core with NO diagram dir does not report diagrams (readdir throws → nothing to render)', () => {
+  const fsImpl = docAssetFs();
+  fsImpl.readdirSync = () => { throw new Error('ENOENT'); };
+  assert.deepEqual(u.missingDocAssets('/core', fsImpl), []);
+});
+
+t('healDocAssets: the post-upgrade case regenerates BOTH, node for the atlas and bash for the renders, cwd = coreRoot', () => {
+  const calls = [];
+  const run = (cmd, args, opts) => { calls.push({ cmd, arg0: args[0], cwd: opts && opts.cwd }); return { status: 0 }; };
+  const res = u.healDocAssets({ coreRoot: '/core' }, run, docAssetFs({ atlas: false, renders: false }));
+  assert.equal(res.ok, true);
+  assert.deepEqual(res.ran, ['atlas', 'diagrams']);
+  assert.equal(calls.length, 2);
+  assert.equal(calls[0].cmd, process.execPath, 'atlas generator runs under node');
+  assert.equal(calls[0].arg0, join('/core', 'scripts', 'gds', 'gen-atlas.js'));
+  assert.equal(calls[1].cmd, 'bash', 'the diagram renderer is a shell script');
+  assert.equal(calls[1].arg0, join('/core', 'scripts', 'render-diagrams.sh'));
+  assert.ok(calls.every((c) => c.cwd === '/core'), 'both run against the CORE root, where the assets live');
+});
+
+t('healDocAssets: nothing missing → spawns NOTHING (safe to call from a deploy loop)', () => {
+  let spawned = 0;
+  const res = u.healDocAssets({ coreRoot: '/core' }, () => { spawned++; return { status: 0 }; }, docAssetFs());
+  assert.equal(spawned, 0);
+  assert.deepEqual(res.missing, []);
+  assert.equal(res.ok, true);
+});
+
+t('healDocAssets: only the MISSING group is regenerated (atlas present → renderer only)', () => {
+  const spawned = [];
+  const run = (_c, args) => { spawned.push(args[0]); return { status: 0 }; };
+  const res = u.healDocAssets({ coreRoot: '/core' }, run, docAssetFs({ renders: false }));
+  assert.deepEqual(res.ran, ['diagrams']);
+  assert.equal(spawned.length, 1);
+  assert.match(String(spawned[0]), /render-diagrams\.sh$/);
+});
+
+t('healDocAssets: a failing renderer (no Chromium) is LOUD-failed but the atlas still heals — never aborts the bump', () => {
+  const run = (_c, args) => ({ status: String(args[0]).endsWith('render-diagrams.sh') ? 1 : 0 });
+  const res = u.healDocAssets({ coreRoot: '/core' }, run, docAssetFs({ atlas: false, renders: false }));
+  assert.equal(res.ok, false, 'reported as incomplete');
+  assert.deepEqual(res.ran, ['atlas'], 'the independent atlas still regenerated');
+  assert.equal(res.failed.length, 1);
+  assert.equal(res.failed[0].group, 'diagrams');
+  assert.match(res.failed[0].reason, /exited 1/);
+});
+
+t('healDocAssets: a generator absent from this core is recorded, not spawned', () => {
+  const fsImpl = docAssetFs({ atlas: false, renders: false });
+  fsImpl._present.delete(join('/core', 'scripts', 'render-diagrams.sh'));
+  const spawned = [];
+  const res = u.healDocAssets({ coreRoot: '/core' }, (_c, args) => { spawned.push(args[0]); return { status: 0 }; }, fsImpl);
+  assert.equal(res.ok, false);
+  assert.deepEqual(res.ran, ['atlas']);
+  assert.match(res.failed[0].reason, /not found in core/);
+  assert.equal(spawned.length, 1, 'the absent script is never spawned');
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/web_admission_status.mjs

@@ -0,0 +1,162 @@
+// tests/web_admission_status.mjs — auth.webAdmissionStatus (task 1002097).
+//
+// The stub must go into require.cache BEFORE auth.js loads: auth.js destructures
+// accessStateByLogin at require time, so patching the export object afterwards
+// would not rebind what it already captured.
+//
+// Run:  node tests/web_admission_status.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// --- stub the kernel BEFORE auth.js captures its bindings ------------------
+const kernelPath = require.resolve('../src/bongos/db-kernel.js');
+const realKernel = require(kernelPath);
+
+let dbState = { member: false, invited: false, pending: false };
+let dbThrows = false;
+
+require.cache[kernelPath].exports = {
+  ...realKernel,
+  accessStateByLogin: async () => {
+    if (dbThrows) throw new Error('simulated DB outage');
+    return dbState;
+  },
+};
+
+const auth = require('../src/bongos/auth.js');
+
+const FIRST_ADMIN = 'ownerlogin';
+// OTB is a permanent entry in LEGACY_ENV_PREFIXES, so this resolves regardless
+// of the instance's own env prefix — and regardless of whether the branding
+// pack configures a firstAdmin (this repo's does not).
+process.env.OTB_FIRST_ADMIN = FIRST_ADMIN;
+
+function setDb({ member = false, invited = false, pending = false } = {}) {
+  dbState = { member, invited, pending };
+  dbThrows = false;
+}
+
+function withOpenEnrollment(val, fn) {
+  const prev = process.env.OTB_OPEN_XENOS_ENROLLMENT;
+  if (val === undefined) delete process.env.OTB_OPEN_XENOS_ENROLLMENT;
+  else process.env.OTB_OPEN_XENOS_ENROLLMENT = val;
+  return Promise.resolve()
+    .then(fn)
+    .finally(() => {
+      if (prev === undefined) delete process.env.OTB_OPEN_XENOS_ENROLLMENT;
+      else process.env.OTB_OPEN_XENOS_ENROLLMENT = prev;
+    });
+}
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+await t('a blank or missing login is never admitted', async () => {
+  setDb({ member: true });
+  for (const bad of ['', '   ', null, undefined]) {
+    assert.deepEqual(await auth.webAdmissionStatus(bad), { admitted: false, expectedSoon: false });
+  }
+});
+
+await t('an existing builder is admitted', async () => {
+  setDb({ member: true });
+  assert.deepEqual(await auth.webAdmissionStatus('someone'), { admitted: true, expectedSoon: true });
+});
+
+await t('an invited login is admitted', async () => {
+  setDb({ invited: true });
+  assert.deepEqual(await auth.webAdmissionStatus('someone'), { admitted: true, expectedSoon: true });
+});
+
+await t('PENDING is the keep-polling case: not admitted, but expected soon', async () => {
+  // The whole point of the waiting page — an Archon is about to flip this to
+  // invited, so the visitor should wait rather than see a rejection.
+  setDb({ pending: true });
+  assert.deepEqual(await auth.webAdmissionStatus('someone'), { admitted: false, expectedSoon: true });
+});
+
+await t('a genuine stranger is neither admitted nor expected', async () => {
+  // Must be false, or the stranger gets a spinner that never resolves instead
+  // of the request-access page.
+  setDb({});
+  assert.deepEqual(await auth.webAdmissionStatus('nobody'), { admitted: false, expectedSoon: false });
+});
+
+await t('the configured firstAdmin is admitted with nothing in the DB', async () => {
+  // The bootstrap window this task was filed for: a fresh instance where the
+  // owner has no builder row and no access_request yet.
+  setDb({});
+  assert.deepEqual(await auth.webAdmissionStatus(FIRST_ADMIN), { admitted: true, expectedSoon: true });
+});
+
+await t('the firstAdmin match is case-insensitive and trims', async () => {
+  setDb({});
+  assert.equal((await auth.webAdmissionStatus('OwNerLogin')).admitted, true);
+  assert.equal((await auth.webAdmissionStatus(`  ${FIRST_ADMIN.toUpperCase()}  `)).admitted, true);
+});
+
+await t('open enrollment admits anyone', async () => {
+  setDb({});
+  await withOpenEnrollment('1', async () => {
+    assert.deepEqual(await auth.webAdmissionStatus('anyone'), { admitted: true, expectedSoon: true });
+  });
+});
+
+await t('a DB outage fails CLOSED on admitted', async () => {
+  // Never let an error read as "you're in".
+  dbThrows = true;
+  // The helper logs the outage by design; mute it so the unit gate's output
+  // stays readable (the assertions below are what prove the behaviour).
+  const realError = console.error;
+  console.error = () => {};
+  try {
+    const stranger = await auth.webAdmissionStatus('nobody');
+    assert.equal(stranger.admitted, false);
+    assert.equal(stranger.expectedSoon, false);
+    // ...but the owner may still keep polling through a transient outage, since
+    // the bootstrap window is exactly when the DB may be settling.
+    const owner = await auth.webAdmissionStatus(FIRST_ADMIN);
+    assert.equal(owner.admitted, false);
+    assert.equal(owner.expectedSoon, true);
+  } finally {
+    console.error = realError;
+    dbThrows = false;
+  }
+});
+
+await t('ANTI-DRIFT: admitted always equals the real gate\'s verdict', async () => {
+  // The probe must never disagree with firstTimeAdmissionBlocked — that is the
+  // one gate both sign-in flows call. Sweep the full input space.
+  for (const member of [false, true]) {
+    for (const invited of [false, true]) {
+      for (const openEnroll of [undefined, '1']) {
+        for (const login of ['nobody', FIRST_ADMIN]) {
+          setDb({ member, invited });
+          await withOpenEnrollment(openEnroll, async () => {
+            const probe = await auth.webAdmissionStatus(login);
+            const blocked = auth.firstTimeAdmissionBlocked({
+              existing: member ? { id: 1 } : null,
+              approved: invited,
+              login,
+            });
+            assert.equal(
+              probe.admitted, !blocked,
+              `drift: member=${member} invited=${invited} open=${openEnroll} login=${login} `
+              + `→ probe.admitted=${probe.admitted} but gate blocked=${blocked}`,
+            );
+          });
+        }
+      }
+    }
+  }
+});
+
+console.log(`\nweb admission status (task 1002097): ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/tests/write_validation_gaps.mjs

@@ -0,0 +1,110 @@
+// tests/write_validation_gaps.mjs — the three write routes the old route scanner
+// could not see (BV1.R109c, task 1002552).
+//
+// ADR 0118 / R12 requires every body-reading write route to call validateOrRespond.
+// Three routes were exempt not by decision but by accident: the route-discovery
+// regex required the method and path on the SAME line, and these three are declared
+// multi-line, so the fitness check never saw them. BV1.R109b fixed discovery and
+// recorded them in a named, non-growing WRITE_VALIDATION_BASELINE; this closes them
+// and empties that list.
+//
+// The risk being guarded here is NOT "is there a schema" (fitness asserts that) but
+// "does the schema still accept exactly what the live contract accepted". Each route
+// hand-coerced its one field, so a too-strict schema would silently break a caller.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
+
+test('the baseline is empty — the invariant is back to hard-zero', () => {
+  const fit = require(path.join(ROOT, 'scripts', 'gds', 'fitness.js'));
+  const baseline = fit.WRITE_VALIDATION_BASELINE;
+  if (baseline !== undefined) {
+    assert.equal(baseline.size, 0, `still-exempt write routes: ${[...baseline].join(', ')}`);
+  } else {
+    // Deleted outright rather than emptied — also acceptable, and the fitness
+    // check below is the real assertion either way.
+    assert.doesNotMatch(read('scripts/gds/fitness.js'), /'POST \/inbox\/:id\/ratify'/,
+      'the ratify entry must be gone from the baseline');
+  }
+});
+
+test('fitness reports ZERO unvalidated write routes', () => {
+  const fit = require(path.join(ROOT, 'scripts', 'gds', 'fitness.js'));
+  assert.equal(typeof fit.scanUnvalidatedWriteRoutes, 'function',
+    'the scanner must stay exported so this cannot silently stop being checked');
+  const unvalidated = fit.scanUnvalidatedWriteRoutes();
+  assert.deepEqual(unvalidated, [], `unvalidated write routes: ${JSON.stringify(unvalidated)}`);
+});
+
+test('each of the three routes now calls validateOrRespond', () => {
+  const inbox = read('modules/ideas/routes/inbox.js');
+  const reports = read('modules/security/routes/reports.js');
+  // ratify
+  const ratify = inbox.slice(inbox.indexOf("'/inbox/:id/ratify'"));
+  assert.match(ratify.slice(0, 900), /validateOrRespond\(req, res, \{[\s\S]*notes_md/, 'ratify must validate notes_md');
+  // confirm
+  const confirm = reports.slice(reports.indexOf("'/security/reports/:id/confirm'"));
+  assert.match(confirm.slice(0, 1200), /validateOrRespond\(req, res, \{[\s\S]*drachmae_awarded/, 'confirm must validate drachmae_awarded');
+  // link-fix
+  const linkFix = reports.slice(reports.indexOf("'/security/reports/:id/link-fix'"));
+  assert.match(linkFix.slice(0, 1200), /validateOrRespond\(req, res, \{[\s\S]*task_id/, 'link-fix must validate task_id');
+});
+
+// ---- contract preservation: the schemas must not narrow what was accepted ----
+//
+// These assert the SHAPE of each declaration, because the live coercion happens in
+// the handler and a type= on the schema would pre-empt it. A regression here means
+// a caller that worked yesterday starts getting a 400.
+
+test('drachmae_awarded stays UNTYPED — number, stringified number, "" and null all still reach the handler', () => {
+  const reports = read('modules/security/routes/reports.js');
+  const confirm = reports.slice(reports.indexOf("'/security/reports/:id/confirm'"), reports.indexOf("'/security/reports/:id/dispute'"));
+  assert.match(confirm, /drachmae_awarded:\s*\{\s*\}/,
+    'declaring a type would reject the stringified/"" forms the handler accepts and coerces');
+  // The inline check remains the thing that enforces finite/non-negative.
+  assert.match(confirm, /Number\.isFinite\(n\)/, 'the handler-side numeric check must survive');
+  assert.match(confirm, /bad_drachmae_awarded/, 'its error code must be unchanged');
+});
+
+test('task_id stays REQUIRED but untyped — the stringified form still works', () => {
+  const reports = read('modules/security/routes/reports.js');
+  const linkFix = reports.slice(reports.indexOf("'/security/reports/:id/link-fix'"));
+  assert.match(linkFix, /task_id:\s*\{\s*required:\s*true\s*\}/,
+    'same idiom as POST /tasks/:id/dependencies — required, coerced in-handler');
+  assert.match(linkFix, /Number\.isInteger\(taskId\)/, 'the handler-side integer check must survive');
+  assert.match(linkFix, /bad_task_id/, 'its error code must be unchanged');
+});
+
+test('notes_md stays OPTIONAL — a ratify with no body still works', () => {
+  const inbox = read('modules/ideas/routes/inbox.js');
+  const ratify = inbox.slice(inbox.indexOf("'/inbox/:id/ratify'"));
+  const decl = ratify.slice(0, 900);
+  assert.doesNotMatch(decl, /notes_md:\s*\{[^}]*required:\s*true/,
+    'notes_md was optional (absent => empty string) and must stay optional');
+  assert.match(ratify, /typeof req\.body\.notes_md === 'string'/,
+    'the absent-to-empty-string coercion must survive');
+});
+
+test('validation runs BEFORE the handler consumes the field', () => {
+  // A schema declared after the read would validate nothing on the path that matters.
+  for (const [file, route, field] of [
+    ['modules/ideas/routes/inbox.js', "'/inbox/:id/ratify'", 'notes_md'],
+    ['modules/security/routes/reports.js', "'/security/reports/:id/link-fix'", 'task_id'],
+  ]) {
+    const src = read(file);
+    const body = src.slice(src.indexOf(route));
+    const validateAt = body.indexOf('validateOrRespond');
+    const readAt = body.indexOf(`req.body?.${field}`) >= 0
+      ? body.indexOf(`req.body?.${field}`)
+      : body.indexOf(`req.body.${field}`);
+    assert.ok(validateAt > 0 && validateAt < readAt,
+      `${route}: validateOrRespond must precede the req.body.${field} read`);
+  }
+});