@beryl-so/cli 0.34.3 → 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/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.3",
+  "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",