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

package/dist/fleet-env.d.mts

@@ -0,0 +1,228 @@
+/**
+ * The fleet named by the environment — ONE parser, because there were three that did not agree.
+ *
+ * `doctor.mjs` preferred `A11Y_WORKERS`, `check-worker-code.mjs` preferred `A11Y_WORKER`, and the
+ * dataset runner read only `A11Y_WORKERS`. With both variables set, `doctor` and `worker:code` reported
+ * on **different machines** — so "doctor says the fleet is fine" and "worker:code says a worker is
+ * stale" could be statements about two disjoint sets, with nothing to say so.
+ *
+ * `A11Y_WORKERS` wins, matching the dataset runner: the plural names the pool a run dispatches across,
+ * and a diagnostic that describes a different set from the one that will do the work is worse than no
+ * diagnostic. Each entry is trimmed and de-slashed, because `A11Y_WORKERS=a, b` otherwise yields a URL
+ * with a leading space — a configuration typo wearing a dead-machine costume.
+ *
+ * Returns `[]` rather than null when neither is set: "no worker was named" is a normal state that means
+ * "find the local VMs", and every caller already branches on emptiness.
+ *
+ * @returns {Array<{ name: string, url: string }>}
+ */
+export function configuredWorkers(): Array<{
+    name: string;
+    url: string;
+}>;
+/**
+ * Which group each line of the inventory sits in, index-aligned with `text.split(/\r?\n/)`.
+ *
+ * Exported so there is ONE group implementation. `fleet-discover.mjs` has its own host reader with its own
+ * regexes -- two readers of one file, which this repo's notes call its most expensive recurring shape -- and
+ * when this module became group-aware that one did not, so `fleet:discover` probed the lab container on
+ * :8765 and reported it "ASLEEP?". A phantom worker in the diagnostic instead of in the dispatch list is
+ * still a phantom worker. Rather than teach a second parser about groups, both now ask this.
+ *
+ * @param {string} text
+ * @returns {Array<string | undefined>}
+ */
+export function groupPerLine(text: string): Array<string | undefined>;
+/**
+ * Worker URLs from the text of an inventory file.
+ *
+ * `scope` says which question is asked. `"fleet"` (the default) is every enrolled worker -- what `doctor`,
+ * `worker:code`, `fleet:status` and the deploy tooling mean, and they must keep seeing a worker that is
+ * serving but not capturing. `"capture"` is the fleet minus every host that declares `a11y_capture: false`
+ * -- what `A11Y_WORKERS` means. It is a string and not a flag because a boolean argument does not say
+ * which of the two you got.
+ *
+ * Exported and pure so the strictness above is testable: a reader that has never been shown to reject
+ * anything is a reader nobody knows the limits of.
+ *
+ * @param {string} text
+ * @param {{ port?: number, group?: string, scope?: "fleet" | "capture" }} [options]
+ * @returns {string[]}
+ */
+export function workersFromInventory(text: string, { port, group, scope }?: {
+    port?: number;
+    group?: string;
+    scope?: "fleet" | "capture";
+}): string[];
+/**
+ * The hosts left OUT of the capture set, so the command that leaves them out can say so.
+ *
+ * @param {string} text
+ * @param {{ port?: number, group?: string }} [options]
+ * @returns {{name: string, url: string}[]}
+ */
+export function hostsOutOfCaptureSet(text: string, { port, group }?: {
+    port?: number;
+    group?: string;
+}): {
+    name: string;
+    url: string;
+}[];
+/**
+ * The inventory as `{ url -> name }`, so a report can say which machine a command would act on.
+ *
+ * Same parser, same group rules — deliberately not a second reader of the same file, which this repo
+ * calls its most expensive recurring shape and has already paid for once in `fleet-discover.mjs`.
+ *
+ * @param {string} text
+ * @param {{ port?: number, group?: string }} [options]
+ * @returns {Record<string, string>}
+ */
+export function workerNamesFromInventory(text: string, { port, group }?: {
+    port?: number;
+    group?: string;
+}): Record<string, string>;
+/** The port the group vars declare, so it is stated once and not guessed here. */
+/** @param {string} text @returns {number} */
+export function portFromGroupVars(text: string): number;
+/**
+ * The workers declared in `inventory.yml` — i.e. the BARE-METAL fleet.
+ *
+ * Exists so a caller can tell a physical box from a local UTM VM, which decides how it is deployed to and
+ * therefore what remedy to print. `worker:code` used to tell every stale worker to run `utmctl` and
+ * `npm run worker:deploy`, which CANNOT reach a bare-metal box — it is a `utmctl file push` keyed on a VM
+ * UUID and fails immediately off macOS. Following that advice on this fleet wastes the time it takes to
+ * discover the tool was describing a different kind of machine.
+ *
+ * Reads the same file through the same parser as `main()`, rather than a second copy of the knowledge.
+ *
+ * `inventoryPath`/`groupVarsPath` are INJECTED, defaulting to this monorepo's own control-plane files —
+ * see the comment above `INVENTORY` for why the default exists and what it does not fix on its own.
+ *
+ * @param {{ inventoryPath?: string, groupVarsPath?: string }} [paths]
+ */
+export function inventoryWorkerUrls({ inventoryPath, groupVarsPath }?: {
+    inventoryPath?: string;
+    groupVarsPath?: string;
+}): string[];
+/**
+ * The bare-metal fleet as `{name, url}` — the shape a REPORT needs.
+ *
+ * `fleet-status.mjs` already pairs the two, and its comment records what the address alone cost: "this
+ * table named .224 as the box whose Edge had drifted, and .224 is a11y-worker-FIVE — so
+ * `fleet:sleep --limit=a11y-worker-4` put a healthy machine to sleep and left the drifted one serving. A
+ * report and a command that cannot be matched up is a report you have to translate, and translation is
+ * where the mistake goes."
+ *
+ * Here rather than in each reporter, because that is the same pairing and a second copy would drift.
+ *
+ * `inventoryPath`/`groupVarsPath` are INJECTED, same reason and same default as `inventoryWorkerUrls`.
+ *
+ * @param {{ inventoryPath?: string, groupVarsPath?: string }} [paths]
+ * @returns {{name: string, url: string}[]} empty when no inventory is declared, like `inventoryWorkerUrls`
+ */
+export function namedInventoryWorkers({ inventoryPath, groupVarsPath }?: {
+    inventoryPath?: string;
+    groupVarsPath?: string;
+}): {
+    name: string;
+    url: string;
+}[];
+/**
+ * WHICH WORKERS TO USE, AND WHERE THAT LIST CAME FROM — the one precedence, in one place.
+ *
+ * THREE MODULES HELD THREE DIFFERENT ANSWERS, and one of them carried a comment saying they had been
+ * unified. Measured 2026-08-29:
+ *
+ *   doctor.mjs                        named -> inventory
+ *   check-worker-code.mjs             named -> LOCAL UTM POOL -> inventory
+ *   capture-screenreader-dataset.mjs  named -> LOCAL UTM POOL -> single-VM lease   (never reads inventory)
+ *
+ * The corpus capture path's own comment reads "One parser, in fleet-env.mjs. This copy and doctor's and
+ * check-worker-code's had drifted apart on precedence, which meant a diagnostic could describe a different
+ * fleet from the one about to run." That unification covered the NAMED half only; the fallback order below
+ * it stayed three separate answers, so the sentence describes a fix that was half applied.
+ *
+ * The consequence is the one the comment predicted: on a Mac with any registered UTM guest, `worker:code`
+ * reports the local VM while `doctor` reports the five bare-metal boxes, and a capture dispatches to
+ * whichever the entry point happened to prefer.
+ *
+ * ## THE LOCAL UTM POOL IS LAST, and that is a deprecation, not a preference
+ *
+ * The local guests were a testing arrangement and are deprecated; `inventory.yml` is the fleet, and ADR
+ * 0012 already calls it the single source of truth. So the pool is a fallback for a checkout with NO
+ * inventory — a supported setup for an outside contributor with one Mac and no hardware — and never a
+ * contender with one. Any other order reproduces the divergence above on every Mac that still has a bundle
+ * registered.
+ *
+ * `local` is injected rather than imported: reading the UTM pool means shelling out to `utmctl`, and this
+ * module is imported by everything that needs a worker list, including on Linux. A caller that has no
+ * local-pool reader simply omits it.
+ *
+ * @param {{ named?: () => {url: string}[], inventory?: () => string[], local?: () => string[] }} readers
+ * @returns {{ urls: string[], source: string }}
+ */
+export function resolveWorkerPool({ named, inventory, local, }?: {
+    named?: () => {
+        url: string;
+    }[];
+    inventory?: () => string[];
+    local?: () => string[];
+}): {
+    urls: string[];
+    source: string;
+};
+/**
+ * What `fleet:env` prints, as data: `stdout` is what a shell reads, `stderr` is what the operator reads.
+ *
+ * `mode: "list"` is the WHOLE fleet, one URL per line, and leaves nobody out. The default is the capture
+ * set as an `export`, and it NAMES every host it left out on stderr -- an omission with no line is a
+ * machine nothing reports, which is the failure this module's header is about. stderr, because stdout is
+ * `eval`-ed.
+ *
+ * @param {string} text the inventory
+ * @param {{ port?: number, mode?: "env" | "list" }} [options]
+ * @returns {{stdout: string, stderr: string}}
+ */
+export function fleetEnvOutput(text: string, { port, mode }?: {
+    port?: number;
+    mode?: "env" | "list";
+}): {
+    stdout: string;
+    stderr: string;
+};
+export const DEFAULT_WORKER_PORT: 8765;
+/**
+ * The inventory group whose hosts are capture workers.
+ *
+ * This reader was GROUPLESS until 2026-08-21, and that was a live hazard rather than an untidiness: every
+ * `ansible_host:` in the file became `http://<addr>:8765`, so adding any non-worker host to `inventory.yml`
+ * -- the lab container, the control container, a switch -- would have silently added a phantom worker to
+ * `A11Y_WORKERS`, and a run would have dispatched capture cases to it. That is the exact failure this
+ * module's own header says it exists to prevent ("dispatched to but never updated", "both of those are
+ * silent"), arriving through the door nobody had shut.
+ */
+export const WORKER_GROUP: "a11y_workers";
+/**
+ * One frame of the indentation stack: a key and the column it started at.
+ */
+export type Frame = {
+    indent: number;
+    key: string;
+};
+/**
+ * A host as the inventory declares it — the ADDRESS and the NAME together.
+ *
+ * They travel as one value because separating them is what sent `fleet:sleep` at the wrong machine: every
+ * tool that ACTS on a worker takes the name, every tool that REPORTS on one printed the address, and
+ * nothing mapped between them. `collectHost` explains the incident.
+ *
+ * `capture` is false for a host that declares `a11y_capture: false`: enrolled, served, deployed to, and not
+ * handed corpus cases.
+ */
+export type Host = {
+    name: string | undefined;
+    host: string;
+    capture: boolean;
+};
+//# sourceMappingURL=fleet-env.d.mts.map

package/dist/fleet-env.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-env.d.mts","sourceRoot":"","sources":["../src/fleet-env.mjs"],"names":[],"mappings":"AA4CA;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFa,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAehD;AA+FD;;;;;;;;;;;GAWG;AACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAUrC;AA4FD;;;;;;;;;;;;;;;GAeG;AACH,2CAJW,MAAM,2BACN;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAE,GAC5D,MAAM,EAAE,CAWpB;AAED;;;;;;GAMG;AACH,2CAJW,MAAM,oBACN;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,EAAE,CAMzC;AAED;;;;;;;;;GASG;AACH,+CAJW,MAAM,oBACN;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBlC;AAiCD,kFAAkF;AAClF,6CAA6C;AAC7C,wCADY,MAAM,GAAiB,MAAM,CAIxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,uEAFW;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,YAW5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,yEAHW;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,EAAE,CAYzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iEAHW;IAAE,KAAK,CAAC,EAAE,MAAM;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,MAAM,EAAE,CAAA;CAAE,GACnF;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAmB9C;AAED;;;;;;;;;;;GAWG;AACH,qCAJW,MAAM,mBACN;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,GACtC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAe5C;AA/dD,kCAAmC,IAAI,CAAC;AAqExC;;;;;;;;;GASG;AACH,2BAA4B,cAAc,CAAC;;;;oBAK9B;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC;;;;;;;;;;;mBAa7B;IAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC"}