@deeeed/metamask-harness 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.7.1
+
+### Added
+- **`doctor --expect-live`** — exit-coded runtime liveness for hooks and scripts: exit 0 only when the adapter runtime decision is `ready` (extension: watcher + CDP; mobile: metro + bridge; core: deps), non-zero with a teaching escape otherwise. Fails closed on every degraded path; reuses the doctor runtime probe, no duplicated checks.
+
+### Fixed
+- **Per-command `--help` documents every implemented flag** (`call/run --list`, `--library`, `--action-manifest`, `logs --window`, `actions --action`, `launch --url`, `doctor --runtime-dir`, `stop --adapter`) and tab-completion matches — the CLI self-teaches its own surface. A contract test guards help/implementation parity.
+- **Injected runner shims resolve at run time** instead of a path baked at inject time: `MM_HARNESS_BIN` → global `mm-harness` on PATH → the recorded install-time path as last resort → teaching escape. A slot copied to or shared with another machine no longer points at a missing absolute path.
+- Removed two parsed-but-unused `launch` flags (`--yes`, `--json-stream`).
+
 ## 0.7.0
 
 The "version people use": every remaining identified fix/improvement batched on the

package/adapters/core/inject.sh

@@ -88,8 +88,13 @@ install_v1_runner_assets() {
     if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
-    printf 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ "$MM_HARNESS_BIN" != %s ]; then echo "mm-harness overlay: %s: %s (reinstall to repoint: mm-harness install)" >&2; fi\n' "$runner_exec_q" 'delegating to the runner pinned at install time' "$runner_exec_q"
-    printf 'exec %s "$@"\n' "$runner_exec_q"
+    # Resolve the runner at run time (override > global install > install-time
+    # record); the recorded path is last resort so a moved checkout is not pinned.
+    printf '%s\n' 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi'
+    printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
+    printf 'if [ -x %s ]; then exec %s "$@"; fi\n' "$runner_exec_q" "$runner_exec_q"
+    printf '%s\n' 'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2'
+    printf '%s\n' 'exit 127'
   } > "$HARNESS_DIR/runner/bin/mm-harness"
   chmod +x "$HARNESS_DIR/runner/bin/mm-harness"
   if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then

package/adapters/extension/inject.mjs

@@ -68,12 +68,19 @@ fs.mkdirSync(path.join(harnessDir, 'runner/recipes'), { recursive: true });
 fs.rmSync(path.join(harnessDir, 'scripts'), { recursive: true, force: true });
 fs.mkdirSync(path.join(harnessDir, 'scripts/lib'), { recursive: true });
 
+// Resolve the runner at run time so a moved or shared checkout is never bound to
+// an install-time absolute path: explicit override, then a global install, then
+// the runner recorded at install time as a last resort; teach install on miss.
+const pinnedBin = shellQuote(path.join(runnerDir, 'bin/mm-harness'));
 const delegate = [
   '#!/usr/bin/env bash',
   'set -euo pipefail',
   protocolRoot ? `export FARMSLOT_ROOT=\${FARMSLOT_ROOT:-${shellQuote(protocolRoot)}}` : null,
-  `if [ -n "\${MM_HARNESS_BIN:-}" ] && [ "\$MM_HARNESS_BIN" != ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} ]; then echo "mm-harness overlay: delegating to the runner pinned at install time: ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} (reinstall to repoint: mm-harness install)" >&2; fi`,
-  `exec ${shellQuote(path.join(runnerDir, 'bin/mm-harness'))} "$@"`,
+  'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi',
+  'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi',
+  `if [ -x ${pinnedBin} ]; then exec ${pinnedBin} "$@"; fi`,
+  'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2',
+  'exit 127',
 ].filter(Boolean).join('\n') + '\n';
 fs.writeFileSync(path.join(harnessDir, 'runner/bin/mm-harness'), delegate, { mode: 0o755 });
 if (protocolRoot) fs.writeFileSync(path.join(harnessDir, 'runner/.farmslot-root'), `${protocolRoot}\n`);

package/adapters/mobile/inject.sh

@@ -187,8 +187,13 @@ install_v1_runner_assets() {
     if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then
       printf 'export FARMSLOT_ROOT=${FARMSLOT_ROOT:-%s}\n' "$runner_protocol_root_q"
     fi
-    printf 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ "$MM_HARNESS_BIN" != %s ]; then echo "mm-harness overlay: %s: %s (reinstall to repoint: mm-harness install)" >&2; fi\n' "$runner_exec_q" 'delegating to the runner pinned at install time' "$runner_exec_q"
-    printf 'exec %s "$@"\n' "$runner_exec_q"
+    # Resolve the runner at run time (override > global install > install-time
+    # record); the recorded path is last resort so a moved checkout is not pinned.
+    printf '%s\n' 'if [ -n "${MM_HARNESS_BIN:-}" ] && [ -x "${MM_HARNESS_BIN}" ]; then exec "${MM_HARNESS_BIN}" "$@"; fi'
+    printf '%s\n' 'if command -v mm-harness >/dev/null 2>&1; then exec mm-harness "$@"; fi'
+    printf 'if [ -x %s ]; then exec %s "$@"; fi\n' "$runner_exec_q" "$runner_exec_q"
+    printf '%s\n' 'echo "mm-harness not found. Next: npm i -g @deeeed/metamask-harness" >&2'
+    printf '%s\n' 'exit 127'
   } > "$HARNESS_DIR/runner/bin/mm-harness"
   chmod +x "$HARNESS_DIR/runner/bin/mm-harness"
   if [ -n "$METAMASK_RUNNER_PROTOCOL_ROOT" ]; then

package/dist/cli-commands.js

@@ -11,10 +11,10 @@ const SPEC = {
     { name: "ports", desc: "Slot ports and runtime paths", flags: ["--json"] },
     { name: "up", desc: "Decide + run minimum work to reach ready", flags: ["--json", "--dry-run"] },
     { name: "sync", desc: "Refresh harness + canonicalize wallet fixture", flags: ["--json"] },
-    { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f"] },
+    { name: "logs", aliases: ["tail"], desc: "Compact build events or full log", flags: ["--full", "-f", "--window", "--events", "--source", "--json"] },
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
-    { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir"] },
+    { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port"] },
     { name: "run", desc: "Execute a proof recipe", args: ["recipe.json"], flags: ["--list"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
     { name: "prepare", desc: "Install harness (+ optional validate)", flags: ["--target", "--runtime-dir", "--json"] },

package/dist/commands/doctor.js

@@ -7,7 +7,7 @@ import { assertAdapter, runnerDir } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { ensureOverlay, newHealState, recipeRunning } from "../heal-bounds.js";
-import { ADAPTER_DETECT_NEXT, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import {
   actionManifestPathOption,
   applyRuntimeDirOption,
@@ -15,10 +15,24 @@ import {
   optionString,
   targetPath
 } from "./parse-args.js";
+function applyDoctorRuntimePorts(options) {
+  const cdpPort = optionString(options, "cdpPort");
+  if (cdpPort) {
+    process.env.CDP_PORT = cdpPort;
+    process.env.RECIPE_CDP_PORT = cdpPort;
+  }
+  const watcherPort = optionString(options, "watcherPort") ?? optionString(options, "port") ?? optionString(options, "metroPort");
+  if (watcherPort) {
+    process.env.WATCHER_PORT = watcherPort;
+    process.env.METRO_PORT = watcherPort;
+    process.env.RECIPE_WATCHER_PORT = watcherPort;
+  }
+}
 async function handleDoctor({ options }) {
   applyRuntimeDirOption(options);
   const target = targetPath(options);
   const json = optionFlag(options, "json");
+  const expectLive = optionFlag(options, "expectLive");
   const explicitAdapter = optionString(options, "adapter") ?? optionString(options, "platform");
   const adapter = explicitAdapter ?? detectAdapter(target);
   if (!adapter) {
@@ -40,11 +54,13 @@ async function handleDoctor({ options }) {
   try {
     const surface = getAdapterSurface(adapter);
     surface.resolveSlotPorts(target);
+    applyDoctorRuntimePorts(options);
     runtime = await surface.runtimeStatus(target);
   } catch {
   }
   const orphanMetros = adapter === "mobile" ? detectOrphanMetros(target, process.env.WATCHER_PORT) : [];
   const capture = captureHelperHealth();
+  if (expectLive) return emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, json);
   if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
@@ -78,6 +94,23 @@ async function handleDoctor({ options }) {
   }
   return result.status === "pass" ? 0 : 1;
 }
+function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, json) {
+  const live = runtime?.decision === "ready";
+  if (json) {
+    console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture }, null, 2));
+    return live ? EXIT.ok : EXIT.runtime;
+  }
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  if (live) {
+    console.log(`${out("ok", "live")} ${out("bold", adapter)} runtime ready`);
+    return EXIT.ok;
+  }
+  const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
+  console.error(`${out("err", "not-live")} ${out("bold", adapter)} ${detail} ${out("dim", target)}`);
+  for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
+  console.error(`  Next: ${getAdapterSurface(adapter).hints.relaunch}`);
+  return EXIT.runtime;
+}
 function captureHelperHealth() {
   if (process.platform !== "darwin") return null;
   const bin = process.env.CAPTURE_HELPER_PATH || "capture-helper";

package/dist/commands/launch/index.js

@@ -32,9 +32,7 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "sidepanel",
   "fullscreen",
   "runway",
-  "json",
-  "jsonStream",
-  "yes"
+  "json"
 ]);
 async function handleLaunch(argv) {
   const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);

package/dist/commands/parse-args.js

@@ -28,6 +28,7 @@ function parseArgs(argv, command) {
     "fix",
     "force",
     "resolveOnly",
+    "expectLive",
     "help"
   ]);
   for (let i = 0; i < argv.length; i += 1) {

package/dist/mm-harness-cli.js

@@ -18,6 +18,7 @@ const REAL = [
 
   List the action vocabulary + field schemas for the checkout adapter.
 
+  --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --raw                              Dump raw action registry JSON
@@ -25,6 +26,7 @@ const REAL = [
 
 Example:
   mm-harness actions --adapter mobile
+  mm-harness actions --adapter mobile --action assert_orders
   mm-harness actions --adapter extension --raw`
   },
   {
@@ -41,6 +43,7 @@ Example:
     core       headless \u2014 no dev server to stop (teaching error)
 
   --port <port>                      Dev-server port (default: the checkout's slot context)
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --json                             Machine-readable output
 
@@ -59,11 +62,13 @@ Example:
   if unique; ambiguous = exit 2. 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)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (default: temp dir)
   --action-manifest <path>           Override the action manifest
+  --library <name=path>              Add/override a recipe-library source (repeatable)
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
 
@@ -96,10 +101,13 @@ Example:
 
   Validate + run a recipe and write evidence (summary / trace / artifacts).
 
+  --list                             List everything invocable for the adapter (actions + flows); no <recipe> needed
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --artifacts-dir <dir>              Where to write evidence (required unless --plan)
+  --action-manifest <path>           Override the action manifest
+  --library <name=path>              Add/override a recipe-library source (repeatable)
   --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
   --json                             Machine-readable output
   --record-video=full-run            Record a video of the run
@@ -118,13 +126,17 @@ Example:
   sections so there is no hunting for files.
 
   --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
+  --expect-live                      Exit 0 iff the runtime is live (extension: watcher+CDP; mobile: Metro+bridge; core: deps), non-zero + teaching escape otherwise
+  --cdp-port <port>                  Extension CDP port for the liveness probe (env: CDP_PORT / RECIPE_CDP_PORT)
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
+  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
   --json                             Machine-readable output
 
 Example:
   mm-harness doctor
   mm-harness doctor --fix --json
+  mm-harness doctor --adapter extension --target /path/to/checkout --cdp-port 6662 --expect-live
   mm-harness doctor --adapter mobile --target /path/to/checkout`
   },
   {
@@ -238,6 +250,7 @@ Example:
   --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
   --watch                            Persistent webpack watcher then relaunch (extension only)
   --sidepanel | --fullscreen         Extension display mode (default --fullscreen)
+  --url <dapp-url>                    Open a dapp in the main tab beside the sidepanel (extension only)
   --heal <off|infra-only|auto>       Healing policy (default auto); bounds always enforced
   --device <udid|name>               Target simulator/device (env: IOS_SIMULATOR / ADB_SERIAL)
   --cdp-port <port>                  Extension CDP port (env: CDP_PORT / RECIPE_CDP_PORT)
@@ -261,6 +274,7 @@ Example:
   Teaching error if nothing is running (points at launch).
 
   --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
+  --window                           (Re)open the read-only tmux tail window for the resolved dev-server port (leaves the process untouched)
   --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
   --source <label>                   Log source per adapter \u2014 mobile: metro|app (default metro);
                                      extension: webpack|watcher|rebuild|app (default webpack).
@@ -271,7 +285,8 @@ Example:
 
 Example:
   mm-harness logs
-  mm-harness logs --full`
+  mm-harness logs --full
+  mm-harness logs --window`
   },
   {
     name: "debug",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"