@deeeed/metamask-harness 0.5.0 → 0.6.0

package/src/heal-bounds.ts

@@ -1,198 +0,0 @@
-// Healing policy + recovery bounds — shared by launch, run, and call (policy, not
-// per-command). Owns: overlay auto-ensure, failure classification, the recovery
-// bounds that stop blind retry loops, and the --heal parser.
-//
-// Overlay auto-ensure seam (overridable for CI/agents and contract tests):
-//   MM_HARNESS_INSTALL_BIN — overlay installer (default: handleHarness install)
-
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { handleHarness } from './harness.ts';
-import { recipeHarnessPath, recipeRuntimePath } from './paths.ts';
-import type { MetaMaskRecipeAdapter } from './types.ts';
-import { EXIT } from './commands/shared.ts';
-import type { DeviceAdapter } from './commands/shared.ts';
-
-export type HealPolicy = 'off' | 'infra-only' | 'auto';
-
-interface Mutation {
-  type: string;
-  action: string;
-  [key: string]: unknown;
-}
-
-export interface HealState {
-  recovered: string[];
-  mutations: Mutation[];
-  attemptedRecoveries: string[];
-}
-
-export function newHealState(): HealState {
-  return { recovered: [], mutations: [], attemptedRecoveries: [] };
-}
-
-export function parseHeal(
-  options: Record<string, string | boolean>,
-  fallback: HealPolicy,
-): HealPolicy | { error: string } {
-  const value = options.heal;
-  if (value === undefined) return fallback;
-  if (value === 'off' || value === 'infra-only' || value === 'auto') return value;
-  return { error: `--heal must be off, infra-only, or auto (got "${String(value)}").` };
-}
-
-function overlayDir(target: string, adapter: MetaMaskRecipeAdapter): string {
-  return recipeHarnessPath(target, adapter);
-}
-
-function overlayPresent(target: string, adapter: MetaMaskRecipeAdapter): boolean {
-  try {
-    return fs.statSync(overlayDir(target, adapter)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-// Validates that the installed overlay's runner-source stamp points to an existing
-// runner directory whose binary is still present. Two failure modes are detected:
-//   1. Stale stamp — runner dir moved or renamed since install (dir absent).
-//   2. Stale exec target — runner dir exists but its bin/mm-harness was removed
-//      (e.g. the package was unlinked/purged inside an otherwise-live dir).
-// Either way the delegate binary will fail to exec; treat the overlay as absent
-// so auto-ensure re-installs it from the current runner.
-function overlayDelegateValid(target: string, adapter: MetaMaskRecipeAdapter): boolean {
-  if (adapter === 'core') return true;
-  const pointer = path.join(recipeHarnessPath(target, adapter), 'runner', '.runner-source');
-  if (!fs.existsSync(pointer)) return true; // no stamp = running from local runner, valid
-  const runnerPath = fs.readFileSync(pointer, 'utf8').trim();
-  if (!Boolean(runnerPath) || !fs.existsSync(runnerPath)) return false;
-  // Runner dir is present; verify the binary inside still exists — the directory
-  // can survive a package removal while the binary inside is deleted.
-  return fs.existsSync(path.join(runnerPath, 'bin', 'mm-harness'));
-}
-
-// Auto-ensure the runtime overlay (install phase). Missing + heal != off →
-// install inline, emit a first-install notice to stderr, and record the mutation.
-// heal === off disables auto-install (repro-preserving); we proceed and let the
-// porcelain surface any missing-overlay failure itself.
-export async function ensureOverlay(
-  adapter: MetaMaskRecipeAdapter,
-  target: string,
-  heal: HealPolicy,
-  state: HealState,
-  json: boolean,
-): Promise<{ ok: boolean; error?: string }> {
-  // core is headless — the engine path used by run/call needs no launch overlay.
-  if (adapter === 'core') return { ok: true };
-  if (overlayPresent(target, adapter) && overlayDelegateValid(target, adapter)) return { ok: true };
-  if (heal === 'off') return { ok: true };
-
-  const installBin = process.env.MM_HARNESS_INSTALL_BIN;
-  let code: number;
-  if (installBin) {
-    const result = spawnSync(installBin, ['install', '--platform', adapter, '--target', target], {
-      cwd: target,
-      stdio: ['ignore', 2, 'inherit'],
-      env: process.env,
-    });
-    code = result.status ?? 1;
-  } else {
-    code = await handleHarness(['install', '--platform', adapter, '--target', target, ...(json ? ['--json'] : [])]);
-  }
-  if (code !== 0 || !overlayPresent(target, adapter)) {
-    return { ok: false, error: `runtime overlay install failed (exit ${code})` };
-  }
-  const dir = overlayDir(target, adapter);
-  state.mutations.push({ type: 'file', action: 'created', path: dir });
-  // First-install notice → stderr (human) / mutations[] only (json; stdout clean).
-  if (!json) process.stderr.write(`installed mm-harness overlay → ${dir}\n`);
-  return { ok: true };
-}
-
-// A recovery that would need a seeded wallet is NEVER auto-performed (healing
-// never touches fixtures). Only POSITIVELY-IDENTIFIED infra transport failures
-// are healable. Unknown/unclassified failures → 'app' (safe default: no healing
-// attempted, failure surfaced verbatim). Defaulting to 'infra' would cause
-// self-healing to mask real app-logic breakage.
-export function classifyFailure(output: string): 'wallet' | 'infra' | 'app' {
-  if (/wallet|fixture|keyring|not seeded|\bsrp\b|password|onboard/iu.test(output)) return 'wallet';
-  if (/metro|cdp|chrome|bundle|packager|port\b|econnrefused|not reachable|watcher|dev client|websocket/iu.test(output)) {
-    return 'infra';
-  }
-  return 'app';
-}
-
-// Refuse ALL recovery while a recipe is executing (mid-run recovery would corrupt
-// state). Signalled by a lock file or MM_HARNESS_RECIPE_RUNNING=1.
-export function recipeRunning(target: string): boolean {
-  if (process.env.MM_HARNESS_RECIPE_RUNNING === '1') return true;
-  return fs.existsSync(recipeRuntimePath(target, 'recipe.lock'));
-}
-
-// Stable recovery codes for the launch infra retry (surfaced in recovered[]).
-export const RECOVERY_CODE: Record<DeviceAdapter, string> = {
-  mobile: 'metro.restarted',
-  extension: 'chrome.reopened',
-};
-
-export interface HealBoundViolation {
-  code: string;
-  exitCode: number;
-  message: string;
-  userAction?: string;
-  // The ORIGINAL failure output that drove this classification, carried verbatim.
-  // The classification `message` accompanies it — it NEVER replaces it: an
-  // app-logic assertion like "expected balance 10, got 7" must survive so the
-  // human/agent sees the real cause, not just the note.
-  originalError?: string;
-}
-
-// Returns null (ok to proceed) or a violation descriptor when a bound is hit.
-// Using null instead of { ok: true } keeps the return typeof-narrowable without
-// relying on discriminated-union narrowing (avoids strict-mode tsconfig issues).
-export function checkHealBounds(
-  target: string,
-  output: string,
-  state: HealState,
-): HealBoundViolation | null {
-  // Carry the original failure output verbatim on every violation so the caller
-  // can surface it (--json + human) alongside the classification note.
-  const originalError = output.trim() || undefined;
-  if (recipeRunning(target)) {
-    return {
-      code: 'RECIPE_RUNNING',
-      exitCode: EXIT.bounded,
-      message: 'a recipe is currently running — refusing recovery to avoid corrupting mid-run state.',
-      originalError,
-    };
-  }
-  const failureClass = classifyFailure(output);
-  if (failureClass === 'wallet') {
-    return {
-      code: 'WALLET_STATE_REQUIRED',
-      exitCode: EXIT.bounded,
-      message: 'recovery would require a seeded wallet — healing never touches fixtures.',
-      userAction: 'run mm-harness fixtures set',
-      originalError,
-    };
-  }
-  if (failureClass === 'app') {
-    return {
-      code: 'APP_LOGIC_FAILURE',
-      exitCode: EXIT.runtime,
-      message: 'failure looks like app-logic — healing cannot help; surface verbatim.',
-      originalError,
-    };
-  }
-  if (state.attemptedRecoveries.length > 0) {
-    return {
-      code: 'SAME_RECOVERY_TWICE',
-      exitCode: EXIT.bounded,
-      message: 'same recovery already failed once this invocation — refusing to loop.',
-      originalError,
-    };
-  }
-  return null;
-}

package/src/index.ts

@@ -1,15 +0,0 @@
-// Keep the package entrypoint narrow: runner factory, manifest, doctor, and the
-// path/import helpers that library actions are allowed to consume (R9 — no
-// deep-importing src internals past this file).
-export { createDoctorReport } from './doctor.ts';
-export { loadActionManifest, validateManifest } from './manifest.ts';
-export { createMetaMaskExtensionRunner, createMetaMaskMobileRunner, createMetaMaskRunner } from './runner.ts';
-export type { CreateMetaMaskRunnerOptions, MetaMaskDoctorReport, MetaMaskRecipeAdapter } from './types.ts';
-export {
-  extensionIdPath,
-  importRecipeHarnessRuntimeBrowserExtension,
-  importRecipeHarnessRuntimeCdp,
-  recipeHarnessPath,
-  walletFixturePath,
-} from './paths.ts';
-export { captureActiveRecipeRecordingSnapshot } from './run-recording.ts';

package/src/leaf-invoke.ts

@@ -1,28 +0,0 @@
-// Interpreter routing for adapter shell and node leaves.
-import fs from 'node:fs';
-import path from 'node:path';
-
-// Returns the interpreter and args for invoking a leaf. Shell leaves (.sh) run
-// through bash so the file mode does not need to be executable. Node leaves
-// are already invoked through process.execPath by their callers and are
-// returned unchanged.
-export function resolveLeafInvoke(command: string, args: string[]): { bin: string; args: string[] } {
-  if (command.endsWith('.sh')) return { bin: 'bash', args: [command, ...args] };
-  return { bin: command, args };
-}
-
-// Teaching diagnostic for a shell leaf that is absent from disk. Bash exits
-// 127 (not a Node spawn error) for a missing file, so callers pre-check and
-// emit this rather than relying on result.error.
-export function missingShellLeafMessage(leafPath: string): string {
-  const leaf = path.basename(leafPath);
-  return (
-    `leaf could not start: ${leaf} (ENOENT)\n` +
-    `  Next: reinstall mm-harness (npm i -g @deeeed/metamask-harness) — the shell leaf is missing or not executable`
-  );
-}
-
-// Returns true when a .sh leaf path does not exist on disk.
-export function shellLeafMissing(leafPath: string): boolean {
-  return leafPath.endsWith('.sh') && !fs.existsSync(leafPath);
-}

package/src/live-adapter-contract.ts

@@ -1,274 +0,0 @@
-import { access, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import { existsSync, readFileSync } from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { spawn } from 'node:child_process';
-
-import { resolveRequiredLocalProtocolRoot, runnerDir } from './paths.ts';
-
-function actionFileStem(action: string) {
-  return String(action).replace(/[^a-zA-Z0-9._-]/g, '_');
-}
-
-function actionParts(action: string) {
-  const parts = String(action).split('.').filter(Boolean);
-  if (parts.length >= 3 && parts[0] === 'metamask') {
-    return { family: parts[1], localName: parts.slice(2).join('.') };
-  }
-  if (parts.length >= 2) {
-    return { family: parts[0], localName: parts.slice(1).join('.') };
-  }
-  return { family: 'actions', localName: String(action) };
-}
-
-function candidateStems(action: string) {
-  const stem = actionFileStem(action);
-  const { localName } = actionParts(action);
-  const localStem = actionFileStem(localName);
-  const stems = [stem];
-  if (localStem && localStem !== stem) stems.push(localStem);
-  return stems;
-}
-
-function candidateFamilies(action: string) {
-  const { family } = actionParts(action);
-  const families = [family];
-  return [...new Set(families)];
-}
-
-function candidatePaths(platform: string, action: string) {
-  const stems = candidateStems(action);
-  const families = candidateFamilies(action);
-  const roots = [
-    process.env.METAMASK_RECIPE_LIVE_ADAPTER_DIR,
-    path.join(runnerDir, 'library/actions'),
-  ].filter(Boolean);
-  const files = [];
-  for (const root of roots) {
-    for (const family of families) {
-      for (const candidateStem of stems) {
-        pushCandidateFiles(files, root, platform, family, candidateStem);
-      }
-      pushDomainDispatcherFiles(files, root, platform, family);
-    }
-    for (const candidateStem of stems) {
-      pushFlatCandidateFiles(files, root, platform, candidateStem);
-    }
-  }
-  return files;
-}
-
-function pushCandidateFiles(files: string[], root: string, platform: string, family: string, stem: string) {
-  for (const extension of ['mjs', 'js', 'sh']) {
-    files.push(path.join(root, platform, family, `${stem}.${extension}`));
-    files.push(path.join(root, 'shared', family, `${stem}.${extension}`));
-  }
-}
-
-
-function pushDomainDispatcherFiles(files: string[], root: string, platform: string, family: string) {
-  for (const extension of ['mjs', 'js', 'sh']) {
-    files.push(path.join(root, platform, family, `${family}.${extension}`));
-    files.push(path.join(root, 'shared', family, `${family}.${extension}`));
-  }
-}
-
-function pushFlatCandidateFiles(files: string[], root: string, platform: string, stem: string) {
-  for (const extension of ['mjs', 'js', 'sh']) {
-    files.push(path.join(root, platform, `${stem}.${extension}`));
-    files.push(path.join(root, 'shared', `${stem}.${extension}`));
-  }
-}
-
-async function firstExecutablePath(paths: string[]) {
-  for (const file of paths) {
-    try {
-      await access(file);
-      return file;
-    } catch (error) {
-      // Try the next candidate path. Missing optional live adapters are reported by the caller.
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
-    }
-  }
-  return null;
-}
-
-function runProcess(
-  command: string,
-  args: string[],
-  options: { cwd: string; env: NodeJS.ProcessEnv; timeoutMs?: number },
-): Promise<{ exitCode: number | null; stdout: string; stderr: string; timedOut: boolean }> {
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const child = spawn(command, args, {
-      cwd: options.cwd,
-      env: options.env,
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => {
-      stdout += chunk;
-    });
-    child.stderr.on('data', (chunk) => {
-      stderr += chunk;
-    });
-    const timeout = options.timeoutMs
-      ? setTimeout(() => {
-          if (settled) return;
-          settled = true;
-          child.kill('SIGTERM');
-          setTimeout(() => {
-            if (!child.killed) child.kill('SIGKILL');
-          }, 1000);
-          resolve({ exitCode: null, stdout, stderr, timedOut: true });
-        }, options.timeoutMs)
-      : undefined;
-    child.on('error', (error) => {
-      if (settled) return;
-      settled = true;
-      if (timeout) clearTimeout(timeout);
-      reject(error);
-    });
-    child.on('close', (exitCode) => {
-      if (settled) return;
-      settled = true;
-      if (timeout) clearTimeout(timeout);
-      resolve({ exitCode, stdout, stderr, timedOut: false });
-    });
-  });
-}
-
-function commandFor(file: string) {
-  if (file.endsWith('.sh')) return { command: 'bash', args: [file] };
-  if (file.endsWith('.mjs') || file.endsWith('.js')) {
-    if (!importsSourceTypescript(file)) return { command: process.execPath, args: [file] };
-  }
-  const localTsx = path.join(runnerDir, 'node_modules/.bin/tsx');
-  const tsxBin =
-    process.env.TSX_BIN ||
-    (existsSync(localTsx)
-      ? localTsx
-      : path.join(
-          resolveRequiredLocalProtocolRoot('TypeScript live adapter execution'),
-          'node_modules/.bin/tsx',
-        ));
-  return { command: tsxBin, args: [file] };
-}
-
-function importsSourceTypescript(file: string): boolean {
-  return importsSourceTypescriptFrom(file, new Set());
-}
-
-function importsSourceTypescriptFrom(file: string, visited: Set<string>): boolean {
-  const absolute = path.resolve(file);
-  if (visited.has(absolute)) return false;
-  visited.add(absolute);
-  const source = readFileSync(file, 'utf8');
-  const importPattern = /(?:from\s+|import\(\s*)['"]([^'"]+)['"]/gu;
-  for (const match of source.matchAll(importPattern)) {
-    const specifier = match[1] ?? '';
-    if (specifier.endsWith('.ts')) return true;
-    if (!specifier.startsWith('.')) continue;
-    if (!specifier.endsWith('.mjs') && !specifier.endsWith('.js')) continue;
-    if (importsSourceTypescriptFrom(path.resolve(path.dirname(absolute), specifier), visited)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-export async function resolveLiveAdapter(platform: string, action: string) {
-  return firstExecutablePath(candidatePaths(platform, action));
-}
-
-// Workspace packages the headless core adapter imports as runtime values. In an
-// unbuilt MetaMask/core checkout these have no dist/, so their package "exports"
-// (which point only at dist) cannot resolve. We point tsx at the package src via
-// a generated tsconfig paths map so the adapter can import the controller without
-// building or modifying the core checkout.
-const CORE_WORKSPACE_PACKAGES = [
-  '@metamask/base-controller',
-  '@metamask/messenger',
-  '@metamask/controller-utils',
-  '@metamask/keyring-controller',
-];
-
-async function platformAdapterEnv(
-  platform: string,
-  projectRoot: string,
-  tempDir: string,
-): Promise<NodeJS.ProcessEnv> {
-  if (platform !== 'core') return {};
-  const paths: Record<string, string[]> = {};
-  for (const pkg of CORE_WORKSPACE_PACKAGES) {
-    const packageDir = path.join(projectRoot, 'packages', pkg.replace('@metamask/', ''));
-    const distEntry = path.join(packageDir, 'dist/index.cjs');
-    if (existsSync(distEntry)) continue; // built package resolves normally
-    const srcDir = path.join(packageDir, 'src');
-    if (!existsSync(path.join(srcDir, 'index.ts'))) continue;
-    paths[pkg] = [path.join(srcDir, 'index.ts')];
-    paths[`${pkg}/*`] = [path.join(srcDir, '*')];
-  }
-  if (Object.keys(paths).length === 0) return {};
-  const tsconfigPath = path.join(tempDir, 'core-adapter.tsconfig.json');
-  await writeFile(
-    tsconfigPath,
-    `${JSON.stringify({ compilerOptions: { baseUrl: projectRoot, paths } }, null, 2)}\n`,
-  );
-  return { TSX_TSCONFIG_PATH: tsconfigPath };
-}
-
-export async function runLiveAdapterScript({ platform, action, node, context }: { platform: string; action: string; node: Record<string, any>; context: any }) {
-  const script = await resolveLiveAdapter(platform, action);
-  if (!script) return null;
-
-  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'mm-harness-live-adapter-'));
-  const inputPath = path.join(tempDir, 'input.json');
-  const outputPath = path.join(tempDir, 'output.json');
-  const input = {
-    schemaVersion: 1,
-    platform,
-    action,
-    node,
-    context: {
-      nodeId: context.nodeId,
-      projectRoot: context.projectRoot,
-      artifactsDir: context.artifactsDir,
-    },
-    outputPath,
-  };
-  await writeFile(inputPath, `${JSON.stringify(input, null, 2)}\n`);
-  const command = commandFor(script);
-  const platformEnv = await platformAdapterEnv(platform, context.projectRoot, tempDir);
-  const result = await runProcess(command.command, [...command.args, inputPath], {
-    cwd: context.projectRoot,
-    env: {
-      ...process.env,
-      ...context.env,
-      ...platformEnv,
-      METAMASK_RECIPE_ADAPTER_INPUT: inputPath,
-      METAMASK_RECIPE_ADAPTER_OUTPUT: outputPath,
-    },
-    timeoutMs: Number(node.live_adapter_timeout_ms ?? node.timeout_ms ?? 60000),
-  });
-  try {
-    if (result.timedOut) {
-      throw new Error(`Live adapter ${script} timed out after ${Number(node.live_adapter_timeout_ms ?? node.timeout_ms ?? 60000)}ms.`);
-    }
-    if (result.exitCode !== 0) {
-      throw new Error(`Live adapter ${script} exited ${result.exitCode}: ${result.stderr || result.stdout}`);
-    }
-    let parsed = null;
-    try {
-      parsed = JSON.parse(await readFile(outputPath, 'utf8'));
-    } catch (_error) {
-      const stdout = result.stdout.trim();
-      if (!stdout) throw new Error(`Live adapter ${script} did not write JSON output.`);
-      parsed = JSON.parse(stdout);
-    }
-    return { script, result: parsed };
-  } finally {
-    await rm(tempDir, { recursive: true, force: true });
-  }
-}

package/src/manifest.ts

@@ -1,47 +0,0 @@
-import path from 'node:path';
-
-import type { RecipeActionManifestDocument, RecipeValidationResult } from '@farmslot/protocol';
-
-import { manifestPath, readJson, importRecipeProtocol } from './paths.ts';
-import type { MetaMaskRecipeAdapter } from './types.ts';
-
-export function loadMetaMaskMobileActionManifest(): RecipeActionManifestDocument {
-  return asActionManifest(readJson(manifestPath('mobile')));
-}
-
-export function loadMetaMaskExtensionActionManifest(): RecipeActionManifestDocument {
-  return asActionManifest(readJson(manifestPath('extension')));
-}
-
-export function loadMetaMaskCoreActionManifest(): RecipeActionManifestDocument {
-  return asActionManifest(readJson(manifestPath('core')));
-}
-
-export function loadActionManifest(
-  adapter: MetaMaskRecipeAdapter,
-  overridePath?: string,
-): RecipeActionManifestDocument {
-  if (overridePath) return asActionManifest(readJson(path.resolve(overridePath)));
-  if (adapter === 'mobile') return loadMetaMaskMobileActionManifest();
-  if (adapter === 'core') return loadMetaMaskCoreActionManifest();
-  return loadMetaMaskExtensionActionManifest();
-}
-
-export async function validateManifest(
-  manifest: RecipeActionManifestDocument,
-): Promise<RecipeValidationResult> {
-  const { validateRecipeActionManifestDocument } = await importRecipeProtocol();
-  const result = validateRecipeActionManifestDocument(manifest);
-  if (result.status === 'invalid') {
-    throw new Error(
-      `Manifest invalid: ${result.findings
-        .map((finding) => `${finding.code} ${finding.path}`)
-        .join(', ')}`,
-    );
-  }
-  return result;
-}
-
-function asActionManifest(value: unknown): RecipeActionManifestDocument {
-  return value as RecipeActionManifestDocument;
-}