@deeeed/metamask-harness 0.2.0

package/runner/src/mm-harness-cli.ts

@@ -0,0 +1,488 @@
+// mm-harness — the single front door for the MetaMask recipe loop.
+//
+// This is the commander-based CLI entry (same stack as @farmslot/recipe-harness,
+// which depends on commander ^12). It presents ONLY the end-state surface
+// (docs/MENTAL-MODEL.md + docs/CLI-SPEC.md) and delegates to the dispatch in
+// `cli.ts` (`main`) so no orchestration logic is forked. Retired names still
+// teach; genuinely-unknown commands fall to commander's default.
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { Command } from 'commander';
+
+// runner root (…/runner) → its parent is the package root that holds scripts/.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// Signal cli.ts NOT to auto-run its own dispatch when we import it below: we
+// reuse its `main` in-process. Must be set BEFORE the dynamic import runs the
+// module body. (A dynamic import guarantees ordering; a static import would hoist
+// and execute cli.ts first.)
+(globalThis as Record<string, unknown>).__MM_HARNESS_WRAPPER__ = true;
+const { main: recipeMain } = await import('./cli.ts');
+
+const rawArgv = process.argv.slice(2);
+
+// --- Surface definition (single source for both dispatch and grouped help) ----
+
+interface CliCommand {
+  name: string;
+  summary: string;
+  example: string;
+  /** Per-command flags help printed when the user passes --help / -h. */
+  helpText: string;
+}
+
+
+// Commands that route straight to the dispatch in cli.ts. `actions --raw` is the
+// one translation (raw manifest dump).
+const REAL: CliCommand[] = [
+  {
+    name: 'actions',
+    summary: 'List the action vocabulary + field schemas (--raw dumps the raw action registry JSON).',
+    example: 'mm-harness actions --adapter mobile',
+    helpText: `mm-harness actions [flags]
+
+  List the action vocabulary + field schemas for the checkout adapter.
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --raw                              Dump raw action registry JSON
+  --json                             Machine-readable output
+
+Example:
+  mm-harness actions --adapter mobile
+  mm-harness actions --adapter extension --raw`,
+  },
+  {
+    name: 'call',
+    summary: 'Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).',
+    example: 'mm-harness call unlock',
+    helpText: `mm-harness call <action> [--arg k=v ...] [flags]
+
+  Run one action in isolation as a one-node recipe through the real engine path.
+  Fuzzy short-name: 'unlock' resolves to 'metamask.wallet.unlock' if unique; ambiguous = exit 2.
+
+  --arg k=v                          Action field value (repeatable)
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --artifacts-dir <dir>              Where to write evidence (default: temp dir)
+  --action-manifest <path>           Override the action manifest
+  --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
+  --json                             Machine-readable output
+
+Example:
+  mm-harness call unlock --adapter extension
+  mm-harness call command --arg cmd="echo hi" --adapter core --json`,
+  },
+  {
+    name: 'flows',
+    summary: 'Browse the reusable flow library (bare = list; `flows promote` publishes a flow up a tier). Resolves across libraries — personal > team > canonical, highest tier wins.',
+    example: 'mm-harness flows',
+    helpText: `mm-harness flows [flags]
+
+  Browse the reusable flow library. Flows resolve across libraries by precedence
+  (personal > team > canonical); the highest-tier copy wins and shadows lower ones.
+  Flow resolution is adapter-global, so there is no --adapter flag here.
+
+  --library <name=path>              Add/override a library source (repeatable)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness flows`,
+  },
+  {
+    name: 'run',
+    summary: 'Validate + run a recipe and write evidence (summary/trace/artifacts). --plan validates + prints the plan, touching nothing.',
+    example: 'mm-harness run recipe.json',
+    helpText: `mm-harness run <recipe.json> [flags]
+
+  Validate + run a recipe and write evidence (summary / trace / artifacts).
+
+  --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --artifacts-dir <dir>              Where to write evidence (required unless --plan)
+  --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
+  --json                             Machine-readable output
+  --record-video=full-run            Record a video of the run
+
+Example:
+  mm-harness run recipe.json --plan --adapter mobile
+  mm-harness run recipe.json --adapter extension --artifacts-dir ./out`,
+  },
+  {
+    name: 'doctor',
+    summary: 'Readiness check for a checkout — no app launch. --fix repairs the overlay/runtime without launching.',
+    example: 'mm-harness doctor',
+    helpText: `mm-harness doctor [flags]
+
+  Readiness check for a checkout — no app launch. Reports the fixture and runtime-context
+  sections so there is no hunting for files.
+
+  --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness doctor
+  mm-harness doctor --fix --json
+  mm-harness doctor --adapter mobile --target /path/to/checkout`,
+  },
+  {
+    name: 'install',
+    summary: 'Install the per-checkout runtime overlay (CI/agents; the everyday commands auto-ensure it).',
+    example: 'mm-harness install',
+    helpText: `mm-harness install [flags]
+
+  Install the per-checkout runtime overlay (for CI / agents).
+  The everyday commands auto-ensure it on first use.
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+
+Example:
+  mm-harness install
+  mm-harness install --adapter extension --target /path/to/checkout`,
+  },
+  {
+    name: 'verify',
+    summary: 'Check the overlay/runtime is present and healthy (no launch).',
+    example: 'mm-harness verify',
+    helpText: `mm-harness verify [flags]
+
+  Check the runtime overlay is present and healthy (no app launch).
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness verify
+  mm-harness verify --adapter core --target /path/to/checkout`,
+  },
+  {
+    name: 'cleanup',
+    summary: 'Remove the installed overlay and restore the checkout.',
+    example: 'mm-harness cleanup',
+    helpText: `mm-harness cleanup [flags]
+
+  Remove the installed overlay and restore the checkout.
+
+  --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+
+Example:
+  mm-harness cleanup
+  mm-harness cleanup --adapter mobile --target /path/to/checkout`,
+  },
+  {
+    name: 'launch',
+    summary: 'Launch the app (Metro/build + boot), auto-ensuring the runtime overlay first. Mobile: ios|android required.',
+    example: 'mm-harness launch ios',
+    helpText: `mm-harness launch [ios|android] [flags]
+
+  Launch the app — quick relaunch by default; --build for a full native/webpack build.
+  Mobile: target is MANDATORY (ios | android). Extension: no target (--fullscreen default;
+  --sidepanel to override). core is headless (teaching error — use verify/run).
+
+  --build                            Full native/webpack build tier (default = quick relaunch)
+  --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
+  --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
+  --watch                            Persistent webpack watcher then relaunch (extension only)
+  --sidepanel | --fullscreen         Extension display mode (default --fullscreen)
+  --heal <off|infra-only|auto>       Healing policy (default auto); bounds always enforced
+  --device <udid|name>               Target simulator/device (env: IOS_SIMULATOR / ADB_SERIAL)
+  --cdp-port <port>                  Extension CDP port (env: CDP_PORT / RECIPE_CDP_PORT)
+  --watcher-port <port>              Metro/webpack port (env: WATCHER_PORT / METRO_PORT)
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable summary (recovered[] / mutations[] / phase)
+
+Example:
+  mm-harness launch ios
+  mm-harness launch ios --build
+  mm-harness launch --verify --json`,
+  },
+  {
+    name: 'logs',
+    summary: 'Tail Metro/webpack + app logs for the active checkout.',
+    example: 'mm-harness logs',
+    helpText: `mm-harness logs [flags]
+
+  Tail Metro/webpack + app logs for the active checkout.
+  Teaching error if nothing is running (points at launch).
+
+  --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
+  --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
+  --source <metro|app>               Log source (default metro)
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness logs
+  mm-harness logs --full`,
+  },
+  {
+    name: 'debug',
+    summary: 'Open the debug console — extension: Chrome DevTools via CDP; mobile: RN DevTools.',
+    example: 'mm-harness debug',
+    helpText: `mm-harness debug [flags]
+
+  Open the debug console — extension: Chrome DevTools via CDP; mobile: RN DevTools.
+
+  --worker                           Extension service-worker DevTools
+  --dev-menu                         Mobile RN developer menu
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness debug
+  mm-harness debug --worker`,
+  },
+  {
+    name: 'fixtures',
+    summary: 'Manage the canonical wallet fixture (wallet DATA only) — sync files / set the wallet.',
+    example: 'mm-harness fixtures set',
+    helpText: `mm-harness fixtures <sync|set> [flags]
+
+  Manage the ONE canonical wallet fixture per checkout — wallet DATA only.
+  sync   Refresh the wallet fixture files on the target.
+  set    Apply the canonical fixture (SRP/password/accounts); the password is read
+         FROM the fixture, never typed.
+  Want different accounts? Edit the fixture file directly:
+    <checkout>/temp/recipe/runtime/wallet-fixture.json
+
+  --fixture <path>                   Override the fixture path (agent form; env: RECIPE_WALLET_FIXTURE)
+  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
+  --target <path>                    Checkout path (default: cwd)
+  --json                             Machine-readable output
+
+Example:
+  mm-harness fixtures sync
+  mm-harness fixtures set`,
+  },
+];
+
+// Retired names: NOT on the surface, but they must TEACH rather than fall to
+// commander's generic "unknown command" path. Each names its replacement and
+// exits 2 (bad-args/unsupported, distinct from a genuinely-unknown command's
+// exit 1). Genuinely-unknown commands stay on commander's default (which points
+// at --help via showHelpAfterError).
+interface RetiredCommand {
+  name: string;
+  message: string;
+}
+
+const RETIRED_INTERNAL = [
+  'runtime-health',
+  'runtime-decision',
+  'runtime-launch',
+  'resolve-extension',
+  'ensure-ready',
+  'self-test',
+];
+
+const RETIRED: RetiredCommand[] = [
+  {
+    name: 'live',
+    message:
+      `mm-harness live is retired (exit 2).\n\n` +
+      `Replacement: mm-harness launch --verify (install overlay → launch → CDP/bridge poll → smoke verify).`,
+  },
+  {
+    name: 'manifest',
+    message:
+      `mm-harness manifest is retired (exit 2).\n\n` +
+      `Replacement: mm-harness actions --raw   (works now — dumps the raw action registry JSON,\n` +
+      `identical to the old \`manifest --json\`). Manifest validation moved into doctor / run --plan.`,
+  },
+  ...RETIRED_INTERNAL.map((name) => ({
+    name,
+    message:
+      `mm-harness ${name} is retired (exit 2).\n\n` +
+      `It is internal now — its logic lives inside doctor / launch / verify self-healing.\n` +
+      `Use: mm-harness doctor`,
+  })),
+];
+
+// --- Grouped help (custom formatHelp; commander owns parse/dispatch) ---------
+
+interface HelpGroup {
+  title: string;
+  blurb: string;
+  commands: string[];
+}
+
+const HELP_GROUPS: HelpGroup[] = [
+  {
+    title: 'DAILY LOOP',
+    blurb: 'what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)',
+    commands: ['launch', 'logs', 'debug', 'fixtures'],
+  },
+  {
+    title: 'DISCOVER',
+    blurb: 'compose recipes from the action vocabulary + flow library (--json is the agent-primary form)',
+    commands: ['actions', 'call', 'flows'],
+  },
+  {
+    title: 'PROVE',
+    blurb: 'run recipes and inspect readiness',
+    commands: ['run', 'doctor'],
+  },
+  {
+    title: 'RUNTIME OVERLAY',
+    blurb: 'install/verify/clean the per-checkout overlay (the everyday commands auto-ensure it)',
+    commands: ['install', 'verify', 'cleanup'],
+  },
+];
+
+function commandMeta(name: string): { summary: string; example: string; planned: boolean } {
+  const real = REAL.find((command) => command.name === name);
+  if (real) return { summary: real.summary, example: real.example, planned: false };
+  return { summary: '', example: '', planned: false };
+}
+
+function groupedHelp(): string {
+  const lines: string[] = [];
+  lines.push('mm-harness — one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.');
+  lines.push('Run it from inside a MetaMask checkout; the platform (mobile | extension | core) is auto-detected.');
+  lines.push('Grammar: mm-harness <command> [target] [flags]   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)');
+  for (const group of HELP_GROUPS) {
+    lines.push('');
+    lines.push(`${group.title} — ${group.blurb}:`);
+    for (const name of group.commands) {
+      const meta = commandMeta(name);
+      const planned = meta.planned ? '   (planned)' : '';
+      lines.push(`  ${name.padEnd(10)} ${meta.summary}${planned}`);
+      lines.push(`               ${meta.example}`);
+    }
+  }
+  lines.push('');
+  lines.push('ONE bin: mm-harness is the only command. Platform is auto-detected; the positional target forces it');
+  lines.push('(mm-harness launch ios); platform-specific needs are FLAGS on the same command. Human happy path = the bare');
+  lines.push('command; agents add depth via flags (--json, --target, ports).');
+  lines.push('');
+  lines.push('SETUP — tab-completion (zsh + bash), sourced from the bundled scripts:');
+  lines.push('  mm-harness completions install   # print the lines to add to ~/.zshrc / ~/.bashrc');
+  lines.push('');
+  lines.push('See docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).');
+  return `${lines.join('\n')}\n`;
+}
+
+// --- Delegation -------------------------------------------------------------
+
+async function delegate(argv: string[]): Promise<number> {
+  try {
+    return await recipeMain(argv);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    // CliError (from cli.ts) carries an exitCode so usage errors (2) and
+    // validation errors (5) propagate correctly rather than always returning 1.
+    return error !== null &&
+      typeof error === 'object' &&
+      'exitCode' in error &&
+      typeof (error as Record<string, unknown>).exitCode === 'number'
+      ? (error as { exitCode: number }).exitCode
+      : 1;
+  }
+}
+
+// `actions --raw` == the retired `manifest --adapter <p> --json` raw dump.
+function translateActionsRaw(argv: string[]): string[] {
+  const rest = argv.slice(1).filter((arg) => arg !== '--raw');
+  const withJson = rest.includes('--json') ? rest : [...rest, '--json'];
+  return ['manifest', ...withJson];
+}
+
+// --- Program ----------------------------------------------------------------
+
+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 () => {
+      // Intercept --help / -h before delegation: the hand-rolled parser in cli.ts
+      // treats unknown flags as value-consuming and throws "Missing value for --help".
+      // Each command exposes its own flags via helpText; exit 0 so shell completion
+      // and tooling work correctly.
+      // Only check flags BEFORE the `--` separator so `install -- --help` correctly
+      // forwards --help to the underlying install script rather than intercepting it.
+      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}\n`);
+        process.exit(0);
+      }
+      const argv = command.name === 'actions' && rawArgv.includes('--raw') ? translateActionsRaw(rawArgv) : rawArgv;
+      process.exit(await delegate(argv));
+    });
+}
+
+// Hidden commands: real routing, but intentionally absent from the grouped help.
+// `completion-candidates <actions|flows>` is what the shell completion scripts
+// source; humans never type it.
+const HIDDEN: readonly string[] = ['completion-candidates'];
+for (const name of HIDDEN) {
+  program
+    .command(name, { hidden: true })
+    .allowUnknownOption()
+    .helpOption(false)
+    .argument('[args...]')
+    .action(async () => {
+      process.exit(await delegate(rawArgv));
+    });
+}
+
+// `completions` installs/prints the bundled zsh + bash tab-completion. It is
+// shell tooling (no engine), so it runs the bundled installer script directly
+// rather than routing through the dispatch in cli.ts.
+program
+  .command('completions')
+  .description('Install/print bundled shell tab-completion (zsh + bash)')
+  .allowUnknownOption()
+  .helpOption(false)
+  .argument('[args...]')
+  .action(() => {
+    const script = path.join(packageRoot, 'scripts', 'install-completions.sh');
+    const result = spawnSync('bash', [script, ...rawArgv.slice(1)], { stdio: 'inherit' });
+    process.exit(result.status ?? 1);
+  });
+
+// Retired names teach their replacement and exit 2 (not commander's generic
+// "unknown command" exit 1). They are NOT listed in the grouped help.
+for (const retired of RETIRED) {
+  program
+    .command(retired.name)
+    .description(`${retired.name} is retired (see teaching error)`)
+    .allowUnknownOption()
+    .helpOption(false)
+    .argument('[args...]')
+    .action(() => {
+      console.error(retired.message);
+      process.exit(2);
+    });
+}
+
+if (rawArgv.length === 0) {
+  process.stdout.write(groupedHelp());
+  process.exit(0);
+}
+
+await program.parseAsync(process.argv);

package/runner/src/paths.ts

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import type {
+  RecipeHarnessBrowserExtensionModule,
+  RecipeHarnessCdpModule,
+  RecipeHarnessModule,
+  RecipeHarnessReactNativeBridgeModule,
+  RecipeProtocolModule,
+  MetaMaskRecipeAdapter,
+} from './types.ts';
+
+export const runnerDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const pathDefaults = readPathDefaults();
+export const DEFAULT_RECIPE_RUNTIME_DIR = pathDefaults.recipeRuntimeDir;
+export const DEFAULT_RECIPE_HARNESS_ROOT = pathDefaults.recipeHarnessRoot;
+
+export function recipeRuntimeDir() {
+  return validateRelativeRecipePath('RECIPE_RUNTIME_DIR', process.env.RECIPE_RUNTIME_DIR || DEFAULT_RECIPE_RUNTIME_DIR);
+}
+
+export function recipeHarnessRoot() {
+  return validateRelativeRecipePath('RECIPE_HARNESS_ROOT', process.env.RECIPE_HARNESS_ROOT || DEFAULT_RECIPE_HARNESS_ROOT);
+}
+
+
+function readPathDefaults(): { recipeRuntimeDir: string; recipeHarnessRoot: string } {
+  const defaultsPath = path.join(runnerDir, 'orchestration/lib/path-defaults.json');
+  const parsed = JSON.parse(fs.readFileSync(defaultsPath, 'utf8')) as Partial<{ recipeRuntimeDir: string; recipeHarnessRoot: string }>;
+  return {
+    recipeRuntimeDir: validateRelativeRecipePath('recipeRuntimeDir', parsed.recipeRuntimeDir || ''),
+    recipeHarnessRoot: validateRelativeRecipePath('recipeHarnessRoot', parsed.recipeHarnessRoot || ''),
+  };
+}
+
+function validateRelativeRecipePath(name: string, value: string): string {
+  if (!value || path.isAbsolute(value)) throw new Error(`${name} must be a non-empty relative path: ${value}`);
+  if (!/^[A-Za-z0-9._/-]+$/u.test(value)) throw new Error(`${name} contains unsupported characters: ${value}`);
+  for (const part of value.split('/')) {
+    if (!part || part === '.' || part === '..') throw new Error(`${name} contains unsafe path component: ${value}`);
+  }
+  return value;
+}
+
+export function recipeRuntimePath(projectRoot: string, ...segments: string[]) {
+  return path.join(projectRoot, recipeRuntimeDir(), ...segments);
+}
+
+export function recipeHarnessPath(projectRoot: string, ...segments: string[]) {
+  return path.join(projectRoot, recipeHarnessRoot(), ...segments);
+}
+
+export function walletFixturePath(projectRoot: string) {
+  return recipeRuntimePath(projectRoot, 'wallet-fixture.json');
+}
+
+export function extensionIdPath(projectRoot: string) {
+  return recipeRuntimePath(projectRoot, 'extension.id');
+}
+
+export function recipeWatchLogCandidates() {
+  return [
+    path.join(recipeRuntimeDir(), 'webpack.log'),
+    path.join(recipeRuntimeDir(), 'recipe-harness-webpack.log'),
+  ];
+}
+
+export function resolveLocalProtocolRoot() {
+  const candidates = [
+    process.env.FARMSLOT_ROOT,
+    readConfiguredProtocolRoot(),
+    findProtocolRoot(runnerDir),
+    findProtocolRoot(process.cwd()),
+  ].filter(Boolean);
+  const root = candidates[0];
+  return root ? path.resolve(root) : undefined;
+}
+
+export function resolveRequiredLocalProtocolRoot(reason: string) {
+  const root = resolveLocalProtocolRoot();
+  if (!root) {
+    throw new Error(
+      `${reason} requires a local protocol/runtime checkout. Set FARMSLOT_ROOT or create .farmslot-root for this dev-only path.`,
+    );
+  }
+  return root;
+}
+
+function readConfiguredProtocolRoot() {
+  const configPath = path.join(runnerDir, '.farmslot-root');
+  if (!fs.existsSync(configPath)) return undefined;
+  const value = fs.readFileSync(configPath, 'utf8').trim();
+  return value || undefined;
+}
+
+function findProtocolRoot(start) {
+  let dir = path.resolve(start);
+  while (dir !== path.dirname(dir)) {
+    if (isProtocolRoot(dir)) return dir;
+    const sibling = path.join(dir, 'farmslot');
+    if (isProtocolRoot(sibling)) return sibling;
+    dir = path.dirname(dir);
+  }
+  return undefined;
+}
+
+function isProtocolRoot(candidate) {
+  return (
+    fs.existsSync(path.join(candidate, 'packages/recipe-harness/package.json')) &&
+    fs.existsSync(path.join(candidate, 'packages/protocol/package.json'))
+  );
+}
+
+export function assertAdapter(adapter: unknown): asserts adapter is MetaMaskRecipeAdapter {
+  if (adapter !== 'mobile' && adapter !== 'extension' && adapter !== 'core') {
+    throw new Error('Adapter must be mobile, extension, or core.');
+  }
+}
+
+export function manifestPath(adapter: MetaMaskRecipeAdapter) {
+  assertAdapter(adapter);
+  return path.join(runnerDir, 'library/manifests', `${adapter}.action-manifest.json`);
+}
+
+export function recipePath(name: string) {
+  return path.join(runnerDir, 'library/recipes', name);
+}
+
+export function readJson(file: string): unknown {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export async function importRecipeHarness(): Promise<RecipeHarnessModule> {
+  return importProtocolPackage(
+    '@farmslot/recipe-harness',
+    'packages/recipe-harness/src/index.ts',
+  ) as Promise<RecipeHarnessModule>;
+}
+
+export async function importRecipeHarnessRuntimeCdp(): Promise<RecipeHarnessCdpModule> {
+  return importProtocolPackage(
+    '@farmslot/recipe-harness/runtime/cdp',
+    'packages/recipe-harness/src/runtime/cdp.ts',
+  ) as Promise<RecipeHarnessCdpModule>;
+}
+
+export async function importRecipeHarnessRuntimeBrowserExtension(): Promise<RecipeHarnessBrowserExtensionModule> {
+  return importProtocolPackage(
+    '@farmslot/recipe-harness/runtime/browser-extension',
+    'packages/recipe-harness/src/runtime/browser-extension.ts',
+  ) as Promise<RecipeHarnessBrowserExtensionModule>;
+}
+
+export async function importRecipeHarnessRuntimeReactNativeBridge(): Promise<RecipeHarnessReactNativeBridgeModule> {
+  return importProtocolPackage(
+    '@farmslot/recipe-harness/runtime/react-native-bridge',
+    'packages/recipe-harness/src/runtime/react-native-bridge.ts',
+  ) as Promise<RecipeHarnessReactNativeBridgeModule>;
+}
+
+export async function importRecipeHarnessCli(): Promise<{
+  runRecipeHarnessCli: (argv: string[]) => Promise<void>;
+}> {
+  return importProtocolPackage(
+    '@farmslot/recipe-harness/cli',
+    'packages/recipe-harness/src/cli/index.ts',
+  ) as Promise<{ runRecipeHarnessCli: (argv: string[]) => Promise<void> }>;
+}
+
+export async function importRecipeProtocol(): Promise<RecipeProtocolModule> {
+  return importProtocolPackage(
+    '@farmslot/protocol',
+    'packages/protocol/src/index.ts',
+  ) as Promise<RecipeProtocolModule>;
+}
+
+async function importProtocolPackage(packageName: string, localSourceEntry: string) {
+  try {
+    return await import(packageName);
+  } catch (error) {
+    if (!isMissingPackageError(error, packageName)) throw error;
+  }
+
+  const root = resolveLocalProtocolRoot();
+  if (!root) {
+    throw new Error(
+      `${packageName} is not installed. Install @farmslot/* packages normally, or set FARMSLOT_ROOT/use npm run dev:link-farmslot while co-developing protocol packages locally.`,
+    );
+  }
+  return import(pathToFileURL(path.join(root, localSourceEntry)).href);
+}
+
+function isMissingPackageError(error: unknown, packageName: string) {
+  if (!(error instanceof Error)) return false;
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === 'ERR_MODULE_NOT_FOUND' && error.message.includes(packageName);
+}