@deeeed/metamask-harness 0.17.5 → 0.19.0

package/docs/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing
+
+Keep `mm-harness` thin: put each change in the layer that owns it and validate
+both the machine contract and the visible human result.
+
+## Ownership
+
+```text
+bin/mm-harness
+  -> src/                         typed CLI and product decisions
+  -> @farmslot/recipe-harness    generic execution, UI transports, evidence
+  -> @farmslot/protocol          schemas
+  -> adapters/                   focused host/browser/device leaves
+  -> library/                    MetaMask actions and recipes
+  -> MetaMask checkout           product under test
+```
+
+| Layer | Owns |
+|---|---|
+| `@farmslot/protocol` | recipe and evidence schemas |
+| `@farmslot/recipe-harness` | generic execution, recovery, traces, artifacts, `ui.*` |
+| `mm-harness` | MetaMask runtime control, diagnostics, durable domain actions |
+| skills/checklists | task workflow and proof expectations |
+| product checkout | app behavior and explicit debug hooks |
+
+Generic bootstrap, trust, receipts, and recovery belong upstream. MetaMask
+platform behavior and risk classification belong here. Ticket assertions stay
+task-local.
+
+## Repository map
+
+| Path | Responsibility |
+|---|---|
+| `bin/mm-harness` | only public executable |
+| `src/commands/` | command behavior |
+| `src/adapters/` | typed platform decisions and `AdapterSurface` |
+| `adapters/<platform>/` | focused shell/Node host operations |
+| `adapters/<platform>/inject*` | assemble the checkout overlay from shipped adapter/library files |
+| `library/actions/` | executable MetaMask action adapters |
+| `library/recipes/` | reusable parameterized behavior and proofs |
+| `library/manifests/` | declared capability surface |
+| `scripts/` | build/validation tooling and shipped completion/human-QA helpers |
+
+All TypeScript lives under `src/`. Use `.mjs` for direct no-build Node leaves,
+`.cjs` only for required CommonJS contexts, and shell only for host/device
+commands. Decisions belong in TypeScript; a leaf performs one operation and
+exits.
+
+## Adapter surface
+
+Commands resolve shared platform behavior through
+`src/adapters/surface.ts`. Extend `AdapterSurface` only when all platforms need
+the concept, implement all three adapters, and let Core report headless/N/A
+explicitly. Do not add command-local platform ladders for surface-owned behavior.
+
+Each checkout owns:
+
+```text
+temp/recipe/runtime/   ports, processes, fixture, logs, runtime identity
+temp/recipe/harness/   installed runtime overlay
+```
+
+Profiles, devices, ports, watchers, and evidence paths must resolve from that
+checkout so slots remain isolated.
+
+## Actions and adapters
+
+Official `ui.*` behavior comes from the generic runtime. MetaMask-specific
+actions are manifest-declared modules under:
+
+```text
+library/actions/<platform>/<domain>/<name>.mjs
+library/actions/shared/<domain>/<name>.mjs
+```
+
+Configured libraries use the same structure. An adapter receives a JSON input
+path, writes JSON to its `outputPath` or stdout, returns redacted trace-safe
+output, and performs only the declared operation. It must not execute another
+recipe graph.
+
+The input path is argv 1 and `METAMASK_RECIPE_ADAPTER_INPUT`. Its document is:
+
+```json
+{
+  "schemaVersion": 1,
+  "platform": "mobile|extension|core",
+  "action": "metamask.example.action",
+  "node": {},
+  "context": {
+    "nodeId": "step-id",
+    "projectRoot": "/path/to/checkout",
+    "artifactsDir": "/path/to/run/artifacts"
+  },
+  "outputPath": "/temporary/output.json"
+}
+```
+
+Write JSON to `outputPath` (also `METAMASK_RECIPE_ADAPTER_OUTPUT`) or stdout.
+Write evidence under `context.artifactsDir` and return relative artifact paths.
+`METAMASK_RECIPE_LIVE_ADAPTER_DIR` is the explicit task-local implementation
+root; configured libraries are the durable sharing mechanism.
+
+Add a bundled action only when it is reusable, typed, stable, reduces inference
+or risk, and has a real postcondition. Otherwise use a team library or task-local
+recipe. Follow [Recipes](RECIPES.md) and [Security](SECURITY.md).
+
+## CLI contract
+
+- Human mode is contextual, colored only in a TTY, and teaches one exact next
+  action on failure.
+- `--json` stdout is one stable document with no decoration.
+- Long work acknowledges intent before blocking and streams child output.
+- Lifecycle commands are checkout-scoped and idempotent.
+- `doctor` is read-only; `doctor --fix` repairs without launching.
+- No command may fabricate platform support or readiness.
+
+When adding a command, register its behavior and human metadata, then add a
+contract test. When a flag reaches a host leaf, both the typed composer and leaf
+parser must accept it. Before renaming or removing a public flag, injected file,
+or wrapper, verify real callers and retain compatibility only when one exists.
+
+## Change gates
+
+```bash
+yarn test:unit
+yarn test:coverage
+yarn check
+bash tests/contract/run.sh
+```
+
+Runtime changes also require real affected-platform QA and a packed installation
+test. Update `CHANGELOG.md` under `Unreleased` for user-visible behavior.
+
+Docs describe only current behavior. History belongs in the changelog and Git;
+do not add handovers, audits, speculative roadmaps, or duplicate command guides
+under `docs/`.

package/docs/QA.md

@@ -0,0 +1,184 @@
+# QA
+
+Validate the installed candidate as a human would use it. Use disposable
+profiles and an unfunded fixture; preserve existing product source and active
+processes.
+
+## Candidate and provenance
+
+```bash
+export CANDIDATE=/path/to/mm-harness-candidate.tgz
+export QA_HOME="$(mktemp -d "$HOME/mmh-qa.XXXXXX")"
+export QA_PREFIX="$QA_HOME/npm"
+HOME="$QA_HOME" npm install -g --prefix "$QA_PREFIX" "$CANDIDATE"
+export PATH="$QA_PREFIX/bin:$PATH"
+mm-harness --version
+```
+
+- [ ] The executable and dependencies resolve inside the isolated prefix.
+- [ ] No dependency is a symlink or resolves through a local Farmslot checkout.
+- [ ] Record the tarball SHA-256 and product SHAs.
+- [ ] Product trees start and finish without tracked changes.
+
+## Common
+
+Run inside each Extension, Mobile, and Core checkout:
+
+```bash
+mm-harness doctor
+mm-harness doctor --json
+mm-harness status
+mm-harness actions
+mm-harness run --list
+mm-harness run runner.smoke --describe
+mm-harness run runner.smoke --plan
+mm-harness run runner.smoke
+mm-harness last --json
+```
+
+- [ ] Product, checkout, slot, ports, and next action are correct.
+- [ ] Human output is concise and evidence paths are absolute.
+- [ ] JSON output is one parseable document without color or prose on stdout.
+- [ ] `run` chooses a checkout-local artifact directory; an explicit
+  `--artifacts-dir` still wins.
+- [ ] Reports, trace, diagnostics, executed recipe, and manifest exist and agree.
+- [ ] `last --json` reconstructs the run without re-executing it.
+
+Recovery checks:
+
+```bash
+mm-harness actions --wat
+mm-harness run missing.recipe --describe
+mm-harness doctor --fix
+mm-harness verify
+```
+
+- [ ] Bad input fails before runtime work with a stable code and one exact next
+  action.
+- [ ] `doctor --fix` is idempotent and does not choose a fixture or launch.
+- [ ] With `capture-helper` absent, Extension reports CDP screenshots and Mobile
+  reports `simctl`/ADB screenshots; video is honestly unavailable.
+
+Run the bounded multi-platform preflight when all three checkouts are available:
+
+```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 supplements the visible checks below; it does not replace them.
+
+## Extension
+
+Fresh MetaMask Extension needs its normal product configuration and
+checkout-pinned Chromium. Follow the product files; do not invent values:
+
+```bash
+cd /path/to/metamask-extension
+cp .metamaskrc.dist .metamaskrc
+${EDITOR:-vi} .metamaskrc
+yarn playwright install chromium
+mm-harness launch --verify
+mm-harness fixtures set
+mm-harness run wallet.smoke
+mm-harness logs --source extension
+mm-harness logs --source dapp
+mm-harness logs --source webpack
+mm-harness debug
+```
+
+- [ ] Missing/placeholder Infura configuration returns
+  `EXTENSION_PRODUCT_CONFIG_REQUIRED` before build or browser startup.
+- [ ] Missing Chromium returns `EXTENSION_BROWSER_REQUIRED` without using system
+  Chrome.
+- [ ] Launch uses the checkout-owned profile, opens one MetaMask surface, avoids
+  keychain prompts, and preserves keyboard focus by default.
+- [ ] A second launch reuses the watcher/profile without duplicate tabs.
+- [ ] Two source edits rebuild incrementally; refresh shows each change; revert
+  restores a clean tree.
+- [ ] Log sources are distinct.
+- [ ] `debug` opens connected DevTools for the active Extension surface;
+  `location.href` returns its `chrome-extension://` URL and remains connected.
+
+## Mobile
+
+```bash
+cd /path/to/metamask-mobile
+mm-harness provision runway ios
+mm-harness launch ios --verify
+mm-harness fixtures set
+mm-harness call metamask.wallet.ensure_unlocked
+mm-harness run wallet.smoke
+mm-harness logs --source app
+mm-harness logs --source metro
+mm-harness debug
+```
+
+- [ ] Simulator opens only when absent and does not steal focus by default.
+- [ ] A second launch reuses the running simulator and Metro.
+- [ ] Fixture setup and unlock show the intended redacted account without
+  mnemonic/private-key output.
+- [ ] Status matches verified product routes: `Login`/`LockScreen` are locked;
+  `WalletView` is unlocked.
+- [ ] App and Metro logs are separate.
+- [ ] A JS edit rebuilds through Metro and appears after reload without a native
+  rebuild; revert restores a clean tree.
+
+When Android/ADB is available, repeat with:
+
+```bash
+mm-harness launch android --device <serial> --verify
+```
+
+## Core
+
+```bash
+cd /path/to/metamask-core
+mm-harness doctor
+mm-harness call metamask.wallet.list_accounts scope=selected
+mm-harness run runner.smoke
+mm-harness logs
+mm-harness debug
+```
+
+- [ ] Doctor reports a headless controller surface and no capture requirement.
+- [ ] Account output is fixture-backed and redacted.
+- [ ] Smoke writes the complete evidence package without launching an app.
+- [ ] Logs/debug fail with truthful headless teaching errors.
+
+## Trust and evidence
+
+- [ ] An untrusted restricted plan fails with `RECIPE_TRUST_REQUIRED` and no
+  side effect.
+- [ ] A wrong/stale digest fails with `RECIPE_APPROVAL_MISMATCH`.
+- [ ] Only the unchanged, reviewed plan executes with its exact approval digest.
+- [ ] Human output, JSON, reports, traces, diagnostics, and screenshots contain
+  no mnemonic, private key, seed, bearer token, or API credential.
+- [ ] Diagnostics contain only events observed in the proof window.
+- [ ] Screenshot provenance identifies capture-helper, CDP, simctl, or ADB
+  accurately.
+
+## Automated and release gates
+
+```bash
+yarn check
+bash tests/contract/run.sh
+```
+
+Before release:
+
+- [ ] Focused unit tests and full contract suite pass.
+- [ ] Packed isolated installation passes the critical Extension, Mobile, and
+  Core scenarios.
+- [ ] Independent review approves the exact final diff.
+- [ ] Known limits are explicit: Extension requires product Infura setup;
+  Mobile requires its normal dev-client/device setup; video requires optional
+  `capture-helper`; the harness never invents funded fixtures.
+- [ ] Existing Farmslot slots remain compatible.
+
+When a slot manager is available, repeat `runner.smoke` in one existing managed
+checkout per product and verify its profile/device, ports, processes, and fixture
+remain isolated.

package/docs/RECIPES.md

@@ -0,0 +1,122 @@
+# Recipes
+
+Use the smallest durable layer that proves the task:
+
+1. call an existing action;
+2. compose existing recipes;
+3. write a task-local recipe;
+4. use a verified controller or CDP path when no stable action exists.
+
+Discover before authoring:
+
+```bash
+mm-harness actions <intent>
+mm-harness actions --action <name>
+mm-harness run --list
+mm-harness run <name> --describe
+```
+
+Discovery reports parameters, selected adapter variant, nested recipes, source,
+and shadows. Use `--json` for exact metadata.
+
+## Author and run
+
+An action performs one typed operation. A recipe owns a reusable graph or a
+task proof and may call other recipes.
+
+```json
+{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Wallet readiness",
+  "description": "Proves the running wallet is reachable and unlocked.",
+  "paramsSchema": {
+    "type": "object",
+    "properties": {
+      "account": { "type": "string", "default": "Account 1" }
+    },
+    "additionalProperties": false
+  },
+  "workflow": {
+    "entry": "unlock",
+    "nodes": {
+      "unlock": {
+        "action": "metamask.wallet.ensure_unlocked",
+        "intent": "Make the fixture-backed wallet ready for use",
+        "next": "done"
+      },
+      "done": { "action": "end", "status": "pass" }
+    }
+  }
+}
+```
+
+Defaults are applied before validation. Root values use `key=value`; a nested
+recipe call uses `action: "call"`, `ref`, and `params`.
+
+```bash
+mm-harness run recipe.json account="Account 2" --plan
+mm-harness run recipe.json account="Account 2"
+```
+
+Rules:
+
+- Validate with `--plan` before side effects.
+- Use real product paths; never mutate hidden state to fabricate proof.
+- Prove preparation with an independent read/assert or visible UI postcondition.
+- Keep ticket-specific claims in task-local recipes.
+- Parameterize repeated behavior instead of multiplying names.
+- Keep secrets out of recipes, libraries, and evidence.
+
+The protocol is authoritative:
+<https://farmslot.io/docs/reference/recipe-protocol-v1>.
+
+## Share a library
+
+```text
+team-recipes/
+  library.json
+  manifests/extension.action-manifest.json
+  actions/extension/wallet/ensure_ready.mjs
+  recipes/onboarding/smoke.extension.recipe.json
+```
+
+```json
+{
+  "kind": "recipe-library",
+  "schema_version": 1,
+  "name": "wallet-team",
+  "owner": "wallet-team"
+}
+```
+
+```bash
+export RECIPE_LIBRARY_PATH="wallet=$HOME/shared-library/wallet-team"
+mm-harness run --list
+mm-harness run onboarding.smoke --describe
+mm-harness run onboarding.smoke --plan
+```
+
+Use `--library wallet=/path/to/library` for one command. Resolution follows the
+explicit library order, then bundled MetaMask. Adapter-specific variants are
+selected deterministically. Every run records the root recipe, exact resolved
+dependency documents, their digests, call edges, selected sources, and shadows.
+
+## Direct product access
+
+The bundled library is intentionally small. A task may use a verified controller
+or CDP path when that is clearer than adding a permanent wrapper. Confirm the
+current source path, mutation risk, preconditions, independent postcondition,
+and redaction. Do not infer route or controller names from memory. Repeated team
+behavior belongs in a reviewed team recipe; only broadly reusable stable
+capabilities belong in the bundled library.
+
+Mobile and Extension share vocabulary where the product supports it. Core is
+headless and must not fabricate UI state. Inspect the current surface:
+
+```bash
+mm-harness actions --category wallet --json
+mm-harness actions --category perps --json
+mm-harness run --list --json
+```
+
+See [Security](SECURITY.md) before enabling custom executable actions.

package/docs/SECURITY.md

@@ -0,0 +1,88 @@
+# Security
+
+`mm-harness` executes product code, recipes, and optional custom adapters with
+the current user's authority. It is a proof tool, not an OS sandbox.
+
+## Trust boundary
+
+- Bundled actions and recipes are trusted package content.
+- A configured library cannot declare itself trusted.
+- Untrusted plans that request restricted capabilities stop before runtime
+  preparation or side effects with `RECIPE_TRUST_REQUIRED`.
+- The failure reports blocked nodes, capabilities, source provenance, and one
+  exact approval command.
+- Approval is bound to the resolved plan, implementation bundle, project root,
+  artifact directory, and execution environment.
+- Changed code or inputs produce `RECIPE_APPROVAL_MISMATCH`; an old digest does
+  not authorize a new plan.
+
+Never construct an approval from memory. Inspect the plan and use the exact
+`userAction` emitted by the failed run. Review custom libraries like application
+code because approved code retains the user's filesystem, process, and network
+permissions.
+
+## Product-state integrity
+
+Proof must come from supported UI, controller, or API paths. Never write DOM,
+React/Redux/MobX state, controller internals, or storage merely to manufacture
+the claimed result.
+
+Fixture setup is allowed before the proof window when it is explicit in the
+trace. Mutating setup must finish with a real read/assert or visible UI
+postcondition.
+
+## Wallet fixtures
+
+Each checkout has one canonical fixture:
+
+```text
+temp/recipe/runtime/wallet-fixture.json
+```
+
+Initialize it explicitly from an approved fixture or choose the disposable
+`--dev` option shown in the [README](../README.md). Never fund a dev fixture.
+
+- Never commit a fixture containing a mnemonic or private key.
+- Never print, paste, or record mnemonic/private-key material.
+- Use funded fixtures only in the intended isolated environment.
+- `fixtures set` reads the password from the fixture; do not put it on the
+  command line.
+- Human and JSON outputs may identify redacted accounts but must not expose
+  secret material.
+
+## Evidence and journals
+
+Recipe output may include application logs, screenshots, traces, and custom
+action results. Before sharing it:
+
+- verify the artifact manifest contains only intended files;
+- search human output, JSON, traces, diagnostics, and reports for credentials;
+- confirm screenshots use the declared provider and show no sensitive UI;
+- keep task-local artifacts out of source control unless intentionally reviewed.
+
+`mm-harness last --json` stores a redacted resumability record. It is not a
+secret store.
+
+## Runtime isolation
+
+Extension uses a checkout-owned Chrome profile and CDP port. Mobile resolves a
+checkout-owned simulator/device and Metro port. Core is headless. Parallel
+checkouts must not share profiles, runtime directories, process markers, or
+evidence directories.
+
+On macOS, Extension Chromium uses a mock keychain so an isolated test profile
+does not touch the operator's login keychain. Product configuration and wallet
+fixtures remain user-owned; the harness detects missing prerequisites but never
+invents them.
+
+## Release checks
+
+Security-sensitive changes require:
+
+1. trust-boundary tests proving rejection occurs before side effects;
+2. exact-digest success and stale-digest rejection;
+3. redaction tests for arguments, results, journals, and evidence;
+4. packed-install provenance with no local links;
+5. independent review of the exact diff.
+
+Use [QA](QA.md) for the runnable checklist.

package/library/README.md

@@ -1,5 +1,9 @@
 # Recipe library
 
+- An **action** performs one typed operation.
+- A **recipe** is a parameterized, composable graph that may call actions and
+  other recipes.
+
 - `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.
@@ -9,6 +13,6 @@
 - Actions load harness helpers ONLY through `actions/harness-exports.mjs` (the
   dist-preferring bridge) — never deep-import `src/` (published installs have no
   src/, and the entrypoint would close an import cycle through adapters.ts).
-- `recipes/` — runnable smoke/validation recipes (`mm-harness run <file>`).
-- Flow resolution order is personal > team > canonical; shadowing is recorded in
-  summary.json (never silent).
+- `recipes/` — runnable recipes (`mm-harness run <name-or-file>`).
+- Recipe resolution is explicit library order, then bundled MetaMask; selected
+  variants and shadows are recorded in run evidence.