@bugmole/cli 0.4.0

package/src/runtime/journey-evidence.ts

@@ -0,0 +1,180 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { ObjectStore } from "../storage/object-store.js";
+import { headlessBrowserArgs, resolveHeadlessBrowserPath } from "./local-browser.js";
+import type { JourneyGraph, JourneyNode, JourneyScreenshotEvidence } from "./journey-graph.js";
+
+const execFileAsync = promisify(execFile);
+
+// Each captureUrlWithLocalBrowser() call launches a brand-new headless
+// Chrome process, and even a single-page headless launch spawns ~10-15 OS
+// processes (GPU process, network/audio/storage utility services, a
+// renderer, a crashpad handler). Capturing every node in a journey graph
+// concurrently with no limit (as a bare Promise.all did previously) means a
+// graph with N nodes launches N simultaneous Chrome instances — for a
+// realistic ~40-node graph that's ~500+ processes at once, visible on macOS
+// as a burst of windows/Dock icons flashing open and closed. Bounded to a
+// small worker pool instead.
+const DEFAULT_CAPTURE_CONCURRENCY = 3;
+
+export function resolveCaptureConcurrency(): number {
+  const configured = Number(process.env.BUGMOLE_CAPTURE_CONCURRENCY);
+  return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_CAPTURE_CONCURRENCY;
+}
+
+export async function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let nextIndex = 0;
+  async function worker(): Promise<void> {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex++;
+      results[currentIndex] = await fn(items[currentIndex], currentIndex);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+export async function captureUrlWithLocalBrowser(
+  url: string,
+  viewport: { width: number; height: number } = { width: 390, height: 844 },
+): Promise<Uint8Array> {
+  const directory = await fs.mkdtemp(path.join("/tmp", "bugmole-journey-capture-"));
+  const output = path.join(directory, "capture.png");
+  const browser = await resolveHeadlessBrowserPath();
+  try {
+    await execFileAsync(browser, [
+      "--headless=new",
+      "--disable-gpu",
+      "--hide-scrollbars",
+      ...headlessBrowserArgs(),
+      `--window-size=${viewport.width},${viewport.height}`,
+      `--screenshot=${output}`,
+      url,
+    ], { timeout: 45_000 });
+    return new Uint8Array(await fs.readFile(output));
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The page's rendered HTML, for reading navigation the source cannot show.
+ *
+ * A source scan only sees link literals, so navigation built from a route
+ * table (`href={hrefFor(value)}`) is invisible to it — on this dashboard
+ * that hid the entire primary nav. By the time the page has rendered those
+ * hrefs are real strings, so the DOM is the honest place to read them.
+ *
+ * Same browser and invocation as the screenshot path, with --dump-dom
+ * instead of --screenshot, so there is one way to drive a browser here.
+ */
+export async function dumpRenderedDom(
+  url: string,
+  timeoutMs = 45_000,
+): Promise<string> {
+  const browser = await resolveHeadlessBrowserPath();
+  const { stdout } = await execFileAsync(browser, [
+    "--headless=new",
+    "--disable-gpu",
+    "--hide-scrollbars",
+    ...headlessBrowserArgs(),
+    "--virtual-time-budget=4000",
+    "--dump-dom",
+    url,
+  ], { timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024 });
+  return stdout;
+}
+
+export type JourneyEvidenceSource = {
+  kind: "reference" | "runtime";
+  location?: string;
+  active?: boolean;
+  related?: boolean;
+  referenceId?: string;
+  viewport?: { width: number; height: number };
+};
+
+export type JourneyEvidenceOptions = {
+  projectId: string;
+  journeyId: string;
+  store: ObjectStore;
+  sources?: JourneyEvidenceSource[];
+  captureReferenceUrl?: (url: string, node: JourneyNode) => Promise<Uint8Array>;
+  captureRuntime?: (node: JourneyNode) => Promise<Uint8Array>;
+};
+
+export function journeyScreenshotKey(projectId: string, journeyId: string, nodeId: string): string {
+  const safe = nodeId.replace(/[^a-z0-9._-]+/gi, "_").replace(/^_+|_+$/g, "") || "node";
+  return `projects/${encodeURIComponent(projectId)}/journeys/evidence/${encodeURIComponent(journeyId)}/${safe}.png`;
+}
+
+function blocked(source: "reference" | "runtime", reason: string, referenceId?: string): JourneyScreenshotEvidence {
+  return { source, status: "blocked", reason, referenceId };
+}
+
+export async function captureJourneyScreenshots(
+  graph: JourneyGraph,
+  options: JourneyEvidenceOptions,
+): Promise<JourneyGraph> {
+  const journey = graph.journeys.find((item) => item.id === options.journeyId);
+  if (!journey) return graph;
+  const reference = options.sources?.find((source) =>
+    source.kind === "reference" && source.active !== false && source.related !== false && source.location,
+  );
+  const nextNodes = await mapWithConcurrency(graph.nodes, resolveCaptureConcurrency(), async (node) => {
+    let bytes: Uint8Array | undefined;
+    let source: "reference" | "runtime" = "runtime";
+    let referenceId: string | undefined;
+    let reason: string | undefined;
+    if (reference?.location) {
+      source = "reference";
+      referenceId = reference.referenceId;
+      try {
+        if (/^https?:\/\//i.test(reference.location)) {
+            if (options.captureReferenceUrl) {
+            bytes = await options.captureReferenceUrl(reference.location, node);
+          } else {
+              bytes = await captureUrlWithLocalBrowser(reference.location, reference.viewport);
+          }
+        } else {
+          bytes = await fs.readFile(path.resolve(reference.location));
+        }
+      } catch (error) {
+        reason = error instanceof Error
+          ? error.message
+          : `Reference screenshot could not be captured: ${reference.location}`;
+      }
+    } else if (options.captureRuntime) {
+      try {
+        bytes = await options.captureRuntime(node);
+      } catch (error) {
+        reason = error instanceof Error ? error.message : "Runtime screenshot capture failed";
+      }
+    } else {
+      reason = "No active related reference or runtime screenshot capture is available";
+    }
+    if (!bytes) {
+      return { ...node, screenshot: blocked(source, reason ?? "Screenshot capture failed", referenceId) };
+    }
+    const artifactKey = journeyScreenshotKey(options.projectId, options.journeyId, node.id);
+    await options.store.put(artifactKey, bytes, "image/png");
+    const screenshot: JourneyScreenshotEvidence = {
+      source,
+      status: "captured",
+      artifactKey,
+      contentType: "image/png",
+      capturedAt: new Date().toISOString(),
+      viewport: reference?.viewport,
+      referenceId,
+      confidence: source === "reference" ? "high" : "medium",
+    };
+    return {
+      ...node,
+      screenshot,
+    };
+  });
+  return { ...graph, nodes: nextNodes };
+}

package/src/runtime/journey-graph.test.ts

@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { emptyJourneyGraph, repairJourneyGraph, validateJourneyGraph } from "./journey-graph.js";
+import {
+  addJourneyStep,
+  addJourneyTransition,
+  createJourney,
+  reuseJourneyStep,
+  stabilizeJourney,
+  nextJourneyTask,
+  readJourneyGraph,
+  removeJourneyItem,
+  updateJourney,
+  writeJourneyGraph,
+} from "./journey-editor.js";
+
+test("validates journey references and dangling edges", () => {
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [{ id: "start", title: "Open app", kind: "screen" }];
+  graph.edges = [{ id: "bad", from: "start", to: "missing" }];
+  graph.journeys = [{
+    id: "signup",
+    name: "Sign up",
+    actor: "user",
+    nodeIds: ["start"],
+    edgeIds: ["bad"],
+    revision: 1,
+    status: "draft",
+  }];
+  const result = validateJourneyGraph(graph);
+  assert.equal(result.valid, false);
+  assert.match(result.errors.join("\n"), /missing target/);
+});
+
+test("repairs legacy screenshot scope and dangling journey references", () => {
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [
+    { id: "home", title: "Home", kind: "screen", screenshot: { source: "reference", status: "captured", artifactKey: "projects/other/journeys/evidence/home.png" } },
+    { id: "settings", title: "Settings", kind: "screen", screenshot: { source: "reference", status: "captured", artifactKey: "projects/demo/journeys/evidence/settings.png" } },
+  ];
+  graph.journeys = [{ id: "settings-flow", name: "Settings", actor: "user", nodeIds: ["home", "missing"], edgeIds: ["missing-edge"], revision: 1, status: "draft" }];
+  const repaired = repairJourneyGraph(graph, "demo");
+  assert.equal(repaired.nodes[0].screenshot, undefined);
+  assert.ok(repaired.nodes[1].screenshot);
+  assert.deepEqual(repaired.journeys[0].nodeIds, ["home"]);
+  assert.deepEqual(repaired.journeys[0].edgeIds, []);
+  assert.equal(validateJourneyGraph(repaired).valid, true);
+});
+
+test("accepts a valid branching journey", () => {
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [
+    { id: "open", title: "Open app", kind: "screen" },
+    { id: "has-user", title: "Has user?", kind: "decision" },
+    { id: "login", title: "Login", kind: "action" },
+    { id: "buy", title: "Buy plan", kind: "action" },
+  ];
+  graph.edges = [
+    { id: "open-user", from: "open", to: "has-user", label: "open" },
+    { id: "yes-login", from: "has-user", to: "login", condition: "yes" },
+    { id: "no-buy", from: "has-user", to: "buy", condition: "no" },
+  ];
+  graph.journeys = [{
+    id: "membership",
+    name: "Buy membership",
+    actor: "user",
+    startNodeId: "open",
+    nodeIds: graph.nodes.map((node) => node.id),
+    edgeIds: graph.edges.map((edge) => edge.id),
+    revision: 1,
+    status: "draft",
+  }];
+  assert.deepEqual(validateJourneyGraph(graph), { valid: true, errors: [] });
+});
+
+test("supports incremental flow CRUD and mirrors revisions to the object store", async () => {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "bugmole-flow-"));
+  const cfg = {
+    project: { id: "demo" },
+    runtime: { spec_dir: path.join(root, "spec"), artifacts_dir: path.join(root, "artifacts") },
+    storage: { provider: "local", localDirectory: path.join(root, "artifacts") },
+  };
+  await createJourney(cfg, { id: "checkout", name: "Checkout", actor: "customer" });
+  const first = await addJourneyStep(cfg, {
+    journeyId: "checkout",
+    node: { id: "cart", title: "Open cart", kind: "screen", route: "/cart" },
+  });
+  const second = await addJourneyStep(cfg, {
+    journeyId: "checkout",
+    node: { id: "payment", title: "Pay", kind: "action", route: "/payment" },
+  });
+  await addJourneyTransition(cfg, {
+    journeyId: "checkout",
+    from: "cart",
+    to: "payment",
+    edge: { id: "cart-pay", label: "Continue to payment" },
+  });
+  assert.equal(first.journey.revision, 2);
+  assert.equal(second.journey.revision, 3);
+  assert.equal(readJourneyGraph(cfg).journeys[0].revision, 4);
+  assert.equal(fs.existsSync(path.join(root, "artifacts", "projects", "demo", "journeys", "graph.json")), true);
+  assert.equal(nextJourneyTask(cfg, "checkout").status, "exhausted");
+
+  const edited = await updateJourney(cfg, {
+    journeyId: "checkout",
+    journey: { description: "Updated flow" },
+  });
+  assert.equal(edited.journey.description, "Updated flow");
+  await removeJourneyItem(cfg, { journeyId: "checkout", edgeId: "cart-pay" });
+  assert.deepEqual(readJourneyGraph(cfg).journeys[0].edgeIds, []);
+  await fs.promises.rm(root, { recursive: true, force: true });
+});
+
+test("stabilizes one canonical flow and reuses its step in another flow", async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "bugmole-canonical-"));
+  const cfg = {
+    project: { id: "demo" },
+    runtime: { spec_dir: root, artifacts_dir: path.join(root, "runs") },
+    storage: { provider: "local", localDirectory: path.join(root, "runs") },
+  };
+  try {
+    await createJourney(cfg, { id: "source", name: "Source", actor: "user" });
+    await addJourneyStep(cfg, { journeyId: "source", node: { id: "login", title: "Login", kind: "action" } });
+    const stable = await stabilizeJourney(cfg, { journeyId: "source", verificationRunId: "run-1" });
+    assert.equal(stable.journey.stability, "stable");
+    await createJourney(cfg, { id: "target", name: "Target", actor: "user" });
+    const reused = await reuseJourneyStep(cfg, {
+      journeyId: "target",
+      sourceJourneyId: "source",
+      stepId: "login",
+    });
+    assert.deepEqual(reused.journey.reuses, [{ flowId: "source", stepId: "login", alias: undefined }]);
+    assert.equal(reused.journey.linkedToGraph, false);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("returns the next task for a branch outside the selected flow", async () => {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "bugmole-flow-next-"));
+  const cfg = {
+    project: { id: "demo" },
+    runtime: { spec_dir: path.join(root, "spec"), artifacts_dir: path.join(root, "artifacts") },
+    storage: { provider: "local", localDirectory: path.join(root, "artifacts") },
+  };
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [
+    { id: "home", title: "Home", kind: "screen", route: "/" },
+    { id: "settings", title: "Settings", kind: "screen", route: "/settings" },
+  ];
+  graph.edges = [{ id: "home-settings", from: "home", to: "settings", label: "Open settings" }];
+  graph.journeys = [{
+    id: "settings-flow", name: "Settings", actor: "user", startNodeId: "home",
+    nodeIds: ["home"], edgeIds: [], revision: 1, status: "draft",
+  }];
+  await writeJourneyGraph(cfg, graph);
+  const next = nextJourneyTask(cfg, "settings-flow");
+  assert.equal(next.status, "actionable");
+  assert.equal(next.route, "/settings");
+  assert.equal(next.edgeId, "home-settings");
+  await fs.promises.rm(root, { recursive: true, force: true });
+});
+
+test("does not make unrelated sitemap screens tasks for a selected flow", async () => {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "bugmole-flow-scope-"));
+  const cfg = {
+    project: { id: "demo" },
+    runtime: { spec_dir: path.join(root, "spec"), artifacts_dir: path.join(root, "artifacts") },
+    storage: { provider: "local", localDirectory: path.join(root, "artifacts") },
+  };
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [
+    { id: "home", title: "Home", kind: "screen", route: "/" },
+    { id: "about", title: "About", kind: "screen", route: "/about" },
+  ];
+  graph.journeys = [{
+    id: "home-flow", name: "Home", actor: "user", startNodeId: "home",
+    nodeIds: ["home"], edgeIds: [], revision: 1, status: "draft",
+  }];
+  await writeJourneyGraph(cfg, graph);
+  const next = nextJourneyTask(cfg, "home-flow");
+  assert.equal(next.status, "exhausted");
+  assert.match(next.reason, /selected flow/);
+  await fs.promises.rm(root, { recursive: true, force: true });
+});
+
+test("requires runtime transition and terminal-goal completion for source paths", async () => {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "bugmole-flow-runtime-"));
+  const cfg = {
+    project: { id: "demo" },
+    runtime: { spec_dir: path.join(root, "spec"), artifacts_dir: path.join(root, "artifacts") },
+    storage: { provider: "local", localDirectory: path.join(root, "artifacts") },
+  };
+  const graph = emptyJourneyGraph("demo");
+  graph.nodes = [
+    { id: "home", title: "Home", kind: "screen", route: "/" },
+    {
+      id: "top-up",
+      title: "Top up credits",
+      kind: "screen",
+      route: "/top-up-credits",
+      metadata: {
+        interactiveControls: [{ id: "confirm-top-up", label: "Confirm top up", kind: "action" }],
+      },
+    },
+  ];
+  graph.edges = [{ id: "home-top-up", from: "home", to: "top-up", label: "Open top up credits" }];
+  graph.journeys = [{
+    id: "top-up-flow",
+    name: "Top up credits",
+    actor: "user",
+    startNodeId: "home",
+    nodeIds: ["home", "top-up"],
+    edgeIds: ["home-top-up"],
+    revision: 1,
+    status: "draft",
+    metadata: {
+      flowScope: "path",
+      goalNodeId: "top-up",
+      verifiedEdgeIds: [],
+      completedGoalIds: [],
+    },
+  }];
+  await writeJourneyGraph(cfg, graph);
+  const first = nextJourneyTask(cfg, "top-up-flow");
+  assert.equal(first.status, "actionable");
+  assert.equal(first.edgeId, "home-top-up");
+
+  graph.journeys[0].metadata = {
+    ...graph.journeys[0].metadata,
+    verifiedEdgeIds: ["home-top-up"],
+  };
+  await writeJourneyGraph(cfg, graph);
+  const goal = nextJourneyTask(cfg, "top-up-flow");
+  assert.equal(goal.status, "actionable");
+  assert.equal(goal.controlId, "confirm-top-up");
+
+  graph.journeys[0].metadata = {
+    ...graph.journeys[0].metadata,
+    verifiedControlIds: ["confirm-top-up"],
+  };
+  await writeJourneyGraph(cfg, graph);
+  const completion = nextJourneyTask(cfg, "top-up-flow");
+  assert.equal(completion.status, "actionable");
+  assert.match(completion.action ?? "", /Complete and verify/);
+
+  graph.journeys[0].metadata = {
+    ...graph.journeys[0].metadata,
+    completedGoalIds: ["top-up"],
+  };
+  await writeJourneyGraph(cfg, graph);
+  assert.equal(nextJourneyTask(cfg, "top-up-flow").status, "exhausted");
+  await fs.promises.rm(root, { recursive: true, force: true });
+});

package/src/runtime/journey-graph.ts

@@ -0,0 +1,170 @@
+export type JourneyNodeStatus = "success" | "blocked" | "failed";
+
+export type JourneyScreenshotEvidence = {
+  source: "reference" | "runtime";
+  status: "captured" | "blocked";
+  artifactKey?: string;
+  contentType?: "image/png" | "image/jpeg" | "image/webp" | "video/mp4" | "video/webm";
+  capturedAt?: string;
+  viewport?: { width: number; height: number };
+  referenceId?: string;
+  confidence?: "high" | "medium" | "low";
+  reason?: string;
+};
+
+export type JourneyNode = {
+  id: string;
+  title: string;
+  kind: "screen" | "decision" | "action" | "checkpoint";
+  route?: string;
+  action?: string;
+  actor?: string;
+  expectedOutcome?: "pass" | "blocked" | "warn" | "fail" | "unknown";
+  proofs?: Array<Record<string, unknown>>;
+  position?: { x: number; y: number };
+  metadata?: Record<string, unknown>;
+  screenshot?: JourneyScreenshotEvidence;
+};
+
+export type JourneyEdge = {
+  id: string;
+  from: string;
+  to: string;
+  label?: string;
+  condition?: string;
+  order?: number;
+};
+
+export type UserJourney = {
+  id: string;
+  name: string;
+  description?: string;
+  actor: string;
+  startNodeId?: string;
+  nodeIds: string[];
+  edgeIds: string[];
+  revision: number;
+  status: "draft" | "published";
+  sourceOfTruth?: "canonical_flow";
+  stability?: "discovered" | "stabilizing" | "stable";
+  linkedToGraph?: boolean;
+  verificationRunId?: string;
+  verifiedAt?: string;
+  reuses?: Array<{ flowId: string; stepId: string; alias?: string }>;
+  metadata?: Record<string, unknown>;
+};
+
+export type JourneyGraph = {
+  version: 2;
+  projectId?: string;
+  appId?: string;
+  environmentId?: string;
+  journeys: UserJourney[];
+  nodes: JourneyNode[];
+  edges: JourneyEdge[];
+  metadata?: Record<string, unknown>;
+};
+
+export function canonicalFlows(graph: JourneyGraph): UserJourney[] {
+  return graph.journeys.filter((journey) =>
+    journey.sourceOfTruth === "canonical_flow" &&
+    journey.stability === "stable" &&
+    journey.linkedToGraph === true,
+  );
+}
+
+export type JourneyValidation = {
+  valid: boolean;
+  errors: string[];
+};
+
+export function projectJourneyArtifactPrefix(projectId: string): string {
+  return `projects/${encodeURIComponent(projectId)}/`;
+}
+
+export function isProjectScopedJourneyArtifact(artifactKey: string, projectId: string): boolean {
+  return artifactKey.startsWith(projectJourneyArtifactPrefix(projectId));
+}
+
+/**
+ * Repair legacy graphs at the read boundary so one bad historical write does
+ * not make every later project-scoped CRUD operation impossible. Repair is
+ * deliberately conservative: invalid screenshot references are removed, and
+ * dangling journey references are pruned, but discovered nodes and edges are
+ * retained for inspection.
+ */
+export function repairJourneyGraph(graph: JourneyGraph, projectId: string): JourneyGraph {
+  const nodeIds = new Set(graph.nodes.map((node) => node.id));
+  const nodes = graph.nodes.map((node) => {
+    const artifactKey = node.screenshot?.artifactKey;
+    if (artifactKey && !isProjectScopedJourneyArtifact(artifactKey, projectId)) {
+      const { screenshot: _screenshot, ...withoutScreenshot } = node;
+      return withoutScreenshot;
+    }
+    return node;
+  });
+  const journeys = graph.journeys.map((journey) => ({
+    ...journey,
+    nodeIds: journey.nodeIds.filter((nodeId) => nodeIds.has(nodeId)),
+    edgeIds: journey.edgeIds.filter((edgeId) => graph.edges.some((edge) => edge.id === edgeId)),
+    startNodeId: journey.startNodeId && nodeIds.has(journey.startNodeId)
+      ? journey.startNodeId
+      : undefined,
+  }));
+  return {
+    ...graph,
+    projectId,
+    journeys,
+    nodes,
+  };
+}
+
+export function validateJourneyGraph(graph: JourneyGraph): JourneyValidation {
+  const errors: string[] = [];
+  const nodeIds = new Set(graph.nodes.map((node) => node.id));
+  const edgeIds = new Set<string>();
+  for (const edge of graph.edges) {
+    if (edgeIds.has(edge.id)) errors.push(`Duplicate edge id: ${edge.id}`);
+    edgeIds.add(edge.id);
+    if (!nodeIds.has(edge.from)) errors.push(`Edge ${edge.id} references missing source ${edge.from}`);
+    if (!nodeIds.has(edge.to)) errors.push(`Edge ${edge.id} references missing target ${edge.to}`);
+  }
+  for (const node of graph.nodes) {
+    const screenshot = node.screenshot;
+    if (!screenshot) continue;
+    if (screenshot.status === "captured" && !screenshot.artifactKey) {
+      errors.push(`Node ${node.id} has captured screenshot evidence without an artifact key`);
+    }
+    if (screenshot.status === "blocked" && !screenshot.reason?.trim()) {
+      errors.push(`Node ${node.id} has blocked screenshot evidence without a reason`);
+    }
+    if (screenshot.artifactKey && graph.projectId
+      && screenshot.artifactKey !== `projects/${encodeURIComponent(graph.projectId)}/${screenshot.artifactKey.replace(/^projects\/[^/]+\//, "")}`) {
+      errors.push(`Node ${node.id} screenshot artifact is not project-scoped`);
+    }
+  }
+  const journeyIds = new Set<string>();
+  for (const journey of graph.journeys) {
+    if (journeyIds.has(journey.id)) errors.push(`Duplicate journey id: ${journey.id}`);
+    journeyIds.add(journey.id);
+    if (!journey.name.trim()) errors.push(`Journey ${journey.id} must have a name`);
+    if (!journey.actor.trim()) errors.push(`Journey ${journey.id} must have an actor`);
+    if (journey.linkedToGraph && journey.stability !== "stable") {
+      errors.push(`Journey ${journey.id} cannot link to the app graph before stabilization`);
+    }
+    for (const nodeId of journey.nodeIds) {
+      if (!nodeIds.has(nodeId)) errors.push(`Journey ${journey.id} references missing node ${nodeId}`);
+    }
+    for (const edgeId of journey.edgeIds) {
+      if (!edgeIds.has(edgeId)) errors.push(`Journey ${journey.id} references missing edge ${edgeId}`);
+    }
+    if (journey.startNodeId && !journey.nodeIds.includes(journey.startNodeId)) {
+      errors.push(`Journey ${journey.id} start node is not part of the journey`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function emptyJourneyGraph(projectId?: string): JourneyGraph {
+  return { version: 2, projectId, journeys: [], nodes: [], edges: [] };
+}

package/src/runtime/legacy-names.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+
+/**
+ * Bugmole was called Valkyrie until 0.4.0. Workspaces set up before the
+ * rename still have its file names and environment variables; these helpers
+ * let them keep working without anyone having to rename anything.
+ */
+const LEGACY_ENV_PREFIX = "VALKYRIE_";
+const ENV_PREFIX = "BUGMOLE_";
+
+/** Copies each VALKYRIE_* variable to its BUGMOLE_* name, unless that is already set. */
+export function adoptLegacyEnv(env: NodeJS.ProcessEnv = process.env): void {
+  for (const [key, value] of Object.entries(env)) {
+    if (!key.startsWith(LEGACY_ENV_PREFIX) || value === undefined) continue;
+    const current = ENV_PREFIX + key.slice(LEGACY_ENV_PREFIX.length);
+    if (env[current] === undefined) env[current] = value;
+  }
+}
+
+/** The legacy path when only it exists; otherwise the current one. */
+export function preferExisting(current: string, legacy: string): string {
+  return !fs.existsSync(current) && fs.existsSync(legacy) ? legacy : current;
+}
+
+/** Old file and directory names, keyed by the current name. */
+export const LEGACY_PATHS: Record<string, string> = {
+  ".bugmole.env": ".valk.env",
+  ".bugmole": ".valkyrie",
+  ".bugmole/config.yaml": ".valkyrie/config.yaml",
+  "bugmole.config.yaml": "valkyrie.config.yaml",
+  "qa/bugmole-runs": "qa/valkyrie-runs",
+};