@deeeed/metamask-harness 0.17.5 → 0.19.0

package/dist/adapters/resolve-slot-ports.js

@@ -1,5 +1,6 @@
 import {
   formatKvLines,
+  formatExtensionIdentityPorts,
   formatExtensionSlotPorts,
   inferSlotSuffix,
   realRepoPath,
@@ -7,12 +8,12 @@ import {
   resolveExtensionRuntimeContext,
   resolveExtensionRuntimePorts,
   resolveSlotPortsByRepo,
-  resolveFarmslotPortsByRepo,
   resolveMobileRuntimeContext,
   resolveMobileRuntimePorts,
   resolveMobileSlotDefaults
 } from "../../adapters/shared/resolve-slot-ports-core.mjs";
 export {
+  formatExtensionIdentityPorts,
   formatExtensionSlotPorts,
   formatKvLines,
   inferSlotSuffix,
@@ -20,7 +21,6 @@ export {
   resolveDefaultExtensionPorts,
   resolveExtensionRuntimeContext,
   resolveExtensionRuntimePorts,
-  resolveFarmslotPortsByRepo,
   resolveMobileRuntimeContext,
   resolveMobileRuntimePorts,
   resolveMobileSlotDefaults,

package/dist/adapters/slot-ports.js

@@ -3,8 +3,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { recipeRuntimeDir } from "../paths.js";
 import {
+  formatExtensionIdentityPorts,
   resolveDefaultExtensionPorts,
-  resolveExtensionRuntimeContext,
   resolveMobileRuntimeContext,
   resolveSlotPortsByRepo,
   resolveMobileSlotDefaults
@@ -55,12 +55,10 @@ function resolveMobileSlotPorts(target) {
 }
 function resolveExtensionSlotPorts(target) {
   const resolved = path.resolve(target);
-  const ctxOut = resolveExtensionRuntimeContext(resolved);
-  if (ctxOut?.trim()) applyKVLines(ctxOut, true);
-  const poolOut = resolveSlotPortsByRepo(resolved);
-  if (poolOut?.trim()) applyKVLines(poolOut, false);
-  const defOut = resolveDefaultExtensionPorts(resolved);
-  if (defOut?.trim()) applyKVLines(defOut, false);
+  const identity = formatExtensionIdentityPorts(resolved);
+  if (identity.trim()) applyKVLines(identity, true);
+  const fallback = resolveDefaultExtensionPorts(resolved);
+  if (fallback?.trim()) applyKVLines(fallback, false);
 }
 function extensionWatcherPids(target) {
   const resolved = path.resolve(target);
@@ -78,7 +76,9 @@ function extensionWatcherPids(target) {
       const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
       if (!match) continue;
       const [, pidStr, cmd] = match;
-      const isWatcher = cmd.includes("yarn start") || cmd.includes("webpack --watch") || cmd.includes("development/webpack/launch.ts --watch");
+      const executable = path.basename(cmd.trim().split(/\s+/u)[0] ?? "");
+      const isNodeProcess = executable === "node" || executable === "nodejs" || executable === "yarn";
+      const isWatcher = isNodeProcess && (/(?:^|\/)yarn start(?:\s|$)/u.test(cmd) || /(?:^|\/)yarn\.js webpack --watch(?:\s|$)/u.test(cmd) || /development\/webpack\/launch\.ts --watch(?:\s|$)/u.test(cmd));
       if (!isWatcher) continue;
       if (cmd.includes(resolved)) {
         ownedPids.add(Number(pidStr));
@@ -127,9 +127,8 @@ function stopExtensionWatcher(target) {
 function stopExtensionRuntime(target) {
   const resolved = path.resolve(target);
   const runtimeAbs = path.join(resolved, recipeRuntimeDir());
-  const profile = path.resolve(
-    process.env.CHROME_USER_DATA_DIR || path.join(runtimeAbs, process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile")
-  );
+  const configuredProfile = process.env.CHROME_USER_DATA_DIR || path.join(runtimeAbs, process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile");
+  const profiles = process.env.CHROME_USER_DATA_DIR ? [path.resolve(configuredProfile)] : [configuredProfile, path.join(runtimeAbs, "chrome-profile-recipe"), path.join(runtimeAbs, "chrome-profile-pw")].map((value) => path.resolve(value));
   let signalled = stopExtensionWatcher(resolved);
   const ownedBrowserPids = /* @__PURE__ */ new Set();
   try {
@@ -138,9 +137,7 @@ function stopExtensionRuntime(target) {
       const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
       if (!match) continue;
       const pid = Number(match[1]);
-      if (pid !== process.pid && commandHasExactArg(match[2], "--user-data-dir", profile)) {
-        ownedBrowserPids.add(pid);
-      }
+      if (pid !== process.pid && profiles.some((profile) => commandHasExactArg(match[2], "--user-data-dir", profile))) ownedBrowserPids.add(pid);
     }
   } catch {
   }
@@ -195,8 +192,8 @@ function processAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (error) {
+    return error.code === "EPERM";
   }
 }
 function commandHasExactArg(command, flag, value) {

package/dist/adapters.js

@@ -1,6 +1,8 @@
 import http from "node:http";
 import { compatibilityMode, fixtureSummary, repoShape } from "./doctor.js";
-import { runLiveAdapterScript } from "./live-adapter-contract.js";
+import {
+  runLiveAdapterScript
+} from "./live-adapter-contract.js";
 import { withExtensionPage } from "../library/actions/extension/platform/cdp.mjs";
 import { bridgeCommand, evalSync, MOBILE_BRIDGE_ERROR_CODES, selectBridgeStatusEntry, simulatorScreenshot } from "../library/actions/mobile/platform/bridge.mjs";
 function sleep(ms) {
@@ -32,6 +34,7 @@ const LIVE_ONLY_WALLET_ACTIONS = /* @__PURE__ */ new Set([
   "metamask.wallet.setup",
   "metamask.wallet.ensure_unlocked",
   "metamask.wallet.select_account",
+  "metamask.wallet.list_accounts",
   "metamask.wallet.read_state"
 ]);
 const LIVE_ONLY_APP_ACTIONS = /* @__PURE__ */ new Set(["ui.navigate"]);
@@ -42,14 +45,20 @@ function liveRuntimeConfigured(platform, node) {
   if (platform === "mobile" || platform === "core") return true;
   return Boolean(node.cdp_port ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT);
 }
-async function runLiveFirst(platform, action, node, context) {
+async function runLiveFirst(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
   if (node.allow_static_placeholder === true) {
     throw new Error(
       `${action} refused allow_static_placeholder. MetaMask runner proof runs must use live adapters and real artifacts.`
     );
   }
-  if (!requiresLiveAdapter(platform, action) && !liveRuntimeConfigured(platform, node)) return null;
-  const live = await runLiveAdapterScript({ platform, action, node, context });
+  if (!forceLive && !requiresLiveAdapter(platform, action) && !liveRuntimeConfigured(platform, node)) return null;
+  const live = await runLiveAdapterScript({
+    platform,
+    action,
+    node,
+    context,
+    prepared: preparedLiveAdapters?.get(action)
+  });
   if (!live) return null;
   const liveResult = isRecord(live.result) ? live.result : { result: live.result };
   const output = { ...liveResult, liveAdapter: live.script };
@@ -64,10 +73,17 @@ function liveAdapterPathHint(platform, action) {
   }
   return `library/actions/${platform}/${action.replaceAll(".", "/")}.mjs`;
 }
-async function semanticResult(platform, action, node, context) {
-  const live = await runLiveFirst(platform, action, node, context);
+async function semanticResult(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
+  const live = await runLiveFirst(
+    platform,
+    action,
+    node,
+    context,
+    forceLive,
+    preparedLiveAdapters
+  );
   if (live) return live;
-  if (requiresLiveAdapter(platform, action)) {
+  if (forceLive || requiresLiveAdapter(platform, action)) {
     const expected = liveAdapterPathHint(platform, action);
     throw new Error(
       `${action} requires a live ${platform} adapter that drives a real supported app/API path; no adapter script was found or no live runtime is configured (for example ${expected}). Static placeholders are refused to avoid fabricated proof. Set METAMASK_RECIPE_LIVE_ADAPTER_DIR or add a runner library/actions script.`
@@ -145,15 +161,16 @@ function probeHttpJson(url, timeoutMs = 1e3) {
     });
   });
 }
-function createMetaMaskSemanticAdapters(platform) {
+function createMetaMaskSemanticAdapters(platform, declaredCustomActions = [], preparedLiveAdapters) {
   const walletActions = [
     "metamask.wallet.fixture_status",
     "metamask.wallet.setup",
     "metamask.wallet.ensure_unlocked",
     "metamask.wallet.select_account",
+    "metamask.wallet.list_accounts",
     "metamask.wallet.read_state"
   ];
-  const actions = [
+  const bundledActions = [
     ...walletActions,
     "metamask.perps.read_positions",
     "metamask.perps.ensure_positions",
@@ -169,10 +186,19 @@ function createMetaMaskSemanticAdapters(platform) {
     // read_account is core-only: only the headless core adapter implements it.
     ...platform === "core" ? ["metamask.perps.read_account"] : []
   ];
+  const bundled = new Set(bundledActions);
+  const actions = [.../* @__PURE__ */ new Set([...bundledActions, ...declaredCustomActions])];
   return actions.map(
     (action) => simpleAdapter(
       action,
-      async (node, context) => semanticResult(platform, action, node, context)
+      async (node, context) => semanticResult(
+        platform,
+        action,
+        node,
+        context,
+        !bundled.has(action),
+        preparedLiveAdapters
+      )
     )
   );
 }
@@ -287,8 +313,15 @@ async function handleMobileNavigate(payload, context) {
   return isRecord(live.result) ? { ...live.result, liveAdapter: live.script } : live.result;
 }
 async function handleMobilePress(payload, context) {
-  const target = firstScalarText(payload, ["test_id", "testID", "selector", "text"], "ui.press");
-  return bridgeCommand(mobileUiInput(context, "press", payload), ["press-test-id", target]);
+  const identifiers = ["test_id", "testID", "selector"].map((field) => optionalScalarText(payload[field], `ui.press.${field}`)).filter((value) => value !== void 0);
+  const text = optionalScalarText(payload.text, "ui.press.text");
+  if (identifiers.length + Number(text !== void 0) !== 1) {
+    throw new Error("ui.press requires exactly one of: test_id, testID, selector, text.");
+  }
+  const target = text ?? identifiers[0];
+  if (target.trim() === "") throw new Error("ui.press target must be non-empty.");
+  const input = mobileUiInput(context, "press", payload);
+  return text !== void 0 ? bridgeCommand(input, ["press-text", target]) : bridgeCommand(input, ["press-test-id", target]);
 }
 async function handleMobileSetInput(payload, context) {
   const input = mobileUiInput(context, "set_input", payload);
@@ -432,7 +465,7 @@ function mobileHudStatusLabel(status) {
   if (status === "pass") return "pass";
   return "run";
 }
-function createMetaMaskUiTransport(platform, harness) {
+function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
   if (platform === "core") {
     return {
       async execute(action) {
@@ -461,7 +494,14 @@ function createMetaMaskUiTransport(platform, harness) {
   return {
     async execute(action, node, context) {
       if (action === "ui.navigate") {
-        const live = await runLiveFirst(platform, action, node, context);
+        const live = await runLiveFirst(
+          platform,
+          action,
+          node,
+          context,
+          false,
+          preparedLiveAdapters
+        );
         if (live) return live.output;
         throw new Error(`ui.navigate requires library/actions/${platform}/ui/navigate.mjs.`);
       }
@@ -473,7 +513,7 @@ function normalizeUiWaitNode(node) {
   if (node.expected !== void 0 || typeof node.visible !== "boolean") return node;
   return { ...node, expected: node.visible ? "visible" : "absent" };
 }
-function createMetaMaskAdapters(adapter) {
+function createMetaMaskAdapters(adapter, declaredCustomActions = [], preparedLiveAdapters) {
   const platform = adapter;
   const adapters = [
     simpleAdapter("app.status", async (_node, context) => ({
@@ -525,7 +565,7 @@ function createMetaMaskAdapters(adapter) {
         }
       };
     }),
-    ...createMetaMaskSemanticAdapters(platform)
+    ...createMetaMaskSemanticAdapters(platform, declaredCustomActions, preparedLiveAdapters)
   ];
   return adapters;
 }

package/dist/checkout-lock.js

@@ -7,7 +7,7 @@ function acquireCheckoutLock(target, operation) {
   const lockPath = path.join(repoRoot, recipeRuntimeDir(), "sandbox.lock");
   fs.mkdirSync(path.dirname(lockPath), { recursive: true });
   const inheritedToken = process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
-  for (let attempt = 0; attempt < 2; attempt += 1) {
+  for (let attempt = 0; attempt < 4; attempt += 1) {
     try {
       const fd = fs.openSync(lockPath, "wx", 384);
       const token = inheritedToken || randomUUID();
@@ -46,11 +46,36 @@ function acquireCheckoutLock(target, operation) {
           message: `checkout sandbox is busy with ${String(owner.operation ?? "another operation")} (pid ${owner.pid}).`
         };
       }
-      fs.rmSync(lockPath, { force: true });
+      claimStaleLock(lockPath, owner);
     }
   }
   return { path: lockPath, owner: readOwner(lockPath), message: "checkout sandbox lock could not be acquired." };
 }
+function claimStaleLock(lockPath, expectedOwner) {
+  const claimedPath = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+  try {
+    fs.renameSync(lockPath, claimedPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  try {
+    const claimedOwner = readOwner(claimedPath);
+    if (!sameOwner(claimedOwner, expectedOwner) || claimedOwner && typeof claimedOwner.pid === "number" && processAlive(claimedOwner.pid)) {
+      try {
+        fs.linkSync(claimedPath, lockPath);
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+      }
+    }
+  } finally {
+    fs.rmSync(claimedPath, { force: true });
+  }
+}
+function sameOwner(left, right) {
+  if (!left || !right) return left === right;
+  return left.pid === right.pid && left.token === right.token && left.startedAt === right.startedAt && left.repoRoot === right.repoRoot;
+}
 function readOwner(lockPath) {
   try {
     const value = JSON.parse(fs.readFileSync(lockPath, "utf8"));

package/dist/cli-color.js

@@ -47,6 +47,24 @@ function colorStatusWord(word, { stream = process.stderr } = {}) {
   }
   return color("info", word, { stream });
 }
+function colorHumanMessage(message, { stream = process.stderr } = {}) {
+  return String(message).split("\n").map((line) => {
+    const marker = /^(\s*)(→|✓|✗)\s?(.*)$/u.exec(line);
+    if (marker) {
+      const style = marker[2] === "\u2713" ? "ok" : marker[2] === "\u2717" ? "err" : "accent";
+      return `${marker[1]}${color(style, marker[2], { stream })}${marker[3] ? ` ${marker[3]}` : ""}`;
+    }
+    const next = /^(\s*)Next:\s*(.*)$/u.exec(line);
+    if (next) {
+      return `${next[1]}${color("label", "Next:", { stream })}${next[2] ? ` ${color("cmd", next[2], { stream })}` : ""}`;
+    }
+    const warning = /^(\s*)(WARN(?:ING)?)(:?)[ \t]*(.*)$/iu.exec(line);
+    if (warning) {
+      return `${warning[1]}${color("warn", `${warning[2]}${warning[3]}`, { stream })}${warning[4] ? ` ${warning[4]}` : ""}`;
+    }
+    return line;
+  }).join("\n");
+}
 function classifyLogEvent(event) {
   const text = String(event || "");
   if (/Module build failed|^ERROR in |BUILD FAILED|compiled with [1-9][0-9]* error/iu.test(text)) {
@@ -72,6 +90,7 @@ export {
   classifyLogEvent,
   color,
   colorEnabled,
+  colorHumanMessage,
   colorKv,
   colorLogEvent,
   colorStatusWord,

package/dist/cli-commands.js

@@ -15,7 +15,7 @@ const SPEC = {
     { 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: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
-    { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
+    { name: "actions", desc: "List runnable recipe actions", flags: ["--json", "--categories", "--category", "--action", "--library"] },
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { detectAdapter, handleHarness } from "./harness.js";
-import { handleActions, handleManifest } from "./commands/manifest.js";
+import { handleActions } from "./commands/manifest.js";
 import { handleDoctor } from "./commands/doctor.js";
 import { handleProvision } from "./commands/provision.js";
 import { handleRuntimeHealth } from "./commands/runtime-health.js";
@@ -11,7 +11,6 @@ import { handleRun } from "./commands/run.js";
 import { handleSelfTest } from "./commands/self-test.js";
 import { handleCall } from "./commands/call.js";
 import { handleStop } from "./commands/stop.js";
-import { handleFlows } from "./commands/flows.js";
 import { handleCompletionCandidates, invalidateCompletionCache } from "./commands/completion-candidates.js";
 import { handleLaunch } from "./commands/launch/index.js";
 import { handleLogs } from "./commands/logs.js";
@@ -21,10 +20,9 @@ import { handleRecipeQuality } from "./commands/recipe-quality.js";
 import { handleStatus } from "./commands/status.js";
 import { handleCheck } from "./commands/check.js";
 import { handleChecklist } from "./commands/checklist.js";
+import { handleLast } from "./commands/last.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
-import { runOneNode } from "./commands/run-engine.js";
 const COMMANDS = {
-  manifest: handleManifest,
   actions: handleActions,
   doctor: handleDoctor,
   "runtime-health": handleRuntimeHealth,
@@ -35,7 +33,7 @@ const COMMANDS = {
   run: handleRun,
   "self-test": handleSelfTest
 };
-const OVERLAY_COMMANDS = ["install", "verify", "cleanup", "live"];
+const OVERLAY_COMMANDS = ["install", "verify", "cleanup"];
 function usage() {
   console.error(`mm-harness \u2014 the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay.
 Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.
@@ -54,17 +52,12 @@ DAILY LOOP \u2014 what a teammate runs many times a day:
 PROVE \u2014 run recipes and inspect capabilities:
   run        Run a recipe and write evidence (summary/trace/artifacts).
                mm-harness run recipe.json
-  flows      List/promote recipe library flows (personal/team win over canonical).
-               mm-harness flows list
   doctor     Readiness check for a checkout (no app launch).
                mm-harness doctor
   check      Run bounded repo-local checks for an active diff.
                mm-harness check diff --profile fast --artifacts-dir artifacts/validation
   actions    Describe the actions a manifest declares.
                mm-harness actions --adapter mobile
-  manifest   Print/validate the action manifest for an adapter.
-               mm-harness manifest --adapter extension --json
-
 RUNTIME OVERLAY \u2014 install/verify/clean the per-checkout runtime overlay:
   provision  Install the cached Runway mobile dev client (artifact cache + sim install).
                mm-harness provision runway ios --adapter mobile
@@ -72,12 +65,8 @@ RUNTIME OVERLAY \u2014 install/verify/clean the per-checkout runtime overlay:
                mm-harness install                      # inside a checkout, auto-detected
   verify     Check the overlay/runtime is present and healthy (no launch).
                mm-harness verify
-  live       Launch/reuse the app, then verify live control end-to-end.
-               mm-harness live
   cleanup    Remove the installed overlay and restore the checkout.
                mm-harness cleanup
-  # Open sub-question (Arthur): keep these top-level (mm-harness install) or group
-  # them under an \`overlay\` command (mm-harness overlay install)? Top-level for now.
 
 ADVANCED \u2014 internal runtime probes (rarely typed by hand):
   runtime-health     runtime-decision   runtime-launch
@@ -88,7 +77,7 @@ ONE bin: mm-harness is the only command. No per-platform binaries \u2014 platfor
 auto-detected, the positional target forces it (mm-harness launch ios), and
 platform-specific needs are FLAGS on the same command (e.g. --sidebar, --full-build).
 Human happy path = the bare command; agents add depth via flags (--json, --target, ports).
-See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).
+See README.md for the workflow and docs/RECIPES.md for proof authoring.
 `);
 }
 async function main(argv) {
@@ -100,7 +89,6 @@ async function main(argv) {
   if (command === "status" || command === "health" || command === "home") {
     return handleStatus(parseArgs(argv.slice(1), "status"));
   }
-  if (command === "flows") return handleFlows(argv.slice(1));
   if (command === "call") return handleCall(argv.slice(1));
   if (command === "completion-candidates") return handleCompletionCandidates(argv.slice(1));
   if (command === "provision") return handleProvision(parseArgs(argv.slice(1), command));
@@ -111,7 +99,7 @@ async function main(argv) {
         const target = targetPath(options);
         const adapterRaw = (typeof options["adapter"] === "string" ? options["adapter"] : void 0) ?? (typeof options["platform"] === "string" ? options["platform"] : void 0) ?? detectAdapter(target);
         if (adapterRaw === "mobile" || adapterRaw === "extension" || adapterRaw === "core") {
-          await handleHarness(["install", "--platform", adapterRaw, "--target", target]);
+          await handleHarness(["install", "--platform", adapterRaw, "--target", target, "--quiet"]);
         }
       } catch {
       }
@@ -129,10 +117,11 @@ 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 === "fixtures") return handleFixtures(argv.slice(1), { runOneNode });
+  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));
   if (command === "checklist") return handleChecklist(argv.slice(1));
+  if (command === "last") return handleLast(parseArgs(argv.slice(1), command));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);
   return handler(parseArgs(argv.slice(1), command));