@a11ign/screenreader-fleet 0.0.0-reserved.0 → 0.2.0

package/dist/code-drift.mjs

@@ -0,0 +1,284 @@
+// @ts-check
+/**
+ * Compare a fleet's `/health.code` readings against an EXPECTED hash, and describe the result — the half
+ * of `worker-code-check.mjs` that has no opinion about what "expected" means.
+ *
+ * Split out on 2026-09-05 so a SECOND caller could reach it. `worker-code-check.mjs`'s `expectedWorkerCode`
+ * imports `codeVersion`/`workerSourceDir` through a SUBPATH export (`@a11ign/screenreader-worker/code-version`)
+ * rather than a relative path, because a relative one drags `nvda-worker`'s `.mjs` files into
+ * `worker-fleet`'s own tsc project and the build dies with TS5055 ("would overwrite input file"). That
+ * subpath resolves through `node_modules` — fine for `worker-fleet`, which is a normal installed package,
+ * and fatal for `packages/control`, which runs from a raw git checkout with none (ADR 0012):
+ * `control-has-no-dependencies.test.ts` walks every import reachable from there and refuses exactly this
+ * shape. So the two constraints — no TS5055 here, no `node_modules` there — cannot both be satisfied by one
+ * import line in one file, and this file exists to be the copy neither constraint touches: every function
+ * below takes `expected` as a plain string, computed by whichever caller can safely reach a hasher.
+ *
+ * It imports `node:child_process` and, for `readWorkerCode`, this package's own `./worker-http.mjs` —
+ * relative, and itself importing nothing but `node:http`/`node:https`, so it resolves without
+ * `node_modules` exactly like this file already does. Verified against
+ * `control-has-no-dependencies.test.ts` before relying on it, since "should resolve" and "does resolve" are
+ * different claims and this file's whole reason for existing is being the copy the second one has to hold
+ * for. `fetch` (a global, needing no import) is what it replaced, kept out for the reason
+ * `worker-http.mjs`'s own header gives: undici silently caps the wait for response headers at ~300 s
+ * regardless of an `AbortSignal`, which this file's own question — does the fleet run this checkout — must
+ * never answer wrongly because of a truncated response.
+ *
+ * `lab-job.mjs` is that second caller — it needs this BEFORE dispatching to the lab at all, from
+ * `packages/control`, which cannot import `worker-code-check.mjs` directly for the reason above.
+ */
+import { execFileSync } from "node:child_process";
+import { sandboxGitEnv } from "./git-safe-env.mjs";
+import { requestJson } from "./worker-http.mjs";
+/** How long a worker gets to answer `/health`. Matches `check-worker-code.mjs`: a cold Windows box needs it. */
+const HEALTH_TIMEOUT_MS = 15_000;
+/**
+ * Split a set of `/health.code` readings into stale and unreachable. PURE.
+ *
+ * `null` is UNREACHABLE and is not a finding, matching `assertOneBrowserAcross`: a box that is asleep
+ * contributes no evidence and no mismatch, and treating silence as a fault is how a check earns a
+ * reputation for crying wolf. `"absent"` IS a finding — a worker predating `/health.code` is itself a
+ * stale deploy.
+ *
+ * `answered` is returned rather than left to be inferred from the two lists, because "nothing was wrong"
+ * and "nothing was examined" produce the SAME empty `stale` — and a caller with only the lists cannot
+ * distinguish 3 clean workers from 3 silent ones. Every number carrying what it was computed from is this
+ * file's parent rule; this is the one number that was missing.
+ *
+ * @param {string} expected
+ * @param {Array<{worker: string, code: string|null|undefined}>} readings
+ * @returns {{expected: string, stale: Array<{worker: string, serving: string}>, unreachable: string[],
+ *            answered: number}}
+ */
+export function codeDrift(expected, readings) {
+    const stale = [];
+    const unreachable = [];
+    let answered = 0;
+    for (const reading of readings ?? []) {
+        const code = reading?.code;
+        if (code === null || code === undefined) {
+            unreachable.push(reading?.worker);
+            continue;
+        }
+        answered += 1;
+        if (code !== expected)
+            stale.push({ worker: reading.worker, serving: String(code) });
+    }
+    return { expected, stale, unreachable, answered };
+}
+/**
+ * Name the deploy route that can actually reach these workers.
+ *
+ * There are two, they share no mechanism, and the wrong one wastes real time. `worker:deploy` is
+ * `utmctl file push` plus a `utmctl` reboot: it takes a VM UUID and fails immediately off macOS, so it
+ * cannot touch a physical box. Bare-metal workers are git-cloned and deploy by PULLING, through Ansible.
+ *
+ * This printed the utmctl advice unconditionally, including to a fleet of four mini PCs where none of it
+ * applies — a tool confidently prescribing a remedy for a different kind of machine. Which kind a worker is
+ * is not a guess: `inventory.yml` is the single source of truth for the bare-metal fleet (ADR 0012).
+ *
+ * PURE, and the bare-metal list is a parameter rather than a read, because a remedy that only appears when
+ * something is already broken is one nobody sees until it matters. This repo has shipped an inert remedy
+ * before (`refreshBrowseBuffer`, whose trigger was never set) and confirmed it by results it had no part in
+ * producing. Returning lines makes both branches assertable with nothing stale and no fleet.
+ *
+ * @param {string[]} staleUrls
+ * @param {string[]} bareMetalUrls
+ * @returns {string[]}
+ */
+export function remedyLines(staleUrls, bareMetalUrls) {
+    const bareMetal = new Set(bareMetalUrls);
+    const physical = staleUrls.filter((u) => bareMetal.has(u));
+    const vms = staleUrls.filter((u) => !bareMetal.has(u));
+    const lines = [`\n${staleUrls.length} stale worker(s).`];
+    if (physical.length) {
+        lines.push(`\n  ${physical.length} in inventory.yml — bare metal, so they deploy by PULLING:`, "    npm run fleet:deploy", "  `npm run worker:deploy` cannot reach these: it is utmctl, keyed on a VM UUID.");
+    }
+    if (vms.length) {
+        lines.push(`\n  ${vms.length} not in inventory.yml — local VM(s). A restart via \`utmctl exec\``, "  silently does nothing on some guests; rebooting always picks up a pushed file:", "    npm run worker:deploy");
+    }
+    return lines;
+}
+/**
+ * The refusal text, or `null` when the fleet is running this checkout. PURE.
+ *
+ * Every number it reports carries what it was computed from, which is this file's parent rule: the hash,
+ * which side is dirty, and how many boxes were silent rather than merely absent from the count.
+ *
+ * @param {{expected: string, stale: Array<{worker: string, serving: string}>, unreachable: string[],
+ *           answered?: number}} drift
+ * @param {{when?: string, bareMetalUrls?: string[], sourceDirty?: string}} options
+ * @returns {string|null}
+ */
+export function describeCodeDrift(drift, { when = "before the run", bareMetalUrls = [], sourceDirty = "" } = {}) {
+    // A FLEET NOBODY COULD REACH IS NOT A CLEAN FLEET. `describeEmptyPool` below makes exactly this
+    // argument for `workers.length === 0` -- "an affirmative claim about a fleet it had not looked at" --
+    // and the identical condition arrives by a second path when the pool is full and every box is silent:
+    // `stale` is empty because nothing was COMPARED, not because everything matched, so this returned null
+    // and the caller printed "Fleet runs this checkout (worker code …, 0 of 5 worker(s) checked)".
+    //
+    // A remedy that reaches one of several paths, in the module whose own header names that shape.
+    //
+    // Silence is NOT a per-worker finding -- a box asleep contributes no mismatch, and treating that as a
+    // fault is how a check earns a reputation for crying wolf. The judgement is about the WHOLE reading:
+    // some answered, so the ones that did not are context; none answered, so there is no reading at all.
+    if (drift?.answered === 0 && drift?.unreachable?.length) {
+        return [
+            "",
+            `REFUSING to vouch for the fleet ${when}: ${drift.unreachable.length} worker(s) were asked and NONE`,
+            `answered, so nothing was compared against this checkout (${drift.expected}).`,
+            ...drift.unreachable.map((w) => `  ${w}`),
+            "",
+            "This is not a clean fleet, it is an unexamined one. A capture is about to dispatch to these boxes,",
+            "so silence here is a broken invocation rather than a pass. Common causes: the fleet is powered",
+            "down (npm run fleet:status), or a deploy just rebooted it and nothing waited.",
+            "",
+            "Or pass --allow-stale-workers if you know something this check does not.",
+            "",
+        ].join("\n");
+    }
+    if (!drift?.stale?.length)
+        return null;
+    const lines = [
+        `\nFLEET IS NOT RUNNING THIS CHECKOUT ${when}.`,
+        `This checkout expects worker code ${drift.expected}; ${drift.stale.length} worker(s) serve something else:`,
+        ...drift.stale.map(({ worker, serving }) => `  ${worker}  ${serving}`),
+    ];
+    if (drift.unreachable.length) {
+        // Counted and named, because "3 of 4 agreed" and "3 of 4 answered" are different sentences and only
+        // one of them is reassuring.
+        lines.push(`  (${drift.unreachable.length} worker(s) did not answer and were not judged: `
+            + `${drift.unreachable.join(", ")})`);
+    }
+    lines.push("", "A capture stamps the commit the LAB is at, and nothing downstream keys on the worker's code —", "`workerCode` is outside the cache key on purpose — so evidence taken by a stale worker is", "indistinguishable from current evidence for ever after.");
+    if (sourceDirty) {
+        // The odd one out is HERE, so the remedy is the opposite one. Getting this backwards ships
+        // uncommitted work to twelve machines, and a CAPTURE_PROTOCOL_VERSION bump among it would invalidate
+        // every cached capture — the trap `worker:code` already warns about, arriving through this door.
+        lines.push("", "But the drift is on THIS side: the worker source in this checkout is modified against HEAD —", `  ${sourceDirty}`, "so the fleet may be perfectly current and deploying would ship uncommitted work. Commit or revert", "first, then re-check. Do not reach for the remedy below until this is clean.");
+    }
+    lines.push(...remedyLines(drift.stale.map((s) => s.worker), bareMetalUrls));
+    lines.push("", "Or pass --allow-stale-workers if you know something this check does not; it will say so in", "the output rather than passing quietly.");
+    return `${lines.join("\n")}\n`;
+}
+/** What a single worker is serving, or `null` when it did not answer. */
+/** @param {string} url */
+export async function readWorkerCode(url) {
+    try {
+        // `requestJson`, not `fetch` -- see worker-http.mjs's own header: undici silently caps the wait for
+        // response headers at ~300 s regardless of an AbortSignal, and this file exists to answer a question
+        // (does the fleet run this checkout) that a truncated response must never answer wrongly. `requestJson`
+        // imports only `node:http`/`node:https`, so pulling it in here does not add anything `packages/control`
+        // could not already resolve from a raw checkout -- verified against
+        // `control-has-no-dependencies.test.ts` rather than assumed, since this file's whole reason for existing
+        // is being the copy that constraint reaches.
+        const response = await requestJson(`${String(url).replace(/\/$/, "")}/health`, { timeoutMs: HEALTH_TIMEOUT_MS });
+        // `undefined` on unparseable JSON (requestJson's contract) is folded into the same "did not answer"
+        // path as a network failure below, via the throw -- matching fetch's `.json()`, which threw here too.
+        if (response.json === undefined)
+            throw new Error(`invalid JSON from ${url}`);
+        // "absent" rather than null: a worker that answers without a code field predates `/health.code`,
+        // which is a stale deploy and must not be filed under "did not answer".
+        return response.json.code ?? "absent";
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is the worker source in `sourceDir` modified against HEAD?
+ *
+ * The DIRECTORY IS THE CALLER'S, never a path guessed here: this file is reached from `control` (which asks
+ * `layer-checkouts.mjs`) and from `worker-fleet` (which asks the worker package by name), and a guessed
+ * monorepo path would read the wrong tree the day the layer lives in another repository (#3394).
+ *
+ * Guarded, exactly like `protocolBumpNote`: outside a git checkout there is simply nothing to add, and a
+ * precondition that throws because `git` is missing is worse than the drift it was checking for.
+ *
+ * @param {string} sourceDir
+ */
+export function workerSourceDirty(sourceDir) {
+    // Outside the `try`: a missing directory is a caller's bug, and the catch below would turn it into "clean".
+    if (typeof sourceDir !== "string" || !sourceDir) {
+        throw new TypeError("workerSourceDirty needs the worker source directory to read; there is no default");
+    }
+    try {
+        return execFileSync("git", ["-C", sourceDir, "status", "--porcelain", "--", "."], { encoding: "utf8", env: sandboxGitEnv() }).trim().split("\n").filter(Boolean).join("; ");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * AN EMPTY POOL IS NOT A CLEAN FLEET — the refusal, as a value, so it can be tested without exiting.
+ *
+ * `assertFleetRunsThisCheckout([])` used to print "Fleet runs this checkout (worker code …, 0 worker(s)
+ * checked)" and return: an affirmative claim about a fleet it had not looked at. The count sitting in the
+ * sentence is the only reason that was ever arguable, and "0 worker(s) checked" under a heading saying the
+ * fleet is fine is precisely how "verified" comes to mean "unexamined".
+ *
+ * REFUSED, not reported-and-continued. The pre-push hook's loud skip is right for `runs/`, whose absence is
+ * legitimate; an empty pool at a capture boundary never is. Both callers pass a pool a capture is about to
+ * dispatch to, so failing here with a named cause beats failing later as "0 captured".
+ *
+ * Returned rather than written, and that split is this file's own convention: the classification and the
+ * message are pure and driven directly by the tests, because a function that calls `process.exit` cannot be
+ * asserted on without stubbing the runtime out from under it.
+ *
+ * @param {string[] | undefined} workers
+ * @param {string} expected
+ * @returns {string | null} the refusal, or null when there is a pool to check
+ */
+export function describeEmptyPool(workers, expected) {
+    if (workers?.length)
+        return null;
+    return "REFUSING to vouch for the fleet: no workers were given, so nothing was compared against this "
+        + `checkout (${expected}). A capture dispatches to workers, so an empty pool is a broken invocation `
+        + "rather than a clean fleet — check A11Y_WORKER(S), the local pool, or inventory.yml.\n";
+}
+/**
+ * Refuse to run against a fleet that is not serving `expected` — the shared body of
+ * `assertFleetRunsThisCheckout`, taking the hash as a parameter rather than computing it.
+ *
+ * That split is the whole reason this function exists rather than living only in `worker-code-check.mjs`:
+ * computing `expected` needs `codeVersion`/`workerSourceDir`, and reaching those from `packages/control`
+ * cannot go through a relative path (TS5055 in `worker-fleet`'s own build) or a package-name import (no
+ * `node_modules` on the control plane, ADR 0012) at once — see this file's header. So the CALLER computes
+ * `expected` however it can safely reach a hasher, and this function starts from the answer.
+ *
+ * Exits 3, matching `assertOneBrowserAcross`: a precondition the operator must act on, distinct from 1
+ * (captures failed) and 2 (the request was malformed).
+ *
+ * @param {string} expected
+ * @param {string[]} workers
+ * `sourceDir` is the worker source the `expected` hash was computed over, so a dirty tree is read from the
+ * same place the hash came from.
+ *
+ * @param {{when?: string, allow?: boolean, read?: (url: string) => Promise<string|null>, bareMetalUrls?: string[], sourceDir: string}} options
+ */
+export async function assertWorkersServe(expected, workers, options) {
+    const { when = "before the run", allow = false, read = readWorkerCode, bareMetalUrls = [], sourceDir } = options;
+    if (allow) {
+        process.stdout.write("--allow-stale-workers: NOT checking that the fleet runs this checkout.\n");
+        return;
+    }
+    const empty = describeEmptyPool(workers, expected);
+    if (empty) {
+        process.stderr.write(empty);
+        process.exit(3);
+    }
+    const readings = await Promise.all(workers.map(async (worker) => ({ worker, code: await read(worker) })));
+    const drift = codeDrift(expected, readings);
+    const refusal = describeCodeDrift(drift, { when, bareMetalUrls, sourceDirty: workerSourceDirty(sourceDir) });
+    if (!refusal) {
+        // Says it CHECKED, not merely that nothing was wrong. A silent pass and a check that never ran look
+        // identical from the outside, which is the `refreshBrowseBuffer` lesson applied to a precondition.
+        process.stdout.write(`Fleet runs this checkout (worker code ${expected}, `
+            + `${drift.unreachable.length ? `${readings.length - drift.unreachable.length} of ` : ""}`
+            + `${readings.length} worker(s) checked).\n`);
+        return;
+    }
+    process.stderr.write(refusal);
+    process.exit(3);
+}
+//# sourceMappingURL=code-drift.mjs.map

package/dist/code-drift.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-drift.mjs","sourceRoot":"","sources":["../src/code-drift.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,gHAAgH;AAChH,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEjC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,QAAQ,EAAE,QAAQ;IAC1C,MAAM,KAAK,GAAG,EAAE,CAAC;IACjB,MAAM,WAAW,GAAG,EAAE,CAAC;IACvB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,OAAO,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;QAC3B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACxC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAClC,SAAS;QACX,CAAC;QACD,QAAQ,IAAI,CAAC,CAAC;QACd,IAAI,IAAI,KAAK,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CAAC,SAAS,EAAE,aAAa;IAClD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,CAAC,KAAK,SAAS,CAAC,MAAM,mBAAmB,CAAC,CAAC;IAEzD,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,MAAM,4DAA4D,EAC3F,0BAA0B,EAC1B,iFAAiF,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,MAAM,oEAAoE,EAC9F,kFAAkF,EAClF,2BAA2B,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAK,EAAE,EAAE,IAAI,GAAG,gBAAgB,EAAE,aAAa,GAAG,EAAE,EAAE,WAAW,GAAG,EAAE,EAAE,GAAG,EAAE;IAC7G,gGAAgG;IAChG,sGAAsG;IACtG,sGAAsG;IACtG,uGAAuG;IACvG,+FAA+F;IAC/F,EAAE;IACF,+FAA+F;IAC/F,EAAE;IACF,sGAAsG;IACtG,qGAAqG;IACrG,qGAAqG;IACrG,IAAI,KAAK,EAAE,QAAQ,KAAK,CAAC,IAAI,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;QACxD,OAAO;YACL,EAAE;YACF,mCAAmC,IAAI,KAAK,KAAK,CAAC,WAAW,CAAC,MAAM,gCAAgC;YACpG,4DAA4D,KAAK,CAAC,QAAQ,IAAI;YAC9E,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,EAAE;YACF,oGAAoG;YACpG,gGAAgG;YAChG,+EAA+E;YAC/E,EAAE;YACF,0EAA0E;YAC1E,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,KAAK,GAAG;QACZ,wCAAwC,IAAI,GAAG;QAC/C,qCAAqC,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM,kCAAkC;QAC5G,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,KAAK,MAAM,KAAK,OAAO,EAAE,CAAC;KACvE,CAAC;IACF,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;QAC7B,oGAAoG;QACpG,6BAA6B;QAC7B,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,WAAW,CAAC,MAAM,iDAAiD;cACtF,GAAG,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,+FAA+F,EAC5G,2FAA2F,EAC3F,yDAAyD,CAAC,CAAC;IAE7D,IAAI,WAAW,EAAE,CAAC;QAChB,2FAA2F;QAC3F,qGAAqG;QACrG,iGAAiG;QACjG,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,8FAA8F,EAC3G,KAAK,WAAW,EAAE,EAClB,mGAAmG,EACnG,8EAA8E,CAAC,CAAC;IACpF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,4FAA4F,EACzG,yCAAyC,CAAC,CAAC;IAC7C,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,yEAAyE;AACzE,0BAA0B;AAC1B,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAG;IACtC,IAAI,CAAC;QACH,oGAAoG;QACpG,qGAAqG;QACrG,wGAAwG;QACxG,wGAAwG;QACxG,oEAAoE;QACpE,yGAAyG;QACzG,6CAA6C;QAC7C,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC,CAAC;QACjH,oGAAoG;QACpG,sGAAsG;QACtG,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;QAC7E,iGAAiG;QACjG,wEAAwE;QACxE,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAS;IACzC,4GAA4G;IAC5G,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,kFAAkF,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,CAAC,EAC9E,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAO,EAAE,QAAQ;IACjD,IAAI,OAAO,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,+FAA+F;UAClG,aAAa,QAAQ,8EAA8E;UACnG,uFAAuF,CAAC;AAC9F,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO;IACjE,MAAM,EAAE,IAAI,GAAG,gBAAgB,EAAE,KAAK,GAAG,KAAK,EAAE,IAAI,GAAG,cAAc,EAAE,aAAa,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACjH,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0EAA0E,CAAC,CAAC;QACjG,OAAO;IACT,CAAC;IACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACnD,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAC9D,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC7G,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,oGAAoG;QACpG,mGAAmG;QACnG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yCAAyC,QAAQ,IAAI;cACtE,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;cACxF,GAAG,QAAQ,CAAC,MAAM,wBAAwB,CAAC,CAAC;QAChD,OAAO;IACT,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/command-line-census.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Every `.mjs` under the tree's known CLI roots, no predicate applied — the population itself, for a
+ * caller to classify by whatever question is theirs.
+ *
+ * @param {string} repoRoot absolute path to the repository root
+ * @returns {string[]} repo-relative paths, unsorted (discovery order)
+ */
+export function allMjsFiles(repoRoot: string): string[];
+/**
+ * Does this file read argv? Comments stripped first, and that is not a nicety: matching raw source
+ * classified a module as a CLI merely because a COMMENT mentioned `process.argv` — measured on
+ * `gates/dispatch.mjs`, a library whose comment said it deliberately does NOT read `process.argv`. This
+ * repo's own rule: a check must not derive its expectations from source TEXT, because text includes the
+ * prose about the code as well as the code.
+ *
+ * Excludes `cli-flags.mjs` itself, the guard's OWN definition, which mentions `process.argv` in its
+ * implementation without being a command line for anything to classify.
+ *
+ * @param {string} rel repo-relative path
+ * @param {string} repoRoot absolute path to the repository root
+ * @returns {boolean}
+ */
+export function readsArgv(rel: string, repoRoot: string): boolean;
+/**
+ * `allMjsFiles()` filtered to the ones that read argv — the population `cli-flags.test.ts`'s flag-guard
+ * census classifies. NOT the same question as "is this a runnable command with an entry-point guard";
+ * see this file's own header for why those stay two predicates over one walk rather than one.
+ *
+ * @param {string} repoRoot absolute path to the repository root
+ * @returns {string[]}
+ */
+export function commandLineModules(repoRoot: string): string[];
+//# sourceMappingURL=command-line-census.d.mts.map

package/dist/command-line-census.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-line-census.d.mts","sourceRoot":"","sources":["../src/command-line-census.mjs"],"names":[],"mappings":"AAmCA;;;;;;GAMG;AACH,sCAHW,MAAM,GACJ,MAAM,EAAE,CAkBpB;AAED;;;;;;;;;;;;;GAaG;AACH,+BAJW,MAAM,YACN,MAAM,GACJ,OAAO,CAMnB;AAED;;;;;;;GAOG;AACH,6CAHW,MAAM,GACJ,MAAM,EAAE,CAIpB"}

package/dist/command-line-census.mjs

@@ -0,0 +1,96 @@
+// @ts-check
+/**
+ * Every `.mjs` under this repo's known CLI roots — DISCOVERED by walking the tree, never a hand-typed list.
+ *
+ * Extracted from `cli-flags.test.ts` (A2, #453) so a SECOND consumer with a DIFFERENT question about the
+ * same population reuses the walk rather than re-deriving it — the identical shape `preInstallEntries()`
+ * and `busy-worker-guard.test.ts` already follow, and the one this repo's own rule names: *"delete a copy,
+ * or derive one from the other"* ranks above a second independent `readdirSync` walk of the same tree that
+ * could silently narrow from this one's (a different root list, a missed `node_modules` exclusion).
+ *
+ * `allMjsFiles()` is the WALK ALONE, with no predicate applied — deliberately, because "reads argv" and
+ * "is a runnable command" are DIFFERENT questions over an overlapping but non-identical population.
+ * `cli-flags.test.ts` filters this walk with `readsArgv()` to classify flag-guard coverage; a consumer
+ * asking "does this file declare the `if (import.meta.url === ...) main()` entry-point guard" (docs
+ * generation, say) filters the SAME walk with its own predicate instead of importing `readsArgv` and
+ * getting the wrong population — a script can guard `main()` with no flags at all (nothing to read from
+ * argv), and in principle a pre-install script reads `process.argv` at import time with no guard at all.
+ * Sharing the walk and NOT the predicate is what keeps those two questions from being silently conflated.
+ *
+ * A CONSUMER OF THIS FILE ALREADY HAS `node_modules` AND A BUILD. `cli-flags.mjs` itself deliberately
+ * imports nothing but `node:path`/`node:fs`/`node:url`, because scripts like `auto-arm-sweep.mjs` are
+ * invoked by a workflow job with only `actions/checkout` -- no `npm ci`, no `dist` (#330/#331). This file
+ * is NOT that kind of dependency: `stripComments` is a real workspace import
+ * (`@a11ign/evidence/source-text`), so anything importing THIS module needs to run where that package's
+ * `dist` exists -- a test file, or tooling invoked after `npm run build`. Keeping `cli-flags.mjs` itself
+ * free of that import is why this is a sibling file rather than an addition to it.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stripComments } from "@a11ign/evidence/source-text";
+/** Every top-level directory a `.mjs` command line can live under, relative to the repo root. */
+const ROOTS = ["scripts", ...["packages/lab", "packages/worker-fleet"]
+        .flatMap((pkg) => ["src", "scripts"].map((sub) => `${pkg}/${sub}`))];
+/**
+ * Every `.mjs` under the tree's known CLI roots, no predicate applied — the population itself, for a
+ * caller to classify by whatever question is theirs.
+ *
+ * @param {string} repoRoot absolute path to the repository root
+ * @returns {string[]} repo-relative paths, unsorted (discovery order)
+ */
+export function allMjsFiles(repoRoot) {
+    const found = /** @type {string[]} */ ([]);
+    /** @param {string} dir */
+    const walk = (dir) => {
+        for (const entry of readdirSync(join(repoRoot, dir), { withFileTypes: true })) {
+            const rel = `${dir}/${entry.name}`;
+            if (entry.isDirectory() && entry.name !== "node_modules")
+                walk(rel);
+            else if (!entry.isDirectory() && rel.endsWith(".mjs"))
+                found.push(rel);
+        }
+    };
+    for (const root of ROOTS) {
+        // A package without a `scripts/` directory is not a fault; anything else is, and must not be swallowed.
+        try {
+            statSync(join(repoRoot, root));
+        }
+        catch {
+            continue;
+        }
+        walk(root);
+    }
+    return found;
+}
+/**
+ * Does this file read argv? Comments stripped first, and that is not a nicety: matching raw source
+ * classified a module as a CLI merely because a COMMENT mentioned `process.argv` — measured on
+ * `gates/dispatch.mjs`, a library whose comment said it deliberately does NOT read `process.argv`. This
+ * repo's own rule: a check must not derive its expectations from source TEXT, because text includes the
+ * prose about the code as well as the code.
+ *
+ * Excludes `cli-flags.mjs` itself, the guard's OWN definition, which mentions `process.argv` in its
+ * implementation without being a command line for anything to classify.
+ *
+ * @param {string} rel repo-relative path
+ * @param {string} repoRoot absolute path to the repository root
+ * @returns {boolean}
+ */
+export function readsArgv(rel, repoRoot) {
+    if (!rel.endsWith(".mjs"))
+        return false;
+    const source = stripComments(readFileSync(join(repoRoot, rel), "utf8"));
+    return source.includes("process.argv") && !source.includes("export function refuseUnknownFlags");
+}
+/**
+ * `allMjsFiles()` filtered to the ones that read argv — the population `cli-flags.test.ts`'s flag-guard
+ * census classifies. NOT the same question as "is this a runnable command with an entry-point guard";
+ * see this file's own header for why those stay two predicates over one walk rather than one.
+ *
+ * @param {string} repoRoot absolute path to the repository root
+ * @returns {string[]}
+ */
+export function commandLineModules(repoRoot) {
+    return allMjsFiles(repoRoot).filter((rel) => readsArgv(rel, repoRoot));
+}
+//# sourceMappingURL=command-line-census.mjs.map

package/dist/command-line-census.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-line-census.mjs","sourceRoot":"","sources":["../src/command-line-census.mjs"],"names":[],"mappings":"AAAA,YAAY;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,iGAAiG;AACjG,MAAM,KAAK,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,cAAc,EAAE,uBAAuB,CAAC;SACnE,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,QAAQ;IAClC,MAAM,KAAK,GAAG,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3C,0BAA0B;IAC1B,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,EAAE;QACnB,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9E,MAAM,GAAG,GAAG,GAAG,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc;gBAAE,IAAI,CAAC,GAAG,CAAC,CAAC;iBAC/D,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzE,CAAC;IACH,CAAC,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,wGAAwG;QACxG,IAAI,CAAC;YAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,GAAG,EAAE,QAAQ;IACrC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,MAAM,GAAG,aAAa,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE,OAAO,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,oCAAoC,CAAC,CAAC;AACnG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAQ;IACzC,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;AACzE,CAAC"}

package/dist/compare-workers.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=compare-workers.d.mts.map

package/dist/compare-workers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-workers.d.mts","sourceRoot":"","sources":["../src/compare-workers.mjs"],"names":[],"mappings":""}