@bugmole/cli 0.4.0

package/src/runtime/run.ts

@@ -0,0 +1,132 @@
+export async function runBugmole(cfg: any, opts: { mode: string; args?: any }): Promise<any> {
+  const { mode, args = {} } = opts;
+
+  console.log(`[Bugmole MCP] mode=${mode} env=${cfg.runtime.env}`);
+  console.log(`[Bugmole MCP] spec_dir=${cfg.runtime.spec_dir}`);
+  console.log(`[Bugmole MCP] artifacts_dir=${cfg.runtime.artifacts_dir}`);
+
+  switch (mode) {
+    case "explore": {
+      const { explore } = await import("./explorer.js");
+      const result = await explore(cfg, {
+        baseUrl: args.baseUrl || args.baseurl || cfg.execution?.playwright?.base_url || "http://localhost:3000",
+        maxDepth: args.maxDepth || args.maxdepth || 5,
+      });
+      console.log(`[Bugmole MCP] Exploration result:`, result);
+      return result;
+    }
+
+    case "plan": {
+      const { plan } = await import("./planner.js");
+      const journeyId = args.journeyId || args.journeyid;
+      if (!journeyId || !args.actor) {
+        throw new Error(
+          "Planning requires guided exploration first. Read bugmole://guidance/agent-testing, run --mode explore --baseUrl <url>, choose a discovered journey and defined actor, then retry with --journeyId <id> --actor <role>.",
+        );
+      }
+      const result = await plan(cfg, {
+        journeyId,
+        actor: args.actor,
+      });
+      console.log(`[Bugmole MCP] Planning result:`, result);
+      return result;
+    }
+
+    case "run": {
+      const { execute } = await import("./executor.js");
+      // parseArgs lowercases flags (`--plan-id` → `planid`); MCP callers pass camelCase.
+      const planId = args.planId || args.planid;
+      if (!planId) {
+        throw new Error("run mode requires --plan-id argument");
+      }
+      const { targetsFromFlags } = await import("./browser-matrix.js");
+      const targets = targetsFromFlags(args.browsers, args.devices);
+      const baseUrl = args.baseUrl || args.baseurl;
+      const result = await execute(cfg, {
+        planId,
+        journeyId: args.journeyId || args.journeyid,
+        ...(typeof baseUrl === "string" && baseUrl ? { baseUrl } : {}),
+        ...(targets.length ? { targets } : {}),
+      });
+      console.log(`[Bugmole MCP] Execution result:`, result);
+      return result;
+    }
+
+    case "propose-diff": {
+      const { proposeDiff } = await import("./diff-proposal.js");
+      if (!args.filePath || !args.evidence) {
+        throw new Error("propose-diff mode requires --file-path and --evidence arguments");
+      }
+      const result = await proposeDiff(cfg, {
+        filePath: args.filePath,
+        evidence: args.evidence,
+        failures: args.failures,
+      });
+      console.log(`[Bugmole MCP] Diff proposal result:`, result);
+      return result;
+    }
+
+    case "review": {
+      const { review } = await import("./reviewer.js");
+      if (!args.filePath || !args.changeSummary || !args.diff) {
+        throw new Error("review mode requires --file-path, --change-summary, and --diff arguments");
+      }
+      const result = await review(cfg, {
+        filePath: args.filePath,
+        changeSummary: args.changeSummary,
+        diff: args.diff,
+        evidence: args.evidence || {},
+      });
+      console.log(`[Bugmole MCP] Review result:`, result);
+      return result;
+    }
+
+    case "report": {
+      const { generateReport } = await import("./reporter.js");
+      const result = await generateReport(cfg, {
+        runId: args.runId,
+        format: args.format || "markdown",
+      });
+      console.log(`[Bugmole MCP] Report generated:`, result.reportPath);
+      return result;
+    }
+
+    case "cursor-driver": {
+      const { runCursorDriver } = await import("./cursor-driver-run.js");
+      if (!args.task) {
+        throw new Error("cursor-driver mode requires --task argument");
+      }
+      const projectDirectory =
+        args.projectDirectory || args.projectdirectory || cfg.cursor_driver?.project_directory;
+      if (projectDirectory) {
+        console.log(`[Bugmole MCP] Using project directory: ${projectDirectory}`);
+      }
+      const result = await runCursorDriver(args.task, {
+        mcpHost: cfg.mcp?.host || "127.0.0.1",
+        mcpPort: cfg.mcp?.port || 3187,
+        artifactsDir: cfg.runtime.artifacts_dir || "./artifacts",
+        timeout: args.timeout || 300000,
+        pollInterval: args.pollInterval || 1000,
+        requestId: args.requestId,
+        customInstructions: args.customInstructions,
+        projectDirectory,
+        nudgeOptions:
+          args.nudgeEnabled === false
+            ? { enabled: false }
+            : {
+                enabled: args.nudgeEnabled !== false,
+                progressReportTimeout:
+                  args.nudgeProgressReportTimeout || args.nudgeInactivityThreshold,
+                nudgeInterval: args.nudgeInterval,
+                maxNudges: args.nudgeMaxNudges,
+                customMessage: args.nudgeMessage,
+              },
+      });
+      console.log(`[Bugmole MCP] CURSOR_DRIVER result:`, result);
+      return result;
+    }
+
+    default:
+      throw new Error(`Unknown mode: ${mode}`);
+  }
+}

package/src/runtime/screen-recording.ts

@@ -0,0 +1,34 @@
+import fs from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Drop near-identical frames, then restamp what is left as evenly spaced.
+ *
+ * Without the restamp the dropped frames leave their duration behind and the
+ * video is the same length with the motion stuttering through it, which is the
+ * opposite of what skipping idle is for.
+ */
+export function mpdecimateArgs(input: string, output: string): string[] {
+  return ["-y", "-i", input, "-vf", "mpdecimate,setpts=N/FRAME_RATE/TB", "-an", output];
+}
+
+/** Returns the trimmed file, or the original when ffmpeg cannot do it. */
+export async function dropIdleFrames(localPath: string, ffmpegCommand: string): Promise<string> {
+  const trimmed = localPath.replace(/\.mp4$/, "") + ".trimmed.mp4";
+  try {
+    await execFileAsync(ffmpegCommand, mpdecimateArgs(localPath, trimmed), { timeout: 300_000 });
+    const stats = await fs.stat(trimmed).catch(() => undefined);
+    if (!stats || stats.size === 0) return localPath;
+    await fs.rm(localPath, { force: true }).catch(() => undefined);
+    await fs.rename(trimmed, localPath).catch(() => undefined);
+    return localPath;
+  } catch {
+    // No ffmpeg, or it refused the file. Keeping the untrimmed recording is
+    // the point: skipping idle is a convenience, not a requirement.
+    await fs.rm(trimmed, { force: true }).catch(() => undefined);
+    return localPath;
+  }
+}

package/src/runtime/serve-gateway.test.ts

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import http from "node:http";
+import test from "node:test";
+import WebSocket, { WebSocketServer } from "ws";
+import { connectServeGateway, startServeGateway } from "./serve-gateway.js";
+
+async function listen(server: http.Server): Promise<number> {
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  return (server.address() as { port: number }).port;
+}
+
+function fakeRegistry(projectId: string) {
+  const server = http.createServer();
+  const sockets = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (request, socket, head) => {
+    sockets.handleUpgrade(request, socket, head, (client) => sockets.emit("connection", client));
+  });
+  sockets.on("connection", (socket) => {
+    socket.on("message", (raw) => {
+      const message = JSON.parse(raw.toString()) as { projectId?: string };
+      if (message.projectId === projectId) {
+        socket.send(JSON.stringify({ type: "job_queued", projectId, runId: `${projectId}-run` }));
+      }
+    });
+  });
+  return server;
+}
+
+test("serve gateway authenticates workers and routes by project", async () => {
+  const registryA = fakeRegistry("project-a");
+  const registryB = fakeRegistry("project-b");
+  const registryAPort = await listen(registryA);
+  const registryBPort = await listen(registryB);
+  const gateway = await startServeGateway({ port: 0, secret: "gateway-secret" });
+  const messages = new Map<string, Record<string, unknown>>();
+  const connect = (projectId: string, registryPort: number) => new Promise<WebSocket>((resolve, reject) => {
+    const socket = connectServeGateway(
+      gateway.origin,
+      gateway.secret,
+      {
+        workerId: `${projectId}-worker`,
+        projectId,
+        registryUrl: `http://127.0.0.1:${registryPort}`,
+        apiKey: "local-test-key",
+      },
+      (message) => {
+        if (message.type === "job_queued") messages.set(projectId, message);
+      },
+    );
+    socket.once("open", () => resolve(socket));
+    socket.once("error", reject);
+  });
+  const workerA = await connect("project-a", registryAPort);
+  const workerB = await connect("project-b", registryBPort);
+  await new Promise((resolve) => setTimeout(resolve, 40));
+  assert.equal(messages.get("project-a")?.runId, "project-a-run");
+  assert.equal(messages.get("project-b")?.runId, "project-b-run");
+  workerA.close();
+  workerB.close();
+  await gateway.close();
+  await new Promise<void>((resolve) => registryA.close(() => resolve()));
+  await new Promise<void>((resolve) => registryB.close(() => resolve()));
+});
+
+test("serve gateway rejects unauthorized worker connections", async () => {
+  const gateway = await startServeGateway({ port: 0, secret: "gateway-secret" });
+  const rejected = await new Promise<boolean>((resolve) => {
+    const socket = new WebSocket(`${gateway.origin.replace(/^http/, "ws")}/worker?secret=wrong`);
+    socket.once("open", () => resolve(false));
+    socket.once("error", () => resolve(true));
+  });
+  assert.equal(rejected, true);
+  await gateway.close();
+});

package/src/runtime/serve-gateway.ts

@@ -0,0 +1,164 @@
+import http from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import WebSocket, { WebSocketServer } from "ws";
+import { ControlPlaneClient } from "../registry/control-plane-client.js";
+
+export type GatewayRegistration = {
+  type: "worker_hello";
+  workerId: string;
+  projectId: string;
+  workspaceId?: string;
+  registryUrl: string;
+  apiKey: string;
+};
+
+type WorkerMessage = GatewayRegistration | { type: "worker_goodbye"; workerId: string };
+
+function sameSecret(actual: string | undefined, expected: string): boolean {
+  if (!actual) return false;
+  const left = Buffer.from(actual);
+  const right = Buffer.from(expected);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function json(response: http.ServerResponse, status: number, body: unknown): void {
+  response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(body));
+}
+
+export type ServeGateway = {
+  origin: string;
+  secret: string;
+  close(): Promise<void>;
+};
+
+export type ServeGatewayOptions = {
+  host?: string;
+  port?: number;
+  secret?: string;
+};
+
+export async function startServeGateway(options: ServeGatewayOptions = {}): Promise<ServeGateway> {
+  const host = options.host ?? "127.0.0.1";
+  const secret = options.secret ?? randomBytes(32).toString("base64url");
+  const workers = new Map<string, { socket: WebSocket; projectId: string; registrySocket: WebSocket }>();
+  const projects = new Map<string, string>();
+  const webSockets = new WebSocketServer({ noServer: true });
+  const server = http.createServer((request, response) => {
+    const url = new URL(request.url ?? "/", `http://${host}`);
+    if (url.pathname === "/health") {
+      json(response, 200, { ok: true, workers: workers.size, projects: [...projects.keys()] });
+      return;
+    }
+    json(response, 404, { error: "Not found" });
+  });
+
+  const removeWorker = (workerId: string) => {
+    const worker = workers.get(workerId);
+    if (!worker) return;
+    workers.delete(workerId);
+    if (projects.get(worker.projectId) === workerId) projects.delete(worker.projectId);
+    worker.registrySocket.close();
+  };
+
+  webSockets.on("connection", (socket) => {
+    let workerId: string | undefined;
+    socket.on("message", (raw) => {
+      let message: WorkerMessage;
+      try {
+        message = JSON.parse(raw.toString()) as WorkerMessage;
+      } catch {
+        socket.close(1003, "Invalid JSON");
+        return;
+      }
+      if (message.type === "worker_goodbye") {
+        if (message.workerId === workerId) removeWorker(message.workerId);
+        return;
+      }
+      if (message.type !== "worker_hello") return;
+      if (!message.workerId || !message.projectId || !message.registryUrl || !message.apiKey) {
+        socket.close(1008, "Incomplete worker registration");
+        return;
+      }
+      const existing = projects.get(message.projectId);
+      if (existing && existing !== message.workerId) {
+        socket.close(1008, "Project already has an active worker");
+        return;
+      }
+      removeWorker(message.workerId);
+      const client = new ControlPlaneClient({
+        registryUrl: message.registryUrl,
+        apiKey: message.apiKey,
+        projectId: message.projectId,
+        workspaceId: message.workspaceId,
+      });
+      const registrySocket = client.connectWorker(message.workerId, (registryMessage) => {
+        if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(registryMessage));
+      });
+      workerId = message.workerId;
+      workers.set(workerId, { socket, projectId: message.projectId, registrySocket });
+      projects.set(message.projectId, workerId);
+      socket.send(JSON.stringify({ type: "gateway_registered", workerId, projectId: message.projectId }));
+      socket.on("close", () => removeWorker(workerId!));
+      socket.on("error", () => removeWorker(workerId!));
+    });
+  });
+
+  server.on("upgrade", (request, socket, head) => {
+    const url = new URL(request.url ?? "/", `http://${host}`);
+    if (url.pathname !== "/worker" || !sameSecret(url.searchParams.get("secret") ?? undefined, secret)) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+    webSockets.handleUpgrade(request, socket, head, (client) => {
+      webSockets.emit("connection", client, request);
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: NodeJS.ErrnoException) => {
+      server.removeListener("error", onError);
+      reject(error);
+    };
+    server.once("error", onError);
+    server.listen(options.port ?? 3191, host, () => {
+      server.removeListener("error", onError);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Gateway did not bind");
+  return {
+    origin: `http://${host}:${address.port}`,
+    secret,
+    close: async () => {
+      for (const workerId of workers.keys()) removeWorker(workerId);
+      await new Promise<void>((resolve, reject) => webSockets.close((error) => error ? reject(error) : resolve()));
+      await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+    },
+  };
+}
+
+export function connectServeGateway(
+  origin: string,
+  secret: string,
+  registration: Omit<GatewayRegistration, "type">,
+  onMessage: (message: Record<string, unknown>) => void,
+): WebSocket {
+  const url = new URL("/worker", origin.replace(/^http/, "ws"));
+  url.searchParams.set("secret", secret);
+  // .toString() rather than the URL itself: @types/ws still types its
+  // address as node:url's URL, while @types/node 26 makes the global URL the
+  // web-standard one, and the two no longer line up.
+  const socket = new WebSocket(url.toString());
+  socket.on("open", () => socket.send(JSON.stringify({ type: "worker_hello", ...registration })));
+  socket.on("message", (raw) => {
+    try {
+      onMessage(JSON.parse(raw.toString()) as Record<string, unknown>);
+    } catch {
+      // Ignore malformed gateway messages.
+    }
+  });
+  return socket;
+}

package/src/runtime/serve-worker.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { RegistryRequestError } from "../registry/control-plane-client.js";
+import { isClaimConflict, resolveMaxConcurrentRuns, workerTasksEnabled } from "./serve-worker.js";
+
+test("runs one run at a time unless a positive limit is configured", () => {
+  assert.equal(resolveMaxConcurrentRuns({}), 1);
+  assert.equal(resolveMaxConcurrentRuns({ BUGMOLE_MAX_CONCURRENT_RUNS: "3" }), 3);
+  assert.equal(resolveMaxConcurrentRuns({ BUGMOLE_MAX_CONCURRENT_RUNS: "0" }), 1);
+  assert.equal(resolveMaxConcurrentRuns({ BUGMOLE_MAX_CONCURRENT_RUNS: "lots" }), 1);
+});
+
+test("agent tasks stay on unless the worker opts out", () => {
+  assert.equal(workerTasksEnabled({}), true);
+  assert.equal(workerTasksEnabled({ BUGMOLE_WORKER_TASKS: "false" }), false);
+  assert.equal(workerTasksEnabled({ BUGMOLE_WORKER_TASKS: " FALSE " }), false);
+});
+
+test("treats only a 409 from the registry as a lost claim", () => {
+  assert.equal(isClaimConflict(new RegistryRequestError(409)), true);
+  assert.equal(isClaimConflict(new RegistryRequestError(500)), false);
+  assert.equal(isClaimConflict(new Error("Registry request failed (409)")), false);
+});