@beryl-so/cli 0.37.0 → 0.40.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` |
@@ -359,11 +359,14 @@ Send product feedback to the Beryl team.
 
 ### billing
 
-Review a workspace's plan usage, subscription, and invoices.
+Review a workspace's plan usage, subscription, and invoices; upgrade or switch plans.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl billing usage` | Show plan usage: monthly cloud run minutes | none |
+| `beryl billing plans` | List the plans: price, cloud run minutes, storage, overage terms | none |
+| `beryl billing usage` | Show plan usage: cloud run minutes, storage held, and this month's overage | none |
+| `beryl billing checkout` | Get a Stripe Checkout link that moves a Free workspace onto Team or Business | none |
+| `beryl billing plan` | Switch a paid workspace between Team and Business in place (prorated) | none |
 | `beryl billing subscription` | Show the workspace's subscription | none |
 | `beryl billing invoices` | List recent invoices | none |
 | `beryl billing portal` | Get a Stripe billing-portal link for the workspace | none |

package/dist/commands/account.js

@@ -43,16 +43,53 @@ export const accountCommands = [
             return { data: await ctx.client.post("/feedback", { message: arg(input, "message") }) };
         },
     },
+    {
+        name: "billing plans",
+        summary: "List the plans: price, cloud run minutes, storage, overage terms",
+        groupSummary: "Review a workspace's plan usage, subscription, and invoices; upgrade or switch plans.",
+        async run(ctx) {
+            return { data: await ctx.client.get("/billing/plans") };
+        },
+    },
     {
         name: "billing usage",
-        summary: "Show plan usage: monthly cloud run minutes",
+        summary: "Show plan usage: cloud run minutes, storage held, and this month's overage",
         scope: "workspace",
-        groupSummary: "Review a workspace's plan usage, subscription, and invoices.",
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
             return { data: await ctx.client.get(`/workspaces/${ws}/billing/usage`) };
         },
     },
+    {
+        name: "billing checkout",
+        summary: "Get a Stripe Checkout link that moves a Free workspace onto Team or Business",
+        scope: "workspace",
+        flags: [
+            { name: "plan", type: "string", description: "team or business", required: true },
+        ],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            const plan = flagStr(input, "plan");
+            if (plan !== "team" && plan !== "business")
+                throw new UsageError("--plan must be team or business");
+            return { data: await ctx.client.post(`/workspaces/${ws}/billing/checkout`, { plan }) };
+        },
+    },
+    {
+        name: "billing plan",
+        summary: "Switch a paid workspace between Team and Business in place (prorated)",
+        scope: "workspace",
+        flags: [
+            { name: "plan", type: "string", description: "team or business", required: true },
+        ],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            const plan = flagStr(input, "plan");
+            if (plan !== "team" && plan !== "business")
+                throw new UsageError("--plan must be team or business");
+            return { data: await ctx.client.post(`/workspaces/${ws}/billing/plan`, { plan }) };
+        },
+    },
     {
         name: "billing subscription",
         summary: "Show the workspace's subscription",
@@ -82,11 +119,7 @@ export const accountCommands = [
         scope: "workspace",
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
-            return {
-                data: await ctx.client.post(`/workspaces/${ws}/billing/portal`, {
-                    return_url: "https://beryl.so/settings/billing",
-                }),
-            };
+            return { data: await ctx.client.post(`/workspaces/${ws}/billing/portal`, {}) };
         },
     },
 ];

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 " +
@@ -72,8 +72,14 @@ 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: "fail-fast",
+                type: "boolean",
+                description: "With --watch: cancel the run and exit 1 on the first failing test, instead of " +
+                    "waiting for the rest of the suite. Built for CI gates; off by default",
+            },
             {
                 name: "retries",
                 type: "number",
@@ -118,7 +124,10 @@ export const runCommands = [
             }));
             if (!flagBool(input, "watch"))
                 return { data: created };
-            return await watchRun(ctx, workspaceId, projectId, created.id, flagNum(input, "timeout"));
+            return await watchRun(ctx, workspaceId, projectId, created.id, flagNum(input, "timeout"), {
+                failFast: flagBool(input, "fail-fast"),
+                ci: process.env.GITHUB_ACTIONS === "true",
+            });
         },
     },
     {
@@ -571,14 +580,25 @@ 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 }],
-        flags: [{ name: "timeout", type: "number", description: "Max minutes to wait" }],
+        flags: [
+            { name: "timeout", type: "number", description: "Max minutes to wait" },
+            {
+                name: "fail-fast",
+                type: "boolean",
+                description: "Cancel the run and exit 1 on the first failing test, instead of waiting for " +
+                    "the rest of the suite. Built for CI gates; off by default",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return await watchRun(ctx, workspaceId, projectId, arg(input, "run-id"), flagNum(input, "timeout"));
+            return await watchRun(ctx, workspaceId, projectId, arg(input, "run-id"), flagNum(input, "timeout"), {
+                failFast: flagBool(input, "fail-fast"),
+                ci: process.env.GITHUB_ACTIONS === "true",
+            });
         },
     },
     {

package/dist/commands/watch.js

@@ -1,70 +1,193 @@
+import fs from "node:fs";
 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);
 }
-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 PROGRESS_WAIT_S = 25;
+const HEARTBEAT_MS = 180_000;
+const SETTLED = new Set(["passed", "failed", "errored", "cancelled"]);
+const FAILING = new Set(["failed", "errored"]);
+const TERMINAL_RUN = new Set(["completed", "failed", "cancelled"]);
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const CI_ERROR_MAX_LEN = 4_000;
+function runPageUrl(apiUrl, projectId, runId) {
+    if (!apiUrl)
+        return null;
+    let host;
+    try {
+        host = new URL(apiUrl).hostname;
+    }
+    catch {
+        return null;
+    }
+    const webapp = host === "api.beryl.so"
+        ? "https://beryl.so"
+        : host === "dev.beryl.so"
+            ? "https://preview.beryl.so"
+            : null;
+    return webapp ? `${webapp}/projects/${projectId}/runs/${runId}` : null;
+}
+const escapeAnnotationData = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const escapeAnnotationProp = (s) => escapeAnnotationData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+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, opts = {}) {
+    const path = projectPath(ws, project);
+    const deadline = timeoutMinutes ? Date.now() + timeoutMinutes * 60_000 : undefined;
+    const tty = Boolean(process.stderr.isTTY) && !ctx.json;
+    const ci = Boolean(opts.ci) && !ctx.json;
+    const printed = new Set();
+    let since = 0;
+    let backoffMs = 2_000;
+    let lastHeartbeat = Date.now();
+    let spin = 0;
+    let run = null;
+    let knownTotal = 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 seq = ci ? dim(`${printed.size}/${knownTotal ?? "?"} `) : "";
+        const fullError = ci && !ok && !muted;
+        const errorText = r.error_message && !fullError ? ` ${String(r.error_message).slice(0, 120)}` : "";
+        const error = errorText ? (muted ? dim(errorText) : red(errorText)) : "";
+        ctx.err(`${seq}${mark} ${label} ${dim(r.title || r.id)}${duration}${error}`);
+        if (fullError && r.error_message) {
+            const detail = String(r.error_message).slice(0, CI_ERROR_MAX_LEN);
+            ctx.err(red(detail.replace(/^/gm, "    ")));
+            process.stdout.write(`::error title=${escapeAnnotationProp(r.title || r.id)}::${escapeAnnotationData(detail)}\n`);
         }
-        if (ev.counters)
-            counters = ev.counters;
-        const kind = ev.event;
-        if (!ctx.json) {
-            if (kind === "run_started") {
-                ctx.err(dim(`run ${runId} started`));
+    };
+    if (!ctx.json)
+        ctx.err(dim(`watching run ${runId}`));
+    let lastCounters = {};
+    let failFastStop = false;
+    while (true) {
+        if (deadline && Date.now() > deadline) {
+            clearStatusLine();
+            throw new CliError(`Timed out after ${timeoutMinutes} minutes`, 1);
+        }
+        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;
+        }
+        // Not every event carries counters, so an empty snapshot means "no news",
+        // not "zero settled": keep the last populated one.
+        if (progress.counters && Object.keys(progress.counters).length > 0)
+            lastCounters = progress.counters;
+        if (lastCounters.total)
+            knownTotal = lastCounters.total;
+        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;
+            }
+            if (run?.total_tests)
+                knownTotal = run.total_tests;
+            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 (opts.failFast && FAILING.has(r.status) && !r.quarantined) {
+                        failFastStop = true;
+                        break;
+                    }
+                }
             }
-            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}`);
+            if (failFastStop) {
+                clearStatusLine();
+                if (!ctx.json)
+                    ctx.err(red(`fail-fast: cancelling run ${runId}`));
+                try {
+                    await ctx.client.post(`${path}/runs/${runId}/cancel`);
                 }
+                catch {
+                    // Best-effort: the cancel may race the worker or the run may already be
+                    // terminal; the failure that triggered it decides the exit code anyway.
+                }
+                break;
             }
+            if (run && TERMINAL_RUN.has(run.status))
+                break;
         }
-        if (kind === "run_completed" || kind === "run_cancelled") {
-            finalStatus = ev.status ?? kind;
-            break;
+        const done = Math.max(settledCount(lastCounters), printed.size);
+        const total = lastCounters.total || knownTotal || "?";
+        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 = failFastStop ? "failed" : (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`) : "") +
@@ -75,8 +198,44 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes) {
         : green(`${passed} passed`) + extra;
     if (!ctx.json)
         ctx.err(`\n${statusColor(finalStatus)}: ${summary}`);
+    const link = runPageUrl(ctx.client.baseUrl, project, runId);
+    if (ci && link)
+        ctx.err(dim(link));
+    if (ci && process.env.GITHUB_STEP_SUMMARY) {
+        const failures = (run?.test_results ?? []).filter((r) => FAILING.has(r.status) && !r.quarantined);
+        const md = [
+            `### Beryl run ${finalStatus}${failFastStop ? " (fail-fast)" : ""}`,
+            "",
+            "| passed | failed | errored | cancelled | quarantined | total |",
+            "| --- | --- | --- | --- | --- | --- |",
+            `| ${counters.passed} | ${counters.failed} | ${counters.errored} | ${counters.cancelled} | ${counters.quarantined} | ${counters.total} |`,
+            ...(link ? ["", `[Open the run in Beryl](${link})`] : []),
+            ...failures.flatMap((r) => [
+                "",
+                `**✗ ${r.title || r.id}**`,
+                "```",
+                String(r.error_message ?? "").slice(0, CI_ERROR_MAX_LEN),
+                "```",
+            ]),
+            "",
+        ];
+        try {
+            fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, md.join("\n"));
+        }
+        catch {
+            // The summary is decoration; never fail the watch over it.
+        }
+    }
     const exitCode = finalStatus === "completed" && failed === 0 ? 0 : 1;
-    return { data: { run_id: runId, status: finalStatus, ...counters }, exitCode };
+    return {
+        data: {
+            run_id: runId,
+            status: finalStatus,
+            ...(failFastStop ? { fail_fast: true } : {}),
+            ...counters,
+        },
+        exitCode,
+    };
 }
 export async function watchExploration(ctx, ws, project, explorationId, timeoutMinutes) {
     const signal = withTimeout(timeoutMinutes);

package/package.json

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