@jerryan/just-bash 3.5.0

package/dist/fs/interface.d.ts

@@ -0,0 +1,255 @@
+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;
+    /** Stable filesystem identity when the backend can expose it safely. */
+    dev?: number | bigint;
+    ino?: number | bigint;
+    identity?: string;
+}
+/**
+ * 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/apply.d.ts

@@ -0,0 +1,22 @@
+import type { OverlayWrite } from "./overlay-fs.js";
+/**
+ * Host-side application of overlay change sets to the real filesystem.
+ *
+ * This is the privileged step of the agent-sandbox flow: the sandbox
+ * never writes to disk by itself, and applying a reviewed change set is
+ * always an explicit host decision. Keeping the raw disk access here —
+ * inside the reviewed filesystem area, next to the implementations it
+ * mirrors — is what the banned-pattern lint's raw-fs restriction is for.
+ */
+/** Canonicalize a real directory path (resolves symlinks and casing). */
+export declare function canonicalizeRealPath(path: string): string;
+/** Remove a real path (recursive, force) — applying a change-set deletion. */
+export declare function removeFromRealFs(path: string): void;
+/**
+ * Apply one change-set write to a real path. Directories are mkdir -p;
+ * symlinks are recreated with the recorded target; files get the recorded
+ * content (unless metadataOnly — a chmod/utimes copy-up), the recorded
+ * mode (POSIX only — mode bits are advisory on Windows), and the recorded
+ * mtime restored after the content write.
+ */
+export declare function applyWriteToRealFs(path: string, write: Omit<OverlayWrite, "path">): void;

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

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