@deeeed/metamask-harness 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.17.0 - 2026-07-14
+
+### Added
+
+- Command-specific JSON failures now preserve a structured `userAction` across device targeting, action calls, recipe validation/execution, checks, and dev-server stop. Successful install/verify/cleanup, provision, and stop transitions add `next` only when one truthful follow-up exists; discovery and terminal evidence results remain quiet.
+- `run` and `launch` now implement the documented `--json-stream` contract: line-flushed JSONL phase/progress events, per-node recipe status, compact evidence paths, and one terminal `complete` event. Stream mode keeps stdout machine-clean and takes precedence when combined with `--json`; existing `--json` output is unchanged.
+- Interactive Mobile launch, Runway provisioning, and recipe execution now print contextual intent before their first potentially slow readiness or validation probe. The new lines are suppressed for `--json` and non-TTY stdout.
+- `last --json` reads an atomic, mode-`0600`, per-checkout resumability journal for significant runtime/proof commands, including redacted args, verdict, evidence paths, and timestamps. Interrupted commands remain `running`; discovery commands do not overwrite the record.
+- `actions <query>` now searches action names, categories, fields, and descriptions with typo tolerance, while single-action detail includes compact related-action names.
+
+### Changed
+
+- Action categories now group protocol primitives into useful `assertion`, `control`, `evidence`, and `runtime` domains instead of exposing one category per unnamespaced action.
+- Public commands now reject unknown commands/options, missing values and positionals, invalid enums, and excess positionals before dispatch. Human errors include valid command-local options, a closest match when available, and a runnable example; `--json` returns stable `CLI_*` codes with `error.message` and `error.userAction`.
+- `docs/CLI-ERGONOMICS-AUDIT.md` is generated from the public command contract so every command remains covered by the shared bad-flag and JSON usage-error policy as the surface evolves.
+
 ## 0.16.0 - 2026-07-14
 
 ### Added

package/README.md

@@ -29,6 +29,7 @@ Naming: **"harness" is the tool** (`mm-harness`) and the generic engine package
 (`@farmslot/recipe-harness`); the files it installs into a checkout are the
 **runtime overlay**. Read [MENTAL-MODEL.md](docs/MENTAL-MODEL.md) first (the
 before→after map), then [CLI-SPEC.md](docs/CLI-SPEC.md) for the full contract.
+Release candidates have a short [human QA checklist](docs/CLI-ERGONOMICS-HUMAN-QA.md).
 
 One package, two responsibilities:
 
@@ -76,16 +77,18 @@ windows, wallet state, health, ports, parallel).
 
 ```bash
 # Capabilities (compose recipes from the vocabulary + flow library)
-mm-harness actions --adapter mobile --categories --json # compact discovery
+mm-harness actions positions --adapter mobile --json    # focused discovery
 mm-harness actions --adapter mobile --category ui --json # bounded vocabulary
 mm-harness actions --adapter mobile --raw       # raw action-manifest dump
 mm-harness call unlock --adapter extension      # run one action via the real engine path
+mm-harness last --json                          # resume from the last significant command
 mm-harness flows --json                         # reusable library flows, with provenance
 
 # Readiness + proof
 mm-harness doctor                               # read-only readiness check (no launch)
 mm-harness doctor --fix                         # heal the overlay without launching
 mm-harness run recipe.json --plan --adapter mobile   # validate + plan, touch nothing
+mm-harness run recipe.json --json-stream             # line-flushed JSONL progress for agents
 
 # Daily loop (run from inside a checkout)
 mm-harness launch ios                           # launch (mobile: ios | android)

package/dist/cli.js

@@ -21,6 +21,7 @@ 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 = {
@@ -133,6 +134,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
+};