@deeeed/metamask-harness 0.74.0 → 0.76.0

package/dist/adapters/extension/readiness.js

@@ -0,0 +1,32 @@
+import { optionFlag, optionString, parsePort } from "../../commands/parse-args.js";
+import { ensureExtensionPerpsBuildFlag, extensionBrowserDoctorCheck, extensionBrowserResolutionDoctorCheck } from "./doctor-checks.js";
+import { readExtensionPinnedFlags } from "./feature-flags.js";
+import { extensionProductConfigBlock } from "./product-config.js";
+const extensionReadiness = {
+  compatibilityMode(_target, shape) {
+    if (!shape.extensionProject) return "unsupported/no bridge";
+    if (shape.extensionRuntime || shape.injectedHarness) return "bridge present";
+    return "bridge injectable";
+  },
+  checks: (target) => [extensionBrowserDoctorCheck(target), extensionBrowserResolutionDoctorCheck(target)],
+  captureProviders: ["cdp"],
+  fixes: [{ id: "extension-perps-build", apply: ensureExtensionPerpsBuildFlag }],
+  runtimeBlock: (target, runtime) => runtime?.reasonCode === "product-config-required" ? { id: "extension-product-config", userAction: extensionProductConfigBlock(target)?.userAction } : void 0,
+  pinnedFlags: readExtensionPinnedFlags,
+  statusRuntime: true
+};
+async function extensionRuntimeDecision(target, options) {
+  const cdpPortRaw = optionString(options, "cdpPort") ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  const cdpPort = cdpPortRaw === void 0 ? void 0 : parsePort(cdpPortRaw, "runtime-decision --cdp-port must be a port.");
+  const { decideExtensionReadiness } = await import("./runtime-decision.js");
+  const report = await decideExtensionReadiness(target, {
+    cdpPort,
+    watchLog: optionString(options, "watchLog"),
+    record: optionFlag(options, "record")
+  });
+  return { report, line: `${report.decision}${report.clean ? " (clean)" : ""} ${report.reasonCode} \u2014 ${report.reasons[0] ?? ""}` };
+}
+export {
+  extensionReadiness,
+  extensionRuntimeDecision
+};

package/dist/adapters/extension/reload.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { EXIT, spawnScript, usageOut } from "../../commands/shared.js";
+import { runnerDir } from "../../paths.js";
+function reloadExtension(target, json) {
+  const adapter = "extension";
+  if (!process.env.CDP_PORT) {
+    return usageOut(
+      json,
+      "reload",
+      "the Extension CDP port could not be resolved.",
+      "mm-harness launch"
+    );
+  }
+  const script = path.join(runnerDir, "adapters/extension/reattach.sh");
+  const args = ["--target", target, "--cdp-port", process.env.CDP_PORT];
+  if (process.env.WATCHER_PORT) {
+    args.push("--watcher-port", process.env.WATCHER_PORT);
+  }
+  const result = spawnScript(script, args, target, json);
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: result.status === 0,
+          adapter,
+          method: "cdp-reattach",
+          command: "reload",
+          cdpPort: Number(process.env.CDP_PORT),
+          ...result.status === 0 ? {} : { error: result.output.slice(-4e3) || "Extension reload failed." }
+        },
+        null,
+        2
+      )
+    );
+  }
+  return result.status === 0 ? EXIT.ok : EXIT.runtime;
+}
+export {
+  reloadExtension
+};

package/dist/adapters/extension/run.js

@@ -0,0 +1,105 @@
+import { optionString } from "../../commands/parse-args.js";
+import { resolveExtensionBrowserPid } from "../../recording-target.js";
+import {
+  ensureExtensionConsoleCapture,
+  extensionCaptureFiles,
+  extensionCdpPort,
+  verifyExtensionConsoleControl
+} from "./console-capture.js";
+import { launchedBrowser } from "./launched-browser.js";
+const extensionRun = {
+  async prepareRuntime(projectRoot, runtimeOptions) {
+    if (runtimeOptions.skipExtensionRuntimePrepare === true) return;
+    const { releaseArtifactState, runtimeDistCheck } = await import("./runtime-decision.js");
+    const artifact = releaseArtifactState(projectRoot);
+    const runtimeSnapshot = runtimeDistCheck(projectRoot, artifact);
+    if (artifact.status !== "none") {
+      if (artifact.status === "valid" && runtimeSnapshot.status === "fresh") return;
+      throw new Error(
+        "The loaded release artifact identity is invalid or stale. Next: rerun runtime-launch with the same artifact source."
+      );
+    }
+    const { prepareExtensionRuntime } = await import("./runtime.js");
+    await prepareExtensionRuntime({
+      projectRoot,
+      cdpPort: runtimeOptions.cdpPort,
+      slot: runtimeOptions.slot,
+      launchExistingDist: runtimeOptions.launchExistingDist === true,
+      validationRuntimeDir: runtimeOptions.validationRuntimeDir,
+      pageMode: "home-or-sidepanel"
+    });
+  },
+  // The proof runtime is checked on the run's own ports: explicit flags win over
+  // the slot's for the check, and the slot's come back afterwards.
+  runtimeCheck({ target, options, heal, state, json, onRecovery }) {
+    return async () => {
+      const cliOptions = options;
+      const previousCdpPort = process.env.CDP_PORT;
+      const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+      const previousWatcherPort = process.env.WATCHER_PORT;
+      const explicitCdpPort = optionString(cliOptions, "cdpPort");
+      const explicitWatcherPort = optionString(cliOptions, "watcherPort") ?? optionString(cliOptions, "metroPort");
+      if (explicitCdpPort) {
+        process.env.CDP_PORT = explicitCdpPort;
+        process.env.RECIPE_CDP_PORT = explicitCdpPort;
+      }
+      if (explicitWatcherPort) process.env.WATCHER_PORT = explicitWatcherPort;
+      try {
+        const { ensureExtensionProofRuntime } = await import("../../commands/run-engine.js");
+        return await ensureExtensionProofRuntime(target, heal, state, json, { onRecovery });
+      } finally {
+        restoreEnv("CDP_PORT", previousCdpPort);
+        restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
+        restoreEnv("WATCHER_PORT", previousWatcherPort);
+      }
+    };
+  },
+  launchedBrowser: (target, artifactsDir, cdpPort) => launchedBrowser(target, artifactsDir, cdpPort)
+};
+const extensionRecording = {
+  target: (context) => resolveExtensionRecordingTarget(context),
+  framed: {
+    browserPid: (projectRoot, artifactsDir, cdpPort) => resolveExtensionBrowserPid(projectRoot, artifactsDir, cdpPort)
+  }
+};
+async function resolveExtensionRecordingTarget(context) {
+  const pid = resolveExtensionBrowserPid(
+    context.projectRoot,
+    context.artifactsDir,
+    context.env.CDP_PORT ?? context.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT
+  );
+  if (!pid) {
+    throw new Error(
+      "Could not resolve the extension browser PID for --record-video. Ensure the slot browser is running and CDP_PORT is set."
+    );
+  }
+  return { kind: "pid", pid };
+}
+const extensionDiagnostics = {
+  console: {
+    start: (projectRoot) => ensureExtensionConsoleCapture(projectRoot),
+    files: (projectRoot) => extensionCaptureFiles(projectRoot),
+    cdpPort: () => extensionCdpPort(),
+    verifyControl: (capture) => verifyExtensionConsoleControl(capture)
+  }
+};
+const extensionObservation = {
+  network: {
+    backend: async (_target, env, artifactsDir) => (await import("../../network-observation.js")).createExtensionNetworkBackend(env, artifactsDir),
+    actions: true
+  },
+  performance: {
+    backend: async (target, env, ports) => (await import("../../performance-observation.js")).createExtensionPerformanceObserver(target, env, ports),
+    platform: () => "extension"
+  }
+};
+function restoreEnv(key, value) {
+  if (value === void 0) delete process.env[key];
+  else process.env[key] = value;
+}
+export {
+  extensionDiagnostics,
+  extensionObservation,
+  extensionRecording,
+  extensionRun
+};

package/dist/adapters/extension/surface.js

@@ -10,6 +10,10 @@ import {
 import { decideExtensionReadiness } from "./runtime-decision.js";
 import { extensionProductConfigBlock } from "./product-config.js";
 import { adapterRegistry } from "../registry.js";
+import { extensionActions } from "./actions.js";
+import { extensionHarness, extensionPrepare, extensionRuntimeContext } from "./overlay.js";
+import { extensionReadiness, extensionRuntimeDecision } from "./readiness.js";
+import { extensionDiagnostics, extensionObservation, extensionRecording, extensionRun } from "./run.js";
 function watcherStatus(buildLog) {
   if (buildLog === "ok") return "up";
   if (buildLog === "no-watch") return "down";
@@ -82,7 +86,8 @@ const extensionSurface = {
       spawnSync("bash", [stopViewers, "--target", target], { stdio: "ignore", timeout: 5e3 });
       const summary = stopped.signalled > 0 || stopped.removedMarkers > 0 ? `stopped Extension runtime (${stopped.signalled} process${stopped.signalled === 1 ? "" : "es"}, ${stopped.removedMarkers} stale marker${stopped.removedMarkers === 1 ? "" : "s"}) for ${target}` : `Extension runtime not running for ${target} \u2014 nothing to stop`;
       return { kind: "stopped", status: 0, summary, signalled: stopped.signalled };
-    }
+    },
+    afterStop: (target) => `mm-harness launch --target ${shellQuote(target)}`
   },
   logSources(target) {
     return [
@@ -103,10 +108,33 @@ const extensionSurface = {
   launch: async (context) => {
     const [{ runDeviceLaunch }, { extensionLaunchProfile }] = await Promise.all([
       import("../../commands/launch/device.js"),
-      import("../../commands/launch/extension.js")
+      import("./launch.js")
     ]);
     return runDeviceLaunch(context, extensionLaunchProfile);
-  }
+  },
+  actions: extensionActions,
+  harness: extensionHarness,
+  runtimeContext: extensionRuntimeContext,
+  readiness: extensionReadiness,
+  fixtures: {
+    operations: ["init", "sync", "set", "reset", "generate", "finalize"],
+    apply: async (context) => (await import("./fixtures.js")).applyExtensionFixture(context)
+  },
+  prepare: extensionPrepare,
+  debug: {
+    refuse: ({ devMenu }) => devMenu ? { message: "--dev-menu is mobile-only (RN developer menu). Use --worker on the extension.", userAction: "mm-harness debug --worker" } : void 0,
+    args: ({ worker }) => [
+      ...process.env.CDP_PORT ? ["--cdp-port", process.env.CDP_PORT] : [],
+      "--target",
+      worker ? "worker" : "page"
+    ]
+  },
+  reload: async (target, json) => (await import("./reload.js")).reloadExtension(target, json),
+  runtimeDecision: extensionRuntimeDecision,
+  run: extensionRun,
+  recording: extensionRecording,
+  diagnostics: extensionDiagnostics,
+  observation: extensionObservation
 };
 adapterRegistry.register(extensionSurface);
 export {

package/dist/adapters/harness-freshness.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { recipeHarnessPath, runnerDir } from "../paths.js";
+import { getAdapterSurface } from "./surface.js";
 async function ensureHarnessFresh(target, adapter) {
   if (!fs.existsSync(path.join(target, "package.json")) || !hasCheckoutHead(target)) return;
   let current;
@@ -17,9 +18,10 @@ async function ensureHarnessFresh(target, adapter) {
   const installed = readInstalledFingerprint(manifestPath);
   if (installed === current) return;
   const reason = installed === null ? "harness not installed" : "runner changed";
-  const injector = path.join(runnerDir, `adapters/${adapter}/inject.${adapter === "extension" ? "mjs" : "sh"}`);
+  const install = getAdapterSurface(adapter).harness.install;
+  const injector = path.resolve(runnerDir, install.entry);
   try {
-    execFileSync(adapter === "extension" ? process.execPath : "bash", [injector, "--target", target], {
+    execFileSync(install.node ? process.execPath : "bash", [injector, "--target", target], {
       stdio: ["ignore", "ignore", "inherit"]
     });
     console.error(`\u2192 refreshed ${adapter} harness overlay (${reason})`);

package/dist/adapters/mobile/actions.js

@@ -0,0 +1,54 @@
+import { manifestPath } from "../../paths.js";
+const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.press",
+  "ui.key_press",
+  "ui.set_input",
+  "ui.scroll",
+  "ui.swipe",
+  "ui.pan",
+  "ui.drag",
+  "ui.long_press",
+  "ui.wait_for",
+  "ui.screenshot",
+  "ui.capture_surface"
+]);
+const mobileActions = {
+  manifestPath: () => manifestPath("mobile"),
+  semantic: [
+    "app.network_capture",
+    "app.network_assert",
+    "app.performance_capture",
+    "app.performance_assert",
+    "metamask.swap_bridge.submit_transaction",
+    "metamask.perps.close_positions",
+    "metamask.perps.start_state",
+    "metamask.perps.clear_performance_caches",
+    "metamask.perps.measure_homepage_visible",
+    "metamask.perps.prepare_local_snapshot_endpoint"
+  ],
+  cdpTarget: {
+    transport: "react-native-debug-bridge",
+    probePath: "json/list",
+    watcherPortFirst: true,
+    requiredProbe: async (node, context) => (await import("./ui.js")).probeMobileBridgeTarget(node, context)
+  },
+  ui: (harness) => ({
+    base: harness.createReactNativeBridgeUiTransport({
+      bridge: {
+        send: async (command, context) => (await import("./ui.js")).sendMobileBridgeCommand(command, context)
+      }
+    }),
+    async execute(action, node, context, standard) {
+      if (NATIVE_PROVIDER_UI_ACTIONS.has(action) && (context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1" || ["ui.swipe", "ui.pan", "ui.drag", "ui.long_press", "ui.capture_surface"].includes(action))) {
+        const { executeNativeProviderAction } = await import("./ui.js");
+        return executeNativeProviderAction(action, node, context, harness.createNativeUiTransport);
+      }
+      return standard();
+    }
+  }),
+  wrap: async (adapters) => (await import("./runtime-identity.js")).withMobileNativeRuntimeIdentity(adapters),
+  lifecycle: async (adapters) => (await import("./lifecycle.js")).mobileSourceAwareLifecycleAdapters(adapters)
+};
+export {
+  mobileActions
+};

package/dist/adapters/mobile/devices.js

@@ -0,0 +1,21 @@
+import {
+  mobileDeviceLiveView,
+  mobileDeviceView,
+  nextForLive,
+  renderAdditionalReachableDevices,
+  renderAndroidPortHints,
+  renderMobileDeviceList,
+  renderMobileLiveBlock
+} from "../../commands/mobile-device-view.js";
+const mobileDevices = {
+  view: mobileDeviceView,
+  live: mobileDeviceLiveView,
+  renderList: renderMobileDeviceList,
+  renderAdditional: renderAdditionalReachableDevices,
+  renderLive: renderMobileLiveBlock,
+  renderPortHints: renderAndroidPortHints,
+  nextForLive
+};
+export {
+  mobileDevices
+};

package/dist/adapters/mobile/doctor-checks.js

@@ -0,0 +1,40 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import {
+  mobileToolRecovery,
+  resolveMobileToolPath
+} from "../../../library/actions/mobile/platform/tool-paths.mjs";
+import { runnerDir } from "../../paths.js";
+function mobileToolDoctorChecks(platform) {
+  const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
+    { tool: "adb", platform: "Android" },
+    { tool: "idb", platform: "iOS" }
+  ];
+  return specs.map(({ tool, platform: platformName }) => {
+    const resolved = resolveMobileToolPath(tool);
+    return {
+      id: `device-tool-${tool}`,
+      status: resolved ? "pass" : "fail",
+      required: platform !== void 0,
+      message: resolved ? `${platformName} device tool ${tool} is ready.` : `${platformName} device tool ${tool} is unavailable.`,
+      ...resolved ? { detail: resolved } : {},
+      ...!resolved ? { userAction: mobileToolRecovery(tool) } : {}
+    };
+  });
+}
+function detectOrphanMetros(target, livePort) {
+  try {
+    const script = path.join(runnerDir, "adapters/shared/reap-checkout-metros.sh");
+    const out = execFileSync("bash", [script, "detect", target, livePort ?? ""], {
+      encoding: "utf8",
+      timeout: 5e3
+    });
+    return out.split("\n").map((line) => line.trim()).filter((line) => /^\d+$/u.test(line));
+  } catch {
+    return [];
+  }
+}
+export {
+  detectOrphanMetros,
+  mobileToolDoctorChecks
+};

package/dist/adapters/mobile/fixtures.js

@@ -0,0 +1,141 @@
+import path from "node:path";
+import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
+import { runnerDir } from "../../paths.js";
+import { FIXTURE_STREAM_TIMEOUT_MS } from "../../commands/fixtures.js";
+const FIXTURE_BRIDGE_READY_TIMEOUT_MS = 18e4;
+const MOBILE_SETUP_WALLET_TIMEOUT_MS = 36e4;
+async function applyMobileFixture({
+  target,
+  sub,
+  fixturePath,
+  canonicalFixture,
+  fixtureFlags,
+  json,
+  retryHint
+}) {
+  const adapter = "mobile";
+  const fixtureFlagsJson = JSON.stringify(fixtureFlags);
+  const reset = sub === "reset";
+  process.stderr.write(`\u2192 fixtures ${sub} ${adapter} \u2014 ${reset ? "resetting selected app data, relaunching, then applying" : "connecting bridge + applying"} wallet fixture (can take ~30s)\u2026
+`);
+  let status;
+  let mobileSetupResult;
+  let resetError;
+  const setupWalletSh = path.join(runnerDir, "adapters/mobile/bridge-runtime/setup-wallet.sh");
+  const previousAppRoot = process.env.APP_ROOT;
+  process.env.APP_ROOT = target;
+  try {
+    if (reset) {
+      const platform = process.env.PLATFORM === "android" || process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
+      const port = process.env.WATCHER_PORT ?? process.env.METRO_PORT ?? "8081";
+      const resetAppData = path.join(runnerDir, "adapters/mobile/reset-app-data.sh");
+      const resetArgs = ["--platform", platform, "--target", target];
+      if (platform === "ios") {
+        resetArgs.push("--simulator", process.env.SIM_UDID || process.env.IOS_SIMULATOR || "booted");
+      } else if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL) {
+        resetArgs.push("--adb-serial", process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || "");
+      }
+      const resetResult = await spawnScriptStreaming(resetAppData, resetArgs, target, {
+        timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+      });
+      if (resetResult.status !== 0) {
+        resetError = new Error("Mobile app data reset failed.");
+      } else {
+        const prewarmBundle = path.join(runnerDir, "adapters/mobile/prewarm-bundle.sh");
+        const prewarmResult = await spawnScriptStreaming(
+          prewarmBundle,
+          ["--platform", platform, "--target", target, "--port", port],
+          target,
+          {
+            timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+          }
+        );
+        if (prewarmResult.status !== 0) {
+          resetError = new Error("Mobile bundle prewarm failed after app data reset.");
+        }
+      }
+      if (!resetError) {
+        const openDevice = path.join(runnerDir, "adapters/mobile/open-device.sh");
+        const openArgs = ["--platform", platform, "--target", target, "--port", port, "--preflight-mode", "fast", "--restart"];
+        if (platform === "ios") {
+          openArgs.push("--simulator", process.env.SIM_UDID || process.env.IOS_SIMULATOR || "booted");
+        } else if (process.env.ADB_SERIAL || process.env.ANDROID_SERIAL) {
+          openArgs.push("--adb-serial", process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || "");
+        }
+        const openResult = await spawnScriptStreaming(openDevice, openArgs, target, {
+          timeoutMs: FIXTURE_STREAM_TIMEOUT_MS
+        });
+        if (openResult.status !== 0) {
+          resetError = new Error("Mobile app relaunch after data reset failed.");
+        } else {
+          const waitForBridge = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
+          const waitResult = await spawnScriptStreaming(
+            waitForBridge,
+            ["--target", target, "--port", port, "--platform", platform, "--timeout-ms", String(FIXTURE_BRIDGE_READY_TIMEOUT_MS)],
+            target,
+            { timeoutMs: FIXTURE_BRIDGE_READY_TIMEOUT_MS + 1e4 }
+          );
+          if (waitResult.status !== 0) {
+            resetError = new Error("Mobile bridge did not return after app data reset.");
+          }
+        }
+      }
+    }
+    const configuredTimeout = Number(process.env.MM_HARNESS_FIXTURES_SET_TIMEOUT_MS ?? MOBILE_SETUP_WALLET_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(configuredTimeout) && configuredTimeout > 0 ? configuredTimeout : MOBILE_SETUP_WALLET_TIMEOUT_MS;
+    if (!resetError) {
+      mobileSetupResult = await spawnScriptStreaming(
+        setupWalletSh,
+        ["--fixture", fixturePath, "--remote-flags-json", fixtureFlagsJson],
+        target,
+        {
+          env: {
+            APP_ROOT: target,
+            WATCHER_PORT: process.env.WATCHER_PORT ?? "8081",
+            METRO_PORT: process.env.METRO_PORT ?? process.env.WATCHER_PORT ?? "8081"
+          },
+          timeoutMs
+        }
+      );
+    }
+    status = !resetError && mobileSetupResult?.status === 0 ? "pass" : "fail";
+  } finally {
+    if (previousAppRoot === void 0) delete process.env.APP_ROOT;
+    else process.env.APP_ROOT = previousAppRoot;
+  }
+  if (!json && status === "fail") {
+    console.error(`  Next: ${retryHint}`);
+  }
+  const teaching = status === "pass" ? `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}` : "Wallet fixture was not applied.";
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "fixtures",
+          action: sub,
+          adapter,
+          fixture: fixturePath,
+          canonicalFixture,
+          status,
+          exitCode: status === "pass" ? EXIT.ok : EXIT.runtime,
+          walletReset: reset && status === "pass",
+          message: teaching,
+          error: status === "fail" ? {
+            code: resetError ? "MOBILE_WALLET_RESET_FAILED" : mobileSetupResult?.timedOut ? "SETUP_WALLET_TIMEOUT" : "SETUP_WALLET_FAILED",
+            message: resetError ? `wallet reset failed: ${resetError instanceof Error ? resetError.message : String(resetError)}` : mobileSetupResult?.timedOut ? `wallet fixture setup exceeded its ${String(mobileSetupResult.timeoutMs)}ms bound on Metro port ${process.env.WATCHER_PORT ?? "8081"}` : `wallet fixture setup failed on ${process.env.WATCHER_PORT ?? "8081"}`,
+            userAction: retryHint
+          } : null
+        },
+        null,
+        2
+      )
+    );
+  } else if (status === "pass") {
+    console.error(teaching);
+  }
+  return status === "pass" ? EXIT.ok : EXIT.runtime;
+}
+export {
+  applyMobileFixture
+};