rea-agents 6.3.0 → 6.4.0

package/dist/artifacts/DirectoryArtifactReader.js

@@ -1,21 +1,24 @@
 import { constants } from "node:fs";
-import { lstat, open, opendir, realpath } from "node:fs/promises";
+import { lstat, open, opendir, realpath, } from "node:fs/promises";
 import { isAbsolute, join, relative, sep } from "node:path";
-import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+import { Readable } from "node:stream";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
-/** Deterministic, non-symlink-following directory reader. */
+import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
+/** Non-symlink-following directory reader. */
 export class DirectoryArtifactReader {
     format = "directory";
     #rootPromise;
     #rootPath;
+    #directories = new Set();
+    #files = new Map();
     constructor(root) {
         this.#rootPath = root;
-        this.#rootPromise = realpath(root);
     }
-    async *entries(signal) {
-        const root = await this.#rootPromise.catch((cause) => {
-            throw directoryIoFailure("resolve artifact root", this.#rootPath, cause);
-        });
+    /** Enumerate entries, optionally restricting descent while retaining directories. */
+    async *entries(signal, descendInto) {
+        const root = await this.#resolveRoot();
         const pending = [root];
         while (pending.length > 0) {
             abortIfNeeded(signal);
@@ -23,74 +26,84 @@ export class DirectoryArtifactReader {
             if (directory === undefined)
                 break;
             await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
-            const children = [];
-            const handle = await opendir(directory).catch((cause) => {
-                throw directoryIoFailure("open directory", directory, cause);
-            });
-            try {
-                for await (const child of handle)
-                    children.push(child.name);
-            }
-            catch (cause) {
-                throw directoryIoFailure("read directory", directory, cause);
-            }
-            finally {
-                // best-effort cleanup: directory-handle close must not mask traversal.
-                await handle.close().catch(() => undefined);
-            }
+            for await (const entry of this.#readDirectory(directory, pending, signal, descendInto))
+                yield entry;
             await withDirectoryIoContext("inspect directory", directory, () => assertContainedDirectory(root, directory));
-            children.sort(compareUnicodeCodePoints);
-            const directories = [];
-            for (const name of children) {
+        }
+    }
+    async #resolveRoot() {
+        return (this.#rootPromise ??= realpath(this.#rootPath)).catch((cause) => {
+            throw directoryIoFailure("resolve artifact root", this.#rootPath, cause);
+        });
+    }
+    async *#readDirectory(directory, pending, signal, descendInto) {
+        const root = await this.#resolveRoot();
+        const handle = new OwnedDirectoryHandle(await opendir(directory).catch((cause) => {
+            throw directoryIoFailure("open directory", directory, cause);
+        }));
+        this.#directories.add(handle);
+        const childDirectories = [];
+        let traversal = {
+            kind: "complete",
+        };
+        try {
+            for (;;) {
+                const child = await handle.handle.read();
+                if (child === null)
+                    break;
                 abortIfNeeded(signal);
-                const absolute = join(directory, name);
+                const absolute = join(directory, child.name);
                 const metadata = await lstat(absolute).catch((cause) => {
                     throw directoryIoFailure("inspect entry", absolute, cause);
                 });
                 const path = relative(root, absolute).split(sep).join("/");
-                const kind = metadata.isSymbolicLink()
-                    ? "symlink"
-                    : metadata.isDirectory()
-                        ? "directory"
-                        : metadata.isFile()
-                            ? "file"
-                            : undefined;
-                if (kind === undefined)
+                const entry = artifactEntry(path, absolute, metadata);
+                if (entry === undefined)
                     continue;
-                if (kind === "directory")
-                    directories.push(absolute);
-                yield {
-                    path,
-                    kind,
-                    declaredSize: kind === "file" ? metadata.size : null,
-                    compressedSize: null,
-                    executable: (metadata.mode & 0o111) !== 0,
-                    encrypted: false,
-                    byteOffset: null,
-                    declaredSha256: null,
-                    unpacked: false,
-                    limitations: kind === "symlink"
-                        ? ["Symlink target was not followed or disclosed."]
-                        : [],
-                    adapterKey: absolute,
-                    ...(kind === "file"
-                        ? { sourceIdentity: { device: metadata.dev, inode: metadata.ino } }
-                        : {}),
-                };
+                yield entry;
+                if (entry.kind === "directory" && (descendInto?.(path) ?? true))
+                    childDirectories.push(absolute);
             }
-            directories.reverse();
-            pending.push(...directories);
+        }
+        catch (cause) {
+            traversal = {
+                kind: "failed",
+                cause: cause instanceof ArtifactReaderFailure
+                    ? cause
+                    : directoryIoFailure("read directory", directory, cause),
+            };
+        }
+        finally {
+            await this.#finishDirectory(handle, directory, traversal);
+        }
+        if (traversal.kind === "failed")
+            throw traversal.cause;
+        childDirectories.reverse();
+        pending.push(...childDirectories);
+    }
+    async #finishDirectory(handle, path, traversal) {
+        try {
+            await handle.close();
+            this.#directories.delete(handle);
+        }
+        catch (cause) {
+            const closeFailure = directoryIoFailure("close directory", path, cause);
+            if (traversal.kind === "failed")
+                throw ArtifactReaderFailure.withCleanup(traversal.cause, ArtifactReaderFailure.cleanupObservation(closeFailure, path));
+            throw closeFailure;
         }
     }
     async open(entry, signal) {
         abortIfNeeded(signal);
         if (entry.kind !== "file")
             throw new ArtifactReaderFailure("format", "Only regular files can be opened");
-        const handle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch((cause) => {
+        const fileHandle = await open(entry.adapterKey, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch((cause) => {
             throw directoryIoFailure("open entry", entry.adapterKey, cause);
         });
+        const owner = new OwnedFileHandle(fileHandle);
+        this.#files.set(owner, entry.adapterKey);
         try {
-            const observed = await handle.stat().catch((cause) => {
+            const observed = await owner.handle.stat().catch((cause) => {
                 throw directoryIoFailure("inspect opened entry", entry.adapterKey, cause);
             });
             if (!observed.isFile() ||
@@ -99,21 +112,95 @@ export class DirectoryArtifactReader {
                 observed.ino !== entry.sourceIdentity.inode) {
                 throw new ArtifactReaderFailure("integrity", `Directory entry changed before open: ${entry.path}`);
             }
-            return handle.createReadStream({ autoClose: true });
+            abortIfNeeded(signal);
+            const source = Readable.from(mapFileReadCancellation(owner.handle, signal), { objectMode: false });
+            source.once("close", () => {
+                void this.#closeFile(owner).catch(() => undefined);
+            });
+            return source;
         }
         catch (cause) {
-            // best-effort cleanup: file-handle close must not mask the open failure.
-            await handle.close().catch(() => undefined);
+            try {
+                await this.#closeFile(owner);
+            }
+            catch (closeCause) {
+                throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(directoryIoFailure("close opened entry", entry.adapterKey, closeCause), entry.adapterKey));
+            }
             throw cause;
         }
     }
-    close() {
-        return Promise.resolve();
+    async close() {
+        const failures = [];
+        for (const [owner, path] of this.#files) {
+            try {
+                await this.#closeFile(owner);
+            }
+            catch (cause) {
+                failures.push(directoryIoFailure("close opened entry", path, cause));
+            }
+        }
+        for (const owner of this.#directories) {
+            try {
+                await owner.close();
+                this.#directories.delete(owner);
+            }
+            catch (cause) {
+                failures.push(directoryIoFailure("close directory", owner.handle.path, cause));
+            }
+        }
+        if (failures.length > 0) {
+            const reason = failures.map(failureMessage).join("; ");
+            throw new ArtifactReaderFailure("io", `Directory artifact cleanup failed: ${reason}`, {
+                cause: new AggregateError(failures),
+                cleanup: {
+                    reason,
+                    resources: [
+                        ...this.#files.values(),
+                        ...[...this.#directories].map((owner) => owner.handle.path),
+                    ],
+                },
+            });
+        }
+    }
+    async #closeFile(owner) {
+        await owner.close();
+        this.#files.delete(owner);
     }
     provenance() {
         return [];
     }
 }
+const artifactEntry = (path, absolute, metadata) => {
+    const kind = metadata.isSymbolicLink()
+        ? "symlink"
+        : metadata.isDirectory()
+            ? "directory"
+            : metadata.isFile()
+                ? "file"
+                : undefined;
+    if (kind === undefined)
+        return undefined;
+    return {
+        path,
+        kind,
+        declaredSize: kind === "file" ? metadata.size : null,
+        compressedSize: null,
+        executable: (metadata.mode & 0o111) !== 0,
+        encrypted: false,
+        byteOffset: null,
+        declaredSha256: null,
+        unpacked: false,
+        limitations: kind === "symlink"
+            ? ["Symlink target was not followed or disclosed."]
+            : [],
+        adapterKey: absolute,
+        ...(kind === "file"
+            ? {
+                sourceIdentity: { device: metadata.dev, inode: metadata.ino },
+            }
+            : {}),
+    };
+};
 const directoryIoFailure = (operation, path, cause) => {
     if (cause instanceof ArtifactReaderFailure)
         return cause;
@@ -123,7 +210,23 @@ const directoryIoFailure = (operation, path, cause) => {
         typeof cause.code === "string"
         ? ` (${cause.code})`
         : "";
-    return new ArtifactReaderFailure("io", `Could not ${operation} at ${path}${code}`, { cause });
+    const detail = failureMessage(cause);
+    return new ArtifactReaderFailure("io", `Could not ${operation} at ${path}${code}: ${detail}`, { cause });
+};
+const failureMessage = (cause) => cause instanceof Error ? cause.message : String(cause);
+const mapFileReadCancellation = async function* (handle, signal) {
+    try {
+        for await (const chunk of readFileHandleChunks(handle, { signal })) {
+            abortIfNeeded(signal);
+            yield chunk;
+        }
+        abortIfNeeded(signal);
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw new ArtifactReaderFailure("cancelled", "Directory artifact read cancelled", { cause });
+        throw cause;
+    }
 };
 const withDirectoryIoContext = async (operation, path, action) => {
     try {

package/dist/artifacts/MachOSliceArtifactReader.js

@@ -1,22 +1,36 @@
-import { createReadStream } from "node:fs";
-import { open as openFile, stat } from "node:fs/promises";
+import { lstat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { XcrunCommandRunner, } from "../native/CommandRunner.js";
 import { parseLipoArchitectures, } from "../native/parsers/lipo.js";
+import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
 import { readMachoImage } from "./apple/MachoLoadCommandReader.js";
-import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+import { ArtifactReaderFailure, copyArtifactEntry, sameArtifactEntry, } from "./ArtifactReader.js";
 import { streamChunkToBuffer } from "./StreamBytes.js";
+import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
 /** Read-only universal Mach-O slice reader backed by native lipo metadata. */
 export class MachOSliceArtifactReader {
     path;
     runner;
     format = "file";
     #command;
-    constructor(path, environment, runner = new XcrunCommandRunner(environment)) {
+    #source;
+    #ownedSource;
+    #pendingSource;
+    #entries = new Map();
+    #ownsSource;
+    #closed = false;
+    #closePromise;
+    constructor(path, environment, runner = new XcrunCommandRunner(environment), source) {
         this.path = path;
         this.runner = runner;
+        this.#source = source;
+        this.#ownsSource = source === undefined;
     }
     async *entries(signal) {
+        this.#entries.clear();
+        const source = await this.#ensureSource();
+        await this.#verifySource(source);
         const captured = await this.runner.run("lipo", ["-detailed_info", this.path], signal === undefined ? {} : { signal });
         if (!captured.ok)
             throw new ArtifactReaderFailure(captured.error.reason === "cancelled" ? "cancelled" : "unavailable", "lipo could not enumerate universal Mach-O slices", { cause: captured.error });
@@ -28,9 +42,11 @@ export class MachOSliceArtifactReader {
             exit_code: captured.value.exitCode,
             effects: ["read"],
         };
-        const fileSize = (await stat(this.path)).size;
+        await this.#verifySource(source);
+        const fileSize = source.initial.size;
         const architectures = parseLipoArchitectures(captured.value.stdout);
-        const structural = await readStructuralSlices(this.path, fileSize);
+        const structural = await readStructuralSlices(source.handle, fileSize);
+        await this.#verifySource(source);
         if (structural.status === "malformed")
             throw new ArtifactReaderFailure("integrity", `Mach-O structural slice index is malformed: ${structural.reason}`);
         if (structural.status === "unsupported")
@@ -63,7 +79,7 @@ export class MachOSliceArtifactReader {
                 !Number.isSafeInteger(offset + sliceSize) ||
                 offset + sliceSize > fileSize)
                 throw new ArtifactReaderFailure("integrity", `lipo reported an out-of-bounds Mach-O slice: ${architecture.name}`);
-            yield {
+            const entry = {
                 path: `slices/${architecture.name}`,
                 kind: "slice",
                 declaredSize: sliceSize,
@@ -99,33 +115,40 @@ export class MachOSliceArtifactReader {
                 ],
                 adapterKey: `${String(offset)}:${String(sliceSize)}`,
             };
+            this.#entries.set(entry.adapterKey, copyArtifactEntry(entry));
+            yield entry;
         }
     }
     async open(entry, signal) {
         if (signal?.aborted === true)
             return Promise.reject(new ArtifactReaderFailure("cancelled", "Mach-O slice read cancelled"));
-        const [offsetText, sizeText] = entry.adapterKey.split(":");
-        const offset = parseSliceKeyInteger(offsetText);
-        const size = parseSliceKeyInteger(sizeText);
-        if (!Number.isSafeInteger(offset) ||
-            !Number.isSafeInteger(size) ||
-            offset === null ||
+        const produced = this.#entries.get(entry.adapterKey);
+        if (produced === undefined || !sameArtifactEntry(entry, produced))
+            throw new ArtifactReaderFailure("integrity", "Mach-O slice entry metadata does not match this reader's inventory");
+        const offset = produced.byteOffset;
+        const size = produced.declaredSize;
+        if (offset === null ||
             size === null ||
+            !Number.isSafeInteger(offset) ||
+            !Number.isSafeInteger(size) ||
             offset < 0 ||
             size <= 0)
             throw new ArtifactReaderFailure("integrity", "Invalid Mach-O slice byte range");
-        const fileSize = (await stat(this.path)).size;
-        if (!Number.isSafeInteger(offset + size) || offset + size > fileSize)
+        const source = await this.#ensureSource();
+        await this.#verifySource(source);
+        if (!Number.isSafeInteger(offset + size) ||
+            offset + size > source.initial.size)
             throw new ArtifactReaderFailure("integrity", `Mach-O slice range is outside the artifact: ${entry.path}`);
-        const source = createReadStream(this.path, {
+        const sourceStream = readFileHandleChunks(source.handle, {
             start: offset,
             end: offset + size - 1,
             ...(signal === undefined ? {} : { signal }),
         });
+        const verifySource = () => this.#verifySource(source);
         return Readable.from((async function* () {
             let observedBytes = 0;
             try {
-                for await (const raw of source) {
+                for await (const raw of sourceStream) {
                     const chunk = streamChunkToBuffer(raw);
                     observedBytes += chunk.byteLength;
                     if (observedBytes > size)
@@ -142,30 +165,90 @@ export class MachOSliceArtifactReader {
             }
             if (observedBytes !== size)
                 throw new ArtifactReaderFailure("integrity", `Mach-O slice size disagrees with lipo metadata: ${entry.path}`);
+            await verifySource();
         })());
     }
     provenance() {
         return this.#command === undefined ? [] : [structuredClone(this.#command)];
     }
-    close() {
-        return Promise.resolve();
+    async close() {
+        this.#closed = true;
+        this.#closePromise ??= this.#closeSource().catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
     }
-}
-/** Compare lipo's independent ranges with structurally parsed slice identity. */
-const readStructuralSlices = async (path, size) => {
-    const file = await openFile(path, "r");
-    try {
-        const readAt = async (offset, length) => {
-            const bytes = Buffer.alloc(length);
-            const { bytesRead } = await file.read(bytes, 0, length, offset);
-            return bytes.subarray(0, bytesRead);
-        };
-        const facts = await readMachoImage(readAt, size);
-        return facts;
+    async #ensureSource() {
+        if (this.#closed)
+            throw new ArtifactReaderFailure("unavailable", "Universal Mach-O reader is closed");
+        if (this.#source !== undefined)
+            return this.#source;
+        this.#pendingSource ??= this.#acquireSource();
+        const source = await this.#pendingSource;
+        if (this.#closed)
+            throw new ArtifactReaderFailure("unavailable", "Universal Mach-O reader closed during source acquisition");
+        return source;
+    }
+    async #acquireSource() {
+        let handle;
+        try {
+            handle = await openRegularFile(this.path, { symlinks: "reject" });
+        }
+        catch (cause) {
+            if (!(cause instanceof RegularFileAdmissionFailure))
+                throw cause;
+            this.#ownedSource = cause.owner;
+            const primary = cause.cause instanceof NonRegularFileReadError
+                ? new ArtifactReaderFailure("format", `Universal Mach-O source is not a regular file: ${this.path}`, { cause: cause.cause })
+                : cause.cause;
+            throw ArtifactReaderFailure.withCleanup(primary, ArtifactReaderFailure.cleanupObservation(cause.cleanupCause, this.path));
+        }
+        const owner = new OwnedFileHandle(handle);
+        this.#ownedSource = owner;
+        try {
+            const initial = await handle.stat();
+            const source = { handle, initial };
+            this.#source = source;
+            return source;
+        }
+        catch (cause) {
+            try {
+                await owner.close();
+                this.#ownedSource = undefined;
+            }
+            catch (cleanupCause) {
+                throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(cleanupCause, this.path));
+            }
+            throw cause;
+        }
     }
-    finally {
-        await file.close();
+    async #closeSource() {
+        await this.#pendingSource?.catch(() => undefined);
+        if (!this.#ownsSource || this.#ownedSource === undefined)
+            return;
+        await this.#ownedSource.close();
+        this.#ownedSource = undefined;
+        this.#source = undefined;
     }
+    async #verifySource(source) {
+        const [opened, currentPath] = await Promise.all([
+            source.handle.stat(),
+            lstat(this.path),
+        ]);
+        if (!sameRegularFileState(source.initial, opened) ||
+            !sameRegularFileState(source.initial, currentPath))
+            throw new ArtifactReaderFailure("integrity", `Universal Mach-O source changed during inventory: ${this.path}`);
+    }
+}
+/** Compare lipo's independent ranges with structurally parsed slice identity. */
+const readStructuralSlices = async (file, size) => {
+    const readAt = async (offset, length) => {
+        const bytes = Buffer.alloc(length);
+        const { bytesRead } = await file.read(bytes, 0, length, offset);
+        return bytes.subarray(0, bytesRead);
+    };
+    return readMachoImage(readAt, size);
 };
 const lipoMatchesSlice = (reported, observed, structurallyUnique) => {
     const observedCpuType = observed.fat_cpu_type ?? observed.cpu_type;
@@ -194,9 +277,3 @@ const lipoMatchesSlice = (reported, observed, structurallyUnique) => {
  */
 const lipoNameMatches = (reported, observed) => reported === observed ||
     (observed === "arm64e" && /^arm64e\.[A-Za-z0-9_]+$/u.test(reported));
-const parseSliceKeyInteger = (value) => {
-    if (value === undefined || !/^\d+$/u.test(value))
-        return null;
-    const parsed = Number(value);
-    return Number.isSafeInteger(parsed) ? parsed : null;
-};

package/dist/artifacts/NativeDmgArtifactReader.js

@@ -49,9 +49,10 @@ const createSystemHost = (environment) => ({
 /** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */
 export class NativeDmgArtifactReader {
     path;
-    host;
     format = "file";
+    host;
     #provenance = [];
+    #initialization;
     #directory;
     #devices = [];
     #inventoryConfirmedDevices = new Set();
@@ -61,34 +62,41 @@ export class NativeDmgArtifactReader {
     #attachOutputReturned = false;
     #attachMayHaveMounted = false;
     #ownershipUncertainty;
-    constructor(path, host) {
+    #closed = false;
+    #closePromise;
+    constructor(path, environment, host) {
         this.path = path;
-        this.host = host;
-    }
-    /** Verify and attach one image beneath an exclusively owned temporary root. */
-    static async create(path, environment, signal, host) {
         if (process.platform !== "darwin" && host === undefined)
             throw new ArtifactReaderFailure("unavailable", "Native DMG traversal is available only on macOS");
-        const reader = new NativeDmgArtifactReader(path, host ?? createSystemHost(environment));
-        await reader.attach(signal);
-        return reader;
+        this.host = host ?? createSystemHost(environment);
     }
     async *entries(signal) {
+        await this.#ensureAttached(signal);
         if (this.#directory === undefined)
             throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
         const prefix = basename(this.path);
         for await (const entry of this.#directory.entries(signal))
             yield { ...entry, path: `${prefix}/${entry.path}` };
     }
-    open(entry, signal) {
+    async open(entry, signal) {
+        await this.#ensureAttached(signal);
         if (this.#directory === undefined)
-            return Promise.reject(new ArtifactReaderFailure("unavailable", "DMG is not attached"));
+            throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
         return this.#directory.open(entry, signal);
     }
     provenance() {
         return structuredClone(this.#provenance);
     }
-    async close() {
+    close() {
+        this.#closed = true;
+        this.#closePromise ??= this.#closeOwnedResources().catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    async #closeOwnedResources() {
+        await this.#initialization?.catch(() => undefined);
         let detachFailure = await this.#reconcileAttachState();
         let remainingDevices = [];
         for (const device of [...this.#devices].reverse()) {
@@ -190,7 +198,15 @@ export class NativeDmgArtifactReader {
             return true;
         }
     }
-    async attach(signal) {
+    async #ensureAttached(signal) {
+        if (this.#closed)
+            throw new ArtifactReaderFailure("unavailable", "DMG reader is closed");
+        this.#initialization ??= this.#attach(signal);
+        await this.#initialization;
+        if (this.#closed)
+            throw new ArtifactReaderFailure("unavailable", "DMG reader is closed");
+    }
+    async #attach(signal) {
         await runChecked(this.host, ["verify", this.path], signal);
         this.#provenance.push(command(["verify", this.path], ["read"]));
         const baseline = await this.#readInfo();
@@ -249,15 +265,6 @@ export class NativeDmgArtifactReader {
                 this.#attachMayHaveMounted = false;
                 this.#ownershipUncertainty = undefined;
             }
-            let cleanupFailure;
-            try {
-                await this.close();
-            }
-            catch (cleanupCause) {
-                cleanupFailure = cleanupCause;
-            }
-            if (cleanupFailure !== undefined)
-                throw ArtifactReaderFailure.withCleanup(cause, ArtifactReaderFailure.cleanupObservation(cleanupFailure, `DMG mount root ${this.#mountRoot ?? this.path}`));
             throw cause;
         }
     }