@beryl-so/cli 0.17.0 → 0.21.4

package/dist/commands/accounts.js

@@ -0,0 +1,331 @@
+import { ApiError } from "../http.js";
+import { dim, green, table, yellow } from "../output.js";
+import { arg, flagBool, flagStr, projectPath, readJsonFlag } from "./util.js";
+// The stored login plan heals, so a blind overwrite could silently clobber a repair the
+// caller never read. A write cites the hash it read; this turns the server's refusal into
+// the two-step recovery, and treats "you already wrote exactly this" as success.
+function staleLoginResult(err) {
+    if (!(err instanceof ApiError) || err.status !== 409)
+        return undefined;
+    const detail = err.detail;
+    if (typeof detail !== "object" || detail === null || detail.code !== "stale_login_plan")
+        return undefined;
+    return {
+        data: {
+            stale: true,
+            current_hash: detail.current_hash,
+            message: detail.message,
+        },
+        human: (detail.message ?? "This account's login plan changed since you read it.") +
+            `\nCurrent hash: ${detail.current_hash ?? "unknown"}`,
+        exitCode: 1,
+    };
+}
+const accountsPath = (ws, p) => `${projectPath(ws, p)}/test-accounts`;
+function accountTable(rows) {
+    return table(rows.map((a) => ({
+        label: a.identity_label + (a.is_default ? " *" : ""),
+        email: a.email,
+        type: a.type,
+        login: a.login_method,
+        status: a.status,
+        id: a.id,
+    })));
+}
+export const testAccountCommands = [
+    {
+        name: "accounts list",
+        summary: "List the test accounts an environment's tests sign in as",
+        groupDefault: true,
+        groupSummary: "Durable identities on the site under test — what an authenticated test signs in as.",
+        description: "Every test account on the project, with the identity label a plan's `auth_label` " +
+            "names. The row marked * is the default: what a plan gets when it sets " +
+            "requires_auth without an auth_label.",
+        scope: "project",
+        flags: [{ name: "env", type: "string", description: "Only accounts on this environment id" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const rows = (await ctx.client.get(accountsPath(workspaceId, projectId), {
+                environment_id: flagStr(input, "env"),
+            }));
+            if (rows.length === 0)
+                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}}."),
+                };
+            return { data: rows, human: accountTable(rows) };
+        },
+    },
+    {
+        name: "accounts create",
+        summary: "Add a test account — the customer's own, or one Beryl signs up",
+        description: "Two kinds. `--type user_provided` records a dedicated account you already have on " +
+            "the site: pass --email and --password, and it is usable immediately. `--type beryl` " +
+            "reserves one Beryl will sign up itself, addressed at the project mailbox — it starts " +
+            "`pending` and becomes usable after `beryl accounts provision`. " +
+            "The first account an environment gets is its default whatever you pass.",
+        scope: "project",
+        flags: [
+            {
+                name: "type",
+                type: "string",
+                enum: ["user_provided", "beryl"],
+                description: "Whose account this is (default: user_provided when --password is given)",
+            },
+            {
+                name: "label",
+                type: "string",
+                description: "Identity label a plan's auth_label names (default 'default')",
+            },
+            { name: "email", type: "string", description: "user_provided only: the account's email" },
+            {
+                name: "password",
+                type: "string",
+                description: "user_provided only: stored encrypted as a project secret, never returned",
+            },
+            {
+                name: "login-method",
+                type: "string",
+                enum: ["password", "magic_link", "otp"],
+                description: "How tests sign in as it (default password)",
+            },
+            { name: "env", type: "string", description: "Environment id (default: the project's)" },
+            { name: "default", type: "boolean", description: "Make this the environment's default" },
+        ],
+        examples: [
+            "beryl accounts create --email qa@acme.test --password 'hunter2'",
+            "beryl accounts create --type beryl --login-method otp",
+            "beryl accounts create --email admin@acme.test --password 'hunter2' --label admin",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const password = flagStr(input, "password");
+            const account = (await ctx.client.post(accountsPath(workspaceId, projectId), {
+                type: flagStr(input, "type") ?? (password ? "user_provided" : "beryl"),
+                identity_label: flagStr(input, "label") ?? "default",
+                email: flagStr(input, "email") ?? null,
+                password: password ?? null,
+                login_method: flagStr(input, "login-method") ?? null,
+                environment_id: flagStr(input, "env") ?? null,
+                is_default: flagBool(input, "default"),
+            }));
+            const next = account.status === "pending"
+                ? yellow(`\nNot proven yet — run:\n  beryl accounts provision ${account.id} --file <plan.json>\n` +
+                    `with a plan that ends logged in (a signup, or a sign-in if it already exists).`)
+                : "";
+            return {
+                data: account,
+                human: `${green("Created")} test account ${account.id}\n\n${accountTable([account])}${next}`,
+            };
+        },
+    },
+    {
+        name: "accounts provision",
+        summary: "Prove a test account can get in, by replaying a plan that ends logged in",
+        description: "Runs the plan once in a real browser and, if it passes, marks the account ready. " +
+            "The plan is an ordinary ActionPlan that ends logged in — a SIGNUP when the account " +
+            "does not exist yet, or a SIGN-IN when it already does (you created it by hand, or " +
+            "the site already had it). Either proves the same thing, and a sign-in is what every " +
+            "later test will do anyway. Type {{mailbox_address}} into the email field and " +
+            "{{login_password}} into the password field — both resolve at replay time, and an " +
+            "`await_email` step reads the project mailbox, so a verification code works.",
+        scope: "project",
+        args: [{ name: "account-id", description: "Account id from `beryl accounts list`", required: true }],
+        flags: [
+            {
+                name: "file",
+                type: "string",
+                required: true,
+                description: "ActionPlan that ends logged in, as JSON (path, or - for stdin)",
+            },
+        ],
+        examples: [
+            "beryl accounts provision acc_123 --file signup-plan.json",
+            "beryl accounts provision acc_123 --file signin-plan.json",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const account = (await ctx.client.post(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/provision`, { plan: readJsonFlag(input, "file") }));
+            if (account.status !== "ready")
+                return {
+                    data: account,
+                    human: `${yellow("The account could not get in")}: ${account.last_error ?? account.status}`,
+                    exitCode: 1,
+                };
+            return {
+                data: account,
+                human: `${green("Ready")} — ${account.email}\n\n${accountTable([account])}`,
+            };
+        },
+    },
+    {
+        name: "accounts set-login",
+        summary: "Store the sign-in plan a run replays once, plus the probe that proves it",
+        description: "Session mode: instead of every authenticated test signing in for itself, the " +
+            "account signs in ONCE at the start of a run and every test rides that session. " +
+            "This stores the two plans that makes possible.\n\n" +
+            "--file is the SIGN-IN plan (not the signup): it must end logged in. Type " +
+            "{{login_email}} into the email field and {{login_password}} into the password " +
+            "field; an emailed code or magic link arrives at the account's own address, so an " +
+            "`await_email` step reads it with no human involved.\n\n" +
+            "--probe is the liveness check: a two-step plan (goto a gated page, then a POSITIVE " +
+            "assertion that only holds when signed in — the account menu, a 'Sign out' control). " +
+            "It is replayed in a fresh browser carrying only the captured session. It is " +
+            "REQUIRED, and not a formality: assertions like `hidden` and `count 0` all pass " +
+            "against a logged-out page, so without a positive signal a dead session would run " +
+            "every test logged-out and still report the run green.\n\n" +
+            "Storing only stores. Run `beryl accounts check` to prove it against the live app.",
+        scope: "project",
+        args: [
+            { name: "account-id", description: "Account id from `beryl accounts list`", required: true },
+        ],
+        flags: [
+            {
+                name: "file",
+                type: "string",
+                required: true,
+                description: "The sign-in ActionPlan, as JSON (path, or - for stdin)",
+            },
+            {
+                name: "probe",
+                type: "string",
+                required: true,
+                description: "The liveness probe plan, as JSON (path, or - for stdin): goto a gated page, " +
+                    "then assert something only a signed-in user sees",
+            },
+            {
+                name: "base-hash",
+                type: "string",
+                description: "The login_plan_hash from `beryl accounts get-login`. The write is rejected if " +
+                    "the stored plan changed since. Omit only when writing the first plan",
+            },
+        ],
+        examples: [
+            "beryl accounts set-login acc_123 --file signin.json --probe probe.json",
+            "beryl accounts set-login acc_123 --file signin.json --probe probe.json --base-hash 9f2c…",
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            try {
+                const account = (await ctx.client.put(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/login`, {
+                    plan: readJsonFlag(input, "file"),
+                    probe: readJsonFlag(input, "probe"),
+                    base_hash: flagStr(input, "base-hash") ?? null,
+                }));
+                return {
+                    data: account,
+                    human: `${green("Stored")} — ${account.email}\n` +
+                        dim("Now run `beryl accounts check " + account.id + "` to prove it works."),
+                };
+            }
+            catch (err) {
+                const stale = staleLoginResult(err);
+                if (stale)
+                    return stale;
+                throw err;
+            }
+        },
+    },
+    {
+        name: "accounts get-login",
+        summary: "Read the stored sign-in plan, its probe, and the hash a safe write must cite",
+        description: "The login plan is readable, not just writable: it heals, so overwriting without " +
+            "reading first can clobber a repair you never saw. Pass login_plan_hash back as " +
+            "--base-hash on the next `accounts set-login`.",
+        scope: "project",
+        args: [{ name: "account-id", description: "Account id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const login = (await ctx.client.get(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/login`));
+            if (!login.plan)
+                return {
+                    data: login,
+                    human: dim("No login plan stored. Author one by driving the sign-in in a browser, then " +
+                        "`beryl accounts set-login " + login.account_id + " --file … --probe …`."),
+                };
+            return {
+                data: login,
+                human: `${login.identity_label} — session ${login.session_support}\n` +
+                    `hash ${login.login_plan_hash}\n` +
+                    (login.login_verified_at
+                        ? dim(`last proved ${login.login_verified_at}`)
+                        : dim("never proved — run `beryl accounts check`")),
+            };
+        },
+    },
+    {
+        name: "accounts check",
+        summary: "Sign in now and prove the session survives into a fresh browser",
+        description: "Replays the stored sign-in plan, captures the session it produces, then injects " +
+            "that session into a clean browser and runs the probe. Green here is the same green " +
+            "a run gets, because it is the same code path.\n\n" +
+            "A failure tells you which half broke: SESSION_LOGIN_FAILED means the sign-in " +
+            "itself did not complete (fix the plan); SESSION_PROOF_FAILED means the sign-in " +
+            "worked but the session did not survive the move to a fresh browser, so this app " +
+            "keeps its credential somewhere that cannot be carried (a service worker, a " +
+            "WebAuthn binding). In that case the account is marked unsupported and its tests " +
+            "keep signing in inline — degraded, not broken.\n\n" +
+            "Blocks for two browser replays.",
+        scope: "project",
+        args: [{ name: "account-id", description: "Account id", required: true }],
+        examples: ["beryl accounts check acc_123"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const res = (await ctx.client.post(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/check`, {}));
+            if (!res.proved)
+                return {
+                    data: res,
+                    human: `${yellow("Not proved")}: ${res.error ?? res.session_support}`,
+                    exitCode: 1,
+                };
+            return {
+                data: res,
+                human: `${green("Proved")} — ${res.identity_label} signs in and its session survives a fresh browser.`,
+            };
+        },
+    },
+    {
+        name: "accounts update",
+        summary: "Change a test account's password, login method, or default flag",
+        scope: "project",
+        args: [{ name: "account-id", description: "Account id", required: true }],
+        flags: [
+            { name: "email", type: "string", description: "New email" },
+            { name: "password", type: "string", description: "New password (re-marks the account ready)" },
+            {
+                name: "login-method",
+                type: "string",
+                enum: ["password", "magic_link", "otp"],
+                description: "How tests sign in as it",
+            },
+            { name: "default", type: "boolean", description: "Make this the environment's default" },
+        ],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const account = (await ctx.client.patch(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}`, {
+                email: flagStr(input, "email") ?? null,
+                password: flagStr(input, "password") ?? null,
+                login_method: flagStr(input, "login-method") ?? null,
+                is_default: flagBool(input, "default") ? true : null,
+            }));
+            return { data: account, human: accountTable([account]) };
+        },
+    },
+    {
+        name: "accounts delete",
+        summary: "Delete a test account",
+        description: "Removes the identity. Tests naming it in auth_label start failing with a clear " +
+            "reason rather than silently signing in as somebody else.",
+        scope: "project",
+        args: [{ name: "account-id", description: "Account id", required: true }],
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const id = arg(input, "account-id");
+            await ctx.confirm(`Delete test account ${id}?`, flagBool(input, "force"));
+            await ctx.client.del(`${accountsPath(workspaceId, projectId)}/${id}`);
+            return { human: "Deleted." };
+        },
+    },
+];

package/dist/commands/environments.js

@@ -38,7 +38,6 @@ export const environmentCommands = [
                 enum: ["public", "gated"],
                 description: "Whether this environment needs a login",
             },
-            { name: "allow-mutations", type: "boolean", description: "Allow state-changing actions" },
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
@@ -47,7 +46,6 @@ export const environmentCommands = [
                     name: arg(input, "name"),
                     root_url: arg(input, "url"),
                     requires_auth_choice: flagStr(input, "auth") ?? null,
-                    mutation_choice: flagBool(input, "allow-mutations") ? "allow_mutations" : null,
                 }),
             };
         },

package/dist/commands/init.js

@@ -7,7 +7,7 @@ import { loadConfig } from "../config.js";
 import { CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { bold, cyan, dim, green, red, yellow } from "../output.js";
-import { hasPlaywrightTest, installPlaywright, PLAYWRIGHT_INSTALL_COMMANDS, } from "../playwright-install.js";
+import { anyGap, describeGaps, installCommandsFor, installPlaywright, playwrightGaps, } from "../playwright-install.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 import { authCommands } from "./auth.js";
 import { flagStr } from "./util.js";
@@ -82,22 +82,24 @@ function claudeAddHint(name, entry) {
 function cursorUserConfigPath() {
     return path.join(os.homedir(), ".cursor", "mcp.json");
 }
-// Write the skill to one `.../beryl-test/SKILL.md` file. Idempotent: an identical copy is
-// left alone; a customer-EDITED copy is never clobbered — we notice and skip so their
-// changes survive a re-run.
+// 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) {
+    let outcome = "installed";
     if (fs.existsSync(file)) {
-        // Compare with line endings normalized so a CRLF checkout of our own content still
-        // reads as unchanged (not falsely "customized") — we always write LF.
+        // 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))
             return { outcome: "unchanged", file };
-        return { outcome: "customized", file };
+        outcome = "updated";
     }
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, BERYL_TEST_SKILL);
-    return { outcome: "wrote", file };
+    return { outcome, file };
 }
 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`
@@ -107,8 +109,7 @@ const skillLeaf = (root) => path.join(root, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKI
 // `project` both copies stay repo-local (committed, so teammates get them with the repo).
 // `.agents/skills/` is the vendor-neutral location; Claude Code does NOT index it, so the
 // same string also goes to `.claude/skills/`, which Claude Code auto-discovers. Both are
-// written with the same idempotent / never-clobber-a-customer-edit behavior. Existing
-// repo-local copies from earlier inits are left untouched.
+// refreshed to this CLI's version on every run.
 function writeSkills(cwd, scope) {
     const root = scope === "user" ? os.homedir() : cwd;
     return [
@@ -119,21 +120,28 @@ function writeSkills(cwd, scope) {
 // Local authoring drives a real browser via `@playwright/test` + chromium, and the whole
 // authoring workflow (walk the flow first, then bank the plan) depends on it — so the
 // install is mandatory, not offered: missing means install now, no prompt, no opt-out.
-// Never throws — a failed install must not fail `init`, which has already done its wiring;
-// it prints the exact commands to finish by hand instead.
+// Both halves count: the npm package without the browser binary is a real state, and it
+// fails every local run with the same launch error. Never throws — a failed install must not
+// fail `init`, which has already done its wiring; it prints the exact commands instead.
 async function ensureLocalPlaywright(ctx, cwd) {
-    if (hasPlaywrightTest(cwd)) {
-        ctx.err(`${green("✓")} @playwright/test already installed ${dim("(local runs ready)")}`);
+    const gaps = playwrightGaps(cwd);
+    if (!anyGap(gaps)) {
+        ctx.err(`${green("✓")} @playwright/test + Chromium already installed ${dim("(local runs ready)")}`);
         return;
     }
     try {
         await installPlaywright(cwd, (line) => ctx.err(dim(line)));
-        ctx.err(`${green("✓")} Local Playwright installed ${dim("(local runs ready)")}`);
+        // Believe the check, not the exit code — "local runs ready" is only honest if both
+        // halves are actually there afterwards.
+        const left = playwrightGaps(cwd);
+        if (anyGap(left))
+            throw new Error(`${describeGaps(left)} still missing afterwards`);
+        ctx.err(`${green("✓")} ${describeGaps(gaps)} installed ${dim("(local runs ready)")}`);
     }
     catch (err) {
         ctx.err(`${red("✗")} Playwright install failed: ${err.message}`);
         ctx.err(`${dim("•")} Finish the install by hand — local runs and browser authoring need it:\n` +
-            `    ${cyan(PLAYWRIGHT_INSTALL_COMMANDS)}`);
+            `    ${cyan(installCommandsFor(gaps))}`);
     }
 }
 export const initCommands = [
@@ -142,15 +150,17 @@ export const initCommands = [
         summary: "Set up Beryl in this repo — sign in and wire up your coding agent",
         description: "One-command onboarding: signs you in (emailed one-time code) and wires up your coding " +
             "agent. Nothing is detected and nothing is conditional — every run wires the beryl AND " +
-            "playwright MCP servers, installs the authoring skill (user scope: your home " +
+            "playwright MCP servers, writes the authoring skill (user scope: your home " +
             ".agents/skills/ + .claude/skills/, so it follows you into every session; --scope " +
             "project: the repo's own dirs, committed for teammates), and installs @playwright/test " +
             "+ chromium if missing — 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 " +
-            "your site and it resolves the workspace, project, and URL. Safe to re-run; every step " +
-            "is idempotent and skips what is already set up.",
+            "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 " +
+            "up.",
         interactive: true,
         flags: [
             {
@@ -221,10 +231,15 @@ export const initCommands = [
             for (const skill of skills) {
                 const rel = path.relative(cwd, skill.file);
                 const skillWhere = rel.startsWith("..") ? skill.file : rel;
-                if (skill.outcome === "customized")
-                    ctx.err(`${dim("•")} Beryl authoring skill left as-is ${dim(`(${skillWhere} — you edited it; delete it to reinstall)`)}`);
-                else
-                    ctx.err(`${green("✓")} Beryl authoring skill ${skill.outcome === "wrote" ? "installed" : "already installed"} ${dim(skillWhere)}`);
+                const what = skill.outcome === "installed"
+                    ? "installed"
+                    : skill.outcome === "updated"
+                        ? "updated"
+                        : "already current";
+                const where = skill.outcome === "updated"
+                    ? `${skillWhere} (refreshed to this CLI's version)`
+                    : skillWhere;
+                ctx.err(`${green("✓")} Beryl authoring skill ${what} ${dim(where)}`);
             }
             await ensureLocalPlaywright(ctx, cwd);
             const nextSteps = `\n${bold("Beryl is set up — now open your editor and ask Claude to write tests.")}\n` +
@@ -251,10 +266,11 @@ export const initCommands = [
         name: "guide",
         summary: "Print the Beryl test-authoring guide",
         description: "The full guide to authoring durable, healable tests: the ActionPlan shape, outcome " +
-            "assertions, natural-language intent, per-run email inboxes for OTP/signup flows " +
-            "({{inbox_address}} + await_email), and the local run-fix loop. The same content " +
-            "`beryl init` installs as the beryl-test skill — call this before authoring your " +
-            "first plan when no skill is installed (works without logging in).",
+            "assertions, natural-language intent, test accounts and the project mailbox " +
+            "({{login_email}}, {{mailbox_address}}, {{inbox_address}} + await_email), and the " +
+            "local run-fix loop. The same content `beryl init` installs as the beryl-test " +
+            "skill — call this before authoring your first plan when no skill is installed " +
+            "(works without logging in).",
         examples: ["beryl guide"],
         async run() {
             return { human: BERYL_TEST_SKILL };

package/dist/commands/mailboxes.js

@@ -0,0 +1,159 @@
+import { extractCode } from "../email-extract.js";
+import { dim, green, table } from "../output.js";
+import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+const mailboxPath = (ws) => `/workspaces/${ws}/mailboxes`;
+export const mailboxCommands = [
+    {
+        name: "mailbox get",
+        summary: "The project's mailbox address",
+        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.",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const mailbox = (await ctx.client.get(`${projectPath(workspaceId, projectId)}/mailbox`));
+            return {
+                data: mailbox,
+                human: `${mailbox.address}\n\n` +
+                    dim(`Read its mail with: beryl mailbox read ${mailbox.id}`),
+            };
+        },
+    },
+    {
+        name: "mailbox list",
+        summary: "List the project's mailboxes",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const rows = (await ctx.client.get(mailboxPath(workspaceId), {
+                project_id: projectId,
+            }));
+            return {
+                data: rows,
+                human: table(rows.map((m) => ({
+                    address: m.address + (m.is_default ? " *" : ""),
+                    label: m.label ?? "",
+                    id: m.id,
+                }))),
+            };
+        },
+    },
+    {
+        name: "mailbox create",
+        summary: "Add a second mailbox to the project",
+        description: "Only needed when a flow requires two genuinely separate inboxes at the same time " +
+            "— both sides of an invite handshake. For an address the site has not seen before, " +
+            "cite {{inbox_address}} in the plan instead: it aliases the existing mailbox and " +
+            "costs nothing to manage.",
+        scope: "project",
+        flags: [
+            { name: "label", type: "string", description: "What this mailbox is for, e.g. 'invitee'" },
+            { name: "default", type: "boolean", description: "Make it the project's default" },
+        ],
+        examples: ["beryl mailbox create --label invitee"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const mailbox = (await ctx.client.post(mailboxPath(workspaceId), {
+                project_id: projectId,
+                label: flagStr(input, "label") ?? null,
+                is_default: flagBool(input, "default"),
+            }));
+            return {
+                data: mailbox,
+                human: `${green("Created")} mailbox ${mailbox.id}\n\n  ${mailbox.address}`,
+            };
+        },
+    },
+    {
+        name: "mailbox delete",
+        summary: "Delete a mailbox and every email it has received",
+        description: "Destructive: the address is configured into the site under test, so removing it " +
+            "breaks every test that signs in through it.",
+        scope: "project",
+        args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        async run(ctx, input) {
+            const { workspaceId } = await ctx.requireProject(input);
+            const id = arg(input, "mailbox-id");
+            await ctx.confirm(`Delete mailbox ${id} and its emails?`, flagBool(input, "force"));
+            await ctx.client.del(`${mailboxPath(workspaceId)}/${id}`);
+            return { human: "Deleted." };
+        },
+    },
+    {
+        name: "mailbox read",
+        summary: "Read the latest email in a mailbox (waits for one to arrive)",
+        description: "Waits up to --timeout-s for a matching email and returns it (one blocking request; " +
+            "the server caps the wait at 50s — re-run to keep waiting). With --extract-code, " +
+            "also pulls the one-time code (4-8 digits) out of the body/subject. Use " +
+            "--recipient-contains to read only one `+tag` alias's mail when several identities " +
+            "share the mailbox. Exits non-zero if nothing arrives before the timeout.",
+        scope: "project",
+        args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
+        flags: [
+            {
+                name: "timeout-s",
+                type: "number",
+                description: "Seconds to wait for a matching email (0 = don't wait; max 50, default 30)",
+            },
+            { name: "since", type: "string", description: "Only emails received after this ISO timestamp" },
+            { name: "from-contains", type: "string", description: "Only emails whose sender contains this" },
+            {
+                name: "subject-contains",
+                type: "string",
+                description: "Only emails whose subject contains this",
+            },
+            {
+                name: "recipient-contains",
+                type: "string",
+                description: "Only mail delivered to an address containing this (a +tag alias)",
+            },
+            {
+                name: "extract-code",
+                type: "boolean",
+                description: "Also return the one-time code found in the email as `code`",
+            },
+        ],
+        examples: [
+            "beryl mailbox read mbx_123 --timeout-s 45 --json",
+            "beryl mailbox read mbx_123 --subject-contains code --extract-code --json",
+        ],
+        async run(ctx, input) {
+            const { workspaceId } = await ctx.requireProject(input);
+            const email = (await ctx.client.get(`${mailboxPath(workspaceId)}/${arg(input, "mailbox-id")}/emails/latest`, {
+                timeout_s: flagNum(input, "timeout-s"),
+                since: flagStr(input, "since"),
+                from_contains: flagStr(input, "from-contains"),
+                subject_contains: flagStr(input, "subject-contains"),
+                recipient_contains: flagStr(input, "recipient-contains"),
+            }));
+            if (!flagBool(input, "extract-code"))
+                return { data: email };
+            return { data: { ...email, code: extractCode(email) } };
+        },
+    },
+    {
+        name: "mailbox emails",
+        summary: "List the emails a mailbox has received",
+        scope: "project",
+        args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
+        flags: [
+            { name: "since", type: "string", description: "Only emails received after this ISO timestamp" },
+            {
+                name: "limit",
+                type: "number",
+                description: "Return only the most recent N emails (newest first)",
+            },
+        ],
+        async run(ctx, input) {
+            const { workspaceId } = await ctx.requireProject(input);
+            return {
+                data: await ctx.client.get(`${mailboxPath(workspaceId)}/${arg(input, "mailbox-id")}/emails`, { since: flagStr(input, "since"), limit: flagNum(input, "limit") }),
+            };
+        },
+    },
+];