@androperator/emulator 0.1.0

package/dist/hostRequirements.d.ts

@@ -0,0 +1,9 @@
+import { type AndroidSdkTool } from "./hostToolClient.js";
+import type { RuntimeConfig } from "./runtimeConfig.js";
+export interface HostToolAvailability {
+    tool: AndroidSdkTool;
+    available: boolean;
+}
+export declare function checkRequiredEmulatorTools(config: RuntimeConfig): Promise<HostToolAvailability[]>;
+export declare function assertRequiredEmulatorTools(config: RuntimeConfig): Promise<void>;
+//# sourceMappingURL=hostRequirements.d.ts.map

package/dist/hostRequirements.js

@@ -0,0 +1,28 @@
+// Ported from Androperator; adaptations recorded in docs/provenance.md.
+import { isAndroidSdkToolAvailable } from "./hostToolClient.js";
+import { ERROR_CODES } from "./errors.js";
+export async function checkRequiredEmulatorTools(config) {
+    const tools = ["adb", "emulator", "sdkmanager", "avdmanager"];
+    const results = [];
+    for (const tool of tools) {
+        results.push({
+            tool,
+            available: await isAndroidSdkToolAvailable(config, tool),
+        });
+    }
+    return results;
+}
+export async function assertRequiredEmulatorTools(config) {
+    const results = await checkRequiredEmulatorTools(config);
+    const missing = results.filter((result) => !result.available).map((result) => result.tool);
+    if (missing.length === 0) {
+        return;
+    }
+    const error = {
+        code: ERROR_CODES.ANDROID_SDK_TOOL_MISSING,
+        message: `Required Android SDK tools are missing: ${missing.join(", ")}`,
+        details: { missingTools: missing },
+    };
+    throw error;
+}
+//# sourceMappingURL=hostRequirements.js.map

package/dist/hostToolClient.d.ts

@@ -0,0 +1,10 @@
+import type { ProcessResult } from "./processRunner.js";
+import type { RuntimeConfig } from "./runtimeConfig.js";
+export type AndroidSdkTool = "adb" | "emulator" | "sdkmanager" | "avdmanager";
+export declare function runAndroidSdkTool(config: RuntimeConfig, tool: AndroidSdkTool, args: string[], options?: {
+    timeoutMs?: number;
+    cwd?: string;
+    input?: string;
+}): Promise<ProcessResult>;
+export declare function isAndroidSdkToolAvailable(config: RuntimeConfig, tool: AndroidSdkTool): Promise<boolean>;
+//# sourceMappingURL=hostToolClient.d.ts.map

package/dist/hostToolClient.js

@@ -0,0 +1,23 @@
+function getToolPath(config, tool) {
+    switch (tool) {
+        case "adb":
+            return config.adbPath;
+        case "emulator":
+            return config.emulatorPath;
+        case "sdkmanager":
+            return config.sdkmanagerPath;
+        case "avdmanager":
+            return config.avdmanagerPath;
+    }
+}
+export async function runAndroidSdkTool(config, tool, args, options) {
+    return config.runner.run(getToolPath(config, tool), args, options);
+}
+export async function isAndroidSdkToolAvailable(config, tool) {
+    const result = await runAndroidSdkTool(config, tool, ["--help"], { timeoutMs: 5_000 });
+    if (result.error && result.error.code === "ENOENT") {
+        return false;
+    }
+    return result.code === 0 || result.code === 1 || result.stdout.length > 0 || result.stderr.length > 0;
+}
+//# sourceMappingURL=hostToolClient.js.map

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./runtimeConfig.js";
+export * from "./processRunner.js";
+export * from "./hostToolClient.js";
+export * from "./hostRequirements.js";
+export * from "./configuredAvds.js";
+export * from "./runningEmulators.js";
+export * from "./lifecycle.js";
+export * from "./validation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./runtimeConfig.js";
+export * from "./processRunner.js";
+export * from "./hostToolClient.js";
+export * from "./hostRequirements.js";
+export * from "./configuredAvds.js";
+export * from "./runningEmulators.js";
+export * from "./lifecycle.js";
+export * from "./validation.js";
+//# sourceMappingURL=index.js.map

package/dist/lifecycle.d.ts

@@ -0,0 +1,22 @@
+import type { RuntimeConfig } from "./runtimeConfig.js";
+export declare function normalizeEmulatorDataPartitionSize(size: string): string;
+export declare function setAvdDataPartitionSize(name: string, size: string): Promise<void>;
+export declare function isSystemImageInstalled(config: RuntimeConfig, systemImage: string): Promise<boolean>;
+export declare function acceptAndroidSdkLicenses(config: RuntimeConfig): Promise<void>;
+export declare function ensureSystemImageInstalled(config: RuntimeConfig, systemImage: string, options?: {
+    acceptLicenses?: boolean;
+}): Promise<void>;
+export declare function createAvd(config: RuntimeConfig, options: {
+    name: string;
+    systemImage: string;
+    deviceProfile: string;
+    dataPartitionSize: string;
+    replace?: boolean;
+    acceptLicenses?: boolean;
+}): Promise<void>;
+export declare function startAvd(config: RuntimeConfig, name: string, extraArgs?: string[]): Promise<void>;
+export declare function waitForEmulatorRegistration(config: RuntimeConfig, name: string, timeoutMs?: number): Promise<string>;
+export declare function waitForBootCompletion(config: RuntimeConfig, serial: string, timeoutMs?: number): Promise<void>;
+export declare function stopAvd(config: RuntimeConfig, name: string): Promise<void>;
+export declare function deleteAvd(config: RuntimeConfig, name: string): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.js

@@ -0,0 +1,209 @@
+import { validateAvdName, validateSystemImage } from "./validation.js";
+// Ported from Androperator; adaptations recorded in docs/provenance.md.
+import { setTimeout as delay } from "node:timers/promises";
+import { readFile, writeFile } from "node:fs/promises";
+import { runAdb, listDevices } from "./adbClient.js";
+import { runAndroidSdkTool } from "./hostToolClient.js";
+import { ERROR_CODES } from "./errors.js";
+import { ADB_REGISTRATION_TIMEOUT_MS, BOOT_POLL_INTERVAL_MS, EMULATOR_DATA_PARTITION_SIZE_PATTERN, EMULATOR_BOOT_TIMEOUT_MS, } from "./constants.js";
+import { getAvdConfigPath, inspectConfiguredAvd } from "./configuredAvds.js";
+import { isEmulatorBooted, resolveRunningEmulatorByName } from "./runningEmulators.js";
+function buildError(code, message, details) {
+    return { code, message, details };
+}
+export function normalizeEmulatorDataPartitionSize(size) {
+    const normalized = size.trim().toUpperCase();
+    const match = normalized.match(EMULATOR_DATA_PARTITION_SIZE_PATTERN);
+    if (!match) {
+        throw buildError(ERROR_CODES.ANDROID_AVD_CREATE_FAILED, "Emulator data partition size must be a positive integer followed by G or GB", { value: size, expectedFormat: "<positive_integer>G|GB" });
+    }
+    return `${match[1]}G`;
+}
+async function setAvdConfigValue(path, key, value) {
+    let contents;
+    try {
+        contents = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw buildError(ERROR_CODES.ANDROID_AVD_CREATE_FAILED, `Failed to read created AVD config at ${path}`, { path, cause: error instanceof Error ? error.message : String(error) });
+    }
+    const line = `${key}=${value}`;
+    const lines = contents.length > 0 ? contents.split("\n") : [];
+    const index = lines.findIndex((existing) => existing.trimStart().startsWith(`${key}=`));
+    if (index >= 0) {
+        lines[index] = line;
+    }
+    else {
+        if (lines.length > 0 && lines[lines.length - 1] === "") {
+            lines[lines.length - 1] = line;
+            lines.push("");
+        }
+        else {
+            lines.push(line);
+        }
+    }
+    try {
+        await writeFile(path, lines.join("\n"), "utf8");
+    }
+    catch (error) {
+        throw buildError(ERROR_CODES.ANDROID_AVD_CREATE_FAILED, `Failed to write AVD config at ${path}`, { path, key, value, cause: error instanceof Error ? error.message : String(error) });
+    }
+}
+export async function setAvdDataPartitionSize(name, size) {
+    await setAvdConfigValue(await getAvdConfigPath(name), "disk.dataPartition.size", normalizeEmulatorDataPartitionSize(size));
+}
+async function deleteCreatedAvdAfterFailedConfigUpdate(config, name, cause) {
+    const result = await runAndroidSdkTool(config, "avdmanager", ["delete", "avd", "--name", name], {
+        timeoutMs: 60_000,
+    });
+    const typedCause = cause;
+    throw buildError(ERROR_CODES.ANDROID_AVD_CREATE_FAILED, typedCause.message ?? `Failed to configure Android Virtual Device ${name}`, {
+        ...(typedCause.details ?? {}),
+        name,
+        cleanup: {
+            attempted: true,
+            succeeded: result.code === 0,
+            stderr: result.stderr,
+        },
+    });
+}
+export async function isSystemImageInstalled(config, systemImage) {
+    const result = await runAndroidSdkTool(config, "sdkmanager", ["--list_installed"], { timeoutMs: 30_000 });
+    if (result.code !== 0) {
+        throw buildError(ERROR_CODES.ANDROID_SYSTEM_IMAGE_INSTALL_FAILED, result.stderr || "Failed to query installed Android system images", { systemImage });
+    }
+    return result.stdout.split("\n").some((line) => {
+        // Legacy sdkmanager uses semicolon IDs and pipes; the Android CLI shim
+        // uses slash IDs and whitespace columns. Compare the entire first token.
+        const packageId = line.trim().split(/[\s|]+/, 1)[0].replaceAll("/", ";");
+        return packageId === systemImage;
+    });
+}
+export async function acceptAndroidSdkLicenses(config) {
+    const result = await runAndroidSdkTool(config, "sdkmanager", ["--licenses"], {
+        timeoutMs: 120_000,
+        input: "y\n".repeat(100),
+    });
+    if (result.code !== 0) {
+        throw buildError(ERROR_CODES.ANDROID_SYSTEM_IMAGE_INSTALL_FAILED, result.stderr || "Failed to accept Android SDK licenses");
+    }
+}
+export async function ensureSystemImageInstalled(config, systemImage, options = {}) {
+    validateSystemImage(systemImage);
+    if (await isSystemImageInstalled(config, systemImage)) {
+        return;
+    }
+    if (options.acceptLicenses)
+        await acceptAndroidSdkLicenses(config);
+    const result = await runAndroidSdkTool(config, "sdkmanager", [systemImage], { timeoutMs: 300_000 });
+    if (result.code !== 0) {
+        throw buildError(ERROR_CODES.ANDROID_SYSTEM_IMAGE_INSTALL_FAILED, result.stderr || "Failed to install Android system image", { systemImage });
+    }
+    if (!(await isSystemImageInstalled(config, systemImage))) {
+        throw buildError(ERROR_CODES.ANDROID_SYSTEM_IMAGE_INSTALL_FAILED, "System image remains uninstalled; accept its SDK license before retrying, or explicitly set acceptLicenses", { systemImage });
+    }
+}
+export async function createAvd(config, options) {
+    const systemImage = options.systemImage;
+    const deviceProfile = options.deviceProfile;
+    const dataPartitionSize = normalizeEmulatorDataPartitionSize(options.dataPartitionSize);
+    validateAvdName(options.name);
+    const existedBeforeCreate = (await inspectConfiguredAvd(options.name)).exists;
+    validateSystemImage(systemImage);
+    if (!deviceProfile.trim() || deviceProfile.startsWith("-")) {
+        throw buildError(ERROR_CODES.INVALID_ARGUMENT, "deviceProfile must be a nonblank hardware profile ID");
+    }
+    if (existedBeforeCreate) {
+        if (!options.replace)
+            throw buildError(ERROR_CODES.ANDROID_AVD_ALREADY_EXISTS, `AVD ${options.name} already exists; set replace only to discard its data`, { name: options.name });
+        await assertAvdStopped(config, options.name);
+    }
+    await ensureSystemImageInstalled(config, systemImage, { acceptLicenses: options.acceptLicenses });
+    const result = await runAndroidSdkTool(config, "avdmanager", ["create", "avd", ...(options.replace ? ["--force"] : []), "--name", options.name, "--package", systemImage, "--device", deviceProfile], { timeoutMs: 120_000, input: "no\n" });
+    if (result.code !== 0) {
+        throw buildError(ERROR_CODES.ANDROID_AVD_CREATE_FAILED, result.stderr || "Failed to create Android Virtual Device", { name: options.name, systemImage, deviceProfile });
+    }
+    try {
+        await setAvdDataPartitionSize(options.name, dataPartitionSize);
+    }
+    catch (error) {
+        if (!existedBeforeCreate) {
+            await deleteCreatedAvdAfterFailedConfigUpdate(config, options.name, error);
+        }
+        throw error;
+    }
+}
+export async function startAvd(config, name, extraArgs = []) {
+    validateAvdName(name);
+    const args = [`@${name}`, "-no-snapshot-load", "-no-boot-anim", ...extraArgs];
+    const child = config.runner.spawn(config.emulatorPath, args, {
+        detached: true,
+        stdio: ["ignore", "ignore", "ignore"],
+        shell: false,
+    });
+    if (child && typeof child.once === "function") {
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", (error) => reject(buildError(ERROR_CODES.EMULATOR_START_FAILED, error.message, { name })));
+        });
+    }
+    if (child && typeof child.unref === "function") {
+        child.unref();
+    }
+}
+export async function waitForEmulatorRegistration(config, name, timeoutMs = ADB_REGISTRATION_TIMEOUT_MS) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const running = await resolveRunningEmulatorByName(config, name);
+        if (running) {
+            return running.serial;
+        }
+        await delay(BOOT_POLL_INTERVAL_MS);
+    }
+    throw buildError(ERROR_CODES.EMULATOR_START_FAILED, `Timed out waiting for emulator ${name} to appear in adb`, { name, timeoutMs });
+}
+export async function waitForBootCompletion(config, serial, timeoutMs = EMULATOR_BOOT_TIMEOUT_MS) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        if (await isEmulatorBooted(config, serial)) {
+            return;
+        }
+        await delay(BOOT_POLL_INTERVAL_MS);
+    }
+    throw buildError(ERROR_CODES.EMULATOR_BOOT_TIMEOUT, `Timed out waiting for emulator ${serial} to finish booting`, { serial, timeoutMs });
+}
+export async function stopAvd(config, name) {
+    const running = await resolveRunningEmulatorByName(config, name);
+    if (!running) {
+        throw buildError(ERROR_CODES.EMULATOR_NOT_RUNNING, `Emulator ${name} is not running`, { name });
+    }
+    const result = await runAdb({ ...config, deviceId: running.serial }, ["emu", "kill"]);
+    if (result.code !== 0) {
+        throw buildError(ERROR_CODES.EMULATOR_STOP_FAILED, result.stderr || `Failed to stop emulator ${name}`, { name, serial: running.serial });
+    }
+}
+export async function deleteAvd(config, name) {
+    validateAvdName(name);
+    await assertAvdStopped(config, name);
+    const existing = await inspectConfiguredAvd(name);
+    if (!existing.exists) {
+        throw buildError(ERROR_CODES.EMULATOR_NOT_FOUND, `AVD ${name} does not exist`, { name });
+    }
+    const result = await runAndroidSdkTool(config, "avdmanager", ["delete", "avd", "--name", name], {
+        timeoutMs: 60_000,
+    });
+    if (result.code !== 0) {
+        throw buildError(ERROR_CODES.EMULATOR_DELETE_FAILED, result.stderr || `Failed to delete emulator ${name}`, { name });
+    }
+}
+async function assertAvdStopped(config, name) {
+    const devices = await listDevices(config);
+    if (devices.some((device) => device.serial.startsWith("emulator-") && device.state !== "device")) {
+        throw buildError(ERROR_CODES.EMULATOR_ALREADY_RUNNING, "Cannot safely modify an AVD while an emulator is offline or unauthorized");
+    }
+    const running = await resolveRunningEmulatorByName(config, name, devices);
+    if (running) {
+        throw buildError(ERROR_CODES.EMULATOR_ALREADY_RUNNING, `Cannot modify running emulator ${name}`, { name, serial: running.serial });
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/processRunner.d.ts

@@ -0,0 +1,33 @@
+export interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    code: number | null;
+    error?: Error;
+}
+export interface ProcessRunner {
+    run(command: string, args: string[], options?: {
+        timeoutMs?: number;
+        cwd?: string;
+        input?: string;
+    }): Promise<ProcessResult>;
+    spawn(command: string, args: string[], options?: {
+        detached?: boolean;
+        stdio?: any;
+        shell?: boolean;
+        env?: NodeJS.ProcessEnv;
+    }): any;
+}
+export declare class NodeProcessRunner implements ProcessRunner {
+    run(command: string, args: string[], options?: {
+        timeoutMs?: number;
+        cwd?: string;
+        input?: string;
+    }): Promise<ProcessResult>;
+    spawn(command: string, args: string[], options?: {
+        detached?: boolean;
+        stdio?: any;
+        shell?: boolean;
+        env?: NodeJS.ProcessEnv;
+    }): any;
+}
+//# sourceMappingURL=processRunner.d.ts.map

package/dist/processRunner.js

@@ -0,0 +1,65 @@
+// Ported from Androperator; adaptations recorded in docs/provenance.md.
+import { spawn } from "node:child_process";
+export class NodeProcessRunner {
+    async run(command, args, options) {
+        return new Promise((resolve) => {
+            const stdin = options?.input !== undefined ? "pipe" : "ignore";
+            const proc = spawn(command, args, {
+                cwd: options?.cwd,
+                detached: process.platform !== "win32",
+                stdio: [stdin, "pipe", "pipe"],
+                shell: false,
+            });
+            let stdout = "";
+            let stderr = "";
+            proc.stdout?.on("data", (d) => (stdout += d.toString()));
+            proc.stderr?.on("data", (d) => (stderr += d.toString()));
+            proc.stdin?.on("error", () => { });
+            if (options?.input !== undefined) {
+                proc.stdin?.write(options.input);
+                proc.stdin?.end();
+            }
+            const timeoutMs = options?.timeoutMs ?? 30_000;
+            let timedOut = false;
+            const t = setTimeout(() => {
+                timedOut = true;
+                // SDK scripts can launch children that inherit the output pipes.
+                if (process.platform !== "win32" && proc.pid !== undefined) {
+                    try {
+                        process.kill(-proc.pid, "SIGKILL");
+                    }
+                    catch (error) {
+                        if (error.code !== "ESRCH")
+                            proc.kill("SIGKILL");
+                    }
+                }
+                else {
+                    proc.kill("SIGKILL");
+                }
+                proc.stdout?.destroy();
+                proc.stderr?.destroy();
+                proc.stdin?.destroy();
+                resolve({ stdout, stderr: `${stderr}\nProcess timed out after ${timeoutMs}ms`, code: null });
+            }, timeoutMs);
+            proc.on("error", (err) => {
+                clearTimeout(t);
+                resolve({ stdout, stderr, code: err.code === "ENOENT" ? 127 : 1, error: err });
+            });
+            proc.on("close", (code) => {
+                clearTimeout(t);
+                resolve({ stdout, stderr: timedOut ? `${stderr}\nProcess timed out after ${timeoutMs}ms` : stderr, code: timedOut ? null : code ?? null });
+            });
+        });
+    }
+    spawn(command, args, options) {
+        const detached = options?.detached ?? false;
+        const stdio = options?.stdio ?? (detached ? ["ignore", "ignore", "ignore"] : ["ignore", "pipe", "pipe"]);
+        return spawn(command, args, {
+            detached,
+            stdio,
+            shell: options?.shell ?? false,
+            env: options?.env,
+        });
+    }
+}
+//# sourceMappingURL=processRunner.js.map

package/dist/runningEmulators.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimeConfig } from "./runtimeConfig.js";
+import { type DeviceInfo } from "./adbClient.js";
+import type { RunningEmulator } from "./types.js";
+export declare function getRunningEmulatorAvdName(config: RuntimeConfig, serial: string): Promise<string>;
+export declare function isEmulatorBooted(config: RuntimeConfig, serial: string): Promise<boolean>;
+export declare function listRunningEmulators(config: RuntimeConfig, devices?: DeviceInfo[]): Promise<RunningEmulator[]>;
+export declare function resolveRunningEmulatorByName(config: RuntimeConfig, name: string, devices?: DeviceInfo[]): Promise<RunningEmulator | undefined>;
+//# sourceMappingURL=runningEmulators.d.ts.map

package/dist/runningEmulators.js

@@ -0,0 +1,55 @@
+// Ported from Androperator; adaptations recorded in docs/provenance.md.
+import { runAdb } from "./adbClient.js";
+import { listDevices } from "./adbClient.js";
+function isEmulatorSerial(serial) {
+    return serial.startsWith("emulator-");
+}
+function parseEmulatorAvdName(stdout) {
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && line !== "OK");
+    if (lines.length === 0) {
+        throw new Error("Emulator did not return an AVD name");
+    }
+    return lines[0];
+}
+async function isBootPropComplete(config, serial, prop) {
+    const result = await runAdb({ ...config, deviceId: serial }, ["shell", "getprop", prop]);
+    return result.code === 0 && result.stdout.trim() === "1";
+}
+export async function getRunningEmulatorAvdName(config, serial) {
+    const result = await runAdb({ ...config, deviceId: serial }, ["emu", "avd", "name"]);
+    if (result.code !== 0) {
+        throw new Error(result.stderr || `Failed to resolve AVD name for ${serial}`);
+    }
+    return parseEmulatorAvdName(result.stdout);
+}
+export async function isEmulatorBooted(config, serial) {
+    const [sysBootCompleted, devBootComplete] = await Promise.all([
+        isBootPropComplete(config, serial, "sys.boot_completed"),
+        isBootPropComplete(config, serial, "dev.bootcomplete"),
+    ]);
+    return sysBootCompleted && devBootComplete;
+}
+export async function listRunningEmulators(config, devices) {
+    devices ??= await listDevices(config);
+    const emulators = devices.filter((device) => device.state === "device" && isEmulatorSerial(device.serial));
+    const running = [];
+    for (const device of emulators) {
+        const avdName = await getRunningEmulatorAvdName(config, device.serial);
+        const booted = await isEmulatorBooted(config, device.serial);
+        running.push({
+            type: "emulator",
+            avdName,
+            serial: device.serial,
+            booted,
+        });
+    }
+    return running;
+}
+export async function resolveRunningEmulatorByName(config, name, devices) {
+    const emulators = await listRunningEmulators(config, devices);
+    return emulators.find((emulator) => emulator.avdName === name);
+}
+//# sourceMappingURL=runningEmulators.js.map

package/dist/runtimeConfig.d.ts

@@ -0,0 +1,15 @@
+import { type ProcessRunner } from "./processRunner.js";
+export interface RuntimeConfig {
+    adbPath: string;
+    emulatorPath: string;
+    sdkmanagerPath: string;
+    avdmanagerPath: string;
+    runner: ProcessRunner;
+    /** Optional consumer ADB adapter, for diagnostics and logging. */
+    adb?: (args: string[], options?: {
+        timeoutMs?: number;
+    }) => ReturnType<ProcessRunner["run"]>;
+    deviceId?: string;
+}
+export declare function getDefaultRuntimeConfig(overrides?: Partial<RuntimeConfig>): RuntimeConfig;
+//# sourceMappingURL=runtimeConfig.d.ts.map

package/dist/runtimeConfig.js

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { NodeProcessRunner } from "./processRunner.js";
+export function getDefaultRuntimeConfig(overrides = {}) {
+    const sdkRoots = [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT,
+        join(homedir(), "Library", "Android", "sdk"), join(homedir(), "Android", "Sdk")]
+        .filter((root) => root !== undefined && root.length > 0);
+    function tool(name, relativePath, env) {
+        const explicit = process.env[env];
+        if (explicit !== undefined) {
+            if (!explicit.trim())
+                throw new Error(`${env} must not be blank`);
+            return explicit;
+        }
+        return sdkRoots.map((root) => join(root, relativePath)).find(existsSync) ?? name;
+    }
+    const defined = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined));
+    return {
+        adbPath: tool("adb", "platform-tools/adb", "ADB_PATH"),
+        emulatorPath: tool("emulator", "emulator/emulator", "EMULATOR_PATH"),
+        sdkmanagerPath: tool("sdkmanager", "cmdline-tools/latest/bin/sdkmanager", "SDKMANAGER_PATH"),
+        avdmanagerPath: tool("avdmanager", "cmdline-tools/latest/bin/avdmanager", "AVDMANAGER_PATH"),
+        runner: new NodeProcessRunner(),
+        ...defined,
+    };
+}
+//# sourceMappingURL=runtimeConfig.js.map

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export interface ConfiguredAvd {
+    name: string;
+    exists: boolean;
+    running: boolean;
+    apiLevel: number | null;
+    abi: string | null;
+    playStore: boolean;
+    deviceProfile: string | null;
+    systemImage: string | null;
+}
+export interface RunningEmulator {
+    type: "emulator";
+    avdName: string;
+    serial: string;
+    booted: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/validation.d.ts

@@ -0,0 +1,3 @@
+export declare function validateAvdName(name: string): void;
+export declare function validateSystemImage(systemImage: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.js

@@ -0,0 +1,12 @@
+import { ERROR_CODES } from "./errors.js";
+export function validateAvdName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(name)) {
+        throw { code: ERROR_CODES.ANDROID_AVD_CREATE_FAILED, message: "AVD name must start with a letter or number and contain only letters, numbers, dots, underscores or hyphens", details: { name } };
+    }
+}
+export function validateSystemImage(systemImage) {
+    if (!/^system-images;android-[A-Za-z0-9_.-]+;[A-Za-z0-9_.-]+;[A-Za-z0-9_.-]+$/.test(systemImage)) {
+        throw { code: ERROR_CODES.INVALID_ARGUMENT, message: "Use a system image package ID, for example system-images;android-35;google_apis;arm64-v8a", details: { systemImage } };
+    }
+}
+//# sourceMappingURL=validation.js.map

package/docs/provenance.md

@@ -0,0 +1,47 @@
+# Extraction provenance
+
+Source: `https://github.com/androperator/androperator`, revision
+`43210a51315ad9e0badd80311bf686596a46b154`. Source license: Apache-2.0, retained
+in `LICENSE`; attribution retained in `NOTICE`. This is primarily ported code.
+
+Paths in the first column are relative to the source `apps/node/src/`.
+
+| Original module/test | Destination | Adaptation |
+| --- | --- | --- |
+| `domain/android-emulators/configuredAvds.ts` | `src/configuredAvds.ts` | Remove support policy; validate names; follow locator paths; propagate read errors; recognize empty locator files |
+| `domain/android-emulators/runningEmulators.ts` | `src/runningEmulators.ts` | Remove support annotation; retain serial/name and both boot-property checks |
+| `domain/android-emulators/lifecycle.ts` | `src/lifecycle.ts` | Explicit inputs/license/replacement policy; early size validation; exact image matching and post-install verification; async launch errors; fail-closed delete/replacement |
+| `domain/android-emulators/hostRequirements.ts` | `src/hostRequirements.ts` | Generic runtime/error imports |
+| `domain/android-emulators/constants.ts`, `types.ts` | `src/constants.ts`, `src/types.ts` | Keep only timing/size mechanics and generic metadata |
+| `adapters/android-sdk/hostToolClient.ts` | `src/hostToolClient.ts` | Generic imports |
+| `adapters/android-bridge/processRunner.ts` | `src/processRunner.ts` | Remove shell execution; handle stdin closure; kill timed-out SDK process group and report timeout |
+| `adapters/android-bridge/adbClient.ts`, `domain/devices/listDevices.ts` | `src/adbClient.ts` | Preserve serial selection; inject consumer logging; check failed/malformed device discovery |
+| `adapters/android-bridge/runtimeConfig.ts` | `src/runtimeConfig.ts` | New minimal runtime contract and SDK discovery adapted from source |
+| `contracts/errors.ts` | `src/errors.ts` | Retain emulator error strings; add boundary errors |
+| `cli/commands/emulator.ts` | `src/cli.ts` | New parser and versioned JSON envelope; orchestration adapted from source |
+| `test/unit/configuredAvds.test.ts` | `src/test/configuredAvds.test.ts` | Port parsing/discovery checks; remove consumer compatibility assertions |
+| `test/unit/runningEmulators.test.ts` | `src/test/runningEmulators.test.ts` | Port console, boot and serial checks; remove compatibility assertions |
+| `test/unit/emulatorLifecycle.test.ts` | `src/test/emulatorLifecycle.test.ts` | Port creation/storage/cleanup/start/wait/stop/delete checks with explicit inputs; developer-settings test remains in consumer |
+| `test/unit/androidEmulatorsFoundation.test.ts` | `src/test/androidEmulatorsFoundation.test.ts` | Port tool availability tests; defaults tests remain in consumer |
+| `test/unit/fakes/FakeProcessRunner.ts` | `src/test/fakes/FakeProcessRunner.ts` | Port deterministic runner |
+| No source equivalent | `src/test/boundaries.test.ts` | New boundary, process-error and CLI protocol checks |
+
+`compatibility.ts`, `provision.ts`, defaults, default-name generation and guest
+developer settings remain Androperator policy. Its `emulatorCli.test.ts` and
+`emulatorProvision.test.ts` stay in the consumer as integration regressions.
+
+## Intentional corrections and limits
+
+- Generic creation never silently replaces data or accepts licenses. The consumer
+  can explicitly retain its former policy. Replacement refuses a running target.
+- Invalid capacity fails before SDK mutation. Failed post-create configuration
+  still attempts cleanup only for a newly created AVD, as in the source.
+- Installed-image matching uses the exact package column instead of substring
+  matching. Installation is re-queried because license refusal can exit zero. No remote image catalog or recommendation algorithm was added.
+- Config paths follow AVD metadata instead of assuming `<name>.avd` always owns
+  the data. Unexpected filesystem errors are no longer silently treated as absent.
+- ADB query errors and offline emulators cannot be interpreted as safe deletion.
+- Start reports asynchronous spawn failure; callers must await it. Process timeout
+  is reported even if a child exits successfully after the deadline.
+- Storage configuration remains virtual capacity only. No host disk cap, resizing,
+  qcow2 conversion, cancellation or snapshot-save policy is claimed.