@expo-harmony/cli 55.0.26-harmony.12 → 55.0.26-harmony.13

package/README.md

@@ -49,6 +49,7 @@ npx expo-harmony run ./my-app --device <hdc-target>
 ```sh
 npx expo-harmony start
 npx expo-harmony start --port 8082
+npx expo-harmony start --host 192.168.1.100
 npx expo-harmony start --clear
 ```
 
@@ -56,6 +57,8 @@ npx expo-harmony start --clear
 
 可以用 `--port <number>` 指定端口，默认是 `8081`。`--reset-cache` 清除 Metro 缓存，也可以写成 `--clear` 或 `-c`。
 
+多网卡环境下，可以用 `--host <IP 或主机名>` 指定设备连接的电脑地址，例如 `npx expo-harmony start --host 192.168.1.100 --port 8082`。地址应是设备能访问的网卡 IPv4 或主机名，不带协议和端口。
+
 端口上已有 Metro 时，命令会提示并退出，已有服务继续运行。要清除它的缓存，需要先停止服务，再带缓存选项启动。端口被其他进程占用时，命令会报错。
 
 要构建并启动应用，在另一个终端运行 `npx expo-harmony run --no-bundler`。如果指定了端口，两个命令应使用相同的 `--port`。
@@ -113,7 +116,7 @@ npx expo-harmony doctor
 - HDC、OHPM、Hvigor 是否可用
 - 原生工程的 Hvigor 文件和自动链接配置
 
-有 `error` 级别的问题时，命令以非零退出码结束。CNG 工程未配置外部签名文件时会显示警告，仍可构建未签名的 HAP。证书是否有效，需要在构建时由 Hvigor 检查。
+有 `error` 级别的问题时，命令以非零退出码结束。CNG 工程未配置外部签名文件时会显示警告，仍可构建未签名的 HAP。首次生成、删除 `harmony/` 后重新生成或使用 `prebuild --clean` 时，若配置的签名文件或材料缺失、无效，会给出警告并按未签名生成；签名配置可用时仍会正常应用。对已有工程执行普通 prebuild 或 doctor 时，签名文件缺失或无效会被视为 `error`。证书是否有效，需要在构建时由 Hvigor 检查。
 
 ## Modules
 
@@ -161,6 +164,7 @@ npx expo-harmony run \
 - `--variant debug|release`：构建模式，默认 `debug`。Release 将 JS Bundle 和资源打包进应用，不启动 Metro。
 - `--device <id-or-name>`：选择已连接的 HDC 设备，或按完整名称启动本地模拟器，例如 `--device "Pura 90 Pro"`。有多个候选目标时必须指定。
 - `--port <number>`：电脑上的 Metro 端口，默认 `8081`。Debug 模式下会配置设备端口映射，让应用连接到这个端口。
+- `--host <IP 或主机名>`：指定本次启动的 Metro 对外公布的地址，与 `start --host` 相同；使用 `--no-bundler` 时应在启动 Metro 的命令中指定。
 - `--no-bundler`：使用已运行的 Metro，找不到服务时报错。不加此选项时，会启动 Metro，或复用端口上已有的 Metro。
 - `--reset-cache`：Debug 模式下启动 Metro 时清除 Metro 缓存；Release 模式下清除生产导出缓存。
 - `--no-install`：仍会构建 HAP，但跳过安装，启动设备上已有的应用。
@@ -183,6 +187,7 @@ CLI 先读取环境变量指定的工具路径，再查找 DevEco Studio 的安
 
 | 环境变量 | 用途 |
 | --- | --- |
+| `REACT_NATIVE_PACKAGER_HOSTNAME` | 指定 Metro 对外公布的 IP 或主机名，`--host` 优先 |
 | `HARMONY_HDC` | 指定 HDC 路径 |
 | `HARMONY_EMULATOR` | 指定模拟器命令行工具路径 |
 | `HARMONY_OHPM` | 指定 OHPM 路径 |

package/build/development/host.d.ts

@@ -0,0 +1,2 @@
+export declare function parseHostOption(host?: string): string | undefined;
+export declare function resolveDevelopmentHostAsync(root: string, hostname?: string): Promise<string>;

package/build/development/host.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseHostOption = parseHostOption;
+exports.resolveDevelopmentHostAsync = resolveDevelopmentHostAsync;
+const node_module_1 = require("node:module");
+const node_os_1 = __importDefault(require("node:os"));
+const errors_1 = require("../errors");
+const expo_1 = require("../expo");
+function parseHostOption(host) {
+    if (host !== undefined && !/^[A-Za-z0-9.-]+$/.test(host)) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--host must be a hostname or IPv4 address without a port or scheme.', { operation: 'parse-arguments' });
+    }
+    return host;
+}
+function interfacePriority(name, info) {
+    // Interface names alone cannot identify every virtual adapter (especially on Windows).
+    const virtual = /^(utun|tun|tap|wg|ppp|ipsec|vmnet|vboxnet|virbr|docker|br-|bridge\d|veth|tailscale|zt)|virtual|vmware|vpn/i.test(name)
+        || /^(00:00:00:00:00:00|00:05:69:|00:0c:29:|00:1c:14:|00:50:56:|08:00:27:|00:15:5d:)/i.test(info.mac)
+        || /^198\.(18|19)\./.test(info.address);
+    return Number(virtual) + (info.address.startsWith('169.254.') ? 2 : 0);
+}
+async function resolveDevelopmentHostAsync(root, hostname) {
+    const override = hostname || process.env.REACT_NATIVE_PACKAGER_HOSTNAME;
+    if (override) {
+        if (!/^[A-Za-z0-9.-]+$/.test(override)) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_MANIFEST_HOST', 'Harmony development requires an HTTP LAN hostname or IPv4 address.', { operation: 'development-manifest' });
+        }
+        return override;
+    }
+    const candidates = Object.entries(node_os_1.default.networkInterfaces()).flatMap(([name, addresses]) => (addresses || [])
+        .filter(info => info.family === 'IPv4' && !info.internal)
+        .map(info => ({ address: info.address, priority: interfacePriority(name, info) }))).sort((a, b) => a.priority - b.priority);
+    if (!candidates.length)
+        return '127.0.0.1';
+    const preferred = candidates.filter(candidate => candidate.priority === candidates[0].priority);
+    if (preferred.length > 1) {
+        // Use Expo's route discovery to choose between equally suitable interfaces,
+        // but do not let a VPN default route displace an available LAN interface.
+        const expo = (0, node_module_1.createRequire)((0, expo_1.resolveExpoCli)(root).cliPath);
+        const require = (0, node_module_1.createRequire)(expo.resolve('@expo/cli/package.json'));
+        const { getGatewayAsync } = require('./build/src/utils/ip');
+        const gateway = await getGatewayAsync();
+        if (preferred.some(candidate => candidate.address === gateway.address))
+            return gateway.address;
+    }
+    return preferred[0].address;
+}

package/build/development/session.js

@@ -5,19 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readDevelopmentSessionAsync = readDevelopmentSessionAsync;
 const node_http_1 = __importDefault(require("node:http"));
-const node_os_1 = __importDefault(require("node:os"));
 const errors_1 = require("../errors");
 const config_1 = require("../runtime/config");
+const host_1 = require("./host");
 const protocol_1 = require("./protocol");
 async function readDevelopmentSessionAsync(root, port, hostname) {
     const project = await (0, config_1.readProjectRuntimeAsync)(root);
     const { config } = project;
-    const host = hostname || process.env.REACT_NATIVE_PACKAGER_HOSTNAME
-        || Object.values(node_os_1.default.networkInterfaces()).flat().find(item => item?.family === 'IPv4' && !item.internal)?.address
-        || '127.0.0.1';
-    if (!/^[A-Za-z0-9.-]+$/.test(host)) {
-        throw new errors_1.HarmonyCliError('ERR_HARMONY_MANIFEST_HOST', 'Harmony development requires an HTTP LAN hostname or IPv4 address.', { operation: 'development-manifest' });
-    }
+    const host = await (0, host_1.resolveDevelopmentHostAsync)(root, hostname);
     const manifest = await new Promise((resolve, reject) => {
         const request = node_http_1.default.get({
             host: '127.0.0.1',

package/build/doctor/doctor.d.ts

@@ -10,6 +10,7 @@ export interface DoctorResult {
     projectRoot: string;
 }
 interface DoctorOptions {
+    freshPrebuild?: boolean;
     requireBuildTools?: boolean;
     requireDeviceTools?: boolean;
     validateGeneratedProject?: boolean;

package/build/doctor/doctor.js

@@ -116,7 +116,10 @@ async function doctorUnlockedAsync(root, options = {}) {
                 checks.push(check('signing', 'pass', `Harmony signing config ${signing.name} is valid.`));
             }
             catch (error) {
-                checks.push(check('signing', 'error', error.message, { code: error.code || 'ERR_HARMONY_SIGNING_INVALID' }));
+                const fresh = options.freshPrebuild || !node_fs_1.default.existsSync(node_path_1.default.join(root, internal_1.HarmonyPlatformDirectory));
+                checks.push(check('signing', fresh ? 'warn' : 'error', fresh
+                    ? `The fresh Harmony project will be generated unsigned because signing materials are unavailable: ${error.message}`
+                    : error.message, { code: error.code || 'ERR_HARMONY_SIGNING_INVALID' }));
             }
         }
         else {

package/build/help.d.ts

@@ -1 +1 @@
-export declare const Help = "Usage: expo-harmony <command> [project] [options]\n\nCommands:\n  start                 Start Expo Metro for Harmony development\n  runtime               Describe project requirements; --client file checks compatibility\n  runtime --publish     Embed capabilities from prepared native build inputs\n  prebuild              Generate the Harmony native project with Expo CNG\n  prebuild --clean      Safely recreate the managed Harmony directory\n  prebuild --check      Compare generated desired state without project writes\n  build                 Build a HAP without selecting or contacting a device\n  doctor                Validate config, versions, Metro, RNOH, SDK, and signing\n  modules list          List native module candidates and their discovery source\n  modules inspect       Resolve Harmony metadata (--package narrows the result)\n  modules verify        Validate module config, registration conflicts and safe paths\n  export                Export an OTA update, assets, metadata, and source map\n  export:embed          Export validated Hermes bytecode, assets, and a source map\n  run                   Build, install, and launch the Harmony app\n\nOptions:\n  --no-install          Skip dependency install (prebuild) or HAP install (run)\n  --npm|--yarn|--pnpm|--bun\n                        Select the package manager used by prebuild dependency install\n  --skip-dependency-update <packages>\n                        Preserve comma-separated dependency versions\n  --device <id-or-name> Select an HDC target or start a local emulator by name\n  --variant <mode>      Build debug or release (default: debug)\n  --no-bundler          Use an already-running Expo Metro server\n  --app-id <bundleName>\n                        Launch another installed app (requires --no-install when different)\n  --host <hostname>     Advertised HTTP LAN hostname (start)\n  --private-key-path <path>\n                        Sign development manifests using the configured Updates certificate\n  --port <number>       Metro and device reverse port (default: 8081)\n  --sync                Re-run prebuild before building\n  --output-dir <path>   OTA export directory (default: dist)\n  --asset-url <url>     HTTP(S) root hosting exported OTA assets\n  --check               Validate an existing export without writing\n  --reset-cache         Reset Metro while exporting or starting\n  -c, --clear           Alias for --reset-cache (start)\n  -h, --help            Show this help\n";
+export declare const Help = "Usage: expo-harmony <command> [project] [options]\n\nCommands:\n  start                 Start Expo Metro for Harmony development\n  runtime               Describe project requirements; --client file checks compatibility\n  runtime --publish     Embed capabilities from prepared native build inputs\n  prebuild              Generate the Harmony native project with Expo CNG\n  prebuild --clean      Safely recreate the managed Harmony directory\n  prebuild --check      Compare generated desired state without project writes\n  build                 Build a HAP without selecting or contacting a device\n  doctor                Validate config, versions, Metro, RNOH, SDK, and signing\n  modules list          List native module candidates and their discovery source\n  modules inspect       Resolve Harmony metadata (--package narrows the result)\n  modules verify        Validate module config, registration conflicts and safe paths\n  export                Export an OTA update, assets, metadata, and source map\n  export:embed          Export validated Hermes bytecode, assets, and a source map\n  run                   Build, install, and launch the Harmony app\n\nOptions:\n  --no-install          Skip dependency install (prebuild) or HAP install (run)\n  --npm|--yarn|--pnpm|--bun\n                        Select the package manager used by prebuild dependency install\n  --skip-dependency-update <packages>\n                        Preserve comma-separated dependency versions\n  --device <id-or-name> Select an HDC target or start a local emulator by name\n  --variant <mode>      Build debug or release (default: debug)\n  --no-bundler          Use an already-running Expo Metro server\n  --app-id <bundleName>\n                        Launch another installed app (requires --no-install when different)\n  --host <hostname>     Advertised LAN hostname or IPv4 address (start, run)\n  --private-key-path <path>\n                        Sign development manifests using the configured Updates certificate\n  --port <number>       Metro and device reverse port (default: 8081)\n  --sync                Re-run prebuild before building\n  --output-dir <path>   OTA export directory (default: dist)\n  --asset-url <url>     HTTP(S) root hosting exported OTA assets\n  --check               Validate an existing export without writing\n  --reset-cache         Reset Metro while exporting or starting\n  -c, --clear           Alias for --reset-cache (start)\n  -h, --help            Show this help\n";

package/build/help.js

@@ -30,7 +30,7 @@ Options:
   --no-bundler          Use an already-running Expo Metro server
   --app-id <bundleName>
                         Launch another installed app (requires --no-install when different)
-  --host <hostname>     Advertised HTTP LAN hostname (start)
+  --host <hostname>     Advertised LAN hostname or IPv4 address (start, run)
   --private-key-path <path>
                         Sign development manifests using the configured Updates certificate
   --port <number>       Metro and device reverse port (default: 8081)

package/build/prebuild/index.js

@@ -21,6 +21,7 @@ const command = async (argv, io) => {
         }
         const { doctorAsync, formatDoctor } = await import('../doctor/doctor.js');
         const doctor = await doctorAsync(root, {
+            freshPrebuild: clean,
             requireBuildTools: false,
             validateGeneratedProject: !clean,
             validateModules: false,

package/build/prebuild/prebuild.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prebuildParsedAsync = prebuildParsedAsync;
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const internal_1 = require("@expo-harmony/prebuild-config/internal");
 const errors_1 = require("../errors");
 const bare_1 = require("../native/bare");
 const process_1 = require("../process");
@@ -20,6 +22,8 @@ async function prebuildParsedUnlockedAsync(projectRoot, passthrough, options = {
     }
     if (passthrough.includes('--clean'))
         await (0, clean_1.assertSafeCleanTarget)(projectRoot);
+    const freshHarmonyProject = passthrough.includes('--clean')
+        || !node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, internal_1.HarmonyPlatformDirectory));
     const expo = (0, expo_1.resolveExpoCli)(projectRoot);
     const packed = await (0, template_1.packAsync)(projectRoot);
     try {
@@ -35,6 +39,7 @@ async function prebuildParsedUnlockedAsync(projectRoot, passthrough, options = {
             env: {
                 ...(0, toolchain_1.createHarmonyToolchainEnv)(),
                 ...packed.env,
+                EXPO_HARMONY_PREBUILD_FRESH: freshHarmonyProject ? '1' : '0',
                 ...(options.buildType ? { EXPO_HARMONY_BUILD_TYPE: options.buildType } : {}),
             },
             operation: 'expo-prebuild',

package/build/run/metro.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.requireExistingMetroAsync = requireExistingMetroAsync;
 exports.startExpoMetroAsync = startExpoMetroAsync;
 const node_http_1 = __importDefault(require("node:http"));
+const host_1 = require("../development/host");
 const session_1 = require("../development/session");
 const errors_1 = require("../errors");
 const process_1 = require("../process");
@@ -66,10 +67,11 @@ async function requireExistingMetroAsync(port) {
     throw new errors_1.HarmonyCliError(code, message, { operation: 'metro-probe' });
 }
 async function startExpoMetroAsync(projectRoot, options) {
+    const host = await (0, host_1.resolveDevelopmentHostAsync)(projectRoot, options.host);
     const before = await probeMetroAsync(options.port);
     if (before === 'metro') {
         return {
-            development: await (0, session_1.readDevelopmentSessionAsync)(projectRoot, options.port, options.host),
+            development: await (0, session_1.readDevelopmentSessionAsync)(projectRoot, options.port, host),
             owner: 'existing',
             port: options.port,
             stop: async () => { },
@@ -94,7 +96,7 @@ async function startExpoMetroAsync(projectRoot, options) {
         env: {
             ...process.env,
             EXPO_METRO_TARGET: 'harmony',
-            ...(options.host ? { REACT_NATIVE_PACKAGER_HOSTNAME: options.host } : {}),
+            REACT_NATIVE_PACKAGER_HOSTNAME: host,
         },
         operation: 'expo-metro',
         outputLimit: 1024 * 1024,
@@ -128,7 +130,7 @@ async function startExpoMetroAsync(projectRoot, options) {
             }
             if (await probeMetroAsync(options.port) === 'metro') {
                 return {
-                    development: await (0, session_1.readDevelopmentSessionAsync)(projectRoot, options.port, options.host),
+                    development: await (0, session_1.readDevelopmentSessionAsync)(projectRoot, options.port, host),
                     owner: 'started',
                     port: options.port,
                     process: managed,

package/build/run/options.d.ts

@@ -2,6 +2,7 @@ declare function parseRunArgs(argv: string[]): {
     appId: string;
     device: string;
     help: boolean;
+    host: string;
     noBundler: boolean;
     noInstall: boolean;
     port: number;

package/build/run/options.js

@@ -3,10 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseRunArgs = parseRunArgs;
 const errors_1 = require("../errors");
 const args_1 = require("../args");
+const host_1 = require("../development/host");
 const RunOptions = {
     ...args_1.CommonOptions,
     'app-id': { type: 'string' },
     'device': { type: 'string' },
+    'host': { type: 'string' },
     'no-bundler': { type: 'boolean' },
     'no-install': { type: 'boolean' },
     'port': { type: 'string' },
@@ -50,6 +52,7 @@ function parseRunArgs(argv) {
         appId,
         device,
         help: Boolean(values.help),
+        host: (0, host_1.parseHostOption)(values.host),
         noBundler: Boolean(values['no-bundler']),
         noInstall: Boolean(values['no-install']),
         port,

package/build/run/run.d.ts

@@ -3,6 +3,7 @@ import { type NativeBuildResult } from '../native/build';
 export interface HarmonyRunOptions {
     appId?: string;
     device?: string;
+    host?: string;
     io?: Pick<Console, 'error' | 'log' | 'warn'>;
     noBundler?: boolean;
     noInstall?: boolean;

package/build/run/run.js

@@ -33,6 +33,7 @@ async function runHarmonyUnlockedAsync(root, options = {}) {
     const settings = {
         appId: options.appId,
         device: options.device,
+        host: options.host,
         interactiveBundler: Boolean(options.interactiveBundler),
         io: options.io || console,
         noBundler: Boolean(options.noBundler),
@@ -72,6 +73,7 @@ async function runHarmonyUnlockedAsync(root, options = {}) {
             metro = await (0, profile_1.timedAsync)(steps, 'metro', () => settings.noBundler
                 ? (0, metro_1.requireExistingMetroAsync)(settings.port)
                 : (0, metro_1.startExpoMetroAsync)(root, {
+                    host: settings.host,
                     interactive: settings.interactiveBundler,
                     port: settings.port,
                     privateKeyPath: settings.privateKeyPath,

package/build/runtime/contract.js

@@ -40,10 +40,6 @@ async function createRuntimeContractAsync(root, project, modules, metro) {
         modules: (0, expo_modules_autolinking_1.createNativeModuleContracts)(modules),
         config: project.native,
     };
-    if (contract.rnoh !== '0.84.1' || contract.react !== '19.2.3' || contract.hermes !== '250829098.0.9'
-        || !contract.expo.startsWith('55.') || !modules.some(module => module.packageName === '@expo-harmony/expo-modules-core')) {
-        throw new errors_1.HarmonyCliError('ERR_HARMONY_RUNTIME_UNSUPPORTED', 'The fixed development runtime requires Expo SDK 55, Harmony Expo Modules Core, RNOH 0.84.1, React 19.2.3, and Hermes 250829098.0.9. Check the Metro React alias.', { operation: 'runtime-contract' });
-    }
     const issues = (0, runtime_1.validateHarmonyRuntime)(contract);
     if (issues.length > 0) {
         throw new errors_1.HarmonyCliError('ERR_HARMONY_RUNTIME_CONFIG', issues.map(issue => issue.message).join('\n'), { operation: 'runtime-contract' });

package/build/start/options.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseStartArgs = parseStartArgs;
 const args_1 = require("../args");
+const host_1 = require("../development/host");
 const errors_1 = require("../errors");
 const StartOptions = {
     ...args_1.CommonOptions,
@@ -24,12 +25,9 @@ function parseStartArgs(argv) {
             operation: 'parse-arguments',
         });
     }
-    if (values.host !== undefined && !/^[A-Za-z0-9.-]+$/.test(values.host)) {
-        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--host must be a hostname or IPv4 address without a port or scheme.', { operation: 'parse-arguments' });
-    }
     return {
         help: Boolean(values.help),
-        host: values.host,
+        host: (0, host_1.parseHostOption)(values.host),
         port,
         privateKeyPath: values['private-key-path'],
         project: positionals[0],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo-harmony/cli",
-  "version": "55.0.26-harmony.12",
+  "version": "55.0.26-harmony.13",
   "keywords": [
     "react-native",
     "expo",
@@ -53,7 +53,7 @@
   "dependencies": {
     "@expo-harmony/config-plugins": "55.0.10-harmony.5",
     "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.5",
-    "@expo-harmony/prebuild-config": "55.0.0-harmony.9",
+    "@expo-harmony/prebuild-config": "55.0.0-harmony.10",
     "@expo/config": "55.0.17",
     "@expo/fingerprint": "0.16.7",
     "cross-spawn": "^7.0.6",

package/src/development/host.ts

@@ -0,0 +1,62 @@
+import { createRequire } from 'node:module';
+import os from 'node:os';
+
+import { HarmonyCliError } from '../errors';
+import { resolveExpoCli } from '../expo';
+
+export function parseHostOption(host?: string): string | undefined {
+  if (host !== undefined && !/^[A-Za-z0-9.-]+$/.test(host)) {
+    throw new HarmonyCliError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      '--host must be a hostname or IPv4 address without a port or scheme.',
+      { operation: 'parse-arguments' }
+    );
+  }
+
+  return host;
+}
+
+function interfacePriority(name: string, info: os.NetworkInterfaceInfo): number {
+  // Interface names alone cannot identify every virtual adapter (especially on Windows).
+  const virtual = /^(utun|tun|tap|wg|ppp|ipsec|vmnet|vboxnet|virbr|docker|br-|bridge\d|veth|tailscale|zt)|virtual|vmware|vpn/i.test(name)
+    || /^(00:00:00:00:00:00|00:05:69:|00:0c:29:|00:1c:14:|00:50:56:|08:00:27:|00:15:5d:)/i.test(info.mac)
+    || /^198\.(18|19)\./.test(info.address);
+
+  return Number(virtual) + (info.address.startsWith('169.254.') ? 2 : 0);
+}
+
+export async function resolveDevelopmentHostAsync(root: string, hostname?: string): Promise<string> {
+  const override = hostname || process.env.REACT_NATIVE_PACKAGER_HOSTNAME;
+  if (override) {
+    if (!/^[A-Za-z0-9.-]+$/.test(override)) {
+      throw new HarmonyCliError(
+        'ERR_HARMONY_MANIFEST_HOST',
+        'Harmony development requires an HTTP LAN hostname or IPv4 address.',
+        { operation: 'development-manifest' }
+      );
+    }
+
+    return override;
+  }
+
+  const candidates = Object.entries(os.networkInterfaces()).flatMap(([name, addresses]) =>
+    (addresses || [])
+      .filter(info => info.family === 'IPv4' && !info.internal)
+      .map(info => ({ address: info.address, priority: interfacePriority(name, info) }))
+  ).sort((a, b) => a.priority - b.priority);
+
+  if (!candidates.length) return '127.0.0.1';
+
+  const preferred = candidates.filter(candidate => candidate.priority === candidates[0].priority);
+  if (preferred.length > 1) {
+    // Use Expo's route discovery to choose between equally suitable interfaces,
+    // but do not let a VPN default route displace an available LAN interface.
+    const expo = createRequire(resolveExpoCli(root).cliPath);
+    const require = createRequire(expo.resolve('@expo/cli/package.json'));
+    const { getGatewayAsync } = require('./build/src/utils/ip');
+    const gateway = await getGatewayAsync();
+    if (preferred.some(candidate => candidate.address === gateway.address)) return gateway.address;
+  }
+
+  return preferred[0].address;
+}

package/src/development/session.ts

@@ -1,26 +1,17 @@
 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 { resolveDevelopmentHostAsync } from './host';
 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 host = await resolveDevelopmentHostAsync(root, hostname);
 
   const manifest = await new Promise<HarmonyDevelopmentManifest>((resolve, reject) => {
     const request = http.get({

package/src/doctor/doctor.ts

@@ -5,7 +5,11 @@ import path from 'node:path';
 import { getConfig } from '@expo/config';
 import { normalizeHarmonyConfig } from '@expo-harmony/config-plugins';
 import { verifyModulesAsync } from '@expo-harmony/expo-modules-autolinking';
-import { isRnohAutolinkingDisabled, validateHarmonySigningConfigFile } from '@expo-harmony/prebuild-config/internal';
+import {
+  HarmonyPlatformDirectory,
+  isRnohAutolinkingDisabled,
+  validateHarmonySigningConfigFile,
+} from '@expo-harmony/prebuild-config/internal';
 
 import { spawnAsync } from '../process';
 import { resolveTimeoutMs } from '../timeout';
@@ -29,6 +33,7 @@ export interface DoctorResult {
 }
 
 interface DoctorOptions {
+  freshPrebuild?: boolean;
   requireBuildTools?: boolean;
   requireDeviceTools?: boolean;
   validateGeneratedProject?: boolean;
@@ -140,7 +145,15 @@ async function doctorUnlockedAsync(root: string, options: DoctorOptions = {}): P
         const signing = await validateHarmonySigningConfigFile(root, harmony.signingConfigFile);
         checks.push(check('signing', 'pass', `Harmony signing config ${signing.name} is valid.`));
       } catch (error) {
-        checks.push(check('signing', 'error', error.message, { code: error.code || 'ERR_HARMONY_SIGNING_INVALID' }));
+        const fresh = options.freshPrebuild || !fs.existsSync(path.join(root, HarmonyPlatformDirectory));
+        checks.push(check(
+          'signing',
+          fresh ? 'warn' : 'error',
+          fresh
+            ? `The fresh Harmony project will be generated unsigned because signing materials are unavailable: ${error.message}`
+            : error.message,
+          { code: error.code || 'ERR_HARMONY_SIGNING_INVALID' }
+        ));
       }
     } else {
       checks.push(check('signing', 'warn', 'No external signing config is set; unsigned generation remains available.'));

package/src/help.ts

@@ -27,7 +27,7 @@ Options:
   --no-bundler          Use an already-running Expo Metro server
   --app-id <bundleName>
                         Launch another installed app (requires --no-install when different)
-  --host <hostname>     Advertised HTTP LAN hostname (start)
+  --host <hostname>     Advertised LAN hostname or IPv4 address (start, run)
   --private-key-path <path>
                         Sign development manifests using the configured Updates certificate
   --port <number>       Metro and device reverse port (default: 8081)

package/src/prebuild/index.ts

@@ -25,6 +25,7 @@ export const command: Command = async (argv, io) => {
 
       const { doctorAsync, formatDoctor } = await import('../doctor/doctor.js');
       const doctor = await doctorAsync(root, {
+        freshPrebuild: clean,
         requireBuildTools: false,
         validateGeneratedProject: !clean,
         validateModules: false,

package/src/prebuild/prebuild.ts

@@ -1,4 +1,7 @@
 import fs from 'node:fs';
+import path from 'node:path';
+
+import { HarmonyPlatformDirectory } from '@expo-harmony/prebuild-config/internal';
 
 import { HarmonyCliError } from '../errors';
 import { isBareHarmonyProject } from '../native/bare';
@@ -25,6 +28,9 @@ async function prebuildParsedUnlockedAsync(
   }
   if (passthrough.includes('--clean')) await assertSafeCleanTarget(projectRoot);
 
+  const freshHarmonyProject = passthrough.includes('--clean')
+    || !fs.existsSync(path.join(projectRoot, HarmonyPlatformDirectory));
+
   const expo = resolveExpoCli(projectRoot);
   const packed = await packAsync(projectRoot);
 
@@ -41,6 +47,7 @@ async function prebuildParsedUnlockedAsync(
       env: {
         ...createHarmonyToolchainEnv(),
         ...packed.env,
+        EXPO_HARMONY_PREBUILD_FRESH: freshHarmonyProject ? '1' : '0',
         ...(options.buildType ? { EXPO_HARMONY_BUILD_TYPE: options.buildType } : {}),
       },
       operation: 'expo-prebuild',

package/src/run/metro.ts

@@ -1,5 +1,6 @@
 import http from 'node:http';
 
+import { resolveDevelopmentHostAsync } from '../development/host';
 import { readDevelopmentSessionAsync } from '../development/session';
 import { HarmonyCliError } from '../errors';
 import { formatDiagnostics, startManagedProcess, type ProcessResult } from '../process';
@@ -102,11 +103,12 @@ async function startExpoMetroAsync(
   projectRoot: string,
   options: MetroOptions
 ): Promise<MetroSession> {
+  const host = await resolveDevelopmentHostAsync(projectRoot, options.host);
   const before = await probeMetroAsync(options.port);
 
   if (before === 'metro') {
     return {
-      development: await readDevelopmentSessionAsync(projectRoot, options.port, options.host),
+      development: await readDevelopmentSessionAsync(projectRoot, options.port, host),
       owner: 'existing',
       port: options.port,
       stop: async () => {},
@@ -137,7 +139,7 @@ async function startExpoMetroAsync(
     env: {
       ...process.env,
       EXPO_METRO_TARGET: 'harmony',
-      ...(options.host ? { REACT_NATIVE_PACKAGER_HOSTNAME: options.host } : {}),
+      REACT_NATIVE_PACKAGER_HOSTNAME: host,
     },
     operation: 'expo-metro',
     outputLimit: 1024 * 1024,
@@ -193,7 +195,7 @@ async function startExpoMetroAsync(
 
       if (await probeMetroAsync(options.port) === 'metro') {
         return {
-          development: await readDevelopmentSessionAsync(projectRoot, options.port, options.host),
+          development: await readDevelopmentSessionAsync(projectRoot, options.port, host),
           owner: 'started',
           port: options.port,
           process: managed,

package/src/run/options.ts

@@ -1,10 +1,12 @@
 import { HarmonyCliError } from '../errors';
 import { CommonOptions, parseArgs } from '../args';
+import { parseHostOption } from '../development/host';
 
 const RunOptions = {
   ...CommonOptions,
   'app-id': { type: 'string' },
   'device': { type: 'string' },
+  'host': { type: 'string' },
   'no-bundler': { type: 'boolean' },
   'no-install': { type: 'boolean' },
   'port': { type: 'string' },
@@ -59,6 +61,7 @@ function parseRunArgs(argv: string[]) {
     appId,
     device,
     help: Boolean(values.help),
+    host: parseHostOption(values.host),
     noBundler: Boolean(values['no-bundler']),
     noInstall: Boolean(values['no-install']),
     port,

package/src/run/run.ts

@@ -24,6 +24,7 @@ import { timedAsync } from '../profile';
 export interface HarmonyRunOptions {
   appId?: string;
   device?: string;
+  host?: string;
   io?: Pick<Console, 'error' | 'log' | 'warn'>;
   noBundler?: boolean;
   noInstall?: boolean;
@@ -60,8 +61,8 @@ interface HarmonyRunSession {
   result: HarmonyRunResult;
 }
 
-type NormalizedRunOptions = Required<Omit<HarmonyRunSessionOptions, 'appId' | 'device' | 'privateKeyPath'>>
-  & Pick<HarmonyRunSessionOptions, 'appId' | 'device' | 'privateKeyPath'>;
+type NormalizedRunOptions = Required<Omit<HarmonyRunSessionOptions, 'appId' | 'device' | 'host' | 'privateKeyPath'>>
+  & Pick<HarmonyRunSessionOptions, 'appId' | 'device' | 'host' | 'privateKeyPath'>;
 
 const BundleName = /^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*){2,}$/u;
 
@@ -91,6 +92,7 @@ async function runHarmonyUnlockedAsync(
   const settings: NormalizedRunOptions = {
     appId: options.appId,
     device: options.device,
+    host: options.host,
     interactiveBundler: Boolean(options.interactiveBundler),
     io: options.io || console,
     noBundler: Boolean(options.noBundler),
@@ -140,6 +142,7 @@ async function runHarmonyUnlockedAsync(
       metro = await timedAsync(steps, 'metro', () => settings.noBundler
         ? requireExistingMetroAsync(settings.port)
         : startExpoMetroAsync(root, {
+            host: settings.host,
             interactive: settings.interactiveBundler,
             port: settings.port,
             privateKeyPath: settings.privateKeyPath,

package/src/runtime/contract.ts

@@ -49,15 +49,6 @@ async function createRuntimeContractAsync(
     config: project.native,
   };
 
-  if (contract.rnoh !== '0.84.1' || contract.react !== '19.2.3' || contract.hermes !== '250829098.0.9'
-    || !contract.expo.startsWith('55.') || !modules.some(module => module.packageName === '@expo-harmony/expo-modules-core')) {
-    throw new HarmonyCliError(
-      'ERR_HARMONY_RUNTIME_UNSUPPORTED',
-      'The fixed development runtime requires Expo SDK 55, Harmony Expo Modules Core, RNOH 0.84.1, React 19.2.3, and Hermes 250829098.0.9. Check the Metro React alias.',
-      { operation: 'runtime-contract' }
-    );
-  }
-
   const issues = validateHarmonyRuntime(contract);
   if (issues.length > 0) {
     throw new HarmonyCliError(

package/src/start/options.ts

@@ -1,4 +1,5 @@
 import { CommonOptions, parseArgs } from '../args';
+import { parseHostOption } from '../development/host';
 import { HarmonyCliError } from '../errors';
 
 const StartOptions = {
@@ -27,17 +28,9 @@ function parseStartArgs(argv: string[]) {
     });
   }
 
-  if (values.host !== undefined && !/^[A-Za-z0-9.-]+$/.test(values.host)) {
-    throw new HarmonyCliError(
-      'ERR_HARMONY_CONFIG_INVALID',
-      '--host must be a hostname or IPv4 address without a port or scheme.',
-      { operation: 'parse-arguments' }
-    );
-  }
-
   return {
     help: Boolean(values.help),
-    host: values.host,
+    host: parseHostOption(values.host),
     port,
     privateKeyPath: values['private-key-path'],
     project: positionals[0],