@expo-harmony/cli 55.0.26-harmony.4 → 55.0.26-harmony.6

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 开发服务、生成原生工程、构建和安装 HAP。
 
 ## 安装
 
@@ -10,11 +10,11 @@
 npm install --save-dev @expo-harmony/cli
 ```
 
-CLI 必须安装在项目本地，JS 打包调用项目内的 Expo CLI，Hermes 字节码编译调用项目内的 `@expo/metro-config`，Release 原生构建也会回调项目本地的 `expo-harmony` 二进制生成 Bundle。
+CLI 必须装在项目本地。JS 打包调用项目内的 Expo CLI，Hermes 字节码编译调用项目内的 `@expo/metro-config`，Release 原生构建回调项目本地的 `expo-harmony` 二进制生成 Bundle。
 
-项目需要 Node.js 20 或更高版本，在 Expo 配置中注册 `@expo-harmony/prebuild-config` 插件，并使用 `@expo-harmony/metro-config` 组合 Metro 配置。
+项目需要 Node.js 20 或更高版本，在 Expo 配置中注册 `@expo-harmony/prebuild-config` 插件，并用 `@expo-harmony/metro-config` 组合 Metro 配置。
 
-HAP 构建需要完整的 HarmonyOS SDK（含 HMS 与 OpenHarmony 组件）、OHPM、Hvigor 和 HDC，这些环境可用 `doctor` 命令检查。
+HAP 构建需要完整的 HarmonyOS SDK（含 HMS 和 OpenHarmony 组件）、OHPM、Hvigor 和 HDC。用 `doctor` 检查这些环境。
 
 ## 命令
 
@@ -32,7 +32,7 @@ HAP 构建需要完整的 HarmonyOS SDK（含 HMS 与 OpenHarmony 组件）、OH
 | `expo-harmony export:embed` | 导出 Hermes 字节码、资源和 Source Map 并写入原生工程 |
 | `expo-harmony run` | 构建 HAP，在连接的 HarmonyOS 设备上安装并启动应用 |
 
-所有命令都可接收可选的项目路径（`modules` 命令写在子命令之后）；未提供时从当前目录向上查找最近的项目根目录作为默认值：
+所有命令都可以带一个可选的项目路径；`modules` 的路径写在子命令后面。不提供时，从当前目录向上找最近的项目根目录：
 
 ```sh
 npx expo-harmony start ./my-app
@@ -50,13 +50,13 @@ npx expo-harmony start --port 8082
 npx expo-harmony start --clear
 ```
 
-所有命令都会在 CLI 入口、读取应用配置之前设置 `EXPO_HARMONY=1` 和 `EXPO_METRO_TARGET=harmony`。
+CLI 入口先设置 `EXPO_HARMONY=1` 和 `EXPO_METRO_TARGET=harmony`，再读取应用配置，所有命令都如此。
 
-`start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro。它只启动 JS 开发服务，不执行原生工程生成、构建、安装、应用启动或设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。新启动的 Metro 在当前终端输出日志，按 Ctrl+C 退出。
+`start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro。它只启动 JS 开发服务：不生成原生工程，不构建、安装、启动应用，不做设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。Metro 在当前终端输出日志，Ctrl+C 退出。
 
-支持 `--port <number>`（默认 `8081`）和 `--reset-cache`（别名 `--clear`、`-c`）。端口上已有 Metro 时提示并退出，不停止已有服务；此时缓存选项不会生效，需要先停止已有 Metro 后重新执行命令。端口被其他进程占用时会报错。
+选项有 `--port <number>`（默认 `8081`）和 `--reset-cache`（别名 `--clear`、`-c`）。端口上已有 Metro 时提示并退出，不停止已有服务；这时缓存选项不生效，要先停掉已有的 Metro 再执行一次。端口被其他进程占用时报错。
 
-需要构建并启动应用时，在另一个终端运行 `expo-harmony run --no-bundler`；若指定了端口，两个命令使用相同的 `--port`。
+要构建并启动应用，在另一个终端运行 `expo-harmony run --no-bundler`；指定了端口时，两个命令用同一个 `--port`。
 
 ## Prebuild
 
@@ -66,9 +66,11 @@ 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` 固定生成 HarmonyOS 平台，固定用 `@expo-harmony/template` 模板，因此没有 `--platform` 和 `--template`。依赖安装的选项透传给 Expo CLI：`--no-install`、`--npm`/`--yarn`/`--pnpm`/`--bun`（最多选一个）和 `--skip-dependency-update <packages>`。执行前先跑一遍 doctor，有阻塞错误就中止；这个阶段不要求构建工具就绪。
 
-`--clean` 只会清理带有 Expo Harmony 模板标记的原生目录：CNG manifest 缺失、目标不是项目内的普通目录或模板标记异常时都会拒绝删除。`--check` 是只读操作，会把项目镜像到临时目录（`node_modules` 以符号链接共享，不复制），在其中执行一次隔离的 prebuild 后比较受管文件；无差异时退出码为 `0`，有差异时列出变更并以 `2` 退出，且不能与其他会修改工程的选项同时使用。
+`--clean` 只删除带 Expo Harmony 模板标记的原生目录。CNG manifest 缺失、目标不是项目内的普通目录、模板标记异常，都拒绝删除。
+
+`--check` 是只读操作。它把项目镜像到临时目录（`node_modules` 里的包目录用链接共享，Windows 下的普通文件复制过去，不需要文件符号链接权限），在临时目录里执行一次 prebuild，再比较受管文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能和其他会修改工程的选项一起用。
 
 ## Build
 
@@ -78,9 +80,9 @@ npx expo-harmony build --variant release
 npx expo-harmony build --sync
 ```
 
-`build` 在不使用设备的前提下完成 HAP 构建。缺少原生工程时自动执行 prebuild，`--sync` 强制重新生成，默认则校验 CNG 期望状态并在发现差错时报错。随后依次执行 OHPM 依赖安装、原生构建缓存校验和 Hvigor `assembleHap`，最后确认产物 HAP 存在且非空。原生依赖指纹变化时会自动失效旧的 `.cxx` 和 `build` 缓存，避免链接到过期的产物。
+`build` 构建 HAP，不选设备，也不安装和启动应用。没有原生工程时先执行 prebuild；`--sync` 强制重新生成；默认只校验 CNG 期望状态，发现差错就报错。之后安装 OHPM 依赖、校验原生构建缓存、执行 Hvigor `assembleHap`，最后确认产物 HAP 存在且非空。原生依赖的指纹变化时，旧的 `.cxx` 和 `build` 缓存会失效，不会链接到过期产物。
 
-选项：`--variant debug|release`（默认 `debug`）和 `--sync`。Release 构建会先执行生产导出，再带着预生成的 Bundle 进入 Hvigor。
+选项：`--variant debug|release`（默认 `debug`）和 `--sync`。Release 构建先执行生产导出，再带着预生成的 Bundle 进 Hvigor。
 
 ## Doctor
 
@@ -88,7 +90,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` 逐项检查：
+
+- Expo `harmony` 配置和 `@expo-harmony/prebuild-config` 插件注册
+- 签名配置文件
+- Metro 配置是否启用 Harmony
+- 必需依赖：RNOH 运行时和 CLI、`@expo-harmony/expo-modules-autolinking`
+- Harmony Expo Modules
+- HarmonyOS SDK 是否完整
+- HDC、OHPM、Hvigor 是否可用
+- 生成工程中的 Hvigor 文件和 RNOH 自动链接禁用状态
+
+有 error 级别的问题时，命令以非零状态退出。未配置外部签名文件只警告，不影响未签名构建。
 
 ## Modules
 
@@ -98,7 +111,7 @@ 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 的模块、重复版本和缺失的必需依赖。`inspect` 展示模块解析后的元数据：包根、ArkTS modules、HAR 路径。`--package <name>` 筛选单个模块，未发现时报错。`verify` 输出诊断信息，有 error 时以非零状态退出。
 
 三个子命令都支持 `--variant debug|release` 和 `--native-modules-dir <dir>`（app-local 模块目录，默认 `./modules`）。
 
@@ -110,7 +123,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` 先运行 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，清除转换缓存。
 
 ## Run
 
@@ -121,28 +138,30 @@ npx expo-harmony run \
   --port 8081
 ```
 
-`run` 会依次执行环境诊断、确保原生工程（缺失时自动预构建，`--sync` 强制重新生成，否则校验 CNG 状态）、选择设备、Release 生产导出、OHPM 安装、Hvigor 构建、Metro 端口反向映射（仅 Debug）、HAP 安装和 Ability 启动。模块接线的最终正确性由 OHPM、Hvigor、CMake 和 ArkTS 编译器验证。
+`run` 按顺序执行：环境诊断、确保原生工程（缺失时预构建，`--sync` 强制重新生成，否则复用已有工程）、选择设备、Release 生产导出、OHPM 安装、Hvigor 构建、Metro 端口反向映射（仅 Debug）、HAP 安装、Ability 启动。模块接线是否正确，由 OHPM、Hvigor、CMake 和 ArkTS 编译器验证。
 
 常用选项：
 
-- `--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 先执行生产导出，不启动 Metro。
+- `--device <id-or-name>`：选择已连接的 HDC 设备，或按完整名称启动本地模拟器，例如 `--device "Pura 90 Pro"`。有多个候选目标时必须指定。
+- `--port <number>`：Metro 端口和设备反向映射端口，默认 `8081`。
+- `--no-bundler`：连接已经在运行的 Expo Metro，不启动新的服务；端口空闲或被其他进程占用时报错。不加此选项时，端口上已有 Metro 在运行就直接复用。
 - `--reset-cache`：Debug 模式下启动 Metro 时清除 Metro 缓存；Release 模式下清除生产导出缓存。
 - `--no-install`：跳过 HAP 安装，直接启动设备上已有的应用。
-- `--app-id <bundleName>`：指定要启动的应用；与生成包名不同时必须同时使用 `--no-install`。
+- `--app-id <bundleName>`：指定要启动的应用；与生成的包名不同时，必须同时使用 `--no-install`。
 - `--sync`：构建前强制重新执行一次预构建。
 
-Debug 模式下由 CLI 启动的 Metro 会接管终端输出日志，按 Ctrl+C 退出。
+Debug 模式下由 CLI 启动的 Metro 接管终端输出日志，Ctrl+C 退出。
 
-未指定 `--device` 时，优先使用已连接的设备；没有连接的设备时，优先等待正在启动的模拟器，否则自动启动唯一的本地模拟器。存在多个候选模拟器时会列出名称，使用 `--device "模拟器名称"` 选择。通过模拟器名称选择或自动拉起时，等待 HDC 连接并确认该实例开机完成后才继续构建、安装和启动应用，最多等待 120 秒；退出 CLI 或 Metro 后模拟器继续运行。
+未指定 `--device` 时，优先用已连接的设备。没有连接的设备时，先等正在启动的模拟器；否则启动唯一的本地模拟器。有多个候选模拟器时列出名称，用 `--device "模拟器名称"` 选择。通过名称选择或自动拉起模拟器时，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 中创建模拟器。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 安装布局 → 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` 显式指定。
+工具链按「环境变量覆盖 → 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` 指定。
 
 ## Author
 

package/build/buildHap/build.js

@@ -50,6 +50,7 @@ async function buildHarmonyUnlockedAsync(projectRoot, options = {}) {
     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

package/build/buildHap/common.d.ts

@@ -1,7 +1,7 @@
 interface HarmonyBuildPipelineOptions {
     io?: Pick<Console, 'error' | 'log' | 'warn'>;
     requireDeviceTools?: boolean;
-    /** @internal The caller already completed an isolated prebuild check. */
+    /** @internal Reuse the native project without an isolated drift check. */
     skipGeneratedProjectCheck?: boolean;
     sync: boolean;
     variant: 'debug' | 'release';

package/build/doctor/doctor.js

@@ -59,7 +59,19 @@ async function validateMetroConfigAsync(projectRoot) {
         })();
         throw new Error(`metro-config ${version} does not expose resolveConfig().`);
     }
-    const resolved = await metroConfig.resolveConfig(undefined, projectRoot);
+    const hadMetroTarget = Object.hasOwn(process.env, 'EXPO_METRO_TARGET');
+    const previousMetroTarget = process.env.EXPO_METRO_TARGET;
+    let resolved;
+    try {
+        process.env.EXPO_METRO_TARGET = 'harmony';
+        resolved = await metroConfig.resolveConfig(undefined, projectRoot);
+    }
+    finally {
+        if (hadMetroTarget)
+            process.env.EXPO_METRO_TARGET = previousMetroTarget;
+        else
+            delete process.env.EXPO_METRO_TARGET;
+    }
     const config = resolved?.config;
     const platforms = config?.resolver?.platforms;
     const conditions = config?.resolver?.unstable_conditionsByPlatform?.harmony;
@@ -153,6 +165,7 @@ async function doctorUnlockedAsync(projectRoot, options = {}) {
         tools.unshift(['hdc', toolchain.hdc, ['-v'], unavailableToolStatus]);
     }
     for (const [id, tool, versionArgs, unavailableStatus] of tools) {
+        const command = [tool.command, ...tool.args].map(value => JSON.stringify(value)).join(' ');
         try {
             const result = await (0, process_1.spawnAsync)(tool.command, [...tool.args, ...versionArgs], {
                 capture: true,
@@ -161,11 +174,11 @@ async function doctorUnlockedAsync(projectRoot, options = {}) {
                 timeoutMs: 10_000,
             });
             checks.push(result.code === 0 && !result.timedOut
-                ? check(id, 'pass', `${tool.command} is available through ${tool.source}.`)
-                : check(id, unavailableStatus, `${tool.command} is unavailable or unhealthy; HAP build cannot be verified.`));
+                ? check(id, 'pass', `${command} is available through ${tool.source}.`)
+                : check(id, unavailableStatus, `${command} is unavailable or unhealthy; HAP build cannot be verified.`));
         }
         catch {
-            checks.push(check(id, unavailableStatus, `${tool.command} is unavailable; generation remains available.`));
+            checks.push(check(id, unavailableStatus, `${command} is unavailable; generation remains available.`));
         }
     }
     if (options.validateGeneratedProject !== false) {

package/build/exportEmbed/export.js

@@ -65,6 +65,7 @@ async function exportEmbedUnlockedAsync(projectRoot, options = {}) {
             cwd: projectRoot,
             env: {
                 ...process.env,
+                EXPO_METRO_TARGET: 'harmony',
                 HERMES_V1_ENABLED: 'true',
                 NODE_ENV: 'production',
             },

package/build/prebuild/check.js

@@ -31,6 +31,16 @@ function mirrorRoot(temp, project) {
     const segments = absolute.slice(parsed.root.length).split(node_path_1.default.sep).filter(Boolean);
     return node_path_1.default.join(temp, 'filesystem', volume, ...segments);
 }
+async function linkModuleEntryAsync(source, target, entry) {
+    const directory = entry.isSymbolicLink()
+        ? (await node_fs_1.default.promises.stat(source)).isDirectory()
+        : entry.isDirectory();
+    if (process.platform === 'win32' && !directory) {
+        await node_fs_1.default.promises.copyFile(source, target);
+        return;
+    }
+    await node_fs_1.default.promises.symlink(node_path_1.default.resolve(source), target, directory ? process.platform === 'win32' ? 'junction' : 'dir' : 'file');
+}
 async function linkModulesAsync(source, target) {
     await node_fs_1.default.promises.mkdir(target, { recursive: true });
     for (const entry of await node_fs_1.default.promises.readdir(source, { withFileTypes: true })) {
@@ -39,15 +49,11 @@ async function linkModulesAsync(source, target) {
         if (entry.name.startsWith('@') && entry.isDirectory() && !entry.isSymbolicLink()) {
             await node_fs_1.default.promises.mkdir(to);
             for (const child of await node_fs_1.default.promises.readdir(from, { withFileTypes: true })) {
-                await node_fs_1.default.promises.symlink(node_path_1.default.join(from, child.name), node_path_1.default.join(to, child.name), process.platform === 'win32' && (child.isDirectory() || child.isSymbolicLink())
-                    ? 'junction'
-                    : child.isDirectory() ? 'dir' : 'file');
+                await linkModuleEntryAsync(node_path_1.default.join(from, child.name), node_path_1.default.join(to, child.name), child);
             }
             continue;
         }
-        await node_fs_1.default.promises.symlink(from, to, process.platform === 'win32' && (entry.isDirectory() || entry.isSymbolicLink())
-            ? 'junction'
-            : entry.isDirectory() ? 'dir' : 'file');
+        await linkModuleEntryAsync(from, to, entry);
     }
 }
 function isAppLocalHarmonyPath(project, source) {
@@ -90,8 +96,8 @@ async function copyAsync(project, target, plan, temp = node_path_1.default.dirna
     // Keep a real node_modules directory in the isolated project and link its
     // entries. Dependency scanners then retain the isolated lexical package path
     // (including scoped packages) instead of collapsing the entire node_modules
-    // root to the source project's realpath. The packages remain read-only and
-    // are never copied or modified by --check.
+    // root to the source project's realpath. Package directories stay linked;
+    // Windows copies loose files to avoid requiring file-symlink privileges.
     await linkModulesAsync(modules, node_path_1.default.join(target, 'node_modules'));
     await (0, check_1.stageAsync)(project, target, temp);
 }

package/build/process.d.ts

@@ -25,7 +25,7 @@ declare function startManagedProcess(command: string, args: string[], options?:
     completion: Promise<ProcessResult>;
     getStderr: () => string;
     getStdout: () => string;
-    stop: (signal?: NodeJS.Signals, graceMs?: number) => Promise<any>;
+    stop: (signal?: NodeJS.Signals, graceMs?: number) => Promise<ProcessResult>;
     wasStopped: () => boolean;
 };
 export { formatDiagnostics, spawnAsync, startManagedProcess };

package/build/process.js

@@ -7,6 +7,7 @@ exports.formatDiagnostics = formatDiagnostics;
 exports.spawnAsync = spawnAsync;
 exports.startManagedProcess = startManagedProcess;
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
+const tool_command_1 = require("@expo-harmony/expo-modules-autolinking/tool-command");
 const errors_1 = require("./errors");
 const DefaultOutputLimit = 1024 * 1024;
 const DefaultStopGraceMs = 3_000;
@@ -53,8 +54,14 @@ function formatDiagnostics(result, limit = 4_000) {
 }
 function spawnAsync(command, args, options = {}) {
     return new Promise((resolve, reject) => {
+        if (options.signal?.aborted) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: operation aborted.`, {
+                cause: options.signal.reason,
+                operation: options.operation || 'spawn',
+            });
+        }
         const piped = Boolean(options.capture || options.onStdout || options.onStderr);
-        const outputLimit = options.outputLimit || DefaultOutputLimit;
+        const limit = options.outputLimit || DefaultOutputLimit;
         const child = (0, cross_spawn_1.default)(command, args, {
             cwd: options.cwd,
             env: options.env || process.env,
@@ -62,11 +69,12 @@ function spawnAsync(command, args, options = {}) {
             stdio: piped ? ['ignore', 'pipe', 'pipe'] : 'inherit',
             windowsHide: true,
         });
-        const stdout = new BoundedCapture(outputLimit);
-        const stderr = new BoundedCapture(outputLimit);
+        const stdout = new BoundedCapture(limit);
+        const stderr = new BoundedCapture(limit);
         let timedOut = false;
         let settled = false;
-        let forceKillTimer = null;
+        let escalation = null;
+        let stopping;
         if (piped) {
             child.stdout.on('data', (chunk) => {
                 stdout.append(chunk);
@@ -77,67 +85,91 @@ function spawnAsync(command, args, options = {}) {
                 options.onStderr?.(chunk);
             });
         }
-        const stopChild = (signal = 'SIGTERM') => {
-            child.kill(signal);
-            if (forceKillTimer === null) {
-                forceKillTimer = setTimeout(() => child.kill('SIGKILL'), options.stopGraceMs || DefaultStopGraceMs);
-                forceKillTimer.unref?.();
+        const stop = (signal = 'SIGTERM') => {
+            if (stopping || settled)
+                return;
+            stopping = Promise.resolve().then(() => (0, tool_command_1.terminateProcess)(child, signal));
+            if (process.platform === 'win32') {
+                void finish(null, signal);
+            }
+            else {
+                stopping.catch((cause) => {
+                    void finish(null, null, cause);
+                });
+                escalation = setTimeout(() => {
+                    stopping = (0, tool_command_1.terminateProcess)(child, 'SIGKILL');
+                    stopping.catch((cause) => {
+                        void finish(null, null, cause);
+                    });
+                }, options.stopGraceMs || DefaultStopGraceMs);
+                escalation.unref?.();
             }
         };
-        const forwardSigint = () => stopChild('SIGINT');
-        const forwardSigterm = () => stopChild('SIGTERM');
-        process.once('SIGINT', forwardSigint);
-        process.once('SIGTERM', forwardSigterm);
+        const interrupt = () => stop('SIGINT');
+        const terminate = () => stop('SIGTERM');
+        process.once('SIGINT', interrupt);
+        process.once('SIGTERM', terminate);
         const timeout = options.timeoutMs
             ? setTimeout(() => {
                 timedOut = true;
-                stopChild('SIGTERM');
+                stop('SIGTERM');
             }, options.timeoutMs)
             : null;
         timeout?.unref?.();
         const cleanup = () => {
             if (timeout)
                 clearTimeout(timeout);
-            if (forceKillTimer)
-                clearTimeout(forceKillTimer);
-            process.removeListener('SIGINT', forwardSigint);
-            process.removeListener('SIGTERM', forwardSigterm);
+            if (escalation)
+                clearTimeout(escalation);
+            process.removeListener('SIGINT', interrupt);
+            process.removeListener('SIGTERM', terminate);
             options.signal?.removeEventListener('abort', abort);
         };
-        const abort = () => stopChild('SIGTERM');
-        if (options.signal?.aborted)
-            abort();
-        else
-            options.signal?.addEventListener('abort', abort, { once: true });
-        child.once('error', (cause) => {
+        const finish = async (code, signal, cause) => {
+            try {
+                await stopping;
+            }
+            catch (error) {
+                cause = error;
+            }
             if (settled)
                 return;
             settled = true;
             cleanup();
-            reject(new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
-                cause,
-                operation: options.operation || 'spawn',
-            }));
+            if (cause)
+                reject(new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: ${cause.message}`, {
+                    cause,
+                    operation: options.operation || 'spawn',
+                }));
+            else
+                resolve({
+                    code: code === null ? 1 : code,
+                    signal,
+                    stderr: stderr.toString(),
+                    stdout: stdout.toString(),
+                    timedOut,
+                });
+        };
+        child.once('error', (cause) => {
+            void finish(null, null, cause);
         });
-        // `close` runs after stdout/stderr have closed, so captured diagnostics are
-        // complete. `exit` can fire while pipe data is still pending.
         child.once('close', (code, signal) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            resolve({
-                code: code === null ? 1 : code,
-                signal,
-                stderr: stderr.toString(),
-                stdout: stdout.toString(),
-                timedOut,
-            });
+            void finish(code, signal);
         });
+        const abort = () => stop('SIGTERM');
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
     });
 }
 function startManagedProcess(command, args, options = {}) {
-    const outputLimit = options.outputLimit || DefaultOutputLimit;
+    if (options.signal?.aborted) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: operation aborted.`, {
+            cause: options.signal.reason,
+            operation: options.operation || 'spawn',
+        });
+    }
+    const limit = options.outputLimit || DefaultOutputLimit;
     const piped = options.stdio !== 'inherit';
     const child = (0, cross_spawn_1.default)(command, args, {
         cwd: options.cwd,
@@ -146,11 +178,14 @@ function startManagedProcess(command, args, options = {}) {
         stdio: piped ? ['ignore', 'pipe', 'pipe'] : 'inherit',
         windowsHide: true,
     });
-    const stdout = new BoundedCapture(outputLimit);
-    const stderr = new BoundedCapture(outputLimit);
-    let spawnError = null;
+    const stdout = new BoundedCapture(limit);
+    const stderr = new BoundedCapture(limit);
+    let failure = null;
     let closed = false;
-    let stopRequested = false;
+    let stopped = false;
+    let stopping;
+    let stopPromise;
+    let finish;
     if (piped) {
         child.stdout.on('data', (chunk) => {
             stdout.append(chunk);
@@ -161,32 +196,42 @@ function startManagedProcess(command, args, options = {}) {
             options.onStderr?.(chunk);
         });
     }
-    const forwardSigint = () => {
-        void stop('SIGINT');
+    const interrupt = () => {
+        void stop('SIGINT').catch(() => { });
     };
-    const forwardSigterm = () => {
-        void stop('SIGTERM');
+    const terminate = () => {
+        void stop('SIGTERM').catch(() => { });
     };
     const abort = () => {
-        void stop('SIGTERM');
+        void stop('SIGTERM').catch(() => { });
     };
     const cleanup = () => {
-        process.removeListener('SIGINT', forwardSigint);
-        process.removeListener('SIGTERM', forwardSigterm);
+        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGTERM', terminate);
         options.signal?.removeEventListener('abort', abort);
     };
     const completion = new Promise((resolve, reject) => {
         child.once('error', (cause) => {
-            spawnError = new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
+            failure = new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
                 cause,
                 operation: options.operation || 'spawn',
             });
         });
-        child.once('close', (code, signal) => {
+        finish = async (code, signal) => {
+            try {
+                await stopping;
+            }
+            catch (cause) {
+                failure = new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot stop ${command}: ${cause.message}`, {
+                    cause, operation: options.operation || 'spawn',
+                });
+            }
+            if (closed)
+                return;
             closed = true;
             cleanup();
-            if (spawnError)
-                reject(spawnError);
+            if (failure)
+                reject(failure);
             else
                 resolve({
                     code: code === null ? 1 : code,
@@ -195,32 +240,59 @@ function startManagedProcess(command, args, options = {}) {
                     stdout: stdout.toString(),
                     timedOut: false,
                 });
+        };
+        child.once('close', (code, signal) => {
+            void finish(code, signal);
         });
     });
     // A readiness probe may be the first consumer. Keep early spawn failures from
     // becoming unhandled rejections while the probe is still polling.
     completion.catch(() => { });
     async function stop(signal = 'SIGTERM', graceMs = DefaultStopGraceMs) {
+        if (stopPromise)
+            return stopPromise;
         if (closed)
             return completion;
-        stopRequested = true;
-        child.kill(signal);
-        let timer;
-        await Promise.race([
-            completion.catch(() => undefined),
-            new Promise((resolve) => {
-                timer = setTimeout(resolve, graceMs);
-                timer.unref?.();
-            }),
-        ]);
-        if (timer)
-            clearTimeout(timer);
-        if (!closed)
-            child.kill('SIGKILL');
-        return completion.catch(() => undefined);
+        stopped = true;
+        stopping = Promise.resolve().then(() => (0, tool_command_1.terminateProcess)(child, signal));
+        stopPromise = (async () => {
+            if (process.platform === 'win32') {
+                void finish(null, signal);
+                return completion;
+            }
+            try {
+                await stopping;
+            }
+            catch {
+                await finish(null, signal);
+                return completion;
+            }
+            let timer;
+            await Promise.race([
+                completion.catch(() => undefined),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, graceMs);
+                    timer.unref?.();
+                }),
+            ]);
+            if (timer)
+                clearTimeout(timer);
+            if (!closed) {
+                stopping = (0, tool_command_1.terminateProcess)(child, 'SIGKILL');
+                try {
+                    await stopping;
+                }
+                catch {
+                    await finish(null, signal);
+                }
+            }
+            return completion.catch(() => undefined);
+        })();
+        stopPromise.catch(() => { });
+        return stopPromise;
     }
-    process.once('SIGINT', forwardSigint);
-    process.once('SIGTERM', forwardSigterm);
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', terminate);
     if (options.signal?.aborted)
         abort();
     else
@@ -231,6 +303,6 @@ function startManagedProcess(command, args, options = {}) {
         getStderr: () => stderr.toString(),
         getStdout: () => stdout.toString(),
         stop,
-        wasStopped: () => stopRequested,
+        wasStopped: () => stopped,
     };
 }

package/build/run/metro.js

@@ -88,6 +88,7 @@ async function startExpoMetroAsync(projectRoot, options) {
         cwd: projectRoot,
         env: {
             ...process.env,
+            EXPO_METRO_TARGET: 'harmony',
         },
         operation: 'expo-metro',
         outputLimit: 1024 * 1024,