@deeeed/metamask-harness 0.3.9 → 0.5.0

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

@@ -0,0 +1,315 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  clearDecisionState,
+  depsCheck,
+  recordDepsBaseline
+} from "@farmslot/recipe-harness/runtime/deps-readiness";
+import {
+  analyzeBundleLog,
+  evaluatePersistentBundleError,
+  supersededErrorCapture
+} from "@farmslot/recipe-harness/runtime/log-analysis";
+import { probeMetroPackager } from "@farmslot/recipe-harness/runtime/metro-probe";
+import { recipeRuntimePath } from "../../paths.js";
+import { mobileProductMarkers } from "./deps-markers.js";
+const BUNDLE_ERR = /Bundling failed|Unable to resolve /u;
+const BUNDLE_OK = /Bundled \d+ms|iOS Bundled|Android Bundled|Finished bundling/u;
+const NATIVE_MODULE_STALE = /\[runtime not ready\].*HybridObject "([^"]+)" - It has not yet been registered in the Nitro Modules HybridObjectRegistry/u;
+function resolveMetroLog(target, metroLog) {
+  const abs = metroLog ? path.isAbsolute(metroLog) ? metroLog : path.join(target, metroLog) : recipeRuntimePath(target, "metro.log");
+  return fs.existsSync(abs) ? abs : null;
+}
+function isMetroLogStale(target, logAbs) {
+  try {
+    const logMtime = fs.statSync(logAbs).mtimeMs;
+    const INSTALL_MARKERS = ["node_modules/.yarn-state.yml", ".yarn/install-state.gz"];
+    return INSTALL_MARKERS.some((rel) => {
+      try {
+        return logMtime < fs.statSync(path.join(target, rel)).mtimeMs;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+function metroLogCheck(target, metroLog) {
+  const abs = resolveMetroLog(target, metroLog);
+  if (!abs) return { status: "no-log" };
+  if (isMetroLogStale(target, abs)) return { status: "no-log" };
+  const logText = fs.readFileSync(abs, "utf8");
+  return analyzeBundleLog({
+    target,
+    logText,
+    errorPattern: BUNDLE_ERR,
+    okPattern: BUNDLE_OK
+  });
+}
+function missingRequiredDeps(target) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(target, "package.json"), "utf8"));
+    const all = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+    return Object.keys(all).filter(
+      (name) => !fs.existsSync(path.join(target, "node_modules", name))
+    );
+  } catch {
+    return [];
+  }
+}
+const installActions = (target) => [
+  { id: "yarn-setup", argv: ["yarn", "setup"], cwd: target }
+];
+function appRunningOnDevice(platform) {
+  try {
+    if (platform === "android") {
+      const serial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL;
+      const args = serial ? ["-s", serial] : [];
+      const out2 = execFileSync("adb", [...args, "shell", "ps", "-A"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5e3
+      });
+      return out2.includes("io.metamask");
+    }
+    const device = process.env.IOS_SIMULATOR || "booted";
+    const out = execFileSync("xcrun", ["simctl", "spawn", device, "launchctl", "list"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5e3
+    });
+    return out.toLowerCase().includes("io.metamask");
+  } catch {
+    return false;
+  }
+}
+const launchActions = (target, clearMetro = false) => {
+  const actions = [];
+  actions.push({
+    id: "start-metro",
+    argv: clearMetro ? ["--clear"] : [],
+    cwd: target
+  });
+  actions.push({ id: "prewarm-bundle", cwd: target });
+  actions.push({ id: "launch-mobile-runtime" });
+  actions.push({ id: "wait-for-bridge", cwd: target });
+  return actions;
+};
+async function decideMobileReadiness(target, options = {}) {
+  const resolved = path.resolve(target);
+  if (options.record) recordDepsBaseline(resolved);
+  const fast = options.preflightMode === "fast";
+  const report = await computeMobileReadiness(resolved, options, fast);
+  if (fast && report.decision === "install") {
+    return {
+      ...report,
+      decision: "blocked",
+      reasonCode: "deps-not-ready",
+      reasons: [
+        "Fast preflight found dependencies not ready and does not install them (the orchestrator deps phase owns installation).",
+        ...report.reasons
+      ],
+      userAction: "run the slot deps/prepare phase; standalone: `yarn setup:expo --no-build-ios --no-build-android` in the checkout, or `mm-harness launch <platform> --build` to install and build",
+      actions: []
+    };
+  }
+  return report;
+}
+async function computeMobileReadiness(resolved, options, fast) {
+  const rawDeps = depsCheck(resolved, {
+    productMarkers: mobileProductMarkers(options.platform)
+  });
+  let deps = rawDeps;
+  if (rawDeps.status === "stale" && !rawDeps.hasBaseline) {
+    deps = { installed: rawDeps.installed, status: "current", hasBaseline: false };
+    process.stderr.write(
+      "[runtime-decision] manifest is newer than install markers (no recorded baseline); trusting installed node_modules \u2014 run yarn setup manually if deps truly changed.\n"
+    );
+  }
+  if (deps.status === "current") {
+    const absent = missingRequiredDeps(resolved);
+    if (absent.length > 0) {
+      deps = { installed: deps.installed, status: "partial", hasBaseline: deps.hasBaseline, missingProducts: absent };
+    }
+  }
+  const metroLog = metroLogCheck(resolved, options.metroLog);
+  const metro = options.watcherPort ? await probeMetroPackager(options.watcherPort) : { status: "skipped" };
+  if (metroLog.status === "ok") {
+    clearDecisionState(resolved, "bundle-error-state.json");
+  }
+  const checks = { deps, metroLog, metro };
+  if (deps.status === "missing") {
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "install",
+      reasonCode: "deps-missing",
+      reasons: ["Dependencies are not installed (no yarn install-state markers)."],
+      checks,
+      actions: installActions(resolved)
+    };
+  }
+  if (deps.status === "partial") {
+    const missing = deps.missingProducts?.join(", ") ?? "product markers";
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "install",
+      reasonCode: "deps-partial",
+      reasons: [`node_modules tree is incomplete (missing: ${missing}).`],
+      checks,
+      actions: installActions(resolved)
+    };
+  }
+  if (deps.status === "stale") {
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "install",
+      reasonCode: "deps-stale",
+      reasons: ["package.json/yarn.lock changed since the recorded install baseline."],
+      checks,
+      actions: installActions(resolved)
+    };
+  }
+  const metroLogAbs = resolveMetroLog(resolved, options.metroLog);
+  const metroLogText = metroLogAbs && !isMetroLogStale(resolved, metroLogAbs) ? fs.readFileSync(metroLogAbs, "utf8") : "";
+  const staleNativeModule = supersededErrorCapture(metroLogText, {
+    errorPattern: NATIVE_MODULE_STALE,
+    okPattern: BUNDLE_OK
+  });
+  if (staleNativeModule) {
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "launch",
+      reasonCode: "native-module-stale",
+      reasons: [
+        `Installed dev client is missing native module "${staleNativeModule}" (JS deps are current). Rebuild the native app (yarn start:ios / yarn start:android or --preflight-mode rebuild-native).`,
+        "Metro may report a successful bundle while the installed dev client binary predates the native Nitro module link."
+      ],
+      checks,
+      actions: [
+        { id: "rebuild-native-dev-client" },
+        ...launchActions(resolved, true)
+      ]
+    };
+  }
+  if (metroLog.status === "errors") {
+    const depsSatisfied = deps.status === "current";
+    if (depsSatisfied && (metroLog.reason === "stale-bundle-error" || metroLog.reason === "bundle-error")) {
+      const excerpt = metroLog.excerpt ?? "";
+      const persistent = evaluatePersistentBundleError(resolved, excerpt);
+      if (persistent.blocked) {
+        return {
+          schemaVersion: 1,
+          adapter: "mobile",
+          target: resolved,
+          decision: "blocked",
+          reasonCode: "bundle-error-persistent",
+          reasons: [
+            "Metro bundle keeps failing with the same error after a cache-cleared relaunch was already suggested; fix the bundle error in app code before retrying recipe up.",
+            ...excerpt ? [excerpt] : []
+          ],
+          checks,
+          actions: []
+        };
+      }
+      return {
+        schemaVersion: 1,
+        adapter: "mobile",
+        target: resolved,
+        decision: "launch",
+        reasonCode: metroLog.reason === "stale-bundle-error" ? "metro-stale-log" : "bundle-errors-recoverable",
+        reasons: [
+          metroLog.reason === "stale-bundle-error" ? "Metro log shows prior bundle failures but cited modules are installed; restart Metro with a cleared cache." : "Metro bundle is failing with current deps; restart Metro (clear cache) before relaunching the dev client.",
+          ...excerpt ? [excerpt] : []
+        ],
+        checks,
+        actions: launchActions(resolved, true)
+      };
+    }
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "install",
+      reasonCode: metroLog.reason === "unresolved-module" ? "deps-unresolved-module" : "bundle-errors",
+      reasons: [
+        metroLog.reason === "unresolved-module" ? "Metro cannot resolve modules that are absent from node_modules; run yarn setup." : "Metro bundle is failing; reinstall deps or clear Metro cache before retrying.",
+        ...metroLog.excerpt ? [metroLog.excerpt] : []
+      ],
+      checks,
+      actions: installActions(resolved)
+    };
+  }
+  if (metro.status === "down") {
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "launch",
+      reasonCode: "metro-down",
+      reasons: ["Metro is not reachable; start Metro and launch the dev client."],
+      checks,
+      actions: launchActions(resolved)
+    };
+  }
+  if (metroLog.status === "bundling" || metroLog.status === "no-log") {
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "launch",
+      reasonCode: metroLog.status === "bundling" ? "bundle-in-progress" : "runtime-cold",
+      reasons: [
+        metroLog.status === "bundling" ? "Metro bundle is still in progress; launch or wait for a successful bundle." : "No successful Metro bundle recorded; start Metro and launch the dev client."
+      ],
+      checks,
+      actions: launchActions(resolved)
+    };
+  }
+  if (metro.status === "up" && metroLog.status === "ok") {
+    if (!appRunningOnDevice(options.platform)) {
+      return {
+        schemaVersion: 1,
+        adapter: "mobile",
+        target: resolved,
+        decision: "launch",
+        reasonCode: "app-not-running",
+        reasons: ["Metro is healthy but the dev client is not running on the target device; launching it."],
+        checks,
+        actions: launchActions(resolved)
+      };
+    }
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "ready",
+      reasonCode: "healthy",
+      reasons: ["Dependencies are current, Metro reports a successful bundle, and the dev client is running. Verify bridge before replay."],
+      checks,
+      actions: []
+    };
+  }
+  return {
+    schemaVersion: 1,
+    adapter: "mobile",
+    target: resolved,
+    decision: "launch",
+    reasonCode: "runtime-unverified",
+    reasons: ["Dependencies are current; start or refresh Metro + dev client before replay."],
+    checks,
+    actions: launchActions(resolved)
+  };
+}
+export {
+  decideMobileReadiness
+};

package/dist/adapters/mobile/surface.js

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { recipeRuntimePath, runnerDir } from "../../paths.js";
+import { resolveMobileSlotPorts } from "../slot-ports.js";
+import { mobileRuntimeStatus } from "./prepare.js";
+import { hasRunwayProvisionBaseline, provisionRunwayMobile } from "./provision.js";
+const mobileSurface = {
+  adapter: "mobile",
+  headless: false,
+  resolveSlotPorts(target) {
+    resolveMobileSlotPorts(target);
+  },
+  async runtimeStatus(target) {
+    const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : void 0;
+    const report = await mobileRuntimeStatus(target, { watcherPort });
+    const runwayProvisioned = hasRunwayProvisionBaseline(target);
+    const depsPending = runwayProvisioned && report.checks?.deps?.status !== "current";
+    return {
+      decision: depsPending ? "launch" : report.decision,
+      reasonCode: depsPending ? "app-installed-deps-pending" : report.reasonCode,
+      reasons: depsPending ? ["Runway app is installed; JavaScript dependencies are pending until dispatch-time launch."] : report.reasons,
+      deps: runwayProvisioned && report.checks?.deps?.status !== "current" ? "pending" : report.checks?.deps?.status,
+      devServer: { label: "metro", status: report.checks?.metro?.status ?? "unprobed" }
+    };
+  },
+  runwayProvision: {
+    async run(target, options) {
+      return provisionRunwayMobile(target, options);
+    }
+  },
+  devServer: {
+    describe: () => "Metro dev server",
+    stop(target) {
+      const leaf = path.join(runnerDir, "adapters", "mobile", "stop-metro.sh");
+      const args = ["--target", target];
+      if (process.env.WATCHER_PORT) args.push("--port", process.env.WATCHER_PORT);
+      const result = spawnSync("bash", [leaf, ...args], { encoding: "utf8" });
+      const status = result.status ?? 1;
+      const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+      const summary = status === 0 ? `stopped Metro dev server for ${target}` : `failed to stop Metro for ${target}`;
+      return { kind: "stopped", status, summary, output };
+    }
+  },
+  logSources(target) {
+    return [{ label: "metro", path: recipeRuntimePath(target, "metro.log") }];
+  },
+  hints: {
+    launch: "mm-harness launch ios",
+    relaunch: "mm-harness launch ios"
+  }
+};
+export {
+  mobileSurface
+};

package/dist/adapters/slot-ports.js

@@ -0,0 +1,146 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { readRuntimeContextField, resolveRuntimeContextPath } from "../harness.js";
+import { recipeRuntimeDir, runnerDir } from "../paths.js";
+function applyKVLines(output, overwrite) {
+  for (const line of output.split("\n")) {
+    const m = /^([A-Z_]+)=(.+)$/u.exec(line.trim());
+    if (!m) continue;
+    const [, key, val] = m;
+    switch (key) {
+      case "WATCHER_PORT":
+        if (overwrite || !process.env["WATCHER_PORT"]) {
+          process.env["WATCHER_PORT"] = val;
+          process.env["METRO_PORT"] = val;
+          process.env["RECIPE_WATCHER_PORT"] = val;
+        }
+        break;
+      case "IOS_SIMULATOR":
+        if (overwrite || !process.env["IOS_SIMULATOR"]) process.env["IOS_SIMULATOR"] = val;
+        break;
+      case "SLOT_ID":
+        if (overwrite || !process.env["RECIPE_SLOT_ID"]) process.env["RECIPE_SLOT_ID"] = val;
+        break;
+      case "CDP_PORT":
+        if (overwrite || !process.env["CDP_PORT"]) {
+          process.env["CDP_PORT"] = val;
+          process.env["RECIPE_CDP_PORT"] = val;
+        }
+        break;
+    }
+  }
+}
+function sourceResolve(fn, target) {
+  const resolveScript = path.join(runnerDir, "adapters/shared/resolve-farmslot-ports.sh");
+  try {
+    return execFileSync("bash", ["-c", `source "${resolveScript}" && ${fn} "${target}"`], {
+      encoding: "utf8",
+      timeout: 5e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return "";
+  }
+}
+function resolveMobileSlotPorts(target) {
+  const ctxOut = sourceResolve("resolve_mobile_runtime_context", target);
+  if (ctxOut.trim()) {
+    applyKVLines(ctxOut, true);
+    return;
+  }
+  const poolOut = sourceResolve("resolve_farmslot_ports_by_repo", target);
+  if (poolOut.trim()) {
+    applyKVLines(poolOut, true);
+    return;
+  }
+  const defOut = sourceResolve("resolve_mobile_slot_defaults", target);
+  if (defOut.trim()) applyKVLines(defOut, false);
+}
+function resolveExtensionSlotPorts(target) {
+  const contextPath = resolveRuntimeContextPath(target);
+  const cdp = readRuntimeContextField(contextPath, "cdpPort");
+  if (cdp) {
+    process.env["CDP_PORT"] = cdp;
+    process.env["RECIPE_CDP_PORT"] = cdp;
+  }
+  const dev = readRuntimeContextField(contextPath, "devServerPort");
+  if (dev) {
+    process.env["WATCHER_PORT"] = dev;
+    process.env["RECIPE_WATCHER_PORT"] = dev;
+  }
+  if (process.env["CDP_PORT"]) return;
+  const poolOut = sourceResolve("resolve_farmslot_ports_by_repo", target);
+  if (poolOut.trim()) {
+    applyKVLines(poolOut, true);
+    return;
+  }
+  const defOut = sourceResolve("resolve_default_extension_ports", target);
+  if (defOut.trim()) applyKVLines(defOut, false);
+}
+function stopExtensionWatcher(target) {
+  const runtimeAbs = path.join(target, recipeRuntimeDir());
+  const webpackPidFile = path.join(runtimeAbs, "recipe-harness-webpack.pid");
+  let signalled = 0;
+  try {
+    const pid = fs.readFileSync(webpackPidFile, "utf8").trim();
+    if (/^\d+$/u.test(pid)) {
+      try {
+        process.kill(Number(pid), "SIGTERM");
+        signalled += 1;
+      } catch {
+      }
+    }
+    fs.rmSync(webpackPidFile, { force: true });
+  } catch {
+  }
+  try {
+    const psOut = execFileSync("ps", ["-axo", "pid=,command="], { encoding: "utf8" });
+    const orphanPids = [];
+    for (const line of psOut.split("\n")) {
+      const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
+      if (!match) continue;
+      const [, pidStr, cmd] = match;
+      const isWatcher = cmd.includes("yarn start") || cmd.includes("webpack --watch") || cmd.includes("development/webpack/launch.ts --watch");
+      if (!isWatcher) continue;
+      if (cmd.includes(target)) {
+        orphanPids.push(Number(pidStr));
+        continue;
+      }
+      try {
+        const cwd = execFileSync("lsof", ["-a", `-p${pidStr}`, "-dcwd", "-Fn"], {
+          encoding: "utf8",
+          timeout: 2e3
+        });
+        if (cwd.split("\n").some((l) => l.startsWith("n") && l.slice(1) === target)) {
+          orphanPids.push(Number(pidStr));
+        }
+      } catch {
+      }
+    }
+    if (orphanPids.length > 0) {
+      for (const pid of orphanPids) {
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {
+        }
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2e3);
+      for (const pid of orphanPids) {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+        }
+      }
+      signalled += orphanPids.length;
+    }
+  } catch {
+  }
+  return signalled;
+}
+export {
+  applyKVLines,
+  resolveExtensionSlotPorts,
+  resolveMobileSlotPorts,
+  stopExtensionWatcher
+};

package/dist/adapters/surface.js

@@ -0,0 +1,14 @@
+import { coreSurface } from "./core/surface.js";
+import { extensionSurface } from "./extension/surface.js";
+import { mobileSurface } from "./mobile/surface.js";
+const SURFACES = {
+  mobile: mobileSurface,
+  extension: extensionSurface,
+  core: coreSurface
+};
+function getAdapterSurface(adapter) {
+  return SURFACES[adapter];
+}
+export {
+  getAdapterSurface
+};