@beryl-so/cli 0.29.0 → 0.33.0

package/dist/commands/tests.js

@@ -7,7 +7,7 @@ import { PlaywrightMissingError } from "../local-run.js";
 import { dim, green, red, table, yellow } from "../output.js";
 import { confirmInstall, installPlaywright } from "../playwright-install.js";
 import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
-import { arg, argList, flagBool, flagNum, flagStr, projectPath, readJsonFlag } from "./util.js";
+import { arg, argList, flagBool, flagNum, flagStr, flagStrings, inGroup, projectPath, readJsonFlag, } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
 // A duplicate-title 409 after a green replay is idempotent when the existing row
 // holds the same plan (a retry after a lost response) — success, not an error.
@@ -80,7 +80,7 @@ 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 " +
+        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. " +
@@ -106,19 +106,62 @@ export const testCommands = [
         name: "tests list",
         summary: "List the project's tests with their latest result",
         description: "Prints a concise table by default (title / status / id / last result / last run). " +
-            "Pass --wide for every field, or --json for the raw records.",
+            "Pass --wide for every field, or --json for the raw records. Returns every test " +
+            "unless --page is given; pass --page to walk a large project a slice at a time.",
         scope: "project",
         groupDefault: true,
-        groupSummary: "Author, inspect, version, and heal a project's tests — the checks Beryl runs on each run.",
+        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" },
+            {
+                name: "group",
+                type: "string",
+                description: "Show only tests in this group (by name; see `beryl groups list`)",
+            },
             { name: "wide", type: "boolean", description: "Show all columns, not the concise default" },
+            {
+                name: "page",
+                type: "number",
+                description: "Return only this 1-indexed page instead of every test",
+            },
+            {
+                name: "page-size",
+                type: "number",
+                description: "Tests per page when --page is given (default 20, max 100)",
+            },
+            {
+                name: "status",
+                type: "string",
+                description: "With --page, show only this bucket: passed, failed, or blocked",
+            },
+            {
+                name: "ungrouped",
+                type: "boolean",
+                description: "With --page, show only tests carrying no group",
+            },
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`, {
-                environment_id: flagStr(input, "env"),
-            }));
+            const page = flagNum(input, "page");
+            const group = flagStr(input, "group");
+            let data;
+            if (page === undefined) {
+                data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`, {
+                    environment_id: flagStr(input, "env"),
+                }));
+                // GET /tests takes no group param; the paged route below filters server-side.
+                if (group)
+                    data = data.filter((t) => inGroup(t, group));
+            }
+            else {
+                data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/page`, {
+                    page,
+                    page_size: flagNum(input, "page-size"),
+                    status: flagStr(input, "status"),
+                    group: flagBool(input, "ungrouped") ? "__ungrouped__" : group,
+                    environment_id: flagStr(input, "env"),
+                })).items;
+            }
             if (flagBool(input, "wide"))
                 return { data };
             // `data` stays the full records so --json is unchanged; only the human table is trimmed.
@@ -129,7 +172,7 @@ export const testCommands = [
         name: "tests get",
         summary: "Show one test",
         description: "Returns the test's metadata row (status, flags, per-environment last result), not " +
-            "the plan — `tests plan` prints the stored JSON plan, `tests script` the rendered " +
+            "the plan. `tests plan` prints the stored JSON plan, `tests script` the rendered " +
             "Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
@@ -141,7 +184,7 @@ export const testCommands = [
     {
         name: "tests plan",
         summary: "Print a test's current step plan (JSON)",
-        description: "Returns the stored json_plan of the test's current version — `tests get` returns " +
+        description: "Returns the stored json_plan of the test's current version. `tests get` returns " +
             "the metadata row, `tests script` the rendered Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
@@ -155,30 +198,30 @@ 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",
+        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 " +
             "EXECUTED step must be a goto, and at least one step must be an expect. Before anything is " +
             "banked, the plan is proven by replaying it in a browser ON YOUR MACHINE with your local " +
-            "@playwright/test: the server renders the spec (`tests/compile`), the CLI runs it — minting " +
+            "@playwright/test: the server renders the spec (`tests/compile`), the CLI runs it (minting " +
             "a run inbox for await_email steps and resolving the saved login exactly as a cloud run " +
-            "would — and only a green replay creates the test (bound to the replayed plan by its hash). " +
+            "would), and only a green replay creates the test (bound to the replayed plan by its hash). " +
             "This holds over MCP too: the replay runs on the machine hosting the MCP server, never on " +
             "Beryl's; if @playwright/test is missing there the tool returns the install commands (on a " +
             "terminal the CLI offers to install it). " +
             "A red replay banks NOTHING: the failure evidence comes back (over MCP the screenshot is " +
             "image content), you fix the plan file and re-run. The proving run is imported as the " +
             "test's first run (--no-sync to skip). A plan that signs in with a session Beryl captured " +
-            "server-side cannot replay locally (that session never leaves Beryl's cloud) — it falls " +
+            "server-side cannot replay locally (that session never leaves Beryl's cloud). It falls " +
             "back to server-side verification automatically, and says so. A session-mode plan replays locally " +
             "fine: the server renders it with its account's stored sign-in steps in front, so " +
             "the same identity is exercised on your machine. 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. " +
-            "Recovery: a 409 `duplicate_title` carries existing_test_id + existing_plan_hash — " +
+            "Recovery: a 409 `duplicate_title` carries existing_test_id + existing_plan_hash, so " +
             "reconcile with that test (`tests get` / `tests set-plan`), don't rename-and-retry; a " +
             "409 `plan_hash_mismatch` means the submitted plan is not the bytes that were replayed " +
-            "— re-run `tests create`; a 429 with Retry-After 30 means the verify slots are " +
-            "saturated — wait and retry.",
+            "(re-run `tests create`); a 429 with Retry-After 30 means the verify slots are " +
+            "saturated (wait and retry).",
         scope: "project",
         flags: [
             { name: "title", type: "string", required: true, description: "Title for the new test" },
@@ -186,20 +229,26 @@ export const testCommands = [
             {
                 name: "description",
                 type: "string",
-                description: "1–3 sentences stating what this test proves — the immutable outcome Beryl's healing " +
+                description: "One to three 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 verification entirely — bank the authored plan as-is, unproven",
+                description: "Skip verification entirely: bank the authored plan as-is, unproven",
             },
             {
                 name: "url-override",
                 type: "string",
                 description: "Replay against this base URL instead of the environment's (e.g. http://localhost:3000). " +
-                    "The banked test is then unproven against its real environment — the CLI says so.",
+                    "The banked test is then unproven against its real environment, and the CLI says so.",
+            },
+            {
+                name: "group",
+                type: "strings",
+                description: "Put the test in an existing project group (by name), repeatable. An unknown " +
+                    "name is an error (create groups with `beryl groups create`). Omit for no group.",
             },
             { name: "env", type: "string", description: "Environment id to compile and prove against" },
             {
@@ -230,10 +279,12 @@ export const testCommands = [
             const urlOverride = flagStr(input, "url-override");
             const env = flagStr(input, "env");
             const sync = input.flags.sync !== false;
+            const groups = flagStrings(input, "group");
             const bank = (extra) => ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
                 title,
                 plan,
                 description,
+                groups,
                 ...extra,
             });
             if (flagBool(input, "no-verify")) {
@@ -429,9 +480,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 " +
+            "`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. Saves the edit with NO replay — " +
+            "proves; omit it to keep the test's existing intent. Saves the edit with NO replay: " +
             "it rides into the next run unproven; `tests recompile` is the verify-first " +
             "alternative.",
         scope: "project",
@@ -441,7 +492,7 @@ export const testCommands = [
             {
                 name: "description",
                 type: "string",
-                description: "1–3 sentences stating what this test proves — the immutable outcome Beryl's healing " +
+                description: "One to three 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.",
             },
@@ -472,16 +523,45 @@ export const testCommands = [
             };
         },
     },
+    {
+        name: "tests set-groups",
+        summary: "Replace the groups a test belongs to",
+        description: "Groups are project-defined labels used to filter, run, or schedule a slice of the " +
+            "suite (`beryl runs trigger --group <name>`). This REPLACES the whole set: pass every " +
+            "group you want, or none to clear it. Names must already exist in the project " +
+            "(`beryl groups list`); an unknown name is an error, never a new group.",
+        scope: "project",
+        args: [{ name: "test-id", description: "Test id", required: true }],
+        flags: [
+            {
+                name: "group",
+                type: "strings",
+                description: "Group name, repeatable. Omit entirely to clear the set.",
+            },
+        ],
+        examples: [
+            "beryl tests set-groups 4f… --group Checkout --group Smoke",
+            "beryl tests set-groups 4f…",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.patch(testPath(workspaceId, projectId, arg(input, "test-id")), {
+                    groups: flagStrings(input, "group") ?? [],
+                }),
+            };
+        },
+    },
     {
         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 " +
+        description: "A quarantined test still executes and its result is still recorded and visible. Its " +
             "red lands in the run's quarantined_count and gates neither the run's verdict nor exit " +
             "codes, 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). After 5 consecutive " +
-            "clean passes the test reports rehab_ready — advisory only, nothing un-quarantines " +
-            "itself. `off` un-quarantines.",
+            "clean passes the test reports rehab_ready (advisory only, nothing un-quarantines " +
+            "itself). `off` un-quarantines.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -518,11 +598,11 @@ export const testCommands = [
         summary: "Validate + verify an edited plan against the live site before persisting",
         description: "Unlike `tests set-plan` (which saves the edit and lets it ride into the next run), " +
             "this replays the edited plan against the live site before anything persists. A " +
-            "deterministic replay failure (verdict `drop`) REJECTS the edit — persisted:false, " +
-            "the prior plan stays live — and returns the failure evidence (over MCP the " +
+            "deterministic replay failure (verdict `drop`) REJECTS the edit (persisted:false, " +
+            "the prior plan stays live) and returns the failure evidence (over MCP the " +
             "screenshot is image content). Verdict `flag` (the runner errored, no verdict on " +
             "the flow) persists the plan but reports it unverified. Returns 429 with " +
-            "Retry-After 30 when the 2 inline-verify slots are saturated — wait and retry.",
+            "Retry-After 30 when the 2 inline-verify slots are saturated (wait and retry).",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -591,7 +671,7 @@ export const testCommands = [
     {
         name: "tests restore",
         summary: "Restore a test to an earlier version",
-        description: "Copies the named older version's plan forward as a NEW head version — unlike " +
+        description: "Copies the named older version's plan forward as a NEW head version, unlike " +
             "`tests reset`, which flips authored_by back to `system` and leaves the plan " +
             "untouched.",
         scope: "project",
@@ -610,7 +690,7 @@ export const testCommands = [
         name: "tests reset",
         summary: "Discard user edits and return the test to its latest system-authored version",
         description: "Flips authored_by back to `system` WITHOUT changing the plan (the next " +
-            "regeneration overwrites it) — unlike `tests restore`, which copies an older " +
+            "regeneration overwrites it), unlike `tests restore`, which copies an older " +
             "version's plan forward as a new version.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
@@ -659,9 +739,9 @@ export const testCommands = [
         name: "tests script",
         summary: "Print the rendered Playwright spec for a test (or an unbanked plan file)",
         description: "With a test id, fetches the banked test's rendered .spec.ts. With --file, compiles a " +
-            "plan JSON that has NOT been banked yet — the same render `tests create` proves locally — " +
+            "plan JSON that has NOT been banked yet (the same render `tests create` proves locally) " +
             "so you can inspect exactly what would run before creating anything. This returns the " +
-            "executable spec — `tests plan` returns the stored JSON plan it is rendered from, " +
+            "executable spec. `tests plan` returns the stored JSON plan it is rendered from, " +
             "`tests get` the metadata row.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id (omit when passing --file)" }],

package/dist/commands/util.js

@@ -54,3 +54,23 @@ export function readJsonFlag(input, name) {
         throw new UsageError(`--${name}: ${file} is not valid JSON (${err.message})`);
     }
 }
+export function flagStrings(input, name) {
+    const v = input.flags[name];
+    return v && v.length > 0 ? v : undefined;
+}
+export function inGroup(row, group) {
+    const want = group.trim().toLowerCase();
+    return (row.groups ?? []).some((g) => g.toLowerCase() === want);
+}
+/** Resolve a --group name to the ids of the project's ACTIVE tests in it.
+ *  Client-side on purpose: the run endpoint keeps one selection mechanism
+ *  (test_case_ids), so a run always records the exact ids it ran even if group
+ *  membership changes later. */
+export function idsInGroup(rows, group) {
+    return rows.filter((t) => t.is_active !== false && inGroup(t, group)).map((t) => t.id);
+}
+/** Match a `--group` value against the project's groups by name (case-insensitive) or id. */
+export function findGroup(groups, ref) {
+    const want = ref.trim().toLowerCase();
+    return groups.find((g) => g.id === ref || g.name.toLowerCase() === want);
+}

package/dist/commands/watch.js

@@ -68,7 +68,8 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes) {
     // 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`) : "");
+        (counters.flaky ? yellow(`, ${counters.flaky} flaky`) : "") +
+        (counters.healed ? yellow(`, ${counters.healed} healed`) : "");
     const summary = failed > 0
         ? red(`${failed} failed`) + `, ${passed} passed` + extra
         : green(`${passed} passed`) + extra;

package/dist/registry/index.js

@@ -4,6 +4,7 @@ import { authCommands } from "../commands/auth.js";
 import { configCommands } from "../commands/config-vars.js";
 import { environmentCommands } from "../commands/environments.js";
 import { explorationCommands } from "../commands/explorations.js";
+import { groupCommands } from "../commands/groups.js";
 import { healthCommands } from "../commands/health.js";
 import { mailboxCommands } from "../commands/mailboxes.js";
 import { initCommands } from "../commands/init.js";
@@ -57,6 +58,7 @@ export const commands = [
     ...projectCommands,
     ...environmentCommands,
     ...testCommands,
+    ...groupCommands,
     ...runCommands,
     ...healthCommands,
     ...explorationCommands,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.29.0",
-  "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
+  "version": "0.33.0",
+  "description": "Beryl on the command line \u2014 projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",
   "homepage": "https://beryl.so/docs/cli",