@expo-harmony/cli 55.0.26-harmony.1

package/README.md

@@ -0,0 +1,150 @@
+# @expo-harmony/cli
+
+[**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/cli)
+
+为 Expo 项目提供 HarmonyOS 平台的命令行工具，支持 Metro 开发服务、CNG 原生工程生成、环境诊断、Harmony Expo Module 发现与校验、生产 Bundle 导出，以及 HAP 的构建、安装和启动。
+
+## 安装
+
+```sh
+npm install --save-dev @expo-harmony/cli
+```
+
+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 配置。
+
+HAP 构建需要完整的 HarmonyOS SDK（含 HMS 与 OpenHarmony 组件）、OHPM、Hvigor 和 HDC，这些环境可用 `doctor` 命令检查。
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `expo-harmony start` | 启动 Harmony 开发所需的 Expo 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 export:embed` | 导出 Hermes 字节码、资源和 Source Map 并写入原生工程 |
+| `expo-harmony run` | 构建 HAP，在连接的 HarmonyOS 设备上安装并启动应用 |
+
+所有命令都可接收可选的项目路径（`modules` 命令写在子命令之后）；未提供时从当前目录向上查找最近的项目根目录作为默认值：
+
+```sh
+npx expo-harmony start ./my-app
+npx expo-harmony doctor ./my-app
+npx expo-harmony prebuild ./my-app
+npx expo-harmony build ./my-app --variant release
+npx expo-harmony run ./my-app --device <hdc-target>
+```
+
+## Start
+
+```sh
+npx expo-harmony start
+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 退出。
+
+支持 `--port <number>`（默认 `8081`）和 `--reset-cache`（别名 `--clear`、`-c`）。端口上已有 Metro 时提示并退出，不停止已有服务；此时缓存选项不会生效，需要先停止已有 Metro 后重新执行命令。端口被其他进程占用时会报错。
+
+需要构建并启动应用时，在另一个终端运行 `expo-harmony run --no-bundler`；若指定了端口，两个命令使用相同的 `--port`。
+
+## Prebuild
+
+```sh
+npx expo-harmony prebuild
+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（此阶段不要求构建工具就绪），发现阻塞错误时直接中止。
+
+`--clean` 只会清理带有 Expo Harmony 模板标记的原生目录：CNG manifest 缺失、目标不是项目内的普通目录或模板标记异常时都会拒绝删除。`--check` 是只读操作，会把项目镜像到临时目录（`node_modules` 以符号链接共享，不复制），在其中执行一次隔离的 prebuild 后比较受管文件；无差异时退出码为 `0`，有差异时列出变更并以 `2` 退出，且不能与其他会修改工程的选项同时使用。
+
+## Build
+
+```sh
+npx expo-harmony build
+npx expo-harmony build --variant release
+npx expo-harmony build --sync
+```
+
+`build` 在不使用设备的前提下完成 HAP 构建。缺少原生工程时自动执行 prebuild，`--sync` 强制重新生成，默认则校验 CNG 期望状态并在发现差错时报错。随后依次执行 OHPM 依赖安装、原生构建缓存校验和 Hvigor `assembleHap`，最后确认产物 HAP 存在且非空。原生依赖指纹变化时会自动失效旧的 `.cxx` 和 `build` 缓存，避免链接到过期的产物。
+
+选项：`--variant debug|release`（默认 `debug`）和 `--sync`。Release 构建会先执行生产导出，再带着预生成的 Bundle 进入 Hvigor。
+
+## Doctor
+
+```sh
+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 级别的问题时命令以非零状态退出；未配置外部签名文件只会警告，不影响未签名构建。
+
+## Modules
+
+```sh
+npx expo-harmony modules list
+npx expo-harmony modules inspect --package expo-linear-gradient
+npx expo-harmony modules verify
+```
+
+`list` 列出发现的模块候选（包名、版本、来源），并标出不支持 Harmony 的模块、重复版本和缺失的必需依赖。`inspect` 展示模块解析后的完整元数据，包括包根、ArkTS modules 和 HAR 路径，`--package <name>` 可筛选单个模块，未发现时报错。`verify` 输出诊断信息，存在 error 时以非零状态退出。
+
+三个子命令都支持 `--variant debug|release` 和 `--native-modules-dir <dir>`（app-local 模块目录，默认 `./modules`）。
+
+## Export
+
+```sh
+npx expo-harmony export:embed
+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 清除转换缓存。
+
+## Run
+
+```sh
+npx expo-harmony run \
+  --device <id-or-name> \
+  --variant debug \
+  --port 8081
+```
+
+`run` 会依次执行环境诊断、确保原生工程（缺失时自动预构建，`--sync` 强制重新生成，否则校验 CNG 状态）、选择设备、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 在运行则直接复用。
+- `--reset-cache`：Debug 模式下启动 Metro 时清除 Metro 缓存；Release 模式下清除生产导出缓存。
+- `--no-install`：跳过 HAP 安装，直接启动设备上已有的应用。
+- `--app-id <bundleName>`：指定要启动的应用；与生成包名不同时必须同时使用 `--no-install`。
+- `--sync`：构建前强制重新执行一次预构建。
+
+Debug 模式下由 CLI 启动的 Metro 会接管终端输出日志，按 Ctrl+C 退出。
+
+未指定 `--device` 时，优先使用已连接的设备；没有连接的设备时，优先等待正在启动的模拟器，否则自动启动唯一的本地模拟器。存在多个候选模拟器时会列出名称，使用 `--device "模拟器名称"` 选择。通过模拟器名称选择或自动拉起时，等待 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 安装布局 → 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
+
+**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)

package/build/bin/expo-harmony.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("../cli");
+(0, cli_1.main)();

package/build/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHarmonyAsync = exports.prepareHarmonyNativeBuildCacheAsync = exports.commitHarmonyNativeBuildCacheAsync = exports.runModulesCommandAsync = exports.formatModulesResult = exports.installHarmonyDependenciesAsync = exports.resolveHarmonyToolchain = exports.resolveHarmonyBuildPlanAsync = exports.exportEmbedAsync = exports.buildHarmonyAsync = exports.runAsync = void 0;
+var cli_1 = require("./cli");
+Object.defineProperty(exports, "runAsync", { enumerable: true, get: function () { return cli_1.runAsync; } });
+var build_1 = require("./buildHap/build");
+Object.defineProperty(exports, "buildHarmonyAsync", { enumerable: true, get: function () { return build_1.buildHarmonyAsync; } });
+var export_1 = require("./exportEmbed/export");
+Object.defineProperty(exports, "exportEmbedAsync", { enumerable: true, get: function () { return export_1.exportEmbedAsync; } });
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "resolveHarmonyBuildPlanAsync", { enumerable: true, get: function () { return tools_1.resolveHarmonyBuildPlanAsync; } });
+Object.defineProperty(exports, "resolveHarmonyToolchain", { enumerable: true, get: function () { return tools_1.resolveHarmonyToolchain; } });
+var install_1 = require("./run/install");
+Object.defineProperty(exports, "installHarmonyDependenciesAsync", { enumerable: true, get: function () { return install_1.installHarmonyDependenciesAsync; } });
+var modules_1 = require("./modules/modules");
+Object.defineProperty(exports, "formatModulesResult", { enumerable: true, get: function () { return modules_1.formatModulesResult; } });
+Object.defineProperty(exports, "runModulesCommandAsync", { enumerable: true, get: function () { return modules_1.runModulesCommandAsync; } });
+var cache_1 = require("./run/cache");
+Object.defineProperty(exports, "commitHarmonyNativeBuildCacheAsync", { enumerable: true, get: function () { return cache_1.commitHarmonyNativeBuildCacheAsync; } });
+Object.defineProperty(exports, "prepareHarmonyNativeBuildCacheAsync", { enumerable: true, get: function () { return cache_1.prepareHarmonyNativeBuildCacheAsync; } });
+var run_1 = require("./run/run");
+Object.defineProperty(exports, "runHarmonyAsync", { enumerable: true, get: function () { return run_1.runHarmonyAsync; } });

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@expo-harmony/cli",
+  "version": "55.0.26-harmony.1",
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-harmony",
+    "harmonyos"
+  ],
+  "homepage": "https://github.com/renbaoshuo/expo-harmony/tree/master/packages/cli#readme",
+  "bugs": "https://github.com/renbaoshuo/expo-harmony/issues",
+  "license": "MIT",
+  "author": "Baoshuo <i@baoshuo.ren>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/renbaoshuo/expo-harmony.git",
+    "directory": "packages/cli"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "prebuild": "yarn workspace @expo-harmony/prebuild-config build",
+    "build": "tsc -p tsconfig.json",
+    "prepare": "yarn build",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "require": "./build/index.js",
+      "default": "./build/index.js"
+    },
+    "./bin/expo-harmony": "./build/bin/expo-harmony.js"
+  },
+  "bin": {
+    "expo-harmony": "build/bin/expo-harmony.js"
+  },
+  "dependencies": {
+    "@expo-harmony/config-plugins": "55.0.10-harmony.1",
+    "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.1",
+    "@expo-harmony/prebuild-config": "55.0.0-harmony.1",
+    "@expo/config": "55.0.17",
+    "cross-spawn": "^7.0.6",
+    "json5": "2.2.3"
+  },
+  "peerDependencies": {
+    "expo": "55.0.26"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/node": "18.19.0",
+    "expo": "55.0.26",
+    "react": "19.2.3",
+    "react-native": "0.84.1",
+    "typescript": "6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.ts

@@ -0,0 +1,42 @@
+import {
+  parseArgs as parseNodeArgs,
+} from 'node:util';
+
+import { HarmonyCliError } from './errors';
+
+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;
+};
+
+const CommonOptions = {
+  help: { short: 'h', type: 'boolean' },
+} as const satisfies Options;
+
+function parseArgs<T extends Options>(
+  options: T,
+  argv: string[]
+): { positionals: string[]; values: Values<T> } {
+  try {
+    return parseNodeArgs({
+      allowPositionals: true,
+      args: argv,
+      options,
+      strict: true,
+    }) as { positionals: string[]; values: Values<T> };
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', message, {
+      cause,
+      operation: 'parse-arguments',
+    });
+  }
+}
+
+export { CommonOptions, parseArgs };

package/src/bin/expo-harmony.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from '../cli';
+
+main();

package/src/buildHap/build.ts

@@ -0,0 +1,164 @@
+import path from 'node:path';
+
+import { HarmonyCliError } from '../errors';
+import { exportEmbedAsync } from '../exportEmbed/export';
+import type { HarmonyExportManifest } from '../exportEmbed/manifest';
+import { toPosixPath } from '../path';
+import { withHarmonyProjectLockAsync } from '../projectLock';
+import {
+  commitHarmonyNativeBuildCacheAsync,
+  prepareHarmonyNativeBuildCacheAsync,
+} from '../run/cache';
+import { installHarmonyDependenciesAsync } from '../run/install';
+import {
+  resolveHarmonyBuildPlanAsync,
+  resolveHarmonyToolchain,
+} from '../tools';
+import {
+  ensureGeneratedProjectAsync,
+  isNonEmptyRegularFile,
+  progress,
+  runCheckedAsync,
+  timed,
+} from './common';
+
+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 {
+  bundleName: string;
+  export: null | { assetCount: number; bundleSha256: string; sourceMapSha256: string };
+  hapPath: string;
+  headless: true;
+  installed: false;
+  launched: false;
+  ok: true;
+  schemaVersion: 1;
+  steps: Record<string, number>;
+  variant: 'debug' | 'release';
+}
+
+type NormalizedBuildOptions = Required<HarmonyBuildOptions> & {
+  requireDeviceTools: false;
+};
+
+async function buildHarmonyUnlockedAsync(
+  projectRoot: string,
+  options: HarmonyBuildOptions = {}
+): Promise<HarmonyBuildResult> {
+  const normalizedOptions: NormalizedBuildOptions = {
+    io: options.io || console,
+    requireDeviceTools: false,
+    skipGeneratedProjectCheck: Boolean(options.skipGeneratedProjectCheck),
+    sync: Boolean(options.sync),
+    variant: options.variant || 'debug',
+  };
+  const steps: Record<string, number> = {
+    device: 0,
+    install: 0,
+    launch: 0,
+    metro: 0,
+    metroPort: 0,
+  };
+
+  await ensureGeneratedProjectAsync(projectRoot, normalizedOptions, steps);
+
+  const plan = await timed(steps, 'buildPlan', () => resolveHarmonyBuildPlanAsync(
+    projectRoot,
+    { buildMode: normalizedOptions.variant }
+  ));
+  const toolchain = resolveHarmonyToolchain();
+
+  let exportManifest: HarmonyExportManifest | null = null;
+  if (normalizedOptions.variant === 'release') {
+    progress(normalizedOptions, 'Exporting the release Hermes bundle');
+    exportManifest = await timed(steps, 'export', () => exportEmbedAsync(
+      projectRoot,
+      { skipDoctor: true }
+    ));
+  } else {
+    steps.export = 0;
+  }
+
+  progress(normalizedOptions, 'Installing Harmony project dependencies');
+  await timed(steps, 'ohpm', () => installHarmonyDependenciesAsync(plan, toolchain));
+
+  progress(normalizedOptions, 'Checking Harmony native dependency cache');
+  const nativeBuildCache = await timed(steps, 'nativeCache', () => (
+    prepareHarmonyNativeBuildCacheAsync(projectRoot, plan)
+  ));
+
+  if (nativeBuildCache.changed) {
+    progress(normalizedOptions, 'Invalidated stale Harmony native build objects');
+  }
+
+  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 timed(steps, 'build', () => 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 (!isNonEmptyRegularFile(plan.expectedHap)) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_HAP_MISSING',
+      'Hvigor completed without producing the expected non-empty regular HAP.',
+      { operation: 'verify-hap' }
+    );
+  }
+
+  await timed(steps, 'nativeCacheCommit', () => commitHarmonyNativeBuildCacheAsync(nativeBuildCache));
+
+  return {
+    bundleName: plan.bundleName,
+    export: exportManifest
+      ? {
+          assetCount: exportManifest.assets.length,
+          bundleSha256: exportManifest.bundle.sha256,
+          sourceMapSha256: exportManifest.sourceMap.sha256,
+        }
+      : null,
+    hapPath: toPosixPath(path.relative(projectRoot, plan.expectedHap)),
+    headless: true,
+    installed: false,
+    launched: false,
+    ok: true,
+    schemaVersion: 1,
+    steps,
+    variant: normalizedOptions.variant,
+  };
+}
+
+async function buildHarmonyAsync(
+  projectRoot: string,
+  options: HarmonyBuildOptions = {}
+): Promise<HarmonyBuildResult> {
+  return withHarmonyProjectLockAsync(
+    projectRoot,
+    'build',
+    () => buildHarmonyUnlockedAsync(projectRoot, options)
+  );
+}
+
+export { buildHarmonyAsync };

package/src/buildHap/common.ts

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+
+import { doctorAsync, type DoctorResult } from '../doctor/doctor';
+import { HarmonyCliError } from '../errors';
+import { checkAsync } from '../prebuild/check';
+import { prebuildParsedAsync } from '../prebuild/prebuild';
+import { formatDiagnostics, spawnAsync } from '../process';
+import { resolveHarmonyBuildPlanIfPresentAsync } from '../tools';
+
+interface HarmonyBuildPipelineOptions {
+  io?: Pick<Console, 'error' | 'log' | 'warn'>;
+  requireDeviceTools?: boolean;
+  /** @internal The caller already completed an isolated prebuild check. */
+  skipGeneratedProjectCheck?: boolean;
+  sync: boolean;
+  variant: 'debug' | 'release';
+}
+
+interface CheckedProcessOptions {
+  code: string;
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  message: string;
+  operation: string;
+  outputLimit?: number;
+  timeoutMs?: number;
+}
+
+function progress(options: HarmonyBuildPipelineOptions, message: string): void {
+  options.io?.log?.(`› ${message}`);
+}
+
+async function timed<T>(
+  steps: Record<string, number>,
+  name: string,
+  operation: () => Promise<T> | T
+): Promise<T> {
+  const started = performance.now();
+  try {
+    return await operation();
+  } finally {
+    steps[name] = Math.max(0, Math.round(performance.now() - started));
+  }
+}
+
+function assertDoctor(result: DoctorResult): void {
+  if (result.ok) return;
+
+  const failing = result.checks.filter(check => check.status === 'error').map(check => check.id);
+
+  throw new HarmonyCliError('ERR_HARMONY_DOCTOR_FAILED', `Harmony doctor found blocking checks: ${failing.join(', ') || 'unknown'}.`, { operation: 'doctor' });
+}
+
+function isNonEmptyRegularFile(file: string): boolean {
+  try {
+    const stat = fs.lstatSync(file);
+    return !stat.isSymbolicLink() && stat.isFile() && stat.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function runCheckedAsync(
+  command: string,
+  args: string[],
+  options: CheckedProcessOptions
+) {
+  const result = await spawnAsync(command, args, {
+    capture: true,
+    cwd: options.cwd,
+    env: options.env,
+    operation: options.operation,
+    outputLimit: options.outputLimit || 2 * 1024 * 1024,
+    timeoutMs: options.timeoutMs,
+  });
+
+  if (result.code !== 0 || result.timedOut) {
+    const diagnostics = formatDiagnostics(result);
+    throw new HarmonyCliError(
+      options.code,
+      `${options.message} exited with code ${result.code}${result.timedOut ? ' after timing out' : ''}.${diagnostics ? `\n${diagnostics}` : ''}`,
+      { exitCode: result.code || 1, operation: options.operation }
+    );
+  }
+
+  return result;
+}
+
+async function ensureGeneratedProjectAsync(
+  projectRoot: string,
+  options: HarmonyBuildPipelineOptions,
+  steps: Record<string, number>
+) {
+  const plan = await resolveHarmonyBuildPlanIfPresentAsync(projectRoot, {
+    buildMode: options.variant,
+  });
+  const exists = Boolean(plan && fs.existsSync(plan.harmonyRoot));
+
+  progress(options, 'Checking the Harmony project');
+  const doctor = await timed(steps, 'doctor', () => doctorAsync(projectRoot, {
+    requireBuildTools: true,
+    requireDeviceTools: options.requireDeviceTools,
+    validateGeneratedProject: exists,
+    validateModules: false,
+  }));
+  assertDoctor(doctor);
+
+  if (!exists || options.sync) {
+    progress(options, exists
+      ? 'Synchronizing the generated Harmony project'
+      : 'Generating the missing Harmony project');
+    await timed(steps, 'prebuild', () => prebuildParsedAsync(
+      projectRoot,
+      [],
+      { buildType: options.variant }
+    ));
+    steps.cngCheck = 0;
+    return;
+  }
+
+  steps.prebuild = 0;
+  if (options.skipGeneratedProjectCheck) {
+    steps.cngCheck = 0;
+    return;
+  }
+  progress(options, 'Checking CNG ownership and drift');
+  const check = await timed(steps, 'cngCheck', () => checkAsync(projectRoot, { 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' }
+    );
+  }
+}
+
+export {
+  ensureGeneratedProjectAsync,
+  isNonEmptyRegularFile,
+  progress,
+  runCheckedAsync,
+  timed,
+};
+export type { CheckedProcessOptions, HarmonyBuildPipelineOptions };

package/src/buildHap/options.ts

@@ -0,0 +1,35 @@
+import { CommonOptions, parseArgs } from '../args';
+import { HarmonyCliError } from '../errors';
+
+const BuildOptions = {
+  ...CommonOptions,
+  sync: { type: 'boolean' },
+  variant: { type: 'string' },
+} as const;
+
+function parseBuildArgs(argv: string[]) {
+  const { positionals, values } = parseArgs(BuildOptions, argv);
+
+  if (positionals.length > 1) {
+    throw new 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 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 as 'debug' | 'release',
+  };
+}
+
+export { parseBuildArgs };