@bugmole/cli 0.4.0

package/src/runtime/init-wizard.ts

@@ -0,0 +1,354 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import YAML from "yaml";
+
+export type StorageProvider = "local" | "gcs" | "s3" | "r2" | "bugmole";
+
+export type InitOptions = {
+  cwd?: string;
+  nonInteractive?: boolean;
+  force?: boolean;
+  configPath?: string;
+  envPath?: string;
+  projectId?: string;
+  projectName?: string;
+  appId?: string;
+  appName?: string;
+  workspaceId?: string;
+  workspaceName?: string;
+  environment?: string;
+  specDir?: string;
+  evidenceManifest?: string;
+  evidenceScreenshots?: string;
+  artifactsDir?: string;
+  storageProvider?: string;
+  bucket?: string;
+  region?: string;
+  endpoint?: string;
+  cloudProjectId?: string;
+  accountId?: string;
+};
+
+export type InitConfig = {
+  projectId: string;
+  projectName: string;
+  appId: string;
+  appName: string;
+  workspaceId: string;
+  workspaceName: string;
+  environment: string;
+  specDir: string;
+  evidenceManifest: string;
+  evidenceScreenshots: string;
+  artifactsDir: string;
+  storageProvider: StorageProvider;
+  bucket?: string;
+  region?: string;
+  endpoint?: string;
+  cloudProjectId?: string;
+  accountId?: string;
+};
+
+const providers = new Set<StorageProvider>(["local", "gcs", "s3", "r2", "bugmole"]);
+
+export function validateStorageProvider(value: string): StorageProvider {
+  const lowered = value.trim().toLowerCase();
+  // "valkyrie" is Bugmole storage's pre-rename name.
+  const normalized = (lowered === "valkyrie" ? "bugmole" : lowered) as StorageProvider;
+  if (!providers.has(normalized)) {
+    throw new Error(`Unsupported storage provider "${value}". Choose local, gcs, s3, r2, or bugmole.`);
+  }
+  return normalized;
+}
+
+function existingDefaults(cwd: string, configPath: string): Partial<InitConfig> {
+  const absolute = path.resolve(cwd, configPath);
+  if (!fs.existsSync(absolute)) return {};
+  const config = YAML.parse(fs.readFileSync(absolute, "utf8")) as Record<string, any>;
+  const project = config.project ?? {};
+  const runtime = config.runtime ?? {};
+  const storage = config.storage ?? {};
+  const provider = storage.provider;
+  return {
+    projectId: project.id,
+    projectName: project.name,
+    appId: project.app_id ?? project.appId ?? project.applications?.[0]?.id,
+    appName: project.app_name ?? project.appName ?? project.applications?.[0]?.name,
+    workspaceId: project.workspace_id ?? project.workspaceId,
+    workspaceName: project.workspace_name ?? project.workspaceName,
+    environment: project.environment ?? runtime.environment,
+    specDir: project.spec_dir ?? runtime.spec_dir,
+    evidenceManifest: project.evidence_manifest,
+    evidenceScreenshots: project.evidence_screenshots,
+    artifactsDir: runtime.artifacts_dir ?? storage.local?.directory,
+    storageProvider: provider && !String(provider).includes("${") ? provider : undefined,
+    bucket: storage[provider]?.bucket,
+    region: storage[provider]?.region,
+    endpoint: storage[provider]?.endpoint,
+    cloudProjectId: storage[provider]?.project_id,
+    accountId: storage[provider]?.account_id,
+  };
+}
+
+const valueOr = (value: string | undefined, fallback: string) => value?.trim() || fallback;
+
+export function openBrowser(url: string): void {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  // With no opener installed (xdg-open on a server), spawn emits "error"; unhandled, that crashes the process.
+  child.on("error", () => undefined);
+  child.unref();
+}
+
+function writeEnvValue(envFile: string, key: string, value: string): void {
+  const existing = fs.existsSync(envFile) ? fs.readFileSync(envFile, "utf8") : "";
+  const line = `${key}=${value}`;
+  const pattern = new RegExp(`^${key}=.*$`, "m");
+  const updated = pattern.test(existing)
+    ? existing.replace(pattern, line)
+    : `${existing}${existing.endsWith("\n") || !existing ? "" : "\n"}${line}\n`;
+  fs.writeFileSync(envFile, updated, "utf8");
+}
+
+function renderConfig(config: InitConfig): string {
+  const cloud =
+    config.storageProvider === "gcs"
+      ? `    bucket: ${config.bucket ?? "${GCS_BUCKET}"}\n    project_id: ${config.cloudProjectId ?? "${GCS_PROJECT_ID}"}\n    credentials_json: \${GCS_CREDENTIALS_JSON}`
+      : config.storageProvider === "s3"
+        ? `    bucket: ${config.bucket ?? "${S3_BUCKET}"}\n    region: ${config.region ?? "${S3_REGION}"}\n    endpoint: ${config.endpoint ?? "${S3_ENDPOINT}"}\n    access_key_id: \${S3_ACCESS_KEY_ID}\n    secret_access_key: \${S3_SECRET_ACCESS_KEY}`
+        : config.storageProvider === "r2"
+          ? `    bucket: ${config.bucket ?? "${R2_BUCKET}"}\n    account_id: ${config.accountId ?? "${R2_ACCOUNT_ID}"}\n    endpoint: ${config.endpoint ?? "${R2_ENDPOINT}"}\n    access_key_id: \${R2_ACCESS_KEY_ID}\n    secret_access_key: \${R2_SECRET_ACCESS_KEY}`
+          : config.storageProvider === "bugmole"
+            ? `    registry_url: \${BUGMOLE_REGISTRY_URL}`
+            : `    directory: \${BUGMOLE_LOCAL_ARTIFACTS_DIR:-${config.artifactsDir}}`;
+  return `version: 1
+project:
+  id: ${config.projectId}
+  name: ${JSON.stringify(config.projectName)}
+  app_id: ${config.appId}
+  app_name: ${JSON.stringify(config.appName)}
+  workspace_id: ${config.workspaceId}
+  workspace_name: ${JSON.stringify(config.workspaceName)}
+  environment: ${config.environment}
+  spec_dir: ${config.specDir}
+  evidence_manifest: ${config.evidenceManifest}
+  evidence_screenshots: ${config.evidenceScreenshots}
+
+runtime:
+  artifacts_dir: ${config.artifactsDir}
+  spec_dir: ${config.specDir}
+  environment: ${config.environment}
+
+storage:
+  provider: ${config.storageProvider}
+  ${config.storageProvider}:
+${cloud}
+
+qa:
+  framework_config: ./bugmole.config.yaml
+  test_plan: ./QA_TEST_PLAN.md
+  evidence: ./QA_EVIDENCE.md
+`;
+}
+
+function renderEnv(config: InitConfig): string {
+  const lines = [
+    "# Generated by bugmole init. Fill credentials privately; never commit this file.",
+    `BUGMOLE_PROJECT_ID=${config.projectId}`,
+    `BUGMOLE_PROJECT_NAME=${JSON.stringify(config.projectName)}`,
+    `BUGMOLE_APP_ID=${config.appId}`,
+    `BUGMOLE_APP_NAME=${JSON.stringify(config.appName)}`,
+    `BUGMOLE_WORKSPACE_ID=${config.workspaceId}`,
+    `BUGMOLE_WORKSPACE_NAME=${JSON.stringify(config.workspaceName)}`,
+    `BUGMOLE_ENVIRONMENT=${config.environment}`,
+    `BUGMOLE_STORAGE_PROVIDER=${config.storageProvider}`,
+    `BUGMOLE_LOCAL_ARTIFACTS_DIR=${config.artifactsDir}`,
+    `BUGMOLE_AEGIS_EMAIL=${JSON.stringify(process.env.BUGMOLE_AEGIS_EMAIL?.trim() ?? "")}`,
+    "",
+  ];
+  if (config.storageProvider === "gcs") {
+    lines.push(
+      "# GCS identifiers",
+      `GCS_BUCKET=${config.bucket ?? ""}`,
+      `GCS_PROJECT_ID=${config.cloudProjectId ?? ""}`,
+      "GCS_CREDENTIALS_JSON=REPLACE_ME",
+    );
+  } else if (config.storageProvider === "s3") {
+    lines.push(
+      "# S3-compatible identifiers",
+      `S3_BUCKET=${config.bucket ?? ""}`,
+      `S3_REGION=${config.region ?? ""}`,
+      `S3_ENDPOINT=${config.endpoint ?? ""}`,
+      "S3_ACCESS_KEY_ID=REPLACE_ME",
+      "S3_SECRET_ACCESS_KEY=REPLACE_ME",
+    );
+  } else if (config.storageProvider === "r2") {
+    lines.push(
+      "# Cloudflare R2 identifiers",
+      `R2_BUCKET=${config.bucket ?? ""}`,
+      `R2_ACCOUNT_ID=${config.accountId ?? ""}`,
+      `R2_ENDPOINT=${config.endpoint ?? ""}`,
+      "R2_ACCESS_KEY_ID=REPLACE_ME",
+      "R2_SECRET_ACCESS_KEY=REPLACE_ME",
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+async function ask(rl: readline.Interface, label: string, fallback: string): Promise<string> {
+  const answer = await rl.question(`${label} [${fallback}]: `);
+  return valueOr(answer, fallback);
+}
+
+export async function runInitWizard(
+  options: InitOptions = {},
+): Promise<{ configPath: string; envPath: string; config: InitConfig }> {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = options.configPath ?? ".bugmole/config.yaml";
+  const envPath = options.envPath ?? ".bugmole.env";
+  const defaults = existingDefaults(cwd, configPath);
+  const nonInteractive = options.nonInteractive ?? process.env.BUGMOLE_NON_INTERACTIVE === "true";
+  const rl = nonInteractive ? undefined : readline.createInterface({ input, output });
+  const choose = async (value: string | undefined, label: string, fallback: string) =>
+    value?.trim() || (rl ? await ask(rl, label, fallback) : fallback);
+  try {
+    const config: InitConfig = {
+      workspaceId: await choose(options.workspaceId, "Workspace id", valueOr(defaults.workspaceId, `workspace_${path.basename(cwd)}`)),
+      workspaceName: await choose(options.workspaceName, "Workspace name", valueOr(defaults.workspaceName, path.basename(cwd))),
+      projectId: await choose(options.projectId, "Project id", valueOr(defaults.projectId, path.basename(cwd))),
+      projectName: await choose(options.projectName, "Project name", valueOr(defaults.projectName, path.basename(cwd))),
+      appId: await choose(options.appId, "Default app id", valueOr(defaults.appId, "default")),
+      appName: await choose(options.appName, "Default app name", valueOr(defaults.appName, path.basename(cwd))),
+      environment: await choose(options.environment, "Environment", valueOr(defaults.environment, "local")),
+      specDir: await choose(options.specDir, "Spec directory", valueOr(defaults.specDir, "./spec")),
+      evidenceManifest: await choose(options.evidenceManifest, "Evidence manifest", valueOr(defaults.evidenceManifest, "./qa/browser-evidence.json")),
+      evidenceScreenshots: await choose(options.evidenceScreenshots, "Evidence screenshots directory", valueOr(defaults.evidenceScreenshots, "./qa/screenshots")),
+      artifactsDir: await choose(options.artifactsDir, "Artifact directory", valueOr(defaults.artifactsDir, "./qa/bugmole-runs")),
+      storageProvider: validateStorageProvider(
+        await choose(options.storageProvider, "Storage provider (local|gcs|s3|r2|bugmole)", valueOr(defaults.storageProvider, "local")),
+      ),
+    };
+    if (config.storageProvider !== "local" && config.storageProvider !== "bugmole") {
+      config.bucket = await choose(options.bucket, "Bucket", valueOr(defaults.bucket, ""));
+      if (config.storageProvider === "gcs")
+        config.cloudProjectId = await choose(options.cloudProjectId, "GCS project id", valueOr(defaults.cloudProjectId, ""));
+      if (config.storageProvider === "s3")
+        config.region = await choose(options.region, "S3 region", valueOr(defaults.region, ""));
+      if (config.storageProvider === "r2")
+        config.accountId = await choose(options.accountId, "R2 account id", valueOr(defaults.accountId, ""));
+      if (config.storageProvider !== "gcs")
+        config.endpoint = await choose(options.endpoint, "Endpoint (blank for provider default)", valueOr(defaults.endpoint, ""));
+    }
+    const configFile = path.resolve(cwd, configPath);
+    const envFile = path.resolve(cwd, envPath);
+    const exists = fs.existsSync(configFile);
+    const shouldWrite =
+      !exists || options.force || nonInteractive
+        ? !exists || options.force
+        : (await rl!.question(`Overwrite ${configPath}? [y/N]: `)).trim().toLowerCase() === "y";
+    if (shouldWrite) {
+      fs.mkdirSync(path.dirname(configFile), { recursive: true });
+      fs.writeFileSync(configFile, renderConfig(config), "utf8");
+      if (options.force || !fs.existsSync(envFile)) {
+        fs.writeFileSync(envFile, renderEnv(config), "utf8");
+        console.log(`Generated ${configPath} and ${envPath}.`);
+      } else {
+        console.log(`Generated ${configPath}; kept existing ${envPath}.`);
+      }
+    } else {
+      console.log(`Kept existing ${configPath}; no files overwritten.`);
+    }
+    const registryUrl =
+      process.env.BUGMOLE_REGISTRY_URL?.trim() || "https://api.bugmole.com";
+    const apiKey = process.env.BUGMOLE_API_KEY?.trim();
+    if (registryUrl && apiKey && shouldWrite) {
+      const headers: Record<string, string> = {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`,
+      };
+      const response = await fetch(`${registryUrl.replace(/\/$/, "")}/api/projects/register`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          id: config.projectId,
+          name: config.projectName,
+          appId: config.appId,
+          appName: config.appName,
+          workspaceId: config.workspaceId,
+          workspaceName: config.workspaceName,
+          environment: config.environment,
+          storageProvider: config.storageProvider,
+        }),
+      });
+      if (!response.ok) {
+        throw new Error(`Bugmole registry rejected project registration (${response.status})`);
+      }
+      console.log(`Registered ${config.projectId} with the Bugmole registry.`);
+    } else if (registryUrl && !apiKey && shouldWrite && !nonInteractive) {
+      const createResponse = await fetch(`${registryUrl.replace(/\/$/, "")}/api/device-authorizations`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          projectId: config.projectId,
+          projectName: config.projectName,
+          environment: config.environment,
+          storageProvider: config.storageProvider,
+        }),
+      });
+      const attempt = await createResponse.json().catch(() => null) as {
+        attemptId?: string;
+        code?: string;
+        pollSecret?: string;
+        expiresAt?: string;
+        error?: string;
+      } | null;
+      if (!createResponse.ok || !attempt?.attemptId || !attempt.code || !attempt.pollSecret) {
+        throw new Error(attempt?.error ?? "Unable to start Bugmole device registration");
+      }
+      const dashboardUrl =
+        process.env.BUGMOLE_DASHBOARD_URL?.trim() || "https://app.bugmole.com";
+      const registrationUrl =
+        `${dashboardUrl.replace(/\/$/, "")}/register?attemptId=${encodeURIComponent(attempt.attemptId)}&projectId=${encodeURIComponent(config.projectId)}${process.env.BUGMOLE_AEGIS_EMAIL?.trim() ? `&email=${encodeURIComponent(process.env.BUGMOLE_AEGIS_EMAIL.trim())}` : ""}`;
+      console.log(`Open ${registrationUrl} and enter code: ${attempt.code}`);
+      openBrowser(registrationUrl);
+      console.log("Waiting for Aegis registration...");
+      for (let poll = 0; poll < 300; poll++) {
+        await new Promise((resolve) => setTimeout(resolve, 2_000));
+        const pollResponse = await fetch(`${registryUrl.replace(/\/$/, "")}/api/device-authorizations/poll`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ attemptId: attempt.attemptId, pollSecret: attempt.pollSecret }),
+        });
+        const result = await pollResponse.json().catch(() => null) as {
+          status?: string;
+          token?: string;
+          email?: string;
+          alreadyInitialized?: boolean;
+          error?: string;
+        } | null;
+        if (result?.status === "pending") continue;
+        if (!pollResponse.ok) {
+          const detail = result?.error ?? result?.status ?? `HTTP ${pollResponse.status}`;
+          throw new Error(`Bugmole device registration failed: ${detail}`);
+        }
+        if (result?.alreadyInitialized) {
+          throw new Error("This Aegis account already has an API key; revoke it or use that key in .bugmole.env.");
+        }
+        if (result?.token) {
+          writeEnvValue(envFile, "BUGMOLE_REGISTRY_URL", registryUrl);
+          writeEnvValue(envFile, "BUGMOLE_API_KEY", result.token);
+          if (result.email) writeEnvValue(envFile, "BUGMOLE_AEGIS_EMAIL", JSON.stringify(result.email.trim()));
+          console.log(`Registered ${config.projectId}; saved the machine credential to ${envPath}.`);
+          break;
+        }
+      }
+    }
+    return { configPath, envPath, config };
+  } finally {
+    rl?.close();
+  }
+}

package/src/runtime/ios-screen-record.test.ts

@@ -0,0 +1,68 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import {
+  chunkPattern,
+  chunkPrefix,
+  clampIosChunkSeconds,
+  DEFAULT_CHUNK_SECONDS,
+  DEFAULT_MJPEG_URL,
+  ffmpegSegmentArgs,
+  mjpegUrl,
+  startIosScreenRecording,
+} from "./ios-screen-record.js";
+
+test("the names written and the names looked for cannot drift apart", () => {
+  // They did drift once: every chunk was recorded correctly and then reported
+  // as none, because the prefix was assembled separately from the pattern.
+  const base = "/runs/abc/run.mp4";
+  assert.equal(chunkPattern(base), "/runs/abc/run-%03d.mp4");
+  assert.equal(chunkPrefix(base), "run-");
+  assert.ok("run-001.mp4".startsWith(chunkPrefix(base)));
+});
+
+test("the chunk number goes before the extension, not after it", () => {
+  assert.equal(chunkPattern("/runs/run.mp4"), "/runs/run-%03d.mp4");
+  assert.equal(chunkPattern("/runs/run"), "/runs/run-%03d");
+  // A dot in a directory name is not an extension.
+  assert.equal(chunkPattern("/runs/v1.2/run"), "/runs/v1.2/run-%03d");
+});
+
+test("chunks are numbered from one, matching the Android recorder", () => {
+  const args = ffmpegSegmentArgs("http://x", "/o/run-%03d.mp4", 10, 10);
+  assert.equal(args[args.indexOf("-segment_start_number") + 1], "1");
+});
+
+test("MJPEG is stamped with wall-clock time, or every duration is wrong", () => {
+  // MJPEG carries no timestamps: ffmpeg otherwise assumes a nominal rate and a
+  // 22s recording asks for 550 frames from a source serving nine a second.
+  assert.ok(ffmpegSegmentArgs("http://x", "/o/r-%03d.mp4", 10, 10).includes("-use_wallclock_as_timestamps"));
+});
+
+test("keyframes are forced at the segment boundary", () => {
+  // A segment can only start on a keyframe. Without forcing them a chunk asked
+  // to be ten seconds ran fifteen.
+  const args = ffmpegSegmentArgs("http://x", "/o/r-%03d.mp4", 10, 10);
+  assert.match(args[args.indexOf("-force_key_frames") + 1], /n_forced\*10/);
+  assert.equal(args[args.indexOf("-segment_time") + 1], "10");
+});
+
+test("an absurd chunk length falls back rather than recording one huge file", () => {
+  assert.equal(clampIosChunkSeconds(undefined), DEFAULT_CHUNK_SECONDS);
+  assert.equal(clampIosChunkSeconds(0), DEFAULT_CHUNK_SECONDS);
+  assert.equal(clampIosChunkSeconds(-5), DEFAULT_CHUNK_SECONDS);
+  assert.equal(clampIosChunkSeconds(30), 30);
+  assert.equal(clampIosChunkSeconds(99_999), 3_600);
+});
+
+test("the MJPEG server is reached over the cable by default", () => {
+  assert.equal(mjpegUrl({}), DEFAULT_MJPEG_URL);
+  assert.match(DEFAULT_MJPEG_URL, /^http:\/\/127\.0\.0\.1:/);
+  assert.equal(mjpegUrl({ BUGMOLE_IOS_MJPEG_URL: "http://127.0.0.1:9200" }), "http://127.0.0.1:9200");
+});
+
+test("returns undefined instead of throwing when ffmpeg is unavailable", async () => {
+  const recording = await startIosScreenRecording("/tmp/bugmole-ios-rec-test/run.mp4", {
+    ffmpegCommand: "definitely-not-a-real-ffmpeg-binary",
+  });
+  assert.equal(recording, undefined);
+});

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

@@ -0,0 +1,155 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+import { dropIdleFrames } from "./screen-recording.js";
+
+export type IosScreenRecording = {
+  /** Stops recording and returns every chunk, in order. */
+  stop(): Promise<string[]>;
+};
+
+export interface IosRecordingOptions {
+  /** Seconds per chunk. */
+  chunkSeconds?: number;
+  /** Drop frames where the screen did not change. */
+  skipIdle?: boolean;
+  /** WebDriverAgent's MJPEG server, reached over the usbmux forward. */
+  mjpegUrl?: string;
+  ffmpegCommand?: string;
+  /** Frames per second WDA is serving; used to place keyframes. */
+  fps?: number;
+}
+
+export const DEFAULT_MJPEG_URL = "http://127.0.0.1:9100";
+/** WDA's mjpegServerFramerate defaults to 10, and measured ~8.8 in practice. */
+export const DEFAULT_MJPEG_FPS = 10;
+export const DEFAULT_CHUNK_SECONDS = 180;
+
+export function clampIosChunkSeconds(value: number | undefined): number {
+  if (!Number.isFinite(value) || (value as number) <= 0) return DEFAULT_CHUNK_SECONDS;
+  // No screenrecord ceiling here — ffmpeg segments as long as asked — but an
+  // hour-long chunk defeats the point of chunking at all.
+  return Math.min(Math.floor(value as number), 3_600);
+}
+
+export function mjpegUrl(env: Record<string, string | undefined> = process.env): string {
+  return env.BUGMOLE_IOS_MJPEG_URL?.trim() || DEFAULT_MJPEG_URL;
+}
+
+/**
+ * Record WebDriverAgent's MJPEG stream, segmented as it goes.
+ *
+ * iOS has no screenrecord. pymobiledevice3 offers only stills, and the phone
+ * does not appear as an AVFoundation capture device here, so the usable source
+ * is WDA's own MJPEG server on port 9100 — the same runner already driving
+ * input, reached over the same usbmux forward.
+ *
+ * ffmpeg does the segmenting rather than a supervisor loop, so unlike the
+ * Android path there is no seam between chunks: one continuous input is cut at
+ * keyframe boundaries.
+ */
+export function ffmpegSegmentArgs(
+  source: string,
+  outputPattern: string,
+  chunkSeconds: number,
+  fps: number,
+): string[] {
+  return [
+    "-hide_banner", "-loglevel", "error",
+    // MJPEG carries no timestamps. Without this ffmpeg assumes a nominal frame
+    // rate and every duration is wrong — a 22s recording asked for 550 frames
+    // at a source delivering nine a second.
+    "-use_wallclock_as_timestamps", "1",
+    "-f", "mjpeg", "-i", source,
+    "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",
+    "-fps_mode", "vfr",
+    // Segments can only start on a keyframe. Without forcing them the cut
+    // lands wherever the encoder last put one, and a chunk asked to be ten
+    // seconds ran fifteen.
+    "-force_key_frames", `expr:gte(t,n_forced*${chunkSeconds})`,
+    "-g", String(Math.max(1, Math.round(fps * chunkSeconds))),
+    "-f", "segment",
+    "-segment_time", String(chunkSeconds),
+    "-reset_timestamps", "1",
+    // One-based, to match the Android recorder's run-001.mp4.
+    "-segment_start_number", "1",
+    outputPattern,
+  ];
+}
+
+/** `run.mp4` becomes the `run-%03d.mp4` pattern ffmpeg writes chunks through. */
+export function chunkPattern(basePath: string): string {
+  const dot = basePath.lastIndexOf(".");
+  return dot <= basePath.lastIndexOf("/")
+    ? `${basePath}-%03d`
+    : `${basePath.slice(0, dot)}-%03d${basePath.slice(dot)}`;
+}
+
+/**
+ * The literal part of the chunk filenames, up to ffmpeg's number placeholder.
+ *
+ * Taken from the pattern rather than assembled separately, so the names
+ * written and the names looked for cannot drift apart — they already did once,
+ * and every chunk was recorded correctly and then reported as none.
+ */
+export function chunkPrefix(basePath: string): string {
+  const pattern = path.basename(chunkPattern(basePath));
+  return pattern.slice(0, pattern.indexOf("%"));
+}
+
+export async function startIosScreenRecording(
+  localBasePath: string,
+  options: IosRecordingOptions = {},
+): Promise<IosScreenRecording | undefined> {
+  const chunkSeconds = clampIosChunkSeconds(options.chunkSeconds);
+  const ffmpegCommand = options.ffmpegCommand ?? "ffmpeg";
+  const source = options.mjpegUrl ?? mjpegUrl();
+  const pattern = chunkPattern(localBasePath);
+  await fs.mkdir(path.dirname(localBasePath), { recursive: true }).catch(() => undefined);
+
+  let spawnFailed = false;
+  const child: ChildProcess = spawn(
+    ffmpegCommand,
+    ffmpegSegmentArgs(source, pattern, chunkSeconds, options.fps ?? DEFAULT_MJPEG_FPS),
+    { stdio: "ignore" },
+  );
+  child.once("error", () => { spawnFailed = true; });
+  // Long enough to surface a missing ffmpeg or an unreachable MJPEG server,
+  // which both fail immediately rather than midway.
+  await new Promise((resolve) => setTimeout(resolve, 800));
+  if (spawnFailed || child.exitCode !== null) return undefined;
+
+  return {
+    async stop(): Promise<string[]> {
+      // SIGINT, not SIGKILL: ffmpeg writes the trailer of the segment it is
+      // holding on interrupt. Killing it outright leaves the last chunk with
+      // no moov atom, which is the same way the Android path lost the end of
+      // every run.
+      try {
+        child.kill("SIGINT");
+        await new Promise<void>((resolve) => {
+          child.once("exit", () => resolve());
+          setTimeout(resolve, 15_000);
+        });
+      } catch {
+        // Already gone; whatever it finished writing still counts.
+      }
+      const dir = path.dirname(localBasePath);
+      const entries = await fs.readdir(dir).catch(() => [] as string[]);
+      const chunks = entries
+        .filter((name) => name.startsWith(chunkPrefix(localBasePath)) && /-\d{3}\.mp4$/.test(name))
+        .sort()
+        .map((name) => path.join(dir, name));
+      const kept: string[] = [];
+      for (const chunk of chunks) {
+        const stats = await fs.stat(chunk).catch(() => undefined);
+        if (!stats || stats.size === 0) {
+          await fs.rm(chunk, { force: true }).catch(() => undefined);
+          continue;
+        }
+        kept.push(options.skipIdle ? await dropIdleFrames(chunk, ffmpegCommand) : chunk);
+      }
+      return kept;
+    },
+  };
+}