@openclaw/fs-safe 0.1.0

package/dist/json-files.js

@@ -0,0 +1,153 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+function getErrorCode(err) {
+    return err instanceof Error ? err.code : undefined;
+}
+export class JsonFileReadError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason, cause) {
+        super(`Failed to ${reason} JSON file: ${filePath}`, { cause });
+        this.name = "JsonFileReadError";
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+async function replaceFileWithWindowsFallback(tempPath, filePath, mode) {
+    try {
+        await fs.rename(tempPath, filePath);
+        return;
+    }
+    catch (err) {
+        const code = getErrorCode(err);
+        if (process.platform !== "win32" || (code !== "EPERM" && code !== "EEXIST")) {
+            throw err;
+        }
+    }
+    const existing = await fs.lstat(filePath).catch(() => null);
+    if (existing?.isSymbolicLink()) {
+        await fs.rm(filePath, { force: true });
+        await fs.rename(tempPath, filePath);
+        return;
+    }
+    await fs.copyFile(tempPath, filePath);
+    try {
+        await fs.chmod(filePath, mode);
+    }
+    catch {
+        // best-effort; ignore on platforms without chmod
+    }
+    await fs.rm(tempPath, { force: true }).catch(() => undefined);
+}
+export async function readJsonFile(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readDurableJsonFile(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (getErrorCode(err) === "ENOENT") {
+            return null;
+        }
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export function readJsonFileSync(filePath) {
+    try {
+        const raw = readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeJsonAtomic(filePath, value, options) {
+    const text = JSON.stringify(value, null, 2);
+    await writeTextAtomic(filePath, text, {
+        mode: options?.mode,
+        ensureDirMode: options?.ensureDirMode,
+        appendTrailingNewline: options?.trailingNewline,
+    });
+}
+export async function writeTextAtomic(filePath, content, options) {
+    const mode = options?.mode ?? 0o600;
+    const payload = options?.appendTrailingNewline && !content.endsWith("\n") ? `${content}\n` : content;
+    const mkdirOptions = { recursive: true };
+    if (typeof options?.ensureDirMode === "number") {
+        mkdirOptions.mode = options.ensureDirMode;
+    }
+    await fs.mkdir(path.dirname(filePath), mkdirOptions);
+    const parentDir = path.dirname(filePath);
+    const tmp = `${filePath}.${randomUUID()}.tmp`;
+    try {
+        const tmpHandle = await fs.open(tmp, "w", mode);
+        try {
+            await tmpHandle.writeFile(payload, { encoding: "utf8" });
+            await tmpHandle.sync();
+        }
+        finally {
+            await tmpHandle.close().catch(() => undefined);
+        }
+        try {
+            await fs.chmod(tmp, mode);
+        }
+        catch {
+            // best-effort; ignore on platforms without chmod
+        }
+        await replaceFileWithWindowsFallback(tmp, filePath, mode);
+        try {
+            const dirHandle = await fs.open(parentDir, "r");
+            try {
+                await dirHandle.sync();
+            }
+            finally {
+                await dirHandle.close().catch(() => undefined);
+            }
+        }
+        catch {
+            // best-effort; some platforms/filesystems do not support syncing directories.
+        }
+        try {
+            await fs.chmod(filePath, mode);
+        }
+        catch {
+            // best-effort; ignore on platforms without chmod
+        }
+    }
+    finally {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+    }
+}
+export function createAsyncLock() {
+    let lock = Promise.resolve();
+    return async function withLock(fn) {
+        const prev = lock;
+        let release;
+        lock = new Promise((resolve) => {
+            release = resolve;
+        });
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            release?.();
+        }
+    };
+}

package/dist/json-store.d.ts

@@ -0,0 +1,9 @@
+import { type JsonFileStoreOptions, type JsonStore, type JsonStoreLockOptions } from "./json-document-store.js";
+export type JsonStoreOptions<T> = JsonFileStoreOptions & {
+    filePath: string;
+    dirMode?: number;
+    mode?: number;
+};
+export type { JsonFileStoreOptions, JsonStore, JsonStoreLockOptions };
+export declare function jsonStore<T>(options: JsonStoreOptions<T>): JsonStore<T>;
+//# sourceMappingURL=json-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-store.d.ts","sourceRoot":"","sources":["../src/json-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,oBAAoB,GAAG;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,YAAY,EAAE,oBAAoB,EAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC;AAEtE,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAQvE"}

package/dist/json-store.js

@@ -0,0 +1,12 @@
+import path from "node:path";
+import { fileStore } from "./file-store.js";
+import { createJsonStore, } from "./json-document-store.js";
+export function jsonStore(options) {
+    const filePath = path.resolve(options.filePath);
+    return fileStore({
+        rootDir: path.dirname(filePath),
+        private: true,
+        mode: options.mode,
+        dirMode: options.dirMode,
+    }).json(path.basename(filePath), options);
+}

package/dist/json.d.ts

@@ -0,0 +1,17 @@
+export declare function tryReadJsonSync<T = unknown>(pathname: string): T | null;
+export declare function writeJsonSync(pathname: string, data: unknown): void;
+export declare class JsonFileReadError extends Error {
+    readonly filePath: string;
+    readonly reason: "read" | "parse";
+    constructor(filePath: string, reason: "read" | "parse", cause: unknown);
+}
+export declare function tryReadJson<T>(filePath: string): Promise<T | null>;
+export declare function readJson<T>(filePath: string): Promise<T>;
+export declare function readJsonIfExists<T>(filePath: string): Promise<T | null>;
+export declare function readJsonSync<T = unknown>(filePath: string): T;
+export declare function writeJson(filePath: string, value: unknown, options?: {
+    mode?: number;
+    trailingNewline?: boolean;
+    dirMode?: number;
+}): Promise<void>;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AA8FA,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOvE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,QAmB5D;AAED,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;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAOxE;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAY9D;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAe7E;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAY7D;AAED,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,iBAQzE"}

package/dist/json.js

@@ -0,0 +1,198 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import path from "node:path";
+import { readRegularFile, readRegularFileSync } from "./regular-file.js";
+import { writeTextAtomic } from "./text-atomic.js";
+const JSON_FILE_MODE = 0o600;
+const JSON_DIR_MODE = 0o700;
+const SUPPORTS_SYNC_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants;
+function getErrorCode(err) {
+    return err instanceof Error ? err.code : undefined;
+}
+function trySetSecureMode(pathname) {
+    let fd;
+    try {
+        fd = fsSync.openSync(pathname, fsSync.constants.O_RDONLY |
+            (SUPPORTS_SYNC_NOFOLLOW ? fsSync.constants.O_NOFOLLOW : 0));
+        fsSync.fchmodSync(fd, JSON_FILE_MODE);
+    }
+    catch {
+        // best-effort on platforms without chmod support
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function trySyncDirectory(pathname) {
+    let fd;
+    try {
+        fd = fsSync.openSync(path.dirname(pathname), "r");
+        fsSync.fsyncSync(fd);
+    }
+    catch {
+        // best-effort; some platforms/filesystems do not support syncing directories.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsSync.closeSync(fd);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function renameJsonFileWithFallback(tmpPath, pathname) {
+    try {
+        fsSync.renameSync(tmpPath, pathname);
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EPERM" || code === "EEXIST") {
+            const existing = (() => {
+                try {
+                    return fsSync.lstatSync(pathname);
+                }
+                catch (lstatError) {
+                    if (lstatError.code === "ENOENT") {
+                        return null;
+                    }
+                    throw lstatError;
+                }
+            })();
+            if (existing?.isSymbolicLink()) {
+                fsSync.rmSync(pathname, { force: true });
+                fsSync.renameSync(tmpPath, pathname);
+                return;
+            }
+            fsSync.copyFileSync(tmpPath, pathname);
+            fsSync.rmSync(tmpPath, { force: true });
+            return;
+        }
+        throw error;
+    }
+}
+function writeTempJsonFile(pathname, payload) {
+    const fd = fsSync.openSync(pathname, "wx", JSON_FILE_MODE);
+    try {
+        fsSync.writeFileSync(fd, payload, "utf8");
+        fsSync.fsyncSync(fd);
+    }
+    finally {
+        fsSync.closeSync(fd);
+    }
+}
+export function tryReadJsonSync(pathname) {
+    try {
+        const raw = readRegularFileSync({ filePath: pathname }).buffer.toString("utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeJsonSync(pathname, data) {
+    const targetPath = pathname;
+    const tmpPath = `${targetPath}.${randomUUID()}.tmp`;
+    const payload = `${JSON.stringify(data, null, 2)}\n`;
+    fsSync.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 {
+            fsSync.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup when rename does not happen
+        }
+    }
+}
+export class JsonFileReadError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason, cause) {
+        super(`Failed to ${reason} JSON file: ${filePath}`, { cause });
+        this.name = "JsonFileReadError";
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+export async function tryReadJson(filePath) {
+    try {
+        const raw = (await readRegularFile({ filePath })).buffer.toString("utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readJson(filePath) {
+    let raw;
+    try {
+        raw = (await readRegularFile({ filePath })).buffer.toString("utf8");
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export async function readJsonIfExists(filePath) {
+    let raw;
+    try {
+        raw = (await readRegularFile({ filePath })).buffer.toString("utf8");
+    }
+    catch (err) {
+        if (getErrorCode(err) === "ENOENT") {
+            return null;
+        }
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export function readJsonSync(filePath) {
+    let raw;
+    try {
+        raw = readRegularFileSync({ filePath }).buffer.toString("utf8");
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export async function writeJson(filePath, value, options) {
+    const text = JSON.stringify(value, null, 2);
+    await writeTextAtomic(filePath, text, {
+        mode: options?.mode,
+        dirMode: options?.dirMode,
+        trailingNewline: options?.trailingNewline,
+    });
+}

package/dist/local-file-access.d.ts

@@ -0,0 +1,8 @@
+export declare function hasEncodedFileUrlSeparator(pathname: string): boolean;
+export declare function isWindowsNetworkPath(filePath: string, platform?: NodeJS.Platform): boolean;
+export declare function isWindowsDriveLetterPath(filePath: string, platform?: NodeJS.Platform): boolean;
+export declare function assertNoWindowsNetworkPath(filePath: string, label?: string): void;
+export declare function safeFileURLToPath(fileUrl: string): string;
+export declare function trySafeFileURLToPath(fileUrl: string): string | undefined;
+export declare function basenameFromMediaSource(source?: string): string | undefined;
+//# sourceMappingURL=local-file-access.d.ts.map

package/dist/local-file-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAWA,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAMT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmBzD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}

package/dist/local-file-access.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { fileURLToPath, URL } from "node:url";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const ENCODED_FILE_URL_SEPARATOR_RE = /%(?:2f|5c)/i;
+function isLocalFileUrlHost(hostname) {
+    const normalized = normalizeLowercaseStringOrEmpty(hostname);
+    return normalized === "" || normalized === "localhost";
+}
+export function hasEncodedFileUrlSeparator(pathname) {
+    return ENCODED_FILE_URL_SEPARATOR_RE.test(pathname);
+}
+export function isWindowsNetworkPath(filePath, platform = process.platform) {
+    if (platform !== "win32") {
+        return false;
+    }
+    const normalized = filePath.replace(/\//g, "\\");
+    return normalized.startsWith("\\\\?\\UNC\\") || normalized.startsWith("\\\\");
+}
+export function isWindowsDriveLetterPath(filePath, platform = process.platform) {
+    return platform === "win32" && /^[A-Za-z]:[\\/]/.test(filePath);
+}
+export function assertNoWindowsNetworkPath(filePath, label = "Path") {
+    if (isWindowsNetworkPath(filePath)) {
+        throw new Error(`${label} cannot use Windows network paths: ${filePath}`);
+    }
+}
+export function safeFileURLToPath(fileUrl) {
+    let parsed;
+    try {
+        parsed = new URL(fileUrl);
+    }
+    catch {
+        throw new Error(`Invalid file:// URL: ${fileUrl}`);
+    }
+    if (parsed.protocol !== "file:") {
+        throw new Error(`Invalid file:// URL: ${fileUrl}`);
+    }
+    if (!isLocalFileUrlHost(parsed.hostname)) {
+        throw new Error(`file:// URLs with remote hosts are not allowed: ${fileUrl}`);
+    }
+    if (hasEncodedFileUrlSeparator(parsed.pathname)) {
+        throw new Error(`file:// URLs cannot encode path separators: ${fileUrl}`);
+    }
+    const filePath = fileURLToPath(parsed);
+    assertNoWindowsNetworkPath(filePath, "Local file URL");
+    return filePath;
+}
+export function trySafeFileURLToPath(fileUrl) {
+    try {
+        return safeFileURLToPath(fileUrl);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function basenameFromMediaSource(source) {
+    if (!source) {
+        return undefined;
+    }
+    if (source.startsWith("file://")) {
+        const filePath = trySafeFileURLToPath(source);
+        return filePath ? path.basename(filePath) || undefined : undefined;
+    }
+    if (/^https?:\/\//i.test(source)) {
+        try {
+            return path.basename(new URL(source).pathname) || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path.basename(source) || undefined;
+}

package/dist/local-roots.d.ts

@@ -0,0 +1,26 @@
+import { type HardlinkPolicy, type ReadResult, type SymlinkPolicy } from "./root.js";
+export type LocalRootsPathResult = {
+    path: string;
+    root: string;
+};
+export type LocalRootsReadResult = ReadResult & {
+    root: string;
+};
+export type LocalRootsInputOptions = {
+    filePath: string;
+    roots: readonly string[];
+    label?: string;
+};
+export type ResolveLocalPathFromRootsSyncOptions = LocalRootsInputOptions & {
+    allowMissing?: boolean;
+    requireFile?: boolean;
+};
+export type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
+    hardlinks?: HardlinkPolicy;
+    maxBytes?: number;
+    nonBlockingRead?: boolean;
+    symlinks?: SymlinkPolicy;
+};
+export declare function resolveLocalPathFromRootsSync(options: ResolveLocalPathFromRootsSyncOptions): LocalRootsPathResult | null;
+export declare function readLocalFileFromRoots(options: ReadLocalFileFromRootsOptions): Promise<LocalRootsReadResult | null>;
+//# sourceMappingURL=local-roots.d.ts.map

package/dist/local-roots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-roots.d.ts","sourceRoot":"","sources":["../src/local-roots.ts"],"names":[],"mappings":"AAMA,OAAO,EAAQ,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE3F,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,oCAAoC,GAAG,sBAAsB,GAAG;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,sBAAsB,GAAG;IACnE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B,CAAC;AA0FF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,oCAAoC,GAC5C,oBAAoB,GAAG,IAAI,CA6B7B;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAgCtC"}

package/dist/local-roots.js

@@ -0,0 +1,150 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { expandHomePrefix, resolveUserPath } from "./home-dir.js";
+import { safeFileURLToPath } from "./local-file-access.js";
+import { isPathInside } from "./path.js";
+import { root } from "./root.js";
+function resolveLocalPathInput(input, label) {
+    if (input.startsWith("file://")) {
+        try {
+            return safeFileURLToPath(input);
+        }
+        catch {
+            const location = label === "file path" ? "" : ` in ${label}`;
+            throw new Error(`Invalid file:// URL${location}: ${input}`);
+        }
+    }
+    if (input.includes("\0")) {
+        throw new FsSafeError("invalid-path", `${label} must not contain NUL bytes`);
+    }
+    return resolveUserPath(input);
+}
+function resolveLocalRootInput(input, label) {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        throw new FsSafeError("invalid-path", `${label} entry is required`);
+    }
+    const resolved = trimmed.startsWith("file://")
+        ? resolveLocalPathInput(trimmed, label)
+        : expandHomePrefix(trimmed);
+    if (resolved.includes("\0")) {
+        throw new FsSafeError("invalid-path", `${label} entry must not contain NUL bytes`);
+    }
+    if (!path.isAbsolute(resolved)) {
+        throw new FsSafeError("invalid-path", `${label} entries must be absolute paths: ${input}`);
+    }
+    return path.resolve(resolved);
+}
+function isPathInsideRoot(candidate, rootDir) {
+    return isPathInside(rootDir, candidate);
+}
+function resolveRootRealSync(rootDir) {
+    try {
+        const stat = fsSync.lstatSync(rootDir);
+        if (!stat.isDirectory()) {
+            return null;
+        }
+        return fsSync.realpathSync(rootDir);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveCandidateCanonicalSync(filePath) {
+    try {
+        const stat = fsSync.lstatSync(filePath);
+        return {
+            exists: true,
+            canonicalPath: fsSync.realpathSync(filePath),
+            isFile: stat.isFile(),
+        };
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    let cursor = filePath;
+    const missingSegments = [];
+    while (true) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor) {
+            return { exists: false, canonicalPath: filePath };
+        }
+        missingSegments.unshift(path.basename(cursor));
+        cursor = parent;
+        try {
+            fsSync.lstatSync(cursor);
+            const ancestorReal = fsSync.realpathSync(cursor);
+            return {
+                exists: false,
+                canonicalPath: path.join(ancestorReal, ...missingSegments),
+            };
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                throw err;
+            }
+        }
+    }
+}
+export function resolveLocalPathFromRootsSync(options) {
+    const label = options.label ?? "local roots";
+    const requestedPath = path.resolve(resolveLocalPathInput(options.filePath, "file path"));
+    for (const rootEntry of options.roots) {
+        const rootDir = resolveLocalRootInput(rootEntry, label);
+        const rootReal = resolveRootRealSync(rootDir);
+        if (!rootReal) {
+            continue;
+        }
+        let candidate;
+        try {
+            candidate = resolveCandidateCanonicalSync(requestedPath);
+        }
+        catch {
+            continue;
+        }
+        if (!candidate.exists && options.allowMissing !== true) {
+            continue;
+        }
+        if (candidate.exists && options.requireFile === true && !candidate.isFile) {
+            continue;
+        }
+        if (isPathInsideRoot(candidate.canonicalPath, rootReal)) {
+            return { path: candidate.canonicalPath, root: rootReal };
+        }
+    }
+    return null;
+}
+export async function readLocalFileFromRoots(options) {
+    const label = options.label ?? "local roots";
+    const requestedPath = path.resolve(resolveLocalPathInput(options.filePath, "file path"));
+    for (const rootEntry of options.roots) {
+        const rootDir = resolveLocalRootInput(rootEntry, label);
+        let scopedRoot;
+        try {
+            scopedRoot = await root(rootDir);
+        }
+        catch {
+            continue;
+        }
+        const relativePath = path.relative(scopedRoot.rootDir, requestedPath);
+        if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+            continue;
+        }
+        try {
+            const result = await scopedRoot.read(relativePath, {
+                hardlinks: options.hardlinks,
+                maxBytes: options.maxBytes,
+                nonBlockingRead: options.nonBlockingRead,
+                symlinks: options.symlinks,
+            });
+            return { ...result, root: scopedRoot.rootReal };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}

package/dist/mode.d.ts

@@ -0,0 +1,2 @@
+export declare function formatPosixMode(mode: number): string;
+//# sourceMappingURL=mode.d.ts.map

package/dist/mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../src/mode.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/mode.js

@@ -0,0 +1,3 @@
+export function formatPosixMode(mode) {
+    return (mode & 0o777).toString(8).padStart(3, "0");
+}

package/dist/move-path.d.ts

@@ -0,0 +1,6 @@
+export type MovePathWithCopyFallbackOptions = {
+    from: string;
+    to: string;
+};
+export declare function movePathWithCopyFallback(options: MovePathWithCopyFallbackOptions): Promise<void>;
+//# sourceMappingURL=move-path.d.ts.map