@deeeed/metamask-harness 0.80.0 → 0.81.0

package/dist/commands/run-engine.js

@@ -1,1301 +0,0 @@
-import fs from "node:fs";
-import { mkdtemp } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { resolveActionManifest, validateManifest } from "../manifest.js";
-import { getAdapterSurface } from "../adapters/surface.js";
-import { extensionProductConfigBlock } from "../adapters/extension/product-config.js";
-import { importRecipeHarness, importRecipeProtocol, runnerDir } from "../paths.js";
-import {
-  resolveMetaMaskParameterValue,
-  validateMetaMaskActionInputs
-} from "../metamask-action-validation.js";
-import { beginRunDiagnostics, captureExecutionProvenance, captureHelperSupportsRecordSessionSnapshots, executedBrowser, executionProvenanceDrift, finishRunDiagnostics, ProvenanceDriftError, recipeCdpPorts, recipeEnvName, startRecipeRecording, stopRecipeRecording, validateRuntimeProofPlan, writeExecutionProvenance, gitLibraryProvenance, recipeRuntimePath, ensureOverlay, newHealState, parseHeal, recipeRunning, checkHealBounds, conciseFailureForHuman, EXIT, actionManifestPathOption, optionString, optionFlag, optionStrings, isRecord, shellQuoteArg, targetPath, usageError } from "@farmslot/recipe-cli/harness";
-import { runnableLibraryRecipes } from "../discovery.js";
-import { recipeComposition } from "@farmslot/recipe-cli";
-import { consoleClassifier } from "../console-classifier.js";
-import {
-  authorizeTrustedMutationPlan,
-  loadTrustedMutationBase
-} from "../funding-execution-context.js";
-const RUNNER_INCLUDES = ["src", "adapters", "library", "bin", "dist", "package.json"];
-async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}, preflightedExecution, effectsState = newHealState()) {
-  const restoreRuntimeEnvironment = activateRecipeRuntimeEnvironment(
-    adapter,
-    projectRoot,
-    runtimeOptions
-  );
-  try {
-    const wasPreflighted = preflightedExecution !== void 0;
-    const execution = preflightedExecution ?? await resolveRecipeExecution(
-      adapter,
-      recipe,
-      artifactsDir,
-      projectRoot,
-      actionManifestPath,
-      runtimeOptions
-    );
-    const {
-      runner,
-      runRequest,
-      absoluteArtifactsDir,
-      useFramedExtensionRecording,
-      provenanceInput,
-      provenanceSnapshots
-    } = execution;
-    if (!wasPreflighted) await runner.preflight(runRequest);
-    await prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions);
-    await runner.preflight(runRequest);
-    const preExecute = await captureExecutionProvenance(
-      provenanceInput,
-      "pre-execute"
-    );
-    provenanceSnapshots.push(preExecute);
-    const preExecuteDrift = executionProvenanceDrift(
-      provenanceSnapshots[0],
-      preExecute
-    );
-    if (preExecuteDrift.length > 0) {
-      const provenancePath2 = await writeExecutionProvenance(
-        absoluteArtifactsDir,
-        provenanceSnapshots,
-        preExecuteDrift
-      );
-      throw new ProvenanceDriftError(provenancePath2, preExecuteDrift);
-    }
-    const diagnosticBaseline = await beginRunDiagnostics(adapter, projectRoot);
-    const recording = useFramedExtensionRecording ? await startRecipeRecording(adapter, projectRoot, absoluteArtifactsDir, {
-      record: true,
-      cdpPort: runtimeOptions.cdpPort
-    }) : void 0;
-    let result;
-    let executionError;
-    try {
-      result = await runner.run(runRequest);
-    } catch (error) {
-      executionError = error;
-      try {
-        await stopRecipeRecording(recording);
-      } catch (recordingError2) {
-        console.error(
-          `WARN: recipe and video recording both failed; preserving recipe failure: ${recordingError2 instanceof Error ? recordingError2.message : String(recordingError2)}`
-        );
-      }
-    } finally {
-      const teardown = getAdapterSurface(adapter).run?.teardown;
-      if (teardown) await teardown(projectRoot, recipeRunEnv(adapter, runtimeOptions));
-    }
-    let recordingError;
-    if (executionError === void 0 && result) {
-      try {
-        await stopRecipeRecording(recording, result);
-      } catch (error) {
-        recordingError = error;
-      }
-    }
-    const end = await captureExecutionProvenance(provenanceInput, "end");
-    provenanceSnapshots.push(end);
-    const endDrift = executionProvenanceDrift(provenanceSnapshots[0], end);
-    const provenancePath = await writeExecutionProvenance(
-      absoluteArtifactsDir,
-      provenanceSnapshots,
-      endDrift,
-      result?.artifactManifestPath
-    );
-    if (endDrift.length > 0) {
-      throw new ProvenanceDriftError(provenancePath, endDrift, executionError);
-    }
-    if (executionError !== void 0) throw executionError;
-    if (recordingError !== void 0) throw recordingError;
-    if (!result) throw new Error("Recipe execution returned no result.");
-    const finalized = await finishRunDiagnostics(diagnosticBaseline, result, consoleClassifier);
-    persistRunEffects(
-      finalized.summaryPath,
-      finalized.artifactManifestPath,
-      effectsState
-    );
-    const browser = executedBrowser(
-      adapter,
-      projectRoot,
-      finalized.artifactManifestPath,
-      recipeCdpPorts(runRequest)
-    );
-    return browser ? { ...finalized, browser } : finalized;
-  } finally {
-    restoreRuntimeEnvironment();
-  }
-}
-async function preflightRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}) {
-  const restoreRuntimeEnvironment = activateRecipeRuntimeEnvironment(
-    adapter,
-    projectRoot,
-    runtimeOptions
-  );
-  try {
-    const execution = await resolveRecipeExecution(
-      adapter,
-      recipe,
-      artifactsDir,
-      projectRoot,
-      actionManifestPath,
-      runtimeOptions
-    );
-    await execution.runner.preflight(execution.runRequest);
-    return execution;
-  } finally {
-    restoreRuntimeEnvironment();
-  }
-}
-function persistRunEffects(summaryPath, artifactManifestPath, state) {
-  for (const filePath of [summaryPath, artifactManifestPath]) {
-    let document;
-    try {
-      document = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    } catch {
-      document = null;
-    }
-    if (!isRecord(document)) {
-      throw new Error(`Recipe evidence file is not valid JSON: ${filePath}`);
-    }
-    document.recovered = [...state.recovered];
-    document.mutations = state.mutations.map((mutation) => ({ ...mutation }));
-    fs.writeFileSync(filePath, `${JSON.stringify(document, null, 2)}
-`);
-  }
-}
-async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions) {
-  const absoluteArtifactsDir = path.resolve(artifactsDir);
-  const absoluteRecipePath = typeof recipe === "string" ? path.resolve(recipe) : void 0;
-  const recordVideo = runtimeOptions.recordVideo ?? false;
-  const { resolveRecipeTrustInput } = await importRecipeHarness();
-  const trust = resolveRecipeTrustInput({
-    sourceTrust: runtimeOptions.source?.trust,
-    sourceKind: runtimeOptions.source?.kind,
-    sourceName: runtimeOptions.source?.name,
-    sourceDigest: runtimeOptions.source?.digest,
-    approvalDigest: runtimeOptions.approval?.planDigest
-  });
-  const librarySources = executionLibrarySources(
-    runtimeOptions.librarySources,
-    trust.source?.trust ?? "trusted"
-  );
-  const { manifest, actionSources } = await resolveActionManifest(
-    adapter,
-    actionManifestPath,
-    librarySources,
-    process.env[recipeEnvName("LIVE_ADAPTER_DIR")]
-  );
-  const { createMetaMaskRunner } = await import("../runner.js");
-  const recipeDocument = runtimeRecipeDocument(recipe, absoluteRecipePath);
-  const trustedMutation = await loadTrustedMutationBase({
-    fundingRequest: runtimeOptions.fundingRequest,
-    fundingPreflight: runtimeOptions.fundingPreflight,
-    fundingReleaseProof: runtimeOptions.fundingReleaseProof,
-    fundingBalanceProof: runtimeOptions.fundingBalanceProof,
-    artifactsDir: absoluteArtifactsDir,
-    projectRoot,
-    rootRecipe: recipeDocument
-  });
-  const surface = getAdapterSurface(adapter);
-  const suppressAutoHud = surface.run?.autoHud?.() === false;
-  const runnerOptions = {
-    quietStdout: runtimeOptions.stdoutIsMachineContract === true,
-    suppressLibraryResolutionLogs: runtimeOptions.suppressLibraryResolutionLogs,
-    autoHud: suppressAutoHud ? false : trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
-    onActionEvent: runtimeOptions.onActionEvent,
-    actionSources,
-    // A direct engineer invocation is the explicit trust boundary for a
-    // task-local adapter. Inherited gateway provenance remains authoritative,
-    // so an untrusted worker cannot promote itself with CLI flags.
-    trustTaskActions: (trust.source?.trust ?? "trusted") === "trusted"
-  };
-  let runner = await createMetaMaskRunner(adapter, manifest, {
-    ...runnerOptions,
-    trustedMutation
-  });
-  const useFramedExtensionRecording = surface.recording?.framed !== void 0 && recordVideo === "full-run" && trust.source?.trust !== "untrusted" && trust.source?.trust !== "unknown" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
-  const runRequest = {
-    ...recipeDocument !== void 0 ? { recipeDocument } : absoluteRecipePath ? { recipePath: absoluteRecipePath } : { recipeDocument: recipe },
-    artifactsDir: absoluteArtifactsDir,
-    projectRoot,
-    inheritProcessEnv: false,
-    env: {
-      ...recipeProcessEnvironment(),
-      ...recipeRunEnv(adapter, runtimeOptions),
-      [recipeEnvName("ACTION_SOURCE_MAP")]: actionSourceMap(actionSources)
-    },
-    recordVideo: useFramedExtensionRecording ? false : recordVideo,
-    ...trust,
-    ...librarySources ? { librarySources } : {},
-    adapter,
-    ...runtimeOptions.params ? { params: runtimeOptions.params } : {}
-  };
-  if (trustedMutation) {
-    const executionPlan = await runner.preflight(runRequest);
-    const authorizedMutation = await authorizeTrustedMutationPlan(trustedMutation, executionPlan);
-    runner = await createMetaMaskRunner(adapter, manifest, {
-      ...runnerOptions,
-      trustedMutation: authorizedMutation
-    });
-  }
-  const provenanceInput = {
-    adapter,
-    projectRoot,
-    recipeDocument: recipeDocument ?? recipe,
-    ...absoluteRecipePath ? { recipePath: absoluteRecipePath } : {},
-    ...librarySources ? { librarySources } : {},
-    excludedProductRoots: [
-      absoluteArtifactsDir,
-      recipeRuntimePath(projectRoot, "operations"),
-      recipeRuntimePath(projectRoot, "lock-members")
-    ],
-    helperPaths: commandHelperPaths(recipeDocument ?? recipe, projectRoot),
-    runnerIncludes: RUNNER_INCLUDES
-  };
-  const startProvenance = await captureExecutionProvenance(
-    provenanceInput,
-    "start"
-  );
-  return {
-    runner,
-    absoluteArtifactsDir,
-    useFramedExtensionRecording,
-    runRequest,
-    provenanceInput,
-    provenanceSnapshots: [startProvenance]
-  };
-}
-function commandHelperPaths(recipe, projectRoot) {
-  const helpers = /* @__PURE__ */ new Set();
-  visitRecipeValues(recipe, (value) => {
-    if (!isRecord(value) || value.action !== "command" || typeof value.cmd !== "string") return;
-    const candidates = commandHelperTokens(value.cmd);
-    for (const token of candidates) {
-      if (/[$`{}]/u.test(token)) {
-        throw new Error(`Command helper path cannot be bound before execution: ${token}`);
-      }
-      if (!isHelperToken(token)) continue;
-      const absolute = path.isAbsolute(token) ? path.resolve(token) : path.resolve(projectRoot, token);
-      let stat;
-      try {
-        stat = fs.lstatSync(absolute);
-      } catch {
-        throw new Error(`Command helper source does not exist: ${token}`);
-      }
-      if (stat.isSymbolicLink() || !stat.isFile()) {
-        throw new Error(`Command helper source must be a regular file: ${token}`);
-      }
-      helpers.add(absolute);
-    }
-  });
-  return [...helpers].sort();
-}
-function commandHelperTokens(command, depth = 0) {
-  if (depth > 4) {
-    throw new Error("Command helper sources exceed the supported shell nesting depth.");
-  }
-  const tokens = shellTokens(command);
-  const candidates = new Set(tokens.filter(isHelperToken));
-  for (const token of tokens) {
-    const assignment = /^(?:--)?(?:config|configuration|manifest|project|recipe|schema|tsconfig)=([^=]+)$/iu.exec(
-      token
-    );
-    const value = assignment?.[1];
-    if (value && (isHelperToken(value) || isConfigInputToken(value))) {
-      candidates.add(value);
-    }
-  }
-  for (let index = 0; index < tokens.length - 1; index += 1) {
-    if (!isScriptInterpreter(tokens[index])) continue;
-    const option = tokens[index + 1];
-    if (isShellInterpreter(tokens[index]) && /^-[a-z]*c[a-z]*$/iu.test(option) && tokens[index + 2]) {
-      for (const nested of commandHelperTokens(tokens[index + 2], depth + 1)) {
-        candidates.add(nested);
-      }
-      continue;
-    }
-    if (!option.startsWith("-")) candidates.add(option);
-  }
-  return candidates;
-}
-function visitRecipeValues(value, visit) {
-  visit(value);
-  if (Array.isArray(value)) {
-    for (const child of value) visitRecipeValues(child, visit);
-    return;
-  }
-  if (!isRecord(value)) return;
-  for (const child of Object.values(value)) visitRecipeValues(child, visit);
-}
-function isHelperToken(token) {
-  return !token.startsWith("-") && !token.includes("=") && !/^[a-z][a-z0-9+.-]*:\/\//iu.test(token) && /^\S+\.(?:cjs|mjs|js|jsx|ts|tsx|sh|py)$/u.test(token);
-}
-function isConfigInputToken(token) {
-  return !token.startsWith("-") && !token.includes("=") && /^\S+\.(?:json|json5|ya?ml|toml)$/u.test(token);
-}
-function isScriptInterpreter(token) {
-  return /^(?:node|bash|sh|python|python3)$/u.test(path.basename(token));
-}
-function isShellInterpreter(token) {
-  return /^(?:bash|sh)$/u.test(path.basename(token));
-}
-function shellTokens(command) {
-  const tokens = [];
-  let token = "";
-  let quote = null;
-  let escaped = false;
-  const push = () => {
-    if (token) tokens.push(token);
-    token = "";
-  };
-  for (const character of command) {
-    if (escaped) {
-      token += character;
-      escaped = false;
-      continue;
-    }
-    if (character === "\\" && quote !== "'") {
-      escaped = true;
-      continue;
-    }
-    if (quote) {
-      if (character === quote) quote = null;
-      else token += character;
-      continue;
-    }
-    if (character === "'" || character === '"') {
-      quote = character;
-      continue;
-    }
-    if (/\s|[;&|<>]/u.test(character)) push();
-    else token += character;
-  }
-  if (quote || escaped) {
-    throw new Error("Command helper sources cannot be bound from an unterminated shell token.");
-  }
-  push();
-  return tokens;
-}
-function runtimeRecipeDocument(recipe, absoluteRecipePath) {
-  if (typeof recipe !== "string") return recipe;
-  if (!absoluteRecipePath || !fs.existsSync(absoluteRecipePath)) return void 0;
-  try {
-    return JSON.parse(fs.readFileSync(absoluteRecipePath, "utf8"));
-  } catch {
-    return void 0;
-  }
-}
-function recipeProcessEnvironment() {
-  const env = { ...process.env };
-  delete env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
-  delete env.MM_HARNESS_OPERATION_ID;
-  return env;
-}
-function executionLibrarySources(sources, invocationTrust) {
-  return sources?.map((source) => {
-    if (source.name === "metamask") return source;
-    return {
-      ...source,
-      provenance: {
-        ...source.provenance,
-        kind: source.provenance?.kind ?? "library",
-        trust: invocationTrust === "trusted" ? "trusted" : "unknown",
-        name: source.provenance?.name ?? source.name ?? path.basename(source.root)
-      }
-    };
-  });
-}
-const RUN_ENV_KEYS = [
-  "CDP_PORT",
-  "RECIPE_CDP_PORT",
-  "WATCHER_PORT",
-  "METRO_PORT"
-];
-function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions) {
-  const surface = getAdapterSurface(adapter);
-  const previousEnv = Object.fromEntries(
-    [...RUN_ENV_KEYS, ...surface.run?.envKeys ?? []].map((key) => [key, process.env[key]])
-  );
-  const pinnedEnv = surface.run?.pinnedEnv?.();
-  surface.resolveSlotPorts(projectRoot);
-  if (pinnedEnv) {
-    for (const [key, value] of Object.entries(pinnedEnv)) {
-      restoreEnv(key, value);
-    }
-  }
-  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;
-  }
-  surface.run?.activateEnv?.(projectRoot, runtimeOptions);
-  return () => {
-    for (const [key, value] of Object.entries(previousEnv)) restoreEnv(key, value);
-  };
-}
-function actionSourceMap(sources) {
-  const roots = {};
-  for (const [action, source] of sources) {
-    if (source.tier === "official") continue;
-    roots[action] = source.implementationRoot ?? (source.tier === "task" ? path.join(path.dirname(source.manifestPath), "actions") : path.join(
-      path.dirname(path.dirname(source.manifestPath)),
-      "actions"
-    ));
-  }
-  return JSON.stringify(roots);
-}
-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,
-    RECIPE_RN_EXPLICIT_PLATFORM: process.env.RECIPE_RN_EXPLICIT_PLATFORM
-  };
-  const childEnv = getAdapterSurface(adapter).run?.childEnv;
-  return childEnv ? childEnv(base) : base;
-}
-async function prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions) {
-  await getAdapterSurface(adapter).run?.prepareRuntime?.(projectRoot, runtimeOptions);
-}
-function restoreEnv(key, value) {
-  if (value === void 0) delete process.env[key];
-  else process.env[key] = value;
-}
-async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySources, rootRef, params, proof = false) {
-  const protocol = await importRecipeProtocol();
-  let externalRecipeIds;
-  let libraryResolution;
-  const harness = await importRecipeHarness();
-  if (librarySources && librarySources.length > 0) {
-    libraryResolution = await harness.loadRecipeLibraries(librarySources, {
-      adapter
-    });
-    externalRecipeIds = new Set(libraryResolution.recipes.keys());
-  }
-  const validationOptions = externalRecipeIds !== void 0 ? { externalRecipeIds } : void 0;
-  const withManifest = protocol.validateRecipeWithManifest(
-    recipe,
-    manifest,
-    validationOptions
-  );
-  const findings = [
-    ...withManifest.findings,
-    ...withManifest.status === "valid" && params ? protocol.validateRecipeWithManifest(
-      resolveMetaMaskParameterValue(recipe, params),
-      manifest,
-      validationOptions
-    ).findings : [],
-    ...validateMetaMaskActionInputs(recipe, adapter, params)
-  ];
-  if (withManifest.status === "valid" && isRecord(recipe) && libraryResolution) {
-    try {
-      const digest = protocol.digestRecipeDocument(recipe);
-      const dependencies = harness.resolveRecipeDependencies({
-        rootRef: rootRef ?? `$root:${digest}`,
-        root: recipe,
-        rootSource: {
-          kind: "recipe-file",
-          trust: "unknown",
-          name: rootRef ?? "recipe file",
-          digest
-        },
-        recipes: libraryResolution.recipes
-      });
-      if (params) {
-        harness.validateRecipeDependencyParams({
-          root: recipe,
-          params,
-          recipes: dependencies.recipes
-        });
-      }
-      for (const dependency of dependencies.recipes.values()) {
-        findings.push(
-          ...protocol.validateRecipeWithManifest(
-            dependency.document,
-            manifest,
-            validationOptions
-          ).findings
-        );
-      }
-      const validateDependencyInstances = (document, parentParams) => {
-        if (!isRecord(document) || !isRecord(document.workflow) || !isRecord(document.workflow.nodes)) return;
-        for (const rawNode of Object.values(document.workflow.nodes)) {
-          const node = resolveMetaMaskParameterValue(rawNode, parentParams);
-          if (!isRecord(node) || node.action !== "call" || typeof node.ref !== "string") continue;
-          const dependency = dependencies.recipes.get(protocol.normalizeRecipeRef(node.ref));
-          if (!dependency) continue;
-          const supplied = isRecord(node.params) ? node.params : {};
-          const childParams = protocol.applyRecipeParamDefaults(
-            supplied,
-            isRecord(dependency.document) ? dependency.document.paramsSchema : void 0
-          );
-          findings.push(...protocol.validateRecipeWithManifest(
-            resolveMetaMaskParameterValue(dependency.document, childParams),
-            manifest,
-            validationOptions
-          ).findings);
-          findings.push(...validateMetaMaskActionInputs(dependency.document, adapter, childParams));
-          validateDependencyInstances(dependency.document, childParams);
-        }
-      };
-      validateDependencyInstances(recipe, params ?? {});
-      if (proof && !findings.some((finding) => finding.severity === "error")) {
-        findings.push(...validateRuntimeProofPlan(
-          recipe,
-          new Map([...dependencies.recipes].map(([ref, dependency]) => [ref, dependency.document]))
-        ));
-      }
-    } catch (error) {
-      const resolutionError = error instanceof harness.RecipeResolutionError ? error : void 0;
-      if (!resolutionError) throw error;
-      findings.push({
-        severity: "error",
-        code: resolutionError.code,
-        path: "workflow",
-        message: `${resolutionError.message} Next: ${resolutionError.userAction}`
-      });
-    }
-  }
-  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 isRecipeFile(p) {
-  try {
-    return fs.statSync(p).isFile();
-  } catch {
-    return false;
-  }
-}
-async function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
-  const direct = path.resolve(recipeArg);
-  if (isRecipeFile(direct)) return { recipeFile: direct };
-  const sources = effectiveLibrarySources(librarySources);
-  const harness = await importRecipeHarness();
-  const resolution = await harness.loadRecipeLibraries(sources, { adapter });
-  if (!recipeArg.includes("/") && !recipeArg.includes(path.sep)) {
-    const selected = resolution.recipes.get(recipeArg);
-    if (selected) return { recipeFile: selected.path, ref: selected.ref };
-  }
-  const available = [...resolution.recipes.keys()].sort();
-  const nonCanonical = sources.filter((source) => source.name !== "metamask");
-  const notFoundCore = nonCanonical.length > 0 ? `recipe not found: ${recipeArg} \u2014 not a file, and no recipe matched in library sources [${sources.map((source) => source.name ?? path.basename(source.root)).join(", ")}].` : `recipe not found: ${recipeArg} \u2014 not a file, and no packaged library recipe matched.`;
-  const suffix = available.length > 0 ? ` Library recipes for ${adapter}: ${available.join(", ")} (mm-harness run <name>).` : ` The packaged library has no recipes for ${adapter}.`;
-  return { notFound: notFoundCore + suffix };
-}
-function effectiveLibrarySources(librarySources) {
-  return librarySources && librarySources.length > 0 ? librarySources : [{ name: "metamask", root: path.resolve(runnerDir, "library") }];
-}
-async function listRunnableRecipes(adapter, librarySources) {
-  return (await runnableLibraryRecipes(adapter, effectiveLibrarySources(librarySources))).map(
-    (recipe) => recipeSummary(recipe.ref, adapter, recipe.document, recipe)
-  ).sort((left, right) => left.name.localeCompare(right.name));
-}
-async function describeRunnableRecipe(recipeArg, adapter, librarySources) {
-  const resolved = await resolveRunRecipeArg(
-    recipeArg,
-    adapter,
-    librarySources
-  );
-  if ("notFound" in resolved) return resolved;
-  let document;
-  try {
-    document = JSON.parse(fs.readFileSync(resolved.recipeFile, "utf8"));
-  } catch (error) {
-    return {
-      unreadable: `could not read recipe ${resolved.recipeFile}: ${error instanceof Error ? error.message : String(error)}`
-    };
-  }
-  if (!isRecord(document)) {
-    return {
-      unreadable: `recipe ${resolved.recipeFile} must contain a JSON object.`
-    };
-  }
-  const harness = await importRecipeHarness();
-  const libraryResolution = await harness.loadRecipeLibraries(
-    effectiveLibrarySources(librarySources),
-    { adapter }
-  );
-  const selected = resolved.ref ? libraryResolution.recipes.get(resolved.ref) : void 0;
-  const composition = recipeComposition(document, libraryResolution.recipes);
-  const summary = recipeSummary(
-    resolved.ref ?? recipeArg,
-    adapter,
-    document,
-    selected
-  );
-  return {
-    recipe: {
-      ...summary,
-      source: selected?.source ?? "file",
-      file: selected?.file ?? resolved.recipeFile,
-      path: resolved.recipeFile,
-      ...typeof document.$schema === "string" ? { $schema: document.$schema } : {},
-      actions: composition.actions,
-      nestedRecipes: composition.nestedRecipes,
-      unresolvedRecipes: composition.unresolvedRecipes
-    }
-  };
-}
-function recipeSummary(ref, adapter, document, selected) {
-  return {
-    name: ref,
-    source: selected?.source ?? "file",
-    file: selected?.file ?? "",
-    shadows: selected?.shadows ?? [],
-    adapter,
-    variant: selected?.adapter ?? null,
-    parameters: recipeParameters(document),
-    ...typeof document.title === "string" && document.title.trim() ? { title: document.title.trim() } : {},
-    ...typeof document.description === "string" && document.description.trim() ? { description: document.description.trim() } : {}
-  };
-}
-function recipeParameters(document) {
-  if (!isRecord(document.paramsSchema)) return [];
-  const schema = document.paramsSchema;
-  const required = new Set(
-    Array.isArray(schema.required) ? schema.required.filter(
-      (entry) => typeof entry === "string"
-    ) : []
-  );
-  if (!isRecord(schema.properties)) return [];
-  return Object.entries(schema.properties).map(([name, raw]) => {
-    const property = isRecord(raw) ? raw : {};
-    return {
-      name,
-      ...typeof property.type === "string" ? { type: property.type } : {},
-      required: required.has(name),
-      ...Object.hasOwn(property, "default") ? { default: property.default } : {},
-      ...typeof property.description === "string" ? { description: property.description } : {},
-      ...Array.isArray(property.enum) ? { enum: property.enum } : {}
-    };
-  });
-}
-async function validateRunRecipeStatic(recipeArg, adapter, options, params = {}) {
-  let librarySources = await resolveMetaMaskLibrarySources(
-    optionStrings(options, "library")
-  );
-  const resolved = await resolveRunRecipeArg(
-    recipeArg,
-    adapter,
-    librarySources
-  );
-  const recipeFile = "recipeFile" in resolved ? resolved.recipeFile : path.resolve(recipeArg);
-  if ("recipeFile" in resolved && !resolved.ref) {
-    librarySources = await resolveMetaMaskLibrarySources(
-      optionStrings(options, "library"),
-      recipeFile
-    );
-  }
-  const empty = {
-    recipe: void 0,
-    recipeFile,
-    findings: [],
-    errorCount: 0,
-    manifestOk: false,
-    schemaValid: false,
-    effectiveParams: params,
-    ...librarySources ? { librarySources } : {}
-  };
-  if ("notFound" in resolved) {
-    return {
-      ...empty,
-      usageError: {
-        code: "RECIPE_NOT_FOUND",
-        message: resolved.notFound + await actionInsteadOfRecipeHint(recipeArg, adapter, options)
-      }
-    };
-  }
-  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 } = await resolveActionManifest(
-    adapter,
-    optionString(options, "actionManifest"),
-    librarySources
-  );
-  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)
-    });
-  }
-  let effectiveParams = params;
-  if (isRecord(recipe)) {
-    const protocol = await importRecipeProtocol();
-    effectiveParams = protocol.applyRecipeParamDefaults(
-      params,
-      recipe.paramsSchema
-    );
-    findings.push(
-      ...protocol.validateRecipeParams(effectiveParams, recipe.paramsSchema).findings
-    );
-  }
-  const validation = manifestOk ? await validateRecipeAdapterAware(
-    adapter,
-    recipe,
-    manifest,
-    librarySources,
-    resolved.ref,
-    effectiveParams,
-    optionFlag(options, "proof")
-  ) : {
-    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" && errorCount === 0,
-    effectiveParams,
-    ...librarySources ? { librarySources } : {}
-  };
-}
-async function actionInsteadOfRecipeHint(recipeArg, adapter, options) {
-  if (recipeArg.includes("/") || recipeArg.includes(path.sep)) return "";
-  try {
-    const librarySources = await resolveMetaMaskLibrarySources(
-      optionStrings(options, "library")
-    );
-    const { manifest } = await resolveActionManifest(
-      adapter,
-      optionString(options, "actionManifest"),
-      librarySources
-    );
-    const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-    const actions = getRecipeActionManifestActionNames(manifest);
-    const matches = actions.includes(recipeArg) ? [recipeArg] : actions.filter((name) => name.split(".").pop() === recipeArg);
-    if (matches.length !== 1) return "";
-    const device = optionString(options, "device");
-    const actionManifest = optionString(options, "actionManifest");
-    const parts = ["mm-harness", "call", matches[0]];
-    parts.push(
-      "--adapter",
-      adapter,
-      "--target",
-      shellQuoteArg(targetPath(options))
-    );
-    if (device) parts.push("--device", shellQuoteArg(device));
-    if (actionManifest)
-      parts.push("--action-manifest", shellQuoteArg(actionManifest));
-    return ` This is an action, not a recipe. Use: ${parts.join(" ")}.`;
-  } catch {
-    return "";
-  }
-}
-async function resolveMetaMaskLibrarySources(libraryEntry, recipePath) {
-  const harness = await importRecipeHarness();
-  const cliEntries = typeof libraryEntry === "string" ? [libraryEntry] : libraryEntry ? [...libraryEntry] : [];
-  const sources = await harness.resolveRecipeLibrarySources({
-    ...cliEntries.length > 0 ? { cliEntries } : {},
-    ...recipePath ? { recipePath } : {}
-  });
-  const canonicalRoot = path.resolve(runnerDir, "library");
-  const configuredCanonical = sources.find(
-    (source) => source.name === "metamask"
-  );
-  if (configuredCanonical && path.resolve(configuredCanonical.root) !== canonicalRoot) {
-    throw usageError(
-      `Recipe library source metamask must resolve to ${canonicalRoot}; got ${path.resolve(configuredCanonical.root)}.`
-    );
-  }
-  if (!sources.some((source) => path.resolve(source.root) === canonicalRoot)) {
-    sources.push({ name: "metamask", root: canonicalRoot });
-  }
-  return Promise.all(
-    sources.map(async (source) => {
-      const isBundled = source.name === "metamask";
-      const detected = isBundled ? {} : await gitLibraryProvenance(source.root);
-      return {
-        ...source,
-        provenance: {
-          kind: isBundled ? "bundled" : "library",
-          trust: isBundled ? "trusted" : "unknown",
-          name: source.name ?? path.basename(source.root),
-          ...detected,
-          ...source.provenance
-        }
-      };
-    })
-  );
-}
-function synthesizeOneNodeRecipe(action, args) {
-  return {
-    $schema: "https://farmslot.io/schemas/recipe-v1.schema.json",
-    title: `mm-harness call ${action}`,
-    description: `Ad-hoc single-action execution of ${action} via the real engine path (mm-harness call).`,
-    workflow: {
-      entry: "call",
-      nodes: {
-        call: {
-          ...args,
-          action,
-          next: "done",
-          intent: typeof args.intent === "string" ? args.intent : `Complete the requested ${action} operation`
-        },
-        done: { action: "end", status: "pass" }
-      }
-    }
-  };
-}
-async function runOneNode(adapter, action, args, target, actionManifest) {
-  const librarySources = await resolveMetaMaskLibrarySources(void 0);
-  const { manifest } = await resolveActionManifest(
-    adapter,
-    actionManifest,
-    librarySources
-  );
-  const recipe = synthesizeOneNodeRecipe(action, args);
-  const validation = await validateRecipeAdapterAware(
-    adapter,
-    recipe,
-    manifest,
-    librarySources
-  );
-  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,
-      stdoutIsMachineContract: true
-    }
-  );
-  return { status: result.status === "pass" ? "pass" : "fail" };
-}
-async function prepareHeal(adapter, target, options, json, prepareOptions = {}) {
-  if (recipeRunning(target)) {
-    const msg = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
-    const userAction = `inspect the checkout state with: mm-harness status --target ${shellQuoteArg(target)} --json; retry after the active recipe finishes`;
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: false,
-            error: { code: "RECIPE_RUNNING", message: msg, userAction }
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`\u2717 mm-harness: ${msg}
-  Next: ${userAction}`);
-    }
-    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 runtimeCheck = getAdapterSurface(adapter).run?.runtimeCheck?.({
-    target,
-    options,
-    heal,
-    state,
-    json,
-    appRestartAuthored: prepareOptions.appRestartAuthored,
-    onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
-  });
-  prepareOptions.onPhase?.("install");
-  const ensured = await ensureOverlay(
-    adapter,
-    target,
-    heal,
-    state,
-    json
-  );
-  if (!ensured.ok) {
-    const userAction = `mm-harness install --adapter ${adapter} --target ${shellQuoteArg(target)}`;
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: false,
-            mutations: state.mutations,
-            error: {
-              code: "OVERLAY_INSTALL_FAILED",
-              message: ensured.error,
-              userAction
-            }
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(
-        `\u2717 overlay auto-ensure failed: ${ensured.error}
-  Next: ${userAction}`
-      );
-    }
-    return EXIT.infra;
-  }
-  prepareOptions.onPhase?.("healthcheck");
-  if (runtimeCheck) {
-    const current = await runtimeCheck();
-    if (current !== null) return current;
-  }
-  return { state, heal };
-}
-async function ensureMobileProofRuntime(target, _heal, state, json, deps = {}) {
-  const source = await import("../adapters/mobile/source-freshness.js");
-  const check = deps.check ?? (() => source.mobileSourceCheck(target));
-  const initial = check();
-  if (initial.status === "unavailable") {
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: false,
-            error: initial.error
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`\u2717 ${initial.error.message}`);
-      console.error(`  Next: ${initial.error.userAction}`);
-    }
-    return EXIT.usage;
-  }
-  if (initial.status === "current") return null;
-  const targetArg = JSON.stringify(path.resolve(target));
-  const userAction = `mm-harness call app.lifecycle --arg command=restart --adapter mobile --target ${targetArg}`;
-  const message = `Mobile loaded source is not current (${initial.status}).`;
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          status: "fail",
-          recoverable: true,
-          mutations: state.mutations,
-          error: { code: "MOBILE_SOURCE_NOT_LOADED", message, userAction }
-        },
-        null,
-        2
-      )
-    );
-  } else {
-    console.error(`\u2717 ${message}`);
-    console.error(`  Next: ${userAction}`);
-  }
-  return EXIT.infra;
-}
-async function ensureExtensionProofRuntime(target, heal, state, json, deps = {}) {
-  const decide = deps.decide ?? (async () => {
-    const { decideExtensionReadiness } = await import("../adapters/extension/runtime-decision.js");
-    const port = Number(process.env.CDP_PORT);
-    return decideExtensionReadiness(target, {
-      ...Number.isInteger(port) && port > 0 ? { cdpPort: port } : {},
-      pageMode: "home-or-sidepanel"
-    });
-  });
-  const initial = await decide();
-  if (initial.decision === "ready") return null;
-  if (initial.reasonCode === "release-artifact-identity-invalid" || initial.reasonCode === "release-artifact-runtime-missing" || initial.reasonCode === "release-artifact-runtime-stale") {
-    const message = initial.reasons[0] ?? "The loaded release artifact identity is invalid.";
-    const userAction2 = "rerun runtime-launch with the same artifact source";
-    if (json) {
-      console.log(JSON.stringify({
-        schemaVersion: 1,
-        status: "fail",
-        recoverable: false,
-        error: { code: "RELEASE_ARTIFACT_NOT_CURRENT", message, userAction: userAction2 }
-      }, null, 2));
-    } else {
-      console.error(`\u2717 ${message}`);
-      console.error(`  Next: ${userAction2}`);
-    }
-    return EXIT.infra;
-  }
-  if (initial.reasonCode === "runtime-dist-check-failed") {
-    const message = `Extension proof runtime freshness could not be checked: ${initial.reasons[0] ?? initial.decision}`;
-    const userAction2 = `mm-harness doctor --adapter extension --target ${JSON.stringify(path.resolve(target))}`;
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: false,
-            error: {
-              code: "EXTENSION_RUNTIME_CHECK_FAILED",
-              message,
-              userAction: userAction2
-            }
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`\u2717 ${message}`);
-      console.error(`  Next: ${userAction2}`);
-    }
-    return EXIT.infra;
-  }
-  if (![
-    "dist-stale",
-    "dist-missing",
-    "runtime-dist-stale",
-    "runtime-dist-missing"
-  ].includes(initial.reasonCode)) {
-    return null;
-  }
-  const tier = initial.decision === "build" ? "build" : "quick";
-  const canHeal = heal === "auto" || heal === "infra-only" && tier === "quick";
-  const targetArg = JSON.stringify(path.resolve(target));
-  const userAction = tier === "build" ? `mm-harness launch --build --verify --adapter extension --target ${targetArg}` : `mm-harness launch --verify --adapter extension --target ${targetArg}`;
-  if (!canHeal) {
-    const message = `Extension proof runtime is not current (${initial.reasonCode}): ${initial.reasons[0] ?? initial.decision}`;
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: true,
-            mutations: state.mutations,
-            error: {
-              code: "EXTENSION_RUNTIME_NOT_CURRENT",
-              message,
-              userAction
-            }
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`\u2717 ${message}`);
-      console.error(`  Next: ${userAction}`);
-    }
-    return EXIT.infra;
-  }
-  const recoveryCode = tier === "build" ? "extension.runtime_rebuilt" : "extension.runtime_reloaded";
-  const productConfigBlock = tier === "build" ? extensionProductConfigBlock(target) : null;
-  if (productConfigBlock) {
-    const message = productConfigBlock.message;
-    const userAction2 = productConfigBlock.userAction;
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: false,
-            mutations: state.mutations,
-            error: {
-              code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
-              message,
-              userAction: userAction2
-            }
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`\u2717 ${message}`);
-      console.error(`  Next: ${userAction2}`);
-    }
-    return EXIT.infra;
-  }
-  state.attemptedRecoveries.push(recoveryCode);
-  deps.onRecovery?.(recoveryCode);
-  if (!json)
-    console.error(
-      `\u2192 Extension proof preflight: ${initial.reasonCode}; ${tier === "build" ? "rebuilding" : "reloading"} before execution`
-    );
-  const launch = deps.launch ?? (async (requestedTier) => {
-    const { launchExtension } = await import("./launch/extension.js");
-    const { readExtensionPinnedFlags } = await import("../adapters/extension/feature-flags.js");
-    const { fixtureFeatureFlags, remoteFlagRequestFor } = await import("../feature-flags.js");
-    const { walletFixturePath } = await import("../paths.js");
-    return launchExtension(
-      target,
-      requestedTier,
-      false,
-      "fullscreen",
-      remoteFlagRequestFor(readExtensionPinnedFlags(target).pinned ?? fixtureFeatureFlags(walletFixturePath(target)))
-    );
-  });
-  const result = await launch(tier);
-  const verified = result.status === 0 ? await decide() : initial;
-  if (result.status !== 0 || verified.decision !== "ready") {
-    const message = `Extension runtime recovery did not produce a current healthy runtime (${verified.reasonCode}).`;
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: false,
-            attemptedRecoveries: state.attemptedRecoveries,
-            error: {
-              code: "EXTENSION_RUNTIME_RECOVERY_FAILED",
-              message,
-              userAction,
-              originalError: result.output
-            }
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`\u2717 ${message}`);
-      console.error(`  Next: ${userAction}`);
-    }
-    return EXIT.infra;
-  }
-  state.recovered.push(recoveryCode);
-  state.mutations.push({
-    type: "runtime",
-    action: tier === "build" ? "rebuilt" : "reloaded",
-    reasonCode: initial.reasonCode
-  });
-  return null;
-}
-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, target, state) {
-  const result = await exec();
-  if (result.status === "pass" || result.status === "unknown") return { result, violation: null };
-  return {
-    result,
-    violation: checkHealBounds(target, readRunFailureText(result), state)
-  };
-}
-function emitHealViolation(json, command, result, violation, state, adapter) {
-  const userAction = (adapter ? getAdapterSurface(adapter).run?.violationUserAction?.(violation) : void 0) ?? violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
-  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,
-            originalError: violation.originalError ?? null
-          }
-        },
-        null,
-        2
-      )
-    );
-  } else {
-    const message = violation.code === "APP_LOGIC_FAILURE" && violation.originalError ? conciseFailureForHuman(violation.originalError) : violation.message;
-    console.error(
-      `\u2717 mm-harness ${command}: ${message}` + (violation.originalError && violation.code !== "APP_LOGIC_FAILURE" ? `
-  --- original failure ---
-${violation.originalError}` : "") + (userAction ? `
-  Next: ${userAction}` : "")
-    );
-  }
-  return violation.exitCode;
-}
-function countRecipeNodes(recipe) {
-  if (!isRecord(recipe)) return void 0;
-  const workflow = isRecord(recipe.workflow) ? recipe.workflow : void 0;
-  const nodes = workflow && isRecord(workflow.nodes) ? workflow.nodes : void 0;
-  return nodes ? Object.keys(nodes).length : void 0;
-}
-export {
-  activateRecipeRuntimeEnvironment,
-  countRecipeNodes,
-  describeRunnableRecipe,
-  emitHealViolation,
-  ensureExtensionProofRuntime,
-  ensureMobileProofRuntime,
-  executeWithHealBounds,
-  listRunnableRecipes,
-  persistRunEffects,
-  preflightRecipe,
-  prepareHeal,
-  prepareRuntimeIfNeeded,
-  resolveMetaMaskLibrarySources,
-  resolveRunRecipeArg,
-  runOneNode,
-  runRecipe,
-  synthesizeOneNodeRecipe,
-  validateRecipeAdapterAware,
-  validateRunRecipeStatic
-};