@deeeed/metamask-harness 0.14.7 → 0.15.0

package/dist/adapters/slot-ports.js

@@ -1,12 +1,12 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { readRuntimeContextField, resolveRuntimeContextPath } from "../harness.js";
 import { recipeRuntimeDir } from "../paths.js";
 import {
   resolveDefaultExtensionPorts,
-  resolveSlotPortsByRepo,
+  resolveExtensionRuntimeContext,
   resolveMobileRuntimeContext,
+  resolveSlotPortsByRepo,
   resolveMobileSlotDefaults
 } from "./resolve-slot-ports.js";
 function applyKVLines(output, overwrite) {
@@ -54,51 +54,34 @@ function resolveMobileSlotPorts(target) {
   if (defOut?.trim()) applyKVLines(defOut, false);
 }
 function resolveExtensionSlotPorts(target) {
-  const contextPath = resolveRuntimeContextPath(target);
-  const cdp = readRuntimeContextField(contextPath, "cdpPort");
-  if (cdp) {
-    process.env["CDP_PORT"] = cdp;
-    process.env["RECIPE_CDP_PORT"] = cdp;
-  }
-  const dev = readRuntimeContextField(contextPath, "devServerPort");
-  if (dev) {
-    process.env["WATCHER_PORT"] = dev;
-    process.env["RECIPE_WATCHER_PORT"] = dev;
-  }
-  if (!process.env["CDP_PORT"] || !process.env["WATCHER_PORT"]) {
-    const poolOut = resolveSlotPortsByRepo(target);
-    if (poolOut?.trim()) applyKVLines(poolOut, false);
-    const defOut = resolveDefaultExtensionPorts(target);
-    if (defOut?.trim()) applyKVLines(defOut, false);
-  }
+  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);
 }
-function stopExtensionWatcher(target) {
-  const runtimeAbs = path.join(target, recipeRuntimeDir());
+function extensionWatcherPids(target) {
+  const resolved = path.resolve(target);
+  const runtimeAbs = path.join(resolved, recipeRuntimeDir());
   const webpackPidFile = path.join(runtimeAbs, "recipe-harness-webpack.pid");
-  let signalled = 0;
+  const ownedPids = /* @__PURE__ */ new Set();
   try {
     const pid = fs.readFileSync(webpackPidFile, "utf8").trim();
-    if (/^\d+$/u.test(pid)) {
-      try {
-        process.kill(Number(pid), "SIGTERM");
-        signalled += 1;
-      } catch {
-      }
-    }
-    fs.rmSync(webpackPidFile, { force: true });
+    if (/^\d+$/u.test(pid) && processAlive(Number(pid))) ownedPids.add(Number(pid));
   } catch {
   }
   try {
     const psOut = execFileSync("ps", ["-axo", "pid=,command="], { encoding: "utf8" });
-    const orphanPids = [];
     for (const line of psOut.split("\n")) {
       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");
       if (!isWatcher) continue;
-      if (cmd.includes(target)) {
-        orphanPids.push(Number(pidStr));
+      if (cmd.includes(resolved)) {
+        ownedPids.add(Number(pidStr));
         continue;
       }
       try {
@@ -106,35 +89,134 @@ function stopExtensionWatcher(target) {
           encoding: "utf8",
           timeout: 2e3
         });
-        if (cwd.split("\n").some((l) => l.startsWith("n") && l.slice(1) === target)) {
-          orphanPids.push(Number(pidStr));
+        if (cwd.split("\n").some((l) => l.startsWith("n") && l.slice(1) === resolved)) {
+          ownedPids.add(Number(pidStr));
         }
       } catch {
       }
     }
-    if (orphanPids.length > 0) {
-      for (const pid of orphanPids) {
-        try {
-          process.kill(pid, "SIGTERM");
-        } catch {
-        }
+  } catch {
+  }
+  return [...ownedPids];
+}
+function isExtensionWatcherLive(target) {
+  return extensionWatcherPids(target).length > 0;
+}
+function stopExtensionWatcher(target) {
+  const runtimeAbs = path.join(path.resolve(target), recipeRuntimeDir());
+  const webpackPidFile = path.join(runtimeAbs, "recipe-harness-webpack.pid");
+  const ownedPids = extensionWatcherPids(target);
+  for (const pid of ownedPids) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+    }
+  }
+  fs.rmSync(webpackPidFile, { force: true });
+  if (ownedPids.length > 0) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2e3);
+    for (const pid of ownedPids) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
       }
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2e3);
-      for (const pid of orphanPids) {
-        try {
-          process.kill(pid, "SIGKILL");
-        } catch {
-        }
+    }
+  }
+  return ownedPids.length;
+}
+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")
+  );
+  let signalled = stopExtensionWatcher(resolved);
+  const ownedBrowserPids = /* @__PURE__ */ new Set();
+  try {
+    const psOut = execFileSync("ps", ["-axo", "pid=,command="], { encoding: "utf8" });
+    for (const line of psOut.split("\n")) {
+      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);
       }
-      signalled += orphanPids.length;
     }
   } catch {
   }
-  return signalled;
+  for (const pid of ownedBrowserPids) {
+    try {
+      process.kill(pid, "SIGTERM");
+      signalled += 1;
+    } catch {
+    }
+  }
+  if (ownedBrowserPids.size > 0) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2e3);
+    for (const pid of ownedBrowserPids) {
+      try {
+        process.kill(pid, 0);
+        process.kill(pid, "SIGKILL");
+      } catch {
+      }
+    }
+  }
+  let removedMarkers = 0;
+  for (const name of [
+    "recipe-harness-webpack.pid",
+    "webpack.pid",
+    "browser.pid",
+    "chromium.pid",
+    "chrome.pid",
+    "launcher.pid",
+    "sandbox.lock",
+    "recipe.lock"
+  ]) {
+    const marker = path.join(runtimeAbs, name);
+    if (!fs.existsSync(marker)) continue;
+    const pid = markerPid(marker);
+    if (pid !== null && processAlive(pid) && !ownedBrowserPids.has(pid)) continue;
+    fs.rmSync(marker, { force: true });
+    removedMarkers += 1;
+  }
+  return { signalled, browserProcesses: ownedBrowserPids.size, removedMarkers };
+}
+function markerPid(file) {
+  try {
+    const raw = fs.readFileSync(file, "utf8").trim();
+    const value = raw.startsWith("{") ? JSON.parse(raw).pid : raw;
+    const pid = Number(value);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function commandHasExactArg(command, flag, value) {
+  const escapedFlag = escapeRegex(flag);
+  const escapedValue = escapeRegex(value);
+  return [
+    new RegExp(`(?:^|\\s)${escapedFlag}=${escapedValue}(?=\\s|$)`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}="${escapedValue}"(?=\\s|$)`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}='${escapedValue}'(?=\\s|$)`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}\\s+${escapedValue}(?=\\s|$)`, "u")
+  ].some((pattern) => pattern.test(command));
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 export {
   applyKVLines,
+  isExtensionWatcherLive,
   resolveExtensionSlotPorts,
   resolveMobileSlotPorts,
+  stopExtensionRuntime,
   stopExtensionWatcher
 };

package/dist/adapters.js

@@ -465,10 +465,14 @@ function createMetaMaskUiTransport(platform, harness) {
         if (live) return live.output;
         throw new Error(`ui.navigate requires library/actions/${platform}/ui/navigate.mjs.`);
       }
-      return base.execute(action, node, context);
+      return base.execute(action, action === "ui.wait_for" ? normalizeUiWaitNode(node, platform) : node, context);
     }
   };
 }
+function normalizeUiWaitNode(node, adapter) {
+  if (adapter !== "extension" || node.expected !== void 0 || typeof node.visible !== "boolean") return node;
+  return { ...node, expected: node.visible ? "visible" : "absent" };
+}
 function createMetaMaskAdapters(adapter) {
   const platform = adapter;
   const adapters = [
@@ -534,5 +538,6 @@ export {
   createMetaMaskAdapters,
   createMetaMaskUiTransport,
   hideMobileHudOnTeardown,
-  isMobileHudLifecycleSkip
+  isMobileHudLifecycleSkip,
+  normalizeUiWaitNode
 };

package/dist/checkout-lock.js

@@ -0,0 +1,72 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { recipeRuntimeDir } from "./paths.js";
+function acquireCheckoutLock(target, operation) {
+  const repoRoot = fs.realpathSync(target);
+  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) {
+    try {
+      const fd = fs.openSync(lockPath, "wx", 384);
+      const token = inheritedToken || randomUUID();
+      const owner = {
+        schemaVersion: 1,
+        pid: process.pid,
+        operation,
+        repoRoot,
+        token,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      fs.writeFileSync(fd, `${JSON.stringify(owner, null, 2)}
+`);
+      fs.closeSync(fd);
+      if (!inheritedToken) process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN = token;
+      return {
+        path: lockPath,
+        release: () => {
+          const current = readOwner(lockPath);
+          if (current?.pid === process.pid && current.token === token) fs.rmSync(lockPath, { force: true });
+          if (!inheritedToken && process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN === token) {
+            delete process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
+          }
+        }
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const owner = readOwner(lockPath);
+      if (inheritedToken && owner?.token === inheritedToken && owner.repoRoot === repoRoot && typeof owner.pid === "number" && processAlive(owner.pid)) {
+        return { path: lockPath, release: () => void 0 };
+      }
+      if (owner && typeof owner.pid === "number" && processAlive(owner.pid)) {
+        return {
+          path: lockPath,
+          owner,
+          message: `checkout sandbox is busy with ${String(owner.operation ?? "another operation")} (pid ${owner.pid}).`
+        };
+      }
+      fs.rmSync(lockPath, { force: true });
+    }
+  }
+  return { path: lockPath, owner: readOwner(lockPath), message: "checkout sandbox lock could not be acquired." };
+}
+function readOwner(lockPath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+export {
+  acquireCheckoutLock
+};

package/dist/cli.js

@@ -20,6 +20,7 @@ import { handleFixtures } from "./commands/fixtures.js";
 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 { parseArgs, targetPath } from "./commands/parse-args.js";
 import { runOneNode } from "./commands/run-engine.js";
 const COMMANDS = {
@@ -131,6 +132,7 @@ async function main(argv) {
   if (command === "fixtures") return handleFixtures(argv.slice(1), { runOneNode });
   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));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);
   return handler(parseArgs(argv.slice(1), command));

package/dist/commands/call.js

@@ -6,7 +6,7 @@ import { loadActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
 import { recipeRunning } from "../heal-bounds.js";
 import { color } from "../cli-color.js";
-import { EXIT } from "./shared.js";
+import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
 import { describeManifestActions, fuzzyResolveActions } from "./manifest.js";
 import {
   parseArgs,
@@ -25,11 +25,13 @@ import {
   emitHealViolation,
   executeWithHealBounds,
   prepareHeal,
+  recoverRunInfra,
   resolveMetaMaskLibrarySources,
   runRecipe,
   synthesizeOneNodeRecipe,
   validateRecipeAdapterAware
 } from "./run-engine.js";
+import { acquireCheckoutLock } from "../checkout-lock.js";
 async function handleCall(argv) {
   if (argv.includes("--list")) {
     const { options: options2 } = parseArgs(argv, "call");
@@ -63,6 +65,14 @@ async function handleCall(argv) {
     return EXIT.usage;
   }
   const { adapter, target } = resolveAdapter(options);
+  if (!fs.existsSync(target)) {
+    return usageOut(
+      json,
+      "call",
+      `target does not exist: ${target}`,
+      "pass --target <metamask-checkout> pointing to an existing checkout"
+    );
+  }
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("call", adapter, options, { gate: true, rerun: "" });
   if ("code" in dtResult) {
@@ -119,65 +129,76 @@ async function handleCall(argv) {
     }
     return EXIT.validation;
   }
-  const prepared = await prepareHeal(adapter, target, options, json);
-  if (typeof prepared === "number") return prepared;
-  const { state, heal } = prepared;
-  const scratch = await mkdtemp(path.join(os.tmpdir(), "mm-harness-call-"));
-  const recipeFile = path.join(scratch, "call.recipe.json");
-  fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}
+  const lock = acquireCheckoutLock(target, "call");
+  if ("message" in lock) {
+    return checkoutBusyOut(json, "call", lock.message, lock.path);
+  }
+  try {
+    const prepared = await prepareHeal(adapter, target, options, json, {
+      skipMobileSourceFreshness: adapter === "mobile" && resolvedAction === "app.lifecycle"
+    });
+    if (typeof prepared === "number") return prepared;
+    const { state, heal } = prepared;
+    const scratch = await mkdtemp(path.join(os.tmpdir(), "mm-harness-call-"));
+    const recipeFile = path.join(scratch, "call.recipe.json");
+    fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}
 `);
-  const artifactsDir = optionString(options, "artifactsDir") ?? path.join(scratch, "artifacts");
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
-  const callRuntimeOptions = {
-    ...runtimeOptionsFromCli(options),
-    ...librarySources ? { librarySources } : {},
-    stdoutIsMachineContract: json
-  };
-  const { result, violation } = await executeWithHealBounds(
-    () => runRecipe(adapter, recipeFile, artifactsDir, target, actionManifestOverride, callRuntimeOptions),
-    adapter,
-    target,
-    heal,
-    state
-  );
-  if (violation !== null) return emitHealViolation(json, "call", result, violation, state, adapter);
-  const callOutput = readCallOutput(result.tracePath);
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: "call",
-          adapter,
-          action: shortName,
-          resolvedAction,
-          args,
-          status: result.status,
-          summaryPath: result.summaryPath,
-          tracePath: result.tracePath,
-          artifactManifestPath: result.artifactManifestPath,
-          ...callOutput !== void 0 ? { output: callOutput } : {},
-          recovered: state.recovered,
-          mutations: state.mutations,
-          exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime
-        },
-        null,
-        2
-      )
+    const artifactsDir = optionString(options, "artifactsDir") ?? path.join(scratch, "artifacts");
+    const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+    const callRuntimeOptions = {
+      ...runtimeOptionsFromCli(options),
+      ...librarySources ? { librarySources } : {},
+      stdoutIsMachineContract: json
+    };
+    const { result, violation } = await executeWithHealBounds(
+      () => runRecipe(adapter, recipeFile, artifactsDir, target, actionManifestOverride, callRuntimeOptions),
+      adapter,
+      target,
+      heal,
+      state,
+      () => recoverRunInfra(adapter, target, json)
     );
-  } else {
-    const rendered = callOutput !== void 0 ? `
+    if (violation !== null) return emitHealViolation(json, "call", result, violation, state, adapter);
+    const callOutput = readCallOutput(result.tracePath);
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            command: "call",
+            adapter,
+            action: shortName,
+            resolvedAction,
+            args,
+            status: result.status,
+            summaryPath: result.summaryPath,
+            tracePath: result.tracePath,
+            artifactManifestPath: result.artifactManifestPath,
+            ...callOutput !== void 0 ? { output: callOutput } : {},
+            recovered: state.recovered,
+            mutations: state.mutations,
+            exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      const rendered = callOutput !== void 0 ? `
 Result:
 ${formatCallOutput(callOutput)}` : "";
-    const out = (style, text) => color(style, text, { stream: process.stdout });
-    console.log(
-      `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
+      const out = (style, text) => color(style, text, { stream: process.stdout });
+      console.log(
+        `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
 ${out("label", "Result:")}
 ${formatCallOutput(callOutput)}` : ""}
 ${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
-    );
+      );
+    }
+    return result.status === "pass" ? EXIT.ok : EXIT.runtime;
+  } finally {
+    lock.release();
   }
-  return result.status === "pass" ? EXIT.ok : EXIT.runtime;
 }
 function readCallOutput(tracePath) {
   try {
@@ -281,7 +302,7 @@ function parseCallArgs(argv) {
       if (pair === void 0) throw usageError("--arg requires k=v.");
       const eq = pair.indexOf("=");
       if (eq === -1) throw usageError(`--arg must be k=v: ${pair}`);
-      args[pair.slice(0, eq)] = pair.slice(eq + 1);
+      args[pair.slice(0, eq)] = parseCallValue(pair.slice(eq + 1));
       continue;
     }
     if (!arg.startsWith("--") && action === void 0) {
@@ -290,13 +311,29 @@ function parseCallArgs(argv) {
     }
     if (action !== void 0 && !isForwardedOptionValue(argv, i) && isArgPair(arg)) {
       const eq = arg.indexOf("=");
-      args[arg.slice(0, eq)] = arg.slice(eq + 1);
+      args[arg.slice(0, eq)] = parseCallValue(arg.slice(eq + 1));
       continue;
     }
     rest.push(arg);
   }
   return { action, args, rest };
 }
+function parseCallValue(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value === "null") return null;
+  if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/u.test(value)) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  if (value.startsWith("[") && value.endsWith("]") || value.startsWith("{") && value.endsWith("}") || value.startsWith('"') && value.endsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+    }
+  }
+  return value;
+}
 function isArgPair(value) {
   const eq = value.indexOf("=");
   return eq > 0;