@bongos/core 1.17.0 → 1.17.2

package/tests/consumer_layout_boot.mjs

@@ -0,0 +1,302 @@
+// tests/consumer_layout_boot.mjs
+//
+// R89-prereq CI proof (task 2142): boot @bongos/core from a REAL consumer layout —
+// the packaged .tgz installed into node_modules, with the instance's OWN content
+// (config / modules / .claude) sitting at a DIFFERENT root — and prove the two-root
+// module loader (task 2133) discovers modules from BOTH roots.
+//
+// WHY THIS EXISTS. Every existing gate runs the SOURCE tree with all deps present:
+//   - tests/platform_boot.mjs imports src/platform-server.js straight from the repo;
+//   - tests/fitness_two_root.mjs diverges resolveInstanceRoot() to a temp dir but
+//     keeps cwd/core = the real repo (resolveCoreRoot() is still __dirname/..).
+// NONE installs the packaged core into a tree whose instance root is elsewhere —
+// which is exactly why the pre-2133 single-root loader gap was invisible: a
+// core-only scan boots a split instance with none of its host modules, and no test
+// ever exercised that shape. This harness closes the blind spot end to end.
+//
+// WHAT IT PROVES (the two-root checks all go RED against the pre-2133 loader):
+//   1. package  — scripts/gds/package-core.js builds an installable .tgz.
+//   2. install  — `npm install <tgz>` lands it at node_modules/@bongos/core.
+//   3. roots    — resolveCoreRoot() is UNDER node_modules/@bongos/core while
+//                 resolveInstanceRoot() is the consumer tree: two DIFFERENT dirs, so
+//                 a green result can never be a same-directory coincidence.
+//   4. boot     — `node node_modules/@bongos/core/src/platform-server.js` serves
+//                 /healthz 200 (the game-less core boots from the package).
+//   5. two-root — discoverModules() loads a module resolved from the CORE modules
+//                 dir AND the consumer-probe module resolved from the INSTANCE
+//                 modules dir, with zero errors. A single-root loader physically
+//                 cannot find consumer-probe → this IS the task-2133 done-when.
+//   6. fitness  — the packaged fitness.js discoveredModuleKeys() spans both roots.
+//   7. gen-file-map — reads the INSTANCE root (lists the consumer's .claude/skills).
+//   8. gen-repo-map — maps CORE code (scripts/gds/fitness.js) from node_modules.
+//
+// This is an INTEGRATION harness (a package build + `npm install` + a live boot), so
+// it is EXCLUDED from the DB-free unit gate (scripts/gds/run-unit-tests.js INTEGRATION
+// set) and driven by .github/workflows/consumer-layout-boot.yml. It needs NO Postgres
+// (/healthz, the loader, fitness, and the generators are all DB-free). Re-runnable:
+//   node tests/consumer_layout_boot.mjs                                  # builds a fresh core .tgz
+//   CORE_TGZ=/abs/path/bongos-core-x.y.z.tgz node tests/consumer_layout_boot.mjs   # reuse a prebuilt one
+
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import net from 'node:net';
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const NPM_BIN = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const CORE_VERSION_RANGE = '^1.0.0'; // consumer-probe's coreVersion — satisfied by any 1.x core.
+
+let passed = 0;
+let failed = 0;
+function check(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e && e.message ? e.message : e}`); }
+}
+
+// Run a node snippet in `cwd` and parse its stdout as JSON. Used to introspect the
+// INSTALLED core (its loader / fitness / generators) exactly as a consumer process
+// would resolve them — absolute paths are injected so the snippet never depends on
+// the snippet file's own location (mirrors tests/fitness_two_root.mjs).
+function runNodeJSON(snippet, cwd) {
+  const r = spawnSync(process.execPath, ['-e', snippet], { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) {
+    throw new Error(`node snippet exited ${r.status}\n--- stdout ---\n${r.stdout}\n--- stderr ---\n${r.stderr}`);
+  }
+  try { return JSON.parse(r.stdout); }
+  catch { throw new Error(`snippet stdout was not JSON:\n${r.stdout}\n--- stderr ---\n${r.stderr}`); }
+}
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+function getHealthz(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/healthz', timeout: 2000 }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => resolve({ status: res.statusCode, body }));
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+async function waitForHealthz(port, timeoutMs = 20000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await getHealthz(port);
+    if (res) return res;
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return null;
+}
+
+async function main() {
+  console.log('=== consumer-layout boot proof (task 2142): install @bongos/core, boot it, assert two-root module load ===');
+
+  const workRoot = mkdtempSync(join(tmpdir(), 'consumer-layout-'));
+  const consumer = join(workRoot, 'consumer');
+  let child = null;
+
+  try {
+    // --- 1. package -----------------------------------------------------------
+    // Build the installable core .tgz from HEAD (the committed tree — so on a PR the
+    // job packages exactly the code under review). Reuse a prebuilt one via CORE_TGZ.
+    let tgz = process.env.CORE_TGZ || '';
+    check('package: scripts/gds/package-core.js builds an installable .tgz', () => {
+      if (tgz) { assert.ok(existsSync(tgz), `CORE_TGZ does not exist: ${tgz}`); return; }
+      const outDir = join(workRoot, 'dist');
+      const r = spawnSync(process.execPath, [join(REPO_ROOT, 'scripts/gds/package-core.js'), '--out-dir', outDir],
+        { cwd: REPO_ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+      assert.equal(r.status, 0, `package-core exited ${r.status}\n${r.stderr}`);
+      const pinLine = r.stdout.trim().split('\n').filter(Boolean).pop();
+      const pin = JSON.parse(pinLine);
+      tgz = join(outDir, pin.tarball.name);
+      assert.ok(existsSync(tgz), `packaged tarball missing: ${tgz}`);
+    });
+    if (!tgz || !existsSync(tgz)) { throw new Error('cannot continue without a core tarball'); }
+
+    // --- build the consumer tree: instance content at its OWN root -------------
+    // A minimal-but-real Cloud Bongos consumer: a bongos.config.json pointing the
+    // instance root at itself, a HOST module (consumer-probe) that is NOT part of
+    // @bongos/core, and an instance-owned .claude/skills dir. The host module is the
+    // crux: it can only be discovered via resolveInstanceRoot(), so finding it proves
+    // the second root is scanned.
+    mkdirSync(consumer, { recursive: true });
+    writeFileSync(join(consumer, 'package.json'), `${JSON.stringify({
+      name: 'consumer-layout-probe',
+      version: '0.0.0',
+      private: true,
+      description: 'Ephemeral @bongos/core consumer used by the R89 two-root CI proof (task 2142).',
+      dependencies: { '@bongos/core': `file:${tgz}` },
+    }, null, 2)}\n`);
+    writeFileSync(join(consumer, 'bongos.config.json'), `${JSON.stringify({ instanceRoot: '.' }, null, 2)}\n`);
+    // A tiny instance CLAUDE.md (the charter heading keeps fitness's budget check happy
+    // if anything reads it) — makes the tree a realistic instance, not load-bearing here.
+    writeFileSync(join(consumer, 'CLAUDE.md'),
+      '# Consumer probe instance\n\n## Working with this file (content charter)\n\nEphemeral fixture for the task-2142 two-root CI proof.\n');
+    mkdirSync(join(consumer, 'config'), { recursive: true });
+    writeFileSync(join(consumer, 'config', 'branding.json'), `${JSON.stringify({
+      configDir: 'cloudbongos', envPrefix: 'CLOUDBONGOS',
+      identity: { productName: 'Consumer Probe' },
+    }, null, 2)}\n`);
+    // The host module — a valid manifest, key === dir name, coreVersion any 1.x.
+    mkdirSync(join(consumer, 'modules', 'consumer-probe'), { recursive: true });
+    writeFileSync(join(consumer, 'modules', 'consumer-probe', 'module.json'), `${JSON.stringify({
+      key: 'consumer-probe',
+      title: 'Consumer Probe',
+      description: 'A host module that ships only in the instance repo, never in @bongos/core.',
+      coreVersion: CORE_VERSION_RANGE,
+      contributes: {},
+    }, null, 2)}\n`);
+    // Instance-owned .claude/skills (gen-file-map lists the instance root's skills).
+    mkdirSync(join(consumer, '.claude', 'skills', 'consumer-probe-skill'), { recursive: true });
+    writeFileSync(join(consumer, '.claude', 'skills', 'consumer-probe-skill', 'SKILL.md'),
+      '# consumer-probe-skill\n\nInstance-owned skill fixture for the task-2142 proof.\n');
+    mkdirSync(join(consumer, '.claude', 'scheduled-tasks'), { recursive: true });
+
+    // --- 2. install -----------------------------------------------------------
+    const coreDir = join(consumer, 'node_modules', '@bongos', 'core');
+    check('install: npm install lands the core at node_modules/@bongos/core', () => {
+      const r = spawnSync(NPM_BIN, ['install', '--no-audit', '--no-fund', '--loglevel=error'],
+        { cwd: consumer, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+      assert.equal(r.status, 0, `npm install exited ${r.status}\n${r.stderr}`);
+      assert.ok(existsSync(join(coreDir, 'package.json')), 'node_modules/@bongos/core/package.json missing');
+      assert.ok(existsSync(join(coreDir, 'src', 'platform-server.js')), 'installed core has no src/platform-server.js');
+      assert.ok(existsSync(join(coreDir, 'modules')), 'installed core ships no modules/ dir');
+    });
+    if (!existsSync(coreDir)) { throw new Error('cannot continue without an installed core'); }
+
+    const A = (p) => JSON.stringify(join(coreDir, p)); // absolute path into the installed core, JSON-quoted
+
+    // --- 3. roots diverge -----------------------------------------------------
+    // The whole proof is meaningless if the two roots secretly coincide, so pin that
+    // down first: core resolves UNDER node_modules/@bongos/core, instance is the
+    // consumer tree, and they are different directories.
+    check('roots: resolveCoreRoot() (node_modules) and resolveInstanceRoot() (consumer) are distinct', () => {
+      const r = runNodeJSON(`
+        const ic = require(${A('src/instance-config.js')});
+        process.stdout.write(JSON.stringify({ core: ic.resolveCoreRoot(), inst: ic.resolveInstanceRoot() }));
+      `, consumer);
+      // Compare realpaths — the child's process.cwd() resolves symlinks (e.g. macOS
+      // /var → /private/var), so match that rather than the raw tmp path we created.
+      assert.ok(r.core.includes(join('node_modules', '@bongos', 'core')), `core root not under node_modules: ${r.core}`);
+      assert.equal(r.inst, realpathSync(consumer), `instance root should be the consumer tree, got ${r.inst}`);
+      assert.notEqual(r.core, r.inst, 'core root and instance root must be different directories');
+    });
+
+    // --- 4. boot + /healthz ---------------------------------------------------
+    const port = await freePort();
+    child = spawn(process.execPath, [join(coreDir, 'src', 'platform-server.js')], {
+      cwd: consumer,
+      env: { ...process.env, PORT: String(port), HOST: '127.0.0.1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let childErr = '';
+    child.stderr.on('data', (c) => { childErr += c; });
+    child.stdout.on('data', () => {});
+    const health = await waitForHealthz(port);
+    check('boot: node node_modules/@bongos/core/src/platform-server.js serves /healthz 200', () => {
+      assert.ok(health, `/healthz never came up on port ${port}\n--- server stderr ---\n${childErr.slice(-2000)}`);
+      assert.equal(health.status, 200, `/healthz status ${health.status}`);
+      assert.equal(health.body.trim(), 'ok', `/healthz body was "${health.body}"`);
+    });
+
+    // --- 5. two-root module load (the task-2133 done-when) --------------------
+    // The real default scan (DEFAULT_ROOTS) PLUS an explicit single-root scan that
+    // reproduces the pre-2133 loader shape — so the job doesn't just PASS today, it
+    // proves it would go RED if the loader regressed to one root ("done when: green
+    // AND would RED against the pre-B1 loader").
+    const disc = runNodeJSON(`
+      const path = require('node:path');
+      const loader = require(${A('src/module-loader/loader.js')});
+      const ic = require(${A('src/instance-config.js')});
+      const coreModulesDir = path.join(ic.resolveCoreRoot(), 'modules');
+      const instModulesDir = path.join(ic.resolveInstanceRoot(), 'modules');
+      const dflt = loader.discoverModules();                                      // real DEFAULT_ROOTS
+      const single = loader.discoverModules({ roots: [coreModulesDir] });         // pre-2133: core root only
+      const two = loader.discoverModules({ roots: [coreModulesDir, instModulesDir] });
+      const hasProbe = (r) => r.loaded.some((m) => m.key === 'consumer-probe');
+      process.stdout.write(JSON.stringify({
+        coreModulesDir, instModulesDir,
+        loaded: dflt.loaded.map((m) => ({ key: m.key, dir: m.dir })),
+        errors: dflt.errors,
+        singleRootHasProbe: hasProbe(single),
+        twoRootHasProbe: hasProbe(two),
+      }));
+    `, consumer);
+    check('two-root: discoverModules() loads modules from BOTH the core AND the instance root, zero errors', () => {
+      assert.deepEqual(disc.errors, [], `loader reported errors: ${JSON.stringify(disc.errors)}`);
+      const fromCore = disc.loaded.filter((m) => m.dir.startsWith(disc.coreModulesDir));
+      const fromInstance = disc.loaded.filter((m) => m.dir.startsWith(disc.instModulesDir));
+      assert.ok(fromCore.length > 0,
+        `no module resolved from the CORE root (${disc.coreModulesDir}) — the package shipped no modules?`);
+      const probe = fromInstance.find((m) => m.key === 'consumer-probe');
+      assert.ok(probe,
+        `consumer-probe was NOT loaded from the INSTANCE root (${disc.instModulesDir}) — a single-root (pre-2133) loader would miss it. loaded=${JSON.stringify(disc.loaded.map((m) => m.key))}`);
+    });
+    check('counterfactual: a single-root (pre-2133) scan MISSES consumer-probe — proves this job reds on regression', () => {
+      assert.equal(disc.twoRootHasProbe, true, 'two-root scan must find consumer-probe (sanity)');
+      assert.equal(disc.singleRootHasProbe, false,
+        'a core-only scan found consumer-probe — the instance module must be invisible to a single root, or this job could not RED against the pre-B1 loader');
+    });
+
+    // --- 6. fitness spans both roots -----------------------------------------
+    check('fitness: discoveredModuleKeys() unions the core + instance module roots', () => {
+      const r = runNodeJSON(`
+        const f = require(${A('scripts/gds/fitness.js')});
+        process.stdout.write(JSON.stringify({ keys: f.discoveredModuleKeys() }));
+      `, consumer);
+      assert.ok(r.keys.includes('consumer-probe'),
+        `fitness.discoveredModuleKeys() missing the instance module 'consumer-probe': ${JSON.stringify(r.keys)}`);
+      // At least one KNOWN core module must also be present (core root scanned too).
+      const coreKeys = disc.loaded.filter((m) => m.dir.startsWith(disc.coreModulesDir)).map((m) => m.key);
+      assert.ok(coreKeys.some((k) => r.keys.includes(k)),
+        `fitness keys carry no core module (expected some of ${JSON.stringify(coreKeys)}): ${JSON.stringify(r.keys)}`);
+    });
+
+    // --- 7. gen-file-map reads the INSTANCE root ------------------------------
+    check('gen-file-map: buildModel() lists the INSTANCE root .claude/skills (consumer-probe-skill)', () => {
+      const model = runNodeJSON(`
+        const g = require(${A('scripts/gds/gen-file-map.js')});
+        process.stdout.write(JSON.stringify(g.buildModel()));
+      `, consumer);
+      const skills = model.find((s) => s.id === 'skills');
+      assert.ok(skills, 'gen-file-map produced no skills section');
+      const names = skills.entries.map((e) => e.name);
+      assert.deepEqual(names, ['consumer-probe-skill'],
+        `gen-file-map read the wrong .claude/skills (expected only the consumer's): ${JSON.stringify(names)}`);
+    });
+
+    // --- 8. gen-repo-map reads the CORE root ----------------------------------
+    check('gen-repo-map: buildModel() maps CORE code (scripts/gds/fitness.js) from node_modules', () => {
+      const model = runNodeJSON(`
+        const g = require(${A('scripts/gds/gen-repo-map.js')});
+        const m = g.buildModel();
+        process.stdout.write(JSON.stringify({ files: m.files.length, hasFitness: m.byFile.some((f) => f.rel === 'scripts/gds/fitness.js') }));
+      `, consumer);
+      assert.ok(model.files > 50, `core scan found too few files (${model.files}) — core root not resolved to the package?`);
+      assert.equal(model.hasFitness, true, 'gen-repo-map did not map the core file scripts/gds/fitness.js');
+    });
+  } finally {
+    if (child && child.exitCode === null) { try { child.kill('SIGTERM'); } catch { /* already gone */ } }
+    try { rmSync(workRoot, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+
+  console.log(`\nconsumer_layout_boot: ${passed} passed, ${failed} failed`);
+  process.exit(failed ? 1 : 0);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/tests/cutover_codemod.mjs

@@ -0,0 +1,184 @@
+// tests/cutover_codemod.mjs
+//
+// R89 cutover codemod (task 2159 [F1], task 2161 [F3]): rewrite HOST files' core-internal
+// require()s to @bongos/core/* subpaths at cutover. Guards the pure transform (quote-preserving,
+// idempotent, table-driven), the host-only scope oracle, the post-split precondition, and the
+// end-to-end plan over a simulated consumer tree.
+//
+// Run:  node tests/cutover_codemod.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cm = require('../scripts/gds/cutover-codemod.js');
+const { rewriteCoreRequires, isHostFile, looksLikeConsumer, planCodemod, CORE_INTERNAL_MAP } = cm;
+
+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.stack || e.message}`); }
+}
+
+// ---- rewriteCoreRequires: the pure transform (F1 — module-api) --------------
+
+t('rewrites ../../src/module-api → @bongos/core/module-api', () => {
+  const r = rewriteCoreRequires(`const { pool } = require('../../src/module-api');`);
+  assert.equal(r.text, `const { pool } = require('@bongos/core/module-api');`);
+  assert.equal(r.changes.length, 1);
+  assert.equal(r.changes[0].key, 'module-api');
+});
+
+t('rewrites deeper ../../../src/module-api (routes depth) too', () => {
+  const r = rewriteCoreRequires(`const { registerProvider } = require('../../../src/module-api');`);
+  assert.equal(r.text, `const { registerProvider } = require('@bongos/core/module-api');`);
+});
+
+t('preserves double quotes', () => {
+  const r = rewriteCoreRequires(`const api = require("../../src/module-api");`);
+  assert.equal(r.text, `const api = require("@bongos/core/module-api");`);
+});
+
+t('is idempotent — a rewritten @bongos/core require is not matched again', () => {
+  const once = rewriteCoreRequires(`const api = require('../../src/module-api');`).text;
+  const twice = rewriteCoreRequires(once);
+  assert.equal(twice.text, once);
+  assert.equal(twice.changes.length, 0);
+});
+
+t('leaves an npm/sibling require untouched', () => {
+  const src = `const express = require('express');\nconst helper = require('./helper');\n`;
+  const r = rewriteCoreRequires(src);
+  assert.equal(r.text, src);
+  assert.equal(r.changes.length, 0);
+  assert.equal(r.unmapped.length, 0);
+});
+
+t('trailing member access is preserved (only the require() call is replaced)', () => {
+  const r = rewriteCoreRequires(`const pool = require('../../src/module-api').pool;`);
+  assert.equal(r.text, `const pool = require('@bongos/core/module-api').pool;`);
+});
+
+t('an UNMAPPED core-internal require is left unchanged AND reported', () => {
+  // A core internal NOT in the table (host code should never import it raw) — flagged, not guessed.
+  const src = `const brand = require('../../src/branding');`;
+  const r = rewriteCoreRequires(src);
+  assert.equal(r.text, src, 'must not guess a specifier for an unmapped internal');
+  assert.equal(r.changes.length, 0);
+  assert.equal(r.unmapped.length, 1);
+  assert.equal(r.unmapped[0].key, 'branding');
+});
+
+t('rewrites every mapped entry in the table', () => {
+  for (const [key, mapped] of Object.entries(CORE_INTERNAL_MAP)) {
+    const r = rewriteCoreRequires(`require('../../src/${key}')`);
+    assert.equal(r.text, `require('@bongos/core/${mapped}')`, `key ${key}`);
+  }
+});
+
+// ---- F3 (task 2161): server.js core internals --------------------------------
+
+t('F3: rewrites server.js core internals from ./src/* form', () => {
+  assert.equal(rewriteCoreRequires(`const p = require('./src/bongos/api-path-404');`).text,
+    `const p = require('@bongos/core/bongos/api-path-404');`);
+  assert.equal(rewriteCoreRequires(`const u = require('./src/bongos/uptime-poller');`).text,
+    `const u = require('@bongos/core/bongos/uptime-poller');`);
+  assert.equal(rewriteCoreRequires(`const l = require('./src/module-loader/loader');`).text,
+    `const l = require('@bongos/core/module-loader/loader');`);
+  assert.equal(rewriteCoreRequires(`const m = require('./src/modules');`).text,
+    `const m = require('@bongos/core/modules');`);
+  assert.equal(rewriteCoreRequires(`const s = require('./src/module-seams');`).text,
+    `const s = require('@bongos/core/module-seams');`);
+});
+
+t('F3: serve-internal maps to its curated export name, NOT ./bongos/serve-internal', () => {
+  // The file is src/bongos/serve-internal.js but the package exports it as ./serve-internal.
+  const r = rewriteCoreRequires(`const { mountInternalSurfaces } = require('./src/bongos/serve-internal');`);
+  assert.equal(r.text, `const { mountInternalSurfaces } = require('@bongos/core/serve-internal');`);
+});
+
+// ---- scope oracle -----------------------------------------------------------
+
+t('isHostFile is true only when isPublishable(rel) === false', () => {
+  const fakePub = (rel) => rel.startsWith('src/') || rel.startsWith('modules/lifecycle/');
+  assert.equal(isHostFile('modules/game/db.js', fakePub), true);
+  assert.equal(isHostFile('server.js', fakePub), true);
+  assert.equal(isHostFile('modules/lifecycle/db.js', fakePub), false);
+  assert.equal(isHostFile('src/module-api.js', fakePub), false);
+});
+
+// ---- precondition -----------------------------------------------------------
+
+t('looksLikeConsumer: false in the monolith (src/module-api.js present), true post-split', () => {
+  const monolith = looksLikeConsumer('/repo', { existsFn: (p) => p.endsWith('/src/module-api.js') });
+  const consumer = looksLikeConsumer('/repo', { existsFn: () => false });
+  assert.equal(monolith, false);
+  assert.equal(consumer, true);
+});
+
+// ---- planCodemod over a simulated consumer tree -----------------------------
+
+t('planCodemod rewrites host files, skips core files, reports unmapped', () => {
+  // A fake post-split consumer: host modules + server.js kept; a core module also present
+  // (as if partition had not yet run) to prove the scope oracle skips it regardless.
+  const tree = {
+    'modules/game/db.js': `const { pool } = require('../../src/module-api');`,
+    'modules/art-pipeline/routes/art-key.js': `const api = require('../../../src/module-api');`,
+    'server.js': `const seams = require('./src/module-seams');`,               // F3 — now mapped → rewritten
+    'modules/game/experimental.js': `const b = require('../../src/branding');`, // unmapped → reported, not rewritten
+    'modules/lifecycle/db.js': `const api = require('../../src/module-api');`,   // CORE — must be skipped
+    'README.md': 'not a js file',
+  };
+  const fsImpl = {
+    readdirSync: (dir, opts) => {
+      // minimal shim: list immediate children of `dir` within the flat `tree`
+      const rootPrefix = '/consumer';
+      const rel = dir === rootPrefix ? '' : dir.slice(rootPrefix.length + 1);
+      const names = new Set();
+      for (const p of Object.keys(tree)) {
+        if (rel && !p.startsWith(rel + '/')) continue;
+        const rest = rel ? p.slice(rel.length + 1) : p;
+        const seg = rest.split('/')[0];
+        const isDir = rest.includes('/');
+        names.add(seg + (isDir ? '/' : ''));
+      }
+      return [...names].map((n) => {
+        const isDir = n.endsWith('/');
+        const name = isDir ? n.slice(0, -1) : n;
+        return { name, isDirectory: () => isDir, isFile: () => !isDir };
+      });
+    },
+    readFileSync: (abs) => tree[abs.slice('/consumer/'.length)],
+  };
+  const isPub = (rel) => rel.startsWith('modules/lifecycle/') || rel.startsWith('src/');
+  // Force the filesystem-walk path (no git) so the injected fake fs is exercised.
+  const runGit = () => { throw new Error('no git in test'); };
+  const plan = planCodemod({ root: '/consumer', fsImpl, runGit, isPublishableFn: isPub });
+
+  const changed = plan.files.map((f) => f.rel).sort();
+  assert.deepEqual(changed, ['modules/art-pipeline/routes/art-key.js', 'modules/game/db.js', 'server.js']);
+  // core module skipped even though it has the same relative require
+  assert.ok(!changed.includes('modules/lifecycle/db.js'), 'core module must be skipped');
+  // a host file with an UNMAPPED core internal is reported, never rewritten
+  assert.ok(!changed.includes('modules/game/experimental.js'), 'unmapped internal must not be rewritten');
+  assert.ok(plan.unmapped.some((u) => u.rel === 'modules/game/experimental.js' && u.key === 'branding'));
+  // the rewritten text is correct for both a host module (F1) and server.js (F3)
+  const game = plan.files.find((f) => f.rel === 'modules/game/db.js');
+  assert.equal(game.newText, `const { pool } = require('@bongos/core/module-api');`);
+  const srv = plan.files.find((f) => f.rel === 'server.js');
+  assert.equal(srv.newText, `const seams = require('@bongos/core/module-seams');`);
+});
+
+// ---- invariant: every mapped target is an actual @bongos/core export ---------
+
+t('every CORE_INTERNAL_MAP target is exported by the core package (a rewrite never outruns an export)', () => {
+  const { buildPackageJson } = require('../scripts/gds/package-core.js');
+  const pkg = buildPackageJson({ version: '0.0.0-test', sourceDeps: { express: '^4.0.0', pg: '^8.0.0' } });
+  for (const mapped of Object.values(CORE_INTERNAL_MAP)) {
+    assert.ok(pkg.exports[`./${mapped}`], `@bongos/core must export ./${mapped} (targeted by the codemod)`);
+  }
+});
+
+console.log(`\ncutover_codemod: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/device_flow_start.mjs

@@ -0,0 +1,96 @@
+// tests/device_flow_start.mjs
+//
+// task 2126 (demo-audit fix C3) — startDeviceFlow() must surface a GitHub OAuth-App
+// misconfig (the HTTP-200-with-{error} body: device_flow_disabled / bad client) as an
+// ACTIONABLE thrown error, not silently drop the missing device_code into a broken flow
+// (which the route then reported as an opaque 500 — the 2026-07-08 demo login failure).
+//
+// Hermetic: stubs globalThis.fetch (no network) + sets creds env so loadGithubCreds()
+// succeeds. auth.js requires pool but never QUERIES it here (startDeviceFlow only fetches),
+// so no DB. Run:  node tests/device_flow_start.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+// Creds must resolve before startDeviceFlow runs loadGithubCreds() — set legacy + prefixed.
+for (const p of ['GDS', 'OTB', 'CLOUDBONGOS']) {
+  process.env[`${p}_GITHUB_CLIENT_ID`] = 'Iv1.testclientid00';
+  process.env[`${p}_GITHUB_CLIENT_SECRET`] = 'testsecret000000000000000000000000000000';
+}
+
+const require = createRequire(import.meta.url);
+const auth = require('../src/bongos/auth.js');
+
+let passed = 0, failed = 0;
+const realFetch = globalThis.fetch;
+function stubFetch(status, jsonBody) {
+  globalThis.fetch = async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => jsonBody,
+    text: async () => JSON.stringify(jsonBody),
+  });
+}
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+  finally { globalThis.fetch = realFetch; }
+}
+
+await t('device_flow_disabled (HTTP 200 + error body) → throws an actionable error deep-linking the GitHub-App settings (task 2129)', async () => {
+  stubFetch(200, { error: 'device_flow_disabled', error_description: 'Device Flow is not enabled for this app.' });
+  await assert.rejects(
+    () => auth.startDeviceFlow(),
+    (err) => /device_flow_disabled/.test(err.message)
+      && /device-flow start/i.test(err.message)
+      // creds client_id is Iv1.* (a GitHub App) → point at the Apps listing + the exact toggle.
+      && /github\.com\/settings\/apps/.test(err.message)
+      && /Enable Device Flow/i.test(err.message),
+  );
+});
+
+await t('device_flow_disabled on an OAuth App (Ov* client_id) → deep-links OAuth developer settings, not /settings/apps (task 2129)', async () => {
+  const saved = {};
+  for (const p of ['GDS', 'OTB', 'CLOUDBONGOS']) {
+    saved[p] = process.env[`${p}_GITHUB_CLIENT_ID`];
+    process.env[`${p}_GITHUB_CLIENT_ID`] = 'Ov23liOAuthClientId0';
+  }
+  try {
+    stubFetch(200, { error: 'device_flow_disabled', error_description: 'Device Flow is not enabled for this app.' });
+    await assert.rejects(
+      () => auth.startDeviceFlow(),
+      (err) => /github\.com\/settings\/developers/.test(err.message)
+        && !/settings\/apps/.test(err.message)
+        && /Enable Device Flow/i.test(err.message),
+    );
+  } finally {
+    for (const p of ['GDS', 'OTB', 'CLOUDBONGOS']) process.env[`${p}_GITHUB_CLIENT_ID`] = saved[p];
+  }
+});
+
+await t('incorrect_client_credentials (HTTP 200 + error) → throws, names the error', async () => {
+  stubFetch(200, { error: 'incorrect_client_credentials', error_description: 'The client_id is not valid.' });
+  await assert.rejects(() => auth.startDeviceFlow(), (err) => /incorrect_client_credentials/.test(err.message));
+});
+
+await t('happy path (valid device/code body) → returns the flow fields', async () => {
+  stubFetch(200, { device_code: 'dc_abc', user_code: 'WXYZ-1234', verification_uri: 'https://github.com/login/device', expires_in: 900, interval: 5 });
+  const out = await auth.startDeviceFlow();
+  assert.equal(out.device_code, 'dc_abc');
+  assert.equal(out.user_code, 'WXYZ-1234');
+  assert.equal(out.verification_uri, 'https://github.com/login/device');
+  assert.equal(out.interval, 5);
+});
+
+await t('malformed 200 (no device_code, no error) → throws rather than a broken flow', async () => {
+  stubFetch(200, {});
+  await assert.rejects(() => auth.startDeviceFlow(), (err) => /device_code/.test(err.message));
+});
+
+await t('non-2xx from GitHub still throws (pre-existing guard preserved)', async () => {
+  stubFetch(404, { message: 'Not Found' });
+  await assert.rejects(() => auth.startDeviceFlow(), (err) => /device\/code failed \(404\)/.test(err.message));
+});
+
+console.log(`\ndevice-flow start (task 2126) tests: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);