@deeeed/metamask-harness 0.13.0 → 0.14.1

package/docs/CLI-SPEC.md

@@ -54,6 +54,7 @@ Name `metamask-recipe` → **REMOVE** (becomes `mm-harness`; no alias). Capabili
 | `resolve-extension` | Resolve the extension id | extension | advanced | **KEEP-INTERNAL** — internal plumbing; called inside `launch`/`launch --verify` |
 | `ensure-ready` | Ensure extension ready (close home tabs) | extension | advanced | **KEEP-INTERNAL** — becomes internal function inside `launch`/`verify` self-healing path |
 | `run` | Run a recipe, write evidence | all | PROVE | ROUTES-NOW |
+| `check diff` | Run bounded repo-local validation for the active git diff | all | PROVE | ROUTES-NOW |
 | `self-test` | Package-wiring smoke (no device) | mobile+extension | advanced | **KEEP-INTERNAL** — CI smoke test; callable via `package.json` scripts; hidden from `--help` |
 | `flows` | List/promote library flows | all | DISCOVER | ROUTES-NOW |
 | `harness install\|verify\|cleanup\|live` | Runtime overlay lifecycle | all (core: no live) | OVERLAY | ROUTES-NOW (`harness` prefix → top-level); `live` **REMOVE** — dissolved into `launch --verify` |
@@ -437,6 +438,30 @@ Readiness check for a checkout without launching the app. Doctor is the single p
 
 ---
 
+## `check diff` (REAL → bounded local validation)
+
+**Synopsis:** `mm-harness check diff [flags]`
+
+Runs bounded validation against the target checkout's active git diff. This is
+for local PR readiness loops and agent templates; it does not launch an app or
+run a recipe.
+
+| Flag | Values | Default | Purpose |
+| --- | --- | --- | --- |
+| `--target <repo>` | path | cwd | MetaMask checkout to inspect |
+| `--adapter <adapter>` / `--platform <adapter>` | mobile\|extension\|core | auto-detect | Adapter label for the report |
+| `--base <ref>` | git ref | GitHub PR base, then remote HEAD, then `origin/develop`/`origin/main`/local fallback | Diff base |
+| `--profile <profile>` | `fast`\|`full` | `fast` | `fast` runs changed-file ESLint/Prettier/Jest; `full` also runs repo typecheck when available |
+| `--artifacts-dir <dir>` | path | `temp/recipe/check-diff/<timestamp>` | Writes summary and per-check logs |
+| `--json` | bool | false | Print the summary envelope to stdout |
+
+**Artifacts:** `validation-summary.json`, `validation-summary.md`, and one log
+per executed check.
+
+**Exit:** 0 pass · 2 bad args / not a git checkout · 5 validation failure.
+
+---
+
 ## `--device <id>` — first-class mobile device targeting (REAL)
 
 `--device` is the uniform mobile device selector on `run`, `call`, `doctor`, and `fixtures`. Pass the **adb serial** for Android (from `adb devices`) or the **UDID / simulator name** for iOS. The harness resolves the adb serial to the Metro CDP target identity internally — users never need to know or set `ANDROID_DEVICE='Pixel 6 - 16 - API 36'`.

package/docs/architecture.md

@@ -216,7 +216,7 @@ describes **how an agent should work**, it belongs in skills.
 | `adapters/extension/` | Runner-owned Extension launch/live/watch/windows/wallet-state/readiness helpers (orchestration) and verify (recipe) copied into installed harnesses. |
 | `adapters/shared/path-defaults.json` | Single source for default `recipeHarnessRoot` and `recipeRuntimeDir`. |
 | `adapters/shared/harness-path.sh`, `src/paths.ts` | Shell and TypeScript accessors for those defaults plus validation. |
-| `library/recipes/` | Reusable smoke/action-validation recipes only. Task-specific proof recipes stay task-local. |
+| `library/recipes/` | Reusable smoke/runner.action-validation recipes only. Task-specific proof recipes stay task-local. |
 | `library/library.json`, `library/flows/` | Canonical recipe library: minimal, stable flows recipes can `call`. Personal/team libraries shadow it by default — see [Recipe Libraries](recipe-libraries.md). |
 | `docs/` | Runner architecture, contracts, and operational conventions. |
 
@@ -377,7 +377,7 @@ TypeScript or a focused `.mjs` adapter and keep shell as the launcher.
 5. Use official `ui.*` actions and screenshot claims for visible acceptance
    criteria; do not add task-specific `metamask.*` actions for exact copy,
    styling, ticket IDs, or one-off selectors.
-6. Update smoke/action-validation recipes only when the capability is reusable.
+6. Update smoke/runner.action-validation recipes only when the capability is reusable.
 
 ## Standalone use first; farm later
 

package/docs/live-adapter-contract.md

@@ -85,7 +85,7 @@ domain capability useful across many tasks, such as `metamask.perps.start_state`
 `metamask.perps.place_order`, `metamask.perps.close_positions`, or
 `metamask.perps.assert_positions`.
 
-`ui.scroll` is part of the current executable contract and action-validation must
+`ui.scroll` is part of the current executable contract and runner.action-validation must
 prove both normal scrolling and `scroll_into_view` before screenshot capture.
 `ui.gesture` is intentionally not advertised yet; drag/swipe proof must wait
 until the shared runtime and this runner expose and validate that action on both

package/docs/recipe-libraries.md

@@ -101,19 +101,20 @@ each user-visible step takes. The runner has no benchmark verb: timings are just
 the per-node `duration`s in a passing run's `trace.json`, so a flow is comparable
 across runs only when you pin the run (same device, healing off) and keep the node
 graph stable. The repo ships one canonical example,
-`library/recipes/perps-performance.mobile.recipe.json` — unlock → open the Perps
+`library/recipes/perps/performance.mobile.recipe.json` — unlock → open the Perps
 market list → read live state → open a market detail. This walkthrough copies it
 into a library of your own and retargets it to your journey. A peer engineer can
-follow it verbatim; the same steps run as the `perps-performance-recipe` contract
+follow it verbatim; the same steps run as the `perps.performance-recipe` contract
 test.
 
 ### 1. Scaffold a personal library
 
 A library is a directory with a `library.json` marker. Keep reusable `flows/`
-(referenced via `call`) beside a `recipes/` folder for the full flows you run:
+(referenced via `call`) beside a domain-grouped `recipes/` folder for the full
+flows you run:
 
 ```bash
-mkdir -p ~/my-recipes/flows ~/my-recipes/recipes
+mkdir -p ~/my-recipes/flows ~/my-recipes/recipes/my-perps
 cat > ~/my-recipes/library.json <<'JSON'
 { "kind": "recipe-library", "schema_version": 1, "name": "mydev", "owner": "mydev" }
 JSON
@@ -130,8 +131,8 @@ it works headlessly (CI, a scratch checkout) and so the path is unambiguous.
 Copy it out of your runner checkout's `library/recipes/`:
 
 ```bash
-cp library/recipes/perps-performance.mobile.recipe.json \
-   ~/my-recipes/recipes/my-perps-performance.mobile.recipe.json
+cp library/recipes/perps/performance.mobile.recipe.json \
+   ~/my-recipes/recipes/my-perps/performance.mobile.recipe.json
 ```
 
 ### 3. Edit the nodes to your journey
@@ -211,33 +212,35 @@ field on flow catalog entries — not yet in the protocol.
 
 ### 4. Run it and read the timings
 
-Validate statically **by name** first — `run` probes each library source's `recipes/`
-directory in precedence order (personal → team → canonical), so `my-perps-performance`
-resolves from `~/my-recipes/recipes/` without you spelling out the path:
+Validate statically **by name** first — `run` probes each library source's
+`recipes/` directory in precedence order (personal → team → canonical), so
+`my-perps.performance` resolves from
+`~/my-recipes/recipes/my-perps/performance.mobile.recipe.json` without you
+spelling out the path:
 
 ```bash
 # Static validation by NAME — resolves from the personal library via --library.
-mm-harness run my-perps-performance \
+mm-harness run my-perps.performance \
   --library mydev=~/my-recipes --plan --adapter mobile
 
 # Zero-flag personal-library: when ~/my-recipes is placed at
 # $FARMSLOT_HOME/recipe-library (default ~/.farmslot/recipe-library), the runner
 # discovers it automatically and run-by-name works without --library:
-mm-harness run my-perps-performance --plan --adapter mobile
+mm-harness run my-perps.performance --plan --adapter mobile
 
 # Pinned live run — same device, healing OFF, so durations are comparable.
-mm-harness run my-perps-performance \
+mm-harness run my-perps.performance \
   --library mydev=~/my-recipes \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts
 
 # Canonical start-state variants — same installed app, no rebuild.
-mm-harness run app-lifecycle-android-smoke \
+mm-harness run app.lifecycle.android-smoke \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/lifecycle-smoke
-mm-harness run perps-performance-warm-start \
+mm-harness run perps.performance.warm-start \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/warm
-mm-harness run perps-performance-background-resume \
+mm-harness run perps.performance.background-resume \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/background
-mm-harness run perps-performance-cold-start \
+mm-harness run perps.performance.cold-start \
   --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/cold
 
 # Per-node durations to diff across runs (trace.json is an array of entries, or
@@ -249,7 +252,7 @@ node -e 'const t=require("./artifacts/trace.json"); \
 A miss with `--library` names the sources that were searched, so you can tell at a
 glance whether a typo or a missing library entry caused the failure.
 
-Run `app-lifecycle-android-smoke` first when validating a new Android slot; it
+Run `app.lifecycle.android-smoke` first when validating a new Android slot; it
 isolates lifecycle control from wallet setup and Perps navigation. The start-state
 variants use the standard outer `app.lifecycle` action. Every
 variant begins with `app.status` so `trace.json` records an idempotent start
@@ -294,5 +297,5 @@ mm-harness run my-perps-with-segment --plan --adapter mobile \
 ```
 
 That resolution — unresolved without the source, `pass` with it — is what the
-`perps-performance-recipe` contract test asserts, alongside the canonical recipe
+`perps.performance-recipe` contract test asserts, alongside the canonical recipe
 resolving by name and the personal mobile copy planning by path and basename.

package/library/actions/extension/platform/cdp.mjs

@@ -46,14 +46,17 @@ function cdpPort(input) {
   return port;
 }
 
-function extensionTarget(targets, extensionId = null) {
-  return (Array.isArray(targets) ? targets : []).find((target) => {
+export function extensionTarget(targets, extensionId = null) {
+  const candidates = (Array.isArray(targets) ? targets : []).filter((target) => {
     if (target?.type !== 'page') return false;
     if (!String(target?.url ?? '').startsWith('chrome-extension://')) return false;
-    if (!String(target.url).includes('/home.html')) return false;
+    if (!String(target.url).includes('/home.html') && !String(target.url).includes('/sidepanel.html')) return false;
     if (extensionId && extensionIdFromTarget(target) !== extensionId) return false;
     return Boolean(target.webSocketDebuggerUrl);
-  }) ?? null;
+  });
+  return candidates.find((target) => String(target.url).includes('/home.html')) ??
+    candidates.find((target) => String(target.url).includes('/sidepanel.html')) ??
+    null;
 }
 
 

package/library/recipes/{app-lifecycle-android-smoke.mobile.recipe.json → app/lifecycle.android-smoke.mobile.recipe.json}

@@ -68,7 +68,7 @@
         },
         "screenshot-after": {
           "action": "ui.screenshot",
-          "path": "screenshots/app-lifecycle-android-smoke.png",
+          "path": "screenshots/app.lifecycle.android-smoke.png",
           "intent": "Capture the app after Android lifecycle foreground",
           "detail": "Visual proof that the selected device is displaying the relaunched app.",
           "flow": "evidence",

package/library/recipes/{perps-performance.mobile.recipe.json → perps/performance.mobile.recipe.json}

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "title": "MetaMask Mobile Perps performance flow",
-  "description": "Canonical measured flow for MetaMask Mobile Perps: setup unlocks the wallet, startState records the stable status, then the measured workflow opens the Perps market list, reads live state, and opens a market detail. Timings live in trace.json as each node's duration; there is no built-in benchmark verb. Run pinned so numbers are comparable: `mm-harness run perps-performance --device <serial> --heal off`. Optional testnet order placement is intentionally omitted because a live order would make the flow destructive and non-repeatable; add metamask.perps.place_order + close in a personal copy when you want to measure the trade path.",
+  "description": "Canonical measured flow for MetaMask Mobile Perps: setup unlocks the wallet, startState records the stable status, then the measured workflow opens the Perps market list, reads live state, and opens a market detail. Timings live in trace.json as each node's duration; there is no built-in benchmark verb. Run pinned so numbers are comparable: `mm-harness run perps.performance --device <serial> --heal off`. Optional testnet order placement is intentionally omitted because a live order would make the flow destructive and non-repeatable; add metamask.perps.place_order + close in a personal copy when you want to measure the trade path.",
   "startState": {
     "action": "app.status",
     "intent": "Record the stable run start status after wallet setup",

package/library/recipes/perps/smoke.core.recipe.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask core Perps smoke",
+  "description": "Non-mutating Perps domain smoke for the headless core adapter: instantiates the Perps controller and reads live positions, orders, and account state.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "read-positions",
+          "intent": "Resolve the core checkout and report headless compatibility mode"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "mode": "all",
+          "next": "read-orders",
+          "intent": "Read live Perps positions from the headless controller"
+        },
+        "read-orders": {
+          "action": "metamask.perps.read_orders",
+          "mode": "all",
+          "next": "read-account",
+          "intent": "Read live Perps open orders from the headless controller"
+        },
+        "read-account": {
+          "action": "metamask.perps.read_account",
+          "next": "done",
+          "intent": "Read live Perps account state from the headless controller"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the core Perps smoke"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps/smoke.extension.recipe.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Extension Perps smoke",
+  "description": "Non-mutating Perps domain smoke for MetaMask Extension: verifies CDP, unlocks if needed, opens the Perps page, and reads live Perps positions and orders.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "cdp",
+          "intent": "Resolve the Extension checkout and adapter status before Perps proof"
+        },
+        "cdp": {
+          "action": "cdp.target",
+          "required": true,
+          "timeout_ms": 15000,
+          "next": "ensure-unlocked",
+          "intent": "Confirm the Extension CDP runtime is reachable"
+        },
+        "ensure-unlocked": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "timeout_ms": 45000,
+          "next": "open-perps",
+          "intent": "Ensure the wallet is unlocked before opening Perps"
+        },
+        "open-perps": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "next": "read-positions",
+          "intent": "Open the Perps page through the stable page alias"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "next": "read-orders",
+          "intent": "Read live Perps positions without mutating account state"
+        },
+        "read-orders": {
+          "action": "metamask.perps.read_orders",
+          "next": "done",
+          "intent": "Read live Perps open orders without mutating account state"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the Extension Perps smoke"
+        }
+      }
+    }
+  }
+}

package/library/recipes/perps/smoke.mobile.recipe.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile Perps smoke",
+  "description": "Non-mutating Perps domain smoke for MetaMask Mobile: verifies the live bridge, unlocks if needed, opens the Perps market list, and reads live Perps positions and orders.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "cdp",
+          "intent": "Resolve the Mobile checkout and adapter status before Perps proof"
+        },
+        "cdp": {
+          "action": "cdp.target",
+          "required": true,
+          "timeout_ms": 15000,
+          "next": "ensure-unlocked",
+          "intent": "Confirm the React Native debug bridge is reachable"
+        },
+        "ensure-unlocked": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "timeout_ms": 45000,
+          "next": "open-perps",
+          "intent": "Ensure the wallet is unlocked before opening Perps"
+        },
+        "open-perps": {
+          "action": "ui.navigate",
+          "page": "perps",
+          "next": "read-positions",
+          "intent": "Open the Perps market list through the stable page alias"
+        },
+        "read-positions": {
+          "action": "metamask.perps.read_positions",
+          "next": "read-orders",
+          "intent": "Read live Perps positions without mutating account state"
+        },
+        "read-orders": {
+          "action": "metamask.perps.read_orders",
+          "next": "done",
+          "intent": "Read live Perps open orders without mutating account state"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass",
+          "intent": "Finish the Mobile Perps smoke"
+        }
+      }
+    }
+  }
+}

package/library/recipes/{action-validation.extension.recipe.json → runner/action-validation.extension.recipe.json}

@@ -8,9 +8,9 @@
       "nodes": {
         "prepare-files": {
           "action": "command",
-          "cmd": "mkdir -p temp/recipe-action-validation && printf 'E2E_ACTION_VALIDATION extension\\n' > temp/recipe-action-validation/probe.txt && printf '{\"platform\":\"extension\",\"ok\":true}\n' > temp/recipe-action-validation/probe.json && printf 'extension log E2E_ACTION_VALIDATION\\n' > temp/recipe-action-validation/validation.log && echo E2E_ACTION_VALIDATION extension",
+          "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION extension\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"extension\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'extension log E2E_ACTION_VALIDATION\\n' > temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION extension",
           "next": "assert-command-exit",
-          "intent": "Prepare action-validation probe files",
+          "intent": "Prepare runner.action-validation probe files",
           "detail": "Create local files used to prove command/assert/log/artifact actions.",
           "flow": "setup"
         },
@@ -35,7 +35,7 @@
         },
         "assert-file": {
           "action": "assert_file",
-          "path": "temp/recipe-action-validation/probe.txt",
+          "path": "temp/recipe-runner.action-validation/probe.txt",
           "contains": "E2E_ACTION_VALIDATION extension",
           "next": "assert-json",
           "intent": "Verify file assertions work",
@@ -44,7 +44,7 @@
         },
         "assert-json": {
           "action": "assert_json",
-          "path": "temp/recipe-action-validation/probe.json",
+          "path": "temp/recipe-runner.action-validation/probe.json",
           "assert": {
             "path": "$.platform",
             "operator": "eq",
@@ -57,7 +57,7 @@
         },
         "watch-logs": {
           "action": "watch_logs",
-          "path": "temp/recipe-action-validation/validation.log",
+          "path": "temp/recipe-runner.action-validation/validation.log",
           "contains": "E2E_ACTION_VALIDATION",
           "next": "index-artifacts",
           "intent": "Verify log watching works",
@@ -68,7 +68,7 @@
           "action": "index_artifacts",
           "artifacts": [
             {
-              "path": "temp/recipe-action-validation/probe.txt",
+              "path": "temp/recipe-runner.action-validation/probe.txt",
               "type": "log",
               "category": "debug",
               "label": "Extension action validation probe"
@@ -173,7 +173,7 @@
         },
         "ui-screenshot-perps": {
           "action": "ui.screenshot",
-          "path": "screenshots/extension-perps-action-validation.png",
+          "path": "screenshots/extension-perps-runner.action-validation.png",
           "timeout_ms": 5000,
           "next": "wallet-navigate-perps",
           "intent": "Capture Perps visual proof",

package/library/recipes/{action-validation.mobile.recipe.json → runner/action-validation.mobile.recipe.json}

@@ -8,9 +8,9 @@
       "nodes": {
         "prepare-files": {
           "action": "command",
-          "cmd": "mkdir -p temp/recipe-action-validation && printf 'E2E_ACTION_VALIDATION mobile\\n' > temp/recipe-action-validation/probe.txt && printf '{\"platform\":\"mobile\",\"ok\":true}\n' > temp/recipe-action-validation/probe.json && printf 'mobile log E2E_ACTION_VALIDATION\\n' > temp/recipe-action-validation/validation.log && echo E2E_ACTION_VALIDATION mobile",
+          "cmd": "mkdir -p temp/recipe-runner.action-validation && printf 'E2E_ACTION_VALIDATION mobile\\n' > temp/recipe-runner.action-validation/probe.txt && printf '{\"platform\":\"mobile\",\"ok\":true}\n' > temp/recipe-runner.action-validation/probe.json && printf 'mobile log E2E_ACTION_VALIDATION\\n' > temp/recipe-runner.action-validation/validation.log && echo E2E_ACTION_VALIDATION mobile",
           "next": "assert-command-exit",
-          "intent": "Prepare action-validation probe files",
+          "intent": "Prepare runner.action-validation probe files",
           "detail": "Create local files used to prove command/assert/log/artifact actions.",
           "flow": "setup"
         },
@@ -35,7 +35,7 @@
         },
         "assert-file": {
           "action": "assert_file",
-          "path": "temp/recipe-action-validation/probe.txt",
+          "path": "temp/recipe-runner.action-validation/probe.txt",
           "contains": "E2E_ACTION_VALIDATION mobile",
           "next": "assert-json",
           "intent": "Verify file assertions work",
@@ -44,7 +44,7 @@
         },
         "assert-json": {
           "action": "assert_json",
-          "path": "temp/recipe-action-validation/probe.json",
+          "path": "temp/recipe-runner.action-validation/probe.json",
           "assert": {
             "path": "$.platform",
             "operator": "eq",
@@ -57,7 +57,7 @@
         },
         "watch-logs": {
           "action": "watch_logs",
-          "path": "temp/recipe-action-validation/validation.log",
+          "path": "temp/recipe-runner.action-validation/validation.log",
           "contains": "E2E_ACTION_VALIDATION",
           "next": "index-artifacts",
           "intent": "Verify log watching works",
@@ -68,7 +68,7 @@
           "action": "index_artifacts",
           "artifacts": [
             {
-              "path": "temp/recipe-action-validation/probe.txt",
+              "path": "temp/recipe-runner.action-validation/probe.txt",
               "type": "log",
               "category": "debug",
               "label": "Mobile action validation probe"
@@ -174,7 +174,7 @@
         },
         "ui-screenshot-wallet": {
           "action": "ui.screenshot",
-          "path": "screenshots/mobile-wallet-action-validation.png",
+          "path": "screenshots/mobile-wallet-runner.action-validation.png",
           "next": "wallet-navigate-perps",
           "intent": "Capture wallet visual proof",
           "detail": "Save a screenshot artifact after generic UI actions.",

package/package.json

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