@deeeed/metamask-harness 0.2.0

package/runner/src/commands/shared.ts

@@ -0,0 +1,138 @@
+// Shared helpers for the mm-harness command modules: flag parsing, adapter
+// resolution, porcelain composition, and the teaching-error emitter. Each command
+// module (launch/logs/debug/fixtures) composes mobile/extension porcelain scripts
+// that live under orchestration/porcelain/; these helpers are the common seam.
+//
+// Composition seams (overridable for CI/agents and contract tests):
+//   MM_HARNESS_MM_RECIPE_BIN  — mobile porcelain (default: <runner>/orchestration/porcelain/mm-recipe)
+//   MM_HARNESS_MME_RECIPE_BIN — extension porcelain (default: <runner>/orchestration/porcelain/mme-recipe)
+// A stub that records argv against one of these paths is the contract-test lever.
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { detectAdapter } from '../harness.ts';
+import { runnerDir } from '../paths.ts';
+import type { MetaMaskRecipeAdapter } from '../types.ts';
+
+// Exit-code taxonomy (docs/CLI-SPEC.md §5.6).
+export const EXIT = { ok: 0, runtime: 1, usage: 2, infra: 3, bounded: 4, validation: 5 } as const;
+
+// Adapters that launch a live app surface (core is headless).
+export type DeviceAdapter = 'mobile' | 'extension';
+
+export interface ParsedFlags {
+  positional: string[];
+  options: Record<string, string | boolean>;
+}
+
+// Positionals + boolean/valued flags; camelCases --foo-bar to fooBar.
+export function parseFlags(argv: string[], booleans: Set<string>): ParsedFlags {
+  const positional: string[] = [];
+  const options: Record<string, string | boolean> = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+    const body = arg.slice(2);
+    const eq = body.indexOf('=');
+    const rawKey = eq === -1 ? body : body.slice(0, eq);
+    const inline = eq === -1 ? undefined : body.slice(eq + 1);
+    const key = rawKey.replace(/-([a-z])/gu, (_, c: string) => c.toUpperCase());
+    if (booleans.has(key)) {
+      options[key] = inline === undefined ? true : inline !== 'false';
+      continue;
+    }
+    if (inline !== undefined) {
+      options[key] = inline;
+      continue;
+    }
+    // Valued flag with a following token, unless the next token is itself a flag.
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      options[key] = true;
+      continue;
+    }
+    options[key] = next;
+    i += 1;
+  }
+  return { positional, options };
+}
+
+export function str(options: Record<string, string | boolean>, key: string): string | undefined {
+  const value = options[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function flag(options: Record<string, string | boolean>, key: string): boolean {
+  return options[key] === true;
+}
+
+export function targetOf(options: Record<string, string | boolean>): string {
+  return path.resolve(str(options, 'target') ?? str(options, 'projectRoot') ?? process.cwd());
+}
+
+const ADAPTER_TOKENS: readonly string[] = ['mobile', 'extension', 'core'];
+
+// Explicit --adapter/--platform, else an optional hint, else auto-detect from the
+// target. Reimplemented here (rather than shared with cli.ts) to avoid a cycle.
+export function resolveAdapter(
+  options: Record<string, string | boolean>,
+  target: string,
+  hint?: MetaMaskRecipeAdapter,
+): MetaMaskRecipeAdapter | undefined {
+  const explicit = str(options, 'adapter') ?? str(options, 'platform');
+  if (explicit && ADAPTER_TOKENS.includes(explicit)) return explicit as MetaMaskRecipeAdapter;
+  if (hint) return hint;
+  return detectAdapter(target);
+}
+
+function porcelainBin(adapter: DeviceAdapter): string {
+  if (adapter === 'mobile') {
+    return process.env.MM_HARNESS_MM_RECIPE_BIN ?? path.join(runnerDir, 'orchestration', 'porcelain', 'mm-recipe');
+  }
+  return process.env.MM_HARNESS_MME_RECIPE_BIN ?? path.join(runnerDir, 'orchestration', 'porcelain', 'mme-recipe');
+}
+
+export interface PorcelainResult {
+  status: number;
+  output: string;
+}
+
+// Compose the porcelain. Output is always captured (needed for heal
+// classification) and, in human mode, forwarded to our stderr so the human still
+// sees it. --json keeps stdout clean for the machine summary.
+export function spawnPorcelain(
+  adapter: DeviceAdapter,
+  args: string[],
+  target: string,
+  json: boolean,
+): PorcelainResult {
+  const bin = porcelainBin(adapter);
+  const result = spawnSync(bin, args, {
+    cwd: target,
+    encoding: 'utf8',
+    env: process.env,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.error) {
+    return { status: 1, output: `porcelain could not start: ${result.error.message}` };
+  }
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+  if (!json && output) process.stderr.write(output);
+  return { status: result.status ?? 1, output };
+}
+
+// Teaching-error emitter (exit 2, machine-readable in --json).
+export function usageOut(json: boolean, command: string, message: string): number {
+  if (json) {
+    console.log(
+      JSON.stringify({ schemaVersion: 1, command, status: 'fail', exitCode: EXIT.usage, error: { code: 'USAGE', message } }, null, 2),
+    );
+  } else {
+    console.error(`✗ mm-harness ${command}: ${message}`);
+  }
+  return EXIT.usage;
+}

package/runner/src/completions-cache.ts

@@ -0,0 +1,86 @@
+// Dynamic completions cache (module + file format).
+//
+// The DISCOVER layer (actions/flows) is the single source that feeds the agent
+// (compose), the shell (complete), and docs (cheatsheet). Shell completion
+// scripts call the hidden `mm-harness completion-candidates <actions|flows>`
+// command; that command reads/writes this per-checkout cache so tab-completion
+// never blocks the shell on a manifest/library read.
+//
+// Format (per-checkout, git-ignored — lives under the runtime dir):
+//   { version, updatedAt (epoch ms), candidates: { actions?: string[], flows?: string[] } }
+// TTL: short; a stale/missing cache falls back to a live read (never an error).
+// Invalidated on overlay install (`mm-harness install`) — the overlay is what
+// changes the available action/flow vocabulary.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { recipeRuntimePath } from './paths.ts';
+
+export const COMPLETION_CACHE_VERSION = 1;
+// Short TTL: completions must reflect a freshly-installed overlay quickly; a miss
+// is cheap (one manifest read) and never blocks the shell.
+export const COMPLETION_CACHE_TTL_MS = 60_000;
+
+export type CompletionKind = 'actions' | 'flows';
+
+export interface CompletionCache {
+  version: number;
+  updatedAt: number;
+  candidates: Partial<Record<CompletionKind, string[]>>;
+}
+
+export function completionCachePath(projectRoot: string): string {
+  return recipeRuntimePath(projectRoot, '.completion-cache.json');
+}
+
+export function readCompletionCache(projectRoot: string): CompletionCache | undefined {
+  try {
+    const raw = JSON.parse(fs.readFileSync(completionCachePath(projectRoot), 'utf8')) as CompletionCache;
+    if (!raw || raw.version !== COMPLETION_CACHE_VERSION || typeof raw.updatedAt !== 'number') return undefined;
+    return raw;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isCacheFresh(cache: CompletionCache, now: number = Date.now()): boolean {
+  return now - cache.updatedAt < COMPLETION_CACHE_TTL_MS;
+}
+
+// Return cached candidates for a kind when the cache is present + fresh; else
+// undefined (caller does a live read and then writeCompletionCandidates).
+export function readFreshCandidates(
+  projectRoot: string,
+  kind: CompletionKind,
+  now: number = Date.now(),
+): string[] | undefined {
+  const cache = readCompletionCache(projectRoot);
+  if (!cache || !isCacheFresh(cache, now)) return undefined;
+  return cache.candidates[kind];
+}
+
+export function writeCompletionCandidates(
+  projectRoot: string,
+  kind: CompletionKind,
+  candidates: string[],
+): void {
+  const existing = readCompletionCache(projectRoot);
+  const next: CompletionCache = {
+    version: COMPLETION_CACHE_VERSION,
+    updatedAt: Date.now(),
+    candidates: { ...(existing?.candidates ?? {}), [kind]: candidates },
+  };
+  const file = completionCachePath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`);
+}
+
+// Invalidated on overlay install (the overlay defines the action/flow vocabulary).
+export function invalidateCompletionCache(projectRoot: string): void {
+  try {
+    fs.rmSync(completionCachePath(projectRoot));
+  } catch {
+    // Absent cache is the desired post-state; nothing to do.
+  }
+}

package/runner/src/doctor.ts

@@ -0,0 +1,203 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readRuntimeContextField, resolveRuntimeContextPath } from './harness.ts';
+import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from './paths.ts';
+import type {
+  MetaMaskDoctorReport,
+  MetaMaskRecipeAdapter,
+  MetaMaskRuntimeContextField,
+  MetaMaskRuntimeContextReport,
+} from './types.ts';
+
+export function repoShape(target: string): Record<string, unknown> {
+  const exists = (rel) => fs.existsSync(path.join(target, rel));
+  const packageInfo = readPackageInfo(target);
+  const extensionProject =
+    packageInfo.name === 'metamask-crx' ||
+    (exists('app/manifest') && exists('app/scripts') && exists('ui'));
+  const mobileProject =
+    packageInfo.name === 'metamask' && exists('app/core') && (exists('ios') || exists('android'));
+  return {
+    packageName: packageInfo.name,
+    packageJsonStatus: packageInfo.status,
+    packageJsonError: packageInfo.error,
+    extensionProject,
+    mobileProject,
+    agenticService: exists('app/dev-tools/AgenticService/AgenticService.ts'),
+    mobileProductHarness: false,
+    mobileBridgeScript: true,
+    extensionRuntime: exists(`${recipeHarnessRoot()}/extension`),
+    injectedHarness: exists(`${recipeHarnessRoot()}/mobile`) || exists(`${recipeHarnessRoot()}/extension`),
+    walletFixture:
+      exists(`${recipeRuntimeDir()}/wallet-fixture.json`),
+  };
+}
+
+export function compatibilityMode(adapter: MetaMaskRecipeAdapter, target: string) {
+  const shape = repoShape(target);
+  if (adapter === 'core') {
+    return fs.existsSync(path.join(target, 'packages/perps-controller/src/index.ts'))
+      ? 'headless controller (no bridge)'
+      : 'unsupported/no bridge';
+  }
+  if (adapter === 'mobile') {
+    if (shape.injectedHarness && shape.agenticService) return 'runner bridge with injected app bridge';
+    if (shape.agenticService) return 'runner bridge with app bridge';
+    return 'runner bridge available; app bridge not installed';
+  }
+  if (!shape.extensionProject) return 'unsupported/no bridge';
+  if (shape.extensionRuntime || shape.injectedHarness) return 'bridge present';
+  return 'bridge injectable';
+}
+
+function readPackageInfo(target: string) {
+  const packageJsonPath = path.join(target, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return { status: 'missing', name: null, error: null };
+  }
+  try {
+    const data = readJsonObject(packageJsonPath);
+    return {
+      status: 'valid',
+      name: typeof data.name === 'string' ? data.name : null,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      status: 'invalid',
+      name: null,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function fixtureSummary(target: string): Record<string, unknown> {
+  const candidates = [
+    `${recipeRuntimeDir()}/wallet-fixture.json`,
+  ];
+  const rel = candidates.find((candidate) => fs.existsSync(path.join(target, candidate)));
+  if (!rel) return { status: 'missing', path: null };
+  try {
+    const data = readJsonObject(path.join(target, rel));
+    return {
+      status: Array.isArray(data.accounts) && data.accounts.length > 0 ? 'ready' : 'incomplete',
+      path: rel,
+      accountCount: Array.isArray(data.accounts) ? data.accounts.length : 0,
+      hasPassword: typeof data.password === 'string' && data.password.length > 0,
+    };
+  } catch (error) {
+    return { status: 'invalid', path: rel, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// The runtime-context fields the harness hydrates from agentic-runtime.json,
+// each paired with the env var(s) that override the file value and the one-line
+// customize hint. `envVars` lists the harness precedence (first set wins); `envVar`
+// is the canonical name reported. Order matches the contract table (CLI-SPEC.md).
+const RUNTIME_CONTEXT_FIELDS: ReadonlyArray<{
+  key: string;
+  envVars: readonly string[];
+  envVar: string | null;
+  customize: string;
+}> = [
+  { key: 'slotId', envVars: ['RECIPE_SLOT_ID'], envVar: 'RECIPE_SLOT_ID', customize: 'farmslot dispatch writes this' },
+  { key: 'extensionId', envVars: ['RECIPE_HARNESS_EXTENSION_ID'], envVar: 'RECIPE_HARNESS_EXTENSION_ID', customize: 'auto-resolved; edit file to pin' },
+  { key: 'cdpPort', envVars: ['RECIPE_CDP_PORT', 'CDP_PORT'], envVar: 'CDP_PORT', customize: 'edit file or pass --cdp-port' },
+  { key: 'runtimeStart.approved', envVars: ['RECIPE_RUNTIME_START_APPROVED'], envVar: 'RECIPE_RUNTIME_START_APPROVED', customize: 'edit file (true/false)' },
+  { key: 'runtimeStart.command', envVars: [], envVar: null, customize: 'edit file' },
+  { key: 'runtimeStart.readyUrl', envVars: ['RECIPE_RUNTIME_READY_URL'], envVar: 'RECIPE_RUNTIME_READY_URL', customize: 'edit file' },
+];
+
+// Report every runtime-context field with its current value and where it came from
+// (live env override > file > unset default), reusing the harness's own file reader
+// so doctor and dispatch agree on resolution. Absent file → fileExists:false and
+// every field falls back to env or default; the path shows where it WOULD live.
+export function runtimeContextSummary(target: string): MetaMaskRuntimeContextReport {
+  const contextPath = resolveRuntimeContextPath(target);
+  const envOverride = process.env.RECIPE_RUNTIME_CONTEXT ?? null;
+  const fileExists = fs.existsSync(contextPath);
+  const file = envOverride ?? path.relative(target, contextPath);
+  const fields: Record<string, MetaMaskRuntimeContextField> = {};
+  for (const spec of RUNTIME_CONTEXT_FIELDS) {
+    const envValue = spec.envVars
+      .map((name) => process.env[name])
+      .find((value) => value !== undefined && value !== '');
+    if (envValue !== undefined) {
+      fields[spec.key] = { value: envValue, source: 'env', envVar: spec.envVar, customize: spec.customize };
+      continue;
+    }
+    const fileValue = fileExists ? readRuntimeContextField(contextPath, spec.key) : undefined;
+    fields[spec.key] = fileValue !== undefined
+      ? { value: fileValue, source: 'file', envVar: spec.envVar, customize: spec.customize }
+      : { value: null, source: 'default', envVar: spec.envVar, customize: spec.customize };
+  }
+  return { file, fileExists, envOverride, fields };
+}
+
+// Human-readable runtime-context section for `doctor` without --json.
+export function renderRuntimeContext(runtimeContext: MetaMaskRuntimeContextReport): string {
+  const lines: string[] = [];
+  lines.push(
+    runtimeContext.fileExists
+      ? `runtime-context: ${runtimeContext.file} (present)`
+      : `runtime-context: ${runtimeContext.file} (absent — written by farmslot prepare/dispatch)`,
+  );
+  for (const [key, field] of Object.entries(runtimeContext.fields)) {
+    const value = field.value ?? '(unset)';
+    const origin = field.source === 'env' && field.envVar ? `env ${field.envVar}` : field.source;
+    lines.push(`  ${key.padEnd(22)} ${value}  [${origin}] — ${field.customize}`);
+  }
+  return lines.join('\n');
+}
+
+export function createDoctorReport(
+  adapter: MetaMaskRecipeAdapter,
+  target: string,
+  manifestValidation: { summary?: { errors?: number } & Record<string, unknown> },
+  actionManifestPath = manifestPath(adapter),
+): MetaMaskDoctorReport {
+  const mode = compatibilityMode(adapter, target);
+  const manifestErrors = Number(manifestValidation.summary?.errors ?? 0);
+  const status = manifestErrors > 0 ? 'fail' : 'pass';
+  const checks = [
+    {
+      id: 'manifest',
+      status: manifestErrors === 0 ? 'pass' : 'fail',
+      message: manifestErrors === 0 ? 'Action manifest is valid Recipe v1.' : `Action manifest has ${manifestErrors} validation error(s).`,
+    },
+    {
+      id: 'bridge',
+      status: mode === 'unsupported/no bridge' ? 'fail' : 'pass',
+      message: mode === 'unsupported/no bridge' ? `No ${adapter} bridge is available for this checkout.` : `${adapter} compatibility mode: ${mode}.`,
+    },
+  ] as const;
+  return {
+    schemaVersion: 1,
+    protocolVersion: 'v1',
+    runner_protocol_version: 1,
+    status,
+    checks: [...checks],
+    adapter,
+    target,
+    runner: {
+      name: '@metamask/recipe-runner',
+      runnerDir,
+      actionManifestPath,
+      harnessPackage: '@farmslot/recipe-harness',
+    },
+    compatibilityMode: mode,
+    shape: repoShape(target),
+    fixture: fixtureSummary(target),
+    runtimeContext: runtimeContextSummary(target),
+    manifestValidation: manifestValidation.summary,
+  };
+}
+
+function readJsonObject(file: string): Record<string, unknown> {
+  const value = readJson(file);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Expected JSON object in ${file}`);
+  }
+  return value as Record<string, unknown>;
+}