@deeeed/metamask-harness 0.2.0 → 0.3.1

package/src/adapters/mobile/prepare.ts

@@ -0,0 +1,210 @@
+// Mobile runtime prepare — in-process decision-and-action loop.
+//
+// Replaces the retired shell orchestrators (prepare-device.sh + launch.sh).
+// All sequencing is in TypeScript; leaf shell scripts handle single OS ops.
+// Control flows down only: TS → adapters/mobile/{yarn-setup,start-metro,open-device}.sh
+// No leaf script may call back into mm-harness (A1).
+
+import path from 'node:path';
+
+import { EXIT, spawnScript } from '../../commands/shared.ts';
+import type { ScriptResult } from '../../commands/shared.ts';
+import { runnerDir } from '../../paths.ts';
+import {
+  decideMobileReadiness,
+  type MobileRuntimeDecisionReport,
+  type MobileRuntimeDecisionOptions,
+} from './runtime-decision.ts';
+
+export { type MobileRuntimeDecisionReport };
+
+export interface PrepareMobileOptions extends MobileRuntimeDecisionOptions {
+  /** Pass through to leaf-script spawnScript calls so output is suppressed in --json mode. */
+  json?: boolean;
+  /**
+   * Passed to open-device.sh --preflight-mode.
+   * 'fast' = error if not installed; 'auto' = install if missing; 'rebuild-native'/'clean' = always rebuild.
+   * Defaults to 'fast'.
+   */
+  preflightMode?: string;
+  /**
+   * Force --clear on start-metro (reset bundle cache).
+   * Used by the setup-wallet clean-Metro retry path (M3).
+   */
+  clearMetro?: boolean;
+}
+
+/**
+ * Read current runtime readiness without executing any action.
+ * No side effects: just calls decideMobileReadiness and returns the report.
+ */
+export async function mobileRuntimeStatus(
+  target: string,
+  opts: PrepareMobileOptions = {},
+): Promise<MobileRuntimeDecisionReport> {
+  return decideMobileReadiness(target, {
+    watcherPort: opts.watcherPort,
+    metroLog: opts.metroLog,
+    platform: opts.platform,
+    record: opts.record,
+  });
+}
+
+/**
+ * Prepare the mobile runtime: run the readiness decision then execute each
+ * action in sequence via single-purpose leaf shell scripts. Returns a
+ * ScriptResult so the launch heal loop can classify outcomes uniformly.
+ */
+export async function prepareMobile(
+  target: string,
+  opts: PrepareMobileOptions = {},
+): Promise<ScriptResult> {
+  const json = opts.json ?? false;
+  const platform = opts.platform ?? 'ios';
+  const preflightMode = opts.preflightMode ?? 'fast';
+  const clearMetro = opts.clearMetro ?? false;
+
+  const report = await decideMobileReadiness(target, {
+    watcherPort: opts.watcherPort,
+    metroLog: opts.metroLog,
+    platform,
+    record: opts.record,
+  });
+
+  if (report.decision === 'blocked') {
+    const reasons = report.reasons.join(' ');
+    const msg = `mobile prepare blocked: ${reasons}\n  Next: fix the bundle error in app code before retrying recipe up.`;
+    if (!json) process.stderr.write(`${msg}\n`);
+    return { status: EXIT.runtime, output: msg };
+  }
+
+  if (report.decision === 'ready') {
+    return { status: 0, output: '' };
+  }
+
+  if (report.decision === 'unknown') {
+    const msg = 'mobile prepare: runtime state unknown\n  Next: run mm-harness verify --adapter mobile --target <checkout>';
+    if (!json) process.stderr.write(`${msg}\n`);
+    return { status: EXIT.runtime, output: msg };
+  }
+
+  // decision is 'install' or 'launch' — execute each action in sequence.
+  // clearMetro forces --clear on start-metro regardless of what decideMobileReadiness set.
+  const actions = clearMetro
+    ? report.actions.map((a) =>
+        a.id === 'start-metro' && !a.argv?.includes('--clear')
+          ? { ...a, argv: [...(a.argv ?? []), '--clear'] }
+          : a,
+      )
+    : report.actions;
+  for (const action of actions) {
+    const result = dispatchAction(action, target, platform, json, preflightMode);
+    if (result.status !== 0) return result;
+  }
+
+  // After install: re-decide and run appropriate actions.
+  // RECIPE_UP_INSTALL_ATTEMPTED guards against infinite loops if yarn-setup was a no-op.
+  if (report.decision === 'install' && !process.env['RECIPE_UP_INSTALL_ATTEMPTED']) {
+    process.env['RECIPE_UP_INSTALL_ATTEMPTED'] = '1';
+    const postInstall = await decideMobileReadiness(target, {
+      watcherPort: opts.watcherPort,
+      metroLog: opts.metroLog,
+      platform,
+      record: true,
+    });
+    switch (postInstall.decision) {
+      case 'install': {
+        // Yarn setup ran but runtime is still unresolved — teach and fail.
+        const msg =
+          `mobile prepare: dependencies installed but runtime is still unresolved ` +
+          `(${postInstall.reasons.join('; ')})\n` +
+          `  Next: inspect the checkout — node_modules may be incomplete or yarn.lock drifted.`;
+        if (!json) process.stderr.write(`${msg}\n`);
+        return { status: EXIT.runtime, output: msg };
+      }
+      case 'ready': {
+        // Deps resolved and runtime appears ready — still confirm bridge is live.
+        const bridge = dispatchAction({ id: 'wait-for-bridge', cwd: target }, target, platform, json, preflightMode);
+        if (bridge.status !== 0) return bridge;
+        break;
+      }
+      case 'launch': {
+        for (const action of postInstall.actions) {
+          const result = dispatchAction(action, target, platform, json, preflightMode);
+          if (result.status !== 0) return result;
+        }
+        break;
+      }
+      default: {
+        // 'blocked' or 'unknown' after install — surface as error.
+        const msg =
+          `mobile prepare: post-install state is ${postInstall.decision}: ${postInstall.reasons.join('; ')}\n` +
+          `  Next: run mm-harness verify --adapter mobile --target <checkout>`;
+        if (!json) process.stderr.write(`${msg}\n`);
+        return { status: EXIT.runtime, output: msg };
+      }
+    }
+  }
+
+  return { status: 0, output: '' };
+}
+
+function dispatchAction(
+  action: { id: string; argv?: string[]; cwd?: string },
+  target: string,
+  platform: string,
+  json: boolean,
+  preflightMode = 'fast',
+): ScriptResult {
+  const cwd = action.cwd ?? target;
+  switch (action.id) {
+    case 'yarn-setup': {
+      // Leaf: install node_modules (deps missing or stale).
+      const leaf = path.join(runnerDir, 'adapters/mobile/yarn-setup.sh');
+      return spawnScript(leaf, ['--target', cwd], target, json);
+    }
+    case 'start-metro': {
+      // Leaf: ensure Metro is running; argv may carry --clear for cache reset.
+      const leaf = path.join(runnerDir, 'adapters/mobile/start-metro.sh');
+      const extra: string[] = action.argv ?? [];
+      return spawnScript(leaf, ['--target', cwd, ...extra], target, json);
+    }
+    case 'prewarm-bundle': {
+      // Leaf: curl the bundle URL before opening the dev client.
+      const leaf = path.join(runnerDir, 'adapters/mobile/prewarm-bundle.sh');
+      return spawnScript(leaf, ['--platform', platform, '--target', cwd], target, json);
+    }
+    case 'wait-for-bridge': {
+      // Leaf: poll CDP bridge until a route target registers.
+      const leaf = path.join(runnerDir, 'adapters/mobile/wait-for-bridge.sh');
+      return spawnScript(leaf, ['--target', cwd], target, json);
+    }
+    case 'clear-metro-cache': {
+      // Legacy alias for start-metro --clear (kept for backward compat).
+      const leaf = path.join(runnerDir, 'adapters/mobile/start-metro.sh');
+      return spawnScript(leaf, ['--target', cwd, '--clear'], target, json);
+    }
+    case 'launch-mobile-runtime': {
+      // Leaf: open the MetaMask Mobile dev client on the simulator/device.
+      const leaf = path.join(runnerDir, 'adapters/mobile/open-device.sh');
+      return spawnScript(
+        leaf,
+        ['--platform', platform, '--target', cwd, '--preflight-mode', preflightMode],
+        target,
+        json,
+      );
+    }
+    case 'rebuild-native-dev-client': {
+      // Native rebuild required — the dev client binary predates a native Nitro
+      // module. Inform the caller; a full native build is not automated here.
+      const msg =
+        'rebuild-native-dev-client required: native module mismatch detected.\n' +
+        '  Next: yarn start:ios or yarn start:android to rebuild the native dev client, ' +
+        'then re-run mm-harness launch.';
+      if (!json) process.stderr.write(`${msg}\n`);
+      return { status: EXIT.runtime, output: msg };
+    }
+    default:
+      return { status: 0, output: '' };
+  }
+}

package/{orchestration → src/adapters}/mobile/runtime-decision.ts

@@ -68,9 +68,31 @@ function resolveMetroLog(target: string, metroLog?: string): string | null {
   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,
@@ -80,16 +102,72 @@ function metroLogCheck(target: string, metroLog?: string): MetroLogCheck {
   });
 }
 
+// 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 [];
+  }
+}
+
+// Returns true when any manifest input (package.json or yarn.lock) is newer than
+// the install markers written by yarn on a successful install. A reliable signal
+// that deps changed since the last install, even when depsCheck found no recorded
+// baseline drift (e.g. git checkout preserved an old author-date mtime on the
+// manifest, then a new dep was committed, making the manifest newer than markers).
+function depsStaleByMtime(target: string): boolean {
+  // Use the same install markers as depsCheck: the files yarn writes on install.
+  const INSTALL_MARKERS = ['node_modules/.yarn-state.yml', '.yarn/install-state.gz'];
+  let markerMtime = 0;
+  for (const rel of INSTALL_MARKERS) {
+    try {
+      const mt = fs.statSync(path.join(target, rel)).mtimeMs;
+      if (mt > markerMtime) markerMtime = mt;
+    } catch {
+      // marker absent; keep searching
+    }
+  }
+  if (markerMtime === 0) return false; // no markers → depsCheck already handles via 'missing'
+  for (const file of ['package.json', 'yarn.lock']) {
+    try {
+      if (fs.statSync(path.join(target, file)).mtimeMs > markerMtime) return true;
+    } catch {
+      // manifest absent; skip
+    }
+  }
+  return false;
+}
+
 const installActions = (target: string): MobileRuntimeDecisionAction[] => [
   { id: 'yarn-setup', argv: ['yarn', 'setup'], cwd: target },
 ];
 
 const launchActions = (target: string, clearMetro = false): MobileRuntimeDecisionAction[] => {
   const actions: MobileRuntimeDecisionAction[] = [];
-  if (clearMetro) {
-    actions.push({ id: 'clear-metro-cache', argv: ['yarn', 'expo', 'start', '--clear'], cwd: target });
-  }
+  // 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;
 };
 
@@ -100,9 +178,28 @@ export async function decideMobileReadiness(
   const resolved = path.resolve(target);
   if (options.record) recordDepsBaseline(resolved);
 
-  const deps = depsCheck(resolved, {
+  const rawDeps = depsCheck(resolved, {
     productMarkers: mobileProductMarkers(options.platform),
   });
+  // Mtime-based fallback: when depsCheck found no recorded baseline, supplement
+  // with a direct mtime comparison — if package.json or yarn.lock is newer than
+  // node_modules, a dep change landed after the last install. Fail fast at
+  // pre-flight rather than launching a doomed Metro bundle. Skip when a baseline
+  // was found (hasBaseline=true) so fingerprint-verified 'current' is trusted.
+  let deps: DepsCheck =
+    rawDeps.status === 'current' && !rawDeps.hasBaseline && depsStaleByMtime(resolved)
+      ? { installed: rawDeps.installed, status: 'stale', hasBaseline: rawDeps.hasBaseline }
+      : rawDeps;
+  // Required-dep absence: even when fingerprint + mtime reports 'current', a
+  // top-level dependency could be absent from node_modules (e.g. added in a
+  // branch merge but install not re-run). Catch at pre-flight before Metro
+  // discovers it during a 249s 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)
@@ -155,7 +252,10 @@ export async function decideMobileReadiness(
   }
 
   const metroLogAbs = resolveMetroLog(resolved, options.metroLog);
-  const metroLogText = metroLogAbs ? fs.readFileSync(metroLogAbs, 'utf8') : '';
+  const metroLogText =
+    metroLogAbs && !isMetroLogStale(resolved, metroLogAbs)
+      ? fs.readFileSync(metroLogAbs, 'utf8')
+      : '';
   const staleNativeModule = supersededErrorCapture(metroLogText, {
     errorPattern: NATIVE_MODULE_STALE,
     okPattern: BUNDLE_OK,

package/{runner/src → src}/adapters.ts

@@ -2,8 +2,8 @@ import http from 'node:http';
 import path from 'node:path';
 import { compatibilityMode, fixtureSummary, repoShape } from './doctor.ts';
 import { runLiveAdapterScript } from './live-adapter-contract.ts';
-import { withExtensionPage } from '../../library/actions/extension/platform/cdp.mjs';
-import { bridgeCommand, evalSync, simulatorScreenshot } from '../../library/actions/mobile/platform/bridge.mjs';
+import { withExtensionPage } from '../library/actions/extension/platform/cdp.mjs';
+import { bridgeCommand, evalSync, simulatorScreenshot } from '../library/actions/mobile/platform/bridge.mjs';
 import type {
   ActionAdapter,
   ActionExecutionContext,
@@ -284,7 +284,7 @@ function mobileProbeOutput(status: unknown, input: MetaMaskUiActionInput, projec
 }
 
 function mobileBridgePath(_projectRoot: string): string {
-  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || 'runner:library/actions/mobile/bridge-runtime/cdp-bridge.cjs';
+  return process.env.METAMASK_RECIPE_MOBILE_BRIDGE_SCRIPT || 'runner:adapters/mobile/bridge-runtime/cdp-bridge.cjs';
 }
 
 async function waitForMobileTarget(input: ReturnType<typeof uiInputFor>, payload: ActionNode) {

package/{orchestration/lib/cli-color.mjs → src/cli-color.ts}

@@ -1,11 +1,14 @@
-#!/usr/bin/env node
 /**
- * cli-color.mjs — shared ANSI styling for recipe CLI human output.
+ * cli-color.ts — shared ANSI styling for recipe CLI human output.
  *
  * Honors NO_COLOR, RECIPE_NO_COLOR, FORCE_COLOR, RECIPE_COLOR, and TTY detection.
  */
 
-const STYLES = {
+type StyleName =
+  | 'reset' | 'bold' | 'dim' | 'label' | 'cmd' | 'ok' | 'warn'
+  | 'err' | 'info' | 'accent' | 'path' | 'comment' | 'active';
+
+const STYLES: Record<StyleName, string> = {
   reset: '\x1b[0m',
   bold: '\x1b[1m',
   dim: '\x1b[2m',
@@ -21,32 +24,37 @@ const STYLES = {
   active: '\x1b[1m',
 };
 
-export function colorEnabled(stream = process.stderr) {
+export function colorEnabled(stream: NodeJS.WriteStream = process.stderr): boolean {
   if (process.env.NO_COLOR != null && process.env.NO_COLOR !== '' && process.env.NO_COLOR !== '0') {
     return false;
   }
   if (process.env.RECIPE_NO_COLOR === '1') return false;
   if (process.env.RECIPE_COLOR === '1' || process.env.FORCE_COLOR === '1') return true;
-  return Boolean(stream?.isTTY);
+  return Boolean((stream as NodeJS.WriteStream & { isTTY?: boolean })?.isTTY);
 }
 
-export function stripAnsi(text) {
+export function stripAnsi(text: string): string {
   return String(text).replace(/\x1b\[[0-9;]*m/gu, '');
 }
 
-export function color(style, text, { stream = process.stderr } = {}) {
+export function color(style: string, text: string, { stream = process.stderr }: { stream?: NodeJS.WriteStream } = {}): string {
   const value = String(text);
   if (!colorEnabled(stream)) return value;
-  const code = STYLES[style];
+  const code = STYLES[style as StyleName];
   if (!code) return value;
   return `${code}${value}${STYLES.reset}`;
 }
 
-export function colorKv(label, value, valueStyle = 'info', { stream = process.stderr } = {}) {
+export function colorKv(
+  label: string,
+  value: string,
+  valueStyle = 'info',
+  { stream = process.stderr }: { stream?: NodeJS.WriteStream } = {},
+): string {
   return `${color('label', `${label}:`, { stream })} ${color(valueStyle, value, { stream })}`;
 }
 
-export function colorStatusWord(word, { stream = process.stderr } = {}) {
+export function colorStatusWord(word: string, { stream = process.stderr }: { stream?: NodeJS.WriteStream } = {}): string {
   const normalized = String(word || '').toLowerCase();
   if (['up', 'ready', 'yes', 'pass', 'running', 'present', 'healthy'].includes(normalized)) {
     return color('ok', word, { stream });
@@ -60,7 +68,7 @@ export function colorStatusWord(word, { stream = process.stderr } = {}) {
   return color('info', word, { stream });
 }
 
-export function classifyLogEvent(event) {
+export function classifyLogEvent(event: string): string {
   const text = String(event || '');
   if (/Module build failed|^ERROR in |BUILD FAILED|compiled with [1-9][0-9]* error/iu.test(text)) {
     return 'err';
@@ -77,8 +85,8 @@ export function classifyLogEvent(event) {
   return 'info';
 }
 
-export function colorLogEvent(event, { latest = false, stream = process.stderr } = {}) {
+export function colorLogEvent(event: string, { latest = false, stream = process.stderr }: { latest?: boolean; stream?: NodeJS.WriteStream } = {}): string {
   const style = classifyLogEvent(event);
   const painted = color(style === 'label' ? 'label' : style, event, { stream });
   return latest ? color('active', painted, { stream }) : painted;
-}
+}