@expo-harmony/cli 55.0.26-harmony.7 → 55.0.26-harmony.9

package/README.md

@@ -2,7 +2,7 @@
 
 [**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/cli)
 
-Expo 项目的 HarmonyOS 命令行工具：启动 Metro 开发服务、生成原生工程、构建和安装 HAP。
+Expo 项目的 HarmonyOS 命令行工具，用于启动 Metro 开发服务、生成原生工程，以及构建、安装和运行应用。
 
 ## 安装
 
@@ -10,29 +10,31 @@ Expo 项目的 HarmonyOS 命令行工具：启动 Metro 开发服务、生成原
 npm install --save-dev @expo-harmony/cli
 ```
 
-CLI 必须装在项目本地。JS 打包调用项目内的 Expo CLI，Hermes 字节码编译调用项目内的 `@expo/metro-config`，Release 原生构建回调项目本地的 `expo-harmony` 二进制生成 Bundle。
+请将 CLI 安装在应用项目中，并使用 Node.js 20 或更高版本。Metro 配置需要接入 `@expo-harmony/metro-config`。
 
-项目需要 Node.js 20 或更高版本，在 Expo 配置中注册 `@expo-harmony/prebuild-config` 插件，并用 `@expo-harmony/metro-config` 组合 Metro 配置。
+通过 Expo 配置生成原生工程的项目（CNG），还需要在 Expo 配置中注册 `@expo-harmony/prebuild-config` 插件。
 
-HAP 构建需要完整的 HarmonyOS SDK（含 HMS 和 OpenHarmony 组件）、OHPM、Hvigor 和 HDC。用 `doctor` 检查这些环境。
+手工维护 `harmony/` 工程的项目可以使用 bare 模式，按原生工程中的配置构建和运行，无需注册 prebuild 插件。接入步骤见 [bare 文档](../../docs/BARE_WORKFLOW.md)。
+
+构建 HAP 需要 HarmonyOS SDK（含 HMS 和 OpenHarmony 组件）、OHPM 和 Hvigor。连接设备或模拟器还需要 HDC。可以运行 `npx expo-harmony doctor` 检查环境。
 
 ## 命令
 
 | 命令 | 作用 |
 | --- | --- |
-| `expo-harmony start` | 启动 Harmony 开发所需的 Expo Metro 服务 |
+| `expo-harmony start` | 启动 Metro 开发服务 |
 | `expo-harmony prebuild` | 使用 Expo CNG 生成或更新 HarmonyOS 原生工程 |
-| `expo-harmony prebuild --clean` | 安全删除并重新生成受管理的 `harmony` 目录 |
-| `expo-harmony prebuild --check` | 在隔离目录中生成期望状态并比较差异，不修改项目文件 |
-| `expo-harmony build` | 构建 HAP，不选择设备，也不安装或启动应用 |
-| `expo-harmony doctor` | 检查配置、依赖版本、Metro、RNOH、SDK、构建工具和签名 |
-| `expo-harmony modules list` | 列出发现的 Harmony Expo Module 候选及其来源 |
-| `expo-harmony modules inspect` | 展示模块解析后的 Harmony 元数据，如 HAR 与 ArkTS modules |
-| `expo-harmony modules verify` | 检查 canonical metadata、应用级 registration/OHPM 冲突、路径边界和约定产物 |
+| `expo-harmony prebuild --clean` | 删除并重新生成由 CNG 管理的原生工程 |
+| `expo-harmony prebuild --check` | 检查 CNG 生成的文件是否需要更新 |
+| `expo-harmony build` | 构建 HAP |
+| `expo-harmony doctor` | 检查项目配置、依赖、开发环境和签名配置 |
+| `expo-harmony modules list` | 列出项目中的 Expo Modules 及其来源 |
+| `expo-harmony modules inspect` | 查看模块的 Harmony 配置和原生文件路径 |
+| `expo-harmony modules verify` | 检查模块配置、依赖冲突和原生文件 |
 | `expo-harmony export:embed` | 导出 Hermes 字节码、资源和 Source Map 并写入原生工程 |
-| `expo-harmony run` | 构建 HAP，在连接的 HarmonyOS 设备上安装并启动应用 |
+| `expo-harmony run` | 构建 HAP，在设备或模拟器上安装并启动应用 |
 
-所有命令都可以带一个可选的项目路径；`modules` 的路径写在子命令后面。不提供时，从当前目录向上找最近的项目根目录：
+所有命令都可以指定项目路径，`modules` 的路径写在子命令后面。不指定时，CLI 从当前目录向上查找最近的项目根目录：
 
 ```sh
 npx expo-harmony start ./my-app
@@ -50,13 +52,13 @@ npx expo-harmony start --port 8082
 npx expo-harmony start --clear
 ```
 
-CLI 入口先设置 `EXPO_HARMONY=1` 和 `EXPO_METRO_TARGET=harmony`，再读取应用配置，所有命令都如此。
+`start` 启动 Metro，为 Debug 应用提供 JS Bundle。运行这个命令不需要 HarmonyOS SDK 或已连接的设备。日志显示在当前终端，按 Ctrl+C 退出。
 
-`start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro。它只启动 JS 开发服务：不生成原生工程，不构建、安装、启动应用，不做设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。Metro 在当前终端输出日志，Ctrl+C 退出。
+可以用 `--port <number>` 指定端口，默认是 `8081`。`--reset-cache` 清除 Metro 缓存，也可以写成 `--clear` 或 `-c`。
 
-选项有 `--port <number>`（默认 `8081`）和 `--reset-cache`（别名 `--clear`、`-c`）。端口上已有 Metro 时提示并退出，不停止已有服务；这时缓存选项不生效，要先停掉已有的 Metro 再执行一次。端口被其他进程占用时报错。
+端口上已有 Metro 时，命令会提示并退出，已有服务继续运行。要清除它的缓存，需要先停止服务，再带缓存选项启动。端口被其他进程占用时，命令会报错。
 
-要构建并启动应用，在另一个终端运行 `expo-harmony run --no-bundler`；指定了端口时，两个命令用同一个 `--port`。
+要构建并启动应用，在另一个终端运行 `npx expo-harmony run --no-bundler`。如果指定了端口，两个命令应使用相同的 `--port`。
 
 ## Prebuild
 
@@ -66,11 +68,19 @@ npx expo-harmony prebuild --clean
 npx expo-harmony prebuild --check
 ```
 
-`prebuild` 固定生成 HarmonyOS 平台，固定用 `@expo-harmony/template` 模板，因此没有 `--platform` 和 `--template`。依赖安装的选项透传给 Expo CLI：`--no-install`、`--npm`/`--yarn`/`--pnpm`/`--bun`（最多选一个）和 `--skip-dependency-update <packages>`。执行前先跑一遍 doctor，有阻塞错误就中止；这个阶段不要求构建工具就绪。
+`prebuild` 根据 Expo 配置生成或更新 HarmonyOS 原生工程，仅用于 CNG 项目。它使用 `@expo-harmony/template` 模板，不接受 `--platform` 和 `--template` 选项。
+
+命令会先检查项目配置和依赖，有错误时停止。这一步不要求安装好原生构建工具。
+
+依赖安装支持以下选项：
 
-`--clean` 只删除带 Expo Harmony 模板标记的原生目录。CNG manifest 缺失、目标不是项目内的普通目录、模板标记异常，都拒绝删除。
+- `--no-install`：跳过依赖安装。
+- `--npm`、`--yarn`、`--pnpm` 或 `--bun`：选择包管理器，最多指定一个。
+- `--skip-dependency-update <packages>`：跳过指定依赖的版本更新。
 
-`--check` 是只读操作。它把项目镜像到临时目录（`node_modules` 里的包目录用链接共享，Windows 下的普通文件复制过去，不需要文件符号链接权限），在临时目录里执行一次 prebuild，再比较受管文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能和其他会修改工程的选项一起用。
+`--clean` 删除原生工程后重新生成。如果工程缺少 CNG 清单或模板标记，或者目录是符号链接、位于项目之外，命令会拒绝删除。
+
+`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能与其他会修改工程的选项一起使用。
 
 ## Build
 
@@ -80,9 +90,11 @@ npx expo-harmony build --variant release
 npx expo-harmony build --sync
 ```
 
-`build` 构建 HAP，不选设备，也不安装和启动应用。没有原生工程时先执行 prebuild；`--sync` 强制重新生成；默认只校验 CNG 期望状态，发现差错就报错。之后安装 OHPM 依赖、校验原生构建缓存、执行 Hvigor `assembleHap`，最后确认产物 HAP 存在且非空。原生依赖的指纹变化时，旧的 `.cxx` 和 `build` 缓存会失效，不会链接到过期产物。
+`build` 构建 HAP，并输出文件路径。执行这个命令不需要连接设备，构建后也不会安装或启动应用。
+
+默认构建 Debug 版本。使用 `--variant release` 构建 Release 版本时，命令会将 JS Bundle 和资源打包进应用。
 
-选项：`--variant debug|release`（默认 `debug`）和 `--sync`。Release 构建先执行生产导出，再带着预生成的 Bundle 进 Hvigor。
+项目没有原生工程时，命令会先运行 prebuild。已有 CNG 工程时，会检查生成的文件是否需要更新；有差异时停止构建，可以使用 `--sync` 重新生成后继续构建。bare 工程按现有原生配置构建，不支持 `--sync`。
 
 ## Doctor
 
@@ -92,16 +104,16 @@ npx expo-harmony doctor
 
 `doctor` 逐项检查：
 
-- Expo `harmony` 配置和 `@expo-harmony/prebuild-config` 插件注册
-- 签名配置文件
+- CNG 工程的 Expo `harmony` 配置和 prebuild 插件；bare 工程的包名、模块、Ability 和构建配置
+- 签名配置文件及其引用
 - Metro 配置是否启用 Harmony
-- 必需依赖：RNOH 运行时和 CLI、`@expo-harmony/expo-modules-autolinking`
-- Harmony Expo Modules
+- RNOH 运行时和 CLI、`@expo-harmony/expo-modules-autolinking` 是否已安装
+- Expo Modules 的 Harmony 支持和配置
 - HarmonyOS SDK 是否完整
 - HDC、OHPM、Hvigor 是否可用
-- 生成工程中的 Hvigor 文件和 RNOH 自动链接禁用状态
+- 原生工程的 Hvigor 文件和自动链接配置
 
-有 error 级别的问题时，命令以非零状态退出。未配置外部签名文件只警告，不影响未签名构建。
+有 `error` 级别的问题时，命令以非零退出码结束。CNG 工程未配置外部签名文件时会显示警告，仍可构建未签名的 HAP。证书是否有效，需要在构建时由 Hvigor 检查。
 
 ## Modules
 
@@ -111,9 +123,13 @@ npx expo-harmony modules inspect --package expo-linear-gradient
 npx expo-harmony modules verify
 ```
 
-`list` 列出发现的模块候选（包名、版本、来源），标出不支持 Harmony 的模块、重复版本和缺失的必需依赖。`inspect` 展示模块解析后的元数据：包根、ArkTS modules、HAR 路径。`--package <name>` 筛选单个模块，未发现时报错。`verify` 输出诊断信息，有 error 时以非零状态退出。
+`list` 显示模块的包名、版本和来源，并标出不支持 Harmony 的模块、重复版本和缺失的依赖。
 
-三个子命令都支持 `--variant debug|release` 和 `--native-modules-dir <dir>`（app-local 模块目录，默认 `./modules`）。
+`inspect` 查看模块的 Harmony 配置，包括包目录、ArkTS 模块和 HAR 路径。可以用 `--package <name>` 筛选单个模块，找不到时会报错。
+
+`verify` 检查模块配置、依赖冲突和原生文件。有 `error` 级别的问题时，以非零退出码结束。
+
+三个子命令都支持 `--variant debug|release`，也可以用 `--native-modules-dir <dir>` 指定应用内的模块目录，默认是 `./modules`。
 
 ## Export
 
@@ -123,11 +139,11 @@ npx expo-harmony export:embed --check
 npx expo-harmony export:embed --reset-cache
 ```
 
-`export:embed` 先运行 doctor，再用项目本地的 Expo CLI 生成 Harmony 平台的 JS Bundle 和资源，交给项目本地的 `@expo/metro-config` 的 Hermes 导出器编译字节码、合并 Source Map。
+`export:embed` 导出 Release 应用使用的 Hermes 字节码、资源和 Source Map。命令会先检查项目配置，再生成并校验导出文件。
 
-产物先校验再写入：检查 Hermes 字节码魔数、Source Map 不含宿主机绝对路径，然后原子写入原生工程。Bundle 和资源进入模块的 `rawfile` 目录，Source Map 和清单写入 `.expo/harmony/export/`。
+Bundle 和资源写入原生模块的 `rawfile` 目录，Source Map 写入 `.expo/harmony/export/`。导出清单位于 `.expo/harmony/export-manifest.json`。
 
-清单 `.expo/harmony/export-manifest.json` 记录每个文件的哈希和大小。`--check` 按清单校验已有的导出，不重新构建。`--reset-cache` 透传给 Metro，清除转换缓存。
+`--check` 检查已有导出文件是否与清单一致，不重新导出。`--reset-cache` 清除 Metro 转换缓存后重新导出。
 
 ## Run
 
@@ -138,30 +154,42 @@ npx expo-harmony run \
   --port 8081
 ```
 
-`run` 按顺序执行：环境诊断、确保原生工程（缺失时预构建，`--sync` 强制重新生成，否则复用已有工程）、选择设备、Release 生产导出、OHPM 安装、Hvigor 构建、Metro 端口反向映射（仅 Debug）、HAP 安装、Ability 启动。模块接线是否正确，由 OHPM、Hvigor、CMake 和 ArkTS 编译器验证。
+`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程；如果工程不存在，会先运行 prebuild。
 
 常用选项：
 
-- `--variant debug|release`：构建模式，默认 `debug`。Release 先执行生产导出，不启动 Metro。
+- `--variant debug|release`：构建模式，默认 `debug`。Release 将 JS Bundle 和资源打包进应用，不启动 Metro。
 - `--device <id-or-name>`：选择已连接的 HDC 设备，或按完整名称启动本地模拟器，例如 `--device "Pura 90 Pro"`。有多个候选目标时必须指定。
-- `--port <number>`：Metro 端口和设备反向映射端口，默认 `8081`。
-- `--no-bundler`：连接已经在运行的 Expo Metro，不启动新的服务；端口空闲或被其他进程占用时报错。不加此选项时，端口上已有 Metro 在运行就直接复用。
+- `--port <number>`：电脑上的 Metro 端口，默认 `8081`。Debug 模式下会配置设备端口映射，让应用连接到这个端口。
+- `--no-bundler`：使用已运行的 Metro，找不到服务时报错。不加此选项时，会启动 Metro，或复用端口上已有的 Metro。
 - `--reset-cache`：Debug 模式下启动 Metro 时清除 Metro 缓存；Release 模式下清除生产导出缓存。
-- `--no-install`：跳过 HAP 安装，直接启动设备上已有的应用。
-- `--app-id <bundleName>`：指定要启动的应用；与生成的包名不同时，必须同时使用 `--no-install`。
-- `--sync`：构建前强制重新执行一次预构建。
+- `--no-install`：仍会构建 HAP，但跳过安装，启动设备上已有的应用。
+- `--app-id <bundleName>`：指定要启动的应用；与项目配置中的包名不同时，必须同时使用 `--no-install`。
+- `--sync`：构建前重新运行 prebuild，仅用于 CNG 项目。bare 项目不支持此选项。
+
+Debug 模式下，如果 Metro 由这个命令启动，日志会显示在当前终端，按 Ctrl+C 退出。
 
-Debug 模式下由 CLI 启动的 Metro 接管终端输出日志，Ctrl+C 退出。
+未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器；如果也没有正在启动的模拟器，就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
 
-未指定 `--device` 时，优先用已连接的设备。没有连接的设备时，先等正在启动的模拟器；否则启动唯一的本地模拟器。有多个候选模拟器时列出名称，用 `--device "模拟器名称"` 选择。通过名称选择或自动拉起模拟器时，CLI 等 HDC 连接、确认开机完成后才继续构建、安装和启动，最多等 120 秒。退出 CLI 或 Metro 后，模拟器继续运行。
+按名称选择或自动启动模拟器时，CLI 会等待模拟器开机并连接 HDC，最多等待 120 秒。退出 CLI 或 Metro 后，模拟器继续运行。
 
-自动启动需要 DevEco Studio 6.1.0 或更新版本，并且已在 Device Manager 中创建模拟器。CLI 按[华为模拟器命令行文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-emulator-command-line)调用 `Emulator -list -details` 和 `Emulator -start <name>`，使用 DevEco Studio 配置的实例和镜像路径。启动日志在项目的 `.expo/harmony/emulator.log`。启动失败时，先在 DevEco Studio 里处理首次使用协议或登录要求；文档注明需要登录开发者账号的模拟器版本无法从命令行启动。
+自动启动模拟器需要 DevEco Studio 6.1.0 或更高版本，并且已在 Device Manager 中创建模拟器。启动日志位于 `.expo/harmony/emulator.log`。启动失败时，可以先在 DevEco Studio 中打开模拟器，处理首次使用协议或登录提示。需要登录开发者账号的模拟器版本不支持从命令行启动，详见 [华为的模拟器文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-emulator-command-line)。
 
 ## 工具链与环境变量
 
-工具链按「环境变量覆盖 → DevEco Studio 安装布局 → PATH」的顺序解析。
+CLI 先读取环境变量指定的工具路径，再查找 DevEco Studio 的安装目录，最后从 `PATH` 查找。
 
-`HARMONY_HDC`、`HARMONY_EMULATOR`、`HARMONY_OHPM`、`HARMONY_HVIGORW` 和 `HARMONY_NODE` 覆盖对应工具的路径。SDK 根目录用 `DEVECO_SDK_HOME`、`HARMONY_HOME` 或 `OHOS_SDK_HOME` 指定。Emulator 支持 DevEco Studio 的 `tools/emulator` 和 Command Line Tools 的 `emulator` 两种布局，只在需要模拟器时调用。原生构建回调 CLI 时用的 Node.js 可以用 `EXPO_HARMONY_NODE` 指定。
+找不到工具或需要使用其他版本时，可以设置以下变量：
+
+| 环境变量 | 用途 |
+| --- | --- |
+| `HARMONY_HDC` | 指定 HDC 路径 |
+| `HARMONY_EMULATOR` | 指定模拟器命令行工具路径 |
+| `HARMONY_OHPM` | 指定 OHPM 路径 |
+| `HARMONY_HVIGORW` | 指定 Hvigor 路径 |
+| `HARMONY_NODE` | 指定 OHPM、Hvigor 使用的 Node.js 路径 |
+| `EXPO_HARMONY_NODE` | 指定原生构建过程中运行 Expo Harmony CLI 的 Node.js 路径，要求 Node.js 20 或更高版本 |
+| `DEVECO_SDK_HOME`、`HARMONY_HOME` 或 `OHOS_SDK_HOME` | 指定 HarmonyOS SDK 根目录 |
 
 ## Author
 

package/build/bin/expo-harmony.js

@@ -2,4 +2,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const cli_1 = require("../cli");
-(0, cli_1.main)();
+(0, cli_1.mainAsync)();

package/build/buildHap/build.d.ts

@@ -1,18 +1,11 @@
+import { type NativeBuildResult } from '../native/build';
 export interface HarmonyBuildOptions {
     io?: Pick<Console, 'error' | 'log' | 'warn'>;
-    /** @internal For release verification after a successful isolated prebuild check. */
-    skipGeneratedProjectCheck?: boolean;
     sync?: boolean;
     variant?: 'debug' | 'release';
 }
-export interface HarmonyBuildResult {
+export interface HarmonyBuildResult extends NativeBuildResult {
     bundleName: string;
-    export: null | {
-        assetCount: number;
-        bundleSha256: string;
-        sourceMapSha256: string;
-    };
-    hapPath: string;
     headless: true;
     installed: false;
     launched: false;
@@ -21,5 +14,5 @@ export interface HarmonyBuildResult {
     steps: Record<string, number>;
     variant: 'debug' | 'release';
 }
-declare function buildHarmonyAsync(projectRoot: string, options?: HarmonyBuildOptions): Promise<HarmonyBuildResult>;
+declare function buildHarmonyAsync(root: string, options?: HarmonyBuildOptions): Promise<HarmonyBuildResult>;
 export { buildHarmonyAsync };

package/build/buildHap/build.js

@@ -1,23 +1,14 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildHarmonyAsync = buildHarmonyAsync;
-const node_path_1 = __importDefault(require("node:path"));
-const errors_1 = require("../errors");
-const export_1 = require("../exportEmbed/export");
-const path_1 = require("../path");
 const projectLock_1 = require("../projectLock");
-const cache_1 = require("../run/cache");
-const install_1 = require("../run/install");
-const tools_1 = require("../tools");
-const common_1 = require("./common");
-async function buildHarmonyUnlockedAsync(projectRoot, options = {}) {
-    const normalizedOptions = {
+const build_1 = require("../native/build");
+const prepareProject_1 = require("../native/prepareProject");
+const toolchain_1 = require("../native/toolchain");
+async function buildHarmonyUnlockedAsync(root, options = {}) {
+    const settings = {
         io: options.io || console,
         requireDeviceTools: false,
-        skipGeneratedProjectCheck: Boolean(options.skipGeneratedProjectCheck),
         sync: Boolean(options.sync),
         variant: options.variant || 'debug',
     };
@@ -28,69 +19,20 @@ async function buildHarmonyUnlockedAsync(projectRoot, options = {}) {
         metro: 0,
         metroPort: 0,
     };
-    await (0, common_1.ensureGeneratedProjectAsync)(projectRoot, normalizedOptions, steps);
-    const plan = await (0, common_1.timed)(steps, 'buildPlan', () => (0, tools_1.resolveHarmonyBuildPlanAsync)(projectRoot, { buildMode: normalizedOptions.variant }));
-    const toolchain = (0, tools_1.resolveHarmonyToolchain)();
-    let exportManifest = null;
-    if (normalizedOptions.variant === 'release') {
-        (0, common_1.progress)(normalizedOptions, 'Exporting the release Hermes bundle');
-        exportManifest = await (0, common_1.timed)(steps, 'export', () => (0, export_1.exportEmbedAsync)(projectRoot, { skipDoctor: true }));
-    }
-    else {
-        steps.export = 0;
-    }
-    (0, common_1.progress)(normalizedOptions, 'Installing Harmony project dependencies');
-    await (0, common_1.timed)(steps, 'ohpm', () => (0, install_1.installHarmonyDependenciesAsync)(plan, toolchain));
-    (0, common_1.progress)(normalizedOptions, 'Checking Harmony native dependency cache');
-    const nativeBuildCache = await (0, common_1.timed)(steps, 'nativeCache', () => ((0, cache_1.prepareHarmonyNativeBuildCacheAsync)(projectRoot, plan)));
-    if (nativeBuildCache.changed) {
-        (0, common_1.progress)(normalizedOptions, 'Invalidated stale Harmony native build objects');
-    }
-    (0, common_1.progress)(normalizedOptions, `Building the ${normalizedOptions.variant} HAP without a device`);
-    const buildEnv = {
-        ...process.env,
-        EXPO_HARMONY_NODE: process.env.EXPO_HARMONY_NODE || process.execPath,
-        EXPO_METRO_TARGET: 'harmony',
-        HERMES_V1_ENABLED: 'true',
-        ...(normalizedOptions.variant === 'release' ? { EXPO_HARMONY_BUNDLE_PREBUILT: '1' } : {}),
-        ...(toolchain.sdkHome && !process.env.DEVECO_SDK_HOME
-            ? { DEVECO_SDK_HOME: toolchain.sdkHome }
-            : {}),
-    };
-    await (0, common_1.timed)(steps, 'build', () => (0, common_1.runCheckedAsync)(toolchain.hvigor.command, [
-        ...toolchain.hvigor.args,
-        ...plan.hvigorArgs,
-    ], {
-        code: 'ERR_HARMONY_BUILD_FAILED',
-        cwd: plan.harmonyRoot,
-        env: buildEnv,
-        message: 'Hvigor build',
-        operation: 'hvigor-build',
-        timeoutMs: 15 * 60_000,
-    }));
-    if (!(0, common_1.isNonEmptyRegularFile)(plan.expectedHap)) {
-        throw new errors_1.HarmonyCliError('ERR_HARMONY_HAP_MISSING', 'Hvigor completed without producing the expected non-empty regular HAP.', { operation: 'verify-hap' });
-    }
-    await (0, common_1.timed)(steps, 'nativeCacheCommit', () => (0, cache_1.commitHarmonyNativeBuildCacheAsync)(nativeBuildCache));
+    const plan = await (0, prepareProject_1.prepareNativeProjectAsync)(root, settings, steps);
+    const built = await (0, build_1.buildNativeAsync)(root, plan, (0, toolchain_1.resolveHarmonyToolchain)(), settings, steps);
     return {
         bundleName: plan.bundleName,
-        export: exportManifest
-            ? {
-                assetCount: exportManifest.assets.length,
-                bundleSha256: exportManifest.bundle.sha256,
-                sourceMapSha256: exportManifest.sourceMap.sha256,
-            }
-            : null,
-        hapPath: (0, path_1.toPosixPath)(node_path_1.default.relative(projectRoot, plan.expectedHap)),
+        ...built,
         headless: true,
         installed: false,
         launched: false,
         ok: true,
         schemaVersion: 1,
         steps,
-        variant: normalizedOptions.variant,
+        variant: settings.variant,
     };
 }
-async function buildHarmonyAsync(projectRoot, options = {}) {
-    return (0, projectLock_1.withHarmonyProjectLockAsync)(projectRoot, 'build', () => buildHarmonyUnlockedAsync(projectRoot, options));
+async function buildHarmonyAsync(root, options = {}) {
+    return (0, projectLock_1.withHarmonyProjectLockAsync)(root, 'build', () => buildHarmonyUnlockedAsync(root, options));
 }

package/build/buildHap/index.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from '../command';
+export declare const command: Command;

package/build/buildHap/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.command = void 0;
+const command_1 = require("../command");
+const options_1 = require("./options");
+const command = async (argv, io) => {
+    const args = (0, command_1.parseCommandArgs)(options_1.parseBuildArgs, argv, io);
+    if (!args)
+        return 0;
+    const { projectRoot: root, options } = args;
+    const { buildHarmonyAsync } = await import('./build.js');
+    const result = await buildHarmonyAsync(root, {
+        ...options,
+        io,
+    });
+    io.log(`Built ${result.variant} HAP at ${result.hapPath}; no device actions were performed.`);
+    return 0;
+};
+exports.command = command;

package/build/cli.d.ts

@@ -1,3 +1,3 @@
-declare function runAsync(argv?: string[], io?: Pick<Console, 'error' | 'log' | 'warn'>): Promise<number>;
-declare function main(argv?: string[]): Promise<void>;
-export { main, runAsync };
+import type { Log } from './log';
+export declare function runAsync(argv?: string[], io?: Log): Promise<number>;
+export declare function mainAsync(argv?: string[]): Promise<void>;

package/build/cli.js

@@ -1,204 +1,38 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.main = main;
 exports.runAsync = runAsync;
-const node_path_1 = __importDefault(require("node:path"));
-const options_1 = require("./buildHap/options");
-const options_2 = require("./doctor/options");
+exports.mainAsync = mainAsync;
 const errors_1 = require("./errors");
-const options_3 = require("./exportEmbed/options");
-const options_4 = require("./modules/options");
-const options_5 = require("./prebuild/options");
-const project_1 = require("./project");
-const projectLock_1 = require("./projectLock");
-const options_6 = require("./run/options");
-const options_7 = require("./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
-`;
-function parseInvocation(argv) {
-    if (argv.length === 0 || (argv.length === 1 && ['--help', '-h'].includes(argv[0]))) {
-        return { command: 'help' };
-    }
-    const command = argv[0];
-    if (!['build', 'prebuild', 'doctor', 'export:embed', 'modules', 'run', 'start'].includes(command)) {
-        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unknown command: ${command}`, {
-            operation: 'parse-arguments',
-        });
-    }
-    const parsed = command === 'build'
-        ? (0, options_1.parseBuildArgs)(argv.slice(1))
-        : command === 'prebuild'
-            ? (0, options_5.parsePrebuildArgs)(argv.slice(1), { allowProject: true })
-            : command === 'doctor'
-                ? (0, options_2.parseDoctorArgs)(argv.slice(1))
-                : command === 'export:embed'
-                    ? (0, options_3.parseExportEmbedArgs)(argv.slice(1))
-                    : command === 'modules'
-                        ? (0, options_4.parseModulesArgs)(argv.slice(1))
-                        : command === 'start'
-                            ? (0, options_7.parseStartArgs)(argv.slice(1))
-                            : (0, options_6.parseRunArgs)(argv.slice(1));
-    if (parsed.help)
-        return { command: 'help' };
-    const projectRoot = (0, project_1.resolveProject)(parsed.project ? node_path_1.default.resolve(parsed.project) : process.cwd());
-    return { command, parsed, projectRoot };
-}
+const help_1 = require("./help");
+const commands = {
+    'start': () => import('./start/index.js'),
+    'prebuild': () => import('./prebuild/index.js'),
+    'build': () => import('./buildHap/index.js'),
+    'doctor': () => import('./doctor/index.js'),
+    'modules': () => import('./modules/index.js'),
+    'export:embed': () => import('./exportEmbed/index.js'),
+    'run': () => import('./run/index.js'),
+};
 async function runAsync(argv = process.argv.slice(2), io = console) {
     process.env.EXPO_HARMONY = '1';
     process.env.EXPO_METRO_TARGET = 'harmony';
-    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();
-        }
+    if (argv.length === 0 || (argv.length === 1 && ['--help', '-h'].includes(argv[0]))) {
+        io.log(help_1.Help);
         return 0;
     }
-    const { check, clean, passthrough } = invocation.parsed;
-    if (check && passthrough.length) {
-        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--check cannot be combined with mutating prebuild options.');
+    const name = argv[0];
+    if (!Object.hasOwn(commands, name)) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unknown command: ${name}`, { operation: 'parse-arguments' });
     }
-    return (0, projectLock_1.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 errors_1.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;
-    });
+    const { command } = await commands[name]();
+    return command(argv.slice(1), io);
 }
-async function main(argv = process.argv.slice(2)) {
+async function mainAsync(argv = process.argv.slice(2)) {
     try {
-        const code = await runAsync(argv);
-        process.exitCode = code;
+        process.exitCode = await runAsync(argv);
     }
     catch (error) {
-        const code = error.code || 'ERR_HARMONY_UNKNOWN';
-        console.error(`[${code}] ${error.message}`);
+        console.error(`[${error.code || 'ERR_HARMONY_UNKNOWN'}] ${error.message}`);
         process.exitCode = error.exitCode || 1;
     }
 }

package/build/command.d.ts

@@ -0,0 +1,9 @@
+import type { Log } from './log';
+export type Command = (argv: string[], io: Log) => Promise<number>;
+export declare function parseCommandArgs<T extends {
+    help: boolean;
+    project?: string;
+}>(parse: (argv: string[]) => T, argv: string[], io: Log): {
+    options: T;
+    projectRoot: string;
+} | null;