@bugmole/cli 0.4.0

package/src/runtime/planner.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { driverForPlatform } from "./planner.js";
+
+test("a web plan is never pinned to the mobile driver", () => {
+  // bugmole.config defaults execution.driver to "maestro" while the plan
+  // itself writes platform "web". Taking that verbatim produced 18 plans that
+  // could only ever fail with "requires a flow reference", blocking 53 cases
+  // that were never really checked.
+  assert.equal(driverForPlatform("maestro", "web"), "playwright");
+});
+
+test("a configured driver is honoured when it can drive the platform", () => {
+  assert.equal(driverForPlatform("playwright", "web"), "playwright");
+  assert.equal(driverForPlatform("maestro", "ios"), "maestro");
+  assert.equal(driverForPlatform("maestro", "android"), "maestro");
+});
+
+test("simulation stays available on every platform, since it drives none of them for real", () => {
+  assert.equal(driverForPlatform("simulation", "web"), "simulation");
+  assert.equal(driverForPlatform("simulation", "ios"), "simulation");
+});
+
+test("a mobile platform does not fall back to a browser driver", () => {
+  assert.equal(driverForPlatform("playwright", "ios"), "maestro");
+});
+
+test("no configured driver picks the one that fits the platform", () => {
+  assert.equal(driverForPlatform(undefined, "web"), "playwright");
+  assert.equal(driverForPlatform(undefined, "android"), "maestro");
+});
+
+test("an unknown platform is treated as web rather than defaulting to mobile", () => {
+  // Guessing mobile for something unrecognised is how this failed in the
+  // first place: the driver that cannot run without a device file.
+  assert.equal(driverForPlatform(undefined, "desktop"), "playwright");
+});

package/src/runtime/planner.ts

@@ -0,0 +1,274 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import { ControlPlaneClient } from "../registry/control-plane-client.js";
+import { nextJourneyTask } from "./journey-editor.js";
+
+/** Drivers that can actually operate each kind of target. */
+const DRIVERS_BY_PLATFORM: Record<string, string[]> = {
+  web: ["playwright", "simulation"],
+  ios: ["maestro", "simulation"],
+  android: ["maestro", "simulation"],
+};
+
+/**
+ * Pick the driver a plan should run under.
+ *
+ * The configured driver is a preference, not an instruction: bugmole.config
+ * defaults it to `maestro`, which is a mobile runner, while this same plan
+ * writes `platform: web`. Honouring that verbatim produced 18 web plans
+ * pinned to maestro, and every run of them died the same way — `Driver
+ * "maestro" requires a flow reference (missing_flow)` — blocking 53 test
+ * cases that were never actually checked.
+ *
+ * A plan that cannot possibly execute is worse than one that ignores a
+ * contradictory setting, so the platform wins when the two disagree.
+ */
+export function driverForPlatform(configured: string | undefined, platform: string): string {
+  const usable = DRIVERS_BY_PLATFORM[platform] ?? DRIVERS_BY_PLATFORM.web;
+  if (configured && usable.includes(configured)) return configured;
+  return usable[0];
+}
+
+interface PlanOptions {
+  journeyId: string;
+  actor: string;
+  revision?: number;
+}
+
+interface PlanResult {
+  status: "success" | "error";
+  planId?: string;
+  planPath?: string;
+  message?: string;
+  error?: string;
+  nextSteps?: string[];
+}
+
+/**
+ * Planner: Converts graph paths into flow plans with prerequisites and variants
+ */
+export async function plan(cfg: any, options: PlanOptions): Promise<PlanResult> {
+  try {
+    const { journeyId, actor } = options;
+    const specDir = cfg.runtime.spec_dir || "./spec";
+    const plansDir = path.join(specDir, "plans");
+    const graphPath = path.join(specDir, "journeys.graph.json");
+
+    // Ensure plans directory exists
+    fs.mkdirSync(plansDir, { recursive: true });
+
+    // Load journey graph
+    if (!fs.existsSync(graphPath)) {
+      return {
+        status: "error",
+        error: "Journey graph not found. Run exploration first.",
+      };
+    }
+
+    const graphContent = fs.readFileSync(graphPath, "utf-8");
+    const graph = JSON.parse(graphContent);
+    const discoveredNodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+    const discoveredEdges = Array.isArray(graph.edges) ? graph.edges : [];
+    const selectedJourney = Array.isArray(graph.journeys)
+      ? graph.journeys.find((journey: any) => journey.id === journeyId)
+      : undefined;
+    if (!selectedJourney) {
+      return {
+        status: "error",
+        error: `Journey "${journeyId}" is not present in the discovered flow graph.`,
+        nextSteps: ["Select an existing journey or record the selected journey before planning."],
+      };
+    }
+    if (selectedJourney.stability !== "stable" || selectedJourney.linkedToGraph !== true) {
+      return {
+        status: "error",
+        error: `Journey "${journeyId}" is not stabilized. Execute and adjust the canonical flow until it is stable before planning.`,
+        nextSteps: [
+          `Run the canonical flow "${journeyId}"`,
+          "Adjust the flow for any failures and rerun it",
+          "Mark the verified run as the stabilized canonical flow",
+        ],
+      };
+    }
+    const flowState = nextJourneyTask(cfg, journeyId);
+    if (flowState.status === "actionable") {
+      return {
+        status: "error",
+        error: "Planning is blocked while the selected journey still has an actionable exploration task.",
+        nextSteps: flowState.nextSteps,
+      };
+    }
+    if (discoveredNodes.length === 0 && discoveredEdges.length === 0) {
+      return {
+        status: "error",
+        error: "Planning is blocked because repository/application exploration has not discovered a journey yet.",
+        nextSteps: [
+          "Read bugmole://guidance/agent-testing",
+          "Inspect the repository entrypoints, routes, and relevant specs",
+          "Run bugmole_explore with the application's runnable base URL",
+          "Report progress and follow the returned next_steps before retrying bugmole_plan",
+        ],
+      };
+    }
+
+    // Load roles to validate actor
+    const rolesPath = path.join(specDir, "roles.yaml");
+    if (!fs.existsSync(rolesPath)) {
+      return {
+        status: "error",
+        error: "Roles file not found. Define roles first.",
+        nextSteps: ["Create roles.yaml from the guided testing workflow, then retry planning."],
+      };
+    }
+    const roles = YAML.parse(fs.readFileSync(rolesPath, "utf-8"));
+    const knownActors = Array.isArray(roles?.roles)
+      ? roles.roles.map((role: any) => role?.name).filter((name: unknown): name is string => typeof name === "string")
+      : [];
+    if (!knownActors.includes(actor)) {
+      return {
+        status: "error",
+        error: `Actor "${actor}" is not defined in roles.yaml.`,
+        nextSteps: [
+          `Read roles.yaml and choose one of: ${knownActors.join(", ") || "(none defined)"}`,
+          "Retry planning with a defined actor",
+        ],
+      };
+    }
+
+    // Build a plan from discovered graph evidence. A fallback action is not
+    // acceptable because it would publish a plan the worker cannot justify.
+    const selectedEdgeIds = new Set<string>(selectedJourney?.edgeIds ?? []);
+    const graphSteps = discoveredEdges
+      .filter((edge: any) => selectedJourney
+        ? selectedEdgeIds.has(edge.id)
+        : String(edge.to ?? edge.target ?? "").includes(journeyId)
+          || String(edge.from ?? edge.source ?? "").includes(journeyId))
+      .slice(0, 12)
+      .map((edge: any, index: number) => ({
+        node_id: selectedJourney?.nodeIds?.[index],
+        action: edge.action || `navigate:${edge.to ?? "next-screen"}`,
+        proofs: [
+          { type: "navigation", expects: edge.to ?? "next-screen" },
+          { type: "dom", expects: `screen source: ${edge.source ?? "discovered application code"}` },
+        ],
+      }));
+    if (graphSteps.length === 0) {
+      return {
+        status: "error",
+        error: `No discovered graph actions match journey "${journeyId}". Planning is blocked to prevent a generic fallback plan.`,
+        nextSteps: [
+          "Use the authenticated owner session to explore the dashboard screens and actions",
+          "Update journeys.graph.json with concrete owner transitions and proof requirements",
+          `Retry planning for "${journeyId}" after matching edges are present`,
+        ],
+      };
+    }
+    const steps = graphSteps;
+    const planId = journeyId.replace(/[^a-z0-9._-]/gi, "_").toLowerCase();
+    const planPath = path.join(plansDir, `${planId}.flow.yaml`);
+
+    const plan = {
+      version: 2,
+      id: planId,
+      name: `Journey: ${journeyId}`,
+      description: `Generated plan for journey ${journeyId} with actor ${actor}`,
+      driver: driverForPlatform(cfg.execution?.driver, cfg.project?.platform || "web"),
+      platform: cfg.project?.platform || "web",
+      target: {
+        base_url: cfg.project?.base_url || cfg.execution?.playwright?.base_url,
+        app_id: cfg.project?.app_id,
+        device_id: cfg.project?.device_id,
+        serial: cfg.project?.serial,
+      },
+      flow: cfg.execution?.maestro?.flow || null,
+      recovery: {
+        enabled: cfg.execution?.recovery?.enabled === true,
+        max_attempts: cfg.execution?.recovery?.max_attempts ?? 1,
+        timeout_ms: cfg.execution?.recovery?.timeout_ms ?? 30_000,
+      },
+      journey_revision: options.revision ?? selectedJourney?.revision ?? 1,
+      suites: [
+        {
+          id: "default",
+          runs: "on_demand",
+          journeys: [
+            {
+              id: journeyId,
+              actor: actor,
+              goal: `Complete journey: ${journeyId}`,
+              capabilities_required: [],
+              preconditions: ["Test tenant / sandbox is active", "Actor account exists"],
+              steps,
+            },
+          ],
+        },
+      ],
+    };
+
+    // Write plan file
+    const yamlContent = YAML.stringify(plan);
+    fs.writeFileSync(planPath, yamlContent, "utf-8");
+    const objectKey = `${projectPrefix(cfg.project?.id ?? "default")}/plans/${planId}.flow.yaml`;
+    const store = createProjectObjectStore(cfg);
+    await store.put(objectKey, yamlContent, "text/yaml");
+    // A cloud worker reads the flow from the store as well, so publish it next to the plan.
+    const flowReference = typeof plan.flow === "string" ? plan.flow : undefined;
+    if (flowReference && !path.isAbsolute(flowReference)) {
+      const localFlow = path.resolve(cfg.runtime?.spec_dir || "./spec", flowReference);
+      if (fs.existsSync(localFlow)) {
+        const flowKey = `${projectPrefix(cfg.project?.id ?? "default")}/spec/${flowReference.replaceAll("\\", "/").replace(/^\/+/, "")}`;
+        await store.put(flowKey, fs.readFileSync(localFlow), "text/yaml");
+      }
+    }
+    const apiKey = process.env.BUGMOLE_API_KEY?.trim();
+    const registryUrl = process.env.BUGMOLE_REGISTRY_URL?.trim();
+    if (apiKey && registryUrl) {
+      const client = new ControlPlaneClient({
+        registryUrl,
+        apiKey,
+        projectId: cfg.project?.id ?? "default",
+      });
+      await client.publishPlan({ planId, journeyId, objectKey });
+      const unresolvedLinks = Array.isArray(graph.metadata?.analysis?.unresolvedLinks)
+        ? graph.metadata.analysis.unresolvedLinks
+        : [];
+      const blockedNodes = discoveredNodes.filter((node: any) => node.runtimeProbe?.status === "blocked");
+      const followUps = [
+        ...(unresolvedLinks.length ? [{
+          title: `Resolve ${unresolvedLinks.length} unresolved journey links`,
+          description: "Validate unresolved navigation targets during the next Lumis exploration and update the sitemap.",
+          taskType: "investigation" as const,
+          priority: 8,
+          idempotencyKey: `${journeyId}:${options.revision ?? selectedJourney?.revision ?? 1}:unresolved-links`,
+        }] : []),
+        ...(blockedNodes.length ? [{
+          title: `Verify ${blockedNodes.length} authenticated journey routes`,
+          description: "Provide the approved authenticated environment/session and rerun route and screenshot verification.",
+          taskType: "ui" as const,
+          priority: 9,
+          idempotencyKey: `${journeyId}:${options.revision ?? selectedJourney?.revision ?? 1}:blocked-routes`,
+        }] : []),
+      ];
+      await Promise.all(followUps.map((task) => client.createTask({
+        ...task,
+        journeyId,
+        journeyRevision: options.revision ?? selectedJourney?.revision ?? 1,
+      })));
+    }
+
+    return {
+      status: "success",
+      planId: planId,
+      planPath: `plans/${planId}.flow.yaml`,
+      message: `Plan created at ${planPath}. Review and customize as needed.${apiKey && registryUrl ? " Published to the dashboard." : ""}`,
+    };
+  } catch (error: any) {
+    return {
+      status: "error",
+      error: error.message || "Planning failed",
+    };
+  }
+}

package/src/runtime/platform-ai.ts

@@ -0,0 +1,76 @@
+// Chooses who pays for a piece of AI work: the project's own model key when
+// one is configured (free), otherwise Bugmole's model account through the
+// registry, charged in credits (see src/billing/plan-catalog.ts).
+import type { AiAction } from "../billing/plan-catalog.js";
+import { analysisModel } from "./ai-analysis.js";
+import { callModelWithUsage } from "./llm.js";
+
+export type ModelCallIds = { projectId: string; runId?: string; requestId?: string; targetId?: string };
+export type ModelCall = (prompt: string, purpose: AiAction) => Promise<{ text: string; model: string; source: "own" | "platform" }>;
+
+export class PlatformAiError extends Error {
+  constructor(message: string, readonly status: number, readonly code?: string) {
+    super(message);
+    this.name = "PlatformAiError";
+  }
+}
+
+type PlatformEnv = Record<string, string | undefined>;
+
+export function platformAiEnabled(env: PlatformEnv = process.env): boolean {
+  if ((env.BUGMOLE_PLATFORM_AI ?? "").toLowerCase() === "off") return false;
+  return Boolean(env.BUGMOLE_REGISTRY_URL?.trim() && (env.BUGMOLE_RUN_TOKEN?.trim() || env.BUGMOLE_API_KEY?.trim()));
+}
+
+export function platformModelCall(ids: ModelCallIds, env: PlatformEnv = process.env, doFetch: typeof fetch = fetch): ModelCall | null {
+  if (!platformAiEnabled(env)) return null;
+  const registryUrl = env.BUGMOLE_REGISTRY_URL!.trim().replace(/\/$/, "");
+  const token = env.BUGMOLE_RUN_TOKEN?.trim() || env.BUGMOLE_API_KEY!.trim();
+  return async (prompt, purpose) => {
+    const response = await doFetch(`${registryUrl}/api/ai/complete`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+      body: JSON.stringify({ purpose, prompt, ...ids }),
+      signal: AbortSignal.timeout(purpose === "exploration" ? 150_000 : 75_000),
+    });
+    const body = await response.json().catch(() => ({})) as { text?: string; model?: string; error?: string; code?: string };
+    if (!response.ok) throw new PlatformAiError(body.error ?? `Bugmole AI returned ${response.status}`, response.status, body.code);
+    return { text: body.text ?? "", model: body.model ?? "bugmole", source: "platform" };
+  };
+}
+
+/** The project's own model when configured, else Bugmole AI, else null. */
+export function modelCaller(cfg: any, ids: ModelCallIds, env: PlatformEnv = process.env): ModelCall | null {
+  const own = analysisModel(cfg);
+  if (own) {
+    return async (prompt, purpose) => {
+      const reply = await callModelWithUsage(prompt, {
+        provider: own.provider,
+        model: own.model,
+        apiKey: own.api_key,
+        baseUrl: own.base_url,
+        timeout: purpose === "exploration" ? 150_000 : 60_000,
+        maxTokens: purpose === "exploration" ? 8_000 : purpose === "repair" ? 2_000 : 600,
+      });
+      return { text: reply.text, model: own.model, source: "own" };
+    };
+  }
+  return platformModelCall(ids, env);
+}
+
+/** The first JSON object in a model reply, tolerating code fences and prose. */
+export function extractJson(text: string): unknown {
+  const body = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "");
+  for (const [open, close] of [["{", "}"], ["[", "]"]] as const) {
+    const start = body.indexOf(open);
+    const end = body.lastIndexOf(close);
+    if (start >= 0 && end > start) {
+      try {
+        return JSON.parse(body.slice(start, end + 1));
+      } catch {
+        // try the other shape
+      }
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,93 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { isMissingVideoEncoder, parseMaestroStyleFlow, PlaywrightDriver } from "./playwright-driver.js";
+
+test("parses a Maestro-style flow with url header", () => {
+  const flow = parseMaestroStyleFlow(`
+url: http://localhost:3010
+---
+- launchApp
+- tapOn: "Upload Template"
+- inputText: "hello"
+- assertVisible: "Consulting v2"
+`);
+  assert.equal(flow.url, "http://localhost:3010");
+  assert.deepEqual(flow.steps, [
+    { type: "launchApp" },
+    { type: "tapOn", text: "Upload Template", index: 0, optional: false },
+    { type: "inputText", text: "hello" },
+    { type: "assertVisible", text: "Consulting v2", timeoutMs: undefined },
+  ]);
+});
+
+test("falls back to the driver target base URL when the flow header declares neither url nor appId", () => {
+  const flow = parseMaestroStyleFlow(
+    `
+name: some-flow
+---
+- launchApp
+`,
+    "http://localhost:4000",
+  );
+  assert.equal(flow.url, "http://localhost:4000");
+});
+
+test("rejects a flow missing the '---' document separator", () => {
+  assert.throws(() => parseMaestroStyleFlow("url: http://localhost\n- launchApp"), /header document and a steps document/);
+});
+
+test("rejects an unsupported step", () => {
+  assert.throws(
+    () => parseMaestroStyleFlow('url: http://localhost\n---\n- swipeLeft: "x"\n'),
+    /Unsupported flow step/,
+  );
+});
+
+test("only supports the web platform", () => {
+  const driver = new PlaywrightDriver();
+  assert.equal(driver.supports("web"), true);
+  assert.equal(driver.supports("android"), false);
+  assert.equal(driver.supports("ios"), false);
+});
+
+test("blocks with a clear reason for a non-web platform", async () => {
+  const driver = new PlaywrightDriver();
+  const result = await driver.run({
+    runId: "run-1",
+    projectId: "demo",
+    journeyId: "checkout",
+    flowPath: "/tmp/does-not-matter.yaml",
+    platform: "android",
+    target: {},
+    timeoutMs: 10_000,
+    artifactsDir: "/tmp/bugmole-runs",
+  });
+  assert.equal(result.status, "blocked");
+  assert.equal(result.failureCode, "unsupported_platform");
+});
+
+test("blocks with a clear reason when the flow file is missing", async () => {
+  const driver = new PlaywrightDriver();
+  const result = await driver.run({
+    runId: "run-1",
+    projectId: "demo",
+    journeyId: "checkout",
+    flowPath: "/tmp/definitely-does-not-exist.yaml",
+    platform: "web",
+    target: { baseUrl: "http://localhost:3010" },
+    timeoutMs: 10_000,
+    artifactsDir: "/tmp/bugmole-runs",
+  });
+  assert.equal(result.status, "blocked");
+  assert.equal(result.failureCode, "invalid_flow");
+});
+
+test("a worker without Playwright's ffmpeg loses the video, not the run", () => {
+  const playwrightError = new Error(
+    "browserContext.newPage: Executable doesn't exist at /home/runner/.cache/ms-playwright/ffmpeg-1011/ffmpeg-linux\n" +
+      "╔═════════════════════════════════════╗\n║ Video rendering requires ffmpeg binary. ║\n╚═════════════════════════════════════╝",
+  );
+  assert.equal(isMissingVideoEncoder(playwrightError), true);
+  assert.equal(isMissingVideoEncoder(new Error("Executable doesn't exist at /ms-playwright/chromium-1234/chrome-linux/chrome")), false);
+  assert.equal(isMissingVideoEncoder(new Error("net::ERR_CONNECTION_REFUSED")), false);
+});