@bugmole/cli 0.4.0

package/scripts/bugmole.ts

@@ -0,0 +1,657 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+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";
+
+type Mode =
+  | "api-key"
+  | "init"
+  | "mcp"
+  | "explore"
+  | "plan"
+  | "run"
+  | "propose-diff"
+  | "review"
+  | "report"
+  | "artifacts"
+  | "serve"
+  | "gateway"
+  | "run-once"
+  | "reset"
+  | "cursor-driver"
+  | "suite"
+  | "init-env";
+
+function readArg(name: string, argv = process.argv): string | undefined {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  return undefined;
+}
+
+export function parseArgs(argv = process.argv): Record<string, any> {
+  const args: Record<string, any> = {};
+  const positionalCommand = argv.slice(2).find((arg) => !arg.startsWith("--"));
+  if (positionalCommand === "init") args.init = true;
+  if (positionalCommand === "artifacts") args.artifacts = true;
+  if (positionalCommand === "serve") args.serve = true;
+  if (positionalCommand === "gateway") args.gateway = true;
+  if (positionalCommand === "run-once") args.runonce = true;
+  if (positionalCommand === "reset") args.reset = true;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2).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;
+    }
+  }
+  return args;
+}
+
+export function printHelp(init = false): void {
+  if (init) {
+    console.log(`Usage: bugmole init [options]
+
+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
+  --workspace-id <id>         Workspace identifier
+  --workspace-name <name>     Workspace display name
+  --app-id <id>               Default app identifier
+  --app-name <name>           Default app display name
+  --config <path>             Configuration output path
+  --help                      Show this help`);
+    return;
+  }
+  console.log(`Usage: bugmole [command] [options]
+
+Commands:
+  init                        Initialize a project configuration
+  api-key create              Generate a one-time machine API key
+  --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
+  serve                       Start the local artifact bridge and HTTP MCP server
+    --no-open                  Print the dashboard handoff without opening a browser
+    --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.
+    --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
+  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 suite                Run a directory of web flows against a running app
+    --flows <dir>             Flow directory (default: .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
+    --grep <text>             Only run flows whose file name contains <text>
+    --share-session           Keep one signed-in session across the suite
+    --headed                  Run with a visible browser
+    --browsers <list>         Run on several browsers in parallel: chromium, firefox, webkit, msedge
+    --devices <list>          Also emulate devices, e.g. "iPhone 15,Pixel 7"
+  --mode run                  Execute a published plan
+    --plan-id <id>            Plan to run
+    --base-url <url>          Run against this environment URL instead of the plan's
+    --browsers, --devices     Same matrix flags as --mode suite
+  --help                      Show this help
+
+Aliases: bugmole and bm`);
+}
+
+export function resolveMode(args: Record<string, any>): Mode {
+  if (args.init === true) return "init";
+  if (args.mcp === true) return "mcp";
+  if (args.serve === true) return "serve";
+  if (args.gateway === true) return "gateway";
+  if (args.runonce === true) return "run-once";
+  if (args.reset === true) return "reset";
+  if (args.artifacts === true) return "artifacts";
+  return (args.mode ?? "mcp") as Mode;
+}
+
+// `run` never throws on a failed or blocked target (see src/runtime/executor.ts) — it
+// reports that in `result.status` so the caller can decide what a failure means. A CI
+// 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;
+}
+
+export function shouldOpenServeBrowser(
+  args: Record<string, any>,
+  env: Record<string, string | undefined> = process.env,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (args.noopen === true) return false;
+  // A headless machine (CI, a cloud container) has no browser to open.
+  if (env.CI?.trim() === "true" || env.BUGMOLE_HEADLESS?.trim() === "true") return false;
+  if (platform === "linux" && !env.DISPLAY?.trim() && !env.WAYLAND_DISPLAY?.trim()) return false;
+  return true;
+}
+
+export function resolveDashboardUrl(args: Record<string, any> = {}): string {
+  if (args.dashboardurl === true) {
+    throw new Error("--dashboard-url requires a URL");
+  }
+  const configuredUrl =
+    typeof args.dashboardurl === "string" && args.dashboardurl.trim()
+      ? args.dashboardurl.trim()
+      : process.env.BUGMOLE_DASHBOARD_URL?.trim() || "https://app.bugmole.com";
+  try {
+    return new URL(configuredUrl).toString();
+  } catch {
+    throw new Error(`Invalid dashboard URL: ${configuredUrl}`);
+  }
+}
+
+/**
+ * The local artifact bridge's CORS allowlist must match whatever origin the
+ * printed handoff link actually sends the browser to. `--dashboard-origin`
+ * remains an explicit override for when the two legitimately differ (e.g. a
+ * proxy in front of the dashboard); otherwise this defaults to the resolved
+ * dashboard URL's own origin instead of silently staying production and
+ * CORS-blocking every non-default dashboard.
+ */
+export function resolveDashboardOrigin(args: Record<string, any>, dashboardUrl: string): string {
+  if (typeof args.dashboardorigin === "string" && args.dashboardorigin.trim()) {
+    return args.dashboardorigin.trim();
+  }
+  return new URL(dashboardUrl).origin;
+}
+
+/**
+ * A project with no real registered access (no BUGMOLE_API_KEY scoped to
+ * it) has every registry write rejected — "Explore this app", "Queue
+ * task", and "Run tests" all 403, and `bugmole serve`'s own worker
+ * never starts ("Worker idle: registry URL, API key, and project id are
+ * required"). `--local-registry`/BUGMOLE_LOCAL_REGISTRY opts into a
+ * loopback-only stand-in registry (`src/runtime/local-registry-stub.ts`)
+ * instead, so the full local write→claim→execute loop works without real
+ * Aegis credentials. Explicit opt-in, default off, so `bugmole serve` against
+ * a project that DOES have real registry access keeps using it unchanged.
+ */
+export function resolveLocalRegistryEnabled(args: Record<string, any>): boolean {
+  if (args.localregistry === true) return true;
+  if (args.localregistry === false) return false;
+  return process.env.BUGMOLE_LOCAL_REGISTRY?.trim() === "true";
+}
+
+// Fixed (not random) so a dashboard's .env.local pointing BUGMOLE_REGISTRY_URL
+// here keeps working across restarts without regenerating it each session —
+// unlike the artifact bridge's port, this one isn't handed to the dashboard
+// via a freshly-printed handoff link every time. Chosen off the Fetch
+// spec's forbidden-port list (4190, an earlier default, silently failed
+// every fetch with "bad port" — 4190 is the reserved ManageSieve port).
+const DEFAULT_LOCAL_REGISTRY_PORT = 4600;
+
+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();
+  return fromEnv ? Number(fromEnv) : DEFAULT_LOCAL_REGISTRY_PORT;
+}
+
+/**
+ * Aegis's device-passkey flow binds a `deviceId` to one tenant permanently
+ * (`deviceBinding` is unique per `(tenantId, deviceId)`) — a second claim
+ * attempt for the same id fails with `device_already_claimed` forever after,
+ * it does not expire or reset. `deviceId` used to be `cfg.project?.id`,
+ * which for this repo's own `.bugmole/config.yaml` is the fixed literal
+ * `"bugmole"`: the same string for every checkout, every teammate, and
+ * every re-run of `bugmole serve` from this project. The first successful
+ * onboarding permanently claims that id, so literally anyone's second
+ * attempt — a different machine, a different person, or the same person
+ * after restarting `bugmole serve` — collides with it. A device id needs to
+ * identify one physical machine, not one project name, so this generates a
+ * random one on first use and persists it outside the repo (survives
+ * `git clean`, shared by every project run from this machine, matching how
+ * a device passkey is actually scoped to one machine's secure enclave).
+ */
+export function resolveDeviceId(options: { stateDir?: string } = {}): string {
+  const override = process.env.BUGMOLE_DEVICE_ID?.trim();
+  if (override) return override;
+  const stateDir = options.stateDir ?? preferExisting(path.join(os.homedir(), ".bugmole"), path.join(os.homedir(), ".valkyrie"));
+  const statePath = path.join(stateDir, "device-id");
+  try {
+    const existing = fs.readFileSync(statePath, "utf-8").trim();
+    if (existing) return existing;
+  } catch {
+    // No cached device id yet (or the state dir doesn't exist) — generate one below.
+  }
+  const generated = crypto.randomUUID();
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(statePath, `${generated}\n`, { mode: 0o600 });
+  } catch {
+    // Best-effort persistence: if the cache can't be written, this run still
+    // gets a valid device id, it just won't be remembered for next time.
+  }
+  return generated;
+}
+
+export function buildDashboardHandoffUrl(
+  dashboardUrl: string,
+  projectId: string,
+  fragment: URLSearchParams,
+): string {
+  const handoff = new URL(dashboardUrl);
+  handoff.searchParams.set("project", projectId);
+  handoff.hash = fragment.toString();
+  return handoff.toString();
+}
+
+function requireEnv(key: string): string {
+  const v = process.env[key];
+  if (!v) throw new Error(`Missing required env var: ${key}`);
+  return v;
+}
+
+// tiny ${ENV} interpolator for yaml configs
+// Supports ${VAR:-default} syntax for default values
+function interpolateEnv(obj: any): any {
+  if (typeof obj === "string") {
+    return obj.replace(/\$\{([A-Z0-9_]+)(?::-([^}]+))?\}/g, (_, k, defaultValue) => {
+      const envValue = process.env[k];
+      if (envValue !== undefined && envValue !== "") {
+        return envValue;
+      }
+      return defaultValue !== undefined ? defaultValue : "";
+    });
+  }
+  if (Array.isArray(obj)) return obj.map(interpolateEnv);
+  if (obj && typeof obj === "object") {
+    const out: any = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = interpolateEnv(v);
+    return out;
+  }
+  return obj;
+}
+
+function loadConfig(configPath: string) {
+  const raw = fs.readFileSync(configPath, "utf-8");
+  const parsed = YAML.parse(raw);
+  return interpolateEnv(parsed);
+}
+
+function generateEnvExample() {
+  const envExample = `# --- LLM / Agent Provider ---
+LLM_PROVIDER=openai
+LLM_API_KEY=REPLACE_ME
+LLM_MODEL=gpt-4o-mini
+
+# Optional: if your provider uses these
+LLM_BASE_URL=
+LLM_ORG=
+LLM_PROJECT=
+
+# --- Runtime ---
+BUGMOLE_ENV=sandbox
+BUGMOLE_WORKSPACE_ID=default
+BUGMOLE_RUN_ID_PREFIX=local
+
+# --- Artifacts ---
+BUGMOLE_ARTIFACTS_DIR=./runs
+BUGMOLE_SPEC_DIR=./spec
+
+# --- MCP (optional) ---
+MCP_ENABLED=true
+MCP_HOST=127.0.0.1
+MCP_PORT=3187
+
+# --- Playwright ---
+PLAYWRIGHT_HEADLESS=true
+PLAYWRIGHT_BASE_URL=http://localhost:3000
+
+# --- Cursor Driver (optional) ---
+# Project directory to open in Cursor before testing
+# If specified, will open a new Cursor window in this directory
+CURSOR_PROJECT_DIRECTORY=
+`;
+
+  const envPath = ".env.example";
+  if (fs.existsSync(envPath)) {
+    console.log(`[Bugmole MCP] ${envPath} already exists. Skipping generation.`);
+    return;
+  }
+
+  fs.writeFileSync(envPath, envExample, "utf-8");
+  console.log(`[Bugmole MCP] Generated ${envPath}`);
+  console.log("[Bugmole MCP] Copy it to .env and fill in your LLM_API_KEY");
+}
+
+async function main() {
+  const args = parseArgs();
+  const positionalCommand = process.argv.slice(2).find((arg) => !arg.startsWith("--"));
+  if (positionalCommand === "init") args.init = true;
+  if (positionalCommand === "api-key") args.apikey = true;
+  if (positionalCommand === "artifacts") args.artifacts = true;
+  if (positionalCommand === "serve") args.serve = true;
+  if (positionalCommand === "reset") args.reset = true;
+  // 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 });
+  adoptLegacyEnv();
+  if (args.help === true) {
+    printHelp(positionalCommand === "init");
+    return;
+  }
+
+  if (args.apikey === true) {
+    if (process.argv.includes("create") === false) {
+      throw new Error("Usage: bugmole api-key create --name <machine-name>");
+    }
+    const registryUrl =
+      process.env.BUGMOLE_REGISTRY_URL?.trim() || "https://api.bugmole.com";
+    const apiKey = requireEnv("BUGMOLE_API_KEY");
+    const { createRemoteApiKey } = await import("../src/registry/api-key-client.js");
+    const key = await createRemoteApiKey({
+      registryUrl,
+      aegisId: "api-key-client",
+      apiKey,
+      name: String(args.name ?? "bugmole-client"),
+      projectIds: args.projectids ? String(args.projectids).split(",").filter(Boolean) : undefined,
+      expiresAt: args.expiresat ? String(args.expiresat) : undefined,
+    });
+    console.log(`API key created: ${key.id}`);
+    console.log("Store this token securely. It will not be shown again:");
+    console.log(key.token);
+    return;
+  }
+
+  // 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,
+    });
+    return;
+  }
+
+  // Keep relative config, spec, and artifact paths rooted at the caller's
+  // workspace. The init wizard writes project configuration there.
+  const workspaceRoot = path.resolve(process.env.BUGMOLE_WORKSPACE || process.cwd());
+  process.chdir(workspaceRoot);
+
+  const mode = resolveMode(args);
+  if (mode === "gateway") {
+    const { startServeGateway } = await import("../src/runtime/serve-gateway.js");
+    const gateway = await startServeGateway({
+      port: args.gatewayport ? Number(args.gatewayport) : undefined,
+      secret: typeof args.gatewaysecret === "string" ? args.gatewaysecret : undefined,
+    });
+    console.log(`[Bugmole] Serve gateway listening at ${gateway.origin}`);
+    console.log(`[Bugmole] Gateway secret: ${gateway.secret}`);
+    const stop = () => void gateway.close();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    await new Promise<void>(() => undefined);
+    return;
+  }
+  if (mode === "run-once") {
+    const { runOnce } = await import("../src/runtime/run-once.js");
+    // Exit outright: browsers a stopped run left behind must not keep the container alive.
+    process.exit(await runOnce());
+  }
+  const configPath =
+    args.config ??
+    process.env.BUGMOLE_CONFIG ??
+    [".bugmole/config.yaml", ".valkyrie/config.yaml", "bugmole.config.yaml", "valkyrie.config.yaml"]
+      .find((candidate) => fs.existsSync(path.join(workspaceRoot, candidate))) ??
+    "bugmole.config.yaml";
+
+  // Special mode: generate .env.example
+  if (mode === "init-env") {
+    generateEnvExample();
+    return;
+  }
+
+  // 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");
+    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"),
+      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),
+      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),
+    });
+    const { total, passed, failed, blocked } = report.totals;
+    console.log(`[Bugmole] Suite ${passed}/${total} passed (${failed} failed, ${blocked} blocked). Report: ${report.reportPath}`);
+    if (failed > 0 || blocked > 0) process.exitCode = 1;
+    return;
+  }
+
+  const cfg = loadConfig(configPath);
+
+  if (mode === "reset") {
+    const { confirmProjectReset, resetProjectData } = await import("../src/runtime/reset.js");
+    const projectId = cfg.project?.id ?? "default";
+    if (args.yes !== true && !(await confirmProjectReset(projectId))) {
+      console.log("[Bugmole] Reset cancelled.");
+      return;
+    }
+    await resetProjectData(cfg);
+    console.log(`[Bugmole] Reset execution data for project ${projectId}.`);
+    return;
+  }
+
+  // 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") {
+    const { validateConfigOrThrow } = await import("../src/runtime/config-validate.js");
+    validateConfigOrThrow(cfg);
+  }
+
+  // Local storage needs a directory; remote providers create objects lazily.
+  if (!cfg.storage || cfg.storage.provider === "local") {
+    fs.mkdirSync(cfg.runtime.artifacts_dir, { recursive: true });
+    fs.mkdirSync(resolveLocalStorageDirectory(cfg), { recursive: true });
+  }
+  fs.mkdirSync(cfg.runtime.spec_dir, { recursive: true });
+
+  // Dispatch modes
+  switch (mode) {
+    case "serve": {
+      const remoteStorage = Boolean(cfg.storage?.provider && cfg.storage.provider !== "local");
+      let closeBridge: () => void = () => {};
+      if (remoteStorage) {
+        // A cloud worker writes evidence straight to remote storage. The loopback bridge only serves
+        // a local artifacts directory to a dashboard on the same machine, so it has nothing to do here.
+        console.log(`[Bugmole] Remote storage (${cfg.storage.provider}): local artifact bridge and dashboard handoff are off`);
+      } else {
+        const dashboardUrl = resolveDashboardUrl(args);
+        const { startLocalArtifactServer } = await import("../src/storage/local-artifact-server.js");
+        const bridge = await startLocalArtifactServer({
+          directory: resolveLocalStorageDirectory(cfg),
+          projectId: cfg.project?.id ?? "default",
+          aegisEmail: process.env.BUGMOLE_AEGIS_EMAIL?.trim(),
+          port: args.artifactport ? Number(args.artifactport) : undefined,
+          // --dashboard-url/BUGMOLE_DASHBOARD_URL previously only changed the
+          // printed handoff link; the bridge's CORS allowlist stayed the
+          // production origin regardless, so any non-default dashboard (e.g.
+          // local dev) was silently blocked by CORS the moment it tried to
+          // read artifacts. Default the allowlist to the same origin the
+          // handoff link actually points at.
+          dashboardOrigin: resolveDashboardOrigin(args, dashboardUrl),
+          service: "serve",
+        });
+        const fragment = new URLSearchParams({
+          "local-artifact-project": cfg.project?.id ?? "default",
+          "local-artifact-origin": bridge.origin,
+          "local-artifact-token": bridge.token,
+        });
+        const dashboardHandoff = new URL(dashboardUrl);
+        dashboardHandoff.searchParams.set("project", cfg.project?.id ?? "default");
+        dashboardHandoff.searchParams.set("deviceId", resolveDeviceId());
+        if (process.env.BUGMOLE_AEGIS_EMAIL?.trim()) {
+          dashboardHandoff.searchParams.set("email", process.env.BUGMOLE_AEGIS_EMAIL.trim());
+        }
+        console.log(`[Bugmole] Local artifact bridge listening at ${bridge.origin}`);
+        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.log(
+          `[Bugmole] Dashboard handoff: ${buildDashboardHandoffUrl(dashboardHandoff.toString(), cfg.project?.id ?? "default", fragment)}`,
+        );
+        if (shouldOpenServeBrowser(args)) {
+          const { openBrowser } = await import("../src/runtime/init-wizard.js");
+          openBrowser(buildDashboardHandoffUrl(dashboardHandoff.toString(), cfg.project?.id ?? "default", fragment));
+        }
+        closeBridge = () => void bridge.close("shutdown");
+      }
+      let localRegistryStop = () => {};
+      if (resolveLocalRegistryEnabled(args)) {
+        const { startLocalRegistryStub } = await import("../src/runtime/local-registry-stub.js");
+        const localRegistry = await startLocalRegistryStub({
+          directory: resolveLocalStorageDirectory(cfg),
+          port: resolveLocalRegistryPort(args),
+        });
+        localRegistryStop = () => void localRegistry.close();
+        // Redirect this process's own registry calls (this worker's
+        // ControlPlaneClient, and any MCP-tool call this session makes that
+        // publishes a plan or journey revision) at the local stub instead of
+        // the real registry. Never overwrite an operator-supplied value —
+        // this only fills in what would otherwise leave the worker idle.
+        if (!process.env.BUGMOLE_REGISTRY_URL?.trim()) process.env.BUGMOLE_REGISTRY_URL = localRegistry.origin;
+        if (!process.env.BUGMOLE_API_KEY?.trim()) process.env.BUGMOLE_API_KEY = "local-registry-stub";
+        console.log(`[Bugmole] Local registry stub listening at ${localRegistry.origin}`);
+        console.log(
+          `[Bugmole] Set BUGMOLE_REGISTRY_URL=${localRegistry.origin} in the dashboard's own env ` +
+          `(apps/qa/.env.local) so its API routes write here instead of the real registry.`,
+        );
+      }
+      const stop = () => {
+        localRegistryStop();
+        closeBridge();
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+      cfg.mcp = { ...(cfg.mcp ?? {}), enabled: true };
+      const { startServeWorker } = await import("../src/runtime/serve-worker.js");
+      // The worker owns a long-lived registry connection. Start it alongside
+      // MCP so this process exposes the project-scoped tools as well.
+      void startServeWorker(cfg).catch((error) => {
+        console.error(`[Bugmole] Serve worker stopped: ${error instanceof Error ? error.message : error}`);
+      });
+      await startMcpServerForServe(cfg);
+      // Keep the serve command's main promise alive independently of the
+      // HTTP servers. This prevents a future MCP implementation from
+      // returning after startup and silently ending the project worker.
+      await new Promise<void>((resolve) => {
+        const keepAlive = () => resolve();
+        process.once("SIGINT", keepAlive);
+        process.once("SIGTERM", keepAlive);
+      });
+      break;
+    }
+    case "artifacts": {
+      if (cfg.storage?.provider && cfg.storage.provider !== "local") {
+        throw new Error("The local artifact bridge requires storage.provider=local");
+      }
+      const dashboardUrl = resolveDashboardUrl(args);
+      const { startLocalArtifactServer } = await import("../src/storage/local-artifact-server.js");
+      const bridge = await startLocalArtifactServer({
+        directory: resolveLocalStorageDirectory(cfg),
+        projectId: cfg.project?.id ?? "default",
+        aegisEmail: process.env.BUGMOLE_AEGIS_EMAIL?.trim(),
+        port: args.artifactport ? Number(args.artifactport) : undefined,
+        dashboardOrigin: resolveDashboardOrigin(args, dashboardUrl),
+        service: "artifacts",
+      });
+      const fragment = new URLSearchParams({
+        "local-artifact-project": cfg.project?.id ?? "default",
+        "local-artifact-origin": bridge.origin,
+        "local-artifact-token": bridge.token,
+      });
+      console.log(`[Bugmole] Local artifact bridge listening at ${bridge.origin}`);
+      console.log(`[Bugmole] Capability expires at ${bridge.expiresAt}`);
+      const dashboardHandoff = buildDashboardHandoffUrl(dashboardUrl, cfg.project?.id ?? "default", fragment);
+      console.log(`[Bugmole] Dashboard handoff: ${dashboardHandoff}`);
+      const { openBrowser } = await import("../src/runtime/init-wizard.js");
+      openBrowser(dashboardHandoff);
+      await new Promise<void>((resolve, reject) => {
+        const stop = () => void bridge.close().then(resolve, reject);
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+      });
+      break;
+    }
+    case "mcp": {
+      const { startMcpServer } = await import("../src/mcp/server.js");
+      await startMcpServer(cfg);
+      break;
+    }
+    default: {
+      const { runBugmole } = await import("../src/runtime/run.js");
+      const result = await runBugmole(cfg, { mode, args });
+      process.exitCode = runModeExitCode(mode, result);
+      break;
+    }
+  }
+}
+
+async function startMcpServerForServe(cfg: any): Promise<void> {
+  const { startMcpServer } = await import("../src/mcp/server.js");
+  await startMcpServer(cfg, { forceHttp: true });
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((err) => {
+    console.error(`[Bugmole MCP] fatal: ${err?.message ?? err}`);
+    process.exit(1);
+  });
+}