@jerryan/just-bash 3.5.0

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

@@ -0,0 +1,23 @@
+/**
+ * Pattern Matching
+ *
+ * Converts shell glob patterns to regex equivalents for pattern matching
+ * in parameter expansion (${var%pattern}, ${var/pattern/replacement}, etc.)
+ * and case statements.
+ *
+ * ## Error Handling
+ *
+ * This module follows bash's behavior for invalid patterns:
+ * - Invalid character ranges (e.g., `[z-a]`) result in regex compilation failure
+ * - Unknown POSIX classes (e.g., `[:foo:]`) produce empty match groups
+ * - Unclosed character classes (`[abc`) are treated as literal `[`
+ *
+ * Callers should wrap regex compilation in try/catch to handle invalid patterns.
+ */
+/**
+ * Convert a shell glob pattern to a regex string.
+ * @param pattern - The glob pattern (*, ?, [...])
+ * @param greedy - Whether * should be greedy (true for suffix matching, false for prefix)
+ * @param extglob - Whether to support extended glob patterns (@(...), *(...), +(...), ?(...), !(...))
+ */
+export declare function patternToRegex(pattern: string, greedy: boolean, extglob?: boolean): string;

package/dist/interpreter/expansion/positional-params.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Positional Parameter Expansion Handlers
+ *
+ * Handles $@ and $* expansion with various operations:
+ * - "${@:offset}" and "${*:offset}" - slicing
+ * - "${@/pattern/replacement}" - pattern replacement
+ * - "${@#pattern}" - pattern removal (strip)
+ * - "$@" and "$*" with adjacent text
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for positional parameter expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type PositionalExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+import type { ArithExpr } from "../../ast/types.js";
+/**
+ * Type for evaluateArithmetic function
+ */
+export type EvaluateArithmeticFn = (ctx: InterpreterContext, expr: ArithExpr, isExpansionContext?: boolean) => Promise<number>;
+/**
+ * Type for expandPart function
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Type for expandWordPartsAsync function
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[]) => Promise<string>;
+/**
+ * Handle "${@:offset}" and "${*:offset}" with Substring operations inside double quotes
+ * "${@:offset}": Each sliced positional parameter becomes a separate word
+ * "${*:offset}": All sliced params joined with IFS as ONE word
+ */
+export declare function handlePositionalSlicing(ctx: InterpreterContext, wordParts: WordPart[], evaluateArithmetic: EvaluateArithmeticFn, expandPart: ExpandPartFn): Promise<PositionalExpansionResult>;
+/**
+ * Handle "${@/pattern/replacement}" and "${* /pattern/replacement}" with PatternReplacement inside double quotes
+ * "${@/pattern/replacement}": Each positional parameter has pattern replaced, each becomes a separate word
+ * "${* /pattern/replacement}": All params joined with IFS, pattern replaced, becomes ONE word
+ */
+export declare function handlePositionalPatternReplacement(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<PositionalExpansionResult>;
+/**
+ * Handle "${@#pattern}" and "${*#pattern}" - positional parameter pattern removal (strip)
+ * "${@#pattern}": Remove shortest matching prefix from each parameter, each becomes a separate word
+ * "${@##pattern}": Remove longest matching prefix from each parameter
+ * "${@%pattern}": Remove shortest matching suffix from each parameter
+ * "${@%%pattern}": Remove longest matching suffix from each parameter
+ */
+export declare function handlePositionalPatternRemoval(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn, expandWordPartsAsync: ExpandWordPartsAsyncFn): Promise<PositionalExpansionResult>;
+/**
+ * Handle "$@" and "$*" with adjacent text inside double quotes, e.g., "-$@-"
+ * "$@": Each positional parameter becomes a separate word, with prefix joined to first
+ *       and suffix joined to last. If no params, produces nothing (or just prefix+suffix if present)
+ * "$*": All params joined with IFS as ONE word. If no params, produces one empty word.
+ */
+export declare function handleSimplePositionalExpansion(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn): Promise<PositionalExpansionResult>;

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

@@ -0,0 +1,39 @@
+/**
+ * Prompt expansion
+ *
+ * Handles prompt escape sequences for ${var@P} transformation and PS1/PS2/PS3/PS4.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Expand prompt escape sequences (${var@P} transformation)
+ * Interprets backslash escapes used in PS1, PS2, PS3, PS4 prompt strings.
+ *
+ * Supported escapes:
+ * - \a - bell (ASCII 07)
+ * - \e - escape (ASCII 033)
+ * - \n - newline
+ * - \r - carriage return
+ * - \\ - literal backslash
+ * - \$ - $ for regular user, # for root (always $ here)
+ * - \[ and \] - non-printing sequence delimiters (removed)
+ * - \u - username
+ * - \h - short hostname (up to first .)
+ * - \H - full hostname
+ * - \w - current working directory
+ * - \W - basename of current working directory
+ * - \d - date (Weekday Month Day format)
+ * - \t - time HH:MM:SS (24-hour)
+ * - \T - time HH:MM:SS (12-hour)
+ * - \@ - time HH:MM AM/PM (12-hour)
+ * - \A - time HH:MM (24-hour)
+ * - \D{format} - strftime format
+ * - \s - shell name
+ * - \v - bash version (major.minor)
+ * - \V - bash version (major.minor.patch)
+ * - \j - number of jobs
+ * - \l - terminal device basename
+ * - \# - command number
+ * - \! - history number
+ * - \NNN - octal character code
+ */
+export declare function expandPrompt(ctx: InterpreterContext, value: string): string;

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

@@ -0,0 +1,13 @@
+/**
+ * Quoting helpers for word expansion
+ *
+ * Handles quoting values for shell reuse (${var@Q} transformation).
+ */
+/**
+ * Quote a value for safe reuse as shell input (${var@Q} transformation)
+ * Uses single quotes with proper escaping for special characters.
+ * Follows bash's quoting behavior:
+ * - Simple strings without quotes: 'value'
+ * - Strings with single quotes or control characters: $'value' with \' escaping
+ */
+export declare function quoteValue(value: string): string;

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

@@ -0,0 +1,14 @@
+/**
+ * Tilde Expansion
+ *
+ * Functions for handling tilde (~) expansion in word expansion.
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Apply tilde expansion to a string.
+ * Used after brace expansion to handle cases like ~{/src,root} -> ~/src ~root -> /home/user/src /root
+ * Only expands ~ at the start of the string followed by / or end of string.
+ */
+export declare function applyTildeExpansion(ctx: InterpreterContext, value: string): string;
+/** Apply assignment-context tilde expansion at the start and after each `:`. */
+export declare function applyAssignmentTildeExpansion(ctx: InterpreterContext, value: string): string;

package/dist/interpreter/expansion/unquoted-expansion.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Unquoted Expansion Handlers
+ *
+ * Handles unquoted positional parameter and array expansions:
+ * - Unquoted $@ and $* (with and without prefix/suffix)
+ * - Unquoted ${arr[@]} and ${arr[*]}
+ * - Unquoted ${@:offset} and ${*:offset} slicing
+ * - Unquoted ${@#pattern} and ${*#pattern} pattern removal
+ * - Unquoted ${arr[@]/pattern/replacement} pattern replacement
+ * - Unquoted ${arr[@]#pattern} pattern removal
+ * - Unquoted ${!prefix@} and ${!prefix*} variable name prefix expansion
+ * - Unquoted ${!arr[@]} and ${!arr[*]} array keys expansion
+ */
+import type { ArithExpr, WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Result type for unquoted expansion handlers.
+ * `null` means the handler doesn't apply to this case.
+ */
+export type UnquotedExpansionResult = {
+    values: string[];
+    quoted: boolean;
+} | null;
+/**
+ * Type for expandPart function reference
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Type for expandWordPartsAsync function reference
+ */
+export type ExpandWordPartsAsyncFn = (ctx: InterpreterContext, parts: WordPart[]) => Promise<string>;
+/**
+ * Type for evaluateArithmetic function
+ */
+export type EvaluateArithmeticFn = (ctx: InterpreterContext, expr: ArithExpr, isExpansionContext?: boolean) => Promise<number>;
+/**
+ * Handle unquoted ${array[@]/pattern/replacement} - apply to each element
+ * This handles ${array[@]/#/prefix} (prepend) and ${array[@]/%/suffix} (append)
+ */
+export declare function handleUnquotedArrayPatternReplacement(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${array[@]#pattern} - apply pattern removal to each element
+ * This handles ${array[@]#pattern} (strip shortest prefix), ${array[@]##pattern} (strip longest prefix)
+ * ${array[@]%pattern} (strip shortest suffix), ${array[@]%%pattern} (strip longest suffix)
+ */
+export declare function handleUnquotedArrayPatternRemoval(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${@#pattern} and ${*#pattern} - apply pattern removal to each positional parameter
+ * This handles ${@#pattern} (strip shortest prefix), ${@##pattern} (strip longest prefix)
+ * ${@%pattern} (strip shortest suffix), ${@%%pattern} (strip longest suffix)
+ */
+export declare function handleUnquotedPositionalPatternRemoval(ctx: InterpreterContext, wordParts: WordPart[], expandWordPartsAsync: ExpandWordPartsAsyncFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${@:offset} and ${*:offset} (with potential prefix/suffix)
+ */
+export declare function handleUnquotedPositionalSlicing(ctx: InterpreterContext, wordParts: WordPart[], evaluateArithmetic: EvaluateArithmeticFn, expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted $@ and $* (simple, without operations)
+ */
+export declare function handleUnquotedSimplePositional(ctx: InterpreterContext, wordParts: WordPart[]): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${arr[@]} and ${arr[*]} (without operations)
+ */
+export declare function handleUnquotedSimpleArray(ctx: InterpreterContext, wordParts: WordPart[]): Promise<UnquotedExpansionResult>;
+/**
+ * Handle unquoted ${!prefix@} and ${!prefix*} (variable name prefix expansion)
+ */
+export declare function handleUnquotedVarNamePrefix(ctx: InterpreterContext, wordParts: WordPart[]): UnquotedExpansionResult;
+/**
+ * Handle unquoted ${!arr[@]} and ${!arr[*]} (array keys/indices expansion)
+ */
+export declare function handleUnquotedArrayKeys(ctx: InterpreterContext, wordParts: WordPart[]): UnquotedExpansionResult;
+/**
+ * Handle unquoted $@ or $* with prefix/suffix (e.g., =$@= or =$*=)
+ */
+export declare function handleUnquotedPositionalWithPrefixSuffix(ctx: InterpreterContext, wordParts: WordPart[], expandPart: ExpandPartFn): Promise<UnquotedExpansionResult>;

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

@@ -0,0 +1,19 @@
+/**
+ * Variable Attributes
+ *
+ * Functions for getting variable attributes (${var@a} transformation).
+ */
+import type { InterpreterContext } from "../types.js";
+/**
+ * Get the attributes of a variable for ${var@a} transformation.
+ * Returns a string with attribute flags (e.g., "ar" for readonly array).
+ *
+ * Attribute flags (in order):
+ * - a: indexed array
+ * - A: associative array
+ * - i: integer
+ * - n: nameref
+ * - r: readonly
+ * - x: exported
+ */
+export declare function getVariableAttributes(ctx: InterpreterContext, name: string): string;

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

@@ -0,0 +1,36 @@
+/**
+ * Variable Access
+ *
+ * Handles variable value retrieval, including:
+ * - Special variables ($?, $$, $#, $@, $*, $0)
+ * - 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]>;
+/**
+ * Check if a variable is an array (has elements stored as name_0, name_1, etc.)
+ */
+export declare function isArray(ctx: InterpreterContext, name: string): boolean;
+/**
+ * Get the value of a variable, optionally checking nounset.
+ * @param ctx - The interpreter context
+ * @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): 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

@@ -0,0 +1,29 @@
+/**
+ * Word Splitting
+ *
+ * IFS-based word splitting for unquoted expansions.
+ */
+import type { WordPart } from "../../ast/types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Type for the expandPart function that will be injected
+ */
+export type ExpandPartFn = (ctx: InterpreterContext, part: WordPart) => Promise<string>;
+/**
+ * Smart word splitting for words containing expansions.
+ *
+ * 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 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[]>;

package/dist/interpreter/expansion.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Word Expansion
+ *
+ * Handles shell word expansion including:
+ * - Variable expansion ($VAR, ${VAR})
+ * - Command substitution $(...)
+ * - Arithmetic expansion $((...))
+ * - Tilde expansion (~)
+ * - Brace expansion {a,b,c}
+ * - Glob expansion (*, ?, [...])
+ */
+import type { WordNode } from "../ast/types.js";
+import type { InterpreterContext } from "./types.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>;
+/**
+ * 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 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/fd-table.d.ts

@@ -0,0 +1,130 @@
+/**
+ * File Descriptor Table
+ *
+ * One typed view over `ctx.state.fileDescriptors`, the shell's descriptor
+ * table. The table itself stays a `Map<number, string>` because it is part
+ * of the public `CommandContext` surface — extensions read fd values as
+ * content — so this module owns the string encoding instead.
+ *
+ * Entry kinds:
+ * - `input`      readable content (`N< file`, `N<<EOF`, `N<<<word`). Reading
+ *                is destructive: the remaining content is written back, so
+ *                successive `read -u N` calls advance a shared position.
+ * - `output`     a file opened for writing (`N> file`, `N>> file`).
+ * - `readwrite`  `N<> file` — content plus an explicit read position.
+ * - `dup-out`    fd duplicated from stdout/stderr (`N>&1`).
+ * - `dup-in`     fd duplicated from stdin (`N<&0`).
+ *
+ * An `input` entry is stored verbatim, so its content can look exactly like
+ * one of the marker encodings (a file whose first line is `__file__:/x`).
+ * `inputFds` records which descriptors hold content, so the markers are
+ * never guessed at for a descriptor this module opened; the prefix sniffing
+ * in {@link decodeFdEntry} is only a fallback for descriptors written by
+ * older code paths.
+ */
+import type { InterpreterContext } from "./types.js";
+/** Lowest descriptor a script may open by number. 0/1/2 are the std streams. */
+export declare const FIRST_USER_FD = 3;
+export type FdEntry = {
+    kind: "input";
+    content: string;
+} | {
+    kind: "output";
+    path: string;
+    append: boolean;
+} | {
+    kind: "readwrite";
+    path: string;
+    position: number;
+    content: string;
+} | {
+    kind: "dup-out";
+    sourceFd: number;
+} | {
+    kind: "dup-in";
+    sourceFd: number;
+} | {
+    kind: "closed";
+};
+/**
+ * A descriptor's raw value, whether it is known to hold content, and which
+ * other descriptors shared its open file description.
+ */
+interface FdSnapshotEntry {
+    raw: string | undefined;
+    isInput: boolean;
+    aliases: number[];
+}
+/** Descriptor state captured by {@link rememberFd}, replayed by
+ * {@link restoreFds}. */
+export type FdSnapshot = Map<number, FdSnapshotEntry>;
+/**
+ * Decode a raw table value into a typed entry.
+ * Callers that know the descriptor holds content should go through
+ * {@link getFdEntry}, which consults `inputFds` first and never guesses.
+ */
+export declare function decodeFdEntry(raw: string): FdEntry;
+/** Encode a typed entry back into its raw table value. */
+export declare function encodeFdEntry(entry: FdEntry): string;
+export declare function getFdAliasMembers(ctx: InterpreterContext, fd: number): number[];
+/** Raw table value for `fd`, or undefined when the fd is not open. */
+export declare function getRawFd(ctx: InterpreterContext, fd: number): string | undefined;
+/** Typed entry for `fd`, or undefined when the fd is not open. */
+export declare function getFdEntry(ctx: InterpreterContext, fd: number): FdEntry | undefined;
+export declare function isFdOpen(ctx: InterpreterContext, fd: number): boolean;
+/**
+ * Store a raw value, charging the descriptor limit for newly opened fds.
+ * Opening a descriptor gives it a NEW open file description, so it stops
+ * sharing an offset with anything it was previously duplicated from —
+ * `exec 4<&3; exec 4< other` leaves fd 3 alone.
+ */
+export declare function setRawFd(ctx: InterpreterContext, fd: number, raw: string, isInput?: boolean): void;
+export declare function setFdEntry(ctx: InterpreterContext, fd: number, entry: FdEntry): void;
+export declare function closeFd(ctx: InterpreterContext, fd: number): void;
+/**
+ * Point `fd` at whatever `sourceFd` refers to, the way `dup2()` does: the raw
+ * value and its content/marker classification are copied, and the two
+ * descriptors join one alias group so they share a read offset from here on.
+ * Returns false when `sourceFd` is not open.
+ */
+export declare function dupFd(ctx: InterpreterContext, fd: number, sourceFd: number): boolean;
+export declare function moveFd(ctx: InterpreterContext, fd: number, sourceFd: number): boolean;
+/**
+ * Readable bytes remaining on `fd`.
+ * Returns a reason instead of content when the fd cannot be read from, so
+ * callers can pick the diagnostic bash uses for their context.
+ */
+export declare function readFd(ctx: InterpreterContext, fd: number): {
+    content: string;
+} | {
+    error: "not-open" | "write-only";
+};
+/**
+ * Advance the read position of `fd` by `count` characters.
+ * `input` entries keep only the unread remainder, matching bash's single
+ * shared file offset: every later read continues where this one stopped —
+ * including reads through a descriptor duplicated from this one, which
+ * shares the same open file description.
+ */
+export declare function advanceFd(ctx: InterpreterContext, fd: number, count: number): void;
+export declare function writeFdEntry(ctx: InterpreterContext, entry: FdEntry, descriptors: number[], content: string, encoding: "binary" | "utf8"): Promise<boolean>;
+/**
+ * Record `fd`'s current state into `snapshot`, unless it is already there —
+ * the FIRST value seen is the one a later {@link restoreFds} puts back.
+ * A `raw` of `undefined` records "was not open".
+ */
+export declare function rememberFd(ctx: InterpreterContext, snapshot: FdSnapshot, fd: number): void;
+/**
+ * Snapshot the given descriptors so a scoped redirection can put the table
+ * back the way it found it.
+ */
+export declare function snapshotFds(ctx: InterpreterContext, fds: Iterable<number>): FdSnapshot;
+/**
+ * Undo the descriptor changes recorded by {@link rememberFd}.
+ *
+ * Only the descriptor is restored, never the file offset behind it: a
+ * command that read through `4<&3` has moved the shared description, and
+ * bash leaves fd 3 where that read left it once fd 4 is taken back down.
+ */
+export declare function restoreFds(ctx: InterpreterContext, snapshot: FdSnapshot): void;
+export {};

package/dist/interpreter/functions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Function Handling
+ *
+ * Handles shell function definition and invocation:
+ * - Function definition (adding to function table)
+ * - Function calls (with positional parameters and local scopes)
+ */
+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[], stdin?: string, callLine?: number, 
+/** A redirection on the call site (`f < file`) gave the function its own fd 0. */
+stdinRedirected?: boolean): Promise<ExecResult>;

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

@@ -0,0 +1,56 @@
+/**
+ * Array helper functions for the interpreter.
+ */
+import type { WordNode } from "../../ast/types.js";
+import type { InterpreterContext, ShellArray } from "../types.js";
+export declare function cloneArray(array: ShellArray): ShellArray;
+export declare function cloneArrays(arrays: Map<string, ShellArray> | undefined): Map<string, ShellArray>;
+export declare function getArray(ctx: InterpreterContext, arrayName: string): ShellArray | undefined;
+export declare function ensureArray(ctx: InterpreterContext, arrayName: string, kind?: "indexed" | "associative"): ShellArray;
+export declare function setArrayKind(ctx: InterpreterContext, arrayName: string, kind: "indexed" | "associative"): ShellArray;
+export declare function hasArray(ctx: InterpreterContext, arrayName: string): boolean;
+export declare function getArrayElement(ctx: InterpreterContext, arrayName: string, key: string | number): string | undefined;
+export declare function hasArrayElement(ctx: InterpreterContext, arrayName: string, key: string | number): boolean;
+export declare function setArrayElement(ctx: InterpreterContext, arrayName: string, key: string | number, value: string, kind?: "indexed" | "associative"): void;
+/** Prove a batch of distinct keys fits before any persistent mutation. */
+export declare function assertArrayKeysFit(ctx: InterpreterContext, arrayName: string, keys: Iterable<string | number>, replace?: boolean): void;
+export declare function deleteArrayElement(ctx: InterpreterContext, arrayName: string, key: string | number): boolean;
+export declare function deleteArray(ctx: InterpreterContext, arrayName: string): void;
+/**
+ * Get all indices of an array, sorted in ascending order.
+ * Indexed arrays are held in dedicated structured interpreter state.
+ */
+export declare function getArrayIndices(ctx: InterpreterContext, arrayName: string): number[];
+/**
+ * Clear all elements of an array from the environment.
+ */
+export declare function clearArray(ctx: InterpreterContext, arrayName: string): void;
+/**
+ * Get all keys of an associative array.
+ * Associative keys are retained exactly in the array element map.
+ */
+export declare function getAssocArrayKeys(ctx: InterpreterContext, arrayName: string): string[];
+/**
+ * Remove surrounding quotes from a key string.
+ * 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/bounded-array.d.ts

@@ -0,0 +1,2 @@
+/** Append untrusted collections without argument spreading and with a cumulative cap. */
+export declare function appendBoundedElements<T>(target: T[], values: readonly T[], maximum: number, site: string): void;

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

@@ -0,0 +1,19 @@
+/**
+ * Condition execution helper for the interpreter.
+ *
+ * Handles executing condition statements with proper inCondition state management.
+ * Used by if, while, and until loops.
+ */
+import type { StatementNode } from "../../ast/types.js";
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+export type ConditionResult = Pick<ExecResult, "stdout" | "stderr" | "exitCode" | "internalOutputAccounting">;
+/**
+ * Execute condition statements with inCondition flag set.
+ * This prevents errexit from triggering during condition evaluation.
+ *
+ * @param ctx - Interpreter context
+ * @param statements - Condition statements to execute
+ * @returns Accumulated stdout, stderr, and final exit code
+ */
+export declare function executeCondition(ctx: InterpreterContext, statements: StatementNode[]): Promise<ConditionResult>;

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

@@ -0,0 +1,8 @@
+/**
+ * Error helper functions for the interpreter.
+ */
+/**
+ * Extract message from an unknown error value.
+ * Handles both Error instances and other thrown values.
+ */
+export declare function getErrorMessage(error: unknown): string;