taphound 0.2.0-dev.1

package/dist/adapters/filesystem/journey-writer.d.ts

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

package/dist/adapters/filesystem/journey-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 { JourneySchema } from "../../domain/journey.js";
+import { readProjectBoundFile, writeProjectBoundText } from "./project-bound-file.js";
+export class FileSystemJourneyWriter {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async write(outputPath, input) {
+        const journey = JourneySchema.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(journey, null, 2)}\n`, "utf8");
+            await rename(temporaryPath, outputPath);
+        }
+        catch (error) {
+            await rm(temporaryPath, { force: true });
+            throw error;
+        }
+    }
+    async writeProjectBound(input) {
+        const journey = JourneySchema.parse(input.journey);
+        await writeProjectBoundText(input, `${JSON.stringify(journey, null, 2)}\n`, this.options.beforeBoundInstall === undefined
+            ? {}
+            : { beforeInstall: this.options.beforeBoundInstall });
+    }
+    async readProjectBound(input) {
+        return readProjectBoundFile(input);
+    }
+}

package/dist/adapters/filesystem/project-bound-file.d.ts

@@ -0,0 +1,6 @@
+import type { ProjectBoundPath } from "../../ports/project-bound-file.js";
+export interface ProjectBoundFileHooks {
+    beforeInstall?: (() => Promise<void> | void) | undefined;
+}
+export declare function writeProjectBoundText(input: ProjectBoundPath, value: string, hooks?: ProjectBoundFileHooks): Promise<void>;
+export declare function readProjectBoundFile(input: ProjectBoundPath): Promise<Buffer>;

package/dist/adapters/filesystem/project-bound-file.js

@@ -0,0 +1,240 @@
+import { randomUUID } from "node:crypto";
+import { constants, lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+async function captureDirectory(path) {
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`Project-bound path is not a safe directory: ${path}`);
+    }
+    return {
+        path,
+        canonicalPath: await realpath(path),
+        dev: stats.dev,
+        ino: stats.ino
+    };
+}
+async function captureFile(path) {
+    const stats = await lstat(path, { bigint: true });
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new Error(`Project-bound destination is not a regular file: ${path}`);
+    }
+    return { dev: stats.dev, ino: stats.ino };
+}
+async function captureOptionalFile(path) {
+    try {
+        return await captureFile(path);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+function relativeInside(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    if (fromRoot.length === 0
+        || fromRoot === ".."
+        || fromRoot.startsWith(`..${sep}`)
+        || isAbsolute(fromRoot)) {
+        throw new Error("Project-bound output escapes the real project root");
+    }
+    return fromRoot;
+}
+function assertOutsideAuthority(authorityCanonicalPath, candidateCanonicalPath) {
+    const fromAuthority = relative(authorityCanonicalPath, candidateCanonicalPath);
+    if (fromAuthority.length === 0
+        || (fromAuthority !== ".."
+            && !fromAuthority.startsWith(`..${sep}`)
+            && !isAbsolute(fromAuthority))) {
+        throw new Error("Project-bound output overlaps the authority subtree");
+    }
+}
+async function verifyDirectory(expected) {
+    const current = await captureDirectory(expected.path);
+    if (current.canonicalPath !== expected.canonicalPath
+        || !sameIdentity(current, expected)) {
+        throw new Error(`Project-bound directory identity changed: ${expected.path}`);
+    }
+}
+async function verifyBoundOutput(bound) {
+    for (const directory of bound.directories) {
+        await verifyDirectory(directory);
+    }
+    await verifyDirectory(bound.authority);
+    relativeInside(bound.root.canonicalPath, bound.parent.canonicalPath);
+    assertOutsideAuthority(bound.authority.canonicalPath, bound.parent.canonicalPath);
+}
+async function verifyOptionalFile(path, expected) {
+    const current = await captureOptionalFile(path);
+    if ((current === null) !== (expected === null)
+        || (current !== null
+            && expected !== null
+            && !sameIdentity(current, expected))) {
+        throw new Error(`Project-bound destination identity changed: ${path}`);
+    }
+}
+async function syncDirectory(path) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function lexicalSegments(root, output) {
+    const fromRoot = relative(root, output);
+    if (fromRoot.length === 0
+        || fromRoot === ".."
+        || fromRoot.startsWith(`..${sep}`)
+        || isAbsolute(fromRoot)) {
+        throw new Error("Project-bound output must stay within the project");
+    }
+    const segments = fromRoot.split(sep);
+    if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        throw new Error("Project-bound output path must be normalized");
+    }
+    return segments;
+}
+async function prepareBoundOutput(input, createParents) {
+    const projectPath = resolve(input.projectRoot);
+    const outputPath = resolve(input.outputPath);
+    const authorityPath = resolve(input.authorityRoot);
+    const segments = lexicalSegments(projectPath, outputPath);
+    const root = await captureDirectory(projectPath);
+    const authority = await captureDirectory(authorityPath);
+    relativeInside(root.canonicalPath, authority.canonicalPath);
+    const authorityFromRoot = relative(root.canonicalPath, authority.canonicalPath);
+    if (authorityFromRoot === ".."
+        || authorityFromRoot.startsWith(`..${sep}`)
+        || isAbsolute(authorityFromRoot)) {
+        throw new Error("Authority root escapes the real project root");
+    }
+    let current = projectPath;
+    const directories = [root];
+    for (const segment of segments.slice(0, -1)) {
+        const next = resolve(current, segment);
+        try {
+            const captured = await captureDirectory(next);
+            relativeInside(root.canonicalPath, captured.canonicalPath);
+            assertOutsideAuthority(authority.canonicalPath, captured.canonicalPath);
+            directories.push(captured);
+        }
+        catch (error) {
+            if (!createParents
+                || !isNodeError(error)
+                || error.code !== "ENOENT") {
+                throw error;
+            }
+            await verifyDirectory(directories.at(-1));
+            await mkdir(next);
+            await syncDirectory(current);
+            const captured = await captureDirectory(next);
+            relativeInside(root.canonicalPath, captured.canonicalPath);
+            assertOutsideAuthority(authority.canonicalPath, captured.canonicalPath);
+            directories.push(captured);
+        }
+        current = next;
+    }
+    const parent = directories.at(-1);
+    if (parent === undefined) {
+        throw new Error("Project-bound output parent is unavailable");
+    }
+    const bound = {
+        root,
+        authority,
+        parent,
+        directories,
+        outputPath
+    };
+    await verifyBoundOutput(bound);
+    return bound;
+}
+async function safeTemporaryCleanup(bound, temporaryPath, expected) {
+    if (expected === undefined) {
+        return;
+    }
+    try {
+        await verifyBoundOutput(bound);
+        const current = await captureFile(temporaryPath);
+        if (sameIdentity(current, expected)) {
+            await unlink(temporaryPath);
+            await syncDirectory(bound.parent.path);
+        }
+    }
+    catch {
+        // Never follow a substituted path to clean up.
+    }
+}
+export async function writeProjectBoundText(input, value, hooks = {}) {
+    const bound = await prepareBoundOutput(input, true);
+    const originalDestination = await captureOptionalFile(bound.outputPath);
+    const temporaryPath = resolve(bound.parent.path, `.${basename(bound.outputPath)}.${randomUUID()}.tmp`);
+    let temporaryIdentity;
+    let handle;
+    try {
+        handle = await open(temporaryPath, constants.O_WRONLY
+            | constants.O_CREAT
+            | constants.O_EXCL
+            | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(value, "utf8");
+        await handle.sync();
+        const stats = await handle.stat({ bigint: true });
+        temporaryIdentity = { dev: stats.dev, ino: stats.ino };
+        await handle.close();
+        handle = undefined;
+        await hooks.beforeInstall?.();
+        await verifyBoundOutput(bound);
+        await verifyOptionalFile(bound.outputPath, originalDestination);
+        const stagedIdentity = await captureFile(temporaryPath);
+        if (!sameIdentity(stagedIdentity, temporaryIdentity)) {
+            throw new Error("Project-bound temporary file identity changed");
+        }
+        await rename(temporaryPath, bound.outputPath);
+        const installedIdentity = await captureFile(bound.outputPath);
+        if (!sameIdentity(installedIdentity, temporaryIdentity)) {
+            throw new Error("Project-bound installed file identity changed");
+        }
+        await syncDirectory(bound.parent.path);
+    }
+    catch (error) {
+        if (handle !== undefined) {
+            await handle.close().catch(() => undefined);
+        }
+        await safeTemporaryCleanup(bound, temporaryPath, temporaryIdentity);
+        throw error;
+    }
+}
+export async function readProjectBoundFile(input) {
+    const bound = await prepareBoundOutput(input, false);
+    const handle = await open(bound.outputPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stats = await handle.stat({ bigint: true });
+        if (!stats.isFile()) {
+            throw new Error("Project-bound output is not a regular file");
+        }
+        const openedIdentity = { dev: stats.dev, ino: stats.ino };
+        await verifyBoundOutput(bound);
+        const pathIdentity = await captureFile(bound.outputPath);
+        if (!sameIdentity(openedIdentity, pathIdentity)) {
+            throw new Error("Project-bound output identity changed");
+        }
+        const bytes = await handle.readFile();
+        await verifyBoundOutput(bound);
+        const finalIdentity = await captureFile(bound.outputPath);
+        if (!sameIdentity(openedIdentity, finalIdentity)) {
+            throw new Error("Project-bound output identity changed during read");
+        }
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/adapters/filesystem/project-file-inspector.d.ts

@@ -0,0 +1,8 @@
+import { type ProjectFileInspection, type ProjectFileInspector } from "../../ports/project-file-inspector.js";
+export declare class NodeProjectFileInspector implements ProjectFileInspector {
+    readonly inspectProjectFile: (input: {
+        projectRoot: string;
+        relativePath: string;
+        maximumBytes: number;
+    }) => Promise<ProjectFileInspection>;
+}

package/dist/adapters/filesystem/project-file-inspector.js

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+function errorCode(error) {
+    return (typeof error === "object"
+        && error !== null
+        && "code" in error
+        && typeof error.code === "string")
+        ? error.code
+        : undefined;
+}
+function isContained(root, path) {
+    const fromRoot = relative(root, path);
+    return (fromRoot === ""
+        || (fromRoot !== ".."
+            && !fromRoot.startsWith(`..${sep}`)
+            && !isAbsolute(fromRoot)));
+}
+function sameIdentity(left, right) {
+    return (left.dev === right.dev
+        && left.ino === right.ino
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs);
+}
+async function fileIdentity(handle) {
+    const fileStats = await handle.stat({ bigint: true });
+    return {
+        dev: fileStats.dev,
+        ino: fileStats.ino,
+        size: fileStats.size,
+        mtimeNs: fileStats.mtimeNs,
+        ctimeNs: fileStats.ctimeNs
+    };
+}
+async function pathIdentity(path) {
+    const fileStats = await stat(path, { bigint: true });
+    return {
+        dev: fileStats.dev,
+        ino: fileStats.ino,
+        size: fileStats.size,
+        mtimeNs: fileStats.mtimeNs,
+        ctimeNs: fileStats.ctimeNs
+    };
+}
+function normalizedRelativePath(root, path) {
+    return relative(root, path).replaceAll("\\", "/");
+}
+function evidenceFailure(error) {
+    return errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR"
+        ? { status: "notFound" }
+        : { status: "unreadable" };
+}
+export class NodeProjectFileInspector {
+    inspectProjectFile = async (input) => {
+        let canonicalRoot;
+        try {
+            canonicalRoot = await realpath(input.projectRoot);
+        }
+        catch (error) {
+            return errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR"
+                ? { status: "rootNotFound" }
+                : { status: "rootUnreadable" };
+        }
+        let rootBefore;
+        try {
+            const rootStats = await stat(canonicalRoot, { bigint: true });
+            if (!rootStats.isDirectory()) {
+                return { status: "rootNotDirectory" };
+            }
+            rootBefore = {
+                dev: rootStats.dev,
+                ino: rootStats.ino,
+                size: rootStats.size,
+                mtimeNs: rootStats.mtimeNs,
+                ctimeNs: rootStats.ctimeNs
+            };
+        }
+        catch (error) {
+            return errorCode(error) === "ENOENT"
+                ? { status: "rootNotFound" }
+                : { status: "rootUnreadable" };
+        }
+        const normalizedPath = input.relativePath.replaceAll("\\", "/");
+        if (normalizedPath.startsWith("/")
+            || /^[A-Za-z]:/.test(normalizedPath)
+            || normalizedPath.split("/").includes("..")) {
+            return { status: "escape" };
+        }
+        const candidate = resolve(canonicalRoot, normalizedPath);
+        if (!isContained(canonicalRoot, candidate)) {
+            return { status: "escape" };
+        }
+        let canonicalBefore;
+        let pathBefore;
+        try {
+            canonicalBefore = await realpath(candidate);
+            if (!isContained(canonicalRoot, canonicalBefore)) {
+                return { status: "escape" };
+            }
+            pathBefore = await pathIdentity(canonicalBefore);
+        }
+        catch (error) {
+            return evidenceFailure(error);
+        }
+        const resolvedRelativePath = normalizedRelativePath(canonicalRoot, canonicalBefore);
+        const openFlags = process.platform === "win32"
+            ? constants.O_RDONLY
+            : constants.O_RDONLY | constants.O_NOFOLLOW;
+        let handle;
+        try {
+            handle = await open(canonicalBefore, openFlags);
+        }
+        catch (error) {
+            return errorCode(error) === "ELOOP"
+                ? { status: "changedIdentity", resolvedRelativePath }
+                : evidenceFailure(error);
+        }
+        try {
+            const openedBefore = await fileIdentity(handle);
+            if (!sameIdentity(pathBefore, openedBefore)) {
+                return { status: "changedIdentity", resolvedRelativePath };
+            }
+            const openedStats = await handle.stat({ bigint: true });
+            if (!openedStats.isFile()) {
+                return { status: "notFile", resolvedRelativePath };
+            }
+            try {
+                const canonicalOpened = await realpath(candidate);
+                const rootOpened = await realpath(input.projectRoot);
+                const pathOpened = await pathIdentity(canonicalOpened);
+                if (canonicalOpened !== canonicalBefore
+                    || rootOpened !== canonicalRoot
+                    || !isContained(canonicalRoot, canonicalOpened)
+                    || !sameIdentity(openedBefore, pathOpened)) {
+                    return { status: "changedIdentity", resolvedRelativePath };
+                }
+            }
+            catch {
+                return { status: "changedIdentity", resolvedRelativePath };
+            }
+            const hash = createHash("sha256");
+            const buffer = Buffer.allocUnsafe(64 * 1024);
+            let totalBytes = 0;
+            let tooLarge = false;
+            while (totalBytes <= input.maximumBytes) {
+                const remaining = input.maximumBytes + 1 - totalBytes;
+                const bytesToRead = Math.min(buffer.byteLength, remaining);
+                const readResult = await handle.read(buffer, 0, bytesToRead, null);
+                if (readResult.bytesRead === 0) {
+                    break;
+                }
+                totalBytes += readResult.bytesRead;
+                hash.update(buffer.subarray(0, readResult.bytesRead));
+                if (totalBytes > input.maximumBytes) {
+                    tooLarge = true;
+                    break;
+                }
+            }
+            const openedAfter = await fileIdentity(handle);
+            let canonicalAfter;
+            let rootCanonicalAfter;
+            let pathAfter;
+            let rootAfter;
+            try {
+                canonicalAfter = await realpath(candidate);
+                rootCanonicalAfter = await realpath(input.projectRoot);
+                pathAfter = await pathIdentity(canonicalAfter);
+                rootAfter = await pathIdentity(canonicalRoot);
+            }
+            catch {
+                return { status: "changedIdentity", resolvedRelativePath };
+            }
+            if (canonicalAfter !== canonicalBefore
+                || rootCanonicalAfter !== canonicalRoot
+                || !isContained(canonicalRoot, canonicalAfter)
+                || !sameIdentity(openedBefore, openedAfter)
+                || !sameIdentity(openedAfter, pathAfter)
+                || !sameIdentity(rootBefore, rootAfter)) {
+                return { status: "changedIdentity", resolvedRelativePath };
+            }
+            return tooLarge
+                ? { status: "tooLarge", resolvedRelativePath }
+                : {
+                    status: "inspected",
+                    resolvedRelativePath,
+                    sha256: hash.digest("hex")
+                };
+        }
+        catch {
+            return { status: "unreadable" };
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    };
+}

package/dist/adapters/filesystem/skill-installer.d.ts

@@ -0,0 +1,10 @@
+import type { SkillInstallResult, SkillInstallerPort } from "../../ports/skill-installer.js";
+export declare class SkillPayloadMissingError extends Error {
+    readonly payloadPath: string;
+    readonly name = "SkillPayloadMissingError";
+    constructor(payloadPath: string);
+}
+export declare class FileSystemSkillInstaller implements SkillInstallerPort {
+    findPayload(): Promise<string>;
+    installTo(targetDir: string): Promise<SkillInstallResult>;
+}

package/dist/adapters/filesystem/skill-installer.js

@@ -0,0 +1,39 @@
+import { access, cp, mkdir } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SKILL_DIRECTORY_NAME } from "../../domain/init.js";
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const PAYLOAD_PATH = resolve(PACKAGE_ROOT, "assets", "skills", SKILL_DIRECTORY_NAME);
+export class SkillPayloadMissingError extends Error {
+    payloadPath;
+    name = "SkillPayloadMissingError";
+    constructor(payloadPath) {
+        super(`Skill payload not found at ${payloadPath}`);
+        this.payloadPath = payloadPath;
+    }
+}
+export class FileSystemSkillInstaller {
+    async findPayload() {
+        try {
+            await access(PAYLOAD_PATH, constants.R_OK);
+        }
+        catch {
+            throw new SkillPayloadMissingError(PAYLOAD_PATH);
+        }
+        return PAYLOAD_PATH;
+    }
+    async installTo(targetDir) {
+        const payloadPath = await this.findPayload();
+        const resolvedTarget = resolve(targetDir);
+        if (resolvedTarget === resolve(payloadPath)) {
+            return { targetPath: resolvedTarget, skipped: true };
+        }
+        await mkdir(dirname(resolvedTarget), { recursive: true });
+        await cp(payloadPath, resolvedTarget, {
+            recursive: true,
+            force: true
+        });
+        return { targetPath: resolvedTarget, skipped: false };
+    }
+}

package/dist/adapters/process/node-process-runner.d.ts

@@ -0,0 +1,8 @@
+import type { CommandResult, CommandSpec, ProcessRunner, RunningCommand, StreamHandlers } from "../../ports/process-runner.js";
+export declare class NodeProcessRunner implements ProcessRunner {
+    private readonly defaultTimeoutMs;
+    private readonly streamStartupGraceMs;
+    constructor(defaultTimeoutMs?: number, streamStartupGraceMs?: number);
+    run(spec: CommandSpec): Promise<CommandResult>;
+    start(spec: CommandSpec, handlers?: StreamHandlers): RunningCommand;
+}