blockyard 0.0.9 → 0.1.1

package/scripts/check.js

@@ -148,6 +148,52 @@ export async function runChecks(node, { rpc, fs = { existsSync, statSync, readdi
     }
   }
 
+  // ---- what KIND of node is this, and what can it do that Core cannot? ----
+  //
+  // Until 2026-09-16 there was no way to tell over RPC. The monitor says so in
+  // its own source: "both report the same non-Core subversion string. So RPC
+  // cannot tell you whether RPC is complete; only the log's build banner can."
+  // That is why `log.enabled` is a per-node setting -- identifying the node
+  // needed FILE ACCESS to a machine we can already reach by RPC.
+  //
+  // bmcgetcapabilities answers it in one call. A plain Core node does not have
+  // the method, and that is not a failure: it is how we learn this is Core.
+  // Every field it returns is LIVE STATE rather than a compile-time list, so
+  // "the node serves address history" means it is serving it now, not that the
+  // binary could if configured.
+  {
+    const caps = await one('bmcgetcapabilities', [], 5000);
+    if (!caps.ok) {
+      facts.nodeKind = 'core';
+      add('node kind', 'ok', 'Bitcoin Core (or a node without bmcgetcapabilities) — BlockYard supplies the address index itself');
+    } else {
+      const r = caps.result ?? {};
+      const x = r.extensions ?? {};
+      facts.nodeKind = r.node ?? 'bitcoinmachinecode';
+      facts.nodeBuild = r.build?.commit ?? null;
+      facts.nodeCapabilities = {
+        addrindex: Boolean(x.addrindex),
+        esploraPort: Number(x.esploraport ?? 0) || 0,
+        mempoolJournal: Boolean(x.mempooljournal?.enabled),
+        mempoolJournalCapacity: x.mempooljournal?.enabled ? Number(x.mempooljournal.capacity) : 0,
+        downloadInfo: Boolean(x.downloadinfo),
+        rpcComplete: Boolean(r.rpc_complete?.peerinfo && r.rpc_complete?.nettotals),
+      };
+      const have = [];
+      if (facts.nodeCapabilities.addrindex) have.push('address history from the node');
+      if (facts.nodeCapabilities.esploraPort) have.push(`Esplora facade on :${facts.nodeCapabilities.esploraPort}`);
+      if (facts.nodeCapabilities.mempoolJournal) have.push(`mempool departure journal (${facts.nodeCapabilities.mempoolJournalCapacity.toLocaleString()} records)`);
+      if (facts.nodeCapabilities.downloadInfo) have.push('download worker map');
+      add('node kind', 'ok',
+          `${facts.nodeKind} ${facts.nodeBuild ? `(${facts.nodeBuild}${r.build?.dirty ? ', dirty' : ''}) ` : ''}in ${caps.ms}`
+          + (have.length ? ` — ${have.join(', ')}` : ' — no extensions enabled'));
+      // The one that changes what BlockYard has to DO: with the node serving
+      // address history there is no reason to build and follow a second copy.
+      if (facts.nodeCapabilities.addrindex)
+        add('address index', 'ok', 'the node serves it (addrindex=1) — BlockYard does not need to build its own');
+    }
+  }
+
   return { ok: !checks.some((c) => c.status === 'fail'), checks, facts };
 }
 

package/scripts/donate-qr.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
-# Regenerate the donation QR in public/index.html (the <svg class="abqr">) from the address below,
-# with OpenCV's encoder, and check the modules written decode back to the address. Run by hand when
-# the address changes; the SVG is committed, so nothing is generated at run time or in the browser.
+# Regenerate the donation QR (public/donate-qr.png, 4 px a module with the 4-module quiet zone) from
+# the address below, with OpenCV's encoder, and check the modules written decode back to the address.
+# Run by hand when the address changes; the PNG is committed, so nothing is generated at run time or
+# in the browser. It was an inline SVG until 2026-09-15, when Safari painted its ground and none of
+# its module rects; a bitmap is painted the same everywhere.
 import cv2, numpy as np, re, sys
 ADDR = 'bc1q249cv27lc2q7y0x53vkczgfvvgsjzhwxwv42gc'
 img = cv2.QRCodeEncoder.create().encode(ADDR)
@@ -12,9 +14,10 @@ for mm in re.finditer(r'M(\d+) (\d+)h1v1h-1z', d):
     x, y = int(mm.group(1)), int(mm.group(2)); m[y*8:(y+1)*8, x*8:(x+1)*8] = 0
 data, _, _ = cv2.QRCodeDetector().detectAndDecode(m)
 if data != ADDR: sys.exit(f'the QR does not decode to the address: {data!r}')
-svg = f'<svg class="abqr" viewBox="0 0 {size} {size}" width="132" height="132" role="img" aria-label="QR code of the donation address" shape-rendering="crispEdges"><rect width="{size}" height="{size}" fill="#fff"/><path fill="#000" d="{d}"/></svg>'
-p = 'public/index.html'; s = open(p).read()
-s2 = re.sub(r'<svg class="abqr".*?</svg>', svg, s, count=1, flags=re.S)
-if s2 == s and svg not in s: sys.exit('no <svg class="abqr"> in public/index.html to replace')
-open(p, 'w').write(s2)
-print(f'{n}x{n} modules, decodes to {data}')
+png = np.full((size * 4, size * 4), 255, np.uint8)
+for mm in re.finditer(r'M(\d+) (\d+)h1v1h-1z', d):
+    x, y = int(mm.group(1)), int(mm.group(2)); png[y*4:(y+1)*4, x*4:(x+1)*4] = 0
+cv2.imwrite('public/donate-qr.png', png)
+check, _, _ = cv2.QRCodeDetector().detectAndDecode(cv2.imread('public/donate-qr.png'))
+if check != ADDR: sys.exit(f'the PNG does not decode to the address: {check!r}')
+print(f'{n}x{n} modules, public/donate-qr.png decodes to {check}')

package/scripts/dos-bench.js

@@ -0,0 +1,56 @@
+// How fast the DOS Diversions' emulated PC runs on this machine, headless (docs/MEASUREMENTS.md §32).
+//
+// Boots a game from games/ on a clock that counts instructions, lets its title and demos run, and
+// reports instructions a second of wall time and the screens it drew. No browser: the same x86.js
+// and dospc.js the worker runs, on Node's V8.
+//
+//   node scripts/dos-bench.js [doom|quake] [millions of instructions]
+//
+// DOOM runs at 30 million instructions to the virtual second (a fast 486); Quake at 70 million and
+// with `+timedemo demo1`, so its screens drawn over the virtual time are the frame rate its own
+// benchmark reports on a machine exactly as fast as this emulator.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createPC } from '../public/js/dospc.js';
+import { createSoundCard } from '../public/js/soundcard.js';
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const game = process.argv[2] === 'quake' ? 'quake' : 'doom';
+const SPEC = {
+  doom: { dir: 'doom_dos', exe: 'DOOM.EXE', args: '', ips: 30e6, total: 400 },
+  quake: { dir: 'quake_dos', exe: 'QUAKE.EXE', args: '-nocdaudio +timedemo demo1', ips: 70e6, total: 3000 },
+}[game];
+const DIR = path.join(ROOT, 'games', SPEC.dir);
+const total = Number(process.argv[3] ?? SPEC.total) * 1e6;
+
+if (!fs.existsSync(path.join(DIR, SPEC.exe))) {
+  console.error(`no ${path.join(DIR, SPEC.exe)}: this measures the shareware ${game}, which is not here`);
+  process.exit(1);
+}
+const files = {};
+const walk = (dir, pre) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.')) continue;
+    if (e.isDirectory()) walk(path.join(dir, e.name), `${pre}${e.name}/`);
+    else files[`${pre}${e.name}`] = new Uint8Array(fs.readFileSync(path.join(dir, e.name)));
+  }
+};
+walk(DIR, '');
+
+let pc;
+const now = () => (pc ? pc.cpu.cycles : 0) / SPEC.ips * 1000;
+pc = createPC({ files, now, args: SPEC.args, sound: (mem) => createSoundCard({ mem, rate: 44100 }) });
+pc.boot(files[SPEC.exe]);
+
+const t0 = process.hrtime.bigint();
+let done = 0, graphicsAt = null;
+while (done < total && !pc.exited) {
+  done += pc.run(1e6);
+  if (graphicsAt === null && pc.vga.mode === 0x13) graphicsAt = done;
+}
+const secs = Number(process.hrtime.bigint() - t0) / 1e9;
+console.log(`${game} on node ${process.version}`);
+console.log(`${(done / 1e6).toFixed(0)} M instructions in ${secs.toFixed(2)} s: ${(done / secs / 1e6).toFixed(1)} M a second`);
+console.log(`graphics mode after ${(graphicsAt / 1e6).toFixed(1)} M instructions`);
+console.log(`${(pc.vga.frames / 2).toFixed(0)} pages flipped, ${(pc.vga.writes / 64000).toFixed(0)} screens' worth written, in ${(done / SPEC.ips).toFixed(1)} virtual seconds`);

package/scripts/index-build.js

@@ -3,7 +3,9 @@
 //
 //   node scripts/index-build.js --out <dir> [--node <id>] [--workers N] [--files 0,1,5754]
 //
-// --files builds a partial index for testing (the completeness check is skipped). Progress goes to
+// --files builds a partial index for testing (the completeness check is skipped). A build stopped part
+// way resumes when run again with the same --out (build.js, THE BUILD JOURNAL); the log line says so,
+// or says why the unfinished work was discarded. Progress goes to
 // stderr once a second; the manifest, with every phase's timings, goes to stdout at the end.
 import { loadConfig } from '../server/config.js';
 import { RpcClient } from '../server/rpc/client.js';
@@ -12,6 +14,10 @@ import path from 'node:path';
 import { progress, progressLine, strip, c, fmt } from './ui.js';
 
 const arg = (name, def) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : def; };
+// --workers must be a whole number of at least one (audit 2026-09-16, I3): `abc` or `0` made a pool with
+// no workers, and with --files that wrote a "successful" manifest of zero rows
+const workersArg = process.argv.includes('--workers') ? String(arg('workers')) : null;
+if (workersArg != null && !(/^\d+$/.test(workersArg) && Number(workersArg) >= 1 && Number.isSafeInteger(Number(workersArg)))) { console.error(`--workers must be a whole number of at least 1, not ${JSON.stringify(workersArg)}`); process.exit(2); }
 const cfg = loadConfig();
 const node = cfg.nodes.find((n) => n.id === arg('node', null)) ?? cfg.nodes.find((n) => n.datadir) ?? cfg.nodes[0];
 if (!node.datadir) { console.error(`node ${node.id} has no datadir configured; the index is built from its block files`); process.exit(2); }
@@ -25,7 +31,8 @@ const bar = progress();
 const manifest = await buildIndex({
   rpc, blocksDir: path.join(node.datadir, 'blocks'), out,
   pace: rpcPacer(rpc, { onChange: (held) => process.stderr.write(held ? '  paused while the node\'s RPC is slow or failing\n' : '  resumed\n') }),
-  workers: arg('workers', null) ? Number(arg('workers')) : undefined,
+  log: (text) => { bar.done(); process.stderr.write(`  ${text}\n`); },
+  workers: workersArg != null ? Number(workersArg) : undefined,
   files: arg('files', null) ? arg('files').split(',').map(Number) : null,
   onProgress: (p) => {
     if (p.phase !== phase) {

package/scripts/pool-map.js

@@ -16,6 +16,13 @@
 //   node scripts/pool-map.js                      # fetch and write data/pool-map.json
 //   node scripts/pool-map.js --file pools-v2.json # offline input
 //   node scripts/pool-map.js --check              # compare against what we are seeing now
+//   node scripts/pool-map.js --yes                # replace an existing data/pool-map.json without asking
+//   node scripts/pool-map.js --expect-sha256 HEX  # refuse a download that is not exactly those bytes
+//
+// Before it replaces data/pool-map.json it prints which pools the new map adds, removes and
+// changes, and writes only on --yes or a "y" at the prompt; redirects are followed to HTTPS only,
+// by both the node:https path and the curl fallback; and the coverage check asks the monitor on
+// the port and scheme its config names (2026-09-16, audit L15).
 //
 // The input shape as fetched on 2026-09-09: 35,733 bytes, 171 pools, 201 tags, keys
 // per pool: addresses, id, link, name, tags. Tags are literal fragments of the coinbase
@@ -85,14 +92,29 @@ function build(content, source) {
 // 367 ms. Pinning the family is the fix; a curl fallback is kept because a tool that
 // fetches pool labels has to work on a box whose stack is half broken.
 import https from 'node:https';
+import readline from 'node:readline/promises';
 import { execFileSync } from 'node:child_process';
+import { loadConfig } from '../server/config.js';
+
+/**
+ * Where a redirect may go (2026-09-16, audit L15): HTTPS only. A `Location: http://...` would
+ * otherwise have been followed by the curl fallback, and the labels read over plain HTTP.
+ * Returns the absolute next URL, or throws.
+ */
+export function redirectTarget(location, from) {
+  const next = new URL(location, from);
+  if (next.protocol !== 'https:') throw new Error(`refusing a redirect from ${from} to ${next.protocol}//${next.host}: HTTPS only`);
+  return next.toString();
+}
 
-function getOverHttps(url, redirectsLeft = 3, extra = {}) {
+export function getOverHttps(url, redirectsLeft = 3, extra = {}) {
   return new Promise((resolve, reject) => {
     const req = https.get(url, { family: 4, ...extra, headers: { 'user-agent': 'BlockYard pool-map/1' }, timeout: 20_000 }, (res) => {
       if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location && redirectsLeft > 0) {
         res.resume();
-        return resolve(getOverHttps(new URL(res.headers.location, url).toString(), redirectsLeft - 1));
+        let next;
+        try { next = redirectTarget(res.headers.location, url); } catch (err) { return reject(err); }
+        return resolve(getOverHttps(next, redirectsLeft - 1));
       }
       if (res.statusCode !== 200) { res.resume(); return reject(new Error(`GET ${url} -> HTTP ${res.statusCode}`)); }
       const chunks = [];
@@ -105,53 +127,147 @@ function getOverHttps(url, redirectsLeft = 3, extra = {}) {
   });
 }
 
+/**
+ * The curl fallback's arguments. `--proto =https --proto-redir =https` (2026-09-16, audit L15):
+ * -L alone follows a redirect to any protocol curl speaks, plain http included.
+ */
+export function curlArgs(url) {
+  return ['-fsSL', '--proto', '=https', '--proto-redir', '=https', '--max-time', '25', url];
+}
+
 async function fetchContent() {
   try {
     return await getOverHttps(URL_);
   } catch (err) {
     // curl follows its own resolver order and got 200 here while node's fetch failed,
     // so a second, different path is worth one retry before declaring the fetch dead.
+    // A refused non-HTTPS redirect is not a flaky stack: it is not retried another way.
+    if (/HTTPS only/.test(err?.message ?? '')) throw err;
     try {
-      return execFileSync('curl', ['-fsSL', '--max-time', '25', URL_], { encoding: 'utf8', maxBuffer: 8 << 20 });
+      return execFileSync('curl', curlArgs(URL_), { encoding: 'utf8', maxBuffer: 8 << 20 });
     } catch {
       throw new Error(`could not fetch ${URL_}: ${err?.message ?? err}`);
     }
   }
 }
 
-const content = asFile ? fs.readFileSync(asFile, 'utf8') : await fetchContent();
-const map = build(content, asFile ? `file:${path.basename(asFile)}` : URL_);
-
-// What we are actually seeing right now, so the coverage number is measured and not
-// assumed. Read live from the running monitor if it answers; otherwise say it is unknown.
-let observed = null;
-let coverageError = null;
-try {
-  const cfgPath = path.join(ROOT, 'config', 'local.json');
-  const host = JSON.parse(fs.readFileSync(cfgPath, 'utf8'))?.server?.hosts?.[0] ?? '127.0.0.1';
-  // Same family:4 path as the fetch above, plus the box's own CA: the monitor serves TLS
-  // from a local CA that is not in the system trust store, and "could not verify" is a
-  // different fact from "could not reach".
-  const caFile = process.env.BLOCKYARD_CA_FILE ?? null;   // a CA file, only where the fetch needs a private one
-  const body = await getOverHttps(`https://${host}:8088/api/mining?node=main`, 0, fs.existsSync(caFile) ? { ca: fs.readFileSync(caFile) } : {});
-  const d = JSON.parse(body);
-  const rows = d.recent ?? [];
-  const hit = rows.filter((r) => map.matchers.some((m) => normalizeText(`${r.rawCoinbase ? Buffer.from(r.rawCoinbase, 'hex').toString('utf8') : ''} ${r.tagText || ''}`).includes(m.tagNorm))).length;
-  observed = {
-    blocks: rows.length, labelled: hit, unknown: rows.filter((r) => !r.poolLabel).length,
-    labelSource: d.labelSource ? `labels from ${d.labelSource.source} @ ${(d.labelSource.sha256 || '').slice(0, 10)}` : 'no map loaded by the monitor yet',
-  };
-} catch (err) {
-  coverageError = err?.message ?? String(err);
+/**
+ * What a refresh changes, pool by pool (2026-09-16, audit L15): the file decides which
+ * organisation the dashboard names for a block, so a rewrite is shown before it is made.
+ * `changed` is a pool whose name, link or tags differ. Keys are the maps' own pool keys.
+ */
+export function diffPoolMaps(before, after) {
+  const index = (m) => new Map((m?.pools ?? []).map((p) => [p.key, p]));
+  const a = index(before), b = index(after);
+  const same = (x, y) => x.name === y.name && (x.link ?? null) === (y.link ?? null)
+    && JSON.stringify([...(x.tags ?? [])].sort()) === JSON.stringify([...(y.tags ?? [])].sort());
+  const added = [...b.keys()].filter((k) => !a.has(k)).sort();
+  const removed = [...a.keys()].filter((k) => !b.has(k)).sort();
+  const changed = [...b.keys()].filter((k) => a.has(k) && !same(a.get(k), b.get(k))).sort();
+  return { added, removed, changed, unchanged: [...b.keys()].filter((k) => a.has(k)).length - changed.length };
+}
+
+export function formatDiff(d, name = (k) => k) {
+  const list = (ks) => (ks.length > 12 ? `${ks.slice(0, 12).map(name).join(', ')}, and ${ks.length - 12} more` : ks.map(name).join(', '));
+  const lines = [`pools: ${d.added.length} added, ${d.removed.length} removed, ${d.changed.length} changed, ${d.unchanged} unchanged`];
+  if (d.added.length) lines.push(`  + ${list(d.added)}`);
+  if (d.removed.length) lines.push(`  - ${list(d.removed)}`);
+  if (d.changed.length) lines.push(`  ~ ${list(d.changed)}`);
+  return lines.join('\n');
+}
+
+/** --expect-sha256: the download must be exactly these bytes (2026-09-16, audit L15). */
+export function checkExpectedSha(content, expected) {
+  if (expected == null) return null;
+  const want = String(expected).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(want)) throw new Error('--expect-sha256 takes 64 hex characters');
+  const got = crypto.createHash('sha256').update(content).digest('hex');
+  if (got !== want) throw new Error(`sha256 mismatch: expected ${want}, got ${got}; nothing written`);
+  return got;
+}
+
+/**
+ * The running monitor's own mining endpoint, for the coverage check (2026-09-16, audit L15): it
+ * was https://<host>:8088 whatever the config said, and the default port has been 21000 since
+ * 2026-09-13, so coverage was never measured. Port, TLS and bind address come from the loaded
+ * config (config/local.json, BLOCKYARD_PORT, BLOCKYARD_TLS); HTTPS unless TLS is turned off.
+ */
+export function coverageUrl(cfg) {
+  const server = cfg?.server ?? {};
+  let host = server.hosts?.[0] ?? server.host ?? '127.0.0.1';
+  if (Array.isArray(host)) host = host[0] ?? '127.0.0.1';
+  if (host === '0.0.0.0') host = '127.0.0.1';
+  if (host === '::') host = '::1';
+  const port = Number.isInteger(Number(server.port)) && Number(server.port) > 0 ? Number(server.port) : 21000;
+  const scheme = cfg?.tls === false || server.tls?.enabled === false ? 'http' : 'https';
+  return `${scheme}://${host.includes(':') ? `[${host}]` : host}:${port}/api/mining?node=main`;
 }
 
-console.log(`pools: ${map.pools.length}  matchers: ${map.matchers.length}  sha256: ${map.sourceSha256.slice(0, 12)}`);
-if (observed) console.log(`coverage of the ${observed.blocks} attributed blocks: ${observed.labelled} matched a curated tag, ${observed.unknown} keep their raw tag\n  ${observed.labelSource ?? ''}`);
-else console.log(`coverage: not measured (${coverageError}) -- reported as unknown rather than assumed`);
-if (checkOnly) process.exit(0);
+async function main() {
+  const argAfter = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] ?? null : null);
+  const content = asFile ? fs.readFileSync(asFile, 'utf8') : await fetchContent();
+  try { checkExpectedSha(content, argAfter('--expect-sha256')); } catch (err) { console.error(err.message); process.exit(1); }
+  const map = build(content, asFile ? `file:${path.basename(asFile)}` : URL_);
 
-fs.mkdirSync(path.dirname(OUT), { recursive: true });
-const tmp = `${OUT}.tmp`;
-fs.writeFileSync(tmp, `${JSON.stringify(map, null, 1)}\n`);
-fs.renameSync(tmp, OUT);
-console.log(`wrote ${path.relative(ROOT, OUT)}`);
+  // What we are actually seeing right now, so the coverage number is measured and not
+  // assumed. Read live from the running monitor if it answers; otherwise say it is unknown.
+  let observed = null;
+  let coverageError = null;
+  try {
+    let cfg;
+    try { cfg = loadConfig(); } catch { cfg = { server: { port: Number(process.env.BLOCKYARD_PORT) || 21000 } }; }
+    const url = coverageUrl(cfg);
+    // Same family:4 path as the fetch above, plus the box's own CA: the monitor serves TLS
+    // from a local CA that is not in the system trust store, and "could not verify" is a
+    // different fact from "could not reach".
+    const caFile = process.env.BLOCKYARD_CA_FILE ?? null;   // a CA file, only where the fetch needs a private one
+    const extra = caFile && fs.existsSync(caFile) ? { ca: fs.readFileSync(caFile) } : {};
+    const body = url.startsWith('https:') ? await getOverHttps(url, 0, extra) : await (await fetch(url)).text();
+    const d = JSON.parse(body);
+    const rows = d.recent ?? [];
+    const hit = rows.filter((r) => map.matchers.some((m) => normalizeText(`${r.rawCoinbase ? Buffer.from(r.rawCoinbase, 'hex').toString('utf8') : ''} ${r.tagText || ''}`).includes(m.tagNorm))).length;
+    observed = {
+      blocks: rows.length, labelled: hit, unknown: rows.filter((r) => !r.poolLabel).length,
+      labelSource: d.labelSource ? `labels from ${d.labelSource.source} @ ${(d.labelSource.sha256 || '').slice(0, 10)}` : 'no map loaded by the monitor yet',
+    };
+  } catch (err) {
+    coverageError = err?.message ?? String(err);
+  }
+
+  console.log(`pools: ${map.pools.length}  matchers: ${map.matchers.length}  sha256: ${map.sourceSha256}`);
+  if (observed) console.log(`coverage of the ${observed.blocks} attributed blocks: ${observed.labelled} matched a curated tag, ${observed.unknown} keep their raw tag\n  ${observed.labelSource ?? ''}`);
+  else console.log(`coverage: not measured (${coverageError}) -- reported as unknown rather than assumed`);
+
+  // THE DIFF BEFORE THE WRITE (2026-09-16, audit L15): against the file this replaces, or, when
+  // there is none yet, the shipped config/pool-map.json the monitor uses until then.
+  const shipped = path.join(ROOT, 'config', 'pool-map.json');
+  const replacing = fs.existsSync(OUT);
+  const prevFile = replacing ? OUT : fs.existsSync(shipped) ? shipped : null;
+  let prev = null;
+  if (prevFile) { try { prev = JSON.parse(fs.readFileSync(prevFile, 'utf8')); } catch { prev = null; } }
+  if (prev) {
+    const names = new Map([...(prev.pools ?? []), ...map.pools].map((p) => [p.key, p.name]));
+    console.log(`against ${path.relative(ROOT, prevFile)}${prev.sourceSha256 ? ` (sha256 ${prev.sourceSha256.slice(0, 12)})` : ''}:`);
+    console.log(formatDiff(diffPoolMaps(prev, map), (k) => names.get(k) ?? k));
+  }
+  if (checkOnly) process.exit(0);
+
+  if (replacing && !args.includes('--yes')) {
+    if (!process.stdin.isTTY) { console.log(`not written: ${path.relative(ROOT, OUT)} exists; pass --yes to replace it`); process.exit(1); }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const a = (await rl.question(`replace ${path.relative(ROOT, OUT)}? (y/N) `)).trim().toLowerCase();
+    rl.close();
+    if (!a.startsWith('y')) { console.log('not written'); process.exit(1); }
+  }
+
+  fs.mkdirSync(path.dirname(OUT), { recursive: true });
+  const tmp = `${OUT}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(map, null, 1)}\n`);
+  fs.renameSync(tmp, OUT);
+  console.log(`wrote ${path.relative(ROOT, OUT)}`);
+}
+
+// run only as a script, so the tests can import the pieces without a fetch
+if (process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1])) {
+  main().catch((err) => { console.error(err?.message ?? err); process.exit(1); });
+}