@openclaw/matrix 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,102 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { openedPathResolutionError } from "./opened-file-failure.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+export async function resolveOpenedFileRealPathForHandle(handle, ioPath) {
+    const fd = handle.fd;
+    const identity = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }));
+    const resolved = await resolveOpenedFileRealPathForFd(fd, identity, ioPath);
+    let first = resolved.stat;
+    inspectFileIdentitySync(() => {
+        const current = first ?? fsSync.statSync(resolved.realPath, { bigint: true });
+        first = undefined;
+        return current;
+    }, identity);
+    return resolved.realPath;
+}
+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/${fd}`, `/dev/fd/${fd}`]
+        : [];
+    for (const fdPath of fdCandidates) {
+        try {
+            const fdRealPath = realpathSync.native(fdPath);
+            const fdRealStat = statOptions ? fsSync.statSync(fdRealPath, statOptions) : fsSync.statSync(fdRealPath);
+            if (sameFileIdentity(handleStat, fdRealStat)) {
+                return { realPath: fdRealPath, stat: fdRealStat };
+            }
+        }
+        catch {
+            // try next fd path
+        }
+    }
+    try {
+        const ioRealPath = realpathSync.native(ioPath);
+        const ioRealStat = statOptions ? fsSync.statSync(ioRealPath, statOptions) : fsSync.statSync(ioRealPath);
+        if (sameFileIdentity(handleStat, ioRealStat)) {
+            return { realPath: ioRealPath, stat: ioRealStat };
+        }
+    }
+    catch (err) {
+        if (!isNotFoundPathError(err)) {
+            // Windows can fail here on a deleted-but-open file. Brand only this
+            // resolver operation; the caller must still prove unlink on the same fd.
+            if (process.platform === "win32" && err instanceof Error &&
+                ["EPERM", "EBADF"].includes(err.code ?? "")) {
+                throw openedPathResolutionError(err);
+            }
+            throw err;
+        }
+    }
+    const parentResolved = await resolveOpenedFileRealPathFromParent(handleStat, ioPath, statOptions);
+    if (parentResolved) {
+        return parentResolved;
+    }
+    throw openedPathResolutionError();
+}
+async function resolveOpenedFileRealPathFromParent(handleStat, ioPath, statOptions) {
+    let parentReal;
+    try {
+        parentReal = realpathSync.native(path.dirname(ioPath));
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return null;
+        }
+        throw err;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(parentReal);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return null;
+        }
+        throw err;
+    }
+    for (const entry of entries.toSorted()) {
+        const candidatePath = path.join(parentReal, entry);
+        try {
+            const candidateStat = statOptions ? fsSync.lstatSync(candidatePath, statOptions) : fsSync.lstatSync(candidatePath);
+            if (candidateStat.isFile() && sameFileIdentity(handleStat, candidateStat)) {
+                const realPath = realpathSync.native(candidatePath);
+                const stat = statOptions ? fsSync.statSync(realPath, statOptions) : fsSync.statSync(realPath);
+                if (sameFileIdentity(handleStat, stat))
+                    return { realPath, stat };
+            }
+        }
+        catch (err) {
+            if (!isNotFoundPathError(err)) {
+                throw err;
+            }
+        }
+    }
+    return null;
+}

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

@@ -0,0 +1,16 @@
+export type ExternalFileWriteOptions<T = void> = {
+    rootDir: string;
+    path: string;
+    write: (filePath: string) => Promise<T>;
+    maxBytes?: number;
+    mode?: number;
+    staging?: "workspace" | "sibling";
+    /** Isolate sibling producers; workspace staging is already private. */
+    producerIsolation?: "private-directory";
+    fallbackFileName?: string;
+};
+export type ExternalFileWriteResult<T = void> = {
+    path: string;
+    result: T;
+};
+export declare function writeExternalFileWithinRoot<T = void>(options: ExternalFileWriteOptions<T>): Promise<ExternalFileWriteResult<T>>;

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

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import { writeCallbackSibling } from "./sibling-staged-file.js";
+import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { fitFileNameToPortableComponent, sanitizeUntrustedFileName } from "./filename.js";
+import { isPathInside } from "./path.js";
+import { root } from "./root.js";
+import { tempFile } from "./temp-target.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+const NON_PORTABLE_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/u;
+function tempFileNameForTarget(targetPath, fallbackFileName) {
+    const fallback = sanitizeUntrustedFileName(fallbackFileName ?? "output.bin", "output.bin");
+    return sanitizeUntrustedFileName(path.basename(targetPath), fallback);
+}
+function sanitizedTargetPath(targetPath, fallbackFileName) {
+    const basename = path.basename(targetPath);
+    if (!NON_PORTABLE_FILE_NAME_CHARACTERS.test(basename)) {
+        return targetPath;
+    }
+    const sanitized = tempFileNameForTarget(targetPath, fallbackFileName);
+    return sanitized === basename ? targetPath : path.join(path.dirname(targetPath), sanitized);
+}
+function ensureTrailingSep(value) {
+    return value.endsWith(path.sep) ? value : `${value}${path.sep}`;
+}
+function toRootPathInput(params) {
+    if (!path.isAbsolute(params.targetPath)) {
+        return params.targetPath;
+    }
+    const absoluteTarget = path.resolve(params.targetPath);
+    const rootDir = path.resolve(params.rootDir);
+    if (isPathInside(ensureTrailingSep(rootDir), absoluteTarget)) {
+        return path.relative(rootDir, absoluteTarget);
+    }
+    if (isPathInside(ensureTrailingSep(params.rootReal), absoluteTarget)) {
+        return path.relative(params.rootReal, absoluteTarget);
+    }
+    return params.targetPath;
+}
+function assertFileTargetPath(targetPath) {
+    const basename = path.basename(targetPath);
+    if (!targetPath ||
+        targetPath === "." ||
+        targetPath.endsWith("/") ||
+        targetPath.endsWith("\\") ||
+        !basename ||
+        basename === "." ||
+        basename === "..") {
+        throw new FsSafeError("invalid-path", "target path must name a file");
+    }
+}
+export async function writeExternalFileWithinRoot(options) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const rootDir = options.rootDir;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "output root uses a Windows filesystem namespace alias");
+    const requestedTargetPath = options.path;
+    assertNoWindowsPathAlias(path.dirname(requestedTargetPath), "filesystem", "output target parent uses a Windows filesystem namespace alias");
+    const producerIsolation = options.producerIsolation;
+    const write = options.write;
+    const mode = options.mode;
+    const staging = options.staging;
+    const fallbackFileName = options.fallbackFileName;
+    const targetRoot = await root(rootDir);
+    if (requestedTargetPath.length === 0) {
+        throw new FsSafeError("invalid-path", "target path is required");
+    }
+    assertFileTargetPath(requestedTargetPath);
+    const rawTargetPath = toRootPathInput({
+        rootDir: targetRoot.rootDir,
+        rootReal: targetRoot.rootReal,
+        targetPath: requestedTargetPath,
+    });
+    assertFileTargetPath(rawTargetPath);
+    const targetPath = sanitizedTargetPath(rawTargetPath, fallbackFileName);
+    assertNoWindowsPathAlias(targetPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    const finalPath = await targetRoot.resolve(targetPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    if (staging === "sibling") {
+        const parentPath = path.dirname(targetPath);
+        if (parentPath !== ".") {
+            await targetRoot.mkdir(parentPath);
+        }
+        const siblingFinalPath = await targetRoot.resolve(targetPath);
+        const result = await writeExternalFileViaSibling({
+            finalPath: siblingFinalPath,
+            write,
+            producerIsolation,
+            fallbackFileName,
+            maxBytes,
+            mode,
+        });
+        return { path: siblingFinalPath, result };
+    }
+    const staged = await tempFile({
+        prefix: "fs-safe-output",
+        fileName: tempFileNameForTarget(targetPath, fallbackFileName),
+    });
+    try {
+        const result = await Function.prototype.call.call(write, options, staged.path);
+        await targetRoot.copyIn(targetPath, staged.path, {
+            maxBytes,
+            mode,
+            mkdir: true,
+            sourceHardlinks: "reject",
+        });
+        return { path: finalPath, result };
+    }
+    finally {
+        await staged.cleanup();
+    }
+}
+function buildSiblingTempName(targetPath, fallbackFileName) {
+    const prefix = `.fs-safe-output-${process.pid}-${randomUUID()}-`;
+    const suffix = ".part";
+    const safeTail = fitFileNameToPortableComponent({
+        prefix,
+        fileName: tempFileNameForTarget(targetPath, fallbackFileName),
+        suffix,
+    });
+    return `${prefix}${safeTail}${suffix}`;
+}
+async function writeExternalFileViaSibling(params) {
+    assertNoWindowsPathAlias(params.finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    const finalPath = path.resolve(params.finalPath);
+    assertNoWindowsPathAlias(finalPath, "filesystem", "output target uses a Windows filesystem namespace alias");
+    const { result } = await writeCallbackSibling({
+        tempDir: path.dirname(finalPath),
+        tempName: buildSiblingTempName(finalPath, params.fallbackFileName),
+        write: params.write,
+        producerIsolation: params.producerIsolation,
+        resolveFinalPath: () => finalPath,
+        mode: params.mode,
+        maxBytes: params.maxBytes,
+        syncTempFile: true,
+        syncParentDir: true,
+    });
+    return result;
+}

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

@@ -0,0 +1,7 @@
+import type { FileHandle } from "node:fs/promises";
+export type OverwriteFileHandleOptions = {
+    /** Admit the whole write once, after rollback preparation and before any mutation. */
+    beforeWrite?: () => void;
+};
+/** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
+export declare function overwriteFileHandle(handle: FileHandle, data: Uint8Array, options?: OverwriteFileHandleOptions): Promise<void>;

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

@@ -0,0 +1,46 @@
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { readFileWindowFully } from "./positional-read.js";
+import { writeAllToFile } from "./write-file-handle.js";
+/** Overwrite a borrowed, non-append read/write handle with best-effort failure rollback. */
+export async function overwriteFileHandle(handle, data, options = {}) {
+    // Snapshot caller-owned admission before the first await. Preserve the
+    // former method-call receiver while preventing a later getter mutation from
+    // replacing authority after rollback preparation.
+    const beforeWrite = options.beforeWrite;
+    const payload = data.subarray(0, data.byteLength);
+    const payloadBytes = payload.byteLength;
+    const stat = await handle.stat();
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "overwrite handle must be a regular file");
+    }
+    const originalSize = stat.size;
+    if (!Number.isSafeInteger(originalSize) || originalSize < 0) {
+        throw new RangeError("file size must be a non-negative safe integer");
+    }
+    const prefixBytes = Math.min(payloadBytes, originalSize);
+    const originalPrefix = Buffer.allocUnsafe(prefixBytes);
+    if (await readFileWindowFully(handle, originalPrefix, 0) !== prefixBytes) {
+        throw new FsSafeError("read-failed", "file ended before overwrite rollback preparation completed");
+    }
+    assertSynchronousCallbackResult(beforeWrite === undefined ? undefined : Reflect.apply(beforeWrite, options, []), "beforeWrite");
+    let prefixStarted = false;
+    try {
+        // Leave existing bytes intact until any additional storage has been written.
+        if (payloadBytes > originalSize) {
+            await writeAllToFile(handle, payload.subarray(originalSize), { position: originalSize });
+        }
+        prefixStarted = true;
+        await writeAllToFile(handle, payload.subarray(0, prefixBytes), { position: 0 });
+        if (payloadBytes < originalSize) {
+            await handle.truncate(payloadBytes);
+        }
+    }
+    catch (error) {
+        if (prefixStarted) {
+            await writeAllToFile(handle, originalPrefix, { position: 0 }).catch(() => undefined);
+        }
+        await handle.truncate(originalSize).catch(() => undefined);
+        throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/owner-dacl-batch-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/node_modules/@openclaw/fs-safe/dist/owner-dacl-batch-worker.js

@@ -0,0 +1,54 @@
+// One isolated process owns every native query in a batch, including stuck OS calls.
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { configureFsSafeNative } from "./native-config.js";
+import { formatCaughtPermissionFailure } from "./permission-exec.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+const MAX_INPUT_BYTES = 16 * 1024 * 1024;
+async function inspectBatch() {
+    const mode = process.env.FS_SAFE_OWNER_DACL_BATCH_MODE;
+    if (mode !== "auto" && mode !== "require") {
+        throw new FsSafeError("helper-unavailable", "isolated Windows native inspection was not enabled");
+    }
+    configureFsSafeNative({ mode });
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.byteLength;
+        if (bytes > MAX_INPUT_BYTES)
+            throw new Error("Windows security batch exceeded its input budget");
+        chunks.push(buffer);
+    }
+    const paths = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+    if (!Array.isArray(paths) || !paths.every(value => typeof value === "string" && value && !value.includes("\0"))) {
+        throw new Error("Windows security batch contains invalid paths");
+    }
+    for (const pathname of paths)
+        assertNoWindowsPathAlias(pathname);
+    const binding = getNativeBinding();
+    const inspect = binding?.readOwnerAndDacl;
+    if (!binding || typeof inspect !== "function") {
+        throw new FsSafeError("helper-unavailable", "isolated Windows native inspection is unavailable");
+    }
+    const result = [];
+    let outputBytes = Buffer.byteLength(JSON.stringify({ ok: true, result: [] }));
+    for (const pathname of paths) {
+        const row = { path: pathname, security: inspect.call(binding, pathname) };
+        outputBytes += Buffer.byteLength(JSON.stringify(row)) + (result.length ? 1 : 0);
+        if (outputBytes > MAX_INPUT_BYTES) {
+            throw new FsSafeError("too-large", "Windows security batch exceeded its output budget");
+        }
+        result.push(row);
+    }
+    return result;
+}
+try {
+    const result = await inspectBatch();
+    process.stdout.write(JSON.stringify({ ok: true, result }));
+}
+catch (error) {
+    const code = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code : "EIO";
+    process.stdout.write(JSON.stringify({ ok: false, code, message: formatCaughtPermissionFailure(error) }));
+}

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

@@ -0,0 +1,5 @@
+import { type OwnerAndDaclResult } from "./owner-dacl.js";
+/** Inspect an ordered batch outside the caller's event loop, without applying trust policy. */
+export declare function readOwnerAndDaclBatch(paths: readonly string[], options?: {
+    timeoutMs?: number;
+}): Promise<OwnerAndDaclResult[]>;

package/node_modules/@openclaw/fs-safe/dist/owner-dacl-batch.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { projectOwnerAndDacl } from "./owner-dacl.js";
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { readWindowsSecurityFactsBatch, WINDOWS_SECURITY_BATCH_MAX_BYTES } from "./windows-security-command.js";
+const DEFAULT_BATCH_TIMEOUT_MS = 60_000;
+function snapshotPaths(paths) {
+    if (!Array.isArray(paths))
+        throw new TypeError("paths must be an array of path strings");
+    const length = paths.length;
+    const selected = [];
+    let bytes = 2;
+    for (let index = 0; index < length; index += 1) {
+        const value = paths[index];
+        if (!Object.hasOwn(paths, index) || typeof value !== "string" || !value || value.includes("\0")) {
+            throw new TypeError("paths must contain nonempty path strings without null bytes");
+        }
+        let captured = value;
+        if (process.platform === "win32") {
+            captured = anchorWindowsDriveRelativePath(value);
+            assertNoWindowsPathAlias(captured, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
+            const root = path.win32.parse(captured).root;
+            // Anchor cwd-dependent paths without normalizing their physical . or .. suffix.
+            if (root.length <= 1 || !path.win32.isAbsolute(captured)) {
+                const base = path.win32.resolve(root || ".");
+                captured = `${base}${base.endsWith("\\") ? "" : "\\"}${captured.slice(root.length)}`;
+            }
+            assertNoWindowsPathAlias(captured, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
+        }
+        bytes += Buffer.byteLength(JSON.stringify(captured), "utf8") + (index ? 1 : 0);
+        if (bytes > WINDOWS_SECURITY_BATCH_MAX_BYTES) {
+            throw new FsSafeError("too-large", "owner and DACL batch exceeds its input budget");
+        }
+        selected.push(captured);
+    }
+    return selected;
+}
+/** Inspect an ordered batch outside the caller's event loop, without applying trust policy. */
+export async function readOwnerAndDaclBatch(paths, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_BATCH_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new RangeError("timeoutMs must be a positive integer no greater than 2147483647");
+    }
+    const selected = snapshotPaths(paths);
+    if (process.platform !== "win32") {
+        return selected.map(() => ({ status: "unsupported-platform", platform: process.platform }));
+    }
+    if (selected.length === 0)
+        return [];
+    const config = getFsSafeNativeConfig();
+    const native = getNativeBinding();
+    const useNative = typeof native?.readOwnerAndDacl === "function";
+    if (!useNative) {
+        if (config.mode === "require") {
+            throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require an up-to-date native helper");
+        }
+        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
+    }
+    const facts = await readWindowsSecurityFactsBatch(selected, { timeoutMs, native: useNative, mode: config.mode });
+    return facts.map(projectOwnerAndDacl);
+}

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

@@ -0,0 +1,32 @@
+import type { DescriptorFacts } from "./windows-security-facts.js";
+export type WindowsAceFlags = {
+    raw: number;
+    objectInherit: boolean;
+    containerInherit: boolean;
+    noPropagateInherit: boolean;
+    inheritOnly: boolean;
+    inherited: boolean;
+    successfulAccess: boolean;
+    failedAccess: boolean;
+};
+export type WindowsAccessControlEntry = {
+    sid: string;
+    mask: number;
+    aceType: "allow" | "deny";
+    flags: WindowsAceFlags;
+};
+export type OwnerAndDaclResult = {
+    status: "supported";
+    ownerSid: string;
+    currentUserSid: string;
+    daclPresent: boolean;
+    isLocal: boolean;
+    complete: boolean;
+    unsupportedAceTypes: number[];
+    aces: WindowsAccessControlEntry[];
+} | {
+    status: "unsupported-platform";
+    platform: NodeJS.Platform;
+};
+export declare function readOwnerAndDacl(targetPath: string): OwnerAndDaclResult;
+export declare function projectOwnerAndDacl(facts: DescriptorFacts): OwnerAndDaclResult;

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

@@ -0,0 +1,39 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { readWindowsSecurityFactsCommand } from "./windows-security-command.js";
+export function readOwnerAndDacl(targetPath) {
+    if (process.platform !== "win32") {
+        return { status: "unsupported-platform", platform: process.platform };
+    }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
+    const native = getNativeBinding();
+    const inspect = native?.readOwnerAndDacl;
+    if (typeof inspect !== "function") {
+        if (getFsSafeNativeConfig().mode === "require") {
+            throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require an up-to-date native helper");
+        }
+        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
+    }
+    const facts = typeof inspect === "function" ? inspect.call(native, targetPath) : readWindowsSecurityFactsCommand(targetPath);
+    return projectOwnerAndDacl(facts);
+}
+export function projectOwnerAndDacl(facts) {
+    return {
+        status: "supported",
+        ownerSid: facts.ownerSid,
+        currentUserSid: facts.currentUserSid,
+        daclPresent: facts.daclPresent,
+        isLocal: facts.isLocal,
+        complete: facts.aceListComplete,
+        unsupportedAceTypes: [...facts.unsupportedAceTypes],
+        aces: facts.aces.map((entry) => ({
+            sid: entry.sid,
+            mask: entry.mask,
+            aceType: entry.aceType,
+            flags: { ...entry.flags },
+        })),
+    };
+}

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

@@ -0,0 +1,6 @@
+export type ProbePathCaseOptions = {
+    /** Allow an exclusively created empty probe when existing entries provide no answer. Defaults to true. */
+    allowTemporaryProbe?: boolean;
+};
+/** Observe local ASCII case behavior; unknown observations never imply an operating-system default. */
+export declare function probePathCaseInsensitiveSync(targetPath: string, options?: ProbePathCaseOptions): boolean | undefined;

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

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import fs, {} from "node:fs";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { writeTempFileSync } from "./replace-file-descriptor.js";
+import { SyncAtomicTempOwner } from "./replace-file-temp-owner.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+function swapAsciiCase(value) {
+    return value.replace(/[A-Za-z]/g, character => {
+        const lower = character.toLowerCase();
+        return character === lower ? character.toUpperCase() : lower;
+    });
+}
+function probeEntry(directory, name, names) {
+    const alternate = swapAsciiCase(name);
+    if (alternate === name)
+        return undefined;
+    const bothListed = names.has(name) && names.has(alternate);
+    const originalPath = path.join(directory, name);
+    let original;
+    let observed;
+    try {
+        original = inspectFileIdentitySync(() => fs.lstatSync(originalPath, { bigint: true }));
+        try {
+            const other = inspectFileIdentitySync(() => fs.lstatSync(path.join(directory, alternate), { bigint: true }));
+            const sameIdentity = sameFileIdentityForCleanup(original, other);
+            if (sameIdentity || bothListed) {
+                // Matching inodes can belong to newly linked case-distinct names.
+                const currentNames = new Set(fs.readdirSync(directory));
+                const bothCurrent = currentNames.has(name) && currentNames.has(alternate);
+                if (bothListed && !bothCurrent)
+                    return undefined;
+                observed = sameIdentity && !bothCurrent;
+            }
+            else {
+                observed = false;
+            }
+        }
+        catch (error) {
+            if (bothListed || !isNotFoundPathError(error))
+                return undefined;
+            observed = false;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    // Disappearance during lookup is not evidence that case variants are distinct.
+    inspectFileIdentitySync(() => fs.lstatSync(originalPath, { bigint: true }), original);
+    return observed;
+}
+function probeTemporaryEntry(directory) {
+    const name = `.fs-safe-case-probe-${randomUUID()}`;
+    const owner = new SyncAtomicTempOwner(path.join(directory, name));
+    try {
+        owner.start();
+        owner.adopt(writeTempFileSync({
+            fsModule: fs,
+            tempPath: owner.pathname,
+            content: "",
+            mode: 0o600,
+            sync: false,
+            onIdentity: owner.onIdentity,
+        }));
+        owner.assertCurrent(fs);
+        const observed = probeEntry(directory, name, new Set(fs.readdirSync(directory)));
+        owner.assertCurrent(fs);
+        return observed;
+    }
+    finally {
+        // Failed cleanup invalidates the observation; the existing owner retains its exit retry.
+        owner.finish({ fsModule: fs, throwOnCleanupError: true });
+    }
+}
+function probeDirectory(directory, allowTemporaryProbe, preferredName) {
+    const canonical = realpathSync.native(directory);
+    const identity = inspectDirectoryIdentitySync(canonical);
+    const names = new Set(fs.readdirSync(canonical));
+    let observed = preferredName === undefined ? undefined : probeEntry(canonical, preferredName, names);
+    for (const name of names) {
+        if (observed !== undefined)
+            break;
+        observed = probeEntry(canonical, name, names);
+    }
+    if (observed === undefined && allowTemporaryProbe)
+        observed = probeTemporaryEntry(canonical);
+    assertDirectoryIdentitySync(canonical, identity);
+    return realpathSync.native(directory) === canonical ? observed : undefined;
+}
+/** Observe local ASCII case behavior; unknown observations never imply an operating-system default. */
+export function probePathCaseInsensitiveSync(targetPath, options = {}) {
+    const resolved = path.resolve(targetPath);
+    const allowTemporaryProbe = options.allowTemporaryProbe !== false;
+    let targetExists = true;
+    try {
+        fs.lstatSync(resolved);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            return undefined;
+        targetExists = false;
+    }
+    if (targetExists) {
+        try {
+            return probeDirectory(path.dirname(resolved), allowTemporaryProbe, path.basename(resolved));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    let directory = path.dirname(resolved);
+    for (;;) {
+        let exists = false;
+        try {
+            exists = fs.statSync(directory).isDirectory();
+        }
+        catch {
+            // A missing or unreadable component can still have a readable existing ancestor.
+        }
+        if (exists) {
+            try {
+                return probeDirectory(directory, allowTemporaryProbe);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}