@beryl-so/cli 0.33.0 → 0.34.2

package/README.md

@@ -216,8 +216,9 @@ Author, inspect, version, and heal a project's tests: the checks Beryl runs on e
 | `beryl tests set-plan <test-id>` | Replace a test's step plan from a JSON file (creates a new version) | `tests_set_plan` |
 | `beryl tests rename <test-id> <title>` | Rename a test | `tests_rename` |
 | `beryl tests set-groups <test-id>` | Replace the groups a test belongs to | `tests_set_groups` |
+| `beryl tests add-groups <test-ids...>` | Add groups to one or more tests, keeping the groups they already have | `tests_add_groups` |
 | `beryl tests quarantine <test-id> <state>` | Mute a flaky test: it keeps running, but its failures stop failing the run | `tests_quarantine` |
-| `beryl tests delete <test-id>` | Delete a test, its version history, and its results | `tests_delete` |
+| `beryl tests delete <test-ids...>` | Delete tests, their version history, and their results | `tests_delete` |
 | `beryl tests recompile <test-id>` | Validate + verify an edited plan against the live site before persisting | `tests_recompile` |
 | `beryl tests versions <test-id>` | List a test's version history | `tests_versions` |
 | `beryl tests version <test-id> <version-no>` | Show one specific version of a test (including its plan) | `tests_version` |
@@ -251,7 +252,7 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) | `runs_trigger` |
-| `beryl runs local [test-ids...]` | Run tests on your machine with your own Playwright; results sync to Beryl | `runs_local` |
+| `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` |

package/dist/beryl-test-skill.js

@@ -73,7 +73,7 @@ exception are in \`tests create\`'s own description.
 Before the first plan:
 
 \`\`\`
-npm i -D @playwright/test && npx playwright install chromium   # once, per project
+npx @beryl-so/cli@latest init                         # once per machine: installs the Chromium browser (the runner ships with the CLI)
 beryl envs list                                       # the root URL gotos resolve against (§2)
 beryl envs update <id> --url https://app.example.com  # set it if root_url is empty — required
 beryl accounts list                                   # who do authenticated tests sign in as? (§1)
@@ -370,7 +370,7 @@ Weak (describes steps + asserts nothing meaningful):
 ## 4. The local run-fix loop
 
 Iterate on your machine before you rely on the cloud. \`beryl runs local\` runs banked
-tests with your local \`@playwright/test\` — no cloud, no waiting for a scheduled run.
+tests with the Playwright runner bundled in the CLI — no cloud, no waiting for a scheduled run.
 
 \`\`\`
 beryl runs local <test-id> --no-sync --url-override http://localhost:3000 --dir ./beryl-local

package/dist/commands/auth.js

@@ -175,7 +175,7 @@ export const authCommands = [
             const human = `${green("Logged in")} as ${me.name} <${me.email}>` +
                 `\n${dim(`Token saved to ${saved}`)}`;
             return {
-                data: { email: me.email, name: me.name, config: saved },
+                data: { id: me.id, email: me.email, name: me.name, config: saved },
                 human,
             };
         },

package/dist/commands/init.js

@@ -8,6 +8,7 @@ import { AuthError, CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { bold, cyan, dim, green, red, yellow } from "../output.js";
 import { anyGap, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
+import { aliasSessionToAccount, captureCliEvent, flushTelemetry, shutdownTelemetry, } from "../telemetry.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 import { authCommands } from "./auth.js";
 import { flagStr } from "./util.js";
@@ -117,16 +118,16 @@ function writeSkills(cwd, scope) {
         writeSkillFile(skillLeaf(path.join(root, ".claude", "skills"))),
     ];
 }
-// Local authoring drives a real browser via `@playwright/test` + chromium, and the whole
-// authoring workflow (walk the flow first, then bank the plan) depends on it — so the
-// install is mandatory, not offered: missing means install now, no prompt, no opt-out.
-// Both halves count: the npm package without the browser binary is a real state, and it
-// fails every local run with the same launch error. Never throws — a failed install must not
-// fail `init`, which has already done its wiring; it prints the exact commands instead.
+// 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:
+// 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
+// exact commands instead.
 async function ensureLocalPlaywright(ctx, cwd) {
     const gaps = playwrightGaps(cwd);
     if (!anyGap(gaps)) {
-        ctx.err(`${green("✓")} @playwright/test + Chromium already installed ${dim("(local runs ready)")}`);
+        ctx.err(`${green("✓")} Playwright + Chromium already installed ${dim("(local runs ready)")}`);
         return;
     }
     try {
@@ -141,7 +142,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` +
-            `    ${cyan(installCommandsFor(gaps))}`);
+            `    ${cyan(installCommandsFor(gaps, cwd))}`);
     }
 }
 export const initCommands = [
@@ -153,8 +154,9 @@ export const initCommands = [
             "agent. Nothing is detected and nothing is conditional: every run wires the beryl AND " +
             "playwright MCP servers, writes the authoring skill (user scope: your home " +
             ".agents/skills/ + .claude/skills/, so it follows you into every session; --scope " +
-            "project: the repo's own dirs, committed for teammates), and installs @playwright/test " +
-            "+ chromium if missing, since browser authoring and local runs depend on it. By default the " +
+            "project: the repo's own dirs, committed for teammates), and installs the Chromium " +
+            "browser if missing (the Playwright runner ships with the CLI, so any repo can run tests " +
+            "locally), since browser authoring and local runs depend on it. By default the " +
             "servers are wired per-user (matching where your login token lives) via `claude mcp add " +
             "-s user`; pass --scope project to write a committed .mcp.json for a shared repo " +
             "instead. No workspace/project pin and no URL prompt: ask Claude to write tests for " +
@@ -187,6 +189,10 @@ export const initCommands = [
         async run(ctx, input) {
             const cwd = process.cwd();
             let { client, config } = ctx;
+            const scope = (flagStr(input, "scope") ?? "user");
+            captureCliEvent("cli_init_started", config.apiUrl, { scope });
+            flushTelemetry();
+            let accountId;
             const signIn = async () => {
                 // Non-interactive skips the picker and lets `login` fail with its own
                 // "interactive input required" message, exactly as before.
@@ -194,7 +200,11 @@ export const initCommands = [
                     ? await ctx.prompt("Sign in: [1] Browser (opens beryl.so)  [2] Email me a code — [1]: ")
                     : "";
                 const login = authCommands.find((c) => c.name === "login");
-                await login.run(ctx, { args: {}, flags: answer.trim() === "2" ? { otp: true } : {} });
+                const result = await login.run(ctx, {
+                    args: {},
+                    flags: answer.trim() === "2" ? { otp: true } : {},
+                });
+                accountId = (result ?? {}).data?.id;
                 config = loadConfig();
                 if (!config.token)
                     throw new CliError("Login did not persist a token");
@@ -203,6 +213,7 @@ export const initCommands = [
             if (config.token) {
                 try {
                     const me = (await client.get("/account/"));
+                    accountId = me.id;
                     ctx.err(`${green("✓")} Signed in as ${me.email}`);
                 }
                 catch (err) {
@@ -215,7 +226,10 @@ export const initCommands = [
             else {
                 await signIn();
             }
-            const scope = (flagStr(input, "scope") ?? "user");
+            if (accountId) {
+                aliasSessionToAccount(accountId);
+                flushTelemetry();
+            }
             const report = (label, fresh, where) => ctx.err(`${green("✓")} ${label} ${fresh ? "configured" : "already configured"} ${dim(where)}`);
             if (scope === "user") {
                 // Claude Code owns ~/.claude.json — shell out to `claude mcp add` rather than write it.
@@ -267,6 +281,7 @@ export const initCommands = [
             // 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)));
+            await shutdownTelemetry();
             return {
                 data: {
                     scope,

package/dist/commands/runs.js

@@ -5,7 +5,7 @@ import { CliError, UsageError } from "../errors.js";
 import { buildImportForm, establishAccountSession, executeLocalSpec, IMPORT_MAX_ERROR_LEN, toRunEntry, } from "../local-exec.js";
 import { countPlannedFrames, countWrittenFrames, PlaywrightMissingError, } from "../local-run.js";
 import { dim, green, red, yellow } from "../output.js";
-import { anyGap, confirmInstall, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
+import { anyGap, confirmInstall, describeGaps, installCommandsFor, installHint, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { ProgressBar } from "../progress.js";
 import { arg, flagBool, flagNum, flagStr, idsInGroup, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
@@ -17,8 +17,8 @@ async function ensureRunnableLocally(ctx) {
     const gaps = playwrightGaps(process.cwd());
     if (!anyGap(gaps))
         return;
-    const commands = installCommandsFor(gaps);
-    const hint = `Local runs need ${describeGaps(gaps)}. Install it, then re-run:\n  ${commands}`;
+    const commands = installCommandsFor(gaps, process.cwd());
+    const hint = installHint(process.cwd(), gaps);
     if (!ctx.interactive || !(await confirmInstall(ctx.prompt, commands)))
         throw new CliError(hint);
     try {
@@ -115,12 +115,13 @@ export const runCommands = [
     },
     {
         name: "runs local",
-        summary: "Run tests on your machine with your own Playwright; results sync to Beryl",
+        summary: "Run tests on your machine with Playwright; results sync to Beryl",
         description: "Unlike `runs trigger`, the browser runs on YOUR machine: each test's rendered spec is " +
-            "fetched and run with your local @playwright/test and the Chromium binary it drives. " +
+            "fetched and run with the Playwright runner bundled in the CLI (your repo's own " +
+            "@playwright/test wins when present) and the Chromium binary it drives. " +
             "Both are checked once before any spec is fetched, so a machine that can't run tests " +
             "says so once instead of failing every test (on a terminal the CLI offers to install " +
-            "whichever half is missing; over MCP it prints the exact install commands). " +
+            "the missing browser; over MCP it prints the exact install command). " +
             "Signup/OTP flows work: the CLI answers the spec's await_email steps over the API " +
             "against the same mailbox the cloud runner uses. Authenticated tests work too: for a plan " +
             "that signs itself in with {{login_email}}/{{login_password}}, the email is baked into " +
@@ -412,7 +413,9 @@ export const runCommands = [
                         if (err instanceof PlaywrightMissingError && ctx.interactive && !installOffered) {
                             installOffered = true;
                             bar.clear();
-                            if (!(await confirmInstall(ctx.prompt)))
+                            const cwd = process.cwd();
+                            const commands = installCommandsFor(playwrightGaps(cwd), cwd);
+                            if (!(await confirmInstall(ctx.prompt, commands)))
                                 throw err;
                             try {
                                 await installPlaywright(process.cwd(), (line) => ctx.err(dim(line)));

package/dist/commands/tests.js

@@ -5,7 +5,7 @@ import { lintPlan } from "../lint.js";
 import { buildImportForm, establishAccountSession, executeLocalSpec, toRunEntry, } from "../local-exec.js";
 import { PlaywrightMissingError } from "../local-run.js";
 import { dim, green, red, table, yellow } from "../output.js";
-import { confirmInstall, installPlaywright } from "../playwright-install.js";
+import { confirmInstall, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
 import { arg, argList, flagBool, flagNum, flagStr, flagStrings, inGroup, projectPath, readJsonFlag, } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
@@ -139,6 +139,11 @@ export const testCommands = [
                 type: "boolean",
                 description: "With --page, show only tests carrying no group",
             },
+            {
+                name: "q",
+                type: "string",
+                description: "With --page, show only tests whose title contains this text (case-insensitive)",
+            },
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -159,6 +164,7 @@ export const testCommands = [
                     page_size: flagNum(input, "page-size"),
                     status: flagStr(input, "status"),
                     group: flagBool(input, "ungrouped") ? "__ungrouped__" : group,
+                    q: flagStr(input, "q"),
                     environment_id: flagStr(input, "env"),
                 })).items;
             }
@@ -201,13 +207,14 @@ export const testCommands = [
         summary: "Create a test case from a JSON action plan (for tests authored locally, e.g. by your coding agent)",
         description: "The plan is a JSON object whose steps are {action, selector, url, value, ...}: the first " +
             "EXECUTED step must be a goto, and at least one step must be an expect. Before anything is " +
-            "banked, the plan is proven by replaying it in a browser ON YOUR MACHINE with your local " +
-            "@playwright/test: the server renders the spec (`tests/compile`), the CLI runs it (minting " +
+            "banked, the plan is proven by replaying it in a browser ON YOUR MACHINE with the " +
+            "Playwright runner bundled in the CLI (your repo's own @playwright/test wins when " +
+            "present): the server renders the spec (`tests/compile`), the CLI runs it (minting " +
             "a run inbox for await_email steps and resolving the saved login exactly as a cloud run " +
             "would), and only a green replay creates the test (bound to the replayed plan by its hash). " +
             "This holds over MCP too: the replay runs on the machine hosting the MCP server, never on " +
-            "Beryl's; if @playwright/test is missing there the tool returns the install commands (on a " +
-            "terminal the CLI offers to install it). " +
+            "Beryl's; if the Chromium browser is missing there the tool returns the install command " +
+            "(`beryl init` installs it; on a terminal the CLI offers to). " +
             "A red replay banks NOTHING: the failure evidence comes back (over MCP the screenshot is " +
             "image content), you fix the plan file and re-run. The proving run is imported as the " +
             "test's first run (--no-sync to skip). A plan that signs in with a session Beryl captured " +
@@ -393,8 +400,10 @@ export const testCommands = [
                         // pipe the hint is the answer.
                         if (ctx.interactive && !installOffered) {
                             installOffered = true;
-                            if (await confirmInstall(ctx.prompt)) {
-                                await installPlaywright(process.cwd(), (line) => ctx.err(dim(line)));
+                            const cwd = process.cwd();
+                            const commands = installCommandsFor(playwrightGaps(cwd), cwd);
+                            if (await confirmInstall(ctx.prompt, commands)) {
+                                await installPlaywright(cwd, (line) => ctx.err(dim(line)));
                                 attempt -= 1;
                                 continue;
                             }
@@ -552,6 +561,39 @@ export const testCommands = [
             };
         },
     },
+    {
+        name: "tests add-groups",
+        summary: "Add groups to one or more tests, keeping the groups they already have",
+        description: "The additive counterpart of `tests set-groups`: every listed test gains the given " +
+            "groups and loses none, so you don't need to know what each test already carries. " +
+            "Names must already exist in the project (`beryl groups list`); an unknown name is " +
+            "an error, never a new group.",
+        scope: "project",
+        args: [{ name: "test-ids", description: "One or more test ids", required: true, variadic: true }],
+        flags: [
+            {
+                name: "group",
+                type: "strings",
+                description: "Group name to add, repeatable (at least one)",
+            },
+        ],
+        examples: ["beryl tests add-groups 4f… 9a… --group Smoke", "beryl tests add-groups 4f… --group Checkout --group Smoke"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const add = flagStrings(input, "group");
+            if (!add)
+                throw new UsageError("Pass at least one --group");
+            const ids = argList(input, "test-ids");
+            const data = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/bulk-groups`, {
+                test_case_ids: ids,
+                add,
+            }));
+            return {
+                data,
+                human: `Added ${add.join(", ")} to ${data.updated} of ${ids.length} test${ids.length === 1 ? "" : "s"} (the rest already had them).`,
+            };
+        },
+    },
     {
         name: "tests quarantine",
         summary: "Mute a flaky test: it keeps running, but its failures stop failing the run",
@@ -581,16 +623,28 @@ export const testCommands = [
     },
     {
         name: "tests delete",
-        summary: "Delete a test, its version history, and its results",
+        summary: "Delete tests, their version history, and their results",
+        description: "Several ids are deleted together in one transaction: an unknown id fails the whole " +
+            "call and nothing is deleted.",
         scope: "project",
-        args: [{ name: "test-id", description: "Test id", required: true }],
+        args: [{ name: "test-ids", description: "One or more test ids", required: true, variadic: true }],
         flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        examples: ["beryl tests delete 4f… --force", "beryl tests delete 4f… 9a… 1c…"],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const testId = arg(input, "test-id");
-            await ctx.confirm(`Delete test ${testId} and all its history?`, flagBool(input, "force"));
-            await ctx.client.del(testPath(workspaceId, projectId, testId));
-            return { human: "Deleted." };
+            const ids = argList(input, "test-ids");
+            const single = ids.length === 1 ? ids[0] : undefined;
+            const what = single ? `test ${single} and all its history` : `${ids.length} tests and all their history`;
+            await ctx.confirm(`Delete ${what}?`, flagBool(input, "force"));
+            if (single) {
+                await ctx.client.del(testPath(workspaceId, projectId, single));
+            }
+            else {
+                await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/bulk-delete`, {
+                    test_case_ids: ids,
+                });
+            }
+            return { human: ids.length === 1 ? "Deleted." : `Deleted ${ids.length} tests.` };
         },
     },
     {

package/dist/local-run.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { PLAYWRIGHT_INSTALL_COMMANDS } from "./playwright-install.js";
+import { bundledRunnerCli, installHint, PLAYWRIGHT_INSTALL_COMMANDS, } from "./playwright-install.js";
 // We invoke @playwright/test as an external rather than bundling it — the CLI's zero-runtime-dep
 // rule. In a node_modules install `playwright` is on PATH; otherwise fall back to `npx playwright`,
 // exactly as the cloud runner does. The install commands come from playwright-install.ts so the
@@ -51,25 +51,36 @@ function runProcess(command, args, cwd, env) {
         child.on("close", (code) => resolve({ code, stdout, stderr }));
     });
 }
-// `npx playwright` is the portable fallback when no local binary is on PATH — it resolves
-// the project's @playwright/test without us hard-coding a node_modules path.
+// The repo's own runner first; else the one bundled with the CLI; `npx playwright` is the
+// last resort for a CLI install that somehow lost its dependencies.
 function playwrightBase(cwd) {
     const binName = process.platform === "win32" ? "playwright.cmd" : "playwright";
     const local = path.join(cwd, "node_modules", ".bin", binName);
     if (fs.existsSync(local))
-        return { command: local, args: ["test"] };
+        return { command: local, args: ["test"], label: "playwright test" };
+    const bundled = bundledRunnerCli();
+    if (bundled) {
+        return {
+            command: process.execPath,
+            args: [bundled, "test"],
+            label: "playwright test (bundled with the CLI)",
+            nodePath: path.resolve(path.dirname(bundled), "..", ".."),
+        };
+    }
     const npx = process.platform === "win32" ? "npx.cmd" : "npx";
-    return { command: npx, args: ["playwright", "test"] };
+    return { command: npx, args: ["playwright", "test"], label: "npx playwright test" };
 }
 // "unknown command 'test'" is the Python `playwright` shim (no `test` subcommand); the module
-// errors mean @playwright/test isn't installed. Either way the actionable answer is the same
-// install hint, not a stack trace.
+// errors mean @playwright/test isn't installed; "Executable doesn't exist" is the runner
+// launching a browser revision that was never downloaded. Either way the actionable answer
+// is the same install hint, not a stack trace.
 function looksLikePlaywrightMissing(r) {
     if (r.spawnError?.code === "ENOENT")
         return true;
     const blob = `${r.stdout}\n${r.stderr}`;
     return (/unknown command ['"]?test/i.test(blob) ||
         /Cannot find module ['"]@playwright\/test/i.test(blob) ||
+        /Executable doesn't exist/i.test(blob) ||
         /npm ERR!.*could not determine executable|npx.*not found/i.test(blob));
 }
 export function parsePlaywrightReport(data) {
@@ -249,12 +260,15 @@ export async function runSpecLocally(opts) {
     fs.writeFileSync(configPath, ISOLATING_CONFIG(runDir, artifactsDir));
     const reportPath = path.join(runDir, "report.json");
     const cleanup = () => fs.rmSync(runDir, { recursive: true, force: true });
-    const { command, args: base } = playwrightBase(cwd);
+    const { command, args: base, label, nodePath } = playwrightBase(cwd);
     const args = [...base, `--config=${configPath}`, "--reporter=json"];
-    opts.onProgress?.(`Running ${command} ${base.join(" ")} on ${opts.testName}…`);
+    opts.onProgress?.(`Running ${label} on ${opts.testName}…`);
     await opts.setup?.(runDir);
     const stop = opts.during?.(runDir);
     const env = { ...process.env, PLAYWRIGHT_JSON_OUTPUT_NAME: reportPath };
+    if (nodePath) {
+        env.NODE_PATH = [nodePath, process.env.NODE_PATH].filter(Boolean).join(path.delimiter);
+    }
     // cwd is the RUN dir, not the project: the spec's relative writes (frames/,
     // email-inbox.json, dom-snapshot.html, phase.json) must land where we harvest and
     // clean up, exactly as the cloud runner keys them to its per-run workdir.
@@ -267,7 +281,7 @@ export async function runSpecLocally(opts) {
     }
     if (looksLikePlaywrightMissing(result)) {
         cleanup();
-        throw new PlaywrightMissingError(PLAYWRIGHT_INSTALL_HINT);
+        throw new PlaywrightMissingError(installHint(cwd));
     }
     let results;
     try {

package/dist/playwright-install.js

@@ -12,6 +12,40 @@ export const PLAYWRIGHT_INSTALL_COMMANDS = `${INSTALL_TEST_RUNNER.join(" ")} &&
 // Resolve from the project tree, not from wherever the globally-installed CLI happens to
 // live — `createRequire` rooted at cwd walks up the same node_modules chain Playwright will.
 const projectRequire = (cwd) => createRequire(path.join(cwd, "package.json"));
+// @playwright/test is a dependency of the CLI, so a repo needs nothing installed to run
+// locally: the runner comes with `npx @beryl-so/cli`, and only the browser is per-machine.
+// A repo's own @playwright/test still wins when present (its version, its browser revision).
+const cliRequire = createRequire(import.meta.url);
+// cli.js is the package's bin, not an export, so it is located via package.json.
+function bundledRunner() {
+    try {
+        const pkgPath = cliRequire.resolve("@playwright/test/package.json");
+        const { version } = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        return { cli: path.join(path.dirname(pkgPath), "cli.js"), version };
+    }
+    catch {
+        return undefined;
+    }
+}
+export const bundledRunnerCli = () => bundledRunner()?.cli;
+// By hand, the browser must be fetched for the runner that will launch it: the repo's own
+// (`npx playwright` resolves it) or, in a bare repo, the CLI's pinned version. An unpinned
+// `npx playwright install` there downloads the registry's latest revision, which is not it.
+export function browserInstallCommand(cwd) {
+    const bundled = bundledRunner();
+    if (hasPlaywrightTest(cwd) || !bundled)
+        return INSTALL_CHROMIUM.join(" ");
+    const [npx, pkg, ...rest] = INSTALL_CHROMIUM;
+    return [npx, `${pkg}@${bundled.version}`, ...rest].join(" ");
+}
+function bundledCoreDir() {
+    try {
+        return path.dirname(cliRequire.resolve("playwright-core/package.json"));
+    }
+    catch {
+        return undefined;
+    }
+}
 export function hasPlaywrightTest(cwd) {
     try {
         projectRequire(cwd).resolve("@playwright/test");
@@ -89,7 +123,7 @@ const isComplete = (dir) => fs.existsSync(path.join(dir, INSTALL_MARKER));
  * problem that reads as a broken suite.
  */
 export function hasChromiumBrowser(cwd) {
-    const coreDir = playwrightCoreDir(cwd);
+    const coreDir = hasPlaywrightTest(cwd) ? playwrightCoreDir(cwd) : bundledCoreDir();
     const root = browsersRoot(coreDir);
     // Nowhere known to look — say nothing rather than block; the run surfaces Playwright's
     // own error if it really is missing.
@@ -110,7 +144,7 @@ export function hasChromiumBrowser(cwd) {
     }
 }
 export function playwrightGaps(cwd) {
-    const runner = !hasPlaywrightTest(cwd);
+    const runner = !hasPlaywrightTest(cwd) && !bundledRunnerCli();
     // With no runner there is no revision to judge a cached browser against, so the honest
     // answer is the full install — not the npm half and a second failure right after it.
     return { runner, browser: runner || !hasChromiumBrowser(cwd) };
@@ -122,10 +156,10 @@ export function describeGaps(gaps) {
     return gaps.browser ? "the Chromium browser" : "@playwright/test";
 }
 /** Only the commands the missing halves need — a present @playwright/test isn't reinstalled. */
-export function installCommandsFor(gaps) {
+export function installCommandsFor(gaps, cwd = process.cwd()) {
     const commands = [
         ...(gaps.runner ? [INSTALL_TEST_RUNNER.join(" ")] : []),
-        ...(gaps.browser ? [INSTALL_CHROMIUM.join(" ")] : []),
+        ...(gaps.browser ? [browserInstallCommand(cwd)] : []),
     ];
     return commands.length > 0 ? commands.join(" && ") : PLAYWRIGHT_INSTALL_COMMANDS;
 }
@@ -160,10 +194,19 @@ function runInherit(command, args, cwd) {
  * the browser binary — an installed runner with no browser still fails a real run.
  */
 export async function installPlaywright(cwd, onStep) {
-    if (!hasPlaywrightTest(cwd)) {
+    const bundled = bundledRunnerCli();
+    if (!hasPlaywrightTest(cwd) && !bundled) {
         onStep?.(`Installing @playwright/test — ${INSTALL_TEST_RUNNER.join(" ")}`);
         await runInherit(INSTALL_TEST_RUNNER[0], INSTALL_TEST_RUNNER.slice(1), cwd);
     }
-    onStep?.(`Installing the Chromium browser — ${INSTALL_CHROMIUM.join(" ")}`);
+    onStep?.(`Installing the Chromium browser — ${browserInstallCommand(cwd)}`);
+    if (!hasPlaywrightTest(cwd) && bundled) {
+        await runInherit(process.execPath, [bundled, ...INSTALL_CHROMIUM.slice(2)], cwd);
+        return;
+    }
     await runInherit(INSTALL_CHROMIUM[0], INSTALL_CHROMIUM.slice(1), cwd);
 }
+export function installHint(cwd, gaps = playwrightGaps(cwd)) {
+    const commands = installCommandsFor(gaps, cwd);
+    return `Local runs need ${describeGaps(gaps)}. Install it, then re-run:\n  ${commands}`;
+}

package/dist/telemetry.js

@@ -233,6 +233,24 @@ export function createPostHogClient() {
     posthog ??= new PostHog(POSTHOG_KEY, { host: POSTHOG_HOST, disableGeoip: false });
     return posthog;
 }
+// `beryl init` starts before there is an account to attribute to: its events land on the
+// process session id, and the session is aliased onto the account once init has signed in,
+// so the install joins the same person as the signup and the later MCP work.
+export function captureCliEvent(event, apiUrl, properties = {}) {
+    createPostHogClient().capture({
+        distinctId: sessionId,
+        event,
+        properties: { ...baseEventProperties(apiUrl), ...properties },
+    });
+}
+export function aliasSessionToAccount(userId) {
+    createPostHogClient().alias({ distinctId: userId, alias: sessionId });
+}
+export function flushTelemetry() {
+    // Fire-and-forget: init keeps running (login, installs) while the batch goes out, and a
+    // failed send must never surface to the user.
+    void posthog?.flush().catch(() => { });
+}
 export function analyticsOptions(apiUrl, identify) {
     const properties = baseEventProperties(apiUrl);
     return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.33.0",
-  "description": "Beryl on the command line \u2014 projects, runs, the exploring agent, and an MCP server over the same commands.",
+  "version": "0.34.2",
+  "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",
   "homepage": "https://beryl.so/docs/cli",
@@ -32,11 +32,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@playwright/test": "^1.61.1",
     "@posthog/mcp": "^0.11.6",
     "posthog-node": "^5.49.1"
   },
   "devDependencies": {
-    "@playwright/test": "^1.61.1",
     "@types/node": "^26.1.1",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",