@deeeed/metamask-harness 0.2.0

package/runner/src/recording-target.ts

@@ -0,0 +1,147 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { RecordingTarget, RecordingTargetContext, RecordingTargetProvider } from '@farmslot/recipe-harness';
+
+import type { MetaMaskRecipeAdapter } from './types.ts';
+
+export function createMetaMaskRecordingTargetProvider(
+  adapter: MetaMaskRecipeAdapter,
+): RecordingTargetProvider {
+  return {
+    async resolveRecordingTarget(context: RecordingTargetContext): Promise<RecordingTarget> {
+      if (adapter === 'extension') {
+        const pid = resolveExtensionBrowserPid(
+          context.projectRoot,
+          context.artifactsDir,
+          context.env.CDP_PORT ?? context.env.RECIPE_CDP_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT,
+        );
+        if (!pid) {
+          throw new Error(
+            'Could not resolve the extension browser PID for --record-video. Ensure the slot browser is running and CDP_PORT is set.',
+          );
+        }
+        return { kind: 'pid', pid };
+      }
+      if (adapter === 'mobile') {
+        const platform = (context.env.PLATFORM ?? process.env.PLATFORM ?? 'ios').trim().toLowerCase();
+        if (platform === 'android' || context.env.ADB_SERIAL || process.env.ADB_SERIAL) {
+          throw new Error('--record-video is not implemented for mobile Android replay yet.');
+        }
+        const simulator = resolveMobileIosSimulatorName(context.env);
+        if (!simulator) {
+          throw new Error(
+            'Could not resolve an iOS simulator name for --record-video. Set IOS_SIMULATOR or pass --simulator to the recipe hook.',
+          );
+        }
+        const pid = resolveMobileIosSimulatorPid(simulator);
+        if (pid) return { kind: 'pid', pid };
+        return { kind: 'app-window', appName: 'Simulator', windowName: simulator };
+      }
+      throw new Error(`--record-video is not implemented for the ${adapter} adapter.`);
+    },
+  };
+}
+
+export function captureHelperSupportsRecordSessionSnapshots(projectRoot: string): boolean {
+  const result = spawnSync(captureHelperPath(), ['version', '--json'], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) return false;
+  try {
+    const parsed = JSON.parse(result.stdout) as { capabilities?: unknown };
+    return Array.isArray(parsed.capabilities) && parsed.capabilities.includes('record_session_snapshot');
+  } catch {
+    return false;
+  }
+}
+
+export function resolveMobileIosSimulatorName(
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): string | undefined {
+  const explicit = env.IOS_SIMULATOR?.trim() || env.SIM_UDID?.trim();
+  if (explicit) return explicit;
+  const slot = env.FARMSLOT_SLOT_ID?.trim() || env.SLOT_ID?.trim();
+  if (!slot) return undefined;
+  const suffix = slot.includes('-') ? slot.slice(slot.lastIndexOf('-') + 1) : slot;
+  return suffix || undefined;
+}
+
+export function resolveMobileIosSimulatorPid(simulator: string): number | null {
+  const result = spawnSync(
+    captureHelperPath(),
+    ['resolve', '--app-name', 'Simulator', '--window-name', simulator, '--json'],
+    { encoding: 'utf8' },
+  );
+  if (result.status !== 0) return null;
+  try {
+    const parsed = JSON.parse(result.stdout) as { selected?: { pid?: unknown } };
+    return parsePositivePid(parsed.selected?.pid);
+  } catch {
+    return null;
+  }
+}
+
+export function resolveExtensionBrowserPid(
+  projectRoot: string,
+  artifactsDir: string,
+  cdpPort: string | undefined,
+): number | null {
+  const explicit = parsePositivePid(process.env.METAMASK_RECIPE_EXTENSION_BROWSER_PID);
+  if (explicit) return explicit;
+  if (cdpPort) {
+    const lsof = spawnSync('lsof', ['-nP', `-iTCP:${cdpPort}`, '-sTCP:LISTEN', '-t'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    });
+    if (lsof.status === 0) {
+      const pid = parsePositivePid(String(lsof.stdout).split(/\s+/u).find(Boolean));
+      if (pid) return pid;
+    }
+  }
+  for (const file of [
+    path.join(artifactsDir, 'extension-runtime/runtime.json'),
+    path.join(projectRoot, 'temp/recipe/runtime/runtime.json'),
+  ]) {
+    const pid = parsePositivePid(readJsonFile(file)?.pid);
+    if (pid) return pid;
+  }
+  for (const file of [
+    path.join(projectRoot, 'temp/recipe/runtime/chromium.pid'),
+    path.join(projectRoot, 'temp/recipe/runtime/browser.pid'),
+  ]) {
+    const pid = parsePositivePid(readTextFile(file));
+    if (pid) return pid;
+  }
+  return null;
+}
+
+function captureHelperPath(): string {
+  return process.env.CAPTURE_HELPER_PATH || 'capture-helper';
+}
+
+function parsePositivePid(value: unknown): number | null {
+  const pid = Number(String(value ?? '').trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function readJsonFile(file: string): Record<string, unknown> | null {
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readTextFile(file: string): string {
+  if (!fs.existsSync(file)) return '';
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}

package/runner/src/run-recording.ts

@@ -0,0 +1,329 @@
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { RecipeRunResult } from '@farmslot/recipe-harness';
+
+import {
+  captureHelperSupportsRecordSessionSnapshots,
+  resolveExtensionBrowserPid,
+} from './recording-target.ts';
+import type { MetaMaskRecipeAdapter } from './types.ts';
+
+export interface RecipeRecordingOptions {
+  record?: boolean;
+  cdpPort?: string;
+}
+
+interface ActiveRecipeRecording {
+  child: ChildProcessWithoutNullStreams;
+  outputPath: string;
+  relativePath: string;
+  pid: number;
+  stdout: string;
+  stderr: string;
+  exited: boolean;
+  exitCode: number | null;
+  error?: Error;
+  stderrBuffer: string;
+  pendingSnapshots: Map<string, PendingRecordingSnapshot>;
+}
+
+interface PendingRecordingSnapshot {
+  outputPath: string;
+  timer: NodeJS.Timeout;
+  resolve: (event: Record<string, unknown>) => void;
+  reject: (error: Error) => void;
+}
+
+const activeRecordingsByPid = new Map<number, ActiveRecipeRecording>();
+
+export async function startRecipeRecording(
+  adapter: MetaMaskRecipeAdapter,
+  projectRoot: string,
+  artifactsDir: string,
+  options: RecipeRecordingOptions,
+): Promise<ActiveRecipeRecording | undefined> {
+  if (!options.record) return undefined;
+  if (process.platform !== 'darwin') {
+    console.error(
+      'WARN: --record uses capture-helper and is currently supported only on macOS; continuing without video.',
+    );
+    return undefined;
+  }
+
+  if (adapter !== 'extension') return undefined;
+
+  const cdpPort = options.cdpPort ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  if (!captureHelperSupportsRecordSessionSnapshots(projectRoot)) {
+    console.error(
+      'WARN: framed extension recording requires capture-helper capability record_session_snapshot; falling back to harness --record-video.',
+    );
+    return undefined;
+  }
+  const pid = resolveExtensionBrowserPid(projectRoot, artifactsDir, cdpPort);
+  if (!pid) {
+    console.error(
+      `WARN: framed extension recording could not resolve browser PID from CDP port ${cdpPort ?? '<unset>'}; falling back to harness --record-video.`,
+    );
+    return undefined;
+  }
+  const recordArgs = ['record', '--framed', '--pid', String(pid)];
+
+  const relativePath = 'videos/full-run.mp4';
+  const outputPath = path.join(artifactsDir, relativePath);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.rmSync(outputPath, { force: true });
+  const child = spawn(captureHelperPath(), [...recordArgs, '--output', outputPath], {
+    cwd: projectRoot,
+    env: process.env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const recording: ActiveRecipeRecording = {
+    child,
+    outputPath,
+    relativePath,
+    pid,
+    stdout: '',
+    stderr: '',
+    exited: false,
+    exitCode: null,
+    stderrBuffer: '',
+    pendingSnapshots: new Map(),
+  };
+  child.stdout.on('data', (chunk) => {
+    recording.stdout += String(chunk);
+  });
+  child.stderr.on('data', (chunk) => {
+    recording.stderr += String(chunk);
+    handleRecordingStderr(recording, String(chunk));
+  });
+  child.on('error', (error) => {
+    recording.error = error;
+    recording.stderr += error.message;
+    recording.exited = true;
+  });
+  child.on('close', (exitCode) => {
+    recording.exited = true;
+    recording.exitCode = exitCode;
+    activeRecordingsByPid.delete(recording.pid);
+    rejectPendingSnapshots(recording, new Error(`capture-helper recording exited before snapshot completed (code=${exitCode ?? 'unknown'})`));
+  });
+
+  await sleep(750);
+  if (recording.exited) {
+    console.error(
+      `WARN: capture-helper record exited before the recipe started (code=${recording.exitCode ?? 'unknown'}): ${recording.stderr || recording.stdout}`,
+    );
+    return undefined;
+  }
+  activeRecordingsByPid.set(pid, recording);
+  console.error(`INFO: recording recipe video with capture-helper pid=${pid} output=${outputPath}`);
+  return recording;
+}
+
+export async function captureActiveRecipeRecordingSnapshot(
+  pid: number,
+  outputPath: string,
+  timeoutMs = 30_000,
+): Promise<Record<string, unknown> | undefined> {
+  const recording = activeRecordingsByPid.get(pid);
+  if (!recording || recording.exited) return undefined;
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.rmSync(outputPath, { force: true });
+  return new Promise<Record<string, unknown>>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      recording.pendingSnapshots.delete(outputPath);
+      reject(new Error(`capture-helper record session snapshot timed out after ${timeoutMs}ms: ${outputPath}`));
+    }, timeoutMs);
+    recording.pendingSnapshots.set(outputPath, { outputPath, timer, resolve, reject });
+    recording.child.stdin.write(`snapshot ${outputPath}\n`, (error) => {
+      if (!error) return;
+      clearTimeout(timer);
+      recording.pendingSnapshots.delete(outputPath);
+      reject(error);
+    });
+  });
+}
+
+export async function stopRecipeRecording(
+  recording: ActiveRecipeRecording | undefined,
+  result?: RecipeRunResult,
+): Promise<void> {
+  if (!recording) return;
+  if (!recording.exited) {
+    recording.child.stdin.end('stop\n');
+    await waitForRecordingExit(recording, 15_000);
+  }
+  if (!recording.exited) {
+    recording.child.kill('SIGINT');
+    await waitForRecordingExit(recording, 5_000);
+  }
+  if (!recording.exited) {
+    recording.child.kill('SIGTERM');
+    await waitForRecordingExit(recording, 3_000);
+  }
+  const validation = validateRecordingArtifact(recording);
+  if (validation.ok === false) {
+    try {
+      fs.rmSync(recording.outputPath, { force: true });
+    } catch (error) {
+      console.error(
+        `WARN: could not remove unusable capture-helper video ${recording.outputPath}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    console.error(
+      `WARN: capture-helper recording did not produce a usable video artifact: ${validation.reason}`,
+    );
+    if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
+    return;
+  }
+  if (result) addRecordingArtifactToManifest(result, recording);
+}
+
+async function waitForRecordingExit(recording: ActiveRecipeRecording, timeoutMs: number): Promise<void> {
+  if (recording.exited) return;
+  await new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, timeoutMs);
+    recording.child.once('close', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+function handleRecordingStderr(recording: ActiveRecipeRecording, chunk: string): void {
+  recording.stderrBuffer += chunk;
+  let newlineIndex = recording.stderrBuffer.indexOf('\n');
+  while (newlineIndex !== -1) {
+    const line = recording.stderrBuffer.slice(0, newlineIndex).trim();
+    recording.stderrBuffer = recording.stderrBuffer.slice(newlineIndex + 1);
+    if (line) handleRecordingEventLine(recording, line);
+    newlineIndex = recording.stderrBuffer.indexOf('\n');
+  }
+}
+
+function handleRecordingEventLine(recording: ActiveRecipeRecording, line: string): void {
+  let event: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return;
+    event = parsed as Record<string, unknown>;
+  } catch {
+    // capture-helper may emit human-readable stderr lines; only JSON event
+    // records are relevant for in-session screenshot correlation.
+    return;
+  }
+  const output = typeof event.output === 'string' ? event.output : undefined;
+  if (!output) return;
+  const pending = recording.pendingSnapshots.get(output);
+  if (!pending) return;
+  if (event.type === 'snapshot') {
+    clearTimeout(pending.timer);
+    recording.pendingSnapshots.delete(output);
+    pending.resolve(event);
+    return;
+  }
+  if (event.type === 'error') {
+    clearTimeout(pending.timer);
+    recording.pendingSnapshots.delete(output);
+    pending.reject(new Error(String(event.message ?? `capture-helper snapshot failed: ${output}`)));
+  }
+}
+
+function rejectPendingSnapshots(recording: ActiveRecipeRecording, error: Error): void {
+  for (const pending of recording.pendingSnapshots.values()) {
+    clearTimeout(pending.timer);
+    pending.reject(error);
+  }
+  recording.pendingSnapshots.clear();
+}
+
+function validateRecordingArtifact(recording: ActiveRecipeRecording): { ok: true } | { ok: false; reason: string } {
+  if (!fs.existsSync(recording.outputPath)) {
+    return { ok: false, reason: `missing output ${recording.outputPath}` };
+  }
+  const size = fs.statSync(recording.outputPath).size;
+  if (size === 0) {
+    return { ok: false, reason: `empty output ${recording.outputPath}` };
+  }
+  const recorderOutput = `${recording.stdout}\n${recording.stderr}`;
+  if (!recorderOutput.includes('record_complete')) {
+    return {
+      ok: false,
+      reason: `capture-helper did not report record_complete for ${recording.outputPath}: ${recorderOutput.trim() || 'no recorder output'}`,
+    };
+  }
+
+  const ffprobe = spawnSync(
+    'ffprobe',
+    ['-hide_banner', '-v', 'error', '-show_entries', 'format=duration', '-of', 'default=noprint_wrappers=1:nokey=1', recording.outputPath],
+    { encoding: 'utf8' },
+  );
+  if (ffprobe.error && (ffprobe.error as NodeJS.ErrnoException).code === 'ENOENT') {
+    return { ok: true };
+  }
+  if (ffprobe.error) {
+    return { ok: false, reason: `ffprobe failed for ${recording.outputPath}: ${ffprobe.error.message}` };
+  }
+  if (ffprobe.status !== 0) {
+    return {
+      ok: false,
+      reason: `invalid MP4 ${recording.outputPath}: ${ffprobe.stderr.trim() || ffprobe.stdout.trim() || `ffprobe exited ${ffprobe.status}`}`,
+    };
+  }
+  const durationSeconds = Number(ffprobe.stdout.trim());
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    return { ok: false, reason: `MP4 has no positive duration: ${recording.outputPath}` };
+  }
+  return { ok: true };
+}
+
+function addRecordingArtifactToManifest(result: RecipeRunResult, recording: ActiveRecipeRecording): void {
+  const manifestPath = result.artifactManifestPath;
+  if (!manifestPath || !fs.existsSync(manifestPath)) {
+    console.error(`WARN: cannot add video artifact to missing artifact manifest: ${manifestPath ?? '<unset>'}`);
+    return;
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as {
+    artifacts?: Array<Record<string, unknown>>;
+  };
+  if (!Array.isArray(manifest.artifacts)) manifest.artifacts = [];
+  manifest.artifacts = manifest.artifacts.filter((artifact) => artifact.path !== recording.relativePath);
+  manifest.artifacts.push({
+    path: recording.relativePath,
+    type: 'video',
+    label: 'Full recipe replay video',
+    category: 'evidence',
+    mimeType: 'video/mp4',
+    record: 'full_run',
+    metadata: {
+      provider: 'capture-helper',
+      mode: 'full_run',
+      pid: recording.pid,
+    },
+  });
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+function removeRecordingArtifactFromManifest(result: RecipeRunResult, relativePath: string): void {
+  const manifestPath = result.artifactManifestPath;
+  if (!manifestPath || !fs.existsSync(manifestPath)) return;
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as {
+    artifacts?: Array<Record<string, unknown>>;
+  };
+  if (!Array.isArray(manifest.artifacts)) return;
+  const nextArtifacts = manifest.artifacts.filter((artifact) => artifact.path !== relativePath);
+  if (nextArtifacts.length === manifest.artifacts.length) return;
+  manifest.artifacts = nextArtifacts;
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+
+function captureHelperPath(): string {
+  return process.env.CAPTURE_HELPER_PATH || 'capture-helper';
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/runner/src/runner.ts

@@ -0,0 +1,108 @@
+import { execSync } from 'node:child_process';
+
+import type { RecipeActionManifestDocument } from '@farmslot/protocol';
+import type { ActionAdapter, RecipeRunner } from '@farmslot/recipe-harness';
+
+import { createMetaMaskAdapters, createMetaMaskUiTransport } from './adapters.ts';
+import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from './manifest.ts';
+import { createMetaMaskRecordingTargetProvider } from './recording-target.ts';
+import { importRecipeHarness, importRecipeHarnessRuntimeCdp, importRecipeHarnessRuntimeReactNativeBridge, runnerDir } from './paths.ts';
+import type { CreateMetaMaskRunnerOptions, MetaMaskRecipeAdapter } from './types.ts';
+
+export async function createMetaMaskMobileRunner(
+  options: CreateMetaMaskRunnerOptions = {},
+): Promise<RecipeRunner> {
+  return createMetaMaskRunner(
+    'mobile',
+    options.actionManifest ?? loadMetaMaskMobileActionManifest(),
+  );
+}
+
+export async function createMetaMaskExtensionRunner(
+  options: CreateMetaMaskRunnerOptions = {},
+): Promise<RecipeRunner> {
+  return createMetaMaskRunner(
+    'extension',
+    options.actionManifest ?? loadMetaMaskExtensionActionManifest(),
+  );
+}
+
+export async function createMetaMaskRunner(
+  adapter: MetaMaskRecipeAdapter,
+  actionManifest: RecipeActionManifestDocument,
+  options: { quietStdout?: boolean } = {},
+): Promise<RecipeRunner> {
+  const {
+    createRecipeRunner,
+    createStandardCoreAdapters,
+    createStandardUiAdapters,
+  } = await importRecipeHarness();
+  const { createCdpWebUiTransport } = await importRecipeHarnessRuntimeCdp();
+  const { createReactNativeBridgeUiTransport } = await importRecipeHarnessRuntimeReactNativeBridge();
+  const actions = [
+    ...actionManifest.supported_official_actions,
+    ...(actionManifest.custom_actions ?? []).map((entry: { name: string }) => entry.name),
+  ];
+  const declaredActions = new Set(actions);
+  const core = createStandardCoreAdapters({ actions });
+  const projectOwnedOfficialActions = new Set(['app.status']);
+  const ui = createStandardUiAdapters({
+    actions: actions.filter((action) => !projectOwnedOfficialActions.has(action)),
+    transport: createMetaMaskUiTransport(adapter, {
+      createCdpWebUiTransport,
+      createReactNativeBridgeUiTransport,
+    }),
+  });
+  const existing = new Set([...core, ...ui].map((entry) => entry.action));
+  const custom: ActionAdapter[] = createMetaMaskAdapters(adapter).filter(
+    (entry) => declaredActions.has(entry.action) && !existing.has(entry.action),
+  );
+  const autoHudDisabled = process.env.METAMASK_RECIPE_AUTO_HUD === '0' || process.env.METAMASK_RECIPE_AUTO_HUD === 'false';
+  // In --json mode stdout is the machine contract; route every engine log
+  // (e.g. the "Recipe libraries: …" resolution line, which uses logger.info →
+  // stdout on the plain console) to stderr so stdout stays parseable JSON.
+  const logger = options.quietStdout ? new console.Console(process.stderr) : console;
+  return createRecipeRunner({
+    actionManifest,
+    adapters: [...core, ...ui, ...custom],
+    logger,
+    recording: {
+      targetProvider: createMetaMaskRecordingTargetProvider(adapter),
+    },
+    runner: runnerProvenance(),
+    hud: autoHudDisabled
+      ? false
+      : {
+          enabled: true,
+          display: {
+            layout: 'docked-bottom',
+            position: 'bottom',
+            showTitle: false,
+            showDebug: false,
+            maxDetailLines: 2,
+          },
+        },
+  });
+}
+
+function runnerProvenance() {
+  return {
+    source: runnerDir,
+    git_ref: runnerGitRef(),
+    name: '@metamask/recipe-runner',
+  };
+}
+
+function runnerGitRef(): string {
+  try {
+    return execSync('git rev-parse HEAD', {
+      cwd: runnerDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    // Standalone packaged runners may be copied without a .git directory; keep
+    // artifact packages valid while source/ref still identifies the runner.
+    return 'unknown';
+  }
+}

package/runner/src/types.ts

@@ -0,0 +1,57 @@
+import type { RecipeActionManifestDocument, RecipeValidationResult } from '@farmslot/protocol';
+
+export type MetaMaskRecipeAdapter = 'mobile' | 'extension' | 'core';
+
+export interface CreateMetaMaskRunnerOptions {
+  actionManifest?: RecipeActionManifestDocument;
+}
+
+export type RecipeHarnessModule = typeof import('@farmslot/recipe-harness');
+export type RecipeHarnessBrowserExtensionModule = typeof import('@farmslot/recipe-harness/runtime/browser-extension');
+export type RecipeHarnessCdpModule = typeof import('@farmslot/recipe-harness/runtime/cdp');
+export type RecipeHarnessReactNativeBridgeModule = typeof import('@farmslot/recipe-harness/runtime/react-native-bridge');
+export type RecipeProtocolModule = typeof import('@farmslot/protocol');
+
+export interface MetaMaskDoctorReport {
+  schemaVersion: 1;
+  protocolVersion: 'v1';
+  runner_protocol_version: 1;
+  status: 'pass' | 'fail';
+  checks: Array<{ id: string; status: 'pass' | 'fail'; message: string }>;
+  adapter: MetaMaskRecipeAdapter;
+  target: string;
+  compatibilityMode:
+    | 'bridge present'
+    | 'injected bridge present'
+    | 'bridge injectable'
+    | 'product-local harness present'
+    | 'runner bridge with injected app bridge'
+    | 'runner bridge with app bridge'
+    | 'runner bridge available; app bridge not installed'
+    | 'headless controller (no bridge)'
+    | 'unsupported/no bridge';
+  runner: {
+    name: '@metamask/recipe-runner';
+    runnerDir: string;
+    actionManifestPath: string;
+    harnessPackage: '@farmslot/recipe-harness';
+  };
+  shape: Record<string, unknown>;
+  fixture: Record<string, unknown>;
+  runtimeContext: MetaMaskRuntimeContextReport;
+  manifestValidation: RecipeValidationResult['summary'] | Record<string, unknown>;
+}
+
+export interface MetaMaskRuntimeContextField {
+  value: string | null;
+  source: 'file' | 'env' | 'default';
+  envVar: string | null;
+  customize: string;
+}
+
+export interface MetaMaskRuntimeContextReport {
+  file: string;
+  fileExists: boolean;
+  envOverride: string | null;
+  fields: Record<string, MetaMaskRuntimeContextField>;
+}