@beryl-so/cli 0.1.0 → 0.2.0

package/dist/commands/runs.js

@@ -1,6 +1,9 @@
 import fs from "node:fs";
+import { downloadRunArtifacts, failureImages, isFailing, resultsOf, } from "../artifacts.js";
+import { dim, yellow } from "../output.js";
 import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
+const MAX_FAILURE_SCREENSHOTS = 5;
 export const runCommands = [
     {
         name: "runs trigger",
@@ -14,11 +17,17 @@ export const runCommands = [
             { name: "url-override", type: "string", description: "Replace the base URL (preview deploys)" },
             { name: "watch", type: "boolean", description: "Stream progress and exit non-zero on failure" },
             { name: "timeout", type: "number", description: "With --watch: max minutes to wait" },
+            {
+                name: "retries",
+                type: "number",
+                description: "Retry a failing test up to N times (0 disables); omit for the default",
+            },
         ],
         examples: [
             "beryl runs trigger --watch",
             "beryl runs trigger --url-override https://preview-123.example.com --watch --timeout 30",
             "beryl runs trigger --test 4f… --test 9a…",
+            "beryl runs trigger --retries 0 --watch",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -27,6 +36,7 @@ export const runCommands = [
                 test_case_ids: tests && tests.length > 0 ? tests : null,
                 environment_id: flagStr(input, "env") ?? null,
                 target_url_override: flagStr(input, "url-override") ?? null,
+                max_retries: flagNum(input, "retries") ?? null,
             }));
             if (!flagBool(input, "watch"))
                 return { data: created };
@@ -37,6 +47,7 @@ export const runCommands = [
         name: "runs list",
         summary: "List recent runs",
         scope: "project",
+        groupDefault: true,
         flags: [{ name: "env", type: "string", description: "Filter by environment id" }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -49,13 +60,31 @@ export const runCommands = [
     {
         name: "runs get",
         summary: "Show one run with its per-test results",
+        description: "Over MCP the failure screenshots come back as viewable image content, so an agent can " +
+            "look at the page that broke instead of guessing from the error string. Set screenshots " +
+            "to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
+        flags: [
+            {
+                name: "screenshots",
+                type: "boolean",
+                default: true,
+                description: "Attach failure screenshots as image content (MCP only; default true)",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return {
-                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}`),
-            };
+            const data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}`));
+            // Only the MCP adapter renders images; fetching bytes for a plain CLI run
+            // would be wasted network.
+            if (!ctx.mcp || input.flags.screenshots === false)
+                return { data };
+            const { images, skipped } = await failureImages(data, MAX_FAILURE_SCREENSHOTS);
+            // A silently-missing picture reads as "there was none" — say what was lost.
+            for (const note of skipped)
+                ctx.err(yellow(`! ${note}`));
+            return { data, images };
         },
     },
     {
@@ -96,18 +125,68 @@ export const runCommands = [
     },
     {
         name: "runs download",
-        summary: "Download a run's full results as JSON",
+        summary: "Download a run's results, with its artifacts, to disk",
+        description: "With --dir, fetches the artifact bytes — screenshots, DOM snapshots, the Playwright " +
+            "trace zip, and the filmstrip frames of the failing tests — into <dir>/<test-result-id>/ " +
+            "alongside a run.json manifest. Artifact URLs are short-lived, so download rather than " +
+            "stash them. With --out (or neither), writes only the JSON manifest.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
-        flags: [{ name: "out", type: "string", description: "Write to a file instead of stdout" }],
+        flags: [
+            {
+                name: "dir",
+                type: "string",
+                description: "Write run.json plus the artifact files into this directory",
+            },
+            {
+                name: "all-frames",
+                type: "boolean",
+                description: "With --dir: also fetch the filmstrip frames of passing tests",
+            },
+            { name: "out", type: "string", description: "Write the JSON to a file instead of stdout" },
+        ],
+        examples: [
+            "beryl runs download 7c1… --dir ./beryl-run",
+            "beryl runs download 7c1… --out run.json",
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const data = await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}/download`);
+            const data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}/download`));
+            // --out and --dir are not alternatives: one says where the JSON goes, the other
+            // asks for the bytes as well. Honour both when both are given.
             const out = flagStr(input, "out");
-            if (out) {
+            if (out)
                 fs.writeFileSync(out, JSON.stringify(data, null, 2) + "\n");
-                return { data: { written: out }, human: `Wrote ${out}` };
+            const dir = flagStr(input, "dir");
+            if (dir) {
+                const report = await downloadRunArtifacts(data, dir, {
+                    allFrames: flagBool(input, "all-frames"),
+                    onProgress: (line) => ctx.err(dim(line)),
+                });
+                for (const failure of report.failures) {
+                    ctx.err(yellow(`! could not fetch ${failure.url}: ${failure.error}`));
+                }
+                const failed = resultsOf(data).filter((r) => isFailing(r.status)).length;
+                // Exit codes are a CI contract: a bundle with zero artifacts on disk when the
+                // run had some is a failed download, not a success with a caveat.
+                const lostEverything = report.artifacts.length === 0 && report.failures.length > 0;
+                return {
+                    data: {
+                        directory: report.directory,
+                        manifest: report.manifest,
+                        artifacts: report.artifacts,
+                        failed_tests: failed,
+                        skipped: report.failures.length,
+                        ...(out ? { written: out } : {}),
+                    },
+                    human: `Wrote ${report.manifest} and ${report.artifacts.length} artifact file(s) to ${dir}` +
+                        (report.failures.length ? ` (${report.failures.length} could not be fetched)` : "") +
+                        (out ? `\nWrote ${out}` : ""),
+                    ...(lostEverything ? { exitCode: 1 } : {}),
+                };
             }
+            if (out)
+                return { data: { written: out }, human: `Wrote ${out}` };
             return { data, human: JSON.stringify(data, null, 2) };
         },
     },

package/dist/commands/tests.js

@@ -1,12 +1,40 @@
 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,
         flags: [{ name: "env", type: "string", description: "Filter by environment id" }],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -44,8 +72,10 @@ 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" },
@@ -74,6 +104,9 @@ 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.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -87,6 +120,62 @@ export const testCommands = [
             };
         },
     },
+    {
+        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/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/registry/index.js

@@ -58,7 +58,20 @@ export function findCommand(words) {
                 best = { spec, consumed: parts.length };
         }
     }
-    return best;
+    if (best)
+        return best;
+    // A bare group word runs its default subcommand — `beryl tests` is `beryl tests list`.
+    // Only when the group is the whole command: `beryl tests bogus` must stay an unknown
+    // command, not silently list tests and drop the typo'd subcommand as a stray argument.
+    if (words.length === 1) {
+        const fallback = groupDefault(words[0]);
+        if (fallback)
+            return { spec: fallback, consumed: 1 };
+    }
+    return undefined;
+}
+export function groupDefault(group) {
+    return commands.find((spec) => spec.groupDefault && spec.name.split(" ")[0] === group);
 }
 export function commandGroups() {
     const groups = new Map();