taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/adapters/android-cli/android-cli-adapter.d.ts

@@ -1,11 +1,19 @@
-import type { AndroidCliPort, CaptureScreenOptions, DeviceCommandOptions, Point } from "../../ports/android-cli.js";
+import type { Point } from "../../domain/geometry.js";
+import type { AnnotatedScreenResolverPort } from "../../ports/annotated-screen-resolver.js";
 import type { CommandResult, ProcessRunner } from "../../ports/process-runner.js";
-import { parseLayout, parseLayoutDiff } from "./layout-parser.js";
-export declare class AndroidCliAdapter implements AndroidCliPort {
+import type { ScreenshotOptions, ScreenshotPort } from "../../ports/screenshot.js";
+import type { UiStabilityObservation, UiStabilityProbe, UiStabilitySampleOptions } from "../../ports/ui-stability.js";
+export declare class AndroidCliAdapter implements ScreenshotPort, AnnotatedScreenResolverPort, UiStabilityProbe {
     private readonly runner;
-    constructor(runner: ProcessRunner);
-    layout(options: DeviceCommandOptions): Promise<ReturnType<typeof parseLayout>>;
-    layoutDiff(options: DeviceCommandOptions): Promise<ReturnType<typeof parseLayoutDiff>>;
-    captureScreen(options: CaptureScreenOptions): Promise<CommandResult>;
-    resolveScreen(screenshotPath: string, label: string, signal?: AbortSignal): Promise<Point>;
+    private readonly createLayoutPath;
+    private readonly frameSignatures;
+    private readonly layoutSignatures;
+    private deviceLayoutTempSwept;
+    constructor(runner: ProcessRunner, createLayoutPath?: () => string);
+    private sweepDeviceLayoutTempOnce;
+    private readUiAutomator;
+    reset(): void;
+    sample(options: UiStabilitySampleOptions): Promise<UiStabilityObservation>;
+    capture(options: ScreenshotOptions): Promise<CommandResult>;
+    resolve(screenshotPath: string, label: string, signal?: AbortSignal): Promise<Point>;
 }

package/dist/adapters/android-cli/android-cli-adapter.js

@@ -1,4 +1,8 @@
-import { parseLayout, parseLayoutDiff } from "./layout-parser.js";
+import { createHash } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { parseLayoutDiff } from "./layout-parser.js";
+import { parseUiAutomatorLayout } from "../adb/ui-automator-parser.js";
+import { createDeviceLayoutPath, sweepDeviceLayoutTemp } from "../ui/device-layout-temp.js";
 function commandSpec(args, signal, timeoutMs) {
     return {
         executable: "android",
@@ -7,34 +11,152 @@ function commandSpec(args, signal, timeoutMs) {
         ...(timeoutMs === undefined ? {} : { timeoutMs })
     };
 }
+function adbCommandSpec(deviceSerial, args, signal, timeoutMs) {
+    return {
+        executable: "adb",
+        args: ["-s", deviceSerial, ...args],
+        ...(signal === undefined ? {} : { signal }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs })
+    };
+}
 function assertSuccess(result, operation) {
-    if (result.exitCode !== 0) {
-        throw new Error(`Android CLI ${operation} failed: ${result.stderr.trim()}`);
+    if (result.exitCode !== 0
+        || result.timedOut
+        || result.cancelled
+        || result.spawnError !== undefined) {
+        throw new Error(`Android CLI ${operation} failed: ${result.stderr.trim() || result.spawnError || "command failed"}`);
     }
 }
+class UiAutomatorUnavailableError extends Error {
+    name = "UiAutomatorUnavailableError";
+}
+function assertUiAutomatorSuccess(result, operation) {
+    if (result.timedOut || result.cancelled) {
+        throw Object.assign(new Error(`UIAutomator ${operation} did not complete before its deadline`), { terminal: true });
+    }
+    if (result.exitCode !== 0 || result.spawnError !== undefined) {
+        throw new UiAutomatorUnavailableError(result.stderr.trim()
+            || result.spawnError
+            || `UIAutomator ${operation} failed`);
+    }
+}
+function terminalBackendFailure(error) {
+    return error !== null
+        && typeof error === "object"
+        && "terminal" in error
+        && error.terminal === true;
+}
 export class AndroidCliAdapter {
     runner;
-    constructor(runner) {
+    createLayoutPath;
+    frameSignatures = new Map();
+    layoutSignatures = new Map();
+    deviceLayoutTempSwept = false;
+    constructor(runner, createLayoutPath = createDeviceLayoutPath) {
         this.runner = runner;
+        this.createLayoutPath = createLayoutPath;
     }
-    async layout(options) {
-        const result = await this.runner.run(commandSpec([
-            "layout",
-            `--device=${options.deviceSerial}`
-        ], options.signal, options.timeoutMs));
-        assertSuccess(result, "layout");
-        return parseLayout(result.stdout);
+    async sweepDeviceLayoutTempOnce(deviceSerial) {
+        if (this.deviceLayoutTempSwept) {
+            return;
+        }
+        this.deviceLayoutTempSwept = true;
+        await sweepDeviceLayoutTemp(this.runner, deviceSerial);
+    }
+    async readUiAutomator(options) {
+        const path = this.createLayoutPath();
+        await this.sweepDeviceLayoutTempOnce(options.deviceSerial);
+        const deadline = options.timeoutMs === undefined
+            ? undefined
+            : performance.now() + options.timeoutMs;
+        const dumped = await this.runner.run(adbCommandSpec(options.deviceSerial, ["shell", "uiautomator", "dump", path], options.signal, options.timeoutMs));
+        try {
+            assertUiAutomatorSuccess(dumped, "dump");
+            const remainingMs = deadline === undefined
+                ? undefined
+                : Math.max(1, deadline - performance.now());
+            const xml = await this.runner.run(adbCommandSpec(options.deviceSerial, ["exec-out", "cat", path], options.signal, remainingMs));
+            assertUiAutomatorSuccess(xml, "read");
+            const layout = parseUiAutomatorLayout(xml.stdout);
+            if (layout.length === 0) {
+                throw new Error("UIAutomator dump contained no layout roots");
+            }
+            return { layout };
+        }
+        finally {
+            await this.runner.run(adbCommandSpec(options.deviceSerial, ["shell", "rm", "-f", path], undefined, 5000)).catch(() => { });
+        }
+    }
+    reset() {
+        this.frameSignatures.clear();
+        this.layoutSignatures.clear();
     }
-    async layoutDiff(options) {
+    async sample(options) {
+        const startedAt = performance.now();
+        if (options.stabilityBackend === "uiautomator") {
+            try {
+                const current = await this.readUiAutomator(options);
+                const signature = createHash("sha256")
+                    .update(JSON.stringify(current.layout))
+                    .digest("hex");
+                const key = options.deviceSerial;
+                const previous = this.layoutSignatures.get(key);
+                this.layoutSignatures.set(key, signature);
+                return {
+                    changes: previous === signature
+                        ? []
+                        : [{ layoutSha256: signature }],
+                    layout: current.layout,
+                    backend: "uiautomator",
+                    durationMs: performance.now() - startedAt
+                };
+            }
+            catch (error) {
+                if (terminalBackendFailure(error))
+                    throw error;
+                const result = await this.runner.run(commandSpec([
+                    "layout",
+                    "--diff",
+                    `--device=${options.deviceSerial}`
+                ], options.signal, options.timeoutMs === undefined
+                    ? undefined
+                    : Math.max(1, options.timeoutMs - (performance.now() - startedAt))));
+                assertSuccess(result, "layout --diff");
+                return {
+                    changes: parseLayoutDiff(result.stdout),
+                    backend: "androidCli",
+                    durationMs: performance.now() - startedAt
+                };
+            }
+        }
+        if (options.packageName !== undefined) {
+            const result = await this.runner.run(adbCommandSpec(options.deviceSerial, ["shell", "dumpsys", "gfxinfo", options.packageName], options.signal, options.timeoutMs));
+            assertSuccess(result, "frame stability");
+            const signature = result.stdout.match(/^Total frames rendered:\s*(\d+)\s*$/m)?.[1];
+            if (signature !== undefined) {
+                const key = `${options.deviceSerial}\u0000${options.packageName}`;
+                const previous = this.frameSignatures.get(key);
+                this.frameSignatures.set(key, signature);
+                return {
+                    changes: previous === signature ? [] : [{ frameStats: signature }],
+                    backend: "gfxFrameStats",
+                    durationMs: performance.now() - startedAt
+                };
+            }
+        }
         const result = await this.runner.run(commandSpec([
             "layout",
             "--diff",
             `--device=${options.deviceSerial}`
         ], options.signal, options.timeoutMs));
         assertSuccess(result, "layout --diff");
-        return parseLayoutDiff(result.stdout);
+        return {
+            changes: parseLayoutDiff(result.stdout),
+            backend: "androidCli",
+            durationMs: performance.now() - startedAt
+        };
     }
-    captureScreen(options) {
+    capture(options) {
         return this.runner.run(commandSpec([
             "screen",
             "capture",
@@ -43,7 +165,7 @@ export class AndroidCliAdapter {
             `--device=${options.deviceSerial}`
         ], options.signal, options.timeoutMs));
     }
-    async resolveScreen(screenshotPath, label, signal) {
+    async resolve(screenshotPath, label, signal) {
         const result = await this.runner.run(commandSpec([
             "screen",
             "resolve",

package/dist/adapters/android-cli/android-cli-snapshot-provider.d.ts

@@ -0,0 +1,9 @@
+import type { ProcessRunner } from "../../ports/process-runner.js";
+import type { OpenUiSnapshotProviderOptions, UiSnapshotProvider, UiSnapshotProviderFactory } from "../../ports/ui-snapshot.js";
+import { type UiSnapshotTiming } from "../ui/ui-snapshot-support.js";
+export declare class AndroidCliSnapshotProviderFactory implements UiSnapshotProviderFactory {
+    private readonly runner;
+    private readonly timing;
+    constructor(runner: ProcessRunner, timing?: UiSnapshotTiming);
+    open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+}

package/dist/adapters/android-cli/android-cli-snapshot-provider.js

@@ -0,0 +1,99 @@
+import { createHash } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { parseLayout } from "./layout-parser.js";
+import { readDeviceUiEnvironment } from "../ui/device-ui-environment.js";
+import { UiSnapshotError } from "../ui/ui-snapshot-error.js";
+import { snapshotFromCapture } from "../ui/ui-snapshot-support.js";
+function descriptor(sdkLevel) {
+    return {
+        id: "android-cli",
+        adapterVersion: "android-cli-layout-v1",
+        engineVersion: `android-api-${String(sdkLevel)}`,
+        configSha256: createHash("sha256")
+            .update(JSON.stringify({ command: "android layout", version: 1 }))
+            .digest("hex")
+    };
+}
+class AndroidCliSnapshotProvider {
+    runner;
+    deviceSerial;
+    environment;
+    descriptor;
+    timing;
+    closed = false;
+    constructor(runner, deviceSerial, environment, descriptor, timing) {
+        this.runner = runner;
+        this.deviceSerial = deviceSerial;
+        this.environment = environment;
+        this.descriptor = descriptor;
+        this.timing = timing;
+    }
+    async capture(options) {
+        if (this.closed) {
+            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, "UI snapshot provider is closed");
+        }
+        const startedAt = performance.now();
+        const result = await this.runner.run({
+            executable: "android",
+            args: ["layout", `--device=${this.deviceSerial}`],
+            timeoutMs: options.timeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        });
+        if (result.exitCode !== 0
+            || result.timedOut
+            || result.cancelled
+            || result.spawnError !== undefined) {
+            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, result.stderr.trim() || result.spawnError || "Android CLI layout failed", { terminal: result.timedOut || result.cancelled });
+        }
+        let roots;
+        try {
+            roots = parseLayout(result.stdout);
+        }
+        catch (error) {
+            throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "Android CLI returned malformed layout source", { cause: error });
+        }
+        if (roots.length === 0) {
+            throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "Android CLI returned an empty layout");
+        }
+        return snapshotFromCapture({
+            startedAt,
+            roots,
+            backend: this.descriptor,
+            viewport: this.environment.viewport,
+            timing: this.timing
+        });
+    }
+    close() {
+        this.closed = true;
+        return Promise.resolve();
+    }
+}
+export class AndroidCliSnapshotProviderFactory {
+    runner;
+    timing;
+    constructor(runner, timing = {}) {
+        this.runner = runner;
+        this.timing = timing;
+    }
+    async open(options) {
+        const environment = await readDeviceUiEnvironment(this.runner, "android-cli", options);
+        const provider = new AndroidCliSnapshotProvider(this.runner, options.deviceSerial, environment, descriptor(environment.sdkLevel), this.timing);
+        try {
+            await provider.capture({
+                reason: "evidence",
+                timeoutMs: options.timeoutMs,
+                ...(options.signal === undefined ? {} : { signal: options.signal })
+            });
+        }
+        catch (error) {
+            if (error instanceof UiSnapshotError
+                && error.code === "UI_SNAPSHOT_FAILED"
+                && !error.terminal
+                && options.signal?.aborted !== true) {
+                throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", "android-cli", error.message, { cause: error });
+            }
+            throw error;
+        }
+        return provider;
+    }
+}

package/dist/adapters/android-cli/layout-parser.js

@@ -1,4 +1,5 @@
-import { BoundsSchema, LayoutPointSchema } from "../../domain/layout.js";
+import { LayoutPointSchema } from "../../domain/layout.js";
+import { normalizeBounds, normalizeResourceId } from "../ui/layout-normalization.js";
 function parseJson(stdout, label) {
     try {
         return JSON.parse(stdout);
@@ -44,14 +45,14 @@ function parseBounds(value) {
         if (match === null) {
             throw new Error("Invalid Android Layout bounds");
         }
-        return BoundsSchema.parse({
+        return normalizeBounds({
             left: Number(match[1]),
             top: Number(match[2]),
             right: Number(match[3]),
             bottom: Number(match[4])
         });
     }
-    return BoundsSchema.parse(value);
+    return normalizeBounds(value);
 }
 function parseCenter(value) {
     if (value === undefined) {
@@ -98,7 +99,7 @@ function parseElement(value, path) {
     if (!Array.isArray(childrenValue)) {
         throw new Error("Invalid Android Layout children");
     }
-    const resourceId = optionalString(record, "resourceId", "resource-id");
+    const resourceId = normalizeResourceId(optionalString(record, "resourceId", "resource-id"));
     const text = optionalString(record, "text");
     const contentDescription = optionalString(record, "contentDescription", "content-desc");
     const interactions = stringSet(record, "interactions");
@@ -120,15 +121,18 @@ function parseElement(value, path) {
             x: Math.round((bounds.left + bounds.right) / 2),
             y: Math.round((bounds.top + bounds.bottom) / 2)
         });
-    if (center === undefined) {
-        throw new Error("Android Layout element has no visible center or bounds");
-    }
     const children = childrenValue.flatMap((child, index) => {
         const parsed = parseElement(child, `${path}/${String(index)}`);
         return parsed === undefined ? [] : [parsed];
     });
+    const serializerKey = record.key;
+    const windowId = typeof serializerKey === "string"
+        || typeof serializerKey === "number"
+        ? String(serializerKey)
+        : undefined;
     return {
         id: elementId(record, path),
+        ...(windowId === undefined ? {} : { windowId }),
         ...(resourceId === undefined ? {} : { resourceId }),
         ...(text === undefined ? {} : { text }),
         ...(contentDescription === undefined ? {} : { contentDescription }),
@@ -138,7 +142,7 @@ function parseElement(value, path) {
         ...(focusable === undefined ? {} : { focusable }),
         ...(focused === undefined ? {} : { focused }),
         enabled: optionalBoolean(record, "enabled") ?? true,
-        center,
+        ...(center === undefined ? {} : { center }),
         ...(bounds === undefined ? {} : { bounds }),
         children
     };

package/dist/adapters/appium/appium-doctor.d.ts

@@ -0,0 +1,7 @@
+import type { ProcessRunner } from "../../ports/process-runner.js";
+export interface AppiumDoctorResult {
+    status: "passed" | "failed";
+    version?: string | undefined;
+    message?: string | undefined;
+}
+export declare function checkAppiumUiAutomator2(runner: ProcessRunner, signal?: AbortSignal): Promise<AppiumDoctorResult>;

package/dist/adapters/appium/appium-doctor.js

@@ -0,0 +1,128 @@
+function firstLine(value) {
+    return value.trim().split(/\r?\n/, 1)[0] ?? "unknown";
+}
+function driverVersion(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const serialized = JSON.stringify(value);
+    const match = serialized.match(/uiautomator2[^\d]*([\d]+(?:\.[\d]+)+(?:[-+][\w.-]+)?)/i);
+    return match?.[1];
+}
+export async function checkAppiumUiAutomator2(runner, signal) {
+    const command = async (args) => runner.run({
+        executable: "appium",
+        args,
+        timeoutMs: 5000,
+        ...(signal === undefined ? {} : { signal })
+    });
+    const serverStatus = async () => {
+        try {
+            const response = await fetch("http://127.0.0.1:4723/status", {
+                signal: AbortSignal.timeout(5000)
+            });
+            const payload = await response.json();
+            if (!response.ok)
+                throw new Error(`HTTP ${String(response.status)}`);
+            return {
+                ok: true,
+                version: typeof payload.value?.build?.version === "string"
+                    ? payload.value.build.version
+                    : undefined
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    };
+    try {
+        const version = await command(["--version"]);
+        if (version.exitCode !== 0
+            || version.spawnError !== undefined
+            || version.timedOut
+            || version.cancelled) {
+            const server = await serverStatus();
+            if (server.ok) {
+                return {
+                    status: "passed",
+                    message: `UiAutomator2 (verified via running server); server ${server.version ?? "unknown"}; start: appium --address 127.0.0.1 --port 4723`
+                };
+            }
+            return {
+                status: "failed",
+                message: version.stderr.trim() || version.spawnError || "Appium server is unavailable"
+            };
+        }
+        const drivers = await command(["driver", "list", "--installed", "--json"]);
+        if (drivers.exitCode !== 0
+            || drivers.spawnError !== undefined
+            || drivers.timedOut
+            || drivers.cancelled) {
+            const server = await serverStatus();
+            if (server.ok) {
+                return {
+                    status: "passed",
+                    version: firstLine(version.stdout),
+                    message: `UiAutomator2 (verified via running server); server ${server.version ?? "unknown"}; start: appium --address 127.0.0.1 --port 4723`
+                };
+            }
+            return {
+                status: "failed",
+                version: firstLine(version.stdout),
+                message: drivers.stderr.trim() || drivers.spawnError
+                    || "Appium UiAutomator2 driver check failed"
+            };
+        }
+        let installed;
+        try {
+            installed = JSON.parse(drivers.stdout);
+        }
+        catch {
+            return {
+                status: "failed",
+                version: firstLine(version.stdout),
+                message: "Appium driver list returned invalid JSON"
+            };
+        }
+        const driver = driverVersion(installed);
+        if (driver === undefined || !/uiautomator2/i.test(JSON.stringify(installed))) {
+            return {
+                status: "failed",
+                version: firstLine(version.stdout),
+                message: "Appium UiAutomator2 driver is not installed"
+            };
+        }
+        let serverVersion;
+        try {
+            const response = await fetch("http://127.0.0.1:4723/status", {
+                signal: AbortSignal.timeout(5000)
+            });
+            const payload = await response.json();
+            if (!response.ok)
+                throw new Error(`HTTP ${String(response.status)}`);
+            serverVersion = typeof payload.value?.build?.version === "string"
+                ? payload.value.build.version
+                : undefined;
+        }
+        catch (error) {
+            return {
+                status: "failed",
+                version: firstLine(version.stdout),
+                message: `UiAutomator2 ${driver}; start: appium --address 127.0.0.1 --port 4723 (${error instanceof Error ? error.message : String(error)})`
+            };
+        }
+        return {
+            status: "passed",
+            version: firstLine(version.stdout),
+            message: `UiAutomator2 ${driver}; server ${serverVersion ?? "unknown"}; start: appium --address 127.0.0.1 --port 4723`
+        };
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            message: error instanceof Error ? error.message : String(error)
+        };
+    }
+}

package/dist/adapters/appium/appium-ui-snapshot-provider.d.ts

@@ -0,0 +1,34 @@
+import type { ProcessRunner } from "../../ports/process-runner.js";
+import type { OpenUiSnapshotProviderOptions, UiSnapshotProvider, UiSnapshotProviderFactory } from "../../ports/ui-snapshot.js";
+export interface AppiumHttpRequest {
+    method: "GET" | "POST" | "DELETE";
+    path: string;
+    body?: unknown;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export interface AppiumHttpClient {
+    request(input: AppiumHttpRequest): Promise<{
+        value: unknown;
+    }>;
+}
+export interface AppiumProviderOptions {
+    endpoint?: string | undefined;
+    mapTestTagToResourceId?: boolean | undefined;
+}
+export declare class FetchAppiumHttpClient implements AppiumHttpClient {
+    private readonly endpoint;
+    constructor(endpoint: URL);
+    request(input: AppiumHttpRequest): Promise<{
+        value: unknown;
+    }>;
+}
+export declare class AppiumUiSnapshotProviderFactory implements UiSnapshotProviderFactory {
+    private readonly runner;
+    private readonly endpoint;
+    private readonly http;
+    private readonly settings;
+    constructor(runner: ProcessRunner, http?: AppiumHttpClient, options?: AppiumProviderOptions);
+    probe(timeoutMs?: number): Promise<boolean>;
+    open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+}