@deeeed/metamask-harness 0.42.0 → 0.44.0

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
 };

package/dist/commands/run.js

@@ -21,6 +21,7 @@ import {
   executeWithHealBounds,
   preflightRecipe,
   prepareHeal,
+  persistRunEffects,
   recoverRunInfra,
   runRecipe,
   validateRunRecipeStatic
@@ -30,11 +31,15 @@ import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { coreDependencyBlock } from "./core-readiness.js";
 import { readMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
-import { writeRunReport } from "./run-report.js";
+import {
+  indexProductProvenanceArtifact,
+  writeRunReport
+} from "./run-report.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
 import { JsonStreamWriter } from "../json-stream.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 import { recipeTrustFailure } from "../recipe-security.js";
+import { ProvenanceDriftError } from "../execution-provenance.js";
 import { recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
 import {
   actionLibraryContextArgs,
@@ -44,6 +49,9 @@ import {
 import {
   startRunNetworkObservation
 } from "../network-observation.js";
+import {
+  startRunPerformanceObservation
+} from "../performance-observation.js";
 async function validationCapabilityRefusals(adapter, findings, librarySources) {
   const actionNames = findings.flatMap((finding) => {
     if (finding.code !== "recipe.action_not_declared_by_manifest") return [];
@@ -72,6 +80,31 @@ async function handleRun(parsed) {
     stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode);
     return exitCode;
   } catch (error) {
+    if (error instanceof ProvenanceDriftError) {
+      const failure = {
+        code: error.code,
+        message: error.message,
+        userAction: error.userAction,
+        provenancePath: error.provenancePath,
+        drift: error.drift
+      };
+      if (stream.enabled) {
+        stream.error(failure);
+        stream.complete("fail", error.exitCode);
+      } else if (optionFlag(parsed.options, "json")) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "run",
+          status: "fail",
+          error: failure,
+          exitCode: error.exitCode
+        }, null, 2));
+      } else {
+        console.error(`\u2717 mm-harness run: ${error.message}`);
+        console.error(`  Next: ${error.userAction}`);
+      }
+      return error.exitCode;
+    }
     const trustFailure = recipeTrustFailure(error);
     if (trustFailure) {
       if (stream.enabled) {
@@ -231,6 +264,7 @@ async function handleRunInner({ positional, options }, stream) {
   recordCommandEvidence(artifactsDir);
   const librarySources = validated.librarySources;
   let networkObservation;
+  let performanceObservation;
   const runtimeOptions = {
     ...runtimeOptionsFromCli(options),
     params,
@@ -239,6 +273,7 @@ async function handleRunInner({ positional, options }, stream) {
     onActionEvent: ({ nodeId, action, status }) => {
       stream.node(nodeId, action, status);
       networkObservation?.onActionEvent({ nodeId, action, status });
+      performanceObservation?.onActionEvent({ nodeId, action, status });
     }
   };
   stream.phase("authorize");
@@ -270,6 +305,14 @@ async function handleRunInner({ positional, options }, stream) {
       return prepared;
     }
     const { state, heal } = prepared;
+    preflightedExecution = await preflightRecipe(
+      adapter,
+      validated.recipeFile,
+      artifactsDir,
+      target,
+      optionString(options, "actionManifest"),
+      runtimeOptions
+    );
     networkObservation = await startRunNetworkObservation(
       adapter,
       target,
@@ -280,6 +323,16 @@ async function handleRunInner({ positional, options }, stream) {
         watcherPort: runtimeOptions.watcherPort
       }
     );
+    performanceObservation = startRunPerformanceObservation(
+      adapter,
+      target,
+      artifactsDir,
+      process.env,
+      {
+        cdpPort: runtimeOptions.cdpPort,
+        watcherPort: runtimeOptions.watcherPort
+      }
+    );
     stream.phase("execute");
     let executionResult;
     try {
@@ -296,7 +349,8 @@ async function handleRunInner({ positional, options }, stream) {
             target,
             optionString(options, "actionManifest"),
             runtimeOptions,
-            execution
+            execution,
+            state
           );
         },
         adapter,
@@ -307,15 +361,25 @@ async function handleRunInner({ positional, options }, stream) {
         (code) => stream.phase("recover", { code })
       );
     } catch (error) {
-      await networkObservation?.finalize();
+      await networkObservation?.finalize().catch(() => void 0);
       networkObservation = void 0;
+      await performanceObservation?.finalize().catch(() => void 0);
+      performanceObservation = void 0;
       throw error;
     }
     const { result, violation } = executionResult;
     await networkObservation?.finalize(result.artifactManifestPath);
     networkObservation = void 0;
+    await performanceObservation?.finalize(result.artifactManifestPath);
+    performanceObservation = void 0;
     for (const mutation of state.mutations) stream.mutation(mutation);
     for (const recovery of state.recovered) stream.recovery(recovery);
+    persistRunEffects(result.summaryPath, result.artifactManifestPath, state);
+    indexProductProvenanceArtifact(
+      result.artifactManifestPath,
+      target,
+      adapter
+    );
     if (violation !== null) {
       const userAction = violation.userAction ?? `inspect ${shellQuote(result.summaryPath)} and ${shellQuote(result.tracePath)}; fix the application or recipe failure before retrying`;
       stream.error({

package/dist/execution-provenance.js

@@ -0,0 +1,342 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs, { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { mobileSourceFingerprint } from "./adapters/mobile/source-freshness.js";
+import { importRecipeProtocol, runnerDir } from "./paths.js";
+const gitContexts = /* @__PURE__ */ new Map();
+let protocolPromise;
+class ProvenanceDriftError extends Error {
+  code = "PROVENANCE_DRIFT";
+  exitCode = 5;
+  userAction;
+  provenancePath;
+  drift;
+  constructor(provenancePath, drift, cause) {
+    const fields = [...new Set(drift.map((entry) => entry.field))].join(", ");
+    super(
+      `Execution inputs changed after preparation (${fields}); evidence is invalid.`,
+      cause === void 0 ? void 0 : { cause }
+    );
+    this.name = "ProvenanceDriftError";
+    this.provenancePath = provenancePath;
+    this.drift = drift;
+    this.userAction = `restore the prepared recipe, library, and product source, then rerun; inspect ${provenancePath}`;
+  }
+}
+async function captureExecutionProvenance(input, phase) {
+  const protocol = await (protocolPromise ??= importRecipeProtocol());
+  const recipeDigest = input.recipePath ? recipeFileDigest(protocol, input.recipePath) : protocol.digestRecipeDocument(input.recipeDocument);
+  const libraries = (input.librarySources ?? []).map((source, index) => ({
+    name: source.name ?? `library-${index + 1}`,
+    ...sourceSnapshot(source.root)
+  }));
+  const runnerRoot = input.runnerRoot ?? runnerDir;
+  return {
+    phase,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    recipeDigest,
+    product: sourceSnapshot(
+      input.projectRoot,
+      input.adapter,
+      input.excludedProductRoots
+    ),
+    runner: sourceSnapshot(runnerRoot, void 0, [], [
+      "src",
+      "adapters",
+      "library",
+      "bin",
+      "dist",
+      "package.json"
+    ]),
+    libraries,
+    helpers: (input.helperPaths ?? []).map((helperPath) => ({
+      path: displayPath(input.projectRoot, helperPath),
+      sourceFingerprint: fileFingerprint(helperPath)
+    }))
+  };
+}
+function executionProvenanceDrift(start, current) {
+  const drift = [];
+  if (current.phase === "start") return drift;
+  const phase = current.phase;
+  compare(drift, phase, "recipeDigest", start.recipeDigest, current.recipeDigest);
+  compareSource(drift, phase, "product", start.product, current.product);
+  compareSource(drift, phase, "runner", start.runner, current.runner);
+  if (start.libraries.length !== current.libraries.length) {
+    compare(
+      drift,
+      phase,
+      "libraries.length",
+      String(start.libraries.length),
+      String(current.libraries.length)
+    );
+  }
+  const count = Math.min(start.libraries.length, current.libraries.length);
+  for (let index = 0; index < count; index += 1) {
+    const expected = start.libraries[index];
+    const actual = current.libraries[index];
+    const prefix = `libraries[${index}]`;
+    compare(drift, phase, `${prefix}.name`, expected.name, actual.name);
+    compareSource(drift, phase, prefix, expected, actual);
+  }
+  if (start.helpers.length !== current.helpers.length) {
+    compare(
+      drift,
+      phase,
+      "helpers.length",
+      String(start.helpers.length),
+      String(current.helpers.length)
+    );
+  }
+  const helperCount = Math.min(start.helpers.length, current.helpers.length);
+  for (let index = 0; index < helperCount; index += 1) {
+    compare(drift, phase, `helpers[${index}].path`, start.helpers[index].path, current.helpers[index].path);
+    compare(
+      drift,
+      phase,
+      `helpers[${index}].sourceFingerprint`,
+      start.helpers[index].sourceFingerprint,
+      current.helpers[index].sourceFingerprint
+    );
+  }
+  return drift;
+}
+function writeExecutionProvenance(artifactsDir, snapshots, drift, artifactManifestPath) {
+  const provenancePath = path.join(path.resolve(artifactsDir), "execution-provenance.json");
+  const record = {
+    schemaVersion: 1,
+    valid: drift.length === 0,
+    snapshots,
+    drift
+  };
+  fs.mkdirSync(path.dirname(provenancePath), { recursive: true });
+  fs.writeFileSync(provenancePath, `${JSON.stringify(record, null, 2)}
+`);
+  if (artifactManifestPath) indexProvenanceArtifact(artifactManifestPath, record);
+  return provenancePath;
+}
+function recipeFileDigest(protocol, recipePath) {
+  const source = readRegularFileNoFollow(recipePath);
+  try {
+    return protocol.digestRecipeDocument(JSON.parse(source.toString("utf8")));
+  } catch {
+    return `invalid:sha256:${createHash("sha256").update(source).digest("hex")}`;
+  }
+}
+function sourceSnapshot(root, adapter, excludedRoots = [], includedRoots = []) {
+  const git = gitContext(root);
+  if (!git) {
+    return {
+      head: null,
+      status: "not-a-git-checkout",
+      sourceFingerprint: directoryFingerprint(root, excludedRoots, includedRoots)
+    };
+  }
+  const pathspecs = sourcePathspecs(git, excludedRoots, includedRoots);
+  const status = gitText(git.topLevel, [
+    "status",
+    "--porcelain=v1",
+    "--untracked-files=normal",
+    "--",
+    ...pathspecs
+  ]);
+  return {
+    head: gitText(git.topLevel, ["rev-parse", "HEAD"]).trim() || null,
+    status,
+    sourceFingerprint: adapter === "mobile" && path.resolve(root) === git.topLevel ? mobileSourceFingerprint(root) : nestedGitSourceFingerprint(root, git, pathspecs, excludedRoots, includedRoots)
+  };
+}
+function nestedGitSourceFingerprint(root, git, pathspecs, excludedRoots, includedRoots) {
+  const gitFingerprint = gitSourceFingerprint(git.topLevel, pathspecs);
+  if (git.pathspec === "." && includedRoots.length === 0) return gitFingerprint;
+  return createHash("sha256").update(gitFingerprint).update("\0nested-source\0").update(directoryFingerprint(root, excludedRoots, includedRoots)).digest("hex");
+}
+function gitContext(root) {
+  const cacheKey = path.resolve(root);
+  if (gitContexts.has(cacheKey)) return gitContexts.get(cacheKey) ?? null;
+  try {
+    const resolved = cacheKey;
+    const topLevel = fs.realpathSync(
+      gitText(resolved, ["rev-parse", "--show-toplevel"]).trim()
+    );
+    const relative = path.relative(topLevel, fs.realpathSync(resolved));
+    const context = relative === ".." || relative.startsWith(`..${path.sep}`) ? null : { topLevel, pathspec: relative || "." };
+    gitContexts.set(cacheKey, context);
+    return context;
+  } catch {
+    gitContexts.set(cacheKey, null);
+    return null;
+  }
+}
+function gitSourceFingerprint(topLevel, pathspecs) {
+  const hash = createHash("sha256");
+  hash.update(gitBuffer(topLevel, ["rev-parse", "HEAD"]));
+  hash.update("\0diff\0");
+  hash.update(
+    gitBuffer(topLevel, [
+      "diff",
+      "--no-ext-diff",
+      "--binary",
+      "HEAD",
+      "--",
+      ...pathspecs
+    ])
+  );
+  const untracked = gitText(topLevel, [
+    "ls-files",
+    "--others",
+    "--exclude-standard",
+    "-z",
+    "--",
+    ...pathspecs
+  ]).split("\0").filter(Boolean).sort();
+  for (const relative of untracked) {
+    hash.update(`\0untracked\0${relative}\0`);
+    const absolute = path.join(topLevel, relative);
+    hash.update(readPathIdentity(absolute));
+  }
+  return hash.digest("hex");
+}
+function sourcePathspecs(git, excludedRoots, includedRoots) {
+  const exclusions = excludedRoots.flatMap((root) => {
+    const relative = path.relative(git.topLevel, path.resolve(root));
+    return relative !== ".." && !relative.startsWith(`..${path.sep}`) ? [`:(exclude)${relative}`] : [];
+  });
+  const inclusions = includedRoots.length > 0 ? includedRoots.map((root) => path.join(git.pathspec === "." ? "" : git.pathspec, root)) : [git.pathspec];
+  return [...inclusions, ...exclusions];
+}
+function directoryFingerprint(root, excludedRoots, includedRoots) {
+  const hash = createHash("sha256");
+  const resolvedRoot = path.resolve(root);
+  const roots = includedRoots.length > 0 ? includedRoots : [""];
+  for (const included of roots) {
+    hashDirectory(
+      hash,
+      resolvedRoot,
+      included,
+      new Set(excludedRoots.map((entry) => path.resolve(entry)))
+    );
+  }
+  return hash.digest("hex");
+}
+function hashDirectory(hash, root, relative, excludedRoots) {
+  const absolute = path.join(root, relative);
+  if ([...excludedRoots].some(
+    (excluded) => absolute === excluded || absolute.startsWith(`${excluded}${path.sep}`)
+  )) return;
+  let stat;
+  try {
+    stat = fs.lstatSync(absolute);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      hash.update(`absent\0${relative}\0`);
+      return;
+    }
+    throw error;
+  }
+  if (stat.isDirectory()) {
+    hash.update(`directory\0${relative}\0`);
+    for (const name of fs.readdirSync(absolute).sort()) {
+      if (relative === "" && (name === ".git" || name === "node_modules" || name === "temp")) continue;
+      hashDirectory(hash, root, path.join(relative, name), excludedRoots);
+    }
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Execution provenance source must not be a symbolic link: ${absolute}`);
+  }
+  hash.update(`file\0${relative}\0`);
+  hash.update(readRegularFileNoFollow(absolute));
+  hash.update("\0");
+}
+function fileFingerprint(filePath) {
+  return createHash("sha256").update(readRegularFileNoFollow(filePath)).digest("hex");
+}
+function readPathIdentity(filePath) {
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Execution provenance source must not be a symbolic link: ${filePath}`);
+  }
+  return readRegularFileNoFollow(filePath);
+}
+function readRegularFileNoFollow(filePath) {
+  let fd;
+  try {
+    fd = fs.openSync(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+  } catch (error) {
+    if (error.code === "ELOOP") {
+      throw new Error(`Execution provenance source must not be a symbolic link: ${filePath}`);
+    }
+    throw error;
+  }
+  try {
+    if (!fs.fstatSync(fd).isFile()) {
+      throw new Error(`Execution provenance source is not a regular file: ${filePath}`);
+    }
+    return fs.readFileSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function displayPath(projectRoot, filePath) {
+  const relative = path.relative(path.resolve(projectRoot), path.resolve(filePath));
+  return relative !== ".." && !relative.startsWith(`..${path.sep}`) ? relative || "." : path.resolve(filePath);
+}
+function gitText(cwd, args) {
+  return gitBuffer(cwd, args).toString("utf8");
+}
+function gitBuffer(cwd, args) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "buffer",
+    maxBuffer: 128 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+}
+function compareSource(drift, phase, prefix, start, current) {
+  compare(drift, phase, `${prefix}.head`, start.head, current.head);
+  compare(drift, phase, `${prefix}.status`, start.status, current.status);
+  compare(
+    drift,
+    phase,
+    `${prefix}.sourceFingerprint`,
+    start.sourceFingerprint,
+    current.sourceFingerprint
+  );
+}
+function compare(drift, phase, field, start, current) {
+  if (start !== current) drift.push({ phase, field, start, current });
+}
+function indexProvenanceArtifact(artifactManifestPath, record) {
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(artifactManifestPath, "utf8"));
+  } catch {
+    return;
+  }
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return;
+  const document = manifest;
+  const artifacts = Array.isArray(document.artifacts) ? document.artifacts : [];
+  document.artifacts = [
+    ...artifacts.filter((artifact) => !artifact || typeof artifact !== "object" || Array.isArray(artifact) || artifact.path !== "execution-provenance.json"),
+    {
+      path: "execution-provenance.json",
+      type: "json",
+      label: "Execution provenance",
+      category: "system",
+      metadata: {
+        valid: record.valid,
+        errorCode: record.valid ? null : "PROVENANCE_DRIFT"
+      }
+    }
+  ];
+  fs.writeFileSync(artifactManifestPath, `${JSON.stringify(document, null, 2)}
+`);
+}
+export {
+  ProvenanceDriftError,
+  captureExecutionProvenance,
+  executionProvenanceDrift,
+  writeExecutionProvenance
+};