@expo-harmony/expo-module-scripts 55.0.0-harmony.0

package/README.md

@@ -0,0 +1,75 @@
+# @expo-harmony/expo-module-scripts
+
+[**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/expo-module-scripts)
+
+为 Harmony Expo Module 提供 HarmonyOS 平台的构建与打包命令。包内提供独立的 `expo-harmony-module` 命令，负责 OHPM 依赖安装、Hvigor HAR 构建、发布产物清洗和 npm 打包前校验；命令名与官方的 `expo-module` 不同，两者可以在同一个模块包中共存。
+
+## 安装
+
+```sh
+npm install --save-dev @expo-harmony/expo-module-scripts
+```
+
+需要 Node.js 20 或更高版本，以及本机可用的 OHPM 和 Hvigor（安装 DevEco Studio 后通常已经具备）。
+
+## 约定布局
+
+所有命令都按固定约定定位文件，模块包需要具备以下结构：
+
+```
+my-expo-module/
+├── expo-module.config.json    # platforms 须包含 "harmony"，harmony.modules 声明 ArkTS 模块类名
+├── package.json
+└── harmony/
+    ├── build-profile.json5    # 可选，其中的模块名用于定位构建产物
+    ├── library/               # HAR library 模块
+    │   ├── oh-package.json5   # OHPM 清单
+    │   └── build/default/outputs/default/<模块名>.har
+    └── library.har            # 清洗后的发布产物，随 npm 包一起发布
+```
+
+模块名解析优先读取 `harmony/build-profile.json5` 中 `srcPath` 指向 `./library` 的模块名称；若未提供该文件，则默认回退至 `library`。
+
+## 命令
+
+| 命令                                       | 作用                                              |
+| ------------------------------------------ | ------------------------------------------------- |
+| `expo-harmony-module inspect`              | 输出解析后的模块配置和约定路径，不执行构建        |
+| `expo-harmony-module prepare`              | 安装依赖、构建 HAR 并发布到 `harmony/library.har` |
+| `expo-harmony-module prepare --clean-only` | 只执行 Hvigor `clean` 任务                        |
+| `expo-harmony-module prepack`              | 从干净状态重建 HAR，并校验 npm 包内容             |
+
+通用选项：`--root <path>` 指定模块包根目录（默认为当前目录）；`--json` 以 JSON 输出结果；`--dry-run` 只打印将要执行的命令而不实际运行（不能与 `inspect` 同用）。`inspect` 始终输出 JSON。
+
+`prepare` 在 `harmony/` 工程内依次执行 `ohpm install --all` 和 Hvigor `assembleHar`（module 模式、`default` product、release buildMode、`--no-daemon`），然后把 `harmony/library/build/default/outputs/default/<模块名>.har` 清洗后原子替换 `harmony/library.har`。
+
+`prepack` 在构建前额外执行一次 Hvigor `clean` 以保证全量重建，构建完成后运行 `npm pack --dry-run --json --ignore-scripts` 检查将要发布的内容：只允许约定内的文件（源码与各平台目录、文档、`harmony/library.har`、`harmony/library/oh-package.json5` 等），且 `package.json`、`expo-module.config.json`、`main`/`types` 入口和两个 Harmony 产物必须齐全；出现多余或缺失的文件都会报错。
+
+## HAR 清洗
+
+发布产物在写入 `harmony/library.har` 前会重新打包：`oh-package.json5` 的 `dependencies`、`devDependencies` 和 `dynamicDependencies` 不允许使用 `file:`、`link:`、`workspace:` 或本地路径，`oh-package-lock.json5` 会被移除，最终以 portable 格式重新压缩，避免把宿主机路径或本地依赖带进发布产物。
+
+## 工具链
+
+`ohpm` 和 `hvigorw` 可分别通过环境变量 `HARMONY_OHPM` 和 `HARMONY_HVIGORW` 指定路径；当 `HARMONY_HVIGORW` 指向 JS 脚本时，会改用 `HARMONY_NODE`（缺省为当前 Node 可执行文件）来运行。
+
+## 在模块包中使用
+
+```json
+{
+  "scripts": {
+    "harmony:clean": "expo-harmony-module prepare --clean-only",
+    "harmony:build": "expo-harmony-module prepare",
+    "prepack": "expo-harmony-module prepack"
+  }
+}
+```
+
+`prepack` 挂在 npm 的同名生命周期钩子上，`npm pack` 和 `npm publish` 前会自动执行。除 CLI 外，包还导出 `inspectModule`、`prepareModule`、`prepackModule` 等函数供编程调用。
+
+## 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/bin/expo-harmony-module.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/index.mjs';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`expo-harmony-module: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@expo-harmony/expo-module-scripts",
+  "version": "55.0.0-harmony.0",
+  "description": "HarmonyOS port of expo-module-scripts",
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-harmony",
+    "harmonyos"
+  ],
+  "homepage": "https://github.com/renbaoshuo/expo-harmony/tree/master/packages/expo-module-scripts#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/expo-module-scripts"
+  },
+  "type": "module",
+  "main": "./src/index.mjs",
+  "bin": {
+    "expo-harmony-module": "bin/expo-harmony-module.js"
+  },
+  "dependencies": {
+    "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.1",
+    "fast-glob": "^3.3.2",
+    "json5": "2.2.3",
+    "semver": "7.7.3",
+    "tar": "6.2.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/har.mjs

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import JSON5 from 'json5';
+import tar from 'tar';
+
+const localDependency = /^(?:file:|link:|workspace:|\.{1,2}[\\/])|^(?:\/|[A-Za-z]:[\\/])/u;
+const absoluteSourcePath = /(?:\/Users\/[^/]+\/|\/home\/[^/]+\/|[A-Za-z]:\\Users\\)/u;
+
+// Hvigor retains a relative OHPM dependency for a native library's type package.
+// It is portable only when both the declaration package and binary are in this HAR.
+function isBundledNativeTypeDependency(packageRoot, manifest, name, specifier) {
+  if (path.basename(name) !== name || !name.endsWith('.so') || !manifest.nativeComponents?.some(component => component.name === name)) return false;
+  const relative = specifier.replace(/^file:/u, '');
+  if (!relative.startsWith('./')) return false;
+
+  try {
+    const root = fs.realpathSync(packageRoot);
+    const typeRoot = fs.realpathSync(path.resolve(root, relative));
+    const relation = path.relative(root, typeRoot);
+    if (!relation || relation.startsWith(`..${path.sep}`) || relation === '..' || path.isAbsolute(relation)) return false;
+    const types = JSON5.parse(fs.readFileSync(path.join(typeRoot, 'oh-package.json5'), 'utf8'));
+    if (types.name !== name || typeof types.types !== 'string' || !types.types.endsWith('.d.ts')) return false;
+    const declaration = fs.realpathSync(path.resolve(typeRoot, types.types));
+    const declarationRelation = path.relative(typeRoot, declaration);
+    if (declarationRelation.startsWith(`..${path.sep}`) || declarationRelation === '..' || path.isAbsolute(declarationRelation)) return false;
+    if (!fs.statSync(declaration).isFile()) return false;
+    const libs = path.join(root, 'libs');
+    return fs.readdirSync(libs, { withFileTypes: true }).some((architecture) => {
+      const binary = path.join(libs, architecture.name, name);
+      return architecture.isDirectory() && fs.existsSync(binary) && fs.lstatSync(binary).isFile();
+    });
+  } catch {
+    return false;
+  }
+}
+
+export async function sanitizeHarmonyHar(file, { sourceManifest: source, workspaceVersions: versions = {} } = {}) {
+  const temp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'expo-har-'));
+  const output = path.join(temp, 'library.har');
+
+  try {
+    await tar.x({ cwd: temp, file, strict: true });
+
+    const root = path.join(temp, 'package');
+    const target = path.join(root, 'oh-package.json5');
+    const manifest = JSON5.parse(await fs.promises.readFile(target, 'utf8'));
+
+    for (const section of ['dependencies', 'devDependencies', 'dynamicDependencies']) {
+      for (const [name, value] of Object.entries(manifest[section] || {})) {
+        if (typeof value !== 'string' || !localDependency.test(value)) continue;
+        if (isBundledNativeTypeDependency(root, manifest, name, value)) continue;
+
+        // Hvigor can retain an override's local HAR path. Only rewrite known
+        // workspace dependencies, preserving the authored publication range.
+        if (Object.hasOwn(versions, name)) {
+          const version = source?.[section]?.[name] || versions[name];
+          if (typeof version === 'string' && !localDependency.test(version)) {
+            manifest[section][name] = version;
+            continue;
+          }
+        }
+
+        throw new Error(`Cannot publish ${file}: ${section}.${name} must use a package version.`);
+      }
+    }
+
+    await fs.promises.writeFile(target, `${JSON5.stringify(manifest, null, 2)}\n`);
+    await fs.promises.rm(path.join(root, 'oh-package-lock.json5'), { force: true });
+
+    await tar.c({ cwd: temp, file: output, gzip: true, portable: true }, ['package']);
+    await fs.promises.copyFile(output, file);
+  } finally {
+    await fs.promises.rm(temp, { recursive: true, force: true });
+  }
+}
+
+export function assertPortableHarmonyHarSync(harPath) {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'expo-har-check-'));
+  try {
+    tar.x({ cwd: tempRoot, file: harPath, strict: true, sync: true });
+
+    const packageRoot = path.join(tempRoot, 'package');
+    for (const name of ['oh-package.json5', 'oh-package-lock.json5']) {
+      const file = path.join(packageRoot, name);
+      if (!fs.existsSync(file)) continue;
+
+      const content = fs.readFileSync(file, 'utf8');
+      if (absoluteSourcePath.test(content) || content.includes('file:/')) {
+        throw new Error(`${harPath} leaks a local dependency path in package/${name}.`);
+      }
+      if (name === 'oh-package.json5') {
+        const manifest = JSON5.parse(content);
+
+        for (const section of ['dependencies', 'devDependencies', 'dynamicDependencies']) {
+          for (const [dependency, version] of Object.entries(manifest[section] || {})) {
+            if (typeof version === 'string' && localDependency.test(version)) {
+              if (isBundledNativeTypeDependency(packageRoot, manifest, dependency, version)) continue;
+              throw new Error(`${harPath} package/${name} ${section}.${dependency} must use a package version.`);
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}

package/src/index.mjs

@@ -0,0 +1,485 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+
+import { normalizeHarmonyModuleMetadata } from '@expo-harmony/expo-modules-autolinking';
+import JSON5 from 'json5';
+import { sanitizeHarmonyHar } from './har.mjs';
+import { findWorkspacePackages, planWorkspaceBuild, workspaceOverrides, withWorkspaceOverrides } from './workspace.mjs';
+
+const HARMONY_PROJECT = 'harmony';
+const HARMONY_MODULE = 'library';
+const HARMONY_PRODUCT = 'default';
+const BUNDLED_HAR = 'harmony/library.har';
+const OH_PACKAGE_MANIFEST = 'harmony/library/oh-package.json5';
+
+function requiredString(value, field) {
+  if (typeof value !== 'string' || value.length === 0) throw new TypeError(`${field} is required.`);
+  return value;
+}
+
+function normalizeConfig(raw, pkg) {
+  if (!Array.isArray(raw?.platforms) || !raw.platforms.includes('harmony')) {
+    throw new TypeError('expo-module.config.json#platforms must include harmony.');
+  }
+
+  const { modules } = normalizeHarmonyModuleMetadata(raw.harmony, {
+    packageName: requiredString(pkg.name, 'package.json#name'),
+    packageVersion: typeof pkg.version === 'string' ? pkg.version : undefined,
+  });
+
+  if (modules.length === 0) throw new TypeError('harmony.modules must declare at least one ArkTS module.');
+
+  return { modules };
+}
+
+async function readJson(file) {
+  return JSON.parse(await fs.promises.readFile(file, 'utf8'));
+}
+
+function inside(root, relative, field) {
+  const resolved = path.resolve(root, relative);
+  const relation = path.relative(root, resolved);
+
+  if (relation === '..' || relation.startsWith(`..${path.sep}`) || path.isAbsolute(relation)) {
+    throw new TypeError(`${field} escapes the package root.`);
+  }
+
+  return resolved;
+}
+
+async function assertExistingAncestorInside(root, target, field) {
+  let ancestor = target;
+  while (!(await exists(ancestor))) {
+    const parent = path.dirname(ancestor);
+    if (parent === ancestor) throw new TypeError(`${field} has no package-contained parent.`);
+
+    ancestor = parent;
+  }
+
+  const realAncestor = await fs.promises.realpath(ancestor);
+  const relation = path.relative(root, realAncestor);
+
+  if (relation === '..' || relation.startsWith(`..${path.sep}`) || path.isAbsolute(relation)) {
+    throw new TypeError(`${field} resolves outside the package root through a symbolic link.`);
+  }
+}
+
+function harmonyModuleName(packageRoot) {
+  const projectRoot = path.join(packageRoot, HARMONY_PROJECT);
+  const profilePath = path.join(projectRoot, 'build-profile.json5');
+  if (!fs.existsSync(profilePath)) return HARMONY_MODULE;
+
+  const profile = JSON5.parse(fs.readFileSync(profilePath, 'utf8'));
+  const moduleRoot = path.join(projectRoot, HARMONY_MODULE);
+  const module = profile.modules?.find(candidate =>
+    typeof candidate?.srcPath === 'string' && path.resolve(projectRoot, candidate.srcPath) === moduleRoot
+  );
+  const name = requiredString(module?.name, 'harmony/build-profile.json5 module name');
+
+  if (path.basename(name) !== name) throw new TypeError('Harmony module name must not contain a path.');
+
+  return name;
+}
+
+function modulePaths(packageRoot, moduleName = harmonyModuleName(packageRoot)) {
+  const projectRoot = inside(packageRoot, HARMONY_PROJECT, 'Harmony project');
+  return {
+    moduleName,
+    projectRoot,
+    moduleRoot: inside(projectRoot, HARMONY_MODULE, 'Harmony module'),
+    sourceOutput: inside(projectRoot, `library/build/default/outputs/default/${moduleName}.har`, 'Hvigor HAR output'),
+    bundledHar: inside(packageRoot, BUNDLED_HAR, 'Bundled HAR'),
+    ohPackageManifest: inside(packageRoot, OH_PACKAGE_MANIFEST, 'OHPM package manifest'),
+  };
+}
+
+async function loadBuildConfig(root, manifest) {
+  const file = path.join(root, 'expo-module.config.json');
+  if (await exists(file)) {
+    return normalizeConfig(await readJson(file), manifest);
+  }
+
+  // RNOH runtime packages (including expo-modules-core) have no Expo module
+  // registration. Keep their existing HAR filename and metadata contract.
+  const linking = manifest.harmony?.autolinking;
+  if (linking?.mainHarPath === 'harmony' && linking.ohPackageName === manifest.name) return { modules: [] };
+
+  throw new TypeError(`${manifest.name} must declare an Expo Harmony module or a Harmony RNOH package.`);
+}
+
+function projectPaths(root, config) {
+  const paths = modulePaths(root);
+  if (config.modules.length === 0) {
+    paths.bundledHar = inside(root, `harmony/${paths.moduleName}.har`, 'Bundled HAR');
+  }
+  return paths;
+}
+
+export async function loadModuleProject(root = process.cwd()) {
+  const packageRoot = await fs.promises.realpath(path.resolve(root));
+  const pkg = await readJson(path.join(packageRoot, 'package.json'));
+
+  const config = await loadBuildConfig(packageRoot, pkg);
+  const paths = projectPaths(packageRoot, config);
+
+  await assertExistingAncestorInside(packageRoot, paths.projectRoot, 'Harmony project');
+  const projectRoot = await fs.promises.realpath(paths.projectRoot);
+  const modulePath = inside(projectRoot, HARMONY_MODULE, 'Harmony module');
+  await assertExistingAncestorInside(packageRoot, modulePath, 'Harmony module');
+  const moduleRoot = await fs.promises.realpath(modulePath);
+  await assertExistingAncestorInside(packageRoot, paths.sourceOutput, 'Hvigor HAR output');
+  await assertExistingAncestorInside(packageRoot, paths.bundledHar, 'Bundled HAR');
+  await assertNonEmptyRegularFile(paths.ohPackageManifest, 'OHPM package manifest', moduleRoot);
+
+  const library = JSON5.parse(await fs.promises.readFile(paths.ohPackageManifest, 'utf8'));
+  const project = JSON5.parse(await fs.promises.readFile(path.join(projectRoot, 'oh-package.json5'), 'utf8'));
+
+  return {
+    packageRoot,
+    packageJson: pkg,
+    config,
+    projectRoot,
+    moduleRoot,
+    moduleName: paths.moduleName,
+    sourceOutput: paths.sourceOutput,
+    bundledHar: paths.bundledHar,
+    ohPackageManifest: paths.ohPackageManifest,
+    ohPackage: library,
+    ohProjectPackage: project,
+  };
+}
+
+async function exists(file) {
+  try {
+    await fs.promises.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function inspectModule(root = process.cwd()) {
+  const packageRoot = await fs.promises.realpath(path.resolve(root));
+  const pkg = await readJson(path.join(packageRoot, 'package.json'));
+
+  const config = await loadBuildConfig(packageRoot, pkg);
+  const paths = projectPaths(packageRoot, config);
+
+  return {
+    config,
+    paths: {
+      project: path.relative(packageRoot, paths.projectRoot).replace(/\\/g, '/'),
+      module: path.relative(packageRoot, paths.moduleRoot).replace(/\\/g, '/'),
+      output: path.relative(packageRoot, paths.sourceOutput).replace(/\\/g, '/'),
+      bundledHar: path.relative(packageRoot, paths.bundledHar).replace(/\\/g, '/'),
+      ohPackageManifest: path.relative(packageRoot, paths.ohPackageManifest).replace(/\\/g, '/'),
+    },
+  };
+}
+
+async function assertNonEmptyRegularFile(file, label, allowedRoot) {
+  let stat;
+  try {
+    stat = await fs.promises.lstat(file);
+  } catch (cause) {
+    if (cause.code === 'ENOENT') throw new Error(`${label} is missing: ${file}`);
+
+    throw new Error(cause instanceof Error ? cause.message : String(cause), { cause });
+  }
+
+  if (stat.isSymbolicLink()) throw new Error(`${label} must not be a symbolic link: ${file}`);
+  if (!stat.isFile()) throw new Error(`${label} must be a regular file: ${file}`);
+  if (stat.size === 0) throw new Error(`${label} must not be empty: ${file}`);
+
+  if (allowedRoot) {
+    const [realRoot, realFile] = await Promise.all([
+      fs.promises.realpath(allowedRoot),
+      fs.promises.realpath(file),
+    ]);
+    const relation = path.relative(realRoot, realFile);
+
+    if (relation === '..' || relation.startsWith(`..${path.sep}`) || path.isAbsolute(relation)) {
+      throw new Error(`${label} resolves outside its allowed root: ${file}`);
+    }
+  }
+}
+
+export function fixedHvigorArgs(task = 'assembleHar', moduleName = HARMONY_MODULE) {
+  if (task !== 'assembleHar' && task !== 'clean') throw new TypeError(`Unsupported Hvigor task: ${task}`);
+
+  return [
+    '--mode', 'module',
+    '-p', `module=${moduleName}@default`,
+    '-p', `product=${HARMONY_PRODUCT}`,
+    '-p', 'buildMode=release',
+    '--no-daemon',
+    task,
+  ];
+}
+
+export function resolveModuleCommand(command, args, env = process.env) {
+  if (command === 'ohpm' && env.HARMONY_OHPM) {
+    return { command: env.HARMONY_OHPM, args };
+  }
+  if (command === 'hvigorw' && env.HARMONY_HVIGORW) {
+    return /\.(?:c|m)?js$/i.test(env.HARMONY_HVIGORW)
+      ? {
+          command: env.HARMONY_NODE || process.execPath,
+          args: [env.HARMONY_HVIGORW, ...args],
+        }
+      : { command: env.HARMONY_HVIGORW, args };
+  }
+  return { command, args };
+}
+
+function spawnCommand(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const invocation = resolveModuleCommand(command, args, process.env);
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: options.cwd,
+      env: process.env,
+      shell: false,
+      signal: options.signal,
+      stdio: options.capture ? ['ignore', 'pipe', 'inherit'] : 'inherit',
+    });
+    let output = '';
+    let failure;
+
+    child.stdout?.on('data', (chunk) => {
+      output += chunk;
+    });
+    child.on('error', (error) => {
+      failure = error;
+    });
+
+    // Wait for the aborted child to stop before restoring its OHPM inputs.
+    child.on('close', (code) => {
+      if (failure) reject(failure);
+      else if (code === 0) resolve(output);
+      else reject(new Error(`${invocation.command} exited with code ${code}.`));
+    });
+  });
+}
+
+async function publishBuiltHar(project, dependencies = []) {
+  await assertNonEmptyRegularFile(project.sourceOutput, 'Hvigor HAR output', project.projectRoot);
+  await assertExistingAncestorInside(project.packageRoot, project.bundledHar, 'Bundled HAR');
+
+  const versions = Object.fromEntries(dependencies.map(dependency => [
+    dependency.ohPackage.name, dependency.ohPackage.version,
+  ]));
+  const temp = `${project.bundledHar}.${process.pid}.${Date.now()}.tmp`;
+
+  await fs.promises.mkdir(path.dirname(project.bundledHar), { recursive: true });
+
+  try {
+    await fs.promises.copyFile(project.sourceOutput, temp, fs.constants.COPYFILE_EXCL);
+    await sanitizeHarmonyHar(temp, {
+      sourceManifest: project.ohPackage,
+      workspaceVersions: versions,
+    });
+    await fs.promises.rename(temp, project.bundledHar);
+  } finally {
+    await fs.promises.rm(temp, { force: true });
+  }
+
+  await assertNonEmptyRegularFile(project.bundledHar, 'Bundled HAR', project.packageRoot);
+}
+
+async function createWorkspaceBuild(root, options = {}) {
+  root = await fs.promises.realpath(root);
+  const workspace = await findWorkspacePackages(root);
+
+  if (options.all && (!workspace || workspace.root !== root)) {
+    throw new Error('build-workspace must run at a package.json workspace root.');
+  }
+
+  const projects = [];
+  for (const directory of workspace?.packages || [root]) {
+    if (await exists(path.join(directory, OH_PACKAGE_MANIFEST))) {
+      projects.push(await loadModuleProject(directory));
+    }
+  }
+
+  const targets = options.all
+    ? projects.filter(project => !project.packageJson.private)
+    : projects.filter(project => project.packageRoot === root);
+  if (targets.length === 0) throw new Error(`No Harmony module projects found in ${root}.`);
+
+  return planWorkspaceBuild(projects, targets).map(({ project, dependencies }) => {
+    const install = { command: 'ohpm', args: ['install', '--all'], cwd: project.projectRoot };
+    const build = { command: 'hvigorw', args: fixedHvigorArgs('assembleHar', project.moduleName), cwd: project.projectRoot };
+    const clean = options.clean ? { ...build, args: fixedHvigorArgs('clean', project.moduleName) } : undefined;
+    const overrides = workspaceOverrides(project, dependencies);
+
+    return {
+      project,
+      dependencies,
+      plan: { ...build, packageName: project.packageJson.name, install, clean, build, overrides },
+    };
+  });
+}
+
+async function executeWorkspaceBuild(entries) {
+  for (const { project, dependencies, plan } of entries) {
+    process.stdout.write(`[Harmony] Building ${project.packageJson.name}\n`);
+
+    for (const dependency of dependencies) {
+      await assertNonEmptyRegularFile(dependency.bundledHar, 'Workspace dependency HAR', dependency.packageRoot);
+    }
+
+    await withWorkspaceOverrides(project, plan.overrides, async (signal) => {
+      const options = { cwd: project.projectRoot, signal };
+
+      await spawnCommand(plan.install.command, plan.install.args, options);
+      if (plan.clean) await spawnCommand(plan.clean.command, plan.clean.args, options);
+      await spawnCommand(plan.build.command, plan.build.args, options);
+
+      await publishBuiltHar(project, dependencies);
+    });
+  }
+}
+
+export async function buildWorkspace(root = process.cwd(), options = {}) {
+  const entries = await createWorkspaceBuild(root, { all: true });
+  if (!options.dryRun) await executeWorkspaceBuild(entries);
+  return { builds: entries.map(entry => entry.plan) };
+}
+
+export async function prepareModule(root = process.cwd(), options = {}) {
+  if (!options.cleanOnly) {
+    const entries = await createWorkspaceBuild(root);
+
+    if (!options.dryRun) await executeWorkspaceBuild(entries);
+
+    return { ...entries.at(-1).plan, workspaceBuilds: entries.map(entry => entry.plan) };
+  }
+
+  const project = await loadModuleProject(root);
+  const build = { command: 'hvigorw', args: fixedHvigorArgs('clean', project.moduleName), cwd: project.projectRoot };
+  const plan = { ...build, build };
+
+  if (options.dryRun) return plan;
+
+  await spawnCommand(build.command, build.args, { cwd: build.cwd });
+
+  return plan;
+}
+
+function allowedPackedFile(name, runtimeFiles) {
+  return runtimeFiles.has(name)
+    || name === 'package.json'
+    || name === 'expo-module.config.json'
+    || name === 'README.md'
+    || name === 'LICENSE'
+    || name === 'CHANGELOG.md'
+    || name === 'app.plugin.js'
+    || name === 'react-native.config.js'
+    || /^(?:[^/]+\.)?podspec(?:\.json)?$/.test(name)
+    || name.startsWith('build/')
+    || name.startsWith('src/')
+    || name.startsWith('ios/')
+    || name.startsWith('android/')
+    || name.startsWith('web/')
+    || name.startsWith('plugin/')
+    || name === BUNDLED_HAR
+    || name === OH_PACKAGE_MANIFEST;
+}
+
+function packageFile(value, field) {
+  const raw = requiredString(value, field).replace(/\\/g, '/');
+  const normalized = path.posix.normalize(raw).replace(/^\.\//, '');
+
+  if (path.posix.isAbsolute(normalized) || path.win32.isAbsolute(raw)
+    || normalized === '..' || normalized.startsWith('../')) {
+    throw new TypeError(`${field} must stay inside the package root.`);
+  }
+
+  return normalized;
+}
+
+export async function prepackModule(root = process.cwd(), options = {}) {
+  const project = await loadModuleProject(root);
+  const entries = await createWorkspaceBuild(root, { clean: true });
+
+  const plan = {
+    clean: { command: 'hvigorw', args: fixedHvigorArgs('clean', project.moduleName) },
+    install: { command: 'ohpm', args: ['install', '--all'] },
+    build: { command: 'hvigorw', args: fixedHvigorArgs('assembleHar', project.moduleName) },
+    pack: { command: 'npm', args: ['pack', '--dry-run', '--json', '--ignore-scripts'] },
+    workspaceBuilds: entries.map(entry => entry.plan),
+  };
+
+  if (options.dryRun) return plan;
+
+  await executeWorkspaceBuild(entries);
+
+  const output = await spawnCommand(plan.pack.command, plan.pack.args, { cwd: project.packageRoot, capture: true });
+  const result = JSON.parse(output);
+  const files = result[0]?.files?.map(entry => entry.path) ?? [];
+  const runtimeFiles = new Set([
+    packageFile(project.packageJson.main, 'package.json#main'),
+    packageFile(project.packageJson.types, 'package.json#types'),
+  ]);
+  const unexpected = files.filter(file => !allowedPackedFile(file, runtimeFiles));
+
+  if (unexpected.length > 0) throw new Error(`npm pack contains unexpected files: ${unexpected.join(', ')}`);
+
+  const required = [
+    'package.json',
+    'expo-module.config.json',
+    ...runtimeFiles,
+    BUNDLED_HAR,
+    OH_PACKAGE_MANIFEST,
+  ].filter(Boolean);
+  const missing = [...new Set(required)].filter(file => !files.includes(file));
+
+  if (missing.length > 0) throw new Error(`npm pack is missing required runtime files: ${missing.join(', ')}`);
+
+  return { files };
+}
+
+function parseCli(argv) {
+  const command = argv[0];
+  const options = { root: process.cwd(), dryRun: false, json: false, cleanOnly: false };
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--clean-only') options.cleanOnly = true;
+    else if (arg === '--root') options.root = argv[++index];
+    else throw new TypeError(`Unknown option: ${arg}`);
+  }
+
+  return { command, options };
+}
+
+export async function runCli(argv) {
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write('Usage: expo-harmony-module <inspect|prepare|prepack|build-workspace> [--root <path>] [--json] [--dry-run]\n');
+    return;
+  }
+
+  const { command, options } = parseCli(argv);
+
+  if (options.cleanOnly && command !== 'prepare') {
+    throw new TypeError('--clean-only is only valid with prepare.');
+  }
+  if (options.dryRun && command === 'inspect') {
+    throw new TypeError('--dry-run is not valid with inspect.');
+  }
+
+  let result;
+  if (command === 'inspect') result = await inspectModule(options.root);
+  else if (command === 'prepare') result = await prepareModule(options.root, options);
+  else if (command === 'prepack') result = await prepackModule(options.root, options);
+  else if (command === 'build-workspace') result = await buildWorkspace(options.root, options);
+  else throw new TypeError(`Unknown command: ${command}`);
+
+  if (options.json || options.dryRun || command === 'inspect') {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+}

package/src/workspace.mjs

@@ -0,0 +1,172 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+import glob from 'fast-glob';
+import JSON5 from 'json5';
+import semver from 'semver';
+
+const sections = ['dependencies', 'devDependencies', 'dynamicDependencies'];
+
+async function readOptional(file) {
+  try {
+    return await fs.readFile(file);
+  } catch (cause) {
+    if (cause.code === 'ENOENT') return undefined;
+
+    throw new Error(cause instanceof Error ? cause.message : String(cause), { cause });
+  }
+}
+
+export async function findWorkspacePackages(root) {
+  root = await fs.realpath(root);
+
+  for (let directory = root; ; directory = path.dirname(directory)) {
+    const source = await readOptional(path.join(directory, 'package.json'));
+    const manifest = source && JSON.parse(source);
+    const patterns = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages;
+
+    if (Array.isArray(patterns)) {
+      const files = await glob(patterns.map(pattern => `${pattern.replace(/\/$/u, '')}/package.json`), {
+        cwd: directory,
+        absolute: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+        ignore: ['**/node_modules/**'],
+      });
+      const roots = await Promise.all(files.map(file => fs.realpath(path.dirname(file))));
+
+      const packages = [...new Set(roots)].sort();
+      if (directory === root || packages.includes(root)) return { root: directory, packages };
+    }
+
+    if (path.dirname(directory) === directory) return undefined;
+  }
+}
+
+// Native manifests, rather than the JS dependency graph, determine HAR build order.
+export function planWorkspaceBuild(projects, targets) {
+  const registry = new Map();
+  for (const project of projects) {
+    const { name, version } = project.ohPackage;
+
+    if (name !== project.packageJson.name || version !== project.packageJson.version || !semver.valid(version)) {
+      throw new Error(`${project.packageRoot}: npm and OHPM package names and versions must match.`);
+    }
+    if (registry.has(name)) throw new Error(`Duplicate workspace OHPM package: ${name}.`);
+
+    registry.set(name, project);
+  }
+
+  const ordered = new Map();
+  const visiting = [];
+
+  function visit(project) {
+    const name = project.ohPackage.name;
+    if (ordered.has(name)) return ordered.get(name);
+    if (visiting.includes(name)) throw new Error(`Circular Harmony workspace dependency: ${[...visiting, name].join(' -> ')}.`);
+
+    visiting.push(name);
+    const dependencies = new Map();
+    const declarations = [
+      ...sections.flatMap(section => Object.entries(project.ohPackage[section] || {})),
+      ...sections.flatMap(section => Object.entries(project.ohProjectPackage[section] || {})
+        // The project normally includes its own ./library module.
+        .filter(([dependency]) => dependency !== name)),
+      ...Object.entries(project.ohProjectPackage.overrides || {}).filter(([dependency]) => dependency !== name),
+    ];
+
+    for (const [target, range] of declarations) {
+      const dependency = registry.get(target);
+      if (!dependency) continue;
+
+      if (typeof range !== 'string' || !semver.validRange(range) || !semver.satisfies(dependency.ohPackage.version, range)) {
+        throw new Error(`${name} requires ${target}@${range}, but the workspace contains ${dependency.ohPackage.version}. Update the native dependency before building.`);
+      }
+
+      const entry = visit(dependency);
+      for (const transitive of entry.dependencies) dependencies.set(transitive.ohPackage.name, transitive);
+      dependencies.set(target, dependency);
+    }
+
+    visiting.pop();
+    const entry = { project, dependencies: [...dependencies.values()] };
+    ordered.set(name, entry);
+
+    return entry;
+  }
+
+  for (const target of targets) visit(target);
+
+  return [...ordered.values()];
+}
+
+export function workspaceOverrides(project, dependencies) {
+  return Object.fromEntries(dependencies.map(dependency => [
+    dependency.ohPackage.name,
+    `file:${path.relative(project.projectRoot, dependency.bundledHar).replace(/\\/gu, '/')}`,
+  ]));
+}
+
+export async function withWorkspaceOverrides(project, overrides, build) {
+  // Fail instead of letting simultaneous builds overwrite each other's manifests.
+  const lock = path.join(project.projectRoot, '.expo-harmony-build.lock');
+  try {
+    await fs.mkdir(lock);
+  } catch (cause) {
+    if (cause.code === 'EEXIST') throw new Error(`Harmony build already locked: ${lock}. If a previous process was killed, remove this directory after confirming it has stopped.`);
+
+    throw new Error(cause instanceof Error ? cause.message : String(cause), { cause });
+  }
+
+  const snapshots = new Map();
+  const controller = new globalThis.AbortController();
+  const { signal } = controller;
+  const interrupt = () => controller.abort();
+
+  process.once('SIGINT', interrupt);
+  process.once('SIGTERM', interrupt);
+
+  try {
+    if (Object.keys(overrides).length > 0) {
+      const file = path.join(project.projectRoot, 'oh-package.json5');
+      const files = [
+        file,
+        path.join(project.projectRoot, 'oh-package-lock.json5'),
+        path.join(project.moduleRoot, 'oh-package-lock.json5'),
+      ];
+
+      for (const target of files) {
+        snapshots.set(target, await readOptional(target));
+      }
+
+      const manifest = JSON5.parse(snapshots.get(file).toString());
+      manifest.overrides = { ...manifest.overrides, ...overrides };
+
+      await fs.writeFile(file, `${JSON5.stringify(manifest, null, 2)}\n`);
+
+      // Local HARs may change without their version or path changing. Force OHPM
+      // to re-resolve them instead of retaining an older lockfile resolution.
+      for (const target of files.slice(1)) await fs.rm(target, { force: true });
+    }
+
+    if (signal.aborted) throw new globalThis.DOMException('This operation was aborted', 'AbortError');
+
+    const result = await build(signal);
+    if (signal.aborted) throw new globalThis.DOMException('This operation was aborted', 'AbortError');
+
+    return result;
+  } finally {
+    try {
+      for (const [file, source] of snapshots) {
+        if (source === undefined) await fs.rm(file, { force: true });
+        else await fs.writeFile(file, source);
+      }
+    } finally {
+      process.removeListener('SIGINT', interrupt);
+      process.removeListener('SIGTERM', interrupt);
+
+      await fs.rmdir(lock);
+    }
+  }
+}