@deeeed/metamask-harness 0.80.0 → 0.82.0

package/adapters/web-dapp/lib/policy.mjs

@@ -0,0 +1,79 @@
+// The venue policy of the adapter that extends web-dapp (e.g. the Terminal
+// plugin's plugins/terminal/policy.mjs): what web-dapp's launch, wallet host,
+// readiness and actions know about the app's venue. mm-harness sets its module
+// path in RECIPE_WEB_DAPP_POLICY when it binds such an adapter, so every
+// web-dapp leaf process and live action it starts reads the same policy.
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export const POLICY_ENV = 'RECIPE_WEB_DAPP_POLICY';
+// The policy contract this web-dapp reads; a policy declares the version it was written for.
+export const POLICY_VERSION = 1;
+let loaded;
+
+// Every member web-dapp reads, checked once when the policy loads: a missing or mistyped
+// member fails here, naming the module, instead of deep in a launch or an assertion (a
+// missing signatureLog would silently drop the venue's L1 and mainnet rules).
+const MEMBERS = {
+  adapterId: 'string',
+  checkout: 'object',
+  venueHosts: 'function',
+  linkHosts: 'array',
+  probe: 'object',
+  startChain: 'number',
+  refuseTypedData: 'object',
+  signatureLog: 'object',
+  startPath: 'string',
+  pagePath: 'function',
+  dependencies: 'array',
+  testnetVariable: 'string',
+  module: 'string',
+};
+
+function checkPolicy(policy, file) {
+  const problems = [];
+  if (!policy || typeof policy !== 'object') problems.push('exports no policy object');
+  else {
+    if (policy.policyVersion !== POLICY_VERSION) problems.push(`policyVersion is ${policy.policyVersion ?? 'missing'}, this web-dapp reads ${POLICY_VERSION}`);
+    for (const [name, type] of Object.entries(MEMBERS)) {
+      const value = policy[name];
+      const ok = type === 'array' ? Array.isArray(value) : type === 'object' ? value !== null && typeof value === 'object' : typeof value === type;
+      if (!ok) problems.push(`${name} must be ${type === 'array' || type === 'object' ? `an ${type}` : `a ${type}`}`);
+    }
+    const { checkout, refuseTypedData, signatureLog } = policy;
+    if (checkout && typeof checkout.matches !== 'function') problems.push('checkout.matches must be a function');
+    for (const name of ['name', 'label', 'needs']) if (checkout && typeof checkout[name] !== 'string') problems.push(`checkout.${name} must be a string`);
+    if (refuseTypedData && typeof refuseTypedData.reason !== 'function') problems.push('refuseTypedData.reason must be a function');
+    for (const name of ['kind', 'message']) if (refuseTypedData && typeof refuseTypedData[name] !== 'string') problems.push(`refuseTypedData.${name} must be a string`);
+    // The venue's request-log rules: both maps are required (empty only on purpose), so a
+    // policy cannot drop its L1 or mainnet rules by omission.
+    for (const name of ['typedDataClasses', 'forbiddenEntries']) {
+      if (signatureLog && (signatureLog[name] === null || typeof signatureLog[name] !== 'object')) problems.push(`signatureLog.${name} must be an object`);
+    }
+  }
+  if (problems.length) {
+    throw new Error(`web-dapp venue policy ${file}: ${problems.join('; ')}.\nNext: update the library that declares the adapter to a revision written for this mm-harness.`);
+  }
+  return policy;
+}
+
+export function webDappPolicy(env = process.env) {
+  const file = env[POLICY_ENV];
+  if (!file) {
+    throw new Error(
+      'web-dapp needs a venue policy: select an adapter that extends it.\n' +
+      'Next: put the library that declares it on RECIPE_LIBRARY_PATH and pass its id, e.g. --adapter terminal.',
+    );
+  }
+  if (loaded?.file !== file) {
+    // The policy module uses node built-ins only and has no top-level await, so it loads synchronously.
+    loaded = { file, policy: checkPolicy(createRequire(import.meta.url)(path.resolve(file)).policy, file) };
+  }
+  return loaded.policy;
+}
+
+// The bound adapter's id, for names and paths; web-dapp's own when none is bound.
+export function webDappAdapterId(env = process.env) {
+  return env[POLICY_ENV] ? webDappPolicy(env).adapterId : 'web-dapp';
+}

package/adapters/{terminal → web-dapp}/lib/processes.mjs

@@ -1,4 +1,4 @@
-// Stop the terminal slot browser and wallet host by their pid files and prove
+// Stop the web-dapp slot browser and wallet host by their pid files and prove
 // the slot CDP port is released. A pid is signalled only when its command line
 // carries this slot's owner marker for that process kind. A pid file naming a
 // dead process is removed; one naming a live process without the marker is
@@ -10,7 +10,7 @@ import { existsSync, readFileSync, rmSync } from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 
-import { terminalRuntimeDir } from '../../../library/actions/terminal/platform/runtime.mjs';
+import { webDappPolicy, webDappRuntimeDir } from '../../../library/actions/web-dapp/platform/runtime.mjs';
 
 export function pidAlive(pid) {
   if (!Number.isInteger(Number(pid)) || Number(pid) <= 0) return false;
@@ -58,7 +58,7 @@ export const OWNER_FLAG = '--mm-harness-owner';
 export const OWNER_KINDS = Object.freeze(['browser', 'wallet-host', 'console-collector']);
 
 export function ownerMarker(kind, runtimeDir) {
-  if (!OWNER_KINDS.includes(kind)) throw new Error(`unknown terminal process kind ${kind}`);
+  if (!OWNER_KINDS.includes(kind)) throw new Error(`unknown web-dapp process kind ${kind}`);
   const id = createHash('sha256').update(path.resolve(runtimeDir)).digest('hex').slice(0, 32);
   return `${OWNER_FLAG}=${kind}-${id}`;
 }
@@ -104,10 +104,10 @@ export async function terminate(pid, graceMs = 8000) {
   return true;
 }
 
-// The console collector a run started (src/adapters/terminal/console-capture.ts)
+// The console collector a run started (src/adapters/web-dapp/console-capture.ts)
 // outlives browser relaunches inside the run; stop and cleanup end it.
 export async function stopConsoleCollector(target, { log = () => {}, runtimeDir } = {}) {
-  const runtime = runtimeDir ?? terminalRuntimeDir(target);
+  const runtime = runtimeDir ?? webDappRuntimeDir(target);
   const pidFile = path.join(runtime, 'console-tail.pid');
   const pid = readPid(pidFile);
   if (!pid) return { stopped: null };
@@ -149,8 +149,8 @@ export function cdpListenerPids(port) {
   }
 }
 
-export async function stopTerminalBrowser(target, { cdpPort, log = () => {}, runtimeDir } = {}) {
-  const runtime = runtimeDir ?? terminalRuntimeDir(target);
+export async function stopWebDappBrowser(target, { cdpPort, log = () => {}, runtimeDir } = {}) {
+  const runtime = runtimeDir ?? webDappRuntimeDir(target);
   const stopped = [];
   const stale = [];
   const foreign = [];
@@ -181,7 +181,7 @@ export async function stopTerminalBrowser(target, { cdpPort, log = () => {}, run
       await new Promise((resolve) => setTimeout(resolve, 250));
       free = await portFree(cdpPort);
     }
-    if (!free) throw new Error(`CDP port ${cdpPort} is still in use after stopping the terminal browser; another process owns it.`);
+    if (!free) throw new Error(`CDP port ${cdpPort} is still in use after stopping the ${webDappPolicy().adapterId} browser; another process owns it.`);
   }
   return { stopped, stale, foreign, cdpPortFree: free };
 }

package/adapters/{terminal → web-dapp}/lib/readiness.mjs

@@ -1,4 +1,4 @@
-// Read-only readiness of a Web Terminal slot for recipe runs: checkout shape,
+// Read-only readiness of a web-dapp slot for recipe runs: checkout shape,
 // dependencies, the slot dev server, forced testnet, wallet fixture, browser,
 // MetaMask extension copy and the per-slot CDP port. Never launches anything
 // except the optional short-lived browser start probe.
@@ -7,23 +7,13 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 
-import { canonicalPath, fixtureEntry, loadWalletFixture, readBrowserState, terminalRuntimeDir, viemAccountFromEntry } from '../../../library/actions/terminal/platform/runtime.mjs';
+import { canonicalPath, fixtureEntry, loadWalletFixture, readBrowserState, viemAccountFromEntry, webDappPolicy, webDappRuntimeDir } from '../../../library/actions/web-dapp/platform/runtime.mjs';
 import { ownsProcess, pidAlive, portFree } from './processes.mjs';
 
 function check(id, ok, detail, { required = true, status } = {}) {
   return { id, status: status ?? (ok ? 'pass' : 'fail'), required, detail };
 }
 
-export function isTerminalCheckout(target) {
-  try {
-    const pkg = JSON.parse(readFileSync(path.join(target, 'package.json'), 'utf8'));
-    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-    return Boolean(deps.next) && existsSync(path.join(target, 'src/features/perpetuals'));
-  } catch {
-    return false;
-  }
-}
-
 async function httpStatus(url, timeoutMs = 20000) {
   try {
     const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'manual' });
@@ -34,18 +24,18 @@ async function httpStatus(url, timeoutMs = 20000) {
 }
 
 // Diagnostic only. Whether the slot's dev server looks configured for testnet:
-// the farm starts `next dev` (temp/farmslot/next-dev.pid) with
-// NEXT_PUBLIC_HYPERLIQUID_FORCE_TESTNET=true. Process inspection cannot prove
+// the farm starts `next dev` (temp/farmslot/next-dev.pid) with the policy's
+// testnet variable set to true (the Terminal's
+// NEXT_PUBLIC_HYPERLIQUID_FORCE_TESTNET). Process inspection cannot prove
 // what the browser talks to (macOS reports a process's initial environment,
 // and lsof cannot see other users' sockets), so this only warns; the browser
-// is held to testnet by the network and wallet layers (mainnet-guard.mjs, the
-// wallet host). Each listener on the app port must descend from the pid-file
-// process and run from the checkout (its cwd); every process on the way from
+// is held to testnet by the network and wallet layers (the venue policy's
+// blocked hosts, the wallet host). Each listener on the app port must descend
+// from the pid-file process and run from the checkout (its cwd); every process on the way from
 // a listener up to the pid-file process is read exactly (argv and environment
 // entries from sysctl KERN_PROCARGS2) and must carry the testnet variable. An
 // unreadable process makes the result unknown.
 export const DEV_SERVER_PID_FILE = 'temp/farmslot/next-dev.pid';
-const FORCE_VARIABLE = 'NEXT_PUBLIC_HYPERLIQUID_FORCE_TESTNET';
 
 function run(command, args) {
   try {
@@ -142,7 +132,7 @@ function chainTo(listener, root, parents) {
   return null;
 }
 
-export function devServerTestnetDiagnostic(target, { appPort, probe = systemProbe } = {}) {
+export function devServerTestnetDiagnostic(target, { appPort, variable, probe = systemProbe } = {}) {
   const checkout = canonicalPath(target);
   const unknown = (detail) => ({ known: false, forced: false, detail });
   const pidFile = path.join(checkout, DEV_SERVER_PID_FILE);
@@ -170,32 +160,40 @@ export function devServerTestnetDiagnostic(target, { appPort, probe = systemProb
       const processMode = nextServerMode(args.argv);
       if (processMode === 'start') return { known: true, forced: false, detail: `pid ${pid} runs next start; its environment cannot prove what the build inlined` };
       if (processMode === 'dev') mode = 'dev';
-      const value = environmentValue(args.env, FORCE_VARIABLE);
+      const value = environmentValue(args.env, variable);
       if (value !== 'true') {
-        return { known: true, forced: false, detail: `pid ${pid} (between app port ${appPort} and next dev pid ${root}) has ${FORCE_VARIABLE}=${value ?? '<unset>'}` };
+        return { known: true, forced: false, detail: `pid ${pid} (between app port ${appPort} and next dev pid ${root}) has ${variable}=${value ?? '<unset>'}` };
       }
     }
   }
   if (mode !== 'dev') return { known: true, forced: false, detail: `no process serving app port ${appPort} runs next dev` };
-  return { known: true, forced: true, detail: `every process from app port ${appPort}'s listeners (cwd ${checkout}) up to next dev pid ${root} has ${FORCE_VARIABLE}=true` };
+  return { known: true, forced: true, detail: `every process from app port ${appPort}'s listeners (cwd ${checkout}) up to next dev pid ${root} has ${variable}=true` };
 }
 
 export const MAINNET_CONFIRMATION = 'REAL_FUNDS';
 
 // The launch only checks the requested network: mainnet needs the real-funds
-// confirmation. Testnet is enforced inside the browser (mainnet-guard.mjs).
+// confirmation. Testnet is enforced inside the browser (the venue policy's blocked hosts).
 export function assertLaunchNetwork(_target, { network, mainnetConfirmation } = {}) {
   const requested = network == null || network === '' ? 'testnet' : String(network);
   if (requested !== 'testnet' && requested !== 'mainnet') {
     throw new Error(`network must be testnet or mainnet, got ${JSON.stringify(network)}.`);
   }
   if (requested === 'mainnet' && mainnetConfirmation !== MAINNET_CONFIRMATION) {
-    throw new Error(`network=mainnet needs mainnet_confirmation=${MAINNET_CONFIRMATION}; refusing to launch the terminal browser.`);
+    throw new Error(`network=mainnet needs mainnet_confirmation=${MAINNET_CONFIRMATION}; refusing to launch the ${webDappPolicy().adapterId} browser.`);
   }
   return requested;
 }
 
-export async function terminalReadiness({
+// "a, b and c".
+function listing(names) {
+  return names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names.join('');
+}
+
+// `policy`: the venue policy (checkout, dependencies, startPath, testnetVariable);
+// by default the one RECIPE_WEB_DAPP_POLICY names.
+export async function webDappReadiness({
+  policy = webDappPolicy(),
   target,
   appPort,
   cdpPort,
@@ -205,19 +203,19 @@ export async function terminalReadiness({
   probeBrowser = undefined,
 }) {
   const checks = [];
-  const shape = isTerminalCheckout(target);
-  checks.push(check('checkout', shape, shape ? 'Next.js checkout with src/features/perpetuals' : `${target} is not a Web Terminal checkout`));
-  const deps = ['next', '@nktkas/hyperliquid', '@metamask/perps-controller'].filter((name) => !existsSync(path.join(target, 'node_modules', name, 'package.json')));
-  checks.push(check('dependencies', deps.length === 0, deps.length === 0 ? 'next, @nktkas/hyperliquid and @metamask/perps-controller installed' : `missing: ${deps.join(', ')} (run npm ci on Node 22)`));
+  const shape = policy.checkout.matches(target);
+  checks.push(check('checkout', shape, shape ? policy.checkout.label : `${target} is not a ${policy.checkout.name} checkout`));
+  const deps = policy.dependencies.filter((name) => !existsSync(path.join(target, 'node_modules', name, 'package.json')));
+  checks.push(check('dependencies', deps.length === 0, deps.length === 0 ? `${listing(policy.dependencies)} installed` : `missing: ${deps.join(', ')} (run npm ci on Node 22)`));
 
   if (appPort) {
-    const status = await httpStatus(`http://127.0.0.1:${appPort}/order/BTC`);
-    checks.push(check('app-dev-server', status === 200, `GET http://localhost:${appPort}/order/BTC -> ${status}`));
+    const status = await httpStatus(`http://127.0.0.1:${appPort}${policy.startPath}`);
+    checks.push(check('app-dev-server', status === 200, `GET http://localhost:${appPort}${policy.startPath} -> ${status}`));
   } else {
     checks.push(check('app-dev-server', false, 'no dev-server port; pass --watcher-port <port> or set TERMINAL_APP_PORT'));
   }
-  // Advisory: the browser enforces testnet itself (mainnet-guard.mjs).
-  const testnet = devServerTestnetDiagnostic(target, { appPort });
+  // Advisory: the browser enforces testnet itself (the venue policy's blocked hosts).
+  const testnet = devServerTestnetDiagnostic(target, { appPort, variable: policy.testnetVariable });
   checks.push(check('testnet-forced', testnet.known && testnet.forced, testnet.detail, {
     required: false,
     status: testnet.known && testnet.forced ? 'pass' : 'warn',
@@ -256,7 +254,7 @@ export async function terminalReadiness({
     : 'TERMINAL_EXTENSION_CHECKOUT unset or not installed (needed to import the wallet into the extension)', { required: extensionRequired }));
 
   const state = await readBrowserState(target);
-  const runtime = terminalRuntimeDir(target);
+  const runtime = webDappRuntimeDir(target);
   const live = Boolean(state && ownsProcess('browser', state.browserPid, runtime) && ownsProcess('wallet-host', state.hostPid, runtime));
   if (cdpPort) {
     const free = await portFree(cdpPort);

package/adapters/{terminal → web-dapp}/stop.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// stop.mjs — stop the terminal slot browser, wallet host and console collector, verify the CDP port
+// stop.mjs — stop the web-dapp slot browser, wallet host and console collector, verify the CDP port
 // is free. Idempotent: nothing running is success.
 //
 // Inputs: --target <checkout> [--cdp-port <port>] [--json]
@@ -9,7 +9,8 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { stopConsoleCollector, stopTerminalBrowser } from './lib/processes.mjs';
+import { webDappPolicy } from '../../library/actions/web-dapp/platform/runtime.mjs';
+import { stopConsoleCollector, stopWebDappBrowser } from './lib/processes.mjs';
 
 const usage = 'Usage: stop.mjs --target <checkout> [--cdp-port <port>] [--json]';
 
@@ -26,8 +27,8 @@ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.me
   const target = value('--target') ?? process.cwd();
   const rawPort = value('--cdp-port') ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT;
   try {
-    const log = (message) => process.stderr.write(`[terminal/stop] ${message}\n`);
-    const result = await stopTerminalBrowser(target, { cdpPort: rawPort ? Number(rawPort) : undefined, log });
+    const log = (message) => process.stderr.write(`[${webDappPolicy().adapterId}/stop] ${message}\n`);
+    const result = await stopWebDappBrowser(target, { cdpPort: rawPort ? Number(rawPort) : undefined, log });
     const collector = await stopConsoleCollector(target, { log });
     process.stdout.write(`${JSON.stringify({ status: 'pass', ...result, consoleCollector: collector })}\n`);
   } catch (error) {

package/adapters/{terminal → web-dapp}/verify.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// verify.mjs — `mm-harness verify --adapter terminal`: read-only readiness of a
-// Web Terminal slot (checkout, deps, dev server, forced testnet, fixture,
+// verify.mjs — `mm-harness verify --adapter <web-dapp adapter>`: read-only readiness of a
+// web-dapp slot (checkout, deps, dev server, forced testnet, fixture,
 // browser start probe, MetaMask extension copy, CDP port).
 //
 // Inputs: --target <checkout> [--cdp-port <port>] [--watcher-port <app port>]
@@ -12,7 +12,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { resolveBrowser } from './launch.mjs';
-import { terminalReadiness } from './lib/readiness.mjs';
+import { webDappPolicy } from '../../library/actions/web-dapp/platform/runtime.mjs';
+import { webDappReadiness } from './lib/readiness.mjs';
 
 const usage = 'Usage: verify.mjs --target <checkout> [--cdp-port <port>] [--watcher-port <app port>] [--signer extension|injected] [--account <name>] [--json]';
 
@@ -27,7 +28,9 @@ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.me
     return index >= 0 ? argv[index + 1] : undefined;
   };
   const num = (raw) => (raw && /^\d+$/u.test(raw) ? Number(raw) : undefined);
-  const report = await terminalReadiness({
+  const policy = webDappPolicy();
+  const report = await webDappReadiness({
+    policy,
     target: path.resolve(value('--target') ?? process.cwd()),
     appPort: num(value('--watcher-port') ?? process.env.TERMINAL_APP_PORT ?? process.env.WATCHER_PORT),
     cdpPort: num(value('--cdp-port') ?? process.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT),
@@ -36,13 +39,13 @@ if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.me
     probeBrowser: resolveBrowser,
   });
   if (argv.includes('--json')) {
-    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, command: 'verify', adapter: 'terminal', ...report }, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, command: 'verify', adapter: policy.adapterId, ...report }, null, 2)}\n`);
   } else {
     for (const check of report.checks) {
       const mark = check.status === 'pass' ? '✓' : check.status === 'warn' || !check.required ? '·' : '✗';
       process.stdout.write(`${mark} ${check.id}: ${check.detail}\n`);
     }
-    process.stdout.write(report.status === 'pass' ? 'terminal slot ready\n' : `not ready: ${report.failed.join(', ')}\n`);
+    process.stdout.write(report.status === 'pass' ? `${policy.adapterId} slot ready\n` : `not ready: ${report.failed.join(', ')}\n`);
   }
   process.exit(report.status === 'pass' ? 0 : 1);
 }