@deeeed/metamask-harness 0.26.5 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.28.0 - 2026-07-31
+
+### Added
+
+- Add `actions --matrix` and adapter-aware action refusals that name missing capabilities and list the adapters that satisfy them.
+- Add `ui.locators` for ranked, copy-pasteable recipe targets derived from the current Extension or Mobile `ui.visible` observation.
+
+## 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,9 @@ async function handleMobileScreenshot(payload, context) {
 async function handleMobileStatus(payload, context) {
   return bridgeCommand(mobileUiInput(context, "status", payload), ["status"]);
 }
+async function handleMobileObserveUi(payload, context) {
+  return observeNativeUi(payload, context);
+}
 async function handleMobileNavigate(payload, context) {
   const live = await runLiveAdapterScript({
     platform: "mobile",
@@ -496,7 +501,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 +519,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/cli-commands.js

@@ -15,7 +15,7 @@ const SPEC = {
     { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
-    { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--categories", "--category", "--action", "--library"] },
+    { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--matrix", "--categories", "--category", "--action", "--library"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { name: "execution-template", desc: "Discover and materialize shared agent checklists", args: ["list", "materialize", "lint", "new"], flags: ["--dir", "--domain-dir", "--project-worker", "--project-name", "--package-templates", "--package-id", "--flow", "--run-mode", "--platform", "--domain", "--id", "--provenance", "--include-shadowed", "--no-include-shadowed", "--title", "--force", "--json"] },

package/dist/command-contract.js

@@ -117,6 +117,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
   actions: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
       "--action": value(),
+      "--matrix": bool(),
       "--categories": bool(),
       "--category": value(),
       "--action-manifest": value(),

package/dist/commands/call.js

@@ -6,7 +6,14 @@ import { importRecipeProtocol } from "../paths.js";
 import { conciseFailureForHuman, recipeRunning } from "../heal-bounds.js";
 import { color } from "../cli-color.js";
 import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
-import { actionExampleCommand, describeManifestActions, fuzzyResolveActions } from "./manifest.js";
+import {
+  actionLibraryContextArgs,
+  actionExampleCommand,
+  describeManifestActions,
+  fuzzyResolveActions,
+  resolveActionCapabilityMatrix,
+  resolveActionCapabilityRefusal
+} from "./manifest.js";
 import {
   parseArgs,
   isRecord,
@@ -112,6 +119,36 @@ async function handleCall(argv) {
   const names = getRecipeActionManifestActionNames(manifest);
   const resolution = resolveActionName(shortName, names);
   if (resolution.status === "unknown") {
+    const refusal = actionManifestOverride ? void 0 : resolveActionCapabilityRefusal(
+      shortName,
+      adapter,
+      await resolveActionCapabilityMatrix(librarySources)
+    );
+    if (refusal) {
+      const satisfying = refusal.satisfyingAdapters.join(", ");
+      const message2 = `missing action capability "${refusal.capability}" for the ${adapter} adapter.`;
+      const userAction2 = `Satisfying adapters for "${refusal.capability}": ${satisfying}. Inspect: mm-harness actions --matrix --action ${shellQuote(refusal.capability)}${actionLibraryContextArgs(librarySources)} --json`;
+      const error = {
+        code: "ACTION_CAPABILITY_UNAVAILABLE",
+        message: message2,
+        capability: refusal.capability,
+        satisfyingAdapters: refusal.satisfyingAdapters,
+        userAction: userAction2
+      };
+      if (json) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "call",
+          adapter,
+          action: shortName,
+          error
+        }, null, 2));
+      } else {
+        console.error(`\u2717 call: ${message2}
+  Next: ${userAction2}`);
+      }
+      return EXIT.usage;
+    }
     const message = `unknown action "${shortName}" for the ${adapter} adapter.`;
     const userAction = `mm-harness actions --adapter ${adapter} --json`;
     if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));

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));