@jerryan/just-bash 3.5.0

package/dist/parser/lexer.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 interface LexerOptions {
+    /** Maximum heredoc size in bytes (default: 10MB) */
+    maxHeredocSize?: number;
+}
+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
+    FD_VARIABLE = "FD_VARIABLE",// {varname} before redirect operator
+    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;
+    /** Quote-removed value for a here-document delimiter token. */
+    heredocDelimiter?: string;
+    /** Whether a here-document content token ended at its delimiter. */
+    heredocTerminated?: boolean;
+}
+/**
+ * Error thrown when the lexer encounters invalid input
+ */
+export declare class LexerError extends Error {
+    line: number;
+    column: number;
+    constructor(message: string, line: number, column: number);
+}
+export declare function isReservedWordToken(type: TokenType): boolean;
+/**
+ * Lexer class
+ */
+export declare class Lexer {
+    private input;
+    private pos;
+    private line;
+    private column;
+    private tokens;
+    private pendingHeredocs;
+    private pendingHeredocDelimiterMode;
+    private dparenDepth;
+    private maxHeredocSize;
+    constructor(input: string, options?: LexerOptions);
+    /**
+     * Tokenize the entire input
+     */
+    tokenize(): Token[];
+    private skipWhitespace;
+    private nextToken;
+    /**
+     * Look ahead from position after (( to determine if this is nested subshells
+     * like ((cmd) || (cmd2)) rather than arithmetic like ((1+2)).
+     *
+     * Returns true if it looks like nested subshells (command invocation).
+     */
+    private looksLikeNestedSubshells;
+    private makeToken;
+    private readComment;
+    private readWord;
+    private readHeredocContent;
+    private readHeredocDelimiterToken;
+    /**
+     * 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;
+    /**
+     * Scan an extglob pattern starting at the opening parenthesis.
+     * Extglob patterns are: @(...), *(...), +(...), ?(...), !(...)
+     * The operator (@, *, +, ?, !) is already consumed; we start at the (.
+     * Returns the content including parentheses, or null if not a valid extglob.
+     */
+    private scanExtglobPattern;
+    /**
+     * Scan for FD variable syntax: {varname} immediately followed by a redirect operator.
+     * This is the bash 4.1+ feature where {fd}>file allocates an FD and stores it in variable.
+     * Returns the variable name and end position if found, null otherwise.
+     *
+     * Valid patterns:
+     * - {varname}>file, {varname}>>file, {varname}>|file
+     * - {varname}<file, {varname}<<word, {varname}<<<word
+     * - {varname}<>file
+     * - {varname}>&N, {varname}<&N
+     * - {varname}>&-, {varname}<&- (close FD)
+     */
+    private scanFdVariable;
+    /**
+     * Scan ahead from a $(( position to determine if it should be treated as
+     * $( ( subshell ) ) instead of $(( arithmetic )).
+     * This handles cases like:
+     *   echo $(( echo 1
+     *   echo 2
+     *   ) )
+     * which should be a command substitution containing a subshell, not arithmetic.
+     *
+     * @param startPos - position at the second ( (i.e., at input[startPos] === "(")
+     * @returns true if this is a subshell (closes with ) )), false if arithmetic (closes with )))
+     */
+    private dollarDparenIsSubshell;
+    /**
+     * Scan ahead from a (( position to determine if it closes with ) ) (nested subshells)
+     * or )) (arithmetic). We need to track paren depth and quotes to find the matching close.
+     * @param startPos - position after the (( (i.e., at the first char of content)
+     * @returns true if it closes with ) ) (space between parens), false otherwise
+     */
+    private dparenClosesWithSpacedParens;
+}

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

@@ -0,0 +1,85 @@
+/**
+ * Command and Arithmetic Substitution Parsing Helpers
+ *
+ * Contains pure string analysis functions and substitution parsing utilities
+ * extracted from the main parser.
+ */
+import { type CommandSubstitutionPart, type ProcessSubstitutionPart, type ScriptNode } from "../ast/types.js";
+/**
+ * Type for a parser factory function that creates new parser instances.
+ * Used to avoid circular dependencies.
+ */
+export type ParserFactory = () => {
+    parse(input: string): ScriptNode;
+};
+/**
+ * Type for an error reporting function.
+ */
+export type ErrorFn = (message: string) => never;
+/**
+ * Check if $(( at position `start` in `value` is a command substitution with nested
+ * subshell rather than arithmetic expansion. This uses similar logic to the lexer's
+ * dparenClosesWithSpacedParens but operates on a string within a word/expansion.
+ *
+ * The key heuristics are:
+ * 1. If it closes with `) )` (separated by whitespace or content), it's a subshell
+ * 2. If at depth 1 we see `||`, `&&`, or single `|`, it's a command context
+ * 3. If it closes with `))`, it's arithmetic
+ *
+ * @param value The string containing the expansion
+ * @param start Position of the `$` in `$((` (so `$((` is at start..start+2)
+ * @returns true if this should be parsed as command substitution, false for arithmetic
+ */
+export declare function isDollarDparenSubshell(value: string, start: number): boolean;
+/**
+ * Read a heredoc delimiter starting at `pos` (the first character after the
+ * `<<` / `<<-` operator and any leading blanks). Returns the delimiter after
+ * outer-word quote removal, plus metadata needed by both the lexer and nested
+ * substitution scanner. Syntax inside unexpanded `$(`, `<(`, and `>(` atoms
+ * remains literal.
+ *
+ * Quoting only controls whether the body is expanded, which is irrelevant to
+ * finding the substitution boundary, so `'EOF'`, `"EOF"`, and `\EOF` all yield
+ * the delimiter `EOF`.
+ */
+export declare function readHeredocDelimiter(value: string, pos: number): {
+    delim: string;
+    endPos: number;
+    quoted: boolean;
+    unclosedQuote: "'" | '"' | undefined;
+    unclosedSubstitution: boolean;
+};
+/**
+ * Parse a command substitution starting at the given position.
+ * Handles $(...) syntax with proper depth tracking for nested substitutions.
+ *
+ * @param value The string containing the substitution
+ * @param start Position of the `$` in `$(`
+ * @param createParser Factory function to create a new parser instance
+ * @param error Error reporting function
+ * @returns The parsed command substitution part and the ending index
+ */
+export declare function parseCommandSubstitutionFromString(value: string, start: number, createParser: ParserFactory, error: ErrorFn): {
+    part: CommandSubstitutionPart;
+    endIndex: number;
+};
+/** Parse process substitution syntax found inside a recursively parsed word fragment. */
+export declare function parseProcessSubstitutionFromString(value: string, start: number, createParser: ParserFactory, error: ErrorFn): {
+    part: ProcessSubstitutionPart;
+    endIndex: number;
+};
+/**
+ * Parse a backtick command substitution starting at the given position.
+ * Handles `...` syntax with proper escape processing.
+ *
+ * @param value The string containing the substitution
+ * @param start Position of the opening backtick
+ * @param inDoubleQuotes Whether the backtick is inside double quotes
+ * @param createParser Factory function to create a new parser instance
+ * @param error Error reporting function
+ * @returns The parsed command substitution part and the ending index
+ */
+export declare function parseBacktickSubstitutionFromString(value: string, start: number, inDoubleQuotes: boolean, createParser: ParserFactory, error: ErrorFn): {
+    part: CommandSubstitutionPart;
+    endIndex: number;
+};

package/dist/parser/parser.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 ProcessSubstitutionPart, type RedirectionNode, type ScriptNode, type StatementNode, type WordNode, type WordPart } from "../ast/types.js";
+import { type LexerOptions, type Token, TokenType } from "./lexer.js";
+import { ParseBudget, WordParseContext } from "./types.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 readonly parseBudget;
+    private readonly ownsParseBudget;
+    private _input;
+    private processLineState;
+    constructor(parseBudget?: ParseBudget);
+    /**
+     * 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;
+    withDepth<T>(callback: () => T): T;
+    /**
+     * 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;
+    getSourceLine(token?: Token): 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 parseTimePrefix;
+    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;
+    isWord(): boolean;
+    private isWordToken;
+    isProcessSubstitutionStart(offset?: number): boolean;
+    private currentTokenJoinsProcessSubstitution;
+    private isAdjacentWordToken;
+    parseWord(context?: WordParseContext): WordNode;
+    parseAdjacentWordParts(parts: WordPart[], previousEnd: number, context?: WordParseContext): 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;
+    private parseWordToken;
+    parseWordFromString(value: string, quoted?: boolean, singleQuoted?: boolean, isAssignment?: boolean, hereDoc?: boolean, noBraceExpansion?: boolean, regexPattern?: boolean, atWordStart?: boolean): WordNode;
+    parseCommandSubstitution(value: string, start: number): {
+        part: CommandSubstitutionPart;
+        endIndex: number;
+    };
+    parseProcessSubstitutionFromString(value: string, start: number): {
+        part: ProcessSubstitutionPart;
+        endIndex: number;
+    };
+    private parseProcessSubstitution;
+    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,40 @@
+/**
+ * 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_PARSER_DEPTH = 200;
+export declare enum WordParseContext {
+    Default = 0,
+    Assignment = 1,
+    NoBraceExpansion = 2,
+    Regex = 4
+}
+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);
+}
+/** Mutable limits shared by every parser created for one top-level source. */
+export declare class ParseBudget {
+    private iterations;
+    private tokens;
+    private depth;
+    reset(): void;
+    chargeIteration(line: number, column: number): void;
+    chargeTokens(count: number, line?: number, column?: number): void;
+    enter(line: number, column: number): () => void;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * 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";
+/** Lexer-level escapes in unquoted arithmetic subscripts need quote removal. */
+export declare const quoteRemoveEscapes: (value: string) => string;
+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,121 @@
+import type { Writable } from "node:stream";
+import { Bash, type JavaScriptConfig } from "../Bash.js";
+import type { CommandName } from "../commands/registry.js";
+import type { CustomCommand } from "../custom-commands.js";
+import type { IFileSystem } from "../fs/interface.js";
+import type { NetworkConfig, SecureFetch } 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;
+    /**
+     * Enable the python3/python commands. Disabled by default: Python adds
+     * security surface (arbitrary code execution via CPython). Forwarded to
+     * the underlying `Bash`.
+     */
+    python?: boolean;
+    /**
+     * Enable the js-exec command (sandboxed JavaScript via QuickJS). Accepts a
+     * boolean or a {@link JavaScriptConfig} (bootstrap code / `invokeTool`
+     * hook). Disabled by default. Forwarded to the underlying `Bash`.
+     */
+    javascript?: boolean | JavaScriptConfig;
+    /**
+     * Restrict the registered command set. When omitted, all built-in commands
+     * are available; pass a list to allow only those. Forwarded to the
+     * underlying `Bash`.
+     */
+    commands?: CommandName[];
+    /**
+     * Custom commands registered alongside the built-ins (these take precedence
+     * over built-ins with the same name). Forwarded to the underlying `Bash`.
+     */
+    customCommands?: CustomCommand[];
+    /**
+     * Custom secure fetch implementation used instead of one derived from
+     * `network`. Providing either `fetch` or `network` registers the network
+     * commands (curl, wget). Forwarded to the underlying `Bash`.
+     */
+    fetch?: SecureFetch;
+}
+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";