@deeeed/metamask-harness 0.4.0 → 0.5.0

package/dist/mm-harness-cli.js

@@ -0,0 +1,521 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { color } from "./cli-color.js";
+import { handleUpdate, maybeNudge } from "./commands/update.js";
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+globalThis.__MM_HARNESS_WRAPPER__ = true;
+const { main: recipeMain } = await import("./cli.js");
+const rawArgv = process.argv.slice(2);
+const REAL = [
+  {
+    name: "actions",
+    summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
+    example: "mm-harness actions --adapter mobile",
+    helpText: `mm-harness actions [flags]
+
+  List the action vocabulary + field schemas for the checkout adapter.
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --raw                              Dump raw action registry JSON
+  --json                             Machine-readable output
+
+Example:
+  mm-harness actions --adapter mobile
+  mm-harness actions --adapter extension --raw`
+  },
+  {
+    name: "stop",
+    summary: "Stop the dev server this checkout owns (mobile Metro / extension webpack watcher) and close its log window.",
+    example: "mm-harness stop",
+    helpText: `mm-harness stop [flags]
+
+  Stop the dev server this checkout owns and close its tmux log-tail window,
+  scoped to this checkout so concurrent slots are untouched. Idempotent \u2014
+  nothing running is success, not an error. Behavior is per platform:
+    mobile     stop the port-scoped Metro dev server
+    extension  stop the checkout's webpack watcher (pid file + orphan scan)
+    core       headless \u2014 no dev server to stop (teaching error)
+
+  --port <port>                      Dev-server port (default: the checkout's slot context)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness stop
+  mm-harness stop --port 8061`
+  },
+  {
+    name: "call",
+    summary: "Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).",
+    example: "mm-harness call ensure_unlocked",
+    helpText: `mm-harness call <action> [--arg k=v ...] [flags]
+
+  Run one action in isolation as a one-node recipe through the real engine path.
+  Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
+  if unique; ambiguous = exit 2. Actions differ per adapter \u2014 list this checkout's
+  with: mm-harness actions.
+
+  --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
+  --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
+  --json                             Machine-readable output
+
+Example (real actions; run mm-harness actions for this checkout's full set):
+  mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
+  mm-harness call command --arg cmd="echo hi" --adapter core   # the universal action (all adapters)`
+  },
+  {
+    name: "flows",
+    summary: "Browse the reusable flow library (bare = list; `flows promote` publishes a flow up a tier). Resolves across libraries \u2014 personal > team > canonical, highest tier wins.",
+    example: "mm-harness flows",
+    helpText: `mm-harness flows [flags]
+
+  Browse the reusable flow library. Flows resolve across libraries by precedence
+  (personal > team > canonical); the highest-tier copy wins and shadows lower ones.
+  Flow resolution is adapter-global, so there is no --adapter flag here.
+
+  --library <name=path>              Add/override a library source (repeatable)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness flows`
+  },
+  {
+    name: "run",
+    summary: "Validate + run a recipe and write evidence (summary/trace/artifacts). --plan validates + prints the plan, touching nothing.",
+    example: "mm-harness run recipe.json",
+    helpText: `mm-harness run <recipe.json> [flags]
+
+  Validate + run a recipe and write evidence (summary / trace / artifacts).
+
+  --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)
+  --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
+
+Example:
+  mm-harness run recipe.json --plan --adapter mobile
+  mm-harness run recipe.json --adapter extension --artifacts-dir ./out`
+  },
+  {
+    name: "doctor",
+    summary: "Readiness check for a checkout \u2014 no app launch. --fix repairs the overlay/runtime without launching.",
+    example: "mm-harness doctor",
+    helpText: `mm-harness doctor [flags]
+
+  Readiness check for a checkout \u2014 no app launch. Reports the fixture and runtime-context
+  sections so there is no hunting for files.
+
+  --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness doctor
+  mm-harness doctor --fix --json
+  mm-harness doctor --adapter mobile --target /path/to/checkout`
+  },
+  {
+    name: "provision",
+    summary: "Install the cached Runway iOS dev client on a prepared mobile slot (no deps, no Metro).",
+    example: "mm-harness provision runway ios --adapter mobile",
+    helpText: `mm-harness provision [runway ios] [flags]
+
+  Install the cached Runway iOS dev client on the slot simulator. This is a thin
+  provisioning path only: artifact cache + simulator create + simctl install.
+  JavaScript dependencies and Metro remain dispatch-time launch concerns.
+
+  --adapter <mobile|extension|core>  Target adapter (mobile supported; extension/core teach)
+  --target <path>                    Slot checkout path (default: cwd)
+  --platform <ios>                   Platform (default ios)
+  --simulator <name|udid>            Override agentic-runtime.json simulator (alias: --device)
+  --device <name|udid>               Alias for --simulator
+  --slot <id>                        Farm slot id recorded in the provision baseline
+  --watcher-port <port>              Farm Metro/watcher port carried through context and Next:
+  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
+  --runtime <id>                     iOS runtime id used if simulator must be created
+  --device-type <id>                 Device type id used if simulator must be created
+  --branch <ref>                     Probe this ref before default branch
+  --default-branch <ref>             Fallback ref (default main)
+  --run <id>                         Exact GitHub Actions run id
+  --cache-root <dir>                 Override shared runway cache root
+  --force                            Reinstall even when the app is already present
+  --resolve-only                     Resolve artifact metadata only; no simulator/cache/install
+  --json                             Machine-readable envelope; progress stays stderr
+
+Example:
+  mm-harness provision runway ios --adapter mobile --target /path/to/slot
+  mm-harness provision runway ios --adapter mobile --slot scratch-1 --runtime-dir temp/recipe/runtime-8081
+  mm-harness provision runway ios --run 28676856835 --resolve-only --json`
+  },
+  {
+    name: "install",
+    summary: "Install the per-checkout runtime overlay, or --runway to install a cached mobile dev client.",
+    example: "mm-harness install",
+    helpText: `mm-harness install [flags]
+
+  Install the per-checkout runtime overlay (for CI / agents).
+  Add --runway on a mobile slot to install the cached Runway iOS dev client only:
+  artifact cache + simulator create + simctl install. JavaScript dependencies
+  and Metro remain dispatch-time launch concerns.
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --runway                           Thin mobile Runway artifact install instead of overlay install
+  --platform <ios>                   Runway platform (default ios)
+  --simulator <name|udid>            Override agentic-runtime.json simulator
+  --runtime <id>                     iOS runtime id used if simulator must be created
+  --device-type <id>                 Device type id used if simulator must be created
+  --branch <ref>                     Probe this ref before default branch
+  --default-branch <ref>             Fallback ref (default main)
+  --run <id>                         Exact GitHub Actions run id
+  --cache-root <dir>                 Override shared runway cache root
+  --force                            Reinstall even when the app is already present
+  --resolve-only                     Runway metadata only; no simulator/cache/install
+
+Example:
+  mm-harness install
+  mm-harness install --adapter extension --target /path/to/checkout
+  mm-harness install --runway --adapter mobile --target /path/to/slot`
+  },
+  {
+    name: "verify",
+    summary: "Check the overlay/runtime is present and healthy (no launch).",
+    example: "mm-harness verify",
+    helpText: `mm-harness verify [flags]
+
+  Check the runtime overlay is present and healthy (no app launch).
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness verify
+  mm-harness verify --adapter core --target /path/to/checkout`
+  },
+  {
+    name: "cleanup",
+    summary: "Remove the installed overlay and restore the checkout.",
+    example: "mm-harness cleanup",
+    helpText: `mm-harness cleanup [flags]
+
+  Remove the installed overlay and restore the checkout.
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+
+Example:
+  mm-harness cleanup
+  mm-harness cleanup --adapter mobile --target /path/to/checkout`
+  },
+  {
+    name: "launch",
+    summary: "Launch the app (Metro/build + boot), auto-ensuring the runtime overlay first. Mobile: ios|android required.",
+    example: "mm-harness launch ios",
+    helpText: `mm-harness launch [ios|android] [flags]
+
+  Launch the app \u2014 quick relaunch by default; --build for a full native/webpack build.
+  Mobile: target is MANDATORY (ios | android). Extension: no target (--fullscreen default;
+  --sidepanel to override). core is headless (teaching error \u2014 use verify/run).
+
+  --build                            Full native/webpack build tier (default = quick relaunch)
+  --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
+  --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)
+  --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)
+  --watcher-port <port>              Metro/webpack port (env: WATCHER_PORT / METRO_PORT)
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable summary (recovered[] / mutations[] / phase)
+
+Example:
+  mm-harness launch ios
+  mm-harness launch ios --build
+  mm-harness launch --verify --json`
+  },
+  {
+    name: "logs",
+    summary: "Tail Metro/webpack + app logs for the active checkout.",
+    example: "mm-harness logs",
+    helpText: `mm-harness logs [flags]
+
+  Tail Metro/webpack + app logs for the active checkout.
+  Teaching error if nothing is running (points at launch).
+
+  --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
+  --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).
+                                     Core is headless (teaching error).
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness logs
+  mm-harness logs --full`
+  },
+  {
+    name: "debug",
+    summary: "Open the debug console \u2014 extension: Chrome DevTools via CDP; mobile: RN DevTools.",
+    example: "mm-harness debug",
+    helpText: `mm-harness debug [flags]
+
+  Open the debug console \u2014 extension: Chrome DevTools via CDP; mobile: RN DevTools.
+
+  --worker                           Extension service-worker DevTools
+  --dev-menu                         Mobile RN developer menu
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness debug
+  mm-harness debug --worker`
+  },
+  {
+    name: "update",
+    summary: "Update the installed mm-harness to the published latest (--check reports only; --json = {current, latest, updateAvailable}).",
+    example: "mm-harness update",
+    helpText: `mm-harness update [flags]
+
+  Update the globally-installed mm-harness to the npm registry's latest.
+  Bare form upgrades (npm i -g @deeeed/metamask-harness@latest) and prints old \u2192 new;
+  already-current exits 0.
+
+  --check                            Report only \u2014 exit 0 up-to-date / exit 1 update available (no install)
+  --json                             Machine-readable { current, latest, updateAvailable }
+
+  A passive once-a-day nudge also prints one stderr line when a newer version exists.
+  Silence it with MM_HARNESS_NO_UPDATE_CHECK=1 (auto-off in CI).
+
+Example:
+  mm-harness update
+  mm-harness update --check --json`
+  },
+  {
+    name: "fixtures",
+    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 sync files / set the wallet.",
+    example: "mm-harness fixtures set",
+    helpText: `mm-harness fixtures <sync|set> [flags]
+
+  Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
+  sync   Refresh the wallet fixture files on the target.
+  set    Apply the canonical fixture (SRP/password/accounts); the password is read
+         FROM the fixture, never typed.
+  Want different accounts? Edit the fixture file directly:
+    <checkout>/temp/recipe/runtime/wallet-fixture.json
+
+  --fixture <path>                   Override the fixture path (agent form; env: RECIPE_WALLET_FIXTURE)
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness fixtures sync
+  mm-harness fixtures set`
+  }
+];
+const RETIRED_INTERNAL = [
+  "runtime-health",
+  "runtime-decision",
+  "runtime-launch",
+  "resolve-extension",
+  "ensure-ready",
+  "self-test"
+];
+const RETIRED = [
+  {
+    name: "live",
+    message: `mm-harness live is retired (exit 2).
+
+Replacement: mm-harness launch --verify (install overlay \u2192 launch \u2192 CDP/bridge poll \u2192 smoke verify).`
+  },
+  {
+    name: "manifest",
+    message: `mm-harness manifest is retired (exit 2).
+
+Replacement: mm-harness actions --raw   (works now \u2014 dumps the raw action registry JSON,
+identical to the old \`manifest --json\`). Manifest validation moved into doctor / run --plan.`
+  },
+  ...RETIRED_INTERNAL.map((name) => ({
+    name,
+    message: `mm-harness ${name} is retired (exit 2).
+
+It is internal now \u2014 its logic lives inside doctor / launch / verify self-healing.
+Use: mm-harness doctor`
+  }))
+];
+const HELP_GROUPS = [
+  {
+    title: "DAILY LOOP",
+    blurb: "what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)",
+    commands: ["launch", "stop", "logs", "debug", "fixtures"]
+  },
+  {
+    title: "DISCOVER",
+    blurb: "compose recipes from the action vocabulary + flow library (--json is the agent-primary form)",
+    commands: ["actions", "call", "flows"]
+  },
+  {
+    title: "PROVE",
+    blurb: "run recipes and inspect readiness",
+    commands: ["run", "doctor"]
+  },
+  {
+    title: "RUNTIME OVERLAY",
+    blurb: "install/verify/clean the overlay, plus thin mobile slot provisioning",
+    commands: ["provision", "install", "verify", "cleanup"]
+  },
+  {
+    title: "MAINTAIN",
+    blurb: "keep the installed harness current with the npm registry",
+    commands: ["update"]
+  }
+];
+function commandMeta(name) {
+  const real = REAL.find((command) => command.name === name);
+  if (real) return { summary: real.summary, example: real.example, planned: false };
+  return { summary: "", example: "", planned: false };
+}
+function detectedSlotLine(out) {
+  const ctxPath = path.join(
+    process.cwd(),
+    process.env.RECIPE_RUNTIME_DIR || "temp/recipe/runtime",
+    "agentic-runtime.json"
+  );
+  try {
+    const ctx = JSON.parse(fs.readFileSync(ctxPath, "utf8"));
+    const parts = [];
+    if (ctx.slotId) parts.push(`slot ${out("ok", String(ctx.slotId))}`);
+    if (ctx.simulator) parts.push(`device ${out("ok", String(ctx.simulator))}`);
+    if (ctx.metroPort) parts.push(`metro :${out("ok", String(ctx.metroPort))}`);
+    if (ctx.gitBranch) parts.push(`branch ${out("info", String(ctx.gitBranch))}`);
+    if (parts.length === 0) return null;
+    return `${out("label", "SLOT")} \u2014 this checkout is a prepared slot: ${parts.join(" \xB7 ")}`;
+  } catch {
+    return null;
+  }
+}
+function groupedHelp() {
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const lines = [];
+  lines.push(`${out("bold", "mm-harness")} \u2014 one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.`);
+  lines.push("Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.");
+  lines.push(`Grammar: ${out("cmd", "mm-harness <command> [target] [flags]")}   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)`);
+  if (process.env.MM_HARNESS_BIN) {
+    lines.push("");
+    lines.push(`${out("warn", "DEV OVERRIDE ACTIVE")} \u2014 this run is served by MM_HARNESS_BIN=${out("path", process.env.MM_HARNESS_BIN)} (unset it to return to the installed/global bin).`);
+  }
+  const slotLine = detectedSlotLine(out);
+  if (slotLine) {
+    lines.push("");
+    lines.push(slotLine);
+  }
+  for (const group of HELP_GROUPS) {
+    lines.push("");
+    lines.push(`${out("label", group.title)} \u2014 ${group.blurb}:`);
+    for (const name of group.commands) {
+      const meta = commandMeta(name);
+      const planned = meta.planned ? "   (planned)" : "";
+      lines.push(`  ${out("cmd", name.padEnd(10))} ${meta.summary}${planned}`);
+      lines.push(`               ${out("comment", meta.example)}`);
+    }
+  }
+  lines.push("");
+  lines.push("ONE bin: mm-harness is the only command. Platform is auto-detected; the positional target forces it");
+  lines.push("(mm-harness launch ios); platform-specific needs are FLAGS on the same command. Human happy path = the bare");
+  lines.push("command; agents add depth via flags (--json, --target, ports).");
+  lines.push("");
+  lines.push("SETUP \u2014 tab-completion (zsh + bash), sourced from the bundled scripts:");
+  lines.push("  mm-harness completions install   # print the lines to add to ~/.zshrc / ~/.bashrc");
+  lines.push("");
+  lines.push("DEV/PROD \u2014 the global npm install is prod; set MM_HARNESS_BIN to a dev checkout to override:");
+  lines.push("  MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # unset = the installed/global bin");
+  lines.push("");
+  lines.push("See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).");
+  return `${lines.join("\n")}
+`;
+}
+async function delegate(argv) {
+  try {
+    return await recipeMain(argv);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : 1;
+  }
+}
+function translateActionsRaw(argv) {
+  const rest = argv.slice(1).filter((arg) => arg !== "--raw");
+  const withJson = rest.includes("--json") ? rest : [...rest, "--json"];
+  return ["manifest", ...withJson];
+}
+const program = new Command();
+program.name("mm-harness").description("the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay").helpOption("-h, --help", "Show grouped help").showHelpAfterError("(run `mm-harness --help` for the full surface)").configureHelp({ formatHelp: () => groupedHelp() });
+for (const command of REAL) {
+  program.command(command.name).description(command.summary).allowUnknownOption().helpOption(false).argument("[args...]").action(async () => {
+    const ddIdx = rawArgv.indexOf("--");
+    const flagsBeforeSep = ddIdx === -1 ? rawArgv : rawArgv.slice(0, ddIdx);
+    if (flagsBeforeSep.includes("--help") || flagsBeforeSep.includes("-h")) {
+      process.stdout.write(`${command.helpText}
+`);
+      process.exit(0);
+    }
+    if (command.name === "update") {
+      process.exit(await handleUpdate(rawArgv.slice(1)));
+    }
+    const argv = command.name === "actions" && rawArgv.includes("--raw") ? translateActionsRaw(rawArgv) : rawArgv;
+    process.exit(await delegate(argv));
+  });
+}
+const HIDDEN = ["completion-candidates"];
+for (const name of HIDDEN) {
+  program.command(name, { hidden: true }).allowUnknownOption().helpOption(false).argument("[args...]").action(async () => {
+    process.exit(await delegate(rawArgv));
+  });
+}
+program.command("completions").description("Install/print bundled shell tab-completion (zsh + bash)").allowUnknownOption().helpOption(false).argument("[args...]").action(() => {
+  const script = path.join(packageRoot, "scripts", "install-completions.sh");
+  const result = spawnSync("bash", [script, ...rawArgv.slice(1)], { stdio: "inherit" });
+  process.exit(result.status ?? 1);
+});
+for (const retired of RETIRED) {
+  program.command(retired.name).description(`${retired.name} is retired (see teaching error)`).allowUnknownOption().helpOption(false).argument("[args...]").action(async () => {
+    if (retired.name === "live") {
+      const adapterIdx = rawArgv.indexOf("--adapter");
+      const aliasIdx = rawArgv.indexOf("-a");
+      const adapterVal = adapterIdx !== -1 ? rawArgv[adapterIdx + 1] : aliasIdx !== -1 ? rawArgv[aliasIdx + 1] : void 0;
+      if (adapterVal === "mobile" || adapterVal === "android") {
+        process.exit(await delegate(rawArgv));
+        return;
+      }
+    }
+    console.error(retired.message);
+    process.exit(2);
+  });
+}
+const NUDGE_SKIP = ["update", "completions", "completion-candidates"];
+if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
+  setImmediate(() => void maybeNudge());
+}
+if (rawArgv.length === 0) {
+  process.stdout.write(groupedHelp());
+  process.exit(0);
+}
+await program.parseAsync(process.argv);