@beryl-so/cli 0.78.0 → 0.92.1

package/dist/commands/tests.js

@@ -1,8 +1,14 @@
 import fs from "node:fs";
 import { UsageError } from "../errors.js";
 import { table } from "../output.js";
-import { arg, argList, flagBool, flagNum, flagStr, flagStrings, inGroup, projectPath, readJsonFlag, } from "./util.js";
+import { arg, argList, flagBool, flagNum, flagStr, flagStrings, inGroup, jsonFileOrInline, projectPath, } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
+const PLAN_FLAG = {
+    name: "plan",
+    type: "json",
+    description: "The plan inline, instead of --file",
+};
+const planInput = (input) => jsonFileOrInline(input, "file", "plan", true);
 const EVENT_VERBS = {
     QUARANTINED: "quarantined",
     UNQUARANTINED: "released from quarantine",
@@ -170,7 +176,7 @@ export const testCommands = [
     },
     {
         name: "tests set-plan",
-        summary: "Replace a test's step plan from a JSON file (creates a new version)",
+        summary: "Replace a test's step plan (creates a new version)",
         description: "Accepts an ActionPlan (the shape `tests plan` returns), including the optional `before` and " +
             "`after` sections. `after` runs on pass and on fail, so cleanup happens even when the " +
             "test goes red. Pass `--description` when the re-authored plan changes what the test " +
@@ -180,7 +186,8 @@ export const testCommands = [
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
-            { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
+            { name: "file", type: "string", description: "Plan JSON file, or - for stdin" },
+            PLAN_FLAG,
             {
                 name: "description",
                 type: "string",
@@ -189,11 +196,16 @@ export const testCommands = [
                     "only if the flow worked. Omit to keep the test's existing intent.",
             },
         ],
-        examples: ["beryl tests plan 4f… > plan.json  # edit, then:", "beryl tests set-plan 4f… --file plan.json"],
+        examples: [
+            "beryl tests plan 4f… > plan.json  # edit, then:",
+            "beryl tests set-plan 4f… --file plan.json",
+            `beryl tests set-plan 4f… --plan '{"steps":[{"action":"goto","url":"/pricing"}]}'`,
+        ],
         async run(ctx, input) {
+            const plan = planInput(input);
             const { workspaceId, projectId } = await ctx.requireProject(input);
             return {
-                data: await ctx.client.patch(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan`, { json_plan: readJsonFlag(input, "file"), description: flagStr(input, "description") }),
+                data: await ctx.client.patch(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan`, { json_plan: plan, description: flagStr(input, "description") }),
             };
         },
     },
@@ -435,11 +447,13 @@ export const testCommands = [
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
-            { name: "file", type: "string", required: true, description: "Plan JSON file, or - for stdin" },
+            { name: "file", type: "string", description: "Plan JSON file, or - for stdin" },
+            PLAN_FLAG,
         ],
         async run(ctx, input) {
+            const plan = planInput(input);
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const res = (await ctx.client.post(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan/recompile`, { json_plan: readJsonFlag(input, "file") }));
+            const res = (await ctx.client.post(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan/recompile`, { json_plan: plan }));
             // Base64 in the JSON output would flood the caller's context — hand the
             // failure screenshot over as image content instead.
             const shot = typeof res.screenshot_b64 === "string" ? res.screenshot_b64 : undefined;
@@ -533,6 +547,8 @@ export const testCommands = [
     {
         name: "tests heal",
         summary: "Turn self-healing on or off for a test",
+        description: "Only matters while the project's self-heal is on (`projects heal on`); it is off " +
+            "by default, and then no test heals.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -582,12 +598,31 @@ export const testCommands = [
     {
         name: "tests export",
         summary: "Export tests as Playwright .spec.ts files in a ZIP",
+        description: "Writes the ZIP to disk. With --inline, nothing is written: the result carries " +
+            "the same files as {files: [{filename, content}]}.",
         scope: "project",
         args: [{ name: "test-ids", description: "One or more test ids", required: true, variadic: true }],
-        flags: [{ name: "out", type: "string", description: "Output file (default beryl-tests.zip)" }],
+        flags: [
+            { name: "out", type: "string", description: "Output file (default beryl-tests.zip)" },
+            {
+                name: "inline",
+                type: "boolean",
+                description: "Return the files in the result instead of writing a ZIP",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const response = (await ctx.client.request("POST", `${projectPath(workspaceId, projectId)}/tests/export`, { body: { test_case_ids: argList(input, "test-ids") }, raw: true }));
+            const ids = argList(input, "test-ids");
+            if (flagBool(input, "inline")) {
+                if (flagStr(input, "out"))
+                    throw new UsageError("pass --out or --inline, not both");
+                const data = (await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests/export`, { test_case_ids: ids }, { format: "json" }));
+                return {
+                    data,
+                    human: data.files.map((f) => `// ${f.filename}\n${f.content}`).join("\n\n"),
+                };
+            }
+            const response = (await ctx.client.request("POST", `${projectPath(workspaceId, projectId)}/tests/export`, { body: { test_case_ids: ids }, raw: true }));
             const out = flagStr(input, "out") ?? "beryl-tests.zip";
             fs.writeFileSync(out, Buffer.from(await response.arrayBuffer()));
             return { data: { written: out }, human: `Wrote ${out}` };

package/dist/commands/util.js

@@ -42,18 +42,50 @@ export function readFileArg(path, label) {
         throw new UsageError(`${label}: cannot read ${path} (${code ?? err.message})`);
     }
 }
-export function readJsonFlag(input, name) {
-    const file = flagStr(input, name);
-    if (!file)
-        throw new UsageError(`--${name} <file> is required`);
-    const text = readFileArg(file, `--${name}`);
+function parseJson(text, label, source) {
     try {
         return JSON.parse(text);
     }
     catch (err) {
-        throw new UsageError(`--${name}: ${file} is not valid JSON (${err.message})`);
+        throw new UsageError(`${label}: ${source} is not valid JSON (${err.message})`);
     }
 }
+export function readJsonFlag(input, name) {
+    const file = flagStr(input, name);
+    if (!file)
+        throw new UsageError(`--${name} <file> is required`);
+    return parseJson(readFileArg(file, `--${name}`), `--${name}`, file);
+}
+/** A `json` flag's value: the object itself (MCP), or on the CLI JSON text, a path, or -
+ *  for stdin. Text opening with { or [ is JSON, never a path. */
+export function jsonFlag(input, name) {
+    const value = input.flags[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        if (typeof value !== "object" || Array.isArray(value)) {
+            throw new UsageError(`--${name} must be a JSON object`);
+        }
+        return value;
+    }
+    const text = value.trim();
+    if (text.startsWith("{") || text.startsWith("["))
+        return parseJson(text, `--${name}`, "the value");
+    return parseJson(readFileArg(value, `--${name}`), `--${name}`, value);
+}
+export function jsonFileOrInline(input, fileFlag, inlineFlag, required) {
+    const hasFile = Boolean(flagStr(input, fileFlag));
+    const hasInline = input.flags[inlineFlag] !== undefined;
+    if (hasFile && hasInline)
+        throw new UsageError(`pass --${fileFlag} or --${inlineFlag}, not both`);
+    if (hasFile)
+        return readJsonFlag(input, fileFlag);
+    if (hasInline)
+        return jsonFlag(input, inlineFlag);
+    if (required)
+        throw new UsageError(`--${fileFlag} or --${inlineFlag} is required`);
+    return undefined;
+}
 export function flagStrings(input, name) {
     const v = input.flags[name];
     return v && v.length > 0 ? v : undefined;

package/dist/commands/watch.js

@@ -196,15 +196,16 @@ export async function watchRun(ctx, ws, project, runId, timeoutMinutes, opts = {
         }
         const done = Math.max(settledCount(lastCounters), printed.size);
         const total = lastCounters.total || knownTotal || "?";
+        const phase = progress.status === "queued" ? "queued" : "running";
         if (tty) {
             spin = (spin + 1) % SPINNER.length;
             const reds = (lastCounters.failed ?? 0) + (lastCounters.errored ?? 0);
-            process.stderr.write(`\r\u001b[2K${SPINNER[spin]} running ${done}/${total} · ` +
+            process.stderr.write(`\r\u001b[2K${SPINNER[spin]} ${phase} ${done}/${total} · ` +
                 `${green(`${lastCounters.passed ?? 0}✓`)} ${reds > 0 ? red(`${reds}✗`) : dim("0✗")}`);
         }
         else if (!ctx.json && Date.now() - lastHeartbeat > HEARTBEAT_MS) {
             lastHeartbeat = Date.now();
-            ctx.err(dim(`still running: ${done}/${total} settled`));
+            ctx.err(dim(`still ${phase}: ${done}/${total} settled`));
         }
     }
     clearStatusLine();

package/dist/config.js

@@ -4,6 +4,8 @@ import os from "node:os";
 import path from "node:path";
 import { CliError } from "./errors.js";
 export const DEFAULT_API_URL = "https://api.beryl.so";
+// Must match SESSION_CAPTURE_EXTENSION_URL in api/app/core/constants.py and the webapp.
+export const SESSION_CAPTURE_EXTENSION_URL = "https://chromewebstore.google.com/detail/beryl/nnjhiapfdhhmmjabnafdaomdmhlolfkp";
 export function withFlagOverrides(config, flags) {
     return {
         ...config,

package/dist/lint.js

@@ -4,6 +4,9 @@ import { ACTION_PLAN_SCHEMA } from "./schema.generated.js";
 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 CREATED_ACCOUNT_NEEDS_TEARDOWN = "This plan signs up a fresh user with create_account, 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 " +
@@ -22,6 +25,8 @@ export const OPTIONAL_TEARDOWN_ACTION_MUST_BE_LAST = (label, action) => `${label
     "them with an optional 'wait_for' or 'expect' instead, or move this step to the end.";
 export const THIRD_PARTY_UNDECLARED = (p) => `third_party_authorize approves the install on ${p}'s consent page, which needs ` +
     `Beryl's ${p} login: add "${p}" to third_party_integrations`;
+export const THIRD_PARTY_WITH_SIGN_IN_AS = "A test that switches accounts with sign_in_as cannot also approve a third party " +
+    "install: the switched-to browser carries no third party login.";
 export const THIRD_PARTY_UNUSED = (p) => `third_party_integrations declares "${p}" but no third_party_authorize step uses it; remove it`;
 const typeOf = (value) => {
     if (value === null)
@@ -155,7 +160,8 @@ 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 INBOX_ADDRESS_RE = /\{\{inbox_address(?:_[2-9])?\}\}/;
+const citesInboxAddress = (step) => Object.values(step).some((v) => typeof v === "string" && INBOX_ADDRESS_RE.test(v));
 const citesMailboxAddress = cites("mailbox_address");
 const TEARDOWN_GUARD_ACTIONS = new Set(["wait_for", "expect"]);
 function optionalPlacementIssues(after) {
@@ -208,6 +214,9 @@ function thirdPartyIssues(plan) {
     const [undeclared] = [...authorized].filter((p) => !declared.has(p)).sort();
     if (undeclared)
         return [{ path: "(root)", message: THIRD_PARTY_UNDECLARED(undeclared) }];
+    if (declared.size > 0 && executed(record).some((s) => s.action === "sign_in_as")) {
+        return [{ path: "(root)", message: THIRD_PARTY_WITH_SIGN_IN_AS }];
+    }
     const [unused] = [...declared].filter((p) => !authorized.has(p)).sort();
     if (unused)
         return [{ path: "third_party_integrations", message: THIRD_PARTY_UNUSED(unused) }];
@@ -260,6 +269,171 @@ const APP_STRING_FIELDS = [
 ];
 const sortedList = (values) => [...values].sort().join(", ");
 const sectionSteps = (plan) => ["before", "steps", "after"].flatMap((section) => steps(plan[section]).map((step, i) => ({ path: `${section}[${i}]`, section, step })));
+// The fresh-address handle a create_account step signs up; an omitted value means
+// {{inbox_address}}. Null for any other step, or a value naming no fresh address.
+const createdHandle = (step) => {
+    if (step.action !== "create_account")
+        return null;
+    if (step.value === undefined || step.value === null)
+        return "inbox_address";
+    if (typeof step.value !== "string")
+        return null;
+    return /^\s*\{\{\s*(inbox_address(?:_[2-9])?)\s*\}\}\s*$/.exec(step.value)?.[1] ?? null;
+};
+// Mirrors the server: recipient names an alias an earlier step typed, on an await_email.
+function recipientIssues(plan) {
+    if (typeof plan !== "object" || plan === null)
+        return [];
+    const typed = new Set();
+    const issues = [];
+    for (const { path, step } of sectionSteps(plan)) {
+        const recipient = step.recipient;
+        if (typeof recipient === "string") {
+            if (step.action !== "await_email") {
+                issues.push({ path, message: "recipient applies only to an await_email step" });
+            }
+            else if (!typed.has(recipient)) {
+                issues.push({
+                    path,
+                    message: `reads mail sent to {{${recipient}}}, but no earlier step types that address ` +
+                        "into the app, so nothing could have been sent to it.",
+                });
+            }
+        }
+        for (const v of Object.values(step)) {
+            if (typeof v !== "string")
+                continue;
+            for (const m of v.matchAll(/\{\{(inbox_address(?:_[2-9])?)\}\}/g)) {
+                if (m[1])
+                    typed.add(m[1]);
+            }
+        }
+        const created = createdHandle(step);
+        if (created)
+            typed.add(created);
+    }
+    return issues;
+}
+// The fields a {{handle}} may be cited in (ALL_HANDLE_REF_FIELDS on the server).
+const HANDLE_REF_FIELDS = ["value", "url", "selector", "option", "expect_text"];
+function citedInboxHandles(step) {
+    const out = [];
+    for (const field of HANDLE_REF_FIELDS) {
+        const v = step[field];
+        if (typeof v !== "string")
+            continue;
+        for (const m of v.matchAll(/\{\{\s*(inbox_address(?:_[2-9])?)\s*\}\}/g)) {
+            if (m[1])
+                out.push(m[1]);
+        }
+    }
+    const created = createdHandle(step);
+    if (created)
+        out.push(created);
+    return out;
+}
+// Mirrors the server: create_account names a fresh address no earlier step typed, sits in
+// before or steps, never inside an account's own sign-in plan, and the test tears down.
+function createAccountIssues(plan, provisioning) {
+    if (typeof plan !== "object" || plan === null)
+        return [];
+    const record = plan;
+    const typed = new Set();
+    const issues = [];
+    let creates = false;
+    for (const { path, section, step } of sectionSteps(record)) {
+        if (!creates &&
+            HANDLE_REF_FIELDS.some((f) => typeof step[f] === "string" && /\{\{\s*created_password\s*\}\}/.test(step[f]))) {
+            issues.push({
+                path,
+                message: "cites {{created_password}}, the password a create_account step signs up with, " +
+                    "but no earlier step is a create_account.",
+            });
+        }
+        if (step.action === "create_account") {
+            creates = true;
+            const handle = createdHandle(step);
+            if (provisioning) {
+                issues.push({
+                    path,
+                    message: "An account's own signup or sign-in plan is what create_account replays, so it " +
+                        "cannot contain one; create_account is for tests.",
+                });
+            }
+            else if (handle === null) {
+                issues.push({
+                    path,
+                    message: "create_account value names the fresh address the new user signs up with: " +
+                        "{{inbox_address}} or {{inbox_address_2}} to {{inbox_address_9}}",
+                });
+            }
+            else if (section === "after") {
+                issues.push({
+                    path,
+                    message: "create_account signs up a user in the teardown; create it in 'before' or 'steps'.",
+                });
+            }
+            else if (typed.has(handle)) {
+                issues.push({
+                    path,
+                    message: `create_account signs up {{${handle}}}, but an earlier step already types that ` +
+                        "address, so that user would sign up twice. Give create_account a fresh handle.",
+                });
+            }
+        }
+        for (const handle of citedInboxHandles(step))
+            typed.add(handle);
+    }
+    if (creates && !provisioning && !steps(record.after).some((s) => s.action !== "expect")) {
+        issues.push({ path: "(root)", message: CREATED_ACCOUNT_NEEDS_TEARDOWN });
+    }
+    return issues;
+}
+// Mirrors the server: account names a test account label or a fresh-address handle the
+// plan types, on a sign_in_as only, and never inside an account's own sign-in plan.
+function signInAsIssues(plan, provisioning) {
+    if (typeof plan !== "object" || plan === null)
+        return [];
+    const all = sectionSteps(plan);
+    const cited = new Set();
+    for (const { step } of all) {
+        for (const handle of citedInboxHandles(step))
+            cited.add(handle);
+    }
+    const issues = [];
+    for (const { path, step } of all) {
+        const account = step.account;
+        if (step.action !== "sign_in_as") {
+            if (account !== undefined && account !== null) {
+                issues.push({ path, message: "account applies only to a sign_in_as step" });
+            }
+            continue;
+        }
+        if (provisioning) {
+            issues.push({
+                path,
+                message: "An account's own signup or sign-in plan acts as that account only; " +
+                    "sign_in_as is for tests.",
+            });
+        }
+        else if (typeof account === "string" && account.includes("{{")) {
+            issues.push({
+                path,
+                message: "sign_in_as account names the account bare (admin, inbox_address_2), not as a {{handle}}",
+            });
+        }
+        else if (typeof account === "string" &&
+            /^inbox_address(?:_[2-9])?$/.test(account) &&
+            !cited.has(account)) {
+            issues.push({
+                path,
+                message: `switches to the fresh user {{${account}}}, but no step types that address ` +
+                    "into the app, so that user is never created.",
+            });
+        }
+    }
+    return issues;
+}
 const appStepRules = (p) => [
     (s) => p === "ios" && s.action === "back"
         ? "is not available on ios: iOS has no back button; tap the app's own back control."
@@ -357,8 +531,8 @@ const COUNT_KINDS = new Set(["gone", "have_count"]);
 // Shorter typed values ("1", "ok") would "name" half the page's buttons.
 const MIN_TYPED_NAME_LEN = 3;
 const SELECTOR_TEXT_RE = /text=["']?([^"'>]+?)["']?\s*(?:>>|$)|(?:has-text|text-is|text)\(\s*["']([^"']+)["']\s*\)|\[(?:name|title|aria-label)\s*[*^$]?=\s*["']([^"']+)["']/g;
-// {{inbox_address}} is minted fresh per execution too, so a record named by it is its own.
-const anchored = (text) => typeof text === "string" && /\{\{\s*(unique|uuid|inbox_address)\s*\}\}/.test(text);
+// A fresh address is minted per execution too, so a record named by one is its own.
+const anchored = (text) => typeof text === "string" && /\{\{\s*(unique|uuid|inbox_address(?:_[2-9])?)\s*\}\}/.test(text);
 const selectorTexts = (selector) => typeof selector === "string"
     ? [...selector.matchAll(SELECTOR_TEXT_RE)].map((m) => m[1] ?? m[2] ?? m[3] ?? "")
     : [];
@@ -417,6 +591,9 @@ export function lintPlan(plan, opts = {}) {
         ...deviceIssues(plan),
         ...thirdPartyIssues(plan),
         ...identityIssues(plan, opts.provisioning === true),
+        ...recipientIssues(plan),
+        ...signInAsIssues(plan, opts.provisioning === true),
+        ...createAccountIssues(plan, opts.provisioning === true),
         ...(opts.access === undefined ? [] : accessIssues(plan, opts.access)),
     ];
 }