@deeeed/metamask-harness 0.5.0 → 0.6.0

package/src/adapters/mobile/prepare.ts

@@ -1,246 +0,0 @@
-// 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 { recordDepsBaseline } from '@farmslot/recipe-harness/runtime/deps-readiness';
-
-import { EXIT, spawnScriptStreaming } 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 };
-
-// Pod install (run by `yarn setup` and by the native `yarn start:ios|android`
-// build) shells `node --print require.resolve('react-native-worklets-core')` and
-// treats any output other than the exact string `undefined` as "module found".
-// An inherited FORCE_COLOR makes node emit a colorized `undefined`, so VisionCamera
-// misdetects the worklets pod, enables FrameProcessors, and fails on the missing
-// pod. Force plain output for pod-triggering spawns so the probe reads `undefined`.
-// CocoaPods reads UTF-8 podspecs; a parent env without a locale (gateway/tmux
-// spawns) makes Ruby parse them as US-ASCII and die on the first multibyte byte
-// ('"\xE2" on US-ASCII' in react-native-mmkv.podspec). Pin a UTF-8 locale for
-// pod-triggering spawns when the caller has none.
-const POD_PROBE_ENV: Record<string, string> = {
-  FORCE_COLOR: '0',
-  NO_COLOR: '1',
-  LANG: process.env.LANG?.includes('UTF-8') ? process.env.LANG : 'en_US.UTF-8',
-  LC_ALL: process.env.LC_ALL?.includes('UTF-8') ? process.env.LC_ALL : 'en_US.UTF-8',
-};
-
-export interface PrepareMobileOptions extends MobileRuntimeDecisionOptions {
-  /**
-   * Whether the caller emits a --json envelope on stdout. Leaf progress always
-   * streams to stderr (see dispatchAction/spawnScriptStreaming); this only gates
-   * the in-process teaching messages so they never pollute the stdout envelope.
-   */
-  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,
-    preflightMode: opts.preflightMode,
-  });
-}
-
-/**
- * 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,
-    preflightMode,
-  });
-
-  if (report.decision === 'blocked') {
-    const reasons = report.reasons.join(' ');
-    const next = report.userAction ?? 'fix the bundle error in app code before retrying recipe up.';
-    const msg = `mobile prepare blocked: ${reasons}\n  Next: ${next}`;
-    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 = await dispatchAction(action, target, platform, json, preflightMode);
-    if (result.status !== 0) return result;
-    // Record the deps baseline the instant a setup/install leaf succeeds, so the
-    // mtime freshness fallback stops firing forever after one good install. This
-    // is unconditional (not gated on a later re-decide or an env flag), so the
-    // baseline lifecycle is self-sustaining regardless of the caller's path.
-    if (action.id === 'yarn-setup') recordDepsBaseline(path.resolve(target));
-  }
-
-  // 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,
-      preflightMode,
-    });
-    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 = await 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 = await 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: '' };
-}
-
-// Long-running leaves stream their output to stderr live (spawnScriptStreaming),
-// so the multi-minute prepare phase is not silent; stdout stays reserved for the
-// caller's --json envelope. Async so the parent can await each leaf in sequence.
-async function dispatchAction(
-  action: { id: string; argv?: string[]; cwd?: string },
-  target: string,
-  platform: string,
-  json: boolean,
-  preflightMode = 'fast',
-): Promise<ScriptResult> {
-  const cwd = action.cwd ?? target;
-  switch (action.id) {
-    case 'yarn-setup': {
-      // Leaf: install node_modules (deps missing or stale); `yarn setup` runs pods.
-      const leaf = path.join(runnerDir, 'adapters/mobile/yarn-setup.sh');
-      return spawnScriptStreaming(leaf, ['--target', cwd], target, POD_PROBE_ENV);
-    }
-    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 spawnScriptStreaming(leaf, ['--target', cwd, ...extra], target);
-    }
-    case 'prewarm-bundle': {
-      // Leaf: curl the bundle URL before opening the dev client.
-      const leaf = path.join(runnerDir, 'adapters/mobile/prewarm-bundle.sh');
-      return spawnScriptStreaming(leaf, ['--platform', platform, '--target', cwd], target);
-    }
-    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 spawnScriptStreaming(leaf, ['--target', cwd], target);
-    }
-    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 spawnScriptStreaming(leaf, ['--target', cwd, '--clear'], target);
-    }
-    case 'launch-mobile-runtime': {
-      // Leaf: open the MetaMask Mobile dev client on the simulator/device. In
-      // auto/rebuild modes this runs the native build (`yarn start:*`), which
-      // triggers pod install — pass the pod-probe env so it stays FORCE_COLOR-safe.
-      const leaf = path.join(runnerDir, 'adapters/mobile/open-device.sh');
-      return spawnScriptStreaming(
-        leaf,
-        ['--platform', platform, '--target', cwd, '--preflight-mode', preflightMode],
-        target,
-        POD_PROBE_ENV,
-      );
-    }
-    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: '' };
-  }
-}