@expo-harmony/cli 55.0.26-harmony.3 → 55.0.26-harmony.5

package/README.md

@@ -50,7 +50,9 @@ npx expo-harmony start --port 8082
 npx expo-harmony start --clear
 ```
 
-`start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro，并自动设置 `EXPO_METRO_TARGET=harmony`。它只启动 JS 开发服务，不执行原生工程生成、构建、安装、应用启动或设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。新启动的 Metro 在当前终端输出日志，按 Ctrl+C 退出。
+所有命令都会在 CLI 入口、读取应用配置之前设置 `EXPO_HARMONY=1` 和 `EXPO_METRO_TARGET=harmony`。
+
+`start` 调用项目本地的 Expo CLI，以 `--dev-client` 模式启动 Metro。它只启动 JS 开发服务，不执行原生工程生成、构建、安装、应用启动或设备端口映射，也不要求 HarmonyOS SDK 和设备就绪。新启动的 Metro 在当前终端输出日志，按 Ctrl+C 退出。
 
 支持 `--port <number>`（默认 `8081`）和 `--reset-cache`（别名 `--clear`、`-c`）。端口上已有 Metro 时提示并退出，不停止已有服务；此时缓存选项不会生效，需要先停止已有 Metro 后重新执行命令。端口被其他进程占用时会报错。
 
@@ -66,7 +68,7 @@ npx expo-harmony prebuild --check
 
 `prebuild` 固定使用 HarmonyOS 平台和 `@expo-harmony/template` 模板，因此不像官方接受 `--platform` 和 `--template`。依赖安装相关选项会透传给 Expo CLI：`--no-install`、`--npm`/`--yarn`/`--pnpm`/`--bun`（最多选择一个）和 `--skip-dependency-update <packages>`。执行前会先运行一次 doctor（此阶段不要求构建工具就绪），发现阻塞错误时直接中止。
 
-`--clean` 只会清理带有 Expo Harmony 模板标记的原生目录：CNG manifest 缺失、目标不是项目内的普通目录或模板标记异常时都会拒绝删除。`--check` 是只读操作，会把项目镜像到临时目录（`node_modules` 以符号链接共享，不复制），在其中执行一次隔离的 prebuild 后比较受管文件；无差异时退出码为 `0`，有差异时列出变更并以 `2` 退出，且不能与其他会修改工程的选项同时使用。
+`--clean` 只会清理带有 Expo Harmony 模板标记的原生目录：CNG manifest 缺失、目标不是项目内的普通目录或模板标记异常时都会拒绝删除。`--check` 是只读操作，会把项目镜像到临时目录（`node_modules` 中的包目录通过链接共享，Windows 下的普通文件复制到临时目录，无须文件符号链接权限），在其中执行一次隔离的 prebuild 后比较受管文件；无差异时退出码为 `0`，有差异时列出变更并以 `2` 退出，且不能与其他会修改工程的选项同时使用。
 
 ## Build
 

package/build/cli.js

@@ -78,6 +78,8 @@ function parseInvocation(argv) {
     return { command, parsed, projectRoot };
 }
 async function runAsync(argv = process.argv.slice(2), io = console) {
+    process.env.EXPO_HARMONY = '1';
+    process.env.EXPO_METRO_TARGET = 'harmony';
     const invocation = parseInvocation(argv);
     if (invocation.command === 'help') {
         io.log(Help);

package/build/doctor/doctor.js

@@ -165,6 +165,7 @@ async function doctorUnlockedAsync(projectRoot, options = {}) {
         tools.unshift(['hdc', toolchain.hdc, ['-v'], unavailableToolStatus]);
     }
     for (const [id, tool, versionArgs, unavailableStatus] of tools) {
+        const command = [tool.command, ...tool.args].map(value => JSON.stringify(value)).join(' ');
         try {
             const result = await (0, process_1.spawnAsync)(tool.command, [...tool.args, ...versionArgs], {
                 capture: true,
@@ -173,11 +174,11 @@ async function doctorUnlockedAsync(projectRoot, options = {}) {
                 timeoutMs: 10_000,
             });
             checks.push(result.code === 0 && !result.timedOut
-                ? check(id, 'pass', `${tool.command} is available through ${tool.source}.`)
-                : check(id, unavailableStatus, `${tool.command} is unavailable or unhealthy; HAP build cannot be verified.`));
+                ? check(id, 'pass', `${command} is available through ${tool.source}.`)
+                : check(id, unavailableStatus, `${command} is unavailable or unhealthy; HAP build cannot be verified.`));
         }
         catch {
-            checks.push(check(id, unavailableStatus, `${tool.command} is unavailable; generation remains available.`));
+            checks.push(check(id, unavailableStatus, `${command} is unavailable; generation remains available.`));
         }
     }
     if (options.validateGeneratedProject !== false) {

package/build/prebuild/check.js

@@ -31,6 +31,16 @@ function mirrorRoot(temp, project) {
     const segments = absolute.slice(parsed.root.length).split(node_path_1.default.sep).filter(Boolean);
     return node_path_1.default.join(temp, 'filesystem', volume, ...segments);
 }
+async function linkModuleEntryAsync(source, target, entry) {
+    const directory = entry.isSymbolicLink()
+        ? (await node_fs_1.default.promises.stat(source)).isDirectory()
+        : entry.isDirectory();
+    if (process.platform === 'win32' && !directory) {
+        await node_fs_1.default.promises.copyFile(source, target);
+        return;
+    }
+    await node_fs_1.default.promises.symlink(node_path_1.default.resolve(source), target, directory ? process.platform === 'win32' ? 'junction' : 'dir' : 'file');
+}
 async function linkModulesAsync(source, target) {
     await node_fs_1.default.promises.mkdir(target, { recursive: true });
     for (const entry of await node_fs_1.default.promises.readdir(source, { withFileTypes: true })) {
@@ -39,15 +49,11 @@ async function linkModulesAsync(source, target) {
         if (entry.name.startsWith('@') && entry.isDirectory() && !entry.isSymbolicLink()) {
             await node_fs_1.default.promises.mkdir(to);
             for (const child of await node_fs_1.default.promises.readdir(from, { withFileTypes: true })) {
-                await node_fs_1.default.promises.symlink(node_path_1.default.join(from, child.name), node_path_1.default.join(to, child.name), process.platform === 'win32' && (child.isDirectory() || child.isSymbolicLink())
-                    ? 'junction'
-                    : child.isDirectory() ? 'dir' : 'file');
+                await linkModuleEntryAsync(node_path_1.default.join(from, child.name), node_path_1.default.join(to, child.name), child);
             }
             continue;
         }
-        await node_fs_1.default.promises.symlink(from, to, process.platform === 'win32' && (entry.isDirectory() || entry.isSymbolicLink())
-            ? 'junction'
-            : entry.isDirectory() ? 'dir' : 'file');
+        await linkModuleEntryAsync(from, to, entry);
     }
 }
 function isAppLocalHarmonyPath(project, source) {
@@ -90,8 +96,8 @@ async function copyAsync(project, target, plan, temp = node_path_1.default.dirna
     // Keep a real node_modules directory in the isolated project and link its
     // entries. Dependency scanners then retain the isolated lexical package path
     // (including scoped packages) instead of collapsing the entire node_modules
-    // root to the source project's realpath. The packages remain read-only and
-    // are never copied or modified by --check.
+    // root to the source project's realpath. Package directories stay linked;
+    // Windows copies loose files to avoid requiring file-symlink privileges.
     await linkModulesAsync(modules, node_path_1.default.join(target, 'node_modules'));
     await (0, check_1.stageAsync)(project, target, temp);
 }

package/build/process.d.ts

@@ -25,7 +25,7 @@ declare function startManagedProcess(command: string, args: string[], options?:
     completion: Promise<ProcessResult>;
     getStderr: () => string;
     getStdout: () => string;
-    stop: (signal?: NodeJS.Signals, graceMs?: number) => Promise<any>;
+    stop: (signal?: NodeJS.Signals, graceMs?: number) => Promise<ProcessResult>;
     wasStopped: () => boolean;
 };
 export { formatDiagnostics, spawnAsync, startManagedProcess };

package/build/process.js

@@ -7,6 +7,7 @@ exports.formatDiagnostics = formatDiagnostics;
 exports.spawnAsync = spawnAsync;
 exports.startManagedProcess = startManagedProcess;
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
+const tool_command_1 = require("@expo-harmony/expo-modules-autolinking/tool-command");
 const errors_1 = require("./errors");
 const DefaultOutputLimit = 1024 * 1024;
 const DefaultStopGraceMs = 3_000;
@@ -53,8 +54,14 @@ function formatDiagnostics(result, limit = 4_000) {
 }
 function spawnAsync(command, args, options = {}) {
     return new Promise((resolve, reject) => {
+        if (options.signal?.aborted) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: operation aborted.`, {
+                cause: options.signal.reason,
+                operation: options.operation || 'spawn',
+            });
+        }
         const piped = Boolean(options.capture || options.onStdout || options.onStderr);
-        const outputLimit = options.outputLimit || DefaultOutputLimit;
+        const limit = options.outputLimit || DefaultOutputLimit;
         const child = (0, cross_spawn_1.default)(command, args, {
             cwd: options.cwd,
             env: options.env || process.env,
@@ -62,11 +69,12 @@ function spawnAsync(command, args, options = {}) {
             stdio: piped ? ['ignore', 'pipe', 'pipe'] : 'inherit',
             windowsHide: true,
         });
-        const stdout = new BoundedCapture(outputLimit);
-        const stderr = new BoundedCapture(outputLimit);
+        const stdout = new BoundedCapture(limit);
+        const stderr = new BoundedCapture(limit);
         let timedOut = false;
         let settled = false;
-        let forceKillTimer = null;
+        let escalation = null;
+        let stopping;
         if (piped) {
             child.stdout.on('data', (chunk) => {
                 stdout.append(chunk);
@@ -77,67 +85,91 @@ function spawnAsync(command, args, options = {}) {
                 options.onStderr?.(chunk);
             });
         }
-        const stopChild = (signal = 'SIGTERM') => {
-            child.kill(signal);
-            if (forceKillTimer === null) {
-                forceKillTimer = setTimeout(() => child.kill('SIGKILL'), options.stopGraceMs || DefaultStopGraceMs);
-                forceKillTimer.unref?.();
+        const stop = (signal = 'SIGTERM') => {
+            if (stopping || settled)
+                return;
+            stopping = Promise.resolve().then(() => (0, tool_command_1.terminateProcess)(child, signal));
+            if (process.platform === 'win32') {
+                void finish(null, signal);
+            }
+            else {
+                stopping.catch((cause) => {
+                    void finish(null, null, cause);
+                });
+                escalation = setTimeout(() => {
+                    stopping = (0, tool_command_1.terminateProcess)(child, 'SIGKILL');
+                    stopping.catch((cause) => {
+                        void finish(null, null, cause);
+                    });
+                }, options.stopGraceMs || DefaultStopGraceMs);
+                escalation.unref?.();
             }
         };
-        const forwardSigint = () => stopChild('SIGINT');
-        const forwardSigterm = () => stopChild('SIGTERM');
-        process.once('SIGINT', forwardSigint);
-        process.once('SIGTERM', forwardSigterm);
+        const interrupt = () => stop('SIGINT');
+        const terminate = () => stop('SIGTERM');
+        process.once('SIGINT', interrupt);
+        process.once('SIGTERM', terminate);
         const timeout = options.timeoutMs
             ? setTimeout(() => {
                 timedOut = true;
-                stopChild('SIGTERM');
+                stop('SIGTERM');
             }, options.timeoutMs)
             : null;
         timeout?.unref?.();
         const cleanup = () => {
             if (timeout)
                 clearTimeout(timeout);
-            if (forceKillTimer)
-                clearTimeout(forceKillTimer);
-            process.removeListener('SIGINT', forwardSigint);
-            process.removeListener('SIGTERM', forwardSigterm);
+            if (escalation)
+                clearTimeout(escalation);
+            process.removeListener('SIGINT', interrupt);
+            process.removeListener('SIGTERM', terminate);
             options.signal?.removeEventListener('abort', abort);
         };
-        const abort = () => stopChild('SIGTERM');
-        if (options.signal?.aborted)
-            abort();
-        else
-            options.signal?.addEventListener('abort', abort, { once: true });
-        child.once('error', (cause) => {
+        const finish = async (code, signal, cause) => {
+            try {
+                await stopping;
+            }
+            catch (error) {
+                cause = error;
+            }
             if (settled)
                 return;
             settled = true;
             cleanup();
-            reject(new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
-                cause,
-                operation: options.operation || 'spawn',
-            }));
+            if (cause)
+                reject(new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: ${cause.message}`, {
+                    cause,
+                    operation: options.operation || 'spawn',
+                }));
+            else
+                resolve({
+                    code: code === null ? 1 : code,
+                    signal,
+                    stderr: stderr.toString(),
+                    stdout: stdout.toString(),
+                    timedOut,
+                });
+        };
+        child.once('error', (cause) => {
+            void finish(null, null, cause);
         });
-        // `close` runs after stdout/stderr have closed, so captured diagnostics are
-        // complete. `exit` can fire while pipe data is still pending.
         child.once('close', (code, signal) => {
-            if (settled)
-                return;
-            settled = true;
-            cleanup();
-            resolve({
-                code: code === null ? 1 : code,
-                signal,
-                stderr: stderr.toString(),
-                stdout: stdout.toString(),
-                timedOut,
-            });
+            void finish(code, signal);
         });
+        const abort = () => stop('SIGTERM');
+        options.signal?.addEventListener('abort', abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
     });
 }
 function startManagedProcess(command, args, options = {}) {
-    const outputLimit = options.outputLimit || DefaultOutputLimit;
+    if (options.signal?.aborted) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: operation aborted.`, {
+            cause: options.signal.reason,
+            operation: options.operation || 'spawn',
+        });
+    }
+    const limit = options.outputLimit || DefaultOutputLimit;
     const piped = options.stdio !== 'inherit';
     const child = (0, cross_spawn_1.default)(command, args, {
         cwd: options.cwd,
@@ -146,11 +178,14 @@ function startManagedProcess(command, args, options = {}) {
         stdio: piped ? ['ignore', 'pipe', 'pipe'] : 'inherit',
         windowsHide: true,
     });
-    const stdout = new BoundedCapture(outputLimit);
-    const stderr = new BoundedCapture(outputLimit);
-    let spawnError = null;
+    const stdout = new BoundedCapture(limit);
+    const stderr = new BoundedCapture(limit);
+    let failure = null;
     let closed = false;
-    let stopRequested = false;
+    let stopped = false;
+    let stopping;
+    let stopPromise;
+    let finish;
     if (piped) {
         child.stdout.on('data', (chunk) => {
             stdout.append(chunk);
@@ -161,32 +196,42 @@ function startManagedProcess(command, args, options = {}) {
             options.onStderr?.(chunk);
         });
     }
-    const forwardSigint = () => {
-        void stop('SIGINT');
+    const interrupt = () => {
+        void stop('SIGINT').catch(() => { });
     };
-    const forwardSigterm = () => {
-        void stop('SIGTERM');
+    const terminate = () => {
+        void stop('SIGTERM').catch(() => { });
     };
     const abort = () => {
-        void stop('SIGTERM');
+        void stop('SIGTERM').catch(() => { });
     };
     const cleanup = () => {
-        process.removeListener('SIGINT', forwardSigint);
-        process.removeListener('SIGTERM', forwardSigterm);
+        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGTERM', terminate);
         options.signal?.removeEventListener('abort', abort);
     };
     const completion = new Promise((resolve, reject) => {
         child.once('error', (cause) => {
-            spawnError = new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
+            failure = new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
                 cause,
                 operation: options.operation || 'spawn',
             });
         });
-        child.once('close', (code, signal) => {
+        finish = async (code, signal) => {
+            try {
+                await stopping;
+            }
+            catch (cause) {
+                failure = new errors_1.HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot stop ${command}: ${cause.message}`, {
+                    cause, operation: options.operation || 'spawn',
+                });
+            }
+            if (closed)
+                return;
             closed = true;
             cleanup();
-            if (spawnError)
-                reject(spawnError);
+            if (failure)
+                reject(failure);
             else
                 resolve({
                     code: code === null ? 1 : code,
@@ -195,32 +240,59 @@ function startManagedProcess(command, args, options = {}) {
                     stdout: stdout.toString(),
                     timedOut: false,
                 });
+        };
+        child.once('close', (code, signal) => {
+            void finish(code, signal);
         });
     });
     // A readiness probe may be the first consumer. Keep early spawn failures from
     // becoming unhandled rejections while the probe is still polling.
     completion.catch(() => { });
     async function stop(signal = 'SIGTERM', graceMs = DefaultStopGraceMs) {
+        if (stopPromise)
+            return stopPromise;
         if (closed)
             return completion;
-        stopRequested = true;
-        child.kill(signal);
-        let timer;
-        await Promise.race([
-            completion.catch(() => undefined),
-            new Promise((resolve) => {
-                timer = setTimeout(resolve, graceMs);
-                timer.unref?.();
-            }),
-        ]);
-        if (timer)
-            clearTimeout(timer);
-        if (!closed)
-            child.kill('SIGKILL');
-        return completion.catch(() => undefined);
+        stopped = true;
+        stopping = Promise.resolve().then(() => (0, tool_command_1.terminateProcess)(child, signal));
+        stopPromise = (async () => {
+            if (process.platform === 'win32') {
+                void finish(null, signal);
+                return completion;
+            }
+            try {
+                await stopping;
+            }
+            catch {
+                await finish(null, signal);
+                return completion;
+            }
+            let timer;
+            await Promise.race([
+                completion.catch(() => undefined),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, graceMs);
+                    timer.unref?.();
+                }),
+            ]);
+            if (timer)
+                clearTimeout(timer);
+            if (!closed) {
+                stopping = (0, tool_command_1.terminateProcess)(child, 'SIGKILL');
+                try {
+                    await stopping;
+                }
+                catch {
+                    await finish(null, signal);
+                }
+            }
+            return completion.catch(() => undefined);
+        })();
+        stopPromise.catch(() => { });
+        return stopPromise;
     }
-    process.once('SIGINT', forwardSigint);
-    process.once('SIGTERM', forwardSigterm);
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', terminate);
     if (options.signal?.aborted)
         abort();
     else
@@ -231,6 +303,6 @@ function startManagedProcess(command, args, options = {}) {
         getStderr: () => stderr.toString(),
         getStdout: () => stdout.toString(),
         stop,
-        wasStopped: () => stopRequested,
+        wasStopped: () => stopped,
     };
 }

package/build/tools.js

@@ -10,6 +10,7 @@ exports.resolveHarmonyEmulator = resolveHarmonyEmulator;
 exports.resolveHarmonyToolchain = resolveHarmonyToolchain;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const tool_command_1 = require("@expo-harmony/expo-modules-autolinking/tool-command");
 const build_descriptor_1 = require("@expo-harmony/prebuild-config/build-descriptor");
 const check_1 = require("@expo-harmony/prebuild-config/check");
 const errors_1 = require("./errors");
@@ -99,38 +100,35 @@ function resolveHarmonyToolchain() {
     const layouts = sdkHome ? devEcoLayouts(sdkHome) : [];
     let ohpm;
     if (env.HARMONY_OHPM) {
-        ohpm = { args: [], command: env.HARMONY_OHPM, source: 'override' };
+        ohpm = { ...(0, tool_command_1.resolveHarmonyCommand)('ohpm', [], env), source: 'override' };
     }
     else {
-        const devEcoOhpm = existingFile(layouts.map(layout => node_path_1.default.join(layout.toolsRoot, 'ohpm', 'bin', platform === 'win32' ? 'ohpm.bat' : 'ohpm')));
-        ohpm = devEcoOhpm
-            ? { args: [], command: devEcoOhpm, source: 'deveco' }
-            : { args: [], command: platform === 'win32' ? 'ohpm.bat' : 'ohpm', source: 'path' };
+        const entry = layouts.map(layout => ({
+            node: devEcoNode(layout, platform, { ...env, HARMONY_NODE: env.HARMONY_OHPM_NODE || env.HARMONY_NODE }),
+            script: node_path_1.default.join(layout.toolsRoot, 'ohpm', 'bin', 'pm-cli.js'),
+        })).find(candidate => candidate.node && node_fs_1.default.existsSync(candidate.script));
+        const command = existingFile(layouts.map(layout => node_path_1.default.join(layout.toolsRoot, 'ohpm', 'bin', platform === 'win32' ? 'ohpm.bat' : 'ohpm')));
+        ohpm = entry
+            ? { args: [entry.script], command: entry.node.command, source: 'deveco' }
+            : command
+                ? { args: [], command, source: 'deveco' }
+                : { args: [], command: platform === 'win32' ? 'ohpm.bat' : 'ohpm', source: 'path' };
     }
     let hvigor;
     if (env.HARMONY_HVIGORW) {
-        if (/\.(?:c|m)?js$/iu.test(env.HARMONY_HVIGORW)) {
-            hvigor = {
-                args: [env.HARMONY_HVIGORW],
-                command: env.HARMONY_NODE || process.execPath,
-                source: 'override',
-            };
-        }
-        else {
-            hvigor = { args: [], command: env.HARMONY_HVIGORW, source: 'override' };
-        }
+        hvigor = { ...(0, tool_command_1.resolveHarmonyCommand)('hvigorw', [], env), source: 'override' };
     }
     else {
-        const devEcoHvigor = layouts.map(layout => ({
-            layout,
-            node: devEcoNode(layout, platform, env),
+        const entry = layouts.map(layout => ({
+            node: devEcoNode(layout, platform, { ...env, HARMONY_NODE: env.HARMONY_HVIGOR_NODE || env.HARMONY_NODE }),
             script: node_path_1.default.join(layout.toolsRoot, 'hvigor', 'bin', 'hvigorw.js'),
         })).find(candidate => candidate.node && node_fs_1.default.existsSync(candidate.script));
-        hvigor = devEcoHvigor
-            ? { args: [devEcoHvigor.script], command: devEcoHvigor.node.command, source: 'deveco' }
+        hvigor = entry
+            ? { args: [entry.script], command: entry.node.command, source: 'deveco' }
             : { args: [], command: platform === 'win32' ? 'hvigorw.bat' : 'hvigorw', source: 'path' };
     }
     const toolsRoot = layouts.find(layout => (hvigor.args[0]?.startsWith(`${layout.toolsRoot}${node_path_1.default.sep}`)
+        || ohpm.args[0]?.startsWith(`${layout.toolsRoot}${node_path_1.default.sep}`)
         || ohpm.command.startsWith(`${layout.toolsRoot}${node_path_1.default.sep}`)))?.toolsRoot || null;
     let hdc;
     if (env.HARMONY_HDC) {
@@ -151,10 +149,14 @@ function resolveHarmonyToolchain() {
 function createHarmonyToolchainEnv(toolchain = resolveHarmonyToolchain()) {
     return {
         ...process.env,
-        HARMONY_OHPM: toolchain.ohpm.command,
-        // A script-based Hvigor invocation must retain both its script and Node executable.
+        HARMONY_OHPM: toolchain.ohpm.args[0] || toolchain.ohpm.command,
+        HARMONY_OHPM_NODE: toolchain.ohpm.args.length > 0 ? toolchain.ohpm.command : undefined,
+        // Script-based tools must retain both their script and Node executable.
         HARMONY_HVIGORW: toolchain.hvigor.args[0] || toolchain.hvigor.command,
-        ...(toolchain.hvigor.args.length > 0 ? { HARMONY_NODE: toolchain.hvigor.command } : {}),
+        HARMONY_HVIGOR_NODE: toolchain.hvigor.args.length > 0 ? toolchain.hvigor.command : undefined,
+        ...(toolchain.hvigor.args.length > 0
+            ? { HARMONY_NODE: toolchain.hvigor.command }
+            : toolchain.ohpm.args.length > 0 ? { HARMONY_NODE: toolchain.ohpm.command } : {}),
         ...(toolchain.sdkHome && !process.env.DEVECO_SDK_HOME
             ? { DEVECO_SDK_HOME: toolchain.sdkHome }
             : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo-harmony/cli",
-  "version": "55.0.26-harmony.3",
+  "version": "55.0.26-harmony.5",
   "keywords": [
     "react-native",
     "expo",
@@ -37,8 +37,8 @@
   },
   "dependencies": {
     "@expo-harmony/config-plugins": "55.0.10-harmony.2",
-    "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.2",
-    "@expo-harmony/prebuild-config": "55.0.0-harmony.3",
+    "@expo-harmony/expo-modules-autolinking": "55.0.25-harmony.3",
+    "@expo-harmony/prebuild-config": "55.0.0-harmony.4",
     "@expo/config": "55.0.17",
     "cross-spawn": "^7.0.6",
     "json5": "2.2.3"

package/src/cli.ts

@@ -90,6 +90,9 @@ async function runAsync(
   argv: string[] = process.argv.slice(2),
   io: Pick<Console, 'error' | 'log' | 'warn'> = console
 ): Promise<number> {
+  process.env.EXPO_HARMONY = '1';
+  process.env.EXPO_METRO_TARGET = 'harmony';
+
   const invocation = parseInvocation(argv);
   if (invocation.command === 'help') {
     io.log(Help);

package/src/doctor/doctor.ts

@@ -208,6 +208,8 @@ async function doctorUnlockedAsync(projectRoot: string, options: DoctorOptions =
     tools.unshift(['hdc', toolchain.hdc, ['-v'], unavailableToolStatus]);
   }
   for (const [id, tool, versionArgs, unavailableStatus] of tools) {
+    const command = [tool.command, ...tool.args].map(value => JSON.stringify(value)).join(' ');
+
     try {
       const result = await spawnAsync(tool.command, [...tool.args, ...versionArgs], {
         capture: true,
@@ -215,11 +217,12 @@ async function doctorUnlockedAsync(projectRoot: string, options: DoctorOptions =
         operation: `doctor-${id}`,
         timeoutMs: 10_000,
       });
+
       checks.push(result.code === 0 && !result.timedOut
-        ? check(id, 'pass', `${tool.command} is available through ${tool.source}.`)
-        : check(id, unavailableStatus, `${tool.command} is unavailable or unhealthy; HAP build cannot be verified.`));
+        ? check(id, 'pass', `${command} is available through ${tool.source}.`)
+        : check(id, unavailableStatus, `${command} is unavailable or unhealthy; HAP build cannot be verified.`));
     } catch {
-      checks.push(check(id, unavailableStatus, `${tool.command} is unavailable; generation remains available.`));
+      checks.push(check(id, unavailableStatus, `${command} is unavailable; generation remains available.`));
     }
   }
 

package/src/prebuild/check.ts

@@ -40,7 +40,28 @@ function mirrorRoot(temp, project) {
   return path.join(temp, 'filesystem', volume, ...segments);
 }
 
-async function linkModulesAsync(source, target) {
+async function linkModuleEntryAsync(
+  source: string,
+  target: string,
+  entry: fs.Dirent
+) {
+  const directory = entry.isSymbolicLink()
+    ? (await fs.promises.stat(source)).isDirectory()
+    : entry.isDirectory();
+
+  if (process.platform === 'win32' && !directory) {
+    await fs.promises.copyFile(source, target);
+    return;
+  }
+
+  await fs.promises.symlink(
+    path.resolve(source),
+    target,
+    directory ? process.platform === 'win32' ? 'junction' : 'dir' : 'file'
+  );
+}
+
+async function linkModulesAsync(source: string, target: string) {
   await fs.promises.mkdir(target, { recursive: true });
 
   for (const entry of await fs.promises.readdir(source, { withFileTypes: true })) {
@@ -49,25 +70,18 @@ async function linkModulesAsync(source, target) {
 
     if (entry.name.startsWith('@') && entry.isDirectory() && !entry.isSymbolicLink()) {
       await fs.promises.mkdir(to);
+
       for (const child of await fs.promises.readdir(from, { withFileTypes: true })) {
-        await fs.promises.symlink(
+        await linkModuleEntryAsync(
           path.join(from, child.name),
           path.join(to, child.name),
-          process.platform === 'win32' && (child.isDirectory() || child.isSymbolicLink())
-            ? 'junction'
-            : child.isDirectory() ? 'dir' : 'file'
+          child
         );
       }
       continue;
     }
 
-    await fs.promises.symlink(
-      from,
-      to,
-      process.platform === 'win32' && (entry.isDirectory() || entry.isSymbolicLink())
-        ? 'junction'
-        : entry.isDirectory() ? 'dir' : 'file'
-    );
+    await linkModuleEntryAsync(from, to, entry);
   }
 }
 
@@ -126,8 +140,8 @@ async function copyAsync(
   // Keep a real node_modules directory in the isolated project and link its
   // entries. Dependency scanners then retain the isolated lexical package path
   // (including scoped packages) instead of collapsing the entire node_modules
-  // root to the source project's realpath. The packages remain read-only and
-  // are never copied or modified by --check.
+  // root to the source project's realpath. Package directories stay linked;
+  // Windows copies loose files to avoid requiring file-symlink privileges.
   await linkModulesAsync(modules, path.join(target, 'node_modules'));
   await stageAsync(project, target, temp);
 }

package/src/process.ts

@@ -1,4 +1,5 @@
 import spawn from 'cross-spawn';
+import { terminateProcess } from '@expo-harmony/expo-modules-autolinking/tool-command';
 
 import { HarmonyCliError } from './errors';
 
@@ -76,8 +77,15 @@ function formatDiagnostics(result: Pick<ProcessResult, 'stderr' | 'stdout'>, lim
 
 function spawnAsync(command: string, args: string[], options: ProcessOptions = {}): Promise<ProcessResult> {
   return new Promise<ProcessResult>((resolve, reject) => {
+    if (options.signal?.aborted) {
+      throw new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: operation aborted.`, {
+        cause: options.signal.reason,
+        operation: options.operation || 'spawn',
+      });
+    }
+
     const piped = Boolean(options.capture || options.onStdout || options.onStderr);
-    const outputLimit = options.outputLimit || DefaultOutputLimit;
+    const limit = options.outputLimit || DefaultOutputLimit;
     const child = spawn(command, args, {
       cwd: options.cwd,
       env: options.env || process.env,
@@ -86,11 +94,12 @@ function spawnAsync(command: string, args: string[], options: ProcessOptions = {
       windowsHide: true,
     });
 
-    const stdout = new BoundedCapture(outputLimit);
-    const stderr = new BoundedCapture(outputLimit);
+    const stdout = new BoundedCapture(limit);
+    const stderr = new BoundedCapture(limit);
     let timedOut = false;
     let settled = false;
-    let forceKillTimer: NodeJS.Timeout | null = null;
+    let escalation: NodeJS.Timeout | null = null;
+    let stopping: Promise<void> | undefined;
 
     if (piped) {
       child.stdout.on('data', (chunk) => {
@@ -103,72 +112,96 @@ function spawnAsync(command: string, args: string[], options: ProcessOptions = {
       });
     }
 
-    const stopChild = (signal: NodeJS.Signals = 'SIGTERM') => {
-      child.kill(signal);
-      if (forceKillTimer === null) {
-        forceKillTimer = setTimeout(
-          () => child.kill('SIGKILL'),
+    const stop = (signal: NodeJS.Signals = 'SIGTERM') => {
+      if (stopping || settled) return;
+
+      stopping = Promise.resolve().then(() => terminateProcess(child, signal));
+      if (process.platform === 'win32') {
+        void finish(null, signal);
+      } else {
+        stopping.catch((cause) => {
+          void finish(null, null, cause);
+        });
+        escalation = setTimeout(
+          () => {
+            stopping = terminateProcess(child, 'SIGKILL');
+            stopping.catch((cause) => {
+              void finish(null, null, cause);
+            });
+          },
           options.stopGraceMs || DefaultStopGraceMs
         );
-        forceKillTimer.unref?.();
+        escalation.unref?.();
       }
     };
 
-    const forwardSigint = () => stopChild('SIGINT');
-    const forwardSigterm = () => stopChild('SIGTERM');
-    process.once('SIGINT', forwardSigint);
-    process.once('SIGTERM', forwardSigterm);
+    const interrupt = () => stop('SIGINT');
+    const terminate = () => stop('SIGTERM');
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', terminate);
 
     const timeout = options.timeoutMs
       ? setTimeout(() => {
           timedOut = true;
-          stopChild('SIGTERM');
+          stop('SIGTERM');
         }, options.timeoutMs)
       : null;
     timeout?.unref?.();
 
     const cleanup = () => {
       if (timeout) clearTimeout(timeout);
-      if (forceKillTimer) clearTimeout(forceKillTimer);
-      process.removeListener('SIGINT', forwardSigint);
-      process.removeListener('SIGTERM', forwardSigterm);
+      if (escalation) clearTimeout(escalation);
+      process.removeListener('SIGINT', interrupt);
+      process.removeListener('SIGTERM', terminate);
       options.signal?.removeEventListener('abort', abort);
     };
 
-    const abort = () => stopChild('SIGTERM');
-    if (options.signal?.aborted) abort();
-    else options.signal?.addEventListener('abort', abort, { once: true });
+    const finish = async (code, signal, cause?) => {
+      try {
+        await stopping;
+      } catch (error) {
+        cause = error;
+      }
 
-    child.once('error', (cause) => {
       if (settled) return;
       settled = true;
       cleanup();
 
-      reject(new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
+      if (cause) reject(new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot run ${command}: ${cause.message}`, {
         cause,
         operation: options.operation || 'spawn',
       }));
-    });
-    // `close` runs after stdout/stderr have closed, so captured diagnostics are
-    // complete. `exit` can fire while pipe data is still pending.
-    child.once('close', (code, signal) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-
-      resolve({
+      else resolve({
         code: code === null ? 1 : code,
         signal,
         stderr: stderr.toString(),
         stdout: stdout.toString(),
         timedOut,
       });
+    };
+
+    child.once('error', (cause) => {
+      void finish(null, null, cause);
     });
+    child.once('close', (code, signal) => {
+      void finish(code, signal);
+    });
+
+    const abort = () => stop('SIGTERM');
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted) abort();
   });
 }
 
 function startManagedProcess(command: string, args: string[], options: ProcessOptions = {}) {
-  const outputLimit = options.outputLimit || DefaultOutputLimit;
+  if (options.signal?.aborted) {
+    throw new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: operation aborted.`, {
+      cause: options.signal.reason,
+      operation: options.operation || 'spawn',
+    });
+  }
+
+  const limit = options.outputLimit || DefaultOutputLimit;
   const piped = options.stdio !== 'inherit';
   const child = spawn(command, args, {
     cwd: options.cwd,
@@ -178,11 +211,14 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
     windowsHide: true,
   });
 
-  const stdout = new BoundedCapture(outputLimit);
-  const stderr = new BoundedCapture(outputLimit);
-  let spawnError: HarmonyCliError | null = null;
+  const stdout = new BoundedCapture(limit);
+  const stderr = new BoundedCapture(limit);
+  let failure: HarmonyCliError | null = null;
   let closed = false;
-  let stopRequested = false;
+  let stopped = false;
+  let stopping: Promise<void> | undefined;
+  let stopPromise: Promise<ProcessResult | undefined> | undefined;
+  let finish: (code: number | null, signal: NodeJS.Signals | null) => Promise<void>;
 
   if (piped) {
     child.stdout.on('data', (chunk) => {
@@ -195,34 +231,43 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
     });
   }
 
-  const forwardSigint = () => {
-    void stop('SIGINT');
+  const interrupt = () => {
+    void stop('SIGINT').catch(() => {});
   };
-  const forwardSigterm = () => {
-    void stop('SIGTERM');
+  const terminate = () => {
+    void stop('SIGTERM').catch(() => {});
   };
   const abort = () => {
-    void stop('SIGTERM');
+    void stop('SIGTERM').catch(() => {});
   };
 
   const cleanup = () => {
-    process.removeListener('SIGINT', forwardSigint);
-    process.removeListener('SIGTERM', forwardSigterm);
+    process.removeListener('SIGINT', interrupt);
+    process.removeListener('SIGTERM', terminate);
     options.signal?.removeEventListener('abort', abort);
   };
 
   const completion = new Promise<ProcessResult>((resolve, reject) => {
     child.once('error', (cause) => {
-      spawnError = new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
+      failure = new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot launch ${command}: ${cause.message}`, {
         cause,
         operation: options.operation || 'spawn',
       });
     });
-    child.once('close', (code, signal) => {
+    finish = async (code, signal) => {
+      try {
+        await stopping;
+      } catch (cause) {
+        failure = new HarmonyCliError('ERR_HARMONY_PROCESS_FAILED', `Cannot stop ${command}: ${cause.message}`, {
+          cause, operation: options.operation || 'spawn',
+        });
+      }
+
+      if (closed) return;
       closed = true;
       cleanup();
 
-      if (spawnError) reject(spawnError);
+      if (failure) reject(failure);
       else resolve({
         code: code === null ? 1 : code,
         signal,
@@ -230,6 +275,10 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
         stdout: stdout.toString(),
         timedOut: false,
       });
+    };
+
+    child.once('close', (code, signal) => {
+      void finish(code, signal);
     });
   });
   // A readiness probe may be the first consumer. Keep early spawn failures from
@@ -237,28 +286,53 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
   completion.catch(() => {});
 
   async function stop(signal: NodeJS.Signals = 'SIGTERM', graceMs = DefaultStopGraceMs) {
+    if (stopPromise) return stopPromise;
     if (closed) return completion;
 
-    stopRequested = true;
-    child.kill(signal);
-    let timer: NodeJS.Timeout | undefined;
+    stopped = true;
+    stopping = Promise.resolve().then(() => terminateProcess(child, signal));
+    stopPromise = (async () => {
+      if (process.platform === 'win32') {
+        void finish(null, signal);
+        return completion;
+      }
+
+      try {
+        await stopping;
+      } catch {
+        await finish(null, signal);
+        return completion;
+      }
 
-    await Promise.race([
-      completion.catch(() => undefined),
-      new Promise((resolve) => {
-        timer = setTimeout(resolve, graceMs);
-        timer.unref?.();
-      }),
-    ]);
+      let timer: NodeJS.Timeout | undefined;
+
+      await Promise.race([
+        completion.catch(() => undefined),
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, graceMs);
+          timer.unref?.();
+        }),
+      ]);
+
+      if (timer) clearTimeout(timer);
+      if (!closed) {
+        stopping = terminateProcess(child, 'SIGKILL');
+        try {
+          await stopping;
+        } catch {
+          await finish(null, signal);
+        }
+      }
 
-    if (timer) clearTimeout(timer);
-    if (!closed) child.kill('SIGKILL');
+      return completion.catch(() => undefined);
+    })();
+    stopPromise.catch(() => {});
 
-    return completion.catch(() => undefined);
+    return stopPromise;
   }
 
-  process.once('SIGINT', forwardSigint);
-  process.once('SIGTERM', forwardSigterm);
+  process.once('SIGINT', interrupt);
+  process.once('SIGTERM', terminate);
   if (options.signal?.aborted) abort();
   else options.signal?.addEventListener('abort', abort, { once: true });
 
@@ -268,7 +342,7 @@ function startManagedProcess(command: string, args: string[], options: ProcessOp
     getStderr: () => stderr.toString(),
     getStdout: () => stdout.toString(),
     stop,
-    wasStopped: () => stopRequested,
+    wasStopped: () => stopped,
   };
 }
 

package/src/tools.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveHarmonyCommand } from '@expo-harmony/expo-modules-autolinking/tool-command';
 
 import {
   resolveHarmonyBuildPath,
@@ -141,43 +142,43 @@ function resolveHarmonyToolchain(): HarmonyToolchain {
 
   let ohpm: HarmonyTool;
   if (env.HARMONY_OHPM) {
-    ohpm = { args: [], command: env.HARMONY_OHPM, source: 'override' };
+    ohpm = { ...resolveHarmonyCommand('ohpm', [], env), source: 'override' };
   } else {
-    const devEcoOhpm = existingFile(layouts.map(layout => path.join(
+    const entry = layouts.map(layout => ({
+      node: devEcoNode(layout, platform, { ...env, HARMONY_NODE: env.HARMONY_OHPM_NODE || env.HARMONY_NODE }),
+      script: path.join(layout.toolsRoot, 'ohpm', 'bin', 'pm-cli.js'),
+    })).find(candidate => candidate.node && fs.existsSync(candidate.script));
+    const command = existingFile(layouts.map(layout => path.join(
       layout.toolsRoot,
       'ohpm',
       'bin',
       platform === 'win32' ? 'ohpm.bat' : 'ohpm'
     )));
-    ohpm = devEcoOhpm
-      ? { args: [], command: devEcoOhpm, source: 'deveco' }
-      : { args: [], command: platform === 'win32' ? 'ohpm.bat' : 'ohpm', source: 'path' };
+
+    ohpm = entry
+      ? { args: [entry.script], command: entry.node.command, source: 'deveco' }
+      : command
+        ? { args: [], command, source: 'deveco' }
+        : { args: [], command: platform === 'win32' ? 'ohpm.bat' : 'ohpm', source: 'path' };
   }
 
   let hvigor: HarmonyTool;
   if (env.HARMONY_HVIGORW) {
-    if (/\.(?:c|m)?js$/iu.test(env.HARMONY_HVIGORW)) {
-      hvigor = {
-        args: [env.HARMONY_HVIGORW],
-        command: env.HARMONY_NODE || process.execPath,
-        source: 'override',
-      };
-    } else {
-      hvigor = { args: [], command: env.HARMONY_HVIGORW, source: 'override' };
-    }
+    hvigor = { ...resolveHarmonyCommand('hvigorw', [], env), source: 'override' };
   } else {
-    const devEcoHvigor = layouts.map(layout => ({
-      layout,
-      node: devEcoNode(layout, platform, env),
+    const entry = layouts.map(layout => ({
+      node: devEcoNode(layout, platform, { ...env, HARMONY_NODE: env.HARMONY_HVIGOR_NODE || env.HARMONY_NODE }),
       script: path.join(layout.toolsRoot, 'hvigor', 'bin', 'hvigorw.js'),
     })).find(candidate => candidate.node && fs.existsSync(candidate.script));
-    hvigor = devEcoHvigor
-      ? { args: [devEcoHvigor.script], command: devEcoHvigor.node.command, source: 'deveco' }
+
+    hvigor = entry
+      ? { args: [entry.script], command: entry.node.command, source: 'deveco' }
       : { args: [], command: platform === 'win32' ? 'hvigorw.bat' : 'hvigorw', source: 'path' };
   }
 
   const toolsRoot = layouts.find(layout => (
     hvigor.args[0]?.startsWith(`${layout.toolsRoot}${path.sep}`)
+    || ohpm.args[0]?.startsWith(`${layout.toolsRoot}${path.sep}`)
     || ohpm.command.startsWith(`${layout.toolsRoot}${path.sep}`)
   ))?.toolsRoot || null;
 
@@ -201,10 +202,14 @@ function resolveHarmonyToolchain(): HarmonyToolchain {
 function createHarmonyToolchainEnv(toolchain = resolveHarmonyToolchain()): NodeJS.ProcessEnv {
   return {
     ...process.env,
-    HARMONY_OHPM: toolchain.ohpm.command,
-    // A script-based Hvigor invocation must retain both its script and Node executable.
+    HARMONY_OHPM: toolchain.ohpm.args[0] || toolchain.ohpm.command,
+    HARMONY_OHPM_NODE: toolchain.ohpm.args.length > 0 ? toolchain.ohpm.command : undefined,
+    // Script-based tools must retain both their script and Node executable.
     HARMONY_HVIGORW: toolchain.hvigor.args[0] || toolchain.hvigor.command,
-    ...(toolchain.hvigor.args.length > 0 ? { HARMONY_NODE: toolchain.hvigor.command } : {}),
+    HARMONY_HVIGOR_NODE: toolchain.hvigor.args.length > 0 ? toolchain.hvigor.command : undefined,
+    ...(toolchain.hvigor.args.length > 0
+      ? { HARMONY_NODE: toolchain.hvigor.command }
+      : toolchain.ohpm.args.length > 0 ? { HARMONY_NODE: toolchain.ohpm.command } : {}),
     ...(toolchain.sdkHome && !process.env.DEVECO_SDK_HOME
       ? { DEVECO_SDK_HOME: toolchain.sdkHome }
       : {}),