@deeeed/metamask-harness 0.4.0 → 0.5.0

package/dist/paths.js

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pathDefaults = readPathDefaults();
+const DEFAULT_RECIPE_RUNTIME_DIR = pathDefaults.recipeRuntimeDir;
+const DEFAULT_RECIPE_HARNESS_ROOT = pathDefaults.recipeHarnessRoot;
+function recipeRuntimeDir() {
+  return validateRelativeRecipePath("RECIPE_RUNTIME_DIR", process.env.RECIPE_RUNTIME_DIR || DEFAULT_RECIPE_RUNTIME_DIR);
+}
+function recipeHarnessRoot() {
+  return validateRelativeRecipePath("RECIPE_HARNESS_ROOT", process.env.RECIPE_HARNESS_ROOT || DEFAULT_RECIPE_HARNESS_ROOT);
+}
+function readPathDefaults() {
+  const defaultsPath = path.join(runnerDir, "adapters/shared/path-defaults.json");
+  const parsed = JSON.parse(fs.readFileSync(defaultsPath, "utf8"));
+  return {
+    recipeRuntimeDir: validateRelativeRecipePath("recipeRuntimeDir", parsed.recipeRuntimeDir || ""),
+    recipeHarnessRoot: validateRelativeRecipePath("recipeHarnessRoot", parsed.recipeHarnessRoot || "")
+  };
+}
+function validateRelativeRecipePath(name, value) {
+  if (!value || path.isAbsolute(value)) throw new Error(`${name} must be a non-empty relative path: ${value}`);
+  if (!/^[A-Za-z0-9._/-]+$/u.test(value)) throw new Error(`${name} contains unsupported characters: ${value}`);
+  for (const part of value.split("/")) {
+    if (!part || part === "." || part === "..") throw new Error(`${name} contains unsafe path component: ${value}`);
+  }
+  return value;
+}
+function recipeRuntimePath(projectRoot, ...segments) {
+  return path.join(projectRoot, recipeRuntimeDir(), ...segments);
+}
+function recipeHarnessPath(projectRoot, ...segments) {
+  return path.join(projectRoot, recipeHarnessRoot(), ...segments);
+}
+function walletFixturePath(projectRoot) {
+  return recipeRuntimePath(projectRoot, "wallet-fixture.json");
+}
+function extensionIdPath(projectRoot) {
+  return recipeRuntimePath(projectRoot, "extension.id");
+}
+function recipeWatchLogCandidates() {
+  return [
+    path.join(recipeRuntimeDir(), "webpack.log"),
+    path.join(recipeRuntimeDir(), "recipe-harness-webpack.log")
+  ];
+}
+function resolveLocalProtocolRoot() {
+  const candidates = [
+    process.env.FARMSLOT_ROOT,
+    readConfiguredProtocolRoot(),
+    findProtocolRoot(runnerDir),
+    findProtocolRoot(process.cwd())
+  ].filter(Boolean);
+  const root = candidates[0];
+  return root ? path.resolve(root) : void 0;
+}
+function resolveRequiredLocalProtocolRoot(reason) {
+  const root = resolveLocalProtocolRoot();
+  if (!root) {
+    throw new Error(
+      `${reason} requires a local protocol/runtime checkout. Set FARMSLOT_ROOT or create .farmslot-root for this dev-only path.`
+    );
+  }
+  return root;
+}
+function readConfiguredProtocolRoot() {
+  const configPath = path.join(runnerDir, ".farmslot-root");
+  if (!fs.existsSync(configPath)) return void 0;
+  const value = fs.readFileSync(configPath, "utf8").trim();
+  return value || void 0;
+}
+function findProtocolRoot(start) {
+  let dir = path.resolve(start);
+  while (dir !== path.dirname(dir)) {
+    if (isProtocolRoot(dir)) return dir;
+    const sibling = path.join(dir, "farmslot");
+    if (isProtocolRoot(sibling)) return sibling;
+    dir = path.dirname(dir);
+  }
+  return void 0;
+}
+function isProtocolRoot(candidate) {
+  return fs.existsSync(path.join(candidate, "packages/recipe-harness/package.json")) && fs.existsSync(path.join(candidate, "packages/protocol/package.json"));
+}
+function assertAdapter(adapter) {
+  if (adapter !== "mobile" && adapter !== "extension" && adapter !== "core") {
+    throw new Error("Adapter must be mobile, extension, or core.");
+  }
+}
+function manifestPath(adapter) {
+  assertAdapter(adapter);
+  return path.join(runnerDir, "library/manifests", `${adapter}.action-manifest.json`);
+}
+function recipePath(name) {
+  return path.join(runnerDir, "library/recipes", name);
+}
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+async function importRecipeHarness() {
+  return importProtocolPackage(
+    "@farmslot/recipe-harness",
+    "packages/recipe-harness/src/index.ts"
+  );
+}
+async function importRecipeHarnessRuntimeCdp() {
+  return importProtocolPackage(
+    "@farmslot/recipe-harness/runtime/cdp",
+    "packages/recipe-harness/src/runtime/cdp.ts"
+  );
+}
+async function importRecipeHarnessRuntimeBrowserExtension() {
+  return importProtocolPackage(
+    "@farmslot/recipe-harness/runtime/browser-extension",
+    "packages/recipe-harness/src/runtime/browser-extension.ts"
+  );
+}
+async function importRecipeHarnessRuntimeReactNativeBridge() {
+  return importProtocolPackage(
+    "@farmslot/recipe-harness/runtime/react-native-bridge",
+    "packages/recipe-harness/src/runtime/react-native-bridge.ts"
+  );
+}
+async function importRecipeHarnessCli() {
+  return importProtocolPackage(
+    "@farmslot/recipe-harness/cli",
+    "packages/recipe-harness/src/cli/index.ts"
+  );
+}
+async function importRecipeProtocol() {
+  return importProtocolPackage(
+    "@farmslot/protocol",
+    "packages/protocol/src/index.ts"
+  );
+}
+async function importProtocolPackage(packageName, localSourceEntry) {
+  try {
+    return await import(packageName);
+  } catch (error) {
+    if (!isMissingPackageError(error, packageName)) throw error;
+  }
+  const root = resolveLocalProtocolRoot();
+  if (!root) {
+    throw new Error(
+      `${packageName} is not installed. Install @farmslot/* packages normally, or set FARMSLOT_ROOT/use npm run dev:link-farmslot while co-developing protocol packages locally.`
+    );
+  }
+  return import(pathToFileURL(path.join(root, localSourceEntry)).href);
+}
+function isMissingPackageError(error, packageName) {
+  if (!(error instanceof Error)) return false;
+  const code = error.code;
+  return code === "ERR_MODULE_NOT_FOUND" && error.message.includes(packageName);
+}
+export {
+  DEFAULT_RECIPE_HARNESS_ROOT,
+  DEFAULT_RECIPE_RUNTIME_DIR,
+  assertAdapter,
+  extensionIdPath,
+  importRecipeHarness,
+  importRecipeHarnessCli,
+  importRecipeHarnessRuntimeBrowserExtension,
+  importRecipeHarnessRuntimeCdp,
+  importRecipeHarnessRuntimeReactNativeBridge,
+  importRecipeProtocol,
+  manifestPath,
+  readJson,
+  recipeHarnessPath,
+  recipeHarnessRoot,
+  recipePath,
+  recipeRuntimeDir,
+  recipeRuntimePath,
+  recipeWatchLogCandidates,
+  resolveLocalProtocolRoot,
+  resolveRequiredLocalProtocolRoot,
+  runnerDir,
+  walletFixturePath
+};

package/dist/progress.js

@@ -0,0 +1,94 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { color } from "./cli-color.js";
+function shouldEmitJson(explicit) {
+  if (explicit) return true;
+  const env = process.env.RECIPE_PROGRESS_JSON;
+  return env === "1" || env === "true";
+}
+function emitProgress(event, { json = false } = {}) {
+  const payload = {
+    schemaVersion: 1,
+    type: "progress",
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    ...event
+  };
+  if (json || shouldEmitJson(false)) {
+    process.stderr.write(`${JSON.stringify(payload)}
+`);
+    return;
+  }
+  const stream = process.stderr;
+  const prefix = color("label", "recipe", { stream });
+  if (payload.phase === "done") {
+    const statusStyle = payload.status === "pass" ? "ok" : "err";
+    const statusWord = payload.status === "pass" ? "done" : "failed";
+    const cmd2 = payload.command ? color("cmd", `${payload.command}`, { stream }) : "";
+    const elapsed2 = Number.isFinite(payload.elapsedMs) ? color("comment", ` (${Math.round(payload.elapsedMs / 1e3)}s)`, { stream }) : "";
+    process.stderr.write(`${prefix}: ${cmd2} ${color(statusStyle, statusWord, { stream })} ${payload.message || ""}${elapsed2}
+`);
+    return;
+  }
+  const cmd = payload.command ? `${color("cmd", payload.command, { stream })}: ` : "";
+  const phase = payload.phase ? `${color("accent", `[${payload.phase}]`, { stream })} ` : "";
+  const elapsed = Number.isFinite(payload.elapsedMs) ? color("comment", ` (${Math.round(payload.elapsedMs / 1e3)}s)`, { stream }) : "";
+  process.stderr.write(`${prefix}: ${cmd}${phase}${payload.message || ""}${elapsed}
+`);
+}
+function usage() {
+  console.error(`Usage:
+  progress emit --command <name> --phase <id> --message <text> [--elapsed-ms <n>] [--json]
+  progress done --command <name> --status pass|fail --message <text> [--elapsed-ms <n>] [--json]`);
+}
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (!command || command === "--help" || command === "-h") {
+    usage();
+    process.exit(command ? 0 : 2);
+  }
+  const { values } = parseArgs({
+    args: rest,
+    options: {
+      command: { type: "string" },
+      phase: { type: "string" },
+      message: { type: "string" },
+      status: { type: "string" },
+      "elapsed-ms": { type: "string" },
+      json: { type: "boolean", default: false }
+    },
+    allowPositionals: false
+  });
+  const elapsedMs = values["elapsed-ms"] ? Number.parseInt(values["elapsed-ms"], 10) : void 0;
+  const json = values.json || shouldEmitJson(false);
+  if (command === "emit") {
+    emitProgress({
+      command: values.command || "recipe",
+      phase: values.phase || "working",
+      message: values.message || "",
+      elapsedMs: Number.isFinite(elapsedMs) ? elapsedMs : void 0
+    }, { json });
+    return;
+  }
+  if (command === "done") {
+    emitProgress({
+      command: values.command || "recipe",
+      phase: "done",
+      status: values.status || "pass",
+      message: values.message || "",
+      elapsedMs: Number.isFinite(elapsedMs) ? elapsedMs : void 0
+    }, { json });
+    return;
+  }
+  usage();
+  process.exit(2);
+}
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename ?? "");
+if (isMain) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}
+export {
+  emitProgress
+};

package/dist/recording-target.js

@@ -0,0 +1,133 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+function createMetaMaskRecordingTargetProvider(adapter) {
+  return {
+    async resolveRecordingTarget(context) {
+      if (adapter === "extension") {
+        const pid = resolveExtensionBrowserPid(
+          context.projectRoot,
+          context.artifactsDir,
+          context.env.CDP_PORT ?? context.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT
+        );
+        if (!pid) {
+          throw new Error(
+            "Could not resolve the extension browser PID for --record-video. Ensure the slot browser is running and CDP_PORT is set."
+          );
+        }
+        return { kind: "pid", pid };
+      }
+      if (adapter === "mobile") {
+        const platform = (context.env.PLATFORM ?? process.env.PLATFORM ?? "ios").trim().toLowerCase();
+        if (platform === "android" || context.env.ADB_SERIAL || process.env.ADB_SERIAL) {
+          throw new Error("--record-video is not implemented for mobile Android replay yet.");
+        }
+        const simulator = resolveMobileIosSimulatorName(context.env);
+        if (!simulator) {
+          throw new Error(
+            "Could not resolve an iOS simulator name for --record-video. Set IOS_SIMULATOR or pass --simulator to the recipe hook."
+          );
+        }
+        const pid = resolveMobileIosSimulatorPid(simulator);
+        if (pid) return { kind: "pid", pid };
+        return { kind: "app-window", appName: "Simulator", windowName: simulator };
+      }
+      throw new Error(`--record-video is not implemented for the ${adapter} adapter.`);
+    }
+  };
+}
+function captureHelperSupportsRecordSessionSnapshots(projectRoot) {
+  const result = spawnSync(captureHelperPath(), ["version", "--json"], {
+    cwd: projectRoot,
+    encoding: "utf8"
+  });
+  if (result.status !== 0) return false;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return Array.isArray(parsed.capabilities) && parsed.capabilities.includes("record_session_snapshot");
+  } catch {
+    return false;
+  }
+}
+function resolveMobileIosSimulatorName(env = process.env) {
+  const explicit = env.IOS_SIMULATOR?.trim() || env.SIM_UDID?.trim();
+  if (explicit) return explicit;
+  const slot = env.FARMSLOT_SLOT_ID?.trim() || env.SLOT_ID?.trim();
+  if (!slot) return void 0;
+  const suffix = slot.includes("-") ? slot.slice(slot.lastIndexOf("-") + 1) : slot;
+  return suffix || void 0;
+}
+function resolveMobileIosSimulatorPid(simulator) {
+  const result = spawnSync(
+    captureHelperPath(),
+    ["resolve", "--app-name", "Simulator", "--window-name", simulator, "--json"],
+    { encoding: "utf8" }
+  );
+  if (result.status !== 0) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return parsePositivePid(parsed.selected?.pid);
+  } catch {
+    return null;
+  }
+}
+function resolveExtensionBrowserPid(projectRoot, artifactsDir, cdpPort) {
+  const explicit = parsePositivePid(process.env.METAMASK_RECIPE_EXTENSION_BROWSER_PID);
+  if (explicit) return explicit;
+  if (cdpPort) {
+    const lsof = spawnSync("lsof", ["-nP", `-iTCP:${cdpPort}`, "-sTCP:LISTEN", "-t"], {
+      cwd: projectRoot,
+      encoding: "utf8"
+    });
+    if (lsof.status === 0) {
+      const pid = parsePositivePid(String(lsof.stdout).split(/\s+/u).find(Boolean));
+      if (pid) return pid;
+    }
+  }
+  for (const file of [
+    path.join(artifactsDir, "extension-runtime/runtime.json"),
+    path.join(projectRoot, "temp/recipe/runtime/runtime.json")
+  ]) {
+    const pid = parsePositivePid(readJsonFile(file)?.pid);
+    if (pid) return pid;
+  }
+  for (const file of [
+    path.join(projectRoot, "temp/recipe/runtime/chromium.pid"),
+    path.join(projectRoot, "temp/recipe/runtime/browser.pid")
+  ]) {
+    const pid = parsePositivePid(readTextFile(file));
+    if (pid) return pid;
+  }
+  return null;
+}
+function captureHelperPath() {
+  return process.env.CAPTURE_HELPER_PATH || "capture-helper";
+}
+function parsePositivePid(value) {
+  const pid = Number(String(value ?? "").trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+function readJsonFile(file) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function readTextFile(file) {
+  if (!fs.existsSync(file)) return "";
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+}
+export {
+  captureHelperSupportsRecordSessionSnapshots,
+  createMetaMaskRecordingTargetProvider,
+  resolveExtensionBrowserPid,
+  resolveMobileIosSimulatorName,
+  resolveMobileIosSimulatorPid
+};

package/dist/run-recording.js

@@ -0,0 +1,271 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  captureHelperSupportsRecordSessionSnapshots,
+  resolveExtensionBrowserPid
+} from "./recording-target.js";
+const activeRecordingsByPid = /* @__PURE__ */ new Map();
+async function startRecipeRecording(adapter, projectRoot, artifactsDir, options) {
+  if (!options.record) return void 0;
+  if (process.platform !== "darwin") {
+    console.error(
+      "WARN: --record uses capture-helper and is currently supported only on macOS; continuing without video."
+    );
+    return void 0;
+  }
+  if (adapter !== "extension") return void 0;
+  const cdpPort = options.cdpPort ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  if (!captureHelperSupportsRecordSessionSnapshots(projectRoot)) {
+    console.error(
+      "WARN: framed extension recording requires capture-helper capability record_session_snapshot; falling back to harness --record-video."
+    );
+    return void 0;
+  }
+  const pid = resolveExtensionBrowserPid(projectRoot, artifactsDir, cdpPort);
+  if (!pid) {
+    console.error(
+      `WARN: framed extension recording could not resolve browser PID from CDP port ${cdpPort ?? "<unset>"}; falling back to harness --record-video.`
+    );
+    return void 0;
+  }
+  const recordArgs = ["record", "--framed", "--pid", String(pid)];
+  const relativePath = "videos/full-run.mp4";
+  const outputPath = path.join(artifactsDir, relativePath);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.rmSync(outputPath, { force: true });
+  const child = spawn(captureHelperPath(), [...recordArgs, "--output", outputPath], {
+    cwd: projectRoot,
+    env: process.env,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  const recording = {
+    child,
+    outputPath,
+    relativePath,
+    pid,
+    stdout: "",
+    stderr: "",
+    exited: false,
+    exitCode: null,
+    stderrBuffer: "",
+    pendingSnapshots: /* @__PURE__ */ new Map()
+  };
+  child.stdout.on("data", (chunk) => {
+    recording.stdout += String(chunk);
+  });
+  child.stderr.on("data", (chunk) => {
+    recording.stderr += String(chunk);
+    handleRecordingStderr(recording, String(chunk));
+  });
+  child.on("error", (error) => {
+    recording.error = error;
+    recording.stderr += error.message;
+    recording.exited = true;
+  });
+  child.on("close", (exitCode) => {
+    recording.exited = true;
+    recording.exitCode = exitCode;
+    activeRecordingsByPid.delete(recording.pid);
+    rejectPendingSnapshots(recording, new Error(`capture-helper recording exited before snapshot completed (code=${exitCode ?? "unknown"})`));
+  });
+  await sleep(750);
+  if (recording.exited) {
+    console.error(
+      `WARN: capture-helper record exited before the recipe started (code=${recording.exitCode ?? "unknown"}): ${recording.stderr || recording.stdout}`
+    );
+    return void 0;
+  }
+  activeRecordingsByPid.set(pid, recording);
+  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${outputPath}`);
+  return recording;
+}
+async function captureActiveRecipeRecordingSnapshot(pid, outputPath, timeoutMs = 3e4) {
+  const recording = activeRecordingsByPid.get(pid);
+  if (!recording || recording.exited) return void 0;
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.rmSync(outputPath, { force: true });
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      recording.pendingSnapshots.delete(outputPath);
+      reject(new Error(`capture-helper record session snapshot timed out after ${timeoutMs}ms: ${outputPath}`));
+    }, timeoutMs);
+    recording.pendingSnapshots.set(outputPath, { outputPath, timer, resolve, reject });
+    recording.child.stdin.write(`snapshot ${outputPath}
+`, (error) => {
+      if (!error) return;
+      clearTimeout(timer);
+      recording.pendingSnapshots.delete(outputPath);
+      reject(error);
+    });
+  });
+}
+async function stopRecipeRecording(recording, result) {
+  if (!recording) return;
+  if (!recording.exited) {
+    recording.child.stdin.end("stop\n");
+    await waitForRecordingExit(recording, 15e3);
+  }
+  if (!recording.exited) {
+    recording.child.kill("SIGINT");
+    await waitForRecordingExit(recording, 5e3);
+  }
+  if (!recording.exited) {
+    recording.child.kill("SIGTERM");
+    await waitForRecordingExit(recording, 3e3);
+  }
+  const validation = validateRecordingArtifact(recording);
+  if (validation.ok === false) {
+    try {
+      fs.rmSync(recording.outputPath, { force: true });
+    } catch (error) {
+      console.error(
+        `WARN: could not remove unusable capture-helper video ${recording.outputPath}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    console.error(
+      `WARN: capture-helper recording did not produce a usable video artifact: ${validation.reason}`
+    );
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    return;
+  }
+  if (result) addRecordingArtifactToManifest(result, recording);
+}
+async function waitForRecordingExit(recording, timeoutMs) {
+  if (recording.exited) return;
+  await new Promise((resolve) => {
+    const timer = setTimeout(resolve, timeoutMs);
+    recording.child.once("close", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+function handleRecordingStderr(recording, chunk) {
+  recording.stderrBuffer += chunk;
+  let newlineIndex = recording.stderrBuffer.indexOf("\n");
+  while (newlineIndex !== -1) {
+    const line = recording.stderrBuffer.slice(0, newlineIndex).trim();
+    recording.stderrBuffer = recording.stderrBuffer.slice(newlineIndex + 1);
+    if (line) handleRecordingEventLine(recording, line);
+    newlineIndex = recording.stderrBuffer.indexOf("\n");
+  }
+}
+function handleRecordingEventLine(recording, line) {
+  let event;
+  try {
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+    event = parsed;
+  } catch {
+    return;
+  }
+  const output = typeof event.output === "string" ? event.output : void 0;
+  if (!output) return;
+  const pending = recording.pendingSnapshots.get(output);
+  if (!pending) return;
+  if (event.type === "snapshot") {
+    clearTimeout(pending.timer);
+    recording.pendingSnapshots.delete(output);
+    pending.resolve(event);
+    return;
+  }
+  if (event.type === "error") {
+    clearTimeout(pending.timer);
+    recording.pendingSnapshots.delete(output);
+    pending.reject(new Error(String(event.message ?? `capture-helper snapshot failed: ${output}`)));
+  }
+}
+function rejectPendingSnapshots(recording, error) {
+  for (const pending of recording.pendingSnapshots.values()) {
+    clearTimeout(pending.timer);
+    pending.reject(error);
+  }
+  recording.pendingSnapshots.clear();
+}
+function validateRecordingArtifact(recording) {
+  if (!fs.existsSync(recording.outputPath)) {
+    return { ok: false, reason: `missing output ${recording.outputPath}` };
+  }
+  const size = fs.statSync(recording.outputPath).size;
+  if (size === 0) {
+    return { ok: false, reason: `empty output ${recording.outputPath}` };
+  }
+  const recorderOutput = `${recording.stdout}
+${recording.stderr}`;
+  if (!recorderOutput.includes("record_complete")) {
+    return {
+      ok: false,
+      reason: `capture-helper did not report record_complete for ${recording.outputPath}: ${recorderOutput.trim() || "no recorder output"}`
+    };
+  }
+  const ffprobe = spawnSync(
+    "ffprobe",
+    ["-hide_banner", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", recording.outputPath],
+    { encoding: "utf8" }
+  );
+  if (ffprobe.error && ffprobe.error.code === "ENOENT") {
+    return { ok: true };
+  }
+  if (ffprobe.error) {
+    return { ok: false, reason: `ffprobe failed for ${recording.outputPath}: ${ffprobe.error.message}` };
+  }
+  if (ffprobe.status !== 0) {
+    return {
+      ok: false,
+      reason: `invalid MP4 ${recording.outputPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`
+    };
+  }
+  const durationSeconds = Number(ffprobe.stdout.trim());
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    return { ok: false, reason: `MP4 has no positive duration: ${recording.outputPath}` };
+  }
+  return { ok: true };
+}
+function addRecordingArtifactToManifest(result, recording) {
+  const manifestPath = result.artifactManifestPath;
+  if (!manifestPath || !fs.existsSync(manifestPath)) {
+    console.error(`WARN: cannot add video artifact to missing artifact manifest: ${manifestPath ?? "<unset>"}`);
+    return;
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (!Array.isArray(manifest.artifacts)) manifest.artifacts = [];
+  manifest.artifacts = manifest.artifacts.filter((artifact) => artifact.path !== recording.relativePath);
+  manifest.artifacts.push({
+    path: recording.relativePath,
+    type: "video",
+    label: "Full recipe replay video",
+    category: "evidence",
+    mimeType: "video/mp4",
+    record: "full_run",
+    metadata: {
+      provider: "capture-helper",
+      mode: "full_run",
+      pid: recording.pid
+    }
+  });
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+}
+function removeRecordingArtifactFromManifest(result, relativePath) {
+  const manifestPath = result.artifactManifestPath;
+  if (!manifestPath || !fs.existsSync(manifestPath)) return;
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (!Array.isArray(manifest.artifacts)) return;
+  const nextArtifacts = manifest.artifacts.filter((artifact) => artifact.path !== relativePath);
+  if (nextArtifacts.length === manifest.artifacts.length) return;
+  manifest.artifacts = nextArtifacts;
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+}
+function captureHelperPath() {
+  return process.env.CAPTURE_HELPER_PATH || "capture-helper";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  captureActiveRecipeRecordingSnapshot,
+  startRecipeRecording,
+  stopRecipeRecording
+};