@deeeed/metamask-harness 0.4.0 → 0.5.0

package/dist/adapters.js

@@ -0,0 +1,485 @@
+import http from "node:http";
+import { compatibilityMode, fixtureSummary, repoShape } from "./doctor.js";
+import { runLiveAdapterScript } from "./live-adapter-contract.js";
+import { withExtensionPage } from "../library/actions/extension/platform/cdp.mjs";
+import { bridgeCommand, evalSync, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function simpleAdapter(action, executor) {
+  return {
+    action,
+    async execute(node, context) {
+      return executor(node, context);
+    }
+  };
+}
+const LIVE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set([
+  "metamask.perps.read_positions",
+  "metamask.perps.ensure_positions",
+  "metamask.perps.assert_positions",
+  "metamask.perps.place_order",
+  "metamask.perps.close_positions",
+  "metamask.perps.read_orders",
+  "metamask.perps.close_orders",
+  "metamask.perps.ensure_orders",
+  "metamask.perps.assert_orders",
+  "metamask.perps.start_state",
+  "metamask.perps.teardown_state"
+]);
+const CORE_ONLY_PERPS_ACTIONS = /* @__PURE__ */ new Set(["metamask.perps.read_account"]);
+const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
+  "metamask.wallet.setup",
+  "metamask.wallet.ensure_unlocked",
+  "metamask.wallet.select_account",
+  "metamask.wallet.read_state"
+]);
+const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set(["ui.navigate"]);
+function requiresLiveAdapter(platform, action) {
+  return LIVE_ONLY_PERPS_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
+}
+function liveRuntimeConfigured(platform, node) {
+  if (platform === "mobile" || platform === "core") return true;
+  return Boolean(node.cdp_port ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT);
+}
+async function runLiveFirst(platform, action, node, context) {
+  if (node.allow_static_placeholder === true) {
+    throw new Error(
+      `${action} refused allow_static_placeholder. MetaMask runner proof runs must use live adapters and real artifacts.`
+    );
+  }
+  if (!requiresLiveAdapter(platform, action) && !liveRuntimeConfigured(platform, node)) return null;
+  const live = await runLiveAdapterScript({ platform, action, node, context });
+  if (!live) return null;
+  const liveResult = isRecord(live.result) ? live.result : { result: live.result };
+  const output = { ...liveResult, liveAdapter: live.script };
+  return {
+    output,
+    artifacts: isRecord(live.result) && Array.isArray(live.result.artifacts) ? live.result.artifacts : void 0
+  };
+}
+function liveAdapterPathHint(platform, action) {
+  if (action.startsWith("metamask.")) {
+    return `library/actions/${platform}/${action.replace(/^metamask[.]/u, "").replaceAll(".", "/")}.mjs`;
+  }
+  return `library/actions/${platform}/${action.replaceAll(".", "/")}.mjs`;
+}
+async function semanticResult(platform, action, node, context) {
+  const live = await runLiveFirst(platform, action, node, context);
+  if (live) return live;
+  if (requiresLiveAdapter(platform, action)) {
+    const expected = liveAdapterPathHint(platform, action);
+    throw new Error(
+      `${action} requires a live ${platform} adapter that drives a real supported app/API path; no adapter script was found or no live runtime is configured (for example ${expected}). Static placeholders are refused to avoid fabricated proof. Set METAMASK_RECIPE_LIVE_ADAPTER_DIR or add a runner library/actions script.`
+    );
+  }
+  const output = { platform, action, redacted: true };
+  if (action === "metamask.wallet.fixture_status") return { output: fixtureSummary(context.projectRoot) };
+  return {
+    output: {
+      ...output,
+      requested: Object.fromEntries(Object.entries(node).filter(([key]) => key !== "action")),
+      note: "static semantic adapter; live proof must use a real supported app/API path"
+    }
+  };
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function optionalScalarText(value, label) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  throw new Error(`${label} must be a string, number, or boolean.`);
+}
+function scalarText(value, label, fallback) {
+  return optionalScalarText(value, label) ?? fallback;
+}
+function firstScalarText(record, keys, label, fallback) {
+  for (const key of keys) {
+    const value = optionalScalarText(record[key], `${label}.${key}`);
+    if (value !== void 0) return value;
+  }
+  if (fallback !== void 0) return fallback;
+  throw new Error(`${label} requires one of: ${keys.join(", ")}.`);
+}
+function traceText(value) {
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+function probeHttpJson(url, timeoutMs = 1e3) {
+  return new Promise((resolve) => {
+    const request = http.get(url, { timeout: timeoutMs }, (response) => {
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        body += chunk;
+      });
+      response.on("end", () => {
+        if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+          resolve({ reachable: false, statusCode: response.statusCode ?? null, error: `HTTP ${response.statusCode ?? "unknown"}` });
+          return;
+        }
+        try {
+          resolve({ reachable: true, statusCode: response.statusCode, json: JSON.parse(body) });
+        } catch (error) {
+          resolve({
+            reachable: true,
+            statusCode: response.statusCode,
+            json: null,
+            parseError: error instanceof Error ? error.message : String(error)
+          });
+        }
+      });
+    });
+    request.on("timeout", () => {
+      request.destroy(new Error(`Timed out after ${timeoutMs}ms`));
+    });
+    request.on("error", (error) => {
+      resolve({ reachable: false, statusCode: null, error: error.message });
+    });
+  });
+}
+function createMetaMaskSemanticAdapters(platform) {
+  const walletActions = [
+    "metamask.wallet.fixture_status",
+    "metamask.wallet.setup",
+    "metamask.wallet.ensure_unlocked",
+    "metamask.wallet.select_account",
+    "metamask.wallet.read_state"
+  ];
+  const actions = [
+    ...walletActions,
+    "metamask.perps.read_positions",
+    "metamask.perps.ensure_positions",
+    "metamask.perps.assert_positions",
+    "metamask.perps.place_order",
+    "metamask.perps.close_positions",
+    "metamask.perps.read_orders",
+    "metamask.perps.close_orders",
+    "metamask.perps.ensure_orders",
+    "metamask.perps.assert_orders",
+    "metamask.perps.start_state",
+    "metamask.perps.teardown_state",
+    // read_account is core-only: only the headless core adapter implements it.
+    ...platform === "core" ? ["metamask.perps.read_account"] : []
+  ];
+  return actions.map(
+    (action) => simpleAdapter(
+      action,
+      async (node, context) => semanticResult(platform, action, node, context)
+    )
+  );
+}
+function uiInputFor(context, input) {
+  return {
+    action: input.action,
+    node: input.node,
+    context: {
+      nodeId: context.nodeId,
+      projectRoot: context.projectRoot,
+      artifactsDir: context.artifactsDir,
+      env: context.env
+    }
+  };
+}
+function mobileProbeOutput(status, input, projectRoot) {
+  const entries = Array.isArray(status) ? status : [status];
+  const preferredDevices = [
+    input.node?.ios_simulator,
+    input.node?.simulator,
+    input.node?.android_device,
+    input.node?.adb_serial,
+    process.env.IOS_SIMULATOR,
+    process.env.ANDROID_DEVICE,
+    process.env.ADB_SERIAL
+  ].filter((value) => typeof value === "string" && value.length > 0);
+  const selected = entries.find((entry) => {
+    if (!isRecord(entry)) return false;
+    return typeof entry.deviceName === "string" && preferredDevices.includes(entry.deviceName);
+  }) ?? entries.find((entry) => isRecord(entry) && isRecord(entry.route)) ?? null;
+  const route = isRecord(selected) && isRecord(selected.route) ? selected.route : null;
+  return {
+    reachable: Boolean(selected),
+    bridge: mobileBridgePath(projectRoot),
+    targetCount: entries.filter((entry) => isRecord(entry)).length,
+    deviceName: isRecord(selected) && typeof selected.deviceName === "string" ? selected.deviceName : null,
+    routeName: route && typeof route.name === "string" ? route.name : null,
+    accountPresent: isRecord(selected) && isRecord(selected.account)
+  };
+}
+function mobileBridgePath(_projectRoot) {
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || "runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs";
+}
+async function waitForMobileTarget(input, payload) {
+  const timeoutMs = Number(payload.timeout_ms ?? payload.timeoutMs ?? 1e4);
+  const deadline = Date.now() + timeoutMs;
+  const testId = firstScalarText(payload, ["test_id", "testID"], "Mobile ui.wait_for");
+  const expected = scalarText(payload.expected, "ui.wait_for.expected", "present").toLowerCase();
+  const expectedText = optionalScalarText(payload.text, "ui.wait_for.text");
+  const textMatch = scalarText(payload.text_match ?? payload.textMatch, "ui.wait_for.text_match", "contains").toLowerCase();
+  const textExpression = `(function(){
+    const api = globalThis.__AGENTIC__;
+    if (!api?.getTextByTestId) return null;
+    return api.getTextByTestId(${JSON.stringify(testId)});
+  })()`;
+  const expression = `Boolean(globalThis.__AGENTIC__?.findFiberByTestId?.(${JSON.stringify(testId)}))`;
+  let lastValue = null;
+  let lastText = null;
+  const expectsAbsent = expected === "absent" || expected === "hidden" || expected === "not_present";
+  while (Date.now() <= deadline) {
+    lastValue = await evalSync(input, expression);
+    const present = Boolean(lastValue);
+    if (expectsAbsent && !present) {
+      return { matched: true, testId, expected, present };
+    }
+    if (!expectsAbsent && present) {
+      if (!expectedText) {
+        return { matched: true, testId, expected, present };
+      }
+      lastText = await evalSync(input, textExpression);
+      const text = traceText(lastText);
+      const textMatched = textMatch === "exact" ? text === expectedText : text.includes(expectedText);
+      if (textMatched) {
+        return { matched: true, testId, expected, present, text, textMatch };
+      }
+    }
+    await sleep(250);
+  }
+  const textReason = expectedText ? ` and text ${textMatch} ${JSON.stringify(expectedText)}; last text=${JSON.stringify(lastText)}` : "";
+  throw new Error(`Timed out waiting for mobile testID ${testId} to be ${expected}${textReason}; last present=${Boolean(lastValue)}.`);
+}
+const MOBILE_BRIDGE_HANDLERS = {
+  screenshot: handleMobileScreenshot,
+  status: handleMobileStatus,
+  navigate: handleMobileNavigate,
+  press: handleMobilePress,
+  setInput: handleMobileSetInput,
+  scroll: handleMobileScroll,
+  waitFor: handleMobileWaitFor,
+  hud: handleMobileHud
+};
+function createMetaMaskMobileBridge() {
+  return {
+    async send(command, context) {
+      const handler = MOBILE_BRIDGE_HANDLERS[command.command];
+      if (!handler) {
+        throw new Error(`React Native bridge command ${command.command} is not implemented by the MetaMask runner transport.`);
+      }
+      return handler(command.payload, context);
+    }
+  };
+}
+function mobileUiInput(context, command, payload) {
+  return uiInputFor(context, { action: `ui.${command}`, node: payload });
+}
+async function handleMobileScreenshot(payload, context) {
+  const input = mobileUiInput(context, "screenshot", payload);
+  const relPath = scalarText(payload.path, "ui.screenshot.path", `screenshots/${context.nodeId}.png`);
+  const artifact = await simulatorScreenshot(input, relPath);
+  context.registerArtifact(artifact);
+  return { captured: true, path: artifact.path, artifact };
+}
+async function handleMobileStatus(payload, context) {
+  return bridgeCommand(mobileUiInput(context, "status", payload), ["status"]);
+}
+async function handleMobileNavigate(payload, context) {
+  const live = await runLiveAdapterScript({
+    platform: "mobile",
+    action: "ui.navigate",
+    node: payload,
+    context
+  });
+  if (!live) throw new Error("ui.navigate requires library/actions/mobile/ui/navigate.mjs.");
+  return isRecord(live.result) ? { ...live.result, liveAdapter: live.script } : live.result;
+}
+async function handleMobilePress(payload, context) {
+  const target = firstScalarText(payload, ["test_id", "testID", "selector", "text"], "ui.press");
+  return bridgeCommand(mobileUiInput(context, "press", payload), ["press-test-id", target]);
+}
+async function handleMobileSetInput(payload, context) {
+  const input = mobileUiInput(context, "set_input", payload);
+  const testId = firstScalarText(payload, ["test_id", "testID"], "ui.set_input");
+  const value = scalarText(payload.value ?? payload.text, "ui.set_input.value", "");
+  const result = await bridgeCommand(input, ["set-input", testId, value]);
+  if (isRecord(result) && result.ok === false) {
+    throw new Error(`ui.set_input failed for mobile testID ${testId}: ${traceText(result.error ?? result)}`);
+  }
+  return isRecord(result) ? result : { result, testId, value };
+}
+async function handleMobileScroll(payload, context) {
+  const input = mobileUiInput(context, "scroll", payload);
+  const testId = optionalScalarText(payload.test_id ?? payload.testID, "ui.scroll.test_id");
+  const offset = scalarText(payload.offset ?? payload.delta_y ?? payload.deltaY, "ui.scroll.offset", "600");
+  const args = testId ? ["scroll-view", "--test-id", testId, "--offset", offset, animatedFlag(payload)] : ["scroll-view", "--offset", offset, animatedFlag(payload)];
+  const result = await bridgeCommand(input, args);
+  return {
+    ...isRecord(result) ? result : { result },
+    intoView: payload.scroll_into_view === true || payload.into_view === true
+  };
+}
+async function handleMobileWaitFor(payload, context) {
+  return waitForMobileTarget(mobileUiInput(context, "waitFor", payload), payload);
+}
+async function handleMobileHud(payload, context) {
+  const input = mobileUiInput(context, "hud", payload);
+  if (payload.clear === true) return bridgeCommand(input, ["hide-step"]);
+  const hud = mobileHudPayload(payload, context);
+  const result = await bridgeCommand(input, ["show-step-json", JSON.stringify(hud.step)]);
+  return { hud: true, nodeId: hud.nodeId, status: hud.status, result };
+}
+function animatedFlag(payload) {
+  return payload.animated === true ? "--animated" : "--no-animated";
+}
+function mobileHudPayload(payload, context) {
+  const nodeId = scalarText(payload.node_id ?? payload.nodeId, "app.hud.node_id", context.nodeId);
+  const status = scalarText(payload.status, "app.hud.status", "running");
+  const text = optionalScalarText(payload.intent ?? payload.text ?? payload.detail, "app.hud.intent");
+  if (!text || !text.trim()) {
+    throw new Error("app.hud requires intent/text/detail; automatic recipe progress should provide node intent.");
+  }
+  const detail = scalarText(payload.detail, "app.hud.detail", "");
+  const error = scalarText(payload.error, "app.hud.error", "");
+  const progress = mobileHudProgress(payload.progress);
+  const display = isRecord(payload.display) ? payload.display : {};
+  const showDebug = display.showDebug === true;
+  const showDetail = display.showDetail === true;
+  const proofTarget = payload.proofTarget ?? payload.proof_target;
+  const displayId = [mobileHudStatusLabel(status), progress.text].filter(Boolean).join(" ");
+  return {
+    nodeId,
+    status,
+    step: {
+      id: displayId || nodeId,
+      nodeId,
+      status,
+      intent: text,
+      progress: progress.value,
+      detail: showDetail && detail !== text ? detail : void 0,
+      error: error || void 0,
+      debug: showDebug ? {
+        nodeId,
+        proofTarget
+      } : void 0
+    }
+  };
+}
+function mobileHudProgress(progress) {
+  if (!isRecord(progress)) return { text: "" };
+  if (typeof progress.current !== "number" || typeof progress.total !== "number") return { text: "" };
+  return {
+    text: `${progress.current}/${progress.total}`,
+    value: { current: progress.current, total: progress.total }
+  };
+}
+function mobileHudStatusLabel(status) {
+  if (status === "fail") return "fail";
+  if (status === "pass") return "pass";
+  return "run";
+}
+function createMetaMaskUiTransport(platform, harness) {
+  if (platform === "core") {
+    return {
+      async execute(action) {
+        throw new Error(
+          `core adapter is headless and cannot execute UI action ${action}. Use a perps read action or run the recipe against the mobile/extension adapter.`
+        );
+      }
+    };
+  }
+  const base = platform === "mobile" ? harness.createReactNativeBridgeUiTransport({ bridge: createMetaMaskMobileBridge() }) : harness.createCdpWebUiTransport({
+    async withPage(input, callback) {
+      return withExtensionPage(
+        {
+          action: input.action,
+          node: input.node,
+          context: {
+            nodeId: input.context.nodeId,
+            projectRoot: input.context.projectRoot,
+            artifactsDir: input.context.artifactsDir
+          }
+        },
+        callback
+      );
+    }
+  });
+  return {
+    async execute(action, node, context) {
+      if (action === "ui.navigate") {
+        const live = await runLiveFirst(platform, action, node, context);
+        if (live) return live.output;
+        throw new Error(`ui.navigate requires library/actions/${platform}/ui/navigate.mjs.`);
+      }
+      return base.execute(action, node, context);
+    }
+  };
+}
+function createMetaMaskAdapters(adapter) {
+  const platform = adapter;
+  const adapters = [
+    simpleAdapter("app.status", async (_node, context) => ({
+      output: {
+        platform,
+        projectRoot: context.projectRoot,
+        compatibilityMode: compatibilityMode(adapter, context.projectRoot),
+        shape: repoShape(context.projectRoot)
+      }
+    })),
+    simpleAdapter("cdp.target", async (node, context) => {
+      const cdpPort = node.cdp_port ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT ?? null;
+      const metroPort = node.metro_port ?? node.watcher_port ?? process.env.WATCHER_PORT ?? null;
+      const timeoutMs = Number(node.probe_timeout_ms ?? node.cdp_timeout_ms ?? node.timeout_ms ?? process.env.CDP_TIMEOUT ?? 1e4);
+      const required = node.require_reachable === true || node.required === true;
+      if (platform === "mobile" && required) {
+        const uiInput = { action: "cdp.target", nodeId: context.nodeId, node };
+        const status = await bridgeCommand(uiInputFor(context, uiInput), ["status"]);
+        const probe2 = mobileProbeOutput(status, uiInput, context.projectRoot);
+        if (!probe2.reachable) {
+          throw new Error("cdp.target required a reachable mobile React Native bridge, but bridge status did not expose a selected app route.");
+        }
+        return {
+          output: {
+            platform,
+            transport: "react-native-debug-bridge",
+            cdpPort,
+            metroPort,
+            timeoutMs,
+            ...probe2
+          }
+        };
+      }
+      const targetPort = platform === "mobile" ? metroPort ?? cdpPort : cdpPort;
+      const url = targetProbeUrl(platform, targetPort);
+      const probe = url ? await probeHttpJson(url, timeoutMs) : { reachable: null, statusCode: null, error: "no port declared" };
+      if (required && !probe.reachable) {
+        throw new Error(`cdp.target required a reachable ${platform} runtime at ${url ?? "<no port>"}: ${traceText(probe.error) || "not reachable"}`);
+      }
+      return {
+        output: {
+          platform,
+          transport: platform === "mobile" ? "react-native-debug-bridge" : "chrome-extension-cdp",
+          cdpPort,
+          metroPort,
+          probeUrl: url,
+          timeoutMs,
+          ...probe
+        }
+      };
+    }),
+    ...createMetaMaskSemanticAdapters(platform)
+  ];
+  return adapters;
+}
+function targetProbeUrl(platform, targetPort) {
+  if (!targetPort) return null;
+  const pathSuffix = platform === "mobile" ? "json/list" : "json/version";
+  return `http://127.0.0.1:${traceText(targetPort)}/${pathSuffix}`;
+}
+export {
+  createMetaMaskAdapters,
+  createMetaMaskUiTransport
+};

package/dist/cli-color.js

@@ -0,0 +1,79 @@
+const STYLES = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  label: "\x1B[1;36m",
+  cmd: "\x1B[1m",
+  ok: "\x1B[1;32m",
+  warn: "\x1B[1;33m",
+  err: "\x1B[1;31m",
+  info: "\x1B[0;37m",
+  accent: "\x1B[1;35m",
+  path: "\x1B[2m",
+  comment: "\x1B[2m",
+  active: "\x1B[1m"
+};
+function colorEnabled(stream = process.stderr) {
+  if (process.env.NO_COLOR != null && process.env.NO_COLOR !== "" && process.env.NO_COLOR !== "0") {
+    return false;
+  }
+  if (process.env.RECIPE_NO_COLOR === "1") return false;
+  if (process.env.RECIPE_COLOR === "1" || process.env.FORCE_COLOR === "1") return true;
+  return Boolean(stream?.isTTY);
+}
+function stripAnsi(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/gu, "");
+}
+function color(style, text, { stream = process.stderr } = {}) {
+  const value = String(text);
+  if (!colorEnabled(stream)) return value;
+  const code = STYLES[style];
+  if (!code) return value;
+  return `${code}${value}${STYLES.reset}`;
+}
+function colorKv(label, value, valueStyle = "info", { stream = process.stderr } = {}) {
+  return `${color("label", `${label}:`, { stream })} ${color(valueStyle, value, { stream })}`;
+}
+function colorStatusWord(word, { stream = process.stderr } = {}) {
+  const normalized = String(word || "").toLowerCase();
+  if (["up", "ready", "yes", "pass", "running", "present", "healthy"].includes(normalized)) {
+    return color("ok", word, { stream });
+  }
+  if (["down", "stopped", "no", "fail", "failed", "missing", "blocked", "unknown"].includes(normalized)) {
+    return color("err", word, { stream });
+  }
+  if (["compiling", "bundling", "starting", "waiting", "warn"].includes(normalized)) {
+    return color("warn", word, { stream });
+  }
+  return color("info", word, { stream });
+}
+function classifyLogEvent(event) {
+  const text = String(event || "");
+  if (/Module build failed|^ERROR in |BUILD FAILED|compiled with [1-9][0-9]* error/iu.test(text)) {
+    return "err";
+  }
+  if (/compiled successfully|compiled with [0-9]+ warning|PASS runtime-launch|launch pass|verify pass|build complete/iu.test(text)) {
+    return "ok";
+  }
+  if (/phase [0-9]\/[0-9]|prepare pipeline|snapshot|fixture:|dist-freshness|build-health/iu.test(text)) {
+    return "label";
+  }
+  if (/webpack [0-9]+%|Bundl(ed|ing)|(iOS|Android).*%/iu.test(text)) {
+    return "warn";
+  }
+  return "info";
+}
+function colorLogEvent(event, { latest = false, stream = process.stderr } = {}) {
+  const style = classifyLogEvent(event);
+  const painted = color(style === "label" ? "label" : style, event, { stream });
+  return latest ? color("active", painted, { stream }) : painted;
+}
+export {
+  classifyLogEvent,
+  color,
+  colorEnabled,
+  colorKv,
+  colorLogEvent,
+  colorStatusWord,
+  stripAnsi
+};