@expo-harmony/cli 55.0.26-harmony.11 → 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`。
@@ -80,7 +83,7 @@ npx expo-harmony prebuild --check
 
 `--clean` 删除原生工程后重新生成。如果工程缺少 CNG 清单或模板标记，或者目录是符号链接、位于项目之外，命令会拒绝删除。
 
-`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能与其他会修改工程的选项一起使用。
+`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0，有差异时列出变更并以退出码 2 结束。这个选项不能和会修改工程的选项一起使用。
 
 ## Build
 
@@ -94,7 +97,7 @@ npx expo-harmony build --sync
 
 默认构建 Debug 版本。使用 `--variant release` 构建 Release 版本时，命令会将 JS Bundle 和资源打包进应用。
 
-项目没有原生工程时，命令会先运行 prebuild。已有 CNG 工程时，会检查生成的文件是否需要更新；有差异时停止构建，可以使用 `--sync` 重新生成后继续构建。bare 工程按现有原生配置构建，不支持 `--sync`。
+项目没有原生工程时，命令会先运行 prebuild。已有 CNG 工程时，会检查生成的文件是否需要更新，有差异就停止构建，可以用 `--sync` 重新生成后继续构建。bare 工程按现有原生配置构建，不支持 `--sync`。
 
 ## Doctor
 
@@ -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
 
@@ -154,13 +157,14 @@ npx expo-harmony run \
   --port 8081
 ```
 
-`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程；如果工程不存在，会先运行 prebuild。
+`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程，工程不存在时先运行 prebuild。
 
 常用选项：
 
 - `--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，但跳过安装，启动设备上已有的应用。
@@ -169,7 +173,7 @@ npx expo-harmony run \
 
 Debug 模式下，如果 Metro 由这个命令启动，日志会显示在当前终端，按 Ctrl+C 退出。
 
-未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器；如果也没有正在启动的模拟器，就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
+未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器，没有的话就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
 
 按名称选择或自动启动模拟器时，CLI 会等待模拟器开机并连接 HDC，最多等待 120 秒。退出 CLI 或 Metro 后，模拟器继续运行。
 
@@ -183,6 +187,7 @@ CLI 先读取环境变量指定的工具路径，再查找 DevEco Studio 的安
 
 | 环境变量 | 用途 |
 | --- | --- |
+| `REACT_NATIVE_PACKAGER_HOSTNAME` | 指定 Metro 对外公布的 IP 或主机名，`--host` 优先 |
 | `HARMONY_HDC` | 指定 HDC 路径 |
 | `HARMONY_EMULATOR` | 指定模拟器命令行工具路径 |
 | `HARMONY_OHPM` | 指定 OHPM 路径 |
@@ -191,6 +196,28 @@ CLI 先读取环境变量指定的工具路径，再查找 DevEco Studio 的安
 | `EXPO_HARMONY_NODE` | 指定原生构建过程中运行 Expo Harmony CLI 的 Node.js 路径，要求 Node.js 20 或更高版本 |
 | `DEVECO_SDK_HOME`、`HARMONY_HOME` 或 `OHOS_SDK_HOME` | 指定 HarmonyOS SDK 根目录 |
 
+### 超时
+
+OHPM 安装、Hvigor 构建、等待模拟器这些步骤都有超时，默认值见下表，可以通过环境变量覆盖。变量名为 `EXPO_HARMONY_<操作名大写下划线>_TIMEOUT_MS`，单位为毫秒，例如 `EXPO_HARMONY_OHPM_INSTALL_TIMEOUT_MS`。设置成 0、负数或无法解析的值时，这个变量会被忽略，并给出警告。
+
+| 环境变量 | 对应操作 | 默认值 |
+| --- | --- | --- |
+| `EXPO_HARMONY_OHPM_INSTALL_TIMEOUT_MS` | OHPM 依赖安装 | 30 分钟 |
+| `EXPO_HARMONY_HVIGOR_BUILD_TIMEOUT_MS` | Hvigor 构建 | 15 分钟 |
+| `EXPO_HARMONY_EXPO_EXPORT_EMBED_TIMEOUT_MS` | `export:embed`（Hermes 打包） | 10 分钟 |
+| `EXPO_HARMONY_METRO_READY_TIMEOUT_MS` | 等待 Metro 就绪 | 30 分钟 |
+| `EXPO_HARMONY_START_EMULATOR_TIMEOUT_MS` | 等待模拟器连接 HDC | 2 分钟 |
+| `EXPO_HARMONY_INSTALL_HAP_TIMEOUT_MS` | 安装 HAP 到设备 | 2 分钟 |
+| `EXPO_HARMONY_LAUNCH_APP_TIMEOUT_MS` | 启动应用 | 30 秒 |
+| `EXPO_HARMONY_LIST_DEVICES_TIMEOUT_MS` | HDC 列出设备 | 15 秒 |
+| `EXPO_HARMONY_LIST_EMULATORS_TIMEOUT_MS` | 列出模拟器实例 | 15 秒 |
+| `EXPO_HARMONY_FORCE_STOP_APP_TIMEOUT_MS` | 强制停止应用 | 15 秒 |
+| `EXPO_HARMONY_LIST_METRO_PORTS_TIMEOUT_MS` | 列出 Metro 端口转发 | 15 秒 |
+| `EXPO_HARMONY_REMOVE_METRO_PORT_TIMEOUT_MS` | 移除 Metro 端口转发 | 15 秒 |
+| `EXPO_HARMONY_REVERSE_METRO_PORT_TIMEOUT_MS` | 反向转发 Metro 端口 | 15 秒 |
+| `EXPO_HARMONY_HDC_TIMEOUT_MS` | 其他 HDC 命令 | 60 秒 |
+| `EXPO_HARMONY_DOCTOR_TIMEOUT_MS` | Doctor 工具检查 | 10 秒 |
+
 ## Author
 
 **expo-harmony** © [Baoshuo](https://github.com/renbaoshuo), Released under the MIT License.<br>

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

@@ -13,6 +13,7 @@ const config_plugins_1 = require("@expo-harmony/config-plugins");
 const expo_modules_autolinking_1 = require("@expo-harmony/expo-modules-autolinking");
 const internal_1 = require("@expo-harmony/prebuild-config/internal");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 const projectLock_1 = require("../projectLock");
 const project_1 = require("../native/project");
 const toolchain_1 = require("../native/toolchain");
@@ -115,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 {
@@ -179,7 +183,7 @@ async function doctorUnlockedAsync(root, options = {}) {
                 capture: true,
                 cwd: root,
                 operation: `doctor-${id}`,
-                timeoutMs: 10_000,
+                timeoutMs: (0, timeout_1.resolveTimeoutMs)('doctor', 10_000),
             });
             checks.push(result.code === 0 && !result.timedOut
                 ? check(id, 'pass', `${command} is available through ${tool.source}.`)

package/build/exportEmbed/export.js

@@ -15,6 +15,7 @@ const errors_1 = require("../errors");
 const projectLock_1 = require("../projectLock");
 const project_1 = require("../native/project");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 const expo_1 = require("../expo");
 const manifest_1 = require("./manifest");
 async function exportEmbedUnlockedAsync(root, options = {}) {
@@ -63,7 +64,7 @@ async function exportEmbedUnlockedAsync(root, options = {}) {
             },
             operation: 'expo-export-embed',
             outputLimit: 4 * 1024 * 1024,
-            timeoutMs: options.timeoutMs || 10 * 60_000,
+            timeoutMs: (0, timeout_1.resolveTimeoutMs)('expo-export-embed', 10 * 60_000, options.timeoutMs),
         });
         if (result.code !== 0 || result.timedOut) {
             const diagnostics = (0, process_1.formatDiagnostics)(result);

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/native/build.js

@@ -15,6 +15,7 @@ const log_1 = require("../log");
 const path_1 = require("../path");
 const process_1 = require("../process");
 const profile_1 = require("../profile");
+const timeout_1 = require("../timeout");
 async function buildNativeAsync(root, plan, tools, options, steps) {
     let exported = null;
     const embedded = plan.buildMode === 'release' || (0, config_1.getConfig)(root).exp.updates?.useNativeDebug === true;
@@ -59,7 +60,7 @@ async function buildNativeAsync(root, plan, tools, options, steps) {
         },
         message: 'Hvigor build',
         operation: 'hvigor-build',
-        timeoutMs: 15 * 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('hvigor-build', 15 * 60_000),
     }));
     if (!(0, file_1.isNonEmptyRegularFile)(plan.expectedHap)) {
         throw new errors_1.HarmonyCliError('ERR_HARMONY_HAP_MISSING', 'Hvigor completed without producing the expected non-empty regular HAP.', { operation: 'verify-hap' });

package/build/native/install.js

@@ -2,12 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installHarmonyDependenciesAsync = installHarmonyDependenciesAsync;
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 async function installHarmonyDependenciesAsync(plan, tools, options = {}) {
     await (0, process_1.runCheckedAsync)(tools.ohpm.command, [...tools.ohpm.args, 'install', '--all'], {
         code: 'ERR_HARMONY_OHPM_FAILED',
         cwd: plan.harmonyRoot,
         message: 'OHPM install',
         operation: 'ohpm-install',
-        timeoutMs: options.timeoutMs || 5 * 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('ohpm-install', 30 * 60_000, options.timeoutMs),
     });
 }

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/devices.js

@@ -8,6 +8,7 @@ const promises_1 = require("node:timers/promises");
 const emulators_1 = require("./emulators");
 const errors_1 = require("../errors");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 function parseHdcTargets(output) {
     const trimmed = String(output).trim();
     if (!trimmed || trimmed === '[Empty]')
@@ -42,7 +43,7 @@ async function runHdcAsync(hdc, args, options = {}) {
         cwd: options.cwd,
         operation: options.operation || 'hdc',
         outputLimit: options.outputLimit || 256 * 1024,
-        timeoutMs: options.timeoutMs || 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)(options.operation || 'hdc', 60_000, options.timeoutMs),
     });
     if (!options.allowFailure && hasCommandFailure(result)) {
         const diagnostics = (0, process_1.formatDiagnostics)(result, 2_000);
@@ -56,7 +57,7 @@ async function listConnectedDevicesAsync(hdc, options) {
         cwd: options.cwd,
         message: 'Cannot list Harmony devices',
         operation: 'list-devices',
-        timeoutMs: options.timeoutMs || 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('list-devices', 15_000, options.timeoutMs),
     });
     const targets = parseHdcTargets(result.stdout || result.stderr);
     return targets.filter(target => target.state.toLowerCase() === 'connected');
@@ -110,7 +111,7 @@ async function selectDeviceAsync(hdc, requested, options = {}) {
         launch = (0, emulators_1.startEmulator)(options.emulator, instance.name, options.emulatorLogFile, options.cwd);
     }
     options.onProgress?.(`Waiting for Harmony emulator ${instance.name} to connect`);
-    const deadline = Date.now() + (options.timeoutMs || 120_000);
+    const deadline = Date.now() + (0, timeout_1.resolveTimeoutMs)('start-emulator', 120_000, options.timeoutMs);
     while (Date.now() < deadline) {
         launch?.assertRunning();
         const devices = await listConnectedDevicesAsync(hdc, {
@@ -155,7 +156,7 @@ async function installHapAsync(hdc, device, hap, options = {}) {
         cwd: options.cwd,
         message: `Cannot install the Harmony HAP on ${device.id}`,
         operation: 'install-hap',
-        timeoutMs: options.timeoutMs || 2 * 60_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('install-hap', 2 * 60_000, options.timeoutMs),
     });
 }
 async function configureMetroPortAsync(hdc, device, port, options = {}) {
@@ -171,7 +172,7 @@ async function configureMetroPortAsync(hdc, device, port, options = {}) {
     const forwards = await runHdcAsync(hdc, ['-t', device.id, 'fport', 'ls'], {
         cwd: options.cwd,
         operation: 'list-metro-ports',
-        timeoutMs: 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('list-metro-ports', 15_000, options.timeoutMs),
     });
     for (const line of forwards.stdout.split(/\r?\n/u)) {
         const [target, remote, local, direction] = line.trim().split(/\s+/u);
@@ -182,7 +183,7 @@ async function configureMetroPortAsync(hdc, device, port, options = {}) {
         await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', remote, local], {
             cwd: options.cwd,
             operation: 'remove-metro-port',
-            timeoutMs: 15_000,
+            timeoutMs: (0, timeout_1.resolveTimeoutMs)('remove-metro-port', 15_000, options.timeoutMs),
         });
     }
     await runHdcAsync(hdc, ['-t', device.id, 'rport', deviceEndpoint, hostEndpoint], {
@@ -190,7 +191,7 @@ async function configureMetroPortAsync(hdc, device, port, options = {}) {
         cwd: options.cwd,
         message: `Cannot reverse Metro port ${port} for ${device.id}`,
         operation: 'reverse-metro-port',
-        timeoutMs: 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('reverse-metro-port', 15_000, options.timeoutMs),
     });
 }
 async function launchAppAsync(hdc, device, bundleName, abilityName, options = {}) {
@@ -204,7 +205,7 @@ async function launchAppAsync(hdc, device, bundleName, abilityName, options = {}
         allowFailure: true,
         cwd: options.cwd,
         operation: 'force-stop-app',
-        timeoutMs: 15_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('force-stop-app', 15_000),
     });
     await runHdcAsync(hdc, [
         '-t', device.id,
@@ -218,6 +219,6 @@ async function launchAppAsync(hdc, device, bundleName, abilityName, options = {}
         cwd: options.cwd,
         message: `Cannot launch ${bundleName} on ${device.id}`,
         operation: 'launch-app',
-        timeoutMs: 30_000,
+        timeoutMs: (0, timeout_1.resolveTimeoutMs)('launch-app', 30_000),
     });
 }

package/build/run/emulators.js

@@ -10,6 +10,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const errors_1 = require("../errors");
 const process_1 = require("../process");
+const timeout_1 = require("../timeout");
 async function listEmulatorsAsync(tool, options = {}) {
     let result;
     try {
@@ -17,7 +18,7 @@ async function listEmulatorsAsync(tool, options = {}) {
             capture: true,
             cwd: options.cwd,
             operation: 'list-emulators',
-            timeoutMs: options.timeoutMs || 15_000,
+            timeoutMs: (0, timeout_1.resolveTimeoutMs)('list-emulators', 15_000, options.timeoutMs),
         });
     }
     catch (cause) {

package/build/run/metro.js

@@ -6,10 +6,12 @@ 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");
 const expo_1 = require("../expo");
+const timeout_1 = require("../timeout");
 function delay(milliseconds) {
     return new Promise(resolve => setTimeout(resolve, milliseconds));
 }
@@ -65,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 () => { },
@@ -93,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,
@@ -107,7 +110,7 @@ async function startExpoMetroAsync(projectRoot, options) {
         exitError = error;
     });
     const startedAt = Date.now();
-    const timeoutMs = options.readyTimeoutMs || 1800000;
+    const timeoutMs = (0, timeout_1.resolveTimeoutMs)('metro-ready', 30 * 60_000, options.readyTimeoutMs);
     try {
         while (Date.now() - startedAt < timeoutMs) {
             if (exitError instanceof errors_1.HarmonyCliError) {
@@ -127,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/build/timeout.d.ts

@@ -0,0 +1,8 @@
+declare function timeoutEnvName(operation: string): string;
+/**
+ * Resolves a command timeout: explicit option first, then the
+ * `EXPO_HARMONY_<OPERATION>_TIMEOUT_MS` environment variable derived from the
+ * operation name (dashes become underscores), then the built-in default.
+ */
+declare function resolveTimeoutMs(operation: string, fallbackMs: number, explicitMs?: number): number;
+export { resolveTimeoutMs, timeoutEnvName };

package/build/timeout.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTimeoutMs = resolveTimeoutMs;
+exports.timeoutEnvName = timeoutEnvName;
+const TimeoutEnvPrefix = 'EXPO_HARMONY_';
+const warnedEnvNames = new Set();
+function timeoutEnvName(operation) {
+    return `${TimeoutEnvPrefix}${operation.toUpperCase().replace(/-/gu, '_')}_TIMEOUT_MS`;
+}
+function timeoutFromEnv(operation) {
+    const name = timeoutEnvName(operation);
+    const raw = process.env[name];
+    if (!raw)
+        return null;
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && parsed > 0)
+        return parsed;
+    if (!warnedEnvNames.has(name)) {
+        warnedEnvNames.add(name);
+        console.warn(`Ignoring unsupported ${name} value: ${raw}. Use a positive number of milliseconds.`);
+    }
+    return null;
+}
+/**
+ * Resolves a command timeout: explicit option first, then the
+ * `EXPO_HARMONY_<OPERATION>_TIMEOUT_MS` environment variable derived from the
+ * operation name (dashes become underscores), then the built-in default.
+ */
+function resolveTimeoutMs(operation, fallbackMs, explicitMs) {
+    return explicitMs && explicitMs > 0
+        ? explicitMs
+        : timeoutFromEnv(operation) ?? fallbackMs;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo-harmony/cli",
-  "version": "55.0.26-harmony.11",
+  "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,9 +5,14 @@ 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';
 import { withHarmonyProjectLockAsync } from '../projectLock';
 import { resolveHarmonyBuildPlanIfPresentAsync } from '../native/project';
 import { resolveHarmonyToolchain, type HarmonyTool } from '../native/toolchain';
@@ -28,6 +33,7 @@ export interface DoctorResult {
 }
 
 interface DoctorOptions {
+  freshPrebuild?: boolean;
   requireBuildTools?: boolean;
   requireDeviceTools?: boolean;
   validateGeneratedProject?: boolean;
@@ -139,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.'));
@@ -221,7 +235,7 @@ async function doctorUnlockedAsync(root: string, options: DoctorOptions = {}): P
         capture: true,
         cwd: root,
         operation: `doctor-${id}`,
-        timeoutMs: 10_000,
+        timeoutMs: resolveTimeoutMs('doctor', 10_000),
       });
 
       checks.push(result.code === 0 && !result.timedOut

package/src/exportEmbed/export.ts

@@ -10,6 +10,7 @@ import { HarmonyCliError } from '../errors';
 import { withHarmonyProjectLockAsync } from '../projectLock';
 import { resolveHarmonyBuildPlanAsync } from '../native/project';
 import { formatDiagnostics, spawnAsync } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 import { resolveExpoHermesBuilder } from '../expo';
 import {
   assertHermesBundle, assertSourceMap, exportPaths,
@@ -88,7 +89,7 @@ async function exportEmbedUnlockedAsync(
       },
       operation: 'expo-export-embed',
       outputLimit: 4 * 1024 * 1024,
-      timeoutMs: options.timeoutMs || 10 * 60_000,
+      timeoutMs: resolveTimeoutMs('expo-export-embed', 10 * 60_000, options.timeoutMs),
     });
 
     if (result.code !== 0 || result.timedOut) {

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/native/build.ts

@@ -12,6 +12,7 @@ import { progress, type Log } from '../log';
 import { toPosixPath } from '../path';
 import { runCheckedAsync } from '../process';
 import { timedAsync } from '../profile';
+import { resolveTimeoutMs } from '../timeout';
 
 export interface NativeBuildResult {
   export: null | { assetCount: number; bundleSha256: string; sourceMapSha256: string };
@@ -70,7 +71,7 @@ export async function buildNativeAsync(
     },
     message: 'Hvigor build',
     operation: 'hvigor-build',
-    timeoutMs: 15 * 60_000,
+    timeoutMs: resolveTimeoutMs('hvigor-build', 15 * 60_000),
   }));
 
   if (!isNonEmptyRegularFile(plan.expectedHap)) {

package/src/native/install.ts

@@ -1,6 +1,7 @@
 import type { HarmonyBuildPlan } from './types';
 import type { HarmonyToolchain } from './toolchain';
 import { runCheckedAsync } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 
 export async function installHarmonyDependenciesAsync(
   plan: Pick<HarmonyBuildPlan, 'harmonyRoot'>,
@@ -12,6 +13,6 @@ export async function installHarmonyDependenciesAsync(
     cwd: plan.harmonyRoot,
     message: 'OHPM install',
     operation: 'ohpm-install',
-    timeoutMs: options.timeoutMs || 5 * 60_000,
+    timeoutMs: resolveTimeoutMs('ohpm-install', 30 * 60_000, options.timeoutMs),
   });
 }

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/devices.ts

@@ -4,6 +4,7 @@ import { listEmulatorsAsync, startEmulator } from './emulators';
 import { HarmonyCliError } from '../errors';
 import { type HarmonyTool } from '../native/toolchain';
 import { formatDiagnostics, spawnAsync, type ProcessResult } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 
 interface Device {
   aliases: string[];
@@ -74,7 +75,7 @@ async function runHdcAsync(
     cwd: options.cwd,
     operation: options.operation || 'hdc',
     outputLimit: options.outputLimit || 256 * 1024,
-    timeoutMs: options.timeoutMs || 60_000,
+    timeoutMs: resolveTimeoutMs(options.operation || 'hdc', 60_000, options.timeoutMs),
   });
 
   if (!options.allowFailure && hasCommandFailure(result)) {
@@ -95,7 +96,7 @@ async function listConnectedDevicesAsync(hdc: HarmonyTool, options: HdcOptions):
     cwd: options.cwd,
     message: 'Cannot list Harmony devices',
     operation: 'list-devices',
-    timeoutMs: options.timeoutMs || 15_000,
+    timeoutMs: resolveTimeoutMs('list-devices', 15_000, options.timeoutMs),
   });
   const targets = parseHdcTargets(result.stdout || result.stderr);
   return targets.filter(target => target.state.toLowerCase() === 'connected');
@@ -173,7 +174,7 @@ async function selectDeviceAsync(
   }
 
   options.onProgress?.(`Waiting for Harmony emulator ${instance.name} to connect`);
-  const deadline = Date.now() + (options.timeoutMs || 120_000);
+  const deadline = Date.now() + resolveTimeoutMs('start-emulator', 120_000, options.timeoutMs);
   while (Date.now() < deadline) {
     launch?.assertRunning();
     const devices = await listConnectedDevicesAsync(hdc, {
@@ -223,7 +224,7 @@ async function installHapAsync(
     cwd: options.cwd,
     message: `Cannot install the Harmony HAP on ${device.id}`,
     operation: 'install-hap',
-    timeoutMs: options.timeoutMs || 2 * 60_000,
+    timeoutMs: resolveTimeoutMs('install-hap', 2 * 60_000, options.timeoutMs),
   });
 }
 
@@ -247,7 +248,7 @@ async function configureMetroPortAsync(
   const forwards = await runHdcAsync(hdc, ['-t', device.id, 'fport', 'ls'], {
     cwd: options.cwd,
     operation: 'list-metro-ports',
-    timeoutMs: 15_000,
+    timeoutMs: resolveTimeoutMs('list-metro-ports', 15_000, options.timeoutMs),
   });
 
   for (const line of forwards.stdout.split(/\r?\n/u)) {
@@ -258,7 +259,7 @@ async function configureMetroPortAsync(
     await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', remote, local], {
       cwd: options.cwd,
       operation: 'remove-metro-port',
-      timeoutMs: 15_000,
+      timeoutMs: resolveTimeoutMs('remove-metro-port', 15_000, options.timeoutMs),
     });
   }
 
@@ -267,7 +268,7 @@ async function configureMetroPortAsync(
     cwd: options.cwd,
     message: `Cannot reverse Metro port ${port} for ${device.id}`,
     operation: 'reverse-metro-port',
-    timeoutMs: 15_000,
+    timeoutMs: resolveTimeoutMs('reverse-metro-port', 15_000, options.timeoutMs),
   });
 }
 
@@ -288,7 +289,7 @@ async function launchAppAsync(
     allowFailure: true,
     cwd: options.cwd,
     operation: 'force-stop-app',
-    timeoutMs: 15_000,
+    timeoutMs: resolveTimeoutMs('force-stop-app', 15_000),
   });
 
   await runHdcAsync(hdc, [
@@ -303,7 +304,7 @@ async function launchAppAsync(
     cwd: options.cwd,
     message: `Cannot launch ${bundleName} on ${device.id}`,
     operation: 'launch-app',
-    timeoutMs: 30_000,
+    timeoutMs: resolveTimeoutMs('launch-app', 30_000),
   });
 }
 

package/src/run/emulators.ts

@@ -4,6 +4,7 @@ import spawn from 'cross-spawn';
 
 import { HarmonyCliError } from '../errors';
 import { formatDiagnostics, spawnAsync } from '../process';
+import { resolveTimeoutMs } from '../timeout';
 import { type HarmonyTool } from '../native/toolchain';
 
 interface HarmonyEmulator {
@@ -21,7 +22,7 @@ async function listEmulatorsAsync(
       capture: true,
       cwd: options.cwd,
       operation: 'list-emulators',
-      timeoutMs: options.timeoutMs || 15_000,
+      timeoutMs: resolveTimeoutMs('list-emulators', 15_000, options.timeoutMs),
     });
   } catch (cause) {
     throw new HarmonyCliError(

package/src/run/metro.ts

@@ -1,9 +1,11 @@
 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';
 import { resolveExpoCli } from '../expo';
+import { resolveTimeoutMs } from '../timeout';
 
 type MetroStatus = 'free' | 'metro' | 'occupied';
 
@@ -101,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 () => {},
@@ -136,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,
@@ -155,7 +158,7 @@ async function startExpoMetroAsync(
   );
 
   const startedAt = Date.now();
-  const timeoutMs = options.readyTimeoutMs || 1800000;
+  const timeoutMs = resolveTimeoutMs('metro-ready', 30 * 60_000, options.readyTimeoutMs);
 
   try {
     while (Date.now() - startedAt < timeoutMs) {
@@ -192,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],

package/src/timeout.ts

@@ -0,0 +1,35 @@
+const TimeoutEnvPrefix = 'EXPO_HARMONY_';
+
+const warnedEnvNames = new Set<string>();
+
+function timeoutEnvName(operation: string): string {
+  return `${TimeoutEnvPrefix}${operation.toUpperCase().replace(/-/gu, '_')}_TIMEOUT_MS`;
+}
+
+function timeoutFromEnv(operation: string): number | null {
+  const name = timeoutEnvName(operation);
+  const raw = process.env[name];
+  if (!raw) return null;
+
+  const parsed = Number(raw);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+
+  if (!warnedEnvNames.has(name)) {
+    warnedEnvNames.add(name);
+    console.warn(`Ignoring unsupported ${name} value: ${raw}. Use a positive number of milliseconds.`);
+  }
+  return null;
+}
+
+/**
+ * Resolves a command timeout: explicit option first, then the
+ * `EXPO_HARMONY_<OPERATION>_TIMEOUT_MS` environment variable derived from the
+ * operation name (dashes become underscores), then the built-in default.
+ */
+function resolveTimeoutMs(operation: string, fallbackMs: number, explicitMs?: number): number {
+  return explicitMs && explicitMs > 0
+    ? explicitMs
+    : timeoutFromEnv(operation) ?? fallbackMs;
+}
+
+export { resolveTimeoutMs, timeoutEnvName };