@deeeed/metamask-harness 0.17.4 → 0.18.0

package/docs/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# 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, flows, 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/flows/` | reusable parameterized behavior |
+| `library/recipes/` | reusable 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,185 @@
+# 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 flows
+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,161 @@
+# Recipes
+
+Use the smallest durable layer that proves the task:
+
+1. bundled actions;
+2. a bundled or team flow;
+3. a task-local recipe;
+4. a trusted task-local action or direct controller/CDP operation when no
+   stable action exists.
+
+Search before writing code:
+
+```bash
+mm-harness actions <intent>
+mm-harness actions --action <name>
+mm-harness flows
+mm-harness flows describe <ref> --json
+mm-harness run --list
+mm-harness run <name> --describe
+```
+
+Discovery reports the winning source, fields, examples, and shadowed sources.
+Use `--json` when an agent needs exact metadata.
+
+## Compose a proof
+
+An action performs one operation. A flow packages reusable product setup or
+behavior. A recipe owns the task's acceptance criteria and evidence.
+
+Minimal recipe:
+
+```json
+{
+  "schema_version": 1,
+  "title": "Wallet readiness proof",
+  "description": "Proves the running wallet is reachable and unlocked.",
+  "validate": {
+    "workflow": {
+      "entry": "unlock",
+      "nodes": {
+        "unlock": {
+          "action": "metamask.wallet.ensure_unlocked",
+          "intent": "Ensure the fixture-backed wallet is unlocked",
+          "next": "done"
+        },
+        "done": { "action": "end", "status": "pass" }
+      }
+    }
+  }
+}
+```
+
+Validate without side effects, then run:
+
+```bash
+mm-harness run recipe.json --plan
+mm-harness run recipe.json
+```
+
+To reuse an existing Extension build on a specific CDP runtime:
+
+```bash
+mm-harness run recipe.json --cdp-port 9500 --launch-existing-dist
+```
+
+Rules:
+
+- Use real product paths; never mutate DOM, Redux, controller, or persisted
+  state to fabricate proof.
+- Setup may use supported APIs, but a read/assert or visible UI postcondition
+  must prove the result.
+- Use `ui.*` for human-visible behavior. Keep ticket copy, styling, and layout
+  claims in the task recipe and screenshots.
+- Parameterize repeated behavior instead of multiplying action names.
+- Every `ensure_*` flow must prove a postcondition.
+- Keep secrets out of recipes, libraries, and evidence.
+
+The Recipe Protocol v1 schema is authoritative:
+<https://farmslot.io/docs/reference/recipe-protocol-v1>.
+
+## Share reusable behavior
+
+A library may contain manifests, action implementations, flows, and complete
+recipes:
+
+```text
+team-recipes/
+  library.json
+  manifests/extension.action-manifest.json
+  actions/extension/wallet/ensure_ready.mjs
+  flows/wallet.flows.json
+  recipes/onboarding/smoke.extension.recipe.json
+```
+
+Minimal `library.json`:
+
+```json
+{
+  "kind": "recipe-library",
+  "schema_version": 1,
+  "name": "wallet-team",
+  "owner": "wallet-team"
+}
+```
+
+Enable it:
+
+```bash
+export RECIPE_LIBRARY_PATH="wallet=$HOME/shared-library/wallet-team"
+mm-harness flows
+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. Without an explicit
+library, the personal library is `$FARMSLOT_HOME/recipe-library` (default
+`~/.farmslot/recipe-library`). Resolution is task/local configuration first,
+then bundled MetaMask; runs snapshot resolved definitions so shadowing is
+reviewable.
+
+Promote a repeated flow only after it has a useful description, typed params,
+and successful proof:
+
+```bash
+mm-harness flows promote --from recipe.json --flow wallet.ensure_ready --run artifacts
+```
+
+## Direct product access
+
+The bundled catalog is intentionally small. A task may use a real controller or
+CDP path when that is clearer than adding a permanent wrapper.
+
+Before doing so, validate the path in current product source and record:
+
+- the controller/API and supported parameters;
+- whether it reads or mutates state;
+- required preconditions;
+- the independent postcondition;
+- trace redaction.
+
+Do not infer route or controller names from memory. A direct mutation still
+requires a separate read/assert or visible UI proof. If the operation repeats
+across tasks, move it to a reviewed team library; promote it into the bundled
+catalog only when it is broadly reusable and stable across supported products.
+
+## Cross-platform expectations
+
+Mobile and Extension use the same wallet and Perps vocabulary where both expose
+the behavior. Core is headless: it reports fixture-backed controller inputs and
+does not pretend to have a selected UI account or app route.
+
+Inspect the current capability instead of assuming parity:
+
+```bash
+mm-harness actions --category wallet --json
+mm-harness actions --category perps --json
+mm-harness actions --action metamask.wallet.list_accounts --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/actions/core/perps/read_account.mjs

@@ -1,4 +1,4 @@
-import { getCoreController, runAdapter } from './_controller.mjs';
+import { getCoreController, isDirectRun, runAdapter } from './_controller.mjs';
 
 function redactAccount(account) {
   return {
@@ -27,4 +27,4 @@ export async function readAccount(input) {
   };
 }
 
-runAdapter(readAccount);
+if (isDirectRun(import.meta.url)) runAdapter(readAccount);

package/library/actions/core/perps/read_orders.mjs

@@ -1,5 +1,6 @@
 import {
   getCoreController,
+  isDirectRun,
   redactOrder,
   runAdapter,
   selectedItems,
@@ -24,4 +25,4 @@ export async function readOrders(input) {
   };
 }
 
-runAdapter(readOrders);
+if (isDirectRun(import.meta.url)) runAdapter(readOrders);

package/library/actions/core/perps/read_positions.mjs

@@ -1,5 +1,6 @@
 import {
   getCoreController,
+  isDirectRun,
   redactPosition,
   runAdapter,
   selectedItems,
@@ -24,4 +25,4 @@ export async function readPositions(input) {
   };
 }
 
-runAdapter(readPositions);
+if (isDirectRun(import.meta.url)) runAdapter(readPositions);