taphound 0.2.0-dev.1

package/dist/application/runtime/verify-runtime.js

@@ -0,0 +1,350 @@
+import { resolve } from "node:path";
+import { normalizeActivity } from "../../domain/activity.js";
+import { exitCodeForFailure } from "../../domain/failure.js";
+import { hashJourney } from "../../domain/report.js";
+import { LogcatCollector } from "../collector/logcat-collector.js";
+import { ActivityWaiter } from "./activity-waiter.js";
+import { launchFailure } from "./launch-failure.js";
+import { ProcessWaiter } from "./process-waiter.js";
+import { StepRunner } from "./step-runner.js";
+function commandFailed(result) {
+    return result.exitCode !== 0
+        || result.timedOut
+        || result.cancelled
+        || result.spawnError !== undefined;
+}
+function commandMessage(result, fallback) {
+    return result.stderr.trim() || result.spawnError || fallback;
+}
+function logcatStopFailed(result) {
+    if (result.timedOut
+        || result.cancelled
+        || result.spawnError !== undefined) {
+        return true;
+    }
+    return result.exitCode !== 0
+        && result.signal !== "SIGTERM"
+        && result.signal !== "SIGKILL";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function layerForFailure(code) {
+    if (code === "APP_NOT_INSTALLED"
+        || code === "APP_LAUNCH_FAILED"
+        || code === "APP_CRASHED") {
+        return "run";
+    }
+    if (code === "ACTIVITY_BEFORE_MISMATCH"
+        || code === "ACTIVITY_AFTER_MISMATCH") {
+        return "activityCheckpoint";
+    }
+    if (code.startsWith("EXPECT_")) {
+        return "explicitExpect";
+    }
+    if (code === "COLLECTION_FAILED") {
+        return "collection";
+    }
+    return "structural";
+}
+export class VerifyRuntime {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async verify(input) {
+        const startedAt = this.dependencies.now();
+        const runId = this.dependencies.createRunId();
+        const launchActivity = normalizeActivity(input.config.run.packageName, input.config.run.activity);
+        const session = await this.dependencies.artifactStore.begin(resolve(input.projectRoot, input.config.artifactsDir), runId);
+        const logcat = new LogcatCollector(this.dependencies.adb, this.dependencies.clock);
+        let logcatStarted = false;
+        let primaryFailure;
+        const secondaryErrors = [];
+        const collectionErrors = [];
+        const steps = [];
+        const layers = {
+            run: "notRun",
+            structural: "notRun",
+            activityCheckpoint: "notRun",
+            explicitExpect: "notRun",
+            collection: "passed"
+        };
+        const setPrimary = (code, message, phase, stepIndex) => {
+            if (primaryFailure !== undefined) {
+                return;
+            }
+            primaryFailure = {
+                code,
+                message,
+                phase,
+                ...(stepIndex === undefined ? {} : { stepIndex })
+            };
+            layers[layerForFailure(code)] = "failed";
+        };
+        const collectionFailure = (message) => {
+            layers.collection = "failed";
+            const failure = {
+                code: "COLLECTION_FAILED",
+                message,
+                phase: "collection"
+            };
+            collectionErrors.push(failure);
+        };
+        try {
+            try {
+                const installed = await this.dependencies.adb.isInstalled({
+                    packageName: input.config.run.packageName,
+                    deviceSerial: input.deviceSerial,
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                    timeoutMs: input.config.idle.timeoutMs
+                });
+                if (!installed) {
+                    setPrimary("APP_NOT_INSTALLED", `Package ${input.config.run.packageName} is not installed on ${input.deviceSerial}`, "install");
+                }
+            }
+            catch (error) {
+                setPrimary("APP_NOT_INSTALLED", errorMessage(error), "install");
+            }
+            if (primaryFailure === undefined) {
+                try {
+                    await logcat.start({
+                        deviceSerial: input.deviceSerial,
+                        ...(input.signal === undefined ? {} : { signal: input.signal })
+                    });
+                    logcatStarted = true;
+                }
+                catch (error) {
+                    layers.collection = "failed";
+                    setPrimary("COLLECTION_FAILED", errorMessage(error), "collection");
+                }
+                if (logcatStarted) {
+                    const identity = {
+                        packageName: input.config.run.packageName,
+                        deviceSerial: input.deviceSerial,
+                        ...(input.signal === undefined ? {} : { signal: input.signal }),
+                        timeoutMs: input.config.idle.timeoutMs
+                    };
+                    const stopped = await this.dependencies.adb.forceStop(identity);
+                    const launched = commandFailed(stopped)
+                        ? undefined
+                        : await this.dependencies.adb.launchActivity({
+                            packageName: input.config.run.packageName,
+                            activity: launchActivity,
+                            deviceSerial: input.deviceSerial,
+                            ...(input.signal === undefined ? {} : { signal: input.signal }),
+                            timeoutMs: input.config.idle.timeoutMs
+                        });
+                    const launchError = launched === undefined
+                        ? commandMessage(stopped, "App reset failed")
+                        : launchFailure(launched);
+                    if (launchError !== undefined) {
+                        layers.run = "failed";
+                        setPrimary("APP_LAUNCH_FAILED", launchError, "run");
+                    }
+                    else {
+                        try {
+                            const launchReadinessStartedAt = this.dependencies.clock.now();
+                            const processReadiness = await new ProcessWaiter(this.dependencies.adb, this.dependencies.clock).wait({
+                                packageName: input.config.run.packageName,
+                                deviceSerial: input.deviceSerial,
+                                pollIntervalMs: input.config.idle.pollIntervalMs,
+                                timeoutMs: input.config.idle.timeoutMs,
+                                ...(input.signal === undefined ? {} : { signal: input.signal })
+                            });
+                            if (processReadiness.status === "timeout") {
+                                setPrimary("APP_LAUNCH_FAILED", "App process was not found after launch", "readiness");
+                            }
+                            else if (processReadiness.status === "cancelled") {
+                                setPrimary("INTERNAL_ERROR", "Verification was cancelled", "readiness");
+                            }
+                            else {
+                                logcat.scopeToPids(processReadiness.pids);
+                                const firstStep = input.journey.steps[0];
+                                if (firstStep === undefined) {
+                                    throw new Error("Journey requires at least one step");
+                                }
+                                const remainingReadinessMs = input.config.idle.timeoutMs
+                                    - (this.dependencies.clock.now()
+                                        - launchReadinessStartedAt);
+                                if (remainingReadinessMs <= 0) {
+                                    setPrimary("APP_LAUNCH_FAILED", `Expected startup Activity ${firstStep.activity.before}, found none before timeout`, "readiness");
+                                }
+                                else {
+                                    const readiness = await new ActivityWaiter(this.dependencies.adb, this.dependencies.clock).wait({
+                                        packageName: input.config.run.packageName,
+                                        deviceSerial: input.deviceSerial,
+                                        expectedActivity: firstStep.activity.before,
+                                        pollIntervalMs: input.config.idle.pollIntervalMs,
+                                        timeoutMs: remainingReadinessMs,
+                                        ...(input.signal === undefined ? {} : { signal: input.signal })
+                                    });
+                                    if (readiness.status === "processMissing") {
+                                        setPrimary("APP_LAUNCH_FAILED", "App process exited before reaching the first Journey Activity", "readiness");
+                                    }
+                                    else if (readiness.status === "timeout") {
+                                        setPrimary("APP_LAUNCH_FAILED", `Expected startup Activity ${firstStep.activity.before}, found ${readiness.actual ?? "none"} before timeout`, "readiness");
+                                    }
+                                    else if (readiness.status === "cancelled") {
+                                        setPrimary("INTERNAL_ERROR", "Verification was cancelled", "readiness");
+                                    }
+                                    else {
+                                        await this.dependencies.androidCli.layout({
+                                            deviceSerial: input.deviceSerial,
+                                            ...(input.signal === undefined ? {} : { signal: input.signal }),
+                                            timeoutMs: input.config.idle.timeoutMs
+                                        });
+                                        layers.run = "passed";
+                                        layers.structural = "passed";
+                                        layers.activityCheckpoint = "passed";
+                                        layers.explicitExpect = "passed";
+                                    }
+                                }
+                            }
+                        }
+                        catch (error) {
+                            setPrimary("APP_LAUNCH_FAILED", errorMessage(error), "readiness");
+                        }
+                    }
+                }
+            }
+            if (primaryFailure === undefined) {
+                const createStepRunner = this.dependencies.createStepRunner
+                    ?? ((options) => new StepRunner(options));
+                const runner = createStepRunner({
+                    adb: this.dependencies.adb,
+                    androidCli: this.dependencies.androidCli,
+                    clock: this.dependencies.clock,
+                    logcat,
+                    artifacts: session,
+                    packageName: input.config.run.packageName,
+                    deviceSerial: input.deviceSerial,
+                    idle: input.config.idle,
+                    ...(input.requireFocusedInput === undefined
+                        ? {}
+                        : { requireFocusedInput: input.requireFocusedInput }),
+                    ...(input.generatedReplayPolicy === undefined
+                        ? {}
+                        : { generatedReplayPolicy: input.generatedReplayPolicy })
+                });
+                for (const [index, step] of input.journey.steps.entries()) {
+                    const result = await runner.run(step, index, input.signal);
+                    steps.push(result.report);
+                    if (result.status === "cancelled") {
+                        setPrimary("INTERNAL_ERROR", "Verification was cancelled", "replay", index);
+                        break;
+                    }
+                    if (result.status === "failed") {
+                        setPrimary(result.failure.code, result.failure.message, result.failure.phase, result.failure.stepIndex);
+                        break;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (primaryFailure === undefined) {
+                setPrimary("INTERNAL_ERROR", errorMessage(error), "runtime");
+            }
+            else {
+                secondaryErrors.push({
+                    code: "INTERNAL_ERROR",
+                    message: errorMessage(error),
+                    phase: "runtime"
+                });
+            }
+        }
+        const screenshotPath = "screenshot.png";
+        let screenshotCollected = false;
+        try {
+            const screenshot = await this.dependencies.androidCli.captureScreen({
+                outputPath: session.path(screenshotPath),
+                deviceSerial: input.deviceSerial,
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+            if (commandFailed(screenshot)) {
+                collectionFailure(commandMessage(screenshot, "Screen capture failed"));
+            }
+            else {
+                screenshotCollected = true;
+            }
+        }
+        catch (error) {
+            collectionFailure(errorMessage(error));
+        }
+        let logcatCollected = false;
+        if (logcatStarted) {
+            try {
+                const stopped = await logcat.stop();
+                if (logcatStopFailed(stopped)) {
+                    collectionFailure(commandMessage(stopped, "Logcat stop failed"));
+                }
+                await session.writeText("logcat.txt", logcat.lines().map((line) => line.raw).join("\n"));
+                logcatCollected = true;
+            }
+            catch (error) {
+                collectionFailure(errorMessage(error));
+            }
+        }
+        if (collectionErrors.length > 0) {
+            if (primaryFailure === undefined) {
+                primaryFailure = collectionErrors.shift();
+            }
+            secondaryErrors.push(...collectionErrors);
+        }
+        const finishedAt = this.dependencies.now();
+        const failure = primaryFailure;
+        const status = failure === undefined
+            ? "passed"
+            : [
+                "CONFIG_INVALID",
+                "ENVIRONMENT_MISSING_TOOL",
+                "DEVICE_UNAVAILABLE",
+                "APP_NOT_INSTALLED",
+                "INTERNAL_ERROR"
+            ].includes(failure.code)
+                ? "error"
+                : "failed";
+        const report = {
+            schemaVersion: 2,
+            runId,
+            status,
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            durationMs: Math.max(0, finishedAt.getTime() - startedAt.getTime()),
+            project: {
+                root: input.projectRoot,
+                packageName: input.config.run.packageName,
+                launchActivity
+            },
+            journey: {
+                name: input.journey.name,
+                sha256: hashJourney(input.journey)
+            },
+            environment: {
+                deviceSerial: input.deviceSerial,
+                tools: input.toolVersions
+            },
+            layers,
+            steps,
+            artifacts: {
+                directory: session.finalDirectory,
+                report: "report.json",
+                summary: "summary.txt",
+                ...(screenshotCollected ? { screenshot: screenshotPath } : {}),
+                ...(logcatCollected ? { logcat: "logcat.txt" } : {}),
+                stepLogs: steps.flatMap((step) => (step.logcatPath === undefined ? [] : [step.logcatPath]))
+            },
+            ...(failure === undefined ? {} : { primaryFailure: failure }),
+            secondaryErrors,
+            fallbackUsed: steps.some((step) => step.locator?.fallbackUsed === true)
+        };
+        const published = await this.dependencies.reportWriter.writeAndPublish(session, report);
+        return {
+            status,
+            exitCode: failure === undefined ? 0 : exitCodeForFailure(failure.code),
+            report,
+            reportPath: published.reportPath,
+            summaryPath: published.summaryPath
+        };
+    }
+}

package/dist/application/wait/idle-waiter.d.ts

@@ -0,0 +1,30 @@
+import type { FailureCode } from "../../domain/failure.js";
+import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { Clock } from "../../ports/clock.js";
+export interface IdleConfig {
+    pollIntervalMs: number;
+    stablePolls: number;
+    timeoutMs: number;
+}
+export type IdleResult = {
+    status: "stable";
+    polls: number;
+    durationMs: number;
+} | {
+    status: "timeout";
+    code: Extract<FailureCode, "IDLE_TIMEOUT">;
+    polls: number;
+    durationMs: number;
+    lastDiff: readonly unknown[];
+} | {
+    status: "cancelled";
+    polls: number;
+    durationMs: number;
+};
+export declare class IdleWaiter {
+    private readonly androidCli;
+    private readonly clock;
+    private readonly deviceSerial;
+    constructor(androidCli: AndroidCliPort, clock: Clock, deviceSerial: string);
+    waitUntilIdle(config: IdleConfig, signal?: AbortSignal): Promise<IdleResult>;
+}

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

@@ -0,0 +1,90 @@
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+export class IdleWaiter {
+    androidCli;
+    clock;
+    deviceSerial;
+    constructor(androidCli, clock, deviceSerial) {
+        this.androidCli = androidCli;
+        this.clock = clock;
+        this.deviceSerial = deviceSerial;
+    }
+    async waitUntilIdle(config, signal) {
+        const startedAt = this.clock.now();
+        let polls = 0;
+        let consecutiveEmpty = 0;
+        let lastDiff = [];
+        for (;;) {
+            if (isAborted(signal)) {
+                return {
+                    status: "cancelled",
+                    polls,
+                    durationMs: this.clock.now() - startedAt
+                };
+            }
+            const elapsedBeforePoll = this.clock.now() - startedAt;
+            polls += 1;
+            let diff;
+            try {
+                diff = await this.androidCli.layoutDiff({
+                    deviceSerial: this.deviceSerial,
+                    ...(signal === undefined ? {} : { signal }),
+                    timeoutMs: Math.max(1, config.timeoutMs - elapsedBeforePoll)
+                });
+            }
+            catch (error) {
+                const elapsed = this.clock.now() - startedAt;
+                if (isAborted(signal)) {
+                    return { status: "cancelled", polls, durationMs: elapsed };
+                }
+                if (elapsed >= config.timeoutMs) {
+                    return {
+                        status: "timeout",
+                        code: "IDLE_TIMEOUT",
+                        polls,
+                        durationMs: elapsed,
+                        lastDiff
+                    };
+                }
+                throw error;
+            }
+            if (diff.length === 0) {
+                consecutiveEmpty += 1;
+            }
+            else {
+                consecutiveEmpty = 0;
+                lastDiff = diff;
+            }
+            if (consecutiveEmpty >= config.stablePolls) {
+                return {
+                    status: "stable",
+                    polls,
+                    durationMs: this.clock.now() - startedAt
+                };
+            }
+            if (this.clock.now() - startedAt >= config.timeoutMs) {
+                return {
+                    status: "timeout",
+                    code: "IDLE_TIMEOUT",
+                    polls,
+                    durationMs: this.clock.now() - startedAt,
+                    lastDiff
+                };
+            }
+            try {
+                await this.clock.sleep(config.pollIntervalMs, signal);
+            }
+            catch (error) {
+                if (isAborted(signal)) {
+                    return {
+                        status: "cancelled",
+                        polls,
+                        durationMs: this.clock.now() - startedAt
+                    };
+                }
+                throw error;
+            }
+        }
+    }
+}

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

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

package/dist/cli/commands/context.js

@@ -0,0 +1,94 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+import { ProjectContextSchema } from "../../domain/project-context.js";
+import { errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
+function exitCodeForContext(command, result) {
+    if (result.status === "invalid") {
+        return 2;
+    }
+    return command === "validate" && result.status === "stale" ? 1 : 0;
+}
+function createContextOperation(dependencies, name) {
+    return new Command(name)
+        .description(name === "validate"
+        ? "Validate deterministic Project Context evidence"
+        : "Observe deterministic Project Context status")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", "taphound.config.json")
+        .requiredOption("--context <path>", "Project Context path")
+        .option("--json", "Emit one machine-readable JSON value")
+        .action(async (options) => {
+        let config;
+        let context;
+        try {
+            config = TapHoundConfigSchema.parse(await dependencies.readJson(resolve(options.project, options.config)));
+        }
+        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;
+        }
+        try {
+            context = ProjectContextSchema.parse(await dependencies.readJson(resolve(options.project, options.context)));
+        }
+        catch (error) {
+            const output = {
+                status: "error",
+                exitCode: 2,
+                failure: {
+                    code: "CONTEXT_INVALID",
+                    message: errorMessage(error)
+                }
+            };
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stderr, output.failure.message);
+            }
+            dependencies.setExitCode(2);
+            return;
+        }
+        try {
+            const result = await dependencies.contextValidator.validate({
+                context,
+                projectRoot: options.project,
+                config
+            });
+            const exitCode = exitCodeForContext(name, result);
+            const output = { ...result, exitCode };
+            if (options.json === true) {
+                writeJson(dependencies.stdout, output);
+            }
+            else {
+                writeLine(dependencies.stdout, result.status === "valid"
+                    ? "Context: valid"
+                    : `Context: ${result.status} (${result.reason.message})`);
+            }
+            dependencies.setExitCode(exitCode);
+        }
+        catch (error) {
+            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);
+        }
+    });
+}
+export function createContextCommand(dependencies) {
+    return new Command("context")
+        .description("Validate or inspect Project Context")
+        .addCommand(createContextOperation(dependencies, "validate"))
+        .addCommand(createContextOperation(dependencies, "status"));
+}

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

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

package/dist/cli/commands/doctor.js

@@ -0,0 +1,51 @@
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+import { doctorMessage, errorMessage, failureOutput, writeJson, writeLine } from "../output.js";
+async function configuredPackageName(dependencies, options) {
+    try {
+        return TapHoundConfigSchema.parse(await dependencies.readJson(resolve(options.project, options.config))).run.packageName;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createDoctorCommand(dependencies) {
+    return new Command("doctor")
+        .description("Check TapHound tools, permissions, application, and device")
+        .option("--project <path>", "Android project root", dependencies.cwd())
+        .option("--config <path>", "TapHound config path", "taphound.config.json")
+        .option("--device <serial>", "Select an online Android device")
+        .option("--json", "Emit machine-readable JSON")
+        .action(async (options) => {
+        try {
+            const packageName = await configuredPackageName(dependencies, options);
+            const report = await dependencies.doctor.run({
+                ...(packageName === undefined ? {} : { packageName }),
+                ...(options.device === undefined
+                    ? {}
+                    : { requestedDevice: options.device }),
+                ...(dependencies.signal === undefined
+                    ? {}
+                    : { signal: dependencies.signal })
+            });
+            if (options.json === true) {
+                writeJson(dependencies.stdout, report);
+            }
+            else {
+                writeLine(dependencies.stdout, doctorMessage(report));
+            }
+            dependencies.setExitCode(report.status === "passed" ? 0 : 3);
+        }
+        catch (error) {
+            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);
+        }
+    });
+}

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

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