@bongos/core 1.21.155 → 1.21.157

package/src/bongos/module-testing.js

@@ -0,0 +1,73 @@
+// src/bongos/module-testing.js — whether this project tests new module versions
+// first (task 1003802, criterion wa5 staged rollout, ADR 0344 D1).
+//
+// A PROJECT opts in, once, and it is the project's own admin who does it: the
+// project is what runs the module, so no builder can volunteer someone else's
+// project. A tester project gets tester-channel versions of every module it has,
+// except the modules it marked "general only". Both choices are reversible, and
+// "willing" is load-bearing: a project is never a tester by default, and a choice
+// that cannot be read reads as NOT a tester (an early version nobody chose is an
+// early victim, not a tester).
+//
+// Storage is two project_settings rows (src/bongos/project-settings.js), the same
+// durable, survives-a-deploy store the project's other knobs use, so no new table:
+//
+//   modules.tester        'on' | 'off'              absent = off
+//   modules.general_only  JSON array of module keys  absent = []
+//
+// This file records the choice and answers it. Handing a tester project tester
+// versions is task 1003805, which asks testsVersionsOf(key).
+
+const { getSetting, setSetting, SETTING_KEYS } = require('./project-settings');
+const { KEY_RE } = require('../module-loader/manifest-schema');
+
+function parseTester(raw) {
+  return raw === 'on';
+}
+
+// A stored list that will not parse, or holds something that is not a key, keeps
+// only the keys it can read: losing a "general only" mark would hand a project an
+// early version of a module it asked to keep on general.
+function parseGeneralOnly(raw) {
+  if (raw == null) return [];
+  let list;
+  try { list = JSON.parse(raw); } catch { return []; }
+  if (!Array.isArray(list)) return [];
+  return [...new Set(list.filter((k) => typeof k === 'string' && KEY_RE.test(k)))].sort();
+}
+
+// { tester, general_only, updated_at, updated_by } — updated_* from the switch row.
+async function readTesting(deps = {}) {
+  const get = deps.getSetting || getSetting;
+  const [t, g] = await Promise.all([get(SETTING_KEYS.MODULE_TESTER), get(SETTING_KEYS.MODULE_GENERAL_ONLY)]);
+  return {
+    tester: parseTester(t && t.value),
+    general_only: parseGeneralOnly(g && g.value),
+    updated_at: t ? t.updated_at : null,
+    updated_by: t && t.updated_by != null ? String(t.updated_by) : null,
+  };
+}
+
+async function setTester(on, builderId = null, deps = {}) {
+  const set = deps.setSetting || setSetting;
+  await set(SETTING_KEYS.MODULE_TESTER, on ? 'on' : 'off', builderId);
+  return readTesting(deps);
+}
+
+async function setGeneralOnly(moduleKey, on, builderId = null, deps = {}) {
+  if (!KEY_RE.test(String(moduleKey))) throw new Error(`not a module key: ${moduleKey}`);
+  const set = deps.setSetting || setSetting;
+  const now = await readTesting(deps);
+  const keys = new Set(now.general_only);
+  if (on) keys.add(moduleKey); else keys.delete(moduleKey);
+  await set(SETTING_KEYS.MODULE_GENERAL_ONLY, JSON.stringify([...keys].sort()), builderId);
+  return readTesting(deps);
+}
+
+// Whether this project takes tester-channel versions of one module. Pure over a
+// readTesting() result.
+function testsVersionsOf(testing, moduleKey) {
+  return !!(testing && testing.tester && !testing.general_only.includes(moduleKey));
+}
+
+module.exports = { readTesting, setTester, setGeneralOnly, testsVersionsOf, parseGeneralOnly };

package/src/bongos/project-settings.js

@@ -53,6 +53,9 @@ const SETTING_KEYS = {
   TWEAK_AUTOPICKUP: 'tweak.autopickup',
   TWEAK_AUTOPICKUP_CAP: 'tweak.autopickup_monthly_cap',
   SPEND_CAP: 'treasury.spend_cap_usd',
+  // Testing new module versions first (task 1003802, ADR 0344 D1): module-testing.js.
+  MODULE_TESTER: 'modules.tester',
+  MODULE_GENERAL_ONLY: 'modules.general_only',
 };
 
 // SHIP MODE (task 1004628, ADR 0369) — WHO starts a ship, never HOW it lands.

package/src/bongos/routes/modules.js

@@ -111,6 +111,7 @@ const log = require('../logger').logger.child({ src: 'modules' });
 // as unused exports and tripped the dead-code ratchet that held this branch out of main.
 const { listOverrides, setOverride } = require('../module-overrides');
 const { listCatalog, SORT_PARTS } = require('../module-listing');
+const { readTesting, setTester, setGeneralOnly } = require('../module-testing');
 
 // The sentence for a toggle that waits on a restart (task 1004463). 'routes' are the
 // module's pages, 'pollers' its background jobs. PURE.
@@ -333,6 +334,48 @@ module.exports = function buildModulesRouter() {
       });
     }));
 
+  // Testing new module versions first (task 1003802, ADR 0344 D1): whether THIS
+  // project gets tester-channel versions, and which modules it keeps on general.
+  // A read anyone signed in can make: the switch is meant to be visible.
+  //
+  // rank: any-builder — a read of this project's own setting; nothing changes.
+  router.get('/modules/testing', auth.requireBuilder,
+    asyncHandler('GET /modules/testing', async (_req, res) => {
+      res.set('Cache-Control', 'no-store');
+      res.json(await readTesting());
+    }));
+
+  // rank: metic+archon — the project's admin volunteers the whole project, so it
+  // takes the same permission that chooses which modules this project runs
+  // (module.enable): a builder cannot opt in a project they cannot run modules for.
+  router.post('/modules/testing', auth.requireBuilder, auth.requirePermission('module.enable'),
+    asyncHandler('POST /modules/testing', async (req, res) => {
+      if (validateOrRespond(req, res, { tester: { type: 'boolean', required: true } })) return;
+      const out = await setTester(req.body.tester, req.builder && req.builder.id);
+      log.info({ tester: out.tester, builder: req.builder && req.builder.id }, 'module testing switched');
+      res.json({
+        ok: true,
+        ...out,
+        note: out.tester
+          ? 'This project now gets new module versions first, except the modules marked general only.'
+          : 'This project is back on general versions from its next update.',
+      });
+    }));
+
+  // rank: metic+archon — same reasoning as POST /modules/testing: which versions
+  // a module arrives in is part of choosing the modules this project runs.
+  router.post('/modules/:key/general-only', auth.requireBuilder, auth.requirePermission('module.enable'),
+    asyncHandler('POST /modules/:key/general-only', async (req, res) => {
+      const { key } = req.params;
+      if (!KEY_RE.test(key)) return res.fail('bad_module_key', { status: 400, message: 'A module key is lowercase kebab-case.' });
+      if (validateOrRespond(req, res, { general_only: { type: 'boolean', required: true } })) return;
+      if (!listModules().some((m) => m.key === key)) {
+        return res.fail('not_found', { status: 404, message: `This project has no module "${key}".` });
+      }
+      const out = await setGeneralOnly(key, req.body.general_only, req.builder && req.builder.id);
+      res.json({ ok: true, key, general_only_this: out.general_only.includes(key), ...out });
+    }));
+
   // POST /api/bongos/modules/:key/submit — ADR 0107 §1 upstreaming submission.
   //
   // task 1770. Body: { signed_by?: "Name <email>" }. Re-runs the §4

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.155'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.157'; // 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

@@ -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 (a third, the store, since task 1003799)', () => {
+test('modules: ONE panel of family rows — the filter bar, the figure band and two groups on one .scroll (the store since task 1003799, testing since task 1003802)', () => {
   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, 3, 'three group heads: the core, this project, the store');
+  assert.equal((html.match(/class="ov-group__head"/g) || []).length, 4, 'four group heads: the core, this project, testing, 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');
 });
@@ -106,6 +106,22 @@ test('modules: the store group reads strengths and weaknesses off the server row
   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 project opts in to testing new versions, and can keep a module on general (task 1003802)', () => {
+  const js = read('modules.js');
+  const html = read('modules.html');
+  assert.match(html, /<div class="ov-group" id="testing-group" hidden>/, 'hidden until the switch is read');
+  assert.match(html, /It is never switched on for you\./, 'the page says a project is never a tester by default');
+  assert.match(js, /api\.request\('GET', `\$\{API\}\/modules\/testing`\)/, 'it reads GET /modules/testing');
+  assert.match(js, /`\$\{API\}\/modules\/testing`, \{ tester: next \}/, 'the switch posts an explicit true or false');
+  assert.match(js, /\/modules\/\$\{encodeURIComponent\(key\)\}\/general-only`, \{ general_only: on \}/, 'a module is kept on general by its own key');
+  assert.match(js, /class="ov-toggle mod-testing"/, 'the switch is the family grant toggle');
+  assert.match(js, /if \(!testing \|\| !testing\.tester\) return '';/, 'the per-module line appears only while the project is testing');
+  assert.match(js, /if \(!canToggle\) return escapeHtml\(says\);/, 'a builder who cannot switch it reads the state, with no dead control');
+  const fixture = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', 'modules__testing.json'), 'utf8'));
+  assert.equal(fixture.tester, true, 'the harness demos the switch on');
+  assert.ok(fixture.general_only.length >= 1, '…with a module kept on general');
+});
+
 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');

package/tests/module_testing.mjs

@@ -0,0 +1,171 @@
+// tests/module_testing.mjs — a project elects to test new module versions first
+// (task 1003802, ADR 0344 D1). Two halves, no port and no real DB:
+//   - the rule: module-testing.js over an in-memory project_settings, through
+//     its deps seam — never a tester by default, reversible, "general only";
+//   - the routes: the real handlers off the real router, with pool.js replaced
+//     in the require cache (the tests/module_store_listing.mjs harness).
+//
+// Run:  node tests/module_testing.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// ---- an in-memory project_settings, behind the real setSetting/getSetting SQL ----
+const rows = new Map();
+const pool = {
+  async query(sql, params = []) {
+    if (/FROM project_settings WHERE key = \$1/.test(sql)) {
+      const r = rows.get(params[0]);
+      return { rows: r ? [r] : [] };
+    }
+    if (/INSERT INTO project_settings/.test(sql)) {
+      const r = { key: params[0], value: params[1], updated_by: params[2], updated_at: 't' };
+      rows.set(params[0], r);
+      return { rows: [r] };
+    }
+    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 { readTesting, setTester, setGeneralOnly, testsVersionsOf, parseGeneralOnly } = require('../src/bongos/module-testing.js');
+const buildModulesRouter = require('../src/bongos/routes/modules.js');
+const { listModules } = buildModulesRouter;
+
+function handlerFor(router, method, p) {
+  const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
+  assert.ok(layer, `no ${method.toUpperCase()} ${p} on the router`);
+  const stack = layer.route.stack;
+  return { handle: stack[stack.length - 1].handle, names: stack.map((s) => s.name) };
+}
+
+async function invoke(handle, req) {
+  const res = {
+    statusCode: 200, body: undefined, headers: {},
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    set(k, v) { this.headers[k] = v; return this; },
+    // Both shapes res.fail is called with: (code, { status, message }) and the
+    // validator's (code, 400, details).
+    fail(code, opts) {
+      const o = typeof opts === 'number' ? { status: opts } : opts;
+      this.statusCode = o.status; this.body = { error: code, ...o }; return this;
+    },
+  };
+  let nextErr = null;
+  await handle({ params: {}, body: {}, builder: { id: 7 }, ...req }, res, (err) => { nextErr = err; });
+  if (nextErr) throw nextErr;
+  return res;
+}
+
+// ---------------------------------------------------------------------------
+// the rule
+// ---------------------------------------------------------------------------
+
+test('a project is never a tester by default', async () => {
+  rows.clear();
+  const t = await readTesting();
+  assert.deepEqual(t, { tester: false, general_only: [], updated_at: null, updated_by: null });
+  assert.equal(testsVersionsOf(t, 'discord'), false);
+});
+
+test('opting in is an act, and it is reversible', async () => {
+  rows.clear();
+  const on = await setTester(true, 7);
+  assert.equal(on.tester, true);
+  assert.equal(on.updated_by, '7', 'who switched it is recorded');
+  assert.equal(testsVersionsOf(on, 'discord'), true);
+  const off = await setTester(false, 7);
+  assert.equal(off.tester, false);
+  assert.equal(testsVersionsOf(off, 'discord'), false);
+});
+
+test('a module marked general only keeps general versions while the rest test', async () => {
+  rows.clear();
+  await setTester(true, 7);
+  await setGeneralOnly('economy', true, 7);
+  const t = await setGeneralOnly('discord', true, 7);
+  assert.deepEqual(t.general_only, ['discord', 'economy']);
+  assert.equal(testsVersionsOf(t, 'economy'), false);
+  assert.equal(testsVersionsOf(t, 'memory'), true);
+  const back = await setGeneralOnly('economy', false, 7);
+  assert.deepEqual(back.general_only, ['discord']);
+  assert.equal(testsVersionsOf(back, 'economy'), true);
+});
+
+test('a "general only" mark survives the switch going off and on', async () => {
+  rows.clear();
+  await setTester(true, 7);
+  await setGeneralOnly('economy', true, 7);
+  await setTester(false, 7);
+  const t = await setTester(true, 7);
+  assert.deepEqual(t.general_only, ['economy']);
+});
+
+test('an unreadable stored value reads as NOT a tester, and keeps the keys it can read', async () => {
+  rows.clear();
+  rows.set('modules.tester', { key: 'modules.tester', value: 'yes please', updated_by: null, updated_at: 't' });
+  assert.equal((await readTesting()).tester, false, 'only "on" is on');
+  assert.deepEqual(parseGeneralOnly('not json'), []);
+  assert.deepEqual(parseGeneralOnly('{"a":1}'), []);
+  assert.deepEqual(parseGeneralOnly('["economy", 4, "Bad Key", "economy", "discord"]'), ['discord', 'economy']);
+});
+
+test('setGeneralOnly refuses something that is not a module key', async () => {
+  await assert.rejects(() => setGeneralOnly('../etc', true, 7), /not a module key/);
+});
+
+// ---------------------------------------------------------------------------
+// the routes
+// ---------------------------------------------------------------------------
+
+test('GET /modules/testing: any signed-in builder can see the switch', async () => {
+  rows.clear();
+  const { handle, names } = handlerFor(buildModulesRouter(), 'get', '/modules/testing');
+  assert.equal(names.length, 2, `expected requireBuilder + handler, got ${names.join(', ')}`);
+  const res = await invoke(handle, {});
+  assert.equal(res.body.tester, false);
+  assert.equal(res.headers['Cache-Control'], 'no-store');
+});
+
+test('POST /modules/testing and /modules/:key/general-only take the module.enable permission', () => {
+  const router = buildModulesRouter();
+  for (const p of ['/modules/testing', '/modules/:key/general-only']) {
+    const { names } = handlerFor(router, 'post', p);
+    assert.equal(names.length, 3, `${p}: requireBuilder + requirePermission + handler, got ${names.join(', ')}`);
+  }
+  const src = require('node:fs').readFileSync(require.resolve('../src/bongos/routes/modules.js'), 'utf8');
+  assert.match(src, /router\.post\('\/modules\/testing', auth\.requireBuilder, auth\.requirePermission\('module\.enable'\)/);
+  assert.match(src, /router\.post\('\/modules\/:key\/general-only', auth\.requireBuilder, auth\.requirePermission\('module\.enable'\)/);
+});
+
+test('POST /modules/testing: switches on and off, and says what it means', async () => {
+  rows.clear();
+  const { handle } = handlerFor(buildModulesRouter(), 'post', '/modules/testing');
+  const on = await invoke(handle, { body: { tester: true } });
+  assert.equal(on.body.tester, true);
+  assert.match(on.body.note, /new module versions first/);
+  const off = await invoke(handle, { body: { tester: false } });
+  assert.equal(off.body.tester, false);
+  assert.match(off.body.note, /back on general versions from its next update/);
+  const bad = await invoke(handle, { body: { tester: 'on' } });
+  assert.equal(bad.statusCode, 400, 'an affirmative act is a boolean, not a string that looks like one');
+});
+
+test('POST /modules/:key/general-only: only a module this project has', async () => {
+  rows.clear();
+  const { handle } = handlerFor(buildModulesRouter(), 'post', '/modules/:key/general-only');
+  const known = listModules()[0].key;
+  const ok = await invoke(handle, { params: { key: known }, body: { general_only: true } });
+  assert.equal(ok.statusCode, 200);
+  assert.equal(ok.body.general_only_this, true);
+  assert.deepEqual(ok.body.general_only, [known]);
+  const missing = await invoke(handle, { params: { key: 'no-such-module-here' }, body: { general_only: true } });
+  assert.equal(missing.statusCode, 404);
+  const badKey = await invoke(handle, { params: { key: 'Not_A_Key' }, body: { general_only: true } });
+  assert.equal(badKey.statusCode, 400);
+});