@beryl-so/cli 0.67.0 → 0.73.2

package/dist/commands/init.js

@@ -20,8 +20,8 @@ const MCP_SERVER_ENTRY = {
     command: "npx",
     args: ["-y", "@beryl-so/cli@latest", "mcp"],
 };
-// Headless: the coding agent drives this browser to author tests — nobody watches the
-// window, and a headed default breaks on CI / headless boxes. Matches how most devs
+// Headless: the coding agent drives this browser to set up sign-ins and repair plans; nobody
+// watches the window, and a headed default breaks on CI / headless boxes. Matches how most devs
 // already wire their own user-scoped playwright.
 const PLAYWRIGHT_SERVER_ENTRY = {
     command: "npx",
@@ -194,7 +194,7 @@ const outcomeLabel = (o) => o === "installed"
         ? "updated (refreshed to this CLI's version)"
         : "already current";
 const skillLeaf = (root) => path.join(root, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME);
-// The authoring skill follows the `--scope` flag, same as the MCP servers: under `user`
+// The beryl-test skill follows the `--scope` flag, same as the MCP servers: under `user`
 // (the default) it lands in the HOME `.agents/skills/` + `.claude/skills/` dirs, so the
 // knowledge travels with the user into every session the user-scoped MCP tools do —
 // otherwise an agent outside this repo has all the tools and none of the guide. Under
@@ -230,8 +230,7 @@ export function refreshInstalledSkills(cwd) {
     }
     return refreshed;
 }
-// Local authoring drives a real browser, and the whole authoring workflow (walk the flow
-// first, then bank the plan) depends on it — so the install is mandatory, not offered:
+// Local runs drive a real browser, so the install is mandatory, not offered:
 // missing means install now, no prompt, no opt-out. The runner ships with the CLI; the
 // browser is the per-machine half, fetched for the runner's own revision. Never throws — a
 // failed install must not fail `init`, which has already done its wiring; it prints the
@@ -253,7 +252,7 @@ async function ensureLocalPlaywright(ctx, cwd) {
     }
     catch (err) {
         ctx.err(`${red("✗")} Playwright install failed: ${err.message}`);
-        ctx.err(`${dim("•")} Finish the install by hand — local runs and browser authoring need it:\n` +
+        ctx.err(`${dim("•")} Finish the install by hand; local runs need it:\n` +
             `    ${cyan(installCommandsFor(gaps, cwd))}`);
     }
 }
@@ -292,7 +291,7 @@ export const initCommands = [
         name: "init",
         summary: "Set up Beryl in this repo: sign in and wire up your coding agent",
         description: "Signs you in, wires the beryl and playwright MCP servers into the coding agent you " +
-            "pick, writes the beryl-test authoring skill, and installs Chromium if it is missing. " +
+            "pick, writes the beryl-test skill, and installs Chromium if it is missing. " +
             "Pick an agent with --claude, --cursor, --vscode and/or --opencode. With no flag it " +
             "prompts (Enter picks Claude); with no flag and no TTY it wires nothing and prints the " +
             "flags. --claude also wires the Claude DESKTOP app when installed, which needs a quit " +
@@ -507,7 +506,7 @@ export const initCommands = [
                 const where = skill.outcome === "updated"
                     ? `${skillWhere} (refreshed to this CLI's version)`
                     : skillWhere;
-                ctx.err(`${green("✓")} Beryl authoring skill ${what} ${dim(where)}`);
+                ctx.err(`${green("✓")} beryl-test skill ${what} ${dim(where)}`);
             }
             await ensureLocalPlaywright(ctx, cwd);
             // Name the agent actually wired, not the raw flag: the picker sets `clients` too.
@@ -519,7 +518,7 @@ export const initCommands = [
                         ? { open: "open VS Code", agent: "Copilot" }
                         : { open: "open opencode", agent: "opencode" };
             const nextSteps = clients.size === 0
-                ? `\n${bold("Beryl is signed in and the authoring skill is installed.")}\n` +
+                ? `\n${bold("Beryl is signed in and the beryl-test skill is installed.")}\n` +
                     `  ${dim("• No MCP server is wired yet, so no agent can reach Beryl.")}\n` +
                     `  ${dim(`• Using ${CLIENT_LABEL_LIST}? Re-run and pick it:`)}\n` +
                     `    ${cyan("npx @beryl-so/cli@latest init")}\n` +
@@ -527,10 +526,10 @@ export const initCommands = [
                     `${cyan(MANUAL_CONFIG_SNIPPET)}\n` +
                     `    ${dim("Some clients name that key `servers` or `mcp`.")}\n` +
                     `    ${yellow(`Details: ${MANUAL_SETUP_DOCS}`)}\n`
-                : `\n${bold(`Beryl is set up. Now ${ed.open} and ask ${ed.agent} to write tests.`)}\n` +
-                    `  ${dim(`• Say: "write tests for https://example.com" and ${ed.agent} picks your workspace/project`)}\n` +
-                    `  ${dim("  and sets the URL for you (no pin, no prompt).")}\n` +
-                    `  ${dim(`• Playwright MCP is wired, so ${ed.agent} can drive a real browser to author from your plan.`)}\n`;
+                : `\n${bold(`Beryl is set up. Now ${ed.open} and ask ${ed.agent} to create tests.`)}\n` +
+                    `  ${dim(`• Say: "create tests for https://example.com from docs/checkout.md" and ${ed.agent} starts`)}\n` +
+                    `  ${dim("  a cloud test-creation job that authors them from that document.")}\n` +
+                    `  ${dim(`• Then ask ${ed.agent} to run them on this machine (local runs) or in the cloud.`)}\n`;
             // The .mcp.json entry is pinned to @latest, but a global install / old npx cache
             // still wins resolution — so tell the user when the CLI they just ran is stale.
             await warnIfStale(cliVersion(), (msg) => ctx.err(yellow(msg)));
@@ -549,11 +548,12 @@ export const initCommands = [
     },
     {
         name: "guide",
-        summary: "Print the Beryl test-authoring guide",
-        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. " +
+        summary: "Print the Beryl test guide",
+        description: "The guide to durable, healable tests: where new tests come from (`jobs create`), 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 ` +
             "(works without logging in).",
         examples: ["beryl guide"],

package/dist/commands/jobs.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "../errors.js";
+import { arg, flagBool, flagStr, projectPath } from "./util.js";
+const jobsPath = (ws, p) => `${projectPath(ws, p)}/test-creation-jobs`;
+const LLM_NOTICE = "The document is sent to the LLM that drives the agent, so leave out anything you " +
+    "would not share with it.";
+function readDocument(file) {
+    try {
+        return new Uint8Array(fs.readFileSync(file));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            throw new UsageError(`file not found: ${file}`);
+        throw new UsageError(`cannot read ${file} (${code ?? err.message})`);
+    }
+}
+export function jobHuman(job) {
+    const lines = [`Job ${job.id}: ${job.status}`];
+    if (job.error)
+        lines.push(`Error: ${job.error}`);
+    for (const t of job.tests)
+        lines.push(`  ${t.title ?? t.id} [${t.surface}] ${t.id}`);
+    if (!job.tests.length)
+        lines.push("  No tests yet.");
+    const skipped = job.skipped_flows ?? [];
+    if (skipped.length)
+        lines.push("Skipped scenarios:");
+    for (const s of skipped)
+        lines.push(`  ${s.handle}: ${s.reason}`);
+    return lines.join("\n");
+}
+export const jobCommands = [
+    {
+        name: "jobs create",
+        groupSummary: "Test-creation jobs: the cloud agent reads a document and authors tests from it.",
+        summary: "Create tests from a document (PRD, release notes) on Beryl's cloud",
+        description: "Uploads a document (Markdown, plain text, PDF or DOCX, or --text) and queues a " +
+            "job: the agent explores the environment, drafts one flow per scenario the document " +
+            "describes, and authors one test per enabled surface of the project. New tests get " +
+            "no groups. A job runs once; to run it again, use `jobs clone`. " +
+            LLM_NOTICE,
+        scope: "project",
+        args: [{ name: "file", description: "Path to the document" }],
+        flags: [
+            { name: "text", type: "string", description: "The document as text, instead of a file" },
+            {
+                name: "env",
+                type: "string",
+                description: "Environment id to explore (defaults to the project's default)",
+            },
+        ],
+        examples: ["beryl jobs create ./release-notes.md --env <env-id>"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const file = input.args.file;
+            const text = flagStr(input, "text");
+            if (Boolean(file) === Boolean(text)) {
+                throw new UsageError("pass a document file or --text, not both");
+            }
+            const form = new FormData();
+            if (file)
+                form.set("file", new Blob([readDocument(file)]), path.basename(file));
+            else
+                form.set("text", text);
+            const envId = flagStr(input, "env");
+            if (envId)
+                form.set("environment_id", envId);
+            const job = (await ctx.client.request("POST", jobsPath(workspaceId, projectId), {
+                form,
+            }));
+            return {
+                data: job,
+                human: `Job ${job.id} queued. Check it with \`beryl jobs get ${job.id}\`.`,
+            };
+        },
+    },
+    {
+        name: "jobs list",
+        summary: "List the project's test-creation jobs",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return { data: await ctx.client.get(jobsPath(workspaceId, projectId)) };
+        },
+    },
+    {
+        name: "jobs get",
+        summary: "Show a job's status and the tests it created",
+        scope: "project",
+        args: [{ name: "job-id", description: "Job id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const job = (await ctx.client.get(`${jobsPath(workspaceId, projectId)}/${arg(input, "job-id")}`));
+            return { data: job, human: jobHuman(job) };
+        },
+    },
+    {
+        name: "jobs clone",
+        summary: "Run a job again: queue a new job with the same document and environment",
+        description: LLM_NOTICE,
+        scope: "project",
+        args: [{ name: "job-id", description: "Job id to clone", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const job = (await ctx.client.post(`${jobsPath(workspaceId, projectId)}/${arg(input, "job-id")}/clone`));
+            return { data: job, human: `Job ${job.id} queued.` };
+        },
+    },
+    {
+        name: "jobs delete",
+        summary: "Delete a job; the flows and tests it created stay",
+        scope: "project",
+        args: [{ name: "job-id", description: "Job 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 jobId = arg(input, "job-id");
+            await ctx.confirm(`Delete job ${jobId}? Its tests stay.`, flagBool(input, "force"));
+            await ctx.client.del(`${jobsPath(workspaceId, projectId)}/${jobId}`);
+            return { human: "Deleted." };
+        },
+    },
+];

package/dist/commands/projects.js

@@ -1,7 +1,7 @@
 import { detectAuthGating } from "../detect.js";
 import { UsageError } from "../errors.js";
 import { dim, green, table, timeAgo } from "../output.js";
-import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { arg, argList, flagBool, flagNum, flagStr, projectPath } from "./util.js";
 import { pollCurrentExploration, watchExploration } from "./watch.js";
 // The API treats the auth choice as the visitor's answer and never infers it — a null
 // choice leaves the project waiting on a login capture that never comes — so resolve it
@@ -84,7 +84,7 @@ export const projectCommands = [
                 name: "name",
                 type: "string",
                 description: "Name for an empty project when no URL is given. Add a URL later with " +
-                    "`beryl envs update <env-id>`, or author tests over the CLI/MCP",
+                    "`beryl envs update <env-id>`",
             },
             {
                 name: "auth",
@@ -97,9 +97,9 @@ export const projectCommands = [
             {
                 name: "explore",
                 type: "boolean",
-                description: "Also start a cloud exploration that authors tests for you. Off by default: author " +
-                    "tests with `beryl tests create` or your coding agent over MCP",
-                mcpDescription: "Leave unset: you author the tests yourself with `tests create`. Set only when the " +
+                description: "Also start a cloud exploration that authors tests for you. Off by default: create " +
+                    "tests from a document with `beryl jobs create`",
+                mcpDescription: "Leave unset: create tests from a document with `jobs create`. Set only when the " +
                     "user explicitly asks for a cloud exploration",
             },
             { name: "watch", type: "boolean", description: "Start the exploration (implies --explore) and stream it live" },
@@ -120,7 +120,7 @@ export const projectCommands = [
             const url = typeof rawUrl === "string" ? rawUrl : "";
             const name = flagStr(input, "name");
             // Name-only: create a real empty project (no URL, no exploration). Set a URL
-            // later with `beryl envs update <env-id>` or author over the CLI/MCP.
+            // later with `beryl envs update <env-id>`.
             if (!url) {
                 if (!name)
                     throw new UsageError("Provide a URL, or --name to create an empty project");
@@ -132,8 +132,8 @@ export const projectCommands = [
                 return {
                     data: created,
                     human: `${green("Project created")}: ${created.project_id} ${dim("(empty)")}\n` +
-                        `Add a site with \`beryl envs update <env-id>\`, or author tests with ` +
-                        `\`beryl tests create\`.`,
+                        `Add a site with \`beryl envs update <env-id>\`, then create tests with ` +
+                        `\`beryl jobs create <document>\`.`,
                 };
             }
             const auth = flagStr(input, "auth") ?? (await resolveAuthChoice(ctx, ws, url));
@@ -147,7 +147,7 @@ export const projectCommands = [
                 return {
                     data: created,
                     human: `${green("Project created")}: ${created.project_id}\n` +
-                        `Ready for your own tests: author a plan and push it with \`beryl tests create\`.`,
+                        `Create tests from a document describing the flows: \`beryl jobs create <file>\`.`,
                 };
             // The agent cannot start until a login is captured, so there is nothing to watch.
             if (created.auth_status === "needs_capture")
@@ -227,6 +227,55 @@ export const projectCommands = [
             return { data: await ctx.client.patch(projectPath(workspaceId, projectId), body) };
         },
     },
+    {
+        name: "projects surfaces",
+        summary: "Set which surfaces are enabled for this project",
+        description: "Replaces the project's enabled surfaces with the ones listed: web-desktop, " +
+            "web-tablet, web-mobile. A new project has web-desktop only. At least one is " +
+            "required; `projects get` shows the current set. Turning a surface off removes " +
+            "no tests: delete a surface's tests to stop running them.",
+        scope: "project",
+        args: [
+            {
+                name: "surfaces",
+                description: "web-desktop | web-tablet | web-mobile, one or more",
+                required: true,
+                variadic: true,
+            },
+        ],
+        examples: ["beryl projects surfaces web-desktop web-mobile", "beryl projects surfaces web-desktop"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const data = (await ctx.client.patch(projectPath(workspaceId, projectId), {
+                enabled_surfaces: argList(input, "surfaces"),
+            }));
+            return { data, human: `Enabled surfaces: ${data.enabled_surfaces.join(", ")}` };
+        },
+    },
+    {
+        name: "projects findings-gate",
+        summary: "Turn the findings gate on each run on or off",
+        description: "With the gate on (new-since-green), every run also reports a findings gate: failed " +
+            "when the environment's Site Health has a finding first seen after the last green run " +
+            "or came back after it (every current finding if there is no green run yet), unknown " +
+            "when Site Health has not run there or is not recording findings (its issue tracker " +
+            "must be connected). The gate sits next to the test verdicts and never changes one, nor the " +
+            "exit code of `runs watch`; read it from `findings_gate` on `runs get`. Off by default.",
+        scope: "project",
+        args: [{ name: "mode", description: "off | new-since-green", required: true }],
+        examples: ["beryl projects findings-gate new-since-green", "beryl projects findings-gate off"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const mode = arg(input, "mode").toLowerCase().replace(/-/g, "_");
+            if (mode !== "off" && mode !== "new_since_green") {
+                throw new UsageError(`Expected "off" or "new-since-green", got "${arg(input, "mode")}"`);
+            }
+            const data = (await ctx.client.patch(projectPath(workspaceId, projectId), {
+                findings_gate: mode,
+            }));
+            return { data, human: `Findings gate: ${data.findings_gate.replace(/_/g, "-")}` };
+        },
+    },
     {
         name: "projects delete",
         summary: "Delete a project and all its tests and runs",
@@ -258,7 +307,7 @@ export const projectCommands = [
     },
     {
         name: "projects report",
-        summary: "Aggregate quality report across recent runs (pass rates, flaky tests, trend)",
+        summary: "Aggregate quality report across recent runs (pass rates, per-test history, trend)",
         scope: "project",
         flags: [
             { name: "runs", type: "number", description: "How many recent runs to aggregate" },

package/dist/commands/runs.js

@@ -581,7 +581,8 @@ export const runCommands = [
             "carries `heal` when Beryl healed it: its steps were rewritten with the intent " +
             "unchanged, proved in a browser and it re-ran green; `version_no` is the revision it " +
             "wrote (see `tests diff`) and `rationale` the agent's reason. A heal that did not turn " +
-            "the test green is not reported: a failure is a failure. " +
+            "the test green is not reported: a failure is a failure. A red that Beryl did not try " +
+            "to heal carries `heal_skip_reason` saying why. " +
             "`runs report` returns the generated report document, `runs explain` an AI explanation " +
             "of one failed result.",
         scope: "project",
@@ -607,7 +608,7 @@ export const runCommands = [
                 name: "status",
                 type: "string",
                 description: "With --page, show only this bucket: passed, failed, errored, cancelled, " +
-                    "quarantined, or unstable (currently unstable in the run's environment)",
+                    "or quarantined",
             },
             {
                 name: "group",