@deeeed/metamask-harness 0.15.2 → 0.17.0

package/dist/commands/launch/index.js

@@ -15,7 +15,8 @@ import {
   spawnScript,
   str,
   targetOf,
-  usageOut
+  usageOut,
+  writeInteractiveProgress
 } from "../shared.js";
 import {
   RECOVERY_CODE,
@@ -33,6 +34,7 @@ import {
 import { launchMobile } from "./mobile.js";
 import { applyDeviceTargeting } from "../device-target.js";
 import { acquireCheckoutLock } from "../../checkout-lock.js";
+import { JsonStreamWriter } from "../../json-stream.js";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
   "watch",
@@ -40,30 +42,58 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "sidepanel",
   "fullscreen",
   "runway",
-  "json"
+  "json",
+  "jsonStream"
 ]);
 const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
 async function handleLaunch(argv) {
   const { options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
+  const stream = new JsonStreamWriter("launch", flag(options, "jsonStream"));
+  const jsonOutput = json && !stream.enabled;
+  const restoreStdout = stream.isolateStdout();
   const target = targetOf(options);
-  if (!fs.existsSync(target)) return handleLaunchLocked(argv);
-  const lock = acquireCheckoutLock(target, "launch");
-  if ("message" in lock) {
-    return checkoutBusyOut(json, "launch", lock.message, lock.path);
-  }
   try {
-    return await handleLaunchLocked(argv);
+    let exitCode;
+    if (!fs.existsSync(target)) {
+      exitCode = await handleLaunchLocked(argv, stream);
+    } else {
+      const lock = acquireCheckoutLock(target, "launch");
+      if ("message" in lock) {
+        const userAction = `wait for the current owner, or inspect ${lock.path} if its process has exited`;
+        stream.error({ code: "SANDBOX_BUSY", message: lock.message, userAction });
+        exitCode = checkoutBusyOut(jsonOutput, "launch", lock.message, lock.path);
+      } else {
+        try {
+          exitCode = await handleLaunchLocked(argv, stream);
+        } finally {
+          lock.release();
+        }
+      }
+    }
+    stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode);
+    return exitCode;
+  } catch (error) {
+    const exitCode = error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : EXIT.runtime;
+    stream.error({
+      code: exitCode === EXIT.usage ? "CLI_USAGE_ERROR" : "LAUNCH_FAILED",
+      message: error instanceof Error ? error.message : String(error),
+      userAction: `mm-harness doctor --target ${shellQuote(target)} --json`
+    });
+    stream.complete("fail", exitCode);
+    throw error;
   } finally {
-    lock.release();
+    restoreStdout();
   }
 }
-async function handleLaunchLocked(argv) {
+async function handleLaunchLocked(argv, stream) {
   const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
+  const jsonOutput = json && !stream.enabled;
+  const machine = json || stream.enabled;
   const target = targetOf(options);
   const heal = parseHeal(options, "auto");
-  if (typeof heal !== "string") return usageOut(json, "launch", heal.error, "use --heal off|infra-only|auto");
+  if (typeof heal !== "string") return launchUsage(jsonOutput, stream, heal.error, "use --heal off|infra-only|auto");
   const posToken = positional[0];
   const mobileTargetToken = posToken === "ios" || posToken === "android" ? posToken : void 0;
   const platformFlag = str(options, "platform");
@@ -72,15 +102,16 @@ async function handleLaunchLocked(argv) {
   const adapterHint = mobileTarget ? "mobile" : void 0;
   const adapter = resolveAdapter(options, target, adapterHint);
   if (!adapter) {
-    return usageOut(json, "launch", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+    return launchUsage(jsonOutput, stream, `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
+  stream.phase("resolve", { target, adapter, platform: mobileTarget ?? null });
   if (adapter === "core") {
-    return usageOut(json, "launch", "core is headless; there is nothing to launch.", "mm-harness verify");
+    return launchUsage(jsonOutput, stream, "core is headless; there is nothing to launch.", "mm-harness verify");
   }
   if (adapter === "mobile" && !mobileTarget) {
-    return usageOut(
-      json,
-      "launch",
+    return launchUsage(
+      jsonOutput,
+      stream,
       "target is required for mobile.",
       "mm-harness launch ios   or   mm-harness launch android"
     );
@@ -90,15 +121,15 @@ async function handleLaunchLocked(argv) {
   const wantWatch = flag(options, "watch");
   const wantRunway = flag(options, "runway");
   if (wantRunway && adapter !== "mobile") {
-    return usageOut(json, "launch", "runway is mobile-only.", "drop --runway for the extension");
+    return launchUsage(jsonOutput, stream, "runway is mobile-only.", "drop --runway for the extension");
   }
   const displayMode = flag(options, "sidepanel") && !flag(options, "fullscreen") ? "sidepanel" : "fullscreen";
   for (const portFlag of ["cdpPort", "watcherPort"]) {
     const value = str(options, portFlag);
     if (value !== void 0 && !/^\d+$/u.test(value)) {
-      return usageOut(
-        json,
-        "launch",
+      return launchUsage(
+        jsonOutput,
+        stream,
         `--${portFlag === "cdpPort" ? "cdp-port" : "watcher-port"} must be numeric (got: ${value}).`,
         `pass a numeric port, e.g. --${portFlag === "cdpPort" ? "cdp-port 6663" : "watcher-port 8081"}`
       );
@@ -106,7 +137,7 @@ async function handleLaunchLocked(argv) {
   }
   const envResult = applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
   if (envResult && "code" in envResult) {
-    return usageOut(json, "launch", envResult.message, "mm-harness launch android --device <adb-serial|device-name>");
+    return launchUsage(jsonOutput, stream, envResult.message, envResult.userAction);
   }
   const tier = wantBuild ? "build" : "quick";
   if (adapter === "extension") {
@@ -115,44 +146,55 @@ async function handleLaunchLocked(argv) {
       process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
     }
   }
-  if (!json && adapter === "extension") {
+  if (!machine && adapter === "extension") {
     const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
     const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
     console.error(
       `\u2192 extension launch \u2014 ${modeNote} \xB7 CDP :${process.env.CDP_PORT ?? "default"} \xB7 ${workNote}`
     );
   }
+  if (adapter === "mobile") {
+    const device = str(options, "device") ?? (mobileTarget === "android" ? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL : process.env.IOS_SIMULATOR ?? process.env.SIM_UDID) ?? "configured device";
+    const watcherPort = str(options, "watcherPort") ?? process.env.WATCHER_PORT ?? "auto";
+    writeInteractiveProgress(
+      machine,
+      `\u2192 mobile launch \u2014 ${mobileTarget} \xB7 ${tier === "build" ? "native build" : "quick readiness"} \xB7 ${device} \xB7 Metro ${watcherPort === "auto" ? "auto" : `:${watcherPort}`}`
+    );
+  }
   const state = newHealState();
   if (tier === "quick" && nativeInputsChanged(target, adapter)) {
-    return usageOut(
-      json,
-      "launch",
+    return launchUsage(
+      jsonOutput,
+      stream,
       "native build inputs changed since last build.",
       `mm-harness launch ${adapter === "mobile" ? `${mobileTarget} ` : ""}--build`
     );
   }
-  const ensured = await ensureOverlay(adapter, target, heal, state, json);
+  stream.phase("install");
+  const ensured = await ensureOverlay(adapter, target, heal, state, machine);
   if (!ensured.ok) {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "OVERLAY_INSTALL_FAILED",
       message: ensured.error ?? "overlay install failed",
       recoverable: false,
       exitCode: EXIT.infra
     });
   }
+  stream.phase("healthcheck");
   if (adapter === "extension") {
     const willBuild = wantWatch || tier === "build" || !await extensionRuntimeReusable(target);
     if (willBuild) {
       const depsBlock = extensionDepsBlock(target);
       if (depsBlock) {
         if (heal === "off") {
-          return usageOut(json, "launch", depsBlock.message, depsBlock.userAction);
+          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(json, adapter, mobileTarget, tier, state, {
+          return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
             code: "DEPENDENCY_INSTALL_FAILED",
             message: depsBlock.message,
             recoverable: false,
@@ -166,12 +208,13 @@ async function handleLaunchLocked(argv) {
       }
     }
   }
-  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
+  stream.phase("launch");
+  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, machine, displayMode);
   if (attempt.status === 0) {
-    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+    return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
   }
   if (heal === "off") {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "LAUNCH_FAILED",
       message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed (healing off)`,
       recoverable: false,
@@ -181,12 +224,13 @@ async function handleLaunchLocked(argv) {
   if (adapter === "extension" && tier === "quick" && extensionQuickReattachFailed(attempt.output)) {
     const recoveryCode2 = "chrome.relaunched";
     state.attemptedRecoveries.push(recoveryCode2);
-    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, json, displayMode);
+    stream.phase("recover");
+    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode);
     if (rebuildAttempt.status === 0) {
       state.recovered.push(recoveryCode2);
-      return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+      return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
     }
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "EXTENSION_RELAUNCH_FAILED",
       message: "quick reattach failed, and clean relaunch failed too.",
       recoverable: false,
@@ -195,7 +239,7 @@ async function handleLaunchLocked(argv) {
     });
   }
   if (adapter === "mobile" && mobileProvisioningBlocked(attempt.output)) {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "MOBILE_PROVISION_REQUIRED",
       message: `mobile ${mobileTarget ?? "runtime"} is not provisioned for this slot.`,
       recoverable: false,
@@ -206,7 +250,7 @@ async function handleLaunchLocked(argv) {
   }
   const bound = checkHealBounds(target, attempt.output, state);
   if (bound !== null) {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: bound.code,
       message: bound.message,
       recoverable: false,
@@ -217,12 +261,13 @@ async function handleLaunchLocked(argv) {
   }
   const recoveryCode = RECOVERY_CODE[adapter];
   state.attemptedRecoveries.push(recoveryCode);
-  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
+  stream.phase("recover");
+  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, machine, displayMode);
   if (attempt.status === 0) {
     state.recovered.push(recoveryCode);
-    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+    return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
   }
-  return launchFail(json, adapter, mobileTarget, tier, state, {
+  return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
     code: "SAME_RECOVERY_TWICE",
     message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed again after ${recoveryCode} recovery \u2014 refusing to loop.`,
     recoverable: false,
@@ -275,14 +320,16 @@ function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
       return {
         ok: false,
         code: "DEVICE_WRONG_PLATFORM",
-        message: `--device ${device} did not resolve to an Android device for launch android.`
+        message: `--device ${device} did not resolve to an Android device for launch android.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
       };
     }
     if (mobileTarget === "ios" && device && !process.env.IOS_SIMULATOR) {
       return {
         ok: false,
         code: "DEVICE_WRONG_PLATFORM",
-        message: `--device ${device} did not resolve to an iOS simulator for launch ios.`
+        message: `--device ${device} did not resolve to an iOS simulator for launch ios.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
       };
     }
   }
@@ -328,26 +375,29 @@ async function executeComposition(adapter, mobileTarget, tier, wantWatch, target
   }
   return launchExtension(target, tier, wantWatch, displayMode);
 }
-async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true) {
+async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true) {
   if (adapter === "extension" && displayMode === "sidepanel") {
     const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
     const sidepanelArgs = ["open"];
     if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
-    if (!json) {
+    if (!machine) {
       console.error(
         `[sidepanel] opening panel beside ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}`
       );
     }
-    const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, json, { REPO: target });
+    const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
     if (sidepanel.status !== 0) {
       const recoveryCode = "chrome.relaunched";
       if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
         state.attemptedRecoveries.push(recoveryCode);
-        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, json, displayMode);
+        stream.phase("recover");
+        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode);
         if (rebuildAttempt.status === 0) {
           state.recovered.push(recoveryCode);
           return await finishLaunch(
-            json,
+            jsonOutput,
+            machine,
+            stream,
             adapter,
             mobileTarget,
             tier,
@@ -359,7 +409,7 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
             false
           );
         }
-        return launchFail(json, adapter, mobileTarget, tier, state, {
+        return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
           code: "EXTENSION_RELAUNCH_FAILED",
           message: "sidepanel open found a blocked extension runtime, and clean relaunch failed too.",
           recoverable: false,
@@ -367,7 +417,7 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
           originalError: rebuildAttempt.output.trim() || void 0
         });
       }
-      return launchFail(json, adapter, mobileTarget, tier, state, {
+      return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
         code: "SIDEPANEL_OPEN_FAILED",
         message: "app launched but opening the side panel failed.",
         recoverable: false,
@@ -378,15 +428,38 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
     }
   }
   if (wantVerify) {
+    stream.phase("verify");
     const verifyArgs = ["verify", "--adapter", adapter, "--target", target];
     if (adapter === "mobile" && mobileTarget) verifyArgs.push("--platform", mobileTarget);
-    if (json) verifyArgs.push("--json");
-    return handleHarness(verifyArgs);
+    if (machine) verifyArgs.push("--json");
+    const exitCode = await handleHarness(verifyArgs);
+    if (stream.enabled) {
+      for (const mutation of state.mutations) stream.mutation(mutation);
+      for (const recovery of state.recovered) stream.recovery(recovery);
+      stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode, {
+        adapter,
+        platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
+        tier,
+        recovered: state.recovered,
+        mutations: state.mutations
+      });
+    }
+    return exitCode;
   }
-  return launchPass(json, adapter, mobileTarget, tier, displayMode, state);
+  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, state);
 }
-function launchPass(json, adapter, mobileTarget, tier, displayMode, state) {
-  if (json) {
+function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, state) {
+  if (stream.enabled) {
+    for (const mutation of state.mutations) stream.mutation(mutation);
+    for (const recovery of state.recovered) stream.recovery(recovery);
+    stream.complete("pass", EXIT.ok, {
+      adapter,
+      platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
+      tier,
+      recovered: state.recovered,
+      mutations: state.mutations
+    });
+  } else if (json) {
     console.log(
       JSON.stringify(
         {
@@ -424,8 +497,32 @@ function launchDeviceLabel(mobileTarget) {
   }
   return process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || "booted device";
 }
-function launchFail(json, adapter, mobileTarget, tier, state, failure) {
-  if (json) {
+function launchUsage(json, stream, message, userAction) {
+  stream.error({ code: "USAGE", message, userAction });
+  return usageOut(json, "launch", message, userAction);
+}
+function launchFail(json, stream, adapter, mobileTarget, tier, state, target, failure) {
+  const userAction = failure.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+  if (stream.enabled) {
+    for (const mutation of state.mutations) stream.mutation(mutation);
+    for (const recovery of state.recovered) stream.recovery(recovery);
+    stream.error({
+      code: failure.code,
+      message: failure.message,
+      retryable: failure.recoverable,
+      userAction,
+      originalError: failure.originalError ?? null
+    });
+    stream.complete("fail", failure.exitCode, {
+      adapter,
+      platform: mobileTarget ?? null,
+      tier,
+      recovered: state.recovered,
+      mutations: state.mutations,
+      recoverable: failure.recoverable,
+      attemptedRecoveries: state.attemptedRecoveries
+    });
+  } else if (json) {
     console.log(
       JSON.stringify(
         {
@@ -445,7 +542,7 @@ function launchFail(json, adapter, mobileTarget, tier, state, failure) {
             code: failure.code,
             message: failure.message,
             retryable: failure.recoverable,
-            userAction: failure.userAction ?? null,
+            userAction,
             originalError: failure.originalError ?? null
           }
         },
@@ -458,8 +555,8 @@ function launchFail(json, adapter, mobileTarget, tier, state, failure) {
       `\u2717 launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed
   ${failure.message}` + (failure.originalError ? `
   --- original failure ---
-${failure.originalError}` : "") + (failure.userAction ? `
-  Next: ${failure.userAction}` : "")
+${failure.originalError}` : "") + `
+  Next: ${userAction}`
     );
   }
   return failure.exitCode;

package/dist/commands/manifest.js

@@ -16,42 +16,125 @@ async function handleManifest({ options }) {
   else console.log(actionManifestPath);
   return 0;
 }
-async function handleActions({ options }) {
+async function handleActions({ options, positional }) {
   const { adapter } = resolveAdapter(options);
   const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
   await validateManifest(manifest);
   const json = optionFlag(options, "json");
   const action = optionString(options, "action");
+  const query = positional[0]?.trim();
+  const category = optionString(options, "category")?.toLowerCase();
+  const categoriesOnly = optionFlag(options, "categories");
   const all = describeManifestActions(manifest);
-  const actions = action ? fuzzyResolveActions(all, action) : all;
+  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 ? { 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}` : ""}`);
     }
+    if (relatedActions) console.log(`Related: ${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 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) {
   const manifestRecord = isRecord(manifest) ? manifest : {};
@@ -80,15 +163,70 @@ function describeManifestAction(name, kind, metadata) {
   return {
     name,
     kind,
+    category: actionCategory(name, record.category),
     description: typeof record.description === "string" ? record.description : "",
     fields: properties,
     schema,
     examples: record.examples
   };
 }
+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
+  handleManifest,
+  searchActions,
+  summarizeActionCategories
 };

package/dist/commands/parse-args.js

@@ -19,12 +19,14 @@ function parseArgs(argv, command) {
   const options = {};
   const booleanOptions = /* @__PURE__ */ new Set([
     "json",
+    "jsonStream",
     "launchExistingDist",
     "startWatch",
     "record",
     "plan",
     "list",
     "raw",
+    "categories",
     "fix",
     "force",
     "resolveOnly",