@deeeed/metamask-harness 0.41.1 → 0.43.0

package/dist/commands/call.js

@@ -43,6 +43,12 @@ 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 {
+  startRunPerformanceObservation
+} from "../performance-observation.js";
 import { recipeTrustFailure } from "../recipe-security.js";
 import { isSensitiveKey, recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
 import { closest } from "../command-contract.js";
@@ -209,12 +215,18 @@ 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;
+  let performanceObservation;
   const callRuntimeOptions = {
     ...requestedRuntimeOptions,
     ...librarySources ? { librarySources } : {},
     autoHud: false,
     suppressLibraryResolutionLogs: true,
     stdoutIsMachineContract: json,
+    onActionEvent: ({ nodeId, action, status }) => {
+      networkObservation?.onActionEvent({ nodeId, action, status });
+      performanceObservation?.onActionEvent({ nodeId, action, status });
+    },
     ...requestedRuntimeOptions.source ? { source: requestedRuntimeOptions.source } : inheritedSource ? {} : {
       source: {
         kind: "operator",
@@ -275,29 +287,63 @@ 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
+      }
     );
+    performanceObservation = startRunPerformanceObservation(
+      adapter,
+      target,
+      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().catch(() => void 0);
+      networkObservation = void 0;
+      await performanceObservation?.finalize().catch(() => void 0);
+      performanceObservation = void 0;
+      throw error;
+    }
+    const { result, violation } = executionResult;
+    await networkObservation?.finalize(result.artifactManifestPath);
+    networkObservation = void 0;
+    await performanceObservation?.finalize(result.artifactManifestPath);
+    performanceObservation = void 0;
     if (violation !== null) {
       const conciseFailure = violation.originalError ? conciseFailureForHuman(violation.originalError) : "";
       const example = describedAction ? actionExampleCommand(

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-engine.js

@@ -241,7 +241,24 @@ function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions)
   const previousAndroidPackageId = process.env.ANDROID_PACKAGE_ID;
   const previousAdbSerial = process.env.ADB_SERIAL;
   const previousAndroidSerial = process.env.ANDROID_SERIAL;
+  const explicitMobileDeviceEnv = adapter === "mobile" && process.env.MM_HARNESS_EXPLICIT_PLATFORM ? Object.fromEntries(
+    [
+      "PLATFORM",
+      "MM_HARNESS_EXPLICIT_PLATFORM",
+      "IOS_SIMULATOR",
+      "SIM_UDID",
+      "ADB_SERIAL",
+      "ANDROID_SERIAL",
+      "ANDROID_DEVICE",
+      "ANDROID_TARGET_DEVICE_NAME"
+    ].map((key) => [key, process.env[key]])
+  ) : void 0;
   getAdapterSurface(adapter).resolveSlotPorts(projectRoot);
+  if (explicitMobileDeviceEnv) {
+    for (const [key, value] of Object.entries(explicitMobileDeviceEnv)) {
+      restoreEnv(key, value);
+    }
+  }
   if (runtimeOptions.cdpPort) {
     process.env.CDP_PORT = runtimeOptions.cdpPort;
     process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
@@ -1362,6 +1379,7 @@ function countRecipeNodes(recipe) {
   return nodes ? Object.keys(nodes).length : void 0;
 }
 export {
+  activateRecipeRuntimeEnvironment,
   countRecipeNodes,
   describeRunnableRecipe,
   emitHealViolation,

package/dist/commands/run.js

@@ -41,6 +41,12 @@ import {
   missingActionCapabilities,
   resolveActionCapabilityMatrix
 } from "./manifest.js";
+import {
+  startRunNetworkObservation
+} from "../network-observation.js";
+import {
+  startRunPerformanceObservation
+} from "../performance-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 +233,18 @@ async function handleRunInner({ positional, options }, stream) {
   }
   recordCommandEvidence(artifactsDir);
   const librarySources = validated.librarySources;
+  let networkObservation;
+  let performanceObservation;
   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 });
+      performanceObservation?.onActionEvent({ nodeId, action, status });
+    }
   };
   stream.phase("authorize");
   let preflightedExecution = await preflightRecipe(
@@ -263,30 +275,64 @@ 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,
+      artifactsDir,
+      process.env,
+      {
+        cdpPort: runtimeOptions.cdpPort,
+        watcherPort: runtimeOptions.watcherPort
+      }
+    );
+    performanceObservation = startRunPerformanceObservation(
       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().catch(() => void 0);
+      networkObservation = void 0;
+      await performanceObservation?.finalize().catch(() => void 0);
+      performanceObservation = void 0;
+      throw error;
+    }
+    const { result, violation } = executionResult;
+    await networkObservation?.finalize(result.artifactManifestPath);
+    networkObservation = void 0;
+    await performanceObservation?.finalize(result.artifactManifestPath);
+    performanceObservation = 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",

package/dist/network-observation.js

@@ -0,0 +1,283 @@
+import path from "node:path";
+import brokerModule from "../adapters/mobile/bridge-runtime/lib/cdp-broker.cjs";
+import configModule from "../adapters/mobile/bridge-runtime/lib/config.cjs";
+import {
+  createExtensionNetworkObserver
+} from "./adapters/extension/network-observer.js";
+import {
+  indexArtifactManifest,
+  writeContainedArtifact
+} from "./artifact-files.js";
+const AUTO_CAPTURE_ID = "run-network";
+const AUTO_ARTIFACT_PATH = "network/run-summary.json";
+const { brokerSocketPath, createBrokerClient } = brokerModule;
+const { resolvePort } = configModule;
+const sessions = /* @__PURE__ */ new Map();
+async function startRunNetworkObservation(adapter, target, artifactsDir, env, ports = {}) {
+  if (adapter === "core") return void 0;
+  const runtimeEnv = {
+    ...env,
+    ...ports.cdpPort ? { CDP_PORT: ports.cdpPort, RECIPE_CDP_PORT: ports.cdpPort } : {},
+    ...ports.watcherPort ? { WATCHER_PORT: ports.watcherPort } : {}
+  };
+  const key = path.resolve(artifactsDir);
+  const session = {
+    artifactsDir: key,
+    autoStarted: false,
+    autoStartedAt: Date.now(),
+    nodeEvents: []
+  };
+  sessions.set(key, session);
+  try {
+    session.backend = adapter === "mobile" ? await createMobileNetworkBackend(target, runtimeEnv) : await createExtensionNetworkObserver(extensionCdpPort(runtimeEnv), key);
+  } catch (error) {
+    session.setupError = boundedError(error);
+  }
+  if (runtimeEnv.MM_HARNESS_AUTO_NETWORK_CAPTURE !== "0") {
+    session.autoStartedAt = Date.now();
+    if (session.backend) {
+      try {
+        await session.backend.start({
+          id: AUTO_CAPTURE_ID,
+          bodyJsonFields: ["type"],
+          maxDurationMs: 60 * 60 * 1e3,
+          maxRequests: 1e4,
+          methods: [],
+          urlIncludes: []
+        });
+        session.autoStarted = true;
+      } catch (error) {
+        session.setupError = boundedError(error);
+      }
+    }
+  }
+  return {
+    onActionEvent(event) {
+      session.nodeEvents.push({ ...event, epochMs: Date.now() });
+    },
+    async finalize(artifactManifestPath) {
+      try {
+        if (runtimeEnv.MM_HARNESS_AUTO_NETWORK_CAPTURE !== "0") {
+          const summary = await automaticSummary(session);
+          await writeSummary(key, AUTO_ARTIFACT_PATH, summary);
+          if (artifactManifestPath) {
+            await indexArtifact(
+              artifactManifestPath,
+              AUTO_ARTIFACT_PATH,
+              "Automatic network observation"
+            );
+          }
+        }
+      } finally {
+        sessions.delete(key);
+        await session.backend?.close();
+      }
+    }
+  };
+}
+async function handleRunNetworkAction(platform, action, node, context) {
+  if (platform !== "extension") return null;
+  if (action === "app.network_assert") {
+    const assertion = await import("../library/actions/shared/app/network-assert.mjs");
+    return {
+      output: await assertion.assertNetwork({ action, node, context })
+    };
+  }
+  if (action !== "app.network_capture") return null;
+  const phase = String(node.phase ?? "").toLowerCase();
+  const id = String(node.id ?? "").trim();
+  if (!["start", "end"].includes(phase) || !id) {
+    throw new Error(
+      "app.network_capture requires phase=start|end and a non-empty id."
+    );
+  }
+  const session = sessions.get(path.resolve(context.artifactsDir));
+  if (!session?.backend) {
+    throw new Error(
+      `Extension network observation is unavailable: ${session?.setupError ?? "run observer was not started"}.`
+    );
+  }
+  if (phase === "start") {
+    const result = await session.backend.start(captureParams(id, node));
+    return {
+      output: {
+        action,
+        phase,
+        ...asRecord(result)
+      }
+    };
+  }
+  const artifactPath = String(
+    node.artifact_path ?? `network/${id}-summary.json`
+  );
+  const summary = await session.backend.end(id);
+  await writeSummary(context.artifactsDir, artifactPath, summary);
+  return {
+    output: {
+      action,
+      phase,
+      ...summary
+    },
+    artifacts: [
+      {
+        path: artifactPath,
+        type: "report",
+        nodeId: context.nodeId
+      }
+    ]
+  };
+}
+async function createMobileNetworkBackend(target, env) {
+  const { client } = await connectMobileBroker(target, env);
+  return {
+    start(params) {
+      return client.control("capture-start", params, 1e4);
+    },
+    async end(id) {
+      return asRecord(await client.control("capture-end", { id }, 1e4));
+    },
+    async close() {
+      client.close();
+    }
+  };
+}
+async function connectMobileBroker(target, env) {
+  const runtimeDir = env.RECIPE_RUNTIME_DIR ? path.resolve(target, env.RECIPE_RUNTIME_DIR) : path.join(target, "temp", "recipe", "runtime");
+  const socketPath = brokerSocketPath(
+    runtimeDir,
+    resolvePort(env, target)
+  );
+  const discoveryClient = await createBrokerClient(socketPath, "", 1e4);
+  let targets;
+  try {
+    targets = await discoveryClient.control(
+      "resolve-targets",
+      { nameIncludes: mobileTargetPin(env) },
+      1e4
+    );
+  } finally {
+    discoveryClient.close();
+  }
+  const deviceId = selectMobileBrokerTarget(targets, env);
+  const client = await createBrokerClient(socketPath, deviceId, 1e4);
+  return { client, deviceId };
+}
+function selectMobileBrokerTarget(value, env) {
+  const targets = Array.isArray(value) ? value.map(asRecord).filter((target) => target.deviceId) : [];
+  const pin = mobileTargetPin(env);
+  const candidates = pin ? targets.filter(
+    (target) => String(target.name ?? "").toLowerCase().includes(pin.toLowerCase())
+  ) : targets;
+  if (candidates.length !== 1) {
+    throw new Error(
+      `Mobile network observation requires one broker target; found ${candidates.length}.`
+    );
+  }
+  return String(candidates[0].deviceId);
+}
+function mobileTargetPin(env) {
+  const platform = String(
+    env.MM_HARNESS_EXPLICIT_PLATFORM ?? env.RECIPE_HARNESS_PLATFORM ?? ""
+  ).toLowerCase();
+  return String(
+    platform === "android" ? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? "" : platform === "ios" ? env.IOS_SIMULATOR ?? "" : env.IOS_SIMULATOR ?? env.ANDROID_TARGET_DEVICE_NAME ?? env.ANDROID_DEVICE ?? ""
+  ).trim();
+}
+async function automaticSummary(session) {
+  let summary;
+  if (session.autoStarted && session.backend) {
+    try {
+      summary = await session.backend.end(AUTO_CAPTURE_ID);
+    } catch (error) {
+      summary = unavailableSummary(session.autoStartedAt, boundedError(error));
+    }
+  } else {
+    summary = unavailableSummary(
+      session.autoStartedAt,
+      session.setupError ?? "Network observer did not start."
+    );
+  }
+  const startedAt = Number(summary.startedAtEpochMs ?? session.autoStartedAt);
+  return {
+    ...summary,
+    nodeEvents: session.nodeEvents.map((event) => ({
+      action: event.action,
+      elapsedMs: Math.max(0, event.epochMs - startedAt),
+      nodeId: event.nodeId,
+      status: event.status
+    }))
+  };
+}
+function unavailableSummary(startedAtEpochMs, reason) {
+  return {
+    schemaVersion: 1,
+    id: AUTO_CAPTURE_ID,
+    status: "unavailable",
+    startedAtEpochMs,
+    endedAtEpochMs: Date.now(),
+    maxDurationMs: 60 * 60 * 1e3,
+    reconnects: 0,
+    droppedRequests: 0,
+    unavailableReasons: [reason],
+    coverageGapReasons: [],
+    uninspectableBodyRequests: 0,
+    projectedBodyFields: ["type"],
+    totalRequests: 0,
+    requestsByMethod: {},
+    requestsByHost: {},
+    requestsByType: {},
+    requests: []
+  };
+}
+function captureParams(id, node) {
+  return {
+    id,
+    urlIncludes: node.url_includes ?? [],
+    methods: node.methods ?? [],
+    bodyJsonFields: node.body_json_fields ?? [],
+    maxRequests: node.max_requests,
+    maxDurationMs: node.max_duration_ms
+  };
+}
+async function writeSummary(artifactsDir, relativePath, summary) {
+  await writeContainedArtifact(
+    artifactsDir,
+    relativePath,
+    `${JSON.stringify(summary, null, 2)}
+`,
+    "Network artifact"
+  );
+}
+async function indexArtifact(artifactManifestPath, relativePath, label) {
+  await indexArtifactManifest(
+    artifactManifestPath,
+    [
+      {
+        path: relativePath,
+        type: "report",
+        label,
+        category: "diagnostic"
+      }
+    ]
+  );
+}
+function extensionCdpPort(env) {
+  const port = Number(
+    env.CDP_PORT ?? env.RECIPE_CDP_PORT ?? process.env.CDP_PORT
+  );
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error("Extension network observation requires CDP_PORT.");
+  }
+  return port;
+}
+function boundedError(error) {
+  return String(error instanceof Error ? error.message : error).slice(0, 256);
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export {
+  connectMobileBroker,
+  handleRunNetworkAction,
+  startRunNetworkObservation
+};