@deeeed/metamask-harness 0.3.9 → 0.5.0

package/dist/harness.js

@@ -0,0 +1,627 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveLeafInvoke, shellLeafMissing, missingShellLeafMessage } from "./leaf-invoke.js";
+import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "./paths.js";
+import { prepareMobile } from "./adapters/mobile/prepare.js";
+const HARNESS_ACTIONS = ["install", "provision", "verify", "cleanup", "live"];
+const ADAPTERS = ["mobile", "extension", "core"];
+function isValidAdapterAction(adapter, action) {
+  if (adapter === "core") return action === "install" || action === "provision" || action === "verify" || action === "cleanup";
+  return true;
+}
+function harnessUsage() {
+  console.error(`mm-harness \u2014 install and validate the MetaMask recipe runtime in a checkout.
+
+Run it from inside a MetaMask checkout; the platform (mobile | extension | core)
+is auto-detected from the repo. Pass --platform only to override.
+
+Commands (one copy-pasteable example each):
+  install   Install the recipe harness runtime overlay into the checkout.
+              mm-harness install
+  provision Install the cached Runway mobile dev client (same path as install --runway).
+              mm-harness provision runway ios --adapter mobile
+  verify    Check the harness/runtime is present and healthy (no app launch).
+              mm-harness verify
+  cleanup   Remove the installed harness overlay and restore the checkout.
+              mm-harness cleanup
+
+Options:
+  --platform <mobile|extension|core>   Override auto-detection (alias: --adapter).
+  --target <repo>                      Checkout to operate on (default: current dir).
+  --json                               Machine-readable summary for agents/scripts.
+  -- <args>                            Forward the rest verbatim to the underlying
+                                       script, e.g. -- --platform ios --preflight-mode fast
+                                       (mobile) or -- --cdp-port 6665 (extension).
+
+Examples:
+  mm-harness install                          # inside a checkout, auto-detected
+  mm-harness verify --platform extension
+  mm-harness cleanup --target ../metamask-mobile
+
+core supports install, verify, and cleanup (headless; no live).`);
+}
+function failureHint(adapter, action) {
+  if (adapter === "core") {
+    if (action === "verify") {
+      return `Install the core harness first: mm-harness install --platform core`;
+    }
+    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}`;
+}
+function hasArg(args, needle) {
+  return args.some((arg) => arg === needle || arg.startsWith(`${needle}=`));
+}
+function argValue(args, needle) {
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === needle) return args[i + 1];
+    if (args[i].startsWith(`${needle}=`)) return args[i].slice(needle.length + 1);
+  }
+  return void 0;
+}
+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";
+}
+function parseHarnessArgs(args) {
+  const forward = [];
+  let adapter;
+  let json = false;
+  let separator = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (separator) {
+      forward.push(arg);
+      continue;
+    }
+    if (arg === "--") {
+      separator = true;
+      continue;
+    }
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg === "--adapter" || arg === "--platform") {
+      const value = args[i + 1];
+      if (arg === "--adapter") {
+        adapter = value;
+        i += 1;
+        continue;
+      }
+      if (adapter === void 0 && isAdapter(value)) {
+        adapter = value;
+        i += 1;
+        continue;
+      }
+      forward.push(arg);
+      continue;
+    }
+    if (arg.startsWith("--adapter=")) {
+      adapter = arg.slice("--adapter=".length);
+      continue;
+    }
+    if (arg.startsWith("--platform=")) {
+      const value = arg.slice("--platform=".length);
+      if (adapter === void 0 && isAdapter(value)) {
+        adapter = value;
+        continue;
+      }
+      forward.push(arg);
+      continue;
+    }
+    forward.push(arg);
+  }
+  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) {
+  let remote = "";
+  try {
+    remote = execFileSync("git", ["-C", target, "config", "--get", "remote.origin.url"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    remote = "";
+  }
+  if (remote.includes("metamask-extension")) return "extension";
+  if (remote.includes("metamask-mobile")) return "mobile";
+  const exists = (rel) => fs.existsSync(path.join(target, rel));
+  const isDir = (rel) => {
+    try {
+      return fs.statSync(path.join(target, rel)).isDirectory();
+    } catch {
+      return false;
+    }
+  };
+  if (exists("development/skills-sync.ts") || isDir("ui") && isDir("app/scripts")) return "extension";
+  if (exists("scripts/skills-sync.mts") || isDir("ios") && isDir("android") && isDir("app/core")) return "mobile";
+  if (isDir("packages/perps-controller") && exists("yarn.lock")) return "core";
+  return void 0;
+}
+function resolveRuntimeContextPath(target) {
+  return process.env.RECIPE_RUNTIME_CONTEXT ?? path.join(target, recipeRuntimeDir(), "agentic-runtime.json");
+}
+function readRuntimeContextField(contextPath, field) {
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(contextPath, "utf8"));
+  } catch {
+    return void 0;
+  }
+  let node = data;
+  for (const key of field.split(".")) {
+    if (node === void 0 || node === null || typeof node !== "object") return void 0;
+    node = node[key];
+  }
+  if (node === void 0 || node === null || node === "") return void 0;
+  return String(node);
+}
+function applyExtensionRuntimeEnv(target, action, 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;
+    }
+    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;
+    }
+  }
+  let result = [...args];
+  if (!hasArg(result, "--cdp-port")) {
+    const contextPort = contextExists ? readRuntimeContextField(contextPath, "cdpPort") : void 0;
+    const cdpPort = contextPort ?? 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];
+    }
+  }
+  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) {
+  for (const candidate of candidates) {
+    const full = path.join(base, candidate);
+    try {
+      const stat = fs.statSync(full);
+      if (!stat.isFile()) continue;
+      if (mode === "file" || (stat.mode & 73) !== 0) return full;
+    } catch {
+    }
+  }
+  return path.join(base, candidates[0]);
+}
+function installedRunnerSource(target, adapter) {
+  const pointer = path.join(recipeHarnessPath(target, adapter), "runner", ".runner-source");
+  if (!fs.existsSync(pointer)) return void 0;
+  const value = fs.readFileSync(pointer, "utf8").trim();
+  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" }
+};
+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" }
+};
+function resolveHarnessDispatch(adapter, action, target) {
+  if (action === "install") {
+    const { entry, fallback } = INJECT_CANDIDATES[adapter];
+    if (adapter === "extension") {
+      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 = installedRunnerSource(target, adapter) ?? runnerDir;
+    if (adapter === "extension") {
+      return { command: process.execPath, prefixArgs: [resolveEntry(base, [entry, fallback], "file")] };
+    }
+    return { command: resolveEntry(base, [entry, fallback], "file"), prefixArgs: [] };
+  }
+  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"] };
+  }
+  const installedScript = path.join(recipeHarnessPath(target, adapter), "scripts", `${action}.sh`);
+  if (fs.existsSync(installedScript)) {
+    return { command: installedScript, prefixArgs: [] };
+  }
+  const command = resolveEntry(
+    runnerDir,
+    [`adapters/${adapter}/${action}.sh`, `scripts/${adapter}/${action}.sh`],
+    "file"
+  );
+  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") {
+    harnessUsage();
+    return action ? 0 : 2;
+  }
+  if (!HARNESS_ACTIONS.includes(action)) {
+    harnessUsage();
+    console.error(`unsupported harness subcommand: ${action}`);
+    return 2;
+  }
+  const harnessAction = action;
+  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 (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 {
+      harnessUsage();
+      console.error(
+        adapter ? `
+\u2717 unsupported platform: ${adapter}` : `
+\u2717 could not detect the MetaMask repo type for ${target}
+  Next: ${ADAPTER_DETECT_NEXT}`
+      );
+    }
+    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 === "provision") {
+    return handleRunwayInstall(adapter, target, provisionRunwayForward(forward), json, "provision");
+  }
+  if (harnessAction === "install" && hasArg(forward, "--runway")) {
+    return handleRunwayInstall(adapter, target, forward, json, "install");
+  }
+  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 (json) {
+      console.log(
+        harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
+          code: "DISPATCH_UNAVAILABLE",
+          message: dispatch.error,
+          // The dispatch error embeds "Next: <hint>" — extract it so --json consumers
+          // get a clean programmatic escape without parsing the human message.
+          userAction: dispatch.error.split("\nNext: ")[1] ?? "run mm-harness install to complete setup, then retry"
+        })
+      );
+    } else {
+      console.error(`\u2717 ${harnessAction} ${adapter} failed
+  ${dispatch.error.replace(/\n/gu, "\n  ")}`);
+    }
+    return 1;
+  }
+  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 (json) {
+      console.log(
+        harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
+          code: "HARNESS_SPAWN_FAILED",
+          message,
+          userAction: failureHint(adapter, harnessAction)
+        })
+      );
+    } else {
+      console.error(`\u2717 ${message}`);
+    }
+    return 1;
+  }
+  const { bin: dispatchBin, args: dispatchArgs } = resolveLeafInvoke(dispatch.command, [
+    ...dispatch.prefixArgs,
+    ...forwardArgs
+  ]);
+  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: json ? ["inherit", 2, "inherit"] : "inherit",
+    env: process.env
+  });
+  const seconds = ((Date.now() - start) / 1e3).toFixed(1);
+  if (result.error) {
+    if (json) {
+      console.log(
+        harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
+          code: "HARNESS_SPAWN_FAILED",
+          message: `${harnessAction} ${adapter} could not start: ${result.error.message}`,
+          userAction: failureHint(adapter, harnessAction)
+        })
+      );
+    } else {
+      console.error(`\u2717 ${harnessAction} ${adapter} could not start: ${result.error.message}
+  ${failureHint(adapter, harnessAction)}`);
+    }
+    return 1;
+  }
+  const exitCode = result.status ?? 1;
+  if (json) {
+    console.log(
+      harnessSummary(
+        harnessAction,
+        adapter,
+        target,
+        exitCode === 0 ? "pass" : "fail",
+        exitCode,
+        autoDetected,
+        exitCode === 0 ? void 0 : { code: "HARNESS_FAILED", message: `${harnessAction} ${adapter} failed (exit ${exitCode})`, userAction: failureHint(adapter, harnessAction) }
+      )
+    );
+  } else if (exitCode === 0) {
+    console.error(`\u2713 ${harnessAction} ${adapter} passed (${seconds}s)`);
+  } else {
+    console.error(`\u2717 ${harnessAction} ${adapter} failed (exit ${exitCode}, ${seconds}s)
+  ${failureHint(adapter, harnessAction)}`);
+  }
+  return exitCode;
+}
+async function handleRunwayInstall(adapter, target, forward, json, action) {
+  const { getAdapterSurface } = await import("./adapters/surface.js");
+  const rerunCommand = action === "provision" ? runwayProvisionRerunCommand(adapter, target, forward, json) : runwayInstallRerunCommand(adapter, target, forward, json);
+  const surface = getAdapterSurface(adapter);
+  const runtimeDir = argValue(forward, "--runtime-dir");
+  const watcherPort = argValue(forward, "--watcher-port");
+  const result = await surface.runwayProvision.run(target, {
+    json,
+    platform: argValue(forward, "--platform") ?? "ios",
+    branch: argValue(forward, "--branch"),
+    defaultBranch: argValue(forward, "--default-branch"),
+    run: argValue(forward, "--run"),
+    cacheRoot: argValue(forward, "--cache-root"),
+    simulator: argValue(forward, "--simulator") ?? argValue(forward, "--device"),
+    runtime: argValue(forward, "--runtime"),
+    deviceType: argValue(forward, "--device-type"),
+    slot: argValue(forward, "--slot"),
+    watcherPort,
+    runtimeDir,
+    force: hasArg(forward, "--force"),
+    resolveOnly: hasArg(forward, "--resolve-only"),
+    rerunCommand
+  });
+  if (json) {
+    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;
+    const artifact = typeof result.artifact === "object" && result.artifact ? result.artifact : void 0;
+    if (result.resolveOnly) {
+      console.error(`\u2713 resolved Runway app for ${adapter} ${result.platform ?? ""} run=${artifact?.runId ?? "unknown"} revision=${artifact?.revision ?? "unknown"} artifact=${artifact?.artifactName ?? "unknown"}`);
+    } else {
+      const action2 = result.skipped ? "already provisioned" : "installed Runway app";
+      console.error(`\u2713 ${action2} for ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "skip"}`);
+    }
+  } else {
+    const label = action === "provision" ? "provision" : "install --runway";
+    console.error(`\u2717 mm-harness ${label}: ${result.error?.message ?? "runway install failed"}
+  Next: ${result.error?.userAction ?? rerunCommand}`);
+  }
+  return result.exitCode;
+}
+function provisionRunwayForward(forward) {
+  const normalized = [];
+  let index = 0;
+  if (forward[index] === "runway") index += 1;
+  if (forward[index] && !forward[index].startsWith("-")) {
+    if (!hasArg(forward, "--platform")) normalized.push("--platform", forward[index]);
+    index += 1;
+  }
+  return [...normalized, ...forward.slice(index)];
+}
+function runwayInstallRerunCommand(adapter, target, forward, json) {
+  const parts = ["mm-harness", "install", "--runway", "--adapter", adapter, "--target", shellQuote(target)];
+  const valueFlags = [
+    "--platform",
+    "--branch",
+    "--default-branch",
+    "--run",
+    "--cache-root",
+    "--simulator",
+    "--device",
+    "--slot",
+    "--watcher-port",
+    "--runtime-dir",
+    "--runtime",
+    "--device-type"
+  ];
+  for (const flag of valueFlags) {
+    const value = argValue(forward, flag);
+    if (value) parts.push(flag, shellQuote(value));
+  }
+  if (hasArg(forward, "--force")) parts.push("--force");
+  if (hasArg(forward, "--resolve-only")) parts.push("--resolve-only");
+  if (json) parts.push("--json");
+  return parts.join(" ");
+}
+function runwayProvisionRerunCommand(adapter, target, forward, json) {
+  const parts = ["mm-harness", "provision", "runway", shellQuote(argValue(forward, "--platform") ?? "ios"), "--adapter", adapter, "--target", shellQuote(target)];
+  const valueFlags = [
+    "--branch",
+    "--default-branch",
+    "--run",
+    "--cache-root",
+    "--simulator",
+    "--device",
+    "--slot",
+    "--watcher-port",
+    "--runtime-dir",
+    "--runtime",
+    "--device-type"
+  ];
+  for (const flag of valueFlags) {
+    const value = argValue(forward, flag);
+    if (value) parts.push(flag, shellQuote(value));
+  }
+  if (hasArg(forward, "--force")) parts.push("--force");
+  if (hasArg(forward, "--resolve-only")) parts.push("--resolve-only");
+  if (json) parts.push("--json");
+  return parts.join(" ");
+}
+function harnessSummary(action, adapter, target, status, exitCode, autoDetected, error) {
+  return JSON.stringify({
+    schemaVersion: 1,
+    command: "harness",
+    action,
+    adapter: adapter ?? null,
+    target,
+    autoDetected,
+    status,
+    exitCode,
+    // Error contract: every --json failure carries a stable machine code + human
+    // 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 } : {}
+  });
+}
+export {
+  ADAPTER_DETECT_NEXT,
+  detectAdapter,
+  handleHarness,
+  readRuntimeContextField,
+  resolveRuntimeContextPath
+};