@expo-harmony/cli 55.0.26-harmony.1

package/src/modules/modules.ts

@@ -0,0 +1,154 @@
+import {
+  resolveModulesAsync,
+  searchModulesAsync,
+  verifyModulesAsync,
+  type BuildType,
+  type Diagnostic,
+  type ModuleDescriptor,
+  type ModuleSource,
+} from '@expo-harmony/expo-modules-autolinking';
+
+import { HarmonyCliError } from '../errors';
+import type { ModulesAction } from './options';
+
+interface ModulesCommandOptions {
+  action: ModulesAction;
+  nativeModulesDir?: string;
+  packageName?: string;
+  variant?: BuildType;
+}
+
+interface ListedModule {
+  packageName: string;
+  packageVersion: string;
+  source: ModuleSource;
+  supportsHarmony: boolean;
+}
+
+interface ModulesListResult {
+  action: 'list';
+  duplicates: ReadonlyArray<{
+    packageName: string;
+    revisions: ReadonlyArray<{ path: string; version: string }>;
+  }>;
+  missingIncludes: ReadonlyArray<string>;
+  modules: ReadonlyArray<ListedModule>;
+  ok: boolean;
+}
+
+interface ModulesInspectResult {
+  action: 'inspect';
+  modules: ReadonlyArray<ModuleDescriptor>;
+  ok: boolean;
+}
+
+interface ModulesVerifyResult {
+  action: 'verify';
+  diagnostics: ReadonlyArray<Diagnostic>;
+  modules: ReadonlyArray<ModuleDescriptor>;
+  ok: boolean;
+}
+
+export type ModulesCommandResult = ModulesInspectResult | ModulesListResult | ModulesVerifyResult;
+
+function apiOptions(projectRoot: string, options: ModulesCommandOptions) {
+  return {
+    projectRoot,
+    platform: 'harmony' as const,
+    ...(options.nativeModulesDir === undefined ? {} : { nativeModulesDir: options.nativeModulesDir }),
+    ...(options.variant === undefined ? {} : { buildType: options.variant }),
+  };
+}
+
+async function runModulesCommandAsync(
+  projectRoot: string,
+  options: ModulesCommandOptions
+): Promise<ModulesCommandResult> {
+  const shared = apiOptions(projectRoot, options);
+
+  if (options.action === 'list') {
+    const result = await searchModulesAsync(shared);
+
+    return {
+      action: 'list',
+      duplicates: result.duplicates,
+      missingIncludes: result.missingIncludes,
+      modules: result.modules.map(module => ({
+        packageName: module.packageName,
+        packageVersion: module.packageVersion,
+        source: module.source,
+        supportsHarmony: module.supportsHarmony,
+      })),
+      ok: result.missingIncludes.length === 0,
+    };
+  }
+
+  if (options.action === 'inspect') {
+    const modules = await resolveModulesAsync(shared);
+    const selected = options.packageName === undefined
+      ? modules
+      : modules.filter(module => module.packageName === options.packageName);
+
+    if (options.packageName !== undefined && selected.length === 0) {
+      throw new HarmonyCliError(
+        'ERR_HARMONY_MODULE_NOT_FOUND',
+        `Harmony module '${options.packageName}' was not discovered. Run 'expo-harmony modules list' to inspect candidates.`,
+        { operation: 'modules-inspect' }
+      );
+    }
+
+    return { action: 'inspect', modules: selected, ok: true };
+  }
+
+  const result = await verifyModulesAsync(shared);
+
+  return {
+    action: 'verify',
+    diagnostics: result.diagnostics,
+    modules: result.modules,
+    ok: result.valid,
+  };
+}
+
+function formatDiagnostic(diagnostic: Diagnostic): string {
+  const subject = diagnostic.packageName ? ` ${diagnostic.packageName}` : '';
+  return `${diagnostic.severity === 'error' ? '✗' : '!'} [${diagnostic.code}]${subject}: ${diagnostic.message}`;
+}
+
+function formatModulesResult(result: ModulesCommandResult): string {
+  if (result.action === 'list') {
+    const lines = result.modules.map(module => (
+      `${module.supportsHarmony ? '✓' : '-'} ${module.packageName}@${module.packageVersion} [${module.source}]`
+    ));
+    for (const packageName of result.missingIncludes) {
+      lines.push(`✗ missing required package ${packageName}`);
+    }
+    for (const duplicate of result.duplicates) {
+      lines.push(`! duplicate ${duplicate.packageName}: ${duplicate.revisions.map(item => item.version).join(', ')}`);
+    }
+    return lines.length === 0 ? 'No native module candidates were discovered.' : lines.join('\n');
+  }
+
+  if (result.action === 'verify') {
+    if (result.diagnostics.length === 0) {
+      return `✓ Verified ${result.modules.length} Harmony native module(s).`;
+    }
+    return result.diagnostics.map(formatDiagnostic).join('\n');
+  }
+
+  return result.modules.map((module) => {
+    const arkTsModules = module.harmony.modules.join(', ') || 'none';
+    const har = module.arkTs
+      ? `${module.arkTs.ohPackageName} <- ${module.arkTs.harPath}`
+      : 'none';
+    return [
+      `${module.packageName}@${module.packageVersion}`,
+      `  source: ${module.source}`,
+      `  packageRoot: ${module.packageRoot}`,
+      `  ArkTS modules: ${arkTsModules}`,
+      `  HAR: ${har}`,
+    ].join('\n');
+  }).join('\n');
+}
+
+export { formatModulesResult, runModulesCommandAsync };

package/src/modules/options.ts

@@ -0,0 +1,70 @@
+import { CommonOptions, parseArgs } from '../args';
+import { HarmonyCliError } from '../errors';
+
+const ModuleOptions = {
+  ...CommonOptions,
+  'package': { short: 'p', type: 'string' },
+  'variant': { type: 'string' },
+  'native-modules-dir': { type: 'string' },
+} as const;
+
+export type ModulesAction = 'inspect' | 'list' | 'verify';
+
+function parseModulesArgs(argv: string[]) {
+  const { positionals, values } = parseArgs(ModuleOptions, argv);
+  const action = positionals[0] as ModulesAction | undefined;
+
+  if (values.help && action === undefined) {
+    return {
+      action: 'list' as const,
+      help: true,
+      project: undefined,
+      packageName: values.package,
+      nativeModulesDir: values['native-modules-dir'],
+      variant: values.variant as 'debug' | 'release' | undefined,
+    };
+  }
+
+  if (!action || !['inspect', 'list', 'verify'].includes(action)) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      'modules requires one of: list, inspect, verify.',
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  if (positionals.length > 2) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      `Unexpected modules positional argument: ${positionals[2]}`,
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  if (values.variant !== undefined && !['debug', 'release'].includes(values.variant)) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      `--variant must be debug or release, received: ${values.variant}`,
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  if (values.package !== undefined && action !== 'inspect') {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      '--package is supported by modules inspect only.',
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  return {
+    action,
+    help: Boolean(values.help),
+    project: positionals[1],
+    packageName: values.package,
+    nativeModulesDir: values['native-modules-dir'],
+    variant: values.variant as 'debug' | 'release' | undefined,
+  };
+}
+
+export { parseModulesArgs };

package/src/path.ts

@@ -0,0 +1,27 @@
+import path from 'node:path';
+
+function isInside(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+
+  return relative === ''
+    || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function toPosixPath(value: string): string {
+  return value.split(path.sep).join('/');
+}
+
+function assertSafeRelative(relative: string, label: string): string {
+  const segments = typeof relative === 'string' ? relative.split('/') : [];
+  const native = segments.join(path.sep);
+
+  if (!relative || relative.includes('\\') || relative.includes('\0')
+    || segments.some(segment => !segment || segment === '.' || segment === '..')
+    || path.isAbsolute(native)) {
+    throw new Error(`${label} contains an unsafe path.`);
+  }
+
+  return native;
+}
+
+export { assertSafeRelative, isInside, toPosixPath };

package/src/prebuild/check.ts

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  compareAsync,
+  stageAsync,
+} from '@expo-harmony/prebuild-config/check';
+
+import { HarmonyCliError } from '../errors';
+import { isInside } from '../path';
+import { spawnAsync } from '../process';
+import { withHarmonyProjectLockAsync } from '../projectLock';
+import { createHarmonyToolchainEnv, resolveHarmonyBuildPlanAsync, type HarmonyBuildPlan } from '../tools';
+import { resolveExpoCli } from '../expo';
+import { packAsync } from './template';
+
+export type { Change as CheckChange } from '@expo-harmony/prebuild-config/check';
+
+const IgnoredProjectDirectories = new Set(['.expo', '.git', '.hvigor', '.yarn', 'node_modules']);
+const IgnoredHarmonyGeneratedDirectories = new Set([
+  '.cxx',
+  '.git',
+  '.hvigor',
+  'build',
+  'node_modules',
+  'oh_modules',
+]);
+
+interface CheckOptions {
+  buildType?: 'debug' | 'release';
+}
+
+function mirrorRoot(temp, project) {
+  const absolute = path.resolve(project);
+  const parsed = path.parse(absolute);
+  const volume = parsed.root.replace(/[^A-Za-z0-9]+/gu, '') || 'root';
+  const segments = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
+
+  return path.join(temp, 'filesystem', volume, ...segments);
+}
+
+async function linkModulesAsync(source, target) {
+  await fs.promises.mkdir(target, { recursive: true });
+
+  for (const entry of await fs.promises.readdir(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name);
+    const to = path.join(target, entry.name);
+
+    if (entry.name.startsWith('@') && entry.isDirectory() && !entry.isSymbolicLink()) {
+      await fs.promises.mkdir(to);
+      for (const child of await fs.promises.readdir(from, { withFileTypes: true })) {
+        await fs.promises.symlink(
+          path.join(from, child.name),
+          path.join(to, child.name),
+          process.platform === 'win32' && (child.isDirectory() || child.isSymbolicLink())
+            ? 'junction'
+            : child.isDirectory() ? 'dir' : 'file'
+        );
+      }
+      continue;
+    }
+
+    await fs.promises.symlink(
+      from,
+      to,
+      process.platform === 'win32' && (entry.isDirectory() || entry.isSymbolicLink())
+        ? 'junction'
+        : entry.isDirectory() ? 'dir' : 'file'
+    );
+  }
+}
+
+function isAppLocalHarmonyPath(project: string, source: string): boolean {
+  const segments = path.relative(project, source).split(path.sep);
+
+  return segments.length >= 3
+    && segments[0] === 'modules'
+    && segments[1] !== ''
+    && segments[2] === 'harmony';
+}
+
+function shouldCopyPrebuildCheckPath(
+  project: string,
+  source: string,
+  plan: HarmonyBuildPlan
+): boolean {
+  const relative = path.relative(project, source);
+  if (!relative) return true;
+
+  const segments = relative.split(path.sep);
+  if (IgnoredProjectDirectories.has(segments[0])) return false;
+
+  const nativeRoot = isInside(plan.harmonyRoot, source)
+    ? plan.harmonyRoot
+    : isAppLocalHarmonyPath(project, source)
+      ? path.join(project, ...segments.slice(0, 3))
+      : null;
+  if (nativeRoot) {
+    const native = path.relative(nativeRoot, source).split(path.sep);
+    if (native.some(segment => IgnoredHarmonyGeneratedDirectories.has(segment))) return false;
+  }
+
+  return source !== plan.exportPaths.bundle;
+}
+
+async function copyAsync(
+  project: string,
+  target: string,
+  plan: HarmonyBuildPlan,
+  temp = path.dirname(target)
+) {
+  await fs.promises.cp(project, target, {
+    recursive: true,
+    filter: source => shouldCopyPrebuildCheckPath(project, source, plan),
+  });
+
+  const modules = path.join(project, 'node_modules');
+
+  if (!fs.existsSync(modules)) {
+    throw new HarmonyCliError('ERR_HARMONY_DEPENDENCIES_MISSING', 'node_modules is required for --check.', {
+      operation: 'check',
+    });
+  }
+
+  // Keep a real node_modules directory in the isolated project and link its
+  // entries. Dependency scanners then retain the isolated lexical package path
+  // (including scoped packages) instead of collapsing the entire node_modules
+  // root to the source project's realpath. The packages remain read-only and
+  // are never copied or modified by --check.
+  await linkModulesAsync(modules, path.join(target, 'node_modules'));
+  await stageAsync(project, target, temp);
+}
+
+async function checkUnlockedAsync(project, options: CheckOptions) {
+  project = path.resolve(project);
+  const plan = await resolveHarmonyBuildPlanAsync(project);
+  const temp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'expo-harmony-check-'));
+  const expected = mirrorRoot(temp, project);
+  let packed;
+
+  try {
+    await copyAsync(project, expected, plan, temp);
+    packed = await packAsync(project);
+
+    const expo = resolveExpoCli(project);
+    const result = await spawnAsync(process.execPath, [
+      expo.cliPath,
+      'prebuild',
+      expected,
+      '--platform', 'harmony',
+      '--template', packed.tarball,
+      '--no-install',
+    ], {
+      capture: true,
+      cwd: expected,
+      env: {
+        ...createHarmonyToolchainEnv(),
+        ...packed.env,
+        ...(options.buildType ? { EXPO_HARMONY_BUILD_TYPE: options.buildType } : {}),
+        EXPO_HARMONY_CHECK_MIRROR_ROOT: temp,
+      },
+      operation: 'check-prebuild',
+    });
+
+    if (result.code !== 0) {
+      throw new HarmonyCliError(
+        'ERR_HARMONY_MANIFEST_DRIFT',
+        `Isolated Expo prebuild failed:\n${result.stderr || result.stdout}`,
+        { exitCode: result.code, operation: 'check-prebuild' }
+      );
+    }
+
+    return compareAsync(project, expected);
+  } finally {
+    if (packed) await packed.cleanup();
+    await fs.promises.rm(temp, { recursive: true, force: true });
+  }
+}
+
+async function checkAsync(project, options: CheckOptions = {}) {
+  return withHarmonyProjectLockAsync(
+    project,
+    'prebuild-check',
+    () => checkUnlockedAsync(project, options)
+  );
+}
+
+export { checkAsync };

package/src/prebuild/clean.ts

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { HarmonyPlatformDirectory } from '@expo-harmony/prebuild-config/build-descriptor';
+
+import { HarmonyCliError } from '../errors';
+import { isInside } from '../path';
+import { resolveHarmonyBuildPlanIfPresentAsync } from '../tools';
+
+async function assertSafeCleanTarget(projectRoot) {
+  const root = await fs.promises.realpath(projectRoot);
+  const plan = await resolveHarmonyBuildPlanIfPresentAsync(root);
+  const target = plan?.harmonyRoot ?? path.join(root, HarmonyPlatformDirectory);
+  let stat;
+
+  try {
+    stat = await fs.promises.lstat(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return target;
+    throw new HarmonyCliError(
+      error.code || 'ERR_HARMONY_CLEAN_TARGET',
+      error.message || `Cannot inspect the Harmony clean target: ${target}. Please delete it manually.`,
+      { cause: error, exitCode: error.exitCode, operation: error.operation }
+    );
+  }
+
+  if (!plan) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CLEAN_TARGET',
+      `Refusing to clean ${target} because its CNG manifest is missing. Please delete it manually or run prebuild without --clean.`,
+      { operation: 'clean' }
+    );
+  }
+
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new HarmonyCliError('ERR_HARMONY_CLEAN_TARGET', `Refusing to clean a non-directory or symlink: ${target}. Please delete it manually.`, {
+      operation: 'clean',
+    });
+  }
+
+  const real = await fs.promises.realpath(target);
+
+  if (real !== target || !isInside(root, real) || real === root || real === path.parse(real).root) {
+    throw new HarmonyCliError('ERR_HARMONY_CLEAN_TARGET', `Unsafe Harmony clean target: ${real}. Please delete it manually.`, { operation: 'clean' });
+  }
+
+  const marker = plan.projectFiles.templateMarker;
+  let markerStat;
+
+  try {
+    markerStat = await fs.promises.lstat(marker);
+  } catch (cause) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CLEAN_TARGET',
+      `Refusing to clean ${real} because its template marker cannot be inspected. Please delete it manually.`,
+      { cause, operation: 'clean' }
+    );
+  }
+
+  if (!isInside(real, marker) || !markerStat.isFile() || markerStat.isSymbolicLink()) {
+    throw new HarmonyCliError('ERR_HARMONY_CLEAN_TARGET', `Refusing to clean ${real} because its template marker is unsafe. Please delete it manually.`, { operation: 'clean' });
+  }
+
+  return real;
+}
+
+export { assertSafeCleanTarget };

package/src/prebuild/options.ts

@@ -0,0 +1,69 @@
+import { HarmonyCliError } from '../errors';
+import { CommonOptions, parseArgs } from '../args';
+
+const PrebuildOptions = {
+  ...CommonOptions,
+  'bun': { type: 'boolean' },
+  'check': { type: 'boolean' },
+  'clean': { type: 'boolean' },
+  'no-install': { type: 'boolean' },
+  'npm': { type: 'boolean' },
+  'platform': { short: 'p', type: 'string' },
+  'pnpm': { type: 'boolean' },
+  'skip-dependency-update': { type: 'string' },
+  'template': { short: 't', type: 'string' },
+  'yarn': { type: 'boolean' },
+} as const;
+
+function parsePrebuildArgs(argv: string[], options: { allowProject?: boolean } = {}) {
+  const { positionals, values } = parseArgs(PrebuildOptions, argv);
+
+  if (values.platform !== undefined) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      '--platform is fixed to harmony by expo-harmony.',
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  if (values.template !== undefined) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      '--template is managed by expo-harmony.',
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  if (positionals.length > (options.allowProject ? 1 : 0)) {
+    const unexpected = positionals[options.allowProject ? 1 : 0];
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      `Unexpected prebuild positional argument: ${unexpected}`,
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  const packageManagerFlags = ['npm', 'yarn', 'pnpm', 'bun'].filter(name => values[name]);
+  if (packageManagerFlags.length > 1) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', 'Choose at most one package manager: --npm, --yarn, --pnpm, or --bun.', { operation: 'parse-arguments' });
+  }
+
+  const passthrough: string[] = [];
+  for (const name of ['clean', 'npm', 'yarn', 'pnpm', 'bun', 'no-install']) {
+    if (values[name]) passthrough.push(`--${name}`);
+  }
+
+  if (values['skip-dependency-update'] !== undefined) {
+    passthrough.push('--skip-dependency-update', values['skip-dependency-update']);
+  }
+
+  return {
+    check: Boolean(values.check),
+    clean: Boolean(values.clean),
+    help: Boolean(values.help),
+    passthrough,
+    project: positionals[0],
+  };
+}
+
+export { parsePrebuildArgs };

package/src/prebuild/prebuild.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+
+import { HarmonyCliError } from '../errors';
+import { formatDiagnostics, spawnAsync } from '../process';
+import { withHarmonyProjectLockAsync } from '../projectLock';
+import { resolveExpoCli } from '../expo';
+import { createHarmonyToolchainEnv, resolveHarmonyBuildPlanAsync } from '../tools';
+import { assertSafeCleanTarget } from './clean';
+import { packAsync } from './template';
+
+interface PrebuildOptions {
+  buildType?: 'debug' | 'release';
+  capture?: boolean;
+}
+
+async function prebuildParsedUnlockedAsync(
+  projectRoot: string,
+  passthrough: string[],
+  options: PrebuildOptions = {}
+) {
+  if (passthrough.includes('--clean')) await assertSafeCleanTarget(projectRoot);
+
+  const expo = resolveExpoCli(projectRoot);
+  const packed = await packAsync(projectRoot);
+
+  try {
+    const result = await spawnAsync(process.execPath, [
+      expo.cliPath,
+      'prebuild', projectRoot,
+      '--platform', 'harmony',
+      '--template', packed.tarball,
+      ...passthrough,
+    ], {
+      capture: Boolean(options.capture),
+      cwd: projectRoot,
+      env: {
+        ...createHarmonyToolchainEnv(),
+        ...packed.env,
+        ...(options.buildType ? { EXPO_HARMONY_BUILD_TYPE: options.buildType } : {}),
+      },
+      operation: 'expo-prebuild',
+      outputLimit: 4 * 1024 * 1024,
+    });
+
+    if (result.code !== 0) {
+      const diagnostics = options.capture ? formatDiagnostics(result) : '';
+      throw new HarmonyCliError('ERR_HARMONY_PREBUILD_FAILED', `Expo prebuild exited with code ${result.code}.${diagnostics ? `\n${diagnostics}` : ''}`, {
+        exitCode: result.code,
+        operation: 'expo-prebuild',
+      });
+    }
+
+    try {
+      const plan = await resolveHarmonyBuildPlanAsync(projectRoot, {
+        buildMode: options.buildType,
+      });
+      await fs.promises.access(plan.projectFiles.templateMarker, fs.constants.R_OK);
+    } catch (cause) {
+      throw new HarmonyCliError('ERR_HARMONY_TEMPLATE_INVALID', 'Expo prebuild exited successfully but the Harmony marker or CNG manifest is invalid.', { cause, operation: 'verify-prebuild' });
+    }
+
+    return result;
+  } finally {
+    await packed.cleanup();
+  }
+}
+
+async function prebuildParsedAsync(
+  projectRoot: string,
+  passthrough: string[],
+  options: PrebuildOptions = {}
+) {
+  return withHarmonyProjectLockAsync(
+    projectRoot,
+    'prebuild',
+    () => prebuildParsedUnlockedAsync(projectRoot, passthrough, options)
+  );
+}
+
+export { prebuildParsedAsync };