@deeeed/metamask-harness 0.12.0 → 0.14.0

package/dist/commands/call.js

@@ -6,14 +6,17 @@ import { loadActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
 import { recipeRunning } from "../heal-bounds.js";
 import { EXIT } from "./shared.js";
+import { describeManifestActions, fuzzyResolveActions } from "./manifest.js";
 import {
   parseArgs,
+  isRecord,
   optionFlag,
   optionString,
   resolveAdapter,
   runtimeOptionsFromCli,
   usageError
 } from "./parse-args.js";
+import { getAdapterSurface } from "../adapters/surface.js";
 import { handleListExecutables } from "./list-executables.js";
 import { applyDeviceTargeting } from "./device-target.js";
 import {
@@ -31,7 +34,7 @@ async function handleCall(argv) {
     return handleListExecutables("call", options2);
   }
   if (argv.length > 0 && argv[0].startsWith("--")) {
-    const message = "call requires <action> first: mm-harness call <action> [--arg k=v ...] [flags]";
+    const message = "call requires <action> first: mm-harness call <action> [key=value ...] [--arg k=v ...] [flags]";
     console.error(message);
     return EXIT.usage;
   }
@@ -58,6 +61,7 @@ async function handleCall(argv) {
     return EXIT.usage;
   }
   const { adapter, target } = resolveAdapter(options);
+  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));
@@ -125,6 +129,7 @@ async function handleCall(argv) {
     state
   );
   if (violation !== null) return emitHealViolation(json, "call", result, violation, state, adapter);
+  const callOutput = readCallOutput(result.tracePath);
   if (json) {
     console.log(
       JSON.stringify(
@@ -139,6 +144,7 @@ async function handleCall(argv) {
           summaryPath: result.summaryPath,
           tracePath: result.tracePath,
           artifactManifestPath: result.artifactManifestPath,
+          ...callOutput !== void 0 ? { output: callOutput } : {},
           recovered: state.recovered,
           mutations: state.mutations,
           exitCode: result.status === "pass" ? EXIT.ok : EXIT.runtime
@@ -148,11 +154,105 @@ async function handleCall(argv) {
       )
     );
   } else {
-    console.log(`call ${resolvedAction}: ${result.status}
+    const rendered = callOutput !== void 0 ? `
+Result:
+${formatCallOutput(callOutput)}` : "";
+    console.log(`call ${resolvedAction}: ${result.status}${rendered}
 Artifacts: ${result.artifactManifestPath}`);
   }
   return result.status === "pass" ? EXIT.ok : EXIT.runtime;
 }
+function readCallOutput(tracePath) {
+  try {
+    const trace = JSON.parse(fs.readFileSync(tracePath, "utf8"));
+    const entries = Array.isArray(trace) ? trace : isRecord(trace) && Array.isArray(trace.entries) ? trace.entries : [];
+    const entry = entries.find((item) => isRecord(item) && item.nodeId === "call");
+    return isRecord(entry) && Object.prototype.hasOwnProperty.call(entry, "output") ? entry.output : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function formatCallOutput(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+  return JSON.stringify(value, null, 2);
+}
+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;
+  try {
+    ({ adapter } = resolveAdapter(options));
+    manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  } catch {
+    process.stdout.write(`${genericHelp}
+`);
+    return EXIT.ok;
+  }
+  const matches = shortName ? fuzzyResolveActions(describeManifestActions(manifest), shortName) : [];
+  if (matches.length === 0) {
+    process.stdout.write(`${genericHelp}
+`);
+    if (shortName) {
+      process.stdout.write(
+        `
+No action matches "${shortName}" for the ${adapter} adapter.
+  Next: mm-harness actions --adapter ${adapter}   # list the action vocabulary
+`
+      );
+    }
+    return EXIT.ok;
+  }
+  for (const entry of matches) process.stdout.write(renderCallActionHelp(entry));
+  process.stdout.write(`${genericHelp}
+`);
+  return EXIT.ok;
+}
+function renderCallActionHelp(entry) {
+  const short = entry.name.split(".").pop() ?? entry.name;
+  const schema = isRecord(entry.schema) ? entry.schema : {};
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []
+  );
+  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();
+  if (names.length === 0) {
+    lines.push("  Fields: (none)");
+  } else {
+    lines.push("  Fields (pass as <name>=<value> or --arg <name>=<value>):");
+    const width = Math.max(...names.map((name) => name.length));
+    for (const name of names) {
+      const prop = isRecord(properties[name]) ? properties[name] : {};
+      const type = typeof prop.type === "string" ? prop.type : "any";
+      const req = required.has(name) ? " (required)" : "";
+      const desc = typeof prop.description === "string" ? ` \u2014 ${prop.description}` : "";
+      const enumVals = Array.isArray(prop.enum) ? ` [one of: ${prop.enum.join(", ")}]` : "";
+      lines.push(`    ${name.padEnd(width)}  ${type}${req}${desc}${enumVals}`);
+    }
+  }
+  const examples = renderCallExamples(short, entry.examples);
+  if (examples.length > 0) {
+    lines.push("", "  Examples:");
+    for (const example of examples) lines.push(`    ${example}`);
+  }
+  return `${lines.join("\n")}
+
+`;
+}
+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;
+    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());
+  }
+  return out;
+}
 function parseCallArgs(argv) {
   const args = {};
   const rest = [];
@@ -171,10 +271,44 @@ function parseCallArgs(argv) {
       action = arg;
       continue;
     }
+    if (action !== void 0 && !isForwardedOptionValue(argv, i) && isArgPair(arg)) {
+      const eq = arg.indexOf("=");
+      args[arg.slice(0, eq)] = arg.slice(eq + 1);
+      continue;
+    }
     rest.push(arg);
   }
   return { action, args, rest };
 }
+function isArgPair(value) {
+  const eq = value.indexOf("=");
+  return eq > 0;
+}
+function isForwardedOptionValue(argv, index) {
+  if (index === 0) return false;
+  const previous = argv[index - 1];
+  if (!previous.startsWith("--") || previous.includes("=")) return false;
+  return VALUE_TAKING_CALL_FLAGS.has(normalizeFlagName(previous));
+}
+const VALUE_TAKING_CALL_FLAGS = /* @__PURE__ */ new Set([
+  "action-manifest",
+  "adapter",
+  "artifacts-dir",
+  "cdp-port",
+  "device",
+  "heal",
+  "library",
+  "metro-port",
+  "platform",
+  "project-root",
+  "slot",
+  "target",
+  "validation-runtime-dir",
+  "watcher-port"
+]);
+function normalizeFlagName(flag) {
+  return flag.replace(/^--/u, "");
+}
 function resolveActionName(shortName, names) {
   if (names.includes(shortName)) return { status: "ok", resolved: shortName, candidates: [shortName] };
   const finalSegment = (name) => name.split(".").pop() ?? name;
@@ -191,5 +325,6 @@ function pickCallExampleAction(names) {
   return names[0] ?? "command";
 }
 export {
-  handleCall
+  handleCall,
+  handleCallHelp
 };

package/dist/commands/device-target.js

@@ -111,9 +111,16 @@ function applyDeviceTargeting(command, adapter, options, opts) {
 ${formatConnectedDevices(connected2)}` : `  No devices are currently connected (adb devices / booted iOS simulators).`)
     };
   }
-  if (!opts.gate) return { ok: true };
   const connected = listConnectedDevices();
   const targetable = connected.filter(isTargetable);
+  const selectedTargetable = targetable.filter(deviceSelected);
+  if (selectedTargetable.length === 1) {
+    const selected = selectedTargetable[0];
+    if (selected.platform === "android") setAndroidDeviceEnv(selected.id, selected.name);
+    else setIosDeviceEnv(selected.id, selected.name);
+    return { ok: true };
+  }
+  if (!opts.gate) return { ok: true };
   if (targetable.length > 1) {
     return {
       ok: false,
@@ -121,8 +128,8 @@ ${formatConnectedDevices(connected2)}` : `  No devices are currently connected (
       message: `${targetable.length} mobile devices available \u2014 ${command} needs exactly one target.
   Connected devices:
 ${formatConnectedDevices(connected)}
-  Add --device <id> to disambiguate, e.g.:${targetable.map((d) => `
-    --device ${d.id}`).join("")}`
+` + (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("")}`)
     };
   }
   return { ok: true };

package/dist/commands/fixtures.js

@@ -39,13 +39,14 @@ async function handleFixtures(argv, deps) {
   if (!adapter) {
     return usageOut(json, "fixtures", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
+  const surface = getAdapterSurface(adapter);
+  surface.resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: false, rerun: "" });
   if ("code" in dtResult) {
     return usageOut(json, "fixtures", dtResult.message, "mm-harness fixtures set --adapter mobile --device <adb-serial|simulator-udid>");
   }
   if (sub === "generate") return fixturesGenerate(adapter, target, options, json);
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
-  const surface = getAdapterSurface(adapter);
   if (surface.headless) return usageOut(json, "fixtures", "core is headless; it has no wallet fixture.", surface.hints.launch);
   const canonicalFixture = walletFixturePath(target);
   const retryHint = `${surface.hints.relaunch}   # relaunch, then retry: mm-harness fixtures set`;

package/dist/commands/manifest.js

@@ -87,6 +87,8 @@ function describeManifestAction(name, kind, metadata) {
   };
 }
 export {
+  describeManifestActions,
+  fuzzyResolveActions,
   handleActions,
   handleManifest
 };

package/dist/commands/run-engine.js

@@ -18,6 +18,7 @@ import {
   runnerDir
 } from "../paths.js";
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
+import { listRecipeFiles } from "../recipe-files.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
 import { EXIT } from "./shared.js";
 import {
@@ -68,7 +69,15 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         recordVideo: useFramedExtensionRecording ? false : recordVideo,
         ...runtimeOptions.librarySources ? { librarySources: runtimeOptions.librarySources } : {}
       };
-      const result = await runner.run(runRequest);
+      let result;
+      try {
+        result = await runner.run(runRequest);
+      } finally {
+        if (adapter === "mobile") {
+          const { hideMobileHudOnTeardown } = await import("../adapters.js");
+          await hideMobileHudOnTeardown(projectRoot, recipeRunEnv(adapter, runtimeOptions));
+        }
+      }
       await stopRecipeRecording(recording, result);
       return result;
     } finally {
@@ -144,7 +153,7 @@ function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
   const direct = path.resolve(recipeArg);
   if (isRecipeFile(direct)) return { recipeFile: direct };
   if (!recipeArg.includes("/") && !recipeArg.includes(path.sep)) {
-    const candidates = [`${recipeArg}.${adapter}.recipe.json`, `${recipeArg}.recipe.json`, recipeArg];
+    const candidates = recipeNameCandidates(recipeArg, adapter);
     if (librarySources && librarySources.length > 0) {
       for (const source of librarySources) {
         for (const candidate of candidates) {
@@ -168,17 +177,75 @@ function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
 function libraryRecipeNames(adapter) {
   let entries;
   try {
-    entries = fs.readdirSync(recipePath(""));
+    entries = listRecipeFiles(recipePath(""));
   } catch {
     return [];
   }
   const scopes = ["mobile", "extension", "core"];
-  const names = entries.filter((f) => f.endsWith(".recipe.json")).map((f) => f.slice(0, -".recipe.json".length)).filter((n) => {
+  const names = entries.filter((f) => f.endsWith(".recipe.json")).map((f) => f.slice(0, -".recipe.json".length).replace(/[\\/]/gu, ".")).filter((n) => {
     const scope = n.split(".").pop() ?? "";
     return !scopes.includes(scope) || scope === adapter;
   }).map((n) => n.endsWith(`.${adapter}`) ? n.slice(0, -(adapter.length + 1)) : n);
   return [...new Set(names)].sort();
 }
+function recipeNameCandidates(recipeArg, adapter) {
+  const names = [recipeArg, ...LEGACY_RECIPE_ALIASES[recipeArg] ?? []];
+  const candidates = [];
+  for (const name of names) {
+    candidates.push(...singleRecipeNameCandidates(name, adapter));
+  }
+  return [...new Set(candidates)];
+}
+function singleRecipeNameCandidates(name, adapter) {
+  if (name.endsWith(".recipe.json")) {
+    return uniqueStrings([domainPathForRecipeFile(name), name]);
+  }
+  const bases = uniqueStrings([domainPathForRecipeName(name), name]);
+  const candidates = [];
+  for (const base of bases) {
+    candidates.push(`${base}.${adapter}.recipe.json`, `${base}.recipe.json`, base);
+  }
+  return candidates;
+}
+function domainPathForRecipeFile(name) {
+  const suffix = ".recipe.json";
+  const base = name.slice(0, -suffix.length);
+  return `${domainPathForRecipeName(base)}${suffix}`;
+}
+function domainPathForRecipeName(name) {
+  if (name.includes("/") || name.includes(path.sep)) return name;
+  const dot = name.indexOf(".");
+  return dot > 0 ? `${name.slice(0, dot)}/${name.slice(dot + 1)}` : name;
+}
+function uniqueStrings(values) {
+  return [...new Set(values)];
+}
+const LEGACY_RECIPE_ALIASES = {
+  "action-validation": ["runner.action-validation"],
+  "action-validation.extension.recipe.json": ["runner.action-validation.extension.recipe.json"],
+  "action-validation.mobile.recipe.json": ["runner.action-validation.mobile.recipe.json"],
+  "app-lifecycle-android-smoke": ["app.lifecycle.android-smoke"],
+  "app-lifecycle-android-smoke.mobile.recipe.json": ["app.lifecycle.android-smoke.mobile.recipe.json"],
+  "order-lifecycle": ["perps.order-lifecycle"],
+  "order-lifecycle.core.recipe.json": ["perps.order-lifecycle.core.recipe.json"],
+  "perps-lifecycle": ["perps.lifecycle"],
+  "perps-lifecycle.recipe.json": ["perps.lifecycle.recipe.json"],
+  "perps-performance": ["perps.performance"],
+  "perps-performance-background-resume": ["perps.performance.background-resume"],
+  "perps-performance-background-resume.mobile.recipe.json": ["perps.performance.background-resume.mobile.recipe.json"],
+  "perps-performance-cold-start": ["perps.performance.cold-start"],
+  "perps-performance-cold-start.mobile.recipe.json": ["perps.performance.cold-start.mobile.recipe.json"],
+  "perps-performance-warm-start": ["perps.performance.warm-start"],
+  "perps-performance-warm-start.mobile.recipe.json": ["perps.performance.warm-start.mobile.recipe.json"],
+  "perps-performance.mobile.recipe.json": ["perps.performance.mobile.recipe.json"],
+  "read-markets": ["perps.read-markets"],
+  "read-markets.core.recipe.json": ["perps.read-markets.core.recipe.json"],
+  "smoke": ["runner.smoke"],
+  "smoke.extension.recipe.json": ["runner.smoke.extension.recipe.json"],
+  "smoke.mobile.recipe.json": ["runner.smoke.mobile.recipe.json"],
+  "trading-lifecycle": ["perps.trading-lifecycle"],
+  "trading-lifecycle.core.recipe.json": ["perps.trading-lifecycle.core.recipe.json"]
+};
 async function validateRunRecipeStatic(recipeArg, adapter, options) {
   const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
   const resolved = resolveRunRecipeArg(recipeArg, adapter, librarySources);

package/dist/commands/run.js

@@ -20,6 +20,7 @@ import {
 } from "./run-engine.js";
 import { handleListExecutables } from "./list-executables.js";
 import { applyDeviceTargeting } from "./device-target.js";
+import { getAdapterSurface } from "../adapters/surface.js";
 async function handleRun({ positional, options }) {
   if (optionFlag(options, "list")) return handleListExecutables("run", options);
   const targetRecipe = positional[0];
@@ -27,6 +28,7 @@ async function handleRun({ positional, options }) {
   if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
   const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
+  getAdapterSurface(adapter).resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("run", adapter, options, { gate: true, rerun: "" });
   if ("code" in dtResult) {
     return emitRunUsageError(json, adapter, targetRecipe, dtResult.code, dtResult.message);

package/dist/commands/self-test.js

@@ -26,7 +26,7 @@ async function runSelfTest(options) {
       const manifest = loadActionManifest(adapter);
       const manifestValidation = await validateManifest(manifest);
       const smokeRecipe = recipePath(
-        adapter === "mobile" ? "smoke.mobile.recipe.json" : "smoke.extension.recipe.json"
+        adapter === "mobile" ? "runner/smoke.mobile.recipe.json" : "runner/smoke.extension.recipe.json"
       );
       const artifactsDir = path.join(root, adapter);
       const result = await runRecipe(adapter, smokeRecipe, artifactsDir, runnerDir, void 0, {

package/dist/commands/status.js

@@ -16,8 +16,10 @@ async function handleStatus({ options }) {
     return usageOut(json, "status", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   assertAdapter(adapter);
-  const devices = adapter === "mobile" ? listConnectedDevices().map((device) => ({ ...device, selected: deviceSelected(device) })) : [];
-  const next = getAdapterSurface(adapter).hints.relaunch;
+  const surface = getAdapterSurface(adapter);
+  surface.resolveSlotPorts(target);
+  const next = surface.hints.relaunch;
+  const devices = adapter === "mobile" ? slotScopedDevices(listConnectedDevices()) : [];
   if (json) {
     const doProbe = !fast && adapter === "mobile" && devices.length > 0;
     if (doProbe) {
@@ -25,7 +27,7 @@ async function handleStatus({ options }) {
       const devicesWithLive = devices.map((d) => mergeDeviceLive(d, liveMap.get(d.id)));
       console.log(
         JSON.stringify(
-          { schemaVersion: 1, command: "status", adapter, target, devices: devicesWithLive, next },
+          { schemaVersion: 1, command: "status", adapter, target, devices: devicesWithLive, next: nextForLive(next, liveMap) },
           null,
           2
         )
@@ -40,13 +42,26 @@ async function handleStatus({ options }) {
   const out = (style, text) => color(style, text, { stream: process.stdout });
   console.log(`${out("label", "status")} ${out("bold", adapter)} ${out("dim", target)}`);
   if (adapter === "mobile") renderDeviceList(devices, out);
-  console.log(`${out("label", "Next:")} ${out("cmd", next)}`);
   if (!fast && adapter === "mobile" && devices.length > 0) {
     const liveMap = await probeMobileLiveState(target, devices);
     renderLiveBlock(devices, liveMap, out);
+    console.log(`${out("label", "Next:")} ${out("cmd", nextForLive(next, liveMap))}`);
+  } else {
+    console.log(`${out("label", "Next:")} ${out("cmd", next)}`);
   }
   return EXIT.ok;
 }
+function nextForLive(fallback, liveMap) {
+  for (const live of liveMap.values()) {
+    if (live.liveState === void 0) return "mm-harness logs";
+  }
+  return fallback;
+}
+function slotScopedDevices(devices) {
+  const withSelection = devices.map((device) => ({ ...device, selected: deviceSelected(device) }));
+  const selected = withSelection.filter((device) => device.selected);
+  return selected.length > 0 ? selected : withSelection;
+}
 function mergeDeviceLive(device, live) {
   if (!live) return device;
   return {

package/dist/mm-harness-cli.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { color } from "./cli-color.js";
 import { handleUpdate, maybeNudge } from "./commands/update.js";
+import { handleCallHelp } from "./commands/call.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 globalThis.__MM_HARNESS_WRAPPER__ = true;
 const { main: recipeMain } = await import("./cli.js");
@@ -89,15 +90,16 @@ Example:
     name: "call",
     summary: "Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).",
     example: "mm-harness call ensure_unlocked",
-    helpText: `mm-harness call <action> [--arg k=v ...] [flags]
+    helpText: `mm-harness call <action> [key=value ...] [--arg k=v ...] [flags]
 
   Run one action in isolation as a one-node recipe through the real engine path.
   Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
-  if unique; ambiguous = exit 2. Actions differ per adapter \u2014 list this checkout's
-  with: mm-harness actions.
+  if unique; ambiguous = exit 2. Pass action fields as key=value shorthand or
+  with --arg k=v. Actions differ per adapter \u2014 list this checkout's with:
+  mm-harness actions.
 
   --list                             List everything invocable for the adapter (actions + flows); no <action> needed
-  --arg k=v                          Action field value (repeatable)
+  --arg k=v                          Action field value (repeatable; equivalent to key=value shorthand)
   --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). Without it, >1 connected mobile device fails fast and lists them.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
@@ -109,7 +111,8 @@ Example:
 
 Example (real actions; run mm-harness actions for this checkout's full set):
   mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
-  mm-harness call command --arg cmd="echo hi" --adapter core   # the universal action (all adapters)`
+  mm-harness call navigate page=perps --adapter mobile
+  mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)`
   },
   {
     name: "flows",
@@ -614,6 +617,13 @@ function hasPassthroughHelp(argv) {
   if (divider === -1) return false;
   return argv.slice(divider + 1).some((arg) => arg === "-h" || arg === "--help");
 }
+function isCallActionHelp(argv) {
+  if (argv[0] !== "call") return false;
+  if (!argv[1] || argv[1].startsWith("-")) return false;
+  const divider = argv.indexOf("--");
+  const scope = divider === -1 ? argv : argv.slice(0, divider);
+  return scope.includes("--help") || scope.includes("-h");
+}
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
@@ -621,4 +631,8 @@ if (rawArgv.length === 0) {
 if (hasPassthroughHelp(rawArgv)) {
   process.exit(await delegate(rawArgv));
 }
+if (isCallActionHelp(rawArgv)) {
+  const callHelp = REAL.find((command) => command.name === "call")?.helpText ?? "";
+  process.exit(await handleCallHelp(rawArgv.slice(1), callHelp));
+}
 await program.parseAsync(process.argv);

package/dist/recipe-files.js

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+import path from "node:path";
+function listRecipeFiles(root, base = "") {
+  const out = [];
+  for (const entry of fs.readdirSync(path.join(root, base), { withFileTypes: true })) {
+    const rel = path.join(base, entry.name);
+    if (entry.isDirectory()) out.push(...listRecipeFiles(root, rel));
+    else if (entry.isFile() && entry.name.endsWith(".recipe.json")) out.push(rel);
+  }
+  return out;
+}
+export {
+  listRecipeFiles
+};

package/docs/architecture.md

@@ -216,7 +216,7 @@ describes **how an agent should work**, it belongs in skills.
 | `adapters/extension/` | Runner-owned Extension launch/live/watch/windows/wallet-state/readiness helpers (orchestration) and verify (recipe) copied into installed harnesses. |
 | `adapters/shared/path-defaults.json` | Single source for default `recipeHarnessRoot` and `recipeRuntimeDir`. |
 | `adapters/shared/harness-path.sh`, `src/paths.ts` | Shell and TypeScript accessors for those defaults plus validation. |
-| `library/recipes/` | Reusable smoke/action-validation recipes only. Task-specific proof recipes stay task-local. |
+| `library/recipes/` | Reusable smoke/runner.action-validation recipes only. Task-specific proof recipes stay task-local. |
 | `library/library.json`, `library/flows/` | Canonical recipe library: minimal, stable flows recipes can `call`. Personal/team libraries shadow it by default — see [Recipe Libraries](recipe-libraries.md). |
 | `docs/` | Runner architecture, contracts, and operational conventions. |
 
@@ -377,7 +377,7 @@ TypeScript or a focused `.mjs` adapter and keep shell as the launcher.
 5. Use official `ui.*` actions and screenshot claims for visible acceptance
    criteria; do not add task-specific `metamask.*` actions for exact copy,
    styling, ticket IDs, or one-off selectors.
-6. Update smoke/action-validation recipes only when the capability is reusable.
+6. Update smoke/runner.action-validation recipes only when the capability is reusable.
 
 ## Standalone use first; farm later
 

package/docs/live-adapter-contract.md

@@ -85,7 +85,7 @@ domain capability useful across many tasks, such as `metamask.perps.start_state`
 `metamask.perps.place_order`, `metamask.perps.close_positions`, or
 `metamask.perps.assert_positions`.
 
-`ui.scroll` is part of the current executable contract and action-validation must
+`ui.scroll` is part of the current executable contract and runner.action-validation must
 prove both normal scrolling and `scroll_into_view` before screenshot capture.
 `ui.gesture` is intentionally not advertised yet; drag/swipe proof must wait
 until the shared runtime and this runner expose and validate that action on both

package/docs/recipe-libraries.md

@@ -101,19 +101,20 @@ each user-visible step takes. The runner has no benchmark verb: timings are just
 the per-node `duration`s in a passing run's `trace.json`, so a flow is comparable
 across runs only when you pin the run (same device, healing off) and keep the node
 graph stable. The repo ships one canonical example,
-`library/recipes/perps-performance.mobile.recipe.json` — unlock → open the Perps
+`library/recipes/perps/performance.mobile.recipe.json` — unlock → open the Perps
 market list → read live state → open a market detail. This walkthrough copies it
 into a library of your own and retargets it to your journey. A peer engineer can
-follow it verbatim; the same steps run as the `perps-performance-recipe` contract
+follow it verbatim; the same steps run as the `perps.performance-recipe` contract
 test.
 
 ### 1. Scaffold a personal library
 
 A library is a directory with a `library.json` marker. Keep reusable `flows/`
-(referenced via `call`) beside a `recipes/` folder for the full flows you run:
+(referenced via `call`) beside a domain-grouped `recipes/` folder for the full
+flows you run:
 
 ```bash
-mkdir -p ~/my-recipes/flows ~/my-recipes/recipes
+mkdir -p ~/my-recipes/flows ~/my-recipes/recipes/my-perps
 cat > ~/my-recipes/library.json <<'JSON'
 { "kind": "recipe-library", "schema_version": 1, "name": "mydev", "owner": "mydev" }
 JSON
@@ -130,8 +131,8 @@ it works headlessly (CI, a scratch checkout) and so the path is unambiguous.
 Copy it out of your runner checkout's `library/recipes/`:
 
 ```bash
-cp library/recipes/perps-performance.mobile.recipe.json \
-   ~/my-recipes/recipes/my-perps-performance.mobile.recipe.json
+cp library/recipes/perps/performance.mobile.recipe.json \
+   ~/my-recipes/recipes/my-perps/performance.mobile.recipe.json
 ```
 
 ### 3. Edit the nodes to your journey
@@ -211,33 +212,35 @@ field on flow catalog entries — not yet in the protocol.
 
 ### 4. Run it and read the timings
 
-Validate statically **by name** first — `run` probes each library source's `recipes/`
-directory in precedence order (personal → team → canonical), so `my-perps-performance`
-resolves from `~/my-recipes/recipes/` without you spelling out the path:
+Validate statically **by name** first — `run` probes each library source's
+`recipes/` directory in precedence order (personal → team → canonical), so
+`my-perps.performance` resolves from
+`~/my-recipes/recipes/my-perps/performance.mobile.recipe.json` without you
+spelling out the path:
 
 ```bash
 # Static validation by NAME — resolves from the personal library via --library.
-mm-harness run my-perps-performance \
+mm-harness run my-perps.performance \
   --library mydev=~/my-recipes --plan --adapter mobile
 
 # Zero-flag personal-library: when ~/my-recipes is placed at
 # $FARMSLOT_HOME/recipe-library (default ~/.farmslot/recipe-library), the runner
 # discovers it automatically and run-by-name works without --library:
-mm-harness run my-perps-performance --plan --adapter mobile
+mm-harness run my-perps.performance --plan --adapter mobile
 
 # Pinned live run — same device, healing OFF, so durations are comparable.
-mm-harness run my-perps-performance \
+mm-harness run my-perps.performance \
   --library mydev=~/my-recipes \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts
 
 # Canonical start-state variants — same installed app, no rebuild.
-mm-harness run app-lifecycle-android-smoke \
+mm-harness run app.lifecycle.android-smoke \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/lifecycle-smoke
-mm-harness run perps-performance-warm-start \
+mm-harness run perps.performance.warm-start \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/warm
-mm-harness run perps-performance-background-resume \
+mm-harness run perps.performance.background-resume \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/background
-mm-harness run perps-performance-cold-start \
+mm-harness run perps.performance.cold-start \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/cold
 
 # Per-node durations to diff across runs (trace.json is an array of entries, or
@@ -249,7 +252,7 @@ node -e 'const t=require("./artifacts/trace.json"); \
 A miss with `--library` names the sources that were searched, so you can tell at a
 glance whether a typo or a missing library entry caused the failure.
 
-Run `app-lifecycle-android-smoke` first when validating a new Android slot; it
+Run `app.lifecycle.android-smoke` first when validating a new Android slot; it
 isolates lifecycle control from wallet setup and Perps navigation. The start-state
 variants use the standard outer `app.lifecycle` action. Every
 variant begins with `app.status` so `trace.json` records an idempotent start
@@ -294,5 +297,5 @@ mm-harness run my-perps-with-segment --plan --adapter mobile \
 ```
 
 That resolution — unresolved without the source, `pass` with it — is what the
-`perps-performance-recipe` contract test asserts, alongside the canonical recipe
+`perps.performance-recipe` contract test asserts, alongside the canonical recipe
 resolving by name and the personal mobile copy planning by path and basename.