@openclaw/matrix 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/dist/root-errors.js

@@ -0,0 +1,92 @@
+import { FsSafeError } from "./errors.js";
+import { hasNodeErrorCode, isNodeError, isNotFoundPathError } from "./path.js";
+const REMOVE_NOT_EMPTY_CODES = new Set(["ENOTEMPTY", "EEXIST"]);
+const PINNED_WRITE_ERRNO_MESSAGES = new Map([
+    ["EACCES", "permission denied"],
+    ["EPERM", "permission denied"],
+    ["EROFS", "read-only filesystem"],
+    ["ENOSPC", "no space left on device"],
+]);
+export function fileNotFoundError(cause, details) {
+    return cause === undefined
+        ? new FsSafeError("not-found", "file not found", { details })
+        : new FsSafeError("not-found", "file not found", { cause, details });
+}
+export function outsideWorkspaceError() {
+    return new FsSafeError("outside-workspace", "file is outside workspace root");
+}
+export function rootPathChangedError(cause) {
+    return new FsSafeError("path-mismatch", "root path changed during operation", { cause });
+}
+export function directoryComponentNotDirectoryError(cause) {
+    return cause === undefined
+        ? new FsSafeError("not-file", "directory component must be a directory")
+        : new FsSafeError("not-file", "directory component must be a directory", { cause });
+}
+export function hardlinkedPathNotAllowedError() {
+    return new FsSafeError("hardlink", "hardlinked path not allowed");
+}
+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;
+    }
+    if (isNotFoundPathError(error)) {
+        return fileNotFoundError(error instanceof Error ? error : undefined);
+    }
+    const code = isNodeError(error) && typeof error.code === "string" && /^E[A-Z0-9_]+$/.test(error.code)
+        ? error.code : undefined;
+    const message = code
+        ? `${PINNED_WRITE_ERRNO_MESSAGES.get(code) ?? "filesystem write failed"} (${code})`
+        : "path is not a regular file under root";
+    return new FsSafeError("invalid-path", message, errorCauseOptions(error));
+}
+export function normalizePinnedPathError(error, details) {
+    if (error instanceof FsSafeError) {
+        return error;
+    }
+    return new FsSafeError("path-alias", "path is not under root", {
+        cause: error instanceof Error ? error : undefined,
+        details,
+    });
+}
+export function normalizeRemoveGuardError(error, details) {
+    if (error instanceof FsSafeError) {
+        return error;
+    }
+    if (isNotFoundPathError(error)) {
+        return fileNotFoundError(error instanceof Error ? error : undefined, details);
+    }
+    return normalizePinnedPathError(error, details);
+}
+export function normalizeRemovePathError(error, details) {
+    if (error instanceof FsSafeError) {
+        return error;
+    }
+    if (!isNodeError(error) || typeof error.code !== "string") {
+        return normalizePinnedPathError(error, details);
+    }
+    const cause = error instanceof Error ? error : undefined;
+    if (isNotFoundPathError(error)) {
+        return fileNotFoundError(cause, details);
+    }
+    if (REMOVE_NOT_EMPTY_CODES.has(error.code)) {
+        return new FsSafeError("not-empty", "directory is not empty", { cause, details });
+    }
+    return new FsSafeError("not-removable", "path could not be removed", { cause, details });
+}
+export function throwFsSafeReadError(error, label) {
+    if (error instanceof FsSafeError) {
+        throw error;
+    }
+    if (isNodeError(error)) {
+        throw new FsSafeError("read-failed", `${label} target could not be read`, { cause: error });
+    }
+    throw error;
+}
+/** Existing boundaries retain only Error instances as their cause. */
+export function errorCauseOptions(error) {
+    return { cause: error instanceof Error ? error : undefined };
+}

package/node_modules/@openclaw/fs-safe/dist/root-file-final-admission.d.ts

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import { type PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
+export type RootFileAdmissionFs = Pick<typeof fs, "lstatSync" | "realpathSync">;
+type ExactIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type CanonicalRootObservation = {
+    ok: true;
+    path: string;
+    identity: ExactIdentity;
+} | {
+    ok: false;
+    error: unknown;
+};
+export declare function observeCanonicalRoot(ioFs: RootFileAdmissionFs, rootPath: string): CanonicalRootObservation;
+export declare function createRootFileFinalAdmission(ioFs: RootFileAdmissionFs, root: Extract<CanonicalRootObservation, {
+    ok: true;
+}>, boundaryLabel: string, rejectHardlinks?: boolean): PinnedOpenSyncFinalAdmission;
+export {};

package/node_modules/@openclaw/fs-safe/dist/root-file-final-admission.js

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { isExpectedPathError } from "./pinned-open.js";
+import { realpathSync } from "./realpath.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { hardlinkedPathNotAllowedError } from "./root-errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+function rootIdentityMismatch(cause) {
+    return new FsSafeError("path-mismatch", "canonical root directory identity changed or could not be verified", cause === undefined ? {} : { cause });
+}
+function inspectCanonicalRoot(ioFs, rootPath, expected) {
+    try {
+        assertNoWindowsPathAlias(rootPath);
+        const operationPath = ioFs === fs ? pathForWindowsFilesystem(rootPath) : rootPath;
+        return inspectFileIdentitySync(() => {
+            const stat = ioFs.lstatSync(operationPath, { bigint: true });
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw rootIdentityMismatch();
+            return stat;
+        }, expected);
+    }
+    catch (error) {
+        if (expected && isExpectedPathError(error))
+            throw rootIdentityMismatch(error);
+        throw error;
+    }
+}
+export function observeCanonicalRoot(ioFs, rootPath) {
+    try {
+        const stat = inspectCanonicalRoot(ioFs, rootPath);
+        const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
+        let observedPath = rootPath;
+        if (process.platform === "win32" && ioFs === fs) {
+            // Native leaf resolution expands Windows short names. Bind that root
+            // spelling before traversal without replacing the observed identity.
+            observedPath = realpathSync.native(pathForWindowsFilesystem(rootPath));
+            if (observedPath !== rootPath)
+                inspectCanonicalRoot(ioFs, observedPath, identity);
+        }
+        return { ok: true, path: observedPath, identity };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+function resolveConsumedPath(ioFs, filePath) {
+    return ioFs === fs ? realpathSync.native(filePath) : ioFs.realpathSync(filePath);
+}
+export function createRootFileFinalAdmission(ioFs, root, boundaryLabel, rejectHardlinks = true) {
+    const inspectRoot = (candidateRootPath, expected) => {
+        inspectCanonicalRoot(ioFs, candidateRootPath, expected);
+    };
+    return ({ path: consumedPath, descriptorIdentity }) => {
+        inspectCanonicalRoot(ioFs, root.path, root.identity);
+        const canonicalPath = resolveConsumedPath(ioFs, consumedPath);
+        assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
+        const admitted = admitPathInsideRoot({
+            rootPath: root.path,
+            candidatePath: canonicalPath,
+            rootIdentity: root.identity,
+            inspectCandidateRoot: inspectRoot,
+        });
+        if (!admitted) {
+            throw new FsSafeError("outside-workspace", `resolved path escapes ${boundaryLabel}`);
+        }
+        try {
+            const current = inspectFileIdentitySync(() => ioFs.lstatSync(admitted.path, { bigint: true }), descriptorIdentity);
+            if (rejectHardlinks && current.isFile() && current.nlink > 1n)
+                throw hardlinkedPathNotAllowedError();
+        }
+        catch (error) {
+            if (isExpectedPathError(error)) {
+                throw new FsSafeError("path-mismatch", "canonical file identity changed or could not be verified", { cause: error });
+            }
+            throw error;
+        }
+        inspectCanonicalRoot(ioFs, root.path, root.identity);
+        return admitted.path;
+    };
+}

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

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import type { PathAliasPolicy } from "./path-policy.js";
+import { type SymlinkPolicy } from "./root-symlink-policy.js";
+import { type PinnedOpenSyncAllowedType, type PinnedOpenSyncFailureReason } from "./pinned-open.js";
+type BoundaryReadFs = Pick<typeof fs, "closeSync" | "constants" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "realpathSync">;
+export type RootFileOpenFailureReason = PinnedOpenSyncFailureReason | "validation";
+export type RootFileOpenResult = {
+    ok: true;
+    path: string;
+    fd: number;
+    stat: fs.Stats;
+    rootRealPath: string;
+} | {
+    ok: false;
+    reason: RootFileOpenFailureReason;
+    error?: unknown;
+};
+export type RootFileOpenFailure = Extract<RootFileOpenResult, {
+    ok: false;
+}>;
+export type OpenRootFileSyncParams = {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    rootRealPath?: string;
+    maxBytes?: number;
+    rejectHardlinks?: boolean;
+    rejectSymlinks?: boolean;
+    symlinks?: SymlinkPolicy;
+    allowedType?: PinnedOpenSyncAllowedType;
+    skipLexicalRootCheck?: boolean;
+    ioFs?: BoundaryReadFs;
+};
+export type OpenRootFileParams = OpenRootFileSyncParams & {
+    aliasPolicy?: PathAliasPolicy;
+};
+export declare function canUseRootFileOpen(ioFs: typeof fs): boolean;
+export declare function openRootFileSync(params: OpenRootFileSyncParams): RootFileOpenResult;
+export declare function matchRootFileOpenFailure<T>(failure: RootFileOpenFailure, handlers: {
+    path?: (failure: RootFileOpenFailure) => T;
+    validation?: (failure: RootFileOpenFailure) => T;
+    io?: (failure: RootFileOpenFailure) => T;
+    fallback: (failure: RootFileOpenFailure) => T;
+}): T;
+export declare function openRootFile(params: OpenRootFileParams): Promise<RootFileOpenResult>;
+export {};

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

@@ -0,0 +1,205 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveRootPathSyncWithCanonicalRootObservation, resolveRootPathWithCanonicalRootObservation, } from "./root-path.js";
+import { readSymlinkResolution } from "./root-symlink-policy.js";
+import { isExpectedPathError, openPinnedFileSync, } from "./pinned-open.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { FsSafeError } from "./errors.js";
+import { createRootFileFinalAdmission, observeCanonicalRoot, } from "./root-file-final-admission.js";
+export function canUseRootFileOpen(ioFs) {
+    return (typeof ioFs.openSync === "function" &&
+        typeof ioFs.closeSync === "function" &&
+        typeof ioFs.fstatSync === "function" &&
+        typeof ioFs.lstatSync === "function" &&
+        typeof ioFs.realpathSync === "function" &&
+        typeof ioFs.readFileSync === "function" &&
+        typeof ioFs.constants === "object" &&
+        ioFs.constants !== null);
+}
+function absoluteRootFilePath(filePath) {
+    if (path.isAbsolute(filePath))
+        return filePath;
+    const drive = path.parse(filePath).root;
+    const base = drive ? path.resolve(drive) : process.cwd();
+    return `${base}${path.sep}${filePath.slice(drive.length)}`;
+}
+export function openRootFileSync(params) {
+    const ioFs = params.ioFs ?? fs;
+    const rawAbsolutePath = params.absolutePath;
+    let resolved;
+    try {
+        const absolutePath = absoluteRootFilePath(rawAbsolutePath);
+        assertNoWindowsPathAlias(absolutePath);
+        const rootPath = params.rootPath;
+        const rootRealPath = params.rootRealPath;
+        const boundaryLabel = params.boundaryLabel;
+        let rootObservation;
+        const resolvedPath = resolveRootPathSyncWithCanonicalRootObservation({
+            absolutePath,
+            rootPath,
+            rootCanonicalPath: rootRealPath,
+            boundaryLabel,
+            ...readSymlinkResolution(params.symlinks ??
+                (params.rejectSymlinks === false ? "follow-within-root" : "reject")),
+            skipLexicalRootCheck: params.skipLexicalRootCheck,
+        }, rootCanonicalPath => {
+            rootObservation = observeCanonicalRoot(ioFs, rootCanonicalPath);
+        });
+        resolved = mapResolvedRootPath(absolutePath, boundaryLabel, resolvedPath, rootObservation);
+    }
+    catch (error) {
+        resolved = toBoundaryValidationError(error);
+    }
+    return finalizeRootFileOpen({
+        resolved,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs,
+    });
+}
+export function matchRootFileOpenFailure(failure, handlers) {
+    switch (failure.reason) {
+        case "path":
+            return handlers.path ? handlers.path(failure) : handlers.fallback(failure);
+        case "validation":
+            return handlers.validation ? handlers.validation(failure) : handlers.fallback(failure);
+        case "io":
+            return handlers.io ? handlers.io(failure) : handlers.fallback(failure);
+    }
+    return handlers.fallback(failure);
+}
+function openRootFileResolved(params) {
+    const rejectHardlinks = params.rejectHardlinks ?? true;
+    const opened = openPinnedFileSync({
+        filePath: params.absolutePath,
+        resolvedPath: params.resolvedPath,
+        rejectHardlinks,
+        maxBytes: params.maxBytes,
+        allowedType: params.allowedType,
+        ioFs: params.ioFs,
+        finalAdmission: createRootFileFinalAdmission(params.ioFs, params.rootObservation, params.boundaryLabel, rejectHardlinks),
+    });
+    if (!opened.ok) {
+        return opened;
+    }
+    return {
+        ok: true,
+        path: opened.path,
+        fd: opened.fd,
+        stat: opened.stat,
+        rootRealPath: params.rootRealPath,
+    };
+}
+function finalizeRootFileOpen(params) {
+    if ("ok" in params.resolved) {
+        return params.resolved;
+    }
+    return openRootFileResolved({
+        absolutePath: params.resolved.absolutePath,
+        resolvedPath: params.resolved.resolvedPath,
+        rootRealPath: params.resolved.rootRealPath,
+        boundaryLabel: params.resolved.boundaryLabel,
+        rootObservation: params.resolved.rootObservation,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs: params.ioFs,
+    });
+}
+export async function openRootFile(params) {
+    const ioFs = params.ioFs ?? fs;
+    const rawAbsolutePath = params.absolutePath;
+    let resolutionSnapshot;
+    try {
+        const absolutePath = absoluteRootFilePath(rawAbsolutePath);
+        assertNoWindowsPathAlias(absolutePath);
+        resolutionSnapshot = snapshotAsyncResolution(params, absolutePath);
+    }
+    catch (error) {
+        resolutionSnapshot = toBoundaryValidationError(error);
+    }
+    const openSnapshot = {
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+    };
+    let resolved;
+    if ("ok" in resolutionSnapshot) {
+        resolved = resolutionSnapshot;
+    }
+    else {
+        try {
+            let rootObservation;
+            const resolvedPath = await resolveRootPathWithCanonicalRootObservation({
+                absolutePath: resolutionSnapshot.absolutePath,
+                rootPath: resolutionSnapshot.rootPath,
+                rootCanonicalPath: resolutionSnapshot.rootRealPath,
+                boundaryLabel: resolutionSnapshot.boundaryLabel,
+                policy: resolutionSnapshot.aliasPolicy,
+                rejectSymlinks: resolutionSnapshot.rejectSymlinks,
+                rejectFinalSymlink: resolutionSnapshot.rejectFinalSymlink,
+                skipLexicalRootCheck: resolutionSnapshot.skipLexicalRootCheck,
+            }, rootCanonicalPath => {
+                rootObservation = observeCanonicalRoot(ioFs, rootCanonicalPath);
+            });
+            resolved = mapResolvedRootPath(resolutionSnapshot.absolutePath, resolutionSnapshot.boundaryLabel, resolvedPath, rootObservation);
+        }
+        catch (error) {
+            resolved = toBoundaryValidationError(error);
+        }
+    }
+    return finalizeRootFileOpen({
+        resolved,
+        maxBytes: openSnapshot.maxBytes,
+        rejectHardlinks: openSnapshot.rejectHardlinks,
+        allowedType: openSnapshot.allowedType,
+        ioFs,
+    });
+}
+function toBoundaryValidationError(error) {
+    return { ok: false, reason: "validation", error };
+}
+function mapResolvedRootPath(absolutePath, boundaryLabel, resolved, rootObservation) {
+    if (!rootObservation) {
+        return toBoundaryValidationError(new FsSafeError("path-mismatch", "canonical root identity was not observed"));
+    }
+    if (!rootObservation.ok) {
+        return toRootObservationError(rootObservation.error);
+    }
+    return {
+        absolutePath,
+        resolvedPath: resolved.canonicalPath,
+        rootRealPath: rootObservation.path,
+        boundaryLabel,
+        rootObservation,
+    };
+}
+function snapshotAsyncResolution(params, absolutePath) {
+    const rootPath = params.rootPath;
+    const rootRealPath = params.rootRealPath;
+    const boundaryLabel = params.boundaryLabel;
+    const sourceAliasPolicy = params.aliasPolicy;
+    const aliasPolicy = sourceAliasPolicy == null ? undefined : {
+        allowFinalSymlinkForUnlink: sourceAliasPolicy.allowFinalSymlinkForUnlink,
+        allowFinalHardlinkForUnlink: sourceAliasPolicy.allowFinalHardlinkForUnlink,
+    };
+    const symlinkResolution = readSymlinkResolution(params.symlinks ?? (params.rejectSymlinks === false ? "follow-within-root" : "reject"));
+    return {
+        absolutePath,
+        rootPath,
+        rootRealPath,
+        boundaryLabel,
+        aliasPolicy,
+        ...symlinkResolution,
+        skipLexicalRootCheck: params.skipLexicalRootCheck,
+    };
+}
+function toRootObservationError(error) {
+    if (error instanceof FsSafeError)
+        return toBoundaryValidationError(error);
+    if (isExpectedPathError(error)) {
+        return { ok: false, reason: "path", error };
+    }
+    return { ok: false, reason: "io", error };
+}

package/node_modules/@openclaw/fs-safe/dist/root-handle-context.d.ts

@@ -0,0 +1,4 @@
+import type { RootContext } from "./root-context.js";
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export declare function registerRootHandleContext(handle: object, context: RootContext): void;
+export declare function rootHandleContext(handle: object): RootContext;

package/node_modules/@openclaw/fs-safe/dist/root-handle-context.js

@@ -0,0 +1,12 @@
+import { FsSafeError } from "./errors.js";
+const contexts = new WeakMap();
+/** Internal registration; never reconstruct authority from public pathname fields. */
+export function registerRootHandleContext(handle, context) {
+    contexts.set(handle, context);
+}
+export function rootHandleContext(handle) {
+    const context = contexts.get(handle);
+    if (!context)
+        throw new FsSafeError("invalid-path", "watch requires a genuine fs-safe Root");
+    return context;
+}

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

@@ -0,0 +1,117 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { ContainmentGuarantee } from "./containment.js";
+import { type ReadResult } from "./read-opened-file.js";
+import { type RootEntriesOptions } from "./root-entries.js";
+import { type RootContext } from "./root-context.js";
+import type { DirEntry, PathStat } from "./types.js";
+import { type RootWalkEntry, type RootWalkOptions, type RootWalkSymlinkPolicy } from "./root-walk.js";
+import { type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions } from "./root-options.js";
+export { DEFAULT_ROOT_MAX_BYTES } from "./root-options.js";
+export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
+export type OpenResult = {
+    handle: FileHandle;
+    containment: ContainmentGuarantee;
+    realPath: string;
+    stat: Stats;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+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, options?: RootRemoveOptions): Promise<void>;
+    mkdir(relativePath: string, options?: RootMkdirOptions): Promise<void>;
+    ensureRoot(options?: RootMkdirOptions): Promise<void>;
+    write(relativePath: string, data: string | Buffer, options?: RootWriteOptions): Promise<void>;
+    create(relativePath: string, data: string | Buffer, options?: RootCreateOptions): Promise<void>;
+    create(relativePath: string, data: AsyncIterable<Uint8Array>, options?: RootCreateStreamOptions): Promise<void>;
+    writeJson(relativePath: string, data: unknown, options?: RootWriteJsonOptions): Promise<void>;
+    createJson(relativePath: string, data: unknown, options?: RootCreateJsonOptions): Promise<void>;
+    copyIn(relativePath: string, source: RootCopySource, 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[]>;
+    entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
+    move(fromRelative: string, toRelative: string, options?: RootMoveOptions): Promise<void>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
+}
+export declare class RootHandle implements Root {
+    private readonly context;
+    readonly rootDir: string;
+    readonly rootReal: string;
+    readonly rootWithSep: string;
+    readonly defaults: RootDefaults;
+    constructor(context: RootContext, defaults?: RootDefaults);
+    private mutationOptions;
+    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, options?: RootRemoveOptions): Promise<void>;
+    mkdir(relativePath: string, options?: RootMkdirOptions): Promise<void>;
+    ensureRoot(options?: RootMkdirOptions): Promise<void>;
+    write(relativePath: string, data: string | Buffer, options?: RootWriteOptions): Promise<void>;
+    create(relativePath: string, data: string | Buffer, options?: RootCreateOptions): Promise<void>;
+    create(relativePath: string, data: AsyncIterable<Uint8Array>, options?: RootCreateStreamOptions): Promise<void>;
+    writeJson(relativePath: string, data: unknown, options?: RootWriteJsonOptions): Promise<void>;
+    createJson(relativePath: string, data: unknown, options?: RootCreateJsonOptions): Promise<void>;
+    copyIn(relativePath: string, source: RootCopySource, 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?: RootMoveOptions): Promise<void>;
+    entries(relativePath: string, options?: RootEntriesOptions): AsyncIterableIterator<DirEntry>;
+    walk<Policy extends RootWalkSymlinkPolicy>(relativePath: string, options: RootWalkOptions<Policy>): AsyncIterableIterator<RootWalkEntry<Policy>>;
+}
+export declare function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
+export declare function rootFromDirectoryGuard(guard: {
+    readonly dir: string;
+    readonly realPath: string;
+    readonly stat: BigIntStats;
+}, defaults?: RootDefaults): Root;
+export declare function readLocalFileSafely(params: {
+    filePath: string;
+    maxBytes?: number;
+}): Promise<ReadResult>;
+export declare function openLocalFileSafely(params: {
+    filePath: string;
+}): Promise<OpenResult>;
+export type WritableOpenResult = OpenResult & {
+    createdForWrite: boolean;
+};