@expo-harmony/cli 55.0.26-harmony.1

package/src/cli.ts

@@ -0,0 +1,242 @@
+import path from 'node:path';
+
+import { parseBuildArgs } from './buildHap/options';
+import { parseDoctorArgs } from './doctor/options';
+import { HarmonyCliError } from './errors';
+import { parseExportEmbedArgs } from './exportEmbed/options';
+import { parseModulesArgs } from './modules/options';
+import { parsePrebuildArgs } from './prebuild/options';
+import { resolveProject } from './project';
+import { withHarmonyProjectLockAsync } from './projectLock';
+import { parseRunArgs } from './run/options';
+import { parseStartArgs } from './start/options';
+
+const Help = `Usage: expo-harmony <command> [project] [options]
+
+Commands:
+  start                 Start Expo Metro for Harmony development
+  prebuild              Generate the Harmony native project with Expo CNG
+  prebuild --clean      Safely recreate the managed Harmony directory
+  prebuild --check      Compare generated desired state without project writes
+  build                 Build a HAP without selecting or contacting a device
+  doctor                Validate config, versions, Metro, RNOH, SDK, and signing
+  modules list          List native module candidates and their discovery source
+  modules inspect       Resolve Harmony metadata (--package narrows the result)
+  modules verify        Validate module config, registration conflicts and safe paths
+  export:embed          Export validated Hermes bytecode, assets, and a source map
+  run                   Build, install, and launch the Harmony app
+
+Options:
+  --no-install          Skip dependency install (prebuild) or HAP install (run)
+  --npm|--yarn|--pnpm|--bun
+                        Select the package manager used by prebuild dependency install
+  --skip-dependency-update <packages>
+                        Preserve comma-separated dependency versions
+  --device <id-or-name> Select an HDC target or start a local emulator by name
+  --variant <mode>      Build debug or release (default: debug)
+  --no-bundler          Use an already-running Expo Metro server
+  --app-id <bundleName>
+                        Launch another installed app (requires --no-install when different)
+  --port <number>       Metro and device reverse port (default: 8081)
+  --sync                Re-run prebuild before building
+  --check               Validate an existing export without writing
+  --reset-cache         Reset Metro while exporting or starting
+  -c, --clear           Alias for --reset-cache (start)
+  -h, --help            Show this help
+`;
+
+type Invocation = { command: 'help' }
+  | { command: 'build'; parsed: ReturnType<typeof parseBuildArgs>; projectRoot: string }
+  | { command: 'doctor'; parsed: ReturnType<typeof parseDoctorArgs>; projectRoot: string }
+  | { command: 'export:embed'; parsed: ReturnType<typeof parseExportEmbedArgs>; projectRoot: string }
+  | { command: 'modules'; parsed: ReturnType<typeof parseModulesArgs>; projectRoot: string }
+  | { command: 'prebuild'; parsed: ReturnType<typeof parsePrebuildArgs>; projectRoot: string }
+  | { command: 'run'; parsed: ReturnType<typeof parseRunArgs>; projectRoot: string }
+  | { command: 'start'; parsed: ReturnType<typeof parseStartArgs>; projectRoot: string };
+
+function parseInvocation(argv: string[]): Invocation {
+  if (argv.length === 0 || (argv.length === 1 && ['--help', '-h'].includes(argv[0]))) {
+    return { command: 'help' };
+  }
+
+  const command = argv[0] as Exclude<Invocation['command'], 'help'>;
+  if (!['build', 'prebuild', 'doctor', 'export:embed', 'modules', 'run', 'start'].includes(command)) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unknown command: ${command}`, {
+      operation: 'parse-arguments',
+    });
+  }
+
+  const parsed = command === 'build'
+    ? parseBuildArgs(argv.slice(1))
+    : command === 'prebuild'
+      ? parsePrebuildArgs(argv.slice(1), { allowProject: true })
+      : command === 'doctor'
+        ? parseDoctorArgs(argv.slice(1))
+        : command === 'export:embed'
+          ? parseExportEmbedArgs(argv.slice(1))
+          : command === 'modules'
+            ? parseModulesArgs(argv.slice(1))
+            : command === 'start'
+              ? parseStartArgs(argv.slice(1))
+              : parseRunArgs(argv.slice(1));
+  if (parsed.help) return { command: 'help' };
+
+  const projectRoot = resolveProject(parsed.project ? path.resolve(parsed.project) : process.cwd());
+
+  return { command, parsed, projectRoot } as Invocation;
+}
+
+async function runAsync(
+  argv: string[] = process.argv.slice(2),
+  io: Pick<Console, 'error' | 'log' | 'warn'> = console
+): Promise<number> {
+  const invocation = parseInvocation(argv);
+  if (invocation.command === 'help') {
+    io.log(Help);
+    return 0;
+  }
+
+  if (invocation.command === 'start') {
+    const { startExpoMetroAsync } = await import('./run/metro.js');
+    const metro = await startExpoMetroAsync(invocation.projectRoot, {
+      ...invocation.parsed,
+      interactive: true,
+    });
+
+    try {
+      if (metro.owner === 'existing') {
+        io.log(`Expo Metro is already running on port ${metro.port}.`);
+        if (invocation.parsed.resetCache) {
+          io.warn('Stop the existing Metro server and run this command again to reset its cache.');
+        }
+      } else {
+        io.log('\n› Logs for your project will appear below. Press Ctrl+C to exit.');
+        await metro.waitAsync();
+      }
+
+      return 0;
+    } finally {
+      await metro.stop();
+    }
+  }
+
+  if (invocation.command === 'doctor') {
+    const { doctorAsync, formatDoctor } = await import('./doctor/doctor.js');
+    const result = await doctorAsync(invocation.projectRoot, { requireBuildTools: true });
+
+    io.log(formatDoctor(result));
+
+    return result.ok ? 0 : 1;
+  }
+
+  if (invocation.command === 'build') {
+    const { buildHarmonyAsync } = await import('./buildHap/build.js');
+    const result = await buildHarmonyAsync(invocation.projectRoot, {
+      ...invocation.parsed,
+      io,
+    });
+
+    io.log(`Built ${result.variant} HAP at ${result.hapPath}; no device actions were performed.`);
+
+    return 0;
+  }
+
+  if (invocation.command === 'export:embed') {
+    const { exportEmbedAsync } = await import('./exportEmbed/export.js');
+    const result = await exportEmbedAsync(invocation.projectRoot, invocation.parsed);
+
+    if (invocation.parsed.check) io.log('Harmony export bundle, assets, and source map are valid.');
+    else io.log(`Exported Hermes bytecode ${result.bundle.path} with ${result.assets.length} asset file(s).`);
+
+    return 0;
+  }
+
+  if (invocation.command === 'modules') {
+    const { formatModulesResult, runModulesCommandAsync } = await import('./modules/modules.js');
+    const result = await runModulesCommandAsync(invocation.projectRoot, invocation.parsed);
+
+    io.log(formatModulesResult(result));
+    return result.ok ? 0 : 1;
+  }
+
+  if (invocation.command === 'run') {
+    const { runHarmonySessionAsync } = await import('./run/run.js');
+
+    const session = await runHarmonySessionAsync(invocation.projectRoot, {
+      ...invocation.parsed,
+      interactiveBundler: true,
+      io,
+    });
+    const { result } = session;
+
+    io.log(`Launched ${result.bundleName} on ${result.device.id} (${result.variant}).`);
+    if (session.metro.owner === 'started') {
+      io.log('\n› Logs for your project will appear below. Press Ctrl+C to exit.');
+      await session.metro.waitAsync();
+    }
+
+    return 0;
+  }
+
+  const { check, clean, passthrough } = invocation.parsed;
+
+  if (check && passthrough.length) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--check cannot be combined with mutating prebuild options.');
+  }
+
+  return withHarmonyProjectLockAsync(
+    invocation.projectRoot,
+    check ? 'prebuild-check' : 'prebuild',
+    async () => {
+      if (clean) {
+        const { assertSafeCleanTarget } = await import('./prebuild/clean.js');
+        await assertSafeCleanTarget(invocation.projectRoot);
+      }
+
+      const { doctorAsync, formatDoctor } = await import('./doctor/doctor.js');
+      const doctor = await doctorAsync(invocation.projectRoot, {
+        requireBuildTools: false,
+        validateGeneratedProject: !clean,
+        validateModules: false,
+      });
+      if (!doctor.ok) {
+        io.error(formatDoctor(doctor));
+        throw new HarmonyCliError('ERR_HARMONY_DOCTOR_FAILED', 'Harmony doctor found blocking errors.', {
+          operation: 'doctor',
+        });
+      }
+
+      for (const item of doctor.checks.filter(item => item.status === 'warn')) io.warn(`! ${item.message}`);
+
+      if (check) {
+        const { checkAsync } = await import('./prebuild/check.js');
+        const result = await checkAsync(invocation.projectRoot);
+
+        if (result.clean) io.log('Harmony CNG output is up to date.');
+        else for (const change of result.changes) io.log(`${change.type}: ${change.path}`);
+
+        return result.clean ? 0 : 2;
+      }
+
+      const { prebuildParsedAsync } = await import('./prebuild/prebuild.js');
+      await prebuildParsedAsync(invocation.projectRoot, passthrough);
+
+      return 0;
+    });
+}
+
+async function main(argv = process.argv.slice(2)) {
+  try {
+    const code = await runAsync(argv);
+
+    process.exitCode = code;
+  } catch (error) {
+    const code = error.code || 'ERR_HARMONY_UNKNOWN';
+
+    console.error(`[${code}] ${error.message}`);
+
+    process.exitCode = error.exitCode || 1;
+  }
+}
+
+export { main, runAsync };

package/src/doctor/doctor.ts

@@ -0,0 +1,267 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { getConfig } from '@expo/config';
+import { normalizeHarmonyConfig } from '@expo-harmony/config-plugins';
+import { verifyModulesAsync } from '@expo-harmony/expo-modules-autolinking';
+import { isRnohAutolinkingDisabled } from '@expo-harmony/prebuild-config/native-project';
+import { validateHarmonySigningConfigFile } from '@expo-harmony/prebuild-config/signing';
+
+import { spawnAsync } from '../process';
+import { withHarmonyProjectLockAsync } from '../projectLock';
+import {
+  resolveHarmonyBuildPlanIfPresentAsync,
+  resolveHarmonyToolchain,
+  type HarmonyTool,
+} from '../tools';
+import { RequiredProjectPackages } from '../upstream';
+
+export interface DoctorCheck {
+  details?: unknown;
+  id: string;
+  message: string;
+  status: 'error' | 'pass' | 'warn';
+}
+
+export interface DoctorResult {
+  checks: DoctorCheck[];
+  ok: boolean;
+  projectRoot: string;
+}
+
+interface DoctorOptions {
+  requireBuildTools?: boolean;
+  requireDeviceTools?: boolean;
+  validateGeneratedProject?: boolean;
+  validateModules?: boolean;
+}
+
+function hasPlugin(plugins, packageName) {
+  return (plugins || []).some(plugin => (Array.isArray(plugin) ? plugin[0] : plugin) === packageName);
+}
+
+function check(id: string, status: DoctorCheck['status'], message: string, details?: unknown): DoctorCheck {
+  return { id, status, message, ...(details ? { details } : {}) };
+}
+
+function canResolvePackage(projectRoot, packageName) {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+  try {
+    projectRequire.resolve(`${packageName}/package.json`);
+    return true;
+  } catch {
+    try {
+      projectRequire.resolve(packageName);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+async function validateMetroConfigAsync(projectRoot) {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+  let metroConfig;
+
+  try {
+    metroConfig = projectRequire('metro-config');
+  } catch (cause) {
+    throw new Error('Cannot load the project-local metro-config package.', { cause });
+  }
+
+  if (typeof metroConfig.resolveConfig !== 'function') {
+    const version = (() => {
+      try {
+        return projectRequire('metro-config/package.json').version;
+      } catch {
+        return 'unknown';
+      }
+    })();
+
+    throw new Error(`metro-config ${version} does not expose resolveConfig().`);
+  }
+
+  const hadMetroTarget = Object.hasOwn(process.env, 'EXPO_METRO_TARGET');
+  const previousMetroTarget = process.env.EXPO_METRO_TARGET;
+  let resolved;
+
+  try {
+    process.env.EXPO_METRO_TARGET = 'harmony';
+    resolved = await metroConfig.resolveConfig(undefined, projectRoot);
+  } finally {
+    if (hadMetroTarget) process.env.EXPO_METRO_TARGET = previousMetroTarget;
+    else delete process.env.EXPO_METRO_TARGET;
+  }
+
+  const config = resolved?.config;
+  const platforms = config?.resolver?.platforms;
+  const conditions = config?.resolver?.unstable_conditionsByPlatform?.harmony;
+
+  if (!Array.isArray(platforms) || !platforms.includes('harmony')
+    || !Array.isArray(conditions) || !conditions.includes('harmony')
+    || typeof config?.resolver?.resolveRequest !== 'function') {
+    throw new Error('The resolved Metro config must register the harmony platform, Harmony conditions, and a resolver.');
+  }
+}
+
+async function doctorUnlockedAsync(projectRoot: string, options: DoctorOptions = {}): Promise<DoctorResult> {
+  const checks: DoctorCheck[] = [];
+  const unavailableToolStatus = options.requireBuildTools ? 'error' : 'warn';
+  let config;
+
+  try {
+    config = getConfig(projectRoot, {
+      isModdedConfig: true,
+      skipSDKVersionRequirement: true,
+    }).exp;
+    normalizeHarmonyConfig(config);
+    checks.push(check('app-config', 'pass', 'Harmony app config is valid.'));
+  } catch (error) {
+    checks.push(check('app-config', 'error', error.message, { code: error.code || 'ERR_HARMONY_CONFIG_INVALID' }));
+  }
+
+  if (config) {
+    checks.push(hasPlugin(config.plugins, '@expo-harmony/prebuild-config')
+      ? check('config-plugin', 'pass', '@expo-harmony/prebuild-config is registered.')
+      : check('config-plugin', 'error', 'Add @expo-harmony/prebuild-config to expo.plugins.'));
+    const harmony = (config as typeof config & {
+      harmony?: { signingConfigFile?: string };
+    }).harmony;
+
+    if (harmony?.signingConfigFile) {
+      try {
+        const signing = await validateHarmonySigningConfigFile(projectRoot, harmony.signingConfigFile);
+        checks.push(check('signing', 'pass', `Harmony signing config ${signing.name} is valid.`));
+      } catch (error) {
+        checks.push(check('signing', 'error', error.message, { code: error.code || 'ERR_HARMONY_SIGNING_INVALID' }));
+      }
+    } else {
+      checks.push(check('signing', 'warn', 'No external signing config is set; unsigned generation remains available.'));
+    }
+  }
+
+  try {
+    await validateMetroConfigAsync(projectRoot);
+    checks.push(check('metro', 'pass', 'The resolved Metro config enables Harmony.'));
+  } catch (error) {
+    checks.push(check('metro', 'error', `Cannot load a Harmony-enabled Metro config: ${error.message}`, { code: error.code || 'ERR_HARMONY_METRO_CONFIG' }));
+  }
+
+  for (const packageName of RequiredProjectPackages) {
+    if (canResolvePackage(projectRoot, packageName)) {
+      checks.push(check(`package:${packageName}`, 'pass', `${packageName} is resolvable.`));
+    } else {
+      checks.push(check(`package:${packageName}`, 'error', `${packageName} is not resolvable from the app.`));
+    }
+  }
+
+  if (options.validateModules !== false) {
+    try {
+      const result = await verifyModulesAsync({ platform: 'harmony', projectRoot });
+      const errors = result.diagnostics.filter(item => item.severity === 'error');
+      const warnings = result.diagnostics.filter(item => item.severity === 'warning');
+
+      if (errors.length > 0) {
+        checks.push(check(
+          'expo-modules',
+          'error',
+          `Harmony Expo Modules verification found ${errors.length} error(s). Run 'expo-harmony modules verify' for details.`,
+          { diagnostics: result.diagnostics }
+        ));
+      } else if (warnings.length > 0) {
+        checks.push(check(
+          'expo-modules',
+          'warn',
+          `Verified ${result.modules.length} Harmony native module(s) with ${warnings.length} warning(s).`,
+          { diagnostics: warnings }
+        ));
+      } else {
+        checks.push(check('expo-modules', 'pass', `Verified ${result.modules.length} Harmony native module(s).`));
+      }
+    } catch (error) {
+      checks.push(check(
+        'expo-modules',
+        'error',
+        `Harmony Expo Modules verification failed: ${error.message}`,
+        { code: error.code || 'ERR_HARMONY_AUTOLINKING_FAILED' }
+      ));
+    }
+  }
+
+  const toolchain = resolveHarmonyToolchain();
+  let sdkCheck;
+
+  if (toolchain.sdkHome) {
+    sdkCheck = check('harmony-sdk', 'pass', `Complete Harmony SDK root was resolved at ${toolchain.sdkHome}.`);
+  } else {
+    sdkCheck = check('harmony-sdk', unavailableToolStatus, 'No complete Harmony SDK root with HMS and OpenHarmony components was found; generation works but HAP build cannot be verified.');
+  }
+
+  checks.push(sdkCheck);
+
+  const tools: Array<[string, HarmonyTool, string[], DoctorCheck['status']]> = [
+    ['ohpm', toolchain.ohpm, ['--version'], unavailableToolStatus],
+    ['hvigor-command', toolchain.hvigor, ['--version'], unavailableToolStatus],
+  ];
+  if (options.requireDeviceTools !== false) {
+    tools.unshift(['hdc', toolchain.hdc, ['-v'], unavailableToolStatus]);
+  }
+  for (const [id, tool, versionArgs, unavailableStatus] of tools) {
+    try {
+      const result = await spawnAsync(tool.command, [...tool.args, ...versionArgs], {
+        capture: true,
+        cwd: projectRoot,
+        operation: `doctor-${id}`,
+        timeoutMs: 10_000,
+      });
+      checks.push(result.code === 0 && !result.timedOut
+        ? check(id, 'pass', `${tool.command} is available through ${tool.source}.`)
+        : check(id, unavailableStatus, `${tool.command} is unavailable or unhealthy; HAP build cannot be verified.`));
+    } catch {
+      checks.push(check(id, unavailableStatus, `${tool.command} is unavailable; generation remains available.`));
+    }
+  }
+
+  if (options.validateGeneratedProject !== false) {
+    try {
+      const plan = await resolveHarmonyBuildPlanIfPresentAsync(projectRoot);
+      if (plan && fs.existsSync(plan.harmonyRoot)) {
+        if (!fs.existsSync(plan.projectFiles.rootHvigor)
+          || !fs.existsSync(plan.projectFiles.moduleHvigor)) {
+          checks.push(check('hvigor', 'error', 'Generated root and module Hvigor files are required.'));
+        } else {
+          const content = await fs.promises.readFile(plan.projectFiles.moduleHvigor, 'utf8');
+          checks.push(isRnohAutolinkingDisabled(content)
+            ? check('hvigor-autolinking', 'pass', 'RNOH duplicate autolinking is disabled.')
+            : check('hvigor-autolinking', 'error', 'The generated module Hvigor file must disable RNOH autolinking.'));
+        }
+      }
+    } catch (error) {
+      checks.push(check('harmony-project', 'error', error.message, { code: error.code || 'ERR_HARMONY_TEMPLATE_INVALID' }));
+    }
+  }
+
+  return {
+    checks,
+    ok: checks.every(item => item.status !== 'error'),
+    projectRoot,
+  };
+}
+
+async function doctorAsync(projectRoot: string, options: DoctorOptions = {}): Promise<DoctorResult> {
+  return withHarmonyProjectLockAsync(
+    projectRoot,
+    'doctor',
+    () => doctorUnlockedAsync(projectRoot, options)
+  );
+}
+
+function formatDoctor(result: DoctorResult): string {
+  return result.checks.map((item) => {
+    const symbol = item.status === 'pass' ? '✓' : item.status === 'warn' ? '!' : '✗';
+    return `${symbol} [${item.status}] ${item.message}`;
+  }).join('\n');
+}
+
+export { doctorAsync, formatDoctor };

package/src/doctor/options.ts

@@ -0,0 +1,17 @@
+import { CommonOptions, parseArgs } from '../args';
+import { HarmonyCliError } from '../errors';
+
+function parseDoctorArgs(argv: string[]) {
+  const { positionals, values } = parseArgs(CommonOptions, argv);
+
+  if (positionals.length > 1) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unexpected doctor positional argument: ${positionals[1]}`, { operation: 'parse-arguments' });
+  }
+
+  return {
+    help: Boolean(values.help),
+    project: positionals[0],
+  };
+}
+
+export { parseDoctorArgs };

package/src/entry.ts

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { resolveEntryPoint } from '@expo/config/paths';
+
+import { HarmonyCliError } from './errors';
+
+function isFile(file) {
+  try {
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveHarmonyEntryPoint(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    let entry = resolveEntryPoint(projectRoot, { pkg, platform: 'harmony' });
+
+    if (!isFile(entry) && typeof pkg.main === 'string' && pkg.main) {
+      const logicalPackageRoot = entry;
+      const resolved = createRequire(packageJsonPath).resolve(pkg.main);
+
+      try {
+        const relative = path.relative(fs.realpathSync(logicalPackageRoot), fs.realpathSync(resolved));
+        entry = relative !== '..'
+          && !relative.startsWith(`..${path.sep}`)
+          && !path.isAbsolute(relative)
+          ? path.join(logicalPackageRoot, relative)
+          : resolved;
+      } catch {
+        entry = resolved;
+      }
+    }
+
+    if (!isFile(entry)) throw new Error('Resolved entry is not a file.');
+
+    return entry;
+  } catch (cause) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_ENTRY', 'Cannot resolve the Expo entry point for the Harmony bundle.', { cause, operation: 'resolve-entry-point' });
+  }
+}
+
+export { resolveHarmonyEntryPoint };

package/src/errors.ts

@@ -0,0 +1,22 @@
+interface HarmonyCliErrorOptions {
+  cause?: unknown;
+  exitCode?: number;
+  operation?: string;
+}
+
+class HarmonyCliError extends Error {
+  code: string;
+  exitCode: number;
+  operation: string;
+
+  constructor(code: string, message: string, options: HarmonyCliErrorOptions = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+
+    this.name = 'HarmonyCliError';
+    this.code = code;
+    this.exitCode = options.exitCode || 1;
+    this.operation = options.operation || 'cli';
+  }
+}
+
+export { HarmonyCliError };

package/src/expo.ts

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { HarmonyCliError } from './errors';
+
+interface ExpoHermesBundleOptions {
+  code: string;
+  filename: string;
+  map: string | null;
+  minify?: boolean;
+  projectRoot: string;
+}
+
+interface ExpoHermesBundleOutput {
+  hbc: Uint8Array;
+  sourcemap: string | null;
+}
+
+type ExpoHermesBuilder = (
+  options: ExpoHermesBundleOptions
+) => Promise<ExpoHermesBundleOutput>;
+
+function resolveExpoCli(projectRoot) {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+  let packageJsonPath;
+
+  try {
+    packageJsonPath = projectRequire.resolve('expo/package.json');
+  } catch (cause) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPO_CLI_NOT_FOUND', 'Cannot resolve the project-local expo package.', { cause, operation: 'resolve-expo-cli' });
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const bin = typeof packageJson.bin === 'string' ? packageJson.bin : packageJson.bin?.expo;
+
+  if (typeof bin !== 'string' || !bin) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPO_CLI_NOT_FOUND', 'The project-local expo package has no expo binary.', { operation: 'resolve-expo-cli' });
+  }
+
+  const cliPath = path.resolve(path.dirname(packageJsonPath), bin);
+
+  if (!fs.existsSync(cliPath)) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPO_CLI_NOT_FOUND', `Expo CLI binary does not exist: ${cliPath}`, { operation: 'resolve-expo-cli' });
+  }
+
+  return { cliPath, packageJsonPath };
+}
+
+function resolveExpoHermesBuilder(projectRoot: string): ExpoHermesBuilder {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+  let packageJsonPath;
+
+  try {
+    packageJsonPath = projectRequire.resolve('@expo/metro-config/package.json');
+  } catch (cause) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_EXPORT_HERMES',
+      'Cannot resolve the project-local @expo/metro-config package required for Hermes export.',
+      { cause, operation: 'resolve-expo-hermes' }
+    );
+  }
+
+  const modulePath = path.join(path.dirname(packageJsonPath), 'build', 'serializer', 'exportHermes.js');
+  let moduleExports;
+
+  try {
+    moduleExports = projectRequire(modulePath);
+  } catch (cause) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_EXPORT_HERMES',
+      `Cannot load the Expo Hermes exporter: ${modulePath}`,
+      { cause, operation: 'resolve-expo-hermes' }
+    );
+  }
+
+  if (typeof moduleExports?.buildHermesBundleAsync !== 'function') {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_EXPORT_HERMES',
+      'The project-local @expo/metro-config package does not expose buildHermesBundleAsync().',
+      { operation: 'resolve-expo-hermes' }
+    );
+  }
+
+  return moduleExports.buildHermesBundleAsync as ExpoHermesBuilder;
+}
+
+export { resolveExpoCli, resolveExpoHermesBuilder };
+export type { ExpoHermesBuilder };