toolcraft 0.0.749 → 0.0.750

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

@@ -0,0 +1,8 @@
+import type { FileStagingEntry, FileStagingResolution, FileStat, PublishStagedFileOptions } from "../contracts/filesystem.js";
+export declare function directoryAncestryPaths(directory: string): string[];
+export declare function snapshotDirectoryAncestry(ancestors: readonly FileStagingEntry[]): readonly FileStagingEntry[];
+export declare function runStagingGuard(guard: () => true): void;
+export declare function snapshotStagingResolution(resolution: FileStagingResolution): FileStagingResolution;
+/** Diagnose failed admission against supplied receipts; this is never a commit
+ * guard. Successful publication still requires the backend's atomic checks. */
+export declare function inspectStagingBindings(read: (path: string) => Promise<FileStat>, destination: string, options: PublishStagedFileOptions): Promise<void>;

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

@@ -0,0 +1,115 @@
+import { FsError, toFsError } from "../contracts/errors.js";
+import { compareIdentity } from "./mount/identity.js";
+import { normalizePath, validatePath } from "../contracts/virtual-path.js";
+export function directoryAncestryPaths(directory) {
+    validatePath(directory);
+    if (!directory.startsWith("/") || normalizePath(directory) !== directory)
+        throw new FsError("EINVAL", { path: directory });
+    let path = "";
+    return ["/", ...directory.split("/").filter(Boolean).map(component => path += `/${component}`)];
+}
+export function snapshotDirectoryAncestry(ancestors) {
+    const entries = ancestors.map(entry => Object.freeze({ path: entry.path, stat: Object.freeze({ ...entry.stat }) }));
+    const paths = directoryAncestryPaths(entries.at(-1)?.path ?? "");
+    if (entries.length !== paths.length || entries.some((entry, index) => entry.path !== paths[index])) {
+        throw new FsError("EINVAL", { message: "directory ancestry requires a complete ordered root-to-directory list" });
+    }
+    for (const entry of entries) {
+        if (entry.stat.type !== "directory")
+            throw new FsError("EINVAL", { path: entry.path });
+        if (compareIdentity(entry.stat, entry.stat) !== "same")
+            throw new FsError("ENOTSUP", { path: entry.path });
+    }
+    return Object.freeze(entries);
+}
+export function runStagingGuard(guard) {
+    const result = guard();
+    if (result !== true) {
+        // A void callback would accept async implementations. Require a literal
+        // success value and observe a misdeclared asynchronous rejection.
+        void Promise.resolve(result).catch(() => { });
+        throw new FsError("ENOTSUP", { message: "staging validation must return true synchronously" });
+    }
+}
+export function snapshotStagingResolution(resolution) {
+    const path = resolution.path;
+    validatePath(path);
+    const ancestors = snapshotDirectoryAncestry(resolution.ancestors);
+    const validate = resolution.validate;
+    if (normalizePath(path) !== path || !path.startsWith("/") || path === "/"
+        || ancestors.at(-1).path !== (path.slice(0, path.lastIndexOf("/")) || "/")
+        || typeof validate !== "function")
+        throw new FsError("EINVAL", { path });
+    const parent = Object.freeze({ ...resolution.parent });
+    if (parent.type !== "directory")
+        throw new FsError("EINVAL", { path });
+    if (compareIdentity(parent, ancestors.at(-1).stat) !== "same")
+        throw new FsError("ENOTSUP", { path });
+    const supplied = resolution.destination;
+    const destination = supplied === null ? null : Object.freeze({ ...supplied });
+    const requireSnapshot = (stat) => {
+        if (compareIdentity(stat, stat) !== "same" || stat.type !== "directory" && (!Number.isSafeInteger(stat.revision) || stat.revision < 0)) {
+            throw new FsError("ENOTSUP", { path });
+        }
+    };
+    if (destination !== null) {
+        if (destination.type !== "file")
+            throw new FsError("EINVAL", { path });
+        requireSnapshot(destination);
+    }
+    if (!resolution.traversed.length)
+        throw new FsError("EINVAL", { path });
+    if (resolution.traversed.length > 4096)
+        throw new FsError("EFBIG", { path });
+    let recordedUnits = 0;
+    const traversed = resolution.traversed.map(entry => {
+        const entryPath = entry.path, stat = Object.freeze({ ...entry.stat }), linkTarget = entry.linkTarget;
+        validatePath(entryPath);
+        if (!entryPath.startsWith("/") || normalizePath(entryPath) !== entryPath
+            || !["directory", "file", "symlink"].includes(stat.type)
+            || stat.type === "symlink" && typeof linkTarget !== "string"
+            || stat.type !== "symlink" && linkTarget !== undefined)
+            throw new FsError("EINVAL", { path: entryPath });
+        requireSnapshot(stat);
+        recordedUnits += entryPath.length + (linkTarget?.length ?? 0);
+        if (recordedUnits > 1_048_576)
+            throw new FsError("EFBIG", { path });
+        return Object.freeze({ path: entryPath, stat, ...(linkTarget === undefined ? {} : { linkTarget }) });
+    });
+    return Object.freeze({ path, parent, destination, ancestors, traversed: Object.freeze(traversed), validate });
+}
+/** Diagnose failed admission against supplied receipts; this is never a commit
+ * guard. Successful publication still requires the backend's atomic checks. */
+export async function inspectStagingBindings(read, destination, options) {
+    options.signal?.throwIfAborted();
+    const ancestors = snapshotDirectoryAncestry(options.ancestors);
+    const parent = destination.slice(0, destination.lastIndexOf("/")) || "/";
+    if (normalizePath(destination) !== destination || ancestors.at(-1)?.path !== parent)
+        throw new FsError("EINVAL", { path: destination });
+    const expected = options.destination === null ? null : { ...options.destination };
+    if (expected !== null && (compareIdentity(expected, expected) !== "same"
+        || expected.type === "file" && (!Number.isSafeInteger(expected.revision) || expected.revision < 0)))
+        throw new FsError("ENOTSUP", { path: destination });
+    const entries = [...ancestors.map(entry => ({ ...entry, directory: true })), { path: destination, stat: expected, directory: false }];
+    for (const entry of entries) {
+        let current;
+        try {
+            current = await read(entry.path);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            const code = toFsError(error).code;
+            if (code === "ENOENT" && entry.stat === null)
+                continue;
+            if (["ENOENT", "ENOTDIR", "ELOOP"].includes(code))
+                throw new FsError("EAGAIN", { path: entry.path, cause: error });
+            throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (entry.stat === null || current.type !== entry.stat.type || compareIdentity(current, entry.stat) !== "same")
+            throw new FsError("EAGAIN", { path: entry.path });
+        if (!entry.directory && ["revision", "size", "mode", "nlink", "mtimeMs", "ctimeMs"].some(field => current[field] !== entry.stat[field])) {
+            throw new FsError("EAGAIN", { path: entry.path });
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+import type { CreateStagedFileOptions, FileStagingCleanup, FsOptions } from "../contracts/filesystem.js";
+/** Capture creation controls before awaits or allocation can split their meaning. */
+export declare function snapshotStagingCreation(options: CreateStagedFileOptions, path: string): CreateStagedFileOptions;
+/** Own admission and release outside wrappers that can fail before dispatch. */
+export declare function createStagingCleanup(path: string, remove: (options: FsOptions) => void | Promise<void>, release: () => void | Promise<void>): FileStagingCleanup;

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

@@ -0,0 +1,63 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+/** Capture creation controls before awaits or allocation can split their meaning. */
+export function snapshotStagingCreation(options, path) {
+    const captured = { ...options };
+    for (const key of ["signal", "retainCleanup", "parent", "mode", "atimeMs", "mtimeMs"]) {
+        if (!Object.hasOwn(captured, key))
+            Object.defineProperty(captured, key, { value: options[key], enumerable: true });
+    }
+    const { signal, retainCleanup, parent, mode, atimeMs, mtimeMs, ...extra } = captured;
+    signal?.throwIfAborted();
+    if (retainCleanup !== undefined && typeof retainCleanup !== "boolean")
+        throw new FsError("EINVAL", { syscall: "createStagedFile", path });
+    return {
+        ...extra, parent,
+        ...(signal === undefined ? {} : { signal }),
+        ...(retainCleanup === undefined ? {} : { retainCleanup }),
+        ...(mode === undefined ? {} : { mode }),
+        ...(atimeMs === undefined ? {} : { atimeMs }),
+        ...(mtimeMs === undefined ? {} : { mtimeMs }),
+    };
+}
+/** Own admission and release outside wrappers that can fail before dispatch. */
+export function createStagingCleanup(path, remove, release) {
+    let accepting = true;
+    let removal;
+    let closing;
+    let released;
+    const dispose = () => released ??= Promise.resolve().then(release);
+    return Object.freeze({
+        remove(options = {}) {
+            if (removal)
+                return removal;
+            if (!accepting) {
+                const rejected = Promise.reject(new FsError("EBADF", { syscall: "removeStagedFile", path }));
+                void rejected.catch(() => { });
+                return rejected;
+            }
+            accepting = false;
+            removal = Promise.resolve().then(async () => {
+                let failed = true;
+                try {
+                    await remove(options);
+                    failed = false;
+                }
+                finally {
+                    await finishCleanup(dispose, failed);
+                }
+            });
+            void removal.catch(() => { });
+            return removal;
+        },
+        close() {
+            accepting = false;
+            closing ??= (async () => {
+                await removal?.catch(() => { });
+                await dispose();
+            })();
+            void closing.catch(() => { });
+            return closing;
+        },
+    });
+}

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

@@ -0,0 +1,2 @@
+export { WebDavFileSystem } from "./webdav.js";
+export type { WebDavFileSystemOptions, WebDavFetch, WebDavAtomicEmptyDirectoryBinding, WebDavAtomicEmptyDirectoryRequest, WebDavAtomicEmptyDirectoryResult, } from "./webdav.js";

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

@@ -0,0 +1 @@
+export { WebDavFileSystem } from "./webdav.js";

package/node_modules/@poe-code/safe-fs/dist/fs/webdav/resource-id.d.ts

@@ -0,0 +1,18 @@
+import type { FileStat, FileSystem, FsOptions } from "../../contracts/filesystem.js";
+import type { EntryAuthority, EntryView } from "../mount/comparison.js";
+export interface OwnedWebDavEntry {
+    readonly storage: object;
+    readonly resource: object;
+}
+export interface OwnedWebDavResource extends OwnedWebDavEntry {
+    readonly identifier: string;
+}
+export declare function registerOwnedResourceResponse(response: Response, entries: ReadonlyMap<string, OwnedWebDavResource>): void;
+export declare function recordOwnedResourceStat(response: Response, filesystem: FileSystem, path: string, stat: FileStat): void;
+export declare function getOwnedWebDavEntry(view: EntryView): OwnedWebDavEntry | undefined;
+export declare function ownedResponseIdentifier(response: Response, path: string): string | undefined;
+type ResourceQuery = (path: string, options: FsOptions) => Promise<string | undefined>;
+export declare function registerResourceQuery(filesystem: FileSystem, query: ResourceQuery, baseComparison: NonNullable<FileSystem["compareEntry"]>, callback?: NonNullable<FileSystem["compareEntry"]>): void;
+export declare function resourceIdentifier(value: string): string;
+export declare const compareWebDavResources: EntryAuthority;
+export {};

package/node_modules/@poe-code/safe-fs/dist/fs/webdav/resource-id.js

@@ -0,0 +1,109 @@
+import { FsError } from "../../contracts/errors.js";
+import { assertCallbackAuthorityAllowed } from "../mount/comparison.js";
+const responses = new WeakMap();
+const observations = new WeakMap();
+export function registerOwnedResourceResponse(response, entries) {
+    if (responses.has(response))
+        throw new TypeError("resource response already registered");
+    responses.set(response, new Map(entries));
+}
+export function recordOwnedResourceStat(response, filesystem, path, stat) {
+    const entry = responses.get(response)?.get(path);
+    if (entry)
+        observations.set(stat, { filesystem, path, entry });
+}
+export function getOwnedWebDavEntry(view) {
+    const observation = observations.get(view.stat);
+    return observation?.filesystem === view.filesystem && observation.path === view.path
+        ? observation.entry : undefined;
+}
+export function ownedResponseIdentifier(response, path) {
+    return responses.get(response)?.get(path)?.identifier;
+}
+const queries = new WeakMap();
+const comparisons = new WeakMap();
+const callbacks = new WeakMap();
+export function registerResourceQuery(filesystem, query, baseComparison, callback) {
+    comparisons.set(filesystem, baseComparison);
+    if (callback)
+        callbacks.set(filesystem, callback);
+    queries.set(filesystem, async (path, options) => {
+        options.signal?.throwIfAborted();
+        const identifier = await query(path, options);
+        options.signal?.throwIfAborted();
+        return identifier;
+    });
+}
+export function resourceIdentifier(value) {
+    if (!/^[A-Za-z][A-Za-z0-9+.-]*:[^\s<>"{}|\\^`]+$/.test(value) || /%(?![0-9A-Fa-f]{2})/.test(value)
+        || /[^\x21-\x7e]/.test(value))
+        throw new Error("invalid DAV:resource-id URI");
+    new URL(value);
+    if (/^urn:uuid:/i.test(value)) {
+        if (!/^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) {
+            throw new Error("invalid DAV:resource-id UUID");
+        }
+        return value.toLowerCase();
+    }
+    return value;
+}
+export const compareWebDavResources = async (own, peer, options) => {
+    options.signal?.throwIfAborted();
+    let explicit = false;
+    let answer = "unknown";
+    const visited = new Set();
+    for (const [left, right] of [[own, peer], [peer, own]]) {
+        const baseComparison = comparisons.get(left.filesystem);
+        if (!baseComparison)
+            continue;
+        const method = left.filesystem.compareEntry;
+        const comparison = method === baseComparison ? callbacks.get(left.filesystem) : method;
+        if (method === baseComparison && !comparison)
+            continue;
+        explicit = true;
+        if (!comparison || visited.has(left.filesystem))
+            continue;
+        visited.add(left.filesystem);
+        options.signal?.throwIfAborted();
+        assertCallbackAuthorityAllowed();
+        const result = await comparison.call(left.filesystem, left.path, right.filesystem, right.path, options);
+        options.signal?.throwIfAborted();
+        if (result !== "same" && result !== "distinct" && result !== "unknown") {
+            throw new FsError("EIO", { path: own.path, dest: peer.path, message: "invalid explicit WebDAV comparison" });
+        }
+        if (result === "unknown")
+            continue;
+        if (answer !== "unknown" && answer !== result) {
+            throw new FsError("EIO", { path: own.path, dest: peer.path, message: "conflicting explicit WebDAV comparisons" });
+        }
+        answer = result;
+    }
+    const builtin = await compareProtocolEntries(own, peer, options);
+    if (builtin === "same" && answer === "distinct") {
+        throw new FsError("EIO", { path: own.path, dest: peer.path, message: "explicit WebDAV comparison contradicts built-in identity" });
+    }
+    if (builtin === "same")
+        return "same";
+    return explicit ? answer : builtin;
+};
+async function compareProtocolEntries(own, peer, options) {
+    const left = getOwnedWebDavEntry(own);
+    const right = getOwnedWebDavEntry(peer);
+    const ownQuery = queries.get(own.filesystem);
+    const peerQuery = queries.get(peer.filesystem);
+    if (!ownQuery || !peerQuery)
+        return "unknown";
+    options.signal?.throwIfAborted();
+    const ownId = await ownQuery(own.path, options);
+    options.signal?.throwIfAborted();
+    const peerId = await peerQuery(peer.path, options);
+    options.signal?.throwIfAborted();
+    if (ownId === undefined || peerId === undefined)
+        return "unknown";
+    if (left && right) {
+        const same = left.storage === right.storage && left.resource === right.resource;
+        if (same !== (ownId === peerId))
+            throw new FsError("EIO", { path: own.path, dest: peer.path, message: "conflicting owned and protocol WebDAV identities" });
+    }
+    return ownId === peerId ? "same" : "distinct";
+}

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

@@ -0,0 +1,141 @@
+import type { PlatformComparisonCallback } from "#safe-fs-platform";
+import type { ByteSource } from "../../contracts/io.js";
+import type { AppendFileOptions, CopyFileOptions, DirectoryEntry, EntryComparison, FileStat, FileSystem, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
+import type { XmlLimits } from "./xml.js";
+export type WebDavFetch = (url: string, init: RequestInit) => Promise<Response>;
+export interface WebDavAtomicEmptyDirectoryRequest {
+    readonly operation: "atomic-empty-rmdir/v1";
+    readonly namespaceUrl: string;
+    readonly path: string;
+    readonly signal?: AbortSignal;
+}
+export interface WebDavAtomicEmptyDirectoryResult {
+    readonly operation: "atomic-empty-rmdir/v1";
+    readonly namespaceUrl: string;
+    readonly path: string;
+    readonly outcome: "removed";
+}
+export interface WebDavAtomicEmptyDirectoryBinding {
+    readonly namespaceUrl: string;
+    readonly removeEmptyDirectory: (request: WebDavAtomicEmptyDirectoryRequest) => Promise<WebDavAtomicEmptyDirectoryResult>;
+}
+export interface WebDavFileSystemOptions {
+    readonly baseUrl: string;
+    readonly fetch: WebDavFetch;
+    readonly requestStreamSupport?: "native" | boolean;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Response ceiling; unlimited unless configured. */
+    readonly maxResponseBytes?: number;
+    /** Metadata response ceiling before decoding/parsing; unlimited unless configured. */
+    readonly maxXmlBytes?: number;
+    /** Timestamp property UTF-8 byte ceiling; unlimited unless configured. */
+    readonly maxTimestampPropertyBytes?: number;
+    readonly maxEntries?: number;
+    /** XML structure ceilings; unlimited unless configured. */
+    readonly xmlLimits?: Pick<XmlLimits, "maxNodes" | "maxContentNodes" | "maxDepth" | "maxAttributes">;
+    /** Per-request and aggregate stat/write-preflight walk timeout; unlimited unless configured. */
+    readonly timeoutMs?: number;
+    readonly overwritePolicy?: "lock" | "etag";
+    readonly atomicEmptyDirectory?: WebDavAtomicEmptyDirectoryBinding;
+    readonly compareEntry?: PlatformComparisonCallback<(this: FileSystem, ...args: Parameters<NonNullable<FileSystem["compareEntry"]>>) => ReturnType<NonNullable<FileSystem["compareEntry"]>>>;
+}
+export declare class WebDavFileSystem implements FileSystem {
+    open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
+    readonly capabilities: Readonly<{
+        open: false;
+        read: true;
+        stat: true;
+        readdir: true;
+        realpath: true;
+        access: true;
+        write: true;
+        append: true;
+        exclusiveCreate: true;
+        explicitDirectories: true;
+        implicitDirectories: false;
+        mkdir: true;
+        recursiveMkdir: true;
+        remove: true;
+        recursiveRemove: true;
+        rename: true;
+        atomicRenameNoReplace: false;
+        copy: true;
+        exclusiveCopy: true;
+        readlink: false;
+        truncate: false;
+        randomAccessWrite: false;
+        removeDirectory: boolean;
+        streamingAppend: boolean;
+        symlinks: false;
+        hardlinks: false;
+        permissions: false;
+        timestamps: true;
+        atomicRename: false;
+        streamingRead: true;
+        streamingWrite: true;
+    }>;
+    private readonly base;
+    private readonly baseSegments;
+    private readonly transport;
+    private readonly requestStreamSupport;
+    private readonly headers;
+    private readonly maxResponseBytes;
+    private readonly maxXmlBytes;
+    private readonly maxTimestampPropertyBytes;
+    private readonly maxEntries;
+    private readonly xmlLimits;
+    private readonly timeoutMs;
+    private readonly walkDeadlines;
+    private readonly overwritePolicy;
+    private readonly configuredComparison;
+    private readonly atomicEmptyDirectory;
+    private readonly etags;
+    constructor(options: WebDavFileSystemOptions);
+    compareEntry(path: string, peer: FileSystem, peerPath: string, options?: FsOptions): Promise<EntryComparison>;
+    private resourceId;
+    private url;
+    private hrefPath;
+    private httpError;
+    private request;
+    private requestStream;
+    private bytes;
+    private responseLength;
+    private bodyChunks;
+    private xml;
+    private multistatus;
+    private lockFailure;
+    private entryStat;
+    private entries;
+    private mutation;
+    private unsupported;
+    private maybeStat;
+    private withWalkDeadline;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    private statWithAncestors;
+    lstat(path: string, options?: FsOptions): Promise<FileStat>;
+    readdir(path: string, options?: ReadDirectoryOptions): Promise<DirectoryEntry[]>;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    readStream(path: string, options?: ReadStreamOptions): AsyncGenerator<Uint8Array>;
+    private prepareWrite;
+    writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    writeStream(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rmdir(path: string, options?: FsOptions): Promise<void>;
+    private atomicRmdir;
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    private guardTransferIdentity;
+    private transfer;
+    private withDestinationLock;
+    rename(source: string, destination: string, options?: RenameOptions): Promise<void>;
+    copyFile(source: string, destination: string, options?: CopyFileOptions): Promise<void>;
+    realpath(path: string, options?: FsOptions): Promise<string>;
+    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>;
+    link(_source: string, path: 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>;
+}