@leera.io/qa-runner 1.0.0

package/dist/src/drivers/windows-appium.js

@@ -0,0 +1,319 @@
+import { dirname } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { AppiumUnavailable } from '../appium/server.js';
+import { hostDevice } from '../devices/desktop.js';
+import { installedWindowsApp, loadWindowsSettings, sharedWinAppDriver, WINAPPDRIVER_VERSION, WINDOWS_NEEDS_WINDOWS, windowsCapabilities, windowsReadiness, } from '../devices/windows.js';
+import { homePaths } from '../home.js';
+import { androidSdkFor, configuredSdkPath, sharedAppiumServer } from './android-appium.js';
+import { clip, errorMessage, expectWithin, matches } from './common.js';
+import { DesktopAppiumDriver, validateNativeAction } from './desktop-appium.js';
+import { Blocked, LaunchRefused, } from './driver.js';
+import { emptyScreen } from './snapshot/format.js';
+import { windowsKeyActions } from './webdriver/desktop-keys.js';
+import { elementIdOf } from './webdriver/locate.js';
+import { NATIVE_DESKTOP_ACTIONS } from './webdriver/native-actions.js';
+import { describeWindowsTarget, WINDOWS_LOCATORS, windowsSelectors, xpathLiteral } from './webdriver/native-locate.js';
+import { openSession, webdriverMessage } from './webdriver/session.js';
+import { windowsSnapshotFromXml } from './webdriver/xml-tree-desktop.js';
+/** Runs an Appium Windows driver `windows:` extension command. */
+export function windowsCommand(client, command, args = {}) {
+    if (!/^[a-zA-Z]+$/.test(command))
+        throw new Error(`invalid windows command '${command}'`);
+    return client.executeScript(`windows: ${command}`, [args]);
+}
+/** `NativeWindowHandle` (decimal, as UIA reports it) → the hex form `appTopLevelWindow` takes. */
+export function windowHandleHex(value) {
+    const n = Number(value);
+    if (!value || !Number.isInteger(n) || n <= 0)
+        return null;
+    return `0x${n.toString(16)}`;
+}
+export function windowsOps(client) {
+    return {
+        platform: 'windows',
+        selectors: windowsSelectors,
+        describe: describeWindowsTarget,
+        click: async (elementId) => void (await client.elementClick(elementId)),
+        doubleClick: async (elementId) => void (await windowsCommand(client, 'click', { elementId, times: 2, interClickDelayMs: 100 })),
+        rightClick: async (elementId) => void (await windowsCommand(client, 'click', { elementId, button: 'right' })),
+        hover: async (elementId) => void (await windowsCommand(client, 'hover', { startElementId: elementId, endElementId: elementId, durationMs: 100 })),
+        press: async (chord, elementId) => {
+            // Focus the element first: `windows: keys` types into whatever has keyboard focus.
+            if (elementId)
+                await client.elementClick(elementId);
+            await windowsCommand(client, 'keys', { actions: windowsKeyActions(chord) });
+        },
+        isChecked: async (elementId) => {
+            const toggle = await client.getElementAttribute(elementId, 'Toggle.ToggleState').catch(() => null);
+            if (toggle === '1')
+                return true;
+            if (toggle === '0')
+                return false;
+            const selected = await client.getElementAttribute(elementId, 'SelectionItem.IsSelected').catch(() => null);
+            if (selected?.toLowerCase() === 'true')
+                return true;
+            if (selected?.toLowerCase() === 'false')
+                return false;
+            return null;
+        },
+        selectOption: async (elementId, value, timeoutMs) => {
+            // Expand a combo box (a list is already open), then click the list item with that name.
+            const type = await client.getElementAttribute(elementId, 'LocalizedControlType').catch(() => null);
+            if (type?.toLowerCase() !== 'list')
+                await client.elementClick(elementId);
+            const xpath = `//ListItem[@Name=${xpathLiteral(value)}]`;
+            const deadline = Date.now() + Math.max(timeoutMs, 500);
+            for (;;) {
+                for (const found of await client.findElements('xpath', xpath).catch(() => [])) {
+                    const id = elementIdOf(found);
+                    if (await client.isElementDisplayed(id).catch(() => false)) {
+                        await client.elementClick(id);
+                        return;
+                    }
+                }
+                if (Date.now() >= deadline)
+                    break;
+                await sleep(300);
+            }
+            const names = [];
+            for (const found of (await client.findElements('xpath', '//ListItem').catch(() => [])).slice(0, 30)) {
+                const name = await client.getElementAttribute(elementIdOf(found), 'Name').catch(() => null);
+                if (name)
+                    names.push(`"${clip(name)}"`);
+            }
+            await windowsCommand(client, 'keys', { actions: windowsKeyActions({ modifiers: [], key: 'escape' }) }).catch(() => undefined);
+            throw new Error(`the list has no option "${value}" (options: ${names.join(', ') || 'none'})`);
+        },
+        text: async (elementId) => {
+            const value = await client.getElementAttribute(elementId, 'Value.Value').catch(() => null);
+            if (value?.trim())
+                return value.trim();
+            const text = (await client.getElementText(elementId).catch(() => '')) ?? '';
+            if (text.trim())
+                return text.trim();
+            return ((await client.getElementAttribute(elementId, 'Name').catch(() => null)) ?? '').trim();
+        },
+    };
+}
+/** Native Windows apps through Appium's Windows driver and WinAppDriver (contracts §M). */
+export class WindowsAppiumDriver extends DesktopAppiumDriver {
+    deps;
+    platform = 'windows';
+    capabilities = { actions: NATIVE_DESKTOP_ACTIONS, targets: [...WINDOWS_LOCATORS], video: 'mp4' };
+    /** What `appium:app` names: an executable path or an AUMID. */
+    appTarget = null;
+    workingDir = null;
+    wadUrl = null;
+    disposed = false;
+    constructor(ctx, appium, deps = {}) {
+        super(ctx, appium);
+        this.deps = deps;
+    }
+    get ops() {
+        return windowsOps(this.requireClient());
+    }
+    async launch() {
+        if (process.platform !== 'win32' && !this.deps.open)
+            throw new LaunchRefused(WINDOWS_NEEDS_WINDOWS);
+        const app = this.ctx.job.app;
+        const resolved = await this.resolveApp('windows');
+        if (resolved.kind === 'installed') {
+            try {
+                this.appTarget = installedWindowsApp(app?.id ?? '');
+            }
+            catch (error) {
+                throw new LaunchRefused(`the installed app cannot be started: ${errorMessage(error)}`);
+            }
+        }
+        else {
+            this.appTarget = resolved.executable;
+            this.workingDir = resolved.executable ? dirname(resolved.executable) : null;
+        }
+        let wad = this.deps.winAppDriver;
+        if (!wad) {
+            const settings = loadWindowsSettings(process.env, this.paths);
+            const readiness = await windowsReadiness(settings);
+            if (!readiness.winAppDriver)
+                throw new LaunchRefused(`WinAppDriver ${WINAPPDRIVER_VERSION} is not installed on this runner (run \`leera-qa-runner setup windows\`)`);
+            wad = sharedWinAppDriver(readiness.winAppDriver);
+        }
+        try {
+            this.wadUrl = await wad.ensure();
+        }
+        catch (error) {
+            throw new Blocked(`WinAppDriver could not start: ${errorMessage(error)}`);
+        }
+        const args = this.firstLaunchArgs();
+        await this.startRecording();
+        await this.start(args);
+    }
+    /** Opens a session that launches the app (WinAppDriver starts it) with `args`. */
+    async start(args, topLevelWindow) {
+        const logOffset = this.appium.logOffset();
+        try {
+            const url = await this.appium.ensure();
+            const capabilities = windowsCapabilities({
+                ...(topLevelWindow ? { topLevelWindow } : { app: this.appTarget ?? '' }),
+                args: topLevelWindow ? [] : args,
+                workingDir: topLevelWindow ? null : this.workingDir,
+                wadUrl: this.wadUrl ?? '',
+                newCommandTimeoutSecs: Math.max(300, Math.ceil((this.ctx.session?.idle_timeout_seconds ?? 0) + 60)),
+            });
+            this.client = await (this.deps.open ?? openSession)(url, capabilities, 180_000);
+        }
+        catch (error) {
+            const reason = error instanceof AppiumUnavailable ? error.message : webdriverMessage(error);
+            const tail = this.appium.logSince(logOffset, 2_000).trim().split('\n').slice(-5).join(' | ');
+            throw new Blocked(`the app could not be launched: ${reason}${tail ? ` (appium: ${clip(tail)})` : ''}`);
+        }
+    }
+    /** Closes the app window and ends the session. */
+    async closeApp() {
+        const client = this.client;
+        this.client = null;
+        this.lastRefs = {};
+        if (!client)
+            return;
+        await windowsCommand(client, 'closeApp').catch(() => undefined);
+        await Promise.race([client.deleteSession().catch(() => undefined), sleep(15_000)]);
+    }
+    async run(action) {
+        if (this.skipFirstLaunch(action))
+            return {};
+        validateNativeAction('windows', action);
+        try {
+            switch (action.type) {
+                case 'launch':
+                    await this.closeApp();
+                    await this.start((action.args ?? []).map(this.render));
+                    return {};
+                case 'terminate':
+                    await this.closeApp();
+                    return {};
+                case 'focus_window':
+                    await this.focusWindow(action);
+                    return {};
+                default:
+                    return await this.runShared(action);
+            }
+        }
+        catch (error) {
+            throw this.translate(error);
+        }
+    }
+    /**
+     * Switches to the app window with that title; a window the app's session does not list (a
+     * dialog of another process) is attached to through a desktop session and `appTopLevelWindow`.
+     */
+    async focusWindow(action) {
+        const client = this.requireClient();
+        const timeout = action.timeout_ms ?? this.ctx.timeouts.actionMs;
+        const wanted = this.render(action.title ?? '');
+        let titles = [];
+        try {
+            await expectWithin(timeout, async () => {
+                if (!client.getWindowHandles || !client.switchToWindow || !client.getTitle)
+                    return false;
+                titles = [];
+                for (const handle of await client.getWindowHandles()) {
+                    await client.switchToWindow(handle);
+                    const title = await client.getTitle().catch(() => '');
+                    titles.push(title);
+                    if (matches(title, wanted, action.match))
+                        return true;
+                }
+                return false;
+            }, 'window');
+            this.lastRefs = {};
+            return;
+        }
+        catch {
+            // not one of the app session's windows: look on the desktop
+        }
+        const handle = await this.desktopWindowHandle(wanted, action.match === 'equals');
+        if (!handle) {
+            throw new Error(`expected a window whose title ${action.match === 'equals' ? 'equals' : 'contains'} "${wanted}", found ${titles.map((t) => `"${clip(t)}"`).join(', ') || 'none'}`);
+        }
+        const previous = this.client;
+        this.client = null;
+        if (previous)
+            await Promise.race([previous.deleteSession().catch(() => undefined), sleep(15_000)]);
+        await this.start([], handle);
+        this.lastRefs = {};
+    }
+    /** Finds a top-level window by title through a short-lived desktop (`Root`) session. */
+    async desktopWindowHandle(title, exact) {
+        const url = await this.appium.ensure();
+        const root = await (this.deps.open ?? openSession)(url, windowsCapabilities({ app: 'Root', wadUrl: this.wadUrl ?? '' }), 60_000);
+        try {
+            const xpath = exact ? `/Pane/Window[@Name=${xpathLiteral(title)}]` : `/Pane/Window[contains(@Name, ${xpathLiteral(title)})]`;
+            const found = (await root.findElements('xpath', xpath).catch(() => []))[0];
+            if (!found)
+                return null;
+            return windowHandleHex(await root.getElementAttribute(elementIdOf(found), 'NativeWindowHandle').catch(() => null));
+        }
+        finally {
+            await root.deleteSession().catch(() => undefined);
+        }
+    }
+    async snapshot(options = {}) {
+        const client = this.requireClient();
+        const tree = windowsSnapshotFromXml(await client.getPageSource(), this.snapshotOptions(options));
+        this.lastRefs = tree.refs;
+        const screen = await this.screen().catch(() => emptyScreen());
+        return {
+            platform: 'windows',
+            taken_at: new Date().toISOString(),
+            screen,
+            app: { id: this.ctx.job.app?.id || this.appTarget, activity: null },
+            root: tree.root,
+            text: tree.text,
+            refs: tree.refs,
+            element_count: tree.element_count,
+            truncated: tree.truncated,
+        };
+    }
+    async screen() {
+        const client = this.requireClient();
+        const [rect, title] = await Promise.all([client.getWindowRect().catch(() => null), client.getTitle?.().catch(() => null) ?? null]);
+        return {
+            width: rect?.width ?? null,
+            height: rect?.height ?? null,
+            scale: null,
+            orientation: null,
+            activity: null,
+            url: null,
+            title: title || null,
+            package: this.ctx.job.app?.id || null,
+        };
+    }
+    /** Clicks at screen coordinates (the snapshot's bounds). */
+    async tapAt(x, y) {
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            throw new Error('coordinates must be numbers');
+        await windowsCommand(this.requireClient(), 'click', { x: Math.round(x), y: Math.round(y) });
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await this.disposeCommon();
+        await this.closeApp();
+    }
+}
+export const windowsDriverFactory = {
+    platform: 'windows',
+    async availability(host) {
+        if (host.os !== 'windows')
+            return { ok: false, labels: [], devices: [], reasons: [WINDOWS_NEEDS_WINDOWS] };
+        const readiness = await windowsReadiness(loadWindowsSettings(process.env, homePaths(process.env)));
+        if (!readiness.ok)
+            return { ok: false, labels: [], devices: [], reasons: readiness.reasons };
+        return { ok: true, labels: ['windows'], devices: [hostDevice('windows', { name: host.hostname })], reasons: [] };
+    },
+    async create(ctx, shared) {
+        const paths = ctx.paths ?? homePaths(process.env);
+        const appium = shared.appium ?? sharedAppiumServer(paths, androidSdkFor(process.env, ctx.androidSdkPath ?? configuredSdkPath(paths)));
+        return new WindowsAppiumDriver(ctx, appium);
+    },
+};

package/dist/src/errors.js

@@ -0,0 +1,21 @@
+/** Process exit codes (plan §7.1). */
+export const ExitCode = {
+    ok: 0,
+    error: 1,
+    usage: 2,
+    tokenRejected: 3,
+    environmentNotReady: 4,
+    versionRefused: 5,
+    interrupted: 130,
+};
+/** An error that ends the process with a specific exit code and a message meant for a person. */
+export class ExitError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/executor.js

@@ -0,0 +1,189 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { describe, errorMessage, firstLine, screenshotName } from './drivers/common.js';
+import { isPlatform } from './devices/types.js';
+import { Blocked, LaunchRefused } from './drivers/driver.js';
+import { BrowserPool, webPlaywrightFactory } from './drivers/web-playwright.js';
+import { silentLogger } from './log.js';
+import { TemplateError } from './template.js';
+import { scriptPlatform } from './types.js';
+export { launchBrowser } from './drivers/web-playwright.js';
+/** The values a script's `{{placeholders}}` resolve to for this job. */
+export function templateContextFor(job) {
+    return {
+        baseUrl: job.environment.base_url ?? '',
+        username: job.credential?.username ?? null,
+        password: job.credential?.password ?? null,
+        runId: job.run.id,
+        appId: job.app?.id ?? null,
+        random: new Map(),
+    };
+}
+/** The platform a claimed job runs on: its `platform` (older servers: web), which its script must match. */
+export function jobPlatform(job) {
+    const platform = job.platform ?? 'web';
+    if (!isPlatform(platform))
+        throw new Error(`this runner does not know the platform '${platform}'`);
+    const scripted = scriptPlatform(job.automation);
+    if (scripted !== platform)
+        throw new Error(`the job runs on ${platform} but its script is written for ${scripted}`);
+    return platform;
+}
+export function jobContext(job, options) {
+    return {
+        jobId: job.job.id,
+        platform: jobPlatform(job),
+        lease: options.lease,
+        job,
+        template: templateContextFor(job),
+        timeouts: { actionMs: options.actionTimeoutMs, jobMs: options.jobTimeoutMs },
+        headless: options.headless,
+        ...(options.proxy ? { proxy: options.proxy } : {}),
+        video: job.capture?.video ?? 'off',
+        redact: options.redact,
+        log: options.log,
+        ...(options.app ?? {}),
+        ...(options.buildDownloadUrl ? { buildDownloadUrl: options.buildDownloadUrl } : {}),
+    };
+}
+/**
+ * A driver context for a device session. Drivers read the app, device and environment
+ * from `ctx.job`, so the session is also presented as a job with no steps (id 0, run 0).
+ */
+export function sessionContext(session, options) {
+    if (!isPlatform(session.platform))
+        throw new Error(`this runner does not know the platform '${session.platform}'`);
+    const platform = session.platform;
+    const job = {
+        kind: 'test',
+        platform,
+        app: session.app,
+        device: session.device,
+        job: { id: 0, attempt: 1, lease_seconds: session.lease_seconds, heartbeat_seconds: session.lease_seconds },
+        run: { id: 0, name: `session ${session.id}` },
+        item: { id: 0, title: `Device session ${session.id}`, steps: [] },
+        environment: session.environment,
+        credential: session.credential,
+        automation: platform === 'web' ? { version: 1, steps: [] } : { version: 2, platform, steps: [] },
+        capture: { video: 'off' },
+    };
+    return { ...jobContext(job, options), session };
+}
+/** Creates the driver for a context through the registry; a platform without a factory is blocked. */
+export async function createDriver(registry, ctx, shared) {
+    const factory = registry.get(ctx.platform);
+    if (!factory)
+        throw new Blocked(`this runner cannot run ${ctx.platform} jobs`);
+    return factory.create(ctx, shared);
+}
+/** Runs a claimed job's script on the driver its platform maps to (web, android, …). */
+export async function executeClaimedJob(registry, ctx, shared, shouldStop) {
+    const driver = await createDriver(registry, ctx, shared);
+    return executeSteps(driver, ctx.job.automation, { jobTimeoutMs: ctx.timeouts.jobMs }, shouldStop, ctx.redact);
+}
+/**
+ * Runs a script's steps in index order on a driver: stops at the first failed or
+ * blocked step, takes a "verified" screenshot after a step with expectations and a
+ * "failure" screenshot when a step does not pass, and blocks once the job's time is up.
+ */
+export async function executeSteps(driver, script, options, shouldStop, redact) {
+    const started = Date.now();
+    const deadline = started + options.jobTimeoutMs;
+    const steps = [];
+    let stopped = false;
+    let videoPath;
+    try {
+        const ordered = [...script.steps].sort((a, b) => a.index - b.index);
+        try {
+            await driver.launch();
+        }
+        catch (error) {
+            // A launch this runner refuses as configured blocks the case; other launch errors fail the job (and may be retried).
+            const first = ordered[0];
+            if (!(error instanceof LaunchRefused) || !first)
+                throw error;
+            const outcome = { index: first.index, result: 'blocked', note: redact(errorMessage(error)), screenshots: [] };
+            return { steps: [outcome], elapsedSecs: Math.max(1, Math.round((Date.now() - started) / 1000)), stopped: false };
+        }
+        for (const step of ordered) {
+            const outcome = { index: step.index, result: 'passed', screenshots: [] };
+            driver.beginStep(step.index);
+            try {
+                for (const action of step.actions) {
+                    if (shouldStop()) {
+                        stopped = true;
+                        break;
+                    }
+                    if (Date.now() > deadline) {
+                        throw new Blocked(`the job ran past its ${Math.round(options.jobTimeoutMs / 60_000)} minute limit`);
+                    }
+                    const result = await runAction(driver, action);
+                    if (result.screenshot) {
+                        outcome.screenshots.push({ name: screenshotName(step.index, action.name ?? 'screenshot'), png: result.screenshot });
+                    }
+                }
+                if (stopped)
+                    break;
+                if (step.actions.some((action) => action.type.startsWith('expect_'))) {
+                    outcome.screenshots.push({ name: screenshotName(step.index, 'verified'), png: await driver.screenshot() });
+                }
+                steps.push(outcome);
+            }
+            catch (error) {
+                outcome.result = error instanceof Blocked ? 'blocked' : 'failed';
+                outcome.note = redact(errorMessage(error));
+                const failure = await driver.screenshot().catch(() => null);
+                if (failure)
+                    outcome.screenshots.push({ name: screenshotName(step.index, 'failure'), png: failure });
+                steps.push(outcome);
+                break;
+            }
+        }
+        // Events still arriving belong to the step that started them.
+        await sleep(options.settleMs ?? 250);
+        for (const outcome of steps) {
+            const captured = driver.debug(outcome.index, outcome.result);
+            if (captured)
+                outcome.debug = captured;
+        }
+    }
+    finally {
+        videoPath = await driver.stopRecording().catch(() => undefined);
+        await driver.dispose().catch(() => undefined);
+    }
+    return {
+        steps,
+        elapsedSecs: Math.max(1, Math.round((Date.now() - started) / 1000)),
+        stopped,
+        ...(videoPath ? { videoPath } : {}),
+    };
+}
+/** Prefixes the action's description; template problems block the step rather than fail it. */
+async function runAction(driver, action) {
+    try {
+        return await driver.run(action);
+    }
+    catch (error) {
+        const message = `${describe(action)}: ${firstLine(error)}`;
+        throw error instanceof Blocked || error instanceof TemplateError ? new Blocked(message) : new Error(message);
+    }
+}
+/** Runs a web job on an already launched browser (kept for callers of the pre-driver API). */
+export async function executeWebJob(browser, job, options, shouldStop, redact) {
+    const ctx = {
+        jobId: job.job.id,
+        platform: 'web',
+        lease: null,
+        job,
+        template: templateContextFor(job),
+        timeouts: { actionMs: options.actionTimeoutMs, jobMs: options.jobTimeoutMs },
+        headless: options.headless,
+        ...(options.proxy ? { proxy: options.proxy } : {}),
+        video: job.capture?.video ?? 'off',
+        redact,
+        log: silentLogger,
+    };
+    const driver = await webPlaywrightFactory.create(ctx, { browsers: BrowserPool.of(browser) });
+    return executeSteps(driver, job.automation, { jobTimeoutMs: options.jobTimeoutMs }, shouldStop, redact);
+}
+/** @deprecated use executeWebJob */
+export const executeJob = executeWebJob;

package/dist/src/home.js

@@ -0,0 +1,76 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** `LEERA_RUNNER_HOME`, else `~/.leera-qa-runner`. */
+export function homePaths(env = process.env) {
+    const root = env.LEERA_RUNNER_HOME?.trim() || join(homedir(), '.leera-qa-runner');
+    return {
+        root,
+        config: join(root, 'config.json'),
+        token: join(root, 'token'),
+        state: join(root, 'state.json'),
+        install: join(root, 'install.json'),
+        logs: join(root, 'logs'),
+        log: join(root, 'logs', 'runner.log'),
+        browsers: join(root, 'browsers'),
+        jobs: join(root, 'jobs'),
+        versions: join(root, 'versions'),
+    };
+}
+const isWindows = process.platform === 'win32';
+/** Creates the home directory (mode 0700) when missing. */
+export function ensureHome(paths) {
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    if (!isWindows)
+        chmodSync(paths.root, 0o700);
+}
+/** Writes a file atomically with owner-only permissions. */
+export function writePrivateFile(path, contents) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, contents, { mode: 0o600 });
+    if (!isWindows)
+        chmodSync(temp, 0o600);
+    renameSync(temp, path);
+}
+/** True when group or others can read or write the file (always false on Windows, where ACLs apply). */
+export function isTooOpen(path) {
+    if (isWindows)
+        return false;
+    return (statSync(path).mode & 0o077) !== 0;
+}
+/** The fixed argv that limits a file to the current user on Windows. */
+export function windowsAclArgv(path, user) {
+    return ['icacls', path, '/inheritance:r', '/grant:r', `${user}:F`];
+}
+/** Reads the stored token, narrowing its permissions to 0600 when they were wider. */
+export function readTokenFile(paths) {
+    if (!existsSync(paths.token))
+        return { token: null, fixedPermissions: false };
+    let fixedPermissions = false;
+    if (isTooOpen(paths.token)) {
+        chmodSync(paths.token, 0o600);
+        fixedPermissions = true;
+    }
+    const token = readFileSync(paths.token, 'utf8').trim();
+    return { token: token || null, fixedPermissions };
+}
+export function writeTokenFile(paths, token) {
+    ensureHome(paths);
+    writePrivateFile(paths.token, `${token.trim()}\n`);
+    if (isWindows && process.env.USERNAME) {
+        const user = process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${process.env.USERNAME}` : process.env.USERNAME;
+        const [command, ...args] = windowsAclArgv(paths.token, user);
+        spawnSync(command, args, { stdio: 'ignore', windowsHide: true });
+    }
+}
+export function readJsonFile(path) {
+    if (!existsSync(path))
+        return null;
+    // Installers on Windows may write a UTF-8 byte order mark.
+    const text = readFileSync(path, 'utf8').replace(/^\uFEFF/, '');
+    if (!text.trim())
+        return null;
+    return JSON.parse(text);
+}

package/dist/src/index.js

@@ -0,0 +1,22 @@
+// Docker entry: starts the runner from the environment (RUNNER_URL, RUNNER_TOKEN, …).
+import { stopSharedAppiumServer } from './drivers/android-appium.js';
+import { messageOf } from './errors.js';
+import { createLogger } from './log.js';
+import { createRunner } from './runner.js';
+const log = createLogger({ console: 'json' });
+async function main() {
+    const { runner, shared } = await createRunner({ env: process.env, log });
+    process.once('SIGTERM', () => runner.stop());
+    process.once('SIGINT', () => runner.stop());
+    try {
+        await runner.run();
+    }
+    finally {
+        await shared.browsers.close();
+        await stopSharedAppiumServer();
+    }
+}
+main().catch((error) => {
+    log.error('runner stopped', { error: messageOf(error) });
+    process.exitCode = 1;
+});