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

package/dist/application/wait/idle-waiter.js

@@ -1,20 +1,112 @@
+import { resolveIdlePolicy } from "./idle-profiles.js";
+const EARLY_BAIL_FRAME_CHANGES = 2;
+const POST_FALLBACK_MIN_STABLE = 2;
+/**
+ * Once frame stats showed no rendering for `stablePolls` polls, the
+ * structural phase only has to confirm the hierarchy did not change between
+ * two captures taken during this wait: one empty diff after at least two
+ * structural samples. Each capture costs a full hierarchy dump.
+ */
+const POST_FRAME_STABLE_CONFIRMATIONS = 1;
+const POST_FRAME_STABLE_MIN_SAMPLES = 2;
+function isEditableWidgetChange(change) {
+    if (typeof change !== "object" || change === null) {
+        return false;
+    }
+    const record = change;
+    const interactions = record.interactions;
+    if (Array.isArray(interactions) && interactions.includes("EDITABLE")) {
+        return true;
+    }
+    const cls = record.class;
+    return typeof cls === "string" && cls.endsWith("EditText");
+}
+function meaningfulChanges(changes, ignoreCursorBlink) {
+    if (!ignoreCursorBlink) {
+        return changes;
+    }
+    return changes.filter((change) => !isEditableWidgetChange(change));
+}
+const EMPTY_SEMANTIC_KEY = "||";
+function semanticKeys(change) {
+    if (typeof change !== "object" || change === null) {
+        return JSON.stringify(change);
+    }
+    const record = change;
+    const cls = typeof record.class === "string" ? record.class : "";
+    const resourceId = typeof record["resource-id"] === "string"
+        ? record["resource-id"]
+        : "";
+    const text = typeof record.text === "string" ? record.text : "";
+    return `${cls}|${resourceId}|${text}`;
+}
+/**
+ * A structural sample from an opaque backend is one `{layoutSha256}` change
+ * that names no element, so every such change collapses to the same empty
+ * key. Suppressing a repeated empty key set would report a screen that keeps
+ * changing as idle, so drift suppression only applies to identified changes.
+ */
+function identifiesElements(keys) {
+    return keys.every((key) => key !== EMPTY_SEMANTIC_KEY);
+}
+function sameKeySet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const sortedLeft = [...left].sort();
+    const sortedRight = [...right].sort();
+    return sortedLeft.every((key, index) => key === sortedRight[index]);
+}
 function isAborted(signal) {
     return signal?.aborted === true;
 }
+function normalizeObservation(result) {
+    return Array.isArray(result)
+        ? { changes: result }
+        : result;
+}
+function telemetry(strategy, backend, fallbackUsed, frameActivityDetected, samplingDurationMs) {
+    return {
+        strategy,
+        ...(backend === undefined ? {} : { backend }),
+        fallbackUsed,
+        frameActivityDetected,
+        samplingDurationMs
+    };
+}
 export class IdleWaiter {
-    androidCli;
+    stability;
     clock;
     deviceSerial;
-    constructor(androidCli, clock, deviceSerial) {
-        this.androidCli = androidCli;
+    packageName;
+    resolveDeviceIdentity;
+    transientKeys;
+    constructor(stability, clock, deviceSerial, packageName, resolveDeviceIdentity) {
+        this.stability = stability;
         this.clock = clock;
         this.deviceSerial = deviceSerial;
+        this.packageName = packageName;
+        this.resolveDeviceIdentity = resolveDeviceIdentity;
     }
-    async waitUntilIdle(config, signal) {
+    async waitUntilIdle(input, signal) {
+        this.stability.reset();
+        this.transientKeys = undefined;
+        const config = await this.effectiveConfig(input);
+        const strategy = config.strategy ?? "hybrid";
         const startedAt = this.clock.now();
         let polls = 0;
         let consecutiveEmpty = 0;
+        let consecutiveFrameChanges = 0;
         let lastDiff = [];
+        let lastLayout;
+        let backend;
+        let fallbackUsed = false;
+        let frameStable = false;
+        let structuralSamples = 0;
+        let frameActivityDetected = false;
+        let samplingDurationMs = 0;
+        let useStructuralBackend = strategy === "layoutDiff"
+            || strategy === "structural"
+            || (strategy === "hybrid" && this.packageName === undefined);
         for (;;) {
             if (isAborted(signal)) {
                 return {
@@ -25,13 +117,21 @@ export class IdleWaiter {
             }
             const elapsedBeforePoll = this.clock.now() - startedAt;
             polls += 1;
-            let diff;
+            let observation;
             try {
-                diff = await this.androidCli.layoutDiff({
+                observation = normalizeObservation(await this.stability.sample({
                     deviceSerial: this.deviceSerial,
+                    ...(useStructuralBackend
+                        ? { stabilityBackend: "uiautomator" }
+                        : this.packageName === undefined
+                            ? {}
+                            : {
+                                packageName: this.packageName,
+                                stabilityBackend: "frameStats"
+                            }),
                     ...(signal === undefined ? {} : { signal }),
                     timeoutMs: Math.max(1, config.timeoutMs - elapsedBeforePoll)
-                });
+                }));
             }
             catch (error) {
                 const elapsed = this.clock.now() - startedAt;
@@ -44,36 +144,110 @@ export class IdleWaiter {
                         code: "IDLE_TIMEOUT",
                         polls,
                         durationMs: elapsed,
-                        lastDiff
+                        lastDiff,
+                        ...telemetry(strategy, backend, fallbackUsed, frameActivityDetected, samplingDurationMs)
                     };
                 }
                 throw error;
             }
-            if (diff.length === 0) {
+            const diff = observation.changes;
+            samplingDurationMs += observation.durationMs ?? 0;
+            lastLayout = observation.layout ?? lastLayout;
+            backend = observation.backend ?? backend;
+            if (observation.backend === "gfxFrameStats" && diff.length > 0) {
+                frameActivityDetected = true;
+                consecutiveFrameChanges += 1;
+            }
+            else {
+                consecutiveFrameChanges = 0;
+            }
+            if (strategy === "hybrid"
+                && !useStructuralBackend
+                && consecutiveFrameChanges >= EARLY_BAIL_FRAME_CHANGES) {
+                useStructuralBackend = true;
+                fallbackUsed = true;
+                consecutiveEmpty = 0;
+            }
+            else if (useStructuralBackend) {
+                structuralSamples += 1;
+                let visibleChanges = meaningfulChanges(diff, config.ignoreCursorBlink === true);
+                if (config.ignoreLayoutDrift === true && visibleChanges.length > 0) {
+                    const keys = visibleChanges.map(semanticKeys);
+                    const identified = identifiesElements(keys);
+                    if (identified
+                        && this.transientKeys !== undefined
+                        && sameKeySet(this.transientKeys, keys)) {
+                        visibleChanges = [];
+                    }
+                    else {
+                        this.transientKeys = identified ? keys : undefined;
+                    }
+                }
+                else if (config.ignoreLayoutDrift === true) {
+                    this.transientKeys = undefined;
+                }
+                consecutiveEmpty = visibleChanges.length === 0
+                    ? consecutiveEmpty + 1
+                    : 0;
+                if (visibleChanges.length > 0)
+                    lastDiff = visibleChanges;
+            }
+            else if (diff.length === 0) {
                 consecutiveEmpty += 1;
             }
             else {
                 consecutiveEmpty = 0;
                 lastDiff = diff;
             }
-            if (consecutiveEmpty >= config.stablePolls) {
+            const isPostFallback = fallbackUsed && strategy === "hybrid";
+            const requiredStableObservations = useStructuralBackend
+                ? (frameStable
+                    ? POST_FRAME_STABLE_CONFIRMATIONS
+                    : isPostFallback
+                        ? Math.max(POST_FALLBACK_MIN_STABLE, config.stablePolls - 1)
+                        : Math.max(2, config.stablePolls))
+                : config.stablePolls;
+            if (consecutiveEmpty >= requiredStableObservations
+                && (!frameStable || structuralSamples >= POST_FRAME_STABLE_MIN_SAMPLES)) {
+                if (strategy === "hybrid" && !useStructuralBackend) {
+                    useStructuralBackend = true;
+                    frameStable = true;
+                    consecutiveEmpty = 0;
+                }
+                else {
+                    return {
+                        status: "stable",
+                        polls,
+                        durationMs: this.clock.now() - startedAt,
+                        ...(lastLayout === undefined ? {} : { layout: lastLayout }),
+                        ...telemetry(strategy, backend, fallbackUsed, frameActivityDetected, samplingDurationMs)
+                    };
+                }
+            }
+            if (this.clock.now() - startedAt >= config.timeoutMs) {
                 return {
-                    status: "stable",
+                    status: "timeout",
+                    code: "IDLE_TIMEOUT",
                     polls,
-                    durationMs: this.clock.now() - startedAt
+                    durationMs: this.clock.now() - startedAt,
+                    lastDiff,
+                    ...telemetry(strategy, backend, fallbackUsed, frameActivityDetected, samplingDurationMs)
                 };
             }
-            if (this.clock.now() - startedAt >= config.timeoutMs) {
+            const remainingMs = config.timeoutMs
+                - (this.clock.now() - startedAt);
+            if (remainingMs <= 0) {
                 return {
                     status: "timeout",
                     code: "IDLE_TIMEOUT",
                     polls,
                     durationMs: this.clock.now() - startedAt,
-                    lastDiff
+                    lastDiff,
+                    ...telemetry(strategy, backend, fallbackUsed, frameActivityDetected, samplingDurationMs)
                 };
             }
             try {
-                await this.clock.sleep(config.pollIntervalMs, signal);
+                await this.clock.sleep(Math.min(config.pollIntervalMs, remainingMs), signal);
             }
             catch (error) {
                 if (isAborted(signal)) {
@@ -87,4 +261,16 @@ export class IdleWaiter {
             }
         }
     }
+    async effectiveConfig(input) {
+        if (this.resolveDeviceIdentity === undefined
+            || input.deviceProfiles === undefined
+            || input.deviceProfiles.length === 0) {
+            return input;
+        }
+        const identity = await this.resolveDeviceIdentity();
+        if (identity === undefined) {
+            return input;
+        }
+        return resolveIdlePolicy(input, identity);
+    }
 }

package/dist/cli/commands/align.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { CliDependencies } from "../dependencies.js";
+export declare function createAlignCommand(dependencies: CliDependencies): Command;

package/dist/cli/commands/align.js

@@ -0,0 +1,124 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+import { assertArtifactDirectory, CONFIG_PATH } from "../../domain/workspace.js";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../domain/failure.js";
+import { AlignError } from "../../application/align/align-service.js";
+import { AlignPromptCancelledError } from "../../ports/align-prompt.js";
+import { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
+import { prepareWorkspace } from "../workspace-guard.js";
+function alignCameraText(result) {
+    if (result.status === "cancelled") {
+        return "Cancelled — no flow written.";
+    }
+    const { flow, probe } = result;
+    const confirmLine = probe.confirmResourceId !== undefined
+        ? `  Confirm button:    ${probe.confirmResourceId}`
+        : "  Confirm button:    (none — camera auto-accepts)";
+    const reviewActivityLine = probe.confirmActivityName === undefined
+        ? []
+        : [`  Review activity:   ${probe.confirmActivityName}`];
+    return [
+        "Probing camera...",
+        `  Camera package:    ${probe.packageName}`,
+        `  Camera activity:   ${probe.activityName}`,
+        ...reviewActivityLine,
+        `  Shutter button:    ${probe.shutterResourceId}`,
+        confirmLine,
+        "",
+        `Wrote ${flow.name} flow (${String(flow.steps)} steps)`,
+        `  Path: ${flow.path}`
+    ].join("\n");
+}
+export function createAlignCommand(dependencies) {
+    const align = new Command("align")
+        .description("Align device-specific External Flows");
+    align
+        .command("camera")
+        .description("Probe the device camera and write a project External Flow")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", CONFIG_PATH)
+        .option("--device <serial>", "Select an online Android device")
+        .option("--force", "Overwrite an existing project flow")
+        .option("--json", "Emit machine-readable JSON")
+        .action(async (options) => {
+        try {
+            try {
+                const config = await TapHoundConfigSchema.parseAsync(await dependencies.readJson(resolve(options.project, options.config)));
+                assertArtifactDirectory(options.project, config.artifactsDir);
+                await prepareWorkspace(dependencies, options.project);
+            }
+            catch (error) {
+                const output = failureOutput(2, "CONFIG_INVALID", errorMessage(error));
+                if (options.json === true) {
+                    writeJson(dependencies.stdout, output);
+                }
+                else {
+                    writeLine(dependencies.stderr, output.failure.message);
+                }
+                dependencies.setExitCode(2);
+                return;
+            }
+            const result = await dependencies.align.alignCamera({
+                projectRoot: options.project,
+                ...(options.device === undefined ? {} : { deviceSerial: options.device }),
+                ...(options.force === undefined ? {} : { force: options.force }),
+                json: options.json === true,
+                ...(dependencies.signal === undefined ? {} : { signal: dependencies.signal })
+            });
+            if (options.json === true) {
+                writeJson(dependencies.stdout, result);
+            }
+            else {
+                writeLine(dependencies.stdout, alignCameraText(result));
+            }
+            dependencies.setExitCode(result.exitCode);
+        }
+        catch (error) {
+            if (error instanceof AlignPromptCancelledError) {
+                const cancelled = { status: "cancelled", exitCode: 2 };
+                if (options.json === true) {
+                    writeJson(dependencies.stdout, cancelled);
+                }
+                else {
+                    writeLine(dependencies.stdout, alignCameraText(cancelled));
+                }
+                dependencies.setExitCode(2);
+                return;
+            }
+            if (error instanceof AlignError) {
+                const output = failureOutput(2, error.code, error.message);
+                if (options.json === true) {
+                    writeJson(dependencies.stdout, output);
+                }
+                else {
+                    writeLine(dependencies.stderr, output.failure.message);
+                }
+                dependencies.setExitCode(2);
+                return;
+            }
+            const failureCode = failureCodeFromUnknown(error);
+            if (failureCode !== undefined) {
+                const exitCode = exitCodeForFailure(failureCode);
+                const output = failureOutput(exitCode, failureCode, errorMessage(error));
+                if (options.json === true) {
+                    writeJson(dependencies.stdout, output);
+                }
+                else {
+                    writeLine(dependencies.stderr, output.failure.message);
+                }
+                dependencies.setExitCode(exitCode);
+                return;
+            }
+            const output = failureOutput(4, "INTERNAL_ERROR", errorMessage(error));
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stderr, output.failure.message);
+            }
+            dependencies.setExitCode(4);
+        }
+    });
+    return align;
+}

package/dist/cli/commands/baseline.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { CliDependencies } from "../dependencies.js";
+export declare function createBaselineCommand(dependencies: CliDependencies): Command;

package/dist/cli/commands/baseline.js

@@ -0,0 +1,130 @@
+import { Command } from "commander";
+import { exitCodeForFailure, failureCodeFromUnknown } from "../../domain/failure.js";
+import { BASELINES_DIR, BUILD_DIR, assertProjectPathUnder } from "../../domain/workspace.js";
+import { failureOutput, writeJson, writeLine } from "../output.js";
+import { prepareWorkspace } from "../workspace-guard.js";
+function writeFailure(dependencies, json, code, message) {
+    const exitCode = exitCodeForFailure(code);
+    const output = failureOutput(exitCode, code, message);
+    if (json) {
+        writeJson(dependencies.stdout, output);
+    }
+    else {
+        writeLine(dependencies.stderr, output.failure.message);
+    }
+    dependencies.setExitCode(exitCode);
+}
+export function createBaselineCommand(dependencies) {
+    const command = new Command("baseline")
+        .description("Capture and compare behavior Baselines against Verification reports")
+        .addCommand(createCaptureCommand(dependencies))
+        .addCommand(createCompareCommand(dependencies));
+    return command;
+}
+function createCaptureCommand(dependencies) {
+    return new Command("capture")
+        .description("Capture a Baseline from a passing Verification report (offline)")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .requiredOption("--report <path>", "Verification report.json path")
+        .option("--id <name>", "Baseline id (defaults to the report runId)")
+        .option("--journey-sha256 <sha256>", "Assert the source report's Journey sha256")
+        .option("--contract-sha256 <sha256>", "Assert the passing Verdict's Contract sha256")
+        .option("--verdict <path>", "Passing Contract verdict.json for the source report")
+        .option("--no-screen-facts", "Exclude Screen facts from this Baseline")
+        .requiredOption("--out <path>", "Baseline output under .taphound/baselines")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        const json = options.json === true;
+        if (dependencies.baselineService === undefined) {
+            writeFailure(dependencies, json, "CONFIG_INVALID", "TapHound baseline capture is not configured");
+            return;
+        }
+        try {
+            await prepareWorkspace(dependencies, options.project);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+            return;
+        }
+        try {
+            const reportPath = assertProjectPathUnder(options.project, options.report, BUILD_DIR, "Verification report");
+            const verdictPath = options.verdict === undefined
+                ? undefined
+                : assertProjectPathUnder(options.project, options.verdict, BUILD_DIR, "Contract verdict");
+            const outputPath = assertProjectPathUnder(options.project, options.out, BASELINES_DIR, "Baseline output");
+            const baseline = await dependencies.baselineService.captureFromReport(reportPath, {
+                id: options.id,
+                journeySha256: options.journeySha256,
+                contractSha256: options.contractSha256,
+                ...(verdictPath === undefined ? {} : { verdictPath }),
+                includeScreenFacts: options.screenFacts
+            });
+            await dependencies.baselineService.write({
+                path: outputPath,
+                baseline
+            });
+            if (json) {
+                writeJson(dependencies.stdout, baseline);
+            }
+            else {
+                writeLine(dependencies.stdout, `Baseline ${baseline.id} captured (${String(baseline.activities.length)} activity facts, ${String(baseline.elements.length)} element facts, ${String(baseline.checkpoints?.length ?? 0)} Checkpoint facts)`);
+            }
+            dependencies.setExitCode(0);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+        }
+    });
+}
+function createCompareCommand(dependencies) {
+    return new Command("compare")
+        .description("Compare a Verification report against a stored Baseline")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .requiredOption("--baseline <path>", "Baseline JSON path")
+        .requiredOption("--report <path>", "Verification report.json path")
+        .option("--journey-sha256 <sha256>", "Assert the current report's Journey sha256")
+        .option("--verdict <path>", "Contract verdict.json for this report (defaults beside report.json)")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        const json = options.json === true;
+        if (dependencies.baselineService === undefined) {
+            writeFailure(dependencies, json, "CONFIG_INVALID", "TapHound regression comparison is not configured");
+            return;
+        }
+        try {
+            await prepareWorkspace(dependencies, options.project);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+            return;
+        }
+        try {
+            const baselinePath = assertProjectPathUnder(options.project, options.baseline, BASELINES_DIR, "Baseline");
+            const reportPath = assertProjectPathUnder(options.project, options.report, BUILD_DIR, "Verification report");
+            const verdictPath = options.verdict === undefined
+                ? undefined
+                : assertProjectPathUnder(options.project, options.verdict, BUILD_DIR, "Contract verdict");
+            const result = await dependencies.baselineService.compare({
+                baselinePath,
+                reportPath,
+                journeySha256: options.journeySha256,
+                ...(verdictPath === undefined ? {} : { verdictPath })
+            });
+            if (json) {
+                writeJson(dependencies.stdout, result);
+            }
+            else {
+                writeLine(dependencies.stdout, result.equivalent
+                    ? `Regression compare: equivalent (${String(result.regressions.length)} diffs)`
+                    : `Regression compare: ${String(result.regressions.length)} diff(s)`);
+                for (const diff of result.regressions) {
+                    writeLine(dependencies.stdout, `- ${diff.kind}${diff.checkpointId === undefined ? "" : ` checkpoint=${diff.checkpointId}`}${diff.stepIndex === undefined ? "" : ` step=${String(diff.stepIndex)}`}: expected ${diff.expected}, actual ${diff.actual}`);
+                }
+            }
+            dependencies.setExitCode(result.equivalent ? 0 : 1);
+        }
+        catch (error) {
+            writeFailure(dependencies, json, failureCodeFromUnknown(error) ?? "CONFIG_INVALID", error instanceof Error ? error.message : String(error));
+        }
+    });
+}