taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/adapters/filesystem/generation-store/store-files.js

@@ -0,0 +1,363 @@
+// Filesystem primitives of the session store: identity, evidence paths, and atomic state.
+import { randomUUID } from "node:crypto";
+import { constants, lstat, mkdir, open, realpath, rename, rm } from "node:fs/promises";
+import { isAbsolute, join, posix, relative } from "node:path";
+import { GenerationSessionStoreError } from "../../../ports/generation-session-store.js";
+import { isErrnoException } from "../../../shared/errors.js";
+import { compareStrings } from "../../../shared/strings.js";
+import { parseSession, sessionId } from "./session-transitions.js";
+export function snapshotMetadata(stats) {
+    return {
+        dev: stats.dev,
+        ino: stats.ino,
+        size: stats.size,
+        mtimeNs: stats.mtimeNs,
+        ctimeNs: stats.ctimeNs
+    };
+}
+export function sameSnapshotMetadata(left, right) {
+    return (sameIdentity(left, right)
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs);
+}
+export function evidenceEntryType(entry) {
+    if (entry.isFile())
+        return "file";
+    if (entry.isDirectory())
+        return "directory";
+    if (entry.isSymbolicLink())
+        return "symlink";
+    return "other";
+}
+export function evidenceEntrySnapshot(entries) {
+    return entries
+        .map((entry) => `${entry.name}\0${evidenceEntryType(entry)}`)
+        .sort();
+}
+export function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+export async function captureStoreDirectory(path) {
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new GenerationSessionStoreError("IO_ERROR", `Generation store path is not a real directory: ${path}`);
+    }
+    return {
+        path,
+        canonicalPath: await realpath(path),
+        identity: { dev: stats.dev, ino: stats.ino }
+    };
+}
+export async function verifyStoreDirectory(expected) {
+    const current = await captureStoreDirectory(expected.path);
+    if (current.canonicalPath !== expected.canonicalPath
+        || !sameIdentity(current.identity, expected.identity)) {
+        throw new GenerationSessionStoreError("IO_ERROR", `Generation store directory identity changed: ${expected.path}`);
+    }
+}
+export async function captureStoreFile(path) {
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new GenerationSessionStoreError("IO_ERROR", `Generation store path is not a real file: ${path}`);
+    }
+    return { dev: stats.dev, ino: stats.ino };
+}
+export async function captureOptionalStoreFile(path) {
+    try {
+        return await captureStoreFile(path);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function verifyOptionalStoreFile(path, expected) {
+    const current = await captureOptionalStoreFile(path);
+    if ((current === null) !== (expected === null)
+        || (current !== null
+            && expected !== null
+            && !sameIdentity(current, expected))) {
+        throw new GenerationSessionStoreError("IO_ERROR", `Generation state file identity changed: ${path}`);
+    }
+}
+export function asStoreIoError(error, action) {
+    if (error instanceof GenerationSessionStoreError) {
+        return error;
+    }
+    return new GenerationSessionStoreError("IO_ERROR", `Generation session store failed to ${action}`, { cause: error });
+}
+export async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function requireRealDirectory(path) {
+    const stats = await lstat(path);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new GenerationSessionStoreError("IO_ERROR", `Generation store path is not a real directory: ${path}`);
+    }
+}
+export async function createOrRequireDirectory(path) {
+    let created = false;
+    try {
+        await mkdir(path);
+        created = true;
+    }
+    catch (error) {
+        if (!isErrnoException(error) || error.code !== "EEXIST") {
+            throw error;
+        }
+    }
+    await requireRealDirectory(path);
+    return created;
+}
+export async function syncDirectory(path) {
+    const handle = await open(path, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function serializeJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function canonicalizeEvidenceValue(value, ancestors = new Set()) {
+    if (value === null
+        || typeof value === "string"
+        || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (Number.isFinite(value)) {
+            return value;
+        }
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE", "Evidence JSON cannot contain non-finite numbers");
+    }
+    if (typeof value !== "object") {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE", "Evidence value must be JSON serializable");
+    }
+    if (ancestors.has(value)) {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE", "Evidence JSON cannot contain cycles");
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => canonicalizeEvidenceValue(item, ancestors));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new GenerationSessionStoreError("INVALID_EVIDENCE", "Evidence value must contain only JSON objects");
+        }
+        return Object.fromEntries(Object.keys(value)
+            .sort((left, right) => compareStrings(left, right))
+            .map((key) => [
+            key,
+            canonicalizeEvidenceValue(value[key], ancestors)
+        ]));
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+export function canonicalizeEvidence(value) {
+    try {
+        return canonicalizeEvidenceValue(value);
+    }
+    catch (error) {
+        if (error instanceof GenerationSessionStoreError) {
+            throw error;
+        }
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE", "Evidence value cannot be safely inspected", { cause: error });
+    }
+}
+export function validateEvidencePath(relativePath) {
+    if (typeof relativePath !== "string"
+        || relativePath.length === 0
+        || relativePath.includes("\\")
+        || relativePath.includes("\0")
+        || isAbsolute(relativePath)
+        || posix.isAbsolute(relativePath)) {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE_PATH", "Invalid generation evidence path");
+    }
+    const segments = relativePath.split("/");
+    if (segments.some((segment) => (segment.length === 0
+        || segment === "."
+        || segment === ".."))
+        || posix.normalize(relativePath) !== relativePath) {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE_PATH", "Invalid generation evidence path");
+    }
+    return segments;
+}
+export function assertContained(root, candidate, allowRoot = false) {
+    const fromRoot = relative(root, candidate);
+    if ((!allowRoot && fromRoot.length === 0)
+        || fromRoot.startsWith("..")
+        || isAbsolute(fromRoot)) {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE_PATH", `Evidence path escapes generation session: ${candidate}`);
+    }
+}
+export async function captureDirectoryEvidence(path) {
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE_PATH", `Evidence parent is not a real directory: ${path}`);
+    }
+    return {
+        path,
+        canonicalPath: await realpath(path),
+        identity: { dev: stats.dev, ino: stats.ino }
+    };
+}
+export async function verifyDirectoryEvidence(activeCanonicalPath, directories) {
+    for (const evidence of directories) {
+        const current = await captureDirectoryEvidence(evidence.path);
+        assertContained(activeCanonicalPath, current.canonicalPath, true);
+        if (current.canonicalPath !== evidence.canonicalPath
+            || current.identity.dev !== evidence.identity.dev
+            || current.identity.ino !== evidence.identity.ino) {
+            throw new GenerationSessionStoreError("INVALID_EVIDENCE_PATH", `Evidence parent identity changed: ${evidence.path}`);
+        }
+    }
+}
+export async function assertEvidenceNamespaceAvailable(activeDirectory, activeEvidence, inFlight) {
+    const relativePath = `evidence/steps/${String(inFlight.stepIndex)}-${inFlight.attemptId}`;
+    const segments = validateEvidencePath(relativePath);
+    await verifyStoreDirectory(activeEvidence);
+    let parent = activeDirectory;
+    const directories = [activeEvidence];
+    for (const [index, segment] of segments.entries()) {
+        const candidate = join(parent, segment);
+        assertContained(activeDirectory, candidate);
+        let stats;
+        try {
+            stats = await lstat(candidate);
+        }
+        catch (error) {
+            if (isErrnoException(error) && error.code === "ENOENT") {
+                await verifyDirectoryEvidence(activeEvidence.canonicalPath, directories);
+                return;
+            }
+            throw error;
+        }
+        if (index === segments.length - 1) {
+            throw new GenerationSessionStoreError("EVIDENCE_ALREADY_EXISTS", `Generation attempt evidence namespace already exists: ${relativePath}`);
+        }
+        if (!stats.isDirectory() || stats.isSymbolicLink()) {
+            throw new GenerationSessionStoreError("INVALID_EVIDENCE_PATH", `Attempt evidence parent is not a safe directory: ${relativePath}`);
+        }
+        const evidence = await captureDirectoryEvidence(candidate);
+        assertContained(activeEvidence.canonicalPath, evidence.canonicalPath, true);
+        directories.push(evidence);
+        parent = candidate;
+    }
+}
+export async function fileIdentity(path) {
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE_PATH", `Evidence output is not a regular file: ${path}`);
+    }
+    return { dev: stats.dev, ino: stats.ino };
+}
+export function evidenceNotFound(relativePath, cause) {
+    return new GenerationSessionStoreError("EVIDENCE_NOT_FOUND", `Generation evidence does not exist: ${relativePath}`, { cause });
+}
+export async function readStateFromDirectory(directory, afterOpen, expectedDirectory) {
+    const directoryEvidence = expectedDirectory
+        ?? await captureStoreDirectory(directory);
+    await verifyStoreDirectory(directoryEvidence);
+    const statePath = join(directory, "state.json");
+    let text;
+    try {
+        const handle = await open(statePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const openedStats = await handle.stat({ bigint: true });
+            if (!openedStats.isFile()) {
+                throw new GenerationSessionStoreError("IO_ERROR", `Generation state is not a regular file: ${statePath}`);
+            }
+            const openedIdentity = {
+                dev: openedStats.dev,
+                ino: openedStats.ino
+            };
+            await afterOpen?.();
+            await verifyStoreDirectory(directoryEvidence);
+            const pathIdentity = await captureStoreFile(statePath);
+            if (!sameIdentity(openedIdentity, pathIdentity)) {
+                throw new GenerationSessionStoreError("IO_ERROR", `Generation state file identity changed: ${statePath}`);
+            }
+            text = await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error instanceof GenerationSessionStoreError) {
+            throw error;
+        }
+        throw new GenerationSessionStoreError("IO_ERROR", `Unable to read generation session state: ${statePath}`, { cause: error });
+    }
+    try {
+        return parseSession(JSON.parse(text));
+    }
+    catch (error) {
+        if (error instanceof GenerationSessionStoreError) {
+            throw error;
+        }
+        throw new GenerationSessionStoreError("INVALID_SESSION", `Unable to parse generation session state: ${statePath}`, { cause: error });
+    }
+}
+export async function readBoundState(directory, id, afterOpen, expectedDirectory) {
+    const session = await readStateFromDirectory(directory, afterOpen, expectedDirectory);
+    if (sessionId(session) !== id) {
+        throw new GenerationSessionStoreError("INVALID_SESSION", "Persisted generation session id does not match its directory");
+    }
+    return session;
+}
+export async function writeStateAtomically(directory, session, sync = syncDirectory, beforeRename, expectedDirectory, beforeInstall) {
+    const directoryEvidence = expectedDirectory
+        ?? await captureStoreDirectory(directory);
+    await verifyStoreDirectory(directoryEvidence);
+    const statePath = join(directory, "state.json");
+    const originalStateIdentity = await captureOptionalStoreFile(statePath);
+    const temporaryPath = join(directory, `.state.json.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporaryPath, constants.O_WRONLY
+            | constants.O_CREAT
+            | constants.O_EXCL
+            | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(serializeJson(session), "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        const temporaryIdentity = await captureStoreFile(temporaryPath);
+        await beforeRename?.();
+        await verifyStoreDirectory(directoryEvidence);
+        await verifyOptionalStoreFile(statePath, originalStateIdentity);
+        await beforeInstall?.();
+        await rename(temporaryPath, statePath);
+        const installedIdentity = await captureStoreFile(statePath);
+        if (!sameIdentity(temporaryIdentity, installedIdentity)) {
+            throw new GenerationSessionStoreError("IO_ERROR", `Generation state install identity changed: ${statePath}`);
+        }
+        await sync(directory);
+    }
+    catch (error) {
+        if (handle !== undefined) {
+            await handle.close().catch(() => undefined);
+        }
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/adapters/filesystem/journey-composition-store.d.ts

@@ -0,0 +1,23 @@
+import type { JourneyCompositionStore } from "../../ports/journey-composition-store.js";
+export declare class FileSystemJourneyCompositionStore implements JourneyCompositionStore {
+    private readonly inspector;
+    readonly read: (input: {
+        projectRoot: string;
+        relativePath: string;
+    }) => Promise<Buffer>;
+    readonly listFlowPaths: (projectRoot: string) => Promise<readonly string[]>;
+    readonly listJourneyPaths: (projectRoot: string) => Promise<readonly string[]>;
+    readonly readJourneyMeta: (input: {
+        projectRoot: string;
+        journeyPath: string;
+    }) => Promise<Buffer | null>;
+    readonly writeText: (input: {
+        projectRoot: string;
+        relativePath: string;
+        content: string;
+    }) => Promise<void>;
+    readonly readOutput: (input: {
+        projectRoot: string;
+        relativePath: string;
+    }) => Promise<Buffer>;
+}

package/dist/adapters/filesystem/journey-composition-store.js

@@ -0,0 +1,151 @@
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { BUILD_DIR, EXTERNAL_FLOWS_DIR, FLOWS_DIR, JOURNEYS_DIR } from "../../domain/workspace.js";
+import { NodeProjectFileInspector } from "./project-file-inspector.js";
+import { readProjectBoundFile, writeProjectBoundText } from "./project-bound-file.js";
+import { ensureBuildLayout } from "./workspace-layout.js";
+const MAX_COMPOSITION_BYTES = 1024 * 1024;
+function contained(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === ""
+        || (fromRoot !== ".."
+            && !fromRoot.startsWith(`..${sep}`)
+            && !isAbsolute(fromRoot));
+}
+export class FileSystemJourneyCompositionStore {
+    inspector = new NodeProjectFileInspector();
+    read = async (input) => {
+        const inspected = await this.inspector.inspectProjectFile({
+            projectRoot: input.projectRoot,
+            relativePath: input.relativePath,
+            maximumBytes: MAX_COMPOSITION_BYTES
+        });
+        if (inspected.status !== "inspected" || inspected.bytes === undefined) {
+            throw new Error(`Unable to safely read ${input.relativePath}: ${inspected.status}`);
+        }
+        return inspected.bytes;
+    };
+    listFlowPaths = async (projectRoot) => {
+        const canonicalRoot = await realpath(projectRoot);
+        const flowRoot = resolve(canonicalRoot, FLOWS_DIR);
+        try {
+            const canonicalFlowRoot = await realpath(flowRoot);
+            if (!contained(canonicalRoot, canonicalFlowRoot)) {
+                throw new Error("Flow directory escapes the project root");
+            }
+            const rootStats = await lstat(flowRoot);
+            if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+                throw new Error("Flow path is not a safe directory");
+            }
+        }
+        catch (error) {
+            if (error instanceof Error
+                && "code" in error
+                && error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+        const paths = [];
+        const externalDir = resolve(canonicalRoot, EXTERNAL_FLOWS_DIR);
+        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(`Flow catalog cannot contain symlinks: ${path}`);
+                }
+                if (entry.isDirectory()) {
+                    if (path === externalDir) {
+                        continue;
+                    }
+                    await visit(path);
+                }
+                else if (entry.isFile() && entry.name.endsWith(".json")) {
+                    paths.push(relative(canonicalRoot, path).replaceAll("\\", "/"));
+                }
+            }
+        };
+        await visit(flowRoot);
+        return paths.sort();
+    };
+    listJourneyPaths = async (projectRoot) => {
+        const canonicalRoot = await realpath(projectRoot);
+        const journeyRoot = resolve(canonicalRoot, JOURNEYS_DIR);
+        try {
+            const canonicalJourneyRoot = await realpath(journeyRoot);
+            if (!contained(canonicalRoot, canonicalJourneyRoot)) {
+                throw new Error("Journey directory escapes the project root");
+            }
+            const rootStats = await lstat(journeyRoot);
+            if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) {
+                throw new Error("Journey path is not a safe directory");
+            }
+        }
+        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(`Journey catalog cannot contain symlinks: ${path}`);
+                }
+                if (entry.isDirectory()) {
+                    await visit(path);
+                }
+                else if (entry.isFile()
+                    && entry.name.endsWith(".json")
+                    && !entry.name.endsWith(".meta.json")
+                    && !entry.name.endsWith(".resolve.json")) {
+                    paths.push(relative(canonicalRoot, path).replaceAll("\\", "/"));
+                }
+            }
+        };
+        await visit(journeyRoot);
+        return paths.sort();
+    };
+    readJourneyMeta = async (input) => {
+        if (!input.journeyPath.endsWith(".json")
+            || input.journeyPath.endsWith(".meta.json")
+            || input.journeyPath.endsWith(".resolve.json")) {
+            throw new Error(`Journey path must be a normalized JSON file: ${input.journeyPath}`);
+        }
+        const metaPath = `${input.journeyPath.slice(0, -".json".length)}.meta.json`;
+        const inspected = await this.inspector.inspectProjectFile({
+            projectRoot: input.projectRoot,
+            relativePath: metaPath,
+            maximumBytes: MAX_COMPOSITION_BYTES
+        });
+        if (inspected.status === "notFound") {
+            return null;
+        }
+        if (inspected.status !== "inspected" || inspected.bytes === undefined) {
+            throw new Error(`Unable to safely read ${metaPath}: ${inspected.status}`);
+        }
+        return inspected.bytes;
+    };
+    writeText = async (input) => {
+        await ensureBuildLayout(input.projectRoot);
+        await writeProjectBoundText({
+            projectRoot: input.projectRoot,
+            authorityRoot: resolve(input.projectRoot, BUILD_DIR),
+            outputPath: resolve(input.projectRoot, input.relativePath)
+        }, input.content);
+    };
+    readOutput = async (input) => {
+        await ensureBuildLayout(input.projectRoot);
+        return readProjectBoundFile({
+            projectRoot: input.projectRoot,
+            authorityRoot: resolve(input.projectRoot, BUILD_DIR),
+            outputPath: resolve(input.projectRoot, input.relativePath)
+        });
+    };
+}

package/dist/adapters/filesystem/knowledge-registry.d.ts

@@ -0,0 +1,12 @@
+import type { KnowledgeRegistryPort, KnowledgeRehashResult, LoadedKnowledgeBundle } from "../../ports/knowledge-registry.js";
+/**
+ * Knowledge is a committed, hand- or agent-authored library of semantic
+ * Anchors and Screens. `index.json` binds every document by content hash;
+ * `rehash` is the only writer and rebuilds the index from the documents.
+ */
+export declare class FileSystemKnowledgeRegistry implements KnowledgeRegistryPort {
+    readonly load: (projectRoot: string) => Promise<LoadedKnowledgeBundle>;
+    readonly rehash: (projectRoot: string, packageName: string) => Promise<KnowledgeRehashResult>;
+    private scanDocuments;
+    private readDocuments;
+}