Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

25.0 KB
Raw Blame
#!/usr/bin/env node
// 在 iOS 模拟器上重编 + 重装 dev 包。
//
// 何时用:动了原生层(app.json / scheme / 权限 / plugin / 原生模块 / pod)之后。
// 纯 JS/TS 改动**不需要**跑这个 —— Metro 的 Fast Refresh 直接生效。
//
// 为什么不用 `expo run:ios`:Xcode 26.5 上 expo 的 devicectl / 设备解析坏掉,
// xcodebuild 枚举不出具体模拟器,会报
//   `xcodebuild: error: Unable to find a destination matching ... { id:<udid> }`。
// 日常独立调用默认用 `generic/platform=iOS Simulator` 通用目标编译(不需要枚举
// 具体设备)。Cindy Host 会把 `--udid` 与 `--build-only` 一起传入,让 xcodebuild
// 绑定精确 destination;后续安装和启动由 Host 自己的精确实例生命周期完成。
// 架构交给 Pods/Xcode 决定,避免覆盖原生 SDK 自己声明的 simulator exclusions。
//
// 两个提速机制(2026-07 加,背景:每任务一个新 worktree 的工作流让"从零冷构建"
// 成为高频成本,一次约 12 分钟;外加一次 pod CDN 挂死 20 分钟的事故):
//
// 1. fingerprint 产物缓存:native 产物只由 @expo/fingerprint 的输入决定(与发版
//    "热更 vs 冷更"同一判定口径;ios/ 已 gitignore,按 CNG 语义不参与哈希,因此
//    跨 worktree 稳定)。构建成功后把 .app 按 fingerprint 存进
//    ~/Library/Caches/xdt-maker/sim-app-cache/;下次(常见:新开 worktree 但没动
//    原生层)fingerprint 命中就直接装缓存产物,prebuild / pod / xcodebuild 全部跳过,
//    分钟级变秒级。缓存只保留最近几份,`--force-build` 可强制重新构建。
//    注意 Debug 包不内嵌 JS(运行时连 8081 Metro),EXPO_PUBLIC_* 也在 Metro bundle
//    时注入,所以"native 产物按 fingerprint 复用"对 dev 验证是安全的。
// 2. pod install 有界化:prebuild 改用 --no-install,pod install 由本脚本经
//    sim-pod-install.mjs 自己跑——本地 specs 优先、失败带 --repo-update 重试一次,
//    两次都在**输出空转看门狗**下运行(不是总时长超时:fresh worktree 可能要下
//    ~90MB 的 RN prebuilt 产物,慢网络下合法耗时 20 分钟以上;挂死的特征是"没有
//    任何输出",详见该模块头注)。把"CDN 连接挂死无限等"变成"分钟级失败重试/报错"。
//
// 用法(apps/mobile 下):
//   node scripts/sim-rebuild.mjs                 # 重编并装到 booted 模拟器(保留 app 数据 / 登录态)
//   node scripts/sim-rebuild.mjs --clean         # 先卸载再装(干净登录态测试)
//   node scripts/sim-rebuild.mjs --force-build   # 跳过 fingerprint 产物缓存,强制完整重编
//   node scripts/sim-rebuild.mjs --build-only    # 只构建 + 入产物缓存,不装/不启动模拟器
//                                                #(预热缓存,或模拟器正被别的验证占用时)
//   node scripts/sim-rebuild.mjs --build-only --udid <UUID>
//                                                # Cindy Host 的精确 destination 构建路径
// 或仓库根:pnpm mobile:sim:rebuild [-- --region=cn] [-- --clean] [-- --force-build] [-- --build-only]

import { execFileSync, spawnSync } from 'node:child_process';
import {
  cpSync,
  existsSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  rmSync,
  statSync,
  utimesSync,
  writeFileSync,
} from 'node:fs';
import { homedir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { mobileClientBundleEnv } from '../../../scripts/shared/client-endpoint-build-env.mjs';
import {
  resolvePnpmInvocation,
  usablePnpmExecPath,
} from '../../../scripts/shared/pnpm-invocation.mjs';
import { ensureMobileEnv, formatMobileEnvStatus } from './ensure-mobile-env.mjs';
import { computeFingerprintReport, parseFingerprintCliOutput } from './ci-fingerprint.mjs';
import {
  extractMobileDevRegionArgs,
  withLocalMobileRegionConfig,
} from './lib/mobile-dev-region.mjs';
import {
  ensureMobileLocalRegionConfig,
  formatMobileLocalConfigStatus,
} from './lib/mobile-local-config.mjs';
import { podInstallBounded, inspectIOSBuildTools, COCOAPODS_SETUP_HINT } from './sim-pod-install.mjs';
import { computeSimulatorNativeFingerprint, inspectSimulatorNativeIdentity } from './lib/sim-native-identity.mjs';
import { ensureWindowsAndroidEmulator, resolveAndroidSdkTools } from './lib/android-simulator.mjs';
import { resolveJavaRuntimeEnv } from './java-runtime-env.mjs';
import {
  gitSourceIdentity,
  probeMetroOwnership,
} from './sim-metro.mjs';

import { applySimMockArg, readSimEnvironment } from './lib/sim-environment.mjs';
import { extractSimWhoamiUdidArgs, resolveMobileSimulatorBundleId, classifySimMetroListener, validateSimMetroIdentity, resolveSimulatorDeviceSets, selectBootedSimulator, findSimulatorDeviceSet, simctlArgs } from './lib/sim-whoami.mjs';

const mobileDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const worktreeRoot = resolve(mobileDir, '../..');
const iosDir = join(mobileDir, 'ios');
const buildDir = join(iosDir, 'build');
const { region, passthrough } = extractMobileDevRegionArgs(applySimMockArg(process.argv.slice(2)));
const clean = passthrough.includes('--clean');
const forceBuild = passthrough.includes('--force-build');
const buildOnly = passthrough.includes('--build-only');
const { simulatorUdid } = extractSimWhoamiUdidArgs(passthrough);
const localConfigResult = ensureMobileLocalRegionConfig({ mobileDir });
const localConfigStatus = formatMobileLocalConfigStatus(localConfigResult, worktreeRoot);
if (localConfigStatus) console.log(localConfigStatus);
const buildEnv = withLocalMobileRegionConfig(
  mobileClientBundleEnv({ authRegion: region }),
);
const devProcessEnv = { ...process.env, ...buildEnv };

// fingerprint 产物缓存位置与保留份数。跨 worktree 共享;条目按 LRU(目录 mtime)清理。
const appCacheRoot = join(homedir(), 'Library/Caches/xdt-maker/sim-app-cache');
const APP_CACHE_KEEP = 4;
// prune 的最小年龄护栏:mtime 在此窗口内的条目视为"可能正被另一个并发 rebuild
// 读/写",即使排到 LRU 尾部也不删。读方命中时会先 touch mtime、写方最后才写
// meta.json,配合这个窗口,跨 worktree 并发时不会删到正在使用的条目
// (缓存无锁,这是面向单人多 worktree 场景的轻量保护,不追求分布式正确性)。
const APP_CACHE_PRUNE_MIN_AGE_MS = 30 * 60_000;

const envResult = ensureMobileEnv({ mobileDir, authRegion: region, endpointEnv: buildEnv });
console.log(formatMobileEnvStatus(envResult, worktreeRoot));
console.log(`==> Mobile dev region: ${region}`);
const envChanged = envResult.created || envResult.addedKeys.length > 0;

const run = (cmd, args, opts = {}) =>
  execFileSync(cmd, args, { stdio: 'inherit', cwd: mobileDir, env: devProcessEnv, ...opts });
const capture = (cmd, args) =>
  execFileSync(cmd, args, { cwd: mobileDir, env: devProcessEnv, encoding: 'utf8' }).trim();
function pnpmInvocation(args) {
  return resolvePnpmInvocation(args, {
    npmExecPath: usablePnpmExecPath(process.env.npm_execpath, existsSync),
  });
}

function runPnpm(args, opts = {}) {
  const invocation = pnpmInvocation(args);
  return run(invocation.command, invocation.args, {
    ...opts,
    shell: invocation.shell,
    windowsVerbatimArguments: invocation.windowsVerbatimArguments,
    env: { ...devProcessEnv, ...(invocation.env ?? {}), ...(opts.env ?? {}) },
  });
}

function capturePnpm(args) {
  const invocation = pnpmInvocation(args);
  return execFileSync(invocation.command, invocation.args, {
    cwd: mobileDir,
    env: { ...devProcessEnv, ...(invocation.env ?? {}) },
    encoding: 'utf8',
    shell: invocation.shell,
    windowsVerbatimArguments: invocation.windowsVerbatimArguments,
  }).trim();
}

// Windows 开发机没有 xcrun/Xcode。这里走 Android debug dev client,避免在任何
// Windows 路径上触发 iOS 的 xcrun、pod 或 xcodebuild。
if (process.platform === 'win32') {
  await rebuildAndroidSimulator();
  process.exit(process.exitCode ?? 0);
}

// 必须有一台 booted 模拟器(--build-only 不装机,无此要求)。默认先找 Cindy 模拟器,
// 没有再找系统模拟器;CINDY_MOBILE_SIMULATOR 可固定其一。
let deviceSet = null;
if (!buildOnly) {
  let selected;
  try {
    selected = selectBootedSimulator(resolveSimulatorDeviceSets(), (set) =>
      capture('xcrun', simctlArgs(set, ['list', 'devices', 'booted'])), simulatorUdid);
  } catch (error) {
    console.error(`✗ ${error.message}`);
    process.exit(1);
  }
  if (selected.targetBooted.length !== 1) {
    console.error('✗ 需要唯一的已启动模拟器;多设备时传 --udid,指定设备必须已启动。');
    process.exit(1);
  }
  deviceSet = selected.deviceSet;
  console.log(`==> 目标模拟器(${deviceSet.name}):${selected.targetBooted[0].trim()}`);
} else if (simulatorUdid) {
  // 仅构建不要求设备已启动,但 xcodebuild 的精确目标只对系统目录有效:先确认 UDID 属于哪个目录。
  try {
    deviceSet = findSimulatorDeviceSet(resolveSimulatorDeviceSets(), (set) =>
      capture('xcrun', simctlArgs(set, ['list', 'devices'])), simulatorUdid);
  } catch (error) {
    console.error(`✗ ${error.message}`);
    process.exit(1);
  }
}

async function ensureMetroOwnershipBeforeLaunch(packageName) {
  const ownership = probeMetroOwnership(8081);
  const { envFingerprint } = readSimEnvironment(mobileDir, buildEnv);
  const verdict = validateSimMetroIdentity({
    listener: classifySimMetroListener({ cwd: ownership?.cwd, source: ownership?.source, targetWorktree: worktreeRoot }),
    currentSource: gitSourceIdentity(worktreeRoot), runningSource: ownership?.source,
    currentRegion: region, runningRegion: ownership?.region,
    currentEnvFingerprint: envFingerprint, runningEnvFingerprint: ownership?.envFingerprint,
    envChanged,
  });
  if (verdict.healthy) return true;
  console.error(`Native package installed (${packageName}); launch blocked: ${verdict.code}.`);
  const mock = readSimEnvironment(mobileDir, buildEnv).uiMock ? ' --mock' : '';
  console.error(`Run pnpm mobile:sim:start -- --region=${region}${mock}, then mobile:sim:whoami with the same options.`);
  process.exitCode = 1;
  return false;
}

async function rebuildAndroidSimulator() {
  const androidTools = process.platform === 'win32'
    ? resolveAndroidSdkTools({
      env: devProcessEnv,
      platform: process.platform,
      requireTools: !buildOnly,
    })
    : null;
  const emulator = buildOnly
    ? { serial: null, adb: null, sdkRoot: androidTools?.sdkRoot }
    : await ensureWindowsAndroidEmulator({ port: 8081 });
  const sdkRoot = emulator.sdkRoot ?? androidTools?.sdkRoot;
  const androidDir = join(mobileDir, 'android');
  const javaEnv = resolveJavaRuntimeEnv({
    ...devProcessEnv,
    ...(sdkRoot ? { ANDROID_SDK_ROOT: sdkRoot, ANDROID_HOME: sdkRoot } : {}),
  });
  console.log('› Android expo prebuild (debug development client)');
  runPnpm(['exec', 'expo', 'prebuild', '--platform', 'android', '--no-install']);

  const gradle = process.platform === 'win32' ? 'gradlew.bat' : './gradlew';
  console.log('› Android gradle assembleDebug');
  if (process.platform === 'win32') {
    run('cmd.exe', ['/d', '/s', '/c', '.\\gradlew.bat assembleDebug'], {
      cwd: androidDir,
      env: javaEnv,
      windowsVerbatimArguments: true,
    });
  } else {
    run(gradle, ['assembleDebug'], { cwd: androidDir, env: javaEnv });
  }

  const apk = join(androidDir, 'app/build/outputs/apk/debug/app-debug.apk');
  if (!existsSync(apk)) {
    throw new Error(`prebuild/gradle 后未找到 Android debug APK: ${apk}`);
  }
  const config = JSON.parse(capturePnpm(['exec', 'expo', 'config', '--type', 'public', '--json']));
  const packageName = config?.android?.package;
  if (typeof packageName !== 'string' || !packageName.trim()) {
    throw new Error(`Expo config 缺少 android.package(region=${region})`);
  }
  if (buildOnly) {
    console.log(`✓ Android --build-only 完成: ${apk}`);
    return;
  }
  const { adb, serial } = emulator;
  const target = ['-s', serial];
  if (clean) {
    try {
      run(adb, [...target, 'uninstall', packageName]);
    } catch {
      console.log('  (没有可卸载的旧 Android 包,跳过)');
    }
  }
  console.log(`› 安装 Android debug 包到 ${serial}`);
  run(adb, [...target, 'install', '-r', apk]);
  run(adb, [...target, 'shell', 'am', 'force-stop', packageName]);
  if (!await ensureMetroOwnershipBeforeLaunch(packageName)) return;
  run(adb, [...target, 'shell', 'monkey', '-p', packageName, '1']);
  console.log(`\n✓ 完成: ${packageName} 已安装并发送启动请求;尚未验证页面显示。JS 改动直接由 Metro Fast Refresh 提供。`);
}

// 宿主机架构只参与缓存隔离;真实构建架构由 Xcode 与各 Pod 的支持矩阵决定。
const simArch = process.arch === 'arm64' ? 'arm64' : 'x86_64';
console.log('› 解析目标 App 身份…');
const expectedBundleId = resolveMobileSimulatorBundleId(region);
console.log(`==> Worktree: ${worktreeRoot}; region=${region}; bundleId=${expectedBundleId}; arch=${simArch}`);
console.log('› 计算原生兼容指纹(最长 120s)…');
let expectedNativeFingerprint = computeSimulatorNativeFingerprint(mobileDir, devProcessEnv);

function assertNativeIdentity(appPath) {
  const verdict = inspectSimulatorNativeIdentity({ appPath, expectedFingerprint: expectedNativeFingerprint });
  if (!verdict.healthy) throw new Error(`${verdict.code}: 原生产物与当前依赖不匹配,不能交付测试。请用 --force-build 重新构建。`);
}

// —— fingerprint 产物缓存查询 ——
// 失败(工具异常等)只降级为完整构建,绝不让缓存机制本身挡住构建路径。
// --force-build 也要算哈希:它只跳过缓存"读",构建结果仍写回同一条目,把坏缓存
// 覆盖掉——否则逃生舱跑完一次,坏条目还在,下次普通 rebuild 又命中它。
let fingerprintHash = null;
try {
  console.log('› 计算 native fingerprint(产物缓存键,最长 120s)…');
  fingerprintHash = computeFingerprintReport(mobileDir, {
    platforms: ['ios'],
    run: runFingerprintWithCurrentEnv,
  }).platforms.ios;
} catch (error) {
  console.warn(`  fingerprint 计算失败(${error.message}),回退完整构建(本次不读写产物缓存)。`);
}
const cacheDir = fingerprintHash ? join(appCacheRoot, `ios-${simArch}-${fingerprintHash}`) : null;

let app = null;
let cache = { code: forceBuild ? 'cache-bypassed' : 'cache-fingerprint-unavailable', app: null };
if (cacheDir && !forceBuild) {
  cache = readAppCacheEntry(cacheDir, simArch);
  if (cache.app) {
    console.log(`✓ fingerprint 命中产物缓存(${fingerprintHash.slice(0, 12)}…),跳过 prebuild / pod / xcodebuild。`);
    console.log('  (改了原生层但怀疑缓存不对时,用 --force-build 强制重编。)');
    utimesSync(cacheDir, new Date(), new Date());
    app = cache.app;
  }
}
console.log(`SIM_CACHE=${JSON.stringify({ ...cache, directory: cacheDir, root: appCacheRoot, fingerprint: fingerprintHash })}`);

if (!app) {
  console.log(`› 缓存不可复用(${cache.code}),检查 iOS 构建工具链…`);
  const preflight = inspectIOSBuildTools({ env: devProcessEnv });
  console.log(`SIM_BUILD_PREFLIGHT=${JSON.stringify(preflight)}`);
  if (!preflight.healthy) {
    console.error(`✗ IOS_BUILD_TOOLS_UNAVAILABLE: ${preflight.checks.filter((check) => !check.healthy).map((check) => `${check.tool}=${check.code}`).join(', ')};尚未执行 prebuild / pod install / xcodebuild。`);
    if (preflight.checks.some((check) => check.tool === 'pod' && !check.healthy)) console.error(COCOAPODS_SETUP_HINT);
    console.error('先按 docs/dev-rules/environment-setup.md 修复上述工具,再用相同 region / UDID / --mock 参数重试;不要改用其他 App 身份。');
    process.exit(1);
  }
  // 总是先 prebuild,再 xcodebuild。本脚本是 native 变更的验证路径 —— 若只在 ios/ 缺失时
  // prebuild,那么"改了 app.json / Expo plugins / Pods 但 ios/ 已存在"时会构建到 stale 的
  // native 工程还报成功。prebuild 不带 --clean 是增量的,无 native 改动时很快。
  // --no-install:node modules 由仓库工作流负责,pod install 由下面的 podInstall() 有界执行。
  // pnpm exec:pnpm 不在 apps/mobile/node_modules/.bin 放 expo bin,直接 node 跑会 MODULE_NOT_FOUND。
  console.log('› expo prebuild(把 app.json / plugins / Pods 的 native 改动应用进 ios/,不含 pod install)…');
  run('pnpm', ['exec', 'expo', 'prebuild', '-p', 'ios', '--no-install']);
  console.log('› pod install(本地 specs 优先,输出空转看门狗兜底)…');
  try {
    await podInstallBounded({ iosDir, env: devProcessEnv });
  } catch (error) {
    console.error(`✗ ${error.message}`);
    if (!error.podMissing) {
      console.error('  多为网络/代理问题(CocoaPods CDN / prebuilt 产物源不可达)。检查网络后重试;specs 缓存在 ~/.cocoapods/。');
    }
    process.exit(1);
  }

  const workspace = existsSync(iosDir)
    ? readdirSync(iosDir).find((f) => f.endsWith('.xcworkspace'))
    : undefined;
  if (!workspace) {
    console.error('✗ prebuild 后仍未生成 .xcworkspace,请检查 expo prebuild 输出。');
    process.exit(1);
  }
  const scheme = workspace.replace(/\.xcworkspace$/, '');

  // xcodebuild 只认得系统设备目录;其它设备目录(如 Cindy 模拟器)用通用目标编译,再按目录安装。
  const exactDestination = simulatorUdid && !deviceSet?.path;
  const simulatorDestination = exactDestination
    ? `platform=iOS Simulator,id=${simulatorUdid}`
    : 'generic/platform=iOS Simulator';
  console.log(`› 编译 ${scheme}(${exactDestination ? 'exact' : 'generic'} iOS Simulator destination)…`);
  run('xcodebuild', [
    '-workspace', join(iosDir, workspace),
    '-scheme', scheme,
    '-configuration', 'Debug',
    '-destination', simulatorDestination,
    '-derivedDataPath', buildDir,
    '-quiet',
    'build',
  ]);

  app = join(buildDir, 'Build/Products/Debug-iphonesimulator', `${scheme}.app`);
  if (!existsSync(app)) {
    console.error(`✗ 没找到产物 ${app}`);
    process.exit(1);
  }
  assertBundleIdentity(app);
  // Prebuild can update generated inputs. Compare the actual build resource,
  // never label an old artifact with a newly computed hash.
  expectedNativeFingerprint = computeSimulatorNativeFingerprint(mobileDir, devProcessEnv);
  assertNativeIdentity(app);
  if (cacheDir) storeAppCacheEntry(cacheDir, scheme, app, readAppBundleIdentifier(app));
}

assertAppSupportsArchitecture(app, simArch);
assertBundleIdentity(app);
assertNativeIdentity(app);

// bundle identity 必须从实际产物读:global 的 app.config.js 会把 bundle id
// 切成 com.xd.cindy,不能再用默认 cn 的 app.json 值启动错 app。
const bundleId = readAppBundleIdentifier(app);

if (buildOnly) {
  console.log(`\n✓ --build-only 完成:产物在 ${app}${cacheDir ? '(已入 fingerprint 缓存)' : ''}。未安装到模拟器。`);
  process.exit(0);
}

if (clean) {
  console.log('› --clean:卸载旧包…');
  // uninstall 容错:app 未安装时 simctl 返回非零会让 execFileSync 抛错、后续 install 不执行
  // (首次干净安装就是这个场景)。卸载失败基本只意味着"本来就没装",忽略即可。
  try {
    run('xcrun', simctlArgs(deviceSet, ['uninstall', simulatorUdid ?? 'booted', bundleId]));
  } catch {
    console.log('  (没有可卸载的旧包,跳过)');
  }
}
console.log('› 安装到 booted 模拟器…');
run('xcrun', simctlArgs(deviceSet, ['install', simulatorUdid ?? 'booted', app]));
assertNativeIdentity(capture('xcrun', simctlArgs(deviceSet, ['get_app_container', simulatorUdid ?? 'booted', bundleId, 'app'])).trim());

if (!await ensureMetroOwnershipBeforeLaunch(bundleId)) process.exit(1);
console.log('› 启动…');
run('xcrun', simctlArgs(deviceSet, ['launch', simulatorUdid ?? 'booted', bundleId]));
console.log(`\n✓ 完成。${bundleId} 已安装并发送启动请求;尚未验证页面显示。改 JS 直接靠 Metro Fast Refresh,不用再跑本脚本。`);

/**
 * 用**当前环境**跑 @expo/fingerprint。不能用 ci-fingerprint 默认 runner:它是
 * production 口径,会剥离全部 EXPO_PUBLIC_*;而本脚本后面的 expo prebuild 继承
 * 当前环境(app.config.js 在 EXPO_PUBLIC_APP_VARIANT==='beta' 时会改原生 name),
 * 缓存键必须跟着同一份 env 算,否则 beta / production 变体会命中彼此的产物。
 */
function runFingerprintWithCurrentEnv({ binPath, projectDir, platform }) {
  const result = spawnSync(process.execPath, [binPath, 'fingerprint:generate', '--platform', platform], {
    cwd: resolve(projectDir),
    env: devProcessEnv,
    encoding: 'utf8',
    // 输出含全部 sources(>1MB),必须调大 maxBuffer(与 ci-fingerprint 同款)。
    maxBuffer: 64 * 1024 * 1024,
    timeout: 120_000,
    killSignal: 'SIGKILL',
  });
  if (result.status !== 0) {
    throw new Error(`fingerprint:generate --platform ${platform} failed: ${result.error?.code ?? `exit ${result.status}`}`);
  }
  return parseFingerprintCliOutput(result.stdout);
}

/** 读产物缓存条目;结构不完整(半份缓存)时视为未命中。 */
function readAppCacheEntry(dir, expectedArch) {
  const miss = (code) => ({ code, app: null });
  if (!existsSync(join(dir, 'meta.json'))) return miss('cache-entry-missing');
  try {
    const meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf8'));
    if (typeof meta.scheme !== 'string' || !meta.scheme) return miss('cache-metadata-invalid');
    const cachedApp = join(dir, `${meta.scheme}.app`);
    if (!existsSync(cachedApp)) return miss('cache-app-missing');
    if (readAppBundleIdentifier(cachedApp) !== expectedBundleId) return miss('cache-bundle-mismatch');
    const architectures = readAppArchitectures(cachedApp);
    if (!architectures.includes(expectedArch)) {
      console.warn(
        `  缓存产物架构不匹配(实际=${architectures.join(',') || '未知'},当前 Simulator 需要=${expectedArch}),忽略并重新构建。`,
      );
      return miss('cache-architecture-mismatch');
    }
    const native = inspectSimulatorNativeIdentity({ appPath: cachedApp, expectedFingerprint: expectedNativeFingerprint });
    if (!native.healthy) return miss(`cache-${native.code}`);
    return { code: 'cache-hit', app: cachedApp };
  } catch {
    return miss('cache-read-failed');
  }
}

/**
 * 把构建产物 .app 存进 fingerprint 缓存。先写 .app 再写 meta.json(meta 是条目
 * 完整性的标记,readAppCacheEntry 缺 meta 即未命中,天然规避半份缓存),最后按
 * LRU 清理只留最近 APP_CACHE_KEEP 份。缓存写失败不影响本次构建结果。
 */
function storeAppCacheEntry(dir, scheme, builtApp, builtBundleId) {
  try {
    rmSync(dir, { recursive: true, force: true });
    mkdirSync(dir, { recursive: true });
    cpSync(builtApp, join(dir, `${scheme}.app`), { recursive: true, verbatimSymlinks: true });
    writeFileSync(join(dir, 'meta.json'), `${JSON.stringify({
      scheme,
      bundleId: builtBundleId,
      createdAt: new Date().toISOString(),
    }, null, 2)}\n`);
    pruneAppCache();
    console.log(`› 产物已入 fingerprint 缓存(下次未动原生层的 worktree 可直接复用)。`);
  } catch (error) {
    console.warn(`  产物缓存写入失败(${error.message}),忽略。`);
  }
}

function assertBundleIdentity(appPath) {
  const actual = readAppBundleIdentifier(appPath);
  if (actual !== expectedBundleId) throw new Error(`Native bundle identity mismatch: ${actual}; expected ${expectedBundleId} (${region}).`);
}

/** 从已构建 .app 的 Info.plist 读取真实 bundle identity。 */
function readAppBundleIdentifier(appPath) {
  return readAppInfoValue(appPath, 'CFBundleIdentifier');
}

/** 读取 .app 可执行文件实际包含的 Mach-O 架构。 */
function readAppArchitectures(appPath) {
  const executableName = readAppInfoValue(appPath, 'CFBundleExecutable');
  return capture('lipo', ['-archs', join(appPath, executableName)])
    .split(/\s+/)
    .filter(Boolean);
}

/** 产物架构不匹配时在安装前失败,避免把 IXUserPresentableErrorDomain 丢给用户。 */
function assertAppSupportsArchitecture(appPath, expectedArch) {
  const architectures = readAppArchitectures(appPath);
  if (architectures.includes(expectedArch)) return;
  throw new Error(
    `Simulator 产物架构错误:实际=${architectures.join(',') || '未知'},期望=${expectedArch};请检查排除 arm64 的 native pod。`,
  );
}

/** 从已构建 .app 的 Info.plist 读取单个原生配置值。 */
function readAppInfoValue(appPath, key) {
  return capture('plutil', [
    '-extract',
    key,
    'raw',
    '-o',
    '-',
    join(appPath, 'Info.plist'),
  ]);
}

/** 按目录 mtime 保留最近 APP_CACHE_KEEP 份;更旧的里只删超过最小年龄的(见常量注释)。 */
function pruneAppCache() {
  const entries = readdirSync(appCacheRoot)
    .map((name) => {
      const dir = join(appCacheRoot, name);
      try {
        const stat = statSync(dir);
        return stat.isDirectory() ? { dir, mtimeMs: stat.mtimeMs } : null;
      } catch {
        return null;
      }
    })
    .filter(Boolean)
    .sort((a, b) => b.mtimeMs - a.mtimeMs);
  for (const entry of entries.slice(APP_CACHE_KEEP)) {
    if (Date.now() - entry.mtimeMs < APP_CACHE_PRUNE_MIN_AGE_MS) continue;
    rmSync(entry.dir, { recursive: true, force: true });
  }
}