@openclaw/fs-safe 0.1.0

package/dist/home-dir.js

@@ -0,0 +1,107 @@
+import os from "node:os";
+import path from "node:path";
+import { normalizeOptionalString } from "./string-coerce.js";
+function normalize(value) {
+    const trimmed = normalizeOptionalString(value);
+    if (!trimmed) {
+        return undefined;
+    }
+    if (trimmed === "undefined" || trimmed === "null") {
+        return undefined;
+    }
+    return trimmed;
+}
+export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir) {
+    const raw = resolveRawHomeDir(env, homedir);
+    return raw ? path.resolve(raw) : undefined;
+}
+export function resolveOsHomeDir(env = process.env, homedir = os.homedir) {
+    const raw = resolveRawOsHomeDir(env, homedir);
+    return raw ? path.resolve(raw) : undefined;
+}
+function resolveRawHomeDir(env, homedir) {
+    const explicitHome = normalize(env.OPENCLAW_HOME);
+    if (explicitHome) {
+        if (explicitHome === "~" || explicitHome.startsWith("~/") || explicitHome.startsWith("~\\")) {
+            const fallbackHome = resolveRawOsHomeDir(env, homedir);
+            if (fallbackHome) {
+                return explicitHome.replace(/^~(?=$|[\\/])/, fallbackHome);
+            }
+            return undefined;
+        }
+        return explicitHome;
+    }
+    return resolveRawOsHomeDir(env, homedir);
+}
+function resolveRawOsHomeDir(env, homedir) {
+    const envHome = normalize(env.HOME);
+    if (envHome) {
+        return envHome;
+    }
+    const userProfile = normalize(env.USERPROFILE);
+    if (userProfile) {
+        return userProfile;
+    }
+    return normalizeSafe(homedir);
+}
+function normalizeSafe(homedir) {
+    try {
+        return normalize(homedir());
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveRequiredHomeDir(env = process.env, homedir = os.homedir) {
+    return resolveEffectiveHomeDir(env, homedir) ?? path.resolve(process.cwd());
+}
+export function resolveRequiredOsHomeDir(env = process.env, homedir = os.homedir) {
+    return resolveOsHomeDir(env, homedir) ?? path.resolve(process.cwd());
+}
+export function expandHomePrefix(input, opts) {
+    if (!input.startsWith("~")) {
+        return input;
+    }
+    const home = normalize(opts?.home) ??
+        resolveEffectiveHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir);
+    if (!home) {
+        return input;
+    }
+    return input.replace(/^~(?=$|[\\/])/, home);
+}
+export function resolveHomeRelativePath(input, opts) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    if (trimmed.startsWith("~")) {
+        const expanded = expandHomePrefix(trimmed, {
+            home: resolveRequiredHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+            env: opts?.env,
+            homedir: opts?.homedir,
+        });
+        return path.resolve(expanded);
+    }
+    return path.resolve(trimmed);
+}
+export function resolveUserPath(input, optsOrEnv, homedir) {
+    const opts = optsOrEnv && ("env" in optsOrEnv || "homedir" in optsOrEnv)
+        ? optsOrEnv
+        : { env: optsOrEnv, homedir };
+    return resolveHomeRelativePath(input, opts);
+}
+export function resolveOsHomeRelativePath(input, opts) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    if (trimmed.startsWith("~")) {
+        const expanded = expandHomePrefix(trimmed, {
+            home: resolveRequiredOsHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir),
+            env: opts?.env,
+            homedir: opts?.homedir,
+        });
+        return path.resolve(expanded);
+    }
+    return path.resolve(trimmed);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, } from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type HardlinkPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
+export { configureFsSafePython, getFsSafePythonConfig, type FsSafePythonConfig, type FsSafePythonMode, } from "./pinned-python-config.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, } from "./root.js";
+export { configureFsSafePython, getFsSafePythonConfig, } from "./pinned-python-config.js";

package/dist/install-path.d.ts

@@ -0,0 +1,20 @@
+export declare function safeDirName(input: string): string;
+export declare function safePathSegmentHashed(input: string): string;
+export declare function resolveSafeInstallDir(params: {
+    baseDir: string;
+    id: string;
+    invalidNameMessage: string;
+    nameEncoder?: (id: string) => string;
+}): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function assertCanonicalPathWithinBase(params: {
+    baseDir: string;
+    candidatePath: string;
+    boundaryLabel: string;
+}): Promise<void>;
+//# sourceMappingURL=install-path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAsB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}

package/dist/install-path.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPathInside } from "./path.js";
+export function safeDirName(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
+}
+export function safePathSegmentHashed(input) {
+    const trimmed = input.trim();
+    const base = trimmed
+        .replaceAll(/[\\/]/g, "-")
+        .replaceAll(/[^a-zA-Z0-9._-]/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^-+/g, "")
+        .replaceAll(/-+$/g, "");
+    const normalized = base.length > 0 ? base : "skill";
+    const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
+    const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
+    if (safe !== trimmed) {
+        const prefix = safe.length > 50 ? safe.slice(0, 50) : safe;
+        return `${prefix}-${hash}`;
+    }
+    if (safe.length > 60) {
+        return `${safe.slice(0, 50)}-${hash}`;
+    }
+    return safe;
+}
+export function resolveSafeInstallDir(params) {
+    const encodedName = (params.nameEncoder ?? safeDirName)(params.id);
+    const targetDir = path.join(params.baseDir, encodedName);
+    const resolvedBase = path.resolve(params.baseDir);
+    const resolvedTarget = path.resolve(targetDir);
+    const relative = path.relative(resolvedBase, resolvedTarget);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    return { ok: true, path: targetDir };
+}
+export async function assertCanonicalPathWithinBase(params) {
+    const baseDir = path.resolve(params.baseDir);
+    const candidatePath = path.resolve(params.candidatePath);
+    if (!isPathInside(baseDir, candidatePath)) {
+        throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+    }
+    const baseLstat = await fs.lstat(baseDir);
+    if (baseLstat.isSymbolicLink()) {
+        const baseStat = await fs.stat(baseDir);
+        if (!baseStat.isDirectory()) {
+            throw new Error(`Invalid ${params.boundaryLabel}: base directory must resolve to a directory`);
+        }
+    }
+    else if (!baseLstat.isDirectory()) {
+        throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
+    }
+    const baseRealPath = await fs.realpath(baseDir);
+    const validateDirectory = async (dirPath) => {
+        const resolvedDirPath = path.resolve(dirPath);
+        const dirLstat = await fs.lstat(dirPath);
+        if (dirLstat.isSymbolicLink()) {
+            if (resolvedDirPath !== baseDir) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+            const dirStat = await fs.stat(dirPath);
+            if (!dirStat.isDirectory()) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+        }
+        else if (!dirLstat.isDirectory()) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+        const dirRealPath = await fs.realpath(dirPath);
+        if (!isPathInside(baseRealPath, dirRealPath)) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+    };
+    try {
+        await validateDirectory(candidatePath);
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            throw err;
+        }
+    }
+    await validateDirectory(path.dirname(candidatePath));
+}

package/dist/install-safe-path.d.ts

@@ -0,0 +1,20 @@
+export declare function safeDirName(input: string): string;
+export declare function safePathSegmentHashed(input: string): string;
+export declare function resolveSafeInstallDir(params: {
+    baseDir: string;
+    id: string;
+    invalidNameMessage: string;
+    nameEncoder?: (id: string) => string;
+}): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function assertCanonicalPathWithinBase(params: {
+    baseDir: string;
+    candidatePath: string;
+    boundaryLabel: string;
+}): Promise<void>;
+//# sourceMappingURL=install-safe-path.d.ts.map

package/dist/install-safe-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-safe-path.d.ts","sourceRoot":"","sources":["../src/install-safe-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAsB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}

package/dist/install-safe-path.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPathInside } from "./path-guards.js";
+export function safeDirName(input) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
+}
+export function safePathSegmentHashed(input) {
+    const trimmed = input.trim();
+    const base = trimmed
+        .replaceAll(/[\\/]/g, "-")
+        .replaceAll(/[^a-zA-Z0-9._-]/g, "-")
+        .replaceAll(/-+/g, "-")
+        .replaceAll(/^-+/g, "")
+        .replaceAll(/-+$/g, "");
+    const normalized = base.length > 0 ? base : "skill";
+    const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
+    const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
+    if (safe !== trimmed) {
+        const prefix = safe.length > 50 ? safe.slice(0, 50) : safe;
+        return `${prefix}-${hash}`;
+    }
+    if (safe.length > 60) {
+        return `${safe.slice(0, 50)}-${hash}`;
+    }
+    return safe;
+}
+export function resolveSafeInstallDir(params) {
+    const encodedName = (params.nameEncoder ?? safeDirName)(params.id);
+    const targetDir = path.join(params.baseDir, encodedName);
+    const resolvedBase = path.resolve(params.baseDir);
+    const resolvedTarget = path.resolve(targetDir);
+    const relative = path.relative(resolvedBase, resolvedTarget);
+    if (!relative ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    return { ok: true, path: targetDir };
+}
+export async function assertCanonicalPathWithinBase(params) {
+    const baseDir = path.resolve(params.baseDir);
+    const candidatePath = path.resolve(params.candidatePath);
+    if (!isPathInside(baseDir, candidatePath)) {
+        throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+    }
+    const baseLstat = await fs.lstat(baseDir);
+    if (baseLstat.isSymbolicLink()) {
+        const baseStat = await fs.stat(baseDir);
+        if (!baseStat.isDirectory()) {
+            throw new Error(`Invalid ${params.boundaryLabel}: base directory must resolve to a directory`);
+        }
+    }
+    else if (!baseLstat.isDirectory()) {
+        throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
+    }
+    const baseRealPath = await fs.realpath(baseDir);
+    const validateDirectory = async (dirPath) => {
+        const resolvedDirPath = path.resolve(dirPath);
+        const dirLstat = await fs.lstat(dirPath);
+        if (dirLstat.isSymbolicLink()) {
+            if (resolvedDirPath !== baseDir) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+            const dirStat = await fs.stat(dirPath);
+            if (!dirStat.isDirectory()) {
+                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            }
+        }
+        else if (!dirLstat.isDirectory()) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+        const dirRealPath = await fs.realpath(dirPath);
+        if (!isPathInside(baseRealPath, dirRealPath)) {
+            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        }
+    };
+    try {
+        await validateDirectory(candidatePath);
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            throw err;
+        }
+    }
+    await validateDirectory(path.dirname(candidatePath));
+}

package/dist/json-document-store.d.ts

@@ -0,0 +1,30 @@
+import type { FileLockRetryOptions } from "./file-lock.js";
+export type JsonStoreLockOptions = {
+    staleMs?: number;
+    timeoutMs?: number;
+    retry?: FileLockRetryOptions;
+    managerKey?: string;
+};
+export type JsonFileStoreOptions = {
+    trailingNewline?: boolean;
+    lock?: boolean | JsonStoreLockOptions;
+};
+export type JsonStore<T> = {
+    readonly filePath: string;
+    read(): Promise<T | undefined>;
+    readOr(fallback: T): Promise<T>;
+    readRequired(): Promise<T>;
+    write(value: T): Promise<void>;
+    update(run: (current: T | undefined) => T | Promise<T>): Promise<T>;
+    updateOr(fallback: T, run: (current: T) => T | Promise<T>): Promise<T>;
+};
+export type JsonStoreAdapter<T> = {
+    filePath: string;
+    readIfExists(): Promise<T | null>;
+    readRequired(): Promise<T>;
+    write(value: T, options?: {
+        trailingNewline?: boolean;
+    }): Promise<void>;
+};
+export declare function createJsonStore<T>(adapter: JsonStoreAdapter<T>, options?: JsonFileStoreOptions): JsonStore<T>;
+//# sourceMappingURL=json-document-store.d.ts.map

package/dist/json-document-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AAyBF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CA0Dd"}

package/dist/json-document-store.js

@@ -0,0 +1,68 @@
+import { createSidecarLockManager } from "./sidecar-lock.js";
+function cloneFallback(value) {
+    if (value && typeof value === "object") {
+        return structuredClone(value);
+    }
+    return value;
+}
+function resolveLockOptions(filePath, options) {
+    if (!options.lock) {
+        return null;
+    }
+    const lockOptions = options.lock === true ? {} : options.lock;
+    return {
+        managerKey: lockOptions.managerKey ?? `fs-safe.json-store:${filePath}`,
+        retry: lockOptions.retry ?? {},
+        staleMs: lockOptions.staleMs ?? 30_000,
+        timeoutMs: lockOptions.timeoutMs ?? 30_000,
+    };
+}
+export function createJsonStore(adapter, options = {}) {
+    const lockOptions = resolveLockOptions(adapter.filePath, options);
+    const locks = lockOptions ? createSidecarLockManager(lockOptions.managerKey) : null;
+    async function read() {
+        return (await adapter.readIfExists()) ?? undefined;
+    }
+    async function readOr(fallback) {
+        return (await read()) ?? cloneFallback(fallback);
+    }
+    async function write(value) {
+        await adapter.write(value, {
+            trailingNewline: options.trailingNewline ?? true,
+        });
+    }
+    async function withOptionalLock(run) {
+        if (!locks || !lockOptions) {
+            return await run();
+        }
+        return await locks.withLock({
+            targetPath: adapter.filePath,
+            staleMs: lockOptions.staleMs,
+            timeoutMs: lockOptions.timeoutMs,
+            retry: lockOptions.retry,
+            allowReentrant: true,
+            payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+        }, run);
+    }
+    return {
+        filePath: adapter.filePath,
+        read,
+        readOr,
+        readRequired: adapter.readRequired,
+        write: async (value) => {
+            await withOptionalLock(async () => {
+                await write(value);
+            });
+        },
+        update: async (run) => await withOptionalLock(async () => {
+            const next = await run(await read());
+            await write(next);
+            return next;
+        }),
+        updateOr: async (fallback, run) => await withOptionalLock(async () => {
+            const next = await run((await read()) ?? cloneFallback(fallback));
+            await write(next);
+            return next;
+        }),
+    };
+}

package/dist/json-file.d.ts

@@ -0,0 +1,3 @@
+export declare function loadJsonFile<T = unknown>(pathname: string): T | undefined;
+export declare function saveJsonFile(pathname: string, data: unknown): void;
+//# sourceMappingURL=json-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-file.d.ts","sourceRoot":"","sources":["../src/json-file.ts"],"names":[],"mappings":"AAkGA,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAOzE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,QAqB3D"}

package/dist/json-file.js

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const JSON_FILE_MODE = 0o600;
+const JSON_DIR_MODE = 0o700;
+function trySetSecureMode(pathname) {
+    try {
+        fs.chmodSync(pathname, JSON_FILE_MODE);
+    }
+    catch {
+        // best-effort on platforms without chmod support
+    }
+}
+function trySyncDirectory(pathname) {
+    let fd;
+    try {
+        fd = fs.openSync(path.dirname(pathname), "r");
+        fs.fsyncSync(fd);
+    }
+    catch {
+        // best-effort; some platforms/filesystems do not support syncing directories.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function readSymlinkTargetPath(linkPath) {
+    const target = fs.readlinkSync(linkPath);
+    return path.resolve(path.dirname(linkPath), target);
+}
+function resolveJsonWriteTarget(pathname) {
+    let currentPath = pathname;
+    const visited = new Set();
+    let followsSymlink = false;
+    for (;;) {
+        let stat;
+        try {
+            stat = fs.lstatSync(currentPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            return { targetPath: currentPath, followsSymlink };
+        }
+        if (!stat.isSymbolicLink()) {
+            return { targetPath: currentPath, followsSymlink };
+        }
+        if (visited.has(currentPath)) {
+            const err = new Error(`Too many symlink levels while resolving ${pathname}`);
+            err.code = "ELOOP";
+            throw err;
+        }
+        visited.add(currentPath);
+        followsSymlink = true;
+        currentPath = readSymlinkTargetPath(currentPath);
+    }
+}
+function renameJsonFileWithFallback(tmpPath, pathname) {
+    try {
+        fs.renameSync(tmpPath, pathname);
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        // Windows does not reliably support rename-based overwrite for existing files.
+        if (code === "EPERM" || code === "EEXIST") {
+            fs.copyFileSync(tmpPath, pathname);
+            fs.rmSync(tmpPath, { force: true });
+            return;
+        }
+        throw error;
+    }
+}
+function writeTempJsonFile(pathname, payload) {
+    const fd = fs.openSync(pathname, "w", JSON_FILE_MODE);
+    try {
+        fs.writeFileSync(fd, payload, "utf8");
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function loadJsonFile(pathname) {
+    try {
+        const raw = fs.readFileSync(pathname, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveJsonFile(pathname, data) {
+    const { targetPath, followsSymlink } = resolveJsonWriteTarget(pathname);
+    const tmpPath = `${targetPath}.${randomUUID()}.tmp`;
+    const payload = `${JSON.stringify(data, null, 2)}\n`;
+    if (!followsSymlink) {
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true, mode: JSON_DIR_MODE });
+    }
+    try {
+        writeTempJsonFile(tmpPath, payload);
+        trySetSecureMode(tmpPath);
+        renameJsonFileWithFallback(tmpPath, targetPath);
+        trySetSecureMode(targetPath);
+        trySyncDirectory(targetPath);
+    }
+    finally {
+        try {
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup when rename does not happen
+        }
+    }
+}

package/dist/json-files.d.ts

@@ -0,0 +1,20 @@
+export declare class JsonFileReadError extends Error {
+    readonly filePath: string;
+    readonly reason: "read" | "parse";
+    constructor(filePath: string, reason: "read" | "parse", cause: unknown);
+}
+export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
+export declare function readDurableJsonFile<T>(filePath: string): Promise<T | null>;
+export declare function readJsonFileSync(filePath: string): unknown;
+export declare function writeJsonAtomic(filePath: string, value: unknown, options?: {
+    mode?: number;
+    trailingNewline?: boolean;
+    ensureDirMode?: number;
+}): Promise<void>;
+export declare function writeTextAtomic(filePath: string, content: string, options?: {
+    mode?: number;
+    ensureDirMode?: number;
+    appendTrailingNewline?: boolean;
+}): Promise<void>;
+export declare function createAsyncLock(): <T>(fn: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=json-files.d.ts.map

package/dist/json-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-files.d.ts","sourceRoot":"","sources":["../src/json-files.ts"],"names":[],"mappings":"AASA,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO;CAMvE;AA6BD,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAOzE;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAehF;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,iBAQ/E;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,iBA4CrF;AAED,wBAAgB,eAAe,KAEE,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAapE"}