@deeeed/metamask-harness 0.26.4 → 0.27.0

package/dist/commands/doctor.js

@@ -131,7 +131,31 @@ async function handleDoctor({ options }) {
     }
     return status === "pass" ? 0 : 1;
   }
-  const result = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
+  const mobilePlatform = adapter === "mobile" && (platformOption === "ios" || platformOption === "android") ? platformOption : void 0;
+  const result = createDoctorReport(
+    adapter,
+    target,
+    manifestValidation,
+    actionManifestPath,
+    mobilePlatform
+  );
+  const missingRequiredTool = result.checks.find(
+    (check) => check.required && check.status === "fail" && check.id.startsWith("device-tool-") && check.userAction
+  );
+  if (missingRequiredTool) {
+    const error = {
+      code: "DOCTOR_CHECKS_FAILED",
+      message: missingRequiredTool.message,
+      userAction: missingRequiredTool.userAction
+    };
+    if (json) {
+      console.log(JSON.stringify({ ...result, ready: false, error }, null, 2));
+    } else {
+      console.error(`\u2717 doctor: ${error.message}
+  Next: ${error.userAction}`);
+    }
+    return EXIT.runtime;
+  }
   let runtime;
   let runtimeProbeError;
   try {
@@ -178,7 +202,9 @@ async function handleDoctor({ options }) {
       printReady
     );
   }
-  const doctorUserAction = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+  const doctorUserAction = doctorResult.checks.find(
+    (check) => check.required && check.status === "fail" && check.userAction
+  )?.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
   const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
   const next = doctorError?.userAction ?? (runtime?.decision === "ready" ? void 0 : runtime?.nextAction);
   if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...next ? { next } : {}, ...doctorError ? { error: doctorError } : {} }, null, 2));

package/dist/commands/mobile-device-view.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { resolveMobileToolPath } from "../../library/actions/mobile/platform/tool-paths.mjs";
 import { listConnectedDevices } from "../devices.js";
 import { renderDeviceList, scopedDevices } from "./device-target.js";
 import { probeMobileLiveState } from "./status-probe.js";
@@ -116,8 +117,10 @@ function selectedAndroidPortHints(devices, liveMap) {
   }).filter((hint) => hint.reversePorts.length > 0);
 }
 function androidReversePorts(serial) {
+  const adbPath = resolveMobileToolPath("adb");
+  if (!adbPath) return [];
   try {
-    const out = execFileSync("adb", ["-s", serial, "reverse", "--list"], {
+    const out = execFileSync(adbPath, ["-s", serial, "reverse", "--list"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5e3

package/dist/devices.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 function listConnectedDevices(platform) {
   const devices = [];
   if (!platform || platform === "android") devices.push(...listAndroidDevices());
@@ -6,9 +7,11 @@ function listConnectedDevices(platform) {
   return devices;
 }
 function listAndroidDevices() {
+  const adbPath = resolveMobileToolPath("adb");
+  if (!adbPath) return [];
   let output;
   try {
-    output = execFileSync("adb", ["devices", "-l"], {
+    output = execFileSync(adbPath, ["devices", "-l"], {
       encoding: "utf8",
       timeout: 5e3,
       stdio: ["ignore", "pipe", "ignore"]

package/dist/doctor.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { color } from "./cli-color.js";
+import {
+  mobileToolRecovery,
+  resolveMobileToolPath
+} from "../library/actions/mobile/platform/tool-paths.mjs";
 import { mobilePerpsEnvironment } from "./adapters/mobile/perps-env.js";
 import { readRuntimeContextField, resolveRuntimeContextPath } from "./harness.js";
 import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
@@ -128,7 +132,7 @@ function renderRuntimeContext(runtimeContext) {
   }
   return lines.join("\n");
 }
-function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter)) {
+function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter), mobilePlatform) {
   const mode = compatibilityMode(adapter, target);
   const manifestErrors = Number(manifestValidation.summary?.errors ?? 0);
   const checks = [
@@ -143,7 +147,8 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
       status: mode === "unsupported/no bridge" ? "fail" : "pass",
       required: false,
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
-    }
+    },
+    ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
@@ -164,6 +169,23 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
     manifestValidation: manifestValidation.summary
   };
 }
+function mobileToolDoctorChecks(platform) {
+  const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
+    { tool: "adb", platform: "Android" },
+    { tool: "idb", platform: "iOS" }
+  ];
+  return specs.map(({ tool, platform: platformName }) => {
+    const resolved = resolveMobileToolPath(tool);
+    return {
+      id: `device-tool-${tool}`,
+      status: resolved ? "pass" : "fail",
+      required: platform !== void 0,
+      message: resolved ? `${platformName} device tool ${tool} is ready.` : `${platformName} device tool ${tool} is unavailable.`,
+      ...resolved ? { detail: resolved } : {},
+      ...!resolved ? { userAction: mobileToolRecovery(tool) } : {}
+    };
+  });
+}
 function runnerInstallKind(runnerRoot, invokedPath, executablePath) {
   const normalizedRoot = path.normalize(runnerRoot);
   const nodeModulesSegment = `${path.sep}node_modules${path.sep}`;
@@ -230,6 +252,7 @@ export {
   createDoctorReport,
   fixtureFileSummary,
   fixtureSummary,
+  mobileToolDoctorChecks,
   renderRuntimeContext,
   repoShape,
   requiredDoctorCheckSummary,

package/dist/run-recording.js

@@ -6,6 +6,7 @@ import {
   resolveExtensionBrowserPid
 } from "./recording-target.js";
 const activeRecordingsByPid = /* @__PURE__ */ new Map();
+const ACTIVE_EXTENSION_RECORDING_PID = "METAMASK_RECIPE_EXTENSION_ACTIVE_RECORDING_PID";
 async function startRecipeRecording(adapter, projectRoot, artifactsDir, options) {
   if (!options.record) return void 0;
   if (process.platform !== "darwin") {
@@ -31,17 +32,27 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
   }
   const recordArgs = ["record", "--framed", "--pid", String(pid)];
   const relativePath = "videos/full-run.mp4";
-  const stage = preparePrivateRecordingStage(artifactsDir, relativePath);
-  const child = spawn(captureHelperPath(), [...recordArgs, "--output", stage.stagedOutputPath], {
-    cwd: projectRoot,
-    env: process.env,
-    stdio: ["pipe", "pipe", "pipe"]
-  });
+  const outputPath = path.join(artifactsDir, relativePath);
+  const { stagingDir, stagedPath } = preparePrivateRecordingDestination(
+    artifactsDir,
+    outputPath
+  );
+  let child;
+  try {
+    child = spawn(captureHelperPath(), [...recordArgs, "--output", stagedPath], {
+      cwd: projectRoot,
+      env: process.env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch (error) {
+    cleanupRecordingStaging(stagingDir);
+    throw error;
+  }
   const recording = {
     child,
-    outputPath: stage.outputPath,
-    stagedOutputPath: stage.stagedOutputPath,
-    stagingDir: stage.stagingDir,
+    outputPath,
+    stagingDir,
+    stagedPath,
     relativePath,
     pid,
     stdout: "",
@@ -50,6 +61,7 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     exitCode: null,
     frameReady: false,
     finalized: false,
+    previousActiveRecordingPid: process.env[ACTIVE_EXTENSION_RECORDING_PID],
     stderrBuffer: "",
     pendingSnapshots: /* @__PURE__ */ new Map()
   };
@@ -69,11 +81,12 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     recording.exited = true;
     recording.exitCode = exitCode;
     activeRecordingsByPid.delete(recording.pid);
+    restoreActiveRecordingEnvironment(recording);
     rejectPendingSnapshots(recording, new Error(`capture-helper recording exited before snapshot completed (code=${exitCode ?? "unknown"})`));
   });
   await waitForRecordingReady(recording, 15e3);
   if (recording.exited) {
-    cleanupRecordingStage(recording);
+    cleanupRecordingStaging(recording.stagingDir);
     throw new Error(
       `capture-helper exited before recording its first frame (code=${recording.exitCode ?? "unknown"}): ${recording.stderr || recording.stdout}`
     );
@@ -82,14 +95,15 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     try {
       await stopRecordingProcess(recording);
     } finally {
-      cleanupRecordingStage(recording);
+      cleanupRecordingStaging(recording.stagingDir);
     }
     throw new Error(
       `capture-helper did not record a frame within 15000ms: ${recording.stderr || recording.stdout || "no recorder output"}`
     );
   }
   activeRecordingsByPid.set(pid, recording);
-  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${recording.outputPath}`);
+  process.env[ACTIVE_EXTENSION_RECORDING_PID] = String(pid);
+  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${outputPath}`);
   return recording;
 }
 async function captureActiveRecipeRecordingSnapshot(pid, outputPath, timeoutMs = 3e4) {
@@ -117,29 +131,22 @@ async function stopRecipeRecording(recording, result) {
   recording.finalized = true;
   try {
     await stopRecordingProcess(recording);
+    const validation = validateRecordingArtifact(recording);
+    if (validation.ok === false) {
+      throw new Error(
+        `capture-helper recording did not produce a usable video artifact: ${validation.reason}`
+      );
+    }
+    publishRecordingArtifact(recording);
+    if (result) addRecordingArtifactToManifest(result, recording);
   } catch (error) {
-    cleanupRecordingStage(recording);
     if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
     throw error;
+  } finally {
+    activeRecordingsByPid.delete(recording.pid);
+    restoreActiveRecordingEnvironment(recording);
+    cleanupRecordingStaging(recording.stagingDir);
   }
-  const validation = validateRecordingArtifact(recording);
-  if (validation.ok === false) {
-    cleanupRecordingStage(recording);
-    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
-    throw new Error(
-      `capture-helper recording did not produce a usable video artifact: ${validation.reason}`
-    );
-  }
-  try {
-    publishPrivateRecording(recording);
-  } catch (error) {
-    cleanupRecordingStage(recording);
-    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
-    throw new Error(
-      `capture-helper recording could not safely publish ${recording.outputPath}: ${error instanceof Error ? error.message : String(error)}`
-    );
-  }
-  if (result) addRecordingArtifactToManifest(result, recording);
 }
 async function stopRecordingProcess(recording) {
   if (!recording.exited && !recording.child.stdin.destroyed) {
@@ -227,117 +234,146 @@ function rejectPendingSnapshots(recording, error) {
   recording.pendingSnapshots.clear();
 }
 function validateRecordingArtifact(recording) {
-  if (!fs.existsSync(recording.stagedOutputPath)) {
-    return { ok: false, reason: `missing output ${recording.stagedOutputPath}` };
+  if (!fs.existsSync(recording.stagedPath)) {
+    return { ok: false, reason: `missing output ${recording.stagedPath}` };
   }
-  const info = fs.lstatSync(recording.stagedOutputPath);
-  if (info.isSymbolicLink() || !info.isFile()) {
-    return { ok: false, reason: `output is not a safe regular file ${recording.stagedOutputPath}` };
+  const stagedStat = fs.lstatSync(recording.stagedPath);
+  if (stagedStat.isSymbolicLink() || !stagedStat.isFile()) {
+    return { ok: false, reason: `unsafe non-regular output ${recording.stagedPath}` };
   }
-  if (info.size === 0) {
-    return { ok: false, reason: `empty output ${recording.stagedOutputPath}` };
+  const size = stagedStat.size;
+  if (size === 0) {
+    return { ok: false, reason: `empty output ${recording.stagedPath}` };
   }
   const recorderOutput = `${recording.stdout}
 ${recording.stderr}`;
   if (!recorderOutput.includes("record_complete")) {
     return {
       ok: false,
-      reason: `capture-helper did not report record_complete for ${recording.stagedOutputPath}: ${recorderOutput.trim() || "no recorder output"}`
+      reason: `capture-helper did not report record_complete for ${recording.stagedPath}: ${recorderOutput.trim() || "no recorder output"}`
     };
   }
   const ffprobe = spawnSync(
     "ffprobe",
-    ["-hide_banner", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", recording.stagedOutputPath],
+    ["-hide_banner", "-v", "error", "-show_entries", "format=duration", "-of", "default=noprint_wrappers=1:nokey=1", recording.stagedPath],
     { encoding: "utf8" }
   );
   if (ffprobe.error && ffprobe.error.code === "ENOENT") {
     return { ok: true };
   }
   if (ffprobe.error) {
-    return { ok: false, reason: `ffprobe failed for ${recording.stagedOutputPath}: ${ffprobe.error.message}` };
+    return { ok: false, reason: `ffprobe failed for ${recording.stagedPath}: ${ffprobe.error.message}` };
   }
   if (ffprobe.status !== 0) {
     return {
       ok: false,
-      reason: `invalid MP4 ${recording.stagedOutputPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`
+      reason: `invalid MP4 ${recording.stagedPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`
     };
   }
   const durationSeconds = Number(ffprobe.stdout.trim());
   if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
-    return { ok: false, reason: `MP4 has no positive duration: ${recording.outputPath}` };
+    return { ok: false, reason: `MP4 has no positive duration: ${recording.stagedPath}` };
   }
   return { ok: true };
 }
-function preparePrivateRecordingStage(artifactsDir, relativePath) {
-  const artifactsRoot = path.resolve(artifactsDir);
-  const outputPath = path.resolve(artifactsRoot, relativePath);
-  if (!outputPath.startsWith(`${artifactsRoot}${path.sep}`)) {
-    throw new Error(`Refusing recording artifact outside artifacts dir: ${relativePath}`);
-  }
-  fs.mkdirSync(artifactsRoot, { recursive: true });
-  ensureRecordingParent(artifactsRoot, path.dirname(outputPath));
-  refuseUnsafeRecordingDestination(outputPath);
-  const stagingDir = fs.mkdtempSync(path.join(artifactsRoot, ".extension-recording-"));
+function preparePrivateRecordingDestination(artifactsDir, outputPath) {
+  const outputDir = path.dirname(outputPath);
+  ensureRecordingDirectory(path.resolve(artifactsDir), outputDir);
+  refuseRecordingDestinationSymlink(outputPath);
+  const stagingDir = fs.mkdtempSync(path.join(outputDir, ".mm-harness-recording-"));
   fs.chmodSync(stagingDir, 448);
   return {
-    outputPath,
-    stagedOutputPath: path.join(stagingDir, "full-run.mp4"),
-    stagingDir
+    stagingDir,
+    stagedPath: path.join(stagingDir, "full-run.mp4")
   };
 }
-function ensureRecordingParent(artifactsRoot, parent) {
-  const relative = path.relative(artifactsRoot, parent);
+function ensureRecordingDirectory(artifactsRoot, outputDir) {
+  fs.mkdirSync(artifactsRoot, { recursive: true });
+  requireRecordingDirectory(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);
-    const info = lstatIfPresent(current);
-    if (!info) {
-      fs.mkdirSync(current, { mode: 448 });
-      continue;
-    }
-    if (info.isSymbolicLink() || !info.isDirectory()) {
-      throw new Error(`Refusing recording artifact parent that is not a real directory: ${current}`);
+    try {
+      fs.mkdirSync(current);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
     }
+    requireRecordingDirectory(current);
   }
 }
-function refuseUnsafeRecordingDestination(outputPath) {
-  const info = lstatIfPresent(outputPath);
-  if (!info) return;
-  if (info.isSymbolicLink()) {
-    throw new Error(`Refusing recording artifact destination symlink: ${outputPath}`);
-  }
-  if (!info.isFile()) {
-    throw new Error(`Refusing recording artifact destination that is not a regular file: ${outputPath}`);
+function requireRecordingDirectory(directory) {
+  const entry = fs.lstatSync(directory);
+  if (entry.isDirectory() && !entry.isSymbolicLink()) return;
+  throw new Error(
+    `Refusing unsafe recording artifact directory: ${directory}
+Next: replace ${JSON.stringify(directory)} with a regular directory and retry the recipe.`
+  );
+}
+function publishRecordingArtifact(recording) {
+  const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(recording.stagedPath, fs.constants.O_RDONLY | noFollow);
+    const stagedStat = fs.fstatSync(descriptor);
+    if (!stagedStat.isFile()) {
+      throw unsafeRecordingArtifactError(recording.stagedPath);
+    }
+    fs.fchmodSync(descriptor, 384);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Next:")) throw error;
+    throw unsafeRecordingArtifactError(
+      recording.stagedPath,
+      error instanceof Error ? error.message : String(error)
+    );
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
   }
+  refuseRecordingDestinationSymlink(recording.outputPath);
+  fs.renameSync(recording.stagedPath, recording.outputPath);
 }
-function lstatIfPresent(filePath) {
+function refuseRecordingDestinationSymlink(outputPath) {
   try {
-    return fs.lstatSync(filePath);
+    const destination = fs.lstatSync(outputPath);
+    if (destination.isSymbolicLink()) {
+      throw new Error(
+        `Refusing recording artifact destination symlink: ${outputPath}
+Next: rm -- ${JSON.stringify(outputPath)} and retry the recipe.`
+      );
+    }
+    if (!destination.isFile()) {
+      throw new Error(
+        `Refusing non-file recording artifact destination: ${outputPath}
+Next: remove ${JSON.stringify(outputPath)} and retry the recipe.`
+      );
+    }
   } catch (error) {
-    if (error.code === "ENOENT") return void 0;
+    if (error.code === "ENOENT") return;
     throw error;
   }
 }
-function publishPrivateRecording(recording) {
-  const descriptor = fs.openSync(
-    recording.stagedOutputPath,
-    fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)
+function unsafeRecordingArtifactError(stagedPath, detail) {
+  return new Error(
+    `Capture-helper recording output is not a safe regular file: ${stagedPath}${detail ? ` (${detail})` : ""}.
+Next: capture-helper doctor --json`
   );
+}
+function cleanupRecordingStaging(stagingDir) {
   try {
-    const info = fs.fstatSync(descriptor);
-    if (!info.isFile()) {
-      throw new Error(`Captured recording is not a safe regular file: ${recording.stagedOutputPath}`);
-    }
-    fs.fchmodSync(descriptor, 384);
-    refuseUnsafeRecordingDestination(recording.outputPath);
-    fs.renameSync(recording.stagedOutputPath, recording.outputPath);
-  } finally {
-    fs.closeSync(descriptor);
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+  } catch (error) {
+    console.error(
+      `WARN: could not remove capture-helper staging directory ${stagingDir}: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
-  cleanupRecordingStage(recording);
 }
-function cleanupRecordingStage(recording) {
-  fs.rmSync(recording.stagingDir, { recursive: true, force: true });
+function restoreActiveRecordingEnvironment(recording) {
+  if (process.env[ACTIVE_EXTENSION_RECORDING_PID] !== String(recording.pid)) return;
+  if (recording.previousActiveRecordingPid === void 0) {
+    delete process.env[ACTIVE_EXTENSION_RECORDING_PID];
+    return;
+  }
+  process.env[ACTIVE_EXTENSION_RECORDING_PID] = recording.previousActiveRecordingPid;
 }
 function addRecordingArtifactToManifest(result, recording) {
   const manifestPath = result.artifactManifestPath;