taphound 0.2.0-dev.1

package/dist/adapters/process/node-process-runner.js

@@ -0,0 +1,155 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+function consumeLines(buffer, chunk) {
+    const content = buffer.pending + chunk;
+    const lines = content.split(/\r?\n/);
+    buffer.pending = lines.pop() ?? "";
+    for (const line of lines) {
+        buffer.emit?.(line);
+    }
+}
+function flushLine(buffer) {
+    if (buffer.pending.length > 0) {
+        buffer.emit?.(buffer.pending);
+        buffer.pending = "";
+    }
+}
+export class NodeProcessRunner {
+    defaultTimeoutMs;
+    streamStartupGraceMs;
+    constructor(defaultTimeoutMs = 15 * 60 * 1000, streamStartupGraceMs = 250) {
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.streamStartupGraceMs = streamStartupGraceMs;
+    }
+    run(spec) {
+        return this.start({
+            ...spec,
+            timeoutMs: spec.timeoutMs ?? this.defaultTimeoutMs
+        }).completion;
+    }
+    start(spec, handlers = {}) {
+        const startedAt = performance.now();
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let cancelled = false;
+        let spawnError;
+        let settled = false;
+        let timeout;
+        let forceKillTimeout;
+        let startupTimeout;
+        let startupSettled = false;
+        let resolveStarted = () => undefined;
+        const started = new Promise((resolve) => {
+            resolveStarted = resolve;
+        });
+        const settleStarted = (result) => {
+            if (startupSettled) {
+                return;
+            }
+            startupSettled = true;
+            if (startupTimeout !== undefined) {
+                clearTimeout(startupTimeout);
+            }
+            resolveStarted(result);
+        };
+        const stdoutLines = {
+            pending: "",
+            emit: handlers.onStdoutLine === undefined
+                ? undefined
+                : (line) => handlers.onStdoutLine?.(line)
+        };
+        const stderrLines = {
+            pending: "",
+            emit: handlers.onStderrLine === undefined
+                ? undefined
+                : (line) => handlers.onStderrLine?.(line)
+        };
+        const child = spawn(spec.executable, [...spec.args], {
+            cwd: spec.cwd,
+            env: {
+                ...process.env,
+                ...spec.env
+            },
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+            consumeLines(stdoutLines, chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+            consumeLines(stderrLines, chunk);
+        });
+        child.on("spawn", () => {
+            startupTimeout = setTimeout(() => {
+                settleStarted(undefined);
+            }, this.streamStartupGraceMs);
+            startupTimeout.unref();
+        });
+        child.on("error", (error) => {
+            spawnError = error.message;
+        });
+        const terminate = () => {
+            if (settled || child.killed) {
+                return;
+            }
+            child.kill("SIGTERM");
+            forceKillTimeout = setTimeout(() => {
+                if (!settled) {
+                    child.kill("SIGKILL");
+                }
+            }, 1000);
+            forceKillTimeout.unref();
+        };
+        const abort = () => {
+            cancelled = true;
+            terminate();
+        };
+        spec.signal?.addEventListener("abort", abort, { once: true });
+        if (spec.timeoutMs !== undefined) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                terminate();
+            }, spec.timeoutMs);
+            timeout.unref();
+        }
+        const completion = new Promise((resolve) => {
+            child.on("close", (exitCode, signal) => {
+                settled = true;
+                if (timeout !== undefined) {
+                    clearTimeout(timeout);
+                }
+                if (forceKillTimeout !== undefined) {
+                    clearTimeout(forceKillTimeout);
+                }
+                spec.signal?.removeEventListener("abort", abort);
+                flushLine(stdoutLines);
+                flushLine(stderrLines);
+                const result = {
+                    exitCode,
+                    signal,
+                    stdout,
+                    stderr,
+                    durationMs: performance.now() - startedAt,
+                    timedOut,
+                    cancelled,
+                    ...(spawnError === undefined ? {} : { spawnError })
+                };
+                settleStarted(result);
+                resolve(result);
+            });
+        });
+        const stop = () => {
+            terminate();
+            return completion;
+        };
+        if (spec.signal?.aborted === true) {
+            abort();
+        }
+        return { started, completion, stop };
+    }
+}

package/dist/adapters/prompt/inquirer-generation-prompt.d.ts

@@ -0,0 +1,55 @@
+import { confirm } from "@inquirer/prompts";
+import type { PendingConfirmation } from "../../domain/generation.js";
+import { type ProposedStep } from "../../domain/proposed-step.js";
+import type { GenerationPromptPort, ManualProposalInput } from "../../ports/generation-prompt.js";
+interface SelectConfig {
+    message: string;
+    choices: readonly {
+        name: string;
+        value: string;
+    }[];
+}
+interface InputConfig {
+    message: string;
+    validate?: ((value: string) => boolean | string) | undefined;
+}
+interface ConfirmConfig {
+    message: string;
+    default: boolean;
+}
+interface NumberConfig {
+    message: string;
+    default: number;
+    min?: number | undefined;
+    max?: number | undefined;
+}
+export type GenerationPromptContext = NonNullable<Parameters<typeof confirm>[1]>;
+export interface GenerationPromptFunctions {
+    select: (config: SelectConfig, context: GenerationPromptContext) => Promise<unknown>;
+    input: (config: InputConfig, context: GenerationPromptContext) => Promise<unknown>;
+    confirm: (config: ConfirmConfig, context: GenerationPromptContext) => Promise<unknown>;
+    number: (config: NumberConfig, context: GenerationPromptContext) => Promise<unknown>;
+}
+export type GenerationInputStream = NodeJS.ReadableStream & {
+    isTTY?: boolean | undefined;
+};
+export type GenerationDiagnosticStream = NodeJS.WritableStream & {
+    isTTY?: boolean | undefined;
+};
+export declare class InquirerGenerationPrompt implements GenerationPromptPort {
+    private readonly prompts;
+    private readonly promptInput;
+    private readonly diagnostics;
+    constructor(prompts?: GenerationPromptFunctions, promptInput?: GenerationInputStream, diagnostics?: GenerationDiagnosticStream);
+    confirm(challenge: PendingConfirmation, signal?: AbortSignal): Promise<boolean>;
+    buildManualProposal(input: ManualProposalInput, signal?: AbortSignal): Promise<ProposedStep>;
+    private buildScrollTo;
+    private selectTarget;
+    private selectDirection;
+    private swipeOptions;
+    private assertLocalTty;
+    private ask;
+    private throwIfCancelled;
+    private context;
+}
+export {};

package/dist/adapters/prompt/inquirer-generation-prompt.js

@@ -0,0 +1,213 @@
+import { confirm, input, number as numberPrompt, select } from "@inquirer/prompts";
+import { listLocatableTargets, listRecorderTargets } from "../../application/recorder/locator-selector.js";
+import { ProposedStepSchema } from "../../domain/proposed-step.js";
+import { GenerationPromptCancelledError } from "../../ports/generation-prompt.js";
+const defaultPrompts = {
+    select: async (config, context) => select({
+        message: config.message,
+        choices: [...config.choices]
+    }, context),
+    input: async (config, context) => input({
+        message: config.message,
+        ...(config.validate === undefined ? {} : { validate: config.validate })
+    }, context),
+    confirm: async (config, context) => confirm(config, context),
+    number: async (config, context) => numberPrompt(config, context)
+};
+function selectedString(value, allowed) {
+    if (typeof value !== "string"
+        || (allowed !== undefined && !allowed.includes(value))) {
+        throw new Error("Prompt returned an invalid selection");
+    }
+    return value;
+}
+function selectedNumber(value, minimum, maximum = Number.POSITIVE_INFINITY) {
+    if (typeof value !== "number"
+        || !Number.isFinite(value)
+        || value < minimum
+        || value > maximum) {
+        throw new Error("Prompt returned an invalid number");
+    }
+    return value;
+}
+function common(input) {
+    return {
+        binding: input.binding,
+        activity: { before: input.before },
+        ...(input.expect === undefined ? {} : { expect: input.expect })
+    };
+}
+function requireTargets(targets) {
+    if (targets.length === 0) {
+        throw new Error("No deterministic Layout targets are available");
+    }
+}
+export class InquirerGenerationPrompt {
+    prompts;
+    promptInput;
+    diagnostics;
+    constructor(prompts = defaultPrompts, promptInput = process.stdin, diagnostics = process.stderr) {
+        this.prompts = prompts;
+        this.promptInput = promptInput;
+        this.diagnostics = diagnostics;
+    }
+    async confirm(challenge, signal) {
+        this.throwIfCancelled(signal);
+        this.assertLocalTty("Generation confirmation");
+        if (challenge.status !== "pending") {
+            throw new Error("Generation confirmation challenge is not pending");
+        }
+        this.diagnostics.write(`TapHound confirmation: ${challenge.actionSummary}\n`);
+        const answer = await this.ask((context) => this.prompts.confirm({
+            message: `Approve action at step ${String(challenge.stepIndex)}?`,
+            default: false
+        }, context), signal);
+        if (typeof answer !== "boolean") {
+            throw new Error("Prompt returned an invalid confirmation");
+        }
+        return answer;
+    }
+    async buildManualProposal(input, signal) {
+        this.throwIfCancelled(signal);
+        this.assertLocalTty("Manual generation takeover");
+        const shared = common(input);
+        if (input.action === "back" || input.action === "wait") {
+            return ProposedStepSchema.parse({ action: input.action, ...shared });
+        }
+        if (input.action === "inputText") {
+            const text = selectedString(await this.ask((context) => this.prompts.input({
+                message: "Text to enter",
+                validate: (answer) => answer.length > 0 || "Text must not be empty"
+            }, context), signal));
+            return ProposedStepSchema.parse({ action: input.action, text, ...shared });
+        }
+        if (input.action === "scrollTo") {
+            return this.buildScrollTo(input, shared, signal);
+        }
+        const targets = listRecorderTargets(input.layout, input.action);
+        const target = await this.selectTarget(targets, "Choose a deterministic Layout target", signal);
+        if (input.action === "click") {
+            return ProposedStepSchema.parse({
+                action: input.action,
+                locator: target.locator,
+                ...shared
+            });
+        }
+        if (input.action === "longClick") {
+            const durationMs = selectedNumber(await this.ask((context) => this.prompts.number({
+                message: "Long-click duration (ms)",
+                default: 800,
+                min: 1
+            }, context), signal), 1);
+            return ProposedStepSchema.parse({
+                action: input.action,
+                locator: target.locator,
+                durationMs,
+                ...shared
+            });
+        }
+        const direction = await this.selectDirection(signal);
+        const options = await this.swipeOptions(signal);
+        return ProposedStepSchema.parse({
+            action: input.action,
+            locator: target.locator,
+            direction,
+            ...options,
+            ...shared
+        });
+    }
+    async buildScrollTo(input, shared, signal) {
+        const container = await this.selectTarget(listRecorderTargets(input.layout, "swipe"), "Choose the scrollable container", signal);
+        const target = await this.selectTarget(listLocatableTargets(input.layout), "Choose the scroll target", signal);
+        const direction = await this.selectDirection(signal);
+        const options = await this.swipeOptions(signal);
+        const maxSwipes = selectedNumber(await this.ask((context) => this.prompts.number({
+            message: "Maximum scroll swipes",
+            default: 20,
+            min: 1,
+            max: 30
+        }, context), signal), 1, 30);
+        return ProposedStepSchema.parse({
+            action: "scrollTo",
+            locator: target.locator,
+            container: container.locator,
+            direction,
+            maxSwipes,
+            ...options,
+            ...shared
+        });
+    }
+    async selectTarget(targets, message, signal) {
+        requireTargets(targets);
+        const id = selectedString(await this.ask((context) => this.prompts.select({
+            message,
+            choices: targets.map((target) => ({
+                name: target.label,
+                value: target.element.id
+            }))
+        }, context), signal), targets.map((target) => target.element.id));
+        const target = targets.find((candidate) => candidate.element.id === id);
+        if (target === undefined) {
+            throw new Error("Prompt returned an invalid selection");
+        }
+        return target;
+    }
+    async selectDirection(signal) {
+        const directions = ["up", "down", "left", "right"];
+        const value = await this.ask((context) => this.prompts.select({
+            message: "Swipe direction",
+            choices: directions.map((direction) => ({
+                name: direction,
+                value: direction
+            }))
+        }, context), signal);
+        return selectedString(value, directions);
+    }
+    async swipeOptions(signal) {
+        const distancePercent = selectedNumber(await this.ask((context) => this.prompts.number({
+            message: "Swipe distance (0–1)",
+            default: 0.6,
+            min: 0.01,
+            max: 1
+        }, context), signal), 0.01, 1);
+        const durationMs = selectedNumber(await this.ask((context) => this.prompts.number({
+            message: "Swipe duration (ms)",
+            default: 300,
+            min: 1
+        }, context), signal), 1);
+        return { distancePercent, durationMs };
+    }
+    assertLocalTty(operation) {
+        if (this.promptInput.isTTY !== true
+            || this.diagnostics.isTTY !== true) {
+            throw new Error(`${operation} requires local TTY input and diagnostics`);
+        }
+    }
+    async ask(operation, signal) {
+        this.throwIfCancelled(signal);
+        try {
+            return await operation(this.context(signal));
+        }
+        catch (error) {
+            if (signal?.aborted === true
+                || (error instanceof Error
+                    && (error.name === "AbortPromptError"
+                        || error.name === "ExitPromptError"))) {
+                throw new GenerationPromptCancelledError();
+            }
+            throw error;
+        }
+    }
+    throwIfCancelled(signal) {
+        if (signal?.aborted === true) {
+            throw new GenerationPromptCancelledError();
+        }
+    }
+    context(signal) {
+        return {
+            input: this.promptInput,
+            output: this.diagnostics,
+            ...(signal === undefined ? {} : { signal })
+        };
+    }
+}

package/dist/adapters/prompt/inquirer-init-prompt.d.ts

@@ -0,0 +1,32 @@
+import { checkbox } from "@inquirer/prompts";
+import { type AgentId } from "../../domain/init.js";
+import type { InitPromptPort } from "../../ports/init-prompt.js";
+export type InitInputStream = NodeJS.ReadableStream & {
+    isTTY?: boolean | undefined;
+};
+export type InitDiagnosticStream = NodeJS.WritableStream & {
+    isTTY?: boolean | undefined;
+};
+export type InitPromptContext = NonNullable<Parameters<typeof checkbox>[1]>;
+export interface CheckboxConfig {
+    message: string;
+    choices: readonly {
+        name: string;
+        value: string;
+        checked?: boolean;
+    }[];
+    validate?: ((choices: readonly {
+        value: string;
+    }[]) => boolean | string) | undefined;
+}
+export interface InitPromptFunctions {
+    checkbox: (config: CheckboxConfig, context: InitPromptContext) => Promise<string[]>;
+}
+export declare class InquirerInitPrompt implements InitPromptPort {
+    private readonly prompts;
+    private readonly promptInput;
+    private readonly diagnostics;
+    constructor(prompts?: InitPromptFunctions, promptInput?: InitInputStream, diagnostics?: InitDiagnosticStream);
+    selectAgents(): Promise<AgentId[]>;
+    private assertLocalTty;
+}

package/dist/adapters/prompt/inquirer-init-prompt.js

@@ -0,0 +1,55 @@
+import { checkbox } from "@inquirer/prompts";
+import { AGENT_REGISTRY } from "../../domain/init.js";
+import { InitPromptCancelledError } from "../../ports/init-prompt.js";
+const defaultPrompts = {
+    checkbox: async (config, context) => checkbox({
+        message: config.message,
+        choices: [...config.choices],
+        ...(config.validate === undefined
+            ? {}
+            : { validate: config.validate })
+    }, context)
+};
+export class InquirerInitPrompt {
+    prompts;
+    promptInput;
+    diagnostics;
+    constructor(prompts = defaultPrompts, promptInput = process.stdin, diagnostics = process.stderr) {
+        this.prompts = prompts;
+        this.promptInput = promptInput;
+        this.diagnostics = diagnostics;
+    }
+    async selectAgents() {
+        this.assertLocalTty();
+        try {
+            const selected = await this.prompts.checkbox({
+                message: "Select AI agents to install the TapHound Skill for:",
+                choices: AGENT_REGISTRY.map((agent) => ({
+                    name: agent.label,
+                    value: agent.id
+                })),
+                validate: (choices) => (choices.length > 0
+                    ? true
+                    : "Select at least one agent")
+            }, {
+                input: this.promptInput,
+                output: this.diagnostics
+            });
+            return selected;
+        }
+        catch (error) {
+            if (error instanceof Error
+                && (error.name === "AbortPromptError"
+                    || error.name === "ExitPromptError")) {
+                throw new InitPromptCancelledError();
+            }
+            throw error;
+        }
+    }
+    assertLocalTty() {
+        if (this.promptInput.isTTY !== true
+            || this.diagnostics.isTTY !== true) {
+            throw new Error("Agent selection requires local TTY input and output");
+        }
+    }
+}

package/dist/adapters/prompt/inquirer-recorder-prompt.d.ts

@@ -0,0 +1,47 @@
+import type { RecorderAction, RecorderPromptPort, RecorderTargetChoice, ScrollDecision, SwipeOptions } from "../../ports/recorder-prompt.js";
+interface SelectConfig {
+    message: string;
+    choices: readonly {
+        name: string;
+        value: string;
+    }[];
+}
+interface InputConfig {
+    message: string;
+    validate?: ((value: string) => boolean | string) | undefined;
+}
+interface ConfirmConfig {
+    message: string;
+    default: boolean;
+}
+interface NumberConfig {
+    message: string;
+    default: number;
+    min?: number | undefined;
+    max?: number | undefined;
+}
+export interface PromptFunctions {
+    select: (config: SelectConfig) => Promise<unknown>;
+    input: (config: InputConfig) => Promise<unknown>;
+    confirm: (config: ConfirmConfig) => Promise<unknown>;
+    number: (config: NumberConfig) => Promise<unknown>;
+}
+export interface DiagnosticStream {
+    write: (content: string) => unknown;
+}
+export declare class InquirerRecorderPrompt implements RecorderPromptPort {
+    private readonly prompts;
+    private readonly diagnostics;
+    constructor(prompts?: PromptFunctions, diagnostics?: DiagnosticStream);
+    selectAction(): Promise<RecorderAction>;
+    selectTarget(choices: readonly RecorderTargetChoice[]): Promise<string>;
+    inputText(): Promise<string>;
+    selectSwipeDirection(): Promise<"up" | "down" | "left" | "right">;
+    longClickDuration(): Promise<number>;
+    swipeOptions(): Promise<SwipeOptions>;
+    selectFallbackLabel(annotatedScreenshotPath: string): Promise<string | undefined>;
+    notifyFailure(message: string): Promise<void>;
+    selectScrollContainer(choices: readonly RecorderTargetChoice[]): Promise<string>;
+    scrollTargetDecision(choices: readonly RecorderTargetChoice[]): Promise<ScrollDecision>;
+}
+export {};