@jerryan/just-bash 3.5.0

package/dist/interpreter/helpers/file-tests.d.ts

@@ -0,0 +1,33 @@
+import type { InterpreterContext } from "../types.js";
+/**
+ * File test operators supported by bash
+ * Unary operators that test file properties
+ */
+declare const FILE_TEST_OPERATORS: readonly ["-e", "-a", "-f", "-d", "-r", "-w", "-x", "-s", "-L", "-h", "-k", "-g", "-u", "-G", "-O", "-b", "-c", "-p", "-S", "-t", "-N"];
+export type FileTestOperator = (typeof FILE_TEST_OPERATORS)[number];
+export declare function isFileTestOperator(op: string): op is FileTestOperator;
+/**
+ * Evaluates a file test operator (-e, -f, -d, etc.) against a path.
+ * Returns a boolean result.
+ *
+ * @param ctx - Interpreter context with filesystem access
+ * @param operator - The file test operator (e.g., "-f", "-d", "-e")
+ * @param operand - The path to test (will be resolved relative to cwd)
+ */
+export declare function evaluateFileTest(ctx: InterpreterContext, operator: string, operand: string): Promise<boolean>;
+/**
+ * Binary file test operators for comparing two files
+ */
+declare const BINARY_FILE_TEST_OPERATORS: readonly ["-nt", "-ot", "-ef"];
+export type BinaryFileTestOperator = (typeof BINARY_FILE_TEST_OPERATORS)[number];
+export declare function isBinaryFileTestOperator(op: string): op is BinaryFileTestOperator;
+/**
+ * Evaluates a binary file test operator (-nt, -ot, -ef) comparing two files.
+ *
+ * @param ctx - Interpreter context with filesystem access
+ * @param operator - The operator (-nt, -ot, -ef)
+ * @param left - Left operand (file path)
+ * @param right - Right operand (file path)
+ */
+export declare function evaluateBinaryFileTest(ctx: InterpreterContext, operator: string, left: string, right: string): Promise<boolean>;
+export {};

package/dist/interpreter/helpers/ifs.d.ts

@@ -0,0 +1,104 @@
+/**
+ * IFS (Internal Field Separator) Handling
+ *
+ * Centralized utilities for IFS-based word splitting used by:
+ * - Word expansion (unquoted variable expansion)
+ * - read builtin
+ * - ${!prefix*} and ${!arr[*]} expansions
+ */
+/**
+ * Get the effective IFS value from environment.
+ * Returns DEFAULT_IFS if IFS is undefined, or the actual value (including empty string).
+ */
+export declare function getIfs(env: Map<string, string>): string;
+/**
+ * Check if IFS is set to empty string (disables word splitting).
+ */
+export declare function isIfsEmpty(env: Map<string, string>): boolean;
+/**
+ * Check if IFS contains only whitespace characters (space, tab, newline).
+ * This affects how empty fields are handled in $@ and $* expansion.
+ * When IFS has non-whitespace chars, empty params are preserved.
+ * When IFS has only whitespace, empty params are dropped.
+ */
+export declare function isIfsWhitespaceOnly(env: Map<string, string>): boolean;
+/**
+ * Build a regex-safe pattern from IFS characters for use in character classes.
+ * E.g., for IFS=" \t\n", returns " \\t\\n" (escaped for [pattern] use)
+ */
+export declare function buildIfsCharClassPattern(ifs: string): string;
+/**
+ * Get the first character of IFS (used for joining with $* and ${!prefix*}).
+ * Returns space if IFS is undefined, empty string if IFS is empty.
+ */
+export declare function getIfsSeparator(env: Map<string, string>): string;
+/**
+ * Advanced IFS splitting for the read builtin with proper whitespace/non-whitespace handling.
+ *
+ * IFS has two types of characters:
+ * - Whitespace (space, tab, newline): Multiple consecutive ones are collapsed,
+ *   leading/trailing are stripped
+ * - Non-whitespace (like 'x', ':'): Create empty fields when consecutive,
+ *   trailing ones preserved (except the final delimiter)
+ *
+ * @param value - String to split
+ * @param ifs - IFS characters to split on
+ * @param maxSplit - Maximum number of splits (for read with multiple vars, the last gets the rest)
+ * @param raw - If true, backslash escaping is disabled (like read -r)
+ * @returns Object with words array and wordStarts array
+ */
+export declare function splitByIfsForRead(value: string, ifs: string, maxArrayElements: number, maxSplit?: number, raw?: boolean): {
+    words: string[];
+    wordStarts: number[];
+};
+/**
+ * IFS splitting for word expansion (unquoted $VAR, $*, etc.).
+ *
+ * Key differences from splitByIfsForRead:
+ * - Trailing non-whitespace delimiter does NOT create an empty field
+ * - No maxSplit concept (always splits fully)
+ * - No backslash escape handling
+ *
+ * @param value - String to split
+ * @param ifs - IFS characters to split on
+ * @returns Array of words after splitting
+ */
+/**
+ * Result of splitByIfsForExpansionEx with leading/trailing delimiter info.
+ */
+export interface IfsExpansionSplitResult {
+    words: string[];
+    /** True if the value started with an IFS whitespace delimiter (affects joining with preceding text) */
+    hadLeadingDelimiter: boolean;
+    /** True if the value ended with an IFS delimiter (affects joining with subsequent text) */
+    hadTrailingDelimiter: boolean;
+}
+/**
+ * Extended IFS splitting that tracks trailing delimiters.
+ * This is needed for proper word boundary handling when literal text follows an expansion.
+ * For example, in `-$x-` where `x='a b c '`, the trailing space means the final `-`
+ * should become a separate word, not join with `c`.
+ */
+export declare function splitByIfsForExpansionEx(value: string, ifs: string, maxArrayElements: number): IfsExpansionSplitResult;
+export declare function splitByIfsForExpansion(value: string, ifs: string, maxArrayElements: number): string[];
+/**
+ * Strip trailing IFS from the last variable in read builtin.
+ *
+ * Bash behavior:
+ * 1. Strip trailing IFS whitespace characters (but NOT if they're escaped by backslash)
+ * 2. If there's a single trailing IFS non-whitespace character, strip it ONLY IF
+ *    there are no other non-ws IFS chars in the content (excluding the trailing one)
+ *
+ * Examples with IFS="x ":
+ * - "ax  " -> "a" (trailing spaces stripped, then trailing single x stripped because no other x)
+ * - "ax" -> "a" (trailing single x stripped because no other x in remaining content)
+ * - "axx" -> "axx" (two trailing x's, so don't strip - there's another x)
+ * - "ax  x" -> "ax  x" (trailing x NOT stripped because there's an x earlier)
+ * - "bx" -> "b" (trailing x stripped, no other x)
+ * - "a\ " -> "a " (backslash-escaped space is NOT stripped)
+ *
+ * @param value - String to strip (raw, before backslash processing)
+ * @param ifs - IFS characters
+ * @param raw - If true, backslash escaping is disabled
+ */
+export declare function stripTrailingIfsWhitespace(value: string, ifs: string, raw?: boolean): string;

package/dist/interpreter/helpers/loop.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Loop Error Handling Helpers
+ *
+ * Consolidates the repeated error handling logic used in all loop constructs
+ * (for, c-style for, while, until).
+ */
+export type LoopAction = "break" | "continue" | "rethrow" | "error";
+export interface LoopErrorResult {
+    action: LoopAction;
+    stdout: string;
+    stderr: string;
+    exitCode?: number;
+    error?: unknown;
+}
+/**
+ * Handle errors thrown during loop body execution.
+ *
+ * @param error - The caught error
+ * @param stdout - Current accumulated stdout
+ * @param stderr - Current accumulated stderr
+ * @param loopDepth - Current loop nesting depth from ctx.state.loopDepth
+ * @returns Result indicating what action the loop should take
+ */
+export declare function handleLoopError(error: unknown, stdout: string, stderr: string, loopDepth: number): LoopErrorResult;

package/dist/interpreter/helpers/nameref.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Nameref (declare -n) support
+ *
+ * Namerefs are variables that reference other variables by name.
+ * When a nameref is accessed, it transparently dereferences to the target variable.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Check if a variable is a nameref
+ */
+export declare function isNameref(ctx: InterpreterContext, name: string): boolean;
+/**
+ * Mark a variable as a nameref
+ */
+export declare function markNameref(ctx: InterpreterContext, name: string): void;
+/**
+ * Remove the nameref attribute from a variable
+ */
+export declare function unmarkNameref(ctx: InterpreterContext, name: string): void;
+/**
+ * Mark a nameref as having an "invalid" target at creation time.
+ * Invalid namerefs always read/write their value directly, never resolving.
+ */
+export declare function markNamerefInvalid(ctx: InterpreterContext, name: string): void;
+/**
+ * Mark a nameref as "bound" - meaning its target existed at creation time.
+ * This is kept for tracking purposes but is currently not used in resolution.
+ */
+export declare function markNamerefBound(ctx: InterpreterContext, name: string): void;
+/**
+ * Check if a name refers to a valid, existing variable or array element.
+ * Used to determine if a nameref target is "real" or just a stored value.
+ */
+export declare function targetExists(ctx: InterpreterContext, target: string): boolean;
+/**
+ * Resolve a nameref chain to the final variable name.
+ * Returns the original name if it's not a nameref.
+ * Detects circular references and returns undefined.
+ *
+ * @param ctx - The interpreter context
+ * @param name - The variable name to resolve
+ * @param maxDepth - Maximum chain depth to prevent infinite loops (default 100)
+ * @returns The resolved variable name, or undefined if circular reference detected
+ */
+export declare function resolveNameref(ctx: InterpreterContext, name: string, maxDepth?: number): string | undefined;
+/**
+ * Get the target name of a nameref (what it points to).
+ * Returns the variable's value if it's a nameref, undefined otherwise.
+ */
+export declare function getNamerefTarget(ctx: InterpreterContext, name: string): string | undefined;
+/**
+ * Resolve a nameref for assignment purposes.
+ * Unlike resolveNameref, this will resolve to the target variable name
+ * even if the target doesn't exist yet (allowing creation).
+ *
+ * @param ctx - The interpreter context
+ * @param name - The variable name to resolve
+ * @param valueBeingAssigned - The value being assigned (needed for empty nameref handling)
+ * @param maxDepth - Maximum chain depth to prevent infinite loops
+ * @returns
+ * - undefined if circular reference detected
+ * - null if the nameref is empty and value is not an existing variable (skip assignment)
+ * - The resolved target name otherwise (may be the nameref itself if target is invalid)
+ */
+export declare function resolveNamerefForAssignment(ctx: InterpreterContext, name: string, valueBeingAssigned?: string, maxDepth?: number): string | null | undefined;

package/dist/interpreter/helpers/numeric-compare.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Numeric comparison helper for conditionals.
+ * Handles -eq, -ne, -lt, -le, -gt, -ge operators.
+ */
+export type NumericOp = "-eq" | "-ne" | "-lt" | "-le" | "-gt" | "-ge";
+/**
+ * Check if an operator is a numeric comparison operator.
+ */
+export declare function isNumericOp(op: string): op is NumericOp;
+/**
+ * Compare two numbers using a numeric comparison operator.
+ */
+export declare function compareNumeric(op: NumericOp, left: number, right: number): boolean;

package/dist/interpreter/helpers/quoting.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shell value quoting utilities
+ *
+ * Provides functions for quoting values in shell output format,
+ * used by both `set` and `declare/typeset` builtins.
+ */
+/**
+ * Quote a value for shell output (used by 'set' and 'typeset' with no args)
+ * Matches bash's output format:
+ * - No quotes for simple alphanumeric values
+ * - Single quotes for values with spaces or shell metacharacters
+ * - $'...' quoting for values with control characters
+ */
+export declare function quotedValueByteLength(value: string): number;
+export declare function quoteValue(value: string): string;
+/**
+ * Quote a value for array element output
+ * Uses $'...' for control characters, double quotes otherwise
+ */
+export declare function quotedArrayValueByteLength(value: string): number;
+export declare function quoteArrayValue(value: string): string;
+/**
+ * Quote a value for declare -p output
+ * Uses $'...' for control characters, double quotes otherwise
+ */
+export declare function quoteDeclareValue(value: string): string;

package/dist/interpreter/helpers/readonly.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Readonly and export variable helpers.
+ *
+ * Consolidates readonly and export variable logic used in declare, export, local, etc.
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Mark a variable as readonly.
+ */
+export declare function markReadonly(ctx: InterpreterContext, name: string): void;
+/**
+ * Check if a variable is readonly.
+ */
+export declare function isReadonly(ctx: InterpreterContext, name: string): boolean;
+/**
+ * Check if a variable is readonly and throw an error if so.
+ * Returns null if the variable is not readonly (can be modified).
+ *
+ * Assigning to a readonly variable is a fatal error that stops script execution.
+ * This matches the behavior of dash, mksh, ash, and bash in POSIX mode.
+ * (Note: bash in non-POSIX mode has a bug where multi-line readonly assignment
+ * continues execution, but one-line still stops. We always stop.)
+ *
+ * @param ctx - Interpreter context
+ * @param name - Variable name
+ * @param command - Command name for error message (default: "bash")
+ * @returns null if variable is not readonly (can be modified)
+ * @throws ExitError if variable is readonly
+ */
+export declare function checkReadonlyError(ctx: InterpreterContext, name: string, command?: string): ExecResult | null;
+/**
+ * Mark a variable as exported.
+ *
+ * If we're inside a local scope and the variable is local (exists in the
+ * current scope), track it as a locally-exported variable. When the scope
+ * is popped, the export attribute will be removed if it wasn't exported
+ * before entering the function.
+ */
+export declare function markExported(ctx: InterpreterContext, name: string): void;
+/**
+ * Remove the export attribute from a variable.
+ * The variable value is preserved, just no longer exported to child processes.
+ */
+export declare function unmarkExported(ctx: InterpreterContext, name: string): void;

package/dist/interpreter/helpers/regex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Regex helper functions for the interpreter.
+ */
+/**
+ * Escape a string for use as a literal in a regex pattern.
+ * All regex special characters are escaped.
+ */
+export declare function escapeRegex(str: string): string;

package/dist/interpreter/helpers/result.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ExecResult factory functions for cleaner code.
+ *
+ * These helpers reduce verbosity and improve readability when
+ * constructing ExecResult objects throughout the interpreter.
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * A successful result with no output.
+ * Use this for commands that succeed silently.
+ */
+export declare const OK: ExecResult;
+/**
+ * Create a successful result with optional stdout.
+ *
+ * @param stdout - Output to include (default: "")
+ * @returns ExecResult with exitCode 0
+ */
+export declare function success(stdout?: string): ExecResult;
+/**
+ * Create a failure result with stderr message.
+ *
+ * @param stderr - Error message to include
+ * @param exitCode - Exit code (default: 1)
+ * @returns ExecResult with the specified exitCode
+ */
+export declare function failure(stderr: string, exitCode?: number): ExecResult;
+/**
+ * Create a result with all fields specified.
+ *
+ * @param stdout - Standard output
+ * @param stderr - Standard error
+ * @param exitCode - Exit code
+ * @returns ExecResult with all fields
+ */
+export declare function result(stdout: string, stderr: string, exitCode: number): ExecResult;
+/**
+ * Convert a boolean test result to an ExecResult.
+ * Useful for test/conditional commands where true = exit 0, false = exit 1.
+ *
+ * @param passed - Boolean test result
+ * @returns ExecResult with exitCode 0 if passed, 1 otherwise
+ */
+export declare function testResult(passed: boolean): ExecResult;
+/**
+ * Throw an ExecutionLimitError for execution limits (recursion, iterations, commands).
+ *
+ * @param message - Error message describing the limit exceeded
+ * @param limitType - Type of limit exceeded
+ * @param stdout - Accumulated stdout to include
+ * @param stderr - Accumulated stderr to include
+ * @throws ExecutionLimitError always
+ */
+export declare function throwExecutionLimit(message: string, limitType: "recursion" | "iterations" | "commands" | "string_length" | "glob_operations" | "substitution_depth" | "output_size" | "file_descriptors", stdout?: string, stderr?: string): never;
+/**
+ * Check file descriptor count against the limit before adding a new one.
+ * Throws ExecutionLimitError if the limit would be exceeded.
+ */
+export declare function checkFdLimit(ctx: InterpreterContext): void;

package/dist/interpreter/helpers/shell-constants.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shell Constants
+ *
+ * Constants for shell builtins, keywords, and POSIX special builtins.
+ */
+/**
+ * POSIX special built-in commands.
+ * In POSIX mode, these have special behaviors:
+ * - Prefix assignments persist after the command
+ * - Cannot be redefined as functions
+ * - Errors may be fatal
+ */
+export declare const POSIX_SPECIAL_BUILTINS: Set<string>;
+/**
+ * Check if a command name is a POSIX special built-in
+ */
+export declare function isPosixSpecialBuiltin(name: string): boolean;
+/**
+ * Shell keywords (for type, command -v, etc.)
+ */
+export declare const SHELL_KEYWORDS: Set<string>;
+/**
+ * Shell builtins (for type, command -v, builtin, etc.)
+ */
+export declare const SHELL_BUILTINS: Set<string>;
+/**
+ * Names in the builtin display sets that have NO implementation: dispatch
+ * has no handler for them, so at runtime they fall through to external
+ * resolution and fail with "command not found" (exit 127). Real bash
+ * implements these; just-bash does not (yet).
+ *
+ * Membership in POSIX_SPECIAL_BUILTINS / SHELL_BUILTINS is about DISPLAY
+ * (type, command -v) and POSIX mode behavior — not about resolvability.
+ * Static analysis (Bash.analyzeCommands) subtracts this set so its
+ * results match dispatch. Keep this honest: the parity test in
+ * command-analysis.test.ts runs every display-set name through both
+ * runtime dispatch and analysis and fails on any divergence — both when
+ * a name here gets implemented (remove it) and when a new unimplemented
+ * name joins a display set (add it).
+ */
+export declare const UNIMPLEMENTED_BUILTIN_NAMES: ReadonlySet<string>;

package/dist/interpreter/helpers/shellopts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SHELLOPTS and BASHOPTS variable helpers.
+ *
+ * SHELLOPTS is a colon-separated list of enabled shell options from `set -o`.
+ * BASHOPTS is a colon-separated list of enabled bash-specific options from `shopt`.
+ */
+import type { InterpreterContext, ShellOptions, ShoptOptions } from "../types.js";
+/**
+ * Build the SHELLOPTS string from current shell options.
+ * Returns a colon-separated list of enabled options (alphabetically sorted).
+ * Includes always-on options like braceexpand, hashall, interactive-comments.
+ */
+export declare function buildShellopts(options: ShellOptions): string;
+/**
+ * Update the SHELLOPTS environment variable to reflect current shell options.
+ * Should be called whenever shell options change (via set -o or shopt -o).
+ */
+export declare function updateShellopts(ctx: InterpreterContext): void;
+/**
+ * Build the BASHOPTS string from current shopt options.
+ * Returns a colon-separated list of enabled options (alphabetically sorted).
+ */
+export declare function buildBashopts(shoptOptions: ShoptOptions): string;
+/**
+ * Update the BASHOPTS environment variable to reflect current shopt options.
+ * Should be called whenever shopt options change.
+ */
+export declare function updateBashopts(ctx: InterpreterContext): void;

package/dist/interpreter/helpers/string-compare.d.ts

@@ -0,0 +1,24 @@
+/**
+ * String comparison helpers for conditionals.
+ *
+ * Consolidates string comparison logic (=, ==, !=) used in:
+ * - [[ ]] conditional expressions (with optional pattern matching)
+ * - test/[ ] command (literal comparison only)
+ */
+export type StringCompareOp = "=" | "==" | "!=";
+/**
+ * Check if an operator is a string comparison operator.
+ */
+export declare function isStringCompareOp(op: string): op is StringCompareOp;
+/**
+ * Compare two strings using the specified operator.
+ *
+ * @param op - The comparison operator (=, ==, !=)
+ * @param left - Left operand
+ * @param right - Right operand
+ * @param usePattern - If true, use glob pattern matching for equality (default: false)
+ * @param nocasematch - If true, use case-insensitive comparison (default: false)
+ * @param extglob - If true, enable extended glob patterns @(), *(), +(), ?(), !() (default: false)
+ * @returns True if the comparison succeeds
+ */
+export declare function compareStrings(op: StringCompareOp, left: string, right: string, usePattern?: boolean, nocasematch?: boolean, extglob?: boolean, maxPatternDepth?: number): boolean;

package/dist/interpreter/helpers/string-tests.d.ts

@@ -0,0 +1,13 @@
+/**
+ * String test helper for conditionals.
+ * Handles -z (empty) and -n (non-empty) operators.
+ */
+export type StringTestOp = "-z" | "-n";
+/**
+ * Check if an operator is a string test operator.
+ */
+export declare function isStringTestOp(op: string): op is StringTestOp;
+/**
+ * Evaluate a string test operator.
+ */
+export declare function evaluateStringTest(op: StringTestOp, value: string): boolean;

package/dist/interpreter/helpers/variable-tests.d.ts

@@ -0,0 +1,9 @@
+import type { InterpreterContext } from "../types.js";
+/**
+ * Evaluates the -v (variable is set) test.
+ * Handles both simple variables and array element access with negative indices.
+ *
+ * @param ctx - Interpreter context with environment variables
+ * @param operand - The variable name to test, may include array subscript (e.g., "arr[0]", "arr[-1]")
+ */
+export declare function evaluateVariableTest(ctx: InterpreterContext, operand: string): Promise<boolean>;

package/dist/interpreter/helpers/word-matching.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Interpreter Utility Functions
+ *
+ * Standalone helper functions used by the interpreter.
+ */
+import type { WordNode } from "../../ast/types.js";
+/**
+ * Check if a WordNode is a literal match for any of the given strings.
+ * Returns true only if the word is a single literal (no expansions, no quoting)
+ * that matches one of the target strings.
+ *
+ * This is used to detect assignment builtins at "parse time" - bash determines
+ * whether a command is export/declare/etc based on the literal token, not the
+ * runtime value after expansion.
+ */
+export declare function isWordLiteralMatch(word: WordNode, targets: string[]): boolean;

package/dist/interpreter/helpers/word-parts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Word Part Helper Functions
+ *
+ * Provides common operations on WordPart types to eliminate duplication
+ * across expansion.ts and word-parser.ts.
+ */
+import type { WordPart } from "../../ast/types.js";
+/**
+ * Get the literal string value from a word part.
+ * Returns the value for Literal, SingleQuoted, and Escaped parts.
+ * Returns null for complex parts that require expansion.
+ */
+export declare function getLiteralValue(part: WordPart): string | null;
+/**
+ * Check if a word part is "quoted" - meaning glob characters should be treated literally.
+ * A part is quoted if it is:
+ * - SingleQuoted
+ * - Escaped
+ * - DoubleQuoted (entirely quoted)
+ * - Literal with empty value (doesn't affect quoting)
+ */
+export declare function isQuotedPart(part: WordPart): boolean;

package/dist/interpreter/helpers/xtrace.d.ts

@@ -0,0 +1,18 @@
+/**
+ * xtrace (set -x) helper functions
+ *
+ * Handles trace output generation when xtrace option is enabled.
+ * PS4 variable controls the prefix (default "+ ").
+ * PS4 is expanded (variable substitution) before each trace line.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Generate xtrace output for a simple command.
+ * Returns the trace line to be added to stderr.
+ */
+export declare function traceSimpleCommand(ctx: InterpreterContext, commandName: string, args: string[]): Promise<string>;
+/**
+ * Generate xtrace output for an assignment.
+ * Returns the trace line to be added to stderr.
+ */
+export declare function traceAssignment(ctx: InterpreterContext, name: string, value: string): Promise<string>;

package/dist/interpreter/index.d.ts

@@ -0,0 +1,3 @@
+export type { InterpreterOptions } from "./interpreter.js";
+export { Interpreter } from "./interpreter.js";
+export type { InterpreterContext, InterpreterState, ShellOptions, } from "./types.js";

package/dist/interpreter/interpreter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Interpreter - AST Execution Engine
+ *
+ * Main interpreter class that executes bash AST nodes.
+ * Delegates to specialized modules for:
+ * - Word expansion (expansion.ts)
+ * - Arithmetic evaluation (arithmetic.ts)
+ * - Conditional evaluation (conditionals.ts)
+ * - Built-in commands (builtins.ts)
+ * - Redirections (redirections.ts)
+ */
+import type { ScriptNode } from "../ast/types.js";
+import type { ExecutionScope } from "../execution-scope.js";
+import type { IFileSystem } from "../fs/interface.js";
+import type { ExecutionLimits } from "../limits.js";
+import type { SecureFetch } from "../network/index.js";
+import type { CommandRegistry, ExecResult, FeatureCoverageWriter, TraceCallback } from "../types.js";
+import type { InterpreterExecOptions, InterpreterState } from "./types.js";
+export type { InterpreterContext, InterpreterState } from "./types.js";
+export interface InterpreterOptions {
+    fs: IFileSystem;
+    commands: CommandRegistry;
+    limits: Required<ExecutionLimits>;
+    executionScope: ExecutionScope;
+    exec: (script: string, options?: InterpreterExecOptions, stdinAlreadyAccounted?: boolean) => Promise<ExecResult>;
+    /** Optional secure fetch function for network-enabled commands */
+    fetch?: SecureFetch;
+    /** Optional sleep function for testing with mock clocks */
+    sleep?: (ms: number) => Promise<void>;
+    /** Optional trace callback for performance profiling */
+    trace?: TraceCallback;
+    /** Optional feature coverage writer for fuzzing instrumentation */
+    coverage?: FeatureCoverageWriter;
+    /**
+     * When true, fail closed if execution occurs outside defense async context.
+     */
+    requireDefenseContext?: boolean;
+    /** Bootstrap JavaScript code for js-exec */
+    jsBootstrapCode?: string;
+    /** Tool invoker hook for js-exec's `tools` proxy */
+    invokeTool?: (path: string, argsJson: string) => Promise<string>;
+}
+export declare class Interpreter {
+    private ctx;
+    constructor(options: InterpreterOptions, state: InterpreterState);
+    /**
+     * Fail closed if defense is expected but async context is missing.
+     */
+    private assertDefenseContext;
+    /**
+     * Build environment record containing only exported variables.
+     * In bash, only exported variables are passed to child processes.
+     * This includes both permanently exported variables (via export/declare -x)
+     * and temporarily exported variables (prefix assignments like FOO=bar cmd).
+     */
+    private buildExportedEnv;
+    executeScript(node: ScriptNode): Promise<ExecResult>;
+    /**
+     * Execute a user script file found in PATH.
+     */
+    private executeUserScript;
+    private executeStatement;
+    private executePipeline;
+    /**
+     * Execute a command, tearing down any process substitutions its own word
+     * expansion opened. Descriptor numbers are handed out from 63 downwards and
+     * released here, so they are reused per command exactly like bash and no
+     * backing file outlives the command that created it.
+     */
+    private executeCommand;
+    private executeCommandInner;
+    private executeSimpleCommand;
+    private executeSimpleCommandInner;
+    private runCommand;
+    private aliasExpansionStack;
+    private expandAlias;
+    findCommandInPath(commandName: string): Promise<string[]>;
+    private executeSubshell;
+    private executeGroup;
+    private executeArithmeticCommand;
+    private executeConditionalCommand;
+}

package/dist/interpreter/numeric-fd-redirects.d.ts

@@ -0,0 +1,8 @@
+import type { RedirectionNode } from "../ast/types.js";
+/**
+ * The descriptor a redirection acts on, or null when it targets both
+ * stdout and stderr (`&>`), which never names a user fd.
+ */
+export declare function effectiveRedirectFd(redir: RedirectionNode): number | null;
+/** True when this redirection is installed in the descriptor table. */
+export declare function isNumericFdRedirection(redir: RedirectionNode): boolean;