@deeeed/metamask-harness 0.43.0 → 0.44.0

package/dist/commands/run-engine.js

@@ -28,6 +28,12 @@ import {
   validateMetaMaskActionInputs
 } from "../metamask-action-validation.js";
 import { gitLibraryProvenance } from "../library-provenance.js";
+import {
+  captureExecutionProvenance,
+  executionProvenanceDrift,
+  ProvenanceDriftError,
+  writeExecutionProvenance
+} from "../execution-provenance.js";
 import {
   authorizeTrustedMutationPlan,
   loadTrustedMutationBase
@@ -36,7 +42,7 @@ import {
   beginRunDiagnostics,
   finishRunDiagnostics
 } from "../run-diagnostics.js";
-import { EXIT, spawnScriptStreaming } from "./shared.js";
+import { EXIT } from "./shared.js";
 import {
   actionManifestPathOption,
   optionString,
@@ -46,13 +52,14 @@ import {
   targetPath,
   usageError
 } from "./parse-args.js";
-async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}, preflightedExecution) {
+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,
@@ -65,27 +72,48 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
       runner,
       runRequest,
       absoluteArtifactsDir,
-      useFramedExtensionRecording
+      useFramedExtensionRecording,
+      provenanceInput,
+      provenanceSnapshots
     } = execution;
-    await runner.preflight(runRequest);
+    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 = 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 (recordingError) {
+      } catch (recordingError2) {
         console.error(
-          `WARN: recipe and video recording both failed; preserving recipe failure: ${recordingError instanceof Error ? recordingError.message : String(recordingError)}`
+          `WARN: recipe and video recording both failed; preserving recipe failure: ${recordingError2 instanceof Error ? recordingError2.message : String(recordingError2)}`
         );
       }
-      throw error;
     } finally {
       if (adapter === "mobile") {
         const { hideMobileHudOnTeardown } = await import("../adapters.js");
@@ -95,8 +123,36 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         );
       }
     }
-    await stopRecipeRecording(recording, result);
-    return finishRunDiagnostics(diagnosticBaseline, result);
+    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 = 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 = finishRunDiagnostics(diagnosticBaseline, result);
+    persistRunEffects(
+      finalized.summaryPath,
+      finalized.artifactManifestPath,
+      effectsState
+    );
+    return finalized;
   } finally {
     restoreRuntimeEnvironment();
   }
@@ -122,6 +178,23 @@ async function preflightRecipe(adapter, recipe, artifactsDir, projectRoot, actio
     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;
@@ -173,7 +246,7 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
   });
   const useFramedExtensionRecording = adapter === "extension" && recordVideo === "full-run" && trust.source?.trust !== "untrusted" && trust.source?.trust !== "unknown" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
   const runRequest = {
-    ...absoluteRecipePath ? { recipePath: absoluteRecipePath } : { recipeDocument: recipe },
+    ...recipeDocument !== void 0 ? { recipeDocument } : absoluteRecipePath ? { recipePath: absoluteRecipePath } : { recipeDocument: recipe },
     artifactsDir: absoluteArtifactsDir,
     projectRoot,
     inheritProcessEnv: false,
@@ -196,12 +269,138 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
       trustedMutation: authorizedMutation
     });
   }
+  const provenanceInput = {
+    adapter,
+    projectRoot,
+    recipeDocument: recipeDocument ?? recipe,
+    ...absoluteRecipePath ? { recipePath: absoluteRecipePath } : {},
+    ...librarySources ? { librarySources } : {},
+    excludedProductRoots: [absoluteArtifactsDir],
+    helperPaths: commandHelperPaths(recipeDocument ?? recipe, projectRoot)
+  };
+  const startProvenance = await captureExecutionProvenance(
+    provenanceInput,
+    "start"
+  );
   return {
     runner,
     absoluteArtifactsDir,
     useFramedExtensionRecording,
-    runRequest
+    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;
@@ -938,19 +1137,15 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
       target,
       heal,
       state,
-      json,
-      {
-        onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
-      }
+      json
     );
     if (current !== null) return current;
   }
   return { state, heal };
 }
-async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
+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 record = deps.record ?? ((fingerprint) => source.recordMobileSourceBaseline(target, fingerprint));
   const initial = check();
   if (initial.status === "unavailable") {
     if (json) {
@@ -975,99 +1170,26 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
   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}`;
-  if (heal === "off") {
-    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;
-  }
-  const recoveryCode = "mobile.source_reloaded";
-  state.attemptedRecoveries.push(recoveryCode);
-  deps.onRecovery?.(recoveryCode);
-  if (!json)
-    console.error(
-      `\u2192 Mobile proof preflight: source ${initial.status}; restarting the app before execution`
-    );
-  const restart = deps.restart ?? (async () => {
-    const result2 = await runOneNode(
-      "mobile",
-      "app.lifecycle",
-      { command: "restart" },
-      target,
-      void 0
+  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
+      )
     );
-    return {
-      status: result2.status === "pass" ? 0 : EXIT.runtime,
-      output: result2.status
-    };
-  });
-  const result = await restart();
-  const platform = resolveRunMobilePlatform();
-  const bridge = result.status === 0 ? await (deps.waitForBridge ? deps.waitForBridge() : spawnScriptStreaming(
-    path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh"),
-    ["--target", target, "--platform", platform],
-    target
-  )) : { status: result.status, output: result.output };
-  const recorded = result.status === 0 && bridge.status === 0 && record(initial.fingerprint);
-  const verified = recorded ? check() : initial;
-  if (result.status !== 0 || bridge.status !== 0 || !recorded || verified.status !== "current") {
-    const message = bridge.status !== 0 ? "Mobile source restart completed but the platform-matched bridge did not become ready." : "Mobile source restart did not produce a current loaded-source baseline.";
-    if (json) {
-      console.log(
-        JSON.stringify(
-          {
-            schemaVersion: 1,
-            status: "fail",
-            recoverable: false,
-            attemptedRecoveries: state.attemptedRecoveries,
-            error: {
-              code: bridge.status !== 0 ? "MOBILE_BRIDGE_NOT_READY" : "MOBILE_SOURCE_RELOAD_FAILED",
-              message,
-              userAction,
-              originalError: bridge.output || result.output
-            }
-          },
-          null,
-          2
-        )
-      );
-    } else {
-      console.error(`\u2717 ${message}`);
-      console.error(
-        `  Next: ${bridge.status !== 0 ? "inspect the bridge-status log and rerun mm-harness launch <platform>" : userAction}`
-      );
-    }
-    return EXIT.infra;
-  }
-  state.recovered.push(recoveryCode);
-  state.mutations.push({
-    type: "runtime",
-    action: "restarted",
-    reasonCode: `source-${initial.status}`
-  });
-  return null;
-}
-function resolveRunMobilePlatform() {
-  if (process.env.PLATFORM === "android" || process.env.PLATFORM === "ios") {
-    return process.env.PLATFORM;
+  } else {
+    console.error(`\u2717 ${message}`);
+    console.error(`  Next: ${userAction}`);
   }
-  return process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
+  return EXIT.infra;
 }
 async function ensureExtensionProofRuntime(target, heal, state, json, deps = {}) {
   const decide = deps.decide ?? (async () => {
@@ -1263,26 +1385,10 @@ async function recoverRunInfra(adapter, target, json, runtimeOptions = {}) {
       return launchExtension(target, "quick", false);
     }
     if (adapter === "mobile") {
-      try {
-        const artifact = requireCurrentMobileReleaseArtifactState(target);
-        if (artifact) {
-          const { relaunchAndroidReleaseArtifactRuntime } = await import("../adapters/mobile/release-artifact.js");
-          await relaunchAndroidReleaseArtifactRuntime(artifact);
-          return {
-            status: 0,
-            output: `Relaunched ${artifact.packageId} ${artifact.versionName} (${artifact.versionCode}) on ${artifact.deviceSerial}.`
-          };
-        }
-      } catch (error) {
-        return {
-          status: 1,
-          output: `Release artifact recovery could not revalidate and relaunch the pinned Android package: ${error instanceof Error ? error.message : String(error)}
-Next: rerun runtime-launch with the same artifact source.`
-        };
-      }
-      const { launchMobile } = await import("./launch/mobile.js");
-      const platform = resolveMobileRecoveryPlatform();
-      return launchMobile(target, platform, "quick", json);
+      return {
+        status: 1,
+        output: "Automatic Mobile runtime recovery is disabled.\nNext: use an explicit app.lifecycle action when the recipe intends to relaunch the app."
+      };
     }
     return { status: 0, output: "headless run retry" };
   } finally {
@@ -1290,15 +1396,6 @@ Next: rerun runtime-launch with the same artifact source.`
     restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
   }
 }
-function resolveMobileRecoveryPlatform(env = process.env) {
-  if (env.PLATFORM === "android" || env.PLATFORM === "ios") return env.PLATFORM;
-  const androidPinned = Boolean(
-    env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_TARGET_DEVICE_NAME || env.ANDROID_DEVICE
-  );
-  const iosPinned = Boolean(env.IOS_SIMULATOR || env.SIM_UDID);
-  if (androidPinned && !iosPinned) return "android";
-  return "ios";
-}
 function readRunFailureText(result) {
   try {
     const trace = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
@@ -1320,11 +1417,22 @@ async function executeWithHealBounds(exec, adapter, target, heal, state, recover
       state
     );
     if (violation !== null) return { result, violation };
+    if (adapter === "mobile") return { result, violation: null };
     if (heal === "off") return { result, violation: null };
     const recoveryCode = RUN_RECOVERY_CODE[adapter];
     state.attemptedRecoveries.push(recoveryCode);
     onRecovery(recoveryCode);
-    await recover();
+    const recovery = await recover();
+    if (recovery.status !== 0) {
+      return { result, violation: null };
+    }
+    if (adapter === "extension") {
+      state.mutations.push({
+        type: "runtime",
+        action: "reloaded",
+        reasonCode: recoveryCode
+      });
+    }
     result = await exec();
     if (result.status === "pass") {
       state.recovered.push(recoveryCode);
@@ -1387,12 +1495,12 @@ export {
   ensureMobileProofRuntime,
   executeWithHealBounds,
   listRunnableRecipes,
+  persistRunEffects,
   preflightRecipe,
   prepareHeal,
   prepareRuntimeIfNeeded,
   recoverRunInfra,
   resolveMetaMaskLibrarySources,
-  resolveMobileRecoveryPlatform,
   resolveRunRecipeArg,
   runOneNode,
   runRecipe,

package/dist/commands/run-report.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { isRecord } from "./parse-args.js";
 function writeRunReport(result) {
   const summaryPath = String(result.summaryPath);
@@ -19,6 +20,72 @@ function writeRunReport(result) {
     preview: lines.filter((line) => line.startsWith("- ")).slice(0, 6).map((line) => line.slice(2))
   };
 }
+function indexProductProvenanceArtifact(artifactManifestPath, target, adapter) {
+  const artifactsDir = path.dirname(artifactManifestPath);
+  let gitRef = "unknown";
+  let branch = "unknown";
+  let dirty = true;
+  try {
+    gitRef = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: target,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    branch = execFileSync("git", ["branch", "--show-current"], {
+      cwd: target,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim() || "detached";
+    dirty = execFileSync(
+      "git",
+      ["status", "--porcelain", "--untracked-files=normal"],
+      {
+        cwd: target,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }
+    ).trim().length > 0;
+  } catch {
+  }
+  const provenance = {
+    schemaVersion: 1,
+    adapter,
+    repository: path.basename(path.resolve(target)),
+    git_ref: gitRef,
+    branch,
+    dirty
+  };
+  fs.writeFileSync(
+    path.join(artifactsDir, "product-provenance.json"),
+    `${JSON.stringify(provenance, null, 2)}
+`
+  );
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(artifactManifestPath, "utf8"));
+  } catch {
+    return;
+  }
+  if (!isRecord(manifest)) return;
+  const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+  manifest.artifacts = [
+    ...artifacts.filter(
+      (artifact) => !isRecord(artifact) || artifact.path !== "product-provenance.json"
+    ),
+    {
+      path: "product-provenance.json",
+      type: "json",
+      label: "Product checkout provenance",
+      category: "system",
+      metadata: { adapter, git_ref: gitRef, branch, dirty }
+    }
+  ];
+  fs.writeFileSync(
+    artifactManifestPath,
+    `${JSON.stringify(manifest, null, 2)}
+`
+  );
+}
 function renderRunReport(summary, entries) {
   const lines = [
     "# MetaMask Recipe Run",
@@ -120,5 +187,6 @@ function indexRunReportArtifact(artifactManifestPath) {
 `);
 }
 export {
+  indexProductProvenanceArtifact,
   writeRunReport
 };