@beryl-so/cli 0.47.0 → 0.48.0

package/dist/beryl-test-skill.js

@@ -13,6 +13,40 @@ const indent = (text) => text
     .join("\n");
 export const BERYL_TEST_SKILL_FILENAME = "SKILL.md";
 export const BERYL_TEST_SKILL_DIR = "beryl-test";
+// The prose both editor pointers share. Cursor and Copilot read neither `.agents/skills/`
+// nor `.claude/skills/`, so `init` writes them their own pointer instead. Thin on purpose:
+// it sends the agent to the `guide` MCP tool rather than inlining the 500-line skill, and
+// `guide` ships with the CLI so the real guidance never drifts from the installed version.
+const BERYL_GUIDE_POINTER = `When writing, editing, or debugging Beryl tests in this repo, call the \`guide\`
+MCP tool first. It returns the full authoring guide: the ActionPlan shape, outcome
+assertions, test accounts and the project mailbox, and the local run-fix loop.
+
+Then use the Beryl MCP tools: \`projects_list\` to find the project, and \`tests_create\`
+to author a plan and replay it locally before it is banked.
+
+The \`guide\` tool ships with the CLI and always matches the installed version, so treat
+it as the source of truth over anything cached here.`;
+// Cursor reads its own `.cursor/rules/*.mdc`, auto-loaded when alwaysApply is set.
+export const BERYL_CURSOR_RULE_FILENAME = "beryl.mdc";
+export const BERYL_CURSOR_RULE = `---
+description: Authoring and editing Beryl end-to-end tests
+alwaysApply: true
+---
+
+# Beryl test authoring
+
+${BERYL_GUIDE_POINTER}
+`;
+// GitHub Copilot reads `.github/copilot-instructions.md`, a file the repo may already own,
+// so our content lives in a marked section that `init` appends once and refreshes in place.
+// The markers must stay byte-stable across releases or the refresh can't find the block.
+export const BERYL_COPILOT_MARK_BEGIN = "<!-- BEGIN beryl (managed by beryl init) -->";
+export const BERYL_COPILOT_MARK_END = "<!-- END beryl -->";
+export const BERYL_COPILOT_SECTION = `${BERYL_COPILOT_MARK_BEGIN}
+## Beryl test authoring
+
+${BERYL_GUIDE_POINTER}
+${BERYL_COPILOT_MARK_END}`;
 // The example plan the skill shows verbatim. Exported so the test suite lints it with
 // lintPlan — the skill's documented shape must pass `beryl tests lint` on the first try.
 export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {

package/dist/commands/init.js

@@ -2,7 +2,7 @@ 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 { BERYL_COPILOT_MARK_BEGIN, BERYL_COPILOT_MARK_END, BERYL_COPILOT_SECTION, BERYL_CURSOR_RULE, BERYL_CURSOR_RULE_FILENAME, BERYL_TEST_SKILL, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME, } from "../beryl-test-skill.js";
 import { loadConfig } from "../config.js";
 import { AuthError, CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
@@ -27,8 +27,14 @@ const PLAYWRIGHT_SERVER_ENTRY = {
     command: "npx",
     args: ["@playwright/mcp@latest", "--headless"],
 };
+// VS Code's `.vscode/mcp.json` uses a top-level `servers` key and tags each stdio server
+// with `type`, unlike Cursor/Claude's `mcpServers`. Same pinned commands, different shape.
+const VSCODE_MCP_SERVER_ENTRY = { type: "stdio", ...MCP_SERVER_ENTRY };
+const VSCODE_PLAYWRIGHT_SERVER_ENTRY = { type: "stdio", ...PLAYWRIGHT_SERVER_ENTRY };
 const ACTION_PLAN_SCHEMA_URL = "https://api.beryl.so/api/v1/schemas/action-plan.schema.json";
-function mergeMcpConfig(file) {
+// `key` is the container the editor expects: `mcpServers` for Claude/Cursor, `servers` for
+// VS Code. `entries` are the editor-shaped server objects (VS Code tags them with `type`).
+function mergeMcpConfig(file, key, entries) {
     let existing = {};
     if (fs.existsSync(file)) {
         try {
@@ -38,16 +44,16 @@ function mergeMcpConfig(file) {
             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);
+    const servers = (existing[key] ?? {});
+    const beryl = JSON.stringify(servers.beryl) !== JSON.stringify(entries.beryl);
     if (beryl)
-        servers.beryl = MCP_SERVER_ENTRY;
+        servers.beryl = entries.beryl;
     // Never clobber a playwright server the user already wired up.
     const playwright = servers.playwright === undefined;
     if (playwright)
-        servers.playwright = PLAYWRIGHT_SERVER_ENTRY;
+        servers.playwright = entries.playwright;
     if (beryl || playwright) {
-        existing.mcpServers = servers;
+        existing[key] = servers;
         fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.writeFileSync(file, JSON.stringify(existing, null, 2) + "\n");
     }
@@ -83,25 +89,54 @@ function claudeAddHint(name, entry) {
 function cursorUserConfigPath() {
     return path.join(os.homedir(), ".cursor", "mcp.json");
 }
-// Write the skill to one `.../beryl-test/SKILL.md` file. The skill is generated content
-// that ships with the CLI and changes every release, so anything that differs is
-// overwritten: a stale copy silently feeds agents months-old guidance, which is worse than
-// losing a local edit the user can redo (and `beryl guide` still prints the same content).
-function writeSkillFile(file) {
+// Write generated content that ships with the CLI and changes every release, so anything
+// that differs is overwritten: a stale copy silently feeds agents months-old guidance,
+// which is worse than losing a local edit the user can redo (and `beryl guide` still prints
+// the same content). CRLF is normalized so a CRLF copy of our own content counts as current
+// and isn't rewritten on every run; we always write LF.
+function writeGeneratedFile(file, content) {
     let outcome = "installed";
     if (fs.existsSync(file)) {
-        // Compare with line endings normalized so a CRLF copy of our own content counts as
-        // current and isn't rewritten on every run — we always write LF.
         const norm = (s) => s.replace(/\r\n/g, "\n");
-        const current = fs.readFileSync(file, "utf8");
-        if (norm(current) === norm(BERYL_TEST_SKILL))
+        if (norm(fs.readFileSync(file, "utf8")) === norm(content))
             return { outcome: "unchanged", file };
         outcome = "updated";
     }
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, BERYL_TEST_SKILL);
+    fs.writeFileSync(file, content);
     return { outcome, file };
 }
+const writeSkillFile = (file) => writeGeneratedFile(file, BERYL_TEST_SKILL);
+// Cursor's equivalent of the skill: a repo-local `.cursor/rules/beryl.mdc`. Always repo-local
+// even at `--scope user`, because Cursor has no global rules FILE (User Rules live in its
+// settings UI), so there is nowhere else to put it.
+const writeCursorRule = (cwd) => writeGeneratedFile(path.join(cwd, ".cursor", "rules", BERYL_CURSOR_RULE_FILENAME), BERYL_CURSOR_RULE);
+const copilotInstructionsPath = (cwd) => path.join(cwd, ".github", "copilot-instructions.md");
+// Copilot's `.github/copilot-instructions.md` may already hold the repo's own instructions,
+// so we own only a marked section: refresh it in place when present, append it once when the
+// file exists without it, create the file when it doesn't. Never rewrites the user's prose.
+function writeCopilotInstructions(cwd) {
+    const file = copilotInstructionsPath(cwd);
+    const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const begin = current.indexOf(BERYL_COPILOT_MARK_BEGIN);
+    if (begin !== -1) {
+        const endAt = current.indexOf(BERYL_COPILOT_MARK_END, begin);
+        const endFull = endAt === -1 ? current.length : endAt + BERYL_COPILOT_MARK_END.length;
+        if (current.slice(begin, endFull) === BERYL_COPILOT_SECTION)
+            return { outcome: "unchanged", file };
+        fs.writeFileSync(file, current.slice(0, begin) + BERYL_COPILOT_SECTION + current.slice(endFull));
+        return { outcome: "updated", file };
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const body = current ? current.replace(/\n*$/, "\n\n") + BERYL_COPILOT_SECTION + "\n" : BERYL_COPILOT_SECTION + "\n";
+    fs.writeFileSync(file, body);
+    return { outcome: "installed", file };
+}
+const outcomeLabel = (o) => o === "installed"
+    ? "installed"
+    : o === "updated"
+        ? "updated (refreshed to this CLI's version)"
+        : "already current";
 const skillLeaf = (root) => path.join(root, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME);
 // The authoring skill follows the `--scope` flag, same as the MCP servers: under `user`
 // (the default) it lands in the HOME `.agents/skills/` + `.claude/skills/` dirs, so the
@@ -126,7 +161,18 @@ export function refreshInstalledSkills(cwd) {
         skillLeaf(path.join(root, ".agents", "skills")),
         skillLeaf(path.join(root, ".claude", "skills")),
     ]));
-    return [...files].filter((file) => fs.existsSync(file)).map(writeSkillFile);
+    const refreshed = [...files].filter((file) => fs.existsSync(file)).map(writeSkillFile);
+    // The Cursor rule and Copilot section are repo-local pointers; refresh them the same way so
+    // a reworded pointer reaches those editors on the next MCP spawn, matching the skill. Both
+    // are refreshed only when already installed, and the Copilot writer touches only its block.
+    const cursorRule = path.join(cwd, ".cursor", "rules", BERYL_CURSOR_RULE_FILENAME);
+    if (fs.existsSync(cursorRule))
+        refreshed.push(writeGeneratedFile(cursorRule, BERYL_CURSOR_RULE));
+    const copilot = copilotInstructionsPath(cwd);
+    if (fs.existsSync(copilot) && fs.readFileSync(copilot, "utf8").includes(BERYL_COPILOT_MARK_BEGIN)) {
+        refreshed.push(writeCopilotInstructions(cwd));
+    }
+    return refreshed;
 }
 // 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:
@@ -169,7 +215,11 @@ export const initCommands = [
             "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 " +
+            "instead. With --cursor the same two servers are also wired into Cursor and a repo-local " +
+            ".cursor/rules/beryl.mdc authoring rule is written (Cursor's equivalent of the skill, " +
+            "since it reads neither skills dir); --vscode does the same for VS Code / GitHub Copilot " +
+            "(.vscode/mcp.json plus a marked section in .github/copilot-instructions.md). No " +
+            "workspace/project pin and no URL prompt: ask Claude to write tests for " +
             "your site and it resolves the workspace, project, and URL. Safe to re-run: every run " +
             "refreshes the authoring skill to this CLI's version (overwriting an older or edited " +
             "copy; `beryl guide` prints the same content), and skips whatever else is already set " +
@@ -188,13 +238,21 @@ export const initCommands = [
             {
                 name: "cursor",
                 type: "boolean",
-                description: "Also write the same two MCP servers to Cursor's config",
+                description: "Also wire the same two MCP servers into Cursor's config and write a repo-local " +
+                    ".cursor/rules/beryl.mdc authoring rule (Cursor's equivalent of the skill)",
+            },
+            {
+                name: "vscode",
+                type: "boolean",
+                description: "Also wire the two MCP servers into .vscode/mcp.json and add a Beryl section to " +
+                    ".github/copilot-instructions.md for GitHub Copilot (both repo-local)",
             },
         ],
         examples: [
             "npx @beryl-so/cli@latest init",
             "beryl init --scope project",
             "beryl init --cursor",
+            "beryl init --vscode",
         ],
         async run(ctx, input) {
             const cwd = process.cwd();
@@ -256,17 +314,43 @@ export const initCommands = [
             }
             else {
                 const file = path.join(cwd, ".mcp.json");
-                const wrote = mergeMcpConfig(file);
+                const wrote = mergeMcpConfig(file, "mcpServers", {
+                    beryl: MCP_SERVER_ENTRY,
+                    playwright: PLAYWRIGHT_SERVER_ENTRY,
+                });
                 const where = path.relative(cwd, file);
                 report("beryl MCP", wrote.beryl, where);
                 report("playwright MCP", wrote.playwright, where);
             }
             if (input.flags.cursor) {
                 const file = scope === "user" ? cursorUserConfigPath() : path.join(cwd, ".cursor", "mcp.json");
-                const wrote = mergeMcpConfig(file);
+                const wrote = mergeMcpConfig(file, "mcpServers", {
+                    beryl: MCP_SERVER_ENTRY,
+                    playwright: PLAYWRIGHT_SERVER_ENTRY,
+                });
                 const where = scope === "user" ? file : path.relative(cwd, file);
                 report("cursor beryl MCP", wrote.beryl, where);
                 report("cursor playwright MCP", wrote.playwright, where);
+                const rule = writeCursorRule(cwd);
+                ctx.err(`${green("✓")} cursor authoring rule ${outcomeLabel(rule.outcome)} ${dim(path.relative(cwd, rule.file))}`);
+                if (scope === "user") {
+                    ctx.err(dim("  • The rule is repo-local (Cursor has no global rules file); commit it to share it."));
+                }
+            }
+            // VS Code (Copilot) is always repo-local: `.vscode/mcp.json` for the servers and a
+            // marked section in `.github/copilot-instructions.md` for the guide pointer. VS Code's
+            // per-user MCP config is managed through its UI, not a portable file, so scope is moot.
+            if (input.flags.vscode) {
+                const file = path.join(cwd, ".vscode", "mcp.json");
+                const wrote = mergeMcpConfig(file, "servers", {
+                    beryl: VSCODE_MCP_SERVER_ENTRY,
+                    playwright: VSCODE_PLAYWRIGHT_SERVER_ENTRY,
+                });
+                const where = path.relative(cwd, file);
+                report("vscode beryl MCP", wrote.beryl, where);
+                report("vscode playwright MCP", wrote.playwright, where);
+                const inst = writeCopilotInstructions(cwd);
+                ctx.err(`${green("✓")} copilot instructions ${outcomeLabel(inst.outcome)} ${dim(path.relative(cwd, inst.file))}`);
             }
             const skills = writeSkills(cwd, scope);
             for (const skill of skills) {

package/package.json

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