toolcraft 0.0.749 → 0.0.750

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

@@ -0,0 +1,279 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+function admitCapabilities(path, options, capabilities) {
+    if (![capabilities.positionedRead, capabilities.positionedWrite, capabilities.truncate].every(value => typeof value === "boolean")
+        || capabilities.noFollow !== undefined && typeof capabilities.noFollow !== "boolean"
+        || capabilities.publication !== undefined && capabilities.publication !== "conditional"
+        || capabilities.position !== undefined && typeof capabilities.position !== "boolean"
+        || capabilities.readObservation !== undefined && typeof capabilities.readObservation !== "boolean"
+        || capabilities.openTruncate !== undefined && typeof capabilities.openTruncate !== "boolean"
+        || capabilities.positionedAppendWrite !== undefined && typeof capabilities.positionedAppendWrite !== "boolean"
+        || capabilities.delegateZeroLengthWrite !== undefined && typeof capabilities.delegateZeroLengthWrite !== "boolean"
+        || !["none", "volatile", "storage"].includes(capabilities.synchronization))
+        throw new FsError("EINVAL", { syscall: "open", path });
+    if (options.noFollow && capabilities.noFollow !== true
+        || options.truncate && !(capabilities.openTruncate ?? capabilities.truncate) || options.synchronization !== undefined && capabilities.synchronization === "none") {
+        throw new FsError("ENOTSUP", { syscall: "open", path });
+    }
+}
+export function forwardFileDescriptor(descriptor, operation, capabilities, snapshot = stat => ({ ...stat })) {
+    const retainedCapabilities = Object.freeze({ ...descriptor.capabilities });
+    const selected = Object.freeze({ ...(capabilities ?? retainedCapabilities) });
+    const getPosition = selected.position === true && retainedCapabilities.position === true ? descriptor.getPosition : undefined;
+    if (selected.position === true && typeof getPosition !== "function")
+        throw new FsError("ENOTSUP", { syscall: "getPosition" });
+    const probeRead = selected.readObservation === true && retainedCapabilities.readObservation === true ? descriptor.probeRead : undefined;
+    if (selected.readObservation === true && typeof probeRead !== "function")
+        throw new FsError("ENOTSUP", { syscall: "probeRead" });
+    return {
+        resource: descriptor, capabilities: selected,
+        ...(getPosition === undefined ? {} : {
+            getPosition: (retained, options) => operation("getPosition", options, () => getPosition.call(retained, options)),
+        }),
+        ...(probeRead === undefined ? {} : {
+            probeRead: (retained, options) => operation("probeRead", options, () => probeRead.call(retained, options)),
+        }),
+        stat: (retained, options) => operation("fstat", options, async () => snapshot(await retained.stat(options))),
+        read: (retained, buffer, position, options) => operation("read", options, () => retained.read(buffer, position, options)),
+        write: (retained, buffer, position, options) => operation("write", options, () => retained.write(buffer, position, options)),
+        truncate: (retained, length, options) => operation("ftruncate", options, () => retained.truncate(length, options)),
+        sync: (retained, dataOnly, options) => operation(dataOnly ? "fdatasync" : "fsync", options, () => retained.sync(dataOnly, options)),
+        close: (retained, options) => operation("close", {}, () => retained.close(options)),
+    };
+}
+function integer(value, syscall, path) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new FsError("EINVAL", { syscall, path });
+}
+const OPEN_FILE_OPTION_KEYS = new Set(["access", "creation", "truncate", "append", "mode", "exactMode", "noFollow", "synchronization", "signal"]);
+const managedCapabilitiesCache = new WeakMap();
+function getManagedCapabilities(capabilities, access, append) {
+    let byKey = managedCapabilitiesCache.get(capabilities);
+    const key = `${access}:${append ? 1 : 0}`;
+    if (byKey) {
+        const cached = byKey.get(key);
+        if (cached)
+            return cached;
+    }
+    else {
+        byKey = new Map();
+        managedCapabilitiesCache.set(capabilities, byKey);
+    }
+    const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && access !== "read";
+    const frozen = Object.freeze({
+        ...(capabilities.noFollow === undefined ? {} : { noFollow: capabilities.noFollow }),
+        ...(capabilities.publication === undefined ? {} : { publication: capabilities.publication }),
+        ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
+        ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
+        ...(capabilities.openTruncate === undefined ? {} : { openTruncate: capabilities.openTruncate }),
+        positionedRead: capabilities.positionedRead && access !== "write",
+        positionedWrite: capabilities.positionedWrite && access !== "read" && (!append || positionedAppendWrite),
+        ...(capabilities.positionedAppendWrite === undefined ? {} : { positionedAppendWrite }),
+        ...(capabilities.delegateZeroLengthWrite === undefined ? {} : { delegateZeroLengthWrite: capabilities.delegateZeroLengthWrite && access !== "read" }),
+        truncate: capabilities.truncate && access !== "read",
+        synchronization: capabilities.synchronization,
+    });
+    byKey.set(key, frozen);
+    return frozen;
+}
+class ManagedFileDescriptor {
+    capabilities;
+    #path;
+    #access;
+    #append;
+    #getPosition;
+    #probeRead;
+    #backend;
+    #pending = Promise.resolve();
+    #closing;
+    constructor(path, options, capabilities, backend) {
+        this.#path = path;
+        this.#access = options.access;
+        this.#append = options.append;
+        const getPosition = capabilities.position === true ? backend.getPosition : undefined;
+        if (capabilities.position === true && typeof getPosition !== "function")
+            throw new FsError("ENOTSUP", { syscall: "getPosition", path });
+        this.#getPosition = getPosition;
+        const probeRead = capabilities.readObservation === true ? backend.probeRead : undefined;
+        if (capabilities.readObservation === true && typeof probeRead !== "function")
+            throw new FsError("ENOTSUP", { syscall: "probeRead", path });
+        this.#probeRead = probeRead;
+        this.#backend = backend;
+        this.capabilities = getManagedCapabilities(capabilities, options.access, options.append);
+    }
+    #run(syscall, options, action) {
+        const signal = options.signal;
+        try {
+            signal?.throwIfAborted();
+            if (this.#closing || !this.#backend)
+                throw new FsError("EBADF", { syscall, path: this.#path });
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const forwarded = signal === undefined ? {} : { signal };
+        const operation = this.#pending.then(async () => {
+            signal?.throwIfAborted();
+            try {
+                const result = await action(this.#backend, forwarded);
+                signal?.throwIfAborted();
+                return result;
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                throw error;
+            }
+        });
+        this.#pending = operation.then(() => { }, () => { });
+        return operation;
+    }
+    #position(buffer, position, syscall) {
+        if (!(buffer instanceof Uint8Array))
+            throw new FsError("EINVAL", { syscall, path: this.#path });
+        if (position !== null) {
+            integer(position, syscall, this.#path);
+            if (syscall === "write" && this.#append && this.capabilities.positionedAppendWrite !== true)
+                throw new FsError("EINVAL", { syscall, path: this.#path });
+            if (!(syscall === "read" ? this.capabilities.positionedRead : this.capabilities.positionedWrite)) {
+                throw new FsError("ESPIPE", { syscall, path: this.#path });
+            }
+        }
+    }
+    stat(options = {}) {
+        return this.#run("fstat", options, (backend, forwarded) => backend.stat(backend.resource, forwarded));
+    }
+    getPosition(options = {}) {
+        return this.#run("getPosition", options, async (backend, forwarded) => {
+            if (!this.capabilities.position || !this.#getPosition)
+                throw new FsError("ENOTSUP", { syscall: "getPosition", path: this.#path });
+            const position = await this.#getPosition.call(backend, backend.resource, forwarded);
+            if (!Number.isSafeInteger(position) || position < 0)
+                throw new FsError("EIO", { syscall: "getPosition", path: this.#path });
+            return position;
+        });
+    }
+    probeRead(options = {}) {
+        return this.#run("probeRead", options, async (backend, forwarded) => {
+            if (!this.capabilities.readObservation || !this.#probeRead)
+                throw new FsError("ENOTSUP", { syscall: "probeRead", path: this.#path });
+            const readiness = await this.#probeRead.call(backend, backend.resource, forwarded);
+            if (readiness !== "ready" && readiness !== "blocked" && readiness !== "unknown")
+                throw new FsError("EIO", { syscall: "probeRead", path: this.#path });
+            return readiness;
+        });
+    }
+    read(buffer, position, options = {}) {
+        return this.#run("read", options, async (backend, forwarded) => {
+            if (this.#access === "write")
+                throw new FsError("EBADF", { syscall: "read", path: this.#path });
+            this.#position(buffer, position, "read");
+            if (buffer.byteLength === 0)
+                return 0;
+            const count = await backend.read(backend.resource, buffer, position, forwarded);
+            if (!Number.isSafeInteger(count) || count < 0 || count > buffer.byteLength)
+                throw new FsError("EIO", { syscall: "read", path: this.#path });
+            return count;
+        });
+    }
+    write(buffer, position, options = {}) {
+        return this.#run("write", options, async (backend, forwarded) => {
+            if (this.#access === "read")
+                throw new FsError("EBADF", { syscall: "write", path: this.#path });
+            this.#position(buffer, position, "write");
+            if (buffer.byteLength === 0 && this.capabilities.delegateZeroLengthWrite !== true)
+                return 0;
+            const count = await backend.write(backend.resource, buffer, position, forwarded);
+            if (!Number.isSafeInteger(count) || count < 0 || count > buffer.byteLength)
+                throw new FsError("EIO", { syscall: "write", path: this.#path });
+            return count;
+        });
+    }
+    truncate(length, options = {}) {
+        return this.#run("ftruncate", options, async (backend, forwarded) => {
+            if (this.#access === "read")
+                throw new FsError("EBADF", { syscall: "ftruncate", path: this.#path });
+            integer(length, "ftruncate", this.#path);
+            if (!this.capabilities.truncate)
+                throw new FsError("ENOTSUP", { syscall: "ftruncate", path: this.#path });
+            await backend.truncate(backend.resource, length, forwarded);
+        });
+    }
+    sync(dataOnly, options = {}) {
+        return this.#run(dataOnly ? "fdatasync" : "fsync", options, async (backend, forwarded) => {
+            if (typeof dataOnly !== "boolean")
+                throw new FsError("EINVAL", { syscall: "fsync", path: this.#path });
+            if (this.capabilities.synchronization === "none")
+                throw new FsError("ENOTSUP", { syscall: dataOnly ? "fdatasync" : "fsync", path: this.#path });
+            await backend.sync(backend.resource, dataOnly, forwarded);
+        });
+    }
+    close(options = {}) {
+        this.#closing ??= this.#pending.then(async () => {
+            try {
+                await this.#backend.close(this.#backend.resource, options);
+            }
+            finally {
+                this.#backend = undefined;
+                this.#getPosition = undefined;
+                this.#probeRead = undefined;
+                this.#pending = Promise.resolve();
+            }
+        });
+        return this.#closing;
+    }
+}
+export async function openFileDescriptor(path, options, capabilities, acquire) {
+    if (!options || typeof options !== "object")
+        throw new FsError("EINVAL", { syscall: "open", path });
+    const signal = options.signal;
+    signal?.throwIfAborted();
+    const { access, creation = "never", truncate = false, append = false, mode = 0o666, synchronization } = options;
+    let invalidKey = false;
+    for (const key in options) {
+        if (Object.prototype.hasOwnProperty.call(options, key) && !OPEN_FILE_OPTION_KEYS.has(key)) {
+            invalidKey = true;
+            break;
+        }
+    }
+    if (invalidKey
+        || (access !== "read" && access !== "write" && access !== "readwrite")
+        || (creation !== "never" && creation !== "ifMissing" && creation !== "exclusive")
+        || options.noFollow !== undefined && typeof options.noFollow !== "boolean"
+        || options.exactMode !== undefined && typeof options.exactMode !== "boolean"
+        || typeof truncate !== "boolean" || typeof append !== "boolean"
+        || access === "read" && (truncate || append)
+        || synchronization !== undefined && !["data", "all"].includes(synchronization)
+        || !Number.isSafeInteger(mode) || mode < 0 || mode > 0o7777) {
+        throw new FsError("EINVAL", { syscall: "open", path });
+    }
+    const admitted = Object.freeze({ access, creation, truncate, append, mode,
+        ...(options.noFollow === undefined ? {} : { noFollow: options.noFollow }),
+        ...(options.exactMode === undefined ? {} : { exactMode: options.exactMode }),
+        ...(signal === undefined ? {} : { signal }), ...(synchronization === undefined ? {} : { synchronization }) });
+    const admittedCapabilities = Object.isFrozen(capabilities) ? capabilities : Object.freeze({ ...capabilities });
+    admitCapabilities(path, admitted, admittedCapabilities);
+    let backend;
+    try {
+        backend = await acquire(admitted);
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        throw error;
+    }
+    try {
+        signal?.throwIfAborted();
+        const rawBackendCapabilities = backend.capabilities;
+        const selected = rawBackendCapabilities ? Object.freeze({ ...rawBackendCapabilities }) : admittedCapabilities;
+        signal?.throwIfAborted();
+        if (rawBackendCapabilities)
+            admitCapabilities(path, admitted, selected);
+        const descriptor = new ManagedFileDescriptor(path, admitted, selected, backend);
+        signal?.throwIfAborted();
+        return descriptor;
+    }
+    catch (error) {
+        await finishCleanup(() => backend.close(backend.resource, {}), true);
+        signal?.throwIfAborted();
+        throw error;
+    }
+}

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

@@ -0,0 +1,59 @@
+import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PublishStagedFileSetOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { ByteSource } from "../../contracts/io.js";
+import { type EntryLocation } from "../mount/comparison.js";
+import { pathNamespace } from "../path-namespace.js";
+export declare class DeviceFileSystem implements FileSystem {
+    #private;
+    readonly capabilities: FileSystemCapabilities;
+    get [pathNamespace](): any;
+    _resolveEntryView: (path: string, options: FsOptions) => Promise<EntryLocation>;
+    _entryAuthority: () => Promise<"unknown">;
+    constructor(filesystem: FileSystem);
+    canonicalizeMissingTarget(path: string, options?: FsOptions): string | undefined;
+    capabilitiesFor(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
+    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("../../runtime-core.js").EntryComparison>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    readStream(path: string, options?: ReadStreamOptions): ByteSource;
+    openReadFile(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
+    open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
+    resizeFile(path: string, operation: FileResizeOperation, options?: FileResizeOptions): Promise<void>;
+    openResizeFile(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
+    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>;
+    readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    unlink(path: string, options?: FsOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    publishFileConditional(path: string, source: ByteSource, options: ConditionalFilePublicationOptions): Promise<FileStat>;
+    writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryOptions & {
+        readonly returnRemainingStat?: false | undefined;
+    }): Promise<void>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryReceiptOptions): Promise<void | FileStat>;
+    removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
+    removeTreeConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
+    createStagedFile(path: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    publishStagedFileSet(receipt: FileStaging, destination: string, supplied: PublishStagedFileSetOptions): Promise<FileStat>;
+    prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
+    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
+    rename(source: string, destination: string, options?: RenameOptions): Promise<void>;
+    copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
+    access(path: string, mode?: number, options?: FsOptions): Promise<void>;
+    readlink(path: string, options?: FsOptions): Promise<string>;
+    symlink(target: string, path: string, options?: FsOptions): Promise<void>;
+    confineExtraction(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    link(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
+    chmod(path: string, mode: number, options?: FsOptions): Promise<void>;
+    utimes(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
+    truncate(path: string, length?: number, options?: FsOptions): Promise<void>;
+}
+export declare function createDeviceFileSystem(filesystem: FileSystem): DeviceFileSystem;