@deeeed/metamask-harness 0.19.1 → 0.21.0

package/dist/command-contract.js

@@ -58,8 +58,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
     })
   },
   checklist: {
-    usage: "mm-harness checklist mark <task-dir> <step> [options]",
-    options: options(HELP, {
+    usage: "mm-harness checklist <mark <task-dir> <step> | closeout <task-dir>> [options]",
+    options: options(HELP, JSON, {
       "--mark-last": bool(),
       "--already-fixed": bool(),
       "--no-self-review": bool(),
@@ -67,10 +67,14 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--skip-checklist": bool(),
       "--reason": value(),
       "--checklist": value(),
-      "--signal": value()
+      "--signal": value(),
+      "--share": bool(),
+      "--config": value(),
+      "--destination": value(),
+      "--metadata": value()
     }),
     positionals: [
-      { label: "action", choices: ["mark"] },
+      { label: "action", choices: ["mark", "closeout"] },
       { label: "task-dir" },
       {
         label: "step",
@@ -82,7 +86,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
         validDescription: "start|complete|no-change|blocked|a positive numeric step"
       }
     ],
-    minimumPositionals: 3
+    minimumPositionals: 2
   },
   actions: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
@@ -307,6 +311,55 @@ function validatePublicInvocation(argv, examples = {}) {
     }
   }
   if (seenOptions.has("--help") || seenOptions.has("-h")) return null;
+  if (name === "checklist") {
+    const action = positionals[0];
+    const markOnly = [
+      "--mark-last",
+      "--already-fixed",
+      "--no-self-review",
+      "--skip-learnings",
+      "--skip-checklist",
+      "--reason",
+      "--checklist",
+      "--signal"
+    ];
+    const closeoutOnly = [
+      "--json",
+      "--share",
+      "--config",
+      "--destination",
+      "--metadata"
+    ];
+    const invalidOption = (action === "mark" ? closeoutOnly : markOnly).find(
+      (option) => seenOptions.has(option)
+    );
+    if (invalidOption && (action === "mark" || action === "closeout")) {
+      return usageFailure(
+        "CLI_UNKNOWN_OPTION",
+        name,
+        `${invalidOption} is not valid with checklist ${action}.`,
+        contract,
+        examples
+      );
+    }
+    if (action === "mark" && positionals.length < 3) {
+      return missingPositionalFailure(
+        name,
+        "checklist mark requires <step>.",
+        contract,
+        examples
+      );
+    }
+    if (action === "closeout" && positionals.length > 2) {
+      return usageFailure(
+        "CLI_EXCESS_POSITIONAL",
+        name,
+        `unexpected positional '${positionals[2]}'; checklist closeout accepts only <task-dir>.`,
+        contract,
+        examples
+      );
+    }
+  }
   if (contract.leadingPositionals && !contract.requiredUnless?.some((option) => seenOptions.has(option)) && tokens.slice(0, contract.leadingPositionals).some((argument) => !argument || argument.startsWith("-"))) {
     const missing = contract.positionals?.[0]?.label ?? "argument";
     return missingPositionalFailure(name, `${name} requires <${missing}> first.`, contract, examples);

package/dist/commands/call.js

@@ -149,7 +149,8 @@ async function handleCall(argv) {
       describedAction,
       adapter,
       target,
-      process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness"
+      process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness",
+      args
     ) ?? `mm-harness actions --action ${resolvedAction} --adapter ${adapter}` : `mm-harness actions --action ${resolvedAction} --adapter ${adapter}`;
     if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "call", adapter, action: shortName, resolvedAction, args: redactCallValue(args), findings: validation.findings, ...parameterHelp.length > 0 ? { parameterHelp } : {}, error: { code: "RECIPE_VALIDATION_FAILED", message, userAction } }, null, 2));
     else {
@@ -259,7 +260,8 @@ async function handleCall(argv) {
         describedAction,
         adapter,
         target,
-        process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness"
+        process.env.MM_HARNESS_INVOKED_AS ?? process.env.MM_HARNESS_EXECUTABLE ?? "mm-harness",
+        args
       ) : void 0;
       const taughtViolation = violation.code === "APP_LOGIC_FAILURE" && conciseFailure.includes(" requires ") && example ? { ...violation, userAction: example } : violation;
       return emitHealViolation(json, "call", result, taughtViolation, state, adapter);
@@ -331,12 +333,13 @@ function parameterValidationHelp(action, findings, args) {
     const property = name && isRecord(properties[name]) ? properties[name] : void 0;
     if (!name || !property) return [];
     const validValues = Array.isArray(property.enum) ? property.enum : void 0;
+    const type = typeof property.type === "string" ? property.type : Array.isArray(property.type) ? property.type.filter((value) => typeof value === "string").join("|") : void 0;
     const received = Object.hasOwn(args, name) ? args[name] : void 0;
     const suggestion = issue === "invalid" && received !== void 0 && validValues ? closest(String(received), validValues.map(String)) : void 0;
     return [{
       issue,
       name,
-      ...typeof property.type === "string" ? { type: property.type } : {},
+      ...type ? { type } : {},
       ...validValues ? { validValues } : {},
       ...typeof property.description === "string" ? { description: property.description } : {},
       ...issue === "invalid" && received !== void 0 ? { received } : {},
@@ -467,7 +470,7 @@ function renderCallExamples(short, examples) {
   if (!Array.isArray(examples)) return [];
   const out = [];
   for (const example of examples.slice(0, 2)) {
-    const node = isRecord(example) && isRecord(example.node) ? example.node : void 0;
+    const node = isRecord(example) ? example : void 0;
     if (!node) continue;
     const tokens = Object.entries(node).filter(([key]) => key !== "action" && key !== "intent").map(([key, value]) => `${key}=${typeof value === "string" ? value : JSON.stringify(value)}`);
     out.push(`mm-harness call ${short} ${tokens.join(" ")}`.trim());

package/dist/commands/check.js

@@ -61,6 +61,7 @@ async function handleCheck(argv) {
   });
   const policyFailed = suppressionCheck.status === "fail";
   const fixes = [];
+  const eslintConfigArgs = resolveEslintConfigArgs(packageJson);
   if (fix && !policyFailed) {
     fixes.push(
       runToolCheck({
@@ -70,7 +71,7 @@ async function handleCheck(argv) {
         artifactsDir,
         files: existingChangedFiles.filter((file) => JS_TS_EXT_RE.test(file)),
         command: executable(target, "eslint"),
-        args: ["--fix", "--cache", "--cache-location", path.join(artifactsDir, "eslintcache")]
+        args: [...eslintConfigArgs, "--fix", "--cache", "--cache-location", path.join(artifactsDir, "eslintcache")]
       })
     );
     fixes.push(runFormatterFix({ target, artifactsDir, files: existingChangedFiles.filter((file) => FORMAT_EXT_RE.test(file)) }));
@@ -85,7 +86,7 @@ async function handleCheck(argv) {
         artifactsDir,
         files: existingChangedFiles.filter((file) => JS_TS_EXT_RE.test(file)),
         command: executable(target, "eslint"),
-        args: ["--cache", "--cache-location", path.join(artifactsDir, "eslintcache")]
+        args: [...eslintConfigArgs, "--cache", "--cache-location", path.join(artifactsDir, "eslintcache")]
       })
     );
     checks.push(runFormatterCheck({ target, artifactsDir, files: existingChangedFiles.filter((file) => FORMAT_EXT_RE.test(file)) }));
@@ -294,6 +295,12 @@ function executable(target, name) {
   const local = path.join(target, "node_modules", ".bin", name);
   return fs.existsSync(local) ? local : null;
 }
+function resolveEslintConfigArgs(packageJson) {
+  const lintScript = packageJson?.scripts?.["lint:eslint"];
+  if (typeof lintScript !== "string") return [];
+  const match = lintScript.match(/(?:^|\s)(?:-c|--config)\s+(['"]?)([^\s'"]+)\1/u);
+  return match?.[2] ? ["--config", match[2]] : [];
+}
 function runToolCheck(input) {
   if (input.files.length === 0) {
     return { id: input.id, label: input.label, status: "skip", reason: "no changed matching files" };

package/dist/commands/checklist.js

@@ -7,7 +7,96 @@ const require2 = createRequire(import.meta.url);
 const MARK_SCRIPT = require2.resolve(
   "@farmslot/agent-runtime/scripts/mark-checklist-step.cjs"
 );
-const USAGE = "mm-harness checklist mark <task-dir> <step> [options]";
+const USAGE = "mm-harness checklist <mark <task-dir> <step> | closeout <task-dir>> [options]";
+const CHECKLIST_VALUE_OPTIONS = /* @__PURE__ */ new Set([
+  "--reason",
+  "--checklist",
+  "--signal",
+  "--config",
+  "--destination",
+  "--metadata"
+]);
+function parseChecklistArgv(argv) {
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    if (arg.startsWith("-")) {
+      const option = arg.split("=", 1)[0] ?? arg;
+      if (CHECKLIST_VALUE_OPTIONS.has(option) && !arg.includes("=")) index += 1;
+      continue;
+    }
+    positionals.push({ index, value: arg });
+  }
+  const consumed = new Set(positionals.slice(0, 2).map(({ index }) => index));
+  return {
+    action: positionals[0]?.value,
+    taskDir: positionals[1]?.value,
+    step: positionals[2]?.value,
+    forwarded: argv.filter((_, index) => !consumed.has(index))
+  };
+}
+function handoffCommand() {
+  if (process.env.HANDOFF_BIN) {
+    try {
+      fs.accessSync(process.env.HANDOFF_BIN, fs.constants.X_OK);
+      return { command: process.env.HANDOFF_BIN, prefix: [] };
+    } catch {
+      return { command: process.execPath, prefix: [process.env.HANDOFF_BIN] };
+    }
+  }
+  return {
+    command: process.execPath,
+    prefix: [require2.resolve("@farmslot/handoff/cli")]
+  };
+}
+function closeoutArgs(taskDir, args) {
+  const normalized = args.flatMap((arg) => {
+    const option = ["--config", "--destination", "--metadata"].find(
+      (name) => arg.startsWith(`${name}=`)
+    );
+    return option ? [option, arg.slice(option.length + 1)] : [arg];
+  });
+  if (process.env.METAMASK_AGENTIC_LEARNINGS_DIR && !normalized.includes("--destination")) {
+    return [
+      "closeout",
+      taskDir,
+      ...normalized,
+      "--destination",
+      process.env.METAMASK_AGENTIC_LEARNINGS_DIR
+    ];
+  }
+  return ["closeout", taskDir, ...normalized];
+}
+function runCloseout(taskDir, args, stdio) {
+  try {
+    const { command, prefix } = handoffCommand();
+    return spawnSync(command, [...prefix, ...closeoutArgs(taskDir, args)], {
+      encoding: "utf8",
+      stdio
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      status: 1,
+      stdout: "",
+      stderr: message,
+      error: new Error(message)
+    };
+  }
+}
+function stageLearningPackage(taskDir, step, markArgs) {
+  if (!["complete", "no-change"].includes(step ?? "") || markArgs.includes("--skip-learnings") || !fs.existsSync(path.join(taskDir, "inputs", "handoff.json"))) {
+    return;
+  }
+  try {
+    const result = runCloseout(taskDir, ["--json"], "pipe");
+    if (result.status === 0) return;
+  } catch {
+  }
+  console.error(
+    `Warning: learning capture could not be staged; rerun: mm-harness checklist closeout ${taskDir}; task verdict is unchanged.`
+  );
+}
 function terminalSignalStatus(taskDir) {
   try {
     const target = JSON.parse(
@@ -20,8 +109,7 @@ function terminalSignalStatus(taskDir) {
     return null;
   }
 }
-function preserveTerminalSignal(taskDir, markArgs) {
-  const step = markArgs[0];
+function preserveTerminalSignal(taskDir, step) {
   if (step !== "start" && numericMarkStep(step) === null) return false;
   const status = terminalSignalStatus(taskDir);
   if (!status) return false;
@@ -60,8 +148,7 @@ function checklistStepRequiresDiffPass(checklist, stepNumber) {
   }
   return false;
 }
-function checkDiffGateReady(taskDir, markArgs) {
-  const step = markArgs[0];
+function checkDiffGateReady(taskDir, step) {
   const stepNumber = numericMarkStep(step);
   if (stepNumber === null) return true;
   let checklist = "";
@@ -92,8 +179,8 @@ function checkDiffGateReady(taskDir, markArgs) {
   console.error("Then rerun the same checklist mark command.");
   return false;
 }
-function teachRecipeCompletion(taskDir, markArgs) {
-  if (markArgs[0] !== "complete") return;
+function teachRecipeCompletion(taskDir, step) {
+  if (step !== "complete") return;
   const artifactsDir = path.join(taskDir, "artifacts");
   if (!fs.existsSync(path.join(artifactsDir, "recipe.json"))) return;
   const qualityPath = path.join(artifactsDir, "recipe-quality.json");
@@ -114,25 +201,41 @@ function teachRecipeCompletion(taskDir, markArgs) {
   console.error("Then rerun the same checklist complete command.");
 }
 async function handleChecklist(argv) {
-  const [action, taskDir, ...markArgs] = argv;
-  if (action !== "mark" || !taskDir || markArgs.length === 0) {
+  const { action, taskDir, step, forwarded } = parseChecklistArgv(argv);
+  if (!taskDir) {
     console.error(`usage: ${USAGE}`);
     return EXIT.usage;
   }
   const resolvedTaskDir = path.resolve(taskDir);
-  if (preserveTerminalSignal(resolvedTaskDir, markArgs)) return EXIT.ok;
-  if (!checkDiffGateReady(resolvedTaskDir, markArgs)) return EXIT.runtime;
-  teachRecipeCompletion(resolvedTaskDir, markArgs);
+  if (action === "closeout") {
+    const result2 = runCloseout(resolvedTaskDir, forwarded, "inherit");
+    if (result2.error) {
+      console.error(`mm-harness checklist closeout: ${result2.error.message}`);
+      return EXIT.runtime;
+    }
+    return result2.status ?? EXIT.runtime;
+  }
+  if (action !== "mark" || !step) {
+    console.error(`usage: ${USAGE}`);
+    return EXIT.usage;
+  }
+  if (preserveTerminalSignal(resolvedTaskDir, step)) return EXIT.ok;
+  if (!checkDiffGateReady(resolvedTaskDir, step)) return EXIT.runtime;
+  teachRecipeCompletion(resolvedTaskDir, step);
   const result = spawnSync(
     process.execPath,
-    [MARK_SCRIPT, resolvedTaskDir, ...markArgs],
+    [MARK_SCRIPT, resolvedTaskDir, ...forwarded],
     { stdio: "inherit" }
   );
   if (result.error) {
     console.error(`mm-harness checklist mark: ${result.error.message}`);
     return EXIT.runtime;
   }
-  return result.status ?? EXIT.runtime;
+  const status = result.status ?? EXIT.runtime;
+  if (status === EXIT.ok) {
+    stageLearningPackage(resolvedTaskDir, step, forwarded);
+  }
+  return status;
 }
 export {
   handleChecklist

package/dist/commands/launch/extension.js

@@ -2,7 +2,10 @@ import { execFileSync } from "node:child_process";
 import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
-import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import {
+  depsCheck,
+  recordDepsBaseline
+} from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { colorHumanMessage } from "../../cli-color.js";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
@@ -27,9 +30,11 @@ function extensionDepsBlock(target) {
   }
   return null;
 }
-function installExtensionDeps(target) {
+async function installExtensionDeps(target) {
   const installScript = path.join(runnerDir, "adapters/shared/install-repo-deps.sh");
-  return spawnScriptStreaming(installScript, ["--target", target], target);
+  const result = await spawnScriptStreaming(installScript, ["--target", target], target);
+  if (result.status === 0) recordDepsBaseline(target);
+  return result;
 }
 async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
   if (process.env.CHROME_USER_DATA_DIR) {

package/dist/commands/launch/index.js

@@ -196,28 +196,28 @@ async function handleLaunchLocked(argv, stream) {
           exitCode: EXIT.infra
         });
       }
-      const depsBlock = extensionDepsBlock(target);
-      if (depsBlock) {
-        if (heal === "off") {
-          return launchUsage(jsonOutput, stream, depsBlock.message, depsBlock.userAction);
-        }
-        const recoveryCode2 = "deps.installed";
-        state.attemptedRecoveries.push(recoveryCode2);
-        stream.phase("recover");
-        const repaired = await installExtensionDeps(target);
-        if (repaired.status !== 0 || extensionDepsBlock(target)) {
-          return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-            code: "DEPENDENCY_INSTALL_FAILED",
-            message: depsBlock.message,
-            recoverable: false,
-            userAction: "install the checkout-pinned Node version, then re-run mm-harness launch",
-            originalError: repaired.output,
-            exitCode: EXIT.infra
-          });
-        }
-        state.recovered.push(recoveryCode2);
-        state.mutations.push({ type: "dependencies", action: "installed", path: target });
+    }
+    const depsBlock = extensionDepsBlock(target);
+    if (depsBlock) {
+      if (heal === "off") {
+        return launchUsage(jsonOutput, stream, depsBlock.message, depsBlock.userAction);
       }
+      const recoveryCode2 = "deps.installed";
+      state.attemptedRecoveries.push(recoveryCode2);
+      stream.phase("recover");
+      const repaired = await installExtensionDeps(target);
+      if (repaired.status !== 0 || extensionDepsBlock(target)) {
+        return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+          code: "DEPENDENCY_INSTALL_FAILED",
+          message: depsBlock.message,
+          recoverable: false,
+          userAction: "install the checkout-pinned Node version, then re-run mm-harness launch",
+          originalError: repaired.output,
+          exitCode: EXIT.infra
+        });
+      }
+      state.recovered.push(recoveryCode2);
+      state.mutations.push({ type: "dependencies", action: "installed", path: target });
     }
   }
   stream.phase("launch");
@@ -290,10 +290,20 @@ async function handleLaunchLocked(argv, stream) {
       originalError: bound.originalError
     });
   }
-  const recoveryCode = RECOVERY_CODE[adapter];
+  const restartMobileApp = adapter === "mobile" && mobileBridgeTargetMissing(attempt.output);
+  const recoveryCode = restartMobileApp ? "mobile.app-restarted" : RECOVERY_CODE[adapter];
   state.attemptedRecoveries.push(recoveryCode);
   stream.phase("recover");
-  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, machine, displayMode);
+  attempt = await executeComposition(
+    adapter,
+    mobileTarget,
+    tier,
+    wantWatch,
+    target,
+    machine,
+    displayMode,
+    restartMobileApp
+  );
   if (attempt.status === 0) {
     state.recovered.push(recoveryCode);
     return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
@@ -321,6 +331,9 @@ function extensionProductConfigMissing(output) {
 function mobileProvisioningBlocked(output) {
   return /open-device: configured iOS simulator '.+' does not exist|open-device: no MetaMask bundle found|fast mode requires an installed (?:iOS dev client|Android dev client)/u.test(output);
 }
+function mobileBridgeTargetMissing(output) {
+  return /no bridge target matched/iu.test(output);
+}
 function mobileProvisionCommand(target, mobileTarget) {
   const platform = mobileTarget === "android" ? "android" : "ios";
   const device = platform === "ios" ? process.env.IOS_SIMULATOR || process.env.SIM_UDID : process.env.ADB_SERIAL || process.env.ANDROID_SERIAL || process.env.ANDROID_DEVICE;
@@ -406,9 +419,9 @@ function nativeInputsChanged(target, adapter) {
     return false;
   }
 }
-async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen") {
+async function executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode = "fullscreen", restartMobileApp = false) {
   if (adapter === "mobile") {
-    return launchMobile(target, mobileTarget, tier, json);
+    return launchMobile(target, mobileTarget, tier, json, restartMobileApp);
   }
   return launchExtension(target, tier, wantWatch, displayMode);
 }

package/dist/commands/launch/mobile.js

@@ -1,11 +1,11 @@
 import { prepareMobile } from "../../adapters/mobile/prepare.js";
 import { ensureHarnessFresh } from "../../adapters/harness-freshness.js";
-async function launchMobile(target, mobileTarget, tier, json) {
+async function launchMobile(target, mobileTarget, tier, json, restartApp = false) {
   await ensureHarnessFresh(target, "mobile");
   const platform = mobileTarget ?? "ios";
   const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : void 0;
   const preflightMode = tier === "build" ? "auto" : "fast";
-  return prepareMobile(target, { platform, json, watcherPort, preflightMode });
+  return prepareMobile(target, { platform, json, watcherPort, preflightMode, restartApp });
 }
 export {
   launchMobile

package/dist/commands/manifest.js

@@ -10,10 +10,14 @@ import {
   shellQuoteArg
 } from "./parse-args.js";
 import { resolveMetaMaskLibrarySources } from "./run-engine.js";
+import { isSensitiveKey, redactStructuredValue } from "../command-journal.js";
 import {
+  OFFICIAL_RECIPE_ACTIONS,
   officialRecipeActionCapabilities
 } from "@farmslot/protocol";
 import { metaMaskActionExecutionCapabilities } from "../recipe-security.js";
+import { closest } from "../command-contract.js";
+const OFFICIAL_ACTIONS = new Set(OFFICIAL_RECIPE_ACTIONS);
 async function handleActions({ options, positional }) {
   const { adapter, target } = resolveAdapter(options);
   const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
@@ -174,7 +178,7 @@ function renderHumanActionCatalog(actions, options) {
   return lines.join("\n");
 }
 function renderHumanActionExample(entry, adapter, target, executable) {
-  const node = authoredExampleNode(entry.examples);
+  const node = authoredExampleNode(entry.examples, void 0, entry.schema);
   if (!node) return void 0;
   const out = (style, text) => color(style, text, { stream: process.stdout });
   const command = actionExampleCommand(entry, adapter, target, executable);
@@ -187,12 +191,12 @@ function renderHumanActionExample(entry, adapter, target, executable) {
   ];
   return lines.join("\n");
 }
-function actionExampleCommand(entry, adapter, target, executable) {
-  const node = authoredExampleNode(entry.examples);
+function actionExampleCommand(entry, adapter, target, executable, preferredValues) {
+  const node = authoredExampleNode(entry.examples, preferredValues, entry.schema);
   if (!node) return void 0;
   const commandName = executable.endsWith("/mm-harness") ? "mm-harness" : executable;
   const args = entry.fields.flatMap(
-    (field) => Object.hasOwn(node, field) ? [shellQuoteArg(`${field}=${actionCallValue(node[field])}`)] : []
+    (field) => Object.hasOwn(node, field) ? [shellQuoteArg(`${field}=${safeActionCallValue(field, node[field])}`)] : []
   );
   return [
     shellQuoteArg(commandName),
@@ -205,16 +209,81 @@ function actionExampleCommand(entry, adapter, target, executable) {
     shellQuoteArg(target)
   ].join(" ");
 }
-function authoredExampleNode(examples) {
+function authoredExampleNode(examples, preferredValues, schema) {
   if (!Array.isArray(examples)) return void 0;
+  if (preferredValues && Object.keys(preferredValues).length > 0) {
+    const normalizedValues = normalizePreferredValues(preferredValues, schema);
+    const nodes = examples.filter(isRecord);
+    if (nodes.length === 0) return void 0;
+    const ranked = nodes.map((node) => ({
+      node,
+      completeness: Object.keys(node).filter((name) => !["action", "intent", "next"].includes(name)).length,
+      score: Object.entries(normalizedValues).reduce((score, [name, value]) => {
+        if (!Object.hasOwn(node, name)) return score;
+        return score + (sameActionValue(name, node[name], value) ? 3 : -1);
+      }, 0)
+    })).sort(
+      (left, right) => right.score - left.score || right.completeness - left.completeness
+    );
+    return { ...ranked[0].node, ...normalizedValues };
+  }
   for (const example of examples) {
-    if (isRecord(example) && isRecord(example.node)) return example.node;
+    if (isRecord(example)) return example;
   }
   return void 0;
 }
+function normalizePreferredValues(preferredValues, schema) {
+  const properties = isRecord(schema) && isRecord(schema.properties) ? schema.properties : {};
+  return Object.fromEntries(
+    Object.entries(preferredValues).flatMap(([name, value]) => {
+      const property = isRecord(properties[name]) ? properties[name] : void 0;
+      if (property && !matchesSchemaType(property.type, value)) return [];
+      const values = property && Array.isArray(property.enum) ? property.enum : void 0;
+      if (!values) {
+        return [[name, value]];
+      }
+      const compatibleValue = values.find(
+        (candidate) => sameActionValue(name, candidate, value)
+      );
+      if (compatibleValue !== void 0) return [[name, compatibleValue]];
+      const strings = values.filter((candidate) => typeof candidate === "string");
+      const suggestion = typeof value === "string" ? closest(value, strings) : void 0;
+      return suggestion === void 0 ? [] : [[name, suggestion]];
+    })
+  );
+}
+function matchesSchemaType(type, value) {
+  const types = Array.isArray(type) ? type : [type];
+  if (types.every((candidate) => typeof candidate !== "string")) return true;
+  return types.some((candidate) => {
+    if (candidate === "null") return value === null;
+    if (candidate === "array") return Array.isArray(value);
+    if (candidate === "object") return isRecord(value);
+    if (candidate === "integer") return typeof value === "number" && Number.isInteger(value);
+    return typeof value === candidate;
+  });
+}
+function sameActionValue(name, left, right) {
+  if (name === "state") {
+    const canonicalState = (value) => {
+      if (value === "present") return "open";
+      if (value === "absent") return "none";
+      return value;
+    };
+    left = canonicalState(left);
+    right = canonicalState(right);
+  }
+  const scalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+  if (scalar(left) && scalar(right)) return String(left) === String(right);
+  return JSON.stringify(left) === JSON.stringify(right);
+}
 function actionCallValue(value) {
   return typeof value === "string" ? value : JSON.stringify(value);
 }
+function safeActionCallValue(field, value) {
+  if (isSensitiveKey(field)) return `<${field}>`;
+  return actionCallValue(redactStructuredValue(value));
+}
 function humanFieldNames(entry) {
   const schema = isRecord(entry.schema) ? entry.schema : void 0;
   const properties = schema && isRecord(schema.properties) ? schema.properties : void 0;
@@ -238,22 +307,15 @@ function summarizeActionCategories(actions) {
 }
 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") : [];
-  const custom = Array.isArray(manifestRecord.custom_actions) ? manifestRecord.custom_actions.flatMap((entry) => {
-    if (typeof entry === "string") return [{ name: entry, metadata: metadata[entry] }];
-    if (isRecord(entry) && typeof entry.name === "string") {
-      const entryMetadata = { ...entry };
-      const metadataOverride = metadata[entry.name];
-      if (isRecord(metadataOverride)) Object.assign(entryMetadata, metadataOverride);
-      return [{ name: entry.name, metadata: entryMetadata }];
-    }
-    return [];
-  }) : [];
-  return [
-    ...official.map((name) => describeManifestAction(name, "official", metadata[name], actionSources.get(name))),
-    ...custom.map((entry) => describeManifestAction(entry.name, "custom", entry.metadata, actionSources.get(entry.name)))
-  ];
+  const actions = isRecord(manifestRecord.actions) ? manifestRecord.actions : {};
+  return Object.entries(actions).map(
+    ([name, metadata]) => describeManifestAction(
+      name,
+      OFFICIAL_ACTIONS.has(name) ? "official" : "custom",
+      metadata,
+      actionSources.get(name)
+    )
+  );
 }
 function describeManifestAction(name, kind, metadata, source) {
   const record = isRecord(metadata) ? metadata : {};
@@ -263,7 +325,7 @@ function describeManifestAction(name, kind, metadata, source) {
   return {
     name,
     kind,
-    category: actionCategory(name, record.category),
+    category: actionCategory(name),
     description: typeof record.description === "string" ? record.description : "",
     fields: properties,
     schema,
@@ -280,8 +342,7 @@ function describeManifestAction(name, kind, metadata, source) {
     ])]
   };
 }
-function actionCategory(name, configured) {
-  if (typeof configured === "string" && configured.trim()) return configured.trim().toLowerCase();
+function actionCategory(name) {
   const segments = name.split(".");
   if (segments[0] === "metamask" && segments.length > 2) return segments[1] ?? "metamask";
   if (segments[0] === "app" || segments[0] === "cdp") return "runtime";