@openclaw/fs-safe 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.2.2 - 2026-05-11
+
+### Fixes
+
+- Fall back to Node path guards for root stat and list operations on Windows, where the pinned Python helper is intentionally unsupported.
+
 ## 0.2.1 - 2026-05-08
 
 ### Fixes

package/dist/archive-utils.d.ts

@@ -0,0 +1,3 @@
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+//# sourceMappingURL=archive-utils.d.ts.map

package/dist/archive-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-utils.d.ts","sourceRoot":"","sources":["../src/archive-utils.ts"],"names":[],"mappings":"AAEA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE"}

package/dist/archive-utils.js

@@ -0,0 +1,26 @@
+import fs from "node:fs/promises";
+export async function withTimeout(promise, timeoutMs, label) {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+export async function fileExists(filePath) {
+    try {
+        await fs.stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/boundary-file-read.d.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import type { PathAliasPolicy } from "./path-alias-guards.js";
+import { type SafeOpenSyncAllowedType, type SafeOpenSyncFailureReason } from "./safe-open-sync.js";
+type BoundaryReadFs = Pick<typeof fs, "closeSync" | "constants" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "realpathSync">;
+export type BoundaryFileOpenFailureReason = SafeOpenSyncFailureReason | "validation";
+export type BoundaryFileOpenResult = {
+    ok: true;
+    path: string;
+    fd: number;
+    stat: fs.Stats;
+    rootRealPath: string;
+} | {
+    ok: false;
+    reason: BoundaryFileOpenFailureReason;
+    error?: unknown;
+};
+export type BoundaryFileOpenFailure = Extract<BoundaryFileOpenResult, {
+    ok: false;
+}>;
+export type OpenBoundaryFileSyncParams = {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    rootRealPath?: string;
+    maxBytes?: number;
+    rejectHardlinks?: boolean;
+    allowedType?: SafeOpenSyncAllowedType;
+    skipLexicalRootCheck?: boolean;
+    ioFs?: BoundaryReadFs;
+};
+export type OpenBoundaryFileParams = OpenBoundaryFileSyncParams & {
+    aliasPolicy?: PathAliasPolicy;
+};
+export declare function canUseBoundaryFileOpen(ioFs: typeof fs): boolean;
+export declare function openBoundaryFileSync(params: OpenBoundaryFileSyncParams): BoundaryFileOpenResult;
+export declare function matchBoundaryFileOpenFailure<T>(failure: BoundaryFileOpenFailure, handlers: {
+    path?: (failure: BoundaryFileOpenFailure) => T;
+    validation?: (failure: BoundaryFileOpenFailure) => T;
+    io?: (failure: BoundaryFileOpenFailure) => T;
+    fallback: (failure: BoundaryFileOpenFailure) => T;
+}): T;
+export declare function openBoundaryFile(params: OpenBoundaryFileParams): Promise<BoundaryFileOpenResult>;
+export {};
+//# sourceMappingURL=boundary-file-read.d.ts.map

package/dist/boundary-file-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-file-read.d.ts","sourceRoot":"","sources":["../src/boundary-file-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,yBAAyB,GAAG,YAAY,CAAC;AAErF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,6BAA6B,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAErF,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,GAAG;IAChE,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAQF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW/D;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,sBAAsB,CAuB/F;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,OAAO,EAAE,uBAAuB,EAChC,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC/C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IACrD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC7C,QAAQ,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;CACnD,GACA,CAAC,CAUH;AAoDD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,sBAAsB,CAAC,CAsBjC"}

package/dist/boundary-file-read.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveBoundaryPath, resolveBoundaryPathSync, } from "./boundary-path.js";
+import { openVerifiedFileSync, } from "./safe-open-sync.js";
+export function canUseBoundaryFileOpen(ioFs) {
+    return (typeof ioFs.openSync === "function" &&
+        typeof ioFs.closeSync === "function" &&
+        typeof ioFs.fstatSync === "function" &&
+        typeof ioFs.lstatSync === "function" &&
+        typeof ioFs.realpathSync === "function" &&
+        typeof ioFs.readFileSync === "function" &&
+        typeof ioFs.constants === "object" &&
+        ioFs.constants !== null);
+}
+export function openBoundaryFileSync(params) {
+    const ioFs = params.ioFs ?? fs;
+    const resolved = resolveBoundaryFilePathGeneric({
+        absolutePath: params.absolutePath,
+        resolve: (absolutePath) => resolveBoundaryPathSync({
+            absolutePath,
+            rootPath: params.rootPath,
+            rootCanonicalPath: params.rootRealPath,
+            boundaryLabel: params.boundaryLabel,
+            skipLexicalRootCheck: params.skipLexicalRootCheck,
+        }),
+    });
+    if (resolved instanceof Promise) {
+        return toBoundaryValidationError(new Error("Unexpected async boundary resolution"));
+    }
+    return finalizeBoundaryFileOpen({
+        resolved,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs,
+    });
+}
+export function matchBoundaryFileOpenFailure(failure, handlers) {
+    switch (failure.reason) {
+        case "path":
+            return handlers.path ? handlers.path(failure) : handlers.fallback(failure);
+        case "validation":
+            return handlers.validation ? handlers.validation(failure) : handlers.fallback(failure);
+        case "io":
+            return handlers.io ? handlers.io(failure) : handlers.fallback(failure);
+    }
+    return handlers.fallback(failure);
+}
+function openBoundaryFileResolved(params) {
+    const opened = openVerifiedFileSync({
+        filePath: params.absolutePath,
+        resolvedPath: params.resolvedPath,
+        rejectHardlinks: params.rejectHardlinks ?? true,
+        maxBytes: params.maxBytes,
+        allowedType: params.allowedType,
+        ioFs: params.ioFs,
+    });
+    if (!opened.ok) {
+        return opened;
+    }
+    return {
+        ok: true,
+        path: opened.path,
+        fd: opened.fd,
+        stat: opened.stat,
+        rootRealPath: params.rootRealPath,
+    };
+}
+function finalizeBoundaryFileOpen(params) {
+    if ("ok" in params.resolved) {
+        return params.resolved;
+    }
+    return openBoundaryFileResolved({
+        absolutePath: params.resolved.absolutePath,
+        resolvedPath: params.resolved.resolvedPath,
+        rootRealPath: params.resolved.rootRealPath,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs: params.ioFs,
+    });
+}
+export async function openBoundaryFile(params) {
+    const ioFs = params.ioFs ?? fs;
+    const maybeResolved = resolveBoundaryFilePathGeneric({
+        absolutePath: params.absolutePath,
+        resolve: (absolutePath) => resolveBoundaryPath({
+            absolutePath,
+            rootPath: params.rootPath,
+            rootCanonicalPath: params.rootRealPath,
+            boundaryLabel: params.boundaryLabel,
+            policy: params.aliasPolicy,
+            skipLexicalRootCheck: params.skipLexicalRootCheck,
+        }),
+    });
+    const resolved = maybeResolved instanceof Promise ? await maybeResolved : maybeResolved;
+    return finalizeBoundaryFileOpen({
+        resolved,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs,
+    });
+}
+function toBoundaryValidationError(error) {
+    return { ok: false, reason: "validation", error };
+}
+function mapResolvedBoundaryPath(absolutePath, resolved) {
+    return {
+        absolutePath,
+        resolvedPath: resolved.canonicalPath,
+        rootRealPath: resolved.rootCanonicalPath,
+    };
+}
+function resolveBoundaryFilePathGeneric(params) {
+    const absolutePath = path.resolve(params.absolutePath);
+    try {
+        const resolved = params.resolve(absolutePath);
+        if (resolved instanceof Promise) {
+            return resolved
+                .then((value) => mapResolvedBoundaryPath(absolutePath, value))
+                .catch((error) => toBoundaryValidationError(error));
+        }
+        return mapResolvedBoundaryPath(absolutePath, resolved);
+    }
+    catch (error) {
+        return toBoundaryValidationError(error);
+    }
+}

package/dist/boundary-path.d.ts

@@ -0,0 +1,39 @@
+type BoundaryPathIntent = "read" | "write" | "create" | "delete" | "stat";
+export type BoundaryPathAliasPolicy = {
+    allowFinalSymlinkForUnlink?: boolean;
+    allowFinalHardlinkForUnlink?: boolean;
+};
+export declare const BOUNDARY_PATH_ALIAS_POLICIES: {
+    readonly strict: Readonly<{
+        allowFinalSymlinkForUnlink: false;
+        allowFinalHardlinkForUnlink: false;
+    }>;
+    readonly unlinkTarget: Readonly<{
+        allowFinalSymlinkForUnlink: true;
+        allowFinalHardlinkForUnlink: true;
+    }>;
+};
+type ResolveBoundaryPathParams = {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    intent?: BoundaryPathIntent;
+    policy?: BoundaryPathAliasPolicy;
+    skipLexicalRootCheck?: boolean;
+    rootCanonicalPath?: string;
+};
+type ResolvedBoundaryPathKind = "missing" | "file" | "directory" | "symlink" | "other";
+export type ResolvedBoundaryPath = {
+    absolutePath: string;
+    canonicalPath: string;
+    rootPath: string;
+    rootCanonicalPath: string;
+    relativePath: string;
+    exists: boolean;
+    kind: ResolvedBoundaryPathKind;
+};
+export declare function resolveBoundaryPath(params: ResolveBoundaryPathParams): Promise<ResolvedBoundaryPath>;
+export declare function resolveBoundaryPathSync(params: ResolveBoundaryPathParams): ResolvedBoundaryPath;
+export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;
+export {};
+//# sourceMappingURL=boundary-path.d.ts.map

package/dist/boundary-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-path.d.ts","sourceRoot":"","sources":["../src/boundary-path.ts"],"names":[],"mappings":"AAMA,KAAK,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG;IACpC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;CAS/B,CAAC;AAEX,KAAK,yBAAyB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,wBAAwB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvF,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,wBAAwB,CAAC;CAChC,CAAC;AAEF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,oBAAoB,CAAC,CA+B/B;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,yBAAyB,GAAG,oBAAoB,CA+B/F;AAmkBD,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA6B7E"}