taphound 0.2.0-dev.1

package/dist/application/recorder/recorder-service.js

@@ -0,0 +1,331 @@
+import { parse } from "node:path";
+import { normalizeActivity } from "../../domain/activity.js";
+import { primaryAppPid } from "../../domain/app-process.js";
+import { JourneySchema, JourneyStepSchema } from "../../domain/journey.js";
+import { ActionExecutor } from "../interaction/action-executor.js";
+import { resolveLocator } from "../locator/locator-resolver.js";
+import { launchFailure } from "../runtime/launch-failure.js";
+import { ProcessWaiter } from "../runtime/process-waiter.js";
+import { IdleWaiter } from "../wait/idle-waiter.js";
+import { listLocatableTargets, listRecorderTargets } from "./locator-selector.js";
+function failedCommand(result) {
+    return result.exitCode !== 0
+        || result.timedOut
+        || result.cancelled
+        || result.spawnError !== undefined;
+}
+function commandMessage(result, fallback) {
+    return result.stderr.trim() || result.spawnError || fallback;
+}
+function annotatedPath(outputPath) {
+    const output = parse(outputPath);
+    return `${output.dir}/${output.name}.annotated.png`;
+}
+function actionTarget(target) {
+    if (target === undefined) {
+        return undefined;
+    }
+    const bounds = target.element.bounds;
+    const point = target.element.center ?? (bounds === undefined
+        ? undefined
+        : {
+            x: Math.round((bounds.left + bounds.right) / 2),
+            y: Math.round((bounds.top + bounds.bottom) / 2)
+        });
+    if (point === undefined) {
+        return undefined;
+    }
+    return {
+        point,
+        ...(bounds === undefined ? {} : { bounds })
+    };
+}
+export class RecorderService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async record(input) {
+        const launchActivity = normalizeActivity(input.config.run.packageName, input.config.run.activity);
+        const identity = {
+            packageName: input.config.run.packageName,
+            deviceSerial: input.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: input.config.idle.timeoutMs
+        };
+        if (!await this.dependencies.adb.isInstalled(identity)) {
+            return {
+                status: "failed",
+                stepsRecorded: 0,
+                message: `Package ${input.config.run.packageName} is not installed on ${input.deviceSerial}`
+            };
+        }
+        const stopped = await this.dependencies.adb.forceStop(identity);
+        if (failedCommand(stopped)) {
+            return {
+                status: "failed",
+                stepsRecorded: 0,
+                message: commandMessage(stopped, "App reset failed")
+            };
+        }
+        const launchError = launchFailure(await this.dependencies.adb.launchActivity({
+            packageName: input.config.run.packageName,
+            activity: launchActivity,
+            deviceSerial: input.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: input.config.idle.timeoutMs
+        }));
+        if (launchError !== undefined) {
+            return {
+                status: "failed",
+                stepsRecorded: 0,
+                message: launchError
+            };
+        }
+        const processReadiness = await new ProcessWaiter(this.dependencies.adb, this.dependencies.clock).wait({
+            packageName: input.config.run.packageName,
+            deviceSerial: input.deviceSerial,
+            pollIntervalMs: input.config.idle.pollIntervalMs,
+            timeoutMs: input.config.idle.timeoutMs,
+            ...(input.signal === undefined ? {} : { signal: input.signal })
+        });
+        if (processReadiness.status === "cancelled") {
+            return { status: "cancelled", stepsRecorded: 0 };
+        }
+        if (processReadiness.status === "timeout") {
+            return {
+                status: "failed",
+                stepsRecorded: 0,
+                message: "App process was not found after launch"
+            };
+        }
+        const idleWaiter = new IdleWaiter(this.dependencies.androidCli, this.dependencies.clock, input.deviceSerial);
+        await this.dependencies.androidCli.layout({
+            deviceSerial: input.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: input.config.idle.timeoutMs
+        });
+        const startupIdle = await idleWaiter.waitUntilIdle(input.config.idle, input.signal);
+        if (startupIdle.status === "cancelled") {
+            return { status: "cancelled", stepsRecorded: 0 };
+        }
+        if (startupIdle.status === "timeout") {
+            return {
+                status: "failed",
+                stepsRecorded: 0,
+                message: "Layout did not become stable before timeout"
+            };
+        }
+        const steps = [];
+        const executor = new ActionExecutor(this.dependencies.adb, input.deviceSerial);
+        for (;;) {
+            const layout = await this.dependencies.androidCli.layout({
+                deviceSerial: input.deviceSerial,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                timeoutMs: input.config.idle.timeoutMs
+            });
+            const action = await this.dependencies.prompt.selectAction();
+            if (action === "cancel") {
+                return { status: "cancelled", stepsRecorded: steps.length };
+            }
+            if (action === "finish") {
+                if (steps.length === 0) {
+                    return {
+                        status: "failed",
+                        stepsRecorded: 0,
+                        message: "Journey requires at least one successful step"
+                    };
+                }
+                const journey = JourneySchema.parse({
+                    version: 1,
+                    name: input.journeyName,
+                    steps
+                });
+                await this.dependencies.journeyWriter.write(input.outputPath, journey);
+                return { status: "completed", stepsRecorded: steps.length, journey };
+            }
+            const prepared = await this.prepareAction(action, layout, input);
+            if (prepared === undefined) {
+                continue;
+            }
+            // scrollTo captures `before` post-scroll by design: it does not navigate, so before==after in practice (replay checks `before` pre-scroll but the Activity is unchanged).
+            const before = normalizeActivity(input.config.run.packageName, await this.dependencies.adb.currentActivity(identity));
+            if (prepared.draft.action !== "scrollTo") {
+                const execution = await executor.execute(prepared.draft, actionTarget(prepared.target), input.signal);
+                if (execution.status === "failed") {
+                    await this.dependencies.prompt.notifyFailure(execution.message);
+                    continue;
+                }
+                const idle = await idleWaiter.waitUntilIdle(input.config.idle, input.signal);
+                if (idle.status !== "stable") {
+                    if (idle.status === "cancelled") {
+                        return { status: "cancelled", stepsRecorded: steps.length };
+                    }
+                    return {
+                        status: "failed",
+                        stepsRecorded: steps.length,
+                        message: "Layout did not become stable before timeout"
+                    };
+                }
+            }
+            const processes = await this.dependencies.adb.appProcesses(identity);
+            if (primaryAppPid(processes, input.config.run.packageName) === null) {
+                return {
+                    status: "failed",
+                    stepsRecorded: steps.length,
+                    message: "App process crashed after the recorded Action"
+                };
+            }
+            const after = normalizeActivity(input.config.run.packageName, await this.dependencies.adb.currentActivity(identity));
+            steps.push(JourneyStepSchema.parse({
+                ...prepared.draft,
+                activity: { before, after }
+            }));
+        }
+    }
+    async prepareAction(action, layout, input) {
+        if (action === "scrollTo") {
+            return this.prepareScrollTo(layout, input);
+        }
+        if (action === "inputText") {
+            return {
+                draft: { action, text: await this.dependencies.prompt.inputText() }
+            };
+        }
+        if (action === "back" || action === "wait") {
+            return { draft: { action } };
+        }
+        const targets = listRecorderTargets(layout, action);
+        if (targets.length === 0) {
+            await this.dependencies.prompt.notifyFailure("No enabled element has a unique deterministic Locator");
+            return undefined;
+        }
+        const selectedId = await this.dependencies.prompt.selectTarget(targets.map((target) => ({
+            id: target.element.id,
+            label: target.label
+        })));
+        const target = targets.find((candidate) => candidate.element.id === selectedId);
+        if (target === undefined) {
+            await this.dependencies.prompt.notifyFailure("Selected Layout element is unavailable");
+            return undefined;
+        }
+        if (action === "swipe") {
+            const options = await this.dependencies.prompt.swipeOptions();
+            return {
+                target,
+                draft: {
+                    action,
+                    locator: target.locator,
+                    direction: await this.dependencies.prompt.selectSwipeDirection(),
+                    ...options
+                }
+            };
+        }
+        let fallback;
+        const screenshotPath = annotatedPath(input.outputPath);
+        const capture = await this.dependencies.androidCli.captureScreen({
+            outputPath: screenshotPath,
+            annotate: true,
+            deviceSerial: input.deviceSerial,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            timeoutMs: input.config.idle.timeoutMs
+        });
+        if (!failedCommand(capture)) {
+            const label = await this.dependencies.prompt.selectFallbackLabel(screenshotPath);
+            if (label !== undefined) {
+                fallback = { type: "annotatedLabel", label };
+            }
+        }
+        if (action === "click") {
+            return {
+                target,
+                draft: {
+                    action,
+                    locator: target.locator,
+                    ...(fallback === undefined ? {} : { fallback })
+                }
+            };
+        }
+        return {
+            target,
+            draft: {
+                action,
+                locator: target.locator,
+                durationMs: await this.dependencies.prompt.longClickDuration(),
+                ...(fallback === undefined ? {} : { fallback })
+            }
+        };
+    }
+    async prepareScrollTo(layout, input) {
+        const containers = listRecorderTargets(layout, "swipe");
+        if (containers.length === 0) {
+            await this.dependencies.prompt.notifyFailure("No scrollable element has a unique deterministic Locator");
+            return undefined;
+        }
+        const containerId = await this.dependencies.prompt.selectScrollContainer(containers.map((c) => ({ id: c.element.id, label: c.label })));
+        const container = containers.find((c) => c.element.id === containerId);
+        if (container === undefined) {
+            await this.dependencies.prompt.notifyFailure("Selected container is unavailable");
+            return undefined;
+        }
+        const direction = await this.dependencies.prompt.selectSwipeDirection();
+        const options = await this.dependencies.prompt.swipeOptions();
+        const executor = new ActionExecutor(this.dependencies.adb, input.deviceSerial);
+        const idleWaiter = new IdleWaiter(this.dependencies.androidCli, this.dependencies.clock, input.deviceSerial);
+        let currentLayout = layout;
+        let swipesUsed = 0;
+        for (;;) {
+            const targets = listLocatableTargets(currentLayout);
+            const decision = await this.dependencies.prompt.scrollTargetDecision(targets.map((t) => ({ id: t.element.id, label: t.label })));
+            if (decision.kind === "cancel") {
+                return undefined;
+            }
+            if (decision.kind === "select") {
+                const target = targets.find((t) => t.element.id === decision.id);
+                if (target === undefined) {
+                    await this.dependencies.prompt.notifyFailure("Selected target is unavailable");
+                    return undefined;
+                }
+                return {
+                    target,
+                    draft: {
+                        action: "scrollTo",
+                        locator: target.locator,
+                        container: container.locator,
+                        direction,
+                        maxSwipes: Math.min(30, swipesUsed + 5),
+                        distancePercent: options.distancePercent,
+                        durationMs: options.durationMs
+                    }
+                };
+            }
+            const resolved = resolveLocator(currentLayout, container.locator, {
+                requireEnabled: false
+            });
+            if (resolved.status !== "found" || resolved.element.bounds === undefined) {
+                await this.dependencies.prompt.notifyFailure("Scroll container disappeared");
+                return undefined;
+            }
+            if (swipesUsed >= 30) {
+                await this.dependencies.prompt.notifyFailure("scrollTo reached the 30-swipe recording cap; the Journey would not replay");
+                return undefined;
+            }
+            const swipe = await executor.swipeBounds(resolved.element.bounds, direction, options.distancePercent, options.durationMs, input.signal);
+            if (swipe.status === "failed") {
+                await this.dependencies.prompt.notifyFailure(swipe.message);
+                return undefined;
+            }
+            const idle = await idleWaiter.waitUntilIdle(input.config.idle, input.signal);
+            if (idle.status !== "stable") {
+                await this.dependencies.prompt.notifyFailure("Layout did not become stable before timeout");
+                return undefined;
+            }
+            swipesUsed += 1;
+            currentLayout = await this.dependencies.androidCli.layout({
+                deviceSerial: input.deviceSerial,
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                timeoutMs: input.config.idle.timeoutMs
+            });
+        }
+    }
+}

package/dist/application/report/report-writer.d.ts

@@ -0,0 +1,10 @@
+import { type TapHoundReport } from "../../domain/report.js";
+import type { ArtifactSession } from "../../ports/artifact-store.js";
+export interface PublishedReport {
+    directory: string;
+    reportPath: string;
+    summaryPath: string;
+}
+export declare class ReportWriter {
+    writeAndPublish(session: ArtifactSession, input: TapHoundReport): Promise<PublishedReport>;
+}

package/dist/application/report/report-writer.js

@@ -0,0 +1,39 @@
+import { join } from "node:path";
+import { TapHoundReportSchema } from "../../domain/report.js";
+function renderSummary(report) {
+    const lines = [
+        `TapHound run ${report.runId}: ${report.status.toUpperCase()}`,
+        `Journey: ${report.journey.name}`,
+        `Package: ${report.project.packageName}`,
+        `Device: ${report.environment.deviceSerial}`,
+        "",
+        "Layers:",
+        ...Object.entries(report.layers).map(([layer, status]) => `- ${layer}: ${status}`)
+    ];
+    if (report.primaryFailure !== undefined) {
+        lines.push("", `Primary failure: ${report.primaryFailure.code}: ${report.primaryFailure.message}`);
+    }
+    if (report.secondaryErrors.length > 0) {
+        lines.push("", "Secondary errors:", ...report.secondaryErrors.map((error) => `- ${error.code}: ${error.message}`));
+    }
+    return `${lines.join("\n")}\n`;
+}
+export class ReportWriter {
+    async writeAndPublish(session, input) {
+        const report = TapHoundReportSchema.parse(input);
+        try {
+            await session.writeJson("report.json", report);
+            await session.writeText("summary.txt", renderSummary(report));
+            const directory = await session.publish();
+            return {
+                directory,
+                reportPath: join(directory, "report.json"),
+                summaryPath: join(directory, "summary.txt")
+            };
+        }
+        catch (error) {
+            await session.discard();
+            throw error;
+        }
+    }
+}

package/dist/application/runtime/activity-waiter.d.ts

@@ -0,0 +1,33 @@
+import type { AdbPort } from "../../ports/adb.js";
+import type { Clock } from "../../ports/clock.js";
+export interface ActivityWaitOptions {
+    packageName: string;
+    deviceSerial: string;
+    expectedActivity: string;
+    pollIntervalMs: number;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export type ActivityWaitResult = {
+    status: "ready";
+    actual: string;
+    durationMs: number;
+} | {
+    status: "timeout";
+    actual?: string | undefined;
+    durationMs: number;
+} | {
+    status: "processMissing";
+    actual?: string | undefined;
+    durationMs: number;
+} | {
+    status: "cancelled";
+    actual?: string | undefined;
+    durationMs: number;
+};
+export declare class ActivityWaiter {
+    private readonly adb;
+    private readonly clock;
+    constructor(adb: AdbPort, clock: Clock);
+    wait(options: ActivityWaitOptions): Promise<ActivityWaitResult>;
+}

package/dist/application/runtime/activity-waiter.js

@@ -0,0 +1,73 @@
+import { primaryAppPid } from "../../domain/app-process.js";
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+export class ActivityWaiter {
+    adb;
+    clock;
+    constructor(adb, clock) {
+        this.adb = adb;
+        this.clock = clock;
+    }
+    async wait(options) {
+        const startedAt = this.clock.now();
+        let actual;
+        for (;;) {
+            if (isAborted(options.signal)) {
+                return {
+                    status: "cancelled",
+                    durationMs: this.clock.now() - startedAt,
+                    ...(actual === undefined ? {} : { actual })
+                };
+            }
+            const elapsed = this.clock.now() - startedAt;
+            if (elapsed >= options.timeoutMs) {
+                return {
+                    status: "timeout",
+                    durationMs: elapsed,
+                    ...(actual === undefined ? {} : { actual })
+                };
+            }
+            const commandTimeoutMs = Math.max(1, options.timeoutMs - elapsed);
+            const identity = {
+                packageName: options.packageName,
+                deviceSerial: options.deviceSerial,
+                timeoutMs: commandTimeoutMs,
+                ...(options.signal === undefined ? {} : { signal: options.signal })
+            };
+            const processes = await this.adb.appProcesses(identity);
+            if (primaryAppPid(processes, options.packageName) === null) {
+                return {
+                    status: "processMissing",
+                    durationMs: this.clock.now() - startedAt,
+                    ...(actual === undefined ? {} : { actual })
+                };
+            }
+            actual = await this.adb.currentActivity(identity);
+            if (actual === options.expectedActivity) {
+                return {
+                    status: "ready",
+                    actual,
+                    durationMs: this.clock.now() - startedAt
+                };
+            }
+            const elapsedAfterPoll = this.clock.now() - startedAt;
+            if (elapsedAfterPoll >= options.timeoutMs) {
+                return { status: "timeout", actual, durationMs: elapsedAfterPoll };
+            }
+            try {
+                await this.clock.sleep(Math.min(options.pollIntervalMs, options.timeoutMs - elapsedAfterPoll), options.signal);
+            }
+            catch (error) {
+                if (isAborted(options.signal)) {
+                    return {
+                        status: "cancelled",
+                        actual,
+                        durationMs: this.clock.now() - startedAt
+                    };
+                }
+                throw error;
+            }
+        }
+    }
+}

package/dist/application/runtime/launch-failure.d.ts

@@ -0,0 +1,2 @@
+import type { CommandResult } from "../../ports/process-runner.js";
+export declare function launchFailure(result: CommandResult): string | undefined;

package/dist/application/runtime/launch-failure.js

@@ -0,0 +1,20 @@
+const AM_START_ERROR = /^Error(:| type)/m;
+export function launchFailure(result) {
+    if (result.spawnError !== undefined) {
+        return result.spawnError;
+    }
+    if (result.timedOut) {
+        return "App launch timed out";
+    }
+    if (result.cancelled) {
+        return "App launch was cancelled";
+    }
+    if (result.exitCode !== 0) {
+        return result.stderr.trim()
+            || `App launch exited with code ${String(result.exitCode)}`;
+    }
+    const reported = result.stdout
+        .split(/\r?\n/)
+        .find((line) => AM_START_ERROR.test(line.trim()));
+    return reported?.trim();
+}

package/dist/application/runtime/process-waiter.d.ts

@@ -0,0 +1,27 @@
+import type { AdbPort } from "../../ports/adb.js";
+import type { Clock } from "../../ports/clock.js";
+export interface ProcessWaitOptions {
+    packageName: string;
+    deviceSerial: string;
+    pollIntervalMs: number;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export type ProcessWaitResult = {
+    status: "ready";
+    pid: number;
+    pids: readonly number[];
+    durationMs: number;
+} | {
+    status: "timeout";
+    durationMs: number;
+} | {
+    status: "cancelled";
+    durationMs: number;
+};
+export declare class ProcessWaiter {
+    private readonly adb;
+    private readonly clock;
+    constructor(adb: AdbPort, clock: Clock);
+    wait(options: ProcessWaitOptions): Promise<ProcessWaitResult>;
+}

package/dist/application/runtime/process-waiter.js

@@ -0,0 +1,73 @@
+import { appProcessPids, primaryAppPid } from "../../domain/app-process.js";
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+export class ProcessWaiter {
+    adb;
+    clock;
+    constructor(adb, clock) {
+        this.adb = adb;
+        this.clock = clock;
+    }
+    async wait(options) {
+        const startedAt = this.clock.now();
+        for (;;) {
+            if (isAborted(options.signal)) {
+                return {
+                    status: "cancelled",
+                    durationMs: this.clock.now() - startedAt
+                };
+            }
+            const elapsed = this.clock.now() - startedAt;
+            const remainingMs = options.timeoutMs - elapsed;
+            if (remainingMs <= 0) {
+                return { status: "timeout", durationMs: elapsed };
+            }
+            let pid;
+            let pids;
+            try {
+                const processes = await this.adb.appProcesses({
+                    packageName: options.packageName,
+                    deviceSerial: options.deviceSerial,
+                    timeoutMs: remainingMs,
+                    ...(options.signal === undefined ? {} : { signal: options.signal })
+                });
+                pid = primaryAppPid(processes, options.packageName);
+                pids = appProcessPids(processes);
+            }
+            catch (error) {
+                if (isAborted(options.signal)) {
+                    return {
+                        status: "cancelled",
+                        durationMs: this.clock.now() - startedAt
+                    };
+                }
+                throw error;
+            }
+            if (pid !== null) {
+                return {
+                    status: "ready",
+                    pid,
+                    pids,
+                    durationMs: this.clock.now() - startedAt
+                };
+            }
+            const elapsedAfterPoll = this.clock.now() - startedAt;
+            if (elapsedAfterPoll >= options.timeoutMs) {
+                return { status: "timeout", durationMs: elapsedAfterPoll };
+            }
+            try {
+                await this.clock.sleep(Math.min(options.pollIntervalMs, options.timeoutMs - elapsedAfterPoll), options.signal);
+            }
+            catch (error) {
+                if (isAborted(options.signal)) {
+                    return {
+                        status: "cancelled",
+                        durationMs: this.clock.now() - startedAt
+                    };
+                }
+                throw error;
+            }
+        }
+    }
+}

package/dist/application/runtime/step-runner.d.ts

@@ -0,0 +1,50 @@
+import type { JourneyStep } from "../../domain/journey.js";
+import type { ReportFailure, StepReport } from "../../domain/report.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { ArtifactSession } from "../../ports/artifact-store.js";
+import type { Clock } from "../../ports/clock.js";
+import type { LogcatCollector } from "../collector/logcat-collector.js";
+import { type IdleConfig } from "../wait/idle-waiter.js";
+export interface StepRunnerOptions {
+    adb: AdbPort;
+    androidCli: AndroidCliPort;
+    clock: Clock;
+    logcat: LogcatCollector;
+    artifacts: ArtifactSession;
+    packageName: string;
+    deviceSerial: string;
+    idle: IdleConfig;
+    requireFocusedInput?: boolean;
+    generatedReplayPolicy?: boolean | undefined;
+}
+export type StepRunResult = {
+    status: "passed";
+    report: StepReport;
+} | {
+    status: "failed";
+    report: StepReport;
+    failure: ReportFailure;
+} | {
+    status: "cancelled";
+    report: StepReport;
+};
+export declare class StepRunner {
+    private readonly options;
+    private readonly actionExecutor;
+    private readonly fallbackResolver;
+    private readonly idleWaiter;
+    private readonly expectationEvaluator;
+    private readonly scrollToExecutor;
+    constructor(options: StepRunnerOptions);
+    private readonly identity;
+    private readonly primaryPid;
+    private generatedForeground;
+    private assertGeneratedForeground;
+    private currentExpectedActivity;
+    private currentSignal;
+    private observeExpectedActivity;
+    private observeExpectedLayout;
+    private captureGeneratedLayout;
+    run(step: JourneyStep, index: number, signal?: AbortSignal): Promise<StepRunResult>;
+}