@openclaw/fs-safe 0.1.0

package/dist/file-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-identity.d.ts","sourceRoot":"","sources":["../src/file-identity.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB,CAAC;AAMF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAWT"}

package/dist/file-identity.js

@@ -0,0 +1,14 @@
+function isZero(value) {
+    return value === 0 || value === 0n;
+}
+export function sameFileIdentity(left, right, platform = process.platform) {
+    if (left.ino !== right.ino) {
+        return false;
+    }
+    // On Windows, path-based stat calls can report dev=0 while fd-based stat
+    // reports a real volume serial; treat either-side dev=0 as "unknown device".
+    if (left.dev === right.dev) {
+        return true;
+    }
+    return platform === "win32" && (isZero(left.dev) || isZero(right.dev));
+}

package/dist/file-lock.d.ts

@@ -0,0 +1,20 @@
+import { type SidecarLockAcquireOptions, type SidecarLockHandle, type SidecarLockHeldEntry, type SidecarLockRetryOptions } from "./sidecar-lock.js";
+export type FileLockRetryOptions = SidecarLockRetryOptions;
+export type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = Omit<SidecarLockAcquireOptions<TPayload>, "targetPath"> & {
+    managerKey?: string;
+};
+export type FileLockHandle = SidecarLockHandle;
+export type FileLockHeldEntry = SidecarLockHeldEntry;
+export type FileLockManager = {
+    acquire<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>): Promise<FileLockHandle>;
+    withLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>, fn: () => Promise<T>): Promise<T>;
+    drain(): Promise<void>;
+    reset(): void;
+    heldEntries(): FileLockHeldEntry[];
+};
+export declare function acquireFileLock<TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>): Promise<FileLockHandle>;
+export declare function withFileLock<T, TPayload extends Record<string, unknown>>(targetPath: string, options: FileLockAcquireOptions<TPayload>, fn: () => Promise<T>): Promise<T>;
+export declare function createFileLockManager(key: string): FileLockManager;
+export declare function drainFileLockManagerForTest(targetPath: string, managerKey?: string): Promise<void>;
+export declare function resetFileLockManagerForTest(targetPath: string, managerKey?: string): void;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAE3D,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC;AAC/C,MAAM,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,QAAQ,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,WAAW,IAAI,iBAAiB,EAAE,CAAC;CACpC,CAAC;AAMF,wBAAsB,eAAe,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,GACxC,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAGZ;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAelE;AAED,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzF"}

package/dist/file-lock.js

@@ -0,0 +1,34 @@
+import { createSidecarLockManager, } from "./sidecar-lock.js";
+function resolveFileLockManagerKey(targetPath, managerKey) {
+    return managerKey ?? `fs-safe.file-lock:${targetPath}`;
+}
+export async function acquireFileLock(targetPath, options) {
+    return await createFileLockManager(resolveFileLockManagerKey(targetPath, options.managerKey))
+        .acquire(targetPath, options);
+}
+export async function withFileLock(targetPath, options, fn) {
+    return await createFileLockManager(resolveFileLockManagerKey(targetPath, options.managerKey))
+        .withLock(targetPath, options, fn);
+}
+export function createFileLockManager(key) {
+    const manager = createSidecarLockManager(key);
+    return {
+        acquire: async (targetPath, options) => {
+            const { managerKey: _managerKey, ...acquireOptions } = options;
+            return await manager.acquire({ ...acquireOptions, targetPath });
+        },
+        withLock: async (targetPath, options, fn) => {
+            const { managerKey: _managerKey, ...acquireOptions } = options;
+            return await manager.withLock({ ...acquireOptions, targetPath }, fn);
+        },
+        drain: manager.drain,
+        reset: manager.reset,
+        heldEntries: manager.heldEntries,
+    };
+}
+export async function drainFileLockManagerForTest(targetPath, managerKey) {
+    await createFileLockManager(resolveFileLockManagerKey(targetPath, managerKey)).drain();
+}
+export function resetFileLockManagerForTest(targetPath, managerKey) {
+    createFileLockManager(resolveFileLockManagerKey(targetPath, managerKey)).reset();
+}

package/dist/file-store.d.ts

@@ -0,0 +1,66 @@
+import type { Readable } from "node:stream";
+import { type JsonFileStoreOptions, type JsonStore } from "./json-document-store.js";
+import { type OpenResult, type ReadResult, type Root, type RootReadOptions } from "./root.js";
+export type FileStoreOptions = {
+    rootDir: string;
+    private?: boolean;
+    dirMode?: number;
+    mode?: number;
+    maxBytes?: number;
+};
+export type FileStoreWriteOptions = {
+    dirMode?: number;
+    mode?: number;
+    maxBytes?: number;
+    tempPrefix?: string;
+};
+export type FileStoreReadOptions = RootReadOptions & {
+    encoding?: BufferEncoding;
+};
+export type FileStorePruneOptions = {
+    ttlMs: number;
+    recursive?: boolean;
+    maxDepth?: number;
+    pruneEmptyDirs?: boolean;
+};
+export type FileStore = {
+    readonly rootDir: string;
+    path(relativePath: string): string;
+    root(): Promise<Root>;
+    write(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): Promise<string>;
+    writeStream(relativePath: string, stream: Readable, options?: FileStoreWriteOptions): Promise<string>;
+    copyIn(relativePath: string, sourcePath: string, options?: FileStoreWriteOptions): Promise<string>;
+    open(relativePath: string, options?: RootReadOptions): Promise<OpenResult>;
+    read(relativePath: string, options?: RootReadOptions): Promise<ReadResult>;
+    readBytes(relativePath: string, options?: RootReadOptions): Promise<Buffer>;
+    readText(relativePath: string, options?: FileStoreReadOptions): Promise<string>;
+    readTextIfExists(relativePath: string, options?: FileStoreReadOptions): Promise<string | null>;
+    readJson<T = unknown>(relativePath: string, options?: FileStoreReadOptions): Promise<T>;
+    readJsonIfExists<T = unknown>(relativePath: string, options?: FileStoreReadOptions): Promise<T | null>;
+    remove(relativePath: string): Promise<void>;
+    exists(relativePath: string): Promise<boolean>;
+    writeText(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): Promise<string>;
+    writeJson(relativePath: string, data: unknown, options?: FileStoreWriteOptions & {
+        trailingNewline?: boolean;
+    }): Promise<string>;
+    json<T = unknown>(relativePath: string, options?: JsonFileStoreOptions): JsonStore<T>;
+    pruneExpired(options: FileStorePruneOptions): Promise<void>;
+};
+export type FileStoreSync = {
+    readonly rootDir: string;
+    path(relativePath: string): string;
+    readTextIfExists(relativePath: string, options?: {
+        maxBytes?: number;
+    }): string | null;
+    readJsonIfExists<T = unknown>(relativePath: string, options?: {
+        maxBytes?: number;
+    }): T | null;
+    write(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): string;
+    writeText(relativePath: string, data: string | Uint8Array, options?: FileStoreWriteOptions): string;
+    writeJson(relativePath: string, data: unknown, options?: FileStoreWriteOptions & {
+        trailingNewline?: boolean;
+    }): string;
+};
+export declare function fileStore(options: FileStoreOptions): FileStore;
+export declare function fileStoreSync(options: FileStoreOptions): FileStoreSync;
+//# sourceMappingURL=file-store.d.ts.map

package/dist/file-store.d.ts.map

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

package/dist/file-store.js

@@ -0,0 +1,436 @@
+import { randomUUID } from "node:crypto";
+import syncFs from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { FsSafeError } from "./errors.js";
+import { createJsonStore } from "./json-document-store.js";
+import { isPathInside, resolveSafeRelativePath } from "./path.js";
+import { root } from "./root.js";
+import { writeSecretFileAtomic } from "./secret-file.js";
+import { writeSiblingTempFile } from "./sibling-temp.js";
+function assertRelativePath(relativePath) {
+    const raw = relativePath.trim();
+    if (!raw) {
+        throw new FsSafeError("invalid-path", "relative path must be non-empty");
+    }
+    return raw.replaceAll("\\", "/");
+}
+function resolveStorePath(rootDir, relativePath) {
+    return resolveSafeRelativePath(rootDir, assertRelativePath(relativePath));
+}
+function assertStoreFilePath(rootDir, filePath) {
+    if (!isPathInside(rootDir, filePath)) {
+        throw new FsSafeError("outside-workspace", "file path escapes store root");
+    }
+}
+async function ensureParent(filePath, mode) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true, mode });
+    await fs.chmod(dir, mode).catch(() => undefined);
+}
+function assertMaxBytes(size, maxBytes) {
+    if (maxBytes !== undefined && size > maxBytes) {
+        throw new FsSafeError("too-large", `file exceeds maximum size of ${maxBytes} bytes`);
+    }
+}
+function isNotFound(error) {
+    return error instanceof FsSafeError
+        ? error.code === "not-found"
+        : error.code === "ENOENT" ||
+            error.code === "ENOTDIR";
+}
+async function copyIntoRoot(params) {
+    const destination = resolveStorePath(params.rootDir, params.relativePath);
+    const sourceStat = await fs.lstat(params.sourcePath);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new FsSafeError("not-file", "source path is not a file");
+    }
+    assertMaxBytes(sourceStat.size, params.maxBytes);
+    await ensureParent(destination, params.dirMode ?? 0o700);
+    const result = await writeSiblingTempFile({
+        dir: path.dirname(destination),
+        dirMode: params.dirMode ?? 0o700,
+        mode: params.mode ?? 0o600,
+        tempPrefix: params.tempPrefix ?? `.${path.basename(destination)}`,
+        writeTemp: async (tempPath) => {
+            await fs.copyFile(params.sourcePath, tempPath);
+        },
+        resolveFinalPath: () => destination,
+        syncTempFile: true,
+        syncParentDir: true,
+    });
+    return result.filePath;
+}
+export function fileStore(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const privateMode = options.private ?? false;
+    const dirMode = options.dirMode ?? 0o700;
+    const mode = options.mode ?? 0o600;
+    const maxBytes = 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);
+        assertMaxBytes(content.byteLength, writeOptions?.maxBytes ?? maxBytes);
+        if (privateMode) {
+            await writeSecretFileAtomic({
+                rootDir,
+                filePath: destination,
+                content,
+                dirMode: writeOptions?.dirMode ?? dirMode,
+                mode: writeOptions?.mode ?? mode,
+            });
+            return destination;
+        }
+        await ensureParent(destination, writeOptions?.dirMode ?? dirMode);
+        const result = await writeSiblingTempFile({
+            dir: path.dirname(destination),
+            dirMode: writeOptions?.dirMode ?? dirMode,
+            mode: writeOptions?.mode ?? mode,
+            tempPrefix: writeOptions?.tempPrefix ?? `.${path.basename(destination)}`,
+            writeTemp: async (tempPath) => {
+                await fs.writeFile(tempPath, content);
+            },
+            resolveFinalPath: () => destination,
+            syncTempFile: true,
+            syncParentDir: true,
+        });
+        return result.filePath;
+    }
+    return {
+        rootDir,
+        path: (relativePath) => resolveStorePath(rootDir, relativePath),
+        root: openRoot,
+        write,
+        writeStream: async (relativePath, stream, writeOptions) => {
+            const destination = resolveStorePath(rootDir, relativePath);
+            const limit = writeOptions?.maxBytes ?? maxBytes;
+            if (privateMode) {
+                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;
+                    assertMaxBytes(total, limit);
+                    chunks.push(buffer);
+                }
+                await writeSecretFileAtomic({
+                    rootDir,
+                    filePath: destination,
+                    content: Buffer.concat(chunks),
+                    dirMode: writeOptions?.dirMode ?? dirMode,
+                    mode: writeOptions?.mode ?? mode,
+                });
+                return destination;
+            }
+            await ensureParent(destination, writeOptions?.dirMode ?? dirMode);
+            let total = 0;
+            const result = await writeSiblingTempFile({
+                dir: path.dirname(destination),
+                dirMode: writeOptions?.dirMode ?? dirMode,
+                mode: writeOptions?.mode ?? mode,
+                tempPrefix: writeOptions?.tempPrefix ?? `.${path.basename(destination)}`,
+                writeTemp: async (tempPath) => {
+                    const writable = await fs.open(tempPath, "w", writeOptions?.mode ?? mode);
+                    try {
+                        const out = writable.createWriteStream();
+                        stream.on("data", (chunk) => {
+                            total += Buffer.byteLength(chunk);
+                            if (limit !== undefined && total > limit) {
+                                stream.destroy(new FsSafeError("too-large", `file exceeds maximum size of ${limit} bytes`));
+                            }
+                        });
+                        await pipeline(stream, out);
+                    }
+                    finally {
+                        await writable.close().catch(() => undefined);
+                    }
+                },
+                resolveFinalPath: () => destination,
+                syncTempFile: true,
+                syncParentDir: true,
+            });
+            return result.filePath;
+        },
+        copyIn: async (relativePath, sourcePath, writeOptions) => privateMode
+            ? await (async () => {
+                const sourceStat = await fs.lstat(sourcePath);
+                if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+                    throw new FsSafeError("not-file", "source path is not a file");
+                }
+                assertMaxBytes(sourceStat.size, writeOptions?.maxBytes ?? maxBytes);
+                return await write(relativePath, await fs.readFile(sourcePath), writeOptions);
+            })()
+            : await copyIntoRoot({
+                rootDir,
+                relativePath,
+                sourcePath,
+                dirMode: writeOptions?.dirMode ?? dirMode,
+                maxBytes: writeOptions?.maxBytes ?? maxBytes,
+                mode: writeOptions?.mode ?? mode,
+                tempPrefix: writeOptions?.tempPrefix,
+            }),
+        open: async (relativePath, readOptions) => await (await openRoot()).open(assertRelativePath(relativePath), readOptions),
+        read: async (relativePath, readOptions) => await (await openRoot()).read(assertRelativePath(relativePath), readOptions),
+        readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(assertRelativePath(relativePath), readOptions),
+        readText: async (relativePath, readOptions) => {
+            const { encoding = "utf8", ...options } = readOptions ?? {};
+            return (await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+                .toString(encoding);
+        },
+        readTextIfExists: async (relativePath, readOptions) => {
+            try {
+                return await (await openRoot()).readText(assertRelativePath(relativePath), readOptions);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        readJson: async (relativePath, readOptions) => {
+            const { encoding = "utf8", ...options } = readOptions ?? {};
+            return JSON.parse((await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+                .toString(encoding));
+        },
+        readJsonIfExists: async (relativePath, readOptions) => {
+            try {
+                return await (await openRoot()).readJson(assertRelativePath(relativePath), readOptions);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        remove: async (relativePath) => {
+            await (await openRoot()).remove(assertRelativePath(relativePath));
+        },
+        exists: async (relativePath) => await (await openRoot()).exists(assertRelativePath(relativePath)),
+        writeText: async (relativePath, data, writeOptions) => await write(relativePath, data, writeOptions),
+        writeJson: async (relativePath, data, writeOptions) => {
+            const json = JSON.stringify(data, null, 2);
+            return await write(relativePath, writeOptions?.trailingNewline === false ? json : `${json}\n`, writeOptions);
+        },
+        json: (relativePath, jsonOptions) => {
+            const filePath = resolveStorePath(rootDir, relativePath);
+            return createJsonStore({
+                filePath,
+                readIfExists: async () => {
+                    try {
+                        return await (await openRoot()).readJson(assertRelativePath(relativePath));
+                    }
+                    catch (error) {
+                        if (isNotFound(error)) {
+                            return null;
+                        }
+                        throw error;
+                    }
+                },
+                readRequired: async () => await (await openRoot()).readJson(assertRelativePath(relativePath)),
+                write: async (value, options) => {
+                    const json = JSON.stringify(value, null, 2);
+                    await write(relativePath, options?.trailingNewline === false ? json : `${json}\n`);
+                },
+            }, jsonOptions);
+        },
+        pruneExpired: async (pruneOptions) => {
+            const now = Date.now();
+            const recursive = pruneOptions.recursive ?? false;
+            const maxDepth = pruneOptions.maxDepth;
+            const pruneEmptyDirs = (recursive || maxDepth !== undefined) && (pruneOptions.pruneEmptyDirs ?? false);
+            async function pruneDir(dir, depth) {
+                const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+                for (const entry of entries) {
+                    const fullPath = path.join(dir, entry.name);
+                    const stat = await fs.lstat(fullPath).catch(() => null);
+                    if (!stat || stat.isSymbolicLink()) {
+                        continue;
+                    }
+                    if (stat.isDirectory()) {
+                        const shouldDescend = maxDepth !== undefined ? depth < maxDepth : recursive;
+                        if (shouldDescend && (await pruneDir(fullPath, depth + 1))) {
+                            await fs.rmdir(fullPath).catch(() => undefined);
+                        }
+                        continue;
+                    }
+                    if (stat.isFile() && now - stat.mtimeMs > pruneOptions.ttlMs) {
+                        await fs.rm(fullPath, { force: true }).catch(() => undefined);
+                    }
+                }
+                if (!pruneEmptyDirs) {
+                    return false;
+                }
+                const remaining = await fs.readdir(dir).catch(() => null);
+                return remaining !== null && remaining.length === 0;
+            }
+            await fs.mkdir(rootDir, { recursive: true, mode: dirMode });
+            await pruneDir(rootDir, 0);
+        },
+    };
+}
+function ensureParentSync(filePath, mode) {
+    const dir = path.dirname(filePath);
+    syncFs.mkdirSync(dir, { recursive: true, mode });
+    try {
+        syncFs.chmodSync(dir, mode);
+    }
+    catch {
+        // Best-effort on platforms that do not enforce POSIX modes.
+    }
+}
+function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
+    const root = path.resolve(rootDir);
+    const target = path.resolve(targetDir);
+    assertStoreFilePath(root, target);
+    let current = root;
+    syncFs.mkdirSync(current, { recursive: true, mode });
+    const rootStat = syncFs.lstatSync(current);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new FsSafeError("not-file", `private store root must be a directory: ${current}`);
+    }
+    try {
+        syncFs.chmodSync(current, mode);
+    }
+    catch {
+        // Best-effort on platforms that do not enforce POSIX modes.
+    }
+    for (const segment of path.relative(root, target).split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = syncFs.lstatSync(current);
+            if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                throw new FsSafeError("not-file", `private store directory component must be a directory: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            syncFs.mkdirSync(current, { mode });
+        }
+        const rootReal = syncFs.realpathSync(root);
+        const currentReal = syncFs.realpathSync(current);
+        if (!isPathInside(rootReal, currentReal)) {
+            throw new FsSafeError("outside-workspace", "private store directory escapes root");
+        }
+        try {
+            syncFs.chmodSync(current, mode);
+        }
+        catch {
+            // Best-effort on platforms that do not enforce POSIX modes.
+        }
+    }
+}
+function writeFileSyncAtomic(params) {
+    const filePath = path.resolve(params.filePath);
+    assertStoreFilePath(params.rootDir, filePath);
+    if (params.privateMode) {
+        ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
+        try {
+            const stat = syncFs.lstatSync(filePath);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                throw new FsSafeError("not-file", `private store target must be a regular file: ${filePath}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+    else {
+        ensureParentSync(filePath, params.dirMode);
+    }
+    const tempPath = path.join(path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
+    let tempExists = false;
+    try {
+        syncFs.writeFileSync(tempPath, params.content, { flag: "wx", mode: params.mode });
+        tempExists = true;
+        try {
+            syncFs.chmodSync(tempPath, params.mode);
+        }
+        catch {
+            // Best-effort on platforms that do not enforce POSIX modes.
+        }
+        syncFs.renameSync(tempPath, filePath);
+        tempExists = false;
+        try {
+            syncFs.chmodSync(filePath, params.mode);
+        }
+        catch {
+            // Best-effort on platforms that do not enforce POSIX modes.
+        }
+        return filePath;
+    }
+    finally {
+        if (tempExists) {
+            try {
+                syncFs.unlinkSync(tempPath);
+            }
+            catch {
+                // Best-effort cleanup after write failure.
+            }
+        }
+    }
+}
+export function fileStoreSync(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const privateMode = options.private ?? false;
+    const dirMode = options.dirMode ?? 0o700;
+    const mode = options.mode ?? 0o600;
+    const maxBytes = options.maxBytes;
+    function write(relativePath, data, writeOptions) {
+        const destination = resolveStorePath(rootDir, relativePath);
+        const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        assertMaxBytes(content.byteLength, writeOptions?.maxBytes ?? maxBytes);
+        return writeFileSyncAtomic({
+            rootDir,
+            filePath: destination,
+            content,
+            privateMode,
+            dirMode: writeOptions?.dirMode ?? dirMode,
+            mode: writeOptions?.mode ?? mode,
+        });
+    }
+    return {
+        rootDir,
+        path: (relativePath) => resolveStorePath(rootDir, relativePath),
+        readTextIfExists: (relativePath, readOptions) => {
+            const targetPath = resolveStorePath(rootDir, relativePath);
+            try {
+                const stat = syncFs.lstatSync(targetPath);
+                if (stat.isSymbolicLink() || !stat.isFile()) {
+                    throw new FsSafeError("not-file", "store target is not a file");
+                }
+                assertMaxBytes(stat.size, readOptions?.maxBytes ?? maxBytes);
+                if (privateMode && stat.nlink > 1) {
+                    throw new FsSafeError("hardlink", "private store target must not be hardlinked");
+                }
+                return syncFs.readFileSync(targetPath, "utf8");
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        readJsonIfExists: (relativePath, readOptions) => {
+            const raw = fileStoreSync({ rootDir, private: privateMode, dirMode, mode, maxBytes })
+                .readTextIfExists(relativePath, readOptions);
+            return raw === null ? null : JSON.parse(raw);
+        },
+        write,
+        writeText: (relativePath, data, writeOptions) => write(relativePath, data, writeOptions),
+        writeJson: (relativePath, data, writeOptions) => {
+            const json = JSON.stringify(data, null, 2);
+            return write(relativePath, writeOptions?.trailingNewline === false ? json : `${json}\n`, writeOptions);
+        },
+    };
+}

package/dist/file-url.d.ts

@@ -0,0 +1,2 @@
+export * from "./local-file-access.js";
+//# sourceMappingURL=file-url.d.ts.map

package/dist/file-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-url.d.ts","sourceRoot":"","sources":["../src/file-url.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/file-url.js

@@ -0,0 +1 @@
+export * from "./local-file-access.js";

package/dist/filename.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitizeUntrustedFileName(fileName: string, fallbackName: string): string;
+//# sourceMappingURL=filename.d.ts.map

package/dist/filename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename.d.ts","sourceRoot":"","sources":["../src/filename.ts"],"names":[],"mappings":"AAEA,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAuBxF"}

package/dist/filename.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+export function sanitizeUntrustedFileName(fileName, fallbackName) {
+    const trimmed = typeof fileName === "string" ? fileName.trim() : "";
+    if (!trimmed) {
+        return fallbackName;
+    }
+    let base = path.posix.basename(trimmed);
+    base = path.win32.basename(base);
+    let cleaned = "";
+    for (let i = 0; i < base.length; i++) {
+        const code = base.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f) {
+            continue;
+        }
+        cleaned += base[i];
+    }
+    base = cleaned.trim();
+    if (!base || base === "." || base === "..") {
+        return fallbackName;
+    }
+    if (base.length > 200) {
+        base = base.slice(0, 200);
+    }
+    return base;
+}

package/dist/fs-pinned-path-helper.d.ts

@@ -0,0 +1,7 @@
+export declare function isPinnedPathHelperSpawnError(error: unknown): boolean;
+export declare function runPinnedPathHelper(params: {
+    operation: "mkdirp" | "remove";
+    rootPath: string;
+    relativePath: string;
+}): Promise<void>;
+//# sourceMappingURL=fs-pinned-path-helper.d.ts.map

package/dist/fs-pinned-path-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-pinned-path-helper.d.ts","sourceRoot":"","sources":["../src/fs-pinned-path-helper.ts"],"names":[],"mappings":"AAmKA,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWpE;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB"}