@deeeed/metamask-harness 0.11.0 → 0.13.0

package/dist/adapters.js

@@ -2,7 +2,7 @@ import http from "node:http";
 import { compatibilityMode, fixtureSummary, repoShape } from "./doctor.js";
 import { runLiveAdapterScript } from "./live-adapter-contract.js";
 import { withExtensionPage } from "../library/actions/extension/platform/cdp.mjs";
-import { bridgeCommand, evalSync, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
+import { bridgeCommand, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -331,9 +331,23 @@ async function handleMobileHud(payload, context) {
     return mobileHudSkippedOrThrow(error, { nodeId: hud.nodeId, status: hud.status });
   }
 }
+async function hideMobileHudOnTeardown(projectRoot, env = {}) {
+  if (process.env.METAMASK_RECIPE_AUTO_HUD === "0" || process.env.METAMASK_RECIPE_AUTO_HUD === "false") return;
+  const input = {
+    node: { bridge_timeout_ms: 8e3, cdp_timeout_ms: 5e3 },
+    context: { nodeId: "teardown", projectRoot, artifactsDir: projectRoot, env }
+  };
+  try {
+    await bridgeCommand(input, ["hide-step"]);
+  } catch {
+  }
+}
 function mobileHudSkippedOrThrow(error, extra = {}) {
   const reason = traceText(error);
-  if (isMobileHudLifecycleSkip(reason)) {
+  const code = isRecord(error) && typeof error.code === "string" ? error.code : void 0;
+  if (isMobileHudLifecycleSkip(reason, code)) {
+    process.stderr.write(`app.hud skipped (bridge target down or transitioning): ${reason}
+`);
     return {
       hud: false,
       skipped: true,
@@ -344,16 +358,30 @@ function mobileHudSkippedOrThrow(error, extra = {}) {
   }
   throw new Error(`app.hud bridge command failed outside a lifecycle/no-target transition: ${reason}`);
 }
-function isMobileHudLifecycleSkip(reason) {
+const HUD_LIFECYCLE_SKIP_CODES = /* @__PURE__ */ new Set([
+  MOBILE_BRIDGE_ERROR_CODES.NO_TARGET,
+  MOBILE_BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  MOBILE_BRIDGE_ERROR_CODES.WS_CLOSED,
+  MOBILE_BRIDGE_ERROR_CODES.METRO_UNREACHABLE
+]);
+function isMobileHudLifecycleSkip(reason, code) {
+  if (code && HUD_LIFECYCLE_SKIP_CODES.has(code)) return true;
+  const haystack = reason.toLowerCase();
   return [
     "no responding bridge target",
-    "Pinned android device",
+    "pinned android device",
     "bridge probe failed",
-    "ECONNREFUSED",
+    "econnrefused",
     "timed out",
-    "Timed out",
-    "No React Native bridge target"
-  ].some((needle) => reason.includes(needle));
+    "no react native bridge target",
+    // Metro down mid-run: HUD cannot paint, so skip rather than abort (the real
+    // action fails on its own). Matches the METRO_UNREACHABLE code branch above.
+    "cannot reach metro",
+    // Dev-client foreground/reload kills the Hermes page mid-flight: pending
+    // CDP calls surface as a message timeout or a closed socket.
+    "cdp message timeout",
+    "websocket closed"
+  ].some((needle) => haystack.includes(needle));
 }
 function animatedFlag(payload) {
   return payload.animated === true ? "--animated" : "--no-animated";
@@ -504,5 +532,7 @@ function targetProbeUrl(platform, targetPort) {
 }
 export {
   createMetaMaskAdapters,
-  createMetaMaskUiTransport
+  createMetaMaskUiTransport,
+  hideMobileHudOnTeardown,
+  isMobileHudLifecycleSkip
 };

package/dist/commands/call.js

@@ -6,8 +6,10 @@ import { loadActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
 import { recipeRunning } from "../heal-bounds.js";
 import { EXIT } from "./shared.js";
+import { describeManifestActions, fuzzyResolveActions } from "./manifest.js";
 import {
   parseArgs,
+  isRecord,
   optionFlag,
   optionString,
   resolveAdapter,
@@ -153,6 +155,82 @@ Artifacts: ${result.artifactManifestPath}`);
   }
   return result.status === "pass" ? EXIT.ok : EXIT.runtime;
 }
+async function handleCallHelp(argv, genericHelp) {
+  const { action: shortName, rest } = parseCallArgs(argv.filter((arg) => arg !== "--help" && arg !== "-h"));
+  const { options } = parseArgs(rest, "call");
+  let adapter;
+  let manifest;
+  try {
+    ({ adapter } = resolveAdapter(options));
+    manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  } catch {
+    process.stdout.write(`${genericHelp}
+`);
+    return EXIT.ok;
+  }
+  const matches = shortName ? fuzzyResolveActions(describeManifestActions(manifest), shortName) : [];
+  if (matches.length === 0) {
+    process.stdout.write(`${genericHelp}
+`);
+    if (shortName) {
+      process.stdout.write(
+        `
+No action matches "${shortName}" for the ${adapter} adapter.
+  Next: mm-harness actions --adapter ${adapter}   # list the action vocabulary
+`
+      );
+    }
+    return EXIT.ok;
+  }
+  for (const entry of matches) process.stdout.write(renderCallActionHelp(entry));
+  process.stdout.write(`${genericHelp}
+`);
+  return EXIT.ok;
+}
+function renderCallActionHelp(entry) {
+  const short = entry.name.split(".").pop() ?? entry.name;
+  const schema = isRecord(entry.schema) ? entry.schema : {};
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []
+  );
+  const lines = [`mm-harness call ${entry.name} [--arg k=v ...] [flags]`, ""];
+  if (entry.description) lines.push(`  ${entry.description}`, "");
+  const names = Object.keys(properties).sort();
+  if (names.length === 0) {
+    lines.push("  Fields: (none)");
+  } else {
+    lines.push("  Fields (pass with --arg <name>=<value>):");
+    const width = Math.max(...names.map((name) => name.length));
+    for (const name of names) {
+      const prop = isRecord(properties[name]) ? properties[name] : {};
+      const type = typeof prop.type === "string" ? prop.type : "any";
+      const req = required.has(name) ? " (required)" : "";
+      const desc = typeof prop.description === "string" ? ` \u2014 ${prop.description}` : "";
+      const enumVals = Array.isArray(prop.enum) ? ` [one of: ${prop.enum.join(", ")}]` : "";
+      lines.push(`    ${name.padEnd(width)}  ${type}${req}${desc}${enumVals}`);
+    }
+  }
+  const examples = renderCallExamples(short, entry.examples);
+  if (examples.length > 0) {
+    lines.push("", "  Examples:");
+    for (const example of examples) lines.push(`    ${example}`);
+  }
+  return `${lines.join("\n")}
+
+`;
+}
+function renderCallExamples(short, examples) {
+  if (!Array.isArray(examples)) return [];
+  const out = [];
+  for (const example of examples.slice(0, 2)) {
+    const node = isRecord(example) && isRecord(example.node) ? example.node : void 0;
+    if (!node) continue;
+    const tokens = Object.entries(node).filter(([key]) => key !== "action" && key !== "intent").map(([key, value]) => `--arg ${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
+    out.push(`mm-harness call ${short} ${tokens.join(" ")}`.trim());
+  }
+  return out;
+}
 function parseCallArgs(argv) {
   const args = {};
   const rest = [];
@@ -191,5 +269,6 @@ function pickCallExampleAction(names) {
   return names[0] ?? "command";
 }
 export {
-  handleCall
+  handleCall,
+  handleCallHelp
 };

package/dist/commands/manifest.js

@@ -87,6 +87,8 @@ function describeManifestAction(name, kind, metadata) {
   };
 }
 export {
+  describeManifestActions,
+  fuzzyResolveActions,
   handleActions,
   handleManifest
 };

package/dist/commands/run-engine.js

@@ -68,7 +68,15 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         recordVideo: useFramedExtensionRecording ? false : recordVideo,
         ...runtimeOptions.librarySources ? { librarySources: runtimeOptions.librarySources } : {}
       };
-      const result = await runner.run(runRequest);
+      let result;
+      try {
+        result = await runner.run(runRequest);
+      } finally {
+        if (adapter === "mobile") {
+          const { hideMobileHudOnTeardown } = await import("../adapters.js");
+          await hideMobileHudOnTeardown(projectRoot, recipeRunEnv(adapter, runtimeOptions));
+        }
+      }
       await stopRecipeRecording(recording, result);
       return result;
     } finally {

package/dist/mm-harness-cli.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { color } from "./cli-color.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
+import { handleCallHelp } from "./commands/call.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
@@ -614,6 +615,13 @@ function hasPassthroughHelp(argv) {
   if (divider === -1) return false;
   return argv.slice(divider + 1).some((arg) => arg === "-h" || arg === "--help");
 }
+function isCallActionHelp(argv) {
+  if (argv[0] !== "call") return false;
+  if (!argv[1] || argv[1].startsWith("-")) return false;
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.includes("--help") || scope.includes("-h");
+}
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
@@ -621,4 +629,8 @@ if (rawArgv.length === 0) {
 if (hasPassthroughHelp(rawArgv)) {
   process.exit(await delegate(rawArgv));
 }
+if (isCallActionHelp(rawArgv)) {
+  const callHelp = REAL.find((command) => command.name === "call")?.helpText ?? "";
+  process.exit(await handleCallHelp(rawArgv.slice(1), callHelp));
+}
 await program.parseAsync(process.argv);

package/dist/runner.js

@@ -40,10 +40,10 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     })
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
-  const lifecycle = adapter === "mobile" ? createAppLifecycleAdapters({
+  const lifecycle = createAppLifecycleAdapters({
     actions,
     targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
-  }) : [];
+  });
   const custom = createMetaMaskAdapters(adapter).filter(
     (entry) => declaredActions.has(entry.action) && !existing.has(entry.action) && !lifecycle.some((lifecycleEntry) => lifecycleEntry.action === entry.action)
   );

package/library/actions/mobile/platform/bridge.mjs

@@ -3,9 +3,35 @@ import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import bridgeErrors from '../../../../adapters/mobile/bridge-runtime/lib/bridge-errors.cjs';
+
+const {
+  BRIDGE_ERROR_CODES,
+  ERROR_CODE_BY_EXIT_CODE,
+  classifyBridgeErrorMessage,
+  coded,
+  parseErrorMarker,
+} = bridgeErrors;
+
+// Re-exported so the TS adapter classifies on the same code constants without a
+// second import path into the cjs bridge-runtime.
+export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 
 const execFileAsync = promisify(execFile);
 
+// Recover the typed code a cdp-bridge child reported: the stderr marker is
+// authoritative (it carries the class the bridge classified at the source), the
+// coded exit status is the fallback for output-less failures, and a raw message
+// needle covers a bridge that predates the codes.
+function bridgeChildErrorCode(exitCode, output) {
+  return (
+    parseErrorMarker(output) ||
+    ERROR_CODE_BY_EXIT_CODE[exitCode] ||
+    classifyBridgeErrorMessage(output) ||
+    null
+  );
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -169,12 +195,12 @@ export function selectBridgeStatusEntry(status, input) {
     }
     // Pinned android but no android entry answered — failing fast beats letting the
     // caller read the iOS entry and report misleading wallet state.
-    throw new Error(
+    throw coded(new Error(
       `Pinned android device ${adbSerial} has no responding bridge target.\n` +
       `  Bridge status entries:\n` +
       entries.map((entry) => `    - ${entry.deviceName ?? '?'} [${entry.platform || 'unknown'}]`).join('\n') +
       `\n  Next: mm-harness launch android   # bring the app back to the foreground`,
-    );
+    ), BRIDGE_ERROR_CODES.NO_TARGET);
   }
   if (iosSimulator) {
     const sim = entries.find((entry) => entry.deviceName === iosSimulator);
@@ -239,11 +265,16 @@ export async function bridgeCommand(input, args) {
   });
   if (result.timedOut) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
-    throw new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`);
+    throw coded(
+      new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`),
+      BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+    );
   }
   if (result.exitCode !== 0) {
     const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
-    throw new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
+    const code = bridgeChildErrorCode(result.exitCode, result.stderr || result.stdout);
+    const error = new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
+    throw code ? coded(error, code) : error;
   }
   // For transient commands, stdout of '' or 'undefined' means the state is not yet
   // settled (e.g. mid-navigation). Return null so callers like waitForRoute can poll

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -69,4 +69,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}