@bongos/core 1.21.152 → 1.21.154

package/src/bongos/routes/modules.js

@@ -110,7 +110,7 @@ const log = require('../logger').logger.child({ src: 'modules' });
 // property access on a CommonJS namespace, so reaching these through one made them read
 // as unused exports and tripped the dead-code ratchet that held this branch out of main.
 const { listOverrides, setOverride } = require('../module-overrides');
-const { listCatalog } = require('../module-listing');
+const { listCatalog, SORT_PARTS } = require('../module-listing');
 
 // The sentence for a toggle that waits on a restart (task 1004463). 'routes' are the
 // module's pages, 'pollers' its background jobs. PURE.
@@ -733,12 +733,20 @@ module.exports = function buildModulesRouter() {
   // listed module's newest version, if it passed the Security gate and scores at or
   // above the floor, or under "new" if it has no real-world data yet. Below the bar
   // is not listed at all. The floor is fixed in module-listing.js and returned here.
+  // `?sort=<part>` orders the listed modules by the part a buyer cares about
+  // (task 1003800, sortByPart); the parts it accepts come back as sort_parts.
   //
   // rank: any-builder — a read of public store metadata, like /store/modules/latest:
   // no entitlement taken, nothing changed.
   router.get('/store/modules', auth.requireBuilder,
-    asyncHandler('GET /store/modules', async (_req, res) => {
-      const listing = await listCatalog();
+    asyncHandler('GET /store/modules', async (req, res) => {
+      const raw = req.query && req.query.sort;
+      const sort = typeof raw === 'string' && raw ? raw : null;
+      if (sort && !SORT_PARTS.some((p) => p.part === sort)) {
+        const names = SORT_PARTS.map((p) => `${p.title} (${p.part})`).join(', ');
+        return res.fail('bad_request', { status: 400, message: `The store can be sorted by one part of the score: ${names}.` });
+      }
+      const listing = await listCatalog({ sort });
       res.set('Cache-Control', 'no-store');
       res.json(listing);
     }));

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.152'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.154'; // 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/github_failure.mjs

@@ -0,0 +1,79 @@
+// tests/github_failure.mjs — a failed GitHub call says WHICH step broke and what
+// GitHub answered (task 1004766).
+//
+// On the toast instance every GET /tasks/:id/publish-status answered a bare 502
+// `status_failed` with no message, and the server log carried one word. The thrown
+// errors already held the step (code) and GitHub's reply (status, detail).
+//
+// Run:  node tests/github_failure.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+const { describeGithubFailure } = require(path.join(ROOT, 'modules/lifecycle/github-failure.js'));
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${e.message}`); }
+}
+const thrown = (code, extra = {}) => Object.assign(new Error(code), { code }, extra);
+
+t('an App token refusal names the step and GitHub\'s answer', () => {
+  const r = describeGithubFailure(thrown('APP_TOKEN_FAILED', { status: 401, detail: '{"message":"A JSON web token could not be decoded"}' }));
+  assert.match(r.message, /GitHub App token/);
+  assert.match(r.message, /HTTP 401: \{"message":"A JSON web token could not be decoded"\}/);
+  assert.equal(r.details.cause, 'APP_TOKEN_FAILED');
+  assert.equal(r.details.github_status, 401);
+  assert.match(r.log, /APP_TOKEN_FAILED \(GitHub HTTP 401/);
+});
+
+t('a refused repository read is told apart from a token failure', () => {
+  const r = describeGithubFailure(thrown('STATUS_FETCH_FAILED', { status: 403 }));
+  assert.match(r.message, /refused a read of the repository/);
+  assert.match(r.message, /HTTP 403\./);
+  assert.equal(r.details.github_detail, null);
+});
+
+t('an unknown error still says something, and never invents a GitHub status', () => {
+  const r = describeGithubFailure(new Error('fetch failed'));
+  assert.match(r.message, /unexpected error/);
+  assert.doesNotMatch(r.message, /HTTP/);
+  assert.equal(r.details.cause, null);
+  assert.equal(r.log, 'fetch failed');
+});
+
+t('GitHub\'s detail is capped', () => {
+  const r = describeGithubFailure(thrown('APP_TOKEN_FAILED', { status: 500, detail: 'x'.repeat(5000) }));
+  assert.ok(r.details.github_detail.length <= 300);
+});
+
+t('publish-status sends the description, not a bare 502', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/routes/tasks.js'), 'utf8');
+  const i = src.indexOf("router.get('/tasks/:id/publish-status'");
+  const handler = src.slice(i, src.indexOf('router.', i + 20));
+  assert.match(handler, /failGithubStatus\(res, log, e\)/);
+  assert.doesNotMatch(handler, /res\.fail\('status_failed', 502\)/);
+});
+
+t('the route answer carries the message and logs the step', () => {
+  const { failGithubStatus } = require(path.join(ROOT, 'modules/lifecycle/github-failure.js'));
+  let sent = null;
+  const logged = [];
+  const res = { fail: (code, opts) => { sent = { code, ...opts }; return 'sent'; } };
+  const out = failGithubStatus(res, { error: (...a) => logged.push(a.join(' ')) }, thrown('APP_TOKEN_FAILED', { status: 401 }));
+  assert.equal(out, 'sent');
+  assert.equal(sent.code, 'status_failed');
+  assert.equal(sent.status, 502);
+  assert.match(sent.message, /GitHub App token.*HTTP 401/);
+  assert.match(logged[0], /APP_TOKEN_FAILED \(GitHub HTTP 401\)/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/github_install_nudge.mjs

@@ -0,0 +1,219 @@
+// tests/github_install_nudge.mjs — a project whose GitHub App is not installed keeps showing
+// its owner the install link (task 1004763).
+//
+// WHY. Toast (instance 52) was made before the wizard asked anyone to install the app (task
+// 1004649), so nobody did, and every ship ended land-not-proven: the platform could not read
+// the repo to see the merge. The install link lived only inside the creation wizard's
+// checklist. Now the owner's two reads carry `github_install`, and the project list card and
+// the project's own page say "Install the GitHub App" until the runner has seen the install.
+//
+// Three layers, DB-free and network-free:
+//   1. modules/provisioning/github-setup.js — installNudge (pure) and installNudgesFor (two reads for a whole list).
+//   2. the REAL list and instance routes over a mounted router: the field rides both.
+//   3. projects.html's ghInstallRow, groupFor and the click handler, run in a vm: the link on
+//      the card and the manage page, "Needs you", and the click asking for a re-check.
+//
+// Run:  node --test tests/github_install_nudge.mjs
+
+import assert from 'node:assert/strict';
+import { test, after } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GS = require(path.join(ROOT, 'modules', 'provisioning', 'github-setup.js'));
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+
+const INSTALL = 'https://github.com/apps/uattest-app/installations/new';
+const APP_ROW = { id: 9, instance_id: 56, status: 'done', app_id: 5, app_slug: 'uattest-app', state: 'SECRETSTATE', attempts: 1,
+  created_at: '2026-10-01T00:00:00Z', updated_at: '2026-10-01T00:05:00Z', resolved_at: '2026-10-01T00:05:00Z' };
+const INST = { id: 56, slug: 'uattest', status: 'active', target_ref: 'acme/uattest' };
+
+// ── 1. the helper ───────────────────────────────────────────────────────────
+
+test('installNudge: the link and repo while the install is unconfirmed, null otherwise', () => {
+  const setup = (install, url = INSTALL) => ({ checklist: { install }, install_url: url, repo: 'acme/uattest' });
+  assert.deepEqual(GS.installNudge(setup('now')), { install_url: INSTALL, repo: 'acme/uattest' });
+  assert.equal(GS.installNudge(setup('done')), null, 'GitHub confirmed it: nothing to say');
+  assert.equal(GS.installNudge(setup('todo', null)), null, 'no app of ours: nothing to install');
+  assert.equal(GS.installNudge(null), null);
+});
+
+// A fake pool answering the two batched reads from plain tables, counting the queries.
+function fakeDb({ attempts = [], installedEvents = [], fail = false } = {}) {
+  const db = { queries: 0 };
+  db.query = async (sql, params) => {
+    db.queries += 1;
+    if (fail) throw new Error('db down');
+    if (/FROM provisioning_oauth_manifests/.test(sql)) {
+      const ids = params[0].map(String);
+      return { rows: attempts.filter((r) => ids.includes(String(r.instance_id))) };
+    }
+    if (/FROM provisioning_events/.test(sql)) {
+      assert.equal(params[2], GS.SETUP_EVENTS.installed, 'only the verified install counts, never a report');
+      const since = new Map(params[0].map((id, i) => [String(id), Date.parse(params[1][i])]));
+      return { rows: installedEvents.filter((e) => since.has(String(e.instance_id)) && Date.parse(e.created_at) >= since.get(String(e.instance_id))) };
+    }
+    throw new Error(`unexpected query: ${sql}`);
+  };
+  return db;
+}
+
+test('installNudgesFor: two reads for the whole list; silent with no app, once installed, switched off, or on a failed read', async () => {
+  const insts = [
+    INST,
+    { id: 52, slug: 'toast', status: 'active', target_ref: 'acme/toast' },
+    { id: 13, slug: 'charter', status: 'active', target_ref: 'acme/charter' },
+    { id: 70, slug: 'gone', status: 'torn_down', target_ref: 'acme/gone' },
+    { id: 71, slug: 'old', status: 'active', target_ref: 'acme/old' },
+  ];
+  const db = fakeDb({
+    attempts: [
+      { instance_id: '56', app_slug: 'uattest-app', created_at: '2026-10-01T00:00:00Z' },
+      { instance_id: '52', app_slug: 'toast-app', created_at: '2026-10-01T00:00:00Z' },
+      { instance_id: '13', app_slug: null, created_at: '2026-10-01T00:00:00Z' },
+      { instance_id: '70', app_slug: 'gone-app', created_at: '2026-10-01T00:00:00Z' },
+      { instance_id: '71', app_slug: 'old-app', created_at: '2026-10-05T00:00:00Z' },
+    ],
+    installedEvents: [
+      { instance_id: '52', created_at: '2026-10-20T10:00:00Z' },
+      { instance_id: '71', created_at: '2026-10-02T00:00:00Z' },
+    ],
+  });
+  const n = await GS.installNudgesFor(db, insts);
+  assert.equal(db.queries, 2, 'two reads, however many projects');
+  assert.deepEqual(n.get('56'), { install_url: 'https://github.com/apps/uattest-app/installations/new', repo: 'acme/uattest' }, 'the stateless link: never the state token');
+  assert.equal(n.get('52'), null, 'the runner saw the install');
+  assert.equal(n.get('13'), null, 'no app was made: nothing to install');
+  assert.equal(n.get('70'), null, 'a switched-off project is silent');
+  assert.deepEqual(n.get('71'), { install_url: 'https://github.com/apps/old-app/installations/new', repo: 'acme/old' }, 'an install seen before the latest attempt began does not count for it');
+  const empty = fakeDb();
+  assert.equal((await GS.installNudgesFor(empty, [{ ...INST, status: 'torn_down' }])).get('56'), null);
+  assert.equal(empty.queries, 0, 'nothing live: no read at all');
+  const broken = await GS.installNudgesFor(fakeDb({ fail: true }), insts);
+  assert.ok([...broken.values()].every((v) => v === null), 'a failed read is no nudge, never a failed list');
+});
+
+test('the instance read: the nudge comes from the same checklist the wizard reads', () => {
+  const read = (install, url) => ({ checklist: { install }, install_url: url, repo: 'acme/uattest' });
+  assert.equal(GS.installNudge(read('now', INSTALL)).install_url, INSTALL);
+  assert.equal(GS.installNudge(read('todo', null)), null, 'no app: githubSetupRead gives no link, so no nudge');
+});
+
+// ── 2. the owner's two reads ────────────────────────────────────────────────
+
+test('GET /provisioning/instances and /provisioning/instances/:id carry github_install', async () => {
+  const provisioning = require(path.join(ROOT, 'modules', 'provisioning', 'provisioning.js'));
+  const api = require(path.join(ROOT, 'src', 'module-api.js'));
+  const catalogBridge = require(path.join(ROOT, 'modules', 'provisioning', 'catalog-bridge.js'));
+  const saved = {
+    list: provisioning.listInstancesForOwner, byId: provisioning.getInstanceById, open: provisioning.getOpenIntent,
+    latest: provisioning.getLatestOAuthManifestForInstance, rb: api.requireBuilder, heal: catalogBridge.healInstanceCatalog, facts: GS.githubSetupFacts,
+  };
+  const owned = [{ ...INST, owner_builder_id: 7 }, { id: 52, slug: 'toast', status: 'active', target_ref: 'acme/toast', owner_builder_id: 7 }];
+  provisioning.listInstancesForOwner = async () => owned;
+  provisioning.getInstanceById = async (_db, id) => owned.find((i) => Number(i.id) === Number(id)) || null;
+  provisioning.getOpenIntent = async () => null;
+  provisioning.getLatestOAuthManifestForInstance = async (_db, id) => ({ ...APP_ROW, instance_id: id, app_slug: `app-${id}` });
+  api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, rank: 'metic' }; next(); };
+  catalogBridge.healInstanceCatalog = async () => {};
+  GS.githubSetupFacts = async () => ({});
+  const realBatch = GS.installNudgesFor;
+  const listDb = fakeDb({
+    attempts: owned.map((i) => ({ instance_id: String(i.id), app_slug: `app-${i.id}`, created_at: '2026-10-01T00:00:00Z' })),
+    installedEvents: [{ instance_id: '52', created_at: '2026-10-20T10:00:00Z' }],
+  });
+  GS.installNudgesFor = (_pool, rows) => realBatch(listDb, rows);
+
+  const express = require('express');
+  const app = express();
+  app.use((_req, res, next) => { res.fail = (code, opts) => res.status(typeof opts === 'number' ? opts : (opts && opts.status) || 400).json({ error: { code } }); next(); });
+  app.use('/api/bongos', require(path.join(ROOT, 'modules', 'provisioning', 'routes', 'provisioning.js'))());
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  after(() => {
+    server.close();
+    Object.assign(provisioning, { listInstancesForOwner: saved.list, getInstanceById: saved.byId, getOpenIntent: saved.open, getLatestOAuthManifestForInstance: saved.latest });
+    api.requireBuilder = saved.rb; catalogBridge.healInstanceCatalog = saved.heal; GS.githubSetupFacts = saved.facts; GS.installNudgesFor = realBatch;
+  });
+  const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+  const list = await (await fetch(`${base}/provisioning/instances`)).json();
+  const by = Object.fromEntries(list.instances.map((i) => [i.slug, i]));
+  assert.deepEqual(by.uattest.github_install, { install_url: 'https://github.com/apps/app-56/installations/new', repo: 'acme/uattest' });
+  assert.equal(by.toast.github_install, null, 'installed: no nudge');
+  assert.equal(listDb.queries, 2, 'the list reads the nudges in two queries');
+
+  const one = await (await fetch(`${base}/provisioning/instances/56`)).json();
+  assert.deepEqual(one.instance.github_install, { install_url: 'https://github.com/apps/app-56/installations/new', repo: 'acme/uattest' });
+  assert.ok(!/SECRETSTATE/.test(JSON.stringify(one)) && !/SECRETSTATE/.test(JSON.stringify(list)), 'the state token never rides an owner read');
+  assert.equal(one.github_setup.checklist.install, 'now', 'the wizard checklist still rides the same read');
+});
+
+// ── 3. the page ─────────────────────────────────────────────────────────────
+
+function grab(head) {
+  const at = HUB.indexOf(`\n  ${head}`);
+  assert.ok(at >= 0, `${head} must exist`);
+  const end = HUB.indexOf('\n  }', at + 1);
+  const close = HUB.slice(end, end + 5) === '\n  };' ? end + 5 : end + 4;
+  return HUB.slice(at, close);
+}
+function page() {
+  const ctx = { STATE_GROUP: { active: 'live', error: 'attention', torn_down: 'gone' } };
+  vm.createContext(ctx);
+  vm.runInContext(['function esc(', 'function ghInstallRow(', 'function groupFor('].map(grab).join('\n'), ctx);
+  return ctx;
+}
+
+test('ghInstallRow: the install link on its own, for an unconfirmed install only', () => {
+  const p = page();
+  const html = p.ghInstallRow({ id: 56, status: 'active', github_install: { install_url: INSTALL, repo: 'acme/uattest' } });
+  assert.match(html, /Install the GitHub App ↗/);
+  assert.match(html, new RegExp(`href="${INSTALL.replace(/[.?/]/g, '\\$&')}" target="_blank" rel="noopener" data-gh-install="56"`));
+  assert.match(html, /<code>acme\/uattest<\/code>/);
+  assert.equal(p.ghInstallRow({ id: 52, status: 'active', github_install: null }), '');
+  assert.equal(p.ghInstallRow({ id: 56, status: 'torn_down', github_install: { install_url: INSTALL } }), '', 'switched off: silent');
+  assert.equal(p.ghInstallRow({ id: 56, status: 'active', github_install: { install_url: 'https://evil.example/x' } }), '', 'only GitHub\'s own app pages are linked');
+  assert.match(p.ghInstallRow({ id: 56, status: 'active', github_install: { install_url: INSTALL, repo: '<b>x</b>' } }), /&lt;b&gt;/, 'the repo is escaped');
+});
+
+test('groupFor: a project waiting on the install counts under Needs you', () => {
+  const p = page();
+  assert.equal(p.groupFor({ status: 'active', last_verified_up: true, github_install: { install_url: INSTALL } }), 'attention');
+  assert.equal(p.groupFor({ status: 'active', last_verified_up: true, github_install: null }), 'live');
+});
+
+test('the card and the project\'s own page both draw it', () => {
+  assert.match(grab('function renderCard('), /var gh = ghInstallRow\(inst\);\n    if \(gh\) body \+= '<div class="projMsg">' \+ gh \+ '<\/div>';/);
+  assert.match(grab('function renderManage('), /var gh = ghInstallRow\(inst\);\n    \$\('mGh'\)\.innerHTML = gh;\n    \$\('mGh'\)\.hidden = !gh;/);
+  assert.match(HUB, /<div class="projMsg" id="mGh" hidden><\/div>/);
+});
+
+test('the click opens GitHub and asks the platform to look again', async () => {
+  const at = HUB.indexOf("\n  document.addEventListener('click', function (ev) {\n    var a = ev.target.closest && ev.target.closest('a[data-gh-install]');");
+  assert.ok(at >= 0, 'the install click handler must exist');
+  const src = HUB.slice(at, HUB.indexOf('\n  });', at) + 6);
+  let listener = null;
+  const calls = [];
+  const ctx = {
+    API: '/api/bongos',
+    document: { addEventListener: (type, fn) => { if (type === 'click') listener = fn; } },
+    fetch: (url, opts) => { calls.push({ url, opts }); return Promise.resolve({ ok: true }); },
+  };
+  vm.createContext(ctx);
+  vm.runInContext(src, ctx);
+  let prevented = false;
+  const link = { getAttribute: (k) => (k === 'data-gh-install' ? '56' : null) };
+  listener({ target: { closest: (sel) => (sel === 'a[data-gh-install]' ? link : null) }, preventDefault: () => { prevented = true; } });
+  assert.equal(prevented, false, 'the link still opens GitHub');
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].url, '/api/bongos/provisioning/instances/56/github-app/pick-up');
+  assert.equal(calls[0].opts.method, 'POST');
+  listener({ target: { closest: () => null }, preventDefault() {} });
+  assert.equal(calls.length, 1, 'any other click asks nothing');
+});

package/tests/hall_catalog_world.mjs

@@ -39,7 +39,7 @@ const noAlias = (rawCss, where) => {
 
 // ---- modules ----------------------------------------------------------------
 
-test('modules: ONE panel of family rows — the filter bar, the figure band and two groups on one .scroll', () => {
+test('modules: ONE panel of family rows — the filter bar, the figure band and two groups on one .scroll (a third, the store, since task 1003799)', () => {
   const html = read('modules.html');
   assert.match(html, /<link rel="stylesheet" href="\/builders\/oversight\.css">\s*<link rel="stylesheet" href="\/builders\/modules\.css">/, 'the family sheet loads before the page sheet');
   assert.equal((html.match(/class="scroll[ "]/g) || []).length, 1, 'one panel, not three');
@@ -47,7 +47,7 @@ test('modules: ONE panel of family rows — the filter bar, the figure band and
   assert.match(html, /class="ov-figs" id="mod-figs"/, 'the figure band is the family\'s');
   assert.match(html, /<ul class="ov-rows" id="core-grid">/, 'the core catalog is a run of rows');
   assert.match(html, /<ul class="ov-rows" id="own-grid">/, 'the project\'s own modules are a run of rows');
-  assert.equal((html.match(/class="ov-group__head"/g) || []).length, 2, 'two group heads');
+  assert.equal((html.match(/class="ov-group__head"/g) || []).length, 3, 'three group heads: the core, this project, the store');
   assert.doesNotMatch(decomment(html), /mod-grid|mod-card|mod-browse|submit-scroll|class="settings-status"/, 'the card grid, the boxed search and the third panel are gone');
   assert.doesNotMatch(html, /\d+ module\(s\)/, 'the page head no longer says the numbers as prose');
 });
@@ -89,6 +89,35 @@ test('modules: upkeep colours the exception — undeclared is the warn pill, mai
   assert.match(js, /cat\.parentTitle, cat\.sub\]/, 'the hall search covers the category, as searchCatalog does');
 });
 
+test('modules: the store group reads strengths and weaknesses off the server row (task 1003799)', () => {
+  const js = read('modules.js');
+  const html = read('modules.html');
+  assert.match(html, /<div class="ov-group" id="store-group" hidden>/, 'the store group is hidden until the store answers');
+  assert.match(html, /<ul class="ov-rows" id="store-grid"><\/ul>/);
+  assert.match(js, /api\.request\('GET', `\$\{API\}\/store\/modules\$\{q\}`\)/, 'it reads GET /store/modules');
+  assert.match(js, /<span class="ov-fact">strong at \$\{partsList\(strong\)\}<\/span>/, 'a strength is a plain fact');
+  assert.match(js, /<span class="fact-pill fact-pill--warn">weak at \$\{partsList\(weak\)\}<\/span>/, 'a weakness is the warn pill');
+  assert.match(js, /not measured yet/, 'a part with no data is named, never counted as weak');
+  assert.match(js, /<details class="mod-more"[^`]*Strengths and weaknesses of/, 'the detail sentence is one click away');
+  assert.doesNotMatch(decomment(js), /score\s*>=\s*80|STRONG_AT/, 'the page does not re-derive the reading — the server owns the thresholds');
+  const fixture = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', 'store__modules.json'), 'utf8'));
+  const two = fixture.listed.filter((m) => m.overall === 74);
+  assert.equal(two.length, 2, 'the harness shows the criterion: two modules on the same score');
+  assert.notDeepEqual(two[0].strengths.map((s) => s.part), two[1].strengths.map((s) => s.part), '…that are strong at different things');
+});
+
+test('modules: the buyer sorts the store by the part that matters to them (task 1003800)', () => {
+  const js = read('modules.js');
+  const html = read('modules.html');
+  assert.match(html, /<select id="store-sort"><option value="">Name<\/option><\/select>/, 'the menu starts at name order');
+  assert.match(js, /\?sort=\$\{encodeURIComponent\(storeSort\)\}/, 'the server orders the list; the page asks for a part');
+  assert.match(js, /fillStoreSort\(body\.sort_parts\)/, 'the parts on the menu are the server\'s list');
+  assert.doesNotMatch(decomment(js), /\.sort\(\(a, b\)/, 'the page does not re-sort the store rows itself');
+  assert.match(js, /not measured yet<\/span>/, 'a row with no score for the sorted part says so, not a zero');
+  const fixture = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', 'store__modules.json'), 'utf8'));
+  assert.deepEqual(fixture.sort_parts.map((p) => p.part), ['tests', 'install', 'reliability', 'tester_feedback', 'docs'], 'the harness carries the menu');
+});
+
 test('modules: the kit filter bar carries the search and a state lens, and the empty state is the kit\'s', () => {
   const js = read('modules.js');
   assert.match(js, /kit\.makeFilterBar\(\{/, 'the bar is the kit\'s');

package/tests/module_store_listing.mjs

@@ -15,7 +15,7 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 
 // ---- the fake registry the route reads ----
-const state = { modules: {}, versions: [], scores: [] };
+const state = { modules: {}, versions: [], scores: [], signals: [] };
 const pool = {
   async query(sql, params = []) {
     if (/FROM store_modules m JOIN store_module_versions v/.test(sql)) {
@@ -35,6 +35,17 @@ const pool = {
       }
       return { rows: [...newest.values()] };
     }
+    if (/FROM module_assessment_signals/.test(sql)) {
+      const ids = params[0].map(String);
+      const newest = new Map();
+      for (const s of state.signals) {
+        if (!ids.includes(String(s.version_id))) continue;
+        const k = `${s.version_id}:${s.part}`;
+        const have = newest.get(k);
+        if (!have || s.measured_at > have.measured_at || (s.measured_at === have.measured_at && s.id > have.id)) newest.set(k, s);
+      }
+      return { rows: [...newest.values()] };
+    }
     return { rows: [] };
   },
 };
@@ -42,7 +53,7 @@ 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 { QUALITY_FLOOR, placeVersion } = require('../src/bongos/module-listing.js');
+const { QUALITY_FLOOR, SORT_PARTS, placeVersion, sortByPart } = require('../src/bongos/module-listing.js');
 
 function handlerFor(router, method, p) {
   const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
@@ -152,5 +163,147 @@ test('GET /store/modules: an empty store answers empty lists and the floor', asy
   state.modules = {}; state.versions = []; state.scores = [];
   const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules');
   const res = await invoke(handle, {});
-  assert.deepEqual(res.body, { floor: 50, listed: [], new: [] });
+  assert.deepEqual(res.body, { floor: 50, sort: null, sort_parts: SORT_PARTS, listed: [], new: [] });
+});
+
+// ---------------------------------------------------------------------------
+// sort by the part a buyer cares about (task 1003800, owner decision 2026-10-22)
+// ---------------------------------------------------------------------------
+
+const entry = (key, overall, partScores) => ({
+  key, overall,
+  parts: Object.fromEntries(Object.entries(partScores).map(([p, s]) => [p, { outcome: s == null ? 'no_data' : 'scored', score: s, sample_size: null }])),
+});
+
+test('sortByPart: highest first for the chosen part; a tie goes to the overall score, then the key', () => {
+  const out = sortByPart([
+    entry('b-mod', 70, { reliability: 90 }),
+    entry('a-mod', 70, { reliability: 90 }),
+    entry('steady', 60, { reliability: 95 }),
+    entry('higher', 80, { reliability: 90 }),
+  ], 'reliability');
+  assert.deepEqual(out.map((e) => e.key), ['steady', 'higher', 'a-mod', 'b-mod']);
+});
+
+test('sortByPart: a module with no score for the part goes last, never first, and the input is untouched', () => {
+  const input = [entry('z-unmeasured', 99, { reliability: null }), entry('low', 55, { reliability: 10 }), entry('a-missing', 99, {})];
+  const out = sortByPart(input, 'reliability');
+  assert.deepEqual(out.map((e) => e.key), ['low', 'a-missing', 'z-unmeasured']);
+  assert.equal(input[0].key, 'z-unmeasured', 'a new array; the listing it came from keeps its order');
+});
+
+test('SORT_PARTS: every part a buyer compares, Security not among them', () => {
+  assert.deepEqual(SORT_PARTS.map((p) => p.part), ['tests', 'install', 'reliability', 'tester_feedback', 'docs']);
+});
+
+test('GET /store/modules?sort=: orders the listed modules by the part, leaves New in key order', async () => {
+  state.modules = {
+    tested: { status: 'listed', title: 'Tested' }, steady: { status: 'listed', title: 'Steady' },
+    'b-new': { status: 'listed', title: 'B new' }, 'a-new': { status: 'listed', title: 'A new' },
+  };
+  state.versions = [
+    { id: 21, module_key: 'tested', version: '1.0.0', published_at: 't' },
+    { id: 22, module_key: 'steady', version: '1.0.0', published_at: 't' },
+    { id: 23, module_key: 'b-new', version: '1.0.0', published_at: 't' },
+    { id: 24, module_key: 'a-new', version: '1.0.0', published_at: 't' },
+  ];
+  state.scores = [
+    { id: 21, version_id: 21, computed_at: 1, ...score({ overall: 74 }) },
+    { id: 22, version_id: 22, computed_at: 1, ...score({ overall: 74 }) },
+    { id: 23, version_id: 23, computed_at: 1, ...score({ is_new: true }) },
+    { id: 24, version_id: 24, computed_at: 1, ...score({ is_new: true }) },
+  ];
+  state.signals = [
+    { id: 21, version_id: 21, measured_at: 1, ...sig('tests', 96) },
+    { id: 22, version_id: 21, measured_at: 1, ...sig('reliability', 52) },
+    { id: 23, version_id: 22, measured_at: 1, ...sig('tests', 58) },
+    { id: 24, version_id: 22, measured_at: 1, ...sig('reliability', 91) },
+    { id: 25, version_id: 23, measured_at: 1, ...sig('reliability', 99) },
+  ];
+  const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules');
+  const byRel = await invoke(handle, { query: { sort: 'reliability' } });
+  assert.equal(byRel.body.sort, 'reliability');
+  assert.deepEqual(byRel.body.listed.map((m) => m.key), ['steady', 'tested'], 'the buyer who cares about reliability sees Steady first');
+  assert.deepEqual(byRel.body.new.map((m) => m.key), ['a-new', 'b-new'], 'New is never ranked, whatever the buyer picks');
+  const byTests = await invoke(handle, { query: { sort: 'tests' } });
+  assert.deepEqual(byTests.body.listed.map((m) => m.key), ['tested', 'steady']);
+  const plain = await invoke(handle, { query: {} });
+  assert.equal(plain.body.sort, null);
+  assert.deepEqual(plain.body.listed.map((m) => m.key), ['steady', 'tested'], 'no sort is key order, as before');
+  state.signals = [];
+});
+
+test('GET /store/modules?sort=: a part it does not know is refused, Security included', async () => {
+  const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules');
+  for (const sort of ['security', 'price', 'overall']) {
+    const res = await invoke(handle, { query: { sort } });
+    assert.equal(res.statusCode, 400, `${sort} is not a part to sort by`);
+    assert.match(res.body.message, /Tests \(tests\), Clean installs \(install\), Reliability \(reliability\), Tester feedback \(tester_feedback\), How-to \(docs\)/, 'the refusal names each part as a person says it, with the value to send');
+  }
+});
+
+// ---------------------------------------------------------------------------
+// strengths and weaknesses (task 1003799, ADR 0343 D4)
+// ---------------------------------------------------------------------------
+
+const { readParts, STRONG_AT } = require('../src/bongos/module-listing.js');
+const sig = (part, score, extra = {}) => ({ part, outcome: 'scored', score, sample_size: null, ...extra });
+
+test('readParts: a part at or above STRONG_AT is a strength, below the floor a weakness, between is neither', () => {
+  assert.equal(STRONG_AT, 80);
+  const r = readParts([sig('tests', 80), sig('install', 79), sig('reliability', 49), sig('docs', 50)]);
+  assert.deepEqual(r.strengths.map((s) => s.part), ['tests']);
+  assert.deepEqual(r.weaknesses.map((s) => s.part), ['reliability']);
+  assert.deepEqual(r.unmeasured.map((s) => s.part), ['tester_feedback'], 'a part with no row is unmeasured');
+});
+
+test('readParts: an unmeasured part is never a weakness, and Security is never listed', () => {
+  const r = readParts([
+    { part: 'security', outcome: 'passed', score: null },
+    { part: 'install', outcome: 'no_data', score: null },
+    { part: 'reliability', outcome: 'pending', score: null },
+    { part: 'tester_feedback', outcome: 'not_scored', score: null },
+    sig('tests', 10),
+  ]);
+  assert.deepEqual(r.weaknesses.map((s) => s.part), ['tests']);
+  assert.deepEqual(r.unmeasured.map((s) => s.part), ['install', 'reliability', 'tester_feedback', 'docs']);
+  for (const list of [r.strengths, r.weaknesses, r.unmeasured]) assert.ok(!list.some((s) => s.part === 'security'));
+  assert.ok(!('security' in r.parts), 'the gate is not one of the parts a buyer compares');
+  assert.deepEqual(r.parts.install, { outcome: 'no_data', score: null, sample_size: null });
+});
+
+test('readParts: strongest first, weakest first, and the detail says what the number rests on', () => {
+  const r = readParts([sig('tests', 85, { sample_size: 40 }), sig('docs', 95), sig('install', 30, { sample_size: 1 }), sig('reliability', 45, { sample_size: 12 })]);
+  assert.deepEqual(r.strengths.map((s) => [s.part, s.score]), [['docs', 95], ['tests', 85]]);
+  assert.deepEqual(r.weaknesses.map((s) => [s.part, s.score]), [['install', 30], ['reliability', 45]]);
+  assert.equal(r.strengths[1].detail, 'Tests scored 85 out of 100, from 40 test cases.');
+  assert.equal(r.weaknesses[0].detail, 'Clean installs scored 30 out of 100, from 1 install.');
+  assert.equal(r.strengths[0].detail, 'How-to scored 95 out of 100.');
+});
+
+test('the criterion: two modules with the same overall score read differently', async () => {
+  state.modules = { steady: { status: 'listed', title: 'Steady' }, tested: { status: 'listed', title: 'Tested' } };
+  state.versions = [
+    { id: 11, module_key: 'steady', version: '1.0.0', published_at: 't' },
+    { id: 12, module_key: 'tested', version: '1.0.0', published_at: 't' },
+  ];
+  state.scores = [
+    { id: 11, version_id: 11, computed_at: 1, ...score({ overall: 74 }) },
+    { id: 12, version_id: 12, computed_at: 1, ...score({ overall: 74 }) },
+  ];
+  state.signals = [
+    { id: 1, version_id: 11, measured_at: 1, ...sig('tests', 58) },
+    { id: 2, version_id: 11, measured_at: 1, ...sig('reliability', 40) }, // superseded below
+    { id: 3, version_id: 11, measured_at: 2, ...sig('reliability', 90) },
+    { id: 4, version_id: 12, measured_at: 1, ...sig('tests', 96) },
+    { id: 5, version_id: 12, measured_at: 1, ...sig('reliability', 52) },
+  ];
+  const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules');
+  const res = await invoke(handle, {});
+  const by = Object.fromEntries(res.body.listed.map((m) => [m.key, m]));
+  assert.equal(by.steady.overall, by.tested.overall);
+  assert.deepEqual(by.steady.strengths.map((s) => s.part), ['reliability'], 'the newest reliability row wins');
+  assert.deepEqual(by.tested.strengths.map((s) => s.part), ['tests']);
+  assert.equal(by.steady.parts.reliability.score, 90);
+  state.signals = [];
 });