expo-harmony-toolkit 1.9.0 → 1.9.1

package/README.en.md

@@ -9,7 +9,7 @@
   <p>
     <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/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-Toolkit/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.9.0-111827?style=flat-square"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.9.1-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%20%2B%20bare%20intake-059669?style=flat-square">
   </p>
@@ -24,7 +24,7 @@
 </div>
 
 > [!IMPORTANT]
-> `v1.9.0` keeps the `verified + preview + experimental` model and brings bare workflow intake, five app foundation modules, and the `react-native-gesture-handler` formal slice onto the mainline tracker. The public promise remains tighter: `latest` only carries fully accepted `verified` capabilities, while `next` is reserved for preview fast-track work. The expanded goal still does not widen the current `verified` boundary yet.
+> `v1.9.1` keeps the `v1.9.0` bare workflow intake, app foundation modules, and `react-native-gesture-handler` formal slice, and adds a local HAR normalize opt-out for `build-hap`. The public promise remains tighter: `latest` only carries fully accepted `verified` capabilities, while `next` is reserved for preview fast-track work. The expanded goal still does not widen the current `verified` boundary yet.
 
 > [!TIP]
 > The two validated `@react-native-oh-tpl/*` adapters in the public matrix 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.
@@ -48,7 +48,7 @@
 <!-- GENERATED:readme-current-status:start -->
 | Item | Status |
 | --- | --- |
-| Current version | `v1.9.0` |
+| Current version | `v1.9.1` |
 | Support model | `verified + preview + experimental` |
 | Public `verified` matrix | `expo55-rnoh082-ui-stack` |
 | Supported input | Managed/CNG Expo projects; bare workflow intake baseline |

package/README.md

@@ -9,7 +9,7 @@
   <p>
     <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/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-Toolkit/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.9.0-111827?style=flat-square"></a>
+    <a href="https://github.com/BlackishGreen33/Expo-Harmony-Toolkit/releases"><img alt="Version" src="https://img.shields.io/badge/version-v1.9.1-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%20%2B%20bare%20intake-059669?style=flat-square">
   </p>
@@ -24,7 +24,7 @@
 </div>
 
 > [!IMPORTANT]
-> `v1.9.0` 延续 `verified + preview + experimental` 三层支持模型，并把 bare workflow intake、五个 app foundation modules 与 `react-native-gesture-handler` formal slice 纳入主线追踪。当前公开承诺仍然收紧为：`latest` 只承诺完整验收的 `verified` 能力，`next` 用于 preview fast track。目标扩大不等于当前 `verified` 边界已经放宽。
+> `v1.9.1` 延续 `v1.9.0` 的 bare workflow intake、app foundation modules 与 `react-native-gesture-handler` formal slice，并为 `build-hap` 增加本地 HAR normalize opt-out。当前公开承诺仍然收紧为：`latest` 只承诺完整验收的 `verified` 能力，`next` 用于 preview fast track。目标扩大不等于当前 `verified` 边界已经放宽。
 
 > [!TIP]
 > 由于当前公开矩阵内的两套 `@react-native-oh-tpl/*` adapter 依赖以 Git URL + exact commit 形式接入，仓库开发和官方 UI-stack sample 推荐使用 `pnpm install --ignore-scripts`，避免 Git adapter 在 prepare 阶段拉取私有资源而中断安装。
@@ -48,7 +48,7 @@
 <!-- GENERATED:readme-current-status:start -->
 | 项目 | 说明 |
 | --- | --- |
-| 当前版本 | `v1.9.0` |
+| 当前版本 | `v1.9.1` |
 | 支持模型 | `verified + preview + experimental` |
 | 唯一 `verified` 公开矩阵 | `expo55-rnoh082-ui-stack` |
 | 输入范围 | Managed/CNG Expo 项目；bare workflow intake baseline |

package/build/cli.js

@@ -40,6 +40,7 @@ async function run(argv = process.argv) {
         .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')
+        .option('--no-har-normalize', 'let ohpm consume file:*.har dependencies without extracting local HARs')
         .action(buildHap_1.runBuildHapCommand);
     program
         .command('init')

package/build/commands/buildHap.d.ts

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

package/build/commands/buildHap.js

@@ -17,6 +17,7 @@ async function runBuildHapCommand(options) {
     }
     const report = await (0, build_1.buildHapProject)(projectRoot, {
         mode,
+        skipHarNormalize: options.harNormalize === false,
     });
     await (0, metadata_1.writeBuildReport)(projectRoot, report);
     if (report.status === 'failed') {

package/build/core/build.d.ts

@@ -2,6 +2,7 @@ import type { BuildReport } from '../types';
 import type { CommandRunner } from './build/commands';
 export type { CommandRunner, CommandRunnerResult } from './build/commands';
 export { renderBuildReport } from './build/reporting';
+export declare const SKIP_HAR_NORMALIZE_WARNING = "Local HAR normalization is disabled; ohpm will consume file:*.har dependencies directly and normalized build-profile/RNOH compatibility steps will be skipped.";
 interface BundleProjectOptions {
     env?: NodeJS.ProcessEnv;
     runner?: CommandRunner;
@@ -11,6 +12,7 @@ interface BuildHapProjectOptions {
     mode: 'debug' | 'release';
     env?: NodeJS.ProcessEnv;
     runner?: CommandRunner;
+    skipHarNormalize?: boolean;
 }
 export declare function bundleProject(projectRoot: string, options?: BundleProjectOptions): Promise<BuildReport>;
 export declare function buildHapProject(projectRoot: string, options: BuildHapProjectOptions): Promise<BuildReport>;

package/build/core/build.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderBuildReport = void 0;
+exports.SKIP_HAR_NORMALIZE_WARNING = exports.renderBuildReport = void 0;
 exports.bundleProject = bundleProject;
 exports.buildHapProject = buildHapProject;
 exports.getDesiredHarmonyScripts = getDesiredHarmonyScripts;
@@ -20,6 +20,7 @@ const reporting_1 = require("./build/reporting");
 const rnohCompatibility_1 = require("./build/rnohCompatibility");
 var reporting_2 = require("./build/reporting");
 Object.defineProperty(exports, "renderBuildReport", { enumerable: true, get: function () { return reporting_2.renderBuildReport; } });
+exports.SKIP_HAR_NORMALIZE_WARNING = 'Local HAR normalization is disabled; ohpm will consume file:*.har dependencies directly and normalized build-profile/RNOH compatibility steps will be skipped.';
 async function bundleProject(projectRoot, options = {}) {
     const runtimeEnv = options.env ?? process.env;
     const runCommand = options.runner ?? commands_1.defaultCommandRunner;
@@ -193,6 +194,7 @@ async function bundleProject(projectRoot, options = {}) {
 async function buildHapProject(projectRoot, options) {
     const runtimeEnv = options.env ?? process.env;
     const runCommand = options.runner ?? commands_1.defaultCommandRunner;
+    const skipHarNormalize = options.skipHarNormalize === true || runtimeEnv.EXPO_HARMONY_SKIP_HAR_NORMALIZE === '1';
     const loadedProject = await (0, project_1.loadProject)(projectRoot);
     const envReport = await (0, env_1.buildEnvReport)(loadedProject.projectRoot, {
         env: runtimeEnv,
@@ -202,6 +204,9 @@ async function buildHapProject(projectRoot, options) {
         ...envReport.warnings.filter((warning) => !warning.startsWith('Harmony sidecar files are not present yet.')),
         ...relevantEnvAdvisories.map((issue) => `${issue.code}: ${issue.message}`),
     ];
+    if (skipHarNormalize) {
+        warnings.push(exports.SKIP_HAR_NORMALIZE_WARNING);
+    }
     const blockingIssues = [];
     if (!envReport.hvigorPath) {
         blockingIssues.push({
@@ -286,39 +291,41 @@ async function buildHapProject(projectRoot, options) {
     let restoreNormalizedRnohCliAutolinkingTemplates = async () => { };
     let restoreNormalizedRnohCodegenAlignment = async () => { };
     let restoreNormalizedHarmonyPackageJsons = async () => { };
-    try {
-        const normalizedLocalHarDependencies = await (0, localHar_1.normalizeLocalHarDependencies)(harmonyProjectRoot);
-        normalizedLocalHarPackages = normalizedLocalHarDependencies.packages;
-        restoreNormalizedDependencies = normalizedLocalHarDependencies.restore;
-        restoreNormalizedLocalHarModules = await (0, localHar_1.ensureHarmonyBuildProfileSupportsNormalizedLocalDeps)(harmonyProjectRoot, normalizedLocalHarDependencies.packages);
-        restoreNormalizedRnohCliAutolinkingTemplates =
-            await (0, rnohCompatibility_1.normalizeProjectRnohCliAutolinkingTemplates)(loadedProject.projectRoot);
-        restoreNormalizedHarmonyPackageJsons =
-            await (0, autolinking_1.normalizeKnownHarmonyPackageJsons)(loadedProject.projectRoot);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return (0, reporting_1.createBuildReport)({
-            projectRoot: loadedProject.projectRoot,
-            command: 'build-hap',
-            mode: options.mode,
-            status: 'failed',
-            harmonyProjectRoot,
-            entryFile: bundleReport.entryFile,
-            bundleOutputPath: bundleReport.bundleOutputPath,
-            assetsDestPath: bundleReport.assetsDestPath,
-            artifactPaths: [],
-            blockingIssues: [
-                {
-                    code: 'build.hap.failed',
-                    message,
-                },
-            ],
-            warnings: [...warnings, ...bundleReport.warnings],
-            steps,
-        });
+    if (!skipHarNormalize) {
+        try {
+            const normalizedLocalHarDependencies = await (0, localHar_1.normalizeLocalHarDependencies)(harmonyProjectRoot);
+            normalizedLocalHarPackages = normalizedLocalHarDependencies.packages;
+            restoreNormalizedDependencies = normalizedLocalHarDependencies.restore;
+            restoreNormalizedLocalHarModules = await (0, localHar_1.ensureHarmonyBuildProfileSupportsNormalizedLocalDeps)(harmonyProjectRoot, normalizedLocalHarDependencies.packages);
+            restoreNormalizedRnohCliAutolinkingTemplates =
+                await (0, rnohCompatibility_1.normalizeProjectRnohCliAutolinkingTemplates)(loadedProject.projectRoot);
+            restoreNormalizedHarmonyPackageJsons =
+                await (0, autolinking_1.normalizeKnownHarmonyPackageJsons)(loadedProject.projectRoot);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return (0, reporting_1.createBuildReport)({
+                projectRoot: loadedProject.projectRoot,
+                command: 'build-hap',
+                mode: options.mode,
+                status: 'failed',
+                harmonyProjectRoot,
+                entryFile: bundleReport.entryFile,
+                bundleOutputPath: bundleReport.bundleOutputPath,
+                assetsDestPath: bundleReport.assetsDestPath,
+                artifactPaths: [],
+                blockingIssues: [
+                    {
+                        code: 'build.hap.failed',
+                        message,
+                    },
+                ],
+                warnings: [...warnings, ...bundleReport.warnings],
+                steps,
+            });
+        }
+        restoreNormalizedRnohCodegenAlignment = await (0, localHar_1.alignRnohCodegenWithNormalizedLocalPackage)(harmonyProjectRoot, normalizedLocalHarPackages);
     }
-    restoreNormalizedRnohCodegenAlignment = await (0, localHar_1.alignRnohCodegenWithNormalizedLocalPackage)(harmonyProjectRoot, normalizedLocalHarPackages);
     const ohpmCommand = (0, commands_1.buildInvocation)(envReport.ohpmPath, ['install', '--all']);
     try {
         const ohpmResult = await runCommand(ohpmCommand.file, ohpmCommand.args, {
@@ -349,10 +356,12 @@ async function buildHapProject(projectRoot, options) {
                 steps,
             });
         }
-        if (!normalizedLocalHarPackages.some((localPackage) => localPackage.packageName === '@rnoh/react-native-openharmony')) {
-            await (0, localHar_1.ensureRnohGeneratedTsShim)(harmonyProjectRoot);
+        if (!skipHarNormalize) {
+            if (!normalizedLocalHarPackages.some((localPackage) => localPackage.packageName === '@rnoh/react-native-openharmony')) {
+                await (0, localHar_1.ensureRnohGeneratedTsShim)(harmonyProjectRoot);
+            }
+            await (0, localHar_1.patchRnohGeneratedCodegenForNormalizedLocalPackage)(harmonyProjectRoot);
         }
-        await (0, localHar_1.patchRnohGeneratedCodegenForNormalizedLocalPackage)(harmonyProjectRoot);
         await (0, localHar_1.patchKnownHarmonyAdapterCodegenOutputs)(harmonyProjectRoot);
         const hvigorCommand = (0, commands_1.buildInvocation)(envReport.hvigorPath, [
             'assembleHap',

package/build/core/constants.d.ts

@@ -1,6 +1,6 @@
 export declare const TOOLKIT_PACKAGE_NAME = "expo-harmony-toolkit";
 export declare const CLI_NAME = "expo-harmony";
-export declare const TOOLKIT_VERSION = "1.9.0";
+export declare const TOOLKIT_VERSION = "1.9.1";
 export declare const TEMPLATE_VERSION = "rnoh-0.82.29";
 export declare const RNOH_VERSION = "0.82.29";
 export declare const RNOH_CLI_VERSION = "0.82.29";

package/build/core/constants.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DESIRED_PACKAGE_SCRIPTS = exports.HARMONY_RUNTIME_PRELUDE_RELATIVE_PATH = exports.HARMONY_ROUTER_ENTRY_FILENAME = exports.STRICT_ENV_EXIT_CODE = exports.STRICT_DOCTOR_EXIT_CODE = exports.DEFAULT_HVIGOR_PLUGIN_FILENAME = exports.PREBUILD_METADATA_FILENAME = exports.TOOLKIT_CONFIG_FILENAME = exports.BUILD_REPORT_FILENAME = exports.ENV_REPORT_FILENAME = exports.DOCTOR_REPORT_FILENAME = exports.MANIFEST_FILENAME = exports.SIGNING_LOCAL_EXAMPLE_FILENAME = exports.SIGNING_LOCAL_FILENAME = exports.GENERATED_SHIMS_DIR = exports.GENERATED_DIR = exports.SUPPORTED_EXPO_SDKS = exports.RNOH_CLI_VERSION = exports.RNOH_VERSION = exports.TEMPLATE_VERSION = exports.TOOLKIT_VERSION = exports.CLI_NAME = exports.TOOLKIT_PACKAGE_NAME = void 0;
 exports.TOOLKIT_PACKAGE_NAME = 'expo-harmony-toolkit';
 exports.CLI_NAME = 'expo-harmony';
-exports.TOOLKIT_VERSION = '1.9.0';
+exports.TOOLKIT_VERSION = '1.9.1';
 exports.TEMPLATE_VERSION = 'rnoh-0.82.29';
 exports.RNOH_VERSION = '0.82.29';
 exports.RNOH_CLI_VERSION = '0.82.29';

package/build/data/publicDocs.d.ts

@@ -8,4 +8,4 @@ export declare const SUPPORTING_SAMPLE_PATHS: readonly ["examples/official-app-s
 export declare const VERIFIED_JS_UI_CAPABILITY_NAMES: readonly ["expo-router", "expo-linking", "expo-constants", ...("react-native-reanimated" | "react-native-svg")[]];
 export declare const PREVIEW_CAPABILITY_DEFINITIONS: import("..").CapabilityDefinition[];
 export declare const EXPERIMENTAL_CAPABILITY_NAMES: readonly string[];
-export declare const PUBLIC_CURRENT_VERSION = "1.9.0";
+export declare const PUBLIC_CURRENT_VERSION = "1.9.1";

package/docs/cli-build.md

@@ -1,6 +1,6 @@
 # CLI 构建指南
 
-`v1.9.0` 延续 `verified + preview + experimental` 支持分层，把 bare workflow 放进 intake baseline，并把五个 app foundation modules 纳入 preview shim baseline；`expo55-rnoh082-ui-stack` 仍是唯一 verified 矩阵。
+`v1.9.1` 延续 `verified + preview + experimental` 支持分层，把 bare workflow 放进 intake baseline，并补上 `build-hap` 的本地 HAR normalize opt-out；`expo55-rnoh082-ui-stack` 仍是唯一 verified 矩阵。
 
 CLI 命令集合不变：
 
@@ -105,6 +105,27 @@ expo-harmony env --strict
 expo-harmony build-hap --mode debug
 ```
 
+### HAR normalize opt-out
+
+默认情况下，`build-hap` 会把 root / entry `oh-package.json5` 里的 `file:*.har` 本地依赖解压到 `harmony/expo-harmony-local-deps`，再让 `ohpm` 消费解压后的目录。这条路径仍是默认 verified build path。
+
+如果项目已经确认当前 DevEco / ohpm 能直接消费纯 HAR，可以显式跳过这一步：
+
+```bash
+EXPO_HARMONY_SKIP_HAR_NORMALIZE=1 expo-harmony build-hap --mode debug
+expo-harmony build-hap --mode debug --no-har-normalize
+```
+
+开启后：
+
+- `file:../node_modules/.../*.har` specifier 会保持原样
+- 不生成 `expo-harmony-local-deps`
+- 不临时注册 normalized local HAR modules 到 `build-profile.json5`
+- 不执行依赖 normalized local RNOH 目录的 codegen / path 兜底
+- `ohpm install --all` 与 `hvigor assembleHap` 继续执行
+
+该开关是 escape hatch，不代表 opt-out 路径和默认路径具备完全相同的兼容兜底。
+
 ### Release
 
 ```bash

package/docs/roadmap.md

@@ -66,7 +66,7 @@
 
 ## 当前主线
 
-`v1.8.x` 已完成 repo 内可收口项，当前主线切到 `v1.9.x`。`v1.9.0` 先落 bare workflow baseline、app foundation modules 与 `react-native-gesture-handler` formal slice；剩余需要真机或 release HAP 的证据继续保留在 v1.8.x capability board，不阻塞 v1.9.x 的 bare / foundation / third-party onboarding 工作。
+`v1.8.x` 已完成 repo 内可收口项，当前主线切到 `v1.9.x`。`v1.9.0` 先落 bare workflow baseline、app foundation modules 与 `react-native-gesture-handler` formal slice；`v1.9.1` 作为 build-hap patch release，补上 HAR normalize opt-out，让已确认 ohpm 可直接消费纯 HAR 的项目可以绕过 `expo-harmony-local-deps`。剩余需要真机或 release HAP 的证据继续保留在 v1.8.x capability board，不阻塞 v1.9.x 的 bare / foundation / third-party onboarding 工作。
 
 ### v1.8.0 Intake Hardening + Parallel Promotion
 
@@ -153,7 +153,28 @@
   - acceptance 记录
 - 本阶段不改变 `verified` 边界；foundation modules 以 `preview` + `runtimeMode=shim` 记录，`react-native-gesture-handler` 以 `experimental` + formal adapter slice 记录
 
-### v1.9.1 Third-party Native Wave A
+### v1.9.1 Build HAP HAR Normalize Opt-out
+
+目标日期：`2026-06-02`
+
+目标：把 issue #1 中的本地 HAR 解压 opt-out 做成正式 patch release，同时不改变默认 verified build path。
+
+- `build-hap` 新增显式 opt-out：
+  - `EXPO_HARMONY_SKIP_HAR_NORMALIZE=1`
+  - `expo-harmony build-hap --no-har-normalize`
+- 默认继续执行现有 `normalizeLocalHarDependencies` 路径：
+  - 解压 `file:*.har` 到 `expo-harmony-local-deps`
+  - 临时改写 root / entry `oh-package.json5`
+  - 注册 normalized local HAR modules
+  - 执行依赖 normalized local package 的 RNOH codegen / path 兜底
+- opt-out 开启后：
+  - 保留 `file:../node_modules/.../*.har`
+  - 让 `ohpm install --all` 直接消费纯 HAR
+  - 在 build report / CLI 文档里明确提示跳过的自动兜底
+- 本阶段只改变 build-hap escape hatch，不扩大 `verified` 能力边界
+- `v1.9.0` 已经存在于 npm `next`，本阶段发布为 `v1.9.1` 并进入 `latest`
+
+### v1.9.2 Third-party Native Wave A
 
 目标日期：`2026-09-30`
 
@@ -172,7 +193,7 @@
   - debug + release evidence
 - 任何进入 Wave A 的 blocker，都不允许继续停留在“矩阵外模糊探索”
 
-### v1.9.2 Third-party Native Wave B + Regression Farm
+### v1.9.3 Third-party Native Wave B + Regression Farm
 
 目标日期：`2026-10-31`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-harmony-toolkit",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "面向 Managed/CNG Expo 项目的 HarmonyOS 迁移、准入检查与 UI-stack 构建工具链",
   "main": "app.plugin.js",
   "types": "build/index.d.ts",