@bugmole/cli 0.4.0

package/src/runtime/local-browser.ts

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+
+/** Where Google Chrome lives on macOS, kept first so existing Mac setups keep using the browser they already have. */
+export const MAC_CHROME_PATH = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+
+export type BrowserResolutionDeps = {
+  env?: Record<string, string | undefined>;
+  exists?: (candidate: string) => boolean;
+  /** Playwright's bundled Chromium, which `npx playwright install chromium` provides on every platform. */
+  playwrightChromiumPath?: () => Promise<string | undefined>;
+};
+
+async function defaultPlaywrightChromiumPath(): Promise<string | undefined> {
+  try {
+    const { chromium } = await import("playwright");
+    return chromium.executablePath();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Picks the browser binary used for headless page captures and DOM dumps.
+ *
+ * Order: an explicit BUGMOLE_BROWSER_PATH, then macOS Google Chrome, then
+ * Playwright's bundled Chromium. The last step is what lets a Linux worker
+ * (CI or a cloud container) capture pages without any extra configuration.
+ */
+export async function resolveHeadlessBrowserPath(deps: BrowserResolutionDeps = {}): Promise<string> {
+  const env = deps.env ?? process.env;
+  const exists = deps.exists ?? ((candidate: string) => fs.existsSync(candidate));
+  const explicit = env.BUGMOLE_BROWSER_PATH?.trim();
+  if (explicit) return explicit;
+  if (exists(MAC_CHROME_PATH)) return MAC_CHROME_PATH;
+  const bundled = await (deps.playwrightChromiumPath ?? defaultPlaywrightChromiumPath)();
+  if (bundled && exists(bundled)) return bundled;
+  throw new Error(
+    "No headless browser found. Set BUGMOLE_BROWSER_PATH, install Google Chrome, or run `npx playwright install chromium`.",
+  );
+}
+
+/**
+ * Chrome refuses to start as root without --no-sandbox, and containers
+ * (including the official Playwright image) run as root by default.
+ */
+export function headlessBrowserArgs(platform: NodeJS.Platform = process.platform, uid: number | undefined = process.getuid?.()): string[] {
+  return platform === "linux" && uid === 0 ? ["--no-sandbox"] : [];
+}

package/src/runtime/local-registry-stub.test.ts

@@ -0,0 +1,325 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { startLocalRegistryStub } from "./local-registry-stub.js";
+
+async function withStub(run: (origin: string) => Promise<void>) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-local-registry-"));
+  const stub = await startLocalRegistryStub({ directory });
+  try {
+    await run(stub.origin);
+  } finally {
+    await stub.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function postJson(origin: string, pathname: string, body: unknown) {
+  const response = await fetch(`${origin}${pathname}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return { status: response.status, body: await response.json() };
+}
+
+test("publishes a plan, then a run against it can be created, claimed, and updated to completion", async () => {
+  await withStub(async (origin) => {
+    const publish = await postJson(origin, "/api/projects/lumis/plans", {
+      planId: "member-login",
+      journeyId: "member-navigation",
+      objectKey: "projects/lumis/plans/member-login.flow.yaml",
+    });
+    assert.equal(publish.status, 201);
+
+    const created = await postJson(origin, "/api/projects/lumis/runs", {
+      planId: "member-login",
+      idempotencyKey: "idem-1",
+    });
+    assert.equal(created.status, 201);
+    const runId = (created.body as { run: { id: string } }).run.id;
+    assert.equal((created.body as { run: { journeyId: string } }).run.journeyId, "member-navigation");
+    assert.equal((created.body as { run: { status: string } }).run.status, "queued");
+
+    const claim = await postJson(origin, `/api/runs/${runId}/claim`, { workerId: "worker-1" });
+    assert.equal(claim.status, 200);
+    assert.equal((claim.body as { claimed: boolean }).claimed, true);
+
+    const doubleClaim = await postJson(origin, `/api/runs/${runId}/claim`, { workerId: "worker-2" });
+    assert.equal(doubleClaim.status, 409);
+
+    const update = await postJson(origin, `/api/runs/${runId}`, {
+      workerId: "worker-1",
+      status: "success",
+      stepsExecuted: 4,
+      stepsPassed: 4,
+      stepsFailed: 0,
+    });
+    assert.equal(update.status, 200);
+
+    const list = await fetch(`${origin}/api/projects/lumis/runs`);
+    const { runs } = await list.json() as { runs: Array<{ status: string; stepsPassed: number }> };
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].status, "success");
+    assert.equal(runs[0].stepsPassed, 4);
+  });
+});
+
+test("creating a run against a plan that was never published is rejected", async () => {
+  await withStub(async (origin) => {
+    const created = await postJson(origin, "/api/projects/lumis/runs", {
+      planId: "never-published",
+      idempotencyKey: "idem-x",
+    });
+    assert.equal(created.status, 404);
+  });
+});
+
+test("queuing the same task twice with the same idempotency key returns the same task, not a duplicate", async () => {
+  await withStub(async (origin) => {
+    const first = await postJson(origin, "/api/projects/lumis/tasks", {
+      title: "Explore the app",
+      description: "Run the exploration loop.",
+      taskType: "investigation",
+      idempotencyKey: "explore-1",
+    });
+    assert.equal(first.status, 201);
+    const second = await postJson(origin, "/api/projects/lumis/tasks", {
+      title: "Explore the app",
+      description: "Run the exploration loop.",
+      taskType: "investigation",
+      idempotencyKey: "explore-1",
+    });
+    assert.equal(second.status, 200);
+    assert.equal((first.body as { task: { id: string } }).task.id, (second.body as { task: { id: string } }).task.id);
+
+    const list = await fetch(`${origin}/api/projects/lumis/tasks`);
+    const { tasks } = await list.json() as { tasks: unknown[] };
+    assert.equal(tasks.length, 1);
+  });
+});
+
+test("a claimed task can be completed, and a UI task cannot complete without a parity score", async () => {
+  await withStub(async (origin) => {
+    const created = await postJson(origin, "/api/projects/lumis/tasks", {
+      title: "Fix the sign-in bug",
+      description: "UI parity fix.",
+      taskType: "ui",
+      idempotencyKey: "ui-task-1",
+    });
+    const taskId = (created.body as { task: { id: string } }).task.id;
+
+    const claim = await postJson(origin, `/api/tasks/${taskId}/claim`, { workerId: "worker-1" });
+    assert.equal(claim.status, 200);
+
+    const rejected = await postJson(origin, `/api/tasks/${taskId}`, { status: "completed" });
+    assert.equal(rejected.status, 422);
+
+    const completed = await postJson(origin, `/api/tasks/${taskId}`, {
+      status: "completed",
+      parityAuditId: "audit-1",
+      parityMatchScore: 0.98,
+    });
+    assert.equal(completed.status, 200);
+    assert.equal((completed.body as { task: { status: string } }).task.status, "completed");
+  });
+});
+
+test("a parked task can be resumed by a human, and only then becomes claimable again", async () => {
+  await withStub(async (origin) => {
+    const created = await postJson(origin, "/api/projects/lumis/tasks", {
+      title: "Verify authenticated routes",
+      description: "Needs an approved session before it can run.",
+      taskType: "investigation",
+      idempotencyKey: "parked-task-1",
+    });
+    const taskId = (created.body as { task: { id: string } }).task.id;
+
+    await postJson(origin, `/api/tasks/${taskId}/claim`, { workerId: "worker-1" });
+    const blocked = await postJson(origin, `/api/tasks/${taskId}`, {
+      status: "blocked",
+      errorMessage: "cursor-agent run timed out.",
+    });
+    assert.equal(blocked.status, 200);
+
+    // Parked: the backoff the block scheduled keeps it out of the queue.
+    const whileParked = await postJson(origin, `/api/tasks/${taskId}/claim`, { workerId: "worker-2" });
+    assert.equal(whileParked.status, 409);
+
+    const resumed = await postJson(origin, `/api/tasks/${taskId}/resume`, {});
+    assert.equal(resumed.status, 200);
+    const task = (resumed.body as { resumed: boolean; task: { status: string; attempts: number; errorMessage: string | null } }).task;
+    assert.equal(task.status, "queued");
+    assert.equal(task.attempts, 0, "the retry budget must be given back, or resuming changes nothing");
+    assert.equal(task.errorMessage, null, "the stale failure should not follow the task into its next run");
+
+    // The point of the whole exercise: a worker can pick it up again.
+    const afterResume = await postJson(origin, `/api/tasks/${taskId}/claim`, { workerId: "worker-2" });
+    assert.equal(afterResume.status, 200);
+  });
+});
+
+test("resume refuses finished work and unknown tasks", async () => {
+  await withStub(async (origin) => {
+    const created = await postJson(origin, "/api/projects/lumis/tasks", {
+      title: "Already done",
+      description: "Completed work must not be reopened by resume.",
+      taskType: "investigation",
+      idempotencyKey: "finished-task-1",
+    });
+    const taskId = (created.body as { task: { id: string } }).task.id;
+    await postJson(origin, `/api/tasks/${taskId}/claim`, { workerId: "worker-1" });
+    await postJson(origin, `/api/tasks/${taskId}`, { status: "completed" });
+
+    const reopened = await postJson(origin, `/api/tasks/${taskId}/resume`, {});
+    assert.equal(reopened.status, 409);
+
+    const missing = await postJson(origin, "/api/tasks/task_does_not_exist/resume", {});
+    assert.equal(missing.status, 404);
+  });
+});
+
+test("journey revisions increment per journeyId and reject a stale expectedRevision", async () => {
+  await withStub(async (origin) => {
+    const first = await postJson(origin, "/api/projects/lumis/journeys", {
+      journeyId: "member-navigation",
+      objectKey: "projects/lumis/journeys/member-navigation.json",
+    });
+    assert.equal(first.status, 201);
+    assert.equal((first.body as { revision: { revision: number } }).revision.revision, 1);
+
+    const stale = await postJson(origin, "/api/projects/lumis/journeys", {
+      journeyId: "member-navigation",
+      objectKey: "projects/lumis/journeys/member-navigation.json",
+      expectedRevision: 0,
+    });
+    assert.equal(stale.status, 409);
+
+    const second = await postJson(origin, "/api/projects/lumis/journeys", {
+      journeyId: "member-navigation",
+      objectKey: "projects/lumis/journeys/member-navigation.json",
+      expectedRevision: 1,
+    });
+    assert.equal(second.status, 201);
+    assert.equal((second.body as { revision: { revision: number } }).revision.revision, 2);
+  });
+});
+
+test("collections are isolated per project", async () => {
+  await withStub(async (origin) => {
+    await postJson(origin, "/api/projects/project-a/tasks", {
+      title: "A task",
+      description: "For project A only.",
+      idempotencyKey: "a-1",
+    });
+    const listB = await fetch(`${origin}/api/projects/project-b/tasks`);
+    const { tasks } = await listB.json() as { tasks: unknown[] };
+    assert.equal(tasks.length, 0);
+  });
+});
+
+test("a run keeps its requested targets and environment URL through claim and completion", async () => {
+  await withStub(async (origin) => {
+    await postJson(origin, "/api/projects/lumis/plans", {
+      planId: "member-login",
+      journeyId: "member-navigation",
+      objectKey: "projects/lumis/plans/member-login.flow.yaml",
+    });
+    const rejected = await postJson(origin, "/api/projects/lumis/runs", {
+      planId: "member-login",
+      idempotencyKey: "idem-bad",
+      targets: [{ browser: "opera" }],
+    });
+    assert.equal(rejected.status, 422);
+
+    const created = await postJson(origin, "/api/projects/lumis/runs", {
+      planId: "member-login",
+      idempotencyKey: "idem-matrix",
+      environmentBaseUrl: "https://staging.example.com",
+      targets: [{ browser: "chromium" }, { browser: "webkit", device: "iPhone 15" }, { browser: "chromium" }],
+    });
+    assert.equal(created.status, 201);
+    const runId = (created.body as { run: { id: string } }).run.id;
+
+    const claim = await postJson(origin, `/api/runs/${runId}/claim`, { workerId: "worker-1" });
+    assert.deepEqual(claim.body, {
+      claimed: true,
+      leaseExpiresAt: (claim.body as { leaseExpiresAt: string }).leaseExpiresAt,
+      environmentBaseUrl: "https://staging.example.com",
+      targets: [{ browser: "chromium" }, { browser: "webkit", device: "iPhone 15" }],
+      fixFrom: null,
+    });
+
+    const targetResults = [{ targetId: "chromium", browser: "chromium", status: "passed", stepsPassed: 2, stepsFailed: 0, artifactKeys: [] }];
+    await postJson(origin, `/api/runs/${runId}`, { status: "running", targetResults });
+    await postJson(origin, `/api/runs/${runId}`, { status: "success" });
+
+    const run = await (await fetch(`${origin}/api/runs/${runId}`)).json() as {
+      run: { targetResults: unknown[]; durationMs: number; environmentBaseUrl: string };
+    };
+    // A later update without results keeps the last snapshot.
+    assert.deepEqual(run.run.targetResults, targetResults);
+    assert.equal(typeof run.run.durationMs, "number");
+    assert.equal(run.run.environmentBaseUrl, "https://staging.example.com");
+  });
+});
+
+test("a late progress update cannot reopen a finished run", async () => {
+  await withStub(async (origin) => {
+    await postJson(origin, "/api/projects/lumis/plans", {
+      planId: "member-login",
+      journeyId: "member-navigation",
+      objectKey: "projects/lumis/plans/member-login.flow.yaml",
+    });
+    const created = await postJson(origin, "/api/projects/lumis/runs", { planId: "member-login", idempotencyKey: "idem-late" });
+    const runId = (created.body as { run: { id: string } }).run.id;
+    await postJson(origin, `/api/runs/${runId}/claim`, { workerId: "worker-1" });
+    await postJson(origin, `/api/runs/${runId}`, { status: "error" });
+    const late = await postJson(origin, `/api/runs/${runId}`, { status: "running" });
+    assert.equal(late.status, 409);
+    const run = await (await fetch(`${origin}/api/runs/${runId}`)).json() as { run: { status: string } };
+    assert.equal(run.run.status, "error");
+  });
+});
+
+test("personas: the default Curious persona is created lazily and matches the real registry's schema", async () => {
+  await withStub(async (origin) => {
+    const first = await (await fetch(`${origin}/api/projects/lumis/personas`)).json() as { personas: Array<{ id: string; name: string; description: string; isDefault: boolean }> };
+    assert.equal(first.personas.length, 1);
+    assert.equal(first.personas[0].name, "Curious");
+    assert.equal(first.personas[0].isDefault, true);
+    assert.ok(first.personas[0].description.length > 0);
+
+    const second = await (await fetch(`${origin}/api/projects/lumis/personas`)).json() as { personas: unknown[] };
+    assert.equal(second.personas.length, 1, "the default is only ever created once");
+  });
+});
+
+test("personas: adding, renaming, and removing, with at least one always kept", async () => {
+  await withStub(async (origin) => {
+    const list0 = await (await fetch(`${origin}/api/projects/lumis/personas`)).json() as { personas: Array<{ id: string }> };
+    const defaultId = list0.personas[0].id;
+
+    const added = await postJson(origin, "/api/projects/lumis/personas", { name: "Impatient power user", description: "Skip straight to checkout." });
+    assert.equal(added.status, 201, JSON.stringify(added.body));
+    const personaId = (added.body as { persona: { id: string } }).persona.id;
+
+    const duplicate = await postJson(origin, "/api/projects/lumis/personas", { name: "Impatient power user", description: "Different text, same name." });
+    assert.equal(duplicate.status, 409);
+
+    const renamed = await fetch(`${origin}/api/projects/lumis/personas/${personaId}`, {
+      method: "PATCH", headers: { "content-type": "application/json" }, body: JSON.stringify({ name: "Very impatient", description: "Skip straight to checkout." }),
+    });
+    assert.equal(renamed.status, 200);
+
+    const list = await (await fetch(`${origin}/api/projects/lumis/personas`)).json() as { personas: Array<{ name: string }> };
+    assert.deepEqual(list.personas.map((persona) => persona.name).sort(), ["Curious", "Very impatient"]);
+
+    const removed = await fetch(`${origin}/api/projects/lumis/personas/${personaId}`, { method: "DELETE" });
+    assert.equal(removed.status, 200);
+    const removeLast = await fetch(`${origin}/api/projects/lumis/personas/${defaultId}`, { method: "DELETE" });
+    assert.equal(removeLast.status, 409, "the last persona in a project can't be removed");
+  });
+});