just-binary 2.9.8

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

@@ -0,0 +1,20 @@
+/**
+ * Statement execution helpers for the interpreter.
+ *
+ * Consolidates the common pattern of executing a list of statements
+ * and accumulating their output.
+ */
+import type { StatementNode } from "../../ast/types.js";
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+/**
+ * Execute a list of statements and accumulate their output.
+ * Handles scope exit errors (break, continue, return) and errexit properly.
+ *
+ * @param ctx - Interpreter context
+ * @param statements - Statements to execute
+ * @param initialStdout - Initial stdout to prepend (default EMPTY)
+ * @param initialStderr - Initial stderr to prepend (default EMPTY)
+ * @returns Accumulated stdout, stderr, and final exit code
+ */
+export declare function executeStatements(ctx: InterpreterContext, statements: StatementNode[], initialStdout?: Uint8Array, initialStderr?: Uint8Array): Promise<ExecResult>;

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

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

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

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

package/dist/interpreter/helpers/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

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

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

@@ -0,0 +1,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/word-parts.d.ts

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

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

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

package/dist/interpreter/index.d.ts

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

package/dist/interpreter/interpreter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Interpreter - AST Execution Engine
+ *
+ * Main interpreter class that executes bash AST nodes.
+ * Delegates to specialized modules for:
+ * - Word expansion (expansion.ts)
+ * - Arithmetic evaluation (arithmetic.ts)
+ * - Conditional evaluation (conditionals.ts)
+ * - Built-in commands (builtins.ts)
+ * - Redirections (redirections.ts)
+ */
+import type { ScriptNode } from "../ast/types.js";
+import type { IFileSystem } from "../fs/interface.js";
+import type { ExecutionLimits } from "../limits.js";
+import type { SecureFetch } from "../network/index.js";
+import type { CommandRegistry, ExecResult, FeatureCoverageWriter, TraceCallback } from "../types.js";
+import type { InterpreterState } from "./types.js";
+export type { InterpreterContext, InterpreterState } from "./types.js";
+export interface InterpreterOptions {
+    fs: IFileSystem;
+    commands: CommandRegistry;
+    limits: Required<ExecutionLimits>;
+    exec: (script: string, options?: {
+        env?: Record<string, string>;
+        cwd?: string;
+        stdin?: Uint8Array;
+    }) => Promise<ExecResult>;
+    /** Optional secure fetch function for network-enabled commands */
+    fetch?: SecureFetch;
+    /** Optional sleep function for testing with mock clocks */
+    sleep?: (ms: number) => Promise<void>;
+    /** Optional trace callback for performance profiling */
+    trace?: TraceCallback;
+    /** Optional feature coverage writer for fuzzing instrumentation */
+    coverage?: FeatureCoverageWriter;
+}
+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;
+    private aliasExpansionStack;
+    private expandAlias;
+    findCommandInPath(commandName: string): Promise<string[]>;
+    private executeSubshell;
+    private executeGroup;
+    private executeArithmeticCommand;
+    private executeConditionalCommand;
+}

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: Uint8Array) => 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

@@ -0,0 +1,51 @@
+/**
+ * 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 type { InterpreterContext } from "./types.js";
+/**
+ * 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>;

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * 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: Uint8Array, executeStatement: ExecuteStatementFn): Promise<ExecResult>;
+/**
+ * Execute a group node { ...; }.
+ * Runs commands in the current execution environment.
+ */
+export declare function executeGroup(ctx: InterpreterContext, node: GroupNode, stdin: Uint8Array, executeStatement: ExecuteStatementFn): 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: Uint8Array, 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>;