@jerryan/just-bash 3.5.0

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

@@ -0,0 +1,62 @@
+/**
+ * Process Substitution
+ *
+ * Implements bash's `<(cmd)` and `>(cmd)`.
+ *
+ * Real bash runs `cmd` asynchronously connected to a pipe and substitutes the
+ * pipe's path (`/dev/fd/N`, or a FIFO on systems without `/dev/fd`). There are
+ * no processes or pipes here, so the construct is modelled with the same
+ * building blocks the rest of the interpreter uses for fds: a backing file in
+ * the VFS under `/dev/fd/`, whose contents are produced (or consumed) by
+ * running the body as a subshell.
+ *
+ * - `<(cmd)` runs `cmd` eagerly during word expansion, writes its stdout to
+ *   the backing file, and substitutes that path. Because the body is fully
+ *   buffered, a body that never terminates on its own (e.g. `yes`) is bounded
+ *   by the ordinary execution limits rather than by the reader closing the
+ *   pipe.
+ * - `>(cmd)` substitutes an empty writable backing file. Once the command that
+ *   consumed the path has finished, whatever was written to the file is fed to
+ *   `cmd` as stdin and `cmd`'s output is appended to the result — the closest
+ *   deterministic analogue of bash's asynchronous writer.
+ *
+ * Backing files live only for the duration of the command whose expansion
+ * created them: {@link markProcessSubstitutions} / {@link releaseProcessSubstitutions}
+ * bracket every command execution, so fd numbers are reused (63, 62, … just
+ * like bash) and nothing accumulates in the VFS across commands.
+ */
+import type { ProcessSubstitutionPart, ScriptNode } from "../ast/types.js";
+import type { InterpreterContext } from "./types.js";
+/** A process substitution whose backing file is still live. */
+export interface ProcessSubstitutionEntry {
+    /** Synthetic descriptor number (63, 62, …). */
+    fd: number;
+    /** Backing file path handed to the outer command. */
+    path: string;
+    /** `<(...)` or `>(...)`. */
+    direction: "input" | "output";
+    /** Body to run with the written bytes as stdin (output substitutions only). */
+    body: ScriptNode;
+}
+/**
+ * Expand a process substitution to the path the outer command should use.
+ */
+export declare function openProcessSubstitution(ctx: InterpreterContext, part: ProcessSubstitutionPart): Promise<string>;
+/**
+ * Remember how many process substitutions were live before a command ran.
+ */
+export declare function markProcessSubstitutions(ctx: InterpreterContext): number;
+/** Output produced by `>(cmd)` writers drained at the end of a command. */
+export interface ProcessSubstitutionWriterOutput {
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Tear down every process substitution opened since `mark`, newest first.
+ *
+ * Input substitutions just drop their backing file. Output substitutions first
+ * feed everything the outer command wrote into their body; the body's output is
+ * returned so the caller can append it to the command's own, the way bash's
+ * asynchronous writer shares the shell's stdout and stderr.
+ */
+export declare function releaseProcessSubstitutions(ctx: InterpreterContext, mark: number): Promise<ProcessSubstitutionWriterOutput>;

package/dist/interpreter/redirections.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Redirection Handling
+ *
+ * Handles output redirections:
+ * - > : Write stdout to file
+ * - >> : Append stdout to file
+ * - 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 { ControlFlowError, ExecutionLimitError, ExitError } from "./errors.js";
+import { type FdEntry } from "./fd-table.js";
+import type { InterpreterContext } from "./types.js";
+/** Expanded targets keyed by their position in the original redirection list. */
+export type ExpandedRedirectTargets = Map<number, string>;
+type PreparedDupSource = {
+    kind: "standard";
+    fd: number;
+} | {
+    kind: "entry";
+    entry: FdEntry;
+    descriptors: number[];
+};
+export type PreparedDupSources = Map<number, PreparedDupSource>;
+export type PreparedRedirections = {
+    targets: ExpandedRedirectTargets;
+    dupSources: PreparedDupSources;
+    standardRoutes: Map<number, FdEntry>;
+    stdin: string | undefined;
+    stdinSourceFd: number;
+    error: ExecResult | null;
+    errorCause?: ExitError | ExecutionLimitError;
+};
+export type RedirectionPolicy = "scoped" | "bare" | "persistent";
+export declare const SIMPLE_REDIRECTION_POLICY: RedirectionPolicy;
+export declare const BARE_REDIRECTION_POLICY: RedirectionPolicy;
+export declare const EXEC_REDIRECTION_POLICY: RedirectionPolicy;
+export type RedirectionTransaction = {
+    prepare: (inheritedStdin?: string) => Promise<PreparedRedirections>;
+    finish: () => void;
+};
+export declare function createRedirectionTransaction(ctx: InterpreterContext, redirections: RedirectionNode[], policy: RedirectionPolicy): RedirectionTransaction;
+export declare function preparedRedirectionError(prepared: PreparedRedirections): ExecResult;
+export declare function routeControlFlowError(ctx: InterpreterContext, error: ControlFlowError, redirections: RedirectionNode[], prepared: PreparedRedirections): Promise<void>;
+export declare function withPreparedRedirections(ctx: InterpreterContext, redirections: RedirectionNode[], inheritedStdin: string, run: (prepared: PreparedRedirections) => Promise<ExecResult>): Promise<ExecResult>;
+export declare function applyRedirections(ctx: InterpreterContext, result: ExecResult, redirections: RedirectionNode[], targets: ExpandedRedirectTargets, dupSources?: PreparedDupSources, standardRoutes?: Map<number, FdEntry>, writeErrorCommand?: string, omitShellPrefix?: boolean): Promise<ExecResult>;
+export {};

package/dist/interpreter/simple-command-assignments.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Simple Command Assignment Handling
+ *
+ * Handles variable assignments in simple commands:
+ * - Array assignments: VAR=(a b c)
+ * - Subscript assignments: VAR[idx]=value
+ * - Scalar assignments with nameref resolution
+ */
+import type { SimpleCommandNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+/**
+ * Result of processing assignments in a simple command
+ */
+export interface AssignmentResult {
+    /** Whether to continue to the next statement (skip command execution) */
+    continueToNext: boolean;
+    /** Accumulated xtrace output for assignments */
+    xtraceOutput: string;
+    /** Temporary assignments for prefix bindings (FOO=bar cmd) */
+    tempAssignments: Map<string, string | undefined>;
+    /** Error result if assignment failed */
+    error?: ExecResult;
+}
+/**
+ * Process all assignments in a simple command.
+ * Returns assignment results including temp bindings and any errors.
+ */
+export declare function processAssignments(ctx: InterpreterContext, node: SimpleCommandNode): Promise<AssignmentResult>;
+/**
+ * Compute the index for an indexed array subscript
+ */
+export declare function computeIndexedArrayIndex(ctx: InterpreterContext, arrayName: string, subscriptExpr: string): Promise<{
+    index: number;
+    error?: ExecResult;
+}>;

package/dist/interpreter/state-transaction.d.ts

@@ -0,0 +1,7 @@
+import type { InterpreterState } from "./types.js";
+/**
+ * Install an isolated copy of mutable shell namespace state and return an
+ * idempotent rollback. Process-wide accounting and PID allocation deliberately
+ * remain shared with the parent execution.
+ */
+export declare function beginIsolatedShellState(state: InterpreterState): () => void;

package/dist/interpreter/subshell-group.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Subshell, Group, and Script Execution
+ *
+ * Handles execution of subshells (...), groups { ...; }, and user scripts
+ */
+import type { GroupNode, ScriptNode, StatementNode, SubshellNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+/**
+ * Type for executeStatement callback
+ */
+export type ExecuteStatementFn = (stmt: StatementNode) => Promise<ExecResult>;
+/**
+ * Execute a subshell node (...).
+ * Creates an isolated execution environment that doesn't affect the parent.
+ */
+export declare function executeSubshell(ctx: InterpreterContext, node: SubshellNode, stdin: string, executeStatement: ExecuteStatementFn, 
+/** See `executeGroup`: empty content can still be an owned, empty fd 0. */
+stdinOwned?: boolean): Promise<ExecResult>;
+/**
+ * Execute a group node { ...; }.
+ * Runs commands in the current execution environment.
+ */
+export declare function executeGroup(ctx: InterpreterContext, node: GroupNode, stdin: string, executeStatement: ExecuteStatementFn, 
+/**
+ * The caller already gave this group its own fd 0 — a function body whose
+ * definition or call was redirected. Needed because an empty `stdin` cannot
+ * say whether it came from `< empty-file` or from no redirection at all.
+ */
+stdinOwned?: boolean): Promise<ExecResult>;
+/**
+ * Type for executeScript callback
+ */
+export type ExecuteScriptFn = (node: ScriptNode) => Promise<ExecResult>;
+/**
+ * Execute a user script file found in PATH.
+ * This handles executable files that don't have registered command handlers.
+ * The script runs in a subshell-like environment with its own positional parameters.
+ */
+export declare function executeUserScript(ctx: InterpreterContext, scriptPath: string, args: string[], stdin: string, executeScript: ExecuteScriptFn): Promise<ExecResult>;

package/dist/interpreter/type-command.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Type Command Implementation
+ *
+ * Implements the `type` builtin command and related functionality:
+ * - type [-afptP] name...
+ * - command -v/-V name...
+ *
+ * Also includes helpers for function source serialization.
+ */
+import type { IFileSystem } from "../fs/interface.js";
+import type { CommandRegistry, ExecResult } from "../types.js";
+import type { InterpreterState } from "./types.js";
+/**
+ * Context needed for type command operations
+ */
+export interface TypeCommandContext {
+    state: InterpreterState;
+    fs: IFileSystem;
+    commands: CommandRegistry;
+}
+/**
+ * Handle the `type` builtin command.
+ * type [-afptP] name...
+ */
+export declare function handleType(ctx: TypeCommandContext, args: string[], findFirstInPath: (name: string) => Promise<string | null>, findCommandInPath: (name: string) => Promise<string[]>): Promise<ExecResult>;
+/**
+ * Handle `command -v` and `command -V` flags
+ * -v: print the name or path of the command (simple output)
+ * -V: print a description like `type` does (verbose output)
+ */
+export declare function handleCommandV(ctx: TypeCommandContext, names: string[], _showPath: boolean, verboseDescribe: boolean): Promise<ExecResult>;
+/**
+ * Find the first occurrence of a command in PATH.
+ * Returns the full path if found, null otherwise.
+ * Only returns executable files, not directories.
+ */
+export declare function findFirstInPath(ctx: TypeCommandContext, name: string): Promise<string | null>;

package/dist/interpreter/types.d.ts

@@ -0,0 +1,402 @@
+/**
+ * Interpreter Types
+ */
+import type { CommandNode, FunctionDefNode, ScriptNode, StatementNode } 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 { CommandExecOptions, CommandRegistry, ExecResult, FeatureCoverageWriter, TraceCallback } from "../types.js";
+import type { ProcessSubstitutionEntry } from "./process-substitution.js";
+export type InterpreterExecOptions = Omit<CommandExecOptions, "cwd"> & {
+    cwd?: string;
+};
+/**
+ * Completion specification for a command, set by the `complete` builtin.
+ */
+export interface CompletionSpec {
+    /** Word list for -W option */
+    wordlist?: string;
+    /** Function name for -F option */
+    function?: string;
+    /** Command to run for -C option */
+    command?: string;
+    /** Completion options (nospace, filenames, etc.) */
+    options?: string[];
+    /** Actions to perform (from -A option) */
+    actions?: string[];
+    /** Whether this is a default completion (-D) */
+    isDefault?: boolean;
+}
+export interface ShellOptions {
+    /** set -e: Exit immediately if a command exits with non-zero status */
+    errexit: boolean;
+    /** set -o pipefail: Return the exit status of the last (rightmost) command in a pipeline that fails */
+    pipefail: boolean;
+    /** set -u: Treat unset variables as an error when substituting */
+    nounset: boolean;
+    /** set -x: Print commands and their arguments as they are executed */
+    xtrace: boolean;
+    /** set -v: Print shell input lines as they are read (verbose) */
+    verbose: boolean;
+    /** set -o posix: POSIX mode for stricter compliance */
+    posix: boolean;
+    /** set -a: Export all variables */
+    allexport: boolean;
+    /** set -C: Prevent overwriting files with redirection */
+    noclobber: boolean;
+    /** set -f: Disable filename expansion (globbing) */
+    noglob: boolean;
+    /** set -n: Read commands but do not execute them (syntax check mode) */
+    noexec: boolean;
+    /** set -o vi: Use vi-style line editing (mutually exclusive with emacs) */
+    vi: boolean;
+    /** set -o emacs: Use emacs-style line editing (mutually exclusive with vi) */
+    emacs: boolean;
+}
+export interface ShoptOptions {
+    /** shopt -s extglob: Enable extended globbing patterns @(), *(), +(), ?(), !() */
+    extglob: boolean;
+    /** shopt -s dotglob: Include dotfiles in glob expansion */
+    dotglob: boolean;
+    /** shopt -s nullglob: Return empty for non-matching globs instead of literal pattern */
+    nullglob: boolean;
+    /** shopt -s failglob: Fail if glob pattern has no matches */
+    failglob: boolean;
+    /** shopt -s globstar: Enable ** recursive glob patterns */
+    globstar: boolean;
+    /** shopt -s globskipdots: Skip . and .. in glob patterns (default: true in bash >=5.2) */
+    globskipdots: boolean;
+    /** shopt -s nocaseglob: Case-insensitive glob matching */
+    nocaseglob: boolean;
+    /** shopt -s nocasematch: Case-insensitive pattern matching in [[ ]] and case */
+    nocasematch: boolean;
+    /** shopt -s expand_aliases: Enable alias expansion */
+    expand_aliases: boolean;
+    /** shopt -s lastpipe: Run last command of pipeline in current shell context */
+    lastpipe: boolean;
+    /** shopt -s xpg_echo: Make echo interpret backslash escapes by default (like echo -e) */
+    xpg_echo: boolean;
+}
+/**
+ * Tracks variable type attributes (declare -i, -l, -u, -n, -a, -A, etc.)
+ * and export status. These affect how variables are read, written, and expanded.
+ */
+export interface VariableAttributeState {
+    /** Set of variable names that are readonly */
+    readonlyVars?: Set<string>;
+    /** Set of variable names that are associative arrays */
+    associativeArrays?: Set<string>;
+    /** Set of variable names that are namerefs (declare -n) */
+    namerefs?: Set<string>;
+    /**
+     * Set of nameref variable names that were "bound" to valid targets at creation time.
+     * A bound nameref will always resolve through to its target, even if the target
+     * is later unset. An unbound nameref (target didn't exist at creation) acts like
+     * a regular variable, returning its raw value.
+     */
+    boundNamerefs?: Set<string>;
+    /**
+     * Set of nameref variable names that were created with an invalid target.
+     * Invalid namerefs always read/write their value directly, never resolving.
+     * For example, after `ref=1; typeset -n ref`, ref has an invalid target "1".
+     */
+    invalidNamerefs?: Set<string>;
+    /** Set of variable names that have integer attribute (declare -i) */
+    integerVars?: Set<string>;
+    /** Set of variable names that have lowercase attribute (declare -l) */
+    lowercaseVars?: Set<string>;
+    /** Set of variable names that have uppercase attribute (declare -u) */
+    uppercaseVars?: Set<string>;
+    /** Set of exported variable names */
+    exportedVars?: Set<string>;
+    /** Set of temporarily exported variable names (for prefix assignments like FOO=bar cmd) */
+    tempExportedVars?: Set<string>;
+    /**
+     * Stack of sets tracking variables exported within each local scope.
+     * When a function returns and a local scope is popped, if a variable was
+     * exported only in that scope (not before entering), the export attribute
+     * should be removed. This enables bash's scoped export behavior where
+     * `local V=x; export V` only exports the local, not the global.
+     */
+    localExportedVars?: Set<string>[];
+    /** Set of variable names that have been declared but not assigned a value */
+    declaredVars?: Set<string>;
+}
+/**
+ * Tracks the complex local variable scoping machinery.
+ * Bash's local variable behavior is intricate: variables are dynamically scoped,
+ * can be declared multiple times in nested contexts, and have different unset
+ * behaviors depending on whether the unset happens in the declaring scope.
+ */
+export interface LocalScopingState {
+    /** Stack of local variable scopes (one Map per function call) */
+    localScopes: Map<string, string | undefined>[];
+    /** Whole-array snapshots parallel to localScopes. */
+    localArrayScopes?: Map<string, ShellArray | undefined>[];
+    /**
+     * Tracks at which call depth each local variable was declared.
+     * Used for bash-specific unset scoping behavior:
+     * - local-unset (same scope): value-unset (clears value, keeps local cell)
+     * - dynamic-unset (different scope): cell-unset (removes local cell, exposes outer value)
+     */
+    localVarDepth?: Map<string, number>;
+    /**
+     * Stack of saved values for each local variable, supporting bash's localvar-nest behavior.
+     * Each entry contains the saved (outer) value and the scope index where it was saved.
+     * This allows multiple nested `local` declarations of the same variable (e.g., in nested evals)
+     * to each have their own cell that can be unset independently.
+     */
+    localVarStack?: Map<string, Array<{
+        value: string | undefined;
+        scopeIndex: number;
+    }>>;
+    /**
+     * Map of variable names to scope index where they were fully unset.
+     * Used to prevent tempenv restoration after all local cells are removed.
+     * Entries are cleared when their scope returns.
+     */
+    fullyUnsetLocals?: Map<string, number>;
+    /**
+     * Stack of temporary environment bindings from prefix assignments (e.g., FOO=bar cmd).
+     * Each entry maps variable names to their saved (underlying) values.
+     * Used for bash-specific unset behavior: when unsetting a variable that has a
+     * tempenv binding, the unset should reveal the underlying value, not completely
+     * remove the variable.
+     */
+    tempEnvBindings?: Map<string, string | undefined>[];
+    /**
+     * Set of tempenv variable names that have been explicitly written to within
+     * the current function context (after the prefix assignment, before local).
+     * Used to distinguish between "fresh" tempenvs (local-unset = value-unset)
+     * and "mutated" tempenvs (local-unset reveals the mutated value).
+     */
+    mutatedTempEnvVars?: Set<string>;
+    /**
+     * Set of tempenv variable names that have been accessed (read or written)
+     * within the current function context. Used to determine if a tempenv was
+     * "observed" before a local declaration.
+     */
+    accessedTempEnvVars?: Set<string>;
+}
+/**
+ * Tracks the function call stack and source file nesting.
+ * This state powers the FUNCNAME, BASH_LINENO, and BASH_SOURCE arrays,
+ * and determines the behavior of `return` in different contexts.
+ */
+export interface CallStackState {
+    /** Function definitions (name -> AST node) */
+    functions: Map<string, FunctionDefNode>;
+    /** Current function call depth (for recursion limits and local scoping) */
+    callDepth: number;
+    /** Current source script nesting depth (for return in sourced scripts) */
+    sourceDepth: number;
+    /** Stack of call line numbers for BASH_LINENO */
+    callLineStack?: number[];
+    /** Stack of function names for FUNCNAME */
+    funcNameStack?: string[];
+    /** Stack of source files for BASH_SOURCE (tracks where functions were defined) */
+    sourceStack?: string[];
+    /** Current source file context (for function definitions) */
+    currentSource?: string;
+}
+/**
+ * Tracks loop nesting and condition context.
+ * Used to implement break/continue commands and to suppress errexit
+ * in condition contexts (if, while, until, ||, &&).
+ */
+export interface ControlFlowState {
+    /** True when executing condition for if/while/until (errexit doesn't apply) */
+    inCondition: boolean;
+    /** Current loop nesting depth (for break/continue) */
+    loopDepth: number;
+    /** True if this subshell was spawned from within a loop context (for break/continue to exit subshell) */
+    parentHasLoopContext?: boolean;
+    /** True when the last executed statement's exit code is "safe" for errexit purposes
+     *  (e.g., from a &&/|| chain where the failure wasn't the final command) */
+    errexitSafe?: boolean;
+}
+/**
+ * Tracks process IDs, timing, and execution counts.
+ * Powers special variables like $$, $BASHPID, $!, and $SECONDS.
+ */
+export interface ProcessState {
+    /** Total commands executed (for execution limits) */
+    commandCount: number;
+    /** Time when shell started (for $SECONDS) */
+    startTime: number;
+    /** PID of last background job (for $!) */
+    lastBackgroundPid: number;
+    /** Current BASHPID (changes in subshells, unlike $$) */
+    bashPid: number;
+    /** Counter for generating unique virtual PIDs for subshells */
+    nextVirtualPid: number;
+    /** Virtual main shell PID for $$ (default 1, never exposes real process.pid) */
+    virtualPid: number;
+    /** Virtual parent PID for $PPID (default 0, never exposes real process.ppid) */
+    virtualPpid: number;
+    /** Virtual user ID for $UID/$EUID (default 1000, never exposes real UID) */
+    virtualUid: number;
+    /** Virtual group ID (default 1000, never exposes real GID) */
+    virtualGid: number;
+}
+/**
+ * Tracks file descriptors and stdin content for I/O operations.
+ * Used for process substitution, here-documents, and compound command stdin.
+ */
+export interface IOState {
+    /** Stdin available for commands in compound commands (groups, subshells, while loops with piped input) */
+    groupStdin?: string;
+    /** Descriptor that supplied `groupStdin`, when it has a shared position. */
+    groupStdinSourceFd?: number;
+    /** File descriptors for process substitution and here-docs */
+    fileDescriptors?: Map<number, string>;
+    /**
+     * Descriptors whose `fileDescriptors` value is verbatim content rather
+     * than one of the `__file__:` / `__rw__:` / `__dupout__:` markers. Kept
+     * beside the table (which is public API and must stay `Map<number,
+     * string>`) so that file content shaped like a marker is never mistaken
+     * for one. Maintained exclusively by `fd-table.ts`.
+     */
+    inputFds?: Set<number>;
+    /**
+     * Descriptors that share one open file description because of `N<&M`, and
+     * therefore share a read offset. Every member of a group maps to the same
+     * Set; descriptors with no aliases have no entry. Maintained exclusively
+     * by `fd-table.ts`.
+     */
+    fdAliases?: Map<number, Set<number>>;
+    /** Standard descriptors closed by persistent `exec N>&-` redirections. */
+    closedStandardFds?: Set<number>;
+    /** Next available file descriptor for {varname}>file allocation (starts at 10) */
+    nextFd?: number;
+    /**
+     * Process substitutions (`<(cmd)` / `>(cmd)`) whose backing files are still
+     * live, oldest first. Used as a stack: each command execution releases the
+     * entries its own expansion pushed.
+     */
+    processSubstitutions?: ProcessSubstitutionEntry[];
+    /**
+     * True once `/dev/fd` has been routed to a private in-memory filesystem
+     * because the supplied one refused to back a descriptor (read-only sandbox).
+     */
+    processSubstitutionFsMounted?: boolean;
+}
+/**
+ * Captures errors that occur during parameter expansion.
+ * Some expansion errors need to be reported after expansion completes,
+ * with their exit codes and stderr preserved.
+ */
+export interface ExpansionState {
+    /** Exit code from expansion errors (arithmetic, etc.) - overrides command exit code */
+    expansionExitCode?: number;
+    /** Stderr from expansion errors */
+    expansionStderr?: string;
+}
+/**
+ * Complete interpreter state for bash script execution.
+ *
+ * This interface is composed from focused sub-interfaces:
+ * - {@link VariableAttributeState} - Variable type attributes (readonly, integer, etc.)
+ * - {@link LocalScopingState} - Local variable scoping machinery
+ * - {@link CallStackState} - Function calls and source file tracking
+ * - {@link ControlFlowState} - Loop nesting and condition context
+ * - {@link ProcessState} - PIDs, timing, execution counts
+ * - {@link IOState} - File descriptors and stdin
+ * - {@link ExpansionState} - Expansion error capture
+ */
+export interface InterpreterState extends VariableAttributeState, LocalScopingState, CallStackState, ControlFlowState, ProcessState, IOState, ExpansionState {
+    /** Environment variables (exported to commands) - uses Map to prevent prototype pollution */
+    env: Map<string, string>;
+    /**
+     * Array values live outside the scalar environment namespace.  Shell names such
+     * as `a_0` and `a__length` are valid scalar variables and must never alias an
+     * element or interpreter metadata.
+     */
+    arrays?: Map<string, ShellArray>;
+    /** Current working directory */
+    cwd: string;
+    /** Previous directory (for `cd -`) */
+    previousDir: string;
+    /** Exit code of last executed command */
+    lastExitCode: number;
+    /** Last argument of previous command, for $_ expansion */
+    lastArg: string;
+    /** Current line number being executed (for $LINENO) */
+    currentLine: number;
+    /** Shell options (set -e, etc.) */
+    options: ShellOptions;
+    /** Shopt options (shopt -s, etc.) */
+    shoptOptions: ShoptOptions;
+    /** Completion specifications set by the `complete` builtin */
+    completionSpecs?: Map<string, CompletionSpec>;
+    /** Default completion policy (-D), kept outside the user command namespace. */
+    defaultCompletionSpec?: CompletionSpec;
+    /** Empty-line completion policy (-E), kept outside the user command namespace. */
+    emptyCompletionSpec?: CompletionSpec;
+    /** Directory stack for pushd/popd/dirs */
+    directoryStack?: string[];
+    /** Hash table for PATH command lookup caching */
+    hashTable?: Map<string, string>;
+    /**
+     * Suppress verbose mode output (set -v) when inside command substitutions.
+     * bash only prints verbose output for the main script, not for commands
+     * inside $(...) or backticks.
+     */
+    suppressVerbose?: boolean;
+    /**
+     * Abort signal for cooperative cancellation.
+     * Checked at statement boundaries; when aborted, execution stops.
+     */
+    signal?: AbortSignal;
+    /** Extra arguments injected via exec({ args }), appended to first command's args */
+    extraArgs?: string[];
+}
+export interface ShellArray {
+    kind: "indexed" | "associative";
+    elements: Map<string, string>;
+}
+export interface InterpreterContext {
+    state: InterpreterState;
+    fs: IFileSystem;
+    commands: CommandRegistry;
+    /** Execution limits configuration */
+    limits: Required<ExecutionLimits>;
+    /** Shared security accounting for this top-level execution and descendants. */
+    executionScope: ExecutionScope;
+    execFn: (script: string, options?: InterpreterExecOptions, stdinAlreadyAccounted?: boolean) => Promise<ExecResult>;
+    executeScript: (node: ScriptNode) => Promise<ExecResult>;
+    executeStatement: (node: StatementNode) => Promise<ExecResult>;
+    /**
+     * `stdinOwned` says the caller gave this command its own fd 0, even when the
+     * content is the empty string (`f < empty-file`). Without it an empty stdin
+     * is indistinguishable from "no redirection", and the command would fall
+     * back to the enclosing shell's stdin instead of seeing EOF.
+     */
+    executeCommand: (node: CommandNode, stdin: string, stdinOwned?: 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;
+    /** Current command substitution nesting depth (for limit enforcement) */
+    substitutionDepth?: number;
+    /** Optional feature coverage writer for fuzzing instrumentation */
+    coverage?: FeatureCoverageWriter;
+    /**
+     * When true, interpreter execution must run inside DefenseInDepthBox
+     * sandbox async context. Used to fail closed on context-loss bugs.
+     */
+    requireDefenseContext?: boolean;
+    /**
+     * Bootstrap JavaScript code for js-exec.
+     * Threaded through the context chain instead of shell env.
+     */
+    jsBootstrapCode?: string;
+    /**
+     * Tool invoker hook. When present, js-exec sets up a `tools` proxy that
+     * routes calls through this callback.
+     */
+    invokeTool?: (path: string, argsJson: string) => Promise<string>;
+}