rea-agents 6.3.0 → 6.5.0

package/dist/application/ReferenceSourceImportPolicy.js

@@ -1,49 +1,125 @@
-import { readFile, realpath, stat } from "node:fs/promises";
+import { lstat, realpath, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import ignore from "ignore";
+import { readRegularFileText, RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
 import { err, ok } from "../domain/result.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS, } from "./ReferenceSourceImportTypes.js";
+import { rootFilesystemFailure } from "../reference/ReferenceSourceReaderErrors.js";
 const failure = (code, message) => ({
     tag: "reference-source-import",
     code,
     message,
 });
-const resolveRoot = async (requestedRoot) => {
+const isAborted = (signal) => signal?.aborted === true;
+const addMarkedPatterns = (matcher, patterns, mark) => {
+    for (const pattern of patterns)
+        for (const line of pattern.split(/\r?\n/u))
+            matcher.add({ pattern: line, mark });
+};
+const resolveRoot = async (requestedRoot, signal) => {
+    if (isAborted(signal))
+        return err(failure("cancelled", "Reference source import cancelled"));
     try {
-        if (!(await stat(requestedRoot)).isDirectory())
-            return err(failure("invalid-root", "Reference source root is not a directory"));
+        const metadata = await stat(requestedRoot);
+        if (isAborted(signal))
+            return err(failure("cancelled", "Reference source import cancelled"));
+        if (!metadata.isDirectory())
+            return err(failure("invalid-root", `Reference source root is not a directory: ${requestedRoot}`));
         const canonicalRoot = await realpath(resolve(requestedRoot));
+        if (isAborted(signal))
+            return err(failure("cancelled", "Reference source import cancelled"));
         return ok(canonicalRoot);
     }
     catch (cause) {
-        void cause;
-        return err(failure("invalid-root", "Reference source root could not be resolved"));
+        if (isAborted(signal))
+            return err(failure("cancelled", "Reference source import cancelled"));
+        const rootFailure = rootFilesystemFailure(cause, "Reference source root could not be resolved");
+        if (rootFailure === undefined)
+            throw cause;
+        return err({ ...failure(rootFailure.code, rootFailure.message), cause });
     }
 };
-const buildIgnored = async (root, excludePaths) => {
+const buildIgnored = async (root, excludePaths, resources, signal) => {
     const ignored = ignore();
+    const policyPath = join(root, ".gitignore");
+    let present = true;
     try {
-        ignored.add(await readFile(join(root, ".gitignore"), "utf8"));
+        await lstat(policyPath);
     }
     catch (cause) {
-        // Missing or unreadable ignore file does not authorize broader access.
-        void cause;
+        if (!(typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            cause.code === "ENOENT"))
+            throw cause;
+        present = false;
+    }
+    signal?.throwIfAborted();
+    if (present) {
+        let text;
+        try {
+            text = await readRegularFileText(policyPath, { signal });
+        }
+        catch (cause) {
+            if (!(cause instanceof RegularFileCleanupFailure))
+                throw cause;
+            const retry = await retryRegularFileCleanup(cause, resources);
+            if (retry.cleanup !== undefined) {
+                const primary = cause.outcome.kind === "failed"
+                    ? cause.outcome.cause
+                    : cause.cleanupCause;
+                return err({
+                    ...failure(signal?.aborted === true ? "cancelled" : "io", `Reference source ignore policy could not be read at ${policyPath}: ${errorMessage(primary)}`),
+                    cleanup: retry.cleanup,
+                    cause: primary,
+                });
+            }
+            if (retry.outcome.kind === "failed")
+                throw retry.outcome.cause;
+            text = retry.outcome.value;
+        }
+        addMarkedPatterns(ignored, [text], "project-ignored");
     }
-    ignored.add([...DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS]);
+    addMarkedPatterns(ignored, DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS, "default-ignored");
     for (const path of excludePaths) {
-        ignored.add(path);
-        ignored.add(`${path}/`);
+        addMarkedPatterns(ignored, [path, `${path}/`], "caller-excluded");
     }
-    return ignored;
+    return ok(ignored);
 };
 /** Resolve the caller-selected directory and build path filters. */
-export const prepareReferenceSourceImport = async (options) => {
-    const root = await resolveRoot(options.root);
-    if (!root.ok)
-        return root;
-    return ok({
-        root: root.value,
-        ignored: await buildIgnored(root.value, options.excludePaths ?? []),
-        secrets: ignore().add([...options.policy.secretPatterns]),
-    });
+export const prepareReferenceSourceImport = async (options, resources) => {
+    try {
+        return await resources.run(async () => {
+            const root = await resolveRoot(options.root, options.signal);
+            if (!root.ok)
+                return root;
+            try {
+                const ignored = await buildIgnored(root.value, options.excludePaths ?? [], resources, options.signal);
+                if (!ignored.ok)
+                    return ignored;
+                return ok({
+                    root: root.value,
+                    ignored: ignored.value,
+                    secrets: ignore().add([...options.policy.secretPatterns]),
+                });
+            }
+            catch (cause) {
+                return err({
+                    ...failure(options.signal?.aborted === true ? "cancelled" : "io", `Reference source ignore policy could not be read at ${join(root.value, ".gitignore")}: ${errorMessage(cause)}`),
+                    cause,
+                });
+            }
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof ArtifactReaderFailure))
+            throw cause;
+        return err({
+            ...failure(cause.reason === "cancelled" ? "cancelled" : "io", cause.message),
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            cause,
+        });
+    }
 };
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/application/ReferenceSourceImportTypes.js

@@ -1,28 +1,36 @@
+const IMPORT_FAILURE_GUIDANCE = {
+    cancelled: {
+        category: "cancelled",
+        message: "Reference source import was cancelled. Start it again when ready.",
+    },
+    "invalid-root": {
+        category: "invalid_input",
+        message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
+    },
+    unsupported: {
+        category: "unsupported_host",
+        message: "Safe no-follow file opens are unavailable on this host. Import the source tree with REA on Linux (including WSL) or macOS.",
+    },
+    io: {
+        category: "execution_failure",
+        message: "Reference source files could not be read. Check directory permissions and try again.",
+    },
+    parse: {
+        category: "execution_failure",
+        message: "Reference source could not be indexed. Check that the source tree is readable, then try again.",
+    },
+};
 /** Safe CLI projection for a historical-source import failure. */
 export const projectReferenceSourceImportError = (error) => {
-    if (error.code === "cancelled")
-        return {
-            category: "cancelled",
-            message: "Reference source import was cancelled. Start it again when ready.",
-        };
-    if (error.code === "invalid-root")
-        return {
-            category: "invalid_input",
-            message: "Reference source directory could not be opened. Check that the path exists, is readable, and points to a directory.",
-        };
-    if (error.code === "unsupported")
-        return {
-            category: "unsupported_host",
-            message: "Safe no-follow file opens are unavailable on this host. Import the source tree with REA on Linux (including WSL) or macOS.",
-        };
-    if (error.code === "io")
-        return {
-            category: "execution_failure",
-            message: "Reference source files could not be read. Check directory permissions and try again.",
-        };
+    const primary = IMPORT_FAILURE_GUIDANCE[error.code];
+    const cleanupMessage = error.cleanup === undefined
+        ? ""
+        : ` Cleanup failed during import for ${error.cleanup.resources.join(", ")}: ${error.cleanup.reason}.`;
     return {
-        category: "execution_failure",
-        message: "Reference source could not be indexed. Check that the source tree is readable, then try again.",
+        category: primary.category,
+        message: `${error.message} ${primary.message}${cleanupMessage}`,
+        ...(error.cleanup === undefined ? {} : { cleanup: error.cleanup }),
+        ...(error.partial === undefined ? {} : { partial: error.partial }),
     };
 };
 export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [
@@ -36,4 +44,3 @@ export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [
     ".coverage",
     "*.log",
 ];
-export const PARSEABLE_REFERENCE_SOURCE_LANGUAGES = new Set(["JavaScript", "TypeScript", "JSX", "TSX"]);

package/dist/application/ReferenceSourceVcsAdapter.js

@@ -1,60 +1,191 @@
 import fs from "node:fs";
-import { lstat, readFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { resolveRef } from "isomorphic-git";
+import { lstat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { err, ok } from "../domain/result.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { readRegularFile, RegularFileCleanupFailure, retryRegularFileCleanup, } from "./RegularFileRead.js";
 /**
  * Read Git metadata for a directory using isomorphic-git.
  *
  * No git subprocess or network is used; only the local `.git` object store is read.
  */
-export const readReferenceSourceVcs = async (root, signal) => {
-    if (isAborted(signal))
-        return { kind: "unknown", head: null, dirty: null };
+export const readReferenceSourceVcs = async (root, resources, signal) => {
     try {
-        await lstat(join(root, ".git"));
+        return await resources.run(async () => {
+            // Like Git, a subdirectory belongs to its nearest enclosing repository;
+            // only a missing `.git` at every ancestor means no version control.
+            let repository = resolve(root);
+            for (;;) {
+                if (isAborted(signal))
+                    return ok(unknownVcs());
+                try {
+                    await lstat(join(repository, ".git"));
+                    break;
+                }
+                catch (cause) {
+                    if (errorCode(cause) !== "ENOENT")
+                        return ok(unknownVcs());
+                }
+                const parent = dirname(repository);
+                if (parent === repository)
+                    return ok({ kind: "none", head: null, dirty: null });
+                repository = parent;
+            }
+            try {
+                const head = await resolveSourceHead(repository, resources, signal);
+                if (isAborted(signal))
+                    return ok(unknownVcs());
+                return ok({ kind: "git", head, dirty: null });
+            }
+            catch (cause) {
+                if (cause instanceof ArtifactReaderFailure)
+                    throw cause;
+                return ok(unknownVcs());
+            }
+        });
     }
     catch (cause) {
-        return errorCode(cause) === "ENOENT"
-            ? { kind: "none", head: null, dirty: null }
-            : { kind: "unknown", head: null, dirty: null };
-    }
-    try {
-        const head = await resolveSourceHead(root);
-        if (isAborted(signal))
-            return { kind: "unknown", head: null, dirty: null };
-        return { kind: "git", head, dirty: null };
-    }
-    catch (cause) {
-        // Unresolvable refs mean VCS state is unknown, not absent.
-        void cause;
-        return { kind: "unknown", head: null, dirty: null };
+        if (!(cause instanceof ArtifactReaderFailure))
+            throw cause;
+        return err({
+            tag: "reference-source-reader",
+            code: cause.reason === "cancelled" ? "cancelled" : "io",
+            message: cause.message,
+            ...(cause.cleanup === undefined ? {} : { cleanup: cause.cleanup }),
+            cause,
+        });
     }
 };
-const resolveSourceHead = async (root) => {
+const unknownVcs = () => ({
+    kind: "unknown",
+    head: null,
+    dirty: null,
+});
+const resolveSourceHead = async (root, resources, signal) => {
+    // isomorphic-git is loaded on first use so CLI and MCP startup skip it.
+    const { resolveRef } = await import("isomorphic-git");
+    let failedRead;
+    const cleanupFailures = [];
+    const readMetadataBytes = async (path) => {
+        try {
+            return await readRegularFile(path, { signal });
+        }
+        catch (cause) {
+            if (!(cause instanceof RegularFileCleanupFailure))
+                throw cause;
+            const retry = await retryRegularFileCleanup(cause, resources);
+            if (retry.outcome.kind === "failed" &&
+                errorCode(retry.outcome.cause) !== "ENOENT")
+                failedRead ??= { cause: retry.outcome.cause };
+            if (retry.cleanup === undefined &&
+                retry.outcome.kind === "failed" &&
+                !isAborted(signal))
+                throw retry.outcome.cause;
+            const primary = retry.outcome.kind === "failed"
+                ? retry.outcome.cause
+                : cause.cleanupCause;
+            throw new ArtifactReaderFailure(isAborted(signal) ? "cancelled" : "io", `Git metadata could not be read safely: ${errorMessage(primary)}`, {
+                cause: primary,
+                ...(retry.cleanup === undefined ? {} : { cleanup: retry.cleanup }),
+            });
+        }
+    };
+    const readMetadataText = async (path) => (await readMetadataBytes(path)).toString("utf8");
+    const throwCleanupFailures = (primary) => {
+        const observations = cleanupFailures.flatMap((failure) => failure.cleanup === undefined ? [] : [failure.cleanup]);
+        throw new ArtifactReaderFailure(isAborted(signal) ? "cancelled" : "io", `Git metadata could not be read safely: ${errorMessage(primary)}`, {
+            cause: new AggregateError([primary, ...cleanupFailures], "Git metadata reads and cleanup failed", { cause: primary }),
+            ...(observations.length === 0
+                ? {}
+                : {
+                    cleanup: {
+                        reason: observations.map(({ reason }) => reason).join("; "),
+                        resources: [
+                            ...new Set(observations.flatMap(({ resources }) => resources)),
+                        ],
+                    },
+                }),
+        });
+    };
+    const referenceFs = {
+        ...fs,
+        promises: {
+            ...fs.promises,
+            // Let isomorphic-git continue from a failed loose ref to packed-refs,
+            // then report the original read failure after resolution. This preserves
+            // both observations when packed metadata also fails cleanup.
+            readFile: async (path, options = null) => {
+                // The library probes readFile() without a path to detect promise APIs.
+                // Reject that invocation without attributing it to a source read.
+                if (path === undefined)
+                    throw new TypeError("Git metadata path is required");
+                try {
+                    const bytes = await readMetadataBytes(path);
+                    const encoding = typeof options === "string"
+                        ? options
+                        : typeof options === "object" &&
+                            options !== null &&
+                            "encoding" in options
+                            ? options.encoding
+                            : undefined;
+                    if (encoding === undefined || encoding === null)
+                        return bytes;
+                    if (typeof encoding !== "string" || !Buffer.isEncoding(encoding))
+                        throw new TypeError("Unsupported Git metadata text encoding");
+                    return bytes.toString(encoding);
+                }
+                catch (cause) {
+                    if (cause instanceof ArtifactReaderFailure) {
+                        cleanupFailures.push(cause);
+                    }
+                    else if (errorCode(cause) !== "ENOENT")
+                        failedRead ??= { cause };
+                    throw cause;
+                }
+            },
+        },
+    };
+    const readRef = async (options) => {
+        let head;
+        try {
+            head = await resolveRef({ fs: referenceFs, dir: root, ...options });
+        }
+        catch (cause) {
+            if (cleanupFailures.length > 0)
+                throwCleanupFailures(failedRead?.cause ?? cause);
+            if (failedRead !== undefined)
+                throw failedRead.cause;
+            throw cause;
+        }
+        if (cleanupFailures.length > 0)
+            throwCleanupFailures(failedRead?.cause ?? cleanupFailures[0]?.cause);
+        signal?.throwIfAborted();
+        if (failedRead !== undefined)
+            throw failedRead.cause;
+        return head;
+    };
     const dotgit = join(root, ".git");
     if (!(await lstat(dotgit)).isFile())
-        return resolveRef({ fs, dir: root, ref: "HEAD" });
-    const pointer = (await readFile(dotgit, "utf8")).replace(/\r?\n$/u, "");
+        return readRef({ ref: "HEAD" });
+    const pointer = (await readMetadataText(dotgit)).replace(/\r?\n$/u, "");
     if (!pointer.startsWith("gitdir: ") || pointer.length === 8)
         throw new Error("Invalid Git directory pointer");
     const gitdir = resolve(root, pointer.slice(8));
     let commonDirectory;
     try {
-        commonDirectory = resolve(gitdir, (await readFile(join(gitdir, "commondir"), "utf8")).replace(/\r?\n$/u, ""));
+        commonDirectory = resolve(gitdir, (await readMetadataText(join(gitdir, "commondir"))).replace(/\r?\n$/u, ""));
     }
     catch (cause) {
         if (errorCode(cause) !== "ENOENT")
             throw cause;
-        return resolveRef({ fs, dir: root, gitdir, ref: "HEAD" });
+        return readRef({ gitdir, ref: "HEAD" });
     }
-    const head = (await readFile(join(gitdir, "HEAD"), "utf8")).trim();
+    const head = (await readMetadataText(join(gitdir, "HEAD"))).trim();
     if (!head.startsWith("ref: "))
-        return resolveRef({ fs, dir: root, gitdir, ref: "HEAD" });
+        return readRef({ gitdir, ref: "HEAD" });
     const ref = head.slice(5);
     const privateRef = ["refs/bisect/", "refs/rewritten/", "refs/worktree/"].some((prefix) => ref.startsWith(prefix));
-    return resolveRef({
-        fs,
-        dir: root,
+    return readRef({
         gitdir: privateRef ? gitdir : commonDirectory,
         ref,
     });
@@ -62,4 +193,5 @@ const resolveSourceHead = async (root) => {
 const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
     ? String(cause.code)
     : undefined;
+const errorMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 const isAborted = (signal) => signal?.aborted === true;

package/dist/application/RegularFileRead.js

@@ -1,17 +1,131 @@
-import { openRegularFile } from "../filesystem/RegularFile.js";
+import { lstat, stat } from "node:fs/promises";
+import { RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, RegularFileChangedError, } from "../filesystem/RegularFile.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+export class InvalidUtf8FileError extends TypeError {
+    path;
+    _tag = "InvalidUtf8FileError";
+    constructor(path, cause) {
+        super(`File is not valid UTF-8: ${path}`, { cause });
+        this.path = path;
+        this.name = this._tag;
+    }
+}
+/** A close failed after reading; this error transfers the exact handle owner. */
+export class RegularFileCleanupFailure extends Error {
+    path;
+    owner;
+    outcome;
+    cleanupCause;
+    constructor(path, owner, outcome, cleanupCause) {
+        super(`Regular file cleanup failed: ${path}`, {
+            cause: outcome.kind === "failed" ? outcome.cause : cleanupCause,
+        });
+        this.path = path;
+        this.owner = owner;
+        this.outcome = outcome;
+        this.cleanupCause = cleanupCause;
+        this.name = "RegularFileCleanupFailure";
+    }
+}
+/** Retry a failed close through its retained owner and report any remaining cleanup. */
+export const retryRegularFileCleanup = async (failure, resources) => {
+    const released = await resources.release({
+        kind: "file-handle",
+        handle: failure.owner,
+        resource: failure.path,
+    });
+    if (released.kind === "released")
+        return { outcome: failure.outcome };
+    return {
+        outcome: failure.outcome,
+        cleanup: {
+            reason: `${failureMessage(failure.cleanupCause)}; retry: ${failureMessage(released.cause)}`,
+            resources: [failure.path],
+        },
+    };
+};
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
 /** Admit one regular-file handle, retain it through the consumer, and always close it. */
-export const withRegularFile = async (path, read, signal) => {
-    const handle = await openRegularFile(path, { symlinks: "follow", signal });
+export const withRegularFile = async (path, read, options = {}) => options.resources === undefined
+    ? withRegularFileOwned(path, read, options)
+    : options.resources.run(() => withRegularFileOwned(path, read, options));
+const withRegularFileOwned = async (path, read, options) => {
+    const { signal } = options;
+    let handle;
+    try {
+        handle = await openRegularFile(path, {
+            symlinks: options.symlinks ?? "follow",
+            signal,
+        });
+    }
+    catch (cause) {
+        if (!(cause instanceof RegularFileAdmissionFailure))
+            throw cause;
+        const failure = new RegularFileCleanupFailure(path, cause.owner, { kind: "failed", cause: cause.cause }, cause.cleanupCause);
+        if (options.resources === undefined)
+            throw failure;
+        const retry = await retryRegularFileCleanup(failure, options.resources);
+        if (retry.cleanup !== undefined)
+            throw failure;
+        throw cause.cause;
+    }
+    const owner = new OwnedFileHandle(handle);
+    let outcome;
     try {
         const stats = await handle.stat();
         signal?.throwIfAborted();
         const value = await read(handle, stats);
         signal?.throwIfAborted();
-        return value;
+        const [opened, currentPath] = await Promise.all([
+            handle.stat(),
+            options.symlinks === "reject" ? lstat(path) : stat(path),
+        ]);
+        if (!sameRegularFileState(stats, opened) ||
+            !sameRegularFileState(stats, currentPath))
+            throw new RegularFileChangedError(path);
+        outcome = { kind: "completed", value };
     }
-    finally {
-        await handle.close();
+    catch (cause) {
+        outcome = { kind: "failed", cause };
     }
+    try {
+        await owner.close();
+    }
+    catch (cleanupCause) {
+        const failure = new RegularFileCleanupFailure(path, owner, outcome, cleanupCause);
+        if (options.resources === undefined)
+            throw failure;
+        const retry = await retryRegularFileCleanup(failure, options.resources);
+        if (retry.cleanup !== undefined)
+            throw failure;
+        if (retry.outcome.kind === "failed")
+            throw retry.outcome.cause;
+        return retry.outcome.value;
+    }
+    if (outcome.kind === "failed")
+        throw outcome.cause;
+    return outcome.value;
 };
 /** Admit a regular file without waiting for a pipe, then read its verified handle. */
-export const readRegularFile = (path, signal) => withRegularFile(path, (handle) => handle.readFile({ signal }), signal);
+export const readRegularFile = (path, options = {}) => readRegularFileContent(path, (bytes) => bytes, options);
+/** Read valid UTF-8 without replacing source bytes or stripping an initial BOM. */
+export const readRegularFileText = (path, options = {}) => readRegularFileContent(path, (bytes) => {
+    try {
+        return new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: true,
+        }).decode(bytes);
+    }
+    catch (cause) {
+        if (!(cause instanceof TypeError))
+            throw cause;
+        throw new InvalidUtf8FileError(path, cause);
+    }
+}, options);
+const readRegularFileContent = (path, decode, options) => withRegularFile(path, async (handle, stats) => {
+    const bytes = await readBoundedFileBytes(handle, stats.size, options.signal);
+    if (bytes === undefined || bytes.length !== stats.size)
+        throw new RegularFileChangedError(path);
+    return decode(bytes);
+}, options);