toolcraft 0.0.762 → 0.0.764

package/composition.json

@@ -133,7 +133,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.762",
+      "version": "0.0.764",
       "license": "MIT"
     },
     {
@@ -143,7 +143,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.762",
+      "version": "0.0.764",
       "license": "MIT"
     },
     {

package/dist/composition.json

@@ -133,7 +133,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.762",
+      "version": "0.0.764",
       "license": "MIT"
     },
     {
@@ -143,7 +143,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.762",
+      "version": "0.0.764",
       "license": "MIT"
     },
     {

package/node_modules/@poe-code/safe-fs/README.md

@@ -86,6 +86,7 @@ cause. Preserve cancellation/control exceptions separately. Cross-family
 | Change the namespace | `mkdir`, `rm`, `rename`, `copyFile` |
 | Remove an empty directory | Optional `rmdir`; never a recursive-delete fallback |
 | Links and metadata | Optional `readlink`, `symlink`, `link`, `chmod`, `utimes`, `truncate` |
+| Enumerate directories lazily | Optional `iterateDirectory`; memory and native backends, with readonly/quota/device/scoped delegation; backend order, no sorted-array fallback |
 | Stream bytes | Optional `readStream`, `writeStream`, using async iterables of byte chunks |
 | Retain an open file | Optional `open` with positioned I/O and synchronization; memory and real backends support `noFollow: true` to atomically refuse a final symlink |
 | Publish immutable objects atomically | Optional `publishFileConditional` with opaque identity/version stats and authoritative compare-and-publish |

package/node_modules/@poe-code/safe-fs/dist/contracts/filesystem.d.ts

@@ -352,6 +352,11 @@ export interface FileSystem {
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     compareEntry?(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    /** Optional bounded, lazy directory enumeration in backend-defined order.
+     * No complete listing/sort fallback. Consumers must retire the iterator on
+     * early exit. Namespace changes may reject or follow the backend's live view;
+     * this is not a tree snapshot or a retained path-authority grant. */
+    iterateDirectory?(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;
     /** Atomic final-entry removal; every directory is refused, including raced replacements. */

package/node_modules/@poe-code/safe-fs/dist/fs/devices/index.d.ts

@@ -25,6 +25,7 @@ export declare class DeviceFileSystem implements FileSystem {
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rm(path: string, options?: RemoveOptions): Promise<void>;

package/node_modules/@poe-code/safe-fs/dist/fs/devices/index.js

@@ -490,6 +490,40 @@ export class DeviceFileSystem {
             throw new FsError("ENOTSUP", { path });
         await this.#filesystem.writeStream(path, source, options);
     }
+    async *iterateDirectory(path, options = {}) {
+        const resolved = await this.#resolve(path, options);
+        if (resolved === nullPath)
+            throw new FsError("ENOTDIR", { syscall: "iterateDirectory", path });
+        const virtual = resolved === "/" ? "dev" : resolved === deviceDirectory ? "null" : undefined;
+        if (!this.#filesystem.iterateDirectory)
+            throw new FsError("ENOTSUP", { syscall: "iterateDirectory", path });
+        let seen = false;
+        try {
+            for await (const entry of this.#filesystem.iterateDirectory(virtual ? resolved : path, options)) {
+                options.signal?.throwIfAborted();
+                if (entry.name === "." || entry.name === "..")
+                    continue;
+                if (!entry.name || entry.name.includes("/") || entry.name.includes("\0"))
+                    throw new FsError("EIO", { path, message: "invalid directory entry" });
+                if (entry.name === virtual) {
+                    if (seen)
+                        continue;
+                    seen = true;
+                    yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+                }
+                else
+                    yield { name: entry.name, type: entry.type };
+            }
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (!virtual || !isFsError(error, "ENOENT") && !isFsError(error, "ENOTDIR"))
+                throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (virtual && !seen)
+            yield { name: virtual, type: virtual === "dev" ? "directory" : "character" };
+    }
     readdir(path, options = {}) {
         const fast = this.#tryResolveSync(path, options);
         if (fast !== undefined && fast !== "/") {

package/node_modules/@poe-code/safe-fs/dist/fs/memory/index.d.ts

@@ -134,6 +134,7 @@ export declare class MemoryFileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     tryMkdirFastSync(path: string, recursive: boolean, mode: number | undefined): boolean;
     tryRmFastSync(path: string, recursive: boolean, force: boolean): boolean;

package/node_modules/@poe-code/safe-fs/dist/fs/memory/index.js

@@ -2508,6 +2508,26 @@ export class MemoryFileSystem {
         ownedStats.set(stat, { filesystem: this, path, root: this.root });
         return stat;
     }
+    async *iterateDirectory(path, options = {}) {
+        options.signal?.throwIfAborted();
+        const root = this.root, node = this.resolveNode(path, "iterateDirectory", true);
+        if (node.type !== "directory")
+            this.fail("ENOTDIR", "iterateDirectory", path);
+        this.permission(node, 4, "iterateDirectory", path);
+        const revision = node.revision, ino = node.ino;
+        const check = () => {
+            options.signal?.throwIfAborted();
+            if (this.root !== root || node.ino !== ino || node.revision !== revision || this.resolveNode(path, "iterateDirectory", true) !== node)
+                this.fail("EBUSY", "iterateDirectory", path);
+            this.permission(node, 4, "iterateDirectory", path);
+        };
+        node.atimeMs = Date.now();
+        for (const [name, entry] of node.entries) {
+            check();
+            yield { name, type: entry.type };
+        }
+        check();
+    }
     async readdir(path, options = {}) {
         const limit = directoryEntryLimit(options, path);
         const node = this.resolveNode(path, "readdir", true);

package/node_modules/@poe-code/safe-fs/dist/fs/read-file-stream.js

@@ -6,72 +6,98 @@ const byteKind = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Arra
 /** Sequential payload access without a whole-file fallback. The injected backend
  * must supply streaming reads or retained range reads; no private storage is used.
  * Chunks are borrowed until the consumer advances the iterator. */
-export async function* readFileStream(fs, path, options = {}) {
-    const { signal } = options;
-    signal?.throwIfAborted();
-    const chunkSize = options.chunkSize ?? 65536;
-    let position = options.start ?? 0;
-    const end = options.endExclusive ?? Number.MAX_SAFE_INTEGER;
-    if (!Number.isSafeInteger(chunkSize) || chunkSize <= 0 || !Number.isSafeInteger(position) || position < 0
-        || !Number.isSafeInteger(end) || end < position)
-        throw new FsError("EINVAL", { path, syscall: "readStream" });
-    const capabilities = await fs.capabilitiesFor?.(path, options) ?? fs.capabilities;
-    signal?.throwIfAborted();
-    if (!options.skipStream && fs.readStream && fs.capabilities?.streamingRead !== false && capabilities?.streamingRead !== false) {
-        let emitted = false;
-        let reading = true;
-        try {
-            const source = fs.readStream(path, { ...options, chunkSize });
-            const iterator = source[Symbol.asyncIterator]();
-            let done = false, failed = true;
+export function readFileStream(fs, path, options = {}) {
+    let activeCleanup;
+    const generator = (async function* () {
+        const { signal } = options;
+        signal?.throwIfAborted();
+        const chunkSize = options.chunkSize ?? 65536;
+        let position = options.start ?? 0;
+        const end = options.endExclusive ?? Number.MAX_SAFE_INTEGER;
+        if (!Number.isSafeInteger(chunkSize) || chunkSize <= 0 || !Number.isSafeInteger(position) || position < 0
+            || !Number.isSafeInteger(end) || end < position)
+            throw new FsError("EINVAL", { path, syscall: "readStream" });
+        const capabilities = await fs.capabilitiesFor?.(path, options) ?? fs.capabilities;
+        signal?.throwIfAborted();
+        if (!options.skipStream && fs.readStream && fs.capabilities?.streamingRead !== false && capabilities?.streamingRead !== false) {
+            let emitted = false;
+            let reading = true;
             try {
-                while (true) {
-                    signal?.throwIfAborted();
-                    const item = await iterator.next();
-                    signal?.throwIfAborted();
-                    if (item.done) {
-                        done = true;
-                        break;
+                const source = fs.readStream(path, { ...options, chunkSize });
+                const iterator = source[Symbol.asyncIterator]();
+                let done = false, failed = true;
+                let returned;
+                const closeIterator = () => returned ??= Promise.resolve().then(() => iterator.return?.());
+                activeCleanup = () => done ? Promise.resolve() : closeIterator();
+                try {
+                    while (true) {
+                        signal?.throwIfAborted();
+                        const item = await iterator.next();
+                        signal?.throwIfAborted();
+                        if (item.done) {
+                            done = true;
+                            break;
+                        }
+                        reading = false;
+                        if (byteLength.call(item.value))
+                            emitted = true;
+                        yield item.value;
+                        reading = true;
                     }
-                    reading = false;
-                    if (byteLength.call(item.value))
-                        emitted = true;
-                    yield item.value;
-                    reading = true;
+                    failed = false;
+                }
+                finally {
+                    activeCleanup = undefined;
+                    if (!done)
+                        await finishCleanup(closeIterator, failed);
                 }
-                failed = false;
+                return;
             }
-            finally {
-                if (!done)
-                    await finishCleanup(() => iterator.return?.(), failed);
+            catch (error) {
+                signal?.throwIfAborted();
+                if (!reading || emitted || !(error instanceof FsError) || error.code !== "ENOTSUP")
+                    throw error;
             }
-            return;
         }
-        catch (error) {
-            signal?.throwIfAborted();
-            if (!reading || emitted || !(error instanceof FsError) || error.code !== "ENOTSUP")
-                throw error;
+        const handle = await openRetainedReadFile(fs, path, options);
+        let failed = true;
+        let closed;
+        const closeHandle = () => closed ??= Promise.resolve().then(() => handle.close());
+        activeCleanup = closeHandle;
+        try {
+            while (position < end) {
+                signal?.throwIfAborted();
+                const maximum = Math.min(chunkSize, end - position);
+                const bytes = await handle.read(position, maximum, options);
+                signal?.throwIfAborted();
+                if (byteKind.call(bytes) !== "Uint8Array" || byteLength.call(bytes) > maximum)
+                    throw new FsError("EIO", { path, syscall: "read" });
+                const length = byteLength.call(bytes);
+                if (!length)
+                    break;
+                position += length;
+                yield bytes;
+            }
+            failed = false;
+        }
+        finally {
+            activeCleanup = undefined;
+            await finishCleanup(closeHandle, failed);
+        }
+    })();
+    const originalReturn = generator.return.bind(generator);
+    generator.return = async (value) => {
+        let cleanupError;
+        try {
+            await activeCleanup?.();
         }
-    }
-    const handle = await openRetainedReadFile(fs, path, options);
-    let failed = true;
-    try {
-        while (position < end) {
-            signal?.throwIfAborted();
-            const maximum = Math.min(chunkSize, end - position);
-            const bytes = await handle.read(position, maximum, options);
-            signal?.throwIfAborted();
-            if (byteKind.call(bytes) !== "Uint8Array" || byteLength.call(bytes) > maximum)
-                throw new FsError("EIO", { path, syscall: "read" });
-            const length = byteLength.call(bytes);
-            if (!length)
-                break;
-            position += length;
-            yield bytes;
+        catch (reason) {
+            cleanupError = { reason };
         }
-        failed = false;
-    }
-    finally {
-        await finishCleanup(() => handle.close(), failed);
-    }
+        const result = await originalReturn(value);
+        if (cleanupError)
+            throw cleanupError.reason;
+        return result;
+    };
+    return generator;
 }

package/node_modules/@poe-code/safe-fs/dist/fs/readonly/index.d.ts

@@ -13,6 +13,7 @@ export declare class ReadOnlyFileSystem implements FileSystem {
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
     compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<import("../../contracts/filesystem.js").EntryComparison>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     realpath(path: string, options?: FsOptions): Promise<string>;
     access(path: string, mode?: number, options?: FsOptions): Promise<void>;

package/node_modules/@poe-code/safe-fs/dist/fs/readonly/index.js

@@ -122,6 +122,16 @@ export class ReadOnlyFileSystem {
     compareEntry(path, peer, peerPath, options = {}) {
         return compareEntries(this, path, peer, peerPath, options);
     }
+    async *iterateDirectory(path, options = {}) {
+        options.signal?.throwIfAborted();
+        if (!this.#filesystem.iterateDirectory)
+            throw new FsError("ENOTSUP", { syscall: "iterateDirectory", path });
+        for await (const entry of this.#filesystem.iterateDirectory(path, options)) {
+            options.signal?.throwIfAborted();
+            yield { name: entry.name, type: entry.type };
+        }
+        options.signal?.throwIfAborted();
+    }
     async readdir(path, options) {
         const limit = options?.maxEntries === undefined ? undefined : directoryEntryLimit(options, path);
         const entries = await this.#filesystem.readdir(path, options);

package/node_modules/@poe-code/safe-fs/dist/fs/real/index.d.ts

@@ -81,6 +81,7 @@ export declare class RealFileSystem implements FileSystem {
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    iterateDirectory(path: string, options?: FsOptions): AsyncIterable<DirectoryEntry>;
     readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
     mkdir(path: string, options?: MkdirOptions): Promise<void>;
     rmdir(path: string, options?: FsOptions): Promise<void>;

package/node_modules/@poe-code/safe-fs/dist/fs/real/index.js

@@ -638,6 +638,33 @@ export class RealFileSystem {
             return fileStat(await native.lstat(target, { bigint: true }));
         });
     }
+    async *iterateDirectory(path, options = {}) {
+        let handle, failed = false;
+        try {
+            // Preserve the acquired handle even if cancellation arrives during open:
+            // the following read admission will observe it and finally will close it.
+            handle = await this.operation("iterateDirectory", path, options, async () => {
+                const target = await this.path(path, options);
+                options.signal?.throwIfAborted();
+                return native.opendir(target, { bufferSize: 1 });
+            }, undefined, true);
+            while (true) {
+                const entry = await this.operation("iterateDirectory", path, options, () => handle.read());
+                if (entry === null)
+                    break;
+                yield { name: entry.name, type: fileType(entry) };
+            }
+        }
+        catch (error) {
+            failed = true;
+            options.signal?.throwIfAborted();
+            throw error;
+        }
+        finally {
+            if (handle)
+                await finishCleanup(() => handle.close(), failed);
+        }
+    }
     async readdir(path, options = {}) {
         const limit = directoryEntryLimit(options, path);
         return this.operation("readdir", path, options, async () => {

package/node_modules/@poe-code/safe-fs/dist/fs/scoped.js

@@ -21,7 +21,7 @@ const operations = new Set([
     "prepareDirectoryAncestry", "prepareStagingResolution", "publishStagedFileSet",
     "publishFileConditional", "removeEntryConditional", "removeTreeConditional", "writeFileConditional", "removeFileConditional", "createStagedFile", "publishStagedFile", "removeStagedFile", "prepareDirectory",
     "confineExtraction", "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
-    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir",
+    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir", "iterateDirectory",
     "readlink", "realpath", "rename", "resizeFile", "rm", "rmdir", "unlink", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
 ]);
@@ -188,7 +188,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
             close: (options = {}) => closing ??= Promise.resolve().then(() => descriptor.close(options)),
         };
     };
-    const wrapStream = (source, options) => {
+    const wrapStream = (source, options, chargeNext = false) => {
         const budgetFrames = getScopedTransportBudget();
         return {
             [Symbol.asyncIterator]() {
@@ -203,6 +203,8 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             await closing;
                             return { done: true, value: undefined };
                         }
+                        if (chargeNext)
+                            admit(options);
                         const result = await withScopedTransportBudget(budgetFrames, operation);
                         assertOpen(options);
                         if (closing) {
@@ -430,7 +432,11 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                             });
                         return Reflect.apply(method, original, args);
                     })();
+                if (property === "iterateDirectory")
+                    args[1] = { ...args[1], signal: combineSignal(args[1]?.signal) };
                 const result = Reflect.apply(method, original, args);
+                if (property === "iterateDirectory")
+                    return wrapStream(result, args[1], true);
                 return property === "readStream" ? wrapStream(result, args[1]) : result;
             };
             const dispatch = (...args) => {
@@ -528,7 +534,7 @@ export function scopeFileSystem(filesystem, charge, signal, cleanupCharge = char
                                     ? async (...args) => ownedMutationCapabilities(original, retainedResizeCapabilities(original, await dispatch(...args)))
                                     : property === "openReadFile"
                                         ? async (...args) => wrapHandle(await dispatch(...args))
-                                        : operations.has(property) && property !== "canonicalizeMissingTarget" && property !== "readStream"
+                                        : operations.has(property) && property !== "canonicalizeMissingTarget" && property !== "readStream" && property !== "iterateDirectory"
                                             ? (...args) => {
                                                 try {
                                                     const res = dispatch(...args);

package/node_modules/tiny-stdio-mcp-server/dist/composition.json

@@ -8,7 +8,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.762",
+      "version": "0.0.764",
       "license": "MIT"
     }
   ]

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.762",
+  "version": "0.0.764",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.762",
+  "version": "0.0.764",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -175,7 +175,7 @@
     "@poe-code/terminal-text"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.762",
+    "toolcraft-schema": "0.0.764",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",