@deeeed/metamask-harness 0.4.0 → 0.5.1

package/src/adapters/mobile/provision.ts

@@ -0,0 +1,594 @@
+import { execFileSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { recipeRuntimeDir } from '../../paths.ts';
+
+export interface RunwayProvisionOptions {
+  json?: boolean;
+  platform?: string;
+  branch?: string;
+  defaultBranch?: string;
+  run?: string;
+  cacheRoot?: string;
+  simulator?: string;
+  runtime?: string;
+  deviceType?: string;
+  slot?: string;
+  watcherPort?: string;
+  runtimeDir?: string;
+  force?: boolean;
+  resolveOnly?: boolean;
+  rerunCommand: string;
+}
+
+export interface RunwayProvisionResult {
+  schemaVersion: 1;
+  command: 'provision';
+  adapter: 'mobile';
+  target: string;
+  platform: string;
+  status: 'pass' | 'fail';
+  exitCode: number;
+  slot?: SlotContext;
+  artifact?: RunwayArtifact | ResolvedRunwayArtifact;
+  cache?: { status: 'hit' | 'miss' | 'redownload'; path: string; root: string };
+  simulator?: { name: string; udid?: string; created: boolean; runtime?: string; deviceType?: string };
+  resolveOnly?: boolean;
+  installed?: boolean;
+  skipped?: boolean;
+  baselinePath?: string;
+  error?: { code: string; message: string; userAction: string };
+}
+
+interface SlotContext {
+  path?: string;
+  slotId?: string;
+  platform?: string;
+  simulator?: string;
+  runtime?: string;
+  deviceType?: string;
+  watcherPort?: string;
+  gitBranch?: string;
+  defaultBranch?: string;
+}
+
+interface RunwayArtifact {
+  repo: string;
+  branch: string;
+  runId: string;
+  artifactName: string;
+  revision: string;
+  appPath: string;
+  sizeBytes: number;
+  sha256: string;
+}
+
+interface ResolvedRunwayArtifact {
+  repo: string;
+  branch: string;
+  runId: string;
+  artifactName: string;
+  revision: string;
+  archiveSizeBytes?: number;
+  archiveDownloadUrl?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+interface CacheMeta {
+  artifactName: string;
+  runId: string;
+  sizeBytes: number;
+  sha256: string;
+}
+
+interface GitHubArtifact {
+  name?: string;
+  expired?: boolean;
+  size_in_bytes?: number;
+  archive_download_url?: string;
+  created_at?: string;
+  updated_at?: string;
+}
+
+const RUNWAY_IOS_METADATA = {
+  artifactName: 'ios-app-main-dev-expo',
+  workflow: 'expo-dev-build.yml',
+  bundleId: 'io.metamask.MetaMask',
+  appDirName: 'MetaMask.app',
+  fallbackRepo: 'MetaMask/metamask-mobile',
+} as const;
+
+export async function provisionRunwayMobile(target: string, options: RunwayProvisionOptions): Promise<RunwayProvisionResult> {
+  const resolvedTarget = path.resolve(target);
+  const platform = options.platform ?? 'ios';
+  const slot = readSlotContext(resolvedTarget, options.runtimeDir);
+  if (options.slot) slot.slotId = options.slot;
+  if (options.watcherPort) slot.watcherPort = options.watcherPort;
+  const command = options.rerunCommand;
+  if (platform !== 'ios') {
+    return fail(resolvedTarget, platform, 'UNSUPPORTED_PLATFORM', 'runway provisioning currently installs the iOS .app artifact only.', command, slot);
+  }
+  const simulator = options.simulator ?? slot.simulator ?? process.env.IOS_SIMULATOR;
+  if (!simulator && !options.resolveOnly) {
+    return fail(resolvedTarget, platform, 'SIMULATOR_MISSING', 'no simulator was resolved from agentic-runtime.json, --simulator, or IOS_SIMULATOR.', command, slot);
+  }
+
+  const runtime = options.runtime ?? slot.runtime ?? process.env.IOS_RUNTIME;
+  const deviceType = options.deviceType ?? slot.deviceType ?? process.env.IOS_DEVICE_TYPE;
+  const repo = githubRepo(resolvedTarget);
+  const defaultBranch = options.defaultBranch ?? slot.defaultBranch ?? 'main';
+  const branch = options.branch ?? slot.gitBranch ?? gitBranch(resolvedTarget) ?? defaultBranch;
+
+  try {
+    if (options.resolveOnly) {
+      log(options, `runway: resolving Runway artifact for ${branch} (default ${defaultBranch})`);
+      const resolved = resolveArtifactRun(repo, branch, defaultBranch, options.run);
+      return {
+        schemaVersion: 1,
+        command: 'provision',
+        adapter: 'mobile',
+        target: resolvedTarget,
+        platform,
+        status: 'pass',
+        exitCode: 0,
+        slot,
+        resolveOnly: true,
+        artifact: resolved,
+        installed: false,
+        skipped: true,
+      };
+    }
+
+    const sim = ensureSimulator(simulator, runtime, deviceType);
+    if (!options.force && appInstalled(sim.udid ?? sim.name)) {
+      const baselinePath = writeRunwayBaseline(resolvedTarget, slot, platform, undefined, undefined, sim, true, options.runtimeDir);
+      return {
+        schemaVersion: 1,
+        command: 'provision',
+        adapter: 'mobile',
+        target: resolvedTarget,
+        platform,
+        status: 'pass',
+        exitCode: 0,
+        slot,
+        simulator: sim,
+        skipped: true,
+        installed: false,
+        baselinePath,
+      };
+    }
+
+    log(options, `runway: resolving Runway artifact for ${branch} (default ${defaultBranch})`);
+    const resolved = resolveArtifactRun(repo, branch, defaultBranch, options.run);
+    const cacheRoot = options.cacheRoot ?? defaultRunwayCacheRoot();
+    const cache = ensureCachedArtifact(repo, resolved.branch, resolved.runId, cacheRoot, options);
+
+    log(options, `runway: installing ${cache.artifact.appPath} on ${sim.name}`);
+    execFileSync('xcrun', ['simctl', 'install', sim.udid ?? sim.name, cache.artifact.appPath], { stdio: ['ignore', 'ignore', 'pipe'] });
+    const baselinePath = writeRunwayBaseline(resolvedTarget, slot, platform, resolved, cache.artifact, sim, false, options.runtimeDir);
+    return {
+      schemaVersion: 1,
+      command: 'provision',
+      adapter: 'mobile',
+      target: resolvedTarget,
+      platform,
+      status: 'pass',
+      exitCode: 0,
+      slot,
+      artifact: cache.artifact,
+      cache: { status: cache.status, path: cache.artifact.appPath, root: cacheRoot },
+      simulator: sim,
+      installed: true,
+      skipped: false,
+      baselinePath,
+    };
+  } catch (error) {
+    return fail(resolvedTarget, platform, 'PROVISION_FAILED', errorMessage(error), command, slot);
+  }
+}
+
+export function runwayBaselinePath(target: string, runtimeDir?: string): string {
+  return path.join(target, resolveRuntimeDir(runtimeDir), 'runway-provision.json');
+}
+
+export function hasRunwayProvisionBaseline(target: string): boolean {
+  try {
+    const data = JSON.parse(fs.readFileSync(runwayBaselinePath(target), 'utf8')) as Record<string, unknown>;
+    if (data.appInstalled !== true) return false;
+    const simulators = baselineSimulatorCandidates(data, readSlotContext(path.resolve(target)));
+    return simulators.some((simulator) => appInstalled(simulator));
+  } catch {
+    return false;
+  }
+}
+
+function fail(target: string, platform: string, code: string, message: string, rerunCommand: string, slot?: SlotContext): RunwayProvisionResult {
+  return {
+    schemaVersion: 1,
+    command: 'provision',
+    adapter: 'mobile',
+    target,
+    platform,
+    status: 'fail',
+    exitCode: 1,
+    slot,
+    error: { code, message, userAction: rerunCommand },
+  };
+}
+
+function readSlotContext(target: string, runtimeDir?: string): SlotContext {
+  const candidates = [
+    process.env.RECIPE_RUNTIME_CONTEXT,
+    runtimeContextPath(target, runtimeDir),
+    path.join(target, recipeRuntimeDir(), 'agentic-runtime.json'),
+    path.join(target, 'temp/recipe/runtime/agentic-runtime.json'),
+    path.join(target, 'temp/agentic/recipe-harness/agentic-runtime.json'),
+  ].filter((value): value is string => Boolean(value));
+  for (const candidate of [...new Set(candidates)]) {
+    try {
+      const data = JSON.parse(fs.readFileSync(candidate, 'utf8')) as Record<string, unknown>;
+      return {
+        path: candidate,
+        slotId: stringField(data, 'slotId'),
+        platform: stringField(data, 'platform'),
+        simulator: stringField(data, 'simulator') ?? stringField(data, 'iosSimulator'),
+        runtime: stringField(data, 'runtime') ?? stringField(data, 'iosRuntime'),
+        deviceType: stringField(data, 'deviceType') ?? stringField(data, 'iosDeviceType'),
+        watcherPort: stringField(data, 'watcherPort') ?? stringField(data, 'metroPort') ?? stringField(data, 'devServerPort'),
+        gitBranch: stringField(data, 'gitBranch') ?? stringField(data, 'prepareRef'),
+        defaultBranch: stringField(data, 'defaultBranch') ?? stringField(data, 'prepareDefaultRef'),
+      };
+    } catch {
+      // Try the next context candidate.
+    }
+  }
+  return {};
+}
+
+
+function runtimeContextPath(target: string, runtimeDir?: string): string | undefined {
+  if (!runtimeDir) return undefined;
+  try {
+    return path.join(target, resolveRuntimeDir(runtimeDir), 'agentic-runtime.json');
+  } catch {
+    return undefined;
+  }
+}
+
+function stringField(data: Record<string, unknown>, key: string): string | undefined {
+  const value = data[key];
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+function githubRepo(target: string): string {
+  try {
+    const remote = execFileSync('git', ['-C', target, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const match = /github\.com[:/]([^/]+\/[^/.]+)(?:\.git)?$/u.exec(remote);
+    if (match) return match[1];
+  } catch {
+    // Bare checkouts without git metadata use the canonical upstream repo.
+  }
+  return RUNWAY_IOS_METADATA.fallbackRepo;
+}
+
+function gitBranch(target: string): string | undefined {
+  try {
+    return execFileSync('git', ['-C', target, 'branch', '--show-current'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveArtifactRun(repo: string, branch: string, defaultBranch: string, runOverride?: string): ResolvedRunwayArtifact {
+  if (runOverride) {
+    assertValidRunId(runOverride);
+    const artifact = findRunArtifact(repo, runOverride, RUNWAY_IOS_METADATA.artifactName);
+    if (!artifact) throw new Error(`Runway run ${runOverride} does not contain ${RUNWAY_IOS_METADATA.artifactName}.`);
+    const revision = runRevision(repo, runOverride) ?? runOverride;
+    return resolvedArtifact(repo, branch, runOverride, revision, artifact);
+  }
+  const tried = [...new Set([branch, defaultBranch])];
+  for (const candidate of tried) {
+    const run = latestRunWithArtifact(repo, candidate, RUNWAY_IOS_METADATA.artifactName);
+    if (run) return resolvedArtifact(repo, candidate, run.runId, run.revision, run.artifact);
+  }
+  throw new Error(`no Runway artifact found for ${RUNWAY_IOS_METADATA.artifactName} on ${tried.join(', ')}.`);
+}
+
+function latestRunWithArtifact(repo: string, branch: string, artifactName: string): { runId: string; revision: string; artifact: GitHubArtifact } | undefined {
+  let runs: Array<{ databaseId?: number; headSha?: string }>;
+  try {
+    runs = execJson<Array<{ databaseId?: number; headSha?: string }>>('gh', [
+      'run', 'list', '--repo', repo, `--workflow=${RUNWAY_IOS_METADATA.workflow}`, `--branch=${branch}`, '--status=success', '--limit=30', '--json', 'databaseId,headSha',
+    ]);
+  } catch {
+    return undefined;
+  }
+  for (const run of runs) {
+    const runId = run.databaseId ? String(run.databaseId) : '';
+    if (!runId) continue;
+    const artifact = findRunArtifact(repo, runId, artifactName);
+    if (artifact) return { runId, revision: run.headSha || runId, artifact };
+  }
+  return undefined;
+}
+
+function assertValidRunId(runId: string): void {
+  if (!/^\d+$/u.test(runId)) throw new Error(`invalid Runway run id: ${runId}.`);
+}
+
+function findRunArtifact(repo: string, runId: string, artifactName: string): GitHubArtifact | undefined {
+  assertValidRunId(runId);
+  try {
+    const data = execJson<{ artifacts?: GitHubArtifact[] }>('gh', [
+      'api', `repos/${repo}/actions/runs/${runId}/artifacts`, '--paginate',
+    ]);
+    return data.artifacts?.find((artifact) => artifact.expired === false && artifact.name === artifactName);
+  } catch {
+    return undefined;
+  }
+}
+
+function runRevision(repo: string, runId: string): string | undefined {
+  try {
+    const data = execJson<{ headSha?: string }>('gh', ['run', 'view', runId, '--repo', repo, '--json', 'headSha']);
+    return data.headSha;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvedArtifact(repo: string, branch: string, runId: string, revision: string, artifact: GitHubArtifact): ResolvedRunwayArtifact {
+  return {
+    repo,
+    branch,
+    runId,
+    artifactName: RUNWAY_IOS_METADATA.artifactName,
+    revision,
+    archiveSizeBytes: artifact.size_in_bytes,
+    archiveDownloadUrl: artifact.archive_download_url,
+    createdAt: artifact.created_at,
+    updatedAt: artifact.updated_at,
+  };
+}
+
+function ensureCachedArtifact(
+  repo: string,
+  branch: string,
+  runId: string,
+  cacheRoot: string,
+  options: RunwayProvisionOptions,
+): { status: 'hit' | 'miss' | 'redownload'; artifact: RunwayArtifact } {
+  const dir = path.join(cacheRoot, runId);
+  const appPath = path.join(dir, RUNWAY_IOS_METADATA.appDirName);
+  const metaPath = path.join(dir, 'metadata.json');
+  const valid = validateCache(appPath, metaPath, RUNWAY_IOS_METADATA.artifactName, runId);
+  if (valid) {
+    return { status: 'hit', artifact: { repo, branch, runId, artifactName: RUNWAY_IOS_METADATA.artifactName, revision: runId, appPath, sizeBytes: valid.sizeBytes, sha256: valid.sha256 } };
+  }
+  const redownload = fs.existsSync(dir);
+  if (redownload) {
+    const corruptDir = path.join(cacheRoot, `${runId}.corrupt-${Date.now()}`);
+    fs.renameSync(dir, corruptDir);
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mm-runway-artifact-'));
+  try {
+    log(options, `runway: cache ${redownload ? 'corrupt' : 'miss'} for run ${runId}; downloading once`);
+    execFileSync('gh', ['run', 'download', runId, '--repo', repo, '--name', RUNWAY_IOS_METADATA.artifactName, '--dir', tmp], { stdio: ['ignore', 'ignore', 'pipe'] });
+    const downloaded = findAppOrExtractArchive(tmp);
+    if (!downloaded) throw new Error('downloaded artifact did not contain an iOS .app bundle.');
+    movePath(downloaded, appPath);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+  const digest = hashPath(appPath);
+  const meta: CacheMeta = { artifactName: RUNWAY_IOS_METADATA.artifactName, runId, sizeBytes: digest.sizeBytes, sha256: digest.sha256 };
+  fs.writeFileSync(metaPath, `${JSON.stringify(meta, null, 2)}\n`);
+  return { status: redownload ? 'redownload' : 'miss', artifact: { repo, branch, runId, artifactName: RUNWAY_IOS_METADATA.artifactName, revision: runId, appPath, ...digest } };
+}
+
+function validateCache(appPath: string, metaPath: string, artifactName: string, runId: string): { sizeBytes: number; sha256: string } | null {
+  if (!fs.existsSync(appPath) || !fs.existsSync(metaPath)) return null;
+  try {
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')) as CacheMeta;
+    if (meta.artifactName !== artifactName || meta.runId !== runId) return null;
+    const digest = hashPath(appPath);
+    return digest.sizeBytes === meta.sizeBytes && digest.sha256 === meta.sha256 ? digest : null;
+  } catch {
+    return null;
+  }
+}
+
+function findApp(root: string): string | undefined {
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  let app: string | undefined;
+  for (const entry of entries) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory() && entry.name === RUNWAY_IOS_METADATA.appDirName) return full;
+    if (entry.isDirectory() && entry.name.endsWith('.app')) {
+      app ??= full;
+      continue;
+    }
+    if (entry.isDirectory()) {
+      const nested = findApp(full);
+      if (nested) return nested;
+    }
+  }
+  return app;
+}
+
+function findAppOrExtractArchive(root: string): string | undefined {
+  return findAppOrExtractArchiveInner(root, new Set(), 0);
+}
+
+function findAppOrExtractArchiveInner(root: string, extracted: Set<string>, depth: number): string | undefined {
+  const app = findApp(root);
+  if (app) return app;
+  if (depth >= 3) return undefined;
+  for (const archive of findZipArchives(root)) {
+    const realArchive = fs.realpathSync(archive);
+    if (extracted.has(realArchive)) continue;
+    extracted.add(realArchive);
+    const extractDir = fs.mkdtempSync(path.join(root, '.mm-runway-unzip-'));
+    execFileSync('unzip', ['-q', archive, '-d', extractDir], { stdio: ['ignore', 'ignore', 'pipe'] });
+    const nested = findAppOrExtractArchiveInner(extractDir, extracted, depth + 1);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+function findZipArchives(root: string): string[] {
+  const archives: string[] = [];
+  const visit = (dir: string): void => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.name.endsWith('.app')) visit(full);
+        continue;
+      }
+      if (entry.isFile() && entry.name.toLowerCase().endsWith('.zip')) archives.push(full);
+    }
+  };
+  visit(root);
+  return archives.sort();
+}
+
+function movePath(source: string, destination: string): void {
+  try {
+    fs.renameSync(source, destination);
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'EXDEV') {
+      fs.cpSync(source, destination, { recursive: true });
+      fs.rmSync(source, { recursive: true, force: true });
+      return;
+    }
+    throw error;
+  }
+}
+
+function hashPath(root: string): { sizeBytes: number; sha256: string } {
+  const hash = crypto.createHash('sha256');
+  let sizeBytes = 0;
+  const visitDirectory = (dir: string, relative = ''): void => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      const rel = path.join(relative, entry.name);
+      if (entry.isDirectory()) {
+        visitDirectory(full, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      hash.update(rel);
+      const data = fs.readFileSync(full);
+      sizeBytes += data.length;
+      hash.update(data);
+    }
+  };
+  visitDirectory(root);
+  return { sizeBytes, sha256: hash.digest('hex') };
+}
+
+function ensureSimulator(name: string, runtime?: string, deviceType?: string): { name: string; udid?: string; created: boolean; runtime?: string; deviceType?: string } {
+  const existing = findSimulator(name);
+  if (existing) return { name, udid: existing, created: false, runtime, deviceType };
+  if (!runtime || !deviceType) {
+    throw new Error(`simulator ${name} is missing and runtime/device type could not be resolved. Pass --runtime and --device-type, or write them to agentic-runtime.json.`);
+  }
+  const udid = execFileSync('xcrun', ['simctl', 'create', name, deviceType, runtime], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  return { name, udid: udid || name, created: true, runtime, deviceType };
+}
+
+function findSimulator(name: string): string | undefined {
+  const data = execJson<{ devices?: Record<string, Array<{ name?: string; udid?: string }>> }>('xcrun', ['simctl', 'list', 'devices', '--json']);
+  for (const devices of Object.values(data.devices ?? {})) {
+    const found = devices.find((device) => device.name === name || device.udid === name);
+    if (found?.udid) return found.udid;
+  }
+  return undefined;
+}
+
+
+function baselineSimulatorCandidates(data: Record<string, unknown>, current: SlotContext): string[] {
+  const candidates: string[] = [];
+  if (current.simulator) candidates.push(current.simulator);
+  const simulator = data.simulator;
+  if (simulator && typeof simulator === 'object' && !Array.isArray(simulator)) {
+    const record = simulator as Record<string, unknown>;
+    for (const key of ['udid', 'name'] as const) {
+      const value = record[key];
+      if (typeof value === 'string' && value) candidates.push(value);
+    }
+  }
+  return [...new Set(candidates)];
+}
+
+function appInstalled(device: string): boolean {
+  try {
+    execFileSync('xcrun', ['simctl', 'get_app_container', device, RUNWAY_IOS_METADATA.bundleId, 'app'], { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function writeRunwayBaseline(
+  target: string,
+  slot: SlotContext,
+  platform: string,
+  resolved: { branch: string; runId: string; artifactName: string; revision: string } | undefined,
+  artifact: RunwayArtifact | undefined,
+  simulator: { name: string; udid?: string; created: boolean; runtime?: string; deviceType?: string },
+  alreadyInstalled: boolean,
+  runtimeDir?: string,
+): string {
+  const file = runwayBaselinePath(target, runtimeDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify({
+    schemaVersion: 1,
+    appInstalled: true,
+    deps: 'pending',
+    platform,
+    slotId: slot.slotId ?? null,
+    watcherPort: slot.watcherPort ?? null,
+    simulator,
+    artifact: resolved && artifact ? { ...resolved, path: artifact.appPath, sizeBytes: artifact.sizeBytes, sha256: artifact.sha256 } : null,
+    alreadyInstalled,
+    recordedAt: new Date().toISOString(),
+  }, null, 2)}\n`);
+  return file;
+}
+
+
+function resolveRuntimeDir(runtimeDir?: string): string {
+  if (runtimeDir === undefined) return recipeRuntimeDir();
+  if (!runtimeDir || path.isAbsolute(runtimeDir)) throw new Error(`--runtime-dir must be a non-empty relative path: ${runtimeDir}`);
+  if (!/^[A-Za-z0-9._/-]+$/u.test(runtimeDir)) throw new Error(`--runtime-dir contains unsupported characters: ${runtimeDir}`);
+  for (const part of runtimeDir.split('/')) {
+    if (!part || part === '.' || part === '..') throw new Error(`--runtime-dir contains unsafe path component: ${runtimeDir}`);
+  }
+  return runtimeDir;
+}
+
+function defaultRunwayCacheRoot(): string {
+  return path.join(process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), '.cache'), 'metamask-harness', 'runway');
+}
+
+function execJson<T>(bin: string, args: string[]): T {
+  const out = execFileSync(bin, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return JSON.parse(out) as T;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function log(options: RunwayProvisionOptions, message: string): void {
+  if (!options.json) process.stderr.write(`${message}\n`);
+}

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

@@ -201,6 +201,13 @@ export async function decideMobileReadiness(
   // 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',
@@ -210,7 +217,7 @@ export async function decideMobileReadiness(
         ...report.reasons,
       ],
       userAction:
-        'run the slot deps/prepare phase; standalone: `yarn setup:expo --no-build-ios --no-build-android` in the checkout, or `mm-harness launch <platform> --build` to install and build',
+        `run the slot deps/prepare phase; standalone: ${standalone} in the checkout, then re-run \`mm-harness launch <platform>\``,
       actions: [],
     };
   }

package/src/adapters/mobile/surface.ts

@@ -5,10 +5,12 @@ 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';
 
@@ -23,15 +25,25 @@ export const mobileSurface: AdapterSurface = {
   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: report.decision,
-      reasonCode: report.reasonCode,
-      reasons: report.reasons,
-      deps: report.checks?.deps?.status,
+      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 {

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

@@ -0,0 +1,13 @@
+// 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';