@a11ign/screenreader-fleet 0.5.1 → 0.5.3

package/README.md

@@ -93,3 +93,40 @@ the only real lifecycle — a cold boot to ready is 15–45 s, which is fine.
 
 Not exported: `host-metrics`, `worker-stats`, `fleet-consistency`. They are measurement internals whose shapes
 change every time something new gets measured.
+
+## Working here
+
+This repository is the package: `package.json`, `src/` and this README sit at the root, and the README is the npm page. It moved here from
+[`a11ign/a11ign`](https://github.com/a11ign/a11ign) with its history. It depends on
+[`@a11ign/screenreader-worker`](https://github.com/a11ign/screenreader-worker) and `@a11ign/judge` **by name, from the registry**.
+
+**The fleet drives workers that have no authentication.** Anyone who can reach a worker's port can drive the browser and the screen
+reader on that machine (`SECURITY.md` in `a11ign/a11ign` says what else somebody must know first). Run it only on a network you control.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm test        # what the `gate` check runs on every pull request and merge-queue entry, with lint, typecheck and layout-check
+```
+
+`main` takes pull requests only, each with one approving review, through the merge queue. `pnpm exec layout-check` is the repository-layout
+check from `@a11ign/toolchain`: it fails a workspace of one package, a directory not named for its package, a second README and a leftover
+`lerna.json`.
+
+### What did not come across: 27 tests
+
+The package's test directory was written for the monorepo, and 27 of its 53 test files read something that is not in this repository:
+`packages/control`'s playbooks and inventories, `packages/lab`'s capture clients, the private `guards` package, or the root's
+`scripts/`. Run here, they fail on a file they cannot find, so they were **not** carried into this repository; they stay in
+`a11ign/a11ign`, beside what they read, until its row #3504 relocates them. Their names are the `COUPLED` list in
+`packages/lab/src/packaging/screenreader-fleet-extraction.test.ts` there. The other 26 run here and are what `gate` runs, with
+`scripts/package-boundary.test.ts` holding the package to its own directory.
+
+### Releasing
+
+This repository releases on its own, not with `a11ign/a11ign`. A change that should reach npm carries a changeset
+(`pnpm exec changeset`), and **merging it to `main` is the release**: `.github/workflows/release.yml` calls the one
+reusable per-merge workflow in `a11ign/toolchain`, which versions the merge on a detached commit, publishes, tags and
+releases it. There is no version pull request and nothing is written to `main`, so its `package.json` version and
+`CHANGELOG.md` lag the last tag (`.changeset/README.md`). The publish uses npm trusted publishing over OIDC with
+provenance and no stored token. The first release, 0.1.0, was published before this workflow existed;
+no git tag names it, so the first per-merge release bases on `main`'s 0.1.0.

package/dist/doctor.mjs

@@ -2,7 +2,7 @@
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir } from "node:os";
 import { createRequire } from "node:module";
@@ -361,7 +361,7 @@ async function checkDegradedWorkers(probed) {
     for (const w of probed){
         if (!w.health) continue;
         const { degraded, reason } = assessWorker(w.health.vitals);
-        if (degraded) add(`worker ${w.name}`, true, `DEGRADED — ${reason}`, `re-provision ${w.name}: packages/worker-fleet/src/provisioning/provision-nvda-worker.ps1, elevated, in the interactive session`);
+        if (degraded) add(`worker ${w.name}`, true, `DEGRADED — ${reason}`, `re-provision ${w.name}: ${join(fleetScriptPaths().provisioning, "provision-nvda-worker.ps1")}, elevated, in the interactive session`);
     }
 }
 function checkFleetConsistency(probed, configured) {

package/dist/source-walk.d.mts

@@ -1,5 +1,5 @@
 /**
- * Every non-test source file under `packages/`, as `[relativePath, source]`.
+ * Every non-test source file under the repository root, as `[relativePath, source]`.
  *
  * @param {{ root?: string }} [options]
  * @returns {Array<[string, string]>}
@@ -7,5 +7,5 @@
 export function sourceFiles({ root }?: {
     root?: string;
 }): Array<[string, string]>;
-/** The `packages/` directory, resolved from this module rather than from the caller's cwd. */
-export const PACKAGES: string;
+/** The repository root, resolved from this module rather than from the caller's cwd. */
+export const REPOSITORY: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11ign/screenreader-fleet",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",
@@ -73,9 +73,16 @@
   },
   "devDependencies": {
     "@a11ign/evidence": "0.1.0",
-    "@a11ign/toolchain": "0.1.2",
+    "@a11ign/toolchain": "0.1.5",
+    "@changesets/cli": "3.0.3",
+    "@eslint/js": "^10.0.1",
     "@rslib/core": "1.0.3",
+    "@rstest/core": "0.12.3",
+    "@types/node": "^26.6.4",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
     "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
     "yaml": "^2.9.1"
   },
   "engines": {
@@ -84,11 +91,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/a11ign/screenreader-fleet.git",
-    "directory": "packages/worker-fleet"
-  },
   "homepage": "https://github.com/a11ign/screenreader-fleet",
   "keywords": [
     "accessibility",
@@ -99,7 +101,14 @@
     "utm",
     "vm"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a11ign/screenreader-fleet.git"
+  },
   "scripts": {
-    "build": "rslib build"
+    "build": "rslib build",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "rstest run"
   }
 }

package/src/local-worker/build-vm.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Build a local NVDA capture worker VM on Apple Silicon, unattended.
 #
-#   ./packages/worker-fleet/src/local-worker/build-vm.sh /path/to/Win11_ARM64.iso
+#   ./src/local-worker/build-vm.sh /path/to/Win11_ARM64.iso
 #
 # Produces a self-contained VM directory (default ~/a11y-worker-vm) holding the disk
 # image, UEFI vars and a run script. That directory IS the portable artifact: copy it
@@ -40,7 +40,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 die() { echo "error: $*" >&2; exit 1; }
 info() { echo "==> $*"; }
 
-[ -n "$WIN_ISO" ] || die "usage: $0 <windows-11-arm64.iso>   (build one with CrystalFetch, or packages/worker-fleet/src/local-worker/fetch-windows-iso.sh)"
+[ -n "$WIN_ISO" ] || die "usage: $0 <windows-11-arm64.iso>   (build one with CrystalFetch, or src/local-worker/fetch-windows-iso.sh)"
 [ -f "$WIN_ISO" ] || die "not found: $WIN_ISO"
 command -v qemu-system-aarch64 >/dev/null || die "qemu missing: brew install qemu"
 command -v qemu-img >/dev/null || die "qemu-img missing: brew install qemu"

package/src/local-worker/clone-worker.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Clone the local NVDA worker VM into an additional, independent worker.
 #
-#   ./packages/worker-fleet/src/local-worker/clone-worker.sh [new-name]      # default: a11y-worker-2
+#   ./src/local-worker/clone-worker.sh [new-name]      # default: a11y-worker-2
 #
 # One worker serves one capture at a time by design (one desktop, one foreground window, one
 # NVDA), so throughput scales by running more of them. On APFS the clone is copy-on-write, so

package/src/local-worker/create-utm-vm.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Create the NVDA worker VM in UTM, fully from the CLI. No GUI clicking.
 #
-#   ./packages/worker-fleet/src/local-worker/create-utm-vm.sh <windows-arm64.iso> [support.iso]
+#   ./src/local-worker/create-utm-vm.sh <windows-arm64.iso> [support.iso]
 #
 # Why UTM rather than plain QEMU: homebrew QEMU + HVF cannot boot Windows 11 ARM64 on
 # Apple Silicon (open upstream bug, https://gitlab.com/qemu-project/qemu/-/issues/2893,

package/src/local-worker/fetch-windows-iso.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Build an official Windows 11 ARM64 ISO on macOS, from the CLI.
 #
-#   ./packages/worker-fleet/src/local-worker/fetch-windows-iso.sh [outdir]
+#   ./src/local-worker/fetch-windows-iso.sh [outdir]
 #
 # Microsoft's ARM64 ISO download is a session-token web flow that does not script
 # cleanly, so this uses UUP dump: it fetches the same Unified Update Platform packages
@@ -16,7 +16,7 @@ set -euo pipefail
 
 # architecture-audit.md §8: builds an ISO for a local UTM worker VM, which is deprecated -- "The UTM is
 # deprecated, that was a testing thing." (repository owner, 2026-09-05). Bare-metal boxes install via
-# PXE/autounattend.xml instead — see packages/worker-fleet/src/provisioning/bare-metal/.
+# PXE/autounattend.xml instead — see src/provisioning/bare-metal/.
 echo "DEPRECATED: fetch-windows-iso.sh feeds a local UTM worker VM build. UTM was a testing path and is not the fleet." >&2
 echo "Capture on the bare-metal fleet instead: npm run fleet:status, npm run fleet:deploy." >&2
 
@@ -100,7 +100,7 @@ cd "$OUT_DIR"
 EXISTING="$(ls -t "$OUT_DIR"/*.ISO "$OUT_DIR"/*.iso 2>/dev/null | grep -vi support | head -1 || true)"
 if [ -n "$EXISTING" ] && xorriso -indev "$EXISTING" -report_el_torito plain 2>/dev/null | grep -q UEFI; then
   echo "ISO ready (already built): $EXISTING"
-  echo "Next:  ./packages/worker-fleet/src/local-worker/create-utm-vm.sh \"$EXISTING\""
+  echo "Next:  ./src/local-worker/create-utm-vm.sh \"$EXISTING\""
   exit 0
 fi
 if [ -n "$EXISTING" ]; then
@@ -234,5 +234,5 @@ fi
 
 echo
 echo "ISO ready: $ISO"
-echo "Next:  ./packages/worker-fleet/src/local-worker/build-vm.sh \"$ISO\""
-echo "       ./packages/worker-fleet/src/local-worker/create-utm-vm.sh \"$ISO\""
+echo "Next:  ./src/local-worker/build-vm.sh \"$ISO\""
+echo "       ./src/local-worker/create-utm-vm.sh \"$ISO\""

package/src/local-worker/worker-ctl.sh

@@ -3,20 +3,20 @@
 # while you are not capturing.
 #
 #   npm run worker:ctl -- up                           # make it ready (start or resume), wait for /health
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pause         # freeze it: ~0.6% CPU, instant resume, RAM not guaranteed
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh stop          # shut it down: nothing held, ~15 s to come back
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh status        # state, resource use, health
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh json          # the same, machine-readable (used by the CLI)
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool          # every a11y-worker* VM, as JSON
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool-up       # start them all, wait for health
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool-stop     # shut the whole pool down
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh pool-pause    # freeze the whole pool
+#   ./src/local-worker/worker-ctl.sh pause         # freeze it: ~0.6% CPU, instant resume, RAM not guaranteed
+#   ./src/local-worker/worker-ctl.sh stop          # shut it down: nothing held, ~15 s to come back
+#   ./src/local-worker/worker-ctl.sh status        # state, resource use, health
+#   ./src/local-worker/worker-ctl.sh json          # the same, machine-readable (used by the CLI)
+#   ./src/local-worker/worker-ctl.sh pool          # every a11y-worker* VM, as JSON
+#   ./src/local-worker/worker-ctl.sh pool-up       # start them all, wait for health
+#   ./src/local-worker/worker-ctl.sh pool-stop     # shut the whole pool down
+#   ./src/local-worker/worker-ctl.sh pool-pause    # freeze the whole pool
 #
 # One VM serves one capture at a time, so throughput comes from more VMs. `pool` reports the
 # lot; add one with clone-worker.sh (which handles the duplicate-MAC trap).
 # Operate on a single named VM with A11Y_VM_NAME=a11y-worker-2.
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh idle-pause 15 # watch, then pause after 15 idle minutes
-#   ./packages/worker-fleet/src/local-worker/worker-ctl.sh idle-stop 30  # same but shut down instead
+#   ./src/local-worker/worker-ctl.sh idle-pause 15 # watch, then pause after 15 idle minutes
+#   ./src/local-worker/worker-ctl.sh idle-stop 30  # same but shut down instead
 #
 # Measured on an M4 Max, 4 vCPU / 8 GB guest. Every number here was observed on this
 # machine; none is an estimate:
@@ -117,7 +117,7 @@ resolve_uuid() {
   [ -n "${A11Y_VM_UUID:-}" ] && { echo "$A11Y_VM_UUID"; return; }
   local matches
   matches="$(utmctl list | awk -v n="$VM_NAME" '$3 == n { print $1 }')"
-  [ -n "$matches" ] || die "no VM named '$VM_NAME' (create one: packages/worker-fleet/src/local-worker/create-utm-vm.sh)"
+  [ -n "$matches" ] || die "no VM named '$VM_NAME' (create one: src/local-worker/create-utm-vm.sh)"
   if [ "$(echo "$matches" | wc -l | tr -d ' ')" -gt 1 ]; then
     # Do NOT guess, and do NOT suggest deleting one. Duplicate registrations under the same
     # name point at the SAME <name>.utm bundle, so `utmctl delete` on either removes that
@@ -317,7 +317,7 @@ case "$CMD" in
         echo "         it is down for 5-10s during a restart; if it persists:" >&2
         echo "         utmctl exec <uuid> --cmd powershell.exe -NoProfile -Command 'Start-ScheduledTask -TaskName a11ysrv'" >&2
       else
-        # `$0` is this file's path, which after M6 is `packages/worker-fleet/src/local-worker/worker-ctl.sh` — true,
+        # `$0` is this file's path, which after M6 is `src/local-worker/worker-ctl.sh` — true,
         # and not what anyone wants to type. The npm alias is the stable way to say it, and it is what the docs use.
         echo "         no guest IP either, so the VM itself is not ready. Try 'npm run worker:ctl -- up'." >&2
       fi

package/src/provisioning/apply-foreground-lock-timeout.ps1

@@ -22,7 +22,7 @@
 # and run-server.cmd (so every worker start re-applies it for that session).
 #
 # Style note: `#` line comments and no param() block, matching the other scripts here --
-# see packages/worker-fleet/src/provisioning/diagnose-nvda-worker.ps1 for why.
+# see src/provisioning/diagnose-nvda-worker.ps1 for why.
 
 $ErrorActionPreference = 'Stop'
 

package/src/provisioning/bootstrap-windows-worker.ps1

@@ -3,7 +3,7 @@
 # Run this ONCE, in the VM, in an elevated PowerShell, right after Windows setup:
 #
 #   Set-ExecutionPolicy -Scope Process Bypass -Force
-#   irm https://raw.githubusercontent.com/a11ign/a11ign/main/packages/worker-fleet/src/provisioning/bootstrap-windows-worker.ps1 | iex
+#   irm https://raw.githubusercontent.com/a11ign/screenreader-fleet/main/src/provisioning/bootstrap-windows-worker.ps1 | iex
 #
 # ...or, if you already have the repo, just run this file. It installs the
 # prerequisites, makes the box reachable over SSH, clones the repo, and then hands

package/src/provisioning/diagnose-nvda-worker.ps1

@@ -4,7 +4,7 @@
 # VERDICT per layer rather than raw dumps, so the first FAIL is the thing to fix.
 # Exits non-zero if any check failed. Copy it over and run it with -File:
 #
-#   scp packages/worker-fleet/src/provisioning/diagnose-nvda-worker.ps1 user@host:C:/Users/user/
+#   scp src/provisioning/diagnose-nvda-worker.ps1 user@host:C:/Users/user/
 #   ssh user@host "powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\user\diagnose-nvda-worker.ps1"
 #
 # Do NOT pipe this to `powershell -Command -`. That mode silently truncated this

package/src/provisioning/stamp-provision-revision.ps1

@@ -47,8 +47,8 @@ param(
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
-# TWO OF THE FIVE PATHS ARE NOT WRITTEN HERE (ADR 0039 item 6d, #3397). Where the worker layer lives is
-# declared in `packages/control/layers.json`, and what its launchers reach outside it in the layer's own
+# THREE OF THE FIVE PATHS ARE NOT WRITTEN HERE (ADR 0039 item 6d, #3397; this repository's own file since the flat layout, a11ign/a11ign#4216).
+# Where the worker layer and this fleet layer live is declared in `packages/control/layers.json`, and what its launchers reach outside it in the layer's own
 # `src/launcher-reach.cmd`, which `run-capture-check.cmd` `call`s. Both are READ, so a path cannot change in
 # the launcher and stay behind in the stamp. A declaration that is absent or does not say THROWS: the stamp
 # must not fall back to a literal, because a literal that was right yesterday is the stamp describing less
@@ -77,7 +77,7 @@ $FOREGROUND_LOCK = Get-DeclaredReach -Name 'FLT'
 # The single definition. Explicit paths rather than a filename search, because `main.yml` is not unique
 # in this repo and a search would silently pick the wrong one.
 $ENVIRONMENT_FILES = @(
-    'packages/worker-fleet/src/provisioning/provision-nvda-worker.ps1'
+    (Get-LayerFile -Layer 'screenreader-fleet' -Relative 'src/provisioning/provision-nvda-worker.ps1')
     $RUN_SERVER
     $FOREGROUND_LOCK
     'packages/control/ansible/roles/worker/defaults/main.yml'