@beryl-so/cli 0.17.0 → 0.22.0

package/dist/local-run.js

@@ -21,12 +21,20 @@ const ISOLATING_CONFIG = (testDir, artifactsDir) => `import { defineConfig } fro
     `  outputDir: ${JSON.stringify(artifactsDir)},\n` +
     `  fullyParallel: false,\n` +
     `});\n`;
+export function scrubText(text, redact) {
+    let out = text;
+    for (const value of redact ?? []) {
+        if (value)
+            out = out.split(value).join("***");
+    }
+    return out;
+}
 export function copyTextScrubbed(src, dest, redact) {
-    if (!redact) {
+    if (!redact?.length) {
         fs.copyFileSync(src, dest);
         return;
     }
-    fs.writeFileSync(dest, fs.readFileSync(src, "utf8").split(redact).join("***"));
+    fs.writeFileSync(dest, scrubText(fs.readFileSync(src, "utf8"), redact));
 }
 const PASSING = new Set(["passed", "expected"]);
 const SKIPPED = new Set(["skipped"]);
@@ -224,8 +232,18 @@ export async function runSpecLocally(opts) {
     // ephemeral run dir.
     const outDir = opts.dir ? path.resolve(opts.dir) : runDir;
     fs.mkdirSync(outDir, { recursive: true });
+    let specContent = opts.spec;
+    if (opts.authSession) {
+        // Mirror the cloud runner's staging: write the session files into the workdir and
+        // point the spec's storageState reference at the absolute path (auth-init.json is
+        // read relative to cwd, which is the run dir — same as the cloud workdir).
+        const storagePath = path.join(runDir, "auth-state.json");
+        fs.writeFileSync(storagePath, opts.authSession.storageState, "utf8");
+        fs.writeFileSync(path.join(runDir, "auth-init.json"), JSON.stringify(opts.authSession.initScripts), "utf8");
+        specContent = specContent.split('"auth-state.json"').join(JSON.stringify(storagePath));
+    }
     const specPath = path.join(runDir, "beryl-local.spec.ts");
-    fs.writeFileSync(specPath, opts.spec);
+    fs.writeFileSync(specPath, specContent);
     const configPath = path.join(runDir, "beryl-local.config.ts");
     const artifactsDir = path.join(outDir, "artifacts");
     fs.writeFileSync(configPath, ISOLATING_CONFIG(runDir, artifactsDir));

package/dist/playwright-install.js

@@ -1,5 +1,7 @@
 import { spawn } from "node:child_process";
+import fs from "node:fs";
 import { createRequire } from "node:module";
+import os from "node:os";
 import path from "node:path";
 // The two commands that turn "nothing Playwright-related installed" into "local runs work":
 // the test runner as a dev dep, then its browser binary. Kept as data so the CLI can both
@@ -7,24 +9,133 @@ import path from "node:path";
 export const INSTALL_TEST_RUNNER = ["npm", "i", "-D", "@playwright/test"];
 export const INSTALL_CHROMIUM = ["npx", "playwright", "install", "chromium"];
 export const PLAYWRIGHT_INSTALL_COMMANDS = `${INSTALL_TEST_RUNNER.join(" ")} && ${INSTALL_CHROMIUM.join(" ")}`;
-// Resolve `@playwright/test` the way Playwright itself will at run time — from the project
-// tree, not from wherever the globally-installed CLI happens to live. `createRequire` rooted
-// at cwd walks up the same node_modules chain, so this is true iff a local run would find it.
+// Resolve from the project tree, not from wherever the globally-installed CLI happens to
+// live — `createRequire` rooted at cwd walks up the same node_modules chain Playwright will.
+const projectRequire = (cwd) => createRequire(path.join(cwd, "package.json"));
 export function hasPlaywrightTest(cwd) {
     try {
-        createRequire(path.join(cwd, "package.json")).resolve("@playwright/test");
+        projectRequire(cwd).resolve("@playwright/test");
         return true;
     }
     catch {
         return false;
     }
 }
-export const INSTALL_PROMPT = `Install local Playwright now (${PLAYWRIGHT_INSTALL_COMMANDS})? [Y/n] `;
+// A local run launches chromium headless, which Playwright serves from a separate
+// `chromium_headless_shell` build (`playwright install chromium` fetches both). That is the
+// only engine a run ever launches, so it is the only one we install or check for.
+const HEADLESS_SHELL = "chromium-headless-shell";
+// Written last by Playwright's downloader, so its presence means a complete browser.
+const INSTALL_MARKER = "INSTALLATION_COMPLETE";
+function playwrightCoreDir(cwd) {
+    const req = projectRequire(cwd);
+    try {
+        return path.dirname(req.resolve("playwright-core/package.json"));
+    }
+    catch {
+        // Not hoisted (pnpm) — look from @playwright/test's own tree instead.
+    }
+    try {
+        const fromRunner = createRequire(req.resolve("@playwright/test"));
+        return path.dirname(fromRunner.resolve("playwright-core/package.json"));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Mirrors playwright-core's registry root: PLAYWRIGHT_BROWSERS_PATH ("0" means inside the
+// package), else the per-platform cache dir. undefined on a platform Playwright doesn't
+// support, where we have no verdict to offer.
+function browsersRoot(coreDir) {
+    const override = process.env.PLAYWRIGHT_BROWSERS_PATH;
+    if (override === "0")
+        return coreDir ? path.join(coreDir, ".local-browsers") : undefined;
+    if (override)
+        return path.resolve(override);
+    const home = os.homedir();
+    if (process.platform === "darwin")
+        return path.join(home, "Library", "Caches", "ms-playwright");
+    if (process.platform === "win32") {
+        const local = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+        return path.join(local, "ms-playwright");
+    }
+    if (process.platform === "linux") {
+        return path.join(process.env.XDG_CACHE_HOME || path.join(home, ".cache"), "ms-playwright");
+    }
+    return undefined;
+}
+// The exact directory this project's Playwright will look in: <root>/<browser name with
+// dashes as underscores>-<revision>, straight out of playwright-core's browsers.json — so a
+// browser downloaded for an older Playwright doesn't read as the one this one needs.
+function wantedChromiumDir(coreDir) {
+    if (!coreDir)
+        return undefined;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(coreDir, "browsers.json"), "utf8"));
+        const entry = parsed.browsers?.find((b) => b.name === HEADLESS_SHELL) ??
+            parsed.browsers?.find((b) => b.name === "chromium");
+        if (!entry?.name || !entry.revision)
+            return undefined;
+        return `${entry.name.replace(/-/g, "_")}-${entry.revision}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+const isComplete = (dir) => fs.existsSync(path.join(dir, INSTALL_MARKER));
+/**
+ * Is the browser binary a local run actually launches present? Without it every test in a
+ * run dies with the same `browserType.launch: Executable doesn't exist` — an environment
+ * problem that reads as a broken suite.
+ */
+export function hasChromiumBrowser(cwd) {
+    const coreDir = playwrightCoreDir(cwd);
+    const root = browsersRoot(coreDir);
+    // Nowhere known to look — say nothing rather than block; the run surfaces Playwright's
+    // own error if it really is missing.
+    if (!root)
+        return true;
+    const wanted = wantedChromiumDir(coreDir);
+    if (wanted)
+        return isComplete(path.join(root, wanted));
+    // Revision unknown (no resolvable playwright-core): any completed chromium build is the
+    // best evidence there is, and guessing wrong only costs an idempotent re-install.
+    try {
+        return fs
+            .readdirSync(root)
+            .some((d) => /^chromium(_headless_shell)?-\d+$/.test(d) && isComplete(path.join(root, d)));
+    }
+    catch {
+        return false;
+    }
+}
+export function playwrightGaps(cwd) {
+    const runner = !hasPlaywrightTest(cwd);
+    // With no runner there is no revision to judge a cached browser against, so the honest
+    // answer is the full install — not the npm half and a second failure right after it.
+    return { runner, browser: runner || !hasChromiumBrowser(cwd) };
+}
+export const anyGap = (gaps) => gaps.runner || gaps.browser;
+export function describeGaps(gaps) {
+    if (gaps.runner && gaps.browser)
+        return "@playwright/test + the Chromium browser";
+    return gaps.browser ? "the Chromium browser" : "@playwright/test";
+}
+/** Only the commands the missing halves need — a present @playwright/test isn't reinstalled. */
+export function installCommandsFor(gaps) {
+    const commands = [
+        ...(gaps.runner ? [INSTALL_TEST_RUNNER.join(" ")] : []),
+        ...(gaps.browser ? [INSTALL_CHROMIUM.join(" ")] : []),
+    ];
+    return commands.length > 0 ? commands.join(" && ") : PLAYWRIGHT_INSTALL_COMMANDS;
+}
+export const installPrompt = (commands) => `Install local Playwright now (${commands})? [Y/n] `;
+export const INSTALL_PROMPT = installPrompt(PLAYWRIGHT_INSTALL_COMMANDS);
 // Ask (default-yes) whether to install. Returns false — not throwing — when there is no answer
 // or the prompt fails, so callers uniformly fall back to printing the install hint.
-export async function confirmInstall(prompt) {
+export async function confirmInstall(prompt, commands = PLAYWRIGHT_INSTALL_COMMANDS) {
     try {
-        return !/^n(o)?$/i.test(await prompt(INSTALL_PROMPT));
+        return !/^n(o)?$/i.test(await prompt(installPrompt(commands)));
     }
     catch {
         return false;

package/dist/registry/index.js

@@ -1,9 +1,10 @@
 import { accountCommands } from "../commands/account.js";
+import { testAccountCommands } from "../commands/accounts.js";
 import { authCommands } from "../commands/auth.js";
 import { configCommands } from "../commands/config-vars.js";
 import { environmentCommands } from "../commands/environments.js";
 import { explorationCommands } from "../commands/explorations.js";
-import { inboxCommands } from "../commands/inboxes.js";
+import { mailboxCommands } from "../commands/mailboxes.js";
 import { initCommands } from "../commands/init.js";
 import { mcpCommands } from "../commands/mcp.js";
 import { projectCommands } from "../commands/projects.js";
@@ -61,7 +62,8 @@ export const commands = [
     ...explorationCommands,
     ...configCommands,
     ...slackCommands,
-    ...inboxCommands,
+    ...mailboxCommands,
+    ...testAccountCommands,
     ...accountCommands,
     ...mcpCommands,
 ].map(withScopeFlags).map(hideFromMcp);

package/dist/schema.generated.js

@@ -25,6 +25,15 @@ export const ACTION_PLAN_SCHEMA = {
             "title": "ActionType",
             "type": "string"
         },
+        "AuthMode": {
+            "description": "How an authenticated test reaches its logged-in start state. The AUTHOR sets\nthis, explicitly, on every plan that sets ``requires_auth`` \u2014 a submitted plan\nthat omits it is rejected, because the wrong guess banks a plan that runs logged\nout and fails somewhere misleading.\n\n``inline`` \u2014 the plan signs itself in: its own steps fill ``{{login_email}}`` /\n``{{login_password}}``, or it rides the project's captured session.\n\n``session`` \u2014 the test's account signs in ONCE per run, ahead of the tests; the\nresulting browser session is proved against a fresh context and then handed to every\nsession-mode test in the run. The plan itself carries NO sign-in steps, so it starts\nwhere the flow it actually tests begins. Requires the account to have a stored\nlogin plan (``accounts set-login``).",
+            "enum": [
+                "inline",
+                "session"
+            ],
+            "title": "AuthMode",
+            "type": "string"
+        },
         "DialogChoice": {
             "enum": [
                 "accept",
@@ -865,6 +874,7 @@ export const ACTION_PLAN_SCHEMA = {
                                     "inbox_address",
                                     "login_email",
                                     "login_password",
+                                    "mailbox_address",
                                     "timestamp",
                                     "unique",
                                     "uuid"
@@ -1130,6 +1140,24 @@ export const ACTION_PLAN_SCHEMA = {
     "$id": "https://api.beryl.so/api/v1/schemas/action-plan.schema.json",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "allOf": [
+        {
+            "$comment": "requires_auth demands an explicit auth_mode \u2014 there is no default. 'inline' when the plan signs itself in, 'session' when it rides its account's once-per-run session and carries no sign-in steps.",
+            "if": {
+                "properties": {
+                    "requires_auth": {
+                        "const": true
+                    }
+                },
+                "required": [
+                    "requires_auth"
+                ]
+            },
+            "then": {
+                "required": [
+                    "auth_mode"
+                ]
+            }
+        },
         {
             "$comment": "The first executed step must be a goto, so the test loads a page before acting (that is before[0] when there is a setup section, else steps[0]).",
             "else": {
@@ -1242,6 +1270,10 @@ export const ACTION_PLAN_SCHEMA = {
             "default": null,
             "title": "Auth Label"
         },
+        "auth_mode": {
+            "$ref": "#/$defs/AuthMode",
+            "default": "inline"
+        },
         "before": {
             "items": {
                 "$ref": "#/$defs/PlanStep"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.17.0",
-  "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
+  "version": "0.22.0",
+  "description": "Beryl on the command line \u2014 projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",
   "homepage": "https://beryl.so/docs/cli",

package/dist/commands/inboxes.js

@@ -1,145 +0,0 @@
-import { extractCode } from "../email-extract.js";
-import { dim, green } from "../output.js";
-import { arg, flagBool, flagNum, flagStr } from "./util.js";
-export const inboxCommands = [
-    {
-        name: "inbox create",
-        summary: "Mint an email inbox that Beryl receives mail for",
-        groupSummary: "Email inboxes for testing flows that send mail — signups, OTPs, receipts.",
-        description: "Creates a receiving address under Beryl's inbound email domain and returns it. " +
-            "Use it wherever a test needs a real, readable mailbox — e.g. as the --email for " +
-            "`beryl signup`, then read the code back with `beryl inbox read --extract-code`. " +
-            "Pass --permanent to mint the workspace's single permanent mailbox (no TTL).",
-        scope: "workspace",
-        flags: [
-            {
-                name: "permanent",
-                type: "boolean",
-                description: "Mint the workspace's permanent mailbox (no TTL); one per workspace",
-            },
-            {
-                name: "ttl-hours",
-                type: "number",
-                description: "Hours before the inbox expires and stops receiving (1-168, default 24; ignored with --permanent)",
-            },
-            { name: "project", type: "string", description: "Attach the inbox to a project id" },
-        ],
-        examples: [
-            "beryl inbox create --json",
-            "beryl inbox create --ttl-hours 2",
-            "beryl inbox create --permanent",
-        ],
-        async run(ctx, input) {
-            const ws = await ctx.requireWorkspace(input);
-            const inbox = (await ctx.client.post(`/workspaces/${ws}/inboxes`, {
-                ttl_hours: flagBool(input, "permanent") ? null : (flagNum(input, "ttl-hours") ?? 24),
-                project_id: flagStr(input, "project") ?? null,
-            }));
-            return {
-                data: inbox,
-                human: `${green("Created")} inbox ${inbox.id}\n\n  ${inbox.address}\n\n` +
-                    dim(`Read it with: beryl inbox read ${inbox.id}`),
-            };
-        },
-    },
-    {
-        name: "inbox list",
-        summary: "List the workspace's inboxes, newest first",
-        description: "Every inbox the workspace has minted with `beryl inbox create`. Expired inboxes " +
-            "stop receiving and are hard-deleted by a background sweep, so they drop off " +
-            "this list shortly after their TTL. Pass --permanent for just the permanent mailbox.",
-        scope: "workspace",
-        flags: [
-            {
-                name: "permanent",
-                type: "boolean",
-                description: "Only the workspace's permanent mailbox (no TTL, not run/project scoped)",
-            },
-        ],
-        async run(ctx, input) {
-            const ws = await ctx.requireWorkspace(input);
-            const query = flagBool(input, "permanent") ? { permanent: true } : undefined;
-            return { data: await ctx.client.get(`/workspaces/${ws}/inboxes`, query) };
-        },
-    },
-    {
-        name: "inbox delete",
-        summary: "Delete an inbox and every email it has received",
-        scope: "workspace",
-        args: [{ name: "inbox-id", description: "Inbox id from `beryl inbox create`", required: true }],
-        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
-        async run(ctx, input) {
-            const ws = await ctx.requireWorkspace(input);
-            const id = arg(input, "inbox-id");
-            await ctx.confirm(`Delete inbox ${id} and its emails?`, flagBool(input, "force"));
-            await ctx.client.del(`/workspaces/${ws}/inboxes/${id}`);
-            return { human: "Deleted." };
-        },
-    },
-    {
-        name: "inbox read",
-        summary: "Read the latest email from an inbox (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 — handy for " +
-            "completing `beryl login --email <addr> --code <code>` unattended. Exits non-zero " +
-            "if nothing arrives before the timeout.",
-        scope: "workspace",
-        args: [{ name: "inbox-id", description: "Inbox id from `beryl inbox create`", 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: "extract-code",
-                type: "boolean",
-                description: "Also return the one-time code found in the email as `code`",
-            },
-        ],
-        examples: [
-            "beryl inbox read ibx_123 --timeout-s 45 --json",
-            "beryl inbox read ibx_123 --subject-contains code --extract-code --json",
-        ],
-        async run(ctx, input) {
-            const ws = await ctx.requireWorkspace(input);
-            const email = (await ctx.client.get(`/workspaces/${ws}/inboxes/${arg(input, "inbox-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"),
-            }));
-            if (!flagBool(input, "extract-code"))
-                return { data: email };
-            return { data: { ...email, code: extractCode(email) } };
-        },
-    },
-    {
-        name: "inbox emails",
-        summary: "List the emails an inbox has received",
-        scope: "workspace",
-        args: [{ name: "inbox-id", description: "Inbox id from `beryl inbox create`", 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 ws = await ctx.requireWorkspace(input);
-            return {
-                data: await ctx.client.get(`/workspaces/${ws}/inboxes/${arg(input, "inbox-id")}/emails`, { since: flagStr(input, "since"), limit: flagNum(input, "limit") }),
-            };
-        },
-    },
-];