@bongos/core 1.23.3 → 1.23.4

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/bongos/package-core.js",
-  "core_version": "1.23.3",
-  "core_contract": "1.23.3",
-  "source_commit": "a0b45cd71b45f91da068da6eb3e6afef687897c6",
+  "core_version": "1.23.4",
+  "core_contract": "1.23.4",
+  "source_commit": "b78c52677b921b7b2a6f25834c77b7d516810aa9",
   "source_ref": "HEAD",
-  "built_at": "2026-10-26T21:16:36.258Z",
+  "built_at": "2026-10-26T21:43:52.539Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 616,
     "agent_docs_stubbed": 29,
-    "functional_verbatim": 3551,
+    "functional_verbatim": 3552,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 4197,
-  "tree_sha256": "929094e8d49dd75a5e74b18f58a1b869fc50dbc5df600af9e861981227cdb40c",
+  "file_count": 4198,
+  "tree_sha256": "e5ed2ca130fbbb98e21c941d9c51e72760f74f72e2d48d6d91a4e789bdd6ce10",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2937,12 +2937,12 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "298fea75cd1590bf6dbb3ad5baedf0ec6c81d2eb811cf59a3d138bd15144c021"
+      "sha256": "3907ee1e7036c99afa1790df344933c6652b4d9ffe972715551ad9bdb2bb12d9"
     },
     {
       "path": "docs/modules-contract.md",
       "mode": "0000644",
-      "sha256": "28cbf7f3d10bd67ef74880112746d182fac27a7659c52694c315b17efe5cb325"
+      "sha256": "ed7ab0d4799a935bb296457ebdba667c38dcfea5ebaec72e61968cd3ad91a6eb"
     },
     {
       "path": "docs/onboarding/diagrams/01-task-lifecycle.mmd",
@@ -10832,12 +10832,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4a12dc099ad30270a9f2144f9f243b7183b968c6f9761736c2a10a4471ca08ee"
+      "sha256": "793a3d85e023eafb3f0eb63e7a1c1b10f07a66e331adfb63d06a05921ad2f451"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "975226f43368c946a43c0ae434ba6132e404175ba6b4960c45fb72b6d109e715"
+      "sha256": "db95c78d828b9fd2117b5a7b4e12d741fb21856022a6830b6cd286017a065f6f"
     },
     {
       "path": "public-docs/index.html",
@@ -10857,7 +10857,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "de9343583c3ac62144354a65b34a4a44bb4d9442c4abd1b77fafc16558c70f9c"
+      "sha256": "a491785c22b68e414bdf9668ca809f671a8927d06560aabfbc04ce3d56dfc131"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -11747,7 +11747,7 @@
     {
       "path": "scripts/bongos/module.js",
       "mode": "0000644",
-      "sha256": "0a0bbaea5b010533cfee379593768990a26717c4fcaf614896ec2b3b6b3061b6"
+      "sha256": "6fc19f18daa947837ee09d9d06010380144022ee6f637f3fd444f56cf558bfab"
     },
     {
       "path": "scripts/bongos/move-escalation.js",
@@ -14712,7 +14712,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "f87d7162b505fb241f2c33e6dfeaa86cb97d085c6f822384b2b7d923d4eadd1a"
+      "sha256": "e9850d0157caab4215194a5e69e04420b0d9e3b97a8d1867f8f84e9087b88930"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -18484,6 +18484,11 @@
       "mode": "0000644",
       "sha256": "ba4233ed072c87df9dbc5c75af10655ad8eaaf9d8ccbe69df146052467a1279e"
     },
+    {
+      "path": "tests/module_store_cli.mjs",
+      "mode": "0000644",
+      "sha256": "cf4df707f62fa142f106822c44404603f8ec32213d61b6707818f5649c443275"
+    },
     {
       "path": "tests/module_store_delist.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -3223,5 +3223,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.23.1 with no explicit bump. run 40399986777. (task 1002620)
   1.23.3 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.23.2 with no explicit bump. run 40402796050. (task 1002620)
+  1.23.4 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.23.3 with no explicit bump. run 40406624494. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -176,6 +176,8 @@ closed on every unknown, including a ledger read it cannot complete.
 
 **Attribution (`author`/`origin`/`license`/`maintainer`) is portable metadata, not a cross-Bongos link** — each repo runs its own Bongos with its own builder identities ([ADR 0100](adr/0100-two-repo-instance-model.md) §3), so credit travels *with the module* rather than through a foreign key ([ADR 0107](adr/0107-module-upstreaming-contribution-to-core-catalog.md) §2). `bongos module new` stamps all four as TODO placeholders (license defaults to `AGPL-3.0`) so a module carries its authorship from the day it's scaffolded, not bolted on later at upstream-submit time.
 
+**`bongos module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]`** (task 1003811) is the **store** from the terminal: what the catalog lists, in its order — listed modules ranked, then New ones, unranked — with each module's score, price and place (parent, and sub-category once approved). It asks `GET /store/modules`, the same read the hall's "In the store" group makes, and filters, ranks and caps nothing itself: the quality floor, the ranking and the cap of ten per sub-category live only in `src/bongos/module-listing.js`, so the hall and the terminal cannot disagree about which modules are the best. `tests/module_store_cli.mjs` sends the same queries through the API and the CLI and requires the same modules in the same order.
+
 **`bongos module list [--catalog] [--search <text>] [--json]`** ([ADR 0107](adr/0107-module-upstreaming-contribution-to-core-catalog.md) §2/§3, [ADR 0167](adr/0167-module-catalog-source-vs-provenance.md)) is the browsable catalog from the terminal: every module on disk with its enabled state, its author + origin credit, and its upkeep posture. `--catalog` narrows to the **core-shipped** modules — the shared catalog an instance opts into (§6, default-off). Two axes travel on each row and they are *not* the same question: **`source`** (which tree ships it — the core package or this instance's own repo, read structurally from the loader's discovery root, [ADR 0108](adr/0108-instance-composition-configurable-root.md) §1) and **`provenance`** (who built it, derived from the declared `origin`). A core module that declares no attribution is credited to the platform and the credit is **marked inferred** (`*`) rather than left blank or silently invented. The hall's Modules tab renders the same model (`src/module-loader/catalog.js`) via `GET /modules`, so the two surfaces cannot drift.
 
 **`bongos module check <key> [--sign-off "Name <email>"]`** ([ADR 0107](adr/0107-module-upstreaming-contribution-to-core-catalog.md) §4) is the submit-time pre-check a module must clear before it can be upstreamed. It reuses (never re-types) the public-mirror publish denylist (`scripts/bongos/publish-manifest.js`'s `matchesDeny`) to reject content that cannot ship under AGPL (game content, pixel art, copyrighted reference material) — deliberately the DENY half only, since a brand-new module is never on the publish ALLOWLIST until it's accepted into core (§6). It also requires `module.json`'s `license` to be AGPL-3.0 (inbound = outbound) and a declared `maintenance` posture — acceptance is a commitment to upkeep, so a module with no `maintenance.status`, or one already `deprecated`/`orphaned`, is refused ([ADR 0166](adr/0166-module-maintenance-and-deprecation-policy.md); see below). On a pass, `--sign-off` records a lightweight DCO-style affirmation (own work, licensed AGPL-3.0 — never a copyright-assignment CLA) to `modules/<key>/.upstream-signoff.json`.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.23.3",
+  "version": "1.23.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.23.3",
+      "version": "1.23.4",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.23.3",
+  "version": "1.23.4",
   "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,11 @@
       "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."
+    }
   ]
 }

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)
@@ -1060,6 +1069,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 +1406,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 +1427,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 +1444,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/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.4'; // 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/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>\]/);
+});