@beryl-so/cli 0.29.0 → 0.33.0

package/dist/commands/groups.js

@@ -0,0 +1,69 @@
+import { UsageError } from "../errors.js";
+import { arg, findGroup, flagBool, projectPath } from "./util.js";
+async function resolveGroup(ctx, workspaceId, projectId, ref) {
+    const groups = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/groups`));
+    const match = findGroup(groups, ref);
+    if (!match) {
+        const names = groups.map((g) => g.name).join(", ") || "none yet";
+        throw new UsageError(`No group '${ref}' in this project (existing: ${names}).`);
+    }
+    return match;
+}
+export const groupCommands = [
+    {
+        name: "groups list",
+        summary: "List the project's test groups and how many tests each holds",
+        scope: "project",
+        groupDefault: true,
+        groupSummary: "Manage a project's test groups: labels a test can carry any number of, used to filter, run, or schedule a slice of the suite. Groups are created only here (or in Settings → Groups); assigning a test to an unknown name is an error.",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return { data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/groups`) };
+        },
+    },
+    {
+        name: "groups create",
+        summary: "Create a group",
+        scope: "project",
+        args: [{ name: "name", description: "Group name (unique per project)", required: true }],
+        examples: ["beryl groups create Smoke"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/groups`, {
+                    name: arg(input, "name"),
+                }),
+            };
+        },
+    },
+    {
+        name: "groups rename",
+        summary: "Rename a group (tests keep their membership)",
+        scope: "project",
+        args: [
+            { name: "group", description: "Current group name or id", required: true },
+            { name: "name", description: "New name", required: true },
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const group = await resolveGroup(ctx, workspaceId, projectId, arg(input, "group"));
+            return {
+                data: await ctx.client.patch(`${projectPath(workspaceId, projectId)}/groups/${group.id}`, { name: arg(input, "name") }),
+            };
+        },
+    },
+    {
+        name: "groups delete",
+        summary: "Delete a group: its tests stay; a schedule targeting only this group goes with it",
+        scope: "project",
+        args: [{ name: "group", description: "Group name or 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 group = await resolveGroup(ctx, workspaceId, projectId, arg(input, "group"));
+            await ctx.confirm(`Delete group '${group.name}' (${group.test_count ?? 0} tests leave it)?`, flagBool(input, "force"));
+            await ctx.client.del(`${projectPath(workspaceId, projectId)}/groups/${group.id}`);
+            return { human: "Deleted." };
+        },
+    },
+];

package/dist/commands/health.js

@@ -8,7 +8,7 @@ export const healthCommands = [
     {
         name: "health get",
         groupDefault: true,
-        groupSummary: "Site Health — how your site reads to search engines and visitors: content, " +
+        groupSummary: "Site Health, or how your site reads to search engines and visitors: content, " +
             "speed, mobile, links and security, graded from a real check of your live pages.",
         summary: "Show the latest Site Health report for a project environment",
         description: "A check runs automatically when a project or environment gets its URL. While one " +

package/dist/commands/init.js

@@ -147,20 +147,20 @@ async function ensureLocalPlaywright(ctx, cwd) {
 export const initCommands = [
     {
         name: "init",
-        summary: "Set up Beryl in this repo — sign in and wire up your coding agent",
+        summary: "Set up Beryl in this repo: sign in and wire up your coding agent",
         description: "One-command onboarding: signs you in (browser confirm, or an emailed one-time code) " +
             "and wires up your coding " +
-            "agent. Nothing is detected and nothing is conditional — every run wires the beryl AND " +
+            "agent. Nothing is detected and nothing is conditional: every run wires the beryl AND " +
             "playwright MCP servers, writes the authoring skill (user scope: your home " +
             ".agents/skills/ + .claude/skills/, so it follows you into every session; --scope " +
             "project: the repo's own dirs, committed for teammates), and installs @playwright/test " +
-            "+ chromium if missing — browser authoring and local runs depend on it. By default the " +
+            "+ chromium if missing, since browser authoring and local runs depend on it. By default the " +
             "servers are wired per-user (matching where your login token lives) via `claude mcp add " +
             "-s user`; pass --scope project to write a committed .mcp.json for a shared repo " +
-            "instead. No workspace/project pin and no URL prompt — ask Claude to write tests for " +
+            "instead. No workspace/project pin and no URL prompt: ask Claude to write tests for " +
             "your site and it resolves the workspace, project, and URL. Safe to re-run: every run " +
             "refreshes the authoring skill to this CLI's version (overwriting an older or edited " +
-            "copy — `beryl guide` prints the same content), and skips whatever else is already set " +
+            "copy; `beryl guide` prints the same content), and skips whatever else is already set " +
             "up.",
         interactive: true,
         flags: [
@@ -170,7 +170,7 @@ export const initCommands = [
                 enum: ["user", "project"],
                 description: "Where to wire the MCP servers. `user` (default) configures them per-user (matching " +
                     "where your Beryl login token lives) via `claude mcp add -s user`. `project` writes a " +
-                    "committed .mcp.json for a shared repo — every teammate still runs `beryl login` to " +
+                    "committed .mcp.json for a shared repo. Every teammate still runs `beryl login` to " +
                     "authenticate",
             },
             {
@@ -285,8 +285,8 @@ export const initCommands = [
         description: "The full guide to authoring durable, healable tests: the ActionPlan shape, outcome " +
             "assertions, natural-language intent, test accounts and the project mailbox " +
             "({{login_email}}, {{mailbox_address}}, {{inbox_address}} + await_email), and the " +
-            "local run-fix loop. Same content as the beryl-test skill `beryl init` installs — " +
-            `skip if a loaded beryl-test skill states v${cliVersion()}; else call this first ` +
+            "local run-fix loop. Same content as the beryl-test skill `beryl init` installs. " +
+            `Skip if a loaded beryl-test skill states v${cliVersion()}; else call this first ` +
             "(works without logging in).",
         examples: ["beryl guide"],
         async run() {

package/dist/commands/mailboxes.js

@@ -7,10 +7,10 @@ export const mailboxCommands = [
         name: "mailbox get",
         summary: "The project's mailbox address",
         groupDefault: true,
-        groupSummary: "The project's standing email addresses — where its tests receive sign-in mail.",
+        groupSummary: "The project's standing email addresses, where its tests receive sign-in mail.",
         description: "Returns the address {{mailbox_address}} resolves to, creating it on first ask. " +
             "Every test that reads mail receives here. A test needing an address the site has " +
-            "never seen cites {{inbox_address}} instead — that renders a `+tag` alias of this " +
+            "never seen cites {{inbox_address}} instead. That renders a `+tag` alias of this " +
             "same mailbox, so a signup stays repeatable without a second address to manage.",
         scope: "project",
         async run(ctx, input) {
@@ -46,7 +46,7 @@ export const mailboxCommands = [
         name: "mailbox create",
         summary: "Add a second mailbox to the project",
         description: "Only needed when a flow requires two genuinely separate inboxes at the same time " +
-            "— both sides of an invite handshake. For an address the site has not seen before, " +
+            "(both sides of an invite handshake). For an address the site has not seen before, " +
             "cite {{inbox_address}} in the plan instead: it aliases the existing mailbox and " +
             "costs nothing to manage.",
         scope: "project",
@@ -88,12 +88,12 @@ export const mailboxCommands = [
         name: "mailbox read",
         summary: "Read the latest email in a mailbox (waits for one to arrive)",
         description: "Waits up to --timeout-s for a matching email and returns it (one blocking request; " +
-            "the server caps the wait at 50s — re-run to keep waiting). With --extract-code, " +
+            "the server caps the wait at 50s, so re-run to keep waiting). With --extract-code, " +
             "also asks the server to pull the one-time code out of the email (AI-assisted when " +
             "the email is ambiguous; `code` is null if none was found). Use " +
             "--recipient-contains to read only one `+tag` alias's mail when several identities " +
             "share the mailbox. Exits non-zero if nothing arrives before the timeout. Waits for " +
-            "and returns ONE latest matching email — `mailbox emails` lists what has already " +
+            "and returns ONE latest matching email. `mailbox emails` lists what has already " +
             "arrived, without waiting.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
@@ -154,7 +154,7 @@ export const mailboxCommands = [
     {
         name: "mailbox emails",
         summary: "List the emails a mailbox has received",
-        description: "Returns the already-received emails without waiting — `mailbox read` blocks for " +
+        description: "Returns the already-received emails without waiting. `mailbox read` blocks for " +
             "a matching one and returns just it.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],

package/dist/commands/mcp.js

@@ -3,9 +3,9 @@ export const mcpCommands = [
     {
         name: "version",
         summary: "Show the running CLI version, API URL, and Node version",
-        description: "Answers \"which build am I actually talking to?\" — the one question a long-lived " +
+        description: "Answers \"which build am I actually talking to?\" (the one question a long-lived " +
             "`beryl mcp` process can't otherwise answer, since it loads source at spawn and never " +
-            "hot-reloads. Needs no login, so it still works when a token is missing or broken. " +
+            "hot-reloads). Needs no login, so it still works when a token is missing or broken. " +
             "Also reports whether the running build is behind npm's `latest` (best-effort: " +
             "`update_available` is null when the registry can't be reached, and the check is " +
             "skipped entirely under BERYL_NO_UPDATE_CHECK).",
@@ -26,7 +26,7 @@ export const mcpCommands = [
     },
     {
         name: "mcp",
-        summary: "Run the Beryl MCP server (stdio) — every CLI command as an agent tool",
+        summary: "Run the Beryl MCP server (stdio): every CLI command as an agent tool",
         description: "Exposes the CLI's commands as MCP tools over stdio, so coding agents (Claude Code, " +
             "Cursor, …) can create projects, trigger runs, watch the agent, and edit tests. " +
             "Authenticate via BERYL_API_KEY or a prior `beryl login`.",

package/dist/commands/projects.js

@@ -37,7 +37,7 @@ export const projectCommands = [
         summary: "List projects in the workspace",
         scope: "workspace",
         groupDefault: true,
-        groupSummary: "Create and manage projects — a site Beryl explores, authors tests for, and runs.",
+        groupSummary: "Create and manage projects: a site Beryl explores, authors tests for, and runs.",
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
             const rows = (await ctx.client.get(`/workspaces/${ws}/projects`));
@@ -70,7 +70,7 @@ export const projectCommands = [
     },
     {
         name: "projects create",
-        summary: "Create a project — with a URL the agent starts exploring; with just --name an empty one",
+        summary: "Create a project. With a URL the agent starts exploring; with just --name an empty one",
         scope: "workspace",
         args: [
             {
@@ -91,13 +91,13 @@ export const projectCommands = [
                 type: "string",
                 enum: ["public", "gated"],
                 description: "Whether the site needs a login (gated) or not (public). Default: detected from the " +
-                    "site — only asked when detection is genuinely unsure",
+                    "site, and only asked when detection is genuinely unsure",
             },
             { name: "force-new-login", type: "boolean", description: "Ignore any reusable saved login" },
             {
                 name: "no-explore",
                 type: "boolean",
-                description: "Create the project without starting the cloud exploration — author tests yourself " +
+                description: "Create the project without starting the cloud exploration. Author tests yourself " +
                     "via `beryl tests create` or your coding agent over MCP",
             },
             { name: "watch", type: "boolean", description: "Stream the agent's exploration live" },
@@ -190,7 +190,7 @@ export const projectCommands = [
     },
     {
         name: "projects re-explore",
-        summary: "Send the agent back in — run/heal existing tests and discover new flows",
+        summary: "Send the agent back in to run/heal existing tests and discover new flows",
         scope: "project",
         flags: [
             { name: "watch", type: "boolean", description: "Stream the agent's exploration live" },

package/dist/commands/runs.js

@@ -7,7 +7,7 @@ import { countPlannedFrames, countWrittenFrames, PlaywrightMissingError, } from
 import { dim, green, red, yellow } from "../output.js";
 import { anyGap, confirmInstall, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { ProgressBar } from "../progress.js";
-import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { arg, flagBool, flagNum, flagStr, idsInGroup, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
 const MAX_FAILURE_SCREENSHOTS = 5;
 // One filesystem check before a single spec is fetched. A missing browser binary otherwise
@@ -50,10 +50,19 @@ export const runCommands = [
         name: "runs trigger",
         summary: "Trigger a test run (whole suite, a subset, or one environment)",
         description: "Runs execute in Beryl's cloud. With --watch the CLI streams live progress and " +
-            "exits 0 only if every test passed — wire it straight into CI.",
+            "exits 0 only if every test passed, so wire it straight into CI. A run with a " +
+            "heal-eligible failure completes only after Beryl has tried to heal it: a repaired " +
+            "test is re-run inside the same run and counts as passed (reported as `healed`), so " +
+            "the final counts, the report and the completion email all reflect the repair.",
         scope: "project",
         flags: [
             { name: "test", type: "strings", description: "Run only these test ids (repeatable)" },
+            {
+                name: "group",
+                type: "string",
+                description: "Run only the active tests in this group (by name), resolved to ids before the run, " +
+                    "so the run records exactly what it ran. Cannot be combined with --test.",
+            },
             { name: "env", type: "string", description: "Environment id to run against" },
             { name: "url-override", type: "string", description: "Replace the base URL (preview deploys)" },
             {
@@ -75,11 +84,22 @@ export const runCommands = [
             "beryl runs trigger --url-override https://preview-123.example.com --watch --timeout 30",
             "beryl runs trigger --url-override https://preview-123.example.com --header x-vercel-protection-bypass=<token> --watch",
             "beryl runs trigger --test 4f… --test 9a…",
+            "beryl runs trigger --group Smoke --watch",
             "beryl runs trigger --retries 0 --watch",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const tests = input.flags.test;
+            let tests = input.flags.test;
+            const group = flagStr(input, "group");
+            if (group && tests && tests.length > 0)
+                throw new UsageError("--group cannot be combined with --test");
+            if (group) {
+                const listed = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`));
+                tests = idsInGroup(listed, group);
+                // Exiting 0 here would be a green CI run that tested nothing.
+                if (tests.length === 0)
+                    throw new UsageError(`No active tests in group '${group}'.`);
+            }
             const extraHeaders = parseHeaders(input.flags.header);
             const created = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/runs`, {
                 test_case_ids: tests && tests.length > 0 ? tests : null,
@@ -96,7 +116,7 @@ export const runCommands = [
     {
         name: "runs local",
         summary: "Run tests on your machine with your own Playwright; results sync to Beryl",
-        description: "Unlike `runs trigger`, the browser runs on YOUR machine — each test's rendered spec is " +
+        description: "Unlike `runs trigger`, the browser runs on YOUR machine: each test's rendered spec is " +
             "fetched and run with your local @playwright/test and the Chromium binary it drives. " +
             "Both are checked once before any spec is fetched, so a machine that can't run tests " +
             "says so once instead of failing every test (on a terminal the CLI offers to install " +
@@ -109,12 +129,12 @@ export const runCommands = [
             "does, and scrubbed from any error text or DOM snapshot before results upload; a test " +
             "whose account has no stored password is skipped with the exact fix-it command. When the " +
             "run finishes, the results and replay artifacts are imported into Beryl as a normal run " +
-            "(trigger source `local`) — history, replay, and reports all work; pass --no-sync to " +
+            "(trigger source `local`), so history, replay, and reports all work; pass --no-sync to " +
             "keep a run entirely off the record while iterating. Session-mode tests behave as " +
             "in the cloud: their account signs in once per invocation and every session-mode " +
             "test rides that session; a failed sign-in fails those tests with the same " +
             "SESSION_* reason a cloud run reports. Only a test that depends on a session Beryl " +
-            "captured server-side is skipped, with a note — run those with `runs trigger`. Point " +
+            "captured server-side is skipped, with a note. Run those with `runs trigger`. Point " +
             "--url-override at a local dev server or preview, and --dir to keep specs, artifacts, " +
             "and reports on disk. Exits 0 only if every executed test passed.",
         scope: "project",
@@ -131,6 +151,11 @@ export const runCommands = [
                 type: "boolean",
                 description: "Run every active test in the project (the default when no ids are given)",
             },
+            {
+                name: "group",
+                type: "string",
+                description: "Run only the active tests in this group (by name). Cannot be combined with test ids.",
+            },
             {
                 name: "url-override",
                 type: "string",
@@ -139,7 +164,7 @@ export const runCommands = [
             {
                 name: "env",
                 type: "string",
-                description: "Environment id to run against and attach the imported run to — use for a " +
+                description: "Environment id to run against and attach the imported run to. Use for a " +
                     "standing environment; --url-override is for a throwaway host",
             },
             {
@@ -162,15 +187,23 @@ export const runCommands = [
             "beryl runs local 4f… --no-sync --dir ./beryl-local",
         ],
         async run(ctx, input) {
-            await ensureRunnableLocally(ctx);
-            const { workspaceId, projectId } = await ctx.requireProject(input);
+            // Argument validation runs BEFORE the Chromium/Playwright precondition: a bad flag
+            // combination should say so on any machine, not report a missing browser.
             // Deduped: a repeated id would put the same test twice in one imported run,
             // which the import manifest rejects.
             const explicitIds = [...new Set(input.args["test-ids"] ?? [])];
-            // No ids means the whole suite — `beryl runs local` alone is a complete local run.
-            const all = explicitIds.length === 0;
+            const group = flagStr(input, "group");
+            if (group && explicitIds.length > 0)
+                throw new UsageError("--group cannot be combined with explicit test ids");
             if (explicitIds.length > 0 && flagBool(input, "all"))
                 throw new UsageError("--all cannot be combined with explicit test ids");
+            if (group && flagBool(input, "all"))
+                throw new UsageError("--all cannot be combined with --group");
+            // No ids and no group means the whole suite — `beryl runs local` alone is a
+            // complete local run.
+            const all = explicitIds.length === 0 && !group;
+            await ensureRunnableLocally(ctx);
+            const { workspaceId, projectId } = await ctx.requireProject(input);
             const sync = input.flags.sync !== false;
             const urlOverride = flagStr(input, "url-override");
             const dir = flagStr(input, "dir");
@@ -180,9 +213,15 @@ export const runCommands = [
             // The list rows carry the authored name as nl_title (title is the customer's
             // rename, usually unset) — fall through so the terminal shows names, not ids.
             const titles = new Map(listed.map((t) => [t.id, t.title || t.nl_title || t.id.slice(0, 8)]));
-            const ids = all ? listed.filter((t) => t.is_active !== false).map((t) => t.id) : explicitIds;
+            const ids = all
+                ? listed.filter((t) => t.is_active !== false).map((t) => t.id)
+                : group
+                    ? idsInGroup(listed, group)
+                    : explicitIds;
             if (ids.length === 0)
-                throw new CliError("This project has no tests to run.");
+                throw group
+                    ? new UsageError(`No active tests in group '${group}'.`)
+                    : new CliError("This project has no tests to run.");
             const fetchScript = (id) => ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/${id}/script`, {
                 // frames only matter when the run will be imported: they become the replay.
                 // environment_id keeps the baked login_email on the same environment the
@@ -454,15 +493,36 @@ export const runCommands = [
     {
         name: "runs list",
         summary: "List recent runs",
+        description: "Returns the 50 most recent runs unless --page is given; pass --page to walk the " +
+            "full history a slice at a time.",
         scope: "project",
         groupDefault: true,
         groupSummary: "Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and download results.",
-        flags: [{ name: "env", type: "string", description: "Filter by environment id" }],
+        flags: [
+            { name: "env", type: "string", description: "Filter by environment id" },
+            {
+                name: "page",
+                type: "number",
+                description: "Return only this 1-indexed page instead of the 50 most recent runs",
+            },
+            {
+                name: "page-size",
+                type: "number",
+                description: "Runs per page when --page is given (default 8, max 100)",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const rows = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs`, {
-                environment_id: flagStr(input, "env"),
-            }));
+            const page = flagNum(input, "page");
+            const rows = page === undefined
+                ? (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs`, {
+                    environment_id: flagStr(input, "env"),
+                }))
+                : (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/page`, {
+                    page,
+                    page_size: flagNum(input, "page-size"),
+                    environment_id: flagStr(input, "env"),
+                })).items;
             return { data: rows.map(({ test_results: _omit, ...row }) => row) };
         },
     },
@@ -471,8 +531,8 @@ export const runCommands = [
         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. " +
-            "Returns the run row with its per-test results — `runs report` returns the generated " +
+            "to false to skip fetching them. Ignored outside MCP (the terminal cannot show an image). " +
+            "Returns the run row with its per-test results. `runs report` returns the generated " +
             "report document, `runs explain` an AI explanation of one failed result.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
@@ -525,7 +585,7 @@ export const runCommands = [
     {
         name: "runs report",
         summary: "Show the generated report for a run",
-        description: "Returns the run's stored generated report (404 until it has been generated) — " +
+        description: "Returns the run's stored generated report (404 until it has been generated). " +
             "`runs get` returns the raw run row with per-test results.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
@@ -539,8 +599,8 @@ export const runCommands = [
     {
         name: "runs download",
         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>/ " +
+        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",
@@ -607,7 +667,7 @@ export const runCommands = [
         name: "runs explain",
         summary: "Explain, with AI, why a test result failed",
         description: "Takes a single test-RESULT id (not a run id) and returns an AI failure " +
-            "explanation for that result — `runs get` lists a run's results and their ids.",
+            "explanation for that result. `runs get` lists a run's results and their ids.",
         scope: "project",
         args: [{ name: "result-id", description: "Test result id (from `beryl runs get`)", required: true }],
         async run(ctx, input) {