@deeeed/metamask-harness 0.17.5 → 0.18.0

package/dist/commands/list-executables.js

@@ -1,48 +1,170 @@
-import { loadActionManifest } from "../manifest.js";
-import { importRecipeHarness, importRecipeProtocol } from "../paths.js";
+import path from "node:path";
+import { resolveActionManifest } from "../manifest.js";
+import { importRecipeProtocol } from "../paths.js";
+import { color } from "../cli-color.js";
 import { EXIT } from "./shared.js";
-import { optionFlag, optionString, resolveAdapter } from "./parse-args.js";
-import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+import { optionFlag, optionString, resolveAdapter, shellQuoteArg } from "./parse-args.js";
+import { describeManifestActions, renderHumanActionCatalog } from "./manifest.js";
+import {
+  describeRunnableRecipe,
+  listRunnableRecipes,
+  resolveMetaMaskLibrarySources
+} from "./run-engine.js";
 const finalSegment = (name) => name.split(".").pop() ?? name;
-async function listFlowIds() {
-  try {
-    const sources = await resolveMetaMaskLibrarySources(void 0);
-    if (!sources || sources.length === 0) return [];
-    const harness = await importRecipeHarness();
-    const resolution = await harness.loadRecipeLibraries(sources);
-    return [...resolution.flows.keys()].sort();
-  } catch {
-    return [];
-  }
+function catalogDescription(description) {
+  if (!description) return "";
+  const firstSentence = description.match(/^.*?[.!?](?:\s|$)/u)?.[0]?.trim() ?? description;
+  return firstSentence.length <= 180 ? firstSentence : `${firstSentence.slice(0, 177).trimEnd()}\u2026`;
 }
 async function handleListExecutables(command, options) {
   const json = optionFlag(options, "json");
   const { adapter } = resolveAdapter(options);
-  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  if (command === "run") {
+    const recipes = listRunnableRecipes(adapter, librarySources);
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, recipes }, null, 2));
+      return EXIT.ok;
+    }
+    const out = (style, text) => color(style, text, { stream: process.stdout });
+    console.log(out("bold", `runnable recipes (${adapter})`));
+    console.log(out("comment", "Inspect: mm-harness run <recipe> --describe"));
+    for (const recipe of recipes) {
+      const shadowed = recipe.shadows.length > 0 ? ` shadows=${recipe.shadows.join(",")}` : "";
+      const summary = catalogDescription(recipe.description);
+      const description = summary ? ` \u2014 ${summary}` : "";
+      console.log(`  ${out("cmd", recipe.name)} ${out("dim", `[${recipe.source}]${shadowed}`)}${description}`);
+    }
+    return EXIT.ok;
+  }
+  const { manifest, actionSources } = await resolveActionManifest(
+    adapter,
+    optionString(options, "actionManifest"),
+    librarySources
+  );
   const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
-  const names = getRecipeActionManifestActionNames(manifest).slice().sort();
+  const protocolNames = new Set(getRecipeActionManifestActionNames(manifest));
+  const described = describeManifestActions(manifest, actionSources).filter((entry) => protocolNames.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
   const shortCounts = /* @__PURE__ */ new Map();
-  for (const name of names) shortCounts.set(finalSegment(name), (shortCounts.get(finalSegment(name)) ?? 0) + 1);
-  const actions = names.map((name) => {
-    const short = finalSegment(name);
-    return { name, short: shortCounts.get(short) === 1 ? short : null };
+  for (const entry of described) {
+    const short = finalSegment(entry.name);
+    shortCounts.set(short, (shortCounts.get(short) ?? 0) + 1);
+  }
+  const shortByName = /* @__PURE__ */ new Map();
+  const actions = described.map((entry) => {
+    const short = finalSegment(entry.name);
+    const usableShort = shortCounts.get(short) === 1 ? short : null;
+    shortByName.set(entry.name, usableShort);
+    return {
+      name: entry.name,
+      short: usableShort,
+      description: entry.description,
+      fields: entry.fields,
+      source: entry.source,
+      sourceTier: entry.sourceTier,
+      sourceManifest: entry.sourceManifest,
+      shadows: entry.shadows
+    };
   });
-  const flows = await listFlowIds();
   if (json) {
-    console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, actions, flows }, null, 2));
+    console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, actions }, null, 2));
     return EXIT.ok;
   }
-  console.log(`invocable for ${adapter}:`);
-  console.log(`  actions (mm-harness call <name> \u2014 short or full):`);
-  for (const entry of actions) {
-    console.log(entry.short ? `    ${entry.short}  (${entry.name})` : `    ${entry.name}  (full name only \u2014 ambiguous short)`);
+  console.log(renderHumanActionCatalog(described, {
+    title: `invocable actions (${adapter})`,
+    guidance: "Use: mm-harness call <name>  \xB7  short names shown first where unambiguous",
+    displayName: (entry) => {
+      const short = shortByName.get(entry.name);
+      return short ? `${short} (${entry.name})` : `${entry.name} (full name only \u2014 ambiguous short)`;
+    }
+  }));
+  return EXIT.ok;
+}
+async function handleDescribeRecipe(recipeArg, options) {
+  const json = optionFlag(options, "json");
+  const { adapter } = resolveAdapter(options);
+  const libraryEntry = optionString(options, "library");
+  const librarySources = await resolveMetaMaskLibrarySources(libraryEntry);
+  const result = describeRunnableRecipe(recipeArg, adapter, librarySources);
+  const targetEntry = optionString(options, "target") ?? optionString(options, "projectRoot");
+  const replayTarget = targetEntry ? path.resolve(targetEntry) : void 0;
+  const contextFlags = [
+    `--adapter ${adapter}`,
+    ...libraryEntry ? [`--library ${shellQuoteArg(libraryEntry)}`] : [],
+    ...replayTarget ? [`--target ${shellQuoteArg(replayTarget)}`] : []
+  ].join(" ");
+  const discoveryCommand = `mm-harness run --list ${contextFlags}`;
+  if ("notFound" in result || "unreadable" in result) {
+    const code = "notFound" in result ? "RECIPE_NOT_FOUND" : "RECIPE_UNPARSEABLE";
+    const message = "notFound" in result ? result.notFound : result.unreadable;
+    const userAction = "notFound" in result ? discoveryCommand : `fix ${shellQuoteArg(recipeArg)}, then retry: mm-harness run ${shellQuoteArg(recipeArg)} --describe ${contextFlags}`;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "run",
+        action: "describe",
+        status: "fail",
+        error: { code, message, userAction },
+        exitCode: EXIT.usage
+      }, null, 2));
+    } else {
+      console.error(`\u2717 run: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
   }
-  if (flows.length > 0) {
-    console.log(`  flows (mm-harness run <flow>):`);
-    for (const flow of flows) console.log(`    ${flow}`);
+  const recipe = result.recipe;
+  const nextCommand = `mm-harness run ${shellQuoteArg(recipeArg)} --plan ${contextFlags}`;
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "run",
+      action: "describe",
+      status: "pass",
+      recipe,
+      nextCommand
+    }, null, 2));
+    return EXIT.ok;
+  }
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  console.log(out("bold", `recipe ${recipe.name}`));
+  if (recipe.title) console.log(`  ${out("label", "title:")} ${recipe.title}`);
+  if (recipe.description) console.log(`  ${out("label", "description:")} ${recipe.description}`);
+  console.log(`  ${out("label", "adapter:")} ${recipe.adapter}`);
+  console.log(`  ${out("label", "source:")} ${recipe.source} \xB7 ${recipe.file}`);
+  console.log(`  ${out("label", "path:")} ${out("path", recipe.path)}`);
+  const inputEntries = Object.entries(recipe.inputs);
+  if (inputEntries.length === 0) {
+    console.log(`  ${out("label", "declared inputs:")} none`);
+  } else {
+    console.log(`  ${out("label", "input overrides:")} unavailable \u2014 declared inputs are recipe-owned`);
+    console.log(`  ${out("label", `declared inputs (${inputEntries.length})`)}`);
+    for (const [name, declaration] of inputEntries) {
+      console.log(`    ${out("cmd", name)} = ${compactValue(declaration)}`);
+    }
+  }
+  renderComposition("actions", recipe.actions, out);
+  if (!recipe.actionsComplete) {
+    console.log(`  ${out("comment", "Note: actions inside external library flows are not expanded.")}`);
   }
+  renderComposition("flows", recipe.flows, out);
+  console.log(`  ${out("comment", `Next: ${nextCommand}`)}`);
   return EXIT.ok;
 }
+function compactValue(value) {
+  const rendered = JSON.stringify(value);
+  if (rendered === void 0) return String(value);
+  return rendered.length <= 180 ? rendered : `${rendered.slice(0, 177)}\u2026`;
+}
+function renderComposition(label, values, out) {
+  if (values.length === 0) {
+    console.log(`  ${out("label", `${label}:`)} none`);
+    return;
+  }
+  console.log(`  ${out("label", `${label} (${values.length})`)}`);
+  for (const value of values) console.log(`    ${out("cmd", value)}`);
+}
 export {
+  handleDescribeRecipe,
   handleListExecutables
 };

package/dist/commands/logs.js

@@ -19,9 +19,10 @@ async function handleLogs(argv) {
   const logSources = surface.logSources(target);
   const appLogSource = surface.appLogSource(target);
   const sourceLabels = logSources.map((entry) => entry.label);
-  const defaultSource = sourceLabels[0];
+  const appSourceLabel = appLogSource?.label ?? "app";
+  const defaultSource = appLogSource && appSourceLabel !== "app" ? appSourceLabel : sourceLabels[0];
   const source = str(options, "source") ?? defaultSource;
-  const validSources = [...sourceLabels, ...appLogSource ? ["app"] : []];
+  const validSources = [...sourceLabels, ...appLogSource ? [appSourceLabel] : [], ...appLogSource && appSourceLabel !== "app" ? ["app"] : []];
   if (!validSources.includes(source)) {
     return usageOut(json, "logs", `--source must be one of: ${validSources.join(", ")}.`, `mm-harness logs --source ${defaultSource}`);
   }
@@ -32,11 +33,12 @@ async function handleLogs(argv) {
     }
     process.env.RECIPE_LOG_EVENTS = events;
   }
-  const requested = source === "app" ? appLogSource : logSources.find((entry) => entry.label === source);
-  const ordered = source === "app" ? requested ? [requested] : [] : requested ? [requested, ...logSources.filter((entry) => entry !== requested)] : logSources;
+  const isAppSource = source === "app" || source === appSourceLabel;
+  const requested = isAppSource ? appLogSource : logSources.find((entry) => entry.label === source);
+  const ordered = isAppSource ? requested ? [requested] : [] : requested ? [requested] : logSources;
   const logFile = ordered.find((entry) => fs.existsSync(entry.path))?.path;
   if (!logFile) {
-    if (source === "app" && appLogSource) {
+    if (isAppSource && appLogSource) {
       const message = `application console unavailable for this checkout (${path.basename(appLogSource.path)} is absent).`;
       const userAction = surface.hints.launch;
       if (json) {
@@ -55,7 +57,7 @@ async function handleLogs(argv) {
       }
       return EXIT.runtime;
     }
-    const names = source === "app" && appLogSource ? path.basename(appLogSource.path) : logSources.map((entry) => path.basename(entry.path)).join(" / ");
+    const names = isAppSource && appLogSource ? path.basename(appLogSource.path) : logSources.map((entry) => path.basename(entry.path)).join(" / ");
     return usageOut(
       json,
       "logs",

package/dist/commands/manifest.js

@@ -1,59 +1,228 @@
-import { loadActionManifest, validateManifest } from "../manifest.js";
+import { resolveActionManifest } from "../manifest.js";
+import { color } from "../cli-color.js";
 import { EXIT } from "./shared.js";
 import {
-  actionManifestPathOption,
   isRecord,
   optionFlag,
   optionString,
-  resolveAdapter
+  resolveAdapter,
+  shellQuoteArg
 } from "./parse-args.js";
-async function handleManifest({ options }) {
-  const { adapter } = resolveAdapter(options);
-  const actionManifestPath = actionManifestPathOption(options, adapter);
-  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
-  await validateManifest(manifest);
-  if (optionFlag(options, "json")) console.log(JSON.stringify(manifest, null, 2));
-  else console.log(actionManifestPath);
-  return 0;
-}
-async function handleActions({ options }) {
-  const { adapter } = resolveAdapter(options);
-  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
-  await validateManifest(manifest);
+import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+import {
+  officialRecipeActionCapabilities
+} from "@farmslot/protocol";
+import { metaMaskActionExecutionCapabilities } from "../recipe-security.js";
+async function handleActions({ options, positional }) {
+  const { adapter, target } = resolveAdapter(options);
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const { manifest, actionSources } = await resolveActionManifest(
+    adapter,
+    optionString(options, "actionManifest"),
+    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 all = describeManifestActions(manifest);
-  const actions = action ? fuzzyResolveActions(all, action) : all;
+  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);
+  if (categoriesOnly && (action || category)) {
+    const message = "--categories cannot be combined with --action or --category.";
+    const userAction = `mm-harness actions --adapter ${adapter} --categories`;
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, error: { code: "ACTION_FILTER_CONFLICT", message, userAction } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
+  }
+  if (categoriesOnly) {
+    if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, categories }, null, 2));
+    else for (const entry of categories) console.log(`${entry.name} (${entry.count})`);
+    return EXIT.ok;
+  }
+  const categoryActions = category ? all.filter((entry) => entry.category === category) : all;
+  if (category && categoryActions.length === 0) {
+    const message = `no action category matches "${category}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter} --categories`;
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, category, availableCategories: categories, error: { code: "ACTION_CATEGORY_UNKNOWN", message, userAction } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
+  }
+  const actions = action ? fuzzyResolveActions(categoryActions, action) : query ? searchActions(categoryActions, query) : categoryActions;
   if (action && actions.length === 0) {
     const message = `no action matches "${action}" for the ${adapter} adapter.`;
-    const userAction = `mm-harness actions --adapter ${adapter}   # list the vocabulary`;
+    const userAction = `mm-harness actions --adapter ${adapter}`;
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, action, category, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
+  }
+  if (query && actions.length === 0) {
+    const message = `no action matches search "${query}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter} --categories`;
     if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, action, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "actions",
+        adapter,
+        query,
+        category,
+        error: { code: "ACTION_SEARCH_EMPTY", message, userAction }
+      }, null, 2));
     } else {
       console.error(`\u2717 mm-harness actions: ${message}
   Next: ${userAction}`);
     }
     return EXIT.usage;
   }
+  const relatedActions = action && actions.length === 1 ? findRelatedActions(all, actions[0]) : void 0;
   if (json) {
-    console.log(JSON.stringify({ adapter, actions }, null, 2));
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "actions",
+      adapter,
+      ...query ? { query } : {},
+      category,
+      actions,
+      ...relatedActions?.length ? { relatedActions } : {}
+    }, null, 2));
   } else {
-    for (const entry of actions) {
-      const fields = entry.fields.length ? ` fields=${entry.fields.join(",")}` : "";
-      console.log(`${entry.name} (${entry.kind})${fields}${entry.description ? ` \u2014 ${entry.description}` : ""}`);
-    }
+    console.log(renderHumanActionCatalog(actions, {
+      title: `actions (${adapter})`,
+      guidance: "Inspect: mm-harness actions --action <name>  \xB7  Run: mm-harness call <name>"
+    }));
+    const example = action && actions.length === 1 ? renderHumanActionExample(
+      actions[0],
+      adapter,
+      target,
+      process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness"
+    ) : void 0;
+    if (example) console.log(`
+${example}`);
+    if (relatedActions?.length) console.log(`
+${color("label", "Related:", { stream: process.stdout })} ${relatedActions.join(", ")}`);
   }
   return 0;
 }
 function fuzzyResolveActions(entries, query) {
   const exactFull = entries.filter((e) => e.name === query);
   if (exactFull.length > 0) return exactFull;
-  const finalSegment = (name) => name.split(".").pop() ?? name;
-  const exactSegment = entries.filter((e) => finalSegment(e.name) === query);
+  const finalSegment2 = (name) => name.split(".").pop() ?? name;
+  const exactSegment = entries.filter((e) => finalSegment2(e.name) === query);
   if (exactSegment.length > 0) return exactSegment;
-  return entries.filter((e) => finalSegment(e.name).includes(query));
+  return entries.filter((e) => finalSegment2(e.name).includes(query));
+}
+function searchActions(entries, query) {
+  const terms = searchTerms(query);
+  if (terms.length === 0) return [];
+  return entries.map((entry) => {
+    const scores = terms.map((term) => actionSearchScore(entry, term));
+    return { entry, scores, score: scores.reduce((total, value) => total + value, 0) };
+  }).filter(({ score, scores }) => score > 0 && scores.every((value) => value > 0)).sort((left, right) => right.score - left.score || left.entry.name.localeCompare(right.entry.name)).map(({ entry }) => entry);
+}
+function findRelatedActions(entries, selected, limit = 5) {
+  const selectedNameTerms = searchTerms(finalSegment(selected.name).replaceAll("_", " "));
+  return entries.filter((entry) => entry.name !== selected.name).map((entry) => {
+    const nameTerms = new Set(searchTerms(finalSegment(entry.name).replaceAll("_", " ")));
+    const sharedScore = selectedNameTerms.filter((term) => nameTerms.has(term)).reduce((score2, term) => score2 + (GENERIC_OPERATION_TERMS.has(term) ? 5 : 30), 0);
+    const score = (entry.category === selected.category ? 100 : 0) + sharedScore;
+    return { name: entry.name, score };
+  }).filter(({ score }) => score > 0).sort((left, right) => right.score - left.score || left.name.localeCompare(right.name)).slice(0, limit).map(({ name }) => name);
+}
+const GENERIC_OPERATION_TERMS = /* @__PURE__ */ new Set(["assert", "call", "close", "ensure", "place", "read", "start", "teardown"]);
+function renderHumanActionCatalog(actions, options) {
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of actions) {
+    const group = actionDomainGroup(entry);
+    groups.set(group, [...groups.get(group) ?? [], entry]);
+  }
+  const lines = [out("bold", options.title), out("comment", options.guidance)];
+  for (const [group, entries] of groups) {
+    lines.push("", `${out(group === "official" ? "label" : "accent", group)} ${out("dim", `(${entries.length})`)}`);
+    for (const entry of entries) {
+      const fieldNames = humanFieldNames(entry);
+      const fields = fieldNames.length ? ` ${out("dim", `fields=${fieldNames.join(",")}`)}` : "";
+      const description = entry.description ? ` ${out("comment", `\u2014 ${entry.description}`)}` : "";
+      const source = ` ${out("dim", `[${entry.source}]`)}`;
+      const risk = entry.capabilities.length ? ` ${out("dim", `risk=${entry.capabilities.join(",")}`)}` : "";
+      lines.push(`  ${out("cmd", options.displayName?.(entry) ?? entry.name)}${source}${fields}${risk}${description}`);
+    }
+  }
+  return lines.join("\n");
+}
+function renderHumanActionExample(entry, adapter, target, executable) {
+  const node = authoredExampleNode(entry.examples);
+  if (!node) return void 0;
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const args = entry.fields.flatMap(
+    (field) => Object.hasOwn(node, field) ? [shellQuoteArg(`${field}=${actionCallValue(node[field])}`)] : []
+  );
+  const command = [
+    shellQuoteArg(executable),
+    "call",
+    shellQuoteArg(entry.name),
+    ...args,
+    "--adapter",
+    adapter,
+    "--target",
+    shellQuoteArg(target)
+  ].join(" ");
+  const lines = [
+    out("label", "Example call:"),
+    `  ${out("cmd", command)}`,
+    out("label", "Recipe node:"),
+    ...JSON.stringify(node, null, 2).split("\n").map((line) => `  ${line}`)
+  ];
+  return lines.join("\n");
+}
+function authoredExampleNode(examples) {
+  if (!Array.isArray(examples)) return void 0;
+  for (const example of examples) {
+    if (isRecord(example) && isRecord(example.node)) return example.node;
+  }
+  return void 0;
+}
+function actionCallValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
 }
-function describeManifestActions(manifest) {
+function humanFieldNames(entry) {
+  const schema = isRecord(entry.schema) ? entry.schema : void 0;
+  const properties = schema && isRecord(schema.properties) ? schema.properties : void 0;
+  if (!properties) return entry.fields;
+  return entry.fields.map((field) => {
+    const property = properties[field];
+    if (!isRecord(property) || !Array.isArray(property.enum)) return field;
+    const values = property.enum.filter((value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean");
+    return values.length > 0 ? `${field}=${values.join("|")}` : field;
+  });
+}
+function actionDomainGroup(entry) {
+  if (entry.kind === "official") return "official";
+  const match = /^metamask[.]([^.]+)[.]/u.exec(entry.name);
+  return match ? `metamask \xB7 ${match[1]}` : "custom";
+}
+function summarizeActionCategories(actions) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const action of actions) counts.set(action.category, (counts.get(action.category) ?? 0) + 1);
+  return [...counts.entries()].map(([name, count]) => ({ name, count })).sort((left, right) => left.name.localeCompare(right.name));
+}
+function describeManifestActions(manifest, actionSources = /* @__PURE__ */ new Map()) {
   const manifestRecord = isRecord(manifest) ? manifest : {};
   const metadata = isRecord(manifestRecord.action_metadata) ? manifestRecord.action_metadata : {};
   const official = Array.isArray(manifestRecord.supported_official_actions) ? manifestRecord.supported_official_actions.filter((value) => typeof value === "string") : [];
@@ -68,27 +237,93 @@ function describeManifestActions(manifest) {
     return [];
   }) : [];
   return [
-    ...official.map((name) => describeManifestAction(name, "official", metadata[name])),
-    ...custom.map((entry) => describeManifestAction(entry.name, "custom", entry.metadata))
+    ...official.map((name) => describeManifestAction(name, "official", metadata[name], actionSources.get(name))),
+    ...custom.map((entry) => describeManifestAction(entry.name, "custom", entry.metadata, actionSources.get(entry.name)))
   ];
 }
-function describeManifestAction(name, kind, metadata) {
+function describeManifestAction(name, kind, metadata, source) {
   const record = isRecord(metadata) ? metadata : {};
   const schema = record.schema;
   const schemaRecord = isRecord(schema) ? schema : {};
-  const properties = isRecord(schemaRecord.properties) ? Object.keys(schemaRecord.properties).sort() : [];
+  const properties = isRecord(schemaRecord.properties) ? Object.keys(schemaRecord.properties).filter((field) => field !== "action" && field !== "next").sort() : [];
   return {
     name,
     kind,
+    category: actionCategory(name, record.category),
     description: typeof record.description === "string" ? record.description : "",
     fields: properties,
     schema,
-    examples: record.examples
+    examples: record.examples,
+    source: source?.name ?? (kind === "official" ? "official" : "metamask"),
+    sourceTier: source?.tier ?? (kind === "official" ? "official" : "canonical"),
+    sourceManifest: source?.manifestPath ?? "",
+    shadows: source?.shadows ?? [],
+    capabilities: [.../* @__PURE__ */ new Set([
+      ...Array.isArray(record.execution_capabilities) ? record.execution_capabilities.filter(
+        (value) => typeof value === "string"
+      ) : [],
+      ...kind === "official" ? officialRecipeActionCapabilities(name) : metaMaskActionExecutionCapabilities(name)
+    ])]
   };
 }
+function actionCategory(name, configured) {
+  if (typeof configured === "string" && configured.trim()) return configured.trim().toLowerCase();
+  const segments = name.split(".");
+  if (segments[0] === "metamask" && segments.length > 2) return segments[1] ?? "metamask";
+  if (segments[0] === "app" || segments[0] === "cdp") return "runtime";
+  if (segments[0] === "ui") return "ui";
+  if (name.startsWith("assert_")) return "assertion";
+  if (name === "watch_logs" || name === "index_artifacts") return "evidence";
+  if (name === "command" || name === "wait" || name === "call" || name === "end") return "control";
+  return segments.length > 1 ? segments[0] || "utility" : "utility";
+}
+function actionSearchScore(entry, term) {
+  const name = entry.name.toLowerCase();
+  const segment = finalSegment(name);
+  const nameTerms = searchTerms(name.replaceAll(".", " ").replaceAll("_", " "));
+  const fields = entry.fields.map((field) => field.toLowerCase());
+  const description = entry.description.toLowerCase();
+  if (name === term) return 120;
+  if (segment === term) return 110;
+  if (entry.category === term) return 100;
+  if (fields.includes(term)) return 90;
+  if (nameTerms.includes(term)) return 80;
+  if (name.includes(term)) return 70;
+  if (fields.some((field) => field.includes(term))) return 60;
+  if (description.includes(term)) return 50;
+  if ([...nameTerms, ...fields].some((candidate) => fuzzyTermMatch(term, candidate))) return 40;
+  return 0;
+}
+function fuzzyTermMatch(term, candidate) {
+  if (term.length < 4 || candidate.length < 4) return false;
+  const threshold = Math.max(1, Math.floor(Math.max(term.length, candidate.length) / 4));
+  return levenshtein(term, candidate) <= threshold;
+}
+function searchTerms(value) {
+  return value.toLowerCase().match(/[a-z0-9]+/gu) ?? [];
+}
+function finalSegment(name) {
+  return name.split(".").pop() ?? name;
+}
+function levenshtein(left, right) {
+  const prior = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const substitution = (prior[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1);
+      current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (prior[rightIndex] ?? 0) + 1, substitution);
+    }
+    for (let index = 0; index < current.length; index += 1) prior[index] = current[index] ?? 0;
+  }
+  return prior[right.length] ?? right.length;
+}
 export {
   describeManifestActions,
+  findRelatedActions,
   fuzzyResolveActions,
   handleActions,
-  handleManifest
+  renderHumanActionCatalog,
+  renderHumanActionExample,
+  searchActions,
+  summarizeActionCategories
 };

package/dist/commands/parse-args.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { detectAdapter } from "../harness.js";
 import { assertAdapter, manifestPath } from "../paths.js";
+import { explicitRecipeTrustOptions } from "../recipe-security.js";
 import { ADAPTER_DETECT_NEXT } from "./shared.js";
 import { EXIT } from "./shared.js";
 class CliError extends Error {
@@ -19,12 +20,15 @@ function parseArgs(argv, command) {
   const options = {};
   const booleanOptions = /* @__PURE__ */ new Set([
     "json",
+    "jsonStream",
     "launchExistingDist",
     "startWatch",
     "record",
     "plan",
     "list",
+    "describe",
     "raw",
+    "categories",
     "fix",
     "force",
     "resolveOnly",
@@ -140,13 +144,21 @@ function parsePort(value, errorMessage) {
 }
 function runtimeOptionsFromCli(options) {
   const recordVideo = options.recordVideo;
+  const trust = explicitRecipeTrustOptions({
+    sourceTrust: optionString(options, "sourceTrust"),
+    sourceKind: optionString(options, "sourceKind"),
+    sourceName: optionString(options, "sourceName"),
+    sourceDigest: optionString(options, "sourceDigest"),
+    approvalDigest: optionString(options, "approvePlan")
+  });
   return {
     cdpPort: optionString(options, "cdpPort"),
     watcherPort: optionString(options, "watcherPort") ?? optionString(options, "metroPort"),
     launchExistingDist: optionFlag(options, "launchExistingDist"),
     slot: optionString(options, "slot"),
     validationRuntimeDir: optionString(options, "validationRuntimeDir"),
-    recordVideo: recordVideo === "full-run" ? "full-run" : false
+    recordVideo: recordVideo === "full-run" ? "full-run" : false,
+    ...trust
   };
 }
 function resolveAdapter(options) {