@houwert/conductor 0.29.3 → 0.31.0

package/dist/drivers/bootstrap.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectPlatform = detectPlatform;
+exports.detectDeviceKind = detectDeviceKind;
+exports.resolveDriverHost = resolveDriverHost;
 exports.getDriverPort = getDriverPort;
 exports.getInputPort = getInputPort;
 exports.getStreamPort = getStreamPort;
@@ -18,6 +20,9 @@ exports.stopIOSDriver = stopIOSDriver;
 exports.setupTvOSDriverCache = setupTvOSDriverCache;
 exports.startTvOSDriver = startTvOSDriver;
 exports.stopTvOSDriver = stopTvOSDriver;
+exports.resolveTeamId = resolveTeamId;
+exports.startDeviceDriver = startDeviceDriver;
+exports.stopDeviceDriver = stopDeviceDriver;
 exports.startAndroidDriver = startAndroidDriver;
 exports.stopAndroidDriver = stopAndroidDriver;
 exports.webBrowserName = webBrowserName;
@@ -48,6 +53,7 @@ const path_1 = __importDefault(require("path"));
 const verbose_js_1 = require("../verbose.js");
 const utils_js_1 = require("../utils.js");
 const sdk_js_1 = require("../android/sdk.js");
+const devicectl_js_1 = require("./devicectl.js");
 /** Cache: deviceId → platform */
 const _platformCache = new Map();
 async function detectPlatform(deviceId) {
@@ -63,9 +69,16 @@ async function detectPlatform(deviceId) {
         _platformCache.set(deviceId, 'vega');
         return 'vega';
     }
-    // Check if it looks like an iOS/tvOS simulator UUID (8-4-4-4-12 hex chars)
-    const iosUuidRe = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
-    if (iosUuidRe.test(deviceId)) {
+    // Roku: "roku:<host>" (e.g. "roku:192.168.1.100")
+    if (deviceId === 'roku' || deviceId.startsWith('roku:')) {
+        _platformCache.set(deviceId, 'roku');
+        return 'roku';
+    }
+    // Simulator UDIDs and CoreDevice identifiers share the 8-4-4-4-12 UUID shape;
+    // physical devices additionally answer to their 40-hex hardware UDID.
+    const appleUuidRe = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+    const appleUdidRe = /^[0-9a-f]{40}$/i;
+    if (appleUuidRe.test(deviceId) || appleUdidRe.test(deviceId)) {
         // Query simctl to determine whether this UUID belongs to a tvOS runtime
         try {
             const out = await spawnCapture('xcrun', ['simctl', 'list', 'devices', '--json']);
@@ -74,12 +87,20 @@ async function detectPlatform(deviceId) {
                 if (sims.some((s) => s.udid === deviceId)) {
                     const platform = runtime.includes('tvOS') ? 'tvos' : 'ios';
                     _platformCache.set(deviceId, platform);
+                    _kindCache.set(deviceId, 'simulator');
                     return platform;
                 }
             }
         }
         catch {
-            /* fall through to ios default */
+            /* fall through to devicectl */
+        }
+        // Not a simulator — ask CoreDevice whether it's a paired physical device.
+        const physical = await (0, devicectl_js_1.findPhysicalDevice)(deviceId);
+        if (physical) {
+            _platformCache.set(deviceId, physical.platform);
+            _kindCache.set(deviceId, 'physical');
+            return physical.platform;
         }
         _platformCache.set(deviceId, 'ios');
         return 'ios';
@@ -88,6 +109,40 @@ async function detectPlatform(deviceId) {
     _platformCache.set(deviceId, 'android');
     return 'android';
 }
+/** Cache: deviceId → simulator vs physical. Populated as a side effect of detectPlatform. */
+const _kindCache = new Map();
+/**
+ * Whether the device is a real one rather than a simulator. Only meaningful for
+ * iOS/tvOS; everything else reports 'simulator' since the distinction is either
+ * absent (web) or already encoded in the driver (Android adb, Vega).
+ */
+async function detectDeviceKind(deviceId) {
+    if (_kindCache.has(deviceId))
+        return _kindCache.get(deviceId);
+    const platform = await detectPlatform(deviceId);
+    if (platform !== 'ios' && platform !== 'tvos') {
+        _kindCache.set(deviceId, 'simulator');
+        return 'simulator';
+    }
+    // detectPlatform records the kind for Apple devices it recognised; anything
+    // still unset never matched simctl or devicectl, so treat it as a simulator.
+    const kind = _kindCache.get(deviceId) ?? 'simulator';
+    _kindCache.set(deviceId, kind);
+    return kind;
+}
+/**
+ * Host the XCTest driver for this device is reachable on. Simulators share the
+ * host's loopback; physical devices run the driver on their own loopback, so we
+ * reach them over the LAN instead.
+ */
+async function resolveDriverHost(deviceId) {
+    if ((await detectDeviceKind(deviceId)) !== 'physical')
+        return '127.0.0.1';
+    const device = await (0, devicectl_js_1.findPhysicalDevice)(deviceId);
+    if (!device)
+        throw new Error(`Physical device ${deviceId} is no longer paired`);
+    return (0, devicectl_js_1.resolveDeviceHost)(device);
+}
 // ── Port management ───────────────────────────────────────────────────────────
 const IOS_BASE_PORT = 1075;
 const TVOS_BASE_PORT = 2075;
@@ -174,6 +229,11 @@ async function getDriverPort(platform, deviceId) {
         else if (platform === 'vega') {
             port = state.nextVegaPort++;
         }
+        else if (platform === 'roku') {
+            // Roku is driven entirely over the network (ECP on the device's own port
+            // 8060) — there is no host-side driver process, so no port to reserve.
+            return 0;
+        }
         else {
             port = state.nextAndroidPort++;
         }
@@ -713,6 +773,179 @@ async function startTvOSDriver(deviceId, port = TVOS_BASE_PORT, restoreFocusAfte
 async function stopTvOSDriver(deviceId) {
     await spawnAndWait('xcrun', ['simctl', 'terminate', deviceId, TVOS_RUNNER_BUNDLE_ID]);
 }
+// ── Physical device bootstrap ─────────────────────────────────────────────────
+const DEVICE_STARTUP_TIMEOUT_MS = 300000;
+const DEVICE_STARTUP_POLL_MS = 1000;
+/**
+ * Resolve the Apple Developer team to sign the driver with.
+ *
+ * Unlike simulators, a real device only runs code signed for a team it's
+ * provisioned against, and we can't ship a signed driver — it has to be built
+ * on the user's machine with their credentials.
+ */
+async function resolveTeamId() {
+    const fromEnv = process.env.CONDUCTOR_TEAM_ID?.trim();
+    if (fromEnv)
+        return fromEnv;
+    // Fall back to the keychain when there's exactly one development team, which
+    // is the common single-account setup.
+    let identities;
+    try {
+        identities = await spawnCapture('security', ['find-identity', '-v', '-p', 'codesigning']);
+    }
+    catch {
+        identities = '';
+    }
+    const teams = new Set([...identities.matchAll(/"Apple Development:[^"]*\(([A-Z0-9]{10})\)"/g)].map((m) => m[1]));
+    if (teams.size === 1)
+        return [...teams][0];
+    throw new Error(teams.size === 0
+        ? 'No "Apple Development" signing identity found. Running on a physical device needs one — ' +
+            'sign in to Xcode ▸ Settings ▸ Accounts, then set CONDUCTOR_TEAM_ID=<team> if you have several teams.'
+        : `Multiple development teams found (${[...teams].join(', ')}). ` +
+            'Set CONDUCTOR_TEAM_ID=<team> to pick one.');
+}
+/** Where the signed device driver for a given platform + team is cached. */
+function deviceDriverCache(platform, teamId) {
+    return path_1.default.join(os_1.default.homedir(), '.conductor', `${platform}-driver-device`, teamId);
+}
+/**
+ * Build and sign the XCTest driver for a physical device.
+ *
+ * The bundled simulator builds are unsigned and the wrong slice, so the driver
+ * is compiled from the sources shipped alongside them. Building against the
+ * device (rather than a generic destination) lets Xcode register it with the
+ * team's provisioning profile on first run.
+ */
+async function setupDeviceDriver(deviceId, platform, teamId) {
+    const driversDir = await getDriversDir();
+    const projectDir = path_1.default.join(driversDir, 'ios-driver-src');
+    const project = path_1.default.join(projectDir, 'conductor-driver-ios.xcodeproj');
+    if (!fs_1.default.existsSync(project)) {
+        throw new Error(`Conductor driver sources not found at ${projectDir}.\n` +
+            `Physical devices need a locally signed driver build. Run 'make package-drivers-tarball' ` +
+            `from the repo root, or reinstall conductor to fetch a driver bundle that includes sources.`);
+    }
+    const cache = deviceDriverCache(platform, teamId);
+    const scheme = platform === 'tvos' ? 'conductor-driver-tvos' : 'conductor-driver-ios';
+    // Rebuild when the sources or the signing team change; the xctestrun naming
+    // is derived from the SDK so glob for it rather than hardcoding a version.
+    const stamp = path_1.default.join(cache, '.version');
+    const sourceMtime = String(fs_1.default.statSync(path_1.default.join(project, 'project.pbxproj')).mtimeMs);
+    let cached = '';
+    try {
+        cached = fs_1.default.readFileSync(stamp, 'utf-8').trim();
+    }
+    catch {
+        /* first run */
+    }
+    if (cached === sourceMtime && findDeviceXctestrun(cache))
+        return findDeviceXctestrun(cache);
+    (0, verbose_js_1.log)(`Building signed ${platform} driver for team ${teamId} (first run takes a few minutes)...`);
+    const args = [
+        'build-for-testing',
+        '-project',
+        project,
+        '-scheme',
+        scheme,
+        '-destination',
+        `id=${deviceId}`,
+        '-derivedDataPath',
+        cache,
+        '-allowProvisioningUpdates',
+        `DEVELOPMENT_TEAM=${teamId}`,
+    ];
+    // The first build for a team creates provisioning profiles as a side effect,
+    // and Xcode regularly references one before it lands on disk ("Build input
+    // file cannot be found: ….mobileprovision"). The profile exists by the retry.
+    try {
+        await spawnCaptureAll('xcodebuild', args);
+    }
+    catch (first) {
+        (0, verbose_js_1.log)(`Driver build failed, retrying once: ${first instanceof Error ? first.message : first}`);
+        try {
+            await spawnCaptureAll('xcodebuild', args);
+        }
+        catch (retry) {
+            throw new Error(`Could not build the ${platform} driver for team ${teamId}.\n` +
+                `${retry instanceof Error ? retry.message : String(retry)}\n` +
+                `Check that the device is registered to the team and that Xcode has an account for it.`);
+        }
+    }
+    const xctestrun = findDeviceXctestrun(cache);
+    if (!xctestrun) {
+        throw new Error(`Driver build for ${platform} produced no xctestrun under ${cache}`);
+    }
+    fs_1.default.writeFileSync(stamp, sourceMtime);
+    (0, verbose_js_1.log)(`${platform} device driver ready`);
+    return xctestrun;
+}
+/** Locate the xctestrun a device build produced — its name embeds the SDK version. */
+function findDeviceXctestrun(cache) {
+    const products = path_1.default.join(cache, 'Build', 'Products');
+    try {
+        const match = fs_1.default.readdirSync(products).find((f) => f.endsWith('.xctestrun'));
+        return match ? path_1.default.join(products, match) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Start the XCTest driver on a physical iOS/tvOS device.
+ *
+ * Mirrors startIOSDriver, with two differences forced by real hardware: the
+ * driver is built and signed locally, and it binds every interface because the
+ * device's loopback isn't shared with the host.
+ */
+async function startDeviceDriver(deviceId, platform, port) {
+    const host = await resolveDriverHost(deviceId);
+    if (await isPortOpen(port, host)) {
+        (0, verbose_js_1.log)(`${platform} device driver already running on ${host}:${port}`);
+        return;
+    }
+    const device = await (0, devicectl_js_1.findPhysicalDevice)(deviceId);
+    if (device && !device.developerModeEnabled) {
+        throw new Error(`Developer Mode is disabled on "${device.name}". ` +
+            `Enable it in Settings ▸ Privacy & Security ▸ Developer Mode and re-pair the device.`);
+    }
+    const teamId = await resolveTeamId();
+    const xctestrun = await setupDeviceDriver(deviceId, platform, teamId);
+    const testTarget = platform === 'tvos' ? 'conductor-driver-tvosUITests' : 'conductor-driver-iosUITests';
+    await spawnAndWait('plutil', [
+        '-replace',
+        `${testTarget}.EnvironmentVariables.PORT`,
+        '-string',
+        String(port),
+        xctestrun,
+    ]);
+    // The host reaches the driver over the network, so it can't bind loopback-only.
+    await spawnAndWait('plutil', [
+        '-replace',
+        `${testTarget}.EnvironmentVariables.BIND_ALL`,
+        '-string',
+        '1',
+        xctestrun,
+    ]);
+    (0, verbose_js_1.log)(`Starting ${platform} driver on ${device?.name ?? deviceId} (${host}:${port})`);
+    const proc = (0, child_process_1.spawn)('xcodebuild', ['test-without-building', '-xctestrun', xctestrun, '-destination', `id=${deviceId}`], { detached: true, stdio: ['ignore', 'ignore', 'ignore'] });
+    proc.unref();
+    const deadline = Date.now() + DEVICE_STARTUP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await (0, utils_js_1.sleep)(DEVICE_STARTUP_POLL_MS);
+        if (await isPortOpen(port, host)) {
+            (0, verbose_js_1.log)(`${platform} device driver ready on ${host}:${port}`);
+            return;
+        }
+    }
+    throw new Error(`${platform} XCTest driver did not start within ${DEVICE_STARTUP_TIMEOUT_MS / 1000}s ` +
+        `on ${host}:${port}. Check that the device is awake and on the same network.`);
+}
+/** Stop the driver on a physical device by killing the runner process. */
+async function stopDeviceDriver(deviceId, platform) {
+    const bundleId = platform === 'tvos' ? TVOS_RUNNER_BUNDLE_ID : IOS_RUNNER_BUNDLE_ID;
+    await (0, devicectl_js_1.terminateApp)(deviceId, bundleId).catch(() => { });
+}
 // ── Android bootstrap ─────────────────────────────────────────────────────────
 const ANDROID_STARTUP_TIMEOUT_MS = 30000;
 const ANDROID_STARTUP_POLL_MS = 500;
@@ -984,6 +1217,32 @@ function spawnAndWait(cmd, args) {
         proc.on('error', reject);
     });
 }
+/**
+ * Run a command, and on failure reject with the tail of its output. Used for
+ * xcodebuild, where the exit code alone tells the user nothing actionable.
+ */
+function spawnCaptureAll(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        const append = (chunk) => {
+            out += chunk.toString();
+        };
+        proc.stdout?.on('data', append);
+        proc.stderr?.on('data', append);
+        proc.on('close', (code) => {
+            if (code === 0)
+                return resolve(out);
+            const errors = out
+                .split('\n')
+                .filter((l) => l.includes('error:'))
+                .slice(0, 5)
+                .join('\n');
+            reject(new Error(`${cmd} exited ${code}${errors ? `:\n${errors}` : ''}`));
+        });
+        proc.on('error', reject);
+    });
+}
 function spawnCapture(cmd, args) {
     return new Promise((resolve, reject) => {
         const proc = (0, child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] });

package/dist/drivers/devicectl.js

@@ -0,0 +1,243 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDevicectlDevices = parseDevicectlDevices;
+exports.listPhysicalDevices = listPhysicalDevices;
+exports.findPhysicalDevice = findPhysicalDevice;
+exports.bonjourHostname = bonjourHostname;
+exports.deviceHostCandidates = deviceHostCandidates;
+exports.resolveDeviceHost = resolveDeviceHost;
+exports.installApp = installApp;
+exports.uninstallApp = uninstallApp;
+exports.launchApp = launchApp;
+exports.terminateApp = terminateApp;
+exports.listApps = listApps;
+/**
+ * `xcrun devicectl` wrapper — the physical-device counterpart to `simctl`.
+ *
+ * Simulators and real devices share the XCTest driver (same HTTP protocol), but
+ * everything around it differs: discovery, app install/launch, and reachability.
+ * This module owns the devicectl half so the rest of the CLI can stay generic.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("dns/promises"));
+const verbose_js_1 = require("../verbose.js");
+function devicectl(args, timeoutMs = 30000) {
+    return new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)('xcrun', ['devicectl', ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        const timer = setTimeout(() => {
+            proc.kill('SIGKILL');
+            reject(new Error(`devicectl ${args[0]} ${args[1] ?? ''} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        proc.stdout?.on('data', (c) => {
+            out += c.toString();
+        });
+        proc.stderr?.on('data', (c) => {
+            err += c.toString();
+        });
+        proc.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0) {
+                resolve(out);
+            }
+            else {
+                reject(new Error(`devicectl ${args.join(' ')} failed: ${err.trim() || out.trim()}`));
+            }
+        });
+        proc.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+/**
+ * Run a devicectl subcommand that reports its result as JSON. devicectl only
+ * writes structured output to a file, never stdout, so every call round-trips
+ * through a temp file.
+ */
+async function devicectlJson(args, timeoutMs = 30000) {
+    const file = path_1.default.join(os_1.default.tmpdir(), `conductor-devicectl-${process.pid}-${Math.random().toString(36).slice(2)}.json`);
+    try {
+        await devicectl([...args, '--json-output', file], timeoutMs);
+        return JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    finally {
+        fs_1.default.rmSync(file, { force: true });
+    }
+}
+function toPlatform(raw) {
+    if (!raw)
+        return null;
+    const v = raw.toLowerCase();
+    if (v === 'ios' || v === 'ipados')
+        return 'ios';
+    if (v === 'tvos')
+        return 'tvos';
+    return null;
+}
+/** Map devicectl's device list onto PhysicalDevice, dropping anything we can't drive. */
+function parseDevicectlDevices(parsed) {
+    const devices = [];
+    for (const d of parsed.result?.devices ?? []) {
+        const platform = toPlatform(d.hardwareProperties?.platform);
+        // Skip simulators (reality: "simulator") — simctl already covers those.
+        if (!platform || d.hardwareProperties?.reality !== 'physical')
+            continue;
+        devices.push({
+            identifier: d.identifier,
+            udid: d.hardwareProperties?.udid ?? d.identifier,
+            name: d.deviceProperties?.name ?? d.identifier,
+            platform,
+            // Paired isn't enough: a device that's off or on another network stays
+            // paired but reports no transport, and tunnelState goes 'unavailable'.
+            available: d.connectionProperties?.pairingState === 'paired' &&
+                d.connectionProperties?.tunnelState !== 'unavailable' &&
+                !!d.connectionProperties?.transportType,
+            potentialHostnames: d.connectionProperties?.potentialHostnames ?? [],
+            osVersion: d.deviceProperties?.osVersionNumber ?? '',
+            marketingName: d.hardwareProperties?.marketingName ?? '',
+            developerModeEnabled: d.deviceProperties?.developerModeStatus === 'enabled',
+        });
+    }
+    return devices;
+}
+/** List every paired physical iOS/tvOS device known to CoreDevice. */
+async function listPhysicalDevices() {
+    try {
+        return parseDevicectlDevices(await devicectlJson(['list', 'devices']));
+    }
+    catch (e) {
+        (0, verbose_js_1.log)(`devicectl list devices failed: ${e instanceof Error ? e.message : String(e)}`);
+        return [];
+    }
+}
+/** Cache: deviceId (identifier or udid) → device, or null when it isn't physical. */
+const _deviceCache = new Map();
+/** Look up a physical device by either its CoreDevice identifier or hardware UDID. */
+async function findPhysicalDevice(deviceId) {
+    if (_deviceCache.has(deviceId))
+        return _deviceCache.get(deviceId);
+    const key = deviceId.toLowerCase();
+    const match = (await listPhysicalDevices()).find((d) => d.identifier.toLowerCase() === key || d.udid.toLowerCase() === key) ?? null;
+    _deviceCache.set(deviceId, match);
+    return match;
+}
+/**
+ * Resolve the address the host can reach the device's driver on.
+ *
+ * devicectl's `*.coredevice.local` hostnames only resolve inside Apple's
+ * CoreDevice tunnel, so they're useless for a plain TCP connect. The device's
+ * Bonjour name (`<name>.local`) is what actually resolves on the LAN, so we
+ * derive that from the device name and resolve it to an IP once, since mDNS
+ * lookups are slow enough to matter on every driver poll.
+ */
+const _hostCache = new Map();
+/**
+ * The mDNS name a device advertises itself under, derived from its display name
+ * the same way the device does: apostrophes are dropped outright (so "Douwe's
+ * iPhone" is "Douwes-iPhone", not "Douwe-s-iPhone") and every other run of
+ * non-alphanumerics collapses to a single dash.
+ */
+function bonjourHostname(deviceName) {
+    return (deviceName
+        .replace(/['’]/g, '')
+        .replace(/[^A-Za-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '') + '.local');
+}
+/**
+ * Candidate LAN addresses, best first. devicectl's `potentialHostnames` already
+ * contain Apple's own sanitization of the device name, so re-pointing those at
+ * `.local` is more reliable than our derivation — we keep both because the
+ * hostname list is occasionally absent.
+ */
+function deviceHostCandidates(device) {
+    const fromDevicectl = device.potentialHostnames
+        .filter((h) => h.endsWith('.coredevice.local'))
+        .map((h) => h.replace(/\.coredevice\.local$/, '.local'));
+    return [
+        ...new Set([bonjourHostname(device.name), ...fromDevicectl, ...device.potentialHostnames]),
+    ];
+}
+async function resolveDeviceHost(device) {
+    const cached = _hostCache.get(device.identifier);
+    if (cached)
+        return cached;
+    const candidates = deviceHostCandidates(device);
+    for (const host of candidates) {
+        try {
+            const { address } = await promises_1.default.lookup(host, { family: 4 });
+            (0, verbose_js_1.log)(`Resolved ${device.name} → ${host} (${address})`);
+            _hostCache.set(device.identifier, address);
+            return address;
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    throw new Error(`Could not resolve a network address for "${device.name}".\n` +
+        `Tried: ${candidates.join(', ')}\n` +
+        `The device must be on the same network as this Mac for conductor to reach its driver.`);
+}
+// ── App lifecycle ─────────────────────────────────────────────────────────────
+async function installApp(deviceId, appPath) {
+    await devicectl(['device', 'install', 'app', '--device', deviceId, appPath], 300000);
+}
+async function uninstallApp(deviceId, bundleId) {
+    await devicectl(['device', 'uninstall', 'app', '--device', deviceId, bundleId], 60000);
+}
+/**
+ * Launch an app. `env` is passed as devicectl's JSON environment dictionary,
+ * which is the device-side equivalent of simctl's SIMCTL_CHILD_ vars.
+ */
+async function launchApp(deviceId, bundleId, args = [], env) {
+    const flags = ['device', 'process', 'launch', '--device', deviceId, '--terminate-existing'];
+    if (env && Object.keys(env).length > 0) {
+        flags.push('--environment-variables', JSON.stringify(env));
+    }
+    await devicectl([...flags, bundleId, ...args], 120000);
+}
+/** Terminate an app by bundle id. devicectl only kills by PID, so resolve one first. */
+async function terminateApp(deviceId, bundleId) {
+    const listed = await devicectlJson([
+        'device',
+        'info',
+        'processes',
+        '--device',
+        deviceId,
+    ]);
+    const match = (listed.result?.runningProcesses ?? []).find((p) => p.executable?.includes(`${bundleId}`));
+    if (!match)
+        return;
+    await devicectl([
+        'device',
+        'process',
+        'signal',
+        '--device',
+        deviceId,
+        '--signal',
+        'SIGKILL',
+        '--pid',
+        String(match.processIdentifier),
+    ]);
+}
+async function listApps(deviceId) {
+    const listed = await devicectlJson([
+        'device',
+        'info',
+        'apps',
+        '--device',
+        deviceId,
+    ]);
+    return (listed.result?.apps ?? []).map((a) => ({
+        id: a.bundleIdentifier,
+        name: a.name ?? a.bundleIdentifier,
+    }));
+}

package/dist/drivers/flow-runner.js

@@ -21,6 +21,8 @@ const ios_js_1 = require("./ios.js");
 const android_js_1 = require("./android.js");
 const web_js_1 = require("./web.js");
 const vega_js_1 = require("./vega.js");
+const roku_js_1 = require("./roku.js");
+const key_mapping_js_1 = require("./roku/key-mapping.js");
 const wait_js_1 = require("./wait.js");
 const direct_ios_selector_js_1 = require("./direct-ios-selector.js");
 const perf_hooks_1 = require("perf_hooks");
@@ -135,7 +137,16 @@ function parseFlowString(content, extraEnv) {
         else if (doc && typeof doc === 'object') {
             // Single-document flow: either a header-only or treat as single command
             const keys = Object.keys(doc);
-            const headerKeys = new Set(['appId', 'url', 'env', 'tags', 'onFlowStart', 'onFlowComplete']);
+            const headerKeys = new Set([
+                'appId',
+                'url',
+                'name',
+                'env',
+                'tags',
+                'properties',
+                'onFlowStart',
+                'onFlowComplete',
+            ]);
             if (keys.every((k) => headerKeys.has(k))) {
                 header = doc;
                 rawCommands = [];
@@ -552,7 +563,9 @@ function getConductorObj(driver, output) {
             ? 'web'
             : driver instanceof vega_js_1.VegaDriver
                 ? 'vega'
-                : 'android';
+                : driver instanceof roku_js_1.RokuDriver
+                    ? 'roku'
+                    : 'android';
     return {
         platform,
         copiedText: output['__copiedText'] ?? '',
@@ -684,7 +697,7 @@ async function executeCommandBody(key, val, driver, opts) {
                     await driver.pressKey('delete');
             }
             else {
-                // Android, web, and vega all expose eraseAllText.
+                // Android, web, vega, and roku all expose eraseAllText.
                 await driver.eraseAllText(n);
             }
             break;
@@ -825,7 +838,7 @@ async function executeCommandBody(key, val, driver, opts) {
                 await driver.back();
             else if (driver instanceof web_js_1.WebDriver)
                 await driver.goBack();
-            else if (driver instanceof vega_js_1.VegaDriver)
+            else if (driver instanceof vega_js_1.VegaDriver || driver instanceof roku_js_1.RokuDriver)
                 await driver.back();
             // iOS has no hardware back button — noop
             break;
@@ -1113,6 +1126,11 @@ async function executeCommandBody(key, val, driver, opts) {
                     throw new Error(`pressKey: key "${val}" is not supported on vega`);
                 await driver.pressButton(button);
             }
+            else if (driver instanceof roku_js_1.RokuDriver) {
+                if (!(0, key_mapping_js_1.rokuEcpKey)(keyName))
+                    throw new Error(`pressKey: key "${val}" is not supported on roku`);
+                await driver.pressKeyNamed(keyName);
+            }
             else {
                 const keycode = ANDROID_KEYCODES[keyName];
                 if (keycode === undefined)
@@ -1133,6 +1151,10 @@ async function executeCommandBody(key, val, driver, opts) {
             else if (driver instanceof vega_js_1.VegaDriver) {
                 // No reliable keyboard-hide primitive on vega — noop
             }
+            else if (driver instanceof roku_js_1.RokuDriver) {
+                // Roku dismisses its on-screen keyboard with Back.
+                await driver.back();
+            }
             else {
                 await driver.pressKeyEvent(111); // KEYCODE_ESCAPE
             }