just-bash 2.5.4 → 2.6.0

package/dist/interpreter/expansion/variable.d.ts

@@ -6,12 +6,14 @@
  * - Array access (${arr[0]}, ${arr[@]}, ${arr[*]})
  * - Positional parameters ($1, $2, ...)
  * - Regular variables
+ * - Nameref resolution
  */
 import type { InterpreterContext } from "../types.js";
 /**
  * Get all elements of an array stored as arrayName_0, arrayName_1, etc.
  * Returns an array of [index/key, value] tuples, sorted by index/key.
  * For associative arrays, uses string keys.
+ * Special arrays FUNCNAME, BASH_LINENO, and BASH_SOURCE are handled dynamically from call stack.
  */
 export declare function getArrayElements(ctx: InterpreterContext, arrayName: string): Array<[number | string, string]>;
 /**
@@ -24,4 +26,11 @@ export declare function isArray(ctx: InterpreterContext, name: string): boolean;
  * @param name - The variable name
  * @param checkNounset - Whether to check for nounset (default true)
  */
-export declare function getVariable(ctx: InterpreterContext, name: string, checkNounset?: boolean, _insideDoubleQuotes?: boolean): string;
+export declare function getVariable(ctx: InterpreterContext, name: string, checkNounset?: boolean, _insideDoubleQuotes?: boolean): Promise<string>;
+/**
+ * Check if a variable is set (exists in the environment).
+ * Properly handles array subscripts (e.g., arr[0] -> arr_0).
+ * @param ctx - The interpreter context
+ * @param name - The variable name (possibly with array subscript)
+ */
+export declare function isVariableSet(ctx: InterpreterContext, name: string): Promise<boolean>;

package/dist/interpreter/expansion/word-glob-expansion.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Word Expansion with Glob Handling
+ *
+ * Handles the main word expansion flow including:
+ * - Brace expansion
+ * - Array and positional parameter expansion
+ * - Word splitting
+ * - Glob/pathname expansion
+ */
+import type { ArithExpr, ParameterExpansionPart, WordNode, WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Dependencies injected to avoid circular imports
+ */
+export interface WordGlobExpansionDeps {
+    expandWordAsync: (ctx: InterpreterContext, word: WordNode) => Promise<string>;
+    expandWordForGlobbing: (ctx: InterpreterContext, word: WordNode) => Promise<string>;
+    expandWordWithBracesAsync: (ctx: InterpreterContext, word: WordNode) => Promise<string[] | null>;
+    expandWordPartsAsync: (ctx: InterpreterContext, parts: WordPart[]) => Promise<string>;
+    expandPart: (ctx: InterpreterContext, part: WordPart, inDoubleQuotes?: boolean) => Promise<string>;
+    expandParameterAsync: (ctx: InterpreterContext, part: ParameterExpansionPart, inDoubleQuotes?: boolean) => Promise<string>;
+    hasBraceExpansion: (parts: WordPart[]) => boolean;
+    evaluateArithmetic: (ctx: InterpreterContext, expr: ArithExpr, isExpansionContext?: boolean) => Promise<number>;
+    buildIfsCharClassPattern: (ifsChars: string) => string;
+    smartWordSplit: (ctx: InterpreterContext, wordParts: WordPart[], ifsChars: string, ifsPattern: string, expandPart: (ctx: InterpreterContext, part: WordPart) => Promise<string>) => Promise<string[]>;
+}
+/**
+ * Main word expansion function that handles all expansion types and glob matching.
+ */
+export declare function expandWordWithGlobImpl(ctx: InterpreterContext, word: WordNode, deps: WordGlobExpansionDeps): Promise<{
+    values: string[];
+    quoted: boolean;
+}>;

package/dist/interpreter/expansion/word-split.d.ts

@@ -10,15 +10,20 @@ import type { InterpreterContext } from "../types.js";
  */
 export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
 /**
- * Smart word splitting that respects expansion boundaries.
+ * Smart word splitting for words containing expansions.
  *
- * E.g., with IFS=x: ${v:-AxBxC}x should give "A B Cx" (literal x attaches to last field)
- * E.g., with IFS=x: y${v:-AxBxC}z should give "yA B Cz" (literals attach to first/last fields)
+ * In bash, word splitting respects quoted parts. When you have:
+ * - $a"$b" where a="1 2" and b="3 4"
+ * - The unquoted $a gets split by IFS: "1 2" -> ["1", "2"]
+ * - The quoted "$b" does NOT get split, it joins with the last field from $a
+ * - Result: ["1", "23 4"] (the "2" joins with "3 4")
+ *
+ * This differs from pure literal words which are never IFS-split.
  *
  * @param ctx - Interpreter context
  * @param wordParts - Word parts to expand and split
- * @param _ifsChars - IFS characters (unused, kept for API compatibility)
- * @param ifsPattern - Regex-escaped IFS pattern for splitting
+ * @param ifsChars - IFS characters for proper whitespace/non-whitespace handling
+ * @param ifsPattern - Regex-escaped IFS pattern for checking if splitting is needed
  * @param expandPartFn - Function to expand individual parts (injected to avoid circular deps)
  */
-export declare function smartWordSplit(ctx: InterpreterContext, wordParts: WordPart[], _ifsChars: string, ifsPattern: string, expandPartFn: ExpandPartFn): Promise<string[]>;
+export declare function smartWordSplit(ctx: InterpreterContext, wordParts: WordPart[], ifsChars: string, _ifsPattern: string, expandPartFn: ExpandPartFn): Promise<string[]>;

package/dist/interpreter/expansion.d.ts

@@ -11,17 +11,43 @@
  */
 import type { WordNode } from "../ast/types.js";
 import type { InterpreterContext } from "./types.js";
-export { getArrayElements, getVariable } from "./expansion/variable.js";
+export { escapeGlobChars, escapeRegexChars } from "./expansion/glob-escape.js";
+export { getArrayElements, getVariable, isArray, } from "./expansion/variable.js";
 /**
  * Check if an entire word is fully quoted
  */
 export declare function isWordFullyQuoted(word: WordNode): boolean;
+export declare function expandWord(ctx: InterpreterContext, word: WordNode): Promise<string>;
 /**
- * Escape glob metacharacters in a string for literal matching
+ * Expand a word for use as a regex pattern (in [[ =~ ]]).
+ * Preserves backslash escapes so they're passed to the regex engine.
+ * For example, \[\] becomes \[\] in the regex (matching literal [ and ]).
  */
-export declare function escapeGlobChars(str: string): string;
-export declare function expandWord(ctx: InterpreterContext, word: WordNode): Promise<string>;
+export declare function expandWordForRegex(ctx: InterpreterContext, word: WordNode): Promise<string>;
+/**
+ * Expand a word for use as a pattern (e.g., in [[ == ]] or case).
+ * Preserves backslash escapes for pattern metacharacters so they're treated literally.
+ * This prevents `*\(\)` from being interpreted as an extglob pattern.
+ */
+export declare function expandWordForPattern(ctx: InterpreterContext, word: WordNode): Promise<string>;
 export declare function expandWordWithGlob(ctx: InterpreterContext, word: WordNode): Promise<{
     values: string[];
     quoted: boolean;
 }>;
+export declare function hasQuotedMultiValueAt(ctx: InterpreterContext, word: WordNode): boolean;
+/**
+ * Expand a redirect target with glob handling.
+ *
+ * For redirects:
+ * - If glob matches 0 files with failglob → error (returns { error: ... })
+ * - If glob matches 0 files without failglob → use literal pattern
+ * - If glob matches 1 file → use that file
+ * - If glob matches 2+ files → "ambiguous redirect" error
+ *
+ * Returns { target: string } on success or { error: string } on failure.
+ */
+export declare function expandRedirectTarget(ctx: InterpreterContext, word: WordNode): Promise<{
+    target: string;
+} | {
+    error: string;
+}>;

package/dist/interpreter/functions.d.ts

@@ -9,4 +9,4 @@ import type { FunctionDefNode } from "../ast/types.js";
 import type { ExecResult } from "../types.js";
 import type { InterpreterContext } from "./types.js";
 export declare function executeFunctionDef(ctx: InterpreterContext, node: FunctionDefNode): ExecResult;
-export declare function callFunction(ctx: InterpreterContext, func: FunctionDefNode, args: string[]): Promise<ExecResult>;
+export declare function callFunction(ctx: InterpreterContext, func: FunctionDefNode, args: string[], stdin?: string, callLine?: number): Promise<ExecResult>;

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

@@ -1,6 +1,7 @@
 /**
  * Array helper functions for the interpreter.
  */
+import type { WordNode } from "../../ast/types.js";
 import type { InterpreterContext } from "../types.js";
 /**
  * Get all indices of an array, sorted in ascending order.
@@ -21,3 +22,22 @@ export declare function getAssocArrayKeys(ctx: InterpreterContext, arrayName: st
  * Handles 'key' and "key" → key
  */
 export declare function unquoteKey(key: string): string;
+/**
+ * Parse a keyed array element from an AST WordNode like [key]=value or [key]+=value.
+ * Returns { key, valueParts, append } where valueParts are the AST parts for the value.
+ * Returns null if not a keyed element pattern.
+ *
+ * This is used to properly expand variables in the value part of keyed elements.
+ */
+export interface ParsedKeyedElement {
+    key: string;
+    valueParts: WordNode["parts"];
+    append: boolean;
+}
+export declare function parseKeyedElementFromWord(word: WordNode): ParsedKeyedElement | null;
+/**
+ * Extract literal string content from a Word node (without expansion).
+ * This is used for parsing associative array element syntax like [key]=value
+ * where the [key] part may be parsed as a Glob.
+ */
+export declare function wordToLiteralString(word: WordNode): string;

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

@@ -15,6 +15,13 @@ export declare function getIfs(env: Record<string, string>): string;
  * Check if IFS is set to empty string (disables word splitting).
  */
 export declare function isIfsEmpty(env: Record<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: Record<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)
@@ -26,18 +33,72 @@ export declare function buildIfsCharClassPattern(ifs: string): string;
  */
 export declare function getIfsSeparator(env: Record<string, string>): string;
 /**
- * Split a string by IFS, handling leading/trailing IFS properly.
- * Returns words and their start positions in the original 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 splitByIfs(value: string, ifs: string): {
+export declare function splitByIfsForRead(value: string, ifs: string, maxSplit?: number, raw?: boolean): {
     words: string[];
     wordStarts: number[];
 };
 /**
- * Strip trailing IFS characters from a string.
+ * 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): IfsExpansionSplitResult;
+export declare function splitByIfsForExpansion(value: string, ifs: string): 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 stripTrailingIfs(value: string, ifs: string): string;
+export declare function stripTrailingIfsWhitespace(value: string, ifs: string, raw?: boolean): string;

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/quoting.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 quoteValue(value: string): string;
+/**
+ * Quote a value for array element output
+ * Uses $'...' for control characters, double quotes otherwise
+ */
+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

@@ -1,7 +1,7 @@
 /**
- * Readonly variable helpers.
+ * Readonly and export variable helpers.
  *
- * Consolidates readonly variable logic used in declare, export, local, etc.
+ * Consolidates readonly and export variable logic used in declare, export, local, etc.
  */
 import type { ExecResult } from "../../types.js";
 import type { InterpreterContext } from "../types.js";
@@ -10,12 +10,36 @@ import type { InterpreterContext } from "../types.js";
  */
 export declare function markReadonly(ctx: InterpreterContext, name: string): void;
 /**
- * Check if a variable is readonly and return an error if so.
+ * 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 Error result if readonly, null otherwise
+ * @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/shell-constants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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>;

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

@@ -17,6 +17,8 @@ export declare function isStringCompareOp(op: string): op is StringCompareOp;
  * @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): boolean;
+export declare function compareStrings(op: StringCompareOp, left: string, right: string, usePattern?: boolean, nocasematch?: boolean, extglob?: boolean): boolean;

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

@@ -0,0 +1,13 @@
+/**
+ * Tilde expansion helper functions.
+ *
+ * Handles ~ expansion in assignment contexts.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Expand tildes in assignment values (PATH-like expansion)
+ * - ~ at start expands to HOME
+ * - ~ after : expands to HOME (for PATH-like values)
+ * - ~username expands to user's home (only root supported)
+ */
+export declare function expandTildesInValue(ctx: InterpreterContext, value: string): string;

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

@@ -6,4 +6,4 @@ import type { InterpreterContext } from "../types.js";
  * @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): boolean;
+export declare function evaluateVariableTest(ctx: InterpreterContext, operand: string): Promise<boolean>;

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

@@ -0,0 +1,26 @@
+/**
+ * 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;
+/**
+ * Parse the content of a read-write file descriptor.
+ * Format: __rw__:pathLength:path:position:content
+ * @returns The parsed components, or null if format is invalid
+ */
+export declare function parseRwFdContent(fdContent: string): {
+    path: string;
+    position: number;
+    content: string;
+} | null;

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/interpreter.d.ts

@@ -34,28 +34,27 @@ export interface InterpreterOptions {
 export declare class Interpreter {
     private ctx;
     constructor(options: InterpreterOptions, state: InterpreterState);
+    /**
+     * 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;
     private executeCommand;
     private executeSimpleCommand;
     private executeSimpleCommandInner;
     private runCommand;
-    /**
-     * Resolve a command name to its implementation via PATH lookup.
-     * Returns the command and its resolved path, or null if not found.
-     *
-     * Resolution order:
-     * 1. If command contains "/", resolve as a path
-     * 2. Search PATH directories for the command file
-     * 3. Fall back to registry lookup (for non-InMemoryFs filesystems like OverlayFs)
-     */
-    private resolveCommand;
-    /**
-     * Find all paths for a command in PATH (for `which -a`).
-     */
+    private aliasExpansionStack;
+    private expandAlias;
     findCommandInPath(commandName: string): Promise<string[]>;
-    private handleType;
     private executeSubshell;
     private executeGroup;
     private executeArithmeticCommand;

package/dist/interpreter/pipeline-execution.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pipeline Execution
+ *
+ * Handles execution of command pipelines (cmd1 | cmd2 | cmd3).
+ */
+import type { CommandNode, PipelineNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+/**
+ * Type for executeCommand callback
+ */
+export type ExecuteCommandFn = (node: CommandNode, stdin: string) => Promise<ExecResult>;
+/**
+ * Execute a pipeline node (command or sequence of piped commands).
+ */
+export declare function executePipeline(ctx: InterpreterContext, node: PipelineNode, executeCommand: ExecuteCommandFn): Promise<ExecResult>;

package/dist/interpreter/redirections.d.ts

@@ -7,8 +7,45 @@
  * - 2> : Write stderr to file
  * - &> : Write both stdout and stderr to file
  * - >& : Redirect fd to another fd
+ * - {fd}>file : Allocate FD and store in variable
  */
 import type { RedirectionNode } from "../ast/types.js";
 import type { ExecResult } from "../types.js";
 import type { InterpreterContext } from "./types.js";
-export declare function applyRedirections(ctx: InterpreterContext, result: ExecResult, redirections: RedirectionNode[]): Promise<ExecResult>;
+/**
+ * Pre-expanded redirect targets, keyed by index into the redirections array.
+ * This allows us to expand redirect targets (including side effects) before
+ * executing a function body, then apply the redirections after.
+ */
+export type ExpandedRedirectTargets = Map<number, string>;
+/**
+ * Pre-expand redirect targets for function definitions.
+ * This is needed because redirections on function definitions are evaluated
+ * each time the function is called, and any side effects (like $((i++)))
+ * must occur BEFORE the function body executes.
+ */
+export declare function preExpandRedirectTargets(ctx: InterpreterContext, redirections: RedirectionNode[]): Promise<{
+    targets: ExpandedRedirectTargets;
+    error?: string;
+}>;
+/**
+ * Process FD variable redirections ({varname}>file syntax).
+ * This allocates FDs and sets variables before command execution.
+ * Returns an error result if there's an issue, or null if successful.
+ */
+export declare function processFdVariableRedirections(ctx: InterpreterContext, redirections: RedirectionNode[]): Promise<ExecResult | null>;
+/**
+ * Pre-open (truncate) output redirect files before command execution.
+ * This is needed for compound commands (subshell, for, case, [[) where
+ * bash opens/truncates the redirect file BEFORE evaluating any words in
+ * the command body (including command substitutions).
+ *
+ * Example: `(echo \`cat FILE\`) > FILE`
+ * - Bash first truncates FILE (making it empty)
+ * - Then executes the subshell, where `cat FILE` returns empty string
+ *
+ * Returns an error result if there's an issue (like directory or noclobber),
+ * or null if pre-opening succeeded.
+ */
+export declare function preOpenOutputRedirects(ctx: InterpreterContext, redirections: RedirectionNode[]): Promise<ExecResult | null>;
+export declare function applyRedirections(ctx: InterpreterContext, result: ExecResult, redirections: RedirectionNode[], preExpandedTargets?: ExpandedRedirectTargets): Promise<ExecResult>;