@beryl-so/cli 0.1.0 → 0.5.0

package/dist/commands/tests.js

@@ -1,12 +1,41 @@
 import fs from "node:fs";
 import { UsageError } from "../errors.js";
+import { lintPlan } from "../lint.js";
+import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
 import { arg, argList, flagBool, flagNum, flagStr, projectPath, readJsonFlag } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
 export const testCommands = [
+    {
+        name: "tests lint",
+        summary: "Validate a plan JSON file offline, before sending it to the server",
+        description: "Checks a plan against the published ActionPlan JSON Schema — every action's required " +
+            "fields, plus the two structural rules (the first EXECUTED step must be a goto, and at " +
+            "least one step across before + steps must be an expect). Runs entirely locally, so a " +
+            "malformed plan fails here instead of costing a server round-trip. " +
+            `Schema: ${ACTION_PLAN_SCHEMA.$id}`,
+        scope: "none",
+        flags: [
+            { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
+        ],
+        examples: ["beryl tests lint --file plan.json"],
+        async run(_ctx, input) {
+            const issues = lintPlan(readJsonFlag(input, "file"));
+            if (issues.length === 0) {
+                return { data: { valid: true, issues: [] }, human: "Plan is valid." };
+            }
+            return {
+                data: { valid: false, issues },
+                human: issues.map((i) => `${i.path}: ${i.message}`).join("\n"),
+                exitCode: 1,
+            };
+        },
+    },
     {
         name: "tests list",
         summary: "List the project's tests with their latest result",
         scope: "project",
+        groupDefault: true,
+        groupSummary: "Author, inspect, version, and heal a project's tests — the checks Beryl runs on each run.",
         flags: [{ name: "env", type: "string", description: "Filter by environment id" }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -44,19 +73,31 @@ export const testCommands = [
         name: "tests create",
         summary: "Create a test case from a JSON action plan — for tests authored locally, e.g. by your coding agent",
         description: "The plan is a JSON object whose steps are {action, selector, url, value, ...}: the first " +
-            "step must be a goto, and at least one step must be an expect. By default the plan is " +
-            "verified in a real browser before the test is accepted.",
+            "EXECUTED step must be a goto, and at least one step must be an expect. By default the plan " +
+            "is verified in a real browser before the test is accepted. Optional `before` and `after` " +
+            "arrays hold setup and teardown steps: `after` runs even when a main step fails, which is " +
+            "how a create/update/delete test cleans up the record it made on the runs that go red.",
         scope: "project",
         flags: [
             { name: "title", type: "string", required: true, description: "Title for the new test" },
             { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
+            {
+                name: "description",
+                type: "string",
+                description: "1–3 sentences stating what this test proves — the immutable outcome Beryl's healing " +
+                    "checks against. State the purpose, not the steps; the one observable signal that's true " +
+                    "only if the flow worked.",
+            },
             {
                 name: "no-verify",
                 type: "boolean",
                 description: "Skip the compile-time browser/AI verification — trust the authored plan as-is",
             },
         ],
-        examples: ['beryl tests create --title "Checkout happy path" --file plan.json'],
+        examples: [
+            'beryl tests create --title "Checkout happy path" --file plan.json',
+            'beryl tests create --title "Checkout happy path" --file plan.json --description "Proves a shopper can buy a product: after paying, an order-confirmation page with an order number appears."',
+        ],
         async run(ctx, input) {
             const title = flagStr(input, "title");
             if (!title)
@@ -67,6 +108,7 @@ export const testCommands = [
                     title,
                     plan: readJsonFlag(input, "file"),
                     verify: !flagBool(input, "no-verify"),
+                    description: flagStr(input, "description"),
                 }),
             };
         },
@@ -74,19 +116,86 @@ export const testCommands = [
     {
         name: "tests set-plan",
         summary: "Replace a test's step plan from a JSON file (creates a new version)",
+        description: "Accepts the same plan shape as `tests create`, including the optional `before` and " +
+            "`after` sections — `after` runs on pass and on fail, so cleanup happens even when the " +
+            "test goes red. Pass `--description` when the re-authored plan changes what the test " +
+            "proves; omit it to keep the test's existing intent.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
             { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
+            {
+                name: "description",
+                type: "string",
+                description: "1–3 sentences stating what this test proves — the immutable outcome Beryl's healing " +
+                    "checks against. State the purpose, not the steps; the one observable signal that's true " +
+                    "only if the flow worked. Omit to keep the test's existing intent.",
+            },
         ],
         examples: ["beryl tests plan 4f… > plan.json  # edit, then:", "beryl tests set-plan 4f… --file plan.json"],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             return {
-                data: await ctx.client.patch(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan`, { json_plan: readJsonFlag(input, "file") }),
+                data: await ctx.client.patch(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan`, { json_plan: readJsonFlag(input, "file"), description: flagStr(input, "description") }),
+            };
+        },
+    },
+    {
+        name: "tests rename",
+        summary: "Rename a test",
+        scope: "project",
+        args: [
+            { name: "test-id", description: "Test id", required: true },
+            { name: "title", description: "New title", required: true },
+        ],
+        examples: ['beryl tests rename 4f… "Checkout happy path"'],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.patch(testPath(workspaceId, projectId, arg(input, "test-id")), {
+                    title: arg(input, "title"),
+                }),
+            };
+        },
+    },
+    {
+        name: "tests quarantine",
+        summary: "Mute a flaky test: it keeps running, but its failures stop failing the run",
+        description: "A quarantined test still executes and its result is still recorded and visible — its " +
+            "red just doesn't count towards the run's verdict, so it can't red-light a deploy. Use " +
+            "it on a persistently flaky test instead of deleting it (which destroys the history) or " +
+            "asking support to deactivate it (which stops it running at all). `off` un-quarantines.",
+        scope: "project",
+        args: [
+            { name: "test-id", description: "Test id", required: true },
+            { name: "state", description: "on | off", required: true },
+        ],
+        examples: ["beryl tests quarantine 4f… on", "beryl tests quarantine 4f… off"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const state = arg(input, "state").toLowerCase();
+            if (state !== "on" && state !== "off") {
+                throw new UsageError(`Expected "on" or "off", got "${arg(input, "state")}"`);
+            }
+            return {
+                data: await ctx.client.patch(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/quarantine`, { quarantined: state === "on" }),
             };
         },
     },
+    {
+        name: "tests delete",
+        summary: "Delete a test, its version history, and its results",
+        scope: "project",
+        args: [{ name: "test-id", description: "Test id", required: true }],
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const testId = arg(input, "test-id");
+            await ctx.confirm(`Delete test ${testId} and all its history?`, flagBool(input, "force"));
+            await ctx.client.del(testPath(workspaceId, projectId, testId));
+            return { human: "Deleted." };
+        },
+    },
     {
         name: "tests recompile",
         summary: "Validate + verify an edited plan against the live site before persisting",

package/dist/commands/watch.js

@@ -23,15 +23,28 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes) {
             if (kind === "run_started") {
                 ctx.err(dim(`run ${runId} started`));
             }
+            else if (kind === "test_retrying") {
+                ctx.err(yellow(`↻ retrying ${dim(String(ev.test_result_id))} (attempt ${ev.attempt_no} failed)`));
+            }
             else if (kind === "test_completed") {
                 const key = `${ev.test_result_id}:${ev.status}`;
                 if (!seen.has(key)) {
                     seen.add(key);
                     const ok = ev.status === "passed";
-                    const mark = ok ? green("✓") : red("✗");
+                    // A quarantined red still prints — the result is recorded and visible —
+                    // but marked as muted so it doesn't read as a build-breaking failure.
+                    const muted = Boolean(ev.quarantined) && !ok;
+                    const mark = ok ? green("✓") : muted ? yellow("⚠") : red("✗");
+                    const label = muted
+                        ? yellow(`${String(ev.status)} (quarantined)`)
+                        : statusColor(String(ev.status));
                     const duration = ev.duration_ms ? dim(` ${Math.round(Number(ev.duration_ms) / 1000)}s`) : "";
-                    const error = ev.error_message ? red(` — ${String(ev.error_message).slice(0, 120)}`) : "";
-                    ctx.err(`${mark} ${statusColor(String(ev.status))} ${dim(String(ev.test_result_id))}${duration}${error}`);
+                    const errorText = ev.error_message ? ` — ${String(ev.error_message).slice(0, 120)}` : "";
+                    const error = errorText ? (muted ? dim(errorText) : red(errorText)) : "";
+                    // A pass that took a retry is still a pass, but say so — a flake absorbed in
+                    // silence is how a suite that gates deploys stops being trusted.
+                    const flaky = ev.flaky ? yellow(` flaky (passed on attempt ${ev.attempt_no})`) : "";
+                    ctx.err(`${mark} ${label} ${dim(String(ev.test_result_id))}${duration}${flaky}${error}`);
                 }
             }
         }
@@ -46,11 +59,19 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes) {
     }
     if (signal?.aborted)
         throw new CliError(`Timed out after ${timeoutMinutes} minutes`, 1);
+    // Quarantined reds are excluded from `failed` by the API (they land in their own
+    // counter), so they never reach this sum and never flip the exit code — but they
+    // are always reported, so a green build never silently hides a muted failure.
     const failed = (counters.failed ?? 0) + (counters.errored ?? 0);
     const passed = counters.passed ?? 0;
+    // A flaky pass likewise exits 0 — absorbing a transient blip is the point — but it
+    // is reported too, so a suite that only stays green by retrying can't hide it.
+    const extra = (counters.cancelled ? yellow(`, ${counters.cancelled} cancelled`) : "") +
+        (counters.quarantined ? yellow(`, ${counters.quarantined} quarantined`) : "") +
+        (counters.flaky ? yellow(`, ${counters.flaky} flaky`) : "");
     const summary = failed > 0
-        ? red(`${failed} failed`) + `, ${passed} passed`
-        : green(`${passed} passed`) + (counters.cancelled ? yellow(`, ${counters.cancelled} cancelled`) : "");
+        ? red(`${failed} failed`) + `, ${passed} passed` + extra
+        : green(`${passed} passed`) + extra;
     if (!ctx.json)
         ctx.err(`\n${statusColor(finalStatus)}: ${summary}`);
     const exitCode = finalStatus === "completed" && failed === 0 ? 0 : 1;

package/dist/commands/workspaces.js

@@ -6,6 +6,7 @@ export const workspaceCommands = [
     {
         name: "workspaces list",
         summary: "List workspaces you belong to",
+        groupSummary: "Create and manage workspaces, and pick the one your commands act on by default.",
         async run(ctx) {
             const rows = (await ctx.client.get("/workspaces/"));
             return { data: rows };
@@ -115,6 +116,7 @@ export const workspaceCommands = [
     {
         name: "members list",
         summary: "List workspace members",
+        groupSummary: "Manage who belongs to a workspace and their roles.",
         scope: "workspace",
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
@@ -154,6 +156,7 @@ export const workspaceCommands = [
     {
         name: "invites send",
         summary: "Invite someone to the workspace by email",
+        groupSummary: "Send, list, and revoke workspace invitations, and accept ones sent to you.",
         scope: "workspace",
         args: [{ name: "email", description: "Invitee email", required: true }],
         flags: [

package/dist/context.js

@@ -23,6 +23,7 @@ export function createContext(options) {
         config,
         json,
         interactive: options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        mcp: options.mcp,
         out: options.out ?? ((text) => process.stdout.write(text + "\n")),
         err: options.err ?? ((text) => process.stderr.write(text + "\n")),
         async prompt(question) {

package/dist/detect.js

@@ -0,0 +1,88 @@
+// Login-wall detection for `projects create`. The API takes the visitor's answer as
+// authoritative and never infers it (a null choice there strands the project in
+// needs_capture), so the guess has to happen here, before the request.
+//
+// The asymmetry that shapes this: "gated" can be proven from the response, "public"
+// cannot. An app that renders its login screen client-side serves the same 200 + empty
+// shell as a public landing page, so absence of a login wall is not evidence of a public
+// site. We therefore only claim `public` on positive evidence of real content, and leave
+// everything else undecided — the caller prompts on a TTY and fails loudly in CI.
+const FETCH_TIMEOUT_MS = 10_000;
+const PASSWORD_FIELD = /<input[^>]+type\s*=\s*["']?password["']?/i;
+// Sign-in copy anywhere in the markup. A public marketing page carries this too (its
+// header "Log in" link), so it never proves gated — it only withholds a confident public.
+const LOGIN_COPY = /\b(sign in|signin|log in|login|sign up|create (an )?account)\b/i;
+// Body text with the markup stripped. An SPA shell collapses to ~nothing here, which is
+// exactly the signal that we cannot see the real page and must not guess.
+function visibleText(html) {
+    return html
+        .replace(/<(script|style|noscript|template)\b[^>]*>[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&[a-z#0-9]+;/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+const MIN_PUBLIC_TEXT = 200;
+const isLoginish = (url) => /(^|\/)(login|signin|sign-in|auth|authorize|sso|account\/login|users\/sign_in)(\/|$)/i.test(url.pathname);
+function classify(root, final, status, body) {
+    if (status === 401 || status === 403)
+        return { choice: "gated", reason: `the site answered HTTP ${status}` };
+    if (status < 200 || status >= 300)
+        return { reason: `the site answered HTTP ${status}` };
+    const redirected = final.href !== root.href;
+    const hasPasswordField = PASSWORD_FIELD.test(body);
+    if (redirected && isLoginish(final))
+        return { choice: "gated", reason: `it redirects to a sign-in page (${final.href})` };
+    if (redirected && hasPasswordField)
+        return {
+            choice: "gated",
+            reason: `it redirects to a page with a password field (${final.href})`,
+        };
+    // The root itself is a sign-in page: either the URL says so, or it serves a password
+    // field and nothing else of substance.
+    const text = visibleText(body);
+    if (isLoginish(final) && hasPasswordField)
+        return { choice: "gated", reason: "its root URL is a sign-in page" };
+    if (hasPasswordField && text.length < MIN_PUBLIC_TEXT)
+        return { choice: "gated", reason: "the page is a sign-in form" };
+    // Below here nothing proves gated — but only real, login-free content proves public.
+    if (hasPasswordField)
+        return { reason: "the page serves both a password field and other content" };
+    if (text.length < MIN_PUBLIC_TEXT)
+        return {
+            reason: "the page renders its content in the browser, so its markup does not show whether " +
+                "there is a login wall",
+        };
+    if (LOGIN_COPY.test(text))
+        return { reason: "the page mentions signing in but shows no login form" };
+    return { choice: "public", reason: "the page serves content with no sign-in wall" };
+}
+export async function detectAuthGating(rootUrl) {
+    let root;
+    try {
+        root = new URL(rootUrl);
+    }
+    catch {
+        return { reason: `"${rootUrl}" is not a URL we can fetch` };
+    }
+    if (root.protocol !== "http:" && root.protocol !== "https:")
+        return { reason: `"${rootUrl}" is not an http(s) URL` };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(root, {
+            redirect: "follow",
+            signal: controller.signal,
+            headers: { "User-Agent": "beryl-cli", Accept: "text/html,*/*" },
+        });
+        const body = await res.text();
+        return classify(root, new URL(res.url), res.status, body);
+    }
+    catch (err) {
+        return { reason: `the site could not be fetched (${err.message})` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export { classify as classifyForTest };

package/dist/lint.js

@@ -0,0 +1,125 @@
+import { ACTION_PLAN_SCHEMA } from "./schema.generated.js";
+const typeOf = (value) => {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (Number.isInteger(value))
+        return "integer";
+    return typeof value;
+};
+const typeMatches = (value, type) => type === "number" ? typeof value === "number" : typeOf(value) === type;
+function resolve(schema, root) {
+    const ref = schema.$ref;
+    if (typeof ref !== "string")
+        return schema;
+    const key = ref.replace("#/$defs/", "");
+    return { ...(root.$defs?.[key] ?? {}), ...schema, $ref: undefined };
+}
+function matches(value, schema, root) {
+    return validate(value, schema, root, "").length === 0;
+}
+function validate(value, raw, root, path) {
+    const schema = resolve(raw, root);
+    const issues = [];
+    const at = (message) => issues.push({ path: path || "(root)", message });
+    if (schema.anyOf && !schema.anyOf.some((s) => matches(value, s, root))) {
+        // Optional fields are emitted as anyOf[<real type>, null]. When the value isn't
+        // null, the null branch is noise — report the real branch's own failure ("must
+        // match ^[A-Za-z0-9_]+$") instead of a useless "expected string or null".
+        const real = schema.anyOf.filter((s) => resolve(s, root).type !== "null");
+        if (value !== null && real.length === 1) {
+            return validate(value, real[0], root, path);
+        }
+        const types = schema.anyOf
+            .map((s) => resolve(s, root).type ?? resolve(s, root).enum?.join("|"))
+            .filter(Boolean)
+            .join(" or ");
+        at(types ? `expected ${types}` : "does not match any allowed shape");
+        return issues;
+    }
+    if (typeof schema.type === "string" && !typeMatches(value, schema.type)) {
+        at(`expected ${schema.type}, got ${typeOf(value)}`);
+        return issues;
+    }
+    if (schema.not && matches(value, schema.not, root)) {
+        at(schema.not.type === "null" ? "must not be null" : "is not allowed here");
+        return issues;
+    }
+    if (schema.enum && !schema.enum.includes(value)) {
+        at(`must be one of: ${schema.enum.join(", ")}`);
+    }
+    if (schema.const !== undefined && value !== schema.const) {
+        at(`must be ${JSON.stringify(schema.const)}`);
+    }
+    if (typeof value === "string") {
+        if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+            at(`must match ${schema.pattern}`);
+        }
+        // The server reads "" as absent for the truthiness-guarded fields (url, selector,
+        // key, capture_as/ref), so minLength is what keeps "" from linting clean and 422ing.
+        if (schema.minLength !== undefined && value.length < schema.minLength) {
+            at("must not be empty");
+        }
+    }
+    if (typeof value === "number") {
+        if (schema.minimum !== undefined && value < schema.minimum)
+            at(`must be >= ${schema.minimum}`);
+        if (schema.maximum !== undefined && value > schema.maximum)
+            at(`must be <= ${schema.maximum}`);
+    }
+    if (Array.isArray(value)) {
+        if (schema.minItems !== undefined && value.length < schema.minItems) {
+            at(`must have at least ${schema.minItems} item(s)`);
+        }
+        if (schema.contains && !value.some((v) => matches(v, schema.contains, root))) {
+            at(schema.$comment ?? "is missing a required entry");
+        }
+        schema.prefixItems?.forEach((s, i) => {
+            if (i < value.length)
+                issues.push(...validate(value[i], s, root, `${path}[${i}]`));
+        });
+        if (schema.items) {
+            value.forEach((v, i) => issues.push(...validate(v, schema.items, root, `${path}[${i}]`)));
+        }
+    }
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const object = value;
+        for (const key of schema.required ?? []) {
+            if (object[key] === undefined)
+                at(`missing required field "${key}"`);
+        }
+        for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+            if (object[key] !== undefined) {
+                issues.push(...validate(object[key], sub, root, path ? `${path}.${key}` : key));
+            }
+        }
+    }
+    for (const sub of schema.allOf ?? []) {
+        // if/then[/else] carries the per-action rules ("a fill needs a value") and the
+        // section-dependent plan rules (the first EXECUTED step is before[0] when there is a
+        // setup section, else steps[0]); a bare allOf entry carries the unconditional
+        // plan-level ones. Dropping `else` would silently skip the flat-plan branch — a plan
+        // that lints clean here and then 422s on the server, the exact hole this file closes.
+        if (sub.if) {
+            const branch = matches(value, sub.if, root) ? sub.then : sub.else;
+            if (branch) {
+                const found = validate(value, branch, root, path);
+                if (found.length && sub.$comment)
+                    at(sub.$comment);
+                else
+                    issues.push(...found);
+            }
+            continue;
+        }
+        const found = validate(value, sub, root, path);
+        if (found.length && sub.$comment)
+            at(sub.$comment);
+        else
+            issues.push(...found);
+    }
+    return issues;
+}
+export function lintPlan(plan) {
+    return validate(plan, ACTION_PLAN_SCHEMA, ACTION_PLAN_SCHEMA, "");
+}

package/dist/local-run.js

@@ -0,0 +1,168 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+// The customer already has @playwright/test (the MCP `init` wires it), so we invoke it
+// as an external rather than bundling it — the CLI's zero-runtime-dep rule. In a node_modules
+// install `playwright` is on PATH; otherwise fall back to `npx playwright`, exactly as the
+// cloud runner does.
+export const PLAYWRIGHT_INSTALL_HINT = "Local Playwright not found. Install it in this project, then re-run:\n" +
+    "  npm i -D @playwright/test && npx playwright install chromium";
+// Isolate the run from any playwright.config.ts in the customer's repo: a stray `testMatch`
+// would exclude our spec (a zero-test run that reads as a false pass), and a `use.baseURL` /
+// `use.storageState` / `globalSetup` there would silently retarget or reauth the run we mean
+// to be a clean local execution of exactly this one spec. `testDir` pins us to our own dir.
+// Reporter is left to the CLI flag + PLAYWRIGHT_JSON_OUTPUT_NAME (as the cloud runner does), so
+// the report lands at exactly our path regardless of what a reporter here would default to.
+const ISOLATING_CONFIG = (testDir, artifactsDir) => `import { defineConfig } from "@playwright/test";\n` +
+    `export default defineConfig({\n` +
+    `  testDir: ${JSON.stringify(testDir)},\n` +
+    `  testMatch: "beryl-local.spec.ts",\n` +
+    `  outputDir: ${JSON.stringify(artifactsDir)},\n` +
+    `  fullyParallel: false,\n` +
+    `});\n`;
+const PASSING = new Set(["passed", "expected"]);
+const SKIPPED = new Set(["skipped"]);
+export class PlaywrightMissingError extends Error {
+}
+function runProcess(command, args, cwd, env) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { cwd, env });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => resolve({ code: null, stdout, stderr, spawnError: err }));
+        child.on("close", (code) => resolve({ code, stdout, stderr }));
+    });
+}
+// `npx playwright` is the portable fallback when no local binary is on PATH — it resolves
+// the project's @playwright/test without us hard-coding a node_modules path.
+function playwrightBase(cwd) {
+    const binName = process.platform === "win32" ? "playwright.cmd" : "playwright";
+    const local = path.join(cwd, "node_modules", ".bin", binName);
+    if (fs.existsSync(local))
+        return { command: local, args: ["test"] };
+    const npx = process.platform === "win32" ? "npx.cmd" : "npx";
+    return { command: npx, args: ["playwright", "test"] };
+}
+// "unknown command 'test'" is the Python `playwright` shim (no `test` subcommand); the module
+// errors mean @playwright/test isn't installed. Either way the actionable answer is the same
+// install hint, not a stack trace.
+function looksLikePlaywrightMissing(r) {
+    if (r.spawnError?.code === "ENOENT")
+        return true;
+    const blob = `${r.stdout}\n${r.stderr}`;
+    return (/unknown command ['"]?test/i.test(blob) ||
+        /Cannot find module ['"]@playwright\/test/i.test(blob) ||
+        /npm ERR!.*could not determine executable|npx.*not found/i.test(blob));
+}
+export function parsePlaywrightReport(data) {
+    const results = [];
+    const walk = (suites) => {
+        for (const suite of suites) {
+            for (const spec of suite.specs ?? []) {
+                for (const test of spec.tests ?? []) {
+                    // Last attempt is the verdict — retries can precede it.
+                    const last = test.results?.[test.results.length - 1];
+                    const errors = (last?.errors ?? []).map((e) => e.message).filter(Boolean);
+                    const artifacts = (last?.attachments ?? [])
+                        .map((a) => a.path)
+                        .filter((p) => Boolean(p));
+                    results.push({
+                        name: spec.title ?? "(unnamed)",
+                        status: last?.status ?? "unknown",
+                        duration_ms: last?.duration,
+                        ...(errors.length ? { error: errors.join("\n") } : {}),
+                        artifacts,
+                    });
+                }
+            }
+            if (suite.suites)
+                walk(suite.suites);
+        }
+    };
+    walk(data.suites ?? []);
+    return results;
+}
+// passed/failed exclude skips; an empty set is neither — the caller treats it as a failure
+// because a run that executed nothing is not evidence of a pass.
+export function tally(results) {
+    const passed = results.filter((r) => PASSING.has(r.status)).length;
+    const skipped = results.filter((r) => SKIPPED.has(r.status)).length;
+    return { passed, failed: results.length - passed - skipped };
+}
+function parseReport(reportPath) {
+    return parsePlaywrightReport(JSON.parse(fs.readFileSync(reportPath, "utf8")));
+}
+/**
+ * Write `spec` next to the caller's project, run it with their local @playwright/test, and
+ * parse the JSON report into a structured pass/fail summary. Artifacts + the spec + report land
+ * in `dir` when given (kept), otherwise in a temp dir that is cleaned up. Throws
+ * {@link PlaywrightMissingError} when no runnable @playwright/test is found so the caller can
+ * print an install hint.
+ */
+export async function runSpecLocally(opts) {
+    const cwd = process.cwd();
+    // The spec + isolating config MUST sit inside the project tree: Playwright resolves
+    // `@playwright/test` (imported by both) by walking UP from the config file, so a config in
+    // /tmp finds no node_modules and every run dies with "Cannot find module '@playwright/test'".
+    // A run dir under cwd walks up into the project's node_modules; it's always cleaned up.
+    const runDir = fs.mkdtempSync(path.join(cwd, ".beryl-local-"));
+    // Where the user-facing outputs (artifacts, spec copy, report) go: --dir if asked, else the
+    // ephemeral run dir.
+    const outDir = opts.dir ? path.resolve(opts.dir) : runDir;
+    fs.mkdirSync(outDir, { recursive: true });
+    const specPath = path.join(runDir, "beryl-local.spec.ts");
+    fs.writeFileSync(specPath, opts.spec);
+    const configPath = path.join(runDir, "beryl-local.config.ts");
+    const artifactsDir = path.join(outDir, "artifacts");
+    fs.writeFileSync(configPath, ISOLATING_CONFIG(runDir, artifactsDir));
+    const reportPath = path.join(runDir, "report.json");
+    const cleanup = () => fs.rmSync(runDir, { recursive: true, force: true });
+    const { command, args: base } = playwrightBase(cwd);
+    const args = [...base, `--config=${configPath}`, "--reporter=json"];
+    opts.onProgress?.(`Running ${command} ${base.join(" ")} on ${opts.testName}…`);
+    const env = { ...process.env, PLAYWRIGHT_JSON_OUTPUT_NAME: reportPath };
+    const result = await runProcess(command, args, cwd, env);
+    if (looksLikePlaywrightMissing(result)) {
+        cleanup();
+        throw new PlaywrightMissingError(PLAYWRIGHT_INSTALL_HINT);
+    }
+    let results;
+    try {
+        results = parseReport(reportPath);
+    }
+    catch (err) {
+        // No parsable report on a non-zero exit means the spec never ran (compile/launch error) —
+        // surface stderr/stdout so it isn't a silent failure.
+        const detail = (result.stderr || result.stdout || err.message).trim();
+        cleanup();
+        throw new Error(`Playwright produced no readable report — the spec did not run.\n${detail}`);
+    }
+    // A run that executed zero tests is a failure, not a pass — an isolating config matching
+    // exactly our spec should never yield an empty set, so an empty one means the spec was
+    // filtered/skipped away and there is no evidence it ran.
+    if (results.length === 0) {
+        const detail = (result.stderr || result.stdout || "no tests were run").trim();
+        cleanup();
+        throw new Error(`Playwright ran no tests from the rendered spec.\n${detail}`);
+    }
+    let keptSpec = specPath;
+    let keptReport = reportPath;
+    if (opts.dir) {
+        // Persist the exact spec + report next to the artifacts before the run dir is removed.
+        keptSpec = path.join(outDir, "beryl-local.spec.ts");
+        keptReport = path.join(outDir, "report.json");
+        fs.copyFileSync(specPath, keptSpec);
+        fs.copyFileSync(reportPath, keptReport);
+    }
+    else {
+        // Without --dir the artifacts lived in the run dir we're about to delete, so their paths
+        // would dangle — don't hand back paths to files that no longer exist.
+        for (const r of results)
+            r.artifacts = [];
+    }
+    cleanup();
+    const { passed, failed } = tally(results);
+    return { passed, failed, results, directory: outDir, spec: keptSpec, report: keptReport };
+}