@beryl-so/cli 0.46.4 → 0.48.0

package/README.md

@@ -220,6 +220,7 @@ 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 set-access <test-id> <access>` | Mark a test read or write | `tests_set_access` |
 | `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-ids...>` | Delete tests, their version history, and their results | `tests_delete` |

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 = {
@@ -97,10 +131,11 @@ Then, per test:
 1. **Drive the flow** in a real browser over the Playwright MCP — never author from
    imagination (§2).
 2. **Write the ActionPlan**, with one real outcome assertion (§2).
-3. \`beryl tests lint --file plan.json\` — schema check, offline, no network.
-4. \`beryl tests create --title … --file … --description "<the intent>"\` — replays the
-   plan locally, banks it only on green, records no run; a red replay hands back the
-   failure — fix and re-run (§3 for the intent, §4 for the loop).
+3. \`beryl tests lint --file plan.json --access read|write\` — schema and access check,
+   offline, no network.
+4. \`beryl tests create --title … --file … --access read|write --description "<the
+   intent>"\` — replays the plan locally, banks it only on green, records no run; a red
+   replay hands back the failure — fix and re-run (§3 for the intent, §4 for the loop).
 5. When the batch is banked, run the new ids together ONCE (\`beryl runs local <id…>\`,
    or \`beryl runs trigger\` for the cloud) so they land as one run with real first results.
 
@@ -151,6 +186,14 @@ The trade is drift — run 200 has 200 of everything run 1 created. So:
   your own victim first — in \`before\` or the opening steps, \`{{unique}}\`-named —
   then delete it and assert \`gone\`. Never aim a delete at standing data: run 2 would
   have nothing to delete, and it eats the account's accumulated coverage.
+- **Every test is \`read\` or \`write\`.** \`read\` (the default) only looks. A test
+  that creates, saves, deletes, renames, invites, toggles or uploads anything is
+  \`write\`: bank it with \`--access write\`, and end its \`after\` with an \`expect\`
+  that proves the undo: \`gone\`, \`hidden\`, \`have_count\` or \`count_delta\` for a
+  removal, \`have_text\`, \`have_value\` or \`persisted\` for a restored value.
+  Create refuses a plan that writes without the label and a \`write\` plan
+  without that closing proof; a \`write\` test whose teardown found nothing to remove
+  fails the run. Flip a banked test with \`beryl tests set-access <id> write\`.
 
 ### If there is no account yet
 
@@ -261,7 +304,8 @@ leaves Beryl's cloud).
    gone) the teardown ends quietly right there instead of failing the test. Put it on
    the \`wait_for\` or \`expect\` that probes for the record, so the delete steps
    after it run only when there is something to delete; an optional \`click\` or
-   \`fill\` must be the last step of \`after\`.
+   \`fill\` must be the last step of \`after\`, so a \`write\` test (§1), whose
+   \`after\` ends with the proof \`expect\`, never marks its delete optional.
 
    The full action vocabulary:
 
@@ -432,7 +476,8 @@ this test alone.
 | creates an account, or signs in as one it created (a returning-user test: \`before\` signs up the alias and logs out, the steps sign in as it) | an \`after\` section that deletes it through the app, its steps marked \`optional\`; a plan that reads its signup mail is refused at save time without one |
 | only makes mail arrive, read or not, no account created | nothing to clean up; mail is kept for 48 hours |
 
-Every alias minted is listed by \`beryl mailbox identities\` with how its teardown ended.
+Every alias minted is listed by \`beryl mailbox identities\` with how its teardown
+ended; the run detail shows the same outcome on each result.
 
 The wiring is a three-part chain:
 

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/dist/commands/tests.js

@@ -66,11 +66,20 @@ function verifyFailureResult(err) {
 // The concise human table for `tests list` — the full TestResponse is a 24-column
 // firehose of internal ids that wraps unreadably in a normal terminal. `--wide`
 // (and `--json`) still expose every field.
-const LIST_COLUMNS = ["title", "status", "id", "last_result_status", "last_run_at"];
+const LIST_COLUMNS = ["title", "status", "access", "id", "last_result_status", "last_run_at"];
+const ACCESS_VALUES = ["read", "write"];
+function accessFlag(input, fallback) {
+    const raw = flagStr(input, "access") ?? fallback;
+    if (raw !== undefined && !ACCESS_VALUES.includes(raw)) {
+        throw new UsageError(`--access must be read or write, got "${raw}"`);
+    }
+    return raw;
+}
 function conciseTestRow(row) {
     return {
         title: row.nl_title,
         status: row.quarantined ? "quarantined" : row.is_active ? "active" : "inactive",
+        access: row.access,
         id: row.id,
         last_result_status: row.last_result_status,
         last_run_at: row.last_run_at,
@@ -98,14 +107,22 @@ export const testCommands = [
                 description: "The file is an account's signup or sign-in plan (for `accounts signup` / " +
                     "`accounts set-login`), so it may fill {{mailbox_address}}",
             },
+            {
+                name: "access",
+                type: "string",
+                description: "The label the plan will be banked with, read (default) or write; a plan that " +
+                    "creates, edits, deletes or toggles something must be write",
+            },
         ],
         examples: [
             "beryl tests lint --file plan.json",
+            "beryl tests lint --file plan.json --access write",
             "beryl tests lint --file signup-plan.json --provisioning",
         ],
         async run(_ctx, input) {
             const issues = lintPlan(readJsonFlag(input, "file"), {
                 provisioning: flagBool(input, "provisioning"),
+                access: accessFlag(input, "read"),
             });
             const lines = issues.map((i) => `${i.severity === "warning" ? "warning" : "error"} ${i.path}: ${i.message}`);
             if (issues.every((i) => i.severity === "warning")) {
@@ -134,6 +151,7 @@ export const testCommands = [
                 description: "Show only tests in this group (by name; see `beryl groups list`)",
             },
             { name: "wide", type: "boolean", description: "Show all columns, not the concise default" },
+            { name: "access", type: "string", description: "Only read or only write tests" },
             {
                 name: "page",
                 type: "number",
@@ -164,14 +182,17 @@ export const testCommands = [
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const page = flagNum(input, "page");
             const group = flagStr(input, "group");
+            const access = accessFlag(input);
             let data;
             if (page === undefined) {
                 data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests`, {
                     environment_id: flagStr(input, "env"),
                 }));
-                // GET /tests takes no group param; the paged route below filters server-side.
+                // GET /tests takes no group or access param; the paged route filters server-side.
                 if (group)
                     data = data.filter((t) => inGroup(t, group));
+                if (access)
+                    data = data.filter((t) => t.access === access);
             }
             else {
                 data = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/tests/page`, {
@@ -180,6 +201,7 @@ export const testCommands = [
                     status: flagStr(input, "status"),
                     group: flagBool(input, "ungrouped") ? "__ungrouped__" : group,
                     q: flagStr(input, "q"),
+                    access,
                     environment_id: flagStr(input, "env"),
                 })).items;
             }
@@ -274,6 +296,12 @@ export const testCommands = [
                     "name is an error (create groups with `beryl groups create`). Omit for no group.",
             },
             { name: "env", type: "string", description: "Environment id to compile and prove against" },
+            {
+                name: "access",
+                type: "string",
+                description: "read (default): the test only reads the app. write: any step creates, edits, " +
+                    "renames, deletes or toggles something; a writer must clean up in `after`",
+            },
             {
                 name: "dir",
                 type: "string",
@@ -295,11 +323,13 @@ export const testCommands = [
             const urlOverride = flagStr(input, "url-override");
             const env = flagStr(input, "env");
             const groups = flagStrings(input, "group");
+            const access = accessFlag(input, "read");
             const bank = (extra) => ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
                 title,
                 plan,
                 description,
                 groups,
+                access,
                 ...extra,
             });
             if (flagBool(input, "no-verify")) {
@@ -547,6 +577,31 @@ export const testCommands = [
             };
         },
     },
+    {
+        name: "tests set-access",
+        summary: "Mark a test read or write",
+        description: "read: the test only reads the app. write: any step creates, edits, renames, deletes " +
+            "or toggles something. The server refuses a plan that writes on a read test, so flip " +
+            "the label before re-authoring such a plan. A write test must clean up in `after`.",
+        scope: "project",
+        args: [
+            { name: "test-id", description: "Test id", required: true },
+            { name: "access", description: "read | write", required: true },
+        ],
+        examples: ["beryl tests set-access 4f… write", "beryl tests set-access 4f… read"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const access = arg(input, "access").toLowerCase();
+            if (!ACCESS_VALUES.includes(access)) {
+                throw new UsageError(`Expected "read" or "write", got "${arg(input, "access")}"`);
+            }
+            return {
+                data: await ctx.client.patch(testPath(workspaceId, projectId, arg(input, "test-id")), {
+                    access,
+                }),
+            };
+        },
+    },
     {
         name: "tests add-groups",
         summary: "Add groups to one or more tests, keeping the groups they already have",

package/dist/lint.js

@@ -9,6 +9,13 @@ export const MAILBOX_ADDRESS_IN_TEST = "This plan types the standing account's a
     "and rides the account's session; one that needs an address the site can mail cites " +
     "{{inbox_address}}, an alias only this test reads. Only the account's own signup and " +
     "sign-in plans (accounts signup, accounts set-login) may fill {{mailbox_address}}.";
+export const WRITE_NEEDS_LABEL = (label, detail) => `${label} (${detail}) changes the app, so this test must be marked access 'write' ` +
+    "(tests create --access write, or tests set-access <id> write) and clean up in " +
+    "'after'. A 'read' test only reads.";
+export const WRITE_NEEDS_CLOSING_TEARDOWN = (detail) => "A 'write' test must end with an 'after' section that undoes what it changed and " +
+    "proves it: the last step of 'after' is an expect with expect_kind 'gone', 'hidden', " +
+    "'have_count', 'count_delta' (something removed) or 'have_text', 'have_value', " +
+    `'persisted' (something restored). ${detail}`;
 export const OPTIONAL_TEARDOWN_ACTION_MUST_BE_LAST = (label, action) => `${label} (${action}) is optional but not the last step of 'after'. An optional step ` +
     "that misses ends the teardown, so the steps after it would silently not run. Guard " +
     "them with an optional 'wait_for' or 'expect' instead, or move this step to the end.";
@@ -170,10 +177,69 @@ function identityIssues(plan, provisioning) {
         ? [{ path: "(root)", message: MINTED_IDENTITY_NEEDS_TEARDOWN }]
         : [];
 }
+// Same verb list as the server's write_signal (api/app/ta_shared/schemas.py).
+const WRITE_VERBS_RE = /\b(create|save|delete|remove|rename|revoke|enable|disable|invite|add|publish|archive|restore|quarantine|un-quarantine|turn on|turn off|join|decline)\b/i;
+function writeSignal(plan) {
+    if (typeof plan !== "object" || plan === null)
+        return null;
+    const { before, steps: main, after } = plan;
+    if (steps(after).length > 0)
+        return ["after", "a teardown means something was created"];
+    const sectioned = steps(before).length > 0 || steps(after).length > 0;
+    const label = (section, i) => (sectioned ? `${section}[${i}]` : `step[${i}]`);
+    const all = [
+        ...steps(before).map((s, i) => [label("before", i), s]),
+        ...steps(main).map((s, i) => [label("steps", i), s]),
+    ];
+    for (const [where, s] of all) {
+        if (s.action === "upload")
+            return [where, "upload"];
+        if (s.action === "click" && typeof s.selector === "string") {
+            const hit = WRITE_VERBS_RE.exec(s.selector);
+            if (hit)
+                return [where, `click on '${hit[0]}'`];
+        }
+    }
+    return null;
+}
+const TEARDOWN_PROOF_KINDS = new Set([
+    "gone",
+    "hidden",
+    "have_count",
+    "count_delta",
+    "have_text",
+    "have_value",
+    "persisted",
+]);
+function accessIssues(plan, access) {
+    if (access !== "write") {
+        const signal = writeSignal(plan);
+        return signal ? [{ path: "(root)", message: WRITE_NEEDS_LABEL(signal[0], signal[1]) }] : [];
+    }
+    if (typeof plan !== "object" || plan === null)
+        return [];
+    const after = steps(plan.after);
+    if (after.length === 0) {
+        return [{ path: "(root)", message: WRITE_NEEDS_CLOSING_TEARDOWN("This plan has no 'after'.") }];
+    }
+    const last = after[after.length - 1] ?? {};
+    const kind = typeof last.expect_kind === "string" ? last.expect_kind : undefined;
+    if (last.action !== "expect" || !kind || !TEARDOWN_PROOF_KINDS.has(kind)) {
+        const detail = `Its last step is ${String(last.action)}${kind ? ` ${kind}` : ""}.`;
+        return [{ path: "(root)", message: WRITE_NEEDS_CLOSING_TEARDOWN(detail) }];
+    }
+    return [];
+}
 // `provisioning`: the plan is an account's own signup or sign-in plan, the one place
 // {{mailbox_address}} is legal (mirrors the server's validate_editable_plan flag).
+// `access`: the label the plan will be banked with; given, a writing plan needs 'write'.
 export function lintPlan(plan, opts = {}) {
     const issues = validate(plan, ACTION_PLAN_SCHEMA, ACTION_PLAN_SCHEMA, "");
     // The identity rules read a well-formed plan; a shape error is reported alone.
-    return issues.length > 0 ? issues : identityIssues(plan, opts.provisioning === true);
+    if (issues.length > 0)
+        return issues;
+    return [
+        ...identityIssues(plan, opts.provisioning === true),
+        ...(opts.access === undefined ? [] : accessIssues(plan, opts.access)),
+    ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.46.4",
+  "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",