@beryl-so/cli 0.7.1 → 0.8.0

package/dist/beryl-test-skill.js

@@ -19,6 +19,26 @@ export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {
         { action: "expect", expect_kind: "visible", selector: "text=Pro plan" },
     ],
 };
+// The OTP/signup example the skill shows verbatim (§5). Exported so the test suite lints
+// it with lintPlan, same as the minimal example — the documented await_email shape must
+// pass `beryl tests lint` on the first try.
+export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
+    steps: [
+        { action: "goto", url: "https://app.example.com/signup" },
+        { action: "fill", selector: "input[name=email]", value: "{{inbox_address}}" },
+        { action: "click", selector: "button[type=submit]" },
+        {
+            action: "await_email",
+            extract: "code",
+            subject_contains: "verification code",
+            capture_as: "otp",
+            wait_s: 45,
+        },
+        { action: "fill", selector: "input[name=code]", value: "{{otp}}" },
+        { action: "click", selector: "text=Verify" },
+        { action: "expect", expect_kind: "visible", selector: "text=Welcome" },
+    ],
+};
 export const BERYL_TEST_SKILL = `---
 name: beryl-test
 description: Author durable, healable end-to-end tests for a web app with Beryl. Use when writing, running, or fixing a Beryl test locally with your own coding agent — drafting the plan over the Playwright MCP, writing the natural-language intent, and running it with \`beryl runs local\`.
@@ -176,4 +196,52 @@ beryl runs local <test-id> --url-override http://localhost:3000 --dir ./beryl-lo
 
 Once the test passes locally against a real outcome, it's ready to bank and let Beryl run
 and heal it.
+
+## 5. Testing an OTP / signup flow (\`await_email\`)
+
+A flow that emails the user — a signup verification code, a magic sign-in link, a receipt
+— is testable with the \`await_email\` action. Beryl mints a **run-scoped inbox**
+automatically whenever a plan contains an \`await_email\` step (or cites
+\`{{inbox_address}}\`): no setup, no environment configuration, no flag to turn on. The
+minted address is in scope from step 1 as the reserved \`{{inbox_address}}\` handle.
+
+The wiring is a three-part chain:
+
+1. **Type the minted address into the app** — a \`fill\` with \`value: "{{inbox_address}}"\`.
+   Every run gets a fresh address, so a signup flow is repeatable by construction (no
+   \`{{unique}}\` needed for the email itself; use \`{{unique}}\` for other must-not-collide
+   values like a username).
+2. **Await the mail and bank the extracted value** — an \`await_email\` step with:
+   - \`extract\` (required): \`code\` (an OTP), \`link\` (the sign-in/verify URL), or
+     \`pattern\` (your own regex in \`extract_pattern\`, exactly one capture group).
+   - \`capture_as\` (required): the handle name the extracted string is banked under.
+   - \`subject_contains\` / \`from_contains\` (optional): match the right mail when the app
+     sends more than one.
+   - \`wait_s\` (optional, 1–50, default 30): how many seconds the step blocks waiting
+     for the mail to land.
+3. **Use the banked value** — cite \`{{<capture_as>}}\` in a later step's \`value\` (fill the
+   code) or \`url\` (goto the magic link). A captured handle is legal **only** in
+   \`value\`/\`url\`; in a \`selector\`, \`option\`, or \`expect_text\` it would be used as
+   literal text, and the linter rejects it there.
+
+A fully valid signup-with-OTP plan:
+
+\`\`\`json
+${JSON.stringify(BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN, null, 2)}
+\`\`\`
+
+For a magic-link flow, replace the code steps with
+\`{ "action": "await_email", "extract": "link", "capture_as": "signin_link" }\` followed by
+\`{ "action": "goto", "url": "{{signin_link}}" }\`.
+
+Two caveats:
+
+- \`beryl tests create\` verifies an \`await_email\` plan like any other — the replay mints
+  its own inbox, so the app's mail really is received and extracted before the test is
+  accepted. (Note the replay signs up / sends mail for real; pass \`--no-verify\` only if
+  that side effect is unwanted.) \`runs local\` cannot serve \`await_email\` — the inbox
+  lives in Beryl's cloud — so iterate on these flows with
+  \`beryl runs trigger --test <id> --watch\`.
+- The outcome assertion discipline from §1 still applies: the green signal is the
+  post-verification state (the welcome screen, the dashboard), not "an email arrived".
 `;

package/dist/commands/init.js

@@ -1,4 +1,6 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { BERYL_TEST_SKILL, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME, } from "../beryl-test-skill.js";
 import { LOCAL_CONFIG_FILENAME, loadConfig } from "../config.js";
@@ -16,9 +18,12 @@ 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
+// already wire their own user-scoped playwright.
 const PLAYWRIGHT_SERVER_ENTRY = {
     command: "npx",
-    args: ["@playwright/mcp@latest"],
+    args: ["@playwright/mcp@latest", "--headless"],
 };
 const ACTION_PLAN_SCHEMA_URL = "https://api.beryl.so/api/v1/schemas/action-plan.schema.json";
 // The authoring fork only appears when we create a fresh project with no tests yet; an
@@ -76,6 +81,36 @@ function mergeMcpConfig(file, withPlaywright) {
     }
     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",
+        });
+        return 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;
+    }
+}
+function claudeAddHint(name, entry) {
+    return `claude mcp add ${name} -s user -- ${entry.command} ${entry.args.join(" ")}`;
+}
+// ~/.cursor/mcp.json is Cursor's user-scope config — small and ours to write safely, unlike
+// ~/.claude.json — so we merge it directly rather than shelling out.
+function cursorUserConfigPath() {
+    return path.join(os.homedir(), ".cursor", "mcp.json");
+}
 function detectEditors(cwd) {
     const editors = [];
     if (fs.existsSync(path.join(cwd, ".claude")) || fs.existsSync(path.join(cwd, "CLAUDE.md")))
@@ -108,9 +143,11 @@ 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), and writes the " +
-            "MCP server config for your coding agent (.mcp.json for Claude Code, .cursor/mcp.json for " +
-            "Cursor). When creating a fresh project it asks how you want to author tests — locally with " +
+            "workspace and project via .beryl.json (offering to create the project), and wires the " +
+            "MCP servers for your coding agent. By default they're wired per-user (matching where your " +
+            "login token lives) — via `claude mcp add -s user` for Claude Code, ~/.cursor/mcp.json for " +
+            "Cursor; pass --scope project to write a committed .mcp.json for a shared repo instead. " +
+            "When creating a fresh project it asks how you want to author tests — locally with " +
             "your own coding agent or by hand (the default), or by letting Beryl's agent explore and " +
             "author them for you. Safe to re-run; every step skips what is already set up.",
         interactive: true,
@@ -138,6 +175,15 @@ export const initCommands = [
                 description: "Which coding agent to write MCP config for (default: auto-detect)",
             },
             { name: "no-pin", type: "boolean", description: "Skip writing .beryl.json" },
+            {
+                name: "scope",
+                type: "string",
+                enum: ["user", "project"],
+                description: "Where to wire the MCP servers. `user` (default) configures them per-user (matching " +
+                    "where your Beryl login token lives) via `claude mcp add -s user` / ~/.cursor/mcp.json. " +
+                    "`project` writes a committed .mcp.json for a shared repo — every teammate still runs " +
+                    "`beryl login` to authenticate",
+            },
             {
                 name: "local",
                 type: "boolean",
@@ -149,6 +195,7 @@ export const initCommands = [
         examples: [
             "npx @beryl-so/cli@latest init",
             "beryl init --editor-tools claude-code",
+            "beryl init --scope project",
             "beryl init --project https://app.example.com --authoring agent",
             "beryl init --project https://app.example.com --authoring local --editor-tools none",
         ],
@@ -232,14 +279,35 @@ export const initCommands = [
             // and local authoring needs the Playwright MCP — so default it on. `--no-local` (parsed
             // as an explicit false) opts out.
             const local = input.flags.local ?? editors.length > 0;
+            const scope = (flagStr(input, "scope") ?? "user");
             for (const editor of editors) {
+                if (scope === "user" && editor === "claude-code") {
+                    // Claude Code owns ~/.claude.json — shell out to `claude mcp add` rather than write it.
+                    const berylOk = claudeUserAdd("beryl", MCP_SERVER_ENTRY);
+                    const playwrightOk = local ? claudeUserAdd("playwright", PLAYWRIGHT_SERVER_ENTRY) : undefined;
+                    if (berylOk) {
+                        ctx.err(`${green("✓")} claude-code MCP configured ${dim("(user scope)")}`);
+                        if (playwrightOk)
+                            ctx.err(`${green("✓")} claude-code Playwright MCP configured ${dim("(user scope)")}`);
+                    }
+                    else {
+                        ctx.err(yellow("• `claude` not on PATH — run these to wire user-scope MCP servers:"));
+                        ctx.err(`    ${cyan(claudeAddHint("beryl", MCP_SERVER_ENTRY))}`);
+                        if (local)
+                            ctx.err(`    ${cyan(claudeAddHint("playwright", PLAYWRIGHT_SERVER_ENTRY))}`);
+                    }
+                    continue;
+                }
                 const file = editor === "claude-code"
                     ? path.join(cwd, ".mcp.json")
-                    : path.join(cwd, ".cursor", "mcp.json");
+                    : scope === "user"
+                        ? cursorUserConfigPath()
+                        : 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))}`);
+                const where = scope === "user" ? file : path.relative(cwd, file);
+                ctx.err(`${green("✓")} ${editor} MCP ${wrote.beryl ? "configured" : "already configured"} ${dim(where)}`);
                 if (wrote.playwright !== undefined)
-                    ctx.err(`${green("✓")} ${editor} Playwright MCP ${wrote.playwright ? "configured" : "already configured"} ${dim(path.relative(cwd, file))}`);
+                    ctx.err(`${green("✓")} ${editor} Playwright MCP ${wrote.playwright ? "configured" : "already configured"} ${dim(where)}`);
             }
             if (choice === "auto" && editors.length === 0)
                 ctx.err(dim("No coding agent detected — pass --editor-tools claude-code|cursor to wire one."));

package/package.json

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