@openclaw/fs-safe 0.1.0 → 0.1.2

package/dist/path.js

@@ -22,6 +22,11 @@ export function isNodeError(value) {
 export function hasNodeErrorCode(value, code) {
     return isNodeError(value) && value.code === code;
 }
+export function assertNoNulPathInput(filePath, message = "path contains a NUL byte") {
+    if (filePath.includes("\0")) {
+        throw new FsSafeError("invalid-path", message);
+    }
+}
 export function isNotFoundPathError(value) {
     return isNodeError(value) && typeof value.code === "string" && NOT_FOUND_CODES.has(value.code);
 }
@@ -94,9 +99,7 @@ export function splitSafeRelativePath(relativePath) {
     if (relativePath.length === 0 || relativePath === ".") {
         return [];
     }
-    if (relativePath.includes("\0")) {
-        throw new FsSafeError("invalid-path", "relative path contains a NUL byte");
-    }
+    assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
     if (relativePath.includes("\\")) {
         throw new FsSafeError("invalid-path", "relative path must use forward slashes");
     }

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

@@ -1,18 +1,16 @@
-import { type FileStore } from "./file-store.js";
-export type PrivateStateStoreOptions = {
+export type PrivateFileStore = {
     rootDir: string;
-};
-export type PrivateStateStore = Omit<FileStore, "readText" | "readJson" | "writeText" | "writeJson"> & {
+    path(relativePath: string): string;
     readText(relativePath: string, options?: {
         maxBytes?: number;
     }): Promise<string | null>;
     readJson<T = unknown>(relativePath: string, options?: {
         maxBytes?: number;
     }): Promise<T | null>;
-    writeText(relativePath: string, content: string | Uint8Array): Promise<string>;
+    writeText(relativePath: string, content: string | Uint8Array): Promise<void>;
     writeJson(relativePath: string, value: unknown, options?: {
         trailingNewline?: boolean;
-    }): Promise<string>;
+    }): Promise<void>;
 };
 export declare function writePrivateTextAtomic(params: {
     rootDir: string;
@@ -56,5 +54,5 @@ export declare function writePrivateJsonAtomicSync(params: {
     value: unknown;
     trailingNewline?: boolean;
 }): void;
-export declare function privateStateStore(options: PrivateStateStoreOptions): PrivateStateStore;
+export declare function privateFileStore(rootDir: string): PrivateFileStore;
 //# sourceMappingURL=private-file-store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"private-file-store.d.ts","sourceRoot":"","sources":["../src/private-file-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAM5D,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG;IACrG,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxF,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3G,CAAC;AAgBF,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBzB;AAoBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,IAAI,CAiBhB;AAED,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAGpB;AAED,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC,GAAG,IAAI,CAGX;AAoCD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,IAAI,CA4CP;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,IAAI,CAOP;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CA2CtF"}
+{"version":3,"file":"private-file-store.d.ts","sourceRoot":"","sources":["../src/private-file-store.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxF,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG,CAAC;AAgBF,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBzB;AAoBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,IAAI,CAiBhB;AAED,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAGpB;AAED,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC,GAAG,IAAI,CAGX;AAoCD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,IAAI,CA4CP;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,IAAI,CAOP;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAiClE"}

package/dist/private-file-store.js

@@ -2,11 +2,10 @@ import { randomUUID } from "node:crypto";
 import path from "node:path";
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
-import { fileStore } from "./file-store.js";
 import { isPathInside } from "./path.js";
 import { readRegularFileSync } from "./regular-file.js";
 import { root } from "./root.js";
-import { writeSecretFileAtomic } from "./secret-file.js";
+import { writePrivateSecretFileAtomic } from "./secret-file.js";
 function resolvePrivateStorePath(rootDir, relativePath) {
     const root = path.resolve(rootDir);
     const raw = relativePath.trim();
@@ -21,7 +20,7 @@ function resolvePrivateStorePath(rootDir, relativePath) {
     return resolved;
 }
 export async function writePrivateTextAtomic(params) {
-    await writeSecretFileAtomic(params);
+    await writePrivateSecretFileAtomic(params);
 }
 export async function readPrivateText(params) {
     const rootDir = path.resolve(params.rootDir);
@@ -173,7 +172,7 @@ export function writePrivateTextAtomicSync(params) {
 }
 export async function writePrivateJsonAtomic(params) {
     const json = JSON.stringify(params.value, null, 2);
-    await writeSecretFileAtomic({
+    await writePrivateSecretFileAtomic({
         rootDir: params.rootDir,
         filePath: params.filePath,
         content: params.trailingNewline && !json.endsWith("\n") ? `${json}\n` : json,
@@ -187,47 +186,35 @@ export function writePrivateJsonAtomicSync(params) {
         content: params.trailingNewline && !json.endsWith("\n") ? `${json}\n` : json,
     });
 }
-export function privateStateStore(options) {
-    const rootDir = path.resolve(options.rootDir);
-    const store = fileStore({ rootDir, private: true });
+export function privateFileStore(rootDir) {
+    const root = path.resolve(rootDir);
     return {
-        ...store,
-        rootDir,
-        path: (relativePath) => resolvePrivateStorePath(rootDir, relativePath),
-        readText: async (relativePath, options) => {
-            const safePath = resolvePrivateStorePath(rootDir, relativePath);
-            return await readPrivateText({
-                rootDir,
-                filePath: safePath,
-                maxBytes: options?.maxBytes,
-            });
-        },
-        readJson: async (relativePath, options) => {
-            const safePath = resolvePrivateStorePath(rootDir, relativePath);
-            return await readPrivateJson({
-                rootDir,
-                filePath: safePath,
-                maxBytes: options?.maxBytes,
-            });
-        },
+        rootDir: root,
+        path: (relativePath) => resolvePrivateStorePath(root, relativePath),
+        readText: async (relativePath, options) => await readPrivateText({
+            rootDir: root,
+            filePath: resolvePrivateStorePath(root, relativePath),
+            maxBytes: options?.maxBytes,
+        }),
+        readJson: async (relativePath, options) => await readPrivateJson({
+            rootDir: root,
+            filePath: resolvePrivateStorePath(root, relativePath),
+            maxBytes: options?.maxBytes,
+        }),
         writeText: async (relativePath, content) => {
-            const safePath = resolvePrivateStorePath(rootDir, relativePath);
             await writePrivateTextAtomic({
-                rootDir,
-                filePath: safePath,
+                rootDir: root,
+                filePath: resolvePrivateStorePath(root, relativePath),
                 content,
             });
-            return safePath;
         },
         writeJson: async (relativePath, value, options) => {
-            const safePath = resolvePrivateStorePath(rootDir, relativePath);
             await writePrivateJsonAtomic({
-                rootDir,
-                filePath: safePath,
+                rootDir: root,
+                filePath: resolvePrivateStorePath(root, relativePath),
                 value,
                 trailingNewline: options?.trailingNewline,
             });
-            return safePath;
         },
     };
 }

package/dist/root-context.d.ts

@@ -0,0 +1,23 @@
+export type RootContext = {
+    rootDir: string;
+    rootReal: string;
+    rootWithSep: string;
+};
+export declare const ensureTrailingSep: (value: string) => string;
+export declare function assertValidRootRelativePath(relativePath: string): void;
+export declare function expandRelativePathWithHome(relativePath: string): Promise<string>;
+export declare function resolveRootContext(rootDir: string): Promise<RootContext>;
+export declare function resolvePathInRoot(root: RootContext, relativePath: string): Promise<{
+    rootReal: string;
+    rootWithSep: string;
+    resolved: string;
+}>;
+export declare function resolvePathWithinRoot(params: {
+    rootDir: string;
+    relativePath: string;
+}): Promise<{
+    rootReal: string;
+    rootWithSep: string;
+    resolved: string;
+}>;
+//# sourceMappingURL=root-context.d.ts.map

package/dist/root-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-context.d.ts","sourceRoot":"","sources":["../src/root-context.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,WACM,CAAC;AAEtD,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAID,wBAAsB,0BAA0B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYtF;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB9E;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,WAAW,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAQtE;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEvE"}

package/dist/root-context.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { expandHomePrefix } from "./home-dir.js";
+import { assertNoNulPathInput, isNotFoundPathError, isPathInside } from "./path.js";
+export const ensureTrailingSep = (value) => value.endsWith(path.sep) ? value : value + path.sep;
+export function assertValidRootRelativePath(relativePath) {
+    assertNoNulPathInput(relativePath, "relative path contains a NUL byte");
+}
+let cachedHomePath;
+export async function expandRelativePathWithHome(relativePath) {
+    const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    if (cachedHomePath?.raw !== rawHome) {
+        let realHome = rawHome;
+        try {
+            realHome = await fs.realpath(rawHome);
+        }
+        catch {
+            // If the home dir cannot be canonicalized, keep lexical expansion behavior.
+        }
+        cachedHomePath = { raw: rawHome, real: realHome };
+    }
+    return expandHomePrefix(relativePath, { home: cachedHomePath.real });
+}
+export async function resolveRootContext(rootDir) {
+    assertNoNulPathInput(rootDir, "root dir contains a NUL byte");
+    let rootReal;
+    try {
+        rootReal = await fs.realpath(rootDir);
+        const rootStat = await fs.stat(rootReal);
+        if (!rootStat.isDirectory()) {
+            throw new FsSafeError("invalid-path", "root dir is not a directory");
+        }
+    }
+    catch (err) {
+        if (err instanceof FsSafeError) {
+            throw err;
+        }
+        if (isNotFoundPathError(err)) {
+            throw new FsSafeError("not-found", "root dir not found");
+        }
+        throw err;
+    }
+    return {
+        rootDir: path.resolve(rootDir),
+        rootReal,
+        rootWithSep: ensureTrailingSep(rootReal),
+    };
+}
+export async function resolvePathInRoot(root, relativePath) {
+    assertValidRootRelativePath(relativePath);
+    const expanded = await expandRelativePathWithHome(relativePath);
+    const resolved = path.resolve(root.rootWithSep, expanded);
+    if (!isPathInside(root.rootWithSep, resolved)) {
+        throw new FsSafeError("outside-workspace", "file is outside workspace root");
+    }
+    return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
+}
+export async function resolvePathWithinRoot(params) {
+    return await resolvePathInRoot(await resolveRootContext(params.rootDir), params.relativePath);
+}

package/dist/root-errors.d.ts

@@ -0,0 +1,4 @@
+export declare function isAlreadyExistsError(error: unknown): boolean;
+export declare function normalizePinnedWriteError(error: unknown): Error;
+export declare function normalizePinnedPathError(error: unknown): Error;
+//# sourceMappingURL=root-errors.d.ts.map

package/dist/root-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-errors.d.ts","sourceRoot":"","sources":["../src/root-errors.ts"],"names":[],"mappings":"AAGA,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO9D"}

package/dist/root-errors.js

@@ -0,0 +1,21 @@
+import { FsSafeError } from "./errors.js";
+import { hasNodeErrorCode } from "./path.js";
+export function isAlreadyExistsError(error) {
+    return hasNodeErrorCode(error, "EEXIST") || /File exists|EEXIST/i.test(String(error));
+}
+export function normalizePinnedWriteError(error) {
+    if (error instanceof FsSafeError) {
+        return error;
+    }
+    return new FsSafeError("invalid-path", "path is not a regular file under root", {
+        cause: error instanceof Error ? error : undefined,
+    });
+}
+export function normalizePinnedPathError(error) {
+    if (error instanceof FsSafeError) {
+        return error;
+    }
+    return new FsSafeError("path-alias", "path is not under root", {
+        cause: error instanceof Error ? error : undefined,
+    });
+}

package/dist/root-impl.d.ts

@@ -0,0 +1,108 @@
+import type { Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { DirEntry, PathStat } from "./types.js";
+export type OpenResult = {
+    handle: FileHandle;
+    realPath: string;
+    stat: Stats;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export type ReadResult = {
+    buffer: Buffer;
+    realPath: string;
+    stat: Stats;
+};
+export type RootOptions = {
+    rootDir: string;
+    defaults?: RootDefaults;
+};
+export type SymlinkPolicy = "reject" | "follow-within-root";
+export type HardlinkPolicy = "reject" | "allow";
+export type WritableOpenMode = "replace" | "append" | "update";
+export type RootDefaults = {
+    hardlinks?: HardlinkPolicy;
+    maxBytes?: number;
+    mkdir?: boolean;
+    mode?: number;
+    nonBlockingRead?: boolean;
+    symlinks?: SymlinkPolicy;
+};
+export type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
+export type RootOpenOptions = Omit<RootReadOptions, "maxBytes">;
+export type RootWriteOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+    encoding?: BufferEncoding;
+    overwrite?: boolean;
+};
+export type RootOpenWritableOptions = Pick<RootDefaults, "mkdir" | "mode"> & {
+    writeMode?: WritableOpenMode;
+};
+export type RootCopyOptions = Pick<RootDefaults, "maxBytes" | "mkdir" | "mode"> & {
+    sourceHardlinks?: HardlinkPolicy;
+};
+export type RootWriteJsonOptions = RootWriteOptions & {
+    replacer?: Parameters<typeof JSON.stringify>[1];
+    space?: Parameters<typeof JSON.stringify>[2];
+    trailingNewline?: boolean;
+};
+export type RootCreateOptions = Omit<RootWriteOptions, "overwrite">;
+export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite">;
+export type RootAppendOptions = RootWriteOptions & {
+    prependNewlineIfNeeded?: boolean;
+};
+export declare const DEFAULT_ROOT_MAX_BYTES: number;
+export interface Root {
+    readonly rootDir: string;
+    readonly rootReal: string;
+    readonly rootWithSep: string;
+    readonly defaults: RootDefaults;
+    resolve(relativePath: string): Promise<string>;
+    open(relativePath: string, options?: RootOpenOptions): Promise<OpenResult>;
+    read(relativePath: string, options?: RootReadOptions): Promise<ReadResult>;
+    readBytes(relativePath: string, options?: RootReadOptions): Promise<Buffer>;
+    readText(relativePath: string, options?: RootReadOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<string>;
+    readJson<T = unknown>(relativePath: string, options?: RootReadOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<T>;
+    readAbsolute(filePath: string, options?: RootReadOptions): Promise<ReadResult>;
+    reader(options?: RootReadOptions): (filePath: string) => Promise<Buffer>;
+    openWritable(relativePath: string, options?: RootOpenWritableOptions): Promise<WritableOpenResult>;
+    append(relativePath: string, data: string | Buffer, options?: RootAppendOptions): Promise<void>;
+    remove(relativePath: string): Promise<void>;
+    mkdir(relativePath: string): Promise<void>;
+    ensureRoot(): Promise<void>;
+    write(relativePath: string, data: string | Buffer, options?: RootWriteOptions): Promise<void>;
+    create(relativePath: string, data: string | Buffer, options?: RootCreateOptions): Promise<void>;
+    writeJson(relativePath: string, data: unknown, options?: RootWriteJsonOptions): Promise<void>;
+    createJson(relativePath: string, data: unknown, options?: RootCreateJsonOptions): Promise<void>;
+    copyIn(relativePath: string, sourcePath: string, options?: RootCopyOptions): Promise<void>;
+    exists(relativePath: string): Promise<boolean>;
+    stat(relativePath: string): Promise<PathStat>;
+    list(relativePath: string, options?: {
+        withFileTypes?: false;
+    }): Promise<string[]>;
+    list(relativePath: string, options: {
+        withFileTypes: true;
+    }): Promise<DirEntry[]>;
+    move(fromRelative: string, toRelative: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+}
+export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
+export declare function readLocalFileSafely(params: {
+    filePath: string;
+    maxBytes?: number;
+}): Promise<ReadResult>;
+export declare function openLocalFileSafely(params: {
+    filePath: string;
+}): Promise<OpenResult>;
+export type WritableOpenResult = {
+    handle: FileHandle;
+    createdForWrite: boolean;
+    realPath: string;
+    stat: Stats;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export declare function resolveOpenedFileRealPathForHandle(handle: FileHandle, ioPath: string): Promise<string>;
+//# sourceMappingURL=root-impl.d.ts.map

package/dist/root-impl.d.ts.map

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