just-bash-nx 2.14.4

package/dist/parser/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Parser Types and Constants
+ *
+ * Shared types, interfaces, and constants used across parser modules.
+ */
+import { type Token, TokenType } from "./lexer.js";
+export declare const MAX_INPUT_SIZE = 1000000;
+export declare const MAX_TOKENS = 100000;
+export declare const MAX_PARSE_ITERATIONS = 1000000;
+export declare const MAX_PARSER_DEPTH = 200;
+export declare const REDIRECTION_TOKENS: Set<TokenType>;
+export declare const REDIRECTION_AFTER_NUMBER: Set<TokenType>;
+export declare const REDIRECTION_AFTER_FD_VARIABLE: Set<TokenType>;
+export interface ParseError {
+    message: string;
+    line: number;
+    column: number;
+    token?: Token;
+}
+export declare class ParseException extends Error {
+    line: number;
+    column: number;
+    token: Token | undefined;
+    constructor(message: string, line: number, column: number, token?: Token | undefined);
+}

package/dist/parser/word-parser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Word Parsing Utilities
+ *
+ * String manipulation utilities for parsing words, expansions, and patterns.
+ * These are pure functions extracted from the Parser class.
+ */
+import { type ArithmeticExpressionNode, type RedirectionOperator, type WordNode, type WordPart } from "../ast/types.js";
+import { TokenType } from "./lexer.js";
+import type { Parser } from "./parser.js";
+export declare function findTildeEnd(_p: Parser, value: string, start: number): number;
+export declare function findMatchingBracket(_p: Parser, value: string, start: number, open: string, close: string): number;
+export declare function findParameterOperationEnd(_p: Parser, value: string, start: number): number;
+export declare function findPatternEnd(_p: Parser, value: string, start: number): number;
+export declare function parseGlobPattern(_p: Parser, value: string, start: number): {
+    pattern: string;
+    endIndex: number;
+};
+export declare function parseAnsiCQuoted(_p: Parser, value: string, start: number): {
+    part: WordPart;
+    endIndex: number;
+};
+export declare function parseArithExprFromString(p: Parser, str: string): ArithmeticExpressionNode;
+export type WordPartsParser = (p: Parser, value: string, quoted?: boolean, singleQuoted?: boolean, isAssignment?: boolean) => WordPart[];
+export declare function tryParseBraceExpansion(p: Parser, value: string, start: number, parseWordPartsFn?: WordPartsParser): {
+    part: WordPart;
+    endIndex: number;
+} | null;
+/**
+ * Convert a WordNode back to a string representation.
+ * Used for reconstructing array assignment strings for declare/local.
+ */
+export declare function wordToString(_p: Parser, word: WordNode): string;
+export declare function tokenToRedirectOp(_p: Parser, type: TokenType): RedirectionOperator;

package/dist/sandbox/Command.d.ts

@@ -0,0 +1,35 @@
+import type { Bash } from "../Bash.js";
+export interface OutputMessage {
+    type: "stdout" | "stderr";
+    data: string;
+    timestamp: Date;
+}
+export declare class Command {
+    readonly cmdId: string;
+    readonly cwd: string;
+    readonly startedAt: Date;
+    exitCode: number | undefined;
+    private bashEnv;
+    private cmdLine;
+    private env?;
+    private explicitCwd;
+    private signal?;
+    private timeoutMs?;
+    private abortController;
+    private timeoutId;
+    private externalAbortListener;
+    private resultPromise;
+    constructor(bashEnv: Bash, cmdLine: string, cwd: string, env?: Record<string, string>, explicitCwd?: boolean, signal?: AbortSignal, timeoutMs?: number);
+    private setupCancellation;
+    private cleanupCancellation;
+    private execute;
+    logs(): AsyncGenerator<OutputMessage, void, unknown>;
+    wait(): Promise<CommandFinished>;
+    output(): Promise<string>;
+    stdout(): Promise<string>;
+    stderr(): Promise<string>;
+    kill(): Promise<void>;
+}
+export interface CommandFinished extends Command {
+    exitCode: number;
+}

package/dist/sandbox/Sandbox.d.ts

@@ -0,0 +1,90 @@
+import type { Writable } from "node:stream";
+import { Bash } from "../Bash.js";
+import type { IFileSystem } from "../fs/interface.js";
+import type { NetworkConfig } from "../network/index.js";
+import type { DefenseInDepthConfig } from "../security/types.js";
+import type { CommandFinished } from "./Command.js";
+import { Command } from "./Command.js";
+export interface SandboxOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    /**
+     * Custom filesystem implementation.
+     * Mutually exclusive with `overlayRoot`.
+     */
+    fs?: IFileSystem;
+    /**
+     * Path to a directory to use as the root of an OverlayFs.
+     * Reads come from this directory, writes stay in memory.
+     * Mutually exclusive with `fs`.
+     */
+    overlayRoot?: string;
+    maxCallDepth?: number;
+    maxCommandCount?: number;
+    maxLoopIterations?: number;
+    /**
+     * Network configuration for commands like curl.
+     * Network access is disabled by default - you must explicitly configure allowed URLs.
+     */
+    network?: NetworkConfig;
+    /**
+     * Defense-in-depth configuration. Defaults to true (enabled).
+     * Monkey-patches dangerous JavaScript globals during bash execution.
+     */
+    defenseInDepth?: DefenseInDepthConfig | boolean;
+}
+export interface RunCommandParams {
+    cmd: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Run the command with sudo. No-op in just-bash (already runs as root). */
+    sudo?: boolean;
+    /** Return immediately with a live Command object instead of waiting for completion. */
+    detached?: boolean;
+    /** Stream standard output to a writable. Written after command completes. */
+    stdout?: Writable;
+    /** Stream standard error to a writable. Written after command completes. */
+    stderr?: Writable;
+    signal?: AbortSignal;
+}
+export interface WriteFilesInput {
+    [path: string]: string | {
+        content: string;
+        encoding?: "utf-8" | "base64";
+    };
+}
+export declare class Sandbox {
+    private bashEnv;
+    private timeoutMs?;
+    private constructor();
+    static create(opts?: SandboxOptions): Promise<Sandbox>;
+    runCommand(params: RunCommandParams & {
+        detached: true;
+    }): Promise<Command>;
+    runCommand(params: RunCommandParams): Promise<CommandFinished>;
+    runCommand(command: string, args: string[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<CommandFinished>;
+    runCommand(command: string, opts?: {
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<CommandFinished>;
+    writeFiles(files: WriteFilesInput): Promise<void>;
+    readFile(path: string, encoding?: "utf-8" | "base64"): Promise<string>;
+    mkDir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    stop(): Promise<void>;
+    extendTimeout(_ms: number): Promise<void>;
+    get domain(): string | undefined;
+    /**
+     * Bash-specific: Get the underlying Bash instance for advanced operations.
+     * Not available in Vercel Sandbox API.
+     */
+    get bashEnvInstance(): Bash;
+}
+export { Command };
+export type { CommandFinished };
+export type { OutputMessage } from "./Command.js";

package/dist/sandbox/index.d.ts

@@ -0,0 +1,2 @@
+export type { CommandFinished, OutputMessage, RunCommandParams, SandboxOptions, WriteFilesInput, } from "./Sandbox.js";
+export { Command, Sandbox, } from "./Sandbox.js";

package/dist/shell-metadata.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shell Metadata
+ *
+ * Shared source of truth for shell version and process information.
+ * Used by both variable expansion ($BASH_VERSION, $PPID, etc.)
+ * and /proc filesystem initialization.
+ */
+/**
+ * Simulated bash version string
+ */
+export declare const BASH_VERSION = "5.1.0(1)-release";
+/**
+ * Simulated kernel version for /proc/version
+ */
+export declare const KERNEL_VERSION = "Linux version 5.15.0-generic (just-bash) #1 SMP PREEMPT";
+/**
+ * Format /proc/self/status content using virtual process info.
+ * Never exposes real host process information.
+ */
+export declare function formatProcStatus(info: {
+    pid: number;
+    ppid: number;
+    uid: number;
+    gid: number;
+}): string;

package/dist/timers.d.ts

@@ -0,0 +1,4 @@
+export declare const _setTimeout: typeof globalThis.setTimeout;
+export declare const _clearTimeout: typeof globalThis.clearTimeout;
+export declare const _setInterval: typeof globalThis.setInterval;
+export declare const _clearInterval: typeof globalThis.clearInterval;

package/dist/types.d.ts

@@ -0,0 +1,198 @@
+import type { IFileSystem } from "./fs/interface.js";
+import type { ExecutionLimits } from "./limits.js";
+import type { SecureFetch } from "./network/index.js";
+/**
+ * Lightweight interface for feature coverage tracking during fuzzing.
+ * Lives here to avoid circular dependencies between fuzzing → core modules.
+ */
+export interface FeatureCoverageWriter {
+    hit(feature: string): void;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    /** The final environment variables after execution (only set by BashEnv.exec) */
+    env?: Record<string, string>;
+    /**
+     * Encoding hint for stdout content when writing to files via redirections.
+     * Set to "binary" by commands that produce binary output (e.g., cat, gzip)
+     * to prevent re-encoding of raw byte data as UTF-8.
+     * When not set, the redirect system uses UTF-8 for non-ASCII text.
+     */
+    stdoutEncoding?: "binary";
+}
+/** Result from BashEnv.exec() - always includes env */
+export interface BashExecResult extends ExecResult {
+    env: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+/** Options for exec calls within commands (internal API) */
+export interface CommandExecOptions {
+    /** Environment variables to merge into the exec state */
+    env?: Record<string, string>;
+    /**
+     * Replace the execution environment instead of merging with parent env.
+     * Useful for implementing `env -i` semantics safely without shell prefixes.
+     */
+    replaceEnv?: boolean;
+    /**
+     * Working directory for the exec.
+     * Required to prevent bugs where subcommands run in the wrong directory.
+     * Always pass `ctx.cwd` from the calling command's context.
+     */
+    cwd: string;
+    /**
+     * Standard input to pass to the subcommand.
+     * Optional - if not provided, stdin will be empty.
+     */
+    stdin?: string;
+    /**
+     * Abort signal for cooperative cancellation.
+     * When aborted, the interpreter stops executing at the next statement boundary.
+     * Used by `timeout` to ensure timed-out commands don't continue running.
+     */
+    signal?: AbortSignal;
+    /**
+     * Additional argv entries appended to the first executed command.
+     * Values bypass shell parsing entirely — no escaping, splitting, or globbing.
+     * Like child_process.spawnSync(cmd, args).
+     */
+    args?: string[];
+}
+/**
+ * Context provided to commands during execution.
+ *
+ * ## Field Availability
+ *
+ * **Always available (core fields):**
+ * - `fs`, `cwd`, `env`, `stdin`
+ *
+ * **Available when running via BashEnv interpreter:**
+ * - `exec` - For commands like `xargs`, `bash -c` that need to run subcommands
+ * - `getRegisteredCommands` - For the `help` command to list available commands
+ *
+ * **Conditionally available based on configuration:**
+ * - `fetch` - Only when `network` option is configured in BashEnv
+ * - `sleep` - Only when a custom sleep function is provided (e.g., for testing)
+ */
+/**
+ * Performance trace event for profiling command execution
+ */
+export interface TraceEvent {
+    /** Event category (e.g., "find", "grep") */
+    category: string;
+    /** Event name (e.g., "readdir", "stat", "eval") */
+    name: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Optional details (e.g., path, count) */
+    details?: Record<string, unknown>;
+}
+/**
+ * Trace callback function for receiving performance events
+ */
+export type TraceCallback = (event: TraceEvent) => void;
+export interface CommandContext {
+    /** Virtual filesystem interface for file operations */
+    fs: IFileSystem;
+    /** Current working directory */
+    cwd: string;
+    /** Environment variables - uses Map to prevent prototype pollution */
+    env: Map<string, string>;
+    /**
+     * Exported environment variables only.
+     * Used by commands like printenv and env that should only show exported vars.
+     * In bash, only exported variables are passed to child processes.
+     */
+    exportedEnv?: Record<string, string>;
+    /** Standard input content */
+    stdin: string;
+    /**
+     * Execution limits configuration.
+     * Available when running commands via BashEnv interpreter.
+     */
+    limits?: Required<ExecutionLimits>;
+    /**
+     * Performance trace callback for profiling.
+     * If provided, commands emit timing events for analysis.
+     */
+    trace?: TraceCallback;
+    /**
+     * Execute a subcommand (e.g., for `xargs`, `bash -c`).
+     * Available when running commands via BashEnv interpreter.
+     *
+     * @param command - The command string to execute
+     * @param options - Required options including `cwd` to prevent directory bugs
+     */
+    exec?: (command: string, options: CommandExecOptions) => Promise<ExecResult>;
+    /**
+     * Secure fetch function for network requests (e.g., for `curl`).
+     * Only available when `network` option is configured in BashEnv.
+     */
+    fetch?: SecureFetch;
+    /**
+     * Returns names of all registered commands.
+     * Available when running commands via BashEnv interpreter.
+     * Used by the `help` command.
+     */
+    getRegisteredCommands?: () => string[];
+    /**
+     * Custom sleep implementation.
+     * If provided, used instead of real setTimeout.
+     * Useful for testing with mock clocks.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * File descriptors map for here-docs and process substitution.
+     * Maps FD numbers to their content (e.g., 3 -> "content from 3<<EOF").
+     * Note: FD 0 content is in `stdin`, but may also appear here for consistency.
+     */
+    fileDescriptors?: Map<number, string>;
+    /**
+     * Whether xpg_echo shopt is enabled.
+     * When true, echo interprets backslash escapes by default (like echo -e).
+     */
+    xpgEcho?: boolean;
+    /**
+     * Current command substitution nesting depth.
+     * Used to prevent stack exhaustion from deeply nested $(...).
+     */
+    substitutionDepth?: number;
+    /**
+     * Feature coverage writer for fuzzing instrumentation.
+     * When provided, commands emit coverage hits for analysis.
+     */
+    coverage?: FeatureCoverageWriter;
+    /**
+     * Abort signal from the current execution context.
+     * Commands that spawn sub-executions (bash -c, xargs, etc.)
+     * should forward this signal so cooperative cancellation propagates.
+     */
+    signal?: AbortSignal;
+    /**
+     * When true, command execution must remain inside DefenseInDepthBox
+     * async context. Commands with async boundaries should assert this
+     * before and after awaited operations.
+     */
+    requireDefenseContext?: boolean;
+    /**
+     * Bootstrap JavaScript code for js-exec.
+     * Threaded through the context chain instead of shell env to prevent
+     * user access/injection via environment variables.
+     */
+    jsBootstrapCode?: string;
+}
+export interface Command {
+    name: string;
+    /**
+     * When true, execute this command inside DefenseInDepthBox.runTrustedAsync().
+     * Use for trusted host-extension commands that need direct Node.js globals.
+     * Built-in commands should generally remain untrusted and use explicit
+     * trusted wrappers only at narrow infrastructure boundaries.
+     */
+    trusted?: boolean;
+    execute(args: string[], ctx: CommandContext): Promise<ExecResult>;
+}
+export type CommandRegistry = Map<string, Command>;
+export type { IFileSystem };

package/dist/utils/args.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Lightweight argument parser for command implementations.
+ *
+ * Handles common patterns:
+ * - Boolean flags: -n, --number
+ * - Combined short flags: -rn (same as -r -n)
+ * - Value options: -k VALUE, -kVALUE, --key=VALUE, --key VALUE
+ * - Positional arguments
+ * - Unknown option detection
+ */
+import type { ExecResult } from "../types.js";
+export type ArgType = "boolean" | "string" | "number";
+export interface ArgDef {
+    /** Short form without dash, e.g., "n" for -n */
+    short?: string;
+    /** Long form without dashes, e.g., "number" for --number */
+    long?: string;
+    /** Type of the argument */
+    type: ArgType;
+    /** Default value */
+    default?: boolean | string | number;
+}
+export interface ParsedArgs<T extends Record<string, ArgDef>> {
+    /** Parsed flag/option values */
+    flags: {
+        [K in keyof T]: T[K]["type"] extends "boolean" ? boolean : T[K]["default"] extends number | string ? T[K]["type"] extends "number" ? number : string : T[K]["type"] extends "number" ? number | undefined : string | undefined;
+    };
+    /** Positional arguments (non-flag arguments) */
+    positional: string[];
+}
+export type ParseResult<T extends Record<string, ArgDef>> = {
+    ok: true;
+    result: ParsedArgs<T>;
+} | {
+    ok: false;
+    error: ExecResult;
+};
+/**
+ * Parse command arguments according to the provided definitions.
+ *
+ * @param cmdName - Command name for error messages
+ * @param args - Arguments to parse
+ * @param defs - Argument definitions
+ * @returns Parsed arguments or error result
+ *
+ * @example
+ * const defs = {
+ *   reverse: { short: "r", long: "reverse", type: "boolean" as const },
+ *   count: { short: "n", long: "lines", type: "number" as const, default: 10 },
+ * };
+ * const result = parseArgs("head", args, defs);
+ * if (!result.ok) return result.error;
+ * const { flags, positional } = result.result;
+ */
+export declare function parseArgs<T extends Record<string, ArgDef>>(cmdName: string, args: string[], defs: T): ParseResult<T>;

package/dist/utils/constants.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared constants for the bash environment.
+ */
+/**
+ * Default batch size for parallel I/O operations.
+ *
+ * This value is used across multiple commands (find, ls, tree, du, etc.) to
+ * control how many filesystem operations are performed concurrently. A larger
+ * value provides more parallelism but uses more memory; a smaller value is
+ * more conservative.
+ *
+ * 100 is a good default that provides significant parallelism without
+ * overwhelming the system or using excessive memory.
+ */
+export declare const DEFAULT_BATCH_SIZE = 100;

package/dist/utils/file-reader.d.ts

@@ -0,0 +1,67 @@
+/**
+ * File reading utilities for command implementations.
+ *
+ * Provides common patterns for reading from files or stdin,
+ * including parallel batch reading for performance.
+ */
+import type { CommandContext, ExecResult } from "../types.js";
+export interface ReadFilesOptions {
+    /** Command name for error messages */
+    cmdName: string;
+    /** If true, "-" in file list means stdin */
+    allowStdinMarker?: boolean;
+    /** If true, stop on first error. If false, collect errors and continue */
+    stopOnError?: boolean;
+    /** Number of files to read in parallel (default: 100). Set to 1 for sequential. */
+    batchSize?: number;
+}
+export interface FileContent {
+    /** File name (or "-" for stdin, or "" if stdin with no files) */
+    filename: string;
+    /** File content */
+    content: string;
+}
+export interface ReadFilesResult {
+    /** Successfully read files */
+    files: FileContent[];
+    /** Error messages (e.g., "cmd: file: No such file or directory\n") */
+    stderr: string;
+    /** 0 if all files read successfully, 1 if any errors */
+    exitCode: number;
+}
+/**
+ * Read content from files or stdin.
+ *
+ * If files array is empty, reads from stdin.
+ * If files contains "-", reads stdin at that position.
+ *
+ * @example
+ * const result = await readFiles(ctx, files, { cmdName: "cat" });
+ * if (result.exitCode !== 0 && options.stopOnError) {
+ *   return { stdout: "", stderr: result.stderr, exitCode: result.exitCode };
+ * }
+ * for (const { filename, content } of result.files) {
+ *   // process content
+ * }
+ */
+export declare function readFiles(ctx: CommandContext, files: string[], options: ReadFilesOptions): Promise<ReadFilesResult>;
+/**
+ * Read and concatenate all files into a single string.
+ *
+ * Useful for commands like sort and uniq that process all input together.
+ *
+ * @example
+ * const result = await readAndConcat(ctx, files, { cmdName: "sort" });
+ * if (!result.ok) return result.error;
+ * const lines = result.content.split("\n");
+ */
+export declare function readAndConcat(ctx: CommandContext, files: string[], options: {
+    cmdName: string;
+    allowStdinMarker?: boolean;
+}): Promise<{
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    error: ExecResult;
+}>;

package/dist/utils/glob.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared glob pattern matching utilities.
+ *
+ * Used by grep, find, and other commands that need glob matching.
+ */
+export interface MatchGlobOptions {
+    /** Case-insensitive matching */
+    ignoreCase?: boolean;
+    /** Strip surrounding quotes from pattern before matching */
+    stripQuotes?: boolean;
+}
+/**
+ * Match a filename against a glob pattern.
+ *
+ * Supports:
+ * - `*` matches any sequence of characters
+ * - `?` matches any single character
+ * - `[...]` character classes
+ *
+ * @param name - The filename to test
+ * @param pattern - The glob pattern
+ * @param options - Matching options
+ * @returns true if the name matches the pattern
+ */
+export declare function matchGlob(name: string, pattern: string, options?: MatchGlobOptions | boolean): boolean;

package/dist/vitest-setup.d.ts

@@ -0,0 +1 @@
+export {};