@beryl-so/cli 0.14.1 → 0.21.4

package/dist/local-exec.js

@@ -0,0 +1,198 @@
+import fs from "node:fs";
+import path from "node:path";
+import { startEmailPump } from "./email-pump.js";
+import { PlaywrightMissingError, runSpecLocally, } from "./local-run.js";
+// Client-side mirrors of the server's RUN_IMPORT_* caps: stay under them rather than
+// discover them as a 413/422.
+export const IMPORT_MAX_ERROR_LEN = 5000;
+export const IMPORT_MAX_FILE_BYTES = 14 * 1024 * 1024;
+export const IMPORT_MAX_TOTAL_BYTES = 180 * 1024 * 1024;
+export const IMPORT_MAX_FILES = 3600;
+export function toRunEntry(spec, outcome, runError, startedAt, ordinal, redact) {
+    // Mirrors the cloud runner's redact_result: the spec types the secret into the
+    // page, so error text and the DOM snapshot can echo it back — scrub before the
+    // bytes leave this machine. Frames and screenshots are pixels; nothing to scrub.
+    const scrub = (text) => (redact ? text.split(redact).join("***") : text);
+    const scrubBytes = (bytes) => redact && bytes.includes(redact)
+        ? Buffer.from(bytes.toString("utf8").split(redact).join("***"), "utf8")
+        : bytes;
+    const completedAt = new Date().toISOString();
+    const base = {
+        test_case_id: spec.id,
+        started_at: startedAt,
+        completed_at: completedAt,
+        frames: [],
+        frame_urls: [],
+        frame_durations_ms: [],
+        files: [],
+    };
+    if (!outcome) {
+        return {
+            ...base,
+            status: "errored",
+            phase: "main",
+            error_message: scrub(runError ?? "the spec did not run").slice(0, IMPORT_MAX_ERROR_LEN),
+        };
+    }
+    const result = outcome.results[0];
+    const status = result && (result.status === "passed" || result.status === "expected")
+        ? "passed"
+        : "failed";
+    const harvested = outcome.harvested;
+    const entry = {
+        ...base,
+        status,
+        phase: status === "failed" ? (harvested?.phase ?? "main") : "main",
+        ...(result?.error
+            ? { error_message: scrub(result.error).slice(0, IMPORT_MAX_ERROR_LEN) }
+            : {}),
+        ...(result?.duration_ms !== undefined ? { duration_ms: Math.max(0, result.duration_ms) } : {}),
+    };
+    if (!harvested)
+        return entry;
+    // A frame over the per-file cap would force dropping mid-list and shift the
+    // index-aligned url/duration sidecars — drop the whole filmstrip instead.
+    // Drop the inlined sign-in's frames before anything is index-aligned to the stored
+    // plan: `runs explain` zips the plan's steps against these lists, so an off-by-K here
+    // shows every step's screenshot next to the wrong step.
+    const skip = Math.min(spec.inlinedLoginSteps ?? 0, harvested.frames.length);
+    const frames = harvested.frames.slice(skip);
+    if (frames.every((f) => f.length <= IMPORT_MAX_FILE_BYTES)) {
+        frames.forEach((bytes, i) => {
+            const name = `r${ordinal}-frame-${String(i).padStart(3, "0")}.png`;
+            entry.frames.push(name);
+            entry.files.push({ name, bytes });
+        });
+        entry.frame_urls = harvested.frameUrls.slice(skip);
+        entry.frame_durations_ms = harvested.frameDurationsMs.slice(skip);
+    }
+    if (harvested.screenshot && harvested.screenshot.length <= IMPORT_MAX_FILE_BYTES) {
+        entry.screenshot = `r${ordinal}-screenshot.png`;
+        entry.files.push({ name: entry.screenshot, bytes: harvested.screenshot });
+    }
+    if (harvested.domSnapshot && harvested.domSnapshot.length <= IMPORT_MAX_FILE_BYTES) {
+        entry.dom_snapshot = `r${ordinal}-dom.html`;
+        entry.files.push({ name: entry.dom_snapshot, bytes: scrubBytes(harvested.domSnapshot) });
+    }
+    return entry;
+}
+export function buildImportForm(entries, opts) {
+    // Total-size budget: when a big suite would blow past the server's cap, shed whole
+    // filmstrips (largest droppable payload, replay-only) test by test — never
+    // mid-list, and never silently.
+    let total = entries.flatMap((e) => e.files).reduce((n, f) => n + f.bytes.length, 0);
+    for (const entry of entries) {
+        if (total <= IMPORT_MAX_TOTAL_BYTES)
+            break;
+        const frameBytes = entry.files
+            .filter((f) => entry.frames.includes(f.name))
+            .reduce((n, f) => n + f.bytes.length, 0);
+        if (frameBytes === 0)
+            continue;
+        entry.files = entry.files.filter((f) => !entry.frames.includes(f.name));
+        entry.frames = [];
+        entry.frame_urls = [];
+        entry.frame_durations_ms = [];
+        total -= frameBytes;
+        opts.onNote?.(`replay frames for test ${entry.test_case_id} dropped (upload size cap)`);
+    }
+    // File-count budget: the server parses at most RUN_IMPORT_MAX_FILES multipart
+    // parts, so a big suite's filmstrips can overflow on count with bytes to spare.
+    let fileCount = entries.reduce((n, e) => n + e.files.length, 0);
+    for (const entry of entries) {
+        if (fileCount <= IMPORT_MAX_FILES)
+            break;
+        const frameFiles = entry.files.filter((f) => entry.frames.includes(f.name)).length;
+        if (frameFiles === 0)
+            continue;
+        entry.files = entry.files.filter((f) => !entry.frames.includes(f.name));
+        entry.frames = [];
+        entry.frame_urls = [];
+        entry.frame_durations_ms = [];
+        fileCount -= frameFiles;
+        opts.onNote?.(`replay frames for test ${entry.test_case_id} dropped (upload file-count cap)`);
+    }
+    const manifest = {
+        environment_id: opts.environmentId ?? null,
+        target_url_override: opts.targetUrlOverride ?? null,
+        ...(opts.notifications !== undefined ? { notifications: opts.notifications } : {}),
+        started_at: opts.startedAt,
+        completed_at: opts.completedAt,
+        results: entries.map(({ files: _files, ...rest }) => rest),
+    };
+    const form = new FormData();
+    form.append("manifest", JSON.stringify(manifest));
+    for (const entry of entries) {
+        for (const file of entry.files) {
+            form.append("files", new Blob([new Uint8Array(file.bytes)]), file.name);
+        }
+    }
+    return form;
+}
+/**
+ * Run one rendered spec on this machine with its full service harness: write the
+ * inbox/login sidecars and pump `await_email` requests over the API while Playwright
+ * runs. The one local-execution seam shared by `runs local` and the local-verify
+ * `tests create`. {@link PlaywrightMissingError} propagates (environmental — the
+ * caller decides whether to offer an install); any other throw is captured as
+ * `runError` (the spec never ran: an errored result, not a crashed command).
+ */
+export async function executeLocalSpec(deps, opts) {
+    const { spec } = opts;
+    const inbox = spec.email
+        ? {
+            id: spec.email.inbox_id,
+            address: spec.email.address,
+            recipientContains: spec.email.recipient_contains ?? undefined,
+            // NOW, not the mailbox's creation time: it already holds every earlier run's
+            // mail, and an older code served as this run's would pass the step with a value
+            // the app then rejects. Sent as stored_after, which fences on the server's own
+            // INGESTION time and is clamped server-side — `since` compares against the
+            // sender's Date: header, so a fast local clock would fence out mail that arrived.
+            storedAfter: new Date().toISOString(),
+        }
+        : undefined;
+    try {
+        const outcome = await runSpecLocally({
+            spec: spec.content,
+            testName: spec.title,
+            dir: opts.dir,
+            harvest: opts.harvest,
+            redact: spec.usesLoginPassword ? opts.loginPassword : undefined,
+            setup: inbox || (spec.usesLoginPassword && opts.loginPassword !== undefined)
+                ? (runDir) => {
+                    if (inbox)
+                        fs.writeFileSync(path.join(runDir, "email-inbox.json"), JSON.stringify({ address: inbox.address }), "utf8");
+                    if (spec.usesLoginPassword && opts.loginPassword !== undefined)
+                        fs.writeFileSync(path.join(runDir, "run-config.json"), JSON.stringify({ login_password: opts.loginPassword }), "utf8");
+                }
+                : undefined,
+            during: (runDir) => {
+                const pump = inbox
+                    ? startEmailPump({
+                        sidecarPath: path.join(runDir, "email-inbox.json"),
+                        client: deps.client,
+                        workspaceId: deps.workspaceId,
+                        inboxId: inbox.id,
+                        storedAfter: inbox.storedAfter,
+                        recipientContains: inbox.recipientContains,
+                        onEvent: opts.onEvent,
+                    })
+                    : undefined;
+                const extra = opts.onSpawn?.(runDir);
+                return () => {
+                    extra?.();
+                    pump?.stop();
+                };
+            },
+        });
+        return { outcome };
+    }
+    catch (err) {
+        if (err instanceof PlaywrightMissingError)
+            throw err;
+        // The spec never ran (compile error, filtered away) — an errored result the
+        // caller records, not an aborted command.
+        return { runError: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/local-run.js

@@ -21,6 +21,13 @@ const ISOLATING_CONFIG = (testDir, artifactsDir) => `import { defineConfig } fro
     `  outputDir: ${JSON.stringify(artifactsDir)},\n` +
     `  fullyParallel: false,\n` +
     `});\n`;
+export function copyTextScrubbed(src, dest, redact) {
+    if (!redact) {
+        fs.copyFileSync(src, dest);
+        return;
+    }
+    fs.writeFileSync(dest, fs.readFileSync(src, "utf8").split(redact).join("***"));
+}
 const PASSING = new Set(["passed", "expected"]);
 const SKIPPED = new Set(["skipped"]);
 export class PlaywrightMissingError extends Error {
@@ -95,6 +102,105 @@ export function tally(results) {
 function parseReport(reportPath) {
     return parsePlaywrightReport(JSON.parse(fs.readFileSync(reportPath, "utf8")));
 }
+/** How many filmstrip frames the rendered spec will write — the step total a live
+ *  progress bar counts against. 0 when the spec was rendered without frame capture. */
+export function countPlannedFrames(spec) {
+    return spec.match(/frames\/step-\d+\.png/g)?.length ?? 0;
+}
+export function countWrittenFrames(runDir) {
+    try {
+        return fs
+            .readdirSync(path.join(runDir, "frames"))
+            .filter((f) => /^step-\d+\.png$/.test(f)).length;
+    }
+    catch {
+        return 0;
+    }
+}
+const readIfExists = (p) => {
+    try {
+        return fs.readFileSync(p);
+    }
+    catch {
+        return undefined;
+    }
+};
+function findFirstFile(base, test) {
+    let entries;
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(base, entry.name);
+        if (entry.isFile() && test(entry.name))
+            return readIfExists(full);
+        if (entry.isDirectory()) {
+            const nested = findFirstFile(full, test);
+            if (nested)
+                return nested;
+        }
+    }
+    return undefined;
+}
+// Mirrors the cloud runner's workdir harvest (_harvest_frames/_harvest_frame_urls/
+// _harvest_frame_step_durations/_harvest_dom_snapshot/_harvest_phase): the same
+// sorted step-*.png order drives all three frame lists so they stay index-aligned.
+function harvestArtifacts(runDir, artifactsDir) {
+    const framesDir = path.join(runDir, "frames");
+    let framePaths = [];
+    try {
+        framePaths = fs
+            .readdirSync(framesDir)
+            .filter((f) => /^step-\d+\.png$/.test(f))
+            .sort()
+            .map((f) => path.join(framesDir, f));
+    }
+    catch {
+        // no frames dir — spec rendered without capture, or it never got that far
+    }
+    const frames = [];
+    const frameUrls = [];
+    const stamps = [];
+    for (const p of framePaths) {
+        const png = readIfExists(p);
+        if (!png)
+            continue;
+        frames.push(png);
+        frameUrls.push(readIfExists(p.replace(/\.png$/, ".url"))?.toString("utf8").trim() ?? "");
+        const raw = readIfExists(p.replace(/\.png$/, ".ts"))?.toString("utf8").trim();
+        const stamp = raw ? Number(raw) : NaN;
+        stamps.push(Number.isFinite(stamp) ? stamp : null);
+    }
+    const frameDurationsMs = stamps.map((stamp, i) => {
+        if (i === 0)
+            return 0;
+        const prev = stamps[i - 1];
+        return stamp !== null && prev !== null && prev !== undefined
+            ? Math.max(0, stamp - prev)
+            : null;
+    });
+    let phase = "main";
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(runDir, "phase.json"), "utf8"));
+        if (parsed.phase && ["setup", "main", "teardown"].includes(parsed.phase)) {
+            phase = parsed.phase;
+        }
+    }
+    catch {
+        // no phase sidecar — an unsectioned spec
+    }
+    return {
+        frames,
+        frameUrls,
+        frameDurationsMs,
+        screenshot: findFirstFile(artifactsDir, (n) => n.endsWith(".png")),
+        domSnapshot: readIfExists(path.join(runDir, "dom-snapshot.html")),
+        phase,
+    };
+}
 /**
  * Write `spec` next to the caller's project, run it with their local @playwright/test, and
  * parse the JSON report into a structured pass/fail summary. Artifacts + the spec + report land
@@ -109,6 +215,11 @@ export async function runSpecLocally(opts) {
     // /tmp finds no node_modules and every run dies with "Cannot find module '@playwright/test'".
     // A run dir under cwd walks up into the project's node_modules; it's always cleaned up.
     const runDir = fs.mkdtempSync(path.join(cwd, ".beryl-local-"));
+    // The spec's sidecar helpers (__vmInbox/__vmRunConfig) read files via require(),
+    // which dies with "require is not defined" when the surrounding project is
+    // "type": "module" (the spec then compiles as ESM). Scoping the run dir back to
+    // CommonJS matches the cloud workdir; node_modules resolution still walks up.
+    fs.writeFileSync(path.join(runDir, "package.json"), '{"type":"commonjs"}\n');
     // Where the user-facing outputs (artifacts, spec copy, report) go: --dir if asked, else the
     // ephemeral run dir.
     const outDir = opts.dir ? path.resolve(opts.dir) : runDir;
@@ -123,8 +234,19 @@ export async function runSpecLocally(opts) {
     const { command, args: base } = playwrightBase(cwd);
     const args = [...base, `--config=${configPath}`, "--reporter=json"];
     opts.onProgress?.(`Running ${command} ${base.join(" ")} on ${opts.testName}…`);
+    await opts.setup?.(runDir);
+    const stop = opts.during?.(runDir);
     const env = { ...process.env, PLAYWRIGHT_JSON_OUTPUT_NAME: reportPath };
-    const result = await runProcess(command, args, cwd, env);
+    // cwd is the RUN dir, not the project: the spec's relative writes (frames/,
+    // email-inbox.json, dom-snapshot.html, phase.json) must land where we harvest and
+    // clean up, exactly as the cloud runner keys them to its per-run workdir.
+    let result;
+    try {
+        result = await runProcess(command, args, runDir, env);
+    }
+    finally {
+        stop?.();
+    }
     if (looksLikePlaywrightMissing(result)) {
         cleanup();
         throw new PlaywrightMissingError(PLAYWRIGHT_INSTALL_HINT);
@@ -148,14 +270,25 @@ export async function runSpecLocally(opts) {
         cleanup();
         throw new Error(`Playwright ran no tests from the rendered spec.\n${detail}`);
     }
+    const harvested = opts.harvest ? harvestArtifacts(runDir, artifactsDir) : undefined;
     let keptSpec = specPath;
     let keptReport = reportPath;
     if (opts.dir) {
-        // Persist the exact spec + report next to the artifacts before the run dir is removed.
+        // Persist the exact spec + report next to the artifacts before the run dir is removed,
+        // plus the spec's relative writes (filmstrip frames, failure DOM) that live in it.
+        // Text files are scrubbed like the uploaded bytes; frames are pixels.
         keptSpec = path.join(outDir, "beryl-local.spec.ts");
         keptReport = path.join(outDir, "report.json");
         fs.copyFileSync(specPath, keptSpec);
-        fs.copyFileSync(reportPath, keptReport);
+        copyTextScrubbed(reportPath, keptReport, opts.redact);
+        const framesSrc = path.join(runDir, "frames");
+        if (fs.existsSync(framesSrc) && framesSrc !== path.join(outDir, "frames")) {
+            fs.cpSync(framesSrc, path.join(outDir, "frames"), { recursive: true, force: true });
+        }
+        const domSrc = path.join(runDir, "dom-snapshot.html");
+        if (fs.existsSync(domSrc) && domSrc !== path.join(outDir, "dom-snapshot.html")) {
+            copyTextScrubbed(domSrc, path.join(outDir, "dom-snapshot.html"), opts.redact);
+        }
     }
     else {
         // Without --dir the artifacts lived in the run dir we're about to delete, so their paths
@@ -165,5 +298,13 @@ export async function runSpecLocally(opts) {
     }
     cleanup();
     const { passed, failed } = tally(results);
-    return { passed, failed, results, directory: outDir, spec: keptSpec, report: keptReport };
+    return {
+        passed,
+        failed,
+        results,
+        directory: outDir,
+        spec: keptSpec,
+        report: keptReport,
+        ...(harvested ? { harvested } : {}),
+    };
 }

package/dist/output.js

@@ -16,6 +16,25 @@ export function statusColor(status) {
         return yellow(status);
     return status;
 }
+// Humans read "2h ago", not "2026-07-28T09:51:45.921815Z". Past a month the
+// relative form stops being informative, so it falls back to the plain date.
+export function timeAgo(value) {
+    if (!value)
+        return "";
+    const t = new Date(String(value)).getTime();
+    if (Number.isNaN(t))
+        return "";
+    const s = Math.max(0, (Date.now() - t) / 1000);
+    if (s < 60)
+        return "just now";
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m ago`;
+    if (s < 86400)
+        return `${Math.floor(s / 3600)}h ago`;
+    if (s < 30 * 86400)
+        return `${Math.floor(s / 86400)}d ago`;
+    return new Date(t).toISOString().slice(0, 10);
+}
 const MAX_CELL = 60;
 function cell(value) {
     if (value === null || value === undefined)

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/progress.js

@@ -0,0 +1,44 @@
+import { dim } from "./output.js";
+const BAR_WIDTH = 18;
+export function renderProgressLine(state) {
+    const stepFraction = state.stepTotal && state.stepTotal > 0
+        ? Math.min(1, (state.step ?? 0) / state.stepTotal)
+        : 0;
+    const fraction = state.total > 0 ? Math.min(1, (state.done + stepFraction) / state.total) : 0;
+    const filled = Math.round(fraction * BAR_WIDTH);
+    const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
+    const pct = `${Math.round(fraction * 100)}%`.padStart(4);
+    const steps = state.stepTotal && state.stepTotal > 0
+        ? ` · step ${Math.min(state.step ?? 0, state.stepTotal)}/${state.stepTotal}`
+        : "";
+    const tally = state.failed > 0 ? ` · ✓${state.passed} ✗${state.failed}` : ` · ✓${state.passed}`;
+    return `[${bar}]${pct} · test ${Math.min(state.done + 1, state.total)}/${state.total}${tally} · ${state.title}${steps}`;
+}
+/** A single rewriting status line on a TTY; quiet elsewhere (the caller prints
+ *  per-test boundary lines instead, so MCP/CI logs stay readable). */
+export class ProgressBar {
+    stream;
+    lastLen = 0;
+    tty;
+    constructor(stream = process.stderr) {
+        this.stream = stream;
+        this.tty = Boolean(stream.isTTY);
+    }
+    get active() {
+        return this.tty;
+    }
+    update(state) {
+        if (!this.tty)
+            return;
+        const line = renderProgressLine(state);
+        const padded = line.padEnd(this.lastLen);
+        this.lastLen = line.length;
+        this.stream.write(`\r${dim(padded)}`);
+    }
+    clear() {
+        if (!this.tty || this.lastLen === 0)
+            return;
+        this.stream.write(`\r${" ".repeat(this.lastLen)}\r`);
+        this.lastLen = 0;
+    }
+}

package/dist/registry/index.js

@@ -1,10 +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 { credentialCommands } from "../commands/credentials.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";
@@ -62,8 +62,8 @@ export const commands = [
     ...explorationCommands,
     ...configCommands,
     ...slackCommands,
-    ...credentialCommands,
-    ...inboxCommands,
+    ...mailboxCommands,
+    ...testAccountCommands,
     ...accountCommands,
     ...mcpCommands,
 ].map(withScopeFlags).map(hideFromMcp);