taphound 0.2.0-dev.1

package/dist/adapters/adb/adb-adapter.js

@@ -0,0 +1,218 @@
+import { parseObservedActivityComponent } from "../../domain/activity.js";
+import { isAppProcessName } from "../../domain/app-process.js";
+const PROCESS_ROW = /^(\d+)\s+(\S+)$/;
+function deviceArgs(deviceSerial) {
+    return deviceSerial === undefined ? [] : ["-s", deviceSerial];
+}
+function assertCommandUsable(result, operation) {
+    if (result.spawnError !== undefined) {
+        throw new Error(`ADB ${operation} failed: ${result.spawnError}`);
+    }
+    if (result.timedOut) {
+        throw new Error(`ADB ${operation} timed out`);
+    }
+    if (result.cancelled) {
+        throw new Error(`ADB ${operation} was cancelled`);
+    }
+}
+function quoteRemoteShellArgument(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function inputTextChunks(text) {
+    const chunks = [];
+    let start = 0;
+    for (let index = 0; index < text.length - 1; index += 1) {
+        if (text[index] === "%" && text[index + 1] === "s") {
+            chunks.push(text.slice(start, index + 1));
+            start = index + 1;
+        }
+    }
+    chunks.push(text.slice(start));
+    return chunks;
+}
+export class AdbAdapter {
+    runner;
+    constructor(runner) {
+        this.runner = runner;
+    }
+    run(args, signal, timeoutMs) {
+        return this.runner.run({
+            executable: "adb",
+            args,
+            ...(signal === undefined ? {} : { signal }),
+            ...(timeoutMs === undefined ? {} : { timeoutMs })
+        });
+    }
+    async devices(signal) {
+        const result = await this.run(["devices"], signal);
+        return result.stdout
+            .split(/\r?\n/)
+            .slice(1)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            const [serial, status] = line.split(/\s+/, 2);
+            if (serial === undefined || status === undefined) {
+                throw new Error(`Invalid adb devices line: ${line}`);
+            }
+            return { serial, status };
+        });
+    }
+    async foregroundComponent(identity) {
+        const result = await this.run([
+            ...deviceArgs(identity.deviceSerial),
+            "shell",
+            "dumpsys",
+            "activity",
+            "activities"
+        ], identity.signal, identity.timeoutMs);
+        const resumed = result.stdout.split(/\r?\n/).find((line) => /\b(?:mResumedActivity|topResumedActivity|ResumedActivity)\s*[:=]/
+            .test(line));
+        const component = resumed === undefined
+            ? null
+            : /\b([A-Za-z_$][\w.$]*)\/(\.?[A-Za-z_$][\w.$]*)\b/.exec(resumed);
+        if (component?.[1] === undefined || component[2] === undefined) {
+            throw new Error("ADB did not report a resumed Activity");
+        }
+        return parseObservedActivityComponent(`${component[1]}/${component[2]}`);
+    }
+    async currentActivity(identity) {
+        return (await this.foregroundComponent(identity)).activity;
+    }
+    async isInstalled(identity) {
+        const result = await this.run([
+            ...deviceArgs(identity.deviceSerial),
+            "shell",
+            "pm",
+            "path",
+            identity.packageName
+        ], identity.signal, identity.timeoutMs);
+        assertCommandUsable(result, "pm path");
+        return /^package:/m.test(result.stdout);
+    }
+    launchActivity(options) {
+        return this.run([
+            ...deviceArgs(options.deviceSerial),
+            "shell",
+            "am",
+            "start",
+            "-W",
+            "-n",
+            `${options.packageName}/${options.activity}`
+        ], options.signal, options.timeoutMs);
+    }
+    forceStop(identity) {
+        return this.run([
+            ...deviceArgs(identity.deviceSerial),
+            "shell",
+            "am",
+            "force-stop",
+            identity.packageName
+        ], identity.signal, identity.timeoutMs);
+    }
+    async appProcesses(identity) {
+        const result = await this.run([
+            ...deviceArgs(identity.deviceSerial),
+            "shell",
+            "ps",
+            "-A",
+            "-o",
+            "PID,NAME"
+        ], identity.signal, identity.timeoutMs);
+        assertCommandUsable(result, "ps");
+        if (result.exitCode !== 0) {
+            throw new Error(`ADB ps failed: ${result.stderr.trim() || `exit ${String(result.exitCode)}`}`);
+        }
+        return result.stdout
+            .split(/\r?\n/)
+            .flatMap((line) => {
+            const row = PROCESS_ROW.exec(line.trim());
+            if (row?.[1] === undefined || row[2] === undefined) {
+                return [];
+            }
+            if (!isAppProcessName(row[2], identity.packageName)) {
+                return [];
+            }
+            const pid = Number(row[1]);
+            if (!Number.isSafeInteger(pid) || pid <= 0) {
+                throw new Error(`Invalid PID from adb ps: ${row[1]}`);
+            }
+            return [{ pid, name: row[2] }];
+        })
+            .sort((left, right) => left.pid - right.pid);
+    }
+    tap(point, deviceSerial, signal) {
+        return this.run([
+            ...deviceArgs(deviceSerial),
+            "shell",
+            "input",
+            "tap",
+            String(point.x),
+            String(point.y)
+        ], signal);
+    }
+    longClick(point, durationMs, deviceSerial, signal) {
+        return this.swipe(point, point, durationMs, deviceSerial, signal);
+    }
+    swipe(from, to, durationMs, deviceSerial, signal) {
+        return this.run([
+            ...deviceArgs(deviceSerial),
+            "shell",
+            "input",
+            "swipe",
+            String(from.x),
+            String(from.y),
+            String(to.x),
+            String(to.y),
+            String(durationMs)
+        ], signal);
+    }
+    back(deviceSerial, signal) {
+        return this.run([
+            ...deviceArgs(deviceSerial),
+            "shell",
+            "input",
+            "keyevent",
+            "BACK"
+        ], signal);
+    }
+    async inputText(text, deviceSerial, signal) {
+        let result;
+        for (const chunk of inputTextChunks(text)) {
+            result = await this.run([
+                ...deviceArgs(deviceSerial),
+                "shell",
+                "input",
+                "text",
+                quoteRemoteShellArgument(chunk)
+            ], signal);
+            if (result.exitCode !== 0
+                || result.timedOut
+                || result.cancelled
+                || result.spawnError !== undefined) {
+                return result;
+            }
+        }
+        if (result === undefined) {
+            throw new Error("ADB input text produced no command");
+        }
+        return result;
+    }
+    startLogcat(options) {
+        return this.runner.start({
+            executable: "adb",
+            args: [
+                ...deviceArgs(options.deviceSerial),
+                "logcat",
+                "-v",
+                "threadtime"
+            ],
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        }, {
+            onStdoutLine: options.onStdoutLine,
+            ...(options.onStderrLine === undefined
+                ? {}
+                : { onStderrLine: options.onStderrLine })
+        });
+    }
+}

package/dist/adapters/android-cli/android-cli-adapter.d.ts

@@ -0,0 +1,11 @@
+import type { AndroidCliPort, CaptureScreenOptions, DeviceCommandOptions, Point } from "../../ports/android-cli.js";
+import type { CommandResult, ProcessRunner } from "../../ports/process-runner.js";
+import { parseLayout, parseLayoutDiff } from "./layout-parser.js";
+export declare class AndroidCliAdapter implements AndroidCliPort {
+    private readonly runner;
+    constructor(runner: ProcessRunner);
+    layout(options: DeviceCommandOptions): Promise<ReturnType<typeof parseLayout>>;
+    layoutDiff(options: DeviceCommandOptions): Promise<ReturnType<typeof parseLayoutDiff>>;
+    captureScreen(options: CaptureScreenOptions): Promise<CommandResult>;
+    resolveScreen(screenshotPath: string, label: string, signal?: AbortSignal): Promise<Point>;
+}

package/dist/adapters/android-cli/android-cli-adapter.js

@@ -0,0 +1,64 @@
+import { parseLayout, parseLayoutDiff } from "./layout-parser.js";
+function commandSpec(args, signal, timeoutMs) {
+    return {
+        executable: "android",
+        args,
+        ...(signal === undefined ? {} : { signal }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs })
+    };
+}
+function assertSuccess(result, operation) {
+    if (result.exitCode !== 0) {
+        throw new Error(`Android CLI ${operation} failed: ${result.stderr.trim()}`);
+    }
+}
+export class AndroidCliAdapter {
+    runner;
+    constructor(runner) {
+        this.runner = runner;
+    }
+    async layout(options) {
+        const result = await this.runner.run(commandSpec([
+            "layout",
+            `--device=${options.deviceSerial}`
+        ], options.signal, options.timeoutMs));
+        assertSuccess(result, "layout");
+        return parseLayout(result.stdout);
+    }
+    async layoutDiff(options) {
+        const result = await this.runner.run(commandSpec([
+            "layout",
+            "--diff",
+            `--device=${options.deviceSerial}`
+        ], options.signal, options.timeoutMs));
+        assertSuccess(result, "layout --diff");
+        return parseLayoutDiff(result.stdout);
+    }
+    captureScreen(options) {
+        return this.runner.run(commandSpec([
+            "screen",
+            "capture",
+            `--output=${options.outputPath}`,
+            ...(options.annotate === true ? ["--annotate"] : []),
+            `--device=${options.deviceSerial}`
+        ], options.signal, options.timeoutMs));
+    }
+    async resolveScreen(screenshotPath, label, signal) {
+        const result = await this.runner.run(commandSpec([
+            "screen",
+            "resolve",
+            `--screenshot=${screenshotPath}`,
+            `--string=${label}`
+        ], signal));
+        assertSuccess(result, "screen resolve");
+        const coordinates = result.stdout.match(/-?\d+/g)?.map(Number);
+        if (coordinates?.length !== 2) {
+            throw new Error("Android CLI screen resolve returned invalid coordinates");
+        }
+        const [x, y] = coordinates;
+        if (x === undefined || y === undefined || x < 0 || y < 0) {
+            throw new Error("Android CLI screen resolve returned invalid coordinates");
+        }
+        return { x, y };
+    }
+}

package/dist/adapters/android-cli/layout-parser.d.ts

@@ -0,0 +1,3 @@
+import { type LayoutElement } from "../../domain/layout.js";
+export declare function parseLayout(stdout: string): readonly LayoutElement[];
+export declare function parseLayoutDiff(stdout: string): readonly unknown[];

package/dist/adapters/android-cli/layout-parser.js

@@ -0,0 +1,174 @@
+import { BoundsSchema, LayoutPointSchema } from "../../domain/layout.js";
+function parseJson(stdout, label) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (error) {
+        throw new Error(`Invalid Android ${label} JSON`, { cause: error });
+    }
+}
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid Android Layout element");
+    }
+    return value;
+}
+function optionalString(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function optionalBoolean(record, key) {
+    const value = record[key];
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    return undefined;
+}
+function parseBounds(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === "string") {
+        const match = /^\[(\d+),(\d+)]\[(\d+),(\d+)]$/.exec(value);
+        if (match === null) {
+            throw new Error("Invalid Android Layout bounds");
+        }
+        return BoundsSchema.parse({
+            left: Number(match[1]),
+            top: Number(match[2]),
+            right: Number(match[3]),
+            bottom: Number(match[4])
+        });
+    }
+    return BoundsSchema.parse(value);
+}
+function parseCenter(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value === "string") {
+        const match = /^[[(]\s*(\d+)\s*,\s*(\d+)\s*[)\]]/.exec(value);
+        if (match === null) {
+            throw new Error("Invalid Android Layout center");
+        }
+        return LayoutPointSchema.parse({
+            x: Number(match[1]),
+            y: Number(match[2])
+        });
+    }
+    return LayoutPointSchema.parse(value);
+}
+function stringSet(record, key) {
+    const value = record[key];
+    if (value === undefined) {
+        return new Set();
+    }
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid Android Layout ${key}`);
+    }
+    return new Set(value);
+}
+function elementId(record, path) {
+    const explicitId = record.id;
+    if (typeof explicitId === "string" || typeof explicitId === "number") {
+        return String(explicitId);
+    }
+    const serializerKey = record.key;
+    return typeof serializerKey === "string" || typeof serializerKey === "number"
+        ? `${String(serializerKey)}:${path}`
+        : path;
+}
+function parseElement(value, path) {
+    const record = asRecord(value);
+    if (optionalBoolean(record, "off-screen") === true) {
+        return undefined;
+    }
+    const childrenValue = record.children ?? [];
+    if (!Array.isArray(childrenValue)) {
+        throw new Error("Invalid Android Layout children");
+    }
+    const resourceId = optionalString(record, "resourceId", "resource-id");
+    const text = optionalString(record, "text");
+    const contentDescription = optionalString(record, "contentDescription", "content-desc");
+    const interactions = stringSet(record, "interactions");
+    const clickable = optionalBoolean(record, "clickable")
+        ?? (interactions.has("clickable") ? true : undefined);
+    const longClickable = optionalBoolean(record, "longClickable")
+        ?? optionalBoolean(record, "long-clickable")
+        ?? (interactions.has("long-clickable") ? true : undefined);
+    const scrollable = optionalBoolean(record, "scrollable")
+        ?? (interactions.has("scrollable") ? true : undefined);
+    const focusable = interactions.has("focusable") ? true : undefined;
+    const state = stringSet(record, "state");
+    const focused = state.has("focused") ? true : undefined;
+    const bounds = parseBounds(record.bounds);
+    const parsedCenter = parseCenter(record.center);
+    const center = parsedCenter ?? (bounds === undefined
+        ? undefined
+        : {
+            x: Math.round((bounds.left + bounds.right) / 2),
+            y: Math.round((bounds.top + bounds.bottom) / 2)
+        });
+    if (center === undefined) {
+        throw new Error("Android Layout element has no visible center or bounds");
+    }
+    const children = childrenValue.flatMap((child, index) => {
+        const parsed = parseElement(child, `${path}/${String(index)}`);
+        return parsed === undefined ? [] : [parsed];
+    });
+    return {
+        id: elementId(record, path),
+        ...(resourceId === undefined ? {} : { resourceId }),
+        ...(text === undefined ? {} : { text }),
+        ...(contentDescription === undefined ? {} : { contentDescription }),
+        ...(clickable === undefined ? {} : { clickable }),
+        ...(longClickable === undefined ? {} : { longClickable }),
+        ...(scrollable === undefined ? {} : { scrollable }),
+        ...(focusable === undefined ? {} : { focusable }),
+        ...(focused === undefined ? {} : { focused }),
+        enabled: optionalBoolean(record, "enabled") ?? true,
+        center,
+        ...(bounds === undefined ? {} : { bounds }),
+        children
+    };
+}
+export function parseLayout(stdout) {
+    const parsed = parseJson(stdout, "Layout");
+    try {
+        if (Array.isArray(parsed)) {
+            return parsed.flatMap((element, index) => {
+                const normalized = parseElement(element, String(index));
+                return normalized === undefined ? [] : [normalized];
+            });
+        }
+        const normalized = parseElement(parsed, "0");
+        return normalized === undefined ? [] : [normalized];
+    }
+    catch (error) {
+        throw new Error("Invalid Android Layout structure", { cause: error });
+    }
+}
+export function parseLayoutDiff(stdout) {
+    const parsed = parseJson(stdout, "Layout Diff");
+    if (Array.isArray(parsed)) {
+        return parsed;
+    }
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const record = parsed;
+        const added = Array.isArray(record.added) ? record.added : [];
+        const modified = Array.isArray(record.modified) ? record.modified : [];
+        return [...added, ...modified];
+    }
+    throw new Error("Invalid Android Layout Diff structure");
+}

package/dist/adapters/clock/system-clock.d.ts

@@ -0,0 +1,5 @@
+import type { Clock } from "../../ports/clock.js";
+export declare class SystemClock implements Clock {
+    readonly now: () => number;
+    readonly sleep: (durationMs: number, signal?: AbortSignal) => Promise<void>;
+}

package/dist/adapters/clock/system-clock.js

@@ -0,0 +1,13 @@
+import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
+export class SystemClock {
+    now = () => performance.now();
+    sleep = (durationMs, signal) => {
+        if (signal?.aborted === true) {
+            return Promise.reject(signal.reason instanceof Error
+                ? signal.reason
+                : new Error("Operation aborted"));
+        }
+        return delay(durationMs, undefined, { signal });
+    };
+}

package/dist/adapters/filesystem/artifact-store.d.ts

@@ -0,0 +1,4 @@
+import type { ArtifactSession, ArtifactStore } from "../../ports/artifact-store.js";
+export declare class FileSystemArtifactStore implements ArtifactStore {
+    readonly begin: (baseDirectory: string, runDirectoryName: string) => Promise<ArtifactSession>;
+}

package/dist/adapters/filesystem/artifact-store.js

@@ -0,0 +1,73 @@
+import { access, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+function assertRunDirectoryName(name) {
+    if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+        throw new Error("Invalid artifact run directory name");
+    }
+}
+function safePath(root, relativePath) {
+    const candidate = resolve(root, relativePath);
+    const fromRoot = relative(root, candidate);
+    if (fromRoot.length === 0
+        || fromRoot.startsWith("..")
+        || isAbsolute(fromRoot)) {
+        throw new Error(`Invalid artifact path: ${relativePath}`);
+    }
+    return candidate;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+class FileSystemArtifactSession {
+    temporaryDirectory;
+    finalDirectory;
+    published = false;
+    discarded = false;
+    constructor(temporaryDirectory, finalDirectory) {
+        this.temporaryDirectory = temporaryDirectory;
+        this.finalDirectory = finalDirectory;
+    }
+    path = (relativePath) => (safePath(this.published ? this.finalDirectory : this.temporaryDirectory, relativePath));
+    writeText = async (relativePath, content) => {
+        this.assertWritable();
+        const outputPath = safePath(this.temporaryDirectory, relativePath);
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, content, "utf8");
+    };
+    writeJson = (relativePath, value) => this.writeText(relativePath, `${JSON.stringify(value, null, 2)}\n`);
+    publish = async () => {
+        this.assertWritable();
+        if (await exists(this.finalDirectory)) {
+            throw new Error(`Artifact run directory already exists: ${this.finalDirectory}`);
+        }
+        await rename(this.temporaryDirectory, this.finalDirectory);
+        this.published = true;
+        return this.finalDirectory;
+    };
+    discard = async () => {
+        if (!this.published && !this.discarded) {
+            await rm(this.temporaryDirectory, { recursive: true, force: true });
+            this.discarded = true;
+        }
+    };
+    assertWritable() {
+        if (this.published || this.discarded) {
+            throw new Error("Artifact session is no longer writable");
+        }
+    }
+}
+export class FileSystemArtifactStore {
+    begin = async (baseDirectory, runDirectoryName) => {
+        assertRunDirectoryName(runDirectoryName);
+        await mkdir(baseDirectory, { recursive: true });
+        const temporaryDirectory = await mkdtemp(join(baseDirectory, `.${runDirectoryName}.tmp-`));
+        await mkdir(join(temporaryDirectory, "steps"), { recursive: true });
+        return new FileSystemArtifactSession(temporaryDirectory, join(baseDirectory, runDirectoryName));
+    };
+}

package/dist/adapters/filesystem/generation-meta-writer.d.ts

@@ -0,0 +1,16 @@
+import { type GenerationMeta } from "../../domain/generation.js";
+import type { ProjectBoundGenerationMetaWriterPort } from "../../ports/generation-meta-writer.js";
+import type { ProjectBoundPath } from "../../ports/project-bound-file.js";
+import { type ProjectBoundFileHooks } from "./project-bound-file.js";
+export interface FileSystemGenerationMetaWriterOptions {
+    beforeBoundInstall?: ProjectBoundFileHooks["beforeInstall"];
+}
+export declare class FileSystemGenerationMetaWriter implements ProjectBoundGenerationMetaWriterPort {
+    private readonly options;
+    constructor(options?: FileSystemGenerationMetaWriterOptions);
+    write(outputPath: string, input: GenerationMeta): Promise<void>;
+    writeProjectBound(input: ProjectBoundPath & {
+        meta: GenerationMeta;
+    }): Promise<void>;
+    readProjectBound(input: ProjectBoundPath): Promise<Buffer>;
+}

package/dist/adapters/filesystem/generation-meta-writer.js

@@ -0,0 +1,34 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { GenerationMetaSchema } from "../../domain/generation.js";
+import { readProjectBoundFile, writeProjectBoundText } from "./project-bound-file.js";
+export class FileSystemGenerationMetaWriter {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async write(outputPath, input) {
+        const meta = GenerationMetaSchema.parse(input);
+        const directory = dirname(outputPath);
+        const temporaryPath = join(directory, `.${basename(outputPath)}.${randomUUID()}.tmp`);
+        await mkdir(directory, { recursive: true });
+        try {
+            await writeFile(temporaryPath, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+            await rename(temporaryPath, outputPath);
+        }
+        catch (error) {
+            await rm(temporaryPath, { force: true });
+            throw error;
+        }
+    }
+    async writeProjectBound(input) {
+        const meta = GenerationMetaSchema.parse(input.meta);
+        await writeProjectBoundText(input, `${JSON.stringify(meta, null, 2)}\n`, this.options.beforeBoundInstall === undefined
+            ? {}
+            : { beforeInstall: this.options.beforeBoundInstall });
+    }
+    async readProjectBound(input) {
+        return readProjectBoundFile(input);
+    }
+}