toolcraft 0.0.749 → 0.0.750

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

@@ -0,0 +1,379 @@
+import type { ExactFileReadHandle, ExactFileResizeHandle, ObjectFileSystem } from "./object.js";
+import type { ByteSource } from "./io.js";
+import type { FileDescriptor, OpenFileOptions } from "./descriptor.js";
+export type { FileDescriptor, FileDescriptorCapabilities, OpenFileOptions } from "./descriptor.js";
+export type FileType = "file" | "directory" | "symlink" | "character";
+export type EntryComparison = "same" | "distinct" | "unknown";
+export interface FileStat {
+    readonly type: FileType;
+    /** Backend-reported type of the containing filesystem; absence means unknown. */
+    readonly filesystemType?: string;
+    readonly size: number;
+    readonly allocatedBytes?: number;
+    readonly ioBlockSize?: number;
+    readonly preferredIoBlockSize?: number;
+    readonly mode: number;
+    readonly mtimeMs: number;
+    readonly atimeMs: number;
+    readonly ctimeMs: number;
+    readonly birthtimeMs?: number;
+    readonly revision?: number;
+    readonly identityScope?: object | symbol;
+    /** Authoritative backing identity within identityScope; aliases share this key. */
+    readonly opaqueIdentity?: string;
+    /** ABA-safe namespace generation, changed by replacement and delete/recreate. */
+    readonly opaqueVersion?: string;
+    readonly ino?: number;
+    readonly dev?: number;
+    readonly rdevMajor?: number;
+    readonly rdevMinor?: number;
+    readonly nlink?: number;
+    readonly uid?: number;
+    readonly gid?: number;
+}
+export interface DirectoryEntry {
+    readonly name: string;
+    readonly type: FileType;
+}
+export interface FileSystemCapabilities {
+    readonly open?: boolean;
+    readonly versionedDescriptors?: boolean;
+    /** Prefer pathname streaming for shell > / >> when supported, retaining open for explicit handles.
+     * The host owns stream atomicity; this does not provide retained descriptor identity for redirected output. */
+    readonly preferStreamingRedirection?: boolean;
+    readonly readOnly?: boolean;
+    readonly read?: boolean;
+    readonly stat?: boolean;
+    readonly readdir?: boolean;
+    readonly realpath?: boolean;
+    readonly access?: boolean;
+    readonly write?: boolean;
+    readonly append?: boolean;
+    readonly exclusiveCreate?: boolean;
+    readonly explicitDirectories?: boolean;
+    readonly implicitDirectories?: boolean;
+    readonly mkdir?: boolean;
+    readonly recursiveMkdir?: boolean;
+    readonly remove?: boolean;
+    readonly removeDirectory?: boolean;
+    readonly recursiveRemove?: boolean;
+    readonly rename?: boolean;
+    readonly copy?: boolean;
+    readonly exclusiveCopy?: boolean;
+    readonly readlink?: boolean;
+    readonly truncate?: boolean;
+    readonly streamingAppend?: boolean;
+    readonly randomAccessWrite?: boolean;
+    readonly independentWriteStreams?: boolean;
+    readonly symlinks?: boolean;
+    readonly hardlinks?: boolean;
+    readonly permissions?: boolean;
+    /** Enforces chmod target/ancestry receipts and a synchronous guard at the metadata commit.
+     * Host adapters retain their documented external-filesystem isolation requirements. */
+    readonly conditionalChmod?: boolean;
+    readonly timestamps?: boolean;
+    readonly atomicRename?: boolean;
+    /** Owned staging serialized within a trusted host; requires external tree isolation. */
+    readonly trustedOwnedStaging?: boolean;
+    readonly atomicFileStaging?: boolean;
+    /** Creates a cleanup handle bound to owned staging entries, independent of ancestor paths. */
+    readonly retainedStagingCleanup?: boolean;
+    readonly retainedStagingWrite?: boolean;
+    /** Atomically verifies every supplied root-to-parent directory identity at publication. */
+    readonly atomicStagingAncestry?: boolean;
+    /** Prepares directory guards that validate without yielding or mutating state. */
+    readonly synchronousDirectoryValidation?: boolean;
+    /** Captures a followed destination path with a synchronous commit validator. */
+    readonly synchronousStagingResolution?: boolean;
+    /** Invokes commitGuard in the same synchronous section as staged replacement. */
+    readonly guardedStagingPublication?: boolean;
+    readonly atomicFilePublication?: boolean;
+    readonly atomicFileMutation?: boolean;
+    readonly atomicEntryRemoval?: boolean;
+    /** Returns an atomic post-unlink inode snapshot when explicitly requested. */
+    readonly atomicEntryRemovalReceipt?: boolean;
+    readonly atomicTreeRemoval?: boolean;
+    readonly atomicDirectoryMetadata?: boolean;
+    readonly atomicRenameNoReplace?: boolean;
+    readonly snapshotRmdir?: boolean;
+    readonly streamingRead?: boolean;
+    readonly retainedRead?: boolean;
+    readonly retainedResize?: boolean;
+    readonly atomicResize?: boolean;
+    readonly streamingWrite?: boolean;
+    readonly descriptorWriteStream?: boolean;
+    readonly [capability: string]: boolean | undefined;
+}
+export interface FsOptions {
+    /** Optional virtual device path traversal quotas; disabled by default. */
+    readonly pathLimits?: import("./virtual-path.js").PathLimits;
+    readonly signal?: AbortSignal;
+}
+export interface ChmodOptions extends FsOptions {
+    /** Conditional fields require conditionalChmod and a complete parent/target/ancestry receipt. */
+    readonly parent?: FileStat;
+    readonly expected?: FileStat;
+    readonly ancestors?: readonly FileStagingEntry[];
+    /** Trusted, mutation-free validation; must return literal true synchronously. */
+    readonly commitGuard?: () => true;
+}
+export interface OpenReadFileOptions extends FsOptions {
+    readonly allowDirectory?: boolean;
+}
+export interface CapabilityQueryOptions extends OpenReadFileOptions {
+    /** Include complete wrapper ancestry when checking conditional chmod support. */
+    readonly conditionalChmod?: boolean;
+    /** Inspect complete ancestry for staged publication, including other mounts.
+     * Omission retains the ordinary per-target query and its acquisition intent. */
+    readonly stagingAncestry?: boolean;
+    readonly stagingResolution?: boolean;
+    readonly create?: boolean;
+    readonly creation?: OpenFileOptions["creation"];
+}
+export interface FileReadHandle {
+    /** Exact operations on the same retained object; close owns both facets. */
+    readonly exact?: ExactFileReadHandle;
+    stat(options?: FsOptions): Promise<FileStat>;
+    read(position: number, maxBytes: number, options?: FsOptions): Promise<Uint8Array>;
+    seekEnd?: ((options?: FsOptions) => Promise<bigint>) | undefined;
+    close(): Promise<void>;
+}
+export interface OpenResizeFileOptions extends FsOptions {
+    readonly create?: boolean;
+    readonly mode?: number;
+}
+/** A single atomic read/compute/resize operation, never a caller-side stat/write pair.
+ * size and referenceSize use signed 64-bit byte integers (referenceSize is nonnegative).
+ * ioBlocks scales size by the target's preferred I/O block size before applying the
+ * modifier. Relative/min/max/round operations use referenceSize or the current size.
+ * Signed overflow rejects; negative final sizes clamp to zero. Providers enforce
+ * their size/quota/permission limits before allocation or publication. */
+export interface FileResizeOperation {
+    readonly size: bigint;
+    readonly modifier: "absolute" | "relative" | "minimum" | "maximum" | "down" | "up";
+    readonly referenceSize?: bigint;
+    readonly ioBlocks?: boolean;
+}
+export interface FileResizeOptions extends FsOptions {
+    readonly create?: boolean;
+    readonly mode?: number;
+}
+export interface FileResizeHandle {
+    /** Exact operations on the same retained object; close owns both facets. */
+    readonly exact?: ExactFileResizeHandle;
+    stat(options?: FsOptions): Promise<FileStat>;
+    truncate(length: number, options?: FsOptions): Promise<void>;
+    seekEnd?: ((options?: FsOptions) => Promise<bigint>) | undefined;
+    close(): Promise<void>;
+}
+export interface RenameOptions extends FsOptions {
+    readonly noReplace?: boolean;
+}
+export interface ReadFileOptions extends FsOptions {
+    /** Nonnegative safe-integer byte cap; Infinity adds no per-read cap. */
+    readonly maxBytes?: number;
+}
+export interface ReadDirectoryOptions extends FsOptions {
+    /**
+     * Optional per-listing entry admission limit, a nonnegative safe integer or Infinity.
+     * Zero permits an empty listing; overflow rejects with EFBIG, never truncates.
+     * Omission or Infinity preserves the adapter's existing limits and ordering. Composed
+     * adapters may conservatively count distinct candidates before visibility
+     * filtering. This is not a global traversal, host-allocation or work quota.
+     */
+    readonly maxEntries?: number;
+}
+export interface WriteFileOptions extends FsOptions {
+    readonly flag?: "w" | "wx" | "a" | "ax";
+    readonly mode?: number;
+}
+export interface AppendFileOptions extends FsOptions {
+    readonly mode?: number;
+}
+export interface MkdirOptions extends FsOptions {
+    /** Apply mode exactly to new entries, without an additional host umask. */
+    readonly exactMode?: boolean;
+    readonly recursive?: boolean;
+    readonly mode?: number;
+}
+export interface RemoveOptions extends FsOptions {
+    readonly recursive?: boolean;
+    readonly force?: boolean;
+}
+export interface CopyFileOptions extends FsOptions {
+    readonly exclusive?: boolean;
+}
+export interface ReadStreamOptions extends FsOptions {
+    readonly start?: number;
+    readonly endExclusive?: number;
+    readonly chunkSize?: number;
+}
+export interface ConditionalWriteFileOptions extends FsOptions {
+    readonly parent: FileStat;
+    readonly expected: FileStat | null;
+    readonly append?: boolean;
+    readonly mode?: number;
+    readonly atimeMs?: number;
+    readonly mtimeMs?: number;
+}
+export interface ConditionalRemoveEntryOptions extends FsOptions {
+    readonly parent: FileStat;
+    readonly expected: FileStat;
+}
+export interface ConditionalRemoveEntryReceiptOptions extends ConditionalRemoveEntryOptions {
+    readonly returnRemainingStat?: boolean | undefined;
+}
+export type ConditionalRemoveFileOptions = ConditionalRemoveEntryOptions;
+export interface FileStagingEntry {
+    readonly path: string;
+    readonly stat: FileStat;
+}
+export interface FileResolutionStep extends FileStagingEntry {
+    readonly linkTarget?: string;
+}
+export interface FileStagingResolution {
+    readonly path: string;
+    readonly parent: FileStat;
+    readonly destination: FileStat | null;
+    readonly ancestors: readonly FileStagingEntry[];
+    readonly traversed: readonly FileResolutionStep[];
+    readonly validate: () => true;
+}
+/** Ownership acquired with staging creation. remove is one-shot with shared
+ * completion; close drains admitted removal and releases without new mutation.
+ * Both release retained resources even after a failed removal. Call close when
+ * abandoning the staging receipt. An explicit cleanup signal is independent of
+ * the creation signal; scoped cleanup consumes the cleanup operation budget. */
+export interface FileStagingCleanup {
+    remove(options?: FsOptions): Promise<void>;
+    close(): Promise<void>;
+}
+export interface FileStaging {
+    readonly parent: FileStagingEntry;
+    readonly directory: FileStagingEntry;
+    readonly file: FileStagingEntry;
+    readonly cleanup?: FileStagingCleanup;
+    /** Available for retained regular-file staging on qualified backends. Writes
+     * append to the owned entry; finish seals it and returns its publication stat.
+     * Cleanup owns the lifetime and checks the last successfully written revision. */
+    readonly writer?: {
+        write(bytes: Uint8Array, options?: FsOptions): Promise<void>;
+        finish(options?: FsOptions): Promise<FileStat>;
+    };
+}
+export type StagedFileContent = {
+    readonly type: "file";
+    readonly data: Uint8Array;
+} | {
+    readonly type: "symlink";
+    readonly target: string;
+};
+export interface CreateStagedFileOptions extends FsOptions {
+    /** Requires retainedStagingCleanup; unsupported backends reject before creation. */
+    readonly retainCleanup?: boolean;
+    readonly parent: FileStat;
+    readonly mode?: number;
+    readonly atimeMs?: number;
+    readonly mtimeMs?: number;
+}
+export interface PublishStagedFileOptions extends FsOptions {
+    readonly ancestors?: readonly FileStagingEntry[];
+    /** Trusted, mutation-free validation. Must return literal true synchronously;
+     * a promise is not acceptance. Requires guardedStagingPublication. */
+    readonly commitGuard?: () => true;
+    readonly parent: FileStat;
+    readonly destination: FileStat | null;
+}
+/** Publish one staged regular file and validate/retire sibling source entries in
+ * the same indivisible commit. Every expected version (including absence) must
+ * match before any mutation. Hosts must not emulate this with sequential calls.
+ * Unavailable hosts omit publishStagedFileSet. Sources remain caller-owned. */
+export interface PublishStagedFileSetOptions extends PublishStagedFileOptions {
+    readonly companions: readonly {
+        readonly path: string;
+        readonly expected: FileStat | null;
+        readonly remove: boolean;
+    }[];
+}
+export interface PrepareDirectoryOptions extends FsOptions {
+    readonly expected: FileStat | null;
+    readonly parent: FileStat;
+    readonly mode?: number;
+    readonly atimeMs?: number;
+    readonly mtimeMs?: number;
+}
+export interface ConditionalFilePublicationOptions extends FsOptions {
+    readonly expected: FileStat | null;
+    readonly parent: FileStat;
+    readonly maxBytes: number;
+    readonly mode?: number;
+    readonly mtimeMs?: number;
+}
+export interface FileSystem {
+    /** Retain each extraction root and enforce no-symlink ancestry atomically with
+     * every mutation (including metadata and both hardlink paths). Returned views
+     * must refuse unsupported mutations; no check-then-write emulation is allowed.
+     * Roots and their ancestors must remain the retained directories. */
+    confineExtraction?(roots: readonly string[], options?: FsOptions): Promise<FileSystem>;
+    /** Explicit retained-object capability for qualified byte-path backends. */
+    readonly objects?: ObjectFileSystem;
+    /** Consume the complete source privately, then atomically compare/publish.
+     * Failures before commit preserve the destination. No stat/write fallback. */
+    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>;
+    removeTreeConditional?(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
+    removeFileConditional?(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
+    readonly capabilities: FileSystemCapabilities;
+    open?(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
+    prepareDirectory?(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
+    createStagedFile?(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    publishStagedFile?(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    publishStagedFileSet?(staging: FileStaging, destination: string, options: PublishStagedFileSetOptions): Promise<FileStat>;
+    /** Admit a complete canonical root-to-directory prefix and prepare a guard.
+     * The returned guard checks current identities/search access synchronously;
+     * preparation is not validation, and the guard's result is not an async lease. */
+    prepareDirectoryAncestry?(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
+    prepareStagingResolution?(path: string, options?: FsOptions): Promise<FileStagingResolution>;
+    removeStagedFile?(staging: FileStaging, options?: FsOptions): Promise<void>;
+    openReadFile?(path: string, options?: OpenReadFileOptions): Promise<FileReadHandle>;
+    openResizeFile?(path: string, options?: OpenResizeFileOptions): Promise<FileResizeHandle>;
+    /** Missing targets reject ENOENT unless create is true; existing bytes survive refusals. */
+    resizeFile?(path: string, operation: FileResizeOperation, options?: FileResizeOptions): Promise<void>;
+    canonicalizeMissingTarget?(path: string, options?: FsOptions): string | undefined;
+    capabilitiesFor?(path: string, options?: CapabilityQueryOptions): Promise<FileSystemCapabilities>;
+    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
+    stat(path: string, options?: FsOptions): Promise<FileStat>;
+    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[]>;
+    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. */
+    unlink?(path: string, options?: FsOptions): Promise<void>;
+    rmdir?(path: string, options?: FsOptions): Promise<void>;
+    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?(existingPath: string, newPath: string, options?: FsOptions): Promise<void>;
+    chmod?(path: string, mode: number, options?: ChmodOptions): Promise<void>;
+    utimes?(path: string, atimeMs: number, mtimeMs: number, options?: FsOptions): Promise<void>;
+    truncate?(path: string, length?: number, options?: FsOptions): Promise<void>;
+    readStream?(path: string, options?: ReadStreamOptions): ByteSource;
+    writeStream?(path: string, source: ByteSource, options?: WriteFileOptions): Promise<void>;
+}
+export type FileSystemFactory = (options: Readonly<Record<string, unknown>>) => FileSystem | Promise<FileSystem>;
+export declare const ACCESS_MODES: Readonly<{
+    F_OK: 0;
+    R_OK: 4;
+    W_OK: 2;
+    X_OK: 1;
+}>;

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

@@ -0,0 +1 @@
+export const ACCESS_MODES = Object.freeze({ F_OK: 0, R_OK: 4, W_OK: 2, X_OK: 1 });

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

@@ -0,0 +1,6 @@
+export * from "./errors.js";
+export * from "./filesystem.js";
+export * from "./io.js";
+export * from "./path.js";
+export * from "./object.js";
+export { compareIdentity, compareFileVersion } from "../fs/mount/identity.js";

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

@@ -0,0 +1,6 @@
+export * from "./errors.js";
+export * from "./filesystem.js";
+export * from "./io.js";
+export * from "./path.js";
+export * from "./object.js";
+export { compareIdentity, compareFileVersion } from "../fs/mount/identity.js";

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

@@ -0,0 +1,12 @@
+export type ByteSource = AsyncIterable<Uint8Array>;
+export interface CollectOptions {
+    readonly maxBytes?: number;
+    /** Owned capacity, current input backing storage, and replacement allocation peak. */
+    readonly maxMemoryBytes?: number;
+    readonly signal?: AbortSignal;
+}
+export declare function toByteSource(input: string | Uint8Array): ByteSource;
+export declare function collectBytes(source: ByteSource, options: CollectOptions): Promise<Uint8Array>;
+/** Subscribe when supported; callers must still check cancellation at operation boundaries. */
+export declare function listenForAbort(signal: AbortSignal, listener: () => void): () => void;
+export declare function readBytes(source: ByteSource, signal?: AbortSignal): AsyncGenerator<Uint8Array>;