@bugmole/cli 0.4.0

package/src/runtime/explorer.ts

@@ -0,0 +1,1013 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import { captureJourneyScreenshots, captureUrlWithLocalBrowser } from "./journey-evidence.js";
+import { repairJourneyGraph } from "./journey-graph.js";
+import { getEnvironmentContract } from "./environment.js";
+import { listReferenceInputs } from "./ui-reverse-engineering/coordinator.js";
+import { nextJourneyTaskWithClarification } from "./journey-editor.js";
+import { readAppUnderstanding } from "./app-understanding.js";
+import { crawlNavigation } from "./nav-crawl.js";
+
+interface ExploreOptions {
+  baseUrl?: string;
+  maxDepth?: number;
+  captureScreenshots?: boolean;
+  projectId?: string;
+  appId?: string;
+  environmentId?: string;
+  accessMethod?: "configured" | "handoff" | "manual" | "unknown";
+  journeyId?: string;
+  actor?: string;
+}
+
+interface ExploreResult {
+  status: "success" | "error";
+  screensDiscovered: number;
+  actionsDiscovered: number;
+  interactiveControlsDiscovered?: number;
+  journeyGraphUpdated: boolean;
+  message?: string;
+  error?: string;
+  nextSteps?: string[];
+  nextTask?: Awaited<ReturnType<typeof nextJourneyTaskWithClarification>>;
+  journeysReviewed?: Array<{
+    id: string;
+    revision: number;
+    nodeCount: number;
+    edgeCount: number;
+    review: "preserved" | "migrated" | "retired" | "source-only";
+  }>;
+  journeysAdded?: string[];
+  journeysRetired?: string[];
+  entrancesDiscovered?: Array<{ nodeId: string; route?: string; variant?: string; reason: string }>;
+}
+
+type RouteProbe = {
+  status: "reachable" | "blocked" | "unreachable" | "not_probed";
+  httpStatus?: number;
+  reason?: string;
+};
+
+function normalizeRoute(route: string, baseRoute = "/"): string {
+  const raw = route.split(/[?#]/, 1)[0] || "/";
+  const resolved = raw.startsWith("/")
+    ? raw
+    : `${baseRoute.replace(/\/+$/, "")}/${raw}`;
+  const segments = resolved.split("/").filter(Boolean)
+    .filter((segment) => !/^\([^/]+\)$/.test(segment))
+    .map((segment) => segment
+      .replace(/^\[\.\.\.(.+)\]$/, "*$1")
+      .replace(/^\[(.+)\]$/, ":$1"));
+  const normalized = `/${segments.join("/")}`;
+  return normalized === "/" ? "/" : normalized.replace(/\/+$/, "");
+}
+
+function isCatchAllPattern(part: string): boolean {
+  return part.startsWith("*") || part.startsWith(":[...");
+}
+
+function routePatternMatches(pattern: string, candidate: string): boolean {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const candidateParts = candidate.split("/").filter(Boolean);
+  let patternIndex = 0;
+  let candidateIndex = 0;
+
+  while (patternIndex < patternParts.length) {
+    const part = patternParts[patternIndex];
+    if (isCatchAllPattern(part)) {
+      return true;
+    }
+    if (part.startsWith(":")) {
+      if (candidateIndex >= candidateParts.length) {
+        const remaining = patternParts.slice(patternIndex);
+        return remaining.every((segment) => segment.startsWith(":") && isCatchAllPattern(segment));
+      }
+      patternIndex += 1;
+      candidateIndex += 1;
+      continue;
+    }
+    if (candidateIndex >= candidateParts.length || part !== candidateParts[candidateIndex]) {
+      return false;
+    }
+    patternIndex += 1;
+    candidateIndex += 1;
+  }
+
+  return candidateIndex === candidateParts.length;
+}
+
+async function probeRoute(baseUrl: string, route: string): Promise<RouteProbe> {
+  try {
+    const url = new URL(route, baseUrl).toString();
+    const response = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(1500) });
+    if (response.status === 401 || response.status === 403) {
+      return { status: "blocked", httpStatus: response.status, reason: "Authentication is required." };
+    }
+    if (response.status >= 200 && response.status < 400) {
+      return { status: "reachable", httpStatus: response.status };
+    }
+    return { status: "unreachable", httpStatus: response.status, reason: `HTTP ${response.status}` };
+  } catch (error) {
+    return {
+      status: "unreachable",
+      reason: error instanceof Error ? error.message : "Route probe failed.",
+    };
+  }
+}
+
+const SOURCE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".vue", ".svelte"];
+
+/**
+ * Repo-relative paths of the first-party components a screen imports.
+ *
+ * Only local modules count: a bare specifier is a third-party package, not
+ * a component of this app. Alias imports (`@/...`) are resolved against the
+ * conventional src root so they aren't silently dropped. Paths that don't
+ * resolve to a real file are omitted rather than recorded as a guess.
+ */
+export function resolveImportedComponents(
+  filePath: string,
+  projectRoot: string,
+  content: string,
+): string[] {
+  const specifiers = [
+    ...content.matchAll(/import\s+[^"';]*?from\s*["']([^"']+)["']/g),
+    ...content.matchAll(/import\s*\(\s*["']([^"']+)["']\s*\)/g),
+  ].map((match) => match[1]);
+
+  const resolved: string[] = [];
+  for (const specifier of specifiers) {
+    let candidate: string | null = null;
+    if (specifier.startsWith(".")) {
+      candidate = path.resolve(path.dirname(filePath), specifier);
+    } else if (specifier.startsWith("@/")) {
+      candidate = path.resolve(projectRoot, "src", specifier.slice(2));
+    }
+    if (!candidate) continue;
+    const match = [
+      candidate,
+      ...SOURCE_EXTENSIONS.map((extension) => `${candidate}${extension}`),
+      ...SOURCE_EXTENSIONS.map((extension) => path.join(candidate!, `index${extension}`)),
+    ].find((option) => {
+      try {
+        return fs.statSync(option).isFile();
+      } catch {
+        return false;
+      }
+    });
+    if (match) resolved.push(path.relative(projectRoot, match));
+  }
+  return [...new Set(resolved)];
+}
+
+function slugPart(value: string): string {
+  return value
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/[:[\](){}]+/g, "")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase() || "screen";
+}
+
+function routeVariantFromSegments(segments: string[]): string | undefined {
+  const groups = segments
+    .filter((segment) => /^\([^/]+\)$/.test(segment))
+    .map((segment) => segment.slice(1, -1));
+  return groups.length ? groups.join("-") : undefined;
+}
+
+function routeVariantFromTarget(target: string): string | undefined {
+  return routeVariantFromSegments(target.split("/").filter(Boolean));
+}
+
+function sourceInteractiveControls(
+  content: string,
+  relativePath: string,
+  node: any,
+  routeNodes: any[],
+): Array<Record<string, unknown>> {
+  const controls: Array<Record<string, unknown>> = [];
+  const lines = content.split(/\r?\n/);
+  const interactiveLine = /onPress\s*=|onClick\s*=|href\s*=|to\s*=|router\.(?:push|replace)\s*\(|navigate\s*\(/;
+  const targetPattern = /(?:href|to)\s*=\s*["'`]([^"'`]+)["'`]|(?:router\.(?:push|replace)|navigate)\s*\(\s*["'`]([^"'`]+)["'`]/;
+  const labelPattern = /(?:accessibilityLabel|aria-label|label|title|placeholder)\s*=\s*["'`]([^"'`]+)["'`]/;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!interactiveLine.test(line)) continue;
+    const context = lines.slice(Math.max(0, index - 2), Math.min(lines.length, index + 3)).join(" ");
+    const targetMatch = context.match(targetPattern);
+    const target = targetMatch?.[1] ?? targetMatch?.[2];
+    const label = context.match(labelPattern)?.[1]
+      ?? (target ? `Navigate to ${target}` : `Interactive control at ${relativePath}:${index + 1}`);
+    const normalizedTarget = target && !target.startsWith("http") && !target.startsWith("#")
+      ? normalizeRoute(target, node.route)
+      : undefined;
+    const targetVariant = target ? routeVariantFromTarget(target) : undefined;
+    const matchingNodes = normalizedTarget
+      ? routeNodes.filter((candidate: any) => routePatternMatches(String(candidate.route), normalizedTarget))
+      : [];
+    const destination = matchingNodes.find((candidate: any) =>
+      targetVariant && candidate.variant === targetVariant)
+      ?? matchingNodes.find((candidate: any) => candidate.variant === node.variant)
+      ?? matchingNodes[0];
+    const id = `control:${node.id}:${index + 1}`;
+    if (controls.some((control) => control.label === label && control.destination === destination?.id)) continue;
+    controls.push({
+      id,
+      label,
+      kind: normalizedTarget ? "navigation" : "action",
+      destination: destination?.id,
+      destinationRoute: normalizedTarget,
+      source: relativePath,
+      line: index + 1,
+      evidenceStatus: "source-discovered",
+    });
+  }
+  return controls;
+}
+
+/**
+ * Rank a node's claim to being where a user starts.
+ *
+ * This used to accept a start only when it matched `/onboarding` with an
+ * "auth" variant or `/` with a "tabs" variant — conventions from a
+ * different (mobile) product. Neither matches a typical web app, so the
+ * code fell through to "nodes with no incoming edges", which on this
+ * dashboard meant settings pages became the entrances and the real home
+ * route was only ever reachable as a goal. Ranked signals instead, lower
+ * is better.
+ */
+export function entranceRank(
+  node: any,
+  context: { declaredEntranceRoutes?: Set<string>; inboundCounts?: Map<string, number> } = {},
+): number {
+  const route = String(node?.route ?? "");
+  if (context.declaredEntranceRoutes?.has(route)) return 0;
+  // The product's own conventions stay ahead of generic guesses so the
+  // mobile app that relies on them is not regressed.
+  if (node?.variant === "auth" && route === "/onboarding") return 1;
+  if (node?.variant === "tabs" && route === "/") return 2;
+  // A web app's root is where a user lands.
+  if (route === "/") return 3;
+  const inbound = context.inboundCounts?.get(node?.id) ?? 0;
+  // Otherwise prefer whatever the app links to most: a hub beats a leaf.
+  if (inbound > 0) return 4 + 1 / (inbound + 1);
+  return 6;
+}
+
+function evidenceJourneyCandidates(
+  graph: { nodes: any[]; edges: any[] },
+  actor: string,
+  declaredEntranceRoutes: Set<string> = new Set(),
+): any[] {
+  const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+  const uniqueEdges = new Map<string, any>();
+  for (const edge of graph.edges) {
+    if (!nodesById.has(edge.from) || !nodesById.has(edge.to)) continue;
+    const key = `${edge.from}->${edge.to}`;
+    if (!uniqueEdges.has(key)) uniqueEdges.set(key, edge);
+  }
+  const edges = [...uniqueEdges.values()];
+  const incoming = new Set(edges.map((edge) => edge.to));
+  const outgoing = new Map<string, any[]>();
+  for (const edge of edges) {
+    const list = outgoing.get(edge.from) ?? [];
+    list.push(edge);
+    outgoing.set(edge.from, list);
+  }
+  const inboundCounts = new Map<string, number>();
+  for (const edge of edges) inboundCounts.set(edge.to, (inboundCounts.get(edge.to) ?? 0) + 1);
+  const rankContext = { declaredEntranceRoutes, inboundCounts };
+  // A node only counts as a real entrance if some signal says so; the
+  // "nothing links to it" fallback is kept last rather than first, because
+  // on a real app that selects leaf pages.
+  const ranked = graph.nodes
+    .filter((node) => node.route !== "/callback")
+    .map((node) => ({ node, rank: entranceRank(node, rankContext) }))
+    .sort((left, right) => left.rank - right.rank);
+  const bestRank = ranked[0]?.rank ?? 6;
+  // Only the best tier starts journeys. Widening this to "anything
+  // reasonably entrance-like" makes every page in a meshed navigation an
+  // entrance, which multiplies out into hundreds of near-duplicate flows.
+  const preferred = bestRank < 6
+    ? ranked.filter((entry) => entry.rank === bestRank).map((entry) => entry.node)
+    : graph.nodes.filter((node) => !incoming.has(node.id) && node.route !== "/callback");
+  // A start with nothing leading out of it cannot yield a journey. If the
+  // best-ranked entrances are all dead ends — which happens when a page
+  // renders an empty shell and its navigation gets attributed elsewhere —
+  // fall back to the nodes that do have outgoing navigation, in rank
+  // order, rather than producing no journeys at all.
+  const hasOutgoing = (node: any) => (outgoing.get(node.id) ?? []).length > 0;
+  const startNodes = preferred.some(hasOutgoing)
+    ? preferred
+    : ranked.map((entry) => entry.node).filter(hasOutgoing);
+  const candidates: any[] = [];
+
+  for (const start of startNodes) {
+    const paths: Array<{ nodeIds: string[]; edgeIds: string[] }> = [];
+    const walk = (nodeId: string, nodeIds: string[], edgeIds: string[], depth: number) => {
+      const nextEdges = (outgoing.get(nodeId) ?? [])
+        .filter((edge) => !nodeIds.includes(edge.to))
+        .filter((edge) => {
+          const target = nodesById.get(edge.to);
+          return !(target?.variant === "auth" && target.route === "/onboarding")
+            || nodesById.get(nodeId)?.variant === "auth";
+        })
+        .slice(0, 12);
+      // Every screen reached along the way is a destination in its own
+      // right. Recording only the maximal path meant that in a meshed
+      // navigation each journey wandered through six screens to reach one,
+      // even where the entrance links to it directly; pairing this with
+      // shortest-path-per-destination yields the direct route instead.
+      if (edgeIds.length) paths.push({ nodeIds, edgeIds });
+      if (!nextEdges.length || depth >= 6) return;
+      for (const edge of nextEdges) {
+        walk(edge.to, [...nodeIds, edge.to], [...edgeIds, edge.id], depth + 1);
+      }
+    };
+    walk(start.id, [start.id], [], 0);
+    // One journey per destination, by the shortest route to it.
+    //
+    // A real app's navigation is a mesh — every page in the sidebar links
+    // to every other — so enumerating every distinct path produced ~200
+    // near-identical journeys with the same endpoints. What a user
+    // actually does is "from the entrance, get to X", so keep the shortest
+    // path to each destination and drop the permutations of it.
+    const uniquePaths = new Map<string, { nodeIds: string[]; edgeIds: string[] }>();
+    for (const path of paths) {
+      const destination = path.nodeIds[path.nodeIds.length - 1];
+      const existing = uniquePaths.get(destination);
+      if (!existing || path.nodeIds.length < existing.nodeIds.length) {
+        uniquePaths.set(destination, path);
+      }
+    }
+    for (const path of [...uniquePaths.values()].slice(0, 24)) {
+      const nodes = path.nodeIds.map((id) => nodesById.get(id)).filter(Boolean);
+      const end = nodes[nodes.length - 1];
+      const startRoute = start.route ?? start.id;
+      const endRoute = end?.route ?? startRoute;
+      const variantSuffix = start.variant ? `-${slugPart(start.variant)}` : "";
+      const pathHash = createHash("sha1").update(path.nodeIds.join("|")).digest("hex").slice(0, 8);
+      const startLabel = start.variant === "auth"
+        ? "Complete account onboarding"
+        : start.variant === "tabs"
+          ? "Open the member home"
+          : semanticScreenTitle(startRoute);
+      candidates.push({
+        id: `flow:${slugPart(startRoute)}${variantSuffix}-to-${slugPart(endRoute)}-${pathHash}`,
+        name: `${startLabel} → ${semanticScreenTitle(endRoute)}`,
+        description: "User journey generated from source-discovered entry, transitions, and goal screen.",
+        actor,
+        startNodeId: start.id,
+        nodeIds: path.nodeIds,
+        edgeIds: path.edgeIds,
+        revision: 1,
+        status: "draft",
+        metadata: {
+          generatedBy: "source-exploration",
+          evidenceStatus: "source-transition",
+          flowScope: "path",
+          verificationStatus: "unverified",
+          verifiedNodeIds: [],
+          verifiedEdgeIds: [],
+          verifiedControlIds: [],
+          goalNodeId: end?.id,
+          entrance: { route: start.route, variant: start.variant },
+          goal: { route: end?.route, nodeId: end?.id },
+        },
+      });
+    }
+  }
+  return candidates;
+}
+
+type RoutesManifestEntry = { route: string; title?: string; source?: string };
+type RoutesManifestLink = { from: string; to: string; action?: string };
+type RoutesManifest = { routes?: RoutesManifestEntry[]; links?: RoutesManifestLink[] };
+
+/**
+ * Best-effort escape hatch for target apps that don't use Next.js-style
+ * `app/`/`pages/` file routing (the only convention the source-tree walk
+ * above understands). A project can declare its screens/links explicitly at
+ * `<spec_dir>/routes.manifest.json`; entries are merged in without touching
+ * file-scan discovery, so Next.js projects are unaffected either way.
+ */
+function loadRoutesManifest(specDir: string, projectRoot: string): RoutesManifest {
+  for (const candidate of [path.join(specDir, "routes.manifest.json"), path.join(projectRoot, "spec", "routes.manifest.json")]) {
+    if (fs.existsSync(candidate)) {
+      try {
+        return JSON.parse(fs.readFileSync(candidate, "utf8")) as RoutesManifest;
+      } catch {
+        return {};
+      }
+    }
+  }
+  return {};
+}
+
+function semanticScreenTitle(route: string): string {
+  const titles: Record<string, string> = {
+    "/": "Open the app",
+    "/onboarding": "Complete account onboarding",
+    "/discover": "Discover available clubs",
+    "/my-plan": "Review my plan",
+    "/profile": "Open my profile",
+    "/about": "Read about the app",
+    "/account-settings": "Manage account settings",
+    "/callback": "Return from authentication",
+    "/checkout-webview": "Complete checkout",
+    "/club/[clubId]": "View club details",
+    "/current-tab": "View the current tab",
+    "/item-detail": "View item details",
+    "/join-club": "Join a club",
+    "/notifications": "Review notifications",
+    "/payments": "Review payments",
+    "/search": "Search for content",
+    "/top-up-credits": "Top up credits",
+  };
+  if (titles[route]) return titles[route];
+  const readableRoute = route
+    .replace(/^\/+/, "")
+    .replace(/\[[^\]]+\]/g, "item")
+    .replace(/[()_]/g, " ")
+    .replace(/[-/]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  const label = readableRoute
+    ? readableRoute.replace(/\b\w/g, (letter) => letter.toUpperCase())
+    : "the app";
+  return `Open ${label}`;
+}
+
+/**
+ * Explorer: Discovers screens and actions, builds/updates the Journey Graph
+ */
+export async function explore(cfg: any, options: ExploreOptions): Promise<ExploreResult> {
+  try {
+    const environmentId = options.environmentId
+      ?? cfg.project?.environment_id
+      ?? cfg.project?.environmentId
+      ?? cfg.runtime?.environment;
+    const environment = environmentId ? await getEnvironmentContract(cfg, environmentId) : null;
+    const baseUrl = options.baseUrl ?? environment?.baseUrl;
+    if (!baseUrl?.trim()) throw new Error("Exploration requires a runnable base URL.");
+    const { maxDepth = 5 } = options;
+    const specDir = cfg.runtime.spec_dir || "./spec";
+    const graphPath = path.join(specDir, "journeys.graph.json");
+    const projectRoot = path.resolve(cfg.cursor_driver?.project_directory || process.cwd());
+
+    // Load existing graph
+    let graph: any = { version: 2, journeys: [], nodes: [], edges: [] };
+    if (fs.existsSync(graphPath)) {
+      const graphContent = fs.readFileSync(graphPath, "utf-8");
+      graph = JSON.parse(graphContent);
+    }
+    graph = repairJourneyGraph({
+      version: 2,
+      ...graph,
+      journeys: Array.isArray(graph.journeys) ? graph.journeys : [],
+      nodes: Array.isArray(graph.nodes) ? graph.nodes : [],
+      edges: Array.isArray(graph.edges) ? graph.edges : [],
+    }, options.projectId ?? cfg.project?.id ?? "default");
+    const existingJourneys = Array.isArray(graph.journeys) ? graph.journeys : [];
+    const hadExistingJourneys = existingJourneys.length > 0;
+
+    const ignored = new Set([
+      "node_modules",
+      ".git",
+      ".next",
+      ".open-next",
+      "dist",
+      "build",
+      "coverage",
+      "screenshots",
+      "bugmole-runs",
+    ]);
+    const sourceFiles: string[] = [];
+    const visit = (directory: string, depth: number) => {
+      if (depth > maxDepth) return;
+      for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+        if (ignored.has(entry.name)) continue;
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) visit(fullPath, depth + 1);
+        else if (/\.(tsx?|jsx?|vue|svelte)$/.test(entry.name)) sourceFiles.push(fullPath);
+      }
+    };
+    visit(projectRoot, 0);
+
+    // Rebuild the sitemap from the current source tree on every run. Keeping
+    // old nodes/edges made removed screens look like valid routes.
+    const discoveredNodes = new Map<string, any>();
+    const nodeBySource = new Map<string, any>();
+    const unresolvedLinks: Array<{ source: string; target: string; sourceFile: string }> = [];
+    for (const filePath of sourceFiles) {
+      const relativePath = path.relative(projectRoot, filePath);
+      const parts = relativePath.split(path.sep);
+      const appDirIndex = parts.lastIndexOf("app");
+      const pagesDirIndex = parts.lastIndexOf("pages");
+      const appIndex = Math.max(appDirIndex, pagesDirIndex);
+      if (appIndex < 0) continue;
+      const fileName = parts[parts.length - 1];
+      if (!/\.(?:tsx?|jsx?)$/.test(fileName)) continue;
+      const baseName = fileName.replace(/\.(?:tsx?|jsx?)$/, "");
+      const routeParts = parts.slice(appIndex + 1, -1);
+      // App Router (app/) and Pages Router (pages/) have fundamentally
+      // different route conventions and can't share one rule:
+      //  - App Router: only page.* (a route) and route.* (an API handler)
+      //    are real, navigable endpoints. Every other convention file
+      //    (layout/template/loading/error/not-found/default) and, above
+      //    all, any plain component that merely lives under app/ is NOT
+      //    its own route. Appending its basename as a route segment
+      //    invents fake screens like "/devices/devices-panel" for
+      //    apps/qa/src/app/devices/devices-panel.tsx — a component
+      //    imported by the real page, not a URL — so headless-Chrome
+      //    capture then wastes attempts on routes that don't exist.
+      //  - Pages Router: every file is a route except the framework's own
+      //    reserved files, and "index" maps to the enclosing directory
+      //    rather than appending its own segment.
+      if (appIndex === appDirIndex) {
+        if (!["page", "route"].includes(baseName)) continue;
+      } else if (["_app", "_document", "_error", "_middleware"].includes(baseName)) {
+        continue;
+      } else if (!["page", "route", "index", "_layout"].includes(baseName)) {
+        routeParts.push(baseName);
+      }
+      const route = normalizeRoute(`/${routeParts.join("/")}`);
+      const variant = routeVariantFromSegments(routeParts);
+      const nodeId = `screen:${route || "/"}${variant ? `@${variant}` : ""}`;
+      const existingNode = discoveredNodes.get(nodeId);
+      const node = existingNode ?? {
+        id: nodeId,
+        title: `${semanticScreenTitle(route || "/")}${variant ? ` (${variant})` : ""}`,
+        kind: "screen",
+        signature: `${projectRoot}@route:${route || "/"}`,
+        route: route || "/",
+        variant,
+        source: relativePath,
+        sourcePaths: [],
+      };
+      node.sourcePaths = [...new Set([...(node.sourcePaths ?? []), relativePath])];
+      discoveredNodes.set(nodeId, node);
+      nodeBySource.set(relativePath, node);
+    }
+
+    // Manifest routes only fill in screens the file-tree walk didn't already
+    // find, so a real app/pages route always wins over a declared one.
+    const routesManifest = loadRoutesManifest(specDir, projectRoot);
+    for (const entry of routesManifest.routes ?? []) {
+      if (!entry?.route) continue;
+      const route = normalizeRoute(entry.route);
+      const nodeId = `screen:${route || "/"}`;
+      if (discoveredNodes.has(nodeId)) continue;
+      discoveredNodes.set(nodeId, {
+        id: nodeId,
+        title: entry.title ?? semanticScreenTitle(route || "/"),
+        kind: "screen",
+        signature: `${projectRoot}@route:${route || "/"}`,
+        route: route || "/",
+        source: entry.source ?? "spec/routes.manifest.json",
+        sourcePaths: entry.source ? [entry.source] : [],
+      });
+    }
+    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[];
+    graph.edges = [];
+    for (const filePath of sourceFiles) {
+      const relativePath = path.relative(projectRoot, filePath);
+      const node = nodeBySource.get(relativePath);
+      if (!node) continue;
+      const content = fs.readFileSync(filePath, "utf8");
+      // Record which components this screen actually imports. Without a
+      // real join the dashboard could only ever say "no components
+      // detected"; guessing from names would invent relationships, so the
+      // evidence is the import statement itself.
+      node.componentPaths = [...new Set([
+        ...(node.componentPaths ?? []),
+        ...resolveImportedComponents(filePath, projectRoot, content),
+      ])];
+      const targets = [
+        ...content.matchAll(/(?:href|to)\s*=\s*["'`]([^"'`]+)["'`]/g),
+        ...content.matchAll(/(?:router\.(?:push|replace)|navigate)\(\s*["'`]([^"'`]+)["'`]/g),
+      ];
+      for (const [index, match] of targets.entries()) {
+        const target = match[1];
+        if (!target || target.startsWith("#") || target.startsWith("http")) continue;
+        const normalizedTarget = normalizeRoute(target, node.route);
+        const targetVariant = routeVariantFromTarget(target);
+        const matchingNodes = routeNodes.filter((candidate: any) =>
+          routePatternMatches(String(candidate.route), normalizedTarget));
+        const targetNode = matchingNodes.find((candidate: any) =>
+          targetVariant && candidate.variant === targetVariant)
+          ?? matchingNodes.find((candidate: any) => candidate.variant === node.variant)
+          ?? matchingNodes[0];
+        if (!targetNode) {
+          unresolvedLinks.push({ source: node.route, target: normalizedTarget, sourceFile: relativePath });
+          continue;
+        }
+        if (targetNode.id === node.id) continue;
+        graph.edges.push({
+          id: `${node.id}->${(targetNode as any).id}:${index}`,
+          from: node.id,
+          to: (targetNode as any).id,
+          action: `navigate:${normalizedTarget}`,
+          source: relativePath,
+        });
+      }
+    }
+    for (const [index, link] of (routesManifest.links ?? []).entries()) {
+      if (!link?.from || !link?.to) continue;
+      const fromNode = routeNodes.find((candidate: any) =>
+        routePatternMatches(String(candidate.route), normalizeRoute(link.from)));
+      const toNode = routeNodes.find((candidate: any) =>
+        routePatternMatches(String(candidate.route), normalizeRoute(link.to)));
+      if (!fromNode || !toNode) continue;
+      const edgeId = `${fromNode.id}->${toNode.id}:manifest-${index}`;
+      if (graph.edges.some((edge: any) => edge.id === edgeId)) continue;
+      graph.edges.push({
+        id: edgeId,
+        from: fromNode.id,
+        to: toNode.id,
+        action: link.action ?? `navigate:${normalizeRoute(link.to)}`,
+        source: "spec/routes.manifest.json",
+      });
+    }
+
+    // Read what the project says about itself before crawling it. Docs
+    // state intent and priority; a crawl can only show structure. The
+    // declared flows are reconciled against the routes that actually
+    // exist, so a spec that has outlived its product is reported rather
+    // than injected as flows over screens that are not there.
+    const understanding = readAppUnderstanding(
+      projectRoot,
+      specDir,
+      routeNodes.map((node: any) => String(node.route ?? "")).filter(Boolean),
+    );
+
+    // Then confirm navigation against the running app. The source scan
+    // only sees link literals, so nav built from a route table is
+    // invisible to it — on this dashboard that hid the entire primary nav
+    // and left only the account dropdown, which is why exploration used to
+    // start at a settings page.
+    const crawl = await crawlNavigation(
+      baseUrl,
+      routeNodes.map((node: any) => String(node.route ?? "")).filter(Boolean),
+    );
+    for (const [fromRoute, links] of crawl.linksByRoute) {
+      const fromNode = routeNodes.find((candidate: any) =>
+        routePatternMatches(String(candidate.route), fromRoute));
+      if (!fromNode) continue;
+      for (const [index, link] of links.entries()) {
+        const toNode = routeNodes.find((candidate: any) =>
+          routePatternMatches(String(candidate.route), link.route));
+        if (!toNode || toNode.id === fromNode.id) continue;
+        // A transition already proven by source stays as it is; this only
+        // adds what the source could not show.
+        if (graph.edges.some((edge: any) => edge.from === fromNode.id && edge.to === toNode.id)) continue;
+        graph.edges.push({
+          id: `${fromNode.id}->${toNode.id}:dom-${index}`,
+          from: fromNode.id,
+          to: toNode.id,
+          action: link.label ? `navigate:${link.label}` : `navigate:${link.route}`,
+          label: link.label,
+          source: "rendered-dom",
+        });
+      }
+    }
+
+    for (const filePath of sourceFiles) {
+      const relativePath = path.relative(projectRoot, filePath);
+      const node = nodeBySource.get(relativePath);
+      if (!node) continue;
+      const controls = sourceInteractiveControls(
+        fs.readFileSync(filePath, "utf8"),
+        relativePath,
+        node,
+        graph.nodes,
+      );
+      if (controls.length) {
+        const existingControls = Array.isArray(node.metadata?.interactiveControls)
+          ? node.metadata.interactiveControls
+          : [];
+        node.metadata = {
+          ...(node.metadata ?? {}),
+          interactiveControls: [
+            ...existingControls,
+            ...controls.filter((control) => !existingControls.some((item: any) => item.id === control.id)),
+          ],
+        };
+      }
+    }
+    const actor = options.actor?.trim() || "user";
+    // Entrances declared by an adopted flow win, because that is the
+    // project stating where its own journeys begin.
+    const declaredEntranceRoutes = new Set(
+      understanding.declaredFlows.adopted
+        .map((flow) => flow.routes[0])
+        .filter((route): route is string => Boolean(route)),
+    );
+    const inboundCounts = new Map<string, number>();
+    for (const edge of graph.edges as any[]) {
+      inboundCounts.set(edge.to, (inboundCounts.get(edge.to) ?? 0) + 1);
+    }
+    const entranceReason = (node: any, rank: number): string => {
+      if (rank === 0) return "declared entrance";
+      if (rank === 1) return "authentication entry";
+      if (rank === 2) return "authenticated app entry";
+      if (rank === 3) return "application root";
+      return `most linked-to screen (${inboundCounts.get(node.id) ?? 0} inbound)`;
+    };
+    const entrances = graph.nodes
+      .filter((node: any) => node.route !== "/callback")
+      .map((node: any) => ({ node, rank: entranceRank(node, { declaredEntranceRoutes, inboundCounts }) }))
+      .filter((entry: { rank: number }) => entry.rank < 5)
+      .sort((left: { rank: number }, right: { rank: number }) => left.rank - right.rank)
+      .slice(0, 5)
+      .map(({ node, rank }: any) => ({
+        nodeId: node.id,
+        route: node.route,
+        variant: node.variant,
+        reason: entranceReason(node, rank),
+      }));
+    const candidates = evidenceJourneyCandidates(graph, actor, declaredEntranceRoutes);
+    const journeyCandidates = candidates.filter((candidate) => candidate.edgeIds.length > 0);
+    const trainingCheckpoints = graph.nodes.map((node: any) => ({
+      id: `checkpoint:${slugPart(node.route ?? node.id)}${node.variant ? `-${slugPart(node.variant)}` : ""}`,
+      nodeId: node.id,
+      route: node.route,
+    }));
+    const journeysRetired = existingJourneys
+      .filter((journey: any) =>
+        String(journey.id).startsWith("checkpoint:")
+        || String(journey.id).startsWith("suggested:")
+        || String(journey.id) === "discovered-flow"
+        || String(journey.id).startsWith("explored:")
+        || String(journey.id).startsWith("flow:")
+          && (journey.metadata?.flowScope !== "path"))
+      .map((journey: any) => journey.id);
+    const retainedExistingJourneys = existingJourneys.filter(
+      (journey: any) => !journeysRetired.includes(journey.id),
+    );
+    const existingById = new Map<string, any>(
+      retainedExistingJourneys.map((journey: any) => [journey.id, journey]),
+    );
+    const journeysReviewed: NonNullable<ExploreResult["journeysReviewed"]> = existingJourneys.map((journey: any) => ({
+      id: journey.id,
+      revision: journey.revision ?? 1,
+      nodeCount: Array.isArray(journey.nodeIds) ? journey.nodeIds.length : 0,
+      edgeCount: Array.isArray(journey.edgeIds) ? journey.edgeIds.length : 0,
+      review: journeysRetired.includes(journey.id) ? "retired" : "preserved",
+    }));
+    const journeysAdded: string[] = [];
+    const reviewedJourneys = retainedExistingJourneys.map((journey: any) => ({
+      ...journey,
+      metadata: {
+        ...(journey.metadata ?? {}),
+        lastReviewedAt: new Date().toISOString(),
+        reviewStatus: "preserved",
+        ...(journey.metadata?.flowScope === "path"
+          ? {
+              verificationStatus: journey.metadata?.verificationStatus ?? "unverified",
+              verifiedNodeIds: Array.isArray(journey.metadata?.verifiedNodeIds)
+                ? journey.metadata.verifiedNodeIds
+                : [],
+              verifiedEdgeIds: Array.isArray(journey.metadata?.verifiedEdgeIds)
+                ? journey.metadata.verifiedEdgeIds
+                : [],
+              verifiedControlIds: Array.isArray(journey.metadata?.verifiedControlIds)
+                ? journey.metadata.verifiedControlIds
+                : [],
+            }
+          : {}),
+      },
+    }));
+    const coveredEdges = new Set(
+      reviewedJourneys.flatMap((journey: any) => Array.isArray(journey.edgeIds) ? journey.edgeIds : []),
+    );
+    const coveredNodes = new Set(
+      reviewedJourneys.flatMap((journey: any) => Array.isArray(journey.nodeIds) ? journey.nodeIds : []),
+    );
+    const establishedStarts = new Set(
+      reviewedJourneys.map((journey: any) => journey.startNodeId).filter(Boolean),
+    );
+    const newEntranceIds = new Set(
+      journeyCandidates
+        .filter((candidate) => !establishedStarts.has(candidate.startNodeId))
+        .map((candidate) => candidate.startNodeId),
+    );
+    const generatedJourneys = [...reviewedJourneys];
+    for (const candidate of journeyCandidates) {
+      const existing = existingById.get(candidate.id);
+      if (existing) continue;
+      const addsEvidence = candidate.edgeIds.some((edgeId: string) => !coveredEdges.has(edgeId))
+        || candidate.nodeIds.some((nodeId: string) => !coveredNodes.has(nodeId))
+        || newEntranceIds.has(candidate.startNodeId);
+      if (!addsEvidence && hadExistingJourneys) continue;
+      generatedJourneys.push(candidate);
+      journeysAdded.push(candidate.id);
+      for (const edgeId of candidate.edgeIds) coveredEdges.add(edgeId);
+      for (const nodeId of candidate.nodeIds) coveredNodes.add(nodeId);
+    }
+    if (generatedJourneys.length === 0 && trainingCheckpoints.length) {
+      generatedJourneys.push({
+        id: "training:screen-review",
+        name: "Source screen review training",
+        description: "Review discovered screens individually because no source navigation transitions were found.",
+        actor,
+        startNodeId: trainingCheckpoints[0].nodeId,
+        nodeIds: trainingCheckpoints.map((checkpoint: { nodeId: string }) => checkpoint.nodeId),
+        edgeIds: [],
+        revision: 1,
+        status: "draft",
+        metadata: {
+          generatedBy: "source-exploration",
+          evidenceStatus: "source-only",
+          trainingCheckpoints,
+        },
+      });
+      journeysAdded.push("training:screen-review");
+    }
+    // Journeys this pass newly discovered are immediately canonical: the
+    // graph-first Overview reads only stability:"stable"+linkedToGraph
+    // journeys (journey.ts canonicalJourneys), and gating that behind a
+    // separate manual bugmole_journey_stabilize call left the flagship page
+    // empty after every real exploration run. Retained/reviewed journeys are
+    // left untouched since they may be manually-curated editor drafts
+    // (stability "discovered"/"stabilizing") that must keep requiring the
+    // manual gate.
+    graph.journeys = generatedJourneys.map((journey: any) =>
+      journeysAdded.includes(journey.id)
+        ? { ...journey, sourceOfTruth: "canonical_flow", stability: "stable", linkedToGraph: true }
+        : journey
+    );
+    const primaryJourneyId =
+      options.journeyId && graph.journeys.some((journey: any) => journey.id === options.journeyId)
+        ? options.journeyId
+        : graph.journeys.find((journey: any) => journey.edgeIds?.length > 0)?.id
+          ?? graph.journeys[0]?.id
+          ?? "training-graph";
+    graph.metadata = {
+      ...(graph.metadata ?? {}),
+      // What the project says it is, in its own words, so later stages can
+      // reason about intent rather than only structure.
+      application: understanding.application,
+      declaredFlows: {
+        adopted: understanding.declaredFlows.adopted.map((flow) => ({
+          id: flow.id,
+          name: flow.name,
+          description: flow.description,
+          routes: flow.routes,
+          source: flow.source,
+        })),
+        // Surfaced, not silently dropped: a spec describing screens this
+        // app does not have is a real signal that it belongs to another
+        // product or has drifted.
+        stale: understanding.declaredFlows.stale,
+      },
+      navigationCrawl: {
+        visited: crawl.visited.length,
+        failed: crawl.failed.length,
+        // Coverage is reported so a near-empty crawl reads as "the app was
+        // not reachable" rather than "the app has no navigation".
+        failures: crawl.failed.slice(0, 10),
+      },
+      journeyReview: {
+        mode: retainedExistingJourneys.length > 0 ? "review-and-add" : "initial-training-graph",
+        reviewed: journeysReviewed,
+        added: journeysAdded,
+        retired: journeysRetired,
+        candidateCount: journeyCandidates.length,
+        trainingCheckpoints,
+        entrances,
+      },
+    };
+    graph.version = 2;
+    const routeProbeEntries = await Promise.all(graph.nodes.map(async (node: any) => [
+      node.route,
+      await probeRoute(baseUrl, node.route),
+    ] as const));
+    const routeProbes = Object.fromEntries(routeProbeEntries);
+    graph.nodes = graph.nodes.map((node: any) => ({
+      ...node,
+      runtimeProbe: routeProbes[node.route] ?? { status: "not_probed" },
+    }));
+    graph.projectId = options.projectId ?? cfg.project?.id ?? "default";
+    graph.appId = options.appId ?? cfg.project?.app_id ?? cfg.project?.appId;
+    graph.environmentId = options.environmentId ?? cfg.project?.environment_id ?? cfg.project?.environmentId;
+    graph.metadata = {
+      ...(graph.metadata ?? {}),
+      discoveredAt: new Date().toISOString(),
+      baseUrl,
+      projectRoot,
+      sourceFiles: sourceFiles.length,
+      access: {
+        baseUrl,
+        environmentId: graph.environmentId,
+        mockUrl: environment?.mockUrl,
+        method: options.accessMethod ?? (environment?.access.transport === "adb" ? "handoff" : "configured"),
+        transport: environment?.access.transport ?? "unknown",
+        deviceLabel: environment?.access.deviceLabel,
+        startCommand: environment?.access.startCommand,
+        authState: Object.values(routeProbes).some((probe) => probe.status === "blocked")
+          ? "partially_authenticated"
+          : "unknown",
+        lastVerifiedAt: new Date().toISOString(),
+        credentialPresent: false,
+      },
+      analysis: {
+        mode: "source-routing-plus-runtime-probes",
+        staticSourceEvidence: true,
+        runtimeRouteValidation: true,
+        unresolvedLinks,
+        routeProbes,
+        staleGraphEntriesRemoved: true,
+        semanticTitles: "route-derived",
+      },
+    };
+    if (options.captureScreenshots ?? cfg.journey_evidence?.capture_screenshots ?? true) {
+      const store = createProjectObjectStore(cfg);
+      graph = await captureJourneyScreenshots(graph, {
+        projectId: cfg.project?.id ?? "default",
+        journeyId: primaryJourneyId,
+        store,
+        sources: cfg.journey_evidence?.sources ?? (await listReferenceInputs({
+          project: { id: cfg.project?.id ?? "default" },
+          storage: cfg.storage,
+          runtime: { artifacts_dir: cfg.runtime.artifacts_dir },
+        })).map((input) => ({
+          kind: "reference" as const,
+          location: input.location,
+          active: input.status !== "archived",
+          related: !input.relatedJourneyIds?.length || input.relatedJourneyIds.includes(primaryJourneyId),
+          referenceId: input.id,
+          viewport: input.viewport,
+        })),
+        captureReferenceUrl: cfg.journey_evidence?.captureReferenceUrl,
+        captureRuntime: cfg.journey_evidence?.captureRuntime
+          ?? ((node: any) => captureUrlWithLocalBrowser(
+            new URL(node.route ?? "/", baseUrl).toString(),
+            cfg.journey_evidence?.viewport,
+          )),
+      });
+    }
+    fs.mkdirSync(specDir, { recursive: true });
+    fs.writeFileSync(graphPath, JSON.stringify(graph, null, 2) + "\n", "utf8");
+    const store = createProjectObjectStore(cfg);
+    await store.put(
+      `${projectPrefix(cfg.project?.id ?? "default")}/journeys/graph.json`,
+      JSON.stringify(graph, null, 2) + "\n",
+      "application/json",
+    );
+
+    const selectedJourneyId = primaryJourneyId;
+    const nextTask = await nextJourneyTaskWithClarification(cfg, selectedJourneyId);
+    const interactiveControlsDiscovered = graph.nodes.reduce(
+      (count: number, node: any) => count + (
+        Array.isArray(node.metadata?.interactiveControls) ? node.metadata.interactiveControls.length : 0
+      ),
+      0,
+    );
+    const result: ExploreResult = {
+      status: graph.nodes.length > 0 ? "success" : "error",
+      screensDiscovered: graph.nodes.length,
+      actionsDiscovered: graph.edges.length,
+      interactiveControlsDiscovered,
+      journeyGraphUpdated: graph.nodes.length > 0,
+      journeysReviewed,
+      journeysAdded,
+      journeysRetired,
+      entrancesDiscovered: entrances,
+      message:
+        graph.nodes.length > 0
+          ? `Codebase exploration discovered ${graph.nodes.length} screens, ${graph.edges.length} navigable actions, and ${interactiveControlsDiscovered} interactive controls. Review the graph and verify the returned flow task before planning.`
+          : `No application entrypoints were discovered under ${projectRoot}.`,
+      nextSteps:
+        graph.nodes.length > 0
+          ? [
+              "Read bugmole://spec/journeys.graph.json and inspect the current flow",
+              `Call bugmole_journey_next with journeyId=${selectedJourneyId}`,
+              "Perform and record the returned task, then repeat until exhausted or blocked",
+            ]
+          : [
+              "Inspect the repository entrypoint and application directory",
+              "Start the application if browser exploration is required",
+              "Retry bugmole_explore with the correct project directory and base URL",
+            ],
+      nextTask,
+    };
+
+    return result;
+  } catch (error: any) {
+    return {
+      status: "error",
+      screensDiscovered: 0,
+      actionsDiscovered: 0,
+      journeyGraphUpdated: false,
+      error: error.message || "Exploration failed",
+    };
+  }
+}