@deeeed/metamask-harness 0.74.0 → 0.76.0

package/dist/cli-commands.js

@@ -19,6 +19,7 @@ const SPEC = {
     { name: "ports", desc: "Slot ports and runtime paths", flags: ["--json"] },
     { name: "up", desc: "Decide + run minimum work to reach ready", flags: ["--json", "--dry-run"] },
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", flags: ["--json"] },
+    { name: "pin", desc: "Copy this install into an immutable store for a task to run", flags: ["--json"] },
     { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "reload", desc: "Reload the connected app runtime", flags: ["--json"] },

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { adapterRegistry } from "./adapters/registry.js";
 import { detectAdapter, handleHarness } from "./harness.js";
 import { handleActions } from "./commands/manifest.js";
 import { handleDoctor } from "./commands/doctor.js";
@@ -108,7 +109,8 @@ async function main(argv) {
         const { options } = parseArgs(argv.slice(1), command);
         const target = targetPath(options);
         const adapterRaw = (typeof options["adapter"] === "string" ? options["adapter"] : void 0) ?? (typeof options["platform"] === "string" ? options["platform"] : void 0) ?? detectAdapter(target);
-        if (adapterRaw === "mobile" || adapterRaw === "extension" || adapterRaw === "core" || adapterRaw === "terminal") {
+        await import("./adapters/surface.js");
+        if (adapterRaw && adapterRegistry.has(adapterRaw)) {
           await handleHarness(["install", "--platform", adapterRaw, "--target", target, "--quiet"]);
         }
       } catch {

package/dist/command-contract.js

@@ -398,6 +398,9 @@ const PUBLIC_COMMAND_CONTRACTS = {
   update: {
     options: options(HELP, JSON, { "--check": bool() })
   },
+  pin: {
+    options: options(HELP, JSON)
+  },
   fixtures: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, {
       "--from": value(),

package/dist/commands/call.js

@@ -28,7 +28,6 @@ import {
 import { getAdapterSurface } from "../adapters/surface.js";
 import { handleListExecutables } from "./list-executables.js";
 import { applyDeviceTargeting } from "./device-target.js";
-import { coreDependencyBlock } from "./core-readiness.js";
 import {
   emitHealViolation,
   executeWithHealBounds,
@@ -40,7 +39,6 @@ import {
   synthesizeOneNodeRecipe,
   validateRecipeAdapterAware
 } from "./run-engine.js";
-import { readMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 import {
@@ -178,7 +176,7 @@ async function handleCall(argv) {
   const resolvedAction = resolution.resolved;
   const describedAction = describeManifestActions(manifest, actionSources).find((entry) => entry.name === resolvedAction);
   const defaultsUsed = actionDefaultsUsed(describedAction, args);
-  const depsBlock = adapter === "core" && resolvedAction.startsWith("metamask.perps.") ? coreDependencyBlock(target) : null;
+  const depsBlock = await getAdapterSurface(adapter).run?.dependencyBlock?.(target, { action: resolvedAction }) ?? null;
   if (depsBlock) {
     if (json) {
       console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, status: "fail", exitCode: EXIT.usage, error: depsBlock }, null, 2));
@@ -286,9 +284,8 @@ async function handleCall(argv) {
     return checkoutBusyOut(json, "call", lock.message, lock.path);
   }
   try {
-    const authoredMobileRestart = adapter === "mobile" && resolvedAction === "app.lifecycle" && args.command === "restart";
     const prepared = await prepareHeal(adapter, target, options, json, {
-      skipMobileSourceFreshness: authoredMobileRestart || adapter === "mobile" && readMobileReleaseArtifactState(target) !== null
+      appRestartAuthored: resolvedAction === "app.lifecycle" && args.command === "restart"
     });
     if (typeof prepared === "number") return prepared;
     const { state } = prepared;

package/dist/commands/debug.js

@@ -10,36 +10,17 @@ async function handleDebug(argv) {
   const adapter = resolveAdapter(options, target);
   if (!adapter) return usageOut(json, "debug", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   const surface = getAdapterSurface(adapter);
-  if (surface.headless) return usageOut(json, "debug", "core is headless; there is no debug console.", surface.hints.relaunch);
+  if (surface.headless) return usageOut(json, "debug", `${adapter} is headless; there is no debug console.`, surface.hints.relaunch);
   surface.resolveSlotPorts(target);
   const worker = flag(options, "worker");
   const devMenu = flag(options, "devMenu");
   const noOpen = flag(options, "noOpen");
-  if (adapter === "mobile" && worker) {
-    return usageOut(
-      json,
-      "debug",
-      "--worker is extension-only (service-worker DevTools). Use --dev-menu on mobile.",
-      "mm-harness debug --dev-menu"
-    );
-  }
-  if (adapter === "extension" && devMenu) {
-    return usageOut(
-      json,
-      "debug",
-      "--dev-menu is mobile-only (RN developer menu). Use --worker on the extension.",
-      "mm-harness debug --worker"
-    );
-  }
+  const debug = surface.debug;
+  if (!debug) return usageOut(json, "debug", `${adapter} has no debug console.`, surface.hints.relaunch);
+  const refused = debug.refuse?.({ worker, devMenu });
+  if (refused) return usageOut(json, "debug", refused.message, refused.userAction);
   const openDebug = path.join(runnerDir, "adapters/shared/open-debug.mjs");
-  const debugArgs = ["--adapter", adapter];
-  if (adapter === "extension") {
-    if (process.env.CDP_PORT) debugArgs.push("--cdp-port", process.env.CDP_PORT);
-    debugArgs.push("--target", worker ? "worker" : "page");
-  } else {
-    if (process.env.WATCHER_PORT) debugArgs.push("--port", process.env.WATCHER_PORT);
-    debugArgs.push("--action", devMenu ? "dev-menu" : "debug");
-  }
+  const debugArgs = ["--adapter", adapter, ...debug.args({ worker, devMenu })];
   if (json) debugArgs.push("--json");
   if (noOpen) debugArgs.push("--no-open");
   const result = spawnScript(process.execPath, [openDebug, ...debugArgs], target, json);

package/dist/commands/device-target.js

@@ -4,6 +4,7 @@ import {
   findAvailableIosSimulatorById,
   listConnectedDevices
 } from "../devices.js";
+import { getAdapterSurface } from "../adapters/surface.js";
 import { persistExplicitDevicePin } from "../runtime-context.js";
 import { optionString, shellQuoteArg, targetPath } from "./parse-args.js";
 const DEVICE_SELECT_HINT = "Pass --device <name|udid|serial> to select one target. Do not shut down other connected devices to force selection.";
@@ -97,7 +98,7 @@ function deviceRecovery(options, rerun) {
 function applyDeviceTargeting(command, adapter, options, opts) {
   const device = optionString(options, "device");
   const platformPreference = mobilePlatformPreference(options);
-  if (adapter !== "mobile") {
+  if (!getAdapterSurface(adapter).readiness.devices) {
     if (device !== void 0) {
       return {
         ok: false,

package/dist/commands/doctor.js

@@ -1,28 +1,16 @@
 import { execFileSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { readExtensionPinnedFlags } from "../adapters/extension/feature-flags.js";
 import { featureFlagReport } from "../feature-flags.js";
 import { color } from "../cli-color.js";
 import { collectCheckoutView, renderCheckoutView } from "../checkout-view.js";
 import { createDoctorReport, fixtureSummary, requiredDoctorCheckSummary } from "../doctor.js";
-import { terminalAppPort, terminalCdpPort } from "../adapters/terminal/surface.js";
 import { detectAdapter, resolveRuntimeContextPath } from "../harness.js";
 import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { extensionProductConfigBlock } from "../adapters/extension/product-config.js";
-import { ensureMobilePerpsEnvironment, mobilePerpsEnvironment } from "../adapters/mobile/perps-env.js";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
 import { applyDeviceTargeting } from "./device-target.js";
-import {
-  mobileDeviceView,
-  mobileDeviceLiveView,
-  renderAdditionalReachableDevices,
-  renderMobileDeviceList,
-  renderMobileLiveBlock
-} from "./mobile-device-view.js";
 import { farmslotReadyIndicator } from "./farmslot-ready.js";
 import { updateStatus } from "./update.js";
 import { ensureRuntimeContext } from "../runtime-context.js";
@@ -63,6 +51,7 @@ async function handleDoctor({ options }) {
     return usageOut(json, "doctor", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   assertAdapter(adapter);
+  const { readiness } = getAdapterSurface(adapter);
   if (!fs.existsSync(target)) {
     return usageOut(
       json,
@@ -110,10 +99,9 @@ async function handleDoctor({ options }) {
       runtimeProbeError2 = error2 instanceof Error ? error2.message : String(error2);
     }
     const ready = runtime2?.decision === "ready";
-    if (adapter === "extension" && runtime2?.reasonCode === "product-config-required") {
-      failed.push("extension-product-config");
-    }
-    const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target);
+    const block = readiness.runtimeBlock?.(target, runtime2);
+    if (block) failed.push(block.id);
+    const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target, block);
     if (failed.length === 0 && !ready && runtime2?.nextAction) nextActions.push(runtime2.nextAction);
     const status = result2.status === "pass" && failed.length === 0 ? "pass" : "fail";
     const retryDoctor = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
@@ -136,13 +124,12 @@ async function handleDoctor({ options }) {
     }
     return status === "pass" ? 0 : 1;
   }
-  const mobilePlatform = adapter === "mobile" && (platformOption === "ios" || platformOption === "android") ? platformOption : void 0;
   const result = createDoctorReport(
     adapter,
     target,
     manifestValidation,
     actionManifestPath,
-    mobilePlatform
+    platformOption
   );
   const view = collectCheckoutView(target, adapter);
   const missingRequiredTool = result.checks.find(
@@ -183,7 +170,7 @@ async function handleDoctor({ options }) {
   const checks = [
     ...result.checks,
     runtimeCheck,
-    ...adapter === "terminal" ? await terminalDoctorChecks(target) : []
+    ...await readiness.liveChecks?.(target) ?? []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   const doctorResult = {
@@ -192,10 +179,11 @@ async function handleDoctor({ options }) {
     checks,
     requiredChecks
   };
-  const orphanMetros = adapter === "mobile" ? detectOrphanMetros(target, process.env.WATCHER_PORT) : [];
-  const capture = captureHealth(adapter);
-  const deviceView = adapter === "mobile" ? mobileDeviceView(allDevices) : null;
-  const liveView = deviceView ? await mobileDeviceLiveView(target, deviceView) : null;
+  const orphanMetros = readiness.orphanDevServers?.(target, process.env.WATCHER_PORT) ?? [];
+  const capture = captureHealth(readiness.captureProviders);
+  const deviceSource = await readiness.devices?.();
+  const deviceView = deviceSource ? deviceSource.view(allDevices) : null;
+  const liveView = deviceSource && deviceView ? await deviceSource.live(target, deviceView) : null;
   const devices = liveView?.devicesWithLive ?? deviceView?.devices ?? [];
   const additionalReachableDevices = liveView?.additionalReachableDevices ?? [];
   const discovery = deviceView?.deviceDiscoveryErrors.length ? { deviceDiscoveryErrors: deviceView.deviceDiscoveryErrors } : {};
@@ -216,8 +204,8 @@ async function handleDoctor({ options }) {
   }
   const skills = skillsView(target);
   const update = updateStatus();
-  const extensionFlags = adapter === "extension" ? readExtensionPinnedFlags(target) : null;
-  const featureFlags = extensionFlags ? featureFlagReport(extensionFlags.overrides, extensionFlags) : featureFlagReport(liveView?.featureFlagOverrides ?? null);
+  const pinnedFlags = readiness.pinnedFlags?.(target) ?? null;
+  const featureFlags = pinnedFlags ? featureFlagReport(pinnedFlags.overrides, pinnedFlags) : featureFlagReport(liveView?.featureFlagOverrides ?? null);
   const doctorUserAction = doctorResult.checks.find(
     (check) => check.required && check.status === "fail" && check.userAction
   )?.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
@@ -249,12 +237,7 @@ async function handleDoctor({ options }) {
       featureFlags.error || (featureFlags.overrideCount ?? 0) > 0 ? "warn" : "dim",
       featureFlags.summary.replace(/^feature flags: /u, "")
     )}`);
-    if (adapter === "mobile") {
-      const perps = mobilePerpsEnvironment(target);
-      console.log(
-        `mobile-perps: ${perps.status} (${perps.file}; MM_PERPS_ENABLED=${perps.perpsEnabled.value ?? "missing"}; OVERRIDE_REMOTE_FEATURE_FLAGS=${perps.remoteFeatureFlagOverride.value ?? "missing"})`
-      );
-    }
+    for (const line of readiness.lines?.(target) ?? []) console.log(line);
     if (orphanMetros.length > 0) {
       console.log(
         `${out("warn", "orphan Metro:")} ${orphanMetros.length} leaked bundler(s) for this checkout (pids ${orphanMetros.join(", ")})`
@@ -264,33 +247,15 @@ async function handleDoctor({ options }) {
     if (capture) renderCaptureHealth(capture, out);
     renderSkillsView(skills, out);
     renderUpdateStatus(update, out);
-    if (adapter === "mobile") {
-      if (deviceView) renderMobileDeviceList(deviceView, out);
-      if (additionalReachableDevices.length > 0) renderAdditionalReachableDevices(additionalReachableDevices, out);
-      if (liveView) renderMobileLiveBlock(deviceView?.devices ?? [], liveView.liveMap, out);
+    if (deviceSource) {
+      if (deviceView) deviceSource.renderList(deviceView, out);
+      if (additionalReachableDevices.length > 0) deviceSource.renderAdditional(additionalReachableDevices, out);
+      if (liveView) deviceSource.renderLive(deviceView?.devices ?? [], liveView.liveMap, out);
     }
     if (next) console.log(`  ${out("dim", `Next: ${next}`)}`);
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
-async function terminalDoctorChecks(target) {
-  const { terminalReadiness } = await import("../../adapters/terminal/lib/readiness.mjs");
-  const { resolveBrowser } = await import("../../adapters/terminal/launch.mjs");
-  const report = await terminalReadiness({
-    target,
-    appPort: terminalAppPort(),
-    cdpPort: terminalCdpPort(),
-    signer: process.env.TERMINAL_SIGNER || "extension",
-    account: process.env.TERMINAL_ACCOUNT || "dev1",
-    probeBrowser: resolveBrowser
-  });
-  return report.checks.map((check) => ({
-    id: `terminal-${check.id}`,
-    status: check.status === "pass" ? "pass" : "fail",
-    required: check.required,
-    message: check.detail
-  }));
-}
 function doctorRuntimeCheck(runtime, error, expectLive) {
   if (error) {
     return {
@@ -310,7 +275,7 @@ function doctorRuntimeCheck(runtime, error, expectLive) {
     detail: runtime?.reasons.join(" | ") || "Runtime readiness probe returned no result."
   };
 }
-function doctorFixNextActions(failed, fixture, adapter, target) {
+function doctorFixNextActions(failed, fixture, adapter, target, block) {
   const actions = [];
   const executable = process.env.MM_HARNESS_EXECUTABLE ? shellQuote(process.env.MM_HARNESS_EXECUTABLE) : "mm-harness";
   const scope = `--adapter ${adapter} --target ${shellQuote(target)}`;
@@ -325,10 +290,7 @@ function doctorFixNextActions(failed, fixture, adapter, target) {
     );
   }
   if (failed.includes("overlay")) actions.push(`${executable} install ${scope}`);
-  if (adapter === "extension" && failed.includes("extension-product-config")) {
-    const block = extensionProductConfigBlock(target);
-    if (block) actions.push(block.userAction);
-  }
+  if (block?.userAction && failed.includes(block.id)) actions.push(block.userAction);
   return actions;
 }
 function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
@@ -367,9 +329,9 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
   emitExpectLiveVerdict(adapter, target, runtime, "not-live");
   return EXIT.runtime;
 }
-function captureHealth(adapter) {
-  if (adapter === "core") return null;
-  const fallback = adapter === "extension" ? ["cdp"] : ["simctl", "adb"];
+function captureHealth(providers) {
+  if (!providers) return null;
+  const fallback = [...providers];
   const helper = captureHelperHealth();
   if (!helper) {
     return {
@@ -445,18 +407,6 @@ function renderUpdateStatus(status, out) {
     status.updateAvailable ? `${out("label", "update:")} ${out("warn", `${status.current} \u2192 ${status.latest} available`)} ${out("dim", "(mm-harness update)")}` : status.latest && status.latest !== status.current ? `${out("label", "update:")} ${out("ok", status.current)} ${out("dim", `ahead of registry ${status.latest}`)}` : `${out("label", "update:")} ${out("ok", `${status.current} is latest`)}`
   );
 }
-function detectOrphanMetros(target, livePort) {
-  try {
-    const script = path.join(runnerDir, "adapters/shared/reap-checkout-metros.sh");
-    const out = execFileSync("bash", ["-c", `. "$1"; detect_checkout_metros "$2" "$3"`, "mm-harness-doctor", script, target, livePort ?? ""], {
-      encoding: "utf8",
-      timeout: 5e3
-    });
-    return out.split("\n").map((line) => line.trim()).filter((line) => /^\d+$/u.test(line));
-  } catch {
-    return [];
-  }
-}
 async function runDoctorFix(adapter, target, manifestValidation, json) {
   const fixed = [];
   const failed = [];
@@ -473,18 +423,11 @@ async function runDoctorFix(adapter, target, manifestValidation, json) {
   } catch {
     failed.push("runtime-context");
   }
-  if (adapter === "extension") {
-    try {
-      if (ensureExtensionPerpsBuildFlag(target)) fixed.push("extension-perps-build");
-    } catch {
-      failed.push("extension-perps-build");
-    }
-  }
-  if (adapter === "mobile") {
+  for (const fix of getAdapterSurface(adapter).readiness.fixes ?? []) {
     try {
-      if (ensureMobilePerpsEnvironment(target).length > 0) fixed.push("mobile-perps-env");
+      if (fix.apply(target)) fixed.push(fix.id);
     } catch {
-      failed.push("mobile-perps-env");
+      failed.push(fix.id);
     }
   }
   const state = newHealState();
@@ -508,62 +451,8 @@ async function runDoctorFix(adapter, target, manifestValidation, json) {
   }
   return { fixed, failed };
 }
-function ensureExtensionPerpsBuildFlag(target) {
-  const configPath = path.join(target, ".metamaskrc");
-  const templatePath = path.join(target, ".metamaskrc.dist");
-  const config = readTextSnapshot(configPath);
-  const template = config.kind === "file" ? null : readTextSnapshot(templatePath);
-  const source = config.kind === "file" ? config : template?.kind === "file" ? template : config.kind === "symlink" ? { kind: "file", text: "", mode: 438 } : null;
-  if (!source) return false;
-  const before = source.text;
-  if (/^\s*PERPS_ENABLED\s*=\s*(['"]?)true\1\s*$/mu.test(before)) return false;
-  const line = "PERPS_ENABLED='true'";
-  const after = /^\s*PERPS_ENABLED\s*=.*$/mu.test(before) ? before.replace(/^\s*PERPS_ENABLED\s*=.*$/mu, line) : `${before.replace(/\s*$/u, "")}
-${line}
-`;
-  const temporary = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
-  let descriptor = null;
-  try {
-    const mode = config.kind === "file" ? config.mode : 438;
-    descriptor = fs.openSync(
-      temporary,
-      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
-      mode
-    );
-    fs.writeFileSync(descriptor, after);
-    if (config.kind === "file") fs.fchmodSync(descriptor, config.mode);
-    fs.closeSync(descriptor);
-    descriptor = null;
-    fs.renameSync(temporary, configPath);
-  } finally {
-    if (descriptor !== null) fs.closeSync(descriptor);
-    fs.rmSync(temporary, { force: true });
-  }
-  return true;
-}
-function readTextSnapshot(file) {
-  let descriptor;
-  try {
-    descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
-  } catch (error) {
-    const code = error.code;
-    if (code === "ENOENT") return { kind: "missing" };
-    if (code === "ELOOP") return { kind: "symlink" };
-    throw error;
-  }
-  try {
-    return {
-      kind: "file",
-      text: fs.readFileSync(descriptor, "utf8"),
-      mode: fs.fstatSync(descriptor).mode & 511
-    };
-  } finally {
-    fs.closeSync(descriptor);
-  }
-}
 export {
   doctorFixNextActions,
-  ensureExtensionPerpsBuildFlag,
   handleDoctor,
   skillsView
 };