@deeeed/metamask-harness 0.15.2 → 0.17.0

package/dist/commands/stop.js

@@ -5,7 +5,8 @@ import {
   parseArgs,
   optionFlag,
   optionString,
-  resolveAdapter
+  resolveAdapter,
+  shellQuote
 } from "./parse-args.js";
 async function handleStop(argv) {
   const { options } = parseArgs(argv, "stop");
@@ -22,6 +23,8 @@ async function handleStop(argv) {
   if (stop.kind === "headless") {
     return usageOut(json, "stop", stop.message, stop.userAction);
   }
+  const next = adapter === "extension" ? `${surface.hints.launch} --target ${shellQuote(target)}` : void 0;
+  const userAction = `mm-harness status --target ${shellQuote(target)} --json`;
   if (json) {
     console.log(
       JSON.stringify(
@@ -33,7 +36,8 @@ async function handleStop(argv) {
           status: stop.status === 0 ? "pass" : "fail",
           ...stop.signalled !== void 0 ? { signalled: stop.signalled } : {},
           exitCode: stop.status,
-          ...stop.output ? { output: stop.output } : {}
+          ...stop.output ? { output: stop.output } : {},
+          ...stop.status === 0 ? next ? { next } : {} : { error: { code: "DEV_SERVER_STOP_FAILED", message: stop.summary, userAction } }
         },
         null,
         2
@@ -43,6 +47,7 @@ async function handleStop(argv) {
     if (stop.output) process.stderr.write(`${stop.output}
 `);
     console.error(`${color(stop.status === 0 ? "ok" : "err", stop.status === 0 ? "\u2713" : "\u2717")} ${stop.summary}`);
+    if (stop.status !== 0 || next) console.error(`  Next: ${stop.status === 0 ? next : userAction}`);
   }
   return stop.status;
 }

package/dist/harness.js

@@ -50,6 +50,12 @@ function failureHint(adapter, action) {
   const helper = adapter === "mobile" ? "mm-harness launch ios   # or launch android" : "mm-harness launch";
   return `Read the error above for the specific cause. To (re)start the runtime, run: ${helper}`;
 }
+function successNext(adapter, action, target) {
+  const base = `--adapter ${adapter} --target ${shellQuote(target)}`;
+  if (action === "install") return `mm-harness verify ${base}`;
+  if (action === "cleanup") return `mm-harness install ${base}`;
+  return `mm-harness status --target ${shellQuote(target)} --json`;
+}
 function hasArg(args, needle) {
   return args.some((arg) => arg === needle || arg.startsWith(`${needle}=`));
 }
@@ -347,7 +353,8 @@ async function handleMobileLive(target, forwardArgs, json, autoDetected) {
       )
     );
   } else if (exitCode === 0) {
-    console.error(`\u2713 live mobile passed (${elapsed}s)`);
+    console.error(`\u2713 live mobile passed (${elapsed}s)
+  Next: ${successNext("mobile", "live", target)}`);
   } else {
     console.error(
       `\u2717 live mobile failed (exit ${exitCode}, ${elapsed}s)
@@ -492,7 +499,8 @@ async function handleHarness(argv) {
       )
     );
   } else if (exitCode === 0) {
-    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)`);
+    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)
+  Next: ${successNext(adapter, harnessAction, target)}`);
   } else {
     console.error(`\u2717 ${harnessAction} ${adapter} failed (exit ${exitCode}, ${seconds}s)
   ${failureHint(adapter, harnessAction)}`);
@@ -522,8 +530,10 @@ async function handleRunwayInstall(adapter, target, forward, json) {
     resolveOnly: hasArg(forward, "--resolve-only"),
     rerunCommand
   });
+  const next = result.status === "pass" && adapter === "mobile" && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? "ios")} --adapter mobile --target ${shellQuote(target)}` : void 0;
+  const output = next ? { ...result, next } : result;
   if (json) {
-    console.log(JSON.stringify(result, null, 2));
+    console.log(JSON.stringify(output, 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;
@@ -534,6 +544,7 @@ async function handleRunwayInstall(adapter, target, forward, json) {
       const action = result.skipped ? "already provisioned" : "installed Runway app";
       console.error(`\u2713 ${action} for ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "skip"}`);
     }
+    if (next) console.error(`  Next: ${next}`);
   } else {
     console.error(`\u2717 mm-harness install --runway: ${result.error?.message ?? "runway install failed"}
   Next: ${result.error?.userAction ?? rerunCommand}`);
@@ -578,7 +589,8 @@ function harnessSummary(action, adapter, target, status, exitCode, autoDetected,
     // Error contract: every --json failure carries a stable machine code + human
     // message (CLI-SPEC.md §5.1). userAction is included when present so callers
     // can surface the reachable escape without parsing the human message.
-    ...status === "fail" && error ? { error } : {}
+    ...status === "fail" && error ? { error } : {},
+    ...status === "pass" && adapter ? { next: successNext(adapter, action, target) } : {}
   });
 }
 export {

package/dist/json-stream.js

@@ -0,0 +1,57 @@
+class JsonStreamWriter {
+  enabled;
+  command;
+  completed = false;
+  writeLine;
+  constructor(command, enabled, output = process.stdout) {
+    this.command = command;
+    this.enabled = enabled;
+    const write = output.write.bind(output);
+    this.writeLine = (line) => {
+      write(`${line}
+`);
+    };
+  }
+  isolateStdout() {
+    if (!this.enabled) return () => void 0;
+    const original = process.stdout.write;
+    const redirect = ((chunk, encoding, callback) => process.stderr.write(chunk, encoding, callback));
+    process.stdout.write = redirect;
+    return () => {
+      if (process.stdout.write === redirect) process.stdout.write = original;
+    };
+  }
+  emit(event, fields = {}) {
+    if (!this.enabled || this.completed) return;
+    this.writeLine(JSON.stringify({
+      schemaVersion: 1,
+      command: this.command,
+      event,
+      ...fields,
+      ts: (/* @__PURE__ */ new Date()).toISOString()
+    }));
+  }
+  phase(phase, fields = {}) {
+    this.emit("phase", { phase, ...fields });
+  }
+  node(nodeId, action, status) {
+    this.emit("node", { nodeId, action, status });
+  }
+  mutation(mutation) {
+    this.emit("mutation", { mutation });
+  }
+  recovery(code) {
+    this.emit("recovery", { code });
+  }
+  error(error) {
+    this.emit("error", { error });
+  }
+  complete(status, exitCode, fields = {}) {
+    if (!this.enabled || this.completed) return;
+    this.emit("complete", { status, exitCode, ...fields });
+    this.completed = true;
+  }
+}
+export {
+  JsonStreamWriter
+};

package/dist/mm-harness-cli.js

@@ -4,10 +4,17 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { color } from "./cli-color.js";
+import { withCommandJournal } from "./command-journal.js";
+import { JsonStreamWriter } from "./json-stream.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
 import { handleCallHelp } from "./commands/call.js";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { detectAdapter } from "./harness.js";
+import {
+  PUBLIC_COMMAND_CONTRACTS,
+  publicCommandNames,
+  validatePublicInvocation
+} from "./command-contract.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
@@ -71,11 +78,14 @@ Example:
     name: "actions",
     summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
     example: "mm-harness actions --adapter mobile",
-    helpText: `mm-harness actions [flags]
+    helpText: `mm-harness actions [query] [flags]
 
   List the action vocabulary + field schemas for the checkout adapter.
 
+  query                              Search names, categories, fields, and descriptions (typo-tolerant)
   --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
+  --categories                       List compact action categories and counts
+  --category <name>                  List only one category (for example ui, wallet, or perps)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --raw                              Dump raw action registry JSON
@@ -83,6 +93,9 @@ Example:
 
 Example:
   mm-harness actions --adapter mobile
+  mm-harness actions positions --adapter mobile
+  mm-harness actions --adapter mobile --categories --json
+  mm-harness actions --adapter mobile --category ui --json
   mm-harness actions --adapter mobile --action assert_orders
   mm-harness actions --adapter extension --raw`
   },
@@ -172,12 +185,29 @@ Example:
   --library <name=path>              Add/override a recipe-library source (repeatable)
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
+  --json-stream                      Line-flushed JSONL progress + terminal event
   --record-video=full-run            Record a video of the run
 
 Example:
   mm-harness run recipe.json --plan --adapter mobile
   mm-harness run recipe.json --adapter extension --artifacts-dir ./out`
   },
+  {
+    name: "last",
+    summary: "Show the last significant command, verdict, timestamps, and evidence paths for this checkout.",
+    example: "mm-harness last --json",
+    helpText: `mm-harness last [flags]
+
+  Read the atomic per-checkout resumability journal. Discovery commands do not
+  replace it, and an interrupted process remains recorded as verdict=running.
+
+  --target <path>                    Checkout path (default: cwd)
+  --runtime-dir <dir>                Runtime dir containing last-command.json
+  --json                             Machine-readable envelope
+
+Example:
+  mm-harness last --json`
+  },
   {
     name: "doctor",
     summary: "Readiness check for a checkout \u2014 no app launch. --fix repairs the overlay/runtime without launching.",
@@ -375,6 +405,7 @@ Example:
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable summary (recovered[] / mutations[] / phase)
+  --json-stream                      Line-flushed JSONL progress + terminal event
 
 Example:
   mm-harness launch ios
@@ -473,6 +504,7 @@ Example:
   --cdp-port <port>                  finalize: CDP port of the running extension
   --extension-dir <path>             finalize: loaded extension dist (e.g. dist/chrome)
   --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
+  --action-manifest <path>           Extension set: override the wallet action manifest
   --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --device <udid|serial|name>        Mobile only: target this device for sync/set
@@ -487,6 +519,28 @@ Example:
   mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`
   }
 ];
+const PUBLIC_COMMAND_EXAMPLES = Object.fromEntries(
+  REAL.map((command) => [command.name, command.example])
+);
+function assertPublicContractMatchesSurface() {
+  const registered = REAL.map((command) => command.name).sort();
+  const contracted = publicCommandNames().sort();
+  if (registered.join("\n") !== contracted.join("\n")) {
+    throw new Error(
+      `public command contract drift: registered=[${registered.join(", ")}], contracted=[${contracted.join(", ")}]`
+    );
+  }
+  for (const command of REAL) {
+    const registeredAliases = [...command.aliases ?? []].sort();
+    const contractedAliases = [...PUBLIC_COMMAND_CONTRACTS[command.name]?.aliases ?? []].sort();
+    if (registeredAliases.join("\n") !== contractedAliases.join("\n")) {
+      throw new Error(
+        `public command alias contract drift for ${command.name}: registered=[${registeredAliases.join(", ")}], contracted=[${contractedAliases.join(", ")}]`
+      );
+    }
+  }
+}
+assertPublicContractMatchesSurface();
 const RETIRED = [
   {
     name: "live",
@@ -516,7 +570,7 @@ const HELP_GROUPS = [
   {
     title: "PROVE",
     blurb: "run recipes and inspect readiness",
-    commands: ["run", "doctor", "check", "checklist", "recipe-quality"]
+    commands: ["run", "last", "doctor", "check", "checklist", "recipe-quality"]
   },
   {
     title: "RUNTIME OVERLAY",
@@ -639,7 +693,7 @@ for (const command of REAL) {
       process.exit(await handleUpdate(rawArgv.slice(1)));
     }
     const argv = command.name === "actions" && rawArgv.includes("--raw") ? translateActionsRaw(rawArgv) : rawArgv;
-    process.exit(await delegate(argv));
+    process.exit(await withCommandJournal(command.name, rawArgv, () => delegate(argv)));
   });
 }
 const HIDDEN = [
@@ -692,10 +746,67 @@ function isCallActionHelp(argv) {
   const scope = divider === -1 ? argv : argv.slice(0, divider);
   return scope.includes("--help") || scope.includes("-h");
 }
+function jsonRequestedBeforePassthrough(argv) {
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.some((argument) => argument === "--json" || argument.startsWith("--json="));
+}
+function jsonStreamRequestedBeforePassthrough(argv) {
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.includes("--json-stream");
+}
+function emitUsageError(error, json, jsonStream) {
+  if (jsonStream) {
+    const stream = new JsonStreamWriter(error.command, true);
+    stream.error({ code: error.code, message: error.message, userAction: error.userAction });
+    stream.complete("fail", 2);
+  } else if (json) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: error.command,
+          status: "fail",
+          error: {
+            code: error.code,
+            message: error.message,
+            userAction: error.userAction
+          },
+          exitCode: 2
+        },
+        null,
+        2
+      )}
+`
+    );
+  } else {
+    const scope = error.command === "mm-harness" ? "" : ` ${error.command}`;
+    process.stderr.write(`\u2717 mm-harness${scope}: ${error.message}
+  Next: ${error.userAction}
+`);
+  }
+  process.exit(2);
+}
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
 }
+const preflightBypass = /* @__PURE__ */ new Set([
+  ...HIDDEN,
+  "completions",
+  ...RETIRED.map((command) => command.name)
+]);
+if (!preflightBypass.has(rawArgv[0] ?? "")) {
+  const usageError = validatePublicInvocation(rawArgv, PUBLIC_COMMAND_EXAMPLES);
+  if (usageError) {
+    emitUsageError(
+      usageError,
+      jsonRequestedBeforePassthrough(rawArgv),
+      jsonStreamRequestedBeforePassthrough(rawArgv)
+    );
+  }
+}
 if (hasPassthroughHelp(rawArgv)) {
   process.exit(await delegate(rawArgv));
 }

package/dist/run-diagnostics.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { getAdapterSurface } from "./adapters/surface.js";
+import { runnerDir } from "./paths.js";
+const MAX_CAPTURE_BYTES = 512 * 1024;
+const MAX_FINDINGS = 20;
+const MAX_PREVIEW_CHARS = 320;
+async function beginRunDiagnostics(adapter, projectRoot) {
+  const source = getAdapterSurface(adapter).appLogSource(projectRoot);
+  if (!source) return null;
+  const mobileIssueBuffer = adapter === "mobile" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
+  const extensionConsoleCapture = adapter === "extension" ? await startExtensionConsoleCapture(source, projectRoot) : void 0;
+  const stat = safeStat(source.path);
+  return {
+    source,
+    offset: stat?.size ?? 0,
+    ...stat ? { inode: stat.ino } : {},
+    ...mobileIssueBuffer ? { mobileIssueBuffer } : {},
+    ...extensionConsoleCapture ? { extensionConsoleCapture } : {}
+  };
+}
+function finishRunDiagnostics(baseline, result) {
+  if (!baseline) return result;
+  try {
+    stopRunDiagnostics(baseline);
+    const bufferedIssues = baseline.mobileIssueBuffer ? collectMobileIssueBuffer(baseline.mobileIssueBuffer.projectRoot) : void 0;
+    const diagnostics = collectRunDiagnostics(baseline, bufferedIssues);
+    const artifactsDir = path.dirname(result.summaryPath);
+    const diagnosticsPath = path.join(artifactsDir, "diagnostics.json");
+    fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}
+`);
+    indexDiagnosticArtifact(result.artifactManifestPath);
+    indexDiagnosticSummary(result.summaryPath, diagnostics);
+    return {
+      ...result,
+      diagnosticsPath,
+      sideFindings: {
+        status: diagnostics.status,
+        note: diagnostics.note,
+        counts: diagnostics.counts
+      }
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    console.warn(`WARN: run diagnostics were unavailable: ${detail}`);
+    return {
+      ...result,
+      sideFindings: {
+        status: "unavailable",
+        note: "Run diagnostics could not be collected; the recipe result is unchanged.",
+        counts: { total: 0, warning: 0, error: 0, exception: 0 }
+      }
+    };
+  }
+}
+function stopRunDiagnostics(baseline) {
+  const capture = baseline?.extensionConsoleCapture;
+  if (!capture || capture.exitCode !== null || capture.signalCode !== null) return;
+  capture.kill("SIGTERM");
+}
+function collectRunDiagnostics(baseline, bufferedIssues) {
+  const stat = safeStat(baseline.source.path);
+  const source = {
+    label: baseline.source.label,
+    path: baseline.source.path,
+    startOffset: baseline.offset,
+    endOffset: stat?.size ?? baseline.offset,
+    bytesRead: 0,
+    truncated: false,
+    inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected"
+  };
+  let text = "";
+  if (stat) {
+    const sameFile = baseline.inode === void 0 || baseline.inode === stat.ino;
+    const startOffset = sameFile && stat.size >= baseline.offset ? baseline.offset : 0;
+    const available = Math.max(0, stat.size - startOffset);
+    const bytesToRead = Math.min(available, MAX_CAPTURE_BYTES);
+    source.startOffset = startOffset;
+    source.endOffset = stat.size;
+    source.bytesRead = bytesToRead;
+    source.truncated = available > MAX_CAPTURE_BYTES;
+    if (bytesToRead > 0) text = readSlice(baseline.source.path, startOffset, bytesToRead);
+  }
+  const allFindings = dedupeFindings(
+    [
+      ...text.split(/\r?\n/u).map(classifyLine).filter((finding) => finding !== null),
+      ...(bufferedIssues ?? []).map(classifyBufferedIssue).filter((finding) => finding !== null)
+    ]
+  );
+  const findings = allFindings.slice(0, MAX_FINDINGS);
+  const counts = countFindings(allFindings);
+  const status = counts.total > 0 ? "review" : stat || bufferedIssues !== void 0 && bufferedIssues !== null ? "clean" : "unavailable";
+  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
+  return {
+    schemaVersion: 1,
+    scope: "recipe-run-application",
+    status,
+    nonBlocking: true,
+    note,
+    source,
+    counts,
+    findings
+  };
+}
+function classifyLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  let level = null;
+  if (/\bEXCEPTION\s{2,}|\b(?:Uncaught|UnhandledPromiseRejection|FATAL EXCEPTION)\b/iu.test(trimmed)) {
+    level = "exception";
+  } else if (/^(?:ERROR\s{2,}|\[error\]\s*)/iu.test(trimmed) || /\]\s+ERROR\s{2,}/u.test(trimmed)) {
+    level = "error";
+  } else if (/^(?:WARN(?:ING)?\s{2,}|\[warn(?:ing)?\]\s*)/iu.test(trimmed) || /\]\s+WARN(?:ING)?\s{2,}/u.test(trimmed)) {
+    level = "warning";
+  }
+  if (!level) return null;
+  return makeFinding(level, trimmed);
+}
+function classifyBufferedIssue(value) {
+  if (!isRecord(value) || typeof value.text !== "string") return null;
+  const rawLevel = String(value.level ?? "").toLowerCase();
+  const level = rawLevel === "warn" || rawLevel === "warning" ? "warning" : rawLevel === "error" ? "error" : rawLevel === "exception" ? "exception" : null;
+  return level ? makeFinding(level, value.text) : null;
+}
+function makeFinding(level, text) {
+  const preview = redactPreview(text.trim());
+  const identity = preview.replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?\b/gu, "[TIME]").replace(/\[(?:sw|page:[^\]]+|console:[^\]]+)\]/gu, "[APP]").replace(/^(?:(?:WARN(?:ING)?|ERROR|EXCEPTION|\[TIME\]|\[APP\])\s*)+/u, "");
+  return {
+    level,
+    fingerprint: createHash("sha256").update(`${level}|${identity}`).digest("hex").slice(0, 12),
+    preview
+  };
+}
+function armMobileIssueBuffer(projectRoot) {
+  const armed = runMobileIssueCommand(projectRoot, "issues-arm");
+  if (!armed) return false;
+  return runMobileIssueCommand(projectRoot, "issues-collect") !== null;
+}
+function collectMobileIssueBuffer(projectRoot) {
+  const result = runMobileIssueCommand(projectRoot, "issues-collect");
+  return isRecord(result) && Array.isArray(result.entries) ? result.entries : null;
+}
+function runMobileIssueCommand(projectRoot, command) {
+  const bridge = path.join(runnerDir, "adapters", "mobile", "bridge-runtime", "cdp-bridge.cjs");
+  const result = spawnSync(process.execPath, [bridge, command], {
+    cwd: projectRoot,
+    env: { ...process.env, APP_ROOT: projectRoot, CDP_TIMEOUT: "5000" },
+    encoding: "utf8",
+    timeout: 1e4
+  });
+  if (result.status !== 0) return null;
+  try {
+    return JSON.parse(result.stdout.trim());
+  } catch {
+    return null;
+  }
+}
+async function startExtensionConsoleCapture(source, projectRoot) {
+  const cdpPort = process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  if (!cdpPort) return void 0;
+  fs.mkdirSync(path.dirname(source.path), { recursive: true });
+  const before = safeStat(source.path)?.size ?? 0;
+  const script = path.join(runnerDir, "adapters", "extension", "console-tail.mjs");
+  const child = spawn(process.execPath, [script, "--cdp-port", cdpPort, "--log", source.path], {
+    cwd: projectRoot,
+    stdio: "ignore"
+  });
+  const attached = await waitForExtensionAttachment(source.path, before, child, 3e3);
+  if (attached) {
+    await delay(50);
+    return child;
+  }
+  if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+  return void 0;
+}
+async function waitForExtensionAttachment(logPath, offset, child, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && child.exitCode === null && child.signalCode === null) {
+    const stat = safeStat(logPath);
+    if (stat && stat.size > offset) {
+      const appended = readSlice(logPath, offset, Math.min(stat.size - offset, 64 * 1024));
+      if (appended.includes("[attached]")) return true;
+    }
+    await delay(50);
+  }
+  return false;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function redactPreview(value) {
+  return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/\b(password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]").slice(0, MAX_PREVIEW_CHARS);
+}
+function dedupeFindings(findings) {
+  const byFingerprint = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    const existing = byFingerprint.get(finding.fingerprint);
+    if (existing) existing.count += 1;
+    else byFingerprint.set(finding.fingerprint, { ...finding, count: 1 });
+  }
+  return [...byFingerprint.values()];
+}
+function countFindings(findings) {
+  const counts = { total: findings.length, warning: 0, error: 0, exception: 0 };
+  for (const finding of findings) counts[finding.level] += 1;
+  return counts;
+}
+function readSlice(filePath, offset, length) {
+  const fd = fs.openSync(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const bytesRead = fs.readSync(fd, buffer, 0, length, offset);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function safeStat(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+}
+function indexDiagnosticArtifact(manifestPath) {
+  const manifest = readJsonRecord(manifestPath);
+  if (!manifest) return;
+  const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+  manifest.artifacts = [
+    ...artifacts.filter((artifact) => !isRecord(artifact) || artifact.path !== "diagnostics.json"),
+    {
+      path: "diagnostics.json",
+      type: "json",
+      label: "Run-scoped application diagnostics",
+      category: "diagnostic"
+    }
+  ];
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+}
+function indexDiagnosticSummary(summaryPath, diagnostics) {
+  const summary = readJsonRecord(summaryPath);
+  if (!summary) return;
+  summary.sideFindings = {
+    status: diagnostics.status,
+    nonBlocking: true,
+    counts: diagnostics.counts,
+    diagnosticsPath: "diagnostics.json"
+  };
+  fs.writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}
+`);
+}
+function readJsonRecord(filePath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return isRecord(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export {
+  beginRunDiagnostics,
+  collectRunDiagnostics,
+  finishRunDiagnostics,
+  stopRunDiagnostics
+};

package/dist/runner.js

@@ -58,7 +58,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   const logger = options.quietStdout ? new console.Console(process.stderr) : console;
   return createRecipeRunner({
     actionManifest,
-    adapters: [...core, ...ui, ...lifecycle, ...custom],
+    adapters: withActionProgress([...core, ...ui, ...lifecycle, ...custom], options.onActionEvent),
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter)
@@ -76,6 +76,36 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     }
   });
 }
+function withActionProgress(adapters, onActionEvent) {
+  if (!onActionEvent) return adapters;
+  return adapters.map((entry) => ({
+    ...entry,
+    async execute(node, context) {
+      const event = { nodeId: context.nodeId, action: entry.action };
+      const reportProgress = !isAutomaticHudProgress(entry.action, node, context.nodeId);
+      if (reportProgress) onActionEvent({ ...event, status: "running" });
+      try {
+        const result = await entry.execute(node, context);
+        if (reportProgress) {
+          onActionEvent({ ...event, status: result.status === "fail" ? "failed" : "passed" });
+        }
+        return result;
+      } catch (error) {
+        if (reportProgress) onActionEvent({ ...event, status: "failed" });
+        throw error;
+      }
+    }
+  }));
+}
+function isAutomaticHudProgress(action, node, nodeId) {
+  if (action !== "app.hud" || node === null || typeof node !== "object" || Array.isArray(node)) {
+    return false;
+  }
+  const payload = node;
+  if (typeof payload.action_name === "string") return true;
+  const progress = payload.progress;
+  return nodeId === "recipe-complete" && progress !== null && typeof progress === "object" && !Array.isArray(progress) && progress.complete === true;
+}
 function mobileSourceAwareLifecycleAdapters(adapter, lifecycle) {
   if (adapter !== "mobile") return lifecycle;
   return lifecycle.map((entry) => ({
@@ -120,5 +150,6 @@ export {
   createMetaMaskExtensionRunner,
   createMetaMaskMobileRunner,
   createMetaMaskRunner,
+  isAutomaticHudProgress,
   mobileSourceAwareLifecycleAdapters
 };