@bongos/core 1.21.104 → 1.21.106

package/tests/setup_status_facts.mjs

@@ -0,0 +1,400 @@
+// tests/setup_status_facts.mjs — part 03 after Create is ONE honest list of checked facts
+// (task 1004683; the design of record docs/design/mocks/day-night-rooms/setup-status.html,
+// approved by the owner 2026-10-09: "change the status bar mechanisms for the GitHub related
+// steps and the text, it seems antiquated and not real").
+//
+// The whole path is run, not read: each scenario's rows go through the REAL owner read
+// (GET /provisioning/instances/:id, modules/provisioning/routes/provisioning.js, with its
+// real projections — ownerInstance, publicGithubApp, githubSetupRead — over a fake pool),
+// and the JSON it answers is fetched by the REAL page watch (startProgress, sliced out of
+// projects.html by the vm-slice idiom) into the REAL painter (paintFacts) under a small DOM.
+// What the founder would see is then read back off that DOM. Pinned:
+//   * the five scenarios of the mockup — the count, each fact's state, the one sentence;
+//   * every fact's state comes from a server field: moving one field moves its fact, and
+//     moving the clock moves nothing but the right-hand "when";
+//   * no fact is said twice, none of the outdated words is anywhere, nothing is markup;
+//   * Enter Genesis (and "is alive") appear when, and only when, every required fact is done;
+//   * one live region, written only when its sentence changes.
+//
+// Run:  node --test tests/setup_status_facts.mjs
+
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+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 LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+const HUB = fs.readFileSync(path.join(LANDING, 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+
+// ── the page regions (each boundary asserted, so a rename fails loudly) ─────────────────
+function region(start, end) {
+  const a = SCRIPT.indexOf(start);
+  const b = a < 0 ? -1 : SCRIPT.indexOf(end, a + 1);
+  assert.ok(a > 0 && b > a, `region not found: ${start} … ${end}`);
+  return SCRIPT.slice(a, b);
+}
+const FACTS = region('    /* ── part 03 after Create (task 1004683', "    /* ── C8: the wizard's polls run only");
+const NOTE_ORG = region("    /* the organisation the server says this attempt's app is on: change-only */", '    /* ── Pick up where it stopped');
+const MANIFEST = region('    function manifestInFlight() {', '    function pollManifest(stateToken) {');
+const WATCH = region("    /* ── the owner's instance read (task 2083)", '    /* Everything the wizard must FORGET');
+const ADDRESS_READY = (SCRIPT.match(/\n {2}function addressReady\(inst\) \{[^\n]*\}/) || [''])[0];
+assert.ok(ADDRESS_READY, 'addressReady() must be findable');
+const PANEL = (HUB.match(/<div class="part waiting" id="panel-done"[\s\S]*?\n {10}<\/section>/) || [''])[0];
+assert.ok(PANEL, 'part 03 ships as real markup');
+
+// ── the server: the REAL owner read over a fake pool ───────────────────────────────────
+const provisioning = require(path.join(ROOT, 'modules', 'provisioning', 'provisioning.js'));
+const catalogBridge = require(path.join(ROOT, 'modules', 'provisioning', 'catalog-bridge.js'));
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+let db = null;   // { inst, intent, manifest, events } — the rows the read finds
+provisioning.getInstanceById = async () => db.inst;
+provisioning.getOpenIntent = async () => db.intent;
+provisioning.getLatestOAuthManifestForInstance = async () => db.manifest;
+catalogBridge.healInstanceCatalog = async () => {};
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, rank: 'metic', github_login: 'you' }; next(); };
+api.pool.query = async (sql) => (/FROM provisioning_events/.test(sql) ? { rows: db.events } : { rows: [] });
+const express = require('express');
+const app = express();
+app.use((_req, res, next) => {
+  res.fail = (code, status) => res.status(typeof status === 'number' ? 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));
+const ORIGIN = `http://127.0.0.1:${server.address().port}`;
+after(() => server.close());
+
+// ── a small DOM: nodes, text, attributes, and the few selectors the painter asks ────────
+class Node {
+  constructor(tag, doc) { this.tagName = String(tag).toUpperCase(); this.doc = doc; this.childNodes = []; this.parentNode = null; this.attrs = {}; this.className = ''; this.hidden = false; this._text = ''; this.writes = 0; this.id = ''; }
+  get children() { return this.childNodes.filter((n) => n instanceof Node); }
+  get lastChild() { return this.childNodes[this.childNodes.length - 1] || null; }
+  get textContent() { return this._text + this.childNodes.map((n) => (n instanceof Node ? n.textContent : n.data)).join(''); }
+  set textContent(v) { this.writes += 1; this.childNodes.forEach((n) => { n.parentNode = null; }); this.childNodes = []; this._text = String(v); }
+  set innerHTML(_v) { throw new Error('innerHTML written on #' + (this.id || this.tagName)); }
+  _adopt(n) { if (n.parentNode) n.parentNode.removeChild(n); n.parentNode = this; }
+  appendChild(n) { this._adopt(n); this.childNodes.push(n); this.writes += 1; return n; }
+  insertBefore(n, ref) { this._adopt(n); const i = this.childNodes.indexOf(ref); if (i < 0) this.childNodes.push(n); else this.childNodes.splice(i, 0, n); return n; }
+  removeChild(n) { this.childNodes = this.childNodes.filter((x) => x !== n); n.parentNode = null; return n; }
+  replaceChild(n, old) { this._adopt(n); const i = this.childNodes.indexOf(old); this.childNodes[i] = n; old.parentNode = null; this.writes += 1; return old; }
+  contains(n) { for (let x = n; x; x = x.parentNode) if (x === this) return true; return false; }
+  setAttribute(k, v) { this.attrs[k] = String(v); if (k === 'id') this.id = String(v); }
+  getAttribute(k) { return k in this.attrs ? this.attrs[k] : null; }
+  removeAttribute(k) { delete this.attrs[k]; }
+  addEventListener() {}
+  matches(part) {
+    if (part.startsWith('#')) return this.id === part.slice(1);
+    if (part.startsWith('.')) return (' ' + this.className + ' ').includes(' ' + part.slice(1) + ' ');
+    if (/^[a-z]+$/.test(part)) return this.tagName === part.toUpperCase();
+    const m = part.match(/^\[([\w-]+)(?:="([^"]*)")?\]$/);
+    assert.ok(m, `the DOM stub does not know the selector "${part}"`);
+    return m[2] === undefined ? this.getAttribute(m[1]) !== null : this.getAttribute(m[1]) === m[2];
+  }
+  descendants() { return this.children.flatMap((c) => [c, ...c.descendants()]); }
+  querySelectorAll(sel) {
+    let found = [this];
+    for (const part of sel.trim().split(/\s+/)) found = [...new Set(found.flatMap((n) => n.descendants().filter((d) => d.matches(part))))];
+    return found;
+  }
+  querySelector(sel) { return this.querySelectorAll(sel)[0] || null; }
+}
+function makeDom() {
+  const doc = { hidden: false };
+  const body = new Node('body', doc);
+  const byId = {};
+  const el = (id, tag = 'div', parent = body) => { const n = new Node(tag, doc); n.setAttribute('id', id); parent.appendChild(n); byId[id] = n; return n; };
+  // part 03's own markup, as projects.html bakes it
+  const panel = el('panel-done');
+  el('donePartT', 'span', panel); el('ghState', 'span', panel);
+  const bodyEl = el('doneBody', 'div', panel);
+  el('setupNow', 'p', bodyEl);
+  el('homeFacts', 'div', bodyEl); el('ghFacts', 'div', bodyEl);
+  const pick = el('aaPick', 'div', bodyEl); pick.hidden = true;
+  el('hopLink', 'button', bodyEl);
+  const alive = el('doneAlive', 'div', bodyEl); alive.hidden = true;
+  el('done-h', 'h2', alive); el('enterGenesis', 'a', alive);
+  Object.assign(doc, {
+    createElement: (tag) => new Node(tag, doc),
+    createTextNode: (data) => ({ data: String(data) }),
+    querySelector: (sel) => body.querySelector(sel),
+  });
+  return { doc, $: (id) => byId[id] || null, body };
+}
+
+// ── one page, booted on one project, reading the real route ─────────────────────────────
+async function page({ clockShift = 0 } = {}) {
+  const dom = makeDom();
+  const calls = { invite: [], arrive: 0, pick: [] };
+  const inflight = [];
+  const sandbox = {
+    API: '/api/bongos', $: dom.$, document: dom.doc, root: { addEventListener() {}, contains: () => true },
+    currentView: 'new', instanceId: null, manifestPollTimer: null, manifestStartedAt: 0, progressKick: null, manifestKick: null,
+    state: { step: 2, name: 'Kestrel', slug: 'kestrel', owner: 'you', repo: 'kestrel', domain: 'kestrel.cloudbongos.com', noAddress: false },
+    resolvedDomain: () => 'kestrel.cloudbongos.com', apexBase: () => 'cloudbongos.com',
+    wizPollActive: () => true, wizPollDelay: (ms) => ms,
+    setTimeout: () => 1, clearTimeout() {}, setInterval: () => 1, clearInterval() {},
+    rememberManifest() {}, syncAppPick: (on) => calls.pick.push(on), paintInviteGate: (on) => calls.invite.push(on), hopArrive: () => { calls.arrive += 1; },
+    fetch: (p, init) => { const r = fetch(ORIGIN + p, init); inflight.push(r.then((x) => x.clone().text()).catch(() => null)); return r; },
+    Date: class extends Date { static now() { return Date.now() + clockShift; } },
+    JSON, Math, Object, Array, String, Number, Promise, encodeURIComponent, isNaN, Error,
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext([ADDRESS_READY, FACTS, NOTE_ORG, MANIFEST, WATCH].join('\n'), sandbox);
+  const settle = async () => { for (let i = 0; i < 6; i++) { await Promise.all(inflight.slice()); await new Promise((r) => setImmediate(r)); } };
+  vm.runInContext('startProgress(42)', sandbox);
+  await settle();
+  const read = () => {
+    const facts = dom.body.querySelectorAll('[data-fact]').map((f) => ({
+      key: f.getAttribute('data-fact'),
+      state: f.className.replace(/^setFact /, ''),
+      title: f.querySelector('.t')._text,
+      sub: (f.querySelector('small') || { textContent: '' }).textContent,
+      right: f.querySelector('.r').textContent,
+      acts: f.querySelectorAll('[data-action]').map((b) => b.getAttribute('data-action')).concat(f.querySelectorAll('.btn').filter((b) => !b.getAttribute('data-action')).map((b) => 'link:' + b.textContent)),
+      labels: (f.querySelector('.acts') || { descendants: () => [] }).descendants().filter((n) => /^(BUTTON|A|SUMMARY)$/.test(n.tagName)).map((n) => n.textContent),
+    }));
+    return {
+      facts, byKey: Object.fromEntries(facts.map((f) => [f.key, f.state])),
+      title: dom.$('donePartT').textContent, count: dom.$('ghState').textContent, said: dom.$('setupNow').textContent,
+      aliveHidden: dom.$('doneAlive').hidden, aliveH: dom.$('done-h').textContent, genesis: dom.$('enterGenesis').getAttribute('href'),
+      hopLinkHidden: dom.$('hopLink').hidden, pickInApprove: !!dom.body.querySelector('[data-fact="approve"] .acts') && dom.body.querySelector('[data-fact="approve"] .acts').contains(dom.$('aaPick')),
+    };
+  };
+  const again = async () => { vm.runInContext('progressKick()', sandbox); await settle(); };
+  return { sandbox, dom, calls, read, again };
+}
+
+// ── the rows: one project per scenario of the mockup ───────────────────────────────────
+const NOW = Date.now();
+const ago = (min) => new Date(NOW - min * 60000).toISOString();
+const soon = (min) => new Date(NOW + min * 60000).toISOString();
+const INST = { id: 42, owner_builder_id: 7, slug: 'kestrel', domain: 'kestrel.cloudbongos.com', target_ref: 'you/kestrel', hosting_shape: 'cloud-host', onboard_mode: 'greenfield', torn_down_at: null };
+const inst = (over) => ({ ...INST, status: 'active', created_at: ago(30), updated_at: ago(20), provisioned_at: ago(27), last_verified_at: ago(0.1), last_verified_up: true, dns_resolved_at: ago(25), ...over });
+const attempt = (over) => ({ id: 9, instance_id: 42, state: 'S9', requested_by: 7, attempts: 1, created_at: ago(15), expires_at: ago(1), ...over });
+const installed = { event: 'github-app-installed', at: ago(10), detail: 'you/kestrel' };
+const SCENARIOS = {
+  'Just created': {
+    rows: { inst: inst({ status: 'provisioning', created_at: ago(1), provisioned_at: null, last_verified_at: null, last_verified_up: null, dns_resolved_at: null }), intent: { action: 'provision', state: 'running' }, manifest: null, events: [] },
+    count: '1 of 6 done',
+    states: { address: 'done', server: 'now', answers: 'todo', approve: 'you', install: 'todo', sign_in: 'todo', device_flow: 'todo' },
+    said: 'Setting up its home. You can connect GitHub now; nothing waits on you otherwise.',
+  },
+  'Waiting on GitHub': {
+    rows: { inst: inst({ last_verified_at: null, last_verified_up: null, dns_resolved_at: null }), intent: null, manifest: attempt({ status: 'pending', attempts: 0, created_at: ago(1), expires_at: soon(29) }), events: [] },
+    count: '2 of 6 done',
+    states: { address: 'done', server: 'done', answers: 'now', approve: 'you', install: 'todo', sign_in: 'todo', device_flow: 'todo' },
+    said: 'Your turn on GitHub: approve the app in the tab that opened. This page ticks on its own when you do, on any device.',
+  },
+  Installing: {
+    rows: { inst: inst(), intent: null, manifest: attempt({ status: 'converting', app_id: 5, app_slug: 'kestrel-cloudbongos-com', updated_at: ago(1) }), events: [] },
+    count: '4 of 6 done',
+    states: { address: 'done', server: 'done', answers: 'done', approve: 'done', install: 'you', sign_in: 'now', device_flow: 'todo' },
+    said: 'Your turn on GitHub: confirm the install on you/kestrel. The repo is already picked.',
+  },
+  Stopped: {
+    rows: { inst: inst(), intent: null, manifest: attempt({ status: 'done', app_id: 5, app_slug: 'kestrel-cloudbongos-com', created_at: ago(300), resolved_at: ago(290), updated_at: ago(290) }), events: [] },
+    count: '5 of 6 done',
+    states: { address: 'done', server: 'done', answers: 'done', approve: 'done', install: 'bad', sign_in: 'done', device_flow: 'todo' },
+    said: 'One step stopped. Nothing is lost, and no second app will be made.',
+  },
+  'All done': {
+    rows: { inst: inst(), intent: null, manifest: attempt({ status: 'done', app_id: 5, app_slug: 'kestrel-cloudbongos-com', resolved_at: ago(12), updated_at: ago(12) }), events: [installed] },
+    count: 'ready ✓',
+    states: { address: 'done', server: 'done', answers: 'done', approve: 'done', install: 'done', sign_in: 'done', device_flow: 'todo' },
+    said: 'Kestrel is ready. Command-line sign-in is optional; it ticks itself whenever you turn it on.',
+  },
+};
+const ORDER = ['address', 'server', 'answers', 'approve', 'install', 'sign_in', 'device_flow'];
+async function scenario(name, opts) { db = JSON.parse(JSON.stringify(SCENARIOS[name].rows)); return page(opts); }
+
+// every word part 03 says, split into sentences (the right-hand "when" is not a sentence)
+function sentences(v) {
+  const parts = [v.said, v.title, v.aliveHidden ? '' : v.aliveH, ...v.facts.flatMap((f) => [f.title, f.sub, ...f.labels])];
+  return parts.join('\n').split(/(?<=[.!?])\s+|\n/).map((s) => s.trim()).filter(Boolean);
+}
+const OUTDATED = ['Request filed', 'Standing it up', 'Revive queued', 'Placing credentials', 'Ready to sign in',
+  'Filed. Watching for the standup', 'A standup is queued', 'The standup stopped partway', 'These steps are the same however',
+  'Setting up Kestrel', 'Setting up your project', 'Watch it here', 'Watch the rest here', 'Prefer to create an OAuth app by hand',
+  'Create the empty GitHub repo', 'Enter your builders hall', 'bongos dev', 'Placing the app’s keys', 'placing the app’s keys'];
+
+// ── 1. the five scenarios, from the real read ──────────────────────────────────────────
+for (const name of Object.keys(SCENARIOS)) {
+  test(`${name}: the real owner read draws the mockup's count, facts and one sentence`, async () => {
+    const want = SCENARIOS[name];
+    const p = await scenario(name);
+    const v = p.read();
+    assert.equal(v.title, 'Getting Kestrel ready');
+    assert.equal(v.count, want.count, 'optional facts are not counted');
+    assert.deepEqual(v.facts.map((f) => f.key), ORDER, 'two groups, each fact once, in the mockup\'s order');
+    assert.deepEqual(v.byKey, want.states);
+    assert.equal(v.said, want.said, 'one sentence: what is happening now, and whether it is the founder\'s turn');
+    // Connect GitHub and the account choice sit inside the Approve fact while it is offered
+    const approve = v.facts.find((f) => f.key === 'approve');
+    assert.equal(approve.acts.includes('manifest-start'), name === 'Just created');
+    assert.equal(v.pickInApprove, name === 'Just created', 'the account select is inside the Approve fact only while Connect is offered');
+    // a stopped fact carries the one fix
+    for (const f of v.facts.filter((x) => x.state === 'bad')) assert.equal(f.acts.filter((a) => a === 'pick-up').length, 1, `${f.key}: one "Pick up where it stopped"`);
+    // "is alive", the invite and Enter Genesis only when every required fact is done
+    const ready = name === 'All done';
+    assert.equal(v.aliveHidden, !ready);
+    assert.equal(v.genesis, ready ? 'https://kestrel.cloudbongos.com' : null, 'Enter Genesis opens the project\'s own address, and only then');
+    if (ready) { assert.equal(v.aliveH, 'Kestrel is alive.'); assert.deepEqual(p.calls.invite, [true]); assert.equal(p.calls.arrive, 1, 'the game, if open, puts itself away'); }
+    else assert.deepEqual(p.calls.invite, [], 'the invite box stays shut');
+    assert.equal(v.hopLinkHidden, ready, '"Play cloud hop while you wait" while there is a wait');
+  });
+}
+
+// ── 2. every fact's state is a server field ────────────────────────────────────────────
+test('moving the clock moves nothing but the right-hand "when": no fact\'s state is a timer', async () => {
+  for (const name of Object.keys(SCENARIOS)) {
+    const a = (await scenario(name)).read();
+    const b = (await scenario(name, { clockShift: 3 * 3600 * 1000 })).read();
+    assert.deepEqual(b.byKey, a.byKey, `${name}: three hours later the same read draws the same facts`);
+    assert.equal(b.count, a.count);
+    assert.equal(b.said, a.said);
+  }
+});
+
+test('moving one server field moves its fact — each of the seven, from the real read', async () => {
+  const base = SCENARIOS.Installing.rows;
+  const flips = [
+    ['address', 'instance.domain', { inst: { ...base.inst, domain: null } }, 'todo'],
+    ['server', 'instance.status', { inst: { ...base.inst, status: 'provisioning' } }, 'now'],
+    ['server', 'open_intent', { inst: { ...base.inst, status: 'torn_down', torn_down_at: ago(5) }, intent: { action: 'provision', state: 'queued' } }, 'now'],
+    ['server', 'instance.status (error)', { inst: { ...base.inst, status: 'error' } }, 'bad'],
+    ['answers', 'dns_resolves', { inst: { ...base.inst, dns_resolved_at: null, last_verified_up: null } }, 'now'],
+    ['answers', 'last_verified_up', { inst: { ...base.inst, last_verified_up: false } }, 'now'],
+    ['approve', 'the attempt (none yet)', { manifest: null }, 'you'],
+    ['install', 'github-setup checklist.install', { events: [installed] }, 'done'],
+    ['sign_in', 'github-setup checklist.sign_in', { manifest: { ...base.manifest, status: 'done', resolved_at: ago(1) } }, 'done'],
+    ['device_flow', 'github-setup checklist.device_flow', { manifest: { ...base.manifest, status: 'done', resolved_at: ago(1) }, events: [installed, { event: 'github-app-device-flow', at: ago(2) }] }, 'done'],
+  ];
+  const before = (await scenario('Installing')).read().byKey;
+  for (const [key, field, rows, want] of flips) {
+    db = { ...JSON.parse(JSON.stringify(base)), ...JSON.parse(JSON.stringify(rows)) };
+    const after = (await page()).read().byKey;
+    assert.notEqual(before[key], want, `${key}: the flip must actually move it (${field})`);
+    assert.equal(after[key], want, `${key} follows ${field}`);
+  }
+});
+
+test('the right-hand side says when the server saw it, or what it found', async () => {
+  const v = (await scenario('Installing')).read();
+  const right = Object.fromEntries(v.facts.map((f) => [f.key, f.right]));
+  assert.match(right.address, /^(just now|\d{1,2}:\d\d [ap]m)$/, 'when the address was kept (instance.created_at)');
+  assert.match(right.server, /^(just now|\d{1,2}:\d\d [ap]m)$/, 'when it started running (instance.provisioned_at)');
+  assert.match(right.answers, /^checked \d+s ago$/, 'when it last answered (instance.last_verified_at)');
+  assert.equal(right.install, 'not yet seen', 'what GitHub has told the runner so far');
+  // what it found, under the fact: the address once it resolves, the repo, the app's account
+  const sub = Object.fromEntries(v.facts.map((f) => [f.key, f.sub]));
+  assert.equal(sub.address, 'kestrel.cloudbongos.com');
+  assert.equal(sub.approve, 'Kestrel app on your account');
+  assert.equal(sub.install, 'you/kestrel');
+  const stopped = (await scenario('Stopped')).read();
+  assert.match(stopped.facts.find((f) => f.key === 'install').right, /^checked \d+s ago$/, 'a stop says when it was last checked');
+});
+
+// ── 3. nothing said twice, nothing outdated, nothing markup ────────────────────────────
+test('no fact is said twice, and none of the outdated words is anywhere', async () => {
+  for (const name of Object.keys(SCENARIOS)) {
+    const v = (await scenario(name)).read();
+    const said = sentences(v);
+    const twice = said.filter((s, i) => said.indexOf(s) !== i);
+    assert.deepEqual(twice, [], `${name}: nothing is said twice`);
+    for (const old of OUTDATED) assert.ok(!said.join('\n').includes(old), `${name}: "${old}" is gone`);
+  }
+  // …nor anywhere in part 03's markup or the code that draws it
+  for (const old of OUTDATED) {
+    assert.ok(!PANEL.includes(old), `part 03's markup no longer says "${old}"`);
+    assert.ok(!(FACTS + WATCH).includes(old), `part 03's code no longer says "${old}"`);
+  }
+  for (const id of ['liveProgress', 'hopBar', 'hopBarFill', 'hopStatus', 'humanSteps', 'doneLede']) assert.ok(!HUB.includes(`id="${id}"`), `#${id} is gone`);
+  assert.doesNotMatch(SCRIPT, /PROG_FLOWS|progressMarkup|momentFor|setMoment|ticks > 400/, 'no stage strip, no moment, no tick counter');
+});
+
+test('part 03 is drawn from nodes: the DOM stub refuses innerHTML, and a typed name stays text', async () => {
+  db = JSON.parse(JSON.stringify(SCENARIOS['Just created'].rows));
+  const p = await page();
+  p.sandbox.state.name = 'Kes<b>trel</b>';
+  vm.runInContext('repaintFacts()', p.sandbox);
+  const v = p.read();
+  assert.equal(v.title, 'Getting Kes<b>trel</b> ready', 'the name is text');
+  assert.equal(v.facts.find((f) => f.key === 'approve').title, 'Approve the Kes<b>trel</b> app on GitHub');
+  assert.doesNotMatch(FACTS + WATCH, /\.innerHTML\s*=/, 'no innerHTML anywhere in part 03\'s code');
+});
+
+test('a part 03 link goes only to GitHub, this page or its sign-in; anything else is text', async () => {
+  db = JSON.parse(JSON.stringify(SCENARIOS.Installing.rows));
+  const p = await page();
+  const href = (h) => vm.runInContext(`factHref(${JSON.stringify(h)})`, p.sandbox);
+  for (const ok of ['https://github.com/apps/kestrel-app/installations/new?state=S1', 'https://github.com/settings/apps/kestrel-app', '?view=manage&id=42', '?view=mine', '/api/bongos/auth/web/start?return=/projects%3Fview%3Dnew&repos=1']) {
+    assert.equal(href(ok), ok, ok);
+  }
+  for (const bad of ['javascript:alert(1)', 'https://evil.example/x', 'https://github.com.evil.example/x', '//evil.example', 'data:text/html,x', '?view=manage&id=1"><b>']) {
+    assert.equal(href(bad), '', bad);
+  }
+  // a hostile install link that somehow reached the fact never becomes an href
+  const box = p.dom.doc.createElement('div');
+  vm.runInContext('(function (box) { box.appendChild(factAct("install-link", { href: "javascript:alert(1)" })); })', p.sandbox)(box);
+  assert.equal(box.children[0].getAttribute('href'), 'https://github.com/settings/installations');
+  const line = p.dom.doc.createElement('p');
+  vm.runInContext('partsInto', p.sandbox)(line, [{ t: 'click', href: 'https://evil.example/' }]);
+  assert.equal(line.children.length, 0, 'drawn as text, not an anchor');
+  assert.equal(line.textContent, 'click');
+});
+
+// ── 4. one live region, written only on a real change ──────────────────────────────────
+test('the sentence is the one live region, written only when its words change', async () => {
+  // the sentence (role=status + aria-live) is the one region that speaks for the setup; the
+  // others answer an action the founder just took: the Render key and the look sends
+  // (role=status), the organisation check, and an invite (role=status + aria-live)
+  assert.equal((PANEL.match(/aria-live=|role="status"/g) || []).length, 7, 'no other live region in part 03');
+  assert.match(PANEL, /<p class="setNow" id="setupNow" role="status" aria-live="polite"><\/p>/);
+  assert.doesNotMatch(PANEL, /id="(homeFacts|ghFacts|hopScore|ghState)"[^>]*aria-live/, 'the facts, the score and the count are not live regions');
+  const p = await scenario('Waiting on GitHub');
+  const line = p.dom.$('setupNow');
+  const writes = line.writes;
+  await p.again();
+  assert.equal(line.writes, writes, 'an identical read writes nothing to the live region');
+  db.inst.dns_resolved_at = ago(0.5);
+  db.inst.last_verified_up = true;
+  await p.again();
+  assert.equal(p.read().byKey.answers, 'done');
+  assert.equal(line.writes, writes, 'a fact ticking under the same sentence is not announced twice');
+  db.manifest = attempt({ status: 'converting', app_id: 5, app_slug: 'kestrel-cloudbongos-com', updated_at: ago(0.2) });
+  await p.again();
+  assert.ok(line.writes > writes, 'the founder\'s turn moving on is announced');
+  assert.equal(p.read().said, 'Your turn on GitHub: confirm the install on you/kestrel. The repo is already picked.');
+});
+
+test('a fact\'s buttons are rebuilt only when the fact changes, so a poll never steals the focus', async () => {
+  const p = await scenario('Just created');
+  const approve = p.dom.body.querySelector('[data-fact="approve"]');
+  await p.again();
+  assert.equal(p.dom.body.querySelector('[data-fact="approve"]'), approve, 'the same node: an unchanged fact is left alone');
+});
+
+// ── 5. the page's own guards ───────────────────────────────────────────────────────────
+test('no wizard function is declared twice (a second paintSetup once silently replaced part 02\'s)', () => {
+  const names = [...SCRIPT.matchAll(/\n {4}function (\w+)\(/g)].map((m) => m[1]);
+  const twice = [...new Set(names.filter((n, i) => names.indexOf(n) !== i))];
+  // tick() is the one name two separate closures declare on purpose (the manifest poll and
+  // the hub's own watch); everything else is one function per name
+  assert.deepEqual(twice, ['tick']);
+});
+
+test('part 03 names its own classes: the map table already owns .facts / .fact', () => {
+  // the first cut drew part 03 as .fact and restyled the projects table's .facts > .fact spans
+  const style = HUB.slice(HUB.indexOf('<style>'), HUB.indexOf('</style>'));
+  assert.doesNotMatch(style, /(^|[\s,}])\.facts?[\s{.:,]/m, 'no page rule for the table\'s .facts / .fact');
+  assert.match(PANEL, /<div class="setFacts" id="homeFacts"/);
+  assert.match(FACTS, /textNode\('div', 'setFact ' \+ r\.state\)/);
+});