@deeeed/metamask-harness 0.5.0 → 0.6.0

package/dist/mm-harness-cli.js

@@ -423,6 +423,9 @@ function groupedHelp() {
     lines.push("");
     lines.push(`${out("warn", "DEV OVERRIDE ACTIVE")} \u2014 this run is served by MM_HARNESS_BIN=${out("path", process.env.MM_HARNESS_BIN)} (unset it to return to the installed/global bin).`);
   }
+  if (process.env.MM_HARNESS_BIN && process.env.MM_HARNESS_RUN_MODE) {
+    lines.push(`${out("label", "running from:")} ${out("path", process.env.MM_HARNESS_RUN_MODE)} (source checkout; dist shadows src when both exist)`);
+  }
   const slotLine = detectedSlotLine(out);
   if (slotLine) {
     lines.push("");
@@ -469,14 +472,8 @@ function translateActionsRaw(argv) {
 const program = new Command();
 program.name("mm-harness").description("the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay").helpOption("-h, --help", "Show grouped help").showHelpAfterError("(run `mm-harness --help` for the full surface)").configureHelp({ formatHelp: () => groupedHelp() });
 for (const command of REAL) {
-  program.command(command.name).description(command.summary).allowUnknownOption().helpOption(false).argument("[args...]").action(async () => {
-    const ddIdx = rawArgv.indexOf("--");
-    const flagsBeforeSep = ddIdx === -1 ? rawArgv : rawArgv.slice(0, ddIdx);
-    if (flagsBeforeSep.includes("--help") || flagsBeforeSep.includes("-h")) {
-      process.stdout.write(`${command.helpText}
-`);
-      process.exit(0);
-    }
+  program.command(command.name).description(command.summary).allowUnknownOption().helpOption("-h, --help", "Show command help").configureHelp({ formatHelp: () => `${command.helpText}
+` }).argument("[args...]").action(async () => {
     if (command.name === "update") {
       process.exit(await handleUpdate(rawArgv.slice(1)));
     }
@@ -514,8 +511,16 @@ const NUDGE_SKIP = ["update", "completions", "completion-candidates"];
 if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
   setImmediate(() => void maybeNudge());
 }
+function hasPassthroughHelp(argv) {
+  const divider = argv.indexOf("--");
+  if (divider === -1) return false;
+  return argv.slice(divider + 1).some((arg) => arg === "-h" || arg === "--help");
+}
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);
 }
+if (hasPassthroughHelp(rawArgv)) {
+  process.exit(await delegate(rawArgv));
+}
 await program.parseAsync(process.argv);

package/docs/CLI-SPEC.md

@@ -180,7 +180,7 @@ Audience: **human** (daily, ≤1 flag), **agent** (depth), **both**.
 
 ## `launch` (REAL as of wave 3 → main DAILY LOOP verb)
 
-> **Implemented (wave 3):** `handleLaunch` in `runner/src/commands/launch.ts`. The typed
+> **Implemented (wave 3):** `handleLaunch` in `src/commands/launch/`. The typed
 > layer owns grammar (mobile-target mandatory, core/extension refusals), tier
 > selection, quick-launch change detection, overlay auto-ensure, healing policy +
 > bounds, teaching errors, and the `--json` contract. It does NOT rewrite

package/docs/CODE-MAP.md

@@ -0,0 +1,62 @@
+# Code map — where things live and how a command flows
+
+One page for humans. The contracts live in docs/UX-PRINCIPLES.md and
+docs/ADAPTER-SURFACE.md; this is the geography.
+
+## How a command flows
+
+```
+bin/mm-harness                 bash front door: MM_HARNESS_BIN dev/prod switch,
+  │                            dist-vs-src selection (dist wins when present;
+  │                            stale-dist warning), deps ensure
+  ▼
+src/mm-harness-cli.ts          commander surface: grouped colored help, per-command
+  │                            --help, retired-name teaching; delegates in-process
+  ▼
+src/cli.ts                     parse + dispatch ONLY — no verb logic lives here
+  │
+  ├── src/commands/<verb>.ts   one module per verb (doctor, stop, call, run,
+  │     │                      provision, fixtures, flows, logs, debug, …)
+  │     ▼
+  │   src/adapters/surface.ts  AdapterSurface registry — per-platform behavior
+  │     │                      (ports, runtime status, dev server, log sources)
+  │     ▼
+  │   src/adapters/{mobile,extension,core}/   TS logic per platform
+  │
+  └── src/harness.ts           overlay lifecycle (install/verify/cleanup) — writes
+        │                      the per-checkout overlay + runner delegate
+        ▼
+      adapters/                SHELL LEAVES (repo root — not src/adapters!):
+        mobile/ extension/     single-OS-op scripts the TS layer spawns
+        core/ shared/          (simctl/adb/tmux/metro/webpack lifecycle)
+```
+
+## The two `adapters/` directories
+
+- `adapters/` (repo root) — executable shell leaves. Thin, OS-facing, spawned by TS.
+- `src/adapters/` — TypeScript platform logic behind the AdapterSurface.
+Rule: logic/decisions in TS; a leaf only executes. A leaf converts to TS only when
+it starts making decisions (see backlog ruling), never as a campaign.
+
+## Other roots
+
+- `library/` — recipe library: actions (`library/actions/<adapter>/…`, executable
+  action modules — importing one RUNS it, see library/README.md), flows, recipes.
+- `tests/contract/` — hermetic bash contract tests (PATH-stubbed OS tools). The
+  launch-leaf-flags test enforces composer↔leaf flag agreement.
+- `dist/` — esbuild output; the ONLY thing published runs. gitignored; in a source
+  checkout it SHADOWS src when present (bin warns when it goes stale).
+- Per-checkout runtime state lives in the TARGET repo: `temp/recipe/runtime/`
+  (context, logs, wallet fixture) and `temp/recipe/harness/<adapter>/` (overlay +
+  runner delegate pinned to the installing bin via `.runner-source`).
+
+## Adding things
+
+- **A verb**: module in `src/commands/`, register in `src/cli.ts` dispatch + the
+  commander metadata in `src/mm-harness-cli.ts` (help group), contract test.
+- **A flag**: parse in the verb module; if it reaches a leaf, the leaf's parser
+  must accept it (launch-leaf-flags test will fail otherwise) — or pass via env.
+- **A leaf**: shell under `adapters/<platform>/`, spawned via the shared spawn
+  helpers (never raw exec), contract test with PATH stubs, errors teach escape.
+- **A platform behavior**: extend the AdapterSurface, implement per platform —
+  verbs must not branch on adapter for surface-owned behavior.

package/library/README.md

@@ -0,0 +1,14 @@
+# Recipe library
+
+- `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.
+  That is the engine contract (the recipe engine spawns/imports them with the
+  input env set) — a bare `import` outside the engine throws
+  "Missing live adapter input path", which is expected, not a bug.
+- 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).

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

@@ -8,7 +8,7 @@ import { mnemonicToAccount, privateKeyToAccount } from 'viem/accounts';
 // this adapter under the bundled tsx (see commandFor/importsSourceTypescript in
 // src/live-adapter-contract.ts). The core adapter dynamic-imports the perps
 // controller TypeScript at runtime, so it MUST run under tsx, not plain node.
-import { walletFixturePath } from '../../../../src/index.ts';
+import { walletFixturePath } from '../../harness-exports.mjs';
 
 // Shared headless instantiation for the MetaMask `core` adapter.
 //

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

@@ -11,10 +11,10 @@ import {
   recipeHarnessPath,
   walletFixturePath,
   captureActiveRecipeRecordingSnapshot,
-} from '../../../../src/index.ts';
+} from '../../harness-exports.mjs';
 
 // Resolve the Farmslot harness through normal package dependencies by default.
-// Local Farmslot source is only a dev override handled by src/paths.ts.
+// Local Farmslot source is only a dev override handled by the harness paths module.
 const {
   CdpSession,
   CdpWebPage,

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

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { runAdapter, withExtensionPage } from '../platform/cdp.mjs';
-import { walletFixturePath } from '../../../../src/index.ts';
+import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixturePassword(projectRoot) {
   const candidates = [
@@ -19,6 +19,12 @@ async function fixturePassword(projectRoot) {
 }
 
 runAdapter((input) => withExtensionPage(input, async (page) => {
+  // A fresh profile shows onboarding, which has no password input — that is not
+  // an unlocked wallet, and passing here would be vacuous.
+  const onboarding = await page.evaluate(`(() => (window.location.hash || '').includes('onboarding'))()`);
+  if (onboarding) {
+    throw new Error('No wallet onboarded in this extension profile — unlock has nothing to unlock.\n  Next: mm-harness fixtures set   # applies the fixture wallet, then re-run: mm-harness call ensure_unlocked');
+  }
   const locked = await page.evaluate(`(() => Boolean(document.querySelector('input[type="password"]')))()`);
   if (!locked) {
     return { action: input.action, unlocked: true, alreadyUnlocked: true, proofPath: 'extension-unlocked-state' };

package/library/actions/harness-exports.mjs

@@ -0,0 +1,27 @@
+// Bridge from library actions to the harness path/recording helpers. Published
+// installs load the compiled dist (node cannot type-strip .ts under
+// node_modules); source checkouts without dist fall back to src. Deliberately
+// narrow — importing the package entry here would close an import cycle
+// through src/adapters.ts (which imports these actions) and deadlock.
+const packageRoot = new URL('../../', import.meta.url);
+
+async function load(distRelative, srcRelative) {
+  try {
+    return await import(new URL(distRelative, packageRoot).href);
+  } catch {
+    return await import(new URL(srcRelative, packageRoot).href);
+  }
+}
+
+const paths = await load('dist/paths.js', 'src/paths.ts');
+const recording = await load('dist/run-recording.js', 'src/run-recording.ts');
+
+export const {
+  importRecipeHarnessRuntimeBrowserExtension,
+  importRecipeHarnessRuntimeCdp,
+  extensionIdPath,
+  recipeHarnessPath,
+  walletFixturePath,
+} = paths;
+
+export const { captureActiveRecipeRecordingSnapshot } = recording;

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

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { bridgeCommand, runAdapter } from '../platform/bridge.mjs';
-import { walletFixturePath } from '../../../../src/index.ts';
+import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixturePassword(projectRoot) {
   const candidates = [
@@ -19,7 +19,14 @@ async function fixturePassword(projectRoot) {
 }
 
 function selectedAccount(status, input) {
-  return selectedStatus(status, input)?.account ?? null;
+  // The bridge reports an account OBJECT even pre-onboarding, with every field
+  // empty — an empty shell is not a wallet. Only a populated address/id counts,
+  // otherwise a fresh app "passes" unlock while sitting on the onboarding screen.
+  const account = selectedStatus(status, input)?.account ?? null;
+  if (!account || typeof account !== 'object') return null;
+  const address = typeof account.address === 'string' ? account.address : '';
+  const id = typeof account.id === 'string' ? account.id : '';
+  return address.length > 0 || id.length > 0 ? account : null;
 }
 
 function routeName(status, input) {
@@ -68,6 +75,11 @@ async function waitForUnlocked(input, timeoutMs = 15000) {
 
 runAdapter(async (input) => {
   const before = await status(input);
+  if (!selectedAccount(before, input) && routeName(before, input) !== 'Login') {
+    throw new Error(
+      `No wallet onboarded on this device (route ${routeName(before, input) || 'unknown'}, empty wallet status) — unlock has nothing to unlock.\n  Next: mm-harness fixtures set   # applies the fixture wallet, then re-run: mm-harness call ensure_unlocked`,
+    );
+  }
   if (selectedAccount(before, input) && routeName(before, input) !== 'Login') {
     return {
       action: input.action,

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

@@ -3,7 +3,7 @@ import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bridgeCommand, bridgeEnv, runAdapter } from '../platform/bridge.mjs';
-import { walletFixturePath } from '../../../../src/index.ts';
+import { walletFixturePath } from '../../harness-exports.mjs';
 
 async function fixtureProfile(projectRoot) {
   const candidates = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -19,7 +19,6 @@
     "@farmslot/protocol": "^0.7.2",
     "@farmslot/recipe-harness": "^0.3.3",
     "commander": "^12.0.0",
-    "tsx": "^4.23.0",
     "viem": "^2.54.3"
   },
   "resolutions": {
@@ -33,15 +32,16 @@
     "esbuild": "0.28.1",
     "eslint": "^9",
     "globals": "^17.7.0",
+    "tsx": "^4.23.0",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "publishConfig": {
@@ -50,7 +50,6 @@
   "files": [
     "bin",
     "dist",
-    "src",
     "adapters",
     "library",
     "scripts/completions.sh",

package/src/adapters/core/surface.ts

@@ -1,71 +0,0 @@
-// Core surface: headless. No app, no dev server — dependency presence is the
-// only runtime signal, and lifecycle commands teach the reachable headless path.
-import path from 'node:path';
-
-import { depsCheck } from '@farmslot/recipe-harness/runtime/deps-readiness';
-
-import type {
-  AdapterDevServerStop,
-  AdapterLogSource,
-  AdapterRuntimeStatus,
-  AdapterRunwayProvisionResult,
-  AdapterSurface,
-} from '../surface.ts';
-
-export const coreSurface: AdapterSurface = {
-  adapter: 'core',
-  headless: true,
-
-  resolveSlotPorts(): void {
-    // Headless: no ports or device to resolve.
-  },
-
-  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
-    const deps = depsCheck(path.resolve(target));
-    const ready = deps.status === 'current';
-    return {
-      decision: ready ? 'ready' : 'install',
-      reasonCode: ready ? 'deps-present' : `deps-${deps.status}`,
-      reasons: [
-        ready
-          ? 'Core is headless; dependencies are installed. Run recipes with mm-harness run.'
-          : 'Core is headless; dependencies are not fully installed.',
-      ],
-      deps: deps.status,
-    };
-  },
-
-  runwayProvision: {
-    async run(target, options): Promise<AdapterRunwayProvisionResult> {
-      return {
-        schemaVersion: 1,
-        command: 'provision',
-        adapter: 'core',
-        target: path.resolve(target),
-        status: 'fail',
-        exitCode: 2,
-        error: { code: 'UNSUPPORTED_ADAPTER', message: 'core is headless and has no mobile simulator to provision.', userAction: options.rerunCommand || 'mm-harness run <recipe> --adapter core' },
-      };
-    },
-  },
-
-  devServer: {
-    describe: () => 'no dev server (headless)',
-    stop(): AdapterDevServerStop {
-      return {
-        kind: 'headless',
-        message: 'core is headless — no dev server runs for a core checkout',
-        userAction: 'use mm-harness verify (readiness) or mm-harness run (execute a recipe)',
-      };
-    },
-  },
-
-  logSources(): AdapterLogSource[] {
-    return [];
-  },
-
-  hints: {
-    launch: 'mm-harness run <recipe>   # run recipes against the headless core',
-    relaunch: 'mm-harness verify',
-  },
-};

package/src/adapters/extension/ensure-ready.ts

@@ -1,185 +0,0 @@
-// ensure-ready.ts — ensure the extension runtime is attachable.
-//  runner/extension/extension-ensure-ready.ts) App/instance control.
-import path from 'node:path';
-
-import { resolveExtensionId } from './extension-id.ts';
-
-/**
- * "Drive the extension to a ready state" — the single source of truth for the
- * open-home + collapse-to-one-tab + verify-healthy logic that host launchers
- * and reopen helpers previously hand-rolled. They left duplicate home tabs, which trips
- * runtime-health's "exactly one home page" contract and makes agents see a
- * broken-looking runtime.
- *
- * Guarantees, given a live CDP port:
- *  - the extension id is resolved deterministically (resolveExtensionId),
- *  - exactly ONE chrome-extension home.html page target is open (opened if none,
- *    extras closed if several),
- *  - the runtime is verified healthy (checkExtensionRuntimeHealth).
- *
- * Pure-ish: it only opens/closes tabs to converge on the single-tab invariant;
- * it does not rebuild or relaunch. Unlocking the wallet remains with the host
- * launcher for now (a future increment can fold ensure_unlocked in here too).
- */
-
-export interface EnsureReadyResult {
-  schemaVersion: 1;
-  adapter: 'extension';
-  target: string;
-  cdpPort: number;
-  extensionId: string | null;
-  opened: boolean;
-  homeTabs: { before: number; closed: number; after: number };
-  ready: boolean;
-  reasonCode: string;
-  health: { status: 'PASS' | 'FAIL' | 'unknown'; findings: string[] };
-}
-
-interface CdpTarget {
-  id?: string;
-  type?: string;
-  url?: string;
-}
-
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
-
-async function jsonList(port: number): Promise<CdpTarget[]> {
-  try {
-    const res = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(5000) });
-    if (!res.ok) return [];
-    const value = await res.json();
-    return Array.isArray(value) ? (value as CdpTarget[]) : [];
-  } catch {
-    return [];
-  }
-}
-
-async function closeTab(port: number, id: string): Promise<void> {
-  try {
-    await fetch(`http://127.0.0.1:${port}/json/close/${id}`, { signal: AbortSignal.timeout(4000) });
-  } catch {
-    // best-effort; a tab that won't close is surfaced by the final health check
-  }
-}
-
-async function activateTab(port: number, id: string): Promise<void> {
-  try {
-    await fetch(`http://127.0.0.1:${port}/json/activate/${id}`, { signal: AbortSignal.timeout(4000) });
-  } catch {
-    // best-effort; foregrounding only steers the headed-window screen capture onto
-    // the wallet — the authoritative readiness signal is the health check below
-  }
-}
-
-// Blank / New-Tab pages Chrome opens by default. The headed-window screen capture
-// (device-grid stream) follows whatever tab is foreground, so a lingering New Tab
-// makes the stream show chrome://newtab instead of the wallet. Safe to close once
-// a home tab exists.
-function isStrayTab(url?: string): boolean {
-  if (typeof url !== 'string') return false;
-  return /^chrome:\/\/newtab\/?$/.test(url) || /^chrome:\/\/new-tab-page\b/.test(url) || url === 'about:blank';
-}
-
-async function openHome(port: number, extensionId: string): Promise<boolean> {
-  const endpoint = `http://127.0.0.1:${port}/json/new?${encodeURIComponent(`chrome-extension://${extensionId}/home.html`)}`;
-  try {
-    let res = await fetch(endpoint, { method: 'PUT', signal: AbortSignal.timeout(8000) });
-    if (res.status === 404 || res.status === 405) res = await fetch(endpoint, { signal: AbortSignal.timeout(8000) });
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
-function homePages(targets: CdpTarget[], extensionId: string): CdpTarget[] {
-  const prefix = `chrome-extension://${extensionId}`;
-  return targets.filter(
-    (t) => t.type === 'page' && typeof t.url === 'string' && t.url.startsWith(prefix) && t.url.includes('/home.html') && t.id,
-  );
-}
-
-export async function ensureExtensionReady(
-  target: string,
-  options: { cdpPort: number },
-): Promise<EnsureReadyResult> {
-  const resolved = path.resolve(target);
-  const { cdpPort } = options;
-  const base = (extra: Partial<EnsureReadyResult>): EnsureReadyResult => ({
-    schemaVersion: 1,
-    adapter: 'extension',
-    target: resolved,
-    cdpPort,
-    extensionId: null,
-    opened: false,
-    homeTabs: { before: 0, closed: 0, after: 0 },
-    ready: false,
-    reasonCode: 'unknown',
-    health: { status: 'unknown', findings: [] },
-    ...extra,
-  });
-
-  const { extensionId } = await resolveExtensionId(resolved, { cdpPort });
-  if (!extensionId) return base({ reasonCode: 'no-extension-id' });
-
-  const homes = homePages(await jsonList(cdpPort), extensionId);
-  const before = homes.length;
-
-  // Converge on exactly one home tab.
-  //  - 0 tabs  → open one.
-  //  - 1 tab   → keep it (cheap; the health check below validates it).
-  //  - >1 tabs → close ALL and open one fresh. /json/list alone can't tell a
-  //    healthy tab from a chrome-error one (a crashed page still lists its
-  //    intended url), so keeping the first could discard the good tab and keep a
-  //    broken one. A fresh tab is deterministically clean.
-  let opened = false;
-  let closed = 0;
-  if (homes.length > 1) {
-    for (const h of homes) {
-      await closeTab(cdpPort, String(h.id));
-      closed += 1;
-    }
-    await sleep(500);
-    opened = await openHome(cdpPort, extensionId);
-    await sleep(1500);
-  } else if (homes.length === 0) {
-    opened = await openHome(cdpPort, extensionId);
-    await sleep(1500);
-  }
-
-  // Drop stray New Tab / blank pages and foreground the wallet so the headed
-  // window captured by the device-grid stream shows MetaMask, not chrome://newtab.
-  // Only prune once a home tab exists, so the window is never left with zero tabs
-  // (which would close it).
-  const converged = await jsonList(cdpPort);
-  const homesNow = homePages(converged, extensionId);
-  if (homesNow.length >= 1) {
-    for (const t of converged) {
-      if (t.type === 'page' && t.id && isStrayTab(t.url)) await closeTab(cdpPort, String(t.id));
-    }
-    if (homesNow[0]?.id) await activateTab(cdpPort, String(homesNow[0].id));
-  }
-
-  const after = homePages(await jsonList(cdpPort), extensionId).length;
-
-  // Verify with the single health source. Lazy import: extension-runtime.ts
-  // loads the recipe harness at module scope, so it must not be pulled into
-  // any no-CDP path.
-  let health: EnsureReadyResult['health'] = { status: 'unknown', findings: [] };
-  try {
-    const { checkExtensionRuntimeHealth } = await import('./runtime.ts');
-    const report = await checkExtensionRuntimeHealth(resolved, cdpPort);
-    health = { status: report.status, findings: report.findings };
-  } catch (error) {
-    health = { status: 'FAIL', findings: [error instanceof Error ? error.message : String(error)] };
-  }
-
-  const ready = health.status === 'PASS' && after === 1;
-  return base({
-    extensionId,
-    opened,
-    homeTabs: { before, closed, after },
-    ready,
-    reasonCode: ready ? 'ready' : after !== 1 ? 'tab-count' : 'unhealthy',
-    health,
-  });
-}

package/src/adapters/extension/extension-id.ts

@@ -1,107 +0,0 @@
-// extension-id.ts — deterministic extension (CRX) id resolution.
-// App control: derives the id from the loaded dist manifest key. Name keeps
-// the extension- prefix: this is the CRX id, not an instance/slot id.
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-
-/**
- * Single source of truth for "which extension id is this MetaMask build".
- *
- * WHY THIS EXISTS. The id was resolved in three different, drifting places —
- * host `launch-browser.sh` (Playwright candidate loop), `reopen-browser.sh`
- * (`serviceWorkers()[0]`, which grabs Chrome's *component* extensions and broke
- * recovery), and the harness CDP target selector. They disagreed. This module
- * makes the runner the one resolver host launchers defer to.
- *
- * The id is **deterministic**: Chrome derives an unpacked extension's id from
- * the `key` in its manifest (base64-decode → sha256 → first 16 bytes → each
- * nibble mapped to a-p). Since the browser is launched with `--load-extension`
- * pointing at exactly this dist, the computed id IS the loaded extension's id —
- * no service-worker/page guessing, robust even when the MV3 worker is idle.
- *
- * `--cdp-port` (optional) only *verifies* the computed id is actually present in
- * the running browser; it never changes the answer.
- */
-
-export interface ResolveExtensionResult {
-  adapter: 'extension';
-  target: string;
-  extensionId: string | null;
-  source: 'manifest-key' | 'cdp-target' | 'none';
-  verified: boolean | null;
-}
-
-const DIST_MANIFEST = 'dist/chrome/manifest.json';
-
-/** Chrome's unpacked-extension id derivation from a manifest `key` (base64 DER). */
-export function extensionIdFromKey(keyBase64: string): string {
-  const der = Buffer.from(keyBase64, 'base64');
-  const hash = crypto.createHash('sha256').update(der).digest();
-  let id = '';
-  for (let i = 0; i < 16; i += 1) {
-    id += String.fromCharCode(97 + (hash[i] >> 4));
-    id += String.fromCharCode(97 + (hash[i] & 0xf));
-  }
-  return id;
-}
-
-function idFromDistManifest(target: string): string | null {
-  const manifestPath = path.join(target, DIST_MANIFEST);
-  if (!fs.existsSync(manifestPath)) return null;
-  try {
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as { key?: unknown };
-    return typeof manifest.key === 'string' && manifest.key.length > 0
-      ? extensionIdFromKey(manifest.key)
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-/** chrome-extension ids visible to CDP (page targets + service workers). */
-async function cdpExtensionIds(cdpPort: number): Promise<string[]> {
-  try {
-    const res = await fetch(`http://127.0.0.1:${cdpPort}/json/list`, { signal: AbortSignal.timeout(4000) });
-    if (!res.ok) return [];
-    const targets = (await res.json()) as Array<{ url?: string }>;
-    const ids = new Set<string>();
-    for (const t of targets) {
-      const m = /^chrome-extension:\/\/([^/]+)/u.exec(String(t.url ?? ''));
-      if (m) ids.add(m[1]);
-    }
-    return [...ids];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Resolve the MetaMask extension id for a checkout. Pure file/crypto by default;
- * `--cdp-port` adds a presence check (and a fallback when the dist has no `key`).
- */
-export async function resolveExtensionId(
-  target: string,
-  options: { cdpPort?: number } = {},
-): Promise<ResolveExtensionResult> {
-  const resolved = path.resolve(target);
-  const fromKey = idFromDistManifest(resolved);
-  let cdpIds: string[] | null = null;
-  if (options.cdpPort) cdpIds = await cdpExtensionIds(options.cdpPort);
-
-  if (fromKey) {
-    return {
-      adapter: 'extension',
-      target: resolved,
-      extensionId: fromKey,
-      source: 'manifest-key',
-      verified: cdpIds ? cdpIds.includes(fromKey) : null,
-    };
-  }
-  // No `key` in the dist manifest (rare). Fall back to a live CDP id if exactly
-  // one extension is loaded; otherwise we cannot disambiguate deterministically.
-  if (cdpIds && cdpIds.length === 1) {
-    return { adapter: 'extension', target: resolved, extensionId: cdpIds[0], source: 'cdp-target', verified: true };
-  }
-  return { adapter: 'extension', target: resolved, extensionId: null, source: 'none', verified: cdpIds ? false : null };
-}