@deeeed/metamask-harness 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.3 - 2026-07-04
+
+### Fixed
+- **IMP-23: per-run mobile runtime dir (`RECIPE_RUNTIME_DIR`)** — every on-disk mobile runtime file (`metro.log`, `metro.pid`, `metro.tmux`, `bridge-status.log`, `wallet-fixture.json`) now resolves from the shared runtime-dir resolver that honors `RECIPE_RUNTIME_DIR` instead of the hard-coded `<target>/temp/recipe/runtime`. `RECIPE_RUNTIME_DIR` must be a non-empty relative path under the target checkout — absolute values are rejected at validation. Shell (`recipe_runtime_dir` in `harness-path.sh`, used by `start-metro.sh`, `wait-for-bridge.sh`, `prewarm-bundle.sh`, and `bridge-runtime/setup-wallet.sh`) and TS (`recipeRuntimePath` in `runtime-decision.ts`) resolve the same location, so a run pointed at an isolated subdir (e.g. `temp/recipe/runtime-8081`) writes and reads nothing under the default. Two harness jobs sharing one checkout each set `RECIPE_RUNTIME_DIR` to a distinct relative subdir for full runtime isolation.
+- **IMP-23: port-scoped Metro guard** — the Metro detect/kill/restart helpers are extracted into `adapters/mobile/lib/metro-listener.sh` with an explicit invariant: discovery, inspection, and signalling key off the managed watcher-port only (`lsof -iTCP:<port> -sTCP:LISTEN`). A Metro listening on any other port is never selected, never has its cmdline read, and is never signalled, so a run managing one port cannot detect or kill a concurrent Metro on another port in the same checkout.
+
+## 0.3.2 - 2026-07-04
+
+### Fixed
+- **IMP-21: FORCE_COLOR-safe pod install** — the mobile pod-triggering leaves (`yarn-setup.sh` running `yarn setup`, and `open-device.sh` running the native `yarn start:ios|android` build) now run with `FORCE_COLOR=0` / `NO_COLOR=1`. VisionCamera's podspec probes `node --print require.resolve('react-native-worklets-core')` and treats any output other than the exact string `undefined` as "found"; an inherited `FORCE_COLOR` made node emit a colorized `undefined`, enabling FrameProcessors and hard-failing on the missing worklets pod. Setup/native builds are now reliable from a `FORCE_COLOR` shell.
+- **IMP-22: `--watcher-port` beats `.js.env WATCHER_PORT`** — `verify.sh` port resolution now honors an explicit `WATCHER_PORT` in the process env (which carries `mm-harness launch --watcher-port N`) over the target's `.js.env`. Precedence is flag > process env > `.js.env` > `8081` default, so a run can be pointed at an alternate Metro/CDP port without editing a shared slot's `.js.env`.
+
 ## 0.3.1 - 2026-07-03
 
 ### Fixed

package/adapters/mobile/bridge-runtime/setup-wallet.sh

@@ -27,6 +27,15 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 APP_ROOT="${APP_ROOT:-$PWD}"
 cd "$APP_ROOT"
 
+# Runtime-dir resolver: wallet-fixture.json lands under the same per-run dir as
+# other mobile runtime files, controlled by RECIPE_RUNTIME_DIR (relative, validated).
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../../shared/harness-path.sh"
+if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
+  echo "setup-wallet: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+
 PORT="${WATCHER_PORT:-8081}"
 [[ "$PORT" =~ ^[0-9]+$ ]] || { echo "ERROR: WATCHER_PORT must be numeric (got: $PORT)" >&2; exit 1; }
 SCRIPTS="$SCRIPT_DIR"
@@ -67,11 +76,11 @@ while [[ $# -gt 0 ]]; do
 done
 
 # -- Resolve + validate fixture --
-[ -z "$FIXTURE_PATH" ] && FIXTURE_PATH="${WALLET_FIXTURE:-${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}/wallet-fixture.json}"
+[ -z "$FIXTURE_PATH" ] && FIXTURE_PATH="${WALLET_FIXTURE:-$(recipe_runtime_dir)/wallet-fixture.json}"
 
 if [ ! -f "$FIXTURE_PATH" ]; then
   echo "ERROR: Fixture not found: $FIXTURE_PATH"
-  echo "  create ${RECIPE_RUNTIME_DIR:-temp/recipe/runtime}/wallet-fixture.json"
+  echo "  create $(recipe_runtime_dir)/wallet-fixture.json"
   exit 1
 fi
 echo "Reading fixture: $FIXTURE_PATH"

package/adapters/mobile/lib/metro-listener.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# metro-listener.sh — port-scoped Metro process helpers.
+#
+# Safety boundary: every function keys off the managed Metro port ($PORT) ONLY.
+# Discovery is `lsof -iTCP:$PORT -sTCP:LISTEN`, so a Metro (or anything) listening
+# on any OTHER port is invisible here — its pid is never in the returned set, its
+# cmdline is never read, and it is never signalled. This is what lets one checkout
+# host concurrent Metro instances on different ports (e.g. 8081 and 8092) while a
+# run that manages 8081 provably cannot detect, restart, or kill the 8092 process.
+#
+# Sourced (not executed) by start-metro.sh and by the contract test. Callers set
+# $PORT (managed watcher-port) and, for metro_listener_valid, $TARGET before use.
+
+# metro_ready — true when the managed port serves a running Metro packager status.
+metro_ready() {
+  curl -sf --max-time 2 "http://localhost:${PORT}/status" 2>/dev/null | grep -q 'packager-status:running'
+}
+
+# metro_listener_pids — pids LISTENing on the managed port (and no other port).
+metro_listener_pids() {
+  lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true
+}
+
+# metro_listener_valid — 0 when the managed-port listener is this checkout's Metro
+# with the required env; 1 when absent, foreign, or missing env (→ restart). Only
+# ever inspects pids listening on $PORT.
+metro_listener_valid() {
+  local pids pid command rv
+  pids="$(metro_listener_pids)"
+  [ -n "$(printf '%s' "$pids" | tr -d ' ')" ] || return 1
+  rv=0
+  for pid in $pids; do
+    command="$(ps eww -p "$pid" -o command= 2>/dev/null || true)"
+    case "$command" in
+      *"$TARGET"*) ;;
+      *)
+        printf 'Metro on port %s not owned by this checkout (pid %s); restarting\n' "$PORT" "$pid" >&2
+        rv=1; break
+        ;;
+    esac
+    for required_var in ${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID}; do
+      if ! printf '%s\n' "$command" | grep -Eq "(^|[[:space:]])${required_var}="; then
+        printf 'Metro on port %s missing required env %s (pid %s); restarting\n' "$PORT" "$required_var" "$pid" >&2
+        rv=1; break 2
+      fi
+    done
+  done
+  return "$rv"
+}
+
+# stop_metro_listener — TERM then KILL only the pids LISTENing on the managed port.
+# A process on any other port is never signalled. 0 when the port is free.
+stop_metro_listener() {
+  local pids i
+  pids="$(metro_listener_pids)"
+  [ -n "$(printf '%s' "$pids" | tr -d ' ')" ] || return 0
+  printf 'Stopping Metro listener on port %s: %s\n' "$PORT" "$pids" >&2
+  # shellcheck disable=SC2086
+  kill $pids 2>/dev/null || true
+  for i in $(seq 1 20); do
+    pids="$(metro_listener_pids)"
+    [ -z "$(printf '%s' "$pids" | tr -d ' ')" ] && return 0
+    sleep 0.25
+  done
+  printf 'Metro listener still held; force-killing: %s\n' "$pids" >&2
+  # shellcheck disable=SC2086
+  kill -KILL $pids 2>/dev/null || true
+  for i in $(seq 1 20); do
+    pids="$(metro_listener_pids)"
+    [ -z "$(printf '%s' "$pids" | tr -d ' ')" ] && return 0
+    sleep 0.25
+  done
+  printf 'start-metro: port %s still occupied after force-kill: %s\n' "$PORT" "$pids" >&2
+  return 1
+}

package/adapters/mobile/prewarm-bundle.sh

@@ -39,7 +39,15 @@ case "$PLATFORM" in
 esac
 
 TARGET="$(cd "$TARGET" && pwd)"
-LOG_DIR="$TARGET/temp/recipe/runtime"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../shared/harness-path.sh"
+if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
+  echo "prewarm-bundle: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
 mkdir -p "$LOG_DIR"
 METRO_LOG="$LOG_DIR/metro.log"
 

package/adapters/mobile/start-metro.sh

@@ -37,69 +37,28 @@ while [ "$#" -gt 0 ]; do
 done
 
 TARGET="$(cd "$TARGET" && pwd)"
-LOG_DIR="$TARGET/temp/recipe/runtime"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../shared/harness-path.sh"
+if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
+  echo "start-metro: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+# Port-scoped Metro helpers (metro_ready / *_listener_* / stop_metro_listener)
+# only ever inspect or signal a Metro listening on $PORT.
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/lib/metro-listener.sh"
+
+# RECIPE_RUNTIME_DIR (relative, validated) makes runtime state per-run so jobs
+# sharing one checkout do not collide on metro.log / metro.pid / metro.tmux.
+LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
 mkdir -p "$LOG_DIR"
 LOG_FILE="$LOG_DIR/metro.log"
 PID_FILE="$LOG_DIR/metro.pid"
 
 # --- helpers ------------------------------------------------------------------
 
-metro_ready() {
-  curl -sf --max-time 2 "http://localhost:${PORT}/status" 2>/dev/null | grep -q 'packager-status:running'
-}
-
-metro_listener_pids() {
-  lsof -nP -iTCP:"${PORT}" -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true
-}
-
-metro_listener_valid() {
-  local pids pid command rv
-  pids="$(metro_listener_pids)"
-  [ -n "$(printf '%s' "$pids" | tr -d ' ')" ] || return 1
-  rv=0
-  for pid in $pids; do
-    command="$(ps eww -p "$pid" -o command= 2>/dev/null || true)"
-    case "$command" in
-      *"$TARGET"*) ;;
-      *)
-        printf 'Metro on port %s not owned by this checkout (pid %s); restarting\n' "$PORT" "$pid" >&2
-        rv=1; break
-        ;;
-    esac
-    for required_var in ${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID}; do
-      if ! printf '%s\n' "$command" | grep -Eq "(^|[[:space:]])${required_var}="; then
-        printf 'Metro on port %s missing required env %s (pid %s); restarting\n' "$PORT" "$required_var" "$pid" >&2
-        rv=1; break 2
-      fi
-    done
-  done
-  return "$rv"
-}
-
-stop_metro_listener() {
-  local pids i
-  pids="$(metro_listener_pids)"
-  [ -n "$(printf '%s' "$pids" | tr -d ' ')" ] || return 0
-  printf 'Stopping Metro listener on port %s: %s\n' "$PORT" "$pids" >&2
-  # shellcheck disable=SC2086
-  kill $pids 2>/dev/null || true
-  for i in $(seq 1 20); do
-    pids="$(metro_listener_pids)"
-    [ -z "$(printf '%s' "$pids" | tr -d ' ')" ] && return 0
-    sleep 0.25
-  done
-  printf 'Metro listener still held; force-killing: %s\n' "$pids" >&2
-  # shellcheck disable=SC2086
-  kill -KILL $pids 2>/dev/null || true
-  for i in $(seq 1 20); do
-    pids="$(metro_listener_pids)"
-    [ -z "$(printf '%s' "$pids" | tr -d ' ')" ] && return 0
-    sleep 0.25
-  done
-  printf 'start-metro: port %s still occupied after force-kill: %s\n' "$PORT" "$pids" >&2
-  return 1
-}
-
 default_metro_workers() {
   local cores=""
   if command -v sysctl >/dev/null 2>&1; then

package/adapters/mobile/verify.sh

@@ -174,14 +174,21 @@ watcher_port() {
 const fs = require('fs');
 const path = require('path');
 const target = process.env.TARGET_FOR_WATCHER_PORT;
-let port = process.env.WATCHER_PORT || '8081';
-for (const file of ['.js.env', '.env', '.env.local']) {
-  const full = path.join(target, file);
-  if (!fs.existsSync(full)) continue;
-  const text = fs.readFileSync(full, 'utf8');
-  const match = text.match(/^\s*(?:export\s+)?WATCHER_PORT=(["']?)([0-9]+)\1/m);
-  if (match) { port = match[2]; break; }
+// Precedence: an explicit WATCHER_PORT in the process env (which carries the
+// --watcher-port flag applied by launch) wins over the slot's .js.env, which wins
+// over the 8081 default. This lets a run be pointed at an alternate Metro without
+// editing a shared slot .js.env.
+let port = process.env.WATCHER_PORT || '';
+if (!port) {
+  for (const file of ['.js.env', '.env', '.env.local']) {
+    const full = path.join(target, file);
+    if (!fs.existsSync(full)) continue;
+    const text = fs.readFileSync(full, 'utf8');
+    const match = text.match(/^\s*(?:export\s+)?WATCHER_PORT=(["']?)([0-9]+)\1/m);
+    if (match) { port = match[2]; break; }
+  }
 }
+if (!port) port = '8081';
 console.log(port);
 NODE
 }

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

@@ -33,7 +33,15 @@ while [ "$#" -gt 0 ]; do
 done
 
 TARGET="$(cd "$TARGET" && pwd)"
-LOG_DIR="$TARGET/temp/recipe/runtime"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../shared/harness-path.sh"
+if ! command -v recipe_runtime_dir >/dev/null 2>&1; then
+  echo "wait-for-bridge: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
+  exit 1
+fi
+LOG_DIR="$TARGET/$(recipe_runtime_dir)" || exit 1
 mkdir -p "$LOG_DIR"
 
 BRIDGE_CJS="$(dirname "$0")/bridge-runtime/cdp-bridge.cjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/src/adapters/mobile/prepare.ts

@@ -18,6 +18,14 @@ import {
 
 export { type MobileRuntimeDecisionReport };
 
+// Pod install (run by `yarn setup` and by the native `yarn start:ios|android`
+// build) shells `node --print require.resolve('react-native-worklets-core')` and
+// treats any output other than the exact string `undefined` as "module found".
+// An inherited FORCE_COLOR makes node emit a colorized `undefined`, so VisionCamera
+// misdetects the worklets pod, enables FrameProcessors, and fails on the missing
+// pod. Force plain output for pod-triggering spawns so the probe reads `undefined`.
+const POD_PROBE_ENV: Record<string, string> = { FORCE_COLOR: '0', NO_COLOR: '1' };
+
 export interface PrepareMobileOptions extends MobileRuntimeDecisionOptions {
   /** Pass through to leaf-script spawnScript calls so output is suppressed in --json mode. */
   json?: boolean;
@@ -159,9 +167,9 @@ function dispatchAction(
   const cwd = action.cwd ?? target;
   switch (action.id) {
     case 'yarn-setup': {
-      // Leaf: install node_modules (deps missing or stale).
+      // Leaf: install node_modules (deps missing or stale); `yarn setup` runs pods.
       const leaf = path.join(runnerDir, 'adapters/mobile/yarn-setup.sh');
-      return spawnScript(leaf, ['--target', cwd], target, json);
+      return spawnScript(leaf, ['--target', cwd], target, json, POD_PROBE_ENV);
     }
     case 'start-metro': {
       // Leaf: ensure Metro is running; argv may carry --clear for cache reset.
@@ -185,13 +193,16 @@ function dispatchAction(
       return spawnScript(leaf, ['--target', cwd, '--clear'], target, json);
     }
     case 'launch-mobile-runtime': {
-      // Leaf: open the MetaMask Mobile dev client on the simulator/device.
+      // Leaf: open the MetaMask Mobile dev client on the simulator/device. In
+      // auto/rebuild modes this runs the native build (`yarn start:*`), which
+      // triggers pod install — pass the pod-probe env so it stays FORCE_COLOR-safe.
       const leaf = path.join(runnerDir, 'adapters/mobile/open-device.sh');
       return spawnScript(
         leaf,
         ['--platform', platform, '--target', cwd, '--preflight-mode', preflightMode],
         target,
         json,
+        POD_PROBE_ENV,
       );
     }
     case 'rebuild-native-dev-client': {

package/src/adapters/mobile/runtime-decision.ts

@@ -15,6 +15,7 @@ import {
 } from '@farmslot/recipe-harness/runtime/log-analysis';
 import { probeMetroPackager, type MetroReachabilityCheck } from '@farmslot/recipe-harness/runtime/metro-probe';
 
+import { recipeRuntimePath } from '../../paths.ts';
 import { mobileProductMarkers } from './deps-markers.ts';
 
 /**
@@ -62,9 +63,14 @@ const BUNDLE_OK = /Bundled \d+ms|iOS Bundled|Android Bundled|Finished bundling/u
 const NATIVE_MODULE_STALE =
   /\[runtime not ready\].*HybridObject "([^"]+)" - It has not yet been registered in the Nitro Modules HybridObjectRegistry/u;
 
+// The metro.log location honors RECIPE_RUNTIME_DIR via the shared recipeRuntimePath
+// resolver (relative, validated), so the decision engine reads metro.log from the
+// same per-run dir the mobile leaf scripts write — two jobs sharing one checkout
+// stay isolated. An explicit metroLog override (a --metro-log flag) still wins.
 function resolveMetroLog(target: string, metroLog?: string): string | null {
-  const rel = metroLog ?? 'temp/recipe/runtime/metro.log';
-  const abs = path.isAbsolute(rel) ? rel : path.join(target, rel);
+  const abs = metroLog
+    ? (path.isAbsolute(metroLog) ? metroLog : path.join(target, metroLog))
+    : recipeRuntimePath(target, 'metro.log');
   return fs.existsSync(abs) ? abs : null;
 }
 

package/src/commands/shared.ts

@@ -95,12 +95,14 @@ export interface ScriptResult {
 
 // Compose an adapters/ script directly. Output is always captured (needed for
 // heal classification) and, in human mode, forwarded to stderr. --json keeps
-// stdout clean for the machine summary.
+// stdout clean for the machine summary. `env` overlays extra vars onto the
+// inherited environment for spawns that need a scoped variable (e.g. color mode).
 export function spawnScript(
   script: string,
   args: string[],
   cwd: string,
   json: boolean,
+  env?: Record<string, string>,
 ): ScriptResult {
   // For node invocations (script === process.execPath) the seam stem is derived
   // from args[0] so each spawned script has its own override key.
@@ -114,7 +116,7 @@ export function spawnScript(
   const result = spawnSync(bin, spawnArgs, {
     cwd,
     encoding: 'utf8',
-    env: process.env,
+    env: env ? { ...process.env, ...env } : process.env,
     maxBuffer: 64 * 1024 * 1024,
   });
   if (result.error) {