taphound 0.2.0-dev.1

package/dist/domain/journey.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { LocatorSchema } from "./layout.js";
+const QualifiedActivitySchema = z.string().regex(/^(?:[A-Za-z_$][\w$]*\.)+[A-Za-z_$][\w$]*$/, "Activity checkpoint must be fully qualified");
+export const ActivityCheckpointSchema = z.strictObject({
+    before: QualifiedActivitySchema,
+    after: QualifiedActivitySchema
+});
+const ActivityExpectSchema = z.strictObject({
+    type: z.literal("activity"),
+    value: QualifiedActivitySchema,
+    timeoutMs: z.number().int().positive()
+});
+const ElementExpectSchema = z.strictObject({
+    type: z.literal("element"),
+    locator: LocatorSchema,
+    timeoutMs: z.number().int().positive()
+});
+const LogcatExpectSchema = z.strictObject({
+    type: z.literal("logcat"),
+    tag: z.string().min(1),
+    level: z.enum(["V", "D", "I", "W", "E", "F", "A"]).optional(),
+    pattern: z.string().min(1),
+    match: z.enum(["literal", "regex"]).default("literal"),
+    timeoutMs: z.number().int().positive()
+}).superRefine((expectation, context) => {
+    if (expectation.match === "regex") {
+        try {
+            new RegExp(expectation.pattern);
+        }
+        catch {
+            context.addIssue({
+                code: "custom",
+                path: ["pattern"],
+                message: "pattern must be a valid regular expression"
+            });
+        }
+    }
+});
+export const ExpectSchema = z.discriminatedUnion("type", [
+    ActivityExpectSchema,
+    ElementExpectSchema,
+    LogcatExpectSchema
+]);
+const CommonStepShape = {
+    activity: ActivityCheckpointSchema,
+    expect: ExpectSchema.optional()
+};
+export const AnnotatedLabelFallbackSchema = z.strictObject({
+    type: z.literal("annotatedLabel"),
+    label: z.string().regex(/^#\d+$/, "Fallback label must use Android CLI #number format")
+});
+const ClickStepSchema = z.strictObject({
+    action: z.literal("click"),
+    locator: LocatorSchema,
+    fallback: AnnotatedLabelFallbackSchema.optional(),
+    ...CommonStepShape
+});
+const LongClickStepSchema = z.strictObject({
+    action: z.literal("longClick"),
+    locator: LocatorSchema,
+    durationMs: z.number().int().positive().default(800),
+    fallback: AnnotatedLabelFallbackSchema.optional(),
+    ...CommonStepShape
+});
+const InputTextStepSchema = z.strictObject({
+    action: z.literal("inputText"),
+    text: z.string().min(1),
+    ...CommonStepShape
+});
+const SwipeStepSchema = z.strictObject({
+    action: z.literal("swipe"),
+    locator: LocatorSchema,
+    direction: z.enum(["up", "down", "left", "right"]),
+    distancePercent: z.number().positive().max(1).default(0.6),
+    durationMs: z.number().int().positive().default(300),
+    ...CommonStepShape
+});
+const ScrollToStepSchema = z.strictObject({
+    action: z.literal("scrollTo"),
+    locator: LocatorSchema,
+    container: LocatorSchema,
+    direction: z.enum(["up", "down", "left", "right"]),
+    maxSwipes: z.number().int().positive().max(30).default(20),
+    distancePercent: z.number().positive().max(1).default(0.6),
+    durationMs: z.number().int().positive().default(300),
+    ...CommonStepShape
+});
+const BackStepSchema = z.strictObject({
+    action: z.literal("back"),
+    ...CommonStepShape
+});
+const WaitStepSchema = z.strictObject({
+    action: z.literal("wait"),
+    ...CommonStepShape
+});
+export const JourneyStepSchema = z.discriminatedUnion("action", [
+    ClickStepSchema,
+    LongClickStepSchema,
+    InputTextStepSchema,
+    SwipeStepSchema,
+    ScrollToStepSchema,
+    BackStepSchema,
+    WaitStepSchema
+]);
+export const JourneySchema = z.strictObject({
+    version: z.literal(1),
+    name: z.string().trim().min(1),
+    steps: z.array(JourneyStepSchema).min(1)
+});

package/dist/domain/layout.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+export declare const BoundsSchema: z.ZodObject<{
+    left: z.ZodNumber;
+    top: z.ZodNumber;
+    right: z.ZodNumber;
+    bottom: z.ZodNumber;
+}, z.core.$strict>;
+export type Bounds = z.infer<typeof BoundsSchema>;
+export declare const LayoutPointSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    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>;
+}, z.core.$strict>;
+export type Locator = z.infer<typeof LocatorSchema>;
+export interface LayoutElement {
+    id: string;
+    resourceId?: string | undefined;
+    text?: string | undefined;
+    contentDescription?: string | undefined;
+    clickable?: boolean | undefined;
+    longClickable?: boolean | undefined;
+    scrollable?: boolean | undefined;
+    focusable?: boolean | undefined;
+    focused?: boolean | undefined;
+    enabled: boolean;
+    center?: LayoutPoint | undefined;
+    bounds?: Bounds | undefined;
+    children: LayoutElement[];
+}
+export declare const LayoutElementSchema: z.ZodType<LayoutElement>;

package/dist/domain/layout.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export const BoundsSchema = z.strictObject({
+    left: z.number().int().nonnegative(),
+    top: z.number().int().nonnegative(),
+    right: z.number().int().positive(),
+    bottom: z.number().int().positive()
+}).refine(({ left, right }) => right > left, { message: "right must be greater than left", path: ["right"] }).refine(({ bottom, top }) => bottom > top, { message: "bottom must be greater than top", path: ["bottom"] });
+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()
+}).refine(({ contentDescription, resourceId, text }) => (resourceId !== undefined
+    || text !== undefined
+    || contentDescription !== undefined), { message: "Locator must contain a supported identity field" });
+export const LayoutElementSchema = z.lazy(() => z.strictObject({
+    id: z.string().min(1),
+    resourceId: z.string().min(1).optional(),
+    text: z.string().optional(),
+    contentDescription: z.string().optional(),
+    clickable: z.boolean().optional(),
+    longClickable: z.boolean().optional(),
+    scrollable: z.boolean().optional(),
+    focusable: z.boolean().optional(),
+    focused: z.boolean().optional(),
+    enabled: z.boolean(),
+    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.d.ts

@@ -0,0 +1,8 @@
+import type { LayoutElement } from "./layout.js";
+export declare const LOCATOR_FIELDS: readonly ["resourceId", "text", "contentDescription"];
+export type LocatorField = (typeof LOCATOR_FIELDS)[number];
+export interface LocatedElement {
+    element: LayoutElement;
+    field: LocatorField;
+    value: string;
+}

package/dist/domain/locator.js

@@ -0,0 +1,5 @@
+export const LOCATOR_FIELDS = [
+    "resourceId",
+    "text",
+    "contentDescription"
+];

package/dist/domain/project-context.d.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+export declare const ContextEvidenceConfidenceSchema: z.ZodEnum<{
+    unknown: "unknown";
+    sourceConfirmed: "sourceConfirmed";
+    runtimeConfirmed: "runtimeConfirmed";
+    inferred: "inferred";
+}>;
+export type ContextEvidenceConfidence = z.infer<typeof ContextEvidenceConfidenceSchema>;
+export declare const ProjectRelativePathSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export declare const ContextManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        sha256: z.ZodString;
+        confidence: z.ZodEnum<{
+            unknown: "unknown";
+            sourceConfirmed: "sourceConfirmed";
+            runtimeConfirmed: "runtimeConfirmed";
+            inferred: "inferred";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const InteractionPolicySchema: z.ZodObject<{
+    allowedActions: z.ZodArray<z.ZodEnum<{
+        swipe: "swipe";
+        click: "click";
+        longClick: "longClick";
+        inputText: "inputText";
+        scrollTo: "scrollTo";
+        back: "back";
+        wait: "wait";
+    }>>;
+    confirmationRequiredActions: z.ZodArray<z.ZodEnum<{
+        swipe: "swipe";
+        click: "click";
+        longClick: "longClick";
+        inputText: "inputText";
+        scrollTo: "scrollTo";
+        back: "back";
+        wait: "wait";
+    }>>;
+    forbiddenActions: z.ZodArray<z.ZodEnum<{
+        swipe: "swipe";
+        click: "click";
+        longClick: "longClick";
+        inputText: "inputText";
+        scrollTo: "scrollTo";
+        back: "back";
+        wait: "wait";
+    }>>;
+}, z.core.$strict>;
+export declare const ProjectContextSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    packageName: z.ZodString;
+    launchActivity: z.ZodString;
+    manifest: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+            sha256: z.ZodString;
+            confidence: z.ZodEnum<{
+                unknown: "unknown";
+                sourceConfirmed: "sourceConfirmed";
+                runtimeConfirmed: "runtimeConfirmed";
+                inferred: "inferred";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    interactionPolicy: z.ZodObject<{
+        allowedActions: z.ZodArray<z.ZodEnum<{
+            swipe: "swipe";
+            click: "click";
+            longClick: "longClick";
+            inputText: "inputText";
+            scrollTo: "scrollTo";
+            back: "back";
+            wait: "wait";
+        }>>;
+        confirmationRequiredActions: z.ZodArray<z.ZodEnum<{
+            swipe: "swipe";
+            click: "click";
+            longClick: "longClick";
+            inputText: "inputText";
+            scrollTo: "scrollTo";
+            back: "back";
+            wait: "wait";
+        }>>;
+        forbiddenActions: z.ZodArray<z.ZodEnum<{
+            swipe: "swipe";
+            click: "click";
+            longClick: "longClick";
+            inputText: "inputText";
+            scrollTo: "scrollTo";
+            back: "back";
+            wait: "wait";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ContextManifest = z.infer<typeof ContextManifestSchema>;
+export type InteractionPolicy = z.infer<typeof InteractionPolicySchema>;
+export type ProjectContext = z.infer<typeof ProjectContextSchema>;

package/dist/domain/project-context.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+const QualifiedNameSchema = z.string().regex(/^(?:[A-Za-z_$][\w$]*\.)+[A-Za-z_$][\w$]*$/, "Value must be fully qualified");
+const GenerationActionSchema = z.enum([
+    "click",
+    "longClick",
+    "inputText",
+    "swipe",
+    "scrollTo",
+    "back",
+    "wait"
+]);
+export const ContextEvidenceConfidenceSchema = z.enum([
+    "sourceConfirmed",
+    "runtimeConfirmed",
+    "inferred",
+    "unknown"
+]);
+export const ProjectRelativePathSchema = z.string()
+    .trim()
+    .min(1)
+    .transform((path) => path.replaceAll("\\", "/"))
+    .refine((path) => (!path.startsWith("/")
+    && !/^[A-Za-z]:/.test(path)
+    && !path.split("/").includes("..")), "Path must stay within the project");
+const ContextFileSchema = z.strictObject({
+    path: ProjectRelativePathSchema,
+    sha256: z.string().regex(/^[a-f\d]{64}$/),
+    confidence: ContextEvidenceConfidenceSchema
+});
+export const ContextManifestSchema = z.strictObject({
+    version: z.literal(1),
+    files: z.array(ContextFileSchema).min(1)
+});
+export const InteractionPolicySchema = z.strictObject({
+    allowedActions: z.array(GenerationActionSchema),
+    confirmationRequiredActions: z.array(GenerationActionSchema),
+    forbiddenActions: z.array(GenerationActionSchema)
+}).superRefine((policy, context) => {
+    const forbidden = new Set(policy.forbiddenActions);
+    const overlap = policy.allowedActions.find((action) => forbidden.has(action));
+    if (overlap !== undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["forbiddenActions"],
+            message: `${overlap} cannot be both allowed and forbidden`
+        });
+    }
+    const allowed = new Set(policy.allowedActions);
+    const invalidConfirmation = policy.confirmationRequiredActions.find((action) => !allowed.has(action));
+    if (invalidConfirmation !== undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["confirmationRequiredActions"],
+            message: `${invalidConfirmation} must be allowed before requiring confirmation`
+        });
+    }
+});
+export const ProjectContextSchema = z.strictObject({
+    version: z.literal(1),
+    packageName: QualifiedNameSchema,
+    launchActivity: QualifiedNameSchema,
+    manifest: ContextManifestSchema,
+    interactionPolicy: InteractionPolicySchema
+});