@deeeed/metamask-harness 0.3.9 → 0.5.0

package/dist/cli.js

@@ -0,0 +1,1571 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { mkdtemp } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { color } from "./cli-color.js";
+import { createDoctorReport, renderRuntimeContext } from "./doctor.js";
+import {
+  invalidateCompletionCache,
+  readFreshCandidates,
+  writeCompletionCandidates
+} from "./completions-cache.js";
+import { detectAdapter, handleHarness } from "./harness.js";
+import { handleLaunch } from "./commands/launch.js";
+import { handleLogs } from "./commands/logs.js";
+import { handleDebug } from "./commands/debug.js";
+import { handleFixtures } from "./commands/fixtures.js";
+import {
+  ensureOverlay,
+  newHealState,
+  parseHeal,
+  recipeRunning,
+  checkHealBounds
+} from "./heal-bounds.js";
+import { ensureExtensionReady } from "./adapters/extension/ensure-ready.js";
+import { resolveExtensionId } from "./adapters/extension/extension-id.js";
+import { decideExtensionReadiness } from "./adapters/extension/runtime-decision.js";
+import { decideMobileReadiness } from "./adapters/mobile/runtime-decision.js";
+import { getAdapterSurface } from "./adapters/surface.js";
+import { loadActionManifest, validateManifest } from "./manifest.js";
+import {
+  assertAdapter,
+  importRecipeHarness,
+  importRecipeHarnessCli,
+  importRecipeProtocol,
+  manifestPath,
+  recipeHarnessPath,
+  recipePath,
+  runnerDir,
+  walletFixturePath
+} from "./paths.js";
+import { captureHelperSupportsRecordSessionSnapshots } from "./recording-target.js";
+import { startRecipeRecording, stopRecipeRecording } from "./run-recording.js";
+import { ADAPTER_DETECT_NEXT, usageOut } from "./commands/shared.js";
+const COMMANDS = {
+  manifest: handleManifest,
+  actions: handleActions,
+  doctor: handleDoctor,
+  "runtime-health": handleRuntimeHealth,
+  "runtime-decision": handleRuntimeDecision,
+  "runtime-launch": handleRuntimeLaunch,
+  provision: handleProvision,
+  "resolve-extension": handleResolveExtension,
+  "ensure-ready": handleEnsureReady,
+  run: handleRun,
+  "self-test": handleSelfTest
+};
+const OVERLAY_COMMANDS = ["install", "provision", "verify", "cleanup", "live"];
+function usage() {
+  console.error(`mm-harness \u2014 the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay.
+Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.
+Grammar: mm-harness <command> [target] [flags]   (target is a positional: ios | android | extension; flags add agent depth)
+
+DAILY LOOP \u2014 what a teammate runs many times a day:
+  launch     Launch the app incl. Metro/build, surface auto-detected. Mobile: ios|android required.
+               mm-harness launch ios                    # quick relaunch (add --build | --verify)
+  logs       Tail Metro/webpack + app logs.
+               mm-harness logs
+  debug      Open the debug console (extension DevTools / mobile RN).
+               mm-harness debug
+  fixtures   Sync fixture files + set up the wallet (SRP/password).
+               mm-harness fixtures sync                 # or: mm-harness fixtures set
+
+PROVE \u2014 run recipes and inspect capabilities:
+  run        Run a recipe and write evidence (summary/trace/artifacts).
+               mm-harness run recipe.json
+  flows      List/promote recipe library flows (personal/team win over canonical).
+               mm-harness flows list
+  doctor     Readiness check for a checkout (no app launch).
+               mm-harness doctor
+  actions    Describe the actions a manifest declares.
+               mm-harness actions --adapter mobile
+  manifest   Print/validate the action manifest for an adapter.
+               mm-harness manifest --adapter extension --json
+
+RUNTIME OVERLAY \u2014 install/verify/clean the per-checkout runtime overlay:
+  install    Install the runtime overlay into the checkout.
+               mm-harness install                      # inside a checkout, auto-detected
+  verify     Check the overlay/runtime is present and healthy (no launch).
+               mm-harness verify
+  live       Launch/reuse the app, then verify live control end-to-end.
+               mm-harness live
+  cleanup    Remove the installed overlay and restore the checkout.
+               mm-harness cleanup
+  # Open sub-question (Arthur): keep these top-level (mm-harness install) or group
+  # them under an \`overlay\` command (mm-harness overlay install)? Top-level for now.
+
+ADVANCED \u2014 internal runtime probes (rarely typed by hand):
+  runtime-health     runtime-decision   runtime-launch
+  resolve-extension  ensure-ready       self-test
+  (e.g. mm-harness runtime-decision --adapter extension --target <repo> --json)
+
+ONE bin: mm-harness is the only command. No per-platform binaries \u2014 platform is
+auto-detected, the positional target forces it (mm-harness launch ios), and
+platform-specific needs are FLAGS on the same command (e.g. --sidebar, --full-build).
+Human happy path = the bare command; agents add depth via flags (--json, --target, ports).
+See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).
+`);
+}
+function parseArgs(argv, command) {
+  const positional = [];
+  const options = {};
+  const booleanOptions = /* @__PURE__ */ new Set(["json", "launchExistingDist", "startWatch", "record", "plan", "raw", "fix", "force", "resolveOnly"]);
+  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);
+}
+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;
+  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 runSelfTest(options) {
+  const root = optionString(options, "artifactsDir") ? path.resolve(requiredOption(options, "artifactsDir", "self-test artifacts dir missing.")) : await mkdtemp(path.join(os.tmpdir(), "mm-harness-runner-"));
+  const previousAutoHud = process.env.METAMASK_RECIPE_AUTO_HUD;
+  const runs = [];
+  try {
+    process.env.METAMASK_RECIPE_AUTO_HUD = "0";
+    for (const adapter of ["mobile", "extension"]) {
+      const manifest = loadActionManifest(adapter);
+      const manifestValidation = await validateManifest(manifest);
+      const smokeRecipe = recipePath(
+        adapter === "mobile" ? "smoke.mobile.recipe.json" : "smoke.extension.recipe.json"
+      );
+      const artifactsDir = path.join(root, adapter);
+      const result = await runRecipe(adapter, smokeRecipe, artifactsDir, runnerDir, void 0, {
+        skipExtensionRuntimePrepare: true
+      });
+      runs.push({ adapter, manifestValidation: manifestValidation.summary, artifactsDir, result });
+    }
+  } finally {
+    restoreEnv("METAMASK_RECIPE_AUTO_HUD", previousAutoHud);
+  }
+  return {
+    status: runs.every((run) => run.result.status === "pass") ? "pass" : "fail",
+    artifactsDir: root,
+    runs
+  };
+}
+async function handleManifest({ options }) {
+  const { adapter } = resolveAdapter(options);
+  const actionManifestPath = actionManifestPathOption(options, adapter);
+  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  await validateManifest(manifest);
+  if (optionFlag(options, "json")) console.log(JSON.stringify(manifest, null, 2));
+  else console.log(actionManifestPath);
+  return 0;
+}
+async function handleActions({ options }) {
+  const { adapter } = resolveAdapter(options);
+  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  await validateManifest(manifest);
+  const action = optionString(options, "action");
+  const actions = describeManifestActions(manifest, action);
+  if (optionFlag(options, "json")) {
+    console.log(JSON.stringify({ adapter, actions }, null, 2));
+  } else {
+    for (const entry of actions) {
+      const fields = entry.fields.length ? ` fields=${entry.fields.join(",")}` : "";
+      console.log(`${entry.name} (${entry.kind})${fields}${entry.description ? ` \u2014 ${entry.description}` : ""}`);
+    }
+  }
+  return 0;
+}
+async function handleDoctor({ options }) {
+  applyRuntimeDirOption(options);
+  const target = targetPath(options);
+  const json = optionFlag(options, "json");
+  const explicitAdapter = optionString(options, "adapter") ?? optionString(options, "platform");
+  const adapter = explicitAdapter ?? detectAdapter(target);
+  if (!adapter) {
+    return usageOut(json, "doctor", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  }
+  assertAdapter(adapter);
+  const actionManifestPath = actionManifestPathOption(options, adapter);
+  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  const manifestValidation = await validateManifest(manifest);
+  if (optionFlag(options, "fix")) {
+    const { fixed, failed } = await runDoctorFix(adapter, target, manifestValidation, json);
+    const result2 = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
+    if (json) console.log(JSON.stringify({ ...result2, fixed, failed }, null, 2));
+    else console.log(`${result2.status} ${adapter} ${result2.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
+    return failed.length === 0 ? 0 : 1;
+  }
+  const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
+  let runtime;
+  try {
+    const surface = getAdapterSurface(adapter);
+    surface.resolveSlotPorts(target);
+    runtime = await surface.runtimeStatus(target);
+  } catch {
+  }
+  if (json) console.log(JSON.stringify({ ...result, runtime }, null, 2));
+  else {
+    const out = (style, text) => color(style, text, { stream: process.stdout });
+    const stateStyle = (value, good) => value === good ? "ok" : "warn";
+    console.log(`${out(result.status === "pass" ? "ok" : "err", result.status)} ${out("bold", adapter)} ${result.compatibilityMode} ${out("dim", `manifest=${actionManifestPath}`)}`);
+    if (runtime) {
+      const provisionedDepsPending = runtime.reasonCode === "app-installed-deps-pending";
+      const decisionStyle = provisionedDepsPending ? "info" : runtime.decision === "ready" ? "ok" : runtime.decision === "blocked" ? "err" : "warn";
+      const depsStyle = provisionedDepsPending ? "info" : stateStyle(runtime.deps, "current");
+      const devServerStyle = provisionedDepsPending ? "info" : void 0;
+      const devServer = runtime.devServer ? ` ${runtime.devServer.label}=${out(devServerStyle ?? stateStyle(runtime.devServer.status, "up"), runtime.devServer.status)}` : "";
+      console.log(
+        `${out("label", "runtime:")} decision=${out(decisionStyle, runtime.decision)}${runtime.reasonCode ? ` ${out("dim", `(${runtime.reasonCode})`)}` : ""} deps=${out(depsStyle, runtime.deps ?? "unknown")}${devServer}`
+      );
+      for (const reason of runtime.reasons) console.log(`  ${out("dim", reason)}`);
+    }
+    console.log(renderRuntimeContext(result.runtimeContext));
+  }
+  return result.status === "pass" ? 0 : 1;
+}
+async function runDoctorFix(adapter, target, manifestValidation, json) {
+  const fixed = [];
+  const failed = [];
+  if (recipeRunning(target)) {
+    failed.push("recipe-running");
+    return { fixed, failed };
+  }
+  if (Number(manifestValidation.summary?.errors ?? 0) > 0) failed.push("manifest");
+  const state = newHealState();
+  const ensured = await ensureOverlay(adapter, target, "infra-only", state, json);
+  if (!ensured.ok) failed.push("overlay");
+  else if (state.mutations.length > 0) fixed.push("overlay");
+  return { fixed, failed };
+}
+function describeManifestActions(manifest, filterAction) {
+  const manifestRecord = isRecord(manifest) ? manifest : {};
+  const metadata = isRecord(manifestRecord.action_metadata) ? manifestRecord.action_metadata : {};
+  const official = Array.isArray(manifestRecord.supported_official_actions) ? manifestRecord.supported_official_actions.filter((value) => typeof value === "string") : [];
+  const custom = Array.isArray(manifestRecord.custom_actions) ? manifestRecord.custom_actions.flatMap((entry) => {
+    if (typeof entry === "string") return [{ name: entry, metadata: metadata[entry] }];
+    if (isRecord(entry) && typeof entry.name === "string") {
+      const entryMetadata = { ...entry };
+      const metadataOverride = metadata[entry.name];
+      if (isRecord(metadataOverride)) Object.assign(entryMetadata, metadataOverride);
+      return [{ name: entry.name, metadata: entryMetadata }];
+    }
+    return [];
+  }) : [];
+  const entries = [
+    ...official.map((name) => describeManifestAction(name, "official", metadata[name])),
+    ...custom.map((entry) => describeManifestAction(entry.name, "custom", entry.metadata))
+  ].filter((entry) => !filterAction || entry.name === filterAction);
+  if (filterAction && entries.length === 0) throw new Error(`Action not found in manifest: ${filterAction}`);
+  return entries;
+}
+function describeManifestAction(name, kind, metadata) {
+  const record = isRecord(metadata) ? metadata : {};
+  const schema = record.schema;
+  const schemaRecord = isRecord(schema) ? schema : {};
+  const properties = isRecord(schemaRecord.properties) ? Object.keys(schemaRecord.properties).sort() : [];
+  return {
+    name,
+    kind,
+    description: typeof record.description === "string" ? record.description : "",
+    fields: properties,
+    schema,
+    examples: record.examples
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function handleProvision({ positional, options, rawArgv }) {
+  applyWatcherPortOption(options);
+  const json = optionFlag(options, "json");
+  const { adapter, target } = resolveProvisionAdapter(options);
+  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 resolveProvisionAdapter(options) {
+  const target = targetPath(options);
+  const adapter = optionString(options, "adapter") ?? 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 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;
+}
+function shellQuoteArg(value) {
+  return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : shellQuote(value);
+}
+async function handleRuntimeHealth({ options }) {
+  const adapter = adapterOption(options);
+  if (adapter !== "extension") throw new Error("runtime-health currently applies to the extension adapter.");
+  const target = targetPath(options);
+  const cdpPort = parsePort(
+    optionString(options, "cdpPort") ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
+    "runtime-health requires --cdp-port <port>."
+  );
+  const { checkExtensionRuntimeHealth, formatHealthFailure } = await import("./adapters/extension/runtime.js");
+  const report = await checkExtensionRuntimeHealth(target, cdpPort);
+  if (optionFlag(options, "json")) console.log(JSON.stringify(report, null, 2));
+  else if (report.status === "PASS") console.log(`PASS extension runtime cdp=${cdpPort} target=${report.targetUrl}`);
+  else console.error(formatHealthFailure(report, target));
+  return report.status === "PASS" ? 0 : 1;
+}
+async function handleRuntimeLaunch({ options }) {
+  const adapter = adapterOption(options);
+  const target = targetPath(options);
+  if (adapter !== "extension") throw new Error("runtime-launch currently applies to the extension adapter.");
+  const cdpPort = parsePort(
+    optionString(options, "cdpPort") ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
+    "runtime-launch requires --cdp-port <port>."
+  );
+  const chromeUserDataDir = optionString(options, "chromeUserDataDir");
+  const artifactsDir = path.resolve(
+    optionString(options, "artifactsDir") ?? recipeHarnessPath(target, "extension", "runtime-launch", (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/gu, ""))
+  );
+  const startWatch = optionFlag(options, "startWatch");
+  const liveScript = recipeHarnessPath(target, "extension", "scripts", "live.sh");
+  const command = [
+    "bash",
+    liveScript,
+    "--target",
+    target,
+    "--cdp-port",
+    String(cdpPort),
+    startWatch ? "--start-watch" : "--launch-existing-dist",
+    "--artifacts-dir",
+    artifactsDir
+  ];
+  if (chromeUserDataDir) command.push("--chrome-user-data-dir", chromeUserDataDir);
+  const remoteFlag = optionString(options, "remoteFlag");
+  if (remoteFlag) command.push("--remote-flag", remoteFlag);
+  if (!fs.existsSync(liveScript)) {
+    const report2 = runtimeLaunchReport("fail", {
+      adapter,
+      target,
+      cdpPort,
+      artifactsDir,
+      reason: "harness_live_script_missing",
+      fix: `Run mm-harness install --adapter extension --target ${shellQuote(target)}, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir)}`,
+      command
+    });
+    printRuntimeLaunchReport(report2, optionFlag(options, "json"));
+    return 1;
+  }
+  fs.mkdirSync(artifactsDir, { recursive: true });
+  const jsonMode = optionFlag(options, "json");
+  if (!jsonMode) {
+    console.error(`recipe: runtime-launch starting (cdp=${cdpPort}${startWatch ? ", clean webpack build" : ", existing dist"})`);
+  } else {
+    console.error(JSON.stringify({
+      schemaVersion: 1,
+      type: "progress",
+      command: "rebuild",
+      phase: "runtime-launch",
+      message: startWatch ? "clean webpack build starting" : "launching existing dist",
+      cdpPort
+    }));
+  }
+  const result = spawnSync(command[0], command.slice(1), {
+    cwd: target,
+    encoding: "utf8",
+    maxBuffer: 5 * 1024 * 1024,
+    // Human launches stream webpack/rsync/verify output live; --json keeps
+    // machine-readable capture for wrappers that pipe the final report.
+    stdio: jsonMode ? ["ignore", "pipe", "pipe"] : "inherit"
+  });
+  const summaryPath = path.join(artifactsDir, "summary.json");
+  const summary = readJsonIfExists(summaryPath);
+  if (result.status === 0 && isRecord(summary) && summary.status === "pass") {
+    const report2 = runtimeLaunchReport("pass", {
+      adapter,
+      target,
+      cdpPort,
+      artifactsDir,
+      summaryPath,
+      reason: "runtime_ready",
+      fix: "",
+      command
+    });
+    printRuntimeLaunchReport(report2, optionFlag(options, "json"));
+    return 0;
+  }
+  const launchLogPath = path.join(artifactsDir, "launch", "logs", "launch.log");
+  const report = runtimeLaunchReport("fail", {
+    adapter,
+    target,
+    cdpPort,
+    artifactsDir,
+    summaryPath: fs.existsSync(summaryPath) ? summaryPath : void 0,
+    launchLogPath: fs.existsSync(launchLogPath) ? launchLogPath : void 0,
+    reason: "runtime_launch_failed",
+    fix: `Read ${fs.existsSync(launchLogPath) ? launchLogPath : summaryPath}, fix the first error, then rerun: ${runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, startWatch)}`,
+    command,
+    exitCode: result.status ?? 1
+  });
+  printRuntimeLaunchReport(report, optionFlag(options, "json"));
+  return 1;
+}
+function runtimeLaunchCommand(target, cdpPort, chromeUserDataDir, startWatch = false) {
+  const base = `mm-harness runtime-launch --adapter extension --target ${shellQuote(target)} --cdp-port ${cdpPort}`;
+  const withMode = startWatch ? `${base} --start-watch` : base;
+  return chromeUserDataDir ? `${withMode} --chrome-user-data-dir ${shellQuote(chromeUserDataDir)}` : withMode;
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function runtimeLaunchReport(status, fields) {
+  return {
+    schemaVersion: 1,
+    status,
+    ...fields
+  };
+}
+function printRuntimeLaunchReport(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  const status = String(report.status).toUpperCase();
+  console.log(`${status} runtime-launch ${report.reason}`);
+  if (report.status === "fail") console.log(`Fix: ${report.fix}`);
+  console.log(`Artifacts: ${report.artifactsDir}`);
+}
+function readJsonIfExists(file) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function handleRuntimeDecision({ options }) {
+  applyRuntimeDirOption(options);
+  const adapter = adapterOption(options);
+  const target = targetPath(options);
+  if (adapter === "mobile") {
+    const watcherPortRaw = optionString(options, "watcherPort") ?? process.env.WATCHER_PORT ?? process.env.METRO_PORT;
+    const watcherPort = watcherPortRaw === void 0 ? void 0 : parsePort(watcherPortRaw, "runtime-decision --watcher-port must be a port.");
+    const report2 = await decideMobileReadiness(target, {
+      watcherPort,
+      metroLog: optionString(options, "metroLog"),
+      platform: optionString(options, "platform") ?? process.env.PLATFORM ?? process.env.RECIPE_HARNESS_PLATFORM,
+      record: optionFlag(options, "record"),
+      preflightMode: optionString(options, "preflightMode")
+    });
+    if (optionFlag(options, "json")) console.log(JSON.stringify(report2, null, 2));
+    else console.log(`${report2.decision} ${report2.reasonCode} \u2014 ${report2.reasons[0] ?? ""}`);
+    return 0;
+  }
+  if (adapter !== "extension") {
+    const report2 = {
+      schemaVersion: 1,
+      adapter,
+      target,
+      decision: "unknown",
+      clean: false,
+      reasonCode: "adapter-unsupported",
+      reasons: [`runtime-decision applies to extension and mobile adapters, not ${adapter}.`],
+      checks: {},
+      actions: []
+    };
+    if (optionFlag(options, "json")) console.log(JSON.stringify(report2, null, 2));
+    else console.log(`unknown adapter-unsupported \u2014 ${report2.reasons[0]}`);
+    return 0;
+  }
+  const cdpPortRaw = optionString(options, "cdpPort") ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  const cdpPort = cdpPortRaw === void 0 ? void 0 : parsePort(cdpPortRaw, "runtime-decision --cdp-port must be a port.");
+  const report = await decideExtensionReadiness(target, {
+    cdpPort,
+    watchLog: optionString(options, "watchLog"),
+    record: optionFlag(options, "record")
+  });
+  if (optionFlag(options, "json")) console.log(JSON.stringify(report, null, 2));
+  else console.log(`${report.decision}${report.clean ? " (clean)" : ""} ${report.reasonCode} \u2014 ${report.reasons[0] ?? ""}`);
+  return 0;
+}
+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;
+}
+async function handleEnsureReady({ options }) {
+  const adapter = adapterOption(options);
+  if (adapter !== "extension") throw new Error("ensure-ready currently applies to the extension adapter.");
+  const target = targetPath(options);
+  const cdpPort = parsePort(
+    optionString(options, "cdpPort") ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
+    "ensure-ready requires --cdp-port <port>."
+  );
+  const result = await ensureExtensionReady(target, { cdpPort });
+  if (optionFlag(options, "json")) console.log(JSON.stringify(result, null, 2));
+  else console.log(`${result.ready ? "READY" : "NOT-READY"} ${result.reasonCode} \u2014 id=${result.extensionId} homeTabs ${result.homeTabs.before}\u2192${result.homeTabs.after} (closed ${result.homeTabs.closed})`);
+  return result.ready ? 0 : 1;
+}
+const EXIT = { ok: 0, runtime: 1, usage: 2, infra: 3, bounded: 4, validation: 5 };
+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 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 };
+}
+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 } };
+}
+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;
+}
+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 handleRunPlan(recipeArg, options) {
+  const json = optionFlag(options, "json");
+  const { adapter, target } = resolveAdapter(options);
+  const validated = await validateRunRecipeStatic(recipeArg, adapter, options);
+  if (validated.usageError) {
+    return emitPlanUsageError(json, adapter, validated.recipeFile, validated.usageError.code, validated.usageError.message);
+  }
+  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid } = validated;
+  const status = errorCount === 0 ? "pass" : "fail";
+  const nodeCount = countRecipeNodes(recipe);
+  const artifactsDir = optionString(options, "artifactsDir");
+  const plan = [
+    { step: "resolve.recipe", confidence: "static", status: "ok", detail: recipeFile },
+    { step: "resolve.adapter", confidence: "static", status: "ok", detail: adapter },
+    {
+      step: "resolve.artifactsDir",
+      confidence: "static",
+      status: "ok",
+      detail: artifactsDir ? path.resolve(artifactsDir) : "(resolved to the slot artifacts dir at run time)"
+    },
+    {
+      step: "validate.manifest",
+      confidence: "static",
+      status: manifestOk ? "ok" : "error",
+      detail: manifestOk ? "action manifest is well-formed" : "action manifest failed validation"
+    },
+    {
+      step: "validate.schema",
+      confidence: "static",
+      status: manifestOk && schemaValid ? "ok" : "error",
+      detail: "recipe document schema + action existence/platform vs the adapter manifest"
+    },
+    {
+      step: "fixture.file",
+      confidence: "static",
+      status: "ok",
+      detail: fs.existsSync(walletFixturePath(target)) ? `present: ${walletFixturePath(target)}` : `absent: ${walletFixturePath(target)} (fixtures set to seed)`
+    },
+    {
+      step: "overlay.ensure",
+      confidence: "conditional",
+      status: "planned",
+      detail: "would auto-ensure the runtime overlay if missing (install phase)"
+    },
+    ...adapter === "core" ? [] : [
+      {
+        step: "launch.app",
+        confidence: "conditional",
+        status: "planned",
+        detail: "would launch/attach the app + heal transport (Metro/Chrome/CDP) before executing"
+      }
+    ],
+    {
+      step: "execute.nodes",
+      confidence: "conditional",
+      status: "planned",
+      detail: nodeCount === void 0 ? "would execute the recipe nodes" : `would execute ${nodeCount} recipe node(s)`
+    }
+  ];
+  if (json) {
+    const payload = { schemaVersion: 1, command: "run", mode: "plan", status, adapter, recipe: recipeFile, findings, plan };
+    if (status === "fail") payload.error = { code: "RECIPE_VALIDATION_FAILED", message: `recipe validation found ${errorCount} error(s)` };
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`plan ${status} \u2014 ${adapter} \u2014 ${recipeFile}`);
+    for (const item of plan) {
+      const mark = item.status === "error" ? "\u2717" : item.status === "ok" ? "\u2713" : "\xB7";
+      console.log(`  ${mark} [${item.confidence}] ${item.step}: ${item.detail}`);
+    }
+    if (findings.length) {
+      console.log("findings:");
+      for (const finding of findings) {
+        console.log(`  ${finding.severity === "error" ? "\u2717" : "\u26A0"} ${finding.code} ${finding.path} \u2014 ${finding.message}`);
+      }
+    }
+  }
+  return status === "pass" ? EXIT.ok : EXIT.validation;
+}
+function emitPlanUsageError(json, adapter, recipeFile, code, message) {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: "run", mode: "plan", status: "fail", adapter, recipe: recipeFile, error: { code, message } },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 run --plan: ${message}`);
+  }
+  return EXIT.usage;
+}
+async function handleStop(argv) {
+  const { options } = parseArgs(argv, "stop");
+  const json = optionFlag(options, "json");
+  const { adapter, target } = resolveAdapter(options);
+  const surface = getAdapterSurface(adapter);
+  const explicitPort = optionString(options, "port") ?? optionString(options, "watcherPort");
+  if (explicitPort) {
+    process.env.WATCHER_PORT = explicitPort;
+    process.env.METRO_PORT = explicitPort;
+  } else {
+    surface.resolveSlotPorts(target);
+  }
+  const stop = surface.devServer.stop(target);
+  if (stop.kind === "headless") {
+    return usageOut(json, "stop", stop.message, stop.userAction);
+  }
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "stop",
+          adapter,
+          target,
+          status: stop.status === 0 ? "pass" : "fail",
+          ...stop.signalled !== void 0 ? { signalled: stop.signalled } : {},
+          exitCode: stop.status,
+          ...stop.output ? { output: stop.output } : {}
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    if (stop.output) process.stderr.write(`${stop.output}
+`);
+    console.error(`${color(stop.status === 0 ? "ok" : "err", stop.status === 0 ? "\u2713" : "\u2717")} ${stop.summary}`);
+  }
+  return stop.status;
+}
+async function handleCall(argv) {
+  if (argv.length > 0 && argv[0].startsWith("--")) {
+    const message = "call requires <action> first: mm-harness call <action> [--arg k=v ...] [flags]";
+    console.error(message);
+    return EXIT.usage;
+  }
+  const { action: shortName, args, rest } = parseCallArgs(argv);
+  const { options } = parseArgs(rest, "call");
+  const json = optionFlag(options, "json");
+  if (!shortName) {
+    let example = "mm-harness call <action>";
+    let discovery = "mm-harness actions";
+    try {
+      const { adapter: adapter2 } = resolveAdapter(options);
+      const manifest2 = loadActionManifest(adapter2, optionString(options, "actionManifest"));
+      const { getRecipeActionManifestActionNames: getRecipeActionManifestActionNames2 } = await importRecipeProtocol();
+      const exampleAction = pickCallExampleAction(getRecipeActionManifestActionNames2(manifest2));
+      example = `mm-harness call ${exampleAction} --adapter ${adapter2}`;
+      discovery = `mm-harness actions --adapter ${adapter2}`;
+    } catch {
+    }
+    const message = `call requires <action>. Example: ${example}`;
+    const userAction = `${example}   # see the vocabulary: ${discovery}`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", error: { code: "USAGE", message, userAction } }, null, 2));
+    else console.error(`${message}
+  See the vocabulary: ${discovery}`);
+    return EXIT.usage;
+  }
+  const { adapter, target } = resolveAdapter(options);
+  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, command: "call", status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness call: ${msg}`);
+    }
+    return EXIT.bounded;
+  }
+  const actionManifestOverride = optionString(options, "actionManifest");
+  const manifest = loadActionManifest(adapter, actionManifestOverride);
+  const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+  const names = getRecipeActionManifestActionNames(manifest);
+  const resolution = resolveActionName(shortName, names);
+  if (resolution.status === "unknown") {
+    const message = `\u2717 call: unknown action "${shortName}" for the ${adapter} adapter.
+  See the vocabulary: mm-harness actions --adapter ${adapter} --json`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_UNKNOWN", message } }, null, 2));
+    else console.error(message);
+    return EXIT.usage;
+  }
+  if (resolution.status === "ambiguous") {
+    const message = `\u2717 call: "${shortName}" is ambiguous: ${resolution.candidates.join(", ")} \u2014 use the full name.`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_AMBIGUOUS", message, candidates: resolution.candidates } }, null, 2));
+    else console.error(message);
+    return EXIT.usage;
+  }
+  const resolvedAction = resolution.resolved;
+  const recipe = synthesizeOneNodeRecipe(resolvedAction, args);
+  const validation = await validateRecipeAdapterAware(recipe, manifest);
+  if (validation.status === "invalid") {
+    const message = `\u2717 call ${resolvedAction}: recipe validation failed`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, resolvedAction, args, findings: validation.findings, error: { code: "RECIPE_VALIDATION_FAILED", message } }, null, 2));
+    else {
+      console.error(message);
+      for (const finding of validation.findings) console.error(`  ${finding.code} ${finding.path} \u2014 ${finding.message}`);
+    }
+    return EXIT.validation;
+  }
+  const prepared = await prepareHeal(adapter, target, options, json);
+  if (typeof prepared === "number") return prepared;
+  const { state, heal } = prepared;
+  const scratch = await mkdtemp(path.join(os.tmpdir(), "mm-harness-call-"));
+  const recipeFile = path.join(scratch, "call.recipe.json");
+  fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}
+`);
+  const artifactsDir = optionString(options, "artifactsDir") ?? path.join(scratch, "artifacts");
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const callRuntimeOptions = {
+    ...runtimeOptionsFromCli(options),
+    ...librarySources ? { librarySources } : {},
+    stdoutIsMachineContract: json
+  };
+  const { result, violation } = await executeWithHealBounds(
+    () => runRecipe(adapter, recipeFile, artifactsDir, target, actionManifestOverride, callRuntimeOptions),
+    adapter,
+    target,
+    heal,
+    state
+  );
+  if (violation !== null) return emitHealViolation(json, "call", result, violation, state, adapter);
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "call",
+          adapter,
+          action: shortName,
+          resolvedAction,
+          args,
+          status: result.status,
+          summaryPath: result.summaryPath,
+          tracePath: result.tracePath,
+          artifactManifestPath: result.artifactManifestPath,
+          recovered: state.recovered,
+          mutations: state.mutations,
+          exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(`call ${resolvedAction}: ${result.status}
+Artifacts: ${result.artifactManifestPath}`);
+  }
+  return result.status === "pass" ? EXIT.ok : EXIT.runtime;
+}
+function parseCallArgs(argv) {
+  const args = {};
+  const rest = [];
+  let action;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--arg" || arg.startsWith("--arg=")) {
+      const pair = arg === "--arg" ? argv[i += 1] : arg.slice("--arg=".length);
+      if (pair === void 0) throw usageError("--arg requires k=v.");
+      const eq = pair.indexOf("=");
+      if (eq === -1) throw usageError(`--arg must be k=v: ${pair}`);
+      args[pair.slice(0, eq)] = pair.slice(eq + 1);
+      continue;
+    }
+    if (!arg.startsWith("--") && action === void 0) {
+      action = arg;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { action, args, rest };
+}
+function resolveActionName(shortName, names) {
+  if (names.includes(shortName)) return { status: "ok", resolved: shortName, candidates: [shortName] };
+  const finalSegment = (name) => name.split(".").pop() ?? name;
+  const exactSegment = names.filter((name) => finalSegment(name) === shortName);
+  const tier = exactSegment.length > 0 ? exactSegment : names.filter((name) => finalSegment(name).includes(shortName));
+  if (tier.length === 1) return { status: "ok", resolved: tier[0], candidates: tier };
+  if (tier.length > 1) return { status: "ambiguous", resolved: "", candidates: tier };
+  return { status: "unknown", resolved: "", candidates: [] };
+}
+function pickCallExampleAction(names) {
+  const walletish = names.find((name) => /wallet|unlock/u.test(name));
+  if (walletish) return walletish;
+  if (names.includes("command")) return "command";
+  return names[0] ?? "command";
+}
+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 };
+    }
+  }
+}
+async function handleCompletionCandidates(argv) {
+  const kind = argv[0];
+  const { options } = parseArgs(argv.slice(1), "completion-candidates");
+  const json = optionFlag(options, "json");
+  if (kind !== "actions" && kind !== "flows") {
+    console.error("completion-candidates requires <actions|flows>.");
+    return EXIT.usage;
+  }
+  const target = targetPath(options);
+  let adapter;
+  let candidates;
+  if (kind === "actions") {
+    adapter = resolveAdapter(options).adapter;
+    candidates = readFreshCandidates(target, "actions");
+    if (!candidates) {
+      const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+      candidates = getRecipeActionManifestActionNames(manifest);
+      writeCompletionCandidates(target, "actions", candidates);
+    }
+  } else {
+    candidates = readFreshCandidates(target, "flows");
+    if (!candidates) {
+      const sources = await resolveMetaMaskLibrarySources(void 0).catch(() => void 0);
+      if (!sources) {
+        candidates = [];
+      } else {
+        const harness = await importRecipeHarness();
+        const resolution = await harness.loadRecipeLibraries(sources);
+        candidates = [...resolution.flows.keys()].sort();
+        writeCompletionCandidates(target, "flows", candidates);
+      }
+    }
+  }
+  if (json) console.log(JSON.stringify({ schemaVersion: 1, kind, adapter, candidates }, null, 2));
+  else for (const candidate of candidates) console.log(candidate);
+  return EXIT.ok;
+}
+async function handleRun({ positional, options }) {
+  const targetRecipe = positional[0];
+  if (!targetRecipe) throw usageError("run requires <recipe.json>.");
+  if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
+  const adapter = adapterOption(options);
+  const json = optionFlag(options, "json");
+  const target = targetPath(options);
+  const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
+  const prepared = await prepareHeal(adapter, target, options, json);
+  if (typeof prepared === "number") return prepared;
+  const { state, heal } = prepared;
+  const validated = await validateRunRecipeStatic(targetRecipe, adapter, options);
+  if (validated.usageError) {
+    return emitRunUsageError(json, adapter, validated.recipeFile, validated.usageError.code, validated.usageError.message);
+  }
+  if (validated.errorCount > 0) {
+    return emitRunValidationError(json, adapter, validated.recipeFile, validated.findings, validated.errorCount);
+  }
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const runtimeOptions = {
+    ...runtimeOptionsFromCli(options),
+    ...librarySources ? { librarySources } : {},
+    stdoutIsMachineContract: json
+  };
+  const { result, violation } = await executeWithHealBounds(
+    () => runRecipe(adapter, targetRecipe, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
+    adapter,
+    target,
+    heal,
+    state
+  );
+  if (violation !== null) return emitHealViolation(json, "run", result, violation, state, adapter);
+  const exitCode = result.status === "pass" ? EXIT.ok : EXIT.runtime;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "run",
+          adapter,
+          status: result.status,
+          exitCode,
+          recovered: state.recovered,
+          mutations: state.mutations,
+          result
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(`MetaMask recipe run: ${result.status}
+Artifacts: ${result.artifactManifestPath}`);
+  }
+  return exitCode;
+}
+function emitRunUsageError(json, adapter, recipeFile, code, message) {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: "run", adapter, status: "fail", exitCode: EXIT.usage, recipe: recipeFile, error: { code, message } },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 run: ${message}`);
+  }
+  return EXIT.usage;
+}
+function emitRunValidationError(json, adapter, recipeFile, findings, errorCount) {
+  const message = `recipe validation found ${errorCount} error(s)`;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "run",
+          adapter,
+          status: "fail",
+          exitCode: EXIT.validation,
+          recovered: [],
+          mutations: [],
+          recipe: recipeFile,
+          findings,
+          error: { code: "RECIPE_VALIDATION_FAILED", message }
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 run: ${message}`);
+    for (const finding of findings) {
+      if (finding.severity === "error") console.error(`  ${finding.code} ${finding.path} \u2014 ${finding.message}`);
+    }
+  }
+  return EXIT.validation;
+}
+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;
+}
+async function handleSelfTest({ options }) {
+  const result = await runSelfTest(options);
+  if (optionFlag(options, "json")) console.log(JSON.stringify(result, null, 2));
+  else console.log(`MetaMask runner self-test: ${result.status}
+Artifacts: ${result.artifactsDir}`);
+  return result.status === "pass" ? 0 : 1;
+}
+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 parsePort(value, errorMessage) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0) throw usageError(errorMessage);
+  return port;
+}
+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 serializeLibrarySources(sources) {
+  return sources.map((source) => source.name ? `${source.name}=${source.root}` : source.root).join(":");
+}
+function flowSourceTier(source, index, total) {
+  if (index === total - 1 && source.name === "metamask") return "canonical";
+  if (source.name === "personal") return "personal";
+  return "team";
+}
+const FLOWS_SUBCOMMANDS = ["list", "promote"];
+function stripTargetFlag(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--target") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--target=")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+async function handleFlows(argv) {
+  const sources = await resolveMetaMaskLibrarySources(void 0);
+  if (!sources) {
+    throw usageError(
+      "flows requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support; flows resolve personal > team > canonical). Next: update the dependency and run yarn install."
+    );
+  }
+  const forwarded = stripTargetFlag(argv);
+  const jsonMode = forwarded.includes("--json");
+  if (!jsonMode) {
+    console.error(color("label", "flows resolve by precedence (highest wins; local shadows canonical):"));
+    sources.forEach((source, index) => {
+      const name = source.name ?? path.basename(source.root);
+      console.error(`  ${index + 1}. ${color("cmd", name)} ${color("dim", `[${flowSourceTier(source, index, sources.length)}]`)}`);
+    });
+  }
+  const withSubcommand = FLOWS_SUBCOMMANDS.includes(forwarded[0]) ? forwarded : ["list", ...forwarded];
+  const { runRecipeHarnessCli } = await importRecipeHarnessCli();
+  const previousLibraryPath = process.env.RECIPE_LIBRARY_PATH;
+  process.env.RECIPE_LIBRARY_PATH = serializeLibrarySources(sources);
+  try {
+    await runRecipeHarnessCli(["flows", ...withSubcommand]);
+  } finally {
+    restoreEnv("RECIPE_LIBRARY_PATH", previousLibraryPath);
+  }
+  return 0;
+}
+async function main(argv) {
+  const command = argv[0];
+  if (!command || command === "-h" || command === "--help") {
+    usage();
+    return command ? 0 : 2;
+  }
+  if (command === "flows") return handleFlows(argv.slice(1));
+  if (command === "call") return handleCall(argv.slice(1));
+  if (command === "completion-candidates") return handleCompletionCandidates(argv.slice(1));
+  if (OVERLAY_COMMANDS.includes(command)) {
+    const code = await handleHarness(argv);
+    if (code === 0 && command === "install") {
+      try {
+        invalidateCompletionCache(targetPath(parseArgs(argv.slice(1), command).options));
+      } catch {
+      }
+    }
+    return code;
+  }
+  if (command === "launch") return handleLaunch(argv.slice(1));
+  if (command === "stop") return handleStop(argv.slice(1));
+  if (command === "logs") return handleLogs(argv.slice(1));
+  if (command === "debug") return handleDebug(argv.slice(1));
+  if (command === "fixtures") return handleFixtures(argv.slice(1), { runOneNode });
+  const handler = COMMANDS[command];
+  if (!handler) throw new Error(`Unknown command: ${command}`);
+  return handler(parseArgs(argv.slice(1), command));
+}
+if (!globalThis.__MM_HARNESS_WRAPPER__) {
+  try {
+    process.exit(await main(process.argv.slice(2)));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(
+      error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : 1
+    );
+  }
+}
+export {
+  main
+};