@bugmole/cli 0.4.0

package/src/runtime/android-screen-record.ts

@@ -0,0 +1,192 @@
+import fs from "node:fs/promises";
+import { execFile, spawn, type ChildProcess } from "node:child_process";
+import { promisify } from "node:util";
+
+import { dropIdleFrames, mpdecimateArgs } from "./screen-recording.js";
+
+const execFileAsync = promisify(execFile);
+
+// Re-exported: both recorders post-process the same way, and this is where
+// callers and tests already look for it.
+export { mpdecimateArgs };
+
+export type AndroidScreenRecording = {
+  /**
+   * Stops recording and pulls every chunk, in order.
+   *
+   * Returns a list rather than one path: a run longer than a single chunk is
+   * several files, and the caller attaches each as its own artifact.
+   */
+  stop(localBasePath?: string): Promise<string[]>;
+};
+
+export interface ScreenRecordingOptions {
+  /** Seconds per chunk. screenrecord refuses to run longer than 180. */
+  chunkSeconds?: number;
+  /**
+   * Drop frames where the screen did not change, so a run that spends its
+   * time waiting does not produce minutes of identical video. Needs ffmpeg;
+   * without it the recording is kept whole rather than lost.
+   */
+  skipIdle?: boolean;
+  ffmpegCommand?: string;
+}
+
+/** screenrecord's own ceiling. Asking for more is refused outright. */
+export const MAX_CHUNK_SECONDS = 180;
+
+export function clampChunkSeconds(value: number | undefined): number {
+  if (!Number.isFinite(value) || (value as number) <= 0) return MAX_CHUNK_SECONDS;
+  return Math.min(Math.floor(value as number), MAX_CHUNK_SECONDS);
+}
+
+export function deviceChunkPath(index: number): string {
+  return `/sdcard/bugmole-run-${String(index).padStart(3, "0")}.mp4`;
+}
+
+/** `run.mp4` becomes `run-001.mp4`, `run-002.mp4`, … so the ordering is
+ *  obvious in a directory listing and survives sorting. */
+export function localChunkPath(basePath: string, index: number): string {
+  const suffix = `-${String(index).padStart(3, "0")}`;
+  const dot = basePath.lastIndexOf(".");
+  return dot <= basePath.lastIndexOf("/")
+    ? `${basePath}${suffix}`
+    : `${basePath.slice(0, dot)}${suffix}${basePath.slice(dot)}`;
+}
+
+/** Size in bytes from `stat -c %s`, or null when the file is not there yet. */
+export function parseDeviceFileSize(output: string): number | null {
+  // Digits only. Number("") is 0, so a stat that answered nothing would read
+  // as a real zero-byte file and count towards the size having settled.
+  const token = output.trim().split(/\s+/)[0] ?? "";
+  if (!/^\d+$/.test(token)) return null;
+  const size = Number(token);
+  return Number.isSafeInteger(size) ? size : null;
+}
+
+export function screenrecordArgs(serial: string, devicePath: string, chunkSeconds: number): string[] {
+  return ["-s", serial, "shell", "screenrecord", `--time-limit=${chunkSeconds}`, devicePath];
+}
+
+/**
+ * Wraps `adb shell screenrecord` around a real device run so the actual test
+ * execution is captured, not a second, separately-timed replay.
+ *
+ * screenrecord stops itself at three minutes, which used to mean a long run
+ * was silently truncated to its first three minutes. It is now recorded as
+ * consecutive chunks instead, started back to back until the run ends. The
+ * seam between two chunks loses the moment it takes the device to stop one
+ * recording and begin the next, which is a better trade than losing everything
+ * after minute three.
+ */
+export async function startAndroidScreenRecording(
+  serial: string,
+  adbCommand = "adb",
+  options: ScreenRecordingOptions = {},
+): Promise<AndroidScreenRecording | undefined> {
+  const chunkSeconds = clampChunkSeconds(options.chunkSeconds);
+  const ffmpegCommand = options.ffmpegCommand ?? "ffmpeg";
+  const devicePaths: string[] = [];
+  let stopped = false;
+  let current: ChildProcess | null = null;
+  let spawnFailed = false;
+
+  const startChunk = (): ChildProcess => {
+    const devicePath = deviceChunkPath(devicePaths.length + 1);
+    devicePaths.push(devicePath);
+    const child = spawn(adbCommand, screenrecordArgs(serial, devicePath, chunkSeconds), { stdio: "ignore" });
+    // spawn() does not throw synchronously for a missing executable; the
+    // failure surfaces as an async 'error' event instead.
+    child.once("error", () => { spawnFailed = true; });
+    return child;
+  };
+
+  current = startChunk();
+  // Give screenrecord a moment to actually start (and to surface a spawn
+  // error) before the caller proceeds; a successful spawn does not guarantee
+  // the device accepted the command yet.
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  if (spawnFailed) return undefined;
+
+  // Each chunk ends on its own at the time limit. Start the next immediately
+  // so the run keeps being recorded until someone stops it.
+  const chain = (child: ChildProcess): void => {
+    child.once("exit", () => {
+      if (stopped || spawnFailed) return;
+      current = startChunk();
+      chain(current);
+    });
+  };
+  chain(current);
+
+  return {
+    async stop(localBasePath?: string): Promise<string[]> {
+      stopped = true;
+      try {
+        current?.kill("SIGINT");
+        await new Promise<void>((resolve) => {
+          current?.once("exit", () => resolve());
+          setTimeout(resolve, 5_000);
+        });
+      } catch {
+        // Already gone; the pull below is what actually matters.
+      }
+      // The local adb client exiting says nothing about the device having
+      // finished the file. screenrecord still has to write the mp4 trailer,
+      // and pulling before it does yields a file with no moov atom, which no
+      // player will open. This only ever bit the chunk that was interrupted —
+      // the last one, which is the part of a run worth watching.
+      if (devicePaths.length > 0) {
+        await waitForStableSize(adbCommand, serial, devicePaths[devicePaths.length - 1]);
+      }
+      const base = localBasePath ?? "bugmole-run.mp4";
+      const pulled: string[] = [];
+      for (const [offset, devicePath] of devicePaths.entries()) {
+        const localPath = localChunkPath(base, offset + 1);
+        try {
+          await execFileAsync(adbCommand, ["-s", serial, "pull", devicePath, localPath], { timeout: 60_000 });
+          await execFileAsync(adbCommand, ["-s", serial, "shell", "rm", "-f", devicePath]).catch(() => undefined);
+          const stats = await fs.stat(localPath).catch(() => undefined);
+          // The chunk that was running when stop() arrived can be empty, and a
+          // zero-byte video is worse than no video.
+          if (!stats || stats.size === 0) {
+            await fs.rm(localPath, { force: true }).catch(() => undefined);
+            continue;
+          }
+          pulled.push(options.skipIdle ? await dropIdleFrames(localPath, ffmpegCommand) : localPath);
+        } catch {
+          // One unreadable chunk should not cost the rest of the recording.
+        }
+      }
+      return pulled;
+    },
+  };
+}
+
+/**
+ * Waits until the device stops writing, by watching the size settle.
+ *
+ * Bounded rather than open-ended: a recording that never settles should delay
+ * the run's artifacts, not hold it forever.
+ */
+async function waitForStableSize(
+  adbCommand: string,
+  serial: string,
+  devicePath: string,
+  timeoutMs = 15_000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let previous: number | null = null;
+  while (Date.now() < deadline) {
+    let size: number | null = null;
+    try {
+      const { stdout } = await execFileAsync(adbCommand, ["-s", serial, "shell", "stat", "-c", "%s", devicePath], { timeout: 10_000 });
+      size = parseDeviceFileSize(String(stdout));
+    } catch {
+      // The file may not exist yet, which is itself "not settled".
+    }
+    if (size !== null && size > 0 && size === previous) return;
+    previous = size;
+    await new Promise((resolve) => setTimeout(resolve, 400));
+  }
+}

package/src/runtime/app-understanding.test.ts

@@ -0,0 +1,123 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  readApplicationIdentity,
+  readDeclaredFlows,
+  reconcileDeclaredFlows,
+  type DeclaredFlow,
+} from "./app-understanding.js";
+
+async function tempProject(files: Record<string, string>): Promise<string> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-understanding-"));
+  for (const [relative, content] of Object.entries(files)) {
+    const target = path.join(root, relative);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, content);
+  }
+  return root;
+}
+
+test("reads the project's own description rather than inferring one", async () => {
+  const root = await tempProject({
+    "package.json": JSON.stringify({ name: "acme-shop", description: "Storefront for Acme." }),
+  });
+  try {
+    const identity = readApplicationIdentity(root);
+    assert.equal(identity.name, "acme-shop");
+    assert.equal(identity.description, "Storefront for Acme.");
+    assert.deepEqual(identity.sources, ["package.json"]);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("falls back to the README's first prose paragraph, skipping headings and badges", async () => {
+  const root = await tempProject({
+    "package.json": JSON.stringify({ name: "acme-shop" }),
+    "README.md": [
+      "# Acme Shop",
+      "",
+      "[![badge](https://img.shields.io/x)](https://example.com)",
+      "",
+      "Acme Shop lets customers browse and order parts.",
+      "",
+      "## Install",
+    ].join("\n"),
+  });
+  try {
+    const identity = readApplicationIdentity(root);
+    assert.equal(identity.description, "Acme Shop lets customers browse and order parts.");
+    assert.ok(identity.sources.includes("README.md"));
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("a project that says nothing about itself gets no invented description", async () => {
+  const root = await tempProject({ "package.json": JSON.stringify({ name: "quiet" }) });
+  try {
+    const identity = readApplicationIdentity(root);
+    assert.equal(identity.description, undefined);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+test("reads declared journeys, including routes named only by an action target", async () => {
+  const root = await tempProject({
+    "spec/journey_graph.yaml": [
+      "journeys:",
+      '  - id: "marketing-entry"',
+      '    name: "Marketing Entry"',
+      '    description: "Customer lands and starts booking."',
+      "    screens:",
+      '      - path: "/"',
+      "    actions:",
+      '      - type: "navigate"',
+      '        target: "/book"',
+    ].join("\n"),
+  });
+  try {
+    const flows = readDeclaredFlows(path.join(root, "spec"), root);
+    assert.equal(flows.length, 1);
+    assert.equal(flows[0].name, "Marketing Entry");
+    assert.deepEqual(flows[0].routes, ["/", "/book"]);
+  } finally {
+    await fs.rm(root, { recursive: true, force: true });
+  }
+});
+
+const arionFlow: DeclaredFlow = {
+  id: "public-booking",
+  name: "Public Booking",
+  routes: ["/book", "/book/[vehicleId]"],
+  source: "spec/journey_graph.yaml",
+};
+
+test("a declared flow whose screens exist is adopted", () => {
+  const result = reconcileDeclaredFlows([arionFlow], ["/book", "/book/:vehicleId", "/"]);
+  assert.equal(result.adopted.length, 1);
+  assert.equal(result.stale.length, 0);
+});
+
+test("a spec that outlived its product is reported stale, never injected", () => {
+  // Exactly this repo's situation: journey_graph.yaml describes a rental
+  // app while the project being explored is the dashboard. Injecting it
+  // would invent flows over screens that do not exist.
+  const result = reconcileDeclaredFlows([arionFlow], ["/", "/plans", "/tasks", "/audits"]);
+  assert.equal(result.adopted.length, 0);
+  assert.equal(result.stale.length, 1);
+  assert.equal(result.stale[0].id, "public-booking");
+  assert.deepEqual(result.stale[0].missingRoutes, ["/book", "/book/[vehicleId]"]);
+});
+
+test("parameterised routes match whatever syntax each side used", () => {
+  const result = reconcileDeclaredFlows(
+    [{ id: "f", name: "F", routes: ["/book/[vehicleId]", "/manage/[resource]/[[...action]]"], source: "s" }],
+    ["/book/:vehicleId", "/manage/:resource/:[...action]"],
+  );
+  assert.equal(result.adopted.length, 1, "differing param syntax must not be treated as a missing screen");
+});

package/src/runtime/app-understanding.ts

@@ -0,0 +1,201 @@
+/**
+ * What the project says about itself, read before anything is crawled.
+ *
+ * Exploration used to begin by pattern-matching link literals in source,
+ * which meant it never learned what the application is *for* — only what
+ * happened to be wired with a hardcoded href. On this dashboard the sole
+ * literals live in the account dropdown, so the whole world model was
+ * rebuilt from a secondary menu and every discovered flow started at a
+ * settings page.
+ *
+ * Documentation states intent and priority; a crawl can only ever show
+ * structure. So identity and declared flows are read first, and the crawl
+ * confirms them afterwards.
+ *
+ * Declared intent is reconciled against reality rather than trusted: a
+ * spec can outlive the product it describes (this repo ships a
+ * journey_graph.yaml for a different application entirely), and adopting
+ * it blindly would inject flows for screens that do not exist.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+
+export type ApplicationIdentity = {
+  name?: string;
+  description?: string;
+  /** Where each field came from, so nothing reads as asserted by Bugmole. */
+  sources: string[];
+};
+
+export type DeclaredFlow = {
+  id: string;
+  name: string;
+  description?: string;
+  /** Route paths the flow claims to visit, in order. */
+  routes: string[];
+  source: string;
+};
+
+export type DeclaredFlowReconciliation = {
+  adopted: DeclaredFlow[];
+  /** Declared flows whose screens do not exist in this app, with why. */
+  stale: Array<{ id: string; name: string; source: string; missingRoutes: string[] }>;
+};
+
+export type AppUnderstanding = {
+  application: ApplicationIdentity;
+  declaredFlows: DeclaredFlowReconciliation;
+};
+
+function readFileIfPresent(filePath: string): string | null {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The project's own words about itself. Only what the repo actually
+ * states — an absent description stays absent rather than being inferred
+ * from the directory name.
+ */
+export function readApplicationIdentity(projectRoot: string): ApplicationIdentity {
+  const sources: string[] = [];
+  let name: string | undefined;
+  let description: string | undefined;
+
+  const packageJson = readFileIfPresent(path.join(projectRoot, "package.json"));
+  if (packageJson) {
+    try {
+      const parsed = JSON.parse(packageJson) as { name?: unknown; description?: unknown };
+      if (typeof parsed.name === "string" && parsed.name.trim()) name = parsed.name.trim();
+      if (typeof parsed.description === "string" && parsed.description.trim()) {
+        description = parsed.description.trim();
+      }
+      if (name || description) sources.push("package.json");
+    } catch {
+      // A malformed package.json must not stop exploration.
+    }
+  }
+
+  if (!description) {
+    for (const candidate of ["README.md", "readme.md", "README.MD"]) {
+      const readme = readFileIfPresent(path.join(projectRoot, candidate));
+      if (!readme) continue;
+      // First prose paragraph: skip headings, badges, code fences and lists.
+      const paragraph = readme
+        .split(/\r?\n\s*\r?\n/)
+        .map((block) => block.trim())
+        .find((block) =>
+          block.length > 0
+          && !block.startsWith("#")
+          && !block.startsWith("```")
+          && !block.startsWith("[!")
+          && !block.startsWith("-")
+          && !block.startsWith("*")
+          && !block.startsWith("|"));
+      if (paragraph) {
+        description = paragraph.replace(/\s+/g, " ").slice(0, 600);
+        sources.push(candidate);
+      }
+      break;
+    }
+  }
+
+  return { name, description, sources };
+}
+
+function normalizeDeclaredRoute(value: string): string {
+  const raw = value.split(/[?#]/, 1)[0]?.trim() ?? "";
+  if (!raw) return "";
+  const withSlash = raw.startsWith("/") ? raw : `/${raw}`;
+  return withSlash.length > 1 ? withSlash.replace(/\/+$/, "") : "/";
+}
+
+/** Treat `[id]`, `:id` and `[...rest]` as equivalent when matching. */
+function routeShape(route: string): string {
+  return normalizeDeclaredRoute(route)
+    .replace(/\[\[?\.\.\.[^\]]+\]?\]/g, "*")
+    .replace(/\[[^\]]+\]/g, "*")
+    .replace(/:[^/]+/g, "*")
+    .toLowerCase();
+}
+
+/** Declared journeys from spec/journey_graph.yaml, if one is present. */
+export function readDeclaredFlows(specDir: string, projectRoot: string): DeclaredFlow[] {
+  const candidates = [
+    path.join(specDir, "journey_graph.yaml"),
+    path.join(projectRoot, "spec", "journey_graph.yaml"),
+  ];
+  for (const candidate of candidates) {
+    const content = readFileIfPresent(candidate);
+    if (!content) continue;
+    let doc: any;
+    try {
+      doc = YAML.parse(content);
+    } catch {
+      return [];
+    }
+    if (!Array.isArray(doc?.journeys)) return [];
+    return doc.journeys.flatMap((journey: any): DeclaredFlow[] => {
+      if (!journey || typeof journey.id !== "string") return [];
+      const screenRoutes = Array.isArray(journey.screens)
+        ? journey.screens
+          .map((screen: any) => (typeof screen?.path === "string" ? normalizeDeclaredRoute(screen.path) : ""))
+          .filter(Boolean)
+        : [];
+      const actionRoutes = Array.isArray(journey.actions)
+        ? journey.actions
+          .map((action: any) => (typeof action?.target === "string" ? normalizeDeclaredRoute(action.target) : ""))
+          .filter(Boolean)
+        : [];
+      const routes = [...new Set([...screenRoutes, ...actionRoutes])];
+      if (routes.length === 0) return [];
+      return [{
+        id: journey.id,
+        name: typeof journey.name === "string" && journey.name.trim() ? journey.name.trim() : journey.id,
+        description: typeof journey.description === "string" ? journey.description : undefined,
+        routes,
+        source: path.relative(projectRoot, candidate) || candidate,
+      }];
+    });
+  }
+  return [];
+}
+
+/**
+ * Keep only declared flows whose screens actually exist in this app.
+ *
+ * A spec outliving its product is the normal case, not an edge case: this
+ * repo's journey_graph.yaml describes a rental application, so adopting it
+ * here would invent flows over `/book` and `/owner` — screens that do not
+ * exist. Non-matching flows are reported as stale so the mismatch is
+ * visible, rather than silently injected or silently dropped.
+ */
+export function reconcileDeclaredFlows(
+  declared: DeclaredFlow[],
+  discoveredRoutes: string[],
+): DeclaredFlowReconciliation {
+  const known = new Set(discoveredRoutes.map(routeShape));
+  const adopted: DeclaredFlow[] = [];
+  const stale: DeclaredFlowReconciliation["stale"] = [];
+  for (const flow of declared) {
+    const missingRoutes = flow.routes.filter((route) => !known.has(routeShape(route)));
+    if (missingRoutes.length === 0) adopted.push(flow);
+    else stale.push({ id: flow.id, name: flow.name, source: flow.source, missingRoutes });
+  }
+  return { adopted, stale };
+}
+
+export function readAppUnderstanding(
+  projectRoot: string,
+  specDir: string,
+  discoveredRoutes: string[],
+): AppUnderstanding {
+  return {
+    application: readApplicationIdentity(projectRoot),
+    declaredFlows: reconcileDeclaredFlows(readDeclaredFlows(specDir, projectRoot), discoveredRoutes),
+  };
+}