@deeeed/metamask-harness 0.12.0 → 0.14.0

package/adapters/mobile/verify.sh

@@ -216,6 +216,34 @@ process.stdout.write(value);
 NODE
 }
 
+runtime_context_value() {
+  TARGET_FOR_RUNTIME_CONTEXT="$TARGET" RUNTIME_DIR_FOR_RUNTIME_CONTEXT="$RUNTIME_DIR" RUNTIME_CONTEXT_NAME="$1" node <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const target = process.env.TARGET_FOR_RUNTIME_CONTEXT;
+const runtimeDir = process.env.RUNTIME_DIR_FOR_RUNTIME_CONTEXT;
+const names = process.env.RUNTIME_CONTEXT_NAME.split(',');
+const file = path.join(target, runtimeDir, 'agentic-runtime.json');
+let data = {};
+try { data = JSON.parse(fs.readFileSync(file, 'utf8')); } catch {}
+for (const name of names) {
+  const value = data && data[name];
+  if (value !== undefined && value !== null && value !== '') {
+    process.stdout.write(String(value));
+    process.exit(0);
+  }
+}
+NODE
+}
+
+mobile_device_target() {
+  if [ "$PLATFORM" = "android" ]; then
+    printf '%s' "${ADB_SERIAL:-${ANDROID_SERIAL:-${ANDROID_DEVICE:-$(runtime_context_value adbSerial,androidDevice,device)}}}"
+    return
+  fi
+  printf '%s' "${SIM_UDID:-${IOS_SIMULATOR:-$(runtime_context_value simulator,iosSimulator,device)}}"
+}
+
 check_file() {
   local rel="$1"
   if [ -e "$TARGET/$rel" ]; then
@@ -331,6 +359,7 @@ run_with_timeout() {
 
 live_status_ok() {
   local log_path="$1"
+  local device_target="$2"
   cat > "$ARTIFACTS/mobile-status-smoke.recipe.json" <<'JSON'
 {
   "schema_version": 1,
@@ -349,12 +378,15 @@ live_status_ok() {
 JSON
   (
     cd "$TARGET"
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --project-root "$TARGET" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
+    device_args=()
+    [ -n "$device_target" ] && device_args=(--device "$device_target")
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-status-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-status-smoke" --json
   ) > "$log_path" 2>&1
 }
 
 ensure_live_runtime() {
-  if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log"; then
+  local device_target="$1"
+  if live_status_ok "$ARTIFACTS/logs/app-status-precheck.log" "$device_target"; then
     return 0
   fi
   if [ "$AUTO_START" = true ]; then
@@ -366,7 +398,17 @@ EOF
 }
 
 if [ "$STATIC_ONLY" = false ]; then
-  if ensure_live_runtime; then
+  device_target="$(mobile_device_target)"
+  if [ -z "$device_target" ]; then
+    if [ "$PLATFORM" = "android" ]; then
+      device_target="$(jsenv_value ADB_SERIAL)"
+      [ -n "$device_target" ] || device_target="$(jsenv_value ANDROID_DEVICE)"
+    else
+      device_target="$(jsenv_value IOS_SIMULATOR)"
+    fi
+  fi
+
+  if ensure_live_runtime "$device_target"; then
     checks+=('{"name":"mobile runtime controllable precheck","status":"pass"}')
   else
     checks+=('{"name":"mobile runtime controllable precheck","status":"fail","detail":"see logs/app-status-precheck.log"}')
@@ -394,20 +436,13 @@ if [ "$STATIC_ONLY" = false ]; then
 {
   "schema_version": 1,
   "title": "Mobile v1 runner live bridge smoke",
-  "description": "Verifies the installed MetaMask runner can drive the React Native debug bridge through Recipe v1 actions.",
+  "description": "Verifies the installed MetaMask runner can read the React Native debug bridge without mutating wallet state.",
   "validate": {
     "workflow": {
       "entry": "status",
       "nodes": {
         "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
-        "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "required": true, "timeout_ms": 15000, "next": "wallet-setup" },
-        "wallet-setup": { "action": "metamask.wallet.setup", "intent": "Prepare the wallet fixture for the live bridge smoke", "timeout_ms": 45000, "next": "wallet-unlock" },
-        "wallet-unlock": { "action": "metamask.wallet.ensure_unlocked", "intent": "Unlock the wallet through the manifest-declared action", "timeout_ms": 45000, "next": "wallet-read" },
-        "wallet-read": { "action": "metamask.wallet.read_state", "intent": "Read wallet state before navigating to the wallet view", "timeout_ms": 45000, "next": "navigate-wallet" },
-        "navigate-wallet": { "action": "ui.navigate", "intent": "Open the wallet view through the UI navigation action", "route": "WalletView", "timeout_ms": 45000, "next": "wait-wallet" },
-        "wait-wallet": { "action": "ui.wait_for", "intent": "Wait until the wallet screen is present", "test_id": "wallet-screen", "expected": "present", "timeout_ms": 45000, "next": "hud-smoke" },
-        "hud-smoke": { "action": "app.hud", "status": "running", "intent": "Show the Mobile live bridge smoke HUD", "progress": { "current": 1, "total": 1 }, "timeout_ms": 45000, "next": "screenshot" },
-        "screenshot": { "action": "ui.screenshot", "intent": "Capture proof that the wallet screen is visible", "path": "screenshots/mobile-v1-live-smoke.png", "timeout_ms": 45000, "next": "done" },
+        "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "required": true, "timeout_ms": 15000, "next": "done" },
         "done": { "action": "end", "status": "pass" }
       }
     }
@@ -417,13 +452,15 @@ JSON
 
   ios_simulator_resolved="$(jsenv_value IOS_SIMULATOR)"
   adb_serial_resolved="$(jsenv_value ADB_SERIAL)"
+  device_args=()
+  [ -n "$device_target" ] && device_args=(--device "$device_target")
   if (
     cd "$TARGET"
     METAMASK_RECIPE_AUTO_HUD=0 \
     IOS_SIMULATOR="${IOS_SIMULATOR:-$ios_simulator_resolved}" \
     ADB_SERIAL="${ADB_SERIAL:-$adb_serial_resolved}" \
     ANDROID_SERIAL="${ANDROID_SERIAL:-$adb_serial_resolved}" \
-    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --project-root "$TARGET" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
+    "$RUNNER_BIN" run "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" --adapter mobile --project-root "$TARGET" "${device_args[@]}" --artifacts-dir "$ARTIFACTS/runner-live-smoke" --json
   ) > "$ARTIFACTS/logs/runner-live-smoke.log" 2>&1; then
     checks+=("{\"name\":\"runner v1 live bridge smoke\",\"status\":\"pass\"}")
   else

package/adapters/mobile/wait-for-bridge.sh

@@ -9,6 +9,8 @@
 #   --target <metamask-mobile dir>  (default $PWD)
 #   --port <number>                 (default WATCHER_PORT env, else METRO_PORT, else 8081)
 #   --max-polls <n>                 (default MOBILE_BRIDGE_READY_POLLS env, else 90; 2s each = 180s)
+#   --platform ios|android          bind the required platform: the answering target
+#                                   must belong to it, regardless of ambient device env
 # Outputs:
 #   Progress on stderr; exit 0 bridge ready; 1 timeout.
 #
@@ -18,14 +20,16 @@ set -uo pipefail
 TARGET="$PWD"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
 MAX_POLLS="${MOBILE_BRIDGE_READY_POLLS:-90}"
+REQUIRE_PLATFORM=""
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --target)     TARGET="$2"; shift 2 ;;
     --port)       PORT="$2"; shift 2 ;;
     --max-polls)  MAX_POLLS="$2"; shift 2 ;;
+    --platform)   REQUIRE_PLATFORM="$2"; shift 2 ;;
     -h|--help)
-      printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>]\n'
+      printf 'Usage: wait-for-bridge.sh [--target <dir>] [--port <n>] [--max-polls <n>] [--platform ios|android]\n'
       exit 0
       ;;
     *) printf 'wait-for-bridge: unknown arg: %s\n' "$1" >&2; exit 2 ;;
@@ -34,6 +38,10 @@ done
 
 TARGET="$(cd "$TARGET" && pwd)"
 
+# The matcher reads the required platform from the environment so the value survives
+# into the node subprocess that runs the shared matcher against the status output.
+export WAIT_FOR_BRIDGE_PLATFORM="$REQUIRE_PLATFORM"
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
 . "$SCRIPT_DIR/../shared/harness-path.sh"
@@ -45,6 +53,7 @@ LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
 mkdir -p "$LOG_DIR"
 
 BRIDGE_CJS="$(dirname "$0")/bridge-runtime/cdp-bridge.cjs"
+MATCH_LIB="$(dirname "$0")/bridge-runtime/lib/match-bridge-target.cjs"
 STATUS_LOG="$LOG_DIR/bridge-status.log"
 METRO_LOG="$LOG_DIR/metro.log"
 
@@ -86,30 +95,37 @@ bridge_wait_reason() {
   bundle_progress "$METRO_LOG"
 }
 
+# Matcher is the shared boundary-safe module (match-bridge-target.cjs), so the
+# launch ready-path confirm and this poll enforce identical platform/device rules.
 bridge_has_route() {
   (cd "$TARGET" && APP_ROOT="$TARGET" node "$BRIDGE_CJS" status > "$STATUS_LOG" 2>&1) \
-  && node - "$STATUS_LOG" <<'NODE'
-const fs = require('fs');
+  && node -e '
+const { hasMatchingRoute } = require(process.argv[1]);
+const fs = require("fs");
 try {
-  const value = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
-  const targets = Array.isArray(value) ? value : [value];
-  const androidName = process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ANDROID_DEVICE || '';
-  const adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || '';
-  const iosSimulator = process.env.IOS_SIMULATOR || '';
-  const matchesTarget = (target) => {
-    if (!target || typeof target !== 'object') return false;
-    if (adbSerial || androidName) {
-      if (target.platform !== 'android') return false;
-      if (!androidName) return true;
-      const deviceName = String(target.deviceName || '');
-      return deviceName === androidName || deviceName.startsWith(`${androidName} -`);
-    }
-    if (iosSimulator) return target.deviceName === iosSimulator;
-    return true;
-  };
-  if (!targets.some((t) => matchesTarget(t) && t.route)) process.exit(1);
+  const value = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+  process.exit(hasMatchingRoute(value) ? 0 : 1);
 } catch { process.exit(1); }
-NODE
+' "$MATCH_LIB" "$STATUS_LOG"
+}
+
+# The device/platform this run is pinned to — the bridge target must belong to it.
+requested_target() {
+  node -e 'process.stdout.write(require(process.argv[1]).describeRequested())' "$MATCH_LIB" 2>/dev/null \
+    || printf 'any platform'
+}
+
+# Summarise the targets that DID answer (platform / deviceName), so a timeout teaches
+# what responded vs what was requested — e.g. an iOS target answering an android launch.
+answered_targets() {
+  [ -s "$STATUS_LOG" ] || { printf 'none'; return; }
+  node -e '
+const { describeTargets } = require(process.argv[1]);
+const fs = require("fs");
+try {
+  process.stdout.write(describeTargets(JSON.parse(fs.readFileSync(process.argv[2], "utf8"))));
+} catch { process.stdout.write("none"); }
+' "$MATCH_LIB" "$STATUS_LOG" 2>/dev/null || printf 'none'
 }
 
 for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
@@ -124,7 +140,9 @@ for ATTEMPT in $(seq 1 "$MAX_POLLS"); do
 done
 
 cat "$STATUS_LOG" >&2 || true
-printf 'wait-for-bridge: bridge did not become ready on port %s (%s polls × 2s = %ss)\n' \
-  "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
+printf 'wait-for-bridge: no bridge target matched the requested %s on port %s (%s polls × 2s = %ss)\n' \
+  "$(requested_target)" "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
+printf '  requested: %s\n' "$(requested_target)" >&2
+printf '  answered:  %s\n' "$(answered_targets)" >&2
 printf '  Next: check %s — or run mm-harness app-status\n' "$STATUS_LOG" >&2
 exit 1

package/adapters/shared/log-tui.mjs

@@ -222,13 +222,17 @@ async function watchLog(options) {
     const chunk = readNewContent(logPath, offset);
     offset = chunk.offset;
     const allText = fs.existsSync(logPath) ? fs.readFileSync(logPath, 'utf8') : '';
+    // Match readiness only against bytes read after this watch started. This
+    // assumes line-oriented log writes; a marker split across partial writes
+    // waits for a later complete marker instead of stale-passing.
+    const matchText = chunk.text;
     const events = extractEvents(allText, eventsLimit);
 
-    if (matchesPattern(allText, 'Module build failed|^ERROR in |compiled with [1-9][0-9]* error|FAIL runtime-launch|Extension harness launch fail')) {
+    if (matchesPattern(matchText, 'Module build failed|^ERROR in |compiled with [1-9][0-9]* error|FAIL runtime-launch|Extension harness launch fail')) {
       renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
       return 1;
     }
-    if (matchesPattern(allText, successPattern)) {
+    if (matchesPattern(matchText, successPattern)) {
       renderCompact({ label, logPath, events, quiet: mode === 'quiet' });
       if (mode !== 'quiet') {
         const elapsed = Math.round((Date.now() - started) / 1000);
@@ -357,4 +361,4 @@ async function main() {
 main().catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
   process.exit(1);
-});
+});

package/dist/adapters/mobile/prepare.js

@@ -3,8 +3,10 @@ import { recordDepsBaseline } from "@farmslot/recipe-harness/runtime/deps-readin
 import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
 import { runnerDir } from "../../paths.js";
 import {
-  decideMobileReadiness
+  decideMobileReadiness,
+  launchActions
 } from "./runtime-decision.js";
+const READY_BRIDGE_CONFIRM_POLLS = 3;
 const POD_PROBE_ENV = {
   FORCE_COLOR: "0",
   NO_COLOR: "1",
@@ -42,6 +44,24 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   if (report.decision === "ready") {
+    const confirm = await dispatchAction(
+      { id: "wait-for-bridge", cwd: target, argv: ["--max-polls", String(READY_BRIDGE_CONFIRM_POLLS)] },
+      target,
+      platform,
+      json,
+      preflightMode
+    );
+    if (confirm.status === 0) return { status: 0, output: "" };
+    if (!json) {
+      process.stderr.write(
+        `launch: runtime looked ready but no ${platform} bridge target answered; launching the app.
+`
+      );
+    }
+    for (const action of launchActions(path.resolve(target))) {
+      const result = await dispatchAction(action, target, platform, json, preflightMode);
+      if (result.status !== 0) return result;
+    }
     return { status: 0, output: "" };
   }
   if (report.decision === "unknown") {
@@ -115,7 +135,8 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
     }
     case "wait-for-bridge": {
       const leaf = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
-      return spawnScriptStreaming(leaf, ["--target", cwd], target);
+      const extra = action.argv ?? [];
+      return spawnScriptStreaming(leaf, ["--target", cwd, "--platform", platform, ...extra], target);
     }
     case "clear-metro-cache": {
       const leaf = path.join(runnerDir, "adapters/mobile/start-metro.sh");

package/dist/adapters/mobile/runtime-decision.js

@@ -313,5 +313,6 @@ async function computeMobileReadiness(resolved, options, fast) {
   };
 }
 export {
-  decideMobileReadiness
+  decideMobileReadiness,
+  launchActions
 };

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,21 @@ 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 {
@@ -346,20 +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",
+    "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) => reason.includes(needle));
+    "cdp message timeout",
+    "websocket closed"
+  ].some((needle) => haystack.includes(needle));
 }
 function animatedFlag(payload) {
   return payload.animated === true ? "--animated" : "--no-animated";
@@ -511,5 +533,6 @@ function targetProbeUrl(platform, targetPort) {
 export {
   createMetaMaskAdapters,
   createMetaMaskUiTransport,
+  hideMobileHudOnTeardown,
   isMobileHudLifecycleSkip
 };

package/dist/cli-commands.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { listRecipeFiles } from "./recipe-files.js";
 const SPEC = {
   shim: [
     { name: "sync", desc: "Copy fixture, write slot context, install harness", flags: ["--dry-run", "--no-install"] },
@@ -16,7 +17,7 @@ const SPEC = {
     { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port", "--device"] },
-    { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
+    { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
     { name: "prepare", desc: "Install harness (+ optional validate)", flags: ["--target", "--runtime-dir", "--json"] },
@@ -124,9 +125,9 @@ function listRunRecipes(adapter, root, cwd = process.cwd()) {
   for (const resolveDir of RUN_RECIPE_DIRS) {
     const dir = resolveDir(adapter, root);
     if (!fs.existsSync(dir)) continue;
-    for (const name of fs.readdirSync(dir)) {
-      if (!name.endsWith(".recipe.json") || byBase.has(name)) continue;
-      byBase.set(name, path.join(dir, name));
+    for (const rel of listRecipeFiles(dir)) {
+      if (byBase.has(rel)) continue;
+      byBase.set(rel, path.join(dir, rel));
     }
   }
   return [...byBase.values()].map((abs) => path.relative(cwd, abs)).sort();