@bongos/core 1.19.1041 → 1.19.1042

package/tests/npm_release_work.mjs

@@ -15,9 +15,8 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { createRequire } from 'node:module';
-import { EventEmitter } from 'node:events';
-import { Readable } from 'node:stream';
-import zlib from 'node:zlib';
+
+import { npmTarball, npmPackument, fakeHttpsGet } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const { readWork } = require('../modules/npm-release/work.js');
@@ -26,90 +25,6 @@ const buildRouter = require('../modules/npm-release/routes/work.js');
 const ORIGIN = 'https://registry.npmjs.org';
 const PKG = '@bongos/core';
 
-// ---- a real tarball, built by hand ---------------------------------------------------
-
-function tarHeader(name, size, type = '0') {
-  const h = Buffer.alloc(512, 0);
-  h.write(name.slice(0, 100), 0, 'utf8');
-  h.write('0000644\0', 100, 'ascii');
-  h.write('0000000\0', 108, 'ascii');
-  h.write('0000000\0', 116, 'ascii');
-  h.write(`${size.toString(8).padStart(11, '0')}\0`, 124, 'ascii');
-  h.write('00000000000\0', 136, 'ascii');
-  h.write('        ', 148, 'ascii');
-  h.write(type, 156, 'ascii');
-  h.write('ustar\0', 257, 'ascii');
-  h.write('00', 263, 'ascii');
-  let sum = 0;
-  for (const b of h) sum += b;
-  h.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148, 'ascii');
-  return h;
-}
-function tarEntry(name, data, type = '0') {
-  const body = Buffer.isBuffer(data) ? data : Buffer.from(data);
-  const pad = Buffer.alloc((512 - (body.length % 512)) % 512, 0);
-  return Buffer.concat([tarHeader(name, body.length, type), body, pad]);
-}
-function paxEntry(path) {
-  // A pax record is "<len> <key>=<value>\n", where <len> counts its own digits too.
-  const rec = (k, v) => {
-    const body = ` ${k}=${v}\n`;
-    let n = body.length + 1;
-    while (String(n).length + body.length !== n) n = String(n).length + body.length;
-    return `${n}${body}`;
-  };
-  return tarEntry('PaxHeader/x', rec('path', path), 'x');
-}
-/** A gzipped npm-shaped tarball. `notes` null leaves release-notes.json out. */
-function tarball({ notes, padBytes = 40000, pax = false } = {}) {
-  const parts = [
-    tarEntry('package/package.json', JSON.stringify({ name: PKG })),
-    // A large file BEFORE the notes, so the reader has to skip across many chunks.
-    tarEntry('package/big.js', Buffer.alloc(padBytes, 97)),
-  ];
-  if (notes) {
-    const json = JSON.stringify(notes);
-    if (pax) parts.push(paxEntry('package/release-notes.json'), tarEntry('package/SHORTNAME', json));
-    else parts.push(tarEntry('package/release-notes.json', json));
-  }
-  parts.push(Buffer.alloc(1024, 0));
-  return zlib.gzipSync(Buffer.concat(parts));
-}
-
-// ---- a fake registry -----------------------------------------------------------------
-
-function packument({ versions, latest, times }) {
-  const doc = { name: PKG, 'dist-tags': { latest }, versions: {}, time: {} };
-  for (const v of versions) {
-    doc.versions[v] = { version: v, dist: { tarball: `${ORIGIN}/@bongos/core/-/core-${v}.tgz` } };
-    doc.time[v] = times[v];
-  }
-  return doc;
-}
-
-/** `get` answering from `routes` (url → { status, body }), recording every URL asked for. */
-function fakeGet(routes) {
-  const asked = [];
-  const get = (url, opts, cb) => {
-    asked.push(url);
-    const req = new EventEmitter();
-    req.destroy = () => {};
-    setImmediate(() => {
-      const r = routes[url];
-      if (!r) { req.emit('error', new Error(`no route for ${url}`)); return; }
-      const body = Buffer.isBuffer(r.body) ? r.body : Buffer.from(typeof r.body === 'string' ? r.body : JSON.stringify(r.body));
-      // Small chunks, so a tar header lands across a chunk boundary.
-      const chunks = [];
-      for (let i = 0; i < body.length; i += 777) chunks.push(body.subarray(i, i + 777));
-      const res = Readable.from(chunks);
-      res.statusCode = r.status || 200;
-      cb(res);
-    });
-    return req;
-  };
-  return { get, asked };
-}
-
 function fakePool(tasks, titles = {}) {
   const queries = [];
   return {
@@ -153,13 +68,13 @@ const TASKS = [
   row('23', 'shipped', '2026-09-24T08:00:00.000Z', { value_summary: 'A hand-landed change nobody numbered.' }),
 ];
 
-function setup({ latest = '1.0.5', tgz = tarball({ notes: NOTES }), pkStatus = 200, tgzStatus = 200, installed = INSTALLED_TO_103, tasks = TASKS, titles = {} } = {}) {
+function setup({ latest = '1.0.5', tgz = npmTarball({ notes: NOTES }), pkStatus = 200, tgzStatus = 200, installed = INSTALLED_TO_103, tasks = TASKS, titles = {} } = {}) {
   const versions = Object.keys(TIMES);
   const routes = {
-    [`${ORIGIN}/@bongos%2fcore`]: { status: pkStatus, body: pkStatus === 200 ? packument({ versions, latest, times: TIMES }) : 'nope' },
+    [`${ORIGIN}/@bongos%2fcore`]: { status: pkStatus, body: pkStatus === 200 ? npmPackument({ versions, latest, times: TIMES }) : 'nope' },
     [`${ORIGIN}/@bongos/core/-/core-1.0.5.tgz`]: { status: tgzStatus, body: tgz },
   };
-  const fg = fakeGet(routes);
+  const fg = fakeHttpsGet(routes);
   const pool = fakePool(tasks, titles);
   const store = freshStore();
   const read = (over = {}) => readWork({ pool, pkg: PKG, live: '1.0.3', get: fg.get, store, installedNotes: installed, now: () => Date.parse('2026-09-26T13:00:00Z'), ...over });
@@ -223,7 +138,7 @@ test('notes past the installed copy are read out of the newest package', async (
 });
 
 test('a pax long-name header is followed to the notes file', async () => {
-  const d = await setup({ tgz: tarball({ notes: NOTES, pax: true }) }).read();
+  const d = await setup({ tgz: npmTarball({ notes: NOTES, pax: true }) }).read();
   assert.equal(d.notes.covers_to, '1.0.5');
   assert.deepEqual(ids(d.stages.not_live), ['15']);
 });
@@ -236,7 +151,7 @@ test('when the installed notes already reach the newest version, nothing is down
 });
 
 test('a package without notes is an error, not an empty history', async () => {
-  const d = await setup({ tgz: tarball({ notes: null }) }).read();
+  const d = await setup({ tgz: npmTarball({ notes: null }) }).read();
   assert.match(d.notes.error, /without release notes/);
   // The installed copy stands in: the work up to 1.0.3 is still placed.
   assert.deepEqual(d.notes.source, { from: 'installed', version: '1.0.3' });
@@ -262,9 +177,9 @@ test('a registry that does not answer is reported, and the installed notes still
 
 test('the package download is only ever followed on the registry\'s own origin', async () => {
   const versions = Object.keys(TIMES);
-  const doc = packument({ versions, latest: '1.0.5', times: TIMES });
+  const doc = npmPackument({ versions, latest: '1.0.5', times: TIMES });
   doc.versions['1.0.5'].dist.tarball = 'https://evil.example/core.tgz';
-  const fg = fakeGet({ [`${ORIGIN}/@bongos%2fcore`]: { body: doc } });
+  const fg = fakeHttpsGet({ [`${ORIGIN}/@bongos%2fcore`]: { body: doc } });
   const d = await readWork({ pool: fakePool(TASKS), pkg: PKG, live: '1.0.3', get: fg.get, store: freshStore(), installedNotes: INSTALLED_TO_103 });
   assert.ok(!fg.asked.some((u) => u.includes('evil.example')));
   assert.match(d.notes.error, /no download/);

package/tests/software_update.mjs

@@ -0,0 +1,449 @@
+// tests/software_update.mjs — Settings → Software update (task 1004296): the core's reading
+// (src/bongos/software-update.js over the real registry reader), its route, the panel
+// script executed in a DOM stub, and the /deploy page answering only where the door is.
+//
+// WHAT IS AT RISK. The panel is trusted the way a phone's Software Update screen is: "up to
+// date" must only ever be said from an answer, never from a failed read; the versions it
+// offers must be exactly the ones the upgrade runner would take (its channel rule, not a
+// copy); what's new must come from the package's release notes and say so when they could
+// not be read; and the Update button must be drawn only for the people the door lets
+// through, pointing only at that door.
+//
+// Run:  node tests/software_update.mjs
+import assert from 'node:assert/strict';
+import { test, after } from 'node:test';
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { npmTarball, npmPackument, fakeHttpsGet } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { readSoftwareUpdate } = require('../src/bongos/software-update.js');
+
+const ORIGIN = 'https://registry.npmjs.org';
+const PACKUMENT_URL = `${ORIGIN}/@bongos%2fcore`;
+const tgzUrl = (v) => `${ORIGIN}/@bongos/core/-/core-${v}.tgz`;
+
+const VERSIONS = ['1.19.10', '1.19.11', '1.19.12', '1.19.13', '1.20.0'];
+const TIMES = Object.fromEntries(VERSIONS.map((v, i) => [v, `2026-09-2${i}T10:00:00.000Z`]));
+const NOTES = {
+  '1.19.10': [{ id: 90, text: 'Already running.' }],
+  '1.19.11': [{ id: 101, text: 'Fixed the first thing.' }],
+  '1.19.12': [],
+  '1.19.13': [{ id: '103', text: 'A <b>third</b> thing.' }, { text: 'A merge that named no task.' }],
+  '1.20.0': [{ id: 200, text: 'The start of a new line.' }],
+};
+
+/** A registry that answers the packument and the NEWEST version's tarball. */
+function registry({ versions = VERSIONS, notes = NOTES, pkStatus = 200, tgzStatus = 200, tgz } = {}) {
+  const newest = versions[versions.length - 1];
+  return fakeHttpsGet({
+    [PACKUMENT_URL]: { status: pkStatus, body: npmPackument({ versions, latest: newest, times: TIMES }) },
+    [tgzUrl(newest)]: { status: tgzStatus, body: tgz || npmTarball({ notes }) },
+  });
+}
+const fresh = () => ({ packument: { at: 0, value: null, inflight: null }, notes: { version: null, at: 0, value: null, inflight: null } });
+const read = (running, reg = registry(), extra = {}) => readSoftwareUpdate({ running, get: reg.get, store: fresh(), now: () => Date.parse('2026-09-26T12:00:00Z'), ...extra });
+
+// ---- the reading ---------------------------------------------------------------------
+
+test('behind: offers the newest version its channel takes, never the next line', async () => {
+  const u = await read('1.19.10');
+  assert.equal(u.reading, 'ok');
+  assert.equal(u.running, '1.19.10');
+  assert.equal(u.channel, 'patch', 'no channel given: the runner\'s default, exactly as the banner');
+  assert.equal(u.offered, '1.19.13', 'the patch channel stays within 1.19');
+  assert.equal(u.newest, '1.20.0', 'the newer line is reported, so the panel can say why it is not offered');
+  assert.equal(u.offered_published_at, TIMES['1.19.13']);
+  assert.equal(u.checked_at, '2026-09-26T12:00:00.000Z');
+});
+
+test("what's new: every version in the update, newest first, from the package's own notes", async () => {
+  const reg = registry();
+  const u = await read('1.19.10', reg);
+  const w = u.whats_new;
+  assert.equal(w.ok, true);
+  assert.equal(w.count, 3);
+  assert.deepEqual(w.versions.map((v) => v.version), ['1.19.13', '1.19.12', '1.19.11'], 'not the running one, not past the offer');
+  assert.deepEqual(w.versions[0].entries, [{ id: '103', text: 'A <b>third</b> thing.' }, { id: null, text: 'A merge that named no task.' }],
+    'text is carried as written (the page escapes it); a merge with no task keeps its line');
+  assert.deepEqual(w.versions[1].entries, [], 'a version with nothing listed is empty, not missing');
+  assert.deepEqual(w.versions[2].entries, [{ id: '101', text: 'Fixed the first thing.' }]);
+  assert.equal(w.versions[0].published_at, TIMES['1.19.13']);
+  assert.ok(reg.asked.includes(tgzUrl('1.20.0')), 'the newest package carries the whole history, so it is the one read');
+});
+
+test('up to date: said only from an answer, and nothing is downloaded', async () => {
+  const reg = registry();
+  const u = await read('1.20.0', reg);
+  assert.equal(u.reading, 'ok');
+  assert.equal(u.offered, null);
+  assert.equal(u.whats_new, null);
+  assert.deepEqual(reg.asked, [PACKUMENT_URL], 'no tarball when nothing newer is published');
+});
+
+test('a registry that does not answer is a failed check — never "up to date"', async () => {
+  const u = await read('1.19.10', registry({ pkStatus: 500 }));
+  assert.equal(u.reading, 'no_answer');
+  assert.match(u.error, /500/);
+  assert.equal(u.offered, null);
+  assert.equal(u.whats_new, null);
+});
+
+test('a project that cannot name its own version gets no verdict', async () => {
+  for (const running of [null, '', 'not-a-version']) {
+    const u = await read(running);
+    assert.equal(u.reading, 'no_answer', String(running));
+    assert.match(u.error, /version it runs/);
+  }
+});
+
+test('notes that could not be read say so, and the versions are still listed', async () => {
+  const noNotes = await read('1.19.10', registry({ tgz: npmTarball({ notes: null }) }));
+  assert.equal(noNotes.offered, '1.19.13', 'the offer does not depend on the notes');
+  assert.equal(noNotes.whats_new.ok, false);
+  assert.match(noNotes.whats_new.error, /without release notes/);
+  assert.deepEqual(noNotes.whats_new.versions.map((v) => v.entries), [null, null, null], 'unread, not empty');
+
+  const failed = await read('1.19.10', registry({ tgzStatus: 404 }));
+  assert.equal(failed.whats_new.ok, false);
+  assert.match(failed.whats_new.error, /could not download/);
+});
+
+test('a version the notes do not list is missing, not empty', async () => {
+  const notes = { ...NOTES };
+  delete notes['1.19.11'];
+  const u = await read('1.19.10', registry({ notes }));
+  const v = u.whats_new.versions.find((x) => x.version === '1.19.11');
+  assert.equal(v.entries, null);
+});
+
+test('every line off the network is re-checked: bounded, blank dropped, ids digits only', async () => {
+  const long = 'x'.repeat(900);
+  const notes = { ...NOTES, '1.19.11': [{ id: 7, text: long }, { id: 8, text: '   ' }, { id: '1; DROP', text: 'odd id' }, null] };
+  const u = await read('1.19.10', registry({ notes }));
+  const e = u.whats_new.versions.find((x) => x.version === '1.19.11').entries;
+  assert.equal(e.length, 2);
+  assert.equal(e[0].text.length, 400);
+  assert.ok(e[0].text.endsWith('…'));
+  assert.deepEqual(e[1], { id: null, text: 'odd id' });
+});
+
+test('a project far behind lists the newest forty and counts the rest', async () => {
+  const versions = Array.from({ length: 52 }, (_, i) => `1.19.${i}`);
+  const notes = Object.fromEntries(versions.map((v) => [v, [{ id: 1, text: v }]]));
+  const reg = fakeHttpsGet({
+    [PACKUMENT_URL]: { body: npmPackument({ versions, latest: '1.19.51', times: {} }) },
+    [tgzUrl('1.19.51')]: { body: npmTarball({ notes }) },
+  });
+  const u = await read('1.19.1', reg);
+  assert.equal(u.whats_new.count, 50);
+  assert.equal(u.whats_new.versions.length, 40);
+  assert.equal(u.whats_new.more, 10);
+  assert.equal(u.whats_new.versions[0].version, '1.19.51');
+});
+
+test('a second look within minutes asks the registry nothing new', async () => {
+  const reg = registry();
+  const store = fresh();
+  const now = () => Date.parse('2026-09-26T12:00:00Z');
+  await readSoftwareUpdate({ running: '1.19.10', get: reg.get, store, now });
+  const n = reg.asked.length;
+  const again = await readSoftwareUpdate({ running: '1.19.10', get: reg.get, store, now });
+  assert.equal(reg.asked.length, n);
+  assert.equal(again.offered, '1.19.13');
+});
+
+// ---- the route -----------------------------------------------------------------------
+
+const ROUTE_SRC = fs.readFileSync(path.join(ROOT, 'src/bongos/routes/core-update.js'), 'utf8');
+
+test('the route is open to every signed-in builder — and only the banner reads stay on the atom', () => {
+  const seg = ROUTE_SRC.slice(ROUTE_SRC.indexOf("'/software-update'"), ROUTE_SRC.indexOf('asyncHandler(\'GET /software-update\''));
+  assert.match(seg, /auth\.requireBuilder/);
+  assert.doesNotMatch(seg, /requirePermission/, 'the version and what is new are for everyone who can open Settings');
+  for (const p of ["'/core-update'", "'/core-upgrades'"]) {
+    const s = ROUTE_SRC.slice(ROUTE_SRC.indexOf(p), ROUTE_SRC.indexOf(p) + 200);
+    assert.match(s, /requirePermission\('core\.pin\.move'\)/, `${p} keeps its gate`);
+  }
+});
+
+async function drive(deps) {
+  const auth = require('../src/bongos/auth.js');
+  const saved = auth.requireBuilder;
+  auth.requireBuilder = (req, _res, next) => { req.builder = { id: '7' }; next(); };
+  const build = require('../src/bongos/routes/core-update.js');
+  const express = require('express');
+  const app = express();
+  app.use(build(deps));
+  auth.requireBuilder = saved;
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  try {
+    const res = await fetch(`http://127.0.0.1:${server.address().port}/software-update`);
+    return { status: res.status, body: await res.json() };
+  } finally { server.close(); }
+}
+const STUB_UPDATE = { reading: 'ok', running: '1.19.10', offered: '1.19.13' };
+
+test('the platform\'s hall: the Update button goes to its own door', async () => {
+  const r = await drive({ softwareUpdate: async () => STUB_UPDATE, canUpdate: async () => true, doorInputs: () => ({ provisioning: true, idp: null }) });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.body.update, STUB_UPDATE);
+  assert.deepEqual(r.body.door, { kind: 'local', url: '/deploy' });
+  assert.equal(r.body.can_update, true);
+});
+
+test('a hosted project: the Update button goes to the hub\'s door for THIS project', async () => {
+  const r = await drive({ softwareUpdate: async () => STUB_UPDATE, canUpdate: async () => true,
+    doorInputs: () => ({ provisioning: false, idp: { origin: 'https://cloudbongos.com/', clientId: 'hoodify-finance' } }) });
+  assert.deepEqual(r.body.door, { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=hoodify-finance' });
+});
+
+test('a self-hosted instance has no door to link, and says how it is upgraded instead', async () => {
+  const r = await drive({ softwareUpdate: async () => STUB_UPDATE, canUpdate: async () => true, doorInputs: () => ({ provisioning: false, idp: null }) });
+  assert.deepEqual(r.body.door, { kind: 'cli', url: null });
+});
+
+test('can_update is strictly the answer "yes" — anything else draws no button', async () => {
+  for (const answer of [false, 'yes', 1, null, undefined]) {
+    const r = await drive({ softwareUpdate: async () => STUB_UPDATE, canUpdate: async () => answer, doorInputs: () => ({ provisioning: true }) });
+    assert.equal(r.body.can_update, false, String(answer));
+  }
+});
+
+test('a reading that throws is a 500 with its own code, not a verdict', async () => {
+  const r = await drive({ softwareUpdate: async () => { throw new Error('boom'); }, canUpdate: async () => true, doorInputs: () => ({ provisioning: true }) });
+  assert.equal(r.status, 500);
+  assert.equal(r.body.error, 'software_update_failed');
+  assert.equal(r.body.message, undefined, 'the internal message is not handed to the page');
+});
+
+// ---- the panel -----------------------------------------------------------------------
+
+const PANEL_SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings-software-update.js'), 'utf8');
+// The fixture the hall-preview harness serves — a reading taken off the live registry for
+// the version cloudbongos.com served on 2026-09-26.
+const FIXTURE = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts/hall-preview/fixtures/software-update.json'), 'utf8'));
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+// Voice rule V4: quoted data renders with its dashes as commas (docs/voice.md).
+const unDash = (raw) => String(raw == null ? '' : raw).replace(/\s*[—–]\s*/g, ', ').replace(/,\s*,/g, ',').trim();
+
+function bootPanel(answer, { active = 'update' } = {}) {
+  const el = () => ({ hidden: true, textContent: '', _html: '', dataset: {}, set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; }, querySelectorAll: () => [] });
+  const els = new Map([['software-update-scroll', el()], ['su-body', el()], ['su-note', el()], ['settings-groups', el()]]);
+  els.get('settings-groups').dataset.active = active;
+  const listeners = {};
+  const asked = [];
+  const assigned = [];
+  const documentObj = {
+    getElementById: (id) => els.get(id) || null,
+    addEventListener: (ev, fn) => { (listeners[ev] ||= []).push(fn); },
+  };
+  const windowObj = {
+    BongosClient: { createClient: () => ({ request: async (m, url) => { asked.push(url); return answer(); } }) },
+    OTB: { escapeHtml },
+    location: { assign: (u) => assigned.push(u) },
+  };
+  const sandbox = { window: windowObj, document: documentObj, console, setTimeout, Date, Math, URL, Promise, String, Number };
+  vm.createContext(sandbox);
+  vm.runInContext(PANEL_SRC, sandbox, { filename: 'settings-software-update.js' });
+  const settle = async () => { for (let i = 0; i < 10; i++) await new Promise((r) => setTimeout(r, 0)); };
+  const open = (group = 'update') => { for (const fn of listeners['settings:group'] || []) fn({ detail: { group } }); };
+  return { els, asked, assigned, settle, open, body: () => els.get('su-body').innerHTML, note: () => els.get('su-note').textContent };
+}
+const ok = (data) => ({ ok: true, status: 200, data });
+
+test('the live reading: the running version, the offer, the button, and every version named', async () => {
+  const b = bootPanel(() => ok(FIXTURE));
+  await b.settle();
+  const html = b.body();
+  assert.equal(b.els.get('software-update-scroll').hidden, false);
+  assert.ok(html.includes(FIXTURE.update.running));
+  assert.match(html, new RegExp(`id="su-update" href="/deploy">Update to ${FIXTURE.update.offered.replace(/\./g, '\\.')}<`));
+  assert.match(html, /Update ready/);
+  for (const v of FIXTURE.update.whats_new.versions) {
+    assert.ok(html.includes(`>${v.version}<`), v.version);
+    for (const e of v.entries) assert.ok(html.includes(escapeHtml(unDash(e.text))), `${v.version}: ${e.text.slice(0, 30)}`);
+  }
+  assert.match(b.note(), /^Checked /);
+});
+
+test('read only when its group opens — most visits to Settings are for something else', async () => {
+  const b = bootPanel(() => ok(FIXTURE), { active: 'account' });
+  await b.settle();
+  assert.deepEqual(b.asked, [], 'nothing asked while another group is open');
+  b.open('sound');
+  await b.settle();
+  assert.deepEqual(b.asked, []);
+  b.open('update');
+  b.open('update');
+  await b.settle();
+  assert.deepEqual(b.asked, ['/api/bongos/software-update'], 'asked once when it opens, however often');
+});
+
+const answerWith = (over) => ok({ ...FIXTURE, ...over, update: { ...FIXTURE.update, ...(over.update || {}) } });
+
+test('a hosted project\'s button names the hub it opens; a self-hosted one names the command', async () => {
+  const hub = bootPanel(() => answerWith({ door: { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=mercury' } }));
+  await hub.settle();
+  assert.match(hub.body(), /href="https:\/\/cloudbongos\.com\/deploy\?project=mercury">Update to [\d.]+ ↗</);
+  assert.match(hub.body(), /on cloudbongos\.com:/);
+
+  const cli = bootPanel(() => answerWith({ door: { kind: 'cli', url: null } }));
+  await cli.settle();
+  assert.doesNotMatch(cli.body(), /id="su-update"/);
+  assert.match(cli.body(), /<code>bongos upgrade<\/code>/);
+});
+
+test('no button for a viewer the door would refuse, or for a door that is not a plain address', async () => {
+  const viewer = bootPanel(() => answerWith({ can_update: false }));
+  await viewer.settle();
+  assert.doesNotMatch(viewer.body(), /id="su-update"/);
+  assert.match(viewer.body(), /Only the people allowed to upgrade/);
+  assert.ok(viewer.body().includes(escapeHtml(unDash(FIXTURE.update.whats_new.versions[0].entries[0].text))), 'what\'s new is for everyone');
+
+  for (const url of ['javascript:alert(1)', '//evil.test/x', 'https://x.test/"><img>']) {
+    const b = bootPanel(() => answerWith({ door: { kind: 'hub', url } }));
+    await b.settle();
+    assert.doesNotMatch(b.body(), /id="su-update"/, url);
+  }
+});
+
+test('up to date is drawn only from an ok reading with nothing offered', async () => {
+  const b = bootPanel(() => answerWith({ update: { offered: null, whats_new: null, newest: FIXTURE.update.running } }));
+  await b.settle();
+  assert.match(b.body(), /Up to date/);
+  assert.doesNotMatch(b.body(), /id="su-update"|What's new/);
+
+  const failed = bootPanel(() => answerWith({ update: { reading: 'no_answer', error: 'the registry answered 503', offered: null, whats_new: null } }));
+  await failed.settle();
+  assert.doesNotMatch(failed.body(), /Up to date/);
+  assert.match(failed.body(), /Could not check for a newer version: the registry answered 503/);
+});
+
+test('a newer line the channel does not take is explained, once, in the note', async () => {
+  const b = bootPanel(() => answerWith({ update: { running: '1.19.13', offered: null, whats_new: null, newest: '1.20.0' } }));
+  await b.settle();
+  assert.match(b.note(), /1\.20\.0 is also published; it starts a new line, and this project takes updates within 1\.19/);
+});
+
+test('unread notes are reported as unread, never as versions with no changes', async () => {
+  const w = { ok: false, error: '1.19.1040 was published without release notes', count: 2, more: 0,
+    versions: [{ version: '1.19.1040', published_at: null, entries: null }, { version: '1.19.1039', published_at: null, entries: null }] };
+  const b = bootPanel(() => answerWith({ update: { whats_new: w } }));
+  await b.settle();
+  assert.match(b.body(), /The release notes could not be read: 1\.19\.1040 was published without release notes/);
+  assert.match(b.body(), /Its notes could not be read/);
+  assert.doesNotMatch(b.body(), /No changes are listed/);
+});
+
+test('task links only where the ids belong — the hall that runs the door — and text is escaped', async () => {
+  const w = { ok: true, error: null, count: 1, more: 0,
+    versions: [{ version: '1.19.1040', published_at: null, entries: [{ id: '42', text: '<img src=x onerror=alert(1)>' }, { id: null, text: 'no task' }] }] };
+  const local = bootPanel(() => answerWith({ update: { whats_new: w } }));
+  await local.settle();
+  assert.match(local.body(), /<a href="\/task\/42">&lt;img src=x onerror=alert\(1\)&gt;<\/a>/);
+  assert.match(local.body(), /<li>no task<\/li>/);
+
+  const hub = bootPanel(() => answerWith({ door: { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=m' }, update: { whats_new: w } }));
+  await hub.settle();
+  assert.doesNotMatch(hub.body(), /\/task\/42/, 'a hosted project\'s hall has no such task');
+});
+
+test('a release-note line is quoted ledger data: its dashes render as commas (V4)', async () => {
+  const w = { ok: true, error: null, count: 1, more: 0,
+    versions: [{ version: '1.19.1040', published_at: null, entries: [{ id: null, text: 'Lists every task — not merged, published – or released' }] }] };
+  const b = bootPanel(() => answerWith({ update: { whats_new: w } }));
+  await b.settle();
+  assert.match(b.body(), /<li>Lists every task, not merged, published, or released<\/li>/);
+  assert.doesNotMatch(b.body().slice(b.body().indexOf('su-entries')), /[—–]/, 'no dash survives in the quoted lines');
+});
+
+test('a long update opens its newest five and folds the rest behind one button', async () => {
+  const versions = Array.from({ length: 8 }, (_, i) => ({ version: `1.19.${100 - i}`, published_at: null, entries: [] }));
+  const b = bootPanel(() => answerWith({ update: { whats_new: { ok: true, error: null, count: 12, more: 4, versions } } }));
+  await b.settle();
+  assert.equal((b.body().match(/<li class="su-version" hidden>/g) || []).length, 3);
+  assert.match(b.body(), /Show 3 more versions/);
+  assert.match(b.body(), /…and 4 older versions, also in this update/);
+});
+
+test('a failed read says so in the panel and may be asked again', async () => {
+  let n = 0;
+  const b = bootPanel(() => { n++; return { ok: false, status: 500, data: { error: 'software_update_failed' } }; });
+  await b.settle();
+  assert.match(b.body(), /Could not check for updates/);
+  b.open('update');
+  await b.settle();
+  assert.equal(n, 2);
+});
+
+// ---- /deploy exists only where the door does -----------------------------------------
+//
+// A REAL REQUEST, in two processes: whether the provisioning module is on is read from the
+// environment at require time, so each shape boots its own server (the
+// tests/single_host_apex_routes.mjs harness). node:http, not fetch — a redirect must be read,
+// not followed, and fetch cannot send a Host header at all.
+
+const SERVER_SRC = `
+  const express = require('express');
+  const { mountInternalSurfaces } = require(${JSON.stringify(path.join(ROOT, 'src/bongos/serve-internal.js'))});
+  const app = express();
+  mountInternalSurfaces(app);
+  const s = app.listen(0, () => console.log('PORT ' + s.address().port));
+`;
+const children = [];
+after(() => { for (const c of children) c.kill(); });
+
+function startServer(env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['-e', SERVER_SRC], { cwd: ROOT, env: { ...process.env, ...env }, stdio: ['ignore', 'pipe', 'pipe'] });
+    children.push(child);
+    let out = '';
+    let err = '';
+    const timer = setTimeout(() => reject(new Error(`server did not start; stderr: ${err}`)), 30000);
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (c) => { err += c; });
+    child.stdout.on('data', (c) => {
+      out += c;
+      const m = out.match(/PORT (\d+)/);
+      if (m) { clearTimeout(timer); resolve(Number(m[1])); }
+    });
+    child.on('exit', (code) => { if (!/PORT \d+/.test(out)) { clearTimeout(timer); reject(new Error(`server exited ${code}: ${err}`)); } });
+  });
+}
+// Asked on the hall's own host, where the page lives at /deploy (the builders shim roots it).
+function get(port, p) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, path: p, headers: { Host: 'builders.hall.test' } }, (res) => { res.resume(); res.on('end', () => resolve({ status: res.statusCode, location: res.headers.location })); });
+    req.on('error', reject);
+    req.end();
+  });
+}
+const MODULE_ENV = 'BONGOS_MODULE_PROVISIONING';
+
+test('/deploy answers with Settings → Software update on a hall that does not run the door', async () => {
+  const port = await startServer({ [MODULE_ENV]: '0' });
+  for (const p of ['/deploy', '/deploy.html', '/deploy/']) {
+    const r = await get(port, p);
+    assert.equal(r.status, 302, p);
+    assert.equal(r.location, '/settings#software-update', p);
+  }
+  const other = await get(port, '/settings');
+  assert.notEqual(other.location, '/settings#software-update', 'only /deploy is sent there');
+});
+
+test('the platform, which runs the door, keeps /deploy behind its own page gate', async () => {
+  const port = await startServer({ [MODULE_ENV]: '1' });
+  const r = await get(port, '/deploy');
+  assert.notEqual(r.location, '/settings#software-update', 'not redirected away');
+  assert.equal(r.status, 302, 'a visitor with no session meets the page gate');
+  assert.match(String(r.location), /auth|sign/i, 'and is sent to sign in, as before');
+});