@bongos/core 1.24.41 → 1.24.42

package/tests/hall_onboarding_bongos_setup.mjs

@@ -14,20 +14,20 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
 const OLD = /\/builder-setup|setup-builder\.(sh|js)/;
 
-// The welcome panel's markup, from the setupSteps literal to the panel's innerHTML.
-function welcomeMarkup() {
-  const src = read('modules/hall-ui/public/hall-render.js');
-  const start = src.indexOf('const setupSteps = `');
-  const end = src.indexOf('body.innerHTML = `', start);
-  assert.ok(start > 0 && end > start, 'welcome panel markup located');
+// The setup screen's machine-linking step (task 1005076 replaced the Home welcome panel).
+function setupStepMarkup() {
+  const src = read('modules/hall-ui/public/setup-gate.js');
+  const start = src.indexOf("if (step.id === 'cli_setup') {");
+  const end = src.indexOf("if (step.id === 'pick_disciplines')", start);
+  assert.ok(start > 0 && end > start, 'the setup screen\'s cli_setup step located');
   return src.slice(start, end).split('\n').filter((l) => !/^\s*\/\//.test(l)).join('\n');
 }
 
-test('welcome panel: the steps and the clone block say npx bongos setup', () => {
-  const w = welcomeMarkup();
-  assert.match(w, /Run <code>npx bongos setup<\/code>/);
-  assert.match(w, /\\nnpm install\\nnpx bongos setup`/, 'clone block ends npm install + npx bongos setup');
-  assert.doesNotMatch(w, OLD, 'no legacy setup command on the welcome panel');
+test('setup screen: the steps and the clone block say npx bongos setup', () => {
+  const w = setupStepMarkup();
+  assert.match(w, /run <code>npx bongos setup<\/code>/);
+  assert.match(w, /\\nnpm install\\nnpx bongos setup<\/pre>/, 'clone block ends npm install + npx bongos setup');
+  assert.doesNotMatch(w, OLD, 'no legacy setup command on the setup screen');
   assert.doesNotMatch(w, /On Windows, run/, 'one command on every OS — no Windows-only line');
   assert.match(w, /nodejs\.org/, 'the tooling list names Node, which npm install needs');
 });
@@ -51,7 +51,7 @@ test('primer: both routes sign in with npx bongos setup', () => {
 
 test('the get-the-code block keeps one command per line (screen and copy)', () => {
   const css = read('modules/hall-ui/public/style.css');
-  const m = /\.setup__getcode \.welcome__paste\s*\{([^}]*)\}/.exec(css);
+  const m = /\.setup-gate__code\s*\{([^}]*)\}/.exec(css);
   assert.ok(m, 'scoped rule present');
   assert.match(m[1], /white-space:\s*pre/, 'copy-on-click reads innerText, so pre is what keeps the line breaks');
   assert.match(m[1], /overflow-y:\s*hidden/, 'a one-axis strip names both axes');
@@ -66,8 +66,8 @@ test('bin/bongos.js is committed executable, so npx leaves a fresh clone clean',
   assert.match(entry, /^100755 /, `expected mode 100755, got: ${entry.trim()}`);
 });
 
-test('welcome intro and checklist lead ask only for what a builder needs', () => {
-  const src = read('modules/hall-ui/public/hall-render.js');
+test('the setup screen and checklist lead ask only for what a builder needs', () => {
+  const src = read('modules/hall-ui/public/setup-gate.js');
   assert.doesNotMatch(src, /run the platform locally/, 'a builder does not run the platform');
   assert.match(src, /Clone the project to your machine and run <code>npm install<\/code> in it\./);
   const st = read('modules/onboarding/onboarding-state.js');

package/tests/module_contributions.mjs

@@ -228,7 +228,8 @@ test('the role axis has exactly one user-facing word, and no surface types it',
     'modules/hall-ui/public/work.js',
     'modules/hall-ui/public/goals-page.js',
     'modules/hall-ui/public/profile.js',
-    'modules/hall-ui/public/builders.js',
+    // task 1005076: the setup screen's role step replaced builders.js's checklist picker.
+    'modules/hall-ui/public/setup-gate.js',
   ];
   for (const p of SURFACES) {
     const s = readSrc(p);
@@ -266,7 +267,8 @@ test('craft picker options: neither picker hardcodes the craft list any more', (
   // silently dropped a module-contributed craft. Whichever picker is edited next
   // must keep reading the server list.
   const read = (p) => readFileSync(path.join(ROOT, p), 'utf8');
-  for (const p of ['modules/hall-ui/public/settings.js', 'modules/hall-ui/public/hall-render.js']) {
+  // task 1005076: the second picker is the setup screen's role step (it was the Home checklist's).
+  for (const p of ['modules/hall-ui/public/settings.js', 'modules/hall-ui/public/setup-gate.js']) {
     const src = read(p);
     assert.ok(/OTB\.disciplines\(\)/.test(src), `${p} builds its options from OTB.disciplines()`);
     assert.ok(!/\['engineer',\s*'artist',\s*'ideator'\]/.test(src), `${p} no longer hardcodes the craft triple`);

package/tests/nav_permission_atoms.mjs

@@ -96,8 +96,9 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // Market Watch settings nav item and its fuel glyph; task 1005041: the Update pill replaced the
 // core-update banner; task 1005045: the Market Watch settings item left (one sidebar item);
 // task 1005046: Ranks, Economy and Diagrams left Docs (one reading room, the Primer);
-// task 1005049: Sessions and Autobongos left the sidebar (tabs on Watch).
-const SHELL_SHA = 'bb0abbadab2508ca';
+// task 1005049: Sessions and Autobongos left the sidebar (tabs on Watch);
+// task 1005076: the setup flow's holdForSetup.
+const SHELL_SHA = '248d104831bae0de';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);

package/tests/onboarding_state.mjs

@@ -322,6 +322,39 @@ test('graduation is engine-only (display signals never gate it)', async () => {
   assert.ok(shaped.stages.every((s) => s.cleared === true));
 });
 
+// ---- the setup flow (task 1005076) -----------------------------------------
+
+const SETUP_IDS = ['signed_in', 'cli_setup', 'pick_disciplines', 'first_start'];
+const setupOf = (state, opts) => onboarding.shapeForApi(state, opts).setup;
+const clearedIds = (setup) => setup.steps.filter((s) => s.cleared).map((s) => s.id);
+
+test('setup: a brand-new xenos is held, with only signed_in cleared', () => {
+  const setup = setupOf(null, { rank: 'xenos' });
+  assert.equal(setup.complete, false);
+  assert.deepEqual(setup.steps.map((s) => s.id), SETUP_IDS);
+  assert.deepEqual(clearedIds(setup), ['signed_in']);
+  assert.ok(setup.steps.every((s) => s.label && s.hint), 'every step says what to do');
+});
+
+test('setup: each step ticks from its own signal, and all four complete it', () => {
+  const state = { current_stage: 'pick_disciplines', completed_stages: ['auth_complete'] };
+  assert.deepEqual(clearedIds(setupOf(state, { rank: 'xenos', cliAuthed: true })), ['signed_in', 'cli_setup']);
+  const picked = { current_stage: 'first_start', completed_stages: ['auth_complete', 'pick_disciplines'] };
+  const almost = setupOf(picked, { rank: 'xenos', cliAuthed: true });
+  assert.equal(almost.complete, false, 'first_start not yet run from Claude');
+  const started = { current_stage: 'first_claim', completed_stages: ['auth_complete', 'pick_disciplines', 'first_start'] };
+  assert.equal(setupOf(started, { rank: 'xenos', cliAuthed: true }).complete, true);
+  assert.equal(setupOf(started, { rank: 'xenos', cliAuthed: false }).complete, false, 'no linked machine, not set up');
+});
+
+test('setup: anyone already past it goes straight in', () => {
+  const fresh = { current_stage: 'auth_complete', completed_stages: [] };
+  for (const rank of ['thetes', 'metic', 'archon']) assert.equal(setupOf(fresh, { rank }).complete, true, rank);
+  assert.equal(setupOf({ current_stage: 'graduated', completed_stages: [] }, { rank: 'xenos' }).complete, true, 'graduated');
+  assert.equal(setupOf({ current_stage: 'ship_three', completed_stages: ['first_claim'] }, { rank: 'xenos' }).complete, true, 'claimed a task');
+  assert.equal(setupOf(fresh, {}).complete, false, 'an unknown rank is not a pass');
+});
+
 // ---- wrap-up --------------------------------------------------------------
 
 Promise.resolve().then(async () => {

package/tests/setup_flow.mjs

@@ -0,0 +1,242 @@
+// tests/setup_flow.mjs — the setup flow a new builder finishes once (task 1005076).
+//
+// Owner, 2026-11-05: a new builder is held on one setup screen until every step is done,
+// and once set up they are in for good — no setup banner on Home. Three halves, each run
+// for real: the claimable route ticks first_start only for a Claude (CLI) session; the
+// shell loads setup-gate.js and draws nothing else over it while setup is incomplete; and
+// the screen draws the steps, saves a craft, and lets the builder in once /me says done.
+// The rule itself (which steps, who goes straight in) is in tests/onboarding_state.mjs.
+//
+// Run:  node tests/setup_flow.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { makeEl, realOTB, settle } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+const ROUTE = read('modules/lifecycle/routes/tasks.js');
+const SHELL = read('modules/hall-ui/public/shell.js');
+const GATE = read('modules/hall-ui/public/setup-gate.js');
+
+let passed = 0;
+let failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed += 1; console.log(`  PASS  ${name}`); }
+  catch (e) { failed += 1; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+const STEPS = (cleared) => ['signed_in', 'cli_setup', 'pick_disciplines', 'first_start']
+  .map((id) => ({ id, label: `Label ${id}`, hint: `Hint ${id}`, cleared: cleared.includes(id) }));
+
+console.log('the setup flow (task 1005076)');
+
+// ---- the claimable route: first_start only from Claude --------------------
+
+// The real guarded statement, run against each kind of session.
+const from = ROUTE.indexOf("if (req.gdsSession && req.gdsSession.source === 'cli')");
+const guard = ROUTE.slice(from, ROUTE.indexOf('\n', from));
+const runGuard = (gdsSession) => {
+  const marks = [];
+  const seams = { resolveOptional: () => ({ safeMarkStage: (_pool, id, stage) => marks.push([id, stage]) }) };
+  vm.runInNewContext(guard, { req: { gdsSession, builder: { id: 7 } }, seams, pool: {} });
+  return marks;
+};
+
+await t('GET /tasks/claimable marks first_start for a Claude (CLI) session, never for the browser', () => {
+  assert.ok(from > 0, 'the guard is in the claimable handler');
+  assert.match(guard, /safeMarkStage\(pool, req\.builder\.id, 'first_start', req\.builder\)/);
+  assert.deepEqual(runGuard({ source: 'cli' }), [[7, 'first_start']]);
+  assert.deepEqual(runGuard({ source: 'web' }), [], 'the hall pages read this feed from the browser');
+  assert.deepEqual(runGuard(null), []);
+  assert.equal((ROUTE.match(/'first_start'/g) || []).length, 1, 'no unguarded mark elsewhere in the routes');
+});
+
+// ---- the screen ------------------------------------------------------------
+
+function bootGate({ patchOk = true } = {}) {
+  const body = makeEl('body');
+  const htmlClasses = new Set();
+  const requests = [];
+  let reloaded = 0;
+  let me = null;
+  const api = { request: (method, p, opts) => {
+    requests.push({ method, p, body: opts && opts.body });
+    if (method === 'PATCH') return Promise.resolve({ ok: patchOk, status: patchOk ? 200 : 422, data: {} });
+    return Promise.resolve({ ok: true, status: 200, data: me });
+  } };
+  const intervals = [];
+  const document = {
+    body,
+    documentElement: { classList: { add: (c) => htmlClasses.add(c), remove: (c) => htmlClasses.delete(c) } },
+    createElement: (tag) => makeEl(tag),
+    getElementById: (id) => body.querySelector('#' + id),
+    activeElement: null,
+  };
+  // the crafts this project offers (dom-utils.js reads them off __MODULES__)
+  const window = { OTB: { ...realOTB(), disciplines: () => ['engineer', 'artist', 'ui'] }, location: { reload: () => { reloaded += 1; } } };
+  const sandbox = { window, document, setInterval: (fn) => { intervals.push(fn); return intervals.length; }, clearInterval() {} };
+  vm.createContext(sandbox);
+  vm.runInContext(GATE, sandbox, { filename: 'setup-gate.js' });
+  return {
+    show: (setup, builder) => window.OTBSetupGate.show(setup, { api, builder }),
+    gate: () => body.querySelector('#setup-gate'),
+    htmlClasses, requests, intervals,
+    setMe: (v) => { me = v; },
+    reloaded: () => reloaded,
+    click: (target) => body.querySelector('#setup-gate').fire('click', { target }),
+  };
+}
+
+await t('the screen lists every step in order, ticks the cleared ones, and opens the first gap', () => {
+  const g = bootGate();
+  g.show({ complete: false, steps: STEPS(['signed_in', 'cli_setup']) }, { display_name: 'Sam' });
+  const gate = g.gate();
+  assert.ok(gate, 'drawn');
+  assert.equal(gate.getAttribute('aria-modal'), 'true');
+  assert.ok(g.htmlClasses.has('setup-gate-open'), 'the hall behind it does not scroll');
+  assert.match(gate.querySelector('#setup-gate-h').textContent, /Welcome, Sam/);
+  assert.equal(gate.querySelector('.setup-gate__count').textContent, '2 of 4 done');
+  const steps = gate.querySelectorAll('.setup-gate__step');
+  assert.deepEqual(steps.map((s) => s.className), ['setup-gate__step is-done', 'setup-gate__step is-done', 'setup-gate__step is-current', 'setup-gate__step']);
+  assert.match(steps[2].textContent, /Hint pick_disciplines/, 'only the current step shows its hint');
+  assert.doesNotMatch(steps[3].textContent, /Hint first_start/);
+  assert.deepEqual(gate.querySelectorAll('[data-craft]').map((b) => b.textContent), ['Engineer', 'Artist', 'UI'],
+    'the crafts this project offers');
+});
+
+await t('choosing a craft saves it through PATCH /me/disciplines, the route every picker uses', async () => {
+  const g = bootGate();
+  g.show({ complete: false, steps: STEPS(['signed_in', 'cli_setup']) });
+  const save = () => g.gate().querySelector('[data-save-crafts]');
+  assert.equal(save().disabled, true, 'nothing picked, nothing to save');
+  g.click(g.gate().querySelector('[data-craft="artist"]'));
+  assert.equal(g.gate().querySelector('[data-craft="artist"]').getAttribute('aria-pressed'), 'true');
+  assert.equal(save().disabled, false);
+  g.setMe({ onboarding: { setup: { complete: false, steps: STEPS(['signed_in', 'cli_setup', 'pick_disciplines']) } } });
+  g.click(save());
+  await settle(); await settle();
+  const patch = g.requests.find((r) => r.method === 'PATCH');
+  assert.equal(patch.p, '/api/bongos/me/disciplines');
+  assert.deepEqual(JSON.parse(JSON.stringify(patch.body)), { preferred_disciplines: ['artist'] });
+  assert.equal(g.gate().querySelector('.setup-gate__count').textContent, '3 of 4 done', 're-read /me and ticked');
+});
+
+await t('a craft that does not save says so and can be tried again', async () => {
+  const g = bootGate({ patchOk: false });
+  g.show({ complete: false, steps: STEPS(['signed_in', 'cli_setup']) });
+  g.click(g.gate().querySelector('[data-craft="engineer"]'));
+  g.click(g.gate().querySelector('[data-save-crafts]'));
+  await settle();
+  const err = g.gate().querySelector('[data-craft-err]');
+  assert.equal(err.hidden, false);
+  assert.match(err.textContent, /did not save/);
+  assert.equal(g.gate().querySelector('[data-save-crafts]').disabled, false);
+});
+
+await t('it checks /me while it is up, and lets the builder in the moment setup is complete', async () => {
+  const g = bootGate();
+  g.show({ complete: false, steps: STEPS(['signed_in', 'cli_setup', 'pick_disciplines']) });
+  assert.equal(g.intervals.length, 1, 'it polls');
+  g.setMe({ onboarding: { setup: { complete: true, steps: STEPS(['signed_in', 'cli_setup', 'pick_disciplines', 'first_start']) } } });
+  g.intervals[0]();
+  await settle();
+  assert.equal(g.gate(), null, 'the screen is gone');
+  assert.ok(!g.htmlClasses.has('setup-gate-open'));
+  assert.equal(g.reloaded(), 1, 'the page reloads into the hall');
+});
+
+await t('a complete setup draws nothing', () => {
+  const g = bootGate();
+  g.show({ complete: true, steps: STEPS(['signed_in', 'cli_setup', 'pick_disciplines', 'first_start']) });
+  assert.equal(g.gate(), null);
+});
+
+// ---- the shell: loads the screen, and nothing else is drawn over it ---------
+
+function bootShell({ deferLoad = false } = {}) {
+  const loaded = [];
+  const pending = [];
+  const asked = [];
+  let sandbox = null;
+  const stubEl = () => ({
+    dataset: {}, style: {}, textContent: '', hidden: false, innerHTML: '',
+    classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } },
+    setAttribute() {}, getAttribute() { return null; }, removeAttribute() {}, addEventListener() {},
+    querySelector() { return null; }, querySelectorAll() { return []; }, appendChild() {}, focus() {},
+  });
+  const els = new Map();
+  const document = {
+    body: { dataset: { page: 'work' }, appendChild() {} },
+    documentElement: { dataset: {}, style: {}, classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } } },
+    getElementById(id) { if (!els.has(id)) els.set(id, stubEl()); return els.get(id); },
+    querySelectorAll() { return []; }, createElement: () => stubEl(),
+    addEventListener() {}, dispatchEvent() {}, get cookie() { return ''; }, set cookie(_v) {},
+    head: { appendChild(tag) {
+      loaded.push(tag.src);
+      const land = () => {
+        if (/setup-gate/.test(tag.src)) sandbox.window.OTBSetupGate = { show: (setup) => asked.push(['gate', setup.complete]) };
+        if (tag.onload) tag.onload();
+      };
+      if (deferLoad && /setup-gate/.test(tag.src)) pending.push(land); else land();
+    } },
+  };
+  const location = { hostname: 'h', origin: 'https://h', pathname: '/work', hash: '', assign() {}, replace() {} };
+  const window = {
+    OTB: realOTB(), __BRANDING__: {}, __MODULES__: { enabled: {} },
+    BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
+    // the boot pass runs before anyone is signed in, when neither draws anything: count signed-in asks only
+    OTBWelcome: { onAccess: (access) => { if (access.authed === true) asked.push(['welcome']); return false; } },
+    OTBCraftMode: { onAccess: (access) => { if (access.authed === true) asked.push(['craft']); }, applyNav() {}, mount() {}, setPositions() {}, switchHtml: () => '' },
+    matchMedia: () => ({ matches: false, addEventListener() {} }),
+    localStorage: { getItem: () => null, setItem() {} },
+    requestAnimationFrame() {}, scrollTo() {}, location, addEventListener() {},
+  };
+  sandbox = { window, document, location, console, setTimeout, clearTimeout, queueMicrotask,
+    CustomEvent: class { constructor(tp, i) { this.type = tp; Object.assign(this, i); } } };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(SHELL, sandbox, { filename: 'shell.js' });
+  return { apply: (state) => window.OTBShell.applyAccess(state), land: () => pending.splice(0).forEach((f) => f()), loaded, asked };
+}
+
+await t('the shell holds an unfinished builder on the setup screen, with no welcome or craft picker over it', () => {
+  const s = bootShell();
+  s.apply({ authed: true, rank: 'xenos', builder: { id: 9 }, setup: { complete: false, steps: STEPS(['signed_in']) } });
+  assert.equal(s.loaded.filter((u) => /^\/builders\/setup-gate\.js/.test(u)).length, 1, 'its file is loaded');
+  assert.deepEqual(s.asked, [['gate', false]], 'the screen, and nothing over it');
+});
+
+await t('the setup screen loads once, however often the shell re-checks access before it lands', () => {
+  const s = bootShell({ deferLoad: true });
+  const held = { authed: true, rank: 'xenos', builder: { id: 9 }, setup: { complete: false, steps: STEPS(['signed_in']) } };
+  s.apply(held);
+  s.apply(held);
+  s.apply(held);
+  assert.equal(s.loaded.filter((u) => /setup-gate\.js/.test(u)).length, 1, 'one script tag, so one screen');
+  s.land();
+  assert.deepEqual(s.asked, [['gate', false]]);
+});
+
+await t('a set-up builder loads no setup file and gets the hall as before', () => {
+  const s = bootShell();
+  s.apply({ authed: true, rank: 'xenos', builder: { id: 9 }, setup: { complete: true, steps: [] } });
+  assert.equal(s.loaded.filter((u) => /setup-gate/.test(u)).length, 0);
+  assert.ok(!s.asked.some(([k]) => k === 'gate'), 'no setup screen');
+  assert.deepEqual(s.asked.slice(0, 2), [['welcome'], ['craft']], 'the daily welcome and craft picker as before');
+  const unknown = bootShell();
+  unknown.apply({ authed: true, rank: 'xenos', builder: { id: 9 }, setup: null });
+  assert.equal(unknown.loaded.filter((u) => /setup-gate/.test(u)).length, 0, 'an older server that sends no setup holds nobody');
+});
+
+await t('Home carries no setup banner: the Welcome and Getting started panels are gone', () => {
+  const widgets = read('modules/hall-ui/public/hall-widgets.js');
+  assert.doesNotMatch(widgets, /w\('welcome-scroll'|w\('onboarding-scroll'/);
+  assert.doesNotMatch(read('modules/hall-ui/public/index.html'), /welcome-reopen|Show the setup guide again/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/welcome_boot.mjs

@@ -122,6 +122,7 @@ test('Home loads the welcome before the shell, and the shell asks it before the
     'welcome-boot.js, then the shell trio');
   assert.ok(at('welcome-boot.css') > 0, 'and its sheet');
   const shell = fs.readFileSync(path.join(HALL, 'shell.js'), 'utf8');
-  assert.match(shell, /if \(!\(window\.OTBWelcome && window\.OTBWelcome\.onAccess\(access, state && state\.builder\)\) && CRAFT\) CRAFT\.onAccess\(/,
-    'the picker is asked only when the welcome did not show');
+  // task 1005076: and neither is asked while the setup screen holds the builder (tests/setup_flow.mjs).
+  assert.match(shell, /if \(!holdForSetup\(state && state\.builder\) && !\(window\.OTBWelcome && window\.OTBWelcome\.onAccess\(access, state && state\.builder\)\) && CRAFT\) CRAFT\.onAccess\(/,
+    'the picker is asked only when setup is done and the welcome did not show');
 });