@deeeed/metamask-harness 0.17.0 → 0.17.2

package/docs/CHEATSHEET.md

@@ -1,61 +1,48 @@
-# mm-harness — user cheatsheet
+# mm-harness cheatsheet
 
-`mm-harness <command> [target] [flags]` · Run from inside any MetaMask checkout · Platform auto-detected
+Run inside a MetaMask checkout. Product, slot, ports, and runtime paths are
+auto-detected.
 
----
+## Operate
 
-## Daily loop
-
-| Situation | Command |
+| Need | Command |
 |---|---|
-| Start / relaunch iOS | `mm-harness launch ios` |
-| Start / relaunch Android | `mm-harness launch android` |
-| Launch extension (fullscreen) | `mm-harness launch` |
-| Launch extension in sidepanel | `mm-harness launch --sidepanel` |
-| Native code changed — rebuild first | `mm-harness launch ios --build` |
-| Tail Metro / webpack logs | `mm-harness logs` |
-| Open DevTools / RN inspector | `mm-harness debug` |
-| Seed wallet from fixture — no typing | `mm-harness fixtures set` |
-| Refresh wallet fixture files on slot | `mm-harness fixtures sync` |
-
-`launch` auto-installs the overlay on first use.
-`fixtures set` reads the password **from** the fixture — never typed.
-
----
-
-## Proof loop
-
-```
-actions  →  call <action>  →  flows  →  run recipe.json --plan  →  run recipe.json
+| Extension | `mm-harness launch` |
+| Extension sidepanel | `mm-harness launch --sidepanel` |
+| iOS / Android | `mm-harness launch ios` / `mm-harness launch android` |
+| Clean rebuild | `mm-harness launch --build` |
+| Runtime status | `mm-harness status` |
+| Logs | `mm-harness logs` |
+| Debugger | `mm-harness debug` |
+| Apply wallet fixture | `mm-harness fixtures set` |
+
+Extension log sources: `extension`, `dapp`, `webpack`, `watcher`, `rebuild`.
+Mobile log sources: `app`, `metro`.
+
+## Discover and prove
+
+```bash
+mm-harness actions positions
+mm-harness actions --action metamask.wallet.ensure_unlocked
+mm-harness call metamask.wallet.ensure_unlocked
+mm-harness flows
+mm-harness run recipe.json --plan
+mm-harness run recipe.json --artifacts-dir temp/recipe-proof
 ```
 
-| Command | What it does |
-|---|---|
-| `mm-harness actions` | Action vocabulary for this adapter |
-| `mm-harness call unlock` | One action through the real engine (fuzzy name ok) |
-| `mm-harness flows` | Reusable flows (personal > team > canonical) |
-| `mm-harness run recipe.json --plan` | Validate + print plan, no device touched; exit 5 if invalid |
-| `mm-harness run recipe.json` | Execute + write evidence (summary / trace / artifacts) |
-
----
+The run result prints diagnostics plus absolute evidence paths. Resume safely with
+`mm-harness last --json`.
 
-## Health
+## Recover
 
-| Command | What it does |
-|---|---|
-| `mm-harness doctor` | Full readiness check — fixture, runtime context, overlay. No launch. |
-| `mm-harness doctor --fix` | Repair overlay + runtime context without launching the app. |
-| `mm-harness verify` | Check overlay/runtime is present and healthy. No launch. |
-| `mm-harness cleanup` | Remove the overlay and restore the checkout. |
-
----
-
-## For agents and scripts
-
-**`--json`** — machine-readable output on every command; includes `recovered[]`, `mutations[]`, `schemaVersion`.
-
-**`--heal`** — `off` (fail fast, repro-preserving) · `infra-only` (heal transport, never wallet; `run`/`call` default) · `auto` (auto-ensure overlay + heal; `launch` default).
-
-**Exit codes** — `0` success · `1` recipe/action failed · `2` bad args / missing target · `5` validation failure (fix recipe).
+```bash
+mm-harness doctor
+mm-harness doctor --fix
+mm-harness verify
+mm-harness cleanup
+mm-harness update
+```
 
-**Tab completion** — `mm-harness completions install` prints the lines to add to `~/.zshrc` / `~/.bashrc`.
+For automation, add `--json`. Use `--json-stream` for line-delimited run progress.
+Bad input exits `2`; recipe/action failure exits `1`; recipe validation failure
+exits `5`.

package/docs/CLI-ERGONOMICS-HUMAN-QA.md

@@ -1,104 +1,48 @@
-# CLI ergonomics human QA
-
-Use this short pass after installing a release candidate. Automated contracts remain the release gate; this checklist confirms the experience in a real shell and checkout.
-
-## Setup
-
-```bash
-export TARGET=/absolute/path/to/a/metamask-checkout
-export ADAPTER=extension # extension, mobile, or core
-mm-harness --version
-mm-harness doctor --adapter "$ADAPTER" --target "$TARGET" --json | jq .status
-```
-
-Expected: the intended version is printed and `doctor` returns parseable JSON. Resolve required doctor failures before continuing.
-
-## 1. Teaching errors
-
-```bash
-out="$(mm-harness actions --categoriez --adapter "$ADAPTER" --json 2>/dev/null || true)"
-jq '.error | {code, message, userAction}' <<<"$out"
-```
-
-Expected: `code` is stable, the message names the bad flag and valid options, and `userAction` suggests the closest valid invocation.
-
-## 2. In-tool discovery
-
-```bash
-mm-harness actions --adapter "$ADAPTER" --categories
-mm-harness actions status --adapter "$ADAPTER"
-mm-harness actions --action app.status --adapter "$ADAPTER" --json | jq '{actions, relatedActions}'
-```
-
-Expected: category output is compact, fuzzy search is bounded, and action detail includes related actions when available. A missing example action should produce a teaching error, not silent output.
-
-## 3. Machine-output cleanliness and recovery
-
-```bash
-out="$(mm-harness call definitely.not.an.action --adapter "$ADAPTER" --target "$TARGET" --json 2>/dev/null || true)"
-jq '{status, error}' <<<"$out"
-```
-
-Expected: stdout is one parseable JSON document with `error.code`, `error.message`, and `error.userAction`; it contains no spinner, banner, or human-only glyph.
-
-## 4. Immediate human feedback
-
-Run the platform-appropriate launch in an interactive terminal:
-
-```bash
-# Extension
-mm-harness launch --adapter extension --target "$TARGET"
-
-# Mobile: choose the intended platform
-mm-harness launch ios --target "$TARGET"
-# mm-harness launch android --target "$TARGET"
-```
-
-Expected: intent/progress appears immediately, long work continues to report progress, and the app becomes ready. Redirected or `--json` stdout stays decoration-free.
-
-## 5. Lifecycle next step
-
-For Extension:
-
-```bash
-mm-harness stop --adapter extension --target "$TARGET" --json | jq '{status, next}'
-```
-
-Expected: `next` is a target-scoped launch command. Mobile `stop` intentionally omits `next` because Metro does not identify whether iOS or Android should be relaunched.
-
-## 6. Resume after interruption
-
-```bash
-mm-harness last --target "$TARGET" --json | jq '.last | {command, args, verdict, evidencePaths, startedAt, finishedAt}'
-```
-
-Expected: the last operation can be reconstructed without rerunning it, including its arguments, verdict, evidence paths, and timestamps.
-
-## 7. Recipe proof smoke
-
-```bash
-mm-harness run --list --adapter "$ADAPTER" --json | jq '{actions: .actions[0:5], flows: .flows[0:5]}'
-export RECIPE=replace-with-a-safe-recipe-name-or-path
-export ARTIFACTS_DIR="$(mktemp -d)"
-mm-harness run "$RECIPE" --plan --adapter "$ADAPTER" --target "$TARGET" --json | jq '{status, plan}'
-mm-harness run "$RECIPE" --adapter "$ADAPTER" --target "$TARGET" --artifacts-dir "$ARTIFACTS_DIR"
-```
-
-Expected: the plan validates before execution; the final result identifies evidence paths and `mm-harness last --json` records the run.
-
-Optional JSONL check:
-
-```bash
-mm-harness run "$RECIPE" --adapter "$ADAPTER" --target "$TARGET" --artifacts-dir "$ARTIFACTS_DIR-stream" --json-stream | jq -c .
-```
-
-Expected: complete JSON objects arrive line by line while the run is active.
-
-## Cleanup
-
-```bash
-[ "$ADAPTER" = core ] || mm-harness stop --adapter "$ADAPTER" --target "$TARGET"
-mm-harness status --target "$TARGET" --json | jq .
-```
-
-Record the harness version, checkout SHA, adapter/platform, failed command, exit code, and JSON envelope for any discrepancy.
+# Human QA
+
+Run this from each product checkout before a release. Verify the visible outcome,
+not only the exit code.
+
+## Common
+
+- [ ] `mm-harness --version` prints the candidate version.
+- [ ] `mm-harness doctor` detects the correct product and reports only current
+      configuration.
+- [ ] A misspelled flag explains the error and gives a runnable next command.
+- [ ] `mm-harness actions` and `mm-harness flows` return useful, bounded discovery.
+- [ ] `mm-harness fixtures set` either applies the fixture or names the missing
+      file and exact recovery action.
+- [ ] `mm-harness run <safe-recipe> --artifacts-dir temp/qa-proof` prints findings,
+      diagnostics, and absolute evidence paths.
+- [ ] `mm-harness last --json` identifies that run without rerunning it.
+- [ ] `mm-harness doctor --json` is one parseable document with no human decoration.
+
+## Extension
+
+- [ ] `mm-harness launch` opens/reuses the checkout's named Chrome profile.
+- [ ] `mm-harness launch --sidepanel` opens the MetaMask sidepanel without extra
+      Extension tabs.
+- [ ] `mm-harness debug` opens connected DevTools for the active MetaMask target.
+- [ ] `mm-harness logs --source extension` shows Extension console events.
+- [ ] `mm-harness logs --source dapp` shows dapp console events separately.
+- [ ] Edit a visible source string twice, waiting for successful incremental
+      compilation after each edit; refresh the browser and confirm both changes.
+- [ ] Revert the edit, confirm a third incremental compilation, and verify the
+      same watcher and Chrome process were reused.
+
+## Mobile
+
+- [ ] `mm-harness launch ios` boots/reuses the intended simulator and opens the app.
+- [ ] `mm-harness launch android` targets the intended emulator/device.
+- [ ] `mm-harness logs --source metro` and `--source app` show distinct streams.
+- [ ] `mm-harness debug` opens the usable React Native developer surface.
+- [ ] Change a visible JS string, confirm Metro rebuilds, reload the app, and see
+      the change without a native rebuild.
+
+## Core
+
+- [ ] `mm-harness status`, `doctor`, `actions`, `flows`, and a safe recipe run work
+      without browser/device assumptions.
+
+Record the command, version, checkout SHA, visible mismatch, exit code, and JSON
+error envelope for any failure.

package/docs/CODE-MAP.md

@@ -11,7 +11,7 @@ bin/mm-harness                 bash front door: MM_HARNESS_BIN dev/prod switch,
   │                            stale-dist warning), deps ensure
   ▼
 src/mm-harness-cli.ts          commander surface: grouped colored help, per-command
-  │                            --help, retired-name teaching; delegates in-process
+  │                            --help and usage errors; delegates in-process
   ▼
 src/cli.ts                     parse + dispatch ONLY — no verb logic lives here
   │

package/docs/VIDEO-DEMO-VALIDATION.md

@@ -0,0 +1,62 @@
+# Video demo validation
+
+Candidate: local packed `@deeeed/metamask-harness` 0.17.1 installed globally.
+Run commands from the named checkout; product/ports are auto-detected.
+
+## Common
+
+- [x] `mm-harness --version` prints `0.17.1` from the global npm install.
+- [x] `yarn check` passes.
+- [x] No `package-lock.json`; Yarn state is valid.
+- [x] Current source/docs contain no compatibility or removed-command paths.
+- [x] `doctor` reports current runtime fields only.
+- [x] Recipe results print diagnostics and absolute artifact paths inline.
+
+## Extension (`mme-2`)
+
+- [x] `mm-harness doctor` reports healthy CDP and active webpack watcher.
+- [x] `mm-harness run runner.smoke --artifacts-dir temp/final-demo-smoke` passes.
+- [x] Smoke prints six absolute evidence paths and `diagnostics: CLEAN`.
+- [x] `mm-harness debug` connects native DevTools to the active slot target.
+- [x] Fullscreen and sidepanel targets are selectable.
+- [x] Two source edits plus revert compiled incrementally with the same watcher;
+      browser refresh showed each change without relaunch.
+
+## Mobile (`mm-1`, iOS)
+
+- [x] `mm-harness install` writes metadata only; product checkout remains clean.
+- [x] `mm-harness fixtures set` reads the canonical fixture and unlocks `dev1`.
+- [x] `mm-harness call metamask.wallet.ensure_unlocked` passes from the global package.
+- [x] `mm-harness verify` passes after fixture setup.
+- [x] `mm-harness status` reports `WalletView`, unlocked wallet, selected account,
+      and fixture `READY`.
+- [ ] During the recording, visually confirm the expected simulator is foregrounded.
+
+## Core (`core-1`)
+
+- [x] `mm-harness doctor` reports the headless controller ready.
+- [x] Canonical wallet fixture is present.
+- [x] `mm-harness run perps.smoke --artifacts-dir temp/final-demo-smoke` passes.
+- [x] Positions, orders, and account state are read through the controller.
+- [x] Evidence prints absolute paths; diagnostics correctly reports `N/A` for headless Core.
+
+## Recording sequence
+
+```bash
+# Extension
+cd /Users/deeeed/farmslot/repos/mme-2
+mm-harness doctor
+mm-harness actions positions
+mm-harness flows
+mm-harness run runner.smoke --artifacts-dir temp/demo
+
+# Mobile
+cd /Users/deeeed/farmslot/repos/mm-1
+mm-harness launch ios
+mm-harness fixtures set
+mm-harness call metamask.wallet.ensure_unlocked
+
+# Core
+cd /Users/deeeed/farmslot/repos/core-1
+mm-harness run perps.smoke --artifacts-dir temp/demo
+```