just-bash-nx 2.14.4

package/dist/commands/yq/formats.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Format parsing and output for yq command
+ *
+ * Supports YAML, JSON, XML, INI, CSV, and TOML formats with conversion between them.
+ */
+import type { QueryValue } from "../query-engine/index.js";
+export type InputFormat = "yaml" | "xml" | "json" | "ini" | "csv" | "toml";
+export type OutputFormat = "yaml" | "json" | "xml" | "ini" | "csv" | "toml";
+/**
+ * Type guard to validate input format strings at runtime
+ */
+export declare function isValidInputFormat(value: unknown): value is InputFormat;
+/**
+ * Type guard to validate output format strings at runtime
+ */
+export declare function isValidOutputFormat(value: unknown): value is OutputFormat;
+export interface FormatOptions {
+    /** Input format (default: yaml) */
+    inputFormat: InputFormat;
+    /** Output format (default: yaml) */
+    outputFormat: OutputFormat;
+    /** Output raw strings without quotes (json only) */
+    raw: boolean;
+    /** Compact output (json only) */
+    compact: boolean;
+    /** Pretty print output */
+    prettyPrint: boolean;
+    /** Indentation level */
+    indent: number;
+    /** XML attribute prefix (default: +@) */
+    xmlAttributePrefix: string;
+    /** XML text content name (default: +content) */
+    xmlContentName: string;
+    /** CSV delimiter (empty = auto-detect) */
+    csvDelimiter: string;
+    /** CSV has header row */
+    csvHeader: boolean;
+}
+export declare const defaultFormatOptions: FormatOptions;
+/**
+ * Detect input format from file extension
+ */
+export declare function detectFormatFromExtension(filename: string): InputFormat | null;
+/**
+ * Parse input data from the given format into a QueryValue
+ */
+export declare function parseInput(input: string, options: FormatOptions): QueryValue;
+/**
+ * Parse all YAML documents from input (for slurp mode)
+ */
+export declare function parseAllYamlDocuments(input: string): QueryValue[];
+/**
+ * Extract front-matter from content
+ * Front-matter is YAML/TOML/JSON at the start of a file between --- or +++ delimiters
+ * Returns { frontMatter: parsed data, content: remaining content } or null if no front-matter
+ */
+export declare function extractFrontMatter(input: string): {
+    frontMatter: QueryValue;
+    content: string;
+} | null;
+/**
+ * Format a QueryValue for output in the given format
+ */
+export declare function formatOutput(value: QueryValue, options: FormatOptions): string;

package/dist/commands/yq/yq.d.ts

@@ -0,0 +1,13 @@
+/**
+ * yq - Command-line YAML/XML/INI/CSV/TOML processor
+ *
+ * Uses jq-style query expressions to process YAML, XML, INI, CSV, and TOML files.
+ * Shares the query engine with jq for consistent filtering behavior.
+ *
+ * Inspired by mikefarah/yq (https://github.com/mikefarah/yq)
+ * This is a reimplementation for the just-bash sandboxed environment.
+ */
+import type { Command } from "../../types.js";
+export declare const yqCommand: Command;
+import type { CommandFuzzInfo } from "../fuzz-flags-types.js";
+export declare const flagsForFuzzing: CommandFuzzInfo;

package/dist/custom-commands.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Custom Commands API
+ *
+ * Provides types and utilities for registering user-provided TypeScript commands.
+ */
+import type { Command, CommandContext, ExecResult } from "./types.js";
+/**
+ * A custom command - either a Command object or a lazy loader.
+ */
+export type CustomCommand = Command | LazyCommand;
+/**
+ * Lazy-loaded custom command (for code-splitting).
+ */
+export interface LazyCommand {
+    name: string;
+    load: () => Promise<Command>;
+}
+/**
+ * Type guard to check if a custom command is lazy-loaded.
+ */
+export declare function isLazyCommand(cmd: CustomCommand): cmd is LazyCommand;
+/**
+ * Define a TypeScript command with type inference.
+ * Convenience wrapper - you can also just use the Command interface directly.
+ *
+ * @example
+ * ```ts
+ * const hello = defineCommand("hello", async (args, ctx) => {
+ *   const name = args[0] || "world";
+ *   return { stdout: `Hello, ${name}!\n`, stderr: "", exitCode: 0 };
+ * });
+ *
+ * const bash = new Bash({ customCommands: [hello] });
+ * await bash.exec("hello Alice"); // "Hello, Alice!\n"
+ * ```
+ */
+export declare function defineCommand(name: string, execute: (args: string[], ctx: CommandContext) => Promise<ExecResult>): Command;
+/**
+ * Create a lazy-loaded wrapper for a custom command.
+ * The command is only loaded when first executed.
+ */
+export declare function createLazyCustomCommand(lazy: LazyCommand): Command;

package/dist/fs/encoding.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared utilities for filesystem implementations
+ */
+import type { BufferEncoding, ReadFileOptions, WriteFileOptions } from "./interface.js";
+export type FileContent = string | Uint8Array;
+/**
+ * Helper to convert content to Uint8Array
+ */
+export declare function toBuffer(content: FileContent, encoding?: BufferEncoding): Uint8Array;
+/**
+ * Helper to convert Uint8Array to string with encoding
+ */
+export declare function fromBuffer(buffer: Uint8Array, encoding?: BufferEncoding | null): string;
+/**
+ * Helper to get encoding from options
+ */
+export declare function getEncoding(options?: ReadFileOptions | WriteFileOptions | BufferEncoding | string | null): BufferEncoding | undefined;

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

@@ -0,0 +1,73 @@
+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>;
+    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,229 @@
+/**
+ * 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 a string (default: utf8)
+     * @throws Error if file doesn't exist or is a directory
+     */
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    /**
+     * 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,116 @@
+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>;
+    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";