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

package/build/project.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProject = resolveProject;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("./errors");
+function resolveProject(start = process.cwd()) {
+    let current = node_path_1.default.resolve(start);
+    if (node_fs_1.default.existsSync(current) && node_fs_1.default.statSync(current).isFile())
+        current = node_path_1.default.dirname(current);
+    while (true) {
+        if (node_fs_1.default.existsSync(node_path_1.default.join(current, 'package.json')))
+            return node_fs_1.default.realpathSync(current);
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `No package.json was found from ${start}.`, { operation: 'resolve-project' });
+}

package/build/projectLock.d.ts

@@ -0,0 +1,2 @@
+declare function withHarmonyProjectLockAsync<T>(projectRoot: string, operation: string, callback: () => Promise<T> | T): Promise<T>;
+export { withHarmonyProjectLockAsync };

package/build/projectLock.js

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withHarmonyProjectLockAsync = withHarmonyProjectLockAsync;
+const node_async_hooks_1 = require("node:async_hooks");
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("./errors");
+const DefaultMalformedLockGraceMs = 30_000;
+const DefaultPollIntervalMs = 100;
+const DefaultWaitTimeoutMs = 5_000;
+const LockRelativePath = '.expo/harmony/native-operation.lock';
+const ActiveLock = new node_async_hooks_1.AsyncLocalStorage();
+async function canonicalProjectRootAsync(projectRoot) {
+    try {
+        return await node_fs_1.default.promises.realpath(node_path_1.default.resolve(projectRoot));
+    }
+    catch (cause) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_PROJECT_LOCK', 'Cannot resolve the application project before acquiring its Harmony native operation lock.', { cause, operation: 'project-lock' });
+    }
+}
+function projectLockPath(projectRoot) {
+    return node_path_1.default.join(projectRoot, ...LockRelativePath.split('/'));
+}
+async function processIsAliveAsync(pid) {
+    if (!Number.isInteger(pid) || Number(pid) <= 0)
+        return false;
+    try {
+        process.kill(Number(pid), 0);
+        return true;
+    }
+    catch (cause) {
+        return cause?.code !== 'ESRCH';
+    }
+}
+async function readLockOwnerAsync(lockPath) {
+    try {
+        const candidate = JSON.parse(await node_fs_1.default.promises.readFile(lockPath, 'utf8'));
+        if (!candidate
+            || typeof candidate !== 'object'
+            || !Number.isInteger(candidate.pid)
+            || candidate.pid <= 0
+            || typeof candidate.createdAt !== 'string'
+            || typeof candidate.operation !== 'string'
+            || typeof candidate.projectRoot !== 'string'
+            || typeof candidate.token !== 'string') {
+            return null;
+        }
+        return candidate;
+    }
+    catch (_cause) {
+        return null;
+    }
+}
+async function removeStaleProjectLockAsync(lockPath) {
+    let observed;
+    try {
+        observed = await node_fs_1.default.promises.lstat(lockPath);
+    }
+    catch (_cause) {
+        return false;
+    }
+    if (!observed.isFile() || observed.isSymbolicLink())
+        return false;
+    const owner = await readLockOwnerAsync(lockPath);
+    if (owner) {
+        if (await processIsAliveAsync(owner.pid))
+            return false;
+    }
+    else if (Date.now() - observed.mtimeMs < DefaultMalformedLockGraceMs) {
+        return false;
+    }
+    try {
+        const current = await node_fs_1.default.promises.lstat(lockPath);
+        if (!current.isFile() || current.isSymbolicLink()
+            || current.dev !== observed.dev
+            || current.ino !== observed.ino
+            || current.mtimeMs !== observed.mtimeMs
+            || current.size !== observed.size) {
+            return false;
+        }
+        await node_fs_1.default.promises.unlink(lockPath);
+        return true;
+    }
+    catch (_cause) {
+        return false;
+    }
+}
+async function releaseOwnedLockAsync(handle, lockPath, owned) {
+    await handle.close().catch(() => { });
+    if (!owned)
+        return false;
+    try {
+        const current = await node_fs_1.default.promises.lstat(lockPath);
+        if (!current.isFile() || current.isSymbolicLink()
+            || current.dev !== owned.dev || current.ino !== owned.ino) {
+            return false;
+        }
+        await node_fs_1.default.promises.unlink(lockPath);
+        return true;
+    }
+    catch (_cause) {
+        return false;
+    }
+}
+function delayAsync(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+async function acquireHarmonyProjectLockAsync(projectRoot, operation) {
+    const canonicalRoot = await canonicalProjectRootAsync(projectRoot);
+    const lockPath = projectLockPath(canonicalRoot);
+    const deadline = Date.now() + DefaultWaitTimeoutMs;
+    await node_fs_1.default.promises.mkdir(node_path_1.default.dirname(lockPath), { recursive: true });
+    while (true) {
+        try {
+            const handle = await node_fs_1.default.promises.open(lockPath, 'wx', 0o600);
+            let owned;
+            const owner = {
+                createdAt: new Date().toISOString(),
+                operation,
+                pid: process.pid,
+                projectRoot: canonicalRoot,
+                token: node_crypto_1.default.randomUUID(),
+            };
+            try {
+                owned = await handle.stat();
+                await handle.writeFile(`${JSON.stringify(owner)}\n`);
+                await handle.sync();
+            }
+            catch (cause) {
+                await releaseOwnedLockAsync(handle, lockPath, owned);
+                throw new errors_1.HarmonyCliError('ERR_HARMONY_PROJECT_LOCK', 'Cannot initialize the Harmony native operation lock.', { cause, operation: 'project-lock' });
+            }
+            let released = false;
+            return {
+                async releaseAsync() {
+                    if (released)
+                        return;
+                    released = true;
+                    if (await releaseOwnedLockAsync(handle, lockPath, owned))
+                        return;
+                    throw new errors_1.HarmonyCliError('ERR_HARMONY_PROJECT_LOCK', 'The Harmony native operation lock changed before it could be released safely.', { operation: 'project-lock' });
+                },
+            };
+        }
+        catch (cause) {
+            if (cause instanceof errors_1.HarmonyCliError) {
+                throw new errors_1.HarmonyCliError(cause.code, cause.message, {
+                    cause,
+                    exitCode: cause.exitCode,
+                    operation: cause.operation,
+                });
+            }
+            if (cause?.code !== 'EEXIST') {
+                throw new errors_1.HarmonyCliError('ERR_HARMONY_PROJECT_LOCK', 'Cannot acquire the Harmony native operation lock.', { cause, operation: 'project-lock' });
+            }
+            if (await removeStaleProjectLockAsync(lockPath))
+                continue;
+            if (Date.now() >= deadline) {
+                const owner = await readLockOwnerAsync(lockPath);
+                const detail = owner?.operation ? ` (${owner.operation}, pid ${owner.pid})` : '';
+                throw new errors_1.HarmonyCliError('ERR_HARMONY_PROJECT_BUSY', `Another Harmony native operation is using this project${detail}. Retry after it finishes.`, { operation });
+            }
+            await delayAsync(Math.min(DefaultPollIntervalMs, Math.max(1, deadline - Date.now())));
+        }
+    }
+}
+async function withHarmonyProjectLockAsync(projectRoot, operation, callback) {
+    const canonicalRoot = await canonicalProjectRootAsync(projectRoot);
+    const active = ActiveLock.getStore();
+    if (active?.projectRoot === canonicalRoot && !active.released)
+        return await callback();
+    const lease = await acquireHarmonyProjectLockAsync(canonicalRoot, operation);
+    const context = { projectRoot: canonicalRoot, released: false };
+    try {
+        return await ActiveLock.run(context, callback);
+    }
+    finally {
+        context.released = true;
+        await lease.releaseAsync();
+    }
+}

package/build/run/devices.d.ts

@@ -0,0 +1,29 @@
+import { type HarmonyTool } from '../native/toolchain';
+interface Device {
+    aliases: string[];
+    connectTool: string | null;
+    id: string;
+    location: string | null;
+    state: string;
+    transport: string;
+}
+interface HdcOptions {
+    allowFailure?: boolean;
+    code?: string;
+    cwd?: string;
+    devicePort?: number;
+    message?: string;
+    operation?: string;
+    outputLimit?: number;
+    timeoutMs?: number;
+}
+interface DeviceSelectionOptions extends HdcOptions {
+    emulator?: HarmonyTool;
+    emulatorLogFile?: string;
+    onProgress?: (message: string) => void;
+}
+declare function selectDeviceAsync(hdc: HarmonyTool, requested?: string, options?: DeviceSelectionOptions): Promise<Device>;
+declare function installHapAsync(hdc: HarmonyTool, device: Device, hap: string, options?: HdcOptions): Promise<void>;
+declare function configureMetroPortAsync(hdc: HarmonyTool, device: Device, port: number, options?: HdcOptions): Promise<void>;
+declare function launchAppAsync(hdc: HarmonyTool, device: Device, bundleName: string, abilityName: string, options?: HdcOptions): Promise<void>;
+export { configureMetroPortAsync, installHapAsync, launchAppAsync, selectDeviceAsync, };

package/build/run/devices.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureMetroPortAsync = configureMetroPortAsync;
+exports.installHapAsync = installHapAsync;
+exports.launchAppAsync = launchAppAsync;
+exports.selectDeviceAsync = selectDeviceAsync;
+const promises_1 = require("node:timers/promises");
+const emulators_1 = require("./emulators");
+const errors_1 = require("../errors");
+const process_1 = require("../process");
+function parseHdcTargets(output) {
+    const trimmed = String(output).trim();
+    if (!trimmed || trimmed === '[Empty]')
+        return [];
+    return trimmed.split(/\r?\n/u).filter(Boolean).map((line) => {
+        const fields = line.trim().split(/\s+/u);
+        if (fields.length < 3 || !fields[0]) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_DEVICE_OUTPUT', 'HDC returned an unsupported target-list format.', { operation: 'list-devices' });
+        }
+        return {
+            aliases: [fields[0]],
+            connectTool: fields[4] || null,
+            id: fields[0],
+            location: fields[3] || null,
+            state: fields[2],
+            transport: fields[1],
+        };
+    });
+}
+function hasCommandFailure(result) {
+    const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+    return result.code !== 0 || result.timedOut
+        // HDC can print failures to stdout while returning exit code 0.
+        || /\[(?:Fail|Error)\]|\b(?:Failure|failed)\b|(?:失败|错误)/iu.test(output);
+}
+async function runHdcAsync(hdc, args, options = {}) {
+    const result = await (0, process_1.spawnAsync)(hdc.command, [
+        ...hdc.args,
+        ...args,
+    ], {
+        capture: true,
+        cwd: options.cwd,
+        operation: options.operation || 'hdc',
+        outputLimit: options.outputLimit || 256 * 1024,
+        timeoutMs: options.timeoutMs || 60_000,
+    });
+    if (!options.allowFailure && hasCommandFailure(result)) {
+        const diagnostics = (0, process_1.formatDiagnostics)(result, 2_000);
+        throw new errors_1.HarmonyCliError(options.code || 'ERR_HARMONY_DEVICE_COMMAND', `${options.message || 'HDC command failed'}${diagnostics ? `: ${diagnostics}` : '.'}`, { exitCode: result.code || 1, operation: options.operation || 'hdc' });
+    }
+    return result;
+}
+async function listConnectedDevicesAsync(hdc, options) {
+    const result = await runHdcAsync(hdc, ['list', 'targets', '-v'], {
+        code: 'ERR_HARMONY_DEVICE_LIST',
+        cwd: options.cwd,
+        message: 'Cannot list Harmony devices',
+        operation: 'list-devices',
+        timeoutMs: options.timeoutMs || 15_000,
+    });
+    const targets = parseHdcTargets(result.stdout || result.stderr);
+    return targets.filter(target => target.state.toLowerCase() === 'connected');
+}
+async function selectDeviceAsync(hdc, requested, options = {}) {
+    if (requested !== undefined && (!requested || /[\0\r\n]/u.test(requested) || requested.trim() !== requested)) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--device must be a non-empty HDC id or exact emulator name.', { operation: 'select-device' });
+    }
+    const connected = await listConnectedDevicesAsync(hdc, { cwd: options.cwd });
+    if (requested) {
+        const matches = connected.filter(target => target.id === requested || target.aliases.includes(requested));
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_DEVICE_AMBIGUOUS', `The requested device name matches multiple connected targets: ${requested}.`, { operation: 'select-device' });
+        }
+        if (!options.emulator) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_DEVICE_NOT_FOUND', `The requested Harmony device is not connected: ${requested}.`, { operation: 'select-device' });
+        }
+    }
+    else {
+        if (connected.length === 1)
+            return connected[0];
+        if (connected.length > 1) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_DEVICE_AMBIGUOUS', `Multiple Harmony devices are connected (${connected.map(target => target.id).join(', ')}); use --device.`, { operation: 'select-device' });
+        }
+    }
+    if (!options.emulator) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_DEVICE_NOT_FOUND', 'No connected Harmony device was reported by HDC.', { operation: 'select-device' });
+    }
+    const instances = await (0, emulators_1.listEmulatorsAsync)(options.emulator, { cwd: options.cwd });
+    const running = instances.filter(instance => instance.running);
+    const candidates = requested
+        ? instances.filter(instance => instance.name === requested)
+        : running.length ? running : instances;
+    if (candidates.length === 0) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_DEVICE_NOT_FOUND', requested
+            ? `No connected HDC target or local emulator matches ${requested}. Available emulators: ${instances.map(instance => instance.name).join(', ') || 'none'}.`
+            : 'No connected Harmony device or local emulator was found. Create an emulator in DevEco Studio Device Manager first.', { operation: 'select-device' });
+    }
+    if (candidates.length > 1) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_DEVICE_AMBIGUOUS', `Multiple Harmony emulators are available (${candidates.map(instance => JSON.stringify(instance.name)).join(', ')}); use --device <emulator-name>.`, { operation: 'select-device' });
+    }
+    const instance = candidates[0];
+    let launch;
+    if (!instance.running) {
+        if (!options.emulatorLogFile) {
+            throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', 'An emulator log file is required to start a Harmony emulator.', { operation: 'start-emulator' });
+        }
+        options.onProgress?.(`Starting Harmony emulator ${instance.name}`);
+        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);
+    while (Date.now() < deadline) {
+        launch?.assertRunning();
+        const devices = await listConnectedDevicesAsync(hdc, {
+            cwd: options.cwd,
+            timeoutMs: Math.max(1, Math.min(15_000, deadline - Date.now())),
+        });
+        for (const device of devices) {
+            if (Date.now() >= deadline)
+                break;
+            // DevEco may report hw.hdc.port as "notset" even while running. Query
+            // the guest's instance name instead of guessing from a newly seen ID.
+            if (!/^(?:127\.0\.0\.1|localhost|\[::1\]):\d+$/u.test(device.id))
+                continue;
+            const identity = await runHdcAsync(hdc, ['-t', device.id, 'shell', 'param', 'get', 'ohos.qemu.hvd.name'], {
+                allowFailure: true,
+                cwd: options.cwd,
+                operation: 'identify-emulator',
+                timeoutMs: Math.max(1, Math.min(5_000, deadline - Date.now())),
+            });
+            if (identity.code !== 0 || identity.timedOut || identity.stdout.trim() !== instance.name)
+                continue;
+            if (Date.now() >= deadline)
+                break;
+            const boot = await runHdcAsync(hdc, ['-t', device.id, 'shell', 'param', 'get', 'bootevent.boot.completed'], {
+                allowFailure: true,
+                cwd: options.cwd,
+                operation: 'wait-emulator-boot',
+                timeoutMs: Math.max(1, Math.min(5_000, deadline - Date.now())),
+            });
+            if (!hasCommandFailure(boot) && boot.stdout.trim() === 'true')
+                return device;
+        }
+        if (Date.now() >= deadline)
+            break;
+        await (0, promises_1.setTimeout)(Math.min(1_000, deadline - Date.now()));
+    }
+    throw new errors_1.HarmonyCliError('ERR_HARMONY_EMULATOR_TIMEOUT', `Timed out waiting for Harmony emulator ${instance.name} to connect to HDC.${launch ? ` See ${options.emulatorLogFile}.` : ''} Try starting it in DevEco Studio to resolve any license or login requirements.`, { operation: 'start-emulator' });
+}
+async function installHapAsync(hdc, device, hap, options = {}) {
+    await runHdcAsync(hdc, ['-t', device.id, 'install', '-r', hap], {
+        code: 'ERR_HARMONY_INSTALL_FAILED',
+        cwd: options.cwd,
+        message: `Cannot install the Harmony HAP on ${device.id}`,
+        operation: 'install-hap',
+        timeoutMs: options.timeoutMs || 2 * 60_000,
+    });
+}
+async function configureMetroPortAsync(hdc, device, port, options = {}) {
+    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,
+    });
+    for (const line of forwards.stdout.split(/\r?\n/u)) {
+        const [target, remote, local, direction] = line.trim().split(/\s+/u);
+        if (target !== device.id || remote !== deviceEndpoint || direction !== '[Reverse]')
+            continue;
+        if (local === hostEndpoint)
+            return;
+        await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', remote, local], {
+            cwd: options.cwd,
+            operation: 'remove-metro-port',
+            timeoutMs: 15_000,
+        });
+    }
+    await runHdcAsync(hdc, ['-t', device.id, 'rport', deviceEndpoint, hostEndpoint], {
+        code: 'ERR_HARMONY_METRO_FORWARD',
+        cwd: options.cwd,
+        message: `Cannot reverse Metro port ${port} for ${device.id}`,
+        operation: 'reverse-metro-port',
+        timeoutMs: 15_000,
+    });
+}
+async function launchAppAsync(hdc, device, bundleName, abilityName, options = {}) {
+    await runHdcAsync(hdc, [
+        '-t', device.id,
+        'shell',
+        'aa',
+        'force-stop',
+        bundleName,
+    ], {
+        allowFailure: true,
+        cwd: options.cwd,
+        operation: 'force-stop-app',
+        timeoutMs: 15_000,
+    });
+    await runHdcAsync(hdc, [
+        '-t', device.id,
+        'shell',
+        'aa',
+        'start',
+        '-a', abilityName,
+        '-b', bundleName,
+    ], {
+        code: 'ERR_HARMONY_LAUNCH_FAILED',
+        cwd: options.cwd,
+        message: `Cannot launch ${bundleName} on ${device.id}`,
+        operation: 'launch-app',
+        timeoutMs: 30_000,
+    });
+}

package/build/run/emulators.d.ts

@@ -0,0 +1,13 @@
+import { type HarmonyTool } from '../native/toolchain';
+interface HarmonyEmulator {
+    name: string;
+    running: boolean;
+}
+declare function listEmulatorsAsync(tool: HarmonyTool, options?: {
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<HarmonyEmulator[]>;
+declare function startEmulator(tool: HarmonyTool, name: string, logFile: string, cwd?: string): {
+    assertRunning(): void;
+};
+export { listEmulatorsAsync, startEmulator };

package/build/run/emulators.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listEmulatorsAsync = listEmulatorsAsync;
+exports.startEmulator = startEmulator;
+const node_fs_1 = __importDefault(require("node:fs"));
+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");
+async function listEmulatorsAsync(tool, options = {}) {
+    let result;
+    try {
+        result = await (0, process_1.spawnAsync)(tool.command, [...tool.args, '-list', '-details'], {
+            capture: true,
+            cwd: options.cwd,
+            operation: 'list-emulators',
+            timeoutMs: options.timeoutMs || 15_000,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_EMULATOR_LIST', 'Cannot run Emulator. Install DevEco Studio 6.1.0 or newer, add tools/emulator to PATH, or set HARMONY_EMULATOR.', { cause, operation: 'list-emulators' });
+    }
+    if (result.code !== 0 || result.timedOut) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_EMULATOR_LIST', `Cannot list Harmony emulators: ${(0, process_1.formatDiagnostics)(result, 2_000) || 'Emulator timed out or exited unsuccessfully.'}`, { operation: 'list-emulators' });
+    }
+    try {
+        const instances = JSON.parse(result.stdout);
+        if (!Array.isArray(instances))
+            throw new Error('Expected an array.');
+        return instances.map((instance) => {
+            if (!instance || typeof instance.name !== 'string' || !instance.name.trim()
+                || /[\0\r\n]/u.test(instance.name)
+                || ![true, false, 'true', 'false'].includes(instance.isRunning)) {
+                throw new Error('Invalid emulator instance.');
+            }
+            return {
+                name: instance.name,
+                running: instance.isRunning === true || instance.isRunning === 'true',
+            };
+        });
+    }
+    catch (cause) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_EMULATOR_OUTPUT', 'Emulator returned an unsupported instance list. Use DevEco Studio 6.1.0 or newer with Emulator -list -details support.', { cause, operation: 'list-emulators' });
+    }
+}
+function startEmulator(tool, name, logFile, cwd) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(logFile), { recursive: true });
+    const log = node_fs_1.default.openSync(logFile, 'w', 0o600);
+    let failure = null;
+    try {
+        // A detached process with file output lets the emulator survive CLI exit.
+        const child = (0, cross_spawn_1.default)(tool.command, [...tool.args, '-start', name], {
+            cwd,
+            detached: true,
+            shell: false,
+            stdio: ['ignore', log, log],
+            windowsHide: false,
+        });
+        child.once('error', (cause) => {
+            failure = cause.message;
+        });
+        child.once('exit', (code, signal) => {
+            // Some launchers exit before the guest boots; HDC still has to confirm readiness.
+            if (code !== 0)
+                failure = signal ? `terminated by ${signal}` : `exited with code ${code}`;
+        });
+        child.unref();
+    }
+    finally {
+        node_fs_1.default.closeSync(log);
+    }
+    return {
+        assertRunning() {
+            if (failure) {
+                throw new errors_1.HarmonyCliError('ERR_HARMONY_EMULATOR_START', `Cannot start Harmony emulator ${name}: ${failure}. See ${logFile}. Try starting it in DevEco Studio to resolve any license or login requirements.`, { operation: 'start-emulator' });
+            }
+        },
+    };
+}

package/build/run/index.d.ts

@@ -0,0 +1,2 @@
+import { type Command } from '../command';
+export declare const command: Command;

package/build/run/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.command = void 0;
+const command_1 = require("../command");
+const options_1 = require("./options");
+const command = async (argv, io) => {
+    const args = (0, command_1.parseCommandArgs)(options_1.parseRunArgs, argv, io);
+    if (!args)
+        return 0;
+    const { projectRoot: root, options } = args;
+    const { runHarmonySessionAsync } = await import('./run.js');
+    const session = await runHarmonySessionAsync(root, {
+        ...options,
+        interactiveBundler: true,
+        io,
+    });
+    const { result } = session;
+    io.log(`Launched ${result.bundleName} on ${result.device.id} (${result.variant}).`);
+    if (session.metro.owner === 'started') {
+        io.log('\n› Logs for your project will appear below. Press Ctrl+C to exit.');
+        await session.metro.waitAsync();
+    }
+    return 0;
+};
+exports.command = command;

package/build/run/metro.d.ts

@@ -0,0 +1,21 @@
+import { readDevelopmentSessionAsync } from '../development/session';
+import { startManagedProcess } from '../process';
+interface MetroOptions {
+    interactive?: boolean;
+    host?: string;
+    port: number;
+    privateKeyPath?: string;
+    readyTimeoutMs?: number;
+    resetCache?: boolean;
+}
+export interface MetroSession {
+    owner: 'existing' | 'started';
+    development?: Awaited<ReturnType<typeof readDevelopmentSessionAsync>>;
+    port: number;
+    process?: ReturnType<typeof startManagedProcess>;
+    stop(): Promise<unknown>;
+    waitAsync(): Promise<void>;
+}
+declare function requireExistingMetroAsync(port: number): Promise<MetroSession>;
+declare function startExpoMetroAsync(projectRoot: string, options: MetroOptions): Promise<MetroSession>;
+export { requireExistingMetroAsync, startExpoMetroAsync, };