@bongos/core 1.17.0 → 1.17.2

package/scripts/gds/cutover-codemod.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+'use strict';
+// cutover-codemod.js — rewrite HOST files' core-internal require()s to the @bongos/core
+// package subpaths at cutover (R89 / task 2159 [F1], task 2161 [F3]).
+//
+// WHY. Post-split (task 1728) a host file lives at `<instance>/…` with NO co-located `src/`.
+// Its relative core require()s — `require('../../src/module-api')` (host modules, F1),
+// `require('./src/bongos/…')` (the game entrypoint server.js, F3) — point at the DELETED
+// instance `src/` → boot crash (the 2026-07-10 rehearsal, findings F1+F3:
+// docs/reviews/2026-07-10-amazonprimea-decouple-r89-rehearsal.md). Core modules are UNAFFECTED:
+// they ship INSIDE @bongos/core, where `src/` sits next to `modules/`, so their identical
+// relative requires still resolve. The fix is to rewrite the host files' core requires to the
+// package's EXPORTED subpaths (`@bongos/core/module-api`, `@bongos/core/serve-internal`, …).
+//
+// WHY A CUTOVER TRANSFORM, NOT AN IN-PLACE MONOLITH EDIT. In the monolith `@bongos/core` is not
+// a dependency (the specifier resolves nowhere) and fitness's "modules import only
+// src/module-api.js" check would fail the rewritten form. So this must run AT CUTOVER on the
+// partitioned consumer tree — never on the committed monolith source. Mirrors the `.claude/hooks`
+// `_core-resolve.js` step (task 2139); `claude-materialize.js` rewrites `.claude/`, this rewrites
+// host-module + server.js source — the gap that rehearsal F1/F3 named.
+//
+// TWO GUARDS make it structurally impossible to corrupt the monolith:
+//   1. SCOPE ORACLE = publish-manifest. A file is rewritten only when `isPublishable(rel) === false`
+//      (host: game / art-pipeline / character-anim / demo + server.js). Core files (publishable)
+//      ship with the package and are left untouched — reusing the exact partition logic as the
+//      core-vs-host oracle, so this can never drift from what the cutover actually deletes/keeps.
+//   2. PRECONDITION = post-split consumer. Refuse unless the instance core doorway is gone
+//      (`src/module-api.js` absent at the root) — the definitive signal core was partitioned out.
+//      In the monolith that file exists, so the codemod refuses. `--force` overrides for a
+//      read-only preview only.
+//
+// The rewrite is TABLE-DRIVEN (CORE_INTERNAL_MAP), not a blind `src/X → @bongos/core/X` path swap,
+// because the core's export names do not all mirror the src layout: `src/bongos/serve-internal.js`
+// is exported as `./serve-internal`, not `./bongos/serve-internal`. The table encodes each mapping
+// so a rewrite can never produce a specifier the package doesn't export. Idempotent (a rewritten
+// `@bongos/core/*` require no longer matches the relative-into-src pattern) and quote-preserving.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { isPublishable } = require('./publish-manifest');
+
+const CORE_PKG = '@bongos/core';
+
+// <subpath after `src/` in the relative require> → <the @bongos/core export subpath>.
+// The core exports map (scripts/gds/package-core.js buildPackageJson) MUST export every value
+// here, or the rewritten require won't resolve. Kept deliberately small + explicit.
+//   F1 (task 2159): the host-module doorway.
+//   F3 (task 2161): the six core internals the game entrypoint server.js wires — added there,
+//     in lockstep with widening the core exports map, so a rewrite never outruns an export.
+const CORE_INTERNAL_MAP = {
+  // F1 — every host module imports the core doorway; the ONLY core import a module is allowed.
+  'module-api': 'module-api',
+  // F3 (task 2161) — the six core internals the game entrypoint server.js wires. Each LHS is the
+  // subpath after `src/` in server.js's relative require; each RHS is the core's EXPORTED subpath
+  // (widened in package-core.js buildPackageJson in lockstep). Note the divergence: the file at
+  // `src/bongos/serve-internal.js` is exported as `./serve-internal` (a curated name), NOT
+  // `./bongos/serve-internal` — this table encodes that so the rewrite can't emit an unexported
+  // specifier. The other five mirror their src/ path.
+  'bongos/api-path-404': 'bongos/api-path-404',
+  'bongos/uptime-poller': 'bongos/uptime-poller',
+  'bongos/serve-internal': 'serve-internal',
+  'module-loader/loader': 'module-loader/loader',
+  'modules': 'modules',
+  'module-seams': 'module-seams',
+};
+
+// require('<./ or ../…>src/<key>')  — a RELATIVE require that reaches into a `src/` dir.
+// Group 1 = quote (preserved), group 2 = the `./`/`../…` prefix, group 3 = the key after `src/`.
+// An already-rewritten `require('@bongos/core/…')` has no `../src/` and never matches → idempotent.
+const REQUIRE_RE = /require\((['"])((?:\.\.?\/)+)src\/([^'"]+)\1\)/g;
+
+// Pure. Rewrite the core-internal require()s in one file's text per `map`.
+// Returns { text, changes:[{from,to,key}], unmapped:[{key,spec}] }.
+//   - changes: requires rewritten to `@bongos/core/<mapped>`.
+//   - unmapped: relative-into-`src/` requires whose key is NOT in the table — left UNCHANGED and
+//     surfaced so a new core internal a host file starts depending on can't be silently missed
+//     (it would still crash at boot; the codemod flags "add an export + a table entry").
+function rewriteCoreRequires(text, map = CORE_INTERNAL_MAP) {
+  const changes = [];
+  const unmapped = [];
+  const out = String(text == null ? '' : text).replace(REQUIRE_RE, (whole, q, _prefix, key) => {
+    const mapped = Object.prototype.hasOwnProperty.call(map, key) ? map[key] : null;
+    if (mapped == null) {
+      unmapped.push({ key, spec: whole });
+      return whole; // leave unknown core internals untouched — never guess a specifier
+    }
+    const to = `require(${q}${CORE_PKG}/${mapped}${q})`;
+    changes.push({ from: whole, to, key });
+    return to;
+  });
+  return { text: out, changes, unmapped };
+}
+
+// A file is in scope iff the partition classifies it HOST (not shipped in the core package).
+function isHostFile(rel, isPublishableFn = isPublishable) {
+  return isPublishableFn(rel) === false;
+}
+
+// Post-split consumer signal: the instance's own core doorway is gone. In the monolith
+// `src/module-api.js` exists, so this is false and the CLI refuses (protecting the monolith).
+function looksLikeConsumer(root, { existsFn = fs.existsSync } = {}) {
+  return !existsFn(path.join(root, 'src', 'module-api.js'));
+}
+
+// Skip vendored deps, VCS metadata, the `.claude/` topology surface (materialize's job), and
+// build output. `dist/` in particular holds an extracted @bongos/core tarball whose bundled
+// core modules carry the SAME `../../src/module-api` requires — scanning it would be noise
+// (it's gitignored throwaway, never part of the consumer).
+const SKIP_DIRS = new Set(['node_modules', '.git', '.claude', 'dist', 'coverage']);
+
+// Preferred source scope: git-TRACKED *.js files. A consumer tree is a git repo at cutover, and
+// tracking is the honest "source" oracle — it excludes every gitignored build artifact (dist/,
+// coverage/, …) without enumerating them. Returns repo-relative POSIX paths, or null when git is
+// unavailable / this isn't a repo (→ caller falls back to the filesystem walk).
+function gitTrackedJsFiles(root, { runGit } = {}) {
+  const run = runGit || ((args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }));
+  let out;
+  try { out = run(['ls-files', '-z', '*.js']); } catch { return null; }
+  if (typeof out !== 'string') return null;
+  return out.split('\0').filter(Boolean).map((p) => p.split(path.sep).join('/')).sort();
+}
+
+// Recursively collect *.js files under `root`, skipping SKIP_DIRS. Returns repo-relative POSIX
+// paths (what isPublishable expects). The fallback when git tracking is unavailable.
+function collectJsFiles(root, { fsImpl = fs } = {}) {
+  const found = [];
+  const walk = (absDir) => {
+    let entries;
+    try { entries = fsImpl.readdirSync(absDir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        walk(path.join(absDir, ent.name));
+      } else if (ent.isFile() && ent.name.endsWith('.js')) {
+        found.push(path.relative(root, path.join(absDir, ent.name)).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+
+function underSkipDir(rel) {
+  return SKIP_DIRS.has(rel.split('/')[0]);
+}
+
+// The candidate *.js set to consider: git-tracked source when available, else the filesystem walk.
+// SKIP_DIRS is enforced on BOTH paths — git ls-files does not know about it, and `.claude/` in
+// particular is materialize's + _core-resolve.js's domain (task 2139), never the codemod's.
+function candidateJsFiles(root, { fsImpl = fs, runGit } = {}) {
+  const tracked = gitTrackedJsFiles(root, { runGit });
+  const list = tracked && tracked.length ? tracked : collectJsFiles(root, { fsImpl });
+  return list.filter((rel) => !underSkipDir(rel));
+}
+
+// Plan the codemod over a consumer `root`: which host files change, and any unmapped core requires.
+// Pure-ish (reads disk via injectable deps for tests). Does NOT write.
+function planCodemod({ root, fsImpl = fs, runGit, isPublishableFn = isPublishable, map = CORE_INTERNAL_MAP } = {}) {
+  const files = [];
+  const unmapped = [];
+  for (const rel of candidateJsFiles(root, { fsImpl, runGit })) {
+    if (!isHostFile(rel, isPublishableFn)) continue; // core file → ships with the package, leave it
+    let raw;
+    try { raw = fsImpl.readFileSync(path.join(root, rel), 'utf8'); } catch { continue; }
+    const res = rewriteCoreRequires(raw, map);
+    if (res.unmapped.length) for (const u of res.unmapped) unmapped.push({ rel, ...u });
+    if (res.changes.length) files.push({ rel, changes: res.changes, newText: res.text });
+  }
+  return { files, unmapped };
+}
+
+// ---- CLI -------------------------------------------------------------------
+function parseArgs(argv) {
+  const a = { root: process.cwd(), apply: false, force: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') a.root = argv[++i];
+    else if (argv[i] === '--apply') a.apply = true;
+    else if (argv[i] === '--force') a.force = true;
+  }
+  return a;
+}
+
+function main(argv = process.argv.slice(2), { log = console.log, err = console.error } = {}) {
+  const args = parseArgs(argv);
+  const root = path.resolve(args.root);
+
+  if (!looksLikeConsumer(root) && !args.force) {
+    err(`[cutover-codemod] REFUSING: ${path.join(root, 'src/module-api.js')} still exists — this looks like the monolith,`);
+    err('  not a post-split consumer. This codemod is a CUTOVER transform and must not edit the monolith');
+    err('  (there @bongos/core is not a dep and fitness would reject the rewrite). Run it after the partition,');
+    err('  or pass --force for a read-only preview only.');
+    return 2;
+  }
+
+  const plan = planCodemod({ root });
+
+  for (const u of plan.unmapped) {
+    err(`[cutover-codemod] WARNING ${u.rel}: unmapped core-internal require ${u.spec} — add a CORE_INTERNAL_MAP`);
+    err(`  entry + a matching core export before cutover, or this require will crash at boot.`);
+  }
+
+  if (!plan.files.length) {
+    log('[cutover-codemod] no host files need rewriting (already converted, or none present).');
+    return 0;
+  }
+
+  const verb = args.apply ? 'rewrote' : 'would rewrite';
+  for (const f of plan.files) {
+    log(`[cutover-codemod] ${verb} ${f.rel} (${f.changes.length} require${f.changes.length === 1 ? '' : 's'}):`);
+    for (const c of f.changes) log(`    ${c.from}  →  ${c.to}`);
+    if (args.apply) fs.writeFileSync(path.join(root, f.rel), f.newText);
+  }
+
+  const total = plan.files.reduce((n, f) => n + f.changes.length, 0);
+  if (args.apply) {
+    log(`[cutover-codemod] ✓ rewrote ${total} require(s) across ${plan.files.length} host file(s).`);
+  } else {
+    log(`[cutover-codemod] dry-run: ${total} require(s) across ${plan.files.length} host file(s). Re-run with --apply to write.`);
+  }
+  return 0;
+}
+
+module.exports = {
+  CORE_PKG,
+  CORE_INTERNAL_MAP,
+  REQUIRE_RE,
+  rewriteCoreRequires,
+  isHostFile,
+  looksLikeConsumer,
+  gitTrackedJsFiles,
+  collectJsFiles,
+  candidateJsFiles,
+  planCodemod,
+  parseArgs,
+  main,
+};
+
+if (require.main === module) {
+  process.exit(main());
+}

package/scripts/gds/fitness.js

@@ -1170,6 +1170,59 @@ function checkCoreRequiresExcludedConfig() {
   };
 }
 
+// ============================================================================
+// Check 16b — core code must not require an instance-EXCLUDED module (task 2135)
+// ============================================================================
+//
+// Sibling of Check 16 for the code→MODULE class. A publishable core file that
+// require()s a boundary-EXCLUDED module (modules/game, modules/art-pipeline,
+// modules/character-anim, …) throws MODULE_NOT_FOUND once that module lives in the
+// consumer's instance repo rather than the core package (R89 split). The cure is
+// either to reclassify the module INTO core (if it belongs there — e.g. provisioning,
+// sibling of dev-box) or to exclude the requiring file with the feature it serves
+// (art tooling). Catches BOTH require forms: a direct literal
+// require('../modules/<key>/…') AND a require(path.join(<root>, 'modules/<key>/…')).
+// Only an EXCLUDED module required from a PUBLISHABLE file is a violation; requiring a
+// publishable (core) module is fine, and the loader's DYNAMIC dispatch
+// (path.join(dir,'routes',rk) — no literal modules/<key>/ string) is invisible here.
+const MODULE_PATH_IN_STRING_RE = /['"](?:[^'"]*\/)?modules\/([a-z0-9][a-z0-9-]*)\/[^'"]*['"]/g;
+
+function checkCoreRequiresExcludedModule() {
+  const { isPublishable } = require('./publish-manifest');
+  const violations = [];
+  const seen = new Set();
+  const allAbs = [
+    ...['src', 'scripts'].flatMap((d) => walkJs(path.join(CORE_ROOT, d))),
+    ...walkJsAllRoots('modules'),
+  ];
+  for (const abs of allAbs) {
+    const relFile = rel(abs);
+    if (seen.has(relFile)) continue;
+    seen.add(relFile);
+    if (!isPublishable(relFile)) continue; // only CORE (publishable) code can crash a vanilla boot
+    for (const raw of fs.readFileSync(abs, 'utf8').split('\n')) {
+      const trimmed = raw.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+      if (!/require\s*\(/.test(raw)) continue; // only lines that actually require()
+      let m;
+      MODULE_PATH_IN_STRING_RE.lastIndex = 0;
+      while ((m = MODULE_PATH_IN_STRING_RE.exec(raw))) {
+        const key = m[1];
+        if (isPublishable(`modules/${key}/module.json`)) continue; // requiring a CORE module is fine
+        violations.push(`${relFile} → require(...'modules/${key}/…') pulls in an instance-EXCLUDED module — reclassify it into core (if it belongs there) or exclude ${relFile} with the feature it serves, so a fresh core boots (task 2135).`);
+      }
+    }
+  }
+  return {
+    name: 'core never requires an excluded module (task 2135)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: "a publishable src/·scripts/·modules/ .js must not require('…modules/<key>/…') when that module is boundary-excluded — MODULE_NOT_FOUND post-split (R89).",
+  };
+}
+
 // ============================================================================
 // Check 17 — no route hand-rolls a FLAT error (BV1 R03 / task 1990 / ADR 0116)
 // ============================================================================
@@ -1360,6 +1413,7 @@ const CHECKS = [
   checkKernelPromptsNoHardcodedIdentity, // BV1.R76 — kernel prompts read identity from branding()
   checkHallSectionRegistry,
   checkCoreRequiresExcludedConfig, // task 1824 — core→instance-config require guard
+  checkCoreRequiresExcludedModule, // Check 16b — task 2135: core→excluded-module require guard (R89 split)
   checkErrorEnvelope, // Check 17 — BV1 R03 / task 1990: no route hand-rolls a flat error (ADR 0116)
   checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
 ];

package/scripts/gds/gen-api-client.js

@@ -10,7 +10,7 @@
 //
 // Design (mirrors gen-api-docs.js / ADR 0063): deterministic (stable sort, no
 // clock), zero runtime deps, --check gate. The client itself has ZERO deps — it
-// uses the platform `fetch` (Node 18+ / browsers), so `npm i @cloudbongos/client`
+// uses the platform `fetch` (Node 18+ / browsers), so `npm i @bongos/client`
 // pulls nothing transitive.
 //
 // Usage:
@@ -92,7 +92,7 @@ function renderClientJs(spec, ops) {
   const groups = groupByTag(ops);
   const defaultBase = (spec.servers && spec.servers[0] && spec.servers[0].url) || '/api/bongos/v1';
   const L = [];
-  L.push(`// @cloudbongos/client — GENERATED from the OpenAPI spec by`);
+  L.push(`// @bongos/client — GENERATED from the OpenAPI spec by`);
   L.push(`// scripts/gds/gen-api-client.js (task 1995 / ADR 0118). DO NOT EDIT BY HAND —`);
   L.push(`// regenerate on spec change. Zero deps; uses the platform fetch.`);
   L.push(`'use strict';`);
@@ -210,7 +210,7 @@ function stripEsmExports(esm) {
 // app, which is a zero-dep CJS subproject and vendors this file at package time).
 function renderClientCjs(esm) {
   const header =
-    '// @cloudbongos/client (CommonJS build) — GENERATED from index.mjs by\n' +
+    '// @bongos/client (CommonJS build) — GENERATED from index.mjs by\n' +
     '// scripts/gds/gen-api-client.js. DO NOT EDIT BY HAND. Same behavior as the ESM\n' +
     '// build; only the module bindings differ. For require()-based consumers.\n';
   const body = stripEsmExports(esm)
@@ -232,7 +232,7 @@ function renderClientBrowserGlobal(esm) {
     .replace(/^'use strict';\n/m, '')
     .replace(/^\/\/ @cloudbongos\/client — GENERATED[^\n]*\n(?:\/\/[^\n]*\n)*/m, '');
   return (
-    '// @cloudbongos/client (browser-global build) — GENERATED from index.mjs by\n' +
+    '// @bongos/client (browser-global build) — GENERATED from index.mjs by\n' +
     '// scripts/gds/gen-api-client.js. DO NOT EDIT BY HAND. Exposes window.BongosClient\n' +
     '// for classic <script> pages. Same behavior as the ESM build.\n' +
     '(function (global) {\n' +
@@ -316,7 +316,7 @@ function methodSignature(op) {
 function renderTypes(spec, ops) {
   const groups = groupByTag(ops);
   const L = [];
-  L.push(`// GENERATED — TypeScript types for @cloudbongos/client (task 1995; field-level`);
+  L.push(`// GENERATED — TypeScript types for @bongos/client (task 1995; field-level`);
   L.push(`// request typing added in task 2050 / ADR 0118). DO NOT EDIT BY HAND.`);
   L.push(`export declare const API_VERSION: string;`);
   L.push(`export declare const DEFAULT_BASE_URL: string;`);
@@ -352,7 +352,7 @@ function renderTypes(spec, ops) {
 
 function renderPackageJson(spec) {
   return JSON.stringify({
-    name: '@cloudbongos/client',
+    name: '@bongos/client',
     version: spec.info && spec.info.version ? spec.info.version : '0.0.0',
     description: 'Generated typed client for the Bongos API (ADR 0118). Do not edit by hand.',
     type: 'module',
@@ -374,7 +374,7 @@ function renderPackageJson(spec) {
     license: 'AGPL-3.0-or-later',
     // Pre-launch: publish PRIVATE (task 2089 / ADR 0134). Scoped + access:"restricted"
     // = only paid-org members can install. Flip to "public" (or `npm access public
-    // @cloudbongos/client`) at launch, alongside the core.
+    // @bongos/client`) at launch, alongside the core.
     publishConfig: { access: 'restricted' },
     sideEffects: false,
   }, null, 2) + '\n';
@@ -418,7 +418,7 @@ function exampleLines(ops) {
 function renderReadme(spec, ops) {
   const base = (spec.servers && spec.servers[0] && spec.servers[0].url) || '/api/bongos/v1';
   return [
-    `# @cloudbongos/client`,
+    `# @bongos/client`,
     ``,
     `A **generated**, zero-dependency typed client for the Bongos API — produced from`,
     `\`docs/api/openapi.json\` by \`scripts/gds/gen-api-client.js\` (ADR 0118). Do not edit`,
@@ -430,13 +430,13 @@ function renderReadme(spec, ops) {
     `## Install`,
     ``,
     '```bash',
-    `npm install @cloudbongos/client   # internal registry / workspace path`,
+    `npm install @bongos/client   # internal registry / workspace path`,
     '```',
     ``,
     `## Use`,
     ``,
     '```js',
-    `import { createClient, ApiError } from '@cloudbongos/client';`,
+    `import { createClient, ApiError } from '@bongos/client';`,
     ``,
     `const api = createClient({`,
     `  baseUrl: 'https://amazonprimea.com${base}', // or omit for same-origin (browser)`,

package/scripts/gds/init.js

@@ -37,7 +37,7 @@
 // it refuses where config/branding.json exists, and --force OVERWRITES. `--adopt` is
 // the opposite: it LAYERS Cloud Bongos onto an EXISTING repo (app code, git history,
 // a package.json). It writes the lean config only where absent, adds the pinned
-// @cloudbongos/core dependency to the owner's package.json without touching any other
+// @bongos/core dependency to the owner's package.json without touching any other
 // field, and materializes .claude/ ADDITIVELY — for any pre-existing file it
 // MERGES-or-LEAVES-AND-REPORTS, it NEVER overwrites, and it does not reuse the --force
 // path. It deliberately does NOT seed a synthetic "V1 — Prove the loop": capturing the
@@ -56,11 +56,17 @@
 //   bongos init --dir <path>          target dir for the config files (default: cwd)
 //   bongos init --no-seed             write config only; skip the version/task seeding
 //   bongos init --force               overwrite existing config files (greenfield only; ignored by --adopt)
-//   bongos init --vendor-core <tgz>   greenfield only: vendor the @cloudbongos/core .tgz + pin
+//   bongos init --vendor-core <tgz>   greenfield only: vendor the @bongos/core .tgz + pin
 //                                       package.json to file:vendor/… + generate package-lock.json,
 //                                       so the scaffold is `npm ci`-installable (ADR 0108 gap 1/4).
-//                                       Without it the scaffold pins the caret range (unresolvable
-//                                       on npm today) — a local/dev scaffold you resolve another way.
+//                                       Without it the scaffold pins the caret range (which now
+//                                       resolves from the PRIVATE registry — see --registry-core).
+//   bongos init --registry-core       greenfield only: keep the caret pin + write an env-fed
+//                                       .npmrc (`_authToken=${NPM_TOKEN}`) so `npm ci` pulls the
+//                                       PRIVATE @bongos/core from the npm registry (ADR 0134).
+//                                       With NPM_TOKEN set it also generates package-lock.json;
+//                                       without a token it 404s (the expected tokenless outcome).
+//                                       Mutually exclusive with --vendor-core (registry vs tarball).
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -72,6 +78,7 @@ const { materializeClaude } = require('./claude-materialize'); // ADR 0108 §3 (
 const { detectStack, formatStackSummary } = require('./adopt-detect'); // ADR 0121 §Decision 4 (task 2043): inspect an existing repo before layering
 const { resolveBacklogTasks, DEFAULT_MAX: BACKLOG_MAX } = require('./adopt-import'); // ADR 0121 §Decision 3 (task 2044): import an existing backlog
 const { preflightAdopt, formatPreflight } = require('./adopt-preflight'); // ADR 0121 §Decision 5 (task 2045): the accept-gated conflict pre-flight
+const { writeNpmrc, hasNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the registry-install path's env-fed .npmrc
 
 const KNOWN_MODULES = ['game', 'art-pipeline', 'discord', 'dev-box'];
 
@@ -87,7 +94,7 @@ const HOSTING_SHAPES = ['co-tenant', 'dedicated', 'standalone'];
 // `bongos init --adopt` LAYERS this onto an existing repo's package.json; `bongos
 // upgrade` later re-pins it to a vendored `file:` tarball. Named so the adopt
 // layering and the upgrade re-pin agree on the dependency name.
-const CORE_PKG = '@cloudbongos/core';
+const CORE_PKG = '@bongos/core';
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
 
@@ -114,19 +121,25 @@ function coreVersionSafe() {
 // (`bash <core>/scripts/migrate.sh`). Keeping them identical means `npm start` /
 // `npm run migrate` on the instance behave like production, and `bongos upgrade`'s
 // `npm run migrate` step resolves to the core's migrate.sh (ADR 0108).
-const INSTANCE_CORE_PKG_DIR = 'node_modules/@cloudbongos/core';
+const INSTANCE_CORE_PKG_DIR = 'node_modules/@bongos/core';
 const INSTANCE_START_SCRIPT = `node ${INSTANCE_CORE_PKG_DIR}/src/platform-server.js`;
 const INSTANCE_MIGRATE_SCRIPT = `bash ${INSTANCE_CORE_PKG_DIR}/scripts/migrate.sh`;
 
 // PURE (exported for tests) — build/augment the greenfield instance package.json so a
 // fresh instance is `npm ci`-installable and runnable (ADR 0108 greenfield gap 1/4,
-// task 2053): the @cloudbongos/core dependency (the `file:` tarball pin when a tarball is
+// task 2053): the @bongos/core dependency (the `file:` tarball pin when a tarball is
 // vendored, else the declared caret range — the CARET RESOLVES NOWHERE on npm, which is
 // exactly why the vendored path pins `file:`) plus the start/migrate npm scripts a
 // standalone instance runs. Preserves any pre-existing fields + scripts (fills only what
 // is missing); greenfield OWNS the core dep, so it is always (re)set to `coreDep`. Never
 // spawns npm — generating the lockfile is a separate imperative step in main().
-function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', coreDep } = {}) {
+// `moduleDeps` (ADR 0138 / task 2160): the merged external npm deps of the modules this
+// instance ENABLES. @bongos/core ships lean (express+pg, ADR 0108), so a bundled module that
+// needs more (e.g. discord → discord.js) declares it in its module.json `dependencies`, and the
+// consumer's package.json must carry it or boot crashes on the missing module (rehearsal F2).
+// Precedence: module deps FILL gaps, an explicit pre-existing pin WINS over them, @bongos/core
+// is always (re)set. With no moduleDeps this is byte-identical to before.
+function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', coreDep, moduleDeps } = {}) {
   const dep = coreDep || coreDepRange();
   const pkg = isObj(existing) ? { ...existing } : {};
   if (!pkg.name) pkg.name = name;
@@ -134,10 +147,37 @@ function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', cor
   pkg.scripts = { ...(isObj(pkg.scripts) ? pkg.scripts : {}) };
   if (!pkg.scripts.start) pkg.scripts.start = INSTANCE_START_SCRIPT;
   if (!pkg.scripts.migrate) pkg.scripts.migrate = INSTANCE_MIGRATE_SCRIPT;
-  pkg.dependencies = { ...(isObj(pkg.dependencies) ? pkg.dependencies : {}), [CORE_PKG]: dep };
+  pkg.dependencies = {
+    ...(isObj(moduleDeps) ? moduleDeps : {}),
+    ...(isObj(pkg.dependencies) ? pkg.dependencies : {}),
+    [CORE_PKG]: dep,
+  };
   return pkg;
 }
 
+// The external npm deps a single module declares in its module.json `dependencies` (ADR 0138).
+// I/O (reads the core-package module manifest); fail-soft → {} when absent/unreadable.
+function moduleDeclaredDeps(moduleKey, { coreRoot = resolveCoreRoot(), fsImpl = fs } = {}) {
+  try {
+    const mj = JSON.parse(fsImpl.readFileSync(path.join(coreRoot, 'modules', moduleKey, 'module.json'), 'utf8'));
+    return isObj(mj.dependencies) ? mj.dependencies : {};
+  } catch {
+    return {};
+  }
+}
+
+// Merge the declared deps of every ENABLED module (modulesConfig = { modules: { key: bool } })
+// into one object. PURE — `readDeps(key)` is injected (defaults to moduleDeclaredDeps) so this is
+// testable with no disk. A later-enabled module's range wins on a key collision (rare).
+function enabledModuleDeps(modulesConfig, { readDeps = (k) => moduleDeclaredDeps(k) } = {}) {
+  const enabled = isObj(modulesConfig) && isObj(modulesConfig.modules) ? modulesConfig.modules : {};
+  const out = {};
+  for (const [key, on] of Object.entries(enabled)) {
+    if (on === true) Object.assign(out, readDeps(key));
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Pure builders (exported for tests — no I/O, no network)
 // ---------------------------------------------------------------------------
@@ -258,7 +298,7 @@ function buildHierarchyConfig(spec) {
 }
 
 // PURE — layer the pinned core dependency into a parsed package.json (ADR 0121
-// §Decision 2 / task 2042). NEVER clobbers: if `@cloudbongos/core` is already a dep
+// §Decision 2 / task 2042). NEVER clobbers: if `@bongos/core` is already a dep
 // (in dependencies OR devDependencies) it returns the object untouched with
 // action:'present'; if there is no package.json at all it MINTS a minimal one
 // (action:'created'); otherwise it ADDS the dep, preserving every existing field and
@@ -466,7 +506,7 @@ async function interview({ adopt = false } = {}) {
     let provisioning;
     const wantProv = (await ask(rl, '  Provision production hosting now? (y/N)', 'N')).toLowerCase();
     if (wantProv === 'y' || wantProv === 'yes') {
-      const shape = (await ask(rl, '  Hosting shape? (co-tenant = share an existing box, $0 / dedicated = its own droplet / standalone = its own repo + pinned @cloudbongos/core, ADR 0108)', 'co-tenant')).toLowerCase();
+      const shape = (await ask(rl, '  Hosting shape? (co-tenant = share an existing box, $0 / dedicated = its own droplet / standalone = its own repo + pinned @bongos/core, ADR 0108)', 'co-tenant')).toLowerCase();
       const domain = await ask(rl, '  Domain you own — bring-your-own (blank = none yet)?');
       const targetRef = await ask(rl, '  Target credential ref? (which control-plane creds the runner should use; optional)');
       let tier = '';
@@ -518,7 +558,11 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
   const pkgName = slugify((spec.identity && spec.identity.productName) || '', 'cloudbongos-instance');
   let existingPkg = null;
   if (fs.existsSync(pkgPath)) { try { existingPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { existingPkg = null; } }
-  const pkg = buildInstancePackageJson(existingPkg, { name: pkgName, coreDep });
+  // Compose the deps of the ENABLED modules (ADR 0138 / task 2160) so an instance that turns a
+  // bundled module on gets that module's npm deps (e.g. discord → discord.js) in its package.json,
+  // rather than crashing at boot on a dep @bongos/core deliberately doesn't carry (rehearsal F2).
+  const moduleDeps = enabledModuleDeps(modules);
+  const pkg = buildInstancePackageJson(existingPkg, { name: pkgName, coreDep, moduleDeps });
   const pinNote = pkg.dependencies[CORE_PKG];
 
   if (dryRun) {
@@ -579,7 +623,7 @@ function layerConfigs(spec, { dir, dryRun, log = console.log }) {
 }
 
 // `--adopt` package.json layering (ADR 0121 §Decision 2 / task 2042): add the
-// pinned @cloudbongos/core dependency to the owner's EXISTING package.json without
+// pinned @bongos/core dependency to the owner's EXISTING package.json without
 // touching any other field, or MINT a minimal one when the repo has none. When the
 // dep is already present the file is left byte-untouched (no reserialize). An
 // unparseable package.json is left alone with a report — adopt never risks
@@ -785,10 +829,15 @@ async function main(argv) {
   const adopt = hasFlag('--adopt', args); // brownfield: LAYER onto an existing repo (ADR 0121)
   const accept = hasFlag('--accept', args) || hasFlag('--yes', args) || hasFlag('-y', args); // adopt pre-flight accept-gate (§Decision 5)
   const vendorCore = arg('--vendor-core', args); // greenfield: vendor + file:-pin a core .tgz, then generate the lockfile (ADR 0108 gap 1/4, task 2053)
+  const registryCore = hasFlag('--registry-core', args); // greenfield: caret pin + env-fed .npmrc → `npm ci` pulls the PRIVATE core from the registry (ADR 0134, task 2090)
 
   if (adopt && force) {
     console.error('init: --force is a greenfield-only overwrite; --adopt never overwrites, so --force is ignored.');
   }
+  if (vendorCore && registryCore) {
+    console.error('init: --vendor-core and --registry-core are mutually exclusive — the vendored tarball and the registry pull are two ways to resolve the same core dependency. Pick one.');
+    return 1;
+  }
 
   let raw;
   if (fromPath) {
@@ -841,7 +890,7 @@ async function main(argv) {
   console.log(`\nScaffolding "${spec.identity.productName}"${dryRun ? '  (dry run — nothing will be written or created)' : ''}:`);
   writeConfigs(spec, { dir, force, dryRun, coreDep });
 
-  // Vendor the pinned @cloudbongos/core tarball + generate the lockfile so the scaffold is
+  // Vendor the pinned @bongos/core tarball + generate the lockfile so the scaffold is
   // `npm ci --omit=dev`-installable by the provisioner (ADR 0108 gap 1/4, task 2053). The
   // `npm install` here is the ONLY heavy step — it CREATES package-lock.json from the file:
   // tarball; the provisioner later runs `npm ci` against that committed lockfile.
@@ -849,14 +898,42 @@ async function main(argv) {
     if (dryRun) {
       console.log(`\n[dry-run] would vendor ${vendorPlan.tgz} → ${vendorPlan.vendorRel} and run \`npm install\` to generate package-lock.json`);
     } else {
-      console.log('\nVendoring the pinned @cloudbongos/core + generating the lockfile:');
+      console.log('\nVendoring the pinned @bongos/core + generating the lockfile:');
       upgrade.vendorTarball({ instanceDir: dir, fromTgz: vendorPlan.tgz, targetVersion: vendorPlan.version });
       console.log(`  ✓ vendored ${vendorPlan.vendorRel}`);
       const inst = upgrade.npmInstall(dir);
       if (!inst.ok) {
         console.error(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — package-lock.json not generated; run \`npm install\` in ${dir} by hand before provisioning.`);
       } else {
-        console.log('  ✓ npm install → package-lock.json generated (node_modules/@cloudbongos/core installed)');
+        console.log('  ✓ npm install → package-lock.json generated (node_modules/@bongos/core installed)');
+      }
+    }
+  }
+
+  // Registry-install path (ADR 0134, task 2090): keep the caret pin writeConfigs wrote
+  // and add an env-fed .npmrc so `npm ci` pulls the PRIVATE @bongos/core from the
+  // registry. With NPM_TOKEN present we also generate package-lock.json (a reproducible
+  // `npm ci` later); without a token we still write the caret pin + .npmrc so the
+  // scaffold is registry-shaped, and say plainly that the private package 404s until a
+  // token is provided — the expected tokenless outcome the ADR calls to verify.
+  if (registryCore) {
+    if (dryRun) {
+      console.log(`\n[dry-run] would write .npmrc (env-fed @bongos auth) and ${hasNpmToken()
+        ? 'run `npm install` to generate package-lock.json from the registry'
+        : 'SKIP lockfile generation (no NPM_TOKEN — the private core 404s until one is provided)'}`);
+    } else {
+      console.log('\nWiring the registry-install path (ADR 0134):');
+      writeNpmrc(dir, { log: console.log });
+      if (hasNpmToken()) {
+        const inst = upgrade.npmInstall(dir);
+        if (!inst.ok) {
+          console.error(`  ! npm install failed (${inst.reason || 'exit ' + inst.code}) — confirm NPM_TOKEN reaches the private @bongos org; package-lock.json not generated.`);
+        } else {
+          console.log('  ✓ npm install → package-lock.json generated (pulled @bongos/core from the registry)');
+        }
+      } else {
+        console.log('  • no NPM_TOKEN in the environment — wrote the caret pin + .npmrc but skipped lockfile generation.');
+        console.log('    Provide a read-only automation token (paid `bongos` org) as NPM_TOKEN before `npm ci`; without it the private package 404s cleanly.');
       }
     }
   }
@@ -868,6 +945,23 @@ async function main(argv) {
   console.log('\nMaterializing the .claude/ methodology surface:');
   materializeClaude({ coreRoot: resolveCoreRoot(), instanceDir: dir, dryRun, log: console.log });
 
+  // Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
+  // client) from the PINNED core's routes so this fresh consumer's COMMITTED artifacts
+  // match its core from day one — not the core package's build-time snapshot (task 2141).
+  // They ship as CORE starters (task 2078 — the hall/docs must render before first regen)
+  // yet are per-instance GENERATED; `bongos upgrade` does the same on a bump, this closes
+  // the gap at standup. Best-effort: a hiccup warns, never fails init — the instance-root
+  // drift guard (fitness `gen-api-docs --check` + the api_client byte-identity test)
+  // catches any lag on the consumer's first CI.
+  if (dryRun) {
+    console.log('\n[dry-run] would regenerate the API artifacts (OpenAPI spec + reference + typed client) from the pinned core');
+  } else {
+    console.log('\nRegenerating the API artifacts from the pinned core (OpenAPI spec + reference + typed client):');
+    const regen = upgrade.regenerateApiArtifacts({ instanceDir: dir, coreRoot: resolveCoreRoot() });
+    if (regen.ok) console.log(`  ✓ regenerated (${regen.ran.join(', ')}) → docs/api/ + docs/api-reference.md + clients/bongos-client/`);
+    else console.error(`  ! API-artifact regen skipped (${regen.reason}) — regenerate in ${dir} by hand; the instance-root fitness gate flags the lag otherwise.`);
+  }
+
   let seedResult = {};
   if (!noSeed) seedResult = (await seedViaApi(spec, { dryRun })) || {};
   else console.log('  (--no-seed: skipped version/task seeding)');
@@ -893,6 +987,8 @@ module.exports = {
   KNOWN_MODULES, HOSTING_SHAPES, CORE_PKG,
   // greenfield installability (ADR 0108 gap 1/4, task 2053)
   buildInstancePackageJson, coreVersionSafe, INSTANCE_START_SCRIPT, INSTANCE_MIGRATE_SCRIPT,
+  // enabled-module dep composition (ADR 0138 / task 2160)
+  moduleDeclaredDeps, enabledModuleDeps,
 };
 
 if (require.main === module) {