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

package/dist/adapters/filesystem/context-document-writer.js

@@ -0,0 +1,112 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { isContained } from "../../shared/paths.js";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : "Unknown write failure";
+}
+export class FileSystemContextDocumentWriter {
+    writeContextDocument = async (input) => {
+        const normalizedPath = input.relativePath.replaceAll("\\", "/");
+        if (normalizedPath.length === 0
+            || normalizedPath.startsWith("/")
+            || /^[A-Za-z]:/.test(normalizedPath)
+            || normalizedPath.split("/").includes("..")) {
+            return { status: "escape" };
+        }
+        let canonicalRoot;
+        try {
+            canonicalRoot = await realpath(input.projectRoot);
+        }
+        catch (error) {
+            return { status: "unwritable", message: errorMessage(error) };
+        }
+        const target = resolve(canonicalRoot, normalizedPath);
+        if (!isContained(canonicalRoot, target)) {
+            return { status: "escape" };
+        }
+        const bytes = `${JSON.stringify(input.document, null, 2)}\n`;
+        const directory = dirname(target);
+        const temporaryPath = join(directory, `.${basename(target)}.${randomUUID()}.tmp`);
+        try {
+            await mkdir(directory, { recursive: true });
+            await writeFile(temporaryPath, bytes, "utf8");
+            await rename(temporaryPath, target);
+        }
+        catch (error) {
+            await rm(temporaryPath, { force: true }).catch(() => undefined);
+            return { status: "unwritable", message: errorMessage(error) };
+        }
+        return {
+            status: "written",
+            sha256: createHash("sha256").update(bytes).digest("hex")
+        };
+    };
+    writeContextDocumentBatch = async (input) => {
+        let canonicalRoot;
+        try {
+            canonicalRoot = await realpath(input.projectRoot);
+        }
+        catch (error) {
+            const failure = {
+                status: "unwritable",
+                message: errorMessage(error)
+            };
+            return input.documents.map(() => failure);
+        }
+        const prepared = [];
+        for (const doc of input.documents) {
+            const normalizedPath = doc.relativePath.replaceAll("\\", "/");
+            if (normalizedPath.length === 0
+                || normalizedPath.startsWith("/")
+                || /^[A-Za-z]:/.test(normalizedPath)
+                || normalizedPath.split("/").includes("..")) {
+                for (const item of prepared) {
+                    await rm(item.tempPath, { force: true }).catch(() => undefined);
+                }
+                const failure = { status: "escape" };
+                return input.documents.map(() => failure);
+            }
+            const target = resolve(canonicalRoot, normalizedPath);
+            if (!isContained(canonicalRoot, target)) {
+                for (const item of prepared) {
+                    await rm(item.tempPath, { force: true }).catch(() => undefined);
+                }
+                const failure = { status: "escape" };
+                return input.documents.map(() => failure);
+            }
+            const bytes = `${JSON.stringify(doc.document, null, 2)}\n`;
+            const directory = dirname(target);
+            const tempPath = join(directory, `.${basename(target)}.${randomUUID()}.tmp`);
+            prepared.push({
+                target,
+                tempPath,
+                bytes,
+                sha256: createHash("sha256").update(bytes).digest("hex")
+            });
+        }
+        try {
+            for (const item of prepared) {
+                await mkdir(dirname(item.target), { recursive: true });
+                await writeFile(item.tempPath, item.bytes, "utf8");
+            }
+            for (const item of prepared) {
+                await rename(item.tempPath, item.target);
+            }
+        }
+        catch (error) {
+            for (const item of prepared) {
+                await rm(item.tempPath, { force: true }).catch(() => undefined);
+            }
+            const failure = {
+                status: "unwritable",
+                message: errorMessage(error)
+            };
+            return input.documents.map(() => failure);
+        }
+        return prepared.map((item) => ({
+            status: "written",
+            sha256: item.sha256
+        }));
+    };
+}

package/dist/adapters/filesystem/external-flow-registry.d.ts

@@ -0,0 +1,17 @@
+import type { ExternalFlowCatalogEntry, ExternalFlowRecord, ExternalFlowRegistry, WriteExternalFlowInput, WriteExternalFlowResult } from "../../ports/external-flow-registry.js";
+export declare class FileSystemExternalFlowRegistry implements ExternalFlowRegistry {
+    private readonly builtinFlowsRoot;
+    constructor(builtinFlowsRoot: string);
+    readonly read: (input: {
+        projectRoot: string;
+        name: string;
+    }) => Promise<ExternalFlowRecord>;
+    readonly list: (projectRoot: string) => Promise<readonly ExternalFlowCatalogEntry[]>;
+    readonly write: (input: WriteExternalFlowInput) => Promise<WriteExternalFlowResult>;
+    private readonly loadFlow;
+    private readonly resolveProjectFlowPath;
+    private readonly resolveBuiltinFlowPath;
+    private readonly readFlowFile;
+    private readonly listBuiltinFlows;
+    private readonly listProjectFlows;
+}

package/dist/adapters/filesystem/external-flow-registry.js

@@ -0,0 +1,325 @@
+import { lstat, mkdir, readdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { ExternalFlowSchema } from "../../domain/external-flow.js";
+import { EXTERNAL_FLOWS_DIR } from "../../domain/workspace.js";
+const MAX_EXTERNAL_FLOW_BYTES = 1024 * 1024;
+function contained(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === ""
+        || (fromRoot !== ".."
+            && !fromRoot.startsWith(`..${sep}`)
+            && !isAbsolute(fromRoot));
+}
+function flowFileName(name) {
+    return `${name}.json`;
+}
+function errorDetails(error) {
+    if (error instanceof Error) {
+        return {
+            code: "EXTERNAL_FLOW_INVALID",
+            message: error.message
+        };
+    }
+    return {
+        code: "EXTERNAL_FLOW_INVALID",
+        message: String(error)
+    };
+}
+export class FileSystemExternalFlowRegistry {
+    builtinFlowsRoot;
+    constructor(builtinFlowsRoot) {
+        this.builtinFlowsRoot = builtinFlowsRoot;
+    }
+    read = async (input) => {
+        const loaded = await this.loadFlow(input.projectRoot, input.name);
+        return {
+            bytes: loaded.bytes,
+            flow: loaded.flow,
+            source: loaded.source,
+            path: loaded.path
+        };
+    };
+    list = async (projectRoot) => {
+        const builtinEntries = await this.listBuiltinFlows();
+        const projectEntries = await this.listProjectFlows(projectRoot);
+        const projectNames = new Set(projectEntries.map((entry) => entry.name));
+        const entries = [
+            ...projectEntries,
+            ...builtinEntries.filter((entry) => !projectNames.has(entry.name))
+        ];
+        return entries.sort((left, right) => left.name.localeCompare(right.name));
+    };
+    write = async (input) => {
+        const { projectRoot, name, flow, force } = input;
+        const canonicalRoot = await realpath(projectRoot);
+        const externalRoot = resolve(canonicalRoot, EXTERNAL_FLOWS_DIR);
+        const targetPath = join(externalRoot, flowFileName(name));
+        const canonicalExternalRoot = await realpath(externalRoot).catch((error) => {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        });
+        if (canonicalExternalRoot !== undefined
+            && !contained(canonicalRoot, canonicalExternalRoot)) {
+            throw new Error("External Flow directory escapes the project root");
+        }
+        const rootStats = await lstat(externalRoot).catch((error) => {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        });
+        if (rootStats !== undefined && rootStats.isSymbolicLink()) {
+            throw new Error("External Flow directory is a symlink");
+        }
+        const validated = ExternalFlowSchema.parse(flow);
+        if (validated.name !== name) {
+            throw new Error(`External Flow declares name "${validated.name}", expected "${name}"`);
+        }
+        let overwritten = false;
+        const existingStats = await lstat(targetPath).catch((error) => {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        });
+        if (existingStats !== undefined) {
+            if (existingStats.isSymbolicLink()) {
+                throw new Error(`External Flow target is a symlink: ${targetPath}`);
+            }
+            if (!force) {
+                throw new Error(`External Flow already exists: ${name}`);
+            }
+            overwritten = true;
+        }
+        const parentDir = name.includes("/")
+            ? join(externalRoot, name.split("/").slice(0, -1).join("/"))
+            : externalRoot;
+        await mkdir(parentDir, { recursive: true });
+        const tempPath = `${targetPath}.tmp`;
+        await writeFile(tempPath, `${JSON.stringify(validated, null, 2)}\n`);
+        await rename(tempPath, targetPath);
+        const relativePath = relative(canonicalRoot, targetPath).replaceAll("\\", "/");
+        return { path: relativePath, overwritten };
+    };
+    loadFlow = async (projectRoot, name) => {
+        const projectPath = await this.resolveProjectFlowPath(projectRoot, name);
+        if (projectPath !== undefined) {
+            return this.readFlowFile(projectPath, name, "project");
+        }
+        const builtinPath = await this.resolveBuiltinFlowPath(name);
+        if (builtinPath !== undefined) {
+            return this.readFlowFile(builtinPath, name, "builtin");
+        }
+        throw new Error(`External Flow not found: ${name}`);
+    };
+    resolveProjectFlowPath = async (projectRoot, name) => {
+        const canonicalRoot = await realpath(projectRoot);
+        const externalRoot = resolve(canonicalRoot, EXTERNAL_FLOWS_DIR);
+        try {
+            const canonicalExternalRoot = await realpath(externalRoot);
+            if (!contained(canonicalRoot, canonicalExternalRoot)) {
+                throw new Error("External Flow directory escapes the project root");
+            }
+            const rootStats = await lstat(externalRoot);
+            if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+                return undefined;
+            }
+        }
+        catch (error) {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+        const filePath = join(externalRoot, flowFileName(name));
+        try {
+            const stats = await lstat(filePath);
+            if (!stats.isFile() || stats.isSymbolicLink()) {
+                return undefined;
+            }
+            return filePath;
+        }
+        catch (error) {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+    };
+    resolveBuiltinFlowPath = async (name) => {
+        const filePath = join(this.builtinFlowsRoot, flowFileName(name));
+        try {
+            const stats = await lstat(filePath);
+            if (!stats.isFile() || stats.isSymbolicLink()) {
+                return undefined;
+            }
+            return filePath;
+        }
+        catch (error) {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+    };
+    readFlowFile = async (filePath, expectedName, source) => {
+        const bytes = await readFile(filePath);
+        if (bytes.byteLength > MAX_EXTERNAL_FLOW_BYTES) {
+            throw new Error(`External Flow exceeds ${String(MAX_EXTERNAL_FLOW_BYTES)} bytes: ${filePath}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(bytes.toString("utf8"));
+        }
+        catch (error) {
+            throw new Error(`External Flow is not valid JSON: ${filePath}`, { cause: error });
+        }
+        const flow = ExternalFlowSchema.parse(parsed);
+        if (flow.name !== expectedName) {
+            throw new Error(`External Flow at ${filePath} declares name "${flow.name}", expected "${expectedName}"`);
+        }
+        return { bytes, flow, path: filePath, source };
+    };
+    listBuiltinFlows = async () => {
+        let rootStats;
+        try {
+            rootStats = await lstat(this.builtinFlowsRoot);
+        }
+        catch (error) {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+        if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+            return [];
+        }
+        const paths = [];
+        const visit = async (directory) => {
+            const entries = await readdir(directory, { withFileTypes: true });
+            for (const entry of entries) {
+                const path = join(directory, entry.name);
+                if (entry.isSymbolicLink()) {
+                    throw new Error(`Built-in External Flow catalog cannot contain symlinks: ${path}`);
+                }
+                if (entry.isDirectory()) {
+                    await visit(path);
+                }
+                else if (entry.isFile() && entry.name.endsWith(".json")) {
+                    paths.push(path);
+                }
+            }
+        };
+        await visit(this.builtinFlowsRoot);
+        paths.sort();
+        const results = [];
+        for (const filePath of paths) {
+            const relativePath = relative(this.builtinFlowsRoot, filePath).replaceAll("\\", "/");
+            const name = relativePath.slice(0, -".json".length);
+            try {
+                const loaded = await this.readFlowFile(filePath, name, "builtin");
+                results.push({
+                    name,
+                    source: "builtin",
+                    path: filePath,
+                    status: "valid",
+                    escapedPackageName: loaded.flow.escapedPackageName,
+                    stepCount: loaded.flow.steps.length
+                });
+            }
+            catch (error) {
+                results.push({
+                    name,
+                    source: "builtin",
+                    path: filePath,
+                    status: "invalid",
+                    failure: errorDetails(error)
+                });
+            }
+        }
+        return results;
+    };
+    listProjectFlows = async (projectRoot) => {
+        const canonicalRoot = await realpath(projectRoot);
+        const externalRoot = resolve(canonicalRoot, EXTERNAL_FLOWS_DIR);
+        try {
+            const canonicalExternalRoot = await realpath(externalRoot);
+            if (!contained(canonicalRoot, canonicalExternalRoot)) {
+                throw new Error("External Flow directory escapes the project root");
+            }
+            const rootStats = await lstat(externalRoot);
+            if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+                return [];
+            }
+        }
+        catch (error) {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+        const paths = [];
+        const visit = async (directory) => {
+            const entries = await readdir(directory, { withFileTypes: true });
+            for (const entry of entries) {
+                const path = join(directory, entry.name);
+                if (entry.isSymbolicLink()) {
+                    throw new Error(`External Flow catalog cannot contain symlinks: ${path}`);
+                }
+                if (entry.isDirectory()) {
+                    await visit(path);
+                }
+                else if (entry.isFile() && entry.name.endsWith(".json")) {
+                    paths.push(path);
+                }
+            }
+        };
+        await visit(externalRoot);
+        paths.sort();
+        const results = [];
+        for (const filePath of paths) {
+            const relativePath = relative(canonicalRoot, filePath).replaceAll("\\", "/");
+            const name = relativePath
+                .slice(`${EXTERNAL_FLOWS_DIR}/`.length, -".json".length);
+            try {
+                const loaded = await this.readFlowFile(filePath, name, "project");
+                results.push({
+                    name,
+                    source: "project",
+                    path: relativePath,
+                    status: "valid",
+                    escapedPackageName: loaded.flow.escapedPackageName,
+                    stepCount: loaded.flow.steps.length
+                });
+            }
+            catch (error) {
+                results.push({
+                    name,
+                    source: "project",
+                    path: relativePath,
+                    status: "invalid",
+                    failure: errorDetails(error)
+                });
+            }
+        }
+        return results;
+    };
+}

package/dist/adapters/filesystem/generation-session-store.d.ts

@@ -1,10 +1,11 @@
-import { type GenerationInFlight, type GenerationSession, type PendingConfirmation } from "../../domain/generation.js";
+import { type GenerationInFlight, type GenerationSession, type PendingConfirmation, type VerificationPhase } from "../../domain/generation.js";
 import { type GenerationSessionStore } from "../../ports/generation-session-store.js";
 export interface FileSystemGenerationSessionStoreOptions {
     lockTimeoutMs?: number;
     lockRetryMs?: number;
     now?: (() => Date) | undefined;
     hooks?: FileSystemGenerationSessionStoreHooks;
+    generationRoot?: string | undefined;
 }
 export interface FileSystemGenerationSessionStoreHooks {
     beforeLockStagingWrite?: () => Promise<void> | void;
@@ -27,6 +28,8 @@ export declare class FileSystemGenerationSessionStore implements GenerationSessi
     private readonly options;
     private readonly now;
     private readonly hooks;
+    private readonly customGenerationRoot;
+    private readonly lock;
     constructor(projectRoot: string, options?: FileSystemGenerationSessionStoreOptions);
     readonly create: (input: GenerationSession) => Promise<void>;
     readonly read: (id: string) => Promise<GenerationSession>;
@@ -36,14 +39,24 @@ export declare class FileSystemGenerationSessionStore implements GenerationSessi
     readonly beginStep: (id: string, expectedRevision: number, inFlightInput: GenerationInFlight, approvedConfirmationInput?: PendingConfirmation) => Promise<GenerationSession>;
     readonly completeStep: (id: string, expectedRevision: number, expectedInFlightInput: GenerationInFlight, input: GenerationSession) => Promise<void>;
     readonly recover: (id: string, expectedRevision: number, input: GenerationSession) => Promise<void>;
-    readonly beginVerification: (id: string, expectedRevision: number, attemptId: string) => Promise<GenerationSession>;
+    readonly beginVerification: (id: string, expectedRevision: number, attemptId: string, owner?: {
+        pid: number;
+        startedAt: string;
+    }) => Promise<GenerationSession>;
+    readonly updateVerificationPhase: (id: string, attemptId: string, phase: VerificationPhase) => Promise<void>;
+    readonly abortVerification: (id: string, expectedRevision: number) => Promise<GenerationSession>;
     readonly completeVerification: (id: string, expectedRevision: number, input: GenerationSession) => Promise<void>;
     readonly failVerification: (id: string, expectedRevision: number, input: GenerationSession) => Promise<void>;
+    readonly recoverVerification: (id: string, expectedRevision: number, input: GenerationSession) => Promise<void>;
+    readonly reopenVerification: (id: string, expectedRevision: number, input: GenerationSession) => Promise<void>;
     readonly markBundlePublishable: (id: string, expectedRevision: number, input: GenerationSession) => Promise<void>;
+    readonly archive: (id: string, expectedRevision: number, input: GenerationSession) => Promise<void>;
+    readonly list: () => Promise<readonly GenerationSession[]>;
     readonly writeEvidence: (id: string, relativePath: string, value: unknown) => Promise<void>;
     readonly writeTextEvidence: (id: string, relativePath: string, value: string) => Promise<void>;
     readonly produceEvidence: (id: string, relativePath: string, produce: (temporaryPath: string) => Promise<void>) => Promise<void>;
     readonly readEvidence: (id: string, relativePath: string) => Promise<Buffer>;
+    readonly evidenceReference: (id: string, relativePath: string) => Promise<string>;
     readonly listEvidence: (id: string) => Promise<readonly {
         path: string;
         contentBase64: string;
@@ -54,15 +67,8 @@ export declare class FileSystemGenerationSessionStore implements GenerationSessi
     private readonly writeVerificationTransition;
     private readonly activeDirectory;
     private readonly finalDirectory;
-    private readonly lockPath;
-    private readonly syncDirectory;
+    private readonly withVerifiedEvidence;
     private readonly withLock;
-    private readonly acquireLock;
-    private readonly tryInstallLock;
-    private readonly reapDeadOwnerLock;
-    private readonly releaseLock;
-    private readonly readLockOwner;
-    private readonly fileIdentity;
-    private readonly isProcessAlive;
+    private readonly syncDirectory;
     private assertPublishable;
 }