automatica11y 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Instructure, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/automatica11y.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "automatica11y",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Test and compare the accessibility of web pages, Storybook builds, and npm component libraries.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "automatica11y": "bin/automatica11y.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "SKILL.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "tsc -p jsconfig.json"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@guidepup/virtual-screen-reader": "^0.33.0",
+    "accessibility-checker-engine": "^4.0.34",
+    "axe-core": "^4.14.0",
+    "esbuild": "^0.28.2",
+    "playwright-core": "^1.64.0",
+    "valibot": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,49 @@
+import { auditCommand } from "./commands/audit.js";
+import { compareCommand } from "./commands/compare.js";
+import { EXIT, UsageError, runSavedPlan, usage } from "./commands/common.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { initSkillCommand } from "./commands/init-skill.js";
+import { ownVersion } from "./env/versions.js";
+
+const COMMANDS = {
+  audit: auditCommand,
+  compare: compareCommand,
+  run: runSavedPlan,
+  doctor: doctorCommand,
+  "init-skill": initSkillCommand,
+};
+
+/**
+ * Run the CLI and return its exit code. Takes its streams and environment as arguments so tests can drive it.
+ * @param {string[]} argv Arguments after the program name.
+ * @param {Partial<import("./commands/common.js").Io>} [overrides]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, overrides = {}) {
+  /** @type {import("./commands/common.js").Io} */
+  const io = { stdout: process.stdout, stderr: process.stderr, cwd: process.cwd(), env: process.env, ...overrides };
+  const [first, ...rest] = argv;
+
+  if (first === "--version" || first === "-v") {
+    io.stdout.write(`${ownVersion()}\n`);
+    return EXIT.OK;
+  }
+  if (first === "--help" || first === "-h") {
+    io.stdout.write(usage());
+    return EXIT.OK;
+  }
+  const handler = first ? COMMANDS[/** @type {keyof typeof COMMANDS} */ (first)] : undefined;
+  if (!handler) {
+    io.stderr.write(first ? `Unknown command "${first}".\n\n${usage()}` : usage());
+    return EXIT.USAGE;
+  }
+  try {
+    return await handler(rest, io);
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.stderr.write(`${error.message}\n\nRun "automatica11y ${first} --help" for options.\n`);
+      return EXIT.USAGE;
+    }
+    throw error;
+  }
+}

package/src/commands/audit.js

@@ -0,0 +1,4 @@
+import { runCommand } from "./common.js";
+
+/** @param {string[]} argv @param {import("./common.js").Io} io */
+export const auditCommand = (argv, io) => runCommand("audit", argv, io);

package/src/commands/common.js

@@ -0,0 +1,274 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { checkEnvironment } from "../env/browser.js";
+import { readToolVersions } from "../env/versions.js";
+import { buildPlan, findDuplicateLabel } from "../plan/build-plan.js";
+import { loadMappingFile } from "../plan/mapping.js";
+import { runPlan } from "../run/run-plan.js";
+import { ARCHETYPES, ENGINES, FAIL_MODES, IMPACTS, LEVELS, LIB_A11Y, TIERS, TOOLKIT_LEVELS, WCAG_VERSIONS, parsePlan } from "../schema.js";
+
+export const EXIT = { OK: 0, FAIL_THRESHOLD: 1, USAGE: 2, ENVIRONMENT: 3, ALL_TARGETS_FAILED: 4, NOT_IMPLEMENTED: 70 };
+
+/** A bad command line. The CLI prints the message plus a usage hint and exits 2. */
+export class UsageError extends Error {}
+
+/**
+ * @typedef {{ stdout: { write(text: string): unknown }, stderr: { write(text: string): unknown }, cwd: string, env: NodeJS.ProcessEnv, fetch?: import("../plan/classify.js").FetchLike, npmView?: (spec: string) => Promise<any>, installPackage?: Function, platform?: NodeJS.Platform }} Io
+ */
+
+const OPTION_DEFS = /** @type {const} */ ({
+  wcag: { type: "string" },
+  level: { type: "string" },
+  tiers: { type: "string" },
+  engine: { type: "string" },
+  archetypes: { type: "string" },
+  "lib-a11y": { type: "string" },
+  mapping: { type: "string" },
+  plan: { type: "boolean" },
+  out: { type: "string" },
+  "max-stories": { type: "string" },
+  "fail-on-axe": { type: "string" },
+  "fail-on-ibm": { type: "string" },
+  "fail-mode": { type: "string" },
+  help: { type: "boolean", short: "h" },
+});
+
+/** Split a comma list and check every item against the allowed values. */
+function parseList(flag, text, allowed) {
+  const items = [...new Set(text.split(",").map((item) => item.trim()).filter(Boolean))];
+  if (items.length === 0) throw new UsageError(`--${flag} needs at least one value. Choose from: ${allowed.join(", ")}.`);
+  const bad = items.filter((item) => !allowed.includes(item));
+  if (bad.length) throw new UsageError(`Unknown ${flag} value${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}. Choose from: ${allowed.join(", ")}.`);
+  return items;
+}
+
+/** @param {string} flag @param {string} value @param {string[]} allowed */
+function parseChoice(flag, value, allowed) {
+  if (!allowed.includes(value)) throw new UsageError(`--${flag} must be one of: ${allowed.join(", ")}. Got "${value}".`);
+  return value;
+}
+
+/**
+ * Turn `audit` or `compare` arguments into plan options and raw targets. Throws UsageError on any problem.
+ * @param {"audit" | "compare"} command
+ * @param {string[]} argv
+ */
+export function parseRunArgs(command, argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTION_DEFS, allowPositionals: true, strict: true });
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message.split(". ")[0] : String(error));
+  }
+  const { values, positionals } = parsed;
+  if (values.help) return { help: true, targets: [], planOnly: false, options: null };
+
+  if (command === "audit" && positionals.length !== 1) {
+    throw new UsageError(positionals.length === 0 ? "audit needs one target." : "audit takes one target. Use compare for more than one.");
+  }
+  if (command === "compare" && positionals.length < 2) {
+    throw new UsageError("compare needs at least two targets.");
+  }
+  if (positionals.some((target) => !target.trim())) throw new UsageError("A target can't be empty.");
+  const duplicate = findDuplicateLabel(positionals);
+  if (duplicate) throw new UsageError(`Two targets use the label "${duplicate}". Labels must be unique.`);
+
+  const tiers = values.tiers ? parseList("tiers", values.tiers, TIERS) : [...TIERS];
+  const engines = values.engine ? parseList("engine", values.engine, ENGINES) : [...ENGINES];
+  const libA11y = values["lib-a11y"] ? parseList("lib-a11y", values["lib-a11y"], LIB_A11Y) : [...LIB_A11Y];
+  const archetypes = values.archetypes ? parseList("archetypes", values.archetypes, ARCHETYPES) : null;
+
+  let maxStories = 200;
+  if (values["max-stories"] !== undefined) {
+    maxStories = Number(values["max-stories"]);
+    if (!Number.isInteger(maxStories) || maxStories < 1) throw new UsageError(`--max-stories must be a whole number of 1 or more. Got "${values["max-stories"]}".`);
+  }
+
+  const axeFlag = values["fail-on-axe"];
+  const ibmFlag = values["fail-on-ibm"];
+  const modeFlag = values["fail-mode"];
+  /** @type {import("valibot").InferOutput<typeof import("../schema.js").FailConfigSchema> | null} */
+  let fail = null;
+  if (axeFlag === undefined && ibmFlag === undefined) {
+    if (modeFlag !== undefined) throw new UsageError("--fail-mode needs --fail-on-axe, --fail-on-ibm, or both.");
+  } else {
+    if (!tiers.includes("rules")) throw new UsageError("The fail flags check the rules tier. Add rules to --tiers or drop the fail flags.");
+    const axe = axeFlag === undefined ? null : parseChoice("fail-on-axe", axeFlag, IMPACTS);
+    const ibm = ibmFlag === undefined ? null : Number(parseChoice("fail-on-ibm", ibmFlag, TOOLKIT_LEVELS.map(String)));
+    if (axe && !engines.includes("axe")) throw new UsageError("--fail-on-axe needs the axe engine. Add axe to --engine or drop the flag.");
+    if (ibm && !engines.includes("ibm")) throw new UsageError("--fail-on-ibm needs the ibm engine. Add ibm to --engine or drop the flag.");
+    fail = { mode: /** @type {"any" | "all"} */ (modeFlag === undefined ? "any" : parseChoice("fail-mode", modeFlag, FAIL_MODES)), axe: /** @type {any} */ (axe), ibm: /** @type {any} */ (ibm) };
+  }
+
+  const options = {
+    wcag: /** @type {any} */ (values.wcag === undefined ? "2.2" : parseChoice("wcag", values.wcag, WCAG_VERSIONS)),
+    level: /** @type {any} */ (values.level === undefined ? "AA" : parseChoice("level", values.level, LEVELS)),
+    tiers: /** @type {any} */ (tiers),
+    engines: /** @type {any} */ (engines),
+    libA11y: /** @type {any} */ (libA11y),
+    archetypes: /** @type {any} */ (archetypes),
+    mapping: values.mapping ?? null,
+    maxStories,
+    out: values.out ?? "./a11y-report",
+    fail,
+  };
+  return { help: false, targets: positionals, planOnly: Boolean(values.plan), options };
+}
+
+/** One line describing what a target resolved to. */
+export function describeTarget(target) {
+  if (target.status === "failed") return `failed: ${target.reason}`;
+  const r = target.resolved ?? {};
+  if (target.kind?.startsWith("npm")) return `${r.name}@${r.version ?? r.requested ?? "latest"}${r.framework ? ` (${r.framework})` : ""}`;
+  return r.url ?? r.path ?? "";
+}
+
+/** @param {ReturnType<typeof parsePlan>} plan @param {string} planPath @param {boolean} planOnly @param {Io} io */
+function printSummary(plan, planPath, planOnly, io) {
+  const o = plan.options;
+  const lines = [
+    `automatica11y ${plan.command} ${planOnly ? "plan" : "run"}`,
+    `  WCAG ${o.wcag} level ${o.level}, tiers: ${o.tiers.join(", ")}, engines: ${o.engines.join(", ")}`,
+  ];
+  if (o.fail) lines.push(`  Fail checks (${o.fail.mode}): ${[o.fail.axe && `axe ${o.fail.axe}`, o.fail.ibm && `ibm level ${o.fail.ibm}`].filter(Boolean).join(", ")}`);
+  lines.push("  Targets:");
+  const width = Math.max(...plan.targets.map((t) => t.id.length));
+  for (const t of plan.targets) {
+    lines.push(`    ${t.id.padEnd(width)}  ${(t.kind ?? "-").padEnd(10)}  ${describeTarget(t)}${t.evidenceLevel ? `  (${t.evidenceLevel} evidence)` : ""}`);
+  }
+  lines.push(`  Wrote ${planPath}`);
+  io.stdout.write(`${lines.join("\n")}\n`);
+}
+
+/** Warn when installed tool versions differ from the ones a saved plan recorded. */
+function versionWarnings(plan) {
+  const now = readToolVersions({ chromium: plan.tools.chromium });
+  return Object.entries(plan.tools)
+    .filter(([key, was]) => was && now[key] && now[key] !== was)
+    .map(([key, was]) => `${key} was ${was} when this plan was made and is ${now[key]} now.`);
+}
+
+/**
+ * Write plan.json, then stop (plan only) or run the plan.
+ * @param {ReturnType<typeof parsePlan>} plan
+ * @param {{ planOnly: boolean, savedPlanPath?: string }} mode
+ * @param {Io} io
+ */
+export async function executePlan(plan, { planOnly, savedPlanPath }, io) {
+  const outDir = resolve(io.cwd, plan.options.out);
+  const planPath = resolve(outDir, "plan.json");
+  if (!savedPlanPath || resolve(io.cwd, savedPlanPath) !== planPath) {
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+  }
+  printSummary(plan, planPath, planOnly, io);
+  for (const warning of savedPlanPath ? versionWarnings(plan) : []) io.stderr.write(`Warning: ${warning}\n`);
+
+  if (plan.targets.every((t) => t.status === "failed")) {
+    io.stderr.write("Every target failed to resolve.\n");
+    return EXIT.ALL_TARGETS_FAILED;
+  }
+  if (planOnly) return EXIT.OK;
+
+  return runPlan(plan, io);
+}
+
+/**
+ * Shared body of `audit` and `compare`.
+ * @param {"audit" | "compare"} command
+ * @param {string[]} argv
+ * @param {Io} io
+ */
+export async function runCommand(command, argv, io) {
+  const parsed = parseRunArgs(command, argv);
+  if (parsed.help) {
+    io.stdout.write(usage(command));
+    return EXIT.OK;
+  }
+  const options = /** @type {NonNullable<typeof parsed.options>} */ (parsed.options);
+  let browserVersion = null;
+  if (!parsed.planOnly) {
+    const env = await checkEnvironment({ env: io.env, platform: io.platform });
+    browserVersion = env.browser?.version ?? null;
+  }
+  let mapping = null;
+  if (options.mapping) {
+    try {
+      mapping = loadMappingFile(options.mapping, io.cwd);
+    } catch (error) {
+      throw new UsageError(error instanceof Error ? error.message : String(error));
+    }
+  }
+  const built = await buildPlan({ command, targets: parsed.targets, options, browserVersion, ctx: { cwd: io.cwd, fetch: io.fetch, npmView: io.npmView } });
+  if (mapping) {
+    const ids = new Set(built.targets.map((t) => t.id));
+    const unknown = Object.keys(mapping).filter((id) => !ids.has(id));
+    if (unknown.length) throw new UsageError(`The mapping has entries for ${unknown.join(", ")}, which ${unknown.length === 1 ? "isn't" : "aren't"} a target in this run. Targets here: ${[...ids].join(", ")}.`);
+    for (const target of built.targets) target.mapping = mapping[target.id] ?? null;
+  }
+  const plan = parsePlan(built);
+  return executePlan(plan, { planOnly: parsed.planOnly }, io);
+}
+
+/** `run --plan <file>`: re-run a saved plan. */
+export async function runSavedPlan(argv, io) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { plan: { type: "string" }, help: { type: "boolean", short: "h" } }, allowPositionals: false, strict: true });
+  } catch (error) {
+    throw new UsageError(error instanceof Error ? error.message.split(". ")[0] : String(error));
+  }
+  if (parsed.values.help) {
+    io.stdout.write(usage("run"));
+    return EXIT.OK;
+  }
+  const file = parsed.values.plan;
+  if (!file) throw new UsageError("run needs --plan <plan.json>.");
+  let plan;
+  try {
+    plan = parsePlan(JSON.parse(readFileSync(resolve(io.cwd, file), "utf8")));
+  } catch (error) {
+    throw new UsageError(`Can't read the plan ${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return executePlan(plan, { planOnly: false, savedPlanPath: file }, io);
+}
+
+const FLAGS = `Options:
+  --wcag <2.0|2.1|2.2>        WCAG version. Default 2.2.
+  --level <A|AA|AAA>          Conformance level. Default AA.
+  --tiers <list>              rules, interactions, vsr. Default all three.
+  --engine <list>             axe, ibm. Default both.
+  --archetypes <list>         Limit npm and Storybook targets to these archetypes.
+  --lib-a11y <list>           on, off. Default both.
+  --mapping <file>            Archetype mapping file.
+  --max-stories <n>           Storybook story cap. Default 200.
+  --plan                      Resolve and print the plan, then stop.
+  --out <dir>                 Output directory. Default ./a11y-report.
+  --fail-on-axe <impact>      minor, moderate, serious, or critical.
+  --fail-on-ibm <level>       1, 2, or 3 (IBM Toolkit level).
+  --fail-mode <any|all>       How to combine fail checks. Default any.
+`;
+
+/** @param {string} [command] */
+export function usage(command) {
+  const header = {
+    audit: "Usage: automatica11y audit <target> [options]\n\nCheck how accessible one target is.\n\n",
+    compare: "Usage: automatica11y compare <target> <target> [<target>...] [options]\n\nCompare two or more targets.\n\n",
+    run: "Usage: automatica11y run --plan <plan.json>\n\nRe-run a saved plan.\n",
+  }[command ?? ""];
+  if (command === "run") return header;
+  if (header) {
+    return `${header}A target is [label=]<spec>. A spec is a package name, an http(s) URL, or a path starting with ./, ../, /, ~, or file:.\n\n${FLAGS}`;
+  }
+  return `Usage:
+  automatica11y audit <target> [options]
+  automatica11y compare <target> <target> [<target>...] [options]
+  automatica11y run --plan <plan.json>
+  automatica11y doctor
+  automatica11y init-skill [--dest <dir>]
+  automatica11y --version
+
+Run a command with --help for its options.
+`;
+}

package/src/commands/compare.js

@@ -0,0 +1,4 @@
+import { runCommand } from "./common.js";
+
+/** @param {string[]} argv @param {import("./common.js").Io} io */
+export const compareCommand = (argv, io) => runCommand("compare", argv, io);

package/src/commands/doctor.js

@@ -0,0 +1,20 @@
+import { checkEnvironment } from "../env/browser.js";
+import { EXIT } from "./common.js";
+
+/** @param {string[]} _argv @param {import("./common.js").Io} io */
+export async function doctorCommand(_argv, io) {
+  const result = await checkEnvironment({ env: io.env, platform: io.platform });
+  const lines = ["automatica11y doctor"];
+  const nodeProblem = result.problems.find((p) => p.id === "node");
+  lines.push(`  Node     ${result.node}  ${nodeProblem ? "problem" : "ok"}`);
+  if (result.browser) {
+    const { kind, version, path } = result.browser;
+    lines.push(`  Browser  ${kind}${version ? ` ${version}` : ""}  ok`, `           ${path}`);
+  } else {
+    lines.push("  Browser  not found  problem");
+  }
+  io.stdout.write(`${lines.join("\n")}\n`);
+  if (result.ok) return EXIT.OK;
+  for (const problem of result.problems) io.stderr.write(`\n${problem.message}\n  Fix: ${problem.fix}\n`);
+  return EXIT.ENVIRONMENT;
+}

package/src/commands/init-skill.js

@@ -0,0 +1,7 @@
+import { EXIT } from "./common.js";
+
+/** @param {string[]} _argv @param {import("./common.js").Io} io */
+export async function initSkillCommand(_argv, io) {
+  io.stderr.write("init-skill isn't built yet. It arrives in M8.\n");
+  return EXIT.NOT_IMPLEMENTED;
+}

package/src/env/browser.js

@@ -0,0 +1,136 @@
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+
+export const INSTALL_COMMAND = "npx playwright-core install --only-shell chromium";
+export const BROWSER_ENV_VAR = "AUTOMATICA11Y_CHROME";
+export const MIN_NODE_MAJOR = 20;
+
+/**
+ * @typedef {{ kind: "chrome" | "chromium" | "headless-shell" | "custom", path: string, version: string | null }} Browser
+ * @typedef {{ id: string, message: string, fix: string }} Problem
+ */
+
+/** Known install locations for Chrome and Chromium, by platform. */
+function candidatePaths(platform, env) {
+  if (platform === "darwin") {
+    return [
+      { kind: "chrome", path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" },
+      { kind: "chromium", path: "/Applications/Chromium.app/Contents/MacOS/Chromium" },
+    ];
+  }
+  if (platform === "win32") {
+    const roots = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA].filter(Boolean);
+    return roots.map((root) => ({ kind: "chrome", path: join(/** @type {string} */ (root), "Google", "Chrome", "Application", "chrome.exe") }));
+  }
+  const names = [
+    ["chrome", "google-chrome"],
+    ["chrome", "google-chrome-stable"],
+    ["chromium", "chromium"],
+    ["chromium", "chromium-browser"],
+  ];
+  const dirs = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  return names.flatMap(([kind, name]) => dirs.map((dir) => ({ kind, path: join(dir, name) })));
+}
+
+/** Where Playwright keeps the browsers `playwright-core install` downloads. */
+function playwrightCacheDir(platform, env) {
+  if (env.PLAYWRIGHT_BROWSERS_PATH && env.PLAYWRIGHT_BROWSERS_PATH !== "0") return env.PLAYWRIGHT_BROWSERS_PATH;
+  if (platform === "darwin") return join(homedir(), "Library", "Caches", "ms-playwright");
+  if (platform === "win32") return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "ms-playwright");
+  return join(homedir(), ".cache", "ms-playwright");
+}
+
+/** Find a headless shell that `playwright-core install --only-shell chromium` downloaded. */
+function findHeadlessShell(platform, env) {
+  const root = playwrightCacheDir(platform, env);
+  const names = new Set(["chrome-headless-shell", "chrome-headless-shell.exe", "headless_shell"]);
+  /** @param {string} dir @param {number} depth @returns {string | null} */
+  const search = (dir, depth) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return null;
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && names.has(entry.name)) return join(dir, entry.name);
+    }
+    if (depth === 0) return null;
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const found = search(join(dir, entry.name), depth - 1);
+        if (found) return found;
+      }
+    }
+    return null;
+  };
+  let shells;
+  try {
+    shells = readdirSync(root).filter((name) => name.startsWith("chromium_headless_shell-")).sort().reverse();
+  } catch {
+    return null;
+  }
+  for (const shell of shells) {
+    const found = search(join(root, shell), 3);
+    if (found) return found;
+  }
+  return null;
+}
+
+/** @param {string} path @returns {Promise<string | null>} */
+function readVersion(path) {
+  return new Promise((resolve) => {
+    execFile(path, ["--version"], { timeout: 5000 }, (error, stdout) => {
+      const match = error ? null : /(\d+\.\d+\.\d+\.\d+)/.exec(stdout);
+      resolve(match ? match[1] : null);
+    });
+  });
+}
+
+/**
+ * Find a browser we can drive. Prefers an explicit override, then installed Chrome or Chromium,
+ * then the Playwright headless shell. Never imports Playwright.
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform }} [options]
+ * @returns {Promise<{ browser: Browser | null, problem: Problem | null }>}
+ */
+export async function findBrowser({ env = process.env, platform = process.platform } = {}) {
+  const override = env[BROWSER_ENV_VAR];
+  if (override) {
+    if (!existsSync(override)) {
+      return {
+        browser: null,
+        problem: { id: "browser", message: `${BROWSER_ENV_VAR} points to a file that doesn't exist: ${override}`, fix: `Fix or unset ${BROWSER_ENV_VAR}, or run: ${INSTALL_COMMAND}` },
+      };
+    }
+    return { browser: { kind: "custom", path: override, version: await readVersion(override) }, problem: null };
+  }
+  for (const candidate of candidatePaths(platform, env)) {
+    if (existsSync(candidate.path)) {
+      return { browser: { kind: /** @type {"chrome" | "chromium"} */ (candidate.kind), path: candidate.path, version: await readVersion(candidate.path) }, problem: null };
+    }
+  }
+  const shell = findHeadlessShell(platform, env);
+  if (shell) return { browser: { kind: "headless-shell", path: shell, version: await readVersion(shell) }, problem: null };
+  return {
+    browser: null,
+    problem: { id: "browser", message: "No Chrome or Chromium found.", fix: `Install Chrome, or run: ${INSTALL_COMMAND}` },
+  };
+}
+
+/**
+ * Check everything a real run needs. Used by `doctor` and by real runs.
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, nodeVersion?: string }} [options]
+ */
+export async function checkEnvironment({ env = process.env, platform = process.platform, nodeVersion = process.versions.node } = {}) {
+  /** @type {Problem[]} */
+  const problems = [];
+  const major = Number(nodeVersion.split(".")[0]);
+  if (!(major >= MIN_NODE_MAJOR)) {
+    problems.push({ id: "node", message: `Node ${nodeVersion} is too old. automatica11y needs Node ${MIN_NODE_MAJOR} or newer.`, fix: `Install Node ${MIN_NODE_MAJOR} or newer from https://nodejs.org.` });
+  }
+  const { browser, problem } = await findBrowser({ env, platform });
+  if (problem) problems.push(problem);
+  return { ok: problems.length === 0, node: nodeVersion, browser, problems };
+}

package/src/env/versions.js

@@ -0,0 +1,60 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/** The packages whose resolved versions every plan and results file records. */
+const TOOL_PACKAGES = {
+  "axe-core": "axe-core",
+  "ibm-checker-engine": "accessibility-checker-engine",
+  "playwright-core": "playwright-core",
+  esbuild: "esbuild",
+  "guidepup-vsr": "@guidepup/virtual-screen-reader",
+};
+
+/**
+ * Read an installed package's version without importing the package itself.
+ * @param {string} name
+ * @returns {string | null} The version, or null when the package isn't installed.
+ */
+export function readPackageVersion(name) {
+  try {
+    return JSON.parse(readFileSync(require.resolve(`${name}/package.json`), "utf8")).version ?? null;
+  } catch {
+    // The package may hide its package.json behind an exports map. Walk up from its entry file.
+  }
+  try {
+    let dir = dirname(require.resolve(name));
+    for (let depth = 0; depth < 6; depth += 1) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        if (pkg.name === name) return pkg.version ?? null;
+      } catch {
+        // Keep walking.
+      }
+      dir = dirname(dir);
+    }
+  } catch {
+    // Not installed.
+  }
+  return null;
+}
+
+/** Version of automatica11y itself. */
+export function ownVersion() {
+  const url = new URL("../../package.json", import.meta.url);
+  return JSON.parse(readFileSync(url, "utf8")).version;
+}
+
+/**
+ * Resolved versions of every tool, keyed the way plan.json and results.json record them.
+ * @param {{ chromium?: string | null }} [extra]
+ */
+export function readToolVersions(extra = {}) {
+  /** @type {Record<string, string | null>} */
+  const tools = { node: process.versions.node, automatica11y: ownVersion() };
+  for (const [key, pkg] of Object.entries(TOOL_PACKAGES)) tools[key] = readPackageVersion(pkg);
+  tools.chromium = extra.chromium ?? null;
+  return tools;
+}

package/src/globals.d.ts

@@ -0,0 +1,10 @@
+/** Properties our init scripts and helpers put on the page's window. They only exist inside the browser. */
+interface Window {
+  __a11y: any;
+  __vsr: any;
+  __a11yClicks: number;
+  __a11yLast: any;
+  __a11yExports?: any;
+  __a11yDefined?: string[];
+  __a11yClosedShadowHosts?: string[];
+}

package/src/harness/browser.js

@@ -0,0 +1,20 @@
+import { findBrowser } from "../env/browser.js";
+
+export const VIEWPORT = { width: 1280, height: 800 };
+
+/**
+ * Launch the browser we found. Playwright loads here and nowhere else, so commands that never launch a browser never pay for it.
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform }} [options]
+ */
+export async function launchBrowser({ env, platform } = {}) {
+  const { browser: found, problem } = await findBrowser({ env, platform });
+  if (!found) throw new Error(problem?.message ?? "No browser found.");
+  let chromium;
+  try {
+    ({ chromium } = await import("playwright-core"));
+  } catch {
+    throw new Error("playwright-core isn't installed. Run: npm install playwright-core");
+  }
+  const browser = await chromium.launch({ executablePath: found.path, args: process.env.CI ? ["--no-sandbox"] : [] });
+  return { browser, found, version: browser.version() };
+}