@deeeed/metamask-harness 0.26.5 → 0.28.0

package/library/actions/extension/platform/cdp.mjs

@@ -84,76 +84,107 @@ function resolveRelativeArtifactPath(artifactsDir, relPath) {
   if (absolute !== artifactsRoot && !absolute.startsWith(`${artifactsRoot}${path.sep}`)) {
     throw new Error(`Refusing Extension screenshot artifact path outside artifacts dir: ${relative}`);
   }
-  return { relative: normalized, absolute };
+  return { relative: normalized, absolute, artifactsRoot };
 }
 
-async function preparePrivateArtifactStage(artifactsDir, relPath) {
-  const destination = resolveRelativeArtifactPath(artifactsDir, relPath);
-  const artifactsRoot = path.resolve(artifactsDir);
-  await mkdir(artifactsRoot, { recursive: true });
-  await ensureArtifactParent(artifactsRoot, path.dirname(destination.absolute));
-  await refuseUnsafeDestination(destination.absolute);
-  const stagingDir = await mkdtemp(path.join(artifactsRoot, '.extension-evidence-'));
+async function preparePrivateEvidenceDestination(absolute, artifactsRoot) {
+  const outputDir = path.dirname(absolute);
+  await ensureEvidenceDirectory(artifactsRoot, outputDir);
+  await refuseEvidenceDestinationSymlink(absolute);
+  const stagingDir = await mkdtemp(path.join(outputDir, '.mm-harness-extension-evidence-'));
   await chmod(stagingDir, 0o700);
   return {
-    ...destination,
+    absolute,
     stagingDir,
-    staged: path.join(stagingDir, 'artifact'),
+    stagedPath: path.join(stagingDir, 'captured.png'),
   };
 }
 
-async function ensureArtifactParent(artifactsRoot, parent) {
-  const relative = path.relative(artifactsRoot, parent);
+async function ensureEvidenceDirectory(artifactsRoot, outputDir) {
+  await mkdir(artifactsRoot, { recursive: true });
+  await requireEvidenceDirectory(artifactsRoot);
+  const relative = path.relative(artifactsRoot, outputDir);
   let current = artifactsRoot;
   for (const segment of relative.split(path.sep).filter(Boolean)) {
     current = path.join(current, segment);
     try {
-      const info = await lstat(current);
-      if (info.isSymbolicLink() || !info.isDirectory()) {
-        throw new Error(`Refusing Extension evidence parent that is not a real directory: ${current}`);
-      }
+      await mkdir(current);
     } catch (error) {
-      if (error?.code !== 'ENOENT') throw error;
-      await mkdir(current, { mode: 0o700 });
+      if (error?.code !== 'EEXIST') throw error;
     }
+    await requireEvidenceDirectory(current);
   }
 }
 
-async function refuseUnsafeDestination(destination) {
+async function requireEvidenceDirectory(directory) {
+  const entry = await lstat(directory);
+  if (entry.isDirectory() && !entry.isSymbolicLink()) return;
+  throw new Error(
+    `Refusing unsafe Extension evidence directory: ${directory}\n` +
+      `Next: replace ${JSON.stringify(directory)} with a regular directory and retry the recipe.`,
+  );
+}
+
+async function publishPrivateEvidence(destination) {
+  let handle;
   try {
-    const info = await lstat(destination);
-    if (info.isSymbolicLink()) {
-      throw new Error(`Refusing Extension evidence destination symlink: ${destination}`);
-    }
-    if (!info.isFile()) {
-      throw new Error(`Refusing Extension evidence destination that is not a regular file: ${destination}`);
+    try {
+      handle = await open(
+        destination.stagedPath,
+        constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
+      );
+      const stagedStat = await handle.stat();
+      if (!stagedStat.isFile()) {
+        throw unsafeEvidenceArtifactError(destination.stagedPath);
+      }
+      await handle.chmod(0o600);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('Next:')) throw error;
+      throw unsafeEvidenceArtifactError(
+        destination.stagedPath,
+        error instanceof Error ? error.message : String(error),
+      );
+    } finally {
+      await handle?.close();
     }
-  } catch (error) {
-    if (error?.code !== 'ENOENT') throw error;
+    await refuseEvidenceDestinationSymlink(destination.absolute);
+    await rename(destination.stagedPath, destination.absolute);
+  } finally {
+    await cleanupEvidenceStaging(destination.stagingDir);
   }
 }
 
-async function publishPrivateArtifact(stage) {
-  const handle = await open(
-    stage.staged,
-    constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
-  );
+async function refuseEvidenceDestinationSymlink(absolute) {
+  let destination;
   try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      throw new Error(`Captured Extension evidence is not a safe regular file: ${stage.staged}`);
-    }
-    await handle.chmod(0o600);
-    await refuseUnsafeDestination(stage.absolute);
-    await rename(stage.staged, stage.absolute);
-  } finally {
-    await handle.close();
+    destination = await lstat(absolute);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return;
+    throw error;
+  }
+  if (destination.isSymbolicLink()) {
+    throw new Error(
+      `Refusing Extension evidence destination symlink: ${absolute}\n` +
+        `Next: rm -- ${JSON.stringify(absolute)} and retry the recipe.`,
+    );
   }
-  await rm(stage.stagingDir, { recursive: true, force: true });
+  if (!destination.isFile()) {
+    throw new Error(
+      `Refusing non-file Extension evidence destination: ${absolute}\n` +
+        `Next: remove ${JSON.stringify(absolute)} and retry the recipe.`,
+    );
+  }
+}
+
+function unsafeEvidenceArtifactError(stagedPath, detail) {
+  return new Error(
+    `Captured Extension evidence is not a safe regular file: ${stagedPath}${detail ? ` (${detail})` : ''}.\n` +
+      'Next: mm-harness doctor --adapter extension --json',
+  );
 }
 
-async function cleanupPrivateArtifactStage(stage) {
-  await rm(stage.stagingDir, { recursive: true, force: true });
+async function cleanupEvidenceStaging(stagingDir) {
+  await rm(stagingDir, { recursive: true, force: true });
 }
 
 function captureHelperPath() {
@@ -203,10 +234,12 @@ async function captureHelperBrowserPid(context, port) {
 }
 
 async function captureCdpViewportSnapshot(page, context, relPath, metadata, captureHelperError = null) {
-  const stage = await preparePrivateArtifactStage(context.artifactsDir, relPath);
+  const { relative, absolute, artifactsRoot } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
+  const destination = await preparePrivateEvidenceDestination(absolute, artifactsRoot);
+  let result;
   try {
     const timeoutMs = Number(metadata?.cdpTimeoutMs ?? 5000);
-    const result = await Promise.race([
+    result = await Promise.race([
       page.session.call('Page.captureScreenshot', {
         format: 'png',
         fromSurface: true,
@@ -217,33 +250,41 @@ async function captureCdpViewportSnapshot(page, context, relPath, metadata, capt
     if (typeof result?.data !== 'string' || result.data.length === 0) {
       throw new Error('Chrome Page.captureScreenshot returned no image data.');
     }
-    await writeFile(stage.staged, Buffer.from(result.data, 'base64'), {
-      flag: 'wx',
-      mode: 0o600,
-    });
-    await publishPrivateArtifact(stage);
-    return {
-      path: stage.relative,
-      type: 'screenshot',
-      nodeId: context.nodeId,
-      label: metadata?.label ?? `${context.nodeId} screenshot`,
-      category: metadata?.category ?? 'evidence',
-      mimeType: 'image/png',
-      metadata: {
-        provider: 'cdp',
-        mode: 'Page.captureScreenshot',
-        ...(captureHelperError ? { fallbackFrom: 'capture-helper', captureHelperError } : {}),
-      },
-    };
   } catch (error) {
-    await cleanupPrivateArtifactStage(stage);
+    await cleanupEvidenceStaging(destination.stagingDir);
     const cdpError = error instanceof Error ? error.message : String(error);
     return captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError);
   }
+  try {
+    await writeFile(
+      destination.stagedPath,
+      Buffer.from(result.data, 'base64'),
+      { flag: 'wx', mode: 0o600 },
+    );
+  } catch (error) {
+    await cleanupEvidenceStaging(destination.stagingDir);
+    throw error;
+  }
+  await publishPrivateEvidence(destination);
+  return {
+    path: relative,
+    type: 'screenshot',
+    nodeId: context.nodeId,
+    label: metadata?.label ?? `${context.nodeId} screenshot`,
+    category: metadata?.category ?? 'evidence',
+    mimeType: 'image/png',
+    metadata: {
+      provider: 'cdp',
+      mode: 'Page.captureScreenshot',
+      ...(captureHelperError ? { fallbackFrom: 'capture-helper', captureHelperError } : {}),
+    },
+  };
 }
 
 async function captureDomRasterSnapshot(page, context, relPath, metadata, captureHelperError, cdpError) {
-  const dataUrl = await page.evaluate(`(async () => {
+  const { relative, absolute, artifactsRoot } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
+  const destination = await preparePrivateEvidenceDestination(absolute, artifactsRoot);
+  const dataUrlPromise = page.evaluate(`(async () => {
     const width = Math.max(1, window.innerWidth);
     const height = Math.max(1, window.innerHeight);
     const source = document.documentElement;
@@ -282,23 +323,24 @@ async function captureDomRasterSnapshot(page, context, relPath, metadata, captur
     context.drawImage(image, 0, 0, width, height);
     return canvas.toDataURL('image/png');
   })()`);
-  if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) {
-    throw new Error(`Extension screenshot fallbacks failed: capture-helper=${captureHelperError ?? 'not attempted'}; cdp=${cdpError}; DOM raster returned no PNG.`);
-  }
-  const stage = await preparePrivateArtifactStage(context.artifactsDir, relPath);
+  let dataUrl;
   try {
+    dataUrl = await dataUrlPromise;
+    if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) {
+      throw new Error(`Extension screenshot fallbacks failed: capture-helper=${captureHelperError ?? 'not attempted'}; cdp=${cdpError}; DOM raster returned no PNG.`);
+    }
     await writeFile(
-      stage.staged,
+      destination.stagedPath,
       Buffer.from(dataUrl.slice('data:image/png;base64,'.length), 'base64'),
       { flag: 'wx', mode: 0o600 },
     );
-    await publishPrivateArtifact(stage);
   } catch (error) {
-    await cleanupPrivateArtifactStage(stage);
+    await cleanupEvidenceStaging(destination.stagingDir);
     throw error;
   }
+  await publishPrivateEvidence(destination);
   return {
-    path: stage.relative,
+    path: relative,
     type: 'screenshot',
     nodeId: context.nodeId,
     label: metadata?.label ?? `${context.nodeId} screenshot`,
@@ -318,59 +360,70 @@ export async function captureHelperSnapshot(page, context, relPath, metadata) {
   if (process.platform !== 'darwin') {
     return captureCdpViewportSnapshot(page, context, relPath, metadata);
   }
-  const stage = await preparePrivateArtifactStage(context.artifactsDir, relPath);
+  const { relative, absolute, artifactsRoot } = resolveRelativeArtifactPath(context.artifactsDir, relPath);
+  const destination = await preparePrivateEvidenceDestination(absolute, artifactsRoot);
 
+  let pid;
+  let mode;
+  let details;
   try {
-    const pid = await captureHelperBrowserPid(context, page.port);
+    pid = await captureHelperBrowserPid(context, page.port);
     const timeoutMs = Number(metadata?.timeoutMs ?? 30000);
-    const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(pid, stage.staged, timeoutMs);
+    const sessionSnapshot = await captureActiveRecipeRecordingSnapshot(
+      pid,
+      destination.stagedPath,
+      timeoutMs,
+    );
     if (sessionSnapshot) {
-      await publishPrivateArtifact(stage);
-      return {
-        path: stage.relative,
-        type: 'screenshot',
-        nodeId: context.nodeId,
-        label: metadata?.label ?? `${context.nodeId} screenshot`,
-        category: metadata?.category ?? 'evidence',
-        mimeType: 'image/png',
-        metadata: {
-          provider: 'capture-helper',
-          mode: 'record_session_snapshot',
-          pid,
-          captureHelper: sessionSnapshot,
+      mode = 'record_session_snapshot';
+      details = sessionSnapshot;
+    } else if (
+      parsePositivePid(process.env.METAMASK_RECIPE_EXTENSION_ACTIVE_RECORDING_PID) === pid
+    ) {
+      await cleanupEvidenceStaging(destination.stagingDir);
+      return captureCdpViewportSnapshot(
+        page,
+        context,
+        relPath,
+        metadata,
+        'native snapshot skipped while full-run recording owns the browser window',
+      );
+    } else {
+      const result = await runProcess(
+        captureHelperPath(),
+        ['snapshot', '--pid', String(pid), '--output', destination.stagedPath],
+        {
+          cwd: context.projectRoot,
+          env: process.env,
+          timeoutMs,
         },
-      };
-    }
-
-    const result = await runProcess(captureHelperPath(), ['snapshot', '--pid', String(pid), '--output', stage.staged], {
-      cwd: context.projectRoot,
-      env: process.env,
-      timeoutMs,
-    });
-    if (result.exitCode !== 0) {
-      throw new Error(`capture-helper snapshot failed for pid ${pid}: ${result.stderr || result.stdout}`);
+      );
+      if (result.exitCode !== 0) {
+        throw new Error(`capture-helper snapshot failed for pid ${pid}: ${result.stderr || result.stdout}`);
+      }
+      mode = 'snapshot';
+      details = parseJsonObject(result.stdout);
     }
-    const details = parseJsonObject(result.stdout);
-    await publishPrivateArtifact(stage);
-    return {
-      path: stage.relative,
-      type: 'screenshot',
-      nodeId: context.nodeId,
-      label: metadata?.label ?? `${context.nodeId} screenshot`,
-      category: metadata?.category ?? 'evidence',
-      mimeType: 'image/png',
-      metadata: {
-        provider: 'capture-helper',
-        mode: 'snapshot',
-        pid,
-        ...(details ? { captureHelper: details } : {}),
-      },
-    };
   } catch (error) {
-    await cleanupPrivateArtifactStage(stage);
+    await cleanupEvidenceStaging(destination.stagingDir);
     const message = error instanceof Error ? error.message : String(error);
     return captureCdpViewportSnapshot(page, context, relPath, metadata, message);
   }
+  await publishPrivateEvidence(destination);
+  return {
+    path: relative,
+    type: 'screenshot',
+    nodeId: context.nodeId,
+    label: metadata?.label ?? `${context.nodeId} screenshot`,
+    category: metadata?.category ?? 'evidence',
+    mimeType: 'image/png',
+    metadata: {
+      provider: 'capture-helper',
+      mode,
+      pid,
+      ...(details ? { captureHelper: details } : {}),
+    },
+  };
 }
 
 function autolaunchEnabled(input) {

package/library/actions/extension/ui/locators.mjs

@@ -0,0 +1,13 @@
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+import {
+  locatorsFromObservation,
+  requireVisibleObservation,
+} from '../../shared/ui/locators.mjs';
+
+runAdapter(async (input) => withExtensionPage(input, async (page) => {
+  const observed = await page.observe(['ui.visible']);
+  return {
+    action: input.action,
+    ...locatorsFromObservation(requireVisibleObservation(observed)),
+  };
+}));

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

@@ -7,6 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import bridgeErrors from '../../../../adapters/mobile/bridge-runtime/lib/bridge-errors.cjs';
+import { resolveMobileToolPath } from './tool-paths.mjs';
 
 const {
   BRIDGE_ERROR_CODES,
@@ -72,9 +73,11 @@ function runtimeDir() {
  * or the serial does not respond. Uses execFile (never shell interpolation).
  */
 async function resolveAndroidModel(adbSerial) {
+  const adbPath = resolveMobileToolPath('adb');
+  if (!adbPath) return null;
   try {
     const { stdout } = await execFileAsync(
-      'adb',
+      adbPath,
       ['-s', adbSerial, 'shell', 'getprop', 'ro.product.model'],
       { timeout: 5000, encoding: 'utf8' },
     );
@@ -90,12 +93,16 @@ async function resolveAndroidModel(adbSerial) {
 }
 
 export async function bridgeEnv(input) {
+  const adbPath = resolveMobileToolPath('adb');
+  const idbPath = resolveMobileToolPath('idb');
   /** @type {NodeJS.ProcessEnv} */
   const env = {
     ...process.env,
     ...(input.context?.env || {}),
     CDP_TIMEOUT: String(input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? '10000'),
   };
+  if (adbPath) env.MM_HARNESS_ADB_PATH = adbPath;
+  if (idbPath) env.MM_HARNESS_IDB_PATH = idbPath;
   const target = resolveMobileTarget(input);
   const watcherPort = target.watcherPort;
   const simulator = target.iosSimulator;
@@ -483,13 +490,14 @@ async function androidScreenshot(input, relPath) {
   try {
     temporaryDirectory = await createScreenshotTemporaryDirectory();
     const adbSerial = await resolveAndroidScreenshotSerial(input);
+    const adbPath = resolveMobileToolPath('adb', { required: true });
     let result;
     try {
-      result = await runScreenshotProcess('adb', ['-s', adbSerial, 'exec-out', 'screencap', '-p'], true);
+      result = await runScreenshotProcess(adbPath, ['-s', adbSerial, 'exec-out', 'screencap', '-p'], true);
     } catch (error) {
       throw new Error(
         `adb screenshot could not start for ${adbSerial}: ${error instanceof Error ? error.message : String(error)}\n` +
-        '  Next: install Android SDK Platform-Tools, ensure adb is on PATH, then rerun the same mm-harness command.',
+        '  Next: install Android SDK Platform-Tools, then rerun the same mm-harness command.',
       );
     }
     if (result.exitCode !== 0) {
@@ -541,11 +549,12 @@ async function resolveAndroidScreenshotSerial(input) {
 
   let result;
   try {
-    result = await runScreenshotProcess('adb', ['devices'], false);
+    const adbPath = resolveMobileToolPath('adb', { required: true });
+    result = await runScreenshotProcess(adbPath, ['devices'], false);
   } catch (error) {
     throw new Error(
       `Android screenshot could not resolve an adb serial: ${error instanceof Error ? error.message : String(error)}\n` +
-      '  Next: install Android SDK Platform-Tools, ensure adb is on PATH, then rerun with --device <adb-serial>.',
+      '  Next: install Android SDK Platform-Tools, then rerun with --device <adb-serial>.',
     );
   }
   if (result.exitCode !== 0) {