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

package/README.md

@@ -2,7 +2,7 @@
 
 [**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/cli)
 
-为 Expo 项目提供 HarmonyOS 平台的命令行工具，支持 Metro 开发服务、CNG 原生工程生成、环境诊断、Harmony Expo Module 发现与校验、生产 Bundle 导出，以及 HAP 的构建、安装和启动。
+Expo 项目的 HarmonyOS 命令行工具，用于启动 Metro 开发服务、生成原生工程，以及构建、安装和运行应用。
 
 ## 安装
 
@@ -10,29 +10,31 @@
 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 插件。
+
+构建 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,11 +52,13 @@ npx expo-harmony start --port 8082
 npx expo-harmony start --clear
 ```
 
-`start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro，并自动设置 `EXPO_METRO_TARGET=harmony`。它只启动 JS 开发服务，不执行原生工程生成、构建、安装、应用启动或设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。新启动的 Metro 在当前终端输出日志，按 Ctrl+C 退出。
+`start` 启动 Metro，为 Debug 应用提供 JS Bundle。运行这个命令不需要 HarmonyOS SDK 或已连接的设备。日志显示在当前终端，按 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
 
@@ -64,9 +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` 选项。
+
+命令会先检查项目配置和依赖，有错误时停止。这一步不要求安装好原生构建工具。
+
+依赖安装支持以下选项：
+
+- `--no-install`：跳过依赖安装。
+- `--npm`、`--yarn`、`--pnpm` 或 `--bun`：选择包管理器，最多指定一个。
+- `--skip-dependency-update <packages>`：跳过指定依赖的版本更新。
 
-`--clean` 只会清理带有 Expo Harmony 模板标记的原生目录：CNG manifest 缺失、目标不是项目内的普通目录或模板标记异常时都会拒绝删除。`--check` 是只读操作，会把项目镜像到临时目录（`node_modules` 以符号链接共享，不复制），在其中执行一次隔离的 prebuild 后比较受管文件；无差异时退出码为 `0`，有差异时列出变更并以 `2` 退出，且不能与其他会修改工程的选项同时使用。
+`--clean` 删除原生工程后重新生成。如果工程缺少 CNG 清单或模板标记，或者目录是符号链接、位于项目之外，命令会拒绝删除。
+
+`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能与其他会修改工程的选项一起使用。
 
 ## Build
 
@@ -76,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
 
@@ -86,7 +102,18 @@ npx expo-harmony build --sync
 npx expo-harmony doctor
 ```
 
-`doctor` 逐项检查 Expo `harmony` 配置与 `@expo-harmony/prebuild-config` 插件注册、签名配置文件、启用 Harmony 的 Metro 配置、必需依赖（RNOH 运行时与 CLI、`@expo-harmony/expo-modules-autolinking`）、Harmony Expo Modules 校验、完整的 HarmonyOS SDK、HDC/OHPM/Hvigor 可用性，以及生成工程中的 Hvigor 文件和 RNOH 自动链接禁用状态。存在 error 级别的问题时命令以非零状态退出；未配置外部签名文件只会警告，不影响未签名构建。
+`doctor` 逐项检查：
+
+- CNG 工程的 Expo `harmony` 配置和 prebuild 插件；bare 工程的包名、模块、Ability 和构建配置
+- 签名配置文件及其引用
+- Metro 配置是否启用 Harmony
+- RNOH 运行时和 CLI、`@expo-harmony/expo-modules-autolinking` 是否已安装
+- Expo Modules 的 Harmony 支持和配置
+- HarmonyOS SDK 是否完整
+- HDC、OHPM、Hvigor 是否可用
+- 原生工程的 Hvigor 文件和自动链接配置
+
+有 `error` 级别的问题时，命令以非零退出码结束。CNG 工程未配置外部签名文件时会显示警告，仍可构建未签名的 HAP。证书是否有效，需要在构建时由 Hvigor 检查。
 
 ## Modules
 
@@ -96,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
 
@@ -108,7 +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。产物经过校验（Hermes 字节码魔数、Source Map 不含宿主机绝对路径）后原子写入原生工程：Bundle 和资源进入模块的 `rawfile` 目录，Source Map 与清单写入 `.expo/harmony/export/`。清单 `.expo/harmony/export-manifest.json` 记录每个文件的哈希与大小，`--check` 据此校验已有导出而不重新构建，`--reset-cache` 会透传给 Metro 清除转换缓存。
+`export:embed` 导出 Release 应用使用的 Hermes 字节码、资源和 Source Map。命令会先检查项目配置，再生成并校验导出文件。
+
+Bundle 和资源写入原生模块的 `rawfile` 目录，Source Map 写入 `.expo/harmony/export/`。导出清单位于 `.expo/harmony/export-manifest.json`。
+
+`--check` 检查已有导出文件是否与清单一致，不重新导出。`--reset-cache` 清除 Metro 转换缓存后重新导出。
 
 ## Run
 
@@ -119,32 +154,46 @@ npx expo-harmony run \
   --port 8081
 ```
 
-`run` 会依次执行环境诊断、确保原生工程（缺失时自动预构建，`--sync` 强制重新生成，否则校验 CNG 状态）、选择设备、Release 生产导出、OHPM 安装、Hvigor 构建、Metro 端口反向映射（仅 Debug）、HAP 安装和 Ability 启动。模块接线的最终正确性由 OHPM、Hvigor、CMake 和 ArkTS 编译器验证。
+`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程；如果工程不存在，会先运行 prebuild。
 
 常用选项：
 
-- `--variant debug|release`：选择构建模式，默认为 `debug`。Release 构建会先执行生产导出，不启动 Metro。
-- `--device <id-or-name>`：选择已连接的 HDC 设备，或按完整名称启动本地模拟器，例如 `--device "Pura 90 Pro"`。存在多个候选目标时必须指定。
-- `--port <number>`：设置 Metro 端口及设备反向映射端口，默认为 `8081`。
-- `--no-bundler`：连接已经运行的 Expo Metro，不启动新的服务；端口空闲或被其他进程占用时会报错。不加此选项时，若端口上已有 Metro 在运行则直接复用。
+- `--variant debug|release`：构建模式，默认 `debug`。Release 将 JS Bundle 和资源打包进应用，不启动 Metro。
+- `--device <id-or-name>`：选择已连接的 HDC 设备，或按完整名称启动本地模拟器，例如 `--device "Pura 90 Pro"`。有多个候选目标时必须指定。
+- `--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 模式下由 CLI 启动的 Metro 会接管终端输出日志，按 Ctrl+C 退出。
+Debug 模式下，如果 Metro 由这个命令启动，日志会显示在当前终端，按 Ctrl+C 退出。
 
-未指定 `--device` 时，优先使用已连接的设备；没有连接的设备时，优先等待正在启动的模拟器，否则自动启动唯一的本地模拟器。存在多个候选模拟器时会列出名称，使用 `--device "模拟器名称"` 选择。通过模拟器名称选择或自动拉起时，等待 HDC 连接并确认该实例开机完成后才继续构建、安装和启动应用，最多等待 120 秒；退出 CLI 或 Metro 后模拟器继续运行。
+未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器；如果也没有正在启动的模拟器，就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
 
-自动启动需要 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 中处理首次使用协议或登录要求；文档注明需要登录开发者账号的模拟器版本无法通过命令行启动。
+按名称选择或自动启动模拟器时，CLI 会等待模拟器开机并连接 HDC，最多等待 120 秒。退出 CLI 或 Metro 后，模拟器继续运行。
+
+自动启动模拟器需要 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」的顺序解析。`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` 显式指定。
+CLI 先读取环境变量指定的工具路径，再查找 DevEco Studio 的安装目录，最后从 `PATH` 查找。
+
+找不到工具或需要使用其他版本时，可以设置以下变量：
+
+| 环境变量 | 用途 |
+| --- | --- |
+| `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
 
 **expo-harmony** © [Baoshuo](https://github.com/renbaoshuo), Released under the MIT License.<br>
 Authored and maintained by Baoshuo with help from [contributors](https://github.com/renbaoshuo/expo-harmony/contributors).
 
-> [Personal Website](https://baoshuo.ren) · [Blog](https://blog.baoshuo.ren) · GitHub [@renbaoshuo](https://github.com/renbaoshuo) · Twitter [@baoshuo](https://twitter.com/baoshuo)
+> [Personal Website](https://baoshuo.ren) · [Blog](https://blog.baoshuo.ren) · GitHub [@renbaoshuo](https://github.com/renbaoshuo) · Twitter [@renbaoshuo](https://twitter.com/renbaoshuo)

package/build/args.d.ts

@@ -0,0 +1,19 @@
+type Option = {
+    short?: string;
+    type: 'boolean' | 'string';
+};
+type Options = Record<string, Option>;
+type Values<T extends Options> = {
+    [K in keyof T]?: T[K]['type'] extends 'boolean' ? boolean : string;
+};
+declare const CommonOptions: {
+    readonly help: {
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+};
+declare function parseArgs<T extends Options>(options: T, argv: string[]): {
+    positionals: string[];
+    values: Values<T>;
+};
+export { CommonOptions, parseArgs };

package/build/args.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommonOptions = void 0;
+exports.parseArgs = parseArgs;
+const node_util_1 = require("node:util");
+const errors_1 = require("./errors");
+const CommonOptions = {
+    help: { short: 'h', type: 'boolean' },
+};
+exports.CommonOptions = CommonOptions;
+function parseArgs(options, argv) {
+    try {
+        return (0, node_util_1.parseArgs)({
+            allowPositionals: true,
+            args: argv,
+            options,
+            strict: true,
+        });
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', message, {
+            cause,
+            operation: 'parse-arguments',
+        });
+    }
+}

package/build/bin/expo-harmony.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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

@@ -0,0 +1,18 @@
+import { type NativeBuildResult } from '../native/build';
+export interface HarmonyBuildOptions {
+    io?: Pick<Console, 'error' | 'log' | 'warn'>;
+    sync?: boolean;
+    variant?: 'debug' | 'release';
+}
+export interface HarmonyBuildResult extends NativeBuildResult {
+    bundleName: string;
+    headless: true;
+    installed: false;
+    launched: false;
+    ok: true;
+    schemaVersion: 1;
+    steps: Record<string, number>;
+    variant: 'debug' | 'release';
+}
+declare function buildHarmonyAsync(root: string, options?: HarmonyBuildOptions): Promise<HarmonyBuildResult>;
+export { buildHarmonyAsync };

package/build/buildHap/build.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHarmonyAsync = buildHarmonyAsync;
+const projectLock_1 = require("../projectLock");
+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,
+        sync: Boolean(options.sync),
+        variant: options.variant || 'debug',
+    };
+    const steps = {
+        device: 0,
+        install: 0,
+        launch: 0,
+        metro: 0,
+        metroPort: 0,
+    };
+    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,
+        ...built,
+        headless: true,
+        installed: false,
+        launched: false,
+        ok: true,
+        schemaVersion: 1,
+        steps,
+        variant: settings.variant,
+    };
+}
+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/buildHap/options.d.ts

@@ -0,0 +1,7 @@
+declare function parseBuildArgs(argv: string[]): {
+    help: boolean;
+    project: string;
+    sync: boolean;
+    variant: "debug" | "release";
+};
+export { parseBuildArgs };

package/build/buildHap/options.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBuildArgs = parseBuildArgs;
+const args_1 = require("../args");
+const errors_1 = require("../errors");
+const BuildOptions = {
+    ...args_1.CommonOptions,
+    sync: { type: 'boolean' },
+    variant: { type: 'string' },
+};
+function parseBuildArgs(argv) {
+    const { positionals, values } = (0, args_1.parseArgs)(BuildOptions, argv);
+    if (positionals.length > 1) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unexpected build positional argument: ${positionals[1]}`, {
+            operation: 'parse-arguments',
+        });
+    }
+    const variant = values.variant || 'debug';
+    if (variant !== 'debug' && variant !== 'release') {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--variant must be debug or release.', {
+            operation: 'parse-arguments',
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        project: positionals[0],
+        sync: Boolean(values.sync),
+        variant: variant,
+    };
+}

package/build/cli.d.ts

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAsync = runAsync;
+exports.mainAsync = mainAsync;
+const errors_1 = require("./errors");
+const help_1 = require("./help");
+const commands = {
+    'runtime': () => import('./runtime/index.js'),
+    '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': () => import('./updates/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';
+    if (argv.length === 0 || (argv.length === 1 && ['--help', '-h'].includes(argv[0]))) {
+        io.log(help_1.Help);
+        return 0;
+    }
+    const name = argv[0];
+    if (!Object.hasOwn(commands, name)) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unknown command: ${name}`, { operation: 'parse-arguments' });
+    }
+    const { command } = await commands[name]();
+    return command(argv.slice(1), io);
+}
+async function mainAsync(argv = process.argv.slice(2)) {
+    try {
+        process.exitCode = await runAsync(argv);
+    }
+    catch (error) {
+        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;

package/build/command.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCommandArgs = parseCommandArgs;
+const node_path_1 = __importDefault(require("node:path"));
+const help_1 = require("./help");
+const project_1 = require("./project");
+function parseCommandArgs(parse, argv, io) {
+    const options = parse(argv);
+    if (options.help) {
+        io.log(help_1.Help);
+        return null;
+    }
+    return {
+        options,
+        projectRoot: (0, project_1.resolveProject)(options.project ? node_path_1.default.resolve(options.project) : process.cwd()),
+    };
+}

package/build/development/manifest.d.ts

@@ -0,0 +1 @@
+export declare function installHarmonyManifest(root: string): void;

package/build/development/manifest.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHarmonyManifest = installHarmonyManifest;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_module_1 = require("node:module");
+const errors_1 = require("../errors");
+const expo_1 = require("../expo");
+const project_1 = require("../native/project");
+const contract_1 = require("../runtime/contract");
+const protocol_1 = require("./protocol");
+async function createManifestResponseAsync(middleware, options, require) {
+    const { ExpoGoManifestHandlerMiddleware: Manifest, ResponseContentType: Types } = require('./build/src/start/server/middleware/ExpoGoManifestHandlerMiddleware');
+    const { getCodeSigningInfoAsync, signManifestString } = require('./build/src/utils/codesigning');
+    const { serializeDictionary } = require('structured-headers');
+    const { exp, expoGoConfig, bundleUrl, hostUri } = await middleware._resolveProjectSettingsAsync(options);
+    const requirements = await (0, contract_1.resolveRuntimeRequirementsAsync)(middleware.projectRoot);
+    const signing = await getCodeSigningInfoAsync(exp, options.expectSignature, middleware.options.privateKeyPath);
+    const scope = await Manifest.getScopeKeyAsync({ slug: exp.slug, codeSigningInfo: signing });
+    const bundle = new URL(bundleUrl);
+    bundle.searchParams.set('transform.engine', 'hermes');
+    bundle.searchParams.set('transform.bytecode', '0');
+    bundle.searchParams.set('unstable_transformProfile', 'hermes-stable');
+    bundle.searchParams.set('lazy', 'false');
+    const name = exp.harmony?.bundleName || (await (0, project_1.resolveHarmonyBuildPlanAsync)(middleware.projectRoot)).bundleName;
+    const id = exp.extra?.eas?.projectId;
+    const address = (0, protocol_1.canonicalHarmonyManifestURL)(`${bundle.origin}${options.harmonyManifestPath ?? `${protocol_1.HarmonyManifestPath}?platform=harmony`}`);
+    const manifest = JSON.stringify({
+        id: node_crypto_1.default.randomUUID(),
+        createdAt: new Date().toISOString(),
+        runtimeVersion: requirements.runtimeVersion,
+        launchAsset: { key: 'bundle', contentType: 'application/javascript', url: bundle.toString() },
+        assets: [],
+        metadata: {},
+        extra: {
+            eas: { projectId: id ?? undefined },
+            expoClient: { ...exp, hostUri },
+            expoGo: expoGoConfig,
+            scopeKey: scope,
+            harmony: {
+                projectId: id || `@${exp.owner || 'anonymous'}/${exp.slug}/${name}`,
+                manifestUrl: address,
+                launchLink: (0, protocol_1.createHarmonyLaunchLink)(address),
+                requirements,
+            },
+        },
+    });
+    const signature = signing
+        ? serializeDictionary(new Map(Object.entries({
+            keyid: signing.keyId,
+            sig: signManifestString(manifest, signing),
+            alg: 'rsa-v1_5-sha256',
+        }).map(([key, value]) => [key, [value, new Map()]])))
+        : undefined;
+    if (options.responseContentType === Types.MULTIPART_MIXED) {
+        return middleware.encodeFormDataAsync({
+            stringifiedManifest: manifest,
+            manifestPartHeaders: signature ? { 'expo-signature': signature } : undefined,
+            certificateChainBody: signing?.certificateChainForResponse.join('\n') ?? null,
+        });
+    }
+    const headers = middleware.getDefaultResponseHeaders();
+    headers.set('content-type', Manifest.getContentTypeForResponseContentType(options.responseContentType));
+    if (signature)
+        headers.set('expo-signature', signature);
+    return new Response(manifest, { headers });
+}
+function installHarmonyManifest(root) {
+    const expo = (0, node_module_1.createRequire)((0, expo_1.resolveExpoCli)(root).cliPath);
+    const require = (0, node_module_1.createRequire)(expo.resolve('@expo/cli/package.json'));
+    const version = require('./package.json').version;
+    if (version !== '55.0.32') {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_EXPO_CLI_UNSUPPORTED', `The Harmony manifest adapter requires @expo/cli 55.0.32; found ${version}.`, { operation: 'development-manifest' });
+    }
+    const { BundlerDevServer } = require('./build/src/start/server/BundlerDevServer');
+    const { parsePlatformHeader } = require('./build/src/start/server/middleware/resolvePlatform');
+    const create = BundlerDevServer.prototype.getManifestMiddlewareAsync;
+    // Reuse Expo's terminal QR renderer and dev-session publishing with our
+    // registered link, rather than emitting a second, incompatible QR code.
+    const nativeURL = BundlerDevServer.prototype.getNativeRuntimeUrl;
+    const redirectURL = BundlerDevServer.prototype.getRedirectUrl;
+    BundlerDevServer.prototype.getNativeRuntimeUrl = function (options = {}) {
+        const address = this.getUrlCreator().constructUrl({ ...options, scheme: 'http' });
+        if (!address)
+            return nativeURL.call(this, options);
+        const manifest = new URL(protocol_1.HarmonyManifestPath, address);
+        manifest.searchParams.set('platform', 'harmony');
+        return (0, protocol_1.createHarmonyLaunchLink)(manifest.toString());
+    };
+    BundlerDevServer.prototype.getRedirectUrl = function (platform = null) {
+        return platform === null || platform === 'harmony'
+            ? this.getNativeRuntimeUrl()
+            : redirectURL.call(this, platform);
+    };
+    // Expo installs the manifest before Metro's enhancer; adapt only the created instance.
+    BundlerDevServer.prototype.getManifestMiddlewareAsync = async function (...args) {
+        const middleware = await create.apply(this, args);
+        const parse = middleware.getParsedHeaders;
+        const respond = middleware._getManifestResponseAsync;
+        middleware.getParsedHeaders = (request) => {
+            if (parsePlatformHeader(request) !== 'harmony')
+                return parse.call(middleware, request);
+            // Bypass only the upstream platform assertion without changing the actual request.
+            const url = new URL(request.url, 'http://localhost');
+            url.searchParams.delete('platform');
+            url.searchParams.append('platform', 'harmony');
+            const manifest = new URL((0, protocol_1.canonicalHarmonyManifestURL)(url.toString()));
+            const harmonyManifestPath = manifest.pathname + manifest.search;
+            url.searchParams.set('platform', 'ios');
+            const copy = Object.create(request);
+            copy.url = url.pathname + url.search;
+            return { ...parse.call(middleware, copy), platform: 'harmony', harmonyManifestPath };
+        };
+        middleware._getManifestResponseAsync = options => options.platform === 'harmony'
+            ? createManifestResponseAsync(middleware, options, require)
+            : respond.call(middleware, options);
+        return middleware;
+    };
+}

package/build/development/protocol.d.ts

@@ -0,0 +1,3 @@
+export declare const HarmonyManifestPath = "/manifest";
+export declare function canonicalHarmonyManifestURL(value: string): string;
+export declare function createHarmonyLaunchLink(manifest: string): string;