@deeeed/metamask-harness 0.3.9 → 0.5.0

package/dist/adapters/extension/runtime.js

@@ -0,0 +1,324 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, recipeRuntimeDir, resolveLocalProtocolRoot, resolveRequiredLocalProtocolRoot, runnerDir } from "../../paths.js";
+const { CdpSession, jsonGet, sleep } = await importRecipeHarnessRuntimeCdp();
+const { extensionIdFromTarget } = await importRecipeHarnessRuntimeBrowserExtension();
+async function prepareExtensionRuntime(options) {
+  const projectRoot = path.resolve(options.projectRoot);
+  const slot = resolveExtensionSlot(projectRoot, options.slot);
+  const cdpPort = resolveCdpPort(options.cdpPort, slot);
+  let launch = null;
+  if (options.launchExistingDist) {
+    if (!slot) {
+      throw new Error(
+        `Cannot launch host-managed Extension runtime for ${projectRoot}: no configured slot maps to this repo. Pass --slot <slot-id> or add the checkout to pool/*.json.`
+      );
+    }
+    launch = await launchHostValidationBrowser({
+      projectRoot,
+      cdpPort,
+      slotId: slot.id,
+      validationRuntimeDir: options.validationRuntimeDir ?? `${recipeRuntimeDir()}/validation-${cdpPort}`
+    });
+  }
+  const health = await assertHealthyExtensionRuntime({
+    projectRoot,
+    cdpPort,
+    timeoutMs: options.healthTimeoutMs
+  });
+  return { launch, health };
+}
+async function assertHealthyExtensionRuntime(options) {
+  const timeoutMs = options.timeoutMs ?? 3e4;
+  const deadline = Date.now() + timeoutMs;
+  let lastReport = null;
+  while (Date.now() <= deadline) {
+    lastReport = await checkExtensionRuntimeHealth(options.projectRoot, options.cdpPort);
+    if (lastReport.status === "PASS") return lastReport;
+    await sleep(500);
+  }
+  const report = lastReport ?? failReport(options.cdpPort, ["CDP runtime was not probed."], {});
+  throw new Error(formatHealthFailure(report, options.projectRoot));
+}
+async function checkExtensionRuntimeHealth(projectRoot, cdpPort) {
+  const findings = [];
+  let targets = [];
+  try {
+    await jsonGet(`http://127.0.0.1:${cdpPort}/json/version`);
+    const rawTargets = await jsonGet(`http://127.0.0.1:${cdpPort}/json/list`);
+    targets = Array.isArray(rawTargets) ? rawTargets : [];
+  } catch (error) {
+    return failReport(cdpPort, [`CDP is not reachable on port ${cdpPort}: ${messageOf(error)}`], {});
+  }
+  const extensionTargets = targets.filter(
+    (target2) => target2.type === "page" && String(target2.url ?? "").startsWith("chrome-extension://") && String(target2.url ?? "").includes("/home.html") && Boolean(target2.webSocketDebuggerUrl)
+  );
+  if (extensionTargets.length !== 1) {
+    findings.push(`Expected exactly one MetaMask extension home page target, found ${extensionTargets.length}.`);
+  }
+  const target = extensionTargets[0];
+  if (!target?.webSocketDebuggerUrl) {
+    return failReport(cdpPort, findings, {
+      targetUrls: targets.map((entry) => entry.url).filter(Boolean)
+    });
+  }
+  if (String(target.url ?? "").startsWith("chrome-error://")) {
+    findings.push(`Extension target resolved to chrome-error page: ${target.url}`);
+  }
+  const session = await CdpSession.connect(target.webSocketDebuggerUrl);
+  try {
+    await session.call("Runtime.enable");
+    await session.call("Page.enable");
+    const runtime = await evaluateHealth(session);
+    if (runtime.href && !String(runtime.href).startsWith("chrome-extension://")) {
+      findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
+    }
+    if (runtime.backgroundUnresponsive === true) {
+      findings.push("Extension UI reports background connection unresponsive.");
+    }
+    if (runtime.hasSubmitRequest !== true) {
+      findings.push("stateHooks.submitRequestToBackground is unavailable.");
+    }
+    if (runtime.hasStore !== true) {
+      findings.push("stateHooks.store is unavailable.");
+    }
+    if (runtime.hasPerpsStreamManager !== true) {
+      findings.push("stateHooks.getPerpsStreamManager is unavailable.");
+    }
+    if (runtime.backgroundProbeOk !== true) {
+      findings.push(`Perps background read probe failed: ${runtime.backgroundProbeError ?? "unknown error"}.`);
+    }
+    const extensionId = safeExtensionId(target);
+    return {
+      status: findings.length === 0 ? "PASS" : "FAIL",
+      cdpPort,
+      targetUrl: target.url,
+      extensionId,
+      extensionPageTargets: extensionTargets.length,
+      findings,
+      details: {
+        projectRoot,
+        targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+        runtime
+      }
+    };
+  } finally {
+    session.close();
+  }
+}
+function failReport(cdpPort, findings, details) {
+  return {
+    status: "FAIL",
+    cdpPort,
+    extensionPageTargets: 0,
+    findings,
+    details
+  };
+}
+async function evaluateHealth(session) {
+  const result = await session.call("Runtime.evaluate", {
+    expression: `(() => {
+      const hooks = globalThis.stateHooks || {};
+      const bodyText = document.body?.innerText || '';
+      const storeState = hooks.store?.getState?.() || {};
+      const manager = hooks.getPerpsStreamManager?.();
+      const accountCache = manager?.account?.cache;
+      return Promise.race([
+        (async () => {
+          let backgroundProbeOk = false;
+          let backgroundProbeError = null;
+          if (typeof hooks.submitRequestToBackground === 'function') {
+            try {
+              const accountState = await hooks.submitRequestToBackground('perpsGetAccountState', []);
+              backgroundProbeOk = Boolean(accountState && typeof accountState === 'object');
+              if (!backgroundProbeOk) backgroundProbeError = 'perpsGetAccountState returned an empty result';
+            } catch (error) {
+              backgroundProbeError = String(error?.message || error);
+            }
+          } else {
+            backgroundProbeError = 'submitRequestToBackground is not a function';
+          }
+          return {
+            href: location.href,
+            title: document.title,
+            hookKeys: Object.keys(hooks),
+            hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
+            hasStore: Boolean(hooks.store),
+            hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
+            backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+            activeProvider: storeState.metamask?.activeProvider || null,
+            isTestnet: Boolean(storeState.metamask?.isTestnet),
+            perpsManagerInitialized: Boolean(manager?.isInitialized?.()),
+            positionsCacheIsArray: Array.isArray(manager?.positions?.cache),
+            ordersCacheIsArray: Array.isArray(manager?.orders?.cache),
+            accountCachePresent: Boolean(accountCache && typeof accountCache === 'object'),
+            backgroundProbeOk,
+            backgroundProbeError,
+          };
+        })(),
+        new Promise((resolve) => setTimeout(() => resolve({
+          href: location.href,
+          title: document.title,
+          hookKeys: Object.keys(hooks),
+          hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
+          hasStore: Boolean(hooks.store),
+          hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
+          backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
+          backgroundProbeOk: false,
+          backgroundProbeError: 'perpsGetAccountState timed out after 5000ms',
+        }), 5000)),
+      ]);
+    })()`,
+    awaitPromise: true,
+    returnByValue: true
+  });
+  if (result.exceptionDetails) {
+    throw new Error(
+      result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Extension runtime health evaluation failed."
+    );
+  }
+  return result.result?.value ?? {};
+}
+function formatHealthFailure(report, projectRoot) {
+  return [
+    `Extension runtime health check failed for ${projectRoot} on CDP port ${report.cdpPort}.`,
+    ...report.findings.map((finding) => `- ${finding}`),
+    "Use the host-managed validation launcher, for example:",
+    `  mm-harness run <recipe.json> --adapter extension --target ${projectRoot} --slot <slot-id> --cdp-port ${report.cdpPort} --launch-existing-dist --artifacts-dir <artifacts-dir>`,
+    `Health details: ${JSON.stringify(report.details)}`
+  ].join("\n");
+}
+function resolveCdpPort(rawPort, slot) {
+  const raw = rawPort ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT ?? slot?.cdpPort;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error("Extension runtime requires --cdp-port, CDP_PORT, RECIPE_CDP_PORT, or a configured slot with resources.browser.cdp_port.");
+  }
+  return port;
+}
+function resolveExtensionSlot(projectRoot, requestedSlot) {
+  const protocolRoot = resolveLocalProtocolRoot();
+  if (!protocolRoot) {
+    if (requestedSlot) throw new Error("Extension slot lookup requires a local host checkout when --slot is provided.");
+    return null;
+  }
+  const poolsDir = path.join(protocolRoot, "pool");
+  if (!fs.existsSync(poolsDir)) return null;
+  for (const file of fs.readdirSync(poolsDir)) {
+    if (!file.endsWith(".json") || file.includes(".bak")) continue;
+    const pool = JSON.parse(fs.readFileSync(path.join(poolsDir, file), "utf8"));
+    for (const rawSlot of pool.slots ?? []) {
+      if (!rawSlot || typeof rawSlot !== "object") continue;
+      const slot = rawSlot;
+      if (requestedSlot && slot.id !== requestedSlot) continue;
+      if (!requestedSlot) {
+        const repo = String(slot.repo ?? "");
+        if (!path.isAbsolute(repo) || path.resolve(repo) !== projectRoot) continue;
+      }
+      return {
+        id: String(slot.id),
+        repo: path.resolve(String(slot.repo)),
+        cdpPort: Number(slot.resources?.browser?.cdp_port || slot.resources?.browser?.cdpPort || void 0) || void 0
+      };
+    }
+  }
+  return null;
+}
+async function launchHostValidationBrowser(options) {
+  const protocolRoot = resolveRequiredLocalProtocolRoot("Extension validation browser launch");
+  const script = path.join(protocolRoot, "projects/metamask-extension-farm/setup/launch-validation-browser.sh");
+  if (!fs.existsSync(script)) {
+    throw new Error(`Extension validation launcher not found: ${script}`);
+  }
+  await killCdpPort(options.cdpPort);
+  const result = await runProcess("bash", [
+    script,
+    options.slotId,
+    "--cdp-port",
+    String(options.cdpPort),
+    "--runtime-dir",
+    options.validationRuntimeDir,
+    "--no-landing"
+  ], {
+    cwd: protocolRoot,
+    env: process.env,
+    timeoutMs: 18e4
+  });
+  if (result.timedOut) {
+    throw new Error(`Extension validation launcher timed out after 180000ms.
+${result.stdout}
+${result.stderr}`);
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(`Extension validation launcher failed with exit ${result.exitCode}.
+${result.stdout}
+${result.stderr}`);
+  }
+  return {
+    launched: true,
+    slotId: options.slotId,
+    cdpPort: options.cdpPort,
+    runtimeDir: options.validationRuntimeDir,
+    stdout: result.stdout
+  };
+}
+function runProcess(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timeout = options.timeoutMs ? setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        if (!child.killed) child.kill("SIGKILL");
+      }, 1e3);
+      resolve({ exitCode: null, stdout, stderr, timedOut: true });
+    }, options.timeoutMs) : void 0;
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      reject(error);
+    });
+    child.on("close", (exitCode) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      resolve({ exitCode, stdout, stderr, timedOut: false });
+    });
+  });
+}
+async function killCdpPort(cdpPort) {
+  if (process.platform !== "darwin" && process.platform !== "linux") return;
+  await runProcess("bash", ["-lc", `lsof -ti tcp:${cdpPort} -sTCP:LISTEN | xargs -r kill -TERM || true; sleep 1; lsof -ti tcp:${cdpPort} -sTCP:LISTEN | xargs -r kill -KILL || true`], {
+    cwd: runnerDir,
+    env: process.env,
+    timeoutMs: 1e4
+  });
+}
+function safeExtensionId(target) {
+  try {
+    return extensionIdFromTarget(target);
+  } catch (_error) {
+    return void 0;
+  }
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+export {
+  assertHealthyExtensionRuntime,
+  checkExtensionRuntimeHealth,
+  formatHealthFailure,
+  prepareExtensionRuntime
+};

package/dist/adapters/extension/surface.js

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { recipeRuntimePath } from "../../paths.js";
+import { resolveExtensionSlotPorts, stopExtensionWatcher } from "../slot-ports.js";
+import { decideExtensionReadiness } from "./runtime-decision.js";
+function watcherStatus(buildLog) {
+  if (buildLog === "ok") return "up";
+  if (buildLog === "no-watch") return "down";
+  return buildLog;
+}
+const extensionSurface = {
+  adapter: "extension",
+  headless: false,
+  resolveSlotPorts(target) {
+    resolveExtensionSlotPorts(target);
+  },
+  async runtimeStatus(target) {
+    const cdpPort = process.env.CDP_PORT ? parseInt(process.env.CDP_PORT, 10) : void 0;
+    const report = await decideExtensionReadiness(target, { cdpPort });
+    return {
+      decision: report.decision,
+      reasonCode: report.reasonCode,
+      reasons: report.reasons,
+      deps: report.checks.deps.status,
+      devServer: { label: "webpack", status: watcherStatus(report.checks.buildLog.status) }
+    };
+  },
+  runwayProvision: {
+    async run(target, options) {
+      return {
+        schemaVersion: 1,
+        command: "provision",
+        adapter: "extension",
+        target: path.resolve(target),
+        status: "fail",
+        exitCode: 2,
+        error: {
+          code: "UNSUPPORTED_ADAPTER",
+          message: "extension uses a browser runtime; Runway mobile provisioning is not supported.",
+          userAction: options.rerunCommand || "mm-harness provision --adapter extension"
+        }
+      };
+    }
+  },
+  devServer: {
+    describe: () => "webpack watcher",
+    stop(target) {
+      const signalled = stopExtensionWatcher(target);
+      const port = process.env.WATCHER_PORT ?? "default";
+      spawnSync("tmux", ["kill-window", "-t", `webpack-${port}`], { stdio: "ignore", timeout: 2e3 });
+      const summary = signalled > 0 ? `stopped webpack watcher (${signalled} process${signalled === 1 ? "" : "es"}) for ${target}` : `webpack watcher not running for ${target} \u2014 nothing to stop`;
+      return { kind: "stopped", status: 0, summary, signalled };
+    }
+  },
+  logSources(target) {
+    return [
+      { label: "webpack", path: recipeRuntimePath(target, "webpack.log") },
+      { label: "watcher", path: recipeRuntimePath(target, "recipe-harness-webpack.log") },
+      { label: "rebuild", path: recipeRuntimePath(target, "rebuild.log") }
+    ];
+  },
+  hints: {
+    launch: "mm-harness launch",
+    relaunch: "mm-harness launch --build"
+  }
+};
+export {
+  extensionSurface
+};

package/dist/adapters/mobile/deps-markers.js

@@ -0,0 +1,22 @@
+const MOBILE_PRODUCT_MARKERS = [
+  "node_modules/.yarn-state.yml",
+  "app/core/InpageBridgeWeb3.js",
+  "docs/assets/termsOfUse.html",
+  "app/util/termsOfUse/termsOfUseContent.ts",
+  "node_modules/.bin/anvil"
+];
+const MOBILE_IOS_NATIVE_MARKERS = ["ios/Podfile.lock"];
+const MOBILE_ANDROID_NATIVE_MARKERS = ["android/gradle.properties"];
+function mobileProductMarkers(platform) {
+  const markers = [...MOBILE_PRODUCT_MARKERS];
+  const resolved = (platform ?? process.env.PLATFORM ?? process.env.RECIPE_HARNESS_PLATFORM ?? "").trim().toLowerCase();
+  if (resolved === "ios") markers.push(...MOBILE_IOS_NATIVE_MARKERS);
+  else if (resolved === "android") markers.push(...MOBILE_ANDROID_NATIVE_MARKERS);
+  return markers;
+}
+export {
+  MOBILE_ANDROID_NATIVE_MARKERS,
+  MOBILE_IOS_NATIVE_MARKERS,
+  MOBILE_PRODUCT_MARKERS,
+  mobileProductMarkers
+};

package/dist/adapters/mobile/prepare.js

@@ -0,0 +1,146 @@
+import path from "node:path";
+import { recordDepsBaseline } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
+import { runnerDir } from "../../paths.js";
+import {
+  decideMobileReadiness
+} from "./runtime-decision.js";
+const POD_PROBE_ENV = {
+  FORCE_COLOR: "0",
+  NO_COLOR: "1",
+  LANG: process.env.LANG?.includes("UTF-8") ? process.env.LANG : "en_US.UTF-8",
+  LC_ALL: process.env.LC_ALL?.includes("UTF-8") ? process.env.LC_ALL : "en_US.UTF-8"
+};
+async function mobileRuntimeStatus(target, opts = {}) {
+  return decideMobileReadiness(target, {
+    watcherPort: opts.watcherPort,
+    metroLog: opts.metroLog,
+    platform: opts.platform,
+    record: opts.record,
+    preflightMode: opts.preflightMode
+  });
+}
+async function prepareMobile(target, opts = {}) {
+  const json = opts.json ?? false;
+  const platform = opts.platform ?? "ios";
+  const preflightMode = opts.preflightMode ?? "fast";
+  const clearMetro = opts.clearMetro ?? false;
+  const report = await decideMobileReadiness(target, {
+    watcherPort: opts.watcherPort,
+    metroLog: opts.metroLog,
+    platform,
+    record: opts.record,
+    preflightMode
+  });
+  if (report.decision === "blocked") {
+    const reasons = report.reasons.join(" ");
+    const next = report.userAction ?? "fix the bundle error in app code before retrying recipe up.";
+    const msg = `mobile prepare blocked: ${reasons}
+  Next: ${next}`;
+    if (!json) process.stderr.write(`${msg}
+`);
+    return { status: EXIT.runtime, output: msg };
+  }
+  if (report.decision === "ready") {
+    return { status: 0, output: "" };
+  }
+  if (report.decision === "unknown") {
+    const msg = "mobile prepare: runtime state unknown\n  Next: run mm-harness verify --adapter mobile --target <checkout>";
+    if (!json) process.stderr.write(`${msg}
+`);
+    return { status: EXIT.runtime, output: msg };
+  }
+  const actions = clearMetro ? report.actions.map(
+    (a) => a.id === "start-metro" && !a.argv?.includes("--clear") ? { ...a, argv: [...a.argv ?? [], "--clear"] } : a
+  ) : report.actions;
+  for (const action of actions) {
+    const result = await dispatchAction(action, target, platform, json, preflightMode);
+    if (result.status !== 0) return result;
+    if (action.id === "yarn-setup") recordDepsBaseline(path.resolve(target));
+  }
+  if (report.decision === "install" && !process.env["RECIPE_UP_INSTALL_ATTEMPTED"]) {
+    process.env["RECIPE_UP_INSTALL_ATTEMPTED"] = "1";
+    const postInstall = await decideMobileReadiness(target, {
+      watcherPort: opts.watcherPort,
+      metroLog: opts.metroLog,
+      platform,
+      preflightMode
+    });
+    switch (postInstall.decision) {
+      case "install": {
+        const msg = `mobile prepare: dependencies installed but runtime is still unresolved (${postInstall.reasons.join("; ")})
+  Next: inspect the checkout \u2014 node_modules may be incomplete or yarn.lock drifted.`;
+        if (!json) process.stderr.write(`${msg}
+`);
+        return { status: EXIT.runtime, output: msg };
+      }
+      case "ready": {
+        const bridge = await dispatchAction({ id: "wait-for-bridge", cwd: target }, target, platform, json, preflightMode);
+        if (bridge.status !== 0) return bridge;
+        break;
+      }
+      case "launch": {
+        for (const action of postInstall.actions) {
+          const result = await dispatchAction(action, target, platform, json, preflightMode);
+          if (result.status !== 0) return result;
+        }
+        break;
+      }
+      default: {
+        const msg = `mobile prepare: post-install state is ${postInstall.decision}: ${postInstall.reasons.join("; ")}
+  Next: run mm-harness verify --adapter mobile --target <checkout>`;
+        if (!json) process.stderr.write(`${msg}
+`);
+        return { status: EXIT.runtime, output: msg };
+      }
+    }
+  }
+  return { status: 0, output: "" };
+}
+async function dispatchAction(action, target, platform, json, preflightMode = "fast") {
+  const cwd = action.cwd ?? target;
+  switch (action.id) {
+    case "yarn-setup": {
+      const leaf = path.join(runnerDir, "adapters/mobile/yarn-setup.sh");
+      return spawnScriptStreaming(leaf, ["--target", cwd], target, POD_PROBE_ENV);
+    }
+    case "start-metro": {
+      const leaf = path.join(runnerDir, "adapters/mobile/start-metro.sh");
+      const extra = action.argv ?? [];
+      return spawnScriptStreaming(leaf, ["--target", cwd, ...extra], target);
+    }
+    case "prewarm-bundle": {
+      const leaf = path.join(runnerDir, "adapters/mobile/prewarm-bundle.sh");
+      return spawnScriptStreaming(leaf, ["--platform", platform, "--target", cwd], target);
+    }
+    case "wait-for-bridge": {
+      const leaf = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
+      return spawnScriptStreaming(leaf, ["--target", cwd], target);
+    }
+    case "clear-metro-cache": {
+      const leaf = path.join(runnerDir, "adapters/mobile/start-metro.sh");
+      return spawnScriptStreaming(leaf, ["--target", cwd, "--clear"], target);
+    }
+    case "launch-mobile-runtime": {
+      const leaf = path.join(runnerDir, "adapters/mobile/open-device.sh");
+      return spawnScriptStreaming(
+        leaf,
+        ["--platform", platform, "--target", cwd, "--preflight-mode", preflightMode],
+        target,
+        POD_PROBE_ENV
+      );
+    }
+    case "rebuild-native-dev-client": {
+      const msg = "rebuild-native-dev-client required: native module mismatch detected.\n  Next: yarn start:ios or yarn start:android to rebuild the native dev client, then re-run mm-harness launch.";
+      if (!json) process.stderr.write(`${msg}
+`);
+      return { status: EXIT.runtime, output: msg };
+    }
+    default:
+      return { status: 0, output: "" };
+  }
+}
+export {
+  mobileRuntimeStatus,
+  prepareMobile
+};