taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/adapters/ui/ui-snapshot-support.d.ts

@@ -0,0 +1,15 @@
+import type { DisplayViewport } from "../../domain/geometry.js";
+import type { LayoutElement } from "../../domain/layout.js";
+import type { UiBackendDescriptor } from "../../domain/ui-backend.js";
+import type { UiSnapshot } from "../../ports/ui-snapshot.js";
+export interface UiSnapshotTiming {
+    now?: (() => Date) | undefined;
+    createObservationId?: (() => string) | undefined;
+}
+export declare function snapshotFromCapture(input: {
+    startedAt: number;
+    roots: readonly LayoutElement[];
+    backend: UiBackendDescriptor;
+    viewport: DisplayViewport;
+    timing: UiSnapshotTiming;
+}): UiSnapshot;

package/dist/adapters/ui/ui-snapshot-support.js

@@ -0,0 +1,12 @@
+import { randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
+export function snapshotFromCapture(input) {
+    return {
+        observationId: (input.timing.createObservationId ?? randomUUID)(),
+        capturedAt: (input.timing.now ?? (() => new Date()))().toISOString(),
+        durationMs: performance.now() - input.startedAt,
+        backend: input.backend,
+        viewport: input.viewport,
+        roots: input.roots
+    };
+}

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

@@ -0,0 +1,42 @@
+import type { FailureCode } from "../../domain/failure.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { AlignPromptPort } from "../../ports/align-prompt.js";
+import type { CameraProbePort, CameraProbeResult } from "../../ports/camera-probe.js";
+import type { ExternalFlowRegistry, WriteExternalFlowResult } from "../../ports/external-flow-registry.js";
+export declare class AlignError extends Error {
+    readonly code: FailureCode;
+    constructor(code: FailureCode, message: string);
+}
+export interface AlignServiceDeps {
+    adb: Pick<AdbPort, "devices">;
+    probe: CameraProbePort;
+    prompt: AlignPromptPort;
+    registry: ExternalFlowRegistry;
+}
+export interface AlignCameraInput {
+    projectRoot: string;
+    deviceSerial?: string | undefined;
+    force?: boolean | undefined;
+    json: boolean;
+    signal?: AbortSignal | undefined;
+}
+export interface AlignCameraWrittenResult {
+    status: "written";
+    exitCode: 0;
+    flow: WriteExternalFlowResult & {
+        name: string;
+        steps: number;
+    };
+    probe: CameraProbeResult;
+    deviceSerial: string;
+}
+export interface AlignCameraCancelledResult {
+    status: "cancelled";
+    exitCode: 2;
+}
+export type AlignCameraResult = AlignCameraWrittenResult | AlignCameraCancelledResult;
+export declare class AlignService {
+    private readonly deps;
+    constructor(deps: AlignServiceDeps);
+    alignCamera(input: AlignCameraInput): Promise<AlignCameraResult>;
+}

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

@@ -0,0 +1,106 @@
+import { CameraProbeError } from "../../ports/camera-probe.js";
+export class AlignError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AlignError";
+        this.code = code;
+    }
+}
+const FLOW_NAME = "camera/photo-capture";
+function selectDevice(devices, requested) {
+    const online = devices.filter((device) => device.status === "device");
+    if (requested !== undefined) {
+        return online.find((device) => device.serial === requested)?.serial;
+    }
+    return online.length === 1 ? online[0]?.serial : undefined;
+}
+function buildFlow(probeResult, deviceSerial) {
+    const steps = [
+        { action: "wait", expectedActivity: probeResult.activityName },
+        {
+            action: "click",
+            locator: { resourceId: probeResult.shutterResourceId },
+            expectedActivity: probeResult.activityName
+        }
+    ];
+    if (probeResult.confirmResourceId !== undefined) {
+        steps.push({
+            action: "click",
+            locator: { resourceId: probeResult.confirmResourceId },
+            expectedActivity: probeResult.confirmActivityName
+                ?? probeResult.activityName
+        });
+    }
+    return {
+        version: 1,
+        kind: "externalFlow",
+        name: FLOW_NAME,
+        description: `Auto-generated by \`taphound align camera\` for ${probeResult.packageName} on ${deviceSerial}`,
+        escapedPackageName: probeResult.packageName,
+        expectedEscapeActivity: probeResult.activityName,
+        includes: [],
+        steps
+    };
+}
+export class AlignService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async alignCamera(input) {
+        const devices = await this.deps.adb.devices(input.signal);
+        const deviceSerial = selectDevice(devices, input.deviceSerial);
+        if (deviceSerial === undefined) {
+            throw new AlignError("ALIGN_DEVICE_UNAVAILABLE", input.deviceSerial === undefined
+                ? `Expected exactly one online device, found ${String(devices.filter((d) => d.status === "device").length)}`
+                : `Requested device is not online: ${input.deviceSerial}`);
+        }
+        let probeResult;
+        try {
+            probeResult = await this.deps.probe.probe({
+                deviceSerial,
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+        }
+        catch (error) {
+            if (error instanceof CameraProbeError) {
+                throw new AlignError(error.code, error.message);
+            }
+            throw error;
+        }
+        if (!input.json) {
+            const confirmed = await this.deps.prompt.confirmWrite({
+                values: probeResult,
+                targetPath: `.taphound/flows/external/${FLOW_NAME}.json`
+            });
+            if (!confirmed) {
+                return { status: "cancelled", exitCode: 2 };
+            }
+        }
+        const flow = buildFlow(probeResult, deviceSerial);
+        let writeResult;
+        try {
+            writeResult = await this.deps.registry.write({
+                projectRoot: input.projectRoot,
+                name: FLOW_NAME,
+                flow,
+                ...(input.force === undefined ? {} : { force: input.force })
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/already exists/i.test(message)) {
+                throw new AlignError("ALIGN_FLOW_EXISTS", `External Flow already exists: ${FLOW_NAME} (use --force to overwrite)`);
+            }
+            throw error;
+        }
+        return {
+            status: "written",
+            exitCode: 0,
+            flow: { ...writeResult, name: FLOW_NAME, steps: flow.steps.length },
+            probe: probeResult,
+            deviceSerial
+        };
+    }
+}

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

@@ -1,14 +1,17 @@
 import type { FailureCode } from "../../domain/failure.js";
 import type { Expectation } from "../../domain/journey.js";
+import type { StepReport } from "../../domain/report.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";
+import type { UiSnapshotProvider } from "../../ports/ui-snapshot.js";
+import type { LogcatCollector, LogcatLine } from "../collector/logcat-collector.js";
 export interface ExpectationContext {
     packageName: string;
     deviceSerial: string;
     stepStartedAt: number;
+    runStartedAt?: number | undefined;
+    markers?: ReadonlyMap<string, number> | undefined;
 }
 export interface ExpectationObservationInput {
     timeoutMs: number;
@@ -38,24 +41,34 @@ export type ExpectationResult = {
     durationMs: number;
     actual?: string | undefined;
     matchedLine?: string | undefined;
+    logcatEvent?: NonNullable<StepReport["expectation"]>["logcatEvent"];
 } | {
     status: "failed";
     type: Expectation["type"];
-    code: Extract<FailureCode, "EXPECT_ACTIVITY_FAILED" | "EXPECT_ELEMENT_FAILED" | "EXPECT_LOGCAT_FAILED">;
+    code: Extract<FailureCode, "EXPECT_ACTIVITY_FAILED" | "EXPECT_ELEMENT_FAILED" | "EXPECT_LOGCAT_FAILED" | "EXPECT_LOGCAT_AMBIGUOUS">;
     message: string;
     durationMs: number;
     actual?: string | undefined;
+    logcatEvent?: NonNullable<StepReport["expectation"]>["logcatEvent"];
 } | {
     status: "cancelled";
     type: Expectation["type"];
     durationMs: number;
 };
+type ElementExpectation = Extract<Expectation, {
+    type: "element";
+}>;
+export declare function elementPredicateMismatch(element: LayoutElement, expectation: ElementExpectation): string | undefined;
 export declare class ExpectationEvaluator {
     private readonly adb;
-    private readonly androidCli;
+    private readonly uiSnapshotProvider;
     private readonly logcat;
     private readonly clock;
     private readonly pollIntervalMs;
-    constructor(adb: AdbPort, androidCli: AndroidCliPort, logcat: LogcatCollector, clock: Clock, pollIntervalMs?: number);
+    private readonly matchedEvents;
+    constructor(adb: AdbPort, uiSnapshotProvider: UiSnapshotProvider, logcat: LogcatCollector, clock: Clock, pollIntervalMs?: number);
+    /** Internal runtime-only evidence, deliberately absent from JSON results. */
+    matchedEventFor(result: ExpectationResult): LogcatLine | undefined;
     evaluate(expectation: Expectation, context: ExpectationContext, signal?: AbortSignal, observations?: ExpectationObservationBoundary): Promise<ExpectationResult>;
 }
+export {};

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

@@ -1,7 +1,18 @@
+import { createHash } from "node:crypto";
+import { matchesLogcatEvent, requestErrorClassFor } from "../collector/logcat-event.js";
 import { resolveLocator } from "../locator/locator-resolver.js";
-function hasElement(elements, locator) {
-    return resolveLocator(elements, locator, { requireEnabled: false }).status
-        === "found";
+export function elementPredicateMismatch(element, expectation) {
+    if (expectation.enabled !== undefined
+        && element.enabled !== expectation.enabled) {
+        return `element ${element.id} enabled=${element.enabled ? "true" : "false"}`
+            + `, expected enabled=${expectation.enabled ? "true" : "false"}`;
+    }
+    if (expectation.clickable !== undefined
+        && (element.clickable === true) !== expectation.clickable) {
+        return `element ${element.id} clickable=${element.clickable === true ? "true" : "false"}`
+            + `, expected clickable=${expectation.clickable ? "true" : "false"}`;
+    }
+    return undefined;
 }
 function matchesLogcat(line, expectation, pattern) {
     if (line.tag !== expectation.tag
@@ -19,17 +30,22 @@ function isAborted(signal) {
 }
 export class ExpectationEvaluator {
     adb;
-    androidCli;
+    uiSnapshotProvider;
     logcat;
     clock;
     pollIntervalMs;
-    constructor(adb, androidCli, logcat, clock, pollIntervalMs = 100) {
+    matchedEvents = new WeakMap();
+    constructor(adb, uiSnapshotProvider, logcat, clock, pollIntervalMs = 100) {
         this.adb = adb;
-        this.androidCli = androidCli;
+        this.uiSnapshotProvider = uiSnapshotProvider;
         this.logcat = logcat;
         this.clock = clock;
         this.pollIntervalMs = pollIntervalMs;
     }
+    /** Internal runtime-only evidence, deliberately absent from JSON results. */
+    matchedEventFor(result) {
+        return this.matchedEvents.get(result);
+    }
     async evaluate(expectation, context, signal, observations = {}) {
         const startedAt = this.clock.now();
         const logPattern = expectation.type === "logcat"
@@ -38,6 +54,43 @@ export class ExpectationEvaluator {
                 : expectation.pattern)
             : undefined;
         let actual;
+        let elementObservation;
+        const window = expectation.type === "logcatEvent"
+            ? expectation.window
+            : undefined;
+        const windowStart = window === undefined
+            ? undefined
+            : window.from === "stepStart"
+                ? context.stepStartedAt
+                : window.from === "runStart"
+                    ? context.runStartedAt
+                    : context.markers?.get(window.markerId);
+        if (window !== undefined && windowStart === undefined) {
+            return {
+                status: "failed",
+                type: "logcatEvent",
+                code: "EXPECT_LOGCAT_FAILED",
+                message: "Logcat event window source is unavailable",
+                durationMs: 0
+            };
+        }
+        const eventEvidence = (matched) => window === undefined || windowStart === undefined
+            ? undefined
+            : {
+                matchedCount: matched.length,
+                ...(matched.length !== 1 || matched[0] === undefined
+                    ? {}
+                    : {
+                        matchedLineSha256: createHash("sha256")
+                            .update(matched[0].raw)
+                            .digest("hex"),
+                        ...(requestErrorClassFor(matched[0]) === undefined
+                            ? {} : { requestErrorClass: requestErrorClassFor(matched[0]) })
+                    }),
+                window,
+                startedAtMs: windowStart
+            };
+        let eventMatches = [];
         for (;;) {
             if (isAborted(signal)) {
                 return {
@@ -95,11 +148,12 @@ export class ExpectationEvaluator {
                         const observation = observations.layout === undefined
                             ? {
                                 status: "observed",
-                                layout: await this.androidCli.layout({
-                                    deviceSerial: context.deviceSerial,
+                                layout: (await this.uiSnapshotProvider.capture({
+                                    reason: "expect",
+                                    freshness: "sameMutationEpoch",
                                     ...(signal === undefined ? {} : { signal }),
                                     timeoutMs: commandTimeoutMs
-                                })
+                                })).roots
                             }
                             : await observations.layout({
                                 timeoutMs: commandTimeoutMs,
@@ -121,12 +175,34 @@ export class ExpectationEvaluator {
                                 durationMs: this.clock.now() - startedAt
                             };
                         }
-                        if (hasElement(observation.layout, expectation.locator)) {
-                            return {
-                                status: "passed",
-                                type: expectation.type,
-                                durationMs: this.clock.now() - startedAt
-                            };
+                        const resolution = resolveLocator(observation.layout, expectation.locator, { requireEnabled: false });
+                        if (expectation.absent === true) {
+                            if (resolution.status === "failed"
+                                && resolution.code === "LOCATOR_NOT_FOUND"
+                                && resolution.evidenceMismatch !== true) {
+                                return {
+                                    status: "passed",
+                                    type: expectation.type,
+                                    durationMs: this.clock.now() - startedAt
+                                };
+                            }
+                            elementObservation = resolution.status === "found"
+                                ? `expected absent element matched by ${resolution.matchedBy}`
+                                : `expected absent element still resolvable: ${resolution.message}`;
+                        }
+                        else if (resolution.status === "found") {
+                            const mismatch = elementPredicateMismatch(resolution.element, expectation);
+                            if (mismatch === undefined) {
+                                return {
+                                    status: "passed",
+                                    type: expectation.type,
+                                    durationMs: this.clock.now() - startedAt
+                                };
+                            }
+                            elementObservation = mismatch;
+                        }
+                        else {
+                            elementObservation = resolution.message;
                         }
                         break;
                     }
@@ -142,6 +218,45 @@ export class ExpectationEvaluator {
                                 matchedLine: matched.raw
                             };
                         }
+                        if (!this.logcat.completeSince(context.stepStartedAt)) {
+                            const metadata = this.logcat.metadata();
+                            return {
+                                status: "failed",
+                                type: expectation.type,
+                                code: "EXPECT_LOGCAT_FAILED",
+                                message: "Logcat evidence is incomplete in the step window"
+                                    + ` (droppedLines=${String(metadata.droppedLines ?? 0)},`
+                                    + ` droppedBytes=${String(metadata.droppedBytes ?? 0)},`
+                                    + ` lastDroppedAtMs=${String(metadata.lastDroppedAtMs ?? "unknown")})`,
+                                durationMs: this.clock.now() - startedAt
+                            };
+                        }
+                        break;
+                    }
+                    case "logcatEvent": {
+                        if (windowStart === undefined || !this.logcat.completeSince(windowStart)) {
+                            return {
+                                status: "failed",
+                                type: expectation.type,
+                                code: "EXPECT_LOGCAT_FAILED",
+                                message: "Logcat event evidence is incomplete in the declared window",
+                                durationMs: this.clock.now() - startedAt,
+                                logcatEvent: eventEvidence(eventMatches)
+                            };
+                        }
+                        eventMatches = this.logcat
+                            .linesBetween(windowStart, Math.min(this.clock.now(), startedAt + expectation.timeoutMs))
+                            .filter((line) => matchesLogcatEvent(line, expectation));
+                        if (eventMatches.length > 1) {
+                            return {
+                                status: "failed",
+                                type: expectation.type,
+                                code: "EXPECT_LOGCAT_AMBIGUOUS",
+                                message: "Logcat event appeared more than once in the declared window",
+                                durationMs: this.clock.now() - startedAt,
+                                logcatEvent: eventEvidence(eventMatches)
+                            };
+                        }
                         break;
                     }
                 }
@@ -159,7 +274,8 @@ export class ExpectationEvaluator {
                     const codes = {
                         activity: "EXPECT_ACTIVITY_FAILED",
                         element: "EXPECT_ELEMENT_FAILED",
-                        logcat: "EXPECT_LOGCAT_FAILED"
+                        logcat: "EXPECT_LOGCAT_FAILED",
+                        logcatEvent: "EXPECT_LOGCAT_FAILED"
                     };
                     return {
                         status: "failed",
@@ -177,14 +293,36 @@ export class ExpectationEvaluator {
                 const codes = {
                     activity: "EXPECT_ACTIVITY_FAILED",
                     element: "EXPECT_ELEMENT_FAILED",
-                    logcat: "EXPECT_LOGCAT_FAILED"
+                    logcat: "EXPECT_LOGCAT_FAILED",
+                    logcatEvent: "EXPECT_LOGCAT_FAILED"
                 };
+                if (expectation.type === "logcatEvent" && eventMatches.length === 1) {
+                    const result = {
+                        status: "passed",
+                        type: expectation.type,
+                        durationMs: elapsed,
+                        logcatEvent: eventEvidence(eventMatches)
+                    };
+                    if (eventMatches[0] !== undefined) {
+                        this.matchedEvents.set(result, eventMatches[0]);
+                    }
+                    return result;
+                }
                 return {
                     status: "failed",
                     type: expectation.type,
                     code: codes[expectation.type],
-                    message: `${expectation.type} Expect did not match before timeout`,
+                    message: expectation.type === "logcatEvent"
+                        ? "Logcat event did not appear before timeout"
+                        : expectation.type === "element"
+                            ? elementObservation === undefined
+                                ? "element Expect did not match before timeout"
+                                : `element Expect did not match before timeout: ${elementObservation}`
+                            : `${expectation.type} Expect did not match before timeout`,
                     durationMs: elapsed,
+                    ...(expectation.type === "logcatEvent"
+                        ? { logcatEvent: eventEvidence(eventMatches) }
+                        : {}),
                     ...(actual === undefined ? {} : { actual })
                 };
             }

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

@@ -0,0 +1,45 @@
+import type { Expectation } from "../../domain/journey.js";
+import type { LayoutElement } from "../../domain/layout.js";
+import type { ExpectationObservationBoundary, ExpectationObservationInput } from "./expectation-evaluator.js";
+/**
+ * Engine-specific observation of the App under a bound identity. Each call
+ * re-checks the foreground package and process identity and throws when they
+ * no longer match; `layout` also re-checks them after the capture.
+ */
+export interface GuardedExpectationProbe<TObservation extends {
+    layout: readonly LayoutElement[];
+}> {
+    activity: (input: ExpectationObservationInput) => Promise<string>;
+    layout: (input: ExpectationObservationInput) => Promise<TObservation>;
+    /** Errors that must propagate instead of failing the observation. */
+    rethrow?: (error: unknown) => boolean;
+}
+/**
+ * Expectation observations shared by generated Replay and Generation. A guard
+ * violation becomes a failed observation, which the evaluator reports as
+ * `EXPECT_ACTIVITY_FAILED` or `EXPECT_ELEMENT_FAILED`. The first Layout
+ * observation reuses the settled post-action Layout, which the engine has
+ * already guarded, instead of capturing the same screen again.
+ */
+export declare class GuardedExpectationObservations<TObservation extends {
+    layout: readonly LayoutElement[];
+}> {
+    private readonly probe;
+    private seed;
+    private last;
+    constructor(probe: GuardedExpectationProbe<TObservation>, settled?: TObservation);
+    boundary(): ExpectationObservationBoundary;
+    /** The Layout observation the element expectation last resolved against. */
+    lastLayoutObservation(): TObservation | undefined;
+    private failed;
+}
+/**
+ * The foreground a passing expectation leaves behind. An `element`
+ * expectation is proven on the guarded Layout it resolved against and an
+ * `activity` expectation on the guarded Activity it matched; log expectations
+ * prove nothing about the screen, so the foreground must be re-checked.
+ */
+export declare function settledExpectationForeground(expectation: Expectation, afterActivity: string): {
+    activity: string;
+    proven: boolean;
+};

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

@@ -0,0 +1,74 @@
+/**
+ * Expectation observations shared by generated Replay and Generation. A guard
+ * violation becomes a failed observation, which the evaluator reports as
+ * `EXPECT_ACTIVITY_FAILED` or `EXPECT_ELEMENT_FAILED`. The first Layout
+ * observation reuses the settled post-action Layout, which the engine has
+ * already guarded, instead of capturing the same screen again.
+ */
+export class GuardedExpectationObservations {
+    probe;
+    seed;
+    last;
+    constructor(probe, settled) {
+        this.probe = probe;
+        this.seed = settled;
+    }
+    boundary() {
+        return {
+            activity: async (input) => {
+                try {
+                    return {
+                        status: "observed",
+                        activity: await this.probe.activity(input)
+                    };
+                }
+                catch (error) {
+                    return this.failed(error, "Expect Activity observation failed");
+                }
+            },
+            layout: async (input) => {
+                if (this.seed !== undefined) {
+                    this.last = this.seed;
+                    this.seed = undefined;
+                    return { status: "observed", layout: this.last.layout };
+                }
+                try {
+                    this.last = await this.probe.layout(input);
+                    return { status: "observed", layout: this.last.layout };
+                }
+                catch (error) {
+                    return this.failed(error, "Expect Layout observation failed");
+                }
+            }
+        };
+    }
+    /** The Layout observation the element expectation last resolved against. */
+    lastLayoutObservation() {
+        return this.last;
+    }
+    failed(error, fallback) {
+        if (this.probe.rethrow?.(error) === true)
+            throw error;
+        return {
+            status: "failed",
+            message: error instanceof Error ? error.message : fallback
+        };
+    }
+}
+/**
+ * The foreground a passing expectation leaves behind. An `element`
+ * expectation is proven on the guarded Layout it resolved against and an
+ * `activity` expectation on the guarded Activity it matched; log expectations
+ * prove nothing about the screen, so the foreground must be re-checked.
+ */
+export function settledExpectationForeground(expectation, afterActivity) {
+    switch (expectation.type) {
+        case "activity":
+            return { activity: expectation.value, proven: true };
+        case "element":
+            return { activity: afterActivity, proven: true };
+        case "logcat":
+        case "logcatEvent":
+            return { activity: afterActivity, proven: false };
+    }
+}

package/dist/application/checkpoint/baseline-capturer.d.ts

@@ -0,0 +1,26 @@
+import { type Baseline } from "../../domain/checkpoint.js";
+import type { VerifyResult } from "../runtime/verify-runtime.js";
+export interface BaselineCaptureInput {
+    id: string;
+    journeySha256: string;
+    contractSha256?: string | undefined;
+    includeScreenFacts?: boolean | undefined;
+    capturedAt: string;
+    runId: string;
+    packageName: string;
+    result: Pick<VerifyResult, "report" | "hookOutcomes" | "status" | "reportPath">;
+}
+export interface BaselineCapturerDependencies {
+    now: () => Date;
+    createBaselineId?: (() => string) | undefined;
+}
+/**
+ * Captures a Baseline from a completed (passing) verification run. The
+ * capture is read-only with respect to the device: it derives deterministic
+ * facts from the published report and hook outcomes.
+ */
+export declare class BaselineCapturer {
+    private readonly dependencies;
+    constructor(dependencies: BaselineCapturerDependencies);
+    readonly capture: (input: BaselineCaptureInput) => Baseline;
+}