@beryl-so/cli 0.34.2 → 0.34.4

package/dist/adapters/mcp.js

@@ -18,29 +18,68 @@ export function mcpTools() {
     return commands.filter((c) => !c.interactive && !c.hidden && !c.mcpHidden && c.name !== "mcp");
 }
 const mcpToolNames = new Set(mcpTools().map(toolName));
+const toolByCommand = new Map(mcpTools().map((spec) => [spec.name, toolName(spec)]));
+const flagNames = new Set(commands.flatMap((spec) => (spec.flags ?? []).map((f) => f.name)));
 /** The tool name a command is exposed as under `beryl mcp`, or undefined if it isn't exposed. */
 export function mcpToolFor(spec) {
     const name = toolName(spec);
     return mcpToolNames.has(name) ? name : undefined;
 }
+/** `[beryl] tests list ...` as its tool name plus the rest, or undefined when the words are
+ *  no MCP tool (login, init, mcp): those are real terminal instructions and must stay. */
+function commandToTool(text) {
+    const words = text.trim().split(/\s+/);
+    if (words[0] === "beryl")
+        words.shift();
+    for (const n of [3, 2, 1]) {
+        const tool = toolByCommand.get(words.slice(0, n).join(" "));
+        if (tool)
+            return [tool, ...words.slice(n)].join(" ");
+    }
+    return undefined;
+}
+function flagsToParams(text, wrap) {
+    return text
+        .replace(/--json\b/g, "JSON output (always on over MCP)")
+        .replace(/--no-([a-z][a-z-]*)/g, (_, name) => flagNames.has(`no-${name}`) ? wrap(`no-${name}`) : wrap(`${name}: false`))
+        .replace(/--([a-z][a-z-]*)/g, (_, name) => wrap(name));
+}
+/** Registry text is written for `beryl --help`; the agent sees JSON parameters and tool
+ *  names, so `--wide` becomes `wide`, `beryl groups list` becomes `groups_list`, and a
+ *  command that only exists in a terminal is left verbatim. */
+export function toMcpDialect(text) {
+    return text.replace(/`[^`]*`|[^`]+/g, (segment) => {
+        if (segment.startsWith("`")) {
+            const inner = segment.slice(1, -1);
+            const asTool = commandToTool(inner);
+            if (asTool === undefined && inner.startsWith("beryl "))
+                return segment;
+            return `\`${flagsToParams(asTool ?? inner, (n) => n)}\``;
+        }
+        const prose = segment.replace(/\bberyl( [a-z][a-z-]*){1,3}(?=$|[^a-z-])/g, (command) => commandToTool(command) ?? command);
+        return flagsToParams(prose, (n) => `\`${n}\``);
+    });
+}
 export function toolInputSchema(spec) {
     const properties = {};
     const required = [];
     for (const a of spec.args ?? []) {
+        const description = toMcpDialect(a.description);
         properties[a.name] = a.variadic
-            ? { type: "array", items: { type: "string" }, description: a.description }
-            : { type: "string", description: a.description };
+            ? { type: "array", items: { type: "string" }, description }
+            : { type: "string", description };
         if (a.required)
             required.push(a.name);
     }
     for (const f of spec.flags ?? []) {
         const withDefault = f.default !== undefined ? { default: f.default } : {};
+        const description = toMcpDialect(f.mcpDescription ?? f.description);
         properties[f.name] =
             f.type === "strings"
-                ? { type: "array", items: { type: "string" }, description: f.description, ...withDefault }
+                ? { type: "array", items: { type: "string" }, description, ...withDefault }
                 : {
                     type: f.type,
-                    description: f.description,
+                    description,
                     ...(f.enum ? { enum: f.enum } : {}),
                     ...withDefault,
                 };
@@ -124,7 +163,7 @@ export function exampleArgs(spec, example) {
     return Object.keys(out).length ? out : null;
 }
 export function toolDescription(spec) {
-    const base = spec.description ? `${spec.summary}. ${spec.description}` : spec.summary;
+    const base = toMcpDialect(spec.description ? `${spec.summary}. ${spec.description}` : spec.summary);
     const lines = (spec.examples ?? [])
         .map((e) => exampleArgs(spec, e))
         .filter((a) => a !== null)
@@ -251,7 +290,9 @@ export function mcpInstructions() {
         "run-fix loop) ships as both the beryl-test skill and the `guide` tool — same " +
         `content. If a beryl-test skill stating v${version} is already loaded, do not ` +
         "call `guide`; if no beryl-test skill is available or it states another version, " +
-        "call `guide` before authoring your first test plan.");
+        "call `guide` before authoring your first test plan. " +
+        "An account can hold several workspaces and projects: call `projects_list` first " +
+        "and pass `project` (an id is enough) on every project-scoped tool, or the call fails.");
 }
 export async function serveMcp(baseCtx) {
     setSurface("mcp");
@@ -300,7 +341,7 @@ export async function serveMcp(baseCtx) {
             return toolResult(result, lines);
         }
         catch (err) {
-            const message = err instanceof CliError ? err.message : String(err);
+            const message = toMcpDialect(err instanceof CliError ? err.message : String(err));
             return {
                 content: [{ type: "text", text: [...lines, message].join("\n") }],
                 isError: true,

package/dist/commands/auth.js

@@ -186,7 +186,7 @@ export const authCommands = [
         description: "Creates a passwordless account for the email and sends it a 6-digit code. " +
             "Finish with `beryl login --email <addr> --code <the 6 digits>`, which verifies " +
             "the account, creates its workspace, and signs the CLI in. With an inbox from " +
-            "`beryl inbox create` as the address, an agent can provision a fresh account " +
+            "`beryl mailbox create` as the address, an agent can provision a fresh account " +
             "end-to-end with no human at a prompt.",
         flags: [
             {

package/dist/context.js

@@ -18,6 +18,23 @@ async function pickOne(ctx, candidates, kind, usageMessage) {
     }
     return candidates[n - 1].id;
 }
+// Over MCP there is no --flag and no env var to set: the only fix is a JSON parameter on
+// every call, and a project id alone already resolves its workspace.
+function ambiguousMessage(ctx, kind, candidates) {
+    const rows = candidates.map((c) => `  ${c.id}  ${c.name ?? c.root_url ?? ""}`).join("\n");
+    let how;
+    if (ctx.mcp) {
+        how =
+            kind === "workspace"
+                ? 'pass "workspace": "<id>" on each call, or "project": "<project id>", which implies its workspace:'
+                : 'pass "project": "<id>" on every project-scoped call (a project id alone is enough, no workspace needed):';
+    }
+    else {
+        const forms = kind === "workspace" ? "<id|name>" : "<id|name|url>";
+        how = `pass --${kind} ${forms} or set BERYL_${kind.toUpperCase()}:`;
+    }
+    return `Multiple ${kind}s: ${how}\n${rows}`;
+}
 function matchByName(candidates, value, kind) {
     const lower = value.toLowerCase();
     const matches = candidates.filter((c) => c.name?.toLowerCase() === lower ||
@@ -82,8 +99,7 @@ export function createContext(options) {
                 throw new CliError("You have no workspaces yet — create one with `beryl workspaces create`");
             }
             else {
-                workspaceCache = await pickOne(ctx, workspaces, "workspace", "Multiple workspaces — pass --workspace <id|name> or set BERYL_WORKSPACE:\n" +
-                    workspaces.map((w) => `  ${w.id}  ${w.name ?? ""}`).join("\n"));
+                workspaceCache = await pickOne(ctx, workspaces, "workspace", ambiguousMessage(ctx, "workspace", workspaces));
             }
             return workspaceCache;
         },
@@ -121,8 +137,7 @@ export function createContext(options) {
                     "`beryl projects create <url>` (add --no-explore to author tests yourself).");
             }
             else {
-                projectId = await pickOne(ctx, projects, "project", "Multiple projects — pass --project <id|name|url> or set BERYL_PROJECT:\n" +
-                    projects.map((p) => `  ${p.id}  ${p.name ?? p.root_url ?? ""}`).join("\n"));
+                projectId = await pickOne(ctx, projects, "project", ambiguousMessage(ctx, "project", projects));
             }
             projectCache = { workspaceId, projectId };
             return projectCache;

package/dist/local-run.js

@@ -1,11 +1,9 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-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
-// hint text and the actual installer never drift apart.
+import { installHint, PLAYWRIGHT_INSTALL_COMMANDS, resolvePlaywrightRunner, } from "./playwright-install.js";
+// @playwright/test is invoked as an external, never bundled — the CLI's zero-runtime-dep rule.
+// The install commands come from playwright-install.ts so hint and installer never drift apart.
 export const PLAYWRIGHT_INSTALL_HINT = "Local Playwright not found. Install it in this project, then re-run:\n" +
     `  ${PLAYWRIGHT_INSTALL_COMMANDS}`;
 // Isolate the run from any playwright.config.ts in the customer's repo: a stray `testMatch`
@@ -51,20 +49,20 @@ function runProcess(command, args, cwd, env) {
         child.on("close", (code) => resolve({ code, stdout, stderr }));
     });
 }
-// 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"], label: "playwright test" };
-    const bundled = bundledRunnerCli();
-    if (bundled) {
+// Resolved from the run dir — the exact place the spec imports from — so the process we
+// spawn and the module the spec loads are the same copy. `npx playwright` is the last
+// resort for a CLI install that somehow lost its dependencies.
+export function playwrightBase(runDir) {
+    const runner = resolvePlaywrightRunner(runDir);
+    if (runner?.source === "project") {
+        return { command: process.execPath, args: [runner.cli, "test"], label: "playwright test" };
+    }
+    if (runner) {
         return {
             command: process.execPath,
-            args: [bundled, "test"],
+            args: [runner.cli, "test"],
             label: "playwright test (bundled with the CLI)",
-            nodePath: path.resolve(path.dirname(bundled), "..", ".."),
+            nodePath: path.resolve(path.dirname(runner.cli), "..", ".."),
         };
     }
     const npx = process.platform === "win32" ? "npx.cmd" : "npx";
@@ -260,7 +258,7 @@ 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, label, nodePath } = playwrightBase(cwd);
+    const { command, args: base, label, nodePath } = playwrightBase(runDir);
     const args = [...base, `--config=${configPath}`, "--reporter=json"];
     opts.onProgress?.(`Running ${label} on ${opts.testName}…`);
     await opts.setup?.(runDir);

package/dist/playwright-install.js

@@ -17,16 +17,32 @@ const projectRequire = (cwd) => createRequire(path.join(cwd, "package.json"));
 // 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 runnerAt(pkgPath, source) {
+    const { version } = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return { cli: path.join(path.dirname(pkgPath), "cli.js"), version, source };
+}
+function projectRunner(dir) {
+    try {
+        return runnerAt(projectRequire(dir).resolve("@playwright/test/package.json"), "project");
+    }
+    catch {
+        return undefined;
+    }
+}
 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 };
+        return runnerAt(cliRequire.resolve("@playwright/test/package.json"), "bundled");
     }
     catch {
         return undefined;
     }
 }
+// The single answer to "which @playwright/test": what `import "@playwright/test"` from `dir`
+// resolves to (any ancestor's node_modules), else the bundled copy. Runner and spec must load
+// the same one or Playwright refuses to run ("did not expect test.use() to be called here").
+export function resolvePlaywrightRunner(dir) {
+    return projectRunner(dir) ?? bundledRunner();
+}
 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
@@ -46,15 +62,7 @@ function bundledCoreDir() {
         return undefined;
     }
 }
-export function hasPlaywrightTest(cwd) {
-    try {
-        projectRequire(cwd).resolve("@playwright/test");
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+export const hasPlaywrightTest = (cwd) => projectRunner(cwd) !== undefined;
 // A local run launches chromium headless, which Playwright serves from a separate
 // `chromium_headless_shell` build (`playwright install chromium` fetches both). That is the
 // only engine a run ever launches, so it is the only one we install or check for.

package/dist/registry/index.js

@@ -17,11 +17,15 @@ export const WORKSPACE_FLAG = {
     name: "workspace",
     type: "string",
     description: "Workspace id or name (defaults to BERYL_WORKSPACE, or your only workspace)",
+    mcpDescription: "Workspace id or name. Needed only when the account has more than one workspace and " +
+        "no project id is passed (a project id implies its workspace)",
 };
 export const PROJECT_FLAG = {
     name: "project",
     type: "string",
     description: "Project id, name, or URL (defaults to BERYL_PROJECT, or the workspace's only project)",
+    mcpDescription: "Project id, name, or URL. Pass it on every call unless the account has exactly one " +
+        "project; a project id alone is enough, its workspace is looked up",
 };
 function withScopeFlags(spec) {
     if (!spec.scope || spec.scope === "none")

package/package.json

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