@beryl-so/cli 0.1.0

package/dist/commands/explorations.js

@@ -0,0 +1,50 @@
+import { arg, flagNum, projectPath } from "./util.js";
+import { watchExploration } from "./watch.js";
+export const explorationCommands = [
+    {
+        name: "explorations list",
+        summary: "List the agent's exploration passes for a project",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return { data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/explorations`) };
+        },
+    },
+    {
+        name: "explorations get",
+        summary: "Show one exploration: authored tests, abandoned flows, coverage, frontier",
+        scope: "project",
+        args: [{ name: "exploration-id", description: "Exploration id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/explorations/${arg(input, "exploration-id")}`),
+            };
+        },
+    },
+    {
+        name: "explorations steps",
+        summary: "List every step the agent took in an exploration",
+        scope: "project",
+        args: [{ name: "exploration-id", description: "Exploration id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/explorations/${arg(input, "exploration-id")}/steps`),
+            };
+        },
+    },
+    {
+        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.",
+        scope: "project",
+        args: [{ name: "exploration-id", description: "Exploration id", required: true }],
+        flags: [{ name: "timeout", type: "number", description: "Max minutes to wait" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return await watchExploration(ctx, workspaceId, projectId, arg(input, "exploration-id"), flagNum(input, "timeout"));
+        },
+    },
+];

package/dist/commands/init.js

@@ -0,0 +1,189 @@
+import fs from "node:fs";
+import path from "node:path";
+import { LOCAL_CONFIG_FILENAME, loadConfig } from "../config.js";
+import { CliError, UsageError } from "../errors.js";
+import { ApiClient } from "../http.js";
+import { bold, cyan, dim, green } from "../output.js";
+import { authCommands } from "./auth.js";
+import { flagBool, flagStr } from "./util.js";
+const MCP_SERVER_ENTRY = {
+    command: "npx",
+    args: ["-y", "@beryl-so/cli", "mcp"],
+};
+const PLAYWRIGHT_SERVER_ENTRY = {
+    command: "npx",
+    args: ["@playwright/mcp@latest"],
+};
+async function pick(ctx, kind, items) {
+    if (items.length === 1)
+        return items[0];
+    ctx.err(`\n${bold(`Which ${kind}?`)}`);
+    items.forEach((item, i) => ctx.err(`  ${i + 1}. ${item.name ?? item.root_url ?? item.id} ${dim(item.id)}`));
+    const answer = await ctx.prompt(`${kind} [1-${items.length}]: `);
+    const index = Number(answer) - 1;
+    const chosen = items[index];
+    if (!chosen)
+        throw new UsageError(`"${answer}" is not between 1 and ${items.length}`);
+    return chosen;
+}
+function mergeMcpConfig(file, withPlaywright) {
+    let existing = {};
+    if (fs.existsSync(file)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            throw new CliError(`${file} exists but is not valid JSON (${err.message})`);
+        }
+    }
+    const servers = (existing.mcpServers ?? {});
+    const beryl = JSON.stringify(servers.beryl) !== JSON.stringify(MCP_SERVER_ENTRY);
+    if (beryl)
+        servers.beryl = MCP_SERVER_ENTRY;
+    let playwright;
+    if (withPlaywright) {
+        // Never clobber a playwright server the user already wired up.
+        playwright = servers.playwright === undefined;
+        if (playwright)
+            servers.playwright = PLAYWRIGHT_SERVER_ENTRY;
+    }
+    if (beryl || playwright) {
+        existing.mcpServers = servers;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(existing, null, 2) + "\n");
+    }
+    return { beryl, playwright };
+}
+function detectEditors(cwd) {
+    const editors = [];
+    if (fs.existsSync(path.join(cwd, ".claude")) || fs.existsSync(path.join(cwd, "CLAUDE.md")))
+        editors.push("claude-code");
+    if (fs.existsSync(path.join(cwd, ".cursor")))
+        editors.push("cursor");
+    return editors;
+}
+export const initCommands = [
+    {
+        name: "init",
+        summary: "Set up Beryl in this repo — sign in, pin a project, wire up your coding agent",
+        description: "One-command onboarding: signs you in (emailed one-time code), pins this repo to a " +
+            "workspace and project via .beryl.json (offering to create the project — the agent " +
+            "starts exploring and authoring tests immediately), and writes the MCP server config " +
+            "for your coding agent (.mcp.json for Claude Code, .cursor/mcp.json for Cursor). " +
+            "Safe to re-run; every step skips what is already set up.",
+        interactive: true,
+        flags: [
+            { name: "workspace", type: "string", description: "Workspace id or name to pin" },
+            { name: "project", type: "string", description: "Project id, name, or URL to pin" },
+            {
+                name: "editor-tools",
+                type: "string",
+                enum: ["claude-code", "cursor", "both", "none"],
+                description: "Which coding agent to write MCP config for (default: auto-detect)",
+            },
+            { name: "no-pin", type: "boolean", description: "Skip writing .beryl.json" },
+            {
+                name: "local",
+                type: "boolean",
+                description: "Also wire the Playwright MCP so your coding agent can drive a local browser " +
+                    "(for authoring tests yourself)",
+            },
+        ],
+        examples: [
+            "npx @beryl-so/cli@latest init",
+            "beryl init --editor-tools claude-code",
+            "beryl init --project https://app.example.com --editor-tools none",
+        ],
+        async run(ctx, input) {
+            const cwd = process.cwd();
+            let { client, config } = ctx;
+            if (config.token) {
+                const me = (await client.get("/account/"));
+                ctx.err(`${green("✓")} Signed in as ${me.email}`);
+            }
+            else {
+                const login = authCommands.find((c) => c.name === "login");
+                await login.run(ctx, { args: {}, flags: {} });
+                config = loadConfig();
+                if (!config.token)
+                    throw new CliError("Login did not persist a token");
+                client = new ApiClient(config.apiUrl, config.token);
+            }
+            let workspaceId;
+            let projectId;
+            if (!flagBool(input, "no-pin")) {
+                const workspaces = (await client.get("/workspaces/"));
+                if (workspaces.length === 0)
+                    throw new CliError("You have no workspaces yet — create one with `beryl workspaces create`");
+                const wanted = flagStr(input, "workspace");
+                const workspace = wanted
+                    ? workspaces.find((w) => w.id === wanted || w.name?.toLowerCase() === wanted.toLowerCase())
+                    : await pick(ctx, "workspace", workspaces);
+                if (!workspace)
+                    throw new CliError(`No workspace named "${wanted}" found`);
+                workspaceId = workspace.id;
+                const projects = (await client.get(`/workspaces/${workspaceId}/projects`));
+                const wantedProject = flagStr(input, "project");
+                if (wantedProject) {
+                    projectId = (await ctx.requireProject({
+                        args: {},
+                        flags: { workspace: workspaceId, project: wantedProject },
+                    })).projectId;
+                }
+                else if (projects.length > 0) {
+                    projectId = (await pick(ctx, "project", projects)).id;
+                }
+                else {
+                    const url = await ctx.prompt("No projects yet. Root URL of the site to test: ");
+                    const created = (await client.post(`/workspaces/${workspaceId}/projects`, {
+                        root_url: url,
+                    }));
+                    projectId = created.project_id;
+                    ctx.err(`${green("✓")} Project created — the agent is exploring ${url} and authoring tests ` +
+                        `(watch with \`beryl explorations watch\`)`);
+                }
+                const localFile = path.join(cwd, LOCAL_CONFIG_FILENAME);
+                let local = {};
+                try {
+                    local = JSON.parse(fs.readFileSync(localFile, "utf8"));
+                }
+                catch {
+                    // no local config yet
+                }
+                fs.writeFileSync(localFile, JSON.stringify({ ...local, workspace: workspaceId, project: projectId }, null, 2) + "\n");
+                ctx.err(`${green("✓")} Pinned to ${LOCAL_CONFIG_FILENAME} ${dim(`(${projectId})`)}`);
+            }
+            const choice = flagStr(input, "editor-tools") ?? "auto";
+            const editors = choice === "auto"
+                ? detectEditors(cwd)
+                : choice === "both"
+                    ? ["claude-code", "cursor"]
+                    : choice === "none"
+                        ? []
+                        : [choice];
+            const local = flagBool(input, "local");
+            for (const editor of editors) {
+                const file = editor === "claude-code"
+                    ? path.join(cwd, ".mcp.json")
+                    : path.join(cwd, ".cursor", "mcp.json");
+                const wrote = mergeMcpConfig(file, local);
+                ctx.err(`${green("✓")} ${editor} MCP ${wrote.beryl ? "configured" : "already configured"} ${dim(path.relative(cwd, file))}`);
+                if (wrote.playwright !== undefined)
+                    ctx.err(`${green("✓")} ${editor} Playwright MCP ${wrote.playwright ? "configured" : "already configured"} ${dim(path.relative(cwd, file))}`);
+            }
+            if (choice === "auto" && editors.length === 0)
+                ctx.err(dim("No coding agent detected — pass --editor-tools claude-code|cursor to wire one."));
+            return {
+                data: { workspace: workspaceId ?? null, project: projectId ?? null, editors },
+                human: `\n${bold("Beryl is set up.")} Try:\n` +
+                    `  ${cyan("beryl runs trigger --watch")}     run the suite\n` +
+                    `  ${cyan("beryl explorations watch")}       watch the agent work\n` +
+                    `  ${cyan("beryl tests list")}               see authored tests` +
+                    (local
+                        ? `\n\nPlaywright MCP is wired — your coding agent can explore the site locally ` +
+                            `and push tests with ${cyan("beryl tests create")}.`
+                        : ""),
+            };
+        },
+    },
+];

package/dist/commands/mcp.js

@@ -0,0 +1,15 @@
+export const mcpCommands = [
+    {
+        name: "mcp",
+        summary: "Run the Beryl MCP server (stdio) — every CLI command as an agent tool",
+        description: "Exposes the CLI's commands as MCP tools over stdio, so coding agents (Claude Code, " +
+            "Cursor, …) can create projects, trigger runs, watch the agent, and edit tests. " +
+            "Authenticate via BERYL_API_KEY or a prior `beryl login`.",
+        examples: ["claude mcp add beryl -- beryl mcp"],
+        async run(ctx) {
+            const { serveMcp } = await import("../adapters/mcp.js");
+            await serveMcp(ctx);
+            return {};
+        },
+    },
+];

package/dist/commands/projects.js

@@ -0,0 +1,177 @@
+import { saveGlobalConfig } from "../config.js";
+import { UsageError } from "../errors.js";
+import { dim, green } from "../output.js";
+import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { pollCurrentExploration, watchExploration } from "./watch.js";
+export const projectCommands = [
+    {
+        name: "projects list",
+        summary: "List projects in the workspace",
+        scope: "workspace",
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            return { data: await ctx.client.get(`/workspaces/${ws}/projects`) };
+        },
+    },
+    {
+        name: "projects get",
+        summary: "Show one project, including its current exploration state",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return { data: await ctx.client.get(projectPath(workspaceId, projectId)) };
+        },
+    },
+    {
+        name: "projects create",
+        summary: "Create a project — the agent starts exploring and authoring tests immediately",
+        scope: "workspace",
+        args: [{ name: "url", description: "Root URL of the site to test", required: true }],
+        flags: [
+            {
+                name: "auth",
+                type: "string",
+                enum: ["public", "gated"],
+                description: "Whether the site needs a login (gated) or not (public)",
+            },
+            {
+                name: "allow-mutations",
+                type: "boolean",
+                description: "Let the agent perform state-changing actions while exploring",
+            },
+            { name: "force-new-login", type: "boolean", description: "Ignore any reusable saved login" },
+            {
+                name: "no-explore",
+                type: "boolean",
+                description: "Create the project without starting the cloud exploration — author tests yourself " +
+                    "via `beryl tests create` or your coding agent over MCP",
+            },
+            { name: "watch", type: "boolean", description: "Stream the agent's exploration live" },
+            { name: "timeout", type: "number", description: "With --watch: max minutes to wait" },
+        ],
+        examples: [
+            "beryl projects create https://app.example.com --auth public --watch",
+            "beryl projects create https://app.example.com --auth gated",
+            "beryl projects create https://app.example.com --auth public --no-explore",
+        ],
+        async run(ctx, input) {
+            const noExplore = flagBool(input, "no-explore");
+            if (noExplore && flagBool(input, "watch"))
+                throw new UsageError("--no-explore cannot be combined with --watch");
+            const ws = await ctx.requireWorkspace(input);
+            const auth = flagStr(input, "auth");
+            const created = (await ctx.client.post(`/workspaces/${ws}/projects`, {
+                root_url: arg(input, "url"),
+                requires_auth_choice: auth ?? null,
+                mutation_choice: flagBool(input, "allow-mutations") ? "allow_mutations" : null,
+                force_new_login: flagBool(input, "force-new-login"),
+                skip_exploration: noExplore,
+            }));
+            if (noExplore)
+                return {
+                    data: created,
+                    human: `${green("Project created")}: ${created.project_id} ${dim("(no exploration started)")}\n` +
+                        `Ready for your own tests — author a plan and push it with \`beryl tests create\`.`,
+                };
+            if (!flagBool(input, "watch"))
+                return { data: created };
+            ctx.err(dim(`project ${created.project_id} created — waiting for the agent to start…`));
+            const explorationId = await pollCurrentExploration(ctx, ws, created.project_id);
+            const watched = await watchExploration(ctx, ws, created.project_id, explorationId, flagNum(input, "timeout"));
+            return { data: { ...created, ...watched.data }, exitCode: watched.exitCode };
+        },
+    },
+    {
+        name: "projects rename",
+        summary: "Rename a project",
+        scope: "project",
+        args: [{ name: "name", description: "New name", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.patch(projectPath(workspaceId, projectId), {
+                    name: arg(input, "name"),
+                }),
+            };
+        },
+    },
+    {
+        name: "projects delete",
+        summary: "Delete a project and all its tests and runs",
+        scope: "project",
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            await ctx.confirm(`Delete project ${projectId} and all its data?`, flagBool(input, "force"));
+            await ctx.client.del(projectPath(workspaceId, projectId));
+            return { human: "Deleted." };
+        },
+    },
+    {
+        name: "projects re-explore",
+        summary: "Send the agent back in — run/heal existing tests and discover new flows",
+        scope: "project",
+        flags: [
+            { name: "watch", type: "boolean", description: "Stream the agent's exploration live" },
+            { name: "timeout", type: "number", description: "With --watch: max minutes to wait" },
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            await ctx.client.post(`${projectPath(workspaceId, projectId)}/re-explore`);
+            if (!flagBool(input, "watch"))
+                return { human: "Exploration queued." };
+            const explorationId = await pollCurrentExploration(ctx, workspaceId, projectId);
+            return await watchExploration(ctx, workspaceId, projectId, explorationId, flagNum(input, "timeout"));
+        },
+    },
+    {
+        name: "projects report",
+        summary: "Aggregate quality report across recent runs (pass rates, flaky tests, trend)",
+        scope: "project",
+        flags: [
+            { name: "runs", type: "number", description: "How many recent runs to aggregate" },
+            { name: "env", type: "string", description: "Limit to one environment id" },
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/report`, {
+                    run_limit: flagNum(input, "runs"),
+                    environment_id: flagStr(input, "env"),
+                }),
+            };
+        },
+    },
+    {
+        name: "projects reusable-auth",
+        summary: "Check whether a saved login can be reused for a URL before creating a project",
+        scope: "workspace",
+        args: [{ name: "url", description: "The URL you plan to test", required: true }],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            return {
+                data: await ctx.client.get(`/workspaces/${ws}/projects/reusable-auth`, {
+                    url: arg(input, "url"),
+                }),
+            };
+        },
+    },
+    {
+        name: "projects use",
+        summary: "Set the default project for future commands",
+        scope: "workspace",
+        args: [{ name: "project", description: "Project id, name, or URL", required: true }],
+        async run(ctx, input) {
+            const value = arg(input, "project");
+            const { workspaceId, projectId } = await ctx.requireProject({
+                args: {},
+                flags: { ...input.flags, project: value },
+            });
+            saveGlobalConfig({ workspace: workspaceId, project: projectId });
+            return {
+                data: { workspace: workspaceId, project: projectId },
+                human: `${green("Default project set")}: ${projectId} ${dim(`(workspace ${workspaceId})`)}`,
+            };
+        },
+    },
+];

package/dist/commands/runs.js

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { watchRun } from "./watch.js";
+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 " +
+            "exits 0 only if every test passed — wire it straight into CI.",
+        scope: "project",
+        flags: [
+            { name: "test", type: "strings", description: "Run only these test ids (repeatable)" },
+            { name: "env", type: "string", description: "Environment id to run against" },
+            { name: "url-override", type: "string", description: "Replace the base URL (preview deploys)" },
+            { name: "watch", type: "boolean", description: "Stream progress and exit non-zero on failure" },
+            { name: "timeout", type: "number", description: "With --watch: max minutes to wait" },
+        ],
+        examples: [
+            "beryl runs trigger --watch",
+            "beryl runs trigger --url-override https://preview-123.example.com --watch --timeout 30",
+            "beryl runs trigger --test 4f… --test 9a…",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const tests = input.flags.test;
+            const created = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/runs`, {
+                test_case_ids: tests && tests.length > 0 ? tests : null,
+                environment_id: flagStr(input, "env") ?? null,
+                target_url_override: flagStr(input, "url-override") ?? null,
+            }));
+            if (!flagBool(input, "watch"))
+                return { data: created };
+            return await watchRun(ctx, workspaceId, projectId, created.id, flagNum(input, "timeout"));
+        },
+    },
+    {
+        name: "runs list",
+        summary: "List recent runs",
+        scope: "project",
+        flags: [{ name: "env", type: "string", description: "Filter by environment id" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const rows = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs`, {
+                environment_id: flagStr(input, "env"),
+            }));
+            return { data: rows.map(({ test_results: _omit, ...row }) => row) };
+        },
+    },
+    {
+        name: "runs get",
+        summary: "Show one run with its per-test results",
+        scope: "project",
+        args: [{ name: "run-id", description: "Run id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}`),
+            };
+        },
+    },
+    {
+        name: "runs watch",
+        summary: "Attach to a run and stream progress 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" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return await watchRun(ctx, workspaceId, projectId, arg(input, "run-id"), flagNum(input, "timeout"));
+        },
+    },
+    {
+        name: "runs cancel",
+        summary: "Cancel an in-flight run",
+        scope: "project",
+        args: [{ name: "run-id", description: "Run id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}/cancel`),
+            };
+        },
+    },
+    {
+        name: "runs report",
+        summary: "Show the generated report for a run",
+        scope: "project",
+        args: [{ name: "run-id", description: "Run id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}/report`),
+            };
+        },
+    },
+    {
+        name: "runs download",
+        summary: "Download a run's full results as JSON",
+        scope: "project",
+        args: [{ name: "run-id", description: "Run id", required: true }],
+        flags: [{ name: "out", type: "string", description: "Write to a file instead of stdout" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const data = await ctx.client.get(`${projectPath(workspaceId, projectId)}/runs/${arg(input, "run-id")}/download`);
+            const out = flagStr(input, "out");
+            if (out) {
+                fs.writeFileSync(out, JSON.stringify(data, null, 2) + "\n");
+                return { data: { written: out }, human: `Wrote ${out}` };
+            }
+            return { data, human: JSON.stringify(data, null, 2) };
+        },
+    },
+    {
+        name: "runs explain",
+        summary: "AI explanation of why a test result failed",
+        scope: "project",
+        args: [{ name: "result-id", description: "Test result id (from `beryl runs get`)", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${projectPath(workspaceId, projectId)}/results/${arg(input, "result-id")}/explain`),
+            };
+        },
+    },
+];