@deeeed/metamask-harness 0.27.0 → 0.29.0

package/dist/commands/launch/extension.js

@@ -1,13 +1,19 @@
 import { execFileSync } from "node:child_process";
 import http from "node:http";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 import {
   depsCheck,
   recordDepsBaseline
 } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { colorHumanMessage } from "../../cli-color.js";
-import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
+import {
+  importRecipeHarnessRuntimeCdp,
+  recipeHarnessPath,
+  recipeRuntimeDir,
+  runnerDir
+} from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
 import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
@@ -15,6 +21,10 @@ import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
 import { EXIT, spawnScriptStreaming } from "../shared.js";
+const { CdpSession } = await importRecipeHarnessRuntimeCdp();
+const { RUNTIME_IDENTITY_FILENAME, RUNTIME_NONCE_PREFIX } = createRequire(import.meta.url)(
+  path.join(runnerDir, "adapters/extension/lib/chrome-args.cjs")
+);
 function extensionDepsBlock(target) {
   if (!fs.existsSync(path.join(target, "package.json"))) return null;
   const deps = depsCheck(target);
@@ -73,7 +83,8 @@ async function extensionRuntimeReusable(target) {
   if (isExtensionDistStale(target)) return false;
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const reachable = await cdpVersionReachable(cdpPort);
-    const owned = reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
+    const nonceOwned = reachable && await cdpOwnedByRuntimeNonce(cdpPort, target);
+    const owned = nonceOwned || reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
     const targetPresent = owned && await cdpHasExpectedExtensionTarget(cdpPort, target);
     const healthy = targetPresent && await cdpRuntimeHealthy(cdpPort, target);
     if (healthy) return true;
@@ -88,17 +99,20 @@ function expectedChromeProfile(target) {
 function expectedRuntimeDist(target) {
   return path.resolve(path.join(target, recipeRuntimeDir(), process.env.RECIPE_RUNTIME_DIST_DIR || "runtime-dist"));
 }
-function cdpOwnedByExpectedRuntime(port, target) {
-  let pids = [];
-  try {
-    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    });
-    pids = out.split(/\s+/u).filter((value) => /^\d+$/u.test(value));
-  } catch {
-    return false;
+function commandHasExactFlagValue(command, flag, value) {
+  const expected = `${flag}=${value}`;
+  let offset = command.indexOf(expected);
+  while (offset !== -1) {
+    const before = offset === 0 ? "" : command[offset - 1];
+    const afterOffset = offset + expected.length;
+    const after = afterOffset === command.length ? "" : command[afterOffset];
+    if ((!before || /\s/u.test(before)) && (!after || /\s/u.test(after))) return true;
+    offset = command.indexOf(expected, offset + 1);
   }
+  return false;
+}
+function cdpOwnedByExpectedRuntime(port, target) {
+  const pids = cdpListenerPids(port);
   const profile = expectedChromeProfile(target);
   const runtimeDist = expectedRuntimeDist(target);
   for (const pid of pids) {
@@ -107,7 +121,7 @@ function cdpOwnedByExpectedRuntime(port, target) {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"]
       });
-      if (command.includes(`--user-data-dir=${profile}`) && (command.includes(`--load-extension=${runtimeDist}`) || command.includes(`--disable-extensions-except=${runtimeDist}`))) {
+      if (commandHasExactFlagValue(command, "--user-data-dir", profile) && (commandHasExactFlagValue(command, "--load-extension", runtimeDist) || commandHasExactFlagValue(command, "--disable-extensions-except", runtimeDist))) {
         return true;
       }
     } catch {
@@ -115,21 +129,118 @@ function cdpOwnedByExpectedRuntime(port, target) {
   }
   return false;
 }
-function cdpVersionReachable(port) {
+async function cdpOwnedByRuntimeNonce(port, target) {
+  const identity = readRuntimeIdentity(port, target);
+  if (!identity) return false;
+  const version = await cdpVersion(port);
+  const webSocketDebuggerUrl = version?.webSocketDebuggerUrl;
+  if (typeof webSocketDebuggerUrl !== "string" || !webSocketDebuggerUrl) return false;
+  let session;
+  try {
+    session = await CdpSession.connect(webSocketDebuggerUrl, { timeoutMs: 2e3 });
+    const result = await boundedBrowserCdpCall(
+      session,
+      "Browser.getBrowserCommandLine",
+      {},
+      2e3
+    );
+    if (!Array.isArray(result.arguments)) return false;
+    const nonceArgs = result.arguments.filter(
+      (argument) => typeof argument === "string" && argument.startsWith(RUNTIME_NONCE_PREFIX)
+    );
+    return nonceArgs.length === 1 && nonceArgs[0] === `${RUNTIME_NONCE_PREFIX}${identity.nonce}`;
+  } catch {
+    return false;
+  } finally {
+    session?.close();
+  }
+}
+async function boundedBrowserCdpCall(session, method, params, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      session.call(method, params),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${method} timed out after ${timeoutMs}ms.`)),
+          timeoutMs
+        );
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function readRuntimeIdentity(port, target) {
+  const expectedPort = Number(port);
+  if (!Number.isInteger(expectedPort) || expectedPort <= 0 || expectedPort > 65535) return null;
+  const identityPath = path.join(target, recipeRuntimeDir(), RUNTIME_IDENTITY_FILENAME);
+  let descriptor;
+  try {
+    descriptor = fs.openSync(
+      identityPath,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW
+    );
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size <= 0 || stat.size > 4096 || (stat.mode & 63) !== 0) {
+      return null;
+    }
+    const parsed = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+    if (parsed.port !== expectedPort || !Number.isInteger(parsed.pid) || Number(parsed.pid) <= 0 || !Number.isInteger(parsed.startedAt) || Number(parsed.startedAt) <= 0 || Number(parsed.startedAt) > Date.now() + 6e4 || typeof parsed.nonce !== "string" || !/^[a-f0-9]{64}$/u.test(parsed.nonce)) {
+      return null;
+    }
+    if (!cdpListenerPids(port).includes(String(parsed.pid))) return null;
+    return parsed;
+  } catch {
+    return null;
+  } finally {
+    if (descriptor !== void 0) fs.closeSync(descriptor);
+  }
+}
+function cdpListenerPids(port) {
+  try {
+    const out = execFileSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.split(/\s+/u).filter((value) => /^\d+$/u.test(value));
+  } catch {
+    return [];
+  }
+}
+async function cdpVersionReachable(port) {
+  return Boolean(await cdpVersion(port));
+}
+function cdpVersion(port) {
   return new Promise((resolve) => {
     const request = http.get(
       { host: "127.0.0.1", port: Number(port), path: "/json/version", timeout: 2e3 },
       (response) => {
-        response.resume();
-        const code = response.statusCode ?? 0;
-        resolve(code >= 200 && code < 300);
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          const code = response.statusCode ?? 0;
+          if (code < 200 || code >= 300) {
+            resolve(null);
+            return;
+          }
+          try {
+            const parsed = JSON.parse(body);
+            resolve(parsed && typeof parsed === "object" ? parsed : null);
+          } catch {
+            resolve(null);
+          }
+        });
       }
     );
     request.on("timeout", () => {
       request.destroy();
-      resolve(false);
+      resolve(null);
     });
-    request.on("error", () => resolve(false));
+    request.on("error", () => resolve(null));
   });
 }
 function expectedExtensionId(target) {

package/dist/commands/manifest.js

@@ -18,22 +18,33 @@ import {
 import { metaMaskActionExecutionCapabilities } from "../recipe-security.js";
 import { closest } from "../command-contract.js";
 const OFFICIAL_ACTIONS = new Set(OFFICIAL_RECIPE_ACTIONS);
+const ACTION_MATRIX_ADAPTERS = ["mobile", "extension", "core"];
+function actionLibraryContextArgs(librarySources) {
+  return (librarySources ?? []).filter((source) => source.name !== "metamask").map((source) => {
+    const entry = source.name ? `${source.name}=${source.root}` : source.root;
+    return ` --library ${shellQuoteArg(entry)}`;
+  }).join("");
+}
 async function handleActions({ options, positional }) {
-  const { adapter, target } = resolveAdapter(options);
   const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+  const json = optionFlag(options, "json");
+  const action = optionString(options, "action");
+  const query = positional[0]?.trim();
+  const category = optionString(options, "category")?.toLowerCase();
+  if (optionFlag(options, "matrix")) {
+    return handleActionMatrix(options, { json, action, query, category, librarySources });
+  }
+  const { adapter, target } = resolveAdapter(options);
+  const actionManifestOverride = optionString(options, "actionManifest");
   const { manifest, actionSources } = await resolveActionManifest(
     adapter,
-    optionString(options, "actionManifest"),
+    actionManifestOverride,
     librarySources
   );
   if (optionFlag(options, "raw")) {
     console.log(JSON.stringify(manifest, null, 2));
     return EXIT.ok;
   }
-  const json = optionFlag(options, "json");
-  const action = optionString(options, "action");
-  const query = positional[0]?.trim();
-  const category = optionString(options, "category")?.toLowerCase();
   const categoriesOnly = optionFlag(options, "categories");
   const all = describeManifestActions(manifest, actionSources);
   const categories = summarizeActionCategories(all);
@@ -67,6 +78,36 @@ async function handleActions({ options, positional }) {
   }
   const actions = action ? fuzzyResolveActions(categoryActions, action) : query ? searchActions(categoryActions, query) : categoryActions;
   if (action && actions.length === 0) {
+    const refusal = actionManifestOverride ? void 0 : resolveActionCapabilityRefusal(
+      action,
+      adapter,
+      await resolveActionCapabilityMatrix(librarySources)
+    );
+    if (refusal) {
+      const satisfying = refusal.satisfyingAdapters.join(", ");
+      const message2 = `missing action capability "${refusal.capability}" for the ${adapter} adapter.`;
+      const userAction2 = `Satisfying adapters for "${refusal.capability}": ${satisfying}. Inspect: mm-harness actions --matrix --action ${shellQuoteArg(refusal.capability)}${actionLibraryContextArgs(librarySources)} --json`;
+      if (json) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "actions",
+          adapter,
+          action,
+          category,
+          error: {
+            code: "ACTION_CAPABILITY_UNAVAILABLE",
+            message: message2,
+            capability: refusal.capability,
+            satisfyingAdapters: refusal.satisfyingAdapters,
+            userAction: userAction2
+          }
+        }, null, 2));
+      } else {
+        console.error(`\u2717 mm-harness actions: ${message2}
+  Next: ${userAction2}`);
+      }
+      return EXIT.usage;
+    }
     const message = `no action matches "${action}" for the ${adapter} adapter.`;
     const userAction = `mm-harness actions --adapter ${adapter}`;
     if (json) {
@@ -126,6 +167,154 @@ ${color("label", "Related:", { stream: process.stdout })} ${relatedActions.join(
   }
   return 0;
 }
+async function resolveActionCapabilityMatrix(librarySources) {
+  const catalogs = await Promise.all(
+    ACTION_MATRIX_ADAPTERS.map(async (adapter) => {
+      const { manifest, actionSources } = await resolveActionManifest(
+        adapter,
+        void 0,
+        librarySources
+      );
+      return { adapter, actions: describeManifestActions(manifest, actionSources) };
+    })
+  );
+  const actions = /* @__PURE__ */ new Map();
+  for (const catalog of catalogs) {
+    for (const action of catalog.actions) {
+      const entry = actions.get(action.name) ?? { entries: [], adapters: /* @__PURE__ */ new Set() };
+      entry.entries.push(action);
+      entry.adapters.add(catalog.adapter);
+      actions.set(action.name, entry);
+    }
+  }
+  return [...actions.entries()].map(([name, entry]) => {
+    const representative = entry.entries[0];
+    const satisfyingAdapters = ACTION_MATRIX_ADAPTERS.filter(
+      (adapter) => entry.adapters.has(adapter)
+    );
+    return {
+      name,
+      category: representative.category,
+      description: entry.entries.map((action) => action.description).find(Boolean) ?? "",
+      fields: [...new Set(entry.entries.flatMap((action) => action.fields))].sort(),
+      support: Object.fromEntries(
+        ACTION_MATRIX_ADAPTERS.map((adapter) => [
+          adapter,
+          entry.adapters.has(adapter) ? "available" : "unavailable"
+        ])
+      ),
+      satisfyingAdapters
+    };
+  }).sort((left, right) => left.name.localeCompare(right.name));
+}
+function resolveActionCapabilityRefusal(action, adapter, matrix) {
+  const matches = fuzzyResolveActions(matrix, action);
+  if (matches.length !== 1 || matches[0].satisfyingAdapters.includes(adapter)) {
+    return void 0;
+  }
+  return {
+    capability: matches[0].name,
+    satisfyingAdapters: matches[0].satisfyingAdapters
+  };
+}
+function missingActionCapabilities(adapter, actionNames, matrix) {
+  return [...new Set(actionNames)].flatMap((action) => {
+    const row = matrix.find((entry) => entry.name === action);
+    if (!row || row.satisfyingAdapters.includes(adapter)) return [];
+    return [{ capability: row.name, satisfyingAdapters: row.satisfyingAdapters }];
+  });
+}
+function handleActionMatrixError(json, code, message, userAction, details = {}) {
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "actions",
+      view: "matrix",
+      ...details,
+      error: { code, message, userAction }
+    }, null, 2));
+  } else {
+    console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+  }
+  return EXIT.usage;
+}
+async function handleActionMatrix(options, input) {
+  const inspectCommand = `mm-harness actions --matrix${actionLibraryContextArgs(input.librarySources)} --json`;
+  const conflicts = [
+    optionFlag(options, "raw") ? "--raw" : void 0,
+    optionFlag(options, "categories") ? "--categories" : void 0,
+    optionString(options, "adapter") ? "--adapter" : void 0,
+    optionString(options, "platform") ? "--platform" : void 0,
+    optionString(options, "actionManifest") ? "--action-manifest" : void 0
+  ].filter((value) => Boolean(value));
+  if (conflicts.length > 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_MATRIX_CONFLICT",
+      `--matrix cannot be combined with ${conflicts.join(", ")}.`,
+      inspectCommand
+    );
+  }
+  const matrix = await resolveActionCapabilityMatrix(input.librarySources);
+  const categories = summarizeActionCategories(matrix);
+  const categoryActions = input.category ? matrix.filter((entry) => entry.category === input.category) : matrix;
+  if (input.category && categoryActions.length === 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_CATEGORY_UNKNOWN",
+      `no action category matches "${input.category}" across the adapter matrix.`,
+      inspectCommand,
+      { category: input.category, availableCategories: categories }
+    );
+  }
+  const actions = input.action ? fuzzyResolveActions(categoryActions, input.action) : input.query ? searchActions(categoryActions, input.query) : categoryActions;
+  if (input.action && actions.length === 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_UNKNOWN",
+      `no action capability matches "${input.action}" across Mobile, Extension, or Core.`,
+      inspectCommand,
+      { action: input.action, category: input.category }
+    );
+  }
+  if (input.query && actions.length === 0) {
+    return handleActionMatrixError(
+      input.json,
+      "ACTION_SEARCH_EMPTY",
+      `no action capability matches search "${input.query}" across Mobile, Extension, or Core.`,
+      inspectCommand,
+      { query: input.query, category: input.category }
+    );
+  }
+  if (input.json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "actions",
+      view: "matrix",
+      adapters: ACTION_MATRIX_ADAPTERS,
+      ...input.query ? { query: input.query } : {},
+      ...input.category ? { category: input.category } : {},
+      actions
+    }, null, 2));
+  } else {
+    console.log(renderHumanActionMatrix(actions));
+  }
+  return EXIT.ok;
+}
+function renderHumanActionMatrix(actions) {
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const width = Math.max("action capability".length, ...actions.map((action) => action.name.length));
+  const cell = (status, width2) => status === "available" ? out("accent", "yes".padEnd(width2)) : out("dim", "\u2014".padEnd(width2));
+  return [
+    out("bold", "action capability matrix"),
+    out("comment", "Inspect one: mm-harness actions --matrix --action <name> --json"),
+    `${"action capability".padEnd(width)}  mobile  extension  core`,
+    ...actions.map(
+      (action) => `${action.name.padEnd(width)}  ${cell(action.support.mobile, 6)}  ${cell(action.support.extension, 9)}  ${cell(action.support.core, 4)}`
+    )
+  ].join("\n");
+}
 function fuzzyResolveActions(entries, query) {
   const exactFull = entries.filter((e) => e.name === query);
   if (exactFull.length > 0) return exactFull;
@@ -393,13 +582,19 @@ function levenshtein(left, right) {
   return prior[right.length] ?? right.length;
 }
 export {
+  ACTION_MATRIX_ADAPTERS,
   actionExampleCommand,
+  actionLibraryContextArgs,
   describeManifestActions,
   findRelatedActions,
   fuzzyResolveActions,
   handleActions,
+  missingActionCapabilities,
   renderHumanActionCatalog,
   renderHumanActionExample,
+  renderHumanActionMatrix,
+  resolveActionCapabilityMatrix,
+  resolveActionCapabilityRefusal,
   searchActions,
   summarizeActionCategories,
   summarizeDescribedAction

package/dist/commands/parse-args.js

@@ -29,6 +29,7 @@ function parseArgs(argv, command) {
     "list",
     "describe",
     "raw",
+    "matrix",
     "categories",
     "fix",
     "force",

package/dist/commands/run.js

@@ -35,6 +35,30 @@ import { JsonStreamWriter } from "../json-stream.js";
 import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
 import { recipeTrustFailure } from "../recipe-security.js";
 import { recordCommandEvidence, redactStructuredValue } from "../command-journal.js";
+import {
+  actionLibraryContextArgs,
+  missingActionCapabilities,
+  resolveActionCapabilityMatrix
+} from "./manifest.js";
+async function validationCapabilityRefusals(adapter, findings, librarySources) {
+  const actionNames = findings.flatMap((finding) => {
+    if (finding.code !== "recipe.action_not_declared_by_manifest") return [];
+    const match = /^Recipe action ([^ ]+) is not declared by the runner action manifest[.]?$/u.exec(finding.message);
+    return match?.[1] ? [match[1]] : [];
+  });
+  if (actionNames.length === 0) return [];
+  return missingActionCapabilities(
+    adapter,
+    actionNames,
+    await resolveActionCapabilityMatrix(librarySources)
+  );
+}
+function capabilityValidationUserAction(adapter, refusals, libraryContextArgs) {
+  const capabilities = refusals.map(
+    (refusal) => `"${refusal.capability}" [${refusal.satisfyingAdapters.join(", ")}]`
+  ).join("; ");
+  return `Missing action capabilities for ${adapter}, with satisfying adapters: ${capabilities}. Inspect: mm-harness actions --matrix${libraryContextArgs} --json; then rerun from a checkout matching a satisfying adapter, splitting the recipe if no single adapter satisfies every capability`;
+}
 async function handleRun(parsed) {
   const stream = new JsonStreamWriter("run", optionFlag(parsed.options, "jsonStream"));
   const restoreStdout = stream.isolateStdout();
@@ -165,7 +189,21 @@ async function handleRunInner({ positional, options }, stream) {
     );
   }
   if (validated.errorCount > 0) {
-    return emitRunValidationError(jsonOutput, stream, adapter, validated.recipeFile, validated.findings, validated.errorCount);
+    const capabilityRefusals = optionString(options, "actionManifest") ? [] : await validationCapabilityRefusals(
+      adapter,
+      validated.findings,
+      validated.librarySources
+    );
+    return emitRunValidationError(
+      jsonOutput,
+      stream,
+      adapter,
+      validated.recipeFile,
+      validated.findings,
+      validated.errorCount,
+      capabilityRefusals,
+      actionLibraryContextArgs(validated.librarySources)
+    );
   }
   const depsBlock = adapter === "core" && await recipeUsesCoreController(validated.recipe, validated.librarySources) ? coreDependencyBlock(target) : null;
   if (depsBlock) {
@@ -447,8 +485,23 @@ async function handleRunPlan(recipeArg, params, options, stream) {
       userAction
     );
   }
-  const { recipe, recipeFile, findings, errorCount, manifestOk, schemaValid, effectiveParams } = validated;
+  const {
+    recipe,
+    recipeFile,
+    findings,
+    errorCount,
+    manifestOk,
+    schemaValid,
+    effectiveParams,
+    librarySources
+  } = validated;
   const status = errorCount === 0 ? "pass" : "fail";
+  const capabilityRefusals = status === "fail" && !optionString(options, "actionManifest") ? await validationCapabilityRefusals(adapter, findings, librarySources) : [];
+  const failureUserAction = capabilityRefusals.length > 0 ? capabilityValidationUserAction(
+    adapter,
+    capabilityRefusals,
+    actionLibraryContextArgs(librarySources)
+  ) : runPlanProbe(adapter, recipeFile);
   const nodeCount = countRecipeNodes(recipe);
   const artifactsDir = optionString(options, "artifactsDir");
   const plan = [
@@ -514,7 +567,8 @@ async function handleRunPlan(recipeArg, params, options, stream) {
     payload.error = {
       code: "RECIPE_VALIDATION_FAILED",
       message: `recipe validation found ${errorCount} error(s)`,
-      userAction: runPlanProbe(adapter, recipeFile)
+      ...capabilityRefusals.length > 0 ? { missingCapabilities: capabilityRefusals } : {},
+      userAction: failureUserAction
     };
   }
   if (stream.enabled) {
@@ -534,7 +588,7 @@ async function handleRunPlan(recipeArg, params, options, stream) {
         console.log(`  ${finding.severity === "error" ? "\u2717" : "\u26A0"} ${finding.code} ${finding.path} \u2014 ${finding.message}`);
       }
     }
-    if (status === "fail") console.error(`  Next: ${runPlanProbe(adapter, recipeFile)}`);
+    if (status === "fail") console.error(`  Next: ${failureUserAction}`);
   }
   return status === "pass" ? EXIT.ok : EXIT.validation;
 }
@@ -582,10 +636,17 @@ function emitRunUsageError(json, stream, adapter, recipeFile, code, message, use
   }
   return EXIT.usage;
 }
-function emitRunValidationError(json, stream, adapter, recipeFile, findings, errorCount) {
+function emitRunValidationError(json, stream, adapter, recipeFile, findings, errorCount, capabilityRefusals, libraryContextArgs) {
   const message = `recipe validation found ${errorCount} error(s)`;
-  const userAction = runPlanProbe(adapter, recipeFile);
-  stream.error({ code: "RECIPE_VALIDATION_FAILED", message, userAction, findings });
+  const userAction = capabilityRefusals.length > 0 ? capabilityValidationUserAction(adapter, capabilityRefusals, libraryContextArgs) : runPlanProbe(adapter, recipeFile);
+  const capabilityDetails = capabilityRefusals.length > 0 ? { missingCapabilities: capabilityRefusals } : {};
+  stream.error({
+    code: "RECIPE_VALIDATION_FAILED",
+    message,
+    userAction,
+    findings,
+    ...capabilityDetails
+  });
   if (json) {
     console.log(
       JSON.stringify(
@@ -599,7 +660,12 @@ function emitRunValidationError(json, stream, adapter, recipeFile, findings, err
           mutations: [],
           recipe: recipeFile,
           findings,
-          error: { code: "RECIPE_VALIDATION_FAILED", message, userAction }
+          error: {
+            code: "RECIPE_VALIDATION_FAILED",
+            message,
+            userAction,
+            ...capabilityDetails
+          }
         },
         null,
         2

package/dist/commands/setup-base.js

@@ -0,0 +1,24 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { runnerDir } from "../paths.js";
+function handleSetupBase(argv) {
+  const script = path.join(runnerDir, "adapters", "shared", "setup-base.sh");
+  const result = spawnSync("bash", [script, ...argv], {
+    cwd: process.cwd(),
+    env: { ...process.env, MM_HARNESS_NODE: process.execPath },
+    stdio: "inherit"
+  });
+  if (result.error) {
+    const code = result.error.code ?? "ESPAWN";
+    process.stderr.write(
+      `setup-base could not start (${code}).
+  Next: npm i -g @deeeed/metamask-harness@latest
+`
+    );
+    return 3;
+  }
+  return result.status ?? 1;
+}
+export {
+  handleSetupBase
+};