expo-harmony-toolkit 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BlackishGreen33
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,197 @@
+<div align="center">
+  <h1>Expo Harmony Toolkit</h1>
+  <p><strong>A HarmonyOS migration, admission, and UI-stack build toolkit for Managed/CNG Expo projects.</strong></p>
+  <p>One validated UI-stack matrix, explicit dependency admission rules, managed Harmony sidecar scaffolding, and a toolkit-driven <code>doctor → init → bundle → build-hap</code> path.</p>
+  <p>
+    <a href="./README.md">简体中文</a> ·
+    <a href="./README.en.md">English</a>
+  </p>
+  <p>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/badge/checks-passing-16a34a?style=flat-square&logo=githubactions&logoColor=white"></a>
+    <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-0f766e?style=flat-square"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.5.0-111827?style=flat-square"></a>
+    <a href="./docs/support-matrix.md"><img alt="Matrix" src="https://img.shields.io/badge/matrix-expo55--rnoh082--ui--stack-2563eb?style=flat-square"></a>
+    <img alt="Input" src="https://img.shields.io/badge/input-Managed%2FCNG-059669?style=flat-square">
+  </p>
+  <p>
+    <a href="./docs/support-matrix.md">Support Matrix</a> ·
+    <a href="./docs/cli-build.md">CLI Build Guide</a> ·
+    <a href="./docs/official-ui-stack-sample.md">Official UI Stack Sample</a> ·
+    <a href="./docs/npm-release.md">npm Release Notes</a> ·
+    <a href="./docs/roadmap.md">Roadmap</a>
+  </p>
+</div>
+
+> [!IMPORTANT]
+> `v1.5.0` makes one formal public promise only: `expo55-rnoh082-ui-stack`. This is not a claim that arbitrary Expo applications can be published to HarmonyOS unchanged.
+
+> [!TIP]
+> The three validated `@react-native-oh-tpl/*` adapters are currently consumed via exact Git URLs and commits. For repository development and the official UI-stack sample, prefer `pnpm install --ignore-scripts` so adapter prepare hooks do not fail on private upstream resources.
+
+## Overview
+
+`expo-harmony-toolkit` provides a constrained, verifiable Expo-to-Harmony toolchain:
+
+- Expo config plugin entrypoint `app.plugin.js`
+- `expo-harmony doctor`
+- `expo-harmony init`
+- `expo-harmony sync-template`
+- `expo-harmony env`
+- `expo-harmony bundle`
+- `expo-harmony build-hap --mode debug|release`
+- Managed `harmony/` sidecar templates and autolinking artifacts
+- Stable `.expo-harmony/*.json` reports and metadata
+
+## Current Status
+
+| Item | Status |
+| --- | --- |
+| Current version | `v1.5.0` |
+| Public matrix | `expo55-rnoh082-ui-stack` |
+| Supported input | Managed/CNG Expo projects |
+| Validated JS/UI capabilities | `expo-router`, `expo-linking`, `expo-constants`, `react-native-reanimated`, `react-native-svg`, `react-native-gesture-handler` |
+| Build path | `doctor -> init -> bundle -> build-hap` |
+| Primary sample | `examples/official-ui-stack-sample` |
+| Regression baselines | `examples/official-app-shell-sample`, `examples/official-minimal-sample` |
+
+<details>
+<summary><strong>Currently out of scope</strong></summary>
+
+- bare Expo
+- `expo-image-picker`
+- `expo-file-system`
+- `expo-location`
+- `expo-camera`
+- `expo-notifications`
+- multiple public matrices
+
+</details>
+
+## Quick Start
+
+For this repository:
+
+```bash
+pnpm install --ignore-scripts
+pnpm build
+pnpm test
+```
+
+For any Expo project:
+
+```bash
+expo-harmony doctor --project-root /path/to/app
+expo-harmony doctor --project-root /path/to/app --strict
+expo-harmony init --project-root /path/to/app
+expo-harmony sync-template --project-root /path/to/app
+```
+
+Inside the project root:
+
+```bash
+cd /path/to/app
+expo-harmony env --strict
+expo-harmony build-hap --mode debug
+```
+
+If you only need the JavaScript artifact:
+
+```bash
+expo-harmony bundle
+```
+
+## Support Matrix
+
+`v1.5.0` stays on one public matrix: `expo55-rnoh082-ui-stack`.
+
+- Expo SDK: `55`
+- React: `19.2.x`
+- React Native: `0.83.x`
+- RNOH and `@react-native-oh/react-native-harmony-cli`: `0.82.18`
+- App Shell packages: `expo-router`, `expo-linking`, `expo-constants`
+- UI stack packages: `react-native-reanimated`, `react-native-svg`, `react-native-gesture-handler`
+- Harmony adapters: the matching `@react-native-oh-tpl/*` exact Git specifiers
+- Native identifier: at least `android.package` or `ios.bundleIdentifier`
+
+See [docs/support-matrix.md](./docs/support-matrix.md) for the full allowlist, pairing rules, exact specifiers, issue codes, and release gates.
+
+## Official Samples
+
+- `examples/official-ui-stack-sample`
+  The primary public sample for `v1.5.0`, covering router, linking, constants, SVG, gesture, reanimated, and Harmony sidecar build flow.
+- `examples/official-app-shell-sample`
+  The `v1.1` App Shell regression baseline that protects router behavior while UI-stack support is finalized.
+- `examples/official-minimal-sample`
+  The smallest smoke baseline for sidecar templates and the shortest bundle path.
+
+See:
+
+- [Official UI Stack Sample Guide](./docs/official-ui-stack-sample.md)
+- [Official App Shell Sample Guide](./docs/official-app-shell-sample.md)
+- [Official Minimal Sample Guide](./docs/official-minimal-sample.md)
+
+## CLI Commands
+
+| Command | Purpose |
+| --- | --- |
+| `expo-harmony doctor` | Inspect Expo config and dependencies and produce a migration report |
+| `expo-harmony doctor --strict` | Run the formal matrix admission gate |
+| `expo-harmony init` | Generate Harmony sidecar files, autolinking artifacts, metadata, and package scripts |
+| `expo-harmony sync-template` | Reapply managed templates and report drift |
+| `expo-harmony env` | Check the local DevEco / hvigor / hdc / signing environment |
+| `expo-harmony bundle` | Generate a standard `bundle.harmony.js` |
+| `expo-harmony build-hap --mode debug` | Trigger a debug HAP build |
+| `expo-harmony build-hap --mode release` | Trigger a release HAP build; signing must be ready |
+
+Key managed outputs include:
+
+- `harmony/oh-package.json5`
+- `harmony/entry/src/main/ets/RNOHPackagesFactory.ets`
+- `harmony/entry/src/main/cpp/RNOHPackagesFactory.h`
+- `harmony/entry/src/main/cpp/autolinking.cmake`
+- `metro.harmony.config.js`
+- `.expo-harmony/manifest.json`
+- `.expo-harmony/doctor-report.json`
+- `.expo-harmony/env-report.json`
+- `.expo-harmony/build-report.json`
+- `.expo-harmony/toolkit-config.json`
+
+## Release And Validation
+
+Pre-publish checks:
+
+- `pnpm build`
+- `pnpm test`
+- `npm pack --dry-run`
+- tarball smoke: `doctor --strict`, `init --force`, `bundle`
+
+Automatic publishing defaults to hosted CI only:
+
+- GitHub workflow runs `build/test/pack/tarball smoke`
+- `build-hap --mode debug` does not block npm publish
+- npm publish uses the `latest` dist-tag and provenance
+
+Manual Harmony acceptance still requires:
+
+- `official-ui-stack-sample` launches successfully
+- SVG renders correctly
+- the gesture triggers visible animation
+- routing still works after the animation completes
+- `Build Debug Hap(s)` succeeds
+
+See [docs/npm-release.md](./docs/npm-release.md) and [docs/signing-and-release.md](./docs/signing-and-release.md).
+
+## Documentation
+
+- [Support Matrix](./docs/support-matrix.md)
+- [CLI Build Guide](./docs/cli-build.md)
+- [Official UI Stack Sample Guide](./docs/official-ui-stack-sample.md)
+- [Official App Shell Sample Guide](./docs/official-app-shell-sample.md)
+- [Official Minimal Sample Guide](./docs/official-minimal-sample.md)
+- [npm Release Notes](./docs/npm-release.md)
+- [Signing and Release Notes](./docs/signing-and-release.md)
+- [Roadmap](./docs/roadmap.md)
+
+## License
+
+Released under the [MIT License](./LICENSE).

package/README.md

@@ -0,0 +1,197 @@
+<div align="center">
+  <h1>Expo Harmony Toolkit</h1>
+  <p><strong>面向 Managed/CNG Expo 项目的 HarmonyOS 迁移、准入检查与 UI-stack 构建工具链。</strong></p>
+  <p>One validated UI-stack matrix, explicit dependency admission rules, managed Harmony sidecar scaffolding, and a toolkit-driven <code>doctor → init → bundle → build-hap</code> path.</p>
+  <p>
+    <a href="./README.md">简体中文</a> ·
+    <a href="./README.en.md">English</a>
+  </p>
+  <p>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/badge/checks-passing-16a34a?style=flat-square&logo=githubactions&logoColor=white"></a>
+    <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-0f766e?style=flat-square"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Plugin/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.5.0-111827?style=flat-square"></a>
+    <a href="./docs/support-matrix.md"><img alt="Matrix" src="https://img.shields.io/badge/matrix-expo55--rnoh082--ui--stack-2563eb?style=flat-square"></a>
+    <img alt="Input" src="https://img.shields.io/badge/input-Managed%2FCNG-059669?style=flat-square">
+  </p>
+  <p>
+    <a href="./docs/support-matrix.md">支持矩阵</a> ·
+    <a href="./docs/cli-build.md">CLI 构建指南</a> ·
+    <a href="./docs/official-ui-stack-sample.md">官方 UI Stack Sample</a> ·
+    <a href="./docs/npm-release.md">npm 发布说明</a> ·
+    <a href="./docs/roadmap.md">路线图</a>
+  </p>
+</div>
+
+> [!IMPORTANT]
+> `v1.5.0` 只对 `expo55-rnoh082-ui-stack` 做正式公开承诺。这不是“任意 Expo 项目都能原样发布到 HarmonyOS”的声明，而是对一条受限、可验证矩阵的稳定承诺。
+
+> [!TIP]
+> 由于当前三套 `@react-native-oh-tpl/*` adapter 依赖以 Git URL + exact commit 形式接入，仓库开发和官方 UI-stack sample 推荐使用 `pnpm install --ignore-scripts`，避免 Git adapter 在 prepare 阶段拉取私有资源而中断安装。
+
+## 概览
+
+`expo-harmony-toolkit` 提供一条围绕 Expo 到 HarmonyOS 迁移的受限、可验证工具链：
+
+- Expo config plugin 根入口 `app.plugin.js`
+- `expo-harmony doctor`
+- `expo-harmony init`
+- `expo-harmony sync-template`
+- `expo-harmony env`
+- `expo-harmony bundle`
+- `expo-harmony build-hap --mode debug|release`
+- 受管 `harmony/` sidecar 模板与 autolinking 产物
+- `.expo-harmony/*.json` 形式的稳定报告与元数据
+
+## 当前状态
+
+| 项目 | 说明 |
+| --- | --- |
+| 当前版本 | `v1.5.0` |
+| 唯一公开矩阵 | `expo55-rnoh082-ui-stack` |
+| 输入范围 | Managed/CNG Expo 项目 |
+| 已验证 JS/UI 能力 | `expo-router`、`expo-linking`、`expo-constants`、`react-native-reanimated`、`react-native-svg`、`react-native-gesture-handler` |
+| 构建链 | `doctor -> init -> bundle -> build-hap` |
+| 主 sample | `examples/official-ui-stack-sample` |
+| 回归基线 | `examples/official-app-shell-sample`、`examples/official-minimal-sample` |
+
+<details>
+<summary><strong>当前不在承诺范围</strong></summary>
+
+- bare Expo
+- `expo-image-picker`
+- `expo-file-system`
+- `expo-location`
+- `expo-camera`
+- `expo-notifications`
+- 多矩阵并行支持
+
+</details>
+
+## 快速开始
+
+仓库自身：
+
+```bash
+pnpm install --ignore-scripts
+pnpm build
+pnpm test
+```
+
+任意 Expo 项目：
+
+```bash
+expo-harmony doctor --project-root /path/to/app
+expo-harmony doctor --project-root /path/to/app --strict
+expo-harmony init --project-root /path/to/app
+expo-harmony sync-template --project-root /path/to/app
+```
+
+进入项目根目录后的 CLI 构建链：
+
+```bash
+cd /path/to/app
+expo-harmony env --strict
+expo-harmony build-hap --mode debug
+```
+
+如果你只想单独生成 JS bundle：
+
+```bash
+expo-harmony bundle
+```
+
+## 支持矩阵
+
+`v1.5.0` 继续坚持单矩阵路线：`expo55-rnoh082-ui-stack`。
+
+- Expo SDK：`55`
+- React：`19.2.x`
+- React Native：`0.83.x`
+- RNOH / `@react-native-oh/react-native-harmony-cli`：`0.82.18`
+- App Shell 依赖：`expo-router`、`expo-linking`、`expo-constants`
+- UI stack 依赖：`react-native-reanimated`、`react-native-svg`、`react-native-gesture-handler`
+- Harmony adapter：对应三项 `@react-native-oh-tpl/*` exact Git specifier
+- 原生标识：至少配置 `android.package` 或 `ios.bundleIdentifier`
+
+完整白名单、配对规则、exact specifier、issue code 与 release gate 见 [docs/support-matrix.md](./docs/support-matrix.md)。
+
+## 官方 Samples
+
+- `examples/official-ui-stack-sample`
+  当前唯一对外主 sample，同时覆盖 router、linking、constants、SVG、gesture、reanimated 和 Harmony sidecar 构建链。
+- `examples/official-app-shell-sample`
+  `v1.1` App Shell 回归基线，用来防止 UI-stack 收口引入 router 退化。
+- `examples/official-minimal-sample`
+  最小 smoke baseline，用来回归 sidecar 模板与最短 bundle 路径。
+
+详见：
+
+- [官方 UI Stack sample 指南](./docs/official-ui-stack-sample.md)
+- [官方 App Shell sample 指南](./docs/official-app-shell-sample.md)
+- [官方最小 sample 指南](./docs/official-minimal-sample.md)
+
+## CLI 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `expo-harmony doctor` | 扫描 Expo 配置与依赖，输出迁移报告 |
+| `expo-harmony doctor --strict` | 将当前矩阵准入检查作为正式 gate 执行 |
+| `expo-harmony init` | 生成 Harmony sidecar、autolinking 产物、metadata 与 package scripts |
+| `expo-harmony sync-template` | 再次应用受管模板并检查 drift |
+| `expo-harmony env` | 检查 DevEco / hvigor / hdc / signing 本地环境 |
+| `expo-harmony bundle` | 生成标准 `bundle.harmony.js` |
+| `expo-harmony build-hap --mode debug` | 触发 debug HAP 构建 |
+| `expo-harmony build-hap --mode release` | 触发 release HAP 构建，需要 signing 就绪 |
+
+关键受管产物包括：
+
+- `harmony/oh-package.json5`
+- `harmony/entry/src/main/ets/RNOHPackagesFactory.ets`
+- `harmony/entry/src/main/cpp/RNOHPackagesFactory.h`
+- `harmony/entry/src/main/cpp/autolinking.cmake`
+- `metro.harmony.config.js`
+- `.expo-harmony/manifest.json`
+- `.expo-harmony/doctor-report.json`
+- `.expo-harmony/env-report.json`
+- `.expo-harmony/build-report.json`
+- `.expo-harmony/toolkit-config.json`
+
+## 发布与验收
+
+发布前统一检查：
+
+- `pnpm build`
+- `pnpm test`
+- `npm pack --dry-run`
+- tarball 安装 smoke：`doctor --strict`、`init --force`、`bundle`
+
+自动发布默认走 hosted CI only：
+
+- GitHub workflow 跑 `build/test/pack/tarball smoke`
+- `build-hap --mode debug` 不阻塞 npm publish
+- npm 发布使用 `latest` dist-tag 和 provenance
+
+手动 Harmony 验收继续要求：
+
+- `official-ui-stack-sample` 成功启动
+- SVG 正常渲染
+- gesture 能触发可见动画
+- 动画完成后路由跳转仍正常
+- `Build Debug Hap(s)` 成功
+
+详见 [docs/npm-release.md](./docs/npm-release.md) 与 [docs/signing-and-release.md](./docs/signing-and-release.md)。
+
+## 文档索引
+
+- [支持矩阵](./docs/support-matrix.md)
+- [CLI 构建指南](./docs/cli-build.md)
+- [官方 UI Stack sample 指南](./docs/official-ui-stack-sample.md)
+- [官方 App Shell sample 指南](./docs/official-app-shell-sample.md)
+- [官方最小 sample 指南](./docs/official-minimal-sample.md)
+- [npm 发布说明](./docs/npm-release.md)
+- [签名与 Release 说明](./docs/signing-and-release.md)
+- [路线图](./docs/roadmap.md)
+
+## License
+
+本项目基于 [MIT License](./LICENSE) 发布。

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./build/plugin').default;

package/bin/expo-harmony.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+require('../build/cli')
+  .run(process.argv)
+  .catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    process.stderr.write(message + '\n');
+    process.exit(1);
+  });

package/build/cli.d.ts

@@ -0,0 +1 @@
+export declare function run(argv?: string[]): Promise<void>;

package/build/cli.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const commander_1 = require("commander");
+const constants_1 = require("./core/constants");
+const buildHap_1 = require("./commands/buildHap");
+const bundle_1 = require("./commands/bundle");
+const doctor_1 = require("./commands/doctor");
+const env_1 = require("./commands/env");
+const init_1 = require("./commands/init");
+const syncTemplate_1 = require("./commands/syncTemplate");
+async function run(argv = process.argv) {
+    const program = new commander_1.Command();
+    program
+        .name(constants_1.CLI_NAME)
+        .description('Validated Expo-to-Harmony toolkit for managed Expo UI-stack projects')
+        .version(constants_1.TOOLKIT_VERSION);
+    program
+        .command('env')
+        .description('Inspect the local DevEco/Harmony CLI environment for bundle and HAP builds')
+        .option('--strict', 'return a non-zero exit code when required local build tools are missing')
+        .option('--json', 'print JSON instead of a human-readable report')
+        .action(env_1.runEnvCommand);
+    program
+        .command('doctor')
+        .description('Inspect an Expo project and classify dependencies against the Harmony migration matrix')
+        .option('-p, --project-root <path>', 'path to the Expo project')
+        .option('--strict', 'return a non-zero exit code when the project falls outside the validated v1.5 matrix')
+        .option('--json', 'print JSON instead of a human-readable report')
+        .option('-o, --output <path>', 'write the JSON report to a file')
+        .action(doctor_1.runDoctorCommand);
+    program
+        .command('bundle')
+        .description('Generate a Harmony JavaScript bundle with the validated Metro sidecar')
+        .option('-p, --project-root <path>', 'path to the Expo project')
+        .action(bundle_1.runBundleCommand);
+    program
+        .command('build-hap')
+        .description('Build a Harmony HAP from the validated sidecar and bundle outputs')
+        .option('-p, --project-root <path>', 'path to the Expo project')
+        .option('--mode <mode>', 'build mode: debug or release', 'debug')
+        .action(buildHap_1.runBuildHapCommand);
+    program
+        .command('init')
+        .description('Scaffold Harmony sidecar files, vendored template files, and package scripts')
+        .option('-p, --project-root <path>', 'path to the Expo project')
+        .option('-f, --force', 'overwrite drifted managed files')
+        .action(init_1.runInitCommand);
+    program
+        .command('sync-template')
+        .description('Re-apply the vendored Harmony template in an idempotent way')
+        .option('-p, --project-root <path>', 'path to the Expo project')
+        .option('-f, --force', 'overwrite drifted managed files')
+        .action(syncTemplate_1.runSyncTemplateCommand);
+    await program.parseAsync(argv);
+}

package/build/commands/buildHap.d.ts

@@ -0,0 +1,5 @@
+export interface BuildHapCommandOptions {
+    projectRoot?: string;
+    mode?: 'debug' | 'release';
+}
+export declare function runBuildHapCommand(options: BuildHapCommandOptions): Promise<void>;

package/build/commands/buildHap.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBuildHapCommand = runBuildHapCommand;
+const path_1 = __importDefault(require("path"));
+const build_1 = require("../core/build");
+const metadata_1 = require("../core/metadata");
+async function runBuildHapCommand(options) {
+    const projectRoot = path_1.default.resolve(options.projectRoot ?? process.cwd());
+    const mode = options.mode ?? 'debug';
+    if (mode !== 'debug' && mode !== 'release') {
+        process.exitCode = 1;
+        process.stderr.write(`Unsupported build mode "${mode}". Expected debug or release.\n`);
+        return;
+    }
+    const report = await (0, build_1.buildHapProject)(projectRoot, {
+        mode,
+    });
+    await (0, metadata_1.writeBuildReport)(projectRoot, report);
+    if (report.status === 'failed') {
+        process.exitCode = 1;
+    }
+    process.stdout.write((0, build_1.renderBuildReport)(report) + '\n');
+}

package/build/commands/bundle.d.ts

@@ -0,0 +1,4 @@
+export interface BundleCommandOptions {
+    projectRoot?: string;
+}
+export declare function runBundleCommand(options: BundleCommandOptions): Promise<void>;

package/build/commands/bundle.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBundleCommand = runBundleCommand;
+const path_1 = __importDefault(require("path"));
+const build_1 = require("../core/build");
+const metadata_1 = require("../core/metadata");
+async function runBundleCommand(options) {
+    const projectRoot = path_1.default.resolve(options.projectRoot ?? process.cwd());
+    const report = await (0, build_1.bundleProject)(projectRoot);
+    await (0, metadata_1.writeBuildReport)(projectRoot, report);
+    if (report.status === 'failed') {
+        process.exitCode = 1;
+    }
+    process.stdout.write((0, build_1.renderBuildReport)(report) + '\n');
+}

package/build/commands/doctor.d.ts

@@ -0,0 +1,7 @@
+export interface DoctorCommandOptions {
+    projectRoot?: string;
+    strict?: boolean;
+    json?: boolean;
+    output?: string;
+}
+export declare function runDoctorCommand(options: DoctorCommandOptions): Promise<void>;

package/build/commands/doctor.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctorCommand = runDoctorCommand;
+const path_1 = __importDefault(require("path"));
+const constants_1 = require("../core/constants");
+const report_1 = require("../core/report");
+async function runDoctorCommand(options) {
+    const projectRoot = path_1.default.resolve(options.projectRoot ?? process.cwd());
+    const report = await (0, report_1.buildDoctorReport)(projectRoot);
+    if (options.output) {
+        await (0, report_1.writeDoctorReport)(projectRoot, report, path_1.default.resolve(options.output));
+    }
+    if (options.strict && report.eligibility === 'ineligible') {
+        process.exitCode = constants_1.STRICT_DOCTOR_EXIT_CODE;
+    }
+    if (options.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write((0, report_1.renderDoctorReport)(report) + '\n');
+}

package/build/commands/env.d.ts

@@ -0,0 +1,5 @@
+export interface EnvCommandOptions {
+    strict?: boolean;
+    json?: boolean;
+}
+export declare function runEnvCommand(options: EnvCommandOptions): Promise<void>;

package/build/commands/env.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEnvCommand = runEnvCommand;
+const path_1 = __importDefault(require("path"));
+const env_1 = require("../core/env");
+const metadata_1 = require("../core/metadata");
+async function runEnvCommand(options) {
+    const projectRoot = path_1.default.resolve(process.cwd());
+    const report = await (0, env_1.buildEnvReport)(projectRoot);
+    await (0, metadata_1.writeEnvReport)(projectRoot, report);
+    if (options.strict && report.blockingIssues.length > 0) {
+        process.exitCode = (0, env_1.getStrictEnvExitCode)();
+    }
+    if (options.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return;
+    }
+    process.stdout.write((0, env_1.renderEnvReport)(report) + '\n');
+}

package/build/commands/init.d.ts

@@ -0,0 +1,5 @@
+export interface InitCommandOptions {
+    projectRoot?: string;
+    force?: boolean;
+}
+export declare function runInitCommand(options: InitCommandOptions): Promise<void>;

package/build/commands/init.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitCommand = runInitCommand;
+const path_1 = __importDefault(require("path"));
+const template_1 = require("../core/template");
+const report_1 = require("../core/report");
+async function runInitCommand(options) {
+    const projectRoot = path_1.default.resolve(options.projectRoot ?? process.cwd());
+    const result = await (0, template_1.initProject)(projectRoot, Boolean(options.force));
+    const lines = [
+        (0, report_1.renderDoctorReport)(result.report),
+        '',
+        `Scaffold result:`,
+        `- written: ${result.sync.writtenFiles.length}`,
+        `- unchanged: ${result.sync.unchangedFiles.length}`,
+        `- skipped: ${result.sync.skippedFiles.length}`,
+        `- doctor report: ${result.doctorReportPath}`,
+    ];
+    if (result.sync.warnings.length > 0 || result.packageWarnings.length > 0) {
+        lines.push('', 'Warnings:');
+        for (const warning of [...result.sync.warnings, ...result.packageWarnings]) {
+            lines.push(`- ${warning}`);
+        }
+    }
+    process.stdout.write(lines.join('\n') + '\n');
+}

package/build/commands/syncTemplate.d.ts

@@ -0,0 +1,5 @@
+export interface SyncTemplateCommandOptions {
+    projectRoot?: string;
+    force?: boolean;
+}
+export declare function runSyncTemplateCommand(options: SyncTemplateCommandOptions): Promise<void>;