@deeeed/metamask-harness 0.17.4 → 0.18.0

package/library/actions/core/wallet/list_accounts.mjs

@@ -0,0 +1,95 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
+
+import { walletFixturePath } from '../../harness-exports.mjs';
+
+function fixtureAccountName(base, index, count) {
+  if (count === 1) return base || 'account1';
+  const match = /^(.*?)(\d+)$/u.exec(base || 'account1');
+  return match
+    ? `${match[1]}${Number(match[2]) + index}`
+    : `${base || 'account'}${index + 1}`;
+}
+
+function mnemonicCount(entry, fixturePath, index) {
+  const count = Number(entry.count ?? entry.numberOfAccounts ?? 1);
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new Error(`${fixturePath} accounts[${index}] mnemonic count must be an integer from 1 through 100.`);
+  }
+  return count;
+}
+
+function deriveFixtureAccounts(fixture, fixturePath) {
+  if (!Array.isArray(fixture.accounts) || fixture.accounts.length === 0) {
+    throw new Error(`wallet fixture at ${fixturePath} has no accounts array.`);
+  }
+  return fixture.accounts.flatMap((entry, fixtureIndex) => {
+    if (!entry || typeof entry !== 'object' || typeof entry.value !== 'string' || !entry.value.trim()) {
+      throw new Error(`${fixturePath} accounts[${fixtureIndex}] must contain a non-empty value.`);
+    }
+    if (entry.type === 'mnemonic') {
+      const count = mnemonicCount(entry, fixturePath, fixtureIndex);
+      return Array.from({ length: count }, (_, addressIndex) => {
+        const account = mnemonicToAccount(entry.value.trim(), { addressIndex });
+        return {
+          id: `fixture:${fixtureAccountName(entry.name, addressIndex, count)}`,
+          address: account.address,
+          name: fixtureAccountName(entry.name, addressIndex, count),
+          type: 'eip155:eoa',
+        };
+      });
+    }
+    if (entry.type === 'privateKey') {
+      const raw = entry.value.trim();
+      const normalized = raw.startsWith('0x') ? raw : `0x${raw}`;
+      if (!/^0x[0-9a-fA-F]{64}$/u.test(normalized)) {
+        throw new Error(`${fixturePath} accounts[${fixtureIndex}] privateKey is not a 32-byte hex key.`);
+      }
+      const account = privateKeyToAccount(normalized);
+      const name = entry.name || `account${fixtureIndex + 1}`;
+      return [{ id: `fixture:${name}`, address: account.address, name, type: 'eip155:eoa' }];
+    }
+    throw new Error(`${fixturePath} accounts[${fixtureIndex}].type must be mnemonic or privateKey.`);
+  });
+}
+
+async function listAccounts(input) {
+  const scope = input.node?.scope == null ? 'named' : String(input.node.scope);
+  if (scope !== 'selected' && scope !== 'named' && scope !== 'evm' && scope !== 'all') {
+    throw new Error('metamask.wallet.list_accounts scope must be selected, named, evm, or all.');
+  }
+  const fixturePath = walletFixturePath(input.context.projectRoot);
+  const fixture = JSON.parse(await readFile(fixturePath, 'utf8'));
+  const selectedName = String(input.node?.account_name ?? input.node?.account ?? 'dev1');
+  const accounts = deriveFixtureAccounts(fixture, fixturePath)
+    .map((account) => ({
+      ...account,
+      selected: account.name === selectedName,
+    }))
+    .filter((account) => {
+      if (scope === 'selected') return account.selected;
+      if (scope === 'all') return true;
+      if (scope === 'evm') return /^0x[0-9a-f]{40}$/iu.test(account.address);
+      return account.selected || Boolean(account.name.trim());
+    });
+  return {
+    action: input.action,
+    source: 'core-headless-wallet-fixture',
+    scope,
+    accounts,
+    count: accounts.length,
+    redacted: true,
+    selectionSource: 'explicit-controller-account-input',
+    proofPath: 'core-wallet-fixture-accounts',
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const inputPath = process.argv[2] || process.env.METAMASK_RECIPE_ADAPTER_INPUT;
+  if (!inputPath) throw new Error('Adapter input path is required.');
+  const input = JSON.parse(await readFile(inputPath, 'utf8'));
+  const result = await listAccounts(input);
+  if (input.outputPath) await writeFile(input.outputPath, `${JSON.stringify(result, null, 2)}\n`);
+  else process.stdout.write(`${JSON.stringify(result)}\n`);
+}

package/library/actions/extension/platform/cdp.mjs

@@ -397,6 +397,7 @@ async function launchExistingDistRuntime(input, port) {
   try {
     child = spawn(chrome, [
       `--user-data-dir=${profileDir}`,
+      ...(process.platform === 'darwin' ? ['--use-mock-keychain'] : []),
       '--remote-debugging-address=127.0.0.1',
       `--remote-debugging-port=${port}`,
       '--no-first-run',

package/library/actions/extension/wallet/list_accounts.mjs

@@ -0,0 +1,41 @@
+import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
+
+runAdapter((input) => withExtensionPage(input, async (page) => {
+  const scope = input.node?.scope == null ? 'named' : String(input.node.scope);
+  if (scope !== 'selected' && scope !== 'named' && scope !== 'evm' && scope !== 'all') {
+    throw new Error('metamask.wallet.list_accounts scope must be selected, named, evm, or all.');
+  }
+  const result = await page.evaluate(`(() => {
+    const store = globalThis.stateHooks?.store;
+    if (!store || typeof store.getState !== 'function') {
+      throw new Error('stateHooks.store.getState is unavailable.');
+    }
+    const internal = store.getState()?.metamask?.internalAccounts || {};
+    const selectedId = internal.selectedAccount || null;
+    const scope = ${JSON.stringify(scope)};
+    const accounts = Object.entries(internal.accounts || {})
+      .map(([id, account]) => ({
+        id,
+        address: account?.address || null,
+        name: account?.metadata?.name || null,
+        type: account?.type || null,
+        selected: id === selectedId
+      }))
+      .filter((account) => {
+        if (scope === 'selected') return account.selected;
+        if (scope === 'all') return true;
+        if (scope === 'evm') return /^0x[0-9a-f]{40}$/iu.test(account.address || '');
+        return account.selected || Boolean(String(account.name || '').trim());
+      });
+    return { accounts };
+  })()`);
+  return {
+    action: input.action,
+    source: 'extension-stateHooks-store',
+    scope,
+    ...result,
+    count: result.accounts.length,
+    redacted: true,
+    proofPath: 'extension-wallet-accounts',
+  };
+}));

package/library/actions/mobile/platform/bridge.mjs

@@ -529,14 +529,10 @@ async function androidScreenshot(input, relPath) {
 async function resolveAndroidScreenshotSerial(input) {
   const contextEnv = input.context?.env || {};
   const explicit = input.node?.adb_serial ??
-    input.node?.android_device ??
-    input.node?.device ??
     contextEnv.ADB_SERIAL ??
     contextEnv.ANDROID_SERIAL ??
-    contextEnv.ANDROID_DEVICE ??
     process.env.ADB_SERIAL ??
-    process.env.ANDROID_SERIAL ??
-    process.env.ANDROID_DEVICE;
+    process.env.ANDROID_SERIAL;
   if (explicit !== undefined && explicit !== null && String(explicit).trim()) return String(explicit).trim();
 
   let result;

package/library/actions/mobile/wallet/list_accounts.mjs

@@ -0,0 +1,37 @@
+import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
+
+runAdapter(async (input) => {
+  const scope = input.node?.scope == null ? 'named' : String(input.node.scope);
+  if (scope !== 'selected' && scope !== 'named' && scope !== 'evm' && scope !== 'all') {
+    throw new Error('metamask.wallet.list_accounts scope must be selected, named, evm, or all.');
+  }
+  const rawAccounts = await bridgeCommand(input, ['list-accounts']);
+  if (!Array.isArray(rawAccounts)) {
+    throw new Error(`metamask.wallet.list_accounts expected an array, got ${typeof rawAccounts}.`);
+  }
+  const selected = await bridgeCommand(input, ['get-selected-account']);
+  const selectedAddress = String(selected?.address ?? selected ?? '').toLowerCase();
+  const accounts = rawAccounts
+    .map((account) => ({
+      id: account?.id ?? null,
+      address: account?.address ?? null,
+      name: account?.name ?? null,
+      type: account?.type ?? null,
+      selected: Boolean(selectedAddress && String(account?.address ?? '').toLowerCase() === selectedAddress),
+    }))
+    .filter((account) => {
+      if (scope === 'selected') return account.selected;
+      if (scope === 'all') return true;
+      if (scope === 'evm') return /^0x[0-9a-f]{40}$/iu.test(String(account.address ?? ''));
+      return account.selected || Boolean(String(account.name ?? '').trim());
+    });
+  return {
+    action: input.action,
+    source: 'mobile-accounts-controller',
+    scope,
+    accounts,
+    count: accounts.length,
+    redacted: true,
+    proofPath: 'agentic-wallet-accounts',
+  };
+});

package/library/manifests/core.action-manifest.json

@@ -162,6 +162,18 @@
         }
       ]
     },
+    "metamask.wallet.list_accounts": {
+      "description": "List redacted headless fixture accounts available to Core controller actions.",
+      "examples": [
+        {
+          "description": "List configured Core accounts",
+          "node": {
+            "action": "metamask.wallet.list_accounts",
+            "intent": "Discover the accounts available to headless controller actions"
+          }
+        }
+      ]
+    },
     "metamask.perps.read_positions": {
       "description": "Read live Perps positions directly from the perps controller (HyperLiquid testnet, HTTP read-only) and return the selected subset.",
       "examples": [
@@ -392,6 +404,51 @@
     }
   },
   "custom_actions": [
+    {
+      "name": "metamask.wallet.list_accounts",
+      "owner": "metamask",
+      "description": "List redacted headless fixture accounts available to Core controller actions.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "const": "metamask.wallet.list_accounts"
+          },
+          "scope": {
+            "type": "string",
+            "enum": [
+              "selected",
+              "named",
+              "evm",
+              "all"
+            ],
+            "description": "Account scope. Core fixtures are EVM-only today; selected filters to the explicit controller account input."
+          },
+          "account": {
+            "type": "string",
+            "description": "Optional account name to mark as selected for the next controller operation; defaults to dev1."
+          },
+          "account_name": {
+            "type": "string",
+            "description": "Alias for account."
+          }
+        },
+        "required": [
+          "action"
+        ]
+      },
+      "examples": [
+        {
+          "description": "List configured Core accounts",
+          "node": {
+            "action": "metamask.wallet.list_accounts",
+            "intent": "Discover the accounts available to headless controller actions"
+          }
+        }
+      ],
+      "proof_effect": "Records the redacted addresses derived from the same wallet fixture used by headless controller actions.",
+      "safety_notes": "Read-only fixture metadata; must never return private keys, mnemonics, passwords, or vault data."
+    },
     {
       "name": "metamask.perps.read_positions",
       "owner": "metamask",
@@ -1486,6 +1543,10 @@
       "action": "app.status",
       "implementation": "@metamask/recipe-runner/platform-status"
     },
+    {
+      "action": "metamask.wallet.list_accounts",
+      "implementation": "@metamask/recipe-runner/core/wallet"
+    },
     {
       "action": "metamask.perps.read_positions",
       "implementation": "@metamask/recipe-runner/core/perps"

package/library/manifests/extension.action-manifest.json

@@ -516,6 +516,18 @@
         }
       ]
     },
+    "metamask.wallet.list_accounts": {
+      "description": "List redacted wallet accounts and identify the selected account without mutating the app.",
+      "examples": [
+        {
+          "description": "List wallet accounts",
+          "node": {
+            "action": "metamask.wallet.list_accounts",
+            "intent": "Discover the available wallet accounts"
+          }
+        }
+      ]
+    },
     "metamask.wallet.read_state": {
       "description": "Read the redacted wallet state (selected account, route, and device) from the running app.",
       "examples": [
@@ -911,6 +923,43 @@
       ],
       "owner": "metamask"
     },
+    {
+      "name": "metamask.wallet.list_accounts",
+      "owner": "metamask",
+      "description": "List redacted wallet accounts and identify the selected account without mutating the app.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "const": "metamask.wallet.list_accounts"
+          },
+          "scope": {
+            "type": "string",
+            "enum": [
+              "selected",
+              "named",
+              "evm",
+              "all"
+            ],
+            "description": "Account scope. Defaults to named human-visible accounts; use selected for the active account, evm for EVM accounts, or all for the full inventory."
+          }
+        },
+        "required": [
+          "action"
+        ]
+      },
+      "examples": [
+        {
+          "description": "List wallet accounts",
+          "node": {
+            "action": "metamask.wallet.list_accounts",
+            "intent": "Discover the available wallet accounts"
+          }
+        }
+      ],
+      "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or target runtime output.",
+      "safety_notes": "Read-only account metadata; must never expose keys, mnemonics, vault data, or credentials."
+    },
     {
       "name": "metamask.wallet.read_state",
       "owner": "metamask",
@@ -2045,6 +2094,10 @@
       "action": "metamask.wallet.select_account",
       "implementation": "@metamask/recipe-runner/extension/wallet"
     },
+    {
+      "action": "metamask.wallet.list_accounts",
+      "implementation": "@metamask/recipe-runner/extension/wallet"
+    },
     {
       "action": "metamask.wallet.read_state",
       "implementation": "@metamask/recipe-runner/extension/wallet"

package/library/manifests/mobile.action-manifest.json

@@ -550,6 +550,18 @@
         }
       ]
     },
+    "metamask.wallet.list_accounts": {
+      "description": "List redacted wallet accounts and identify the selected account without mutating the app.",
+      "examples": [
+        {
+          "description": "List wallet accounts",
+          "node": {
+            "action": "metamask.wallet.list_accounts",
+            "intent": "Discover the available wallet accounts"
+          }
+        }
+      ]
+    },
     "metamask.wallet.read_state": {
       "description": "Read the redacted wallet state (selected account, route, and device) from the running app.",
       "examples": [
@@ -947,6 +959,43 @@
       "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or target runtime output.",
       "safety_notes": "Must not inject mid-recipe UI/app state to fabricate proof."
     },
+    {
+      "name": "metamask.wallet.list_accounts",
+      "owner": "metamask",
+      "description": "List redacted wallet accounts and identify the selected account without mutating the app.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "const": "metamask.wallet.list_accounts"
+          },
+          "scope": {
+            "type": "string",
+            "enum": [
+              "selected",
+              "named",
+              "evm",
+              "all"
+            ],
+            "description": "Account scope. Defaults to named human-visible accounts; use selected for the active account, evm for EVM accounts, or all for the full inventory."
+          }
+        },
+        "required": [
+          "action"
+        ]
+      },
+      "examples": [
+        {
+          "description": "List wallet accounts",
+          "node": {
+            "action": "metamask.wallet.list_accounts",
+            "intent": "Discover the available wallet accounts"
+          }
+        }
+      ],
+      "proof_effect": "E2E validation must record this action in trace.json; live-proof actions include liveAdapter/proofPath or target runtime output.",
+      "safety_notes": "Read-only account metadata; must never expose keys, mnemonics, vault data, or credentials."
+    },
     {
       "name": "metamask.wallet.read_state",
       "owner": "metamask",
@@ -2092,6 +2141,10 @@
       "action": "metamask.wallet.select_account",
       "implementation": "@metamask/recipe-runner/mobile/wallet"
     },
+    {
+      "action": "metamask.wallet.list_accounts",
+      "implementation": "@metamask/recipe-runner/mobile/wallet"
+    },
     {
       "action": "metamask.wallet.read_state",
       "implementation": "@metamask/recipe-runner/mobile/wallet"

package/library/recipes/runner/action-validation.extension.recipe.json

@@ -125,11 +125,18 @@
         },
         "wallet-read-state": {
           "action": "metamask.wallet.read_state",
-          "next": "extension-account-list",
+          "next": "wallet-list-accounts",
           "intent": "Read wallet state for proof",
           "detail": "Capture selected account and network state without mutating UI.",
           "flow": "wallet"
         },
+        "wallet-list-accounts": {
+          "action": "metamask.wallet.list_accounts",
+          "next": "extension-account-list",
+          "intent": "List wallet accounts for proof",
+          "detail": "Capture redacted account metadata and the selected account without mutating the app.",
+          "flow": "wallet"
+        },
         "app-navigate-wallet": {
           "action": "ui.navigate",
           "next": "app-navigate-perps",

package/library/recipes/runner/action-validation.mobile.recipe.json

@@ -125,11 +125,18 @@
         },
         "wallet-read-state": {
           "action": "metamask.wallet.read_state",
-          "next": "select-account",
+          "next": "wallet-list-accounts",
           "intent": "Read wallet state for proof",
           "detail": "Capture selected account and network state without mutating UI.",
           "flow": "wallet"
         },
+        "wallet-list-accounts": {
+          "action": "metamask.wallet.list_accounts",
+          "next": "select-account",
+          "intent": "List wallet accounts for proof",
+          "detail": "Capture redacted account metadata and the selected account without mutating the app.",
+          "flow": "wallet"
+        },
         "select-account": {
           "action": "metamask.wallet.select_account",
           "address": "0x8dc623e964475d4d669da601fd15ea9125469003",

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.17.4",
+  "version": "0.18.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
   },
   "scripts": {
     "build": "node scripts/build-dist.mjs",
-    "audit:cli-ergonomics": "node scripts/generate-cli-ergonomics-audit.mjs",
     "prepack": "npm run build",
     "dev:link-farmslot": "node scripts/link-local-farmslot.mjs",
     "check": "node scripts/check.mjs",
+    "test:unit": "vitest run --config scripts/vitest.config.mjs",
+    "test:coverage": "vitest run --coverage --config scripts/vitest.config.mjs",
     "qa:human": "node scripts/validate-human-outcomes.mjs",
     "self-test": "bin/mm-harness self-test",
     "manifest:mobile": "bin/mm-harness actions --raw --adapter mobile --json",
@@ -19,9 +20,11 @@
   },
   "dependencies": {
     "@farmslot/agent-runtime": "^0.2.0",
-    "@farmslot/protocol": "^0.8.0",
-    "@farmslot/recipe-harness": "^0.5.0",
+    "@farmslot/protocol": "^0.10.0",
+    "@farmslot/recipe-harness": "^0.8.0",
     "commander": "^12.0.0",
+    "es-module-lexer": "2.3.1",
+    "esbuild": "0.28.1",
     "viem": "^2.54.3",
     "ws": "8.21.0"
   },
@@ -33,12 +36,13 @@
   "devDependencies": {
     "@eslint/js": "^9",
     "@types/node": "^22.0.0",
-    "esbuild": "0.28.1",
+    "@vitest/coverage-v8": "^4.1.10",
     "eslint": "^9",
     "globals": "^17.7.0",
     "tsx": "^4.23.0",
     "typescript": "^5.6.0",
-    "typescript-eslint": "^8"
+    "typescript-eslint": "^8",
+    "vitest": "^4.1.10"
   },
   "main": "./dist/index.js",
   "exports": {

package/scripts/completions.sh

@@ -3,9 +3,9 @@
 #
 # Static parts (commands, positional targets, per-command flags) mirror the
 # mm-harness surface. Dynamic parts are sourced live from the hidden
-# `mm-harness completion-candidates <actions|flows>` command (per-checkout cached):
+# `mm-harness completion-candidates <actions|recipes>` command (per-checkout cached):
 #   call <TAB>   → action names from the adapter manifest
-#   run  <TAB>   → recipe files + flow refs from the recipe library
+#   run  <TAB>   → recipe files + named recipes from the recipe library
 # so completion reflects the installed overlay's real vocabulary. A candidate read
 # that fails is silently empty — completion never blocks the shell.
 #
@@ -41,9 +41,9 @@ _mmh_flags_for() {
     fixtures) printf '%s' "--from --dev --force --fixture --adapter --target --json" ;;
     checklist) printf '%s' "" ;;
     actions)  printf '%s' "--adapter --action --kind --raw --action-manifest --target --json" ;;
-    call)     printf '%s' "--arg --adapter --target --artifacts-dir --action-manifest --heal --json" ;;
+    call)     printf '%s' "--list --arg --adapter --target --artifacts-dir --action-manifest --heal --json" ;;
     flows)    printf '%s' "--library --json" ;;
-    run)      printf '%s' "--plan --adapter --artifacts-dir --target --library --cdp-port --heal --record-video --json" ;;
+    run)      printf '%s' "--list --describe --plan --adapter --artifacts-dir --target --library --cdp-port --heal --record-video --json" ;;
     doctor)   printf '%s' "--adapter --target --fix --json" ;;
     install|verify|cleanup) printf '%s' "--adapter --target --json" ;;
     *)        printf '%s' "" ;;
@@ -52,7 +52,7 @@ _mmh_flags_for() {
 
 # Dynamic candidates from the DISCOVER layer (silent empty on any failure).
 _mmh_actions() { local b; b="$(_mmh_bin)" || return 0; "$b" completion-candidates actions 2>/dev/null; }
-_mmh_flows()   { local b; b="$(_mmh_bin)" || return 0; "$b" completion-candidates flows 2>/dev/null; }
+_mmh_recipes() { local b; b="$(_mmh_bin)" || return 0; "$b" completion-candidates recipes 2>/dev/null; }
 
 # ── Bash ────────────────────────────────────────────────────────────────
 if [ -n "${BASH_VERSION:-}" ]; then
@@ -82,7 +82,7 @@ if [ -n "${BASH_VERSION:-}" ]; then
       completions) [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "install bash zsh status" -- "$cur")) ;;
       flows)       [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "list promote" -- "$cur")) ;;
       call)        [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "$(_mmh_actions)" -- "$cur")) ;;
-      run)         COMPREPLY=($(compgen -f -- "$cur"; compgen -W "$(_mmh_flows)" -- "$cur")) ;;
+      run)         COMPREPLY=($(compgen -f -- "$cur"; compgen -W "$(_mmh_recipes)" -- "$cur")) ;;
       *)           COMPREPLY=($(compgen -W "$(_mmh_flags_for "$cmd")" -- "$cur")) ;;
     esac
   }
@@ -117,7 +117,7 @@ if [ -n "${ZSH_VERSION:-}" ]; then
       completions) (( CURRENT == 3 )) && { candidates=(install bash zsh status); compadd -a candidates; } ;;
       flows)       (( CURRENT == 3 )) && { candidates=(list promote); compadd -a candidates; } ;;
       call)        (( CURRENT == 3 )) && { candidates=("${(@f)$(_mmh_actions)}"); compadd -a candidates; } ;;
-      run)         candidates=("${(@f)$(_mmh_flows)}"); compadd -a candidates; _files ;;
+      run)         candidates=("${(@f)$(_mmh_recipes)}"); compadd -a candidates; _files ;;
       *)           candidates=(${=$(_mmh_flags_for "$cmd")}); compadd -a candidates ;;
     esac
   }

package/docs/ADAPTER-SURFACE.md

@@ -1,26 +0,0 @@
-# Adapter surface
-
-`src/adapters/surface.ts` is the typed seam for Mobile, Extension, and Core.
-Commands ask it for platform behavior instead of re-deriving platform rules.
-
-Each adapter implements:
-
-- runtime readiness;
-- slot-owned ports;
-- dev-server lifecycle;
-- log sources;
-- launch/recovery hints;
-- headless capability.
-
-Implementations live in `src/adapters/{mobile,extension,core}/surface.ts`.
-Platform-specific shell and Node operations live under `adapters/<platform>/`.
-
-When adding behavior:
-
-1. Extend `AdapterSurface` only when every platform needs the concept.
-2. Implement all three adapters; Core should explicitly report headless/N/A.
-3. Call the surface from the command instead of adding adapter conditionals.
-4. Add a registry-completeness contract and a real affected-platform check.
-
-Mechanisms unique to one command may remain platform-specific. Shared readiness,
-ports, logs, lifecycle, and recovery language belong on the surface.

package/docs/CHEATSHEET.md

@@ -1,48 +0,0 @@
-# mm-harness cheatsheet
-
-Run inside a MetaMask checkout. Product, slot, ports, and runtime paths are
-auto-detected.
-
-## Operate
-
-| Need | Command |
-|---|---|
-| 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
-```
-
-The run result prints diagnostics plus absolute evidence paths. Resume safely with
-`mm-harness last --json`.
-
-## Recover
-
-```bash
-mm-harness doctor
-mm-harness doctor --fix
-mm-harness verify
-mm-harness cleanup
-mm-harness update
-```
-
-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`.