@invariant-ui/cli 0.0.0-stage → 0.2.0

package/dist/browser-verify/runner.js

@@ -0,0 +1,175 @@
+import { allowedOrigins } from "./spec.js";
+export const DEFAULT_VIEWPORT = { width: 1280, height: 800 };
+export const DEFAULT_TIMEOUT_MS = 5000;
+const describeStep = (s) => s.action === "press"
+    ? `press ${s.key}`
+    : `${s.action} ${s.selector}${s.action === "fill" ? ` with "${s.value}"` : ""}`;
+const message = (e) => e instanceof Error ? (e.message.split("\n")[0] ?? "failed") : String(e);
+async function runStep(page, s) {
+    if (s.action === "click")
+        return page.click(s.selector);
+    if (s.action === "fill")
+        return page.fill(s.selector, s.value);
+    if (s.action === "press")
+        return page.press(s.key);
+    return page.waitFor(s.selector);
+}
+async function evaluate(page, e) {
+    switch (e.kind) {
+        case "visible": {
+            const ok = await page.isVisible(e.selector);
+            return ok
+                ? { status: "pass", reason: `${e.selector} is visible` }
+                : {
+                    status: "fail",
+                    reason: `${e.selector} is not visible`,
+                    suggestion: "Check the selector, and that the element renders and is not hidden."
+                };
+        }
+        case "hidden": {
+            const ok = !(await page.isVisible(e.selector));
+            return ok
+                ? { status: "pass", reason: `${e.selector} is not visible` }
+                : { status: "fail", reason: `${e.selector} is visible, and should not be` };
+        }
+        case "text": {
+            const text = await page.text(e.selector);
+            if (text === null)
+                return { status: "fail", reason: `${e.selector} was not found` };
+            const trimmed = text.replace(/\s+/g, " ").trim();
+            if (e.equals !== undefined)
+                return trimmed === e.equals
+                    ? { status: "pass", reason: `${e.selector} reads "${e.equals}"` }
+                    : {
+                        status: "fail",
+                        reason: `${e.selector} reads "${trimmed.slice(0, 120)}", expected "${e.equals}"`
+                    };
+            if (e.contains !== undefined)
+                return trimmed.includes(e.contains)
+                    ? { status: "pass", reason: `${e.selector} contains "${e.contains}"` }
+                    : {
+                        status: "fail",
+                        reason: `${e.selector} reads "${trimmed.slice(0, 120)}", which lacks "${e.contains}"`
+                    };
+            return { status: "fail", reason: "a text expectation needs equals or contains" };
+        }
+        case "focused": {
+            const ok = await page.isFocused(e.selector);
+            return ok
+                ? { status: "pass", reason: `focus is on ${e.selector}` }
+                : {
+                    status: "fail",
+                    reason: `focus is on ${await page.activeElement()}, not ${e.selector}`,
+                    suggestion: "Check what moves focus here, such as autofocus, a focus trap or a focus call after the action."
+                };
+        }
+        case "tab-order": {
+            for (const [i, sel] of e.selectors.entries()) {
+                await page.press("Tab");
+                if (!(await page.isFocused(sel)))
+                    return {
+                        status: "fail",
+                        reason: `Tab ${i + 1} should reach ${sel}, but focus is on ${await page.activeElement()}`,
+                        suggestion: "Check the order of focusable elements, tabindex values and anything that traps or skips focus."
+                    };
+            }
+            return { status: "pass", reason: `Tab visits ${e.selectors.join(", then ")} in that order` };
+        }
+        case "contains": {
+            const ok = await page.contains(e.outer, e.inner);
+            return ok
+                ? { status: "pass", reason: `${e.inner} is inside ${e.outer}` }
+                : { status: "fail", reason: `${e.inner} is not inside ${e.outer} in the rendered page` };
+        }
+        case "count": {
+            const n = await page.count(e.selector);
+            const low = e.min !== undefined && n < e.min;
+            const high = e.max !== undefined && n > e.max;
+            return low || high
+                ? {
+                    status: "fail",
+                    reason: `${n} match ${e.selector}, expected ${e.min !== undefined ? `at least ${e.min}` : ""}${e.min !== undefined && e.max !== undefined ? " and " : ""}${e.max !== undefined ? `at most ${e.max}` : ""}`
+                }
+                : { status: "pass", reason: `${n} match ${e.selector}` };
+        }
+    }
+}
+async function runOne(driver, spec, scenario, viewport) {
+    const url = new URL(scenario.path, spec.baseUrl).toString();
+    const context = { browser: driver.browser, browserVersion: driver.version(), viewport, url };
+    const base = {
+        scenario: scenario.id,
+        level: "runtime-verified",
+        context,
+        ...(scenario.pattern ? { pattern: scenario.pattern } : {}),
+        ...(scenario.constraint ? { constraint: scenario.constraint } : {})
+    };
+    const everything = (status, reason, check, suggestion) => [
+        { ...base, check, kind: "scenario", status, reason, ...(suggestion ? { suggestion } : {}) }
+    ];
+    let page;
+    try {
+        page = await driver.open({
+            viewport,
+            allowedOrigins: allowedOrigins(spec),
+            timeoutMs: spec.timeoutMs ?? DEFAULT_TIMEOUT_MS
+        });
+    }
+    catch (e) {
+        return everything("error", `could not open a page: ${message(e)}`, "open");
+    }
+    try {
+        try {
+            await page.goto(url);
+        }
+        catch (e) {
+            return everything("error", `could not load ${url}: ${message(e)}`, "goto", "Is the app running at baseUrl?");
+        }
+        for (const [i, s] of scenario.steps.entries())
+            try {
+                await runStep(page, s);
+            }
+            catch (e) {
+                return everything("error", `step ${i + 1} (${describeStep(s)}) failed: ${message(e)}`, `step ${i + 1}`, "The expectations were not checked. Fix the step or the selector.");
+            }
+        const out = [];
+        for (const [i, e] of scenario.expect.entries()) {
+            try {
+                const r = await evaluate(page, e);
+                out.push({ ...base, check: `expect ${i + 1}`, kind: e.kind, ...r });
+            }
+            catch (err) {
+                out.push({
+                    ...base,
+                    check: `expect ${i + 1}`,
+                    kind: e.kind,
+                    status: "error",
+                    reason: `could not check: ${message(err)}`
+                });
+            }
+        }
+        return out;
+    }
+    finally {
+        await page.close().catch(() => undefined);
+    }
+}
+/**
+ * Runs each scenario, once per viewport, in a fresh page. Results are runtime findings tied to the browser,
+ * its version, the viewport and the URL. The run opens no browser by itself: the driver does, and a caller that
+ * never builds a driver never touches one.
+ */
+export async function runBrowserChecks(driver, spec) {
+    const results = [];
+    for (const scenario of spec.scenarios)
+        for (const viewport of scenario.viewports ?? [DEFAULT_VIEWPORT])
+            results.push(...(await runOne(driver, spec, scenario, viewport)));
+    return results;
+}
+export const summarizeBrowser = (results) => {
+    const out = { pass: 0, fail: 0, error: 0 };
+    for (const r of results)
+        out[r.status]++;
+    return out;
+};
+//# sourceMappingURL=runner.js.map

package/dist/browser-verify/spec.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+export const BROWSER_SPEC_FILE = "invariant.browser.json";
+export const BROWSER_RESULTS_FILE = "invariant.browser-results.json";
+export const BROWSERS = ["chromium", "firefox", "webkit"];
+/** Selectors are CSS or Playwright selector strings. A spec holds data only: it can never carry code to run. */
+const selector = z.string().min(1).max(300);
+const step = z.discriminatedUnion("action", [
+    z.strictObject({ action: z.literal("click"), selector }),
+    z.strictObject({ action: z.literal("fill"), selector, value: z.string().max(1000) }),
+    z.strictObject({ action: z.literal("press"), key: z.string().min(1).max(40) }),
+    z.strictObject({ action: z.literal("wait-for"), selector })
+]);
+const expectation = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("visible"), selector }),
+    z.strictObject({ kind: z.literal("hidden"), selector }),
+    z.strictObject({
+        kind: z.literal("text"),
+        selector,
+        equals: z.string().max(1000).optional(),
+        contains: z.string().max(1000).optional()
+    }),
+    z.strictObject({ kind: z.literal("focused"), selector }),
+    /** Pressing Tab from the current focus visits these, in this order. */
+    z.strictObject({ kind: z.literal("tab-order"), selectors: z.array(selector).min(1).max(50) }),
+    /** The element for `inner` is inside the element for `outer` in the rendered page. */
+    z.strictObject({ kind: z.literal("contains"), outer: selector, inner: selector }),
+    z.strictObject({
+        kind: z.literal("count"),
+        selector,
+        min: z.number().int().nonnegative().optional(),
+        max: z.number().int().nonnegative().optional()
+    })
+]);
+const viewport = z.strictObject({
+    width: z.number().int().min(200).max(4000),
+    height: z.number().int().min(200).max(4000)
+});
+export const scenarioSchema = z.strictObject({
+    id: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9._-]*$/)
+        .max(80),
+    description: z.string().min(1).max(500).optional(),
+    /** The approved pattern and constraint this scenario gives a runtime check for. Recorded, never inferred. */
+    pattern: z.string().min(1).max(200).optional(),
+    constraint: z.string().min(1).max(200).optional(),
+    /** A path on the base URL, starting with `/`. */
+    path: z
+        .string()
+        .regex(/^\/[^\s]*$/)
+        .max(500),
+    /** One result is produced per viewport; no viewport means 1280 by 800. */
+    viewports: z.array(viewport).min(1).max(6).optional(),
+    steps: z.array(step).max(100).default([]),
+    expect: z.array(expectation).min(1).max(100)
+});
+export const browserSpecSchema = z.strictObject({
+    $schema: z.string().optional(),
+    version: z.literal(1),
+    baseUrl: z.url().max(300),
+    /** Origins besides the base URL the page may load from. Everything else is blocked. */
+    allowOrigins: z.array(z.url().max(300)).max(20).optional(),
+    browser: z.enum(BROWSERS).optional(),
+    timeoutMs: z.number().int().min(500).max(60000).optional(),
+    scenarios: z.array(scenarioSchema).min(1).max(200)
+});
+export function parseSpec(text, name = BROWSER_SPEC_FILE) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        return { ok: false, message: `${name} is not valid JSON: ${error.message}` };
+    }
+    const parsed = browserSpecSchema.safeParse(raw);
+    if (!parsed.success) {
+        const i = parsed.error.issues[0];
+        return {
+            ok: false,
+            message: `${name} is invalid at ${i?.path.join(".") || "(root)"}: ${i?.message ?? "schema error"}`
+        };
+    }
+    const ids = parsed.data.scenarios.map((s) => s.id);
+    const dup = ids.find((id, i) => ids.indexOf(id) !== i);
+    if (dup)
+        return { ok: false, message: `${name}: scenario id "${dup}" is used twice` };
+    return { ok: true, value: parsed.data };
+}
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+/** A run reaches only the base URL's origin and listed origins, and the base URL must be local unless listed. */
+export function checkOrigins(spec) {
+    const base = new URL(spec.baseUrl);
+    if (!LOOPBACK.has(base.hostname) &&
+        !(spec.allowOrigins ?? []).some((o) => new URL(o).origin === base.origin))
+        return `baseUrl ${base.origin} is not local. To verify a remote site, list its origin in allowOrigins to say that is intended.`;
+    return undefined;
+}
+export function allowedOrigins(spec) {
+    return [
+        ...new Set([new URL(spec.baseUrl).origin, ...(spec.allowOrigins ?? []).map((o) => new URL(o).origin)])
+    ].sort();
+}
+//# sourceMappingURL=spec.js.map

package/dist/cli/args.js

@@ -0,0 +1,77 @@
+import { parseArgs } from "node:util";
+import { CliError } from "./errors.js";
+const OPTIONS = {
+    cwd: { type: "string" },
+    config: { type: "string" },
+    dir: { type: "string" },
+    "trust-config": { type: "boolean" },
+    json: { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+    force: { type: "boolean" },
+    id: { type: "string" },
+    to: { type: "string" },
+    fresh: { type: "boolean" },
+    watch: { type: "boolean" },
+    "keep-ir": { type: "boolean" },
+    severity: { type: "string" },
+    type: { type: "string" },
+    subject: { type: "string" },
+    evidence: { type: "boolean" },
+    command: { type: "string" },
+    "command-arg": { type: "string", multiple: true },
+    "dry-run": { type: "boolean" },
+    format: { type: "string" },
+    "fail-on": { type: "string" },
+    framework: { type: "string" },
+    as: { type: "string" },
+    role: { type: "string" },
+    reference: { type: "string" },
+    note: { type: "string" },
+    source: { type: "string" },
+    kind: { type: "string" },
+    category: { type: "string" },
+    status: { type: "string" },
+    direction: { type: "string" },
+    depth: { type: "string" },
+    variation: { type: "string" },
+    "min-files": { type: "string" },
+    "min-uses": { type: "string" },
+    similarity: { type: "string" },
+    all: { type: "boolean" },
+    name: { type: "string" },
+    spec: { type: "string" },
+    browser: { type: "string" },
+    url: { type: "string" },
+    "update-baseline": { type: "boolean" },
+    "no-baseline": { type: "boolean" },
+    posture: { type: "string" },
+    session: { type: "string" },
+    client: { type: "string" },
+    only: { type: "string" },
+    quiet: { type: "boolean" },
+    yes: { type: "boolean" },
+    "confirm-contract": { type: "boolean" },
+    "no-agent": { type: "boolean" },
+    paths: { type: "string" },
+    contract: { type: "string" },
+    ci: { type: "boolean" },
+    "no-ci": { type: "boolean" },
+    "no-rules": { type: "boolean" },
+    "no-publish": { type: "boolean" }
+};
+export function parse(argv) {
+    try {
+        const { values, positionals } = parseArgs({
+            args: argv,
+            options: OPTIONS,
+            allowPositionals: true,
+            strict: true
+        });
+        return { values, positionals };
+    }
+    catch (error) {
+        throw new CliError(error.message.replace(/\. To specify.*$/, ""));
+    }
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/baseline.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+export const BASELINE_FILE = "invariant.baseline.json";
+const baselineSchema = z.strictObject({
+    version: z.literal(1),
+    /** Violations that existed when the baseline was taken. They are hidden, not fixed, and counted. */
+    violations: z.array(z.strictObject({
+        file: z.string(),
+        code: z.string(),
+        message: z.string(),
+        count: z.number().int().positive()
+    }))
+});
+/** Line numbers are left out so moving code does not bring an old finding back as new. */
+const keyOf = (v) => `${v.file}\u0000${v.code}\u0000${v.message}`;
+export function makeBaseline(violations) {
+    const counts = new Map();
+    for (const v of violations) {
+        const k = keyOf(v);
+        const held = counts.get(k);
+        if (held)
+            held.count++;
+        else
+            counts.set(k, { file: v.file, code: v.code, message: v.message, count: 1 });
+    }
+    const list = [...counts.values()].sort((a, b) => a.file !== b.file
+        ? a.file < b.file
+            ? -1
+            : 1
+        : a.code !== b.code
+            ? a.code < b.code
+                ? -1
+                : 1
+            : a.message < b.message
+                ? -1
+                : 1);
+    return { version: 1, violations: list };
+}
+export function readBaseline(file) {
+    if (!existsSync(file))
+        return undefined;
+    const parsed = baselineSchema.safeParse(JSON.parse(readFileSync(file, "utf8")));
+    if (!parsed.success)
+        throw new Error(`${file} is not a valid baseline. Regenerate it with \`invariant validate <path...> --update-baseline\`.`);
+    return parsed.data;
+}
+export const writeBaseline = (file, baseline) => writeFileSync(file, `${JSON.stringify(baseline, null, 2)}\n`);
+/** A violation is hidden only while the baseline still has room for one like it. A new one beyond the count shows. */
+export function applyBaseline(violations, baseline) {
+    const room = new Map(baseline.violations.map((v) => [keyOf(v), v.count]));
+    const fresh = [];
+    let hidden = 0;
+    for (const v of violations) {
+        const left = room.get(keyOf(v)) ?? 0;
+        if (left > 0) {
+            room.set(keyOf(v), left - 1);
+            hidden++;
+        }
+        else
+            fresh.push(v);
+    }
+    return { fresh, hidden };
+}
+//# sourceMappingURL=baseline.js.map

package/dist/cli/cli.js

@@ -0,0 +1,121 @@
+import path from "node:path";
+import { parse } from "./args.js";
+import * as commands from "./commands.js";
+import * as browserCommands from "./commands-browser.js";
+import * as discoverCommands from "./commands-discover.js";
+import * as enforcementCommands from "./commands-enforcement.js";
+import * as governance from "./commands-governance.js";
+import * as hookCommands from "./commands-hook.js";
+import * as patterns from "./commands-patterns.js";
+import * as setupCommands from "./commands-setup.js";
+import * as validation from "./commands-validate.js";
+import { CliError } from "./errors.js";
+import { CLI_NAME, CLI_VERSION } from "./version.js";
+export const HELP = `${CLI_NAME} ${CLI_VERSION}: compile a design system into a machine-readable contract
+
+usage: ${CLI_NAME} <command> [options]
+
+  init                          detect sources and write invariant.config.json
+  source add <type> [path]      add a source (react, vue, angular, storybook, tokens)
+  source remove <id>            remove a configured source
+  source list                   list configured sources
+  analyze                       extract each source and report what was found
+  compile                       build the contract, evidence, diagnostics, review and report [--watch recompiles when sources change]
+  components list | inspect <name>
+  tokens list
+  setup                         one command: compile, propose patterns from your code, connect your AI tool   [--yes] [--confirm-contract] [--as name] [--paths a,b] [--only 1,3|none] [--posture gate-errors|warn|off] [--contract dir] [--no-agent] [--ci|--no-ci] [--no-rules] [--no-baseline] [--no-publish]
+  browser run                   check a running app in a real browser (opt-in; needs Playwright)   [--spec file] [--browser chromium|firefox|webkit] [--url base]
+  discover <path...>            find structures that recur in your code and write them as candidates   [--min-files n] [--min-uses n] [--similarity 0-1] [--depth n]
+  candidates list | show <id> | accept|reject|defer <id> | promote <id>   review candidates   [--status s] [--kind k] [--all] [--as name] [--note why] [--id pattern-id]
+  patterns list | inspect <name> | resolve <name> | search <query> | relationships <name>   [--category c] [--status s] [--direction out|in|both] [--depth n] [--variation v] [--evidence]
+  conflicts list                [--severity s] [--type t] [--subject id]
+  validate <path...>            check application code against the contract [--format text|json|github|sarif] [--fail-on error|warning|never]
+  verify                        check the compiled output itself [--fresh recompiles and compares]
+  rules                         list the validation rules
+  policy list                   list approved policies (written in invariant.policies.json)
+  review list | show <id>       what needs a human decision
+  review approve|reject|resolve|accept|dismiss <id> --as <name>   record a decision in invariant.decisions.json
+  export --to <dir>             write a portable copy of the artifacts
+  mcp                           serve the compiled contract to AI tools over stdio (read-only)
+  hook                          check an agent's Write/Edit against the contract and answer in its hook format (stdin payload) [--posture gate-errors|warn|off] [--client claude-code|cursor] [--quiet]
+  enforcement report            the enforcement timeline of an agent session [--session id|--all] [--format text|html] [--to file]
+  agent init <client|all>       write MCP config and skills for claude-code, cursor, codex, windsurf
+  agent list                    list supported clients
+
+options: --version --help --cwd <dir> --config <file> --dir <output dir> --json --force --trust-config --keep-ir --evidence
+         agent init: --command <exe> --command-arg <arg> --dry-run
+exit codes: 0 ok, 1 findings or invalid output, 2 bad usage or input
+`;
+/** Runs one command line. Returns the process exit code and never throws. */
+export async function run(argv, io) {
+    try {
+        const args = parse(argv);
+        if (args.values.version) {
+            io.stdout(`${CLI_VERSION}\n`);
+            return 0;
+        }
+        const [command] = args.positionals;
+        if (args.values.help || !command || command === "help") {
+            io.stdout(HELP);
+            return command || args.values.help ? 0 : 2;
+        }
+        const context = { io, args, cwd: path.resolve(io.cwd, args.values.cwd ?? ".") };
+        switch (command) {
+            case "init":
+                return await commands.init(context);
+            case "source":
+                return await commands.source(context);
+            case "analyze":
+                return await commands.analyze(context);
+            case "compile":
+                return await commands.compileCommand(context);
+            case "components":
+                return await commands.components(context);
+            case "tokens":
+                return await commands.tokens(context);
+            case "patterns":
+                return await patterns.patterns(context);
+            case "discover":
+                return await discoverCommands.discoverCommand(context);
+            case "setup":
+                return await setupCommands.setup(context);
+            case "browser":
+                return await browserCommands.browser(context);
+            case "candidates":
+                return await discoverCommands.candidatesCommand(context);
+            case "conflicts":
+                return await commands.conflicts(context);
+            case "validate":
+                return await validation.validate(context);
+            case "verify":
+                return await commands.verify(context);
+            case "rules":
+                return await validation.rules(context);
+            case "review":
+                return await governance.review(context);
+            case "policy":
+                return await governance.policy(context);
+            case "export":
+                return await commands.exportCommand(context);
+            case "mcp":
+                return await commands.mcp(context);
+            case "hook":
+                return await hookCommands.hook(context);
+            case "enforcement":
+                return await enforcementCommands.enforcement(context);
+            case "agent":
+                return await commands.agent(context);
+            default:
+                throw new CliError(`unknown command "${command}". Run \`${CLI_NAME} help\`.`);
+        }
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            io.stderr(`error: ${error.message}\n`);
+            return error.exitCode;
+        }
+        io.stderr(`error: ${error.stack ?? String(error)}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli/commands-browser.js

@@ -0,0 +1,104 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { BROWSER_RESULTS_FILE, BROWSER_SPEC_FILE, BROWSERS, checkOrigins, PlaywrightMissing, parseSpec, playwrightDriver, runBrowserChecks, summarizeBrowser } from "../browser-verify/index.js";
+import { json, outputDir, print, writableDir } from "./commands.js";
+import { CliError } from "./errors.js";
+import { table } from "./format.js";
+import { loadCompiled } from "./store.js";
+import { CLI_NAME } from "./version.js";
+const USAGE = `usage: ${CLI_NAME} browser run [--spec ${BROWSER_SPEC_FILE}] [--browser chromium|firefox|webkit] [--url <base url>] [--json]
+Runs the scenarios in the spec against a running app in a headless browser. Opt-in: it needs Playwright in your project,
+and nothing else in ${CLI_NAME} starts a browser. Results are runtime findings, kept apart from \`validate\`.`;
+/** `invariant browser run`: runtime checks in a real browser, separate from static validation. */
+export async function browser(c) {
+    const [, sub] = c.args.positionals;
+    if (sub !== "run")
+        throw new CliError(USAGE);
+    const specFile = path.resolve(c.cwd, c.args.values.spec ?? BROWSER_SPEC_FILE);
+    if (!existsSync(specFile))
+        throw new CliError(`no ${path.basename(specFile)}. Write one (see docs/specifications/browser-verification-v1.md), or pass --spec.`);
+    const parsed = parseSpec(readFileSync(specFile, "utf8"), path.basename(specFile));
+    if (!parsed.ok)
+        throw new CliError(parsed.message);
+    const spec = c.args.values.url ? { ...parsed.value, baseUrl: c.args.values.url } : parsed.value;
+    if (c.args.values.url) {
+        try {
+            new URL(c.args.values.url);
+        }
+        catch {
+            throw new CliError("--url must be a full URL such as http://localhost:3000");
+        }
+    }
+    const refused = checkOrigins(spec);
+    if (refused)
+        throw new CliError(refused);
+    const name = (c.args.values.browser ?? spec.browser ?? "chromium");
+    if (!BROWSERS.includes(name))
+        throw new CliError(`--browser must be one of: ${BROWSERS.join(", ")}`);
+    const notes = [];
+    try {
+        const { contract } = loadCompiled(await outputDir(c));
+        const patterns = new Map(contract.patterns.map((p) => [p.id, p]));
+        const constraints = new Set(contract.constraints.map((x) => x.id));
+        for (const s of spec.scenarios) {
+            if (s.pattern && !patterns.has(s.pattern))
+                notes.push(`${s.id}: pattern ${s.pattern} is not in the contract`);
+            if (s.constraint && !constraints.has(s.constraint))
+                notes.push(`${s.id}: constraint ${s.constraint} is not in the contract`);
+        }
+    }
+    catch {
+        // No compiled contract is fine: scenarios are checked without linking them to patterns.
+    }
+    let driver;
+    try {
+        driver = await (c.io.browserDriver ?? playwrightDriver)(name, c.cwd);
+    }
+    catch (error) {
+        if (error instanceof PlaywrightMissing)
+            throw new CliError(error.message);
+        throw error;
+    }
+    let results;
+    try {
+        results = await runBrowserChecks(driver, spec);
+    }
+    finally {
+        await driver.close().catch(() => undefined);
+    }
+    const summary = summarizeBrowser(results);
+    const report = {
+        version: 1,
+        kind: "runtime",
+        spec: path.basename(specFile),
+        browser: { name, version: driver.version() },
+        summary,
+        notes,
+        results
+    };
+    const dir = await writableDir(c);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, BROWSER_RESULTS_FILE), `${JSON.stringify(report, null, 2)}\n`);
+    if (c.args.values.json)
+        json(c, report);
+    else {
+        print(c, `${name} ${driver.version()}: ${summary.pass} passed, ${summary.fail} failed, ${summary.error} could not run (runtime results; static results are from \`validate\`)`);
+        for (const n of notes)
+            print(c, `note: ${n}`);
+        const bad = results.filter((r) => r.status !== "pass");
+        if (bad.length > 0)
+            print(c, `\n${table(["scenario", "check", "status", "viewport", "why"], bad.map((r) => [
+                r.scenario,
+                r.check,
+                r.status,
+                `${r.context.viewport.width}x${r.context.viewport.height}`,
+                r.reason
+            ]))}`);
+        for (const r of bad)
+            if (r.suggestion)
+                print(c, `  ${r.scenario} ${r.check}: ${r.suggestion}`);
+        print(c, `\nwritten to ${BROWSER_RESULTS_FILE}`);
+    }
+    return summary.fail + summary.error > 0 ? 1 : 0;
+}
+//# sourceMappingURL=commands-browser.js.map