@deeeed/metamask-harness 0.26.5 → 0.28.0

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/mobile-device-view.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { resolveMobileToolPath } from "../../library/actions/mobile/platform/tool-paths.mjs";
 import { listConnectedDevices } from "../devices.js";
 import { renderDeviceList, scopedDevices } from "./device-target.js";
 import { probeMobileLiveState } from "./status-probe.js";
@@ -116,8 +117,10 @@ function selectedAndroidPortHints(devices, liveMap) {
   }).filter((hint) => hint.reversePorts.length > 0);
 }
 function androidReversePorts(serial) {
+  const adbPath = resolveMobileToolPath("adb");
+  if (!adbPath) return [];
   try {
-    const out = execFileSync("adb", ["-s", serial, "reverse", "--list"], {
+    const out = execFileSync(adbPath, ["-s", serial, "reverse", "--list"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5e3

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/devices.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 function listConnectedDevices(platform) {
   const devices = [];
   if (!platform || platform === "android") devices.push(...listAndroidDevices());
@@ -6,9 +7,11 @@ function listConnectedDevices(platform) {
   return devices;
 }
 function listAndroidDevices() {
+  const adbPath = resolveMobileToolPath("adb");
+  if (!adbPath) return [];
   let output;
   try {
-    output = execFileSync("adb", ["devices", "-l"], {
+    output = execFileSync(adbPath, ["devices", "-l"], {
       encoding: "utf8",
       timeout: 5e3,
       stdio: ["ignore", "pipe", "ignore"]

package/dist/doctor.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { color } from "./cli-color.js";
+import {
+  mobileToolRecovery,
+  resolveMobileToolPath
+} from "../library/actions/mobile/platform/tool-paths.mjs";
 import { mobilePerpsEnvironment } from "./adapters/mobile/perps-env.js";
 import { readRuntimeContextField, resolveRuntimeContextPath } from "./harness.js";
 import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
@@ -128,7 +132,7 @@ function renderRuntimeContext(runtimeContext) {
   }
   return lines.join("\n");
 }
-function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter)) {
+function createDoctorReport(adapter, target, manifestValidation, actionManifestPath = manifestPath(adapter), mobilePlatform) {
   const mode = compatibilityMode(adapter, target);
   const manifestErrors = Number(manifestValidation.summary?.errors ?? 0);
   const checks = [
@@ -143,7 +147,8 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
       status: mode === "unsupported/no bridge" ? "fail" : "pass",
       required: false,
       message: mode === "unsupported/no bridge" ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`
-    }
+    },
+    ...adapter === "mobile" ? mobileToolDoctorChecks(mobilePlatform) : []
   ];
   const requiredChecks = requiredDoctorCheckSummary(checks);
   return {
@@ -164,6 +169,23 @@ function createDoctorReport(adapter, target, manifestValidation, actionManifestP
     manifestValidation: manifestValidation.summary
   };
 }
+function mobileToolDoctorChecks(platform) {
+  const specs = platform === "android" ? [{ tool: "adb", platform: "Android" }] : platform === "ios" ? [{ tool: "idb", platform: "iOS" }] : [
+    { tool: "adb", platform: "Android" },
+    { tool: "idb", platform: "iOS" }
+  ];
+  return specs.map(({ tool, platform: platformName }) => {
+    const resolved = resolveMobileToolPath(tool);
+    return {
+      id: `device-tool-${tool}`,
+      status: resolved ? "pass" : "fail",
+      required: platform !== void 0,
+      message: resolved ? `${platformName} device tool ${tool} is ready.` : `${platformName} device tool ${tool} is unavailable.`,
+      ...resolved ? { detail: resolved } : {},
+      ...!resolved ? { userAction: mobileToolRecovery(tool) } : {}
+    };
+  });
+}
 function runnerInstallKind(runnerRoot, invokedPath, executablePath) {
   const normalizedRoot = path.normalize(runnerRoot);
   const nodeModulesSegment = `${path.sep}node_modules${path.sep}`;
@@ -230,6 +252,7 @@ export {
   createDoctorReport,
   fixtureFileSummary,
   fixtureSummary,
+  mobileToolDoctorChecks,
   renderRuntimeContext,
   repoShape,
   requiredDoctorCheckSummary,

package/dist/mm-harness-cli.js

@@ -121,6 +121,7 @@ Materialize:
 
   query                              Search names, categories, fields, and descriptions (typo-tolerant)
   --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
+  --matrix                           Compare action availability across Mobile, Extension, and Core
   --categories                       List compact action categories and counts
   --category <name>                  List only one category (for example ui, wallet, or perps)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
@@ -130,6 +131,7 @@ Materialize:
 
 Example:
   mm-harness actions --adapter mobile
+  mm-harness actions --matrix --json
   mm-harness actions positions --adapter mobile
   mm-harness actions --adapter mobile --categories --json
   mm-harness actions --adapter mobile --category ui --json

package/dist/recipe-security.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, readFile, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 const READ_ONLY_CUSTOM_ACTIONS = /* @__PURE__ */ new Set([
+  "ui.locators",
   "metamask.wallet.fixture_status",
   "metamask.wallet.list_accounts",
   "metamask.wallet.read_state",