@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/module.js

@@ -0,0 +1,1376 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/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/bongos/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/bongos/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); }
+  );
+}