@jerryan/just-bash 3.5.0

package/dist/fs/read-write-fs/read-write-fs.d.ts

@@ -0,0 +1,150 @@
+/**
+ * ReadWriteFs - Direct wrapper around the real filesystem
+ *
+ * All operations go directly to the underlying Node.js filesystem.
+ * Paths are relative to the configured root directory.
+ *
+ * Security: Symlinks are blocked by default (allowSymlinks: false).
+ * All real-FS access goes through resolveAndValidate() / validateParent()
+ * gates which detect symlink traversal via path comparison. When symlinks
+ * are allowed, targets are validated and transformed to stay within root.
+ * New methods must use these gates — never access the real FS directly.
+ */
+import { type ByteString } from "../../encoding.js";
+import { type FileContent } from "../encoding.js";
+import type { CpOptions, DirentEntry, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "../interface.js";
+export interface ReadWriteFsOptions {
+    /**
+     * The root directory on the real filesystem.
+     * All paths are relative to this root.
+     */
+    root: string;
+    /**
+     * Maximum file size in bytes that can be read.
+     * Files larger than this will throw an EFBIG error.
+     * Defaults to 10MB (10485760).
+     */
+    maxFileReadSize?: number;
+    /**
+     * Maximum file size in bytes that metadata operations and append may copy
+     * when isolating a multiply-linked regular file. Defaults to 100MB.
+     * Set to 0 to disable this limit.
+     */
+    maxCopyOnWriteSize?: number;
+    /**
+     * Maximum regular file size in bytes that cp may copy. Defaults to 0
+     * (unlimited) for compatibility with normal filesystem copy behavior.
+     */
+    maxCopySize?: number;
+    /**
+     * Whether to allow following and creating symlinks.
+     * When false (default), any path traversing a symlink is rejected
+     * and symlink() throws EPERM.
+     */
+    allowSymlinks?: boolean;
+}
+export declare class ReadWriteFs implements IFileSystem {
+    private static activeMutationRoots;
+    private static pendingMutations;
+    private readonly root;
+    private readonly canonicalRoot;
+    private readonly maxFileReadSize;
+    private readonly maxCopyOnWriteSize;
+    private readonly maxCopySize;
+    private readonly allowSymlinks;
+    constructor(options: ReadWriteFsOptions);
+    /**
+     * Validate that a resolved real path stays within the sandbox root and
+     * return the canonical (symlink-resolved) path for use in subsequent I/O.
+     * This closes the TOCTOU gap where the original path could be swapped
+     * between validation and use.
+     * Throws EACCES if the path escapes the root.
+     */
+    private resolveAndValidate;
+    /**
+     * Validate the parent directory of a path (for operations like lstat/readlink
+     * that should not follow the final component's symlink).
+     * Returns the canonical parent joined with the original basename.
+     */
+    private validateParent;
+    /**
+     * Convert a virtual path to a real filesystem path.
+     */
+    private toRealPath;
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBytes(path: string): Promise<ByteString>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    private writeFileUnlocked;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    private appendFileUnlocked;
+    private withFilesystemMutation;
+    private static drainMutationQueue;
+    private assertCopyOnWriteSize;
+    private assertCopySize;
+    private randomTransactionToken;
+    /** Open a bounded copy source, avoiding atime updates where permitted. */
+    private openCopySource;
+    /**
+     * Commit file contents by replacing a directory entry, never by mutating
+     * its existing inode. This prevents writes through host-planted hard links
+     * from changing files outside the sandbox.
+     */
+    private replaceFile;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    private mkdirUnlocked;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    private rmUnlocked;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    private cpUnlocked;
+    private copyTreeEntry;
+    private assertCopyDestinationWritable;
+    private replaceSymlink;
+    private toVirtualAbsoluteSymlinkTarget;
+    private preflightCopyTree;
+    mv(src: string, dest: string): Promise<void>;
+    private mvUnlocked;
+    /** Compare canonical path identity, not user-visible lexical spelling. */
+    private isSameOrDescendantIdentity;
+    private uniqueTransactionPath;
+    /**
+     * Transactional EXDEV fallback. The destination is assembled under a hidden
+     * sibling, then committed by rename. Source removal is also staged by rename,
+     * so failures can restore both visible names without claiming atomicity.
+     */
+    private moveAcrossDevices;
+    resolvePath(base: string, path: string): string;
+    getAllPaths(): string[];
+    private sanitizeError;
+    /**
+     * Recursively scan a directory for symlinks whose targets escape the sandbox.
+     * Returns an array of paths (real OS paths) for any escaping symlinks found.
+     */
+    private findEscapingSymlinks;
+    private scanDir;
+    chmod(path: string, mode: number): Promise<void>;
+    private chmodUnlocked;
+    symlink(target: string, linkPath: string): Promise<void>;
+    private symlinkUnlocked;
+    link(existingPath: string, newPath: string): Promise<void>;
+    private linkUnlocked;
+    readlink(path: string): Promise<string>;
+    /**
+     * Resolve all symlinks in a path to get the canonical physical path.
+     * This is equivalent to POSIX realpath().
+     */
+    realpath(path: string): Promise<string>;
+    /**
+     * Set access and modification times of a file
+     * @param path - The file path
+     * @param atime - Access time
+     * @param mtime - Modification time
+     */
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+    private utimesUnlocked;
+}

package/dist/fs/real-fs-utils.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared utilities for real-filesystem-backed IFileSystem implementations
+ * (OverlayFs and ReadWriteFs).
+ *
+ * Security-critical path validation logic lives here so both implementations
+ * stay consistent.
+ *
+ * Pure path utilities (normalizePath, validatePath, dirname, resolvePath, etc.)
+ * live in path-utils.ts (no node:fs dependency, browser-safe) and are
+ * re-exported here for convenience.
+ */
+export { isSameOrDescendantPath, normalizePath, validatePath, } from "./path-utils.js";
+/**
+ * Check whether `resolved` is equal to, or a child of, `canonicalRoot`.
+ * Uses a boundary-safe prefix check (appends `/`) so that `/data` does not
+ * match `/datastore`.
+ */
+export declare function isPathWithinRoot(resolved: string, canonicalRoot: string): boolean;
+/**
+ * Validate that a real filesystem path stays within the sandbox root after
+ * resolving all OS-level symlinks (including in parent components).
+ *
+ * Uses `realpathSync`; when the path does not exist (`ENOENT`) it walks up
+ * to the nearest existing parent.  Returns `false` for any path that escapes
+ * the sandbox (fail-closed on unexpected errors).
+ */
+export declare function validateRealPath(realPath: string, canonicalRoot: string): boolean;
+/**
+ * Resolve a real filesystem path to its canonical form and verify it stays
+ * within the sandbox root.  Returns the canonical path on success, or `null`
+ * if the path escapes the root (fail-closed on unexpected errors).
+ *
+ * Unlike `validateRealPath` (which returns a boolean), this function returns
+ * the canonical path so callers can use it for subsequent I/O, closing the
+ * TOCTOU gap where the original (unresolved) path could be swapped between
+ * validation and use.
+ */
+export declare function resolveCanonicalPath(realPath: string, canonicalRoot: string): string | null;
+/**
+ * Resolve a real filesystem path to its canonical form, verify it stays
+ * within the sandbox root, AND reject the path if any symlinks were
+ * traversed.
+ *
+ * Detection: compare the relative path from `root` (unresolved) with the
+ * relative path from `canonicalRoot` (resolved).  A mismatch means a
+ * symlink was followed somewhere in the path.
+ *
+ * This piggybacks on the `realpathSync` call inside `resolveCanonicalPath`
+ * — the only extra cost is one string comparison.
+ */
+export declare function resolveCanonicalPathNoSymlinks(realPath: string, root: string, canonicalRoot: string): string | null;
+/**
+ * Validate that a root directory exists and is actually a directory.
+ * Throws with a descriptive message including `fsName` (e.g. "OverlayFs",
+ * "ReadWriteFs") on failure.  Does NOT include the real root path in the
+ * error message to prevent information leakage.
+ */
+export declare function validateRootDirectory(root: string, fsName: string): void;
+export { sanitizeErrorMessage } from "./sanitize-error.js";
+/**
+ * Sanitize a raw OS symlink target so it does not leak real filesystem paths
+ * outside the sandbox.
+ *
+ * - Relative targets are returned as-is (they don't leak real paths).
+ * - Absolute targets that resolve within the canonical root are converted to
+ *   a path relative to the root (the caller decides how to present it).
+ * - Absolute targets outside the root are reduced to `basename` only.
+ *
+ * Returns `{ withinRoot: true, relativePath }` when the target is inside the
+ * sandbox, or `{ withinRoot: false, safeName }` when it is outside.
+ */
+export declare function sanitizeSymlinkTarget(rawTarget: string, canonicalRoot: string): {
+    withinRoot: true;
+    relativePath: string;
+} | {
+    withinRoot: false;
+    safeName: string;
+};
+/**
+ * Sanitize an error thrown during real-FS operations to prevent leaking
+ * real OS paths.  Node.js ErrnoException objects contain a `.path` property
+ * with the real filesystem path — this must never reach the sandbox user.
+ *
+ * Errors whose `.path` is `undefined` are our own errors (constructed with
+ * `new Error(...)`) rather than Node.js ErrnoExceptions.  If their message
+ * contains one of `passthroughPatterns`, they are rethrown as-is (they
+ * already contain safe virtual paths).  All other errors are replaced with
+ * a generic `"CODE: operation 'virtualPath'"` message.
+ */
+export declare function sanitizeFsError(e: unknown, virtualPath: string, operation: string, passthroughPatterns: readonly string[]): never;

package/dist/fs/sanitize-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Error message sanitization utility.
+ *
+ * This module has NO Node.js dependencies (no `node:fs`, etc.) so it can
+ * safely be imported in browser bundles.
+ */
+/**
+ * Sanitize an error message to strip common real OS paths and stack traces.
+ *
+ * Preserves virtual paths that don't match the common host prefixes used by
+ * the default runtime.
+ */
+export declare function sanitizeErrorMessage(message: string): string;
+/**
+ * Aggressive sanitizer for host-originated errors such as worker/bootstrap
+ * failures. This also scrubs file:// URLs and additional runtime roots that
+ * are common in hosted environments.
+ */
+export declare function sanitizeHostErrorMessage(message: string): string;

package/dist/fs/traversal.d.ts

@@ -0,0 +1,98 @@
+import type { CommandExecutionBudget } from "../execution-scope.js";
+import type { ExecutionLimits } from "../limits.js";
+import type { FsStat, IFileSystem } from "./interface.js";
+declare const canonicalPathBrand: unique symbol;
+/** A canonical virtual path proven to be inside a particular validation root. */
+export type CanonicalPath<Policy extends string = string> = string & {
+    readonly [canonicalPathBrand]: Policy;
+};
+export interface CanonicalPathPolicy<Policy extends string> {
+    readonly name: Policy;
+    readonly root: string;
+}
+export declare function canonicalizePath<Policy extends string>(fs: IFileSystem, path: string, policy: CanonicalPathPolicy<Policy>): Promise<CanonicalPath<Policy>>;
+export declare class FileSystemPolicyError extends Error {
+    readonly operation: string;
+    readonly virtualPath: string;
+    readonly name = "FileSystemPolicyError";
+    constructor(operation: string, virtualPath: string, message: string);
+}
+export type SameFileResult = "same" | "different" | "unknown";
+export type PathContainmentResult = "inside" | "outside" | "unknown";
+export type ResolvedFileIdentity = {
+    readonly existence: "existing";
+    readonly canonicalPath?: string;
+    readonly stableIdentity?: string;
+} | {
+    readonly existence: "missing";
+    /** Canonical nearest-existing parent plus every missing path component. */
+    readonly canonicalPath?: string;
+} | {
+    readonly existence: "unknown";
+};
+/**
+ * Resolve an existing path to both its canonical spelling and, where the
+ * backend supports it, an alias-resistant identity. For a path that does not
+ * exist, canonicalize the nearest existing parent and append all missing
+ * components. Other failures remain unknown rather than being treated as
+ * non-existence.
+ */
+export declare function resolveFileIdentity(fs: IFileSystem, path: string, budget?: FileTraversalBudget): Promise<ResolvedFileIdentity>;
+/**
+ * Conservatively compare two paths. `unknown` forces destructive callers to
+ * stage work instead of treating an inability to prove identity as inequality.
+ */
+export declare function compareFileIdentity(fs: IFileSystem, left: string, right: string): Promise<SameFileResult>;
+/**
+ * Resolve an existing destination or its nearest existing parent before a
+ * recursive copy/move. This closes lexical-prefix gaps created by directory
+ * aliases while retaining `unknown` for backends that cannot prove it.
+ */
+export declare function compareCanonicalContainment(fs: IFileSystem, sourceDirectory: string, destination: string, budget?: FileTraversalBudget): Promise<PathContainmentResult>;
+export type SymlinkTraversalPolicy = "never" | "follow";
+export interface TraversalBudgetOptions {
+    readonly limits: Required<ExecutionLimits>;
+    readonly signal?: AbortSignal;
+    readonly executionScope?: CommandExecutionBudget;
+    readonly site: string;
+    /** User-facing resource name for commands with established diagnostics. */
+    readonly label?: string;
+}
+/** One shared, command-local view over the top-level execution work budget. */
+export declare class FileTraversalBudget {
+    private readonly options;
+    private entries;
+    private discoveredEntries;
+    private work;
+    constructor(options: TraversalBudgetOptions);
+    checkpoint(work?: number): void;
+    visit(depth: number): void;
+    /**
+     * Reserve directory children before retaining work items for them. A single
+     * readdir can return far more entries than the traversal is allowed to
+     * process, so waiting until each child is visited permits an oversized queue
+     * allocation first.
+     */
+    discover(count: number): void;
+}
+export interface TraversalEntry {
+    readonly path: string;
+    readonly depth: number;
+    readonly stat: FsStat;
+    readonly isSymlink: boolean;
+    readonly phase: "enter" | "leave";
+}
+export interface TraverseFileTreeOptions extends TraversalBudgetOptions {
+    readonly fs: IFileSystem;
+    readonly root: string;
+    readonly symlinks?: SymlinkTraversalPolicy;
+    readonly includeLeave?: boolean;
+    readonly budget?: FileTraversalBudget;
+}
+/**
+ * Iterative, deterministic DFS. Directory identities stay active until their
+ * leave marker, detecting ancestor symlink cycles without suppressing valid
+ * aliases in separate branches.
+ */
+export declare function traverseFileTree(options: TraverseFileTreeOptions, visitor: (entry: TraversalEntry) => void | Promise<void>): Promise<void>;
+export {};

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+export { AgentSandbox, type AgentSandboxOptions, createAgentSandbox, type SandboxChangeSet, type SandboxWrite, } from "./agent-sandbox.js";
+export type { CommandNode, PipelineNode, ScriptNode, SimpleCommandNode, StatementNode, WordNode, } from "./ast/types.js";
+export type { BashLogger, BashOptions, ExecOptions, JavaScriptConfig, } from "./Bash.js";
+export { Bash } from "./Bash.js";
+export type { AllCommandName, CommandName, JavaScriptCommandName, NetworkCommandName, PythonCommandName, } from "./commands/registry.js";
+export { getCommandNames, getJavaScriptCommandNames, getNetworkCommandNames, getPythonCommandNames, } from "./commands/registry.js";
+export type { CommandContextOptions, CustomCommand, LazyCommand, } from "./custom-commands.js";
+export { createCommandContext, defineCommand, } from "./custom-commands.js";
+export type { ByteString, OutputKind } from "./encoding.js";
+export { bytesOutput, decodeBytesToUtf8, EMPTY_BYTES, encodeUtf8ToBytes, latin1FromBytes, stdoutAsBytes, stdoutKind, textOutput, unsafeBytesFromLatin1, } from "./encoding.js";
+export { InMemoryFs } from "./fs/in-memory-fs/index.js";
+export type { BufferEncoding, CpOptions, DirectoryEntry, FileContent, FileEntry, FileInit, FileSystemFactory, FsEntry, FsStat, InitialFiles, LazyFileEntry, LazyFileProvider, MkdirOptions, RmOptions, SymlinkEntry, } from "./fs/interface.js";
+export { MountableFs, type MountableFsOptions, type MountConfig, } from "./fs/mountable-fs/index.js";
+export { type OverlayDiff, OverlayFs, type OverlayFsOptions, type OverlayNodeType, type OverlayWrite, } from "./fs/overlay-fs/index.js";
+export { ReadWriteFs, type ReadWriteFsOptions, } from "./fs/read-write-fs/index.js";
+export type { AllowedUrl, AllowedUrlEntry, NetworkConfig, RequestTransform, SecureFetch, } from "./network/index.js";
+export { NetworkAccessDeniedError, RedirectNotAllowedError, TooManyRedirectsError, } from "./network/index.js";
+export { parse } from "./parser/parser.js";
+export type { CommandFinished as SandboxCommandFinished, OutputMessage, SandboxOptions, WriteFilesInput, } from "./sandbox/index.js";
+export { Command as SandboxCommand, Sandbox } from "./sandbox/index.js";
+export type { DefenseInDepthConfig, DefenseInDepthHandle, DefenseInDepthStats, DefenseInDepthStatus, SecurityViolation, SecurityViolationType, } from "./security/index.js";
+export { createConsoleViolationCallback, DefenseInDepthBox, SecurityViolationError, SecurityViolationLogger, } from "./security/index.js";
+export { BashTransformPipeline } from "./transform/pipeline.js";
+export type { CommandCollectorMetadata } from "./transform/plugins/command-collector.js";
+export { CommandCollectorPlugin } from "./transform/plugins/command-collector.js";
+export type { TeeFileInfo, TeePluginMetadata, TeePluginOptions, } from "./transform/plugins/tee-plugin.js";
+export { TeePlugin } from "./transform/plugins/tee-plugin.js";
+export { serialize } from "./transform/serialize.js";
+export type { BashTransformResult, TransformContext, TransformPlugin, TransformResult, } from "./transform/types.js";
+export type { BashExecResult, Command, CommandAnalysis, CommandContext, ExecResult, IFileSystem, ResolvedCommandContext, } from "./types.js";

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { AgentSandbox, type AgentSandboxOptions, createAgentSandbox, type SandboxChangeSet, type SandboxWrite, } from "./agent-sandbox.js";
+export type { CommandNode, PipelineNode, ScriptNode, SimpleCommandNode, StatementNode, WordNode, } from "./ast/types.js";
+export type { BashLogger, BashOptions, ExecOptions, JavaScriptConfig, } from "./Bash.js";
+export { Bash } from "./Bash.js";
+export type { AllCommandName, CommandName, JavaScriptCommandName, NetworkCommandName, PythonCommandName, } from "./commands/registry.js";
+export { getCommandNames, getJavaScriptCommandNames, getNetworkCommandNames, getPythonCommandNames, } from "./commands/registry.js";
+export type { CommandContextOptions, CustomCommand, LazyCommand, } from "./custom-commands.js";
+export { createCommandContext, defineCommand, } from "./custom-commands.js";
+export type { ByteString, OutputKind } from "./encoding.js";
+export { bytesOutput, decodeBytesToUtf8, EMPTY_BYTES, encodeUtf8ToBytes, latin1FromBytes, stdoutAsBytes, stdoutKind, textOutput, unsafeBytesFromLatin1, } from "./encoding.js";
+export { InMemoryFs } from "./fs/in-memory-fs/index.js";
+export type { BufferEncoding, CpOptions, DirectoryEntry, FileContent, FileEntry, FileInit, FileSystemFactory, FsEntry, FsStat, InitialFiles, LazyFileEntry, LazyFileProvider, MkdirOptions, RmOptions, SymlinkEntry, } from "./fs/interface.js";
+export { MountableFs, type MountableFsOptions, type MountConfig, } from "./fs/mountable-fs/index.js";
+export { type OverlayDiff, OverlayFs, type OverlayFsOptions, type OverlayNodeType, type OverlayWrite, } from "./fs/overlay-fs/index.js";
+export { ReadWriteFs, type ReadWriteFsOptions, } from "./fs/read-write-fs/index.js";
+export type { AllowedUrl, AllowedUrlEntry, NetworkConfig, RequestTransform, SecureFetch, } from "./network/index.js";
+export { NetworkAccessDeniedError, RedirectNotAllowedError, TooManyRedirectsError, } from "./network/index.js";
+export { parse } from "./parser/parser.js";
+export type { CommandFinished as SandboxCommandFinished, OutputMessage, SandboxOptions, WriteFilesInput, } from "./sandbox/index.js";
+export { Command as SandboxCommand, Sandbox } from "./sandbox/index.js";
+export type { DefenseInDepthConfig, DefenseInDepthHandle, DefenseInDepthStats, DefenseInDepthStatus, SecurityViolation, SecurityViolationType, } from "./security/index.js";
+export { createConsoleViolationCallback, DefenseInDepthBox, SecurityViolationError, SecurityViolationLogger, } from "./security/index.js";
+export { BashTransformPipeline } from "./transform/pipeline.js";
+export type { CommandCollectorMetadata } from "./transform/plugins/command-collector.js";
+export { CommandCollectorPlugin } from "./transform/plugins/command-collector.js";
+export type { TeeFileInfo, TeePluginMetadata, TeePluginOptions, } from "./transform/plugins/tee-plugin.js";
+export { TeePlugin } from "./transform/plugins/tee-plugin.js";
+export { serialize } from "./transform/serialize.js";
+export type { BashTransformResult, TransformContext, TransformPlugin, TransformResult, } from "./transform/types.js";
+export type { BashExecResult, Command, CommandAnalysis, CommandContext, ExecResult, IFileSystem, ResolvedCommandContext, } from "./types.js";

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

@@ -0,0 +1,27 @@
+/**
+ * Alias Expansion
+ *
+ * Handles bash alias expansion for SimpleCommandNodes.
+ *
+ * Alias expansion rules:
+ * 1. Only expands if command name is a literal unquoted word
+ * 2. Alias value is substituted for the command name
+ * 3. If alias value ends with a space, the next word is also checked for alias expansion
+ * 4. Recursive expansion is allowed but limited to prevent infinite loops
+ */
+import type { SimpleCommandNode } from "../ast/types.js";
+/**
+ * Context needed for alias expansion operations
+ */
+export interface AliasExpansionContext {
+    env: Map<string, string>;
+    limits: {
+        maxCallDepth: number;
+        maxStringLength: number;
+    };
+}
+/**
+ * Expand alias in a SimpleCommandNode if applicable.
+ * Returns a new node with the alias expanded, or the original node if no expansion.
+ */
+export declare function expandAlias(ctx: AliasExpansionContext, node: SimpleCommandNode, aliasExpansionStack: Set<string>): SimpleCommandNode;

package/dist/interpreter/arithmetic.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Arithmetic Evaluation
+ *
+ * Evaluates bash arithmetic expressions including:
+ * - Basic operators (+, -, *, /, %)
+ * - Comparison operators (<, <=, >, >=, ==, !=)
+ * - Bitwise operators (&, |, ^, ~, <<, >>)
+ * - Logical operators (&&, ||, !)
+ * - Assignment operators (=, +=, -=, etc.)
+ * - Ternary operator (? :)
+ * - Pre/post increment/decrement (++, --)
+ * - Nested arithmetic: $((expr))
+ * - Command substitution: $(cmd) or `cmd`
+ *
+ * Known limitations:
+ * - Bitwise operations use JavaScript's 32-bit signed integers, not 64-bit.
+ *   This means values like (1 << 31) will be negative (-2147483648) instead
+ *   of the bash 64-bit result (2147483648).
+ * - Dynamic arithmetic expressions (e.g., ${base}#a where base=16) are not
+ *   fully supported - variable expansion happens at parse time, not runtime.
+ */
+import type { ArithExpr } from "../ast/types.js";
+import type { InterpreterContext } from "./types.js";
+export declare function evaluateArithmetic(ctx: InterpreterContext, expr: ArithExpr, isExpansionContext?: boolean): Promise<number>;

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

@@ -0,0 +1,24 @@
+/**
+ * Assignment Expansion Helpers
+ *
+ * Handles expansion of assignment arguments for local/declare/typeset builtins.
+ * - Array assignments: name=(elem1 elem2 ...)
+ * - Scalar assignments: name=value, name+=value, name[index]=value
+ */
+import type { WordNode } from "../ast/types.js";
+import type { InterpreterContext } from "./types.js";
+/**
+ * Check if a Word represents an array assignment (name=(...)) and expand it
+ * while preserving quote structure for elements.
+ * Returns the expanded string like "name=(elem1 elem2 ...)" or null if not an array assignment.
+ */
+export declare function expandLocalArrayAssignment(ctx: InterpreterContext, word: WordNode): Promise<string | null>;
+/**
+ * Check if a Word represents a scalar assignment (name=value, name+=value, or name[index]=value)
+ * and expand it WITHOUT glob expansion on the value part.
+ * Returns the expanded string like "name=expanded_value" or null if not a scalar assignment.
+ *
+ * This is important for bash compatibility: `local var=$x` where x='a b' should
+ * set var to "a b", not try to glob-expand it.
+ */
+export declare function expandScalarAssignmentArg(ctx: InterpreterContext, word: WordNode): Promise<string | null>;

package/dist/interpreter/builtin-dispatch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Builtin Command Dispatch
+ *
+ * Handles dispatch of built-in shell commands like export, unset, cd, etc.
+ * Separated from interpreter.ts for modularity.
+ */
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+/**
+ * Type for the function that runs a command recursively
+ */
+export type RunCommandFn = (commandName: string, args: string[], quotedArgs: boolean[], stdin: string, skipFunctions?: boolean, useDefaultPath?: boolean, stdinSourceFd?: number, stdinRedirected?: boolean) => Promise<ExecResult>;
+/**
+ * Type for the function that builds exported environment
+ */
+export type BuildExportedEnvFn = () => Record<string, string>;
+/**
+ * Type for the function that executes user scripts
+ */
+export type ExecuteUserScriptFn = (scriptPath: string, args: string[], stdin?: string) => Promise<ExecResult>;
+/**
+ * Dispatch context containing dependencies needed for builtin dispatch
+ */
+export interface BuiltinDispatchContext {
+    ctx: InterpreterContext;
+    runCommand: RunCommandFn;
+    buildExportedEnv: BuildExportedEnvFn;
+    executeUserScript: ExecuteUserScriptFn;
+}
+/**
+ * Dispatch a command to the appropriate builtin handler or external command.
+ * Returns null if the command should be handled by external command resolution.
+ */
+export declare function dispatchBuiltin(dispatchCtx: BuiltinDispatchContext, commandName: string, args: string[], _quotedArgs: boolean[], stdin: string, skipFunctions: boolean, _useDefaultPath: boolean, stdinSourceFd: number, 
+/**
+ * True when a redirection gave this command its own fd 0. `stdin` alone
+ * cannot express it: `cmd < empty-file` and an unredirected command both
+ * arrive as `""`, but only the first means EOF rather than "inherit the
+ * shell's stdin".
+ */
+stdinRedirected?: boolean): Promise<ExecResult | null>;
+/**
+ * Handle external command resolution and execution.
+ * Called when dispatchBuiltin returns null.
+ */
+export declare function executeExternalCommand(dispatchCtx: BuiltinDispatchContext, commandName: string, args: string[], stdin: string, useDefaultPath: boolean): Promise<ExecResult>;

package/dist/interpreter/builtins/break.d.ts

@@ -0,0 +1,6 @@
+/**
+ * break - Exit from loops builtin
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+export declare function handleBreak(ctx: InterpreterContext, args: string[]): ExecResult;

package/dist/interpreter/builtins/cd.d.ts

@@ -0,0 +1,6 @@
+/**
+ * cd - Change directory builtin
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+export declare function handleCd(ctx: InterpreterContext, args: string[]): Promise<ExecResult>;

package/dist/interpreter/builtins/compgen.d.ts

@@ -0,0 +1,26 @@
+/**
+ * compgen - Generate completion matches
+ *
+ * Usage:
+ *   compgen -v [prefix]         - List variable names (optionally starting with prefix)
+ *   compgen -A variable [prefix] - Same as -v
+ *   compgen -A function [prefix] - List function names
+ *   compgen -e [prefix]          - List exported variable names
+ *   compgen -A builtin [prefix]  - List builtin command names
+ *   compgen -A keyword [prefix]  - List shell keywords (alias: -k)
+ *   compgen -A alias [prefix]    - List alias names
+ *   compgen -A shopt [prefix]    - List shopt options
+ *   compgen -A helptopic [prefix] - List help topics
+ *   compgen -A directory [prefix] - List directory names
+ *   compgen -A file [prefix]      - List file names
+ *   compgen -f [prefix]           - List file names (alias for -A file)
+ *   compgen -A user               - List user names
+ *   compgen -A command [prefix]   - List commands (builtins, functions, aliases, external)
+ *   compgen -W wordlist [prefix]  - Generate from wordlist
+ *   compgen -P prefix             - Prefix to add to completions
+ *   compgen -S suffix             - Suffix to add to completions
+ *   compgen -o option             - Completion option (plusdirs, dirnames, default, etc.)
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+export declare function handleCompgen(ctx: InterpreterContext, args: string[]): Promise<ExecResult>;

package/dist/interpreter/builtins/complete.d.ts

@@ -0,0 +1,17 @@
+/**
+ * complete - Set and display programmable completion specifications
+ *
+ * Usage:
+ *   complete                        - List all completion specs
+ *   complete -p                     - Print all completion specs in reusable format
+ *   complete -p cmd                 - Print completion spec for specific command
+ *   complete -W 'word1 word2' cmd   - Set word list completion for cmd
+ *   complete -F func cmd            - Set function completion for cmd
+ *   complete -r cmd                 - Remove completion spec for cmd
+ *   complete -r                     - Remove all completion specs
+ *   complete -D ...                 - Set default completion (for commands with no specific spec)
+ *   complete -o opt cmd             - Set completion options (nospace, filenames, default, etc.)
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+export declare function handleComplete(ctx: InterpreterContext, args: string[]): ExecResult;

package/dist/interpreter/builtins/compopt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * compopt - Modify completion options
+ *
+ * Usage:
+ *   compopt [-o option] [+o option] [name ...]
+ *   compopt -D [-o option] [+o option]
+ *   compopt -E [-o option] [+o option]
+ *
+ * Modifies completion options for the specified commands (names) or the
+ * currently executing completion when no names are provided.
+ *
+ * Options:
+ *   -o option  Enable completion option
+ *   +o option  Disable completion option
+ *   -D         Apply to default completion
+ *   -E         Apply to empty-line completion
+ *
+ * Valid completion options:
+ *   bashdefault, default, dirnames, filenames, noquote, nosort, nospace, plusdirs
+ *
+ * Returns:
+ *   0 on success
+ *   1 if not in a completion function and no command name is given
+ *   2 if an invalid option is specified
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+export declare function handleCompopt(ctx: InterpreterContext, args: string[]): ExecResult;

package/dist/interpreter/builtins/continue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * continue - Skip to next loop iteration builtin
+ */
+import type { ExecResult } from "../../types.js";
+import type { InterpreterContext } from "../types.js";
+export declare function handleContinue(ctx: InterpreterContext, args: string[]): ExecResult;