@bongos/core 1.21.93 → 1.21.94

package/tests/github_one_trip.mjs

@@ -0,0 +1,297 @@
+// tests/github_one_trip.mjs — "Connect GitHub in one trip: approving the app goes straight
+// to installing it on the repo, and the checklist ticks itself" (task 1004649).
+//
+// Four layers, DB-free and network-free:
+//   1. modules/provisioning/github-setup.js — each checklist step's state from server facts,
+//      the honest "not yet" states included; the install link; the verify window (PURE).
+//   2. scripts/gds/provision-github-setup.js — the runner's check, asked of GitHub with the
+//      app's OWN key: the creds read back out of a REAL webEnvBody, a JWT that verifies,
+//      installed / not installed / cannot tell, device flow on / off / cannot tell, and the
+//      tick recording only what GitHub confirmed — never a secret in a log line.
+//   3. the REAL projection (githubSetupRead) run into the REAL page renderers (projects.html,
+//      the vm-slice idiom): each server state draws the step the founder should see.
+//   4. the device-flow finding is written down where the next builder will look.
+//
+// Run:  node --test tests/github_one_trip.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import crypto from 'node:crypto';
+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 GS = require(path.join(ROOT, 'modules', 'provisioning', 'github-setup.js'));
+const RUN = require(path.join(ROOT, 'scripts', 'gds', 'provision-github-setup.js'));
+const UNITS = require(path.join(ROOT, 'scripts', 'gds', 'provision-units.js'));
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+
+// ── 1. the checklist from server facts ──────────────────────────────────────
+
+test('each step reads only what the server has seen — the honest "not yet" states included', () => {
+  const none = GS.githubChecklist(null, null);
+  assert.deepEqual(none, { approve: 'todo', install: 'todo', sign_in: 'todo', device_flow: 'todo', connected: false }, 'never started');
+  assert.equal(GS.githubChecklist('pending', null).approve, 'now', 'waiting for the approval on GitHub');
+  for (const s of ['code_received', 'converting']) {
+    const c = GS.githubChecklist(s, null);
+    assert.equal(c.approve, 'now', `${s}: approved, but no keys placed yet — not ticked`);
+    assert.equal(c.install, 'todo', `${s}: nothing to install before the app is named`);
+  }
+  const placed = GS.githubChecklist('converting', 'mercury-app');
+  assert.deepEqual([placed.approve, placed.install, placed.sign_in, placed.device_flow], ['done', 'now', 'now', 'todo'], 'keys placed: approve ticks, install and sign-in are under way');
+  const signedIn = GS.githubChecklist('done', 'mercury-app');
+  assert.deepEqual([signedIn.install, signedIn.sign_in, signedIn.device_flow, signedIn.connected], ['now', 'done', 'later', false],
+    'sign-in verified is NOT connected: the install has not been confirmed by GitHub');
+  const installed = GS.githubChecklist('done', 'mercury-app', { installedAt: '2026-10-08T10:00:00Z' });
+  assert.equal(installed.connected, true, 'approve + install + sign-in = connected');
+  assert.equal(installed.device_flow, 'later', 'device flow stays optional and never holds "connected" back');
+  assert.equal(GS.githubChecklist('done', 'mercury-app', { installedAt: 'x', deviceFlowAt: 'y' }).device_flow, 'done');
+  // a REPORTED install (the setup_url redirect, spoofable) ticks nothing
+  assert.equal(GS.githubChecklist('done', 'mercury-app', { installReportedAt: '2026-10-08T10:00:00Z' }).install, 'now');
+  // failures: where it stopped
+  assert.equal(GS.githubChecklist('error', null).approve, 'stopped');
+  assert.equal(GS.githubChecklist('expired', null).approve, 'stopped');
+  const signInFailed = GS.githubChecklist('error', 'mercury-app');
+  assert.deepEqual([signInFailed.approve, signInFailed.sign_in], ['done', 'stopped'], 'an app exists; sign-in is where it stopped');
+});
+
+test('the install link names the app and carries the attempt; the repo is strict', () => {
+  assert.equal(GS.installUrlFor({ appSlug: null, state: 'abc' }), null);
+  assert.equal(GS.installUrlFor({ appSlug: 'mercury-app', state: 'ab cd' }), 'https://github.com/apps/mercury-app/installations/new?state=ab%20cd');
+  assert.equal(GS.installUrlFor({ appSlug: 'mercury-app' }), 'https://github.com/apps/mercury-app/installations/new');
+  assert.equal(GS.targetRepo({ target_ref: 'acme/mercury' }), 'acme/mercury');
+  assert.equal(GS.targetRepo({ target_ref: 'acme/mercury.git' }), 'acme/mercury');
+  for (const bad of ['', 'acme', '../x/y', 'a/b/c', 'acme/mer cury', '-acme/x']) assert.equal(GS.targetRepo({ target_ref: bad }), null, bad);
+});
+
+test('the runner checks for a bounded window after the attempt settles, re-opened by an install report', () => {
+  const now = Date.parse('2026-10-08T12:00:00Z');
+  assert.equal(GS.stillVerifying({ resolved_at: '2026-10-08T11:00:00Z' }, {}, now), true);
+  assert.equal(GS.stillVerifying({ resolved_at: '2026-10-08T09:00:00Z' }, {}, now), false);
+  assert.equal(GS.stillVerifying({ resolved_at: '2026-10-08T09:00:00Z' }, { installReportedAt: '2026-10-08T11:30:00Z' }, now), true);
+  assert.equal(GS.stillVerifying(null, {}, now), false);
+});
+
+test('githubSetupRead: one events read since the attempt began; the owner read leaves the state off', async () => {
+  const seen = [];
+  const db = { query: async (sql, params) => { seen.push({ sql, params }); return { rows: [{ event: GS.SETUP_EVENTS.installed, at: '2026-10-08T10:00:00Z' }] }; } };
+  const row = { instance_id: 42, state: 'S1', created_at: '2026-10-08T09:00:00Z', app_slug: 'mercury-app', status: 'done' };
+  const pub = await GS.githubSetupRead(db, { target_ref: 'acme/mercury' }, row, 'done', { now: Date.parse('2026-10-08T10:30:00Z') });
+  assert.equal(seen.length, 1);
+  assert.match(seen[0].sql, /FROM provisioning_events/);
+  assert.deepEqual(seen[0].params, [42, Object.values(GS.SETUP_EVENTS), '2026-10-08T09:00:00Z']);
+  assert.equal(pub.checklist.install, 'done');
+  assert.equal(pub.install_url, null, 'no install link once it is verified');
+  const notYet = await GS.githubSetupRead({ query: async () => ({ rows: [] }) }, {}, row, 'done', { withState: false });
+  assert.equal(notYet.install_url, 'https://github.com/apps/mercury-app/installations/new', 'the owner read never carries the state token');
+  const broken = await GS.githubSetupRead({ query: async () => { throw new Error('db down'); } }, {}, row, 'done');
+  assert.equal(broken.checklist.install, 'now', 'a failed read is "nothing verified yet", never a 500');
+});
+
+// ── 2. the runner's check ───────────────────────────────────────────────────
+
+const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });
+const PEM = privateKey.export({ type: 'pkcs1', format: 'pem' });
+const INST = { id: 42, slug: 'mercury', port: 4100, domain: 'mercury.example.com', target_ref: 'acme/mercury', hosting_shape: 'co-tenant' };
+const ENV = UNITS.webEnvBody(INST, { clientId: 'Iv23liABCDEF123456', clientSecret: 's'.repeat(40), appId: 5189633, appPem: PEM });
+
+test('the app creds come back out of the web.env the runner itself writes', () => {
+  const c = RUN.appCredsFromEnv(ENV);
+  assert.equal(c.appId, '5189633');
+  assert.equal(c.clientId, 'Iv23liABCDEF123456');
+  assert.equal(c.pem.trim(), PEM.trim(), 'the one-line pem is restored to real newlines');
+  assert.deepEqual(RUN.appCredsFromEnv(''), { appId: null, pem: null, clientId: null });
+});
+
+test('the app JWT is RS256, signed by the app key, issued by the app id, under ten minutes', () => {
+  const jwt = RUN.appJwt({ appId: 5189633, pem: PEM, nowSec: 1_800_000_000 });
+  const [h, b, s] = jwt.split('.');
+  const ok = crypto.createVerify('RSA-SHA256').update(`${h}.${b}`).verify(publicKey, Buffer.from(s, 'base64url'));
+  assert.equal(ok, true);
+  const body = JSON.parse(Buffer.from(b, 'base64url').toString());
+  assert.equal(body.iss, '5189633');
+  assert.ok(body.exp - body.iat <= 600);
+});
+
+test('installed / not installed / cannot tell — only a 200 with an id is "installed"', async () => {
+  const calls = [];
+  const answer = (status, body) => async (url, opts) => { calls.push({ url, opts }); return { status, ok: status >= 200 && status < 300, json: async () => body }; };
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: answer(200, { id: 99 }) }), true);
+  assert.equal(calls[0].url, 'https://api.github.com/repos/acme/mercury/installation');
+  assert.match(calls[0].opts.headers.Authorization, /^Bearer [\w-]+\.[\w-]+\.[\w-]+$/, 'asked as the app');
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: answer(404, {}) }), false);
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: answer(500, {}) }), null);
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: async () => { throw new Error('offline'); } }), null);
+});
+
+test('device flow on / off / cannot tell — read from GitHub\'s own answer to a device sign-in start', async () => {
+  const with_ = (body) => async () => ({ status: 200, ok: true, json: async () => body });
+  assert.equal(await RUN.deviceFlowOn({ clientId: 'Iv1', fetchImpl: with_({ device_code: 'dc', user_code: 'AB-CD' }) }), true);
+  assert.equal(await RUN.deviceFlowOn({ clientId: 'Iv1', fetchImpl: with_({ error: 'device_flow_disabled' }) }), false);
+  assert.equal(await RUN.deviceFlowOn({ clientId: 'Iv1', fetchImpl: with_({ error: 'slow_down' }) }), null, 'any other answer is never read as off');
+});
+
+// A fake db that answers the runner's two reads: the attempts in the window, and the facts.
+function fakeDb({ attempts, facts = [] }) {
+  return { query: async (sql) => (/WITH latest AS/.test(sql) ? { rows: attempts } : /FROM provisioning_events/.test(sql) ? { rows: facts } : { rows: [] }) };
+}
+const ATTEMPT = { id: 18, instance_id: 42, created_at: '2026-10-08T09:00:00Z', requested_by: 7, slug: 'mercury', target_ref: 'acme/mercury', hosting_shape: 'co-tenant', instance_status: 'active' };
+
+test('the runner records what GitHub confirmed — and only that — reading the creds on the box', async () => {
+  const events = [], logs = [], cmds = [];
+  const fetchImpl = async (url) => (/\/installation$/.test(url)
+    ? { status: 200, ok: true, json: async () => ({ id: 31337 }) }
+    : { status: 200, ok: true, json: async () => ({ error: 'device_flow_disabled' }) });
+  const out = await RUN.verifyGithubAppSetups({
+    apply: true, privileged: true, log: (m) => logs.push(m), fetchImpl,
+    db: fakeDb({ attempts: [ATTEMPT] }),
+    exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: ENV }; },
+    provisioning: { recordEvent: async (_db, e) => { events.push(e); } },
+  });
+  assert.deepEqual(out, { checked: 1, installed: 1, deviceFlow: 0 });
+  assert.deepEqual(cmds, ['sudo cat /etc/mercury/web.env'], 'the creds are read where the runner placed them');
+  assert.deepEqual(events.map((e) => e.event), ['github-app-installed'], 'device flow off records nothing');
+  assert.match(events[0].detail, /acme\/mercury/);
+  const said = logs.join('\n') + JSON.stringify(events);
+  assert.doesNotMatch(said, /BEGIN RSA|s{40}|Iv23liABCDEF123456/, 'no key, secret or client id ever reaches a log or an event');
+});
+
+test('an attempt already fully verified is skipped; dry-run asks GitHub nothing', async () => {
+  let asked = 0;
+  const deps = {
+    apply: true, log: () => {}, fetchImpl: async () => { asked++; return { status: 200, ok: true, json: async () => ({}) }; },
+    db: fakeDb({ attempts: [ATTEMPT], facts: [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }, { event: 'github-app-device-flow', at: '2026-10-08T10:00:00Z' }] }),
+    exec: () => { throw new Error('must not read the box'); }, provisioning: { recordEvent: async () => { throw new Error('nothing to record'); } },
+  };
+  assert.deepEqual(await RUN.verifyGithubAppSetups(deps), { checked: 0, installed: 0, deviceFlow: 0 });
+  const lines = [];
+  await RUN.verifyGithubAppSetups({ ...deps, apply: false, log: (m) => lines.push(m), db: fakeDb({ attempts: [ATTEMPT] }) });
+  assert.equal(asked, 0);
+  assert.match(lines.join('\n'), /would check the GitHub install \+ device flow for mercury/);
+});
+
+test('the window query takes each project\'s LATEST attempt, past placement, still settling or newly reported', async () => {
+  let sql = '', params = null;
+  await RUN.attemptsToVerify({ query: async (q, p) => { sql = q; params = p; return { rows: [] }; } });
+  assert.match(sql, /DISTINCT ON \(instance_id\)[\s\S]*ORDER BY instance_id, created_at DESC/);
+  assert.match(sql, /l\.app_id IS NOT NULL AND l\.status IN \('done', 'error'\) AND i\.status = 'active'/);
+  assert.match(sql, /LIMIT 20/);
+  assert.deepEqual(params, [GS.VERIFY_WINDOW_MS / 1000, 'github-app-install-reported']);
+  assert.match(fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'provision.js'), 'utf8'), /require\('\.\/provision-github-setup\.js'\)\.verifyGithubAppSetups\(deps\)/, 'it runs on every runner tick, after the conversions');
+});
+
+// ── 3. the real projection into the real renderers ──────────────────────────
+
+const RS = SCRIPT.indexOf('    /* The four GitHub steps of part 03');
+const RE = SCRIPT.indexOf('    var STEP_RENDERERS = {', RS);
+const SS = SCRIPT.indexOf('    /* the checklist the server derived (task 1004649)');
+const SE = SCRIPT.indexOf('    function pollManifest(stateToken) {', SS);
+const PS = SCRIPT.indexOf('    function stepsPaint() {');
+const PE = SCRIPT.indexOf('    (function hopInput()', PS);
+
+test('the regions are findable (a rename must fail loudly)', () => {
+  assert.ok(RS > 0 && RE > RS && SS > 0 && SE > SS && PS > 0 && PE > PS);
+});
+
+function page({ manifest, appSlug = null }) {
+  const sandbox = {
+    live: { manifest, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug, setup: null, installUrl: null, instStatus: 'active', addrReady: true },
+    state: { name: 'Mer<cury', slug: 'mercury', owner: 'acme', repo: 'mercury', step: 2 },
+    manifestStale: false, autoOpenArmed: false,
+    resolvedDomain: () => 'mercury.example.com', apexBase: () => 'example.com',
+    esc: (x) => String(x).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
+    GH_ICON: '', manualOauthDetails: () => '', projectPageLink: (t) => t, autoOpenTick: () => '',
+    progressMarkup: (a, b, note) => `<prog>${note}</prog>`, encodeURIComponent, JSON, Array,
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(`${SCRIPT.slice(RS, RE)}\n${SCRIPT.slice(SS, SE)}\n${SCRIPT.slice(PS, PE)}`, sandbox);
+  return sandbox;
+}
+const ROWS = ['renderStepOauthApp', 'renderStepAppInstall', 'renderStepFirstSignIn', 'renderStepDeviceFlow'];
+function draw(sb) {
+  return ROWS.map((f) => vm.runInContext(`${f}()`, sb));
+}
+function cls(li) { return ((li.match(/^<li(?: class="([^"]*)")?/) || [])[1] || '').split(/\s+/).filter(Boolean); }
+
+async function serverSays(status, appSlug, eventRows) {
+  const db = { query: async () => ({ rows: eventRows }) };
+  const row = { instance_id: 42, state: 'S1', created_at: '2026-10-08T09:00:00Z', resolved_at: new Date().toISOString(), app_slug: appSlug };
+  return GS.githubSetupRead(db, { target_ref: 'acme/mercury' }, row, status);
+}
+
+test('the mockup\'s four steps, in its words and order, the typed name escaped', () => {
+  const sb = page({ manifest: null });
+  const rows = draw(sb);
+  const titles = rows.map((li) => (li.match(/<b>([^<]*)<\/b>/) || [])[1]);
+  assert.deepEqual(titles, ['Approve the Mer&lt;cury app on GitHub', 'Install it on your repo', 'Builders can sign in', 'Command-line sign-in is on']);
+  assert.match(rows[0], /data-action="manifest-start"[^>]*>Connect GitHub ↗/, 'one click starts the one trip');
+  assert.equal(SCRIPT.match(/var STEP_ORDER = \[([^\]]*)\]/)[1], "'github-repo', 'oauth-app', 'app-install', 'first-sign-in', 'device-flow', 'enter-hall'", 'drawn in the mockup\'s order');
+});
+
+test('each server state draws the step the founder should see — from the REAL projection', async () => {
+  // keys placed, nothing verified on GitHub yet
+  let sb = page({ manifest: 'converting', appSlug: 'mercury-app' });
+  let d = await serverSays('converting', 'mercury-app', []);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  let rows = draw(sb);
+  assert.deepEqual(rows.map(cls), [['sdone'], [], ['slocked'], ['slocked', 'soptional']]);
+  assert.match(rows[1], /href="https:\/\/github\.com\/apps\/mercury-app\/installations\/new\?state=S1"/, 'the way back to the install, with the attempt');
+  assert.equal(vm.runInContext('stepsPaint.toString().length > 0', sb), true);
+
+  // sign-in verified, install still unconfirmed: NOT connected
+  sb = page({ manifest: 'done', appSlug: 'mercury-app' });
+  d = await serverSays('done', 'mercury-app', []);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  rows = draw(sb);
+  assert.deepEqual(rows.map(cls), [['sdone'], [], ['sdone'], ['soptional']]);
+  assert.match(rows[3], /Optional — turn it on later\./);
+  assert.equal(vm.runInContext('setupOpen()', sb), true, 'the page keeps watching for the install');
+
+  // GitHub confirmed the install to the runner: connected, device flow still optional
+  sb = page({ manifest: 'done', appSlug: 'mercury-app' });
+  d = await serverSays('done', 'mercury-app', [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }]);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  rows = draw(sb);
+  assert.deepEqual(rows.map(cls), [['sdone'], ['sdone'], ['sdone'], ['soptional']]);
+  assert.match(rows[1], /The app is on acme\/mercury/);
+  assert.equal(vm.runInContext('setupOpen()', sb), false);
+  // the part's state line, from these very rows: the optional step does not hold it back
+  const items = rows.map((li) => ({ classList: { contains: (c) => cls(li).includes(c) } }));
+  const ghState = { textContent: '' };
+  sb.$ = (id) => (id === 'humanSteps' ? { children: items } : id === 'ghState' ? ghState : null);
+  sb.manifestInFlight = () => false;
+  vm.runInContext('stepsPaint()', sb);
+  assert.equal(ghState.textContent, 'connected ✓');
+
+  // and once GitHub has device flow on, the fourth ticks too
+  sb = page({ manifest: 'done', appSlug: 'mercury-app' });
+  d = await serverSays('done', 'mercury-app', [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }, { event: 'github-app-device-flow', at: '2026-10-08T10:05:00Z' }]);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  assert.deepEqual(cls(draw(sb)[3]), ['sdone', 'soptional']);
+});
+
+test('seedSetup is change-only, and an install link must be GitHub\'s', () => {
+  const sb = page({ manifest: 'done', appSlug: 'a' });
+  const c = JSON.stringify(GS.githubChecklist('done', 'a'));
+  assert.equal(vm.runInContext(`seedSetup(${c}, 'https://github.com/apps/a/installations/new?state=S')`, sb), true);
+  assert.equal(vm.runInContext(`seedSetup(${c}, 'https://github.com/apps/a/installations/new?state=S')`, sb), false, 'nothing moved, nothing redrawn');
+  assert.equal(vm.runInContext(`seedSetup(${c}, 'https://github.com/apps/a/installations/new')`, sb), false, 'a stateless link never replaces the one carrying the attempt');
+  assert.equal(vm.runInContext('live.installUrl', sb), 'https://github.com/apps/a/installations/new?state=S');
+  const sb2 = page({ manifest: 'done', appSlug: 'a' });
+  vm.runInContext(`seedSetup(${c}, 'javascript:alert(1)')`, sb2);
+  assert.equal(vm.runInContext('live.installUrl', sb2), null);
+  assert.equal(vm.runInContext('seedSetup(null, null)', sb2), false);
+});
+
+// ── 4. the finding is written down ──────────────────────────────────────────
+
+test('the device-flow finding lives in the direction doc, and the code points at it', () => {
+  const doc = fs.readFileSync(path.join(ROOT, 'docs', 'design', 'project-startup-direction.md'), 'utf8');
+  assert.match(doc, /Device flow cannot be switched on for the founder \(spike, task 1004649\)/);
+  assert.match(fs.readFileSync(path.join(ROOT, 'modules', 'provisioning', 'github-setup.js'), 'utf8'), /docs\/design\/project-startup-direction\.md/);
+});

package/tests/projects_hub_dns_ready.mjs

@@ -165,7 +165,8 @@ test('every door to the address on the page asks addressReady', () => {
   const SCRIPT = HUB;
   assert.match(SCRIPT, /inst\.status === 'active' && addressReady\(inst\)\) acts\.push\('<a class="btn small ghost" href="https:\/\/' \+ esc\(inst\.domain\) \+ '" target="_blank" rel="noopener">View<\/a>'\)/, 'the row\'s View');
   assert.match(SCRIPT, /inst\.status === 'active' && addressReady\(inst\)\) acts\.push\('<a class="btn small ghost" href="https:\/\/' \+ esc\(inst\.domain\) \+ '" target="_blank" rel="noopener">Open site →<\/a>'\)/, 'the manage page\'s Open site');
-  assert.match(SCRIPT, /live\.instStatus !== 'active' \|\| !live\.addrReady \|\| live\.manifest !== 'done'/, 'first sign-in and the hall step stay locked');
+  // task 1004649: "Builders can sign in" opens its door only on a resolving address
+  assert.match(SCRIPT, /var open = live\.instStatus === 'active' && live\.addrReady;\n\s*return '<li class="sdone" data-onboard-step="first-sign-in">/, 'the sign-in step\'s door waits for the address');
   assert.match(SCRIPT, /live\.addrReady = addressReady\(inst\); renderSteps\(\);/, 'and unlock on the tick the lookup answers');
   assert.equal((SCRIPT.match(/inst\.status !== 'active' \|\| !addressReady\(inst\)\) \{ (vis|join)Runs\(''\); return; \}/g) || []).length, 2,
     'the browser\'s own manifest reads wait for the name too');

package/tests/projects_hub_pre_uat.mjs

@@ -185,14 +185,18 @@ test('the 33-minute hand-off keeps a snag honest and keeps its flow', () => {
   assert.match(SCRIPT, /progressMarkup\(1, 1, m\.slice\(5\), 'isErr', watchFlow\)/, 'the session-expiry message keeps its flow too');
 });
 
-test('First sign-in and Enter your builders hall unlock only when the project answers AND sign-in is wired', () => {
+test('"Builders can sign in" ticks on verified sign-in, and its door opens only when the project answers (task 1004649)', () => {
+  // the one-page checklist (task 1004649): the step's tick is the server's 'done';
+  // the door to the project still waits for a resolving address (task 1004505)
   const first = fn('renderStepFirstSignIn');
+  assert.match(first, /<b>Builders can sign in<\/b>/);
+  assert.match(first, /if \(live\.manifest !== 'done'\) \{\n\s*return '<li class="slocked"/, 'locked until the platform has seen sign-in work');
+  assert.match(first, /var open = live\.instStatus === 'active' && live\.addrReady;/, 'the door gates on status and a resolving address');
+  assert.match(first, /\(open \? '<a class="ghbtn" href="https:\/\/' \+ esc\(domain\)/, 'and only then links the address');
+  // the hall is the "is alive" block's way in; the step survives only for the local hall
   const hall = fn('renderStepEnterHall');
-  for (const [name, body] of [['first-sign-in', first], ['enter-hall', hall]]) {
-    assert.match(body, /live\.instStatus !== 'active' \|\| !live\.addrReady \|\| live\.manifest !== 'done'/, `${name} gates on status, a resolving address (task 1004505) and sign-in`);
-    assert.match(body, /class="slocked"/, `${name} has a locked rendering`);
-  }
-  assert.match(first, /Unlocks once your project is answering and sign-in above is wired/);
+  assert.match(hall, /if \(domain\) return '';/);
+  assert.match(hall, /bongos dev/);
 });
 
 test('the domainless build is standing, not "Live"', () => {
@@ -208,7 +212,7 @@ test('the fallback checklist carries every human step the canonical plan has', (
 test('the manifest step acknowledges code_received, offers a restart after a stall, and rides the CREATED record', () => {
   // 'converting' is the same stage — it used to fall through to "waiting for approval" (task 1004572)
   assert.match(SCRIPT, /if \(live\.manifest === 'code_received' \|\| live\.manifest === 'converting'\)/, 'GitHub’s half is acknowledged');
-  assert.match(SCRIPT, /GitHub’s part is done/);
+  assert.match(SCRIPT, /Approved on GitHub\. The platform is placing the app’s keys on your project/);
   assert.match(SCRIPT, /manifestStale \? '<button type="button" class="linklike" data-action="manifest-start">/, 'a stalled wait gets a restart door');
   assert.match(SCRIPT, /\(Date\.now\(\) - manifestStartedAt\) > 90000/, 'after ~90 seconds');
   assert.match(SCRIPT, /function rememberManifest\(stateToken, status, appSlug\)/);
@@ -610,10 +614,14 @@ test('teardown copy is state-aware: a queued project is told nothing was built',
 
 test('founder voice on the Device Flow step and the manual OAuth fallback', () => {
   const df = fn('renderStepDeviceFlow');
-  assert.equal((df.match(/<b>Let builders sign in from a command line — one checkbox<\/b>/g) || []).length, 2, 'both branches carry the outcome-first title');
+  // the mockup's words (task 1004649): one title, in every branch
+  assert.match(df, /var title = '<b>Command-line sign-in is on<\/b>';/, 'the outcome-first title');
   assert.doesNotMatch(df, /<b>Enable Device Flow — one checkbox<\/b>/);
   assert.match(df, /the <code style="font-family:var\(--font-mono\)">bongos setup<\/code> command builders run on their own machine/, 'the command is glossed, not bare-coded');
-  assert.doesNotMatch(df, /Optional/, 'not optional — a manifest-born App has Device Flow off');
+  // GitHub has no manifest field and no API for device flow (task 1004649's spike), so the
+  // step is OPTIONAL by design and never holds the project back
+  assert.equal((df.match(/Optional — turn it on later\./g) || []).length, 2, 'the not-yet branches say it is optional');
+  assert.equal((df.match(/class="[^"]*soptional/g) || []).length, 3, 'every branch is marked optional, so "connected" never waits on it');
   assert.equal((df.match(/<strong>Enable Device Flow<\/strong>/g) || []).length, 2, 'GitHub’s own checkbox label stays verbatim in the instructions');
   const manual = fn('manualOauthDetails');
   assert.match(manual, /The platform team places the generated credentials; this step ticks itself once they land\.<\/p><\/details>/);

package/tests/provision.mjs

@@ -1740,13 +1740,54 @@ await ta('drainOAuthManifests (--apply): claims a code_received row, places cred
   };
   const r = await P.drainOAuthManifests(deps);
   assert.deepEqual(r, { converted: 1, errors: 0 });
-  assert.equal(resolved.length, 1);
-  assert.equal(resolved[0].status, 'done');
-  assert.equal(resolved[0].patch.app_slug, 'app-3');
-  assert.equal(resolved[0].patch.github_code, null, 'a done row holds no re-convertible code (F23)');
+  // task 1004649: the slug lands the moment the creds are placed (still 'converting'),
+  // so the callback page can send the founder on to the install before sign-in is checked
+  assert.deepEqual(resolved.map((x) => x.status), ['converting', 'done']);
+  assert.deepEqual(resolved[0].patch, { app_id: 3, app_slug: 'app-3' });
+  assert.equal(resolved[1].patch.app_slug, 'app-3');
+  assert.equal(resolved[1].patch.github_code, null, 'a done row holds no re-convertible code (F23)');
   assert.ok(events.includes('oauth-manifest-done'));
 });
 
+await ta('the sign-in check reads the JSON health answer, never the root /healthz "ok" (task 1004577)', async () => {
+  // The REAL answers of the two endpoints (src/bongos/serve-internal.js answers GET /healthz
+  // with a plain "ok"; src/bongos/routes/healthz.js answers /api/bongos/healthz with JSON).
+  // The old probe hit /healthz, never parsed, and recorded every working setup as FAILED.
+  const real = (cmd) => (/\/api\/bongos\/healthz/.test(cmd) ? '{"ok":true,"auth_configured":true}'
+    : /\/healthz/.test(cmd) ? 'ok' : '');
+  const inst = { ...coTenant, domain: 'mercury.example.com' };
+  const probes = [];
+  const deps = {
+    apply: true, privileged: false, log: () => {}, sleep: async () => {},
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 7, appSlug: 'mercury-app' }),
+    exec: (cmd) => { if (/healthz/.test(cmd)) probes.push(cmd); return { ok: true, stdout: real(cmd) }; },
+    writeFile: () => ({ ok: true }),
+  };
+  const r = await P.placeManifestCreds(inst, { github_code: 'C', attempts: 1 }, deps);
+  assert.equal(r.ok, true, 'a project whose JSON health says auth_configured is verified');
+  assert.ok(probes.length >= 1 && probes.every((c) => /\/api\/bongos\/healthz/.test(c)), 'only the JSON endpoint is asked');
+  assert.equal(P.authHealthzCmd({ port: 4100 }), 'curl -sS --max-time 5 http://127.0.0.1:4100/api/bongos/healthz');
+  // and a plain "ok" is no verdict either way: it never reads as configured
+  const plain = await P.placeManifestCreds(inst, { github_code: 'C', attempts: 1 }, { ...deps, exec: () => ({ ok: true, stdout: 'ok' }) });
+  assert.equal(plain.ok, false, 'a bare "ok" never confirms sign-in');
+  const oauthSecret = require('../scripts/gds/oauth-secret.js');
+  assert.deepEqual(oauthSecret.parseHealthzAuth('ok'), { ok: false, authConfigured: false, parseError: true });
+  assert.match(readFileSync(new URL('../scripts/gds/oauth-secret.js', import.meta.url), 'utf8'), /127\.0\.0\.1:\$\{port\}\/api\/bongos\/healthz/, 'the manual placement probes the same JSON answer');
+});
+
+await ta('the slug is recorded only AFTER the credentials are placed (task 1004649)', async () => {
+  const order = [];
+  const inst = { ...coTenant, domain: 'mercury.example.com' };
+  await P.placeManifestCreds(inst, { github_code: 'C', attempts: 1 }, {
+    apply: true, privileged: false, log: () => {}, sleep: async () => {},
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 7, appSlug: 'mercury-app' }),
+    exec: (cmd) => { if (/systemctl restart/.test(cmd)) order.push('restart'); return { ok: true, stdout: '{"auth_configured":true}' }; },
+    writeFile: (p) => { if (/web\.env$/.test(p)) order.push('write'); return { ok: true }; },
+    onCredsPlaced: async (c) => { order.push(`slug:${c.appSlug}`); },
+  });
+  assert.deepEqual(order, ['write', 'restart', 'slug:mercury-app'], 'the first tick means the keys are on the project');
+});
+
 await ta('a SPENT code is never re-converted — terminal error, no code_received reset (F23)', async () => {
   // A stateful one-row store: claimNext honors status, resolve writes it back —
   // exactly the reset loop that used to re-convert a burned code on the next tick.
@@ -1804,11 +1845,12 @@ await ta('a sign-in check that never confirms still records WHICH App GitHub mad
       recordEvent: async () => {},
     },
   });
-  assert.equal(resolves.length, 1);
-  assert.equal(resolves[0].status, 'error');
-  assert.equal(resolves[0].patch.app_slug, 'mercury-cloudbongos-com', 'the error row names the App');
-  assert.equal(resolves[0].patch.app_id, 5189633);
-  assert.equal(resolves[0].patch.github_code, null, 'the burned code is still scrubbed');
+  // the slug is recorded at placement (task 1004649), then the row settles as an error
+  assert.deepEqual(resolves.map((x) => x.status), ['converting', 'error']);
+  const settled = resolves[1];
+  assert.equal(settled.patch.app_slug, 'mercury-cloudbongos-com', 'the error row names the App');
+  assert.equal(settled.patch.app_id, 5189633);
+  assert.equal(settled.patch.github_code, null, 'the burned code is still scrubbed');
 });
 
 await ta('a failure BEFORE GitHub handed over credentials claims no App (task 1004572)', async () => {

package/tests/provisioning_github_app_routes.mjs

@@ -39,8 +39,18 @@ branding.branding = () => ({ ...realBranding(), identity: { ...(realBranding().i
 const api = require(`${ROOT}/src/module-api.js`);
 api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
 
+// The verified-facts read (task 1004649) is the one DB query the github-setup routes make;
+// stub it on the cached module like the data-access fns above.
+const githubSetup = require(`${ROOT}/modules/provisioning/github-setup.js`);
+let facts = {};
+const reported = [];
+githubSetup.githubSetupFacts = async () => facts;
+const prevRecord = provisioning.recordEvent;
+provisioning.recordEvent = async (_db, e) => { reported.push(e); return prevRecord(); };
+
 const express = require('express');
 const provisioningRoutes = require(`${ROOT}/modules/provisioning/routes/provisioning.js`);
+const githubSetupRoutes = require(`${ROOT}/modules/provisioning/routes/github-setup.js`);
 const app = express();
 app.use(express.json());
 // res.fail is mounted globally by the core error middleware in production; add a minimal
@@ -53,6 +63,7 @@ app.use((_req, res, next) => {
   next();
 });
 app.use('/api/bongos', provisioningRoutes());
+app.use('/api/bongos', githubSetupRoutes());
 
 const server = app.listen(0);
 await new Promise((r) => server.once('listening', r));
@@ -70,6 +81,7 @@ console.log('POST /provisioning/instances/:id/github-app (mint the one-click lin
   t('manifest.redirect_url is the MOTHERSHIP callback', j.manifest && j.manifest.redirect_url === 'https://cloudbongos.com/api/bongos/provisioning/github-app/callback', j.manifest && j.manifest.redirect_url);
   t('manifest.callback_urls are the INSTANCE sign-in (both prefixes)', j.manifest && j.manifest.callback_urls[0] === 'https://mercury.example.com/api/gds/auth/web/callback' && j.manifest.callback_urls[1] === 'https://mercury.example.com/api/bongos/auth/web/callback');
   t('manifest.name is the instance domain (unique + matches the consent-screen redirect) within 34 chars', j.manifest && j.manifest.name === 'mercury.example.com' && j.manifest.name.length <= 34, j.manifest && j.manifest.name);
+  t('manifest.setup_url sends an install back to the MOTHERSHIP setup route (task 1004649)', j.manifest && j.manifest.setup_url === 'https://cloudbongos.com/api/bongos/provisioning/github-app/setup' && j.manifest.setup_on_update === true, j.manifest && j.manifest.setup_url);
   t('org_url derived from the target_ref owner (acme)', j.org_url === `https://github.com/organizations/acme/settings/apps/new?state=${j.state}`, j.org_url);
   t('the attempt row was persisted with the minted state', !!(stored && stored.instanceId === 42 && stored.state === j.state && stored.requestedBy === 7));
 }
@@ -93,15 +105,83 @@ console.log('\nGET /provisioning/github-app/callback (the public GitHub redirect
 {
   const res = await fetch(`${base}/provisioning/github-app/callback?code=GHCODE123&state=GOODSTATE`);
   const html = await res.text();
-  t('good state → 200 text/html hand-back page', res.status === 200 && /text\/html/.test(res.headers.get('content-type') || '') && /GitHub app created/.test(html) && /__CB_SETUP__/.test(html) && html.includes('GOODSTATE'), `status=${res.status}`);
-  t('the page names the instance host', /mercury\.example\.com/.test(html));
-  // task 1004548: the founder no longer waits here — the page hands them back to the
-  // checklist, which shows the wait. A manual way back is always on the page.
-  t('carries a plain "back to my checklist" link (works without script)', /<a class="btn" id="back" href="\/projects\?view=new">Back to my checklist/.test(html));
+  t('good state → 200 text/html one-trip page', res.status === 200 && /text\/html/.test(res.headers.get('content-type') || '') && /GitHub app created/.test(html) && /__CB_SETUP__/.test(html) && html.includes('GOODSTATE'), `status=${res.status}`);
+  // task 1004649: GitHub's half of the approval is done — the SAME tab goes on to the install
+  t('says the next step is installing it on the repo', /Next, install it on your repo/.test(html));
+  t('carries a plain way back to the project (works without script)', /<a class="btn" id="back" href="\/projects\?view=new">Back to my project/.test(html));
   t('no progress stepper or countdown left on the page', !/id="steps"/.test(html) && !/Placing credentials/.test(html) && !/location\.href=target/.test(html));
 
-  // Run the served script itself (not a copy) against a minimal DOM, once as the
-  // wizard's pop-up and once as a same-tab return, and watch what it does.
+  // Run the served INSTALL script (not a copy): it polls the real status shape and goes on.
+  const installScript = (html.match(/<script>\s*(\(function\(\)\{[\s\S]*?)<\/script>\s*<\/body>/) || [])[1];
+  t('the one-trip page ships its client script', typeof installScript === 'string' && /installations|install_url/.test(installScript));
+  async function runInstall(statuses, repoAnswer) {
+    const vm = await import('node:vm');
+    const back = { href: '/projects?view=new' }, note = { textContent: '' };
+    const timers = [], fetched = [];
+    const calls = { replaced: null };
+    const sandbox = {
+      __CB_SETUP__: { state: 'GOODSTATE', domain: 'mercury.example.com', back: '/projects?view=new' },
+      document: { getElementById: (id) => (id === 'back' ? back : id === 'note' ? note : null) },
+      location: { replace: (u) => { calls.replaced = u; } },
+      setTimeout: (fn) => { timers.push(fn); return timers.length; },
+      encodeURIComponent, String,
+      fetch: async (url) => {
+        fetched.push(url);
+        if (/api\.github\.com\/repos\//.test(url)) return repoAnswer ? { ok: true, json: async () => repoAnswer } : { ok: false, json: async () => ({}) };
+        const body = statuses.length > 1 ? statuses.shift() : statuses[0];
+        return { ok: true, json: async () => body };
+      },
+    };
+    sandbox.window = sandbox;
+    vm.runInNewContext(installScript, sandbox);
+    for (let i = 0; i < 20 && !calls.replaced; i++) {
+      await new Promise((r) => setImmediate(r));
+      if (!calls.replaced && timers.length) timers.shift()();
+    }
+    return { ...calls, fetched, note: note.textContent };
+  }
+  // the REAL status route's answer for this attempt, before and after the runner named the app
+  const statusOf = async () => (await fetch(`${base}/provisioning/github-app/status?state=GOODSTATE`)).json();
+  const prevGet = provisioning.getOAuthManifestByState;
+  provisioning.getOAuthManifestByState = async () => ({ id: 99, instance_id: 42, state: 'GOODSTATE', status: 'converting', attempts: 1, expires_at: new Date(Date.now() + 600000).toISOString() });
+  const waiting = await statusOf();
+  provisioning.getOAuthManifestByState = async () => ({ id: 99, instance_id: 42, state: 'GOODSTATE', status: 'converting', attempts: 1, app_id: 5, app_slug: 'mercury-app', expires_at: new Date(Date.now() + 600000).toISOString() });
+  const named = await statusOf();
+  provisioning.getOAuthManifestByState = prevGet;
+  t('the real status: no install link until the app is named, then the one-trip link with the state', waiting.install_url === null && named.install_url === 'https://github.com/apps/mercury-app/installations/new?state=GOODSTATE' && named.repo === 'acme/mercury', JSON.stringify({ waiting: waiting.install_url, named: named.install_url }));
+  const narrowed = await runInstall([waiting, named], { id: 777, owner: { id: 42424 } });
+  t('waits for the app, then sends the founder to install it on THEIR repo, preselected', narrowed.replaced === 'https://github.com/apps/mercury-app/installations/new/permissions?state=GOODSTATE&suggested_target_id=42424&repository_ids[]=777', JSON.stringify(narrowed));
+  const plain = await runInstall([named], null);
+  t('a repo GitHub will not describe (private) falls back to the plain install page', plain.replaced === 'https://github.com/apps/mercury-app/installations/new?state=GOODSTATE', JSON.stringify(plain));
+  const doneAlready = await runInstall([{ ...named, checklist: { ...named.checklist, install: 'done' } }], null);
+  t('already installed → straight back to the checklist', doneAlready.replaced === '/projects?view=new#ghstate=GOODSTATE', JSON.stringify(doneAlready));
+  const stopped = await runInstall([{ ...named, status: 'error' }], null);
+  t('a stopped attempt → back to the checklist, which says what stopped', stopped.replaced === '/projects?view=new#ghstate=GOODSTATE', JSON.stringify(stopped));
+}
+
+console.log('\nGET /provisioning/github-app/setup (the App\'s setup_url — task 1004649):');
+{
+  reported.length = 0;
+  const prevGet = provisioning.getOAuthManifestByState;
+  provisioning.getOAuthManifestByState = async (_db, s) => (s === 'abcdef0123456789abcdef' ? { id: 99, instance_id: 42, requested_by: 7, state: s, status: 'done', app_slug: 'mercury-app' } : null);
+  const res = await fetch(`${base}/provisioning/github-app/setup?installation_id=123456&setup_action=install&state=abcdef0123456789abcdef`);
+  const html = await res.text();
+  t('a known state → 200 hand-back page to the checklist, carrying the attempt', res.status === 200 && /Installed on GitHub/.test(html) && html.includes('abcdef0123456789abcdef') && /Back to my checklist/.test(html), `status=${res.status}`);
+  t('records only that an install was REPORTED (the id is unverified), for the runner to check', reported.length === 1 && reported[0].event === 'github-app-install-reported' && /installation 123456, unverified/.test(reported[0].detail), JSON.stringify(reported));
+  reported.length = 0;
+  const forged = await fetch(`${base}/provisioning/github-app/setup?installation_id=1;rm%20-rf&state=abcdef0123456789abcdef`);
+  t('a non-numeric installation id never reaches the record', forged.status === 200 && reported.length === 1 && !/rm/.test(reported[0].detail), JSON.stringify(reported));
+  reported.length = 0;
+  const unknown = await fetch(`${base}/provisioning/github-app/setup?installation_id=1&state=NOPE`);
+  const uh = await unknown.text();
+  t('an unknown or missing state → the same way back, nothing recorded, no oracle', unknown.status === 200 && /Back to my projects/.test(uh) && reported.length === 0, `status=${unknown.status}`);
+  provisioning.getOAuthManifestByState = prevGet;
+}
+{
+  // the plain hand-back page (now the setup_url's) still behaves as before (task 1004548)
+  const callbackPage = require(`${ROOT}/modules/provisioning/routes/callback-page.js`).callbackPage;
+  const html = callbackPage({ ok: true, title: 'Installed on GitHub', state: 'GOODSTATE', domain: 'mercury.example.com' });
+  t('carries a plain "back to my checklist" link (works without script)', /<a class="btn" id="back" href="\/projects\?view=new">Back to my checklist/.test(html));
   const script = (html.match(/<script>\s*(\(function\(\)\{[\s\S]*?)<\/script>\s*<\/body>/) || [])[1];
   t('the hand-back page ships the client script', typeof script === 'string' && script.length > 100);
   async function runCallback({ opener }) {
@@ -155,7 +235,13 @@ console.log('\nGET /provisioning/github-app/status (the page poll → auto-open
     : null);
   const res = await fetch(`${base}/provisioning/github-app/status?state=GOODSTATE`);
   const j = await res.json();
-  t("status 'done' → ready:true + terminal:true", res.status === 200 && j.ready === true && j.terminal === true, JSON.stringify(j));
+  // task 1004649: sign-in verified is not the end of the trip — the install still is ahead
+  t("status 'done', install not verified → ready:true, NOT terminal, the install still ahead", res.status === 200 && j.ready === true && j.terminal === false && j.checklist && j.checklist.sign_in === 'done' && j.checklist.install === 'todo', JSON.stringify(j));
+  facts = { installedAt: new Date().toISOString() };
+  provisioning.getOAuthManifestByState = async () => ({ id: 99, instance_id: 42, state: 'GOODSTATE', status: 'done', app_slug: 'mercury-app', resolved_at: new Date(Date.now() - 3 * 3600 * 1000).toISOString(), expires_at: new Date().toISOString() });
+  const j2 = await (await fetch(`${base}/provisioning/github-app/status?state=GOODSTATE`)).json();
+  t('installed + sign-in verified, the runner done checking → connected, terminal, no install link', j2.checklist.connected === true && j2.checklist.device_flow === 'later' && j2.terminal === true && j2.install_url === null, JSON.stringify(j2));
+  facts = {};
   provisioning.getOAuthManifestByState = prev;
 }
 {