@beryl-so/cli 0.46.3 → 0.47.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

@@ -97,10 +97,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 +152,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 +270,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 +442,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/runs.js

@@ -557,11 +557,10 @@ export const runCommands = [
             "which keeps the output readable rather than saving a round trip. With --page the " +
             "match total and page counts come back under results_page. Paged results are the run's " +
             "settled tests only: anything still running, healing or queued is left out. A result " +
-            "carries `heal` when Beryl tried to repair it: `healed` (steps rewritten with the intent " +
-            "unchanged, proved in a browser, re-ran green; `version_no` is the revision it wrote, " +
-            "see `tests diff`) or `heal_failed` (the repair did not restore the flow, so the app " +
-            "changed), with the agent's rationale. The run's `summary` counts both as `healed` and " +
-            "`heal_failed`. " +
+            "carries `heal` when Beryl healed it: its steps were rewritten with the intent " +
+            "unchanged, proved in a browser and it re-ran green; `version_no` is the revision it " +
+            "wrote (see `tests diff`) and `rationale` the agent's reason. A heal that did not turn " +
+            "the test green is not reported: a failure is a failure. " +
             "`runs report` returns the generated report document, `runs explain` an AI explanation " +
             "of one failed result.",
         scope: "project",

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

@@ -180,7 +180,6 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
         total: run?.total_tests ?? settledCount(lastCounters),
         flaky: run?.summary?.flaky ?? 0,
         healed: run?.summary?.healed ?? 0,
-        heal_failed: run?.summary?.heal_failed ?? 0,
     };
     const finalStatus = failFastStop ? "failed" : (run?.status ?? "unknown");
     // Quarantined reds are excluded from `failed` by the API (they land in their own
@@ -193,8 +192,7 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
     const extra = (counters.cancelled ? yellow(`, ${counters.cancelled} cancelled`) : "") +
         (counters.quarantined ? yellow(`, ${counters.quarantined} quarantined`) : "") +
         (counters.flaky ? yellow(`, ${counters.flaky} flaky`) : "") +
-        (counters.healed ? yellow(`, ${counters.healed} healed`) : "") +
-        (counters.heal_failed ? yellow(`, ${counters.heal_failed} heal failed`) : "");
+        (counters.healed ? yellow(`, ${counters.healed} healed`) : "");
     const summary = failed > 0
         ? red(`${failed} failed`) + `, ${passed} passed` + extra
         : green(`${passed} passed`) + extra;

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.3",
+  "version": "0.47.0",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",