@deeeed/metamask-harness 0.17.2 → 0.17.3

package/dist/harness.js

@@ -71,6 +71,7 @@ function parseHarnessArgs(args) {
   const forward = [];
   let adapter;
   let json = false;
+  let quiet = false;
   let separator = false;
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -86,6 +87,10 @@ function parseHarnessArgs(args) {
       json = true;
       continue;
     }
+    if (arg === "--quiet") {
+      quiet = true;
+      continue;
+    }
     if (arg === "--adapter" || arg === "--platform") {
       const value = args[i + 1];
       if (arg === "--adapter") {
@@ -116,7 +121,7 @@ function parseHarnessArgs(args) {
     }
     forward.push(arg);
   }
-  return { adapter, json, forward };
+  return { adapter, json, quiet, forward };
 }
 const ADAPTER_DETECT_NEXT = "cd into a MetaMask checkout or pass --target <path>, or force it with --adapter <mobile|extension|core>";
 function detectAdapter(target) {
@@ -276,12 +281,14 @@ async function handleHarness(argv) {
     return 2;
   }
   const harnessAction = action;
-  const { adapter: parsedAdapter, json, forward } = parseHarnessArgs(argv.slice(1));
+  const { adapter: parsedAdapter, json, quiet, forward } = parseHarnessArgs(argv.slice(1));
   const rawTarget = argValue(forward, "--target");
   const target = path.resolve(rawTarget ?? process.cwd());
   const adapter = parsedAdapter ?? detectAdapter(target);
   if (!adapter || !isAdapter(adapter)) {
-    if (json) {
+    if (quiet) {
+      return 2;
+    } else if (json) {
       const detectError = adapter ? { code: "UNSUPPORTED_PLATFORM", message: `unsupported platform: ${adapter}`, userAction: "pass --adapter <mobile|extension|core> to specify a supported adapter" } : { code: "ADAPTER_DETECTION_FAILED", message: `could not detect the MetaMask repo type for ${target}`, userAction: ADAPTER_DETECT_NEXT };
       console.log(harnessSummary(harnessAction, void 0, target, "fail", 2, false, detectError));
     } else {
@@ -305,7 +312,9 @@ async function handleHarness(argv) {
   }
   const dispatch = resolveHarnessDispatch(adapter, harnessAction, target);
   if ("error" in dispatch) {
-    if (json) {
+    if (quiet) {
+      return 1;
+    } else if (json) {
       console.log(
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "DISPATCH_UNAVAILABLE",
@@ -321,14 +330,16 @@ async function handleHarness(argv) {
     }
     return 1;
   }
-  if (!json) {
+  if (!json && !quiet) {
     const detected = autoDetected ? ", auto-detected" : "";
     console.error(`\u2192 ${harnessAction} (${adapter}${detected}) \u2014 target: ${target}`);
   }
   const start = Date.now();
   if (shellLeafMissing(dispatch.command)) {
     const message = missingShellLeafMessage(dispatch.command);
-    if (json) {
+    if (quiet) {
+      return 1;
+    } else if (json) {
       console.log(
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "HARNESS_SPAWN_FAILED",
@@ -348,12 +359,14 @@ async function handleHarness(argv) {
   const result = spawnSync(dispatchBin, dispatchArgs, {
     // Default: stream child output verbatim (byte-identical to the skill path).
     // --json: route child output to our stderr so stdout carries only the summary.
-    stdio: json ? ["inherit", 2, "inherit"] : "inherit",
+    stdio: quiet ? "ignore" : json ? ["inherit", 2, "inherit"] : "inherit",
     env: process.env
   });
   const seconds = ((Date.now() - start) / 1e3).toFixed(1);
   if (result.error) {
-    if (json) {
+    if (quiet) {
+      return 1;
+    } else if (json) {
       console.log(
         harnessSummary(harnessAction, adapter, target, "fail", 1, autoDetected, {
           code: "HARNESS_SPAWN_FAILED",
@@ -368,7 +381,9 @@ async function handleHarness(argv) {
     return 1;
   }
   const exitCode = result.status ?? 1;
-  if (json) {
+  if (quiet) {
+    return exitCode;
+  } else if (json) {
     console.log(
       harnessSummary(
         harnessAction,

package/dist/mm-harness-cli.js

@@ -76,11 +76,11 @@ Example:
   },
   {
     name: "actions",
-    summary: "List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).",
+    summary: "Discover typed single operations and their fields.",
     example: "mm-harness actions --adapter mobile",
     helpText: `mm-harness actions [query] [flags]
 
-  List the action vocabulary + field schemas for the checkout adapter.
+  Discover typed single operations and their field schemas for this checkout.
 
   query                              Search names, categories, fields, and descriptions (typo-tolerant)
   --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
@@ -152,11 +152,11 @@ Example (real actions; run mm-harness actions for this checkout's full set):
   },
   {
     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.",
+    summary: "Browse reusable parameterized action sequences.",
     example: "mm-harness flows",
     helpText: `mm-harness flows [flags]
 
-  Browse the reusable flow library. Flows resolve across libraries by precedence
+  Browse reusable parameterized action sequences. Flows resolve 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.
 
@@ -169,11 +169,12 @@ Example:
   },
   {
     name: "run",
-    summary: "Validate + run a recipe and write evidence (summary/trace/artifacts). --plan validates + prints the plan, touching nothing.",
+    summary: "Execute a complete proof and write its evidence.",
     example: "mm-harness run recipe.json",
     helpText: `mm-harness run <recipe.json> [flags]
 
-  Validate + run a recipe and write evidence (summary / trace / artifacts).
+  Validate and execute a complete proof, then write summary, trace, diagnostics,
+  and artifacts. A recipe may use actions directly or call reusable flows.
 
   --list                             List everything invocable for the adapter (actions + flows); no <recipe> needed
   --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.

package/dist/run-diagnostics.js

@@ -52,7 +52,6 @@ function isRunDiagnosticsDocument(value) {
 function finishRunDiagnostics(baseline, result) {
   if (!baseline) return result;
   try {
-    stopRunDiagnostics(baseline);
     const bufferedIssues = baseline.mobileIssueBuffer ? collectMobileIssueBuffer(baseline.mobileIssueBuffer.projectRoot) : void 0;
     const diagnostics = collectRunDiagnostics(baseline, bufferedIssues);
     const artifactsDir = path.dirname(result.summaryPath);
@@ -83,9 +82,6 @@ function finishRunDiagnostics(baseline, result) {
     };
   }
 }
-function stopRunDiagnostics(baseline) {
-  void baseline;
-}
 function collectRunDiagnostics(baseline, bufferedIssues) {
   const stat = safeStat(baseline.source.path);
   const source = {
@@ -261,6 +257,5 @@ export {
   collectRunDiagnostics,
   finishRunDiagnostics,
   formatRunDiagnosticsForHuman,
-  readRunDiagnosticsDocument,
-  stopRunDiagnostics
+  readRunDiagnosticsDocument
 };

package/docs/ADAPTER-SURFACE.md

@@ -1,119 +1,26 @@
-# The adapter surface — one seam for per-platform behavior
+# Adapter surface
 
-`mm-harness` runs against three platforms (mobile | extension | core). The
-danger is that every command re-derives "what does this platform do?" with its
-own `if (adapter === 'mobile') … else if (adapter === 'extension') …` ladder.
-When it does, a platform gets forgotten in one command but not another — the
-class of bug where `doctor` reported a live runtime section for mobile only,
-`stop` refused every non-mobile adapter, and `logs` knew a single extension log
-file instead of all three. Those are *platform-blind* commands.
+`src/adapters/surface.ts` is the typed seam for Mobile, Extension, and Core.
+Commands ask it for platform behavior instead of re-deriving platform rules.
 
-The **adapter surface** is the fix: one interface per platform, resolved through
-a registry, that owns the behavior a command would otherwise branch on.
+Each adapter implements:
 
-## The interface
+- runtime readiness;
+- slot-owned ports;
+- dev-server lifecycle;
+- log sources;
+- launch/recovery hints;
+- headless capability.
 
-`src/adapters/surface.ts` defines `AdapterSurface` and the registry
-`getAdapterSurface(adapter)`. Each platform ships one implementation:
+Implementations live in `src/adapters/{mobile,extension,core}/surface.ts`.
+Platform-specific shell and Node operations live under `adapters/<platform>/`.
 
-- `src/adapters/mobile/surface.ts`
-- `src/adapters/extension/surface.ts`
-- `src/adapters/core/surface.ts`
+When adding behavior:
 
-```ts
-interface AdapterSurface {
-  readonly adapter: MetaMaskRecipeAdapter;
-  readonly headless: boolean;                       // core runs no app/dev server
-  resolveSlotPorts(target: string): void;           // context > pool > formula (no-op for core)
-  runtimeStatus(target: string): Promise<AdapterRuntimeStatus>; // read-only readiness for doctor
-  devServer: {
-    describe(): string;                             // "Metro" | "webpack watcher" | "no dev server (headless)"
-    stop(target: string): AdapterDevServerStop;     // idempotent, slot-scoped; headless = teach
-  };
-  logSources(target: string): AdapterLogSource[];   // ordered candidate log files (empty for core)
-  hints: { launch: string; relaunch: string };      // platform-phrased Next: hints
-}
-```
+1. Extend `AdapterSurface` only when every platform needs the concept.
+2. Implement all three adapters; Core should explicitly report headless/N/A.
+3. Call the surface from the command instead of adding adapter conditionals.
+4. Add a registry-completeness contract and a real affected-platform check.
 
-`runtimeStatus` returns a normalized shape so `doctor` renders one line the same
-way for every platform:
-
-```ts
-interface AdapterRuntimeStatus {
-  decision: string;
-  reasonCode?: string;
-  reasons: string[];
-  deps?: string;
-  devServer?: { label: string; status: string };    // absent for headless core
-}
-```
-
-The implementations are thin: they delegate to the readiness/port plumbing that
-already existed (`decideExtensionReadiness`, `mobileRuntimeStatus`, the slot-port
-resolvers and the webpack-watcher stop, all re-homed to
-`src/adapters/slot-ports.ts`). The surface is an organizing seam, not a rewrite.
-
-## The rule
-
-**A command never branches on adapter for behavior the surface owns.**
-
-- Do not write `if (adapter === 'core')` — ask `surface.headless`.
-- Do not write `adapter === 'mobile' ? metroPorts() : extensionPorts()` — call
-  `surface.resolveSlotPorts(target)`.
-- Do not print `adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness
-  launch'` — use `surface.hints.launch`.
-
-A new platform behavior is added by **extending the surface** (a new member on
-the interface plus its three implementations), never by adding another branch to
-a command. TypeScript then makes it impossible to ship a platform that forgot the
-new member, because each implementation is annotated `: AdapterSurface`.
-
-What the surface deliberately does **not** own: a command may still branch on
-adapter for a *mechanism* that is genuinely platform-specific and not part of the
-interface — e.g. `fixtures set` uses a shell arm on mobile and the engine path on
-extension. Those branches select a mechanism; they never re-derive readiness,
-ports, log locations, dev-server lifecycle, or Next: phrasing, which are the
-surface's responsibility.
-
-## Migration status
-
-Every command that used to branch on adapter now resolves through the surface:
-
-| command | surface-backed | uses |
-| --- | --- | --- |
-| `doctor` | yes | `resolveSlotPorts` + `runtimeStatus` (mobile/extension/core runtime section) |
-| `launch` | yes | `resolveSlotPorts` |
-| `stop` | yes | `resolveSlotPorts` + `devServer.stop` (+ headless teaching) |
-| `logs` | yes | `logSources` + `hints.launch` + `headless` |
-| `debug` | yes | `headless` + `hints.relaunch` (core teaching); flag semantics stay per-command |
-| `fixtures` | yes | `headless` + `hints` (retry/launch); the set *mechanism* stays per-platform |
-| `run` / `call` | n/a | engine path; core-headless is handled by the heal contract, not the surface |
-| `flows` | no (by design) | recipe-library flows are adapter-global; not a platform-owned behavior |
-| `completion-candidates` | partial | `actions` scope to the detected checkout adapter; `flows` are adapter-global |
-
-`flows` is intentionally not surface-backed: a recipe-library flow can compose
-actions across platforms, so flows are adapter-global by design rather than a
-platform-blind gap. `completion-candidates actions` already resolves the adapter
-from the checkout context (cwd/`--target`); only the adapter-global `flows`
-candidates are unscoped, matching the flows model.
-
-## How this composes with the UX principles
-
-`docs/UX-PRINCIPLES.md` principle 1 (*Context-aware by default* — "output is
-scoped to the platform… help, flag lists, and completion candidates shrink to
-what applies here") states the intent. The adapter surface is its **enforcement
-mechanism**: a command that resolves platform behavior through the surface is
-context-aware by construction, and one that hand-rolls an adapter ladder is the
-exact failure principle 1 warns against. When adding a command or output path,
-satisfy principle 1 by going through the surface.
-
-## Adding a platform behavior — checklist
-
-1. Add the member to `AdapterSurface` in `src/adapters/surface.ts`.
-2. Implement it in all three `src/adapters/*/surface.ts` (TypeScript will not
-   compile until you do).
-3. Have the command call `getAdapterSurface(adapter).<member>` instead of
-   branching.
-4. Cover the closed blind spot with a contract test (see
-   `tests/contract/adapter-surface.test.sh`), and keep the registry-completeness
-   assertion green.
+Mechanisms unique to one command may remain platform-specific. Shared readiness,
+ports, logs, lifecycle, and recovery language belong on the surface.

package/docs/CLI-ERGONOMICS-HUMAN-QA.md

@@ -3,11 +3,27 @@
 Run this from each product checkout before a release. Verify the visible outcome,
 not only the exit code.
 
+Run the non-visual gate first:
+
+```bash
+yarn qa:human \
+  --extension /path/to/metamask-extension \
+  --mobile /path/to/metamask-mobile \
+  --core /path/to/metamask-core \
+  --artifacts-dir temp/human-qa
+```
+
+It verifies live readiness, installed runtime, debugger target resolution, smoke
+evidence, and unchanged tracked product source. The checks below cover outcomes
+that still require eyes or an intentional source edit.
+
 ## Common
 
 - [ ] `mm-harness --version` prints the candidate version.
 - [ ] `mm-harness doctor` detects the correct product and reports only current
       configuration.
+- [ ] Without `capture-helper`, `doctor` names the CDP or simulator/ADB screenshot
+      fallback and says video is unavailable.
 - [ ] A misspelled flag explains the error and gives a runnable next command.
 - [ ] `mm-harness actions` and `mm-harness flows` return useful, bounded discovery.
 - [ ] `mm-harness fixtures set` either applies the fixture or names the missing

package/docs/UX-PRINCIPLES.md

@@ -5,7 +5,7 @@ a PR that adds a command or output path is checked against each one.
 
 **Scope: the HUMAN surface.** The agent contract is exempt and inviolable: under
 `--json`, stdout carries exactly one machine-readable envelope — no color, no
-banners, no decorative lines, schema per CLI-SPEC.md. Progress/streaming exists
+banners, no decorative lines. Progress/streaming exists
 for agents too, but only ever on stderr. When a rule below conflicts with envelope
 purity, the envelope wins.
 

package/docs/VIDEO-DEMO-VALIDATION.md

@@ -1,62 +1,74 @@
 # Video demo validation
 
-Candidate: local packed `@deeeed/metamask-harness` 0.17.1 installed globally.
-Run commands from the named checkout; product/ports are auto-detected.
+Use this checklist against the installed release before recording. Each checkout
+auto-detects its platform, ports, and slot; the paths below are placeholders only.
+
+```bash
+export EXTENSION_CHECKOUT=/path/to/metamask-extension
+export MOBILE_CHECKOUT=/path/to/metamask-mobile
+export CORE_CHECKOUT=/path/to/core
+```
 
 ## Common
 
-- [x] `mm-harness --version` prints `0.17.1` from the global npm install.
-- [x] `yarn check` passes.
-- [x] No `package-lock.json`; Yarn state is valid.
-- [x] Current source/docs contain no compatibility or removed-command paths.
-- [x] `doctor` reports current runtime fields only.
-- [x] Recipe results print diagnostics and absolute artifact paths inline.
+- [ ] `mm-harness --version` prints the intended release.
+- [ ] `mm-harness doctor` explains any unavailable capability and gives one next step.
+- [ ] Recipe results print diagnostics and absolute artifact paths inline.
+- [ ] `git status --short` is unchanged in each product checkout after validation.
 
-## Extension (`mme-2`)
+## Extension
 
-- [x] `mm-harness doctor` reports healthy CDP and active webpack watcher.
-- [x] `mm-harness run runner.smoke --artifacts-dir temp/final-demo-smoke` passes.
-- [x] Smoke prints six absolute evidence paths and `diagnostics: CLEAN`.
-- [x] `mm-harness debug` connects native DevTools to the active slot target.
-- [x] Fullscreen and sidepanel targets are selectable.
-- [x] Two source edits plus revert compiled incrementally with the same watcher;
-      browser refresh showed each change without relaunch.
+```bash
+cd "$EXTENSION_CHECKOUT"
+mm-harness launch --build --verify
+mm-harness doctor
+mm-harness actions positions
+mm-harness flows
+mm-harness run runner.smoke --artifacts-dir temp/demo
+mm-harness run wallet.smoke --artifacts-dir temp/wallet-demo
+mm-harness logs --source app
+mm-harness debug
+```
 
-## Mobile (`mm-1`, iOS)
+- [ ] Launch keeps an incremental webpack watcher alive.
+- [ ] Two small source edits compile incrementally; browser refresh shows both changes.
+- [ ] `debug` connects to the active slot's MetaMask target and opens Console.
+- [ ] `logs --source app` shows extension logs; `--source dapp` and `--source webpack`
+      show their separate streams.
+- [ ] Each recipe prints `diagnostics: CLEAN` or expands every warning/error inline.
+- [ ] Each recipe prints absolute paths for its report, trace, diagnostics, screenshots,
+      and artifact manifest.
 
-- [x] `mm-harness install` writes metadata only; product checkout remains clean.
-- [x] `mm-harness fixtures set` reads the canonical fixture and unlocks `dev1`.
-- [x] `mm-harness call metamask.wallet.ensure_unlocked` passes from the global package.
-- [x] `mm-harness verify` passes after fixture setup.
-- [x] `mm-harness status` reports `WalletView`, unlocked wallet, selected account,
-      and fixture `READY`.
-- [ ] During the recording, visually confirm the expected simulator is foregrounded.
+## Mobile
 
-## Core (`core-1`)
+```bash
+cd "$MOBILE_CHECKOUT"
+mm-harness launch ios --verify
+mm-harness fixtures set
+mm-harness call metamask.wallet.ensure_unlocked
+mm-harness status
+mm-harness logs --source app
+```
 
-- [x] `mm-harness doctor` reports the headless controller ready.
-- [x] Canonical wallet fixture is present.
-- [x] `mm-harness run perps.smoke --artifacts-dir temp/final-demo-smoke` passes.
-- [x] Positions, orders, and account state are read through the controller.
-- [x] Evidence prints absolute paths; diagnostics correctly reports `N/A` for headless Core.
+- [ ] The intended simulator is running; focus changes only when explicitly requested.
+- [ ] Fixture setup reads the canonical checkout fixture and unlocks the wallet.
+- [ ] Status reports the live route, wallet state, account, and fixture readiness.
+- [ ] App logs are separate from Metro logs (`mm-harness logs --source metro`).
 
-## Recording sequence
+## Core
 
 ```bash
-# Extension
-cd /Users/deeeed/farmslot/repos/mme-2
+cd "$CORE_CHECKOUT"
 mm-harness doctor
-mm-harness actions positions
-mm-harness flows
 mm-harness run runner.smoke --artifacts-dir temp/demo
+```
 
-# Mobile
-cd /Users/deeeed/farmslot/repos/mm-1
-mm-harness launch ios
-mm-harness fixtures set
-mm-harness call metamask.wallet.ensure_unlocked
+- [ ] Doctor reports the headless controller ready.
+- [ ] The canonical wallet fixture supplies the default account.
+- [ ] Evidence paths are absolute; diagnostics is explicitly `N/A` for headless Core.
 
-# Core
-cd /Users/deeeed/farmslot/repos/core-1
-mm-harness run perps.smoke --artifacts-dir temp/demo
-```
+## Recording path
+
+Show the Extension discovery and proof commands, then the equivalent Mobile and Core
+commands. The useful story is: one auto-detected CLI, reusable team libraries,
+parameterized recipes, app diagnostics, and proof artifacts that a human can inspect.