@deeeed/metamask-harness 0.73.0 → 0.75.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/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/launch/device.js

@@ -0,0 +1,342 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import { color, colorHumanMessage } from "../../cli-color.js";
+import { handleHarness } from "../../harness.js";
+import { recipeRuntimePath, walletFixturePath } from "../../paths.js";
+import { getAdapterSurface } from "../../adapters/surface.js";
+import { EXIT, flag, str } from "../shared.js";
+import {
+  checkHealBounds,
+  ensureOverlay,
+  newHealState
+} from "../../heal-bounds.js";
+import {
+  FeatureFlagSpecError,
+  fixtureFeatureFlags,
+  parseRemoteFlagSpec,
+  remoteFlagRequestFor
+} from "../../feature-flags.js";
+import { terminalOnlyLaunchFlags } from "../../adapters/terminal/launch.js";
+import { shellQuote } from "./quote.js";
+async function runDeviceLaunch(context, profile) {
+  const { adapter, options, target, heal, jsonOutput, machine, stream, usage } = context;
+  const terminalOnly = terminalOnlyLaunchFlags(options);
+  if (terminalOnly.length > 0) {
+    return usage(
+      `${terminalOnly.join(", ")} apply only to --adapter terminal; ${adapter} does not read them.`,
+      "drop the terminal flags, or pass --adapter terminal"
+    );
+  }
+  const wantBuild = flag(options, "build");
+  const wantVerify = flag(options, "verify");
+  const wantWatch = flag(options, "watch");
+  const wantRunway = flag(options, "runway");
+  const wantClearMetro = flag(options, "clearMetro");
+  const requestedSurface = str(options, "surface");
+  const legacySidepanel = flag(options, "sidepanel");
+  const legacyFullscreen = flag(options, "fullscreen");
+  const remoteFlagSpec = str(options, "remoteFlag");
+  const refused = profile.refuseFlags(context, { watch: wantWatch, runway: wantRunway, clearMetro: wantClearMetro, remoteFlagSpec });
+  if (refused) return usage(refused.message, refused.userAction);
+  if (requestedSurface !== void 0 && requestedSurface !== "fullscreen" && requestedSurface !== "sidepanel") {
+    return usage(
+      `--surface must be fullscreen or sidepanel (got: ${requestedSurface}).`,
+      "pass --surface fullscreen or --surface sidepanel"
+    );
+  }
+  if (legacySidepanel && legacyFullscreen) {
+    return usage("--sidepanel and --fullscreen conflict.", "pass exactly one Extension surface");
+  }
+  const legacySurface = legacySidepanel ? "sidepanel" : legacyFullscreen ? "fullscreen" : void 0;
+  if (requestedSurface && legacySurface && requestedSurface !== legacySurface) {
+    return usage(
+      `--surface ${requestedSurface} conflicts with --${legacySurface}.`,
+      "pass one consistent Extension surface"
+    );
+  }
+  const displayMode = requestedSurface ?? legacySurface ?? "fullscreen";
+  let remoteFlagRequest;
+  try {
+    remoteFlagRequest = remoteFlagRequestFor({
+      ...fixtureFeatureFlags(walletFixturePath(target)),
+      ...remoteFlagSpec === void 0 ? {} : parseRemoteFlagSpec(remoteFlagSpec)
+    });
+  } catch (error) {
+    if (!(error instanceof FeatureFlagSpecError)) throw error;
+    return usage(error.message, error.userAction);
+  }
+  for (const portFlag of ["cdpPort", "watcherPort"]) {
+    const value = str(options, portFlag);
+    if (value !== void 0 && !/^\d+$/u.test(value)) {
+      return usage(
+        `--${portFlag === "cdpPort" ? "cdp-port" : "watcher-port"} must be numeric (got: ${value}).`,
+        `pass a numeric port, e.g. --${portFlag === "cdpPort" ? "cdp-port 6663" : "watcher-port 8081"}`
+      );
+    }
+  }
+  getAdapterSurface(adapter).resolveSlotPorts(target);
+  const envError = profile.applyEnv?.(context);
+  if (envError) return usage(envError.message, envError.userAction);
+  const cdpPort = str(options, "cdpPort");
+  if (cdpPort) {
+    process.env.CDP_PORT = cdpPort;
+    process.env.RECIPE_CDP_PORT = cdpPort;
+  }
+  const watcherPort = str(options, "watcherPort");
+  if (watcherPort) {
+    process.env.WATCHER_PORT = watcherPort;
+    process.env.RECIPE_WATCHER_PORT = watcherPort;
+    process.env.METRO_PORT = watcherPort;
+  }
+  const launch = {
+    ...context,
+    tier: wantBuild ? "build" : "quick",
+    wantWatch,
+    wantVerify,
+    wantClearMetro,
+    displayMode,
+    remoteFlagRequest,
+    compose: (tier2, restartApp = false, clearMetro = false) => profile.compose(launch, tier2, restartApp, clearMetro),
+    settle: (state2, provenFlags, sidepanelRecoveryAllowed = true) => settleLaunch(launch, profile, state2, sidepanelRecoveryAllowed, provenFlags),
+    fail: (state2, failure) => launchFail(launch, profile, state2, failure)
+  };
+  const { tier } = launch;
+  profile.start(launch);
+  const state = newHealState();
+  if (tier === "quick" && nativeInputsChanged(target, profile.nativeInputs)) {
+    return usage("native build inputs changed since last build.", profile.rebuildCommand(launch));
+  }
+  stream.phase("install");
+  const ensured = await ensureOverlay(adapter, target, heal, state, machine);
+  if (!ensured.ok) {
+    return launch.fail(state, {
+      code: "OVERLAY_INSTALL_FAILED",
+      message: ensured.error ?? "overlay install failed",
+      recoverable: false,
+      exitCode: EXIT.infra
+    });
+  }
+  stream.phase("healthcheck");
+  const blocked = await profile.healthcheck?.(launch, state);
+  if (blocked !== void 0) return blocked;
+  stream.phase("launch");
+  let attempt = await launch.compose(tier, false, wantClearMetro);
+  if (attempt.status === 0) {
+    return await launch.settle(state, attempt.remoteFeatureFlags);
+  }
+  const readinessFailure = readinessBlockFailure(attempt);
+  if (readinessFailure) return launch.fail(state, readinessFailure);
+  const classified = profile.classify(launch, attempt.output);
+  if (classified) return launch.fail(state, classified);
+  if (heal === "off") {
+    return launch.fail(state, {
+      code: "LAUNCH_FAILED",
+      message: `launch ${adapter}${launch.mobileTarget ? ` ${launch.mobileTarget}` : ""} failed (healing off)`,
+      recoverable: false,
+      exitCode: EXIT.infra
+    });
+  }
+  const handled = await profile.beforeHeal?.(launch, attempt, state);
+  if (handled !== void 0) return handled;
+  const bound = checkHealBounds(target, attempt.output, state);
+  if (bound !== null) {
+    return launch.fail(state, {
+      code: bound.code,
+      message: bound.message,
+      recoverable: false,
+      userAction: bound.userAction,
+      exitCode: bound.exitCode,
+      originalError: bound.originalError
+    });
+  }
+  const recovery = profile.recovery(launch, attempt.output);
+  state.attemptedRecoveries.push(recovery.code);
+  stream.phase("recover");
+  const recoveryTier = recovery.restartApp && tier === "build" ? "quick" : tier;
+  if (!jsonOutput) {
+    process.stderr.write(`launch: recovering (${recovery.code}) with the ${recoveryTier} tier
+`);
+  }
+  attempt = await launch.compose(recoveryTier, recovery.restartApp, false);
+  if (attempt.status === 0) {
+    state.recovered.push(recovery.code);
+    return await launch.settle(state, attempt.remoteFeatureFlags);
+  }
+  const retryReadinessFailure = readinessBlockFailure(attempt);
+  if (retryReadinessFailure) return launch.fail(state, retryReadinessFailure);
+  return launch.fail(state, {
+    code: "SAME_RECOVERY_TWICE",
+    message: `launch ${adapter}${launch.mobileTarget ? ` ${launch.mobileTarget}` : ""} failed again after ${recovery.code} recovery \u2014 refusing to loop.`,
+    recoverable: false,
+    exitCode: EXIT.bounded,
+    originalError: attempt.output.trim() || void 0
+  });
+}
+function readinessBlockFailure(result) {
+  const block = result.readinessBlock;
+  if (!block) return void 0;
+  return {
+    code: block.reasonCode === "deps-not-ready" ? "MOBILE_DEPENDENCIES_NOT_READY" : "MOBILE_READINESS_BLOCKED",
+    message: block.message,
+    userAction: block.userAction,
+    recoverable: false,
+    exitCode: result.status
+  };
+}
+function nativeInputsChanged(target, paths) {
+  const baselineFile = recipeRuntimePath(target, ".last-build-ref");
+  let baseline;
+  try {
+    baseline = fs.readFileSync(baselineFile, "utf8").trim();
+  } catch {
+    return false;
+  }
+  if (!baseline) return false;
+  try {
+    const diff = execFileSync("git", ["-C", target, "diff", "--name-only", baseline, "--", ...paths], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return diff.length > 0;
+  } catch {
+    return false;
+  }
+}
+async function settleLaunch(launch, profile, state, sidepanelRecoveryAllowed, provenFlags) {
+  const proven = profile.provenFlags(launch, launch.remoteFlagRequest?.flags ?? {}, provenFlags);
+  if (!("flags" in proven)) return launch.fail(state, proven);
+  const stopped = await profile.finish?.(launch, state, sidepanelRecoveryAllowed);
+  if (stopped !== void 0) return stopped;
+  const { adapter, target, stream, tier } = launch;
+  if (launch.wantVerify) {
+    stream.phase("verify");
+    const verifyArgs = ["verify", "--adapter", adapter, "--target", target, ...profile.verifyArgs(launch)];
+    if (launch.machine) verifyArgs.push("--json");
+    const exitCode = await handleHarness(verifyArgs);
+    if (stream.enabled) {
+      for (const mutation of state.mutations) stream.mutation(mutation);
+      for (const recovery of state.recovered) stream.recovery(recovery);
+      stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode, {
+        adapter,
+        platform: profile.platformLabel(launch),
+        tier,
+        recovered: state.recovered,
+        mutations: state.mutations,
+        metro: profile.evidence?.(target),
+        remoteFeatureFlags: proven.flags
+      });
+    }
+    return exitCode;
+  }
+  return launchPass(launch, profile, state, proven.flags);
+}
+function launchPass(launch, profile, state, remoteFlags) {
+  const { adapter, mobileTarget, target, stream, tier } = launch;
+  if (stream.enabled) {
+    for (const mutation of state.mutations) stream.mutation(mutation);
+    for (const recovery of state.recovered) stream.recovery(recovery);
+    stream.complete("pass", EXIT.ok, {
+      adapter,
+      platform: profile.platformLabel(launch),
+      tier,
+      recovered: state.recovered,
+      mutations: state.mutations,
+      metro: profile.evidence?.(target),
+      remoteFeatureFlags: remoteFlags
+    });
+  } else if (launch.jsonOutput) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "launch",
+          adapter,
+          platform: profile.platformLabel(launch),
+          tier,
+          status: "pass",
+          phase: "launch",
+          recovered: state.recovered,
+          mutations: state.mutations,
+          metro: profile.evidence?.(target),
+          remoteFeatureFlags: remoteFlags,
+          exitCode: EXIT.ok
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    const tierNote = tier === "quick" ? "quick relaunch, no native build" : tier;
+    const devNote = process.env.MM_HARNESS_BIN ? ` ${color("dim", "[dev: MM_HARNESS_BIN]")}` : "";
+    console.error(
+      `${color("ok", "\u2713")} launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} \u2014 ${color("ok", profile.deviceLabel(launch))} \xB7 ${tierNote} \xB7 app + bridge ready${devNote}`
+    );
+  }
+  return EXIT.ok;
+}
+function launchFail(launch, profile, state, failure) {
+  const { adapter, mobileTarget, target, stream, tier } = launch;
+  const userAction = failure.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+  if (stream.enabled) {
+    for (const mutation of state.mutations) stream.mutation(mutation);
+    for (const recovery of state.recovered) stream.recovery(recovery);
+    stream.error({
+      code: failure.code,
+      message: failure.message,
+      retryable: failure.recoverable,
+      userAction,
+      originalError: failure.originalError ?? null
+    });
+    stream.complete("fail", failure.exitCode, {
+      adapter,
+      platform: mobileTarget ?? null,
+      tier,
+      recovered: state.recovered,
+      mutations: state.mutations,
+      recoverable: failure.recoverable,
+      attemptedRecoveries: state.attemptedRecoveries,
+      metro: profile.evidence?.(target)
+    });
+  } else if (launch.jsonOutput) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "launch",
+          adapter,
+          platform: mobileTarget ?? null,
+          tier,
+          status: "fail",
+          phase: state.attemptedRecoveries.length ? "recover" : "launch",
+          recovered: state.recovered,
+          mutations: state.mutations,
+          recoverable: failure.recoverable,
+          attemptedRecoveries: state.attemptedRecoveries,
+          metro: profile.evidence?.(target),
+          exitCode: failure.exitCode,
+          error: {
+            code: failure.code,
+            message: failure.message,
+            retryable: failure.recoverable,
+            userAction,
+            originalError: failure.originalError ?? null
+          }
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(colorHumanMessage(
+      `\u2717 launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed
+  ${failure.message}` + (failure.originalError ? `
+  --- original failure ---
+${failure.originalError}` : "") + `
+  Next: ${userAction}`
+    ));
+  }
+  return failure.exitCode;
+}
+export {
+  runDeviceLaunch
+};