@deeeed/metamask-harness 0.4.0 → 0.5.0

package/dist/commands/shared.js

@@ -0,0 +1,157 @@
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { detectAdapter } from "../harness.js";
+import { resolveLeafInvoke, shellLeafMissing } from "../leaf-invoke.js";
+const EXIT = { ok: 0, runtime: 1, usage: 2, infra: 3, bounded: 4, validation: 5 };
+function parseFlags(argv, booleans) {
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const body = arg.slice(2);
+    const eq = body.indexOf("=");
+    const rawKey = eq === -1 ? body : body.slice(0, eq);
+    const inline = eq === -1 ? void 0 : body.slice(eq + 1);
+    const key = rawKey.replace(/-([a-z])/gu, (_, c) => c.toUpperCase());
+    if (booleans.has(key)) {
+      options[key] = inline === void 0 ? true : inline !== "false";
+      continue;
+    }
+    if (inline !== void 0) {
+      options[key] = inline;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next === void 0 || next.startsWith("--")) {
+      options[key] = true;
+      continue;
+    }
+    options[key] = next;
+    i += 1;
+  }
+  return { positional, options };
+}
+function str(options, key) {
+  const value = options[key];
+  return typeof value === "string" ? value : void 0;
+}
+function flag(options, key) {
+  return options[key] === true;
+}
+function targetOf(options) {
+  return path.resolve(str(options, "target") ?? str(options, "projectRoot") ?? process.cwd());
+}
+const ADAPTER_TOKENS = ["mobile", "extension", "core"];
+function resolveAdapter(options, target, hint) {
+  const explicit = str(options, "adapter") ?? str(options, "platform");
+  if (explicit && ADAPTER_TOKENS.includes(explicit)) return explicit;
+  if (hint) return hint;
+  return detectAdapter(target);
+}
+function spawnScript(script, args, cwd, json, env) {
+  const isNodeScript = script === process.execPath && args.length > 0;
+  const stem = isNodeScript ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase() : path.basename(script).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase();
+  const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
+  const bin = override ?? script;
+  const directArgs = override !== void 0 && isNodeScript ? args.slice(1) : args;
+  if (shellLeafMissing(bin)) {
+    const message = `leaf could not start: ${path.basename(bin)} (ENOENT)
+  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) \u2014 the shell leaf is missing or not executable`;
+    process.stderr.write(`${message}
+`);
+    return { status: 1, output: message };
+  }
+  const { bin: invokeBin, args: spawnArgs } = resolveLeafInvoke(bin, directArgs);
+  const result = spawnSync(invokeBin, spawnArgs, {
+    cwd,
+    encoding: "utf8",
+    env: env ? { ...process.env, ...env } : process.env,
+    maxBuffer: 64 * 1024 * 1024
+  });
+  if (result.error) {
+    const leaf = isNodeScript ? path.basename(args[0]) : path.basename(script);
+    const code = result.error.code ?? "ESPAWN";
+    const message = `leaf could not start: ${leaf} (${code})
+  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) \u2014 the shell leaf is missing or not executable`;
+    process.stderr.write(`${message}
+`);
+    return { status: 1, output: message };
+  }
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  if (!json && output) process.stderr.write(output);
+  return { status: result.status ?? 1, output };
+}
+function spawnScriptStreaming(script, args, cwd, env) {
+  const isNodeScript = script === process.execPath && args.length > 0;
+  const stem = isNodeScript ? path.basename(args[0]).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase() : path.basename(script).replace(/[^A-Za-z0-9]/gu, "_").toUpperCase();
+  const override = process.env[`MM_HARNESS_SCRIPT_BIN_${stem}`];
+  const bin = override ?? script;
+  const directArgs = override !== void 0 && isNodeScript ? args.slice(1) : args;
+  if (shellLeafMissing(bin)) {
+    const message = `leaf could not start: ${path.basename(bin)} (ENOENT)
+  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) \u2014 the shell leaf is missing or not executable`;
+    process.stderr.write(`${message}
+`);
+    return Promise.resolve({ status: 1, output: message });
+  }
+  const { bin: invokeBin, args: spawnArgs } = resolveLeafInvoke(bin, directArgs);
+  return new Promise((resolve) => {
+    const child = spawn(invokeBin, spawnArgs, {
+      cwd,
+      env: env ? { ...process.env, ...env } : process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let output = "";
+    const tee = (chunk) => {
+      const text = chunk.toString("utf8");
+      output += text;
+      process.stderr.write(text);
+    };
+    child.stdout?.on("data", tee);
+    child.stderr?.on("data", tee);
+    child.on("error", (error) => {
+      const leaf = isNodeScript ? path.basename(args[0]) : path.basename(script);
+      const code = error.code ?? "ESPAWN";
+      const message = `leaf could not start: ${leaf} (${code})
+  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) \u2014 the shell leaf is missing or not executable`;
+      process.stderr.write(`${message}
+`);
+      resolve({ status: 1, output: message });
+    });
+    child.on("close", (status) => {
+      resolve({ status: status ?? 1, output });
+    });
+  });
+}
+import { ADAPTER_DETECT_NEXT } from "../harness.js";
+function usageOut(json, command, message, userAction) {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command, status: "fail", exitCode: EXIT.usage, error: { code: "USAGE", message, userAction } },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 mm-harness ${command}: ${message}
+  Next: ${userAction}`);
+  }
+  return EXIT.usage;
+}
+export {
+  ADAPTER_DETECT_NEXT,
+  EXIT,
+  flag,
+  parseFlags,
+  resolveAdapter,
+  spawnScript,
+  spawnScriptStreaming,
+  str,
+  targetOf,
+  usageOut
+};

package/dist/commands/update.js

@@ -0,0 +1,243 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runnerDir } from "../paths.js";
+import { EXIT, flag, parseFlags } from "./shared.js";
+const PACKAGE_NAME = "@deeeed/metamask-harness";
+const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+const NUDGE_FETCH_TIMEOUT_MS = 300;
+function currentVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(runnerDir, "package.json"), "utf8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function parseVersion(value) {
+  const cleaned = value.replace(/^v/u, "");
+  const dash = cleaned.indexOf("-");
+  const core = dash === -1 ? cleaned : cleaned.slice(0, dash);
+  const pre = dash === -1 ? "" : cleaned.slice(dash + 1);
+  const nums = core.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  while (nums.length < 3) nums.push(0);
+  return { nums, pre };
+}
+function isNewer(candidate, base) {
+  const a = parseVersion(candidate);
+  const b = parseVersion(base);
+  for (let i = 0; i < 3; i += 1) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i];
+  }
+  if (a.pre === b.pre) return false;
+  if (a.pre === "") return true;
+  if (b.pre === "") return false;
+  return a.pre > b.pre;
+}
+function fetchLatest(timeoutMs) {
+  const result = spawnSync("npm", ["view", PACKAGE_NAME, "dist-tags.latest"], {
+    encoding: "utf8",
+    timeout: timeoutMs,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.error) {
+    const code = result.error.code;
+    if (code === "ENOENT") return { error: { kind: "no-npm", message: "npm was not found on PATH" } };
+    return { error: { kind: "unreachable", message: result.error.message } };
+  }
+  if (result.signal) {
+    return { error: { kind: "unreachable", message: `registry fetch timed out after ${timeoutMs}ms` } };
+  }
+  if (result.status !== 0) {
+    return { error: { kind: "unreachable", message: (result.stderr ?? "").trim() || `npm view exited ${result.status}` } };
+  }
+  const latest = (result.stdout ?? "").trim();
+  if (!latest) return { error: { kind: "unreachable", message: "npm returned no dist-tag for latest" } };
+  return { latest };
+}
+async function fetchLatestAsync(timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE_NAME)}/dist-tags`;
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) return { error: { kind: "unreachable", message: `registry returned HTTP ${res.status}` } };
+    const data = await res.json();
+    const latest = data["latest"];
+    if (!latest) return { error: { kind: "unreachable", message: "npm registry returned no latest dist-tag" } };
+    return { latest };
+  } catch (err) {
+    const msg = err.name === "AbortError" ? `registry fetch timed out after ${timeoutMs}ms` : err.message;
+    return { error: { kind: "unreachable", message: msg } };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function teachFailure(json, current, code, message, userAction) {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: "update", status: "fail", current, error: { code, message, userAction } },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 mm-harness update: ${message}
+  Next: ${userAction}`);
+  }
+  return EXIT.infra;
+}
+function emitFetchError(json, error, current) {
+  if (error.kind === "no-npm") {
+    return teachFailure(
+      json,
+      current,
+      "NO_NPM",
+      "npm was not found on PATH \u2014 cannot check for updates",
+      "install Node.js (which bundles npm) from https://nodejs.org, then re-run: mm-harness update"
+    );
+  }
+  return teachFailure(
+    json,
+    current,
+    "REGISTRY_UNREACHABLE",
+    `could not reach the npm registry (${error.message})`,
+    "check your network, then re-run: mm-harness update \u2014 or inspect the registry with: npm config get registry"
+  );
+}
+async function handleUpdate(argv) {
+  const { options } = parseFlags(argv, /* @__PURE__ */ new Set(["check", "json"]));
+  const json = flag(options, "json");
+  const checkOnly = flag(options, "check");
+  const current = currentVersion();
+  const fetched = fetchLatest(3e4);
+  if (fetched.error) return emitFetchError(json, fetched.error, current);
+  const latest = fetched.latest;
+  const updateAvailable = isNewer(latest, current);
+  if (checkOnly) {
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "update", current, latest, updateAvailable }, null, 2));
+    } else if (updateAvailable) {
+      console.error(`mm-harness ${current} \u2192 ${latest} available \xB7 run: mm-harness update`);
+    } else {
+      console.log(`mm-harness is up to date (${current}).`);
+    }
+    return updateAvailable ? EXIT.runtime : EXIT.ok;
+  }
+  if (!updateAvailable) {
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "update", current, latest, updateAvailable: false, updated: false }, null, 2));
+    } else {
+      console.log(`mm-harness is up to date (${current}).`);
+    }
+    return EXIT.ok;
+  }
+  const INSTALL_TIMEOUT_MS = 5 * 60 * 1e3;
+  const install = spawnSync("npm", ["i", "-g", `${PACKAGE_NAME}@latest`], {
+    encoding: "utf8",
+    timeout: INSTALL_TIMEOUT_MS,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (install.error) {
+    const code = install.error.code;
+    if (code === "ENOENT") return emitFetchError(json, { kind: "no-npm", message: "npm was not found on PATH" }, current);
+    return teachFailure(json, current, "INSTALL_FAILED", `global install failed (${install.error.message})`, `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`);
+  }
+  if (install.signal) {
+    return teachFailure(
+      json,
+      current,
+      "INSTALL_FAILED",
+      `global install timed out after ${INSTALL_TIMEOUT_MS / 1e3}s \u2014 slow network or registry unavailable`,
+      `check your network, then retry: mm-harness update \u2014 or install manually: npm i -g ${PACKAGE_NAME}@latest`
+    );
+  }
+  const combined = `${install.stdout ?? ""}${install.stderr ?? ""}`;
+  if (install.status !== 0) {
+    if (/EACCES|permission denied|EPERM/iu.test(combined)) {
+      return teachFailure(
+        json,
+        current,
+        "GLOBAL_DIR_PERMISSION",
+        "global install denied \u2014 the npm global directory is not writable",
+        "either re-run with sudo, or point npm at a user-writable prefix: npm config set prefix ~/.npm-global (then add ~/.npm-global/bin to PATH) and re-run: mm-harness update"
+      );
+    }
+    return teachFailure(
+      json,
+      current,
+      "INSTALL_FAILED",
+      `global install failed (${combined.trim() || `npm exited ${install.status}`})`,
+      `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`
+    );
+  }
+  const rechecked = fetchLatest(3e4);
+  const installed = rechecked.latest ?? latest;
+  if (json) {
+    console.log(JSON.stringify({ schemaVersion: 1, command: "update", current, latest: installed, updateAvailable: true, updated: true, from: current, to: installed }, null, 2));
+  } else {
+    console.log(`mm-harness updated ${current} \u2192 ${installed}.`);
+  }
+  return EXIT.ok;
+}
+function cacheFile() {
+  const override = process.env.MM_HARNESS_UPDATE_CACHE;
+  if (override) return override;
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(base, "mm-harness", "update-check.json");
+}
+function readCache(file) {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (typeof data.lastCheck === "number" && typeof data.latest === "string") {
+      return { lastCheck: data.lastCheck, latest: data.latest };
+    }
+  } catch {
+  }
+  return null;
+}
+function writeCache(file, cache) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache));
+  } catch {
+  }
+}
+function nudgeDisabled() {
+  return process.env.MM_HARNESS_NO_UPDATE_CHECK === "1" || Boolean(process.env.CI);
+}
+function nudgeLine(current, latest) {
+  return isNewer(latest, current) ? `mm-harness ${current} \u2192 ${latest} available \xB7 run: mm-harness update` : null;
+}
+async function maybeNudge(now = Date.now()) {
+  if (nudgeDisabled()) return;
+  const file = cacheFile();
+  const cache = readCache(file);
+  const current = currentVersion();
+  let latest = cache?.latest ?? "";
+  process.once("exit", () => {
+    const line = nudgeLine(current, latest);
+    if (line) process.stderr.write(`${line}
+`);
+  });
+  if (!cache || now - cache.lastCheck >= NUDGE_INTERVAL_MS) {
+    writeCache(file, { lastCheck: now, latest });
+    const fetched = await fetchLatestAsync(NUDGE_FETCH_TIMEOUT_MS);
+    if (fetched.latest) {
+      latest = fetched.latest;
+      writeCache(file, { lastCheck: now, latest });
+    }
+  }
+}
+export {
+  PACKAGE_NAME,
+  currentVersion,
+  fetchLatest,
+  handleUpdate,
+  isNewer,
+  maybeNudge,
+  nudgeDisabled,
+  nudgeLine
+};

package/dist/completions-cache.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+import { recipeRuntimePath } from "./paths.js";
+const COMPLETION_CACHE_VERSION = 1;
+const COMPLETION_CACHE_TTL_MS = 6e4;
+function completionCachePath(projectRoot) {
+  return recipeRuntimePath(projectRoot, ".completion-cache.json");
+}
+function readCompletionCache(projectRoot) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(completionCachePath(projectRoot), "utf8"));
+    if (!raw || raw.version !== COMPLETION_CACHE_VERSION || typeof raw.updatedAt !== "number") return void 0;
+    return raw;
+  } catch {
+    return void 0;
+  }
+}
+function isCacheFresh(cache, now = Date.now()) {
+  return now - cache.updatedAt < COMPLETION_CACHE_TTL_MS;
+}
+function readFreshCandidates(projectRoot, kind, now = Date.now()) {
+  const cache = readCompletionCache(projectRoot);
+  if (!cache || !isCacheFresh(cache, now)) return void 0;
+  return cache.candidates[kind];
+}
+function writeCompletionCandidates(projectRoot, kind, candidates) {
+  const existing = readCompletionCache(projectRoot);
+  const next = {
+    version: COMPLETION_CACHE_VERSION,
+    updatedAt: Date.now(),
+    candidates: { ...existing?.candidates ?? {}, [kind]: candidates }
+  };
+  const file = completionCachePath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(next, null, 2)}
+`);
+}
+function invalidateCompletionCache(projectRoot) {
+  try {
+    fs.rmSync(completionCachePath(projectRoot));
+  } catch {
+  }
+}
+export {
+  COMPLETION_CACHE_TTL_MS,
+  COMPLETION_CACHE_VERSION,
+  completionCachePath,
+  invalidateCompletionCache,
+  isCacheFresh,
+  readCompletionCache,
+  readFreshCandidates,
+  writeCompletionCandidates
+};

package/dist/doctor.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import { color } from "./cli-color.js";
+import { readRuntimeContextField, resolveRuntimeContextPath } from "./harness.js";
+import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
+function repoShape(target) {
+  const exists = (rel) => fs.existsSync(path.join(target, rel));
+  const packageInfo = readPackageInfo(target);
+  const extensionProject = packageInfo.name === "metamask-crx" || exists("app/manifest") && exists("app/scripts") && exists("ui");
+  const mobileProject = packageInfo.name === "metamask" && exists("app/core") && (exists("ios") || exists("android"));
+  return {
+    packageName: packageInfo.name,
+    packageJsonStatus: packageInfo.status,
+    packageJsonError: packageInfo.error,
+    extensionProject,
+    mobileProject,
+    agenticService: exists("app/dev-tools/AgenticService/AgenticService.ts"),
+    mobileProductHarness: false,
+    mobileBridgeScript: true,
+    extensionRuntime: exists(`${recipeHarnessRoot()}/extension`),
+    injectedHarness: exists(`${recipeHarnessRoot()}/mobile`) || exists(`${recipeHarnessRoot()}/extension`),
+    walletFixture: exists(`${recipeRuntimeDir()}/wallet-fixture.json`)
+  };
+}
+function compatibilityMode(adapter, target) {
+  const shape = repoShape(target);
+  if (adapter === "core") {
+    return fs.existsSync(path.join(target, "packages/perps-controller/src/index.ts")) ? "headless controller (no bridge)" : "unsupported/no bridge";
+  }
+  if (adapter === "mobile") {
+    if (shape.injectedHarness && shape.agenticService) return "runner bridge with injected app bridge";
+    if (shape.agenticService) return "runner bridge with app bridge";
+    return "runner bridge available; app bridge not installed";
+  }
+  if (!shape.extensionProject) return "unsupported/no bridge";
+  if (shape.extensionRuntime || shape.injectedHarness) return "bridge present";
+  return "bridge injectable";
+}
+function readPackageInfo(target) {
+  const packageJsonPath = path.join(target, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return { status: "missing", name: null, error: null };
+  }
+  try {
+    const data = readJsonObject(packageJsonPath);
+    return {
+      status: "valid",
+      name: typeof data.name === "string" ? data.name : null,
+      error: null
+    };
+  } catch (error) {
+    return {
+      status: "invalid",
+      name: null,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function fixtureSummary(target) {
+  const candidates = [
+    `${recipeRuntimeDir()}/wallet-fixture.json`
+  ];
+  const rel = candidates.find((candidate) => fs.existsSync(path.join(target, candidate)));
+  if (!rel) return { status: "missing", path: null };
+  try {
+    const data = readJsonObject(path.join(target, rel));
+    return {
+      status: Array.isArray(data.accounts) && data.accounts.length > 0 ? "ready" : "incomplete",
+      path: rel,
+      accountCount: Array.isArray(data.accounts) ? data.accounts.length : 0,
+      hasPassword: typeof data.password === "string" && data.password.length > 0
+    };
+  } catch (error) {
+    return { status: "invalid", path: rel, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+const RUNTIME_CONTEXT_FIELDS = [
+  { key: "slotId", envVars: ["RECIPE_SLOT_ID"], envVar: "RECIPE_SLOT_ID", customize: "farmslot dispatch writes this", adapters: ["mobile", "extension", "core"] },
+  { key: "extensionId", envVars: ["RECIPE_HARNESS_EXTENSION_ID"], envVar: "RECIPE_HARNESS_EXTENSION_ID", customize: "auto-resolved; edit file to pin", adapters: ["extension"] },
+  { key: "cdpPort", envVars: ["RECIPE_CDP_PORT", "CDP_PORT"], envVar: "CDP_PORT", customize: "edit file or pass --cdp-port", adapters: ["extension"] },
+  { key: "runtimeStart.approved", envVars: ["RECIPE_RUNTIME_START_APPROVED"], envVar: "RECIPE_RUNTIME_START_APPROVED", customize: "edit file (true/false)", adapters: ["mobile", "extension"] },
+  { key: "runtimeStart.command", envVars: [], envVar: null, customize: "edit file", adapters: ["mobile", "extension"] },
+  { key: "runtimeStart.readyUrl", envVars: ["RECIPE_RUNTIME_READY_URL"], envVar: "RECIPE_RUNTIME_READY_URL", customize: "edit file", adapters: ["mobile", "extension"] }
+];
+function runtimeContextSummary(target, adapter) {
+  const contextPath = resolveRuntimeContextPath(target);
+  const envOverride = process.env.RECIPE_RUNTIME_CONTEXT ?? null;
+  const fileExists = fs.existsSync(contextPath);
+  const file = envOverride ?? path.relative(target, contextPath);
+  const fields = {};
+  const specs = adapter ? RUNTIME_CONTEXT_FIELDS.filter((spec) => spec.adapters.includes(adapter)) : RUNTIME_CONTEXT_FIELDS;
+  for (const spec of specs) {
+    const envValue = spec.envVars.map((name) => process.env[name]).find((value) => value !== void 0 && value !== "");
+    if (envValue !== void 0) {
+      fields[spec.key] = { value: envValue, source: "env", envVar: spec.envVar, customize: spec.customize };
+      continue;
+    }
+    const fileValue = fileExists ? readRuntimeContextField(contextPath, spec.key) : void 0;
+    fields[spec.key] = fileValue !== void 0 ? { value: fileValue, source: "file", envVar: spec.envVar, customize: spec.customize } : { value: null, source: "default", envVar: spec.envVar, customize: spec.customize };
+  }
+  return { file, fileExists, envOverride, fields };
+}
+function renderRuntimeContext(runtimeContext) {
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const lines = [];
+  lines.push(
+    runtimeContext.fileExists ? `${out("label", "runtime-context:")} ${runtimeContext.file} ${out("ok", "(present)")}` : `${out("label", "runtime-context:")} ${runtimeContext.file} ${out("dim", "(absent \u2014 written by farmslot prepare/dispatch)")}`
+  );
+  for (const [key, field] of Object.entries(runtimeContext.fields)) {
+    const isSet = field.value !== void 0 && field.value !== null && field.value !== "";
+    const value = isSet ? out("ok", String(field.value)) : out("dim", "(unset)");
+    const origin = field.source === "env" && field.envVar ? `env ${field.envVar}` : field.source;
+    const originTag = isSet ? out("accent", `[${origin}]`) : out("dim", `[${origin}]`);
+    lines.push(`  ${key.padEnd(22)} ${value}  ${originTag} ${out("dim", `\u2014 ${field.customize}`)}`);
+  }
+  return lines.join("\n");
+}
+function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter)) {
+  const mode = compatibilityMode(adapter, target);
+  const manifestErrors = Number(manifestValidation.summary?.errors ?? 0);
+  const status = manifestErrors > 0 ? "fail" : "pass";
+  const checks = [
+    {
+      id: "manifest",
+      status: manifestErrors === 0 ? "pass" : "fail",
+      message: manifestErrors === 0 ? "Action manifest is valid Recipe v1." : `Action manifest has ${manifestErrors} validation error(s).`
+    },
+    {
+      id: "bridge",
+      status: mode === "unsupported/no bridge" ? "fail" : "pass",
+      message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
+    }
+  ];
+  return {
+    schemaVersion: 1,
+    protocolVersion: "v1",
+    runner_protocol_version: 1,
+    status,
+    checks: [...checks],
+    adapter,
+    target,
+    runner: {
+      name: "@metamask/recipe-runner",
+      runnerDir,
+      actionManifestPath,
+      harnessPackage: "@farmslot/recipe-harness"
+    },
+    compatibilityMode: mode,
+    shape: repoShape(target),
+    fixture: fixtureSummary(target),
+    runtimeContext: runtimeContextSummary(target, adapter),
+    manifestValidation: manifestValidation.summary
+  };
+}
+function readJsonObject(file) {
+  const value = readJson(file);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Expected JSON object in ${file}`);
+  }
+  return value;
+}
+export {
+  compatibilityMode,
+  createDoctorReport,
+  fixtureSummary,
+  renderRuntimeContext,
+  repoShape,
+  runtimeContextSummary
+};