@deeeed/metamask-harness 0.5.0 → 0.6.0

package/src/run-recording.ts

@@ -1,329 +0,0 @@
-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/src/runner.ts

@@ -1,108 +0,0 @@
-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/src/types.ts

@@ -1,57 +0,0 @@
-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>;
-}