@expo-harmony/cli 55.0.26-harmony.8 → 55.0.26-harmony.9

package/src/prebuild/check.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -5,20 +6,22 @@ import path from 'node:path';
 import {
   compareAsync,
   stageAsync,
-} from '@expo-harmony/prebuild-config/check';
+} from '@expo-harmony/prebuild-config/internal';
 
 import { HarmonyCliError } from '../errors';
 import { isInside } from '../path';
 import { spawnAsync } from '../process';
 import { withHarmonyProjectLockAsync } from '../projectLock';
-import { createHarmonyToolchainEnv, resolveHarmonyBuildPlanAsync, type HarmonyBuildPlan } from '../tools';
+import { createHarmonyToolchainEnv } from '../native/toolchain';
+import { resolveHarmonyBuildPlanAsync } from '../native/project';
+import { type HarmonyBuildPlan } from '../native/types';
 import { resolveExpoCli } from '../expo';
 import { packAsync } from './template';
 
-export type { Change as CheckChange } from '@expo-harmony/prebuild-config/check';
+export type { Change as CheckChange } from '@expo-harmony/prebuild-config/internal';
 
-const IgnoredProjectDirectories = new Set(['.expo', '.git', '.hvigor', '.yarn', 'node_modules']);
-const IgnoredHarmonyGeneratedDirectories = new Set([
+const IgnoredDirectories = new Set(['.expo', '.git', '.hvigor', '.yarn', 'node_modules']);
+const GeneratedDirectories = new Set([
   '.cxx',
   '.git',
   '.hvigor',
@@ -103,16 +106,18 @@ function shouldCopyPrebuildCheckPath(
   if (!relative) return true;
 
   const segments = relative.split(path.sep);
-  if (IgnoredProjectDirectories.has(segments[0])) return false;
+  if (IgnoredDirectories.has(segments[0])) return false;
 
-  const nativeRoot = isInside(plan.harmonyRoot, source)
+  const root = 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;
+  if (root) {
+    const native = path.relative(root, source).split(path.sep);
+    if (GeneratedDirectories.has(native[0])
+      || (GeneratedDirectories.has(native[1])
+        && fs.existsSync(path.join(root, native[0], 'src/main/module.json5')))) return false;
   }
 
   return source !== plan.exportPaths.bundle;
@@ -126,6 +131,7 @@ async function copyAsync(
 ) {
   await fs.promises.cp(project, target, {
     recursive: true,
+    verbatimSymlinks: true,
     filter: source => shouldCopyPrebuildCheckPath(project, source, plan),
   });
 
@@ -137,16 +143,16 @@ async function copyAsync(
     });
   }
 
-  // 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. Package directories stay linked;
-  // Windows copies loose files to avoid requiring file-symlink privileges.
+  // Link individual packages so dependency scanners retain paths inside the mirror.
   await linkModulesAsync(modules, path.join(target, 'node_modules'));
   await stageAsync(project, target, temp);
 }
 
-async function checkUnlockedAsync(project, options: CheckOptions) {
+async function withGeneratedProjectAsync<T>(
+  project: string,
+  options: CheckOptions & { clean?: boolean; skipPatches?: boolean },
+  action: (expected: string, checksum: string) => Promise<T>
+): Promise<T> {
   project = path.resolve(project);
   const plan = await resolveHarmonyBuildPlanAsync(project);
   const temp = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'expo-harmony-check-'));
@@ -155,6 +161,8 @@ async function checkUnlockedAsync(project, options: CheckOptions) {
 
   try {
     await copyAsync(project, expected, plan, temp);
+    if (options.clean) await fs.promises.rm(path.join(expected, 'harmony'), { recursive: true, force: true });
+
     packed = await packAsync(project);
 
     const expo = resolveExpoCli(project);
@@ -173,6 +181,7 @@ async function checkUnlockedAsync(project, options: CheckOptions) {
         ...packed.env,
         ...(options.buildType ? { EXPO_HARMONY_BUILD_TYPE: options.buildType } : {}),
         EXPO_HARMONY_CHECK_MIRROR_ROOT: temp,
+        ...(options.skipPatches ? { EXPO_HARMONY_SKIP_PATCHES: '1' } : {}),
       },
       operation: 'check-prebuild',
     });
@@ -185,7 +194,9 @@ async function checkUnlockedAsync(project, options: CheckOptions) {
       );
     }
 
-    return compareAsync(project, expected);
+    const checksum = createHash('md5').update(Uint8Array.from(await fs.promises.readFile(packed.tarball))).digest('hex');
+
+    return await action(expected, checksum);
   } finally {
     if (packed) await packed.cleanup();
     await fs.promises.rm(temp, { recursive: true, force: true });
@@ -196,8 +207,8 @@ async function checkAsync(project, options: CheckOptions = {}) {
   return withHarmonyProjectLockAsync(
     project,
     'prebuild-check',
-    () => checkUnlockedAsync(project, options)
+    () => withGeneratedProjectAsync(project, options, expected => compareAsync(project, expected))
   );
 }
 
-export { checkAsync };
+export { checkAsync, withGeneratedProjectAsync };

package/src/prebuild/clean.ts

@@ -1,11 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { HarmonyPlatformDirectory } from '@expo-harmony/prebuild-config/build-descriptor';
+import { HarmonyPlatformDirectory } from '@expo-harmony/prebuild-config/internal';
 
 import { HarmonyCliError } from '../errors';
 import { isInside } from '../path';
-import { resolveHarmonyBuildPlanIfPresentAsync } from '../tools';
+import { resolveHarmonyBuildPlanIfPresentAsync } from '../native/project';
 
 async function assertSafeCleanTarget(projectRoot) {
   const root = await fs.promises.realpath(projectRoot);
@@ -24,7 +24,7 @@ async function assertSafeCleanTarget(projectRoot) {
     );
   }
 
-  if (!plan) {
+  if (!plan || plan.workflow !== 'cng') {
     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.`,

package/src/prebuild/index.ts

@@ -0,0 +1,56 @@
+import { parseCommandArgs, type Command } from '../command';
+import { HarmonyCliError } from '../errors';
+import { withHarmonyProjectLockAsync } from '../projectLock';
+import { parsePrebuildArgs } from './options';
+
+export const command: Command = async (argv, io) => {
+  const args = parseCommandArgs(args => parsePrebuildArgs(args, { allowProject: true }), argv, io);
+  if (!args) return 0;
+
+  const { projectRoot: root, options } = args;
+  const { check, clean, passthrough } = options;
+
+  if (check && passthrough.length) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--check cannot be combined with mutating prebuild options.');
+  }
+
+  return withHarmonyProjectLockAsync(
+    root,
+    check ? 'prebuild-check' : 'prebuild',
+    async () => {
+      if (clean) {
+        const { assertSafeCleanTarget } = await import('./clean.js');
+        await assertSafeCleanTarget(root);
+      }
+
+      const { doctorAsync, formatDoctor } = await import('../doctor/doctor.js');
+      const doctor = await doctorAsync(root, {
+        requireBuildTools: false,
+        validateGeneratedProject: !clean,
+        validateModules: false,
+      });
+      if (!doctor.ok) {
+        io.error(formatDoctor(doctor));
+        throw new HarmonyCliError('ERR_HARMONY_DOCTOR_FAILED', 'Harmony doctor found blocking errors.', {
+          operation: 'doctor',
+        });
+      }
+
+      for (const item of doctor.checks.filter(item => item.status === 'warn')) io.warn(`! ${item.message}`);
+
+      if (check) {
+        const { checkAsync } = await import('./check.js');
+        const result = await checkAsync(root);
+
+        if (result.clean) io.log('Harmony CNG output is up to date.');
+        else for (const change of result.changes) io.log(`${change.type}: ${change.path}`);
+
+        return result.clean ? 0 : 2;
+      }
+
+      const { prebuildParsedAsync } = await import('./prebuild.js');
+      await prebuildParsedAsync(root, passthrough);
+
+      return 0;
+    });
+};

package/src/prebuild/prebuild.ts

@@ -1,10 +1,12 @@
 import fs from 'node:fs';
 
 import { HarmonyCliError } from '../errors';
+import { isBareHarmonyProject } from '../native/bare';
 import { formatDiagnostics, spawnAsync } from '../process';
 import { withHarmonyProjectLockAsync } from '../projectLock';
 import { resolveExpoCli } from '../expo';
-import { createHarmonyToolchainEnv, resolveHarmonyBuildPlanAsync } from '../tools';
+import { createHarmonyToolchainEnv } from '../native/toolchain';
+import { resolveHarmonyBuildPlanAsync } from '../native/project';
 import { assertSafeCleanTarget } from './clean';
 import { packAsync } from './template';
 
@@ -18,6 +20,9 @@ async function prebuildParsedUnlockedAsync(
   passthrough: string[],
   options: PrebuildOptions = {}
 ) {
+  if (isBareHarmonyProject(projectRoot)) {
+    throw new HarmonyCliError('ERR_HARMONY_BARE_PREBUILD', 'This Harmony project is manually maintained. Build it directly; prebuild cannot overwrite a bare project.', { operation: 'prebuild' });
+  }
   if (passthrough.includes('--clean')) await assertSafeCleanTarget(projectRoot);
 
   const expo = resolveExpoCli(projectRoot);
@@ -44,6 +49,7 @@ async function prebuildParsedUnlockedAsync(
 
     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',
@@ -54,6 +60,10 @@ async function prebuildParsedUnlockedAsync(
       const plan = await resolveHarmonyBuildPlanAsync(projectRoot, {
         buildMode: options.buildType,
       });
+      if (plan.workflow !== 'cng') {
+        throw new HarmonyCliError('ERR_HARMONY_TEMPLATE_INVALID', 'Prebuild did not produce a CNG project.', { operation: 'prebuild' });
+      }
+
       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' });

package/src/prebuild/template.ts

@@ -19,11 +19,11 @@ function resolve(project: string) {
   let api: Api;
 
   try {
-    api = load('@expo-harmony/prebuild-config/template');
+    api = load('@expo-harmony/prebuild-config/internal/template');
   } catch (cause) {
     throw new HarmonyCliError(
       'ERR_HARMONY_TEMPLATE_INVALID',
-      'Cannot load @expo-harmony/prebuild-config/template from the project. Update the project-local prebuild config to a compatible version.',
+      'Cannot load @expo-harmony/prebuild-config/internal/template from the project. Update the project-local prebuild config to a compatible version.',
       { cause, operation: 'resolve-template' }
     );
   }

package/src/process.ts

@@ -28,6 +28,16 @@ export interface ProcessResult {
   timedOut: boolean;
 }
 
+interface CheckedProcessOptions {
+  code: string;
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  message: string;
+  operation: string;
+  outputLimit?: number;
+  timeoutMs?: number;
+}
+
 class BoundedCapture {
   private buffers: Uint8Array[] = [];
   private head = 0;
@@ -346,4 +356,31 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
   };
 }
 
-export { formatDiagnostics, spawnAsync, startManagedProcess };
+async function runCheckedAsync(
+  command: string,
+  args: string[],
+  options: CheckedProcessOptions
+) {
+  const result = await spawnAsync(command, args, {
+    capture: true,
+    cwd: options.cwd,
+    env: options.env,
+    operation: options.operation,
+    outputLimit: options.outputLimit || 2 * 1024 * 1024,
+    timeoutMs: options.timeoutMs,
+  });
+
+  if (result.code !== 0 || result.timedOut) {
+    const diagnostics = formatDiagnostics(result);
+
+    throw new HarmonyCliError(
+      options.code,
+      `${options.message} exited with code ${result.code}${result.timedOut ? ' after timing out' : ''}.${diagnostics ? `\n${diagnostics}` : ''}`,
+      { exitCode: result.code || 1, operation: options.operation }
+    );
+  }
+
+  return result;
+}
+
+export { formatDiagnostics, runCheckedAsync, spawnAsync, startManagedProcess };

package/src/profile.ts

@@ -0,0 +1,13 @@
+export async function timedAsync<T>(
+  steps: Record<string, number>,
+  name: string,
+  operation: () => Promise<T> | T
+): Promise<T> {
+  const started = performance.now();
+
+  try {
+    return await operation();
+  } finally {
+    steps[name] = Math.max(0, Math.round(performance.now() - started));
+  }
+}

package/src/projectLock.ts

@@ -162,6 +162,7 @@ async function acquireHarmonyProjectLockAsync(
         await handle.sync();
       } catch (cause) {
         await releaseOwnedLockAsync(handle, lockPath, owned);
+
         throw new HarmonyCliError(
           'ERR_HARMONY_PROJECT_LOCK',
           'Cannot initialize the Harmony native operation lock.',
@@ -183,7 +184,14 @@ async function acquireHarmonyProjectLockAsync(
         },
       };
     } catch (cause) {
-      if (cause instanceof HarmonyCliError) throw cause;
+      if (cause instanceof HarmonyCliError) {
+        throw new HarmonyCliError(cause.code, cause.message, {
+          cause,
+          exitCode: cause.exitCode,
+          operation: cause.operation,
+        });
+      }
+
       if (cause?.code !== 'EEXIST') {
         throw new HarmonyCliError(
           'ERR_HARMONY_PROJECT_LOCK',

package/src/run/devices.ts

@@ -2,7 +2,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 
 import { listEmulatorsAsync, startEmulator } from './emulators';
 import { HarmonyCliError } from '../errors';
-import type { HarmonyTool } from '../tools';
+import { type HarmonyTool } from '../native/toolchain';
 import { formatDiagnostics, spawnAsync, type ProcessResult } from '../process';
 
 interface Device {
@@ -44,8 +44,6 @@ function parseHdcTargets(output: string): Device[] {
     }
 
     return {
-      // Only the first HDC column is a selectable target name. The remaining
-      // verbose columns describe transport, state, location and connect tool.
       aliases: [fields[0]],
       connectTool: fields[4] || null,
       id: fields[0],
@@ -59,10 +57,7 @@ function parseHdcTargets(output: string): Device[] {
 function hasCommandFailure(result: ProcessResult): boolean {
   const output = `${result.stdout || ''}\n${result.stderr || ''}`;
   return result.code !== 0 || result.timedOut
-    // HDC occasionally reports transport and package-manager failures on
-    // stdout while still returning exit code 0 (for example,
-    // "Connect server failed"). Treat its documented failure vocabulary as
-    // authoritative regardless of where it appears on the line.
+    // HDC can print failures to stdout while returning exit code 0.
     || /\[(?:Fail|Error)\]|\b(?:Failure|failed)\b|(?:失败|错误)/iu.test(output);
 }
 
@@ -146,7 +141,6 @@ async function selectDeviceAsync(
   }
 
   const instances = await listEmulatorsAsync(options.emulator, { cwd: options.cwd });
-  // Prefer an instance that is already booting when HDC is not connected yet.
   const running = instances.filter(instance => instance.running);
   const candidates = requested
     ? instances.filter(instance => instance.name === requested)
@@ -242,13 +236,24 @@ async function configureMetroPortAsync(
   const deviceEndpoint = `tcp:${options.devicePort || 8081}`;
   const hostEndpoint = `tcp:${port}`;
 
-  await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', deviceEndpoint, hostEndpoint], {
-    allowFailure: true,
+  const forwards = await runHdcAsync(hdc, ['-t', device.id, 'fport', 'ls'], {
     cwd: options.cwd,
-    operation: 'remove-metro-port',
+    operation: 'list-metro-ports',
     timeoutMs: 15_000,
   });
 
+  for (const line of forwards.stdout.split(/\r?\n/u)) {
+    const [target, remote, local, direction] = line.trim().split(/\s+/u);
+    if (target !== device.id || remote !== deviceEndpoint || direction !== '[Reverse]') continue;
+    if (local === hostEndpoint) return;
+
+    await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', remote, local], {
+      cwd: options.cwd,
+      operation: 'remove-metro-port',
+      timeoutMs: 15_000,
+    });
+  }
+
   await runHdcAsync(hdc, ['-t', device.id, 'rport', deviceEndpoint, hostEndpoint], {
     code: 'ERR_HARMONY_METRO_FORWARD',
     cwd: options.cwd,

package/src/run/emulators.ts

@@ -4,7 +4,7 @@ import spawn from 'cross-spawn';
 
 import { HarmonyCliError } from '../errors';
 import { formatDiagnostics, spawnAsync } from '../process';
-import type { HarmonyTool } from '../tools';
+import { type HarmonyTool } from '../native/toolchain';
 
 interface HarmonyEmulator {
   name: string;
@@ -67,10 +67,9 @@ function startEmulator(tool: HarmonyTool, name: string, logFile: string, cwd?: s
   fs.mkdirSync(path.dirname(logFile), { recursive: true });
   const log = fs.openSync(logFile, 'w', 0o600);
   let failure: string | null = null;
+
   try {
-    // Emulator may remain alive for the whole GUI session. Give it its own
-    // process group and file-backed output so it survives the CLI/Metro exit.
-    // Default instance/image paths match the ones used by -list -details.
+    // A detached process with file output lets the emulator survive CLI exit.
     const child = spawn(tool.command, [...tool.args, '-start', name], {
       cwd,
       detached: true,
@@ -82,8 +81,7 @@ function startEmulator(tool: HarmonyTool, name: string, logFile: string, cwd?: s
       failure = cause.message;
     });
     child.once('exit', (code, signal) => {
-      // Some versions use a short-lived launcher. A zero exit alone does not
-      // prove readiness; the caller still checks the guest's name and boot state.
+      // Some launchers exit before the guest boots; HDC still has to confirm readiness.
       if (code !== 0) failure = signal ? `terminated by ${signal}` : `exited with code ${code}`;
     });
     child.unref();

package/src/run/index.ts

@@ -0,0 +1,25 @@
+import { parseCommandArgs, type Command } from '../command';
+import { parseRunArgs } from './options';
+
+export const command: Command = async (argv, io) => {
+  const args = parseCommandArgs(parseRunArgs, argv, io);
+  if (!args) return 0;
+
+  const { projectRoot: root, options } = args;
+  const { runHarmonySessionAsync } = await import('./run.js');
+
+  const session = await runHarmonySessionAsync(root, {
+    ...options,
+    interactiveBundler: true,
+    io,
+  });
+  const { result } = session;
+
+  io.log(`Launched ${result.bundleName} on ${result.device.id} (${result.variant}).`);
+  if (session.metro.owner === 'started') {
+    io.log('\n› Logs for your project will appear below. Press Ctrl+C to exit.');
+    await session.metro.waitAsync();
+  }
+
+  return 0;
+};