@deeeed/metamask-harness 0.73.0 → 0.75.0

package/dist/runner.js

@@ -1,27 +1,10 @@
-import { execFileSync, execSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
-import { createAndroidMirrorVideoRecorder } from "@farmslot/recipe-harness";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
-import {
-  bridgeCommand,
-  MOBILE_BRIDGE_ERROR_CODES
-} from "../library/actions/mobile/platform/bridge.mjs";
-import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
-import {
-  mobileSourceFingerprint,
-  recordMobileSourceBaseline
-} from "./adapters/mobile/source-freshness.js";
-import { readAndroidNativeRuntimeIdentity } from "./adapters/mobile/release-artifact.js";
-import { readMobileReleaseArtifactState } from "./adapters/mobile/release-artifact-state.js";
-import {
-  createAndroidVideoRecorder,
-  createIosSimulatorVideoRecorder
-} from "./adapters/mobile/video-recorder.js";
+import { getAdapterSurface } from "./adapters/surface.js";
 import {
   bindMetaMaskMobileLifecycleDeadline,
   createMetaMaskMobileLifecycleCommandRunner,
-  MOBILE_LIFECYCLE_DEADLINE_FIELD,
-  MOBILE_LIFECYCLE_PREPARED,
   resolveMetaMaskMobileLifecycleTarget
 } from "./app-lifecycle.js";
 import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
@@ -29,11 +12,7 @@ import { actionSourceIntegrity, metaMaskActionExecutionCapabilities } from "./re
 import {
   prepareLiveAdapterScript
 } from "./live-adapter-contract.js";
-import {
-  createMetaMaskRecordingTargetProvider,
-  resolveAndroidDeviceSerial,
-  resolveMobileIosSimulatorName
-} from "./recording-target.js";
+import { createMetaMaskRecordingTargetProvider } from "./recording-target.js";
 import {
   importMetaMaskNativeUiProvider,
   importRecipeHarness,
@@ -92,16 +71,15 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     }, preparedLiveAdapters, { hudPolicy: options.autoHud === true ? "show" : "auto" })
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
-  const lifecycle = mobileSourceAwareLifecycleAdapters(
-    adapter,
-    bindMetaMaskMobileLifecycleDeadline(
-      createAppLifecycleAdapters({
-        actions,
-        commandRunner: createMetaMaskMobileLifecycleCommandRunner(),
-        targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
-      })
-    )
+  const surface = getAdapterSurface(adapter);
+  const lifecycleAdapters = bindMetaMaskMobileLifecycleDeadline(
+    createAppLifecycleAdapters({
+      actions,
+      commandRunner: createMetaMaskMobileLifecycleCommandRunner(),
+      targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
+    })
   );
+  const lifecycle = surface.actions.lifecycle ? await surface.actions.lifecycle(lifecycleAdapters) : lifecycleAdapters;
   const custom = createMetaMaskAdapters(
     adapter,
     customActions,
@@ -117,31 +95,22 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     options.quietStdout ? new console.Console(process.stderr) : console,
     options.suppressLibraryResolutionLogs
   );
-  const androidRecordingSerial = adapter === "mobile" ? resolveAndroidDeviceSerial() : void 0;
-  const iosRecordingSimulator = adapter === "mobile" && !androidRecordingSerial ? resolveMobileIosSimulatorName() : void 0;
+  const videoRecorder = await surface.recording?.videoRecorder?.();
+  const secured = [...core, ...ui, ...lifecycle, ...custom].map((entry) => ({
+    ...entry,
+    ...adapterSecurity(entry.action, actionSources, options.trustTaskActions)
+  }));
+  const mutationBound = surface.actions.trustedMutation ? withTrustedMutationContext(secured, options.trustedMutation, externalMutationActions) : secured;
   return createRecipeRunner({
     actionManifest,
     adapters: withActionProgress(
-      withMobileNativeRuntimeIdentity(
-        adapter,
-        withTrustedMutationContext(
-          [...core, ...ui, ...lifecycle, ...custom].map((entry) => ({
-            ...entry,
-            ...adapterSecurity(entry.action, actionSources, options.trustTaskActions)
-          })),
-          options.trustedMutation,
-          externalMutationActions,
-          adapter
-        )
-      ),
+      surface.actions.wrap ? await surface.actions.wrap(mutationBound) : mutationBound,
       options.onActionEvent
     ),
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter),
-      ...androidRecordingSerial ? { videoRecorder: createAndroidMirrorVideoRecorder({ serial: androidRecordingSerial, fallback: createAndroidVideoRecorder(androidRecordingSerial) }) } : iosRecordingSimulator ? {
-        videoRecorder: createIosSimulatorVideoRecorder(iosRecordingSimulator)
-      } : {}
+      ...videoRecorder ? { videoRecorder } : {}
     },
     runner: runnerProvenance(),
     defaultSource: {
@@ -161,38 +130,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     }
   });
 }
-function withMobileNativeRuntimeIdentity(adapter, adapters, identity = {
-  state: readMobileReleaseArtifactState,
-  read: readAndroidNativeRuntimeIdentity
-}) {
-  if (adapter !== "mobile") return adapters;
-  return adapters.map((entry) => ({
-    ...entry,
-    async execute(node, context) {
-      const state = identity.state(context.projectRoot);
-      if (!state) {
-        if (context.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1") {
-          throw new Error("Mobile release-artifact actions require current trusted runtime state. Next: rerun runtime-launch with the exact artifact.");
-        }
-        return entry.execute(node, context);
-      }
-      identity.read(state);
-      const result = await entry.execute(node, context);
-      const nativeRuntimeIdentity = identity.read(state);
-      const output = result.output && typeof result.output === "object" && !Array.isArray(result.output) ? result.output : { result: result.output };
-      return {
-        ...result,
-        output: {
-          ...output,
-          nativeRuntimeIdentity,
-          runtimeSessionId: nativeRuntimeIdentity.runtimeSessionId
-        }
-      };
-    }
-  }));
-}
-function withTrustedMutationContext(adapters, base, externalMutationActions, adapter = "extension") {
-  if (adapter !== "extension") return adapters;
+function withTrustedMutationContext(adapters, base, externalMutationActions) {
   let selectedIdentitySha256;
   const identityProofAction = "metamask.wallet.import";
   const identityInvalidatingActions = /* @__PURE__ */ new Set([
@@ -353,289 +291,6 @@ function isAutomaticHudProgress(action, node, nodeId) {
   const progress = payload.progress;
   return nodeId === "recipe-complete" && progress !== null && typeof progress === "object" && !Array.isArray(progress) && progress.complete === true;
 }
-function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe = probeMobileLifecycleRuntime, sourceFreshness = {
-  fingerprint: mobileSourceFingerprint,
-  record: recordMobileSourceBaseline
-}, processIdentity = {
-  readIosPid: readIosAppPid,
-  readAndroidPid: readAndroidAppPid
-}, runtimeMarker = readMobileLifecycleRuntimeIdentity) {
-  if (adapter !== "mobile") return lifecycle;
-  return lifecycle.map((entry) => ({
-    ...entry,
-    async execute(node, context) {
-      const command = node.command ?? node.event ?? node.state;
-      const opaqueRuntime = context.env?.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME === "1";
-      const requiresProcessContinuity = command !== "restart" && node.require_process_continuity === true;
-      if (opaqueRuntime && !requiresProcessContinuity) {
-        return entry.execute(node, context);
-      }
-      const reloadsSource = !opaqueRuntime && (command === "launch" || command === "foreground" || command === "restart");
-      const recordsSource = !opaqueRuntime && command === "restart";
-      const androidLifecycle = isAndroidLifecycle(node, context.env ?? {});
-      const checksIosContinuity = command === "foreground" && !androidLifecycle;
-      const checksRequiredContinuity = requiresProcessContinuity;
-      const recordsProcessIdentity = checksIosContinuity || checksRequiredContinuity;
-      const readProcessId = androidLifecycle ? processIdentity.readAndroidPid ?? readAndroidAppPid : processIdentity.readIosPid;
-      const processBefore = recordsProcessIdentity ? readProcessId(node, context) : void 0;
-      const fingerprint = recordsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
-      const previousRuntimeIdentity = recordsSource ? await runtimeMarker(node, context) : void 0;
-      const androidRestart = command === "restart" && androidLifecycle;
-      const initialResult = await entry.execute(node, context);
-      const readinessDeadline = reloadsSource ? mobileLifecycleReadinessDeadline(command, node) : void 0;
-      let result = initialResult;
-      let runtimeReady = false;
-      if (androidRestart) {
-        try {
-          const remainingMs = Math.max(
-            1,
-            (readinessDeadline ?? Date.now()) - Date.now()
-          );
-          const handoffDeadline = Math.min(
-            readinessDeadline ?? Number.POSITIVE_INFINITY,
-            Date.now() + Math.min(1e4, Math.max(1, remainingMs / 2))
-          );
-          await readinessProbe(
-            node,
-            context,
-            previousRuntimeIdentity,
-            handoffDeadline
-          );
-          runtimeReady = true;
-        } catch (error) {
-          if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
-            throw error;
-          }
-          const foregroundTimeoutMs = Math.max(
-            1,
-            (readinessDeadline ?? Date.now() + 1) - Date.now()
-          );
-          const foregroundResult = await entry.execute(
-            {
-              ...node,
-              command: "foreground",
-              settle_ms: 0,
-              timeout_ms: foregroundTimeoutMs,
-              [MOBILE_LIFECYCLE_DEADLINE_FIELD]: readinessDeadline,
-              [MOBILE_LIFECYCLE_PREPARED]: true
-            },
-            context
-          );
-          result = mergeAndroidRestartResults(initialResult, foregroundResult);
-        }
-      }
-      if (reloadsSource && !runtimeReady) {
-        if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
-          throw new Error(
-            `Mobile lifecycle ${String(command)} exhausted its runtime readiness deadline before recovery completed.`
-          );
-        }
-        await readinessProbe(
-          node,
-          context,
-          previousRuntimeIdentity,
-          readinessDeadline
-        );
-      }
-      if (recordsProcessIdentity) {
-        const processAfter = readProcessId(node, context);
-        const processPreserved = processBefore !== null && processBefore === processAfter;
-        const actualTransition = processPreserved ? command === "background" ? "background_same_process" : "foreground_resume" : processAfter !== null ? "cold_relaunch" : "unknown";
-        const processContinuity = processPreserved ? "preserved" : processAfter === null ? "unknown" : "changed";
-        const resultRecord = asRecord(result);
-        result = {
-          ...resultRecord,
-          output: {
-            ...asRecord(resultRecord.output),
-            actualTransition,
-            processContinuity,
-            processBefore,
-            processAfter
-          }
-        };
-        if (checksRequiredContinuity && !processPreserved) {
-          const platform = androidLifecycle ? "Android" : "iOS";
-          throw new Error(
-            `${platform} ${String(command)} did not prove app-process continuity (actualTransition=${actualTransition}, before=${String(processBefore)}, after=${String(processAfter)}); this lifecycle sample cannot be classified as a same-process reconnect.`
-          );
-        }
-      }
-      if (fingerprint !== void 0 && !sourceFreshness.record(context.projectRoot, fingerprint)) {
-        throw new Error(
-          "Mobile source changed while the app was reloading; the loaded-source baseline was not recorded. Next: retry app.lifecycle restart."
-        );
-      }
-      return result;
-    }
-  }));
-}
-function readAndroidAppPid(node, context) {
-  const env = context.env ?? {};
-  const device = node.adb_serial ?? node.android_device ?? node.device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL;
-  const packageId = node.package_id ?? node.packageName ?? node.app_id ?? env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask";
-  if (typeof device !== "string" || typeof packageId !== "string") return null;
-  try {
-    const adb = resolveMobileToolPath("adb", { required: true });
-    const output = execFileSync(
-      adb,
-      ["-s", device, "shell", "pidof", packageId],
-      { encoding: "utf8", timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }
-    );
-    const pid = Number.parseInt(output.trim().split(/\s+/u)[0] ?? "", 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
-  }
-}
-function readIosAppPid(node, context) {
-  const env = context.env ?? {};
-  const device = node.simulator ?? node.ios_simulator ?? env.SIM_UDID ?? env.IOS_SIMULATOR ?? process.env.SIM_UDID ?? process.env.IOS_SIMULATOR;
-  const bundleId = node.bundle_id ?? node.bundleId ?? env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask";
-  if (typeof device !== "string" || typeof bundleId !== "string") return null;
-  try {
-    const output = execFileSync(
-      "xcrun",
-      ["simctl", "spawn", device, "launchctl", "list"],
-      { encoding: "utf8", timeout: 5e3 }
-    );
-    const labelPrefix = `UIKitApplication:${bundleId}[`;
-    const line = output.split("\n").find((candidate) => candidate.includes(labelPrefix));
-    if (!line) return null;
-    const pid = Number.parseInt(line.trim().split(/\s+/u)[0] ?? "", 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
-  }
-}
-function isAndroidLifecycle(node, env) {
-  const platform = node.platform ?? env.PLATFORM ?? process.env.PLATFORM;
-  if (platform === "android") return true;
-  if (platform === "ios") return false;
-  return Boolean(
-    node.adb_serial ?? node.android_device ?? env.ADB_SERIAL ?? env.ANDROID_SERIAL ?? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL
-  );
-}
-function mergeAndroidRestartResults(initialResult, foregroundResult) {
-  const initial = asRecord(initialResult);
-  const foreground = asRecord(foregroundResult);
-  const initialOutput = asRecord(initial.output);
-  const foregroundOutput = asRecord(foreground.output);
-  return {
-    ...initial,
-    output: {
-      ...initialOutput,
-      command: "restart",
-      calls: [
-        ...Array.isArray(initialOutput.calls) ? initialOutput.calls : [],
-        ...Array.isArray(foregroundOutput.calls) ? foregroundOutput.calls : []
-      ],
-      settleMs: foregroundOutput.settleMs ?? initialOutput.settleMs ?? 0,
-      foregroundEnsured: true
-    }
-  };
-}
-async function probeMobileLifecycleRuntime(node, context, previousRuntimeIdentity, deadlineMs) {
-  const command = node.command ?? node.event ?? node.state;
-  const timeoutMs = resolveMobileLifecycleReadinessTimeout(
-    command,
-    node.runtime_ready_timeout_ms
-  );
-  const startedAt = Date.now();
-  const deadline = deadlineMs ?? startedAt + timeoutMs;
-  let lastError;
-  while (Date.now() < deadline) {
-    try {
-      const status = await bridgeCommand(
-        {
-          action: "app.lifecycle",
-          node: {
-            ...node,
-            cdp_timeout_ms: Math.min(8e3, Math.max(1, deadline - Date.now()))
-          },
-          context
-        },
-        ["status-selected"]
-      );
-      if (status?.agenticPresent === true && status.route && (!previousRuntimeIdentity || status.runtimeIdentity !== previousRuntimeIdentity)) {
-        return status;
-      }
-      lastError = new Error(
-        previousRuntimeIdentity && status?.runtimeIdentity === previousRuntimeIdentity ? "retiring Mobile runtime is still selected" : "selected Mobile runtime is not ready"
-      );
-    } catch (error) {
-      lastError = error;
-    }
-    const remainingMs = deadline - Date.now();
-    if (remainingMs > 0) {
-      await new Promise(
-        (resolve) => setTimeout(resolve, Math.min(1e3, remainingMs))
-      );
-    }
-  }
-  throw new Error(
-    `Mobile lifecycle ${String(command)} did not expose a usable pinned __AGENTIC__ runtime within ${Math.max(0, deadline - startedAt)}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`
-  );
-}
-async function readMobileLifecycleRuntimeIdentity(node, context) {
-  const deadline = Date.now() + 5e3;
-  let lastError;
-  do {
-    try {
-      const status = await bridgeCommand(
-        {
-          action: "app.lifecycle",
-          node: {
-            ...node,
-            cdp_timeout_ms: Math.min(1e3, Math.max(1, deadline - Date.now()))
-          },
-          context
-        },
-        ["target-identity-selected"]
-      );
-      if (typeof status?.runtimeIdentity === "string") {
-        return status.runtimeIdentity;
-      }
-      lastError = new Error("selected Mobile runtime has no stable identity");
-    } catch (error) {
-      if (error instanceof Error && "code" in error && error.code === MOBILE_BRIDGE_ERROR_CODES.NO_TARGET) {
-        return void 0;
-      }
-      lastError = error;
-    }
-    const remainingMs = deadline - Date.now();
-    if (remainingMs <= 0) {
-      break;
-    }
-    await new Promise(
-      (resolve) => setTimeout(resolve, Math.min(250, remainingMs))
-    );
-  } while (Date.now() < deadline);
-  throw new Error(
-    `Mobile lifecycle restart could not identify the retiring runtime: ${lastError instanceof Error ? lastError.message : String(lastError)}`
-  );
-}
-function mobileLifecycleReadinessDeadline(command, node) {
-  const timeoutMs = resolveMobileLifecycleReadinessTimeout(
-    command,
-    node.runtime_ready_timeout_ms
-  );
-  return Date.now() + timeoutMs;
-}
-function resolveMobileLifecycleReadinessTimeout(command, value) {
-  if (value === void 0) {
-    return command === "launch" || command === "restart" || command === "foreground" ? 6e4 : 3e4;
-  }
-  const timeout = Number(value);
-  if (!Number.isInteger(timeout) || timeout < 1e3 || timeout > 12e4) {
-    throw new Error(
-      "app.lifecycle.runtime_ready_timeout_ms must be an integer from 1000 through 120000."
-    );
-  }
-  return timeout;
-}
-function asRecord(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
 function runnerProvenance() {
   return {
     source: runnerDir,
@@ -659,8 +314,5 @@ export {
   createMetaMaskMobileRunner,
   createMetaMaskRunner,
   isAutomaticHudProgress,
-  mobileSourceAwareLifecycleAdapters,
-  resolveMobileLifecycleReadinessTimeout,
-  withMobileNativeRuntimeIdentity,
   withTrustedMutationContext
 };

package/docs/CONTRIBUTING.md

@@ -61,9 +61,26 @@ exits.
 ## Adapter surface
 
 Commands resolve shared platform behavior through
-`src/adapters/surface.ts`. Extend `AdapterSurface` only when all platforms need
-the concept, implement all three adapters, and let Core report headless/N/A
-explicitly. Do not add command-local platform ladders for surface-owned behavior.
+`src/adapters/surface.ts`. Each platform's surface registers itself in
+`src/adapters/registry.ts` when its module loads. A platform registered the same
+way is reached by `launch`, by the `run`/`call` engine and by the runner's
+action set with no edit to shared code (`tests/fixtures/example-adapter.ts`).
+The CLI front door still validates `--adapter` against the four built-ins
+(`src/command-contract.ts`), and the other commands still branch on the name,
+so a new platform reaches `bin/mm-harness` only when those families move and a
+plugin loader registers it.
+
+Extend `AdapterSurface` when a platform owns the behavior; members a platform
+does not need are optional (`actions` is required: every platform has an
+action set), and Core reports headless/N/A explicitly. Put each platform's
+implementation under `src/adapters/<adapter>/` (`launch.ts`, `run.ts`,
+`actions.ts`). Do not add command-local platform ladders for surface-owned
+behavior: `launch` dispatches through `AdapterSurface.launch` (the device
+platforms share `src/commands/launch/device.ts` through a
+`DeviceLaunchProfile`), `run`/`call` read `run`, `recording`, `diagnostics`,
+`observation` and `sourceFingerprint`, and the runner reads `actions`
+(manifest, bundled semantic actions, live adapter scripts, `cdp.target`, the
+`ui.*` transport, adapter wrappers, input checks).
 
 Each checkout owns:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -45,6 +45,7 @@
     "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^9",
     "globals": "^17.7.0",
+    "proper-lockfile": "^4.1.2",
     "tsx": "^4.23.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8",

package/scripts/completions.sh

@@ -29,13 +29,14 @@ _mmh_bin() {
   return 1
 }
 
-_mmh_commands="launch stop logs debug reload fixtures actions call run doctor check checklist execution-template recipe-quality install verify cleanup completions"
+_mmh_commands="launch stop logs debug reload fixtures actions call run doctor check checklist execution-template recipe-quality install verify cleanup pin completions"
 
 # Per-command flags (static, from the mm-harness surface).
 _mmh_flags_for() {
   case "$1" in
     launch)   printf '%s' "--build --watch --verify --sidepanel --fullscreen --runway --device --cdp-port --watcher-port --heal --adapter --target --json" ;;
     stop)     printf '%s' "--port --target --json" ;;
+    pin)      printf '%s' "--json" ;;
     logs)     printf '%s' "--full --events --source --adapter --target --json" ;;
     debug)    printf '%s' "--worker --dev-menu --adapter --target --json" ;;
     reload)   printf '%s' "--adapter --platform --target --json" ;;