@deeeed/metamask-harness 0.17.2 → 0.17.4

package/docs/recipe-libraries.md

@@ -1,301 +1,71 @@
-# Recipe Libraries
+# Recipe libraries
 
-Per-change recipes are throwaway proofs: generated for one PR, run as evidence,
-discarded. A **recipe library** is the durable keep behind them — the reusable
-flows ("set up a funded wallet", "converge Perps to a clean BTC baseline") a
-per-change recipe is composed FROM. Libraries are owned bottom-up: each
-developer accumulates their own, teams share theirs, and this runner ships only
-a minimal canonical set. Nothing here requires central governance to function.
+A library shares reusable behavior without coupling it to one ticket:
 
-## The three sources and who owns them
+- an **action** is one typed operation supplied by a platform adapter;
+- a **flow** is a reusable parameterized action sequence;
+- a **recipe** is a complete executable proof and owns task acceptance criteria.
 
-| Source | Location | Owned by | Contains |
-| --- | --- | --- | --- |
-| Personal | `<farmslot home>/recipe-library` (`FARMSLOT_HOME`, default `~/.farmslot`) | the developer, entirely | the developer's accumulated flow history |
-| Team | a repo the team owns (any host); checked out locally and configured as a source | the team's developers directly — not a MetaMask-governed artifact | richer domain flows the team maintains |
-| Canonical (repo-native) | this runner's `library/` | this runner | minimal, stable primitives only (see `library/flows/`) |
+Use a flow when several recipes repeat the same product journey. Keep ticket copy,
+layout claims, and one-off assertions in the task recipe.
 
-A library is just a directory:
+## Directory
 
 ```text
-<library-root>/
-  library.json          { "kind": "recipe-library", "schema_version": 1, "name": "..." }
-  flows/*.flows.json    standard recipe-flow-catalog documents (Recipe Protocol v1 §8)
+team-recipes/
+  library.json
+  flows/
+    wallet.flows.json
+  recipes/
+    onboarding/
+      smoke.extension.recipe.json
 ```
 
-There is no new format: library flows are the same flow-catalog documents a
-recipe can reference through `uses`, and per-change recipes call them with the
-standard `call` node.
-
-## Resolution and precedence
-
-`mm-harness run` resolves `call` refs from ordered sources; the first
-source that declares a ref wins:
-
-1. recipe-local declarations (inline `flows` and explicit `uses` paths) — always win;
-2. your explicit entries: repeatable/colon-separated `--library name=path` or `RECIPE_LIBRARY_PATH` (order = precedence), or, when neither is set, your personal library;
-3. the canonical `metamask` library, appended last.
-
-Personal and team flows therefore shadow canonical ones **by default** — that
-is intentional (your history is the point; the canonical set is fallback
-vocabulary, not authority). Shadowing is never silent: it is printed at run
-start, recorded in `summary.json` under `flowResolution`, and the exact
-definitions a run executed are snapshotted into the `resolved-flows.json`
-artifact so reviewers can inspect the evidence without access to your
-libraries.
-
-```bash
-mm-harness flows list                          # every flow across your sources, with provenance
-RECIPE_LIBRARY_PATH="team=~/dev/team-recipes" mm-harness flows list
-mm-harness run recipe.json --adapter extension --artifacts-dir artifacts \
-  --library "team=~/dev/team-recipes"
-```
-
-## Promoting a flow (building your history)
-
-After a successful run, keep a flow that proved useful:
-
-```bash
-mm-harness flows promote --from recipe.json --flow perps.my_baseline \
-  --run artifacts    # stamps provenance.lastVerified from the passing run
-```
-
-Promotion is the contract gate: the flow must have a `description`, `ensure_*`
-flows must declare a `postcondition`, and the stored flow is stamped with
-provenance (origin recipe, promotion date, and `lastVerified` only when backed
-by a passing run's artifacts). The personal library is created on first
-promote.
-
-## Sharing with your team
-
-Sharing is a plain PR: copy or promote the flow into the team's library repo
-and let the team review it like any other change. Their repo, their rules —
-there is no registration step and no org approval involved.
-
-## Trust and drift
-
-Library flows rot as the app changes. Three guards, cheapest first:
-
-1. **Postconditions** — a stale flow fails its postcondition at run time and
-   fails the recipe loudly; promotion nudges every flow toward asserting its
-   outcome.
-2. **Freshness warnings** — `flows list` and run-start resolution flag flows
-   whose `lastVerified` is older than 30 days.
-3. **Provenance in evidence** — `flowResolution` + `resolved-flows.json` make
-   it visible exactly which flow, from which source, produced a proof.
-
-## Rules for the canonical library
-
-Additions to `library/flows/` are held to the flow-catalog maintenance rules
-(`docs/perps-flow-catalog.md`, Recipe Protocol v1 §8.1): parameterized
-primitives over name multiplication, a real reusable domain concept per flow,
-and a small flow budget. If a flow is team- or task-specific, it belongs in a
-team or personal library — that is what the precedence order is for.
-`scripts/check.mjs` validates every committed catalog against the action
-manifests.
-
-## Your own measured flow: creating a personal recipe library
-
-A **measured flow** is a recipe you run the same way every time to watch how long
-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
-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
-test.
-
-### 1. Scaffold a personal library
-
-A library is a directory with a `library.json` marker. Keep reusable `flows/`
-(referenced via `call`) beside a domain-grouped `recipes/` folder for the full
-flows you run:
-
-```bash
-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
-```
-
-In real use this is discovered for you: with no `--library` flag and no
-`RECIPE_LIBRARY_PATH`, the runner reads your personal library at
-`$FARMSLOT_HOME/recipe-library` (default `~/.farmslot/recipe-library`). The
-explicit `--library mydev=<dir>` form below is the same mechanism, spelled out so
-it works headlessly (CI, a scratch checkout) and so the path is unambiguous.
-
-### 2. Copy the canonical recipe as a starting point
-
-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
-```
-
-### 3. Edit the nodes to your journey
-
-Open the copy and change what you measure while keeping the measured-flow shape.
-Retarget `open-market-detail` to your market and add one extra measured step —
-here, reading live orders on the detail screen:
-
-```jsonc
-"open-market-detail": {
-  "action": "ui.navigate",
-  "page": "perps-market",
-  "market": "ETH",                       // was BTC
-  "intent": "Open the ETH Perps market detail screen",
-  "next": "read-orders"                  // was "end"
-},
-"read-orders": {                         // your extra measured step
-  "action": "metamask.perps.read_orders",
-  "market": "ETH",
-  "intent": "Read live ETH orders on the market detail screen",
-  "next": "end"
-}
-```
-
-The canonical recipe keeps its nodes inline — a clean measured baseline. For
-bigger journeys you can extract repeated setup steps into a personal `flows/`
-segment and `call` it. For example, define an unlock + open-Perps-list segment
-in `~/my-recipes/flows/mydev.flows.json`:
+`library.json`:
 
 ```json
 {
-  "schema_version": 1, "kind": "recipe-flow-catalog", "owner": "mydev",
-  "flows": {
-    "mydev.open_perps_setup": {
-      "version": 1,
-      "description": "Unlock the wallet and open the Perps market list.",
-      "workflow": {
-        "entry": "ensure-unlocked",
-        "nodes": {
-          "ensure-unlocked": {
-            "action": "metamask.wallet.ensure_unlocked",
-            "intent": "Unlock the wallet before the Perps journey",
-            "next": "open-perps-list"
-          },
-          "open-perps-list": {
-            "action": "ui.navigate",
-            "page": "perps",
-            "intent": "Open the Perps market list screen",
-            "next": "done"
-          },
-          "done": { "action": "end", "status": "pass" }
-        }
-      }
-    }
-  }
+  "kind": "recipe-library",
+  "schema_version": 1,
+  "name": "wallet-team",
+  "owner": "wallet-team"
 }
 ```
 
-Then replace the two inline setup nodes in your recipe with a single `call` node:
+## Enable a team library
 
-```jsonc
-"setup": {
-  "action": "call",
-  "ref": "mydev.open_perps_setup",
-  "intent": "Run the personal Perps setup segment (unlock + open list)",
-  "next": "read-positions"
-}
+```bash
+export RECIPE_LIBRARY_PATH="wallet=$HOME/shared-library/wallet-team"
+mm-harness flows
+mm-harness run onboarding.smoke --plan
+mm-harness run onboarding.smoke --artifacts-dir temp/onboarding-proof
 ```
 
-The segment validates via `--plan` — the plan step verifies the `call` ref
-resolves from the library. Keep flow segment actions within the mobile action
-surface: the flow catalog format has no `platform`/`adapter` dimension today,
-so a flow using a core-only action (e.g. `command`) will pass `--plan` on mobile
-but fail at live-run time with "No adapter registered for flow action X". There
-is no plan-time cross-adapter enforcement; that gap would require an `adapters`
-field on flow catalog entries — not yet in the protocol.
+Use `--library wallet=/path/to/library` for a one-command override. Without an
+explicit library, the personal library is read from
+`$FARMSLOT_HOME/recipe-library` (default `~/.farmslot/recipe-library`).
 
-### 4. Run it and read the timings
+Resolution order is recipe-local, explicit/personal/team, then bundled MetaMask.
+The first matching flow wins. Runs print provenance and save resolved definitions
+in `resolved-flows.json`, so shadowing is reviewable.
 
-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:
+## Promote useful behavior
 
 ```bash
-# Static validation by NAME — resolves from the personal library via --library.
-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
-
-# Pinned live run — same device, healing OFF, so durations are comparable.
-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 \
-  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/lifecycle-smoke
-mm-harness run perps.performance.warm-start \
-  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/warm
-mm-harness run perps.performance.background-resume \
-  --adapter mobile --device <serial> --heal off --artifacts-dir artifacts/background
-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
-# { metadata, entries: [...] }; each entry carries nodeId + durationMs):
-node -e 'const t=require("./artifacts/trace.json"); \
-  for (const e of Array.isArray(t)?t:t.entries) console.log(e.nodeId, e.durationMs)'
+mm-harness flows promote --from recipe.json --flow wallet.ensure_ready --run artifacts
 ```
 
-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
-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
-marker before lifecycle setup and Perps timing nodes. Android background resume
-sends HOME, then relaunches through the Expo dev-client deep link. Cold start
-force-stops the installed package, then launches the same build through the deep
-link.
-
-### The measured-flow pattern
+Promotion requires a description. `ensure_*` flows require a machine-checkable
+postcondition. A passing run stamps verification provenance.
 
-Five rules keep timings meaningful and diffable:
+## Keep libraries durable
 
-1. **Pin the run** — `--device <serial> --heal off`. Healing retries hide the
-   regressions you are trying to measure.
-2. **One node per user-visible step** — a node's `duration` is only a signal when
-   it maps to a single thing the user sees.
-3. **Stable, human-meaningful node keys** — operators diff node keys across runs;
-   renaming `open-market-detail` breaks every historical comparison.
-4. **No destructive side effects** — a measured flow should be repeatable. The
-   canonical recipe stops at read + navigate; add `place_order`/`close` only in a
-   personal copy when you deliberately want to measure the trade path.
-5. **Read timings from `trace.json`, not the console** — the trace is the durable
-   per-node record; the console is for humans watching the run.
-
-### Shadowing, in practice
-
-Because `--library` sources resolve `call` refs before the canonical `metamask`
-library, a personal flow named like a canonical one shadows it — your history is
-the point. You can watch this happen on mobile with the segment recipe from the
-walkthrough above:
-
-```bash
-# A mobile recipe with "action": "call", "ref": "mydev.open_perps_setup"
-# fails without the library source…
-mm-harness run my-perps-with-segment --plan --adapter mobile
-#   → workflow.unresolved_call_ref
-
-# …and resolves once the personal library is on the path:
-mm-harness run my-perps-with-segment --plan --adapter mobile \
-  --library "mydev=~/my-recipes"
-#   → plan pass
-```
+- Parameterize before adding another name.
+- Keep setup idempotent and prove postconditions.
+- Keep secrets and wallet material out of libraries.
+- Review shared libraries like code.
+- Re-run their recipes when the product changes; stale provenance is surfaced.
+- Keep generic graph or UI mechanics in Recipe Protocol, not a team library.
 
-That resolution — unresolved without the source, `pass` with it — is what the
-`perps.performance-recipe` contract test asserts, alongside the canonical recipe
-resolving by name and the personal mobile copy planning by path and basename.
+The bundled examples `runner.smoke`, `wallet.smoke`, and `perps.smoke` show the
+same structure at increasing product specificity.

package/library/README.md

@@ -1,5 +1,9 @@
 # Recipe library
 
+- An **action** performs one typed operation.
+- A **flow** packages a reusable parameterized sequence of actions.
+- A **recipe** is a complete proof that may call actions and flows.
+
 - `actions/<adapter>/<group>/<name>.mjs` — executable action modules.
   **Importing an action module RUNS it**: each ends with `runAdapter(main)` at top
   level, which reads the live-adapter input path from the environment and executes.

package/library/manifests/core.action-manifest.json

@@ -446,7 +446,7 @@
           },
           "account": {
             "type": "string",
-            "description": "EVM address to read positions for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+            "description": "EVM address to read positions for; defaults to the canonical wallet fixture account."
           },
           "timeout_ms": {
             "type": "number"
@@ -523,7 +523,7 @@
           },
           "account": {
             "type": "string",
-            "description": "EVM address to read orders for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+            "description": "EVM address to read orders for; defaults to the canonical wallet fixture account."
           },
           "timeout_ms": {
             "type": "number"
@@ -558,7 +558,7 @@
           },
           "account": {
             "type": "string",
-            "description": "EVM address to read account state for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+            "description": "EVM address to read account state for; defaults to the canonical wallet fixture account."
           },
           "timeout_ms": {
             "type": "number"
@@ -653,7 +653,7 @@
           },
           "account": {
             "type": "string",
-            "description": "EVM address to trade for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+            "description": "EVM address to trade for; defaults to the canonical wallet fixture account."
           },
           "timeout_ms": {
             "type": "number"
@@ -748,7 +748,7 @@
           },
           "account": {
             "type": "string",
-            "description": "EVM address to close for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+            "description": "EVM address to close for; defaults to the canonical wallet fixture account."
           },
           "timeout_ms": {
             "type": "number"
@@ -837,7 +837,7 @@
           },
           "account": {
             "type": "string",
-            "description": "EVM address to read for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+            "description": "EVM address to read for; defaults to the canonical wallet fixture account."
           },
           "timeout_ms": {
             "type": "number"
@@ -937,7 +937,7 @@
           },
           "account": {
             "type": "string",
-            "description": "EVM address to trade for; defaults to MM_TEST_ACCOUNT_ADDRESS."
+            "description": "EVM address to trade for; defaults to the canonical wallet fixture account."
           },
           "timeout_ms": {
             "type": "number"

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

@@ -0,0 +1,27 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Core runner smoke",
+  "description": "Proves the headless Core runner resolves the checkout, executes generic actions, and writes a valid artifact package.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "package",
+          "intent": "Resolve the Core checkout and report headless readiness"
+        },
+        "package": {
+          "action": "assert_file",
+          "path": "package.json",
+          "next": "done",
+          "intent": "Prove generic project-file assertions work in Core"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,42 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Extension wallet smoke",
+  "description": "Fixture-backed proof that the Extension wallet is reachable, unlocked, readable, and visually capturable without depending on a product feature domain.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "fixture",
+          "intent": "Confirm the Extension runtime is reachable"
+        },
+        "fixture": {
+          "action": "metamask.wallet.fixture_status",
+          "next": "unlock",
+          "intent": "Confirm the checkout wallet fixture is ready"
+        },
+        "unlock": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "next": "state",
+          "intent": "Ensure the fixture-backed wallet is unlocked"
+        },
+        "state": {
+          "action": "metamask.wallet.read_state",
+          "next": "screenshot",
+          "intent": "Read the current wallet state through the public adapter"
+        },
+        "screenshot": {
+          "action": "ui.screenshot",
+          "path": "screenshots/wallet-smoke.png",
+          "next": "done",
+          "intent": "Capture visual wallet evidence"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass"
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,42 @@
+{
+  "schema_version": 1,
+  "title": "MetaMask Mobile wallet smoke",
+  "description": "Fixture-backed proof that the Mobile wallet is reachable, unlocked, readable, and visually capturable without depending on a product feature domain.",
+  "validate": {
+    "workflow": {
+      "entry": "status",
+      "nodes": {
+        "status": {
+          "action": "app.status",
+          "next": "fixture",
+          "intent": "Confirm the Mobile runtime is reachable"
+        },
+        "fixture": {
+          "action": "metamask.wallet.fixture_status",
+          "next": "unlock",
+          "intent": "Confirm the checkout wallet fixture is ready"
+        },
+        "unlock": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "next": "state",
+          "intent": "Ensure the fixture-backed wallet is unlocked"
+        },
+        "state": {
+          "action": "metamask.wallet.read_state",
+          "next": "screenshot",
+          "intent": "Read the current wallet state through the public adapter"
+        },
+        "screenshot": {
+          "action": "ui.screenshot",
+          "path": "screenshots/wallet-smoke.png",
+          "next": "done",
+          "intent": "Capture visual wallet evidence"
+        },
+        "done": {
+          "action": "end",
+          "status": "pass"
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -11,6 +11,7 @@
     "prepack": "npm run build",
     "dev:link-farmslot": "node scripts/link-local-farmslot.mjs",
     "check": "node scripts/check.mjs",
+    "qa:human": "node scripts/validate-human-outcomes.mjs",
     "self-test": "bin/mm-harness self-test",
     "manifest:mobile": "bin/mm-harness actions --raw --adapter mobile --json",
     "manifest:extension": "bin/mm-harness actions --raw --adapter extension --json",
@@ -57,6 +58,7 @@
     "library",
     "scripts/completions.sh",
     "scripts/install-completions.sh",
+    "scripts/validate-human-outcomes.mjs",
     "!scripts/README.md",
     "docs",
     "README.md",
@@ -71,4 +73,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}