taphound 0.2.0-dev.1

package/dist/adapters/prompt/inquirer-recorder-prompt.js

@@ -0,0 +1,157 @@
+import { confirm, input, number as numberPrompt, select } from "@inquirer/prompts";
+const defaultPrompts = {
+    select: async (config) => select({
+        message: config.message,
+        choices: [...config.choices]
+    }),
+    input: async (config) => input({
+        message: config.message,
+        ...(config.validate === undefined ? {} : { validate: config.validate })
+    }),
+    confirm: async (config) => confirm(config),
+    number: async (config) => numberPrompt(config)
+};
+const ACTIONS = [
+    "click",
+    "longClick",
+    "inputText",
+    "swipe",
+    "scrollTo",
+    "back",
+    "wait",
+    "finish",
+    "cancel"
+];
+function selectedString(value, allowed) {
+    if (typeof value !== "string"
+        || (allowed !== undefined && !allowed.includes(value))) {
+        throw new Error("Prompt returned an invalid selection");
+    }
+    return value;
+}
+function selectedNumber(value, minimum, maximum = Number.POSITIVE_INFINITY) {
+    if (typeof value !== "number"
+        || !Number.isFinite(value)
+        || value < minimum
+        || value > maximum) {
+        throw new Error("Prompt returned an invalid number");
+    }
+    return value;
+}
+export class InquirerRecorderPrompt {
+    prompts;
+    diagnostics;
+    constructor(prompts = defaultPrompts, diagnostics = process.stderr) {
+        this.prompts = prompts;
+        this.diagnostics = diagnostics;
+    }
+    async selectAction() {
+        const value = await this.prompts.select({
+            message: "Choose the next TapHound Action",
+            choices: ACTIONS.map((action) => ({ name: action, value: action }))
+        });
+        return selectedString(value, ACTIONS);
+    }
+    async selectTarget(choices) {
+        const value = await this.prompts.select({
+            message: "Choose a Layout target",
+            choices: choices.map((choice) => ({
+                name: choice.label,
+                value: choice.id
+            }))
+        });
+        return selectedString(value, choices.map((choice) => choice.id));
+    }
+    async inputText() {
+        const value = await this.prompts.input({
+            message: "Text to enter",
+            validate: (answer) => answer.length > 0 || "Text must not be empty"
+        });
+        return selectedString(value);
+    }
+    async selectSwipeDirection() {
+        const directions = ["up", "down", "left", "right"];
+        const value = await this.prompts.select({
+            message: "Swipe direction",
+            choices: directions.map((direction) => ({
+                name: direction,
+                value: direction
+            }))
+        });
+        return selectedString(value, directions);
+    }
+    async longClickDuration() {
+        return selectedNumber(await this.prompts.number({
+            message: "Long-click duration (ms)",
+            default: 800,
+            min: 1
+        }), 1);
+    }
+    async swipeOptions() {
+        const distancePercent = selectedNumber(await this.prompts.number({
+            message: "Swipe distance (0–1)",
+            default: 0.6,
+            min: 0.01,
+            max: 1
+        }), 0.01, 1);
+        const durationMs = selectedNumber(await this.prompts.number({
+            message: "Swipe duration (ms)",
+            default: 300,
+            min: 1
+        }), 1);
+        return { distancePercent, durationMs };
+    }
+    async selectFallbackLabel(annotatedScreenshotPath) {
+        const enabled = await this.prompts.confirm({
+            message: `Add annotated-label fallback from ${annotatedScreenshotPath}?`,
+            default: false
+        });
+        if (enabled !== true) {
+            return undefined;
+        }
+        const label = await this.prompts.input({
+            message: "Android CLI annotated label",
+            validate: (value) => /^#\d+$/.test(value) || "Use the #number format"
+        });
+        const selected = selectedString(label);
+        if (!/^#\d+$/.test(selected)) {
+            throw new Error("Fallback label must use the #number format");
+        }
+        return selected;
+    }
+    notifyFailure(message) {
+        this.diagnostics.write(`TapHound: ${message}\n`);
+        return Promise.resolve();
+    }
+    async selectScrollContainer(choices) {
+        const value = await this.prompts.select({
+            message: "Choose the scrollable container",
+            choices: choices.map((choice) => ({ name: choice.label, value: choice.id }))
+        });
+        return selectedString(value, choices.map((choice) => choice.id));
+    }
+    async scrollTargetDecision(choices) {
+        const scrollMore = "__scroll_more__";
+        const cancel = "__cancel__";
+        const value = await this.prompts.select({
+            message: "Select the target once visible, or scroll again",
+            choices: [
+                ...choices.map((choice) => ({ name: choice.label, value: choice.id })),
+                { name: "Scroll again", value: scrollMore },
+                { name: "Cancel scrollTo", value: cancel }
+            ]
+        });
+        const selected = selectedString(value, [
+            ...choices.map((choice) => choice.id),
+            scrollMore,
+            cancel
+        ]);
+        if (selected === scrollMore) {
+            return { kind: "scrollMore" };
+        }
+        if (selected === cancel) {
+            return { kind: "cancel" };
+        }
+        return { kind: "select", id: selected };
+    }
+}

package/dist/application/assertion/expectation-evaluator.d.ts

@@ -0,0 +1,61 @@
+import type { FailureCode } from "../../domain/failure.js";
+import type { Expectation } from "../../domain/journey.js";
+import type { LayoutElement } from "../../domain/layout.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 { LogcatCollector } from "../collector/logcat-collector.js";
+export interface ExpectationContext {
+    packageName: string;
+    deviceSerial: string;
+    stepStartedAt: number;
+}
+export interface ExpectationObservationInput {
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export type ActivityExpectationObservation = {
+    status: "observed";
+    activity: string;
+} | {
+    status: "failed";
+    message: string;
+};
+export type LayoutExpectationObservation = {
+    status: "observed";
+    layout: readonly LayoutElement[];
+} | {
+    status: "failed";
+    message: string;
+};
+export interface ExpectationObservationBoundary {
+    activity?: (input: ExpectationObservationInput) => Promise<ActivityExpectationObservation>;
+    layout?: (input: ExpectationObservationInput) => Promise<LayoutExpectationObservation>;
+}
+export type ExpectationResult = {
+    status: "passed";
+    type: Expectation["type"];
+    durationMs: number;
+    actual?: string | undefined;
+    matchedLine?: string | undefined;
+} | {
+    status: "failed";
+    type: Expectation["type"];
+    code: Extract<FailureCode, "EXPECT_ACTIVITY_FAILED" | "EXPECT_ELEMENT_FAILED" | "EXPECT_LOGCAT_FAILED">;
+    message: string;
+    durationMs: number;
+    actual?: string | undefined;
+} | {
+    status: "cancelled";
+    type: Expectation["type"];
+    durationMs: number;
+};
+export declare class ExpectationEvaluator {
+    private readonly adb;
+    private readonly androidCli;
+    private readonly logcat;
+    private readonly clock;
+    private readonly pollIntervalMs;
+    constructor(adb: AdbPort, androidCli: AndroidCliPort, logcat: LogcatCollector, clock: Clock, pollIntervalMs?: number);
+    evaluate(expectation: Expectation, context: ExpectationContext, signal?: AbortSignal, observations?: ExpectationObservationBoundary): Promise<ExpectationResult>;
+}

package/dist/application/assertion/expectation-evaluator.js

@@ -0,0 +1,207 @@
+import { resolveLocator } from "../locator/locator-resolver.js";
+function hasElement(elements, locator) {
+    return resolveLocator(elements, locator, { requireEnabled: false }).status
+        === "found";
+}
+function matchesLogcat(line, expectation, pattern) {
+    if (line.tag !== expectation.tag
+        || (expectation.level !== undefined
+            && line.level !== expectation.level)) {
+        return false;
+    }
+    const content = line.message ?? line.raw;
+    return typeof pattern === "string"
+        ? content.includes(pattern)
+        : pattern.test(content);
+}
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+export class ExpectationEvaluator {
+    adb;
+    androidCli;
+    logcat;
+    clock;
+    pollIntervalMs;
+    constructor(adb, androidCli, logcat, clock, pollIntervalMs = 100) {
+        this.adb = adb;
+        this.androidCli = androidCli;
+        this.logcat = logcat;
+        this.clock = clock;
+        this.pollIntervalMs = pollIntervalMs;
+    }
+    async evaluate(expectation, context, signal, observations = {}) {
+        const startedAt = this.clock.now();
+        const logPattern = expectation.type === "logcat"
+            ? (expectation.match === "regex"
+                ? new RegExp(expectation.pattern)
+                : expectation.pattern)
+            : undefined;
+        let actual;
+        for (;;) {
+            if (isAborted(signal)) {
+                return {
+                    status: "cancelled",
+                    type: expectation.type,
+                    durationMs: this.clock.now() - startedAt
+                };
+            }
+            const commandTimeoutMs = Math.max(1, expectation.timeoutMs - (this.clock.now() - startedAt));
+            try {
+                switch (expectation.type) {
+                    case "activity": {
+                        const observation = observations.activity === undefined
+                            ? {
+                                status: "observed",
+                                activity: await this.adb.currentActivity({
+                                    packageName: context.packageName,
+                                    deviceSerial: context.deviceSerial,
+                                    ...(signal === undefined ? {} : { signal }),
+                                    timeoutMs: commandTimeoutMs
+                                })
+                            }
+                            : await observations.activity({
+                                timeoutMs: commandTimeoutMs,
+                                ...(signal === undefined ? {} : { signal })
+                            });
+                        if (isAborted(signal)) {
+                            return {
+                                status: "cancelled",
+                                type: expectation.type,
+                                durationMs: this.clock.now() - startedAt
+                            };
+                        }
+                        if (observation.status === "failed") {
+                            return {
+                                status: "failed",
+                                type: expectation.type,
+                                code: "EXPECT_ACTIVITY_FAILED",
+                                message: observation.message,
+                                durationMs: this.clock.now() - startedAt
+                            };
+                        }
+                        actual = observation.activity;
+                        if (actual === expectation.value) {
+                            return {
+                                status: "passed",
+                                type: expectation.type,
+                                durationMs: this.clock.now() - startedAt,
+                                actual
+                            };
+                        }
+                        break;
+                    }
+                    case "element": {
+                        const observation = observations.layout === undefined
+                            ? {
+                                status: "observed",
+                                layout: await this.androidCli.layout({
+                                    deviceSerial: context.deviceSerial,
+                                    ...(signal === undefined ? {} : { signal }),
+                                    timeoutMs: commandTimeoutMs
+                                })
+                            }
+                            : await observations.layout({
+                                timeoutMs: commandTimeoutMs,
+                                ...(signal === undefined ? {} : { signal })
+                            });
+                        if (isAborted(signal)) {
+                            return {
+                                status: "cancelled",
+                                type: expectation.type,
+                                durationMs: this.clock.now() - startedAt
+                            };
+                        }
+                        if (observation.status === "failed") {
+                            return {
+                                status: "failed",
+                                type: expectation.type,
+                                code: "EXPECT_ELEMENT_FAILED",
+                                message: observation.message,
+                                durationMs: this.clock.now() - startedAt
+                            };
+                        }
+                        if (hasElement(observation.layout, expectation.locator)) {
+                            return {
+                                status: "passed",
+                                type: expectation.type,
+                                durationMs: this.clock.now() - startedAt
+                            };
+                        }
+                        break;
+                    }
+                    case "logcat": {
+                        const matched = this.logcat
+                            .linesBetween(context.stepStartedAt, this.clock.now())
+                            .find((line) => matchesLogcat(line, expectation, logPattern ?? ""));
+                        if (matched !== undefined) {
+                            return {
+                                status: "passed",
+                                type: expectation.type,
+                                durationMs: this.clock.now() - startedAt,
+                                matchedLine: matched.raw
+                            };
+                        }
+                        break;
+                    }
+                }
+            }
+            catch (error) {
+                const elapsed = this.clock.now() - startedAt;
+                if (isAborted(signal)) {
+                    return {
+                        status: "cancelled",
+                        type: expectation.type,
+                        durationMs: elapsed
+                    };
+                }
+                if (elapsed >= expectation.timeoutMs) {
+                    const codes = {
+                        activity: "EXPECT_ACTIVITY_FAILED",
+                        element: "EXPECT_ELEMENT_FAILED",
+                        logcat: "EXPECT_LOGCAT_FAILED"
+                    };
+                    return {
+                        status: "failed",
+                        type: expectation.type,
+                        code: codes[expectation.type],
+                        message: `${expectation.type} Expect command exceeded its timeout`,
+                        durationMs: elapsed,
+                        ...(actual === undefined ? {} : { actual })
+                    };
+                }
+                throw error;
+            }
+            const elapsed = this.clock.now() - startedAt;
+            if (elapsed >= expectation.timeoutMs) {
+                const codes = {
+                    activity: "EXPECT_ACTIVITY_FAILED",
+                    element: "EXPECT_ELEMENT_FAILED",
+                    logcat: "EXPECT_LOGCAT_FAILED"
+                };
+                return {
+                    status: "failed",
+                    type: expectation.type,
+                    code: codes[expectation.type],
+                    message: `${expectation.type} Expect did not match before timeout`,
+                    durationMs: elapsed,
+                    ...(actual === undefined ? {} : { actual })
+                };
+            }
+            const remaining = expectation.timeoutMs - elapsed;
+            try {
+                await this.clock.sleep(Math.min(this.pollIntervalMs, remaining), signal);
+            }
+            catch (error) {
+                if (isAborted(signal)) {
+                    return {
+                        status: "cancelled",
+                        type: expectation.type,
+                        durationMs: this.clock.now() - startedAt
+                    };
+                }
+                throw error;
+            }
+        }
+    }
+}

package/dist/application/collector/logcat-collector.d.ts

@@ -0,0 +1,39 @@
+import type { AdbPort } from "../../ports/adb.js";
+import type { Clock } from "../../ports/clock.js";
+import type { CommandResult } from "../../ports/process-runner.js";
+export type LogLevel = "V" | "D" | "I" | "W" | "E" | "F" | "A";
+export interface LogcatLine {
+    receivedAt: number;
+    raw: string;
+    pid?: number | undefined;
+    tid?: number | undefined;
+    level?: LogLevel | undefined;
+    tag?: string | undefined;
+    message?: string | undefined;
+}
+export interface LogcatMetadata {
+    deviceSerial: string;
+    pids: readonly number[];
+}
+export interface StartLogcatOptions {
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+}
+export declare class LogcatCollector {
+    private readonly adb;
+    private readonly clock;
+    private readonly collected;
+    private readonly stderr;
+    private readonly scopedPids;
+    private running?;
+    private streamMetadata?;
+    private stopPromise?;
+    constructor(adb: AdbPort, clock: Clock);
+    start(options: StartLogcatOptions): Promise<void>;
+    scopeToPids(pids: readonly number[]): void;
+    metadata(): LogcatMetadata;
+    lines(): readonly LogcatLine[];
+    diagnosticLines(): readonly string[];
+    linesBetween(startedAt: number, finishedAt: number): LogcatLine[];
+    stop(): Promise<CommandResult>;
+}

package/dist/application/collector/logcat-collector.js

@@ -0,0 +1,107 @@
+const THREADTIME = /^\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d+\s+(\d+)\s+(\d+)\s+([VDIWEFA])\s+([^:]+):\s?(.*)$/;
+function parseLine(raw, receivedAt) {
+    const match = THREADTIME.exec(raw);
+    if (match === null) {
+        return { receivedAt, raw };
+    }
+    const [, pid, tid, level, tag, message] = match;
+    if (pid === undefined
+        || tid === undefined
+        || level === undefined
+        || tag === undefined
+        || message === undefined) {
+        return { receivedAt, raw };
+    }
+    return {
+        receivedAt,
+        raw,
+        pid: Number(pid),
+        tid: Number(tid),
+        level: level,
+        tag: tag.trim(),
+        message
+    };
+}
+function startupFailure(result) {
+    return result.stderr.trim()
+        || result.spawnError
+        || (result.cancelled
+            ? "Logcat startup was cancelled"
+            : result.timedOut
+                ? "Logcat startup timed out"
+                : `Logcat exited during startup with code ${String(result.exitCode)}`);
+}
+export class LogcatCollector {
+    adb;
+    clock;
+    collected = [];
+    stderr = [];
+    scopedPids = new Set();
+    running;
+    streamMetadata;
+    stopPromise;
+    constructor(adb, clock) {
+        this.adb = adb;
+        this.clock = clock;
+    }
+    async start(options) {
+        if (this.running !== undefined) {
+            throw new Error("Logcat collector already started");
+        }
+        const logcatOptions = {
+            deviceSerial: options.deviceSerial,
+            onStdoutLine: (line) => {
+                this.collected.push(parseLine(line, this.clock.now()));
+            },
+            onStderrLine: (line) => {
+                this.stderr.push(line);
+            },
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        };
+        this.running = this.adb.startLogcat(logcatOptions);
+        this.streamMetadata = { deviceSerial: options.deviceSerial };
+        const startupResult = await this.running.started;
+        if (startupResult !== undefined) {
+            throw new Error(startupFailure(startupResult));
+        }
+    }
+    scopeToPids(pids) {
+        if (this.streamMetadata === undefined) {
+            throw new Error("Logcat collector has not started");
+        }
+        for (const pid of pids) {
+            if (!Number.isInteger(pid) || pid <= 0) {
+                throw new Error("Logcat PID must be a positive integer");
+            }
+            this.scopedPids.add(pid);
+        }
+    }
+    metadata() {
+        if (this.streamMetadata === undefined) {
+            throw new Error("Logcat collector has not started");
+        }
+        return {
+            deviceSerial: this.streamMetadata.deviceSerial,
+            pids: [...this.scopedPids].sort((left, right) => left - right)
+        };
+    }
+    lines() {
+        if (this.scopedPids.size === 0) {
+            return [...this.collected];
+        }
+        return this.collected.filter((line) => line.pid === undefined || this.scopedPids.has(line.pid));
+    }
+    diagnosticLines() {
+        return [...this.stderr];
+    }
+    linesBetween(startedAt, finishedAt) {
+        return this.lines().filter((line) => line.receivedAt >= startedAt && line.receivedAt <= finishedAt);
+    }
+    stop() {
+        if (this.running === undefined) {
+            throw new Error("Logcat collector has not started");
+        }
+        this.stopPromise ??= this.running.stop();
+        return this.stopPromise;
+    }
+}

package/dist/application/context/context-validator.d.ts

@@ -0,0 +1,27 @@
+import type { TapHoundConfig } from "../../domain/config.js";
+import { type ProjectFileInspector } from "../../ports/project-file-inspector.js";
+export declare const MAX_CONTEXT_EVIDENCE_BYTES: number;
+export type ContextValidationReasonCode = "CONTEXT_SCHEMA_INVALID" | "CONTEXT_IDENTITY_MISMATCH" | "PROJECT_ROOT_UNREADABLE" | "PROJECT_ROOT_NOT_DIRECTORY" | "EVIDENCE_SECRET_PATH" | "EVIDENCE_NOT_FOUND" | "EVIDENCE_UNREADABLE" | "EVIDENCE_NOT_FILE" | "EVIDENCE_PATH_ESCAPE" | "EVIDENCE_CHANGED_IDENTITY" | "EVIDENCE_TOO_LARGE" | "EVIDENCE_HASH_MISMATCH";
+export interface ContextValidationReason {
+    code: ContextValidationReasonCode;
+    message: string;
+}
+export type ContextValidationResult = {
+    status: "valid";
+} | {
+    status: "stale";
+    reason: ContextValidationReason;
+} | {
+    status: "invalid";
+    reason: ContextValidationReason;
+};
+export interface ContextValidationInput {
+    context: unknown;
+    projectRoot: string;
+    config: TapHoundConfig;
+}
+export declare class ContextValidator {
+    private readonly files;
+    constructor(files: ProjectFileInspector);
+    readonly validate: (input: ContextValidationInput) => Promise<ContextValidationResult>;
+}