@deeeed/metamask-harness 0.17.3 → 0.17.5

package/dist/doctor.js

@@ -93,7 +93,10 @@ function fixtureFileSummary(file, adapter, reportedPath = file) {
 const RUNTIME_CONTEXT_FIELDS = [
   { key: "slotId", envVars: ["RECIPE_SLOT_ID"], envVar: "RECIPE_SLOT_ID", customize: "doctor --fix creates local identity; Farmslot may override", adapters: ["mobile", "extension", "core"] },
   { key: "extensionId", envVars: ["RECIPE_HARNESS_EXTENSION_ID"], envVar: "RECIPE_HARNESS_EXTENSION_ID", customize: "resolved from the built extension", adapters: ["extension"] },
-  { key: "cdpPort", envVars: ["RECIPE_CDP_PORT", "CDP_PORT"], envVar: "CDP_PORT", customize: "doctor --fix claims one; --cdp-port overrides", adapters: ["extension"] }
+  { key: "cdpPort", envVars: ["RECIPE_CDP_PORT", "CDP_PORT"], envVar: "CDP_PORT", customize: "doctor --fix claims one; --cdp-port overrides", adapters: ["extension"] },
+  { key: "runtimeStart.approved", envVars: ["RECIPE_RUNTIME_START_APPROVED"], envVar: "RECIPE_RUNTIME_START_APPROVED", customize: "optional orchestrator-provided legacy live context", adapters: ["mobile", "extension"] },
+  { key: "runtimeStart.command", envVars: [], envVar: null, customize: "optional orchestrator-provided legacy live context", adapters: ["mobile", "extension"] },
+  { key: "runtimeStart.readyUrl", envVars: ["RECIPE_RUNTIME_READY_URL"], envVar: "RECIPE_RUNTIME_READY_URL", customize: "optional orchestrator-provided legacy live context", adapters: ["mobile", "extension"] }
 ];
 function runtimeContextSummary(target, adapter) {
   const contextPath = resolveRuntimeContextPath(target);

package/dist/harness.js

@@ -4,8 +4,13 @@ import path from "node:path";
 import { resolveLeafInvoke, shellLeafMissing, missingShellLeafMessage } from "./leaf-invoke.js";
 import { resolveExtensionSlotPorts } from "./adapters/slot-ports.js";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "./paths.js";
-const HARNESS_ACTIONS = ["install", "verify", "cleanup"];
+import { prepareMobile } from "./adapters/mobile/prepare.js";
+const HARNESS_ACTIONS = ["install", "verify", "cleanup", "live"];
 const ADAPTERS = ["mobile", "extension", "core"];
+function isValidAdapterAction(adapter, action) {
+  if (adapter === "core") return action === "install" || action === "verify" || action === "cleanup";
+  return true;
+}
 function harnessUsage() {
   console.error(`mm-harness \u2014 install and validate the MetaMask recipe runtime in a checkout.
 
@@ -45,12 +50,6 @@ function failureHint(adapter, action) {
   const helper = adapter === "mobile" ? "mm-harness launch ios   # or launch android" : "mm-harness launch";
   return `Read the error above for the specific cause. To (re)start the runtime, run: ${helper}`;
 }
-function successNext(adapter, action, target) {
-  const base = `--adapter ${adapter} --target ${shellQuote(target)}`;
-  if (action === "install") return `mm-harness verify ${base}`;
-  if (action === "cleanup") return `mm-harness install ${base}`;
-  return `mm-harness status --target ${shellQuote(target)} --json`;
-}
 function hasArg(args, needle) {
   return args.some((arg) => arg === needle || arg.startsWith(`${needle}=`));
 }
@@ -71,7 +70,6 @@ function parseHarnessArgs(args) {
   const forward = [];
   let adapter;
   let json = false;
-  let quiet = false;
   let separator = false;
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -87,10 +85,6 @@ function parseHarnessArgs(args) {
       json = true;
       continue;
     }
-    if (arg === "--quiet") {
-      quiet = true;
-      continue;
-    }
     if (arg === "--adapter" || arg === "--platform") {
       const value = args[i + 1];
       if (arg === "--adapter") {
@@ -121,7 +115,7 @@ function parseHarnessArgs(args) {
     }
     forward.push(arg);
   }
-  return { adapter, json, quiet, forward };
+  return { adapter, json, forward };
 }
 const ADAPTER_DETECT_NEXT = "cd into a MetaMask checkout or pass --target <path>, or force it with --adapter <mobile|extension|core>";
 function detectAdapter(target) {
@@ -167,7 +161,7 @@ function readRuntimeContextField(contextPath, field) {
   if (node === void 0 || node === null || node === "") return void 0;
   return String(node);
 }
-function applyExtensionRuntimeEnv(target, args) {
+function applyExtensionRuntimeEnv(target, action, args) {
   const contextPath = resolveRuntimeContextPath(target);
   const contextExists = fs.existsSync(contextPath);
   if (contextExists) {
@@ -180,6 +174,19 @@ function applyExtensionRuntimeEnv(target, args) {
       const extensionId = readRuntimeContextField(contextPath, "extensionId");
       if (extensionId) process.env.RECIPE_HARNESS_EXTENSION_ID = extensionId;
     }
+    if (process.env.RECIPE_RUNTIME_START_APPROVED === void 0) {
+      const approved = readRuntimeContextField(contextPath, "runtimeStart.approved");
+      if (approved === "true" || approved === "True" || approved === "1") process.env.RECIPE_RUNTIME_START_APPROVED = "1";
+      else if (approved === "false" || approved === "False" || approved === "0") process.env.RECIPE_RUNTIME_START_APPROVED = "0";
+    }
+    if (!process.env.RECIPE_RUNTIME_START_CMD) {
+      const command = readRuntimeContextField(contextPath, "runtimeStart.command");
+      if (command) process.env.RECIPE_RUNTIME_START_CMD = command;
+    }
+    if (!process.env.RECIPE_RUNTIME_READY_URL) {
+      const readyUrl = readRuntimeContextField(contextPath, "runtimeStart.readyUrl");
+      if (readyUrl) process.env.RECIPE_RUNTIME_READY_URL = readyUrl;
+    }
   } else {
     delete process.env.RECIPE_RUNTIME_CONTEXT;
   }
@@ -193,6 +200,11 @@ function applyExtensionRuntimeEnv(target, args) {
       result = [...result, "--cdp-port", cdpPort];
     }
   }
+  if (action === "live" && !hasArg(result, "--prepare-cmd")) {
+    if (process.env.RECIPE_RUNTIME_START_APPROVED === "1" && process.env.RECIPE_RUNTIME_START_CMD) {
+      result = [...result, "--prepare-cmd", process.env.RECIPE_RUNTIME_START_CMD];
+    }
+  }
   return result;
 }
 function resolveEntry(base, candidates, mode) {
@@ -269,6 +281,81 @@ Next: mm-harness install --platform core --target ${target}`
   );
   return { command, prefixArgs: [] };
 }
+async function handleMobileLive(target, forwardArgs, json, autoDetected) {
+  const platform = argValue(forwardArgs, "--platform") ?? "ios";
+  const watcherPortStr = argValue(forwardArgs, "--watcher-port") ?? process.env.WATCHER_PORT;
+  const watcherPort = watcherPortStr ? parseInt(watcherPortStr, 10) : void 0;
+  const start = Date.now();
+  if (!json) {
+    const detected = autoDetected ? ", auto-detected" : "";
+    console.error(`\u2192 live (mobile${detected}) \u2014 target: ${target}`);
+  }
+  const prepResult = await prepareMobile(target, { platform, json, watcherPort });
+  if (prepResult.status !== 0) {
+    const elapsed2 = ((Date.now() - start) / 1e3).toFixed(1);
+    if (json) {
+      console.log(
+        harnessSummary("live", "mobile", target, "fail", prepResult.status, autoDetected, {
+          code: "MOBILE_PREPARE_FAILED",
+          message: `mobile prepare failed (exit ${prepResult.status})`,
+          userAction: failureHint("mobile", "live")
+        })
+      );
+    } else {
+      console.error(
+        `\u2717 live mobile failed (exit ${prepResult.status}, ${elapsed2}s)
+  ${failureHint("mobile", "live")}`
+      );
+    }
+    return prepResult.status;
+  }
+  const installedVerify = path.join(recipeHarnessPath(target, "mobile"), "scripts", "verify.sh");
+  const verifySh = fs.existsSync(installedVerify) ? installedVerify : resolveEntry(runnerDir, ["adapters/mobile/verify.sh", "scripts/mobile/verify.sh"], "file");
+  const verifyArgs = hasArg(forwardArgs, "--no-auto-start") ? [...forwardArgs] : ["--no-auto-start", ...forwardArgs];
+  if (shellLeafMissing(verifySh)) {
+    const message = missingShellLeafMessage(verifySh);
+    if (json) {
+      console.log(
+        harnessSummary("live", "mobile", target, "fail", 1, autoDetected, {
+          code: "HARNESS_SPAWN_FAILED",
+          message,
+          userAction: failureHint("mobile", "live")
+        })
+      );
+    } else {
+      console.error(`\u2717 ${message}`);
+    }
+    return 1;
+  }
+  const { bin: verifyBin, args: verifySpawnArgs } = resolveLeafInvoke(verifySh, verifyArgs);
+  const result = spawnSync(verifyBin, verifySpawnArgs, {
+    stdio: json ? ["inherit", 2, "inherit"] : "inherit",
+    env: process.env
+  });
+  const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
+  const exitCode = result.status ?? 1;
+  if (json) {
+    console.log(
+      harnessSummary(
+        "live",
+        "mobile",
+        target,
+        exitCode === 0 ? "pass" : "fail",
+        exitCode,
+        autoDetected,
+        exitCode === 0 ? void 0 : { code: "MOBILE_VERIFY_FAILED", message: `mobile live verify failed (exit ${exitCode})`, userAction: failureHint("mobile", "live") }
+      )
+    );
+  } else if (exitCode === 0) {
+    console.error(`\u2713 live mobile passed (${elapsed}s)`);
+  } else {
+    console.error(
+      `\u2717 live mobile failed (exit ${exitCode}, ${elapsed}s)
+  ${failureHint("mobile", "live")}`
+    );
+  }
+  return exitCode;
+}
 async function handleHarness(argv) {
   const action = argv[0];
   if (!action || action === "-h" || action === "--help") {
@@ -281,14 +368,12 @@ async function handleHarness(argv) {
     return 2;
   }
   const harnessAction = action;
-  const { adapter: parsedAdapter, json, quiet, forward } = parseHarnessArgs(argv.slice(1));
+  const { adapter: parsedAdapter, json, forward } = parseHarnessArgs(argv.slice(1));
   const rawTarget = argValue(forward, "--target");
   const target = path.resolve(rawTarget ?? process.cwd());
   const adapter = parsedAdapter ?? detectAdapter(target);
   if (!adapter || !isAdapter(adapter)) {
-    if (quiet) {
-      return 2;
-    } else if (json) {
+    if (json) {
       const detectError = adapter ? { code: "UNSUPPORTED_PLATFORM", message: `unsupported platform: ${adapter}`, userAction: "pass --adapter <mobile|extension|core> to specify a supported adapter" } : { code: "ADAPTER_DETECTION_FAILED", message: `could not detect the MetaMask repo type for ${target}`, userAction: ADAPTER_DETECT_NEXT };
       console.log(harnessSummary(harnessAction, void 0, target, "fail", 2, false, detectError));
     } else {
@@ -302,19 +387,36 @@ async function handleHarness(argv) {
     }
     return 2;
   }
+  if (!isValidAdapterAction(adapter, harnessAction)) {
+    if (json) {
+      console.log(
+        harnessSummary(harnessAction, adapter, target, "fail", 2, parsedAdapter === void 0, {
+          code: "UNSUPPORTED_ACTION",
+          message: `${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`,
+          userAction: "run mm-harness doctor to see which actions are supported for this adapter"
+        })
+      );
+    } else {
+      console.error(
+        `\u2717 ${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`
+      );
+    }
+    return 2;
+  }
   const autoDetected = parsedAdapter === void 0;
   let forwardArgs = hasArg(forward, "--target") ? [...forward] : ["--target", target, ...forward];
   if (harnessAction === "install" && hasArg(forward, "--runway")) {
     return handleRunwayInstall(adapter, target, forward, json);
   }
-  if (adapter === "extension" && harnessAction === "verify") {
-    forwardArgs = applyExtensionRuntimeEnv(target, forwardArgs);
+  if (adapter === "extension" && (harnessAction === "live" || harnessAction === "verify")) {
+    forwardArgs = applyExtensionRuntimeEnv(target, harnessAction, forwardArgs);
+  }
+  if (adapter === "mobile" && harnessAction === "live") {
+    return handleMobileLive(target, forwardArgs, json, autoDetected);
   }
   const dispatch = resolveHarnessDispatch(adapter, harnessAction, target);
   if ("error" in dispatch) {
-    if (quiet) {
-      return 1;
-    } else if (json) {
+    if (json) {
       console.log(
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "DISPATCH_UNAVAILABLE",
@@ -330,16 +432,14 @@ async function handleHarness(argv) {
     }
     return 1;
   }
-  if (!json && !quiet) {
+  if (!json) {
     const detected = autoDetected ? ", auto-detected" : "";
     console.error(`\u2192 ${harnessAction} (${adapter}${detected}) \u2014 target: ${target}`);
   }
   const start = Date.now();
   if (shellLeafMissing(dispatch.command)) {
     const message = missingShellLeafMessage(dispatch.command);
-    if (quiet) {
-      return 1;
-    } else if (json) {
+    if (json) {
       console.log(
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "HARNESS_SPAWN_FAILED",
@@ -359,14 +459,12 @@ async function handleHarness(argv) {
   const result = spawnSync(dispatchBin, dispatchArgs, {
     // Default: stream child output verbatim (byte-identical to the skill path).
     // --json: route child output to our stderr so stdout carries only the summary.
-    stdio: quiet ? "ignore" : json ? ["inherit", 2, "inherit"] : "inherit",
+    stdio: json ? ["inherit", 2, "inherit"] : "inherit",
     env: process.env
   });
   const seconds = ((Date.now() - start) / 1e3).toFixed(1);
   if (result.error) {
-    if (quiet) {
-      return 1;
-    } else if (json) {
+    if (json) {
       console.log(
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "HARNESS_SPAWN_FAILED",
@@ -381,9 +479,7 @@ async function handleHarness(argv) {
     return 1;
   }
   const exitCode = result.status ?? 1;
-  if (quiet) {
-    return exitCode;
-  } else if (json) {
+  if (json) {
     console.log(
       harnessSummary(
         harnessAction,
@@ -396,8 +492,7 @@ async function handleHarness(argv) {
       )
     );
   } else if (exitCode === 0) {
-    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)
-  Next: ${successNext(adapter, harnessAction, target)}`);
+    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)`);
   } else {
     console.error(`\u2717 ${harnessAction} ${adapter} failed (exit ${exitCode}, ${seconds}s)
   ${failureHint(adapter, harnessAction)}`);
@@ -427,10 +522,8 @@ async function handleRunwayInstall(adapter, target, forward, json) {
     resolveOnly: hasArg(forward, "--resolve-only"),
     rerunCommand
   });
-  const next = result.status === "pass" && adapter === "mobile" && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? "ios")} --adapter mobile --target ${shellQuote(target)}` : void 0;
-  const output = next ? { ...result, next } : result;
   if (json) {
-    console.log(JSON.stringify(output, null, 2));
+    console.log(JSON.stringify(result, null, 2));
   } else if (result.status === "pass") {
     const cache = typeof result.cache === "object" && result.cache ? result.cache : void 0;
     const simulator = typeof result.simulator === "object" && result.simulator ? result.simulator : void 0;
@@ -441,7 +534,6 @@ async function handleRunwayInstall(adapter, target, forward, json) {
       const action = result.skipped ? "already provisioned" : "installed Runway app";
       console.error(`\u2713 ${action} for ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "skip"}`);
     }
-    if (next) console.error(`  Next: ${next}`);
   } else {
     console.error(`\u2717 mm-harness install --runway: ${result.error?.message ?? "runway install failed"}
   Next: ${result.error?.userAction ?? rerunCommand}`);
@@ -484,10 +576,9 @@ function harnessSummary(action, adapter, target, status, exitCode, autoDetected,
     status,
     exitCode,
     // Error contract: every --json failure carries a stable machine code + human
-    // message. userAction is included when present so callers
+    // message (CLI-SPEC.md §5.1). userAction is included when present so callers
     // can surface the reachable escape without parsing the human message.
-    ...status === "fail" && error ? { error } : {},
-    ...status === "pass" && adapter ? { next: successNext(adapter, action, target) } : {}
+    ...status === "fail" && error ? { error } : {}
   });
 }
 export {

package/dist/heal-bounds.js

@@ -103,7 +103,7 @@ function checkHealBounds(target, output, state) {
     return {
       code: "SAME_RECOVERY_TWICE",
       exitCode: EXIT.bounded,
-      message: state.recovered.length > 0 ? "one recovery already succeeded this invocation \u2014 bounded policy refuses a second recovery." : "one recovery was already attempted this invocation \u2014 refusing to loop.",
+      message: "same recovery already failed once this invocation \u2014 refusing to loop.",
       originalError
     };
   }

package/dist/live-adapter-contract.js

@@ -46,16 +46,29 @@ function candidatePaths(platform, action) {
       }
       pushDomainDispatcherFiles(files, root, platform, family);
     }
+    for (const candidateStem of stems) {
+      pushFlatCandidateFiles(files, root, platform, candidateStem);
+    }
   }
   return files;
 }
 function pushCandidateFiles(files, root, platform, family, stem) {
-  files.push(path.join(root, platform, family, `${stem}.mjs`));
-  files.push(path.join(root, "shared", family, `${stem}.mjs`));
+  for (const extension of ["mjs", "js", "sh"]) {
+    files.push(path.join(root, platform, family, `${stem}.${extension}`));
+    files.push(path.join(root, "shared", family, `${stem}.${extension}`));
+  }
 }
 function pushDomainDispatcherFiles(files, root, platform, family) {
-  files.push(path.join(root, platform, family, `${family}.mjs`));
-  files.push(path.join(root, "shared", family, `${family}.mjs`));
+  for (const extension of ["mjs", "js", "sh"]) {
+    files.push(path.join(root, platform, family, `${family}.${extension}`));
+    files.push(path.join(root, "shared", family, `${family}.${extension}`));
+  }
+}
+function pushFlatCandidateFiles(files, root, platform, stem) {
+  for (const extension of ["mjs", "js", "sh"]) {
+    files.push(path.join(root, platform, `${stem}.${extension}`));
+    files.push(path.join(root, "shared", `${stem}.${extension}`));
+  }
 }
 async function firstExecutablePath(paths) {
   for (const file of paths) {
@@ -107,8 +120,9 @@ function runProcess(command, args, options) {
   });
 }
 function commandFor(file, projectRoot, platform) {
+  if (file.endsWith(".sh")) return { command: "bash", args: [file] };
   const needsTsx = platform === "core" || importsSourceTypescript(file);
-  if (!needsTsx) {
+  if (!needsTsx && (file.endsWith(".mjs") || file.endsWith(".js"))) {
     return { command: process.execPath, args: [file] };
   }
   const tsxBin = resolveTsxBin(projectRoot);
@@ -151,7 +165,7 @@ function importsSourceTypescriptFrom(file, visited) {
     const specifier = match[1] ?? "";
     if (specifier.endsWith(".ts")) return true;
     if (!specifier.startsWith(".")) continue;
-    if (!specifier.endsWith(".mjs")) continue;
+    if (!specifier.endsWith(".mjs") && !specifier.endsWith(".js")) continue;
     if (importsSourceTypescriptFrom(path.resolve(path.dirname(absolute), specifier), visited)) {
       return true;
     }