@deeeed/metamask-harness 0.17.5 → 0.18.0

package/adapters/mobile/overlay/compat/README.md

@@ -1,28 +0,0 @@
-# Compatibility overlays (historical-commit replay)
-
-NOT dead code. These overlays exist for replay/eval runs against OLD product
-commits — e.g. re-running a historical task on a fixed baseline to validate
-prompt or harness changes. A "zero current references" scan will always come
-up empty here by design: the feature's purpose is non-current checkouts.
-
-- Purpose: make historical product checkouts bootable/bridgeable under the
-  current local toolchain so Recipe v1 evals can replay against them.
-- When it applies: mobile checkouts predating React Native 0.81 polyfill fixes.
-- How it is applied: MANUALLY (no automatic apply logic in this repo).
-  The operator or the `/recipe-harness` skill applies the patch reversibly
-  before a historical rebuild (`git apply <patch>` in the product checkout,
-  `git apply -R` to remove) and records the overlay path in validation
-  evidence. `adapters/mobile/inject.sh` does NOT apply these.
-
-Kept in the external runner repository, not Farmslot root scripts, so a
-`/recipe-harness` skill can apply the same reversible overlay before a
-historical rebuild and record the overlay path in validation evidence.
-
-Listed in adapters/manifest.json (kind: compat-overlay) so the doctor
-verifies the surface and this directory is never flagged as unused again.
-
-## Patches
-
-- `rn81-message-event-source.patch`: adds a read-only `MessageEvent.prototype.source`
-  getter for React Native 0.81 historical checkouts whose bundled polyfill omits
-  it while CDP websocket clients expect browser-compatible `MessageEvent` shape.

package/adapters/mobile/overlay/compat/rn81-message-event-source.patch

@@ -1,42 +0,0 @@
-compat-overlay: rn81-message-event-source (historical-checkout replay support)
-
-What: patches metamask-mobile shim.js to add a read-only
-MessageEvent.prototype.source getter.
-Why: the harness CDP bridge expects browser-compatible MessageEvent shape;
-pre-RN-0.81 checkouts ship a polyfill that omits .source, so the bridge
-cannot attach when replaying tasks on those historical commits.
-When: only when replaying/evaluating against mobile checkouts older than the
-RN 0.81 upgrade (pre-RN-0.81 checkouts). Never needed on current main.
-How: applied MANUALLY in the historical product checkout —
-  git apply <this file>     (and `git apply -R` to remove)
-No automatic apply logic exists in this repo. See ../README.md.
-
-diff --git a/shim.js b/shim.js
---- a/shim.js
-+++ b/shim.js
-@@
- if (typeof global.MessageEvent === 'undefined') {
-   global.MessageEvent =
-     require('react-native/src/private/webapis/html/events/MessageEvent').default;
- }
- 
-+// Historical runner compatibility: React Native 0.81's MessageEvent polyfill
-+// can omit the browser `source` getter expected by CDP websocket clients under
-+// newer Xcode/Hermes toolchains. Keep the getter read-only and null, matching
-+// browser MessageEvent semantics for non-window messages.
-+if (
-+  global.MessageEvent?.prototype &&
-+  !Object.getOwnPropertyDescriptor(global.MessageEvent.prototype, 'source')
-+) {
-+  Object.defineProperty(global.MessageEvent.prototype, 'source', {
-+    configurable: true,
-+    enumerable: true,
-+    get() {
-+      return null;
-+    },
-+  });
-+}
-+
- class AbortError extends Error {
-   constructor(message) {
-     super(message);

package/adapters/shared/resolve-farmslot-ports-core.mjs

@@ -1,3 +0,0 @@
-// Back-compat shim: the port-resolution core is now resolve-slot-ports-core.mjs.
-// Re-exports it verbatim for one release so importers of the old path keep resolving.
-export * from './resolve-slot-ports-core.mjs';

package/adapters/shared/resolve-farmslot-ports.mjs

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-// Back-compat shim: this leaf is now resolve-slot-ports.mjs. Delegates to it for one
-// release so `node resolve-farmslot-ports.mjs <fn> <repo>` keeps working (the new CLI
-// reads the same argv positions on import).
-import './resolve-slot-ports.mjs';

package/adapters/shared/resolve-farmslot-ports.sh

@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-# Back-compat shim: this wrapper is now resolve-slot-ports.sh. Sources it for one
-# release so old callers keep the same sourced function names (including the
-# resolve_farmslot_ports_by_repo alias defined there).
-_SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck disable=SC1091
-. "$_SHIM_DIR/resolve-slot-ports.sh"

package/docs/ADAPTER-SURFACE.md

@@ -1,119 +0,0 @@
-# The adapter surface — one seam for per-platform behavior
-
-`mm-harness` runs against three platforms (mobile | extension | core). The
-danger is that every command re-derives "what does this platform do?" with its
-own `if (adapter === 'mobile') … else if (adapter === 'extension') …` ladder.
-When it does, a platform gets forgotten in one command but not another — the
-class of bug where `doctor` reported a live runtime section for mobile only,
-`stop` refused every non-mobile adapter, and `logs` knew a single extension log
-file instead of all three. Those are *platform-blind* commands.
-
-The **adapter surface** is the fix: one interface per platform, resolved through
-a registry, that owns the behavior a command would otherwise branch on.
-
-## The interface
-
-`src/adapters/surface.ts` defines `AdapterSurface` and the registry
-`getAdapterSurface(adapter)`. Each platform ships one implementation:
-
-- `src/adapters/mobile/surface.ts`
-- `src/adapters/extension/surface.ts`
-- `src/adapters/core/surface.ts`
-
-```ts
-interface AdapterSurface {
-  readonly adapter: MetaMaskRecipeAdapter;
-  readonly headless: boolean;                       // core runs no app/dev server
-  resolveSlotPorts(target: string): void;           // context > pool > formula (no-op for core)
-  runtimeStatus(target: string): Promise<AdapterRuntimeStatus>; // read-only readiness for doctor
-  devServer: {
-    describe(): string;                             // "Metro" | "webpack watcher" | "no dev server (headless)"
-    stop(target: string): AdapterDevServerStop;     // idempotent, slot-scoped; headless = teach
-  };
-  logSources(target: string): AdapterLogSource[];   // ordered candidate log files (empty for core)
-  hints: { launch: string; relaunch: string };      // platform-phrased Next: hints
-}
-```
-
-`runtimeStatus` returns a normalized shape so `doctor` renders one line the same
-way for every platform:
-
-```ts
-interface AdapterRuntimeStatus {
-  decision: string;
-  reasonCode?: string;
-  reasons: string[];
-  deps?: string;
-  devServer?: { label: string; status: string };    // absent for headless core
-}
-```
-
-The implementations are thin: they delegate to the readiness/port plumbing that
-already existed (`decideExtensionReadiness`, `mobileRuntimeStatus`, the slot-port
-resolvers and the webpack-watcher stop, all re-homed to
-`src/adapters/slot-ports.ts`). The surface is an organizing seam, not a rewrite.
-
-## The rule
-
-**A command never branches on adapter for behavior the surface owns.**
-
-- Do not write `if (adapter === 'core')` — ask `surface.headless`.
-- Do not write `adapter === 'mobile' ? metroPorts() : extensionPorts()` — call
-  `surface.resolveSlotPorts(target)`.
-- Do not print `adapter === 'mobile' ? 'mm-harness launch ios' : 'mm-harness
-  launch'` — use `surface.hints.launch`.
-
-A new platform behavior is added by **extending the surface** (a new member on
-the interface plus its three implementations), never by adding another branch to
-a command. TypeScript then makes it impossible to ship a platform that forgot the
-new member, because each implementation is annotated `: AdapterSurface`.
-
-What the surface deliberately does **not** own: a command may still branch on
-adapter for a *mechanism* that is genuinely platform-specific and not part of the
-interface — e.g. `fixtures set` uses a shell arm on mobile and the engine path on
-extension. Those branches select a mechanism; they never re-derive readiness,
-ports, log locations, dev-server lifecycle, or Next: phrasing, which are the
-surface's responsibility.
-
-## Migration status
-
-Every command that used to branch on adapter now resolves through the surface:
-
-| command | surface-backed | uses |
-| --- | --- | --- |
-| `doctor` | yes | `resolveSlotPorts` + `runtimeStatus` (mobile/extension/core runtime section) |
-| `launch` | yes | `resolveSlotPorts` |
-| `stop` | yes | `resolveSlotPorts` + `devServer.stop` (+ headless teaching) |
-| `logs` | yes | `logSources` + `hints.launch` + `headless` |
-| `debug` | yes | `headless` + `hints.relaunch` (core teaching); flag semantics stay per-command |
-| `fixtures` | yes | `headless` + `hints` (retry/launch); the set *mechanism* stays per-platform |
-| `run` / `call` | n/a | engine path; core-headless is handled by the heal contract, not the surface |
-| `flows` | no (by design) | recipe-library flows are adapter-global; not a platform-owned behavior |
-| `completion-candidates` | partial | `actions` scope to the detected checkout adapter; `flows` are adapter-global |
-
-`flows` is intentionally not surface-backed: a recipe-library flow can compose
-actions across platforms, so flows are adapter-global by design rather than a
-platform-blind gap. `completion-candidates actions` already resolves the adapter
-from the checkout context (cwd/`--target`); only the adapter-global `flows`
-candidates are unscoped, matching the flows model.
-
-## How this composes with the UX principles
-
-`docs/UX-PRINCIPLES.md` principle 1 (*Context-aware by default* — "output is
-scoped to the platform… help, flag lists, and completion candidates shrink to
-what applies here") states the intent. The adapter surface is its **enforcement
-mechanism**: a command that resolves platform behavior through the surface is
-context-aware by construction, and one that hand-rolls an adapter ladder is the
-exact failure principle 1 warns against. When adding a command or output path,
-satisfy principle 1 by going through the surface.
-
-## Adding a platform behavior — checklist
-
-1. Add the member to `AdapterSurface` in `src/adapters/surface.ts`.
-2. Implement it in all three `src/adapters/*/surface.ts` (TypeScript will not
-   compile until you do).
-3. Have the command call `getAdapterSurface(adapter).<member>` instead of
-   branching.
-4. Cover the closed blind spot with a contract test (see
-   `tests/contract/adapter-surface.test.sh`), and keep the registry-completeness
-   assertion green.

package/docs/CHEATSHEET.md

@@ -1,61 +0,0 @@
-# mm-harness — user cheatsheet
-
-`mm-harness <command> [target] [flags]` · Run from inside any MetaMask checkout · Platform auto-detected
-
----
-
-## Daily loop
-
-| Situation | 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
-```
-
-| 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) |
-
----
-
-## Health
-
-| 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).
-
-**Tab completion** — `mm-harness completions install` prints the lines to add to `~/.zshrc` / `~/.bashrc`.