@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/replace-file-temp-owner.js

@@ -57,6 +57,15 @@ function cleanupFailure(originalFailure, cleanupError) {
     }
     return isErrorValue(cleanupError) ? cleanupError : new Error(describeFailure(cleanupError));
 }
+function closeFailure(closeError, params, cleanupFailure) {
+    return {
+        error: cleanupFailure
+            ? new AggregateError([cleanupFailure.error, closeError], "Atomic temp cleanup and close failed")
+            : params.originalFailure
+                ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
+                : closeError,
+    };
+}
 async function cleanupOwnedPath(params) {
     try {
         await removeOwnedPath(params);
@@ -92,36 +101,48 @@ function cleanupOwnedPathSync(params) {
         return false;
     }
 }
-export class AsyncAtomicTempOwner {
+class AtomicTempOwner {
     pathname;
-    #handle;
-    #identity;
-    #exists = false;
-    #unregister;
+    resource;
+    recordedIdentity;
+    exists = false;
+    unregister;
     constructor(pathname) {
         this.pathname = pathname;
-        this.#unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
+        this.unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
     }
     start() {
-        this.#exists = true;
+        this.exists = true;
     }
     onIdentity = (identity) => {
-        this.#identity = identity;
-        this.#unregister.setIdentity(identity);
+        this.recordedIdentity = identity;
+        this.unregister.setIdentity(identity);
     };
-    adopt(temp) {
-        this.#handle = temp.handle;
-        this.onIdentity(temp.identity);
-    }
     get identity() {
-        if (!this.#identity)
+        if (!this.recordedIdentity)
             throw new Error("Atomic temp owner has no identity");
-        return this.#identity;
+        return this.recordedIdentity;
+    }
+    markRenamed() {
+        this.exists = false;
+        this.unregister();
+    }
+    takeResource() {
+        // A throwing close may already have released the descriptor for reuse.
+        const resource = this.resource;
+        this.resource = undefined;
+        return resource;
+    }
+}
+export class AsyncAtomicTempOwner extends AtomicTempOwner {
+    adopt(temp) {
+        this.resource = temp.handle;
+        this.onIdentity(temp.identity);
     }
     async assertCurrent(fsModule, pathname = this.pathname) {
         const opened = await inspectFileIdentity(async () => {
-            const stat = fsModule === fs ? syncFs.fstatSync(this.#handle.fd, { bigint: true })
-                : await this.#handle.stat({ bigint: true });
+            const stat = fsModule === fs ? syncFs.fstatSync(this.resource.fd, { bigint: true })
+                : await this.resource.stat({ bigint: true });
             assertOwnedFile(stat, pathname, false);
             return stat;
         }, this.identity);
@@ -178,30 +199,30 @@ export class AsyncAtomicTempOwner {
             if (sha256Hex(await published.readFile()) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
-            const previousHandle = this.#handle;
-            this.#handle = undefined;
+            const previousHandle = this.takeResource();
             await previousHandle?.close();
-            this.#handle = published;
-            this.#identity = identity;
+            this.resource = published;
+            this.recordedIdentity = identity;
             published = undefined;
         }
         finally {
-            await published?.close().catch(() => undefined);
+            try {
+                await published?.close();
+            }
+            catch {
+                // Preserve the selected verification or previous-handle close failure.
+            }
         }
     }
-    markRenamed() {
-        this.#exists = false;
-        this.#unregister();
-    }
     async finish(params) {
         let deferredFailure;
-        let cleanupComplete = !this.#exists;
-        if (this.#exists) {
+        let cleanupComplete = !this.exists;
+        if (this.exists) {
             try {
                 cleanupComplete = await cleanupOwnedPath({
                     fsModule: params.fsModule,
                     pathname: this.pathname,
-                    identity: this.#identity,
+                    identity: this.recordedIdentity,
                     originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
@@ -211,54 +232,26 @@ export class AsyncAtomicTempOwner {
             }
         }
         if (cleanupComplete)
-            this.#unregister();
-        const handle = this.#handle;
-        this.#handle = undefined;
+            this.unregister();
+        const handle = this.takeResource();
         try {
             await handle?.close();
         }
         catch (closeError) {
-            deferredFailure = {
-                error: deferredFailure
-                    ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
-                    : params.originalFailure
-                        ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
-                        : closeError,
-            };
+            deferredFailure = closeFailure(closeError, params, deferredFailure);
         }
         if (deferredFailure)
             throw deferredFailure.error;
     }
 }
-export class SyncAtomicTempOwner {
-    pathname;
-    #fd;
-    #identity;
-    #exists = false;
-    #unregister;
-    constructor(pathname) {
-        this.pathname = pathname;
-        this.#unregister = registerTempPathForExit(pathname, { singleLinkFile: true });
-    }
-    start() {
-        this.#exists = true;
-    }
-    onIdentity = (identity) => {
-        this.#identity = identity;
-        this.#unregister.setIdentity(identity);
-    };
+export class SyncAtomicTempOwner extends AtomicTempOwner {
     adopt(temp) {
-        this.#fd = temp.fd;
+        this.resource = temp.fd;
         this.onIdentity(temp.identity);
     }
-    get identity() {
-        if (!this.#identity)
-            throw new Error("Atomic temp owner has no identity");
-        return this.#identity;
-    }
     assertCurrent(fsModule, pathname = this.pathname) {
         const opened = inspectFileIdentitySync(() => {
-            const stat = fsModule.fstatSync(this.#fd, { bigint: true });
+            const stat = fsModule.fstatSync(this.resource, { bigint: true });
             assertOwnedFile(stat, pathname, false);
             return stat;
         }, this.identity);
@@ -312,11 +305,10 @@ export class SyncAtomicTempOwner {
             if (sha256Hex(fsModule.readFileSync(publishedFd)) !== expectedHash) {
                 throw new FsSafeError("path-mismatch", `Atomic replace published content changed: ${pathname}`);
             }
-            const previousFd = this.#fd;
-            this.#fd = undefined;
+            const previousFd = this.takeResource();
             fsModule.closeSync(previousFd);
-            this.#fd = publishedFd;
-            this.#identity = identity;
+            this.resource = publishedFd;
+            this.recordedIdentity = identity;
             publishedFd = undefined;
         }
         finally {
@@ -330,19 +322,15 @@ export class SyncAtomicTempOwner {
             }
         }
     }
-    markRenamed() {
-        this.#exists = false;
-        this.#unregister();
-    }
     finish(params) {
         let deferredFailure;
-        let cleanupComplete = !this.#exists;
-        if (this.#exists) {
+        let cleanupComplete = !this.exists;
+        if (this.exists) {
             try {
                 cleanupComplete = cleanupOwnedPathSync({
                     fsModule: params.fsModule,
                     pathname: this.pathname,
-                    identity: this.#identity,
+                    identity: this.recordedIdentity,
                     originalFailure: params.originalFailure,
                     throwOnCleanupError: params.throwOnCleanupError,
                 });
@@ -352,21 +340,14 @@ export class SyncAtomicTempOwner {
             }
         }
         if (cleanupComplete)
-            this.#unregister();
-        if (this.#fd !== undefined) {
-            const fd = this.#fd;
-            this.#fd = undefined;
+            this.unregister();
+        const fd = this.takeResource();
+        if (fd !== undefined) {
             try {
                 params.fsModule.closeSync(fd);
             }
             catch (closeError) {
-                deferredFailure = {
-                    error: deferredFailure
-                        ? new AggregateError([deferredFailure.error, closeError], "Atomic temp cleanup and close failed")
-                        : params.originalFailure
-                            ? new AggregateError([params.originalFailure.error, closeError], "Atomic file replace and close failed")
-                            : closeError,
-                };
+                deferredFailure = closeFailure(closeError, params, deferredFailure);
             }
         }
         if (deferredFailure)

package/dist/replace-file.d.ts

@@ -1,7 +1,7 @@
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
-import { type ReplaceFileAtomicRestoreCleanup, type ReplaceFileAtomicRestoreFailureDetails, type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
-import { type RenameIdentityPolicy } from "./replace-file-rename-policy.js";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
+import { type ReplaceFileCopyFallbackRestorePolicy, type ReplaceFileDestinationHardlinkPolicy } from "./replace-file-copy-fallback.js";
 export type ReplaceFileAtomicFileSystem = {
     promises: Pick<typeof fs, "mkdir" | "writeFile" | "rename" | "copyFile" | "unlink" | "rm" | "open" | "stat" | "lstat"> & {
         /** @deprecated Accepted for adapter compatibility but never called. */
@@ -13,7 +13,6 @@ export type ReplaceFileAtomicSyncFileSystem = Pick<typeof syncFs, "mkdirSync" |
     chmodSync?: typeof syncFs.chmodSync;
     fchmodSync?: typeof syncFs.fchmodSync;
 };
-export type { RenameIdentityPolicy, ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, };
 type ReplaceFileAtomicBaseOptions = {
     filePath: string;
     content: string | Uint8Array;
@@ -56,4 +55,4 @@ export type ReplaceFileAtomicResult = {
 export declare function replaceFileAtomic(options: ReplaceFileAtomicOptions): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicWithDirectorySync(options: ReplaceFileAtomicOptions, syncParent?: (directoryPath: string) => Promise<unknown>): Promise<ReplaceFileAtomicResult>;
 export declare function replaceFileAtomicSync(options: ReplaceFileAtomicSyncOptions): ReplaceFileAtomicResult;
-//# sourceMappingURL=replace-file.d.ts.map
+export {};

package/dist/replace-file.js

@@ -9,7 +9,7 @@ import { inheritedRegularFileMode } from "./replace-file-mode.js";
 import { atomicExpectedContentHash, validateRenameIdentity, withAtomicRenameIdentityLock, withAtomicRenameIdentityLockSync, } from "./replace-file-rename-policy.js";
 import { AsyncAtomicTempOwner, SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
 import { assertSafePathPrefix } from "./safe-path-segment.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 import { sleep, sleepSync } from "./timing.js";
 import { serializePathWrite } from "./write-queue.js";
 import { hasErrorCode, readErrorCode } from "./file-cleanup.js";

package/dist/retained-directory-replacement.d.ts

@@ -23,4 +23,3 @@ export declare class RetainedDirectoryReplacement {
     close(): void;
 }
 export {};
-//# sourceMappingURL=retained-directory-replacement.d.ts.map

package/dist/root-boundary.d.ts

@@ -27,4 +27,3 @@ export declare function admitPathInsideRoot(params: {
         ino: bigint;
     }>) => void;
 }): AdmittedRootPath | undefined;
-//# sourceMappingURL=root-boundary.d.ts.map

package/dist/root-context.d.ts

@@ -41,4 +41,3 @@ export declare function resolvePathInRoot(root: RootContext, relativePath: strin
     rootWithSep: string;
     resolved: string;
 }>;
-//# sourceMappingURL=root-context.d.ts.map

package/dist/root-context.js

@@ -7,7 +7,7 @@ import { sameFileIdentity } from "./file-identity.js";
 import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, } from "./path.js";
 import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath } from "./root-path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
-import { outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
+import { errorCauseOptions, outsideWorkspaceError, rootPathChangedError } from "./root-errors.js";
 import { isDriveRelativePath } from "./safe-path-segment.js";
 import { realpathSync } from "./realpath.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
@@ -223,14 +223,10 @@ export async function resolvePathInRoot(root, relativePath, options) {
             throw error;
         }
         if (hasNodeErrorCode(error, "ENAMETOOLONG")) {
-            throw new FsSafeError("invalid-path", "relative path is too long", {
-                cause: error instanceof Error ? error : undefined,
-            });
+            throw new FsSafeError("invalid-path", "relative path is too long", errorCauseOptions(error));
         }
         const code = options?.aliasErrorCode ?? "outside-workspace";
-        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        throw new FsSafeError(code, code === "path-alias" ? "path alias escape blocked" : "file is outside workspace root", errorCauseOptions(error));
     }
     return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
 }

package/dist/root-create-input.d.ts

@@ -1,4 +1,4 @@
-import type { PinnedWriteInput } from "./pinned-write.js";
+import type { PinnedWriteInput } from "./pinned-write-types.js";
 import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
 declare const exclusiveSidecarCreate: unique symbol;
 export declare const sidecarExclusiveCreate: Readonly<{
@@ -14,4 +14,3 @@ export declare function rethrowCreateInputError(error: unknown): never;
 export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;
 export declare function rootWriteInput(params: RootWriteParams): PinnedWriteInput;
 export {};
-//# sourceMappingURL=root-create-input.d.ts.map

package/dist/root-directory-creation.d.ts

@@ -1,4 +1,4 @@
-import type { PinnedWriteMutationAdmission } from "./pinned-write.js";
+import type { PinnedWriteMutationAdmission } from "./pinned-write-types.js";
 import { type RootContext } from "./root-context.js";
 /**
  * Complete the common Root.mkdir case with one exact existing parent. This is
@@ -10,4 +10,3 @@ export declare function mkdirPathFallback(root: RootContext, resolved: {
     rootReal: string;
     resolved: string;
 }, assertBeforeMutation?: () => void, rejectSymlinks?: boolean, mutationAdmission?: PinnedWriteMutationAdmission, privateMode?: boolean): Promise<void>;
-//# sourceMappingURL=root-directory-creation.d.ts.map

package/dist/root-directory-creation.js

@@ -1,7 +1,7 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { assertPrivateDirectory } from "./creation-permissions.js";
+import { assertPrivateDirectory } from "./creation-boundary.js";
 import { assertAsyncDirectoryGuard, assertDirectoryIdentitySync, assertSyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";

package/dist/root-directory-list.d.ts

@@ -36,4 +36,3 @@ export type RootDirectoryListingOptions = {
     admitEntry(): boolean;
 };
 export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
-//# sourceMappingURL=root-directory-list.d.ts.map

package/dist/root-directory-list.js

@@ -7,7 +7,7 @@ import { FsSafeError } from "./errors.js";
 import { inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
-import { rootPathChangedError } from "./root-errors.js";
+import { errorCauseOptions, rootPathChangedError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { realpathSync } from "./realpath.js";
@@ -50,9 +50,7 @@ export async function createRootDirectoryObservationGuard(root, directory) {
 function directoryChangedError(error) {
     if (error instanceof FsSafeError && error.code === "path-mismatch")
         return error;
-    return new FsSafeError("path-mismatch", "directory changed during operation", {
-        cause: error instanceof Error ? error : undefined,
-    });
+    return new FsSafeError("path-mismatch", "directory changed during operation", errorCauseOptions(error));
 }
 export async function assertRootDirectoryObservationGuard(root, guard) {
     if (isNativeDirectoryObservationGuard(guard)) {
@@ -162,9 +160,7 @@ export function assertRootPathObservationReceiptCurrent(root, receipt, finalTarg
 }
 function normalizeDirectoryError(error) {
     if (isNotFoundPathError(error)) {
-        return new FsSafeError("not-found", "directory not found", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("not-found", "directory not found", errorCauseOptions(error));
     }
     return error;
 }

package/dist/root-directory.d.ts

@@ -20,4 +20,3 @@ export declare function ensureDirectoryWithinRoot(params: {
     defaultDirName?: string;
     mode?: number;
 }): Promise<DirectoryResult>;
-//# sourceMappingURL=root-directory.d.ts.map

package/dist/root-entries.d.ts

@@ -8,4 +8,3 @@ export type RootEntriesOptions = {
     symlinks?: SymlinkPolicy;
 };
 export declare function entriesInRoot(root: RootContext, relativePath: string, options: RootEntriesOptions): AsyncGenerator<DirEntry>;
-//# sourceMappingURL=root-entries.d.ts.map

package/dist/root-entries.js

@@ -1,5 +1,5 @@
 import { FsSafeError } from "./errors.js";
-import { validatePinnedOperationPayload } from "./pinned-operation.js";
+import { validatePinnedRelativePath } from "./pinned-operation.js";
 import { resolvePathInRoot } from "./root-context.js";
 import { openRootDirectoryListing } from "./root-directory-list.js";
 import { readSymlinkResolution } from "./root-symlink-policy.js";
@@ -13,7 +13,7 @@ export async function* entriesInRoot(root, relativePath, options) {
         throw new TypeError(`invalid root entries order: ${String(options.order)}`);
     }
     options.signal?.throwIfAborted();
-    validatePinnedOperationPayload({ relativePath });
+    validatePinnedRelativePath(relativePath);
     const resolved = await resolvePathInRoot(root, relativePath, {
         ...readSymlinkResolution(options.symlinks),
         resolveCanonical: true,

package/dist/root-errors.d.ts

@@ -10,4 +10,7 @@ export declare function normalizePinnedPathError(error: unknown, details?: FsSaf
 export declare function normalizeRemoveGuardError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function normalizeRemovePathError(error: unknown, details?: FsSafeErrorDetails): Error;
 export declare function throwFsSafeReadError(error: unknown, label: string): never;
-//# sourceMappingURL=root-errors.d.ts.map
+/** Existing boundaries retain only Error instances as their cause. */
+export declare function errorCauseOptions(error: unknown): {
+    cause: Error | undefined;
+};

package/dist/root-errors.js

@@ -41,9 +41,7 @@ export function normalizePinnedWriteError(error) {
     const message = code
         ? `${PINNED_WRITE_ERRNO_MESSAGES.get(code) ?? "filesystem write failed"} (${code})`
         : "path is not a regular file under root";
-    return new FsSafeError("invalid-path", message, {
-        cause: error instanceof Error ? error : undefined,
-    });
+    return new FsSafeError("invalid-path", message, errorCauseOptions(error));
 }
 export function normalizePinnedPathError(error, details) {
     if (error instanceof FsSafeError) {
@@ -88,3 +86,7 @@ export function throwFsSafeReadError(error, label) {
     }
     throw error;
 }
+/** Existing boundaries retain only Error instances as their cause. */
+export function errorCauseOptions(error) {
+    return { cause: error instanceof Error ? error : undefined };
+}

package/dist/root-file-final-admission.d.ts

@@ -18,4 +18,3 @@ export declare function createRootFileFinalAdmission(ioFs: RootFileAdmissionFs,
     ok: true;
 }>, boundaryLabel: string, rejectHardlinks?: boolean): PinnedOpenSyncFinalAdmission;
 export {};
-//# sourceMappingURL=root-file-final-admission.d.ts.map

package/dist/root-file.d.ts

@@ -44,4 +44,3 @@ export declare function matchRootFileOpenFailure<T>(failure: RootFileOpenFailure
 }): T;
 export declare function openRootFile(params: OpenRootFileParams): Promise<RootFileOpenResult>;
 export {};
-//# sourceMappingURL=root-file.d.ts.map

package/dist/root-impl.d.ts

@@ -7,13 +7,8 @@ import { type RootContext } from "./root-context.js";
 import type { DirEntry, PathStat } from "./types.js";
 import { type RootWalkEntry, type RootWalkOptions } from "./root-walk.js";
 import { type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions } from "./root-options.js";
-export type { HardlinkPolicy, RootAppendOptions, RootCopyOptions, RootCopySource, RootCreateJsonOptions, RootCreateOptions, RootCreateStreamOptions, RootDefaults, RootMkdirOptions, RootMoveOptions, RootOpenOptions, RootOpenWritableOptions, RootOptions, RootReadOptions, RootRemoveOptions, RootWriteJsonOptions, RootWriteOptions, WritableOpenMode, } from "./root-options.js";
 export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
-export type { DenyMutationPolicy } from "./deny-mutations.js";
-export type { RenameIdentityPolicy } from "./pinned-write.js";
-export type { MutationSymlinkPolicy, SymlinkPolicy } from "./root-symlink-policy.js";
 export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
-export type { ReadResult } from "./read-opened-file.js";
 export type OpenResult = {
     handle: FileHandle;
     containment: ContainmentGuarantee;
@@ -62,14 +57,12 @@ export interface Root {
     walk(relativePath: string, options: RootWalkOptions): AsyncIterableIterator<RootWalkEntry>;
 }
 export declare class RootHandle implements Root {
-    private readonly rootGuard;
-    private readonly rootIdentity;
+    private readonly context;
     readonly rootDir: string;
     readonly rootReal: string;
     readonly rootWithSep: string;
     readonly defaults: RootDefaults;
     constructor(context: RootContext, defaults?: RootDefaults);
-    private get context();
     private mutationOptions;
     resolve(relativePath: string): Promise<string>;
     open(relativePath: string, options?: RootOpenOptions): Promise<OpenResult>;
@@ -119,12 +112,6 @@ export declare function readLocalFileSafely(params: {
 export declare function openLocalFileSafely(params: {
     filePath: string;
 }): Promise<OpenResult>;
-export type WritableOpenResult = {
-    handle: FileHandle;
-    containment: ContainmentGuarantee;
+export type WritableOpenResult = OpenResult & {
     createdForWrite: boolean;
-    realPath: string;
-    stat: Stats;
-    [Symbol.asyncDispose](): Promise<void>;
 };
-//# sourceMappingURL=root-impl.d.ts.map