@bongos/core 1.19.1072 → 1.19.1074

package/scripts/gds/local-preview-lib.js

@@ -1,15 +1,13 @@
 // scripts/gds/local-preview-lib.js — core of the LOCAL sandbox launcher (task 1056).
 //
-// Gives a builder working on a LOCAL full clone (laptop) the same private game
-// preview a dev box gets at sandbox-<login>.example.com (ADR 0044/0046/0052)
-// — but served at http://localhost:<port> on their OWN machine: no Cloudflare
-// tunnel, no public URL, $0. It runs the ADR 0052 game-only entry
-// (src/preview-server.js), which serves ONLY the playable game (no /api/bongos, no
-// BuildersHall), degraded-DB exactly like the box sandbox.
+// Gives a builder working on a LOCAL full clone a private game preview (ADR
+// 0044/0046/0052) served at http://localhost:<port> on their OWN machine: no
+// public URL, $0. It runs the ADR 0052 game-only entry (src/preview-server.js),
+// which serves ONLY the playable game (no /api/bongos, no BuildersHall),
+// degraded-DB.
 //
-// The preview is a long-running DETACHED background process (the laptop analogue
-// of the box's box-game-preview.service systemd unit). The edit loop mirrors the
-// box: edit -> restart -> refresh the browser tab.
+// The preview is a long-running DETACHED background process. The edit loop is:
+// edit -> restart -> refresh the browser tab.
 //
 // Everything is pure + injectable (deps.fs / deps.spawn / deps.kill /
 // deps.fetchImpl / deps.env / deps.*Path) so tests/local_preview.mjs can exercise
@@ -25,18 +23,6 @@ const path = require('node:path');
 const DEFAULT_PORT = 3100;
 const HOST = '127.0.0.1';
 
-// Box-only markers (ADR 0031/0044). ANY one ⇒ this is a provisioned dev box, NOT
-// a laptop. Deliberately broader than /etc/otb/box.env alone: a box whose box.env
-// was lost or is unreadable must still be recognized as a box, never mistaken for
-// a laptop — because the laptop path hands back a http://localhost preview URL,
-// which is unreachable from the builder's own browser when the server is on a
-// remote box (the task-1443 footgun: "the link is giving me localhost"). box.env
-// is the canonical marker; box-preview (the preview control command) and the
-// box-game-preview.service unit are written on every box and survive an
-// unreadable/empty box.env, so they're the resilient backstops.
-const BOX_ENV_PATH = '/etc/otb/box.env';
-const BOX_PREVIEW_WRAPPER = '/usr/local/bin/box-preview';
-const BOX_SERVICE_UNIT = '/etc/systemd/system/box-game-preview.service';
 // scripts/gds/ -> repo root. Absolute + cwd-independent so staging works no
 // matter where ship.js is invoked from.
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -62,22 +48,6 @@ function hasGameEntry(deps = {}) {
   return f.existsSync(previewEntry(deps));
 }
 
-// Is this a provisioned dev box (ADR 0031/0044), i.e. NOT a laptop? True if any
-// box-only marker is present. Pure + injectable (deps.fs + per-marker path
-// overrides) like everything else here, and honors the dep names sandbox-stage.js
-// already injects (deps.boxEnvPath / deps.previewWrapper) so a single call site
-// drives both. Used to keep the localhost local-preview path from EVER being
-// chosen on a box — see the BOX_* marker note above (task 1443).
-function onBox(deps = {}) {
-  const f = deps.fs || fs;
-  const markers = [
-    deps.boxEnvPath || BOX_ENV_PATH,
-    deps.previewWrapper || BOX_PREVIEW_WRAPPER,
-    deps.boxServiceUnit || BOX_SERVICE_UNIT,
-  ];
-  return markers.some((p) => { try { return f.existsSync(p); } catch { return false; } });
-}
-
 function readPid(deps = {}) {
   const f = deps.fs || fs;
   try {
@@ -152,8 +122,7 @@ async function health(deps = {}) {
 
 module.exports = {
   DEFAULT_PORT, HOST, REPO_ROOT,
-  BOX_ENV_PATH, BOX_PREVIEW_WRAPPER, BOX_SERVICE_UNIT,
   previewPort, localUrl, healthUrl, previewEntry, pidPath, logPath,
-  hasGameEntry, onBox, readPid, pidAlive, isRunning,
+  hasGameEntry, readPid, pidAlive, isRunning,
   start, stop, restart, health,
 };

package/scripts/gds/local-preview.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // scripts/gds/local-preview.js — the builder's control for the LOCAL game
-// preview (task 1056), the laptop analogue of `box-preview` (ADR 0044) on a dev
-// box. Runs the ADR 0052 game-only entry privately at http://localhost:<port>.
+// preview (task 1056, ADR 0044). Runs the ADR 0052 game-only entry privately at
+// http://localhost:<port>.
 //
 //   npm run preview                          # start it (then open the URL)
 //   node scripts/gds/local-preview.js status   is it up + the URL          (default)
@@ -27,21 +27,8 @@ async function pollHealthy(ms = 20_000) {
 
 const HINT = `Open ${lib.localUrl()} — your PRIVATE copy of the game (degraded DB, nothing shipped).`;
 
-// This launcher is the LAPTOP analogue of box-preview. On a dev box it's the
-// wrong tool: it binds http://localhost, which the builder's browser can't reach
-// when the server is on a remote box — the "the link is giving me localhost"
-// footgun (task 1443). Warn loudly and point at the box's HOSTED sandbox; warn,
-// don't hard-fail, so an operator who really wants a box-local loopback still can.
-function warnIfOnBox() {
-  if (!lib.onBox()) return;
-  console.error('⚠ You appear to be on a dev box. This LOCAL preview binds http://localhost —');
-  console.error('  your browser cannot reach the box\'s localhost. Your sandbox is the HOSTED url:');
-  console.error('  run  /builder-stage  (or  box-preview status )  to get https://sandbox-<login>.<host> and refresh that tab.');
-}
-
 (async () => {
   const cmd = process.argv[2] || 'status';
-  if (cmd === 'start' || cmd === 'restart' || cmd === 'status' || cmd === 'url') warnIfOnBox();
   switch (cmd) {
     case 'start': {
       const r = lib.start();

package/scripts/gds/migration-namespace.js

@@ -14,7 +14,7 @@
 // DISCIPLINE. Every migration SOURCE owns a distinct filename namespace, so stems can
 // never collide across sources and each source's allocator counts only its own numbers:
 //   • CORE      (the @bongos/core package's  migrations/*.sql)        → core_NNN_slug.sql
-//   • MODULE    (modules/<key>/migrations/*.sql)                           → <key>_NNN_slug.sql   (key: dev-box → dev_box_)
+//   • MODULE    (modules/<key>/migrations/*.sql)                           → <key>_NNN_slug.sql   (key: art-pipeline → art_pipeline_)
 //   • INSTANCE  (the host repo's                   migrations/instance/*.sql) → NNN_slug.sql        (BARE — the instance owns the bare namespace)
 //
 // The core prefix ALONE is enough to break stem-equality with a bare instance file
@@ -42,7 +42,7 @@ const INSTANCE_NS = 'instance';
 // Reserved namespace words a module key may not be (they name the core/instance sources).
 const RESERVED_NS = new Set([CORE_NS, INSTANCE_NS]);
 
-// SQL/filename-safe namespace prefix for a module key: dev-box → dev_box (matches
+// SQL/filename-safe namespace prefix for a module key: art-pipeline → art_pipeline (matches
 // fitness.js moduleNamespace + the existing economy_/lifecycle_ files).
 function sqlNamespace(moduleKey) {
   return String(moduleKey == null ? '' : moduleKey).replace(/-/g, '_');
@@ -70,7 +70,7 @@ const RENAMED_MODULE_PREFIXES = { government: new Set(['governance']) };
 
 const BARE_RE = /^(\d{3,})_(.+)\.sql$/;
 // A prefix is a lowercase word (letters/digits/underscores) starting with a letter,
-// then `_NNN_`. Lazy so `dev_box_003_x` splits as prefix=dev_box, num=003 (not dev/box).
+// then `_NNN_`. Lazy so `art_pipeline_003_x` splits as prefix=art_pipeline, num=003 (not art/pipeline).
 const PREFIXED_RE = /^([a-z][a-z0-9_]*?)_(\d{3,})_(.+)\.sql$/;
 
 // Parse a migration basename into { prefix, number, slug, bare, ok }. A non-migration

package/scripts/gds/module-artifact.js

@@ -0,0 +1,212 @@
+// scripts/gds/module-artifact.js — pack and verify ONE module version for the
+// Bongos-hosted module store (task 1004271, ADR 0338 D1).
+//
+// ADR 0338 settled "no second packaging format": a module version is a tarball plus a
+// hash manifest in exactly the shape package-core.js emits for the core — per-file
+// sha256, a compression-independent tree_sha256, a deterministic ustar+gzip — so the
+// tar writer, reader and tree pin all come from artifact-format.js, the file the core
+// release builds with. What differs is only WHAT is packed and what the manifest names:
+//
+//   tarball   package/<path inside modules/<key>/>   (module.json at package/module.json)
+//             package/.bongos-module.json            the inner manifest (below)
+//   manifest  { artifact: 'bongos-module', manifest_schema, generator, module_key,
+//               module_version, core_version, built_at, file_count, tree_sha256,
+//               files: [{ path, mode, sha256 }] }
+//   side-car  the same manifest + { tarball: { name, sha256, bytes } } (withTarballInfo)
+//
+// THE GATE. The core's isPublishable() is default-deny: a path ships only if the
+// allowlist names it and the denylist does not. The allowlist names the CORE's own
+// modules, so for a store module the allow side is "inside this module's own
+// modules/<key>/ directory" and the deny side is the SAME repo-wide denylist
+// (matchesDeny — game content, pixel art, copyrighted references, instance topology,
+// secrets), plus credential-named files anywhere in the module (SECRET_FILE_RE). Anything the denylist catches refuses the whole publish rather than being
+// silently dropped: a module that ships without a file it expected is a broken module.
+//
+// Both halves live here so the CLI (packModule) and the store route
+// (verifyModuleArtifact) cannot disagree about the format. Pure apart from reading the
+// module directory in packModule; never touches the network or the database.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { sha256hex, canonicalTreeHash, normalizeMode, buildTar, readTarAsync } = require('./artifact-format');
+const { matchesDeny } = require('./publish-manifest');
+const { validateManifest } = require('../../src/module-loader/manifest-schema');
+
+const ARTIFACT_NAME = 'bongos-module';
+const MANIFEST_SCHEMA = 1;
+const TAR_ROOT = 'package/';
+const INNER_MANIFEST_PATH = '.bongos-module.json';
+const INNER_MANIFEST = TAR_ROOT + INNER_MANIFEST_PATH;
+// Local-only files a module dir may hold that are never part of the module itself.
+const NEVER_PACKED = new Set(['.upstream-signoff.json', INNER_MANIFEST_PATH]);
+// The store's caps. A real feature module is tens of KB (the biggest bundled one packs
+// to ~90 KB), so these are generous headroom — and deliberately small, because the
+// store verifies an upload inside the web process: every byte is inflated and hashed
+// there. 5 MB on the wire matches the upstreaming queue's SUBMISSION_MAX_BYTES; the
+// unpacked cap bounds a gzip bomb.
+const MAX_TARBALL_BYTES = 5 * 1024 * 1024;
+const READ_LIMITS = { maxUnpackedBytes: 16 * 1024 * 1024, maxFiles: 2000 };
+
+function tarballName(key, version) { return `${ARTIFACT_NAME}-${key}-${version}.tgz`; }
+
+// Every file under dir, as module-relative forward-slash paths, sorted. Skips
+// VCS/dependency noise the way listModuleFiles (module.js) does.
+function listFiles(dir, rel = '') {
+  const out = [];
+  for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name === '.git') continue;
+    const r = rel ? `${rel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFiles(dir, r));
+    else if (entry.isFile()) out.push(r);
+  }
+  return out.sort();
+}
+
+// A module-relative path is safe to unpack only if it stays inside the module.
+function isSafeRelPath(p) {
+  return typeof p === 'string' && p.length > 0 && !p.startsWith('/') && !p.includes('\\')
+    && !/^[A-Za-z]:/.test(p) && !p.split('/').some((seg) => seg === '' || seg === '.' || seg === '..');
+}
+
+// The repo denylist anchors its secret entries at the root (`.env`, not
+// `modules/x/.env`), which is right for the core tree and wrong for a module that
+// travels on its own. So a store module is also refused any file whose NAME marks it
+// as a credential, wherever it sits in the module.
+const SECRET_FILE_RE = /^(?:\.env(?:\..*)?|\.npmrc|\.netrc|\.pgpass|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|.*\.(?:pem|key|p12|pfx|jks|keystore))$/i;
+
+// The files the gate refuses, named at their canonical modules/<key>/ path.
+function deniedFiles(key, relPaths) {
+  return relPaths
+    .filter((p) => matchesDeny(`modules/${key}/${p}`) || SECRET_FILE_RE.test(p.split('/').pop()))
+    .map((p) => `modules/${key}/${p}`);
+}
+
+function buildModuleManifest({ key, version, coreVersion, builtAtIso, files, treeHash }) {
+  return {
+    artifact: ARTIFACT_NAME,
+    manifest_schema: MANIFEST_SCHEMA,
+    generator: 'scripts/gds/module-artifact.js',
+    module_key: key,
+    module_version: version,
+    core_version: coreVersion,
+    built_at: builtAtIso,
+    file_count: files.length,
+    tree_sha256: treeHash,
+    files: files.map((f) => ({ path: f.path, mode: normalizeMode(f.mode), sha256: f.sha256 })),
+  };
+}
+
+// Pack modules/<key>/ into { tgz, manifest, sidecar } or throw with a plain reason.
+// `modeOf` is injectable because Windows reports no executable bit.
+function packModule(key, { modulesDir, now = () => new Date(), modeOf } = {}) {
+  const dir = path.join(modulesDir, key);
+  if (!fs.existsSync(dir)) throw new Error(`modules/${key} does not exist`);
+  let moduleJson;
+  try { moduleJson = JSON.parse(fs.readFileSync(path.join(dir, 'module.json'), 'utf8')); }
+  catch { throw new Error(`modules/${key}/module.json is missing or is not valid JSON`); }
+  const { valid, errors } = validateManifest(moduleJson);
+  if (!valid) throw new Error(`modules/${key}/module.json is invalid: ${errors.join('; ')}`);
+  if (moduleJson.key !== key) throw new Error(`modules/${key}/module.json names key "${moduleJson.key}"`);
+
+  const rel = listFiles(dir).filter((p) => !NEVER_PACKED.has(p));
+  const denied = deniedFiles(key, rel);
+  if (denied.length) {
+    throw new Error(`the publish denylist refuses: ${denied.join(', ')} — remove them from the module (ADR 0098)`);
+  }
+  const unsafe = rel.filter((p) => !isSafeRelPath(p));
+  if (unsafe.length) throw new Error(`unpackable file name(s): ${unsafe.join(', ')}`);
+
+  const files = [];
+  const entries = [];
+  for (const p of rel) {
+    const abs = path.join(dir, ...p.split('/'));
+    const buf = fs.readFileSync(abs);
+    const mode = normalizeMode(modeOf ? modeOf(abs) : (fs.statSync(abs).mode & 0o777).toString(8));
+    files.push({ path: p, mode, sha256: sha256hex(buf) });
+    entries.push({ name: TAR_ROOT + p, mode: parseInt(mode, 8), buf });
+  }
+  const manifest = buildModuleManifest({
+    key, version: moduleJson.version, coreVersion: moduleJson.coreVersion,
+    builtAtIso: now().toISOString(), files, treeHash: canonicalTreeHash(files),
+  });
+  entries.push({ name: INNER_MANIFEST, mode: 0o644, buf: Buffer.from(JSON.stringify(manifest, null, 2) + '\n') });
+  const tgz = buildTar(entries);
+  const sidecar = { ...manifest, tarball: { name: tarballName(key, manifest.module_version), sha256: sha256hex(tgz), bytes: tgz.length } };
+  return { tgz, manifest, sidecar, moduleJson };
+}
+
+// The store's check on an upload. Trusts NOTHING the client says beyond the bytes:
+// every hash is recomputed, the inner manifest must describe exactly the files the
+// tarball holds, module.json must validate and name the route's key, and the
+// denylist runs again. Resolves { ok: true, ... } or { ok: false, code, message }.
+// Async so the inflate runs off the event loop (readTarAsync); the rest is one pass
+// over at most READ_LIMITS.maxUnpackedBytes.
+async function verifyModuleArtifact(tgz, { key, maxBytes = MAX_TARBALL_BYTES } = {}) {
+  const fail = (code, message) => ({ ok: false, code, message });
+  if (!Buffer.isBuffer(tgz) || tgz.length === 0) return fail('empty_artifact', 'the upload is empty');
+  if (tgz.length > maxBytes) return fail('artifact_too_large', `the tarball is over ${maxBytes} bytes`);
+
+  let entries;
+  try { entries = await readTarAsync(tgz, READ_LIMITS); }
+  catch (e) { return fail('bad_tarball', e.message); }
+
+  const byName = new Map();
+  for (const e of entries) {
+    if (!e.name.startsWith(TAR_ROOT)) return fail('bad_tarball', `"${e.name}" is outside ${TAR_ROOT}`);
+    const rel = e.name.slice(TAR_ROOT.length);
+    if (!isSafeRelPath(rel)) return fail('bad_tarball', `"${e.name}" is not a safe path`);
+    if (byName.has(rel)) return fail('bad_tarball', `"${e.name}" appears twice`);
+    byName.set(rel, e);
+  }
+  const inner = byName.get(INNER_MANIFEST_PATH);
+  if (!inner) return fail('no_manifest', `the tarball carries no ${INNER_MANIFEST}`);
+  let manifest;
+  try { manifest = JSON.parse(inner.buf.toString('utf8')); }
+  catch { return fail('no_manifest', `${INNER_MANIFEST} is not valid JSON`); }
+  if (manifest.artifact !== ARTIFACT_NAME || manifest.manifest_schema !== MANIFEST_SCHEMA || !Array.isArray(manifest.files)) {
+    return fail('bad_manifest', `${INNER_MANIFEST} is not a ${ARTIFACT_NAME} schema ${MANIFEST_SCHEMA} manifest`);
+  }
+
+  // Recompute the pin from the bytes and hold the manifest to it, file by file.
+  byName.delete(INNER_MANIFEST_PATH);
+  const actual = [...byName.entries()]
+    .map(([p, e]) => ({ path: p, mode: normalizeMode(e.mode.toString(8)), sha256: sha256hex(e.buf) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const declared = [...manifest.files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  if (declared.length !== actual.length || manifest.file_count !== actual.length) {
+    return fail('hash_mismatch', `the manifest lists ${declared.length} file(s) but the tarball holds ${actual.length}`);
+  }
+  for (let i = 0; i < actual.length; i++) {
+    const a = actual[i]; const d = declared[i];
+    if (d.path !== a.path || normalizeMode(d.mode) !== a.mode || d.sha256 !== a.sha256) {
+      return fail('hash_mismatch', `"${a.path}" does not match its manifest entry`);
+    }
+  }
+  const treeSha = canonicalTreeHash(actual);
+  if (manifest.tree_sha256 !== treeSha) return fail('hash_mismatch', 'tree_sha256 does not match the files');
+
+  const denied = deniedFiles(key, actual.map((f) => f.path));
+  if (denied.length) return fail('denied_content', `the publish denylist refuses: ${denied.join(', ')}`);
+
+  const mj = byName.get('module.json');
+  if (!mj) return fail('bad_module', 'the tarball has no module.json');
+  let moduleJson;
+  try { moduleJson = JSON.parse(mj.buf.toString('utf8')); }
+  catch { return fail('bad_module', 'module.json is not valid JSON'); }
+  const v = validateManifest(moduleJson);
+  if (!v.valid) return fail('bad_module', `module.json is invalid: ${v.errors.join('; ')}`);
+  if (moduleJson.key !== key || manifest.module_key !== key) {
+    return fail('key_mismatch', `the tarball is module "${moduleJson.key}", not "${key}"`);
+  }
+  if (manifest.module_version !== moduleJson.version || manifest.core_version !== moduleJson.coreVersion) {
+    return fail('bad_manifest', 'the manifest version does not match module.json');
+  }
+
+  return {
+    ok: true, manifest, moduleJson,
+    version: moduleJson.version, coreVersion: moduleJson.coreVersion,
+    treeSha256: treeSha, tarballSha256: sha256hex(tgz), bytes: tgz.length,
+  };
+}
+
+module.exports = { MAX_TARBALL_BYTES, packModule, verifyModuleArtifact };

package/scripts/gds/module.js

@@ -102,12 +102,12 @@ function envPrefix() {
 // Pure builders (exported for tests — no I/O, no network)
 // ---------------------------------------------------------------------------
 
-// dev-box -> "Dev Box"; economy -> "Economy". A readable default title.
+// 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(' ');
 }
-// dev-box -> devBox (for the generated route-factory function name).
+// art-pipeline -> artPipeline (for the generated route-factory function name).
 function camel(key) {
   return String(key).replace(/[-_]+(.)/g, (_, c) => c.toUpperCase());
 }
@@ -125,6 +125,8 @@ function buildManifest(key, { core = coreVersion() } = {}) {
     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',
@@ -265,7 +267,7 @@ function evaluateUpgrade({ rows = [], errors = [], core } = {}) {
 
 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. "dev-box")`);
+    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) {
@@ -411,14 +413,14 @@ function formatCatalog(rows, { catalogOnly = false, query = '', core = null } =
     return out.join('\n');
   }
 
-  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('SOURCE', 10)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
+  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${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';
-    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(r.source, 10)}${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(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${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');
@@ -776,6 +778,90 @@ async function cmdSubmit(args, {
   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})`);
+  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' : ''}.`);
+  return 0;
+}
+
 function printHelp(out = console.log) {
   out('bongos module — scaffold + manage Cloud Bongos modules\n');
   out('Usage:');
@@ -787,6 +873,8 @@ function printHelp(out = console.log) {
   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');
 }
 
 async function main(argv) {
@@ -797,6 +885,7 @@ async function main(argv) {
   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 || sub === 'help' || sub === '--help' || sub === '-h') {
     printHelp();
     return sub ? 0 : 2;
@@ -807,7 +896,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, printHelp,
+  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, printHelp,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,