@deeeed/metamask-harness 0.2.0

package/library/actions/mobile/perps/place_order.mjs

@@ -0,0 +1,7 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { assertPositions, placeOrder } from './perps.mjs';
+runAdapter(async (input) => {
+  const order = await placeOrder(input);
+  const assertion = await assertPositions(input, true);
+  return { ...assertion, submitted: order.submitted === true, order };
+});

package/library/actions/mobile/perps/read_orders.mjs

@@ -0,0 +1,4 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { readOrders } from './perps.mjs';
+
+runAdapter(readOrders);

package/library/actions/mobile/perps/read_positions.mjs

@@ -0,0 +1,3 @@
+import { runAdapter } from '../platform/bridge.mjs';
+import { readPerpsPositions } from './perps.mjs';
+runAdapter(readPerpsPositions);

package/library/actions/mobile/platform/bridge.mjs

@@ -0,0 +1,283 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function loadInput() {
+  const inputPath = process.argv[2] || process.env.METAMASK_RECIPE_ADAPTER_INPUT;
+  if (!inputPath) throw new Error('Missing live adapter input path.');
+  return JSON.parse(await readFile(inputPath, 'utf8'));
+}
+
+export async function writeOutput(input, output) {
+  await writeFile(input.outputPath, `${JSON.stringify(output, null, 2)}\n`);
+}
+
+export async function runAdapter(callback) {
+  const input = await loadInput();
+  const output = await callback(input);
+  await writeOutput(input, output);
+}
+
+function bridgeScript(input) {
+  if (process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT) {
+    return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT;
+  }
+  return path.join(runtimeDir(), 'cdp-bridge.cjs');
+}
+
+function runtimeDir() {
+  return fileURLToPath(new URL('../bridge-runtime', import.meta.url));
+}
+
+export function bridgeEnv(input) {
+  /** @type {NodeJS.ProcessEnv} */
+  const env = {
+    ...process.env,
+    ...(input.context?.env || {}),
+    CDP_TIMEOUT: String(input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? '10000'),
+  };
+  const target = resolveMobileTarget(input);
+  const watcherPort = target.watcherPort;
+  const simulator = target.iosSimulator;
+  const androidDevice = target.androidDevice;
+  const adbSerial = target.adbSerial;
+  if (watcherPort !== undefined && watcherPort !== null && String(watcherPort) !== '') env.WATCHER_PORT = String(watcherPort);
+  if (simulator !== undefined && simulator !== null && String(simulator) !== '') env.IOS_SIMULATOR = String(simulator);
+  if (androidDevice !== undefined && androidDevice !== null && String(androidDevice) !== '') env.ANDROID_DEVICE = String(androidDevice);
+  if (adbSerial !== undefined && adbSerial !== null && String(adbSerial) !== '') {
+    env.ADB_SERIAL = String(adbSerial);
+    env.ANDROID_SERIAL = String(adbSerial);
+  }
+  return env;
+}
+
+function resolveMobileTarget(input) {
+  const contextEnv = input.context?.env || {};
+  const watcherPort = input.node?.watcher_port ?? input.node?.metro_port ?? input.node?.cdp_port ?? contextEnv.WATCHER_PORT ?? contextEnv.CDP_PORT ?? contextEnv.RECIPE_CDP_PORT ?? process.env.WATCHER_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  const iosSimulator = input.node?.simulator ?? input.node?.ios_simulator ?? contextEnv.IOS_SIMULATOR ?? process.env.IOS_SIMULATOR;
+  const androidDevice = input.node?.android_device ?? contextEnv.ANDROID_DEVICE ?? process.env.ANDROID_DEVICE;
+  const adbSerial = input.node?.adb_serial ?? contextEnv.ADB_SERIAL ?? contextEnv.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL ?? androidDevice;
+  return { watcherPort, iosSimulator, androidDevice, adbSerial };
+}
+
+export async function bridgeCommand(input, args) {
+  const script = bridgeScript(input);
+  const result = await new Promise((resolve, reject) => {
+    const timeoutMs = Number(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? 30000);
+    const child = spawn(process.execPath, [script, ...args], {
+      cwd: input.context.projectRoot,
+      env: { ...bridgeEnv(input), APP_ROOT: input.context.projectRoot },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timer = Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        child.kill('SIGTERM');
+        setTimeout(() => {
+          if (!child.killed) child.kill('SIGKILL');
+        }, 1000);
+        resolve({ exitCode: null, stdout, stderr, timedOut: true, timeoutMs });
+      }, timeoutMs)
+      : null;
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (exitCode) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({ exitCode, stdout, stderr, timedOut: false, timeoutMs });
+    });
+  });
+  if (result.timedOut) {
+    const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
+    throw new Error(`Mobile CDP bridge command timed out after ${result.timeoutMs}ms: ${command}`);
+  }
+  if (result.exitCode !== 0) {
+    const command = ['node', path.relative(input.context.projectRoot, script), ...redactBridgeArgs(args)].join(' ');
+    throw new Error(`Mobile CDP bridge command failed: ${command}\n${redactBridgeOutput(result.stderr || result.stdout, sensitiveBridgeArgs(args))}`);
+  }
+  try {
+    const parsed = JSON.parse(result.stdout);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.ok === false) {
+      throw new Error(
+        `Mobile CDP bridge command reported failure for ${redactBridgeArgs(args).join(' ')}: ${redactBridgeOutput(JSON.stringify(parsed), sensitiveBridgeArgs(args))}`,
+      );
+    }
+    return parsed;
+  } catch (error) {
+    if (String(error?.message ?? '').startsWith('Mobile CDP bridge command reported failure')) {
+      throw error;
+    }
+    throw new Error(`Mobile CDP bridge returned non-JSON output for ${args[0]}: ${error.message}\n${result.stdout}`);
+  }
+}
+
+function redactBridgeArgs(args) {
+  const command = String(args[0] ?? '');
+  if (command === 'unlock' && args.length > 1) return [command, '<redacted-password>', ...args.slice(2)];
+  return args.map((arg) => String(arg));
+}
+
+function redactBridgeOutput(output, args) {
+  let redacted = String(output ?? '');
+  for (const arg of args) {
+    const value = String(arg ?? '');
+    if (value.length < 6) continue;
+    redacted = redacted.split(value).join('<redacted>');
+  }
+  return redacted;
+}
+
+function sensitiveBridgeArgs(args) {
+  const command = String(args[0] ?? '');
+  if (command === 'unlock' && args.length > 1) return [args[1]];
+  return [];
+}
+
+function parseMaybeJson(value) {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    // The bridge can legitimately return plain strings for eval results; keep
+    // the original value when it is not a JSON-encoded payload.
+    return value;
+  }
+}
+
+export async function evalAsync(input, expression) {
+  const deadline = Date.now() + Number(input.node?.controller_ready_timeout_ms ?? 30000);
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return parseMaybeJson(await bridgeCommand(input, ['eval-async', expression]));
+    } catch (error) {
+      lastError = error;
+      if (!String(error?.message ?? error).includes('CLIENT_NOT_INITIALIZED')) throw error;
+      await sleep(500);
+    }
+  }
+  throw lastError ?? new Error('Timed out waiting for Mobile async evaluation.');
+}
+
+export async function evalSync(input, expression) {
+  return parseMaybeJson(await bridgeCommand(input, ['eval', expression]));
+}
+
+export async function navigate(input, route, params = {}) {
+  const navigation = await bridgeCommand(input, ['navigate', route, JSON.stringify(params)]);
+  const verifiedRoute = navigation && typeof navigation === 'object' && navigation.navigated
+    ? String(navigation.navigated)
+    : String(route);
+  const currentRoute = await waitForRoute(input, verifiedRoute, Number(input.node?.navigation_timeout_ms ?? 15000));
+  return { ...navigation, currentRoute, verifiedRoute };
+}
+
+function routeName(route) {
+  return route && typeof route === 'object' ? String(route.name ?? '') : '';
+}
+
+export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
+  const expected = String(expectedRoute);
+  const deadline = Date.now() + timeoutMs;
+  let lastRoute = null;
+  while (Date.now() < deadline) {
+    lastRoute = await bridgeCommand(input, ['get-route']);
+    if (routeName(lastRoute) === expected) return lastRoute;
+    await sleep(250);
+  }
+  throw new Error(`Timed out waiting for Mobile route ${expected}; last route was ${JSON.stringify(lastRoute)}`);
+}
+
+export async function simulatorScreenshot(input, relPath) {
+  const targetInfo = resolveMobileTarget(input);
+  const androidTarget = targetInfo.androidDevice;
+  const adbSerial = targetInfo.adbSerial;
+  const platform = String(input.node?.platform ?? process.env.PLATFORM ?? '').toLowerCase();
+  if (androidTarget || adbSerial || platform === 'android') {
+    return androidScreenshot(input, relPath, adbSerial);
+  }
+  const target = targetInfo.iosSimulator;
+  if (!target) {
+    throw new Error('iOS screenshot requires node.simulator, node.ios_simulator, or IOS_SIMULATOR so the proof is tied to the same device as the bridge commands.');
+  }
+  const { relative, absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
+  await mkdir(path.dirname(absolute), { recursive: true });
+  const result = await new Promise((resolve, reject) => {
+    const child = spawn('xcrun', ['simctl', 'io', String(target), 'screenshot', absolute], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (exitCode) => resolve({ exitCode, stdout, stderr }));
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(`simctl screenshot failed for ${target}: ${result.stderr || result.stdout}`);
+  }
+  return {
+    path: relative,
+    type: 'screenshot',
+    nodeId: input.context.nodeId,
+    label: input.node?.description || `${input.action} screenshot`,
+    category: 'evidence',
+  };
+}
+
+async function androidScreenshot(input, relPath, androidDevice) {
+  const { relative, absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
+  await mkdir(path.dirname(absolute), { recursive: true });
+  const args = [];
+  if (androidDevice) args.push('-s', String(androidDevice));
+  args.push('exec-out', 'screencap', '-p');
+  const result = await new Promise((resolve, reject) => {
+    const child = spawn('adb', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdout = [];
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout.push(Buffer.from(chunk)); });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (exitCode) => resolve({ exitCode, stdout: Buffer.concat(stdout), stderr }));
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(`adb screenshot failed${androidDevice ? ` for ${androidDevice}` : ''}: ${result.stderr}`);
+  }
+  await writeFile(absolute, result.stdout);
+  return {
+    path: relative,
+    type: 'screenshot',
+    nodeId: input.context.nodeId,
+    label: input.node?.description || `${input.action} screenshot`,
+    category: 'evidence',
+  };
+}
+
+function resolveArtifactPath(artifactsDir, relativePath) {
+  const raw = String(relativePath);
+  if (path.isAbsolute(raw) || /^[A-Za-z]:/.test(raw)) {
+    throw new Error(`Artifact path must be relative: ${raw}`);
+  }
+  const normalized = path.normalize(raw);
+  if (normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
+    throw new Error(`Artifact path must not escape artifacts directory: ${raw}`);
+  }
+  return {
+    relative: normalized.split(path.sep).join('/'),
+    absolute: path.join(artifactsDir, normalized),
+  };
+}

package/library/actions/mobile/ui/navigate.mjs

@@ -0,0 +1,38 @@
+import { navigate, runAdapter } from '../platform/bridge.mjs';
+
+const PAGE_ROUTES = {
+  home: { route: 'WalletView', params: {} },
+  perps: { route: 'PerpsMarketListView', params: {} },
+};
+
+function text(value) {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function pageRoute(node) {
+  const page = text(node?.page);
+  if (!page) return undefined;
+  if (PAGE_ROUTES[page]) return { page, ...PAGE_ROUTES[page] };
+  if (page === 'perps-market') {
+    const market = text(node.market) ?? text(node.symbol) ?? text(node.params?.market?.symbol);
+    if (!market) throw new Error('mobile ui.navigate page=perps-market requires market or symbol.');
+    return { page, route: 'PerpsMarketDetails', params: { market: { symbol: market } } };
+  }
+  throw new Error('mobile ui.navigate supported page aliases: home, perps, perps-market.');
+}
+
+runAdapter(async (input) => {
+  const alias = pageRoute(input.node);
+  if (alias) {
+    const navigation = await navigate(input, alias.route, alias.params);
+    return { action: input.action, ...alias, navigation, proofPath: 'agentic-navigation' };
+  }
+
+  const route = input.node?.route ?? input.node?.screen;
+  if (typeof route !== 'string' || route.length === 0) {
+    throw new Error('mobile ui.navigate requires page or a raw React Navigation route in node.route or node.screen.');
+  }
+  const params = input.node?.params && typeof input.node.params === 'object' ? input.node.params : {};
+  const navigation = await navigate(input, route, params);
+  return { action: input.action, route, params, navigation, proofPath: 'agentic-navigation' };
+});

package/library/actions/mobile/wallet/ensure_unlocked.mjs

@@ -0,0 +1,107 @@
+import { readFile } from 'node:fs/promises';
+import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+import { walletFixturePath } from '../../../../runner/src/paths.ts';
+
+async function fixturePassword(projectRoot) {
+  const candidates = [
+    walletFixturePath(projectRoot),
+  ];
+  for (const candidate of candidates) {
+    try {
+      const fixture = JSON.parse(await readFile(candidate, 'utf8'));
+      if (fixture.password) return fixture.password;
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+      throw error;
+    }
+  }
+  throw new Error('No wallet fixture password found for Mobile unlock.');
+}
+
+function selectedAccount(status, input) {
+  return selectedStatus(status, input)?.account ?? null;
+}
+
+function routeName(status, input) {
+  const route = selectedStatus(status, input)?.route ?? null;
+  return route && typeof route === 'object' ? String(route.name ?? '') : '';
+}
+
+function selectedStatus(status, input) {
+  if (!Array.isArray(status)) {
+    return status && typeof status === 'object' ? status : null;
+  }
+  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);
+  for (const preferredDevice of preferredDevices) {
+    const match = status.find((entry) => entry?.deviceName === preferredDevice);
+    if (match) return match;
+  }
+  return (
+    status.find((entry) => entry?.account) ??
+    status.find((entry) => entry && typeof entry === 'object') ??
+    null
+  );
+}
+
+async function status(input) {
+  return bridgeCommand(input, ['status']);
+}
+
+async function waitForUnlocked(input, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  let last = null;
+  while (Date.now() < deadline) {
+    last = await status(input);
+    if (selectedAccount(last, input) && routeName(last, input) !== 'Login') return last;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`Timed out waiting for Mobile wallet unlock; last status was ${JSON.stringify(last)}`);
+}
+
+runAdapter(async (input) => {
+  const before = await status(input);
+  if (selectedAccount(before, input) && routeName(before, input) !== 'Login') {
+    return {
+      action: input.action,
+      unlocked: true,
+      alreadyUnlocked: true,
+      account: selectedAccount(before, input),
+      redacted: true,
+      proofPath: 'agentic-wallet-status',
+    };
+  }
+
+  const password = input.node?.password ?? await fixturePassword(input.context.projectRoot);
+  try {
+    const result = await bridgeCommand(input, ['unlock', String(password)]);
+    const after = await waitForUnlocked(input, Number(input.node?.unlock_timeout_ms ?? 15000));
+    return {
+      action: input.action,
+      unlocked: Boolean(result?.ok ?? result?.unlocked ?? true),
+      account: selectedAccount(after, input),
+      route: selectedStatus(after, input)?.route ?? null,
+      redacted: true,
+      proofPath: 'agentic-wallet-unlock',
+    };
+  } catch (error) {
+    if (!String(error?.message ?? error).includes('login-password-input not found')) throw error;
+    const after = await status(input);
+    if (!selectedAccount(after, input) || routeName(after, input) === 'Login') throw error;
+    return {
+      action: input.action,
+      unlocked: true,
+      alreadyUnlocked: true,
+      account: selectedAccount(after, input),
+      redacted: true,
+      proofPath: 'agentic-wallet-status-after-missing-login-input',
+    };
+  }
+});

package/library/actions/mobile/wallet/home.mjs

@@ -0,0 +1,35 @@
+import { bridgeCommand, navigate, waitForRoute } from '../platform/bridge.mjs';
+
+/**
+ * Navigate to the wallet home across MetaMask Mobile navigation generations.
+ *
+ * Current checkouts can navigate directly to `WalletView`. Some historical
+ * checkouts only register `HomeNav` at the navigator boundary and then resolve
+ * to `WalletView` after React Navigation processes the parent route. The
+ * historical path is still a real app navigation command; it is not state
+ * injection.
+ */
+export async function navigateWalletHome(input) {
+  try {
+    const direct = await navigate(input, 'WalletView', {});
+    return { navigation: direct, route: 'WalletView', proofPath: 'agentic-navigation' };
+  } catch (directError) {
+    const parent = await bridgeCommand(input, ['navigate', 'HomeNav', '{}']);
+    const currentRoute = await waitForRoute(
+      input,
+      'WalletView',
+      Number(input.node?.navigation_timeout_ms ?? 15000),
+    );
+    return {
+      navigation: {
+        ...parent,
+        currentRoute,
+        verifiedRoute: 'WalletView',
+        fallbackFrom: 'WalletView',
+        fallbackReason: directError instanceof Error ? directError.message : String(directError),
+      },
+      route: 'HomeNav',
+      proofPath: 'agentic-navigation-home-nav',
+    };
+  }
+}

package/library/actions/mobile/wallet/read_state.mjs

@@ -0,0 +1,40 @@
+import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+
+function selectedStatus(status, input) {
+  if (!Array.isArray(status)) {
+    return status && typeof status === 'object' ? status : null;
+  }
+  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);
+  for (const preferredDevice of preferredDevices) {
+    const match = status.find((entry) => entry?.deviceName === preferredDevice);
+    if (match) return match;
+  }
+  return (
+    status.find((entry) => entry?.account) ??
+    status.find((entry) => entry && typeof entry === 'object') ??
+    null
+  );
+}
+
+runAdapter(async (input) => {
+  const status = selectedStatus(await bridgeCommand(input, ['status']), input);
+  const output = {
+    action: input.action,
+    source: 'mobile-agentic-status',
+    account: status?.account ?? null,
+    route: status?.route ?? null,
+    deviceName: status?.deviceName ?? null,
+    platform: status?.platform ?? 'mobile',
+    redacted: true,
+    proofPath: 'agentic-wallet-status',
+  };
+  return output;
+});

package/library/actions/mobile/wallet/select_account.mjs

@@ -0,0 +1,48 @@
+import { bridgeCommand, evalAsync, runAdapter } from '../platform/bridge.mjs';
+
+runAdapter(async (input) => {
+  const requestedAddress = input.node?.address ? String(input.node.address).toLowerCase() : null;
+  const requestedId = input.node?.id ? String(input.node.id) : null;
+  const requestedName = input.node?.name ? String(input.node.name) : null;
+  if (!requestedAddress && !requestedId && !requestedName) {
+    throw new Error('metamask.wallet.select_account mobile live adapter requires node.address, node.id, or node.name.');
+  }
+  const accounts = await bridgeCommand(input, ['list-accounts']);
+  if (!Array.isArray(accounts)) {
+    throw new Error(`metamask.wallet.select_account expected list-accounts to return an array, got ${typeof accounts}.`);
+  }
+  const match = accounts.find((account) => {
+    const address = String(account?.address ?? '').toLowerCase();
+    const id = String(account?.id ?? '');
+    const name = String(account?.name ?? '');
+    return (requestedAddress && address === requestedAddress) ||
+      (requestedId && id === requestedId) ||
+      (requestedName && name === requestedName);
+  });
+  if (!match?.address) {
+    throw new Error(`Requested mobile account was not found in list-accounts: ${JSON.stringify({ address: requestedAddress, id: requestedId, name: requestedName })}`);
+  }
+  const result = await bridgeCommand(input, ['switch-account', String(match.address)]);
+  const perps = await evalAsync(
+    input,
+    `(async function(){
+      var controller = Engine.context.PerpsController;
+      if (!controller) return JSON.stringify({ skipped: true, reason: 'PerpsController unavailable' });
+      if (typeof controller.disconnect === 'function') await controller.disconnect();
+      if (typeof controller.init === 'function') await controller.init();
+      var positions = typeof controller.getPositions === 'function' ? await controller.getPositions() : [];
+      var account = typeof controller.getAccountState === 'function' ? await controller.getAccountState() : null;
+      return JSON.stringify({ reinitialized: true, positions: positions.length, withdrawableBalance: account && account.withdrawableBalance });
+    })()`,
+  );
+  return {
+    action: input.action,
+    selected: {
+      address: result.address,
+      id: result.id,
+      name: result.name,
+    },
+    perps,
+    proofPath: 'agentic-account-selection',
+  };
+});