@bongos/core 1.20.55 → 1.20.56

package/release-notes.json

@@ -8447,5 +8447,11 @@
       "id": "1004478",
       "text": "The recommended ranks on the Government page now say in plain words what each one can do, for example \"Check finished work, vote on tasks, and sort incoming ideas\", instead of listing system codes. The confirmation after addin"
     }
+  ],
+  "1.20.56": [
+    {
+      "id": "1004424",
+      "text": "Everyone who joins a project while it is being founded now becomes a founding builder, numbered in the order they arrived, and the owner is marked founder. The mark shows as a small seed badge on the builders list and on their"
+    }
   ]
 }

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

@@ -0,0 +1,263 @@
+// tests/founding_builders.mjs — THE FOUNDING MARK (task 1004424 / BV2.PS10, goal 1000121).
+//
+// Everyone who joins while a project is founding becomes a founding builder, numbered in
+// join order, with the stage they joined at; the founder is "founder". It is a mark, not
+// a rank (spec D1). Done-when: joiners during genesis are numbered and marked on all
+// four surfaces (roster, profile, ranks, the founding wall on Home), and joiners after
+// it are not. The blend rule rides along: a project that was never founded must render
+// every one of those surfaces exactly as before.
+//
+// The server half is RUN (the pure shaper, the read over a fake pool, the write-once
+// stamps setFoundingMode now keeps). The client half is RUN too: founding-mark.js and
+// the real roster.js / hall-widgets.js in a vm, so the row and the wall are the bytes a
+// browser would get, not a copy of them.
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PUB = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const read = (f) => fs.readFileSync(path.join(PUB, f), 'utf8');
+const fb = require('../modules/onboarding/founding-builders.js');
+const fm = require('../modules/onboarding/founding-mode.js');
+
+const START = '2026-10-01T00:00:00Z';
+const STAMPS = {
+  decide: '2026-10-01T00:00:00Z',
+  scope: '2026-10-02T00:00:00Z',
+  strategize: '2026-10-05T00:00:00Z',
+};
+const B = (id, created_at, extra = {}) => ({ id, created_at, display_name: `b${id}`, github_login: `b${id}`, rank: 'xenos', ...extra });
+
+// ── the shaper ───────────────────────────────────────────────────────────────
+
+test('a project that was never founded has no marks at all', () => {
+  assert.deepEqual(fb.shapeFoundingBuilders({ startedAt: null, founderId: 1, builders: [B(1, START)] }), []);
+  assert.deepEqual(fb.shapeFoundingBuilders({}), []);
+});
+
+test('joiners during genesis are numbered in join order from #2; the founder is "founder"', () => {
+  const marks = fb.shapeFoundingBuilders({
+    startedAt: START, stageAt: STAMPS, founderId: 1,
+    // deliberately out of order: the order is join time, not the array or the id
+    builders: [B(9, '2026-10-06T09:00:00Z'), B(1, '2026-09-20T00:00:00Z', { rank: 'archon' }), B(4, '2026-10-03T12:00:00Z')],
+  });
+  assert.deepEqual(marks.map((m) => [m.builder_id, m.number, m.founder]), [[1, 1, true], [4, 2, false], [9, 3, false]]);
+  assert.equal(marks[0].rank, 'archon', 'the rank rides along for the ranks page');
+});
+
+test('each joiner records the stage they joined at and the day of genesis', () => {
+  const marks = fb.shapeFoundingBuilders({
+    startedAt: START, stageAt: STAMPS, founderId: 1,
+    builders: [B(1, START), B(2, '2026-10-01T05:00:00Z'), B(3, '2026-10-03T00:00:00Z'), B(4, '2026-10-06T00:00:00Z')],
+  });
+  assert.deepEqual(marks.slice(1).map((m) => [m.stage, m.day]), [['decide', 1], ['scope', 3], ['strategize', 6]]);
+});
+
+test('joiners after genesis carry no mark; builders from before it carry none either', () => {
+  const marks = fb.shapeFoundingBuilders({
+    startedAt: START, endedAt: '2026-10-10T00:00:00Z', stageAt: STAMPS, founderId: 1,
+    builders: [B(1, '2026-01-01T00:00:00Z'), B(2, '2026-06-01T00:00:00Z'), B(3, '2026-10-04T00:00:00Z'), B(4, '2026-10-10T00:00:00Z'), B(5, '2026-11-01T00:00:00Z')],
+  });
+  assert.deepEqual(marks.map((m) => m.builder_id), [1, 3], 'only the founder and the in-window joiner');
+  assert.equal(marks[1].number, 2);
+});
+
+test('stageAt walks the stamps in genesis order, and an unstamped history is decide', () => {
+  assert.equal(fb.stageAt('2026-10-04T00:00:00Z', STAMPS), 'scope');
+  assert.equal(fb.stageAt('2026-10-04T00:00:00Z', {}), 'decide');
+  assert.equal(fb.stageAt('not a date', STAMPS), 'decide');
+});
+
+// ── the read ─────────────────────────────────────────────────────────────────
+
+function settingsStore(values) {
+  return async (key) => (values[key] != null ? { key, value: values[key] } : null);
+}
+
+test('the read asks for the founder and the window, and shapes what comes back', async () => {
+  const calls = [];
+  const pool = { query: async (sql, params) => { calls.push({ sql, params }); return { rows: [B(1, START), B(2, '2026-10-02T06:00:00Z')] }; } };
+  const marks = await fb.foundingBuildersFor({
+    getSetting: settingsStore({ [fm.KEYS.STARTED_AT]: START, [fm.stageAtKey('scope')]: STAMPS.scope }),
+    getFoundingBuilder: async () => ({ id: 1 }),
+    pool,
+  });
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].params, [1, START, null], 'founder id, window start, open end');
+  assert.match(calls[0].sql, /system_role IS NULL/, 'system principals are never founding builders');
+  assert.deepEqual(marks.map((m) => [m.builder_id, m.number, m.stage]), [[1, 1, 'decide'], [2, 2, 'scope']]);
+});
+
+test('the read never queries a project that was never founded, and never throws', async () => {
+  let queried = false;
+  const pool = { query: async () => { queried = true; return { rows: [] }; } };
+  assert.deepEqual(await fb.foundingBuildersFor({ getSetting: settingsStore({}), getFoundingBuilder: async () => ({ id: 1 }), pool }), []);
+  assert.equal(queried, false);
+  const broken = { query: async () => { throw new Error('db down'); } };
+  assert.deepEqual(await fb.foundingBuildersFor({
+    getSetting: settingsStore({ [fm.KEYS.STARTED_AT]: START }), getFoundingBuilder: async () => null, pool: broken,
+  }), []);
+});
+
+// ── the founding record setFoundingMode keeps ───────────────────────────────
+
+test('setFoundingMode stamps each stage once, and ended_at on the first switch-off', async () => {
+  const store = new Map();
+  const deps = {
+    getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+    setSetting: async (k, v) => { store.set(k, String(v)); return { key: k, value: String(v) }; },
+    now: new Date('2026-10-01T00:00:00Z'),
+  };
+  await fm.setFoundingMode({ active: true }, 1, deps);
+  assert.equal(store.get(fm.stageAtKey('decide')), '2026-10-01T00:00:00.000Z', 'starting with no stage stamps decide');
+  deps.now = new Date('2026-10-03T00:00:00Z');
+  await fm.setFoundingMode({ stage: 'scope' }, 1, deps);
+  deps.now = new Date('2026-10-04T00:00:00Z');
+  await fm.setFoundingMode({ stage: 'scope' }, 1, deps);
+  assert.equal(store.get(fm.stageAtKey('scope')), '2026-10-03T00:00:00.000Z', 'a stage stamp is write-once');
+  await fm.setFoundingMode({ active: false }, 1, deps);
+  deps.now = new Date('2026-10-09T00:00:00Z');
+  await fm.setFoundingMode({ active: false }, 1, deps);
+  assert.equal(store.get(fm.KEYS.ENDED_AT), '2026-10-04T00:00:00.000Z', 'ended_at is write-once');
+});
+
+test('switching off a project that never started founding stamps no end', async () => {
+  const store = new Map();
+  await fm.setFoundingMode({ active: false }, 1, {
+    getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+    setSetting: async (k, v) => { store.set(k, String(v)); },
+  });
+  assert.equal(store.has(fm.KEYS.ENDED_AT), false);
+});
+
+// ── the route ────────────────────────────────────────────────────────────────
+
+test('the onboarding router serves GET /founding/builders behind a signed-in builder', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'onboarding', 'routes', 'onboarding.js'), 'utf8');
+  assert.match(src, /router\.get\('\/founding\/builders', api\.requireBuilder,/);
+});
+
+// ── the client, RUN ──────────────────────────────────────────────────────────
+
+const escapeHtml = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const MARKS = [
+  { builder_id: 1, number: 1, founder: true, stage: 'decide', day: 1, display_name: 'Ada', rank: 'archon' },
+  { builder_id: 7, number: 2, founder: false, stage: 'scope', day: 3, display_name: 'Avery <x>', rank: 'xenos' },
+];
+
+function sandboxWith(marks, extra = {}) {
+  const sandbox = {
+    window: { OTB: { escapeHtml, fmtInt: (n) => String(n == null ? 0 : n), rankLabel: (r) => r } },
+    fetch: (url) => Promise.resolve(url.includes('/founding/builders')
+      ? (marks ? { ok: true, json: () => Promise.resolve({ builders: marks }) } : { ok: false, json: () => Promise.resolve({}) })
+      : { ok: true, json: () => Promise.resolve({ leaderboard: [{ id: 1, display_name: 'Ada' }, { id: 7, display_name: 'Avery' }, { id: 8, display_name: 'Rae' }] }) }),
+    console,
+    Promise,
+    ...extra,
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(read('founding-mark.js'), sandbox, { filename: 'founding-mark.js' });
+  return sandbox;
+}
+
+test('the chip says founder / founding · #N, escapes, and explains itself in its title', () => {
+  const { window } = sandboxWith(MARKS);
+  const F = window.OTBFounding;
+  assert.match(F.chipHtml(MARKS[0]), />founder<\/span>$/);
+  assert.match(F.chipHtml(MARKS[1]), /founding · #2/);
+  assert.match(F.chipHtml(MARKS[1]), /title="Founding builder #2 — Joined at scope, day 3 of genesis\. A mark for good; it grants nothing\."/);
+  assert.equal(F.chipHtml(null), '');
+  assert.equal(F.joinedLine(MARKS[0]), 'Founded the project');
+});
+
+test('a failed or signed-out founding read is an empty list, never an error', async () => {
+  const { window } = sandboxWith(null);
+  assert.equal((await window.OTBFounding.load()).length, 0);
+});
+
+async function rosterRows(marks) {
+  const sandbox = sandboxWith(marks);
+  let rowFn = null;
+  Object.assign(sandbox.window, {
+    OTBBranding: { currencyLabel: () => 'Credits' },
+    OTBKit: {
+      esc: escapeHtml, makePager: () => ({ page: 1 }), makeFilterBar: () => {}, paginate: (xs) => xs,
+      makeLedger: (cfg) => { rowFn = cfg.rowHtml; return { render() {} }; },
+    },
+  });
+  sandbox.document = { getElementById: () => ({ innerHTML: '', className: '', textContent: '', hidden: false }) };
+  if (!marks) delete sandbox.window.OTBFounding; // a page without the script at all
+  vm.runInContext(read('roster.js'), sandbox, { filename: 'roster.js' });
+  await new Promise((r) => setImmediate(r));
+  assert.ok(rowFn, 'roster.js mounted its ledger');
+  return rowFn;
+}
+
+test('the roster marks the founding builders and leaves everyone else exactly as before', async () => {
+  const withMarks = await rosterRows(MARKS);
+  const without = await rosterRows(null);
+  assert.match(withMarks({ id: 7, display_name: 'Avery' }), /class="lb-founding"><span class="founding-mark"[^>]*>.*founding · #2/);
+  assert.match(withMarks({ id: 1, display_name: 'Ada' }), />founder<\/span>/);
+  assert.equal(withMarks({ id: 8, display_name: 'Rae' }), without({ id: 8, display_name: 'Rae' }), 'an unmarked row is byte-identical');
+  assert.doesNotMatch(without({ id: 7, display_name: 'Avery' }), /founding/, 'no founding record, no mark');
+});
+
+function wall(marks) {
+  const sandbox = sandboxWith(marks);
+  const widgets = [];
+  sandbox.window.OTB.contributeHallWidget = (w) => { widgets.push(w); return w; };
+  sandbox.window.__BRANDING__ = {};
+  sandbox.window.OTBKit = { pagerBarHtml: () => '' }; // later widgets' skeletons ask the kit for a pager bar
+  vm.runInContext(read('hall-widgets.js'), sandbox, { filename: 'hall-widgets.js' });
+  const w = widgets.find((x) => x.id === 'home-founding');
+  const list = { innerHTML: '' };
+  const host = { innerHTML: '', hidden: true, querySelector: () => list };
+  return { w, host, list };
+}
+
+test('the founding wall registers on Home, inside the budgeted main zone, hidden by default', () => {
+  const { w } = wall(MARKS);
+  assert.ok(w, 'a home-founding widget is registered');
+  assert.equal(w.view, 'home');
+  assert.equal(w.zone, 'home-main');
+  assert.equal(w.hiddenByDefault, true);
+});
+
+test('the wall shows the founder first and each joiner with number and stage', async () => {
+  const { w, host, list } = wall(MARKS);
+  w.mount(host);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(host.hidden, false);
+  const items = list.innerHTML.split('</li>').filter(Boolean);
+  assert.equal(items.length, 2);
+  assert.match(items[0], /Ada<\/a><span class="founding-wall__sub">founder/);
+  assert.match(items[1], /Avery &lt;x&gt;<\/a><span class="founding-wall__sub">#2 · scope/);
+});
+
+test('a project that was never founded keeps the wall hidden', async () => {
+  const { w, host } = wall([]);
+  w.mount(host);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(host.hidden, true);
+});
+
+test('the profile and the ranks page read the same list, and every page loads the script first', () => {
+  const profile = read('profile.js');
+  const ranks = read('ranks.js');
+  assert.match(profile, /renderHead\(builder\);\s*\n\s*renderFoundingMark\(builder\);/);
+  assert.match(ranks, /render\(builder \|\| \{\}\);\s*\n\s*renderFounding\(\);/);
+  assert.match(read('ranks.html'), /id="founding-scroll"[^>]*hidden/, 'the ranks section is hidden in the markup');
+  for (const [html, page] of [['roster.html', 'roster.js'], ['profile.html', 'profile.js'], ['ranks.html', 'ranks.js'], ['index.html', 'hall-widgets.js']]) {
+    const src = read(html);
+    const a = src.indexOf('/builders/founding-mark.js');
+    const b = src.indexOf(`/builders/${page}`);
+    assert.ok(a > 0 && a < b, `${html} loads founding-mark.js before ${page}`);
+  }
+});