@deeeed/metamask-harness 0.70.1 → 0.71.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.71.0 - 2026-10-02
+
+### Added
+
+- `terminal` adapter for the MetaMask Web Terminal (Next.js site): `mm-harness launch|doctor|verify|install|cleanup|stop|run --adapter terminal` drive a per-slot Chrome for Testing on `--cdp-port` against the slot dev server on `--watcher-port`. `signer=extension` loads a MetaMask build with the fixture account imported; `signer=injected` is a strict EIP-1193 test wallet that rejects typed data for another chain. A wallet host logs every wallet request (method, EIP-712 primary type, chain, outcome; never params or signatures) and every MetaMask confirmation shown.
+- Terminal actions: `metamask.app.launch`, venue-backed `metamask.perps.read_positions|read_orders|read_snapshot|assert_positions|assert_orders`, testnet `metamask.perps.teardown_state` and `metamask.perps.revoke_agent` (signed in Node by the fixture account; mainnet only with `mainnet_confirmation=REAL_FUNDS`), `metamask.wallet.read_signatures|assert_signatures|list_accounts`, and `ui.*` with `surface: app|wallet` to drive the MetaMask side panel / notification.
+- Terminal browser is visible by default, one window per slot side by side on the main screen (odd CDP port left, even right; `TERMINAL_WINDOW` / `TERMINAL_SCREEN` override) with a profile zoom that keeps the desktop layout. `--headless`, launch node `headless: true` or `TERMINAL_HEADLESS=1` hide it; `--headful` stays accepted. `--slow-mo <ms>` / `slow_mo_ms` / `TERMINAL_SLOW_MO` pause before each UI action. Terminal `app.hud` draws the recipe, step N/M, current intent and last result on the app tab (closed shadow root outside `<body>`, pointer-events none, redrawn after navigation, never on MetaMask pages); `--hud auto` shows it only in a visible browser.
+- Terminal testnet enforcement: every mainnet host the venue SDK names, and the API and base URLs of `@metamask/perps-controller` and the app source, are unresolvable for the whole browser and blocked by the wallet host (`blocked-mainnet`); mainnet Hyperliquid typed data is refused before any signer sees it (`refused-mainnet`). The venues' web hosts (`app.hyperliquid.xyz`, `app.hyperliquid-testnet.xyz`) are neither blocked nor proof of the served network, and a launch fails if any scanned source uses one with an API path. Source URLs are compared in canonical form (parsed: lowercase host without a trailing dot, default port dropped, dot segments resolved), and the host resolver rules cover each host's trailing-dot form. The launch proves both blocks with probes and that the app talks to a testnet API host, and fails if the SDK names a mainnet host missing from the block list. Mainnet needs `network: mainnet` with `mainnet_confirmation: REAL_FUNDS`. A browser is reused only while it enforces the same host list.
+- Terminal slot safety: slot processes carry `--mm-harness-owner` markers and only proven-owned ones are signalled; wallet calls are judged against their own document's commit, and anything that can't be (including calls pending when a tab detaches) is logged as `unattributed`; a failed launch stops what it started and removes temporary key material; a first page that never commits is reported with what the tab and the dev server did. Only `TERMINAL_CHROME_BIN` overrides the browser.
+- Terminal focus: a visible browser starts in the background through LaunchServices with no startup window; one check after the launch (shared `macos-focus.cjs`, `restoreFrontmostIfOurs`) gives the front back once, by pid, only if this slot's browser took it, and the wallet host only observes. Pages come to front only with `MM_HARNESS_FOCUS_BROWSER=1`.
+- Terminal run diagnostics: recipe runs start the shared console collector for the slot (`terminal/app-console.log` for the app page, `terminal/extension-console.log` for MetaMask; `mm-harness logs` lists both and the wallet request log), and the run's non-probe `blocked-mainnet`, `refused-mainnet` and `unattributed` wallet entries are findings. `metamask.app.assert_no_console_errors` fails a recipe on unexplained page, browser or extension errors.
+- Console allowlists (`diagnostics/console-allowlist.json`, `schemaVersion: 3`, earlier versions refused): exact signatures of an event's first line, continuation and optional location, compared by string equality through one matcher, `library/actions/shared/console-findings.mjs`, which recipe-library guards also call. Normalisation only touches parsed fields: URLs (Next.js scope only on a plain path: every segment made of letters, digits, `.`, `_`, `@`, `-` and `%40`, never `.` or `..`) in a loopback port, a `/_next/static/` asset name (its directory and extension kept), `dpl`/`v` on `/_next/` paths and an unpacked extension id; frames and locations lose their position; other text only in times, UUIDs and hex of 9+ digits. `library/actions/shared/console-allowlist-add.mjs <run artifacts dir>` writes entries from a real run.
+
+### Changed
+
+- Console collector capture files are framed: every line after an event's first starts with `│ `, and a browser Log entry's `[browser:<source>]` tag sits in the record header before the level word, where message text can't put it; its location is its URL alone, without a line number. **Logs from older collectors:** each unprefixed line is a finding of its own (at least an error) and their browser entries read as page events, so they report REVIEW.
+- Run diagnostics and `assert_no_console_errors` require capture evidence: this runtime's own collector (a process running this checkout's `console-tail.mjs` as its script, with its exact argument list, so install and runtime paths may contain spaces; owner marker; a marker-less collector for the same log is replaced once, and this runtime's collector started by another harness install is retired before its replacement starts; capture files rotate past 32 MB) and a control line logged in the captured target that reaches the capture file (for the Extension, from MetaMask's own extension id). **Extension consumers:** a run whose capture can't be proven at the end reports UNAVAILABLE instead of CLEAN, so the browser must still be open then; a capture over the 512 KB read limit with no findings is UNAVAILABLE too. Capture control lines are never findings.
+
 ## 0.70.1 - 2026-10-02
 
 ### Fixed

package/adapters/extension/console-tail.mjs

@@ -39,11 +39,13 @@ function parseArgs(argv) {
       case '-h':
       case '--help':
         process.stdout.write(
-          'Usage: console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>]\n',
+          'Usage: console-tail.mjs --cdp-port <port> [--extension-log <file>] [--dapp-log <file>] [--mm-harness-owner=<marker>]\n',
         );
         process.exit(0);
         break;
       default:
+        // An ownership marker the caller identifies its collector by.
+        if (arg.startsWith('--mm-harness-owner=')) break;
         throw new Error(`Unknown argument: ${arg}`);
     }
   }
@@ -73,7 +75,13 @@ const cooldown = new Map();
 // Writes formatted console-event strings (never raw HTTP response bodies) to
 // stdout and optionally to a caller-supplied log file. The source is the local
 // Chrome CDP WebSocket (127.0.0.1:<cdpPort>) — a trusted-local endpoint.
-function out(line, destination = null) {
+// Every line after an event's first is written with this prefix, so text
+// inside a message can never read as the start of another event.
+const CONTINUATION_PREFIX = '│ ';
+
+function out(event, destination = null) {
+  const [first, ...rest] = String(event).split('\n');
+  const line = [first, ...rest.map((continued) => `${CONTINUATION_PREFIX}${continued}`)].join('\n');
   process.stdout.write(`${line}\n`);
   if (destination) {
     // This file is explicitly an untrusted application-console transcript; it is never executed or parsed as configuration.
@@ -136,10 +144,23 @@ function previewArg(arg) {
   return arg.subtype || arg.type || '?';
 }
 
+// Where an event came from, appended as "  (at <frame>)": the first stack
+// frame of a console call or exception, the URL of a browser log entry. Run
+// diagnostics group findings by message and report this frame.
+function frameText(callFrame) {
+  if (!callFrame?.url) return '';
+  return `${callFrame.functionName || '<anonymous>'} ${callFrame.url}:${(callFrame.lineNumber ?? 0) + 1}:${(callFrame.columnNumber ?? 0) + 1}`;
+}
+
+function atSuffix(frame) {
+  return frame ? `  (at ${frame})` : '';
+}
+
 function emitConsole(label, params, destination) {
   const level = String(params.type || 'log').toUpperCase();
   const text = (params.args || []).map(previewArg).join(' ');
-  out(`${stamp()} [${label}] ${level}  ${text}`, destination);
+  const [first, ...rest] = text.split('\n');
+  out(`${stamp()} [${label}] ${level}  ${first}${atSuffix(frameText(params.stackTrace?.callFrames?.[0]))}${rest.length ? `\n${rest.join('\n')}` : ''}`, destination);
 }
 
 function emitException(label, params, destination) {
@@ -149,13 +170,23 @@ function emitException(label, params, destination) {
     d.exception?.value ||
     d.text ||
     'uncaught exception';
-  out(`${stamp()} [${label}] EXCEPTION  ${text}`, destination);
+  const frame = frameText(d.stackTrace?.callFrames?.[0]) || frameText({ url: d.url, lineNumber: d.lineNumber, columnNumber: d.columnNumber });
+  const [first, ...rest] = String(text).split('\n');
+  out(`${stamp()} [${label}] EXCEPTION  ${first}${atSuffix(frame)}${rest.length ? `\n${rest.join('\n')}` : ''}`, destination);
 }
 
+// Browser log entries (network failures, interventions, deprecations) are
+// tagged with their Log source in the record header, before the level word,
+// e.g. "[dapp:page:BTC] [browser:network] ERROR  …": message text (written
+// after the level word) can never produce the tag.
 function emitLogEntry(label, params, destination) {
   const e = params.entry || {};
   const level = String(e.level || 'log').toUpperCase();
-  out(`${stamp()} [${label}] ${level}  ${e.text || ''}`, destination);
+  const source = String(e.source || 'other').replace(/[^a-z-]/gu, '') || 'other';
+  // A Log entry's location is its URL as is: a line number appended to a URL
+  // could not be told apart from the URL's own text.
+  const where = e.url ? e.url : frameText(e.stackTrace?.callFrames?.[0]);
+  out(`${stamp()} [${label}] [browser:${source}] ${level}  ${e.text || ''}${atSuffix(where)}`, destination);
 }
 
 function handleMessage(label, destination, data) {
@@ -185,7 +216,8 @@ function handleMessage(label, destination, data) {
 function attach(target) {
   const stream = targetStream(target);
   if (!stream) return;
-  const label = `${stream.kind}:${shortLabel(target)}`;
+  // No brackets or spaces: the label is a header field.
+  const label = `${stream.kind}:${shortLabel(target)}`.replace(/[[\]\s]/gu, '_');
   const ws = new WebSocket(target.webSocketDebuggerUrl);
   const entry = { ws, label, destination: stream.log, opened: false };
   attached.set(target.id, entry);

package/adapters/manifest.json

@@ -638,6 +638,134 @@
       "purpose": "Bootstrap numbered MetaMask checkouts through the setup-base command.",
       "inputs": "setup-base command arguments",
       "outputs": "numbered checkouts, saved preferences, and run summary"
+    },
+    {
+      "id": "terminal/launch",
+      "entry": "adapters/terminal/launch.mjs",
+      "kind": "node",
+      "purpose": "Start or reuse the Web Terminal slot browser (Chrome for Testing unless TERMINAL_CHROME_BIN; MetaMask extension with the fixture imported, or the injected strict wallet) and its wallet host. On macOS the browser starts through LaunchServices with no startup window; in testnet mode the venue SDK's mainnet hosts are unresolvable for the whole browser.",
+      "inputs": "--target --cdp-port --app-port [--signer extension|injected] [--account] [--fresh-profile] [--headless|--headful] [--slow-mo] [--network mainnet --mainnet-confirmation REAL_FUNDS] [--json]; env TERMINAL_CHROME_BIN, TERMINAL_EXTENSION_DIR, TERMINAL_EXTENSION_CHECKOUT, RECIPE_WALLET_FIXTURE, TERMINAL_HEADLESS, TERMINAL_SLOW_MO, TERMINAL_WINDOW, TERMINAL_SCREEN",
+      "outputs": "<runtime>/terminal/browser.json + pid/log files; JSON on stdout; exit 0/1/2"
+    },
+    {
+      "id": "terminal/wallet-host",
+      "entry": "adapters/terminal/wallet-host.mjs",
+      "kind": "node",
+      "purpose": "Long-running CDP observer: opens the app tab blank, hooks it once per target, navigates it to the app and verifies the log binding before ready; logs every wallet request from the app top frame and every MetaMask confirmation shown; answers the injected strict wallet in injected mode (other frames and blank popups get 4100).",
+      "inputs": "--cdp-port --runtime-dir --signer --app-origin [--extension-id] [--target --account --start-chain] [--browser-app <.app>]",
+      "outputs": "<runtime>/terminal/wallet-requests.jsonl, wallet-host.ready"
+    },
+    {
+      "id": "terminal/stop",
+      "entry": "adapters/terminal/stop.mjs",
+      "kind": "node",
+      "purpose": "Stop the terminal slot browser, wallet host and console collector and prove the CDP port is free.",
+      "inputs": "--target [--cdp-port]",
+      "outputs": "JSON on stdout; exit 0/1"
+    },
+    {
+      "id": "terminal/inject",
+      "entry": "adapters/terminal/inject.mjs",
+      "kind": "node",
+      "purpose": "Terminal install: overlay marker, runtime dir and wallet fixture (0600); no product writes.",
+      "inputs": "--target [--fixture] [--force]; env RECIPE_WALLET_FIXTURE",
+      "outputs": "<harness>/terminal/install.json, <runtime>/wallet-fixture.json; exit 0/1"
+    },
+    {
+      "id": "terminal/cleanup",
+      "entry": "adapters/terminal/cleanup.mjs",
+      "kind": "node",
+      "purpose": "Terminal cleanup: stop browser/host, remove terminal runtime state, overlay marker and installed fixture; profiles kept unless --reset-profile.",
+      "inputs": "--target [--cdp-port] [--reset-profile]",
+      "outputs": "JSON on stdout; exit 0/1"
+    },
+    {
+      "id": "terminal/verify",
+      "entry": "adapters/terminal/verify.mjs",
+      "kind": "node",
+      "purpose": "Read-only terminal slot readiness: checkout, deps, dev server, forced testnet, fixture, browser start probe, extension copy, CDP port.",
+      "inputs": "--target [--cdp-port] [--watcher-port] [--signer] [--account] [--json]",
+      "outputs": "readiness report; exit 0 ready / 1 not ready"
+    },
+    {
+      "id": "terminal/lib-cdp-client",
+      "entry": "adapters/terminal/lib/cdp-client.mjs",
+      "kind": "lib",
+      "purpose": "Browser-level CDP client with flattened target sessions for the wallet host.",
+      "inputs": "CdpClient.connect(url)",
+      "outputs": "send/on"
+    },
+    {
+      "id": "terminal/lib-page-script",
+      "entry": "adapters/terminal/lib/page-script.mjs",
+      "kind": "lib",
+      "purpose": "Page script source: wallet request logging and the injected strict provider (EIP-6963 io.metamask).",
+      "inputs": "pageScriptSource({ signer, appOrigin })",
+      "outputs": "script source string"
+    },
+    {
+      "id": "terminal/lib-strict-wallet",
+      "entry": "adapters/terminal/lib/strict-wallet.mjs",
+      "kind": "lib",
+      "purpose": "EIP-1193 strict test wallet enforcing typed-data chainId == active chain.",
+      "inputs": "createStrictWallet({ account, chainId })",
+      "outputs": "request()"
+    },
+    {
+      "id": "terminal/lib-processes",
+      "entry": "adapters/terminal/lib/processes.mjs",
+      "kind": "lib",
+      "purpose": "Pid-file process stop with owner-marker checks (--mm-harness-owner=<kind>-<id>, exact token; live foreign pids kept and reported, dead ones dropped), process-group termination, CDP port release check.",
+      "inputs": "stopTerminalBrowser(target, { cdpPort }), stopConsoleCollector(target), ownerMarker(kind, runtimeDir), ownsProcess(kind, pid, runtimeDir)",
+      "outputs": "stopped processes"
+    },
+    {
+      "id": "terminal/lib-readiness",
+      "entry": "adapters/terminal/lib/readiness.mjs",
+      "kind": "lib",
+      "purpose": "Terminal slot readiness checks shared by verify, doctor and the surface.",
+      "inputs": "terminalReadiness({ target, appPort, cdpPort, signer }), assertLaunchNetwork(target, { network, mainnetConfirmation }), devServerTestnetDiagnostic(target, { appPort }) (advisory)",
+      "outputs": "checks[]"
+    },
+    {
+      "id": "terminal/lib-display",
+      "entry": "adapters/terminal/lib/display.mjs",
+      "kind": "lib",
+      "purpose": "Headless/headful and slow-mo resolution, per-slot window placement and the profile zoom that keeps the desktop layout.",
+      "inputs": "resolveHeadless, resolveSlowMo, windowPlacement, writeProfileZoom",
+      "outputs": "browser display args"
+    },
+    {
+      "id": "terminal/lib-hud",
+      "entry": "adapters/terminal/lib/hud.mjs",
+      "kind": "lib",
+      "purpose": "Recipe HUD state (<runtime>/hud.json) and the page expression that draws it on the app origin only.",
+      "inputs": "nextHudState, hudRenderExpression",
+      "outputs": "HUD state, expression source"
+    },
+    {
+      "id": "terminal/lib-origin",
+      "entry": "adapters/terminal/lib/origin.mjs",
+      "kind": "lib",
+      "purpose": "Exact app-origin and app top-frame checks for targets, wallet requests and log entries.",
+      "inputs": "isAppUrl(url, appOrigin), isAppTopFrameContext(context, { targetId, appOrigin })",
+      "outputs": "boolean"
+    },
+    {
+      "id": "terminal/lib-mainnet-guard",
+      "entry": "adapters/terminal/lib/mainnet-guard.mjs",
+      "kind": "lib",
+      "purpose": "Testnet enforcement: the venue endpoint hosts (from the venue SDK, @metamask/perps-controller and the app source in the checkout), the browser's host-resolver block, and the mainnet typed-data classifier used by the page script and the wallet host.",
+      "inputs": "venueHosts(checkout), hostResolverRules(hosts), isMainnetVenueUrl(url, hosts), mainnetTypedDataReason(data)",
+      "outputs": "host list, launch switch, refusal reason"
+    },
+    {
+      "id": "terminal/surface",
+      "entry": "src/adapters/terminal/surface.ts",
+      "kind": "module",
+      "purpose": "Terminal adapter surface (runtime status, browser stop, logs, hints).",
+      "inputs": "terminalSurface",
+      "outputs": "AdapterSurface"
     }
   ]
 }

package/adapters/terminal/cleanup.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// cleanup.mjs — `mm-harness cleanup --adapter terminal`: stop the slot browser
+// and wallet host, then remove the terminal runtime state and the installed
+// wallet fixture. Browser profiles are kept unless --reset-profile.
+//
+// Inputs: --target <checkout> [--cdp-port <port>] [--reset-profile]
+// Outputs: JSON summary on stdout. Exit 0 cleaned; 1 the CDP port stayed busy.
+// Never touches: product source files, the Next.js dev server.
+
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { recipeHarnessPath, walletFixturePath } from '../../library/actions/harness-exports.mjs';
+import { terminalRuntimeDir } from '../../library/actions/terminal/platform/runtime.mjs';
+import { stopConsoleCollector, stopTerminalBrowser } from './lib/processes.mjs';
+
+const usage = 'Usage: cleanup.mjs --target <checkout> [--cdp-port <port>] [--reset-profile]';
+
+export async function cleanupTerminalRuntime({ target, cdpPort, resetProfile = false }) {
+  const root = path.resolve(target);
+  const stop = await stopTerminalBrowser(root, { cdpPort });
+  await stopConsoleCollector(root);
+  const runtime = terminalRuntimeDir(root);
+  const removed = [];
+  if (existsSync(runtime)) {
+    for (const entry of readdirSync(runtime)) {
+      if (entry.startsWith('profile-') && !resetProfile) continue;
+      rmSync(path.join(runtime, entry), { recursive: true, force: true });
+      removed.push(entry);
+    }
+  }
+  const overlay = recipeHarnessPath(root, 'terminal');
+  if (existsSync(overlay)) {
+    rmSync(overlay, { recursive: true, force: true });
+    removed.push(path.relative(root, overlay));
+  }
+  const fixture = walletFixturePath(root);
+  if (existsSync(fixture)) {
+    rmSync(fixture, { force: true });
+    removed.push(path.relative(root, fixture));
+  }
+  return { status: 'pass', target: root, stopped: stop.stopped, cdpPortFree: stop.cdpPortFree, removed };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(`${usage}\n`);
+    process.exit(0);
+  }
+  const value = (flag) => {
+    const index = argv.indexOf(flag);
+    return index >= 0 ? argv[index + 1] : undefined;
+  };
+  const rawPort = value('--cdp-port') ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
+  try {
+    const result = await cleanupTerminalRuntime({
+      target: value('--target') ?? process.cwd(),
+      cdpPort: rawPort ? Number(rawPort) : undefined,
+      resetProfile: argv.includes('--reset-profile'),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ status: 'fail', error: error.message })}\n`);
+    process.exit(1);
+  }
+}

package/adapters/terminal/inject.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// inject.mjs — `mm-harness install --adapter terminal`: prepare the slot runtime
+// directory and install the wallet fixture the terminal actions read.
+//
+// Inputs: --target <terminal checkout> [--fixture <wallet-fixture.json>] [--force]
+//   env RECIPE_WALLET_FIXTURE (fixture source when --fixture is absent)
+// Outputs: <target>/<harness root>/terminal/install.json (overlay marker),
+//   <target>/<runtime>/terminal/ (0700), <runtime>/wallet-fixture.json (0600);
+//   JSON summary on stdout (account names only). Exit 0 installed; 1 failure; 2 usage.
+// Never touches: product source files; never prints key material.
+
+import { copyFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { recipeHarnessPath, recipeRuntimeDir, walletFixturePath } from '../../library/actions/harness-exports.mjs';
+import { terminalRuntimeDir } from '../../library/actions/terminal/platform/runtime.mjs';
+import { isTerminalCheckout } from './lib/readiness.mjs';
+
+const usage = 'Usage: inject.mjs --target <terminal checkout> [--fixture <wallet-fixture.json>] [--force]';
+
+export function installTerminalRuntime({ target, fixture, force = false }) {
+  const root = path.resolve(target);
+  if (!isTerminalCheckout(root)) throw new Error(`${root} is not a Web Terminal checkout (needs next + src/features/perpetuals).`);
+  mkdirSync(path.join(root, recipeRuntimeDir()), { recursive: true, mode: 0o700 });
+  mkdirSync(terminalRuntimeDir(root), { recursive: true, mode: 0o700 });
+  const destination = walletFixturePath(root);
+  let fixtureAction = 'kept';
+  if (fixture && (force || !existsSync(destination))) {
+    const parsed = JSON.parse(readFileSync(fixture, 'utf8'));
+    if (!Array.isArray(parsed.accounts) || parsed.accounts.length === 0) throw new Error(`${fixture} has no accounts.`);
+    copyFileSync(fixture, destination);
+    chmodSync(destination, 0o600);
+    fixtureAction = 'installed';
+  } else if (!existsSync(destination)) {
+    fixtureAction = 'missing';
+  }
+  const accounts = existsSync(destination)
+    ? JSON.parse(readFileSync(destination, 'utf8')).accounts.map((account) => account?.name).filter(Boolean)
+    : [];
+  const marker = { schemaVersion: 1, adapter: 'terminal', installedAt: new Date().toISOString(), fixture: fixtureAction };
+  // The overlay directory is the install marker run/call auto-ensure checks.
+  const overlay = recipeHarnessPath(root, 'terminal');
+  mkdirSync(overlay, { recursive: true, mode: 0o700 });
+  writeFileSync(path.join(overlay, 'install.json'), `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
+  return { status: fixtureAction === 'missing' ? 'fail' : 'pass', target: root, fixture: fixtureAction, fixturePath: destination, accounts };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(`${usage}\n`);
+    process.exit(0);
+  }
+  const value = (flag) => {
+    const index = argv.indexOf(flag);
+    return index >= 0 ? argv[index + 1] : undefined;
+  };
+  try {
+    const result = installTerminalRuntime({
+      target: value('--target') ?? process.cwd(),
+      fixture: value('--fixture') ?? process.env.RECIPE_WALLET_FIXTURE,
+      force: argv.includes('--force'),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status !== 'pass') {
+      process.stderr.write('No wallet fixture installed. Next: set RECIPE_WALLET_FIXTURE or pass --fixture <wallet-fixture.json>.\n');
+      process.exit(1);
+    }
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+}