@expo-harmony/cli 55.0.26-harmony.1 → 55.0.26-harmony.10

package/src/file.ts

@@ -1,4 +1,4 @@
-import nodeCrypto from 'node:crypto';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -6,7 +6,7 @@ import { isInside } from './path';
 
 async function sha256File(file: string): Promise<string> {
   return await new Promise<string>((resolve, reject) => {
-    const hash = nodeCrypto.createHash('sha256');
+    const hash = crypto.createHash('sha256');
     const input = fs.createReadStream(file);
 
     input.on('error', reject);
@@ -70,26 +70,26 @@ async function ensureSafeParent(root: string, destination: string): Promise<void
 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`);
+  const temp = path.join(path.dirname(destination), `.${path.basename(destination)}.expo-${crypto.randomUUID()}.tmp`);
 
   try {
-    await fs.promises.copyFile(source, temporary, fs.constants.COPYFILE_EXCL);
-    await fs.promises.rename(temporary, destination);
+    await fs.promises.copyFile(source, temp, fs.constants.COPYFILE_EXCL);
+    await fs.promises.rename(temp, destination);
   } finally {
-    await fs.promises.rm(temporary, { force: true });
+    await fs.promises.rm(temp, { 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`);
+  const temp = path.join(path.dirname(destination), `.${path.basename(destination)}.expo-${crypto.randomUUID()}.tmp`);
 
   try {
-    await fs.promises.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
-    await fs.promises.rename(temporary, destination);
+    await fs.promises.writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+    await fs.promises.rename(temp, destination);
   } finally {
-    await fs.promises.rm(temporary, { force: true });
+    await fs.promises.rm(temp, { force: true });
   }
 }
 
@@ -107,4 +107,13 @@ async function removeEmptyParents(file: string, stop: string): Promise<void> {
   }
 }
 
-export { atomicCopy, atomicWriteJson, describeFile, listFiles, removeEmptyParents };
+function isNonEmptyRegularFile(file: string): boolean {
+  try {
+    const stat = fs.lstatSync(file);
+    return !stat.isSymbolicLink() && stat.isFile() && stat.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+export { atomicCopy, atomicWriteJson, describeFile, isNonEmptyRegularFile, listFiles, removeEmptyParents };

package/src/help.ts

@@ -0,0 +1,41 @@
+export const Help = `Usage: expo-harmony <command> [project] [options]
+
+Commands:
+  start                 Start Expo Metro for Harmony development
+  runtime               Describe project requirements; --client file checks compatibility
+  runtime --publish     Embed capabilities from prepared native build inputs
+  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                Export an OTA update, assets, metadata, and source map
+  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)
+  --host <hostname>     Advertised HTTP LAN hostname (start)
+  --private-key-path <path>
+                        Sign development manifests using the configured Updates certificate
+  --port <number>       Metro and device reverse port (default: 8081)
+  --sync                Re-run prebuild before building
+  --output-dir <path>   OTA export directory (default: dist)
+  --asset-url <url>     HTTP(S) root hosting exported OTA assets
+  --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
+`;

package/src/index.ts

@@ -2,11 +2,13 @@ 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 { resolveHarmonyBuildPlanAsync } from './native/project';
+export type { HarmonyBuildPlan, HarmonyBuildMode } from './native/types';
+export { resolveHarmonyToolchain } from './native/toolchain';
+export { installHarmonyDependenciesAsync } from './native/install';
 export { formatModulesResult, runModulesCommandAsync } from './modules/modules';
 export type { ModulesCommandResult } from './modules/modules';
-export { commitHarmonyNativeBuildCacheAsync, prepareHarmonyNativeBuildCacheAsync } from './run/cache';
+export { commitHarmonyNativeBuildCacheAsync, prepareHarmonyNativeBuildCacheAsync } from './native/cache';
 export { runHarmonyAsync } from './run/run';
 export type { HarmonyExportManifest } from './exportEmbed/manifest';
 export type { HarmonyRunOptions, HarmonyRunResult } from './run/run';

package/src/internal/development.ts

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+
+import { installHarmonyManifest } from '../development/manifest';
+
+installHarmonyManifest(process.cwd());
+process.argv.splice(1, 1);
+const run = createRequire(__filename);
+run(process.argv[1]);

package/src/internal/export.ts

@@ -0,0 +1,82 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { HarmonyCliError } from '../errors';
+
+async function main(): Promise<void> {
+  const [root, serialized, destination] = process.argv.slice(2);
+  const project = createRequire(path.join(root, 'package.json'));
+  const expo = createRequire(project.resolve('expo/package.json'));
+  const require = createRequire(expo.resolve('@expo/cli/package.json'));
+  if (require('./package.json').version !== '55.0.32') {
+    throw new HarmonyCliError('ERR_HARMONY_EXPORT_UPSTREAM', 'Harmony asset export requires Expo CLI 55.0.32.', { operation: 'export' });
+  }
+
+  const options = JSON.parse(serialized);
+  require('./build/src/utils/nodeEnv').setNodeEnv('production');
+  require('./build/src/utils/nodeEnv').loadEnvFiles(root);
+  if (options.update) {
+    const directory = path.join(path.dirname(destination), 'export');
+    await require('./build/src/export/exportApp').exportAppAsync(root, {
+      platforms: ['harmony'], outputDir: directory, clear: options.resetCache,
+      dev: false, sourceMaps: true, minify: false, bytecode: false,
+    });
+    const metadata = JSON.parse(await fs.readFile(path.join(directory, 'metadata.json'), 'utf8')).fileMetadata.harmony;
+    const mime = require('mime-types');
+    const assets = [];
+    for (const asset of metadata.assets) {
+      const source = path.join(directory, asset.path);
+      const data = await fs.readFile(source);
+      const key = path.basename(asset.path, path.extname(asset.path));
+      const relative = `assets/${key}.${asset.ext}`;
+      await fs.mkdir(path.join(options.assetsDest, 'assets'), { recursive: true });
+      await fs.copyFile(source, path.join(options.assetsDest, relative));
+      assets.push({ key, hash: crypto.createHash('sha256').update(Uint8Array.from(data)).digest('base64url'),
+        contentType: mime.lookup(asset.ext) || 'application/octet-stream', fileExtension: '.' + asset.ext,
+        embeddedAssetFilename: relative });
+    }
+    await require('@expo/metro/metro/shared/output/bundle').save({
+      code: await fs.readFile(path.join(directory, metadata.bundle), 'utf8'),
+      map: await fs.readFile(path.join(directory, metadata.bundle + '.map'), 'utf8'),
+    }, options, console.log);
+    await fs.writeFile(destination, JSON.stringify(assets));
+
+    return;
+  }
+
+  const { bundle, assets, files } = await require('./build/src/export/embed/exportEmbedAsync').exportEmbedBundleAndAssetsAsync(root, options);
+  const { getAssetLocalPath } = require('./build/src/export/metroAssetLocalPath');
+  const mime = require('mime-types');
+  const metadata: Record<string, unknown>[] = [];
+
+  for (const asset of assets) {
+    if (!Array.isArray(asset.fileHashes) || asset.fileHashes.length !== asset.files.length) {
+      throw new HarmonyCliError('ERR_HARMONY_EXPORT_ASSETS', 'Metro assets must include expo-asset fileHashes.', { operation: 'export' });
+    }
+    for (let index = 0; index < asset.files.length; index++) {
+      const data = await fs.readFile(asset.files[index]);
+      metadata.push({ key: asset.fileHashes[index], hash: crypto.createHash('sha256').update(Uint8Array.from(data)).digest('base64url'),
+        contentType: mime.lookup(asset.type) || 'application/octet-stream', fileExtension: '.' + asset.type,
+        embeddedAssetFilename: getAssetLocalPath(asset, { platform: 'harmony', scale: asset.scales[index] }) });
+    }
+  }
+
+  await fs.mkdir(path.dirname(options.bundleOutput), { recursive: true });
+  await Promise.all([
+    require('@expo/metro/metro/shared/output/bundle').save(bundle, options, console.log),
+    require('./build/src/export/persistMetroAssets').persistMetroAssetsAsync(root, assets, { platform: 'harmony', outputDirectory: options.assetsDest }),
+  ]);
+  if (files.size > 0) {
+    const { copyPublicFolderAsync, getPublicFolderPath } = require('./build/src/export/publicFolder');
+    const { DOM_COMPONENTS_BUNDLE_DIR } = require('./build/src/start/server/middleware/DomComponentsMiddleware');
+    await require('./build/src/export/saveAssets').persistMetroFilesAsync(files, options.assetsDest);
+    await copyPublicFolderAsync(getPublicFolderPath(root), path.join(options.assetsDest, DOM_COMPONENTS_BUNDLE_DIR));
+  }
+  await fs.writeFile(destination, JSON.stringify(metadata));
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/src/internal/prebuild.ts

@@ -0,0 +1,3 @@
+export { withGeneratedProjectAsync } from '../prebuild/check';
+export { assertSafeCleanTarget } from '../prebuild/clean';
+export { withHarmonyProjectLockAsync } from '../projectLock';

package/src/log.ts

@@ -0,0 +1,5 @@
+export type Log = Pick<Console, 'error' | 'log' | 'warn'>;
+
+export function progress(options: { io?: Log }, message: string): void {
+  options.io?.log(`› ${message}`);
+}

package/src/modules/index.ts

@@ -0,0 +1,16 @@
+import { parseCommandArgs, type Command } from '../command';
+import { parseModulesArgs } from './options';
+
+export const command: Command = async (argv, io) => {
+  const args = parseCommandArgs(parseModulesArgs, argv, io);
+  if (!args) return 0;
+
+  const { projectRoot: root, options } = args;
+  const { formatModulesResult, runModulesCommandAsync } = await import('./modules.js');
+
+  const result = await runModulesCommandAsync(root, options);
+
+  io.log(formatModulesResult(result));
+
+  return result.ok ? 0 : 1;
+};

package/src/native/bare.ts

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import JSON5 from 'json5';
+
+import { HarmonyCliError } from '../errors';
+import type { BareHarmonyBuildPlan } from './types';
+
+function isBareHarmonyProject(root: string): boolean {
+  return fs.existsSync(path.join(root, 'harmony'))
+    && !fs.existsSync(path.join(root, 'harmony/.expo-harmony-template'))
+    && !fs.existsSync(path.join(root, '.expo/harmony/cng-manifest.json'));
+}
+
+function record(value: unknown, field: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `Native ${field} must be an object.`, { operation: 'resolve-build' });
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function records(value: unknown, field: string): Record<string, unknown>[] {
+  if (!Array.isArray(value)) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `Native ${field} must be an array.`, { operation: 'resolve-build' });
+  }
+
+  return value.map(item => record(item, field));
+}
+
+function readJson(file: string): Record<string, unknown> {
+  try {
+    return record(JSON5.parse(fs.readFileSync(file, 'utf8')), file);
+  } catch (cause) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `Cannot read native project file ${file}: ${cause.message}`, { cause, operation: 'resolve-build' });
+  }
+}
+
+function identifier(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !/^[A-Za-z_][A-Za-z0-9_.]*$/.test(value)) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `The native project must specify a valid ${field}.`, { operation: 'resolve-build' });
+  }
+
+  return value;
+}
+
+function selectDefault(items: Record<string, unknown>[], field: string): Record<string, unknown> {
+  if (items.length === 0) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `No ${field} is defined in harmony/build-profile.json5.`, { operation: 'resolve-build' });
+  }
+
+  const defaults = items.filter(item => item.name === 'default');
+
+  if (defaults.length === 1) return defaults[0];
+  if (items.length === 1) return items[0];
+
+  throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `Multiple ${field} are defined; name the intended default "default" in harmony/build-profile.json5.`, { operation: 'resolve-build' });
+}
+
+function resolveBareHarmonyBuildPlan(root: string, mode: 'debug' | 'release'): BareHarmonyBuildPlan {
+  const harmony = path.join(root, 'harmony');
+  const entry = path.join(harmony, 'entry');
+
+  for (const directory of [harmony, entry]) {
+    if (!fs.existsSync(directory)
+      || !fs.lstatSync(directory).isDirectory() || fs.lstatSync(directory).isSymbolicLink()) {
+      throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `Bare Harmony projects require a regular directory at ${directory}.`, { operation: 'resolve-build' });
+    }
+  }
+
+  const profile = readJson(path.join(harmony, 'build-profile.json5'));
+  const app = record(readJson(path.join(harmony, 'AppScope/app.json5')).app, 'app');
+  const module = record(readJson(path.join(entry, 'src/main/module.json5')).module, 'module');
+
+  const name = identifier(module.name, 'module.name');
+  const registration = records(profile.modules, 'modules').find(item => item.name === name);
+  if (!registration || typeof registration.srcPath !== 'string'
+    || path.resolve(harmony, registration.srcPath) !== entry || module.type !== 'entry') {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', 'Bare Harmony autolinking requires an entry module at harmony/entry, registered in build-profile.json5.', { operation: 'resolve-build' });
+  }
+
+  const config = record(profile.app, 'build-profile.app');
+  const selected = selectDefault(records(config.products, 'products'), 'products');
+  const product = identifier(selected.name, 'product name');
+  const targets = records(registration.targets, 'module targets').filter((item) => {
+    if (item.applyToProducts === undefined) return true;
+    if (!Array.isArray(item.applyToProducts) || item.applyToProducts.some(value => typeof value !== 'string')) {
+      throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', 'Native target.applyToProducts must be an array of product names.', { operation: 'resolve-build' });
+    }
+
+    return item.applyToProducts.includes(product);
+  });
+  const target = identifier(selectDefault(targets, 'module targets').name, 'target name');
+
+  const ability = identifier(module.mainElement, 'module.mainElement');
+  if (!records(module.abilities, 'abilities').some(item => item.name === ability)) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `Ability ${ability} is missing from module.json5.`, { operation: 'resolve-build' });
+  }
+
+  const bundle = identifier(app.bundleName, 'app.bundleName');
+  const signed = Boolean(selected.signingConfig);
+  if (signed && !records(config.signingConfigs, 'signingConfigs').some(item => item.name === selected.signingConfig)) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_PROJECT', `Signing config ${selected.signingConfig} is referenced by the product but is not defined.`, { operation: 'resolve-build' });
+  }
+
+  const rawfile = path.join(entry, 'src/main/resources/rawfile');
+  const metadata = path.join(root, '.expo/harmony/export');
+
+  return {
+    workflow: 'bare',
+    abilityName: ability,
+    buildMode: mode,
+    bundleName: bundle,
+    harmonyRoot: harmony,
+    moduleName: name,
+    moduleRoot: entry,
+    productName: product,
+    targetName: target,
+    expectedHap: path.join(entry, `build/${target}/outputs/${target}/${name}-${target}-${signed ? 'signed' : 'unsigned'}.hap`),
+    hvigorArgs: ['--mode', 'module', '-p', `module=${name}@${target}`, '-p', `product=${product}`, '-p', `buildMode=${mode}`, '--no-daemon', 'assembleHap'],
+    exportPaths: {
+      bundle: path.join(rawfile, 'hermes_bundle.hbc'),
+      manifest: path.join(root, '.expo/harmony/export-manifest.json'),
+      metadataRoot: metadata,
+      rawfileRoot: rawfile,
+      sourceMap: path.join(metadata, 'hermes_bundle.hbc.map'),
+    },
+    nativeCache: {
+      invalidationRoots: [path.join(entry, '.cxx'), path.join(entry, 'build')],
+      stateFile: path.join(entry, '.cxx/.expo-harmony-native-dependencies.json'),
+    },
+    nativeInputs: {
+      lockfile: path.join(harmony, 'oh-package-lock.json5'),
+      manifest: path.join(harmony, 'oh-package.json5'),
+    },
+    projectFiles: {
+      hvigorConfig: path.join(harmony, 'hvigor/hvigor-config.json5'),
+      moduleHvigor: path.join(entry, 'hvigorfile.ts'),
+      moduleJson: path.join(entry, 'src/main/module.json5'),
+      projectBuildProfile: path.join(harmony, 'build-profile.json5'),
+      rootHvigor: path.join(harmony, 'hvigorfile.ts'),
+    },
+  };
+}
+
+export { isBareHarmonyProject, resolveBareHarmonyBuildPlan };

package/src/native/build.ts

@@ -0,0 +1,83 @@
+import { getConfig } from '@expo/config';
+import path from 'node:path';
+
+import { commitHarmonyNativeBuildCacheAsync, prepareHarmonyNativeBuildCacheAsync } from './cache';
+import { installHarmonyDependenciesAsync } from './install';
+import type { HarmonyToolchain } from './toolchain';
+import type { HarmonyBuildPlan } from './types';
+import { HarmonyCliError } from '../errors';
+import { exportEmbedAsync } from '../exportEmbed/export';
+import { isNonEmptyRegularFile } from '../file';
+import { progress, type Log } from '../log';
+import { toPosixPath } from '../path';
+import { runCheckedAsync } from '../process';
+import { timedAsync } from '../profile';
+
+export interface NativeBuildResult {
+  export: null | { assetCount: number; bundleSha256: string; sourceMapSha256: string };
+  hapPath: string;
+}
+
+export async function buildNativeAsync(
+  root: string,
+  plan: HarmonyBuildPlan,
+  tools: HarmonyToolchain,
+  options: { io?: Log; resetCache?: boolean },
+  steps: Record<string, number>
+): Promise<NativeBuildResult> {
+  let exported: NativeBuildResult['export'] = null;
+  const embedded = plan.buildMode === 'release' || getConfig(root).exp.updates?.useNativeDebug === true;
+  if (embedded) {
+    progress(options, 'Exporting the release Hermes bundle');
+    const manifest = await timedAsync(steps, 'export', () => exportEmbedAsync(root, {
+      resetCache: options.resetCache,
+      skipDoctor: true,
+    }));
+
+    exported = {
+      assetCount: manifest.assets.length,
+      bundleSha256: manifest.bundle.sha256,
+      sourceMapSha256: manifest.sourceMap.sha256,
+    };
+  } else {
+    steps.export = 0;
+  }
+
+  progress(options, 'Installing Harmony project dependencies');
+  await timedAsync(steps, 'ohpm', () => installHarmonyDependenciesAsync(plan, tools));
+
+  progress(options, 'Checking Harmony native dependency cache');
+  const cache = await timedAsync(steps, 'nativeCache', () => prepareHarmonyNativeBuildCacheAsync(root, plan));
+  if (cache.changed) progress(options, 'Invalidated stale Harmony native build objects');
+
+  progress(options, `Building the ${plan.buildMode} HAP`);
+  await timedAsync(steps, 'build', () => runCheckedAsync(tools.hvigor.command, [
+    ...tools.hvigor.args,
+    ...plan.hvigorArgs,
+  ], {
+    code: 'ERR_HARMONY_BUILD_FAILED',
+    cwd: plan.harmonyRoot,
+    env: {
+      ...process.env,
+      EXPO_HARMONY_NODE: process.env.EXPO_HARMONY_NODE || process.execPath,
+      EXPO_METRO_TARGET: 'harmony',
+      HERMES_V1_ENABLED: 'true',
+      ...(plan.workflow === 'bare' ? { EXPO_HARMONY_NATIVE_PREPARED: '1' } : {}),
+      ...(embedded ? { EXPO_HARMONY_BUNDLE_PREBUILT: '1' } : {}),
+      ...(tools.sdkHome && !process.env.DEVECO_SDK_HOME
+        ? { DEVECO_SDK_HOME: tools.sdkHome }
+        : {}),
+    },
+    message: 'Hvigor build',
+    operation: 'hvigor-build',
+    timeoutMs: 15 * 60_000,
+  }));
+
+  if (!isNonEmptyRegularFile(plan.expectedHap)) {
+    throw new HarmonyCliError('ERR_HARMONY_HAP_MISSING', 'Hvigor completed without producing the expected non-empty regular HAP.', { operation: 'verify-hap' });
+  }
+
+  await timedAsync(steps, 'nativeCacheCommit', () => commitHarmonyNativeBuildCacheAsync(cache));
+
+  return { export: exported, hapPath: toPosixPath(path.relative(root, plan.expectedHap)) };
+}

package/src/{run → native}/cache.ts

@@ -4,10 +4,10 @@ import path from 'node:path';
 import {
   HarmonyNativeInputsFingerprintVersion,
   fingerprintHarmonyNativeInputsSync,
-} from '@expo-harmony/config-plugins/native-inputs';
+} from '@expo-harmony/config-plugins/internal/native-inputs';
 
 import { HarmonyCliError } from '../errors';
-import type { HarmonyBuildPlan } from '../tools';
+import { type HarmonyBuildPlan } from './types';
 
 export interface HarmonyNativeBuildCacheState {
   artifactCount: number;
@@ -17,13 +17,14 @@ export interface HarmonyNativeBuildCacheState {
   fingerprintVersion: number;
 }
 
-const CacheSchemaVersion = 1;
+const SchemaVersion = 1;
 
 async function readOptionalFile(file) {
   try {
     return await fs.promises.readFile(file);
   } catch (error) {
     if (error?.code === 'ENOENT') return null;
+
     throw new HarmonyCliError(
       error.code || 'ERR_HARMONY_NATIVE_CACHE',
       error.message || `Cannot read a Harmony native cache input: ${file}`,
@@ -33,14 +34,14 @@ async function readOptionalFile(file) {
 }
 
 async function resolveNativeDependencyFingerprintAsync(
-  projectRoot: string,
+  root: string,
   plan: HarmonyBuildPlan
 ) {
   try {
     return fingerprintHarmonyNativeInputsSync({
       lockfile: plan.nativeInputs.lockfile,
       manifest: plan.nativeInputs.manifest,
-      projectRoot,
+      projectRoot: root,
     });
   } catch (cause) {
     throw new HarmonyCliError(
@@ -52,10 +53,10 @@ async function resolveNativeDependencyFingerprintAsync(
 }
 
 async function prepareHarmonyNativeBuildCacheAsync(
-  projectRoot: string,
+  root: string,
   plan: HarmonyBuildPlan
 ): Promise<HarmonyNativeBuildCacheState> {
-  const current = await resolveNativeDependencyFingerprintAsync(projectRoot, plan);
+  const current = await resolveNativeDependencyFingerprintAsync(root, plan);
   const file = plan.nativeCache.stateFile;
   const source = await readOptionalFile(file);
   let saved = null;
@@ -68,7 +69,7 @@ async function prepareHarmonyNativeBuildCacheAsync(
     }
   }
 
-  const changed = saved?.schemaVersion !== CacheSchemaVersion
+  const changed = saved?.schemaVersion !== SchemaVersion
     || saved?.fingerprintVersion !== HarmonyNativeInputsFingerprintVersion
     || saved?.fingerprint !== current.fingerprint;
 
@@ -94,7 +95,7 @@ async function commitHarmonyNativeBuildCacheAsync(state: HarmonyNativeBuildCache
     artifactCount: state.artifactCount,
     fingerprint: state.fingerprint,
     fingerprintVersion: state.fingerprintVersion,
-    schemaVersion: CacheSchemaVersion,
+    schemaVersion: SchemaVersion,
   }, null, 2)}\n`);
   await fs.promises.rename(temp, state.cacheFile);
 }

package/src/native/hvigor.ts

@@ -0,0 +1,88 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fingerprintHarmonyNativeInputsSync } from '@expo-harmony/config-plugins/internal/native-inputs';
+
+import { HarmonyCliError } from '../errors';
+import { createHarmonyToolchainEnv, resolveHarmonyToolchain } from './toolchain';
+
+function nodeExecutable(): string {
+  const candidates = process.env.EXPO_HARMONY_NODE
+    ? [process.env.EXPO_HARMONY_NODE]
+    : [
+        process.execPath,
+        ...(process.env.PATH || '').split(path.delimiter).filter(Boolean)
+          .map(directory => path.join(directory, process.platform === 'win32' ? 'node.exe' : 'node')),
+      ];
+
+  for (const candidate of new Set(candidates)) {
+    const result = spawnSync(candidate, ['-p', 'process.versions.node'], { encoding: 'utf8', timeout: 5_000 });
+    if (result.status === 0 && Number.parseInt(result.stdout, 10) >= 20) return candidate;
+  }
+
+  throw new HarmonyCliError('ERR_HARMONY_NODE', 'Harmony native builds require Node.js 20 or newer. Set EXPO_HARMONY_NODE to its executable.', { operation: 'native-build' });
+}
+
+function run(command: string, args: string[], cwd: string): void {
+  const result = spawnSync(command, args, {
+    cwd,
+    env: { ...createHarmonyToolchainEnv(), EXPO_HARMONY: '1', EXPO_METRO_TARGET: 'harmony', HERMES_V1_ENABLED: 'true' },
+    stdio: 'inherit',
+    timeout: 10 * 60_000,
+  });
+
+  if (result.error || result.status !== 0) {
+    throw new HarmonyCliError('ERR_HARMONY_NATIVE_BUILD', `Harmony build command failed: ${command} (${result.error?.message || result.status}).`, { cause: result.error, exitCode: result.status || 1, operation: 'native-build' });
+  }
+}
+
+// Hvigor configuration is synchronous; linking must finish before task execution.
+export function prepareHarmonyNativeBuild(root: string, mode: 'debug' | 'release'): void {
+  const harmony = path.join(root, 'harmony');
+
+  if (process.env.EXPO_HARMONY_NATIVE_PREPARED !== '1') {
+    const require = createRequire(path.join(root, 'package.json'));
+    const manifest = path.resolve(path.dirname(require.resolve('@expo-harmony/expo-modules-autolinking')), '../package.json');
+    const bin = path.resolve(path.dirname(manifest), require(manifest).bin['expo-harmony-autolinking']);
+
+    run(nodeExecutable(), [bin, 'link', '--project-root', root, '--harmony-project-path', harmony, '--build-type', mode], root);
+
+    const { ohpm } = resolveHarmonyToolchain();
+    run(ohpm.command, [...ohpm.args, 'install', '--all'], harmony);
+  }
+
+  publishHarmonyNativeRuntime(root, mode);
+
+  const { fingerprint } = fingerprintHarmonyNativeInputsSync({
+    projectRoot: root,
+    manifest: path.join(harmony, 'oh-package.json5'),
+    lockfile: path.join(harmony, 'oh-package-lock.json5'),
+  });
+  const file = path.join(harmony, '.hvigor/expo-harmony/native-inputs.cmake');
+  const content = `# Generated native dependency fingerprint.\nadd_compile_definitions(EXPO_HARMONY_NATIVE_INPUTS_SHA256_${fingerprint}=1)\n`;
+  if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') === content) return;
+
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+
+  try {
+    fs.writeFileSync(temp, content);
+    fs.renameSync(temp, file);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+export function bundleHarmonyNativeBuild(root: string): void {
+  if (process.env.EXPO_HARMONY_BUNDLE_PREBUILT === '1') return;
+
+  const require = createRequire(path.join(root, 'package.json'));
+  run(nodeExecutable(), [require.resolve('@expo-harmony/cli/bin/expo-harmony'), 'export:embed', root], root);
+}
+
+export function publishHarmonyNativeRuntime(root: string, mode: 'debug' | 'release'): void {
+  const require = createRequire(path.join(root, 'package.json'));
+  run(nodeExecutable(), [require.resolve('@expo-harmony/cli/bin/expo-harmony'), 'runtime', root, '--publish', '--variant', mode], root);
+}

package/src/native/install.ts

@@ -0,0 +1,17 @@
+import type { HarmonyBuildPlan } from './types';
+import type { HarmonyToolchain } from './toolchain';
+import { runCheckedAsync } from '../process';
+
+export async function installHarmonyDependenciesAsync(
+  plan: Pick<HarmonyBuildPlan, 'harmonyRoot'>,
+  tools: HarmonyToolchain,
+  options: { timeoutMs?: number } = {}
+): Promise<void> {
+  await runCheckedAsync(tools.ohpm.command, [...tools.ohpm.args, 'install', '--all'], {
+    code: 'ERR_HARMONY_OHPM_FAILED',
+    cwd: plan.harmonyRoot,
+    message: 'OHPM install',
+    operation: 'ohpm-install',
+    timeoutMs: options.timeoutMs || 5 * 60_000,
+  });
+}