@deeeed/metamask-harness 0.26.5 → 0.27.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.27.0 - 2026-07-31
+
+### Changed
+
+- Mobile UI actions now record bounded native-hierarchy observations, while defaulted Extension UI actions record screen and visible observations; Extension screenshots and recordings publish through symlink-safe private staging as regular `0600` files, Mobile launch and diagnostics resolve absolute device-tool paths, and iOS preparation enables application accessibility before relaunching.
+
+### Fixed
+
+- Serve analytics capture on both IPv4 and IPv6 loopback so Mobile clients resolving `localhost` to `::1` can reach the collector without exposing it on external interfaces.
+
 ## 0.26.5 - 2026-07-31
 
 ### Fixed

package/adapters/mobile/open-device.sh

@@ -25,6 +25,7 @@ PLATFORM="ios"
 TARGET="$PWD"
 SIMULATOR="${IOS_SIMULATOR:-${SIM_UDID:-booted}}"
 ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
+ADB_BIN="${MM_HARNESS_ADB_PATH:-}"
 PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
 UI_ONLY=false
@@ -54,6 +55,17 @@ case "$PLATFORM" in
   ios|android) ;;
   *) printf 'open-device: --platform must be ios or android (got: %s)\n' "$PLATFORM" >&2; exit 2 ;;
 esac
+if [ "$PLATFORM" = "android" ]; then
+  if [ -z "$ADB_BIN" ]; then
+    ADB_BIN="$(command -v adb 2>/dev/null || true)"
+  fi
+  if [ -z "$ADB_BIN" ] || [ "${ADB_BIN#/}" = "$ADB_BIN" ] || [ ! -x "$ADB_BIN" ]; then
+    printf 'open-device: Android SDK Platform-Tools (adb) is required but no executable was found.\n' >&2
+    printf 'Next: brew install android-platform-tools\n' >&2
+    exit 1
+  fi
+  export MM_HARNESS_ADB_PATH="$ADB_BIN"
+fi
 if $UI_ONLY && [ "$PLATFORM" != "ios" ]; then
   printf 'open-device: --ui-only is supported only for ios.\n' >&2
   exit 2
@@ -207,7 +219,7 @@ focus_simulator() {
 android_app_installed() {
   local pkg="$1"
   shift
-  adb "$@" shell pm list packages 2>/dev/null | grep -q "package:${pkg}"
+  "$ADB_BIN" "$@" shell pm list packages 2>/dev/null | grep -q "package:${pkg}"
 }
 
 run_android_native_build() {
@@ -315,14 +327,14 @@ else
   [ -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 || \
+  "$ADB_BIN" "${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
     if $RESTART; then
-      adb "${ADB_ARGS[@]}" shell am force-stop "$PKG" >/dev/null 2>&1 || true
+      "$ADB_BIN" "${ADB_ARGS[@]}" shell am force-stop "$PKG" >/dev/null 2>&1 || true
       printf 'Restarting Android dev client %s\n' "$PKG" >&2
     fi
 
@@ -331,7 +343,7 @@ else
     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 \
+    if "$ADB_BIN" "${ADB_ARGS[@]}" shell am start \
         -a android.intent.action.VIEW \
         -d "$DEEP_LINK" >/dev/null 2>&1; then
       LAUNCHED=true

package/dist/adapters/mobile/prepare.js

@@ -1,5 +1,7 @@
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { recordDepsBaseline } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { resolveAndExportMobileToolPaths } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
 import { runnerDir } from "../../paths.js";
 import {
@@ -33,6 +35,14 @@ async function prepareMobile(target, opts = {}) {
   const preflightMode = opts.preflightMode ?? "fast";
   const clearMetro = opts.clearMetro ?? false;
   const restartApp = opts.restartApp ?? false;
+  try {
+    resolveAndExportMobileToolPaths(platform);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!json) process.stderr.write(`${message}
+`);
+    return { status: EXIT.runtime, output: message };
+  }
   const report = await decideMobileReadiness(target, {
     watcherPort: opts.watcherPort,
     metroLog: opts.metroLog,
@@ -49,8 +59,9 @@ async function prepareMobile(target, opts = {}) {
 `);
     return { status: EXIT.runtime, output: msg };
   }
+  const iosAccessibilityChanged = platform === "ios" && report.decision !== "unknown" && enableIosAccessibility(json);
   if (report.decision === "ready") {
-    if (restartApp) {
+    if (restartApp || iosAccessibilityChanged) {
       const launch2 = await dispatchActionSequence(
         withAppRestart(launchActions(path.resolve(target)), true),
         target,
@@ -91,7 +102,10 @@ async function prepareMobile(target, opts = {}) {
       );
     }
     const launch = await dispatchActionSequence(
-      withAppRestart(launchActions(path.resolve(target)), restartApp),
+      withAppRestart(
+        launchActions(path.resolve(target)),
+        restartApp || iosAccessibilityChanged
+      ),
       target,
       platform,
       json,
@@ -110,7 +124,7 @@ async function prepareMobile(target, opts = {}) {
     clearMetro ? report.actions.map(
       (a) => a.id === "start-metro" && !a.argv?.includes("--clear") ? { ...a, argv: [...a.argv ?? [], "--clear"] } : a
     ) : report.actions,
-    restartApp
+    restartApp || iosAccessibilityChanged
   );
   const actionResult = await dispatchActionSequence(
     actions,
@@ -158,7 +172,10 @@ async function prepareMobile(target, opts = {}) {
       }
       case "launch": {
         const result = await dispatchActionSequence(
-          withAppRestart(postInstall.actions, restartApp),
+          withAppRestart(
+            postInstall.actions,
+            restartApp || iosAccessibilityChanged
+          ),
           target,
           platform,
           json,
@@ -240,6 +257,99 @@ async function dispatchActionSequence(requestedActions, target, platform, json,
   }
   return { status: 0, output: "" };
 }
+function enableIosAccessibility(json) {
+  const simulator = process.env.SIM_UDID || process.env.IOS_SIMULATOR || "booted";
+  const defaultsArgs = [
+    "simctl",
+    "spawn",
+    simulator,
+    "defaults"
+  ];
+  try {
+    execFileSync("xcrun", ["simctl", "boot", simulator], {
+      stdio: "ignore",
+      timeout: 15e3
+    });
+  } catch {
+  }
+  try {
+    execFileSync("xcrun", ["simctl", "bootstatus", simulator, "-b"], {
+      stdio: "ignore",
+      timeout: 12e4
+    });
+  } catch (error) {
+    if (!json) {
+      process.stderr.write(
+        `mobile prepare: selected iOS simulator was unavailable (${error instanceof Error ? error.message : String(error)}); continuing with native-view fallback.
+`
+      );
+    }
+    return false;
+  }
+  try {
+    const current = execFileSync(
+      "xcrun",
+      [...defaultsArgs, "read", "com.apple.Accessibility", "ApplicationAccessibilityEnabled"],
+      {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5e3
+      }
+    ).trim().toLowerCase();
+    if (current === "1" || current === "true" || current === "yes") return false;
+  } catch {
+  }
+  try {
+    execFileSync(
+      "xcrun",
+      [
+        ...defaultsArgs,
+        "write",
+        "com.apple.Accessibility",
+        "ApplicationAccessibilityEnabled",
+        "-bool",
+        "YES"
+      ],
+      {
+        stdio: "ignore",
+        timeout: 5e3
+      }
+    );
+    try {
+      execFileSync("xcrun", ["simctl", "shutdown", simulator], {
+        stdio: "ignore",
+        timeout: 15e3
+      });
+    } catch {
+    }
+    try {
+      execFileSync("xcrun", ["simctl", "boot", simulator], {
+        stdio: "ignore",
+        timeout: 15e3
+      });
+    } catch {
+    }
+    execFileSync("xcrun", ["simctl", "bootstatus", simulator, "-b"], {
+      stdio: "ignore",
+      timeout: 12e4
+    });
+    if (!json) {
+      process.stderr.write(
+        `Enabled iOS application accessibility on ${simulator}; restarted the simulator before app launch.
+`
+      );
+    }
+    return true;
+  } catch (error) {
+    if (!json) {
+      process.stderr.write(
+        `mobile prepare: iOS accessibility enablement was unavailable (${error instanceof Error ? error.message : String(error)}); continuing with native-view fallback.
+`
+      );
+    }
+    return false;
+  }
+}
 async function dispatchAction(action, target, platform, json, preflightMode = "fast", watcherPort) {
   const cwd = action.cwd ?? target;
   switch (action.id) {

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

@@ -13,6 +13,7 @@ import {
 } from "@farmslot/recipe-harness/runtime/log-analysis";
 import { probeMetroPackager } from "@farmslot/recipe-harness/runtime/metro-probe";
 import { recipeRuntimePath } from "../../paths.js";
+import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { mobileProductMarkers } from "./deps-markers.js";
 import { applyMobileMetroEnvPolicy, mobileMetroEnvCheck } from "./metro-env.js";
 const BUNDLE_ERR = /Bundling failed|Unable to resolve /u;
@@ -66,9 +67,11 @@ const installActions = (target) => [
 function appRunningOnDevice(platform) {
   try {
     if (platform === "android") {
+      const adbPath = resolveMobileToolPath("adb");
+      if (!adbPath) return false;
       const serial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL;
       const args = serial ? ["-s", serial] : [];
-      const out2 = execFileSync("adb", [...args, "shell", "ps", "-A"], {
+      const out2 = execFileSync(adbPath, [...args, "shell", "ps", "-A"], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"],
         timeout: 5e3

package/dist/adapters.js

@@ -5,6 +5,7 @@ import {
 } from "./live-adapter-contract.js";
 import { withExtensionPage } from "../library/actions/extension/platform/cdp.mjs";
 import { bridgeCommand, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
+import { observeNativeUi } from "../library/actions/mobile/platform/observe-ui.mjs";
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -276,7 +277,8 @@ const MOBILE_BRIDGE_HANDLERS = {
   setInput: handleMobileSetInput,
   scroll: handleMobileScroll,
   waitFor: handleMobileWaitFor,
-  hud: handleMobileHud
+  hud: handleMobileHud,
+  observeUi: handleMobileObserveUi
 };
 function createMetaMaskMobileBridge() {
   return {
@@ -302,6 +304,20 @@ async function handleMobileScreenshot(payload, context) {
 async function handleMobileStatus(payload, context) {
   return bridgeCommand(mobileUiInput(context, "status", payload), ["status"]);
 }
+async function handleMobileObserveUi(payload, context) {
+  try {
+    await bridgeCommand(
+      mobileUiInput(context, "observe", {
+        ...payload,
+        bridge_timeout_ms: 2e3,
+        cdp_timeout_ms: 2e3
+      }),
+      ["hide-step"]
+    );
+  } catch {
+  }
+  return observeNativeUi(payload, context);
+}
 async function handleMobileNavigate(payload, context) {
   const live = await runLiveAdapterScript({
     platform: "mobile",
@@ -496,7 +512,8 @@ function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
       );
     }
   });
-  const transport = {
+  return {
+    ...base.observe ? { observe: base.observe.bind(base) } : {},
     async execute(action, node, context) {
       if (action === "ui.navigate") {
         const live = await runLiveFirst(
@@ -513,10 +530,6 @@ function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
       return base.execute(action, action === "ui.wait_for" ? normalizeUiWaitNode(node) : node, context);
     }
   };
-  if (base.observe) {
-    transport.observe = (refs, node, context) => base.observe(refs, node, context);
-  }
-  return transport;
 }
 function normalizeUiWaitNode(node) {
   if (node.expected !== void 0 || typeof node.visible !== "boolean") return node;

package/dist/commands/device-target.js

@@ -1,12 +1,15 @@
 import { execFileSync } from "node:child_process";
+import { resolveMobileToolPath } from "../../library/actions/mobile/platform/tool-paths.mjs";
 import { listConnectedDevices } from "../devices.js";
 import { optionString, shellQuoteArg, targetPath } from "./parse-args.js";
 function normalizeDeviceName(value) {
   return value.replace(/_/gu, " ").trim();
 }
 function resolveAndroidModel(serial) {
+  const adbPath = resolveMobileToolPath("adb");
+  if (!adbPath) return void 0;
   try {
-    const output = execFileSync("adb", ["-s", serial, "shell", "getprop", "ro.product.model"], {
+    const output = execFileSync(adbPath, ["-s", serial, "shell", "getprop", "ro.product.model"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5e3

package/dist/commands/doctor.js

@@ -131,7 +131,31 @@ async function handleDoctor({ options }) {
     }
     return status === "pass" ? 0 : 1;
   }
-  const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
+  const mobilePlatform = adapter === "mobile" && (platformOption === "ios" || platformOption === "android") ? platformOption : void 0;
+  const result = createDoctorReport(
+    adapter,
+    target,
+    manifestValidation,
+    actionManifestPath,
+    mobilePlatform
+  );
+  const missingRequiredTool = result.checks.find(
+    (check) => check.required && check.status === "fail" && check.id.startsWith("device-tool-") && check.userAction
+  );
+  if (missingRequiredTool) {
+    const error = {
+      code: "DOCTOR_CHECKS_FAILED",
+      message: missingRequiredTool.message,
+      userAction: missingRequiredTool.userAction
+    };
+    if (json) {
+      console.log(JSON.stringify({ ...result, ready: false, error }, null, 2));
+    } else {
+      console.error(`\u2717 doctor: ${error.message}
+  Next: ${error.userAction}`);
+    }
+    return EXIT.runtime;
+  }
   let runtime;
   let runtimeProbeError;
   try {
@@ -178,7 +202,9 @@ async function handleDoctor({ options }) {
       printReady
     );
   }
-  const doctorUserAction = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+  const doctorUserAction = doctorResult.checks.find(
+    (check) => check.required && check.status === "fail" && check.userAction
+  )?.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
   const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
   const next = doctorError?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
   if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));

package/dist/commands/mobile-device-view.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { resolveMobileToolPath } from "../../library/actions/mobile/platform/tool-paths.mjs";
 import { listConnectedDevices } from "../devices.js";
 import { renderDeviceList, scopedDevices } from "./device-target.js";
 import { probeMobileLiveState } from "./status-probe.js";
@@ -116,8 +117,10 @@ function selectedAndroidPortHints(devices, liveMap) {
   }).filter((hint) => hint.reversePorts.length > 0);
 }
 function androidReversePorts(serial) {
+  const adbPath = resolveMobileToolPath("adb");
+  if (!adbPath) return [];
   try {
-    const out = execFileSync("adb", ["-s", serial, "reverse", "--list"], {
+    const out = execFileSync(adbPath, ["-s", serial, "reverse", "--list"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5e3

package/dist/devices.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 function listConnectedDevices(platform) {
   const devices = [];
   if (!platform || platform === "android") devices.push(...listAndroidDevices());
@@ -6,9 +7,11 @@ function listConnectedDevices(platform) {
   return devices;
 }
 function listAndroidDevices() {
+  const adbPath = resolveMobileToolPath("adb");
+  if (!adbPath) return [];
   let output;
   try {
-    output = execFileSync("adb", ["devices", "-l"], {
+    output = execFileSync(adbPath, ["devices", "-l"], {
       encoding: "utf8",
       timeout: 5e3,
       stdio: ["ignore", "pipe", "ignore"]

package/dist/doctor.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { color } from "./cli-color.js";
+import {
+  mobileToolRecovery,
+  resolveMobileToolPath
+} from "../library/actions/mobile/platform/tool-paths.mjs";
 import { mobilePerpsEnvironment } from "./adapters/mobile/perps-env.js";
 import { readRuntimeContextField, resolveRuntimeContextPath } from "./harness.js";
 import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
@@ -128,7 +132,7 @@ function renderRuntimeContext(runtimeContext) {
   }
   return lines.join("\n");
 }
-function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter)) {
+function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter), mobilePlatform) {
   const mode = compatibilityMode(adapter, target);
   const manifestErrors = Number(manifestValidation.summary?.errors ?? 0);
   const checks = [
@@ -143,7 +147,8 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
       status: mode === "unsupported/no bridge" ? "fail" : "pass",
       required: false,
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
-    }
+    },
+    ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
@@ -164,6 +169,23 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
     manifestValidation: manifestValidation.summary
   };
 }
+function mobileToolDoctorChecks(platform) {
+  const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
+    { tool: "adb", platform: "Android" },
+    { tool: "idb", platform: "iOS" }
+  ];
+  return specs.map(({ tool, platform: platformName }) => {
+    const resolved = resolveMobileToolPath(tool);
+    return {
+      id: `device-tool-${tool}`,
+      status: resolved ? "pass" : "fail",
+      required: platform !== void 0,
+      message: resolved ? `${platformName} device tool ${tool} is ready.` : `${platformName} device tool ${tool} is unavailable.`,
+      ...resolved ? { detail: resolved } : {},
+      ...!resolved ? { userAction: mobileToolRecovery(tool) } : {}
+    };
+  });
+}
 function runnerInstallKind(runnerRoot, invokedPath, executablePath) {
   const normalizedRoot = path.normalize(runnerRoot);
   const nodeModulesSegment = `${path.sep}node_modules${path.sep}`;
@@ -230,6 +252,7 @@ export {
   createDoctorReport,
   fixtureFileSummary,
   fixtureSummary,
+  mobileToolDoctorChecks,
   renderRuntimeContext,
   repoShape,
   requiredDoctorCheckSummary,