@deeeed/metamask-harness 0.16.0 → 0.17.1

package/dist/adapters/extension/surface.js

@@ -65,11 +65,12 @@ const extensionSurface = {
     return [
       { label: "webpack", path: recipeRuntimePath(target, "webpack.log") },
       { label: "watcher", path: recipeRuntimePath(target, "recipe-harness-webpack.log") },
-      { label: "rebuild", path: recipeRuntimePath(target, "rebuild.log") }
+      { label: "rebuild", path: recipeRuntimePath(target, "rebuild.log") },
+      { label: "dapp", path: recipeRuntimePath(target, "dapp-console.log") }
     ];
   },
   appLogSource(target) {
-    return { label: "app", path: recipeRuntimePath(target, "extension-console.log") };
+    return { label: "extension", path: recipeRuntimePath(target, "extension-console.log") };
   },
   hints: {
     launch: "mm-harness launch",

package/dist/adapters/mobile/prepare.js

@@ -56,14 +56,21 @@ async function prepareMobile(target, opts = {}) {
       json,
       preflightMode
     );
-    if (confirm.status === 0) return { status: 0, output: "" };
+    if (confirm.status === 0) return startMobileConsoleForwarder(target, json);
     if (!json) {
       process.stderr.write(
         `launch: runtime looked ready but no ${platform} bridge target answered; launching the app.
 `
       );
     }
-    return dispatchActionSequence(launchActions(path.resolve(target)), target, platform, json, preflightMode);
+    const launch = await dispatchActionSequence(
+      launchActions(path.resolve(target)),
+      target,
+      platform,
+      json,
+      preflightMode
+    );
+    return launch.status === 0 ? startMobileConsoleForwarder(target, json) : launch;
   }
   if (report.decision === "unknown") {
     const msg = "mobile prepare: runtime state unknown\n  Next: run mm-harness verify --adapter mobile --target <checkout>";
@@ -111,7 +118,15 @@ async function prepareMobile(target, opts = {}) {
       }
     }
   }
-  return { status: 0, output: "" };
+  return startMobileConsoleForwarder(target, json);
+}
+function startMobileConsoleForwarder(target, json) {
+  return dispatchAction(
+    { id: "start-console-forwarder", cwd: target, argv: json ? ["--quiet"] : [] },
+    target,
+    "ios",
+    json
+  );
 }
 async function dispatchActionSequence(requestedActions, target, platform, json, preflightMode) {
   const resolved = path.resolve(target);
@@ -147,6 +162,10 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
       const extra = action.argv ?? [];
       return spawnScriptStreaming(leaf, ["--target", cwd, ...extra], target);
     }
+    case "start-console-forwarder": {
+      const leaf = path.join(runnerDir, "adapters/mobile/start-console-forwarder.sh");
+      return spawnScriptStreaming(leaf, ["--target", cwd, ...action.argv ?? []], target);
+    }
     case "prewarm-bundle": {
       const leaf = path.join(runnerDir, "adapters/mobile/prewarm-bundle.sh");
       return spawnScriptStreaming(leaf, ["--platform", platform, "--target", cwd], target);
@@ -156,10 +175,6 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
       const extra = action.argv ?? [];
       return spawnScriptStreaming(leaf, ["--target", cwd, "--platform", platform, ...extra], target);
     }
-    case "clear-metro-cache": {
-      const leaf = path.join(runnerDir, "adapters/mobile/start-metro.sh");
-      return spawnScriptStreaming(leaf, ["--target", cwd, "--clear"], target);
-    }
     case "launch-mobile-runtime": {
       const leaf = path.join(runnerDir, "adapters/mobile/open-device.sh");
       return spawnScriptStreaming(

package/dist/adapters/mobile/surface.js

@@ -47,7 +47,7 @@ const mobileSurface = {
     return [{ label: "metro", path: recipeRuntimePath(target, "metro.log") }];
   },
   appLogSource(target) {
-    return { label: "app", path: recipeRuntimePath(target, "metro.log") };
+    return { label: "app", path: recipeRuntimePath(target, "app-console.log") };
   },
   hints: {
     launch: "mm-harness launch ios",

package/dist/adapters/resolve-slot-ports.js

@@ -7,7 +7,6 @@ import {
   resolveExtensionRuntimeContext,
   resolveExtensionRuntimePorts,
   resolveSlotPortsByRepo,
-  resolveFarmslotPortsByRepo,
   resolveMobileRuntimeContext,
   resolveMobileRuntimePorts,
   resolveMobileSlotDefaults
@@ -20,7 +19,6 @@ export {
   resolveDefaultExtensionPorts,
   resolveExtensionRuntimeContext,
   resolveExtensionRuntimePorts,
-  resolveFarmslotPortsByRepo,
   resolveMobileRuntimeContext,
   resolveMobileRuntimePorts,
   resolveMobileSlotDefaults,

package/dist/adapters/slot-ports.js

@@ -105,7 +105,13 @@ function isExtensionWatcherLive(target) {
 function stopExtensionWatcher(target) {
   const runtimeAbs = path.join(path.resolve(target), recipeRuntimeDir());
   const webpackPidFile = path.join(runtimeAbs, "recipe-harness-webpack.pid");
+  const syncPidFile = path.join(runtimeAbs, "recipe-harness-webpack-sync.pid");
   const ownedPids = extensionWatcherPids(target);
+  try {
+    const syncPid = fs.readFileSync(syncPidFile, "utf8").trim();
+    if (/^\d+$/u.test(syncPid) && processAlive(Number(syncPid))) ownedPids.push(Number(syncPid));
+  } catch {
+  }
   for (const pid of ownedPids) {
     try {
       process.kill(pid, "SIGTERM");
@@ -113,6 +119,7 @@ function stopExtensionWatcher(target) {
     }
   }
   fs.rmSync(webpackPidFile, { force: true });
+  fs.rmSync(syncPidFile, { force: true });
   if (ownedPids.length > 0) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2e3);
     for (const pid of ownedPids) {
@@ -164,6 +171,7 @@ function stopExtensionRuntime(target) {
   let removedMarkers = 0;
   for (const name of [
     "recipe-harness-webpack.pid",
+    "recipe-harness-webpack-sync.pid",
     "webpack.pid",
     "browser.pid",
     "chromium.pid",

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { detectAdapter, handleHarness } from "./harness.js";
-import { handleActions, handleManifest } from "./commands/manifest.js";
+import { handleActions } from "./commands/manifest.js";
 import { handleDoctor } from "./commands/doctor.js";
 import { handleProvision } from "./commands/provision.js";
 import { handleRuntimeHealth } from "./commands/runtime-health.js";
@@ -21,10 +21,10 @@ import { handleRecipeQuality } from "./commands/recipe-quality.js";
 import { handleStatus } from "./commands/status.js";
 import { handleCheck } from "./commands/check.js";
 import { handleChecklist } from "./commands/checklist.js";
+import { handleLast } from "./commands/last.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 import { runOneNode } from "./commands/run-engine.js";
 const COMMANDS = {
-  manifest: handleManifest,
   actions: handleActions,
   doctor: handleDoctor,
   "runtime-health": handleRuntimeHealth,
@@ -35,7 +35,7 @@ const COMMANDS = {
   run: handleRun,
   "self-test": handleSelfTest
 };
-const OVERLAY_COMMANDS = ["install", "verify", "cleanup", "live"];
+const OVERLAY_COMMANDS = ["install", "verify", "cleanup"];
 function usage() {
   console.error(`mm-harness \u2014 the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay.
 Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.
@@ -62,9 +62,6 @@ PROVE \u2014 run recipes and inspect capabilities:
                mm-harness check diff --profile fast --artifacts-dir artifacts/validation
   actions    Describe the actions a manifest declares.
                mm-harness actions --adapter mobile
-  manifest   Print/validate the action manifest for an adapter.
-               mm-harness manifest --adapter extension --json
-
 RUNTIME OVERLAY \u2014 install/verify/clean the per-checkout runtime overlay:
   provision  Install the cached Runway mobile dev client (artifact cache + sim install).
                mm-harness provision runway ios --adapter mobile
@@ -72,12 +69,8 @@ RUNTIME OVERLAY \u2014 install/verify/clean the per-checkout runtime overlay:
                mm-harness install                      # inside a checkout, auto-detected
   verify     Check the overlay/runtime is present and healthy (no launch).
                mm-harness verify
-  live       Launch/reuse the app, then verify live control end-to-end.
-               mm-harness live
   cleanup    Remove the installed overlay and restore the checkout.
                mm-harness cleanup
-  # Open sub-question (Arthur): keep these top-level (mm-harness install) or group
-  # them under an \`overlay\` command (mm-harness overlay install)? Top-level for now.
 
 ADVANCED \u2014 internal runtime probes (rarely typed by hand):
   runtime-health     runtime-decision   runtime-launch
@@ -88,7 +81,7 @@ ONE bin: mm-harness is the only command. No per-platform binaries \u2014 platfor
 auto-detected, the positional target forces it (mm-harness launch ios), and
 platform-specific needs are FLAGS on the same command (e.g. --sidebar, --full-build).
 Human happy path = the bare command; agents add depth via flags (--json, --target, ports).
-See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).
+See README.md for the current workflow and docs/CHEATSHEET.md for examples.
 `);
 }
 async function main(argv) {
@@ -133,6 +126,7 @@ async function main(argv) {
   if (command === "recipe-quality") return handleRecipeQuality(argv.slice(1));
   if (command === "check") return handleCheck(argv.slice(1));
   if (command === "checklist") return handleChecklist(argv.slice(1));
+  if (command === "last") return handleLast(parseArgs(argv.slice(1), command));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);
   return handler(parseArgs(argv.slice(1), command));

package/dist/command-contract.js

@@ -0,0 +1,441 @@
+const bool = () => ({ kind: "boolean" });
+const value = (choices) => ({ kind: "value", ...choices ? { choices } : {} });
+const optionalValue = (choices) => ({ kind: "optional-value", ...choices ? { choices } : {} });
+const options = (...groups) => Object.assign({}, ...groups);
+const HELP = { "--help": bool(), "-h": bool() };
+const JSON = { "--json": bool() };
+const JSON_STREAM = { "--json-stream": bool() };
+const TARGET = { "--target": value(), "--project-root": value() };
+const ADAPTER = { "--adapter": value(["mobile", "extension", "core"]) };
+const MOBILE_PLATFORM = { "--platform": value(["ios", "android"]) };
+const ADAPTER_OR_MOBILE_PLATFORM = { "--platform": value(["mobile", "extension", "core", "ios", "android"]) };
+const DEVICE = { "--device": value() };
+const RUNTIME_PORTS = {
+  "--cdp-port": value(),
+  "--watcher-port": value(),
+  "--metro-port": value(),
+  "--runtime-dir": value()
+};
+const RECIPE_RUNTIME = {
+  "--artifacts-dir": value(),
+  "--action-manifest": value(),
+  "--library": value(),
+  "--heal": value(["off", "infra-only", "auto"]),
+  "--slot": value(),
+  "--validation-runtime-dir": value(),
+  "--launch-existing-dist": bool(),
+  "--record-video": optionalValue(["full-run", "off"]),
+  "--record": bool()
+};
+const RUNWAY = {
+  "--branch": value(),
+  "--default-branch": value(),
+  "--run": value(),
+  "--cache-root": value(),
+  "--simulator": value(),
+  "--runtime": value(),
+  "--device-type": value(),
+  "--slot": value(),
+  "--watcher-port": value(),
+  "--runtime-dir": value(),
+  "--force": bool(),
+  "--resolve-only": bool()
+};
+const PUBLIC_COMMAND_CONTRACTS = {
+  status: {
+    aliases: ["health", "home"],
+    options: options(HELP, JSON, TARGET, DEVICE, {
+      "--fast": bool(),
+      "--all-devices": bool()
+    })
+  },
+  checklist: {
+    usage: "mm-harness checklist mark <task-dir> <step> [options]",
+    options: options(HELP, {
+      "--mark-last": bool(),
+      "--already-fixed": bool(),
+      "--no-self-review": bool(),
+      "--skip-learnings": bool(),
+      "--skip-checklist": bool(),
+      "--reason": value(),
+      "--checklist": value(),
+      "--signal": value()
+    }),
+    positionals: [
+      { label: "action", choices: ["mark"] },
+      { label: "task-dir" },
+      {
+        label: "step",
+        validate: (step) => {
+          if (["start", "complete", "no-change", "blocked"].includes(step)) return true;
+          const numeric = Number(step);
+          return Number.isInteger(numeric) && numeric >= 1;
+        },
+        validDescription: "start|complete|no-change|blocked|a positive numeric step"
+      }
+    ],
+    minimumPositionals: 3
+  },
+  actions: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--action": value(),
+      "--categories": bool(),
+      "--category": value(),
+      "--action-manifest": value(),
+      "--raw": bool()
+    }),
+    positionals: [{ label: "query" }],
+    noPositionalsWith: ["--action", "--categories", "--raw"]
+  },
+  stop: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--port": value(),
+      "--watcher-port": value()
+    })
+  },
+  call: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
+      "--list": bool(),
+      "--arg": value()
+    }),
+    positionals: [{ label: "action" }],
+    minimumPositionals: 0,
+    requiredUnless: ["--list"],
+    noPositionalsWith: ["--list"],
+    leadingPositionals: 1,
+    variadic: { label: "key=value", pattern: /^[^=\s]+=.*/u }
+  },
+  flows: {
+    options: options(HELP, JSON, TARGET, {
+      "--library": value(),
+      "--from": value(),
+      "--flow": value(),
+      "--to": value(),
+      "--domain": value(),
+      "--run": value(),
+      "--force": bool()
+    }),
+    positionals: [{ label: "action", choices: ["list", "promote"] }]
+  },
+  run: {
+    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
+      "--list": bool(),
+      "--plan": bool()
+    }),
+    positionals: [{ label: "recipe" }],
+    minimumPositionals: 1,
+    requiredUnless: ["--list"],
+    noPositionalsWith: ["--list"]
+  },
+  last: {
+    options: options(HELP, JSON, TARGET, {
+      "--runtime-dir": value()
+    })
+  },
+  doctor: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
+      "--fix": bool(),
+      "--expect-live": bool(),
+      "--print-ready": bool(),
+      "--all-devices": bool(),
+      "--action-manifest": value(),
+      "--port": value()
+    })
+  },
+  check: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--base": value(),
+      "--profile": value(["fast", "full"]),
+      "--fix": bool(),
+      "--artifacts-dir": value()
+    }),
+    positionals: [{ label: "action", choices: ["diff"] }],
+    minimumPositionals: 1
+  },
+  "recipe-quality": {
+    options: options(HELP, JSON, {
+      "--input": value(),
+      "--output": value()
+    }),
+    positionals: [{ label: "action", choices: ["build"] }]
+  },
+  provision: {
+    options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, RUNWAY, {
+      "--platform": value(["ios"]),
+      "--device-platform": value(["ios"])
+    }),
+    positionals: [
+      { label: "source", choices: ["runway", "ios"] },
+      { label: "platform", choices: ["ios"] }
+    ]
+  },
+  install: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, RUNWAY, {
+      "--runway": bool()
+    }),
+    allowPassthrough: true
+  },
+  verify: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, RUNTIME_PORTS),
+    allowPassthrough: true
+  },
+  cleanup: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM),
+    allowPassthrough: true
+  },
+  launch: {
+    options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, {
+      "--build": bool(),
+      "--verify": bool(),
+      "--runway": bool(),
+      "--watch": bool(),
+      "--sidepanel": bool(),
+      "--fullscreen": bool(),
+      "--url": value(),
+      "--heal": value(["off", "infra-only", "auto"])
+    }),
+    positionals: [{ label: "platform", choices: ["ios", "android"] }]
+  },
+  logs: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--full": bool(),
+      "--window": bool(),
+      "--events": value(),
+      "--source": value()
+    })
+  },
+  debug: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
+      "--worker": bool(),
+      "--dev-menu": bool(),
+      "--no-open": bool()
+    })
+  },
+  update: {
+    options: options(HELP, JSON, { "--check": bool() })
+  },
+  fixtures: {
+    options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, DEVICE, {
+      "--from": value(),
+      "--dev": bool(),
+      "--force": bool(),
+      "--fixture": value(),
+      "--out": value(),
+      "--state": value(),
+      "--cdp-port": value(),
+      "--extension-dir": value(),
+      "--extension-id-file": value(),
+      "--action-manifest": value()
+    }),
+    positionals: [{ label: "action", choices: ["init", "sync", "set", "generate", "finalize"] }],
+    minimumPositionals: 1
+  }
+};
+function validatePublicInvocation(argv, examples = {}) {
+  const token = argv[0];
+  if (!token || token === "--help" || token === "-h" || token === "--version" || token === "-v") return null;
+  const resolved = resolveCommand(token);
+  if (!resolved) {
+    const names = publicCommandTokens();
+    const suggestion = closest(token, names);
+    if (token.startsWith("-")) {
+      return {
+        code: "CLI_UNKNOWN_OPTION",
+        command: "mm-harness",
+        message: `unknown top-level option '${token}'. Valid top-level options: --help, --version.`,
+        userAction: actionFor(token, closest(token, ["--help", "--version"]), "mm-harness --help")
+      };
+    }
+    return {
+      code: "CLI_UNKNOWN_COMMAND",
+      command: token,
+      message: `unknown command '${token}'. Valid commands: ${Object.keys(PUBLIC_COMMAND_CONTRACTS).join(", ")}.`,
+      userAction: actionFor(token, suggestion, suggestion ? exampleFor(resolveCommand(suggestion)?.name, examples) : "mm-harness --help")
+    };
+  }
+  const { name, contract } = resolved;
+  const tokens = argv.slice(1);
+  const positionals = [];
+  const seenOptions = /* @__PURE__ */ new Set();
+  const validOptions = Object.keys(contract.options);
+  for (let index = 0; index < tokens.length; index += 1) {
+    const argument = tokens[index] ?? "";
+    if (argument === "--") {
+      if (!contract.allowPassthrough) {
+        return usageFailure("CLI_UNEXPECTED_PASSTHROUGH", name, "this command does not accept `--` passthrough.", contract, examples);
+      }
+      break;
+    }
+    if (!argument.startsWith("-") || argument === "-") {
+      positionals.push(argument);
+      continue;
+    }
+    const equals = argument.indexOf("=");
+    const optionName = equals === -1 ? argument : argument.slice(0, equals);
+    const inlineValue = equals === -1 ? void 0 : argument.slice(equals + 1);
+    const spec = contract.options[optionName];
+    if (!spec) {
+      const suggestion = closest(optionName, validOptions);
+      return {
+        code: "CLI_UNKNOWN_OPTION",
+        command: name,
+        message: `unknown option '${optionName}'. Valid options for mm-harness ${name}: ${formatOptions(contract)}.`,
+        userAction: actionFor(optionName, suggestion, exampleFor(name, examples))
+      };
+    }
+    seenOptions.add(optionName);
+    if (spec.kind === "boolean") {
+      if (inlineValue !== void 0) {
+        return usageFailure("CLI_INVALID_OPTION_VALUE", name, `${optionName} is a flag and does not take a value.`, contract, examples);
+      }
+      continue;
+    }
+    if (spec.kind === "optional-value" && inlineValue === void 0) continue;
+    const optionValue = inlineValue ?? tokens[index + 1];
+    const nextTokenIsOption = inlineValue === void 0 && (optionValue === "-h" || optionValue === "--" || optionValue?.startsWith("--"));
+    if (optionValue === void 0 || spec.kind === "value" && optionValue === "" || nextTokenIsOption) {
+      return usageFailure("CLI_MISSING_OPTION_VALUE", name, `${optionName} requires a value.`, contract, examples);
+    }
+    if (inlineValue === void 0) index += 1;
+    if (spec.choices && !spec.choices.includes(optionValue)) {
+      const suggestion = closest(optionValue, spec.choices);
+      return {
+        code: "CLI_INVALID_OPTION_VALUE",
+        command: name,
+        message: `${optionName} must be ${formatChoiceList(spec.choices)}; received '${optionValue}'. Valid options for mm-harness ${name}: ${formatOptions(contract)}.`,
+        userAction: actionFor(optionValue, suggestion, exampleFor(name, examples))
+      };
+    }
+  }
+  if (seenOptions.has("--help") || seenOptions.has("-h")) return null;
+  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 usageFailure("CLI_MISSING_POSITIONAL", name, `${name} requires <${missing}> first.`, contract, examples);
+  }
+  const forbiddingOption = contract.noPositionalsWith?.find((option) => seenOptions.has(option));
+  if (forbiddingOption && positionals.length > 0) {
+    return usageFailure(
+      "CLI_EXCESS_POSITIONAL",
+      name,
+      `${forbiddingOption} does not accept positional '${positionals[0]}'.`,
+      contract,
+      examples
+    );
+  }
+  const minimum = contract.requiredUnless?.some((option) => seenOptions.has(option)) ? 0 : contract.minimumPositionals ?? 0;
+  if (positionals.length < minimum) {
+    const missingSpec = contract.positionals?.[positionals.length];
+    const missing = missingSpec?.label ?? "argument";
+    const valid = missingSpec?.choices?.length ? ` Choose one: ${missingSpec.choices.join("|")}.` : "";
+    const usage = contract.usage ? ` Usage: ${contract.usage}.` : "";
+    return usageFailure("CLI_MISSING_POSITIONAL", name, `missing required <${missing}>.${valid}${usage}`, contract, examples);
+  }
+  const fixed = contract.positionals ?? [];
+  for (let index = 0; index < Math.min(positionals.length, fixed.length); index += 1) {
+    const invalid = invalidPositional(positionals[index] ?? "", fixed[index]);
+    if (invalid) return positionalFailure(name, positionals[index] ?? "", fixed[index], contract, examples);
+  }
+  if (positionals.length > fixed.length && !contract.variadic) {
+    const unexpected = positionals[fixed.length] ?? "";
+    return usageFailure("CLI_EXCESS_POSITIONAL", name, `unexpected positional '${unexpected}'; this command accepts ${formatPositionals(contract)}.`, contract, examples);
+  }
+  if (contract.variadic) {
+    for (const positional of positionals.slice(fixed.length)) {
+      if (invalidPositional(positional, contract.variadic)) {
+        return positionalFailure(name, positional, contract.variadic, contract, examples);
+      }
+    }
+  }
+  return null;
+}
+function publicCommandTokens() {
+  const tokens = [];
+  for (const [name, contract] of Object.entries(PUBLIC_COMMAND_CONTRACTS)) {
+    tokens.push(name, ...contract.aliases ?? []);
+  }
+  return tokens;
+}
+function publicCommandNames() {
+  return Object.keys(PUBLIC_COMMAND_CONTRACTS);
+}
+function resolveCommand(token) {
+  const direct = PUBLIC_COMMAND_CONTRACTS[token];
+  if (direct) return { name: token, contract: direct };
+  for (const [name, contract] of Object.entries(PUBLIC_COMMAND_CONTRACTS)) {
+    if (contract.aliases?.includes(token)) return { name, contract };
+  }
+  return null;
+}
+function usageFailure(code, command, message, contract, examples) {
+  return {
+    code,
+    command,
+    message: `${message} Valid options for mm-harness ${command}: ${formatOptions(contract)}.`,
+    userAction: `Try: ${exampleFor(command, examples)}. Inspect options: mm-harness ${command} --help`
+  };
+}
+function positionalFailure(command, received, spec, contract, examples) {
+  const valid = spec.validDescription ?? (spec.choices ? spec.choices.join(", ") : spec.pattern || spec.validate ? `a valid <${spec.label}>` : `<${spec.label}>`);
+  const suggestion = spec.choices ? closest(received, spec.choices) : void 0;
+  return {
+    code: "CLI_INVALID_POSITIONAL",
+    command,
+    message: `invalid <${spec.label}> '${received}'. Valid values: ${valid}. Valid options for mm-harness ${command}: ${formatOptions(contract)}.`,
+    userAction: actionFor(received, suggestion, exampleFor(command, examples))
+  };
+}
+function invalidPositional(value2, spec) {
+  if (!spec) return true;
+  if (spec.choices && !spec.choices.includes(value2)) return true;
+  if (spec.validate && !spec.validate(value2)) return true;
+  return Boolean(spec.pattern && !spec.pattern.test(value2));
+}
+function formatOptions(contract) {
+  return Object.entries(contract.options).map(([name, spec]) => {
+    if (spec.kind === "boolean") return name;
+    const valueLabel = spec.choices?.join("|") ?? "value";
+    return spec.kind === "optional-value" ? `${name}[=${valueLabel}]` : `${name} <${valueLabel}>`;
+  }).join(", ");
+}
+function formatChoiceList(choices) {
+  if (choices.length === 1) return choices[0] ?? "";
+  if (choices.length === 2) return `${choices[0]} or ${choices[1]}`;
+  return `${choices.slice(0, -1).join(", ")}, or ${choices[choices.length - 1]}`;
+}
+function formatPositionals(contract) {
+  const fixed = (contract.positionals ?? []).map((spec) => `<${spec.label}>`);
+  if (contract.variadic) fixed.push(`[<${contract.variadic.label}> ...]`);
+  return fixed.length > 0 ? fixed.join(" ") : "no positionals";
+}
+function actionFor(received, suggestion, example) {
+  return `${suggestion ? `Did you mean '${suggestion}' instead of '${received}'? ` : ""}Try: ${example}`;
+}
+function exampleFor(command, examples) {
+  return command ? examples[command] ?? `mm-harness ${command} --help` : "mm-harness --help";
+}
+function closest(input, candidates) {
+  if (candidates.length === 0) return void 0;
+  const ranked = candidates.map((candidate) => ({ candidate, distance: levenshtein(input, candidate) })).sort((left, right) => left.distance - right.distance || left.candidate.localeCompare(right.candidate));
+  const best = ranked[0];
+  if (!best) return void 0;
+  const threshold = Math.max(2, Math.floor(Math.max(input.length, best.candidate.length) / 3));
+  return best.distance <= threshold ? best.candidate : void 0;
+}
+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] + (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 {
+  PUBLIC_COMMAND_CONTRACTS,
+  publicCommandNames,
+  publicCommandTokens,
+  validatePublicInvocation
+};