@bugmole/cli 0.4.0 → 0.6.0

package/scripts/bugmole.ts

@@ -9,6 +9,7 @@ import dotenv from "dotenv";
 import YAML from "yaml";
 import { resolveLocalStorageDirectory } from "../src/storage/storage-directory.js";
 import { adoptLegacyEnv, preferExisting } from "../src/runtime/legacy-names.js";
+import { approvalModeOf, workerApprovalMode, type ApprovalMode } from "../src/registry/task-scheduling.js";
 
 type Mode =
   | "api-key"
@@ -18,16 +19,20 @@ type Mode =
   | "plan"
   | "run"
   | "propose-diff"
+  | "discover"
   | "review"
   | "report"
   | "artifacts"
   | "serve"
   | "gateway"
   | "run-once"
+  | "propose"
+  | "roles"
   | "reset"
   | "cursor-driver"
   | "suite"
-  | "init-env";
+  | "init-env"
+  | "secrets";
 
 function readArg(name: string, argv = process.argv): string | undefined {
   const i = argv.indexOf(name);
@@ -44,23 +49,42 @@ export function parseArgs(argv = process.argv): Record<string, any> {
   if (positionalCommand === "gateway") args.gateway = true;
   if (positionalCommand === "run-once") args.runonce = true;
   if (positionalCommand === "reset") args.reset = true;
+  if (positionalCommand === "roles") args.roles = true;
+  if (positionalCommand === "secrets") args.secrets = true;
+  if (positionalCommand === "propose") {
+    args.propose = true;
+    const file = argv.slice(argv.indexOf("propose") + 1).find((arg) => !arg.startsWith("--"));
+    if (file) args.proposefile = file;
+  }
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg.startsWith("--")) {
-      const key = arg.slice(2).replace(/-/g, "");
+      const name = arg.slice(2);
+      const key = name.replace(/-/g, "");
       const next = argv[i + 1];
       const value = next && !next.startsWith("--") ? next : true;
       if (value !== true) i++;
-      // Try to parse as number or boolean
-      if (value === true || value === "true") args[key] = true;
-      else if (value === "false") args[key] = false;
-      else if (!isNaN(Number(value))) args[key] = Number(value);
-      else args[key] = value;
+      // Only counts and durations become numbers: `--grep 404` or
+      // `--project 2024` are names, and must stay strings.
+      let parsed: unknown;
+      if (value === true || value === "true") parsed = true;
+      else if (value === "false") parsed = false;
+      else if (NUMERIC_FLAGS.has(key.toLowerCase()) && value.trim() !== "" && !isNaN(Number(value))) parsed = Number(value);
+      else parsed = value;
+      args[key] = parsed;
+      // Modes read either spelling: --file-path is args.filepath and args.filePath.
+      const camel = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+      if (camel !== key) args[camel] = parsed;
     }
   }
   return args;
 }
 
+const NUMERIC_FLAGS = new Set([
+  "timeout", "maxpages", "maxdepth", "localregistryport", "artifactport", "gatewayport", "pollinterval",
+  "nudgeinterval", "nudgemaxnudges", "nudgeinactivitythreshold", "nudgeprogressreporttimeout",
+]);
+
 export function printHelp(init = false): void {
   if (init) {
     console.log(`Usage: bugmole init [options]
@@ -70,40 +94,87 @@ Initialize .bugmole/config.yaml and .bugmole.env without reading credentials.
 Options:
   --non-interactive           Use defaults and never prompt
   --force                     Overwrite an existing configuration
-  --storage-provider <name>   local, gcs, s3, or r2
+  --storage-provider <name>   local, bugmole, gcs, s3, or r2
+  --bucket <name>             Bucket for gcs, s3 or r2
+  --region <region>           S3 region
+  --account-id <id>           R2 account ID
+  --cloud-project-id <id>     Google Cloud project for gcs
+  --endpoint <url>            Custom storage endpoint
+  --project-id <id>           Project identifier (default: the folder name)
+  --project-name <name>       Project display name
+  --environment <name>        Environment name (default: local)
+  --spec-dir <folder>         Where flows, plans and roles live (default: ./spec)
   --workspace-id <id>         Workspace identifier
   --workspace-name <name>     Workspace display name
   --app-id <id>               Default app identifier
   --app-name <name>           Default app display name
+  --app-path <folder>         The app's folder in a repository with several apps
+  --app-url <url>             The app's URL (a public one identifies the project by domain)
   --config <path>             Configuration output path
-  --help                      Show this help`);
+  --help                      Show this help
+
+Bugmole tests web apps and mobile apps (Android and iOS). One app is one
+project: a repository's git remote plus the app's folder identify it, so
+teammates who clone the same repository join the same project.`);
     return;
   }
   console.log(`Usage: bugmole [command] [options]
 
 Commands:
   init                        Initialize a project configuration
-  api-key create              Generate a one-time machine API key
+  api-key create              Generate a one-time machine API key (needs a key with keys:write;
+                                the dashboard's API keys page works without one)
+    --name <name>             What the key is for
+    --project-ids <ids>       Comma-separated projects it may use
   --mcp                       Start the MCP server
   artifacts serve             Serve local artifacts to the dashboard over loopback
     --artifact-port <port>    Loopback port (default: 3190)
     --dashboard-origin <url>  Allowed dashboard origin
+  propose <file.json>         Propose test-case changes (add, change, retire) for review;
+                                once accepted each becomes a new revision and the old one obsolete
+  secrets                     List the {{secret.NAME}}s your flows use and where each comes from
+  secrets set <NAME>          Keep a value in this machine's secure store (typed hidden, or piped on stdin)
+  secrets delete <NAME>       Remove it. Or map names to your vault (gcpsm://, awssm://, keychain://,
+                                env://) under secrets: in the config
+  roles                       List the project's roles: confirmed ones are used for test cases and runs
+  roles suggest <name>        Suggest a role for a person to confirm on the dashboard's Roles page
+    --evidence <text>         What points at it (a sign-in wall, a gated route or menu)
+    --description <text>      Who this is and what they can do
+    --from-evidence           Suggest every role the journey graph, blockers and roles.yaml imply
   serve                       Start the local artifact bridge and HTTP MCP server
     --no-open                  Print the dashboard handoff without opening a browser
+    --approval <mode>         manual | auto | extreme: only take tasks this mode would allow.
+                                Stricter than the project's mode, never looser (sets BUGMOLE_APPROVAL).
     --dashboard-url <url>     Dashboard URL for the handoff (overrides BUGMOLE_DASHBOARD_URL)
     --local-registry          Stand in for the real registry locally (overrides BUGMOLE_LOCAL_REGISTRY)
                                 so queueing tasks/runs and this worker executing them works without
-                                a real Aegis login or a BUGMOLE_API_KEY scoped to this project.
+                                signing in or a BUGMOLE_API_KEY scoped to this project.
     --local-registry-port     Local registry stub port (default: 4600, or BUGMOLE_LOCAL_REGISTRY_PORT)
   gateway                     Multiplex project serve workers over loopback
     --gateway-port <port>     Loopback port (default: 3191)
     --gateway-secret <value>  Shared secret for worker registration
   reset                       Delete current-project execution data after confirmation
+    --yes                     Skip the typed confirmation (scripts and CI)
   run-once                    Execute one Bugmole Cloud run and exit (used inside cloud runners;
                                 reads BUGMOLE_REGISTRY_URL, BUGMOLE_RUN_ID, BUGMOLE_RUN_TOKEN)
-  --mode <mode>               explore, plan, run, report, review, propose-diff, or suite
+  --mode <mode>               explore, plan, run, report, review, propose-diff, suite, or discover
+  --app-path <folder>         The app's folder in a repository with several apps
+  --app-url <url>             The app's URL
+  --timeout <ms>              How long a flow may take
+  --mode explore              Learn the app's screens from its source, or by crawling it
+    --base-url <url>          The running app
+  --mode plan                 Write a runnable plan for a journey
+    --journey-id <id>         The journey to plan
+    --actor <role>            A confirmed role to plan it for
+  --mode discover             Click through a running app and write a flow for each page and form
+    --base-url <url>          The running app
+    --out <dir>               Where to write the flows (required)
+    --sign-in <flow>          Sign in with this flow first, to explore the signed-in app
+    --max-pages <n>           Stop after this many pages
+    --max-depth <n>           Follow links at most this many clicks from the start
+    --open-each-page          Open every page directly as well as by clicking
   --mode suite                Run a directory of web flows against a running app
-    --flows <dir>             Flow directory (default: .maestro)
+    --flows <dir>             Flow directory (default: spec/flows, then flows, then .maestro)
     --base-url <url>          Application base URL (or BUGMOLE_BASE_URL)
     --artifacts-dir <dir>     Evidence directory (default: qa/bugmole-runs)
     --project <id>            Project id used in the evidence path
@@ -128,6 +199,9 @@ export function resolveMode(args: Record<string, any>): Mode {
   if (args.gateway === true) return "gateway";
   if (args.runonce === true) return "run-once";
   if (args.reset === true) return "reset";
+  if (args.propose === true) return "propose";
+  if (args.roles === true) return "roles";
+  if (args.secrets === true) return "secrets";
   if (args.artifacts === true) return "artifacts";
   return (args.mode ?? "mcp") as Mode;
 }
@@ -137,9 +211,10 @@ export function resolveMode(args: Record<string, any>): Mode {
 // step needs it to fail the build, so `--mode run` is the one mode whose exit code
 // reflects the result rather than just whether the process threw.
 export function runModeExitCode(mode: string, result: unknown): number {
-  if (mode !== "run") return 0;
   const status = result && typeof result === "object" ? (result as { status?: unknown }).status : undefined;
-  return status === "success" ? 0 : 1;
+  // A run passes only when it all passed; the other modes fail on an error.
+  if (mode === "run") return status === "success" ? 0 : 1;
+  return status === "error" ? 1 : 0;
 }
 
 export function shouldOpenServeBrowser(
@@ -209,6 +284,19 @@ export function resolveLocalRegistryEnabled(args: Record<string, any>): boolean
 // every fetch with "bad port" — 4190 is the reserved ManageSieve port).
 const DEFAULT_LOCAL_REGISTRY_PORT = 4600;
 
+/**
+ * `--approval manual|auto|extreme` for `bugmole serve`. It becomes
+ * BUGMOLE_APPROVAL so every part of this process (worker, MCP, the coding
+ * agent driver) holds back the same tasks. Returns null for a bad value.
+ */
+export function applyApprovalFlag(args: Record<string, any>, env: Record<string, string | undefined> = process.env): ApprovalMode | undefined | null {
+  if (args.approval === undefined) return workerApprovalMode(env);
+  const mode = approvalModeOf(typeof args.approval === "string" ? args.approval.trim() : "");
+  if (!mode) return null;
+  env.BUGMOLE_APPROVAL = mode;
+  return mode;
+}
+
 export function resolveLocalRegistryPort(args: Record<string, any>): number {
   if (typeof args.localregistryport === "number") return args.localregistryport;
   const fromEnv = process.env.BUGMOLE_LOCAL_REGISTRY_PORT?.trim();
@@ -351,6 +439,13 @@ async function main() {
   if (positionalCommand === "artifacts") args.artifacts = true;
   if (positionalCommand === "serve") args.serve = true;
   if (positionalCommand === "reset") args.reset = true;
+  if (positionalCommand === "roles") args.roles = true;
+  if (positionalCommand === "secrets") args.secrets = true;
+  if (positionalCommand === "propose") {
+    args.propose = true;
+    const file = process.argv.slice(process.argv.indexOf("propose") + 1).find((arg) => !arg.startsWith("--"));
+    if (file) args.proposefile = file;
+  }
   // quiet: dotenv 17 prints an "injected env" banner on every load, which
   // would land in the middle of this CLI's own output.
   dotenv.config({ path: preferExisting(".bugmole.env", ".valk.env"), quiet: true });
@@ -384,29 +479,38 @@ async function main() {
 
   // Init must run from the caller's workspace, not the package directory.
   if (resolveMode(args) === "init") {
-    const { runInitWizard } = await import("../src/runtime/init-wizard.js");
-    await runInitWizard({
-      nonInteractive: args.noninteractive === true,
-      force: args.force === true,
-      configPath: args.config,
-      workspaceId: args.workspaceid,
-      workspaceName: args.workspacename,
-      projectId: args.projectid,
-      projectName: args.projectname,
-      appId: args.appid,
-      appName: args.appname,
-      environment: args.environment,
-      specDir: args.specdir,
-      evidenceManifest: args.evidencemanifest,
-      evidenceScreenshots: args.evidencescreenshots,
-      artifactsDir: args.artifactsdir,
-      storageProvider: args.storageprovider,
-      bucket: args.bucket,
-      region: args.region,
-      endpoint: args.endpoint,
-      cloudProjectId: args.cloudprojectid,
-      accountId: args.accountid,
-    });
+    const { runInitWizard, PlanLimitError, describePlanLimit } = await import("../src/runtime/init-wizard.js");
+    try {
+      await runInitWizard({
+        nonInteractive: args.noninteractive === true,
+        force: args.force === true,
+        configPath: args.config,
+        workspaceId: args.workspaceid,
+        workspaceName: args.workspacename,
+        projectId: args.projectid,
+        projectName: args.projectname,
+        appId: args.appid,
+        appName: args.appname,
+        environment: args.environment,
+        specDir: args.specdir,
+        evidenceManifest: args.evidencemanifest,
+        evidenceScreenshots: args.evidencescreenshots,
+        artifactsDir: args.artifactsdir,
+        storageProvider: args.storageprovider,
+        bucket: args.bucket,
+        region: args.region,
+        endpoint: args.endpoint,
+        cloudProjectId: args.cloudprojectid,
+        accountId: args.accountid,
+        appPath: typeof args.apppath === "string" ? args.apppath : undefined,
+        appUrl: typeof args.appurl === "string" ? args.appurl : undefined,
+      });
+    } catch (error) {
+      // A plan limit is an answer, not a crash: say what the plan allows and where to upgrade.
+      if (!(error instanceof PlanLimitError)) throw error;
+      console.error(describePlanLimit(error));
+      process.exitCode = 1;
+    }
     return;
   }
 
@@ -448,23 +552,56 @@ async function main() {
     return;
   }
 
+  // Suite and discover run without a project configuration, but use its
+  // secrets: map when there is one, so flows can type values from a vault.
+  const flowSecrets = async (projectId: string) => {
+    const { secretMap } = await import("../src/runtime/secret-sources.js");
+    const { withFlowSecrets } = await import("../src/runtime/secret-driver.js");
+    let cfg: { secrets?: unknown; project?: { id?: string } } | null = null;
+    try {
+      if (fs.existsSync(path.resolve(workspaceRoot, configPath))) cfg = loadConfig(path.resolve(workspaceRoot, configPath));
+    } catch {
+      cfg = null;
+    }
+    const { map, problems } = secretMap(cfg);
+    for (const problem of problems) console.warn(`[Bugmole] ${problem}`);
+    const id = cfg?.project?.id ?? projectId;
+    return (driver: import("../src/runtime/driver.js").AppDriver) => withFlowSecrets(driver, { map, projectId: id });
+  };
+
   // A web suite is deterministic: it needs a running app and flow files, not
   // an LLM or a project configuration, so it runs in any workspace as-is.
   if (mode === "suite") {
     const { runWebSuite } = await import("../src/runtime/web-suite.js");
+    let configured: { project?: { id?: string }; runtime?: { spec_dir?: string } } | null = null;
+    try {
+      if (fs.existsSync(path.resolve(workspaceRoot, configPath))) configured = loadConfig(path.resolve(workspaceRoot, configPath));
+    } catch {
+      configured = null;
+    }
+    // Evidence goes under the project's ID, so reset finds it.
+    const suiteProject = typeof args.project === "string" ? args.project : configured?.project?.id ?? path.basename(workspaceRoot);
+    // The first flows folder that exists: spec/flows (where the docs put
+    // them), flows/, then .maestro.
+    const specFlows = path.join(configured?.runtime?.spec_dir ?? "spec", "flows");
+    const defaultFlows = [specFlows, "flows", ".maestro"].find((dir) => fs.existsSync(path.resolve(workspaceRoot, dir)));
+    if (typeof args.flows !== "string" && !defaultFlows) {
+      throw new Error(`No flows folder found (looked for ${specFlows}, flows and .maestro). Pass --flows <dir>.`);
+    }
     const { targetsFromFlags } = await import("../src/runtime/browser-matrix.js");
     const baseUrl = typeof args.baseurl === "string" ? args.baseurl : process.env.BUGMOLE_BASE_URL;
     if (!baseUrl) throw new Error("--base-url (or BUGMOLE_BASE_URL) is required for --mode suite");
     const report = await runWebSuite({
-      flowsDir: path.resolve(workspaceRoot, typeof args.flows === "string" ? args.flows : ".maestro"),
+      flowsDir: path.resolve(workspaceRoot, typeof args.flows === "string" ? args.flows : defaultFlows!),
       baseUrl,
       artifactsDir: path.resolve(workspaceRoot, typeof args.artifactsdir === "string" ? args.artifactsdir : preferExisting(path.join(workspaceRoot, "qa/bugmole-runs"), path.join(workspaceRoot, "qa/valkyrie-runs"))),
-      projectId: typeof args.project === "string" ? args.project : path.basename(workspaceRoot),
+      projectId: suiteProject,
       headless: args.headed !== true,
       timeoutMs: typeof args.timeout === "number" ? args.timeout : undefined,
       grep: typeof args.grep === "string" ? args.grep : undefined,
       shareSession: args.sharesession === true,
       targets: targetsFromFlags(args.browsers, args.devices),
+      wrapDriver: await flowSecrets(suiteProject),
     });
     const { total, passed, failed, blocked } = report.totals;
     console.log(`[Bugmole] Suite ${passed}/${total} passed (${failed} failed, ${blocked} blocked). Report: ${report.reportPath}`);
@@ -472,6 +609,81 @@ async function main() {
     return;
   }
 
+  // Explores a running app like a first-time visitor and writes a flow for
+  // every page and form it finds, ready for --mode suite. With --sign-in, that
+  // flow runs first and exploration continues in its session, which is
+  // deleted afterwards.
+  if (mode === "discover") {
+    const { discoverSite } = await import("../src/runtime/site-discovery.js");
+    const baseUrl = typeof args.baseurl === "string" ? args.baseurl : process.env.BUGMOLE_BASE_URL;
+    if (!baseUrl) throw new Error("--base-url (or BUGMOLE_BASE_URL) is required for --mode discover");
+    if (typeof args.out !== "string") throw new Error("--out <directory> is required for --mode discover");
+    const outDir = path.resolve(workspaceRoot, args.out);
+    const sessionDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "bugmole-discover-"));
+    try {
+      let storageState: string | undefined;
+      if (typeof args.signin === "string") {
+        const { PlaywrightDriver } = await import("../src/runtime/playwright-driver.js");
+        storageState = path.join(sessionDir, "session-state.json");
+        const projectId = typeof args.project === "string" ? args.project : path.basename(workspaceRoot);
+        const signIn = await (await flowSecrets(projectId))(new PlaywrightDriver({ headless: args.headed !== true })).run({
+          runId: `discover-${Date.now()}`,
+          projectId: typeof args.project === "string" ? args.project : path.basename(workspaceRoot),
+          journeyId: "sign-in",
+          flowPath: path.resolve(workspaceRoot, args.signin),
+          platform: "web",
+          target: { baseUrl },
+          rebaseOrigin: true,
+          timeoutMs: typeof args.timeout === "number" ? args.timeout : 30_000,
+          artifactsDir: path.join(sessionDir, "artifacts"),
+          sessionStatePath: storageState,
+        });
+        if (signIn.status !== "passed") throw new Error(`Sign-in flow did not pass: ${signIn.message}`);
+        console.log(`[Bugmole] Signed in with ${args.signin}`);
+      }
+      const result = await discoverSite(baseUrl, {
+        storageState,
+        openEachPage: args.openeachpage === true,
+        maxPages: typeof args.maxpages === "number" ? args.maxpages : undefined,
+        maxDepth: typeof args.maxdepth === "number" ? args.maxdepth : undefined,
+        headless: args.headed !== true,
+        onEvent: (event) => {
+          if (event.kind !== "click") console.log(`[discover] ${event.text}`);
+        },
+      });
+      await fs.promises.mkdir(outDir, { recursive: true });
+      for (const flow of result.flows) {
+        await fs.promises.writeFile(path.join(outDir, path.basename(flow.file)), flow.content, "utf8");
+      }
+      await fs.promises.writeFile(
+        path.join(outDir, "discovery.json"),
+        `${JSON.stringify({
+          baseUrl: result.baseUrl,
+          pages: result.pages.map(({ route, heading, title, path: via }) => ({ route, heading, title, via })),
+          limits: result.limits,
+          events: result.events,
+        }, null, 2)}\n`,
+        "utf8",
+      );
+      // Flows found signed in only pass signed in: put the sign-in flow first
+      // in the folder, so a suite with --share-session signs in, then runs them.
+      if (typeof args.signin === "string") {
+        await fs.promises.copyFile(path.resolve(workspaceRoot, args.signin), path.join(outDir, "00-sign-in.yaml"));
+      }
+      const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? "" : "s"}`;
+      const outName = path.relative(workspaceRoot, outDir) || ".";
+      console.log(`[Bugmole] Discovered ${plural(result.pages.length, "page")} and wrote ${plural(result.flows.length, "flow")} to ${outName}`);
+      if (result.flows.length) {
+        console.log(`[Bugmole] Run them: bugmole --mode suite --flows ${outName} --base-url ${baseUrl}${typeof args.signin === "string" ? " --share-session" : ""}`);
+      }
+      if (result.pages.length === 0) process.exitCode = 1;
+    } finally {
+      // Holds the app's cookies and tokens: never outlives the exploration.
+      await fs.promises.rm(sessionDir, { recursive: true, force: true });
+    }
+    return;
+  }
+
   const cfg = loadConfig(configPath);
 
   if (mode === "reset") {
@@ -489,7 +701,13 @@ async function main() {
   // Serve only needs the local runtime/storage and registry settings. Full
   // execution validation belongs to plan/run modes, which require LLM and
   // browser configuration that an idle worker does not use.
-  if (mode !== "serve" && mode !== "artifacts" && mode !== "explore") {
+  if (mode === "secrets") {
+    const { runSecretsCommand } = await import("../src/runtime/secrets-cli.js");
+    process.exitCode = await runSecretsCommand(cfg, process.argv, { workspaceRoot });
+    return;
+  }
+
+  if (mode !== "serve" && mode !== "artifacts" && mode !== "explore" && mode !== "roles") {
     const { validateConfigOrThrow } = await import("../src/runtime/config-validate.js");
     validateConfigOrThrow(cfg);
   }
@@ -503,7 +721,36 @@ async function main() {
 
   // Dispatch modes
   switch (mode) {
+    case "roles": {
+      const { parseRolesCommand, runRolesCommand } = await import("../src/runtime/roles-cli.js");
+      const command = parseRolesCommand(process.argv, args);
+      if ("error" in command) {
+        console.error(command.error);
+        process.exit(2);
+      }
+      for (const line of await runRolesCommand(cfg, command)) console.log(`[Bugmole] ${line}`);
+      return;
+    }
+    case "propose": {
+      if (typeof args.proposefile !== "string") {
+        console.error("Usage: bugmole propose <changes.json>");
+        process.exit(2);
+      }
+      const { proposeFromFile } = await import("../src/runtime/propose-cli.js");
+      const proposals = await proposeFromFile(cfg, args.proposefile);
+      for (const proposal of proposals) {
+        const state = proposal.status === "pending" ? "waiting for a manager's review" : proposal.status;
+        console.log(`[Bugmole] ${proposal.action} ${proposal.caseSetId}/${proposal.caseId}: ${state} (${proposal.id})`);
+      }
+      return;
+    }
     case "serve": {
+      const approval = applyApprovalFlag(args);
+      if (approval === null) {
+        console.error("[Bugmole] --approval must be manual, auto or extreme");
+        process.exit(2);
+      }
+      if (approval) console.log(`[Bugmole] Approval: ${approval}. This worker waits for a person's approval on ${approval === "manual" ? "every task" : approval === "auto" ? "tasks that change code" : "nothing"}, whatever the project allows.`);
       const remoteStorage = Boolean(cfg.storage?.provider && cfg.storage.provider !== "local");
       let closeBridge: () => void = () => {};
       if (remoteStorage) {
@@ -542,7 +789,7 @@ async function main() {
         console.log(`[Bugmole] MCP will start on the configured HTTP port`);
         console.log(`[Bugmole] Capability expires at ${bridge.expiresAt}`);
         if (!process.env.BUGMOLE_AEGIS_EMAIL?.trim()) {
-          console.warn("[Bugmole] No BUGMOLE_AEGIS_EMAIL found; enter your Aegis email on the login page to generate rid.");
+          console.warn("[Bugmole] Sign in with your Bugmole account email on the page that opens.");
         }
         console.log(
           `[Bugmole] Dashboard handoff: ${buildDashboardHandoffUrl(dashboardHandoff.toString(), cfg.project?.id ?? "default", fragment)}`,
@@ -651,7 +898,7 @@ async function startMcpServerForServe(cfg: any): Promise<void> {
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   main().catch((err) => {
-    console.error(`[Bugmole MCP] fatal: ${err?.message ?? err}`);
+    console.error(`[Bugmole] ${err?.message ?? err}`);
     process.exit(1);
   });
 }

package/scripts/ensure-playwright.cjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Downloads the browsers Bugmole runs tests in, since the `playwright` package
+// installs only the library: without this, the first `bugmole run` or
+// `bugmole serve` on a new machine stops with "Chromium is not installed".
+// Runs as a postinstall step next to ensure-maestro.cjs, and like it never
+// fails the parent `npm install` — this is best-effort.
+//
+// It uses the package's own Playwright, so the browsers always match the
+// version Bugmole drives. Edge is left out: installing it needs admin rights
+// (sudo on Linux, a system package on macOS), so it stays a one-line opt-in.
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+// Chromium, Firefox and WebKit (Safari) are the browsers a run targets by
+// default; ffmpeg is what records a run's video.
+const BROWSERS = ["chromium", "firefox", "webkit", "ffmpeg"];
+
+function log(message) {
+  console.log(`[bugmole postinstall] ${message}`);
+}
+
+function skipReason(env = process.env) {
+  if (env.BUGMOLE_SKIP_PLAYWRIGHT_INSTALL === "true") return "BUGMOLE_SKIP_PLAYWRIGHT_INSTALL=true";
+  // A CI job that runs Bugmole's tests asks for the browsers explicitly.
+  if (env.BUGMOLE_PLAYWRIGHT_INSTALL === "true") return null;
+  // Playwright's own switch, which CI images and Docker builds already set.
+  if (env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD && env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD !== "0") return "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is set";
+  // CI installs dependencies on every job; several hundred MB of browsers
+  // each time is wasted unless the job runs tests, and then it says so.
+  if (env.CI && env.CI !== "false" && env.CI !== "0") return "running in CI";
+  return null;
+}
+
+// Playwright doesn't export its CLI, so find it the way npm does: through
+// the `bin` its package.json declares.
+function playwrightCli() {
+  try {
+    const manifest = require.resolve("playwright/package.json");
+    const bin = require(manifest).bin;
+    const entry = typeof bin === "string" ? bin : bin && bin.playwright;
+    return entry ? path.join(path.dirname(manifest), entry) : null;
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const reason = skipReason();
+  if (reason) {
+    log(`Skipping Playwright browser install (${reason}). Set BUGMOLE_PLAYWRIGHT_INSTALL=true to install them anyway, or later: npx playwright install ${BROWSERS.join(" ")}`);
+    return;
+  }
+  const cli = playwrightCli();
+  if (!cli) {
+    log("Playwright is not installed next to Bugmole, so there are no browsers to fetch yet.");
+    return;
+  }
+  log(`Installing Playwright browsers (${BROWSERS.join(", ")}). Already-installed ones are skipped.`);
+  const install = spawnSync(process.execPath, [cli, "install", ...BROWSERS], {
+    stdio: "inherit",
+    timeout: 10 * 60 * 1000,
+  });
+  if (install.error || install.status !== 0) {
+    log(
+      "Automatic browser install failed. Runs report the missing browser until it is installed: " +
+        `npx playwright install ${BROWSERS.join(" ")}`,
+    );
+    if (process.platform === "linux") {
+      log("On Linux the browsers also need system libraries: sudo npx playwright install-deps");
+    }
+    return;
+  }
+  log("Playwright browsers are ready. For Edge as well: npx playwright install msedge (needs admin rights).");
+  if (process.platform === "linux") {
+    log("If a browser fails to start on Linux, install its system libraries: sudo npx playwright install-deps");
+  }
+}
+
+module.exports = { BROWSERS, playwrightCli, skipReason };
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    log(`Skipping Playwright browser install after unexpected error: ${error.message}`);
+  }
+}

package/scripts/ensure-playwright.test.ts

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const { BROWSERS, playwrightCli, skipReason } = require("./ensure-playwright.cjs") as {
+  BROWSERS: string[];
+  playwrightCli: () => string | null;
+  skipReason: (env: Record<string, string | undefined>) => string | null;
+};
+
+test("installing the CLI fetches the browsers a run targets by default, plus ffmpeg for video", () => {
+  assert.deepEqual(BROWSERS, ["chromium", "firefox", "webkit", "ffmpeg"]);
+  assert.ok(!BROWSERS.includes("msedge"), "Edge needs admin rights, so it stays opt-in");
+  const pkg = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")) as { scripts: Record<string, string> };
+  assert.match(pkg.scripts.postinstall, /ensure-playwright\.cjs/);
+});
+
+test("the browser download is skipped in CI and when either skip switch is set", () => {
+  assert.equal(skipReason({}), null);
+  assert.equal(skipReason({ CI: "false" }), null);
+  assert.match(skipReason({ CI: "true" }) ?? "", /CI/);
+  assert.match(skipReason({ BUGMOLE_SKIP_PLAYWRIGHT_INSTALL: "true" }) ?? "", /BUGMOLE_SKIP_PLAYWRIGHT_INSTALL/);
+  assert.match(skipReason({ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "1" }) ?? "", /PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD/);
+  assert.equal(skipReason({ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: "0" }), null);
+  assert.equal(skipReason({ CI: "true", BUGMOLE_PLAYWRIGHT_INSTALL: "true" }), null, "a CI job that runs tests can ask for the browsers");
+  assert.match(skipReason({ BUGMOLE_PLAYWRIGHT_INSTALL: "true", BUGMOLE_SKIP_PLAYWRIGHT_INSTALL: "true" }) ?? "", /SKIP/, "an explicit skip still wins");
+});
+
+test("finds Playwright's CLI even though the package doesn't export it", () => {
+  const cli = playwrightCli();
+  assert.ok(cli && cli.endsWith("cli.js"), `expected Playwright's cli.js, got ${cli}`);
+});

package/scripts/sync-byok.d.mts

@@ -0,0 +1,2 @@
+export const byokCopy: string;
+export const BYOK_HEADER: string;

package/scripts/sync-byok.mjs

@@ -0,0 +1,18 @@
+// Vendors Arcana's bring-your-own-vault resolver (packages/byok/src/byok.ts
+// in theaiinc/arcana) into src/vendor/byok.ts, verbatim under a header. It is
+// one dependency-free file, so the CLI ships it without the Arcana app.
+//   ARCANA_DIR=~/arcana node scripts/sync-byok.mjs
+import { readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "..");
+export const byokCopy = path.join(root, "src/vendor/byok.ts");
+export const BYOK_HEADER = "// VENDORED from theaiinc/arcana packages/byok/src/byok.ts by `node scripts/sync-byok.mjs` — change it there, then sync.\n";
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const arcana = process.env.ARCANA_DIR ?? path.join(os.homedir(), "arcana");
+  const source = await readFile(path.join(arcana, "packages/byok/src/byok.ts"), "utf8");
+  await writeFile(byokCopy, BYOK_HEADER + source);
+  console.log(`Wrote ${path.relative(root, byokCopy)} from ${arcana}`);
+}