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

package/src/buildHap/build.ts

@@ -1,39 +1,16 @@
-import path from 'node:path';
-
-import { HarmonyCliError } from '../errors';
-import { exportEmbedAsync } from '../exportEmbed/export';
-import type { HarmonyExportManifest } from '../exportEmbed/manifest';
-import { toPosixPath } from '../path';
 import { withHarmonyProjectLockAsync } from '../projectLock';
-import {
-  commitHarmonyNativeBuildCacheAsync,
-  prepareHarmonyNativeBuildCacheAsync,
-} from '../run/cache';
-import { installHarmonyDependenciesAsync } from '../run/install';
-import {
-  resolveHarmonyBuildPlanAsync,
-  resolveHarmonyToolchain,
-} from '../tools';
-import {
-  ensureGeneratedProjectAsync,
-  isNonEmptyRegularFile,
-  progress,
-  runCheckedAsync,
-  timed,
-} from './common';
+import { buildNativeAsync, type NativeBuildResult } from '../native/build';
+import { prepareNativeProjectAsync } from '../native/prepareProject';
+import { resolveHarmonyToolchain } from '../native/toolchain';
 
 export interface HarmonyBuildOptions {
   io?: Pick<Console, 'error' | 'log' | 'warn'>;
-  /** @internal For release verification after a successful isolated prebuild check. */
-  skipGeneratedProjectCheck?: boolean;
   sync?: boolean;
   variant?: 'debug' | 'release';
 }
 
-export interface HarmonyBuildResult {
+export interface HarmonyBuildResult extends NativeBuildResult {
   bundleName: string;
-  export: null | { assetCount: number; bundleSha256: string; sourceMapSha256: string };
-  hapPath: string;
   headless: true;
   installed: false;
   launched: false;
@@ -48,13 +25,12 @@ type NormalizedBuildOptions = Required<HarmonyBuildOptions> & {
 };
 
 async function buildHarmonyUnlockedAsync(
-  projectRoot: string,
+  root: string,
   options: HarmonyBuildOptions = {}
 ): Promise<HarmonyBuildResult> {
-  const normalizedOptions: NormalizedBuildOptions = {
+  const settings: NormalizedBuildOptions = {
     io: options.io || console,
     requireDeviceTools: false,
-    skipGeneratedProjectCheck: Boolean(options.skipGeneratedProjectCheck),
     sync: Boolean(options.sync),
     variant: options.variant || 'debug',
   };
@@ -66,98 +42,30 @@ async function buildHarmonyUnlockedAsync(
     metroPort: 0,
   };
 
-  await ensureGeneratedProjectAsync(projectRoot, normalizedOptions, steps);
-
-  const plan = await timed(steps, 'buildPlan', () => resolveHarmonyBuildPlanAsync(
-    projectRoot,
-    { buildMode: normalizedOptions.variant }
-  ));
-  const toolchain = resolveHarmonyToolchain();
-
-  let exportManifest: HarmonyExportManifest | null = null;
-  if (normalizedOptions.variant === 'release') {
-    progress(normalizedOptions, 'Exporting the release Hermes bundle');
-    exportManifest = await timed(steps, 'export', () => exportEmbedAsync(
-      projectRoot,
-      { skipDoctor: true }
-    ));
-  } else {
-    steps.export = 0;
-  }
-
-  progress(normalizedOptions, 'Installing Harmony project dependencies');
-  await timed(steps, 'ohpm', () => installHarmonyDependenciesAsync(plan, toolchain));
-
-  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 without a device`);
-  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));
+  const plan = await prepareNativeProjectAsync(root, settings, steps);
+  const built = await buildNativeAsync(root, plan, resolveHarmonyToolchain(), settings, steps);
 
   return {
     bundleName: plan.bundleName,
-    export: exportManifest
-      ? {
-          assetCount: exportManifest.assets.length,
-          bundleSha256: exportManifest.bundle.sha256,
-          sourceMapSha256: exportManifest.sourceMap.sha256,
-        }
-      : null,
-    hapPath: toPosixPath(path.relative(projectRoot, plan.expectedHap)),
+    ...built,
     headless: true,
     installed: false,
     launched: false,
     ok: true,
     schemaVersion: 1,
     steps,
-    variant: normalizedOptions.variant,
+    variant: settings.variant,
   };
 }
 
 async function buildHarmonyAsync(
-  projectRoot: string,
+  root: string,
   options: HarmonyBuildOptions = {}
 ): Promise<HarmonyBuildResult> {
   return withHarmonyProjectLockAsync(
-    projectRoot,
+    root,
     'build',
-    () => buildHarmonyUnlockedAsync(projectRoot, options)
+    () => buildHarmonyUnlockedAsync(root, options)
   );
 }
 

package/src/buildHap/index.ts

@@ -0,0 +1,19 @@
+import { parseCommandArgs, type Command } from '../command';
+import { parseBuildArgs } from './options';
+
+export const command: Command = async (argv, io) => {
+  const args = parseCommandArgs(parseBuildArgs, argv, io);
+  if (!args) return 0;
+
+  const { projectRoot: root, options } = args;
+  const { buildHarmonyAsync } = await import('./build.js');
+
+  const result = await buildHarmonyAsync(root, {
+    ...options,
+    io,
+  });
+
+  io.log(`Built ${result.variant} HAP at ${result.hapPath}; no device actions were performed.`);
+
+  return 0;
+};

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,106 @@
+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 { 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 = `${bundle.origin}${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;
+
+  // 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.set('platform', 'ios');
+      const copy = Object.create(request);
+      copy.url = url.pathname + url.search;
+
+      return { ...parse.call(middleware, copy), platform: 'harmony' };
+    };
+    middleware._getManifestResponseAsync = options => options.platform === 'harmony'
+      ? createManifestResponseAsync(middleware, options, require)
+      : respond.call(middleware, options);
+
+    return middleware;
+  };
+}

package/src/development/protocol.ts

@@ -0,0 +1,37 @@
+import { HarmonyCliError } from '../errors';
+
+export const HarmonyManifestPath = '/manifest';
+
+function validateManifestUrl(value: string): URL {
+  let url: URL;
+
+  try {
+    url = new URL(value);
+  } 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
+    || !['/', '/manifest', '/index.exp'].includes(url.pathname) || url.searchParams.toString() !== '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' }
+    );
+  }
+
+  return url;
+}
+
+export function createHarmonyLaunchLink(manifest: string): string {
+  validateManifestUrl(manifest);
+
+  const url = new URL('expo-harmony://open');
+  url.searchParams.set('url', manifest);
+
+  return url.toString();
+}