@farmslot/adapter-web 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to `@farmslot/adapter-web` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.19.1 - 2026-11-08
+
+- Republish against protocol 0.82.2 and the current package set, so consumers load one copy of each Farmslot package.
+
+## 0.19.0 - 2026-11-06
+
+- Web-dapp wallet accounts: a mnemonic entry yields every account its `count` names (`names[]`, else dev1, dev2, ...), and `--account` selects one by name or address. A host can add named derivations of a fixture secret at a higher HD index through `RECIPE_WALLET_DERIVED_ACCOUNTS`; a declared address that does not match is refused. `browser.json` records the account's fixture secret name and index.
+
 ## 0.18.0 - 2026-11-05
 
 - Run ordinary websites in an owned extension-free browser with shared CDP actions, screenshots and whole-run recording. Existing extension launches retain their lifecycle.

package/dist/web-dapp/index.d.mts

@@ -125,5 +125,5 @@ export { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, shellQuote, wal
 export { assertPolicyDigest, fencePolicy, POLICY_DIGEST_ENV, PolicyFenceError } from "./lib/policy-fence.mjs";
 export { cdpListenerPids, ownedBrowserPids, OWNER_FLAG, OWNER_KINDS, ownerMarker, ownsProcess, pidAlive, portFree, stopConsoleCollector, stopWebDappBrowser, terminate } from "./lib/processes.mjs";
 export { assertLaunchNetwork, DEV_SERVER_PID_FILE, devServerTestnetDiagnostic, pythonFor, webDappReadiness } from "./lib/readiness.mjs";
-export { accountName, appOrigin, appPort, canonicalPath, cdpPort, DEFAULT_ACCOUNT, fixtureAccount, fixtureEntry, fixturePath, loadWalletFixture, readBrowserState, readJsonFile, resolveAccountAddress, resolveSigner, SIGNER_MODES, viemAccountFromEntry, webDappRuntimeDir, webDappRuntimePath, writePrivateJson } from "./lib/runtime.mjs";
+export { accountName, appOrigin, appPort, canonicalPath, cdpPort, DEFAULT_ACCOUNT, DERIVED_ACCOUNTS_ENV, fixtureAccount, fixtureEntry, fixturePath, loadWalletFixture, readBrowserState, readJsonFile, resolveAccountAddress, resolveSigner, SIGNER_MODES, viemAccountFromEntry, walletAccount, walletAccounts, webDappRuntimeDir, webDappRuntimePath, writePrivateJson } from "./lib/runtime.mjs";
 export { macosSessionLocked, parseSessionLocked, SESSION_LOCKED_MESSAGE, SESSION_LOCKED_USER_ACTION } from "./lib/session-lock.mjs";

package/dist/web-dapp/lib/runtime.d.mts

@@ -15,7 +15,28 @@ export function loadWalletFixture(projectRoot: any, env?: NodeJS.ProcessEnv): Pr
     fixture: any;
 }>;
 export function fixtureEntry(fixture: any, name: any): any;
-export function viemAccountFromEntry(entry: any, projectRoot: any): any;
+export function viemAccountFromEntry(entry: any, projectRoot: any, addressIndex?: number): any;
+export function derivedAccounts(env?: NodeJS.ProcessEnv): any[];
+/**
+ * Every account the fixture offers: each mnemonic entry expanded to its count,
+ * each private key, then the host's named derivations (DERIVED_ACCOUNTS_ENV)
+ * of the secrets this fixture holds. `account` is the viem account holding the
+ * key: sign with it, never log or persist it.
+ */
+export function walletAccounts(fixture: any, projectRoot: any, env?: NodeJS.ProcessEnv): {
+    name: any;
+    address: any;
+    secret: any;
+    index: any;
+    account: any;
+}[];
+export function walletAccount(fixture: any, selector: any, projectRoot: any, env?: NodeJS.ProcessEnv): {
+    name: any;
+    address: any;
+    secret: any;
+    index: any;
+    account: any;
+};
 export function fixtureAccount(projectRoot: any, name: any, env?: NodeJS.ProcessEnv): Promise<any>;
 export function resolveAccountAddress(input: any, env?: NodeJS.ProcessEnv): Promise<{
     name: any;
@@ -23,6 +44,7 @@ export function resolveAccountAddress(input: any, env?: NodeJS.ProcessEnv): Prom
 }>;
 export const SIGNER_MODES: readonly string[];
 export const DEFAULT_ACCOUNT: "dev1";
+export const DERIVED_ACCOUNTS_ENV: "RECIPE_WALLET_DERIVED_ACCOUNTS";
 import { POLICY_ENV } from './policy.mjs';
 import { webDappAdapterId } from './policy.mjs';
 import { webDappPolicy } from './policy.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-web",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Web platform adapter for Farmslot recipes: resolve and launch an isolated Chromium, own its CDP port, load unpacked extensions, and keep macOS focus.",
   "type": "commonjs",
   "exports": {
@@ -87,9 +87,9 @@
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/adapter-web"
   },
   "dependencies": {
-    "@farmslot/adapter-sdk": "0.26.3",
-    "@farmslot/protocol": "0.76.0",
-    "@farmslot/recipe-runner": "0.46.6",
+    "@farmslot/adapter-sdk": "0.26.4",
+    "@farmslot/protocol": "0.82.2",
+    "@farmslot/recipe-runner": "0.46.8",
     "ws": "^8.18.0"
   },
   "devDependencies": {

package/src/web-dapp/index.mjs

@@ -90,6 +90,7 @@ export {
   canonicalPath,
   cdpPort,
   DEFAULT_ACCOUNT,
+  DERIVED_ACCOUNTS_ENV,
   fixtureAccount,
   fixtureEntry,
   fixturePath,
@@ -100,6 +101,8 @@ export {
   resolveSigner,
   SIGNER_MODES,
   viemAccountFromEntry,
+  walletAccount,
+  walletAccounts,
   webDappRuntimeDir,
   webDappRuntimePath,
   writePrivateJson,

package/src/web-dapp/launch.mjs

@@ -11,11 +11,12 @@
 //   wallet requests.
 //
 // Inputs (flags): --target <checkout> --cdp-port <port> --app-port <port>
-//   [--signer extension|injected] [--signer-module <path>] [--account <fixture name>]
+//   [--signer extension|injected] [--signer-module <path>] [--account <name|address>]
 //   [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--start-chain <id>]
 //   [--json] [--network mainnet --mainnet-confirmation REAL_FUNDS] (testnet
 //   otherwise, enforced in the browser from the venue policy)
 //   env: TERMINAL_CHROME_BIN, RECIPE_WEB_DAPP_SIGNER_MODULE, RECIPE_WALLET_FIXTURE,
+//   RECIPE_WALLET_DERIVED_ACCOUNTS,
 //   TERMINAL_HEADLESS, TERMINAL_SLOW_MO, TERMINAL_WINDOW, TERMINAL_SCREEN
 //   (plus whatever the signer module reads)
 //   The browser is headful by default, in a window placed per slot (see
@@ -68,10 +69,9 @@ import {
 } from './lib/processes.mjs';
 import { assertLaunchNetwork, devServerTestnetDiagnostic } from './lib/readiness.mjs';
 import {
-  fixtureEntry,
   loadWalletFixture,
   resolveSigner,
-  viemAccountFromEntry,
+  walletAccount,
   webDappPolicy,
   webDappRuntimeDir,
 } from './lib/runtime.mjs';
@@ -86,7 +86,7 @@ const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const macosFocus = createRequire(import.meta.url)('../macos-focus.cjs');
 
 function usage() {
-  return 'Usage: launch.mjs --target <checkout> --cdp-port <port> --app-port <port> [--signer extension|injected] [--signer-module <path>] [--account <name>] [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--network testnet|mainnet --mainnet-confirmation REAL_FUNDS] [--start-chain <id>] [--json]';
+  return 'Usage: launch.mjs --target <checkout> --cdp-port <port> --app-port <port> [--signer extension|injected] [--signer-module <path>] [--account <name|address>] [--fresh-profile] [--headless | --headful] [--slow-mo <ms>] [--network testnet|mainnet --mainnet-confirmation REAL_FUNDS] [--start-chain <id>] [--json]';
 }
 
 export function parseLaunchArgs(argv, env = process.env) {
@@ -490,7 +490,14 @@ export async function launchWebDappBrowser(
   }
 
   const { fixture } = await loadWalletFixture(target, env);
-  const accountAddress = viemAccountFromEntry(fixtureEntry(fixture, args.account), target).address;
+  // --account is an account name or address; the browser runs under its name.
+  const selected = walletAccount(fixture, args.account, target, env);
+  const account = {
+    name: selected.name,
+    address: selected.address,
+    secret: selected.secret,
+    index: selected.index,
+  };
 
   const previous = readStateFile(stateFile);
   const reusable =
@@ -499,7 +506,8 @@ export async function launchWebDappBrowser(
     previous.signer === signer &&
     previous.cdpPort === cdpPort &&
     previous.appOrigin === appOrigin &&
-    previous.account?.name === args.account &&
+    previous.account?.name === account.name &&
+    previous.account?.address?.toLowerCase() === account.address.toLowerCase() &&
     previous.browser?.headless === headless &&
     (previous.network ?? 'testnet') === network &&
     previous.networkEnforcement?.fingerprint === enforcementFingerprint &&
@@ -507,7 +515,7 @@ export async function launchWebDappBrowser(
     ownsProcess('wallet-host', previous.hostPid, runtime);
   if (reusable) {
     await browserWebSocketUrl(cdpPort, 5000);
-    log(`reusing browser pid ${previous.browserPid} (${signer}, ${args.account})`);
+    log(`reusing browser pid ${previous.browserPid} (${signer}, ${account.name})`);
     const state = { ...previous, slowMoMs };
     if (previous.slowMoMs !== slowMoMs)
       writePrivateFile(stateFile, `${JSON.stringify(state, null, 2)}\n`);
@@ -518,7 +526,7 @@ export async function launchWebDappBrowser(
   const browser = await resolveBrowser(env);
   const profile = path.join(
     runtime,
-    `profile-${signer}-${args.account.replace(/[^A-Za-z0-9_-]/gu, '_')}`,
+    `profile-${signer}-${account.name.replace(/[^A-Za-z0-9_-]/gu, '_')}`,
   );
   if (args['fresh-profile'] && existsSync(profile)) {
     const retired = `${profile}.retired-${Date.now()}`;
@@ -571,7 +579,7 @@ export async function launchWebDappBrowser(
         target,
         runtime,
         profile,
-        account: args.account,
+        account: account.name,
         fixture,
         env,
         freshProfile,
@@ -683,7 +691,7 @@ export async function launchWebDappBrowser(
       '--target',
       target,
       '--account',
-      args.account,
+      account.name,
       '--start-chain',
       String(args['start-chain'] ?? policy.startChain),
       '--network',
@@ -758,7 +766,7 @@ export async function launchWebDappBrowser(
       appListeners: cdpListenerPids(appPort),
       cdpPort,
       appOrigin,
-      account: { name: args.account, address: accountAddress },
+      account,
       browserPid,
       hostPid,
       browser: {

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

@@ -11,10 +11,9 @@ import path from 'node:path';
 import { ownsProcess, pidAlive, portFree } from './processes.mjs';
 import {
   canonicalPath,
-  fixtureEntry,
   loadWalletFixture,
   readBrowserState,
-  viemAccountFromEntry,
+  walletAccount,
   webDappPolicy,
   webDappRuntimeDir,
 } from './runtime.mjs';
@@ -359,7 +358,7 @@ export async function webDappReadiness({
 
   try {
     const { file, fixture } = await loadWalletFixture(target, env);
-    const address = viemAccountFromEntry(fixtureEntry(fixture, account), target).address;
+    const { address } = walletAccount(fixture, account, target, env);
     checks.push(
       check('wallet-fixture', true, `${path.basename(file)}: account ${account} -> ${address}`),
     );

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

@@ -151,22 +151,26 @@ export function fixtureEntry(fixture, name) {
       .join(', ');
     throw new Error(`wallet fixture has no account named "${name}". Available: ${names}.`);
   }
+  return checkedEntry(entry);
+}
+
+function checkedEntry(entry) {
   if (entry.type !== 'mnemonic' && entry.type !== 'privateKey') {
     throw new Error(
-      `wallet fixture account "${name}" must be mnemonic or privateKey, got "${entry.type}".`,
+      `wallet fixture account "${entry.name}" must be mnemonic or privateKey, got "${entry.type}".`,
     );
   }
   if (typeof entry.value !== 'string' || !entry.value.trim()) {
-    throw new Error(`wallet fixture account "${name}" has no value.`);
+    throw new Error(`wallet fixture account "${entry.name}" has no value.`);
   }
   return entry;
 }
 
-// Mnemonics use BIP-44 index 0, the MetaMask default and the derivation the
-// Extension fixture flow imports.
-export function viemAccountFromEntry(entry, projectRoot) {
+// Mnemonics use BIP-44 m/44'/60'/0'/0/<addressIndex>, the MetaMask derivation
+// the Extension fixture flow imports; index 0 is the wallet's first account.
+export function viemAccountFromEntry(entry, projectRoot, addressIndex = 0) {
   const { mnemonicToAccount, privateKeyToAccount } = loadViemAccounts(projectRoot);
-  if (entry.type === 'mnemonic') return mnemonicToAccount(entry.value.trim(), { addressIndex: 0 });
+  if (entry.type === 'mnemonic') return mnemonicToAccount(entry.value.trim(), { addressIndex });
   const raw = entry.value.trim();
   const key = raw.startsWith('0x') ? raw : `0x${raw}`;
   if (!/^0x[0-9a-fA-F]{64}$/u.test(key)) {
@@ -175,9 +179,123 @@ export function viemAccountFromEntry(entry, projectRoot) {
   return privateKeyToAccount(key);
 }
 
+// Named HD derivations of the fixture's mnemonic entries that the host adds,
+// e.g. a team's shared test account at a higher index: JSON
+// [{ "name", "secret": <mnemonic entry name>, "index", "address"? }]. Names and
+// indexes only; the key stays in the fixture.
+export const DERIVED_ACCOUNTS_ENV = 'RECIPE_WALLET_DERIVED_ACCOUNTS';
+
+export function derivedAccounts(env = process.env) {
+  const raw = env[DERIVED_ACCOUNTS_ENV];
+  if (!raw) return [];
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${DERIVED_ACCOUNTS_ENV} is not JSON: ${error.message}`);
+  }
+  const valid = (item) =>
+    item &&
+    typeof item.name === 'string' &&
+    item.name.trim() &&
+    typeof item.secret === 'string' &&
+    item.secret.trim() &&
+    Number.isInteger(item.index) &&
+    item.index >= 0 &&
+    (item.address === undefined || /^0x[0-9a-fA-F]{40}$/u.test(item.address));
+  if (!Array.isArray(value) || !value.every(valid)) {
+    throw new Error(
+      `${DERIVED_ACCOUNTS_ENV} must be an array of { name, secret, index, address? } (index a non-negative integer).`,
+    );
+  }
+  return value;
+}
+
+function mnemonicCount(entry) {
+  const count = Number(entry.count ?? entry.numberOfAccounts ?? 1);
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new Error(
+      `wallet fixture account "${entry.name}" count must be an integer from 1 through 100.`,
+    );
+  }
+  return count;
+}
+
+// names[index] when the entry gives one; a single account keeps the entry's
+// name; otherwise dev1 with count 3 is dev1, dev2, dev3 (a name without a
+// trailing number gets one appended).
+function derivedName(entry, index, count) {
+  const explicit = Array.isArray(entry.names) ? entry.names[index] : undefined;
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+  if (count === 1) return entry.name;
+  const match = /^(.*?)(\d+)$/u.exec(entry.name);
+  return match ? `${match[1]}${Number(match[2]) + index}` : `${entry.name}${index + 1}`;
+}
+
+/**
+ * Every account the fixture offers: each mnemonic entry expanded to its count,
+ * each private key, then the host's named derivations (DERIVED_ACCOUNTS_ENV)
+ * of the secrets this fixture holds. `account` is the viem account holding the
+ * key: sign with it, never log or persist it.
+ */
+export function walletAccounts(fixture, projectRoot, env = process.env) {
+  const accounts = [];
+  for (const entry of fixture.accounts) {
+    if (entry?.type !== 'mnemonic' && entry?.type !== 'privateKey') continue;
+    checkedEntry(entry);
+    const count = entry.type === 'mnemonic' ? mnemonicCount(entry) : 1;
+    for (let index = 0; index < count; index += 1) {
+      const account = viemAccountFromEntry(entry, projectRoot, index);
+      accounts.push({
+        name: derivedName(entry, index, count),
+        address: account.address,
+        secret: entry.name,
+        index,
+        account,
+      });
+    }
+  }
+  for (const item of derivedAccounts(env)) {
+    const entry = fixture.accounts.find(
+      (candidate) => candidate?.type === 'mnemonic' && candidate.name === item.secret,
+    );
+    if (!entry) continue;
+    const account = viemAccountFromEntry(checkedEntry(entry), projectRoot, item.index);
+    if (item.address && item.address.toLowerCase() !== account.address.toLowerCase()) {
+      throw new Error(
+        `wallet account "${item.name}" derives to ${account.address} from "${item.secret}" index ${item.index}, not the declared ${item.address}.`,
+      );
+    }
+    accounts.push({
+      name: item.name,
+      address: account.address,
+      secret: item.secret,
+      index: item.index,
+      account,
+    });
+  }
+  return accounts;
+}
+
+// The fixture account a selector names: an account name, else an address.
+export function walletAccount(fixture, selector, projectRoot, env = process.env) {
+  const accounts = walletAccounts(fixture, projectRoot, env);
+  const wanted = String(selector ?? '').trim();
+  const found =
+    accounts.find((account) => account.name === wanted) ??
+    (/^0x[0-9a-fA-F]{40}$/u.test(wanted)
+      ? accounts.find((account) => account.address.toLowerCase() === wanted.toLowerCase())
+      : undefined);
+  if (!found) {
+    const names = accounts.map((account) => account.name).join(', ');
+    throw new Error(`wallet fixture has no account named "${wanted}". Available: ${names}.`);
+  }
+  return found;
+}
+
 export async function fixtureAccount(projectRoot, name, env = process.env) {
   const { fixture } = await loadWalletFixture(projectRoot, env);
-  return viemAccountFromEntry(fixtureEntry(fixture, name), projectRoot);
+  return walletAccount(fixture, name, projectRoot, env).account;
 }
 
 // Address-only view of the account a node targets: an explicit address wins