@deeeed/metamask-harness 0.14.0 → 0.14.2

package/dist/commands/run-report.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isRecord } from "./parse-args.js";
+function writeRunReport(result) {
+  const summaryPath = String(result.summaryPath);
+  const tracePath = String(result.tracePath);
+  const artifactManifestPath = String(result.artifactManifestPath);
+  const artifactsDir = path.dirname(summaryPath);
+  const summary = JSON.parse(fs.readFileSync(summaryPath, "utf8"));
+  const trace = JSON.parse(fs.readFileSync(tracePath, "utf8"));
+  const entries = Array.isArray(trace.entries) ? trace.entries : [];
+  const lines = renderRunReport(summary, entries);
+  const reportPath = path.join(artifactsDir, "report.md");
+  fs.writeFileSync(reportPath, `${lines.join("\n")}
+`);
+  indexRunReportArtifact(artifactManifestPath);
+  return {
+    path: reportPath,
+    preview: lines.filter((line) => line.startsWith("- ")).slice(0, 6).map((line) => line.slice(2))
+  };
+}
+function renderRunReport(summary, entries) {
+  const lines = [
+    "# MetaMask Recipe Run",
+    "",
+    `Status: ${String(summary.status ?? "unknown")}`,
+    `Duration: ${formatDuration(Number(summary.durationMs ?? 0))}`,
+    `Nodes: ${Number(summary.passed ?? 0)}/${Number(summary.total ?? entries.length)} passed`,
+    "",
+    "## Steps"
+  ];
+  for (const entry of entries) {
+    if (!isRecord(entry)) continue;
+    const mark = entry.ok === false ? "FAIL" : "PASS";
+    const nodeId = String(entry.nodeId ?? "(node)");
+    const action = String(entry.action ?? "(action)");
+    const duration = formatDuration(Number(entry.durationMs ?? 0));
+    const detail = summarizeNodeOutput(entry.output);
+    lines.push(`- ${mark} ${nodeId} (${action}, ${duration})${detail ? `: ${detail}` : ""}`);
+  }
+  return lines;
+}
+function summarizeNodeOutput(output) {
+  if (!isRecord(output)) return "";
+  const parts = [];
+  const preferredKeys = [
+    "platform",
+    "screen",
+    "route",
+    "page",
+    "network",
+    "account",
+    "count",
+    "matchingCount",
+    "proofPath",
+    "screenshot",
+    "path"
+  ];
+  for (const key of preferredKeys) addPart(parts, labelFor(key), summarizeValue(output[key]));
+  const accountState = isRecord(output.accountState) ? output.accountState : void 0;
+  if (accountState) {
+    addPart(parts, "totalBalance", accountState.totalBalance);
+    addPart(parts, "spendable", accountState.spendableBalance);
+    addPart(parts, "marginUsed", accountState.marginUsed);
+    addPart(parts, "unrealizedPnl", accountState.unrealizedPnl);
+  }
+  if (parts.length === 0) {
+    for (const [key, value] of Object.entries(output)) {
+      if (parts.length >= 5) break;
+      if (key === "liveAdapter" || key === "artifacts") continue;
+      addPart(parts, key, summarizeValue(value));
+    }
+  }
+  return parts.join(", ");
+}
+function labelFor(key) {
+  return key === "matchingCount" ? "matching" : key === "proofPath" ? "proof" : key;
+}
+function summarizeValue(value) {
+  if (typeof value === "string") return shortenAddress(value);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return `${value.length} item${value.length === 1 ? "" : "s"}`;
+  return void 0;
+}
+function addPart(parts, label, value) {
+  if (value === void 0 || value === null || value === "") return;
+  parts.push(`${label}=${String(value)}`);
+}
+function shortenAddress(value) {
+  return /^0x[a-fA-F0-9]{40}$/u.test(value) ? `${value.slice(0, 6)}...${value.slice(-4)}` : value;
+}
+function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return "0ms";
+  if (ms < 1e3) return `${Math.round(ms)}ms`;
+  return `${(ms / 1e3).toFixed(ms < 1e4 ? 1 : 0)}s`;
+}
+function indexRunReportArtifact(artifactManifestPath) {
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(artifactManifestPath, "utf8"));
+  } catch {
+    return;
+  }
+  if (!isRecord(manifest)) return;
+  const artifacts = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+  manifest.artifacts = [
+    ...artifacts.filter((artifact) => !isRecord(artifact) || artifact.path !== "report.md"),
+    { path: "report.md", type: "report", label: "Human run report", category: "system" }
+  ];
+  fs.writeFileSync(artifactManifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+}
+export {
+  writeRunReport
+};

package/dist/commands/run.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { walletFixturePath } from "../paths.js";
+import { color } from "../cli-color.js";
+import { recipeRunning } from "../heal-bounds.js";
 import { EXIT } from "./shared.js";
 import {
   optionFlag,
@@ -8,6 +10,7 @@ import {
   requiredOption,
   resolveAdapter,
   runtimeOptionsFromCli,
+  isRecord,
   usageError
 } from "./parse-args.js";
 import {
@@ -21,6 +24,8 @@ import {
 import { handleListExecutables } from "./list-executables.js";
 import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
+import { coreDependencyBlock } from "./core-readiness.js";
+import { writeRunReport } from "./run-report.js";
 async function handleRun({ positional, options }) {
   if (optionFlag(options, "list")) return handleListExecutables("run", options);
   const targetRecipe = positional[0];
@@ -33,10 +38,10 @@ async function handleRun({ positional, options }) {
   if ("code" in dtResult) {
     return emitRunUsageError(json, adapter, targetRecipe, dtResult.code, dtResult.message);
   }
-  const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
-  const prepared = await prepareHeal(adapter, target, options, json);
-  if (typeof prepared === "number") return prepared;
-  const { state, heal } = prepared;
+  if (recipeRunning(target)) return emitRunRecipeRunning(json);
+  if (optionString(options, "artifactsDir") === void 0 && runArgLooksLikeRecipeFile(targetRecipe)) {
+    requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
+  }
   const validated = await validateRunRecipeStatic(targetRecipe, adapter, options);
   if (validated.usageError) {
     return emitRunUsageError(json, adapter, validated.recipeFile, validated.usageError.code, validated.usageError.message);
@@ -44,6 +49,14 @@ async function handleRun({ positional, options }) {
   if (validated.errorCount > 0) {
     return emitRunValidationError(json, adapter, validated.recipeFile, validated.findings, validated.errorCount);
   }
+  const depsBlock = adapter === "core" && recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
+  if (depsBlock) {
+    return emitRunUsageError(json, adapter, validated.recipeFile, depsBlock.code, depsBlock.message, depsBlock.userAction);
+  }
+  const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
+  const prepared = await prepareHeal(adapter, target, options, json);
+  if (typeof prepared === "number") return prepared;
+  const { state, heal } = prepared;
   const librarySources = validated.librarySources;
   const runtimeOptions = {
     ...runtimeOptionsFromCli(options),
@@ -60,6 +73,7 @@ async function handleRun({ positional, options }) {
     state
   );
   if (violation !== null) return emitHealViolation(json, "run", result, violation, state, adapter);
+  const report = writeRunReport(result);
   const exitCode = result.status === "pass" ? EXIT.ok : EXIT.runtime;
   if (json) {
     console.log(
@@ -72,6 +86,7 @@ async function handleRun({ positional, options }) {
           exitCode,
           recovered: state.recovered,
           mutations: state.mutations,
+          reportPath: report.path,
           result
         },
         null,
@@ -79,11 +94,88 @@ async function handleRun({ positional, options }) {
       )
     );
   } else {
-    console.log(`MetaMask recipe run: ${result.status}
-Artifacts: ${result.artifactManifestPath}`);
+    const out = (style, text) => color(style, text, { stream: process.stdout });
+    console.log(`${out(result.status === "pass" ? "ok" : "err", result.status.toUpperCase())} ${out("bold", "recipe run")} ${out("dim", `[${adapter}]`)}`);
+    if (report.preview.length > 0) {
+      console.log(out("label", "summary:"));
+      for (const line of report.preview) console.log(`  ${formatPreviewLine(line, out)}`);
+    }
+    console.log(`${out("label", "report:")} ${out("path", report.path)}`);
+    console.log(`${out("label", "artifacts:")} ${out("path", result.artifactManifestPath)}`);
   }
   return exitCode;
 }
+function formatPreviewLine(line, out) {
+  const match = /^(PASS|FAIL)\s+(.+)$/u.exec(line);
+  if (!match) return line;
+  const status = match[1];
+  const rest = match[2];
+  return `${out(status === "PASS" ? "ok" : "err", status)} ${rest}`;
+}
+function recipeUsesCoreController(recipe, librarySources) {
+  if (objectUsesCoreController(recipe)) return true;
+  const refs = collectCallRefs(recipe);
+  if (refs.length === 0) return false;
+  const flows = loadFlowCatalogs(librarySources ?? []);
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (ref) => {
+    if (visited.has(ref)) return false;
+    visited.add(ref);
+    const flow = flows.get(ref);
+    if (!flow) return false;
+    if (objectUsesCoreController(flow)) return true;
+    return collectCallRefs(flow).some(visit);
+  };
+  return refs.some(visit);
+}
+function objectUsesCoreController(value) {
+  if (Array.isArray(value)) return value.some(objectUsesCoreController);
+  if (!isRecord(value)) return false;
+  if (actionUsesCoreController(value.action)) return true;
+  return Object.values(value).some(objectUsesCoreController);
+}
+function collectCallRefs(value) {
+  const refs = [];
+  const visit = (node) => {
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    if (!isRecord(node)) return;
+    if (node.action === "call" && typeof node.ref === "string" && node.ref) refs.push(node.ref);
+    for (const child of Object.values(node)) visit(child);
+  };
+  visit(value);
+  return [...new Set(refs)];
+}
+function loadFlowCatalogs(librarySources) {
+  const flows = /* @__PURE__ */ new Map();
+  for (const source of librarySources) {
+    const flowsDir = path.join(source.root, "flows");
+    let entries;
+    try {
+      entries = fs.readdirSync(flowsDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(flowsDir, entry), "utf8"));
+        if (!isRecord(parsed) || !isRecord(parsed.flows)) continue;
+        for (const [id, flow] of Object.entries(parsed.flows)) {
+          if (!flows.has(id)) flows.set(id, flow);
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return flows;
+}
+function actionUsesCoreController(action) {
+  return typeof action === "string" && action.startsWith("metamask.perps.");
+}
 async function handleRunPlan(recipeArg, options) {
   const json = optionFlag(options, "json");
   const { adapter, target } = resolveAdapter(options);
@@ -176,17 +268,30 @@ function emitPlanUsageError(json, adapter, recipeFile, code, message) {
   }
   return EXIT.usage;
 }
-function emitRunUsageError(json, adapter, recipeFile, code, message) {
+function runArgLooksLikeRecipeFile(value) {
+  return path.isAbsolute(value) || value.includes("/") || value.includes(path.sep) || value.endsWith(".json") || fs.existsSync(path.resolve(value));
+}
+function emitRunRecipeRunning(json) {
+  const message = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
+  if (json) {
+    console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message } }, null, 2));
+  } else {
+    console.error(`\u2717 mm-harness: ${message}`);
+  }
+  return EXIT.bounded;
+}
+function emitRunUsageError(json, adapter, recipeFile, code, message, userAction) {
   if (json) {
     console.log(
       JSON.stringify(
-        { schemaVersion: 1, command: "run", adapter, status: "fail", exitCode: EXIT.usage, recipe: recipeFile, error: { code, message } },
+        { schemaVersion: 1, command: "run", adapter, status: "fail", exitCode: EXIT.usage, recipe: recipeFile, error: { code, message, ...userAction ? { userAction } : {} } },
         null,
         2
       )
     );
   } else {
     console.error(`\u2717 run: ${message}`);
+    if (userAction) console.error(`  Next: ${userAction}`);
   }
   return EXIT.usage;
 }

package/dist/commands/shared.js

@@ -47,7 +47,8 @@ function targetOf(options) {
 }
 const ADAPTER_TOKENS = ["mobile", "extension", "core"];
 function resolveAdapter(options, target, hint) {
-  const explicit = str(options, "adapter") ?? str(options, "platform");
+  const platform = str(options, "platform");
+  const explicit = str(options, "adapter") ?? (platform === "ios" || platform === "android" ? "mobile" : platform);
   if (explicit && ADAPTER_TOKENS.includes(explicit)) return explicit;
   if (hint) return hint;
   return detectAdapter(target);

package/dist/commands/status-probe.js

@@ -38,15 +38,21 @@ function parseBridgeEntries(raw) {
     ...typeof e.agenticPresent === "boolean" ? { agenticPresent: e.agenticPresent } : {}
   }));
 }
-function matchBridgeEntry(device, entries) {
+function matchBridgeEntry(device, entries, devices) {
   const byId = entries.find((e) => e.deviceName === device.id);
   if (byId) return byId;
   if (device.name) {
     const byName = entries.find((e) => e.deviceName === device.name);
     if (byName) return byName;
+    if (device.platform === "android") {
+      const model = device.name.replace(/_/gu, " ");
+      const byModel = entries.find((e) => e.deviceName === model || e.deviceName.startsWith(`${model} -`));
+      if (byModel) return byModel;
+    }
   }
   const platformEntries = entries.filter((e) => e.platform === device.platform);
-  if (platformEntries.length === 1) return platformEntries[0];
+  const platformDevices = devices.filter((d) => d.platform === device.platform);
+  if (!device.name && platformEntries.length === 1 && platformDevices.length === 1) return platformEntries[0];
   return null;
 }
 function probeMobileBridge(target) {
@@ -123,7 +129,7 @@ async function probeMobileLiveState(target, devices) {
   const matched = /* @__PURE__ */ new Map();
   const usedEntries = /* @__PURE__ */ new Set();
   for (const device of devices) {
-    const entry = matchBridgeEntry(device, entries.filter((e) => !usedEntries.has(e)));
+    const entry = matchBridgeEntry(device, entries.filter((e) => !usedEntries.has(e)), devices);
     if (entry) {
       matched.set(device.id, entry);
       usedEntries.add(entry);

package/dist/commands/status.js

@@ -2,15 +2,25 @@ import { color } from "../cli-color.js";
 import { detectAdapter } from "../harness.js";
 import { assertAdapter } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { listConnectedDevices } from "../devices.js";
-import { deviceSelected, renderDeviceList } from "./device-target.js";
-import { probeMobileLiveState } from "./status-probe.js";
+import {
+  applyDeviceTargeting
+} from "./device-target.js";
+import {
+  mobileDeviceView,
+  mobileDeviceLiveView,
+  nextForLive,
+  renderAndroidPortHints,
+  renderMobileDeviceList,
+  renderAdditionalReachableDevices,
+  renderMobileLiveBlock
+} from "./mobile-device-view.js";
 import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import { optionFlag, targetPath } from "./parse-args.js";
 async function handleStatus({ options }) {
   const target = targetPath(options);
   const json = optionFlag(options, "json");
   const fast = optionFlag(options, "fast");
+  const allDevices = optionFlag(options, "allDevices");
   const adapter = detectAdapter(target);
   if (!adapter) {
     return usageOut(json, "status", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
@@ -18,16 +28,31 @@ async function handleStatus({ options }) {
   assertAdapter(adapter);
   const surface = getAdapterSurface(adapter);
   surface.resolveSlotPorts(target);
+  if (adapter === "mobile") {
+    const dtResult = applyDeviceTargeting("status", adapter, options, { gate: false, rerun: "" });
+    if ("code" in dtResult) {
+      return usageOut(json, "status", dtResult.message, "mm-harness status --device <id> or --all-devices");
+    }
+  }
   const next = surface.hints.relaunch;
-  const devices = adapter === "mobile" ? slotScopedDevices(listConnectedDevices()) : [];
+  const deviceView = adapter === "mobile" ? mobileDeviceView(allDevices) : null;
+  const devices = deviceView?.devices ?? [];
   if (json) {
-    const doProbe = !fast && adapter === "mobile" && devices.length > 0;
+    const doProbe = !fast && adapter === "mobile" && deviceView !== null && deviceView.allConnectedDevices.length > 0;
     if (doProbe) {
-      const liveMap = await probeMobileLiveState(target, devices);
-      const devicesWithLive = devices.map((d) => mergeDeviceLive(d, liveMap.get(d.id)));
+      const liveView = await mobileDeviceLiveView(target, deviceView);
       console.log(
         JSON.stringify(
-          { schemaVersion: 1, command: "status", adapter, target, devices: devicesWithLive, next: nextForLive(next, liveMap) },
+          {
+            schemaVersion: 1,
+            command: "status",
+            adapter,
+            target,
+            devices: liveView.devicesWithLive,
+            ...liveView.additionalReachableDevices.length > 0 ? { additionalReachableDevices: liveView.additionalReachableDevices } : {},
+            ...liveView.androidPortHints.length > 0 ? { androidPortHints: liveView.androidPortHints } : {},
+            next: nextForLive(next, liveView.liveMap)
+          },
           null,
           2
         )
@@ -41,63 +66,18 @@ async function handleStatus({ options }) {
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });
   console.log(`${out("label", "status")} ${out("bold", adapter)} ${out("dim", target)}`);
-  if (adapter === "mobile") renderDeviceList(devices, out);
-  if (!fast && adapter === "mobile" && devices.length > 0) {
-    const liveMap = await probeMobileLiveState(target, devices);
-    renderLiveBlock(devices, liveMap, out);
-    console.log(`${out("label", "Next:")} ${out("cmd", nextForLive(next, liveMap))}`);
+  if (deviceView) renderMobileDeviceList(deviceView, out);
+  if (!fast && adapter === "mobile" && deviceView !== null && deviceView.allConnectedDevices.length > 0) {
+    const liveView = await mobileDeviceLiveView(target, deviceView);
+    if (liveView.additionalReachableDevices.length > 0) renderAdditionalReachableDevices(liveView.additionalReachableDevices, out);
+    renderMobileLiveBlock(devices, liveView.liveMap, out);
+    renderAndroidPortHints(liveView.androidPortHints, out);
+    console.log(`${out("label", "Next:")} ${out("cmd", nextForLive(next, liveView.liveMap))}`);
   } else {
     console.log(`${out("label", "Next:")} ${out("cmd", next)}`);
   }
   return EXIT.ok;
 }
-function nextForLive(fallback, liveMap) {
-  for (const live of liveMap.values()) {
-    if (live.liveState === void 0) return "mm-harness logs";
-  }
-  return fallback;
-}
-function slotScopedDevices(devices) {
-  const withSelection = devices.map((device) => ({ ...device, selected: deviceSelected(device) }));
-  const selected = withSelection.filter((device) => device.selected);
-  return selected.length > 0 ? selected : withSelection;
-}
-function mergeDeviceLive(device, live) {
-  if (!live) return device;
-  return {
-    ...device,
-    fixtureStatus: live.fixtureStatus,
-    ...live.liveState !== void 0 ? { liveState: live.liveState } : {},
-    ...live.currentScreen !== void 0 ? { currentScreen: live.currentScreen } : {},
-    ...live.walletState !== void 0 ? { walletState: live.walletState } : {},
-    ...live.selectedAccount !== void 0 ? { selectedAccount: live.selectedAccount } : {}
-  };
-}
-function renderLiveBlock(devices, liveMap, out) {
-  console.log(`${out("label", "live:")}`);
-  for (const device of devices) {
-    const live = liveMap.get(device.id);
-    const prefix = `  ${device.platform} ${out("dim", device.id)}${device.name ? ` (${device.name})` : ""}`;
-    if (!live || live.liveState === "no-bridge") {
-      console.log(`${prefix}: ${out("dim", "(no-bridge)")}`);
-      continue;
-    }
-    if (live.liveState === "bridge-absent") {
-      console.log(`${prefix}: ${out("warn", "(bridge-absent \u2014 app attached, build lacks __AGENTIC__; rebuild/reinstall a dev build)")}`);
-      continue;
-    }
-    const parts = [];
-    if (live.currentScreen !== void 0) parts.push(`screen=${out("cmd", live.currentScreen)}`);
-    if (live.walletState !== void 0) parts.push(`wallet=${out(live.walletState === "unlocked" ? "ok" : "warn", live.walletState)}`);
-    if (live.selectedAccount !== void 0) {
-      parts.push(`account=${live.selectedAccount.label} ${out("dim", `(${live.selectedAccount.address})`)}`);
-    }
-    if (live.fixtureStatus !== void 0) {
-      parts.push(`fixture=${out(live.fixtureStatus === "READY" ? "ok" : "warn", live.fixtureStatus)}`);
-    }
-    console.log(`${prefix}: ${parts.join("  ")}`);
-  }
-}
 export {
   handleStatus
 };

package/dist/live-adapter-contract.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { resolveRequiredLocalProtocolRoot, runnerDir } from "./paths.js";
+import { corePnpNodeOptions } from "./commands/core-readiness.js";
 function actionFileStem(action) {
   return String(action).replace(/[^a-zA-Z0-9._-]/g, "_");
 }
@@ -199,7 +200,10 @@ async function platformAdapterEnv(platform, projectRoot, tempDir) {
     `${JSON.stringify({ compilerOptions: { baseUrl: projectRoot, paths } }, null, 2)}
 `
   );
-  return { TSX_TSCONFIG_PATH: tsconfigPath };
+  return {
+    TSX_TSCONFIG_PATH: tsconfigPath,
+    NODE_OPTIONS: corePnpNodeOptions(projectRoot, process.env.NODE_OPTIONS)
+  };
 }
 async function runLiveAdapterScript({ platform, action, node, context }) {
   const script = await resolveLiveAdapter(platform, action);