@expo-harmony/cli 55.0.26-harmony.1 → 55.0.26-harmony.10

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

@@ -1,4 +1,5 @@
 import spawn from 'cross-spawn';
+import { terminateProcess } from '@expo-harmony/expo-modules-autolinking/tool-command';
 
 import { HarmonyCliError } from './errors';
 
@@ -27,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;
@@ -76,8 +87,15 @@ function formatDiagnostics(result: Pick<ProcessResult, 'stderr' | 'stdout'>, lim
 
 function spawnAsync(command: string, args: string[], options: ProcessOptions = {}): Promise<ProcessResult> {
   return new Promise<ProcessResult>((resolve, reject) => {
+    if (options.signal?.aborted) {
+      throw new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: operation aborted.`, {
+        cause: options.signal.reason,
+        operation: options.operation || 'spawn',
+      });
+    }
+
     const piped = Boolean(options.capture || options.onStdout || options.onStderr);
-    const outputLimit = options.outputLimit || DefaultOutputLimit;
+    const limit = options.outputLimit || DefaultOutputLimit;
     const child = spawn(command, args, {
       cwd: options.cwd,
       env: options.env || process.env,
@@ -86,11 +104,12 @@ function spawnAsync(command: string, args: string[], options: ProcessOptions = {
       windowsHide: true,
     });
 
-    const stdout = new BoundedCapture(outputLimit);
-    const stderr = new BoundedCapture(outputLimit);
+    const stdout = new BoundedCapture(limit);
+    const stderr = new BoundedCapture(limit);
     let timedOut = false;
     let settled = false;
-    let forceKillTimer: NodeJS.Timeout | null = null;
+    let escalation: NodeJS.Timeout | null = null;
+    let stopping: Promise<void> | undefined;
 
     if (piped) {
       child.stdout.on('data', (chunk) => {
@@ -103,72 +122,96 @@ function spawnAsync(command: string, args: string[], options: ProcessOptions = {
       });
     }
 
-    const stopChild = (signal: NodeJS.Signals = 'SIGTERM') => {
-      child.kill(signal);
-      if (forceKillTimer === null) {
-        forceKillTimer = setTimeout(
-          () => child.kill('SIGKILL'),
+    const stop = (signal: NodeJS.Signals = 'SIGTERM') => {
+      if (stopping || settled) return;
+
+      stopping = Promise.resolve().then(() => terminateProcess(child, signal));
+      if (process.platform === 'win32') {
+        void finish(null, signal);
+      } else {
+        stopping.catch((cause) => {
+          void finish(null, null, cause);
+        });
+        escalation = setTimeout(
+          () => {
+            stopping = terminateProcess(child, 'SIGKILL');
+            stopping.catch((cause) => {
+              void finish(null, null, cause);
+            });
+          },
           options.stopGraceMs || DefaultStopGraceMs
         );
-        forceKillTimer.unref?.();
+        escalation.unref?.();
       }
     };
 
-    const forwardSigint = () => stopChild('SIGINT');
-    const forwardSigterm = () => stopChild('SIGTERM');
-    process.once('SIGINT', forwardSigint);
-    process.once('SIGTERM', forwardSigterm);
+    const interrupt = () => stop('SIGINT');
+    const terminate = () => stop('SIGTERM');
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', terminate);
 
     const timeout = options.timeoutMs
       ? setTimeout(() => {
           timedOut = true;
-          stopChild('SIGTERM');
+          stop('SIGTERM');
         }, options.timeoutMs)
       : null;
     timeout?.unref?.();
 
     const cleanup = () => {
       if (timeout) clearTimeout(timeout);
-      if (forceKillTimer) clearTimeout(forceKillTimer);
-      process.removeListener('SIGINT', forwardSigint);
-      process.removeListener('SIGTERM', forwardSigterm);
+      if (escalation) clearTimeout(escalation);
+      process.removeListener('SIGINT', interrupt);
+      process.removeListener('SIGTERM', terminate);
       options.signal?.removeEventListener('abort', abort);
     };
 
-    const abort = () => stopChild('SIGTERM');
-    if (options.signal?.aborted) abort();
-    else options.signal?.addEventListener('abort', abort, { once: true });
+    const finish = async (code, signal, cause?) => {
+      try {
+        await stopping;
+      } catch (error) {
+        cause = error;
+      }
 
-    child.once('error', (cause) => {
       if (settled) return;
       settled = true;
       cleanup();
 
-      reject(new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
+      if (cause) reject(new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: ${cause.message}`, {
         cause,
         operation: options.operation || 'spawn',
       }));
-    });
-    // `close` runs after stdout/stderr have closed, so captured diagnostics are
-    // complete. `exit` can fire while pipe data is still pending.
-    child.once('close', (code, signal) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-
-      resolve({
+      else resolve({
         code: code === null ? 1 : code,
         signal,
         stderr: stderr.toString(),
         stdout: stdout.toString(),
         timedOut,
       });
+    };
+
+    child.once('error', (cause) => {
+      void finish(null, null, cause);
+    });
+    child.once('close', (code, signal) => {
+      void finish(code, signal);
     });
+
+    const abort = () => stop('SIGTERM');
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted) abort();
   });
 }
 
 function startManagedProcess(command: string, args: string[], options: ProcessOptions = {}) {
-  const outputLimit = options.outputLimit || DefaultOutputLimit;
+  if (options.signal?.aborted) {
+    throw new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: operation aborted.`, {
+      cause: options.signal.reason,
+      operation: options.operation || 'spawn',
+    });
+  }
+
+  const limit = options.outputLimit || DefaultOutputLimit;
   const piped = options.stdio !== 'inherit';
   const child = spawn(command, args, {
     cwd: options.cwd,
@@ -178,11 +221,14 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
     windowsHide: true,
   });
 
-  const stdout = new BoundedCapture(outputLimit);
-  const stderr = new BoundedCapture(outputLimit);
-  let spawnError: HarmonyCliError | null = null;
+  const stdout = new BoundedCapture(limit);
+  const stderr = new BoundedCapture(limit);
+  let failure: HarmonyCliError | null = null;
   let closed = false;
-  let stopRequested = false;
+  let stopped = false;
+  let stopping: Promise<void> | undefined;
+  let stopPromise: Promise<ProcessResult | undefined> | undefined;
+  let finish: (code: number | null, signal: NodeJS.Signals | null) => Promise<void>;
 
   if (piped) {
     child.stdout.on('data', (chunk) => {
@@ -195,34 +241,43 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
     });
   }
 
-  const forwardSigint = () => {
-    void stop('SIGINT');
+  const interrupt = () => {
+    void stop('SIGINT').catch(() => {});
   };
-  const forwardSigterm = () => {
-    void stop('SIGTERM');
+  const terminate = () => {
+    void stop('SIGTERM').catch(() => {});
   };
   const abort = () => {
-    void stop('SIGTERM');
+    void stop('SIGTERM').catch(() => {});
   };
 
   const cleanup = () => {
-    process.removeListener('SIGINT', forwardSigint);
-    process.removeListener('SIGTERM', forwardSigterm);
+    process.removeListener('SIGINT', interrupt);
+    process.removeListener('SIGTERM', terminate);
     options.signal?.removeEventListener('abort', abort);
   };
 
   const completion = new Promise<ProcessResult>((resolve, reject) => {
     child.once('error', (cause) => {
-      spawnError = new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
+      failure = new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
         cause,
         operation: options.operation || 'spawn',
       });
     });
-    child.once('close', (code, signal) => {
+    finish = async (code, signal) => {
+      try {
+        await stopping;
+      } catch (cause) {
+        failure = new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot stop ${command}: ${cause.message}`, {
+          cause, operation: options.operation || 'spawn',
+        });
+      }
+
+      if (closed) return;
       closed = true;
       cleanup();
 
-      if (spawnError) reject(spawnError);
+      if (failure) reject(failure);
       else resolve({
         code: code === null ? 1 : code,
         signal,
@@ -230,6 +285,10 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
         stdout: stdout.toString(),
         timedOut: false,
       });
+    };
+
+    child.once('close', (code, signal) => {
+      void finish(code, signal);
     });
   });
   // A readiness probe may be the first consumer. Keep early spawn failures from
@@ -237,28 +296,53 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
   completion.catch(() => {});
 
   async function stop(signal: NodeJS.Signals = 'SIGTERM', graceMs = DefaultStopGraceMs) {
+    if (stopPromise) return stopPromise;
     if (closed) return completion;
 
-    stopRequested = true;
-    child.kill(signal);
-    let timer: NodeJS.Timeout | undefined;
+    stopped = true;
+    stopping = Promise.resolve().then(() => terminateProcess(child, signal));
+    stopPromise = (async () => {
+      if (process.platform === 'win32') {
+        void finish(null, signal);
+        return completion;
+      }
 
-    await Promise.race([
-      completion.catch(() => undefined),
-      new Promise((resolve) => {
-        timer = setTimeout(resolve, graceMs);
-        timer.unref?.();
-      }),
-    ]);
+      try {
+        await stopping;
+      } catch {
+        await finish(null, signal);
+        return completion;
+      }
+
+      let timer: NodeJS.Timeout | undefined;
+
+      await Promise.race([
+        completion.catch(() => undefined),
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, graceMs);
+          timer.unref?.();
+        }),
+      ]);
+
+      if (timer) clearTimeout(timer);
+      if (!closed) {
+        stopping = terminateProcess(child, 'SIGKILL');
+        try {
+          await stopping;
+        } catch {
+          await finish(null, signal);
+        }
+      }
 
-    if (timer) clearTimeout(timer);
-    if (!closed) child.kill('SIGKILL');
+      return completion.catch(() => undefined);
+    })();
+    stopPromise.catch(() => {});
 
-    return completion.catch(() => undefined);
+    return stopPromise;
   }
 
-  process.once('SIGINT', forwardSigint);
-  process.once('SIGTERM', forwardSigterm);
+  process.once('SIGINT', interrupt);
+  process.once('SIGTERM', terminate);
   if (options.signal?.aborted) abort();
   else options.signal?.addEventListener('abort', abort, { once: true });
 
@@ -268,8 +352,35 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
     getStderr: () => stderr.toString(),
     getStdout: () => stdout.toString(),
     stop,
-    wasStopped: () => stopRequested,
+    wasStopped: () => stopped,
   };
 }
 
-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;
+};