@bugmole/cli 0.4.0

package/src/runtime/maestro-driver.test.ts

@@ -0,0 +1,84 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { buildMaestroArgs, maestroDebugDir, MaestroDriver, parseMaestroCommands } from "./maestro-driver.js";
+
+const context = {
+  runId: "run-1",
+  projectId: "demo",
+  journeyId: "checkout",
+  flowPath: "/tmp/checkout.yaml",
+  platform: "android" as const,
+  target: { appId: "com.example.app", serial: "emulator-5554" },
+  timeoutMs: 10_000,
+  artifactsDir: "/tmp/bugmole-runs",
+};
+
+test("builds a bounded Maestro command for a target device with an explicit debug dir", () => {
+  assert.deepEqual(buildMaestroArgs(context), [
+    "test",
+    "/tmp/checkout.yaml",
+    "--format",
+    "junit",
+    "--test-output-dir",
+    maestroDebugDir(context),
+    "--device",
+    "emulator-5554",
+  ]);
+});
+
+test("passes --platform web for web-target flows", () => {
+  assert.deepEqual(buildMaestroArgs({ ...context, platform: "web", target: {} }), [
+    "test",
+    "/tmp/checkout.yaml",
+    "--format",
+    "junit",
+    "--test-output-dir",
+    maestroDebugDir({ ...context, platform: "web", target: {} }),
+    "--platform",
+    "web",
+  ]);
+});
+
+test("supports the canonical web, Android, and iOS platforms", () => {
+  const driver = new MaestroDriver({ command: "maestro" });
+  assert.equal(driver.supports("web"), true);
+  assert.equal(driver.supports("android"), true);
+  assert.equal(driver.supports("ios"), true);
+});
+
+test("does not claim unsupported platforms", () => {
+  const driver = new MaestroDriver();
+  assert.equal(driver.supports("web"), true);
+  assert.equal(driver.supports("desktop" as never), false);
+});
+
+test("parses real per-step status/timing from Maestro's own commands.json", () => {
+  // Shape confirmed from an actual local capture:
+  // ~/.maestro/tests/2026-08-27_125426/member-login/commands.json
+  const raw = JSON.stringify([
+    {
+      command: { launchAppCommand: { appId: "com.example.app" } },
+      metadata: { status: "COMPLETED", timestamp: 1000, duration: 3363, sequenceNumber: 0, depth: 0 },
+    },
+    {
+      command: { tapOnCommand: { text: "Sign in" } },
+      metadata: { status: "FAILED", timestamp: 4400, duration: 50, sequenceNumber: 1, depth: 0 },
+    },
+    {
+      command: { assertVisibleCommand: { text: "Home" } },
+      // Nested inside a retry/repeat block; must not be treated as its own step.
+      metadata: { status: "COMPLETED", timestamp: 4500, duration: 10, sequenceNumber: 2, depth: 1 },
+    },
+  ]);
+  const steps = parseMaestroCommands(raw);
+  assert.equal(steps.length, 2);
+  assert.equal(steps[0].status, "passed");
+  assert.equal(steps[0].durationMs, 3363);
+  assert.equal(steps[1].status, "failed");
+  assert.equal(steps[1].sequenceNumber, 1);
+});
+
+test("returns no steps for malformed or missing commands.json content", () => {
+  assert.deepEqual(parseMaestroCommands("not json"), []);
+  assert.deepEqual(parseMaestroCommands(JSON.stringify({ not: "an array" })), []);
+});

package/src/runtime/maestro-driver.ts

@@ -0,0 +1,209 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type {
+  AppDriver,
+  DriverContext,
+  DriverPlatform,
+  DriverResult,
+  DriverStepResult,
+} from "./driver.js";
+
+const execFileAsync = promisify(execFile);
+
+export type MaestroDriverOptions = {
+  command?: string;
+  extraArgs?: string[];
+};
+
+export function maestroDebugDir(context: DriverContext): string {
+  return path.join(context.artifactsDir, context.projectId, context.runId, "maestro-debug");
+}
+
+export function buildMaestroArgs(context: DriverContext, extraArgs: string[] = []): string[] {
+  const args = [
+    "test",
+    context.flowPath,
+    "--format",
+    "junit",
+    // Without an explicit output directory, Maestro writes commands.json,
+    // screenshots/, and logs/ under a timestamped ~/.maestro/tests/ path this
+    // driver never reads back. An explicit --test-output-dir writes those
+    // artifacts directly into a run-scoped directory this driver controls.
+    "--test-output-dir",
+    maestroDebugDir(context),
+  ];
+  // Maestro's CLI selects platform via --platform, not an env var; without it,
+  // `maestro test` falls back to Android device auto-detection even for a web
+  // flow and fails with "device offline" when no emulator is running.
+  // Android/iOS already disambiguate via --device below, so this is scoped to
+  // web to avoid changing behavior for the driver's other supported platforms.
+  if (context.platform === "web") {
+    args.push("--platform", "web");
+  }
+  if (context.target.deviceId || context.target.serial) {
+    args.push("--device", context.target.deviceId || context.target.serial || "");
+  }
+  return [...args, ...extraArgs];
+}
+
+function artifactPath(context: DriverContext, name: string): string {
+  return path.join(context.artifactsDir, context.projectId, context.runId, name);
+}
+
+async function writeOutput(context: DriverContext, name: string, value: string): Promise<string> {
+  const outputPath = artifactPath(context, name);
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, value, "utf8");
+  return outputPath;
+}
+
+type MaestroCommandRecord = {
+  command?: Record<string, unknown>;
+  metadata?: {
+    status?: string;
+    timestamp?: number;
+    duration?: number;
+    sequenceNumber?: number;
+    depth?: number;
+  };
+};
+
+/**
+ * Parses Maestro's own --test-output-dir commands.json into real per-step
+ * results. Only depth:0 commands are surfaced — nested commands (inside
+ * repeat/retry blocks) do not correspond 1:1 with a flow's declared steps.
+ */
+export function parseMaestroCommands(raw: string): DriverStepResult[] {
+  let records: MaestroCommandRecord[];
+  try {
+    records = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(records)) return [];
+  const topLevel = records.filter((record) => (record.metadata?.depth ?? 0) === 0);
+  return topLevel.map((record, index) => {
+    const status = (record.metadata?.status ?? "").toUpperCase();
+    const commandName = record.command ? Object.keys(record.command)[0] : undefined;
+    return {
+      sequenceNumber: record.metadata?.sequenceNumber ?? index,
+      status: status.includes("FAIL")
+        ? "failed"
+        : status === "COMPLETED" || status === "SUCCESS"
+          ? "passed"
+          : "blocked",
+      message: commandName ? `${commandName}: ${record.metadata?.status ?? "unknown"}` : record.metadata?.status,
+      durationMs: record.metadata?.duration,
+      timestamp: record.metadata?.timestamp ? new Date(record.metadata.timestamp).toISOString() : undefined,
+    };
+  });
+}
+
+async function readMaestroDebugArtifacts(
+  debugDir: string,
+): Promise<{ steps: DriverStepResult[]; screenshotPaths: string[] }> {
+  const steps = await fs
+    .readFile(path.join(debugDir, "commands.json"), "utf8")
+    .then(parseMaestroCommands)
+    .catch(() => []);
+  const screenshotPaths = await fs
+    .readdir(path.join(debugDir, "screenshots"))
+    .then((names) => names.filter((name) => /\.(png|jpe?g)$/i.test(name)).map((name) => path.join(debugDir, "screenshots", name)))
+    .catch(() => []);
+  return { steps, screenshotPaths };
+}
+
+export class MaestroDriver implements AppDriver {
+  readonly id = "maestro";
+  private readonly command: string;
+  private readonly extraArgs: string[];
+
+  constructor(options: MaestroDriverOptions = {}) {
+    this.command = options.command?.trim() || "maestro";
+    this.extraArgs = options.extraArgs ?? [];
+  }
+
+  supports(platform: DriverPlatform): boolean {
+    return platform === "web" || platform === "android" || platform === "ios";
+  }
+
+  async run(context: DriverContext): Promise<DriverResult> {
+    if (!this.supports(context.platform)) {
+      return {
+        status: "blocked",
+        message: `Maestro does not support platform "${context.platform}".`,
+        artifacts: [],
+        failureCode: "unsupported_platform",
+      };
+    }
+
+    const args = buildMaestroArgs(context, this.extraArgs);
+    const environment = {
+      ...process.env,
+      ...context.environment,
+      MAESTRO_PLATFORM: context.platform,
+      ...(context.target.baseUrl ? { MAESTRO_BASE_URL: context.target.baseUrl } : {}),
+      ...(context.target.appId ? { MAESTRO_APP_ID: context.target.appId } : {}),
+    };
+
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    try {
+      const result = await execFileAsync(this.command, args, {
+        cwd: process.cwd(),
+        env: environment,
+        timeout: context.timeoutMs,
+        maxBuffer: 8 * 1024 * 1024,
+      });
+      stdout = result.stdout;
+      stderr = result.stderr;
+    } catch (error) {
+      const failure = error as { code?: string | number; stdout?: string; stderr?: string; killed?: boolean; signal?: string };
+      stdout = failure.stdout ?? "";
+      stderr = failure.stderr ?? "";
+      exitCode = typeof failure.code === "number" ? failure.code : 1;
+      if (failure.code === "ENOENT") {
+        return {
+          status: "blocked",
+          message: `Maestro executable was not found: ${this.command}`,
+          stdout,
+          stderr,
+          artifacts: [],
+          failureCode: "driver_unavailable",
+        };
+      }
+      if (failure.killed || failure.signal === "SIGTERM") {
+        exitCode = 124;
+      }
+    }
+
+    const stdoutPath = await writeOutput(context, "maestro.stdout.log", stdout);
+    const stderrPath = await writeOutput(context, "maestro.stderr.log", stderr);
+    const debugDir = maestroDebugDir(context);
+    const { steps, screenshotPaths } = await readMaestroDebugArtifacts(debugDir);
+    const artifacts = [
+      { path: stdoutPath, contentType: "text/plain", name: "maestro.stdout.log" },
+      { path: stderrPath, contentType: "text/plain", name: "maestro.stderr.log" },
+      ...screenshotPaths.map((screenshotPath) => ({
+        path: screenshotPath,
+        contentType: /\.png$/i.test(screenshotPath) ? "image/png" : "image/jpeg",
+        name: `screenshots/${path.basename(screenshotPath)}`,
+      })),
+    ];
+    const passed = exitCode === 0;
+    return {
+      status: passed ? "passed" : "failed",
+      exitCode,
+      message: passed ? "Maestro flow completed." : `Maestro flow failed with exit code ${exitCode}.`,
+      stdout,
+      stderr,
+      artifacts,
+      recoverable: !passed && exitCode !== 124,
+      failureCode: passed ? undefined : exitCode === 124 ? "driver_timeout" : "flow_failed",
+      steps: steps.length ? steps : undefined,
+    };
+  }
+}

package/src/runtime/mole-voice.ts

@@ -0,0 +1,21 @@
+// How Bugmole talks about results: its agents are moles, failures it catches
+// are bugs they found, and failures that later pass are bugs they ate. The
+// theme is personality only: workspace, project, test run and issue keep
+// their ordinary names everywhere.
+// apps/qa/src/lib/mole-voice.ts is the dashboard's copy; keep them in step.
+
+export const bugCount = (count: number): string => `${count} bug${count === 1 ? "" : "s"}`;
+
+/** "Our moles found 3 bugs" / "No bugs hiding here". */
+export const molesFound = (count: number): string =>
+  count > 0 ? `Our moles found ${bugCount(count)}` : NO_BUGS;
+
+export const NO_BUGS = "No bugs hiding here";
+
+/** What a run in progress is doing: "Digging for bugs in shop.example.com…". */
+export const digging = (where?: string | null): string =>
+  where ? `Digging for bugs in ${where}…` : "Digging for bugs…";
+
+/** "Our moles ate 3 bugs"; without a count, "Our moles ate the bugs". */
+export const molesAte = (count?: number | null): string =>
+  count && count > 0 ? `Our moles ate ${bugCount(count)}` : "Our moles ate the bugs";

package/src/runtime/nav-crawl.test.ts

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { extractLinks, normalizeCrawledHref } from "./nav-crawl.js";
+import { entranceRank } from "./explorer.js";
+
+const BASE = "http://localhost:3020";
+
+test("keeps in-app navigation and drops the query string, since it is the same screen", () => {
+  assert.equal(normalizeCrawledHref("/plans?project=bugmole&environment=all", BASE), "/plans");
+  assert.equal(normalizeCrawledHref("/parity/issues?project=x", BASE), "/parity/issues");
+  assert.equal(normalizeCrawledHref("http://localhost:3020/tasks", BASE), "/tasks");
+});
+
+test("the root route normalises to /", () => {
+  assert.equal(normalizeCrawledHref("/", BASE), "/");
+  assert.equal(normalizeCrawledHref("/?project=bugmole", BASE), "/");
+  assert.equal(normalizeCrawledHref("/plans/", BASE), "/plans");
+});
+
+test("build output and static assets are not screens", () => {
+  for (const href of [
+    "/_next/static/chunks/webpack.js?v=1",
+    "/_next/static/css/app/layout.css",
+    "/favicon.png",
+    "/bugmole-logo.png",
+    "/report.pdf",
+  ]) {
+    assert.equal(normalizeCrawledHref(href, BASE), null, `${href} must not be treated as a route`);
+  }
+});
+
+test("cross-origin and non-navigational hrefs are dropped", () => {
+  assert.equal(normalizeCrawledHref("https://example.com/plans", BASE), null);
+  assert.equal(normalizeCrawledHref("mailto:a@b.com", BASE), null);
+  assert.equal(normalizeCrawledHref("javascript:void(0)", BASE), null);
+  assert.equal(normalizeCrawledHref("#section", BASE), null);
+  assert.equal(normalizeCrawledHref("", BASE), null);
+});
+
+test("reads the app's own label for each destination", () => {
+  // Shaped like the dashboard's real rendered nav, including the computed
+  // hrefs the source scan cannot see.
+  const html = `
+    <nav>
+      <a class="active" href="/?project=bugmole&amp;environment=all">Overview</a>
+      <a href="/plans?project=bugmole&amp;environment=all">Test plans</a>
+      <a href="/tasks?project=bugmole&amp;environment=all"><span>Agent</span> tasks</a>
+      <a href="/_next/static/chunks/webpack.js">ignored</a>
+      <a href="https://storybook.js.org/">external</a>
+    </nav>`;
+  const links = extractLinks(html, BASE);
+  const byRoute = new Map(links.map((link) => [link.route, link.label]));
+  assert.deepEqual([...byRoute.keys()].sort(), ["/", "/plans", "/tasks"]);
+  assert.equal(byRoute.get("/"), "Overview");
+  assert.equal(byRoute.get("/plans"), "Test plans");
+  // Nested markup still yields the human label.
+  assert.equal(byRoute.get("/tasks"), "Agent tasks");
+});
+
+test("the same destination is reported once, preferring a real label", () => {
+  const html = `
+    <a href="/plans"></a>
+    <a href="/plans?project=x">Test plans</a>`;
+  const links = extractLinks(html, BASE);
+  assert.equal(links.length, 1);
+  assert.equal(links[0].label, "Test plans");
+});
+
+test("a declared entrance outranks everything — the project stating its own start", () => {
+  const declared = new Set(["/dashboard"]);
+  const dashboard = entranceRank({ id: "d", route: "/dashboard" }, { declaredEntranceRoutes: declared });
+  const root = entranceRank({ id: "r", route: "/" }, { declaredEntranceRoutes: declared });
+  assert.ok(dashboard < root, "declared entrance should win");
+});
+
+test("the app root beats a leaf page — this is the reported bug", () => {
+  // Previously /api-keys won purely because nothing linked to it, so the
+  // journeys started at a settings page and ended at the home page.
+  const inbound = new Map([["root", 6]]);
+  const root = entranceRank({ id: "root", route: "/" }, { inboundCounts: inbound });
+  const apiKeys = entranceRank({ id: "keys", route: "/api-keys" }, { inboundCounts: inbound });
+  assert.ok(root < apiKeys, "the application root must outrank a settings page");
+});
+
+test("the mobile app's own conventions still win when present, so it is not regressed", () => {
+  const onboarding = entranceRank({ id: "o", route: "/onboarding", variant: "auth" });
+  const tabs = entranceRank({ id: "t", route: "/", variant: "tabs" });
+  const plainRoot = entranceRank({ id: "r2", route: "/" });
+  assert.ok(onboarding < tabs, "auth onboarding stays the first entry");
+  assert.ok(tabs < plainRoot, "the tabs root stays ahead of a generic root");
+});
+
+test("a hub outranks a leaf when neither is the root", () => {
+  const inbound = new Map([["hub", 5], ["leaf", 1]]);
+  const hub = entranceRank({ id: "hub", route: "/hub" }, { inboundCounts: inbound });
+  const leaf = entranceRank({ id: "leaf", route: "/leaf" }, { inboundCounts: inbound });
+  const orphan = entranceRank({ id: "orphan", route: "/orphan" }, { inboundCounts: inbound });
+  assert.ok(hub < leaf, "more inbound navigation means a stronger entrance");
+  assert.ok(leaf < orphan, "a linked page still beats one nothing links to");
+});

package/src/runtime/nav-crawl.ts

@@ -0,0 +1,153 @@
+/**
+ * Navigation read from the running application.
+ *
+ * The source scan can only see link literals. This dashboard builds its
+ * primary navigation from a route table (`href={hrefFor(value)}`), so the
+ * scan found none of it and fell back to the handful of hardcoded links in
+ * the account dropdown — which is why every discovered flow began at a
+ * settings page. Once rendered, those hrefs are real strings, so the DOM
+ * is where navigation can honestly be read.
+ *
+ * This runs last, after the project's declared intent has been read: docs
+ * say what matters, the crawl says what exists.
+ */
+import { dumpRenderedDom, mapWithConcurrency, resolveCaptureConcurrency } from "./journey-evidence.js";
+
+/** Assets are not navigation, and would otherwise become phantom screens. */
+const ASSET_PATTERN = /\.(png|jpe?g|gif|svg|webp|avif|ico|css|js|mjs|map|woff2?|ttf|otf|json|txt|xml|pdf)$/i;
+
+export type CrawledLink = {
+  /** Route the anchor points at, normalised. */
+  route: string;
+  /** Anchor text, which is the app's own name for the destination. */
+  label?: string;
+};
+
+export type NavCrawlResult = {
+  /** Links found per starting route. */
+  linksByRoute: Map<string, CrawledLink[]>;
+  /** Routes that were successfully rendered. */
+  visited: string[];
+  /** Routes that could not be rendered, with why. */
+  failed: Array<{ route: string; reason: string }>;
+};
+
+/**
+ * Normalise an href to a comparable route, or null if it is not in-app
+ * navigation. Query strings and fragments are dropped: `/plans?project=x`
+ * and `/plans` are the same screen.
+ */
+export function normalizeCrawledHref(href: string, baseUrl: string): string | null {
+  const raw = href?.trim();
+  if (!raw) return null;
+  if (/^(mailto:|tel:|javascript:|data:|blob:)/i.test(raw)) return null;
+  if (raw.startsWith("#")) return null;
+
+  let url: URL;
+  try {
+    url = new URL(raw, baseUrl);
+  } catch {
+    return null;
+  }
+  // Only same-origin links are this app's navigation.
+  try {
+    if (url.origin !== new URL(baseUrl).origin) return null;
+  } catch {
+    return null;
+  }
+  const pathname = url.pathname;
+  // Framework build output and static files are not screens.
+  if (pathname.startsWith("/_next/") || pathname.startsWith("/__")) return null;
+  if (ASSET_PATTERN.test(pathname)) return null;
+  const trimmed = pathname.length > 1 ? pathname.replace(/\/+$/, "") : "/";
+  return trimmed || "/";
+}
+
+/**
+ * Build the URL to crawl, carrying over any query the base URL sets.
+ *
+ * An app can need context before it will render anything real: this
+ * dashboard shows "No projects available" until `?project=` is present.
+ * Crawling bare routes therefore produced an empty shell for the home page
+ * and attributed the whole navigation to whichever page happened to render
+ * — so the base URL's query is propagated to every route rather than
+ * dropped.
+ */
+export function resolveCrawlUrl(route: string, baseUrl: string): string {
+  const base = new URL(baseUrl);
+  const url = new URL(route, base);
+  for (const [key, value] of base.searchParams) {
+    if (!url.searchParams.has(key)) url.searchParams.set(key, value);
+  }
+  return url.toString();
+}
+
+/** Anchors from rendered HTML, with their visible text. */
+export function extractLinks(html: string, baseUrl: string): CrawledLink[] {
+  const found = new Map<string, CrawledLink>();
+  for (const match of html.matchAll(/<a\b[^>]*href\s*=\s*"([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi)) {
+    const route = normalizeCrawledHref(decodeHtml(match[1]), baseUrl);
+    if (!route) continue;
+    const label = decodeHtml(match[2].replace(/<[^>]*>/g, " ")).replace(/\s+/g, " ").trim();
+    const existing = found.get(route);
+    if (!existing || (!existing.label && label)) {
+      found.set(route, { route, label: label || existing?.label });
+    }
+  }
+  return [...found.values()];
+}
+
+function decodeHtml(value: string): string {
+  return value
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#0?39;|&apos;/g, "'");
+}
+
+/**
+ * Render each route and read its navigation.
+ *
+ * Bounded on purpose: every dump launches a headless Chrome, and each of
+ * those spawns a dozen OS processes. An unbounded pass over a graph of
+ * this size previously produced hundreds of simultaneous Chrome processes,
+ * so this reuses the same worker pool and budget as screenshot capture
+ * rather than introducing a second unbounded launcher.
+ */
+export async function crawlNavigation(
+  baseUrl: string,
+  routes: string[],
+  options: { concurrency?: number; maxRoutes?: number; timeoutMs?: number } = {},
+): Promise<NavCrawlResult> {
+  const limit = options.concurrency ?? resolveCaptureConcurrency();
+  const maxRoutes = options.maxRoutes ?? 40;
+  // Concrete routes only: a parameterised route has no real URL to visit
+  // without inventing an id, and a guessed id is not evidence.
+  const targets = routes
+    .filter((route) => !/[[:*]/.test(route))
+    .slice(0, maxRoutes);
+
+  const linksByRoute = new Map<string, CrawledLink[]>();
+  const visited: string[] = [];
+  const failed: Array<{ route: string; reason: string }> = [];
+
+  await mapWithConcurrency(targets, limit, async (route) => {
+    let url: string;
+    try {
+      url = resolveCrawlUrl(route, baseUrl);
+    } catch {
+      failed.push({ route, reason: "Route could not be resolved against the base URL" });
+      return;
+    }
+    try {
+      const html = await dumpRenderedDom(url, options.timeoutMs);
+      linksByRoute.set(route, extractLinks(html, baseUrl));
+      visited.push(route);
+    } catch (error) {
+      failed.push({ route, reason: error instanceof Error ? error.message : "Rendered DOM could not be read" });
+    }
+  });
+
+  return { linksByRoute, visited, failed };
+}