@bugmole/cli 0.4.0 → 0.6.0

package/src/runtime/discovery-task.ts

@@ -6,9 +6,10 @@ import { createProjectObjectStore } from "../storage/create-object-store.js";
 import { projectPrefix } from "../storage/keys.js";
 import { readJourneyGraph, writeJourneyGraph } from "./journey-editor.js";
 import type { JourneyEdge, JourneyNode, UserJourney } from "./journey-graph.js";
-import { discoverSite, type DiscoveryResult } from "./site-discovery.js";
-import { explorationPrompt, parseExploration, type ExplorationPersona } from "./ai-exploration.js";
+import { discoverSite, stoppedAtSignIn, type DiscoveryLimits, type DiscoveryResult } from "./site-discovery.js";
+import { explorationPrompt, parseCheckedExploration, type ExplorationPersona } from "./ai-exploration.js";
 import { modelCaller } from "./platform-ai.js";
+import { proposeRoleSuggestions } from "./project-roles.js";
 
 /** Discovery tasks queued as "Explore with AI …" also have a model write multi-page journeys. */
 export function discoveryUsesAi(task: Pick<RegistryTask, "title">): boolean {
@@ -69,6 +70,8 @@ export type DiscoveryProgress = {
   events: DiscoveryResult["events"];
   pages: Array<{ route: string; title: string; heading?: string; forms: number }>;
   flows: Array<{ id: string; name: string; kind: "page" | "form" | "journey"; route: string; steps: string[]; planId?: string }>;
+  /** Present once the crawl has finished: the bounds it ran with and what they left out. */
+  limits?: Omit<DiscoveryLimits, "notFollowed"> & { notFollowed: number; notFollowedRoutes: string[] };
 };
 
 export function progressOf(url: string, result: DiscoveryResult, planIds: Record<string, string> = {}): DiscoveryProgress {
@@ -79,6 +82,18 @@ export function progressOf(url: string, result: DiscoveryResult, planIds: Record
     events: result.events.slice(-40),
     pages: result.pages.map((page) => ({ route: page.route, title: page.title, ...(page.heading ? { heading: page.heading } : {}), forms: page.forms.length })),
     flows: result.flows.map((flow) => ({ id: flow.id, name: flow.name, kind: flow.kind, route: flow.route, steps: flow.steps, ...(planIds[flow.id] ? { planId: planIds[flow.id] } : {}) })),
+    ...(result.limits
+      ? {
+        limits: {
+          maxPages: result.limits.maxPages,
+          maxDepth: result.limits.maxDepth,
+          stoppedAtPageLimit: result.limits.stoppedAtPageLimit,
+          notFollowed: result.limits.notFollowed.length,
+          // A sample is enough to show which; every update carries it.
+          notFollowedRoutes: result.limits.notFollowed.slice(0, 20),
+        },
+      }
+      : {}),
   };
 }
 
@@ -191,7 +206,7 @@ export async function saveDiscovery(cfg: WorkerConfig, client: Pick<ControlPlane
  */
 export async function runDiscoveryTask(
   cfg: WorkerConfig,
-  client: Pick<ControlPlaneClient, "claimTask" | "updateTask" | "publishPlan">,
+  client: Pick<ControlPlaneClient, "claimTask" | "updateTask" | "publishPlan"> & Partial<Pick<ControlPlaneClient, "proposeRole">>,
   task: RegistryTask,
   workerId: string,
   discover: typeof discoverSite = discoverSite,
@@ -200,6 +215,16 @@ export async function runDiscoveryTask(
     claimed?: boolean;
     /** Called once if the registry answers an update with `stop`. */
     onStop?: (signal: { reason: string; message: string }) => void;
+    /**
+     * Signs in before exploring (a cloud runner with the project's sign-in
+     * flow) and returns the saved browser session to explore in.
+     */
+    signIn?: (url: string) => Promise<string>;
+    /**
+     * How far to explore: the workspace plan's bounds on Bugmole Cloud, the
+     * machine's own settings on a project worker. Discovery's defaults otherwise.
+     */
+    limits?: { maxPages?: number; maxDepth?: number };
   } = {},
 ): Promise<void> {
   const url = discoveryUrl(task);
@@ -242,13 +267,60 @@ export async function runDiscoveryTask(
   heartbeat.unref?.();
   try {
     await send("running");
+    // Sign-in happens before discovery has a result to report into, so its
+    // events are kept here and put in front of discovery's own.
+    const before: DiscoveryResult["events"] = [];
+    let storageState: string | undefined;
+    if (options.signIn) {
+      before.push({ at: new Date().toISOString(), kind: "visit", text: "Signing in with the project's sign-in flow…" });
+      latest = progressOf(url, { baseUrl: url, pages: [], flows: [], events: before });
+      await send("running");
+      storageState = await options.signIn(url);
+      before.push({ at: new Date().toISOString(), kind: "visit", text: "Signed in; exploring as a signed-in user" });
+    }
     const result = await discover(url, {
+      ...(storageState ? { storageState } : {}),
+      ...(options.limits?.maxPages ? { maxPages: options.limits.maxPages } : {}),
+      ...(options.limits?.maxDepth ? { maxDepth: options.limits.maxDepth } : {}),
       onEvent: async (_event, snapshot) => {
-        latest = progressOf(url, snapshot);
+        latest = progressOf(url, { ...snapshot, events: [...before, ...snapshot.events] });
         await send("running");
       },
     });
-    if (discoveryUsesAi(task)) {
+    result.events.unshift(...before);
+    // Everything reachable was a sign-in screen. Say so plainly, and don't
+    // ask AI to imagine the app behind it: that spends credits on journeys
+    // through pages nobody has seen.
+    const signInWall = stoppedAtSignIn(result);
+    if (signInWall) {
+      result.events.push({
+        at: new Date().toISOString(),
+        kind: "skip",
+        text: storageState
+          ? "Stopped at a sign-in page even after the sign-in flow passed, so everything behind it is unexplored. "
+            + "Check that the sign-in flow ends signed in (assert something only a signed-in user sees)."
+          : "Stopped at a sign-in page, so everything behind it is unexplored. To explore signed in, add a sign-in flow and its secrets "
+            + "under Settings → Sign-in for cloud runs, or run discovery from your machine or CI: bugmole --mode discover --sign-in <flow>.",
+      });
+      latest = progressOf(url, result);
+      await send("running");
+      // A sign-in wall says the app has signed-out and signed-in people:
+      // suggest both roles for a person to confirm on the Roles page.
+      if (client.proposeRole && !storageState) {
+        const evidence = `Exploring ${url} reached only a sign-in page`;
+        const proposed = await proposeRoleSuggestions([
+          { name: "guest", description: "Visitor who is not signed in and only sees public screens.", source: "sign_in_wall", evidence },
+          { name: "member", description: "Signed-in user who gets past the sign-in wall.", source: "sign_in_wall", evidence },
+        ], { proposeRole: client.proposeRole.bind(client) }).catch(() => []);
+        const sent = proposed.filter((role) => role.status === "suggested" && !role.alreadyDecided).map((role) => role.name);
+        if (sent.length) {
+          result.events.push({ at: new Date().toISOString(), kind: "flows", text: `Suggested the roles ${sent.join(" and ")} for you to confirm under Settings → Roles` });
+          latest = progressOf(url, result);
+          await send("running");
+        }
+      }
+    }
+    if (discoveryUsesAi(task) && !signInWall) {
       const caller = modelCaller(cfg, { projectId: cfg.project?.id ?? "default", requestId: task.id });
       const note = (text: string, kind: "flows" | "error") => {
         result.events.push({ at: new Date().toISOString(), kind, text });
@@ -262,9 +334,13 @@ export async function runDiscoveryTask(
         await note(persona ? `Asking AI for multi-page journeys as ${persona.name}…` : "Asking AI for multi-page journeys…", "flows");
         try {
           const reply = await caller(explorationPrompt(result, persona ?? undefined), "exploration");
-          const journeys = parseExploration(reply.text, result.baseUrl, result.flows);
+          const { flows: journeys, setAside } = parseCheckedExploration(reply.text, result);
           result.flows.push(...journeys);
           await note(`AI wrote ${journeys.length} journey${journeys.length === 1 ? "" : "s"}`, "flows");
+          for (const journey of setAside.slice(0, 5)) {
+            await note(`Set aside “${journey.name}”: it ${journey.reason}`, "error");
+          }
+          if (setAside.length > 5) await note(`Set aside ${setAside.length - 5} more that used things discovery didn't see`, "error");
         } catch (error) {
           await note(`AI exploration failed: ${error instanceof Error ? error.message : String(error)}`, "error");
         }
@@ -273,7 +349,11 @@ export async function runDiscoveryTask(
     const planIds = await saveDiscovery(cfg, client, result);
     latest = progressOf(url, result, planIds);
     await send("completed", {
-      completionSummary: `Explored ${result.pages.length} page(s) of ${url} and discovered ${result.flows.length} flow(s).`,
+      completionSummary: `Explored ${result.pages.length} page(s) of ${url} and discovered ${result.flows.length} flow(s).`
+        + (signInWall ? " Stopped at a sign-in page; the app behind it is unexplored." : "")
+        + (result.limits?.notFollowed.length
+          ? ` ${result.limits.notFollowed.length} linked page(s) were not opened (limit: ${result.limits.maxPages} pages, ${result.limits.maxDepth} clicks deep).`
+          : ""),
     });
   } catch (error) {
     await send("error", { errorMessage: error instanceof Error ? error.message : String(error) });

package/src/runtime/executor.ts

@@ -11,6 +11,8 @@ import { journeyScreenshotKey } from "./journey-evidence.js";
 import type { AppDriver, DriverPlatform } from "./driver.js";
 import { MaestroDriver } from "./maestro-driver.js";
 import { PlaywrightDriver } from "./playwright-driver.js";
+import { withFlowSecrets } from "./secret-driver.js";
+import { secretMap } from "./secret-sources.js";
 import { recoverDriverFailure } from "./driver-recovery.js";
 import { startAndroidScreenRecording } from "./android-screen-record.js";
 import { startIosScreenRecording } from "./ios-screen-record.js";
@@ -115,16 +117,27 @@ export interface ExecutionResult {
 }
 
 function configuredDriver(cfg: any, driverId: string): AppDriver {
+  // Flows type {{secret.NAME}} from wherever the project keeps it (its
+  // config's secrets: map, or this machine's keychain).
+  const secrets = (driver: AppDriver) => {
+    const { map } = secretMap(cfg);
+    return withFlowSecrets(driver, {
+      map,
+      projectId: cfg.project?.id ?? "default",
+      // A cloud runner has the project's released secrets already; it has no keychain.
+      localFallback: !process.env.BUGMOLE_RUN_TOKEN,
+    });
+  };
   if (driverId === "maestro") {
-    return new MaestroDriver({
+    return secrets(new MaestroDriver({
       command: cfg.execution?.maestro?.command,
       extraArgs: Array.isArray(cfg.execution?.maestro?.args) ? cfg.execution.maestro.args : undefined,
-    });
+    }));
   }
   if (driverId === "playwright") {
-    return new PlaywrightDriver({
+    return secrets(new PlaywrightDriver({
       headless: cfg.execution?.playwright?.headless,
-    });
+    }));
   }
   throw new Error(`No app driver adapter is registered for "${driverId}"`);
 }
@@ -400,12 +413,7 @@ export async function execute(cfg: any, runOptions: RunOptions): Promise<Executi
         stepsPassed: 0,
         stepsFailed: 0,
         error:
-          `Plan not found: ${planPath}\n` +
-          `Plan ID provided: ${planId}\n` +
-          `Spec dir: ${specDir}\n` +
-          `Plans dir: ${plansDir}\n` +
-          `Current working directory: ${process.cwd()}\n` +
-          `Environment variables: CURSOR_PROJECT_DIRECTORY=${process.env.CURSOR_PROJECT_DIRECTORY || "not set"}, BUGMOLE_PROJECT_DIR=${process.env.BUGMOLE_PROJECT_DIR || "not set"}`,
+          `No plan "${planId}" at ${planPath}. Create it with bugmole_plan (or bugmole --mode plan), or check the plan ID and that Bugmole runs in your project folder (now ${process.cwd()}).`,
       };
     }
 

package/src/runtime/explorer.test.ts

@@ -99,3 +99,35 @@ test("manage hub links resolve against optional catch-all resource routes", asyn
     assert.ok(targets.has(route), `expected /manage to link to ${route}`);
   }
 });
+
+test("an app with no route files is explored by crawling it, and recorded transitions survive re-exploring", async () => {
+  const projectDir = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-explorer-plain-"));
+  await fs.writeFile(path.join(projectDir, "server.mjs"), "// a plain http server\n");
+  const specDir = path.join(projectDir, "spec");
+  const cfg = {
+    runtime: { spec_dir: specDir, artifacts_dir: path.join(projectDir, "runs") },
+    cursor_driver: { project_directory: projectDir },
+    project: { id: "plain" },
+  };
+  const page = (route: string, title: string, links: Array<{ label: string; route: string }>) => ({ route, url: `http://127.0.0.1:1${route}`, title, links });
+  const discover = async () => ({
+    pages: [
+      page("/", "Home", [{ label: "Pricing", route: "/pricing" }, { label: "Sign up", route: "/signup" }]),
+      page("/pricing", "Pricing", [{ label: "Home", route: "/" }]),
+      page("/signup", "Sign up", []),
+    ],
+  });
+  const first = await explore(cfg, { baseUrl: "http://127.0.0.1:1", captureScreenshots: false, discover });
+  assert.equal(first.status, "success");
+  let graph = JSON.parse(await fs.readFile(path.join(specDir, "journeys.graph.json"), "utf-8"));
+  assert.deepEqual(graph.nodes.map((node: { route: string }) => node.route).sort(), ["/", "/pricing", "/signup"]);
+  assert.ok(graph.edges.some((edge: { from: string; to: string; label?: string }) => edge.from === "screen:/" && edge.to === "screen:/signup" && edge.label === "Sign up"));
+
+  // A transition an agent recorded by hand, for its own journey.
+  graph.edges.push({ id: "screen:/signup->screen:/:manual", from: "screen:/signup", to: "screen:/", label: "Back home" });
+  graph.journeys.push({ id: "manual", name: "Manual", actor: "visitor", nodeIds: ["screen:/signup", "screen:/"], edgeIds: ["screen:/signup->screen:/:manual"], revision: 1, status: "draft", startNodeId: "screen:/signup" });
+  await fs.writeFile(path.join(specDir, "journeys.graph.json"), JSON.stringify(graph));
+  await explore(cfg, { baseUrl: "http://127.0.0.1:1", captureScreenshots: false, discover });
+  graph = JSON.parse(await fs.readFile(path.join(specDir, "journeys.graph.json"), "utf-8"));
+  assert.ok(graph.edges.some((edge: { id: string }) => edge.id === "screen:/signup->screen:/:manual"));
+});

package/src/runtime/explorer.ts

@@ -21,6 +21,10 @@ interface ExploreOptions {
   accessMethod?: "configured" | "handoff" | "manual" | "unknown";
   journeyId?: string;
   actor?: string;
+  /** false: never crawl the running app when the source has no route files. */
+  crawl?: boolean;
+  /** The crawler, replaceable in tests. */
+  discover?: (baseUrl: string, options: { maxPages?: number; maxDepth?: number }) => Promise<{ pages: Array<{ route: string; url: string; title: string; heading?: string; links: Array<{ label: string; route: string }> }> }>;
 }
 
 interface ExploreResult {
@@ -572,10 +576,43 @@ export async function explore(cfg: any, options: ExploreOptions): Promise<Explor
         sourcePaths: entry.source ? [entry.source] : [],
       });
     }
+    // No route files (Express, Fastify, a plain http server, a framework the
+    // walk doesn't know): learn the screens from the running app instead,
+    // by clicking through it the way site discovery does.
+    const crawledEdges: any[] = [];
+    if (discoveredNodes.size === 0 && options.crawl !== false) {
+      const { discoverSite } = await import("./site-discovery.js");
+      const site = await (options.discover ?? discoverSite)(baseUrl, { maxPages: 30, maxDepth: 3 });
+      for (const page of site.pages) {
+        const route = normalizeRoute(page.route) || "/";
+        const nodeId = `screen:${route}`;
+        if (discoveredNodes.has(nodeId)) continue;
+        discoveredNodes.set(nodeId, {
+          id: nodeId,
+          title: page.heading || page.title || semanticScreenTitle(route),
+          kind: "screen",
+          signature: `${projectRoot}@route:${route}`,
+          route,
+          source: "running app",
+          sourcePaths: [],
+          runtimeProbe: { status: "reachable", url: page.url },
+          metadata: { discoveredBy: "site-discovery" },
+        });
+      }
+      for (const page of site.pages) {
+        const from = `screen:${normalizeRoute(page.route) || "/"}`;
+        for (const [index, link] of page.links.entries()) {
+          const to = `screen:${normalizeRoute(link.route) || "/"}`;
+          if (to === from || !discoveredNodes.has(to)) continue;
+          crawledEdges.push({ id: `${from}->${to}:crawl-${index}`, from, to, label: link.label, action: `navigate:${normalizeRoute(link.route) || "/"}`, source: "running app" });
+        }
+      }
+    }
     graph.nodes = [...discoveredNodes.values()];
     // Resolve links after all route files are known so source order cannot
     // make a valid link look unresolved.
     const routeNodes = graph.nodes as any[];
+    const previousEdges: any[] = Array.isArray(graph.edges) ? graph.edges : [];
     graph.edges = [];
     for (const filePath of sourceFiles) {
       const relativePath = path.relative(projectRoot, filePath);
@@ -619,6 +656,17 @@ export async function explore(cfg: any, options: ExploreOptions): Promise<Explor
         });
       }
     }
+    for (const edge of crawledEdges) {
+      if (!graph.edges.some((existing: any) => existing.from === edge.from && existing.to === edge.to)) graph.edges.push(edge);
+    }
+    // Transitions a person or an agent recorded for a journey aren't in the
+    // source or the crawl: keep them while both of their screens still exist,
+    // or rebuilding the sitemap breaks those journeys.
+    const recorded = new Set(existingJourneys.flatMap((journey: any) => Array.isArray(journey.edgeIds) ? journey.edgeIds : []));
+    for (const edge of previousEdges) {
+      if (!recorded.has(edge?.id) || graph.edges.some((existing: any) => existing.id === edge.id)) continue;
+      if (discoveredNodes.has(edge.from) && discoveredNodes.has(edge.to)) graph.edges.push(edge);
+    }
     for (const [index, link] of (routesManifest.links ?? []).entries()) {
       if (!link?.from || !link?.to) continue;
       const fromNode = routeNodes.find((candidate: any) =>

package/src/runtime/flow-language.ts

@@ -1,4 +1,5 @@
 import YAML from "yaml";
+import { registerSecretValue } from "./secret-redaction.js";
 
 /**
  * The Maestro-style flow subset this project's web plans author.
@@ -25,6 +26,18 @@ export type FlowStep =
    * sitting on top of a link or button and silently swallowing the tap.
    */
   | { type: "assertClickable"; text: string; index: number; timeoutMs?: number }
+  /**
+   * The page looks right at this screen size: it doesn't scroll sideways,
+   * no text spills out of the card or box it sits in, and none is cut off
+   * without an ellipsis. What a person notices first on a phone.
+   */
+  | { type: "assertLayout" }
+  /**
+   * Every link on the page leads somewhere. Same-site links must answer;
+   * with `external`, other sites' links are checked too (a 404, 410 or
+   * server error fails; sites that refuse robots are not counted).
+   */
+  | { type: "assertLinks"; external: boolean }
   | { type: "scrollUntilVisible"; text: string }
   | { type: "wait"; ms: number }
   | { type: "takeScreenshot"; name: string }
@@ -128,6 +141,8 @@ function parseStep(raw: unknown): FlowStep {
     if (raw === "launchApp") return { type: "launchApp" };
     if (raw === "stopApp") return { type: "stopApp" };
     if (raw === "eraseText") return { type: "eraseText" };
+    if (raw === "assertLayout") return { type: "assertLayout" };
+    if (raw === "assertLinks") return { type: "assertLinks", external: false };
     if (raw === "requestTempEmail") return { type: "requestTempEmail", as: "tempEmail" };
     if (raw === "openEmailLink") return { type: "openEmailLink", as: "tempEmail" };
     // Maestro waits for animations before asserting; the web driver's
@@ -187,6 +202,11 @@ function parseStep(raw: unknown): FlowStep {
     }
     return { type: "assertVisible", text: requireText(value.visible, "extendedWaitUntil"), timeoutMs };
   }
+  if ("assertLayout" in record) return { type: "assertLayout" };
+  if ("assertLinks" in record) {
+    const value = asRecord(record.assertLinks);
+    return { type: "assertLinks", external: Boolean(value?.external) };
+  }
   if ("scrollUntilVisible" in record) {
     const value = asRecord(record.scrollUntilVisible);
     return { type: "scrollUntilVisible", text: requireText(value ? value.element : record.scrollUntilVisible, "scrollUntilVisible") };
@@ -291,6 +311,13 @@ export type InterpolateOptions = {
   env?: Readonly<Record<string, string | undefined>>;
 };
 
+/** The secret names a flow's text references as `{{secret.NAME}}`, sorted and unique. */
+export function referencedSecretNames(content: string): string[] {
+  const names = new Set<string>();
+  for (const match of content.matchAll(/\{\{\s*secret\.([a-zA-Z0-9_]+)\s*\}\}/g)) names.add(match[1]);
+  return [...names].sort();
+}
+
 /**
  * Substitutes `{{name}}` tokens with a value bound earlier in the same flow
  * (currently, only requestTempEmail binds one). Plain text with no template
@@ -316,6 +343,8 @@ export function interpolateTemplate(
       if (value === undefined || value === "") {
         throw new Error(`Flow references "{{secret.${name}}}", but ${variable} is not set on this worker.`);
       }
+      // Typed from here on, so it must never show up in a log or result.
+      registerSecretValue(value);
       return value;
     }
     if (!(name in context)) {
@@ -351,6 +380,8 @@ export function describeStepLabel(step: FlowStep): string {
     case "assertVisible": return `See “${step.text}”`;
     case "assertNotVisible": return `No “${step.text}”`;
     case "assertClickable": return `“${step.text}” is clickable`;
+    case "assertLayout": return "Nothing spills off the screen";
+    case "assertLinks": return step.external ? "Every link works" : "Every link on the site works";
     case "scrollUntilVisible": return `Scroll to “${step.text}”`;
     case "wait": return `Wait ${step.ms}ms`;
     case "takeScreenshot": return `Screenshot “${step.name}”`;
@@ -382,22 +413,26 @@ export function describeAddressForLog(address: string): string {
  * have templated. `retry`'s nested steps are deliberately left alone here --
  * the driver interpolates each one individually as it actually executes it.
  */
-export function interpolateStep(step: FlowStep, context: Readonly<Record<string, string>>): FlowStep {
+export function interpolateStep(
+  step: FlowStep,
+  context: Readonly<Record<string, string>>,
+  options: Pick<InterpolateOptions, "env"> = {},
+): FlowStep {
   switch (step.type) {
     case "tapOn":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "inputText":
-      return { ...step, text: interpolateTemplate(step.text, context, { allowSecrets: true }) };
+      return { ...step, text: interpolateTemplate(step.text, context, { ...options, allowSecrets: true }) };
     case "assertVisible":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "assertNotVisible":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "assertClickable":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "scrollUntilVisible":
-      return { ...step, text: interpolateTemplate(step.text, context) };
+      return { ...step, text: interpolateTemplate(step.text, context, options) };
     case "openLink":
-      return { ...step, url: interpolateTemplate(step.url, context) };
+      return { ...step, url: interpolateTemplate(step.url, context, options) };
     default:
       return step;
   }