@deeeed/metamask-harness 0.5.1 → 0.6.0

package/src/adapters/mobile/runtime-decision.ts

@@ -1,466 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import {
-  clearDecisionState,
-  depsCheck,
-  recordDepsBaseline,
-  type DepsCheck,
-} from '@farmslot/recipe-harness/runtime/deps-readiness';
-import {
-  analyzeBundleLog,
-  evaluatePersistentBundleError,
-  supersededErrorCapture,
-  type BundleLogAnalysis,
-} from '@farmslot/recipe-harness/runtime/log-analysis';
-import { probeMetroPackager, type MetroReachabilityCheck } from '@farmslot/recipe-harness/runtime/metro-probe';
-
-import { recipeRuntimePath } from '../../paths.ts';
-import { mobileProductMarkers } from './deps-markers.ts';
-
-/**
- * MetaMask Mobile runtime-readiness adapter.
- *
- * Generic deps/log/metro primitives live in `@farmslot/recipe-harness/runtime/*`.
- * This file owns MetaMask-specific markers, Nitro staleness regex, and action ids.
- */
-
-export type MobileReadinessDecision = 'install' | 'launch' | 'ready' | 'blocked' | 'unknown';
-
-export interface MobileRuntimeDecisionAction {
-  id: string;
-  argv?: string[];
-  cwd?: string;
-  paths?: string[];
-}
-
-export type MetroLogCheck = BundleLogAnalysis;
-
-export interface MobileRuntimeDecisionReport {
-  schemaVersion: 1;
-  adapter: 'mobile';
-  target: string;
-  decision: MobileReadinessDecision;
-  reasonCode: string;
-  reasons: string[];
-  // A single teaching escape for the caller's actual situation, set on decisions
-  // the runner deliberately refuses to auto-resolve (e.g. fast-mode deps gaps).
-  userAction?: string;
-  checks: {
-    deps: DepsCheck;
-    metroLog: MetroLogCheck;
-    metro: MetroReachabilityCheck;
-  };
-  actions: MobileRuntimeDecisionAction[];
-}
-
-export interface MobileRuntimeDecisionOptions {
-  watcherPort?: number;
-  metroLog?: string;
-  platform?: string;
-  record?: boolean;
-  // 'fast' (quick launch / no --build) makes deps readiness a presence check only:
-  // freshness is the orchestrator's deps-phase contract, never re-decided here.
-  preflightMode?: string;
-}
-
-const BUNDLE_ERR = /Bundling failed|Unable to resolve /u;
-const BUNDLE_OK = /Bundled \d+ms|iOS Bundled|Android Bundled|Finished bundling/u;
-const NATIVE_MODULE_STALE =
-  /\[runtime not ready\].*HybridObject "([^"]+)" - It has not yet been registered in the Nitro Modules HybridObjectRegistry/u;
-
-// The metro.log location honors RECIPE_RUNTIME_DIR via the shared recipeRuntimePath
-// resolver (relative, validated), so the decision engine reads metro.log from the
-// same per-run dir the mobile leaf scripts write — two jobs sharing one checkout
-// stay isolated. An explicit metroLog override (a --metro-log flag) still wins.
-function resolveMetroLog(target: string, metroLog?: string): string | null {
-  const abs = metroLog
-    ? (path.isAbsolute(metroLog) ? metroLog : path.join(target, metroLog))
-    : recipeRuntimePath(target, 'metro.log');
-  return fs.existsSync(abs) ? abs : null;
-}
-
-// A metro.log is stale when the yarn install markers are newer — a yarn install
-// happened after the last bundle run, so the log describes a now-superseded module
-// tree. Ignoring it lets launch start fresh instead of deciding off stale content.
-function isMetroLogStale(target: string, logAbs: string): boolean {
-  try {
-    const logMtime = fs.statSync(logAbs).mtimeMs;
-    // Check against the same install markers as depsCheck; they are updated by
-    // yarn on every successful install, making them a reliable freshness signal.
-    const INSTALL_MARKERS = ['node_modules/.yarn-state.yml', '.yarn/install-state.gz'];
-    return INSTALL_MARKERS.some((rel) => {
-      try {
-        return logMtime < fs.statSync(path.join(target, rel)).mtimeMs;
-      } catch {
-        return false;
-      }
-    });
-  } catch {
-    return false;
-  }
-}
-
-function metroLogCheck(target: string, metroLog?: string): MetroLogCheck {
-  const abs = resolveMetroLog(target, metroLog);
-  if (!abs) return { status: 'no-log' };
-  if (isMetroLogStale(target, abs)) return { status: 'no-log' };
-  const logText = fs.readFileSync(abs, 'utf8');
-  return analyzeBundleLog({
-    target,
-    logText,
-    errorPattern: BUNDLE_ERR,
-    okPattern: BUNDLE_OK,
-  });
-}
-
-// Returns names of top-level package.json dependencies absent from node_modules.
-// Catches the case where a dep was added in a branch merge but yarn install was not
-// re-run — install markers and fingerprint may both be satisfied while a required
-// package directory is simply missing (real case: 249s Metro bundle discovers it
-// too late).
-function missingRequiredDeps(target: string): string[] {
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(target, 'package.json'), 'utf8')) as {
-      dependencies?: Record<string, unknown>;
-      devDependencies?: Record<string, unknown>;
-    };
-    const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
-    return Object.keys(all).filter(
-      (name) => !fs.existsSync(path.join(target, 'node_modules', name)),
-    );
-  } catch {
-    return [];
-  }
-}
-
-const installActions = (target: string): MobileRuntimeDecisionAction[] => [
-  { id: 'yarn-setup', argv: ['yarn', 'setup'], cwd: target },
-];
-
-// True when a MetaMask dev client process is alive on the target device
-// (IOS_SIMULATOR / ADB_SERIAL, falling back to the booted simulator). Probe
-// failures count as not-running: the worst case is an idempotent relaunch,
-// while failing open would declare a dead app "ready".
-function appRunningOnDevice(platform?: string): boolean {
-  try {
-    if (platform === 'android') {
-      const serial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL;
-      const args = serial ? ['-s', serial] : [];
-      const out = execFileSync('adb', [...args, 'shell', 'ps', '-A'], {
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-        timeout: 5_000,
-      });
-      return out.includes('io.metamask');
-    }
-    const device = process.env.IOS_SIMULATOR || 'booted';
-    const out = execFileSync('xcrun', ['simctl', 'spawn', device, 'launchctl', 'list'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 5_000,
-    });
-    return out.toLowerCase().includes('io.metamask');
-  } catch {
-    return false;
-  }
-}
-
-const launchActions = (target: string, clearMetro = false): MobileRuntimeDecisionAction[] => {
-  const actions: MobileRuntimeDecisionAction[] = [];
-  // start-metro ensures Metro is running; --clear resets the bundle cache.
-  actions.push({
-    id: 'start-metro',
-    argv: clearMetro ? ['--clear'] : [],
-    cwd: target,
-  });
-  // Prewarm the bundle before opening the dev client so the app connects instantly.
-  actions.push({ id: 'prewarm-bundle', cwd: target });
-  // Open the dev client via the expo-development-client deep link.
-  actions.push({ id: 'launch-mobile-runtime' });
-  // Poll the CDP bridge until a route target registers (confirms app is bridged).
-  actions.push({ id: 'wait-for-bridge', cwd: target });
-  return actions;
-};
-
-export async function decideMobileReadiness(
-  target: string,
-  options: MobileRuntimeDecisionOptions = {},
-): Promise<MobileRuntimeDecisionReport> {
-  const resolved = path.resolve(target);
-  if (options.record) recordDepsBaseline(resolved);
-
-  const fast = options.preflightMode === 'fast';
-  const report = await computeMobileReadiness(resolved, options, fast);
-
-  // mtime churn is already neutralized above, so a fast-mode 'install' verdict
-  // means deps genuinely need work (absent markers, an absent required package, a
-  // fingerprint-baseline drift, or Metro unable to resolve a module). In an
-  // orchestrated run the deps phase owns installation; having the runner install
-  // mid-launch is inverted authority. Surface a teaching block, not an implicit
-  // setup, so a runway preflight never re-does the orchestrator's deps work.
-  if (fast && report.decision === 'install') {
-    // A checkout without node_modules cannot even run yarn scripts (yarn exits
-    // with "Couldn't find the node_modules state file"), so the taught command
-    // must lead with the install when that is the caller's actual state.
-    const hasNodeModules = fs.existsSync(path.join(resolved, 'node_modules'));
-    const standalone = hasNodeModules
-      ? '`yarn setup:expo --no-build-ios --no-build-android`'
-      : '`yarn install --immutable && yarn setup:expo --no-build-ios --no-build-android`';
-    return {
-      ...report,
-      decision: 'blocked',
-      reasonCode: 'deps-not-ready',
-      reasons: [
-        'Fast preflight found dependencies not ready and does not install them (the orchestrator deps phase owns installation).',
-        ...report.reasons,
-      ],
-      userAction:
-        `run the slot deps/prepare phase; standalone: ${standalone} in the checkout, then re-run \`mm-harness launch <platform>\``,
-      actions: [],
-    };
-  }
-  return report;
-}
-
-async function computeMobileReadiness(
-  resolved: string,
-  options: MobileRuntimeDecisionOptions,
-  fast: boolean,
-): Promise<MobileRuntimeDecisionReport> {
-  const rawDeps = depsCheck(resolved, {
-    productMarkers: mobileProductMarkers(options.platform),
-  });
-  // Presence is authoritative; mtime is only a hint. Without a recorded baseline
-  // the only way depsCheck reports 'stale' is mtime drift (a manifest newer than
-  // the install markers). In a managed checkout the orchestrator's git phase
-  // refreshes tracked-file mtimes on every sync while its deps phase leaves
-  // node_modules untouched, so "manifest newer than markers" is normal and NOT
-  // proof of drift — treating it as stale re-ran the full yarn setup inside every
-  // launch. Trust the installed node_modules and warn; genuine drift is caught by
-  // the recorded-baseline fingerprint when one exists (hasBaseline=true stays 'stale').
-  let deps: DepsCheck = rawDeps;
-  if (rawDeps.status === 'stale' && !rawDeps.hasBaseline) {
-    deps = { installed: rawDeps.installed, status: 'current', hasBaseline: false };
-    process.stderr.write(
-      '[runtime-decision] manifest is newer than install markers (no recorded baseline); ' +
-        'trusting installed node_modules — run yarn setup manually if deps truly changed.\n',
-    );
-  }
-  // Required-dep absence is a presence check (both modes): a top-level dependency
-  // can be absent from node_modules even when markers + fingerprint report
-  // 'current' (e.g. added in a branch merge but install not re-run). Catch at
-  // pre-flight before Metro discovers it during a long bundle run.
-  if (deps.status === 'current') {
-    const absent = missingRequiredDeps(resolved);
-    if (absent.length > 0) {
-      deps = { installed: deps.installed, status: 'partial', hasBaseline: deps.hasBaseline, missingProducts: absent };
-    }
-  }
-  const metroLog = metroLogCheck(resolved, options.metroLog);
-  const metro = options.watcherPort
-    ? await probeMetroPackager(options.watcherPort)
-    : { status: 'skipped' as const };
-
-  if (metroLog.status === 'ok') {
-    clearDecisionState(resolved, 'bundle-error-state.json');
-  }
-
-  const checks = { deps, metroLog, metro };
-
-  if (deps.status === 'missing') {
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'install',
-      reasonCode: 'deps-missing',
-      reasons: ['Dependencies are not installed (no yarn install-state markers).'],
-      checks,
-      actions: installActions(resolved),
-    };
-  }
-
-  if (deps.status === 'partial') {
-    const missing = deps.missingProducts?.join(', ') ?? 'product markers';
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'install',
-      reasonCode: 'deps-partial',
-      reasons: [`node_modules tree is incomplete (missing: ${missing}).`],
-      checks,
-      actions: installActions(resolved),
-    };
-  }
-
-  if (deps.status === 'stale') {
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'install',
-      reasonCode: 'deps-stale',
-      reasons: ['package.json/yarn.lock changed since the recorded install baseline.'],
-      checks,
-      actions: installActions(resolved),
-    };
-  }
-
-  const metroLogAbs = resolveMetroLog(resolved, options.metroLog);
-  const metroLogText =
-    metroLogAbs && !isMetroLogStale(resolved, metroLogAbs)
-      ? fs.readFileSync(metroLogAbs, 'utf8')
-      : '';
-  const staleNativeModule = supersededErrorCapture(metroLogText, {
-    errorPattern: NATIVE_MODULE_STALE,
-    okPattern: BUNDLE_OK,
-  });
-  if (staleNativeModule) {
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'launch',
-      reasonCode: 'native-module-stale',
-      reasons: [
-        `Installed dev client is missing native module "${staleNativeModule}" (JS deps are current). Rebuild the native app (yarn start:ios / yarn start:android or --preflight-mode rebuild-native).`,
-        'Metro may report a successful bundle while the installed dev client binary predates the native Nitro module link.',
-      ],
-      checks,
-      actions: [
-        { id: 'rebuild-native-dev-client' },
-        ...launchActions(resolved, true),
-      ],
-    };
-  }
-
-  if (metroLog.status === 'errors') {
-    const depsSatisfied = deps.status === 'current';
-    if (
-      depsSatisfied
-      && (metroLog.reason === 'stale-bundle-error'
-        || metroLog.reason === 'bundle-error')
-    ) {
-      const excerpt = metroLog.excerpt ?? '';
-      const persistent = evaluatePersistentBundleError(resolved, excerpt);
-      if (persistent.blocked) {
-        return {
-          schemaVersion: 1,
-          adapter: 'mobile',
-          target: resolved,
-          decision: 'blocked',
-          reasonCode: 'bundle-error-persistent',
-          reasons: [
-            'Metro bundle keeps failing with the same error after a cache-cleared relaunch was already suggested; fix the bundle error in app code before retrying recipe up.',
-            ...(excerpt ? [excerpt] : []),
-          ],
-          checks,
-          actions: [],
-        };
-      }
-      return {
-        schemaVersion: 1,
-        adapter: 'mobile',
-        target: resolved,
-        decision: 'launch',
-        reasonCode: metroLog.reason === 'stale-bundle-error' ? 'metro-stale-log' : 'bundle-errors-recoverable',
-        reasons: [
-          metroLog.reason === 'stale-bundle-error'
-            ? 'Metro log shows prior bundle failures but cited modules are installed; restart Metro with a cleared cache.'
-            : 'Metro bundle is failing with current deps; restart Metro (clear cache) before relaunching the dev client.',
-          ...(excerpt ? [excerpt] : []),
-        ],
-        checks,
-        actions: launchActions(resolved, true),
-      };
-    }
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'install',
-      reasonCode: metroLog.reason === 'unresolved-module' ? 'deps-unresolved-module' : 'bundle-errors',
-      reasons: [
-        metroLog.reason === 'unresolved-module'
-          ? 'Metro cannot resolve modules that are absent from node_modules; run yarn setup.'
-          : 'Metro bundle is failing; reinstall deps or clear Metro cache before retrying.',
-        ...(metroLog.excerpt ? [metroLog.excerpt] : []),
-      ],
-      checks,
-      actions: installActions(resolved),
-    };
-  }
-
-  if (metro.status === 'down') {
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'launch',
-      reasonCode: 'metro-down',
-      reasons: ['Metro is not reachable; start Metro and launch the dev client.'],
-      checks,
-      actions: launchActions(resolved),
-    };
-  }
-
-  if (metroLog.status === 'bundling' || metroLog.status === 'no-log') {
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'launch',
-      reasonCode: metroLog.status === 'bundling' ? 'bundle-in-progress' : 'runtime-cold',
-      reasons: [
-        metroLog.status === 'bundling'
-          ? 'Metro bundle is still in progress; launch or wait for a successful bundle.'
-          : 'No successful Metro bundle recorded; start Metro and launch the dev client.',
-      ],
-      checks,
-      actions: launchActions(resolved),
-    };
-  }
-
-  if (metro.status === 'up' && metroLog.status === 'ok') {
-    // Metro health alone is not runtime readiness: the dev client may be
-    // installed but not running on the target device (launch must launch).
-    // Probe the device before declaring ready; a healthy Metro with a dead
-    // app relaunches the client without touching Metro.
-    if (!appRunningOnDevice(options.platform)) {
-      return {
-        schemaVersion: 1,
-        adapter: 'mobile',
-        target: resolved,
-        decision: 'launch',
-        reasonCode: 'app-not-running',
-        reasons: ['Metro is healthy but the dev client is not running on the target device; launching it.'],
-        checks,
-        actions: launchActions(resolved),
-      };
-    }
-    return {
-      schemaVersion: 1,
-      adapter: 'mobile',
-      target: resolved,
-      decision: 'ready',
-      reasonCode: 'healthy',
-      reasons: ['Dependencies are current, Metro reports a successful bundle, and the dev client is running. Verify bridge before replay.'],
-      checks,
-      actions: [],
-    };
-  }
-
-  return {
-    schemaVersion: 1,
-    adapter: 'mobile',
-    target: resolved,
-    decision: 'launch',
-    reasonCode: 'runtime-unverified',
-    reasons: ['Dependencies are current; start or refresh Metro + dev client before replay.'],
-    checks,
-    actions: launchActions(resolved),
-  };
-}

package/src/adapters/mobile/surface.ts

@@ -1,71 +0,0 @@
-// Mobile surface: delegates to the existing mobile readiness/port plumbing.
-import { spawnSync } from 'node:child_process';
-import path from 'node:path';
-
-import { recipeRuntimePath, runnerDir } from '../../paths.ts';
-import { resolveMobileSlotPorts } from '../slot-ports.ts';
-import { mobileRuntimeStatus } from './prepare.ts';
-import { hasRunwayProvisionBaseline, provisionRunwayMobile } from './provision.ts';
-import type {
-  AdapterDevServerStop,
-  AdapterLogSource,
-  AdapterRuntimeStatus,
-  AdapterRunwayProvisionResult,
-  AdapterSurface,
-} from '../surface.ts';
-
-export const mobileSurface: AdapterSurface = {
-  adapter: 'mobile',
-  headless: false,
-
-  resolveSlotPorts(target: string): void {
-    resolveMobileSlotPorts(target);
-  },
-
-  async runtimeStatus(target: string): Promise<AdapterRuntimeStatus> {
-    const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : undefined;
-    const report = await mobileRuntimeStatus(target, { watcherPort });
-    const runwayProvisioned = hasRunwayProvisionBaseline(target);
-    const depsPending = runwayProvisioned && report.checks?.deps?.status !== 'current';
-    return {
-      decision: depsPending ? 'launch' : report.decision,
-      reasonCode: depsPending ? 'app-installed-deps-pending' : report.reasonCode,
-      reasons: depsPending
-        ? ['Runway app is installed; JavaScript dependencies are pending until dispatch-time launch.']
-        : report.reasons,
-      deps: runwayProvisioned && report.checks?.deps?.status !== 'current' ? 'pending' : report.checks?.deps?.status,
-      devServer: { label: 'metro', status: report.checks?.metro?.status ?? 'unprobed' },
-    };
-  },
-
-  runwayProvision: {
-    async run(target, options): Promise<AdapterRunwayProvisionResult> {
-      return provisionRunwayMobile(target, options) as Promise<AdapterRunwayProvisionResult>;
-    },
-  },
-
-  devServer: {
-    describe: () => 'Metro dev server',
-    stop(target: string): AdapterDevServerStop {
-      const leaf = path.join(runnerDir, 'adapters', 'mobile', 'stop-metro.sh');
-      const args = ['--target', target];
-      if (process.env.WATCHER_PORT) args.push('--port', process.env.WATCHER_PORT);
-      const result = spawnSync('bash', [leaf, ...args], { encoding: 'utf8' });
-      const status = result.status ?? 1;
-      const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
-      const summary = status === 0
-        ? `stopped Metro dev server for ${target}`
-        : `failed to stop Metro for ${target}`;
-      return { kind: 'stopped', status, summary, output };
-    },
-  },
-
-  logSources(target: string): AdapterLogSource[] {
-    return [{ label: 'metro', path: recipeRuntimePath(target, 'metro.log') }];
-  },
-
-  hints: {
-    launch: 'mm-harness launch ios',
-    relaunch: 'mm-harness launch ios',
-  },
-};

package/src/adapters/resolve-farmslot-ports.ts

@@ -1,13 +0,0 @@
-// TypeScript surface for slot-port resolution — delegates to the self-contained core leaf.
-
-export {
-  formatKvLines,
-  inferSlotSuffix,
-  realRepoPath,
-  resolveDefaultExtensionPorts,
-  resolveExtensionRuntimePorts,
-  resolveFarmslotPortsByRepo,
-  resolveMobileRuntimeContext,
-  resolveMobileRuntimePorts,
-  resolveMobileSlotDefaults,
-} from '../../adapters/shared/resolve-farmslot-ports-core.mjs';