@deeeed/metamask-harness 0.14.0 → 0.14.2

package/dist/commands/launch/extension.js

@@ -4,7 +4,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
+import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
+import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { spawnScriptStreaming } from "../shared.js";
 function extensionDepsBlock(target) {
@@ -22,7 +24,7 @@ function extensionDepsBlock(target) {
   }
   return null;
 }
-async function launchExtension(target, tier, wantWatch) {
+async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
     const watchArgs = ["--target", target];
@@ -34,29 +36,53 @@ async function launchExtension(target, tier, wantWatch) {
     return extensionRebuild(target);
   }
   if (await extensionRuntimeReusable(target)) {
-    return extensionReattach(target);
+    return extensionReattach(target, displayMode);
   }
   return extensionRebuild(target);
 }
 async function extensionRuntimeReusable(target) {
-  const watcherPort = process.env.WATCHER_PORT;
   const cdpPort = process.env.CDP_PORT;
-  if (!watcherPort || !cdpPort) return false;
-  if (!portHasListener(watcherPort)) return false;
+  if (!cdpPort) return false;
+  if (!cdpOwnedByExpectedRuntime(cdpPort, target)) return false;
   if (!await cdpVersionReachable(cdpPort)) return false;
+  if (!await cdpHasExpectedExtensionTarget(cdpPort, target)) return false;
+  if (!await cdpRuntimeHealthy(cdpPort, target)) return false;
   if (isExtensionDistStale(target)) return false;
   return true;
 }
-function portHasListener(port) {
+function expectedChromeProfile(target) {
+  const profileName = process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile";
+  return path.resolve(process.env.CHROME_USER_DATA_DIR || path.join(target, recipeRuntimeDir(), profileName));
+}
+function expectedRuntimeDist(target) {
+  return path.resolve(path.join(target, recipeRuntimeDir(), process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist"));
+}
+function cdpOwnedByExpectedRuntime(port, target) {
+  let pids = [];
   try {
     const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     });
-    return out.split(/\s+/u).some((value) => /^\d+$/u.test(value));
+    pids = out.split(/\s+/u).filter((value) => /^\d+$/u.test(value));
   } catch {
     return false;
   }
+  const profile = expectedChromeProfile(target);
+  const runtimeDist = expectedRuntimeDist(target);
+  for (const pid of pids) {
+    try {
+      const command = execFileSync("ps", ["-ww", "-o", "command=", "-p", pid], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      if (command.includes(`--user-data-dir=${profile}`) && (command.includes(`--load-extension=${runtimeDist}`) || command.includes(`--disable-extensions-except=${runtimeDist}`))) {
+        return true;
+      }
+    } catch {
+    }
+  }
+  return false;
 }
 function cdpVersionReachable(port) {
   return new Promise((resolve) => {
@@ -75,9 +101,79 @@ function cdpVersionReachable(port) {
     request.on("error", () => resolve(false));
   });
 }
-async function extensionReattach(target) {
+function expectedExtensionId(target) {
+  const runtimeDir = recipeRuntimeDir();
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(target, runtimeDir, process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist", "manifest.json"), "utf8")
+    );
+    if (typeof manifest.key === "string" && manifest.key) return extensionIdFromKey(manifest.key);
+  } catch {
+  }
+  try {
+    const marker = fs.readFileSync(path.join(target, runtimeDir, "extension.id"), "utf8").trim();
+    return /^[a-p]{32}$/u.test(marker) ? marker : null;
+  } catch {
+    return null;
+  }
+}
+function cdpHasExpectedExtensionTarget(port, target) {
+  return new Promise((resolve) => {
+    const request = http.get(
+      { host: "127.0.0.1", port: Number(port), path: "/json/list", timeout: 2e3 },
+      (response) => {
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          if ((response.statusCode ?? 0) < 200 || (response.statusCode ?? 0) >= 300) {
+            resolve(false);
+            return;
+          }
+          let targets;
+          try {
+            targets = JSON.parse(body);
+          } catch {
+            resolve(false);
+            return;
+          }
+          if (!Array.isArray(targets)) {
+            resolve(false);
+            return;
+          }
+          const expectedId = expectedExtensionId(target);
+          if (!expectedId) {
+            resolve(false);
+            return;
+          }
+          resolve(targets.some((entry) => {
+            if (!entry || typeof entry !== "object") return false;
+            const candidate = entry;
+            return typeof candidate.url === "string" && candidate.url.startsWith(`chrome-extension://${expectedId}/`);
+          }));
+        });
+      }
+    );
+    request.on("timeout", () => {
+      request.destroy();
+      resolve(false);
+    });
+    request.on("error", () => resolve(false));
+  });
+}
+async function cdpRuntimeHealthy(port, target) {
+  try {
+    const report = await checkExtensionRuntimeHealth(target, Number(port), { pageMode: "home-or-sidepanel" });
+    return report.status === "PASS";
+  } catch {
+    return false;
+  }
+}
+async function extensionReattach(target, displayMode = "fullscreen") {
   const reattachScript = recipeHarnessPath(target, "extension", "scripts", "reattach.sh");
-  const reattachArgs = ["--target", target];
+  const reattachArgs = ["--target", target, "--display-mode", displayMode];
   if (process.env.CDP_PORT) reattachArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.WATCHER_PORT) reattachArgs.push("--watcher-port", process.env.WATCHER_PORT);
   if (process.env.EXTENSION_START_URL) reattachArgs.push("--start-url", process.env.EXTENSION_START_URL);

package/dist/commands/launch/index.js

@@ -35,6 +35,7 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "runway",
   "json"
 ]);
+const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
 async function handleLaunch(argv) {
   const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
@@ -85,10 +86,20 @@ async function handleLaunch(argv) {
   if (envResult && "code" in envResult) {
     return usageOut(json, "launch", envResult.message, "mm-harness launch android --device <adb-serial|device-name>");
   }
-  if (adapter === "extension" && typeof options["url"] === "string" && options["url"]) {
-    process.env.EXTENSION_START_URL = options["url"];
-  }
   const tier = wantVerify ? "verify" : wantBuild ? "build" : "quick";
+  if (adapter === "extension") {
+    const requestedUrl = typeof options["url"] === "string" && options["url"] ? options["url"] : "";
+    if (requestedUrl || displayMode === "sidepanel") {
+      process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
+    }
+  }
+  if (!json && adapter === "extension" && tier !== "verify") {
+    const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
+    const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
+    console.error(
+      `\u2192 extension launch \u2014 ${modeNote} \xB7 CDP :${process.env.CDP_PORT ?? "default"} \xB7 ${workNote}`
+    );
+  }
   const state = newHealState();
   if (tier === "quick" && nativeInputsChanged(target, adapter)) {
     return usageOut(
@@ -130,9 +141,9 @@ async function handleLaunch(argv) {
       }
     }
   }
-  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
+  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
   if (attempt.status === 0) {
-    return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);
+    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch);
   }
   if (heal === "off") {
     return launchFail(json, adapter, mobileTarget, tier, state, {
@@ -142,6 +153,32 @@ async function handleLaunch(argv) {
       exitCode: EXIT.infra
     });
   }
+  if (adapter === "extension" && tier === "quick" && extensionQuickReattachFailed(attempt.output)) {
+    const recoveryCode2 = "chrome.relaunched";
+    state.attemptedRecoveries.push(recoveryCode2);
+    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, json, displayMode);
+    if (rebuildAttempt.status === 0) {
+      state.recovered.push(recoveryCode2);
+      return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch);
+    }
+    return launchFail(json, adapter, mobileTarget, tier, state, {
+      code: "EXTENSION_RELAUNCH_FAILED",
+      message: "quick reattach failed, and clean relaunch failed too.",
+      recoverable: false,
+      exitCode: EXIT.infra,
+      originalError: rebuildAttempt.output.trim() || void 0
+    });
+  }
+  if (adapter === "mobile" && mobileProvisioningBlocked(attempt.output)) {
+    return launchFail(json, adapter, mobileTarget, tier, state, {
+      code: "MOBILE_PROVISION_REQUIRED",
+      message: `mobile ${mobileTarget ?? "runtime"} is not provisioned for this slot.`,
+      recoverable: false,
+      userAction: mobileProvisionCommand(target, mobileTarget),
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim() || void 0
+    });
+  }
   const bound = checkHealBounds(target, attempt.output, state);
   if (bound !== null) {
     return launchFail(json, adapter, mobileTarget, tier, state, {
@@ -155,10 +192,10 @@ async function handleLaunch(argv) {
   }
   const recoveryCode = RECOVERY_CODE[adapter];
   state.attemptedRecoveries.push(recoveryCode);
-  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json);
+  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
   if (attempt.status === 0) {
     state.recovered.push(recoveryCode);
-    return finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state);
+    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch);
   }
   return launchFail(json, adapter, mobileTarget, tier, state, {
     code: "SAME_RECOVERY_TWICE",
@@ -168,11 +205,35 @@ async function handleLaunch(argv) {
     originalError: attempt.output.trim() || void 0
   });
 }
+function extensionQuickReattachFailed(output) {
+  return /\[reattach\]|extension quick reattach|mm-harness launch --build/u.test(output);
+}
+function extensionRuntimeBlocked(output) {
+  return /ERR_BLOCKED_BY_CLIENT|has been blocked by Chromium/u.test(output);
+}
+function mobileProvisioningBlocked(output) {
+  return /open-device: configured iOS simulator '.+' does not exist|open-device: no MetaMask bundle found|fast mode requires an installed (?:iOS dev client|Android dev client)/u.test(output);
+}
+function mobileProvisionCommand(target, mobileTarget) {
+  const platform = mobileTarget === "android" ? "android" : "ios";
+  const device = platform === "ios" ? process.env.IOS_SIMULATOR || process.env.SIM_UDID : process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_DEVICE;
+  const parts = ["mm-harness", "provision", "runway", platform, "--adapter", "mobile", "--target", shellQuote(target)];
+  if (device) parts.push("--device", shellQuote(device));
+  return parts.join(" ");
+}
+function shellQuote(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(value)) return value;
+  return `'${value.replace(/'/gu, `'"'"'`)}'`;
+}
 function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const device = str(options, "device");
-  if (device && adapter === "mobile") {
-    const result = applyDeviceTargeting("launch", adapter, options, { gate: false, rerun: "" });
+  if (adapter === "mobile" && (device || mobileTarget === "ios" || mobileTarget === "android")) {
+    const targetingOptions = {
+      ...options,
+      ...mobileTarget && !device ? { platform: mobileTarget } : {}
+    };
+    const result = applyDeviceTargeting("launch", adapter, targetingOptions, { gate: false, rerun: "" });
     if ("code" in result) {
       if (mobileTarget === "ios" && result.code === "DEVICE_NOT_FOUND") {
         process.env.IOS_SIMULATOR = device;
@@ -185,14 +246,14 @@ function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
         return result;
       }
     }
-    if (mobileTarget === "android" && !process.env.ADB_SERIAL && !process.env.ANDROID_SERIAL) {
+    if (mobileTarget === "android" && device && !process.env.ADB_SERIAL && !process.env.ANDROID_SERIAL) {
       return {
         ok: false,
         code: "DEVICE_WRONG_PLATFORM",
         message: `--device ${device} did not resolve to an Android device for launch android.`
       };
     }
-    if (mobileTarget === "ios" && !process.env.IOS_SIMULATOR) {
+    if (mobileTarget === "ios" && device && !process.env.IOS_SIMULATOR) {
       return {
         ok: false,
         code: "DEVICE_WRONG_PLATFORM",
@@ -236,19 +297,50 @@ function nativeInputsChanged(target, adapter) {
     return false;
   }
 }
-async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json) {
+async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen") {
   if (adapter === "mobile") {
     return launchMobile(target, mobileTarget, tier, json);
   }
-  return launchExtension(target, tier, wantWatch);
+  return launchExtension(target, tier, wantWatch, displayMode);
 }
-function finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state) {
+async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, sidepanelRecoveryAllowed = true) {
   if (adapter === "extension" && displayMode === "sidepanel") {
     const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
     const sidepanelArgs = ["open"];
     if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
+    if (!json) {
+      console.error(
+        `[sidepanel] opening panel beside ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}`
+      );
+    }
     const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, json, { REPO: target });
     if (sidepanel.status !== 0) {
+      const recoveryCode = "chrome.relaunched";
+      if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
+        state.attemptedRecoveries.push(recoveryCode);
+        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, json, displayMode);
+        if (rebuildAttempt.status === 0) {
+          state.recovered.push(recoveryCode);
+          return await finishLaunch(
+            json,
+            adapter,
+            mobileTarget,
+            tier,
+            displayMode,
+            target,
+            state,
+            wantWatch,
+            false
+          );
+        }
+        return launchFail(json, adapter, mobileTarget, tier, state, {
+          code: "EXTENSION_RELAUNCH_FAILED",
+          message: "sidepanel open found a blocked extension runtime, and clean relaunch failed too.",
+          recoverable: false,
+          exitCode: EXIT.infra,
+          originalError: rebuildAttempt.output.trim() || void 0
+        });
+      }
       return launchFail(json, adapter, mobileTarget, tier, state, {
         code: "SIDEPANEL_OPEN_FAILED",
         message: "app launched but opening the side panel failed.",
@@ -282,7 +374,7 @@ function launchPass(json, adapter, mobileTarget, tier, displayMode, state) {
       )
     );
   } else {
-    const device = adapter === "mobile" ? process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || "booted device" : displayMode;
+    const device = adapter === "mobile" ? launchDeviceLabel(mobileTarget) : displayMode;
     const tierNote = tier === "quick" ? "quick relaunch, no native build" : tier;
     const devNote = process.env.MM_HARNESS_BIN ? ` ${color("dim", "[dev: MM_HARNESS_BIN]")}` : "";
     console.error(
@@ -291,6 +383,15 @@ function launchPass(json, adapter, mobileTarget, tier, displayMode, state) {
   }
   return EXIT.ok;
 }
+function launchDeviceLabel(mobileTarget) {
+  if (mobileTarget === "android") {
+    return process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_DEVICE || "android device";
+  }
+  if (mobileTarget === "ios") {
+    return process.env.IOS_SIMULATOR || process.env.SIM_UDID || "iOS simulator";
+  }
+  return process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || "booted device";
+}
 function launchFail(json, adapter, mobileTarget, tier, state, failure) {
   if (json) {
     console.log(

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

@@ -0,0 +1,140 @@
+import { execFileSync } from "node:child_process";
+import { listConnectedDevices } from "../devices.js";
+import { renderDeviceList, scopedDevices } from "./device-target.js";
+import { probeMobileLiveState } from "./status-probe.js";
+function mobileDeviceView(allDevices) {
+  const allConnectedDevices = listConnectedDevices();
+  return {
+    allConnectedDevices,
+    devices: scopedDevices(allConnectedDevices, allDevices)
+  };
+}
+async function mobileDeviceLiveView(target, view) {
+  const allLiveMap = await probeMobileLiveState(target, view.allConnectedDevices);
+  const liveMap = scopedLiveMap(view.devices, allLiveMap);
+  const devicesWithLive = view.devices.map((device) => mergeDeviceLive(device, liveMap.get(device.id)));
+  const reachableDevices = detectAdditionalReachableDevices(view.devices, view.allConnectedDevices, allLiveMap);
+  return {
+    liveMap,
+    devicesWithLive,
+    additionalReachableDevices: reachableDevices,
+    androidPortHints: selectedAndroidPortHints(view.devices, liveMap)
+  };
+}
+function scopedLiveMap(devices, allLiveMap) {
+  const liveMap = /* @__PURE__ */ new Map();
+  for (const device of devices) {
+    const live = allLiveMap.get(device.id);
+    if (live) liveMap.set(device.id, live);
+  }
+  return liveMap;
+}
+function detectAdditionalReachableDevices(scoped, allConnected, liveMap) {
+  const scopedIds = new Set(scoped.map((device) => device.id));
+  return allConnected.filter((device) => !scopedIds.has(device.id)).map((device) => {
+    const live = liveMap.get(device.id);
+    if (!live || live.liveState === "no-bridge") return null;
+    return mergeDeviceLive({ ...device, selected: false }, live);
+  }).filter((device) => device !== null);
+}
+function renderMobileDeviceList(view, out) {
+  renderDeviceList(view.devices, out);
+}
+function renderAdditionalReachableDevices(devices, out) {
+  console.log(`${out("warn", "additional reachable target:")} ${devices.length} device(s) answered on this Metro but are not the active target for this command`);
+  for (const device of devices) {
+    console.log(`  ${out("warn", "\u25CB")} ${device.id}${device.name ? ` (${device.name})` : ""} ${out("dim", `[${device.state}] ${device.platform}`)}`);
+    const live = formatDeviceLive(device, out);
+    if (live) console.log(`    ${live}`);
+    console.log(`    ${out("dim", `Use --device ${device.id} to inspect/run/call this target intentionally.`)}`);
+  }
+}
+function renderMobileLiveBlock(devices, liveMap, out) {
+  console.log(`${out("label", "live:")}`);
+  for (const device of devices) {
+    const live = liveMap.get(device.id);
+    const prefix = `  ${device.platform} ${out("dim", device.id)}${device.name ? ` (${device.name})` : ""}`;
+    if (!live || live.liveState === "no-bridge") {
+      console.log(`${prefix}: ${out("dim", "(no-bridge)")}`);
+      continue;
+    }
+    const rendered = formatDeviceLive(mergeDeviceLive(device, live), out);
+    console.log(`${prefix}: ${rendered.replace(/^live: /u, "")}`);
+  }
+}
+function renderAndroidPortHints(hints, out) {
+  for (const hint of hints) {
+    const current = hint.currentPort ? `; current slot Metro is ${hint.currentPort}` : "";
+    console.log(`${out("warn", "android reverse:")} selected ${hint.deviceId} has reverse port(s) ${hint.reversePorts.join(", ")}${current}`);
+    console.log(`  ${out("dim", `Next: ${hint.next}   # rewrites adb reverse and reopens the dev client`)}`);
+  }
+}
+function nextForLive(fallback, liveMap) {
+  for (const live of liveMap.values()) {
+    if (live.liveState === void 0) return "mm-harness logs";
+  }
+  return fallback;
+}
+function mergeDeviceLive(device, live) {
+  if (!live) return device;
+  return {
+    ...device,
+    fixtureStatus: live.fixtureStatus,
+    ...live.liveState !== void 0 ? { liveState: live.liveState } : {},
+    ...live.currentScreen !== void 0 ? { currentScreen: live.currentScreen } : {},
+    ...live.walletState !== void 0 ? { walletState: live.walletState } : {},
+    ...live.selectedAccount !== void 0 ? { selectedAccount: live.selectedAccount } : {}
+  };
+}
+function formatDeviceLive(device, out) {
+  if (device.liveState === "bridge-absent") {
+    return out("warn", "live: bridge-absent \u2014 app attached, build lacks __AGENTIC__; rebuild/reinstall a dev build");
+  }
+  const parts = [];
+  if (device.currentScreen !== void 0) parts.push(`screen=${out("cmd", device.currentScreen)}`);
+  if (device.walletState !== void 0) {
+    parts.push(`wallet=${out(device.walletState === "unlocked" ? "ok" : "warn", device.walletState)}`);
+  }
+  if (device.selectedAccount !== void 0) {
+    parts.push(`account=${device.selectedAccount.label} ${out("dim", `(${device.selectedAccount.address})`)}`);
+  }
+  if (device.fixtureStatus !== void 0) {
+    parts.push(`fixture=${out(device.fixtureStatus === "READY" ? "ok" : "warn", device.fixtureStatus)}`);
+  }
+  return parts.length > 0 ? `live: ${parts.join("  ")}` : "";
+}
+function selectedAndroidPortHints(devices, liveMap) {
+  const currentPort = process.env.WATCHER_PORT || process.env.METRO_PORT || void 0;
+  return devices.filter((device) => device.selected && device.platform === "android").filter((device) => liveMap.get(device.id)?.liveState === "no-bridge").map((device) => {
+    const reversePorts = androidReversePorts(device.id).filter((port) => currentPort === void 0 || port !== currentPort);
+    return {
+      deviceId: device.id,
+      ...currentPort !== void 0 ? { currentPort } : {},
+      reversePorts,
+      next: `mm-harness launch android --device ${device.id}`
+    };
+  }).filter((hint) => hint.reversePorts.length > 0);
+}
+function androidReversePorts(serial) {
+  try {
+    const out = execFileSync("adb", ["-s", serial, "reverse", "--list"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
+    });
+    return [...out.matchAll(/tcp:(\d+)\s+tcp:(\d+)/gu)].map((match) => match[2]).filter((port, index, ports) => ports.indexOf(port) === index);
+  } catch {
+    return [];
+  }
+}
+export {
+  detectAdditionalReachableDevices,
+  mergeDeviceLive,
+  mobileDeviceLiveView,
+  mobileDeviceView,
+  nextForLive,
+  renderAdditionalReachableDevices,
+  renderAndroidPortHints,
+  renderMobileDeviceList,
+  renderMobileLiveBlock
+};

package/dist/commands/parse-args.js

@@ -30,6 +30,7 @@ function parseArgs(argv, command) {
     "resolveOnly",
     "expectLive",
     "fast",
+    "allDevices",
     "help"
   ]);
   for (let i = 0; i < argv.length; i += 1) {
@@ -149,7 +150,9 @@ function runtimeOptionsFromCli(options) {
 }
 function resolveAdapter(options) {
   const target = targetPath(options);
-  const explicit = optionString(options, "adapter") ?? optionString(options, "platform");
+  const adapterOptionValue = optionString(options, "adapter");
+  const platformOptionValue = optionString(options, "platform");
+  const explicit = adapterOptionValue ?? (platformOptionValue === "ios" || platformOptionValue === "android" ? "mobile" : platformOptionValue);
   const adapter = explicit ?? detectAdapter(target);
   if (!adapter) {
     throw usageError(`could not detect the MetaMask repo type for ${target}

package/dist/commands/recipe-quality.js

@@ -6,6 +6,7 @@ import {
 import { EXIT, usageOut } from "./shared.js";
 import { optionFlag, optionString, parseArgs } from "./parse-args.js";
 const BUILD_USAGE = "mm-harness recipe-quality build --input <compact.json> --output <path> [--json]";
+const SHORTHAND_USAGE = "mm-harness recipe-quality build --input <compact.json> --output <path> [--json]\n  Shorthand: mm-harness recipe-quality --input <compact.json> --output <path> [--json]\n  Note: this CLI builds the recipe-quality artifact from an existing compact verdict; recipe critique is performed by the fs-recipe-quality skill.";
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -36,9 +37,12 @@ async function handleRecipeQuality(argv) {
   const { positional, options } = parseArgs(argv, "recipe-quality");
   const json = optionFlag(options, "json");
   const action = positional[0];
+  if (!action && (optionString(options, "input") || optionString(options, "output"))) {
+    return buildArtifact(options, json);
+  }
   if (action !== "build") {
-    const message = action ? `unknown action '${action}'` : "missing action";
-    return usageOut(json, "recipe-quality", message, BUILD_USAGE);
+    const message = action ? `unknown action '${action}'` : "missing action: use build, or pass --input and --output";
+    return usageOut(json, "recipe-quality", message, SHORTHAND_USAGE);
   }
   return buildArtifact(options, json);
 }

package/dist/commands/run-engine.js

@@ -25,6 +25,7 @@ import {
   actionManifestPathOption,
   optionString,
   isRecord,
+  shellQuoteArg,
   usageError
 } from "./parse-args.js";
 async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}) {
@@ -119,7 +120,8 @@ async function prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions) {
     cdpPort: runtimeOptions.cdpPort,
     slot: runtimeOptions.slot,
     launchExistingDist: runtimeOptions.launchExistingDist === true,
-    validationRuntimeDir: runtimeOptions.validationRuntimeDir
+    validationRuntimeDir: runtimeOptions.validationRuntimeDir,
+    pageMode: "home-or-sidepanel"
   });
 }
 function restoreEnv(key, value) {
@@ -260,7 +262,13 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
     ...librarySources ? { librarySources } : {}
   };
   if ("notFound" in resolved) {
-    return { ...empty, usageError: { code: "RECIPE_NOT_FOUND", message: resolved.notFound } };
+    return {
+      ...empty,
+      usageError: {
+        code: "RECIPE_NOT_FOUND",
+        message: resolved.notFound + await actionInsteadOfRecipeHint(recipeArg, adapter, options)
+      }
+    };
   }
   let recipe;
   try {
@@ -301,6 +309,24 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
     ...librarySources ? { librarySources } : {}
   };
 }
+async function actionInsteadOfRecipeHint(recipeArg, adapter, options) {
+  if (recipeArg.includes("/") || recipeArg.includes(path.sep)) return "";
+  try {
+    const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+    const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+    const actions = getRecipeActionManifestActionNames(manifest);
+    const matches = actions.includes(recipeArg) ? [recipeArg] : actions.filter((name) => name.split(".").pop() === recipeArg);
+    if (matches.length !== 1) return "";
+    const device = optionString(options, "device");
+    const actionManifest = optionString(options, "actionManifest");
+    const parts = ["mm-harness", "call", matches[0]];
+    if (device) parts.push("--device", shellQuoteArg(device));
+    if (actionManifest) parts.push("--action-manifest", shellQuoteArg(actionManifest));
+    return ` This is an action, not a recipe. Use: ${parts.join(" ")}.`;
+  } catch {
+    return "";
+  }
+}
 async function resolveMetaMaskLibrarySources(libraryEntry) {
   const harness = await importRecipeHarness();
   if (typeof harness.resolveRecipeLibrarySources !== "function") {