@deeeed/metamask-harness 0.75.0 → 0.76.0

package/dist/harness.js

@@ -3,7 +3,7 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { shellLeafMissing, missingShellLeafMessage } from "./leaf-invoke.js";
-import { resolveExtensionSlotPorts } from "./adapters/slot-ports.js";
+import { adapterRegistry } from "./adapters/registry.js";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "./paths.js";
 import { colorHumanMessage } from "./cli-color.js";
 const HARNESS_ACTIONS = ["install", "verify", "cleanup"];
@@ -37,15 +37,15 @@ Examples:
 
 core supports install, verify, and cleanup (headless; no live).`);
 }
-function failureHint(adapter, action) {
-  if (adapter === "core") {
+function failureHint(surface, action) {
+  const restart = surface.harness.restart;
+  if (!restart) {
     if (action === "verify") {
-      return `Install the core harness first: mm-harness install --platform core`;
+      return `Install the ${surface.adapter} harness first: mm-harness install --platform ${surface.adapter}`;
     }
     return "Read the error above for the specific cause, then re-run this command.";
   }
-  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}`;
+  return `Read the error above for the specific cause. To (re)start the runtime, run: ${restart}`;
 }
 function successNext(adapter, action, target) {
   const base = `--adapter ${adapter} --target ${shellQuote(target)}`;
@@ -67,7 +67,7 @@ function shellQuote(value) {
   return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : `'${value.replace(/'/gu, `'\\''`)}'`;
 }
 function isAdapter(value) {
-  return value === "mobile" || value === "extension" || value === "core" || value === "terminal";
+  return value !== void 0 && adapterRegistry.has(value);
 }
 function parseHarnessArgs(args) {
   const forward = [];
@@ -170,37 +170,9 @@ function readRuntimeContextField(contextPath, field) {
   if (node === void 0 || node === null || node === "") return void 0;
   return String(node);
 }
-function applyExtensionRuntimeEnv(target, args) {
-  const contextPath = resolveRuntimeContextPath(target);
-  const contextExists = fs.existsSync(contextPath);
-  if (contextExists) {
-    process.env.RECIPE_RUNTIME_CONTEXT = contextPath;
-    if (!process.env.RECIPE_SLOT_ID) {
-      const slotId = readRuntimeContextField(contextPath, "slotId");
-      if (slotId) process.env.RECIPE_SLOT_ID = slotId;
-    }
-    if (!process.env.RECIPE_HARNESS_EXTENSION_ID) {
-      const extensionId = readRuntimeContextField(contextPath, "extensionId");
-      if (extensionId) process.env.RECIPE_HARNESS_EXTENSION_ID = extensionId;
-    }
-  } else {
-    delete process.env.RECIPE_RUNTIME_CONTEXT;
-  }
-  resolveExtensionSlotPorts(target);
-  let result = [...args];
-  if (!hasArg(result, "--cdp-port")) {
-    const cdpPort = process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
-    if (cdpPort) {
-      process.env.RECIPE_CDP_PORT = cdpPort;
-      process.env.CDP_PORT = cdpPort;
-      result = [...result, "--cdp-port", cdpPort];
-    }
-  }
-  return result;
-}
 function resolveEntry(base, candidates, mode) {
   for (const candidate of candidates) {
-    const full = path.join(base, candidate);
+    const full = path.resolve(base, candidate);
     try {
       const stat = fs.statSync(full);
       if (!stat.isFile()) continue;
@@ -208,7 +180,7 @@ function resolveEntry(base, candidates, mode) {
     } catch {
     }
   }
-  return path.join(base, candidates[0]);
+  return path.resolve(base, candidates[0]);
 }
 function installedRunnerSource(target, adapter) {
   const pointer = path.join(recipeHarnessPath(target, adapter), "runner", ".runner-source");
@@ -217,56 +189,12 @@ function installedRunnerSource(target, adapter) {
   if (!value || !fs.existsSync(value)) return void 0;
   return value;
 }
-function isExecutable(file) {
-  try {
-    const stat = fs.statSync(file);
-    return stat.isFile() && (stat.mode & 73) !== 0;
-  } catch {
-    return false;
-  }
-}
-const INJECT_CANDIDATES = {
-  mobile: { entry: "adapters/mobile/inject.sh", fallback: "scripts/inject-mobile-harness.sh" },
-  extension: { entry: "adapters/extension/inject.mjs", fallback: "scripts/inject-extension-harness.mjs" },
-  core: { entry: "adapters/core/inject.sh", fallback: "scripts/inject-core-harness.sh" },
-  terminal: { entry: "adapters/terminal/inject.mjs", fallback: "adapters/terminal/inject.mjs" }
-};
-const CLEANUP_CANDIDATES = {
-  mobile: { entry: "adapters/mobile/cleanup.sh", fallback: "scripts/cleanup-mobile-harness.sh" },
-  extension: { entry: "adapters/extension/cleanup.mjs", fallback: "scripts/cleanup-extension-harness.mjs" },
-  core: { entry: "adapters/core/cleanup.sh", fallback: "scripts/cleanup-core-harness.sh" },
-  terminal: { entry: "adapters/terminal/cleanup.mjs", fallback: "adapters/terminal/cleanup.mjs" }
-};
-function resolveHarnessDispatch(adapter, action, target) {
-  if (action === "install") {
-    const { entry, fallback } = INJECT_CANDIDATES[adapter];
-    if (adapter === "extension" || adapter === "terminal") {
-      return { command: process.execPath, prefixArgs: [resolveEntry(runnerDir, [entry, fallback], "file")] };
-    }
-    return { command: resolveEntry(runnerDir, [entry, fallback], "file"), prefixArgs: [] };
-  }
-  if (action === "cleanup") {
-    const { entry, fallback } = CLEANUP_CANDIDATES[adapter];
-    const base = adapter === "terminal" ? runnerDir : installedRunnerSource(target, adapter) ?? runnerDir;
-    if (adapter === "extension" || adapter === "terminal") {
-      return { command: process.execPath, prefixArgs: [resolveEntry(base, [entry, fallback], "file")] };
-    }
-    return { command: resolveEntry(base, [entry, fallback], "file"), prefixArgs: [] };
-  }
-  if (adapter === "terminal" && action === "verify") {
-    return { command: process.execPath, prefixArgs: [path.join(runnerDir, "adapters", "terminal", "verify.mjs")] };
-  }
-  if (adapter === "core" && action === "verify") {
-    const delegate = path.join(recipeHarnessPath(target, "core"), "runner", "bin", "mm-harness");
-    if (!isExecutable(delegate)) {
-      return {
-        error: `core recipe harness not installed: missing delegate ${delegate}.
-Next: mm-harness install --platform core --target ${target}`
-      };
-    }
-    return { command: delegate, prefixArgs: ["doctor", "--adapter", "core"] };
-  }
-  return { inProcess: adapter === "mobile" ? "mobile-verify" : "extension-verify" };
+function resolveHarnessDispatch(surface, action, target) {
+  if (action === "verify") return surface.harness.verify(target);
+  const leaf = action === "install" ? surface.harness.install : surface.harness.cleanup;
+  const base = action === "cleanup" && surface.harness.cleanup.fromInstalledRunner ? installedRunnerSource(target, surface.adapter) ?? runnerDir : runnerDir;
+  const entry = resolveEntry(base, [leaf.entry, leaf.fallback], "file");
+  return leaf.node ? { command: process.execPath, prefixArgs: [entry] } : { command: entry, prefixArgs: [] };
 }
 async function handleHarness(argv) {
   const action = argv[0];
@@ -280,6 +208,7 @@ async function handleHarness(argv) {
     return 2;
   }
   const harnessAction = action;
+  const { getAdapterSurface } = await import("./adapters/surface.js");
   const { adapter: parsedAdapter, json, quiet, forward } = parseHarnessArgs(argv.slice(1));
   const rawTarget = argValue(forward, "--target");
   const target = path.resolve(rawTarget ?? process.cwd());
@@ -306,10 +235,11 @@ async function handleHarness(argv) {
   if (harnessAction === "install" && hasArg(forward, "--runway")) {
     return handleRunwayInstall(adapter, target, forward, json);
   }
-  if (adapter === "extension" && harnessAction === "verify") {
-    forwardArgs = applyExtensionRuntimeEnv(target, forwardArgs);
+  const surface = getAdapterSurface(adapter);
+  if (harnessAction === "verify" && surface.harness.verifyArgs) {
+    forwardArgs = surface.harness.verifyArgs(target, forwardArgs);
   }
-  const dispatch = resolveHarnessDispatch(adapter, harnessAction, target);
+  const dispatch = resolveHarnessDispatch(surface, harnessAction, target);
   if ("error" in dispatch) {
     if (quiet) {
       return 1;
@@ -335,7 +265,7 @@ async function handleHarness(argv) {
   }
   const start = Date.now();
   if ("inProcess" in dispatch) {
-    const runVerify = dispatch.inProcess === "mobile-verify" ? (await import("./adapters/mobile/verify.js")).runMobileVerify : (await import("./adapters/extension/verify.js")).runExtensionVerify;
+    const runVerify = await dispatch.inProcess();
     let exitCode;
     try {
       exitCode = await runVerify(forwardArgs, {
@@ -355,7 +285,7 @@ async function handleHarness(argv) {
 `);
       exitCode = 1;
     }
-    return reportHarnessOutcome(harnessAction, adapter, target, exitCode, autoDetected, json, quiet, start);
+    return reportHarnessOutcome(harnessAction, surface, target, exitCode, autoDetected, json, quiet, start);
   }
   if (shellLeafMissing(dispatch.command)) {
     const message = missingShellLeafMessage(dispatch.command);
@@ -366,7 +296,7 @@ async function handleHarness(argv) {
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "HARNESS_SPAWN_FAILED",
           message,
-          userAction: failureHint(adapter, harnessAction)
+          userAction: failureHint(surface, harnessAction)
         })
       );
     } else {
@@ -387,19 +317,20 @@ async function handleHarness(argv) {
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "HARNESS_SPAWN_FAILED",
           message: `${harnessAction} ${adapter} could not start: ${result.error.message}`,
-          userAction: failureHint(adapter, harnessAction)
+          userAction: failureHint(surface, harnessAction)
         })
       );
     } else {
       console.error(`\u2717 ${harnessAction} ${adapter} could not start: ${result.error.message}
-  ${failureHint(adapter, harnessAction)}`);
+  ${failureHint(surface, harnessAction)}`);
     }
     return 1;
   }
-  return reportHarnessOutcome(harnessAction, adapter, target, result.status ?? 1, autoDetected, json, quiet, start);
+  return reportHarnessOutcome(harnessAction, surface, target, result.status ?? 1, autoDetected, json, quiet, start);
 }
-function reportHarnessOutcome(action, adapter, target, exitCode, autoDetected, json, quiet, start) {
+function reportHarnessOutcome(action, surface, target, exitCode, autoDetected, json, quiet, start) {
   const seconds = ((Date.now() - start) / 1e3).toFixed(1);
+  const adapter = surface.adapter;
   if (quiet) {
     return exitCode;
   } else if (json) {
@@ -411,7 +342,7 @@ function reportHarnessOutcome(action, adapter, target, exitCode, autoDetected, j
         exitCode === 0 ? "pass" : "fail",
         exitCode,
         autoDetected,
-        exitCode === 0 ? void 0 : { code: "HARNESS_FAILED", message: `${action} ${adapter} failed (exit ${exitCode})`, userAction: failureHint(adapter, action) }
+        exitCode === 0 ? void 0 : { code: "HARNESS_FAILED", message: `${action} ${adapter} failed (exit ${exitCode})`, userAction: failureHint(surface, action) }
       )
     );
   } else if (exitCode === 0) {
@@ -419,7 +350,7 @@ function reportHarnessOutcome(action, adapter, target, exitCode, autoDetected, j
   Next: ${successNext(adapter, action, target)}`));
   } else {
     console.error(colorHumanMessage(`\u2717 ${action} ${adapter} failed (exit ${exitCode}, ${seconds}s)
-  ${failureHint(adapter, action)}`));
+  ${failureHint(surface, action)}`));
   }
   return exitCode;
 }
@@ -448,7 +379,7 @@ async function handleRunwayInstall(adapter, target, forward, json) {
   });
   const provisionedSimulator = typeof result.simulator === "object" && result.simulator ? result.simulator : void 0;
   const provisionedDevice = typeof provisionedSimulator?.udid === "string" ? provisionedSimulator.udid : typeof provisionedSimulator?.name === "string" ? provisionedSimulator.name : void 0;
-  const next = result.status === "pass" && adapter === "mobile" && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? "ios")} --adapter mobile --target ${shellQuote(target)}` + (provisionedDevice ? ` --device ${shellQuote(provisionedDevice)}` : "") : void 0;
+  const next = result.status === "pass" && surface.runwayProvision.launchNext && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? "ios")} --adapter ${adapter} --target ${shellQuote(target)}` + (provisionedDevice ? ` --device ${shellQuote(provisionedDevice)}` : "") : void 0;
   const output = next ? { ...result, next } : result;
   if (json) {
     console.log(JSON.stringify(output, null, 2));

package/dist/mm-harness-cli.js

@@ -1032,8 +1032,9 @@ function detectedSlotLine(out) {
     if (ctx.slotId) parts.push(`slot ${out("ok", String(ctx.slotId))}`);
     if (ctx.simulator) parts.push(`device ${out("ok", String(ctx.simulator))}`);
     const devServerPort = ctx.watcherPort ?? ctx.devServerPort ?? ctx.metroPort;
-    if (adapter && adapter !== "core" && devServerPort) {
-      parts.push(`${getAdapterSurface(adapter).devServer.label} :${out("ok", String(devServerPort))}`);
+    const surface = adapter ? getAdapterSurface(adapter) : void 0;
+    if (surface && !surface.headless && devServerPort) {
+      parts.push(`${surface.devServer.label} :${out("ok", String(devServerPort))}`);
     }
     if (ctx.gitBranch) parts.push(`branch ${out("info", String(ctx.gitBranch))}`);
     if (parts.length === 0) return null;

package/dist/paths.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { adapterRegistry } from "./adapters/registry.js";
 const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const pathDefaults = readPathDefaults();
 const DEFAULT_RECIPE_RUNTIME_DIR = pathDefaults.recipeRuntimeDir;
@@ -88,8 +89,13 @@ function isProtocolRoot(candidate) {
   return fs.existsSync(path.join(candidate, "packages/recipe-harness/package.json")) && fs.existsSync(path.join(candidate, "packages/protocol/package.json"));
 }
 function assertAdapter(adapter) {
-  if (adapter !== "mobile" && adapter !== "extension" && adapter !== "core" && adapter !== "terminal") {
-    throw new Error("Adapter must be mobile, extension, core, or terminal.");
+  const ids = adapterRegistry.list();
+  if (ids.length === 0) {
+    throw new Error("internal: no adapters are registered yet; import src/adapters/surface.ts before validating an adapter");
+  }
+  if (typeof adapter !== "string" || !adapterRegistry.has(adapter)) {
+    const choices = ids.length > 1 ? `${ids.slice(0, -1).join(", ")}, or ${ids.at(-1)}` : ids.join("");
+    throw new Error(`Adapter must be ${choices}.`);
   }
 }
 function manifestPath(adapter) {

package/dist/runtime-context.js

@@ -3,6 +3,7 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { getAdapterSurface } from "./adapters/surface.js";
 import { recipeRuntimeDir } from "./paths.js";
 function ensureRuntimeContext(target, adapter) {
   const repoRoot = fs.realpathSync(target);
@@ -91,7 +92,7 @@ function validExistingContext(context, repoRoot, runtimeDir, adapter) {
       if (runtimeStart[field] !== void 0 && (typeof runtimeStart[field] !== "string" || runtimeStart[field].length === 0)) return false;
     }
   }
-  const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial"] : adapter === "terminal" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : ["cdpPort", "extensionId"];
+  const forbiddenResources = getAdapterSurface(adapter).runtimeContext.forbiddenFields;
   if (forbiddenResources.some((field) => context[field] !== void 0)) return false;
   return true;
 }
@@ -104,11 +105,12 @@ function localDefaults(repoRoot, adapter, existing) {
   const digest = createHash("sha256").update(repoRoot).digest("hex");
   const offset = Number.parseInt(digest.slice(0, 8), 16) % 1e4;
   const defaults = { slotId: `local-${adapter}-${digest.slice(0, 8)}` };
-  if (adapter === "extension" && !numericEnv("RECIPE_CDP_PORT", "CDP_PORT") && !existing.cdpPort) {
-    defaults.cdpPort = claimLocalPort(repoRoot, "cdp", 2e4 + offset);
+  const localPorts = getAdapterSurface(adapter).runtimeContext.localPorts ?? {};
+  if (localPorts.cdp !== void 0 && !numericEnv("RECIPE_CDP_PORT", "CDP_PORT") && !existing.cdpPort) {
+    defaults.cdpPort = claimLocalPort(repoRoot, "cdp", localPorts.cdp + offset);
   }
-  if (adapter !== "core" && adapter !== "terminal" && !numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") && !existing.watcherPort && !existing.metroPort && !existing.devServerPort) {
-    defaults.watcherPort = claimLocalPort(repoRoot, "watcher", (adapter === "extension" ? 3e4 : 4e4) + offset);
+  if (localPorts.watcher !== void 0 && !numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") && !existing.watcherPort && !existing.metroPort && !existing.devServerPort) {
+    defaults.watcherPort = claimLocalPort(repoRoot, "watcher", localPorts.watcher + offset);
   }
   return defaults;
 }
@@ -158,21 +160,14 @@ function portClaimIsLive(claim, port) {
   }
 }
 function runtimeResources(adapter, existing, defaults) {
-  if (adapter === "core") return {};
+  const { resources } = getAdapterSurface(adapter).runtimeContext;
+  if (!resources) return {};
   const watcherPort = numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") ?? existing.watcherPort ?? existing.metroPort ?? existing.devServerPort ?? defaults.watcherPort;
-  const shared = {
+  return {
     watcherPort,
-    devServerPort: watcherPort
+    devServerPort: watcherPort,
+    ...resources({ watcherPort, existing, defaults, envPort: numericEnv })
   };
-  if (adapter === "extension" || adapter === "terminal") {
-    shared.cdpPort = numericEnv("RECIPE_CDP_PORT", "CDP_PORT") ?? existing.cdpPort ?? defaults.cdpPort;
-  } else {
-    shared.metroPort = watcherPort;
-    shared.simulator = process.env.IOS_SIMULATOR || existing.simulator;
-    shared.simulatorUdid = process.env.SIM_UDID || existing.simulatorUdid;
-    shared.adbSerial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || existing.adbSerial;
-  }
-  return shared;
 }
 function numericEnv(...names) {
   for (const name of names) {

package/docs/CONTRIBUTING.md

@@ -62,25 +62,35 @@ exits.
 
 Commands resolve shared platform behavior through
 `src/adapters/surface.ts`. Each platform's surface registers itself in
-`src/adapters/registry.ts` when its module loads. A platform registered the same
-way is reached by `launch`, by the `run`/`call` engine and by the runner's
-action set with no edit to shared code (`tests/fixtures/example-adapter.ts`).
-The CLI front door still validates `--adapter` against the four built-ins
-(`src/command-contract.ts`), and the other commands still branch on the name,
-so a new platform reaches `bin/mm-harness` only when those families move and a
-plugin loader registers it.
+`src/adapters/registry.ts` when its module loads, and commands look adapters up
+in the registry, so a platform registered the same way is reached by the
+commands that take `--adapter` with no edit to shared code
+(`tests/fixtures/example-adapter.ts`); `status` detects the adapter from the
+checkout.
+The CLI contract (`src/command-contract.ts`) still lists the four built-ins for
+`--adapter`, so a new platform reaches `bin/mm-harness` once a plugin loader
+registers it and extends that list.
 
 Extend `AdapterSurface` when a platform owns the behavior; members a platform
-does not need are optional (`actions` is required: every platform has an
-action set), and Core reports headless/N/A explicitly. Put each platform's
-implementation under `src/adapters/<adapter>/` (`launch.ts`, `run.ts`,
-`actions.ts`). Do not add command-local platform ladders for surface-owned
-behavior: `launch` dispatches through `AdapterSurface.launch` (the device
-platforms share `src/commands/launch/device.ts` through a
-`DeviceLaunchProfile`), `run`/`call` read `run`, `recording`, `diagnostics`,
-`observation` and `sourceFingerprint`, and the runner reads `actions`
-(manifest, bundled semantic actions, live adapter scripts, `cdp.target`, the
-`ui.*` transport, adapter wrappers, input checks).
+does not need are optional, and Core reports headless/N/A explicitly. Put each
+platform's implementation under `src/adapters/<adapter>/`: `launch.ts`,
+`run.ts`, `actions.ts`, `overlay.ts` (install/verify/cleanup, the runtime
+context, prepare) and `readiness.ts` (doctor and status). Do not add
+command-local platform ladders for surface-owned behavior:
+- `launch` dispatches through `AdapterSurface.launch` (the device platforms
+  share `src/commands/launch/device.ts` through a `DeviceLaunchProfile`);
+- `run`/`call` read `run`, `recording`, `diagnostics`, `observation` and
+  `sourceFingerprint`;
+- the runner reads `actions` (manifest, bundled semantic actions, live adapter
+  scripts, `cdp.target`, the `ui.*` transport, adapter wrappers, input checks);
+- `install`/`verify`/`cleanup` read `harness`, `agentic-runtime.json` reads
+  `runtimeContext`, `doctor`/`status` read `readiness`, and `fixtures`,
+  `prepare`, `debug`, `reload` and `runtime-decision` read their own members.
+
+A few comparisons remain where a command exists for one platform
+(`runtime-health`, `resolve-extension`, `ensure-ready`, `runtime-launch`) or
+code compares a platform's own data (`review/knowledge.ts`, the Core jest
+grouping in `check.ts`, the Mobile release-artifact state file).
 
 Each checkout owns:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"