@taqwright/taqwright 0.0.24

package/dist/providers/lambdatest/index.d.ts

@@ -0,0 +1,28 @@
+import { type TaqwrightUseOptions } from '../../types/index.js';
+import { CloudProvider } from '../cloud.js';
+export declare function buildCapabilities(use: TaqwrightUseOptions, projectName: string, appUrl: string): {
+    'lt:options': {
+        w3c: boolean;
+        platformName: string;
+        deviceName: string;
+        platformVersion: string;
+        deviceOrientation: import("../../types/index.js").DeviceOrientation | undefined;
+        app: string;
+        isRealMobile: boolean;
+        build: string;
+        project: string;
+        video: boolean;
+        devicelog: boolean;
+        queueTimeout: number;
+        idleTimeout: number;
+        autoGrantPermissions: boolean;
+        autoAcceptAlerts: boolean;
+        enableImageInjection: boolean | undefined;
+    };
+    'appium:settings[snapshotMaxDepth]'?: number | undefined;
+    platformName: string;
+    'appium:automationName': string;
+};
+export declare class LambdaTestDeviceProvider extends CloudProvider {
+    constructor(use: TaqwrightUseOptions, appBundleId: string | undefined, projectName?: string);
+}

package/dist/providers/lambdatest/index.js

@@ -0,0 +1,99 @@
+import { Platform, } from '../../types/index.js';
+import { CloudProvider } from '../cloud.js';
+const SESSION_API = 'https://mobile-api.lambdatest.com/mobile-automation/api/v1';
+const UPLOAD_API = 'https://manual-api.lambdatest.com/app/upload/realDevice';
+function normalizeDevice(name, osVersion) {
+    const deviceAliases = { 'Google Pixel 8': 'Pixel 8' };
+    const osAliases = { '14.0': '14' };
+    return {
+        name: deviceAliases[name] ?? name,
+        osVersion: osAliases[osVersion] ?? osVersion,
+    };
+}
+export function buildCapabilities(use, projectName, appUrl) {
+    const device = use.device;
+    const resolved = normalizeDevice(device.name, device.osVersion);
+    const ciLabel = process.env.GITHUB_ACTIONS === 'true' ? `CI ${process.env.GITHUB_RUN_ID}` : process.env.USER;
+    const isIOS = use.platform === Platform.IOS;
+    const platformName = isIOS ? 'iOS' : 'Android';
+    const userCaps = { ...(use.capabilities ?? {}) };
+    const userLt = userCaps['lt:options'] ?? {};
+    delete userCaps['lt:options'];
+    const topLevelUser = {};
+    const bareUserLt = {};
+    for (const [k, v] of Object.entries(userCaps)) {
+        if (k === 'platformName' || k.includes(':'))
+            topLevelUser[k] = v;
+        else
+            bareUserLt[k] = v;
+    }
+    return {
+        platformName,
+        'appium:automationName': isIOS ? 'XCUITest' : 'UiAutomator2',
+        ...(isIOS ? { 'appium:settings[snapshotMaxDepth]': 62 } : {}),
+        'lt:options': {
+            w3c: true,
+            platformName,
+            deviceName: resolved.name,
+            platformVersion: resolved.osVersion,
+            deviceOrientation: device.orientation,
+            app: appUrl,
+            isRealMobile: true,
+            build: `${projectName} ${use.platform} ${ciLabel}`,
+            project: projectName,
+            video: true,
+            devicelog: true,
+            queueTimeout: 600,
+            idleTimeout: 600,
+            autoGrantPermissions: true,
+            autoAcceptAlerts: true,
+            enableImageInjection: device.enableCameraImageInjection,
+            ...userLt,
+            ...bareUserLt,
+        },
+        ...topLevelUser,
+    };
+}
+const lambdaTestSpec = {
+    provider: 'lambdatest',
+    credentialEnv: ['LAMBDATEST_USERNAME', 'LAMBDATEST_ACCESS_KEY'],
+    prebuiltScheme: 'lt://',
+    appUrlEnvVar: (projectName) => `LAMBDATEST_APP_URL_${projectName.toUpperCase()}`,
+    upload: {
+        endpoint: UPLOAD_API,
+        urlBody: (buildPath, projectName) => new URLSearchParams({
+            url: buildPath,
+            visibility: 'team',
+            storage: 'url',
+            name: projectName,
+        }),
+        fileBody: (file, fileName, projectName) => {
+            const form = new FormData();
+            form.append('visibility', 'team');
+            form.append('storage', 'file');
+            form.append('appFile', new Blob([new Uint8Array(file)]), fileName);
+            form.append('name', projectName);
+            return form;
+        },
+    },
+    hub: { hostname: 'mobile-hub.lambdatest.com', port: 443, path: '/wd/hub', protocol: 'https' },
+    buildCapabilities: ({ use, projectName, appUrl }) => buildCapabilities(use, projectName, appUrl),
+    syncRequest: (sessionId, details) => ({
+        url: `${SESSION_API}/sessions/${sessionId}`,
+        method: 'PATCH',
+        body: details.status
+            ? JSON.stringify({
+                name: details.name,
+                status_ind: details.status,
+                custom_data: details.reason,
+            })
+            : JSON.stringify({ name: details.name }),
+    }),
+    strictSync: false,
+    requireBundleId: true,
+};
+export class LambdaTestDeviceProvider extends CloudProvider {
+    constructor(use, appBundleId, projectName) {
+        super(lambdaTestSpec, use, appBundleId, projectName);
+    }
+}

package/dist/providers/lambdatest/utils.d.ts

@@ -0,0 +1 @@
+export declare function getAuthHeader(): string;

package/dist/providers/lambdatest/utils.js

@@ -0,0 +1,6 @@
+export function getAuthHeader() {
+    const userName = process.env.LAMBDATEST_USERNAME;
+    const accessKey = process.env.LAMBDATEST_ACCESS_KEY;
+    const key = Buffer.from(`${userName}:${accessKey}`).toString('base64');
+    return `Basic ${key}`;
+}

package/dist/providers/local/index.d.ts

@@ -0,0 +1,9 @@
+import { type TaqwrightUseOptions, type DeviceHandle, type DeviceProvider } from '../../types/index.js';
+export declare class LocalDeviceProvider implements DeviceProvider {
+    private readonly use;
+    sessionId?: string;
+    constructor(use: TaqwrightUseOptions, appBundleId?: string);
+    globalSetup(): Promise<void>;
+    getDevice(): Promise<DeviceHandle>;
+    private resolveUdid;
+}

package/dist/providers/local/index.js

@@ -0,0 +1,53 @@
+import { Platform, } from '../../types/index.js';
+import { getActiveAndroidDevices, getAppBundleId, getConnectedIOSDeviceUDID } from '../appium.js';
+import { buildLocalCapabilities, makeHandle, openLocalSession, resolveAndroidApp, } from '../local-session.js';
+import { validateBuildPath } from '../../utils.js';
+import { logger } from '../../logger.js';
+export class LocalDeviceProvider {
+    use;
+    sessionId;
+    constructor(use, appBundleId) {
+        this.use = use;
+        if (use.device.provider !== 'local-device') {
+            throw new Error(`local-device provider received device.provider='${use.device.provider}'.`);
+        }
+        if (appBundleId) {
+            logger.log(`Bundle id (${appBundleId}) ignored for local-device provider — resolved from the build at runtime.`);
+        }
+    }
+    async globalSetup() {
+        const android = this.use.platform === Platform.ANDROID;
+        validateBuildPath(this.use.buildPath, android ? '.apk' : '.ipa');
+        if (android && !process.env.ANDROID_HOME) {
+            throw new Error('ANDROID_HOME is not set. Required to locate adb / build-tools. See https://developer.android.com/tools');
+        }
+    }
+    async getDevice() {
+        const device = this.use.device;
+        const { appPackage, appActivity } = await resolveAndroidApp(this.use);
+        const udid = await this.resolveUdid(device);
+        const capabilities = buildLocalCapabilities(this.use, device, {
+            appPackage,
+            appActivity,
+            udid,
+        });
+        const driver = await openLocalSession(this.use, capabilities);
+        this.sessionId = driver.sessionId;
+        const bundleId = this.use.platform === Platform.IOS && this.use.buildPath
+            ? await getAppBundleId(this.use.buildPath)
+            : this.use.appBundleId;
+        return makeHandle(this.use, driver, bundleId);
+    }
+    async resolveUdid(device) {
+        if (device.udid) {
+            return device.udid;
+        }
+        if (this.use.platform === Platform.IOS) {
+            return getConnectedIOSDeviceUDID();
+        }
+        if ((await getActiveAndroidDevices()) > 1) {
+            logger.warn('Multiple active Android devices detected — picking one. Set device.udid to disambiguate.');
+        }
+        return undefined;
+    }
+}

package/dist/providers/local-session.d.ts

@@ -0,0 +1,16 @@
+import type { Client as WebDriverClient } from 'webdriver';
+import { type TaqwrightUseOptions, type DeviceHandle, type EmulatorDeviceConfig, type LocalDeviceConfig } from '../types/index.js';
+type LocalDevice = EmulatorDeviceConfig | LocalDeviceConfig;
+export declare function resolveAndroidApp(use: TaqwrightUseOptions): Promise<{
+    appPackage?: string;
+    appActivity?: string;
+}>;
+export declare function buildLocalCapabilities(use: TaqwrightUseOptions, device: LocalDevice, parts: {
+    appPackage?: string;
+    appActivity?: string;
+    udid?: string;
+    extraCaps?: Record<string, unknown>;
+}): Record<string, unknown>;
+export declare function openLocalSession(use: TaqwrightUseOptions, capabilities: Record<string, unknown>): Promise<WebDriverClient>;
+export declare function makeHandle(use: TaqwrightUseOptions, driver: WebDriverClient, bundleId: string | undefined): DeviceHandle;
+export {};

package/dist/providers/local-session.js

@@ -0,0 +1,55 @@
+import { Platform, } from '../types/index.js';
+import { getApkDetails, installDriver, startAppiumServer } from './appium.js';
+import { bootableAvdName } from '../setup/avd.js';
+function appiumConnection(use) {
+    return {
+        port: use.appium?.port ?? 4723,
+        hostname: use.appium?.host ?? 'localhost',
+        path: use.appium?.path ?? '/',
+        logLevel: use.appium?.logLevel ?? 'warn',
+        ...(use.appium?.connectionTimeout !== undefined
+            ? { connectionRetryTimeout: use.appium.connectionTimeout }
+            : {}),
+    };
+}
+export async function resolveAndroidApp(use) {
+    if (use.platform === Platform.ANDROID && use.buildPath) {
+        const { packageName, launchableActivity } = await getApkDetails(use.buildPath);
+        return { appPackage: packageName, appActivity: launchableActivity };
+    }
+    return {};
+}
+export function buildLocalCapabilities(use, device, parts) {
+    const platform = use.platform;
+    return {
+        platformName: platform,
+        'appium:automationName': platform === Platform.ANDROID ? 'uiautomator2' : 'xcuitest',
+        'appium:deviceName': typeof device.name === 'string' ? device.name : device.name?.source,
+        'appium:udid': parts.udid,
+        'appium:app': use.buildPath,
+        'appium:appPackage': parts.appPackage,
+        'appium:appActivity': parts.appActivity,
+        'appium:autoGrantPermissions': true,
+        'appium:autoAcceptAlerts': true,
+        'appium:fullReset': true,
+        'appium:deviceOrientation': device.orientation,
+        'appium:settings[snapshotMaxDepth]': 62,
+        ...(parts.extraCaps ?? {}),
+        ...(use.capabilities ?? {}),
+    };
+}
+export async function openLocalSession(use, capabilities) {
+    const driverName = use.platform === Platform.ANDROID ? 'uiautomator2' : 'xcuitest';
+    await installDriver(driverName);
+    await startAppiumServer(use.device.provider, {}, bootableAvdName(use));
+    const WebDriver = (await import('webdriver')).default;
+    return WebDriver.newSession({ ...appiumConnection(use), capabilities });
+}
+export function makeHandle(use, driver, bundleId) {
+    return {
+        driver,
+        bundleId,
+        options: { expectTimeout: use.expectTimeout ?? 30_000 },
+        provider: use.device.provider,
+    };
+}

package/dist/setup/archive.d.ts

@@ -0,0 +1,2 @@
+export declare function download(url: string, destFile: string, signal?: AbortSignal): Promise<void>;
+export declare function extract(archiveFile: string, destDir: string): Promise<void>;

package/dist/setup/archive.js

@@ -0,0 +1,43 @@
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import path from 'node:path';
+export async function download(url, destFile, signal) {
+    mkdirSync(path.dirname(destFile), { recursive: true });
+    const res = await fetch(url, { redirect: 'follow', signal });
+    if (!res.ok || !res.body) {
+        throw new Error(`download failed (HTTP ${res.status}) — ${url}`);
+    }
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(destFile));
+}
+function run(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'inherit'] });
+        p.on('exit', (code) => resolve(code ?? 1));
+        p.on('error', reject);
+    });
+}
+export async function extract(archiveFile, destDir) {
+    mkdirSync(destDir, { recursive: true });
+    const lower = archiveFile.toLowerCase();
+    if (lower.endsWith('.tar.gz') || lower.endsWith('.tgz')) {
+        if ((await run('tar', ['-xzf', archiveFile, '-C', destDir])) !== 0) {
+            throw new Error(`tar extraction failed for ${archiveFile}`);
+        }
+        return;
+    }
+    if (lower.endsWith('.zip')) {
+        try {
+            if ((await run('unzip', ['-q', archiveFile, '-d', destDir])) === 0)
+                return;
+        }
+        catch {
+        }
+        if ((await run('tar', ['-xf', archiveFile, '-C', destDir])) === 0)
+            return;
+        throw new Error(`could not unzip ${archiveFile} — install \`unzip\` ` +
+            '(Linux: `sudo apt-get install unzip`) and re-run `taqwright install`.');
+    }
+    throw new Error(`unsupported archive type: ${archiveFile}`);
+}

package/dist/setup/avd.d.ts

@@ -0,0 +1,12 @@
+import { type TaqwrightUseOptions } from '../types/index.js';
+export declare function bootableAvdName(use: TaqwrightUseOptions): string | undefined;
+export declare function normalizeSysImagePath(raw: string): string;
+export declare function avdHomeDir(): string;
+export declare function readAvdSystemImage(avdName: string, avdHome?: string): Promise<string | undefined>;
+export declare function isAvdImageInstalled(image: string, androidHome: string): boolean;
+export declare function resolveAvdSdk(avdName: string): Promise<{
+    image?: string;
+    sdkRoot?: string;
+}>;
+export declare function androidEnvForAvd(avdName?: string): Promise<NodeJS.ProcessEnv | undefined>;
+export declare function avdBootPreflightError(avdName: string, androidHome?: string | undefined): Promise<string | null>;

package/dist/setup/avd.js

@@ -0,0 +1,103 @@
+import { existsSync, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Platform } from '../types/index.js';
+import { managedEnv, readManifest, systemAndroidHome } from './paths.js';
+export function bootableAvdName(use) {
+    const device = use.device;
+    return use.platform === Platform.ANDROID &&
+        device.provider === 'emulator' &&
+        typeof device.name === 'string'
+        ? device.name
+        : undefined;
+}
+export function normalizeSysImagePath(raw) {
+    return raw.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+}
+export function avdHomeDir() {
+    return process.env.ANDROID_AVD_HOME || path.join(os.homedir(), '.android', 'avd');
+}
+export async function readAvdSystemImage(avdName, avdHome = avdHomeDir()) {
+    const configPath = path.join(avdHome, `${avdName}.avd`, 'config.ini');
+    if (!existsSync(configPath))
+        return undefined;
+    let content;
+    try {
+        content = await fs.readFile(configPath, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+    const m = content.match(/^image\.sysdir\.1\s*=\s*(.+)$/m);
+    return m ? normalizeSysImagePath(m[1]) : undefined;
+}
+export function isAvdImageInstalled(image, androidHome) {
+    return existsSync(path.join(androidHome, image));
+}
+function candidateSdkRoots() {
+    const roots = [];
+    const managed = readManifest()?.androidHome;
+    if (managed)
+        roots.push(managed);
+    if (process.env.ANDROID_HOME?.trim())
+        roots.push(process.env.ANDROID_HOME);
+    const sys = systemAndroidHome();
+    if (sys)
+        roots.push(sys);
+    return [...new Set(roots)];
+}
+export async function resolveAvdSdk(avdName) {
+    const image = await readAvdSystemImage(avdName);
+    if (!image)
+        return {};
+    const sdkRoot = candidateSdkRoots().find((r) => isAvdImageInstalled(image, r));
+    return { image, sdkRoot };
+}
+export async function androidEnvForAvd(avdName) {
+    const base = managedEnv();
+    if (!base || !avdName)
+        return base;
+    const managedHome = base.ANDROID_HOME;
+    const image = await readAvdSystemImage(avdName);
+    if (!image || isAvdImageInstalled(image, managedHome))
+        return base;
+    const sys = systemAndroidHome();
+    if (!sys || !isAvdImageInstalled(image, sys))
+        return base;
+    const binDirs = [
+        path.join(base.JAVA_HOME, 'bin'),
+        path.join(sys, 'platform-tools'),
+        path.join(sys, 'cmdline-tools', 'latest', 'bin'),
+        path.join(sys, 'emulator'),
+    ];
+    const appiumBin = readManifest()?.appiumBin;
+    if (appiumBin && existsSync(appiumBin))
+        binDirs.push(appiumBin);
+    return {
+        ...base,
+        ANDROID_HOME: sys,
+        ANDROID_SDK_ROOT: sys,
+        PATH: binDirs.join(path.delimiter) + path.delimiter + (process.env.PATH ?? ''),
+    };
+}
+export async function avdBootPreflightError(avdName, androidHome = process.env.ANDROID_HOME) {
+    if (!androidHome)
+        return null;
+    const image = await readAvdSystemImage(avdName);
+    if (!image || isAvdImageInstalled(image, androidHome))
+        return null;
+    const sys = systemAndroidHome();
+    if (sys && isAvdImageInstalled(image, sys))
+        return null;
+    const sdkmanager = `sdkmanager "${image.replace(/\//g, ';')}"`;
+    const head = `Cannot boot AVD "${avdName}": its system image "${image}" is not in the active SDK (ANDROID_HOME=${androidHome}).`;
+    if (readManifest()) {
+        const manifest = path.join(path.dirname(androidHome), 'manifest.json');
+        return (`${head}\n` +
+            'A managed taqwright toolchain is overriding ANDROID_HOME, but this AVD belongs to your system SDK. Fix one of:\n' +
+            `  (a) use your system SDK — \`rm ${manifest}\` (drops the managed override), then re-run;\n` +
+            `  (b) install the image into the managed SDK — \`${sdkmanager}\`;\n` +
+            "  (c) point device.name at a managed AVD (e.g. 'taqwright_api34').");
+    }
+    return `${head}\nInstall it with \`${sdkmanager}\`, or recreate the AVD against an installed image.`;
+}

package/dist/setup/index.d.ts

@@ -0,0 +1,6 @@
+export interface SetupOptions {
+    force?: boolean;
+    withAvd?: boolean;
+    printEnv?: boolean;
+}
+export declare function runSetup(opts?: SetupOptions): Promise<void>;

package/dist/setup/index.js

@@ -0,0 +1,55 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { manifestPath, taqwrightHome, applyManagedEnv } from './paths.js';
+import { installJdk } from './install-jdk.js';
+import { installAndroidSdk, installAvd } from './install-android.js';
+import { installAppium } from './install-appium.js';
+import { runDoctorChecks } from '../doctor.js';
+export async function runSetup(opts = {}) {
+    const force = !!opts.force;
+    const home = taqwrightHome();
+    mkdirSync(home, { recursive: true });
+    console.log(`taqwright install — vendoring the Android toolchain into:\n  ${home}\n`);
+    console.log('Downloads ~700 MB (JDK + Android cmdline-tools + Appium). ' +
+        'No sudo, and nothing is exported to your shell — your global JAVA_HOME, ' +
+        'ANDROID_HOME and ~/.zshrc/.bashrc are left untouched; taqwright points only ' +
+        'its own commands at the dir above.\n');
+    console.log('1/4  JDK (Temurin 21)');
+    const javaHome = await installJdk(force);
+    console.log(`  ✓ JAVA_HOME (taqwright-only) → ${javaHome}\n`);
+    console.log('2/4  Android SDK (cmdline-tools + platform-tools/adb)');
+    const androidHome = await installAndroidSdk(force, javaHome);
+    console.log(`  ✓ ANDROID_HOME (taqwright-only) → ${androidHome}\n`);
+    console.log(`3/4  Appium 3 + uiautomator2 driver${process.platform === 'darwin' ? ' (+ xcuitest)' : ''}`);
+    const appiumBin = await installAppium(force, androidHome, javaHome);
+    console.log(`  ✓ appium at ${appiumBin}\n`);
+    writeFileSync(manifestPath(), JSON.stringify({ androidHome, javaHome, appiumBin }, null, 2) + '\n');
+    if (opts.withAvd) {
+        console.log('4/4  Android Virtual Device');
+        await installAvd(androidHome, javaHome);
+        console.log('  ✓ AVD `taqwright_api34` created — boot it with `emulator -avd taqwright_api34`\n' +
+            '    (it shows up in `npx taqwright devices`)\n');
+    }
+    else {
+        console.log('4/4  AVD — skipped (pass --with-avd to also create an emulator)\n');
+    }
+    applyManagedEnv();
+    console.log('Verifying with doctor:\n');
+    const checks = await runDoctorChecks();
+    for (const c of checks) {
+        const mark = c.status === 'ok' ? '[ok]' : c.status === 'warn' ? '[--]' : '[!!]';
+        console.log(`  ${mark} ${c.name}${c.detail ? '  — ' + c.detail : ''}`);
+    }
+    console.log('\nAndroid is ready — `npx taqwright test` uses this toolchain automatically ' +
+        '(your shell environment is unchanged — no exports needed).');
+    console.log(process.platform === 'darwin'
+        ? 'The xcuitest driver is installed too; for iOS you still need Xcode + a booted ' +
+            'simulator (cannot be auto-installed), plus Node 24.x or 25.x.'
+        : 'Still manual (cannot be auto-installed): Node 24.x or 25.x and the iOS/Xcode stack.');
+    if (opts.printEnv) {
+        console.log('\nTo also use this toolchain from your own shell, add:');
+        console.log(`  export JAVA_HOME="${javaHome}"`);
+        console.log(`  export ANDROID_HOME="${androidHome}"`);
+        console.log('  export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:' +
+            '$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"');
+    }
+}

package/dist/setup/install-android.d.ts

@@ -0,0 +1,2 @@
+export declare function installAndroidSdk(force: boolean, javaHome: string): Promise<string>;
+export declare function installAvd(androidHome: string, javaHome: string): Promise<void>;

package/dist/setup/install-android.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { androidSdkDir, downloadCacheDir } from './paths.js';
+import { download, extract } from './archive.js';
+import { spawnTool } from './spawn-tool.js';
+const CMDLINE_VERSION = '11076708';
+function toolEnv(androidHome, javaHome) {
+    return {
+        ...process.env,
+        JAVA_HOME: javaHome,
+        ANDROID_HOME: androidHome,
+        ANDROID_SDK_ROOT: androidHome,
+        PATH: `${path.join(javaHome, 'bin')}${path.delimiter}${process.env.PATH ?? ''}`,
+    };
+}
+function sdkmanagerBin(sdk) {
+    const bin = process.platform === 'win32' ? 'sdkmanager.bat' : 'sdkmanager';
+    return path.join(sdk, 'cmdline-tools', 'latest', 'bin', bin);
+}
+function runTool(cmd, args, env, feedYes = false) {
+    return new Promise((resolve, reject) => {
+        const p = spawnTool(cmd, args, {
+            stdio: [feedYes ? 'pipe' : 'ignore', 'ignore', 'inherit'],
+            env,
+        });
+        if (feedYes && p.stdin) {
+            p.stdin.write('y\n'.repeat(50));
+            p.stdin.end();
+        }
+        p.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`${path.basename(cmd)} exited with code ${code}`)));
+        p.on('error', reject);
+    });
+}
+export async function installAndroidSdk(force, javaHome) {
+    const sdk = androidSdkDir();
+    if (force && existsSync(sdk))
+        rmSync(sdk, { recursive: true, force: true });
+    const env = toolEnv(sdk, javaHome);
+    const cmdlineLatest = path.join(sdk, 'cmdline-tools', 'latest', 'bin');
+    if (!existsSync(cmdlineLatest)) {
+        const osName = process.platform === 'darwin' ? 'mac' : process.platform === 'win32' ? 'win' : 'linux';
+        const url = `https://dl.google.com/android/repository/commandlinetools-${osName}-${CMDLINE_VERSION}_latest.zip`;
+        const archive = path.join(downloadCacheDir(), `cmdline-tools-${osName}.zip`);
+        console.log(`  • downloading Android cmdline-tools (${osName})…`);
+        await download(url, archive);
+        console.log('  • extracting cmdline-tools…');
+        const ctRoot = path.join(sdk, 'cmdline-tools');
+        rmSync(ctRoot, { recursive: true, force: true });
+        mkdirSync(ctRoot, { recursive: true });
+        await extract(archive, ctRoot);
+        renameSync(path.join(ctRoot, 'cmdline-tools'), path.join(ctRoot, 'latest'));
+    }
+    const sm = sdkmanagerBin(sdk);
+    console.log('  • accepting Android SDK licenses…');
+    await runTool(sm, [`--sdk_root=${sdk}`, '--licenses'], env, true);
+    console.log('  • installing platform-tools (adb) + build-tools (aapt2)…');
+    await runTool(sm, [`--sdk_root=${sdk}`, 'platform-tools', 'build-tools;34.0.0'], env);
+    return sdk;
+}
+export async function installAvd(androidHome, javaHome) {
+    const env = toolEnv(androidHome, javaHome);
+    const abi = process.arch === 'arm64' ? 'arm64-v8a' : 'x86_64';
+    const sysImage = `system-images;android-34;google_apis;${abi}`;
+    const sm = sdkmanagerBin(androidHome);
+    console.log(`  • installing emulator + platform + ${sysImage} (~1 GB)…`);
+    await runTool(sm, [`--sdk_root=${androidHome}`, 'emulator', 'platforms;android-34', sysImage], env, true);
+    const avdmanager = path.join(androidHome, 'cmdline-tools', 'latest', 'bin', process.platform === 'win32' ? 'avdmanager.bat' : 'avdmanager');
+    console.log('  • creating AVD `taqwright_api34`…');
+    await runTool(avdmanager, ['create', 'avd', '-n', 'taqwright_api34', '-k', sysImage, '-d', 'pixel_7', '--force'], env, true);
+}

package/dist/setup/install-appium.d.ts

@@ -0,0 +1 @@
+export declare function installAppium(force: boolean, androidHome: string, javaHome: string): Promise<string>;

package/dist/setup/install-appium.js

@@ -0,0 +1,64 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { appiumDir, appiumHomeDir } from './paths.js';
+import { installDriver } from '../providers/appium.js';
+import { spawnTool } from './spawn-tool.js';
+function npm(args, cwd, env) {
+    return new Promise((resolve, reject) => {
+        const p = spawnTool('npm', args, { cwd, env, stdio: ['ignore', 'ignore', 'inherit'] });
+        p.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`npm ${args.join(' ')} exited with code ${code}`)));
+        p.on('error', reject);
+    });
+}
+export async function installAppium(force, androidHome, javaHome) {
+    const dir = appiumDir();
+    const appiumHome = appiumHomeDir();
+    const binDir = path.join(dir, 'node_modules', '.bin');
+    const appiumBin = path.join(binDir, process.platform === 'win32' ? 'appium.cmd' : 'appium');
+    const uia2Dir = path.join(appiumHome, 'node_modules', 'appium-uiautomator2-driver');
+    const xcuiDir = path.join(appiumHome, 'node_modules', 'appium-xcuitest-driver');
+    const env = {
+        ...process.env,
+        ANDROID_HOME: androidHome,
+        ANDROID_SDK_ROOT: androidHome,
+        JAVA_HOME: javaHome,
+        APPIUM_HOME: appiumHome,
+        PATH: `${path.join(javaHome, 'bin')}${path.delimiter}` +
+            `${path.join(androidHome, 'platform-tools')}${path.delimiter}` +
+            `${process.env.PATH ?? ''}`,
+    };
+    if (force && existsSync(dir))
+        rmSync(dir, { recursive: true, force: true });
+    if (force && existsSync(appiumHome))
+        rmSync(appiumHome, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    mkdirSync(appiumHome, { recursive: true });
+    const pkg = path.join(dir, 'package.json');
+    if (!existsSync(pkg)) {
+        writeFileSync(pkg, JSON.stringify({ name: 'taqwright-managed-appium', private: true }, null, 2) + '\n');
+    }
+    if (force || !existsSync(appiumBin)) {
+        console.log('  • installing Appium 3…');
+        await npm(['install', 'appium@^3'], dir, env);
+    }
+    if (force || !existsSync(uia2Dir)) {
+        console.log('  • installing the uiautomator2 driver…');
+        await installDriver('uiautomator2', { appiumPath: appiumBin, env });
+    }
+    else {
+        console.log('  • uiautomator2 driver already present — skipping');
+    }
+    if (process.platform === 'darwin') {
+        if (force || !existsSync(xcuiDir)) {
+            console.log('  • installing the xcuitest driver…');
+            await installDriver('xcuitest', { appiumPath: appiumBin, env });
+        }
+        else {
+            console.log('  • xcuitest driver already present — skipping');
+        }
+    }
+    else {
+        console.log('  • xcuitest driver — skipped (iOS needs macOS)');
+    }
+    return binDir;
+}

package/dist/setup/install-jdk.d.ts

@@ -0,0 +1 @@
+export declare function installJdk(force: boolean): Promise<string>;