@bongos/core 1.19.1032 → 1.19.1034

package/tests/core_upgrade_runner.mjs

@@ -31,7 +31,8 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 // An ESM named import, not R.parseSchemaPending: knip credits a CJS export only when a test imports it this way.
-import { parseSchemaPending } from '../scripts/gds/provision-core-upgrade.js';
+import { parseSchemaPending, repoNote, REPO_NOTES } from '../scripts/gds/provision-core-upgrade.js';
+import { parseRepoNote } from '../modules/provisioning/core-upgrade.js';
 
 const require = createRequire(import.meta.url);
 const R = require('../scripts/gds/provision-core-upgrade.js');
@@ -196,9 +197,9 @@ await t('and an ordinary slug still runs', async () => {
 });
 
 await t('the guard error carries a status and a sentence, so a route CAN answer with it', async () => {
-  // No route maps it today — reaching it means a route forgot its own check, which
-  // deserves a 500 and a stack. The fields exist so that stays a choice rather than a
-  // rewrite, and so the wording is settled once.
+  // Every route answers it through failFrom now (task 1004126): the owner reads this
+  // sentence as a 409, and the route still logs the stack. The wording is settled here,
+  // once; tests/provisioning_public_refusal.mjs pins that it arrives.
   const selfRow = { query: async () => ({ rows: [{ hosting_shape: 'control-plane' }] }) };
   await assert.rejects(() => G.assertIntentAllowed(selfRow, 1, 'teardown'), (err) => {
     assert.equal(err.code, 'control_plane_protected');
@@ -886,15 +887,26 @@ await t('a paragraph-long summary is bounded — it reaches a DOM', () => {
 // A box that really does hold a core checkout. `repos` maps a directory to what git
 // there answers: `core` (a real core checkout), `notCore` (a git repo of something else),
 // `shallow`, `owned` (git refuses on ownership) or absent (not a git repo).
+//
+// The release notes the core PACKAGE carries (task 1004218) are asked first, and are
+// stubbed here: none unless a test hands some in, so the checkout tests below exercise the
+// fallback — and no test in this file can ever reach the real registry.
 const changeDeps = ({
   shas = { '1.19.900': 'a'.repeat(40), '1.19.949': 'b'.repeat(40) },
   log = LOG, logOk = true, repos = { '/srv/core': 'core' }, env = {}, privileged = false,
+  installedNotes = null, packagedNotes = null,
 } = {}) => {
   const ran = [];
+  const downloaded = [];
   return {
-    ran, env, privileged,
+    ran, downloaded, env, privileged,
     selfInstanceRoot: () => '/srv/core',
     appUser: () => 'appacct',
+    readInstalledNotes: () => (installedNotes ? { notes: installedNotes } : { missing: 'this core carries no release notes' }),
+    readPackagedNotes: (v) => {
+      downloaded.push(v);
+      return packagedNotes ? { notes: packagedNotes } : { missing: `the core ${v} package carries no release notes` };
+    },
     exec: (cmd) => {
       ran.push(cmd);
       const dir = (/git -C (\S+) /.exec(cmd) || [])[1];
@@ -1051,6 +1063,83 @@ await t('a long range is capped, and says how many it did not list', () => {
   assert.equal(r.more, 5, 'the remainder is counted, not silently dropped');
 });
 
+// ---- THE NOTES THE PACKAGE CARRIES, asked first (task 1004218) --------------------
+
+// What the packer writes into release-notes.json: one key per release, what each brought in.
+const NOTES = {
+  '1.19.900': [{ text: 'already live before the move' }],
+  '1.19.901': [{ id: '1004001', text: 'the first thing the move brings' }],
+  '1.19.920': [],
+  '1.19.949': [{ id: '1004003', text: 'the target itself' }, { text: 'a hand-landed ship in the target' }],
+  '1.19.950': [{ text: 'after the target, so not part of this move' }],
+};
+
+await t('THE PACKAGE’S NOTES ANSWER FIRST — on a box with no checkout, and with no git run at all', () => {
+  // A tenant box, which is every box but the one that builds the core: no core history.
+  const d = changeDeps({ packagedNotes: NOTES, repos: {} });
+  const r = R.changesBetween('1.19.900', '1.19.949', d);
+  assert.equal(r.error, undefined);
+  assert.deepEqual(r.entries.map((e) => e.text),
+    ['the target itself', 'a hand-landed ship in the target', 'the first thing the move brings'], 'newest release first');
+  assert.equal(r.source, 'release-notes');
+  assert.deepEqual(d.ran, [], 'not one git command');
+  assert.deepEqual(d.downloaded, ['1.19.949'], "the TARGET's own package is the one read");
+});
+
+await t('the range is (from, to]: what the box already runs is not listed, what the target carries is', () => {
+  const texts = R.changesBetween('1.19.900', '1.19.949', changeDeps({ packagedNotes: NOTES })).entries.map((e) => e.text);
+  assert.ok(!texts.includes('already live before the move'), '`from` is exclusive');
+  assert.ok(texts.includes('the target itself'), '`to` is inclusive');
+  assert.ok(!texts.includes('after the target, so not part of this move'));
+});
+
+await t('the INSTALLED core’s notes answer alone when they already reach the target — nothing is downloaded', () => {
+  const d = changeDeps({ installedNotes: NOTES });
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 3);
+  assert.deepEqual(d.downloaded, [], 'a tenant catching up to where the platform already is costs no download');
+});
+
+await t('installed notes that stop SHORT of the target send it to the target’s package', () => {
+  const d = changeDeps({ installedNotes: { '1.19.900': [], '1.19.901': [{ text: 'x' }] }, packagedNotes: NOTES });
+  assert.equal(R.changesBetween('1.19.900', '1.19.949', d).entries.length, 3);
+  assert.deepEqual(d.downloaded, ['1.19.949']);
+});
+
+await t('notes that BEGIN after the box’s version are not used — the list would look whole and be short', () => {
+  // A bounded file drops its oldest releases. Answering a range that reaches back past
+  // where it begins would silently omit what it no longer holds.
+  const r = R.changesBetween('1.19.850', '1.19.949', changeDeps({ packagedNotes: NOTES, repos: {} }));
+  assert.equal(r.entries, undefined, 'no list at all');
+  assert.match(r.error, /the release notes in the core 1\.19\.949 package begin at core 1\.19\.900, after 1\.19\.850/);
+});
+
+await t('NEITHER SOURCE CAN ANSWER: the error carries both reasons, and is never an empty list', () => {
+  // Every target published before the notes were packaged, on every tenant box.
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps({ repos: {} }));
+  assert.equal(r.entries, undefined);
+  assert.match(r.error, /the core 1\.19\.949 package carries no release notes/, "the notes' reason");
+  assert.match(r.error, /no core checkout is reachable/, "and the checkout's own precise sentence (task 1004212)");
+});
+
+await t('no notes in the package, but a checkout on the box: the checkout still answers', () => {
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps());
+  assert.equal(r.entries.length, 2);
+  assert.equal(r.source, 'checkout');
+});
+
+await t('a download that fails is named, and the checkout is still tried', () => {
+  const d = changeDeps({ repos: {} });
+  d.readPackagedNotes = () => ({ error: 'could not download the core 1.19.949 package to read its release notes (npm error code E404)' });
+  assert.match(R.changesBetween('1.19.900', '1.19.949', d).error, /could not download the core 1\.19\.949 package.*; no core checkout is reachable/);
+});
+
+await t('a notes answer is capped exactly like a checkout answer', () => {
+  const many = { '1.19.900': [], '1.19.949': Array.from({ length: R.CHANGE_CAP + 3 }, (_, i) => ({ text: `summary ${i}` })) };
+  const r = R.changesBetween('1.19.900', '1.19.949', changeDeps({ packagedNotes: many }));
+  assert.equal(r.entries.length, R.CHANGE_CAP);
+  assert.equal(r.more, 3);
+});
+
 await t('the dry run records the list beside the verdict, keyed to where the box IS', async () => {
   // Both answers are about ONE move, so they are stored together — and `from` is stored
   // with them because the list is only true of that starting point.
@@ -1071,5 +1160,240 @@ await t('the dry run records the list beside the verdict, keyed to where the box
   assert.equal(stored.changes.entries[0].text, 'a thing landed');
 });
 
+console.log('\nthe pin reaches the project\'s GitHub repo — pushed from the HUB (task 1004065):');
+
+// THE BUG. A hosted project's upgrade runs connected to the PROJECT's database, which
+// has no provisioning table (ADR 0281), so upgrade.js could never find the owner's
+// token, fell back to `git push origin` over a read-only deploy key (ADR 0176), was
+// refused, and the intent still resolved `done`. hermeslines-marketing's box ran
+// 1.19.994 while its GitHub repo still pinned 1.19.881. These cases drive the whole
+// move so the push is proven to happen, from where the token actually lives, AFTER a
+// confirmed upgrade, and to be reported when it cannot.
+
+const OWNER_TOKEN = 'ghu_OWNER_TOKEN_never_in_a_command';
+
+function pinDeps({ served = '1.19.762', token = OWNER_TOKEN, branch = 'main', pushResult = null, originResult = null, upgradeThrows = false } = {}) {
+  const d = makeDeps({ served });
+  const ran = [];
+  const writes = [];
+  const tokenAsks = [];
+  d.ran = [];
+  d.ranWith = ran;
+  d.exec = (cmd, opts) => {
+    ran.push({ cmd, cwd: opts && opts.cwd, env: opts && opts.env });
+    d.ran.push(cmd);
+    if (/upgrade\.js/.test(cmd) && upgradeThrows) throw new Error('health check failed after restart — rolled back');
+    if (/\/version/.test(cmd)) return { ok: true, stdout: JSON.stringify({ coreVersion: served }) };
+    if (/symbolic-ref/.test(cmd)) {
+      return branch ? { ok: true, stdout: `${branch}\n` } : { ok: true, softFailed: true, stdout: '', stderr: 'fatal: ref HEAD is not a symbolic ref' };
+    }
+    if (/push https:\/\/x-access-token@github\.com\//.test(cmd)) return pushResult || { ok: true, stdout: '' };
+    if (/ push origin /.test(cmd)) return originResult || { ok: true, stdout: '' };
+    return { ok: true, stdout: '' };
+  };
+  d.controlWriteFile = (p, body, o) => { writes.push({ p, body, mode: o && o.mode }); return { ok: true }; };
+  d.getGithubToken = async (builderId) => { tokenAsks.push(builderId); return token ? { token } : null; };
+  d._writes = writes;
+  d._tokenAsks = tokenAsks;
+  return d;
+}
+
+const hosted = (over = {}) => inst({
+  hosting_shape: 'cloud-host', slug: 'acme-site', port: 3011, db_name: 'acme-site',
+  target_ref: 'acme/site', owner_builder_id: 5, ...over,
+});
+const tokenPush = (d) => d.ranWith.find((c) => /push https:\/\/x-access-token@github\.com\//.test(c.cmd));
+const originPush = (d) => d.ranWith.find((c) => / push origin /.test(c.cmd));
+const refusedBy = (stderr) => ({ ok: true, softFailed: true, stdout: '', stderr });
+
+await t('a hosted project\'s upgrade COMMITS the pin on the box and leaves the push to the hub', async () => {
+  const d = pinDeps();
+  await R.coreUpgradeInstance(hosted(), d, intent());
+  const cmd = upgradeCall(d);
+  assert.ok(cmd.includes('--commit-pin'), 'the pin is still committed — an uncommitted pin is the silent-revert bug');
+  assert.ok(cmd.includes('--pin-no-push'), 'and upgrade.js no longer attempts a push it has no credential for');
+});
+
+await t('the platform itself keeps pushing its own pin — its key CAN write its own repo', async () => {
+  const d = makeDeps({ served: '1.19.762' });
+  await R.coreUpgradeInstance(inst(), d, intent());
+  assert.doesNotMatch(upgradeCall(d), /--pin-no-push/, 'unchanged for the control plane');
+});
+
+await t('the preview carries no push flag at all — it never gets as far as a pin', () => {
+  const peek = R.upgradeInvocation(hosted(), '1.19.762', { dryRun: true });
+  assert.doesNotMatch(peek.cmd, /--pin-no-push|--commit-pin/);
+});
+
+await t('THE HUB PUSHES the committed pin to the project\'s repo with the owner\'s token read from the HUB db', async () => {
+  const d = pinDeps();
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.ok, true);
+  assert.deepEqual(d._tokenAsks, [5], 'the OWNER\'s token, looked up by the owner id on the provisioning row');
+  const push = tokenPush(d);
+  assert.ok(push, 'the hub pushed');
+  assert.ok(push.cmd.includes('https://x-access-token@github.com/acme/site.git HEAD:main'), `to the row's target_ref, main — got ${push.cmd}`);
+  assert.ok(push.cmd.includes(`-C ${RP.standaloneRoot(hosted())} `), 'from the project\'s own checkout');
+  assert.equal(r.repo.pushed, true);
+  assert.equal(r.repo.via, 'owner-token');
+  assert.ok(!r.doneNote, 'a clean push leaves nothing to report');
+});
+
+await t('the push happens AFTER the confirmed upgrade, never before it', async () => {
+  const d = pinDeps();
+  await R.coreUpgradeInstance(hosted(), d, intent());
+  const at = (re) => d.ranWith.findIndex((c) => re.test(c.cmd));
+  assert.ok(at(/upgrade\.js/) >= 0 && at(/upgrade\.js/) < at(/x-access-token@github\.com/), 'the pin must exist before it can be pushed');
+});
+
+await t('the TOKEN never appears in a command line, and its credential file is removed', async () => {
+  const d = pinDeps();
+  await R.coreUpgradeInstance(hosted(), d, intent());
+  for (const c of d.ranWith) assert.ok(!c.cmd.includes(OWNER_TOKEN), `argv reaches ps and the journal — leaked in: ${c.cmd}`);
+  assert.equal(d._writes.length, 1, 'one credential file');
+  const cred = d._writes[0];
+  assert.ok(cred.body.includes(OWNER_TOKEN), 'the token rides a file');
+  assert.equal(cred.mode, 0o600, 'readable by the runner alone');
+  assert.ok(tokenPush(d).cmd.includes(`store --file=${cred.p}`), 'git reads it through the store helper');
+  assert.ok(d.ranWith.some((c) => c.cmd === `rm -f ${cred.p}`), 'and it is deleted afterwards');
+});
+
+await t('the push is HARDENED: helper list reset, no hooks, no prompt', async () => {
+  // Helpers are cumulative — a global one would answer first with some other account.
+  // A hook in the project's checkout would otherwise run as the RUNNER on this push.
+  const d = pinDeps();
+  await R.coreUpgradeInstance(hosted(), d, intent());
+  const push = tokenPush(d);
+  assert.match(push.cmd, /-c credential\.helper= -c credential\.helper='store --file=/, 'the empty entry resets the list first');
+  assert.match(push.cmd, /-c core\.hooksPath=\/dev\/null /, 'no hook runs');
+  assert.equal(push.env && push.env.GIT_TERMINAL_PROMPT, '0', 'a refused credential fails instead of waiting at a prompt');
+  assert.doesNotMatch(push.cmd, /--force|\+HEAD/, 'never forced');
+});
+
+await t('the credential file is removed even when the push FAILS', async () => {
+  const d = pinDeps({ pushResult: refusedBy('remote: Write access to repository not granted.\nfatal: unable to access: The requested URL returned error: 403') });
+  await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.ok(d.ranWith.some((c) => c.cmd === `rm -f ${d._writes[0].p}`));
+});
+
+await t('NO TOKEN STORED: the box\'s own remote is tried, and a refusal resolves done WITH a note', async () => {
+  const d = pinDeps({ token: null, originResult: refusedBy('ERROR: The key you are authenticating with has been marked as read only.\nfatal: Could not read from remote repository.') });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.ok, true, 'the upgrade DID land and the site runs it — that is not a failure');
+  assert.ok(originPush(d), 'the remote was tried, in case it can write');
+  assert.equal(d._writes.length, 0, 'no credential file without a credential');
+  assert.equal(r.repo.pushed, false);
+  assert.equal(r.repo.code, 'no_access');
+  assert.match(r.doneNote, /^repo_not_updated:no_access: /, 'the note the web tier reads');
+  assert.match(r.doneNote, /an hour/, 'and it says WHY there was no access, in words');
+});
+
+await t('NO TOKEN, but the box\'s remote CAN write: pushed that way, nothing to report', async () => {
+  const d = pinDeps({ token: null });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.repo.pushed, true);
+  assert.equal(r.repo.via, 'origin');
+  assert.ok(!r.doneNote);
+  assert.match(originPush(d).cmd, /-c core\.hooksPath=\/dev\/null /, 'hardened the same way');
+});
+
+await t('GitHub REFUSES the owner\'s token: named as a refusal, not as "no token stored"', async () => {
+  const d = pinDeps({ pushResult: refusedBy('remote: Write access to repository not granted.\nfatal: unable to access: The requested URL returned error: 403') });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.repo.code, 'refused');
+  assert.match(r.doneNote, /^repo_not_updated:refused: /);
+  assert.match(r.doneNote, /Write access to repository not granted/, 'GitHub\'s own words ride along');
+  assert.equal(originPush(d), undefined, 'a read-only remote cannot succeed where the token was refused');
+});
+
+await t('GitHub HAS COMMITS THE BOX DOES NOT: reported, and nothing is forced over them', async () => {
+  const d = pinDeps({ pushResult: refusedBy(' ! [rejected]        HEAD -> main (fetch first)\nerror: failed to push some refs to \'https://github.com/acme/site.git\'') });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.repo.code, 'behind');
+  assert.match(r.doneNote, /^repo_not_updated:behind: /);
+  assert.ok(!d.ranWith.some((c) => /--force|\+HEAD|reset --hard|rebase/.test(c.cmd)), 'the box never rewrites anyone\'s history');
+});
+
+await t('a push that fails some OTHER way is reported with git\'s line, not guessed at', async () => {
+  const d = pinDeps({ pushResult: refusedBy('fatal: unable to access \'https://github.com/acme/site.git/\': Could not resolve host: github.com') });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.repo.code, 'failed');
+  assert.match(r.doneNote, /Could not resolve host/);
+});
+
+await t('NO REPOSITORY RECORDED: reported, and no git is run after the upgrade', async () => {
+  const d = pinDeps();
+  const r = await R.coreUpgradeInstance(hosted({ target_ref: null }), d, intent());
+  assert.equal(r.repo.code, 'no_repo');
+  assert.match(r.doneNote, /^repo_not_updated:no_repo: /);
+  assert.equal(d._tokenAsks.length, 0, 'no token is read for a push that cannot happen');
+  assert.ok(!d.ranWith.some((c) => /\bgit\b/.test(c.cmd)), 'nothing touched the checkout');
+});
+
+await t('a checkout not on a branch is pushed NOWHERE — HEAD:main from a detached head would be a guess', async () => {
+  const d = pinDeps({ branch: null });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.repo.code, 'no_branch');
+  assert.equal(tokenPush(d), undefined);
+  assert.equal(d._tokenAsks.length, 0, 'and no token is read for it');
+});
+
+await t('a branch name that is not a plain ref never reaches the shell', async () => {
+  const d = pinDeps({ branch: 'main;touch /tmp/pwn' });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.repo.code, 'no_branch');
+  assert.ok(!d.ranWith.some((c) => /pwn/.test(c.cmd)), 'the name was refused, not interpolated');
+});
+
+await t('a FAILED upgrade pushes nothing — only a confirmed pin is worth saving', async () => {
+  const d = pinDeps({ upgradeThrows: true });
+  const r = await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(r.ok, false);
+  assert.equal(tokenPush(d), undefined);
+  assert.equal(d._tokenAsks.length, 0);
+});
+
+await t('the event log says GitHub was not updated, so the history is not a clean success either', async () => {
+  const events = [];
+  const d = pinDeps({ token: null, originResult: refusedBy('ERROR: The key you are authenticating with has been marked as read only.') });
+  d.provisioning = { ...d.provisioning, recordEvent: async (_db, e) => { events.push(e); } };
+  await R.coreUpgradeInstance(hosted(), d, intent());
+  assert.equal(events.length, 1);
+  assert.match(events[0].detail, /GitHub was not updated/);
+});
+
+await t('every note the runner writes is one the web tier reads back, code and sentence intact', () => {
+  for (const code of Object.keys(REPO_NOTES)) {
+    const note = repoNote(code, '(git: something)');
+    const w = parseRepoNote(note);
+    assert.ok(w, `${code} parses`);
+    assert.equal(w.code, code);
+    assert.ok(w.text.startsWith(REPO_NOTES[code]), `${code}: the sentence survives`);
+    assert.ok(note.length <= 600, `${code}: fits the page's bound`);
+  }
+});
+
+await t('the DRAIN LOOP resolves a done-with-a-note move WITH its note, still as done', async () => {
+  // Driven through the real dispatch: the note is only worth anything if it reaches the
+  // intent row the deploy page reads.
+  const P2 = require('../scripts/gds/provision.js');
+  let claims = 0; const resolved = []; const statusWrites = [];
+  const d = pinDeps({ token: null, originResult: refusedBy('ERROR: The key you are authenticating with has been marked as read only.') });
+  d.provisioning = {
+    claimNextIntent: async () => (claims++ === 0 ? { id: 12, instance_id: 7, action: 'core-upgrade', attempts: 1, target_version: '1.19.762', requested_by: 'api:archon:42' } : null),
+    getInstanceById: async () => hosted(),
+    resolveIntent: async (_db, id, state, note) => { resolved.push({ id, state, note }); },
+    setInstanceStatus: async (_db, _id, s, patch) => { statusWrites.push({ s, patch }); },
+    recordEvent: async () => {}, clearErrorNote: async () => {},
+    claimNextOAuthManifest: async () => null, resolveOAuthManifest: async () => {},
+  };
+  const r = await P2.cmdRunIntents(d);
+  assert.equal(r.errors, 0, JSON.stringify(r));
+  assert.equal(resolved.length, 1);
+  assert.equal(resolved[0].state, 'done', 'the upgrade landed — never an error');
+  assert.match(String(resolved[0].note), /^repo_not_updated:no_access: /, 'and the note travels to the row');
+  assert.equal(statusWrites.length, 0, 'a healthy instance is not marked anything');
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/credential_presence.mjs

@@ -0,0 +1,153 @@
+// tests/credential_presence.mjs — the host credential sweep reports names and presence,
+// never a value, and the inventory it sweeps is the one docs/credentials.md documents
+// (task 1002880).
+//
+// Every value below is invented for the test and is chosen to be easy to spot: the
+// "never a value" cases scan the whole report for every value AND every 4-character
+// fragment of one, because a leak of a prefix ("ghp_…") is still a leak.
+//
+// Run:  node --test tests/credential_presence.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'gds', 'credential-presence.js');
+const { CREDENTIALS, parseEnvFile, sweep, format, readFiles } = require('../scripts/gds/credential-presence.js');
+const { envPrefix } = require('../src/instance-config.js');
+const P = envPrefix();
+
+// Random-looking on purpose: a value that shares four characters with a variable name
+// ("CLIE" in CLIENT_ID) would make the fragment scan below flag the name, not a leak.
+const SECRETS = {
+  client: 'q7Zx9vLp2Rk8', pat: 'w3Ty6uHb1Nm4', box: 'e5Rc8oJd0Qs2', key: 'f9Gh2kAa7Vb3',
+};
+const WEB_ENV = [
+  '# /etc/example/web.env — test fixture',
+  `${P}_GITHUB_CLIENT_ID=Iv1clientIDqq9`,
+  `${P}_GITHUB_CLIENT_SECRET="${SECRETS.client}"`,
+  `GITHUB_PUSH_TOKEN=${SECRETS.pat}`,
+  `${P}_GITHUB_OWNER=example-owner`,
+  `${P}_GITHUB_REPO=example-repo`,
+  `BUILDER_SECRET_KEY=${SECRETS.key}`,
+  'DISCORD_BOT_TOKEN=',
+  'PORT=4100',
+].join('\n');
+
+function fragmentsOf(value) {
+  const out = new Set([value]);
+  for (let i = 0; i + 4 <= value.length; i++) out.add(value.slice(i, i + 4));
+  return [...out];
+}
+function assertNoValueIn(text) {
+  for (const v of Object.values(SECRETS)) {
+    for (const frag of fragmentsOf(v)) assert.ok(!text.includes(frag), `the report leaked a fragment of a value: "${frag}"`);
+  }
+}
+
+test('parseEnvFile reads a systemd EnvironmentFile: comments, blanks, quotes, empties', () => {
+  const env = parseEnvFile('# comment\n\nA=1\nB="two words"\nC=\'three\'\nD=\n  E = spaced \nnot a line\n');
+  assert.deepEqual(env, { A: '1', B: 'two words', C: 'three', D: '', E: 'spaced' });
+});
+
+test('a configured host reads as present, row by row, with the NAME that satisfied each', () => {
+  const r = sweep({ files: { 'web.env': { env: parseEnvFile(WEB_ENV) }, 'box.env': { env: { DO_API_TOKEN: SECRETS.box } }, 'spaces.env': { env: {} } } });
+  const row = (id) => r.rows.find((x) => x.id === id);
+  assert.equal(row('github-sign-in').state, 'set');
+  assert.deepEqual(row('github-sign-in').satisfiedBy, [`${P}_GITHUB_CLIENT_ID`, `${P}_GITHUB_CLIENT_SECRET`]);
+  assert.equal(row('publish-pat').state, 'set');
+  assert.equal(row('publish-app').state, 'missing', 'the App is absent...');
+  assert.equal(r.groups.publish.satisfied, true, '...but the publish group is satisfied by the PAT');
+  assert.equal(row('discord-bot').state, 'empty', 'a name present with no value is called out, not treated as set');
+  assert.equal(row('digitalocean').state, 'set');
+  assert.equal(row('cloudflare').state, 'missing');
+  assert.deepEqual(r.requiredMissing, [], 'every required row, or its alternative, is present');
+  assert.equal(r.ok, true);
+});
+
+test('THE ONE RULE: no value, and no fragment of one, ever reaches the report or --json', () => {
+  const r = sweep({ files: { 'web.env': { env: parseEnvFile(WEB_ENV) }, 'box.env': { env: { DO_API_TOKEN: SECRETS.box } }, 'spaces.env': { env: {} } } });
+  assertNoValueIn(format(r, { etc: '/etc/example' }));
+  assertNoValueIn(JSON.stringify(r));
+});
+
+test('a missing required credential fails the sweep and is named', () => {
+  const env = parseEnvFile(WEB_ENV);
+  delete env.GITHUB_PUSH_TOKEN;
+  const r = sweep({ files: { 'web.env': { env }, 'box.env': { env: {} }, 'spaces.env': { env: {} } } });
+  assert.equal(r.groups.publish.satisfied, false, 'neither the App nor the PAT is set');
+  assert.ok(r.requiredMissing.includes('publish-app') && r.requiredMissing.includes('publish-pat'));
+  assert.equal(r.ok, false);
+  assert.match(format(r), /REQUIRED and missing: .*publish-app/);
+});
+
+test('the App needs BOTH halves: an id without a key is not a publish credential', () => {
+  const r = sweep({ files: { 'web.env': { env: { GITHUB_APP_ID: '123' } }, 'box.env': { env: {} }, 'spaces.env': { env: {} } } });
+  const app = r.rows.find((x) => x.id === 'publish-app');
+  assert.equal(app.state, 'missing');
+  assert.deepEqual(app.missing, ['GITHUB_APP_PRIVATE_KEY']);
+});
+
+test('a prefixed name also answers to its legacy spelling, the way the server reads it', () => {
+  const env = { CLOUDBONGOS_GITHUB_CLIENT_ID: 'x-id', CLOUDBONGOS_GITHUB_CLIENT_SECRET: 'x-secret' };
+  const r = sweep({ files: { 'web.env': { env }, 'box.env': { env: {} }, 'spaces.env': { env: {} } } });
+  const row = r.rows.find((x) => x.id === 'github-sign-in');
+  if (P === 'CLOUDBONGOS') return; // the legacy spelling IS canonical on such an instance
+  assert.equal(row.state, 'set');
+  assert.deepEqual(row.satisfiedBy, ['CLOUDBONGOS_GITHUB_CLIENT_ID', 'CLOUDBONGOS_GITHUB_CLIENT_SECRET']);
+});
+
+test('the secret-box key counts when it lives in the key file instead of the env', () => {
+  const r = sweep({ files: { 'web.env': { env: {} }, 'box.env': { env: {} }, 'spaces.env': { env: {} } }, keyFileExists: true });
+  assert.equal(r.rows.find((x) => x.id === 'secret-box-key').state, 'set');
+});
+
+test('an unreadable web.env makes the answer UNKNOWN (exit 2), never a clean pass', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cred-etc-'));
+  try {
+    const files = readFiles(dir);
+    assert.ok(files['web.env'].error, 'no web.env here');
+    assert.deepEqual(files['spaces.env'], { env: {} }, 'an absent spaces.env only means offsite backup was never set up');
+    const r = spawnSync(process.execPath, [SCRIPT, '--etc', dir], { cwd: ROOT, encoding: 'utf8' });
+    assert.equal(r.status, 2, r.stdout + r.stderr);
+    assert.match(r.stdout, /could not read/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('the CLI, run against a real env dir, reports presence and prints no value', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cred-etc-'));
+  try {
+    fs.writeFileSync(path.join(dir, 'web.env'), WEB_ENV);
+    fs.writeFileSync(path.join(dir, 'box.env'), `DO_API_TOKEN=${SECRETS.box}\nCLOUDFLARE_API_TOKEN=\n`);
+    const r = spawnSync(process.execPath, [SCRIPT, '--etc', dir], { cwd: ROOT, encoding: 'utf8' });
+    assert.equal(r.status, 0, r.stdout + r.stderr);
+    assert.match(r.stdout, /✓ github-sign-in/);
+    assert.match(r.stdout, /! cloudflare .*set but EMPTY: CLOUDFLARE_API_TOKEN/);
+    assertNoValueIn(r.stdout + r.stderr);
+    const j = spawnSync(process.execPath, [SCRIPT, '--etc', dir, '--json'], { cwd: ROOT, encoding: 'utf8' });
+    assert.equal(JSON.parse(j.stdout).ok, true);
+    assertNoValueIn(j.stdout + j.stderr);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('docs/credentials.md documents every variable the sweep checks', () => {
+  const doc = fs.readFileSync(path.join(ROOT, 'docs', 'credentials.md'), 'utf8');
+  for (const row of CREDENTIALS) {
+    for (const name of row.names) {
+      const shown = row.prefixed ? `<PREFIX>_${name}` : name;
+      assert.ok(doc.includes('`' + shown + '`'), `docs/credentials.md must name \`${shown}\` (row ${row.id})`);
+    }
+  }
+  assert.match(doc, /never a value|No value of any credential/i, 'the page states the one rule');
+});

package/tests/db_backup_nightly.mjs

@@ -18,6 +18,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { macShapedTools } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SCRIPT = path.join(ROOT, 'scripts', 'gds', 'db-backup-nightly.sh');
@@ -29,13 +30,15 @@ const ENV = 'gds_backup_'.toUpperCase();
 // A fake pg_dump: a plain-format dump of `rows` rows, closed the way pg_dump closes one
 // (including the \unrestrict line patched servers append) unless it is `cut` short, and
 // exiting `exitCode`.
-// `seed` pre-places dumps in the shared dir as [filename, ageInDays].
-function runBackup({ rows = 40, cut = false, exitCode = 0, env = {}, seed = [] } = {}) {
+// `seed` pre-places dumps in the shared dir as [filename, ageInDays]; `mac` puts
+// BSD/macOS-shaped stat and wc first on PATH too.
+function runBackup({ rows = 40, cut = false, exitCode = 0, env = {}, seed = [], mac = false } = {}) {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'db-backup-'));
   const bin = path.join(tmp, 'bin');
   const dir = path.join(tmp, 'backups');
   fs.mkdirSync(bin);
   fs.mkdirSync(dir);
+  if (mac) macShapedTools(bin);
   for (const [name, ageDays] of seed) {
     const f = path.join(dir, name);
     fs.writeFileSync(f, '');
@@ -50,7 +53,7 @@ function runBackup({ rows = 40, cut = false, exitCode = 0, env = {}, seed = [] }
     encoding: 'utf8',
     env: { ...process.env, PATH: `${bin}:${process.env.PATH}`, [`${ENV}DB`]: 'smallproj', [`${ENV}DIR`]: dir, ...env },
   });
-  return { status: r.status, stdout: r.stdout, stderr: r.stderr, dumps: fs.readdirSync(dir).filter((f) => f.endsWith('.sql.gz')) };
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, dir, dumps: fs.readdirSync(dir).filter((f) => f.endsWith('.sql.gz')) };
 }
 
 test('a complete dump of a small project is kept, however small', { skip }, () => {
@@ -93,6 +96,21 @@ test('the prune and the count reach only this database\'s own dumps, never a lon
   assert.match(r.stdout, /ok · 1 dump\(s\) retained/, 'the count is this database\'s dumps only');
 });
 
+test('it runs the same on macOS, where stat refuses -c and wc pads its numbers (task 1004170)', { skip }, () => {
+  // Every case above used to die on a Mac with "stat: illegal option -- c" while CI's
+  // Linux passed them, so the red never showed in Actions. This runs the Mac's tools here.
+  const attach = fs.mkdtempSync(path.join(os.tmpdir(), 'db-backup-attach-'));
+  for (const f of ['a.png', 'b.png']) fs.writeFileSync(path.join(attach, f), 'x');
+  const r = runBackup({ mac: true, seed: [['smallproj-2026-01-01T000000Z.sql.gz', 40]], env: { BUG_ATTACHMENTS_DIR: attach } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.dumps.length, 1, 'the expired dump is pruned and the new one kept');
+  const size = fs.statSync(path.join(r.dir, r.dumps[0])).size;
+  assert.match(r.stdout, new RegExp(`wrote .*\\.sql\\.gz \\(${size} bytes\\)`), 'the byte count is the real size, unpadded');
+  assert.match(r.stdout, /\(2 attachment\(s\)\)/);
+  assert.match(r.stdout, /pruned 1 dump\(s\)/);
+  assert.match(r.stdout, /ok · 1 dump\(s\) retained/);
+});
+
 test('no fixed size floor is baked in for every instance', () => {
   const src = fs.readFileSync(SCRIPT, 'utf8');
   assert.doesNotMatch(src, new RegExp(`${ENV}MIN_BYTES:-[1-9]`), 'a default floor fails every database smaller than it');