@bongos/core 1.24.69 → 1.24.71

package/tests/paste_token_windows.mjs

@@ -0,0 +1,165 @@
+// tests/paste_token_windows.mjs — a first-time CLI sign-in on Windows took four failed
+// attempts (task 1005033). Three of the four failure points are in code:
+//
+//   2. The hall's one-liner starts with `npx`. In Windows PowerShell `npx` resolves to
+//      npx.ps1, which the DEFAULT execution policy refuses to run ("running scripts is
+//      disabled on this system"). `npx.cmd` is the same program without the script
+//      host, and works in PowerShell and cmd alike. The hall now hands a Windows
+//      browser the npx.cmd form.
+//   3. The one-liner only resolves `bongos` inside the project folder (npx finds the
+//      project's own bin); from anywhere else npm says "could not determine executable
+//      to run". Nothing said so — the hall now says it in the instruction itself.
+//   4. The token sat on the command line (shell history). paste-token now also reads it
+//      from a hidden prompt, or from stdin when piped, when no token argument is given.
+//
+//   1. The App's Device Flow switch was off. GitHub has no API to tick it, so the fix is
+//      telling the OWNER: the first refusal files one idempotent blocker
+//      (src/bongos/device-flow-blocker.js). Task 1005118 later replaces the paste route
+//      with a browser approval.
+//
+// Run:  node --test tests/paste_token_windows.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+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 { readTokenFromInput } = require(path.join(ROOT, 'scripts', 'bongos', 'paste-token.js'));
+
+const sink = () => { const s = new PassThrough(); s.text = ''; s.on('data', (c) => { s.text += c; }); return s; };
+
+// ── 4. the token can arrive without touching the command line ────────────────
+
+test('a piped token is read from stdin and trimmed', async () => {
+  const input = new PassThrough();
+  const p = readTokenFromInput({ input, output: sink() });
+  input.end('  abcdef0123456789abcdef0123456789  \r\n');
+  assert.equal(await p, 'abcdef0123456789abcdef0123456789');
+});
+
+test('an interactive prompt reads one line and never echoes the token', async () => {
+  const input = new PassThrough();
+  input.isTTY = true;
+  const modes = [];
+  input.setRawMode = (on) => { modes.push(on); input.isRaw = on; };
+  const output = sink();
+  const p = readTokenFromInput({ input, output });
+  input.write('abcdef01234567');
+  input.write('X\u007f'); // a typo, then backspace
+  input.write('89abcdef\r');
+  const token = await p;
+  assert.equal(token, 'abcdef0123456789abcdef');
+  assert.ok(!output.text.includes('abcdef'), `the token must not be echoed, got: ${JSON.stringify(output.text)}`);
+  assert.match(output.text, /token/i, 'it asks for the token');
+  assert.deepEqual(modes, [true, false], 'raw mode is switched on for the read and back off after');
+});
+
+test('Ctrl+C at the prompt cancels instead of saving a half-typed token', async () => {
+  const input = new PassThrough();
+  input.isTTY = true;
+  input.setRawMode = () => {};
+  const p = readTokenFromInput({ input, output: sink() });
+  input.write('abc\u0003');
+  await assert.rejects(p, /cancel/i);
+});
+
+test('paste-token falls back to the prompt when no token argument is given', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'bongos', 'paste-token.js'), 'utf8');
+  const main = src.slice(src.indexOf('async function main()'));
+  assert.match(main, /readTokenFromInput\(/, 'main reads the token from input when argv has none');
+});
+
+// ── 2 + 3. the hall's one-liner works in a default Windows PowerShell ─────────
+
+const routeSrc = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'routes', 'auth.js'), 'utf8');
+const issueBlock = (() => {
+  const start = routeSrc.indexOf("'/auth/cli-token/issue'");
+  const next = routeSrc.indexOf('\n  router.', start);
+  return routeSrc.slice(start, next === -1 ? routeSrc.length : next);
+})();
+
+test('the issue route also composes a Windows one-liner that avoids npx.ps1', () => {
+  const m = issueBlock.match(/paste_command_windows:\s*issuer\s*\?\s*`([^`]+)`\s*:\s*`([^`]+)`/);
+  assert.ok(m, 'paste_command_windows should be a readable template literal pair');
+  for (const cmd of [m[1], m[2]]) {
+    assert.match(cmd, /^npx\.cmd bongos paste-token \$\{token\}/, `npx.cmd, not npx — got: ${cmd}`);
+  }
+  assert.match(m[1], /--api-base \$\{issuer\}/, 'the Windows form carries the issuer too');
+});
+
+const settingsJs = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'settings.js'), 'utf8');
+const issueFn = (settingsJs.match(/async function issueCliToken\([\s\S]*?\n  \}\n/) || [''])[0];
+
+test('the hall shows the Windows one-liner to a Windows browser', () => {
+  assert.ok(issueFn, 'issueCliToken is a whole function');
+  assert.match(issueFn, /paste_command_windows/, 'it reads the Windows form');
+  assert.match(settingsJs, /function isWindowsBrowser\(/, 'it decides by the browser platform');
+});
+
+test('the hall says the command only runs from inside the project folder', () => {
+  assert.match(issueFn, /cd/, 'the instruction names cd');
+  assert.match(issueFn, /only (runs|works) (from )?(there|inside)/i, 'and says why');
+});
+
+// ── grade round 2 (task 1005033) ─────────────────────────────────────────────
+
+test('a pipe that never closes still settles on the first line', async () => {
+  const input = new PassThrough();
+  const p = readTokenFromInput({ input, output: sink() });
+  input.write('abcdef0123456789abcdef\nsomething else that never ends');
+  assert.equal(await p, 'abcdef0123456789abcdef');
+});
+
+test('Ctrl+D on an empty prompt cancels instead of saving nothing', async () => {
+  const input = new PassThrough();
+  input.isTTY = true;
+  input.setRawMode = () => {};
+  const p = readTokenFromInput({ input, output: sink() });
+  input.write('\u0004');
+  await assert.rejects(p, /cancel/i);
+});
+
+test('the hall offers the token-free command with the token on its own button', () => {
+  assert.match(issueFn, /bongos paste-token\$\{body\.api_base/, 'a command with no token in it');
+  assert.match(issueFn, /Copy token/, 'the token is copied separately');
+  assert.match(issueFn, /Keep the token out of your shell history/, 'and it says why');
+});
+
+// ── 1. the owner hears about Device Flow being off ────────────────────────────
+
+const { raiseDeviceFlowOffBlocker, SOURCE, SOURCE_REF } = require(path.join(ROOT, 'src', 'bongos', 'device-flow-blocker.js'));
+
+test('a device_flow_disabled refusal files ONE owner blocker through ideas.fileBlocker', async () => {
+  const filed = [];
+  const resolveOptional = (port) => (port === 'ideas.fileBlocker' ? async (b) => { filed.push(b); return { id: 1 }; } : null);
+  const out = await raiseDeviceFlowOffBlocker({ reason: 'device_flow_disabled', origin: 'https://x.example', resolveOptional });
+  assert.deepEqual(out, { id: 1 });
+  assert.equal(filed.length, 1);
+  assert.equal(filed[0].source, SOURCE);
+  assert.equal(filed[0].sourceRef, SOURCE_REF, 'a fixed source_ref makes the writer idempotent');
+  assert.match(filed[0].title, /Enable Device Flow/);
+  assert.match(filed[0].bodyMd, /https:\/\/x\.example\/builders\/settings/);
+});
+
+test('any other start failure files nothing', async () => {
+  let called = false;
+  const resolveOptional = () => async () => { called = true; };
+  assert.equal(await raiseDeviceFlowOffBlocker({ reason: 'bad_client_id', resolveOptional }), null);
+  assert.equal(called, false);
+});
+
+test('no ideas module, or a failing write, never breaks the sign-in reply', async () => {
+  assert.equal(await raiseDeviceFlowOffBlocker({ reason: 'device_flow_disabled', resolveOptional: () => null }), null);
+  const boom = () => async () => { throw new Error('db down'); };
+  assert.equal(await raiseDeviceFlowOffBlocker({ reason: 'device_flow_disabled', resolveOptional: boom }), null);
+});
+
+test('the device/start route raises it on the refusal', () => {
+  const start = routeSrc.slice(routeSrc.indexOf("'/auth/device/start'"), routeSrc.indexOf("'/auth/device/start'") + 2500);
+  assert.match(start, /raiseDeviceFlowOffBlocker\(\{ reason/);
+});

package/tests/provision.mjs

@@ -14,6 +14,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import { readFileSync, mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 
 const require = createRequire(import.meta.url);
@@ -905,12 +906,15 @@ t('installedCoreTarball: reuses a consumer instance file: core pin; null on a so
 });
 
 await ta('scaffoldStandaloneRepo: on a consumer control plane it REUSES the pinned tarball — no package-core rebuild (task 1002275)', async () => {
-  // the control plane is itself a consumer instance: its package.json file:-pins the core
+  // the control plane is itself a consumer instance: its package.json file:-pins the core.
+  // Pinned to the REAL running CORE_VERSION — a fixed old literal would now be STALE
+  // (task 1002450) and exercise the recovery instead of the reuse this test is named for.
+  const coreV = P.coreVersionSafe();
   const cp = mkdtempSync(join(tmpdir(), 'cptgz-cp-'));
   mkdirSync(join(cp, 'vendor'));
-  const pinned = join(cp, 'vendor', 'bongos-core-1.17.4.tgz');
+  const pinned = join(cp, 'vendor', `bongos-core-${coreV}.tgz`);
   writeFileSync(pinned, 'x');
-  writeFileSync(join(cp, 'package.json'), JSON.stringify({ dependencies: { '@bongos/core': 'file:vendor/bongos-core-1.17.4.tgz' } }));
+  writeFileSync(join(cp, 'package.json'), JSON.stringify({ dependencies: { '@bongos/core': `file:vendor/bongos-core-${coreV}.tgz` } }));
   const base = mkdtempSync(join(tmpdir(), 'cptgz-standalone-'));   // FRESH base → the scaffold proceeds
   const origBase = P.CONFIG.standaloneBase;
   P.CONFIG.standaloneBase = base;
@@ -931,6 +935,127 @@ await ta('scaffoldStandaloneRepo: on a consumer control plane it REUSES the pinn
   }
 });
 
+// ── the stale-pin guard (task 1002450) ───────────────────────────────────────────────
+// Rung 1 reused a file:-pinned hub's own tarball with no check it was still the core the
+// hub runs — an early instance was born on a 1.18.14 tarball that was NOT the published
+// 1.18.14 (missing the task-1002419 poller fix) and its first ship never left 'confirmed'.
+// A stale pin must be replaced, loudly, and never by the package-core.js rungs (which
+// abort on a consumer hub and leave the new repo empty — task 1002275).
+const sha512 = (txt) => 'sha512-' + createHash('sha512').update(txt).digest('base64');
+function filePinnedHub(label, bytes = 'x', { installed = null, scope = 'bongos' } = {}) {
+  const cp = mkdtempSync(join(tmpdir(), 'stalepin-'));
+  mkdirSync(join(cp, 'vendor'));
+  const file = `${scope}-core-${label}.tgz`;
+  writeFileSync(join(cp, 'vendor', file), bytes);
+  writeFileSync(join(cp, 'package.json'), JSON.stringify({ dependencies: { [`@${scope}/core`]: `file:vendor/${file}` } }));
+  if (installed) {
+    mkdirSync(join(cp, 'node_modules', '@bongos', 'core'), { recursive: true });
+    writeFileSync(join(cp, 'node_modules', '@bongos', 'core', 'package.json'), JSON.stringify({ name: '@bongos/core', version: installed }));
+  }
+  return { cp, pinned: join(cp, 'vendor', file) };
+}
+function resolveWith(cp, coreV, respond = () => ({ ok: true, stdout: '' })) {
+  const cmds = [], logs = [];
+  let res, err;
+  try {
+    res = P.resolveVendorableCoreTarball({ instanceRoot: cp, exec: (c, o) => { cmds.push(c); return respond(c, o); }, log: (m) => logs.push(m), coreV });
+  } catch (e) { err = e; }
+  return { ...res, cmds, logs, err };
+}
+
+t('pinnedTarballVersion: reads both scope aliases; null when the name carries no version', () => {
+  assert.equal(PR.pinnedTarballVersion('/x/vendor/bongos-core-1.18.14.tgz'), '1.18.14');
+  assert.equal(PR.pinnedTarballVersion('cloudbongos-core-2.0.0.tgz'), '2.0.0', 'the @cloudbongos alias the ARTIFACT regex in upgrade.js misses');
+  assert.equal(PR.pinnedTarballVersion('vendor/core.tgz'), null);
+});
+
+t('stale label on a file:-pinned hub → packs the INSTALLED core it runs, loudly, never package-core.js (task 1002450)', () => {
+  const { cp, pinned } = filePinnedHub('1.18.14', 'x', { installed: '1.18.17' });
+  const r = resolveWith(cp, '1.18.17');
+  assert.ok(!r.err, String(r.err));
+  assert.ok(r.logs.some((l) => /STALE/.test(l) && /1\.18\.14/.test(l) && /1\.18\.17/.test(l)), `a loud warning naming both versions, got: ${r.logs.join(' | ')}`);
+  assert.notEqual(r.tgz, pinned, 'never vendors the stale tarball');
+  assert.ok(r.cmds.some((c) => c.startsWith('npm pack ') && c.includes(join(cp, 'node_modules', '@bongos', 'core'))), 'packs node_modules/@bongos/core despite the file: pin');
+  assert.equal(r.tgz, join(r.packDest, 'bongos-core-1.18.17.tgz'));
+  assert.ok(!r.cmds.some((c) => /package-core\.js/.test(c)), 'the empty-set abort path is never reached');
+  assert.equal(PR.runningCoreVersion({ instanceRoot: cp, coreV: '1.18.17' }), '1.18.17', 'the hall runs coreV, not the leftover label');
+  rmSync(cp, { recursive: true, force: true });
+});
+
+t('stale label and no installed match → the registry\'s coreV; no registry either → refuses loudly, never an empty repo (task 1002450)', () => {
+  const { cp } = filePinnedHub('1.18.14');
+  const ok = resolveWith(cp, '1.18.17');
+  assert.ok(ok.cmds.some((c) => c.startsWith('npm pack @bongos/core@1.18.17 ')), `packs the published coreV, got: ${ok.cmds.join(' | ')}`);
+  assert.equal(ok.tgz, join(ok.packDest, 'bongos-core-1.18.17.tgz'));
+  const down = resolveWith(cp, '1.18.17', (c) => (c.startsWith('npm pack ') ? { ok: false, stdout: '' } : { ok: true, stdout: '' }));
+  assert.ok(down.err && /refusing to give a new project a stale core/.test(down.err.message), 'a scaffold with nothing current to vendor is refused');
+  assert.ok(!down.cmds.some((c) => /package-core\.js/.test(c)));
+  rmSync(cp, { recursive: true, force: true });
+});
+
+t('same label, different bytes (the charter case) → the registry\'s own bytes for that version; matching bytes → reuse (task 1002450)', () => {
+  const { cp, pinned } = filePinnedHub('1.18.14', 'local-build');
+  const view = (published) => (c) => (c.startsWith('npm view @bongos/core@1.18.14 dist.integrity') ? { ok: true, stdout: published + '\n' } : { ok: true, stdout: '' });
+  const bad = resolveWith(cp, '1.18.14', view(sha512('published-build')));
+  assert.ok(bad.logs.some((l) => /STALE/.test(l) && /same version label/.test(l)), `loud, got: ${bad.logs.join(' | ')}`);
+  assert.ok(bad.cmds.some((c) => c.startsWith('npm pack @bongos/core@1.18.14 ')), 'repacks the canonical published artifact');
+  assert.notEqual(bad.tgz, pinned);
+  const good = resolveWith(cp, '1.18.14', view(sha512('local-build')));
+  assert.equal(good.tgz, pinned, 'identical bytes → reuse');
+  assert.equal(good.packDest, null);
+  assert.ok(!good.logs.some((l) => /STALE|WARNING/.test(l)));
+  rmSync(cp, { recursive: true, force: true });
+});
+
+t('unverifiable pin (no coreV, no registry answer) → reused, but SAID out loud; the cloudbongos alias is checked too (task 1002450)', () => {
+  const { cp, pinned } = filePinnedHub('1.18.14');
+  const noCore = resolveWith(cp, null);
+  assert.equal(noCore.tgz, pinned, 'fail-open: a resolution gap never blocks a scaffold');
+  assert.ok(noCore.logs.some((l) => /WARNING: cannot verify/.test(l)), 'but it is not silent');
+  const offline = resolveWith(cp, '1.18.14');
+  assert.equal(offline.tgz, pinned);
+  assert.ok(offline.logs.some((l) => /WARNING: cannot verify/.test(l) && /no integrity/.test(l)));
+  rmSync(cp, { recursive: true, force: true });
+  const alt = filePinnedHub('1.0.0', 'x', { scope: 'cloudbongos' });
+  const r = resolveWith(alt.cp, '1.0.1');
+  assert.ok(r.logs.some((l) => /STALE/.test(l)), 'a cloudbongos-core-* pin is not exempt from the label check');
+  assert.notEqual(r.tgz, alt.pinned);
+  rmSync(alt.cp, { recursive: true, force: true });
+});
+
+t('a stale pin\'s recovery never puts an unsafe version into a shell command (task 1002450)', () => {
+  const { cp } = filePinnedHub('1.18.14');
+  const r = resolveWith(cp, '1.18.17;touch pwn');
+  assert.ok(!r.cmds.some((c) => /pwn/.test(c)), `no command carries the label, got: ${r.cmds.join(' | ')}`);
+  assert.ok(r.err && /refusing to give a new project a stale core/.test(r.err.message), 'nothing safe to pack → refused');
+  rmSync(cp, { recursive: true, force: true });
+  // the INSTALLED core's version (read off node_modules) is held to the same rule
+  const inst = filePinnedHub('1.18.14', 'x', { installed: '1.18.17;touch pwn' });
+  const r2 = resolveWith(inst.cp, '1.18.17;touch pwn');
+  assert.ok(!r2.cmds.some((c) => /pwn/.test(c)), `no command carries the installed label, got: ${r2.cmds.join(' | ')}`);
+  assert.ok(r2.err, 'refused');
+  rmSync(inst.cp, { recursive: true, force: true });
+});
+
+t('a file:-pinned hub BEHIND the release gives the new project the release, not its own pin (hub-vs-upstream drift, tasks 1004556 + 1002450)', () => {
+  const { cp, pinned } = filePinnedHub('1.18.14');
+  const cmds = [];
+  const exec = (c) => { cmds.push(c); return { ok: true, stdout: /dist-tags\.latest/.test(c) ? '1.18.17\n' : '' }; };
+  const target = PR.projectCoreTarget({ instanceRoot: cp, coreV: '1.18.14', exec, log: () => {} });
+  assert.deepEqual([target.version, target.source], ['1.18.17', 'released']);
+  const r = P.resolveVendorableCoreTarball({ instanceRoot: cp, exec, log: () => {}, coreV: '1.18.14', target });
+  assert.notEqual(r.tgz, pinned, 'the hub\'s own (older) pin is not vendored');
+  assert.ok(cmds.some((c) => c.startsWith('npm pack @bongos/core@1.18.17 ')), 'the release is packed from the registry');
+  rmSync(cp, { recursive: true, force: true });
+});
+
+t('publishing one version twice as different bytes is refused loudly by the publish workflow (the publish half of the build-identity guard, task 1002450)', () => {
+  const wf = readFileSync(new URL('../.github/workflows/publish.yml', import.meta.url), 'utf8');
+  assert.match(wf, /npm publish "\$TGZ"/, 'the workflow publishes to the npm registry, where a version is immutable');
+  assert.match(wf, /cannot publish over\|previously published\|EPUBLISHCONFLICT/, 'it recognises the registry\'s refusal');
+  assert.match(wf, /::error title=version already on the registry/, 'and fails the run loudly on it');
+});
+
 // ── registry-pinned consumer control plane (task 1002706) ─────────────────────────
 // After the mothership's registry cutover (task 1002621) its package.json pins
 // "@bongos/core": "1.19.x" — NO file: pin — so installedCoreTarball returns null and,
@@ -1001,10 +1126,10 @@ t('resolveVendorableCoreTarball: the ladder picks file: pin → registry pack
   // One helper per rung so the ONLY thing varying between cases is which shape the
   // control-plane root presents. Asserting on the recorded commands is what proves the
   // ORDER: a rung that fires early leaves the later rung's command unrun.
-  const run = (instanceRoot, repoRoot) => {
+  const run = (instanceRoot, repoRoot, coreV = '9.9.9') => {
     const cmds = [];
     const res = P.resolveVendorableCoreTarball({
-      instanceRoot, repoRoot, exec: (c) => { cmds.push(c); }, log: () => {}, coreV: '9.9.9',
+      instanceRoot, repoRoot, exec: (c) => { cmds.push(c); }, log: () => {}, coreV,
     });
     return { cmds, ...res };
   };
@@ -1017,9 +1142,9 @@ t('resolveVendorableCoreTarball: the ladder picks file: pin → registry pack
   mkdirSync(join(filePinned, 'vendor'));
   writeFileSync(join(filePinned, 'vendor', 'bongos-core-1.2.3.tgz'), 'x');
   writeFileSync(join(filePinned, 'package.json'), JSON.stringify({ dependencies: { '@bongos/core': 'file:vendor/bongos-core-1.2.3.tgz' } }));
-  const r1 = run(filePinned, bareRoot);
+  const r1 = run(filePinned, bareRoot, '1.2.3');
   assert.equal(r1.tgz, join(filePinned, 'vendor', 'bongos-core-1.2.3.tgz'));
-  assert.deepEqual(r1.cmds, [], 'rung 1 runs no command — it reuses bytes already on disk');
+  assert.ok(r1.cmds.every((c) => c.startsWith('npm view ')), 'rung 1 builds and packs nothing — it reuses bytes already on disk (only the read-only integrity check runs)');
 
   // Rung 2 — a registry-installed core packs, still without touching package-core.js.
   const reg = mkdtempSync(join(tmpdir(), 'rvct-reg-'));

package/tests/vendored_work_root.mjs

@@ -0,0 +1,72 @@
+// tests/vendored_work_root.mjs
+//
+// task 1005100 - feedback instance vendors: in a project that installs the core from npm
+// (toast, core 1.21.115), docs-entropy.js and ship-check.js took their root from
+// path.resolve(__dirname, '..', '..') — the PACKAGE dir under node_modules/@bongos/core.
+// docs-entropy then ran `git ls-files '*.md'` there, enumerated 0 files and died with a
+// "scan defect"; ship-check ran every generator from the package dir, so gen-api-docs read
+// STALE while `npx bongos exec scripts/bongos/gen-api-docs.js --check` from the project
+// said up to date. resolveWorkRoot() is the root these tools work on: the core checkout when
+// the core is a checkout, the project (pointer, else the git top of cwd, else cwd) when it
+// is installed. ship-check spawns the script from the core and runs it in that root.
+//
+// Run:  node tests/vendored_work_root.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { resolveWorkRoot, CORE_ROOT } = require('../scripts/bongos/fitness-lib.js');
+const { runStep } = require('../scripts/bongos/ship-check.js');
+
+const real = (p) => fs.realpathSync.native(p);
+const tmp = (name) => fs.mkdtempSync(path.join(os.tmpdir(), `vwr-${name}-`));
+
+test('a core checkout works on the core root, whatever the cwd', () => {
+  assert.equal(resolveWorkRoot({ installed: false, cwd: os.tmpdir() }), CORE_ROOT);
+});
+
+test('an installed core with a pointer works on the pointed-at project', () => {
+  assert.equal(resolveWorkRoot({ installed: true, cwd: os.tmpdir(), explicit: () => '/proj' }), '/proj');
+});
+
+test('an installed core with no pointer works on the git top of cwd, not the package dir', () => {
+  const repo = tmp('repo');
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  const sub = path.join(repo, 'docs');
+  fs.mkdirSync(sub);
+  const got = resolveWorkRoot({ installed: true, cwd: sub, explicit: () => null });
+  assert.equal(real(got), real(repo));
+});
+
+test('an installed core outside any repo falls back to cwd', () => {
+  const dir = tmp('norepo');
+  const got = resolveWorkRoot({ installed: true, cwd: dir, explicit: () => null, gitTop: () => null });
+  assert.equal(got, dir);
+});
+
+test('ship-check runs a step from the core but inside the work root', () => {
+  const core = tmp('core');
+  const inst = tmp('inst');
+  fs.mkdirSync(path.join(core, 'scripts', 'bongos'), { recursive: true });
+  fs.writeFileSync(path.join(core, 'scripts', 'bongos', 'where.js'), 'console.log("cwd=" + process.cwd());\n');
+  const r = runStep({ key: 'w', label: 'w', argv: ['scripts/bongos/where.js'], fix: 'f' }, { coreRoot: core, cwd: inst });
+  assert.equal(r.status, 'ok', r.tail);
+  assert.match(r.tail, /cwd=/);
+  assert.equal(real(r.tail.trim().replace(/^cwd=/, '')), real(inst));
+});
+
+test('docs-entropy and ship-check no longer hardwire their root to the package dir', () => {
+  for (const f of ['scripts/bongos/docs-entropy.js', 'scripts/bongos/ship-check.js']) {
+    const src = fs.readFileSync(path.join(ROOT, f), 'utf8');
+    assert.doesNotMatch(src, /const REPO_ROOT = path\.resolve\(__dirname, '\.\.', '\.\.'\)/, f);
+    assert.match(src, /resolveWorkRoot\(\)/, f);
+  }
+});