taphound 0.2.0-dev.1

package/dist/domain/report.d.ts

@@ -0,0 +1,349 @@
+import { z } from "zod";
+export declare const ReportFailureSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        CONFIG_INVALID: "CONFIG_INVALID";
+        APP_CRASHED: "APP_CRASHED";
+        ENVIRONMENT_MISSING_TOOL: "ENVIRONMENT_MISSING_TOOL";
+        DEVICE_UNAVAILABLE: "DEVICE_UNAVAILABLE";
+        APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+        APP_LAUNCH_FAILED: "APP_LAUNCH_FAILED";
+        LOCATOR_NOT_FOUND: "LOCATOR_NOT_FOUND";
+        LOCATOR_AMBIGUOUS: "LOCATOR_AMBIGUOUS";
+        SCROLL_TARGET_NOT_FOUND: "SCROLL_TARGET_NOT_FOUND";
+        ACTION_FAILED: "ACTION_FAILED";
+        IDLE_TIMEOUT: "IDLE_TIMEOUT";
+        ACTIVITY_BEFORE_MISMATCH: "ACTIVITY_BEFORE_MISMATCH";
+        ACTIVITY_AFTER_MISMATCH: "ACTIVITY_AFTER_MISMATCH";
+        EXPECT_ACTIVITY_FAILED: "EXPECT_ACTIVITY_FAILED";
+        EXPECT_ELEMENT_FAILED: "EXPECT_ELEMENT_FAILED";
+        EXPECT_LOGCAT_FAILED: "EXPECT_LOGCAT_FAILED";
+        COLLECTION_FAILED: "COLLECTION_FAILED";
+        INTERNAL_ERROR: "INTERNAL_ERROR";
+    }>;
+    message: z.ZodString;
+    phase: z.ZodString;
+    stepIndex: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const StepReportSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    action: z.ZodEnum<{
+        swipe: "swipe";
+        click: "click";
+        longClick: "longClick";
+        inputText: "inputText";
+        scrollTo: "scrollTo";
+        back: "back";
+        wait: "wait";
+    }>;
+    status: z.ZodEnum<{
+        notRun: "notRun";
+        passed: "passed";
+        failed: "failed";
+    }>;
+    startedAtMs: z.ZodNumber;
+    finishedAtMs: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    locator: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            notRun: "notRun";
+            failed: "failed";
+            found: "found";
+        }>;
+        matchedBy: z.ZodOptional<z.ZodEnum<{
+            resourceId: "resourceId";
+            text: "text";
+            contentDescription: "contentDescription";
+        }>>;
+        fallbackUsed: z.ZodBoolean;
+        fallbackLabel: z.ZodOptional<z.ZodString>;
+        annotatedScreenshotPath: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    idle: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            notRun: "notRun";
+            stable: "stable";
+            timeout: "timeout";
+        }>;
+        polls: z.ZodNumber;
+        lastDiff: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strict>>;
+    scroll: z.ZodOptional<z.ZodObject<{
+        swipesUsed: z.ZodNumber;
+        maxSwipes: z.ZodNumber;
+    }, z.core.$strict>>;
+    activity: z.ZodOptional<z.ZodObject<{
+        before: z.ZodObject<{
+            status: z.ZodEnum<{
+                notRun: "notRun";
+                passed: "passed";
+                failed: "failed";
+            }>;
+            expected: z.ZodString;
+            actual: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        after: z.ZodObject<{
+            status: z.ZodEnum<{
+                notRun: "notRun";
+                passed: "passed";
+                failed: "failed";
+            }>;
+            expected: z.ZodString;
+            actual: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    expectation: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            activity: "activity";
+            logcat: "logcat";
+            element: "element";
+        }>;
+        status: z.ZodEnum<{
+            notRun: "notRun";
+            passed: "passed";
+            failed: "failed";
+        }>;
+        code: z.ZodOptional<z.ZodEnum<{
+            CONFIG_INVALID: "CONFIG_INVALID";
+            APP_CRASHED: "APP_CRASHED";
+            ENVIRONMENT_MISSING_TOOL: "ENVIRONMENT_MISSING_TOOL";
+            DEVICE_UNAVAILABLE: "DEVICE_UNAVAILABLE";
+            APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+            APP_LAUNCH_FAILED: "APP_LAUNCH_FAILED";
+            LOCATOR_NOT_FOUND: "LOCATOR_NOT_FOUND";
+            LOCATOR_AMBIGUOUS: "LOCATOR_AMBIGUOUS";
+            SCROLL_TARGET_NOT_FOUND: "SCROLL_TARGET_NOT_FOUND";
+            ACTION_FAILED: "ACTION_FAILED";
+            IDLE_TIMEOUT: "IDLE_TIMEOUT";
+            ACTIVITY_BEFORE_MISMATCH: "ACTIVITY_BEFORE_MISMATCH";
+            ACTIVITY_AFTER_MISMATCH: "ACTIVITY_AFTER_MISMATCH";
+            EXPECT_ACTIVITY_FAILED: "EXPECT_ACTIVITY_FAILED";
+            EXPECT_ELEMENT_FAILED: "EXPECT_ELEMENT_FAILED";
+            EXPECT_LOGCAT_FAILED: "EXPECT_LOGCAT_FAILED";
+            COLLECTION_FAILED: "COLLECTION_FAILED";
+            INTERNAL_ERROR: "INTERNAL_ERROR";
+        }>>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    logcatPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const TapHoundReportSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    runId: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        passed: "passed";
+        failed: "failed";
+    }>;
+    startedAt: z.ZodString;
+    finishedAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    project: z.ZodObject<{
+        root: z.ZodString;
+        packageName: z.ZodString;
+        launchActivity: z.ZodString;
+    }, z.core.$strict>;
+    journey: z.ZodObject<{
+        name: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>;
+    environment: z.ZodObject<{
+        deviceSerial: z.ZodString;
+        tools: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    layers: z.ZodObject<{
+        run: z.ZodEnum<{
+            notRun: "notRun";
+            passed: "passed";
+            failed: "failed";
+        }>;
+        structural: z.ZodEnum<{
+            notRun: "notRun";
+            passed: "passed";
+            failed: "failed";
+        }>;
+        activityCheckpoint: z.ZodEnum<{
+            notRun: "notRun";
+            passed: "passed";
+            failed: "failed";
+        }>;
+        explicitExpect: z.ZodEnum<{
+            notRun: "notRun";
+            passed: "passed";
+            failed: "failed";
+        }>;
+        collection: z.ZodEnum<{
+            notRun: "notRun";
+            passed: "passed";
+            failed: "failed";
+        }>;
+    }, z.core.$strict>;
+    steps: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        action: z.ZodEnum<{
+            swipe: "swipe";
+            click: "click";
+            longClick: "longClick";
+            inputText: "inputText";
+            scrollTo: "scrollTo";
+            back: "back";
+            wait: "wait";
+        }>;
+        status: z.ZodEnum<{
+            notRun: "notRun";
+            passed: "passed";
+            failed: "failed";
+        }>;
+        startedAtMs: z.ZodNumber;
+        finishedAtMs: z.ZodNumber;
+        durationMs: z.ZodNumber;
+        locator: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<{
+                notRun: "notRun";
+                failed: "failed";
+                found: "found";
+            }>;
+            matchedBy: z.ZodOptional<z.ZodEnum<{
+                resourceId: "resourceId";
+                text: "text";
+                contentDescription: "contentDescription";
+            }>>;
+            fallbackUsed: z.ZodBoolean;
+            fallbackLabel: z.ZodOptional<z.ZodString>;
+            annotatedScreenshotPath: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        idle: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<{
+                cancelled: "cancelled";
+                notRun: "notRun";
+                stable: "stable";
+                timeout: "timeout";
+            }>;
+            polls: z.ZodNumber;
+            lastDiff: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        }, z.core.$strict>>;
+        scroll: z.ZodOptional<z.ZodObject<{
+            swipesUsed: z.ZodNumber;
+            maxSwipes: z.ZodNumber;
+        }, z.core.$strict>>;
+        activity: z.ZodOptional<z.ZodObject<{
+            before: z.ZodObject<{
+                status: z.ZodEnum<{
+                    notRun: "notRun";
+                    passed: "passed";
+                    failed: "failed";
+                }>;
+                expected: z.ZodString;
+                actual: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            after: z.ZodObject<{
+                status: z.ZodEnum<{
+                    notRun: "notRun";
+                    passed: "passed";
+                    failed: "failed";
+                }>;
+                expected: z.ZodString;
+                actual: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        expectation: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<{
+                activity: "activity";
+                logcat: "logcat";
+                element: "element";
+            }>;
+            status: z.ZodEnum<{
+                notRun: "notRun";
+                passed: "passed";
+                failed: "failed";
+            }>;
+            code: z.ZodOptional<z.ZodEnum<{
+                CONFIG_INVALID: "CONFIG_INVALID";
+                APP_CRASHED: "APP_CRASHED";
+                ENVIRONMENT_MISSING_TOOL: "ENVIRONMENT_MISSING_TOOL";
+                DEVICE_UNAVAILABLE: "DEVICE_UNAVAILABLE";
+                APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+                APP_LAUNCH_FAILED: "APP_LAUNCH_FAILED";
+                LOCATOR_NOT_FOUND: "LOCATOR_NOT_FOUND";
+                LOCATOR_AMBIGUOUS: "LOCATOR_AMBIGUOUS";
+                SCROLL_TARGET_NOT_FOUND: "SCROLL_TARGET_NOT_FOUND";
+                ACTION_FAILED: "ACTION_FAILED";
+                IDLE_TIMEOUT: "IDLE_TIMEOUT";
+                ACTIVITY_BEFORE_MISMATCH: "ACTIVITY_BEFORE_MISMATCH";
+                ACTIVITY_AFTER_MISMATCH: "ACTIVITY_AFTER_MISMATCH";
+                EXPECT_ACTIVITY_FAILED: "EXPECT_ACTIVITY_FAILED";
+                EXPECT_ELEMENT_FAILED: "EXPECT_ELEMENT_FAILED";
+                EXPECT_LOGCAT_FAILED: "EXPECT_LOGCAT_FAILED";
+                COLLECTION_FAILED: "COLLECTION_FAILED";
+                INTERNAL_ERROR: "INTERNAL_ERROR";
+            }>>;
+            message: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        logcatPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    artifacts: z.ZodObject<{
+        directory: z.ZodString;
+        report: z.ZodString;
+        summary: z.ZodString;
+        screenshot: z.ZodOptional<z.ZodString>;
+        logcat: z.ZodOptional<z.ZodString>;
+        stepLogs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    primaryFailure: z.ZodOptional<z.ZodObject<{
+        code: z.ZodEnum<{
+            CONFIG_INVALID: "CONFIG_INVALID";
+            APP_CRASHED: "APP_CRASHED";
+            ENVIRONMENT_MISSING_TOOL: "ENVIRONMENT_MISSING_TOOL";
+            DEVICE_UNAVAILABLE: "DEVICE_UNAVAILABLE";
+            APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+            APP_LAUNCH_FAILED: "APP_LAUNCH_FAILED";
+            LOCATOR_NOT_FOUND: "LOCATOR_NOT_FOUND";
+            LOCATOR_AMBIGUOUS: "LOCATOR_AMBIGUOUS";
+            SCROLL_TARGET_NOT_FOUND: "SCROLL_TARGET_NOT_FOUND";
+            ACTION_FAILED: "ACTION_FAILED";
+            IDLE_TIMEOUT: "IDLE_TIMEOUT";
+            ACTIVITY_BEFORE_MISMATCH: "ACTIVITY_BEFORE_MISMATCH";
+            ACTIVITY_AFTER_MISMATCH: "ACTIVITY_AFTER_MISMATCH";
+            EXPECT_ACTIVITY_FAILED: "EXPECT_ACTIVITY_FAILED";
+            EXPECT_ELEMENT_FAILED: "EXPECT_ELEMENT_FAILED";
+            EXPECT_LOGCAT_FAILED: "EXPECT_LOGCAT_FAILED";
+            COLLECTION_FAILED: "COLLECTION_FAILED";
+            INTERNAL_ERROR: "INTERNAL_ERROR";
+        }>;
+        message: z.ZodString;
+        phase: z.ZodString;
+        stepIndex: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    secondaryErrors: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            CONFIG_INVALID: "CONFIG_INVALID";
+            APP_CRASHED: "APP_CRASHED";
+            ENVIRONMENT_MISSING_TOOL: "ENVIRONMENT_MISSING_TOOL";
+            DEVICE_UNAVAILABLE: "DEVICE_UNAVAILABLE";
+            APP_NOT_INSTALLED: "APP_NOT_INSTALLED";
+            APP_LAUNCH_FAILED: "APP_LAUNCH_FAILED";
+            LOCATOR_NOT_FOUND: "LOCATOR_NOT_FOUND";
+            LOCATOR_AMBIGUOUS: "LOCATOR_AMBIGUOUS";
+            SCROLL_TARGET_NOT_FOUND: "SCROLL_TARGET_NOT_FOUND";
+            ACTION_FAILED: "ACTION_FAILED";
+            IDLE_TIMEOUT: "IDLE_TIMEOUT";
+            ACTIVITY_BEFORE_MISMATCH: "ACTIVITY_BEFORE_MISMATCH";
+            ACTIVITY_AFTER_MISMATCH: "ACTIVITY_AFTER_MISMATCH";
+            EXPECT_ACTIVITY_FAILED: "EXPECT_ACTIVITY_FAILED";
+            EXPECT_ELEMENT_FAILED: "EXPECT_ELEMENT_FAILED";
+            EXPECT_LOGCAT_FAILED: "EXPECT_LOGCAT_FAILED";
+            COLLECTION_FAILED: "COLLECTION_FAILED";
+            INTERNAL_ERROR: "INTERNAL_ERROR";
+        }>;
+        message: z.ZodString;
+        phase: z.ZodString;
+        stepIndex: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    fallbackUsed: z.ZodBoolean;
+}, z.core.$strict>;
+export type ReportFailure = z.infer<typeof ReportFailureSchema>;
+export type StepReport = z.infer<typeof StepReportSchema>;
+export type TapHoundReport = z.infer<typeof TapHoundReportSchema>;
+export declare function hashJourney(journey: unknown): string;

package/dist/domain/report.js

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { FAILURE_CODES } from "./failure.js";
+const ResultStatusSchema = z.enum(["passed", "failed", "notRun"]);
+const RunStatusSchema = z.enum(["passed", "failed", "error"]);
+export const ReportFailureSchema = z.strictObject({
+    code: z.enum(FAILURE_CODES),
+    message: z.string().min(1),
+    phase: z.string().min(1),
+    stepIndex: z.number().int().nonnegative().optional()
+});
+const LocatorReportSchema = z.strictObject({
+    status: z.enum(["found", "failed", "notRun"]),
+    matchedBy: z.enum([
+        "resourceId",
+        "text",
+        "contentDescription"
+    ]).optional(),
+    fallbackUsed: z.boolean(),
+    fallbackLabel: z.string().regex(/^#\d+$/).optional(),
+    annotatedScreenshotPath: z.string().min(1).optional(),
+    message: z.string().min(1).optional()
+}).superRefine((locator, context) => {
+    if (locator.fallbackUsed
+        && (locator.fallbackLabel === undefined
+            || locator.annotatedScreenshotPath === undefined)) {
+        context.addIssue({
+            code: "custom",
+            message: "Fallback evidence requires label and annotated screenshot"
+        });
+    }
+});
+const IdleReportSchema = z.strictObject({
+    status: z.enum(["stable", "timeout", "cancelled", "notRun"]),
+    polls: z.number().int().nonnegative(),
+    lastDiff: z.array(z.unknown()).optional()
+});
+const ActivityCheckSchema = z.strictObject({
+    status: ResultStatusSchema,
+    expected: z.string().min(1),
+    actual: z.string().min(1).optional()
+});
+const StepExpectationSchema = z.strictObject({
+    type: z.enum(["activity", "element", "logcat"]),
+    status: ResultStatusSchema,
+    code: z.enum(FAILURE_CODES).optional(),
+    message: z.string().min(1).optional()
+});
+export const StepReportSchema = z.strictObject({
+    index: z.number().int().nonnegative(),
+    action: z.enum([
+        "click",
+        "longClick",
+        "inputText",
+        "swipe",
+        "scrollTo",
+        "back",
+        "wait"
+    ]),
+    status: ResultStatusSchema,
+    startedAtMs: z.number().nonnegative(),
+    finishedAtMs: z.number().nonnegative(),
+    durationMs: z.number().nonnegative(),
+    locator: LocatorReportSchema.optional(),
+    idle: IdleReportSchema.optional(),
+    scroll: z.strictObject({
+        swipesUsed: z.number().int().nonnegative(),
+        maxSwipes: z.number().int().positive()
+    }).optional(),
+    activity: z.strictObject({
+        before: ActivityCheckSchema,
+        after: ActivityCheckSchema
+    }).optional(),
+    expectation: StepExpectationSchema.optional(),
+    logcatPath: z.string().min(1).optional()
+});
+const LayersSchema = z.strictObject({
+    run: ResultStatusSchema,
+    structural: ResultStatusSchema,
+    activityCheckpoint: ResultStatusSchema,
+    explicitExpect: ResultStatusSchema,
+    collection: ResultStatusSchema
+});
+const ArtifactsSchema = z.strictObject({
+    directory: z.string().min(1),
+    report: z.string().min(1),
+    summary: z.string().min(1),
+    screenshot: z.string().min(1).optional(),
+    logcat: z.string().min(1).optional(),
+    stepLogs: z.array(z.string().min(1))
+});
+export const TapHoundReportSchema = z.strictObject({
+    schemaVersion: z.literal(2),
+    runId: z.string().min(1),
+    status: RunStatusSchema,
+    startedAt: z.string().min(1),
+    finishedAt: z.string().min(1),
+    durationMs: z.number().nonnegative(),
+    project: z.strictObject({
+        root: z.string().min(1),
+        packageName: z.string().min(1),
+        launchActivity: z.string().min(1)
+    }),
+    journey: z.strictObject({
+        name: z.string().min(1),
+        sha256: z.string().regex(/^[a-f\d]{64}$/)
+    }),
+    environment: z.strictObject({
+        deviceSerial: z.string().min(1),
+        tools: z.record(z.string(), z.string())
+    }),
+    layers: LayersSchema,
+    steps: z.array(StepReportSchema),
+    artifacts: ArtifactsSchema,
+    primaryFailure: ReportFailureSchema.optional(),
+    secondaryErrors: z.array(ReportFailureSchema),
+    fallbackUsed: z.boolean()
+});
+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 hashJourney(journey) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize(journey)))
+        .digest("hex");
+}

package/dist/domain/runtime-snapshot.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const RuntimeSnapshotSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    generationId: z.ZodString;
+    baseRevision: z.ZodNumber;
+    deviceSerial: z.ZodString;
+    expectedPackageName: z.ZodString;
+    foregroundPackageName: z.ZodString;
+    activity: z.ZodString;
+    pid: z.ZodNullable<z.ZodNumber>;
+    capturedAt: z.ZodISODateTime;
+    screenshotPath: z.ZodOptional<z.ZodString>;
+    layout: z.ZodArray<z.ZodType<import("./layout.js").LayoutElement, unknown, z.core.$ZodTypeInternals<import("./layout.js").LayoutElement, unknown>>>;
+}, z.core.$strict>;
+export type RuntimeSnapshot = z.infer<typeof RuntimeSnapshotSchema>;
+export declare function hashRuntimeSnapshot(snapshot: unknown): string;

package/dist/domain/runtime-snapshot.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { LayoutElementSchema } from "./layout.js";
+const QualifiedNameSchema = z.string().regex(/^(?:[A-Za-z_$][\w$]*\.)+[A-Za-z_$][\w$]*$/, "Value must be fully qualified");
+export const RuntimeSnapshotSchema = z.strictObject({
+    version: z.literal(1),
+    generationId: z.string().trim().min(1),
+    baseRevision: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    deviceSerial: z.string().trim().min(1),
+    expectedPackageName: QualifiedNameSchema,
+    foregroundPackageName: QualifiedNameSchema,
+    activity: QualifiedNameSchema,
+    pid: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
+    capturedAt: z.iso.datetime(),
+    screenshotPath: z.string().trim().min(1).optional(),
+    layout: z.array(LayoutElementSchema)
+});
+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 hashRuntimeSnapshot(snapshot) {
+    const parsed = RuntimeSnapshotSchema.parse(snapshot);
+    const content = {
+        version: parsed.version,
+        generationId: parsed.generationId,
+        baseRevision: parsed.baseRevision,
+        deviceSerial: parsed.deviceSerial,
+        expectedPackageName: parsed.expectedPackageName,
+        foregroundPackageName: parsed.foregroundPackageName,
+        activity: parsed.activity,
+        pid: parsed.pid,
+        layout: parsed.layout
+    };
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize(content)))
+        .digest("hex");
+}

package/dist/ports/adb.d.ts

@@ -0,0 +1,42 @@
+import type { Point } from "./android-cli.js";
+import type { ForegroundComponent } from "../domain/activity.js";
+import type { AppProcess } from "../domain/app-process.js";
+import type { CommandResult, RunningCommand } from "./process-runner.js";
+export interface DeviceInfo {
+    serial: string;
+    status: string;
+}
+export interface AppIdentity {
+    packageName: string;
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface LaunchActivityOptions {
+    packageName: string;
+    activity: string;
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface LogcatOptions {
+    deviceSerial: string;
+    onStdoutLine: (line: string) => void;
+    onStderrLine?: ((line: string) => void) | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface AdbPort {
+    devices: (signal?: AbortSignal) => Promise<readonly DeviceInfo[]>;
+    foregroundComponent: (identity: AppIdentity) => Promise<ForegroundComponent>;
+    currentActivity: (identity: AppIdentity) => Promise<string>;
+    isInstalled: (identity: AppIdentity) => Promise<boolean>;
+    launchActivity: (options: LaunchActivityOptions) => Promise<CommandResult>;
+    forceStop: (identity: AppIdentity) => Promise<CommandResult>;
+    appProcesses: (identity: AppIdentity) => Promise<readonly AppProcess[]>;
+    tap: (point: Point, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
+    longClick: (point: Point, durationMs: number, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
+    swipe: (from: Point, to: Point, durationMs: number, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
+    back: (deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
+    inputText: (text: string, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
+    startLogcat: (options: LogcatOptions) => RunningCommand;
+}

package/dist/ports/adb.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/android-cli.d.ts

@@ -0,0 +1,21 @@
+import type { LayoutElement } from "../domain/layout.js";
+import type { CommandResult } from "./process-runner.js";
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface DeviceCommandOptions {
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface CaptureScreenOptions extends DeviceCommandOptions {
+    outputPath: string;
+    annotate?: boolean | undefined;
+}
+export interface AndroidCliPort {
+    layout: (options: DeviceCommandOptions) => Promise<readonly LayoutElement[]>;
+    layoutDiff: (options: DeviceCommandOptions) => Promise<readonly unknown[]>;
+    captureScreen: (options: CaptureScreenOptions) => Promise<CommandResult>;
+    resolveScreen: (screenshotPath: string, label: string, signal?: AbortSignal) => Promise<Point>;
+}

package/dist/ports/android-cli.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/artifact-store.d.ts

@@ -0,0 +1,12 @@
+export interface ArtifactSession {
+    readonly temporaryDirectory: string;
+    readonly finalDirectory: string;
+    path: (relativePath: string) => string;
+    writeText: (relativePath: string, content: string) => Promise<void>;
+    writeJson: (relativePath: string, value: unknown) => Promise<void>;
+    publish: () => Promise<string>;
+    discard: () => Promise<void>;
+}
+export interface ArtifactStore {
+    begin: (baseDirectory: string, runDirectoryName: string) => Promise<ArtifactSession>;
+}

package/dist/ports/artifact-store.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/clock.d.ts

@@ -0,0 +1,4 @@
+export interface Clock {
+    now: () => number;
+    sleep: (durationMs: number, signal?: AbortSignal) => Promise<void>;
+}

package/dist/ports/clock.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/generation-meta-writer.d.ts

@@ -0,0 +1,10 @@
+import type { GenerationMeta } from "../domain/generation.js";
+import type { ProjectBoundFileReader, ProjectBoundPath } from "./project-bound-file.js";
+export interface GenerationMetaWriterPort {
+    write: (outputPath: string, meta: GenerationMeta) => Promise<void>;
+}
+export interface ProjectBoundGenerationMetaWriterPort extends GenerationMetaWriterPort, ProjectBoundFileReader {
+    writeProjectBound: (path: ProjectBoundPath & {
+        meta: GenerationMeta;
+    }) => Promise<void>;
+}

package/dist/ports/generation-meta-writer.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/generation-prompt.d.ts

@@ -0,0 +1,19 @@
+import type { PendingConfirmation } from "../domain/generation.js";
+import type { Expectation } from "../domain/journey.js";
+import type { LayoutElement } from "../domain/layout.js";
+import type { ProposalBinding, ProposedStep } from "../domain/proposed-step.js";
+export interface ManualProposalInput {
+    action: ProposedStep["action"];
+    binding: ProposalBinding;
+    before: string;
+    expect?: Expectation | undefined;
+    layout: readonly LayoutElement[];
+}
+export interface GenerationPromptPort {
+    confirm: (challenge: PendingConfirmation, signal?: AbortSignal) => Promise<boolean>;
+    buildManualProposal: (input: ManualProposalInput, signal?: AbortSignal) => Promise<ProposedStep>;
+}
+export declare class GenerationPromptCancelledError extends Error {
+    readonly name = "GenerationPromptCancelledError";
+    constructor();
+}