@bongos/core 1.20.54 → 1.20.56

package/modules/onboarding/routes/onboarding.js

@@ -34,6 +34,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const onboardingPort = require('../port');
 const buildAccessRequestsRouter = require('./access-requests');
+const foundingBuilders = require('../founding-builders');
 
 // Register the `onboarding` kernel PORT. See the header + port.js for the full
 // consumer list and the graceful-degradation contract.
@@ -50,5 +51,15 @@ module.exports = function buildOnboardingRouter() {
   // Archon-only resolve routes). Mounted on this same /api/bongos router by the
   // loader, before the public catch-all — byte-identical paths.
   router.use(buildAccessRequestsRouter());
+  // The founding mark (task 1004424): who joined while the project was founding, in
+  // join order, with the stage each joined at. Read by the roster, the profile, the
+  // ranks page and the home's founding wall; an empty list on a project that was
+  // never founded, so those surfaces render exactly as before. Signed-in, like the
+  // hall pages that read it; it carries nothing the roster does not already show.
+  router.get('/founding/builders', api.requireBuilder, async (req, res) => {
+    const builders = await foundingBuilders.foundingBuildersFor();
+    res.set('Cache-Control', 'private, max-age=60');
+    res.json({ builders });
+  });
   return router;
 };

package/modules/ui-design/kit/fixtures/founding-builders-sample.json

@@ -0,0 +1,9 @@
+{
+  "_": "The founding mark (task 1004424): GET /founding/builders on a project that was founded. Builder 1 is the kit's own signed-in builder (me.json), so the ranks and Home renders show the viewer as founder. Only the founding variant states files point at this; the default name has no file, so every other render is a never-founded project.",
+  "builders": [
+    { "builder_id": 1, "display_name": "A Builder", "github_login": "builder", "avatar_url": null, "rank": "archon", "founder": true, "number": 1, "stage": "decide", "day": 1 },
+    { "builder_id": 2, "display_name": "Avery Okonkwo-Lindqvist", "github_login": "avery", "avatar_url": null, "rank": "metic", "founder": false, "number": 2, "stage": "scope", "day": 3 },
+    { "builder_id": 3, "display_name": "Jordan", "github_login": "jordan", "avatar_url": null, "rank": "thetes", "founder": false, "number": 3, "stage": "strategize", "day": 8 },
+    { "builder_id": 4, "display_name": "Sam", "github_login": "sam", "avatar_url": null, "rank": "xenos", "founder": false, "number": 4, "stage": "legislation", "day": 19 }
+  ]
+}

package/modules/ui-design/kit/fixtures/founding-builders.json

@@ -0,0 +1,4 @@
+{
+  "_": "GET /founding/builders on a project that was never founded (task 1004424): the empty list every hall surface reads as 'no marks', so each render is today's page. The founding variants point the name at founding-builders-sample.json instead.",
+  "builders": []
+}

package/modules/ui-design/kit/serve.js

@@ -105,7 +105,10 @@ const FEEDS = {
   '/public/leaderboard': 'leaderboard',
   '/projects/featured': 'featured',
 };
-const AUTHED = { '/my-projects': 'my-projects', '/my-projects/invites': 'my-projects__invites' };
+// /founding/builders (task 1004424) answers a never-founded project's empty list by default,
+// so every existing render stays today's page; a founding variant states file points it at
+// founding-builders-sample via stub.fixtures.
+const AUTHED = { '/my-projects': 'my-projects', '/my-projects/invites': 'my-projects__invites', '/founding/builders': 'founding-builders' };
 const UNAUTH = { error: { code: 'unauthenticated', message: 'unauthenticated' } };
 
 // GET /provisioning/starter-bundles as the create wizard's module picker reads it

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.54",
+  "version": "1.20.56",
   "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

@@ -8441,5 +8441,17 @@
       "id": "1004400",
       "text": "The Government page now recommends a starting government and a starting set of ranks for your kind of project (game, research, business, non-profit) and its size. It only ever recommends a form you can adopt today. A team of a"
     }
+  ],
+  "1.20.55": [
+    {
+      "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.54'; // 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}`);
+  }
+});

package/tests/government_recommendations.mjs

@@ -117,3 +117,16 @@ test('recommendationsFor carries both answers and the vocabulary to ask about an
   assert.equal(r.project_types.length, TYPES.length);
   for (const b of r.size_bands) assert.equal(reco.sizeBandFor(b.example).key, b.key, 'each size option lands in its own band');
 });
+
+test('the panel says what a recommended rank can do in words, never in permission keys (task 1004478)', () => {
+  for (const job of Object.keys(reco.JOB_GRANTS)) {
+    const can = reco.JOB_CAN[job];
+    assert.ok(typeof can === 'string' && can.length > 20, `job ${job} needs a plain sentence`);
+    assert.ok(!/[a-z]+\.[a-z_]+/.test(can), `job ${job}'s sentence must not spell a permission key`);
+  }
+  for (const r of reco.recommendedRankSet('game', 200).ranks) assert.equal(r.can, reco.JOB_CAN[r.job]);
+  const client = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'government.js'), 'utf8');
+  const row = client.slice(client.indexOf('function recoRankRow'), client.indexOf('function recommendationHtml'));
+  assert.match(row, /r\.can/, 'the rank row renders the sentence');
+  assert.doesNotMatch(row, /permissions/, 'the rank row does not render the raw keys');
+});

package/tests/government_routes.mjs

@@ -254,7 +254,7 @@ test('POST /government/rank-sets/apply creates the missing ranks with their gran
   try {
     const r = await call('POST', '/government/rank-sets/apply', { type: 'game', headcount: 20 });
     assert.equal(r.status, 200);
-    assert.deepEqual(r.json.skipped, ['design-lead']);
+    assert.deepEqual(r.json.skipped, [{ rank_key: 'design-lead', label: 'Design lead' }], 'a kept rank is named by its label, not its key (task 1004478)');
     assert.deepEqual(r.json.created.map((c) => c.rank_key), ['playtester']);
     const creates = calls.filter(([k]) => k === 'createRank');
     assert.equal(creates.length, 1);