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

package/README.md

@@ -14,7 +14,7 @@ npm install --save-dev @expo-harmony/cli
 
 通过 Expo 配置生成原生工程的项目（CNG），还需要在 Expo 配置中注册 `@expo-harmony/prebuild-config` 插件。
 
-手工维护 `harmony/` 工程的项目可以使用 bare 模式，按原生工程中的配置构建和运行，无需注册 prebuild 插件。接入步骤见 [bare 文档](../../docs/BARE_WORKFLOW.md)。
+手工维护 `harmony/` 工程的项目可以使用 bare 模式，按原生工程中的配置构建和运行，无需注册 prebuild 插件。
 
 构建 HAP 需要 HarmonyOS SDK（含 HMS 和 OpenHarmony 组件）、OHPM 和 Hvigor。连接设备或模拟器还需要 HDC。可以运行 `npx expo-harmony doctor` 检查环境。
 
@@ -80,7 +80,7 @@ npx expo-harmony prebuild --check
 
 `--clean` 删除原生工程后重新生成。如果工程缺少 CNG 清单或模板标记，或者目录是符号链接、位于项目之外，命令会拒绝删除。
 
-`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0；有差异时列出变更，退出码为 2。它不能与其他会修改工程的选项一起使用。
+`--check` 比较现有文件与当前配置生成的文件，不修改项目文件。没有差异时退出码为 0，有差异时列出变更并以退出码 2 结束。这个选项不能和会修改工程的选项一起使用。
 
 ## Build
 
@@ -94,7 +94,7 @@ npx expo-harmony build --sync
 
 默认构建 Debug 版本。使用 `--variant release` 构建 Release 版本时，命令会将 JS Bundle 和资源打包进应用。
 
-项目没有原生工程时，命令会先运行 prebuild。已有 CNG 工程时，会检查生成的文件是否需要更新；有差异时停止构建，可以使用 `--sync` 重新生成后继续构建。bare 工程按现有原生配置构建，不支持 `--sync`。
+项目没有原生工程时，命令会先运行 prebuild。已有 CNG 工程时，会检查生成的文件是否需要更新，有差异就停止构建，可以用 `--sync` 重新生成后继续构建。bare 工程按现有原生配置构建，不支持 `--sync`。
 
 ## Doctor
 
@@ -154,7 +154,7 @@ npx expo-harmony run \
   --port 8081
 ```
 
-`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程；如果工程不存在，会先运行 prebuild。
+`run` 构建 HAP，在设备或模拟器上安装并启动应用。它使用项目中已有的原生工程，工程不存在时先运行 prebuild。
 
 常用选项：
 
@@ -169,7 +169,7 @@ npx expo-harmony run \
 
 Debug 模式下，如果 Metro 由这个命令启动，日志会显示在当前终端，按 Ctrl+C 退出。
 
-未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器；如果也没有正在启动的模拟器，就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
+未指定 `--device` 时，优先使用已连接的设备。没有连接的设备时，先等待正在启动的模拟器，没有的话就启动本地唯一的模拟器。有多个可选设备或模拟器时，需要用 `--device` 指定。
 
 按名称选择或自动启动模拟器时，CLI 会等待模拟器开机并连接 HDC，最多等待 120 秒。退出 CLI 或 Metro 后，模拟器继续运行。
 
@@ -191,6 +191,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/manifest.js

@@ -26,7 +26,7 @@ async function createManifestResponseAsync(middleware, options, require) {
     bundle.searchParams.set('lazy', 'false');
     const name = exp.harmony?.bundleName || (await (0, project_1.resolveHarmonyBuildPlanAsync)(middleware.projectRoot)).bundleName;
     const id = exp.extra?.eas?.projectId;
-    const address = `${bundle.origin}${protocol_1.HarmonyManifestPath}?platform=harmony`;
+    const address = (0, protocol_1.canonicalHarmonyManifestURL)(`${bundle.origin}${options.harmonyManifestPath ?? `${protocol_1.HarmonyManifestPath}?platform=harmony`}`);
     const manifest = JSON.stringify({
         id: node_crypto_1.default.randomUUID(),
         createdAt: new Date().toISOString(),
@@ -77,6 +77,23 @@ function installHarmonyManifest(root) {
     const { BundlerDevServer } = require('./build/src/start/server/BundlerDevServer');
     const { parsePlatformHeader } = require('./build/src/start/server/middleware/resolvePlatform');
     const create = BundlerDevServer.prototype.getManifestMiddlewareAsync;
+    // Reuse Expo's terminal QR renderer and dev-session publishing with our
+    // registered link, rather than emitting a second, incompatible QR code.
+    const nativeURL = BundlerDevServer.prototype.getNativeRuntimeUrl;
+    const redirectURL = BundlerDevServer.prototype.getRedirectUrl;
+    BundlerDevServer.prototype.getNativeRuntimeUrl = function (options = {}) {
+        const address = this.getUrlCreator().constructUrl({ ...options, scheme: 'http' });
+        if (!address)
+            return nativeURL.call(this, options);
+        const manifest = new URL(protocol_1.HarmonyManifestPath, address);
+        manifest.searchParams.set('platform', 'harmony');
+        return (0, protocol_1.createHarmonyLaunchLink)(manifest.toString());
+    };
+    BundlerDevServer.prototype.getRedirectUrl = function (platform = null) {
+        return platform === null || platform === 'harmony'
+            ? this.getNativeRuntimeUrl()
+            : redirectURL.call(this, platform);
+    };
     // Expo installs the manifest before Metro's enhancer; adapt only the created instance.
     BundlerDevServer.prototype.getManifestMiddlewareAsync = async function (...args) {
         const middleware = await create.apply(this, args);
@@ -87,10 +104,14 @@ function installHarmonyManifest(root) {
                 return parse.call(middleware, request);
             // Bypass only the upstream platform assertion without changing the actual request.
             const url = new URL(request.url, 'http://localhost');
+            url.searchParams.delete('platform');
+            url.searchParams.append('platform', 'harmony');
+            const manifest = new URL((0, protocol_1.canonicalHarmonyManifestURL)(url.toString()));
+            const harmonyManifestPath = manifest.pathname + manifest.search;
             url.searchParams.set('platform', 'ios');
             const copy = Object.create(request);
             copy.url = url.pathname + url.search;
-            return { ...parse.call(middleware, copy), platform: 'harmony' };
+            return { ...parse.call(middleware, copy), platform: 'harmony', harmonyManifestPath };
         };
         middleware._getManifestResponseAsync = options => options.platform === 'harmony'
             ? createManifestResponseAsync(middleware, options, require)

package/build/development/protocol.d.ts

@@ -1,2 +1,3 @@
 export declare const HarmonyManifestPath = "/manifest";
+export declare function canonicalHarmonyManifestURL(value: string): string;
 export declare function createHarmonyLaunchLink(manifest: string): string;

package/build/development/protocol.js

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

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");
@@ -179,7 +180,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/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/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,16 +156,23 @@ 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 = {}) {
+    if (options.devicePort === undefined && port !== 8081) {
+        // RNOH's default provider uses 8081; launcher manifests retain Metro's
+        // advertised port for the bundle, assets, HMR and inspector URLs.
+        await configureMetroPortAsync(hdc, device, port, { ...options, devicePort: 8081 });
+        await configureMetroPortAsync(hdc, device, port, { ...options, devicePort: port });
+        return;
+    }
     const deviceEndpoint = `tcp:${options.devicePort || 8081}`;
     const hostEndpoint = `tcp:${port}`;
     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);
@@ -175,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], {
@@ -183,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 = {}) {
@@ -197,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,
@@ -211,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

@@ -10,6 +10,7 @@ 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));
 }
@@ -107,7 +108,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) {

package/build/runtime/config.d.ts

@@ -11,8 +11,9 @@ export declare function readNativeRuntime(plan: HarmonyBuildPlan): {
     app: any;
     config: {
         nativeCompiler: string;
-        targetApiVersion: number;
-        compatibleApiVersion: number;
+        targetApiVersion: number | string;
+        compatibleApiVersion: number | string;
+        nativeLibFilterHash?: string;
         permissions: string[];
         querySchemes: string[];
         backgroundModes: string[];
@@ -24,8 +25,9 @@ export declare function readProjectRuntimeAsync(root: string): Promise<{
     bundleName: string;
     native: {
         nativeCompiler: string;
-        targetApiVersion: number;
-        compatibleApiVersion: number;
+        targetApiVersion: number | string;
+        compatibleApiVersion: number | string;
+        nativeLibFilterHash?: string;
         permissions: string[];
         querySchemes: string[];
         backgroundModes: string[];

package/build/runtime/config.js

@@ -8,6 +8,7 @@ exports.readMetroRuntimeAsync = readMetroRuntimeAsync;
 exports.readNativeRuntime = readNativeRuntime;
 exports.readProjectRuntimeAsync = readProjectRuntimeAsync;
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = require("node:crypto");
 const node_module_1 = require("node:module");
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("@expo/config");
@@ -56,6 +57,55 @@ async function readMetroRuntimeAsync(root) {
     }
     return config?.resolver?.resolveRequest?.harmonyRuntime;
 }
+function onlyKeys(value, keys) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.keys(value).every(key => keys.includes(key));
+}
+function optionalStrings(value) {
+    return value === undefined || (Array.isArray(value) && value.every(item => typeof item === 'string' && item.length > 0));
+}
+function supportedReleaseOptions(modes) {
+    if (modes === undefined)
+        return true;
+    if (!Array.isArray(modes) || modes.length > 1)
+        return false;
+    return modes.every((mode) => {
+        if (!onlyKeys(mode, ['name', 'arkOptions', 'nativeLib']) || mode.name !== 'release')
+            return false;
+        if (mode.nativeLib !== undefined) {
+            const symbol = mode.nativeLib?.debugSymbol;
+            if (!onlyKeys(mode.nativeLib, ['debugSymbol']) || !onlyKeys(symbol, ['strip', 'exclude'])
+                || typeof symbol.strip !== 'boolean' || !optionalStrings(symbol.exclude))
+                return false;
+        }
+        if (mode.arkOptions !== undefined) {
+            const obfuscation = mode.arkOptions?.obfuscation;
+            const rules = obfuscation?.ruleOptions;
+            if (!onlyKeys(mode.arkOptions, ['obfuscation']) || !onlyKeys(obfuscation, ['ruleOptions'])
+                || !onlyKeys(rules, ['enable', 'files']) || typeof rules.enable !== 'boolean'
+                || !optionalStrings(rules.files))
+                return false;
+        }
+        return true;
+    });
+}
+function nativeLibFilterHash(filter) {
+    if (filter === undefined)
+        return undefined;
+    if (!onlyKeys(filter, ['excludes', 'pickFirsts', 'pickLasts', 'enableOverride'])
+        || !['excludes', 'pickFirsts', 'pickLasts'].every(key => optionalStrings(filter[key]))
+        || (filter.enableOverride !== undefined && typeof filter.enableOverride !== 'boolean')) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_RUNTIME_CONFIG', 'Unsupported nativeLib.filter configuration.', { operation: 'runtime-contract' });
+    }
+    const values = {};
+    for (const key of ['excludes', 'pickFirsts', 'pickLasts']) {
+        if (filter[key]?.length)
+            values[key] = [...new Set(filter[key])].sort();
+    }
+    if (filter.enableOverride)
+        values['enableOverride'] = true;
+    return Object.keys(values).length ? (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(values)).digest('hex') : undefined;
+}
 function nativeConfig(profile, module, build, product, ability) {
     const selected = profile?.app?.products?.find(item => item.name === product);
     const entry = module?.abilities?.find(item => item.name === ability);
@@ -63,14 +113,15 @@ function nativeConfig(profile, module, build, product, ability) {
         || /(?:USE_HERMES|HERMES_V1_ENABLED)(?::BOOL)?=(?:OFF|FALSE|0)/i.test(build.buildOption?.externalNativeOptions?.arguments || '')
         || Object.keys(selected.buildOption || {}).some(key => key !== 'nativeCompiler')
         || profile.app.buildModeSet?.some(mode => mode.buildOption)
-        || build.buildOptionSet?.length || build.targets?.some(target => target.buildOption)) {
-        throw new errors_1.HarmonyCliError('ERR_HARMONY_RUNTIME_CONFIG', 'Runtime contracts require an existing Harmony product and ability, Hermes v1, and native options without per-target or per-mode overrides.', { operation: 'runtime-contract' });
+        || !supportedReleaseOptions(build.buildOptionSet) || build.targets?.some(target => target.buildOption)) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_RUNTIME_CONFIG', 'Runtime contracts require an existing Harmony product and ability, Hermes v1, and no per-target or per-mode overrides except release debugSymbol and ArkTS obfuscation rules.', { operation: 'runtime-contract' });
     }
-    const api = (value) => typeof value === 'number' ? value : Number(/\((\d+)\)$/.exec(String(value))?.[1] ?? value);
+    const hash = nativeLibFilterHash(build.buildOption?.nativeLib?.filter);
     return {
         nativeCompiler: selected.buildOption?.nativeCompiler,
-        targetApiVersion: api(selected.targetSdkVersion),
-        compatibleApiVersion: api(selected.compatibleSdkVersion),
+        targetApiVersion: (0, config_plugins_1.parseHarmonySdkVersion)(selected.targetSdkVersion, 'targetSdkVersion').api,
+        compatibleApiVersion: (0, config_plugins_1.parseHarmonySdkVersion)(selected.compatibleSdkVersion, 'compatibleSdkVersion').api,
+        ...(hash ? { nativeLibFilterHash: hash } : {}),
         permissions: [...new Set((module.requestPermissions || []).map(item => item.name))].sort(),
         querySchemes: [...new Set(module.querySchemes || [])].sort(),
         backgroundModes: [...new Set(entry.backgroundModes || [])].sort(),

package/build/runtime/contract.js

@@ -25,7 +25,7 @@ async function createRuntimeContractAsync(root, project, modules, metro) {
     const version = (name) => require(`${name}/package.json`).version;
     const native = (0, node_module_1.createRequire)(require.resolve(resolution.harmonyPackage + '/package.json'));
     const contract = {
-        schemaVersion: 1,
+        schemaVersion: (0, runtime_1.harmonyRuntimeSchemaVersion)(project.native),
         platform: 'harmony',
         runtimeVersion: project.runtimeVersion,
         development: true,
@@ -92,6 +92,7 @@ async function publishRuntimeContractAsync(root, plan) {
     requirements.development = plan.buildMode === 'debug';
     const contract = {
         ...requirements,
+        schemaVersion: (0, runtime_1.harmonyRuntimeSchemaVersion)(native.config),
         runtimeVersion: await (0, config_1.resolveRuntimeVersionAsync)(root, project.config, native.app),
         config: native.config,
     };

package/build/runtime/fingerprint.js

@@ -7,6 +7,7 @@ exports.fingerprintHarmonyAsync = fingerprintHarmonyAsync;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_module_1 = require("node:module");
+const config_1 = require("@expo/config");
 const fingerprint_1 = require("@expo/fingerprint");
 const expo_modules_autolinking_1 = require("@expo-harmony/expo-modules-autolinking");
 const errors_1 = require("../errors");
@@ -15,18 +16,22 @@ async function fingerprintHarmonyAsync(root) {
     if (!result.valid)
         throw new errors_1.HarmonyCliError('ERR_HARMONY_FINGERPRINT', 'Build and verify Harmony native modules before calculating the runtime fingerprint.', { operation: 'fingerprint' });
     const require = (0, node_module_1.createRequire)(node_path_1.default.join(root, 'package.json'));
-    const dependencies = (0, expo_modules_autolinking_1.createNativeModuleContracts)(result.modules);
+    const modules = (0, expo_modules_autolinking_1.createNativeModuleContracts)(result.modules);
+    const { exp } = (0, config_1.getConfig)(root, { skipSDKVersionRequirement: true, isModdedConfig: true });
     const generated = [];
     const previous = node_path_1.default.join(root, '.expo/harmony/export-manifest.json');
     if (node_fs_1.default.existsSync(previous)) {
         const manifest = JSON.parse(node_fs_1.default.readFileSync(previous, 'utf8'));
         generated.push(...manifest.assets.map(asset => `**/harmony/**/src/main/resources/rawfile/${asset.path}`));
     }
-    const sources = [{ type: 'contents', id: 'harmonyAutolinking', contents: JSON.stringify(dependencies), reasons: ['harmonyAutolinking'] }];
-    for (const name of ['@react-native-oh/react-native-harmony', '@expo-harmony/template', '@expo-harmony/config-plugins', '@expo-harmony/prebuild-config']) {
+    const sources = [{ type: 'contents', id: 'harmonyAutolinking', contents: JSON.stringify(modules), reasons: ['harmonyAutolinking'] }];
+    for (const name of ['@react-native-oh/react-native-harmony', '@expo-harmony/template', '@expo-harmony/config-plugins', '@expo-harmony/prebuild-config', '@expo-harmony/expo-build-properties']) {
         const file = require.resolve(name + '/package.json');
         sources.push({ type: 'dir', filePath: node_path_1.default.relative(root, node_path_1.default.dirname(file)), reasons: ['harmonyNativeToolchain'] });
     }
+    for (const file of exp._internal?.harmonyBuildProperties?.release?.obfuscation?.files ?? []) {
+        sources.push({ type: 'file', filePath: file, reasons: ['harmonyObfuscationRules'] });
+    }
     if (node_fs_1.default.existsSync(node_path_1.default.join(root, 'harmony')))
         sources.push({ type: 'dir', filePath: 'harmony', reasons: ['harmonyNativeProject'] });
     return (0, fingerprint_1.createFingerprintAsync)(root, {

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.10",
+  "version": "55.0.26-harmony.12",
   "keywords": [
     "react-native",
     "expo",
@@ -51,9 +51,9 @@
     "expo-harmony": "build/bin/expo-harmony.js"
   },
   "dependencies": {
-    "@expo-harmony/config-plugins": "55.0.10-harmony.4",
-    "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.4",
-    "@expo-harmony/prebuild-config": "55.0.0-harmony.8",
+    "@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/config": "55.0.17",
     "@expo/fingerprint": "0.16.7",
     "cross-spawn": "^7.0.6",

package/src/development/manifest.ts

@@ -5,7 +5,7 @@ import { HarmonyCliError } from '../errors';
 import { resolveExpoCli } from '../expo';
 import { resolveHarmonyBuildPlanAsync } from '../native/project';
 import { resolveRuntimeRequirementsAsync } from '../runtime/contract';
-import { createHarmonyLaunchLink, HarmonyManifestPath } from './protocol';
+import { canonicalHarmonyManifestURL, createHarmonyLaunchLink, HarmonyManifestPath } from './protocol';
 
 async function createManifestResponseAsync(middleware, options, require: NodeRequire) {
   const { ExpoGoManifestHandlerMiddleware: Manifest, ResponseContentType: Types } = require('./build/src/start/server/middleware/ExpoGoManifestHandlerMiddleware');
@@ -24,7 +24,7 @@ async function createManifestResponseAsync(middleware, options, require: NodeReq
 
   const name = exp.harmony?.bundleName || (await resolveHarmonyBuildPlanAsync(middleware.projectRoot)).bundleName;
   const id = exp.extra?.eas?.projectId;
-  const address = `${bundle.origin}${HarmonyManifestPath}?platform=harmony`;
+  const address = canonicalHarmonyManifestURL(`${bundle.origin}${options.harmonyManifestPath ?? `${HarmonyManifestPath}?platform=harmony`}`);
   const manifest = JSON.stringify({
     id: crypto.randomUUID(),
     createdAt: new Date().toISOString(),
@@ -80,6 +80,23 @@ export function installHarmonyManifest(root: string) {
   const { parsePlatformHeader } = require('./build/src/start/server/middleware/resolvePlatform');
   const create = BundlerDevServer.prototype.getManifestMiddlewareAsync;
 
+  // Reuse Expo's terminal QR renderer and dev-session publishing with our
+  // registered link, rather than emitting a second, incompatible QR code.
+  const nativeURL = BundlerDevServer.prototype.getNativeRuntimeUrl;
+  const redirectURL = BundlerDevServer.prototype.getRedirectUrl;
+  BundlerDevServer.prototype.getNativeRuntimeUrl = function (options = {}) {
+    const address = this.getUrlCreator().constructUrl({ ...options, scheme: 'http' });
+    if (!address) return nativeURL.call(this, options);
+    const manifest = new URL(HarmonyManifestPath, address);
+    manifest.searchParams.set('platform', 'harmony');
+    return createHarmonyLaunchLink(manifest.toString());
+  };
+  BundlerDevServer.prototype.getRedirectUrl = function (platform = null) {
+    return platform === null || platform === 'harmony'
+      ? this.getNativeRuntimeUrl()
+      : redirectURL.call(this, platform);
+  };
+
   // Expo installs the manifest before Metro's enhancer; adapt only the created instance.
   BundlerDevServer.prototype.getManifestMiddlewareAsync = async function (this: object, ...args) {
     const middleware = await create.apply(this, args);
@@ -91,11 +108,15 @@ export function installHarmonyManifest(root: string) {
 
       // Bypass only the upstream platform assertion without changing the actual request.
       const url = new URL(request.url, 'http://localhost');
+      url.searchParams.delete('platform');
+      url.searchParams.append('platform', 'harmony');
+      const manifest = new URL(canonicalHarmonyManifestURL(url.toString()));
+      const harmonyManifestPath = manifest.pathname + manifest.search;
       url.searchParams.set('platform', 'ios');
       const copy = Object.create(request);
       copy.url = url.pathname + url.search;
 
-      return { ...parse.call(middleware, copy), platform: 'harmony' };
+      return { ...parse.call(middleware, copy), platform: 'harmony', harmonyManifestPath };
     };
     middleware._getManifestResponseAsync = options => options.platform === 'harmony'
       ? createManifestResponseAsync(middleware, options, require)

package/src/development/protocol.ts

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

package/src/doctor/doctor.ts

@@ -8,6 +8,7 @@ import { verifyModulesAsync } from '@expo-harmony/expo-modules-autolinking';
 import { 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';
@@ -221,7 +222,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/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/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),
   });
 }
 
@@ -233,13 +234,21 @@ async function configureMetroPortAsync(
   port: number,
   options: HdcOptions = {}
 ): Promise<void> {
+  if (options.devicePort === undefined && port !== 8081) {
+    // RNOH's default provider uses 8081; launcher manifests retain Metro's
+    // advertised port for the bundle, assets, HMR and inspector URLs.
+    await configureMetroPortAsync(hdc, device, port, { ...options, devicePort: 8081 });
+    await configureMetroPortAsync(hdc, device, port, { ...options, devicePort: port });
+    return;
+  }
+
   const deviceEndpoint = `tcp:${options.devicePort || 8081}`;
   const hostEndpoint = `tcp:${port}`;
 
   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)) {
@@ -250,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),
     });
   }
 
@@ -259,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),
   });
 }
 
@@ -280,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, [
@@ -295,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

@@ -4,6 +4,7 @@ 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';
 
@@ -155,7 +156,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) {

package/src/runtime/config.ts

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
+import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
 import { getConfig } from '@expo/config';
-import { compileHarmonyModsAsync, normalizeHarmonyConfig, type ExpoConfigWithHarmony } from '@expo-harmony/config-plugins';
-import { withHarmonyPrebuildConfig } from '@expo-harmony/prebuild-config';
+import { compileHarmonyModsAsync, normalizeHarmonyConfig, parseHarmonySdkVersion, type ExpoConfigWithHarmony } from '@expo-harmony/config-plugins';
 import type { HarmonyRuntimeContract } from '@expo-harmony/expo-modules-autolinking/runtime';
+import { withHarmonyPrebuildConfig } from '@expo-harmony/prebuild-config';
 import JSON5 from 'json5';
 
 import { fingerprintHarmonyAsync } from './fingerprint';
@@ -72,27 +73,83 @@ export async function readMetroRuntimeAsync(root: string): Promise<HarmonyMetroR
   return config?.resolver?.resolveRequest?.harmonyRuntime;
 }
 
+function onlyKeys(value, keys: string[]): boolean {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).every(key => keys.includes(key));
+}
+
+function optionalStrings(value): boolean {
+  return value === undefined || (Array.isArray(value) && value.every(item => typeof item === 'string' && item.length > 0));
+}
+
+function supportedReleaseOptions(modes): boolean {
+  if (modes === undefined) return true;
+  if (!Array.isArray(modes) || modes.length > 1) return false;
+
+  return modes.every((mode) => {
+    if (!onlyKeys(mode, ['name', 'arkOptions', 'nativeLib']) || mode.name !== 'release') return false;
+
+    if (mode.nativeLib !== undefined) {
+      const symbol = mode.nativeLib?.debugSymbol;
+
+      if (!onlyKeys(mode.nativeLib, ['debugSymbol']) || !onlyKeys(symbol, ['strip', 'exclude'])
+        || typeof symbol.strip !== 'boolean' || !optionalStrings(symbol.exclude)) return false;
+    }
+
+    if (mode.arkOptions !== undefined) {
+      const obfuscation = mode.arkOptions?.obfuscation;
+      const rules = obfuscation?.ruleOptions;
+
+      if (!onlyKeys(mode.arkOptions, ['obfuscation']) || !onlyKeys(obfuscation, ['ruleOptions'])
+        || !onlyKeys(rules, ['enable', 'files']) || typeof rules.enable !== 'boolean'
+        || !optionalStrings(rules.files)) return false;
+    }
+
+    return true;
+  });
+}
+
+function nativeLibFilterHash(filter): string | undefined {
+  if (filter === undefined) return undefined;
+  if (!onlyKeys(filter, ['excludes', 'pickFirsts', 'pickLasts', 'enableOverride'])
+    || !['excludes', 'pickFirsts', 'pickLasts'].every(key => optionalStrings(filter[key]))
+    || (filter.enableOverride !== undefined && typeof filter.enableOverride !== 'boolean')) {
+    throw new HarmonyCliError('ERR_HARMONY_RUNTIME_CONFIG', 'Unsupported nativeLib.filter configuration.', { operation: 'runtime-contract' });
+  }
+
+  const values = {};
+
+  for (const key of ['excludes', 'pickFirsts', 'pickLasts']) {
+    if (filter[key]?.length) values[key] = [...new Set(filter[key])].sort();
+  }
+  if (filter.enableOverride) values['enableOverride'] = true;
+
+  return Object.keys(values).length ? createHash('sha256').update(JSON.stringify(values)).digest('hex') : undefined;
+}
+
 function nativeConfig(profile, module, build, product: string, ability: string): HarmonyRuntimeContract['config'] {
   const selected = profile?.app?.products?.find(item => item.name === product);
   const entry = module?.abilities?.find(item => item.name === ability);
+
   if (!selected || !entry || !build
     || /(?:USE_HERMES|HERMES_V1_ENABLED)(?::BOOL)?=(?:OFF|FALSE|0)/i.test(build.buildOption?.externalNativeOptions?.arguments || '')
     || Object.keys(selected.buildOption || {}).some(key => key !== 'nativeCompiler')
     || profile.app.buildModeSet?.some(mode => mode.buildOption)
-    || build.buildOptionSet?.length || build.targets?.some(target => target.buildOption)) {
+    || !supportedReleaseOptions(build.buildOptionSet) || build.targets?.some(target => target.buildOption)) {
     throw new HarmonyCliError(
       'ERR_HARMONY_RUNTIME_CONFIG',
-      'Runtime contracts require an existing Harmony product and ability, Hermes v1, and native options without per-target or per-mode overrides.',
+      'Runtime contracts require an existing Harmony product and ability, Hermes v1, and no per-target or per-mode overrides except release debugSymbol and ArkTS obfuscation rules.',
       { operation: 'runtime-contract' }
     );
   }
 
-  const api = (value: unknown) => typeof value === 'number' ? value : Number(/\((\d+)\)$/.exec(String(value))?.[1] ?? value);
+  const hash = nativeLibFilterHash(build.buildOption?.nativeLib?.filter);
 
   return {
     nativeCompiler: selected.buildOption?.nativeCompiler,
-    targetApiVersion: api(selected.targetSdkVersion),
-    compatibleApiVersion: api(selected.compatibleSdkVersion),
+    targetApiVersion: parseHarmonySdkVersion(selected.targetSdkVersion, 'targetSdkVersion').api,
+    compatibleApiVersion: parseHarmonySdkVersion(selected.compatibleSdkVersion, 'compatibleSdkVersion').api,
+    ...(hash ? { nativeLibFilterHash: hash } : {}),
     permissions: [...new Set<string>((module.requestPermissions || []).map(item => item.name))].sort(),
     querySchemes: [...new Set<string>(module.querySchemes || [])].sort(),
     backgroundModes: [...new Set<string>(entry.backgroundModes || [])].sort(),

package/src/runtime/contract.ts

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 
 import { createNativeModuleContracts, ohpmDependenciesFromManifest, verifyModulesAsync, type Manifest, type ModuleDescriptor } from '@expo-harmony/expo-modules-autolinking';
-import { assertHarmonyCompatibility, validateHarmonyRuntime, type HarmonyRuntimeContract } from '@expo-harmony/expo-modules-autolinking/runtime';
+import { assertHarmonyCompatibility, harmonyRuntimeSchemaVersion, validateHarmonyRuntime, type HarmonyRuntimeContract } from '@expo-harmony/expo-modules-autolinking/runtime';
 import JSON5 from 'json5';
 
 import { publishUpdatesConfigurationAsync } from '../updates/export';
@@ -33,7 +33,7 @@ async function createRuntimeContractAsync(
   const native = createRequire(require.resolve(resolution.harmonyPackage + '/package.json'));
 
   const contract: HarmonyRuntimeContract = {
-    schemaVersion: 1,
+    schemaVersion: harmonyRuntimeSchemaVersion(project.native),
     platform: 'harmony',
     runtimeVersion: project.runtimeVersion,
     development: true,
@@ -143,8 +143,10 @@ export async function publishRuntimeContractAsync(
 
   const native = readNativeRuntime(plan);
   requirements.development = plan.buildMode === 'debug';
+
   const contract: HarmonyRuntimeContract = {
     ...requirements,
+    schemaVersion: harmonyRuntimeSchemaVersion(native.config),
     runtimeVersion: await resolveRuntimeVersionAsync(root, project.config, native.app),
     config: native.config,
   };

package/src/runtime/fingerprint.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { getConfig } from '@expo/config';
 import { createFingerprintAsync, type HashSource } from '@expo/fingerprint';
 import { createNativeModuleContracts, verifyModulesAsync } from '@expo-harmony/expo-modules-autolinking';
 import { HarmonyCliError } from '../errors';
@@ -10,18 +11,27 @@ export async function fingerprintHarmonyAsync(root: string) {
   if (!result.valid) throw new HarmonyCliError('ERR_HARMONY_FINGERPRINT', 'Build and verify Harmony native modules before calculating the runtime fingerprint.', { operation: 'fingerprint' });
 
   const require = createRequire(path.join(root, 'package.json'));
-  const dependencies = createNativeModuleContracts(result.modules);
+  const modules = createNativeModuleContracts(result.modules);
+  const { exp } = getConfig(root, { skipSDKVersionRequirement: true, isModdedConfig: true });
   const generated: string[] = [];
   const previous = path.join(root, '.expo/harmony/export-manifest.json');
+
   if (fs.existsSync(previous)) {
     const manifest = JSON.parse(fs.readFileSync(previous, 'utf8'));
     generated.push(...manifest.assets.map(asset => `**/harmony/**/src/main/resources/rawfile/${asset.path}`));
   }
-  const sources: HashSource[] = [{ type: 'contents', id: 'harmonyAutolinking', contents: JSON.stringify(dependencies), reasons: ['harmonyAutolinking'] }];
-  for (const name of ['@react-native-oh/react-native-harmony', '@expo-harmony/template', '@expo-harmony/config-plugins', '@expo-harmony/prebuild-config']) {
+
+  const sources: HashSource[] = [{ type: 'contents', id: 'harmonyAutolinking', contents: JSON.stringify(modules), reasons: ['harmonyAutolinking'] }];
+
+  for (const name of ['@react-native-oh/react-native-harmony', '@expo-harmony/template', '@expo-harmony/config-plugins', '@expo-harmony/prebuild-config', '@expo-harmony/expo-build-properties']) {
     const file = require.resolve(name + '/package.json');
     sources.push({ type: 'dir', filePath: path.relative(root, path.dirname(file)), reasons: ['harmonyNativeToolchain'] });
   }
+
+  for (const file of exp._internal?.harmonyBuildProperties?.release?.obfuscation?.files ?? []) {
+    sources.push({ type: 'file', filePath: file, reasons: ['harmonyObfuscationRules'] });
+  }
+
   if (fs.existsSync(path.join(root, 'harmony'))) sources.push({ type: 'dir', filePath: 'harmony', reasons: ['harmonyNativeProject'] });
 
   return createFingerprintAsync(root, {

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 };