@deeeed/metamask-harness 0.26.4 → 0.27.0

package/library/actions/mobile/platform/observe-ui.mjs

@@ -0,0 +1,416 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { mobileToolRecovery, resolveMobileToolPath } from './tool-paths.mjs';
+
+const execFileAsync = promisify(execFile);
+const VISIBLE_LIMIT = 50;
+const HIDDEN_LIMIT = 50;
+
+export async function observeNativeUi(payload, context) {
+  const refs = Array.isArray(payload?.refs)
+    ? payload.refs.filter((ref) => typeof ref === 'string')
+    : [];
+  const supported = refs.filter((ref) => ref === 'ui.screen' || ref === 'ui.visible');
+  const warnings = refs
+    .filter((ref) => !supported.includes(ref))
+    .map((ref) => ({ ref, message: `Unsupported UI observer: ${ref}.` }));
+  if (supported.length === 0) return warnings.length ? { warnings } : {};
+
+  try {
+    const hierarchy = await readNativeHierarchy(payload, context);
+    const observations = {};
+    for (const ref of supported) {
+      observations[ref] = ref === 'ui.screen' ? hierarchy.screen : hierarchy.visible;
+    }
+    return {
+      observations,
+      ...(warnings.length ? { warnings } : {}),
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      warnings: [
+        ...warnings,
+        ...supported.map((ref) => ({ ref, message })),
+      ],
+    };
+  }
+}
+
+async function readNativeHierarchy(payload, context) {
+  const node = record(payload?.node);
+  const env = {
+    ...process.env,
+    ...record(context?.env),
+  };
+  const platform = resolvePlatform(node, env);
+  if (platform === 'android') return readAndroidHierarchy(node, env);
+  return readIosHierarchy(node, env);
+}
+
+async function readIosHierarchy(node, env) {
+  const idbPath = resolveMobileToolPath('idb');
+  if (!idbPath) {
+    throw new Error(
+      `iOS UI observation requires the idb client.\n  Next: ${mobileToolRecovery('idb')}`,
+    );
+  }
+  const udid = await resolveIosUdid(node, env);
+  const { stdout } = await execFileAsync(
+    idbPath,
+    ['ui', 'describe-all', '--udid', udid],
+    {
+      encoding: 'utf8',
+      timeout: 15_000,
+      maxBuffer: 16 * 1024 * 1024,
+      env,
+    },
+  );
+  const parsed = parseJsonOutput(stdout);
+  const hierarchy = flattenIosHierarchy(parsed);
+  if (hierarchy.nodeCount === 0) {
+    throw new Error('idb returned an empty accessibility hierarchy.');
+  }
+  return normalizedHierarchy(
+    'idb-accessibility',
+    'ios',
+    udid,
+    hierarchy.visible,
+    hierarchy.hidden,
+    hierarchy,
+  );
+}
+
+async function readAndroidHierarchy(node, env) {
+  const adbPath = resolveMobileToolPath('adb');
+  if (!adbPath) {
+    throw new Error(
+      `Android UI observation requires Android SDK Platform-Tools.\n  Next: ${mobileToolRecovery('adb')}`,
+    );
+  }
+  const serial = await resolveAndroidSerial(adbPath, node, env);
+  const { stdout } = await execFileAsync(
+    adbPath,
+    ['-s', serial, 'exec-out', 'uiautomator', 'dump', '/dev/tty'],
+    {
+      encoding: 'utf8',
+      timeout: 15_000,
+      maxBuffer: 16 * 1024 * 1024,
+      env,
+    },
+  );
+  const hierarchy = parseAndroidHierarchy(stdout);
+  if (hierarchy.nodeCount === 0) {
+    throw new Error('adb returned an empty UIAutomator hierarchy.');
+  }
+  return normalizedHierarchy(
+    'adb-uiautomator',
+    'android',
+    serial,
+    hierarchy.visible,
+    hierarchy.hidden,
+    hierarchy,
+  );
+}
+
+function normalizedHierarchy(
+  provider,
+  platform,
+  deviceId,
+  nodes,
+  hiddenNodes = [],
+  metadata = {},
+) {
+  const items = nodes.slice(0, VISIBLE_LIMIT);
+  const hiddenOrOffscreen = hiddenNodes.slice(0, HIDDEN_LIMIT);
+  const name = metadata.screenName ??
+    items.find((item) => item.label)?.label ??
+    'MetaMask';
+  return {
+    screen: {
+      provider,
+      platform,
+      deviceId,
+      name,
+      nodeCount: metadata.nodeCount ?? nodes.length + hiddenNodes.length,
+      truncated: nodes.length > VISIBLE_LIMIT || hiddenNodes.length > HIDDEN_LIMIT,
+    },
+    visible: {
+      provider,
+      items,
+      hidden_or_offscreen: hiddenOrOffscreen,
+      truncated: nodes.length > VISIBLE_LIMIT || hiddenNodes.length > HIDDEN_LIMIT,
+      limits: { items: VISIBLE_LIMIT, hidden_or_offscreen: HIDDEN_LIMIT },
+    },
+  };
+}
+
+async function resolveIosUdid(node, env) {
+  const requested = text(node.simulator) ?? text(node.ios_simulator) ??
+    text(env.SIM_UDID) ?? text(env.IOS_SIMULATOR) ?? 'booted';
+  if (/^[0-9a-f-]{36}$/iu.test(requested)) return requested;
+  const { stdout } = await execFileAsync(
+    'xcrun',
+    ['simctl', 'list', 'devices', 'booted', '-j'],
+    {
+      encoding: 'utf8',
+      timeout: 5_000,
+      maxBuffer: 4 * 1024 * 1024,
+      env,
+    },
+  );
+  const parsed = JSON.parse(stdout);
+  const devices = Object.values(record(parsed.devices)).flatMap((value) =>
+    Array.isArray(value) ? value : []);
+  const matched = devices.find((device) => {
+    const candidate = record(device);
+    return candidate.state === 'Booted' && (
+      requested === 'booted' ||
+      candidate.udid === requested ||
+      candidate.name === requested
+    );
+  });
+  const udid = text(record(matched).udid);
+  if (!udid) throw new Error(`No booted iOS simulator matched ${requested}.`);
+  return udid;
+}
+
+async function resolveAndroidSerial(adbPath, node, env) {
+  const explicit = text(node.adb_serial) ?? text(node.android_serial) ??
+    text(env.ADB_SERIAL) ?? text(env.ANDROID_SERIAL);
+  if (explicit) return explicit;
+  const { stdout } = await execFileAsync(adbPath, ['devices'], {
+    encoding: 'utf8',
+    timeout: 5_000,
+    maxBuffer: 4 * 1024 * 1024,
+    env,
+  });
+  const serials = stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim().split(/\s+/u))
+    .filter((fields) => fields.length >= 2 && fields[1] === 'device')
+    .map(([serial]) => serial);
+  if (serials.length !== 1) {
+    throw new Error(`Android UI observation requires one ready device; found ${serials.length}.`);
+  }
+  return serials[0];
+}
+
+function resolvePlatform(node, env) {
+  const explicit = text(node.platform) ?? text(env.MOBILE_PLATFORM) ?? text(env.PLATFORM);
+  if (explicit === 'android' || explicit === 'ios') return explicit;
+  if (text(node.adb_serial) || text(env.ADB_SERIAL) || text(env.ANDROID_SERIAL)) {
+    return 'android';
+  }
+  return 'ios';
+}
+
+function parseJsonOutput(output) {
+  try {
+    return JSON.parse(output);
+  } catch {
+    const values = output
+      .split(/\r?\n/u)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line)];
+        } catch {
+          return [];
+        }
+      });
+    if (values.length === 0) throw new Error('idb returned malformed accessibility JSON.');
+    return values.length === 1 ? values[0] : values;
+  }
+}
+
+function flattenIosHierarchy(value) {
+  const visible = [];
+  const hidden = [];
+  let nodeCount = 0;
+  let screenName;
+  let screenBounds;
+  const visit = (current) => {
+    if (Array.isArray(current)) {
+      for (const child of current) visit(child);
+      return;
+    }
+    const item = record(current);
+    if (Object.keys(item).length === 0) return;
+    nodeCount += 1;
+    const role = text(item.role) ?? text(item.type) ?? text(item.AXRole) ??
+      text(item.role_description) ?? text(item.className);
+    const label = text(item.label) ?? text(item.AXLabel) ?? text(item.name) ??
+      text(item.title);
+    const testId = text(item.identifier) ?? text(item.accessibilityIdentifier) ??
+      text(item.AXUniqueId) ?? text(item.id);
+    const bounds = normalizeBounds(item.frame ?? item.AXFrame ?? item.bounds);
+    if (isApplicationRole(role)) {
+      screenName ??= label;
+      screenBounds ??= bounds;
+    }
+    if (isActionableRole(role)) {
+      const normalized = compactItem({
+        role,
+        label,
+        test_id: testId,
+        enabled: boolean(item.enabled ?? item.AXEnabled),
+        selected: boolean(item.selected ?? item.AXSelected),
+        focused: boolean(item.focused ?? item.AXFocused),
+        bounds,
+      });
+      if (hasVisibleBounds(bounds, screenBounds)) {
+        visible.push(normalized);
+      } else {
+        hidden.push({ ...normalized, reason: 'hidden_or_offscreen' });
+      }
+    }
+    for (const key of ['children', 'AXChildren', 'elements', 'subviews']) {
+      if (item[key] !== undefined) visit(item[key]);
+    }
+  };
+  visit(value);
+  return { visible, hidden, nodeCount, screenName };
+}
+
+function parseAndroidHierarchy(output) {
+  const xmlStart = Math.max(output.indexOf('<?xml'), output.indexOf('<hierarchy'));
+  const xml = xmlStart >= 0 ? output.slice(xmlStart) : output;
+  const visible = [];
+  const hidden = [];
+  const ancestorVisibility = [];
+  let nodeCount = 0;
+  let screenName;
+  for (const match of xml.matchAll(/<\/?node\b[^>]*>/gu)) {
+    const tag = match[0];
+    if (tag.startsWith('</')) {
+      ancestorVisibility.pop();
+      continue;
+    }
+    const attributes = {};
+    for (const attribute of tag.matchAll(/([:\w-]+)="([^"]*)"/gu)) {
+      attributes[attribute[1]] = decodeXml(attribute[2]);
+    }
+    nodeCount += 1;
+    const className = text(attributes.class);
+    const role = className?.split('.').pop()?.toLowerCase();
+    const isEditable = role?.includes('edittext') || attributes.password === 'true';
+    const label = text(attributes['content-desc']) ??
+      (isEditable ? undefined : text(attributes.text));
+    if (!screenName && label && !isEditable) screenName = label;
+    const item = compactItem({
+      role,
+      label,
+      test_id: text(attributes['resource-id']),
+      enabled: boolean(attributes.enabled),
+      selected: boolean(attributes.selected),
+      focused: boolean(attributes.focused),
+      bounds: normalizeBounds(attributes.bounds),
+    });
+    const isVisible =
+      ancestorVisibility.every(Boolean) &&
+      attributes['visible-to-user'] !== 'false';
+    const isActionable =
+      isActionableRole(role) ||
+      attributes.clickable === 'true' ||
+      attributes['long-clickable'] === 'true';
+    if (isActionable) {
+      if (isVisible) {
+        visible.push(item);
+      } else {
+        hidden.push({ ...item, reason: 'hidden' });
+      }
+    }
+    if (!tag.endsWith('/>')) ancestorVisibility.push(isVisible);
+  }
+  return { visible, hidden, nodeCount, screenName };
+}
+
+function isApplicationRole(role) {
+  return role?.toLowerCase().includes('application') ?? false;
+}
+
+function isActionableRole(role) {
+  const normalized = role?.toLowerCase() ?? '';
+  return ['button', 'cell', 'link', 'switch', 'textfield', 'text-field', 'edittext']
+    .some((candidate) => normalized.includes(candidate));
+}
+
+function hasVisibleBounds(bounds, viewport) {
+  if (bounds === undefined || bounds.width <= 0 || bounds.height <= 0) return false;
+  if (viewport === undefined) return true;
+  return (
+    bounds.x < viewport.x + viewport.width &&
+    bounds.x + bounds.width > viewport.x &&
+    bounds.y < viewport.y + viewport.height &&
+    bounds.y + bounds.height > viewport.y
+  );
+}
+
+function normalizeBounds(value) {
+  if (typeof value === 'string') {
+    const numbers = value.match(/-?\d+(?:\.\d+)?/gu)?.map(Number) ?? [];
+    if (numbers.length >= 4) {
+      const [x, y, third, fourth] = numbers;
+      const endpointShape = value.includes('][');
+      return {
+        x: Math.round(x),
+        y: Math.round(y),
+        width: Math.round(endpointShape ? third - x : third),
+        height: Math.round(endpointShape ? fourth - y : fourth),
+      };
+    }
+    return undefined;
+  }
+  const bounds = record(value);
+  const origin = record(bounds.origin);
+  const size = record(bounds.size);
+  const x = number(bounds.x ?? origin.x);
+  const y = number(bounds.y ?? origin.y);
+  const width = number(bounds.width ?? size.width);
+  const height = number(bounds.height ?? size.height);
+  if ([x, y, width, height].some((part) => part === undefined)) return undefined;
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    width: Math.round(width),
+    height: Math.round(height),
+  };
+}
+
+function compactItem(item) {
+  return Object.fromEntries(
+    Object.entries(item).filter(([, value]) => value !== undefined && value !== ''),
+  );
+}
+
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function text(value) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/\s+/gu, ' ').trim();
+  return normalized || undefined;
+}
+
+function number(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function boolean(value) {
+  if (value === true || value === 'true' || value === 1 || value === '1') return true;
+  if (value === false || value === 'false' || value === 0 || value === '0') return false;
+  return undefined;
+}
+
+function decodeXml(value) {
+  return value
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+}

package/library/actions/mobile/platform/tool-paths.mjs

@@ -0,0 +1,122 @@
+import { constants as fsConstants, accessSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const TOOL_ENV = {
+  adb: 'MM_HARNESS_ADB_PATH',
+  idb: 'MM_HARNESS_IDB_PATH',
+};
+
+const TOOL_RECOVERY = {
+  adb: 'brew install android-platform-tools',
+  idb: 'brew install idb-companion pipx python@3.13 && pipx install fb-idb --python python3.13',
+};
+
+const resolvedPaths = new Map();
+
+export function mobileToolRecovery(tool) {
+  assertTool(tool);
+  return TOOL_RECOVERY[tool];
+}
+
+export function mobileToolEnvName(tool) {
+  assertTool(tool);
+  return TOOL_ENV[tool];
+}
+
+export function resolveMobileToolPath(tool, { required = false } = {}) {
+  assertTool(tool);
+  const cached = resolvedPaths.get(tool);
+  if (cached && executablePath(cached)) return cached;
+
+  for (const candidate of candidatesFor(tool)) {
+    const resolved = executablePath(candidate);
+    if (!resolved) continue;
+    resolvedPaths.set(tool, resolved);
+    process.env[TOOL_ENV[tool]] = resolved;
+    return resolved;
+  }
+
+  resolvedPaths.delete(tool);
+  if (!required) return null;
+  const label = tool === 'adb' ? 'Android SDK Platform-Tools (adb)' : 'Facebook idb client';
+  throw new Error(
+    `${label} is required but no executable was found.\n` +
+      `  Next: ${TOOL_RECOVERY[tool]}`,
+  );
+}
+
+export function resolveAndExportMobileToolPaths(platform) {
+  if (platform === 'android') {
+    return { adb: resolveMobileToolPath('adb', { required: true }), idb: null };
+  }
+  if (platform === 'ios') {
+    return { adb: null, idb: resolveMobileToolPath('idb') };
+  }
+  return {
+    adb: resolveMobileToolPath('adb'),
+    idb: resolveMobileToolPath('idb'),
+  };
+}
+
+export function clearMobileToolPathCache() {
+  resolvedPaths.clear();
+}
+
+function candidatesFor(tool) {
+  const override = process.env[TOOL_ENV[tool]];
+  const pathCandidates = String(process.env.PATH ?? '')
+    .split(path.delimiter)
+    .filter(Boolean)
+    .map((directory) => path.join(directory, tool));
+  const candidates = override ? [override] : [];
+  candidates.push(...pathCandidates);
+  if (tool === 'adb') {
+    for (const root of [
+      process.env.ANDROID_HOME,
+      process.env.ANDROID_SDK_ROOT,
+      path.join(os.homedir(), 'Library/Android/sdk'),
+      path.join(os.homedir(), 'Android/Sdk'),
+    ]) {
+      if (root) candidates.push(path.join(root, 'platform-tools', 'adb'));
+    }
+  } else {
+    if (process.env.IDB_PATH) candidates.push(process.env.IDB_PATH);
+    candidates.push(
+      '/opt/homebrew/bin/idb',
+      '/usr/local/bin/idb',
+      path.join(os.homedir(), '.local/bin/idb'),
+    );
+    candidates.push(...pythonUserCandidates());
+  }
+  return [...new Set(candidates.map((candidate) => path.resolve(candidate)))];
+}
+
+function pythonUserCandidates() {
+  const root = path.join(os.homedir(), 'Library/Python');
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(root, entry.name, 'bin/idb'));
+  } catch {
+    return [];
+  }
+}
+
+function executablePath(candidate) {
+  try {
+    const resolved = realpathSync(candidate);
+    const stat = statSync(resolved);
+    if (!stat.isFile()) return null;
+    accessSync(resolved, fsConstants.X_OK);
+    return path.resolve(resolved);
+  } catch {
+    return null;
+  }
+}
+
+function assertTool(tool) {
+  if (tool !== 'adb' && tool !== 'idb') {
+    throw new Error(`Unsupported mobile device tool: ${String(tool)}.`);
+  }
+}

package/library/actions/shared/analytics/collector.mjs

@@ -226,7 +226,7 @@ function pidAlive(pid) {
   }
 }
 
-async function collectorHealth(port) {
+async function collectorIdentity(port) {
   try {
     const response = await fetch(`http://127.0.0.1:${port}/__collector`, {
       signal: AbortSignal.timeout(1000),
@@ -241,11 +241,24 @@ async function collectorHealth(port) {
   }
 }
 
+async function collectorHealth(port) {
+  const identity = await collectorIdentity(port);
+  const hosts = identity?.loopbackHosts;
+  if (
+    !Array.isArray(hosts) ||
+    !hosts.includes('127.0.0.1') ||
+    (!hosts.includes('::1') && identity?.ipv6Unavailable !== true)
+  ) {
+    return null;
+  }
+  return identity;
+}
+
 async function stopCollector(state) {
   if (
     !state?.instanceId ||
     !pidAlive(state.pid) ||
-    (await collectorHealth(state.port))?.instanceId !== state.instanceId
+    (await collectorIdentity(state.port))?.instanceId !== state.instanceId
   ) {
     return false;
   }
@@ -346,6 +359,9 @@ export async function startCollector(input) {
   const { eventsFile, stateFile } = await prepareCollectorStorage(projectRoot);
 
   const existing = await readState(stateFile);
+  const existingIdentity = existing?.port
+    ? await collectorIdentity(existing.port)
+    : null;
   const existingHealth = existing?.port ? await collectorHealth(existing.port) : null;
   if (
     existing?.port === port &&
@@ -356,6 +372,14 @@ export async function startCollector(input) {
     const androidDevice = await prepareAndroidAccess(input, port);
     return { port, pid: existing.pid, eventsFile, reused: true, androidDevice };
   }
+  if (
+    existing?.port === port &&
+    existing?.instanceId &&
+    pidAlive(existing.pid) &&
+    existingIdentity?.instanceId === existing.instanceId
+  ) {
+    await stopCollector(existing);
+  }
   if (existing?.port && existing.port !== port) {
     const stopped = await stopCollector(existing);
     if (!stopped && pidAlive(existing.pid)) {
@@ -365,7 +389,7 @@ export async function startCollector(input) {
     }
   }
 
-  const occupied = await collectorHealth(port);
+  const occupied = await collectorIdentity(port);
   if (occupied) {
     throw new Error(
       `Analytics collector port ${port} is owned by another instance. Choose another port or stop that collector.`,
@@ -461,7 +485,9 @@ function eventsFromBody(body) {
 }
 
 function serve(port, eventsFile, instanceId) {
-  const server = createServer((request, response) => {
+  let ipv4Ready = false;
+  let ipv6Status = 'pending';
+  const handleRequest = (request, response) => {
     // The extension's Segment client runs in a page context, so preflight has
     // to pass or nothing is ever delivered.
     const cors = {
@@ -480,6 +506,11 @@ function serve(port, eventsFile, instanceId) {
         collector: 'metamask-harness',
         port,
         instanceId,
+        loopbackHosts: [
+          ...(ipv4Ready ? ['127.0.0.1'] : []),
+          ...(ipv6Status === 'ready' ? ['::1'] : []),
+        ],
+        ...(ipv6Status === 'unavailable' ? { ipv6Unavailable: true } : {}),
       }));
       return;
     }
@@ -504,8 +535,22 @@ function serve(port, eventsFile, instanceId) {
         response.end('{"error":"collector_write_failed"}');
       }
     });
+  };
+  const ipv4Server = createServer(handleRequest);
+  const ipv6Server = createServer(handleRequest);
+  ipv6Server.on('error', (error) => {
+    if (error?.code === 'EAFNOSUPPORT' || error?.code === 'EADDRNOTAVAIL') {
+      ipv6Status = 'unavailable';
+      return;
+    }
+    throw error;
+  });
+  ipv4Server.listen(port, '127.0.0.1', () => {
+    ipv4Ready = true;
+  });
+  ipv6Server.listen(port, '::1', () => {
+    ipv6Status = 'ready';
   });
-  server.listen(port, '127.0.0.1');
 }
 
 function collectorServerSource() {

package/library/manifests/mobile.action-manifest.json

@@ -3044,5 +3044,29 @@
         "additionalProperties": false
       }
     }
-  }
+  },
+  "observers": [
+    {
+      "ref": "ui.screen",
+      "default_for": [
+        "ui.navigate",
+        "ui.press",
+        "ui.screenshot",
+        "ui.scroll",
+        "ui.set_input",
+        "ui.wait_for"
+      ]
+    },
+    {
+      "ref": "ui.visible",
+      "default_for": [
+        "ui.navigate",
+        "ui.press",
+        "ui.screenshot",
+        "ui.scroll",
+        "ui.set_input",
+        "ui.wait_for"
+      ]
+    }
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.26.4",
+  "version": "0.27.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"