@deeeed/metamask-harness 0.2.0 → 0.3.1

package/{orchestration → adapters}/mobile/inject.sh

@@ -42,21 +42,21 @@ done
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 RUNNER_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd -P)"
-ADAPTER_DIR="$RUNNER_DIR/library/actions/mobile"
-# compat-overlays: NOT applied here. orchestration/compat-overlays/ holds
+ADAPTER_DIR="$RUNNER_DIR/adapters/mobile"
+# compat-overlays: NOT applied here. adapters/mobile/overlay/compat/ holds
 # reversible patches applied only when injecting into HISTORICAL checkouts
 # (replay/eval against old product commits, e.g. pre-RN-0.81 mobile); the
 # operator/recipe-harness skill applies them manually before the rebuild.
-# See orchestration/compat-overlays/README.md.
+# See adapters/mobile/overlay/compat/README.md.
 # shellcheck disable=SC1091
-. "$SCRIPT_DIR/../lib/hash-helpers.sh"
+. "$SCRIPT_DIR/../shared/hash-helpers.sh"
 # shellcheck disable=SC1091
-for _hp in "$SCRIPT_DIR/../lib/harness-path.sh"; do
+for _hp in "$SCRIPT_DIR/../shared/harness-path.sh"; do
   [ -f "$_hp" ] && { . "$_hp"; break; }
 done
 unset _hp
 if ! command -v harness_root >/dev/null 2>&1; then
-  echo "mm-harness: shared lib orchestration/lib/harness-path.sh not found; reinstall the runner." >&2
+  echo "mm-harness: shared lib adapters/shared/harness-path.sh not found; reinstall the runner." >&2
   exit 1
 fi
 TARGET="$(cd "$TARGET" && pwd)"
@@ -134,7 +134,7 @@ install_v1_runner_assets() {
   # quote — cannot break the generated wrapper or inject at runtime.
   local runner_protocol_root_q runner_exec_q target_q
   runner_protocol_root_q="$(printf '%q' "$METAMASK_RUNNER_PROTOCOL_ROOT")"
-  runner_exec_q="$(printf '%q' "$METAMASK_RUNNER_DIR/orchestration/porcelain/metamask-recipe")"
+  runner_exec_q="$(printf '%q' "$METAMASK_RUNNER_DIR/bin/mm-harness")"
   target_q="$(printf '%q' "$TARGET")"
   {
     printf '%s\n' '#!/usr/bin/env bash'
@@ -175,8 +175,8 @@ install_v1_runner_assets() {
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
     printf 'exec %s "$@"\n' "$runner_exec_q"
-  } > "$HARNESS_DIR/runner/bin/metamask-recipe"
-  chmod +x "$HARNESS_DIR/runner/bin/metamask-recipe"
+  } > "$HARNESS_DIR/runner/bin/mm-harness"
+  chmod +x "$HARNESS_DIR/runner/bin/mm-harness"
   if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
     printf '%s\n' "$METAMASK_RUNNER_PROTOCOL_ROOT" > "$HARNESS_DIR/runner/.farmslot-root"
   fi
@@ -199,19 +199,19 @@ install_v1_runner_assets() {
   # Installed-layout back-compat (INTENTIONAL): targets keep a flat
   # <harness>/scripts/ subtree assembled from the runner trees, so installed
   # consumers are unaffected by runner-repo layout changes.
-  if [ -d "$METAMASK_RUNNER_DIR/orchestration/mobile" ]; then
+  if [ -d "$METAMASK_RUNNER_DIR/adapters/mobile" ]; then
     mkdir -p "$HARNESS_DIR/scripts"
-    cp "$METAMASK_RUNNER_DIR/orchestration/mobile/launch.sh" "$HARNESS_DIR/scripts/launch.sh"
-    cp "$METAMASK_RUNNER_DIR/orchestration/mobile/live.sh" "$HARNESS_DIR/scripts/live.sh"
-    cp "$METAMASK_RUNNER_DIR/runner/mobile/verify.sh" "$HARNESS_DIR/scripts/verify.sh"
+    # launch and live orchestration is now in-process (src/harness.ts + src/adapters/mobile/prepare.ts).
+    # Remove any copies left by older installs so stale scripts cannot shadow the in-process path.
+    rm -f "$HARNESS_DIR/scripts/launch.sh" "$HARNESS_DIR/scripts/live.sh"
+    cp "$METAMASK_RUNNER_DIR/adapters/mobile/verify.sh" "$HARNESS_DIR/scripts/verify.sh"
     mkdir -p "$HARNESS_DIR/scripts/lib"
-    cp "$METAMASK_RUNNER_DIR/orchestration/lib/harness-path.sh" "$HARNESS_DIR/scripts/lib/harness-path.sh"
-    cp "$METAMASK_RUNNER_DIR/orchestration/lib/path-defaults.json" "$HARNESS_DIR/scripts/lib/path-defaults.json"
-    cp "$METAMASK_RUNNER_DIR/orchestration/lib/recipe-paths.mjs" "$HARNESS_DIR/scripts/lib/recipe-paths.mjs"
+    cp "$METAMASK_RUNNER_DIR/adapters/shared/harness-path.sh" "$HARNESS_DIR/scripts/lib/harness-path.sh"
+    cp "$METAMASK_RUNNER_DIR/adapters/shared/path-defaults.json" "$HARNESS_DIR/scripts/lib/path-defaults.json"
     chmod -R u+rwX,go+rX "$HARNESS_DIR/scripts"
     find "$HARNESS_DIR/scripts" -type f \( -name '*.sh' -o -name '*.cjs' -o -name '*.mjs' \) -exec chmod +x {} +
   fi
-  if [ ! -x "$HARNESS_DIR/runner/bin/metamask-recipe" ]; then
+  if [ ! -x "$HARNESS_DIR/runner/bin/mm-harness" ]; then
     echo "Refusing mobile recipe harness install: failed to make runner executable." >&2
     return 1
   fi
@@ -288,10 +288,8 @@ if [ "$FORCE_OVERLAY" = false ] && has_product_owned_mobile_harness; then
       target,
       protocolVersion: "v1",
       actionManifestPath: harnessRel + "/action-manifest.json",
-      runnerEntrypoint: harnessRel + "/runner/bin/metamask-recipe",
+      runnerEntrypoint: harnessRel + "/runner/bin/mm-harness",
       runtimeHelpers: {
-        launch: harnessRel + "/scripts/launch.sh",
-        live: harnessRel + "/scripts/live.sh",
         verify: harnessRel + "/scripts/verify.sh"
       },
       installedPaths: [],
@@ -527,7 +525,7 @@ install_v1_runner_assets
 
 mkdir -p "$TARGET/app/dev-tools/AgenticService"
 while IFS= read -r -d '' overlay_file; do
-  rel="${overlay_file#$ADAPTER_DIR/app-overlay/app/dev-tools/AgenticService/}"
+  rel="${overlay_file#$ADAPTER_DIR/overlay/app/dev-tools/AgenticService/}"
   dest_rel="${rel%.patch}"
   dest="$TARGET/app/dev-tools/AgenticService/$dest_rel"
   mkdir -p "$(dirname "$dest")"
@@ -537,7 +535,7 @@ while IFS= read -r -d '' overlay_file; do
   # Exclude overlay *.test.* files: they are source tests for the overlay
   # templates and must not ship into the product checkout, where the product's
   # jest could pick them up on local runs.
-done < <(find "$ADAPTER_DIR/app-overlay/app/dev-tools/AgenticService" -type f ! -name '*.test.*' -print0)
+done < <(find "$ADAPTER_DIR/overlay/app/dev-tools/AgenticService" -type f ! -name '*.test.*' -print0)
 
 node - "$TARGET" <<'NODE'
 const fs = require('fs');
@@ -654,7 +652,7 @@ node -e '
     target,
     protocolVersion: "v1",
     actionManifestPath: harnessRel + "/action-manifest.json",
-    runnerEntrypoint: harnessRel + "/runner/bin/metamask-recipe",
+    runnerEntrypoint: harnessRel + "/runner/bin/mm-harness",
     runtimeHelpers: {
       launch: harnessRel + "/scripts/launch.sh",
       live: harnessRel + "/scripts/live.sh",
@@ -673,7 +671,7 @@ node -e '
   fs.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
 ' "$RUNNER_DIR" "$SOURCE_REV" "$METAMASK_RUNNER_DIR" "$METAMASK_RUNNER_REVISION" "$METAMASK_RUNNER_SOURCE_KIND" "$ADAPTER_DIR" "$TARGET" "$BACKUP_DIR" "$SCRIPT_DIR" "$HARNESS_DIR/manifest.json" "${MOBILE_AGENTIC_SOURCE:-}" "$HARNESS_ROOT" "$HARNESS_REL" "$CLEANUP_COMMAND"
 
-ENSURE_DEPS="$SCRIPT_DIR/../lib/ensure-runner-deps.sh"
+ENSURE_DEPS="$SCRIPT_DIR/../shared/ensure-runner-deps.sh"
 if [ -f "$ENSURE_DEPS" ]; then
   bash "$ENSURE_DEPS" "$RUNNER_DIR"
 fi

package/adapters/mobile/open-device.sh

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+# open-device — open the MetaMask Mobile dev client on a simulator or device.
+#
+# iOS: boots simulator if needed, writes EXDevMenuIsOnboardingFinished default,
+# then opens via the expo-development-client deep link (disableOnboarding=1).
+# Android: sets adb reverse for Metro port reachability, then opens via deep link.
+# Preflight-mode guard: fast (teaching error if not installed), auto (install if missing),
+# rebuild-native / clean (always rebuild), default (same as auto).
+#
+# Inputs:
+#   --platform ios|android              (default ios)
+#   --target <metamask-mobile dir>      (default $PWD)
+#   --simulator <udid|name|"booted">    iOS simulator (default: IOS_SIMULATOR env, else "booted")
+#   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
+#   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
+# Outputs:
+#   Progress on stderr; exit 0 pass; 1 open failed; 2 bad args.
+#
+# Single device op: open the dev client. Does not start Metro or install node_modules.
+set -uo pipefail
+
+PLATFORM="ios"
+TARGET="$PWD"
+SIMULATOR="${IOS_SIMULATOR:-${SIM_UDID:-booted}}"
+ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
+PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --platform)       PLATFORM="$2"; shift 2 ;;
+    --target)         TARGET="$2"; shift 2 ;;
+    --simulator)      SIMULATOR="$2"; shift 2 ;;
+    --adb-serial)     ADB_SERIAL_ARG="$2"; shift 2 ;;
+    --preflight-mode) PREFLIGHT_MODE="$2"; shift 2 ;;
+    --port)           PORT="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: open-device.sh [--platform ios|android] [--target <dir>]\n'
+      printf '  [--simulator <udid|name|booted>] [--adb-serial <serial>]\n'
+      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>]\n'
+      exit 0
+      ;;
+    *) printf 'open-device: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+case "$PLATFORM" in
+  ios|android) ;;
+  *) printf 'open-device: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
+esac
+
+TARGET="$(cd "$TARGET" && pwd)"
+
+# --- iOS helpers --------------------------------------------------------------
+
+ios_app_installed() {
+  local sim_target="$1" bundle_id="$2"
+  xcrun simctl get_app_container "$sim_target" "$bundle_id" app >/dev/null 2>&1
+}
+
+run_ios_native_build() {
+  local sim_target="$1" reason="$2"
+  printf '%s; installing with yarn start:ios (WATCHER_PORT=%s)\n' "$reason" "$PORT" >&2
+  (cd "$TARGET" && WATCHER_PORT="$PORT" METRO_PORT="$PORT" IOS_SIMULATOR="$sim_target" EXPO_NO_TYPESCRIPT_SETUP=1 yarn start:ios 2>&1)
+}
+
+ensure_ios_app_for_mode() {
+  local sim_target="$1" bundle_id="$2" mode="$3"
+  case "$mode" in
+    fast)
+      if ios_app_installed "$sim_target" "$bundle_id"; then return 0; fi
+      printf >&2 'open-device: fast mode requires an installed iOS dev client (%s) on %s.\n' \
+        "$bundle_id" "$sim_target"
+      printf >&2 'Fast mode only prewarms the bundle and opens the existing client.\n'
+      printf >&2 'Next: use --preflight-mode auto to install if missing.\n'
+      return 1
+      ;;
+    auto|default)
+      if ios_app_installed "$sim_target" "$bundle_id"; then return 0; fi
+      run_ios_native_build "$sim_target" "iOS dev client ${bundle_id} not installed on ${sim_target}"
+      ;;
+    rebuild-native|clean)
+      run_ios_native_build "$sim_target" "Rebuilding iOS dev client ${bundle_id} (--preflight-mode ${mode})"
+      ;;
+    *)
+      printf 'open-device: unknown --preflight-mode: %s\n' "$mode" >&2; return 2 ;;
+  esac
+}
+
+sim_udid_for_target() {
+  local target="$1"
+  # Already a UDID
+  if printf '%s' "$target" | grep -Eq '^[0-9A-Fa-f-]{36}$'; then
+    printf '%s\n' "$target"; return 0
+  fi
+  xcrun simctl list devices available 2>/dev/null \
+    | sed -n "s/.*${target} (\([0-9A-Fa-f-]*\)) (.*/\1/p" | head -1
+}
+
+boot_simulator_if_needed() {
+  local target="$1" state=""
+  [ "$target" != "booted" ] || return 0
+  local line=""
+  line="$(xcrun simctl list devices available 2>/dev/null | grep -F "${target} (" | head -1 || true)"
+  case "$line" in *"(Booted)"*) state="Booted" ;; *"(Shutdown)"*) state="Shutdown" ;; esac
+  [ "$state" = "Booted" ] && return 0
+  printf 'Booting iOS simulator %s%s\n' "$target" "${state:+ ($state)}" >&2
+  xcrun simctl boot "$target" 2>/dev/null || true
+  xcrun simctl bootstatus "$target" -b >/dev/null
+}
+
+show_simulator() {
+  local target="$1" udid=""
+  if [ "$target" = "booted" ]; then
+    printf 'Opening Simulator UI\n' >&2
+    open -a Simulator >/dev/null 2>&1 || true
+  else
+    udid="$(sim_udid_for_target "$target")"
+    if [ -n "$udid" ]; then
+      open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
+    else
+      open -a Simulator >/dev/null 2>&1 || true
+    fi
+  fi
+  osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
+}
+
+# --- Android helpers ----------------------------------------------------------
+
+android_app_installed() {
+  local pkg="$1"
+  shift
+  adb "$@" shell pm list packages 2>/dev/null | grep -q "package:${pkg}"
+}
+
+run_android_native_build() {
+  local reason="$1"
+  printf '%s; installing with yarn start:android (WATCHER_PORT=%s)\n' "$reason" "$PORT" >&2
+  (cd "$TARGET" && WATCHER_PORT="$PORT" yarn start:android 2>&1)
+}
+
+ensure_android_app_for_mode() {
+  local pkg="$1" mode="$2"
+  shift 2
+  case "$mode" in
+    fast)
+      if android_app_installed "$pkg" "$@"; then return 0; fi
+      printf >&2 'open-device: fast mode requires an installed Android dev client (%s).\n' "$pkg"
+      printf >&2 'Next: use --preflight-mode auto to install if missing.\n'
+      return 1
+      ;;
+    auto|default)
+      if android_app_installed "$pkg" "$@"; then return 0; fi
+      run_android_native_build "Android dev client ${pkg} not installed"
+      ;;
+    rebuild-native|clean)
+      run_android_native_build "Rebuilding Android dev client ${pkg} (--preflight-mode ${mode})"
+      ;;
+    *)
+      printf 'open-device: unknown --preflight-mode: %s\n' "$mode" >&2; return 2 ;;
+  esac
+}
+
+# URL-encode using python3 (same as baseline).
+urlencode() {
+  python3 - "$1" <<'PY'
+import sys, urllib.parse
+print(urllib.parse.quote(sys.argv[1], safe=''))
+PY
+}
+
+# --- dispatch -----------------------------------------------------------------
+
+BUNDLE_IDS=("${IOS_BUNDLE_ID:-io.metamask.MetaMask}" "io.metamask" "io.metamask.flask" "io.metamask.qa")
+ANDROID_PKGS=("${ANDROID_PACKAGE_ID:-io.metamask}" "io.metamask.flask" "io.metamask.qa")
+
+if [ "$PLATFORM" = "ios" ]; then
+  SIM_TARGET="$SIMULATOR"
+  # Expo dev-client URL scheme — drives both the deep link and the scheme-approval key.
+  DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
+
+  boot_simulator_if_needed "$SIM_TARGET"
+  show_simulator "$SIM_TARGET"
+
+  LAUNCHED=false
+  for BUNDLE_ID in "${BUNDLE_IDS[@]}"; do
+    ensure_ios_app_for_mode "$SIM_TARGET" "$BUNDLE_ID" "$PREFLIGHT_MODE" || continue
+
+    # Dismiss Expo dev-menu onboarding for clean headless runs.
+    xcrun simctl spawn "$SIM_TARGET" defaults write "$BUNDLE_ID" \
+      EXDevMenuIsOnboardingFinished -bool YES 2>/dev/null || true
+
+    # Pre-approve the dev-client deep-link scheme so openurl never pauses on the
+    # "Open in <App>?" dialog. The key encodes the CoreSimulator bridge + scheme;
+    # the value is the bundle ID of the approved handler.
+    xcrun simctl spawn "$SIM_TARGET" defaults write \
+      com.apple.launchservices.schemeapproval \
+      "com.apple.CoreSimulator.CoreSimulatorBridge-->${DEV_CLIENT_SCHEME}" \
+      -string "$BUNDLE_ID" 2>/dev/null || true
+
+    # Open via expo-development-client deep link so the app connects to our Metro.
+    ENCODED_URL="$(urlencode "http://localhost:${PORT}?disableOnboarding=1" 2>/dev/null \
+      || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"
+    DEEP_LINK="${DEV_CLIENT_SCHEME}://expo-development-client/?url=${ENCODED_URL}"
+
+    printf 'Launching iOS dev client %s on %s\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
+    if xcrun simctl openurl "$SIM_TARGET" "$DEEP_LINK" 2>/dev/null; then
+      LAUNCHED=true
+      printf 'open-device: iOS dev client opened (%s on %s)\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
+      break
+    fi
+    # Fallback: plain launch (older Expo / non-development-client build).
+    if xcrun simctl launch "$SIM_TARGET" "$BUNDLE_ID" 2>/dev/null; then
+      LAUNCHED=true
+      printf 'open-device: iOS dev client launched (fallback) (%s on %s)\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
+      break
+    fi
+  done
+
+  if [ "$LAUNCHED" = false ]; then
+    printf 'open-device: no MetaMask bundle found on simulator %s\n' "$SIM_TARGET" >&2
+    printf '  tried: %s\n' "${BUNDLE_IDS[*]}" >&2
+    exit 1
+  fi
+
+else
+  ADB_ARGS=()
+  [ -n "$ADB_SERIAL_ARG" ] && ADB_ARGS+=("-s" "$ADB_SERIAL_ARG")
+
+  # Reverse-tunnel Metro port so the device can reach localhost:PORT.
+  adb "${ADB_ARGS[@]}" reverse "tcp:${PORT}" "tcp:${PORT}" >/dev/null 2>&1 || \
+    printf 'open-device: adb reverse failed (non-fatal — device may already be reachable)\n' >&2
+
+  LAUNCHED=false
+  for PKG in "${ANDROID_PKGS[@]}"; do
+    ensure_android_app_for_mode "$PKG" "$PREFLIGHT_MODE" "${ADB_ARGS[@]}" || continue
+
+    ENCODED_URL="$(urlencode "http://localhost:${PORT}?disableOnboarding=1" 2>/dev/null \
+      || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"
+    DEEP_LINK="expo-metamask://expo-development-client/?url=${ENCODED_URL}"
+
+    printf 'Launching Android dev client %s\n' "$PKG" >&2
+    if adb "${ADB_ARGS[@]}" shell am start \
+        -a android.intent.action.VIEW \
+        -d "$DEEP_LINK" >/dev/null 2>&1; then
+      LAUNCHED=true
+      printf 'open-device: Android dev client opened (%s)\n' "$PKG" >&2
+      break
+    fi
+  done
+
+  if [ "$LAUNCHED" = false ]; then
+    printf 'open-device: no MetaMask package found on Android device %s\n' \
+      "${ADB_SERIAL_ARG:-<default>}" >&2
+    printf '  tried: %s\n' "${ANDROID_PKGS[*]}" >&2
+    exit 1
+  fi
+fi
+
+printf '  Next: mm-harness logs   # tail Metro\n' >&2

package/{orchestration/compat-overlays → adapters/mobile/overlay/compat}/README.md

@@ -7,13 +7,22 @@ up empty here by design: the feature's purpose is non-current checkouts.
 
 - Purpose: make historical product checkouts bootable/bridgeable under the
   current local toolchain so Recipe v1 evals can replay against them.
-- When it applies: mobile checkouts predating React Native 0.81 polyfill
-  fixes (see mobile/README.md for the per-patch details).
+- When it applies: mobile checkouts predating React Native 0.81 polyfill fixes.
 - How it is applied: MANUALLY (no automatic apply logic in this repo).
   The operator or the `/recipe-harness` skill applies the patch reversibly
   before a historical rebuild (`git apply <patch>` in the product checkout,
   `git apply -R` to remove) and records the overlay path in validation
-  evidence. `orchestration/mobile/inject.sh` does NOT apply these.
+  evidence. `adapters/mobile/inject.sh` does NOT apply these.
 
-Listed in orchestration/manifest.json (kind: compat-overlay) so the doctor
+Kept in the external runner repository, not Farmslot root scripts, so a
+`/recipe-harness` skill can apply the same reversible overlay before a
+historical rebuild and record the overlay path in validation evidence.
+
+Listed in adapters/manifest.json (kind: compat-overlay) so the doctor
 verifies the surface and this directory is never flagged as unused again.
+
+## Patches
+
+- `rn81-message-event-source.patch`: adds a read-only `MessageEvent.prototype.source`
+  getter for React Native 0.81 historical checkouts whose bundled polyfill omits
+  it while CDP websocket clients expect browser-compatible `MessageEvent` shape.

package/adapters/mobile/prewarm-bundle.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# prewarm-bundle — curl the Metro bundle URL before the dev client opens.
+#
+# Triggers Metro to compile and cache the bundle so the app connects instantly.
+# Streams progress from the Metro log every 30s until the bundle curl finishes
+# or MOBILE_BUNDLE_PREWARM_TIMEOUT seconds elapse.
+# Set MOBILE_BUNDLE_PREWARM=0 to skip.
+#
+# Inputs:
+#   --platform ios|android          (default ios)
+#   --target <metamask-mobile dir>  (default $PWD)
+#   --port <number>                 (default WATCHER_PORT env, else METRO_PORT, else 8081)
+# Outputs:
+#   Progress on stderr; exit 0 bundle ready; 1 timeout or curl error; 2 bad args.
+#
+# Single device op: prewarm the bundle. Does not start Metro or open the dev client.
+set -uo pipefail
+
+PLATFORM="ios"
+TARGET="$PWD"
+PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --platform) PLATFORM="$2"; shift 2 ;;
+    --target)   TARGET="$2"; shift 2 ;;
+    --port)     PORT="$2"; shift 2 ;;
+    -h|--help)
+      printf 'Usage: prewarm-bundle.sh [--platform ios|android] [--target <dir>] [--port <n>]\n'
+      exit 0
+      ;;
+    *) printf 'prewarm-bundle: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+case "$PLATFORM" in
+  ios|android) ;;
+  *) printf 'prewarm-bundle: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
+esac
+
+TARGET="$(cd "$TARGET" && pwd)"
+LOG_DIR="$TARGET/temp/recipe/runtime"
+mkdir -p "$LOG_DIR"
+METRO_LOG="$LOG_DIR/metro.log"
+
+if [ "${MOBILE_BUNDLE_PREWARM:-1}" = "0" ]; then
+  printf 'Skipping %s bundle prewarm (MOBILE_BUNDLE_PREWARM=0)\n' "$PLATFORM" >&2
+  exit 0
+fi
+
+TIMEOUT="${MOBILE_BUNDLE_PREWARM_TIMEOUT:-900}"
+
+BUNDLE_URL="http://localhost:${PORT}/index.bundle?platform=${PLATFORM}&dev=true&hot=false&lazy=true&transform.engine=hermes&transform.bytecode=1&transform.routerRoot=app&unstable_transformProfile=hermes-stable"
+
+printf 'Prewarming %s bundle before launching dev client (set MOBILE_BUNDLE_PREWARM=0 to skip)\n' "$PLATFORM" >&2
+printf '  url: %s\n' "$BUNDLE_URL" >&2
+
+curl -sfL --connect-timeout 5 --max-time "$TIMEOUT" -o /dev/null "$BUNDLE_URL" &
+BUNDLE_PID=$!
+
+ELAPSED=0
+LAST_PROGRESS=""
+while kill -0 "$BUNDLE_PID" 2>/dev/null; do
+  PROGRESS=""
+  if [ -f "$METRO_LOG" ]; then
+    PROGRESS="$(grep -E '^[[:space:]]*(iOS|Android).*index\.(js|tsx?).*%|Bundl(ed|ing)|Finished' "$METRO_LOG" 2>/dev/null | tail -1 | tr -d '\r' || true)"
+  fi
+  if [ -n "$PROGRESS" ] && [ "$PROGRESS" != "$LAST_PROGRESS" ]; then
+    printf 'Bundle progress: %s\n' "$PROGRESS" >&2
+    LAST_PROGRESS="$PROGRESS"
+  elif [ $((ELAPSED % 30)) -eq 0 ] && [ "$ELAPSED" -gt 0 ]; then
+    printf 'Waiting for %s bundle (%ss/%ss)%s\n' "$PLATFORM" "$ELAPSED" "$TIMEOUT" \
+      "${LAST_PROGRESS:+ — $LAST_PROGRESS}" >&2
+  fi
+  if [ "$ELAPSED" -ge "$TIMEOUT" ]; then
+    kill "$BUNDLE_PID" 2>/dev/null || true
+    wait "$BUNDLE_PID" 2>/dev/null || true
+    printf 'prewarm-bundle: %s bundle did not become ready before timeout (%ss)\n' "$PLATFORM" "$TIMEOUT" >&2
+    [ -f "$METRO_LOG" ] && tail -80 "$METRO_LOG" >&2 || true
+    printf '  Next: check %s for errors or reduce MOBILE_BUNDLE_PREWARM_TIMEOUT\n' "$METRO_LOG" >&2
+    exit 1
+  fi
+  sleep 3
+  ELAPSED=$((ELAPSED + 3))
+done
+
+if wait "$BUNDLE_PID"; then
+  printf '%s bundle ready\n' "$PLATFORM" >&2
+  exit 0
+fi
+
+printf 'prewarm-bundle: %s bundle curl failed\n' "$PLATFORM" >&2
+[ -f "$METRO_LOG" ] && tail -80 "$METRO_LOG" >&2 || true
+printf '  Next: check %s for Metro errors\n' "$METRO_LOG" >&2
+exit 1