@deeeed/metamask-harness 0.5.1 → 0.6.0

package/dist/commands/parse-args.js

@@ -0,0 +1,189 @@
+import path from "node:path";
+import { detectAdapter } from "../harness.js";
+import { assertAdapter, manifestPath } from "../paths.js";
+import { ADAPTER_DETECT_NEXT } from "./shared.js";
+import { EXIT } from "./shared.js";
+class CliError extends Error {
+  exitCode;
+  constructor(message, exitCode) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}
+function usageError(message) {
+  return new CliError(message, EXIT.usage);
+}
+function parseArgs(argv, command) {
+  const positional = [];
+  const options = {};
+  const booleanOptions = /* @__PURE__ */ new Set([
+    "json",
+    "launchExistingDist",
+    "startWatch",
+    "record",
+    "plan",
+    "raw",
+    "fix",
+    "force",
+    "resolveOnly",
+    "help"
+  ]);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const body = arg.slice(2);
+    const equalsIndex = body.indexOf("=");
+    const rawKey = equalsIndex === -1 ? body : body.slice(0, equalsIndex);
+    const inlineValue = equalsIndex === -1 ? void 0 : body.slice(equalsIndex + 1);
+    const key = normalizeOptionKey(rawKey);
+    if (key === "recordVideo") {
+      options.recordVideo = parseRecordVideoMode(inlineValue);
+      continue;
+    }
+    if (key === "recordBaseline") {
+      options.record = true;
+      continue;
+    }
+    if (key === "record") {
+      if (command === "runtime-decision") {
+        options.record = true;
+        continue;
+      }
+      options.recordVideo = "full-run";
+      continue;
+    }
+    if (booleanOptions.has(key)) {
+      options[key] = true;
+      continue;
+    }
+    if (inlineValue !== void 0) {
+      options[key] = inlineValue;
+      continue;
+    }
+    if (i + 1 >= argv.length) throw usageError(`Missing value for ${arg}`);
+    options[key] = argv[i + 1];
+    i += 1;
+  }
+  return { positional, options, rawArgv: [...argv] };
+}
+function parseRecordVideoMode(value) {
+  if (value === void 0 || value === "" || value === "true") return "full-run";
+  if (value === "off" || value === "false") return false;
+  if (value === "proof-window" || value === "proof_window") {
+    throw usageError(
+      "--record-video=proof-window is not supported yet; use --record-video=full-run."
+    );
+  }
+  if (value !== "full-run") {
+    throw usageError("--record-video must be full-run or off.");
+  }
+  return "full-run";
+}
+function normalizeOptionKey(key) {
+  return key.replace(/-([a-z])/gu, (_, character) => character.toUpperCase());
+}
+function optionString(options, key) {
+  const value = options[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") throw usageError(`--${key} requires a value.`);
+  return value;
+}
+function optionFlag(options, key) {
+  const value = options[key];
+  return value === true;
+}
+function applyRuntimeDirOption(options) {
+  const runtimeDir = optionString(options, "runtimeDir");
+  if (runtimeDir) process.env.RECIPE_RUNTIME_DIR = runtimeDir;
+}
+function applyWatcherPortOption(options) {
+  const watcherPort = optionString(options, "watcherPort");
+  if (!watcherPort) return;
+  process.env.WATCHER_PORT = watcherPort;
+  process.env.RECIPE_WATCHER_PORT = watcherPort;
+  process.env.METRO_PORT = watcherPort;
+}
+function requiredOption(options, key, message) {
+  const value = optionString(options, key);
+  if (!value) throw usageError(message);
+  return value;
+}
+function adapterOption(options) {
+  const adapter = optionString(options, "adapter");
+  try {
+    assertAdapter(adapter);
+  } catch (error) {
+    throw usageError(error instanceof Error ? error.message : String(error));
+  }
+  return adapter;
+}
+function targetPath(options) {
+  return path.resolve(optionString(options, "target") ?? optionString(options, "projectRoot") ?? process.cwd());
+}
+function actionManifestPathOption(options, adapter) {
+  const configured = optionString(options, "actionManifest");
+  return configured ? path.resolve(configured) : manifestPath(adapter);
+}
+function parsePort(value, errorMessage) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0) throw usageError(errorMessage);
+  return port;
+}
+function runtimeOptionsFromCli(options) {
+  const recordVideo = options.recordVideo;
+  return {
+    cdpPort: optionString(options, "cdpPort"),
+    watcherPort: optionString(options, "watcherPort") ?? optionString(options, "metroPort"),
+    launchExistingDist: optionFlag(options, "launchExistingDist"),
+    slot: optionString(options, "slot"),
+    validationRuntimeDir: optionString(options, "validationRuntimeDir"),
+    recordVideo: recordVideo === "full-run" ? "full-run" : false
+  };
+}
+function resolveAdapter(options) {
+  const target = targetPath(options);
+  const explicit = optionString(options, "adapter") ?? optionString(options, "platform");
+  const adapter = explicit ?? detectAdapter(target);
+  if (!adapter) {
+    throw usageError(`could not detect the MetaMask repo type for ${target}
+  Next: ${ADAPTER_DETECT_NEXT}`);
+  }
+  try {
+    assertAdapter(adapter);
+  } catch (error) {
+    throw usageError(error instanceof Error ? error.message : String(error));
+  }
+  return { adapter, target };
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function shellQuoteArg(value) {
+  return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : shellQuote(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export {
+  CliError,
+  actionManifestPathOption,
+  adapterOption,
+  applyRuntimeDirOption,
+  applyWatcherPortOption,
+  isRecord,
+  optionFlag,
+  optionString,
+  parseArgs,
+  parsePort,
+  requiredOption,
+  resolveAdapter,
+  runtimeOptionsFromCli,
+  shellQuote,
+  shellQuoteArg,
+  targetPath,
+  usageError
+};

package/dist/commands/provision.js

@@ -0,0 +1,136 @@
+import { detectAdapter } from "../harness.js";
+import { assertAdapter } from "../paths.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import { ADAPTER_DETECT_NEXT, usageOut } from "./shared.js";
+import {
+  applyWatcherPortOption,
+  optionFlag,
+  optionString,
+  shellQuote,
+  shellQuoteArg,
+  targetPath
+} from "./parse-args.js";
+async function handleProvision({ positional, options, rawArgv }) {
+  applyWatcherPortOption(options);
+  const json = optionFlag(options, "json");
+  const target = targetPath(options);
+  const adapter = optionString(options, "adapter") ?? detectAdapter(target);
+  if (!adapter) {
+    return usageOut(json, "provision", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  try {
+    assertAdapter(adapter);
+  } catch (error) {
+    return usageOut(json, "provision", error instanceof Error ? error.message : String(error), ADAPTER_DETECT_NEXT);
+  }
+  const surface = getAdapterSurface(adapter);
+  const rerunCommand = provisionRerunCommand(rawArgv, options, adapter, target);
+  const result = await surface.runwayProvision.run(target, {
+    json,
+    platform: optionString(options, "platform") ?? optionString(options, "devicePlatform") ?? (positional[0] === "runway" ? positional[1] : positional[0]) ?? "ios",
+    branch: optionString(options, "branch"),
+    defaultBranch: optionString(options, "defaultBranch"),
+    run: optionString(options, "run"),
+    cacheRoot: optionString(options, "cacheRoot"),
+    simulator: optionString(options, "simulator") ?? optionString(options, "device"),
+    runtime: optionString(options, "runtime"),
+    deviceType: optionString(options, "deviceType"),
+    slot: optionString(options, "slot"),
+    watcherPort: optionString(options, "watcherPort"),
+    runtimeDir: optionString(options, "runtimeDir"),
+    force: optionFlag(options, "force"),
+    resolveOnly: optionFlag(options, "resolveOnly"),
+    rerunCommand
+  });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.status === "pass") {
+    const cache = typeof result.cache === "object" && result.cache ? result.cache : void 0;
+    const simulator = typeof result.simulator === "object" && result.simulator ? result.simulator : void 0;
+    const artifact = typeof result.artifact === "object" && result.artifact ? result.artifact : void 0;
+    if (result.resolveOnly) {
+      console.error(`\u2713 resolved ${adapter} ${result.platform ?? ""} run=${artifact?.runId ?? "unknown"} revision=${artifact?.revision ?? "unknown"} artifact=${artifact?.artifactName ?? "unknown"}`);
+    } else {
+      const action = result.skipped ? "already provisioned" : "provisioned";
+      console.error(`\u2713 ${action} ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "unknown"}`);
+    }
+  } else {
+    console.error(`\u2717 mm-harness provision: ${result.error?.message ?? "provision failed"}
+  Next: ${result.error?.userAction ?? rerunCommand}`);
+  }
+  return result.exitCode;
+}
+function provisionRerunCommand(rawArgv, options, adapter, target) {
+  const parts = ["mm-harness", "provision"];
+  for (const positional of provisionPositionals(rawArgv)) parts.push(shellQuoteArg(positional));
+  parts.push("--adapter", adapter, "--target", shellQuote(target));
+  const aliases = [
+    ["platform", ["--platform", "--device-platform"]],
+    ["branch", ["--branch"]],
+    ["defaultBranch", ["--default-branch"]],
+    ["run", ["--run"]],
+    ["cacheRoot", ["--cache-root"]],
+    ["simulator", ["--simulator", "--device"]],
+    ["runtime", ["--runtime"]],
+    ["deviceType", ["--device-type"]],
+    ["slot", ["--slot"]],
+    ["watcherPort", ["--watcher-port"]],
+    ["runtimeDir", ["--runtime-dir"]]
+  ];
+  for (const [key, flags] of aliases) {
+    const found = findRawOption(rawArgv, flags);
+    const value = found?.value ?? optionString(options, key);
+    if (value) parts.push(found?.flag ?? flags[0], shellQuoteArg(value));
+  }
+  if (optionFlag(options, "force")) parts.push("--force");
+  if (optionFlag(options, "resolveOnly")) parts.push("--resolve-only");
+  if (optionFlag(options, "json")) parts.push("--json");
+  return parts.join(" ");
+}
+function provisionPositionals(rawArgv) {
+  const positionals = [];
+  const valueFlags = /* @__PURE__ */ new Set([
+    "--adapter",
+    "--target",
+    "--project-root",
+    "--platform",
+    "--device-platform",
+    "--branch",
+    "--default-branch",
+    "--run",
+    "--cache-root",
+    "--simulator",
+    "--device",
+    "--runtime",
+    "--device-type",
+    "--slot",
+    "--watcher-port",
+    "--runtime-dir"
+  ]);
+  for (let i = 0; i < rawArgv.length; i += 1) {
+    const arg = rawArgv[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const key = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    if (!arg.includes("=") && valueFlags.has(key)) i += 1;
+  }
+  return positionals;
+}
+function findRawOption(rawArgv, flags) {
+  for (let i = 0; i < rawArgv.length; i += 1) {
+    const arg = rawArgv[i];
+    for (const flag of flags) {
+      if (arg === flag) {
+        const value = rawArgv[i + 1];
+        return value && !value.startsWith("--") ? { flag, value } : void 0;
+      }
+      if (arg.startsWith(`${flag}=`)) return { flag, value: arg.slice(flag.length + 1) };
+    }
+  }
+  return void 0;
+}
+export {
+  handleProvision
+};

package/dist/commands/resolve-extension.js

@@ -0,0 +1,23 @@
+import { resolveExtensionId } from "../adapters/extension/extension-id.js";
+import {
+  adapterOption,
+  optionFlag,
+  optionString,
+  parsePort,
+  targetPath
+} from "./parse-args.js";
+async function handleResolveExtension({ options }) {
+  const adapter = adapterOption(options);
+  if (adapter !== "extension") throw new Error("resolve-extension currently applies to the extension adapter.");
+  const target = targetPath(options);
+  const cdpPortRaw = optionString(options, "cdpPort") ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  const cdpPort = cdpPortRaw === void 0 ? void 0 : parsePort(cdpPortRaw, "resolve-extension --cdp-port must be a port.");
+  const result = await resolveExtensionId(target, { cdpPort });
+  if (optionFlag(options, "json")) console.log(JSON.stringify(result, null, 2));
+  else if (result.extensionId) console.log(result.extensionId);
+  else console.error("Could not resolve a MetaMask extension id (no dist key and no single CDP extension).");
+  return result.extensionId ? 0 : 1;
+}
+export {
+  handleResolveExtension
+};

package/dist/commands/run-engine.js

@@ -0,0 +1,341 @@
+import fs from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import {
+  ensureOverlay,
+  newHealState,
+  parseHeal,
+  recipeRunning,
+  checkHealBounds
+} from "../heal-bounds.js";
+import { loadActionManifest, validateManifest } from "../manifest.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import {
+  importRecipeHarness,
+  importRecipeProtocol,
+  runnerDir
+} from "../paths.js";
+import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
+import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
+import { EXIT } from "./shared.js";
+import {
+  actionManifestPathOption,
+  optionString,
+  isRecord,
+  usageError
+} from "./parse-args.js";
+async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}) {
+  const previousCdpPort = process.env.CDP_PORT;
+  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+  const previousWatcherPort = process.env.WATCHER_PORT;
+  const previousMetroPort = process.env.METRO_PORT;
+  const previousExtensionAutolaunch = process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH;
+  getAdapterSurface(adapter).resolveSlotPorts(projectRoot);
+  if (runtimeOptions.cdpPort) {
+    process.env.CDP_PORT = runtimeOptions.cdpPort;
+    process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
+  }
+  if (runtimeOptions.watcherPort) {
+    process.env.WATCHER_PORT = runtimeOptions.watcherPort;
+    process.env.METRO_PORT = runtimeOptions.watcherPort;
+  }
+  if (runtimeOptions.launchExistingDist) {
+    process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH = "1";
+  }
+  try {
+    await prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions);
+    const absoluteArtifactsDir = path.resolve(artifactsDir);
+    const recordVideo = runtimeOptions.recordVideo ?? false;
+    const useFramedExtensionRecording = adapter === "extension" && recordVideo === "full-run" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
+    const recording = useFramedExtensionRecording ? await startRecipeRecording(adapter, projectRoot, absoluteArtifactsDir, {
+      record: true,
+      cdpPort: runtimeOptions.cdpPort
+    }) : void 0;
+    try {
+      const manifest = loadActionManifest(adapter, actionManifestPath);
+      await validateManifest(manifest);
+      const { createMetaMaskRunner } = await import("../runner.js");
+      const runner = await createMetaMaskRunner(adapter, manifest, {
+        quietStdout: runtimeOptions.stdoutIsMachineContract === true
+      });
+      const runRequest = {
+        recipePath: path.resolve(recipe),
+        artifactsDir: absoluteArtifactsDir,
+        projectRoot,
+        env: recipeRunEnv(adapter, runtimeOptions),
+        recordVideo: useFramedExtensionRecording ? false : recordVideo,
+        ...runtimeOptions.librarySources ? { librarySources: runtimeOptions.librarySources } : {}
+      };
+      const result = await runner.run(runRequest);
+      await stopRecipeRecording(recording, result);
+      return result;
+    } finally {
+      await stopRecipeRecording(recording);
+    }
+  } finally {
+    restoreEnv("CDP_PORT", previousCdpPort);
+    restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
+    restoreEnv("WATCHER_PORT", previousWatcherPort);
+    restoreEnv("METRO_PORT", previousMetroPort);
+    restoreEnv("METAMASK_RECIPE_EXTENSION_AUTOLAUNCH", previousExtensionAutolaunch);
+  }
+}
+function recipeRunEnv(adapter, runtimeOptions = {}) {
+  const base = {
+    CDP_PORT: runtimeOptions.cdpPort ?? process.env.CDP_PORT,
+    RECIPE_CDP_PORT: runtimeOptions.cdpPort ?? process.env.RECIPE_CDP_PORT,
+    FARMSLOT_SLOT_ID: runtimeOptions.slot ?? process.env.FARMSLOT_SLOT_ID,
+    SLOT_ID: runtimeOptions.slot ?? process.env.SLOT_ID,
+    PLATFORM: process.env.PLATFORM
+  };
+  if (adapter !== "mobile") return base;
+  return {
+    ...base,
+    WATCHER_PORT: process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
+    METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? base.CDP_PORT ?? base.RECIPE_CDP_PORT,
+    IOS_SIMULATOR: process.env.IOS_SIMULATOR,
+    ANDROID_DEVICE: process.env.ANDROID_DEVICE,
+    ADB_SERIAL: process.env.ADB_SERIAL,
+    ANDROID_SERIAL: process.env.ANDROID_SERIAL
+  };
+}
+async function prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions) {
+  if (adapter !== "extension" || runtimeOptions.skipExtensionRuntimePrepare === true) return;
+  const { prepareExtensionRuntime } = await import("../adapters/extension/runtime.js");
+  await prepareExtensionRuntime({
+    projectRoot,
+    cdpPort: runtimeOptions.cdpPort,
+    slot: runtimeOptions.slot,
+    launchExistingDist: runtimeOptions.launchExistingDist === true,
+    validationRuntimeDir: runtimeOptions.validationRuntimeDir
+  });
+}
+function restoreEnv(key, value) {
+  if (value === void 0) delete process.env[key];
+  else process.env[key] = value;
+}
+async function validateRecipeAdapterAware(recipe, manifest, librarySources) {
+  const { validateRecipeDocument, validateRecipeWithManifest } = await importRecipeProtocol();
+  let externalFlowIds;
+  if (librarySources && librarySources.length > 0) {
+    const harness = await importRecipeHarness();
+    const resolution = await harness.loadRecipeLibraries(librarySources);
+    externalFlowIds = new Set(resolution.flows.keys());
+  }
+  const validationOptions = externalFlowIds !== void 0 ? { externalFlowIds } : void 0;
+  const schema = validateRecipeDocument(recipe, validationOptions);
+  const withManifest = validateRecipeWithManifest(recipe, manifest, validationOptions);
+  const findings = [...schema.findings, ...withManifest.findings];
+  const errors = findings.filter((finding) => finding.severity === "error").length;
+  const warnings = findings.length - errors;
+  return { status: errors > 0 ? "invalid" : "valid", findings, summary: { errors, warnings } };
+}
+async function validateRunRecipeStatic(recipeArg, adapter, options) {
+  const recipeFile = path.resolve(recipeArg);
+  const empty = { recipe: void 0, recipeFile, findings: [], errorCount: 0, manifestOk: false, schemaValid: false };
+  if (!fs.existsSync(recipeFile)) {
+    return { ...empty, usageError: { code: "RECIPE_NOT_FOUND", message: `recipe not found: ${recipeFile}` } };
+  }
+  let recipe;
+  try {
+    recipe = JSON.parse(fs.readFileSync(recipeFile, "utf8"));
+  } catch (error) {
+    return {
+      ...empty,
+      usageError: {
+        code: "RECIPE_UNPARSEABLE",
+        message: `recipe is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+      }
+    };
+  }
+  const findings = [];
+  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  let manifestOk = true;
+  try {
+    await validateManifest(manifest);
+  } catch (error) {
+    manifestOk = false;
+    findings.push({
+      severity: "error",
+      code: "manifest.invalid",
+      path: actionManifestPathOption(options, adapter),
+      message: error instanceof Error ? error.message : String(error)
+    });
+  }
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const validation = manifestOk ? await validateRecipeAdapterAware(recipe, manifest, librarySources) : { status: "invalid", findings: [], summary: { errors: 1, warnings: 0 } };
+  findings.push(...validation.findings);
+  const errorCount = findings.filter((finding) => finding.severity === "error").length;
+  return { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid: validation.status === "valid" };
+}
+async function resolveMetaMaskLibrarySources(libraryEntry) {
+  const harness = await importRecipeHarness();
+  if (typeof harness.resolveRecipeLibrarySources !== "function") {
+    if (libraryEntry) {
+      throw usageError(
+        "--library requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support / resolveRecipeLibrarySources). The pinned 0.3.0 lacks it, and npm 0.3.2 still does not export it \u2014 recipe-library support is PENDING PUBLISH from farmslot."
+      );
+    }
+    return void 0;
+  }
+  const sources = await harness.resolveRecipeLibrarySources(
+    libraryEntry ? { cliEntries: [libraryEntry] } : void 0
+  );
+  sources.push({ name: "metamask", root: path.join(runnerDir, "library") });
+  return sources;
+}
+function synthesizeOneNodeRecipe(action, args) {
+  return {
+    schema_version: 1,
+    title: `mm-harness call ${action}`,
+    description: `Ad-hoc single-action execution of ${action} via the real engine path (mm-harness call).`,
+    validate: {
+      workflow: {
+        entry: "call",
+        nodes: {
+          call: { action, ...args, next: "done", intent: `Call ${action} in isolation` },
+          done: { action: "end", status: "pass" }
+        }
+      }
+    }
+  };
+}
+async function runOneNode(adapter, action, args, target, actionManifest) {
+  const manifest = loadActionManifest(adapter, actionManifest);
+  const recipe = synthesizeOneNodeRecipe(action, args);
+  const validation = await validateRecipeAdapterAware(recipe, manifest);
+  if (validation.status === "invalid") return { status: "fail" };
+  const scratch = await mkdtemp(path.join(os.tmpdir(), "mm-harness-fixtures-"));
+  const recipeFile = path.join(scratch, "set.recipe.json");
+  fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}
+`);
+  const result = await runRecipe(adapter, recipeFile, path.join(scratch, "artifacts"), target, actionManifest, {
+    librarySources: await resolveMetaMaskLibrarySources(void 0)
+  });
+  return { status: result.status === "pass" ? "pass" : "fail" };
+}
+async function prepareHeal(adapter, target, options, json) {
+  if (recipeRunning(target)) {
+    const msg = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness: ${msg}`);
+    }
+    return EXIT.bounded;
+  }
+  const healValue = optionString(options, "heal");
+  const healOpts = {};
+  if (healValue !== void 0) healOpts.heal = healValue;
+  const heal = parseHeal(healOpts, "infra-only");
+  if (typeof heal !== "string") {
+    console.error(heal.error);
+    return EXIT.usage;
+  }
+  const state = newHealState();
+  const ensured = await ensureOverlay(adapter, target, heal, state, json);
+  if (!ensured.ok) {
+    if (json) {
+      console.log(
+        JSON.stringify(
+          { schemaVersion: 1, status: "fail", recoverable: false, mutations: state.mutations, error: { code: "OVERLAY_INSTALL_FAILED", message: ensured.error } },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`\u2717 overlay auto-ensure failed: ${ensured.error}`);
+    }
+    return EXIT.infra;
+  }
+  return { state, heal };
+}
+const RUN_RECOVERY_CODE = {
+  mobile: "metro.restarted",
+  extension: "chrome.reopened",
+  core: "runtime.reset"
+};
+function readRunFailureText(result) {
+  try {
+    const trace = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
+    const entries = Array.isArray(trace.entries) ? trace.entries : [];
+    return entries.filter((entry) => entry && entry.ok === false && typeof entry.error === "string").map((entry) => entry.error).join("\n").trim();
+  } catch {
+    return "";
+  }
+}
+async function executeWithHealBounds(exec, adapter, target, heal, state) {
+  let result = await exec();
+  for (; ; ) {
+    if (result.status === "pass") return { result, violation: null };
+    const violation = checkHealBounds(target, readRunFailureText(result), state);
+    if (violation !== null) return { result, violation };
+    if (heal === "off") return { result, violation: null };
+    const recoveryCode = RUN_RECOVERY_CODE[adapter];
+    state.attemptedRecoveries.push(recoveryCode);
+    result = await exec();
+    if (result.status === "pass") {
+      state.recovered.push(recoveryCode);
+      return { result, violation: null };
+    }
+  }
+}
+function emitHealViolation(json, command, result, violation, state, adapter) {
+  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? 'set MM_TEST_ACCOUNT_ADDRESS=<0x\u2026> in env, or add "account": "<0x\u2026>" to the node block in the recipe' : violation.userAction;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command,
+          status: "fail",
+          recoverable: false,
+          recovered: state.recovered,
+          mutations: state.mutations,
+          attemptedRecoveries: state.attemptedRecoveries,
+          summaryPath: result.summaryPath,
+          tracePath: result.tracePath,
+          artifactManifestPath: result.artifactManifestPath,
+          exitCode: violation.exitCode,
+          error: {
+            code: violation.code,
+            message: violation.message,
+            retryable: false,
+            userAction: userAction ?? null,
+            originalError: violation.originalError ?? null
+          }
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(
+      `\u2717 mm-harness ${command}: ${violation.message}` + (violation.originalError ? `
+  --- original failure ---
+${violation.originalError}` : "") + (userAction ? `
+  Next: ${userAction}` : "")
+    );
+  }
+  return violation.exitCode;
+}
+function countRecipeNodes(recipe) {
+  if (!isRecord(recipe)) return void 0;
+  const validate = isRecord(recipe.validate) ? recipe.validate : void 0;
+  const workflow = validate && isRecord(validate.workflow) ? validate.workflow : void 0;
+  const nodes = workflow && isRecord(workflow.nodes) ? workflow.nodes : void 0;
+  return nodes ? Object.keys(nodes).length : void 0;
+}
+export {
+  countRecipeNodes,
+  emitHealViolation,
+  executeWithHealBounds,
+  prepareHeal,
+  resolveMetaMaskLibrarySources,
+  runOneNode,
+  runRecipe,
+  synthesizeOneNodeRecipe,
+  validateRecipeAdapterAware,
+  validateRunRecipeStatic
+};