@openclaw/fs-safe 0.5.6 → 0.6.0

package/dist/native-staged-file.js

@@ -0,0 +1,337 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { syncNativeFileBestEffort, writeNativeInput } from "./native-operations.js";
+import { assertStagedDirectoryCurrent } from "./staged-directory.js";
+export function assertNativeStaging(binding) {
+    if ([
+        binding.createStagedFile,
+        binding.stagedFileMatches,
+        binding.removeStagedFile,
+        binding.renameReplace,
+        binding.renameNoReplace,
+    ].some((fn) => typeof fn !== "function")) {
+        throw new FsSafeError("helper-unavailable", "native retained-directory staging is unavailable");
+    }
+}
+function assertBasename(name, portable) {
+    if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0") ||
+        (portable && /[\\:\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(name))) {
+        throw new FsSafeError("invalid-path", "publication requires one direct-child basename");
+    }
+}
+const NOT_PUBLISHED = Object.freeze({ status: "not-published" });
+const UNCOMMITTED_RENAME_ERRORS = new Set([
+    "EACCES", "EBADF", "EBUSY", "EEXIST", "EINVAL", "EISDIR", "ELOOP", "EMLINK",
+    "ENAMETOOLONG", "ENOENT", "ENOSPC", "ENOSYS", "ENOTDIR", "ENOTEMPTY", "ENOTSUP",
+    "EPERM", "EROFS", "ETXTBSY", "EXDEV",
+]);
+function failure(error, details) {
+    const code = error instanceof FsSafeError
+        ? error.code
+        : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
+    return new FsSafeError(code, `staged file ${details.phase} failed`, { cause: error, details });
+}
+class NativeStagedFile {
+    #binding;
+    #parentFd;
+    #directory;
+    #portableNames;
+    #publishedMode;
+    #name = `.fs-safe-${randomUUID()}.tmp`;
+    #state = { status: "open", publication: NOT_PUBLISHED };
+    #receipt;
+    constructor(binding, parentFd, directory, portableNames, publishedMode) {
+        this.#binding = binding;
+        this.#parentFd = parentFd;
+        this.#directory = directory;
+        this.#portableNames = portableNames;
+        this.#publishedMode = publishedMode;
+    }
+    // Takes ownership of parentFd, including all construction and preparation failures.
+    static async create(binding, parentFd, directory, input, mode, maxBytes, 
+    // Public staging uses portable names; existing POSIX writes accept literal names.
+    portableNames = true) {
+        let staged;
+        try {
+            staged = new NativeStagedFile(binding, parentFd, directory, portableNames, mode);
+        }
+        catch (error) {
+            try {
+                fs.closeSync(parentFd);
+            }
+            catch (closeError) {
+                throw new AggregateError([error, closeError], "staged owner construction and close failed");
+            }
+            throw error;
+        }
+        await staged.#prepare(input, maxBytes);
+        return staged;
+    }
+    static async write(binding, parentFd, directory, params, parentGuard) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            // This owner never escapes. Only the internal verifier borrows its fd;
+            // public descriptor methods remain await-free and cannot race disposal.
+            const staged = __addDisposableResource(env_1, await NativeStagedFile.create(binding, parentFd, directory, params.input, params.mode, params.maxBytes, false), true);
+            const published = await staged.publish(params.basename, { overwrite: params.overwrite !== false });
+            const identity = published.staged.identity;
+            await params.verifyPublished?.(staged.#file(), identity, parentGuard);
+            return { dev: identity.dev, ino: identity.ino };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    }
+    get receipt() {
+        if (!this.#receipt) {
+            throw new FsSafeError("helper-failed", "staged file preparation is incomplete");
+        }
+        return this.#receipt;
+    }
+    #open() {
+        if (this.#state.status === "closed") {
+            throw new FsSafeError("helper-failed", "staged file is closed");
+        }
+        return this.#state;
+    }
+    #file() {
+        const state = this.#open();
+        if (state.fileFd === undefined) {
+            throw new FsSafeError("helper-failed", "staged file has not been created");
+        }
+        return state.fileFd;
+    }
+    #assertNamed(name) {
+        const fd = this.#file();
+        if (!this.#binding.stagedFileMatches(this.#parentFd, name, fd) ||
+            fs.fstatSync(fd, { bigint: true }).nlink !== 1n) {
+            throw new FsSafeError("path-mismatch", "staged entry no longer names the exclusive created file");
+        }
+    }
+    #assertCurrent() {
+        if (this.#open().publication.status !== "not-published") {
+            throw new FsSafeError("helper-failed", "staged file publication has already been attempted");
+        }
+        assertStagedDirectoryCurrent(this.#directory);
+        this.#assertNamed(this.#name);
+    }
+    async #prepare(input, maxBytes) {
+        try {
+            const mode = this.#publishedMode;
+            if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
+                throw new FsSafeError("invalid-path", "invalid staged file mode");
+            }
+            assertStagedDirectoryCurrent(this.#directory);
+            // The exclusive open performs no fallible post-open checks. Store its fd
+            // before every subsequent operation, including the first metadata read.
+            const state = this.#open();
+            state.fileFd = this.#binding.createStagedFile(this.#parentFd, this.#name);
+            const fd = state.fileFd;
+            fs.fchmodSync(fd, 0o600);
+            await writeNativeInput(fd, input, maxBytes);
+            syncNativeFileBestEffort(fd);
+            const stat = fs.fstatSync(fd, { bigint: true });
+            this.#receipt = Object.freeze({
+                directory: this.#directory,
+                temporaryBasename: this.#name,
+                identity: Object.freeze({
+                    dev: stat.dev,
+                    ino: stat.ino,
+                    mode: Number(stat.mode & 4095n),
+                    nlink: stat.nlink,
+                    size: stat.size,
+                    uid: Number(stat.uid),
+                    gid: Number(stat.gid),
+                    mtimeNs: stat.mtimeNs,
+                    ctimeNs: stat.ctimeNs,
+                }),
+            });
+            this.#assertCurrent();
+        }
+        catch (error) {
+            const { receipt: cleanup, error: cleanupError } = this.#finalize();
+            if (cleanupError) {
+                throw failure(new AggregateError([error, cleanupError], "preparation and cleanup failed"), { phase: "prepare", publication: cleanup.publication, cleanup });
+            }
+            if (cleanup.status === "preserved") {
+                throw failure(error, { phase: "prepare", publication: cleanup.publication, cleanup });
+            }
+            throw error;
+        }
+    }
+    // Keep public descriptor work await-free: each call completes its mutations
+    // before the next invocation, including closure and cached cleanup failures.
+    async assertCurrent() {
+        this.#assertCurrent();
+    }
+    async publish(basename, options) {
+        const overwrite = options?.overwrite;
+        try {
+            const state = this.#open();
+            assertBasename(basename, this.#portableNames);
+            if (basename === this.#name || typeof overwrite !== "boolean") {
+                throw new FsSafeError("invalid-path", "publication needs a distinct basename and explicit overwrite policy");
+            }
+            this.#assertCurrent();
+            try {
+                if (overwrite) {
+                    this.#binding.renameReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                }
+                else {
+                    this.#binding.renameNoReplace(this.#parentFd, this.#name, this.#parentFd, basename);
+                }
+            }
+            catch (error) {
+                // Unknown rename errors can be indeterminate on remote filesystems.
+                if (!UNCOMMITTED_RENAME_ERRORS.has(error?.code ?? "")) {
+                    state.publication = Object.freeze({ status: "indeterminate", basename, overwrite });
+                }
+                throw error;
+            }
+            // Commit is recorded synchronously before any post-rename operation.
+            const receipt = Object.freeze({
+                status: "published",
+                staged: this.receipt,
+                basename,
+                overwrite,
+            });
+            state.publication = receipt;
+            this.#assertNamed(basename);
+            assertStagedDirectoryCurrent(this.#directory);
+            // Keep contents private until the published name passes its identity
+            // fence. Mode changes use the owned fd, including for final mode 000.
+            const fd = this.#file();
+            fs.fchmodSync(fd, this.#publishedMode);
+            syncNativeFileBestEffort(fd);
+            syncNativeFileBestEffort(this.#parentFd);
+            this.#assertNamed(basename);
+            assertStagedDirectoryCurrent(this.#directory);
+            return receipt;
+        }
+        catch (error) {
+            // Closure rejects further use, not the recorded outcome of an earlier publication.
+            const publication = this.#state.status === "closed"
+                ? this.#state.receipt.publication
+                : this.#state.publication;
+            throw failure(error, { phase: "publish", publication });
+        }
+    }
+    #finalize() {
+        if (this.#state.status === "closed") {
+            return this.#state;
+        }
+        const state = this.#state;
+        let outcome = "not-needed";
+        const errors = [];
+        if (state.publication.status === "indeterminate") {
+            outcome = "preserved";
+        }
+        else if (state.publication.status === "not-published" && state.fileFd !== undefined) {
+            try {
+                outcome = this.#binding.removeStagedFile(this.#parentFd, this.#name, state.fileFd);
+            }
+            catch (error) {
+                outcome = "failed";
+                errors.push(error);
+            }
+        }
+        let resources = "closed";
+        for (const fd of [state.fileFd, this.#parentFd]) {
+            if (fd === undefined) {
+                continue;
+            }
+            try {
+                fs.closeSync(fd);
+            }
+            catch (error) {
+                resources = "close-failed";
+                errors.push(error);
+            }
+        }
+        const receipt = Object.freeze({
+            temporaryBasename: this.#name,
+            publication: state.publication,
+            status: outcome,
+            resources,
+        });
+        const error = errors.length ? failure(errors.length === 1 ? errors[0] : new AggregateError(errors, "staged cleanup failed"), { phase: "cleanup", publication: state.publication, cleanup: receipt }) : undefined;
+        this.#state = { status: "closed", receipt, error };
+        return this.#state;
+    }
+    async cleanup() {
+        const closed = this.#finalize();
+        if (closed.error) {
+            throw closed.error;
+        }
+        return closed.receipt;
+    }
+    async [Symbol.asyncDispose]() {
+        const cleanup = await this.cleanup();
+        if (cleanup.status === "preserved") {
+            throw new FsSafeError("not-removable", "staged cleanup preserved an unverified entry", {
+                details: { phase: "cleanup", publication: cleanup.publication, cleanup },
+            });
+        }
+    }
+}
+export const createNativeStage = NativeStagedFile.create;
+export const writeNativeStage = NativeStagedFile.write;

package/dist/native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAmKzD,wBAAgB,0BAA0B,IAAI,aAAa,CAE1D;AAED,wBAAgB,8BAA8B,IAAI;IAChD,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC,CAMA;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,UAAQ,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAkB5D;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAQpD;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,aAAa,GAAG,IAAI,CAK1E;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAsKzD,wBAAgB,0BAA0B,IAAI,aAAa,CAE1D;AAED,wBAAgB,8BAA8B,IAAI;IAChD,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,OAAO,GAAG,SAAS,CAAC;IAChC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC,CAMA;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,UAAQ,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAkB5D;AAED,wBAAgB,oBAAoB,IAAI,aAAa,CAQpD;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,aAAa,GAAG,IAAI,CAK1E;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAKjD"}

package/dist/native.js

@@ -1,11 +1,8 @@
 import { closeSync, openSync, readSync, readdirSync, } from "node:fs";
 import { createRequire } from "node:module";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { FsSafeError } from "./errors.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 const require = createRequire(import.meta.url);
-const bundledNativeDirectory = fileURLToPath(new URL("../dist/native/", import.meta.url));
 let binding;
 let loadError;
 let attempted = false;
@@ -139,12 +136,15 @@ function targetFor(platform, arch, musl) {
 function bundledTarget() {
     return targetFor(process.platform, process.arch, isMusl());
 }
+function nativePackageForTarget(target) {
+    return `@openclaw/fs-safe-${target}`;
+}
 function loadBundledBinding() {
     const target = bundledTarget();
     if (!target) {
         throw new Error(`Unsupported OS or architecture: ${process.platform}-${process.arch}`);
     }
-    return require(join(bundledNativeDirectory, target, "fs-safe-native.node"));
+    return require(nativePackageForTarget(target));
 }
 export function __loadBundledNativeForTest() {
     return loadBundledBinding();

package/dist/opened-realpath.d.ts

@@ -1,3 +1,5 @@
 import type { FileHandle } from "node:fs/promises";
+import { type FileIdentityStat } from "./file-identity.js";
 export declare function resolveOpenedFileRealPathForHandle(handle: FileHandle, ioPath: string): Promise<string>;
+export declare function resolveOpenedFileRealPathForFd(fd: number, handleStat: FileIdentityStat, ioPath: string): Promise<string>;
 //# sourceMappingURL=opened-realpath.d.ts.map

package/dist/opened-realpath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opened-realpath.d.ts","sourceRoot":"","sources":["../src/opened-realpath.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAoCjB"}
+{"version":3,"file":"opened-realpath.d.ts","sourceRoot":"","sources":["../src/opened-realpath.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG7E,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,wBAAsB,8BAA8B,CAClD,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAqCjB"}

package/dist/opened-realpath.js

@@ -5,15 +5,20 @@ import { sameFileIdentity } from "./file-identity.js";
 import { isNotFoundPathError } from "./path.js";
 export async function resolveOpenedFileRealPathForHandle(handle, ioPath) {
     const handleStat = await handle.stat();
+    return await resolveOpenedFileRealPathForFd(handle.fd, handleStat, ioPath);
+}
+export async function resolveOpenedFileRealPathForFd(fd, handleStat, ioPath) {
+    const statOptions = typeof handleStat.dev === "bigint" || typeof handleStat.ino === "bigint"
+        ? { bigint: true } : undefined;
     const fdCandidates = process.platform === "linux"
-        ? [`/proc/self/fd/${handle.fd}`, `/dev/fd/${handle.fd}`]
+        ? [`/proc/self/fd/${fd}`, `/dev/fd/${fd}`]
         : process.platform === "win32"
             ? []
-            : [`/dev/fd/${handle.fd}`];
+            : [`/dev/fd/${fd}`];
     for (const fdPath of fdCandidates) {
         try {
             const fdRealPath = await fs.realpath(fdPath);
-            const fdRealStat = await fs.stat(fdRealPath);
+            const fdRealStat = statOptions ? await fs.stat(fdRealPath, statOptions) : await fs.stat(fdRealPath);
             if (sameFileIdentity(handleStat, fdRealStat)) {
                 return fdRealPath;
             }
@@ -24,7 +29,7 @@ export async function resolveOpenedFileRealPathForHandle(handle, ioPath) {
     }
     try {
         const ioRealPath = await fs.realpath(ioPath);
-        const ioRealStat = await fs.stat(ioRealPath);
+        const ioRealStat = statOptions ? await fs.stat(ioRealPath, statOptions) : await fs.stat(ioRealPath);
         if (sameFileIdentity(handleStat, ioRealStat)) {
             return ioRealPath;
         }
@@ -34,13 +39,13 @@ export async function resolveOpenedFileRealPathForHandle(handle, ioPath) {
             throw err;
         }
     }
-    const parentResolved = await resolveOpenedFileRealPathFromParent(handleStat, ioPath);
+    const parentResolved = await resolveOpenedFileRealPathFromParent(handleStat, ioPath, statOptions);
     if (parentResolved) {
         return parentResolved;
     }
     throw new FsSafeError("path-mismatch", "unable to resolve opened file path");
 }
-async function resolveOpenedFileRealPathFromParent(handleStat, ioPath) {
+async function resolveOpenedFileRealPathFromParent(handleStat, ioPath, statOptions) {
     let parentReal;
     try {
         parentReal = await fs.realpath(path.dirname(ioPath));
@@ -64,7 +69,7 @@ async function resolveOpenedFileRealPathFromParent(handleStat, ioPath) {
     for (const entry of entries.toSorted()) {
         const candidatePath = path.join(parentReal, entry);
         try {
-            const candidateStat = await fs.lstat(candidatePath);
+            const candidateStat = statOptions ? await fs.lstat(candidatePath, statOptions) : await fs.lstat(candidatePath);
             if (candidateStat.isFile() && sameFileIdentity(handleStat, candidateStat)) {
                 return await fs.realpath(candidatePath);
             }

package/dist/owner-dacl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner-dacl.d.ts","sourceRoot":"","sources":["../src/owner-dacl.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,yBAAyB,EAAE,CAAC;CACnC,GACD;IACE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B,CAAC;AAEN,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CA4BvE"}
+{"version":3,"file":"owner-dacl.d.ts","sourceRoot":"","sources":["../src/owner-dacl.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAC1B;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,yBAAyB,EAAE,CAAC;CACnC,GACD;IACE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B,CAAC;AAEN,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CA6BvE"}

package/dist/owner-dacl.js

@@ -6,7 +6,8 @@ export function readOwnerAndDacl(targetPath) {
     }
     const native = getNativeBinding();
     if (!native) {
-        throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require the bundled native binding");
+        throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require the matching optional native platform package; " +
+            "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
     }
     const facts = native.readOwnerAndDacl(targetPath);
     return {

package/dist/permission-exec.d.ts

@@ -1,4 +1,23 @@
 export declare const DEFAULT_PERMISSION_EXEC_TIMEOUT_MS = 30000;
+export type PermissionCommandFailure = {
+    command: string;
+    durationMs: number;
+    timedOut: boolean;
+    exitCode: number | null;
+    signal: string | null;
+    stderr: string;
+};
+export declare function formatPermissionErrorDetail(value: string): string;
+export declare class PermissionCommandError extends Error implements PermissionCommandFailure {
+    readonly command: string;
+    readonly durationMs: number;
+    readonly timedOut: boolean;
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stderr: string;
+    constructor(command: string, durationMs: number, cause: unknown, timeoutMs?: number);
+}
+export declare function getPermissionCommandFailure(error: unknown, command: string, durationMs: number): PermissionCommandFailure | undefined;
 export declare function executePermissionCommand(command: string, args: string[], timeoutMs?: number): Promise<{
     stdout: string;
     stderr: string;

package/dist/permission-exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission-exec.d.ts","sourceRoot":"","sources":["../src/permission-exec.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,kCAAkC,QAAS,CAAC;AAEzD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,SAAqC,GAC7C,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB7C"}
+{"version":3,"file":"permission-exec.d.ts","sourceRoot":"","sources":["../src/permission-exec.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,kCAAkC,QAAS,CAAC;AAEzD,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjE;AAgBD,qBAAa,sBAAuB,SAAQ,KAAM,YAAW,wBAAwB;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YACE,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,OAAO,EACd,SAAS,SAAqC,EAc/C;CACF;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,wBAAwB,GAAG,SAAS,CAgBtC;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,SAAqC,GAC7C,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAa7C"}

package/dist/permission-exec.js

@@ -1,8 +1,64 @@
 import { execFile } from "node:child_process";
+import path from "node:path";
 import { promisify } from "node:util";
+import { formatErrorDetail } from "./error-detail.js";
 const execFileAsync = promisify(execFile);
 export const DEFAULT_PERMISSION_EXEC_TIMEOUT_MS = 30_000;
+export function formatPermissionErrorDetail(value) {
+    const formatted = formatErrorDetail(value);
+    return formatted.length > 400 ? `${formatted.slice(0, 399)}…` : formatted;
+}
+function commandFailureFields(error) {
+    const fields = error && typeof error === "object" ? error : {};
+    return {
+        timedOut: "killed" in fields && fields.killed === true &&
+            "signal" in fields && fields.signal === "SIGKILL",
+        exitCode: "code" in fields && typeof fields.code === "number" ? fields.code : null,
+        signal: "signal" in fields && typeof fields.signal === "string" ? fields.signal : null,
+        stderr: formatPermissionErrorDetail("stderr" in fields && (typeof fields.stderr === "string" || Buffer.isBuffer(fields.stderr))
+            ? fields.stderr.toString() : ""),
+    };
+}
+export class PermissionCommandError extends Error {
+    command;
+    durationMs;
+    timedOut;
+    exitCode;
+    signal;
+    stderr;
+    constructor(command, durationMs, cause, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+        const fields = commandFailureFields(cause);
+        super(fields.timedOut
+            ? `Windows permission inspection timed out after ${timeoutMs}ms`
+            : `Windows permission command ${formatPermissionErrorDetail(path.win32.basename(command))} failed (exit code ${fields.exitCode}, signal ${formatPermissionErrorDetail(fields.signal ?? "none")})`, { cause });
+        this.name = "PermissionCommandError";
+        this.command = command;
+        this.durationMs = Math.round(durationMs);
+        this.timedOut = fields.timedOut;
+        this.exitCode = fields.exitCode;
+        this.signal = fields.signal;
+        this.stderr = fields.stderr;
+    }
+}
+export function getPermissionCommandFailure(error, command, durationMs) {
+    if (error instanceof PermissionCommandError) {
+        return {
+            command: error.command,
+            durationMs: error.durationMs,
+            timedOut: error.timedOut,
+            exitCode: error.exitCode,
+            signal: error.signal,
+            stderr: error.stderr,
+        };
+    }
+    if (!error || typeof error !== "object" ||
+        !("code" in error || "signal" in error || "killed" in error || "stderr" in error)) {
+        return undefined;
+    }
+    return { command, durationMs: Math.round(durationMs), ...commandFailureFields(error) };
+}
 export async function executePermissionCommand(command, args, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+    const startedAt = performance.now();
     try {
         return (await execFileAsync(command, args, {
             encoding: "utf8",
@@ -13,16 +69,6 @@ export async function executePermissionCommand(command, args, timeoutMs = DEFAUL
         }));
     }
     catch (err) {
-        if (err &&
-            typeof err === "object" &&
-            "killed" in err &&
-            err.killed === true &&
-            "signal" in err &&
-            err.signal === "SIGKILL") {
-            throw new Error(`Windows permission inspection timed out after ${timeoutMs}ms`, {
-                cause: err,
-            });
-        }
-        throw err;
+        throw new PermissionCommandError(command, performance.now() - startedAt, err, timeoutMs);
     }
 }

package/dist/permissions-public.d.ts

@@ -1,4 +1,4 @@
-export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, type PermissionCheck, type PermissionCheckOptions, type SafeStatResult, } from "./permissions.js";
+export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, type PermissionCheck, type PermissionCheckOptions, type PermissionCommandFailure, type SafeStatResult, } from "./permissions.js";
 export { createPrivateDirectory, type CreatePrivateDirectoryOptions, } from "./private-directory.js";
 export { readOwnerAndDacl, type OwnerAndDaclResult, type WindowsAccessControlEntry, type WindowsAceFlags, } from "./owner-dacl.js";
 //# sourceMappingURL=permissions-public.d.ts.map

package/dist/permissions-public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions-public.d.ts","sourceRoot":"","sources":["../src/permissions-public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,eAAe,EACf,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"permissions-public.d.ts","sourceRoot":"","sources":["../src/permissions-public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,eAAe,EACf,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC"}

package/dist/permissions-windows.d.ts

@@ -1,3 +1,4 @@
+import { type PermissionCommandFailure } from "./permission-exec.js";
 import type { PermissionCheck, PermissionCheckOptions, SafeStatResult } from "./permissions.js";
 export type PermissionExec = (command: string, args: string[]) => Promise<{
     stdout: string;
@@ -19,6 +20,8 @@ export type WindowsAclSummary = {
     untrustedGroup: WindowsAclEntry[];
     trusted: WindowsAclEntry[];
     error?: string;
+    errorDetail?: PermissionCommandFailure;
+    errorCause?: unknown;
 };
 export type WindowsUserInfoProvider = () => {
     username?: string | null;

package/dist/permissions-windows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions-windows.d.ts","sourceRoot":"","sources":["../src/permissions-windows.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"permissions-windows.d.ts","sourceRoot":"","sources":["../src/permissions-windows.ts"],"names":[],"mappings":"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"}