just-bash 1.0.0

package/dist/parser/lexer.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Lexer for Bash Scripts
+ *
+ * The lexer tokenizes input into a stream of tokens that the parser consumes.
+ * It handles:
+ * - Operators and delimiters
+ * - Words (with quoting rules)
+ * - Comments
+ * - Here-documents
+ * - Escape sequences
+ */
+export declare enum TokenType {
+    EOF = "EOF",
+    NEWLINE = "NEWLINE",
+    SEMICOLON = "SEMICOLON",
+    AMP = "AMP",// &
+    PIPE = "PIPE",// |
+    PIPE_AMP = "PIPE_AMP",// |&
+    AND_AND = "AND_AND",// &&
+    OR_OR = "OR_OR",// ||
+    BANG = "BANG",// !
+    LESS = "LESS",// <
+    GREAT = "GREAT",// >
+    DLESS = "DLESS",// <<
+    DGREAT = "DGREAT",// >>
+    LESSAND = "LESSAND",// <&
+    GREATAND = "GREATAND",// >&
+    LESSGREAT = "LESSGREAT",// <>
+    DLESSDASH = "DLESSDASH",// <<-
+    CLOBBER = "CLOBBER",// >|
+    TLESS = "TLESS",// <<<
+    AND_GREAT = "AND_GREAT",// &>
+    AND_DGREAT = "AND_DGREAT",// &>>
+    LPAREN = "LPAREN",// (
+    RPAREN = "RPAREN",// )
+    LBRACE = "LBRACE",// {
+    RBRACE = "RBRACE",// }
+    DSEMI = "DSEMI",// ;;
+    SEMI_AND = "SEMI_AND",// ;&
+    SEMI_SEMI_AND = "SEMI_SEMI_AND",// ;;&
+    DBRACK_START = "DBRACK_START",// [[
+    DBRACK_END = "DBRACK_END",// ]]
+    DPAREN_START = "DPAREN_START",// ((
+    DPAREN_END = "DPAREN_END",// ))
+    IF = "IF",
+    THEN = "THEN",
+    ELSE = "ELSE",
+    ELIF = "ELIF",
+    FI = "FI",
+    FOR = "FOR",
+    WHILE = "WHILE",
+    UNTIL = "UNTIL",
+    DO = "DO",
+    DONE = "DONE",
+    CASE = "CASE",
+    ESAC = "ESAC",
+    IN = "IN",
+    FUNCTION = "FUNCTION",
+    SELECT = "SELECT",
+    TIME = "TIME",
+    COPROC = "COPROC",
+    WORD = "WORD",
+    NAME = "NAME",// Valid variable name
+    NUMBER = "NUMBER",// For redirections like 2>&1
+    ASSIGNMENT_WORD = "ASSIGNMENT_WORD",// VAR=value
+    COMMENT = "COMMENT",
+    HEREDOC_CONTENT = "HEREDOC_CONTENT"
+}
+export interface Token {
+    type: TokenType;
+    value: string;
+    /** Original position in input */
+    start: number;
+    end: number;
+    line: number;
+    column: number;
+    /** For WORD tokens: quote information */
+    quoted?: boolean;
+    singleQuoted?: boolean;
+}
+/**
+ * Lexer class
+ */
+export declare class Lexer {
+    private input;
+    private pos;
+    private line;
+    private column;
+    private tokens;
+    private pendingHeredocs;
+    constructor(input: string);
+    /**
+     * Tokenize the entire input
+     */
+    tokenize(): Token[];
+    private skipWhitespace;
+    private nextToken;
+    private makeToken;
+    private readComment;
+    private readWord;
+    private readHeredocContent;
+    /**
+     * Register a here-document to be read after the next newline
+     */
+    addPendingHeredoc(delimiter: string, stripTabs: boolean, quoted: boolean): void;
+    /**
+     * Look ahead from current position to find the here-doc delimiter
+     * and register it as a pending here-doc
+     */
+    private registerHeredocFromLookahead;
+    /**
+     * Check if position is followed by word characters (not a word boundary).
+     * Used to determine if } should be literal or RBRACE token.
+     */
+    private isWordCharFollowing;
+    /**
+     * Read a word that starts with a brace expansion.
+     * Includes the brace expansion plus any suffix characters and additional brace expansions.
+     */
+    private readWordWithBraceExpansion;
+    /**
+     * Scan ahead to detect brace expansion pattern.
+     * Returns the full brace expansion string if found, null otherwise.
+     * Brace expansion must contain either:
+     * - A comma (e.g., {a,b,c})
+     * - A range with .. (e.g., {1..10})
+     */
+    private scanBraceExpansion;
+    /**
+     * Scan a literal brace word like {foo} (no comma, no range).
+     * Returns the literal string if found, null otherwise.
+     * This is used when {} contains something but it's not a valid brace expansion.
+     */
+    private scanLiteralBraceWord;
+}

package/dist/parser/parser.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 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;
+    /**
+     * Check parse iteration limit to prevent infinite loops
+     */
+    checkIterationLimit(): void;
+    /**
+     * Parse a bash script string
+     */
+    parse(input: string): 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
+     */
+    private checkUnexpectedToken;
+    parseStatement(): StatementNode | null;
+    private parsePipeline;
+    private parseCommand;
+    isWord(): boolean;
+    parseWord(): WordNode;
+    parseWordFromString(value: string, quoted?: boolean, singleQuoted?: boolean, isAssignment?: boolean, hereDoc?: 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;
+    };
+    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): ScriptNode;

package/dist/parser/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 REDIRECTION_TOKENS: Set<TokenType>;
+export declare const REDIRECTION_AFTER_NUMBER: 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,28 @@
+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 resultPromise;
+    constructor(bashEnv: Bash, cmdLine: string, cwd: string, env?: Record<string, string>, explicitCwd?: boolean);
+    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,60 @@
+import { Bash } from "../Bash.js";
+import type { IFileSystem } from "../fs-interface.js";
+import type { NetworkConfig } from "../network/index.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;
+}
+export interface WriteFilesInput {
+    [path: string]: string | {
+        content: string;
+        encoding?: "utf-8" | "base64";
+    };
+}
+export declare class Sandbox {
+    private bashEnv;
+    private constructor();
+    static create(opts?: SandboxOptions): Promise<Sandbox>;
+    runCommand(cmd: string, opts?: {
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<Command>;
+    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, SandboxOptions, WriteFilesInput, } from "./Sandbox.js";
+export { Command, Sandbox, } from "./Sandbox.js";

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+import type { IFileSystem } from "./fs-interface.js";
+import type { ExecutionLimits } from "./limits.js";
+import type { SecureFetch } from "./network/index.js";
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    /** The final environment variables after execution (only set by BashEnv.exec) */
+    env?: Record<string, string>;
+}
+/** Result from BashEnv.exec() - always includes env */
+export interface BashExecResult extends ExecResult {
+    env: Record<string, string>;
+}
+/** Options for exec calls within commands */
+export interface CommandExecOptions {
+    /** Environment variables to merge into the exec state */
+    env?: Record<string, string>;
+    /** Working directory for the exec */
+    cwd?: 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)
+ */
+export interface CommandContext {
+    /** Virtual filesystem interface for file operations */
+    fs: IFileSystem;
+    /** Current working directory */
+    cwd: string;
+    /** Environment variables */
+    env: Record<string, string>;
+    /** Standard input content */
+    stdin: string;
+    /**
+     * Execution limits configuration.
+     * Available when running commands via BashEnv interpreter.
+     */
+    limits?: Required<ExecutionLimits>;
+    /**
+     * Execute a subcommand (e.g., for `xargs`, `bash -c`).
+     * Available when running commands via BashEnv interpreter.
+     */
+    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>;
+}
+export interface Command {
+    name: string;
+    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/file-reader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * File reading utilities for command implementations.
+ *
+ * Provides common patterns for reading from files or stdin.
+ */
+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;
+}
+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;