@beryl-so/cli 0.61.0 → 0.62.1

package/dist/adapters/cli.js

@@ -1,4 +1,4 @@
-import { loadConfig } from "../config.js";
+import { loadConfig, withFlagOverrides } from "../config.js";
 import { createContext } from "../context.js";
 import { CliError, EXIT_OK, EXIT_USAGE, UsageError } from "../errors.js";
 import { ApiClient } from "../http.js";
@@ -317,11 +317,17 @@ export async function runCli(argv) {
         process.stdout.write(commandHelp(spec) + "\n");
         return EXIT_OK;
     }
-    const config = loadConfig();
-    if (parsed.apiUrl)
-        config.apiUrl = parsed.apiUrl;
-    if (parsed.token)
-        config.token = parsed.token;
+    let config;
+    try {
+        config = withFlagOverrides(loadConfig(), { apiUrl: parsed.apiUrl, token: parsed.token });
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            process.stderr.write(err.message + "\n");
+            return err.exitCode;
+        }
+        throw err;
+    }
     const client = new ApiClient(config.apiUrl, config.token);
     const ctx = createContext({ client, config, json: parsed.json, mcp: false });
     // The MCP server reports its own tool calls; every other invocation is one command.

package/dist/adapters/mcp.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { instrument } from "@posthog/mcp";
 import fs from "node:fs";
-import { loadConfig } from "../config.js";
+import { loadConfig, withFlagOverrides } from "../config.js";
 import { createContext } from "../context.js";
 import { AuthError, CliError } from "../errors.js";
 import { ApiClient, ApiError } from "../http.js";
@@ -222,7 +222,7 @@ export function currentAuth(fallback) {
     }
     if (authCache?.mtimeMs === mtimeMs)
         return authCache.auth;
-    const config = loadConfig();
+    const config = withFlagOverrides(loadConfig(), fallback.config.flagOverrides ?? {});
     const auth = {
         client: new ApiClient(config.apiUrl, config.token),
         config,
@@ -330,17 +330,17 @@ export async function serveMcp(baseCtx) {
             if (lines.length > 400)
                 lines.splice(0, lines.length - 400);
         };
-        const auth = currentAuth(baseCtx);
-        const ctx = createContext({
-            client: auth.client,
-            config: auth.config,
-            json: true,
-            interactive: false,
-            mcp: true,
-            out: push,
-            err: push,
-        });
         try {
+            const auth = currentAuth(baseCtx);
+            const ctx = createContext({
+                client: auth.client,
+                config: auth.config,
+                json: true,
+                interactive: false,
+                mcp: true,
+                out: push,
+                err: push,
+            });
             const input = toInput(spec, request.params.arguments ?? {});
             const result = (await withTool(request.params.name, () => spec.run(ctx, input))) ?? {};
             return toolResult(result, lines);

package/dist/commands/explorations.js

@@ -53,7 +53,8 @@ export const explorationCommands = [
         name: "explorations watch",
         summary: "Stream an exploration live: watch the agent explore and author tests",
         description: "Replays every recorded step on connect, then follows live until the exploration " +
-            "completes or fails.",
+            "ends. Exits 0 only if it completed; a failed or cancelled exploration, or a stream " +
+            "that keeps closing without a final status, exits 1.",
         scope: "project",
         args: [{ name: "exploration-id", description: "Exploration id", required: true }],
         flags: [{ name: "timeout", type: "number", description: "Max minutes to wait" }],

package/dist/commands/health.js

@@ -275,7 +275,8 @@ export const healthCommands = [
             "`selector`, measured values, the `viewports` it shows at and a fix hint in " +
             "`recommendation`. The `performance` category grades Google PageSpeed on mobile " +
             "and on desktop separately (`speeds`, each with its own Core Web Vitals) and takes " +
-            "the worse of the two; one that couldn't be measured is left out. Pass --report for a single-page check started with " +
+            "the worse of the two; one that couldn't be measured is left out. A category's `unchecked` lists checks this run " +
+            "couldn't determine (e.g. robots.txt timed out): they neither pass nor fail. Pass --report for a single-page check started with " +
             "`health run --path`.",
         scope: "project",
         flags: [
@@ -321,7 +322,8 @@ export const healthCommands = [
             "With --ci it starts a CI run, waits for every page, prints a Markdown summary you can " +
             "post as the PR comment, and exits 1 when findings at or above the environment's " +
             "fail-on severity exist, a page couldn't be checked, or the run failed. Builds that the " +
-            "environment's CI mode doesn't cover skip and exit 0. CI runs file tracker tickets only when --health-ci-tickets is on.",
+            "environment's CI mode doesn't cover skip and exit 0; if the stored run settings are invalid it exits 1 " +
+            "rather than skipping. CI runs file tracker tickets only when --health-ci-tickets is on.",
         scope: "project",
         flags: [
             ENV_FLAG,

package/dist/commands/init.js

@@ -77,26 +77,21 @@ function mergeMcpConfig(file, key, entries) {
     }
     return { beryl, playwright };
 }
-// A tool's config lives per-user (same as the PAT it needs, in ~/.config/beryl) — so wire the
-// MCP servers per-user too, not in a committed .mcp.json that 401s for every teammate until
-// they run `beryl login` anyway. We DON'T hand-edit ~/.claude.json (Claude Code owns it; a
-// corrupt write breaks the user's whole CLI) — we shell out to `claude mcp add` and let Claude
-// own the edit. Returns false when the `claude` binary isn't on PATH so the caller can fall
-// back to a copy-paste command.
 function claudeUserAdd(name, entry) {
     try {
         execFileSync("claude", ["mcp", "add", name, "-s", "user", "--", entry.command, ...entry.args], {
-            stdio: "ignore",
+            stdio: ["ignore", "pipe", "pipe"],
         });
-        return true;
+        return { ok: true };
     }
     catch (err) {
-        // A non-zero exit ALSO covers "already exists" — but so does a missing binary. Distinguish:
-        // ENOENT means no `claude` on PATH (fall back), anything else means it ran and declined
-        // (already configured — treat as success, nothing to do).
-        if (err.code === "ENOENT")
-            return false;
-        return true;
+        const e = err;
+        if (e.code === "ENOENT")
+            return { ok: false, reason: "missing" };
+        const output = `${e.stderr ?? ""}\n${e.stdout ?? ""}`.trim();
+        if (/already exists/i.test(output))
+            return { ok: true };
+        return { ok: false, reason: "failed", detail: output.split("\n")[0] || e.message };
     }
 }
 function claudeAddHint(name, entry) {
@@ -399,13 +394,16 @@ export const initCommands = [
             const clients = await selectClients(ctx, input.flags);
             if (clients.has("claude") && scope === "user") {
                 // Claude Code owns ~/.claude.json — shell out to `claude mcp add` rather than write it.
-                const berylOk = claudeUserAdd("beryl", MCP_SERVER_ENTRY);
-                const playwrightOk = claudeUserAdd("playwright", PLAYWRIGHT_SERVER_ENTRY);
-                if (berylOk && playwrightOk) {
+                const beryl = claudeUserAdd("beryl", MCP_SERVER_ENTRY);
+                const playwright = claudeUserAdd("playwright", PLAYWRIGHT_SERVER_ENTRY);
+                if (beryl.ok && playwright.ok) {
                     ctx.err(`${green("✓")} beryl + playwright MCP configured ${dim("(user scope)")}`);
                 }
                 else {
-                    ctx.err(yellow("• `claude` not on PATH — run these to wire user-scope MCP servers:"));
+                    const failure = [beryl, playwright].find((r) => !r.ok && r.reason === "failed");
+                    ctx.err(yellow(failure
+                        ? `• \`claude mcp add\` failed (${failure.detail}); run these to wire user-scope MCP servers:`
+                        : "• `claude` not on PATH; run these to wire user-scope MCP servers:"));
                     ctx.err(`    ${cyan(claudeAddHint("beryl", MCP_SERVER_ENTRY))}`);
                     ctx.err(`    ${cyan(claudeAddHint("playwright", PLAYWRIGHT_SERVER_ENTRY))}`);
                 }

package/dist/commands/runs.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { downloadRunArtifacts, failureImages, isFailing, resultsOf, } from "../artifacts.js";
-import { CliError, UsageError } from "../errors.js";
+import { AuthError, CliError, UsageError } from "../errors.js";
+import { ApiError } from "../http.js";
 import { buildImportForm, establishAccountSession, executeLocalSpec, IMPORT_MAX_ERROR_LEN, specUsesThirdParty, THIRD_PARTY_USE_TRIGGER, toRunEntry, } from "../local-exec.js";
 import { countPlannedFrames, countWrittenFrames, PlaywrightMissingError, } from "../local-run.js";
 import { dim, green, red, yellow } from "../output.js";
@@ -155,7 +156,9 @@ export const runCommands = [
             "captured server-side, or that has third party integration steps (cloud only), 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.",
+            "and reports on disk. With no ids, a test with no plan yet is skipped quietly; one " +
+            "whose script can't be fetched is listed under `skipped` and fails the run. Exits 0 " +
+            "only if every executed test passed and every script was fetched.",
         scope: "project",
         args: [
             {
@@ -265,25 +268,34 @@ export const runCommands = [
                 ...(script.login_config_error ? { loginConfigError: script.login_config_error } : {}),
             });
             const specs = [];
+            // With --all, a test the server can't render (no plan yet, 409) is a quiet skip;
+            // any other fetch failure is listed and fails the run. An explicitly-requested id
+            // failing to render is the caller's problem.
+            const fetchFailed = [];
             for (const id of ids) {
                 let script;
                 try {
                     script = await fetchScript(id);
                 }
                 catch (err) {
-                    // With --all an unrenderable test (no plan yet) is a skip, not an abort;
-                    // an explicitly-requested id failing to render is the caller's problem.
-                    if (all) {
-                        const detail = err instanceof Error ? err.message : String(err);
+                    if (!all || err instanceof AuthError)
+                        throw err;
+                    const detail = err instanceof Error ? err.message : String(err);
+                    if (err instanceof ApiError && err.status === 409) {
                         ctx.err(yellow(`! ${titles.get(id) ?? id}: no runnable script — skipped (${detail})`));
-                        continue;
                     }
-                    throw err;
+                    else {
+                        fetchFailed.push(id);
+                        ctx.err(red(`✗ ${titles.get(id) ?? id}: could not fetch its script (${detail})`));
+                    }
+                    continue;
                 }
                 specs.push(toLocalSpec(id, script));
             }
             if (specs.length === 0)
-                throw new CliError("No runnable tests were found.");
+                throw new CliError(fetchFailed.length
+                    ? `Could not fetch the script for ${fetchFailed.length} test(s); nothing ran.`
+                    : "No runnable tests were found.");
             // A test that leans on a session this CLI cannot establish gets no session here,
             // so skip it rather than run a spec doomed at the login wall. A session-mode test
             // is NOT in that set: its account's session is established below, once, exactly as
@@ -499,6 +511,9 @@ export const runCommands = [
                 : red(`${failed} test(s) failed`) + ` (${passed} passed)`;
             const human = `${summaryLine}` +
                 (skipped.length ? `\n${yellow(`${skipped.length} skipped (see notes above)`)}` : "") +
+                (fetchFailed.length
+                    ? `\n${red(`${fetchFailed.length} could not be fetched (see notes above)`)}`
+                    : "") +
                 (runId ? `\nSynced to Beryl as run ${runId} — \`beryl runs get ${runId}\`` : "") +
                 (!sync ? `\n${dim("--no-sync: nothing recorded in Beryl")}` : "") +
                 (dir ? `\n${dim(`Specs + artifacts + reports under ${path.resolve(dir)}`)}` : "");
@@ -506,13 +521,13 @@ export const runCommands = [
                 data: {
                     passed,
                     failed,
-                    skipped: skipped.map((s) => s.id),
+                    skipped: [...skipped.map((s) => s.id), ...fetchFailed],
                     results: entries.map(({ files: _files, ...rest }) => rest),
                     ...(runId ? { run_id: runId } : {}),
                 },
                 human,
-                // Exit codes are a CI contract: any failing/errored test → exit 1.
-                ...(failed > 0 ? { exitCode: 1 } : {}),
+                // Exit codes are a CI contract: any failing/errored or unfetchable test → exit 1.
+                ...(failed > 0 || fetchFailed.length > 0 ? { exitCode: 1 } : {}),
             };
         },
     },

package/dist/commands/third-party-integrations.js

@@ -29,7 +29,8 @@ export const thirdPartyIntegrationCommands = [
         description: "Returns the project's own destination on Beryl's provider account (for Slack, a " +
             "channel), creating it on first ask. When a test connects the app, it picks this " +
             "channel in the app's settings; `await_third_party` then waits for the app's message " +
-            "there. `recorded_app_id` is the app whose first message was seen, null until then. " +
+            "there. `recorded_app_ids` maps each environment id to the app whose first message " +
+            "was seen there; an environment accepts only its own app once recorded. " +
             "A 409 means the provider is not set up on this deployment (see " +
             "`third-party-integrations list`).",
         scope: "project",
@@ -51,8 +52,10 @@ export const thirdPartyIntegrationCommands = [
             return {
                 data: target,
                 human: `#${target.external_name}\n\n` +
-                    dim(`Pick this channel in the app when the test connects ${target.provider}.` +
-                        (target.recorded_app_id ? ` Recorded app: ${target.recorded_app_id}` : "")),
+                    dim(`Pick this channel in the app when the test connects ${target.provider}.`) +
+                    Object.entries(target.recorded_app_ids ?? {})
+                        .map(([env, app]) => dim(`\nRecorded app for environment ${env}: ${app}`))
+                        .join(""),
             };
         },
     },

package/dist/commands/watch.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
-import { CliError } from "../errors.js";
+import { AuthError, CliError } from "../errors.js";
+import { ApiError, NonJsonResponseError } from "../http.js";
 import { sseStream } from "../sse.js";
 import { dim, green, red, statusColor, yellow } from "../output.js";
 import { projectPath } from "./util.js";
@@ -34,6 +35,15 @@ function runPageUrl(apiUrl, projectId, runId) {
 }
 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");
+// Auth, client and wrong-host errors fail identically on every retry; only a network
+// blip, a timeout, throttling or a 5xx is worth waiting out.
+function isRetryable(e) {
+    if (e instanceof AuthError || e instanceof NonJsonResponseError)
+        return false;
+    if (e instanceof ApiError)
+        return e.status >= 500 || e.status === 408 || e.status === 429;
+    return true;
+}
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
@@ -97,9 +107,10 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
             backoffMs = 2_000;
         }
         catch (e) {
+            if (!isRetryable(e))
+                throw e;
             clearStatusLine();
-            if (!ctx.json)
-                ctx.err(dim(`watch request failed (${e.message}); retrying`));
+            ctx.err(dim(`watch request failed (${e.message}); retrying`));
             await sleep(backoffMs);
             backoffMs = Math.min(backoffMs * 2, 30_000);
             continue;
@@ -118,7 +129,11 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
                 run = (await ctx.client.get(`${path}/runs/${runId}`));
                 backoffMs = 2_000;
             }
-            catch {
+            catch (e) {
+                if (!isRetryable(e))
+                    throw e;
+                clearStatusLine();
+                ctx.err(dim(`run detail request failed (${e.message}); retrying`));
                 // 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);
@@ -148,9 +163,10 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
                 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.
+                catch (e) {
+                    // The failure that triggered the cancel decides the exit code; this only
+                    // warns that the run may still be consuming minutes.
+                    ctx.err(yellow(`fail-fast: could not cancel run ${runId} (${e.message})`));
                 }
                 break;
             }
@@ -279,7 +295,7 @@ export async function watchExploration(ctx, ws, project, explorationId, timeoutM
     }
     return {
         data: { exploration_id: explorationId, status: finalStatus, test_run_id: handedOffRunId, error },
-        exitCode: finalStatus === "failed" ? 1 : 0,
+        exitCode: finalStatus === "completed" ? 0 : 1,
     };
 }
 export async function pollCurrentExploration(ctx, ws, project, timeoutSeconds = 180) {

package/dist/config.js

@@ -2,20 +2,44 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { CliError } from "./errors.js";
 export const DEFAULT_API_URL = "https://api.beryl.so";
+export function withFlagOverrides(config, flags) {
+    return {
+        ...config,
+        ...(flags.apiUrl ? { apiUrl: flags.apiUrl } : {}),
+        ...(flags.token ? { token: flags.token } : {}),
+        flagOverrides: flags,
+    };
+}
 export function globalConfigPath(env = process.env) {
     const base = env.BERYL_CONFIG_DIR ??
         (env.XDG_CONFIG_HOME ? path.join(env.XDG_CONFIG_HOME, "beryl") : undefined) ??
         path.join(os.homedir(), ".config", "beryl");
     return path.join(base, "config.json");
 }
+// Only a missing file means "no config". Anything else must stop the command: treating
+// it as empty would drop the token and api_url, then the next write would overwrite it.
 function readJson(file) {
+    let text;
     try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
+        text = fs.readFileSync(file, "utf8");
     }
-    catch {
-        return undefined;
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw new CliError(`Could not read ${file}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new CliError(`${file} is not valid JSON (${err.message}). Fix or delete it, then retry.`);
     }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new CliError(`${file} must hold a JSON object. Fix or delete it, then retry.`);
+    return parsed;
 }
 export function loadConfig(env = process.env) {
     const globalPath = globalConfigPath(env);

package/dist/http.js

@@ -11,6 +11,8 @@ export class ApiError extends CliError {
         this.detail = detail;
     }
 }
+export class NonJsonResponseError extends CliError {
+}
 export class ApiClient {
     baseUrl;
     token;
@@ -85,7 +87,9 @@ export class ApiClient {
             return JSON.parse(text);
         }
         catch {
-            return text;
+            const type = response.headers.get("content-type") ?? "no content-type";
+            throw new NonJsonResponseError(`${this.baseUrl} answered ${method} ${path} with non-JSON (${type}); ` +
+                "is the API URL pointing at the Beryl API?");
         }
     }
     get(path, query) {

package/dist/sse.js

@@ -69,7 +69,7 @@ export async function* sseStream(client, path, signal) {
             // Clean server-side close without a terminal event: reconnect and replay.
             failures += 1;
             if (failures >= MAX_CONSECUTIVE_FAILURES)
-                return;
+                throw new CliError(`Stream closed ${failures} times without a terminal event; its status is unknown`);
             await sleep(1000, signal);
         }
         catch (err) {

package/package.json

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