@demicodes/just-bash 3.0.1-demi.2

package/dist/parser/parser.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Recursive Descent Parser for Bash Scripts
+ *
+ * This parser consumes tokens from the lexer and produces an AST.
+ * It follows the bash grammar structure for correctness.
+ *
+ * Grammar (simplified):
+ *   script       ::= statement*
+ *   statement    ::= pipeline ((&&|'||') pipeline)*  [&]
+ *   pipeline     ::= [!] command (| command)*
+ *   command      ::= simple_command | compound_command | function_def
+ *   simple_cmd   ::= (assignment)* [word] (word)* (redirection)*
+ *   compound_cmd ::= if | for | while | until | case | subshell | group | (( | [[
+ */
+import { type ArithmeticExpansionPart, type ArithmeticExpressionNode, type CommandSubstitutionPart, type RedirectionNode, type ScriptNode, type StatementNode, type WordNode } from "../ast/types.js";
+import { type LexerOptions, type Token, TokenType } from "./lexer.js";
+export type { ParseError } from "./types.js";
+export { ParseException } from "./types.js";
+/**
+ * Parser class - transforms tokens into AST
+ */
+export declare class Parser {
+    private tokens;
+    private pos;
+    private pendingHeredocs;
+    private parseIterations;
+    private parseDepth;
+    private _input;
+    /**
+     * Get the raw input string being parsed.
+     * Used by conditional-parser for extracting exact whitespace in regex patterns.
+     */
+    getInput(): string;
+    /**
+     * Check parse iteration limit to prevent infinite loops
+     */
+    checkIterationLimit(): void;
+    /**
+     * Increment parse depth and check limit to prevent stack overflow
+     * from deeply nested constructs. Returns a function to decrement depth.
+     */
+    enterDepth(): () => void;
+    /**
+     * Parse a bash script string
+     */
+    parse(input: string, options?: LexerOptions): ScriptNode;
+    /**
+     * Parse from pre-tokenized input
+     */
+    parseTokens(tokens: Token[]): ScriptNode;
+    current(): Token;
+    peek(offset?: number): Token;
+    advance(): Token;
+    getPos(): number;
+    /**
+     * Check if current token matches any of the given types.
+     * Optimized to avoid array allocation for common cases (1-4 args).
+     */
+    check(t1: TokenType, t2?: TokenType, t3?: TokenType, t4?: TokenType, ...rest: TokenType[]): boolean;
+    expect(type: TokenType, message?: string): Token;
+    error(message: string): never;
+    skipNewlines(): void;
+    skipSeparators(includeCaseTerminators?: boolean): void;
+    addPendingHeredoc(redirect: RedirectionNode, delimiter: string, stripTabs: boolean, quoted: boolean): void;
+    private processHeredocs;
+    isStatementEnd(): boolean;
+    private isCommandStart;
+    private parseScript;
+    /**
+     * Check for unexpected tokens that can't appear at statement start.
+     * Returns a deferred error statement for tokens that should cause errors
+     * at execution time rather than parse time (to match bash's incremental behavior).
+     */
+    private checkUnexpectedToken;
+    parseStatement(): StatementNode | null;
+    private parsePipeline;
+    private parseCommand;
+    /**
+     * Scan ahead from current DPAREN_START to determine if it closes with ) )
+     * (two separate RPAREN tokens) or )) (DPAREN_END token).
+     * Returns true if it closes with ) ) (nested subshells case).
+     */
+    private dparenClosesWithSpacedParens;
+    /**
+     * Parse (( ... ) ) as nested subshells when we know it closes with ) ).
+     * We've already determined via dparenClosesWithSpacedParens() that this
+     * DPAREN_START should be treated as two LPAREN tokens.
+     */
+    private parseNestedSubshellsFromDparen;
+    private errorExpectedCommand;
+    isWord(): boolean;
+    parseWord(): WordNode;
+    /**
+     * Parse a word without brace expansion (for [[ ]] conditionals).
+     * In bash, brace expansion does not occur inside [[ ]].
+     */
+    parseWordNoBraceExpansion(): WordNode;
+    /**
+     * Parse a word for regex patterns (in [[ =~ ]]).
+     * All escaped characters create Escaped nodes so the backslash is preserved
+     * for the regex engine. For example, \$ creates Escaped("$") which becomes \$
+     * in the final regex pattern.
+     */
+    parseWordForRegex(): WordNode;
+    parseWordFromString(value: string, quoted?: boolean, singleQuoted?: boolean, isAssignment?: boolean, hereDoc?: boolean, noBraceExpansion?: boolean, regexPattern?: boolean): WordNode;
+    parseCommandSubstitution(value: string, start: number): {
+        part: CommandSubstitutionPart;
+        endIndex: number;
+    };
+    parseBacktickSubstitution(value: string, start: number, 
+    /** Whether the backtick is inside double quotes */
+    inDoubleQuotes?: boolean): {
+        part: CommandSubstitutionPart;
+        endIndex: number;
+    };
+    /**
+     * Check if $(( at position `start` in `value` is a command substitution with nested
+     * subshell rather than arithmetic expansion.
+     */
+    isDollarDparenSubshell(value: string, start: number): boolean;
+    parseArithmeticExpansion(value: string, start: number): {
+        part: ArithmeticExpansionPart;
+        endIndex: number;
+    };
+    private parseArithmeticCommand;
+    private parseConditionalCommand;
+    private parseFunctionDef;
+    private parseCompoundCommandBody;
+    parseCompoundList(): StatementNode[];
+    parseOptionalRedirections(): RedirectionNode[];
+    parseArithmeticExpression(input: string): ArithmeticExpressionNode;
+}
+/**
+ * Convenience function to parse a bash script
+ */
+export declare function parse(input: string, options?: LexerOptions): ScriptNode;

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,248 @@
+import type { ByteString } from "./encoding.js";
+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>;
+    /**
+     * Explicit metadata for what shape `stdout` is in. The pipeline + redirect
+     * layers consult this instead of guessing from string contents:
+     *
+     *   - `"text"`: `stdout` is JS Unicode text. The pipeline UTF-8 encodes it
+     *     before handing it to the next command's stdin; redirects write it
+     *     as UTF-8.
+     *   - `"bytes"`: `stdout` is a latin1-shaped byte buffer (each char = one
+     *     byte). The pipeline forwards the bytes verbatim; redirects write
+     *     them as binary.
+     *
+     * Producers should set this via `textOutput()` / `bytesOutput()` from
+     * `encoding.ts` rather than poking the raw flag. Absent values fall back
+     * to the legacy `stdoutEncoding` heuristic for back-compat with older
+     * commands that haven't been migrated yet.
+     */
+    stdoutKind?: "text" | "bytes";
+    /**
+     * Legacy alias for `stdoutKind: "bytes"`. Older commands set this to
+     * `"binary"` to mark binary output. New code should prefer `stdoutKind`.
+     */
+    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;
+    /**
+     * Shape of {@link stdin}:
+     *   - `"text"` (default): JS Unicode text. UTF-8 encoded into bytes
+     *     before reaching the subcommand, so byte consumers (`wc -c`,
+     *     `base64`, `md5sum`) inside the script see real UTF-8 bytes.
+     *   - `"bytes"`: a latin1-shaped byte buffer (each char = one byte,
+     *     e.g. from `Buffer.from(...).toString("latin1")`). Forwarded
+     *     verbatim — useful for piping raw binary into commands like
+     *     `gzip -d`.
+     */
+    stdinKind?: "text" | "bytes";
+    /**
+     * 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 as a byte buffer. Opaque on purpose — see `encoding.ts`.
+     *
+     * Pipelines carry bytes (a previous command's stdout becomes this stdin).
+     * Choose a conversion at the use site:
+     *   - `latin1FromBytes(ctx.stdin)` to forward bytes unchanged (cat, head,
+     *     tee, base64 -d, gzip, ...).
+     *   - `decodeBytesToUtf8(ctx.stdin)` to interpret as UTF-8 text (jq, sed,
+     *     grep, awk, parsers, code execution, char-position math, ...).
+     * Mixing the two — calling string methods on a latin1 byte buffer that
+     * actually holds UTF-8 — is the bug class this type prevents.
+     */
+    stdin: ByteString;
+    /**
+     * 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;
+    /**
+     * Tool invoker hook. When present, js-exec sets up a `tools` proxy that
+     * routes calls through this callback. Receives `(path, argsJson)` and
+     * returns a JSON result string.
+     */
+    invokeTool?: (path: string, argsJson: string) => Promise<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;
+    /**
+     * Whether this registered command consumes stdin when group/pipeline stdin is
+     * supplied implicitly. Commands like echo do not consume it; cat-like or
+     * host-extension commands with stdin-backed arguments usually do.
+     */
+    consumesStdin?: 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;