@expo-harmony/cli 55.0.26-harmony.1

package/src/exportEmbed/export.ts

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+
+import { doctorAsync, type DoctorResult } from '../doctor/doctor';
+import { resolveHarmonyEntryPoint } from '../entry';
+import { HarmonyCliError } from '../errors';
+import { withHarmonyProjectLockAsync } from '../projectLock';
+import { resolveHarmonyBuildPlanAsync } from '../tools';
+import { formatDiagnostics, spawnAsync } from '../process';
+import { resolveExpoCli, resolveExpoHermesBuilder } from '../expo';
+import {
+  assertHermesBundle, assertSourceMap, exportPaths,
+  publishExportAsync, validatePublishedExportAsync,
+  type HarmonyExportManifest,
+} from './manifest';
+
+export interface ExportOptions {
+  check?: boolean;
+  resetCache?: boolean;
+  skipDoctor?: boolean;
+  timeoutMs?: number;
+}
+
+export interface ExportTemporary {
+  assets: string;
+  bundle: string;
+  javascript: string;
+  metroSourceMap: string;
+  sourceMap: string;
+}
+
+function createExpoExportEmbedArgs(
+  projectRoot: string,
+  entryFile: string,
+  temporary: ExportTemporary,
+  options: ExportOptions = {}
+) {
+  return [
+    'export:embed',
+    '--platform', 'harmony',
+    '--entry-file', entryFile,
+    '--bundle-output', temporary.javascript,
+    '--assets-dest', temporary.assets,
+    '--dev', 'false',
+    '--minify', 'false',
+    '--sourcemap-output', temporary.metroSourceMap,
+    '--sourcemap-sources-root', '.',
+    '--unstable-transform-profile', 'hermes-stable',
+    ...(options.resetCache ? ['--reset-cache=true'] : []),
+    projectRoot,
+  ];
+}
+
+function assertDoctor(result: DoctorResult) {
+  if (result.ok) return;
+
+  const failing = result.checks.filter(check => check.status === 'error').map(check => check.id);
+  throw new HarmonyCliError('ERR_HARMONY_EXPORT_DOCTOR', `Harmony doctor found blocking checks: ${failing.join(', ') || 'unknown'}.`, { operation: 'doctor' });
+}
+
+async function exportEmbedUnlockedAsync(
+  projectRoot: string,
+  options: ExportOptions = {}
+): Promise<HarmonyExportManifest> {
+  if (!options.skipDoctor) assertDoctor(await doctorAsync(projectRoot));
+
+  const plan = await resolveHarmonyBuildPlanAsync(projectRoot, { buildMode: 'release' });
+  const paths = exportPaths(plan);
+
+  if (options.check) return await validatePublishedExportAsync(paths);
+
+  const entryFile = resolveHarmonyEntryPoint(projectRoot);
+  const temporaryRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'expo-harmony-export-'));
+  const temporary: ExportTemporary = {
+    assets: path.join(temporaryRoot, 'assets'),
+    bundle: path.join(temporaryRoot, 'hermes_bundle.hbc'),
+    javascript: path.join(temporaryRoot, 'index.js'),
+    metroSourceMap: path.join(temporaryRoot, 'index.js.map'),
+    sourceMap: path.join(temporaryRoot, 'hermes_bundle.hbc.map'),
+  };
+
+  try {
+    await fs.promises.mkdir(temporary.assets, { recursive: true });
+
+    const expo = resolveExpoCli(projectRoot);
+    const result = await spawnAsync(process.execPath, [
+      expo.cliPath,
+      ...createExpoExportEmbedArgs(projectRoot, entryFile, temporary, options),
+    ], {
+      capture: true,
+      cwd: projectRoot,
+      env: {
+        ...process.env,
+        EXPO_METRO_TARGET: 'harmony',
+        HERMES_V1_ENABLED: 'true',
+        NODE_ENV: 'production',
+      },
+      operation: 'expo-export-embed',
+      outputLimit: 4 * 1024 * 1024,
+      timeoutMs: options.timeoutMs || 10 * 60_000,
+    });
+
+    if (result.code !== 0 || result.timedOut) {
+      const diagnostics = formatDiagnostics(result);
+      throw new HarmonyCliError(
+        'ERR_HARMONY_EXPORT_FAILED',
+        `Expo export:embed exited with code ${result.code}${result.timedOut ? ' after timing out' : ''}.${diagnostics ? `\n${diagnostics}` : ''}`,
+        { exitCode: result.code || 1, operation: 'expo-export-embed' }
+      );
+    }
+
+    // Expo 55 only infers Hermes for iOS and Android. Keep Harmony bundling in the Expo CLI,
+    // then explicitly hand its JS and source map to Expo's own Hermes exporter.
+    try {
+      const [code, map] = await Promise.all([
+        fs.promises.readFile(temporary.javascript, 'utf8'),
+        fs.promises.readFile(temporary.metroSourceMap, 'utf8'),
+      ]);
+      const buildHermesBundleAsync = resolveExpoHermesBuilder(projectRoot);
+      // Expo resolves hermes-compiler from react-native. For Harmony, resolve it
+      // from RNOH instead of the app's Android/iOS React Native installation.
+      const projectRequire = createRequire(path.join(projectRoot, 'package.json'));
+      const harmonyRuntime = path.dirname(projectRequire.resolve('@react-native-oh/react-native-harmony/package.json'));
+      const compilerModules = path.join(temporaryRoot, 'node_modules');
+      await fs.promises.mkdir(compilerModules);
+      await fs.promises.symlink(harmonyRuntime, path.join(compilerModules, 'react-native'),
+        process.platform === 'win32' ? 'junction' : 'dir');
+      const output = await buildHermesBundleAsync({
+        code,
+        filename: entryFile,
+        map,
+        minify: true,
+        projectRoot: temporaryRoot,
+      });
+
+      if (!(output?.hbc instanceof Uint8Array) || typeof output.sourcemap !== 'string') {
+        throw new Error('Expo did not return Hermes bytecode and a composed source map.');
+      }
+
+      await Promise.all([
+        fs.promises.writeFile(temporary.bundle, output.hbc),
+        fs.promises.writeFile(temporary.sourceMap, output.sourcemap),
+      ]);
+    } catch (cause) {
+      if (cause instanceof HarmonyCliError) throw cause;
+      throw new HarmonyCliError(
+        'ERR_HARMONY_EXPORT_HERMES',
+        'Expo failed to compile the Harmony bundle to Hermes bytecode.',
+        { cause, operation: 'expo-hermes-export' }
+      );
+    }
+
+    const bytecode = await assertHermesBundle(temporary.bundle);
+    await assertSourceMap(temporary.sourceMap);
+
+    return await publishExportAsync(projectRoot, paths, temporary, entryFile, bytecode);
+  } finally {
+    await fs.promises.rm(temporaryRoot, { force: true, recursive: true });
+  }
+}
+
+async function exportEmbedAsync(
+  projectRoot: string,
+  options: ExportOptions = {}
+): Promise<HarmonyExportManifest> {
+  return withHarmonyProjectLockAsync(
+    projectRoot,
+    'export:embed',
+    () => exportEmbedUnlockedAsync(projectRoot, options)
+  );
+}
+
+export {
+  exportEmbedAsync,
+};

package/src/exportEmbed/manifest.ts

@@ -0,0 +1,222 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { HarmonyCliError } from '../errors';
+import { atomicCopy, atomicWriteJson, describeFile, listFiles, removeEmptyParents } from '../file';
+import { assertSafeRelative, isInside, toPosixPath } from '../path';
+import type { ExportTemporary } from './export';
+
+export interface HarmonyExportFile {
+  path: string;
+  sha256: string;
+  size: number;
+}
+
+export interface HarmonyExportManifest {
+  assets: HarmonyExportFile[];
+  bundle: HarmonyExportFile & { bytecodeVersion: number };
+  entryFile: string;
+  platform: 'harmony';
+  schemaVersion: 1;
+  sourceMap: HarmonyExportFile;
+  transformProfile: 'hermes-stable';
+}
+
+const HermesMagic = Buffer.from('c61fbc03c103191f', 'hex');
+const ManifestSchemaVersion = 1;
+
+function exportPaths(plan: {
+  exportPaths: {
+    bundle: string;
+    manifest: string;
+    metadataRoot: string;
+    rawfileRoot: string;
+    sourceMap: string;
+  };
+}) {
+  return plan.exportPaths;
+}
+
+async function assertHermesBundle(file) {
+  let handle;
+  try {
+    handle = await fs.promises.open(file, 'r');
+    const header = Buffer.alloc(12);
+    const { bytesRead } = await handle.read(header, 0, header.length, 0);
+    const stat = await handle.stat();
+
+    if (bytesRead < header.length || stat.size <= header.length
+      || header.subarray(0, HermesMagic.length).toString('hex') !== HermesMagic.toString('hex')) {
+      throw new Error('Expo export did not produce non-empty Hermes bytecode.');
+    }
+
+    return { bytecodeVersion: header.readUInt32LE(8), size: stat.size };
+  } catch (cause) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_INVALID_BUNDLE', 'The Harmony export output is not a valid Hermes bytecode bundle.', { cause, operation: 'validate-export' });
+  } finally {
+    await handle?.close();
+  }
+}
+
+async function assertSourceMap(file) {
+  try {
+    const contents = await fs.promises.readFile(file, 'utf8');
+    const sourceMap = JSON.parse(contents);
+    const paths = JSON.stringify({ sourceRoot: sourceMap?.sourceRoot, sources: sourceMap?.sources });
+    const sourcePaths = [sourceMap?.sourceRoot, ...(sourceMap?.sources || [])]
+      .filter(value => typeof value === 'string');
+    const hasAbsoluteSource = sourcePaths.some(value => (
+      path.posix.isAbsolute(value) || path.win32.isAbsolute(value) || /^[A-Za-z][A-Za-z0-9+.-]*:\/\//u.test(value)
+    ));
+
+    if (sourceMap?.version !== 3 || !Array.isArray(sourceMap.sources)
+      || hasAbsoluteSource || paths.includes(os.homedir())) {
+      throw new Error('Invalid or host-specific source map.');
+    }
+
+    return await describeFile(file);
+  } catch (cause) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_INVALID_SOURCEMAP', 'Expo export did not produce a portable source map.', { cause, operation: 'validate-export' });
+  }
+}
+
+async function readPreviousManifest(file: string): Promise<HarmonyExportManifest | null> {
+  try {
+    const manifest = JSON.parse(await fs.promises.readFile(file, 'utf8'));
+    if (manifest?.schemaVersion !== ManifestSchemaVersion || !Array.isArray(manifest.assets)) {
+      throw new Error('Unsupported export manifest schema.');
+    }
+
+    for (const asset of manifest.assets) {
+      assertSafeRelative(asset?.path, 'Previous export manifest');
+    }
+
+    return manifest;
+  } catch (cause) {
+    if (cause.code === 'ENOENT') return null;
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_MANIFEST', 'Cannot read the previous Harmony export manifest.', { cause, operation: 'publish-export' });
+  }
+}
+
+async function publishExportAsync(
+  projectRoot: string,
+  paths: ReturnType<typeof exportPaths>,
+  temporary: ExportTemporary,
+  entryFile: string,
+  bytecode: Awaited<ReturnType<typeof assertHermesBundle>>
+) {
+  const previous = await readPreviousManifest(paths.manifest);
+  const previouslyOwned = new Set((previous?.assets || []).map(asset => asset.path));
+  const assetFiles = await listFiles(temporary.assets);
+  const assetOutputs = [];
+
+  for (const source of assetFiles) {
+    const relative = toPosixPath(path.relative(temporary.assets, source));
+    const nativeRelative = assertSafeRelative(relative, 'Expo asset output');
+    const destination = path.join(paths.rawfileRoot, nativeRelative);
+    if (await fs.promises.lstat(destination).catch(error => error.code === 'ENOENT' ? null : Promise.reject(error))) {
+      if (!previouslyOwned.has(relative)) {
+        throw new HarmonyCliError('ERR_HARMONY_EXPORT_COLLISION', `Expo asset output collides with an unmanaged raw resource: ${relative}.`, { operation: 'publish-export' });
+      }
+    }
+
+    assetOutputs.push({ descriptor: { path: relative, ...(await describeFile(source)) }, source });
+  }
+
+  assetOutputs.sort((left, right) => left.descriptor.path.localeCompare(right.descriptor.path, 'en'));
+  const assets = assetOutputs.map(output => output.descriptor);
+
+  const bundle = await describeFile(temporary.bundle);
+  const sourceMap = await describeFile(temporary.sourceMap);
+  const manifest: HarmonyExportManifest = {
+    assets,
+    bundle: {
+      bytecodeVersion: bytecode.bytecodeVersion,
+      path: toPosixPath(path.relative(projectRoot, paths.bundle)),
+      ...bundle,
+    },
+    entryFile: toPosixPath(path.relative(projectRoot, entryFile)),
+    platform: 'harmony',
+    schemaVersion: ManifestSchemaVersion,
+    sourceMap: {
+      path: toPosixPath(path.relative(projectRoot, paths.sourceMap)),
+      ...sourceMap,
+    },
+    transformProfile: 'hermes-stable',
+  };
+
+  try {
+    await atomicCopy(temporary.bundle, paths.bundle, paths.rawfileRoot);
+    await atomicCopy(temporary.sourceMap, paths.sourceMap, paths.metadataRoot);
+    for (const output of assetOutputs) {
+      const relative = output.descriptor.path;
+      await atomicCopy(
+        output.source,
+        path.join(paths.rawfileRoot, assertSafeRelative(relative, 'Expo asset output')),
+        paths.rawfileRoot
+      );
+    }
+    await atomicWriteJson(manifest, paths.manifest, path.dirname(paths.manifest));
+
+    const nextOwned = new Set(assets.map(asset => asset.path));
+    for (const stale of previouslyOwned) {
+      if (nextOwned.has(stale)) continue;
+      const destination = path.join(paths.rawfileRoot, assertSafeRelative(stale, 'Previous export manifest'));
+      if (!isInside(paths.rawfileRoot, destination)) continue;
+      await fs.promises.rm(destination, { force: true });
+      await removeEmptyParents(destination, paths.rawfileRoot);
+    }
+  } catch (cause) {
+    if (cause instanceof HarmonyCliError) {
+      throw new HarmonyCliError(cause.code, cause.message, {
+        cause,
+        exitCode: cause.exitCode,
+        operation: cause.operation,
+      });
+    }
+
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_PUBLISH', 'Cannot publish the validated Harmony bundle and assets.', { cause, operation: 'publish-export' });
+  }
+
+  return manifest;
+}
+
+async function validatePublishedExportAsync(paths: ReturnType<typeof exportPaths>) {
+  const manifest = await readPreviousManifest(paths.manifest);
+  if (!manifest) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_MANIFEST', 'Harmony export manifest does not exist. Run expo-harmony export:embed first.', { operation: 'check-export' });
+  }
+
+  const bytecode = await assertHermesBundle(paths.bundle);
+  const sourceMap = await assertSourceMap(paths.sourceMap);
+  const expectedBundle = await describeFile(paths.bundle);
+  if (manifest.bundle?.sha256 !== expectedBundle.sha256
+    || manifest.bundle?.size !== expectedBundle.size
+    || manifest.bundle?.bytecodeVersion !== bytecode.bytecodeVersion
+    || manifest.sourceMap?.sha256 !== sourceMap.sha256
+    || manifest.sourceMap?.size !== sourceMap.size) {
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_MANIFEST', 'Harmony bundle or source map differs from the export manifest.', { operation: 'check-export' });
+  }
+
+  for (const asset of manifest.assets) {
+    const file = path.join(paths.rawfileRoot, assertSafeRelative(asset.path, 'Export manifest'));
+    const actual = await describeFile(file).catch((cause) => {
+      throw new HarmonyCliError('ERR_HARMONY_EXPORT_MANIFEST', `Harmony export asset is missing or invalid: ${asset.path}.`, { cause, operation: 'check-export' });
+    });
+    if (actual.sha256 !== asset.sha256 || actual.size !== asset.size) {
+      throw new HarmonyCliError('ERR_HARMONY_EXPORT_MANIFEST', `Harmony export asset differs from the manifest: ${asset.path}.`, { operation: 'check-export' });
+    }
+  }
+
+  return manifest;
+}
+
+export {
+  HermesMagic,
+  assertHermesBundle,
+  assertSourceMap,
+  exportPaths,
+  publishExportAsync,
+  validatePublishedExportAsync,
+};

package/src/exportEmbed/options.ts

@@ -0,0 +1,25 @@
+import { HarmonyCliError } from '../errors';
+import { CommonOptions, parseArgs } from '../args';
+
+const ExportEmbedOptions = {
+  ...CommonOptions,
+  'check': { type: 'boolean' },
+  'reset-cache': { type: 'boolean' },
+} as const;
+
+function parseExportEmbedArgs(argv: string[]) {
+  const { positionals, values } = parseArgs(ExportEmbedOptions, argv);
+
+  if (positionals.length > 1) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unexpected export:embed positional argument: ${positionals[1]}`, { operation: 'parse-arguments' });
+  }
+
+  return {
+    check: Boolean(values.check),
+    help: Boolean(values.help),
+    project: positionals[0],
+    resetCache: Boolean(values['reset-cache']),
+  };
+}
+
+export { parseExportEmbedArgs };

package/src/file.ts

@@ -0,0 +1,110 @@
+import nodeCrypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { isInside } from './path';
+
+async function sha256File(file: string): Promise<string> {
+  return await new Promise<string>((resolve, reject) => {
+    const hash = nodeCrypto.createHash('sha256');
+    const input = fs.createReadStream(file);
+
+    input.on('error', reject);
+    input.on('data', (chunk) => {
+      const bytes = typeof chunk === 'string' ? new TextEncoder().encode(chunk) : Uint8Array.from(chunk);
+      hash.update(bytes);
+    });
+    input.on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+async function describeFile(file: string): Promise<{ sha256: string; size: number }> {
+  const stat = await fs.promises.stat(file);
+
+  if (!stat.isFile()) throw new Error(`Expected a regular file: ${file}`);
+
+  return { sha256: await sha256File(file), size: stat.size };
+}
+
+async function listFiles(root: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function visit(directory: string): Promise<void> {
+    const entries = await fs.promises.readdir(directory, { withFileTypes: true });
+
+    entries.sort((left, right) => left.name.localeCompare(right.name, 'en'));
+
+    for (const entry of entries) {
+      const file = path.join(directory, entry.name);
+
+      if (entry.isSymbolicLink()) throw new Error(`Asset output contains a symbolic link: ${entry.name}`);
+      if (entry.isDirectory()) await visit(file);
+      else if (entry.isFile()) files.push(file);
+      else throw new Error(`Asset output contains an unsupported file: ${entry.name}`);
+    }
+  }
+
+  await visit(root);
+
+  return files;
+}
+
+async function ensureSafeParent(root: string, destination: string): Promise<void> {
+  if (!isInside(root, destination) || destination === root) {
+    throw new Error('Export destination escapes its owned root.');
+  }
+
+  await fs.promises.mkdir(root, { recursive: true });
+  await fs.promises.mkdir(path.dirname(destination), { recursive: true });
+
+  const [realRoot, realParent] = await Promise.all([
+    fs.promises.realpath(root),
+    fs.promises.realpath(path.dirname(destination)),
+  ]);
+
+  if (!isInside(realRoot, realParent)) {
+    throw new Error('Export destination follows a link outside its owned root.');
+  }
+}
+
+async function atomicCopy(source: string, destination: string, root: string): Promise<void> {
+  await ensureSafeParent(root, destination);
+
+  const temporary = path.join(path.dirname(destination), `.${path.basename(destination)}.expo-${nodeCrypto.randomUUID()}.tmp`);
+
+  try {
+    await fs.promises.copyFile(source, temporary, fs.constants.COPYFILE_EXCL);
+    await fs.promises.rename(temporary, destination);
+  } finally {
+    await fs.promises.rm(temporary, { force: true });
+  }
+}
+
+async function atomicWriteJson(value: unknown, destination: string, root: string): Promise<void> {
+  await ensureSafeParent(root, destination);
+
+  const temporary = path.join(path.dirname(destination), `.${path.basename(destination)}.expo-${nodeCrypto.randomUUID()}.tmp`);
+
+  try {
+    await fs.promises.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+    await fs.promises.rename(temporary, destination);
+  } finally {
+    await fs.promises.rm(temporary, { force: true });
+  }
+}
+
+async function removeEmptyParents(file: string, stop: string): Promise<void> {
+  let directory = path.dirname(file);
+
+  while (directory !== stop && isInside(stop, directory)) {
+    try {
+      await fs.promises.rmdir(directory);
+    } catch {
+      return;
+    }
+
+    directory = path.dirname(directory);
+  }
+}
+
+export { atomicCopy, atomicWriteJson, describeFile, listFiles, removeEmptyParents };

package/src/index.ts

@@ -0,0 +1,12 @@
+export { runAsync } from './cli';
+export { buildHarmonyAsync } from './buildHap/build';
+export type { HarmonyBuildOptions, HarmonyBuildResult } from './buildHap/build';
+export { exportEmbedAsync } from './exportEmbed/export';
+export { resolveHarmonyBuildPlanAsync, resolveHarmonyToolchain } from './tools';
+export { installHarmonyDependenciesAsync } from './run/install';
+export { formatModulesResult, runModulesCommandAsync } from './modules/modules';
+export type { ModulesCommandResult } from './modules/modules';
+export { commitHarmonyNativeBuildCacheAsync, prepareHarmonyNativeBuildCacheAsync } from './run/cache';
+export { runHarmonyAsync } from './run/run';
+export type { HarmonyExportManifest } from './exportEmbed/manifest';
+export type { HarmonyRunOptions, HarmonyRunResult } from './run/run';