@bongos/core 1.23.3 → 1.23.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.23.3",
+  "version": "1.23.5",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -10401,5 +10401,17 @@
       "id": "1003809",
       "text": "The module store now shows at most ten modules in each sub-category, and a module that lands eleventh tells its author why."
     }
+  ],
+  "1.23.4": [
+    {
+      "id": "1003811",
+      "text": "Builders can now browse the module store from the terminal with bongos module store, and it always shows the same modules in the same order as the hall."
+    }
+  ],
+  "1.23.5": [
+    {
+      "id": "1004895",
+      "text": "A broken module version can now be pulled back from the store, so new installs and updates stop getting it while projects that already have it are told."
+    }
   ]
 }

package/scripts/bongos/module.js

@@ -31,6 +31,14 @@
 //     model as the hall's Modules tab (src/module-loader/catalog.js), so the two
 //     surfaces cannot disagree about who built what.
 //
+//   bongos module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]
+//     Task 1003811 (criterion wa5-curated-listing) — the STORE from the terminal:
+//     what the catalog lists, in its order. It asks GET /store/modules, the same
+//     read the hall's "In the store" group makes, and never filters, ranks or caps
+//     anything itself — the quality floor, the ranking and the cap of ten per
+//     sub-category live in one place (src/bongos/module-listing.js), so the hall
+//     and the terminal cannot disagree about which modules are the best.
+//
 //   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
@@ -58,6 +66,7 @@
 //   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 module store [--sort <part>] [--max-cents N] [--max-credits N]   what the store lists, best first
 //   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)
@@ -703,7 +712,7 @@ async function gatherUpdates(rows, { request } = {}) {
   // 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) || {} };
+  return { checked: true, latest: (res.data && res.data.latest) || {}, withdrawn: (res.data && res.data.withdrawn) || {} };
 }
 
 // Decide what is stale from rows + the store's answer (pure — tests drive it).
@@ -713,13 +722,22 @@ async function gatherUpdates(rows, { request } = {}) {
 // 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) {
+function evaluateUpdates(rows = [], latest = {}, core, withdrawnByKey = {}) {
   const { satisfies } = require('../../src/module-loader/semver');
   const updates = [];
   const delisted = [];
+  const withdrawn = [];
   for (const r of rows) {
     const store = latest[r.key];
     const have = r.version && parseVersion(String(r.version));
+    // WITHDRAWN (task 1004895) = the store took back the exact version installed
+    // here. It keeps working; the update below, when there is one, is the way off it.
+    const taken = have && (withdrawnByKey[r.key] || [])
+      .map((w) => (typeof w === 'string' ? { version: w, note: null } : w))
+      .find((w) => w && w.version === String(r.version));
+    if (taken) {
+      withdrawn.push({ key: r.key, installed: r.version, latest: store ? store.version : null, enabled: r.enabled, note: taken.note || null });
+    }
     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));
@@ -728,7 +746,7 @@ function evaluateUpdates(rows = [], latest = {}, core) {
     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 };
+  return { updates, delisted, withdrawn };
 }
 
 function reportUpdates(found, verdict, { log, errlog }) {
@@ -737,7 +755,7 @@ function reportUpdates(found, verdict, { log, errlog }) {
     log(`  not checked — ${found.reason}. The compatibility check above still stands.`);
     return;
   }
-  const { updates, delisted } = evaluateUpdates(verdict.rows, found.latest, verdict.core);
+  const { updates, delisted, withdrawn } = evaluateUpdates(verdict.rows, found.latest, verdict.core, found.withdrawn);
   for (const u of updates) {
     const how = u.fits
       ? `run \`bongos module update ${u.key}\``
@@ -747,7 +765,17 @@ function reportUpdates(found, verdict, { log, errlog }) {
   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.');
+  for (const w of withdrawn) {
+    // Update only moves forward, so an OLDER served version is no way off it: until a
+    // fixed version is published, say so rather than name a command that refuses.
+    const newer = w.latest && parseVersion(String(w.latest))
+      && cmp(parseVersion(String(w.latest)), parseVersion(String(w.installed))) > 0;
+    const next = newer
+      ? `move to ${w.latest} with \`bongos module update ${w.key}\``
+      : 'no newer version is out yet; `bongos upgrade` will offer the fix once one is published';
+    errlog(`  ! ${w.key.padEnd(18)} ${w.installed}  — withdrawn in the store${w.note ? ` (${w.note})` : ''}: it keeps working here, but ${next}`);
+  }
+  if (!updates.length && !delisted.length && !withdrawn.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 } = {}) {
@@ -1060,6 +1088,84 @@ function storeError(res) {
   return (err && (err.message || err.code)) || `HTTP ${res.status}`;
 }
 
+// ---------------------------------------------------------------------------
+// bongos module store — what the store lists (task 1003811)
+// ---------------------------------------------------------------------------
+
+const STORE_USAGE = 'usage: bongos module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]';
+
+// The query GET /store/modules takes, from argv. Returns { query } or { error }.
+// The server checks the values too; this only refuses what is not a value at all.
+function storeQuery(args) {
+  const params = [];
+  for (const [flag, param] of [['--sort', 'sort'], ['--max-cents', 'max_cents'], ['--max-credits', 'max_credits']]) {
+    const i = args.indexOf(flag);
+    if (i === -1) continue;
+    const v = args[i + 1];
+    if (!v || v.startsWith('--')) return { error: `${flag} needs a value` };
+    params.push(`${param}=${encodeURIComponent(v)}`);
+  }
+  return { query: params.length ? `?${params.join('&')}` : '' };
+}
+
+function formatPrice(price) {
+  if (!price || price.free) return 'free';
+  const parts = [];
+  if (price.cents != null) parts.push(`$${(price.cents / 100).toFixed(2)}`);
+  if (price.credits != null) parts.push(`${price.credits} credits`);
+  return parts.join(' or ') || 'free';
+}
+
+function formatPlace(category) {
+  if (!category) return '';
+  return category.label ? `${category.parent_title} › ${category.label}` : category.parent_title;
+}
+
+// Pure renderer over the GET /store/modules body. It keeps the server's order and
+// adds nothing to it: listed in rank, then New, never ranked.
+function formatStore(body) {
+  const out = [];
+  out.push('bongos module store — what the store lists, best first');
+  out.push(`  floor ${body.floor} out of 100 · at most ${body.cap} per sub-category`);
+  out.push(`  ${body.ranking}`);
+  if (body.sort) {
+    const part = (body.sort_parts || []).find((x) => x.part === body.sort);
+    out.push(`  sorted by ${part ? part.title : body.sort}`);
+  }
+  const max = body.max_price;
+  if (max) out.push(`  at most ${[max.cents != null ? `$${(max.cents / 100).toFixed(2)}` : null, max.credits != null ? `${max.credits} credits` : null].filter(Boolean).join(' or ')}`);
+  out.push('');
+  const listed = body.listed || [];
+  if (!listed.length) out.push('  Nothing is listed yet.');
+  listed.forEach((m, i) => {
+    out.push(`  ${String(i + 1).padStart(2)}. ${m.key}@${m.version}  ${m.overall}/100  ${formatPrice(m.price)}${m.category ? `  ${formatPlace(m.category)}` : ''}`);
+  });
+  const fresh = body.new || [];
+  if (fresh.length) {
+    out.push('');
+    out.push('  New — not ranked until projects have installed and used them:');
+    for (const m of fresh) out.push(`      ${m.key}@${m.version}  ${formatPrice(m.price)}${m.category ? `  ${formatPlace(m.category)}` : ''}`);
+  }
+  out.push('');
+  out.push('  Why a module is not here: GET /store/modules/<key>/listing');
+  return out.join('\n');
+}
+
+async function cmdStore(args, { log = console.log, errlog = console.error, request } = {}) {
+  const q = storeQuery(args);
+  if (q.error) { errlog(`bongos module store: ${q.error}`); errlog(STORE_USAGE); return 2; }
+  let call;
+  try { call = request || storeRequest(); }
+  catch (e) { errlog(`bongos module store: ${e.message}`); return 1; }
+  let res;
+  try { res = await call('GET', `/store/modules${q.query}`); }
+  catch (e) { errlog(`bongos module store: the store could not be reached — ${e.message}`); return 1; }
+  if (!res.ok) { errlog(`bongos module store: the store answered ${storeError(res)}`); return res.status === 400 ? 2 : 1; }
+  if (args.includes('--json')) { log(JSON.stringify(res.data, null, 2)); return 0; }
+  log(formatStore(res.data || {}));
+  return 0;
+}
+
 // 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() {
@@ -1319,6 +1425,8 @@ function printHelp(out = console.log) {
   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 module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]');
+  out('                              What the store lists, best first: above the quality floor, ranked, ten per sub-category');
   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>"]');
@@ -1338,6 +1446,7 @@ async function main(argv) {
   const sub = args[0];
   if (sub === 'new') return cmdNew(args.slice(1));
   if (sub === 'list' || sub === 'ls') return cmdList(args.slice(1));
+  if (sub === 'store') return cmdStore(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));
@@ -1354,7 +1463,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
+  main, cmdNew, cmdList, cmdStore, formatStore, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
   storeRequest,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, gatherUpdates, evaluateUpdates, buildManifest,

package/src/bongos/module-store.js

@@ -383,6 +383,47 @@ async function latestVersions(keys, { db, channelsFor = null } = {}) {
   return out;
 }
 
+// Withdraw one version (task 1004895, criterion wa5-staged-rollout): the store
+// stops handing it out. Staged rollout catches a bad version on the tester channel;
+// this is the way back once one has reached general. It is one channel row,
+// 'withdrawn' (core_276), which servedChannels never serves, so acquire, install,
+// update and the update check all stop offering it with no other change. Like a
+// delist it reaches nothing a project already holds: an installed copy keeps
+// working (ADR 0338 D2), and `bongos upgrade` and the hall tell its holder, with
+// `note` — the reason the person gave, kept on the row (core_281). The insert only
+// lands while the version is not already withdrawn, so two people withdrawing at
+// once write one row. Returns { ok: true, channel } or { ok: false, status, code, message }.
+const WITHDRAWN_CHANNEL = 'withdrawn';
+
+async function withdrawVersion(versionId, builderId, note, { db } = {}) {
+  const pool = db || require('./pool').pool;
+  const { rowCount } = await pool.query(
+    `INSERT INTO store_module_version_channels (version_id, channel, reason, set_by, note)
+     SELECT $1, '${WITHDRAWN_CHANNEL}', 'withdrawn_by_person', $2, $3
+      WHERE (SELECT c.channel FROM store_module_version_channels c
+              WHERE c.version_id = $1 ORDER BY c.set_at DESC, c.id DESC LIMIT 1)
+            IS DISTINCT FROM '${WITHDRAWN_CHANNEL}'`, [versionId, builderId, note]);
+  if (rowCount === 1) return { ok: true, channel: WITHDRAWN_CHANNEL };
+  return { ok: false, status: 409, code: 'already_withdrawn', message: 'This version is already withdrawn: the store does not hand it out.' };
+}
+
+// Which versions of these module keys are withdrawn, as { key: [{ version, note }] }
+// — so the update check and the hall can tell a project that the version it runs
+// was taken back, and why. `note` is the reason from the withdrawing row.
+async function withdrawnVersions(keys, { db } = {}) {
+  if (!keys.length) return {};
+  const pool = db || require('./pool').pool;
+  const { rows } = await pool.query(
+    `SELECT v.module_key, v.version,
+            (SELECT c.note FROM store_module_version_channels c
+              WHERE c.version_id = v.id ORDER BY c.set_at DESC, c.id DESC LIMIT 1) AS note
+       FROM store_module_versions v
+      WHERE v.module_key = ANY($1) AND ${currentChannelSql('v.id')} = '${WITHDRAWN_CHANNEL}'`, [keys]);
+  const out = {};
+  for (const r of rows) (out[r.module_key] = out[r.module_key] || []).push({ version: r.version, note: r.note || null });
+  return out;
+}
+
 // Delist a module (task 1003797, ADR 0338 D2): it leaves the catalog, takes no new
 // acquisitions or versions, and serves no further downloads — every read above
 // already refuses on status 'delisted', so this one UPDATE is the whole act. It
@@ -427,5 +468,5 @@ function versionArtifactFile(row, { dir = storeDir() } = {}) {
 module.exports = {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
   isFreePrice, servedChannels, resolveAcquirable, resolveReadable, publishedVersionSet, latestVersions, versionArtifactFile,
-  delistModule, delistedKeySet, storeDir, storeDirFor, migrateLegacyStore,
+  delistModule, delistedKeySet, withdrawVersion, withdrawnVersions, storeDir, storeDirFor, migrateLegacyStore,
 };

package/src/bongos/route-rank-check.js

@@ -253,6 +253,9 @@ const EXPECTED_RANKS = {
   // Releasing a version the promotion gate held on tester (task 1003804) hands it to
   // every project; the owner put it on the delist atom (2026-10-23), so it is pinned.
   'POST /store/modules/:key/versions/:version/release': 'perm:module.delist',
+  // Withdrawing a version (task 1004895) stops it being handed to every project, the
+  // same reach as a delist, so it rides the delist atom and is pinned.
+  'POST /store/modules/:key/versions/:version/withdraw': 'perm:module.delist',
 };
 
 // The authz-core route pins (ADR 0174). Paths and the gating atom were renamed

package/src/bongos/routes/modules.js

@@ -97,7 +97,7 @@ const { checkEntitlement, listEntitlements, grantEntitlement, recordAcquired } =
 const {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
   servedChannels, resolveAcquirable, resolveReadable, publishedVersionSet, latestVersions, versionArtifactFile,
-  delistModule, delistedKeySet, migrateLegacyStore,
+  delistModule, delistedKeySet, withdrawVersion, withdrawnVersions, migrateLegacyStore,
 } = require('../module-store');
 const {
   isOptedOut, setReporting, installReportError, errorCountError, recordInstallReport, recordErrorCount,
@@ -272,6 +272,11 @@ module.exports = function buildModulesRouter() {
     let delistedKeys = new Set();
     try { delistedKeys = await delistedKeySet(all.filter((m) => m.source === 'instance').map((m) => m.key)); }
     catch (e) { log.warn({ err: e.message }, 'store status unreadable for the modules list'); }
+    // Which installed store modules run a version the store took back (task 1004895),
+    // so the row says so, with the reason. Same tolerance.
+    let withdrawn = {};
+    try { withdrawn = await withdrawnVersions(all.filter((m) => m.source === 'instance').map((m) => m.key)); }
+    catch (e) { log.warn({ err: e.message }, 'withdrawn versions unreadable for the modules list'); }
     for (const m of all) {
       m.enabled_source = sources[m.key] || 'default';
       m.override = byKey.has(m.key)
@@ -283,6 +288,9 @@ module.exports = function buildModulesRouter() {
         ? `/builders/modules?howto=${encodeURIComponent(m.key)}&version=${encodeURIComponent(String(m.version))}`
         : null;
       m.store_delisted = m.source === 'instance' && delistedKeys.has(m.key);
+      const taken = m.source === 'instance' && m.version
+        ? (withdrawn[m.key] || []).find((w) => w.version === String(m.version)) : null;
+      m.store_withdrawn = taken ? { version: taken.version, note: taken.note } : null;
       // what of this module still waits for a restart to match its toggle (task 1004463)
       m.restart_pending = restartPendingFor(m.key, m.enabled === true);
     }
@@ -637,6 +645,35 @@ module.exports = function buildModulesRouter() {
       res.json({ ok: true, module_key: key, version, channel: out.channel, reason: out.reason });
     }));
 
+  // POST /api/bongos/store/modules/:key/versions/:version/withdraw — a Metic+ person
+  // takes one version back (task 1004895, criterion wa5-staged-rollout). The store
+  // stops handing it out: acquire, install, update and the update check skip it, and
+  // the newest version still served is offered instead. A project that already runs
+  // it keeps it, and `bongos upgrade` and the hall's Modules tab tell it the version
+  // was withdrawn, with the reason. Withdrawing the only served version is allowed;
+  // acquire then says nothing can be handed out. A reason is required: it is kept on
+  // the channel row (core_281) and shown to holders, and the audit middleware also
+  // records it with who asked. The permission is module.delist, the one that already
+  // guards delist and release.
+  router.post('/store/modules/:key/versions/:version/withdraw', auth.requireBuilder, auth.requirePermission('module.delist'),
+    asyncHandler('POST /store/modules/:key/versions/:version/withdraw', async (req, res) => {
+      if (validateOrRespond(req, res, { reason: { type: 'string', maxLength: 2000 } })) return;
+      const { key, version } = req.params;
+      if (!KEY_RE.test(key) || !parseVersion(version)) {
+        return res.fail('bad_request', { status: 400, message: 'A module key is lowercase kebab-case and a version is exact X.Y.Z.' });
+      }
+      const reason = String(req.body?.reason || '').trim();
+      if (!reason) {
+        return res.fail('reason_required', { status: 400, message: 'Say why this version is being taken back, in reason. Projects that already run it keep it.' });
+      }
+      const r = await resolveReadable(key, version);
+      if (!r.ok) return res.fail(r.code, { status: r.status, message: r.message });
+      const out = await withdrawVersion(r.version.id, req.builder.id, reason);
+      if (!out.ok) return res.fail(out.code, { status: out.status, message: out.message });
+      log.info({ versionId: r.version.id, builderId: req.builder.id, reason }, `${key} ${version} withdrawn from the store`);
+      res.json({ ok: true, module_key: key, version, channel: out.channel, reason });
+    }));
+
   // GET /api/bongos/store/entitlements and /store/modules/:key/entitlement — the
   // read side of the entitlement record (task 1003813, ADR 0338 D1). Own-scoped
   // like /me/sessions: the holder is ALWAYS the caller (holder_kind 'builder',
@@ -832,9 +869,14 @@ module.exports = function buildModulesRouter() {
       if (!keys.length || keys.length > STORE_LATEST_MAX_KEYS || !keys.every((k) => KEY_RE.test(k))) {
         return res.fail('bad_request', { status: 400, message: `keys is a comma-separated list of 1 to ${STORE_LATEST_MAX_KEYS} module keys (lowercase kebab-case).` });
       }
-      const latest = await latestVersions(keys, { channelsFor: await projectChannels() });
+      // Which of these keys have versions taken back (task 1004895), so a project
+      // running one is told, with the reason; a key with none is absent.
+      const [latest, withdrawn] = await Promise.all([
+        latestVersions(keys, { channelsFor: await projectChannels() }),
+        withdrawnVersions(keys),
+      ]);
       res.set('Cache-Control', 'no-store');
-      res.json({ latest });
+      res.json({ latest, withdrawn });
     }));
 
   // The store catalog under the quality floor (task 1003807, ADR 0343 D2/D5): each

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.23.3'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.23.5'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/hall_catalog_world.mjs

@@ -58,7 +58,7 @@ test('modules: the row is the oversight row — title with the mono key, clamped
   assert.match(js, /<span class="ov-row__title">\$\{escapeHtml\(m\.title \|\| m\.key\)\}<span class="ov-mono">\$\{escapeHtml\(m\.key\)\}<\/span>/, 'the key rides inside the title in mono');
   assert.match(js, /class="ov-row__sub mod-row__desc"/, 'the description is the sub line');
   assert.match(js, /<details class="mod-more"/, 'a details disclosure opens the rest');
-  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{categoryFact\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}\$\{restartFact\(m\)\}<\/div>/, 'provenance, (task 1003784) the category, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill and (task 1004463) the waits-for-a-restart pill are the facts line');
+  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{categoryFact\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}\$\{withdrawnFact\(m\)\}\$\{restartFact\(m\)\}<\/div>/, 'provenance, (task 1003784) the category, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill, (task 1004895) the withdrawn pill and (task 1004463) the waits-for-a-restart pill are the facts line');
   assert.match(js, /<div class="ov-row__right mod-row__right">\$\{rightHtml\(m\)\}<\/div>/, 'the right column is one function');
   const css = read('modules.css');
   assert.match(css, /\.mod-row__desc \{[^}]*-webkit-line-clamp: 2/, 'the description clamps to two lines');

package/tests/module_store_cli.mjs

@@ -0,0 +1,184 @@
+// tests/module_store_cli.mjs — `bongos module store` and the hall read ONE catalog
+// (task 1003811, criterion wa5-curated-listing). The terminal command asks the
+// real GET /store/modules handler here — off the real router, with pool.js replaced
+// in the require cache (the module_store_listing.mjs harness) — so the test pins
+// what the task asks: the same query through the API and through the CLI returns
+// the same modules in the same order, capped the same way. Two surfaces that drift
+// on which modules are "the best" is worse than either being wrong alone.
+//
+// Run:  node tests/module_store_cli.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// ---- the fake registry the route reads ----
+const state = { modules: {}, versions: [], scores: [], prices: [], categories: {} };
+const newestBy = (rows, keyOf, newer) => {
+  const out = new Map();
+  for (const r of rows) {
+    const k = keyOf(r);
+    if (!out.has(k) || newer(r, out.get(k))) out.set(k, r);
+  }
+  return [...out.values()];
+};
+const pool = {
+  async query(sql, params = []) {
+    if (/FROM store_module_categories c\b/.test(sql)) {
+      return { rows: params[0].filter((k) => state.categories[k]).map((k) => ({ module_key: k, ...state.categories[k] })) };
+    }
+    if (/FROM store_modules m JOIN store_module_versions v/.test(sql)) {
+      return {
+        rows: state.versions
+          .filter((v) => state.modules[v.module_key] && state.modules[v.module_key].status === 'listed')
+          .filter((v) => !params[0] || params[0].includes(v.module_key))
+          .map((v) => ({ ...v, version_id: v.id, title: state.modules[v.module_key].title })),
+      };
+    }
+    if (/FROM store_module_prices/.test(sql)) {
+      return { rows: newestBy(state.prices.filter((p) => params[0].includes(p.module_key)), (p) => p.module_key, (a, b) => a.set_at > b.set_at) };
+    }
+    if (/FROM module_assessment_scores/.test(sql)) {
+      const ids = params[0].map(String);
+      return { rows: newestBy(state.scores.filter((s) => ids.includes(String(s.version_id))), (s) => s.version_id, (a, b) => a.computed_at > b.computed_at) };
+    }
+    return { rows: [] };
+  },
+};
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: { connect: async () => ({ ...pool, release() {} }), query: pool.query } } };
+
+const buildModulesRouter = require('../src/bongos/routes/modules.js');
+const mod = require('../scripts/bongos/module.js');
+
+function storeHandler() {
+  const layer = buildModulesRouter().stack.find((l) => l.route && l.route.path === '/store/modules' && l.route.methods.get);
+  const stack = layer.route.stack;
+  return stack[stack.length - 1].handle;
+}
+
+// The API, as a browser or the hall reads it.
+async function apiGet(query) {
+  const res = {
+    statusCode: 200, body: undefined,
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    set() { return this; },
+    fail(code, opts) { this.statusCode = opts.status; this.body = { error: { code, message: opts.message } }; return this; },
+  };
+  let nextErr = null;
+  await storeHandler()({ builder: { id: 0 }, query }, res, (err) => { nextErr = err; });
+  if (nextErr) throw nextErr;
+  return res;
+}
+
+// The CLI's request function, answered by the same handler: the URL the CLI
+// builds is parsed back into the query the route reads.
+const request = async (method, urlPath) => {
+  assert.equal(method, 'GET');
+  const url = new URL(urlPath, 'http://store.test');
+  assert.equal(url.pathname, '/store/modules');
+  const res = await apiGet(Object.fromEntries(url.searchParams));
+  return { ok: res.statusCode < 400, status: res.statusCode, data: res.body };
+};
+
+async function cliJson(args) {
+  const lines = [];
+  const errs = [];
+  const code = await mod.cmdStore([...args, '--json'], { log: (l) => lines.push(l), errlog: (l) => errs.push(l), request });
+  return { code, body: lines.length ? JSON.parse(lines.join('\n')) : null, errs };
+}
+
+const keys = (b) => b.listed.map((m) => m.key);
+
+// Fifteen Stripe modules above 94 (the owner's example), one module in a proposed
+// sub-category, one with no category, one New, and one under the floor.
+function seed() {
+  state.modules = {}; state.versions = []; state.scores = []; state.prices = []; state.categories = {};
+  const add = (key, s, cat) => {
+    const id = state.versions.length + 1;
+    state.modules[key] = { status: 'listed', title: key };
+    state.versions.push({ id, module_key: key, version: '1.0.0', published_at: 't' });
+    state.scores.push({ id, version_id: id, computed_at: 1, overall: 70, security_passed: true, is_new: false, ...s });
+    if (cat) state.categories[key] = cat;
+  };
+  const stripe = { parent: 'money', sub_key: 'stripe-payments', label: 'Stripe payments', status: 'approved' };
+  for (let i = 0; i < 15; i++) add(`stripe-${String(i).padStart(2, '0')}`, { overall: 99 - i }, stripe);
+  add('waiting', { overall: 60 }, { parent: 'money', sub_key: 'stripe-billing', label: 'Stripe billing', status: 'proposed' });
+  add('loose', { overall: 88 });
+  add('fresh', { is_new: true, overall: null });
+  add('weak', { overall: 20 });
+  state.prices = [
+    { module_key: 'stripe-01', price_cents: 900, price_credits: null, set_at: 1 },
+    { module_key: 'loose', price_cents: null, price_credits: 40, set_at: 1 },
+  ];
+}
+
+test('the terminal shows what the API lists, in its order, capped the same way', async () => {
+  seed();
+  const api = (await apiGet({})).body;
+  const cli = await cliJson([]);
+  assert.equal(cli.code, 0);
+  assert.deepEqual(cli.body, api, 'the CLI hands back the catalog exactly as the API answers it');
+  assert.equal(keys(api).filter((k) => k.startsWith('stripe-')).length, 10, 'the cap of ten holds');
+  assert.ok(!keys(api).includes('stripe-10') && !keys(api).includes('weak'), 'the eleventh and the one under the floor are not listed');
+  assert.ok(keys(api).includes('waiting') && keys(api).includes('loose'), 'a proposed sub-category and no category are not capped');
+  assert.deepEqual(api.new.map((m) => m.key), ['fresh']);
+});
+
+test('the same query through both: a sort and a maximum price give the same modules in the same order', async () => {
+  seed();
+  for (const [args, query] of [
+    [['--sort', 'tests'], { sort: 'tests' }],
+    [['--max-cents', '500'], { max_cents: '500' }],
+    [['--max-credits', '0'], { max_credits: '0' }],
+    [['--sort', 'docs', '--max-cents', '1000', '--max-credits', '100'], { sort: 'docs', max_cents: '1000', max_credits: '100' }],
+  ]) {
+    const api = (await apiGet(query)).body;
+    const cli = await cliJson(args);
+    assert.equal(cli.code, 0, args.join(' '));
+    assert.deepEqual(keys(cli.body), keys(api), args.join(' '));
+    assert.deepEqual(cli.body.new.map((m) => m.key), api.new.map((m) => m.key), args.join(' '));
+  }
+});
+
+test('the text view keeps the API order: listed ranked, then New, and says the floor and the cap', async () => {
+  seed();
+  const api = (await apiGet({})).body;
+  const lines = [];
+  assert.equal(await mod.cmdStore([], { log: (l) => lines.push(l), errlog: () => {}, request }), 0);
+  const text = lines.join('\n');
+  assert.match(text, /floor 50 out of 100 · at most 10 per sub-category/);
+  const at = (k) => text.indexOf(`${k}@`);
+  const order = [...keys(api), ...api.new.map((m) => m.key)].map(at);
+  assert.ok(order.every((i) => i !== -1), 'every listed and New module is shown');
+  assert.deepEqual(order, [...order].sort((a, b) => a - b), 'in the order the API gave');
+  assert.equal(at('stripe-10'), -1, 'the eleventh is not shown');
+  assert.match(text, /stripe-00@1\.0\.0 {2}99\/100 {2}free {2}Money › Stripe payments/);
+  assert.match(text, /stripe-01@1\.0\.0 {2}98\/100 {2}\$9\.00/);
+  assert.match(text, /loose@1\.0\.0 {2}88\/100 {2}40 credits$/m, 'no category, no place');
+  assert.match(text, /waiting@1\.0\.0 {2}60\/100 {2}free {2}Money$/m, 'a proposed sub-category shows its parent only');
+  assert.match(text, /New — not ranked[\s\S]*fresh@1\.0\.0/);
+});
+
+test('a value the server refuses, a flag with no value, and no session are reported, not swallowed', async () => {
+  seed();
+  const bad = await cliJson(['--sort', 'security']);
+  assert.equal(bad.code, 2);
+  assert.match(bad.errs.join('\n'), /the store answered/);
+  const missing = await cliJson(['--max-cents']);
+  assert.equal(missing.code, 2);
+  assert.match(missing.errs.join('\n'), /--max-cents needs a value/);
+  const errs = [];
+  const offline = await mod.cmdStore([], { log: () => {}, errlog: (l) => errs.push(l), request: async () => { throw new Error('ECONNREFUSED'); } });
+  assert.equal(offline, 1);
+  assert.match(errs.join('\n'), /could not be reached — ECONNREFUSED/);
+});
+
+test('`bongos module store` is dispatched and documented in the help', async () => {
+  const out = [];
+  mod.printHelp((l) => out.push(l));
+  assert.match(out.join('\n'), /bongos module store \[--sort <part>\]/);
+});