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

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,
+  });
+}

package/src/native/prepareProject.ts

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import { linkModulesAsync } from '@expo-harmony/expo-modules-autolinking';
+
+import { doctorAsync } from '../doctor/doctor';
+import { HarmonyCliError } from '../errors';
+import { progress, type Log } from '../log';
+import { timedAsync } from '../profile';
+import { checkAsync } from '../prebuild/check';
+import { prebuildParsedAsync } from '../prebuild/prebuild';
+import { createHarmonyToolchainEnv } from './toolchain';
+import { resolveHarmonyBuildPlanAsync, resolveHarmonyBuildPlanIfPresentAsync } from './project';
+import type { HarmonyBuildPlan } from './types';
+
+interface PrepareProjectOptions {
+  io?: Log;
+  requireDeviceTools?: boolean;
+  check?: boolean;
+  sync: boolean;
+  variant: 'debug' | 'release';
+}
+
+async function prepareNativeProjectAsync(
+  root: string,
+  options: PrepareProjectOptions,
+  steps: Record<string, number>
+): Promise<HarmonyBuildPlan> {
+  const plan = await timedAsync(steps, 'buildPlan', () => resolveHarmonyBuildPlanIfPresentAsync(root, {
+    buildMode: options.variant,
+  }));
+  const exists = Boolean(plan && fs.existsSync(plan.harmonyRoot));
+
+  if (plan?.workflow === 'bare' && options.sync) {
+    throw new HarmonyCliError('ERR_HARMONY_BARE_SYNC', '--sync regenerates CNG projects and cannot be used with a manually maintained bare project.', { operation: 'build' });
+  }
+
+  progress(options, 'Checking the Harmony project');
+  const doctor = await timedAsync(steps, 'doctor', () => doctorAsync(root, {
+    requireBuildTools: true,
+    requireDeviceTools: options.requireDeviceTools,
+    validateGeneratedProject: exists,
+    validateModules: false,
+  }));
+  if (!doctor.ok) {
+    const checks = doctor.checks.filter(check => check.status === 'error').map(check => check.id);
+
+    throw new HarmonyCliError('ERR_HARMONY_DOCTOR_FAILED', `Harmony doctor found blocking checks: ${checks.join(', ') || 'unknown'}.`, { operation: 'doctor' });
+  }
+
+  if (plan?.workflow === 'bare') {
+    progress(options, 'Autolinking the bare Harmony project');
+    await timedAsync(steps, 'autolinking', () => linkModulesAsync({
+      projectRoot: root,
+      harmonyProjectPath: plan.harmonyRoot,
+      buildType: options.variant,
+      env: createHarmonyToolchainEnv(),
+    }));
+
+    steps.prebuild = 0;
+    steps.cngCheck = 0;
+
+    return plan;
+  }
+
+  if (!exists || options.sync) {
+    progress(options, exists
+      ? 'Synchronizing the generated Harmony project'
+      : 'Generating the missing Harmony project');
+    await timedAsync(steps, 'prebuild', () => prebuildParsedAsync(
+      root,
+      [],
+      { buildType: options.variant }
+    ));
+    steps.cngCheck = 0;
+
+    return timedAsync(steps, 'buildPlan', () => resolveHarmonyBuildPlanAsync(root, { buildMode: options.variant }));
+  }
+
+  steps.prebuild = 0;
+  if (options.check === false) {
+    steps.cngCheck = 0;
+    return plan;
+  }
+
+  progress(options, 'Checking CNG ownership and drift');
+  const check = await timedAsync(steps, 'cngCheck', () => checkAsync(root, { buildType: options.variant }));
+  if (!check.clean) {
+    const summary = check.changes.slice(0, 8).map(change => `${change.type}:${change.path}`).join(', ');
+
+    throw new HarmonyCliError(
+      'ERR_HARMONY_MANIFEST_DRIFT',
+      `Generated Harmony files differ from CNG desired state${summary ? ` (${summary})` : ''}. Run expo-harmony prebuild or retry with --sync.`,
+      { operation: 'check' }
+    );
+  }
+
+  return plan;
+}
+
+export { prepareNativeProjectAsync };