@expo-harmony/prebuild-config 55.0.0-harmony.1

package/README.md

@@ -0,0 +1,68 @@
+# @expo-harmony/prebuild-config
+
+[**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/prebuild-config)
+
+为 Expo 项目提供 HarmonyOS 默认预构建配置，将 `expo.harmony` 转换为可重复生成的原生工程状态。它基于 `@expo-harmony/template` 配置 AppScope、Entry 模块、资源、Hvigor、CMake 和 RNOH 宿主代码，同时完成 Expo 原生模块自动链接并生成 CNG 清单。
+
+## 安装
+
+```sh
+npm install @expo-harmony/prebuild-config
+```
+
+## 基础用法
+
+在 `app.json` 中启用插件并声明 HarmonyOS 配置：
+
+```json
+{
+  "expo": {
+    "name": "Example",
+    "slug": "example",
+    "version": "1.0.0",
+    "plugins": ["@expo-harmony/prebuild-config"],
+    "harmony": {
+      "bundleName": "com.example.app",
+      "versionCode": 1,
+      "deviceTypes": ["phone", "tablet"]
+    }
+  }
+}
+```
+
+使用 Expo Harmony CLI 生成或更新原生工程：
+
+```sh
+npx expo-harmony prebuild
+```
+
+需要使用字体、启动屏或其他 HarmonyOS 配置插件时，应将这些插件放在 `@expo-harmony/prebuild-config` 之前，由本包最后注册 Harmony Base Mods：
+
+```json
+{
+  "expo": {
+    "plugins": [
+      "@expo-harmony/expo-font",
+      [
+        "@expo-harmony/expo-splash-screen",
+        {
+          "image": "./assets/splash.png",
+          "backgroundColor": "#FFFFFF"
+        }
+      ],
+      "@expo-harmony/expo-system-ui",
+      "@expo-harmony/prebuild-config"
+    ],
+    "harmony": {
+      "bundleName": "com.example.app"
+    }
+  }
+}
+```
+
+## 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/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withHarmonyPrebuildConfig = exports.validateHarmonySigningConfigFile = exports.isRnohAutolinkingDisabled = exports.validateCngManifest = exports.createCngManifest = exports.CngManifestPath = exports.HarmonyPrebuildError = exports.validateHarmonyBuildDescriptor = exports.resolveHarmonyBuildPath = exports.harmonyModuleSourcePath = exports.createHarmonyBuildDescriptor = exports.HarmonyTemplateMarker = exports.HarmonyPlatformDirectory = exports.BuildModes = exports.BuildDescriptorSchemaVersion = exports.default = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return plugin_1.HarmonyPrebuildPlugin; } });
+var buildDescriptor_1 = require("./buildDescriptor");
+Object.defineProperty(exports, "BuildDescriptorSchemaVersion", { enumerable: true, get: function () { return buildDescriptor_1.BuildDescriptorSchemaVersion; } });
+Object.defineProperty(exports, "BuildModes", { enumerable: true, get: function () { return buildDescriptor_1.BuildModes; } });
+Object.defineProperty(exports, "HarmonyPlatformDirectory", { enumerable: true, get: function () { return buildDescriptor_1.HarmonyPlatformDirectory; } });
+Object.defineProperty(exports, "HarmonyTemplateMarker", { enumerable: true, get: function () { return buildDescriptor_1.HarmonyTemplateMarker; } });
+Object.defineProperty(exports, "createHarmonyBuildDescriptor", { enumerable: true, get: function () { return buildDescriptor_1.createHarmonyBuildDescriptor; } });
+Object.defineProperty(exports, "harmonyModuleSourcePath", { enumerable: true, get: function () { return buildDescriptor_1.harmonyModuleSourcePath; } });
+Object.defineProperty(exports, "resolveHarmonyBuildPath", { enumerable: true, get: function () { return buildDescriptor_1.resolveHarmonyBuildPath; } });
+Object.defineProperty(exports, "validateHarmonyBuildDescriptor", { enumerable: true, get: function () { return buildDescriptor_1.validateHarmonyBuildDescriptor; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "HarmonyPrebuildError", { enumerable: true, get: function () { return errors_1.HarmonyPrebuildError; } });
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "CngManifestPath", { enumerable: true, get: function () { return manifest_1.CngManifestPath; } });
+Object.defineProperty(exports, "createCngManifest", { enumerable: true, get: function () { return manifest_1.createCngManifest; } });
+Object.defineProperty(exports, "validateCngManifest", { enumerable: true, get: function () { return manifest_1.validateCngManifest; } });
+var native_1 = require("./native");
+Object.defineProperty(exports, "isRnohAutolinkingDisabled", { enumerable: true, get: function () { return native_1.isRnohAutolinkingDisabled; } });
+var signing_1 = require("./signing");
+Object.defineProperty(exports, "validateHarmonySigningConfigFile", { enumerable: true, get: function () { return signing_1.validateHarmonySigningConfigFile; } });
+var withHarmonyPrebuildConfig_1 = require("./withHarmonyPrebuildConfig");
+Object.defineProperty(exports, "withHarmonyPrebuildConfig", { enumerable: true, get: function () { return withHarmonyPrebuildConfig_1.withHarmonyPrebuildConfig; } });

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@expo-harmony/prebuild-config",
+  "version": "55.0.0-harmony.1",
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-harmony",
+    "harmonyos"
+  ],
+  "homepage": "https://github.com/renbaoshuo/expo-harmony/tree/master/packages/prebuild-config#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/prebuild-config"
+  },
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "prebuild": "yarn workspace @expo-harmony/config-plugins build && yarn workspace @expo-harmony/expo-modules-autolinking 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"
+    },
+    "./check": {
+      "types": "./build/check.d.ts",
+      "require": "./build/check.js",
+      "default": "./build/check.js"
+    },
+    "./build-descriptor": {
+      "types": "./build/buildDescriptor.d.ts",
+      "require": "./build/buildDescriptor.js",
+      "default": "./build/buildDescriptor.js"
+    },
+    "./native-project": {
+      "types": "./build/native.d.ts",
+      "require": "./build/native.js",
+      "default": "./build/native.js"
+    },
+    "./signing": {
+      "types": "./build/api/signing.d.ts",
+      "require": "./build/api/signing.js",
+      "default": "./build/api/signing.js"
+    },
+    "./template": {
+      "types": "./build/template.d.ts",
+      "require": "./build/template.js",
+      "default": "./build/template.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@expo-harmony/config-plugins": "55.0.10-harmony.1",
+    "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.1",
+    "@expo-harmony/template": "55.0.0-harmony.0",
+    "@expo/config": "55.0.17",
+    "@expo/config-plugins": "55.0.10",
+    "@react-native-community/cli-config": "15.1.3",
+    "json5": "2.2.3"
+  },
+  "peerDependencies": {
+    "expo": "55.0.26"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "18.19.0",
+    "typescript": "6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api/signing.ts

@@ -0,0 +1,4 @@
+export {
+  validateHarmonySigningConfigFile,
+  type HarmonySigningConfig,
+} from '../signing';

package/src/buildDescriptor.ts

@@ -0,0 +1,277 @@
+import path from 'node:path';
+
+import { HarmonyPaths, type NormalizedHarmonyConfig } from '@expo-harmony/config-plugins';
+
+const BuildDescriptorSchemaVersion = 2;
+const BuildModes = Object.freeze(['debug', 'release'] as const);
+const HarmonyPlatformDirectory = 'harmony';
+const HarmonyTemplateMarker = '.expo-harmony-template';
+
+type HarmonyBuildMode = typeof BuildModes[number];
+
+interface HarmonyBuildVariantDescriptor {
+  expectedHap: string;
+  hvigorArgs: string[];
+}
+
+interface HarmonyBuildDescriptor {
+  export: {
+    bundle: string;
+    manifest: string;
+    metadataRoot: string;
+    rawfileRoot: string;
+    sourceMap: string;
+  };
+  harmonyRoot: string;
+  identity: {
+    abilityName: string;
+    bundleName: string;
+    moduleName: string;
+    productName: string;
+    targetName: string;
+  };
+  moduleRoot: string;
+  nativeCache: {
+    invalidationRoots: string[];
+    stateFile: string;
+  };
+  nativeInputs: {
+    lockfile: string;
+    manifest: string;
+  };
+  projectFiles: {
+    hvigorConfig: string;
+    moduleHvigor: string;
+    moduleJson: string;
+    nativeInputsStamp: string;
+    projectBuildProfile: string;
+    rootHvigor: string;
+    templateMarker: string;
+  };
+  schemaVersion: typeof BuildDescriptorSchemaVersion;
+  variants: Record<HarmonyBuildMode, HarmonyBuildVariantDescriptor>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isSafeRelativePath(value: unknown): value is string {
+  if (!isNonEmptyString(value)
+    || value.includes('\\')
+    || path.posix.isAbsolute(value)
+    || path.win32.isAbsolute(value)
+    || path.posix.normalize(value) !== value) {
+    return false;
+  }
+
+  const segments = value.split('/');
+  return segments.every(segment => segment && segment !== '.' && segment !== '..');
+}
+
+function isStrictDescendant(root: string, target: string): boolean {
+  const relative = path.posix.relative(root, target);
+  return Boolean(relative)
+    && relative !== '..'
+    && !relative.startsWith('../')
+    && !path.posix.isAbsolute(relative);
+}
+
+function validateVariant(value: unknown): HarmonyBuildVariantDescriptor {
+  if (!isRecord(value)
+    || !isSafeRelativePath(value.expectedHap)
+    || !Array.isArray(value.hvigorArgs)
+    || value.hvigorArgs.length === 0
+    || value.hvigorArgs.some(argument => !isNonEmptyString(argument) || /\0|[\r\n]/u.test(argument))) {
+    throw new TypeError('Harmony build descriptor contains an invalid build variant.');
+  }
+
+  return value as unknown as HarmonyBuildVariantDescriptor;
+}
+
+function validateHarmonyBuildDescriptor(value: unknown): HarmonyBuildDescriptor {
+  if (!isRecord(value) || value.schemaVersion !== BuildDescriptorSchemaVersion) {
+    throw new TypeError(
+      `Unsupported Harmony build descriptor schema: ${isRecord(value) ? value.schemaVersion : 'invalid'}.`
+    );
+  }
+
+  if (value.harmonyRoot !== HarmonyPlatformDirectory
+    || !isSafeRelativePath(value.moduleRoot)
+    || !isStrictDescendant(value.harmonyRoot, value.moduleRoot)) {
+    throw new TypeError('Harmony build descriptor contains invalid project roots.');
+  }
+
+  const harmonyRoot = value.harmonyRoot;
+  const moduleRoot = value.moduleRoot;
+
+  const identity = value.identity;
+
+  if (!isRecord(identity)
+    || ['abilityName', 'bundleName', 'moduleName', 'productName', 'targetName']
+      .some(field => !isNonEmptyString(identity[field]))) {
+    throw new TypeError('Harmony build descriptor contains an invalid identity.');
+  }
+
+  const inputs = value.nativeInputs;
+
+  if (!isRecord(inputs)
+    || !isSafeRelativePath(inputs.manifest)
+    || !isSafeRelativePath(inputs.lockfile)
+    || !isStrictDescendant(harmonyRoot, inputs.manifest)
+    || !isStrictDescendant(harmonyRoot, inputs.lockfile)) {
+    throw new TypeError('Harmony build descriptor contains invalid native input paths.');
+  }
+
+  const cache = value.nativeCache;
+
+  if (!isRecord(cache)
+    || !isSafeRelativePath(cache.stateFile)
+    || !isStrictDescendant(moduleRoot, cache.stateFile)
+    || !Array.isArray(cache.invalidationRoots)
+    || cache.invalidationRoots.length === 0
+    || cache.invalidationRoots.some(item => (
+      !isSafeRelativePath(item) || !isStrictDescendant(moduleRoot, item)
+    ))) {
+    throw new TypeError('Harmony build descriptor contains invalid native cache paths.');
+  }
+
+  const files = value.projectFiles;
+  const roots = [
+    'hvigorConfig',
+    'nativeInputsStamp',
+    'projectBuildProfile',
+    'rootHvigor',
+    'templateMarker',
+  ];
+  const modules = ['moduleHvigor', 'moduleJson'];
+
+  if (!isRecord(files)
+    || [...roots, ...modules].some(field => !isSafeRelativePath(files[field]))
+    || roots.some(field => !isStrictDescendant(harmonyRoot, files[field] as string))
+    || modules.some(field => !isStrictDescendant(moduleRoot, files[field] as string))) {
+    throw new TypeError('Harmony build descriptor contains invalid project file paths.');
+  }
+
+  const output = value.export;
+
+  if (!isRecord(output)) {
+    throw new TypeError('Harmony build descriptor contains invalid export paths.');
+  }
+
+  const invalid = ['bundle', 'manifest', 'metadataRoot', 'rawfileRoot', 'sourceMap']
+    .some(field => !isSafeRelativePath(output[field]));
+
+  if (invalid
+    || !isStrictDescendant(moduleRoot, output.rawfileRoot as string)
+    || !isStrictDescendant(output.rawfileRoot as string, output.bundle as string)
+    || !isStrictDescendant(output.metadataRoot as string, output.sourceMap as string)) {
+    throw new TypeError('Harmony build descriptor contains invalid export paths.');
+  }
+
+  if (!isRecord(value.variants)
+    || Object.keys(value.variants).length !== BuildModes.length
+    || BuildModes.some(mode => !Object.hasOwn(value.variants as object, mode))) {
+    throw new TypeError('Harmony build descriptor must define debug and release variants.');
+  }
+
+  for (const mode of BuildModes) {
+    const variant = validateVariant(value.variants[mode]);
+
+    if (!isStrictDescendant(moduleRoot, variant.expectedHap)) {
+      throw new TypeError(`Harmony ${mode} HAP output must be inside the module root.`);
+    }
+  }
+
+  return value as unknown as HarmonyBuildDescriptor;
+}
+
+function createHarmonyBuildDescriptor(
+  config: NormalizedHarmonyConfig,
+  signing: string | null
+): HarmonyBuildDescriptor {
+  const paths = HarmonyPaths.HARMONY_PATHS;
+  const harmony = HarmonyPlatformDirectory;
+  const module = `${harmony}/${path.posix.dirname(paths.entryBuildProfile)}`;
+  const target = 'default';
+  const rawfile = `${module}/src/main/resources/rawfile`;
+  const suffix = signing ? 'signed' : 'unsigned';
+
+  const variants = Object.fromEntries(BuildModes.map(mode => [mode, {
+    expectedHap: `${module}/build/${target}/outputs/${target}/${config.moduleName}-${target}-${suffix}.hap`,
+    hvigorArgs: [
+      '--mode', 'module',
+      '-p', `module=${config.moduleName}@${target}`,
+      '-p', `product=${config.productName}`,
+      '-p', `buildMode=${mode}`,
+      '--no-daemon',
+      'assembleHap',
+    ],
+  }])) as Record<HarmonyBuildMode, HarmonyBuildVariantDescriptor>;
+
+  return validateHarmonyBuildDescriptor({
+    export: {
+      bundle: `${rawfile}/hermes_bundle.hbc`,
+      manifest: '.expo/harmony/export-manifest.json',
+      metadataRoot: '.expo/harmony/export',
+      rawfileRoot: rawfile,
+      sourceMap: '.expo/harmony/export/hermes_bundle.hbc.map',
+    },
+    harmonyRoot: harmony,
+    identity: {
+      abilityName: config.abilityName,
+      bundleName: config.bundleName,
+      moduleName: config.moduleName,
+      productName: config.productName,
+      targetName: target,
+    },
+    moduleRoot: module,
+    nativeCache: {
+      invalidationRoots: [`${module}/.cxx`, `${module}/build`],
+      stateFile: `${module}/.cxx/.expo-harmony-native-dependencies.json`,
+    },
+    nativeInputs: {
+      lockfile: `${harmony}/oh-package-lock.json5`,
+      manifest: `${harmony}/${paths.rootOhPackage}`,
+    },
+    projectFiles: {
+      hvigorConfig: `${harmony}/${paths.hvigorConfig}`,
+      moduleHvigor: `${harmony}/${paths.entryHvigor}`,
+      moduleJson: `${harmony}/${paths.moduleJson}`,
+      nativeInputsStamp: `${harmony}/${paths.nativeInputsStamp}`,
+      projectBuildProfile: `${harmony}/${paths.projectBuildProfile}`,
+      rootHvigor: `${harmony}/${paths.rootHvigor}`,
+      templateMarker: `${harmony}/${HarmonyTemplateMarker}`,
+    },
+    schemaVersion: BuildDescriptorSchemaVersion,
+    variants,
+  });
+}
+
+function harmonyModuleSourcePath(build: HarmonyBuildDescriptor): string {
+  return `./${path.posix.relative(build.harmonyRoot, build.moduleRoot)}`;
+}
+
+function resolveHarmonyBuildPath(root: string, file: string): string {
+  return path.join(root, ...file.split('/'));
+}
+
+export {
+  BuildDescriptorSchemaVersion,
+  BuildModes,
+  HarmonyPlatformDirectory,
+  HarmonyTemplateMarker,
+  createHarmonyBuildDescriptor,
+  harmonyModuleSourcePath,
+  resolveHarmonyBuildPath,
+  validateHarmonyBuildDescriptor,
+};
+export type {
+  HarmonyBuildDescriptor,
+  HarmonyBuildMode,
+  HarmonyBuildVariantDescriptor,
+};