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

package/dist/application/interaction/scroll-to-executor.js

@@ -2,7 +2,7 @@ import { resolveLocator } from "../locator/locator-resolver.js";
 function isCancelled(signal) {
     return signal?.aborted === true;
 }
-function callbackFailure(error, swipesUsed) {
+function callbackFailure(error, swipesUsed, idleDurationMs) {
     if (error !== null
         && typeof error === "object"
         && "code" in error
@@ -16,7 +16,8 @@ function callbackFailure(error, swipesUsed) {
             status: "failed",
             code: error.code,
             message: error instanceof Error ? error.message : error.code,
-            swipesUsed
+            swipesUsed,
+            idleDurationMs
         };
     }
     return undefined;
@@ -26,41 +27,102 @@ export class ScrollToExecutor {
     constructor(options) {
         this.options = options;
     }
+    async resolveTarget(step, layout, signal) {
+        if (step.anchor !== undefined) {
+            const anchorResolver = this.options.anchorResolver;
+            if (anchorResolver !== undefined) {
+                const anchorResolution = await anchorResolver.resolve({
+                    anchorId: step.anchor,
+                    layout,
+                    ...(this.options.viewport === undefined
+                        ? {}
+                        : { viewport: this.options.viewport() }),
+                    ...(signal === undefined ? {} : { signal })
+                });
+                if (anchorResolution.status === "found") {
+                    const fallbackElement = anchorResolution.element
+                        ?? {
+                            id: step.anchor,
+                            enabled: true,
+                            bounds: anchorResolution.bounds,
+                            children: []
+                        };
+                    return {
+                        status: "found",
+                        element: fallbackElement,
+                        point: anchorResolution.point ?? { x: 0, y: 0 }
+                    };
+                }
+                if (anchorResolution.status === "ambiguous") {
+                    return {
+                        status: "failed",
+                        code: "ANCHOR_AMBIGUOUS",
+                        message: anchorResolution.message
+                            ?? `Knowledge anchor ${step.anchor} resolved ambiguously`
+                    };
+                }
+            }
+        }
+        if (step.locator === undefined) {
+            return {
+                status: "failed",
+                code: "ANCHOR_NOT_FOUND",
+                message: `Knowledge anchor ${step.anchor ?? "(none)"} was not found and no locator fallback exists`
+            };
+        }
+        const resolution = resolveLocator(layout, step.locator, { requireEnabled: false, viewport: this.options.viewport?.() });
+        if (resolution.status === "found") {
+            return {
+                status: "found",
+                element: resolution.element,
+                point: resolution.point
+            };
+        }
+        return {
+            status: "failed",
+            code: resolution.code,
+            message: resolution.message
+        };
+    }
     async execute(step, signal, initialLayout) {
         let swipesUsed = 0;
+        let idleDurationMs = 0;
         let layout = initialLayout;
         for (;;) {
             if (isCancelled(signal)) {
-                return { status: "cancelled", swipesUsed };
+                return { status: "cancelled", swipesUsed, idleDurationMs };
             }
             try {
                 layout ??= this.options.readLayout === undefined
-                    ? await this.options.androidCli.layout({
-                        deviceSerial: this.options.deviceSerial,
+                    ? (await this.options.uiSnapshotProvider.capture({
+                        reason: "locate",
+                        freshness: "sameMutationEpoch",
                         ...(signal === undefined ? {} : { signal }),
                         timeoutMs: this.options.idle.timeoutMs
-                    })
+                    })).roots
                     : await this.options.readLayout();
             }
             catch (error) {
-                const failed = callbackFailure(error, swipesUsed);
+                const failed = callbackFailure(error, swipesUsed, idleDurationMs);
                 if (failed !== undefined)
                     return failed;
                 throw error;
             }
             if (isCancelled(signal)) {
-                return { status: "cancelled", swipesUsed };
+                return { status: "cancelled", swipesUsed, idleDurationMs };
             }
-            const target = resolveLocator(layout, step.locator, { requireEnabled: false });
+            const target = await this.resolveTarget(step, layout, signal);
             if (target.status === "found") {
-                return { status: "found", swipesUsed };
+                return { status: "found", swipesUsed, idleDurationMs };
             }
-            if (target.code === "LOCATOR_AMBIGUOUS") {
+            if (target.code === "LOCATOR_AMBIGUOUS"
+                || target.code === "ANCHOR_AMBIGUOUS") {
                 return {
                     status: "failed",
-                    code: "LOCATOR_AMBIGUOUS",
+                    code: target.code,
                     message: target.message,
-                    swipesUsed
+                    swipesUsed,
+                    idleDurationMs
                 };
             }
             if (swipesUsed >= step.maxSwipes) {
@@ -68,16 +130,18 @@ export class ScrollToExecutor {
                     status: "failed",
                     code: "SCROLL_TARGET_NOT_FOUND",
                     message: `Target not visible after ${String(step.maxSwipes)} swipes`,
-                    swipesUsed
+                    swipesUsed,
+                    idleDurationMs
                 };
             }
-            let container = resolveLocator(layout, step.container, { requireEnabled: false });
+            let container = resolveLocator(layout, step.container, { requireEnabled: false, viewport: this.options.viewport?.() });
             if (container.status !== "found") {
                 return {
                     status: "failed",
                     code: container.code,
                     message: container.message,
-                    swipesUsed
+                    swipesUsed,
+                    idleDurationMs
                 };
             }
             if (container.element.bounds === undefined) {
@@ -85,7 +149,8 @@ export class ScrollToExecutor {
                     status: "failed",
                     code: "ACTION_FAILED",
                     message: "scroll container has no bounds to swipe",
-                    swipesUsed
+                    swipesUsed,
+                    idleDurationMs
                 };
             }
             if (this.options.beforeSwipe !== undefined) {
@@ -93,33 +158,36 @@ export class ScrollToExecutor {
                     layout = await this.options.beforeSwipe();
                 }
                 catch (error) {
-                    const failed = callbackFailure(error, swipesUsed);
+                    const failed = callbackFailure(error, swipesUsed, idleDurationMs);
                     if (failed !== undefined)
                         return failed;
                     throw error;
                 }
                 if (isCancelled(signal)) {
-                    return { status: "cancelled", swipesUsed };
+                    return { status: "cancelled", swipesUsed, idleDurationMs };
                 }
-                const liveTarget = resolveLocator(layout, step.locator, { requireEnabled: false });
+                const liveTarget = await this.resolveTarget(step, layout, signal);
                 if (liveTarget.status === "found") {
-                    return { status: "found", swipesUsed };
+                    return { status: "found", swipesUsed, idleDurationMs };
                 }
-                if (liveTarget.code === "LOCATOR_AMBIGUOUS") {
+                if (liveTarget.code === "LOCATOR_AMBIGUOUS"
+                    || liveTarget.code === "ANCHOR_AMBIGUOUS") {
                     return {
                         status: "failed",
-                        code: "LOCATOR_AMBIGUOUS",
+                        code: liveTarget.code,
                         message: liveTarget.message,
-                        swipesUsed
+                        swipesUsed,
+                        idleDurationMs
                     };
                 }
-                container = resolveLocator(layout, step.container, { requireEnabled: false });
+                container = resolveLocator(layout, step.container, { requireEnabled: false, viewport: this.options.viewport?.() });
                 if (container.status !== "found") {
                     return {
                         status: "failed",
                         code: container.code,
                         message: container.message,
-                        swipesUsed
+                        swipesUsed,
+                        idleDurationMs
                     };
                 }
                 if (container.element.bounds === undefined) {
@@ -127,12 +195,13 @@ export class ScrollToExecutor {
                         status: "failed",
                         code: "ACTION_FAILED",
                         message: "scroll container has no bounds to swipe",
-                        swipesUsed
+                        swipesUsed,
+                        idleDurationMs
                     };
                 }
             }
             if (isCancelled(signal)) {
-                return { status: "cancelled", swipesUsed };
+                return { status: "cancelled", swipesUsed, idleDurationMs };
             }
             if (this.options.requireLiveContainerCapability === true
                 && (!container.element.enabled
@@ -141,39 +210,42 @@ export class ScrollToExecutor {
                     status: "failed",
                     code: "ACTION_FAILED",
                     message: "scroll container lost enabled scrollable bounds",
-                    swipesUsed
+                    swipesUsed,
+                    idleDurationMs
                 };
             }
             try {
                 await this.options.beforeMutation?.();
             }
             catch (error) {
-                const failed = callbackFailure(error, swipesUsed);
+                const failed = callbackFailure(error, swipesUsed, idleDurationMs);
                 if (failed !== undefined)
                     return failed;
                 throw error;
             }
             if (isCancelled(signal)) {
-                return { status: "cancelled", swipesUsed };
+                return { status: "cancelled", swipesUsed, idleDurationMs };
             }
             const swipe = await this.options.actionExecutor.swipeBounds(container.element.bounds, step.direction, step.distancePercent, step.durationMs, signal);
             if (isCancelled(signal)) {
-                return { status: "cancelled", swipesUsed };
+                return { status: "cancelled", swipesUsed, idleDurationMs };
             }
             if (swipe.status === "failed") {
                 return {
                     status: "failed",
                     code: swipe.code,
                     message: swipe.message,
-                    swipesUsed
+                    swipesUsed,
+                    idleDurationMs
                 };
             }
             const idle = await this.options.idleWaiter.waitUntilIdle(this.options.idle, signal);
+            idleDurationMs += idle.durationMs;
             if (isCancelled(signal)) {
-                return { status: "cancelled", swipesUsed };
+                return { status: "cancelled", swipesUsed, idleDurationMs };
             }
             if (idle.status === "cancelled") {
-                return { status: "cancelled", swipesUsed };
+                return { status: "cancelled", swipesUsed, idleDurationMs };
             }
             if (idle.status === "timeout") {
                 return {
@@ -181,7 +253,17 @@ export class ScrollToExecutor {
                     code: idle.code,
                     message: "Layout did not become stable before timeout",
                     swipesUsed,
-                    idle: { polls: idle.polls, lastDiff: idle.lastDiff }
+                    idleDurationMs,
+                    idle: {
+                        polls: idle.polls,
+                        durationMs: idle.durationMs,
+                        samplingDurationMs: idle.samplingDurationMs,
+                        strategy: idle.strategy,
+                        ...(idle.backend === undefined ? {} : { backend: idle.backend }),
+                        fallbackUsed: idle.fallbackUsed,
+                        frameActivityDetected: idle.frameActivityDetected,
+                        lastDiff: idle.lastDiff
+                    }
                 };
             }
             swipesUsed += 1;

package/dist/application/journey/external-flow-resolver.d.ts

@@ -0,0 +1,25 @@
+import type { ExternalFlow } from "../../domain/external-flow.js";
+import type { ExternalFlowCatalogEntry, ExternalFlowRecord } from "../../ports/external-flow-registry.js";
+export interface ExternalFlowResolution {
+    flow: ExternalFlow;
+    flowSha256: string;
+    stepCount: number;
+}
+export interface ExternalFlowResolverDependencies {
+    registry: {
+        read: (input: {
+            projectRoot: string;
+            name: string;
+        }) => Promise<ExternalFlowRecord>;
+        list: (projectRoot: string) => Promise<readonly ExternalFlowCatalogEntry[]>;
+    };
+}
+export declare class ExternalFlowResolver {
+    private readonly dependencies;
+    constructor(dependencies: ExternalFlowResolverDependencies);
+    readonly resolve: (input: {
+        projectRoot: string;
+        name: string;
+    }) => Promise<ExternalFlowResolution>;
+    readonly list: (projectRoot: string) => Promise<readonly ExternalFlowCatalogEntry[]>;
+}

package/dist/application/journey/external-flow-resolver.js

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+export class ExternalFlowResolver {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    resolve = async (input) => {
+        const record = await this.dependencies.registry.read(input);
+        if (record.flow.includes.length > 0) {
+            throw new Error(`External Flow "${input.name}" uses includes, which are not supported in v1`);
+        }
+        return {
+            flow: record.flow,
+            flowSha256: sha256(record.bytes),
+            stepCount: record.flow.steps.length
+        };
+    };
+    list = async (projectRoot) => this.dependencies.registry.list(projectRoot);
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}

package/dist/application/journey/journey-check-service.d.ts

@@ -0,0 +1,54 @@
+import type { TapHoundConfig } from "../../domain/config.js";
+import type { JourneyLifecycleState } from "../../domain/journey-lifecycle.js";
+import type { ProjectContext } from "../../domain/project-context.js";
+import type { JourneyCompositionStore } from "../../ports/journey-composition-store.js";
+import type { ProjectDescription } from "../project/project-describer.js";
+export type JourneyCheckStatus = "fresh" | "stale" | "no-meta" | "invalid";
+export type JourneyCheckReason = "journey-unreadable" | "journey-schema" | "meta-unreadable" | "meta-schema" | "journey-path-mismatch" | "project-hash" | "config-hash" | "module-drift" | "module-missing" | "brief-drift" | "brief-missing";
+export interface JourneyCheckDriftedModule {
+    id: string;
+    reason: "sha256" | "missing";
+}
+export interface JourneyCheckEntry {
+    name: string;
+    journeyPath: string;
+    metaPath: string;
+    status: JourneyCheckStatus;
+    lifecycle: JourneyLifecycleState | undefined;
+    reasons: readonly JourneyCheckReason[];
+    driftedModules: readonly JourneyCheckDriftedModule[];
+    message: string | undefined;
+}
+export interface JourneyCheckSummary {
+    total: number;
+    fresh: number;
+    stale: number;
+    noMeta: number;
+    invalid: number;
+}
+export interface JourneyCheckResult {
+    entries: readonly JourneyCheckEntry[];
+    summary: JourneyCheckSummary;
+}
+export type JourneyCheckErrorCode = "CONFIG_INVALID";
+export declare class JourneyCheckError extends Error {
+    readonly code: JourneyCheckErrorCode;
+    readonly name = "JourneyCheckError";
+    constructor(code: JourneyCheckErrorCode, message: string, options?: ErrorOptions);
+}
+export interface JourneyCheckInput {
+    projectRoot: string;
+    config: TapHoundConfig;
+    project: ProjectDescription;
+    bundle: ProjectContext;
+}
+export interface JourneyCheckDependencies {
+    store: Pick<JourneyCompositionStore, "read" | "listJourneyPaths" | "readJourneyMeta">;
+}
+export declare class JourneyCheckService {
+    private readonly dependencies;
+    constructor(dependencies: JourneyCheckDependencies);
+    readonly check: (input: JourneyCheckInput) => Promise<JourneyCheckResult>;
+    private readonly checkJourney;
+    private briefDriftReason;
+}

package/dist/application/journey/journey-check-service.js

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import { GenerationMetaSchema } from "../../domain/generation.js";
+import { JourneySchema } from "../../domain/journey.js";
+import { JOURNEYS_DIR } from "../../domain/workspace.js";
+import { hashGenerationBinding } from "../generation/generation-starter.js";
+export class JourneyCheckError extends Error {
+    code;
+    name = "JourneyCheckError";
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+function metaPathFor(journeyPath) {
+    return `${journeyPath.slice(0, -".json".length)}.meta.json`;
+}
+function journeyName(journeyPath) {
+    const prefix = `${JOURNEYS_DIR}/`;
+    const withoutPrefix = journeyPath.startsWith(prefix)
+        ? journeyPath.slice(prefix.length)
+        : journeyPath;
+    return withoutPrefix.slice(0, -".json".length);
+}
+function summarize(entries) {
+    const summary = {
+        total: entries.length,
+        fresh: 0,
+        stale: 0,
+        noMeta: 0,
+        invalid: 0
+    };
+    for (const entry of entries) {
+        if (entry.status === "fresh") {
+            summary.fresh += 1;
+        }
+        else if (entry.status === "stale") {
+            summary.stale += 1;
+        }
+        else if (entry.status === "no-meta") {
+            summary.noMeta += 1;
+        }
+        else {
+            summary.invalid += 1;
+        }
+    }
+    return summary;
+}
+function parseJson(bytes) {
+    return JSON.parse(bytes.toString("utf8"));
+}
+export class JourneyCheckService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    check = async (input) => {
+        const paths = await this.dependencies.store.listJourneyPaths(input.projectRoot);
+        const projectHash = hashGenerationBinding(input.project);
+        const configHash = hashGenerationBinding(input.config);
+        const modulesById = new Map(input.bundle.modules.map((module) => [module.id, module]));
+        const entries = [];
+        for (const journeyPath of paths) {
+            entries.push(await this.checkJourney({
+                projectRoot: input.projectRoot,
+                journeyPath,
+                projectHash,
+                configHash,
+                modulesById
+            }));
+        }
+        return { entries, summary: summarize(entries) };
+    };
+    checkJourney = async (input) => {
+        const entry = (status, reasons, message) => ({
+            name: journeyName(input.journeyPath),
+            journeyPath: input.journeyPath,
+            metaPath: metaPathFor(input.journeyPath),
+            status,
+            lifecycle: lifecycleFor(status, reasons),
+            reasons,
+            driftedModules: [],
+            message
+        });
+        let bytes;
+        try {
+            bytes = await this.dependencies.store.read({
+                projectRoot: input.projectRoot,
+                relativePath: input.journeyPath
+            });
+        }
+        catch (error) {
+            return entry("invalid", ["journey-unreadable"], error instanceof Error ? error.message : String(error));
+        }
+        try {
+            JourneySchema.parse(parseJson(bytes));
+        }
+        catch (error) {
+            return entry("invalid", ["journey-schema"], error instanceof Error ? error.message : String(error));
+        }
+        let metaBytes;
+        try {
+            metaBytes = await this.dependencies.store.readJourneyMeta({
+                projectRoot: input.projectRoot,
+                journeyPath: input.journeyPath
+            });
+        }
+        catch (error) {
+            return entry("invalid", ["meta-unreadable"], error instanceof Error ? error.message : String(error));
+        }
+        if (metaBytes === null) {
+            return entry("no-meta", [], undefined);
+        }
+        let meta;
+        try {
+            meta = GenerationMetaSchema.parse(parseJson(metaBytes));
+        }
+        catch (error) {
+            return entry("invalid", ["meta-schema"], error instanceof Error ? error.message : String(error));
+        }
+        const reasons = [];
+        const driftedModules = [];
+        if (meta.journeyPath !== input.journeyPath) {
+            reasons.push("journey-path-mismatch");
+        }
+        if (meta.bindings.projectHash !== input.projectHash) {
+            reasons.push("project-hash");
+        }
+        if (meta.bindings.configHash !== input.configHash) {
+            reasons.push("config-hash");
+        }
+        for (const module of meta.contextSelection.modules) {
+            const reference = input.modulesById.get(module.id);
+            if (reference === undefined) {
+                driftedModules.push({ id: module.id, reason: "missing" });
+            }
+            else if (reference.sha256 !== module.sha256) {
+                driftedModules.push({ id: module.id, reason: "sha256" });
+            }
+        }
+        if (driftedModules.some((module) => module.reason === "sha256")) {
+            reasons.push("module-drift");
+        }
+        if (driftedModules.some((module) => module.reason === "missing")) {
+            reasons.push("module-missing");
+        }
+        if (meta.sourceBrief !== undefined) {
+            reasons.push(...await this.briefDriftReason(input.projectRoot, meta.sourceBrief));
+        }
+        const status = reasons.length === 0 ? "fresh" : "stale";
+        return {
+            name: journeyName(input.journeyPath),
+            journeyPath: input.journeyPath,
+            metaPath: metaPathFor(input.journeyPath),
+            status,
+            lifecycle: meta.retired !== undefined
+                ? "retired"
+                : status === "fresh"
+                    ? meta.status
+                    : classifyLifecycle(reasons),
+            reasons,
+            driftedModules,
+            message: undefined
+        };
+    };
+    async briefDriftReason(projectRoot, brief) {
+        let bytes;
+        try {
+            bytes = await this.dependencies.store.read({
+                projectRoot,
+                relativePath: brief.path
+            });
+        }
+        catch {
+            return ["brief-missing"];
+        }
+        return createHash("sha256").update(bytes).digest("hex") === brief.sha256
+            ? []
+            : ["brief-drift"];
+    }
+}
+const STALE_REASONS = new Set([
+    "journey-path-mismatch",
+    "project-hash",
+    "module-drift",
+    "module-missing",
+    "brief-drift",
+    "brief-missing"
+]);
+function lifecycleFor(status, reasons) {
+    if (status === "invalid") {
+        return undefined;
+    }
+    if (status === "no-meta") {
+        return "draft";
+    }
+    if (reasons.length === 0) {
+        return "verified";
+    }
+    return reasons.some((reason) => STALE_REASONS.has(reason))
+        ? "stale"
+        : "suspect";
+}
+function classifyLifecycle(reasons) {
+    return reasons.some((reason) => STALE_REASONS.has(reason))
+        ? "stale"
+        : "suspect";
+}

package/dist/application/journey/journey-promoter.d.ts

@@ -0,0 +1,26 @@
+import type { JourneyCompositionStore } from "../../ports/journey-composition-store.js";
+export type JourneyPromotionErrorCode = "JOURNEY_NOT_FOUND" | "JOURNEY_INVALID" | "META_MISSING" | "META_INVALID" | "JOURNEY_ALREADY_PROMOTED" | "EVIDENCE_MISSING" | "EVIDENCE_HASH_MISMATCH" | "JOURNEY_MODIFIED";
+export declare class JourneyPromotionError extends Error {
+    readonly code: JourneyPromotionErrorCode;
+    readonly name = "JourneyPromotionError";
+    constructor(code: JourneyPromotionErrorCode, message: string, options?: ErrorOptions);
+}
+export interface JourneyPromotionResult {
+    status: "promoted";
+    journeyPath: string;
+    metaPath: string;
+    generationId: string;
+    promotedAt: string;
+}
+export declare class JourneyPromoter {
+    private readonly dependencies;
+    constructor(dependencies: {
+        store: Pick<JourneyCompositionStore, "read" | "readJourneyMeta" | "writeText">;
+    });
+    readonly promote: (input: {
+        projectRoot: string;
+        journeyPath: string;
+        reason: string;
+        now: Date;
+    }) => Promise<JourneyPromotionResult>;
+}