taphound 0.2.0-dev.11 → 0.2.0-dev.13

package/dist/adapters/appium/appium-ui-snapshot-provider.js

@@ -14,6 +14,14 @@ function loopbackEndpoint(value) {
     }
     return endpoint;
 }
+export class AppiumHttpError extends Error {
+    status;
+    constructor(status) {
+        super(`Appium HTTP ${String(status)}`);
+        this.status = status;
+        this.name = "AppiumHttpError";
+    }
+}
 export class FetchAppiumHttpClient {
     endpoint;
     constructor(endpoint) {
@@ -36,7 +44,7 @@ export class FetchAppiumHttpClient {
         });
         const payload = await response.json();
         if (!response.ok) {
-            throw new Error(`Appium HTTP ${String(response.status)}`);
+            throw new AppiumHttpError(response.status);
         }
         return { value: payload.value };
     }
@@ -47,18 +55,33 @@ function objectValue(value) {
     }
     return value;
 }
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * A page source request that timed out or hit a session Appium no longer
+ * knows (HTTP 404) points at a degraded UiAutomator2 session, not at the app.
+ */
+function degradedSession(error) {
+    return (error instanceof DOMException && error.name === "TimeoutError")
+        || (error instanceof AppiumHttpError && error.status === 404);
+}
 class AppiumUiSnapshotProvider {
     http;
     sessionId;
+    createSession;
     environment;
     descriptor;
+    onSessionRecovery;
     closePromise;
     lastSourceSignature;
-    constructor(http, sessionId, environment, descriptor) {
+    constructor(http, sessionId, createSession, environment, descriptor, onSessionRecovery) {
         this.http = http;
         this.sessionId = sessionId;
+        this.createSession = createSession;
         this.environment = environment;
         this.descriptor = descriptor;
+        this.onSessionRecovery = onSessionRecovery;
     }
     reset() {
         this.lastSourceSignature = undefined;
@@ -90,15 +113,24 @@ class AppiumUiSnapshotProvider {
         const startedAt = performance.now();
         let source;
         try {
-            source = (await this.http.request({
-                method: "GET",
-                path: `/session/${this.sessionId}/source`,
-                timeoutMs: options.timeoutMs,
-                ...(options.signal === undefined ? {} : { signal: options.signal })
-            })).value;
+            source = await this.pageSource(options);
         }
         catch (error) {
-            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, `Appium page source capture failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error, terminal: true });
+            if (options.signal?.aborted === true || !degradedSession(error)) {
+                throw this.captureFailure(errorText(error), error);
+            }
+            // Capture is read-only, so one retry on a fresh session cannot change
+            // what Replay observes; it only stops a degraded session from turning
+            // into a false verification failure.
+            try {
+                await this.recreateSession(options.signal);
+                source = await this.pageSource(options);
+                this.onSessionRecovery?.(true);
+            }
+            catch (retryError) {
+                this.onSessionRecovery?.(false);
+                throw this.captureFailure(`${errorText(error)}; retry on a recreated session failed: ${errorText(retryError)}`, retryError);
+            }
         }
         if (typeof source !== "string") {
             throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "Appium returned a non-string page source");
@@ -121,6 +153,34 @@ class AppiumUiSnapshotProvider {
             timing: {}
         });
     }
+    async pageSource(options) {
+        return (await this.http.request({
+            method: "GET",
+            path: `/session/${this.sessionId}/source`,
+            timeoutMs: options.timeoutMs,
+            ...(options.signal === undefined ? {} : { signal: options.signal })
+        })).value;
+    }
+    captureFailure(detail, cause) {
+        return new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, `Appium page source capture failed: ${detail}`, { cause, terminal: true });
+    }
+    async recreateSession(signal) {
+        await this.http.request({
+            method: "DELETE",
+            path: `/session/${this.sessionId}`,
+            timeoutMs: 2000
+        }).catch(() => undefined);
+        const sessionId = await this.createSession(signal);
+        if (this.closePromise !== undefined) {
+            await this.http.request({
+                method: "DELETE",
+                path: `/session/${sessionId}`,
+                timeoutMs: 5000
+            }).catch(() => undefined);
+            throw new Error("Appium UI snapshot provider is closed");
+        }
+        this.sessionId = sessionId;
+    }
     close() {
         this.closePromise ??= this.http.request({
             method: "DELETE",
@@ -135,6 +195,7 @@ export class AppiumUiSnapshotProviderFactory {
     endpoint;
     http;
     settings;
+    onSessionRecovery;
     constructor(runner, http, options = {}) {
         this.runner = runner;
         this.endpoint = loopbackEndpoint(options.endpoint ?? "http://127.0.0.1:4723/");
@@ -142,6 +203,7 @@ export class AppiumUiSnapshotProviderFactory {
         this.settings = {
             mapTestTagToResourceId: options.mapTestTagToResourceId ?? false
         };
+        this.onSessionRecovery = options.onSessionRecovery;
     }
     async probe(timeoutMs = 2000) {
         try {
@@ -158,7 +220,7 @@ export class AppiumUiSnapshotProviderFactory {
     }
     async open(options) {
         const environment = await readDeviceUiEnvironment(this.runner, "appium-uiautomator2", options);
-        let provisionalSessionId;
+        let provider;
         try {
             const status = objectValue((await this.http.request({
                 method: "GET",
@@ -170,41 +232,8 @@ export class AppiumUiSnapshotProviderFactory {
             const engineVersion = typeof build.version === "string"
                 ? build.version
                 : "unknown";
-            const created = objectValue((await this.http.request({
-                method: "POST",
-                path: "/session",
-                timeoutMs: options.timeoutMs,
-                body: {
-                    capabilities: {
-                        alwaysMatch: {
-                            platformName: "Android",
-                            "appium:automationName": "UiAutomator2",
-                            "appium:udid": options.deviceSerial,
-                            "appium:noReset": true,
-                            "appium:autoLaunch": false,
-                            "appium:autoGrantPermissions": false,
-                            "appium:fullReset": false,
-                            "appium:shouldTerminateApp": false
-                        },
-                        firstMatch: [{}]
-                    }
-                },
-                ...(options.signal === undefined ? {} : { signal: options.signal })
-            })).value);
-            const sessionId = typeof created.sessionId === "string"
-                ? created.sessionId
-                : undefined;
-            if (sessionId === undefined) {
-                throw new Error("Appium did not return a session id");
-            }
-            provisionalSessionId = sessionId;
-            await this.http.request({
-                method: "POST",
-                path: `/session/${sessionId}/appium/settings`,
-                timeoutMs: options.timeoutMs,
-                body: { settings: this.settings },
-                ...(options.signal === undefined ? {} : { signal: options.signal })
-            });
+            const createSession = (signal) => this.createSession(options.deviceSerial, options.timeoutMs, signal);
+            const sessionId = await createSession(options.signal);
             const descriptor = {
                 id: "appium-uiautomator2",
                 adapterVersion: "appium-uiautomator2-v1",
@@ -215,26 +244,66 @@ export class AppiumUiSnapshotProviderFactory {
                     capabilitiesVersion: 1
                 })).digest("hex")
             };
-            const provider = new AppiumUiSnapshotProvider(this.http, sessionId, environment, descriptor);
+            provider = new AppiumUiSnapshotProvider(this.http, sessionId, createSession, environment, descriptor, this.onSessionRecovery);
             await provider.capture({
                 reason: "evidence",
                 timeoutMs: options.timeoutMs,
                 ...(options.signal === undefined ? {} : { signal: options.signal })
             });
-            provisionalSessionId = undefined;
             return provider;
         }
         catch (error) {
-            if (provisionalSessionId !== undefined) {
-                await this.http.request({
-                    method: "DELETE",
-                    path: `/session/${provisionalSessionId}`,
-                    timeoutMs: 5000
-                }).catch(() => undefined);
-            }
+            await provider?.close().catch(() => undefined);
             if (error instanceof UiSnapshotError)
                 throw error;
             throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", "appium-uiautomator2", "Appium UiAutomator2 session could not be opened", { cause: error });
         }
     }
+    async createSession(deviceSerial, timeoutMs, signal) {
+        const created = objectValue((await this.http.request({
+            method: "POST",
+            path: "/session",
+            timeoutMs,
+            body: {
+                capabilities: {
+                    alwaysMatch: {
+                        platformName: "Android",
+                        "appium:automationName": "UiAutomator2",
+                        "appium:udid": deviceSerial,
+                        "appium:noReset": true,
+                        "appium:autoLaunch": false,
+                        "appium:autoGrantPermissions": false,
+                        "appium:fullReset": false,
+                        "appium:shouldTerminateApp": false
+                    },
+                    firstMatch: [{}]
+                }
+            },
+            ...(signal === undefined ? {} : { signal })
+        })).value);
+        const sessionId = typeof created.sessionId === "string"
+            ? created.sessionId
+            : undefined;
+        if (sessionId === undefined) {
+            throw new Error("Appium did not return a session id");
+        }
+        try {
+            await this.http.request({
+                method: "POST",
+                path: `/session/${sessionId}/appium/settings`,
+                timeoutMs,
+                body: { settings: this.settings },
+                ...(signal === undefined ? {} : { signal })
+            });
+        }
+        catch (error) {
+            await this.http.request({
+                method: "DELETE",
+                path: `/session/${sessionId}`,
+                timeoutMs: 5000
+            }).catch(() => undefined);
+            throw error;
+        }
+        return sessionId;
+    }
 }

package/dist/adapters/filesystem/diagnostics-journal.d.ts

@@ -0,0 +1,17 @@
+import { type CommandEvent } from "../../domain/diagnostics.js";
+import type { DiagnosticsJournal } from "../../ports/diagnostics.js";
+/**
+ * Appends one JSON line per invocation under `.taphound/build/log/`. It only
+ * writes where a command already initialized the ignored build layout (the
+ * build directory and `.taphound/.gitignore`), so read-only commands never
+ * create project files, and keeps the current file under `maxBytes` with one
+ * rotated predecessor.
+ */
+export declare class FileSystemDiagnosticsJournal implements DiagnosticsJournal {
+    private readonly maxBytes;
+    constructor(maxBytes?: number);
+    append(projectRoot: string, event: CommandEvent): Promise<void>;
+    readLines(projectRoot: string): Promise<readonly string[]>;
+    salt(projectRoot: string): Promise<Buffer>;
+    private ensureLogDirectory;
+}

package/dist/adapters/filesystem/diagnostics-journal.js

@@ -0,0 +1,130 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { CommandEventSchema, DIAGNOSTICS_EVENTS_FILE, DIAGNOSTICS_EVENTS_ROTATED_FILE, DIAGNOSTICS_SALT_FILE } from "../../domain/diagnostics.js";
+import { BUILD_DIR, BUILD_IGNORE_FILE, DIAGNOSTICS_LOG_DIR, TAPHOUND_DIR } from "../../domain/workspace.js";
+import { ensureBuildLayout } from "./workspace-layout.js";
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+function isMissing(error) {
+    return error?.code === "ENOENT";
+}
+async function isDirectory(path) {
+    try {
+        const stats = await lstat(path);
+        return stats.isDirectory() && !stats.isSymbolicLink();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+async function sizeOf(path) {
+    try {
+        return (await lstat(path)).size;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return 0;
+        throw error;
+    }
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissing(error))
+            return "";
+        throw error;
+    }
+}
+async function isFile(path) {
+    try {
+        const stats = await lstat(path);
+        return stats.isFile();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+/**
+ * Appends one JSON line per invocation under `.taphound/build/log/`. It only
+ * writes where a command already initialized the ignored build layout (the
+ * build directory and `.taphound/.gitignore`), so read-only commands never
+ * create project files, and keeps the current file under `maxBytes` with one
+ * rotated predecessor.
+ */
+export class FileSystemDiagnosticsJournal {
+    maxBytes;
+    constructor(maxBytes = DEFAULT_MAX_BYTES) {
+        this.maxBytes = maxBytes;
+    }
+    async append(projectRoot, event) {
+        if (!await isDirectory(join(projectRoot, BUILD_DIR))
+            || !await isFile(join(projectRoot, BUILD_IGNORE_FILE))) {
+            return;
+        }
+        const line = `${JSON.stringify(CommandEventSchema.parse(event))}\n`;
+        const directory = await this.ensureLogDirectory(projectRoot);
+        const current = join(directory, DIAGNOSTICS_EVENTS_FILE);
+        if (await sizeOf(current) + Buffer.byteLength(line) > this.maxBytes) {
+            await rename(current, join(directory, DIAGNOSTICS_EVENTS_ROTATED_FILE))
+                .catch((error) => {
+                if (!isMissing(error))
+                    throw error;
+            });
+        }
+        const handle = await open(current, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(line, "utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async readLines(projectRoot) {
+        const directory = join(projectRoot, DIAGNOSTICS_LOG_DIR);
+        const text = await readOptional(join(directory, DIAGNOSTICS_EVENTS_ROTATED_FILE))
+            + await readOptional(join(directory, DIAGNOSTICS_EVENTS_FILE));
+        return text.split("\n").filter((line) => line.trim().length > 0);
+    }
+    async salt(projectRoot) {
+        if (!await isDirectory(join(projectRoot, TAPHOUND_DIR))) {
+            throw Object.assign(new Error(`Not a TapHound project (no ${TAPHOUND_DIR}/ directory): ${projectRoot}`), { code: "CONFIG_INVALID" });
+        }
+        await ensureBuildLayout(projectRoot);
+        const path = join(await this.ensureLogDirectory(projectRoot), DIAGNOSTICS_SALT_FILE);
+        try {
+            const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            const salt = randomBytes(32);
+            try {
+                await handle.writeFile(salt);
+            }
+            finally {
+                await handle.close();
+            }
+            return salt;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const salt = await readFile(path);
+        if (salt.length < 16) {
+            throw new Error(`Diagnostics salt is unreadable: ${DIAGNOSTICS_LOG_DIR}/${DIAGNOSTICS_SALT_FILE}`);
+        }
+        return salt;
+    }
+    async ensureLogDirectory(projectRoot) {
+        const directory = join(projectRoot, DIAGNOSTICS_LOG_DIR);
+        await mkdir(directory, { recursive: true });
+        if (!await isDirectory(directory)) {
+            throw new Error(`${DIAGNOSTICS_LOG_DIR} is not a directory`);
+        }
+        return directory;
+    }
+}

package/dist/application/diagnostics/diagnostics-exporter.d.ts

@@ -0,0 +1,29 @@
+import { type DiagnosticsBundle } from "../../domain/diagnostics.js";
+import type { DiagnosticsJournal } from "../../ports/diagnostics.js";
+export interface DiagnosticsExporterDependencies {
+    journal: DiagnosticsJournal;
+    readJson: (path: string) => Promise<unknown>;
+    now: () => Date;
+    taphoundVersion: string;
+    host: DiagnosticsBundle["host"];
+}
+export interface DiagnosticsExportInput {
+    projectRoot: string;
+    /** Most recent journal events to include. */
+    eventLimit: number;
+    /** Most recent referenced runs to summarize. */
+    runLimit: number;
+}
+/**
+ * Builds a feedback bundle from the local journal and the reports it
+ * references. Only allowlisted structural facts survive: identifying strings
+ * become ordinal aliases or salted digests, and everything else is dropped.
+ * The result is validated against the strict bundle schema before return.
+ */
+export declare class DiagnosticsExporter {
+    private readonly dependencies;
+    constructor(dependencies: DiagnosticsExporterDependencies);
+    export(input: DiagnosticsExportInput): Promise<DiagnosticsBundle>;
+    private readConfig;
+    private readReport;
+}