just-bash 1.0.0

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

package/dist/interpreter/redirections.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+import type { RedirectionNode } from "../ast/types.js";
+import type { ExecResult } from "../types.js";
+import type { InterpreterContext } from "./types.js";
+export declare function applyRedirections(ctx: InterpreterContext, result: ExecResult, redirections: RedirectionNode[]): Promise<ExecResult>;

package/dist/interpreter/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Interpreter Types
+ */
+import type { CommandNode, FunctionDefNode, ScriptNode, StatementNode } 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 } from "../types.js";
+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;
+}
+export interface InterpreterState {
+    env: Record<string, string>;
+    cwd: string;
+    previousDir: string;
+    functions: Map<string, FunctionDefNode>;
+    localScopes: Map<string, string | undefined>[];
+    callDepth: number;
+    /** Current source script nesting depth (for return in sourced scripts) */
+    sourceDepth: number;
+    commandCount: number;
+    lastExitCode: number;
+    /** Last argument of previous command, for $_ expansion */
+    lastArg: string;
+    /** Shell options (set -e, etc.) */
+    options: ShellOptions;
+    /** True when executing condition for if/while/until (errexit doesn't apply) */
+    inCondition: boolean;
+    /** Current loop nesting depth (for break/continue) */
+    loopDepth: number;
+    /** Stdin available for commands in compound commands (groups, subshells, while loops with piped input) */
+    groupStdin?: string;
+    /** Set of variable names that are readonly */
+    readonlyVars?: Set<string>;
+    /** Exit code from expansion errors (arithmetic, etc.) - overrides command exit code */
+    expansionExitCode?: number;
+    /** Stderr from expansion errors */
+    expansionStderr?: string;
+    /** Set of variable names that are associative arrays */
+    associativeArrays?: Set<string>;
+}
+export interface InterpreterContext {
+    state: InterpreterState;
+    fs: IFileSystem;
+    commands: CommandRegistry;
+    /** Execution limits configuration */
+    limits: Required<ExecutionLimits>;
+    execFn: (script: string, options?: {
+        env?: Record<string, string>;
+        cwd?: string;
+    }) => Promise<ExecResult>;
+    executeScript: (node: ScriptNode) => Promise<ExecResult>;
+    executeStatement: (node: StatementNode) => Promise<ExecResult>;
+    executeCommand: (node: CommandNode, stdin: string) => 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>;
+}

package/dist/limits.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Execution Limits Configuration
+ *
+ * Centralized configuration for all execution limits to prevent runaway compute.
+ * These limits can be overridden when creating a BashEnv instance.
+ */
+/**
+ * Configuration for execution limits.
+ * All limits are optional - undefined values use defaults.
+ */
+export interface ExecutionLimits {
+    /** Maximum function call/recursion depth (default: 100) */
+    maxCallDepth?: number;
+    /** Maximum number of commands to execute (default: 10000) */
+    maxCommandCount?: number;
+    /** Maximum loop iterations for bash while/for/until loops (default: 10000) */
+    maxLoopIterations?: number;
+    /** Maximum loop iterations for AWK while/for loops (default: 10000) */
+    maxAwkIterations?: number;
+    /** Maximum command iterations for SED (branch loops) (default: 10000) */
+    maxSedIterations?: number;
+}
+/**
+ * Resolve execution limits by merging user-provided limits with defaults.
+ */
+export declare function resolveLimits(userLimits?: ExecutionLimits): Required<ExecutionLimits>;

package/dist/network/allow-list/shared.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared utilities for allow-list e2e tests
+ *
+ * This module provides:
+ * - Mock fetch implementation with predefined responses
+ * - Environment adapters for BashEnv and Sandbox
+ * - Test utilities like expectBlocked
+ */
+import { vi } from "vitest";
+import type { BashOptions } from "../../Bash.js";
+export declare const MOCK_SUCCESS_BODY: string;
+export declare const MOCK_USERS_BODY: string;
+export declare const MOCK_POSTS_BODY: string;
+export declare const MOCK_FILE_BODY: string;
+export declare const MOCK_EVIL_BODY: string;
+export declare const originalFetch: typeof fetch;
+export declare function createMockFetch(): ReturnType<typeof vi.fn<typeof fetch>>;
+/**
+ * Environment adapter interface for running tests with both BashEnv and Sandbox
+ */
+export interface EnvAdapter {
+    exec(cmd: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    readFile(path: string): Promise<string>;
+}
+/**
+ * Creates an adapter for BashEnv
+ */
+export declare function createBashEnvAdapter(options: BashOptions): EnvAdapter;
+/**
+ * Creates an adapter for Sandbox
+ */
+export declare function createSandboxAdapter(options: BashOptions): Promise<EnvAdapter>;
+export type AdapterFactory = (options: BashOptions) => EnvAdapter | Promise<EnvAdapter>;
+/**
+ * Utility for testing that a URL is blocked
+ */
+export declare function expectBlocked(env: EnvAdapter, url: string, expectedUrl?: string): Promise<void>;
+/**
+ * Utility for testing that a URL succeeds with expected mock response
+ */
+export declare function expectAllowed(env: EnvAdapter, url: string, expectedBody: string): Promise<void>;

package/dist/network/allow-list.d.ts

@@ -0,0 +1,51 @@
+/**
+ * URL allow-list matching
+ *
+ * This module provides URL allow-list matching that is enforced at the fetch layer,
+ * independent of any parsing or user input manipulation.
+ */
+/**
+ * Parses a URL string into its components.
+ * Returns null if the URL is invalid.
+ */
+export declare function parseUrl(urlString: string): {
+    origin: string;
+    pathname: string;
+    href: string;
+} | null;
+/**
+ * Normalizes an allow-list entry for consistent matching.
+ * - Removes trailing slashes from origins without paths
+ * - Preserves path prefixes as-is
+ */
+export declare function normalizeAllowListEntry(entry: string): {
+    origin: string;
+    pathPrefix: string;
+} | null;
+/**
+ * Checks if a URL matches an allow-list entry.
+ *
+ * The matching rules are:
+ * 1. Origins must match exactly (case-sensitive for scheme and host)
+ * 2. The URL's path must start with the allow-list entry's path
+ * 3. If the allow-list entry has no path (or just "/"), all paths are allowed
+ *
+ * @param url The URL to check (as a string)
+ * @param allowedEntry The allow-list entry to match against
+ * @returns true if the URL matches the allow-list entry
+ */
+export declare function matchesAllowListEntry(url: string, allowedEntry: string): boolean;
+/**
+ * Checks if a URL is allowed by any entry in the allow-list.
+ *
+ * @param url The URL to check
+ * @param allowedUrlPrefixes The list of allowed URL prefixes
+ * @returns true if the URL is allowed
+ */
+export declare function isUrlAllowed(url: string, allowedUrlPrefixes: string[]): boolean;
+/**
+ * Validates an allow-list configuration.
+ * Each entry must be a full origin (scheme + host), optionally followed by a path prefix.
+ * Returns an array of error messages for invalid entries.
+ */
+export declare function validateAllowList(allowedUrlPrefixes: string[]): string[];

package/dist/network/fetch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Secure fetch wrapper with allow-list enforcement
+ *
+ * This module provides a fetch wrapper that:
+ * 1. Enforces URL allow-list at the fetch layer (not subject to parsing)
+ * 2. Handles redirects manually to check each redirect target against the allow-list
+ * 3. Provides timeout support
+ */
+import { type FetchResult, type NetworkConfig } from "./types.js";
+export interface SecureFetchOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    followRedirects?: boolean;
+    /** Override timeout for this request (capped at global timeout) */
+    timeoutMs?: number;
+}
+/**
+ * Type for the secure fetch function
+ */
+export type SecureFetch = (url: string, options?: SecureFetchOptions) => Promise<FetchResult>;
+/**
+ * Creates a secure fetch function that enforces the allow-list.
+ */
+export declare function createSecureFetch(config: NetworkConfig): SecureFetch;

package/dist/network/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Network module
+ *
+ * Provides secure network access with URL allow-list enforcement.
+ */
+export { createSecureFetch, type SecureFetch, type SecureFetchOptions, } from "./fetch.js";
+export { type FetchResult, type HttpMethod, NetworkAccessDeniedError, type NetworkConfig, RedirectNotAllowedError, TooManyRedirectsError, } from "./types.js";

package/dist/network/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Network configuration types
+ *
+ * Network access is disabled by default. To enable network access (e.g., for curl),
+ * you must explicitly configure allowed URLs.
+ */
+/**
+ * HTTP methods that can be allowed
+ */
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+/**
+ * Configuration for network access
+ */
+export interface NetworkConfig {
+    /**
+     * List of allowed URL prefixes. Each entry must be a full origin (scheme + host),
+     * optionally followed by a path prefix:
+     * - An origin: "https://api.example.com" - allows all paths on this origin
+     * - An origin + path prefix: "https://api.example.com/v1/" - allows only paths starting with /v1/
+     *
+     * The check is performed on the full URL, so "https://api.example.com/v1" will allow:
+     * - https://api.example.com/v1
+     * - https://api.example.com/v1/users
+     * - https://api.example.com/v1/users/123
+     *
+     * But NOT:
+     * - https://api.example.com/v2/users
+     * - https://api.example.org/v1/users (different origin)
+     *
+     * Invalid entries (missing scheme, missing host, relative paths) will throw an error.
+     */
+    allowedUrlPrefixes?: string[];
+    /**
+     * List of allowed HTTP methods. Defaults to ["GET", "HEAD"] for safety.
+     * dangerouslyAllowFullInternetAccess to enables all methods.
+     */
+    allowedMethods?: HttpMethod[];
+    /**
+     * Bypass the allow-list and allow all URLs and methods.
+     * DANGEROUS: Only use this in trusted environments.
+     */
+    dangerouslyAllowFullInternetAccess?: boolean;
+    /**
+     * Maximum number of redirects to follow (default: 20)
+     */
+    maxRedirects?: number;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeoutMs?: number;
+}
+/**
+ * Result of a network fetch operation
+ */
+export interface FetchResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    url: string;
+}
+/**
+ * Error thrown when a URL is not allowed
+ */
+export declare class NetworkAccessDeniedError extends Error {
+    constructor(url: string);
+}
+/**
+ * Error thrown when too many redirects occur
+ */
+export declare class TooManyRedirectsError extends Error {
+    constructor(maxRedirects: number);
+}
+/**
+ * Error thrown when a redirect target is not allowed
+ */
+export declare class RedirectNotAllowedError extends Error {
+    constructor(url: string);
+}
+/**
+ * Error thrown when an HTTP method is not allowed
+ */
+export declare class MethodNotAllowedError extends Error {
+    constructor(method: string, allowedMethods: string[]);
+}

package/dist/overlay-fs/OverlayFs.d.ts

@@ -0,0 +1,87 @@
+/**
+ * OverlayFs - Copy-on-write filesystem backed by a real directory
+ *
+ * Reads come from the real filesystem, writes go to an in-memory layer.
+ * Changes don't persist to disk and can't escape the root directory.
+ */
+import type { BufferEncoding, CpOptions, FsStat, IFileSystem, MkdirOptions, ReadFileOptions, RmOptions, WriteFileOptions } from "../fs-interface.js";
+type FileContent = string | Uint8Array;
+export interface OverlayFsOptions {
+    /**
+     * The root directory on the real filesystem.
+     * All paths are relative to this root and cannot escape it.
+     */
+    root: string;
+    /**
+     * The virtual mount point where the root directory appears.
+     * Defaults to "/home/user/project".
+     */
+    mountPoint?: string;
+    /**
+     * If true, all write operations will throw an error.
+     * Useful for truly read-only access to the filesystem.
+     * Defaults to false.
+     */
+    readOnly?: boolean;
+}
+export declare class OverlayFs implements IFileSystem {
+    private readonly root;
+    private readonly mountPoint;
+    private readonly readOnly;
+    private readonly memory;
+    private readonly deleted;
+    constructor(options: OverlayFsOptions);
+    /**
+     * Throws an error if the filesystem is in read-only mode.
+     */
+    private assertWritable;
+    /**
+     * Create directory entries for the mount point path
+     */
+    private createMountPointDirs;
+    /**
+     * Get the mount point for this overlay
+     */
+    getMountPoint(): string;
+    /**
+     * Normalize a virtual path (resolve . and .., ensure starts with /)
+     */
+    private normalizePath;
+    /**
+     * Check if a normalized virtual path is under the mount point.
+     * Returns the relative path within the mount point, or null if not under it.
+     */
+    private getRelativeToMount;
+    /**
+     * Convert a virtual path to a real filesystem path.
+     * Returns null if the path is not under the mount point or would escape the root.
+     */
+    private toRealPath;
+    private dirname;
+    private ensureParentDirs;
+    /**
+     * Check if a path exists in the overlay (memory + real fs - deleted)
+     */
+    private existsInOverlay;
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBuffer(path: string, seen?: Set<string>): Promise<Uint8Array>;
+    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string, seen?: Set<string>): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    private resolveSymlink;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    resolvePath(base: string, path: string): string;
+    getAllPaths(): string[];
+    private scanRealFs;
+    chmod(path: string, mode: number): Promise<void>;
+    symlink(target: string, linkPath: string): Promise<void>;
+    link(existingPath: string, newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+}
+export {};

package/dist/overlay-fs/index.d.ts

@@ -0,0 +1 @@
+export { OverlayFs, type OverlayFsOptions } from "./OverlayFs.js";

package/dist/parser/arithmetic-parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Arithmetic Expression Parser
+ *
+ * Parses bash arithmetic expressions like:
+ * - $((1 + 2))
+ * - $((x++))
+ * - $((a ? b : c))
+ * - $((2#1010))
+ *
+ * All functions take a Parser instance as the first argument for shared state access.
+ */
+import type { ArithExpr, ArithmeticExpressionNode } from "../ast/types.js";
+import type { Parser } from "./parser.js";
+/**
+ * Parse an arithmetic expression string into an AST node
+ */
+export declare function parseArithmeticExpression(_p: Parser, input: string): ArithmeticExpressionNode;
+export declare function parseArithExpr(p: Parser, input: string, pos: number): {
+    expr: ArithExpr;
+    pos: number;
+};
+/**
+ * Parse a number string with various bases (decimal, hex, octal, base#num)
+ */
+export declare function parseArithNumber(str: string): number;

package/dist/parser/command-parser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Command Parser
+ *
+ * Handles parsing of simple commands, redirections, and assignments.
+ */
+import { type RedirectionNode, type SimpleCommandNode } from "../ast/types.js";
+import type { Parser } from "./parser.js";
+export declare function isRedirection(p: Parser): boolean;
+export declare function parseRedirection(p: Parser): RedirectionNode;
+export declare function parseSimpleCommand(p: Parser): SimpleCommandNode;

package/dist/parser/compound-parser.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compound Command Parser
+ *
+ * Handles parsing of compound commands: if, for, while, until, case, subshell, group.
+ */
+import { type CaseNode, type CStyleForNode, type ForNode, type GroupNode, type IfNode, type SubshellNode, type UntilNode, type WhileNode } from "../ast/types.js";
+import type { Parser } from "./parser.js";
+export declare function parseIf(p: Parser): IfNode;
+export declare function parseFor(p: Parser): ForNode | CStyleForNode;
+export declare function parseWhile(p: Parser): WhileNode;
+export declare function parseUntil(p: Parser): UntilNode;
+export declare function parseCase(p: Parser): CaseNode;
+export declare function parseSubshell(p: Parser): SubshellNode | CStyleForNode;
+export declare function parseGroup(p: Parser): GroupNode;

package/dist/parser/conditional-parser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Conditional Expression Parser
+ *
+ * Handles parsing of [[ ... ]] conditional commands.
+ */
+import type { ConditionalExpressionNode } from "../ast/types.js";
+import type { Parser } from "./parser.js";
+export declare function parseConditionalExpression(p: Parser): ConditionalExpressionNode;

package/dist/parser/expansion-parser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Expansion Parser
+ *
+ * Handles parsing of parameter expansions, arithmetic expansions, etc.
+ */
+import { type WordPart } from "../ast/types.js";
+import type { Parser } from "./parser.js";
+export declare function parseWordParts(p: Parser, value: string, quoted?: boolean, singleQuoted?: boolean, isAssignment?: boolean, hereDoc?: boolean, 
+/** When true, single quotes are treated as literal characters, not quote delimiters */
+singleQuotesAreLiteral?: boolean): WordPart[];