@farmslot/adapter-web 0.5.0 → 0.6.0

package/src/web-dapp/lib/signers.mjs

@@ -0,0 +1,105 @@
+// Signer hooks for the extension signer (signer=extension). The wallet that
+// drives a real browser extension is the host product's (MetaMask's, for
+// mm-harness), so web-dapp's launcher, wallet host and readiness call it
+// through hooks instead of knowing it. signer=injected needs none: the strict
+// test wallet in @farmslot/adapter-web/dapp is generic.
+//
+// A signer module is an ESM file exporting `signers`, an object keyed by signer
+// mode (`extension`, and `injected` for its identity):
+//
+//   export const signers = { extension: {
+//     // Before the browser starts: load the extension and seed the profile.
+//     // Returns { browserArgs, secrets, state, afterBrowserStart? }:
+//     //   browserArgs   extra browser arguments (--load-extension=...)
+//     //   secrets       files holding key material, removed when the launch ends
+//     //   state         recorded under `extension` in browser.json
+//     //   afterBrowserStart(ctx)  runs once the browser answers on CDP; ctx is
+//     //     { cdpPort, launchMethod, windowBounds, withBrowserClient,
+//     //       openBackgroundWindow(url), log, trackSecret }. May return { state, hostArgs }:
+//     //     state merges into the recorded state, hostArgs go to the wallet host.
+//     // `trackSecret(file)` registers a key-material file at once, so it is removed
+//     // even when prepareProfile throws part-way; `secrets` may list more.
+//     async prepareProfile({ target, runtime, profile, account, fixture, env,
+//                            freshProfile, log, writePrivateFile, trackSecret }) {},
+//     // Required with prepareProfile: without it the wallet host would close the
+//     // wallet's own tabs. In the wallet host: judge the wallet's own confirmation
+//     // surfaces. Returns
+//     // { isWalletSurfaceUrl(url), observe(targetId, url) }; `args` are the wallet
+//     // host's flags (e.g. args['extension-id']). `focus`, when the host observes
+//     // focus, has observe(surface, productName) to record a window that took it.
+//     confirm({ args, appendEntry, say, focus }) {},
+//     // In readiness: the signer's own checks (build them with `check` from
+//     // readiness.mjs), `required` when signer=extension is requested.
+//     async readinessChecks({ target, env, required }) {},
+//   } };
+//
+// `signers.injected: { identity }` is the EIP-6963 identity
+// ({ info: { uuid, name, icon, rdns }, isMetaMask }) the injected strict wallet
+// presents, for an app that only connects to a known wallet. Without it the
+// strict wallet presents a generic identity.
+// A configured module makes signer=extension the default (`defaultSigner`), so
+// a host whose module only sets an identity (`signers = { injected: { identity } }`)
+// sets the signer explicitly (--signer injected or TERMINAL_SIGNER=injected).
+//
+// The module path is the one source of these hooks: every process (readiness,
+// launch, verify, the wallet host) loads it through RECIPE_WEB_DAPP_SIGNER_MODULE
+// or --signer-module on launch and verify, or `signerModule` of
+// createWebDappAdapter. With no signer requested, the signer is extension when
+// a module is configured and injected otherwise (`defaultSigner`).
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const SIGNER_MODULE_ENV = 'RECIPE_WEB_DAPP_SIGNER_MODULE';
+
+// The signer a run uses when none is requested: extension when a signer module
+// is configured (by path or RECIPE_WEB_DAPP_SIGNER_MODULE), else the injected
+// strict wallet, which needs none.
+export function defaultSigner(signerModule, env = process.env) {
+  return signerModule || env[SIGNER_MODULE_ENV] ? 'extension' : 'injected';
+}
+
+export async function loadSigners(env = process.env) {
+  const file = env[SIGNER_MODULE_ENV];
+  if (!file) return {};
+  const resolved = path.resolve(file);
+  const loaded = await import(pathToFileURL(resolved).href);
+  const signers = loaded.signers ?? loaded.default;
+  if (!signers || typeof signers !== 'object') {
+    throw new Error(
+      `web-dapp signer module ${resolved} must export \`signers\`, an object keyed by signer mode.`,
+    );
+  }
+  return signers;
+}
+
+// The injected strict wallet's EIP-6963 identity: the signer module's
+// `injected.identity` when it gives one (a host whose app only connects to a
+// known wallet, e.g. mm-harness presenting MetaMask so the app connects to it
+// the way it connects to the extension), else a generic one.
+export const GENERIC_INJECTED_IDENTITY = Object.freeze({
+  info: Object.freeze({
+    uuid: '5d1e5b4e-e2e0-4c3f-9a1d-000000000001',
+    name: 'Strict test wallet',
+    icon: "data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'/>",
+    rdns: 'io.farmslot.strict-wallet',
+  }),
+  isMetaMask: false,
+});
+
+export function injectedWalletIdentity(signers = {}) {
+  const identity = signers.injected?.identity;
+  if (identity === undefined) return GENERIC_INJECTED_IDENTITY;
+  const info = identity?.info;
+  if (
+    !info ||
+    typeof info.uuid !== 'string' ||
+    typeof info.name !== 'string' ||
+    typeof info.rdns !== 'string'
+  ) {
+    throw new Error(
+      'web-dapp signer module: injected.identity needs info.uuid, info.name and info.rdns strings.',
+    );
+  }
+  return identity;
+}

package/src/web-dapp/lib/viem.mjs

@@ -0,0 +1,26 @@
+// viem is the account derivation the wallet fixture needs (mnemonic and private
+// key accounts). adapter-web does not depend on it: it is resolved from the app
+// checkout under test (the Next.js app carries viem), else from where
+// adapter-web is installed, else from the working directory.
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export function loadViemAccounts(projectRoot) {
+  const bases = [
+    ...(projectRoot ? [path.join(path.resolve(projectRoot), 'package.json')] : []),
+    import.meta.url,
+    path.join(process.cwd(), 'package.json'),
+  ];
+  for (const base of bases) {
+    try {
+      return createRequire(base)('viem/accounts');
+    } catch (error) {
+      if (error?.code !== 'MODULE_NOT_FOUND') throw error;
+    }
+  }
+  throw new Error(
+    'viem is not installed where web-dapp can see it (the app checkout, then adapter-web).\n' +
+      'Next: install viem in the app checkout under test.',
+  );
+}

package/src/web-dapp/stop.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// 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]
+// Outputs: JSON summary on stdout. Exit 0 stopped/nothing to stop; 1 port still owned.
+// Never touches: the Next.js dev server (Farmslot owns it), browser profiles.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { stopConsoleCollector, stopWebDappBrowser } from './lib/processes.mjs';
+import { webDappPolicy } from './lib/runtime.mjs';
+
+const usage = 'Usage: stop.mjs --target <checkout> [--cdp-port <port>] [--json]';
+
+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 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(`[${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) {
+    process.stdout.write(`${JSON.stringify({ status: 'fail', error: error.message })}\n`);
+    process.exit(1);
+  }
+}

package/src/web-dapp/verify.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// 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, the extension signer's own checks, CDP port).
+//
+// Inputs: --target <checkout> [--cdp-port <port>] [--watcher-port <app port>]
+//   [--signer extension|injected] [--signer-module <path>] [--account <name>] [--json]
+// Outputs: readiness JSON (or a human summary) on stdout. Exit 0 ready; 1 not ready.
+// Never launches the slot browser or the dev server.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { webDappReadiness } from './lib/readiness.mjs';
+import { webDappPolicy } from './lib/runtime.mjs';
+import { defaultSigner, loadSigners, SIGNER_MODULE_ENV } from './lib/signers.mjs';
+import { resolveBrowser } from './launch.mjs';
+
+const usage =
+  'Usage: verify.mjs --target <checkout> [--cdp-port <port>] [--watcher-port <app port>] [--signer extension|injected] [--signer-module <path>] [--account <name>] [--json]';
+
+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 num = (raw) => (raw && /^\d+$/u.test(raw) ? Number(raw) : undefined);
+  const policy = webDappPolicy();
+  const signerModule = value('--signer-module');
+  const signers = await loadSigners({
+    ...process.env,
+    ...(signerModule ? { [SIGNER_MODULE_ENV]: signerModule } : {}),
+  });
+  const report = await webDappReadiness({
+    policy,
+    signers,
+    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),
+    signer: value('--signer') ?? process.env.TERMINAL_SIGNER ?? defaultSigner(signerModule),
+    account: value('--account') ?? process.env.TERMINAL_ACCOUNT ?? 'dev1',
+    probeBrowser: resolveBrowser,
+  });
+  if (argv.includes('--json')) {
+    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'
+        ? `${policy.adapterId} slot ready\n`
+        : `not ready: ${report.failed.join(', ')}\n`,
+    );
+  }
+  process.exit(report.status === 'pass' ? 0 : 1);
+}