@deeeed/metamask-harness 0.41.1 → 0.42.0

package/adapters/mobile/bridge-runtime/lib/devtools-proxy.cjs

@@ -0,0 +1,177 @@
+'use strict';
+
+const fs = require('node:fs');
+const { WebSocket, WebSocketServer } = require('ws');
+
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const SESSION_TIMEOUT_MS = 10_000;
+const EVENT_GATED_DOMAINS = new Set([
+  'Debugger',
+  'Log',
+  'Network',
+  'Page',
+  'ReactNativeApplication',
+  'Runtime',
+]);
+
+function createDevtoolsProxy({
+  descriptorPath,
+  sessions,
+  sendCommand,
+  requestDiscovery,
+  allowedOrigins,
+}) {
+  if (!Array.isArray(allowedOrigins) || allowedOrigins.length === 0) {
+    throw new Error('DevTools proxy requires at least one allowed Origin');
+  }
+  let listeningPort = null;
+  const clients = new Set();
+  const server = new WebSocketServer({
+    host: '127.0.0.1',
+    port: 0,
+    maxPayload: MAX_FRAME_BYTES,
+  });
+
+  async function waitForSession(deviceId) {
+    const ready = sessions.get(deviceId);
+    if (ready?.brokerReady) return ready;
+    requestDiscovery();
+    const deadline = Date.now() + SESSION_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      const session = sessions.get(deviceId);
+      if (session?.brokerReady) return session;
+    }
+    throw new Error('Hermes runtime is unavailable or reloading; retry the command');
+  }
+
+  function writeDescriptor() {
+    if (!listeningPort) return;
+    fs.writeFileSync(
+      descriptorPath,
+      `${JSON.stringify({ schemaVersion: 1, pid: process.pid, port: listeningPort })}\n`,
+      { mode: 0o600 },
+    );
+  }
+
+  async function forward(client, message) {
+    if (
+      !message ||
+      typeof message !== 'object' ||
+      !Number.isInteger(message.id) ||
+      typeof message.method !== 'string'
+    ) {
+      return;
+    }
+    if (message.method.endsWith('.disable')) {
+      client.enabled.delete(message.method.replace(/\.disable$/u, '.enable'));
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(JSON.stringify({ id: message.id, result: {} }));
+      }
+      return;
+    }
+    const isEnable = message.method.endsWith('.enable');
+    if (isEnable) {
+      client.enabled.set(message.method, message.params || {});
+    }
+    try {
+      const session = await waitForSession(client.deviceId);
+      const result = await sendCommand(
+        session,
+        message.method,
+        message.params || {},
+        SESSION_TIMEOUT_MS,
+      );
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(JSON.stringify({ id: message.id, result }));
+      }
+    } catch (error) {
+      if (isEnable) client.enabled.delete(message.method);
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(
+          JSON.stringify({
+            id: message.id,
+            error: {
+              code: -32000,
+              message: String(error?.message || error).slice(0, 256),
+            },
+          }),
+        );
+      }
+    }
+  }
+
+  server.on('connection', (socket, request) => {
+    const url = new URL(request.url || '/', 'http://127.0.0.1');
+    const deviceId = url.searchParams.get('device');
+    if (
+      !deviceId ||
+      !allowedOrigins.includes(request.headers.origin)
+    ) {
+      socket.close(1008, 'invalid DevTools proxy Origin or device');
+      return;
+    }
+    for (const client of clients) {
+      if (client.deviceId === deviceId) {
+        client.socket.close(1000, 'replaced by a newer DevTools window');
+      }
+    }
+    const client = { socket, deviceId, enabled: new Map() };
+    clients.add(client);
+    socket.on('message', (data) => {
+      let message;
+      try {
+        message = JSON.parse(String(data));
+      } catch {
+        return;
+      }
+      void forward(client, message);
+    });
+    const drop = () => clients.delete(client);
+    socket.on('close', drop);
+    socket.on('error', drop);
+  });
+
+  server.on('listening', () => {
+    const address = server.address();
+    if (!address || typeof address === 'string') return;
+    listeningPort = address.port;
+    writeDescriptor();
+  });
+
+  return {
+    onSessionOpen(deviceId, session) {
+      for (const client of clients) {
+        if (client.deviceId !== deviceId) continue;
+        for (const [method, params] of client.enabled) {
+          void sendCommand(session, method, params, SESSION_TIMEOUT_MS).catch(
+            () => undefined,
+          );
+        }
+      }
+    },
+    onCdpEvent(deviceId, method, params) {
+      const payload = JSON.stringify({ method, params });
+      const domain = method.split('.', 1)[0];
+      for (const client of clients) {
+        if (
+          client.deviceId === deviceId &&
+          client.socket.readyState === WebSocket.OPEN &&
+          (!EVENT_GATED_DOMAINS.has(domain) ||
+            client.enabled.has(`${domain}.enable`))
+        ) {
+          client.socket.send(payload);
+        }
+      }
+    },
+    close() {
+      for (const client of clients) client.socket.close();
+      server.close();
+      try {
+        fs.unlinkSync(descriptorPath);
+      } catch {}
+    },
+  };
+}
+
+module.exports = { createDevtoolsProxy };

package/adapters/mobile/bridge-runtime/lib/target-discovery.cjs

@@ -138,7 +138,7 @@ function targetDeviceIdentity(target) {
  *     page 1 = native C++ runtime, page 2+ = JS runtime (where __AGENTIC__ lives)
  *   - We probe candidates to find the one with __AGENTIC__ installed
  */
-async function discoverTarget(port) {
+async function discoverTarget(port, { probe = true } = {}) {
   const listUrl = `http://localhost:${port}/json/list`;
   const androidTargetName = loadAndroidTargetDeviceName();
   const androidDevice = loadAndroidDevice();
@@ -162,7 +162,7 @@ async function discoverTarget(port) {
       if (androidPinned) {
         const pinnedCandidates = runtimeCandidates.filter(matchesAndroidPin);
         for (const candidate of pinnedCandidates) {
-          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+          if (!probe || (await probeTarget(candidate.webSocketDebuggerUrl))) {
             acceptedPinnedCandidate = candidate;
             return true;
           }
@@ -174,7 +174,7 @@ async function discoverTarget(port) {
           (candidate) => candidate.deviceName === simName,
         );
         for (const candidate of pinnedCandidates) {
-          if (await probeTarget(candidate.webSocketDebuggerUrl)) {
+          if (!probe || (await probeTarget(candidate.webSocketDebuggerUrl))) {
             acceptedPinnedCandidate = candidate;
             return true;
           }
@@ -307,6 +307,16 @@ async function discoverTarget(port) {
     }
   }
 
+  // The persistent console forwarder already owns and validates brokered CDP
+  // sessions. Re-probing here would evict that debugger; preserve the normal
+  // platform/device filtering and select the highest-ranked runtime instead.
+  if (!probe) {
+    return {
+      wsUrl: candidates[0].webSocketDebuggerUrl,
+      deviceName: candidates[0].deviceName || '',
+    };
+  }
+
   // Sort by page number descending (JS runtime has higher page number than C++
   // native). rankRuntimeCandidates output arrives pre-sorted; this re-sort is
   // load-bearing only when the raw targets.filter() fallback above repopulated

package/adapters/mobile/reload-app.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const WebSocket = require('ws');
+
+function parseArgs(argv) {
+  const args = { port: process.env.WATCHER_PORT || process.env.METRO_PORT || '8081', json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === '--port') args.port = argv[++index];
+    else if (argv[index] === '--json') args.json = true;
+    else if (argv[index] === '--help' || argv[index] === '-h') {
+      console.log('Usage: reload-app.mjs [--port <Metro port>] [--json]');
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${argv[index]}`);
+    }
+  }
+  return args;
+}
+
+async function reload(port) {
+  const numericPort = Number.parseInt(String(port), 10);
+  if (!Number.isInteger(numericPort) || numericPort <= 0) {
+    throw new Error(`Metro port is invalid: ${port}`);
+  }
+  await new Promise((resolve, reject) => {
+    const socket = new WebSocket(`ws://127.0.0.1:${numericPort}/message`);
+    const timeout = setTimeout(() => {
+      socket.close();
+      reject(new Error(`Metro reload timed out on port ${numericPort}`));
+    }, 5000);
+    socket.on('open', () => {
+      socket.send(JSON.stringify({ method: 'reload', version: 2 }));
+      setTimeout(() => {
+        clearTimeout(timeout);
+        socket.close();
+        resolve();
+      }, 50);
+    });
+    socket.on('error', () => {
+      clearTimeout(timeout);
+      reject(new Error(`Metro is not reachable on port ${numericPort}`));
+    });
+  });
+  return {
+    ok: true,
+    adapter: 'mobile',
+    method: 'metro-message',
+    command: 'reload',
+    port: numericPort,
+  };
+}
+
+const args = parseArgs(process.argv.slice(2));
+reload(args.port)
+  .then((result) => {
+    if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else console.log(`Reload requested through Metro :${result.port}`);
+  })
+  .catch((error) => {
+    const result = { ok: false, adapter: 'mobile', error: String(error?.message || error) };
+    if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else console.error(result.error);
+    process.exitCode = 1;
+  });

package/adapters/mobile/start-console-forwarder.sh

@@ -32,12 +32,27 @@ APP_LOG_FILE="$LOG_DIR/app-console.log"
 { [ -f "$FORWARDER" ] && command -v node >/dev/null 2>&1; } || exit 0
 mkdir -p "$LOG_DIR"
 
+stopped_pids=()
+stop_forwarder() {
+  local pid="$1"
+  case " ${stopped_pids[*]-} " in
+    *" $pid "*) return ;;
+  esac
+  stopped_pids+=("$pid")
+  kill "$pid" 2>/dev/null || true
+  for _ in {1..20}; do
+    kill -0 "$pid" 2>/dev/null || return
+    sleep 0.05
+  done
+  kill -KILL "$pid" 2>/dev/null || true
+}
+
 # One debugger owns a React Native page. Reap any collector for this Metro port,
 # including one left by an older globally installed harness.
 while read -r pid cmd; do
   case "$cmd" in
     *console-forwarder.cjs*" --port $PORT "*|*console-forwarder.cjs*" --port=$PORT "*)
-      kill "$pid" 2>/dev/null || true
+      stop_forwarder "$pid"
       ;;
   esac
 done < <(ps -axo pid=,command= 2>/dev/null || true)
@@ -46,7 +61,7 @@ if [ -f "$PID_FILE" ]; then
   old_pid="$(cat "$PID_FILE" 2>/dev/null || true)"
   if [ -n "$old_pid" ]; then
     case "$(ps -p "$old_pid" -o command= 2>/dev/null)" in
-      *console-forwarder.cjs*) kill "$old_pid" 2>/dev/null || true ;;
+      *console-forwarder.cjs*) stop_forwarder "$old_pid" ;;
     esac
   fi
   rm -f "$PID_FILE"

package/adapters/mobile/start-metro.sh

@@ -4,8 +4,8 @@
 # Checks if Metro is already running and owned by this checkout with required env vars.
 # Clears stale or foreign listeners before starting. Uses the checkout's canonical
 # yarn watch script and sets EXPO_NO_TYPESCRIPT_SETUP=1. Cache clearing is
-# injected as Expo --clear without invoking Mobile's global watchman cleanup.
-# Metro owns its default worker count; METRO_MAX_WORKERS is an explicit override.
+# passed to Expo only for the explicit --clear option. Metro defaults to four
+# workers; METRO_MAX_WORKERS remains an explicit override.
 #
 # Inputs:
 #   --target <metamask-mobile dir>  (default $PWD)
@@ -227,8 +227,8 @@ fi
 
 stop_metro_listener || exit 1
 
-METRO_WORKERS="${METRO_MAX_WORKERS:-}"
-if [ -n "$METRO_WORKERS" ] && ! printf '%s' "$METRO_WORKERS" | grep -Eq '^[1-9][0-9]*$'; then
+METRO_WORKERS="${METRO_MAX_WORKERS:-4}"
+if ! printf '%s' "$METRO_WORKERS" | grep -Eq '^[1-9][0-9]*$'; then
   printf 'start-metro: METRO_MAX_WORKERS must be a positive integer, got %s\n' "$METRO_WORKERS" >&2
   exit 2
 fi
@@ -240,13 +240,8 @@ fi
 CLEAR_LABEL=""
 [ "$CLEAR" = true ] && CLEAR_LABEL=", clear"
 
-if [ -n "$METRO_WORKERS" ]; then
-  printf 'Starting Metro on port %s (workers=%s%s)\n' \
-    "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
-else
-  printf 'Starting Metro on port %s (workers=Metro default%s)\n' \
-    "$PORT" "$CLEAR_LABEL" >&2
-fi
+printf 'Starting Metro on port %s (workers=%s%s)\n' \
+  "$PORT" "$METRO_WORKERS" "$CLEAR_LABEL" >&2
 printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FILE" >&2
 
 [ -f "$METRO_LOG_GENERATION" ] && [ -f "$METRO_LOG_COALESCER" ] || {

package/adapters/mobile/stop-metro.sh

@@ -21,7 +21,7 @@ while [ $# -gt 0 ]; do
   esac
 done
 
-TARGET="$(cd "$TARGET" && pwd)"
+TARGET="$(cd "$TARGET" && pwd -P)"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck disable=SC1091
@@ -102,6 +102,15 @@ if [ -f "$TMUX_FILE" ] && command -v tmux >/dev/null 2>&1; then
 fi
 rm -f "$TMUX_FILE"
 
+# A stopped checkout must not remain in Watchman's global root set. Metro will
+# add the root again on the next launch; removing only this exact target keeps
+# every other active slot untouched.
+if command -v watchman >/dev/null 2>&1; then
+  if watchman watch-del "$TARGET" >/dev/null 2>&1; then
+    printf 'Removed Watchman root %s\n' "$TARGET" >&2
+  fi
+fi
+
 # Reaching here = cleanup done (nothing needed stopping, or it stopped and
 # windows/pids were cleared). The idempotent-stop contract is success; do not
 # leak an incidental non-zero from the last command on any platform.

package/adapters/shared/open-debug.mjs

@@ -2,12 +2,23 @@
 /**
  * open-debug.mjs — open human-facing debugger UIs for recipe runtimes.
  *
- * Mobile: Metro /open-debugger or /open-dev-menu HTTP endpoints.
+ * Mobile: broker-backed React Native DevTools or Metro /open-dev-menu.
  * Extension: Chrome DevTools frontend for an extension page or service worker.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
 import http from 'node:http';
 import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const {
+  discoverTarget,
+} = require('../mobile/bridge-runtime/lib/target-discovery.cjs');
+const {
+  deviceIdFromUrl,
+} = require('../mobile/bridge-runtime/lib/cdp-broker.cjs');
 
 function usage() {
   console.error(`Usage:
@@ -236,6 +247,9 @@ async function tryDevSettingsCdpFallback(numericPort, normalizedAction) {
 
 async function openMobileDebugger(port, action, shouldOpen) {
   const normalizedAction = action === 'dev-menu' ? 'dev-menu' : 'debug';
+  if (normalizedAction === 'debug') {
+    return openBrokeredMobileDebugger(port, shouldOpen);
+  }
   const urlPath = normalizedAction === 'dev-menu' ? '/open-dev-menu' : '/open-debugger';
   const numericPort = Number.parseInt(String(port), 10);
   if (!Number.isInteger(numericPort) || numericPort <= 0) {
@@ -302,6 +316,162 @@ async function openMobileDebugger(port, action, shouldOpen) {
   };
 }
 
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function openBrokeredMobileDebugger(port, shouldOpen) {
+  const numericPort = Number.parseInt(String(port), 10);
+  if (!Number.isInteger(numericPort) || numericPort <= 0) {
+    return { ok: false, adapter: 'mobile', action: 'debug', error: 'invalid-port', port };
+  }
+  const runtimeDir = path.resolve(
+    process.cwd(),
+    process.env.RECIPE_RUNTIME_DIR || path.join('temp', 'recipe', 'runtime'),
+  );
+  const descriptorPath = path.join(runtimeDir, 'devtools-proxy.json');
+  let descriptor;
+  try {
+    descriptor = JSON.parse(fs.readFileSync(descriptorPath, 'utf8'));
+  } catch {
+    descriptor = null;
+  }
+  if (
+    descriptor?.schemaVersion !== 1 ||
+    !Number.isInteger(descriptor.port) ||
+    descriptor.port <= 0 ||
+    !processIsAlive(descriptor.pid)
+  ) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'broker-unavailable',
+      port: numericPort,
+      hint: 'Start the Mobile runtime first: mm-harness launch ios|android',
+    };
+  }
+
+  let target;
+  try {
+    const selected = await discoverTarget(numericPort, { probe: false });
+    const targets = await fetchJson(`http://127.0.0.1:${numericPort}/json/list`);
+    const selectedUrl = new URL(selected.wsUrl);
+    target = targets.find(
+      (candidate) => {
+        try {
+          const candidateUrl = new URL(candidate.webSocketDebuggerUrl);
+          return (
+            candidateUrl.pathname === selectedUrl.pathname &&
+            candidateUrl.search === selectedUrl.search
+          );
+        } catch {
+          return false;
+        }
+      },
+    );
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'target-unavailable',
+      port: numericPort,
+      hint: 'Wait for the app runtime, then retry: mm-harness debug',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+  if (!target?.webSocketDebuggerUrl) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'target-unavailable',
+      port: numericPort,
+      hint: 'Wait for the app runtime, then retry: mm-harness debug',
+    };
+  }
+
+  const deviceId = deviceIdFromUrl(target.webSocketDebuggerUrl);
+  const proxyPath = `/devtools?device=${encodeURIComponent(deviceId)}`;
+  const publicProxyEndpoint = `ws://127.0.0.1:${descriptor.port}${proxyPath}`;
+  const params = new URLSearchParams([
+    ['ws', `127.0.0.1:${descriptor.port}${proxyPath}`],
+    ['sources.hide_add_folder', 'true'],
+    ['unstable_enableNetworkPanel', 'true'],
+  ]);
+  if (target.appId) params.set('appId', target.appId);
+  const frontendUrl = `http://127.0.0.1:${numericPort}/debugger-frontend/rn_fusebox.html?${params}`;
+  if (!shouldOpen) {
+    return {
+      ok: true,
+      adapter: 'mobile',
+      action: 'debug',
+      method: 'broker-proxy',
+      endpoint: publicProxyEndpoint,
+      port: numericPort,
+      opened: false,
+    };
+  }
+
+  try {
+    const mobileRequire = createRequire(path.join(process.cwd(), 'package.json'));
+    const dotslash = mobileRequire('fb-dotslash');
+    const shellPackage = mobileRequire.resolve(
+      '@react-native/debugger-shell/package.json',
+    );
+    const shellDescriptor = path.join(
+      path.dirname(shellPackage),
+      'bin',
+      'react-native-devtools',
+    );
+    const windowKey = createHash('sha256')
+      .update([frontendUrl, target.appId || '', deviceId].join('-'))
+      .digest('hex');
+    await new Promise((resolve, reject) => {
+      const child = spawn(
+        dotslash,
+        [
+          shellDescriptor,
+          `--frontendUrl=${frontendUrl}`,
+          `--windowKey=${windowKey}`,
+        ],
+        { detached: true, stdio: 'ignore' },
+      );
+      child.once('spawn', resolve);
+      child.once('error', reject);
+      child.unref();
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      adapter: 'mobile',
+      action: 'debug',
+      error: 'devtools-launch-failed',
+      endpoint: publicProxyEndpoint,
+      port: numericPort,
+      hint: 'Install the checkout dependencies, then retry: mm-harness debug',
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  return {
+    ok: true,
+    adapter: 'mobile',
+    action: 'debug',
+    method: 'broker-proxy',
+    endpoint: publicProxyEndpoint,
+    port: numericPort,
+    opened: true,
+  };
+}
+
 function pickExtensionTarget(targets, targetKind) {
   const extensionTargets = targets.filter((target) => String(target.url || '').startsWith('chrome-extension://'));
   if (targetKind === 'worker') {