@beryl-so/cli 0.36.0 → 0.38.0

package/README.md

@@ -258,7 +258,7 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 | `beryl runs local [test-ids...]` | Run tests on your machine with Playwright; results sync to Beryl | `runs_local` |
 | `beryl runs list` | List recent runs | `runs_list` |
 | `beryl runs get <run-id>` | Show one run with its per-test results | `runs_get` |
-| `beryl runs watch <run-id>` | Attach to a run and stream progress until it finishes | `runs_watch` |
+| `beryl runs watch <run-id>` | Follow a run until it finishes | `runs_watch` |
 | `beryl runs cancel <run-id>` | Cancel an in-flight run | `runs_cancel` |
 | `beryl runs report <run-id>` | Show the generated report for a run | `runs_report` |
 | `beryl runs download <run-id>` | Download a run's results, with its artifacts, to disk | `runs_download` |

package/dist/commands/runs.js

@@ -49,7 +49,7 @@ 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 " +
+        description: "Runs execute in Beryl's cloud. With --watch the CLI follows live progress and " +
             "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 " +
@@ -59,9 +59,10 @@ export const runCommands = [
             { 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.",
+                type: "strings",
+                description: "Run only the active tests in these groups (by name, repeatable, union of members), " +
+                    "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)" },
@@ -71,7 +72,7 @@ export const runCommands = [
                 description: "Send a custom request header on every navigation, KEY=VALUE (repeatable). " +
                     "Reaches auth-walled preview deploys, e.g. --header x-vercel-protection-bypass=<token>",
             },
-            { name: "watch", type: "boolean", description: "Stream progress and exit non-zero on failure" },
+            { name: "watch", type: "boolean", description: "Follow progress and exit non-zero on failure" },
             { name: "timeout", type: "number", description: "With --watch: max minutes to wait" },
             {
                 name: "retries",
@@ -84,21 +85,28 @@ 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 --group Smoke --group Checkout --watch",
             "beryl runs trigger --retries 0 --watch",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             let tests = input.flags.test;
-            const group = flagStr(input, "group");
-            if (group && tests && tests.length > 0)
+            const groups = input.flags.group;
+            if (groups && groups.length > 0 && tests && tests.length > 0)
                 throw new UsageError("--group cannot be combined with --test");
-            if (group) {
+            if (groups && groups.length > 0) {
                 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 union = new Set();
+                for (const group of groups) {
+                    const ids = idsInGroup(listed, group);
+                    // Exiting 0 here would be a green CI run that tested nothing (or a typo'd
+                    // group silently narrowing the run).
+                    if (ids.length === 0)
+                        throw new UsageError(`No active tests in group '${group}'.`);
+                    for (const id of ids)
+                        union.add(id);
+                }
+                tests = [...union];
             }
             const extraHeaders = parseHeaders(input.flags.header);
             const created = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/runs`, {
@@ -563,7 +571,7 @@ export const runCommands = [
     },
     {
         name: "runs watch",
-        summary: "Attach to a run and stream progress until it finishes",
+        summary: "Follow a run until it finishes",
         description: "Replays what already happened, then follows live. Exits 0 only if every test passed.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],

package/dist/commands/watch.js

@@ -1,70 +1,137 @@
 import { CliError } from "../errors.js";
-import { dim, green, red, statusColor, yellow } from "../output.js";
 import { sseStream } from "../sse.js";
+import { dim, green, red, statusColor, yellow } from "../output.js";
 import { projectPath } from "./util.js";
 function withTimeout(minutes) {
     if (!minutes)
         return undefined;
     return AbortSignal.timeout(minutes * 60_000);
 }
+const PROGRESS_WAIT_S = 25;
+const HEARTBEAT_MS = 180_000;
+const SETTLED = new Set(["passed", "failed", "errored", "cancelled"]);
+const TERMINAL_RUN = new Set(["completed", "failed", "cancelled"]);
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function settledCount(c) {
+    return ((c.passed ?? 0) +
+        (c.failed ?? 0) +
+        (c.errored ?? 0) +
+        (c.cancelled ?? 0) +
+        (c.quarantined ?? 0));
+}
+// Watching a cloud run is a poll, not a stream: each request parks server-side
+// for up to PROGRESS_WAIT_S and returns when a test settles, so a dropped
+// request or an api deploy costs one retry instead of the whole watch.
 export async function watchRun(ctx, ws, project, runId, timeoutMinutes) {
-    const signal = withTimeout(timeoutMinutes);
-    let finalStatus = "unknown";
-    let counters = {};
-    const seen = new Set();
-    for await (const ev of sseStream(ctx.client, `${projectPath(ws, project)}/runs/${runId}/stream`, signal)) {
-        if (ctx.json) {
-            ctx.out(JSON.stringify(ev));
+    const path = projectPath(ws, project);
+    const deadline = timeoutMinutes ? Date.now() + timeoutMinutes * 60_000 : undefined;
+    const tty = Boolean(process.stderr.isTTY) && !ctx.json;
+    const printed = new Set();
+    let since = 0;
+    let backoffMs = 2_000;
+    let lastHeartbeat = Date.now();
+    let spin = 0;
+    let run = null;
+    const clearStatusLine = () => {
+        if (tty)
+            process.stderr.write("\r\u001b[2K");
+    };
+    const printRow = (r) => {
+        const ok = r.status === "passed";
+        // 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(r.quarantined) && !ok;
+        const mark = ok ? green("✓") : muted ? yellow("⚠") : red("✗");
+        const label = muted ? yellow(`${r.status} (quarantined)`) : statusColor(r.status);
+        const duration = r.duration_ms ? dim(` ${Math.round(r.duration_ms / 1000)}s`) : "";
+        const errorText = r.error_message ? ` ${String(r.error_message).slice(0, 120)}` : "";
+        const error = errorText ? (muted ? dim(errorText) : red(errorText)) : "";
+        ctx.err(`${mark} ${label} ${dim(r.title || r.id)}${duration}${error}`);
+    };
+    if (!ctx.json)
+        ctx.err(dim(`watching run ${runId}`));
+    let lastCounters = {};
+    while (true) {
+        if (deadline && Date.now() > deadline) {
+            clearStatusLine();
+            throw new CliError(`Timed out after ${timeoutMinutes} minutes`, 1);
         }
-        if (ev.counters)
-            counters = ev.counters;
-        const kind = ev.event;
-        if (!ctx.json) {
-            if (kind === "run_started") {
-                ctx.err(dim(`run ${runId} started`));
+        let progress;
+        try {
+            progress = (await ctx.client.get(`${path}/runs/${runId}/progress?since_version=${since}&wait=${PROGRESS_WAIT_S}`));
+            backoffMs = 2_000;
+        }
+        catch (e) {
+            clearStatusLine();
+            if (!ctx.json)
+                ctx.err(dim(`watch request failed (${e.message}); retrying`));
+            await sleep(backoffMs);
+            backoffMs = Math.min(backoffMs * 2, 30_000);
+            continue;
+        }
+        lastCounters = progress.counters ?? {};
+        const version = Number(progress.version ?? 0);
+        const changed = version !== since || TERMINAL_RUN.has(progress.status);
+        since = version;
+        if (changed) {
+            try {
+                run = (await ctx.client.get(`${path}/runs/${runId}`));
+                backoffMs = 2_000;
             }
-            else if (kind === "test_retrying") {
-                ctx.err(yellow(`↻ retrying ${dim(String(ev.test_result_id))} (attempt ${ev.attempt_no} failed)`));
+            catch {
+                // Same backoff as the poll: a terminal run answers the next poll
+                // instantly, so retrying without a delay would busy-loop both endpoints.
+                await sleep(backoffMs);
+                backoffMs = Math.min(backoffMs * 2, 30_000);
+                continue;
             }
-            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";
-                    // 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 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}`);
+            for (const r of run?.test_results ?? []) {
+                if (SETTLED.has(r.status) && !printed.has(r.id)) {
+                    printed.add(r.id);
+                    clearStatusLine();
+                    if (ctx.json)
+                        ctx.out(JSON.stringify({ event: "test_completed", ...r }));
+                    else
+                        printRow(r);
                 }
             }
+            if (run && TERMINAL_RUN.has(run.status))
+                break;
         }
-        if (kind === "run_completed" || kind === "run_cancelled") {
-            finalStatus = ev.status ?? kind;
-            break;
+        const done = settledCount(lastCounters);
+        const total = lastCounters.total ?? "?";
+        if (tty) {
+            spin = (spin + 1) % SPINNER.length;
+            const reds = (lastCounters.failed ?? 0) + (lastCounters.errored ?? 0);
+            process.stderr.write(`\r\u001b[2K${SPINNER[spin]} running ${done}/${total} · ` +
+                `${green(`${lastCounters.passed ?? 0}✓`)} ${reds > 0 ? red(`${reds}✗`) : dim("0✗")}`);
         }
-        if (kind === "error") {
-            finalStatus = "error";
-            break;
+        else if (!ctx.json && Date.now() - lastHeartbeat > HEARTBEAT_MS) {
+            lastHeartbeat = Date.now();
+            ctx.err(dim(`still running: ${done}/${total} settled`));
         }
     }
-    if (signal?.aborted)
-        throw new CliError(`Timed out after ${timeoutMinutes} minutes`, 1);
+    clearStatusLine();
+    const counters = {
+        passed: run?.passed_count ?? 0,
+        failed: run?.failed_count ?? 0,
+        errored: run?.errored_count ?? 0,
+        cancelled: run?.cancelled_count ?? 0,
+        quarantined: run?.quarantined_count ?? 0,
+        total: run?.total_tests ?? settledCount(lastCounters),
+        flaky: run?.summary?.flaky ?? 0,
+        healed: run?.summary?.healed ?? 0,
+    };
+    const finalStatus = run?.status ?? "unknown";
     // 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
+    // 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
+    // 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`) : "") +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",