@deeeed/metamask-harness 0.2.0

package/docs/package-boundaries.md

@@ -0,0 +1,47 @@
+# Package Boundaries
+
+This package intentionally stays as **one npm package** with a clear internal
+split. Splitting into two packages now would make users choose between packages
+before the runtime API is stable. Instead, keep one install surface and separate
+responsibilities inside the repo.
+
+## Internal split
+
+| Area | Owns | Does not own |
+|---|---|---|
+| Recipe layer | Action manifests, reusable recipes, typed runner binding, Mobile/Extension live adapters, proof semantics. | Starting Metro/Chrome, simulator boot, native builds, git cleanup. |
+| Runtime lifecycle layer | Harness install/cleanup, Metro/dev-client launch, bundle prewarm, Chrome/CDP launch, fixture/profile setup, readiness gates. | Recipe graph execution, action vocabulary decisions, task-specific proof logic. |
+
+## Stable command contract
+
+Keep the public package simple:
+
+```bash
+mm-harness launch ios ...               # runtime lifecycle, then readiness proof (mobile)
+mm-harness launch ...                   # runtime lifecycle, then readiness proof (extension)
+mm-harness run <recipe.json> ...        # recipe execution only
+```
+
+Wrappers such as skills or slot farms should call those commands. They should not
+copy adapter scripts or reimplement Metro/Chrome launch behavior.
+
+## Why not two packages yet?
+
+A future split may be useful, for example:
+
+- `@metamask/recipe-runner` for manifests/adapters/proof execution;
+- `@metamask/recipe-runtime` for Mobile/Extension sandbox launch.
+
+Do that only after the runtime CLI is stable, all wrappers call it exclusively
+(no copied adapter scripts), and the two areas have gone several releases
+without a change that touches both. Until then, two packages would likely
+increase confusion and version skew.
+
+## Change discipline
+
+1. Prefer moving behavior into the runner before changing farms/skills.
+2. Keep compatibility wrappers when renaming files or commands.
+3. Validate both paths after runtime changes:
+   - direct runner/skill path;
+   - Farmslot/Command Center prepare path.
+4. Do not move files just for tidiness if callers still depend on old paths.

package/docs/perps-flow-catalog.md

@@ -0,0 +1,235 @@
+# Perps Flow Catalog
+
+MetaMask Perps recipes use a small set of parameterized primitives plus higher-level `ensure_*` wrappers. Do not add one action per scenario. A new Perps capability should first try to extend selector params or flow params.
+
+## Layers
+
+| Layer | Examples | Responsibility |
+|---|---|---|
+| Read primitives | `metamask.perps.read_positions`, `metamask.perps.read_orders` | Return redacted live state for a selected subset. |
+| Bulk mutation primitives | `metamask.perps.close_positions`, `metamask.perps.close_orders`, `metamask.perps.place_order` | Perform one real product operation over a parameterized selection. |
+| Assertion wrappers | `metamask.perps.assert_positions`, `metamask.perps.assert_orders` | Read live state and fail when selected state does not match expectation. |
+| Ensure wrappers | `metamask.perps.ensure_positions`, `metamask.perps.ensure_orders` | Compose read/mutate/assert to create idempotent start states. |
+| Domain setup/teardown | `metamask.perps.start_state`, `metamask.perps.teardown_state` | Compose wallet/provider/network/page/position/order setup before a proof window. |
+
+## Selection contract
+
+Position/order operations accept the same selector shape:
+
+```json
+{
+  "action": "metamask.perps.close_positions",
+  "mode": "matching",
+  "markets": ["BTC", "ETH"],
+  "side": "long",
+  "timeout_ms": 30000
+}
+```
+
+- `mode: "matching"` selects `market`/`symbol` or `markets`/`symbols`.
+- `mode: "all"` selects every live position/order returned by the product.
+- `side` narrows selection when the product returns side information.
+- `selector` can carry the same fields when a nested shape is easier for flow composition.
+
+## Examples
+
+Close every live Perps position before a proof window:
+
+```json
+{ "action": "metamask.perps.close_positions", "mode": "all" }
+```
+
+Cancel only BTC open orders:
+
+```json
+{ "action": "metamask.perps.close_orders", "market": "BTC" }
+```
+
+Higher-level clean start state:
+
+```json
+{
+  "action": "metamask.perps.ensure_positions",
+  "state": "none",
+  "mode": "all"
+}
+```
+
+Provider/network setup belongs in a configurable start-state contract such as `metamask.perps.start_state`, not in duplicate primitive actions:
+
+```json
+{
+  "flow": "metamask.perps.start_state",
+  "params": {
+    "provider": "hyperliquid",
+    "network": "testnet",
+    "page": "market",
+    "market": "BTC",
+    "positions": { "state": "none", "mode": "all" },
+    "orders": { "state": "none", "mode": "all" }
+  }
+}
+```
+
+## Position update operations
+
+Perps needs more than open/close. When TP/SL, margin, or leverage update coverage is added, prefer one parameterized position-update primitive instead of one adapter file per feature. The primitive should accept a position selector, a small set of update operations, and explicit assertions over the resulting position/order state.
+
+That future primitive should compose controller-backed product APIs when that is the supported app path. It must not mutate React/Redux/MobX/DOM/local storage directly.
+
+## Direct controller usage
+
+When a recipe genuinely needs direct controller access and there is no reusable UI-equivalent flow, the agent should call the product controller directly through the platform bridge/CDP capability documented for that project.
+
+The runner should help by documenting discoverable controller capabilities, not by hiding them behind another action vocabulary. For each direct controller capability, document:
+
+- controller/API path;
+- supported params;
+- whether it changes state;
+- required preconditions;
+- expected postcondition assertion;
+- redaction rules for trace output.
+
+Example documentation shape:
+
+```json
+{
+  "capability": "PerpsController.setTpSl",
+  "access": "direct-controller",
+  "params": {
+    "market": "BTC",
+    "takeProfit": { "price": "72000" },
+    "stopLoss": { "price": "65000" }
+  },
+  "postcondition": {
+    "action": "metamask.perps.assert_orders",
+    "market": "BTC",
+    "state": "present"
+  }
+}
+```
+
+State-changing direct controller calls must still be followed by a read/assert step or by an `ensure_*` wrapper that proves the final state.
+
+## Limiting live-adapter file count
+
+Perps should converge to one domain dispatcher per platform, not one new file for every controller operation. The runner can still expose many manifest actions, but implementation should route through a small domain module:
+
+```text
+library/actions/mobile/perps/perps.mjs       # shared Mobile Perps operation catalog
+library/actions/extension/perps/perps.mjs    # shared Extension Perps operation catalog
+```
+
+Runner resolution supports a domain dispatcher fallback such as `library/actions/<platform>/perps/perps.mjs` when an action-specific file is absent. That keeps discoverability in the manifest while avoiding a growing pile of tiny wrapper files.
+
+## Rule of thumb for adding adapter files
+
+Add a named adapter/flow when it represents a reusable product workflow that normally has a UI path and would otherwise waste proof-video time on repetitive setup. Examples: unlock wallet, navigate to Perps, ensure provider/network, open a market, create a baseline position, close selected positions, cancel selected orders, or prepare an order form.
+
+Do not add a new adapter file only because a controller exposes another method. For direct controller operations, document the real controller capability and params so the agent can call the product API directly when appropriate.
+
+| Need | Preferred shape | Why |
+|---|---|---|
+| Faster setup for a visual proof with a matching UI/user workflow | named flow or semantic adapter, e.g. `ensure_positions`, `close_positions` | Keeps proof videos focused while still using supported app/API paths. |
+| Direct product capability with many variants | documented direct controller capability + required postcondition | Avoids one file per controller method and avoids a useless wrapper vocabulary. |
+| Ticket-specific visual claim | task-local recipe assertion/evidence | Avoids polluting the domain API with one-off checks. |
+| Repeated domain baseline across teams | catalog flow such as `start_state` | Creates a stable starting contract for many recipes. |
+
+Direct controller capabilities must still be discoverable in docs/manifest metadata. The metadata should describe the real controller/API path, required params, examples, postconditions, and whether the operation is state-changing. The agent should be able to infer valid direct calls without reverse-engineering app internals first.
+
+## Preconditions vs prestate
+
+Existing Mobile recipes use pre-conditions such as `wallet.unlocked`, `perps.feature_enabled`, `perps.ready_to_trade`, `perps.sufficient_balance`, `perps.open_position`, `perps.open_position_tpsl`, `perps.open_limit_order`, `perps.not_in_watchlist`, and `perps.trading_flag`.
+
+Recipe v1 should keep the same concept, but split it into two different responsibilities:
+
+| Concept | Mutates state? | Purpose | Examples |
+|---|---:|---|---|
+| `preconditions` / `requires` | No | Fast fail with actionable reason when the target cannot support the recipe. | `wallet.unlocked`, `perps.feature_enabled`, `perps.trading_flag` |
+| `prestate` / `startState` | Yes, when needed | Converge the app to a configurable baseline before the proof window. | unlock, select account, choose network/provider, close positions/orders, open market |
+
+A precondition should not repair state. It answers “is this environment eligible?” A prestate answers “make the environment look like this before the proof starts.”
+
+## Recommended Perps base prestate
+
+Most Perps recipes should inherit from a configurable base prestate instead of repeating setup inline:
+
+```json
+{
+  "flow": "metamask.perps.start_state",
+  "params": {
+    "wallet": { "state": "unlocked", "account": "default" },
+    "featureFlags": { "perps": true, "trading": true },
+    "provider": "hyperliquid",
+    "network": "testnet",
+    "readyToTrade": true,
+    "balance": { "minWithdrawableUsd": "1" },
+    "page": "market",
+    "market": "BTC",
+    "positions": { "state": "none", "mode": "matching", "markets": ["BTC"] },
+    "orders": { "state": "none", "mode": "matching", "markets": ["BTC"] },
+    "hud": { "enabled": true, "proofSafe": true }
+  }
+}
+```
+
+This flow should compose smaller actions/flows:
+
+1. `metamask.wallet.ensure_unlocked`
+2. `metamask.wallet.select_account` when requested
+3. provider/network/testnet setup for Hyperliquid or another provider
+4. read-only gates for feature/trading readiness
+5. `metamask.perps.ensure_orders` for order baseline
+6. `metamask.perps.ensure_positions` for position baseline
+7. `ui.navigate` with a manifest-discoverable `page` alias, or raw route/hash fallback
+8. `app.hud` when visual proof should show context and it will not obscure the claim
+
+## Base prestate profiles
+
+The runner should publish named profiles as examples, but keep them parameterized:
+
+| Profile | Intended use | Default params |
+|---|---|---|
+| `perps.clean_market_testnet` | Most visual AC proofs from a clean market screen | Hyperliquid testnet, wallet unlocked, ready to trade, selected market, no selected positions/orders |
+| `perps.open_position_testnet` | TP/SL, margin, close-position proofs | Hyperliquid testnet, selected market, one open position, optional side/notional/leverage |
+| `perps.open_order_testnet` | Limit-order edit/cancel proofs | Hyperliquid testnet, selected market, one open order |
+| `perps.provider_mainnet_readonly` | Read-only balance/provider proofs | Hyperliquid mainnet, no cleanup mutation unless explicitly requested |
+
+Profiles are shortcuts, not separate hardcoded actions. A recipe should be able to override provider, network, market, account, positions, orders, balance, page, and HUD behavior.
+
+## Recipe v1 shape
+
+Recommended shape for a proof recipe:
+
+```json
+{
+  "preconditions": [
+    "wallet.unlocked",
+    "perps.feature_enabled",
+    "perps.trading_flag"
+  ],
+  "startState": {
+    "action": "metamask.perps.start_state",
+    "intent": "Converge Perps to a clean BTC testnet baseline before proof",
+    "params": {
+      "profile": "perps.clean_market_testnet",
+      "market": "BTC",
+      "positions": { "state": "none", "market": "BTC" },
+      "orders": { "state": "none", "market": "BTC" }
+    },
+    "record": "trace_only"
+  },
+  "proof": {
+    "nodes": {
+      "ac-specific-step": {
+        "action": "ui.press",
+        "intent": "Perform the AC-specific Perps interaction through the UI",
+        "test_id": "example",
+        "record": "proof_window"
+      }
+    }
+  }
+}
+```
+
+The prestate runs before the proof window and remains visible in `trace.json`/`summary.json`; the proof window only records the AC-specific behavior. This preserves review speed without hiding setup from the agent or reviewer.

package/docs/recipe-libraries.md

@@ -0,0 +1,95 @@
+# 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.
+
+## The three sources and who owns them
+
+| 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/`) |
+
+A library is just a 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)
+```
+
+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.

package/docs/runtime-file-conventions.md

@@ -0,0 +1,36 @@
+# Runtime File Conventions
+
+This runner uses a small set of file extensions on purpose. The goal is to keep
+MetaMask-specific logic easy to run from either a source checkout or a published
+package without requiring target app builds to transpile runner code.
+
+## Extension rules
+
+- `runner/src/**/*.ts` — typed runner core: CLI parsing, manifests, adapter binding,
+  runtime decisions, and shared helper logic.
+- `library/actions/**/*.mjs`, `orchestration/**/*.mjs`, and `scripts/**/*.mjs` —
+  standalone ESM modules that Node executes directly with no build step. Use
+  these for action adapters and small injected/runtime helpers.
+- `*.cjs` — compatibility islands only. Keep these quarantined for helper code
+  that intentionally needs CommonJS semantics, such as portable `require()`
+  execution from shell scripts or bridge code shared with older runtime contexts.
+- `*.sh` — thin OS/device orchestration wrappers for tools such as `simctl`,
+  `adb`, Chrome launch, tmux, and filesystem setup. Do not put recipe graph
+  execution or MetaMask domain semantics in shell.
+- Plain source `*.js` is not allowed. With `"type": "module"`, `.js` would be
+  ESM, but it is visually ambiguous in this runner. Use `.mjs` for direct Node
+  scripts or `.ts` for typed core code.
+
+## Design intent
+
+The mix is intentional only when the boundary is clear:
+
+1. TypeScript owns maintainable product/runner decisions.
+2. ESM scripts own no-build runtime adapters and injected helpers.
+3. CommonJS stays isolated where the runtime context makes ESM brittle.
+4. Shell stays at the edge for host/device commands.
+
+If a file crosses those boundaries, move the logic inward: shell should call a
+Node module, standalone `.mjs` should become typed `runner/src/**/*.ts` when it grows
+shared domain logic, and new compatibility needs should be documented before
+adding another `.cjs` file.