@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/credential-presence.js

@@ -1,296 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/credential-presence.js — which credentials does this HOST hold? Names and
-// presence only, never a value (task 1002880, from idea 1000630).
-//
-// Run ON THE HOST, as the user that can read the instance's env files (usually via sudo):
-//   node scripts/gds/credential-presence.js                 # reads /etc/<configDir>/*.env
-//   node scripts/gds/credential-presence.js --etc /etc/example --json
-//
-// WHY. The owner was asked to create GitHub credentials at least three times, and each
-// time the credential already existed — nothing could answer "what does this instance
-// need, what is set, what is missing". docs/credentials.md is the written half (what each
-// credential is for, where it lives, who may hold it); this is the one-command half, run
-// where the values actually live. doctor.js cannot do it: it runs on a builder's laptop,
-// which never sees the host's env files, and that is by design.
-//
-// THE ONE RULE: A VALUE NEVER LEAVES THE FILE. The report says set / empty / missing and
-// the NAME of the variable that satisfied each row — never the value, never a prefix,
-// never a length. tests/credential_presence.mjs asserts no fragment of any value reaches
-// the output. If this is ever surfaced over HTTP it must be Archon-gated, and it still
-// returns names only.
-//
-// Deeper than presence: `node scripts/gds/publish-credential-check.js` (task 1002733)
-// probes whether the publish credential can actually read the Actions API. This file
-// does not call GitHub — presence is the question it answers, offline.
-//
-// Exit: 0 = every REQUIRED row is satisfied · 1 = a required row is missing ·
-// 2 = an env file this host should have could not be read (the answer is unknown).
-
+// scripts/gds/credential-presence.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/credential-presence.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { resolveEnv, envPrefix, configDirName, configPath, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
-const { arg, hasFlag, cliExit } = require('./cli-lib');
-
-// ---- the inventory -------------------------------------------------------------------
-//
-// One row per credential this instance's HOST may hold. `names` are the env var(s) that
-// must ALL be non-empty for the row to count as set; `prefixed` names resolve through the
-// instance's own env prefix (and its legacy spellings) the way the server reads them.
-// Rows sharing a `group` are alternatives: the group is satisfied when any member is.
-// `file` is the env file the value lives in on a control-plane host:
-//   web.env    — the web tier (the cloudbongos.service EnvironmentFile)
-//   box.env    — the control-plane runners; deliberately unreadable by the web tier
-//                (InaccessiblePaths=, task 1004176 / ADR 0327 §5)
-//   spaces.env — the offsite-backup timer
-// `need`: required (the instance is broken without it) · recommended (a named feature
-// is off without it) · optional.
-//
-// Every name here is documented in docs/credentials.md; the test fails if either side
-// gains a name the other lacks. Non-host credentials (GitHub Actions secrets, a
-// builder's own machine) are in the doc only — no host sweep can see them.
-const CREDENTIALS = [
-  {
-    id: 'github-sign-in', group: 'sign-in', file: 'web.env', need: 'required',
-    names: ['GITHUB_CLIENT_ID', 'GITHUB_CLIENT_SECRET'], prefixed: true,
-    purpose: 'GitHub OAuth app that signs builders in (src/bongos/auth-config.js)',
-  },
-  {
-    id: 'hub-federation', group: 'sign-in', file: 'web.env', need: 'required',
-    names: ['HUB_ORIGIN', 'HUB_CLIENT_ID', 'HUB_CLIENT_SECRET', 'HUB_PUBLIC_KEY'], prefixed: true,
-    purpose: 'sign-in federated through the Cloud Bongos hub instead of an own GitHub app (ADR 0141 §4)',
-  },
-  {
-    id: 'publish-app', group: 'publish', file: 'web.env', need: 'required',
-    names: ['GITHUB_APP_ID', 'GITHUB_APP_PRIVATE_KEY'],
-    purpose: 'GitHub App the server publishes builder branches and PRs with (modules/lifecycle/github-push.js); preferred',
-  },
-  {
-    id: 'publish-pat', group: 'publish', file: 'web.env', need: 'required',
-    names: ['GITHUB_PUSH_TOKEN'],
-    purpose: 'fine-grained PAT fallback for the same publish path, kept for cutover',
-  },
-  {
-    id: 'repo-pin', file: 'web.env', need: 'required',
-    names: ['GITHUB_OWNER', 'GITHUB_REPO'], prefixed: true, notSecret: true,
-    purpose: "which GitHub repo this instance is — mandatory where the core runs from node_modules, which has no git remote to read (src/bongos/repo-info.js)",
-  },
-  {
-    id: 'secret-box-key', file: 'web.env', need: 'required',
-    names: ['BUILDER_SECRET_KEY'], keyFile: 'builder-secret.key',
-    purpose: "master key encrypting builders' stored AI keys and GitHub tokens (src/bongos/secret-box.js); the key file in the service user's config dir also counts",
-  },
-  {
-    id: 'database-password', file: 'web.env', need: 'optional',
-    names: ['PGPASSWORD'],
-    purpose: "the instance's own Postgres role (src/bongos/pool.js); absent means local peer auth",
-  },
-  {
-    id: 'database-url', file: 'web.env', need: 'optional',
-    names: ['DATABASE_URL'],
-    purpose: 'a full Postgres connection string, when the database is not local',
-  },
-  {
-    id: 'discord-bot', file: 'web.env', need: 'recommended',
-    names: ['DISCORD_BOT_TOKEN'],
-    purpose: 'the Discord bot (modules/discord); also readable from discord-bot.json in the config dir',
-  },
-  {
-    id: 'discord-support', file: 'web.env', need: 'optional',
-    names: ['DISCORD_SUPPORT_ANTHROPIC_API_KEY'],
-    purpose: 'the #support answerer (modules/discord/discord-support.js, ADR 0367); its own key, never a host-wide ANTHROPIC_API_KEY',
-  },
-  {
-    id: 'discord-oauth', file: 'web.env', need: 'optional',
-    names: ['DISCORD_CLIENT_ID', 'DISCORD_CLIENT_SECRET'],
-    purpose: 'linking a Discord account at sign-in (src/bongos/auth-discord.js)',
-  },
-  {
-    id: 'discord-ship-news', file: 'web.env', need: 'optional',
-    names: ['DISCORD_SHIP_NEWS_WEBHOOK'],
-    purpose: '#ship-news posts (scripts/discord/lib.js); discord-webhooks.json in the config dir also works',
-  },
-  {
-    id: 'prelaunch-password', file: 'web.env', need: 'optional',
-    names: ['PRELAUNCH_PASSWORD'], legacyNames: ['STEALTH_PASSWORD'],
-    purpose: 'the pre-launch site password (src/bongos/prelaunch-gate.js); STEALTH_PASSWORD is the deprecated alias',
-  },
-  {
-    id: 'metrics-token', file: 'web.env', need: 'optional',
-    names: ['METRICS_TOKEN'],
-    purpose: 'bearer token for a remote Prometheus scrape of /metrics (src/bongos/metrics.js)',
-  },
-  {
-    id: 'module-test-runner', file: 'web.env', need: 'optional',
-    names: ['MODULE_TEST_REPO', 'MODULE_TEST_TOKEN'],
-    purpose: "runs store modules' own tests in a separate private GitHub repo (scripts/gds/module-test-runner.js, blocker 1000195); unset leaves Tests pending",
-  },
-  {
-    id: 'module-test-ref', file: 'web.env', need: 'optional',
-    names: ['MODULE_TEST_REF'], notSecret: true,
-    purpose: "the test repo branch holding the module-tests workflow (default main)",
-  },
-  {
-    id: 'hub-signing-key', file: 'web.env', need: 'optional',
-    names: ['HUB_SIGNING_KEY'], prefixed: true,
-    purpose: 'the HUB only: signs the assertions federated instances verify (modules/platform-identity/hub-keys.js)',
-  },
-  {
-    id: 'digitalocean', file: 'box.env', need: 'recommended',
-    names: ['DO_API_TOKEN'],
-    purpose: 'creates and destroys project servers (scripts/gds/do-api.js, provisioning); control plane only',
-  },
-  {
-    id: 'cloudflare', file: 'box.env', need: 'recommended',
-    names: ['CLOUDFLARE_API_TOKEN'],
-    purpose: 'DNS records for project addresses (scripts/gds/provision-net.js); control plane only',
-  },
-  {
-    id: 'offsite-backup', file: 'spaces.env', need: 'optional',
-    names: ['SPACES_KEY', 'SPACES_SECRET', 'SPACES_BUCKET'],
-    // The same file also carries the region, the endpoint and the age RECIPIENT the dumps
-    // are encrypted to. None is a secret (a recipient is a public key), so none is swept.
-    purpose: 'the weekly offsite copy of the database dumps (scripts/gds/db-backup-offsite.sh)',
-  },
-];
-
-const ENV_FILES = ['web.env', 'box.env', 'spaces.env'];
-
-// ---- pure core ------------------------------------------------------------------------
-
-// parseEnvFile(text) → { NAME: value } for a systemd EnvironmentFile: KEY=VALUE lines,
-// `#` comments, blank lines, optional surrounding quotes. Values are held only long enough
-// to test for emptiness; nothing returned by the report functions below contains one.
-function parseEnvFile(text) {
-  const out = {};
-  for (const raw of String(text || '').split(/\r?\n/)) {
-    const line = raw.trim();
-    if (!line || line.startsWith('#')) continue;
-    const eq = line.indexOf('=');
-    if (eq <= 0) continue;
-    const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
-    let value = line.slice(eq + 1).trim();
-    if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value[value.length - 1] === value[0]) {
-      value = value.slice(1, -1);
-    }
-    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) out[key] = value;
-  }
-  return out;
-}
-
-// Every spelling a name answers to, in the order the server tries them.
-function spellingsOf(name, row, prefix) {
-  if (row.prefixed) return [...new Set([prefix, ...LEGACY_ENV_PREFIXES])].map((p) => `${p}_${name}`);
-  return [name, ...(row.legacyNames || [])];
-}
-
-// checkRow(row, env, { prefix, keyFileExists }) → { state, satisfiedBy, missing }
-// state: 'set' | 'empty' | 'missing'. satisfiedBy / missing are variable NAMES.
-function checkRow(row, env, { prefix = envPrefix(), keyFileExists = false } = {}) {
-  const satisfiedBy = [];
-  const missing = [];
-  let anyEmpty = false;
-  for (const name of row.names) {
-    const spellings = spellingsOf(name, row, prefix);
-    const value = row.prefixed ? resolveEnv(name, { env, prefix, warn: () => {} }) : spellings.map((s) => env[s]).find((v) => v);
-    if (value) {
-      satisfiedBy.push(spellings.find((s) => env[s] === value) || spellings[0]);
-    } else {
-      if (spellings.some((s) => s in env)) anyEmpty = true;
-      missing.push(spellings[0]);
-    }
-  }
-  if (missing.length && row.keyFile && keyFileExists) {
-    return { state: 'set', satisfiedBy: [`${row.keyFile} (key file)`], missing: [] };
-  }
-  const state = missing.length === 0 ? 'set' : anyEmpty ? 'empty' : 'missing';
-  return { state, satisfiedBy, missing };
-}
-
-// sweep({ files, prefix, keyFileExists }) → { rows, groups, unreadable, ok }
-// files: { 'web.env': { env } | { error } } — the parsed files, or why one could not be read.
-function sweep({ files, prefix = envPrefix(), keyFileExists = false, credentials = CREDENTIALS }) {
-  const unreadable = Object.entries(files).filter(([, f]) => f.error).map(([name, f]) => ({ file: name, error: f.error }));
-  const rows = credentials.map((row) => {
-    const f = files[row.file];
-    if (!f || f.error) return { ...pick(row), state: 'unknown', satisfiedBy: [], missing: [] };
-    return { ...pick(row), ...checkRow(row, f.env, { prefix, keyFileExists }) };
-  });
-  // A group is satisfied when any member is; its members are not individually required.
-  const groups = {};
-  for (const r of rows) {
-    if (!r.group) continue;
-    groups[r.group] = groups[r.group] || { satisfied: false, unknown: false, members: [] };
-    groups[r.group].members.push(r.id);
-    if (r.state === 'set') groups[r.group].satisfied = true;
-    if (r.state === 'unknown') groups[r.group].unknown = true;
-  }
-  const requiredMissing = rows.filter((r) => r.need === 'required' && r.state !== 'set' && r.state !== 'unknown'
-    && !(r.group && groups[r.group].satisfied));
-  const ok = requiredMissing.length === 0 && unreadable.length === 0;
-  return { rows, groups, unreadable, requiredMissing: requiredMissing.map((r) => r.id), ok };
-}
-
-function pick(row) {
-  return { id: row.id, file: row.file, need: row.need, group: row.group || null, purpose: row.purpose, notSecret: !!row.notSecret };
-}
-
-// format(result) → the human report. Built only from ids, names, states and the fixed
-// purpose text — never from a parsed value.
-function format(result, { etc } = {}) {
-  const mark = { set: '✓', empty: '!', missing: '✗', unknown: '?' };
-  const lines = [`Credential presence — names only, never values (${etc || 'env files'})`, ''];
-  for (const file of ENV_FILES) {
-    const rows = result.rows.filter((r) => r.file === file);
-    if (!rows.length) continue;
-    const bad = result.unreadable.find((u) => u.file === file);
-    lines.push(`  ${file}${bad ? `  — could not read: ${bad.error}` : ''}`);
-    for (const r of rows) {
-      const grp = r.group ? result.groups[r.group] : null;
-      const covered = grp && grp.satisfied && r.state !== 'set' ? ` (not needed: another ${r.group} option is set)` : '';
-      const detail = r.state === 'set' ? `via ${r.satisfiedBy.join(', ')}`
-        : r.state === 'unknown' ? 'file unreadable'
-        : `${r.state === 'empty' ? 'set but EMPTY' : 'not set'}: ${r.missing.join(', ')}`;
-      lines.push(`    ${mark[r.state]} ${r.id.padEnd(20)} ${r.need.padEnd(11)} ${detail}${covered}`);
-    }
-    lines.push('');
-  }
-  if (result.requiredMissing.length) lines.push(`REQUIRED and missing: ${result.requiredMissing.join(', ')} — see docs/credentials.md for what each is and where it comes from.`);
-  if (result.unreadable.length) lines.push('Some env files could not be read, so this answer is incomplete — rerun as a user that can read them (usually sudo).');
-  if (result.ok) lines.push('Every required credential is present.');
-  lines.push('Deeper check of the publish credential (can it read Actions?): node scripts/gds/publish-credential-check.js');
-  return lines.join('\n');
-}
-
-// readFiles(etc) → the `files` shape sweep() takes, read from <etc>/<name>.
-function readFiles(etc, { fsImpl = fs } = {}) {
-  const files = {};
-  for (const name of ENV_FILES) {
-    const p = path.join(etc, name);
-    try {
-      files[name] = { env: parseEnvFile(fsImpl.readFileSync(p, 'utf8')) };
-    } catch (e) {
-      // An absent spaces.env just means offsite backups were never set up; an absent
-      // web.env means this is not the host (or the wrong --etc).
-      files[name] = e.code === 'ENOENT' && name !== 'web.env' ? { env: {} } : { error: e.code || e.message };
-    }
-  }
-  return files;
-}
-
-module.exports = { CREDENTIALS, ENV_FILES, parseEnvFile, checkRow, sweep, format, readFiles };
-
-if (require.main === module) {
-  const etcArg = arg('--etc');
-  const etc = etcArg && etcArg !== true ? etcArg : path.join('/etc', configDirName());
-  const files = readFiles(etc);
-  const keyArg = arg('--secret-key-file');
-  const keyFile = keyArg && keyArg !== true ? keyArg : configPath('builder-secret.key');
-  let keyFileExists = false;
-  try { keyFileExists = fs.statSync(keyFile).isFile(); } catch (_) { /* absent */ }
-  const result = sweep({ files, keyFileExists });
-  if (hasFlag('--json')) console.log(JSON.stringify({ etc, ...result }, null, 2));
-  else console.log(format(result, { etc }));
-  cliExit(result.unreadable.length ? 2 : result.ok ? 0 : 1);
-}
+require('../bongos/forwarder.js').forward(module, 'credential-presence.js');

package/scripts/gds/cutover-codemod.js

@@ -1,241 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/cutover-codemod.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/cutover-codemod.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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-example-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());
-}
+require('../bongos/forwarder.js').forward(module, 'cutover-codemod.js');