@openclaw/matrix 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/dist/file-store.js

@@ -0,0 +1,360 @@
+import syncFs from "node:fs";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { readFileDescriptorBoundedSync } from "./bounded-read.js";
+import { FsSafeError } from "./errors.js";
+import { pruneExpiredStoreEntries } from "./file-store-prune.js";
+import { assertFileStoreMaxBytes, assertRelativePath, ensureParentInRoot, literalStoreRootPath, openPrivateStoreLockRoot, openWritableStoreRoot, readFileStoreCopySource, resolveStorePath, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { writeFileSyncAtomic } from "./file-store-sync-write.js";
+import { createJsonStore } from "./json-document-store.js";
+import { stringifyJsonDocument } from "./json-stringify.js";
+import { isNotFoundPathError } from "./path.js";
+import { throwFsSafeReadError } from "./root-errors.js";
+import { root } from "./root.js";
+import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
+import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
+import { writeSecretFileAtomic } from "./secret-file.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function snapshotWriteOptions(options, durabilityFirst = true) {
+    if (options == null)
+        return undefined;
+    return durabilityFirst ? {
+        maxBytes: options.maxBytes,
+        durable: options.durable,
+        dirMode: options.dirMode,
+        mode: options.mode,
+    } : {
+        maxBytes: options.maxBytes,
+        dirMode: options.dirMode,
+        mode: options.mode,
+        durable: options.durable,
+    };
+}
+function isNotFound(error) {
+    return error instanceof FsSafeError ? error.code === "not-found" : isNotFoundPathError(error);
+}
+function handleSyncStoreReadOpenFailure(opened) {
+    return matchRootFileOpenFailure(opened, {
+        path: (failure) => {
+            if (isNotFound(failure.error)) {
+                return null;
+            }
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        validation: (failure) => {
+            if (failure.error instanceof FsSafeError) {
+                throw failure.error;
+            }
+            // Validation failures mean the path existed but violated store policy
+            // (directory, hardlink, symlink race). Do not report them as missing.
+            throw new FsSafeError("path-mismatch", "store target failed read validation", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        io: (failure) => throwFsSafeReadError(failure.error, "store"),
+        fallback: (failure) => {
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+    });
+}
+async function copyIntoRoot(params) {
+    const relativePath = params.relativePath;
+    const destination = resolveStorePath(params.rootDir, relativePath);
+    assertNoWindowsPathAlias(params.sourcePath, "filesystem", "source path uses a Windows filesystem namespace alias");
+    const sourceStat = syncFs.lstatSync(params.sourcePath);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new FsSafeError("not-file", "source path is not a file");
+    }
+    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
+    const scopedRoot = await openWritableStoreRoot({
+        rootDir: params.rootDir,
+        dirMode: params.dirMode,
+        maxBytes: params.maxBytes,
+    });
+    await ensureParentInRoot(scopedRoot, relativePath, params.dirMode);
+    await scopedRoot.copyIn(literalStoreRootPath(relativePath), params.sourcePath, {
+        durable: params.durable,
+        maxBytes: params.maxBytes,
+        mkdir: false,
+        mode: params.mode,
+    });
+    return destination;
+}
+export function fileStore(options) {
+    const rootDirInput = options.rootDir;
+    assertNoWindowsPathAlias(rootDirInput, "filesystem", "store root uses a Windows filesystem namespace alias");
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+    assertNoWindowsPathAlias(rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
+    const privateMode = options.private ?? false;
+    const dirMode = options.dirMode ?? 0o700;
+    const mode = options.mode ?? 0o600;
+    const durable = options.durable ?? true;
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    async function openRoot() {
+        return await root(rootDir, { hardlinks: "reject", maxBytes });
+    }
+    async function write(relativePath, data, writeOptions) {
+        const destination = resolveStorePath(rootDir, relativePath);
+        const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+        assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
+        if (privateMode) {
+            await writeSecretFileAtomic({
+                rootDir,
+                filePath: destination,
+                content,
+                durable: writeOptions?.durable ?? durable,
+                dirMode: writeOptions?.dirMode ?? dirMode,
+                mode: writeOptions?.mode ?? mode,
+            });
+            return destination;
+        }
+        const writeDirMode = writeOptions?.dirMode ?? dirMode;
+        const writeMode = writeOptions?.mode ?? mode;
+        const writeDurable = writeOptions?.durable ?? durable;
+        const scopedRoot = await openWritableStoreRoot({
+            rootDir,
+            dirMode: writeDirMode,
+            maxBytes: writeMaxBytes,
+        });
+        await ensureParentInRoot(scopedRoot, relativePath, writeDirMode);
+        await scopedRoot.write(literalStoreRootPath(relativePath), content, {
+            mkdir: false,
+            mode: writeMode,
+            durable: writeDurable,
+        });
+        return destination;
+    }
+    return {
+        rootDir,
+        path: (relativePath) => resolveStorePath(rootDir, relativePath),
+        root: openRoot,
+        write,
+        writeStream: async (relativePath, stream, writeOptions) => {
+            const destination = resolveStorePath(rootDir, relativePath);
+            const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+            const limit = configuredLimit ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
+            if (privateMode) {
+                const writeDurable = writeOptions?.durable ?? durable;
+                const writeDirMode = writeOptions?.dirMode ?? dirMode;
+                const writeMode = writeOptions?.mode ?? mode;
+                const chunks = [];
+                let total = 0;
+                for await (const chunk of stream) {
+                    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+                    total += buffer.byteLength;
+                    assertFileStoreMaxBytes(total, limit);
+                    chunks.push(buffer);
+                }
+                await writeSecretFileAtomic({
+                    rootDir,
+                    filePath: destination,
+                    content: Buffer.concat(chunks),
+                    durable: writeDurable,
+                    dirMode: writeDirMode,
+                    mode: writeMode,
+                });
+                return destination;
+            }
+            const writeMode = writeOptions?.mode ?? mode;
+            const writeDurable = writeOptions?.durable ?? durable;
+            const writeDirMode = writeOptions?.dirMode ?? dirMode;
+            const staged = await writeStreamToTempSource({
+                stream,
+                maxBytes: limit,
+                mode: writeMode,
+            });
+            try {
+                await copyIntoRoot({
+                    rootDir,
+                    relativePath,
+                    sourcePath: staged.path,
+                    durable: writeDurable,
+                    maxBytes: limit,
+                    mode: writeMode,
+                    tempPrefix: writeOptions?.tempPrefix,
+                    dirMode: writeDirMode,
+                });
+            }
+            finally {
+                await staged.cleanup();
+            }
+            return destination;
+        },
+        copyIn: async (relativePath, sourcePath, writeOptions) => {
+            const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+            if (privateMode) {
+                const policy = writeOptions == null
+                    ? undefined
+                    : {
+                        maxBytes: configuredLimit,
+                        durable: writeOptions?.durable,
+                        dirMode: writeOptions?.dirMode,
+                        mode: writeOptions?.mode,
+                    };
+                const buffer = await readFileStoreCopySource({
+                    sourcePath,
+                    maxBytes: configuredLimit ?? DEFAULT_ROOT_MAX_BYTES,
+                });
+                return await write(relativePath, buffer, policy);
+            }
+            return await copyIntoRoot({
+                rootDir,
+                relativePath,
+                sourcePath,
+                durable: writeOptions?.durable ?? durable,
+                dirMode: writeOptions?.dirMode ?? dirMode,
+                maxBytes: configuredLimit,
+                mode: writeOptions?.mode ?? mode,
+                tempPrefix: writeOptions?.tempPrefix,
+            });
+        },
+        open: async (relativePath, readOptions) => await (await openRoot()).open(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
+        read: async (relativePath, readOptions) => await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
+        readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(literalStoreRootPath(assertRelativePath(relativePath)), readOptions),
+        readText: async (relativePath, readOptions) => {
+            const { encoding = "utf8", ...options } = readOptions ?? {};
+            return (await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), options)).buffer
+                .toString(encoding);
+        },
+        readTextIfExists: async (relativePath, readOptions) => {
+            try {
+                return await (await openRoot()).readText(literalStoreRootPath(assertRelativePath(relativePath)), readOptions);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throwFsSafeReadError(error, "store");
+            }
+        },
+        readJson: async (relativePath, readOptions) => {
+            const { encoding = "utf8", ...options } = readOptions ?? {};
+            return JSON.parse((await (await openRoot()).read(literalStoreRootPath(assertRelativePath(relativePath)), options)).buffer
+                .toString(encoding));
+        },
+        readJsonIfExists: async (relativePath, readOptions) => {
+            try {
+                return await (await openRoot()).readJson(literalStoreRootPath(assertRelativePath(relativePath)), readOptions);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throwFsSafeReadError(error, "store");
+            }
+        },
+        remove: async (relativePath) => {
+            await (await openRoot()).remove(literalStoreRootPath(assertRelativePath(relativePath)));
+        },
+        exists: async (relativePath) => await (await openRoot()).exists(literalStoreRootPath(assertRelativePath(relativePath))),
+        writeText: async (relativePath, data, writeOptions) => await write(relativePath, data, writeOptions),
+        writeJson: async (relativePath, data, writeOptions) => {
+            const trailingNewline = writeOptions?.trailingNewline;
+            const policy = snapshotWriteOptions(writeOptions, privateMode);
+            const json = stringifyJsonDocument(data, null, 2);
+            return await write(relativePath, trailingNewline === false ? json : `${json}\n`, policy);
+        },
+        json: (relativePath, jsonOptions) => {
+            const filePath = resolveStorePath(rootDir, relativePath);
+            return createJsonStore({
+                filePath,
+                ...(privateMode ? {
+                    prepareLock: () => openPrivateStoreLockRoot({ rootDir, filePath, mode, dirMode }),
+                } : {}),
+                readIfExists: async () => {
+                    try {
+                        return await (await openRoot()).readJson(literalStoreRootPath(relativePath));
+                    }
+                    catch (error) {
+                        if (isNotFound(error)) {
+                            return undefined;
+                        }
+                        throw error;
+                    }
+                },
+                readRequired: async () => await (await openRoot()).readJson(literalStoreRootPath(relativePath)),
+                write: async (value, options) => {
+                    const json = stringifyJsonDocument(value, null, 2);
+                    await write(relativePath, options?.trailingNewline === false ? json : `${json}\n`, { durable: options?.durable });
+                },
+            }, jsonOptions);
+        },
+        pruneExpired: async (pruneOptions) => {
+            await pruneExpiredStoreEntries({ rootDir, dirMode, options: pruneOptions });
+        },
+    };
+}
+export function fileStoreSync(options) {
+    const rootDirInput = options.rootDir;
+    assertNoWindowsPathAlias(rootDirInput, "filesystem", "store root uses a Windows filesystem namespace alias");
+    const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+    assertNoWindowsPathAlias(rootDir, "filesystem", "store root uses a Windows filesystem namespace alias");
+    const privateMode = options.private ?? false;
+    const dirMode = options.dirMode ?? 0o700;
+    const mode = options.mode ?? 0o600;
+    const durable = options.durable ?? true;
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    function write(relativePath, data, writeOptions) {
+        const destination = resolveStorePath(rootDir, relativePath);
+        const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+        assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
+        return writeFileSyncAtomic({
+            rootDir,
+            filePath: destination,
+            content,
+            privateMode,
+            durable: writeOptions?.durable ?? durable,
+            dirMode: writeOptions?.dirMode ?? dirMode,
+            mode: writeOptions?.mode ?? mode,
+        });
+    }
+    let readTextIfExists;
+    return {
+        rootDir,
+        path: (relativePath) => resolveStorePath(rootDir, relativePath),
+        readTextIfExists: readTextIfExists = (relativePath, readOptions) => {
+            const limit = normalizeMaxBytes(readOptions?.maxBytes, { defaultValue: maxBytes });
+            const targetPath = resolveStorePath(rootDir, relativePath);
+            const opened = openRootFileSync({
+                absolutePath: targetPath,
+                rootPath: rootDir,
+                boundaryLabel: "store root",
+                rejectHardlinks: true,
+            });
+            if (!opened.ok) {
+                return handleSyncStoreReadOpenFailure(opened);
+            }
+            try {
+                assertFileStoreMaxBytes(opened.stat.size, limit);
+                try {
+                    return limit === undefined
+                        ? syncFs.readFileSync(opened.fd, "utf8")
+                        : readFileDescriptorBoundedSync(opened.fd, limit).toString("utf8");
+                }
+                catch (error) {
+                    throwFsSafeReadError(error, "store");
+                }
+            }
+            finally {
+                syncFs.closeSync(opened.fd);
+            }
+        },
+        readJsonIfExists: (relativePath, readOptions) => {
+            const raw = readTextIfExists(relativePath, readOptions);
+            return raw === null ? null : JSON.parse(raw);
+        },
+        write,
+        writeText: (relativePath, data, writeOptions) => write(relativePath, data, writeOptions),
+        writeJson: (relativePath, data, writeOptions) => {
+            const trailingNewline = writeOptions?.trailingNewline;
+            const policy = snapshotWriteOptions(writeOptions);
+            const json = stringifyJsonDocument(data, null, 2);
+            return write(relativePath, trailingNewline === false ? json : `${json}\n`, policy);
+        },
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/file-sync.d.ts

@@ -0,0 +1,4 @@
+import fs from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export declare function syncFileBestEffort(handle: Pick<FileHandle, "sync">): Promise<void>;
+export declare function syncFileBestEffortSync(fd: number, fsModule?: Pick<typeof fs, "fsyncSync">): void;

package/node_modules/@openclaw/fs-safe/dist/file-sync.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+export async function syncFileBestEffort(handle) {
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        if (error?.code !== "EPERM")
+            throw error;
+    }
+}
+export function syncFileBestEffortSync(fd, fsModule = fs) {
+    try {
+        fsModule.fsyncSync(fd);
+    }
+    catch (error) {
+        if (error?.code !== "EPERM")
+            throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/filename.d.ts

@@ -0,0 +1,8 @@
+export declare function suffixWindowsReservedDeviceName(fileName: string): string;
+/** Keeps short names exact and trims only the filename tail of a composite temp name. */
+export declare function fitFileNameToPortableComponent(params: {
+    prefix: string;
+    fileName: string;
+    suffix: string;
+}): string;
+export declare function sanitizeUntrustedFileName(fileName: string, fallbackName: string): string;

package/node_modules/@openclaw/fs-safe/dist/filename.js

@@ -0,0 +1,138 @@
+import path from "node:path";
+import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
+import { maxNormalizedUtf8Bytes } from "./unicode-path.js";
+import { hasWindowsDrivePrefix } from "./windows-path-syntax.js";
+const INVALID_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/g;
+const HAS_INVALID_FILE_NAME_CHARACTER = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/;
+const HAS_RETAINED_FILE_NAME_CHARACTER = /[^\u0000-\u001f\u007f-\u009f<>:"/\\|?*\s]/;
+function canStartWindowsDeviceName(character) {
+    const folded = character | 0x20;
+    return folded === 0x61 || folded === 0x63 || folded === 0x6c ||
+        folded === 0x6e || folded === 0x70;
+}
+function windowsDeviceStemEnd(value, stemEnd) {
+    let end = stemEnd;
+    while (end > 0) {
+        const character = value.charCodeAt(end - 1);
+        if (character !== 0x20 && character !== 0x2e) {
+            break;
+        }
+        end -= 1;
+    }
+    return end;
+}
+export function suffixWindowsReservedDeviceName(fileName) {
+    if (!canStartWindowsDeviceName(fileName.charCodeAt(0))) {
+        return fileName;
+    }
+    const extensionIndex = fileName.indexOf(".");
+    const baseNameEnd = extensionIndex < 0 ? fileName.length : extensionIndex;
+    const deviceBaseNameEnd = windowsDeviceStemEnd(fileName, baseNameEnd);
+    if (deviceBaseNameEnd === 0 ||
+        deviceBaseNameEnd > 7 ||
+        !WINDOWS_RESERVED_DEVICE_NAMES.has(fileName.slice(0, deviceBaseNameEnd).toUpperCase())) {
+        return fileName;
+    }
+    return `${fileName.slice(0, baseNameEnd)}_${fileName.slice(baseNameEnd)}`;
+}
+const PORTABLE_FILE_NAME_BYTES = 255;
+const SANITIZED_FILE_NAME_CODE_UNITS = 200;
+const SAFE_FALLBACK_FILE_NAME = "file";
+/**
+ * Uses native string and regexp operations to recognize the full sanitizer's
+ * bounded fixed points. The separate non-global regexp keeps this predicate
+ * stateless, and the authoritative device-name transform remains the final
+ * admission check.
+ */
+function isBoundedSanitizedFileName(fileName, trimmedFileName) {
+    return typeof fileName === "string" &&
+        fileName.length > 0 &&
+        fileName.length <= SANITIZED_FILE_NAME_CODE_UNITS &&
+        fileName !== "." &&
+        fileName !== ".." &&
+        trimmedFileName === fileName &&
+        !HAS_INVALID_FILE_NAME_CHARACTER.test(fileName) &&
+        suffixWindowsReservedDeviceName(fileName) === fileName;
+}
+function normalizedFileNameBytes(value) {
+    return maxNormalizedUtf8Bytes(value, true);
+}
+function truncateCodeUnitsWithoutSplittingSurrogate(value, limit) {
+    if (value.length <= limit)
+        return value;
+    let truncated = value.slice(0, limit);
+    const trailingCodeUnit = truncated.charCodeAt(truncated.length - 1);
+    if (trailingCodeUnit >= 0xd800 && trailingCodeUnit <= 0xdbff) {
+        truncated = truncated.slice(0, -1);
+    }
+    return truncated;
+}
+/** Keeps short names exact and trims only the filename tail of a composite temp name. */
+export function fitFileNameToPortableComponent(params) {
+    const complete = `${params.prefix}${params.fileName}${params.suffix}`;
+    if (normalizedFileNameBytes(complete) <= PORTABLE_FILE_NAME_BYTES) {
+        return params.fileName;
+    }
+    if (normalizedFileNameBytes(`${params.prefix}${params.suffix}`) > PORTABLE_FILE_NAME_BYTES) {
+        // Preserve the existing OS error for a caller-supplied prefix that cannot fit.
+        return params.fileName;
+    }
+    const extension = path.extname(params.fileName);
+    const preserveExtension = normalizedFileNameBytes(`${params.prefix}${extension}${params.suffix}`) <=
+        PORTABLE_FILE_NAME_BYTES;
+    const tailSuffix = preserveExtension ? extension : "";
+    const stem = preserveExtension
+        ? params.fileName.slice(0, params.fileName.length - extension.length)
+        : params.fileName;
+    const codePoints = Array.from(stem);
+    let low = 0;
+    let high = codePoints.length;
+    while (low < high) {
+        const length = Math.ceil((low + high) / 2);
+        const candidate = `${params.prefix}${codePoints.slice(0, length).join("")}${tailSuffix}${params.suffix}`;
+        if (normalizedFileNameBytes(candidate) <= PORTABLE_FILE_NAME_BYTES) {
+            low = length;
+        }
+        else {
+            high = length - 1;
+        }
+    }
+    return `${codePoints.slice(0, low).join("")}${tailSuffix}`;
+}
+function sanitizeFileNameCandidate(fileName) {
+    if (typeof fileName !== "string")
+        return undefined;
+    const trimmed = fileName.trim();
+    if (!trimmed)
+        return undefined;
+    if (isBoundedSanitizedFileName(fileName, trimmed))
+        return fileName;
+    // Basename selection cannot manufacture a character, and the complete
+    // sanitizer removes this same invalid set before its final trim.
+    if (!HAS_RETAINED_FILE_NAME_CHARACTER.test(trimmed))
+        return undefined;
+    let base = trimmed;
+    if (base.includes("/"))
+        base = path.posix.basename(base);
+    if (base.includes("\\") || hasWindowsDrivePrefix(base)) {
+        base = path.win32.basename(base);
+    }
+    base = base.replace(INVALID_FILE_NAME_CHARACTERS, "").trim();
+    if (!base || base === "." || base === "..") {
+        return undefined;
+    }
+    base = truncateCodeUnitsWithoutSplittingSurrogate(base, SANITIZED_FILE_NAME_CODE_UNITS);
+    let safeBase = suffixWindowsReservedDeviceName(base);
+    if (safeBase.length > SANITIZED_FILE_NAME_CODE_UNITS) {
+        // The safety suffix is the final invariant. Shorten the unsuffixed tail so
+        // truncation cannot turn a padded reserved stem back into a device name.
+        base = truncateCodeUnitsWithoutSplittingSurrogate(base, SANITIZED_FILE_NAME_CODE_UNITS - 1);
+        safeBase = suffixWindowsReservedDeviceName(base);
+    }
+    return safeBase;
+}
+export function sanitizeUntrustedFileName(fileName, fallbackName) {
+    return (sanitizeFileNameCandidate(fileName) ??
+        sanitizeFileNameCandidate(fallbackName) ??
+        SAFE_FALLBACK_FILE_NAME);
+}

package/node_modules/@openclaw/fs-safe/dist/fs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns true when `fs.stat()` can stat the path.
+ *
+ * This follows stat semantics: broken symlinks return false, while symlinks to
+ * existing targets return true.
+ */
+export declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Synchronous counterpart to `pathExists()`, with the same `fs.statSync()`
+ * semantics.
+ */
+export declare function pathExistsSync(filePath: string): boolean;

package/node_modules/@openclaw/fs-safe/dist/fs.js

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import { pathForWindowsFilesystem } from "./windows-path-alias.js";
+/**
+ * Returns true when `fs.stat()` can stat the path.
+ *
+ * This follows stat semantics: broken symlinks return false, while symlinks to
+ * existing targets return true.
+ */
+export async function pathExists(filePath) {
+    try {
+        fs.statSync(pathForWindowsFilesystem(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Synchronous counterpart to `pathExists()`, with the same `fs.statSync()`
+ * semantics.
+ */
+export function pathExistsSync(filePath) {
+    try {
+        fs.statSync(pathForWindowsFilesystem(filePath));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/guarded-mkdir.d.ts

@@ -0,0 +1,25 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write-types.js";
+/**
+ * Creates each missing path component from `rootReal` down to `targetPath`,
+ * guarding every step. Returns the real (symlink-resolved) path of the final
+ * component so callers can guard/use that path directly instead of
+ * re-deriving it from the original, possibly-symlinked, lexical path.
+ */
+export declare function mkdirPathComponentsWithGuards(params: {
+    rootReal: string;
+    targetPath: string;
+    beforeComponent?: (componentPath: string) => Promise<void> | void;
+    beforeCreateComponent?: (componentPath: string, prospectiveTargetPath: string, retainedTargetPath: string | undefined, parent: MutationDirectoryObservation) => Promise<PinnedMutationAdmissionReceipt | undefined> | PinnedMutationAdmissionReceipt | undefined;
+    beforeUseComponent?: (componentPath: string, prospectiveTargetPath: string, retainedTargetPath: string | undefined) => Promise<void> | void;
+    afterCreateComponent?: (receipt: PinnedCreatedDirectoryReceipt) => PinnedMutationAuthorizationToken | undefined;
+    assertBeforeMutation?: () => void;
+    mode?: number;
+    private?: boolean;
+    rejectSymlinks?: boolean;
+    revalidateParentAfterBeforeComponent?: boolean;
+    synchronousAuthorizationIncludesFence?: boolean;
+    retainedTargetPath?: string;
+    rootIdentity?: RootBoundaryIdentity;
+}): Promise<string>;