@deeeed/metamask-harness 0.41.0 → 0.42.0

package/dist/adapters.js

@@ -12,6 +12,7 @@ import { observeNativeUi } from "../library/actions/mobile/platform/observe-ui.m
 import { nativeAgentDeviceStateDir } from "../library/actions/mobile/platform/native-session-name.mjs";
 import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 import { resolveWalletImportCredentials, validateWalletImportOptions } from "../library/actions/shared/wallet/import-source.mjs";
+import { handleRunNetworkAction } from "./network-observation.js";
 const execFileAsync = promisify(execFile);
 const NATIVE_PROVIDER_UI_ACTIONS = /* @__PURE__ */ new Set([
   "ui.press",
@@ -103,7 +104,11 @@ const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state"
 ]);
-const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set(["ui.navigate"]);
+const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.navigate",
+  "app.network_capture",
+  "app.network_assert"
+]);
 function requiresLiveAdapter(platform, action) {
   return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
 }
@@ -140,6 +145,13 @@ function liveAdapterPathHint(platform, action) {
   return `library/actions/${platform}/${action.replaceAll(".", "/")}.mjs`;
 }
 async function semanticResult(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
+  const networkAction = await handleRunNetworkAction(
+    platform,
+    action,
+    node,
+    context
+  );
+  if (networkAction) return networkAction;
   const live = await runLiveFirst(
     platform,
     action,
@@ -253,6 +265,7 @@ function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], pr
   ];
   const bundledActions = [
     ...walletActions,
+    ...platform !== "core" ? ["app.network_capture", "app.network_assert"] : [],
     "metamask.assets.read_visible_state",
     "metamask.assets.open_details",
     "metamask.assets.read_details",

package/dist/cli-commands.js

@@ -15,6 +15,7 @@ const SPEC = {
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", 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"] },
     { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/reset/generate)", args: ["sync", "set", "reset", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--matrix", "--categories", "--category", "--action", "--library"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
@@ -31,10 +32,11 @@ const SPEC = {
     { name: "ready", aliases: ["ensure-ready"], desc: "Ensure one healthy extension home tab" },
     { name: "watch", aliases: ["start-watch", "watcher"], desc: "Start/reuse webpack watcher", flags: ["--full", "-f"] },
     { name: "stop", aliases: ["stop-watch", "stop-watcher"], desc: "Stop this checkout watcher" },
-    { name: "rebuild", aliases: ["reset", "reopen", "reload", "browser", "launch", "full-launch", "runtime-launch", "build", "build:once", "build-once", "refresh-once"], desc: "Clean webpack + browser launch", flags: ["--json", "--dry-run", "--full"] },
+    { name: "rebuild", aliases: ["reset", "reopen", "browser", "launch", "full-launch", "runtime-launch", "build", "build:once", "build-once", "refresh-once"], desc: "Clean webpack + browser launch", flags: ["--json", "--dry-run", "--full"] },
     { name: "sidepanel", desc: "Side panel helper", args: ["cycle", "open", "close", "toggle", "status"] },
     { name: "prepare", flags: ["--target", "--cdp-port", "--runtime-dir", "--validate"] },
-    { name: "debug", args: ["page", "worker"], flags: ["--json", "--no-open"] }
+    { name: "debug", args: ["page", "worker"], flags: ["--json", "--no-open"] },
+    { name: "reload", desc: "Reload the live Extension UI over CDP", flags: ["--json"] }
   ],
   mobile: [
     { name: "ios", aliases: ["start"], desc: "Start Metro + launch iOS dev client" },
@@ -53,7 +55,8 @@ const SPEC = {
     { name: "screenshot", desc: "Capture simulator/device screenshot", args: ["path"] },
     { name: "dev-menu", aliases: ["devmenu"], desc: "Open RN developer menu", flags: ["--json", "--no-open"] },
     { name: "prepare", flags: ["--target", "--platform", "--preflight-mode", "--port", "--simulator", "--adb-serial", "--runtime-dir", "--wallet-setup", "--wallet-fixture"] },
-    { name: "debug", flags: ["--json", "--no-open", "--action"] }
+    { name: "debug", flags: ["--json", "--no-open", "--action"] },
+    { name: "reload", desc: "Reload the app without restarting Metro", flags: ["--json"] }
   ]
 };
 const GLOBAL_FLAGS = ["--json", "--dry-run", "--full", "-f", "--help", "-h", "--no-open", "--no-color"];

package/dist/cli.js

@@ -15,6 +15,7 @@ import { handleCompletionCandidates, invalidateCompletionCache } from "./command
 import { handleLaunch } from "./commands/launch/index.js";
 import { handleLogs } from "./commands/logs.js";
 import { handleDebug } from "./commands/debug.js";
+import { handleReload } from "./commands/reload.js";
 import { handleFixtures } from "./commands/fixtures.js";
 import { handleRecipeQuality } from "./commands/recipe-quality.js";
 import { handleStatus } from "./commands/status.js";
@@ -47,6 +48,8 @@ DAILY LOOP \u2014 what a teammate runs many times a day:
                mm-harness logs
   debug      Open the debug console (extension DevTools / mobile RN).
                mm-harness debug
+  reload     Reload the connected Mobile or Extension runtime.
+               mm-harness reload
   fixtures   Sync files, set/reset the wallet, generate fixture-state, or finalize labels over CDP.
                mm-harness fixtures sync                 # or: set | reset | generate --fixture <f> --out <o> | finalize \u2026
 
@@ -118,6 +121,7 @@ async function main(argv) {
   if (command === "stop") return handleStop(argv.slice(1));
   if (command === "logs") return handleLogs(argv.slice(1));
   if (command === "debug") return handleDebug(argv.slice(1));
+  if (command === "reload") return handleReload(argv.slice(1));
   if (command === "fixtures") return handleFixtures(argv.slice(1));
   if (command === "recipe-quality") return handleRecipeQuality(argv.slice(1));
   if (command === "check") return handleCheck(argv.slice(1));

package/dist/command-contract.js

@@ -278,6 +278,9 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--no-open": bool()
     })
   },
+  reload: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM)
+  },
   update: {
     options: options(HELP, JSON, { "--check": bool() })
   },

package/dist/commands/call.js

@@ -43,6 +43,9 @@ import {
 import { readMobileReleaseArtifactState } from "../adapters/mobile/release-artifact-state.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
+import {
+  startRunNetworkObservation
+} from "../network-observation.js";
 import { recipeTrustFailure } from "../recipe-security.js";
 import { isSensitiveKey, recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
 import { closest } from "../command-contract.js";
@@ -209,12 +212,14 @@ async function handleCall(argv) {
   recordCommandEvidence(artifactsDir);
   const requestedRuntimeOptions = runtimeOptionsFromCli(options);
   const inheritedSource = process.env.FARMSLOT_RECIPE_SOURCE_TRUST || process.env.FARMSLOT_RECIPE_SOURCE_KIND || process.env.FARMSLOT_RECIPE_SOURCE_NAME || process.env.FARMSLOT_RECIPE_SOURCE_DIGEST;
+  let networkObservation;
   const callRuntimeOptions = {
     ...requestedRuntimeOptions,
     ...librarySources ? { librarySources } : {},
     autoHud: false,
     suppressLibraryResolutionLogs: true,
     stdoutIsMachineContract: json,
+    onActionEvent: ({ nodeId, action, status }) => networkObservation?.onActionEvent({ nodeId, action, status }),
     ...requestedRuntimeOptions.source ? { source: requestedRuntimeOptions.source } : inheritedSource ? {} : {
       source: {
         kind: "operator",
@@ -275,29 +280,49 @@ async function handleCall(argv) {
     });
     if (typeof prepared === "number") return prepared;
     const { state, heal } = prepared;
-    const { result, violation } = await executeWithHealBounds(
-      () => {
-        const execution = preflightedExecution;
-        preflightedExecution = void 0;
-        return runRecipe(
-          adapter,
-          recipe,
-          artifactsDir,
-          target,
-          actionManifestOverride,
-          callRuntimeOptions,
-          execution
-        );
-      },
+    networkObservation = await startRunNetworkObservation(
       adapter,
       target,
-      heal,
-      state,
-      () => recoverRunInfra(adapter, target, json, {
-        cdpPort: optionString(options, "cdpPort"),
-        watcherPort: optionString(options, "watcherPort") ?? optionString(options, "metroPort")
-      })
+      artifactsDir,
+      process.env,
+      {
+        cdpPort: callRuntimeOptions.cdpPort,
+        watcherPort: callRuntimeOptions.watcherPort
+      }
     );
+    let executionResult;
+    try {
+      executionResult = await executeWithHealBounds(
+        () => {
+          const execution = preflightedExecution;
+          preflightedExecution = void 0;
+          return runRecipe(
+            adapter,
+            recipe,
+            artifactsDir,
+            target,
+            actionManifestOverride,
+            callRuntimeOptions,
+            execution
+          );
+        },
+        adapter,
+        target,
+        heal,
+        state,
+        () => recoverRunInfra(adapter, target, json, {
+          cdpPort: optionString(options, "cdpPort"),
+          watcherPort: optionString(options, "watcherPort") ?? optionString(options, "metroPort")
+        })
+      );
+    } catch (error) {
+      await networkObservation?.finalize();
+      networkObservation = void 0;
+      throw error;
+    }
+    const { result, violation } = executionResult;
+    await networkObservation?.finalize(result.artifactManifestPath);
+    networkObservation = void 0;
     if (violation !== null) {
       const conciseFailure = violation.originalError ? conciseFailureForHuman(violation.originalError) : "";
       const example = describedAction ? actionExampleCommand(

package/dist/commands/launch/index.js

@@ -53,6 +53,21 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "jsonStream"
 ]);
 const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
+function metroLaunchEvidence(adapter, target) {
+  if (adapter !== "mobile") return void 0;
+  const evidencePath = recipeRuntimePath(target, "metro-generation.json");
+  let descriptor;
+  try {
+    descriptor = fs.openSync(evidencePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > 256 * 1024) return void 0;
+    return JSON.parse(fs.readFileSync(descriptor, "utf8"));
+  } catch {
+    return void 0;
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+  }
+}
 async function handleLaunch(argv) {
   const { options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
@@ -627,14 +642,15 @@ async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget,
         platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
         tier,
         recovered: state.recovered,
-        mutations: state.mutations
+        mutations: state.mutations,
+        metro: metroLaunchEvidence(adapter, target)
       });
     }
     return exitCode;
   }
-  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, state);
+  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, target, state);
 }
-function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, state) {
+function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, target, state) {
   if (stream.enabled) {
     for (const mutation of state.mutations) stream.mutation(mutation);
     for (const recovery of state.recovered) stream.recovery(recovery);
@@ -643,7 +659,8 @@ function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, stat
       platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
       tier,
       recovered: state.recovered,
-      mutations: state.mutations
+      mutations: state.mutations,
+      metro: metroLaunchEvidence(adapter, target)
     });
   } else if (json) {
     console.log(
@@ -658,6 +675,7 @@ function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, stat
           phase: "launch",
           recovered: state.recovered,
           mutations: state.mutations,
+          metro: metroLaunchEvidence(adapter, target),
           exitCode: EXIT.ok
         },
         null,
@@ -706,7 +724,8 @@ function launchFail(json, stream, adapter, mobileTarget, tier, state, target, fa
       recovered: state.recovered,
       mutations: state.mutations,
       recoverable: failure.recoverable,
-      attemptedRecoveries: state.attemptedRecoveries
+      attemptedRecoveries: state.attemptedRecoveries,
+      metro: metroLaunchEvidence(adapter, target)
     });
   } else if (json) {
     console.log(
@@ -723,6 +742,7 @@ function launchFail(json, stream, adapter, mobileTarget, tier, state, target, fa
           mutations: state.mutations,
           recoverable: failure.recoverable,
           attemptedRecoveries: state.attemptedRecoveries,
+          metro: metroLaunchEvidence(adapter, target),
           exitCode: failure.exitCode,
           error: {
             code: failure.code,

package/dist/commands/reload.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { runnerDir } from "../paths.js";
+import { getAdapterSurface } from "../adapters/surface.js";
+import {
+  ADAPTER_DETECT_NEXT,
+  EXIT,
+  flag,
+  parseFlags,
+  resolveAdapter,
+  spawnScript,
+  targetOf,
+  usageOut
+} from "./shared.js";
+const RELOAD_BOOLEANS = /* @__PURE__ */ new Set(["json"]);
+async function handleReload(argv) {
+  const { options } = parseFlags(argv, RELOAD_BOOLEANS);
+  const json = flag(options, "json");
+  const target = targetOf(options);
+  const adapter = resolveAdapter(options, target);
+  if (!adapter) {
+    return usageOut(
+      json,
+      "reload",
+      `could not detect the MetaMask repo type for ${target}`,
+      ADAPTER_DETECT_NEXT
+    );
+  }
+  if (adapter === "core") {
+    return usageOut(
+      json,
+      "reload",
+      "core is headless; there is no app runtime to reload.",
+      "mm-harness run <core-recipe>"
+    );
+  }
+  getAdapterSurface(adapter).resolveSlotPorts(target);
+  if (adapter === "extension") {
+    if (!process.env.CDP_PORT) {
+      return usageOut(
+        json,
+        "reload",
+        "the Extension CDP port could not be resolved.",
+        "mm-harness launch"
+      );
+    }
+    const script2 = path.join(runnerDir, "adapters/extension/reattach.sh");
+    const args2 = ["--target", target, "--cdp-port", process.env.CDP_PORT];
+    if (process.env.WATCHER_PORT) {
+      args2.push("--watcher-port", process.env.WATCHER_PORT);
+    }
+    const result2 = spawnScript(script2, args2, target, json);
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: result2.status === 0,
+            adapter,
+            method: "cdp-reattach",
+            command: "reload",
+            cdpPort: Number(process.env.CDP_PORT),
+            ...result2.status === 0 ? {} : { error: result2.output.slice(-4e3) || "Extension reload failed." }
+          },
+          null,
+          2
+        )
+      );
+    }
+    return result2.status === 0 ? EXIT.ok : EXIT.runtime;
+  }
+  const script = path.join(runnerDir, "adapters/mobile/reload-app.mjs");
+  const args = [];
+  if (process.env.WATCHER_PORT) args.push("--port", process.env.WATCHER_PORT);
+  if (json) args.push("--json");
+  const result = spawnScript(process.execPath, [script, ...args], target, json);
+  if (json) process.stdout.write(result.output);
+  return result.status === 0 ? EXIT.ok : EXIT.runtime;
+}
+export {
+  handleReload
+};

package/dist/commands/run.js

@@ -41,6 +41,9 @@ import {
   missingActionCapabilities,
   resolveActionCapabilityMatrix
 } from "./manifest.js";
+import {
+  startRunNetworkObservation
+} from "../network-observation.js";
 async function validationCapabilityRefusals(adapter, findings, librarySources) {
   const actionNames = findings.flatMap((finding) => {
     if (finding.code !== "recipe.action_not_declared_by_manifest") return [];
@@ -227,12 +230,16 @@ async function handleRunInner({ positional, options }, stream) {
   }
   recordCommandEvidence(artifactsDir);
   const librarySources = validated.librarySources;
+  let networkObservation;
   const runtimeOptions = {
     ...runtimeOptionsFromCli(options),
     params,
     ...librarySources ? { librarySources } : {},
     stdoutIsMachineContract: machine,
-    onActionEvent: ({ nodeId, action, status }) => stream.node(nodeId, action, status)
+    onActionEvent: ({ nodeId, action, status }) => {
+      stream.node(nodeId, action, status);
+      networkObservation?.onActionEvent({ nodeId, action, status });
+    }
   };
   stream.phase("authorize");
   let preflightedExecution = await preflightRecipe(
@@ -263,30 +270,50 @@ async function handleRunInner({ positional, options }, stream) {
       return prepared;
     }
     const { state, heal } = prepared;
-    stream.phase("execute");
-    const { result, violation } = await executeWithHealBounds(
-      // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
-      // that only the resolver knows how to turn into a file.
-      () => {
-        const execution = preflightedExecution;
-        preflightedExecution = void 0;
-        return runRecipe(
-          adapter,
-          validated.recipeFile,
-          artifactsDir,
-          target,
-          optionString(options, "actionManifest"),
-          runtimeOptions,
-          execution
-        );
-      },
+    networkObservation = await startRunNetworkObservation(
       adapter,
       target,
-      heal,
-      state,
-      () => recoverRunInfra(adapter, target, machine, runtimeOptions),
-      (code) => stream.phase("recover", { code })
+      artifactsDir,
+      process.env,
+      {
+        cdpPort: runtimeOptions.cdpPort,
+        watcherPort: runtimeOptions.watcherPort
+      }
     );
+    stream.phase("execute");
+    let executionResult;
+    try {
+      executionResult = await executeWithHealBounds(
+        // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
+        // that only the resolver knows how to turn into a file.
+        () => {
+          const execution = preflightedExecution;
+          preflightedExecution = void 0;
+          return runRecipe(
+            adapter,
+            validated.recipeFile,
+            artifactsDir,
+            target,
+            optionString(options, "actionManifest"),
+            runtimeOptions,
+            execution
+          );
+        },
+        adapter,
+        target,
+        heal,
+        state,
+        () => recoverRunInfra(adapter, target, machine, runtimeOptions),
+        (code) => stream.phase("recover", { code })
+      );
+    } catch (error) {
+      await networkObservation?.finalize();
+      networkObservation = void 0;
+      throw error;
+    }
+    const { result, violation } = executionResult;
+    await networkObservation?.finalize(result.artifactManifestPath);
+    networkObservation = void 0;
     for (const mutation of state.mutations) stream.mutation(mutation);
     for (const recovery of state.recovered) stream.recovery(recovery);
     if (violation !== null) {

package/dist/mm-harness-cli.js

@@ -524,6 +524,22 @@ Example:
   mm-harness debug
   mm-harness debug --worker`
   },
+  {
+    name: "reload",
+    summary: "Reload the connected Mobile or Extension runtime without restarting its dev server.",
+    example: "mm-harness reload",
+    helpText: `mm-harness reload [flags]
+
+  Mobile broadcasts the same reload command as Metro's interactive r key.
+  Extension refreshes its loaded UI in place over CDP. Core is headless.
+
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness reload`
+  },
   {
     name: "update",
     summary: "Update the installed mm-harness to the published latest (--check reports only; --json = {current, latest, updateAvailable}).",
@@ -648,7 +664,7 @@ const HELP_GROUPS = [
   {
     title: "DAILY LOOP",
     blurb: "what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)",
-    commands: ["status", "launch", "stop", "logs", "debug", "fixtures"]
+    commands: ["status", "launch", "stop", "logs", "debug", "reload", "fixtures"]
   },
   {
     title: "DISCOVER",