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

package/build/run/devices.js

@@ -0,0 +1,211 @@
+"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 {
+            // Only the first HDC column is a selectable target name. The remaining
+            // verbose columns describe transport, state, location and connect tool.
+            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 occasionally reports transport and package-manager failures on
+        // stdout while still returning exit code 0 (for example,
+        // "Connect server failed"). Treat its documented failure vocabulary as
+        // authoritative regardless of where it appears on the line.
+        || /\[(?: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 });
+    // Prefer an instance that is already booting when HDC is not connected yet.
+    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}`;
+    await runHdcAsync(hdc, ['-t', device.id, 'fport', 'rm', deviceEndpoint, hostEndpoint], {
+        allowFailure: true,
+        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 '../tools';
+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,85 @@
+"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 {
+        // Emulator may remain alive for the whole GUI session. Give it its own
+        // process group and file-backed output so it survives the CLI/Metro exit.
+        // Default instance/image paths match the ones used by -list -details.
+        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 versions use a short-lived launcher. A zero exit alone does not
+            // prove readiness; the caller still checks the guest's name and boot state.
+            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/install.d.ts

@@ -0,0 +1,7 @@
+import type { HarmonyBuildPlan, HarmonyToolchain } from '../tools';
+interface InstallOptions {
+    timeoutMs?: number;
+}
+/** Runs OHPM against the generated project without rewriting its manifest. */
+declare function installHarmonyDependenciesAsync(plan: HarmonyBuildPlan, toolchain: HarmonyToolchain, options?: InstallOptions): Promise<void>;
+export { installHarmonyDependenciesAsync };

package/build/run/install.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHarmonyDependenciesAsync = installHarmonyDependenciesAsync;
+const errors_1 = require("../errors");
+const process_1 = require("../process");
+function installMessage(result) {
+    const diagnostics = (0, process_1.formatDiagnostics)(result);
+    return `OHPM install exited with code ${result.code}${result.timedOut ? ' after timing out' : ''}.`
+        + `${diagnostics ? `\n${diagnostics}` : ''}`;
+}
+/** Runs OHPM against the generated project without rewriting its manifest. */
+async function installHarmonyDependenciesAsync(plan, toolchain, options = {}) {
+    const result = await (0, process_1.spawnAsync)(toolchain.ohpm.command, [...toolchain.ohpm.args, 'install', '--all'], {
+        capture: true,
+        cwd: plan.harmonyRoot,
+        operation: 'ohpm-install',
+        outputLimit: 2 * 1024 * 1024,
+        timeoutMs: options.timeoutMs || 5 * 60_000,
+    });
+    if (result.code !== 0 || result.timedOut) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_OHPM_FAILED', installMessage(result), {
+            exitCode: result.code || 1,
+            operation: 'ohpm-install',
+        });
+    }
+}

package/build/run/metro.d.ts

@@ -0,0 +1,17 @@
+import { startManagedProcess } from '../process';
+interface MetroOptions {
+    interactive?: boolean;
+    port: number;
+    readyTimeoutMs?: number;
+    resetCache?: boolean;
+}
+export interface MetroSession {
+    owner: 'existing' | 'started';
+    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, };

package/build/run/metro.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireExistingMetroAsync = requireExistingMetroAsync;
+exports.startExpoMetroAsync = startExpoMetroAsync;
+const node_http_1 = __importDefault(require("node:http"));
+const errors_1 = require("../errors");
+const process_1 = require("../process");
+const expo_1 = require("../expo");
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+function probeMetroAsync(port, options = {}) {
+    const timeoutMs = options.timeoutMs || 750;
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        const request = node_http_1.default.get({
+            headers: { Accept: 'text/plain' },
+            host: options.host || '127.0.0.1',
+            path: '/status',
+            port,
+        }, (response) => {
+            let body = '';
+            response.setEncoding('utf8');
+            response.on('data', (chunk) => {
+                if (body.length < 1_024)
+                    body += chunk;
+            });
+            response.on('end', () => finish(response.statusCode === 200 && body.trim() === 'packager-status:running'
+                ? 'metro'
+                : 'occupied'));
+        });
+        request.setTimeout(timeoutMs, () => {
+            request.destroy();
+            finish('occupied');
+        });
+        request.on('error', (error) => finish(error.code === 'ECONNREFUSED' || error.code === 'EHOSTUNREACH'
+            ? 'free'
+            : 'occupied'));
+    });
+}
+async function requireExistingMetroAsync(port) {
+    const status = await probeMetroAsync(port);
+    if (status === 'metro') {
+        return {
+            owner: 'existing',
+            port,
+            stop: async () => { },
+            waitAsync: async () => { },
+        };
+    }
+    const code = status === 'free' ? 'ERR_HARMONY_METRO_UNAVAILABLE' : 'ERR_HARMONY_METRO_PORT_IN_USE';
+    const message = status === 'free'
+        ? `No Metro server is running on port ${port}; start Expo Metro before using --no-bundler.`
+        : `Port ${port} is occupied by a process that is not a compatible Metro server.`;
+    throw new errors_1.HarmonyCliError(code, message, { operation: 'metro-probe' });
+}
+async function startExpoMetroAsync(projectRoot, options) {
+    const before = await probeMetroAsync(options.port);
+    if (before === 'metro') {
+        return {
+            owner: 'existing',
+            port: options.port,
+            stop: async () => { },
+            waitAsync: async () => { },
+        };
+    }
+    if (before === 'occupied') {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_METRO_PORT_IN_USE', `Port ${options.port} is occupied by a process that is not a compatible Metro server.`, { operation: 'metro-probe' });
+    }
+    const expo = (0, expo_1.resolveExpoCli)(projectRoot);
+    const managed = (0, process_1.startManagedProcess)(process.execPath, [
+        expo.cliPath,
+        'start',
+        projectRoot,
+        '--dev-client',
+        '--port', String(options.port),
+        ...(options.resetCache ? ['--clear'] : []),
+    ], {
+        cwd: projectRoot,
+        env: {
+            ...process.env,
+            EXPO_METRO_TARGET: 'harmony',
+        },
+        operation: 'expo-metro',
+        outputLimit: 1024 * 1024,
+        stdio: options.interactive ? 'inherit' : 'pipe',
+    });
+    let exitResult = null;
+    let exitError = null;
+    managed.completion.then((result) => {
+        exitResult = result;
+    }, (error) => {
+        exitError = error;
+    });
+    const startedAt = Date.now();
+    const timeoutMs = options.readyTimeoutMs || 60_000;
+    try {
+        while (Date.now() - startedAt < timeoutMs) {
+            if (exitError instanceof errors_1.HarmonyCliError) {
+                throw new errors_1.HarmonyCliError(exitError.code, exitError.message, {
+                    cause: exitError,
+                    exitCode: exitError.exitCode,
+                    operation: exitError.operation,
+                });
+            }
+            if (exitError) {
+                const failure = exitError;
+                throw new errors_1.HarmonyCliError(failure.code || 'ERR_HARMONY_METRO_EXITED', failure.message || 'Expo Metro failed before becoming ready.', { cause: exitError, exitCode: failure.exitCode, operation: failure.operation });
+            }
+            if (exitResult) {
+                const diagnostics = (0, process_1.formatDiagnostics)(exitResult);
+                throw new errors_1.HarmonyCliError('ERR_HARMONY_METRO_EXITED', `Expo Metro exited before becoming ready with code ${exitResult.code}.${diagnostics ? `\n${diagnostics}` : ''}`, { exitCode: exitResult.code || 1, operation: 'expo-metro' });
+            }
+            if (await probeMetroAsync(options.port) === 'metro') {
+                return {
+                    owner: 'started',
+                    port: options.port,
+                    process: managed,
+                    stop: () => managed.stop(),
+                    async waitAsync() {
+                        const result = await managed.completion;
+                        if (managed.wasStopped())
+                            return;
+                        const interrupted = result.signal === 'SIGINT' || result.signal === 'SIGTERM';
+                        if (result.code === 0 || interrupted)
+                            return;
+                        const diagnostics = (0, process_1.formatDiagnostics)(result);
+                        throw new errors_1.HarmonyCliError('ERR_HARMONY_METRO_EXITED', `Expo Metro exited with code ${result.code}.${diagnostics ? `\n${diagnostics}` : ''}`, { exitCode: result.code || 1, operation: 'expo-metro' });
+                    },
+                };
+            }
+            await delay(150);
+        }
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_METRO_TIMEOUT', `Expo Metro did not become ready on port ${options.port} within ${timeoutMs}ms.`, { operation: 'expo-metro' });
+    }
+    catch (error) {
+        await managed.stop();
+        if (error instanceof errors_1.HarmonyCliError) {
+            throw new errors_1.HarmonyCliError(error.code, error.message, {
+                cause: error,
+                exitCode: error.exitCode,
+                operation: error.operation,
+            });
+        }
+        throw new errors_1.HarmonyCliError(error.code || 'ERR_HARMONY_METRO_EXITED', error.message || 'Expo Metro failed while waiting for the server to become ready.', { cause: error, exitCode: error.exitCode, operation: error.operation });
+    }
+}

package/build/run/options.d.ts

@@ -0,0 +1,13 @@
+declare function parseRunArgs(argv: string[]): {
+    appId: string;
+    device: string;
+    help: boolean;
+    noBundler: boolean;
+    noInstall: boolean;
+    port: number;
+    project: string;
+    resetCache: boolean;
+    sync: boolean;
+    variant: "debug" | "release";
+};
+export { parseRunArgs };

package/build/run/options.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRunArgs = parseRunArgs;
+const errors_1 = require("../errors");
+const args_1 = require("../args");
+const RunOptions = {
+    ...args_1.CommonOptions,
+    'app-id': { type: 'string' },
+    'device': { type: 'string' },
+    'no-bundler': { type: 'boolean' },
+    'no-install': { type: 'boolean' },
+    'port': { type: 'string' },
+    'reset-cache': { type: 'boolean' },
+    'sync': { type: 'boolean' },
+    'variant': { type: 'string' },
+};
+function parseRunArgs(argv) {
+    const { positionals, values } = (0, args_1.parseArgs)(RunOptions, argv);
+    if (positionals.length > 1) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', `Unexpected run positional argument: ${positionals[1]}`, {
+            operation: 'parse-arguments',
+        });
+    }
+    const variant = values.variant || 'debug';
+    if (variant !== 'debug' && variant !== 'release') {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--variant must be debug or release.', {
+            operation: 'parse-arguments',
+        });
+    }
+    const port = values.port === undefined ? 8081 : Number(values.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--port must be an integer between 1 and 65535.', {
+            operation: 'parse-arguments',
+        });
+    }
+    const appId = values['app-id'];
+    if (appId !== undefined && (!appId || appId.trim() !== appId || appId.includes('\0'))) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--app-id must be a non-empty Harmony bundle name.', {
+            operation: 'parse-arguments',
+        });
+    }
+    const device = values.device;
+    if (device !== undefined && (!device || device.trim() !== device || /[\0\r\n]/u.test(device))) {
+        throw new errors_1.HarmonyCliError('ERR_HARMONY_CONFIG_INVALID', '--device must be a non-empty HDC id or exact emulator name.', {
+            operation: 'parse-arguments',
+        });
+    }
+    return {
+        appId,
+        device,
+        help: Boolean(values.help),
+        noBundler: Boolean(values['no-bundler']),
+        noInstall: Boolean(values['no-install']),
+        port,
+        project: positionals[0],
+        resetCache: Boolean(values['reset-cache']),
+        sync: Boolean(values.sync),
+        variant: variant,
+    };
+}

package/build/run/run.d.ts

@@ -0,0 +1,51 @@
+import { type MetroSession } from './metro';
+export interface HarmonyRunOptions {
+    appId?: string;
+    device?: string;
+    io?: Pick<Console, 'error' | 'log' | 'warn'>;
+    noBundler?: boolean;
+    noInstall?: boolean;
+    port?: number;
+    resetCache?: boolean;
+    sync?: boolean;
+    variant?: 'debug' | 'release';
+}
+export interface HarmonyRunResult {
+    bundleName: string;
+    device: {
+        id: string;
+        transport: string;
+    };
+    export: null | {
+        assetCount: number;
+        bundleSha256: string;
+        sourceMapSha256: string;
+    };
+    hapPath: string;
+    installed: boolean;
+    launched: true;
+    metro: {
+        owner: 'disabled' | 'existing' | 'started';
+        port: number;
+    };
+    ok: true;
+    schemaVersion: 1;
+    steps: Record<string, number>;
+    variant: 'debug' | 'release';
+}
+interface HarmonyRunSessionOptions extends HarmonyRunOptions {
+    /** Give a CLI-started Metro process ownership of the current terminal. */
+    interactiveBundler?: boolean;
+}
+interface HarmonyRunSession {
+    metro: MetroSession | {
+        owner: 'disabled';
+        port: number;
+        stop(): Promise<void>;
+        waitAsync(): Promise<void>;
+    };
+    result: HarmonyRunResult;
+}
+declare function runHarmonySessionAsync(projectRoot: string, options?: HarmonyRunSessionOptions): Promise<HarmonyRunSession>;
+declare function runHarmonyAsync(projectRoot: string, options?: HarmonyRunOptions): Promise<HarmonyRunResult>;
+export { runHarmonyAsync, runHarmonySessionAsync };