@a11ign/screenreader-fleet 0.4.0 → 0.4.2

package/dist/compare-workers.d.mts

@@ -1,2 +1,18 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Where the report is written: under the caller's `--runs-dir=`, else the monorepo's own `runs/`, else a refusal naming
+ * the directory and the flag (a11ign/a11ign#3767).
+ *
+ * Resolved from THIS module, never the cwd -- same reason as `doctor.mjs`'s `runsDirFor`, which this duplicates because
+ * this package cannot import `@a11ign/lab`'s canonical `runs/` resolution without a dependency cycle. From an INSTALLED
+ * package `../../../` is `node_modules`, so the default would write the report under the dependency. A supplied
+ * directory need not exist: the report's own `mkdirSync` makes it, which is what asking for one means.
+ * `baseDir` is INJECTED so a test can stand in for either layout.
+ *
+ * @param {{ argv?: readonly string[], baseDir?: string }} [options]
+ * @returns {string}
+ */
+export function outDirFor({ argv, baseDir }?: {
+    argv?: readonly string[];
+    baseDir?: string;
+}): string;

package/dist/compare-workers.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
 import { describeProbe, probeHealth, WORKER_PROBE_TIMEOUT_MS } from "./probe-outcome.mjs";
 import { CAPTURE_CLIENT_TIMEOUT_MS, requestJson } from "./worker-http.mjs";
-import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
 async function refuseIfBusy(workers, { what, timeoutMs = WORKER_PROBE_TIMEOUT_MS, request }) {
     const states = await Promise.all(workers.map(async (worker)=>{
         const probe = await probeHealth(worker, {
@@ -221,12 +221,22 @@ function diffHost(before, after) {
 }
 refuseUnknownFlags([
     "--rounds=",
-    "--runs="
+    "--runs=",
+    "--runs-dir="
 ], {
     entry: import.meta.url,
     command: "npm run worker:compare"
 });
-const OUT = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "runs/worker-compare");
+const MODULE_DIR = fileURLToPath(new URL(".", import.meta.url));
+const isMonorepoRoot = (root)=>existsSync(resolve(root, "packages")) && existsSync(resolve(root, "package.json"));
+function outDirFor({ argv = process.argv.slice(2), baseDir = MODULE_DIR } = {}) {
+    const supplied = flagValue(argv, "runs-dir");
+    if ("" === supplied) throw new Error("worker:compare: --runs-dir= is empty. Pass --runs-dir=<the runs directory>.");
+    if (void 0 !== supplied) return resolve(supplied, "worker-compare");
+    const root = resolve(baseDir, "..", "..", "..");
+    if (isMonorepoRoot(root)) return resolve(root, "runs", "worker-compare");
+    throw new Error(`worker:compare: no runs directory: ${root} is not a checkout (this is an installed package), so there is no runs/ to write worker-compare/ under. Pass --runs-dir=<the runs directory>.`);
+}
 const MS_PER_S = 1000;
 function refuseIfRunsReadonly() {
     if ("1" !== process.env.A11Y_RUNS_READONLY) return;
@@ -234,6 +244,14 @@ function refuseIfRunsReadonly() {
     console.error("  Unset A11Y_RUNS_READONLY to run this for real.");
     process.exit(3);
 }
+function refuseUnlessOutDir() {
+    try {
+        return outDirFor();
+    } catch (error) {
+        process.stderr.write(`${error.message}\n`);
+        return process.exit(2);
+    }
+}
 const compare_workers_args = process.argv.slice(2);
 const runs = Number(compare_workers_args.find((a)=>a.startsWith("--rounds="))?.slice(9) ?? compare_workers_args.find((a)=>a.startsWith("--runs="))?.slice(7) ?? 6);
 const [page, ...compare_workers_workers] = compare_workers_args.filter((a)=>!a.startsWith("--"));
@@ -297,6 +315,7 @@ async function main() {
         process.stderr.write("usage: npm run worker:compare -- <page-url> <worker> <worker> [--rounds=6]\n");
         process.exit(2);
     }
+    const outDir = refuseUnlessOutDir();
     refuseIfRunsReadonly();
     await refuseIfBusy(compare_workers_workers, {
         what: `worker:compare against ${page}`
@@ -334,10 +353,11 @@ async function main() {
         results,
         vitalsBefore,
         vitalsAfter,
-        hostBefore
+        hostBefore,
+        outDir
     });
 }
-function report({ results, vitalsBefore, vitalsAfter, hostBefore }) {
+function report({ results, vitalsBefore, vitalsAfter, hostBefore, outDir }) {
     const allPhases = [
         ...new Set(Object.values(results).flatMap((r)=>r.phases.flatMap(Object.keys)))
     ];
@@ -355,10 +375,10 @@ function report({ results, vitalsBefore, vitalsAfter, hostBefore }) {
     const { foundations, hostAfter } = reportFoundations({
         hostBefore
     });
-    mkdirSync(OUT, {
+    mkdirSync(outDir, {
         recursive: true
     });
-    writeFileSync(resolve(OUT, "compare.json"), JSON.stringify({
+    writeFileSync(resolve(outDir, "compare.json"), JSON.stringify({
         page: page,
         rounds: runs,
         results,
@@ -368,7 +388,7 @@ function report({ results, vitalsBefore, vitalsAfter, hostBefore }) {
         hostBefore,
         hostAfter
     }, null, 2) + "\n", "utf8");
-    process.stdout.write(`\nReport: ${resolve(OUT, "compare.json")}\n`);
+    process.stdout.write(`\nReport: ${resolve(outDir, "compare.json")}\n`);
 }
 function reportWallTime({ results, vitalsBefore, vitalsAfter }) {
     const wallSeconds = Object.fromEntries(compare_workers_workers.map((w)=>[
@@ -458,3 +478,4 @@ function reportFoundations({ hostBefore }) {
     };
 }
 if (import.meta.url === pathToFileURL(process.argv[1] ? realpathSync(process.argv[1]) : "").href) await main();
+export { outDirFor };

package/dist/doctor.d.mts

@@ -1,4 +1,21 @@
 #!/usr/bin/env node
+/**
+ * The `runs/` directory doctor reads the dataset from: the caller's `--runs-dir=`, else the monorepo's own `runs/`,
+ * else a refusal naming the directory and the flag (a11ign/a11ign#3767).
+ *
+ * `@a11ign/lab` owns the canonical `runs/` resolution (`packages/lab/src/dataset-paths.mjs`), but `lab` depends on
+ * `worker-fleet`, so this package cannot import it without a cycle: the same computation, duplicated (and again in
+ * `compare-workers.mjs`) rather than left cwd-anchored. From an INSTALLED package `../../../` is `node_modules`, so the
+ * default is taken only when that directory is a checkout; a missing `runs/` inside one is normal (a fresh clone).
+ * `baseDir` is INJECTED so a test can stand in for either layout.
+ *
+ * @param {{ argv?: readonly string[], baseDir?: string }} [options]
+ * @returns {string}
+ */
+export function runsDirFor({ argv, baseDir }?: {
+    argv?: readonly string[];
+    baseDir?: string;
+}): string;
 /**
  * The remedy for a failed local-pool query, as a runnable command plus the advice that is not one.
  *
@@ -14,6 +31,45 @@ export function workerControlFix(observed: string): {
     fix: string | null;
     note: string | null;
 };
+/**
+ * IS THE FLEET KEY SITTING NEXT TO 100 MB OF PACKAGES NOBODY AUDITED? — ADR 0012, checked rather than
+ * asserted.
+ *
+ * Found on 2026-08-29 to be violated on BOTH machines the ADR is about: the control plane carried 56 MB
+ * and 121 packages beside the key, and this laptop carries 103 MB beside the same key plus the lab key.
+ * The document was accurate about the intent and described a system that did not exist — which is worse
+ * than no document, because it is read as a guarantee.
+ *
+ * Reported by `doctor` because that is the command whose whole promise is that every check names its own
+ * fix, and because a check nobody runs is one this repo has learned not to write.
+ */
+/**
+ * IS THIS CHECKOUT MARKED AS THE PRIMARY, and does that match what it looks like?
+ *
+ * The primary-checkout guards (`pre-commit`, `post-checkout`) are OPT-IN as of #198: they fire only where
+ * `git config --local a11y.primaryCheckout` is `true`. That is the correct default — inferring it from
+ * `.git` being a directory made the hook fire on the lab, which is an ordinary clone, and broke every
+ * `lab:job -e ref=<branch>`.
+ *
+ * But an opt-in guard nobody can find the switch for is an OFF guard, and "unmarked" must not read the
+ * same as "safe". So this reports the state on every run rather than only when something is wrong — the
+ * `isolation` check above takes the same shape for the same reason: a debt that is reported every run is
+ * a known one, and a debt reported never is a forgotten one.
+ *
+ * ADVISORY, never a hard failure. `doctor` exits 0 when a RUN can proceed, and an unmarked checkout can
+ * run perfectly well — it is the fleet-driving machine's protection that is missing, not its capability.
+ * A doctor that refused READY over this would be ignored, which is how a guard gets switched off.
+ *
+ * It does not GUESS which machine deserves the mark. `doctor` runs on laptops, worktrees, the lab and CI,
+ * and telling four of those five to mark themselves would be the #198 defect wearing an advisory's
+ * clothes. It states what is true and names the command; the operator decides.
+ */
+export function checkPrimaryCheckoutMark({ baseDir }?: {
+    baseDir?: string | undefined;
+}): void;
+export function checkControlPlaneIsolation({ baseDir }?: {
+    baseDir?: string | undefined;
+}): void;
 /**
  * Pure: does `resolvedRealPath` (already realpath'd) live under `thisCheckoutRoot` (also realpath'd)?
  * Both must be realpath'd BEFORE calling this, never inside it -- comparing a symlinked path against a
@@ -59,6 +115,40 @@ export function checkoutRootFor(resolvedRealPath: string): string | null;
 export function tscProjectUpToDate(tsconfigPath: string, { run }?: {
     run?: (cmd: string, args: string[]) => string;
 }): boolean | null;
+/**
+ * WHOSE dist a cross-package import actually resolves to, and is IT stale (#256) -- both computed from
+ * the exact SPECIFIER a real import site in this repo uses, never the bare package name. CLAUDE.md's own
+ * recorded lesson: "resolving @a11ign/judge does not prove @a11ign/judge/rules came from your
+ * tree" -- a package can export subpaths from elsewhere, so resolving the root proves nothing about a
+ * subpath. `@a11ign/judge/rules` is a real specifier this repo imports
+ * (`packages/lab/scripts/score-rules.ts` and others), not a synthetic probe.
+ *
+ * ADVISORY, never a hard failure -- same reasoning as `isolation` above: a worktree resolving to the
+ * primary's dist can still run every command correctly today, and a doctor that refused READY over an
+ * environmental fact would be ignored, which is how a guard gets switched off. It is reported every run
+ * so a stale answer is a known condition, not a silent one.
+ */
+export function checkCrossPackageDist({ baseDir }?: {
+    baseDir?: string | undefined;
+}): number | void;
+/**
+ * Where the trained scorer's weights are, asked of `@a11ign/scorer` itself (a11ign/a11ign#3784).
+ *
+ * This was `../../scorer/models/...` from this module: the monorepo layout, which from an installed package points into
+ * `node_modules/@a11ign/` and answers "missing" under pnpm, where the scorer sits beside `@a11ign/judge` in the store and
+ * not beside this package. The scorer is a PEER of the judge, so it is resolved FROM the judge's real path, the one place
+ * both layouts agree it is reachable, and its own `scorerPaths()` says where its weights are ("the weights are the API").
+ * `from` is INJECTED so a test can stand in for either layout.
+ *
+ * @param {{ from?: string }} [options] a path or file URL to resolve `@a11ign/judge` from
+ * @returns {Promise<string>}
+ */
+export function scorerWeightsFor({ from }?: {
+    from?: string;
+}): Promise<string>;
+export function checkJudge({ from }?: {
+    from?: string | undefined;
+}): Promise<void>;
 /**
  * The agreement sentence, with WHICH FIELDS AGREED DERIVED rather than retyped — #1997.
  *
@@ -198,7 +288,7 @@ export function errorDocument(error: unknown): {
  * The whole run, as a function of its steps and its streams, returning an exit code.
  *
  * @param {{ steps?: (() => unknown)[], json?: boolean, out?: (line: string) => void,
- *           err?: (line: string) => void }} [deps]
+ *           err?: (line: string) => void, runsDir?: () => string }} [deps]
  * @returns {Promise<number>}
  */
 export function doctorRun(deps?: {
@@ -206,7 +296,17 @@ export function doctorRun(deps?: {
     json?: boolean;
     out?: (line: string) => void;
     err?: (line: string) => void;
+    runsDir?: () => string;
 }): Promise<number>;
+export function recordedChecks(): {
+    name: string;
+    id: string;
+    ok: boolean;
+    detail: string;
+    fix: string | null;
+    note?: string | null;
+    advisory?: boolean;
+}[];
 export function addCheck(name: string, ok: boolean, detail: string, remedy?: string | null | {
     fix: string | null;
     note?: string | null;

package/dist/doctor.mjs

@@ -10,7 +10,7 @@ import { availableHostMemoryMb, workersHostCanRun } from "./host-capacity.mjs";
 import { fleetConsistency, describeMismatches } from "./fleet-consistency.mjs";
 import { fleetScriptPaths } from "./src_fleet-scripts_mjs.mjs";
 import { namedInventoryWorkers, configuredWorkers } from "./fleet-env.mjs";
-import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
 import { requestJson } from "./worker-http.mjs";
 import { sandboxGitEnv } from "./src_git-safe-env_mjs.mjs";
 import { assessWorker } from "./worker-health.mjs";
@@ -72,20 +72,44 @@ function shimInvocation(shim, script, args) {
     };
 }
 refuseUnknownFlags([
-    "--json"
+    "--json",
+    "--runs-dir="
 ], {
     entry: import.meta.url,
     command: "pnpm run doctor"
 });
 const doctor_run = promisify(execFile);
 const JSON_OUT = process.argv.includes("--json");
+const REFUSED = 2;
 const WORKERS_ENV = configuredWorkers();
 const PAGES_PORT = Number(process.env.DATASET_PAGES_PORT || 5050);
 const CTL = fleetScriptPaths().workerCtl;
-const SCORER_MODEL_DIR = fileURLToPath(new URL("../../scorer/models/screenreader-scorer/", import.meta.url));
-const DATASET = resolve(fileURLToPath(new URL("../../../", import.meta.url)), "runs/screenreader-dataset");
+const MODULE_DIR = fileURLToPath(new URL(".", import.meta.url));
+const isMonorepoRoot = (root)=>external_node_fs_existsSync(resolve(root, "packages")) && external_node_fs_existsSync(resolve(root, "package.json"));
+function checkoutLayout(baseDir = MODULE_DIR) {
+    const root = resolve(baseDir, "..", "..", "..");
+    return {
+        root,
+        checkout: isMonorepoRoot(root)
+    };
+}
+const notACheckout = (names, root)=>{
+    for (const name of names)advise(name, `n/a: installed package -- ${root} is not a checkout, so there is nothing here for this check to read`);
+};
+function runsDirFor({ argv = process.argv.slice(2), baseDir = MODULE_DIR } = {}) {
+    const supplied = flagValue(argv, "runs-dir");
+    if (void 0 !== supplied) {
+        if (external_node_fs_existsSync(supplied)) return resolve(supplied);
+        throw new Error(`doctor: --runs-dir=${supplied} does not exist. Pass --runs-dir=<the runs directory>.`);
+    }
+    const root = resolve(baseDir, "..", "..", "..");
+    if (isMonorepoRoot(root)) return resolve(root, "runs");
+    throw new Error(`doctor: no runs directory: ${root} is not a checkout (this is an installed package), so there is no runs/ to default to. Pass --runs-dir=<the runs directory>.`);
+}
+const datasetDir = ()=>resolve(runsDirFor(), "screenreader-dataset");
 const PROBE_TIMEOUT_MS = 8000;
 const checks = [];
+const recordedChecks = ()=>checks;
 const GATES = Object.freeze({
     worker: true,
     fleet: true,
@@ -168,8 +192,11 @@ async function httpJson(url) {
     if (void 0 === response.json) throw new Error(`invalid JSON from ${url}`);
     return response.json;
 }
-function checkPrimaryCheckoutMark() {
-    const root = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..");
+function checkPrimaryCheckoutMark({ baseDir = MODULE_DIR } = {}) {
+    const { root, checkout } = checkoutLayout(baseDir);
+    if (!checkout) return notACheckout([
+        "primary checkout"
+    ], root);
     let linked;
     try {
         linked = !statSync(resolve(root, ".git")).isDirectory();
@@ -195,17 +222,19 @@ function checkPrimaryCheckoutMark() {
     if (marked) return add("primary checkout", true, "MARKED — pre-commit refuses commits here and post-checkout keeps it detached at origin/main");
     advise("primary checkout", "not marked, so the primary-checkout guards are INERT here. Correct for the lab, a worker or a colleague's clone; wrong for the machine that drives the fleet.", "pnpm run primary:mark -- --set   (only on the fleet-driving checkout — see docs/primary-checkout.md)");
 }
-function checkControlPlaneIsolation() {
+function checkControlPlaneIsolation({ baseDir = MODULE_DIR } = {}) {
+    const { root, checkout } = checkoutLayout(baseDir);
+    if (!checkout) return notACheckout([
+        "isolation"
+    ], root);
     const raw = process.env.A11Y_SSH_KEY || "~/.ssh/a11y-witness_ed25519";
     const keyPath = raw.startsWith("~/") ? resolve(homedir(), raw.slice(2)) : raw;
     const hasFleetKey = external_node_fs_existsSync(keyPath);
-    const root = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..");
     const hasNodeModules = external_node_fs_existsSync(resolve(root, "node_modules"));
-    const isWorkspace = external_node_fs_existsSync(resolve(root, "packages")) && external_node_fs_existsSync(resolve(root, "package.json"));
     const verdict = controlPlaneIsolation({
         hasNodeModules,
         hasFleetKey,
-        isWorkspace
+        isWorkspace: checkout
     });
     if (!verdict.violated) return add("isolation", true, verdict.why);
     advise("isolation", verdict.why, "docs/control-plane-plan.md L3 — drive the control plane rather than holding its keys");
@@ -256,9 +285,13 @@ function behindOriginMainNote(otherRoot) {
         return "";
     }
 }
-function checkCrossPackageDist() {
+function checkCrossPackageDist({ baseDir = MODULE_DIR } = {}) {
     const specifier = "@a11ign/judge/rules";
-    const thisCheckoutRoot = resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "..", "..");
+    const { root: thisCheckoutRoot, checkout } = checkoutLayout(baseDir);
+    if (!checkout) return notACheckout([
+        "dist-resolution",
+        "dist-freshness"
+    ], thisCheckoutRoot);
     let resolvedRealPath;
     try {
         resolvedRealPath = external_node_fs_realpathSync(createRequire(import.meta.url).resolve(specifier));
@@ -277,11 +310,24 @@ function checkCrossPackageDist() {
     if (upToDate) return add("dist-freshness", true, `packages/judge under ${distRoot} is up to date (tsc --build --dry)`);
     advise("dist-freshness", `packages/judge under ${distRoot} is NOT up to date (tsc --build --dry) -- a build compiled before the source it now reflects`, "pnpm run build   # in that checkout");
 }
-async function checkJudge() {
+async function scorerWeightsFor({ from = import.meta.url } = {}) {
+    const judgeEntry = external_node_fs_realpathSync(createRequire(from).resolve("@a11ign/judge"));
+    const scorerEntry = external_node_fs_realpathSync(createRequire(judgeEntry).resolve("@a11ign/scorer"));
+    const { scorerPaths } = await import(pathToFileURL(scorerEntry).href);
+    return scorerPaths().weights;
+}
+async function checkJudge({ from = import.meta.url } = {}) {
     const backend = (process.env.JUDGE_BACKEND || "local").toLowerCase();
     if ("local" === backend) {
-        const weights = resolve(SCORER_MODEL_DIR, "model.safetensors");
-        return add("judge", external_node_fs_existsSync(weights), external_node_fs_existsSync(weights) ? "backend=local, trained scorer present" : "backend=local, but the trained scorer is missing", `expected weights at ${weights} — they ship in the repo, so this means an incomplete checkout`);
+        let weights;
+        try {
+            weights = await scorerWeightsFor({
+                from
+            });
+        } catch (error) {
+            return add("judge", false, `backend=local, but @a11ign/scorer could not be resolved from @a11ign/judge: ${error.message}`, "install @a11ign/scorer (a peer dependency of @a11ign/judge) beside @a11ign/judge");
+        }
+        return add("judge", external_node_fs_existsSync(weights), external_node_fs_existsSync(weights) ? "backend=local, trained scorer present" : "backend=local, but the trained scorer is missing", `expected weights at ${weights} (where @a11ign/scorer says they are) — reinstall @a11ign/scorer`);
     }
     if ("anthropic" === backend || "openai" === backend) {
         const key = "anthropic" === backend ? "ANTHROPIC_API_KEY" : "JUDGE_BASE_URL";
@@ -419,7 +465,7 @@ function checkHostCapacity(pool) {
     add("host memory", true, limit >= poolSize ? detail : `${detail}; the rest stay stopped so the run does not swap (override: A11Y_MAX_WORKERS)`);
 }
 async function checkDatasetPages() {
-    const manifestPath = resolve(DATASET, "manifest.json");
+    const manifestPath = resolve(datasetDir(), "manifest.json");
     if (!external_node_fs_existsSync(manifestPath)) return add("dataset", false, "no manifest — the dataset has not been generated", "pnpm run training:generate");
     const sample = JSON.parse(readFileSync(manifestPath, "utf8")).cases?.[0]?.id;
     const probe = sample ? `${sample}/good.html` : "";
@@ -434,7 +480,7 @@ async function checkDatasetPages() {
     }
 }
 function checkRunState() {
-    const progress = resolve(DATASET, "capture-progress.json");
+    const progress = resolve(datasetDir(), "capture-progress.json");
     if (!external_node_fs_existsSync(progress)) return add("run", true, "no capture run recorded");
     const p = JSON.parse(readFileSync(progress, "utf8"));
     if (!p.startedAt) return add("run", true, "no capture run recorded");
@@ -475,7 +521,14 @@ function errorDocument(error) {
     };
 }
 async function doctorRun(deps = {}) {
-    const { steps = DEFAULT_STEPS, json = JSON_OUT, out = console.log, err = console.error } = deps;
+    const { steps = DEFAULT_STEPS, json = JSON_OUT, out = console.log, err = console.error, runsDir = runsDirFor } = deps;
+    try {
+        runsDir();
+    } catch (error) {
+        if (json) out(JSON.stringify(errorDocument(error), null, 2));
+        else err(error.message);
+        return REFUSED;
+    }
     try {
         for (const step of steps)await step();
     } catch (error) {
@@ -511,4 +564,4 @@ async function main() {
     process.exit(await doctorRun());
 }
 if (import.meta.url === pathToFileURL(process.argv[1] ? external_node_fs_realpathSync(process.argv[1]) : "").href) await main();
-export { addCheck, allChecks, checkoutRootFor, doctorRun, errorDocument, fleetAgreementLine, gatingChecks, isRunnableCommand, nextCommand, readyFrom, resolvesToThisCheckout, tscProjectUpToDate, workerControlFix };
+export { addCheck, allChecks, checkControlPlaneIsolation, checkCrossPackageDist, checkJudge, checkPrimaryCheckoutMark, checkoutRootFor, doctorRun, errorDocument, fleetAgreementLine, gatingChecks, isRunnableCommand, nextCommand, readyFrom, recordedChecks, resolvesToThisCheckout, runsDirFor, scorerWeightsFor, tscProjectUpToDate, workerControlFix };

package/dist/fleet-env.d.mts

@@ -20,6 +20,27 @@ export function configuredWorkers(): Array<{
     name: string;
     url: string;
 }>;
+/**
+ * The two files the COMMAND reads, from the caller or else from the monorepo layout, and a refusal naming the path
+ * and the flag when the one it would read is not there (a11ign/a11ign#3767).
+ *
+ * `INVENTORY` above points into `packages/control`, which an installed `@a11ign/screenreader-fleet` does not have, so
+ * `fleet-env --list` there died on an ENOENT for a path nobody could have guessed. The library functions keep their
+ * default because their answer for "no inventory here" is `[]`, which is supported; a command that prints
+ * `export A11Y_WORKERS=''` for a missing file would be the same silent wrong answer, so it refuses.
+ *
+ * `baseDir` is INJECTED so a test can stand in for either layout without moving a file.
+ *
+ * @param {{ argv?: readonly string[], baseDir?: string }} [options]
+ * @returns {{ inventoryPath: string, groupVarsPath: string }}
+ */
+export function inventoryPathsFor({ argv, baseDir }?: {
+    argv?: readonly string[];
+    baseDir?: string;
+}): {
+    inventoryPath: string;
+    groupVarsPath: string;
+};
 /**
  * Which group each line of the inventory sits in, index-aligned with `text.split(/\r?\n/)`.
  *

package/dist/fleet-env.mjs

@@ -1,9 +1,12 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertWorkerUrl } from "./worker-http.mjs";
-import { refuseUnknownFlags } from "./cli-flags.mjs";
+import { refuseUnknownFlags, flagValue } from "./cli-flags.mjs";
 refuseUnknownFlags([
-    "--list"
+    "--list",
+    "--inventory=",
+    "--group-vars="
 ], {
     entry: import.meta.url,
     command: "npm run fleet:env"
@@ -19,8 +22,32 @@ function configuredWorkers() {
             url
         }));
 }
-const INVENTORY = fileURLToPath(new URL("../../control/ansible/inventory.yml", import.meta.url));
-const GROUP_VARS = fileURLToPath(new URL("../../control/ansible/group_vars/a11y_workers.yml", import.meta.url));
+const MODULE_DIR = fileURLToPath(new URL(".", import.meta.url));
+const monorepoAnsibleFile = (relative, baseDir = MODULE_DIR)=>resolve(baseDir, "..", "..", "control", "ansible", relative);
+const INVENTORY = monorepoAnsibleFile("inventory.yml");
+const GROUP_VARS = monorepoAnsibleFile("group_vars/a11y_workers.yml");
+function inventoryPathsFor({ argv = process.argv.slice(2), baseDir = MODULE_DIR } = {}) {
+    const inventoryPath = existingPath({
+        flag: "inventory",
+        supplied: flagValue(argv, "inventory"),
+        fallback: monorepoAnsibleFile("inventory.yml", baseDir)
+    });
+    const groupVarsPath = existingPath({
+        flag: "group-vars",
+        supplied: flagValue(argv, "group-vars"),
+        fallback: monorepoAnsibleFile("group_vars/a11y_workers.yml", baseDir)
+    });
+    return {
+        inventoryPath,
+        groupVarsPath
+    };
+}
+function existingPath({ flag, supplied, fallback }) {
+    const path = supplied ?? fallback;
+    if (existsSync(path)) return path;
+    const origin = void 0 === supplied ? "the monorepo layout this command defaults to has no such file" : "no such file";
+    throw new Error(`fleet:env: ${path} does not exist (${origin}). Pass --${flag}=<file>.`);
+}
 const HOST_LINE = /^\s*ansible_host\s*:\s*(\S+)\s*$/;
 const SUSPECT = /ansible_host\s*:/;
 const KEY_LINE = /^(\s*)([A-Za-z_][\w.-]*)\s*:/;
@@ -207,8 +234,16 @@ function fleetEnvOutput(text, { port = DEFAULT_WORKER_PORT, mode = "env" } = {})
     };
 }
 function main() {
-    const port = portFromGroupVars(readFileSync(GROUP_VARS, "utf8"));
-    const { stdout, stderr } = fleetEnvOutput(readFileSync(INVENTORY, "utf8"), {
+    let paths;
+    try {
+        paths = inventoryPathsFor();
+    } catch (error) {
+        process.stderr.write(`${error.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const port = portFromGroupVars(readFileSync(paths.groupVarsPath, "utf8"));
+    const { stdout, stderr } = fleetEnvOutput(readFileSync(paths.inventoryPath, "utf8"), {
         port,
         mode: process.argv.includes("--list") ? "list" : "env"
     });
@@ -216,4 +251,4 @@ function main() {
     process.stdout.write(stdout);
 }
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main();
-export { DEFAULT_WORKER_PORT, WORKER_GROUP, configuredWorkers, fleetEnvOutput, groupPerLine, hostsOutOfCaptureSet, inventoryWorkerUrls, namedInventoryWorkers, portFromGroupVars, resolveWorkerPool, workerNamesFromInventory, workersFromInventory };
+export { DEFAULT_WORKER_PORT, WORKER_GROUP, configuredWorkers, fleetEnvOutput, groupPerLine, hostsOutOfCaptureSet, inventoryPathsFor, inventoryWorkerUrls, namedInventoryWorkers, portFromGroupVars, resolveWorkerPool, workerNamesFromInventory, workersFromInventory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11ign/screenreader-fleet",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Host-side lifecycle, health and capacity for a fleet of Windows NVDA capture workers: lease one, judge whether it is degrading, and know how many the host can afford.",
   "license": "AGPL-3.0-or-later",
   "type": "module",