taphound 0.2.0-dev.1

package/dist/application/interaction/scroll-to-executor.js

@@ -0,0 +1,191 @@
+import { resolveLocator } from "../locator/locator-resolver.js";
+function isCancelled(signal) {
+    return signal?.aborted === true;
+}
+function callbackFailure(error, swipesUsed) {
+    if (error !== null
+        && typeof error === "object"
+        && "code" in error
+        && typeof error.code === "string"
+        && [
+            "ACTIVITY_BEFORE_MISMATCH",
+            "ACTIVITY_AFTER_MISMATCH",
+            "ACTION_FAILED"
+        ].includes(error.code)) {
+        return {
+            status: "failed",
+            code: error.code,
+            message: error instanceof Error ? error.message : error.code,
+            swipesUsed
+        };
+    }
+    return undefined;
+}
+export class ScrollToExecutor {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async execute(step, signal, initialLayout) {
+        let swipesUsed = 0;
+        let layout = initialLayout;
+        for (;;) {
+            if (isCancelled(signal)) {
+                return { status: "cancelled", swipesUsed };
+            }
+            try {
+                layout ??= this.options.readLayout === undefined
+                    ? await this.options.androidCli.layout({
+                        deviceSerial: this.options.deviceSerial,
+                        ...(signal === undefined ? {} : { signal }),
+                        timeoutMs: this.options.idle.timeoutMs
+                    })
+                    : await this.options.readLayout();
+            }
+            catch (error) {
+                const failed = callbackFailure(error, swipesUsed);
+                if (failed !== undefined)
+                    return failed;
+                throw error;
+            }
+            if (isCancelled(signal)) {
+                return { status: "cancelled", swipesUsed };
+            }
+            const target = resolveLocator(layout, step.locator, { requireEnabled: false });
+            if (target.status === "found") {
+                return { status: "found", swipesUsed };
+            }
+            if (target.code === "LOCATOR_AMBIGUOUS") {
+                return {
+                    status: "failed",
+                    code: "LOCATOR_AMBIGUOUS",
+                    message: target.message,
+                    swipesUsed
+                };
+            }
+            if (swipesUsed >= step.maxSwipes) {
+                return {
+                    status: "failed",
+                    code: "SCROLL_TARGET_NOT_FOUND",
+                    message: `Target not visible after ${String(step.maxSwipes)} swipes`,
+                    swipesUsed
+                };
+            }
+            let container = resolveLocator(layout, step.container, { requireEnabled: false });
+            if (container.status !== "found") {
+                return {
+                    status: "failed",
+                    code: container.code,
+                    message: container.message,
+                    swipesUsed
+                };
+            }
+            if (container.element.bounds === undefined) {
+                return {
+                    status: "failed",
+                    code: "ACTION_FAILED",
+                    message: "scroll container has no bounds to swipe",
+                    swipesUsed
+                };
+            }
+            if (this.options.beforeSwipe !== undefined) {
+                try {
+                    layout = await this.options.beforeSwipe();
+                }
+                catch (error) {
+                    const failed = callbackFailure(error, swipesUsed);
+                    if (failed !== undefined)
+                        return failed;
+                    throw error;
+                }
+                if (isCancelled(signal)) {
+                    return { status: "cancelled", swipesUsed };
+                }
+                const liveTarget = resolveLocator(layout, step.locator, { requireEnabled: false });
+                if (liveTarget.status === "found") {
+                    return { status: "found", swipesUsed };
+                }
+                if (liveTarget.code === "LOCATOR_AMBIGUOUS") {
+                    return {
+                        status: "failed",
+                        code: "LOCATOR_AMBIGUOUS",
+                        message: liveTarget.message,
+                        swipesUsed
+                    };
+                }
+                container = resolveLocator(layout, step.container, { requireEnabled: false });
+                if (container.status !== "found") {
+                    return {
+                        status: "failed",
+                        code: container.code,
+                        message: container.message,
+                        swipesUsed
+                    };
+                }
+                if (container.element.bounds === undefined) {
+                    return {
+                        status: "failed",
+                        code: "ACTION_FAILED",
+                        message: "scroll container has no bounds to swipe",
+                        swipesUsed
+                    };
+                }
+            }
+            if (isCancelled(signal)) {
+                return { status: "cancelled", swipesUsed };
+            }
+            if (this.options.requireLiveContainerCapability === true
+                && (!container.element.enabled
+                    || container.element.scrollable !== true)) {
+                return {
+                    status: "failed",
+                    code: "ACTION_FAILED",
+                    message: "scroll container lost enabled scrollable bounds",
+                    swipesUsed
+                };
+            }
+            try {
+                await this.options.beforeMutation?.();
+            }
+            catch (error) {
+                const failed = callbackFailure(error, swipesUsed);
+                if (failed !== undefined)
+                    return failed;
+                throw error;
+            }
+            if (isCancelled(signal)) {
+                return { status: "cancelled", swipesUsed };
+            }
+            const swipe = await this.options.actionExecutor.swipeBounds(container.element.bounds, step.direction, step.distancePercent, step.durationMs, signal);
+            if (isCancelled(signal)) {
+                return { status: "cancelled", swipesUsed };
+            }
+            if (swipe.status === "failed") {
+                return {
+                    status: "failed",
+                    code: swipe.code,
+                    message: swipe.message,
+                    swipesUsed
+                };
+            }
+            const idle = await this.options.idleWaiter.waitUntilIdle(this.options.idle, signal);
+            if (isCancelled(signal)) {
+                return { status: "cancelled", swipesUsed };
+            }
+            if (idle.status === "cancelled") {
+                return { status: "cancelled", swipesUsed };
+            }
+            if (idle.status === "timeout") {
+                return {
+                    status: "failed",
+                    code: idle.code,
+                    message: "Layout did not become stable before timeout",
+                    swipesUsed,
+                    idle: { polls: idle.polls, lastDiff: idle.lastDiff }
+                };
+            }
+            swipesUsed += 1;
+            layout = undefined;
+        }
+    }
+}

package/dist/application/locator/locator-resolver.d.ts

@@ -0,0 +1,20 @@
+import type { FailureCode } from "../../domain/failure.js";
+import { type LocatorField } from "../../domain/locator.js";
+import type { LayoutElement, Locator } from "../../domain/layout.js";
+import type { Point } from "../../ports/android-cli.js";
+export interface LocatedTarget {
+    status: "found";
+    element: LayoutElement;
+    point: Point;
+    matchedBy: LocatorField;
+}
+export interface LocatorFailure {
+    status: "failed";
+    code: Extract<FailureCode, "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "ACTION_FAILED">;
+    message: string;
+}
+export type LocatorResolution = LocatedTarget | LocatorFailure;
+export interface LocatorResolutionOptions {
+    requireEnabled?: boolean | undefined;
+}
+export declare function resolveLocator(roots: readonly LayoutElement[], locator: Locator, options?: LocatorResolutionOptions): LocatorResolution;

package/dist/application/locator/locator-resolver.js

@@ -0,0 +1,89 @@
+import { LOCATOR_FIELDS } from "../../domain/locator.js";
+function flatten(elements) {
+    return elements.flatMap((element) => [
+        element,
+        ...flatten(element.children)
+    ]);
+}
+function center(element) {
+    if (element.center !== undefined) {
+        return element.center;
+    }
+    const bounds = element.bounds;
+    if (bounds === undefined) {
+        throw new Error(`Layout element ${element.id} has no center or bounds`);
+    }
+    return {
+        x: Math.round((bounds.left + bounds.right) / 2),
+        y: Math.round((bounds.top + bounds.bottom) / 2)
+    };
+}
+export function resolveLocator(roots, locator, options = {}) {
+    const elements = flatten(roots);
+    let candidates;
+    let matchedBy;
+    for (const field of LOCATOR_FIELDS) {
+        const value = locator[field];
+        if (value === undefined) {
+            continue;
+        }
+        if (candidates === undefined) {
+            const matches = elements.filter((element) => element[field] === value);
+            if (matches.length === 0) {
+                continue;
+            }
+            candidates = matches;
+            matchedBy = field;
+        }
+        else if (candidates.length > 1) {
+            const narrowed = candidates.filter((element) => element[field] === value);
+            if (narrowed.length === 0) {
+                return {
+                    status: "failed",
+                    code: "LOCATOR_NOT_FOUND",
+                    message: `Locator fields conflict at ${field}`
+                };
+            }
+            candidates = narrowed;
+            matchedBy = field;
+        }
+        if (candidates.length === 1) {
+            break;
+        }
+    }
+    if (candidates === undefined || candidates.length === 0) {
+        return {
+            status: "failed",
+            code: "LOCATOR_NOT_FOUND",
+            message: "No Layout element matches the Locator"
+        };
+    }
+    if (candidates.length > 1) {
+        return {
+            status: "failed",
+            code: "LOCATOR_AMBIGUOUS",
+            message: `Locator matches ${String(candidates.length)} Layout elements`
+        };
+    }
+    const element = candidates[0];
+    if (element === undefined || matchedBy === undefined) {
+        return {
+            status: "failed",
+            code: "LOCATOR_NOT_FOUND",
+            message: "No Layout element matches the Locator"
+        };
+    }
+    if (options.requireEnabled !== false && !element.enabled) {
+        return {
+            status: "failed",
+            code: "ACTION_FAILED",
+            message: `Layout element ${element.id} is disabled`
+        };
+    }
+    return {
+        status: "found",
+        element,
+        point: center(element),
+        matchedBy
+    };
+}

package/dist/application/project/project-describer.d.ts

@@ -0,0 +1,14 @@
+import type { TapHoundConfig } from "../../domain/config.js";
+export interface ProjectDescribeInput {
+    projectRoot: string;
+    config: TapHoundConfig;
+    signal?: AbortSignal | undefined;
+}
+export interface ProjectDescription {
+    projectRoot: string;
+    packageName: string;
+    launchActivity: string;
+}
+export declare class ProjectDescriber {
+    readonly describe: (input: ProjectDescribeInput) => Promise<ProjectDescription>;
+}

package/dist/application/project/project-describer.js

@@ -0,0 +1,8 @@
+import { normalizeActivity } from "../../domain/activity.js";
+export class ProjectDescriber {
+    describe = async (input) => Promise.resolve({
+        projectRoot: input.projectRoot,
+        packageName: input.config.run.packageName,
+        launchActivity: normalizeActivity(input.config.run.packageName, input.config.run.activity)
+    });
+}

package/dist/application/recorder/locator-selector.d.ts

@@ -0,0 +1,10 @@
+import type { LayoutElement, Locator } from "../../domain/layout.js";
+export interface RecorderTarget {
+    element: LayoutElement;
+    locator: Locator;
+    label: string;
+}
+export type RecorderTargetAction = "click" | "longClick" | "swipe";
+export declare function selectUniqueLocator(target: LayoutElement, roots: readonly LayoutElement[]): Locator | undefined;
+export declare function listRecorderTargets(roots: readonly LayoutElement[], action: RecorderTargetAction): RecorderTarget[];
+export declare function listLocatableTargets(roots: readonly LayoutElement[]): RecorderTarget[];

package/dist/application/recorder/locator-selector.js

@@ -0,0 +1,80 @@
+import { LOCATOR_FIELDS } from "../../domain/locator.js";
+function flatten(elements) {
+    return elements.flatMap((element) => [
+        element,
+        ...flatten(element.children)
+    ]);
+}
+export function selectUniqueLocator(target, roots) {
+    const elements = flatten(roots);
+    for (const field of LOCATOR_FIELDS) {
+        const value = target[field];
+        if (value !== undefined
+            && value.length > 0
+            && elements.filter((element) => element[field] === value).length === 1) {
+            return { [field]: value };
+        }
+    }
+    return undefined;
+}
+function targetLabel(element, locator) {
+    const identity = LOCATOR_FIELDS.find((field) => locator[field] !== undefined);
+    if (identity === undefined) {
+        return element.id;
+    }
+    const value = locator[identity] ?? element.id;
+    return `${element.id} — ${identity}: ${value}`;
+}
+function supportsAction(element, action) {
+    return action === "click"
+        ? element.clickable === true
+        : action === "longClick"
+            ? element.longClickable === true
+            : element.scrollable === true && element.bounds !== undefined;
+}
+export function listRecorderTargets(roots, action) {
+    const primary = flatten(roots).flatMap((element) => {
+        if (!element.enabled || !supportsAction(element, action)) {
+            return [];
+        }
+        const locator = selectUniqueLocator(element, roots);
+        if (locator === undefined) {
+            return [];
+        }
+        return [{
+                element,
+                locator,
+                label: targetLabel(element, locator)
+            }];
+    });
+    // Relaxed content targets are click-only: for longClick the interactive
+    // target is often a small bounded view (e.g. a chat bubble), so a sibling
+    // label's center coordinate hit-tests to a neighbouring element instead.
+    if (action !== "click") {
+        return primary;
+    }
+    const hasOrphan = flatten(roots).some((element) => element.enabled
+        && supportsAction(element, action)
+        && selectUniqueLocator(element, roots) === undefined);
+    if (!hasOrphan) {
+        return primary;
+    }
+    const primaryIds = new Set(primary.map((target) => target.element.id));
+    const relaxed = listLocatableTargets(roots).filter((target) => !supportsAction(target.element, action)
+        && !primaryIds.has(target.element.id)
+        && (target.locator.text !== undefined
+            || target.locator.contentDescription !== undefined));
+    return [...primary, ...relaxed];
+}
+export function listLocatableTargets(roots) {
+    return flatten(roots).flatMap((element) => {
+        if (!element.enabled) {
+            return [];
+        }
+        const locator = selectUniqueLocator(element, roots);
+        if (locator === undefined) {
+            return [];
+        }
+        return [{ element, locator, label: targetLabel(element, locator) }];
+    });
+}

package/dist/application/recorder/recorder-service.d.ts

@@ -0,0 +1,41 @@
+import type { TapHoundConfig } from "../../domain/config.js";
+import { type Journey } from "../../domain/journey.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { Clock } from "../../ports/clock.js";
+import type { JourneyWriterPort } from "../../ports/journey-writer.js";
+import type { RecorderPromptPort } from "../../ports/recorder-prompt.js";
+export interface RecorderDependencies {
+    androidCli: AndroidCliPort;
+    adb: AdbPort;
+    clock: Clock;
+    prompt: RecorderPromptPort;
+    journeyWriter: JourneyWriterPort;
+}
+export interface RecordInput {
+    config: TapHoundConfig;
+    projectRoot: string;
+    deviceSerial: string;
+    journeyName: string;
+    outputPath: string;
+    signal?: AbortSignal | undefined;
+}
+export type RecordResult = {
+    status: "completed";
+    stepsRecorded: number;
+    journey: Journey;
+} | {
+    status: "cancelled";
+    stepsRecorded: number;
+} | {
+    status: "failed";
+    stepsRecorded: number;
+    message: string;
+};
+export declare class RecorderService {
+    private readonly dependencies;
+    constructor(dependencies: RecorderDependencies);
+    record(input: RecordInput): Promise<RecordResult>;
+    private prepareAction;
+    private prepareScrollTo;
+}