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

package/src/cli.ts

@@ -1,242 +1,44 @@
-import path from 'node:path';
-
-import { parseBuildArgs } from './buildHap/options';
-import { parseDoctorArgs } from './doctor/options';
+import type { Command } from './command';
 import { HarmonyCliError } from './errors';
-import { parseExportEmbedArgs } from './exportEmbed/options';
-import { parseModulesArgs } from './modules/options';
-import { parsePrebuildArgs } from './prebuild/options';
-import { resolveProject } from './project';
-import { withHarmonyProjectLockAsync } from './projectLock';
-import { parseRunArgs } from './run/options';
-import { parseStartArgs } from './start/options';
-
-const Help = `Usage: expo-harmony <command> [project] [options]
-
-Commands:
-  start                 Start Expo Metro for Harmony development
-  prebuild              Generate the Harmony native project with Expo CNG
-  prebuild --clean      Safely recreate the managed Harmony directory
-  prebuild --check      Compare generated desired state without project writes
-  build                 Build a HAP without selecting or contacting a device
-  doctor                Validate config, versions, Metro, RNOH, SDK, and signing
-  modules list          List native module candidates and their discovery source
-  modules inspect       Resolve Harmony metadata (--package narrows the result)
-  modules verify        Validate module config, registration conflicts and safe paths
-  export:embed          Export validated Hermes bytecode, assets, and a source map
-  run                   Build, install, and launch the Harmony app
-
-Options:
-  --no-install          Skip dependency install (prebuild) or HAP install (run)
-  --npm|--yarn|--pnpm|--bun
-                        Select the package manager used by prebuild dependency install
-  --skip-dependency-update <packages>
-                        Preserve comma-separated dependency versions
-  --device <id-or-name> Select an HDC target or start a local emulator by name
-  --variant <mode>      Build debug or release (default: debug)
-  --no-bundler          Use an already-running Expo Metro server
-  --app-id <bundleName>
-                        Launch another installed app (requires --no-install when different)
-  --port <number>       Metro and device reverse port (default: 8081)
-  --sync                Re-run prebuild before building
-  --check               Validate an existing export without writing
-  --reset-cache         Reset Metro while exporting or starting
-  -c, --clear           Alias for --reset-cache (start)
-  -h, --help            Show this help
-`;
+import { Help } from './help';
+import type { Log } from './log';
+
+const commands: Record<string, () => Promise<{ command: Command }>> = {
+  'runtime': () => import('./runtime/index.js'),
+  'start': () => import('./start/index.js'),
+  'prebuild': () => import('./prebuild/index.js'),
+  'build': () => import('./buildHap/index.js'),
+  'doctor': () => import('./doctor/index.js'),
+  'modules': () => import('./modules/index.js'),
+  'export': () => import('./updates/index.js'),
+  'export:embed': () => import('./exportEmbed/index.js'),
+  'run': () => import('./run/index.js'),
+};
+
+export async function runAsync(argv: string[] = process.argv.slice(2), io: Log = console): Promise<number> {
+  process.env.EXPO_HARMONY = '1';
+  process.env.EXPO_METRO_TARGET = 'harmony';
 
-type Invocation = { command: 'help' }
-  | { command: 'build'; parsed: ReturnType<typeof parseBuildArgs>; projectRoot: string }
-  | { command: 'doctor'; parsed: ReturnType<typeof parseDoctorArgs>; projectRoot: string }
-  | { command: 'export:embed'; parsed: ReturnType<typeof parseExportEmbedArgs>; projectRoot: string }
-  | { command: 'modules'; parsed: ReturnType<typeof parseModulesArgs>; projectRoot: string }
-  | { command: 'prebuild'; parsed: ReturnType<typeof parsePrebuildArgs>; projectRoot: string }
-  | { command: 'run'; parsed: ReturnType<typeof parseRunArgs>; projectRoot: string }
-  | { command: 'start'; parsed: ReturnType<typeof parseStartArgs>; projectRoot: string };
-
-function parseInvocation(argv: string[]): Invocation {
   if (argv.length === 0 || (argv.length === 1 && ['--help', '-h'].includes(argv[0]))) {
-    return { command: 'help' };
-  }
-
-  const command = argv[0] as Exclude<Invocation['command'], 'help'>;
-  if (!['build', 'prebuild', 'doctor', 'export:embed', 'modules', 'run', 'start'].includes(command)) {
-    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unknown command: ${command}`, {
-      operation: 'parse-arguments',
-    });
-  }
-
-  const parsed = command === 'build'
-    ? parseBuildArgs(argv.slice(1))
-    : command === 'prebuild'
-      ? parsePrebuildArgs(argv.slice(1), { allowProject: true })
-      : command === 'doctor'
-        ? parseDoctorArgs(argv.slice(1))
-        : command === 'export:embed'
-          ? parseExportEmbedArgs(argv.slice(1))
-          : command === 'modules'
-            ? parseModulesArgs(argv.slice(1))
-            : command === 'start'
-              ? parseStartArgs(argv.slice(1))
-              : parseRunArgs(argv.slice(1));
-  if (parsed.help) return { command: 'help' };
-
-  const projectRoot = resolveProject(parsed.project ? path.resolve(parsed.project) : process.cwd());
-
-  return { command, parsed, projectRoot } as Invocation;
-}
-
-async function runAsync(
-  argv: string[] = process.argv.slice(2),
-  io: Pick<Console, 'error' | 'log' | 'warn'> = console
-): Promise<number> {
-  const invocation = parseInvocation(argv);
-  if (invocation.command === 'help') {
     io.log(Help);
     return 0;
   }
 
-  if (invocation.command === 'start') {
-    const { startExpoMetroAsync } = await import('./run/metro.js');
-    const metro = await startExpoMetroAsync(invocation.projectRoot, {
-      ...invocation.parsed,
-      interactive: true,
-    });
-
-    try {
-      if (metro.owner === 'existing') {
-        io.log(`Expo Metro is already running on port ${metro.port}.`);
-        if (invocation.parsed.resetCache) {
-          io.warn('Stop the existing Metro server and run this command again to reset its cache.');
-        }
-      } else {
-        io.log('\n› Logs for your project will appear below. Press Ctrl+C to exit.');
-        await metro.waitAsync();
-      }
-
-      return 0;
-    } finally {
-      await metro.stop();
-    }
+  const name = argv[0];
+  if (!Object.hasOwn(commands, name)) {
+    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unknown command: ${name}`, { operation: 'parse-arguments' });
   }
 
-  if (invocation.command === 'doctor') {
-    const { doctorAsync, formatDoctor } = await import('./doctor/doctor.js');
-    const result = await doctorAsync(invocation.projectRoot, { requireBuildTools: true });
-
-    io.log(formatDoctor(result));
-
-    return result.ok ? 0 : 1;
-  }
-
-  if (invocation.command === 'build') {
-    const { buildHarmonyAsync } = await import('./buildHap/build.js');
-    const result = await buildHarmonyAsync(invocation.projectRoot, {
-      ...invocation.parsed,
-      io,
-    });
-
-    io.log(`Built ${result.variant} HAP at ${result.hapPath}; no device actions were performed.`);
+  const { command } = await commands[name]();
 
-    return 0;
-  }
-
-  if (invocation.command === 'export:embed') {
-    const { exportEmbedAsync } = await import('./exportEmbed/export.js');
-    const result = await exportEmbedAsync(invocation.projectRoot, invocation.parsed);
-
-    if (invocation.parsed.check) io.log('Harmony export bundle, assets, and source map are valid.');
-    else io.log(`Exported Hermes bytecode ${result.bundle.path} with ${result.assets.length} asset file(s).`);
-
-    return 0;
-  }
-
-  if (invocation.command === 'modules') {
-    const { formatModulesResult, runModulesCommandAsync } = await import('./modules/modules.js');
-    const result = await runModulesCommandAsync(invocation.projectRoot, invocation.parsed);
-
-    io.log(formatModulesResult(result));
-    return result.ok ? 0 : 1;
-  }
-
-  if (invocation.command === 'run') {
-    const { runHarmonySessionAsync } = await import('./run/run.js');
-
-    const session = await runHarmonySessionAsync(invocation.projectRoot, {
-      ...invocation.parsed,
-      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;
-  }
-
-  const { check, clean, passthrough } = invocation.parsed;
-
-  if (check && passthrough.length) {
-    throw new HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--check cannot be combined with mutating prebuild options.');
-  }
-
-  return withHarmonyProjectLockAsync(
-    invocation.projectRoot,
-    check ? 'prebuild-check' : 'prebuild',
-    async () => {
-      if (clean) {
-        const { assertSafeCleanTarget } = await import('./prebuild/clean.js');
-        await assertSafeCleanTarget(invocation.projectRoot);
-      }
-
-      const { doctorAsync, formatDoctor } = await import('./doctor/doctor.js');
-      const doctor = await doctorAsync(invocation.projectRoot, {
-        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('./prebuild/check.js');
-        const result = await checkAsync(invocation.projectRoot);
-
-        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/prebuild.js');
-      await prebuildParsedAsync(invocation.projectRoot, passthrough);
-
-      return 0;
-    });
+  return command(argv.slice(1), io);
 }
 
-async function main(argv = process.argv.slice(2)) {
+export async function mainAsync(argv: string[] = process.argv.slice(2)): Promise<void> {
   try {
-    const code = await runAsync(argv);
-
-    process.exitCode = code;
+    process.exitCode = await runAsync(argv);
   } catch (error) {
-    const code = error.code || 'ERR_HARMONY_UNKNOWN';
-
-    console.error(`[${code}] ${error.message}`);
-
+    console.error(`[${error.code || 'ERR_HARMONY_UNKNOWN'}] ${error.message}`);
     process.exitCode = error.exitCode || 1;
   }
 }
-
-export { main, runAsync };

package/src/command.ts

@@ -0,0 +1,24 @@
+import path from 'node:path';
+
+import { Help } from './help';
+import type { Log } from './log';
+import { resolveProject } from './project';
+
+export type Command = (argv: string[], io: Log) => Promise<number>;
+
+export function parseCommandArgs<T extends { help: boolean; project?: string }>(
+  parse: (argv: string[]) => T,
+  argv: string[],
+  io: Log
+): { options: T; projectRoot: string } | null {
+  const options = parse(argv);
+  if (options.help) {
+    io.log(Help);
+    return null;
+  }
+
+  return {
+    options,
+    projectRoot: resolveProject(options.project ? path.resolve(options.project) : process.cwd()),
+  };
+}

package/src/development/manifest.ts

@@ -0,0 +1,127 @@
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+
+import { HarmonyCliError } from '../errors';
+import { resolveExpoCli } from '../expo';
+import { resolveHarmonyBuildPlanAsync } from '../native/project';
+import { resolveRuntimeRequirementsAsync } from '../runtime/contract';
+import { canonicalHarmonyManifestURL, createHarmonyLaunchLink, HarmonyManifestPath } from './protocol';
+
+async function createManifestResponseAsync(middleware, options, require: NodeRequire) {
+  const { ExpoGoManifestHandlerMiddleware: Manifest, ResponseContentType: Types } = require('./build/src/start/server/middleware/ExpoGoManifestHandlerMiddleware');
+  const { getCodeSigningInfoAsync, signManifestString } = require('./build/src/utils/codesigning');
+  const { serializeDictionary } = require('structured-headers');
+  const { exp, expoGoConfig, bundleUrl, hostUri } = await middleware._resolveProjectSettingsAsync(options);
+  const requirements = await resolveRuntimeRequirementsAsync(middleware.projectRoot);
+  const signing = await getCodeSigningInfoAsync(exp, options.expectSignature, middleware.options.privateKeyPath);
+  const scope = await Manifest.getScopeKeyAsync({ slug: exp.slug, codeSigningInfo: signing });
+
+  const bundle = new URL(bundleUrl);
+  bundle.searchParams.set('transform.engine', 'hermes');
+  bundle.searchParams.set('transform.bytecode', '0');
+  bundle.searchParams.set('unstable_transformProfile', 'hermes-stable');
+  bundle.searchParams.set('lazy', 'false');
+
+  const name = exp.harmony?.bundleName || (await resolveHarmonyBuildPlanAsync(middleware.projectRoot)).bundleName;
+  const id = exp.extra?.eas?.projectId;
+  const address = canonicalHarmonyManifestURL(`${bundle.origin}${options.harmonyManifestPath ?? `${HarmonyManifestPath}?platform=harmony`}`);
+  const manifest = JSON.stringify({
+    id: crypto.randomUUID(),
+    createdAt: new Date().toISOString(),
+    runtimeVersion: requirements.runtimeVersion,
+    launchAsset: { key: 'bundle', contentType: 'application/javascript', url: bundle.toString() },
+    assets: [],
+    metadata: {},
+    extra: {
+      eas: { projectId: id ?? undefined },
+      expoClient: { ...exp, hostUri },
+      expoGo: expoGoConfig,
+      scopeKey: scope,
+      harmony: {
+        projectId: id || `@${exp.owner || 'anonymous'}/${exp.slug}/${name}`,
+        manifestUrl: address,
+        launchLink: createHarmonyLaunchLink(address),
+        requirements,
+      },
+    },
+  });
+  const signature = signing
+    ? serializeDictionary(new Map(Object.entries({
+        keyid: signing.keyId,
+        sig: signManifestString(manifest, signing),
+        alg: 'rsa-v1_5-sha256',
+      }).map(([key, value]) => [key, [value, new Map()]])))
+    : undefined;
+
+  if (options.responseContentType === Types.MULTIPART_MIXED) {
+    return middleware.encodeFormDataAsync({
+      stringifiedManifest: manifest,
+      manifestPartHeaders: signature ? { 'expo-signature': signature } : undefined,
+      certificateChainBody: signing?.certificateChainForResponse.join('\n') ?? null,
+    });
+  }
+
+  const headers = middleware.getDefaultResponseHeaders();
+  headers.set('content-type', Manifest.getContentTypeForResponseContentType(options.responseContentType));
+  if (signature) headers.set('expo-signature', signature);
+
+  return new Response(manifest, { headers });
+}
+
+export function installHarmonyManifest(root: string) {
+  const expo = createRequire(resolveExpoCli(root).cliPath);
+  const require = createRequire(expo.resolve('@expo/cli/package.json'));
+  const version = require('./package.json').version;
+  if (version !== '55.0.32') {
+    throw new HarmonyCliError('ERR_HARMONY_EXPO_CLI_UNSUPPORTED', `The Harmony manifest adapter requires @expo/cli 55.0.32; found ${version}.`, { operation: 'development-manifest' });
+  }
+
+  const { BundlerDevServer } = require('./build/src/start/server/BundlerDevServer');
+  const { parsePlatformHeader } = require('./build/src/start/server/middleware/resolvePlatform');
+  const create = BundlerDevServer.prototype.getManifestMiddlewareAsync;
+
+  // Reuse Expo's terminal QR renderer and dev-session publishing with our
+  // registered link, rather than emitting a second, incompatible QR code.
+  const nativeURL = BundlerDevServer.prototype.getNativeRuntimeUrl;
+  const redirectURL = BundlerDevServer.prototype.getRedirectUrl;
+  BundlerDevServer.prototype.getNativeRuntimeUrl = function (options = {}) {
+    const address = this.getUrlCreator().constructUrl({ ...options, scheme: 'http' });
+    if (!address) return nativeURL.call(this, options);
+    const manifest = new URL(HarmonyManifestPath, address);
+    manifest.searchParams.set('platform', 'harmony');
+    return createHarmonyLaunchLink(manifest.toString());
+  };
+  BundlerDevServer.prototype.getRedirectUrl = function (platform = null) {
+    return platform === null || platform === 'harmony'
+      ? this.getNativeRuntimeUrl()
+      : redirectURL.call(this, platform);
+  };
+
+  // Expo installs the manifest before Metro's enhancer; adapt only the created instance.
+  BundlerDevServer.prototype.getManifestMiddlewareAsync = async function (this: object, ...args) {
+    const middleware = await create.apply(this, args);
+    const parse = middleware.getParsedHeaders;
+    const respond = middleware._getManifestResponseAsync;
+
+    middleware.getParsedHeaders = (request) => {
+      if (parsePlatformHeader(request) !== 'harmony') return parse.call(middleware, request);
+
+      // Bypass only the upstream platform assertion without changing the actual request.
+      const url = new URL(request.url, 'http://localhost');
+      url.searchParams.delete('platform');
+      url.searchParams.append('platform', 'harmony');
+      const manifest = new URL(canonicalHarmonyManifestURL(url.toString()));
+      const harmonyManifestPath = manifest.pathname + manifest.search;
+      url.searchParams.set('platform', 'ios');
+      const copy = Object.create(request);
+      copy.url = url.pathname + url.search;
+
+      return { ...parse.call(middleware, copy), platform: 'harmony', harmonyManifestPath };
+    };
+    middleware._getManifestResponseAsync = options => options.platform === 'harmony'
+      ? createManifestResponseAsync(middleware, options, require)
+      : respond.call(middleware, options);
+
+    return middleware;
+  };
+}

package/src/development/protocol.ts

@@ -0,0 +1,42 @@
+import { HarmonyCliError } from '../errors';
+
+export const HarmonyManifestPath = '/manifest';
+
+export function canonicalHarmonyManifestURL(value: string): string {
+  let url: URL;
+
+  try {
+    url = new URL(value);
+    decodeURIComponent(url.search);
+  } catch (cause) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_MANIFEST_URL',
+      'Expected an absolute HTTP(S) Harmony manifest URL.',
+      { cause, operation: 'development-manifest' }
+    );
+  }
+
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash
+    || !['/', HarmonyManifestPath, '/index.exp'].includes(url.pathname)
+    || url.searchParams.getAll('platform').length !== 1 || url.searchParams.get('platform') !== 'harmony') {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_MANIFEST_URL',
+      'Expected an HTTP(S) Expo manifest URL with platform=harmony and without credentials or a fragment.',
+      { operation: 'development-manifest' }
+    );
+  }
+
+  url.pathname = HarmonyManifestPath;
+  // Keep all other query values (including repetitions) in order. Platform has
+  // one canonical position, and URLSearchParams normalizes equivalent encoding.
+  url.searchParams.delete('platform');
+  url.searchParams.append('platform', 'harmony');
+  return url.toString();
+}
+
+export function createHarmonyLaunchLink(manifest: string): string {
+  const url = new URL('expo-harmony://open');
+  url.searchParams.set('url', canonicalHarmonyManifestURL(manifest));
+
+  return url.toString();
+}

package/src/development/session.ts

@@ -0,0 +1,83 @@
+import http from 'node:http';
+import os from 'node:os';
+
+import type { HarmonyDevelopmentManifest } from '@expo-harmony/expo-modules-autolinking/runtime';
+
+import { HarmonyCliError } from '../errors';
+import { readProjectRuntimeAsync } from '../runtime/config';
+import { createHarmonyLaunchLink, HarmonyManifestPath } from './protocol';
+
+export async function readDevelopmentSessionAsync(root: string, port: number, hostname?: string) {
+  const project = await readProjectRuntimeAsync(root);
+  const { config } = project;
+
+  const host = hostname || process.env.REACT_NATIVE_PACKAGER_HOSTNAME
+    || Object.values(os.networkInterfaces()).flat().find(item => item?.family === 'IPv4' && !item.internal)?.address
+    || '127.0.0.1';
+  if (!/^[A-Za-z0-9.-]+$/.test(host)) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_MANIFEST_HOST',
+      'Harmony development requires an HTTP LAN hostname or IPv4 address.',
+      { operation: 'development-manifest' }
+    );
+  }
+
+  const manifest = await new Promise<HarmonyDevelopmentManifest>((resolve, reject) => {
+    const request = http.get({
+      host: '127.0.0.1',
+      port,
+      path: `${HarmonyManifestPath}?platform=harmony`,
+      headers: { 'host': `${host}:${port}`, 'accept': 'application/json', 'expo-platform': 'harmony', 'expo-protocol-version': '0' },
+    }, (response) => {
+      let body = '';
+
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => {
+        body += chunk;
+
+        if (body.length > 2 * 1024 * 1024) request.destroy(new Error('Harmony manifest exceeded 2 MB.'));
+      });
+      response.on('error', reject);
+      response.on('end', () => {
+        try {
+          const value = JSON.parse(body);
+          if (response.statusCode !== 200 || response.headers['expo-protocol-version'] !== '0'
+            || !response.headers['content-type']?.startsWith('application/json')) {
+            reject(new Error(value.error?.message || 'Metro did not return an Expo development manifest with protocol version 0.'));
+
+            return;
+          }
+
+          resolve(value);
+        } catch (cause) {
+          reject(new Error('Metro did not return a valid Harmony manifest.', { cause }));
+        }
+      });
+    });
+
+    request.setTimeout(60_000, () => request.destroy(new Error('Harmony manifest request timed out.')));
+    request.on('error', reject);
+  }).catch((cause) => {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_METRO_MANIFEST',
+      `Cannot use this Metro server: ${cause.message}`,
+      { cause, operation: 'development-manifest' }
+    );
+  });
+
+  const identity = config.extra?.eas?.projectId || `@${config.owner || 'anonymous'}/${config.slug}/${project.bundleName}`;
+  if (manifest.extra?.harmony?.projectId !== identity
+    || manifest.runtimeVersion !== project.runtimeVersion) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_METRO_PROJECT',
+      'This Metro server belongs to another Harmony project.',
+      { operation: 'development-manifest' }
+    );
+  }
+
+  return {
+    manifestUrl: manifest.extra.harmony.manifestUrl,
+    launchLink: createHarmonyLaunchLink(manifest.extra.harmony.manifestUrl),
+    bundleUrl: manifest.launchAsset.url,
+  };
+}