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

package/dist/application/knowledge/knowledge-loader.js

@@ -0,0 +1,36 @@
+export class KnowledgeLoadError extends Error {
+    code;
+    name = "KnowledgeLoadError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+export class KnowledgeLoader {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    load = async (input) => {
+        let bundle;
+        try {
+            bundle = await this.registry.load(input.projectRoot);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const notFound = (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT");
+            throw new KnowledgeLoadError(notFound ? "KNOWLEDGE_NOT_FOUND" : "KNOWLEDGE_INVALID", message, { cause: error });
+        }
+        if (input.packageName !== undefined
+            && bundle.index.packageName !== input.packageName) {
+            throw new KnowledgeLoadError("KNOWLEDGE_INVALID", "Knowledge package identity does not match the target project");
+        }
+        if (input.expectedKnowledgeHash !== undefined
+            && bundle.knowledgeHash !== input.expectedKnowledgeHash) {
+            throw new KnowledgeLoadError("KNOWLEDGE_STALE", "Knowledge Registry hash changed after it was bound");
+        }
+        return bundle;
+    };
+}

package/dist/application/locator/layout-failure-summary.d.ts

@@ -0,0 +1,2 @@
+import type { LayoutElement } from "../../domain/layout.js";
+export declare function summarizeLayoutElements(elements: readonly LayoutElement[]): string;

package/dist/application/locator/layout-failure-summary.js

@@ -0,0 +1,67 @@
+const MAX_NOTABLE = 8;
+const MAX_LABEL_TEXT = 24;
+/**
+ * Bounded, human-scannable description of the screen at the moment a
+ * Locator or Expectation failed, so an operator (or agent) can tell an
+ * environment blocker (lock screen, permission dialog, empty window)
+ * from a genuine regression without re-dumping the UI hierarchy.
+ */
+function truncate(value) {
+    return value.length <= MAX_LABEL_TEXT
+        ? value
+        : `${value.slice(0, MAX_LABEL_TEXT - 1)}…`;
+}
+function label(element) {
+    const id = element.resourceId;
+    const text = element.text === undefined || element.text === ""
+        ? undefined
+        : truncate(element.text);
+    const description = element.contentDescription === undefined
+        || element.contentDescription === ""
+        ? undefined
+        : truncate(element.contentDescription);
+    if (id !== undefined && text !== undefined) {
+        return `#${id} "${text}"`;
+    }
+    if (id !== undefined) {
+        return `#${id}`;
+    }
+    if (text !== undefined) {
+        return `"${text}"`;
+    }
+    if (description !== undefined) {
+        return `(${description})`;
+    }
+    return undefined;
+}
+function salience(element) {
+    return (element.clickable === true || element.scrollable === true ? 2 : 0)
+        + (element.focused === true || element.focusable === true ? 1 : 0);
+}
+export function summarizeLayoutElements(elements) {
+    if (elements.length === 0) {
+        return "Screen shows no Layout elements";
+    }
+    const notable = [];
+    const seen = new Set();
+    const ranked = elements
+        .filter((element) => label(element) !== undefined)
+        .sort((a, b) => salience(b) - salience(a));
+    for (const element of ranked) {
+        const text = label(element);
+        if (text === undefined || seen.has(text)) {
+            continue;
+        }
+        seen.add(text);
+        notable.push(text);
+        if (notable.length >= MAX_NOTABLE) {
+            break;
+        }
+    }
+    if (notable.length === 0) {
+        return `Screen shows ${String(elements.length)} element(s),`
+            + " none with resourceId, text, or contentDescription";
+    }
+    return `Screen shows ${String(elements.length)} element(s);`
+        + ` notable: ${notable.join(", ")}`;
+}

package/dist/application/locator/layout-traversal.d.ts

@@ -0,0 +1,11 @@
+import type { LayoutElement } from "../../domain/layout.js";
+export interface LayoutEntry {
+    element: LayoutElement;
+    ancestors: readonly LayoutElement[];
+}
+/**
+ * Pre-order (document order) flattening. Siblings share one ancestor array,
+ * and entries are appended to a single result instead of re-spreading every
+ * subtree at each level.
+ */
+export declare function flattenLayout(elements: readonly LayoutElement[], ancestors?: readonly LayoutElement[]): LayoutEntry[];

package/dist/application/locator/layout-traversal.js

@@ -0,0 +1,18 @@
+/**
+ * Pre-order (document order) flattening. Siblings share one ancestor array,
+ * and entries are appended to a single result instead of re-spreading every
+ * subtree at each level.
+ */
+export function flattenLayout(elements, ancestors = []) {
+    const entries = [];
+    const visit = (siblings, parents) => {
+        for (const element of siblings) {
+            entries.push({ element, ancestors: parents });
+            if (element.children.length > 0) {
+                visit(element.children, [...parents, element]);
+            }
+        }
+    };
+    visit(elements, ancestors);
+    return entries;
+}

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

@@ -1,20 +1,32 @@
 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";
+import type { DisplayViewport, Point } from "../../domain/geometry.js";
 export interface LocatedTarget {
     status: "found";
     element: LayoutElement;
     point: Point;
     matchedBy: LocatorField;
+    matchedFields?: readonly LocatorField[] | undefined;
+}
+export interface LocatedIdentity {
+    status: "found";
+    element: LayoutElement;
+    matchedBy: LocatorField;
+    matchedFields?: readonly LocatorField[] | undefined;
 }
 export interface LocatorFailure {
     status: "failed";
     code: Extract<FailureCode, "LOCATOR_NOT_FOUND" | "LOCATOR_AMBIGUOUS" | "ACTION_FAILED">;
     message: string;
+    evidenceMismatch?: true | undefined;
 }
 export type LocatorResolution = LocatedTarget | LocatorFailure;
+export type LocatorIdentityResolution = LocatedIdentity | LocatorFailure;
 export interface LocatorResolutionOptions {
     requireEnabled?: boolean | undefined;
+    requiredCapability?: "clickable" | "longClickable" | undefined;
+    viewport?: DisplayViewport | undefined;
 }
+export declare function resolveLocatorIdentity(roots: readonly LayoutElement[], locator: Locator): LocatorIdentityResolution;
 export declare function resolveLocator(roots: readonly LayoutElement[], locator: Locator, options?: LocatorResolutionOptions): LocatorResolution;

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

@@ -1,9 +1,16 @@
 import { LOCATOR_FIELDS } from "../../domain/locator.js";
-function flatten(elements) {
-    return elements.flatMap((element) => [
-        element,
-        ...flatten(element.children)
-    ]);
+import { locatorEvidenceMatches } from "../../domain/locator-evidence.js";
+import { flattenLayout } from "./layout-traversal.js";
+import { summarizeLayoutElements } from "./layout-failure-summary.js";
+function pointWithin(point, bounds) {
+    return point !== undefined
+        && bounds !== undefined
+        && point.x >= bounds.left
+        && point.x < bounds.right
+        && point.y >= bounds.top
+        && point.y < bounds.bottom
+        ? point
+        : undefined;
 }
 function center(element) {
     if (element.center !== undefined) {
@@ -11,24 +18,79 @@ function center(element) {
     }
     const bounds = element.bounds;
     if (bounds === undefined) {
-        throw new Error(`Layout element ${element.id} has no center or bounds`);
+        return undefined;
     }
     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);
+const compiledPatterns = new Map();
+const MAX_COMPILED_PATTERNS = 256;
+/** Locator regexes are non-global, so a cached instance is stateless. */
+function compiledPattern(pattern) {
+    let compiled = compiledPatterns.get(pattern);
+    if (compiled === undefined) {
+        if (compiledPatterns.size >= MAX_COMPILED_PATTERNS) {
+            compiledPatterns.clear();
+        }
+        compiled = new RegExp(pattern);
+        compiledPatterns.set(pattern, compiled);
+    }
+    return compiled;
+}
+function fieldValueMatches(elementValue, locatorValue, match) {
+    if (elementValue === undefined) {
+        return false;
+    }
+    if (match === "contains") {
+        return elementValue.includes(locatorValue);
+    }
+    if (match === "startsWith") {
+        return elementValue.startsWith(locatorValue);
+    }
+    if (match === "regex") {
+        return compiledPattern(locatorValue).test(elementValue);
+    }
+    return elementValue === locatorValue;
+}
+function matchForField(locator, field) {
+    return locator.matchBy?.[field] ?? locator.match;
+}
+function resolveEntry(allEntries, locator, entries = allEntries) {
+    if (locator.within !== undefined) {
+        const scope = resolveEntry(allEntries, locator.within);
+        if (scope.status === "failed") {
+            return {
+                ...scope,
+                message: `Locator scope failed: ${scope.message}`
+            };
+        }
+        entries = allEntries.flatMap((entry) => {
+            const scopeIndex = entry.ancestors.indexOf(scope.entry.element);
+            return scopeIndex < 0
+                ? []
+                : [{
+                        ...entry,
+                        ancestors: entry.ancestors.slice(scopeIndex)
+                    }];
+        });
+    }
     let candidates;
     let matchedBy;
-    for (const field of LOCATOR_FIELDS) {
+    let matchedFields;
+    if (locator.combine === "all") {
+        matchedFields = LOCATOR_FIELDS.filter((field) => locator[field] !== undefined);
+        candidates = entries.filter(({ element }) => matchedFields?.every((field) => fieldValueMatches(element[field], locator[field], matchForField(locator, field))) === true);
+        matchedBy = matchedFields[0];
+    }
+    for (const field of locator.combine === "all" ? [] : LOCATOR_FIELDS) {
         const value = locator[field];
         if (value === undefined) {
             continue;
         }
         if (candidates === undefined) {
-            const matches = elements.filter((element) => element[field] === value);
+            const matches = entries.filter(({ element }) => fieldValueMatches(element[field], value, matchForField(locator, field)));
             if (matches.length === 0) {
                 continue;
             }
@@ -36,7 +98,7 @@ export function resolveLocator(roots, locator, options = {}) {
             matchedBy = field;
         }
         else if (candidates.length > 1) {
-            const narrowed = candidates.filter((element) => element[field] === value);
+            const narrowed = candidates.filter(({ element }) => fieldValueMatches(element[field], value, matchForField(locator, field)));
             if (narrowed.length === 0) {
                 return {
                     status: "failed",
@@ -55,24 +117,98 @@ export function resolveLocator(roots, locator, options = {}) {
         return {
             status: "failed",
             code: "LOCATOR_NOT_FOUND",
-            message: "No Layout element matches the Locator"
+            message: "No Layout element matches the Locator."
+                + ` ${summarizeLayoutElements(allEntries.map((entry) => entry.element))}`
         };
     }
-    if (candidates.length > 1) {
+    if (locator.index !== undefined) {
+        const indexed = candidates[locator.index];
+        if (indexed === undefined) {
+            return {
+                status: "failed",
+                code: "LOCATOR_NOT_FOUND",
+                message: `Locator index ${String(locator.index)} is out of range for ${String(candidates.length)} matches`
+            };
+        }
+        candidates = [indexed];
+    }
+    else 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) {
+    const entry = candidates[0];
+    if (entry === undefined || matchedBy === undefined) {
+        return {
+            status: "failed",
+            code: "LOCATOR_NOT_FOUND",
+            message: "No Layout element matches the Locator."
+                + ` ${summarizeLayoutElements(allEntries.map((entry) => entry.element))}`
+        };
+    }
+    return {
+        status: "found",
+        entry,
+        matchedBy,
+        ...(matchedFields === undefined ? {} : { matchedFields })
+    };
+}
+export function resolveLocatorIdentity(roots, locator) {
+    const resolution = resolveEntry(flattenLayout(roots), locator);
+    if (resolution.status === "failed") {
+        return resolution;
+    }
+    const { element } = resolution.entry;
+    if (locator.evidence !== undefined
+        && !locatorEvidenceMatches(element, locator.evidence)) {
+        return {
+            status: "failed",
+            code: "LOCATOR_NOT_FOUND",
+            message: "Indexed Locator element evidence does not match the live Layout",
+            evidenceMismatch: true
+        };
+    }
+    return {
+        status: "found",
+        element,
+        matchedBy: resolution.matchedBy,
+        ...(resolution.matchedFields === undefined
+            ? {}
+            : { matchedFields: resolution.matchedFields })
+    };
+}
+export function resolveLocator(roots, locator, options = {}) {
+    const resolution = resolveEntry(flattenLayout(roots), locator);
+    if (resolution.status === "failed") {
+        return resolution;
+    }
+    const { entry, matchedBy } = resolution;
+    let element = entry.element;
+    if (locator.evidence !== undefined
+        && !locatorEvidenceMatches(element, locator.evidence)) {
         return {
             status: "failed",
             code: "LOCATOR_NOT_FOUND",
-            message: "No Layout element matches the Locator"
+            message: "Indexed Locator element evidence does not match the live Layout",
+            evidenceMismatch: true
         };
     }
+    if (options.requiredCapability !== undefined
+        && element[options.requiredCapability] !== true) {
+        // The nearest capable ancestor receives the touch; a disabled one
+        // swallows it, so it is reported instead of skipped.
+        const ancestor = [...entry.ancestors].reverse().find((candidate) => candidate[options.requiredCapability] === true);
+        if (ancestor === undefined) {
+            return {
+                status: "failed",
+                code: "ACTION_FAILED",
+                message: `Layout target lacks required ${options.requiredCapability} capability`
+            };
+        }
+        element = ancestor;
+    }
     if (options.requireEnabled !== false && !element.enabled) {
         return {
             status: "failed",
@@ -80,10 +216,38 @@ export function resolveLocator(roots, locator, options = {}) {
             message: `Layout element ${element.id} is disabled`
         };
     }
+    // Touch the matched element itself: it dispatches to the capable ancestor,
+    // whose own center may be covered by an unrelated child control.
+    const point = element === entry.element
+        ? center(element)
+        : pointWithin(center(entry.element), element.bounds) ?? center(element);
+    if (point === undefined) {
+        return {
+            status: "failed",
+            code: "ACTION_FAILED",
+            message: `Layout element ${element.id} has no executable geometry`
+        };
+    }
+    const viewport = options.viewport;
+    if (viewport !== undefined
+        && (point.x >= viewport.width
+            || point.y >= viewport.height
+            || (element.bounds !== undefined
+                && (element.bounds.right > viewport.width
+                    || element.bounds.bottom > viewport.height)))) {
+        return {
+            status: "failed",
+            code: "ACTION_FAILED",
+            message: `Layout element ${element.id} geometry is outside the physical display viewport`
+        };
+    }
     return {
         status: "found",
         element,
-        point: center(element),
-        matchedBy
+        point,
+        matchedBy,
+        ...(resolution.matchedFields === undefined
+            ? {}
+            : { matchedFields: resolution.matchedFields })
     };
 }

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

@@ -0,0 +1,20 @@
+import { type ObserveReport } from "../../domain/observation.js";
+import type { RuntimeSessionOpener } from "../../ports/runtime-backend.js";
+import type { UiBackendSelection } from "../../domain/ui-backend.js";
+export interface ObserveInput {
+    packageName: string;
+    deviceSerial: string;
+    logcatLines?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface ObserveDependencies {
+    sessions: RuntimeSessionOpener;
+    layoutTimeoutMs: number;
+    backend?: UiBackendSelection | undefined;
+    cacheEnabled?: boolean | undefined;
+}
+export declare class ObserveService {
+    private readonly dependencies;
+    constructor(dependencies: ObserveDependencies);
+    observe(input: ObserveInput): Promise<ObserveReport>;
+}

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

@@ -0,0 +1,91 @@
+import { ObserveReportSchema } from "../../domain/observation.js";
+import { runtimeCapabilityMissing } from "../../ports/runtime-capability.js";
+import { closeUiSnapshotProvider } from "../ui/ui-snapshot-lifecycle.js";
+function failedCommand(result) {
+    return result.exitCode !== 0
+        || result.spawnError !== undefined
+        || result.timedOut
+        || result.cancelled;
+}
+function splitLogcat(stdout) {
+    const lines = stdout.split("\n");
+    while (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines;
+}
+export class ObserveService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async observe(input) {
+        const { packageName, deviceSerial, logcatLines, signal } = input;
+        const session = await this.dependencies.sessions.openSession({
+            deviceSerial,
+            ...(signal === undefined ? {} : { signal })
+        });
+        const app = {
+            packageName,
+            ...(signal === undefined ? {} : { signal })
+        };
+        if (session.foregroundComponent === undefined) {
+            throw runtimeCapabilityMissing(session.descriptor.id, "foregroundComponent");
+        }
+        const foreground = await session.foregroundComponent(app);
+        const activity = foreground.packageName === packageName
+            ? foreground.activity
+            : undefined;
+        const uiSnapshotProvider = await session.openUiSnapshots({
+            timeoutMs: this.dependencies.layoutTimeoutMs,
+            ...(this.dependencies.backend === undefined
+                ? {}
+                : { backend: this.dependencies.backend }),
+            ...(this.dependencies.cacheEnabled === undefined
+                ? {}
+                : { cacheEnabled: this.dependencies.cacheEnabled }),
+            ...(signal === undefined ? {} : { signal })
+        });
+        let uiCache;
+        const uiSnapshot = await (async () => {
+            try {
+                return await uiSnapshotProvider.capture({
+                    reason: "observe",
+                    timeoutMs: this.dependencies.layoutTimeoutMs,
+                    ...(signal === undefined ? {} : { signal })
+                });
+            }
+            finally {
+                uiCache = uiSnapshotProvider.cacheTelemetry?.();
+                await closeUiSnapshotProvider(uiSnapshotProvider);
+            }
+        })();
+        let logcat;
+        if (logcatLines !== undefined && logcatLines > 0) {
+            if (session.dumpLogcat === undefined) {
+                throw runtimeCapabilityMissing(session.descriptor.id, "dumpLogcat");
+            }
+            const result = await session.dumpLogcat({
+                maxLines: logcatLines,
+                ...(signal === undefined ? {} : { signal })
+            });
+            if (failedCommand(result)) {
+                throw new Error(result.stderr.trim()
+                    || result.spawnError
+                    || "Logcat dump failed");
+            }
+            logcat = splitLogcat(result.stdout);
+        }
+        return ObserveReportSchema.parse({
+            deviceSerial,
+            packageName,
+            ...(activity === undefined ? {} : { activity }),
+            foreground,
+            uiBackend: uiSnapshot.backend,
+            uiCaptureDurationMs: uiSnapshot.durationMs,
+            ...(uiCache === undefined ? {} : { uiCache }),
+            layout: uiSnapshot.roots,
+            ...(logcat === undefined ? {} : { logcat })
+        });
+    }
+}

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

@@ -1,14 +1,22 @@
 import type { TapHoundConfig } from "../../domain/config.js";
+import type { ProjectIdentityInspector } from "../../ports/project-identity-inspector.js";
+import type { ProjectModuleDiscoverer } from "../../ports/project-module-discoverer.js";
 export interface ProjectDescribeInput {
-    projectRoot: string;
-    config: TapHoundConfig;
-    signal?: AbortSignal | undefined;
+    readonly projectRoot: string;
+    readonly config: TapHoundConfig;
+    readonly signal?: AbortSignal | undefined;
 }
 export interface ProjectDescription {
-    projectRoot: string;
-    packageName: string;
-    launchActivity: string;
+    readonly projectRoot: string;
+    readonly packageName: string;
+    readonly launchActivity: string;
+}
+export interface ProjectDescriberDependencies {
+    readonly discoverer?: ProjectModuleDiscoverer | undefined;
+    readonly identity?: ProjectIdentityInspector | undefined;
 }
 export declare class ProjectDescriber {
+    private readonly dependencies;
+    constructor(dependencies?: ProjectDescriberDependencies);
     readonly describe: (input: ProjectDescribeInput) => Promise<ProjectDescription>;
 }

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

@@ -1,8 +1,41 @@
 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)
-    });
+    dependencies;
+    constructor(dependencies = {}) {
+        this.dependencies = dependencies;
+    }
+    describe = async (input) => {
+        const { discoverer, identity } = this.dependencies;
+        if (discoverer !== undefined && identity !== undefined) {
+            try {
+                const discovery = await discoverer.discoverModules({
+                    projectRoot: input.projectRoot
+                });
+                if (discovery.status === "discovered") {
+                    const appModule = discovery.modules.find((module) => module.kind === "application");
+                    if (appModule !== undefined) {
+                        const inspected = await identity.inspectIdentity({
+                            projectRoot: input.projectRoot,
+                            moduleDir: appModule.projectDir
+                        });
+                        if (inspected.status === "inspected") {
+                            return {
+                                projectRoot: input.projectRoot,
+                                packageName: inspected.packageName,
+                                launchActivity: inspected.launchActivity
+                            };
+                        }
+                    }
+                }
+            }
+            catch {
+                // fall back to config values
+            }
+        }
+        return {
+            projectRoot: input.projectRoot,
+            packageName: input.config.run.packageName,
+            launchActivity: normalizeActivity(input.config.run.packageName, input.config.run.activity)
+        };
+    };
 }

package/dist/application/recognition/screen-detector.d.ts

@@ -0,0 +1,28 @@
+import type { AnchorDefinition, ScreenDefinition } from "../../domain/knowledge.js";
+import type { RuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+/** The runtime facts Screen detection reads; any live observation provides them. */
+export type ScreenObservation = Pick<RuntimeSnapshot, "activity" | "layout" | "windowHierarchy">;
+export type AnchorMatchResult = {
+    anchorId: string;
+    result: "matched" | "missing" | "ambiguous" | "unknown";
+    detail?: string | undefined;
+};
+export type ScreenDetectionResult = {
+    status: "matched";
+    screenId: string;
+    evidence: AnchorMatchResult[];
+} | {
+    status: "ambiguous";
+    screenIds: string[];
+    evidence: AnchorMatchResult[];
+} | {
+    status: "unknown";
+    evidence: AnchorMatchResult[];
+};
+export declare class ScreenDetector {
+    readonly detect: (input: {
+        snapshot: ScreenObservation;
+        anchors: readonly AnchorDefinition[];
+        screens: readonly ScreenDefinition[];
+    }) => ScreenDetectionResult;
+}