@out-of-order/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bart Spaans
+
+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/README.md

@@ -0,0 +1,52 @@
+# @out-of-order/cli
+
+> ⚠️ **Under heavy development.** Released, but the API is still changing and may break between versions.
+
+Audit any URL's tab order from the command line. It drives real Chromium (via [Playwright](https://playwright.dev/)), runs the [`@out-of-order/core`](../core) analyzer against the live page, and prints the findings to stdout. Pipe them into an AI agent or gate a CI job on the exit code.
+
+## Install
+
+```bash
+pnpm add -D @out-of-order/cli
+# playwright browsers, if not already present:
+pnpm exec playwright install chromium
+```
+
+## Use
+
+```bash
+out-of-order <url> [options]
+```
+
+```bash
+# text report to stdout, exits non-zero if the page has violations
+out-of-order https://example.com
+
+# machine-readable output, grouped per element
+out-of-order https://example.com --format by-element
+
+# wait for a selector before auditing a JS-heavy page
+out-of-order https://example.com --wait "main [role=dialog]"
+
+# open a headed browser with the live overlay, Ctrl-C to quit
+out-of-order https://example.com --overlay
+```
+
+## Options
+
+| Option              | What it does                                                       |
+| ------------------- | ------------------------------------------------------------------ |
+| `--format <name>`   | Output shape: `text` (default) or `by-element`.                    |
+| `--overlay`         | Open a headed browser with the visual overlay instead of printing. |
+| `--wait <selector>` | Wait for a selector before auditing (JS-heavy pages).              |
+| `--help`            | Show usage.                                                        |
+
+## Exit codes
+
+| Code | Meaning                                    |
+| ---- | ------------------------------------------ |
+| `0`  | Audited, tab order is valid.               |
+| `1`  | Audited, violations found.                 |
+| `2`  | Bad arguments, or the page failed to load. |
+
+Because it exits `1` on any violation, dropping `out-of-order <url>` into a CI step fails the build on a broken tab order.

package/dist/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+import { chromium } from "playwright";
+var FORMATS = ["by-element", "text"];
+var USAGE = `out-of-order <url> [options]
+
+  --format <name>      Output shape: ${FORMATS.join(" | ")} (default: text).
+  --overlay            Open a headed browser with the visual overlay; Ctrl-C to quit.
+  --wait <selector>    Wait for a selector before auditing (JS-heavy pages).
+  --help               Show this message.`;
+var { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    format: { type: "string", default: "text" },
+    overlay: { type: "boolean", default: false },
+    wait: { type: "string" },
+    help: { type: "boolean", default: false }
+  }
+});
+if (values.help) {
+  process.stdout.write(USAGE + "\n");
+  process.exit(0);
+}
+var url = positionals[0];
+if (!url) {
+  process.stderr.write(USAGE + "\n");
+  process.exit(2);
+}
+var format = values.format;
+if (!FORMATS.includes(format)) {
+  process.stderr.write(`Unknown --format "${format}".
+${USAGE}
+`);
+  process.exit(2);
+}
+var here = dirname(fileURLToPath(import.meta.url));
+async function open(page, targetUrl) {
+  const response = await page.goto(targetUrl, { waitUntil: "networkidle" });
+  if (response && !response.ok()) {
+    return response;
+  }
+  if (values.wait) {
+    await page.waitForSelector(values.wait);
+  }
+  return response;
+}
+if (values.overlay) {
+  const overlaySource = readFileSync(join(here, "inject-overlay.global.js"), "utf8");
+  const browser2 = await chromium.launch({ headless: false });
+  const context = await browser2.newContext({
+    viewport: null,
+    bypassCSP: true
+  });
+  const page = await context.newPage();
+  await page.addInitScript({ content: overlaySource });
+  const response = await open(page, url);
+  if (response && !response.ok()) {
+    process.stderr.write(`${url} returned HTTP ${response.status()}
+`);
+    await browser2.close();
+    process.exit(2);
+  }
+  process.stderr.write("Overlay mounted. Ctrl-C to quit.\n");
+  await new Promise((resolve) => {
+    browser2.on("disconnected", () => resolve());
+    process.on("SIGINT", () => resolve());
+  });
+  await browser2.close().catch(() => {
+  });
+  process.exit(0);
+}
+var injectSource = readFileSync(join(here, "inject.global.js"), "utf8");
+var browser = await chromium.launch();
+try {
+  const page = await browser.newPage();
+  await page.addInitScript({ content: injectSource });
+  const response = await open(page, url);
+  if (response && !response.ok()) {
+    throw new Error(`${url} returned HTTP ${response.status()}`);
+  }
+  const out = await page.evaluate((fmt) => {
+    const ooo = window.__ooo;
+    const result = ooo.audit(document, { format: fmt });
+    const violations = result.violations;
+    const output = typeof violations === "string" ? violations : JSON.stringify(violations, null, 2);
+    return { output, valid: result.valid };
+  }, format);
+  process.stdout.write(out.output + "\n");
+  process.exitCode = out.valid ? 0 : 1;
+} catch (err) {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+`);
+  process.exitCode = 2;
+} finally {
+  await browser.close();
+}