@expo-harmony/cli 55.0.26-harmony.1

package/src/run/metro.ts

@@ -0,0 +1,237 @@
+import http from 'node:http';
+
+import { HarmonyCliError } from '../errors';
+import { formatDiagnostics, startManagedProcess, type ProcessResult } from '../process';
+import { resolveExpoCli } from '../expo';
+
+type MetroStatus = 'free' | 'metro' | 'occupied';
+
+interface MetroOptions {
+  interactive?: boolean;
+  port: number;
+  readyTimeoutMs?: number;
+  resetCache?: boolean;
+}
+
+export interface MetroSession {
+  owner: 'existing' | 'started';
+  port: number;
+  process?: ReturnType<typeof startManagedProcess>;
+  stop(): Promise<unknown>;
+  waitAsync(): Promise<void>;
+}
+
+function delay(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+function probeMetroAsync(
+  port: number,
+  options: { host?: string; timeoutMs?: number } = {}
+): Promise<MetroStatus> {
+  const timeoutMs = options.timeoutMs || 750;
+
+  return new Promise<MetroStatus>((resolve) => {
+    let settled = false;
+
+    const finish = (value) => {
+      if (settled) return;
+
+      settled = true;
+      resolve(value);
+    };
+
+    const request = http.get({
+      headers: { Accept: 'text/plain' },
+      host: options.host || '127.0.0.1',
+      path: '/status',
+      port,
+    }, (response) => {
+      let body = '';
+
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => {
+        if (body.length < 1_024) body += chunk;
+      });
+      response.on('end', () => finish(
+        response.statusCode === 200 && body.trim() === 'packager-status:running'
+          ? 'metro'
+          : 'occupied'
+      ));
+    });
+
+    request.setTimeout(timeoutMs, () => {
+      request.destroy();
+      finish('occupied');
+    });
+
+    request.on('error', (error: NodeJS.ErrnoException) => finish(
+      error.code === 'ECONNREFUSED' || error.code === 'EHOSTUNREACH'
+        ? 'free'
+        : 'occupied'
+    ));
+  });
+}
+
+async function requireExistingMetroAsync(port: number): Promise<MetroSession> {
+  const status = await probeMetroAsync(port);
+
+  if (status === 'metro') {
+    return {
+      owner: 'existing',
+      port,
+      stop: async () => {},
+      waitAsync: async () => {},
+    };
+  }
+
+  const code = status === 'free' ? 'ERR_HARMONY_METRO_UNAVAILABLE' : 'ERR_HARMONY_METRO_PORT_IN_USE';
+  const message = status === 'free'
+    ? `No Metro server is running on port ${port}; start Expo Metro before using --no-bundler.`
+    : `Port ${port} is occupied by a process that is not a compatible Metro server.`;
+
+  throw new HarmonyCliError(code, message, { operation: 'metro-probe' });
+}
+
+async function startExpoMetroAsync(
+  projectRoot: string,
+  options: MetroOptions
+): Promise<MetroSession> {
+  const before = await probeMetroAsync(options.port);
+
+  if (before === 'metro') {
+    return {
+      owner: 'existing',
+      port: options.port,
+      stop: async () => {},
+      waitAsync: async () => {},
+    };
+  }
+
+  if (before === 'occupied') {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_METRO_PORT_IN_USE',
+      `Port ${options.port} is occupied by a process that is not a compatible Metro server.`,
+      { operation: 'metro-probe' }
+    );
+  }
+
+  const expo = resolveExpoCli(projectRoot);
+  const managed = startManagedProcess(process.execPath, [
+    expo.cliPath,
+    'start',
+    projectRoot,
+    '--dev-client',
+    '--port', String(options.port),
+    ...(options.resetCache ? ['--clear'] : []),
+  ], {
+    cwd: projectRoot,
+    env: {
+      ...process.env,
+      EXPO_METRO_TARGET: 'harmony',
+    },
+    operation: 'expo-metro',
+    outputLimit: 1024 * 1024,
+    stdio: options.interactive ? 'inherit' : 'pipe',
+  });
+  let exitResult: ProcessResult | null = null;
+  let exitError: unknown = null;
+
+  managed.completion.then(
+    (result) => {
+      exitResult = result;
+    },
+    (error) => {
+      exitError = error;
+    }
+  );
+
+  const startedAt = Date.now();
+  const timeoutMs = options.readyTimeoutMs || 60_000;
+
+  try {
+    while (Date.now() - startedAt < timeoutMs) {
+      if (exitError instanceof HarmonyCliError) {
+        throw new HarmonyCliError(exitError.code, exitError.message, {
+          cause: exitError,
+          exitCode: exitError.exitCode,
+          operation: exitError.operation,
+        });
+      }
+
+      if (exitError) {
+        const failure = exitError as {
+          code?: string;
+          exitCode?: number;
+          message?: string;
+          operation?: string;
+        };
+        throw new HarmonyCliError(
+          failure.code || 'ERR_HARMONY_METRO_EXITED',
+          failure.message || 'Expo Metro failed before becoming ready.',
+          { cause: exitError, exitCode: failure.exitCode, operation: failure.operation }
+        );
+      }
+
+      if (exitResult) {
+        const diagnostics = formatDiagnostics(exitResult);
+        throw new HarmonyCliError(
+          'ERR_HARMONY_METRO_EXITED',
+          `Expo Metro exited before becoming ready with code ${exitResult.code}.${diagnostics ? `\n${diagnostics}` : ''}`,
+          { exitCode: exitResult.code || 1, operation: 'expo-metro' }
+        );
+      }
+
+      if (await probeMetroAsync(options.port) === 'metro') {
+        return {
+          owner: 'started',
+          port: options.port,
+          process: managed,
+          stop: () => managed.stop(),
+          async waitAsync() {
+            const result = await managed.completion;
+            if (managed.wasStopped()) return;
+            const interrupted = result.signal === 'SIGINT' || result.signal === 'SIGTERM';
+            if (result.code === 0 || interrupted) return;
+
+            const diagnostics = formatDiagnostics(result);
+            throw new HarmonyCliError(
+              'ERR_HARMONY_METRO_EXITED',
+              `Expo Metro exited with code ${result.code}.${diagnostics ? `\n${diagnostics}` : ''}`,
+              { exitCode: result.code || 1, operation: 'expo-metro' }
+            );
+          },
+        };
+      }
+
+      await delay(150);
+    }
+
+    throw new HarmonyCliError(
+      'ERR_HARMONY_METRO_TIMEOUT',
+      `Expo Metro did not become ready on port ${options.port} within ${timeoutMs}ms.`,
+      { operation: 'expo-metro' }
+    );
+  } catch (error) {
+    await managed.stop();
+
+    if (error instanceof HarmonyCliError) {
+      throw new HarmonyCliError(error.code, error.message, {
+        cause: error,
+        exitCode: error.exitCode,
+        operation: error.operation,
+      });
+    }
+
+    throw new HarmonyCliError(
+      error.code || 'ERR_HARMONY_METRO_EXITED',
+      error.message || 'Expo Metro failed while waiting for the server to become ready.',
+      { cause: error, exitCode: error.exitCode, operation: error.operation }
+    );
+  }
+}
+
+export {
+  requireExistingMetroAsync,
+  startExpoMetroAsync,
+};

package/src/run/options.ts

@@ -0,0 +1,71 @@
+import { HarmonyCliError } from '../errors';
+import { CommonOptions, parseArgs } from '../args';
+
+const RunOptions = {
+  ...CommonOptions,
+  'app-id': { type: 'string' },
+  'device': { type: 'string' },
+  'no-bundler': { type: 'boolean' },
+  'no-install': { type: 'boolean' },
+  'port': { type: 'string' },
+  'reset-cache': { type: 'boolean' },
+  'sync': { type: 'boolean' },
+  'variant': { type: 'string' },
+} as const;
+
+function parseRunArgs(argv: string[]) {
+  const { positionals, values } = parseArgs(RunOptions, argv);
+
+  if (positionals.length > 1) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unexpected run positional argument: ${positionals[1]}`, {
+      operation: 'parse-arguments',
+    });
+  }
+
+  const variant = values.variant || 'debug';
+
+  if (variant !== 'debug' && variant !== 'release') {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--variant must be debug or release.', {
+      operation: 'parse-arguments',
+    });
+  }
+
+  const port = values.port === undefined ? 8081 : Number(values.port);
+
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--port must be an integer between 1 and 65535.', {
+      operation: 'parse-arguments',
+    });
+  }
+
+  const appId = values['app-id'];
+
+  if (appId !== undefined && (!appId || appId.trim() !== appId || appId.includes('\0'))) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--app-id must be a non-empty Harmony bundle name.', {
+      operation: 'parse-arguments',
+    });
+  }
+
+  const device = values.device;
+
+  if (device !== undefined && (!device || device.trim() !== device || /[\0\r\n]/u.test(device))) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--device must be a non-empty HDC id or exact emulator name.', {
+      operation: 'parse-arguments',
+    });
+  }
+
+  return {
+    appId,
+    device,
+    help: Boolean(values.help),
+    noBundler: Boolean(values['no-bundler']),
+    noInstall: Boolean(values['no-install']),
+    port,
+    project: positionals[0],
+    resetCache: Boolean(values['reset-cache']),
+    sync: Boolean(values.sync),
+    variant: variant as 'debug' | 'release',
+  };
+}
+
+export { parseRunArgs };

package/src/run/run.ts

@@ -0,0 +1,302 @@
+import path from 'node:path';
+
+import {
+  configureMetroPortAsync,
+  installHapAsync,
+  launchAppAsync,
+  selectDeviceAsync,
+} from './devices';
+import { HarmonyCliError } from '../errors';
+import { exportEmbedAsync } from '../exportEmbed/export';
+import type { HarmonyExportManifest } from '../exportEmbed/manifest';
+import {
+  resolveHarmonyBuildPlanAsync,
+  resolveHarmonyEmulator,
+  resolveHarmonyToolchain,
+  type HarmonyBuildPlan,
+} from '../tools';
+import { installHarmonyDependenciesAsync } from './install';
+import {
+  requireExistingMetroAsync,
+  startExpoMetroAsync,
+  type MetroSession,
+} from './metro';
+import {
+  commitHarmonyNativeBuildCacheAsync,
+  prepareHarmonyNativeBuildCacheAsync,
+} from './cache';
+import { toPosixPath } from '../path';
+import { withHarmonyProjectLockAsync } from '../projectLock';
+import {
+  ensureGeneratedProjectAsync,
+  isNonEmptyRegularFile,
+  progress,
+  runCheckedAsync,
+  timed,
+} from '../buildHap/common';
+
+export interface HarmonyRunOptions {
+  appId?: string;
+  device?: string;
+  io?: Pick<Console, 'error' | 'log' | 'warn'>;
+  noBundler?: boolean;
+  noInstall?: boolean;
+  port?: number;
+  resetCache?: boolean;
+  sync?: boolean;
+  variant?: 'debug' | 'release';
+}
+
+export interface HarmonyRunResult {
+  bundleName: string;
+  device: { id: string; transport: string };
+  export: null | { assetCount: number; bundleSha256: string; sourceMapSha256: string };
+  hapPath: string;
+  installed: boolean;
+  launched: true;
+  metro: { owner: 'disabled' | 'existing' | 'started'; port: number };
+  ok: true;
+  schemaVersion: 1;
+  steps: Record<string, number>;
+  variant: 'debug' | 'release';
+}
+
+interface HarmonyRunSessionOptions extends HarmonyRunOptions {
+  /** Give a CLI-started Metro process ownership of the current terminal. */
+  interactiveBundler?: boolean;
+}
+
+interface HarmonyRunSession {
+  metro: MetroSession | {
+    owner: 'disabled';
+    port: number;
+    stop(): Promise<void>;
+    waitAsync(): Promise<void>;
+  };
+  result: HarmonyRunResult;
+}
+
+type NormalizedRunOptions = Required<Omit<HarmonyRunSessionOptions, 'appId' | 'device'>>
+  & Pick<HarmonyRunSessionOptions, 'appId' | 'device'>;
+
+const BundleName = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*){2,}$/u;
+
+function resolveRunIdentity(plan: HarmonyBuildPlan, options: NormalizedRunOptions) {
+  if (options.appId && !BundleName.test(options.appId)) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--app-id must contain at least three valid dot-separated segments.', { operation: 'resolve-run' });
+  }
+
+  if (options.appId && !options.noInstall && options.appId !== plan.bundleName) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_APP_ID_MISMATCH',
+      `--app-id can differ from the generated bundle name only with --no-install; expected ${plan.bundleName}.`,
+      { operation: 'resolve-run' }
+    );
+  }
+
+  return {
+    abilityName: plan.abilityName,
+    bundleName: options.appId || plan.bundleName,
+  };
+}
+
+async function runHarmonyUnlockedAsync(
+  projectRoot: string,
+  options: HarmonyRunSessionOptions = {}
+): Promise<HarmonyRunSession> {
+  const normalizedOptions: NormalizedRunOptions = {
+    appId: options.appId,
+    device: options.device,
+    interactiveBundler: Boolean(options.interactiveBundler),
+    io: options.io || console,
+    noBundler: Boolean(options.noBundler),
+    noInstall: Boolean(options.noInstall),
+    port: options.port || 8081,
+    resetCache: Boolean(options.resetCache),
+    sync: Boolean(options.sync),
+    variant: options.variant || 'debug',
+  };
+  const steps: Record<string, number> = {};
+
+  await ensureGeneratedProjectAsync(projectRoot, normalizedOptions, steps);
+
+  const plan = await timed(steps, 'buildPlan', () => resolveHarmonyBuildPlanAsync(
+    projectRoot,
+    { buildMode: normalizedOptions.variant }
+  ));
+  const identity = resolveRunIdentity(plan, normalizedOptions);
+  const toolchain = resolveHarmonyToolchain();
+
+  progress(normalizedOptions, 'Selecting a Harmony device or emulator');
+  const device = await timed(steps, 'device', () => selectDeviceAsync(
+    toolchain.hdc,
+    normalizedOptions.device,
+    {
+      cwd: plan.harmonyRoot,
+      emulator: resolveHarmonyEmulator(toolchain),
+      emulatorLogFile: path.join(projectRoot, '.expo', 'harmony', 'emulator.log'),
+      onProgress: message => progress(normalizedOptions, message),
+    }
+  ));
+
+  let exportManifest: HarmonyExportManifest | null = null;
+  if (normalizedOptions.variant === 'release') {
+    progress(normalizedOptions, 'Exporting the release Hermes bundle');
+    exportManifest = await timed(steps, 'export', () => exportEmbedAsync(
+      projectRoot,
+      { resetCache: normalizedOptions.resetCache, skipDoctor: true }
+    ));
+  } else {
+    steps.export = 0;
+  }
+
+  progress(normalizedOptions, 'Installing Harmony project dependencies');
+  await timed(steps, 'ohpm', () => installHarmonyDependenciesAsync(plan, toolchain));
+
+  let metro: HarmonyRunSession['metro'] = {
+    owner: 'disabled',
+    port: normalizedOptions.port,
+    stop: async () => {},
+    waitAsync: async () => {},
+  };
+  try {
+    progress(normalizedOptions, 'Checking Harmony native dependency cache');
+    const nativeBuildCache = await timed(steps, 'nativeCache', () => (
+      prepareHarmonyNativeBuildCacheAsync(projectRoot, plan)
+    ));
+
+    if (nativeBuildCache.changed) {
+      progress(normalizedOptions, 'Invalidated stale Harmony native build objects');
+    }
+
+    progress(normalizedOptions, `Building the ${normalizedOptions.variant} HAP`);
+    const buildEnv = {
+      ...process.env,
+      EXPO_HARMONY_NODE: process.env.EXPO_HARMONY_NODE || process.execPath,
+      EXPO_METRO_TARGET: 'harmony',
+      HERMES_V1_ENABLED: 'true',
+      ...(normalizedOptions.variant === 'release' ? { EXPO_HARMONY_BUNDLE_PREBUILT: '1' } : {}),
+      ...(toolchain.sdkHome && !process.env.DEVECO_SDK_HOME
+        ? { DEVECO_SDK_HOME: toolchain.sdkHome }
+        : {}),
+    };
+    await timed(steps, 'build', () => runCheckedAsync(toolchain.hvigor.command, [
+      ...toolchain.hvigor.args,
+      ...plan.hvigorArgs,
+    ], {
+      code: 'ERR_HARMONY_BUILD_FAILED',
+      cwd: plan.harmonyRoot,
+      env: buildEnv,
+      message: 'Hvigor build',
+      operation: 'hvigor-build',
+      timeoutMs: 15 * 60_000,
+    }));
+
+    if (!isNonEmptyRegularFile(plan.expectedHap)) {
+      throw new HarmonyCliError('ERR_HARMONY_HAP_MISSING', 'Hvigor completed without producing the expected non-empty regular HAP.', { operation: 'verify-hap' });
+    }
+
+    await timed(steps, 'nativeCacheCommit', () => commitHarmonyNativeBuildCacheAsync(nativeBuildCache));
+
+    if (normalizedOptions.variant === 'debug') {
+      progress(normalizedOptions, normalizedOptions.noBundler
+        ? 'Connecting to the existing Expo Metro server'
+        : 'Starting Expo Metro');
+      metro = await timed(steps, 'metro', () => normalizedOptions.noBundler
+        ? requireExistingMetroAsync(normalizedOptions.port)
+        : startExpoMetroAsync(projectRoot, {
+            interactive: normalizedOptions.interactiveBundler,
+            port: normalizedOptions.port,
+            resetCache: normalizedOptions.resetCache,
+          }));
+
+      await timed(steps, 'metroPort', () => configureMetroPortAsync(
+        toolchain.hdc,
+        device,
+        normalizedOptions.port,
+        { cwd: plan.harmonyRoot }
+      ));
+    } else {
+      steps.metro = 0;
+      steps.metroPort = 0;
+    }
+
+    if (normalizedOptions.noInstall) {
+      steps.install = 0;
+    } else {
+      progress(normalizedOptions, `Installing the HAP on ${device.id}`);
+      await timed(steps, 'install', () => installHapAsync(
+        toolchain.hdc,
+        device,
+        plan.expectedHap,
+        { cwd: plan.harmonyRoot }
+      ));
+    }
+
+    progress(normalizedOptions, `Launching ${identity.bundleName}`);
+    await timed(steps, 'launch', () => launchAppAsync(
+      toolchain.hdc,
+      device,
+      identity.bundleName,
+      identity.abilityName,
+      { cwd: plan.harmonyRoot }
+    ));
+
+    const result: HarmonyRunResult = {
+      bundleName: identity.bundleName,
+      device: {
+        id: device.id,
+        transport: device.transport,
+      },
+      export: exportManifest
+        ? {
+            assetCount: exportManifest.assets.length,
+            bundleSha256: exportManifest.bundle.sha256,
+            sourceMapSha256: exportManifest.sourceMap.sha256,
+          }
+        : null,
+      hapPath: toPosixPath(path.relative(projectRoot, plan.expectedHap)),
+      installed: !normalizedOptions.noInstall,
+      launched: true,
+      metro: {
+        owner: metro.owner,
+        port: metro.port,
+      },
+      ok: true,
+      schemaVersion: 1,
+      steps,
+      variant: normalizedOptions.variant,
+    };
+
+    return { metro, result };
+  } catch (error) {
+    await metro.stop();
+    throw error;
+  }
+}
+
+async function runHarmonySessionAsync(
+  projectRoot: string,
+  options: HarmonyRunSessionOptions = {}
+): Promise<HarmonyRunSession> {
+  return withHarmonyProjectLockAsync(
+    projectRoot,
+    'run',
+    () => runHarmonyUnlockedAsync(projectRoot, options)
+  );
+}
+
+async function runHarmonyAsync(
+  projectRoot: string,
+  options: HarmonyRunOptions = {}
+): Promise<HarmonyRunResult> {
+  const session = await runHarmonySessionAsync(projectRoot, options);
+
+  try {
+    return session.result;
+  } finally {
+    await session.metro.stop();
+  }
+}
+
+export { runHarmonyAsync, runHarmonySessionAsync };

package/src/start/options.ts

@@ -0,0 +1,36 @@
+import { CommonOptions, parseArgs } from '../args';
+import { HarmonyCliError } from '../errors';
+
+const StartOptions = {
+  ...CommonOptions,
+  'clear': { short: 'c', type: 'boolean' },
+  'port': { type: 'string' },
+  'reset-cache': { type: 'boolean' },
+} as const;
+
+function parseStartArgs(argv: string[]) {
+  const { positionals, values } = parseArgs(StartOptions, argv);
+
+  if (positionals.length > 1) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unexpected start positional argument: ${positionals[1]}`, {
+      operation: 'parse-arguments',
+    });
+  }
+
+  const port = values.port === undefined ? 8081 : Number(values.port);
+
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--port must be an integer between 1 and 65535.', {
+      operation: 'parse-arguments',
+    });
+  }
+
+  return {
+    help: Boolean(values.help),
+    port,
+    project: positionals[0],
+    resetCache: Boolean(values['reset-cache'] || values.clear),
+  };
+}
+
+export { parseStartArgs };