@deeeed/metamask-harness 0.70.1 → 0.72.0

package/dist/adapters/console-capture.js

@@ -0,0 +1,122 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  collectorMatches,
+  collectorOwnerMarker,
+  isLegacyCollector,
+  isOwnedCollector,
+  isPriorInstallCollector,
+  processArgs,
+  processCommand,
+  readPid
+} from "../../library/actions/shared/console-collector.mjs";
+import { runnerDir } from "../paths.js";
+const COLLECTOR_SCRIPT = path.join(runnerDir, "adapters", "extension", "console-tail.mjs");
+async function ensureConsoleCollector(options) {
+  const { cdpPort, extensionLog, pageLog, collectorLog, pidFile } = options;
+  fs.mkdirSync(path.dirname(extensionLog), { recursive: true });
+  const marker = collectorOwnerMarker(path.dirname(pidFile));
+  const identity = { script: COLLECTOR_SCRIPT, cdpPort, extensionLog, pageLog, marker };
+  const existingPid = readPid(pidFile);
+  const existing = existingPid ? processArgs(existingPid) : null;
+  if (existingPid && existing && isOwnedCollector(existing, identity)) {
+    if (collectorMatches(existing, identity) && collectorIsCurrent(existingPid, COLLECTOR_SCRIPT)) return { pid: existingPid, reused: true };
+    await stopProcess(existingPid);
+  } else if (existingPid && existing && isLegacyCollector(existing, identity)) {
+    await stopProcess(existingPid);
+  } else if (existingPid && existing && isPriorInstallCollector(existing, identity)) {
+    await stopProcess(existingPid);
+  }
+  for (const log of [extensionLog, pageLog]) {
+    rotateLargeLog(log);
+    fs.closeSync(fs.openSync(log, "a"));
+  }
+  const output = fs.openSync(collectorLog, "a");
+  let child;
+  try {
+    child = spawn(process.execPath, [
+      COLLECTOR_SCRIPT,
+      "--cdp-port",
+      cdpPort,
+      "--extension-log",
+      extensionLog,
+      "--dapp-log",
+      pageLog,
+      marker
+    ], {
+      cwd: options.cwd,
+      detached: true,
+      stdio: ["ignore", output, output]
+    });
+  } finally {
+    fs.closeSync(output);
+  }
+  if (!child.pid) throw new Error("Console collector did not start.");
+  child.unref();
+  fs.writeFileSync(pidFile, `${child.pid}
+`);
+  const attachmentFrom = { [extensionLog]: fileSize(extensionLog), [pageLog]: fileSize(pageLog) };
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const proc = processArgs(child.pid);
+    if (!proc) break;
+    if (collectorMatches(proc, identity)) {
+      if (!options.waitForAttachment) return { pid: child.pid, reused: false };
+      if (containsAttachment(attachmentFrom)) return { pid: child.pid, reused: false };
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(
+    options.waitForAttachment ? `Console collector ${child.pid} did not attach to CDP ${cdpPort}.` : `Console collector ${child.pid} exited right after starting (see ${collectorLog}).`
+  );
+}
+async function stopProcess(pid) {
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return;
+  }
+  for (let attempt = 0; attempt < 30 && processCommand(pid); attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
+const ROTATE_LOG_BYTES = 32 * 1024 * 1024;
+function rotateLargeLog(file) {
+  if (fileSize(file) < ROTATE_LOG_BYTES) return;
+  try {
+    fs.renameSync(file, `${file}.1`);
+  } catch {
+  }
+}
+function fileSize(file) {
+  try {
+    return fs.statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+function collectorIsCurrent(pid, script) {
+  const result = spawnSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", env: { ...process.env, LC_ALL: "C" } });
+  const startedAt = Date.parse(result.stdout.trim());
+  if (!Number.isFinite(startedAt)) return false;
+  try {
+    return startedAt >= fs.statSync(script).mtimeMs - 1e3;
+  } catch {
+    return false;
+  }
+}
+function containsAttachment(from) {
+  return Object.entries(from).some(([log, offset]) => {
+    try {
+      const text = fs.readFileSync(log);
+      return text.subarray(Math.min(offset, text.length)).includes("[attached]");
+    } catch {
+      return false;
+    }
+  });
+}
+export {
+  COLLECTOR_SCRIPT,
+  ROTATE_LOG_BYTES,
+  ensureConsoleCollector
+};

package/dist/adapters/extension/console-capture.js

@@ -1,95 +1,32 @@
-import { spawn, spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-import { recipeRuntimePath, runnerDir } from "../../paths.js";
+import { recipeRuntimePath } from "../../paths.js";
+import { ensureConsoleCollector } from "../console-capture.js";
+function extensionCaptureFiles(target) {
+  return {
+    extensionLog: recipeRuntimePath(target, "extension-console.log"),
+    pageLog: recipeRuntimePath(target, "dapp-console.log"),
+    collectorLog: recipeRuntimePath(target, "console-tail.log"),
+    pidFile: recipeRuntimePath(target, "console-tail.pid")
+  };
+}
+function extensionCdpPort() {
+  return process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+}
 async function ensureExtensionConsoleCapture(target) {
-  const cdpPort = process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  const cdpPort = extensionCdpPort();
   if (!cdpPort) throw new Error("Extension console capture requires a resolved CDP port.");
   const response = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
     signal: AbortSignal.timeout(3e3)
   });
   if (!response.ok) throw new Error(`Extension CDP ${cdpPort} is not ready for console capture.`);
-  const extensionLog = recipeRuntimePath(target, "extension-console.log");
-  const dappLog = recipeRuntimePath(target, "dapp-console.log");
-  const collectorLog = recipeRuntimePath(target, "console-tail.log");
-  const pidFile = recipeRuntimePath(target, "console-tail.pid");
-  fs.mkdirSync(path.dirname(extensionLog), { recursive: true });
-  const existingPid = readPid(pidFile);
-  if (existingPid && collectorOwnsLog(existingPid, extensionLog)) return;
-  if (existingPid) {
-    try {
-      process.kill(existingPid, "SIGTERM");
-    } catch {
-    }
-  }
-  fs.rmSync(pidFile, { force: true });
-  fs.writeFileSync(extensionLog, "");
-  fs.writeFileSync(dappLog, "");
-  const script = path.join(runnerDir, "adapters", "extension", "console-tail.mjs");
-  const output = fs.openSync(collectorLog, "a");
-  let child;
-  try {
-    child = spawn(process.execPath, [
-      script,
-      "--cdp-port",
-      cdpPort,
-      "--extension-log",
-      extensionLog,
-      "--dapp-log",
-      dappLog
-    ], {
-      cwd: target,
-      detached: true,
-      stdio: ["ignore", output, output]
-    });
-  } finally {
-    fs.closeSync(output);
-  }
-  if (!child.pid) throw new Error("Extension console collector did not start.");
-  child.unref();
-  fs.writeFileSync(pidFile, `${child.pid}
-`);
-  for (let attempt = 0; attempt < 100; attempt += 1) {
-    if (!processAlive(child.pid)) break;
-    if (collectorOwnsLog(child.pid, extensionLog) && containsAttachment(extensionLog, dappLog)) return;
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-  throw new Error(`Extension console collector ${child.pid} did not attach to CDP ${cdpPort}.`);
-}
-function processAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function readPid(pidFile) {
-  try {
-    const pid = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
-    return Number.isInteger(pid) && pid > 0 ? pid : null;
-  } catch {
-    return null;
-  }
-}
-function collectorOwnsLog(pid, extensionLog) {
-  try {
-    process.kill(pid, 0);
-  } catch {
-    return false;
-  }
-  const result = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
-  return result.status === 0 && result.stdout.includes("console-tail.mjs") && result.stdout.includes(extensionLog);
-}
-function containsAttachment(...logs) {
-  return logs.some((log) => {
-    try {
-      return fs.readFileSync(log, "utf8").includes("[attached]");
-    } catch {
-      return false;
-    }
+  await ensureConsoleCollector({
+    cdpPort,
+    ...extensionCaptureFiles(target),
+    waitForAttachment: true,
+    cwd: target
   });
 }
 export {
-  ensureExtensionConsoleCapture
+  ensureExtensionConsoleCapture,
+  extensionCaptureFiles,
+  extensionCdpPort
 };

package/dist/adapters/mobile/verify.js

@@ -12,7 +12,11 @@ const AUTO_START_TRUE = ["1", "true", "TRUE", "True", "yes", "YES", "Yes", "on",
 const AUTO_START_FALSE = ["0", "false", "FALSE", "False", "no", "NO", "No", "off", "OFF", "Off", ""];
 const AUTO_START_REFUSAL = "Mobile auto-start is not allowed from product-local scripts. Start or prepare the app through the runner/slot runtime, then rerun verify with --no-auto-start.";
 const EVM_READINESS_EXPRESSION = "(async function(){try{var engine=globalThis.Engine;var controller=engine&&engine.context&&engine.context.NetworkController;if(!controller||typeof controller.getSelectedNetworkClient!=='function')throw new Error('NetworkController selected client is unavailable');var client=controller.getSelectedNetworkClient();if(!client||!client.provider||typeof client.provider.request!=='function')throw new Error('selected EVM provider is unavailable');var result=await client.provider.request({method:'eth_blockNumber'});if(typeof result!=='string'||!/^0x[0-9a-f]+$/i.test(result))throw new Error('eth_blockNumber returned an invalid result');return {ok:true,result:result};}catch(error){return {ok:false,error:error&&(error.message||String(error))};}})()";
-const LIVE_SMOKE_RECIPE = `{
+function liveSmokeProbeTimeoutMs(env = process.env) {
+  const value = Number(env.MM_HARNESS_MOBILE_VERIFY_PROBE_TIMEOUT_MS);
+  return Number.isInteger(value) && value > 0 ? value : 6e4;
+}
+const liveSmokeRecipeText = (timeoutMs) => `{
   "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "Mobile v1 runner live bridge smoke",
   "description": "Verifies the installed MetaMask runner can read the React Native debug bridge without mutating wallet state.",
@@ -20,7 +24,7 @@ const LIVE_SMOKE_RECIPE = `{
     "entry": "status",
     "nodes": {
       "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
-      "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "require_reachable": true, "timeout_ms": 60000, "cdp_timeout_ms": 60000, "next": "done" },
+      "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "require_reachable": true, "timeout_ms": ${timeoutMs}, "cdp_timeout_ms": ${timeoutMs}, "next": "done" },
       "done": { "action": "end", "status": "pass" }
     }
   }
@@ -386,7 +390,7 @@ async function runMobileVerify(argv, io = defaultIo) {
       }
     }
     const liveSmokeRecipe = path.join(artifacts, "mobile-v1-live-smoke.recipe.json");
-    fs.writeFileSync(liveSmokeRecipe, LIVE_SMOKE_RECIPE);
+    fs.writeFileSync(liveSmokeRecipe, liveSmokeRecipeText(liveSmokeProbeTimeoutMs()));
     const iosSimulatorResolved = resolveJsEnvValue(target, "IOS_SIMULATOR");
     const adbSerialResolved = resolveJsEnvValue(target, "ADB_SERIAL");
     let liveSmokeCode = 1;
@@ -495,6 +499,7 @@ export {
   buildMobileVerifySummary,
   classifyMobileRuntimeOwner,
   isNumericWatcherPort,
+  liveSmokeProbeTimeoutMs,
   parseMobileVerifyArgs,
   resolveJsEnvValue,
   resolveWatcherPort,

package/dist/adapters/surface.js

@@ -1,10 +1,12 @@
 import { coreSurface } from "./core/surface.js";
 import { extensionSurface } from "./extension/surface.js";
 import { mobileSurface } from "./mobile/surface.js";
+import { terminalSurface } from "./terminal/surface.js";
 const SURFACES = {
   mobile: mobileSurface,
   extension: extensionSurface,
-  core: coreSurface
+  core: coreSurface,
+  terminal: terminalSurface
 };
 function getAdapterSurface(adapter) {
   return SURFACES[adapter];

package/dist/adapters/terminal/console-capture.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+import { recipeRuntimePath } from "../../paths.js";
+import { ensureConsoleCollector } from "../console-capture.js";
+const TERMINAL_CONSOLE_FILES = Object.freeze({
+  app: "app-console.log",
+  extension: "extension-console.log",
+  collectorLog: "console-tail.log",
+  pidFile: "console-tail.pid"
+});
+function terminalRuntimeFile(target, name) {
+  let root = path.resolve(target);
+  try {
+    root = fs.realpathSync(root);
+  } catch {
+  }
+  return recipeRuntimePath(root, "terminal", name);
+}
+function terminalCaptureFiles(target) {
+  return {
+    extensionLog: terminalRuntimeFile(target, TERMINAL_CONSOLE_FILES.extension),
+    pageLog: terminalRuntimeFile(target, TERMINAL_CONSOLE_FILES.app),
+    collectorLog: terminalRuntimeFile(target, TERMINAL_CONSOLE_FILES.collectorLog),
+    pidFile: terminalRuntimeFile(target, TERMINAL_CONSOLE_FILES.pidFile)
+  };
+}
+function terminalCdpPort() {
+  return process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
+}
+async function ensureTerminalConsoleCapture(target) {
+  const cdpPort = terminalCdpPort();
+  if (!cdpPort) throw new Error("Terminal console capture requires the slot CDP port.");
+  await ensureConsoleCollector({
+    cdpPort,
+    ...terminalCaptureFiles(target),
+    waitForAttachment: false,
+    cwd: target
+  });
+}
+export {
+  TERMINAL_CONSOLE_FILES,
+  ensureTerminalConsoleCapture,
+  terminalCaptureFiles,
+  terminalCdpPort,
+  terminalRuntimeFile
+};

package/dist/adapters/terminal/stop.js

@@ -0,0 +1,19 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { runnerDir } from "../../paths.js";
+function stopTerminalBrowserSync(target) {
+  const args = [path.join(runnerDir, "adapters", "terminal", "stop.mjs"), "--target", path.resolve(target)];
+  const cdpPort = process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
+  if (cdpPort) args.push("--cdp-port", cdpPort);
+  const result = spawnSync(process.execPath, args, { encoding: "utf8" });
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  const status = result.status ?? 1;
+  return {
+    status,
+    summary: status === 0 ? "terminal browser and wallet host stopped" : "terminal browser stop failed",
+    output
+  };
+}
+export {
+  stopTerminalBrowserSync
+};

package/dist/adapters/terminal/surface.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import { shellQuote } from "../../commands/parse-args.js";
+import fs from "node:fs";
+import { TERMINAL_CONSOLE_FILES, terminalRuntimeFile } from "./console-capture.js";
+import { stopTerminalBrowserSync } from "./stop.js";
+function portFromEnv(...names) {
+  for (const name of names) {
+    const raw = process.env[name];
+    if (raw && /^\d+$/u.test(raw)) return Number(raw);
+  }
+  return void 0;
+}
+function terminalAppPort() {
+  return portFromEnv("TERMINAL_APP_PORT", "RECIPE_WATCHER_PORT", "WATCHER_PORT");
+}
+function terminalCdpPort() {
+  return portFromEnv("RECIPE_CDP_PORT", "CDP_PORT");
+}
+function terminalSignerFor(target) {
+  try {
+    const state = JSON.parse(fs.readFileSync(terminalRuntimeFile(target, "browser.json"), "utf8"));
+    if (typeof state.signer === "string") return state.signer;
+  } catch {
+  }
+  return process.env.TERMINAL_SIGNER || "extension";
+}
+const terminalSurface = {
+  adapter: "terminal",
+  headless: false,
+  resolveSlotPorts() {
+  },
+  async runtimeStatus(target) {
+    const { terminalReadiness } = await import("../../../adapters/terminal/lib/readiness.mjs");
+    const report = await terminalReadiness({
+      target: path.resolve(target),
+      appPort: terminalAppPort(),
+      cdpPort: terminalCdpPort(),
+      signer: process.env.TERMINAL_SIGNER || "extension"
+    });
+    const blocking = report.checks.filter((check) => check.required && check.status === "fail");
+    const devServer = report.checks.find((check) => check.id === "app-dev-server");
+    return {
+      decision: blocking.length === 0 ? "ready" : "blocked",
+      reasonCode: blocking[0]?.id,
+      reasons: (blocking.length ? blocking : report.checks).map((check) => `${check.id}: ${check.detail}`),
+      nextAction: blocking.length === 0 ? void 0 : blocking[0].id === "app-dev-server" || blocking[0].id === "testnet-forced" ? "start the slot dev server with testnet forced (Farmslot preflight), then retry" : `mm-harness doctor --adapter terminal --target ${shellQuote(path.resolve(target))} --json`,
+      deps: report.checks.find((check) => check.id === "dependencies")?.status === "pass" ? "current" : "missing",
+      devServer: {
+        label: "next",
+        status: devServer?.status === "pass" ? "up" : "down"
+      }
+    };
+  },
+  runwayProvision: {
+    async run(target, options) {
+      return {
+        schemaVersion: 1,
+        command: "provision",
+        adapter: "terminal",
+        target: path.resolve(target),
+        status: "fail",
+        exitCode: 2,
+        error: {
+          code: "UNSUPPORTED_ADAPTER",
+          message: "the Web Terminal is a website; there is no simulator or build to provision.",
+          userAction: options.rerunCommand || "mm-harness launch --adapter terminal"
+        }
+      };
+    }
+  },
+  devServer: {
+    label: "browser",
+    describe: () => "terminal slot browser and wallet host (the Next.js dev server belongs to the slot)",
+    stop(target) {
+      const result = stopTerminalBrowserSync(target);
+      return { kind: "stopped", status: result.status, summary: result.summary, output: result.output };
+    }
+  },
+  logSources(target) {
+    return [
+      { label: "app-console", path: terminalRuntimeFile(target, TERMINAL_CONSOLE_FILES.app) },
+      ...terminalSignerFor(target) === "extension" ? [{ label: "extension-console", path: terminalRuntimeFile(target, TERMINAL_CONSOLE_FILES.extension) }] : [],
+      { label: "wallet-requests", path: terminalRuntimeFile(target, "wallet-requests.jsonl") },
+      { label: "wallet-host", path: terminalRuntimeFile(target, "wallet-host.log") },
+      { label: "browser", path: terminalRuntimeFile(target, "browser.log") },
+      { label: "next", path: path.join(target, "temp/farmslot/next-dev.log") }
+    ];
+  },
+  // The terminal page's console and uncaught exceptions, as the Extension's
+  // diagnostics read the extension console: errors make a run REVIEW.
+  appLogSource(target) {
+    return { label: "app-console", path: terminalRuntimeFile(target, TERMINAL_CONSOLE_FILES.app) };
+  },
+  hints: {
+    launch: "mm-harness launch --adapter terminal --cdp-port <port> --watcher-port <app port>",
+    relaunch: "mm-harness launch --adapter terminal --fresh-profile",
+    runtimeProbeRecovery: (target) => `mm-harness doctor --adapter terminal --target ${shellQuote(path.resolve(target))}`
+  }
+};
+export {
+  terminalAppPort,
+  terminalCdpPort,
+  terminalSurface
+};

package/dist/adapters.js

@@ -121,7 +121,7 @@ function requiresLiveAdapter(platform, action) {
   return LIVE_ONLY_ACTIONS.has(action) || platform === "core" && CORE_ONLY_PERPS_ACTIONS.has(action) || LIVE_ONLY_WALLET_ACTIONS.has(action) || LIVE_ONLY_FEATURE_FLAG_ACTIONS.has(action) || LIVE_ONLY_APP_ACTIONS.has(action);
 }
 function liveRuntimeConfigured(platform, node) {
-  if (platform === "mobile" || platform === "core") return true;
+  if (platform === "mobile" || platform === "core" || platform === "terminal") return true;
   return Boolean(node.cdp_port ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT);
 }
 async function runLiveFirst(platform, action, node, context, forceLive = false, preparedLiveAdapters) {
@@ -895,7 +895,7 @@ function mobileHudStatusLabel(status) {
   if (status === "pass") return "pass";
   return "run";
 }
-function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
+function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters, { hudPolicy = "auto" } = {}) {
   if (platform === "core") {
     return {
       async execute(action) {
@@ -905,7 +905,23 @@ function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
       }
     };
   }
-  const base = platform === "mobile" ? harness.createReactNativeBridgeUiTransport({ bridge: createMetaMaskMobileBridge() }) : harness.createCdpWebUiTransport({
+  const base = platform === "mobile" ? harness.createReactNativeBridgeUiTransport({ bridge: createMetaMaskMobileBridge() }) : platform === "terminal" ? harness.createCdpWebUiTransport({
+    async withPage(input, callback) {
+      const { withTerminalPage } = await import("../library/actions/terminal/platform/page.mjs");
+      return withTerminalPage(
+        {
+          action: input.action,
+          node: input.node,
+          context: {
+            nodeId: input.context.nodeId,
+            projectRoot: input.context.projectRoot,
+            artifactsDir: input.context.artifactsDir
+          }
+        },
+        callback
+      );
+    }
+  }) : harness.createCdpWebUiTransport({
     async withPage(input, callback) {
       return withExtensionPage(
         {
@@ -924,6 +940,13 @@ function createMetaMaskUiTransport(platform, harness, preparedLiveAdapters) {
   return {
     ...base.observe ? { observe: base.observe.bind(base) } : {},
     async execute(action, node, context) {
+      if (platform === "terminal" && action === "app.hud") {
+        const { showTerminalHud } = await import("../library/actions/terminal/platform/hud.mjs");
+        return showTerminalHud(
+          { action, node, context: { nodeId: context.nodeId, projectRoot: context.projectRoot } },
+          { hudPolicy }
+        );
+      }
       if (action === "ui.navigate") {
         const live = await runLiveFirst(
           platform,
@@ -1110,7 +1133,7 @@ function createMetaMaskAdapters(adapter, declaredCustomActions = [], preparedLiv
       return {
         output: {
           platform,
-          transport: platform === "mobile" ? "react-native-debug-bridge" : "chrome-extension-cdp",
+          transport: platform === "mobile" ? "react-native-debug-bridge" : platform === "terminal" ? "chrome-cdp" : "chrome-extension-cdp",
           cdpPort,
           metroPort,
           probeUrl: url,

package/dist/cli.js

@@ -44,7 +44,7 @@ const COMMANDS = {
 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.
+Run it from inside a MetaMask checkout; the platform (mobile | extension | core | terminal) is auto-detected.
 Grammar: mm-harness <command> [target] [flags]   (target is a positional: ios | android | extension; flags add agent depth)
 
 DAILY LOOP \u2014 what a teammate runs many times a day:
@@ -108,7 +108,7 @@ async function main(argv) {
         const { options } = parseArgs(argv.slice(1), command);
         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") {
+        if (adapterRaw === "mobile" || adapterRaw === "extension" || adapterRaw === "core" || adapterRaw === "terminal") {
           await handleHarness(["install", "--platform", adapterRaw, "--target", target, "--quiet"]);
         }
       } catch {

package/dist/command-contract.js

@@ -7,9 +7,9 @@ const JSON = { "--json": bool() };
 const NO_OPEN = { "--no-open": bool() };
 const JSON_STREAM = { "--json-stream": bool() };
 const TARGET = { "--target": value() };
-const ADAPTER = { "--adapter": value(["mobile", "extension", "core"]) };
+const ADAPTER = { "--adapter": value(["mobile", "extension", "core", "terminal"]) };
 const MOBILE_PLATFORM = { "--platform": value(["ios", "android"]) };
-const ADAPTER_OR_MOBILE_PLATFORM = { "--platform": value(["mobile", "extension", "core", "ios", "android"]) };
+const ADAPTER_OR_MOBILE_PLATFORM = { "--platform": value(["mobile", "extension", "core", "terminal", "ios", "android"]) };
 const DEVICE = { "--device": value() };
 const RUNTIME_PORTS = {
   "--cdp-port": value(),
@@ -151,7 +151,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
   prepare: {
     usage: "mm-harness prepare [--target <checkout>] [--platform mobile|extension|core] [--mobile-platform ios|android] [--clear-metro] [--artifacts-dir <dir>] [--json]",
     options: options(HELP, JSON, TARGET, {
-      "--platform": value(["mobile", "extension", "core"]),
+      "--platform": value(["mobile", "extension", "core", "terminal"]),
       "--mobile-platform": value(["ios", "android"]),
       "--clear-metro": bool(),
       "--artifacts-dir": value(),
@@ -347,7 +347,15 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--fullscreen": bool(),
       "--url": value(),
       "--heal": value(["off", "infra-only", "auto"]),
-      "--remote-flag": value()
+      "--remote-flag": value(),
+      "--signer": value(["extension", "injected"]),
+      "--account": value(),
+      "--fresh-profile": bool(),
+      "--headless": bool(),
+      "--headful": bool(),
+      "--slow-mo": value(),
+      "--network": value(["testnet", "mainnet"]),
+      "--mainnet-confirmation": value()
     }),
     positionals: [{ label: "platform", choices: ["ios", "android"] }]
   },

package/dist/commands/check.js

@@ -21,7 +21,7 @@ async function handleCheck(argv) {
   const target = path.resolve(optionString(options, "target") ?? process.cwd());
   const explicitAdapter = optionString(options, "adapter") ?? optionString(options, "platform");
   const detected = explicitAdapter ?? detectAdapter(target);
-  if (detected && !["mobile", "extension", "core"].includes(detected)) {
+  if (detected && !["mobile", "extension", "core", "terminal"].includes(detected)) {
     return usageOut(json, "check", `unsupported adapter '${detected}'`, USAGE);
   }
   const adapter = detected;

package/dist/commands/config.js

@@ -7,7 +7,7 @@ import {
   writeConfig
 } from "../review/knowledge.js";
 import { optionFlag, parseArgs, usageError } from "./parse-args.js";
-const USAGE = "Usage: mm-harness config <list|path|get <key>|set <key> <value>|unset <key>> [--json]\n  keys: libraries.<name>, references.<mobile|extension|core>, advisor.<enabled|provider|model|stages>";
+const USAGE = "Usage: mm-harness config <list|path|get <key>|set <key> <value>|unset <key>> [--json]\n  keys: libraries.<name>, references.<mobile|extension|core|terminal>, advisor.<enabled|provider|model|stages>";
 function parseKey(raw) {
   if (!raw) throw usageError(USAGE);
   const dot = raw.indexOf(".");

package/dist/commands/doctor.js

@@ -7,6 +7,7 @@ import { featureFlagReport } from "../feature-flags.js";
 import { color } from "../cli-color.js";
 import { collectCheckoutView, renderCheckoutView } from "../checkout-view.js";
 import { createDoctorReport, fixtureSummary, requiredDoctorCheckSummary } from "../doctor.js";
+import { terminalAppPort, terminalCdpPort } from "../adapters/terminal/surface.js";
 import { detectAdapter, resolveRuntimeContextPath } from "../harness.js";
 import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
@@ -179,7 +180,11 @@ async function handleDoctor({ options }) {
     runtimeProbeError = error instanceof Error ? error.message : String(error);
   }
   const runtimeCheck = doctorRuntimeCheck(runtime, runtimeProbeError, expectLive);
-  const checks = [...result.checks, runtimeCheck];
+  const checks = [
+    ...result.checks,
+    runtimeCheck,
+    ...adapter === "terminal" ? await terminalDoctorChecks(target) : []
+  ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   const doctorResult = {
     ...result,
@@ -268,6 +273,24 @@ async function handleDoctor({ options }) {
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
+async function terminalDoctorChecks(target) {
+  const { terminalReadiness } = await import("../../adapters/terminal/lib/readiness.mjs");
+  const { resolveBrowser } = await import("../../adapters/terminal/launch.mjs");
+  const report = await terminalReadiness({
+    target,
+    appPort: terminalAppPort(),
+    cdpPort: terminalCdpPort(),
+    signer: process.env.TERMINAL_SIGNER || "extension",
+    account: process.env.TERMINAL_ACCOUNT || "dev1",
+    probeBrowser: resolveBrowser
+  });
+  return report.checks.map((check) => ({
+    id: `terminal-${check.id}`,
+    status: check.status === "pass" ? "pass" : "fail",
+    required: check.required,
+    message: check.detail
+  }));
+}
 function doctorRuntimeCheck(runtime, error, expectLive) {
   if (error) {
     return {

package/dist/commands/domain.js

@@ -19,7 +19,7 @@ async function handleDomain(argv) {
     return 0;
   }
   if (!adapter) {
-    throw usageError("No MetaMask checkout detected: pass --adapter <mobile|extension|core> or --domain <name>.");
+    throw usageError("No MetaMask checkout detected: pass --adapter <mobile|extension|core|terminal> or --domain <name>.");
   }
   const config = readConfig(configPath());
   const libraries = discoverLibraries({ target, config });