@deeeed/metamask-harness 0.17.5 → 0.18.0

package/dist/commands/call.js

@@ -1,12 +1,11 @@
 import fs from "node:fs";
-import { mkdtemp } from "node:fs/promises";
-import os from "node:os";
+import { createHash } from "node:crypto";
 import path from "node:path";
-import { loadActionManifest } from "../manifest.js";
+import { resolveActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
 import { recipeRunning } from "../heal-bounds.js";
 import { color } from "../cli-color.js";
-import { EXIT } from "./shared.js";
+import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
 import { describeManifestActions, fuzzyResolveActions } from "./manifest.js";
 import {
   parseArgs,
@@ -15,6 +14,7 @@ import {
   optionString,
   resolveAdapter,
   runtimeOptionsFromCli,
+  shellQuote,
   usageError
 } from "./parse-args.js";
 import { getAdapterSurface } from "../adapters/surface.js";
@@ -27,11 +27,14 @@ import {
   prepareHeal,
   recoverRunInfra,
   resolveMetaMaskLibrarySources,
+  preflightRecipe,
   runRecipe,
   synthesizeOneNodeRecipe,
   validateRecipeAdapterAware
 } from "./run-engine.js";
 import { acquireCheckoutLock } from "../checkout-lock.js";
+import { formatRunDiagnosticsForHuman, readRunDiagnosticsDocument } from "../run-diagnostics.js";
+import { recipeTrustFailure } from "../recipe-security.js";
 async function handleCall(argv) {
   if (argv.includes("--list")) {
     const { options: options2 } = parseArgs(argv, "call");
@@ -50,7 +53,8 @@ async function handleCall(argv) {
     let discovery = "mm-harness actions";
     try {
       const { adapter: adapter2 } = resolveAdapter(options);
-      const manifest2 = loadActionManifest(adapter2, optionString(options, "actionManifest"));
+      const librarySources2 = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+      const { manifest: manifest2 } = await resolveActionManifest(adapter2, optionString(options, "actionManifest"), librarySources2);
       const { getRecipeActionManifestActionNames: getRecipeActionManifestActionNames2 } = await importRecipeProtocol();
       const exampleAction = pickCallExampleAction(getRecipeActionManifestActionNames2(manifest2));
       example = `mm-harness call ${exampleAction} --adapter ${adapter2}`;
@@ -59,44 +63,65 @@ async function handleCall(argv) {
     }
     const message = `call requires <action>. Example: ${example}`;
     const userAction = `${example}   # see the vocabulary: ${discovery}`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", error: { code: "USAGE", message, userAction } }, null, 2));
+    if (json) console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "call",
+      status: "fail",
+      error: { code: "CLI_MISSING_POSITIONAL", message, userAction },
+      exitCode: EXIT.usage
+    }, null, 2));
     else console.error(`${message}
   See the vocabulary: ${discovery}`);
     return EXIT.usage;
   }
   const { adapter, target } = resolveAdapter(options);
+  if (!fs.existsSync(target)) {
+    return usageOut(
+      json,
+      "call",
+      `target does not exist: ${target}`,
+      "pass --target <metamask-checkout> pointing to an existing checkout"
+    );
+  }
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("call", adapter, options, { gate: true, rerun: "" });
   if ("code" in dtResult) {
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, error: { code: dtResult.code, message: dtResult.message } }, null, 2));
-    else console.error(`\u2717 call: ${dtResult.message}`);
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, error: { code: dtResult.code, message: dtResult.message, userAction: dtResult.userAction } }, null, 2));
+    else console.error(`\u2717 call: ${dtResult.message}
+  Next: ${dtResult.userAction}`);
     return EXIT.usage;
   }
   if (recipeRunning(target)) {
     const msg = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
+    const userAction = `inspect the checkout state with: mm-harness status --target ${shellQuote(target)} --json; retry after the active recipe finishes`;
     if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: "call", status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg } }, null, 2));
+      console.log(JSON.stringify({ schemaVersion: 1, command: "call", status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg, userAction } }, null, 2));
     } else {
-      console.error(`\u2717 mm-harness call: ${msg}`);
+      console.error(`\u2717 mm-harness call: ${msg}
+  Next: ${userAction}`);
     }
     return EXIT.bounded;
   }
   const actionManifestOverride = optionString(options, "actionManifest");
-  const manifest = loadActionManifest(adapter, actionManifestOverride);
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const { manifest } = await resolveActionManifest(adapter, actionManifestOverride, librarySources);
   const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
   const names = getRecipeActionManifestActionNames(manifest);
   const resolution = resolveActionName(shortName, names);
   if (resolution.status === "unknown") {
-    const message = `\u2717 call: unknown action "${shortName}" for the ${adapter} adapter.
-  See the vocabulary: mm-harness actions --adapter ${adapter} --json`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_UNKNOWN", message } }, null, 2));
-    else console.error(message);
+    const message = `unknown action "${shortName}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter} --json`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
+    else console.error(`\u2717 call: ${message}
+  Next: ${userAction}`);
     return EXIT.usage;
   }
   if (resolution.status === "ambiguous") {
-    const message = `\u2717 call: "${shortName}" is ambiguous: ${resolution.candidates.join(", ")} \u2014 use the full name.`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_AMBIGUOUS", message, candidates: resolution.candidates } }, null, 2));
-    else console.error(message);
+    const message = `"${shortName}" is ambiguous: ${resolution.candidates.join(", ")} \u2014 use the full name.`;
+    const userAction = `mm-harness actions --action ${resolution.candidates[0]} --adapter ${adapter} --json`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, error: { code: "ACTION_AMBIGUOUS", message, candidates: resolution.candidates, userAction } }, null, 2));
+    else console.error(`\u2717 call: ${message}
+  Next: ${userAction}`);
     return EXIT.usage;
   }
   const resolvedAction = resolution.resolved;
@@ -113,19 +138,74 @@ async function handleCall(argv) {
   const recipe = synthesizeOneNodeRecipe(resolvedAction, args);
   const validation = await validateRecipeAdapterAware(recipe, manifest);
   if (validation.status === "invalid") {
-    const message = `\u2717 call ${resolvedAction}: recipe validation failed`;
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, resolvedAction, args, findings: validation.findings, error: { code: "RECIPE_VALIDATION_FAILED", message } }, null, 2));
+    const message = `call ${resolvedAction}: recipe validation failed`;
+    const userAction = `mm-harness actions --action ${resolvedAction} --adapter ${adapter} --json`;
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, resolvedAction, args: redactCallValue(args), findings: validation.findings, error: { code: "RECIPE_VALIDATION_FAILED", message, userAction } }, null, 2));
     else {
-      console.error(message);
+      console.error(`\u2717 ${message}`);
       for (const finding of validation.findings) console.error(`  ${finding.code} ${finding.path} \u2014 ${finding.message}`);
+      console.error(`  Next: ${userAction}`);
+    }
+    return EXIT.validation;
+  }
+  const artifactsDir = optionString(options, "artifactsDir") ?? defaultCallArtifactsDir(target, resolvedAction, args);
+  const requestedRuntimeOptions = runtimeOptionsFromCli(options);
+  const callRuntimeOptions = {
+    ...requestedRuntimeOptions,
+    ...librarySources ? { librarySources } : {},
+    autoHud: false,
+    stdoutIsMachineContract: json,
+    source: requestedRuntimeOptions.source ?? {
+      kind: "operator",
+      trust: "trusted",
+      name: "mm-harness call"
+    }
+  };
+  let preflightedExecution;
+  try {
+    preflightedExecution = await preflightRecipe(
+      adapter,
+      recipe,
+      artifactsDir,
+      target,
+      actionManifestOverride,
+      callRuntimeOptions
+    );
+  } catch (error) {
+    const trustFailure = recipeTrustFailure(error);
+    if (!trustFailure) throw error;
+    const planDigest = trustFailure.details?.recipeDigest;
+    if (planDigest) {
+      trustFailure.userAction = `review the plan, then rerun this call with --artifacts-dir ${shellQuote(artifactsDir)} --approve-plan ${shellQuote(planDigest)}; managed callers must keep the same artifact directory and execution environment, then set FARMSLOT_RECIPE_APPROVE_PLAN=${shellQuote(planDigest)}`;
+    }
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "call",
+        status: "fail",
+        error: trustFailure,
+        exitCode: EXIT.validation
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness call: ${trustFailure.message}`);
+      const blocked = trustFailure.details?.blocked;
+      if (blocked?.length) {
+        console.error("  Restricted plan nodes:");
+        for (const node of blocked.slice(0, 10)) {
+          const implementation = node.implementation?.digest ? ` implementation=${node.implementation.kind ?? "custom"}@${node.implementation.digest}` : "";
+          console.error(
+            `  - ${node.nodeId}: ${node.action} [${node.capabilities.join(", ")}] source=${node.source}${implementation}`
+          );
+        }
+        if (blocked.length > 10) console.error(`  - \u2026 ${blocked.length - 10} more (use --json)`);
+      }
+      console.error(`  Next: ${trustFailure.userAction}`);
     }
     return EXIT.validation;
   }
   const lock = acquireCheckoutLock(target, "call");
   if ("message" in lock) {
-    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", status: "fail", recoverable: false, error: { code: "SANDBOX_BUSY", message: lock.message } }, null, 2));
-    else console.error(`\u2717 mm-harness call: ${lock.message}`);
-    return EXIT.bounded;
+    return checkoutBusyOut(json, "call", lock.message, lock.path);
   }
   try {
     const prepared = await prepareHeal(adapter, target, options, json, {
@@ -133,19 +213,20 @@ async function handleCall(argv) {
     });
     if (typeof prepared === "number") return prepared;
     const { state, heal } = prepared;
-    const scratch = await mkdtemp(path.join(os.tmpdir(), "mm-harness-call-"));
-    const recipeFile = path.join(scratch, "call.recipe.json");
-    fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}
-`);
-    const artifactsDir = optionString(options, "artifactsDir") ?? path.join(scratch, "artifacts");
-    const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
-    const callRuntimeOptions = {
-      ...runtimeOptionsFromCli(options),
-      ...librarySources ? { librarySources } : {},
-      stdoutIsMachineContract: json
-    };
     const { result, violation } = await executeWithHealBounds(
-      () => runRecipe(adapter, recipeFile, artifactsDir, target, actionManifestOverride, callRuntimeOptions),
+      () => {
+        const execution = preflightedExecution;
+        preflightedExecution = void 0;
+        return runRecipe(
+          adapter,
+          recipe,
+          artifactsDir,
+          target,
+          actionManifestOverride,
+          callRuntimeOptions,
+          execution
+        );
+      },
       adapter,
       target,
       heal,
@@ -154,6 +235,9 @@ async function handleCall(argv) {
     );
     if (violation !== null) return emitHealViolation(json, "call", result, violation, state, adapter);
     const callOutput = readCallOutput(result.tracePath);
+    const safeArgs = redactCallValue(args);
+    const safeCallOutput = redactCallValue(callOutput);
+    const failureUserAction = `mm-harness last --target ${shellQuote(target)} --json`;
     if (json) {
       console.log(
         JSON.stringify(
@@ -163,30 +247,41 @@ async function handleCall(argv) {
             adapter,
             action: shortName,
             resolvedAction,
-            args,
+            args: safeArgs,
             status: result.status,
             summaryPath: result.summaryPath,
             tracePath: result.tracePath,
             artifactManifestPath: result.artifactManifestPath,
-            ...callOutput !== void 0 ? { output: callOutput } : {},
+            ...result.diagnosticsPath ? { diagnosticsPath: result.diagnosticsPath } : {},
+            ...result.sideFindings ? { sideFindings: result.sideFindings } : {},
+            ...callOutput !== void 0 ? { output: safeCallOutput } : {},
             recovered: state.recovered,
             mutations: state.mutations,
-            exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime
+            exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime,
+            ...result.status === "fail" ? { error: { code: "ACTION_EXECUTION_FAILED", message: `${resolvedAction} failed; inspect the persisted result and evidence paths`, userAction: failureUserAction } } : {}
           },
           null,
           2
         )
       );
     } else {
-      const rendered = callOutput !== void 0 ? `
-Result:
-${formatCallOutput(callOutput)}` : "";
+      const renderedInputs = Object.keys(args).length > 0 ? formatCallOutput(safeArgs) : "";
       const out = (style, text) => color(style, text, { stream: process.stdout });
+      const diagnostics = formatRunDiagnosticsForHuman(
+        readRunDiagnosticsDocument(result.diagnosticsPath),
+        adapter
+      );
+      const renderedDiagnostics = `${out("label", "Diagnostics:")}
+${diagnostics.map((line) => `  ${line}`).join("\n")}
+`;
       console.log(
-        `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${rendered ? `
+        `${out("label", "call")} ${out("cmd", resolvedAction)}: ${out(result.status === "pass" ? "ok" : "err", result.status)}${renderedInputs ? `
+${out("label", "Inputs:")}
+${renderedInputs}` : ""}${callOutput !== void 0 ? `
 ${out("label", "Result:")}
-${formatCallOutput(callOutput)}` : ""}
-${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
+${formatCallOutput(safeCallOutput)}` : ""}
+` + renderedDiagnostics + `${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}` + (result.status === "fail" ? `
+  Next: ${failureUserAction}` : "")
       );
     }
     return result.status === "pass" ? EXIT.ok : EXIT.runtime;
@@ -194,6 +289,11 @@ ${out("label", "Artifacts:")} ${out("path", result.artifactManifestPath)}`
     lock.release();
   }
 }
+function defaultCallArtifactsDir(target, action, args) {
+  const actionStem = action.replace(/[^a-zA-Z0-9._-]/gu, "_");
+  const digest = createHash("sha256").update(JSON.stringify({ action, args })).digest("hex").slice(0, 12);
+  return path.join(target, "temp", "recipe", "calls", `${actionStem}-${digest}`);
+}
 function readCallOutput(tracePath) {
   try {
     const trace = JSON.parse(fs.readFileSync(tracePath, "utf8"));
@@ -209,20 +309,32 @@ function formatCallOutput(value) {
   if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
   return JSON.stringify(value, null, 2);
 }
+function redactCallValue(value, key = "") {
+  if (/(?:password|secret|mnemonic|seed|srp|vault|private[_-]?key)/iu.test(key)) return "<redacted>";
+  if (Array.isArray(value)) return value.map((entry) => redactCallValue(entry));
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.entries(value).map(([entryKey, entry]) => [entryKey, redactCallValue(entry, entryKey)]));
+  }
+  return value;
+}
 async function handleCallHelp(argv, genericHelp) {
   const { action: shortName, rest } = parseCallArgs(argv.filter((arg) => arg !== "--help" && arg !== "-h"));
   const { options } = parseArgs(rest, "call");
   let adapter;
   let manifest;
+  let actionSources = /* @__PURE__ */ new Map();
   try {
     ({ adapter } = resolveAdapter(options));
-    manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+    const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+    const resolution = await resolveActionManifest(adapter, optionString(options, "actionManifest"), librarySources);
+    manifest = resolution.manifest;
+    actionSources = resolution.actionSources;
   } catch {
     process.stdout.write(`${genericHelp}
 `);
     return EXIT.ok;
   }
-  const matches = shortName ? fuzzyResolveActions(describeManifestActions(manifest), shortName) : [];
+  const matches = shortName ? fuzzyResolveActions(describeManifestActions(manifest, actionSources), shortName) : [];
   if (matches.length === 0) {
     process.stdout.write(`${genericHelp}
 `);
@@ -250,7 +362,8 @@ function renderCallActionHelp(entry) {
   );
   const lines = [`mm-harness call ${entry.name} [key=value ...] [--arg k=v ...] [flags]`, ""];
   if (entry.description) lines.push(`  ${entry.description}`, "");
-  const names = Object.keys(properties).sort();
+  lines.push(`  Source: ${entry.source}${entry.sourceManifest ? ` (${entry.sourceManifest})` : ""}`, "");
+  const names = Object.keys(properties).filter((name) => name !== "action" && name !== "next").sort();
   if (names.length === 0) {
     lines.push("  Fields: (none)");
   } else {
@@ -320,7 +433,7 @@ function parseCallValue(value) {
     const number = Number(value);
     if (Number.isFinite(number)) return number;
   }
-  if (value.startsWith("[") && value.endsWith("]") || value.startsWith("{") && value.endsWith("}")) {
+  if (value.startsWith("[") && value.endsWith("]") || value.startsWith("{") && value.endsWith("}") || value.startsWith('"') && value.endsWith('"')) {
     try {
       return JSON.parse(value);
     } catch {
@@ -340,6 +453,7 @@ function isForwardedOptionValue(argv, index) {
 }
 const VALUE_TAKING_CALL_FLAGS = /* @__PURE__ */ new Set([
   "action-manifest",
+  "approve-plan",
   "adapter",
   "artifacts-dir",
   "cdp-port",
@@ -350,6 +464,10 @@ const VALUE_TAKING_CALL_FLAGS = /* @__PURE__ */ new Set([
   "platform",
   "project-root",
   "slot",
+  "source-digest",
+  "source-kind",
+  "source-name",
+  "source-trust",
   "target",
   "validation-runtime-dir",
   "watcher-port"
@@ -373,6 +491,8 @@ function pickCallExampleAction(names) {
   return names[0] ?? "command";
 }
 export {
+  defaultCallArtifactsDir,
   handleCall,
-  handleCallHelp
+  handleCallHelp,
+  redactCallValue
 };

package/dist/commands/check.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { detectAdapter } from "../harness.js";
 import { EXIT, usageOut } from "./shared.js";
-import { optionFlag, optionString, parseArgs } from "./parse-args.js";
+import { optionFlag, optionString, parseArgs, shellQuote } from "./parse-args.js";
 const USAGE = "mm-harness check diff [--fix] [--target <repo>] [--adapter mobile|extension|core] [--base <ref>] [--profile fast|full] [--artifacts-dir <dir>] [--json]";
 const JS_TS_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$/u;
 const FORMAT_EXT_RE = /\.(?:c|m)?jsx?$|\.tsx?$|\.json$|\.md$|\.css$|\.scss$|\.ya?ml$/u;
@@ -111,6 +111,7 @@ async function handleCheck(argv) {
   const status = [...fixes, ...checks].some((check) => check.status === "fail") ? "fail" : "pass";
   const exitCode = status === "pass" ? EXIT.ok : EXIT.validation;
   const guidance = policyFailed ? ["Remove the newly added eslint-disable directive(s). Fix the underlying violation with existing named styles, project tokens, or another established source pattern; then rerun mm-harness check diff [--fix]. Other checks were skipped until this policy failure is removed."] : checks.some((check) => check.id === "eslint" && check.status === "fail") ? ["Fix the reported violations in changed source using existing project patterns and tokens; do not suppress rules, hide violations behind indirection, weaken configuration, or bypass check diff. Then rerun mm-harness check diff [--fix]."] : [];
+  const failureUserAction = guidance[0] ?? `inspect ${path.join(artifactsDir, "validation-summary.json")}, fix the failing check, then retry: mm-harness check diff --target ${shellQuote(target)} --base ${shellQuote(baseRef)} --profile ${profile} --json`;
   const summary = {
     schemaVersion: 1,
     command: "check",
@@ -129,6 +130,7 @@ async function handleCheck(argv) {
     fixes,
     checks,
     guidance,
+    ...status === "fail" ? { error: { code: "CHECK_DIFF_FAILED", message: "one or more bounded checks failed", userAction: failureUserAction } } : {},
     artifacts: {
       dir: artifactsDir,
       summaryJson: path.join(artifactsDir, "validation-summary.json"),
@@ -518,10 +520,14 @@ function renderHuman(summary) {
     if (check.status === "fail" && check.logPath) console.log(`    log: ${check.logPath}`);
   }
   for (const item of summary.guidance) console.log(`  Next: ${item}`);
+  if (summary.guidance.length === 0 && summary.status === "fail" && summary.error?.userAction) {
+    console.log(`  Next: ${summary.error.userAction}`);
+  }
   console.log(`Artifacts: ${summary.artifacts.summaryJson}`);
 }
 function failEnvelope(input) {
   const exitCode = EXIT.usage;
+  const userAction = USAGE;
   const body = {
     schemaVersion: 1,
     command: "check",
@@ -534,11 +540,11 @@ function failEnvelope(input) {
     baseRef: input.baseRef,
     baseSource: "unknown",
     artifacts: { dir: input.artifactsDir },
-    error: { code: input.code, message: input.message }
+    error: { code: input.code, message: input.message, userAction }
   };
   if (input.json) console.log(JSON.stringify(body, null, 2));
   else console.error(`\u2717 check diff: ${input.message}
-  Next: ${USAGE}`);
+  Next: ${userAction}`);
   return exitCode;
 }
 export {

package/dist/commands/completion-candidates.js

@@ -1,4 +1,4 @@
-import { loadActionManifest } from "../manifest.js";
+import { resolveActionManifest } from "../manifest.js";
 import {
   invalidateCompletionCache,
   readFreshCandidates,
@@ -13,13 +13,13 @@ import {
   resolveAdapter,
   targetPath
 } from "./parse-args.js";
-import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+import { listRunnableRecipes, resolveMetaMaskLibrarySources } from "./run-engine.js";
 async function handleCompletionCandidates(argv) {
   const kind = argv[0];
   const { options } = parseArgs(argv.slice(1), "completion-candidates");
   const json = optionFlag(options, "json");
-  if (kind !== "actions" && kind !== "flows") {
-    console.error("completion-candidates requires <actions|flows>.");
+  if (kind !== "actions" && kind !== "flows" && kind !== "recipes") {
+    console.error("completion-candidates requires <actions|flows|recipes>.");
     return EXIT.usage;
   }
   const target = targetPath(options);
@@ -27,17 +27,15 @@ async function handleCompletionCandidates(argv) {
   let candidates;
   if (kind === "actions") {
     adapter = resolveAdapter(options).adapter;
-    candidates = readFreshCandidates(target, "actions");
-    if (!candidates) {
-      const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
-      const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-      candidates = getRecipeActionManifestActionNames(manifest);
-      writeCompletionCandidates(target, "actions", candidates);
-    }
-  } else {
+    const sources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+    const { manifest } = await resolveActionManifest(adapter, optionString(options, "actionManifest"), sources);
+    const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
+    candidates = getRecipeActionManifestActionNames(manifest);
+    writeCompletionCandidates(target, "actions", candidates);
+  } else if (kind === "flows") {
     candidates = readFreshCandidates(target, "flows");
     if (!candidates) {
-      const sources = await resolveMetaMaskLibrarySources(void 0).catch(() => void 0);
+      const sources = await resolveMetaMaskLibrarySources(optionString(options, "library")).catch(() => void 0);
       if (!sources) {
         candidates = [];
       } else {
@@ -47,6 +45,15 @@ async function handleCompletionCandidates(argv) {
         writeCompletionCandidates(target, "flows", candidates);
       }
     }
+  } else {
+    adapter = resolveAdapter(options).adapter;
+    const cacheKey = `recipes:${adapter}`;
+    candidates = readFreshCandidates(target, cacheKey);
+    if (!candidates) {
+      const sources = await resolveMetaMaskLibrarySources(optionString(options, "library")).catch(() => void 0);
+      candidates = sources ? listRunnableRecipes(adapter, sources).map((recipe) => recipe.name) : [];
+      writeCompletionCandidates(target, cacheKey, candidates);
+    }
   }
   if (json) console.log(JSON.stringify({ schemaVersion: 1, kind, adapter, candidates }, null, 2));
   else for (const candidate of candidates) console.log(candidate);

package/dist/commands/device-target.js

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { listConnectedDevices } from "../devices.js";
-import { optionString } from "./parse-args.js";
+import { optionString, shellQuoteArg, targetPath } from "./parse-args.js";
 function normalizeDeviceName(value) {
   return value.replace(/_/gu, " ").trim();
 }
@@ -75,6 +75,12 @@ function configuredPinForPlatform(platform) {
 function oppositePlatform(platform) {
   return platform === "ios" ? "android" : "ios";
 }
+function deviceProbe(options) {
+  return `mm-harness status --target ${shellQuoteArg(targetPath(options))} --all-devices --json`;
+}
+function deviceRecovery(options, rerun) {
+  return rerun ? `${deviceProbe(options)}; then retry: ${rerun}` : deviceProbe(options);
+}
 function applyDeviceTargeting(command, adapter, options, opts) {
   const device = optionString(options, "device");
   const platformPreference = mobilePlatformPreference(options);
@@ -84,7 +90,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
         ok: false,
         code: "DEVICE_WRONG_ADAPTER",
         message: `--device is only supported on the mobile adapter (the ${adapter} adapter has no device to target).
-  Drop --device, or run this ${command} inside a metamask-mobile checkout.`
+  Drop --device, or run this ${command} inside a metamask-mobile checkout.`,
+        userAction: `remove --device; ${adapter} has no device target`
       };
     }
     return { ok: true };
@@ -97,7 +104,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
           ok: false,
           code: "DEVICE_PLATFORM_CONFLICT",
           message: `--device ${device} resolves to ${matched.platform}, but --platform ${platformPreference} was requested.
-  To use this device intentionally, drop --platform ${platformPreference} or choose a ${platformPreference} device.`
+  To use this device intentionally, drop --platform ${platformPreference} or choose a ${platformPreference} device.`,
+          userAction: deviceRecovery(options, opts.rerun)
         };
       }
       if (matched.platform === "android") setAndroidDeviceEnv(matched.id, matched.name);
@@ -126,7 +134,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
         ok: false,
         code: "DEVICE_NAME_AMBIGUOUS",
         message: `device name '${device}' is ambiguous; use the id:
-` + byName.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n")
+` + byName.map((d) => `    - ${d.id}${d.name ? ` (${d.name})` : ""} [${d.state}] ${d.platform}`).join("\n"),
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     return {
@@ -134,7 +143,8 @@ function applyDeviceTargeting(command, adapter, options, opts) {
       code: "DEVICE_NOT_FOUND",
       message: `--device ${device} did not match any connected device.
 ` + (connected2.length > 0 ? `  Connected devices:
-${formatConnectedDevices(connected2)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
+${formatConnectedDevices(connected2)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`),
+      userAction: deviceRecovery(options, opts.rerun)
     };
   }
   const connected = listConnectedDevices();
@@ -158,7 +168,8 @@ ${formatConnectedDevices(connected2)}` : `  No devices are currently connected (
         message: `--platform ${platformPreference} conflicts with the current slot-selected device.
   Selected devices:
 ${formatConnectedDevices(selectedTargetable2)}
-  To use a different connected device intentionally, pass --device <id>.`
+  To use a different connected device intentionally, pass --device <id>.`,
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     if (!configuredPin && oppositePin) {
@@ -167,7 +178,8 @@ ${formatConnectedDevices(selectedTargetable2)}
         code: "DEVICE_PLATFORM_CONFLICT",
         message: `--platform ${platformPreference} conflicts with the configured slot target.
   Configured ${oppositePlatform(platformPreference)} target: ${oppositePin}
-  To use a different connected device intentionally, pass --device <id>.`
+  To use a different connected device intentionally, pass --device <id>.`,
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     if (configuredPin) {
@@ -178,8 +190,8 @@ ${formatConnectedDevices(selectedTargetable2)}
         message: `--platform ${platformPreference} matches the configured slot target, but that target is not ready.
   Configured target: ${configuredPin}
   Connected devices:
-${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}
-  Next: run mm-harness launch ${platformPreference}, or pass --device <id> to intentionally use another target.`
+${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}`,
+        userAction: `mm-harness launch ${platformPreference} --target ${shellQuoteArg(targetPath(options))}`
       };
     }
     if (platformTargetable.length === 1) {
@@ -195,7 +207,8 @@ ${connected.length > 0 ? formatConnectedDevices(connected) : "    - none"}
         code: "DEVICE_PLATFORM_NOT_FOUND",
         message: `--platform ${platformPreference} did not match any ready connected device.
 ` + (connected.length > 0 ? `  Connected devices:
-${formatConnectedDevices(connected)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
+${formatConnectedDevices(connected)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`),
+        userAction: deviceRecovery(options, opts.rerun)
       };
     }
     return {
@@ -205,7 +218,8 @@ ${formatConnectedDevices(connected)}` : `  No devices are currently connected (a
   Connected devices:
 ${formatConnectedDevices(connected)}
   Add --device <id> to disambiguate, e.g.:${platformTargetable.map((d) => `
-    --device ${d.id}`).join("")}`
+    --device ${d.id}`).join("")}`,
+      userAction: deviceRecovery(options, opts.rerun)
     };
   }
   const selectedTargetable = targetable.filter(deviceSelected);
@@ -224,7 +238,8 @@ ${formatConnectedDevices(connected)}
   Connected devices:
 ${formatConnectedDevices(connected)}
 ` + (selectedTargetable.length > 1 ? `  The current slot context selects more than one target; fix the slot device pins or add --device <id>.` : `  Add --device <id> to disambiguate, e.g.:${targetable.map((d) => `
-    --device ${d.id}`).join("")}`)
+    --device ${d.id}`).join("")}`),
+      userAction: deviceRecovery(options, opts.rerun)
     };
   }
   return { ok: true };