@deeeed/metamask-harness 0.18.0 → 0.19.0

package/dist/commands/list-executables.js

@@ -1,9 +1,10 @@
+import fs from "node:fs";
 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, shellQuoteArg } from "./parse-args.js";
+import { optionFlag, optionString, optionStrings, resolveAdapter, shellQuoteArg } from "./parse-args.js";
 import { describeManifestActions, renderHumanActionCatalog } from "./manifest.js";
 import {
   describeRunnableRecipe,
@@ -19,9 +20,9 @@ function catalogDescription(description) {
 async function handleListExecutables(command, options) {
   const json = optionFlag(options, "json");
   const { adapter } = resolveAdapter(options);
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
   if (command === "run") {
-    const recipes = listRunnableRecipes(adapter, librarySources);
+    const recipes = await listRunnableRecipes(adapter, librarySources);
     if (json) {
       console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, recipes }, null, 2));
       return EXIT.ok;
@@ -31,9 +32,11 @@ async function handleListExecutables(command, options) {
     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 variant = recipe.variant ? ` variant=${recipe.variant}` : " variant=all";
+      const parameters = recipe.parameters.length > 0 ? ` params=${recipe.parameters.map((parameter) => parameter.name).join(",")}` : "";
       const summary = catalogDescription(recipe.description);
       const description = summary ? ` \u2014 ${summary}` : "";
-      console.log(`  ${out("cmd", recipe.name)} ${out("dim", `[${recipe.source}]${shadowed}`)}${description}`);
+      console.log(`  ${out("cmd", recipe.name)} ${out("dim", `[${recipe.source}]${variant}${shadowed}${parameters}`)}${description}`);
     }
     return EXIT.ok;
   }
@@ -83,14 +86,18 @@ async function handleListExecutables(command, options) {
 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 libraryEntries = optionStrings(options, "library");
+  const directRecipePath = path.resolve(recipeArg);
+  const librarySources = await resolveMetaMaskLibrarySources(
+    libraryEntries,
+    fs.existsSync(directRecipePath) ? directRecipePath : void 0
+  );
+  const result = await describeRunnableRecipe(recipeArg, adapter, librarySources);
+  const targetEntry = optionString(options, "target");
   const replayTarget = targetEntry ? path.resolve(targetEntry) : void 0;
   const contextFlags = [
     `--adapter ${adapter}`,
-    ...libraryEntry ? [`--library ${shellQuoteArg(libraryEntry)}`] : [],
+    ...libraryEntries?.map((entry) => `--library ${shellQuoteArg(entry)}`) ?? [],
     ...replayTarget ? [`--target ${shellQuoteArg(replayTarget)}`] : []
   ].join(" ");
   const discoveryCommand = `mm-harness run --list ${contextFlags}`;
@@ -114,7 +121,14 @@ async function handleDescribeRecipe(recipeArg, options) {
     return EXIT.usage;
   }
   const recipe = result.recipe;
-  const nextCommand = `mm-harness run ${shellQuoteArg(recipeArg)} --plan ${contextFlags}`;
+  const parameterArgs = recipe.parameters.filter((parameter) => parameter.required && !Object.hasOwn(parameter, "default")).map((parameter) => `${parameter.name}=${shellQuoteArg(exampleParameterValue(parameter))}`);
+  const runCommand = [
+    "mm-harness run",
+    shellQuoteArg(recipeArg),
+    ...parameterArgs,
+    contextFlags
+  ].filter(Boolean).join(" ");
+  const nextCommand = `${runCommand} --plan`;
   if (json) {
     console.log(JSON.stringify({
       schemaVersion: 1,
@@ -122,6 +136,7 @@ async function handleDescribeRecipe(recipeArg, options) {
       action: "describe",
       status: "pass",
       recipe,
+      runCommand,
       nextCommand
     }, null, 2));
     return EXIT.ok;
@@ -133,24 +148,45 @@ async function handleDescribeRecipe(recipeArg, options) {
   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`);
+  if (recipe.$schema) console.log(`  ${out("label", "schema:")} ${recipe.$schema}`);
+  console.log(`  ${out("label", "variant:")} ${recipe.variant ?? "all adapters"}`);
+  if (recipe.shadows.length > 0) {
+    console.log(`  ${out("label", "shadows:")} ${recipe.shadows.join(", ")}`);
+  }
+  if (recipe.parameters.length === 0) {
+    console.log(`  ${out("label", "parameters:")} 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)}`);
+    console.log(`  ${out("label", `parameters (${recipe.parameters.length})`)}`);
+    for (const parameter of recipe.parameters) {
+      const required = parameter.required ? " required" : "";
+      const defaultValue = Object.hasOwn(parameter, "default") ? ` default=${compactValue(parameter.default)}` : "";
+      const choices = parameter.enum ? ` choices=${compactValue(parameter.enum)}` : "";
+      const description = parameter.description ? ` \u2014 ${parameter.description}` : "";
+      console.log(
+        `    ${out("cmd", parameter.name)}${parameter.type ? ` (${parameter.type})` : ""}${required}${defaultValue}${choices}${description}`
+      );
     }
   }
   renderComposition("actions", recipe.actions, out);
-  if (!recipe.actionsComplete) {
-    console.log(`  ${out("comment", "Note: actions inside external library flows are not expanded.")}`);
+  renderComposition("called recipes", recipe.nestedRecipes, out);
+  if (recipe.unresolvedRecipes.length > 0) {
+    renderComposition("unresolved recipes", recipe.unresolvedRecipes, out);
   }
-  renderComposition("flows", recipe.flows, out);
+  console.log(`  ${out("comment", `Run: ${runCommand}`)}`);
   console.log(`  ${out("comment", `Next: ${nextCommand}`)}`);
   return EXIT.ok;
 }
+function exampleParameterValue(parameter) {
+  if (parameter.enum && parameter.enum.length > 0) return stringifyAssignmentValue(parameter.enum[0]);
+  if (parameter.type === "boolean") return "false";
+  if (parameter.type === "number" || parameter.type === "integer") return "0";
+  if (parameter.type === "array") return "[]";
+  if (parameter.type === "object") return "{}";
+  return "value";
+}
+function stringifyAssignmentValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value) ?? String(value);
+}
 function compactValue(value) {
   const rendered = JSON.stringify(value);
   if (rendered === void 0) return String(value);

package/dist/commands/manifest.js

@@ -5,6 +5,7 @@ import {
   isRecord,
   optionFlag,
   optionString,
+  optionStrings,
   resolveAdapter,
   shellQuoteArg
 } from "./parse-args.js";
@@ -15,7 +16,7 @@ import {
 import { metaMaskActionExecutionCapabilities } from "../recipe-security.js";
 async function handleActions({ options, positional }) {
   const { adapter, target } = resolveAdapter(options);
-  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+  const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
   const { manifest, actionSources } = await resolveActionManifest(
     adapter,
     optionString(options, "actionManifest"),
@@ -92,13 +93,15 @@ async function handleActions({ options, positional }) {
   }
   const relatedActions = action && actions.length === 1 ? findRelatedActions(all, actions[0]) : void 0;
   if (json) {
+    const detailed = Boolean(action && actions.length === 1);
     console.log(JSON.stringify({
       schemaVersion: 1,
       command: "actions",
       adapter,
       ...query ? { query } : {},
       category,
-      actions,
+      detail: detailed ? "full" : "summary",
+      actions: detailed ? actions : actions.map(summarizeDescribedAction),
       ...relatedActions?.length ? { relatedActions } : {}
     }, null, 2));
   } else {
@@ -145,6 +148,10 @@ function findRelatedActions(entries, selected, limit = 5) {
   }).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 summarizeDescribedAction(entry) {
+  const { schema: _schema, examples: _examples, ...summary } = entry;
+  return summary;
+}
 function renderHumanActionCatalog(actions, options) {
   const out = (style, text) => color(style, text, { stream: process.stdout });
   const groups = /* @__PURE__ */ new Map();
@@ -170,11 +177,25 @@ 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 command = actionExampleCommand(entry, adapter, target, executable);
+  if (!command) return void 0;
+  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 actionExampleCommand(entry, adapter, target, executable) {
+  const node = authoredExampleNode(entry.examples);
+  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])}`)] : []
   );
-  const command = [
-    shellQuoteArg(executable),
+  return [
+    shellQuoteArg(commandName),
     "call",
     shellQuoteArg(entry.name),
     ...args,
@@ -183,13 +204,6 @@ function renderHumanActionExample(entry, adapter, target, executable) {
     "--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;
@@ -318,6 +332,7 @@ function levenshtein(left, right) {
   return prior[right.length] ?? right.length;
 }
 export {
+  actionExampleCommand,
   describeManifestActions,
   findRelatedActions,
   fuzzyResolveActions,
@@ -325,5 +340,6 @@ export {
   renderHumanActionCatalog,
   renderHumanActionExample,
   searchActions,
-  summarizeActionCategories
+  summarizeActionCategories,
+  summarizeDescribedAction
 };

package/dist/commands/parse-args.js

@@ -38,6 +38,7 @@ function parseArgs(argv, command) {
     "allDevices",
     "help"
   ]);
+  const repeatableOptions = /* @__PURE__ */ new Set(["library"]);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -70,15 +71,56 @@ function parseArgs(argv, command) {
       continue;
     }
     if (inlineValue !== void 0) {
-      options[key] = inlineValue;
+      assignOption(options, key, inlineValue, repeatableOptions);
       continue;
     }
     if (i + 1 >= argv.length) throw usageError(`Missing value for ${arg}`);
-    options[key] = argv[i + 1];
+    assignOption(options, key, argv[i + 1], repeatableOptions);
     i += 1;
   }
   return { positional, options, rawArgv: [...argv] };
 }
+function assignOption(options, key, value, repeatableOptions) {
+  if (!repeatableOptions.has(key)) {
+    options[key] = value;
+    return;
+  }
+  const existing = options[key];
+  if (existing === void 0) {
+    options[key] = [value];
+    return;
+  }
+  if (!Array.isArray(existing)) throw usageError(`--${key} has conflicting values.`);
+  options[key] = [...existing, value];
+}
+function parseRecipeParamAssignments(values) {
+  const params = {};
+  for (const assignment of values) {
+    const separator = assignment.indexOf("=");
+    if (separator <= 0) {
+      throw usageError(`recipe parameter ${JSON.stringify(assignment)} must use key=value.`);
+    }
+    const key = assignment.slice(0, separator).trim();
+    if (!key) throw usageError(`recipe parameter ${JSON.stringify(assignment)} has an empty key.`);
+    if (Object.hasOwn(params, key)) {
+      throw usageError(`recipe parameter ${JSON.stringify(key)} was provided more than once.`);
+    }
+    const raw = assignment.slice(separator + 1);
+    let value;
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      value = raw;
+    }
+    Object.defineProperty(params, key, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
+  }
+  return params;
+}
 function parseRecordVideoMode(value) {
   if (value === void 0 || value === "" || value === "true") return "full-run";
   if (value === "off" || value === "false") return false;
@@ -101,6 +143,14 @@ function optionString(options, key) {
   if (typeof value !== "string") throw usageError(`--${key} requires a value.`);
   return value;
 }
+function optionStrings(options, key) {
+  const value = options[key];
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw usageError(`--${key} requires a value.`);
+  }
+  return value;
+}
 function optionFlag(options, key) {
   const value = options[key];
   return value === true;
@@ -131,7 +181,7 @@ function adapterOption(options) {
   return adapter;
 }
 function targetPath(options) {
-  return path.resolve(optionString(options, "target") ?? optionString(options, "projectRoot") ?? process.cwd());
+  return path.resolve(optionString(options, "target") ?? process.cwd());
 }
 function actionManifestPathOption(options, adapter) {
   const configured = optionString(options, "actionManifest");
@@ -196,8 +246,10 @@ export {
   isRecord,
   optionFlag,
   optionString,
+  optionStrings,
   parseArgs,
   parsePort,
+  parseRecipeParamAssignments,
   requiredOption,
   resolveAdapter,
   runtimeOptionsFromCli,

package/dist/commands/provision.js

@@ -99,7 +99,6 @@ function provisionPositionals(rawArgv) {
   const valueFlags = /* @__PURE__ */ new Set([
     "--adapter",
     "--target",
-    "--project-root",
     "--platform",
     "--device-platform",
     "--branch",