taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/domain/knowledge.js

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { LocatorSchema } from "./layout.js";
+import { ProjectRelativePathSchema } from "./project-context.js";
+export const KnowledgeIdSchema = z.string().regex(/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/, "Knowledge identifiers must be stable file-safe names");
+export const KnowledgeStatusSchema = z.enum([
+    "inferred",
+    "observed",
+    "verified"
+]);
+export const KnowledgeSha256Schema = z.string().regex(/^[a-f\d]{64}$/);
+export const QualifiedNameSchema = z.string().regex(/^(?:[A-Za-z_$][\w$]*\.)+[A-Za-z_$][\w$]*$/, "Value must be fully qualified");
+export const AnchorRoleSchema = z.enum([
+    "screenIdentity",
+    "actionable",
+    "transitionVerification"
+]);
+const WindowIdentitySchema = z.strictObject({
+    kind: z.literal("window"),
+    title: z.string().trim().min(1).optional(),
+    packageName: QualifiedNameSchema.optional(),
+    type: z.string().trim().min(1).optional()
+}).refine((identity) => (identity.title !== undefined
+    || identity.packageName !== undefined
+    || identity.type !== undefined), "A window Anchor needs at least one stable identity field");
+export const AnchorIdentitySchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("activity"),
+        activity: QualifiedNameSchema
+    }),
+    WindowIdentitySchema,
+    z.strictObject({
+        kind: z.literal("element"),
+        locator: LocatorSchema
+    })
+]);
+export const KnowledgeSourceFilesSchema = z.array(ProjectRelativePathSchema).superRefine((paths, context) => {
+    if (new Set(paths).size !== paths.length) {
+        context.addIssue({
+            code: "custom",
+            message: "Knowledge source files must be unique"
+        });
+    }
+});
+export const AnchorCandidateKindSchema = z.enum([
+    "composeSemantics",
+    "resourceId",
+    "contentDescription",
+    "visibleText",
+    "visualMatch"
+]);
+export const AnchorCandidateSchema = z.strictObject({
+    kind: AnchorCandidateKindSchema,
+    locator: LocatorSchema
+}).superRefine((candidate, context) => {
+    if (candidate.kind === "visualMatch") {
+        context.addIssue({
+            code: "custom",
+            path: ["locator"],
+            message: "visualMatch candidates are resolved by an external multimodal layer, never by Core"
+        });
+    }
+});
+export const AnchorDefinitionSchema = z.strictObject({
+    version: z.literal(1),
+    id: KnowledgeIdSchema,
+    status: KnowledgeStatusSchema,
+    roles: z.array(AnchorRoleSchema).min(1).superRefine((roles, context) => {
+        if (new Set(roles).size !== roles.length) {
+            context.addIssue({
+                code: "custom",
+                message: "Anchor roles must be unique"
+            });
+        }
+    }),
+    identity: AnchorIdentitySchema,
+    candidates: z.array(AnchorCandidateSchema).optional().superRefine((candidates, context) => {
+        if (candidates === undefined) {
+            return;
+        }
+        const kinds = candidates.map((candidate) => candidate.kind);
+        if (new Set(kinds).size !== kinds.length) {
+            context.addIssue({
+                code: "custom",
+                message: "Anchor candidate kinds must be unique"
+            });
+        }
+    }),
+    description: z.string().trim().min(1).optional(),
+    sourceFiles: KnowledgeSourceFilesSchema.optional()
+});
+export const StatePredicateSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("activityIs"),
+        activity: QualifiedNameSchema
+    }),
+    z.strictObject({
+        kind: z.literal("anchorPresent"),
+        anchorId: KnowledgeIdSchema
+    }),
+    z.strictObject({
+        kind: z.literal("anchorAbsent"),
+        anchorId: KnowledgeIdSchema
+    }),
+    z.strictObject({
+        kind: z.literal("windowPresent"),
+        anchorId: KnowledgeIdSchema
+    })
+]);
+export const ScreenDefinitionSchema = z.strictObject({
+    version: z.literal(1),
+    id: KnowledgeIdSchema,
+    status: KnowledgeStatusSchema,
+    requiredAnchors: z.array(KnowledgeIdSchema).min(1),
+    optionalAnchors: z.array(KnowledgeIdSchema).default([]),
+    forbiddenAnchors: z.array(KnowledgeIdSchema).default([]),
+    predicates: z.array(StatePredicateSchema).default([]),
+    description: z.string().trim().min(1).optional(),
+    sourceFiles: KnowledgeSourceFilesSchema.optional()
+}).superRefine((screen, context) => {
+    const groups = [
+        screen.requiredAnchors,
+        screen.optionalAnchors,
+        screen.forbiddenAnchors
+    ];
+    const all = groups.flat();
+    if (new Set(all).size !== all.length) {
+        context.addIssue({
+            code: "custom",
+            message: "Screen Anchor sets must be unique and disjoint"
+        });
+    }
+});
+export const KnowledgeReferenceSchema = z.strictObject({
+    id: KnowledgeIdSchema,
+    path: ProjectRelativePathSchema,
+    sha256: KnowledgeSha256Schema,
+    status: KnowledgeStatusSchema
+});
+export const KnowledgeBundleIndexSchema = z.strictObject({
+    version: z.literal(1),
+    packageName: QualifiedNameSchema,
+    revision: z.number().int().nonnegative(),
+    anchors: z.array(KnowledgeReferenceSchema),
+    screens: z.array(KnowledgeReferenceSchema).min(1)
+}).superRefine((bundle, context) => {
+    for (const [field, references] of [
+        ["anchors", bundle.anchors],
+        ["screens", bundle.screens]
+    ]) {
+        const ids = new Set();
+        const paths = new Set();
+        for (const [index, reference] of references.entries()) {
+            if (ids.has(reference.id)) {
+                context.addIssue({
+                    code: "custom",
+                    path: [field, index, "id"],
+                    message: "Knowledge reference ids must be unique"
+                });
+            }
+            if (paths.has(reference.path)) {
+                context.addIssue({
+                    code: "custom",
+                    path: [field, index, "path"],
+                    message: "Knowledge reference paths must be unique"
+                });
+            }
+            ids.add(reference.id);
+            paths.add(reference.path);
+        }
+    }
+});
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, canonicalize(item)]));
+    }
+    return value;
+}
+export function hashKnowledge(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize(value)))
+        .digest("hex");
+}

package/dist/domain/layout.d.ts

@@ -11,14 +11,43 @@ export declare const LayoutPointSchema: z.ZodObject<{
     y: z.ZodNumber;
 }, z.core.$strict>;
 export type LayoutPoint = z.infer<typeof LayoutPointSchema>;
-export declare const LocatorSchema: z.ZodObject<{
-    resourceId: z.ZodOptional<z.ZodString>;
-    text: z.ZodOptional<z.ZodString>;
-    contentDescription: z.ZodOptional<z.ZodString>;
+export declare const LocatorEvidenceSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    semanticSha256: z.ZodString;
 }, z.core.$strict>;
-export type Locator = z.infer<typeof LocatorSchema>;
+export type LocatorEvidence = z.infer<typeof LocatorEvidenceSchema>;
+export type LocatorMatch = "exact" | "contains" | "startsWith" | "regex";
+export type LocatorCombine = "priority" | "all";
+export interface LocatorMatchBy {
+    resourceId?: LocatorMatch | undefined;
+    text?: LocatorMatch | undefined;
+    contentDescription?: LocatorMatch | undefined;
+}
+export interface Locator {
+    resourceId?: string | undefined;
+    text?: string | undefined;
+    contentDescription?: string | undefined;
+    match?: LocatorMatch | undefined;
+    matchBy?: LocatorMatchBy | undefined;
+    combine?: LocatorCombine | undefined;
+    index?: number | undefined;
+    within?: Locator | undefined;
+    evidence?: LocatorEvidence | undefined;
+}
+export declare const LocatorMatchSchema: z.ZodEnum<{
+    exact: "exact";
+    contains: "contains";
+    startsWith: "startsWith";
+    regex: "regex";
+}>;
+export declare const LocatorCombineSchema: z.ZodEnum<{
+    priority: "priority";
+    all: "all";
+}>;
+export declare const LocatorSchema: z.ZodType<Locator>;
 export interface LayoutElement {
     id: string;
+    windowId?: string | undefined;
     resourceId?: string | undefined;
     text?: string | undefined;
     contentDescription?: string | undefined;

package/dist/domain/layout.js

@@ -9,15 +9,73 @@ export const LayoutPointSchema = z.strictObject({
     x: z.number().int().nonnegative(),
     y: z.number().int().nonnegative()
 });
-export const LocatorSchema = z.strictObject({
-    resourceId: z.string().trim().min(1).optional(),
-    text: z.string().min(1).optional(),
-    contentDescription: z.string().min(1).optional()
+export const LocatorEvidenceSchema = z.strictObject({
+    version: z.literal(1),
+    semanticSha256: z.string().regex(/^[a-f\d]{64}$/)
+});
+export const LocatorMatchSchema = z.enum([
+    "exact",
+    "contains",
+    "startsWith",
+    "regex"
+]);
+export const LocatorCombineSchema = z.enum(["priority", "all"]);
+const LocatorPatternSchema = z.string().trim().min(1).max(512);
+function validateRegex(pattern, context, path) {
+    try {
+        new RegExp(pattern);
+    }
+    catch {
+        context.addIssue({
+            code: "custom",
+            path,
+            message: "Locator regex must be a valid regular expression"
+        });
+    }
+}
+export const LocatorSchema = z.lazy(() => z.strictObject({
+    resourceId: LocatorPatternSchema.optional(),
+    text: LocatorPatternSchema.optional(),
+    contentDescription: LocatorPatternSchema.optional(),
+    match: LocatorMatchSchema.optional(),
+    matchBy: z.strictObject({
+        resourceId: LocatorMatchSchema.optional(),
+        text: LocatorMatchSchema.optional(),
+        contentDescription: LocatorMatchSchema.optional()
+    }).optional(),
+    combine: LocatorCombineSchema.optional(),
+    index: z.number().int().nonnegative().optional(),
+    within: LocatorSchema.optional(),
+    evidence: LocatorEvidenceSchema.optional()
 }).refine(({ contentDescription, resourceId, text }) => (resourceId !== undefined
     || text !== undefined
-    || contentDescription !== undefined), { message: "Locator must contain a supported identity field" });
+    || contentDescription !== undefined), { message: "Locator must contain a supported identity field" }).refine(({ evidence, index }) => evidence === undefined || index !== undefined, {
+    message: "Locator evidence requires index disambiguation",
+    path: ["evidence"]
+}).superRefine((locator, context) => {
+    const fields = [
+        "resourceId",
+        "text",
+        "contentDescription"
+    ];
+    for (const field of fields) {
+        const value = locator[field];
+        const fieldMatch = locator.matchBy?.[field] ?? locator.match;
+        if (locator.matchBy?.[field] !== undefined && value === undefined) {
+            context.addIssue({
+                code: "custom",
+                path: ["matchBy", field],
+                message: `Locator matchBy.${field} requires ${field}`
+            });
+        }
+        if (value !== undefined && fieldMatch === "regex") {
+            validateRegex(value, context, [field]);
+        }
+    }
+}));
 export const LayoutElementSchema = z.lazy(() => z.strictObject({
     id: z.string().min(1),
+    windowId: z.string().min(1).optional(),
     resourceId: z.string().min(1).optional(),
     text: z.string().optional(),
     contentDescription: z.string().optional(),
@@ -30,4 +88,4 @@ export const LayoutElementSchema = z.lazy(() => z.strictObject({
     center: LayoutPointSchema.optional(),
     bounds: BoundsSchema.optional(),
     children: z.array(LayoutElementSchema).default([])
-}).refine(({ bounds, center }) => bounds !== undefined || center !== undefined, { message: "Layout element requires center or bounds" }));
+}));

package/dist/domain/locator-evidence.d.ts

@@ -0,0 +1,3 @@
+import { type LayoutElement, type LocatorEvidence } from "./layout.js";
+export declare function locatorEvidenceForElement(element: LayoutElement): LocatorEvidence;
+export declare function locatorEvidenceMatches(element: LayoutElement, evidence: LocatorEvidence): boolean;

package/dist/domain/locator-evidence.js

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+import { LocatorEvidenceSchema } from "./layout.js";
+function semanticElement(element) {
+    return {
+        ...(element.resourceId === undefined
+            ? {}
+            : { resourceId: element.resourceId }),
+        ...(element.text === undefined ? {} : { text: element.text }),
+        ...(element.contentDescription === undefined
+            ? {}
+            : { contentDescription: element.contentDescription }),
+        ...(element.clickable === true ? { clickable: true } : {}),
+        ...(element.longClickable === true
+            ? { longClickable: true }
+            : {}),
+        ...(element.scrollable === true ? { scrollable: true } : {}),
+        ...(element.focusable === true ? { focusable: true } : {}),
+        enabled: element.enabled,
+        children: element.children.map(semanticElement)
+    };
+}
+function semanticSha256ForElement(element) {
+    return createHash("sha256")
+        .update(JSON.stringify(semanticElement(element)))
+        .digest("hex");
+}
+export function locatorEvidenceForElement(element) {
+    return LocatorEvidenceSchema.parse({
+        version: 1,
+        semanticSha256: semanticSha256ForElement(element)
+    });
+}
+export function locatorEvidenceMatches(element, evidence) {
+    // Future evidence versions must branch before changing hash semantics.
+    return semanticSha256ForElement(element) === evidence.semanticSha256;
+}

package/dist/domain/logcat-event.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export declare const BindingNameSchema: z.ZodString;
+export declare const BindingReferenceSchema: z.ZodString;
+export declare const EventCaptureSchema: z.ZodObject<{
+    name: z.ZodString;
+    field: z.ZodOptional<z.ZodString>;
+    group: z.ZodOptional<z.ZodLiteral<"correlation">>;
+    valueType: z.ZodEnum<{
+        string: "string";
+        integer: "integer";
+        identifier: "identifier";
+    }>;
+}, z.core.$strict>;
+export declare const LogcatEventWindowSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    from: z.ZodLiteral<"stepStart">;
+}, z.core.$strict>, z.ZodObject<{
+    from: z.ZodLiteral<"runStart">;
+}, z.core.$strict>, z.ZodObject<{
+    from: z.ZodLiteral<"marker">;
+    markerId: z.ZodString;
+}, z.core.$strict>], "from">;
+export declare const LogcatEventExpectSchema: z.ZodObject<{
+    type: z.ZodLiteral<"logcatEvent">;
+    tag: z.ZodString;
+    event: z.ZodString;
+    fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    correlation: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodString]>;
+    }, z.core.$strict>>;
+    capture: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        field: z.ZodOptional<z.ZodString>;
+        group: z.ZodOptional<z.ZodLiteral<"correlation">>;
+        valueType: z.ZodEnum<{
+            string: "string";
+            integer: "integer";
+            identifier: "identifier";
+        }>;
+    }, z.core.$strict>>;
+    unique: z.ZodDefault<z.ZodLiteral<true>>;
+    window: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        from: z.ZodLiteral<"stepStart">;
+    }, z.core.$strict>, z.ZodObject<{
+        from: z.ZodLiteral<"runStart">;
+    }, z.core.$strict>, z.ZodObject<{
+        from: z.ZodLiteral<"marker">;
+        markerId: z.ZodString;
+    }, z.core.$strict>], "from">>;
+    timeoutMs: z.ZodNumber;
+}, z.core.$strict>;
+export type LogcatEventExpect = z.infer<typeof LogcatEventExpectSchema>;
+export type LogcatEventWindow = z.infer<typeof LogcatEventWindowSchema>;
+export type EventCapture = z.infer<typeof EventCaptureSchema>;

package/dist/domain/logcat-event.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { KnowledgeIdSchema } from "./knowledge.js";
+const EventValueSchema = z.union([
+    z.string().max(512),
+    z.number(),
+    z.boolean()
+]);
+export const BindingNameSchema = z.string().regex(/^[a-z][a-zA-Z0-9_]{0,31}$/);
+export const BindingReferenceSchema = z.string().regex(/^\$\{[a-z][a-zA-Z0-9_]{0,31}\}$/);
+export const EventCaptureSchema = z.strictObject({
+    name: BindingNameSchema,
+    field: z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/).optional(),
+    group: z.literal("correlation").optional(),
+    valueType: z.enum(["string", "integer", "identifier"])
+}).superRefine((capture, context) => {
+    if ((capture.field === undefined) === (capture.group === undefined)) {
+        context.addIssue({
+            code: "custom", message: "Capture requires exactly one field or correlation group"
+        });
+    }
+});
+export const LogcatEventWindowSchema = z.discriminatedUnion("from", [
+    z.strictObject({ from: z.literal("stepStart") }),
+    z.strictObject({ from: z.literal("runStart") }),
+    z.strictObject({ from: z.literal("marker"), markerId: KnowledgeIdSchema })
+]);
+export const LogcatEventExpectSchema = z.strictObject({
+    type: z.literal("logcatEvent"),
+    tag: z.string().trim().min(1),
+    event: z.string().trim().min(1),
+    fields: z.record(z.string().trim().min(1), EventValueSchema).default({}),
+    correlation: z.strictObject({
+        key: z.string().trim().min(1),
+        value: z.union([EventValueSchema, BindingReferenceSchema])
+    }).optional(),
+    capture: EventCaptureSchema.optional(),
+    unique: z.literal(true).default(true),
+    window: LogcatEventWindowSchema.default({ from: "stepStart" }),
+    timeoutMs: z.number().int().positive()
+});

package/dist/domain/observation.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export declare const ObserveReportSchema: z.ZodObject<{
+    deviceSerial: z.ZodString;
+    packageName: z.ZodString;
+    activity: z.ZodOptional<z.ZodString>;
+    foreground: z.ZodObject<{
+        packageName: z.ZodString;
+        activity: z.ZodString;
+    }, z.core.$strict>;
+    uiBackend: z.ZodObject<{
+        id: z.ZodEnum<{
+            "system-uiautomator": "system-uiautomator";
+            "android-cli": "android-cli";
+            "appium-uiautomator2": "appium-uiautomator2";
+            "mobile-mcp": "mobile-mcp";
+        }>;
+        adapterVersion: z.ZodString;
+        engineVersion: z.ZodOptional<z.ZodString>;
+        configSha256: z.ZodString;
+    }, z.core.$strict>;
+    uiCaptureDurationMs: z.ZodNumber;
+    uiCache: z.ZodOptional<z.ZodObject<{
+        hits: z.ZodNumber;
+        misses: z.ZodNumber;
+        stale: z.ZodNumber;
+        relearns: z.ZodNumber;
+        capturesSaved: z.ZodNumber;
+        validationDurationMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    layout: z.ZodArray<z.ZodType<import("./layout.js").LayoutElement, unknown, z.core.$ZodTypeInternals<import("./layout.js").LayoutElement, unknown>>>;
+    logcat: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ObserveReport = z.infer<typeof ObserveReportSchema>;

package/dist/domain/observation.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { LayoutElementSchema } from "./layout.js";
+import { UiBackendDescriptorSchema } from "./ui-backend.js";
+import { UiCacheTelemetrySchema } from "./ui-cache.js";
+export const ObserveReportSchema = z.strictObject({
+    deviceSerial: z.string().min(1),
+    packageName: z.string().min(1),
+    activity: z.string().min(1).optional(),
+    foreground: z.strictObject({
+        packageName: z.string().min(1),
+        activity: z.string().min(1)
+    }),
+    uiBackend: UiBackendDescriptorSchema,
+    uiCaptureDurationMs: z.number().nonnegative(),
+    uiCache: UiCacheTelemetrySchema.optional(),
+    layout: z.array(LayoutElementSchema),
+    logcat: z.array(z.string()).optional()
+});