@eidos.space/just-bash 3.0.2

package/dist/fs/in-memory-fs/in-memory-fs.d.ts

@@ -0,0 +1,75 @@
+import { type ByteString } from "../../encoding.js";
+import type { BufferEncoding, CpOptions, DirectoryEntry, DirentEntry, FileContent, FileEntry, FsEntry, FsStat, IFileSystem, InitialFiles, LazyFileEntry, MkdirOptions, ReadFileOptions, RmOptions, SymlinkEntry, WriteFileOptions } from "../interface.js";
+export type { BufferEncoding, FileContent, FileEntry, LazyFileEntry, DirectoryEntry, SymlinkEntry, FsEntry, FsStat, IFileSystem, };
+export interface FsData {
+    [path: string]: FsEntry;
+}
+export declare class InMemoryFs implements IFileSystem {
+    private data;
+    constructor(initialFiles?: InitialFiles);
+    private ensureParentDirs;
+    writeFileSync(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding, metadata?: {
+        mode?: number;
+        mtime?: Date;
+    }): void;
+    /**
+     * Store a lazy file entry whose content is provided by a function on first read.
+     * Writing to the path replaces the lazy entry, so the function is never called.
+     */
+    writeFileLazy(path: string, lazy: () => string | Uint8Array | Promise<string | Uint8Array>, metadata?: {
+        mode?: number;
+        mtime?: Date;
+    }): void;
+    /**
+     * Materialize a lazy file entry, replacing it with a concrete FileEntry.
+     * Returns the materialized FileEntry.
+     */
+    private materializeLazy;
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBytes(path: string): Promise<ByteString>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    /**
+     * Resolve symlinks in intermediate path components only (not the final component).
+     * Used by lstat which should not follow the final symlink.
+     */
+    private resolveIntermediateSymlinks;
+    /**
+     * Resolve all symlinks in a path, including intermediate components.
+     * For example: /home/user/linkdir/file.txt where linkdir is a symlink to "subdir"
+     * would resolve to /home/user/subdir/file.txt
+     */
+    private resolvePathWithSymlinks;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    /**
+     * Synchronous version of mkdir
+     */
+    mkdirSync(path: string, options?: MkdirOptions): void;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    getAllPaths(): string[];
+    resolvePath(base: string, path: string): string;
+    chmod(path: string, mode: number): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    link(existingPath: string, newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    /**
+     * Resolve all symlinks in a path to get the canonical physical path.
+     * This is equivalent to POSIX realpath().
+     */
+    realpath(path: string): Promise<string>;
+    /**
+     * Set access and modification times of a file
+     * @param path - The file path
+     * @param _atime - Access time (ignored, kept for API compatibility)
+     * @param mtime - Modification time
+     */
+    utimes(path: string, _atime: Date, mtime: Date): Promise<void>;
+}

package/dist/fs/in-memory-fs/index.d.ts

@@ -0,0 +1 @@
+export { InMemoryFs } from "./in-memory-fs.js";

package/dist/fs/init.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Filesystem Initialization
+ *
+ * Sets up the default filesystem structure for the bash environment
+ * including /dev, /proc, and common directories.
+ */
+import type { IFileSystem } from "./interface.js";
+/**
+ * Virtual process info for /proc filesystem initialization.
+ */
+interface VirtualProcessInfo {
+    pid: number;
+    ppid: number;
+    uid: number;
+    gid: number;
+}
+/**
+ * Initialize the filesystem with standard directories and files
+ * Works with both InMemoryFs and OverlayFs (both write to memory)
+ */
+export declare function initFilesystem(fs: IFileSystem, useDefaultLayout: boolean, processInfo?: VirtualProcessInfo): void;
+export {};

package/dist/fs/interface.d.ts

@@ -0,0 +1,251 @@
+import type { ByteString } from "../encoding.js";
+/**
+ * Supported buffer encodings
+ */
+export type BufferEncoding = "utf8" | "utf-8" | "ascii" | "binary" | "base64" | "hex" | "latin1";
+/**
+ * File content can be string or Buffer
+ */
+export type FileContent = string | Uint8Array;
+/**
+ * Options for reading files
+ */
+export interface ReadFileOptions {
+    encoding?: BufferEncoding | null;
+}
+/**
+ * Options for writing files
+ */
+export interface WriteFileOptions {
+    encoding?: BufferEncoding;
+}
+/**
+ * File system entry types
+ */
+export interface FileEntry {
+    type: "file";
+    content: string | Uint8Array;
+    mode: number;
+    mtime: Date;
+}
+export interface DirectoryEntry {
+    type: "directory";
+    mode: number;
+    mtime: Date;
+}
+export interface SymlinkEntry {
+    type: "symlink";
+    target: string;
+    mode: number;
+    mtime: Date;
+}
+export interface LazyFileEntry {
+    type: "file";
+    lazy: () => string | Uint8Array | Promise<string | Uint8Array>;
+    mode: number;
+    mtime: Date;
+}
+export type FsEntry = FileEntry | LazyFileEntry | DirectoryEntry | SymlinkEntry;
+/**
+ * Directory entry with type information (similar to Node's Dirent)
+ * Used by readdirWithFileTypes for efficient directory listing without stat calls
+ */
+export interface DirentEntry {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+/**
+ * Stat result from the filesystem
+ */
+export interface FsStat {
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+    mode: number;
+    size: number;
+    mtime: Date;
+}
+/**
+ * Options for mkdir operation
+ */
+export interface MkdirOptions {
+    recursive?: boolean;
+}
+/**
+ * Options for rm operation
+ */
+export interface RmOptions {
+    recursive?: boolean;
+    force?: boolean;
+}
+/**
+ * Options for cp operation
+ */
+export interface CpOptions {
+    recursive?: boolean;
+}
+/**
+ * Abstract filesystem interface that can be implemented by different backends.
+ * This allows BashEnv to work with:
+ * - InMemoryFs (in-memory, default)
+ * - Real filesystem (via node:fs)
+ * - Custom implementations (e.g., remote storage, browser IndexedDB)
+ */
+export interface IFileSystem {
+    /**
+     * Read the contents of a file as decoded text. Default encoding is utf8;
+     * pass an explicit text encoding (`"ascii"`, etc.) to override.
+     *
+     * For raw bytes (encoding `"binary"` / `"latin1"`), use {@link readFileBytes}
+     * — the opaque return type forces callers to decide whether to forward
+     * bytes unchanged or decode as text.
+     *
+     * @throws Error if file doesn't exist or is a directory
+     */
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    /**
+     * Read the raw bytes of a file as a {@link ByteString} (latin1-shaped: each
+     * char = one byte). Use when the bytes will be piped onward unchanged or
+     * explicitly decoded with `decodeBytesToUtf8` — never call string methods
+     * on the result, that's the bug class this type prevents.
+     *
+     * Optional for backwards compatibility with external `IFileSystem`
+     * implementations written before this method existed; built-in
+     * filesystems all implement it. Internal callers must route through the
+     * `readBytesFrom(fs, path)` helper, which falls back to `readFileBuffer`
+     * when this method is missing.
+     *
+     * @throws Error if file doesn't exist or is a directory
+     */
+    readFileBytes?(path: string): Promise<ByteString>;
+    /**
+     * Read the contents of a file as a Uint8Array (binary)
+     * @throws Error if file doesn't exist or is a directory
+     */
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    /**
+     * Write content to a file, creating it if it doesn't exist
+     */
+    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    /**
+     * Append content to a file, creating it if it doesn't exist
+     */
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    /**
+     * Check if a path exists
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Get file/directory information
+     * @throws Error if path doesn't exist
+     */
+    stat(path: string): Promise<FsStat>;
+    /**
+     * Create a directory
+     * @throws Error if parent doesn't exist (unless recursive) or path exists
+     */
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    /**
+     * Read directory contents
+     * @returns Array of entry names (not full paths)
+     * @throws Error if path doesn't exist or is not a directory
+     */
+    readdir(path: string): Promise<string[]>;
+    /**
+     * Read directory contents with file type information (optional)
+     * This is more efficient than readdir + stat for each entry
+     * @returns Array of DirentEntry objects with name and type
+     * @throws Error if path doesn't exist or is not a directory
+     */
+    readdirWithFileTypes?(path: string): Promise<DirentEntry[]>;
+    /**
+     * Remove a file or directory
+     * @throws Error if path doesn't exist (unless force) or directory not empty (unless recursive)
+     */
+    rm(path: string, options?: RmOptions): Promise<void>;
+    /**
+     * Copy a file or directory
+     * @throws Error if source doesn't exist or trying to copy directory without recursive
+     */
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    /**
+     * Move/rename a file or directory
+     */
+    mv(src: string, dest: string): Promise<void>;
+    /**
+     * Resolve a relative path against a base path
+     */
+    resolvePath(base: string, path: string): string;
+    /**
+     * Get all paths in the filesystem (useful for glob matching)
+     * Optional - implementations may return empty array if not supported
+     */
+    getAllPaths(): string[];
+    /**
+     * Change file/directory permissions
+     * @throws Error if path doesn't exist
+     */
+    chmod(path: string, mode: number): Promise<void>;
+    /**
+     * Create a symbolic link
+     * @param target - The path the symlink should point to
+     * @param linkPath - The path where the symlink will be created
+     * @throws Error if linkPath already exists
+     */
+    symlink(target: string, linkPath: string): Promise<void>;
+    /**
+     * Create a hard link
+     * @param existingPath - The existing file to link to
+     * @param newPath - The path where the new link will be created
+     * @throws Error if existingPath doesn't exist or newPath already exists
+     */
+    link(existingPath: string, newPath: string): Promise<void>;
+    /**
+     * Read the target of a symbolic link
+     * @throws Error if path doesn't exist or is not a symlink
+     */
+    readlink(path: string): Promise<string>;
+    /**
+     * Get file/directory information without following symlinks
+     * @throws Error if path doesn't exist
+     */
+    lstat(path: string): Promise<FsStat>;
+    /**
+     * Resolve all symlinks in a path to get the canonical physical path.
+     * This is equivalent to POSIX realpath() - it resolves all symlinks
+     * in the path and returns the absolute physical path.
+     * Used by pwd -P and cd -P for symlink resolution.
+     * @throws Error if path doesn't exist or contains a broken symlink
+     */
+    realpath(path: string): Promise<string>;
+    /**
+     * Set access and modification times of a file
+     * @param path - The file path
+     * @param atime - Access time (currently ignored, kept for API compatibility)
+     * @param mtime - Modification time
+     * @throws Error if path doesn't exist
+     */
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+}
+/**
+ * Extended file initialization options with optional metadata
+ */
+export interface FileInit {
+    content: FileContent;
+    mode?: number;
+    mtime?: Date;
+}
+/**
+ * Lazy file provider - a function whose return value becomes the file content on first read
+ */
+export type LazyFileProvider = () => string | Uint8Array | Promise<string | Uint8Array>;
+/**
+ * Initial files can be simple content, extended options with metadata, or lazy providers
+ */
+export type InitialFiles = Record<string, FileContent | FileInit | LazyFileProvider>;
+/**
+ * Factory function type for creating filesystem instances
+ */
+export type FileSystemFactory = (initialFiles?: InitialFiles) => IFileSystem;

package/dist/fs/mountable-fs/index.d.ts

@@ -0,0 +1 @@
+export { MountableFs, type MountableFsOptions, type MountConfig, } from "./mountable-fs.js";

package/dist/fs/mountable-fs/mountable-fs.d.ts

@@ -0,0 +1,118 @@
+import { type ByteString } from "../../encoding.js";
+import type { BufferEncoding, CpOptions, FileContent, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "../interface.js";
+/**
+ * Configuration for a mount point
+ */
+export interface MountConfig {
+    /** Virtual path where the filesystem is mounted */
+    mountPoint: string;
+    /** The filesystem to mount at this path */
+    filesystem: IFileSystem;
+}
+/**
+ * Options for creating a MountableFs
+ */
+export interface MountableFsOptions {
+    /** Base filesystem used for unmounted paths (defaults to InMemoryFs) */
+    base?: IFileSystem;
+    /** Initial mounts to configure */
+    mounts?: MountConfig[];
+}
+/**
+ * A filesystem that supports mounting other filesystems at specific paths.
+ *
+ * This allows combining multiple filesystem backends into a unified namespace.
+ * For example, mounting a read-only knowledge base at /mnt/knowledge and a
+ * read-write workspace at /home/agent.
+ *
+ * @example
+ * ```typescript
+ * const fs = new MountableFs({ base: new InMemoryFs() });
+ * fs.mount('/mnt/knowledge', new OverlayFs({ root: "/path/to/knowledge", readOnly: true }));
+ * fs.mount('/home/agent', new ReadWriteFs({ root: "/path/to/workspace" }));
+ * ```
+ */
+export declare class MountableFs implements IFileSystem {
+    private baseFs;
+    private mounts;
+    constructor(options?: MountableFsOptions);
+    /**
+     * Mount a filesystem at the specified virtual path.
+     *
+     * @param mountPoint - The virtual path where the filesystem will be accessible
+     * @param filesystem - The filesystem to mount
+     * @throws Error if mounting at root '/' or inside an existing mount
+     */
+    mount(mountPoint: string, filesystem: IFileSystem): void;
+    /**
+     * Unmount the filesystem at the specified path.
+     *
+     * @param mountPoint - The virtual path to unmount
+     * @throws Error if no filesystem is mounted at this path
+     */
+    unmount(mountPoint: string): void;
+    /**
+     * Get all current mounts.
+     */
+    getMounts(): ReadonlyArray<{
+        mountPoint: string;
+        filesystem: IFileSystem;
+    }>;
+    /**
+     * Check if a path is exactly a mount point.
+     */
+    isMountPoint(path: string): boolean;
+    /**
+     * Validate mount path format before normalization.
+     * Rejects paths containing . or .. segments.
+     */
+    private validateMountPath;
+    /**
+     * Validate that a mount point is allowed.
+     */
+    private validateMount;
+    /**
+     * Route a path to the appropriate filesystem.
+     * Returns the filesystem and the relative path within that filesystem.
+     */
+    private routePath;
+    /**
+     * Get mount points that are immediate children of a directory.
+     */
+    private getChildMountPoints;
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBytes(path: string): Promise<ByteString>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    resolvePath(base: string, path: string): string;
+    getAllPaths(): string[];
+    chmod(path: string, mode: number): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    link(existingPath: string, newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    /**
+     * Resolve all symlinks in a path to get the canonical physical path.
+     * This is equivalent to POSIX realpath().
+     */
+    realpath(path: string): Promise<string>;
+    /**
+     * Perform a cross-mount copy operation.
+     */
+    private crossMountCopy;
+    /**
+     * Set access and modification times of a file
+     * @param path - The file path
+     * @param atime - Access time
+     * @param mtime - Modification time
+     */
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+}

package/dist/fs/overlay-fs/index.d.ts

@@ -0,0 +1 @@
+export { OverlayFs, type OverlayFsOptions } from "./overlay-fs.js";

package/dist/fs/overlay-fs/overlay-fs.d.ts

@@ -0,0 +1,165 @@
+/**
+ * OverlayFs - Copy-on-write filesystem backed by a real directory
+ *
+ * Reads come from the real filesystem, writes go to an in-memory layer.
+ * Changes don't persist to disk and can't escape the root directory.
+ *
+ * Security: Symlinks are blocked by default (allowSymlinks: false).
+ * All real-FS access goes through resolveRealPath_() / resolveRealPathParent_()
+ * gates which detect symlink traversal via path comparison and return the
+ * canonical path for I/O (closing the TOCTOU gap). New methods must use these
+ * gates — never access the real FS directly.
+ */
+import { type ByteString } from "../../encoding.js";
+import { type FileContent } from "../encoding.js";
+import type { CpOptions, DirentEntry, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "../interface.js";
+export interface OverlayFsOptions {
+    /**
+     * The root directory on the real filesystem.
+     * All paths are relative to this root and cannot escape it.
+     */
+    root: string;
+    /**
+     * The virtual mount point where the root directory appears.
+     * Defaults to "/home/user/project".
+     */
+    mountPoint?: string;
+    /**
+     * If true, all write operations will throw an error.
+     * Useful for truly read-only access to the filesystem.
+     * Defaults to false.
+     */
+    readOnly?: boolean;
+    /**
+     * Maximum file size in bytes that can be read from the real filesystem.
+     * Files larger than this will throw an EFBIG error.
+     * Defaults to 10MB (10485760).
+     */
+    maxFileReadSize?: number;
+    /**
+     * Whether to allow following and creating symlinks on the real filesystem.
+     * When false (default), any real-FS path traversing a symlink is rejected
+     * and symlink() throws EPERM.
+     */
+    allowSymlinks?: boolean;
+}
+export declare class OverlayFs implements IFileSystem {
+    private readonly root;
+    private readonly canonicalRoot;
+    private readonly mountPoint;
+    private readonly readOnly;
+    private readonly maxFileReadSize;
+    private readonly allowSymlinks;
+    private readonly memory;
+    private readonly deleted;
+    constructor(options: OverlayFsOptions);
+    /**
+     * Throws an error if the filesystem is in read-only mode.
+     */
+    private assertWritable;
+    /**
+     * Create directory entries for the mount point path
+     */
+    private createMountPointDirs;
+    /**
+     * Get the mount point for this overlay
+     */
+    getMountPoint(): string;
+    /**
+     * Create a virtual directory in memory (sync, for initialization)
+     */
+    mkdirSync(path: string, _options?: MkdirOptions): void;
+    /**
+     * Create a virtual file in memory (sync, for initialization)
+     */
+    writeFileSync(path: string, content: string | Uint8Array): void;
+    private getDirname;
+    /**
+     * Check if a normalized virtual path is under the mount point.
+     * Returns the relative path within the mount point, or null if not under it.
+     */
+    private getRelativeToMount;
+    /**
+     * Convert a virtual path to a real filesystem path.
+     * Returns null if the path is not under the mount point or would escape the root.
+     */
+    private toRealPath;
+    /**
+     * Resolve a real-FS path to its canonical form and validate it stays
+     * within the sandbox.  Returns the canonical path for I/O, or null if
+     * the path escapes the root or traverses a symlink (when !allowSymlinks).
+     *
+     * Callers MUST use the returned canonical path for subsequent I/O to
+     * close the TOCTOU gap between validation and use.
+     */
+    private resolveRealPath_;
+    /**
+     * Resolve only the parent directory of a real-FS path, then join with
+     * the original basename.  Used by lstat/readlink/existsInOverlay where
+     * the final component may itself be a symlink we want to inspect (not
+     * follow).  Returns the canonical parent + basename for I/O, or null.
+     */
+    private resolveRealPathParent_;
+    private sanitizeError;
+    private ensureParentDirs;
+    /**
+     * Check if a path exists in the overlay (memory + real fs - deleted)
+     */
+    private existsInOverlay;
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBytes(path: string): Promise<ByteString>;
+    readFileBuffer(path: string, seen?: Set<string>): Promise<Uint8Array>;
+    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string, seen?: Set<string>): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    private resolveSymlink;
+    /**
+     * Convert a real-fs symlink target to a virtual target suitable for resolveSymlink.
+     * Handles absolute real-fs paths that point within the root by converting them
+     * to virtual paths relative to the mount point.
+     */
+    private realTargetToVirtual;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    /**
+     * Core readdir implementation that returns entries with file types.
+     * Both readdir and readdirWithFileTypes use this shared implementation.
+     */
+    private readdirCore;
+    /**
+     * Follow symlinks to resolve the final directory path.
+     * Returns outsideOverlay: true if the symlink points outside the overlay or
+     * the resolved target doesn't exist (security - broken symlinks return []).
+     */
+    private resolveForReaddir;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    /**
+     * Check (synchronously) whether a path exists on the real filesystem.
+     * Used to decide whether a tombstone is needed after deletion.
+     */
+    private existsOnRealFs;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    resolvePath(base: string, rel: string): string;
+    getAllPaths(): string[];
+    private scanRealFs;
+    chmod(path: string, mode: number): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    link(existingPath: string, newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    /**
+     * Resolve all symlinks in a path to get the canonical physical path.
+     * This is equivalent to POSIX realpath().
+     */
+    realpath(path: string): Promise<string>;
+    /**
+     * Set access and modification times of a file
+     * @param path - The file path
+     * @param _atime - Access time (ignored, kept for API compatibility)
+     * @param mtime - Modification time
+     */
+    utimes(path: string, _atime: Date, mtime: Date): Promise<void>;
+}

package/dist/fs/path-utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure path utilities for virtual filesystems.
+ *
+ * No node:fs or node:path dependencies — safe for browser bundles.
+ * Real-FS-backed implementations should import from real-fs-utils.ts
+ * (which re-exports these) to keep a single import source.
+ */
+/** Maximum depth for symlink resolution loops. */
+export declare const MAX_SYMLINK_DEPTH = 40;
+/** Default directory permissions. */
+export declare const DEFAULT_DIR_MODE = 493;
+/** Default file permissions. */
+export declare const DEFAULT_FILE_MODE = 420;
+/** Default symlink permissions. */
+export declare const SYMLINK_MODE = 511;
+/**
+ * Normalize a virtual path: resolve `.` and `..`, ensure it starts with `/`,
+ * strip trailing slashes.  Pure function, no I/O.
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * Validate that a path does not contain null bytes.
+ * Null bytes in paths can be used to truncate filenames or bypass security
+ * filters.
+ */
+export declare function validatePath(path: string, operation: string): void;
+/**
+ * Get the directory name of a normalized virtual path.
+ */
+export declare function dirname(path: string): string;
+/**
+ * Resolve a relative path against a base directory.
+ * If `path` is absolute, it is normalized and returned directly.
+ */
+export declare function resolvePath(base: string, path: string): string;
+/**
+ * Join a parent path with a child name.
+ * Handles the root-path edge case (`"/" + "child"` → `"/child"`).
+ */
+export declare function joinPath(parent: string, child: string): string;
+/**
+ * Resolve a symlink target relative to the symlink's location.
+ * Absolute targets are normalized directly; relative targets are
+ * resolved from the symlink's parent directory.
+ */
+export declare function resolveSymlinkTarget(symlinkPath: string, target: string): string;

package/dist/fs/read-write-fs/index.d.ts

@@ -0,0 +1 @@
+export { ReadWriteFs, type ReadWriteFsOptions } from "./read-write-fs.js";