@deeeed/metamask-harness 0.74.0 → 0.76.0

package/dist/adapters/mobile/launch.js

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import { applyDeviceTargeting } from "../../commands/device-target.js";
+import { launchMobile } from "../../commands/launch/mobile.js";
+import { shellQuote } from "../../commands/launch/quote.js";
+import { EXIT, str, writeInteractiveProgress } from "../../commands/shared.js";
+import { RECOVERY_CODE } from "../../heal-bounds.js";
+import { recipeRuntimePath } from "../../paths.js";
+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 missingConfiguredIosSimulator(output) {
+  return /open-device: configured iOS simulator '([^']+)' does not exist/u.exec(output)?.[1];
+}
+function ambiguousConfiguredIosSimulator(output) {
+  return /open-device: iOS simulator target ("[^"]+") is ambiguous/u.exec(output)?.[1];
+}
+function mobileBridgeTargetMissing(output) {
+  return /no bridge target matched|wait-for-bridge: readiness deadline expired/iu.test(output);
+}
+function mobileProvisionCommand(target, mobileTarget) {
+  const platform = mobileTarget === "android" ? "android" : "ios";
+  const device = platform === "ios" ? process.env.SIM_UDID || process.env.IOS_SIMULATOR : 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 isIosSimulatorUdid(value) {
+  return /^[0-9A-Fa-f-]{36}$/u.test(value);
+}
+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 metroLaunchEvidence(target) {
+  const evidencePath = recipeRuntimePath(target, "metro-generation.json");
+  let descriptor;
+  try {
+    descriptor = fs.openSync(evidencePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > 256 * 1024) return void 0;
+    return JSON.parse(fs.readFileSync(descriptor, "utf8"));
+  } catch {
+    return void 0;
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+  }
+}
+const mobileLaunchProfile = {
+  refuseFlags({ mobileTarget }) {
+    if (!mobileTarget) {
+      return { message: "target is required for mobile.", userAction: "mm-harness launch ios   or   mm-harness launch android" };
+    }
+    return void 0;
+  },
+  applyEnv({ adapter, options, mobileTarget, target }) {
+    const device = str(options, "device");
+    if (!device && mobileTarget !== "ios" && mobileTarget !== "android") return void 0;
+    const targetingOptions = {
+      ...options,
+      ...mobileTarget ? { 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;
+        process.env.SIM_UDID = isIosSimulatorUdid(device) ? device : "";
+        process.env.ADB_SERIAL = "";
+        process.env.ANDROID_SERIAL = "";
+        process.env.ANDROID_DEVICE = "";
+        process.env.ANDROID_TARGET_DEVICE_NAME = "";
+      } else {
+        return result;
+      }
+    }
+    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.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
+      };
+    }
+    if (mobileTarget === "ios" && device && !process.env.IOS_SIMULATOR) {
+      return {
+        ok: false,
+        code: "DEVICE_WRONG_PLATFORM",
+        message: `--device ${device} did not resolve to an iOS simulator for launch ios.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
+      };
+    }
+    return void 0;
+  },
+  start({ options, mobileTarget, machine, tier, wantClearMetro }) {
+    const device = str(options, "device") ?? (mobileTarget === "android" ? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL : process.env.IOS_SIMULATOR ?? process.env.SIM_UDID) ?? "configured device";
+    const watcherPort = str(options, "watcherPort") ?? process.env.WATCHER_PORT ?? "auto";
+    writeInteractiveProgress(
+      machine,
+      `\u2192 mobile launch \u2014 ${mobileTarget} \xB7 ${tier === "build" ? "native build" : "quick readiness"} \xB7 ${device} \xB7 Metro ${watcherPort === "auto" ? "auto" : `:${watcherPort}`}${wantClearMetro ? " \xB7 clear cache" : ""}`
+    );
+  },
+  nativeInputs: ["ios", "android", "package.json", "yarn.lock"],
+  rebuildCommand: ({ mobileTarget }) => `mm-harness launch ${mobileTarget} --build`,
+  compose: ({ target, mobileTarget, machine, remoteFlagRequest }, tier, restartApp, clearMetro) => launchMobile(target, mobileTarget, tier, machine, restartApp, clearMetro, remoteFlagRequest?.flags),
+  classify(_launch, output) {
+    if (output.includes("open-device: Android device is locked.")) {
+      return {
+        code: "MOBILE_DEVICE_LOCKED",
+        message: "the selected Android device is locked.",
+        recoverable: false,
+        userAction: "Unlock the selected Android device, then retry the launch.",
+        exitCode: EXIT.runtime,
+        originalError: output.trim()
+      };
+    }
+    if (/open-device: Android (?:lock state unavailable|display preparation failed)\./u.test(output)) {
+      return {
+        code: "MOBILE_DEVICE_UI_UNAVAILABLE",
+        message: "the selected Android display could not be prepared.",
+        recoverable: false,
+        userAction: "Check adb access and the selected device screen, then retry the launch.",
+        exitCode: EXIT.runtime,
+        originalError: output.trim()
+      };
+    }
+    return void 0;
+  },
+  async beforeHeal(launch, attempt, state) {
+    const { target, mobileTarget, tier } = launch;
+    const output = attempt.output;
+    const missingIosSimulator = missingConfiguredIosSimulator(output);
+    const ambiguousIosSimulator = ambiguousConfiguredIosSimulator(output);
+    if (ambiguousIosSimulator) {
+      return launch.fail(state, {
+        code: "MOBILE_DEVICE_AMBIGUOUS",
+        message: `more than one iOS simulator matches ${ambiguousIosSimulator}.`,
+        recoverable: false,
+        userAction: `mm-harness status --adapter mobile --target ${shellQuote(target)} --all-devices --json`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      });
+    }
+    if (missingIosSimulator && isIosSimulatorUdid(missingIosSimulator)) {
+      return launch.fail(state, {
+        code: "MOBILE_DEVICE_NOT_FOUND",
+        message: `the configured iOS simulator ${missingIosSimulator} no longer exists.`,
+        recoverable: false,
+        userAction: `mm-harness status --adapter mobile --target ${shellQuote(target)} --all-devices --json`,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      });
+    }
+    if (mobileProvisioningBlocked(output)) {
+      return launch.fail(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: output.trim() || void 0
+      });
+    }
+    if (tier === "build" && /open-device: (?:Android|iOS) native build failed/u.test(output)) {
+      return launch.fail(state, {
+        code: "MOBILE_NATIVE_BUILD_FAILED",
+        message: "the selected Mobile native build failed; refusing to repeat the expensive build as a Metro recovery.",
+        recoverable: false,
+        exitCode: EXIT.runtime,
+        originalError: output.trim() || void 0
+      });
+    }
+    return void 0;
+  },
+  recovery(_launch, output) {
+    const restartApp = mobileBridgeTargetMissing(output);
+    return { code: restartApp ? "mobile.app-restarted" : RECOVERY_CODE.mobile, restartApp };
+  },
+  // Mobile proved its set inside launchMobile (null: nothing requested and no
+  // runtime answered).
+  provenFlags: (_launch, requested, proven) => ({ flags: proven === void 0 ? requested : proven }),
+  verifyArgs: ({ mobileTarget }) => mobileTarget ? ["--platform", mobileTarget] : [],
+  platformLabel: ({ mobileTarget }) => mobileTarget ?? null,
+  deviceLabel: ({ mobileTarget }) => launchDeviceLabel(mobileTarget),
+  evidence: metroLaunchEvidence
+};
+export {
+  mobileLaunchProfile
+};

package/dist/adapters/mobile/lifecycle.js

@@ -0,0 +1,300 @@
+import { execFileSync } from "node:child_process";
+import {
+  bridgeCommand,
+  MOBILE_BRIDGE_ERROR_CODES
+} from "../../../library/actions/mobile/platform/bridge.mjs";
+import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
+import {
+  MOBILE_LIFECYCLE_DEADLINE_FIELD,
+  MOBILE_LIFECYCLE_PREPARED
+} from "../../app-lifecycle.js";
+import {
+  mobileSourceFingerprint,
+  recordMobileSourceBaseline
+} from "./source-freshness.js";
+function mobileSourceAwareLifecycleAdapters(lifecycle, readinessProbe = probeMobileLifecycleRuntime, sourceFreshness = {
+  fingerprint: mobileSourceFingerprint,
+  record: recordMobileSourceBaseline
+}, processIdentity = {
+  readIosPid: readIosAppPid,
+  readAndroidPid: readAndroidAppPid
+}, runtimeMarker = readMobileLifecycleRuntimeIdentity) {
+  return lifecycle.map((entry) => ({
+    ...entry,
+    async execute(node, context) {
+      const command = node.command ?? node.event ?? node.state;
+      const opaqueRuntime = context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
+      const requiresProcessContinuity = command !== "restart" && node.require_process_continuity === true;
+      if (opaqueRuntime && !requiresProcessContinuity) {
+        return entry.execute(node, context);
+      }
+      const reloadsSource = !opaqueRuntime && (command === "launch" || command === "foreground" || command === "restart");
+      const recordsSource = !opaqueRuntime && command === "restart";
+      const androidLifecycle = isAndroidLifecycle(node, context.env ?? {});
+      const checksIosContinuity = command === "foreground" && !androidLifecycle;
+      const checksRequiredContinuity = requiresProcessContinuity;
+      const recordsProcessIdentity = checksIosContinuity || checksRequiredContinuity;
+      const readProcessId = androidLifecycle ? processIdentity.readAndroidPid ?? readAndroidAppPid : processIdentity.readIosPid;
+      const processBefore = recordsProcessIdentity ? readProcessId(node, context) : void 0;
+      const fingerprint = recordsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
+      const previousRuntimeIdentity = recordsSource ? await runtimeMarker(node, context) : void 0;
+      const androidRestart = command === "restart" && androidLifecycle;
+      const initialResult = await entry.execute(node, context);
+      const readinessDeadline = reloadsSource ? mobileLifecycleReadinessDeadline(command, node) : void 0;
+      let result = initialResult;
+      let runtimeReady = false;
+      if (androidRestart) {
+        try {
+          const remainingMs = Math.max(
+            1,
+            (readinessDeadline ?? Date.now()) - Date.now()
+          );
+          const handoffDeadline = Math.min(
+            readinessDeadline ?? Number.POSITIVE_INFINITY,
+            Date.now() + Math.min(1e4, Math.max(1, remainingMs / 2))
+          );
+          await readinessProbe(
+            node,
+            context,
+            previousRuntimeIdentity,
+            handoffDeadline
+          );
+          runtimeReady = true;
+        } catch (error) {
+          if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
+            throw error;
+          }
+          const foregroundTimeoutMs = Math.max(
+            1,
+            (readinessDeadline ?? Date.now() + 1) - Date.now()
+          );
+          const foregroundResult = await entry.execute(
+            {
+              ...node,
+              command: "foreground",
+              settle_ms: 0,
+              timeout_ms: foregroundTimeoutMs,
+              [MOBILE_LIFECYCLE_DEADLINE_FIELD]: readinessDeadline,
+              [MOBILE_LIFECYCLE_PREPARED]: true
+            },
+            context
+          );
+          result = mergeAndroidRestartResults(initialResult, foregroundResult);
+        }
+      }
+      if (reloadsSource && !runtimeReady) {
+        if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
+          throw new Error(
+            `Mobile lifecycle ${String(command)} exhausted its runtime readiness deadline before recovery completed.`
+          );
+        }
+        await readinessProbe(
+          node,
+          context,
+          previousRuntimeIdentity,
+          readinessDeadline
+        );
+      }
+      if (recordsProcessIdentity) {
+        const processAfter = readProcessId(node, context);
+        const processPreserved = processBefore !== null && processBefore === processAfter;
+        const actualTransition = processPreserved ? command === "background" ? "background_same_process" : "foreground_resume" : processAfter !== null ? "cold_relaunch" : "unknown";
+        const processContinuity = processPreserved ? "preserved" : processAfter === null ? "unknown" : "changed";
+        const resultRecord = asRecord(result);
+        result = {
+          ...resultRecord,
+          output: {
+            ...asRecord(resultRecord.output),
+            actualTransition,
+            processContinuity,
+            processBefore,
+            processAfter
+          }
+        };
+        if (checksRequiredContinuity && !processPreserved) {
+          const platform = androidLifecycle ? "Android" : "iOS";
+          throw new Error(
+            `${platform} ${String(command)} did not prove app-process continuity (actualTransition=${actualTransition}, before=${String(processBefore)}, after=${String(processAfter)}); this lifecycle sample cannot be classified as a same-process reconnect.`
+          );
+        }
+      }
+      if (fingerprint !== void 0 && !sourceFreshness.record(context.projectRoot, fingerprint)) {
+        throw new Error(
+          "Mobile source changed while the app was reloading; the loaded-source baseline was not recorded. Next: retry app.lifecycle restart."
+        );
+      }
+      return result;
+    }
+  }));
+}
+function readAndroidAppPid(node, context) {
+  const env = context.env ?? {};
+  const device = node.adb_serial ?? node.android_device ?? node.device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
+  const packageId = node.package_id ?? node.packageName ?? node.app_id ?? env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask";
+  if (typeof device !== "string" || typeof packageId !== "string") return null;
+  try {
+    const adb = resolveMobileToolPath("adb", { required: true });
+    const output = execFileSync(
+      adb,
+      ["-s", device, "shell", "pidof", packageId],
+      { encoding: "utf8", timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }
+    );
+    const pid = Number.parseInt(output.trim().split(/\s+/u)[0] ?? "", 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function readIosAppPid(node, context) {
+  const env = context.env ?? {};
+  const device = node.simulator ?? node.ios_simulator ?? env.SIM_UDID ?? env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? process.env.IOS_SIMULATOR;
+  const bundleId = node.bundle_id ?? node.bundleId ?? env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask";
+  if (typeof device !== "string" || typeof bundleId !== "string") return null;
+  try {
+    const output = execFileSync(
+      "xcrun",
+      ["simctl", "spawn", device, "launchctl", "list"],
+      { encoding: "utf8", timeout: 5e3 }
+    );
+    const labelPrefix = `UIKitApplication:${bundleId}[`;
+    const line = output.split("\n").find((candidate) => candidate.includes(labelPrefix));
+    if (!line) return null;
+    const pid = Number.parseInt(line.trim().split(/\s+/u)[0] ?? "", 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function isAndroidLifecycle(node, env) {
+  const platform = node.platform ?? env.PLATFORM ?? process.env.PLATFORM;
+  if (platform === "android") return true;
+  if (platform === "ios") return false;
+  return Boolean(
+    node.adb_serial ?? node.android_device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL
+  );
+}
+function mergeAndroidRestartResults(initialResult, foregroundResult) {
+  const initial = asRecord(initialResult);
+  const foreground = asRecord(foregroundResult);
+  const initialOutput = asRecord(initial.output);
+  const foregroundOutput = asRecord(foreground.output);
+  return {
+    ...initial,
+    output: {
+      ...initialOutput,
+      command: "restart",
+      calls: [
+        ...Array.isArray(initialOutput.calls) ? initialOutput.calls : [],
+        ...Array.isArray(foregroundOutput.calls) ? foregroundOutput.calls : []
+      ],
+      settleMs: foregroundOutput.settleMs ?? initialOutput.settleMs ?? 0,
+      foregroundEnsured: true
+    }
+  };
+}
+async function probeMobileLifecycleRuntime(node, context, previousRuntimeIdentity, deadlineMs) {
+  const command = node.command ?? node.event ?? node.state;
+  const timeoutMs = resolveMobileLifecycleReadinessTimeout(
+    command,
+    node.runtime_ready_timeout_ms
+  );
+  const startedAt = Date.now();
+  const deadline = deadlineMs ?? startedAt + timeoutMs;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const status = await bridgeCommand(
+        {
+          action: "app.lifecycle",
+          node: {
+            ...node,
+            cdp_timeout_ms: Math.min(8e3, Math.max(1, deadline - Date.now()))
+          },
+          context
+        },
+        ["status-selected"]
+      );
+      if (status?.agenticPresent === true && status.route && (!previousRuntimeIdentity || status.runtimeIdentity !== previousRuntimeIdentity)) {
+        return status;
+      }
+      lastError = new Error(
+        previousRuntimeIdentity && status?.runtimeIdentity === previousRuntimeIdentity ? "retiring Mobile runtime is still selected" : "selected Mobile runtime is not ready"
+      );
+    } catch (error) {
+      lastError = error;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs > 0) {
+      await new Promise(
+        (resolve) => setTimeout(resolve, Math.min(1e3, remainingMs))
+      );
+    }
+  }
+  throw new Error(
+    `Mobile lifecycle ${String(command)} did not expose a usable pinned __AGENTIC__ runtime within ${Math.max(0, deadline - startedAt)}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
+}
+async function readMobileLifecycleRuntimeIdentity(node, context) {
+  const deadline = Date.now() + 5e3;
+  let lastError;
+  do {
+    try {
+      const status = await bridgeCommand(
+        {
+          action: "app.lifecycle",
+          node: {
+            ...node,
+            cdp_timeout_ms: Math.min(1e3, Math.max(1, deadline - Date.now()))
+          },
+          context
+        },
+        ["target-identity-selected"]
+      );
+      if (typeof status?.runtimeIdentity === "string") {
+        return status.runtimeIdentity;
+      }
+      lastError = new Error("selected Mobile runtime has no stable identity");
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === MOBILE_BRIDGE_ERROR_CODES.NO_TARGET) {
+        return void 0;
+      }
+      lastError = error;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      break;
+    }
+    await new Promise(
+      (resolve) => setTimeout(resolve, Math.min(250, remainingMs))
+    );
+  } while (Date.now() < deadline);
+  throw new Error(
+    `Mobile lifecycle restart could not identify the retiring runtime: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
+}
+function mobileLifecycleReadinessDeadline(command, node) {
+  const timeoutMs = resolveMobileLifecycleReadinessTimeout(
+    command,
+    node.runtime_ready_timeout_ms
+  );
+  return Date.now() + timeoutMs;
+}
+function resolveMobileLifecycleReadinessTimeout(command, value) {
+  if (value === void 0) {
+    return command === "launch" || command === "restart" || command === "foreground" ? 6e4 : 3e4;
+  }
+  const timeout = Number(value);
+  if (!Number.isInteger(timeout) || timeout < 1e3 || timeout > 12e4) {
+    throw new Error(
+      "app.lifecycle.runtime_ready_timeout_ms must be an integer from 1000 through 120000."
+    );
+  }
+  return timeout;
+}
+function asRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  mobileSourceAwareLifecycleAdapters,
+  resolveMobileLifecycleReadinessTimeout
+};

package/dist/adapters/mobile/overlay.js

@@ -0,0 +1,27 @@
+import { mobilePlatformFromConfiguredTarget, mobilePlatformFromDevices, readRuntimeContextTarget } from "./prepare-target.js";
+const mobileHarness = {
+  install: { entry: "adapters/mobile/inject.sh", fallback: "scripts/inject-mobile-harness.sh" },
+  cleanup: { entry: "adapters/mobile/cleanup.sh", fallback: "scripts/cleanup-mobile-harness.sh", fromInstalledRunner: true },
+  // Runner-owned typed code, not a shipped leaf: no installed overlay copy can shadow it.
+  verify: () => ({ inProcess: async () => (await import("./verify.js")).runMobileVerify }),
+  restart: "mm-harness launch ios   # or launch android"
+};
+const mobileRuntimeContext = {
+  forbiddenFields: ["cdpPort", "extensionId"],
+  localPorts: { watcher: 4e4 },
+  resources: ({ watcherPort, existing }) => ({
+    metroPort: watcherPort,
+    simulator: process.env.IOS_SIMULATOR || existing.simulator,
+    simulatorUdid: process.env.SIM_UDID || existing.simulatorUdid,
+    adbSerial: process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || existing.adbSerial
+  })
+};
+const mobilePrepare = {
+  clearMetro: true,
+  devicePlatform: (target, devices) => mobilePlatformFromConfiguredTarget(process.env, readRuntimeContextTarget(target)) ?? mobilePlatformFromDevices(devices)
+};
+export {
+  mobileHarness,
+  mobilePrepare,
+  mobileRuntimeContext
+};

package/dist/adapters/mobile/prepare-target.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import { recipeRuntimeDir } from "../../paths.js";
+function readRuntimeContextTarget(target) {
+  const file = path.join(target, recipeRuntimeDir(), "agentic-runtime.json");
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+  const record = parsed ?? {};
+  const str = (key) => typeof record[key] === "string" ? record[key] : void 0;
+  return { simulator: str("simulator"), simulatorUdid: str("simulatorUdid"), adbSerial: str("adbSerial") };
+}
+function mobilePlatformFromConfiguredTarget(env, context) {
+  const ios = Boolean(env.IOS_SIMULATOR || env.SIM_UDID || context.simulator || context.simulatorUdid);
+  const android = Boolean(
+    env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_TARGET_DEVICE_NAME || env.ANDROID_DEVICE || context.adbSerial
+  );
+  if (ios === android) return void 0;
+  return ios ? "ios" : "android";
+}
+function mobilePlatformFromDevices(devices) {
+  const selected = devices.filter((device) => device?.selected === true);
+  const candidates = selected.length > 0 ? selected : devices;
+  const platforms = [
+    ...new Set(
+      candidates.map((device) => device?.platform).filter((value) => value === "ios" || value === "android")
+    )
+  ];
+  return platforms.length === 1 ? platforms[0] : void 0;
+}
+export {
+  mobilePlatformFromConfiguredTarget,
+  mobilePlatformFromDevices,
+  readRuntimeContextTarget
+};

package/dist/adapters/mobile/readiness.js

@@ -0,0 +1,39 @@
+import { optionFlag, optionString, parsePort } from "../../commands/parse-args.js";
+import { detectOrphanMetros, mobileToolDoctorChecks } from "./doctor-checks.js";
+import { ensureMobilePerpsEnvironment, mobilePerpsEnvironment } from "./perps-env.js";
+const mobileReadiness = {
+  compatibilityMode(_target, shape) {
+    if (shape.injectedHarness && shape.agenticService) return "runner bridge with injected app bridge";
+    if (shape.agenticService) return "runner bridge with app bridge";
+    return "runner bridge available; app bridge not installed";
+  },
+  checks: (_target, platform) => mobileToolDoctorChecks(platform === "ios" || platform === "android" ? platform : void 0),
+  environment: (target) => ({ mobilePerps: mobilePerpsEnvironment(target) }),
+  lines(target) {
+    const perps = mobilePerpsEnvironment(target);
+    return [
+      `mobile-perps: ${perps.status} (${perps.file}; MM_PERPS_ENABLED=${perps.perpsEnabled.value ?? "missing"}; OVERRIDE_REMOTE_FEATURE_FLAGS=${perps.remoteFeatureFlagOverride.value ?? "missing"})`
+    ];
+  },
+  orphanDevServers: detectOrphanMetros,
+  captureProviders: ["simctl", "adb"],
+  fixes: [{ id: "mobile-perps-env", apply: (target) => ensureMobilePerpsEnvironment(target).length > 0 }],
+  devices: async () => (await import("./devices.js")).mobileDevices
+};
+async function mobileRuntimeDecision(target, options) {
+  const watcherPortRaw = optionString(options, "watcherPort") ?? process.env.WATCHER_PORT ?? process.env.METRO_PORT;
+  const watcherPort = watcherPortRaw === void 0 ? void 0 : parsePort(watcherPortRaw, "runtime-decision --watcher-port must be a port.");
+  const { decideMobileReadiness } = await import("./runtime-decision.js");
+  const report = await decideMobileReadiness(target, {
+    watcherPort,
+    metroLog: optionString(options, "metroLog"),
+    platform: optionString(options, "platform") ?? process.env.PLATFORM ?? process.env.RECIPE_HARNESS_PLATFORM,
+    record: optionFlag(options, "record"),
+    preflightMode: optionString(options, "preflightMode")
+  });
+  return { report, line: `${report.decision} ${report.reasonCode} \u2014 ${report.reasons[0] ?? ""}` };
+}
+export {
+  mobileReadiness,
+  mobileRuntimeDecision
+};

package/dist/adapters/mobile/reload.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { EXIT, spawnScript } from "../../commands/shared.js";
+import { runnerDir } from "../../paths.js";
+function reloadMobile(target, json) {
+  const script = path.join(runnerDir, "adapters/mobile/reload-app.mjs");
+  const args = [];
+  if (process.env.WATCHER_PORT) args.push("--port", process.env.WATCHER_PORT);
+  if (json) args.push("--json");
+  const result = spawnScript(process.execPath, [script, ...args], target, json);
+  if (json) process.stdout.write(result.output);
+  return result.status === 0 ? EXIT.ok : EXIT.runtime;
+}
+export {
+  reloadMobile
+};