@deeeed/metamask-harness 0.41.1 → 0.43.0

package/dist/adapters/extension/browser-cdp.js

@@ -0,0 +1,174 @@
+import { WebSocket } from "ws";
+import { withTimeout } from "../../async.js";
+const DEFAULT_TIMEOUT_MS = 1e4;
+async function createBrowserCdpClient(cdpPort) {
+  if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
+    throw new Error("Extension CDP requires a valid port.");
+  }
+  const version = asRecord(
+    await fetchJson(`http://127.0.0.1:${cdpPort}/json/version`)
+  );
+  const webSocketUrl = String(version.webSocketDebuggerUrl ?? "");
+  if (!webSocketUrl) {
+    throw new Error("Extension browser CDP WebSocket is unavailable.");
+  }
+  const socket = new WebSocket(webSocketUrl);
+  await waitForOpen(socket);
+  let nextId = 0;
+  const pending = /* @__PURE__ */ new Map();
+  const handlers = /* @__PURE__ */ new Set();
+  const closeHandlers = /* @__PURE__ */ new Set();
+  socket.on("message", (data) => {
+    let message;
+    try {
+      message = JSON.parse(String(data));
+    } catch {
+      return;
+    }
+    if (message.id && pending.has(message.id)) {
+      const command = pending.get(message.id);
+      pending.delete(message.id);
+      if (!command) return;
+      clearTimeout(command.timer);
+      if (message.error) {
+        command.reject(
+          new Error(
+            String(message.error.message ?? "Extension CDP command failed")
+          )
+        );
+      } else {
+        command.resolve(message.result ?? {});
+      }
+      return;
+    }
+    for (const handler of handlers) handler(message);
+  });
+  socket.on("close", () => {
+    for (const command of pending.values()) {
+      clearTimeout(command.timer);
+      command.reject(new Error("Extension browser CDP connection closed"));
+    }
+    pending.clear();
+    handlers.clear();
+    for (const handler of closeHandlers) handler();
+    closeHandlers.clear();
+  });
+  return {
+    send(method, params = {}, sessionId, timeoutMs = DEFAULT_TIMEOUT_MS) {
+      return new Promise((resolve, reject) => {
+        const id = ++nextId;
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`Extension CDP command timed out: ${method}`));
+        }, timeoutMs);
+        pending.set(id, { resolve, reject, timer });
+        socket.send(
+          JSON.stringify({
+            id,
+            method,
+            params,
+            ...sessionId ? { sessionId } : {}
+          })
+        );
+      });
+    },
+    onMessage(handler) {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    },
+    onClose(handler) {
+      closeHandlers.add(handler);
+      return () => closeHandlers.delete(handler);
+    },
+    close() {
+      socket.close();
+    }
+  };
+}
+async function fetchCdpJson(cdpPort, path = "/json") {
+  return fetchJson(`http://127.0.0.1:${cdpPort}${path}`);
+}
+function asBrowserCdpTarget(value) {
+  const target = asRecord(value);
+  const targetId = String(target.targetId ?? target.id ?? "");
+  const type = String(target.type ?? "");
+  const url = String(target.url ?? "");
+  return targetId && type && url ? { targetId, type, url } : null;
+}
+function extensionIdFromCdpTargets(value) {
+  const targets = Array.isArray(value) ? value : [];
+  for (const candidate of targets) {
+    const target = asBrowserCdpTarget(candidate);
+    if (!target) continue;
+    try {
+      const url = new URL(target.url);
+      if (url.protocol === "chrome-extension:" && url.hostname) {
+        return url.hostname;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function selectExtensionUiTarget(value, extensionId) {
+  const targets = Array.isArray(value) ? value : [];
+  const candidates = targets.map(asBrowserCdpTarget).filter((candidate) => {
+    if (!candidate || !["page", "other"].includes(candidate.type)) return false;
+    try {
+      const url = new URL(candidate.url);
+      return url.protocol === "chrome-extension:" && url.hostname === extensionId;
+    } catch {
+      return false;
+    }
+  });
+  const matchingPath = (target, pathname) => {
+    try {
+      return new URL(target.url).pathname === pathname;
+    } catch {
+      return false;
+    }
+  };
+  const home = candidates.filter((target) => matchingPath(target, "/home.html"));
+  if (home.length > 0) return home.length === 1 ? home[0] : null;
+  const sidepanel = candidates.filter(
+    (target) => matchingPath(target, "/sidepanel.html")
+  );
+  return sidepanel.length === 1 ? sidepanel[0] : null;
+}
+async function fetchJson(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Extension CDP returned HTTP ${response.status}.`);
+  }
+  return response.json();
+}
+function waitForOpen(socket) {
+  const onOpen = (resolve) => () => resolve();
+  let openHandler;
+  let errorHandler;
+  const opened = new Promise((resolve, reject) => {
+    openHandler = onOpen(resolve);
+    errorHandler = reject;
+    socket.once("open", openHandler);
+    socket.once("error", errorHandler);
+  });
+  return withTimeout(opened, {
+    message: "Extension browser CDP connection timed out.",
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+    onTimeout: () => socket.close()
+  }).finally(() => {
+    if (openHandler) socket.off("open", openHandler);
+    if (errorHandler) socket.off("error", errorHandler);
+  });
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  asBrowserCdpTarget,
+  createBrowserCdpClient,
+  extensionIdFromCdpTargets,
+  fetchCdpJson,
+  selectExtensionUiTarget
+};

package/dist/adapters/extension/network-observer.js

@@ -0,0 +1,209 @@
+import path from "node:path";
+import brokerModule from "../../../adapters/mobile/bridge-runtime/lib/cdp-broker.cjs";
+import {
+  asBrowserCdpTarget,
+  createBrowserCdpClient,
+  extensionIdFromCdpTargets,
+  fetchCdpJson
+} from "./browser-cdp.js";
+const DEVICE_ID = "extension";
+const COMMAND_TIMEOUT_MS = 1e4;
+const EXTENSION_TARGET_TYPES = /* @__PURE__ */ new Set([
+  "background_page",
+  "other",
+  "page",
+  "service_worker"
+]);
+const { brokerSocketPath, createBrokerClient, createCdpBroker } = brokerModule;
+async function createExtensionNetworkObserver(cdpPort, runtimeDir) {
+  if (!Number.isInteger(cdpPort) || cdpPort <= 0) {
+    throw new Error("Extension network observation requires a valid CDP port.");
+  }
+  const targets = await fetchCdpJson(cdpPort);
+  const extensionId = extensionIdFromCdpTargets(targets);
+  if (!extensionId) {
+    throw new Error(
+      "Extension CDP browser or loaded extension target is unavailable."
+    );
+  }
+  const connection = await createBrowserCdpClient(cdpPort);
+  let closed = false;
+  const brokerRef = {};
+  const targetSessions = /* @__PURE__ */ new Map();
+  const attaching = /* @__PURE__ */ new Set();
+  const send = (method, params = {}, sessionId, timeoutMs = COMMAND_TIMEOUT_MS) => connection.send(method, params, sessionId, timeoutMs);
+  const relevantTarget = (target) => {
+    if (!EXTENSION_TARGET_TYPES.has(String(target.type))) return false;
+    try {
+      return new URL(String(target.url)).hostname === extensionId;
+    } catch {
+      return false;
+    }
+  };
+  const refreshBrokerSession = () => {
+    if (!brokerRef.current) return;
+    brokerRef.current.onSessionClose(DEVICE_ID);
+    brokerRef.current.onSessionOpen(DEVICE_ID);
+  };
+  const attachTarget = async (target) => {
+    if (closed || !relevantTarget(target) || targetSessions.has(target.targetId) || attaching.has(target.targetId)) {
+      return;
+    }
+    attaching.add(target.targetId);
+    try {
+      const result = asRecord(
+        await send("Target.attachToTarget", {
+          targetId: target.targetId,
+          flatten: true
+        })
+      );
+      const sessionId = String(result.sessionId ?? "");
+      if (sessionId) {
+        targetSessions.set(target.targetId, sessionId);
+        refreshBrokerSession();
+      }
+    } catch (error) {
+      if (!/already attached/iu.test(String(error))) {
+        brokerRef.current?.onSessionClose(DEVICE_ID);
+      }
+    } finally {
+      attaching.delete(target.targetId);
+    }
+  };
+  connection.onMessage((message) => {
+    if (message.method === "Target.targetCreated") {
+      const target = asBrowserCdpTarget(message.params?.targetInfo);
+      if (target) void attachTarget(target);
+      return;
+    }
+    if (message.method === "Target.attachedToTarget") {
+      const target = asBrowserCdpTarget(message.params?.targetInfo);
+      const sessionId = String(message.params?.sessionId ?? "");
+      if (target && sessionId && relevantTarget(target)) {
+        targetSessions.set(target.targetId, sessionId);
+        refreshBrokerSession();
+      }
+      return;
+    }
+    if (message.method === "Target.detachedFromTarget") {
+      const sessionId = String(message.params?.sessionId ?? "");
+      for (const [targetId, activeSessionId] of targetSessions) {
+        if (activeSessionId !== sessionId) continue;
+        targetSessions.delete(targetId);
+        refreshBrokerSession();
+      }
+      return;
+    }
+    if (message.sessionId && message.method?.startsWith("Network.")) {
+      brokerRef.current?.onCdpEvent(
+        DEVICE_ID,
+        message.method,
+        message.params ?? {}
+      );
+    }
+  });
+  connection.onClose(() => {
+    if (!closed) brokerRef.current?.onSessionClose(DEVICE_ID);
+  });
+  await send("Target.setDiscoverTargets", { discover: true });
+  const targetResult = asRecord(await send("Target.getTargets"));
+  const targetInfos = Array.isArray(targetResult.targetInfos) ? targetResult.targetInfos : [];
+  await Promise.all(
+    targetInfos.map(asBrowserCdpTarget).filter((target) => Boolean(target)).map(attachTarget)
+  );
+  if (targetSessions.size === 0) {
+    connection.close();
+    throw new Error("Extension CDP exposes no attachable extension targets.");
+  }
+  const sessions = /* @__PURE__ */ new Map([[DEVICE_ID, { brokerReady: true }]]);
+  const socketPath = brokerSocketPath(
+    path.join(runtimeDir, "extension-network")
+  );
+  brokerRef.current = createCdpBroker({
+    socketPath,
+    sessions,
+    async sendCommand(_session, method, params, timeoutMs) {
+      const sessionIds = [...new Set(targetSessions.values())];
+      if (sessionIds.length === 0) {
+        throw new Error(
+          "Extension CDP has no active extension target sessions."
+        );
+      }
+      const results = await Promise.allSettled(
+        sessionIds.map(
+          (sessionId) => send(method, params, sessionId, timeoutMs)
+        )
+      );
+      const successes = results.filter(
+        (result) => result.status === "fulfilled"
+      );
+      if (successes.length === 0) {
+        const firstFailure = results.find(
+          (result) => result.status === "rejected"
+        );
+        throw new Error(
+          `Extension CDP command failed on every target: ${String(firstFailure?.reason ?? method)}`
+        );
+      }
+      if (successes.length !== results.length) {
+        results.forEach((result, index) => {
+          if (result.status === "fulfilled") return;
+          const failedSession = sessionIds[index];
+          for (const [targetId, sessionId] of targetSessions) {
+            if (sessionId === failedSession) targetSessions.delete(targetId);
+          }
+        });
+        brokerRef.current?.onSessionClose(DEVICE_ID);
+      }
+      return successes[0].value;
+    },
+    requestDiscovery() {
+      void send("Target.getTargets").then((result) => {
+        const infos = asRecord(result).targetInfos;
+        if (!Array.isArray(infos)) return;
+        for (const value of infos) {
+          const target = asBrowserCdpTarget(value);
+          if (target) void attachTarget(target);
+        }
+      }).catch(() => brokerRef.current?.onSessionClose(DEVICE_ID));
+    }
+  });
+  brokerRef.current.onSessionOpen(DEVICE_ID);
+  await waitForSocket(socketPath);
+  const client = await createBrokerClient(
+    socketPath,
+    DEVICE_ID,
+    COMMAND_TIMEOUT_MS
+  );
+  return {
+    start(params) {
+      return client.control("capture-start", params, COMMAND_TIMEOUT_MS);
+    },
+    async end(id) {
+      return asRecord(
+        await client.control("capture-end", { id }, COMMAND_TIMEOUT_MS)
+      );
+    },
+    async close() {
+      closed = true;
+      client.close();
+      brokerRef.current?.close();
+      connection.close();
+    }
+  };
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+async function waitForSocket(socketPath) {
+  const { existsSync } = await import("node:fs");
+  const deadline = Date.now() + COMMAND_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (existsSync(socketPath)) return;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error("Extension network observer broker did not start.");
+}
+export {
+  createExtensionNetworkObserver
+};

package/dist/adapters/extension/performance-observer.js

@@ -0,0 +1,75 @@
+import {
+  createCdpTraceCollector
+} from "../performance/cdp-trace.js";
+import {
+  createBrowserCdpClient,
+  fetchCdpJson,
+  selectExtensionUiTarget
+} from "./browser-cdp.js";
+import { resolveExtensionId } from "./extension-id.js";
+async function createExtensionPerformanceBackend(cdpPort, target) {
+  const extensionId = (await resolveExtensionId(target, { cdpPort })).extensionId;
+  if (!extensionId) {
+    throw new Error("Extension performance observation could not resolve the MetaMask extension id.");
+  }
+  const uiTarget = selectExtensionUiTarget(
+    await fetchCdpJson(cdpPort),
+    extensionId
+  );
+  if (!uiTarget) {
+    throw new Error("Extension performance observation requires an open MetaMask UI target.");
+  }
+  const browser = await createBrowserCdpClient(cdpPort);
+  const attached = asRecord(
+    await browser.send(
+      "Target.attachToTarget",
+      { targetId: uiTarget.targetId, flatten: true },
+      void 0,
+      1e4
+    )
+  );
+  const sessionId = String(attached.sessionId ?? "");
+  if (!sessionId) {
+    browser.close();
+    throw new Error("Extension performance observation could not attach to the MetaMask UI target.");
+  }
+  const client = browserTraceClient(browser);
+  return createCdpTraceCollector(client, "extension", async (name) => {
+    const before = Date.now();
+    await browser.send(
+      "Runtime.evaluate",
+      {
+        expression: `performance.mark(${JSON.stringify(name)})`,
+        returnByValue: true
+      },
+      sessionId,
+      1e4
+    );
+    const after = Date.now();
+    return {
+      hostEpochMs: (before + after) / 2,
+      uncertaintyMs: (after - before) / 2
+    };
+  });
+}
+function browserTraceClient(browser) {
+  return {
+    send(method, params = {}, timeoutMs) {
+      return browser.send(method, params, void 0, timeoutMs);
+    },
+    on(method, handler) {
+      return browser.onMessage((message) => {
+        if (message.method === method) handler(message.params ?? {});
+      });
+    },
+    close() {
+      browser.close();
+    }
+  };
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  createExtensionPerformanceBackend
+};

package/dist/adapters/mobile/frame-metrics.js

@@ -0,0 +1,45 @@
+function summarizeFrames(samples) {
+  const validSamples = samples.filter(
+    (sample) => Number.isFinite(sample.durationMs) && sample.durationMs > 0
+  );
+  const durations = validSamples.map((sample) => sample.durationMs).sort((first2, second) => first2 - second);
+  if (durations.length === 0) return { frameCount: 0 };
+  const jankValues = validSamples.map((sample) => sample.janky).filter((value) => value !== void 0);
+  const jankyFrameCount = jankValues.filter(Boolean).length;
+  const first = validSamples[0]?.completedAtEpochMs;
+  const last = validSamples.at(-1)?.completedAtEpochMs;
+  const elapsedMs = first !== void 0 && last !== void 0 && last > first ? last - first : void 0;
+  return {
+    ...elapsedMs ? {
+      averageFps: round(
+        (validSamples.length - 1) * 1e3 / elapsedMs
+      )
+    } : {},
+    frameCount: durations.length,
+    ...jankValues.length === validSamples.length ? {
+      jankyFrameCount,
+      jankyFramePercent: round(
+        jankyFrameCount / validSamples.length * 100
+      )
+    } : {},
+    longestFrameMs: round(durations.at(-1) ?? 0),
+    p50FrameMs: round(percentile(durations, 0.5)),
+    p95FrameMs: round(percentile(durations, 0.95)),
+    p99FrameMs: round(percentile(durations, 0.99))
+  };
+}
+function percentile(sorted, quantile) {
+  if (sorted.length === 1) return sorted[0] ?? 0;
+  const position = (sorted.length - 1) * quantile;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  const lowerValue = sorted[lower] ?? 0;
+  const upperValue = sorted[upper] ?? lowerValue;
+  return lowerValue + (upperValue - lowerValue) * (position - lower);
+}
+function round(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+export {
+  summarizeFrames
+};

package/dist/adapters/mobile/metro-env.js

@@ -32,10 +32,6 @@ function mobileMetroEnvCheck(target) {
     status: marker === null ? "missing" : marker.fingerprint === fingerprint ? "current" : "changed"
   };
 }
-function applyMobileMetroEnvPolicy(target, actions) {
-  if (mobileMetroEnvCheck(target).status === "current") return actions;
-  return actions.map((action) => action.id === "start-metro" && !action.argv?.includes("--clear") ? { ...action, argv: [...action.argv ?? [], "--clear"] } : action);
-}
 function recordMobileMetroEnvBaseline(target, expectedFingerprint) {
   if (mobileMetroEnvFingerprint(target) !== expectedFingerprint) return false;
   const marker = recipeRuntimePath(target, BASELINE_FILE);
@@ -69,7 +65,6 @@ function readBaseline(target) {
   }
 }
 export {
-  applyMobileMetroEnvPolicy,
   mobileMetroEnvCheck,
   mobileMetroEnvFingerprint,
   recordMobileMetroEnvBaseline

package/dist/adapters/mobile/performance-observer.js

@@ -0,0 +1,43 @@
+import {
+  createCdpTraceCollector
+} from "../performance/cdp-trace.js";
+import {
+  connectMobileBroker
+} from "../../network-observation.js";
+async function createMobilePerformanceBackend(target, env) {
+  const { client } = await connectMobileBroker(target, env);
+  return createCdpTraceCollector(
+    client,
+    resolvePlatform(env),
+    async (name) => {
+      const before = Date.now();
+      await markRuntime(client, name);
+      const after = Date.now();
+      return {
+        hostEpochMs: (before + after) / 2,
+        uncertaintyMs: (after - before) / 2
+      };
+    }
+  );
+}
+async function markRuntime(client, name) {
+  await client.send(
+    "Runtime.evaluate",
+    {
+      expression: `performance.mark(${JSON.stringify(name)})`,
+      returnByValue: true,
+      awaitPromise: false
+    },
+    1e4
+  );
+}
+function resolvePlatform(env) {
+  const explicit = String(
+    env.MM_HARNESS_EXPLICIT_PLATFORM ?? env.RECIPE_HARNESS_PLATFORM ?? ""
+  ).toLowerCase();
+  if (explicit === "android" || explicit === "ios") return explicit;
+  return env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_DEVICE ? "android" : "ios";
+}
+export {
+  createMobilePerformanceBackend
+};

package/dist/adapters/mobile/prepare.js

@@ -9,7 +9,6 @@ import {
   launchActions
 } from "./runtime-decision.js";
 import {
-  applyMobileMetroEnvPolicy,
   mobileMetroEnvCheck,
   recordMobileMetroEnvBaseline
 } from "./metro-env.js";
@@ -241,9 +240,8 @@ function withAppRestart(actions, restartApp) {
 }
 async function dispatchActionSequence(requestedActions, target, platform, json, preflightMode, watcherPort) {
   const resolved = path.resolve(target);
-  const actions = applyMobileMetroEnvPolicy(resolved, requestedActions);
   let pendingMetroEnvFingerprint;
-  for (const action of actions) {
+  for (const action of requestedActions) {
     if (action.id === "start-metro") {
       pendingMetroEnvFingerprint = mobileMetroEnvCheck(resolved).fingerprint;
     }

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

@@ -13,7 +13,7 @@ import { probeMetroPackager } from "@farmslot/recipe-harness/runtime/metro-probe
 import { recipeRuntimePath } from "../../paths.js";
 import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { mobileProductMarkers } from "./deps-markers.js";
-import { applyMobileMetroEnvPolicy, mobileMetroEnvCheck } from "./metro-env.js";
+import { mobileMetroEnvCheck } from "./metro-env.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;
@@ -130,13 +130,10 @@ async function decideMobileReadiness(target, options = {}) {
     decision: "launch",
     reasonCode: report.decision === "ready" ? env.status === "missing" ? "metro-env-baseline-missing" : "metro-env-changed" : report.reasonCode,
     reasons: [
-      env.status === "missing" ? "Metro environment has no successful bundle baseline; restart once with a cleared transform cache." : "Metro environment inputs changed since the successful bundle baseline; restart once with a cleared transform cache.",
+      env.status === "missing" ? "Metro environment has no successful bundle baseline; restart Metro to load the current environment without clearing its transform cache." : "Metro environment inputs changed since the successful bundle baseline; restart Metro without clearing its transform cache. Pass --clear-metro only if stale transforms are observed.",
       ...report.reasons
     ],
-    actions: applyMobileMetroEnvPolicy(
-      resolved,
-      report.decision === "ready" ? launchActions(resolved) : report.actions
-    )
+    actions: report.decision === "ready" ? launchActions(resolved) : report.actions
   };
 }
 async function computeMobileReadiness(resolved, options, fast) {
@@ -216,7 +213,7 @@ async function computeMobileReadiness(resolved, options, fast) {
       checks,
       actions: [
         { id: "rebuild-native-dev-client" },
-        ...launchActions(resolved, true)
+        ...launchActions(resolved)
       ]
     };
   }
@@ -231,11 +228,11 @@ async function computeMobileReadiness(resolved, options, fast) {
         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.",
+          metroLog.reason === "stale-bundle-error" ? "Metro log shows prior bundle failures but cited modules are installed; restart Metro without clearing the cache. Pass --clear-metro if the failure persists." : "Metro bundle is failing with current deps; restart Metro without clearing the cache. Pass --clear-metro if the failure persists.",
           ...excerpt ? [excerpt] : []
         ],
         checks,
-        actions: launchActions(resolved, true)
+        actions: launchActions(resolved)
       };
     }
     return {