toolcraft 0.0.760 → 0.0.761

package/composition.json

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

package/dist/composition.json

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

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

@@ -303,6 +303,8 @@ For Workers, `externalSpool` must store payloads outside isolate RAM and satisfy
 
 The reusable metadata-only fixture in [`tests/fixtures/bounded-filesystem.ts`](tests/fixtures/bounded-filesystem.ts) generates file ranges and consumes slow writes without storing payload bytes. [`tests/overlay-bounded.test.ts`](tests/overlay-bounded.test.ts) checks fixed transfer sizes, source backpressure, cancellation/error cleanup, byte results, and Memory publication allocation/identity. These deterministic conformance checks do not qualify a deployed Worker backend; follow the [Worker QA plan](../../docs/plans/safe-fs-bounded-overlay-qa.md) for runtime measurements.
 
+`readFileStream(fs, path, options)` reads through the caller's native stream or retained range handle without calling `readFile`. It accepts the stream range/window options above, defaults to a 64 KiB read window, and closes owned readers on completion, failure or cancellation. `skipStream: true` selects retained ranges after an already-attempted stream reports `ENOTSUP`. Chunks are borrowed until the iterator advances. Native adapters must honor the requested window and backpressure. Whole-file-only backends receive `ENOTSUP`; use a streaming or retained-range backend for sequential Worker operations. This helper bounds its I/O window, not the consuming command's parser or output capture.
+
 `collectBytes(source, { maxBytes, maxMemoryBytes, signal })` snapshots streamed chunks into one growing buffer. `maxBytes` and `maxMemoryBytes` accept explicit `Infinity`. `maxMemoryBytes` limits owned capacity, the current input's full backing buffer, and overlapping allocations during growth; exhaustion throws `EFBIG`. Collection limits are disabled by default on Node, browser, and Worker targets. Each call owns its budget; concurrent collections do not consume one another’s allowance. The returned view may retain geometric spare capacity. Configured budgets cover collection, not caller-retained results, transport buffering, archive decoding, strings, or the rest of the runtime; use streaming APIs and limit concurrent workloads for larger inputs.
 
 <details>

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

@@ -17,3 +17,4 @@ export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";

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

@@ -15,3 +15,4 @@ export * from "./fs/s3/index.js";
 export * from "./fs/s3/http/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";

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

@@ -219,7 +219,7 @@ export class MountFileSystem {
                     && await this.supportsDirectoryValidation(location.path.slice(0, location.path.lastIndexOf("/")) || "/", options, true)
                 : this.capabilities.conditionalChmod;
             const { synchronousDirectoryValidation: ignoredValidation, synchronousStagingResolution: ignoredResolution, ...ordinary } = resize;
-            const withOpen = { ...ordinary, retainedStagingWrite: false, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
+            const withOpen = { ...ordinary, ...(conditionalChmod === undefined ? {} : { conditionalChmod }), ...(resolution === undefined ? {} : { synchronousStagingResolution: resolution }), ...(validation === undefined ? {} : { synchronousDirectoryValidation: validation }), atomicStagingAncestry: ancestry, ...(typeof location.mount.backend.open === "function" ? {} : { open: false }) };
             const capabilities = location.synthetic ? { ...withOpen, open: false, retainedRead: false }
                 : retainedResizeCapabilities(location.mount.backend, retainedReadCapabilities(location.mount.backend, withOpen));
             if (location.synthetic)
@@ -973,7 +973,11 @@ export class MountFileSystem {
                     return Object.freeze(staging);
                 const backendCleanup = receipt.cleanup;
                 const cleanup = createStagingCleanup(staging.directory.path, controls => this.operation("removeStagedFile", staging.directory.path, controls, () => backendCleanup.remove(controls), undefined, true), () => backendCleanup.close());
-                return Object.freeze({ ...staging, cleanup });
+                const writer = receipt.writer;
+                return Object.freeze({ ...staging, cleanup, ...(writer ? { writer: Object.freeze({
+                            write: (bytes, controls = {}) => this.operation("stagedWrite", staging.file.path, controls, () => writer.write(bytes, controls), undefined, true),
+                            finish: (controls = {}) => this.operation("stagedFinish", staging.file.path, controls, async () => snapshotStat(await writer.finish(controls)), undefined, true),
+                        }) } : {}) });
             }
             catch (error) {
                 await finishCleanup(() => receipt.cleanup?.close(), true);

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

@@ -0,0 +1,7 @@
+import type { FileSystem, ReadStreamOptions } from "../contracts/filesystem.js";
+/** 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 declare function readFileStream(fs: FileSystem, path: string, options?: ReadStreamOptions & {
+    readonly skipStream?: boolean;
+}): AsyncGenerator<Uint8Array>;

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

@@ -0,0 +1,77 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+import { openRetainedReadFile } from "./capabilities.js";
+const byteLength = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get;
+const byteKind = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), Symbol.toStringTag).get;
+/** 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;
+            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;
+                }
+                failed = false;
+            }
+            finally {
+                if (!done)
+                    await finishCleanup(() => iterator.return?.(), failed);
+            }
+            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;
+    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 {
+        await finishCleanup(() => handle.close(), failed);
+    }
+}

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

@@ -23,3 +23,4 @@ export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./
 export type { FileSystemConfig, FileSystemAdapterDescriptor, FileSystemAdapterRegistry } from "./config.js";
 export { createNodeFileSystemAdapterRegistry } from "./config.node.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";

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

@@ -19,3 +19,4 @@ export * from "./node/index.js";
 export { createFileSystem, readConfigRecord, validateFileSystemConfig } from "./config.js";
 export { createNodeFileSystemAdapterRegistry } from "./config.node.js";
 export { createPortableFileSystemAdapterRegistry } from "./config.portable.js";
+export { readFileStream } from "./fs/read-file-stream.js";

package/node_modules/@poe-code/safe-fs/dist/runtime-core.d.ts

@@ -25,3 +25,4 @@ export declare function tryWriteMemoryFileSync(fs: FileSystem, path: string, dat
 export declare function tryMkdirMemorySync(fs: FileSystem, path: string, recursive: boolean, mode: number, signal?: AbortSignal, dirPrefixHint?: string): boolean;
 export declare function tryRmRfMemorySync(fs: FileSystem, path: string, signal?: AbortSignal): boolean;
 export declare function tryWriteMemoryFileInDirSync(fs: FileSystem, dirPrefix: string, name: string, data: Uint8Array, append: boolean, mode: number, signal?: AbortSignal): boolean;
+export { readFileStream } from "./fs/read-file-stream.js";

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

@@ -55,3 +55,4 @@ export function tryRmRfMemorySync(fs, path, signal) {
 export function tryWriteMemoryFileInDirSync(fs, dirPrefix, name, data, append, mode, signal) {
     return Boolean((fs && _getMemHooks()?.byProto?.get(Object.getPrototypeOf(fs))?.tryWriteMemoryFileInDirSync)?.(fs, dirPrefix, name, data, append, mode, signal));
 }
+export { readFileStream } from "./fs/read-file-stream.js";

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

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

package/node_modules/toolcraft-schema/package.json

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

package/package.json

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