taphound 0.2.0-dev.1

package/dist/application/context/context-validator.js

@@ -0,0 +1,120 @@
+import { normalizeActivity } from "../../domain/activity.js";
+import { ProjectContextSchema } from "../../domain/project-context.js";
+export const MAX_CONTEXT_EVIDENCE_BYTES = 1024 * 1024;
+const SECRET_FILE_NAMES = new Set([
+    ".git-credentials",
+    ".netrc",
+    ".npmrc",
+    ".pypirc",
+    "credentials",
+    "id_dsa",
+    "id_ecdsa",
+    "id_ed25519",
+    "id_rsa",
+    "keystore.properties",
+    "local.properties",
+    "secret.json",
+    "secrets.json"
+]);
+const SECRET_FILE_EXTENSIONS = [
+    ".der",
+    ".jks",
+    ".key",
+    ".keystore",
+    ".p12",
+    ".pk8",
+    ".pem",
+    ".pfx",
+    ".ppk"
+];
+function isSecretEvidencePath(path) {
+    const components = path
+        .replaceAll("\\", "/")
+        .split("/")
+        .filter((component) => component.length > 0)
+        .map((component) => component.toLowerCase());
+    const fileName = components.at(-1) ?? "";
+    return (components.some((component) => (component.startsWith(".env")
+        || component === ".secrets"
+        || component === ".credentials"
+        || component === ".ssh"
+        || component === ".gnupg"))
+        || SECRET_FILE_NAMES.has(fileName)
+        || /^credentials(?:\.|$)/.test(fileName)
+        || /^service-account(?:\.|$)/.test(fileName)
+        || SECRET_FILE_EXTENSIONS.some((extension) => fileName.endsWith(extension)));
+}
+function invalid(code, message) {
+    return { status: "invalid", reason: { code, message } };
+}
+function invalidInspection(path, inspection) {
+    switch (inspection.status) {
+        case "rootNotFound":
+        case "rootUnreadable":
+            return invalid("PROJECT_ROOT_UNREADABLE", "Project root does not exist or cannot be read");
+        case "rootNotDirectory":
+            return invalid("PROJECT_ROOT_NOT_DIRECTORY", "Project root is not a directory");
+        case "notFound":
+            return invalid("EVIDENCE_NOT_FOUND", `Evidence file does not exist: ${path}`);
+        case "unreadable":
+            return invalid("EVIDENCE_UNREADABLE", `Evidence file cannot be read: ${path}`);
+        case "escape":
+            return invalid("EVIDENCE_PATH_ESCAPE", `Evidence file resolves outside the project: ${path}`);
+        case "changedIdentity":
+            return invalid("EVIDENCE_CHANGED_IDENTITY", `Evidence file changed during inspection: ${path}`);
+        case "notFile":
+            return invalid("EVIDENCE_NOT_FILE", `Evidence path is not a file: ${path}`);
+        case "tooLarge":
+            return invalid("EVIDENCE_TOO_LARGE", `Evidence file exceeds ${String(MAX_CONTEXT_EVIDENCE_BYTES)} bytes: ${path}`);
+    }
+}
+export class ContextValidator {
+    files;
+    constructor(files) {
+        this.files = files;
+    }
+    validate = async (input) => {
+        const parsed = ProjectContextSchema.safeParse(input.context);
+        if (!parsed.success) {
+            return invalid("CONTEXT_SCHEMA_INVALID", "Project Context does not match the version 1 schema");
+        }
+        let configuredActivity;
+        try {
+            configuredActivity = normalizeActivity(input.config.run.packageName, input.config.run.activity);
+        }
+        catch {
+            return invalid("CONTEXT_IDENTITY_MISMATCH", "Project Context identity does not match the configured project");
+        }
+        if (parsed.data.packageName !== input.config.run.packageName
+            || parsed.data.launchActivity !== configuredActivity) {
+            return invalid("CONTEXT_IDENTITY_MISMATCH", "Project Context identity does not match the configured project");
+        }
+        let staleReason;
+        for (const evidence of parsed.data.manifest.files) {
+            if (isSecretEvidencePath(evidence.path)) {
+                return invalid("EVIDENCE_SECRET_PATH", `Secret files cannot be context evidence: ${evidence.path}`);
+            }
+            const inspection = await this.files.inspectProjectFile({
+                projectRoot: input.projectRoot,
+                relativePath: evidence.path,
+                maximumBytes: MAX_CONTEXT_EVIDENCE_BYTES
+            });
+            if ("resolvedRelativePath" in inspection
+                && isSecretEvidencePath(inspection.resolvedRelativePath)) {
+                return invalid("EVIDENCE_SECRET_PATH", `Secret files cannot be context evidence: ${evidence.path}`);
+            }
+            if (inspection.status !== "inspected") {
+                return invalidInspection(evidence.path, inspection);
+            }
+            if (inspection.sha256 !== evidence.sha256) {
+                staleReason ??= {
+                    code: "EVIDENCE_HASH_MISMATCH",
+                    message: `Evidence file changed: ${evidence.path}`
+                };
+            }
+        }
+        return staleReason === undefined
+            ? { status: "valid" }
+            : { status: "stale", reason: staleReason };
+    };
+}

package/dist/application/doctor/doctor-service.d.ts

@@ -0,0 +1,35 @@
+import type { FailureCode } from "../../domain/failure.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { ProcessRunner } from "../../ports/process-runner.js";
+export type DoctorCheckName = "node" | "adb" | "android" | "app" | "permissions" | "device";
+export interface DoctorCheck {
+    name: DoctorCheckName;
+    status: "passed" | "failed" | "notRun";
+    version?: string | undefined;
+    message?: string | undefined;
+}
+export interface DoctorReport {
+    status: "passed" | "failed";
+    checks: DoctorCheck[];
+    deviceSerial?: string | undefined;
+    failureCode?: Extract<FailureCode, "ENVIRONMENT_MISSING_TOOL" | "DEVICE_UNAVAILABLE" | "APP_NOT_INSTALLED"> | undefined;
+}
+export interface DoctorRunInput {
+    packageName?: string | undefined;
+    requestedDevice?: string | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface DoctorDependencies {
+    runner: ProcessRunner;
+    adb: AdbPort;
+    nodeVersion: string;
+    checkAndroidPermissions: (deviceSerial: string, signal?: AbortSignal) => Promise<{
+        status: "passed" | "failed";
+        message?: string | undefined;
+    }>;
+}
+export declare class DoctorService {
+    private readonly dependencies;
+    constructor(dependencies: DoctorDependencies);
+    run(input?: DoctorRunInput): Promise<DoctorReport>;
+}

package/dist/application/doctor/doctor-service.js

@@ -0,0 +1,178 @@
+function firstLine(value) {
+    return value.trim().split(/\r?\n/, 1)[0] ?? "unknown";
+}
+function nodeCheck(version) {
+    const normalized = version.replace(/^v/, "");
+    const major = Number(normalized.split(".", 1)[0]);
+    return Number.isInteger(major) && major >= 22
+        ? { name: "node", status: "passed", version: normalized }
+        : {
+            name: "node",
+            status: "failed",
+            version: normalized,
+            message: "TapHound requires Node.js 22 or newer"
+        };
+}
+export class DoctorService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async run(input = {}) {
+        const { packageName, requestedDevice, signal } = input;
+        const checks = [nodeCheck(this.dependencies.nodeVersion)];
+        const tool = async (name, executable, args) => {
+            try {
+                const result = await this.dependencies.runner.run({
+                    executable,
+                    args,
+                    ...(signal === undefined ? {} : { signal })
+                });
+                if (result.exitCode !== 0
+                    || result.spawnError !== undefined
+                    || result.cancelled
+                    || result.timedOut) {
+                    return {
+                        name,
+                        status: "failed",
+                        message: result.stderr.trim()
+                            || result.spawnError
+                            || `${executable} check failed`
+                    };
+                }
+                return {
+                    name,
+                    status: "passed",
+                    version: firstLine(result.stdout)
+                };
+            }
+            catch (error) {
+                return {
+                    name,
+                    status: "failed",
+                    message: error instanceof Error ? error.message : String(error)
+                };
+            }
+        };
+        checks.push(await tool("adb", "adb", ["version"]), await tool("android", "android", ["--version"]));
+        let deviceSerial;
+        let deviceCheck;
+        try {
+            const devices = (await this.dependencies.adb.devices(signal)).filter((device) => device.status === "device");
+            const selected = requestedDevice === undefined
+                ? (devices.length === 1 ? devices[0] : undefined)
+                : devices.find((device) => device.serial === requestedDevice);
+            if (selected !== undefined) {
+                deviceSerial = selected.serial;
+                deviceCheck = {
+                    name: "device",
+                    status: "passed",
+                    message: deviceSerial
+                };
+            }
+            else {
+                deviceCheck = {
+                    name: "device",
+                    status: "failed",
+                    message: requestedDevice === undefined
+                        ? `Expected exactly one online device, found ${String(devices.length)}`
+                        : `Requested device is not online: ${requestedDevice}`
+                };
+            }
+        }
+        catch (error) {
+            deviceCheck = {
+                name: "device",
+                status: "failed",
+                message: error instanceof Error ? error.message : String(error)
+            };
+        }
+        if (packageName === undefined) {
+            checks.push({
+                name: "app",
+                status: "notRun",
+                message: "Installed application probe requires a configured package"
+            });
+        }
+        else if (deviceSerial === undefined) {
+            checks.push({
+                name: "app",
+                status: "notRun",
+                message: "Installed application probe requires an online selected device"
+            });
+        }
+        else {
+            try {
+                const installed = await this.dependencies.adb.isInstalled({
+                    packageName,
+                    deviceSerial,
+                    ...(signal === undefined ? {} : { signal })
+                });
+                checks.push(installed
+                    ? { name: "app", status: "passed", message: packageName }
+                    : {
+                        name: "app",
+                        status: "failed",
+                        message: `Package ${packageName} is not installed on ${deviceSerial}`
+                    });
+            }
+            catch (error) {
+                checks.push({
+                    name: "app",
+                    status: "failed",
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        if (deviceSerial === undefined) {
+            checks.push({
+                name: "permissions",
+                status: "notRun",
+                message: "Permission probe requires an online selected device"
+            });
+        }
+        else {
+            try {
+                const permission = await this.dependencies.checkAndroidPermissions(deviceSerial, signal);
+                checks.push({
+                    name: "permissions",
+                    status: permission.status,
+                    ...(permission.message === undefined
+                        ? {}
+                        : { message: permission.message })
+                });
+            }
+            catch (error) {
+                checks.push({
+                    name: "permissions",
+                    status: "failed",
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        checks.push(deviceCheck);
+        const failedCheck = (name) => checks.some((check) => check.name === name && check.status === "failed");
+        const environmentFailed = ["node", "adb", "android", "permissions"]
+            .some(failedCheck);
+        const failureCode = environmentFailed
+            ? "ENVIRONMENT_MISSING_TOOL"
+            : failedCheck("device")
+                ? "DEVICE_UNAVAILABLE"
+                : failedCheck("app")
+                    ? "APP_NOT_INSTALLED"
+                    : undefined;
+        if (failureCode !== undefined) {
+            return {
+                status: "failed",
+                checks,
+                ...(deviceSerial === undefined ? {} : { deviceSerial }),
+                failureCode
+            };
+        }
+        return {
+            status: "passed",
+            checks,
+            ...(deviceSerial === undefined ? {} : { deviceSerial })
+        };
+    }
+}

package/dist/application/generation/focused-input.d.ts

@@ -0,0 +1,2 @@
+import type { LayoutElement } from "../../domain/layout.js";
+export declare function hasExactlyOneEnabledFocusedElement(layout: readonly LayoutElement[]): boolean;

package/dist/application/generation/focused-input.js

@@ -0,0 +1,9 @@
+function flatten(elements) {
+    return elements.flatMap((element) => [
+        element,
+        ...flatten(element.children)
+    ]);
+}
+export function hasExactlyOneEnabledFocusedElement(layout) {
+    return flatten(layout).filter((element) => element.enabled && element.focused === true).length === 1;
+}

package/dist/application/generation/generation-confirmation-service.d.ts

@@ -0,0 +1,76 @@
+import { type PendingConfirmation } from "../../domain/generation.js";
+import { type ProposedStep } from "../../domain/proposed-step.js";
+import { type RuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { type GenerationPromptPort, type ManualProposalInput } from "../../ports/generation-prompt.js";
+import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+export interface GenerationConfirmationDependencies {
+    store: Pick<GenerationSessionStore, "read" | "updateConfirmation" | "writeEvidence" | "readEvidence">;
+    prompt: Pick<GenerationPromptPort, "confirm" | "buildManualProposal">;
+    now: () => Date;
+    generateChallengeId: () => string;
+    confirmationTtlMs: number;
+}
+export interface ConfirmationRequestInput {
+    generationId: string;
+    proposal: ProposedStep;
+    snapshot: RuntimeSnapshot;
+    source?: "planner" | "manualOverride" | undefined;
+}
+export interface ConfirmationApproveInput extends ConfirmationRequestInput {
+    challengeId: string;
+    signal?: AbortSignal | undefined;
+}
+export interface StoredConfirmationApproveInput {
+    generationId: string;
+    challengeId: string;
+    signal?: AbortSignal | undefined;
+}
+export interface ManualConfirmationRequestInput {
+    generationId: string;
+    snapshot: RuntimeSnapshot;
+    manual: ManualProposalInput;
+    signal?: AbortSignal | undefined;
+}
+export interface PendingManualConfirmationInput {
+    generationId: string;
+    action: ManualProposalInput["action"];
+}
+export interface ConfirmationRequiredResult {
+    status: "confirmationRequired";
+    challenge: PendingConfirmation;
+}
+export type ConfirmationRequestResult = {
+    status: "approved";
+    proposal: ProposedStep;
+} | ConfirmationRequiredResult;
+export interface StoredConfirmationApproveResult {
+    status: "approved";
+    proposal: ProposedStep;
+    snapshot: RuntimeSnapshot;
+    source: "planner" | "manualOverride";
+}
+export declare function summarizeProposedStep(step: ProposedStep): string;
+export declare function confirmationEvidencePath(challengeId: string): string;
+export declare class GenerationConfirmationService {
+    private readonly dependencies;
+    private readonly validator;
+    private readonly riskEvaluator;
+    constructor(dependencies: GenerationConfirmationDependencies);
+    readonly request: (input: ConfirmationRequestInput) => Promise<ConfirmationRequestResult>;
+    readonly requestManual: (input: ManualConfirmationRequestInput) => Promise<ConfirmationRequestResult>;
+    readonly findPendingManual: (input: PendingManualConfirmationInput) => Promise<ConfirmationRequiredResult | null>;
+    readonly confirmStored: (input: StoredConfirmationApproveInput) => Promise<StoredConfirmationApproveResult>;
+    readonly confirm: (input: ConfirmationApproveInput) => Promise<{
+        status: "approved";
+        proposal: ProposedStep;
+    }>;
+    readonly clearApproved: (input: {
+        generationId: string;
+        challenge: PendingConfirmation;
+    }) => Promise<void>;
+    private clearExactChallenge;
+    private cancelPrompt;
+    private requireExactPendingChallenge;
+    private updateConfirmationReconciled;
+    private readStoredEvidence;
+}