@beryl-so/cli 0.43.0 → 0.45.0

package/README.md

@@ -317,6 +317,7 @@ The project's standing email addresses, where its tests receive sign-in mail.
 | --- | --- | --- |
 | `beryl mailbox get` | The project's mailbox address | `mailbox_get` |
 | `beryl mailbox list` | List the project's mailboxes | `mailbox_list` |
+| `beryl mailbox identities` | The +tag addresses Beryl minted for this project's tests, and how each cleanup ended | `mailbox_identities` |
 | `beryl mailbox create` | Add a second mailbox to the project | `mailbox_create` |
 | `beryl mailbox delete <mailbox-id>` | Delete a mailbox and every email it has received | `mailbox_delete` |
 | `beryl mailbox read <mailbox-id>` | Read the latest email in a mailbox (waits for one to arrive) | `mailbox_read` |

package/dist/beryl-test-skill.js

@@ -46,6 +46,12 @@ export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
         { action: "click", selector: "text=Verify" },
         { action: "expect", expect_kind: "visible", selector: "text=Welcome" },
     ],
+    after: [
+        { action: "goto", url: "/account" },
+        { action: "wait_for", selector: "text=Delete account", optional: true },
+        { action: "click", selector: "text=Delete account" },
+        { action: "click", selector: "[role=dialog] button:has-text(\"Delete\")" },
+    ],
 };
 export const BERYL_TEST_SKILL = `---
 name: beryl-test
@@ -238,7 +244,12 @@ never leaves Beryl's cloud).
    handoff, a magic link on another domain).
    Optional \`before\` / \`after\` arrays hold setup and teardown; \`after\` runs even
    when a main step fails, so a create flow can clean up its record — and a deletion
-   flow creates its own record in \`before\` first.
+   flow creates its own record in \`before\` first. A step in \`after\` may carry
+   \`"optional": true\`: if it misses (the record was never created, or is already
+   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\`.
 
    The full action vocabulary:
 
@@ -391,27 +402,27 @@ A flow that emails the user — a signup verification code, a magic sign-in link
 receipt — is testable with the \`await_email\` action. No setup, no configuration, no
 flag to turn on.
 
-**The project has one permanent mailbox and all of its mail arrives there.** Two
-handles put an address on the page; the one you cite decides which *identity* the test
-acts as:
+**The project has one permanent mailbox and all of its mail arrives there.** The
+standing account is used one way only, \`requires_auth: true\` (its session is injected
+before the first step); a test never types its address (the save refuses it), only the
+account's own \`signup\` / \`set-login\` plans fill \`{{mailbox_address}}\`. Every flow that
+sends mail (a signup, a sign-in code, a wrong code, a lockout, a resend timer, an
+invitation) cites \`{{inbox_address}}\`, a \`+tag\` alias minted per execution and read by
+this test alone.
 
-| Handle | Renders as | Use it for |
-|---|---|---|
-| \`{{mailbox_address}}\` | the mailbox's own address, the same every run | signing in as the project's standing test account (§1) |
-| \`{{inbox_address}}\` | a \`+tag\` alias of it, fresh every run | tests whose subject IS getting a NEW identity — a signup, an invited teammate |
+| The test... | Then |
+|---|---|
+| 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 |
 
-An alias is a real address the site has never issued, so a signup is repeatable run
-after run; the mail lands in the same mailbox and Beryl reads only the alias's own
-mail. Nothing expires; there is no second inbox to manage. Default to
-\`{{mailbox_address}}\`; reach for \`{{inbox_address}}\` only when an existing account
-would be rejected — a signup form, an invite accepted as a second person.
+Every alias minted is listed by \`beryl mailbox identities\` with how its teardown ended.
 
 The wiring is a three-part chain:
 
-1. **Type the address into the app** — a \`fill\` with \`value: "{{inbox_address}}"\`
-   (or \`{{mailbox_address}}\`). The alias is fresh every run, so a signup is
-   repeatable by construction — no \`{{unique}}\` needed for the email itself; use it
-   for other must-not-collide values like a username. The generator handles
+1. **Type the address into the app**: a \`fill\` with \`value: "{{inbox_address}}"\`.
+   The alias is fresh every run, so a signup is repeatable by construction, no
+   \`{{unique}}\` needed for the email itself; use it for other must-not-collide
+   values like a username. The generator handles
    \`{{unique}}\`, \`{{uuid}}\`, \`{{timestamp}}\` are each minted once per execution;
    \`{{timestamp}}\` is second-resolution (a time, NOT a uniqueness guarantee —
    \`{{unique}}\` is).

package/dist/commands/accounts.js

@@ -52,7 +52,8 @@ export const testAccountCommands = [
                 return {
                     data: rows,
                     human: dim("No test accounts. Authenticated tests fall back to the LOGIN_EMAIL variable " +
-                        "and LOGIN_PASSWORD secret, or mint a throwaway with {{inbox_address}}."),
+                        "and LOGIN_PASSWORD secret. A flow that must sign up fresh cites " +
+                        "{{inbox_address}} and deletes the account in `after`."),
                 };
             return { data: rows, human: accountTable(rows) };
         },

package/dist/commands/mailboxes.js

@@ -9,9 +9,13 @@ export const mailboxCommands = [
         groupDefault: true,
         groupSummary: "The project's standing email addresses, where its tests receive sign-in mail.",
         description: "Returns the address {{mailbox_address}} resolves to, creating it on first ask. " +
-            "Every test that reads mail receives here. A test needing an address the site has " +
-            "never seen cites {{inbox_address}} instead. That renders a `+tag` alias of this " +
-            "same mailbox, so a signup stays repeatable without a second address to manage.",
+            "Every test that reads mail receives here, at its own `+tag` alias of this mailbox: " +
+            "a plan cites {{inbox_address}}, minted per execution and read by that test alone, " +
+            "so parallel tests never consume each other's codes. A test never types the bare " +
+            "address (the save refuses it); only an account's own signup and sign-in plans " +
+            "(`accounts signup`, `accounts set-login`) may fill it. " +
+            "Every alias minted is listed by `mailbox identities`, and a plan that signs up " +
+            "with one must delete the account in its `after` section.",
         scope: "project",
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -42,6 +46,47 @@ export const mailboxCommands = [
             };
         },
     },
+    {
+        name: "mailbox identities",
+        summary: "The +tag addresses Beryl minted for this project's tests, and how each cleanup ended",
+        description: "Every {{inbox_address}} a run rendered is recorded: which test and run minted it, and " +
+            "what the runner saw of its teardown (clean, skipped, failed, unverified, or none when " +
+            "the plan has no `after` section). This is the list of identities that may still exist " +
+            "on the site under test. Rows are kept for 30 days.",
+        scope: "project",
+        flags: [
+            { name: "run", type: "string", description: "Only addresses minted by this run id" },
+            { name: "test", type: "string", description: "Only addresses minted by this test id" },
+            { name: "limit", type: "number", description: "Newest N rows (default 100, max 500)" },
+        ],
+        examples: ["beryl mailbox identities", "beryl mailbox identities --run run_123 --json"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const rows = (await ctx.client.get(`${mailboxPath(workspaceId)}/identities`, {
+                project_id: projectId,
+                run_id: flagStr(input, "run"),
+                test_id: flagStr(input, "test"),
+                limit: flagNum(input, "limit"),
+            }));
+            if (rows.length === 0) {
+                return {
+                    data: rows,
+                    human: dim("No minted addresses yet. Tests that sign up with {{inbox_address}} appear here."),
+                };
+            }
+            return {
+                data: rows,
+                human: table(rows.map((r) => ({
+                    address: r.address,
+                    teardown: r.teardown_outcome ?? "open",
+                    source: r.source,
+                    test: r.test_case_id ?? "",
+                    run: r.test_run_id ?? "",
+                    minted: r.minted_at,
+                }))),
+            };
+        },
+    },
     {
         name: "mailbox create",
         summary: "Add a second mailbox to the project",

package/dist/commands/tests.js

@@ -82,24 +82,39 @@ export const testCommands = [
         summary: "Validate a plan JSON file offline, before sending it to the server",
         description: "Checks a plan against the published ActionPlan JSON Schema: every action's required " +
             "fields, plus the two structural rules (the first EXECUTED step must be a goto, and at " +
-            "least one step across before + steps must be an expect). Runs entirely locally, so a " +
-            "malformed plan fails here instead of costing a server round-trip. " +
+            "least one step across before + steps must be an expect). Also the identity rules: a " +
+            "plan that signs up with {{inbox_address}} and reads the mail must delete the account " +
+            "in `after`, and no test plan may type {{mailbox_address}} (errors; the server refuses " +
+            "both too). Pass --provisioning for an account's signup or sign-in plan, which may fill " +
+            "{{mailbox_address}}. Runs entirely locally, so a malformed plan fails here instead of " +
+            "costing a server round-trip. " +
             `Schema: ${ACTION_PLAN_SCHEMA.$id}`,
         scope: "none",
         flags: [
             { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
+            {
+                name: "provisioning",
+                type: "boolean",
+                description: "The file is an account's signup or sign-in plan (for `accounts signup` / " +
+                    "`accounts set-login`), so it may fill {{mailbox_address}}",
+            },
+        ],
+        examples: [
+            "beryl tests lint --file plan.json",
+            "beryl tests lint --file signup-plan.json --provisioning",
         ],
-        examples: ["beryl tests lint --file plan.json"],
         async run(_ctx, input) {
-            const issues = lintPlan(readJsonFlag(input, "file"));
-            if (issues.length === 0) {
-                return { data: { valid: true, issues: [] }, human: "Plan is valid." };
+            const issues = lintPlan(readJsonFlag(input, "file"), {
+                provisioning: flagBool(input, "provisioning"),
+            });
+            const lines = issues.map((i) => `${i.severity === "warning" ? "warning" : "error"} ${i.path}: ${i.message}`);
+            if (issues.every((i) => i.severity === "warning")) {
+                return {
+                    data: { valid: true, issues },
+                    human: ["Plan is valid.", ...lines].join("\n"),
+                };
             }
-            return {
-                data: { valid: false, issues },
-                human: issues.map((i) => `${i.path}: ${i.message}`).join("\n"),
-                exitCode: 1,
-            };
+            return { data: { valid: false, issues }, human: lines.join("\n"), exitCode: 1 };
         },
     },
     {

package/dist/lint.js

@@ -1,4 +1,17 @@
 import { ACTION_PLAN_SCHEMA } from "./schema.generated.js";
+// Word for word what the server's save gate says (api/app/ta_shared/schemas.py);
+// keep them identical.
+export const MINTED_IDENTITY_NEEDS_TEARDOWN = "This plan signs up with {{inbox_address}} and reads the mail it triggers, so it " +
+    "leaves an account behind on the site. Add an 'after' section that deletes it " +
+    "through the app (mark steps optional so a missing account ends the teardown quietly).";
+export const MAILBOX_ADDRESS_IN_TEST = "This plan types the standing account's address ({{mailbox_address}}) into the app. " +
+    "A test never signs in that way: one that needs to be signed in sets requires_auth " +
+    "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 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.";
 const typeOf = (value) => {
     if (value === null)
         return "null";
@@ -120,6 +133,47 @@ function validate(value, raw, root, path) {
     }
     return issues;
 }
-export function lintPlan(plan) {
-    return validate(plan, ACTION_PLAN_SCHEMA, ACTION_PLAN_SCHEMA, "");
+const steps = (section) => Array.isArray(section)
+    ? section.filter((s) => typeof s === "object" && s !== null)
+    : [];
+const cites = (handle) => (step) => Object.values(step).some((v) => typeof v === "string" && v.includes(`{{${handle}}}`));
+const citesInboxAddress = cites("inbox_address");
+const citesMailboxAddress = cites("mailbox_address");
+const TEARDOWN_GUARD_ACTIONS = new Set(["wait_for", "expect"]);
+function optionalPlacementIssues(after) {
+    return after.flatMap((s, i) => s.optional === true && !TEARDOWN_GUARD_ACTIONS.has(String(s.action)) && i !== after.length - 1
+        ? [
+            {
+                path: `after[${i}]`,
+                message: OPTIONAL_TEARDOWN_ACTION_MUST_BE_LAST(`after[${i}]`, String(s.action)),
+            },
+        ]
+        : []);
+}
+function identityIssues(plan, provisioning) {
+    if (typeof plan !== "object" || plan === null)
+        return [];
+    const { before, steps: main, after } = plan;
+    const placement = optionalPlacementIssues(steps(after));
+    if (placement.length > 0)
+        return placement;
+    const body = [...steps(before), ...steps(main)];
+    const all = [...body, ...steps(after)];
+    if (!provisioning && all.some(citesMailboxAddress)) {
+        return [{ path: "(root)", message: MAILBOX_ADDRESS_IN_TEST }];
+    }
+    if (!all.some(citesInboxAddress))
+        return [];
+    const readsMail = body.some((s) => s.action === "await_email");
+    const tearsDown = steps(after).some((s) => s.action !== "expect");
+    return readsMail && !tearsDown
+        ? [{ path: "(root)", message: MINTED_IDENTITY_NEEDS_TEARDOWN }]
+        : [];
+}
+// `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).
+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);
 }

package/dist/schema.generated.js

@@ -1050,6 +1050,11 @@ export const ACTION_PLAN_SCHEMA = {
                     "default": null,
                     "title": "Option"
                 },
+                "optional": {
+                    "default": false,
+                    "title": "Optional",
+                    "type": "boolean"
+                },
                 "selector": {
                     "anyOf": [
                         {

package/package.json

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