taphound 0.2.0-dev.1 → 0.2.0-dev.11

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

@@ -0,0 +1,240 @@
+import { createHash } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { parseAppiumPageSource } from "../adb/ui-automator-parser.js";
+import { readDeviceUiEnvironment } from "../ui/device-ui-environment.js";
+import { UiSnapshotError } from "../ui/ui-snapshot-error.js";
+import { snapshotFromCapture } from "../ui/ui-snapshot-support.js";
+function loopbackEndpoint(value) {
+    const endpoint = new URL(value);
+    if (endpoint.protocol !== "http:"
+        || !["127.0.0.1", "localhost", "[::1]"].includes(endpoint.hostname)
+        || endpoint.username !== ""
+        || endpoint.password !== "") {
+        throw new Error("Appium endpoint must be an unauthenticated loopback HTTP URL");
+    }
+    return endpoint;
+}
+export class FetchAppiumHttpClient {
+    endpoint;
+    constructor(endpoint) {
+        this.endpoint = endpoint;
+    }
+    async request(input) {
+        const timeout = AbortSignal.timeout(Math.trunc(input.timeoutMs));
+        const signal = input.signal === undefined
+            ? timeout
+            : AbortSignal.any([input.signal, timeout]);
+        const response = await fetch(new URL(input.path.slice(1), this.endpoint), {
+            method: input.method,
+            ...(input.body === undefined
+                ? {}
+                : {
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(input.body)
+                }),
+            signal
+        });
+        const payload = await response.json();
+        if (!response.ok) {
+            throw new Error(`Appium HTTP ${String(response.status)}`);
+        }
+        return { value: payload.value };
+    }
+}
+function objectValue(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Appium returned an invalid response");
+    }
+    return value;
+}
+class AppiumUiSnapshotProvider {
+    http;
+    sessionId;
+    environment;
+    descriptor;
+    closePromise;
+    lastSourceSignature;
+    constructor(http, sessionId, environment, descriptor) {
+        this.http = http;
+        this.sessionId = sessionId;
+        this.environment = environment;
+        this.descriptor = descriptor;
+    }
+    reset() {
+        this.lastSourceSignature = undefined;
+    }
+    async sample(options) {
+        void options.deviceSerial;
+        const startedAt = performance.now();
+        const snapshot = await this.capture({
+            reason: "idle",
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            timeoutMs: options.timeoutMs ?? 5000
+        });
+        const signature = createHash("sha256")
+            .update(JSON.stringify(snapshot.roots))
+            .digest("hex");
+        const previous = this.lastSourceSignature;
+        this.lastSourceSignature = signature;
+        return {
+            changes: previous === signature ? [] : [{ layoutSha256: signature }],
+            layout: snapshot.roots,
+            backend: "uiautomator",
+            durationMs: performance.now() - startedAt
+        };
+    }
+    async capture(options) {
+        if (this.closePromise !== undefined) {
+            throw new UiSnapshotError("UI_SNAPSHOT_FAILED", this.descriptor.id, "Appium UI snapshot provider is closed");
+        }
+        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;
+        }
+        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 (typeof source !== "string") {
+            throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "Appium returned a non-string page source");
+        }
+        let roots;
+        try {
+            roots = parseAppiumPageSource(source);
+        }
+        catch (error) {
+            throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "Appium returned malformed page source", { cause: error });
+        }
+        if (roots.length === 0) {
+            throw new UiSnapshotError("UI_SNAPSHOT_INVALID", this.descriptor.id, "Appium returned an empty layout");
+        }
+        return snapshotFromCapture({
+            startedAt,
+            roots,
+            backend: this.descriptor,
+            viewport: this.environment.viewport,
+            timing: {}
+        });
+    }
+    close() {
+        this.closePromise ??= this.http.request({
+            method: "DELETE",
+            path: `/session/${this.sessionId}`,
+            timeoutMs: 5000
+        }).then(() => undefined);
+        return this.closePromise;
+    }
+}
+export class AppiumUiSnapshotProviderFactory {
+    runner;
+    endpoint;
+    http;
+    settings;
+    constructor(runner, http, options = {}) {
+        this.runner = runner;
+        this.endpoint = loopbackEndpoint(options.endpoint ?? "http://127.0.0.1:4723/");
+        this.http = http ?? new FetchAppiumHttpClient(this.endpoint);
+        this.settings = {
+            mapTestTagToResourceId: options.mapTestTagToResourceId ?? false
+        };
+    }
+    async probe(timeoutMs = 2000) {
+        try {
+            const response = await this.http.request({
+                method: "GET",
+                path: "/status",
+                timeoutMs
+            });
+            return response.value !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    async open(options) {
+        const environment = await readDeviceUiEnvironment(this.runner, "appium-uiautomator2", options);
+        let provisionalSessionId;
+        try {
+            const status = objectValue((await this.http.request({
+                method: "GET",
+                path: "/status",
+                timeoutMs: options.timeoutMs,
+                ...(options.signal === undefined ? {} : { signal: options.signal })
+            })).value);
+            const build = status.build === undefined ? {} : objectValue(status.build);
+            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 descriptor = {
+                id: "appium-uiautomator2",
+                adapterVersion: "appium-uiautomator2-v1",
+                engineVersion,
+                configSha256: createHash("sha256").update(JSON.stringify({
+                    endpoint: this.endpoint.origin,
+                    settings: this.settings,
+                    capabilitiesVersion: 1
+                })).digest("hex")
+            };
+            const provider = new AppiumUiSnapshotProvider(this.http, sessionId, environment, descriptor);
+            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);
+            }
+            if (error instanceof UiSnapshotError)
+                throw error;
+            throw new UiSnapshotError("UI_BACKEND_UNAVAILABLE", "appium-uiautomator2", "Appium UiAutomator2 session could not be opened", { cause: error });
+        }
+    }
+}

package/dist/adapters/camera/camera-probe-adapter.d.ts

@@ -0,0 +1,18 @@
+import { type RuntimeSessionOpener } from "../../ports/runtime-backend.js";
+import type { RuntimeSessionPortViewsFactory } from "../../ports/runtime-session-ports.js";
+import type { UiSnapshotProviderFactory } from "../../ports/ui-snapshot.js";
+import type { CameraProbeInput, CameraProbePort, CameraProbeResult } from "../../ports/camera-probe.js";
+export interface CameraProbeAdapterDeps {
+    sessions: RuntimeSessionOpener;
+    sessionPorts: RuntimeSessionPortViewsFactory;
+    uiSnapshots: UiSnapshotProviderFactory;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+export declare class CameraProbeAdapter implements CameraProbePort {
+    private readonly deps;
+    constructor(deps: CameraProbeAdapterDeps);
+    probe(input: CameraProbeInput): Promise<CameraProbeResult>;
+    private probeWith;
+    private waitForStableForeground;
+}

package/dist/adapters/camera/camera-probe-adapter.js

@@ -0,0 +1,286 @@
+import { withRuntimeSession } from "../../ports/runtime-backend.js";
+import { CameraProbeError } from "../../ports/camera-probe.js";
+const SHUTTER_KEYWORDS = ["shutter", "快门", "capture", "拍照"];
+const CONFIRM_KEYWORDS = [
+    "done",
+    "confirm",
+    "accept",
+    "ok",
+    "save",
+    "checkmark",
+    "完成",
+    "确认",
+    "接受",
+    "确定",
+    "保存"
+];
+const CONFIRM_RESOURCE_ID_SUBSTRINGS = ["done", "confirm", "accept", "save", "ok"];
+const SHUTTER_RESOURCE_ID_SUBSTRINGS = ["shutter"];
+const IMAGE_CAPTURE_ACTION = "android.media.action.IMAGE_CAPTURE";
+const CAMERA_FOREGROUND_TIMEOUT_MS = 8000;
+const CAMERA_FOREGROUND_POLL_INTERVAL_MS = 500;
+const LAYOUT_SETTLE_MS = 1500;
+const RESOLVER_KEYWORDS = ["resolver", "chooser"];
+const AOSP_CAMERA_PACKAGES = ["com.android.camera", "com.android.camera2"];
+function flatten(elements) {
+    const result = [];
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            result.push(node);
+            visit(node.children);
+        }
+    };
+    visit(elements);
+    return result;
+}
+function matchesAnyKeyword(value, keywords) {
+    const lower = value.toLowerCase();
+    return keywords.some((keyword) => lower.includes(keyword.toLowerCase()));
+}
+function resourceEntryName(resourceId) {
+    const separator = resourceId.lastIndexOf(":id/");
+    return (separator >= 0 ? resourceId.slice(separator + 4) : resourceId).toLowerCase();
+}
+function matchesResourceId(resourceId, token) {
+    const entryName = resourceEntryName(resourceId);
+    const tokens = entryName.split(/[^a-z0-9]+/u);
+    return tokens.includes(token.toLowerCase());
+}
+function selectByResourceIdPriority(candidates, resourceIdTokens) {
+    for (const token of resourceIdTokens) {
+        const matches = candidates.filter((node) => (node.resourceId !== undefined
+            && matchesResourceId(node.resourceId, token)));
+        if (matches.length > 0) {
+            return matches;
+        }
+    }
+    return [];
+}
+function buttonMatch(node) {
+    if (node.resourceId === undefined) {
+        return "no_resource_id";
+    }
+    return {
+        resourceId: node.resourceId,
+        ...(node.contentDescription === undefined
+            ? {}
+            : { contentDescription: node.contentDescription })
+    };
+}
+function findButton(layout, keywords, resourceIdSubstrings) {
+    const eligible = flatten(layout).filter((node) => node.enabled && node.clickable === true);
+    const candidates = eligible.filter((node) => (node.contentDescription !== undefined
+        && matchesAnyKeyword(node.contentDescription, keywords)));
+    if (candidates.length === 0) {
+        const byResourceId = selectByResourceIdPriority(eligible, resourceIdSubstrings);
+        if (byResourceId.length === 0) {
+            return "none";
+        }
+        if (byResourceId.length === 1) {
+            const node = byResourceId[0];
+            return node === undefined ? "none" : buttonMatch(node);
+        }
+        return "ambiguous";
+    }
+    if (candidates.length === 1) {
+        const node = candidates[0];
+        return node === undefined ? "none" : buttonMatch(node);
+    }
+    const byResourceId = selectByResourceIdPriority(candidates, resourceIdSubstrings);
+    if (byResourceId.length === 1) {
+        const node = byResourceId[0];
+        return node === undefined ? "none" : buttonMatch(node);
+    }
+    return "ambiguous";
+}
+function centerOf(element) {
+    if (element.center !== undefined) {
+        return element.center;
+    }
+    if (element.bounds !== undefined) {
+        return {
+            x: Math.round((element.bounds.left + element.bounds.right) / 2),
+            y: Math.round((element.bounds.top + element.bounds.bottom) / 2)
+        };
+    }
+    throw new CameraProbeError("ALIGN_SHUTTER_NOT_FOUND", "Shutter element has no center or bounds");
+}
+function isResolverOrChooser(packageName) {
+    const lower = packageName.toLowerCase();
+    return RESOLVER_KEYWORDS.some((keyword) => lower.includes(keyword));
+}
+function isAospCameraPackage(packageName) {
+    return AOSP_CAMERA_PACKAGES.includes(packageName);
+}
+function deviceIdentity(deviceSerial, signal) {
+    return {
+        packageName: "",
+        deviceSerial,
+        ...(signal === undefined ? {} : { signal })
+    };
+}
+export class CameraProbeAdapter {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    probe(input) {
+        return withRuntimeSession(this.deps.sessions, input.deviceSerial, input.signal, (session) => this.probeWith(this.deps.sessionPorts(session).adb, input));
+    }
+    async probeWith(adb, input) {
+        const { deviceSerial, signal } = input;
+        let cameraPackage;
+        const uiSnapshotProvider = await this.deps.uiSnapshots.open({
+            deviceSerial,
+            timeoutMs: CAMERA_FOREGROUND_TIMEOUT_MS,
+            ...(signal === undefined ? {} : { signal })
+        });
+        try {
+            let preForeground = await adb.foregroundComponent(deviceIdentity(deviceSerial, signal));
+            if (isAospCameraPackage(preForeground.packageName)
+                || isResolverOrChooser(preForeground.packageName)) {
+                await adb.forceStop({
+                    packageName: preForeground.packageName,
+                    deviceSerial,
+                    ...(signal === undefined ? {} : { signal })
+                });
+                preForeground = await adb.foregroundComponent(deviceIdentity(deviceSerial, signal));
+            }
+            const startResult = await adb.startActivityByIntent({
+                action: IMAGE_CAPTURE_ACTION,
+                deviceSerial,
+                ...(signal === undefined ? {} : { signal })
+            });
+            if (startResult.exitCode !== 0) {
+                throw new CameraProbeError("ALIGN_CAMERA_INTENT_FAILED", `am start exited with code ${String(startResult.exitCode)}: ${startResult.stderr || startResult.stdout}`);
+            }
+            const deadline = this.deps.now() + CAMERA_FOREGROUND_TIMEOUT_MS;
+            let current = preForeground;
+            while (this.deps.now() < deadline) {
+                current = await adb.foregroundComponent(deviceIdentity(deviceSerial, signal));
+                if (isResolverOrChooser(current.packageName)) {
+                    throw new CameraProbeError("ALIGN_CAMERA_INTENT_FAILED", `IMAGE_CAPTURE landed on system resolver/chooser (${current.packageName}); set a default camera app`);
+                }
+                if (current.packageName !== preForeground.packageName) {
+                    cameraPackage = current.packageName;
+                    break;
+                }
+                await this.deps.sleep(CAMERA_FOREGROUND_POLL_INTERVAL_MS);
+            }
+            if (cameraPackage === undefined) {
+                throw new CameraProbeError("ALIGN_CAMERA_NOT_LAUNCHED", "Camera package did not become foreground within 8s");
+            }
+            await uiSnapshotProvider.capture({
+                reason: "locate",
+                timeoutMs: CAMERA_FOREGROUND_TIMEOUT_MS,
+                ...(signal === undefined ? {} : { signal })
+            });
+            await this.deps.sleep(LAYOUT_SETTLE_MS);
+            const initialLayout = (await uiSnapshotProvider.capture({
+                reason: "locate",
+                timeoutMs: CAMERA_FOREGROUND_TIMEOUT_MS,
+                ...(signal === undefined ? {} : { signal })
+            })).roots;
+            const preShutterForeground = await this.waitForStableForeground(adb, deviceSerial, signal);
+            if (preShutterForeground.packageName !== cameraPackage) {
+                throw new CameraProbeError("ALIGN_CAMERA_NOT_LAUNCHED", `Camera package left the foreground before shutter discovery: ${preShutterForeground.packageName}`);
+            }
+            const shutter = findButton(initialLayout, SHUTTER_KEYWORDS, SHUTTER_RESOURCE_ID_SUBSTRINGS);
+            if (shutter === "none") {
+                throw new CameraProbeError("ALIGN_SHUTTER_NOT_FOUND", "No enabled clickable element matched shutter contentDescription or resourceId");
+            }
+            if (shutter === "ambiguous") {
+                throw new CameraProbeError("ALIGN_SHUTTER_AMBIGUOUS", "Multiple shutter candidates could not be disambiguated by resourceId");
+            }
+            if (shutter === "no_resource_id") {
+                throw new CameraProbeError("ALIGN_SHUTTER_NO_RESOURCE_ID", "Shutter candidate has no resourceId for deterministic replay");
+            }
+            const shutterElement = flatten(initialLayout).find((node) => node.resourceId === shutter.resourceId);
+            if (shutterElement === undefined) {
+                throw new CameraProbeError("ALIGN_SHUTTER_NOT_FOUND", `Shutter resourceId ${shutter.resourceId} not present in layout`);
+            }
+            await adb.tap(centerOf(shutterElement), deviceSerial, signal);
+            await uiSnapshotProvider.capture({
+                reason: "locate",
+                timeoutMs: CAMERA_FOREGROUND_TIMEOUT_MS,
+                ...(signal === undefined ? {} : { signal })
+            });
+            await this.deps.sleep(LAYOUT_SETTLE_MS);
+            const postShutterLayout = (await uiSnapshotProvider.capture({
+                reason: "locate",
+                timeoutMs: CAMERA_FOREGROUND_TIMEOUT_MS,
+                ...(signal === undefined ? {} : { signal })
+            })).roots;
+            const postShutterForeground = await this.waitForStableForeground(adb, deviceSerial, signal);
+            const activityName = preShutterForeground.activity;
+            if (postShutterForeground.packageName !== cameraPackage) {
+                return {
+                    packageName: cameraPackage,
+                    activityName,
+                    shutterResourceId: shutter.resourceId,
+                    ...(shutter.contentDescription !== undefined
+                        ? { shutterContentDescription: shutter.contentDescription }
+                        : {})
+                };
+            }
+            const confirm = findButton(postShutterLayout, CONFIRM_KEYWORDS, CONFIRM_RESOURCE_ID_SUBSTRINGS);
+            if (confirm === "ambiguous") {
+                throw new CameraProbeError("ALIGN_CONFIRM_AMBIGUOUS", "Multiple confirm candidates could not be disambiguated by resourceId");
+            }
+            if (confirm === "none") {
+                throw new CameraProbeError("ALIGN_CONFIRM_NOT_FOUND", "Camera remained foreground after capture, but no deterministic confirm button was found");
+            }
+            if (confirm === "no_resource_id") {
+                throw new CameraProbeError("ALIGN_CONFIRM_NO_RESOURCE_ID", "Confirm candidate has no resourceId for deterministic replay");
+            }
+            return {
+                packageName: cameraPackage,
+                activityName,
+                shutterResourceId: shutter.resourceId,
+                ...(shutter.contentDescription !== undefined
+                    ? { shutterContentDescription: shutter.contentDescription }
+                    : {}),
+                confirmResourceId: confirm.resourceId,
+                ...(confirm.contentDescription !== undefined
+                    ? { confirmContentDescription: confirm.contentDescription }
+                    : {}),
+                confirmActivityName: postShutterForeground.activity
+            };
+        }
+        finally {
+            try {
+                await uiSnapshotProvider.close();
+            }
+            catch {
+                void null;
+            }
+            if (cameraPackage !== undefined) {
+                try {
+                    await adb.forceStop({
+                        packageName: cameraPackage,
+                        deviceSerial,
+                        ...(signal === undefined ? {} : { signal })
+                    });
+                }
+                catch {
+                    void null;
+                }
+            }
+        }
+    }
+    async waitForStableForeground(adb, deviceSerial, signal) {
+        const deadline = this.deps.now() + CAMERA_FOREGROUND_TIMEOUT_MS;
+        let previous;
+        while (this.deps.now() < deadline) {
+            const current = await adb.foregroundComponent(deviceIdentity(deviceSerial, signal));
+            if (previous !== undefined
+                && previous.packageName === current.packageName
+                && previous.activity === current.activity) {
+                return current;
+            }
+            previous = current;
+            await this.deps.sleep(Math.min(CAMERA_FOREGROUND_POLL_INTERVAL_MS, Math.max(0, deadline - this.deps.now())));
+        }
+        throw new CameraProbeError("ALIGN_CAMERA_NOT_LAUNCHED", "Foreground Activity did not stabilize within 8s");
+    }
+}

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

@@ -1,10 +1,48 @@
-import { access, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, mkdtemp, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { isErrnoException } from "../../shared/errors.js";
 function assertRunDirectoryName(name) {
     if (!/^[A-Za-z0-9._-]+$/.test(name)) {
         throw new Error("Invalid artifact run directory name");
     }
 }
+async function projectedRealPath(path) {
+    const missing = [];
+    let current = resolve(path);
+    for (;;) {
+        try {
+            return resolve(await realpath(current), ...missing.reverse());
+        }
+        catch (error) {
+            if (!isErrnoException(error) || error.code !== "ENOENT") {
+                throw error;
+            }
+            const parent = dirname(current);
+            if (parent === current) {
+                throw error;
+            }
+            missing.push(current.slice(parent.length + 1));
+            current = parent;
+        }
+    }
+}
+async function assertArtifactAuthorityBoundary(path) {
+    const canonical = await projectedRealPath(path);
+    const segments = canonical.split(/[\\/]+/);
+    const workspaceIndex = segments.lastIndexOf(".taphound");
+    if (workspaceIndex < 0) {
+        return;
+    }
+    const namespace = segments[workspaceIndex + 1];
+    if (namespace === "build") {
+        return;
+    }
+    if (namespace === "local"
+        && segments[workspaceIndex + 2] !== undefined) {
+        return;
+    }
+    throw new Error(`Artifact path inside .taphound/ must stay under .taphound/build/ or .taphound/local/<id>/: ${path}`);
+}
 function safePath(root, relativePath) {
     const candidate = resolve(root, relativePath);
     const fromRoot = relative(root, candidate);
@@ -65,6 +103,7 @@ class FileSystemArtifactSession {
 export class FileSystemArtifactStore {
     begin = async (baseDirectory, runDirectoryName) => {
         assertRunDirectoryName(runDirectoryName);
+        await assertArtifactAuthorityBoundary(baseDirectory);
         await mkdir(baseDirectory, { recursive: true });
         const temporaryDirectory = await mkdtemp(join(baseDirectory, `.${runDirectoryName}.tmp-`));
         await mkdir(join(temporaryDirectory, "steps"), { recursive: true });

package/dist/adapters/filesystem/context-document-writer.d.ts

@@ -0,0 +1,15 @@
+import type { ContextDocumentWrite, ContextDocumentWriter } from "../../ports/context-document-writer.js";
+export declare class FileSystemContextDocumentWriter implements ContextDocumentWriter {
+    readonly writeContextDocument: (input: {
+        projectRoot: string;
+        relativePath: string;
+        document: unknown;
+    }) => Promise<ContextDocumentWrite>;
+    readonly writeContextDocumentBatch: (input: {
+        projectRoot: string;
+        documents: readonly {
+            relativePath: string;
+            document: unknown;
+        }[];
+    }) => Promise<ContextDocumentWrite[]>;
+}