@deeeed/metamask-harness 0.8.0 → 0.9.1

package/docs/CLI-SPEC.md

@@ -439,7 +439,9 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ## `--device <id>` — first-class mobile device targeting (REAL)
 
-`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. It sets the **same env `launch` does** before the engine reads `process.env`, so the engine needs no changes: an Android serial → `ADB_SERIAL` + `ANDROID_SERIAL` + `ANDROID_DEVICE`; an iOS UDID/simulator name → `IOS_SIMULATOR`. The android-vs-ios decision comes from matching the id against the connected-device lists (`adb devices -l` + booted `xcrun simctl` simulators); an id that matches neither list is a teaching usage error that lists the connected devices.
+`--device` is the uniform mobile device selector on `run`, `call`, and `doctor`. Pass the **adb serial** for Android (from `adb devices`) or the **UDID / simulator name** for iOS. The harness resolves the adb serial to the Metro CDP target identity internally — users never need to know or set `ANDROID_DEVICE='Pixel 6 - 16 - API 36'`.
+
+**Internal Android identity mapping**: `ADB_SERIAL` / `ANDROID_SERIAL` carry the raw adb serial. The bridge resolves the device model via `adb -s <serial> shell getprop ro.product.model` and propagates it as `ANDROID_TARGET_DEVICE_NAME`. Target-discovery uses `ANDROID_TARGET_DEVICE_NAME` for Metro `deviceName` prefix matching (e.g. `"Pixel 6"` matches `"Pixel 6 - 16 - API 36"`). When the pinned model cannot be matched to any Metro `/json/list` candidate and multiple candidates exist, the bridge fails fast with a diagnostic listing every candidate's `deviceName` — it never silently selects the wrong device. iOS UDID/simulator name → `IOS_SIMULATOR` (unchanged).
 
 | Verb | `--device` given | `--device` omitted (mobile) |
 |---|---|---|
@@ -450,7 +452,7 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ## `status` (aliases `health`, `home`) — home dashboard + devices[] (REAL)
 
-`status` is the compact home dashboard for a checkout: the detected adapter, the next command to run (`next`), and — for **mobile** checkouts — a `devices[]` section. Extension/core checkouts report an empty `devices[]` (CDP tab detail is out of scope). Additive envelope:
+`status` is the compact home dashboard for a checkout: the detected adapter, the next command to run (`next`), and — for **mobile** checkouts — a `devices[]` section with live app state. Extension/core checkouts report an empty `devices[]`. Additive envelope:
 
 ```json
 {
@@ -459,14 +461,49 @@ Readiness check for a checkout without launching the app. Doctor is the single p
   "adapter": "mobile",
   "target": "/path/to/checkout",
   "devices": [
-    { "platform": "android", "id": "emulator-5554", "name": "Pixel_6", "state": "device", "selected": true },
-    { "platform": "ios", "id": "AAAA-BBBB", "name": "iPhone 15", "state": "Booted", "selected": false }
+    {
+      "platform": "android", "id": "emulator-5554", "name": "Pixel_6",
+      "state": "device", "selected": true,
+      "currentScreen": "Wallet", "walletState": "unlocked",
+      "selectedAccount": { "label": "Account 1", "address": "0xabcd…ef12" },
+      "fixtureStatus": "READY"
+    },
+    {
+      "platform": "ios", "id": "AAAA-BBBB", "name": "iPhone 15",
+      "state": "Booted", "selected": false,
+      "fixtureStatus": "READY", "liveState": "no-bridge"
+    }
   ],
   "next": "mm-harness launch ios"
 }
 ```
 
-`selected` is `true` when the device id matches the current `ADB_SERIAL`/`ANDROID_SERIAL` (android) or `IOS_SIMULATOR` (ios) env. `doctor --json` carries the same `devices[]` shape (with `selected`) for mobile checkouts.
+**Per-device live fields** (additive — absent or null when unreachable):
+
+| Field | Type | Description |
+|---|---|---|
+| `currentScreen` | string | Active route/screen in the running app (mobile bridge `status` route field) |
+| `walletState` | `'locked'\|'unlocked'\|'onboarding'` | Derived from bridge status: account present → unlocked; onboarding route → onboarding; else locked |
+| `selectedAccount` | `{ label, address }` | Active account name + address truncated to `0x1234…abcd` form |
+| `fixtureStatus` | `'READY'\|'missing'` | Checkout-level: whether `wallet-fixture.json` is present and well-formed |
+| `liveState` | `'no-bridge'\|'bridge-absent'` | Set when the bridge is unreachable/times out (`no-bridge`) or the target answers but `__AGENTIC__` is absent (`bridge-absent`); live fields omitted in both cases |
+
+**`--fast` flag:** skips all live-state probes. Output is instant (same envelope shape, live fields absent). Safe for scripts and CI where probe latency is unacceptable.
+
+**Human output** is progressive: static info (adapter, device list, next) prints immediately; a `live:` block appends after the ~2s probe window closes. `--fast` suppresses the live block entirely.
+
+`selected` is `true` when the device id matches `ADB_SERIAL`/`ANDROID_SERIAL` (android) or `IOS_SIMULATOR` (ios) env. `doctor --json` carries the same `devices[]` shape (with `selected`) for mobile checkouts.
+
+The mobile bridge probes all connected RN targets in one call and returns an array; each device is matched to its entry by name or platform-uniqueness, so multi-device checkouts (e.g. Android + iOS simulator) receive per-device live state.
+
+`liveState` in the JSON envelope (absent = fully enriched):
+
+| Value | Meaning |
+|---|---|
+| `'no-bridge'` | No matching/responding target on Metro — bridge genuinely unreachable or app not running. |
+| `'bridge-absent'` | Target IS reachable and answered Runtime.evaluate, but `typeof globalThis.__AGENTIC__ === 'undefined'` — the installed build predates the bridge. Reinstall a dev build to get live state. |
+
+Extension/core live-state probing (CDP home-tab route) is V1-pending — use `doctor` for runtime status.
 
 **Exit:** 0 (2 when the repo type cannot be detected).
 

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

@@ -1,8 +1,11 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const execFileAsync = promisify(execFile);
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -34,7 +37,30 @@ function runtimeDir() {
   return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime', import.meta.url));
 }
 
-export function bridgeEnv(input) {
+/**
+ * Resolve the Android model name from an adb serial.
+ * Returns the trimmed ro.product.model value, or null when adb is unavailable
+ * or the serial does not respond. Uses execFile (never shell interpolation).
+ */
+async function resolveAndroidModel(adbSerial) {
+  try {
+    const { stdout } = await execFileAsync(
+      'adb',
+      ['-s', adbSerial, 'shell', 'getprop', 'ro.product.model'],
+      { timeout: 5000, encoding: 'utf8' },
+    );
+    const model = stdout.trim();
+    return model || null;
+  } catch {
+    // Recovery is correct: model resolution for Metro target selection is advisory.
+    // If adb is unavailable or the serial is unreachable, discovery falls through to
+    // the exact ANDROID_DEVICE match or probe-and-pick. The error will surface from
+    // the CDP connection attempt if the wrong target is selected.
+    return null;
+  }
+}
+
+export async function bridgeEnv(input) {
   /** @type {NodeJS.ProcessEnv} */
   const env = {
     ...process.env,
@@ -53,6 +79,20 @@ export function bridgeEnv(input) {
     env.ADB_SERIAL = String(adbSerial);
     env.ANDROID_SERIAL = String(adbSerial);
   }
+  // When --device passes an adb serial, device-target.ts sets both ANDROID_DEVICE and
+  // ADB_SERIAL to the same value. ANDROID_DEVICE must be the Metro deviceName for
+  // target-discovery to select the right CDP target; it cannot be a raw adb serial.
+  // Resolve the device model via adb getprop and propagate it as
+  // ANDROID_TARGET_DEVICE_NAME so target-discovery can match by model prefix
+  // (e.g. "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36").
+  const serialStr = adbSerial != null ? String(adbSerial) : '';
+  const deviceStr = androidDevice != null ? String(androidDevice) : '';
+  if (serialStr && deviceStr === serialStr) {
+    const model = await resolveAndroidModel(serialStr);
+    if (model) {
+      env.ANDROID_TARGET_DEVICE_NAME = model;
+    }
+  }
   return env;
 }
 
@@ -65,13 +105,20 @@ function resolveMobileTarget(input) {
   return { watcherPort, iosSimulator, androidDevice, adbSerial };
 }
 
+// Commands where a transient undefined/empty stdout means "not yet settled", not failure.
+// get-route returns undefined mid-navigation when the route state is momentarily unavailable;
+// waitForRoute polls through these nulls rather than aborting on a parse error.
+const TRANSIENT_NULL_COMMANDS = new Set(['get-route']);
+
 export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
+  // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
+  const env = await bridgeEnv(input);
   const result = await new Promise((resolve, reject) => {
     const timeoutMs = Number(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? 30000);
     const child = spawn(process.execPath, [script, ...args], {
       cwd: input.context.projectRoot,
-      env: { ...bridgeEnv(input), APP_ROOT: input.context.projectRoot },
+      env: { ...env, APP_ROOT: input.context.projectRoot },
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     let stdout = '';
@@ -111,6 +158,14 @@ export async function bridgeCommand(input, args) {
     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))}`);
   }
+  // 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
+  // rather than aborting on a JSON parse error.
+  const command = String(args[0] ?? '');
+  const trimmedStdout = result.stdout.trim();
+  if ((trimmedStdout === '' || trimmedStdout === 'undefined') && TRANSIENT_NULL_COMMANDS.has(command)) {
+    return null;
+  }
   try {
     const parsed = JSON.parse(result.stdout);
     if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.ok === false) {
@@ -195,13 +250,35 @@ function routeName(route) {
 export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
   const expected = String(expectedRoute);
   const deadline = Date.now() + timeoutMs;
+  // lastRoute is null when bridgeCommand returns null (transient: route not yet
+  // settled mid-navigation). Null means "not ready yet" — keep polling.
   let lastRoute = null;
+  let pollCount = 0;
   while (Date.now() < deadline) {
     lastRoute = await bridgeCommand(input, ['get-route']);
     if (routeName(lastRoute) === expected) return lastRoute;
+    pollCount += 1;
     await sleep(250);
   }
-  throw new Error(`Timed out waiting for Mobile route ${expected}; last route was ${JSON.stringify(lastRoute)}`);
+  const target = resolveMobileTarget(input);
+  const deviceHint = [
+    target.adbSerial && `ADB_SERIAL=${target.adbSerial}`,
+    target.androidDevice && target.androidDevice !== target.adbSerial && `ANDROID_DEVICE=${target.androidDevice}`,
+    target.iosSimulator && `IOS_SIMULATOR=${target.iosSimulator}`,
+  ].filter(Boolean).join(', ') || 'no device pin';
+  // bridgeCommand already parsed (or null-normalized) the reply, so raw stdout is
+  // not available here — describe the reply honestly instead of relabeling the
+  // parsed value as "raw".
+  const lastReply = lastRoute === null
+    ? 'empty/undefined (route transiently unavailable — bridge not yet settled)'
+    : JSON.stringify(lastRoute);
+  throw new Error(
+    `Timed out waiting for Mobile route '${expected}' after ${timeoutMs}ms (${pollCount} polls).\n` +
+    `  Expected route: ${expected}\n` +
+    `  Last parsed route: ${JSON.stringify(lastRoute)}\n` +
+    `  Last bridge reply: ${lastReply}\n` +
+    `  Device: ${deviceHint}`,
+  );
 }
 
 export async function simulatorScreenshot(input, relPath) {

package/library/actions/mobile/wallet/setup.mjs

@@ -112,7 +112,10 @@ function setupWalletScript() {
   return fileURLToPath(new URL('../../../../adapters/mobile/bridge-runtime/setup-wallet.sh', import.meta.url));
 }
 
-function runSetupWallet(input, fixture) {
+async function runSetupWallet(input, fixture) {
+  // bridgeEnv is async (it may shell adb to resolve the Metro device name);
+  // spreading its un-awaited Promise would hand the child an almost-empty env.
+  const env = await bridgeEnv(input);
   return new Promise((resolve, reject) => {
     const timeoutMs = Number(
       input.node?.setup_timeout_ms ?? input.node?.timeout_ms ?? 120000,
@@ -122,7 +125,7 @@ function runSetupWallet(input, fixture) {
       [setupWalletScript(), '--fixture', fixture.absolutePath],
       {
         cwd: input.context.projectRoot,
-        env: { ...bridgeEnv(input), CDP_TIMEOUT: String(timeoutMs), APP_ROOT: input.context.projectRoot },
+        env: { ...env, CDP_TIMEOUT: String(timeoutMs), APP_ROOT: input.context.projectRoot },
         stdio: ['ignore', 'pipe', 'pipe'],
       },
     );