@bongos/core 1.21.174 → 1.21.176

package/scripts/gds/module.js

@@ -1,1376 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/module.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/module.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';
-//
-// scripts/gds/module.js — `bongos module new <key>` (scaffolder) + `bongos upgrade`
-// (coreVersion pre-check). BONGOS-V1 · BV1.R50 · task 1419 (ADR 0083 / design 04§2).
-//
-// Two halves of "operating the module system from the terminal":
-//
-//   bongos module new <key>
-//     Scaffolds modules/<key>/ — a VALID, loader-discoverable module.json (M03),
-//     the dir skeleton (routes/, migrations/, ui/), a sample route factory, a
-//     HOWTO.md template for the store page (ADR 0347), and a nested CLAUDE.md — with NO edit to any core file. The loader
-//     (src/module-loader/loader.js) discovers it; enabling it (config/modules.json
-//     or env) mounts its routes behind the kernel's auth — the strangler endgame
-//     where adding a feature is "drop a directory," not "edit routes.js + modules.js".
-//
-//   bongos upgrade
-//     A fail-closed pre-flight: every ENABLED discovered module declares the
-//     src/module-api.js CORE_VERSION range (`coreVersion`) it supports. This
-//     reports each module's compatibility and REFUSES (exit 1) if an enabled
-//     module no longer satisfies the current core — the loud, ahead-of-time
-//     version of the loader's silent coreVersion SKIP (which would just drop the
-//     module at boot). Disabled mismatches are warnings, not blockers.
-//
-//   bongos module list [--catalog] [--search <q>] [--json]
-//     ADR 0107 §2/§3 (task 1001772) — the BROWSABLE CATALOG from the terminal:
-//     every module this instance can enable, each with its author + origin
-//     credit, its enabled state, and who maintains it. `--catalog` narrows to
-//     the CORE-shipped modules (the shared catalog an instance opts into, §6);
-//     without it you also see the instance's own modules. It renders the same
-//     model as the hall's Modules tab (src/module-loader/catalog.js), so the two
-//     surfaces cannot disagree about who built what.
-//
-//   bongos module check <key>
-//     ADR 0107 §4 — the submit-time pre-check a module must clear before it can
-//     be upstreamed into the shared core catalog. REUSES (never re-types) the
-//     public-mirror publish boundary (scripts/gds/publish-manifest.js): every
-//     file the module carries is classified as if it already lived at its
-//     canonical modules/<key>/ location, and anything the DENYLIST forbids
-//     (game content, pixel art, copyrighted reference material, instance
-//     secrets, deploy/CI topology) fails the check with a clear reason — this
-//     is deliberately the DENY half only, not the full isPublishable() gate,
-//     because a brand-new module is never on the ALLOWLIST until it is
-//     accepted (§6); that omission must not read as "denied content." Also
-//     requires the manifest to declare an AGPL-3.0 license (inbound = outbound,
-//     ADR 0107 §4 — no CLA) and a `maintenance` posture (ADR 0107 §7 / ADR
-//     0166 — core-maintained, or maintained by a named maintainer; a module
-//     already deprecated/orphaned cannot be submitted INTO the catalog).
-//     On a pass, `--sign-off "Name <email>"` records a
-//     lightweight DCO-style affirmation (own work, licensed AGPL-3.0 — never a
-//     copyright-assignment CLA) to modules/<key>/.upstream-signoff.json.
-//
-// This is build tooling (scripts/), so — unlike a module — it may freely require
-// the core (src/*). It makes NO API/network calls: it is pure local fs + config
-// resolution, so it runs anywhere (a box, CI, a laptop) with no GDS session.
-//
-// Usage:
-//   bongos module new <key>            scaffold modules/<key>/
-//   bongos module new <key> --force    overwrite an existing modules/<key>/
-//   bongos module list [--catalog]     browse the module catalog (author + origin credit)
-//   bongos upgrade [--no-store]        pre-check enabled modules vs the core version + list store updates
-//   bongos module check <key> [--sign-off "Name <email>"]   AGPL/publish pre-check + DCO sign-off
-//   bongos module install <key> [--version X.Y.Z]   acquire from the store, verify, place (not enabled)
-//   bongos module update <key> [--version X.Y.Z]    move an installed store module forward
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
-const MODULES_DIR = path.join(REPO_ROOT, 'modules');
-
-const { validateManifest, assertValidManifest, KEY_RE, SUNSET_STATUSES } = require('../../src/module-loader/manifest-schema');
-const { parseVersion, cmp } = require('../../src/module-loader/semver');
-const loader = require('../../src/module-loader/loader');
-const catalog = require('../../src/module-loader/catalog');
-const { resolveModules, MODULE_REGISTRY, NEUTRAL_PATH, INSTANCE_PATH } = require('../../src/modules');
-// The public-mirror publish boundary (ADR 0098) — REUSED, never re-typed, for
-// the ADR 0107 §4 upstreaming pre-check. Only matchesDeny is used (not the full
-// isPublishable), because a brand-new module is never on the ALLOWLIST until
-// accepted (§6) — gating on the allowlist here would reject every legitimate
-// new module. The denylist is the copyright/content classification we want.
-const { matchesDeny } = require('./publish-manifest');
-
-// CORE_VERSION via the doorway, lazily + fail-soft (mirrors loader.coreVersion):
-// requiring src/module-api pulls auth/pool, so a tooling context with no DB still
-// resolves to the known initial version rather than crashing.
-function coreVersion() {
-  try { return require('../../src/module-api').CORE_VERSION; }
-  catch { return '1.0.0'; }
-}
-
-function readJson(p) {
-  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
-  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
-}
-
-// A text file's contents, or null when it does not exist.
-function readText(p) {
-  try { return fs.readFileSync(p, 'utf8'); }
-  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
-}
-
-function envPrefix() {
-  const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config');
-  try { return require('../../src/branding').branding().envPrefix || FALLBACK_ENV_PREFIX; }
-  catch { return FALLBACK_ENV_PREFIX; }
-}
-
-// ---------------------------------------------------------------------------
-// Pure builders (exported for tests — no I/O, no network)
-// ---------------------------------------------------------------------------
-
-// art-pipeline -> "Art Pipeline"; economy -> "Economy". A readable default title.
-function titleize(key) {
-  return String(key).split(/[-_]+/).filter(Boolean)
-    .map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
-}
-// art-pipeline -> artPipeline (for the generated route-factory function name).
-function camel(key) {
-  return String(key).replace(/[-_]+(.)/g, (_, c) => c.toUpperCase());
-}
-
-// The minimal-but-valid manifest a fresh module starts from. coreVersion is a
-// caret on the CURRENT core, so the module supports this core + its future
-// minors; it declares one sample route so the scaffold mounts something real.
-// The four attribution fields (ADR 0107 §2) are stamped as TODO placeholders —
-// non-empty so they self-validate — so authorship travels with the module from
-// the start rather than being an afterthought bolted on at upstream-submit time.
-// `license` defaults to the core's own license (AGPL-3.0, ADR 0065) since
-// inbound = outbound is the project's default posture; override if different.
-function buildManifest(key, { core = coreVersion() } = {}) {
-  return {
-    key,
-    title: titleize(key),
-    description: `TODO: one sentence describing the ${key} module.`,
-    // The module's own version (task 1003781). A fresh scaffold is pre-release.
-    version: '0.1.0',
-    coreVersion: `^${core}`,
-    default: false,
-    author: 'TODO: your name or builder handle',
-    origin: 'TODO: the instance/project this module was built in',
-    license: 'AGPL-3.0',
-    maintainer: 'TODO: who to credit/contact if this module is upstreamed',
-    // Upkeep posture (ADR 0107 §7 / ADR 0166). Scaffolded as `maintained`
-    // because a brand-new module's author IS its maintainer — the honest
-    // default. Change it to `core-maintained` only if the core team has agreed
-    // to own it, and to `deprecated`/`orphaned` (with a path) when that changes.
-    maintenance: { status: 'maintained' },
-    contributes: { routes: [key] },
-  };
-}
-
-function routeTemplate(key) {
-  const fn = `${camel(key)}Routes`;
-  return `// modules/${key}/routes/${key}.js — sample route factory for the "${key}" module.
-//
-// A route factory is \`() => express.Router()\`. The loader (src/module-loader)
-// mounts it behind the kernel's auth + audit when this module is enabled — you
-// never edit the core to add a route. Reach core capabilities ONLY through the
-// published doorway src/module-api.js; never deep-import core internals or a
-// sibling module (the one-way rule, ADR 0083).
-'use strict';
-
-const express = require('express');
-const api = require('../../../src/module-api');
-
-module.exports = function ${fn}() {
-  const router = express.Router();
-
-  // Read routes need no rank gate. EVERY write route MUST be rank-gated — list
-  // every rank allowed; ('metic', 'archon') means Metic-and-above, e.g.:
-  //   router.post('/${key}/thing', api.requireRank('metic', 'archon'), (req, res) => { ... });
-  // the BV1.R44 fitness check fails the build on an ungated module write route.
-  router.get('/${key}/health', (req, res) => {
-    res.json({ module: '${key}', ok: true, coreVersion: api.CORE_VERSION });
-  });
-
-  return router;
-};
-`;
-}
-
-function claudeMdTemplate(key, manifest) {
-  const ENVKEY = key.toUpperCase().replace(/-/g, '_');
-  return `# ${manifest.title} module (\`modules/${key}/\`)
-
-> A Cloud Bongos feature module. It contributes routes / rooms / migrations / UI
-> to the host **only** through its \`module.json\` manifest + the published doorway
-> \`src/module-api.js\`. The core never imports it; it never imports core internals
-> or a sibling module (the one-way rule, ADR 0083).
-
-## Manifest (\`module.json\`)
-- \`key\` — must equal this directory name (\`${key}\`).
-- \`coreVersion\` — the \`src/module-api.js\` CORE_VERSION range this module supports.
-  \`bongos upgrade\` refuses to advance the core if an enabled module no longer
-  satisfies it; the loader silently skips a mismatched module at boot.
-- \`contributes\` — what mounts: \`routes\`, \`rooms\`, \`pollers\`, \`disciplines\`,
-  \`skills\`, \`uiSections\`, \`migrations\`. An empty \`{}\` is valid (mounts nothing).
-- \`default\` — fail-safe enablement when no config names the module (keep \`false\`).
-- \`author\` / \`origin\` / \`license\` / \`maintainer\` — attribution (ADR 0107 §2).
-  Optional but scaffolded as TODOs — fill them in now so credit travels with the
-  module if it's ever upstreamed to core. Portable metadata, not a cross-GDS link.
-
-## Enable it
-This module is OFF until an instance turns it on, via \`config/modules.json\`
-(\`{ "modules": { "${key}": true } }\`) or env (\`<PREFIX>_MODULE_${ENVKEY}=1\`). The
-loader then discovers and mounts it — no core edit.
-
-## Add a route
-\`contributes.routes: ["${key}"]\` → \`routes/${key}.js\` exports \`() => express.Router()\`.
-Gate every write route with \`api.requireRank('metic', 'archon')\` (Metic-and-above —
-list every allowed rank; BV1.R44 enforces this).
-
-## Add a migration
-Put \`NNN_*.sql\` under \`migrations/\` and set \`contributes.migrations: true\`
-(BV1.R46). Own only your \`${key}_*\` tables.
-
-## The one-way rule
-\`require('../../../src/module-api')\` — the doorway — is the ONLY core import
-allowed. No deep core imports, no sibling-module imports; cooperate through
-kernel seams (\`api.registerProvider\` / \`api.resolve\` / \`api.on\` / \`api.emit\`).
-
-## The how-to (\`HOWTO.md\`)
-This CLAUDE.md is for AI sessions working *inside* the module. \`HOWTO.md\` is for the
-person who installs it — the store shows it as the module's page (ADR 0347). It is
-plain Markdown, so any AI or person can write it. \`bongos module publish\` refuses
-the module until each of its five sections has some text; replace the prompts in
-\`<!-- -->\` with real answers. An optional \`howto.artifactUrl\` in module.json can
-link a Claude page as an extra — never instead of the file.
-`;
-}
-
-// The HOWTO.md a fresh module starts from (ADR 0347 D2): every required section as a
-// heading, with its prompt in an HTML comment. checkHowto strips comments, so an
-// untouched scaffold fails the publish gate until the author writes each section.
-function howtoTemplate(key, manifest) {
-  const { HOWTO_SECTIONS } = require('./module-artifact');
-  const prompts = {
-    'What it does': 'A few sentences: what this module adds, and who it is for.',
-    'Install and enable': `How to get it (\`bongos module install ${key}\`) and switch it on (hall Modules tab).`,
-    'How to use it': 'Its commands, routes and hall surfaces, with one worked example.',
-    'Configuration': 'Env vars and settings, with their defaults. "None." is a fine answer.',
-    'Limits and known issues': 'What it does not do, and anything known to go wrong. "None known." is a fine answer.',
-  };
-  const sections = HOWTO_SECTIONS.map((name) => `## ${name}\n\n<!-- ${prompts[name]} -->\n`).join('\n');
-  return `# ${manifest.title} — how to use it
-
-<!-- Written for the person who installs this module, or for any AI helping them.
-     The store shows this file as the module's page. Every section below must have
-     some text before \`bongos module publish\` will accept the module (ADR 0347). -->
-
-${sections}`;
-}
-
-// Has the core advanced past a deprecated module's declared removal version?
-// `removeAfter: "1.12.0"` means "may be deleted once core is ABOVE 1.12.0".
-function isPastRemoveAfter(maintenance, core) {
-  const after = maintenance && maintenance.removeAfter;
-  const a = parseVersion(after);
-  const c = parseVersion(core);
-  return !!(a && c && cmp(c, a) > 0);
-}
-
-// One line of "who do I chase about this?" for a row, from its maintenance block
-// (ADR 0166). Shared by cmdUpgrade and upgrade.js's real-bump pre-flight so both
-// surfaces say the same thing about the same module.
-function formatMaintenanceHint(row = {}) {
-  const m = row.maintenance;
-  if (!m || !m.status) {
-    return 'no maintenance declared — nobody is on the hook for this module (ADR 0166: declare a `maintenance` block)';
-  }
-  const parts = [`maintenance: ${m.status}`];
-  if (m.status === 'maintained') parts.push(`maintainer ${row.maintainer || '(unnamed!)'}`);
-  if (m.status === 'core-maintained') parts.push('core-maintained — fixing this is the core\'s job');
-  if (m.successor) parts.push(`superseded by "${m.successor}"`);
-  if (m.removeAfter) parts.push(`removable after core ${m.removeAfter}`);
-  if (m.note) parts.push(m.note);
-  return parts.join('; ');
-}
-
-// Decide compatibility from rows (pure — tests drive it with injected rows).
-// A row: { key, coreVersion, enabled, satisfied, maintenance?, maintainer? }.
-//
-// BLOCKING = an enabled module that does not satisfy the core (fail-closed).
-// WARNINGS = a DISABLED mismatch. These are not cosmetic: an accepted catalog
-// module ships `default: false` (ADR 0107 §6), so EVERY rotted catalog entry
-// lands in this bucket. Dropping warnings on the floor is exactly how "the
-// catalog fills with silently-broken entries" happens (ADR 0107 §7) — every
-// caller must surface them, even though none of them block.
-// DEPRECATIONS = modules whose own manifest says they are on the way out;
-// EXPIRED = deprecated modules the core has already advanced past `removeAfter`
-// (they are due for deletion, not just a label).
-function evaluateUpgrade({ rows = [], errors = [], core } = {}) {
-  const blocking = rows.filter((r) => r.enabled && !r.satisfied);
-  const warnings = rows.filter((r) => !r.enabled && !r.satisfied);
-  const deprecations = rows.filter((r) => r.maintenance && SUNSET_STATUSES.includes(r.maintenance.status));
-  const expired = deprecations.filter((r) => isPastRemoveAfter(r.maintenance, core));
-  const undeclared = rows.filter((r) => !r.maintenance || !r.maintenance.status);
-  return { ok: blocking.length === 0, blocking, warnings, deprecations, expired, undeclared, rows, errors, core };
-}
-
-// ---------------------------------------------------------------------------
-// Scaffolder (fs)
-// ---------------------------------------------------------------------------
-
-function scaffoldModule({ key, modulesDir = MODULES_DIR, core = coreVersion(), force = false } = {}) {
-  if (!key || !KEY_RE.test(key)) {
-    throw new Error(`invalid module key "${key}" — must match ${KEY_RE} (lowercase kebab-case, e.g. "art-pipeline")`);
-  }
-  const dir = path.join(modulesDir, key);
-  if (fs.existsSync(dir) && !force) {
-    throw new Error(`${path.relative(REPO_ROOT, dir)} already exists — use --force to overwrite, or pick another key.`);
-  }
-  const manifest = buildManifest(key, { core });
-  // self-check: a scaffolder that emits an INVALID manifest is a bug, not a typo.
-  assertValidManifest(manifest, `generated modules/${key}/module.json`);
-
-  const files = {
-    'module.json': JSON.stringify(manifest, null, 2) + '\n',
-    [`routes/${key}.js`]: routeTemplate(key),
-    'CLAUDE.md': claudeMdTemplate(key, manifest),
-    'HOWTO.md': howtoTemplate(key, manifest),
-    // git does not track empty dirs — keep the rest of the skeleton with placeholders.
-    'migrations/.gitkeep': '',
-    'ui/.gitkeep': '',
-  };
-  for (const [relp, content] of Object.entries(files)) {
-    const fp = path.join(dir, relp);
-    fs.mkdirSync(path.dirname(fp), { recursive: true });
-    fs.writeFileSync(fp, content);
-  }
-  return { dir, files: Object.keys(files), manifest };
-}
-
-// Gather the live compatibility state from disk + config (the I/O half of upgrade).
-function gatherUpgrade({ modulesDir = MODULES_DIR, core = coreVersion(), env = process.env, neutral, instance, prefix } = {}) {
-  neutral = neutral || readJson(NEUTRAL_PATH) || {};
-  instance = instance || readJson(INSTANCE_PATH) || {};
-  prefix = prefix || envPrefix();
-
-  const { loaded, skipped, errors } = loader.discoverModules({ roots: [modulesDir], core });
-  // the loader drops skipped manifests; re-read them so we can show coreVersion + default.
-  const skippedFull = skipped.map((s) => {
-    let manifest = null;
-    try { manifest = JSON.parse(fs.readFileSync(path.join(s.dir, 'module.json'), 'utf8')); } catch { /* gone/garbled */ }
-    return { ...s, manifest };
-  });
-
-  // resolveModules throws on an unknown key, so the registry MUST span every
-  // discovered key (loaded + skipped) — built-in entries plus a synthesized
-  // {default} for each discovered module.
-  const registry = { ...MODULE_REGISTRY };
-  for (const { key, manifest } of loaded) {
-    if (!(key in registry)) registry[key] = { default: manifest.default === true, contributes: manifest.contributes || {} };
-  }
-  for (const { key, manifest } of skippedFull) {
-    if (key && !(key in registry)) registry[key] = { default: manifest && manifest.default === true, contributes: (manifest && manifest.contributes) || {} };
-  }
-
-  let enabled = {};
-  try { enabled = resolveModules({ neutral, instance, env, envPrefix: prefix, registry }); }
-  catch { /* a malformed config shouldn't crash the pre-check; treat all as disabled */ }
-
-  // Maintenance posture travels with the row (ADR 0166) so both the pre-check
-  // printout and the real bump can say WHO owns a module that no longer fits —
-  // an incompatibility with no owner named is the orphaning failure itself.
-  const upkeep = (manifest) => ({
-    maintenance: (manifest && manifest.maintenance) || null,
-    maintainer: (manifest && manifest.maintainer) || null,
-  });
-
-  const rows = [];
-  for (const { key, manifest } of loaded) {
-    rows.push({ key, version: manifest.version || null, coreVersion: manifest.coreVersion, enabled: enabled[key] === true, satisfied: true, ...upkeep(manifest) });
-  }
-  for (const { key, manifest, reason } of skippedFull) {
-    rows.push({ key, version: (manifest && manifest.version) || null, coreVersion: manifest ? manifest.coreVersion : null, enabled: enabled[key] === true, satisfied: false, reason, ...upkeep(manifest) });
-  }
-  rows.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-  return { rows, errors, core };
-}
-
-// ---------------------------------------------------------------------------
-// bongos module list — ADR 0107 §2/§3 the browsable catalog (task 1001772)
-// ---------------------------------------------------------------------------
-
-// The live catalog off disk + config. Unlike gatherUpgrade (which scans ONE
-// modulesDir because it is answering a question about this checkout's own
-// modules), this uses the loader's DEFAULT roots so a split instance sees both
-// trees — the core package's modules/ AND its own (ADR 0108 §1). That two-root
-// scan is what makes "core-shipped vs. built here" a structural fact here
-// rather than a guess.
-function gatherCatalog({ roots, core = coreVersion(), env = process.env, neutral, instance, prefix } = {}) {
-  neutral = neutral || readJson(NEUTRAL_PATH) || {};
-  instance = instance || readJson(INSTANCE_PATH) || {};
-  prefix = prefix || envPrefix();
-
-  const { loaded, skipped, errors } = loader.discoverModules(roots ? { roots, core } : { core });
-
-  // Same registry-spanning rule as gatherUpgrade: resolveModules throws on an
-  // unknown key, so every discovered key must be in the registry it is given.
-  const registry = { ...MODULE_REGISTRY };
-  for (const { key, manifest } of loaded) {
-    if (!(key in registry)) registry[key] = { default: manifest.default === true, contributes: manifest.contributes || {} };
-  }
-  for (const { key } of skipped) {
-    if (key && !(key in registry)) registry[key] = { default: false, contributes: {} };
-  }
-
-  let enabled = {};
-  try { enabled = resolveModules({ neutral, instance, env, envPrefix: prefix, registry }); }
-  catch { /* a malformed config must not blank the catalog — show it all as disabled */ }
-
-  const { coreRoot, instanceRoot, coreCheckout } = catalog.detectRoots();
-  const rows = catalog.buildCatalog({
-    loaded, enabled, coreRoot, instanceRoot, coreCheckout, ownProjectName: ownProjectName(),
-  });
-  return { rows, skipped, errors, core };
-}
-
-// The instance's own product name, for the credit axis (deriveProvenance).
-// Fail-soft: no brand pack resolvable → null, which makes provenance fall back
-// to "own-built" rather than guessing (provenance.js's documented behaviour).
-function ownProjectName() {
-  try { return require('../../src/branding').branding().identity.productName; } catch { return null; }
-}
-
-function pad(s, n) { return String(s == null ? '' : s).padEnd(n); }
-function clip(s, n) {
-  const v = String(s == null ? '' : s);
-  return v.length > n ? `${v.slice(0, n - 1)}…` : v;
-}
-
-// Pure renderer — every input arrives as a parameter (the tests pass catalog
-// rows straight in), so it touches no disk and no config.
-function formatCatalog(rows, { catalogOnly = false, query = '', core = null, delisted = new Set() } = {}) {
-  const scoped = catalogOnly ? catalog.catalogRows(rows) : rows;
-  const shown = catalog.searchCatalog(scoped, query);
-  const counts = catalog.summarize(rows);
-  const out = [];
-
-  out.push(catalogOnly
-    ? 'bongos module list --catalog — core modules this instance can enable (ADR 0107 §6: opt-in, default-off)'
-    : 'bongos module list — every module on disk, with author + origin credit (ADR 0107 §2)');
-  if (core) out.push(`  core (src/module-api.js CORE_VERSION): ${core}`);
-  out.push(`  ${counts.catalog} in the core catalog (${counts.catalog_enabled} enabled) · ${counts.instance} built here · ${counts.total} total`);
-  if (query) out.push(`  filter "${query}" — ${shown.length} match(es)`);
-  out.push('');
-
-  if (!shown.length) {
-    out.push(query ? '  no module matches that filter.' : '  no modules discovered.');
-    return out.join('\n');
-  }
-
-  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('CATEGORY', 28)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
-  for (const r of shown) {
-    const mark = r.enabled ? '[x]' : '[ ]';
-    // An inferred credit is marked so it never reads as something the author
-    // typed — the catalog's whole job is honest attribution (ADR 0107 §2).
-    const suffix = r.credit.inferred ? '*' : '';
-    const upkeep = ((r.maintenance && r.maintenance.status) || 'undeclared') + (delisted.has(r.key) ? ' · DELISTED' : '');
-    // The parent key, plus the sub-category once one is approved (ADR 0342).
-    const cat = r.category ? r.category.parent + (r.category.sub ? `/${r.category.sub}` : '') : '—';
-    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${pad(clip(cat, 27), 28)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
-  }
-  out.push('');
-  out.push('  [x] enabled here · [ ] available, not enabled');
-  if (shown.some((r) => delisted.has(r.key))) {
-    out.push('  DELISTED = taken out of the store: your copy keeps working, but no more versions will come.');
-  }
-  if (shown.some((r) => r.credit.inferred)) {
-    out.push(`  * credit not declared in module.json — shown as the platform (${catalog.CORE_PROJECT_NAME}), which ships it.`);
-  }
-  out.push('  enable one: add it to config/modules.json, or use the hall\'s Modules tab (Metic+).');
-  return out.join('\n');
-}
-
-// Which installed store modules the store has delisted (task 1003797). Only modules
-// built into this instance's tree can be store installs, so a core checkout asks
-// nothing. Fail-soft like the upgrade check: offline, or no session, lists as before.
-async function gatherDelisted(rows, { checkStore = gatherUpdates } = {}) {
-  const held = rows.filter((r) => r.source === 'instance');
-  if (!held.length) return new Set();
-  const found = await checkStore(held);
-  if (!found.checked) return new Set();
-  return new Set(Object.keys(found.latest).filter((k) => found.latest[k] && found.latest[k].status === 'delisted'));
-}
-
-async function cmdList(args, { log = console.log, errlog = console.error, gather = gatherCatalog, checkStore = gatherUpdates } = {}) {
-  const catalogOnly = args.includes('--catalog');
-  const json = args.includes('--json');
-  const sIdx = args.indexOf('--search');
-  const query = sIdx !== -1 ? (args[sIdx + 1] || '') : '';
-  if (sIdx !== -1 && (!args[sIdx + 1] || args[sIdx + 1].startsWith('--'))) {
-    errlog('usage: bongos module list [--catalog] [--search <text>] [--json]');
-    return 2;
-  }
-
-  let data;
-  try { data = gather(); }
-  catch (e) { errlog(`bongos module list: ${e.message}`); return 1; }
-
-  const delisted = await gatherDelisted(data.rows, { checkStore });
-
-  if (json) {
-    const scoped = catalogOnly ? catalog.catalogRows(data.rows) : data.rows;
-    const modules = catalog.searchCatalog(scoped, query).map((m) => ({ ...m, store_delisted: delisted.has(m.key) }));
-    log(JSON.stringify({ core: data.core, summary: catalog.summarize(data.rows), modules }, null, 2));
-    return 0;
-  }
-
-  log(formatCatalog(data.rows, { catalogOnly, query, core: data.core, delisted }));
-  for (const s of data.skipped) {
-    errlog(`  ! ${s.key}: not listed — ${s.reason}`);
-  }
-  for (const e of data.errors) errlog(`  ! ${e.dir}: ${(e.errors || []).join('; ')}`);
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// bongos module check <key> — ADR 0107 §4 upstreaming pre-check + DCO sign-off
-// ---------------------------------------------------------------------------
-
-// The DCO-style affirmation recorded on a pass. Deliberately NOT a
-// copyright-assignment CLA (ADR 0065 rejects relicensing-as-capture; ADR 0107
-// §4 "inbound = outbound") — the contributor affirms and RETAINS copyright.
-const DCO_STATEMENT =
-  'I affirm that this contribution is my own original work, or that I have the right to ' +
-  'submit it, and that I license it under AGPL-3.0. This is a Developer Certificate of ' +
-  'Origin-style affirmation, not a copyright-assignment CLA — I retain my copyright.';
-
-// Recursively list files under dir (skip VCS/dependency noise no module should ship).
-function listModuleFiles(dir) {
-  const out = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name === 'node_modules' || entry.name === '.git') continue;
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...listModuleFiles(full));
-    else out.push(full);
-  }
-  return out;
-}
-
-// Pure(ish) — reads modules/<key>/ off disk, no network. Returns
-// { key, ok, findings[], files[] }. findings are { kind, detail } — kind is
-// 'manifest' | 'license' | 'content'.
-function checkModulePublishability(key, { modulesDir = MODULES_DIR } = {}) {
-  const dir = path.join(modulesDir, key);
-  if (!fs.existsSync(dir)) {
-    throw new Error(`modules/${key} does not exist under ${path.relative(REPO_ROOT, modulesDir) || '.'}`);
-  }
-
-  const findings = [];
-  const manifestRaw = readJson(path.join(dir, 'module.json'));
-  if (!manifestRaw) {
-    findings.push({ kind: 'manifest', detail: 'module.json missing or unreadable' });
-  } else {
-    const { valid, errors } = validateManifest(manifestRaw);
-    if (!valid) findings.push({ kind: 'manifest', detail: `module.json invalid: ${errors.join('; ')}` });
-    const license = manifestRaw.license;
-    if (!license || !/^AGPL-3\.0/.test(license)) {
-      findings.push({
-        kind: 'license',
-        detail: `module.json license is ${license ? JSON.stringify(license) : 'unset'} — upstreaming requires ` +
-          'AGPL-3.0 (inbound = outbound, ADR 0107 §4)',
-      });
-    }
-
-    // ADR 0107 §7 / ADR 0166 — the maintenance gate. Acceptance into the shared
-    // catalog is a commitment to keep the module true as the core advances, so
-    // the module must SAY who is committing before it can be filed for review.
-    // The shape is already schema-validated above (a `maintained` module must
-    // name a maintainer; a sunset one must state its path); what this adds is
-    // that the block cannot simply be absent. Refusing here — at submit time —
-    // is what keeps the catalog from filling with entries nobody owns.
-    const maint = manifestRaw.maintenance;
-    if (!maint || !maint.status) {
-      findings.push({
-        kind: 'maintenance',
-        detail: 'module.json declares no `maintenance.status` — an upstreamed module must state its upkeep ' +
-          'posture (ADR 0107 §7): "core-maintained" (the core team owns it) or "maintained" with a named ' +
-          '`maintainer`. A module nobody owns rots silently as the core advances.',
-      });
-    } else if (SUNSET_STATUSES.includes(maint.status)) {
-      findings.push({
-        kind: 'maintenance',
-        detail: `module.json declares maintenance.status "${maint.status}" — a module already on its way out ` +
-          'cannot be submitted INTO the catalog. Upstream a maintained module, or its successor.',
-      });
-    }
-  }
-
-  // Classify every file AS IF it already lived at its canonical modules/<key>/
-  // path — this is what makes the check hermetically testable against a temp
-  // modulesDir while still reusing the REAL repo-wide denylist.
-  const files = listModuleFiles(dir)
-    .map((abs) => `modules/${key}/${path.relative(dir, abs).split(path.sep).join('/')}`)
-    .sort();
-  const denied = files.filter((f) => matchesDeny(f));
-  if (denied.length) {
-    findings.push({
-      kind: 'content',
-      detail: 'contains content the AGPL core publish boundary denies (game content, pixel art, ' +
-        `copyrighted reference material, or instance/topology secrets): ${denied.join(', ')}`,
-    });
-  }
-
-  return { key, ok: findings.length === 0, findings, files, denied };
-}
-
-// Records the sign-off ONLY once the content/license check has passed —
-// there is nothing to affirm over rejected content.
-function recordSignOff(key, signedBy, { modulesDir = MODULES_DIR } = {}) {
-  const dir = path.join(modulesDir, key);
-  const now = new Date().toISOString();
-  const record = { module: key, checkedAt: now, statement: DCO_STATEMENT, signOff: { signedBy, date: now } };
-  const file = path.join(dir, '.upstream-signoff.json');
-  fs.writeFileSync(file, JSON.stringify(record, null, 2) + '\n');
-  return { ...record, path: path.relative(REPO_ROOT, file) };
-}
-
-// Reads a previously-recorded sign-off (recordSignOff above), or null if the
-// module has never been signed off. Never throws on a missing/garbled file —
-// "no sign-off yet" is the expected common case, not an error.
-function readSignOff(key, { modulesDir = MODULES_DIR } = {}) {
-  return readJson(path.join(modulesDir, key, '.upstream-signoff.json'));
-}
-
-// ---------------------------------------------------------------------------
-// bongos module submit <key> — ADR 0107 §1 upstreaming submission
-// ---------------------------------------------------------------------------
-
-// Packages a module for the upstreaming queue: its manifest + a full file
-// snapshot (base64, so binary assets round-trip identically) + whatever
-// sign-off is on disk. Pure fs read — no pre-check, no network; the caller
-// (cmdSubmit locally, the POST /modules/:key/submit route server-side) is
-// responsible for having already run checkModulePublishability() and for
-// deciding whether a missing sign-off is fatal.
-function packageModuleForSubmission(key, { modulesDir = MODULES_DIR } = {}) {
-  const dir = path.join(modulesDir, key);
-  const manifest = readJson(path.join(dir, 'module.json'));
-  if (!manifest) throw new Error(`modules/${key}/module.json missing or unreadable`);
-  let totalBytes = 0;
-  const files = listModuleFiles(dir)
-    .map((abs) => {
-      const rel = path.relative(dir, abs).split(path.sep).join('/');
-      const buf = fs.readFileSync(abs);
-      totalBytes += buf.length;
-      return { path: rel, contentBase64: buf.toString('base64'), bytes: buf.length };
-    })
-    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-  const signOff = readSignOff(key, { modulesDir });
-  return { key, manifest, files, totalBytes, signOff };
-}
-
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-
-function cmdNew(args, { log = console.log, errlog = console.error } = {}) {
-  const key = args.find((a) => !a.startsWith('-'));
-  const force = args.includes('--force');
-  if (!key) {
-    errlog('usage: bongos module new <key>   (e.g. bongos module new economy)');
-    return 2;
-  }
-  let res;
-  try { res = scaffoldModule({ key, force }); }
-  catch (e) { errlog(`bongos module new: ${e.message}`); return 1; }
-
-  log(`Scaffolded module "${key}" at modules/${key}/ (no core edit needed):`);
-  for (const f of res.files) log(`  ✓ modules/${key}/${f}`);
-  const ENVKEY = key.toUpperCase().replace(/-/g, '_');
-  log('\nNext:');
-  log(`  • describe it   — edit modules/${key}/module.json (title + description)`);
-  log(`  • credit it     — fill in author/origin/maintainer in module.json (license defaults to AGPL-3.0)`);
-  log(`  • enable it     — add "${key}": true to config/modules.json (or set <PREFIX>_MODULE_${ENVKEY}=1)`);
-  log(`  • build it      — fill routes/${key}.js; add migrations/ + ui/ (see modules/${key}/CLAUDE.md)`);
-  log(`  • explain it    — fill in every section of modules/${key}/HOWTO.md (publish refuses it until you do)`);
-  log('  • verify        — bongos upgrade  (checks coreVersion compatibility)');
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// Available module updates — the store half of `bongos upgrade` (task 1003787)
-// ---------------------------------------------------------------------------
-
-// Ask the store for the newest version of every module here that carries an exact
-// version (the I/O half). A key the store does not know is absent from the answer,
-// so a module built here, or one the core ships, simply has nothing to report.
-// Never throws: no session or an unreachable store comes back as
-// { checked: false, reason }, because the compatibility pre-check must work
-// offline and must never fail on the store's account.
-async function gatherUpdates(rows, { request } = {}) {
-  const keys = rows.filter((r) => r.version && parseVersion(String(r.version))).map((r) => r.key);
-  if (!keys.length) return { checked: true, latest: {} };
-  let call;
-  try { call = request || storeRequest(); }
-  catch (e) { return { checked: false, reason: e.message }; }
-  let res;
-  try { res = await call('GET', `/store/modules/latest?keys=${keys.map(encodeURIComponent).join(',')}`); }
-  catch (e) { return { checked: false, reason: `the store could not be reached — ${e.message}` }; }
-  // A 404 here is a server whose core predates this route, not a missing module.
-  if (res.status === 404) return { checked: false, reason: "this server's store does not answer update checks yet (its core is older)" };
-  if (!res.ok) return { checked: false, reason: `the store answered ${storeError(res)}` };
-  return { checked: true, latest: (res.data && res.data.latest) || {} };
-}
-
-// Decide what is stale from rows + the store's answer (pure — tests drive it).
-// UPDATES = a module whose store version is newer than the one installed; `fits`
-// says whether that newer version can mount on this core (when it cannot, the
-// update waits for the core — it is not something to run now). DELISTED = an
-// installed module the store has delisted: it keeps working, but no further
-// versions will come (ADR 0338 D2). Neither ever blocks — an update is news, and
-// what blocks `bongos upgrade` is still only an incompatible ENABLED module.
-function evaluateUpdates(rows = [], latest = {}, core) {
-  const { satisfies } = require('../../src/module-loader/semver');
-  const updates = [];
-  const delisted = [];
-  for (const r of rows) {
-    const store = latest[r.key];
-    const have = r.version && parseVersion(String(r.version));
-    if (!store || !have) continue;
-    if (store.status === 'delisted') { delisted.push({ key: r.key, installed: r.version, enabled: r.enabled }); continue; }
-    const next = parseVersion(String(store.version));
-    if (!next || cmp(next, have) <= 0) continue;
-    let fits = false;
-    try { fits = !!(core && store.core_version && satisfies(core, store.core_version)); } catch { fits = false; }
-    updates.push({ key: r.key, installed: r.version, latest: store.version, coreVersion: store.core_version, enabled: r.enabled, fits });
-  }
-  return { updates, delisted };
-}
-
-function reportUpdates(found, verdict, { log, errlog }) {
-  log('\nModule updates (from the store):');
-  if (!found.checked) {
-    log(`  not checked — ${found.reason}. The compatibility check above still stands.`);
-    return;
-  }
-  const { updates, delisted } = evaluateUpdates(verdict.rows, found.latest, verdict.core);
-  for (const u of updates) {
-    const how = u.fits
-      ? `run \`bongos module update ${u.key}\``
-      : `needs core ${u.coreVersion}; this core is ${verdict.core}, so it waits until the core moves`;
-    log(`  ↑ ${u.key.padEnd(18)} ${u.installed} → ${u.latest}  — ${how}`);
-  }
-  for (const d of delisted) {
-    errlog(`  ! ${d.key.padEnd(18)} ${d.installed}  — delisted in the store: it keeps working, but no further versions will come`);
-  }
-  if (!updates.length && !delisted.length) log('  every installed store module is on its newest version.');
-}
-
-async function cmdUpgrade(args = [], { log = console.log, errlog = console.error, gather = gatherUpgrade, checkUpdates = gatherUpdates } = {}) {
-  const data = gather();
-  const verdict = evaluateUpgrade(data);
-
-  log('bongos upgrade — module compatibility pre-check');
-  log(`  core (src/module-api.js CORE_VERSION): ${verdict.core}`);
-
-  if (!verdict.rows.length && !data.errors.length) {
-    log('  no modules discovered under modules/ — nothing to check.');
-    return 0;
-  }
-  for (const r of verdict.rows) {
-    const mark = r.satisfied ? '✓' : (r.enabled ? '✗' : '!');
-    const state = r.enabled ? 'enabled' : 'disabled';
-    let note = '';
-    if (!r.satisfied) {
-      // A DISABLED mismatch is harmless to THIS boot, but it is not harmless to
-      // the catalog — it is a rotted entry with an owner who needs telling
-      // (ADR 0166). Name that owner right here rather than shrugging at it.
-      note = `  — coreVersion ${r.coreVersion || '(none)'} not satisfied by core ${verdict.core}` +
-        (r.enabled ? ' — will NOT mount' : ' — disabled, so it does not block this boot, but it is BROKEN if enabled') +
-        `\n      ↳ ${formatMaintenanceHint(r)}`;
-    }
-    log(`  ${mark} ${r.key.padEnd(18)} ${String(r.coreVersion || '').padEnd(10)} ${state}${note}`);
-  }
-  for (const e of data.errors) errlog(`  ! ${e.dir}: ${(e.errors || []).join('; ')}`);
-
-  // Deprecation roll-up (ADR 0166) — separate from compatibility: a module can
-  // satisfy the core perfectly and still be on its way out.
-  for (const d of verdict.deprecations) {
-    const overdue = verdict.expired.includes(d);
-    errlog(`  ${overdue ? '✗' : '!'} ${d.key}: ${d.maintenance.status}${overdue ? ` — PAST removeAfter ${d.maintenance.removeAfter} (core is ${verdict.core}); it is due for removal` : ''}`);
-    errlog(`      ↳ ${formatMaintenanceHint(d)}`);
-  }
-  if (verdict.undeclared.length) {
-    errlog(`  ! ${verdict.undeclared.length} module(s) declare no \`maintenance\` block — nobody is on the hook for them as the core advances (ADR 0166): ${verdict.undeclared.map((r) => r.key).join(', ')}`);
-  }
-
-  // What is stale here, beside what is broken: the store's newer versions of the
-  // modules installed from it. Reported either way, and it never changes the exit
-  // code. `--no-store` skips the read (offline, or a CI pre-check).
-  if (!args.includes('--no-store')) reportUpdates(await checkUpdates(verdict.rows), verdict, { log, errlog });
-
-  if (!verdict.ok) {
-    errlog(`\nREFUSING: ${verdict.blocking.length} enabled module(s) incompatible with core ${verdict.core}: ${verdict.blocking.map((b) => b.key).join(', ')}.`);
-    errlog(`Widen each module's coreVersion to a range that includes ${verdict.core} (or hold the core upgrade) before proceeding.`);
-    return 1;
-  }
-  log(`\nOK — every enabled module satisfies core ${verdict.core}.`);
-  return 0;
-}
-
-function cmdCheck(args, { log = console.log, errlog = console.error, check = checkModulePublishability, sign = recordSignOff, howtoCheck } = {}) {
-  const key = args.find((a) => !a.startsWith('-'));
-  if (!key) {
-    errlog('usage: bongos module check <key> [--sign-off "Name <email>"]');
-    return 2;
-  }
-  const signIdx = args.indexOf('--sign-off');
-  const signedBy = signIdx !== -1 ? args[signIdx + 1] : null;
-
-  let result;
-  try { result = check(key); }
-  catch (e) { errlog(`bongos module check: ${e.message}`); return 1; }
-
-  log(`bongos module check — upstreaming pre-check for "${key}"`);
-  if (result.ok) {
-    log('  ✓ AGPL/publish pre-check passed — no denied content, license is AGPL-3.0, upkeep is declared.');
-  } else {
-    for (const f of result.findings) errlog(`  ✗ ${f.kind}: ${f.detail}`);
-  }
-
-  // The store's how-to gate (ADR 0347 D4), reported here so an author learns early.
-  // Advisory only: it gates `bongos module publish`, never an upstream submit.
-  const { checkHowto, HOWTO_FILE } = require('./module-artifact');
-  const howto = (howtoCheck || ((k) => checkHowto(readText(path.join(MODULES_DIR, k, HOWTO_FILE)))))(key);
-  if (howto.ok) log(`  ✓ ${HOWTO_FILE} has every required section — ready for \`bongos module publish\`.`);
-  else for (const p of howto.problems) log(`  ! ${p} — needed before \`bongos module publish\` (not for an upstream submit)`);
-
-  if (!result.ok) {
-    errlog(`\nREFUSING: "${key}" is not clear to submit upstream. Fix the finding(s) above and re-run.`);
-    return 1;
-  }
-
-  if (signedBy) {
-    const record = sign(key, signedBy);
-    log(`\nSign-off recorded — ${record.path}`);
-    log(`  "${record.signOff.signedBy}", ${record.signOff.date}`);
-  } else {
-    log('\nNo --sign-off given — pass --sign-off "Name <email>" to affirm + record the DCO-style sign-off.');
-  }
-  return 0;
-}
-
-// `bongos module submit <key>` — ADR 0107 §1. Runs the §4 pre-check + requires
-// a sign-off (locally, for fast refusal without a network round trip), then
-// POSTs to POST /modules/:key/submit — the SAME route the hall "Modules" tab's
-// submit button calls (src/bongos/routes/modules.js). That route re-runs the
-// pre-check against ITS OWN on-disk copy of the module and is the authoritative
-// gate: a local pass here is a courtesy, not a guarantee, if the module's
-// changes aren't committed + shipped + deployed yet.
-async function cmdSubmit(args, {
-  log = console.log, errlog = console.error,
-  check = checkModulePublishability, sign = recordSignOff, readSign = readSignOff,
-  submit,
-} = {}) {
-  const key = args.find((a) => !a.startsWith('-'));
-  if (!key) {
-    errlog('usage: bongos module submit <key> [--sign-off "Name <email>"]');
-    return 2;
-  }
-  const signIdx = args.indexOf('--sign-off');
-  const signedBy = signIdx !== -1 ? args[signIdx + 1] : null;
-
-  log(`bongos module submit — upstreaming "${key}" (ADR 0107 §1)`);
-
-  let result;
-  try { result = check(key); }
-  catch (e) { errlog(`bongos module submit: ${e.message}`); return 1; }
-
-  if (!result.ok) {
-    for (const f of result.findings) errlog(`  ✗ ${f.kind}: ${f.detail}`);
-    errlog(`\nREFUSING: "${key}" is not clear to submit upstream. Fix the finding(s) above and re-run.`);
-    return 1;
-  }
-  log('  ✓ AGPL/publish pre-check passed.');
-
-  let signOff = readSign(key);
-  if (!signOff && signedBy) {
-    const record = sign(key, signedBy);
-    log(`  ✓ Sign-off recorded — ${record.path}`);
-    signOff = readSign(key);
-  }
-  if (!signOff) {
-    errlog(`\nREFUSING: no DCO-style sign-off on file for "${key}". Pass --sign-off "Name <email>" (or run \`bongos module check ${key} --sign-off "Name <email>"\` first).`);
-    return 1;
-  }
-  log(`  ✓ Sign-off on file — "${signOff.signOff.signedBy}", ${signOff.signOff.date}.`);
-
-  const doSubmit = submit || (async (k, body) => {
-    // Lazy require: cli-lib.js carries session/fetch plumbing that must NEVER
-    // load into the always-on server process — this file is also required by
-    // src/bongos/routes/modules.js for the pre-check it reuses. A real network
-    // call only happens when a human/agent actually invokes this CLI command.
-    const { cliClient, requireSession } = require('./cli-lib');
-    await requireSession();
-    const api = await cliClient();
-    return api.modules.postModulesKeySubmit({ key: k, body });
-  });
-
-  let res;
-  try { res = await doSubmit(key, { signed_by: signedBy || undefined }); }
-  catch (e) { errlog(`bongos module submit: request failed — ${e.message}`); return 1; }
-
-  if (!res.ok) {
-    const detail = (res.data && (res.data.message || res.data.error)) || JSON.stringify(res.data);
-    errlog(`\nREFUSING: the review queue rejected the submission (HTTP ${res.status}): ${detail}`);
-    if (res.status === 422) errlog('(the server re-runs the pre-check/sign-off check against its OWN deployed copy — commit + ship first if this module has local-only changes.)');
-    return 1;
-  }
-
-  const submission = res.data && res.data.submission;
-  log(`\n✓ Filed — submission id ${submission ? submission.id : '?'} for "${key}", status ${submission ? submission.status : 'pending'}.`);
-  log('Task 1771 (core-side review & accept flow) picks it up from here.');
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// bongos module publish <key> — put a module version in the store (ADR 0338 D1)
-// ---------------------------------------------------------------------------
-
-// `bongos module publish <key>` — task 1004271. Packs modules/<key>/ into the
-// store's tarball + hash manifest (scripts/gds/module-artifact.js — the core
-// release's own format, through the publish denylist), then uploads it to
-// POST /store/modules/:key/versions, which re-verifies every hash itself and
-// records the version. `--dry-run` packs and reports without uploading;
-// `--out <dir>` also writes the tarball and its side-car manifest there.
-// Distinct from `submit`, which proposes a module INTO core (ADR 0135).
-async function cmdPublish(args, {
-  log = console.log, errlog = console.error,
-  modulesDir = MODULES_DIR, pack, upload, writeFile = fs.writeFileSync,
-} = {}) {
-  const key = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--out');
-  if (!key) {
-    errlog('usage: bongos module publish <key> [--dry-run] [--out <dir>]');
-    return 2;
-  }
-  const dryRun = args.includes('--dry-run');
-  const outIdx = args.indexOf('--out');
-  const outDir = outIdx !== -1 ? args[outIdx + 1] : null;
-  if (outIdx !== -1 && (!outDir || outDir.startsWith('--'))) {
-    errlog('usage: bongos module publish <key> [--dry-run] [--out <dir>]');
-    return 2;
-  }
-
-  const artifact = require('./module-artifact');
-  let packed;
-  try { packed = (pack || ((k) => artifact.packModule(k, { modulesDir })))(key); }
-  catch (e) { errlog(`REFUSING: ${e.message}`); return 1; }
-  const { tgz, sidecar } = packed;
-  log(`bongos module publish — "${key}" ${sidecar.module_version} (needs core ${sidecar.core_version})`);
-  // The how-to gate (ADR 0347 D4) — the same checker the store re-runs on upload.
-  const howto = artifact.checkHowto(readText(path.join(modulesDir, key, artifact.HOWTO_FILE)));
-  if (!howto.ok) {
-    for (const p of howto.problems) errlog(`  ✗ ${p}`);
-    errlog(`REFUSING: "${key}" needs a complete ${artifact.HOWTO_FILE} before it can be published — fill in the section(s) above.`);
-    return 1;
-  }
-  log(`  ✓ ${artifact.HOWTO_FILE} has all ${artifact.HOWTO_SECTIONS.length} required sections`);
-  log(`  ✓ packed ${sidecar.file_count} file(s), ${tgz.length} bytes — tree ${sidecar.tree_sha256.slice(0, 12)}…`);
-  if (tgz.length > artifact.MAX_TARBALL_BYTES) {
-    errlog(`REFUSING: the tarball is ${tgz.length} bytes, over the store's ${artifact.MAX_TARBALL_BYTES}-byte cap.`);
-    return 1;
-  }
-
-  if (outDir) {
-    fs.mkdirSync(outDir, { recursive: true });
-    const tgzPath = path.join(outDir, sidecar.tarball.name);
-    writeFile(tgzPath, tgz);
-    writeFile(tgzPath.replace(/\.tgz$/, '.manifest.json'), JSON.stringify(sidecar, null, 2) + '\n');
-    log(`  ✓ wrote ${tgzPath} (+ .manifest.json)`);
-  }
-  if (dryRun) {
-    log('\n--dry-run: nothing uploaded.');
-    return 0;
-  }
-
-  const doUpload = upload || (async (k, body) => {
-    // Lazy require — the same reason cmdSubmit gives: this file loads in the server
-    // process too, and cli-lib's session/fetch plumbing must never come with it.
-    const { readSessionToken, dispatchedFetch, noKeepAliveDispatcher, CLI_USER_AGENT } = require('./cli-lib');
-    const session = readSessionToken();
-    if (!session) throw new Error('no Bongos session — run `bongos setup` first');
-    const res = await dispatchedFetch(`${session.apiBase}/api/bongos/store/modules/${encodeURIComponent(k)}/versions`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/gzip', Authorization: `Bearer ${session.token}`, 'User-Agent': CLI_USER_AGENT },
-      body,
-      dispatcher: noKeepAliveDispatcher(),
-    });
-    const text = await res.text();
-    let data;
-    try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
-    return { status: res.status, ok: res.ok, data };
-  });
-
-  let res;
-  try { res = await doUpload(key, tgz); }
-  catch (e) { errlog(`bongos module publish: upload failed — ${e.message}`); return 1; }
-  if (!res.ok) {
-    const err = res.data && (res.data.error || res.data);
-    const detail = (err && (err.message || err.code)) || JSON.stringify(res.data);
-    errlog(`\nREFUSING: the store rejected "${key}" ${sidecar.module_version} (HTTP ${res.status}): ${detail}`);
-    return 1;
-  }
-  const row = res.data && res.data.version;
-  log(`\n✓ Published "${key}" ${row ? row.version : sidecar.module_version} to the store${res.data && res.data.created_module ? ' — its first version, so you are its author' : ''}.`);
-  if (res.data && res.data.channel === 'tester') {
-    log('  It goes to testing projects first, and reaches every project once it has been tested (ADR 0344).');
-  }
-  return 0;
-}
-
-// ---------------------------------------------------------------------------
-// bongos module install <key> — acquire a module from the store (ADR 0338 D1)
-// ---------------------------------------------------------------------------
-
-// The store half of the CLI, over three calls (src/bongos/routes/modules.js):
-// acquire (take the entitlement, learn the version), download the tarball, and
-// once the files are placed, record the version acquired. Injected in tests.
-function storeRequest() {
-  // Lazy require — cli-lib's session/fetch plumbing must never load in the server
-  // process, which requires this file too (the same reason cmdPublish gives).
-  const { readSessionToken, dispatchedFetch, noKeepAliveDispatcher, CLI_USER_AGENT } = require('./cli-lib');
-  const session = readSessionToken();
-  if (!session) throw new Error('no Bongos session — run `bongos setup` first');
-  const call = async (method, urlPath, { json, binary = false } = {}) => {
-    const res = await dispatchedFetch(`${session.apiBase}/api/bongos${urlPath}`, {
-      method,
-      headers: {
-        Authorization: `Bearer ${session.token}`, 'User-Agent': CLI_USER_AGENT,
-        ...(json ? { 'Content-Type': 'application/json' } : {}),
-      },
-      body: json ? JSON.stringify(json) : undefined,
-      dispatcher: noKeepAliveDispatcher(),
-    });
-    if (binary && res.ok) return { ok: true, status: res.status, buf: Buffer.from(await res.arrayBuffer()) };
-    const text = await res.text();
-    let data;
-    try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
-    return { ok: res.ok, status: res.status, data };
-  };
-  // Where the store lives, so install can print a full link to the how-to page.
-  call.apiBase = session.apiBase;
-  return call;
-}
-
-// The hall page that shows a version's HOWTO.md (task 1004366) — the Modules tab,
-// opened on one version. null when the version shipped without one (published
-// before ADR 0347's gate), so install never prints a link that would 404.
-function howtoLink(key, version, files, apiBase) {
-  if (!files.some((f) => f.path === 'HOWTO.md')) return null;
-  const p = `/builders/modules?howto=${encodeURIComponent(key)}&version=${encodeURIComponent(version)}`;
-  return apiBase ? `${String(apiBase).replace(/\/+$/, '')}${p}` : p;
-}
-
-function storeError(res) {
-  const err = res.data && (res.data.error || res.data);
-  return (err && (err.message || err.code)) || `HTTP ${res.status}`;
-}
-
-// Where install places a module: the INSTANCE's own modules/ root (ADR 0108 §1),
-// which the loader discovers. In a single checkout that is this repo's modules/.
-function instanceModulesDir() {
-  return path.join(require('../../src/instance-config').resolveInstanceRoot(), 'modules');
-}
-
-// Write the verified files into a private staging dir beside the target, then
-// rename it into place, so a crash leaves a staging dir to delete, never a
-// half-written module the loader would try to mount.
-function placeModule(files, target) {
-  const staging = `${target}.installing-${process.pid}-${Date.now()}`;
-  fs.mkdirSync(staging, { recursive: true });
-  try {
-    for (const f of files) {
-      const dest = path.join(staging, ...f.path.split('/'));
-      if (!dest.startsWith(staging + path.sep)) throw new Error(`"${f.path}" would land outside the module`);
-      fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.writeFileSync(dest, f.buf, { mode: parseInt(f.mode, 8) || 0o644 });
-    }
-    fs.renameSync(staging, target);
-  } catch (e) {
-    fs.rmSync(staging, { recursive: true, force: true });
-    throw e;
-  }
-}
-
-// Every discovery root the loader scans (core + instance, ADR 0108 §1). A key on
-// disk in ANY of them is already taken: the loader treats a repeated key as a hard
-// error, so placing a second copy in the instance root would break boot.
-function discoveryRoots() {
-  return require('../../src/module-loader/loader').DEFAULT_ROOTS;
-}
-
-// Parse `<key> [--version X.Y.Z]` for install and update. Returns { key, wanted }
-// or { code } (2 = usage) after printing why.
-function parseStoreArgs(args, verb, errlog) {
-  const usage = `usage: bongos module ${verb} <key> [--version X.Y.Z]`;
-  const vIdx = args.indexOf('--version');
-  const wanted = vIdx !== -1 ? args[vIdx + 1] : null;
-  const key = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '--version');
-  if (!key || (vIdx !== -1 && (!wanted || wanted.startsWith('--')))) { errlog(usage); return { code: 2 }; }
-  if (!KEY_RE.test(key)) { errlog(`REFUSING: "${key}" is not a module key (lowercase kebab-case).`); return { code: 2 }; }
-  const { parseVersion } = require('../../src/module-loader/semver');
-  if (wanted && !parseVersion(wanted)) { errlog(`REFUSING: --version must be exact X.Y.Z, not "${wanted}".`); return { code: 2 }; }
-  return { key, wanted };
-}
-
-// The one acquisition path install AND update share (task 1003786): acquire, check
-// the version can mount on this core, download, verify with verifyModuleArtifact and
-// hold the bytes to what the store described. Nothing here reads a price or branches
-// on how the module was obtained — the store decides entitlement, and a holder it has
-// already granted (for any reason) is never asked again. tests/module_update.mjs
-// fails if a price-conditional branch appears in this path.
-//
-// `shouldDownload(described)` lets update stop before the download when the store's
-// version is not newer than what is installed. Resolves { ok, described, verified }
-// or { ok: false, code, upToDate? } after printing why.
-async function fetchVerified(key, { wanted, call, core, log, errlog, verb, shouldDownload = () => true }) {
-  const fail = (code, msg) => { if (msg) errlog(msg); return { ok: false, code }; };
-  const enc = encodeURIComponent(key);
-  let acq;
-  try { acq = await call('POST', `/store/modules/${enc}/acquire`, { json: wanted ? { version: wanted } : {} }); }
-  catch (e) { return fail(1, `bongos module ${verb}: the store could not be reached — ${e.message}`); }
-  if (!acq.ok) return fail(1, `REFUSING: the store would not hand over "${key}" (HTTP ${acq.status}): ${storeError(acq)}`);
-  const described = acq.data;
-  log(`bongos module ${verb} — "${key}" ${described.version} (needs core ${described.core_version})`);
-
-  const stop = shouldDownload(described);
-  if (stop !== true) return { ok: false, code: stop.code, upToDate: stop.upToDate };
-
-  const { satisfies } = require('../../src/module-loader/semver');
-  const coreV = core || require('../../src/module-api').CORE_VERSION;
-  if (!satisfies(coreV, described.core_version)) {
-    return fail(1, `REFUSING: "${key}" ${described.version} needs core ${described.core_version}; this core is ${coreV}, so it could not mount.`);
-  }
-
-  let dl;
-  try { dl = await call('GET', `/store/modules/${enc}/versions/${encodeURIComponent(described.version)}/tarball`, { binary: true }); }
-  catch (e) { return fail(1, `bongos module ${verb}: download failed — ${e.message}`); }
-  if (!dl.ok) return fail(1, `REFUSING: the download was refused (HTTP ${dl.status}): ${storeError(dl)}`);
-
-  const artifact = require('./module-artifact');
-  const verified = await artifact.verifyModuleArtifact(dl.buf, { key, includeFiles: true });
-  if (!verified.ok) {
-    await reportInstall(call, key, described.version, 'verify_failed');
-    return fail(1, `REFUSING: the downloaded tarball failed verification (${verified.code}): ${verified.message}`);
-  }
-  if (verified.version !== described.version || verified.tarballSha256 !== described.tarball_sha256 || verified.treeSha256 !== described.tree_sha256) {
-    await reportInstall(call, key, described.version, 'hash_mismatch');
-    return fail(1, `REFUSING: the download is not the ${described.version} the store described (version or hash differs).`);
-  }
-  log(`  ✓ verified ${verified.files.length} file(s), ${verified.bytes} bytes — tree ${verified.treeSha256.slice(0, 12)}…`);
-  return { ok: true, described, verified };
-}
-
-// Tell the store whether an install or update of this exact version worked (task
-// 1003793): it feeds the module's Install score, the part an author cannot fake.
-// Counts only — yes, or a short code saying where it failed; never a message, a
-// path or anything about this machine (owner's privacy posture, 2026-10-01). The
-// store drops it if the caller switched reporting off in Settings, so there is no
-// client-side switch to keep in step. Best-effort and silent: a report that does
-// not arrive changes nothing about the install. Only failures that are the
-// module's own count: a refused or unreachable store, or a core the module does
-// not support, says nothing about the module and is not reported.
-async function reportInstall(call, key, version, errorCode = null) {
-  const body = errorCode ? { ok: false, error_code: errorCode } : { ok: true };
-  try {
-    await call('POST', `/store/modules/${encodeURIComponent(key)}/versions/${encodeURIComponent(version)}/install-report`, { json: body });
-  } catch { /* best-effort */ }
-}
-
-// Tell the store which exact version was placed. A failure here never undoes the
-// placement: the files are good, and the next install or update records it.
-async function recordPlaced(key, version, { call, errlog, verb }) {
-  let rec;
-  try { rec = await call('POST', `/store/modules/${encodeURIComponent(key)}/acquired`, { json: { version } }); }
-  catch (e) { rec = { ok: false, status: 0, data: { error: { message: e.message } } }; }
-  if (!rec.ok) {
-    errlog(`WARNING: "${key}" is ${verb === 'update' ? 'updated' : 'installed'}, but the store did not record the version (${storeError(rec)}). Nothing is lost; the next install or update records it.`);
-    return false;
-  }
-  return true;
-}
-
-// `bongos module install <key> [--version X.Y.Z]` — task 1003785. Acquires the
-// module (a free one is granted on the spot; a priced one waits on the buy action,
-// area 8), downloads its tarball, verifies it with verifyModuleArtifact — the one
-// checker the store itself uses on publish — and places it under the instance's
-// modules/. It never enables: the loader discovers what is on disk and the hall's
-// Modules tab decides what mounts. A key already on disk in ANY discovery root is
-// refused; moving an installed module to a newer version is `update` (task 1003786).
-async function cmdInstall(args, {
-  log = console.log, errlog = console.error,
-  modulesDir, roots, request, core,
-} = {}) {
-  const parsed = parseStoreArgs(args, 'install', errlog);
-  if (parsed.code) return parsed.code;
-  const { key, wanted } = parsed;
-
-  const dir = modulesDir || instanceModulesDir();
-  const target = path.join(dir, key);
-  const taken = [dir, ...(roots || discoveryRoots())].map((r) => path.join(r, key)).find((p) => fs.existsSync(p));
-  if (taken) {
-    errlog(`REFUSING: "${key}" is already on disk at ${taken}. Install only adds a new module; to move an installed one forward, run \`bongos module update ${key}\`.`);
-    return 1;
-  }
-
-  let call;
-  try { call = request || storeRequest(); }
-  catch (e) { errlog(`bongos module install: ${e.message}`); return 1; }
-
-  const got = await fetchVerified(key, { wanted, call, core, log, errlog, verb: 'install' });
-  if (!got.ok) return got.code;
-
-  try { placeModule(got.verified.files, target); }
-  catch (e) { await reportInstall(call, key, got.described.version, 'place_failed'); errlog(`bongos module install: could not place the module — ${e.message}`); return 1; }
-  log(`  ✓ placed at ${target}`);
-
-  const recorded = await recordPlaced(key, got.described.version, { call, errlog, verb: 'install' });
-  await reportInstall(call, key, got.described.version);
-  if (!recorded) return 1;
-  log(`\n✓ Installed "${key}" ${got.described.version}. It is not switched on: enable it from the hall's Modules tab when you want it.`);
-  const howto = howtoLink(key, got.described.version, got.verified.files, call.apiBase);
-  if (howto) log(`  How to use it: ${howto}`);
-  return 0;
-}
-
-// Replace an installed module's directory with a verified new one. The new files
-// are written to a staging dir first; the old dir is moved aside, the new one moved
-// in, and only then is the old one removed — so a failure at any step leaves the
-// previous version in place, never a half-written or missing module.
-function replaceModule(files, target) {
-  const aside = `${target}.previous-${process.pid}-${Date.now()}`;
-  const staging = `${target}.installing-${process.pid}-${Date.now()}`;
-  placeModule(files, staging);
-  try {
-    fs.renameSync(target, aside);
-  } catch (e) {
-    fs.rmSync(staging, { recursive: true, force: true });
-    throw e;
-  }
-  try {
-    fs.renameSync(staging, target);
-  } catch (e) {
-    fs.renameSync(aside, target);
-    fs.rmSync(staging, { recursive: true, force: true });
-    throw e;
-  }
-  fs.rmSync(aside, { recursive: true, force: true });
-}
-
-// `bongos module update <key> [--version X.Y.Z]` — task 1003786. Moves an installed
-// store module forward, through exactly the acquisition path install uses
-// (fetchVerified): the same calls whether the module was free or paid, and a module
-// the caller already holds is never charged again (the store's acquire route only
-// looks at price for a caller with no entitlement). Only forward: with no --version
-// it takes the newest, and says so without downloading when that is not newer; an
-// older --version is refused, since rolling back is a different act. Like install it
-// never enables or disables — the module keeps whatever switch it had.
-async function cmdUpdate(args, {
-  log = console.log, errlog = console.error,
-  modulesDir, roots, request, core,
-} = {}) {
-  const parsed = parseStoreArgs(args, 'update', errlog);
-  if (parsed.code) return parsed.code;
-  const { key, wanted } = parsed;
-
-  const dir = modulesDir || instanceModulesDir();
-  const target = path.join(dir, key);
-  if (!fs.existsSync(path.join(target, 'module.json'))) {
-    const bundled = (roots || discoveryRoots()).map((r) => path.join(r, key)).find((p) => p !== target && fs.existsSync(p));
-    errlog(bundled
-      ? `REFUSING: "${key}" at ${bundled} comes with the core, not the store. It updates when the core does (\`bongos upgrade\`).`
-      : `REFUSING: "${key}" is not installed here. Run \`bongos module install ${key}\` first.`);
-    return 1;
-  }
-  const { parseVersion, cmp } = require('../../src/module-loader/semver');
-  let installed;
-  try { installed = JSON.parse(fs.readFileSync(path.join(target, 'module.json'), 'utf8')).version; }
-  catch (e) { errlog(`REFUSING: could not read the installed ${key}/module.json — ${e.message}`); return 1; }
-  const have = parseVersion(String(installed));
-  if (!have) { errlog(`REFUSING: the installed "${key}" has no exact version in module.json, so there is nothing to compare against.`); return 1; }
-  if (wanted && cmp(parseVersion(wanted), have) < 0) {
-    errlog(`REFUSING: ${wanted} is older than the installed ${installed}. Update only moves forward.`);
-    return 1;
-  }
-
-  let call;
-  try { call = request || storeRequest(); }
-  catch (e) { errlog(`bongos module update: ${e.message}`); return 1; }
-
-  const got = await fetchVerified(key, {
-    wanted, call, core, log, errlog, verb: 'update',
-    shouldDownload: (d) => {
-      const next = parseVersion(String(d.version));
-      if (next && cmp(next, have) > 0) return true;
-      log(`\n✓ "${key}" is up to date at ${installed}.`);
-      return { code: 0, upToDate: true };
-    },
-  });
-  if (!got.ok) return got.code;
-
-  try { replaceModule(got.verified.files, target); }
-  catch (e) { await reportInstall(call, key, got.described.version, 'place_failed'); errlog(`bongos module update: could not replace the module, ${installed} is still in place — ${e.message}`); return 1; }
-  log(`  ✓ replaced ${installed} with ${got.described.version} at ${target}`);
-
-  const recorded = await recordPlaced(key, got.described.version, { call, errlog, verb: 'update' });
-  await reportInstall(call, key, got.described.version);
-  if (!recorded) return 1;
-  log(`\n✓ Updated "${key}" ${installed} → ${got.described.version}. Its on/off switch is unchanged.`);
-  return 0;
-}
-
-function printHelp(out = console.log) {
-  out('bongos module — scaffold + manage Cloud Bongos modules\n');
-  out('Usage:');
-  out('  bongos module new <key>     Scaffold modules/<key>/ (manifest + skeleton + sample route + HOWTO.md + CLAUDE.md)');
-  out('  bongos module list [--catalog] [--search <text>] [--json]');
-  out('                              Browse the module catalog — what you can enable, with author + origin credit');
-  out('  bongos upgrade [--no-store] Pre-check enabled modules against the core version (fail-closed),');
-  out('                              then list newer store versions of installed modules (never blocks)');
-  out('  bongos module check <key> [--sign-off "Name <email>"]');
-  out('                              AGPL/publish pre-check before upstreaming + record a DCO-style sign-off');
-  out('  bongos module submit <key> [--sign-off "Name <email>"]');
-  out('                              Pre-check + sign-off, then file into the rank-gated upstreaming review queue');
-  out('  bongos module publish <key> [--dry-run] [--out <dir>]');
-  out('                              Pack a module version (tarball + hash manifest) and upload it to the module store');
-  out('  bongos module install <key> [--version X.Y.Z]');
-  out('                              Acquire a module from the store, verify it and place it under modules/ (not enabled)');
-  out('  bongos module update <key> [--version X.Y.Z]');
-  out('                              Move an installed store module to a newer version (same path, paid or free)');
-}
-
-async function main(argv) {
-  const args = argv.slice(2);
-  const sub = args[0];
-  if (sub === 'new') return cmdNew(args.slice(1));
-  if (sub === 'list' || sub === 'ls') return cmdList(args.slice(1));
-  if (sub === 'upgrade') return cmdUpgrade(args.slice(1));
-  if (sub === 'check') return cmdCheck(args.slice(1));
-  if (sub === 'submit') return cmdSubmit(args.slice(1));
-  if (sub === 'publish') return cmdPublish(args.slice(1));
-  if (sub === 'install') return cmdInstall(args.slice(1));
-  if (sub === 'update') return cmdUpdate(args.slice(1));
-  if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
-    printHelp();
-    return sub ? 0 : 2;
-  }
-  console.error(`bongos module: unknown subcommand "${sub}"`);
-  printHelp(console.error);
-  return 2;
-}
-
-module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
-  storeRequest,
-  gatherCatalog, formatCatalog, ownProjectName,
-  scaffoldModule, gatherUpgrade, evaluateUpgrade, gatherUpdates, evaluateUpdates, buildManifest,
-  formatMaintenanceHint, isPastRemoveAfter,
-  checkModulePublishability, recordSignOff, readSignOff, DCO_STATEMENT,
-  listModuleFiles, packageModuleForSubmission,
-  routeTemplate, claudeMdTemplate, titleize, camel, coreVersion,
-  MODULES_DIR,
-};
-
-if (require.main === module) {
-  // Set the exit code and drain, never a hard exit: install, update and upgrade end
-  // after a store request, and a hard exit there aborts natively on Windows + Node 24
-  // (task 1002734).
-  Promise.resolve(main(process.argv)).then(
-    (code) => { process.exitCode = code; },
-    (e) => { console.error(e); process.exit(1); }
-  );
-}
+require('../bongos/forwarder.js').forward(module, 'module.js');