just-binary 2.9.9 → 3.0.0

package/dist/interpreter/errors.d.ts

@@ -8,21 +8,22 @@
  * - errexit: Exit on error (set -e)
  * - nounset: Error on unset variables (set -u)
  *
- * All control flow errors carry stdout/stderr to accumulate output
- * as they propagate through the execution stack.
+ * All control flow errors carry stdout/stderr ByteStreams to accumulate
+ * output as they propagate through the execution stack.
  */
+import type { ByteStream } from "../utils/stream.js";
 /**
  * Base class for all control flow errors.
  * Carries stdout/stderr to preserve output during propagation.
  */
 declare abstract class ControlFlowError extends Error {
-    stdout: Uint8Array;
-    stderr: Uint8Array;
-    constructor(message: string, stdout?: Uint8Array, stderr?: Uint8Array);
+    stdout: ByteStream;
+    stderr: ByteStream;
+    constructor(message: string, stdout?: ByteStream, stderr?: ByteStream);
     /**
      * Prepend output from the current context before re-throwing.
      */
-    prependOutput(stdout: Uint8Array, stderr: Uint8Array): void;
+    prependOutput(stdout: ByteStream, stderr: ByteStream): void;
 }
 /**
  * Error thrown when break is called to exit loops.
@@ -30,7 +31,7 @@ declare abstract class ControlFlowError extends Error {
 export declare class BreakError extends ControlFlowError {
     levels: number;
     readonly name = "BreakError";
-    constructor(levels?: number, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(levels?: number, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown when continue is called to skip to next iteration.
@@ -38,7 +39,7 @@ export declare class BreakError extends ControlFlowError {
 export declare class ContinueError extends ControlFlowError {
     levels: number;
     readonly name = "ContinueError";
-    constructor(levels?: number, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(levels?: number, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown when return is called to exit a function.
@@ -46,7 +47,7 @@ export declare class ContinueError extends ControlFlowError {
 export declare class ReturnError extends ControlFlowError {
     exitCode: number;
     readonly name = "ReturnError";
-    constructor(exitCode?: number, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(exitCode?: number, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown when set -e (errexit) is enabled and a command fails.
@@ -54,7 +55,7 @@ export declare class ReturnError extends ControlFlowError {
 export declare class ErrexitError extends ControlFlowError {
     readonly exitCode: number;
     readonly name = "ErrexitError";
-    constructor(exitCode: number, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(exitCode: number, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown when set -u (nounset) is enabled and an unset variable is referenced.
@@ -62,7 +63,7 @@ export declare class ErrexitError extends ControlFlowError {
 export declare class NounsetError extends ControlFlowError {
     varName: string;
     readonly name = "NounsetError";
-    constructor(varName: string, stdout?: Uint8Array);
+    constructor(varName: string, stdout?: ByteStream);
 }
 /**
  * Error thrown when exit builtin is called to terminate the script.
@@ -70,7 +71,7 @@ export declare class NounsetError extends ControlFlowError {
 export declare class ExitError extends ControlFlowError {
     readonly exitCode: number;
     readonly name = "ExitError";
-    constructor(exitCode: number, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(exitCode: number, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown for arithmetic expression errors (e.g., floating point, invalid syntax).
@@ -83,7 +84,7 @@ export declare class ArithmeticError extends ControlFlowError {
      * If false, the error is recoverable and execution can continue.
      */
     fatal: boolean;
-    constructor(message: string, stdout?: Uint8Array, stderr?: Uint8Array, fatal?: boolean);
+    constructor(message: string, stdout?: ByteStream, stderr?: ByteStream, fatal?: boolean);
 }
 /**
  * Error thrown for bad substitution errors (e.g., ${#var:1:3}).
@@ -91,7 +92,7 @@ export declare class ArithmeticError extends ControlFlowError {
  */
 export declare class BadSubstitutionError extends ControlFlowError {
     readonly name = "BadSubstitutionError";
-    constructor(message: string, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(message: string, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown when failglob is enabled and a glob pattern has no matches.
@@ -99,7 +100,7 @@ export declare class BadSubstitutionError extends ControlFlowError {
  */
 export declare class GlobError extends ControlFlowError {
     readonly name = "GlobError";
-    constructor(pattern: string, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(pattern: string, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown for invalid brace expansions (e.g., mixed case character ranges like {z..A}).
@@ -107,7 +108,7 @@ export declare class GlobError extends ControlFlowError {
  */
 export declare class BraceExpansionError extends ControlFlowError {
     readonly name = "BraceExpansionError";
-    constructor(message: string, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(message: string, stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown when execution limits are exceeded (recursion depth, command count, loop iterations).
@@ -118,7 +119,7 @@ export declare class ExecutionLimitError extends ControlFlowError {
     readonly limitType: "recursion" | "commands" | "iterations" | "string_length" | "glob_operations" | "substitution_depth";
     readonly name = "ExecutionLimitError";
     static readonly EXIT_CODE = 126;
-    constructor(message: string, limitType: "recursion" | "commands" | "iterations" | "string_length" | "glob_operations" | "substitution_depth", stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(message: string, limitType: "recursion" | "commands" | "iterations" | "string_length" | "glob_operations" | "substitution_depth", stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Error thrown when break/continue is called in a subshell that was
@@ -126,7 +127,7 @@ export declare class ExecutionLimitError extends ControlFlowError {
  */
 export declare class SubshellExitError extends ControlFlowError {
     readonly name = "SubshellExitError";
-    constructor(stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(stdout?: ByteStream, stderr?: ByteStream);
 }
 /**
  * Type guard for errors that exit the current scope (return, break, continue).
@@ -135,16 +136,10 @@ export declare class SubshellExitError extends ControlFlowError {
 export declare function isScopeExitError(error: unknown): error is BreakError | ContinueError | ReturnError;
 /**
  * Error thrown when a POSIX special builtin fails in POSIX mode.
- * In POSIX mode (set -o posix), errors in special builtins like
- * shift, set, readonly, export, etc. cause the entire script to exit.
- *
- * Per POSIX 2.8.1 - Consequences of Shell Errors:
- * "A special built-in utility causes an interactive or non-interactive shell
- * to exit when an error occurs."
  */
 export declare class PosixFatalError extends ControlFlowError {
     readonly exitCode: number;
     readonly name = "PosixFatalError";
-    constructor(exitCode: number, stdout?: Uint8Array, stderr?: Uint8Array);
+    constructor(exitCode: number, stdout?: ByteStream, stderr?: ByteStream);
 }
 export {};

package/dist/interpreter/functions.d.ts

@@ -7,6 +7,7 @@
  */
 import type { FunctionDefNode } from "../ast/types.js";
 import type { ExecResult } from "../types.js";
+import { type ByteStream } from "../utils/stream.js";
 import type { InterpreterContext } from "./types.js";
 export declare function executeFunctionDef(ctx: InterpreterContext, node: FunctionDefNode): ExecResult;
-export declare function callFunction(ctx: InterpreterContext, func: FunctionDefNode, args: string[], stdin?: Uint8Array, callLine?: number): Promise<ExecResult>;
+export declare function callFunction(ctx: InterpreterContext, func: FunctionDefNode, args: string[], stdin?: ByteStream, callLine?: number): Promise<ExecResult>;

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

@@ -4,11 +4,12 @@
  * Consolidates the repeated error handling logic used in all loop constructs
  * (for, c-style for, while, until).
  */
+import { type ByteStream } from "../../utils/stream.js";
 export type LoopAction = "break" | "continue" | "rethrow" | "error";
 export interface LoopErrorResult {
     action: LoopAction;
-    stdout: Uint8Array;
-    stderr: Uint8Array;
+    stdout: ByteStream;
+    stderr: ByteStream;
     exitCode?: number;
     error?: unknown;
 }
@@ -21,4 +22,4 @@ export interface LoopErrorResult {
  * @param loopDepth - Current loop nesting depth from ctx.state.loopDepth
  * @returns Result indicating what action the loop should take
  */
-export declare function handleLoopError(error: unknown, stdout: Uint8Array, stderr: Uint8Array, loopDepth: number): LoopErrorResult;
+export declare function handleLoopError(error: unknown, stdout: ByteStream, stderr: ByteStream, loopDepth: number): LoopErrorResult;

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

@@ -3,60 +3,46 @@
  *
  * These helpers reduce verbosity and improve readability when
  * constructing ExecResult objects throughout the interpreter.
+ *
+ * IMPORTANT: stdout/stderr are now ByteStreams (single-use). Use factory
+ * functions like ok() instead of a shared constant — a constant ExecResult
+ * with stream fields breaks the second time it's consumed.
  */
 import type { ExecResult } from "../../types.js";
+import type { ByteStream } from "../../utils/stream.js";
+/**
+ * Factory: build a successful no-output result.
+ * Streams are single-use, so each call returns a fresh ExecResult.
+ */
+export declare function ok(): ExecResult;
 /**
- * A successful result with no output.
- * Use this for commands that succeed silently.
+ * Backwards-compatible alias — a getter so each access returns a fresh
+ * ExecResult with new streams. Callers that destructure or use this in a
+ * pipeline must not reuse the same reference twice.
  */
 export declare const OK: ExecResult;
 /**
- * Create a successful result with optional stdout bytes.
- *
- * @param stdout - Output bytes to include (default: EMPTY)
- * @returns ExecResult with exitCode 0
+ * Create a successful result with optional stdout stream.
  */
-export declare function success(stdout?: Uint8Array): ExecResult;
+export declare function success(stdout?: ByteStream): ExecResult;
 /**
  * Create a successful result from a text string.
- * Convenience wrapper that encodes the string to UTF-8.
- *
- * @param stdout - Text output to include
- * @returns ExecResult with exitCode 0
  */
 export declare function successText(stdout: string): ExecResult;
 /**
  * Create a failure result with stderr message.
- *
- * @param stderr - Error message to include
- * @param exitCode - Exit code (default: 1)
- * @returns ExecResult with the specified exitCode
  */
 export declare function failure(stderr: string, exitCode?: number): ExecResult;
 /**
  * Create a result with all fields specified.
- *
- * @param stdout - Standard output bytes
- * @param stderr - Standard error bytes
- * @param exitCode - Exit code
- * @returns ExecResult with all fields
+ * Accepts Uint8Array or ByteStream for each; bytes are wrapped via fromBytes.
  */
-export declare function result(stdout: Uint8Array, stderr: Uint8Array, exitCode: number): ExecResult;
+export declare function result(stdout: Uint8Array | ByteStream, stderr: Uint8Array | ByteStream, exitCode: number): ExecResult;
 /**
  * Convert a boolean test result to an ExecResult.
- * Useful for test/conditional commands where true = exit 0, false = exit 1.
- *
- * @param passed - Boolean test result
- * @returns ExecResult with exitCode 0 if passed, 1 otherwise
  */
 export declare function testResult(passed: boolean): ExecResult;
 /**
  * Throw an ExecutionLimitError for execution limits (recursion, iterations, commands).
- *
- * @param message - Error message describing the limit exceeded
- * @param limitType - Type of limit exceeded
- * @param stdout - Accumulated stdout to include
- * @param stderr - Accumulated stderr to include
- * @throws ExecutionLimitError always
  */
-export declare function throwExecutionLimit(message: string, limitType: "recursion" | "iterations" | "commands", stdout?: Uint8Array, stderr?: Uint8Array): never;
+export declare function throwExecutionLimit(message: string, limitType: "recursion" | "iterations" | "commands", stdout?: Uint8Array | ByteStream, stderr?: Uint8Array | ByteStream): never;

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

@@ -6,6 +6,7 @@
  */
 import type { StatementNode } from "../../ast/types.js";
 import type { ExecResult } from "../../types.js";
+import { type ByteStream } from "../../utils/stream.js";
 import type { InterpreterContext } from "../types.js";
 /**
  * Execute a list of statements and accumulate their output.
@@ -13,8 +14,8 @@ import type { InterpreterContext } from "../types.js";
  *
  * @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)
+ * @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>;
+export declare function executeStatements(ctx: InterpreterContext, statements: StatementNode[], initialStdout?: ByteStream, initialStderr?: ByteStream): Promise<ExecResult>;

package/dist/interpreter/interpreter.d.ts

@@ -14,6 +14,7 @@ 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 ByteStream } from "../utils/stream.js";
 import type { InterpreterState } from "./types.js";
 export type { InterpreterContext, InterpreterState } from "./types.js";
 export interface InterpreterOptions {
@@ -23,7 +24,7 @@ export interface InterpreterOptions {
     exec: (script: string, options?: {
         env?: Record<string, string>;
         cwd?: string;
-        stdin?: Uint8Array;
+        stdin?: ByteStream;
     }) => Promise<ExecResult>;
     /** Optional secure fetch function for network-enabled commands */
     fetch?: SecureFetch;
@@ -39,9 +40,6 @@ export declare class Interpreter {
     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>;

package/dist/interpreter/pipeline-execution.d.ts

@@ -5,11 +5,12 @@
  */
 import type { CommandNode, PipelineNode } from "../ast/types.js";
 import type { ExecResult } from "../types.js";
+import { type ByteStream } from "../utils/stream.js";
 import type { InterpreterContext } from "./types.js";
 /**
  * Type for executeCommand callback
  */
-export type ExecuteCommandFn = (node: CommandNode, stdin: Uint8Array) => Promise<ExecResult>;
+export type ExecuteCommandFn = (node: CommandNode, stdin: ByteStream) => Promise<ExecResult>;
 /**
  * Execute a pipeline node (command or sequence of piped commands).
  */

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

@@ -5,6 +5,7 @@
  */
 import type { GroupNode, ScriptNode, StatementNode, SubshellNode } from "../ast/types.js";
 import type { ExecResult } from "../types.js";
+import { type ByteStream } from "../utils/stream.js";
 import type { InterpreterContext } from "./types.js";
 /**
  * Type for executeStatement callback
@@ -14,12 +15,12 @@ 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>;
+export declare function executeSubshell(ctx: InterpreterContext, node: SubshellNode, stdin: ByteStream, 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>;
+export declare function executeGroup(ctx: InterpreterContext, node: GroupNode, stdin: ByteStream, executeStatement: ExecuteStatementFn): Promise<ExecResult>;
 /**
  * Type for executeScript callback
  */
@@ -29,4 +30,4 @@ export type ExecuteScriptFn = (node: ScriptNode) => Promise<ExecResult>;
  * 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>;
+export declare function executeUserScript(ctx: InterpreterContext, scriptPath: string, args: string[], stdin: ByteStream, executeScript: ExecuteScriptFn): Promise<ExecResult>;

package/dist/interpreter/types.d.ts

@@ -6,6 +6,7 @@ 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 { ByteStream } from "../utils/stream.js";
 /**
  * Completion specification for a command, set by the `complete` builtin.
  */
@@ -231,7 +232,7 @@ export interface ProcessState {
  */
 export interface IOState {
     /** Stdin available for commands in compound commands (groups, subshells, while loops with piped input) */
-    groupStdin?: Uint8Array;
+    groupStdin?: ByteStream;
     /** File descriptors for process substitution and here-docs */
     fileDescriptors?: Map<number, string>;
     /** Next available file descriptor for {varname}>file allocation (starts at 10) */
@@ -299,11 +300,11 @@ export interface InterpreterContext {
     execFn: (script: string, options?: {
         env?: Record<string, string>;
         cwd?: string;
-        stdin?: Uint8Array;
+        stdin?: ByteStream;
     }) => Promise<ExecResult>;
     executeScript: (node: ScriptNode) => Promise<ExecResult>;
     executeStatement: (node: StatementNode) => Promise<ExecResult>;
-    executeCommand: (node: CommandNode, stdin: Uint8Array) => Promise<ExecResult>;
+    executeCommand: (node: CommandNode, stdin: ByteStream) => Promise<ExecResult>;
     /** Optional secure fetch function for network-enabled commands */
     fetch?: SecureFetch;
     /** Optional sleep function for testing with mock clocks */

package/dist/test-utils.d.ts

@@ -9,7 +9,6 @@ export interface TextResult {
     env?: Record<string, string>;
 }
 /**
- * Convert an ExecResult (with Uint8Array stdout/stderr) to text strings.
- * Use this in tests for easy string comparison.
+ * Drain ExecResult streams into decoded text strings for test assertions.
  */
-export declare function toText(result: ExecResult): TextResult;
+export declare function toText(result: ExecResult): Promise<TextResult>;

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { IFileSystem } from "./fs/interface.js";
 import type { ExecutionLimits } from "./limits.js";
 import type { SecureFetch } from "./network/index.js";
+import type { ByteStream } from "./utils/stream.js";
 /**
  * Lightweight interface for feature coverage tracking during fuzzing.
  * Lives here to avoid circular dependencies between fuzzing → core modules.
@@ -8,9 +9,16 @@ import type { SecureFetch } from "./network/index.js";
 export interface FeatureCoverageWriter {
     hit(feature: string): void;
 }
+/**
+ * Result of executing a command or script.
+ *
+ * stdout/stderr are streams of byte chunks. Consumers that need the full
+ * content should call collectBytes() / collectText() from utils/stream.ts.
+ * Storage is chunked internally — there is no single-Uint8Array size cap.
+ */
 export interface ExecResult {
-    stdout: Uint8Array;
-    stderr: Uint8Array;
+    stdout: ByteStream;
+    stderr: ByteStream;
     exitCode: number;
     /** The final environment variables after execution (only set by BashEnv.exec) */
     env?: Record<string, string>;
@@ -21,123 +29,42 @@ export interface BashExecResult extends ExecResult {
 }
 /** Options for exec calls within commands (internal API) */
 export interface CommandExecOptions {
-    /** Environment variables to merge into the exec state */
     env?: Record<string, string>;
-    /**
-     * Working directory for the exec.
-     * Required to prevent bugs where subcommands run in the wrong directory.
-     * Always pass `ctx.cwd` from the calling command's context.
-     */
     cwd: string;
-    /**
-     * Standard input to pass to the subcommand.
-     * Optional - if not provided, stdin will be empty.
-     */
-    stdin?: Uint8Array;
+    /** Standard input as a byte stream. Optional — defaults to an empty stream. */
+    stdin?: ByteStream;
 }
-/**
- * Context provided to commands during execution.
- *
- * ## Field Availability
- *
- * **Always available (core fields):**
- * - `fs`, `cwd`, `env`, `stdin`
- *
- * **Available when running via BashEnv interpreter:**
- * - `exec` - For commands like `xargs`, `bash -c` that need to run subcommands
- * - `getRegisteredCommands` - For the `help` command to list available commands
- *
- * **Conditionally available based on configuration:**
- * - `fetch` - Only when `network` option is configured in BashEnv
- * - `sleep` - Only when a custom sleep function is provided (e.g., for testing)
- */
-/**
- * Performance trace event for profiling command execution
- */
 export interface TraceEvent {
-    /** Event category (e.g., "find", "grep") */
     category: string;
-    /** Event name (e.g., "readdir", "stat", "eval") */
     name: string;
-    /** Duration in milliseconds */
     durationMs: number;
-    /** Optional details (e.g., path, count) */
     details?: Record<string, unknown>;
 }
+export type TraceCallback = (event: TraceEvent) => void;
 /**
- * Trace callback function for receiving performance events
+ * Context provided to commands during execution.
  */
-export type TraceCallback = (event: TraceEvent) => void;
 export interface CommandContext {
-    /** Virtual filesystem interface for file operations */
     fs: IFileSystem;
-    /** Current working directory */
     cwd: string;
     /** Environment variables - uses Map to prevent prototype pollution */
     env: Map<string, Uint8Array>;
-    /**
-     * Exported environment variables only.
-     * Used by commands like printenv and env that should only show exported vars.
-     * In bash, only exported variables are passed to child processes.
-     */
     exportedEnv?: Record<string, string>;
-    /** Standard input content */
-    stdin: Uint8Array;
     /**
-     * Execution limits configuration.
-     * Available when running commands via BashEnv interpreter.
+     * Standard input as a byte stream. Commands that need the full input in
+     * memory should call collectBytes(ctx.stdin) once. Streaming commands
+     * (cat, grep, head, tee, wc) can consume chunks incrementally.
      */
+    stdin: ByteStream;
     limits?: Required<ExecutionLimits>;
-    /**
-     * Performance trace callback for profiling.
-     * If provided, commands emit timing events for analysis.
-     */
     trace?: TraceCallback;
-    /**
-     * Execute a subcommand (e.g., for `xargs`, `bash -c`).
-     * Available when running commands via BashEnv interpreter.
-     *
-     * @param command - The command string to execute
-     * @param options - Required options including `cwd` to prevent directory bugs
-     */
     exec?: (command: string, options: CommandExecOptions) => Promise<ExecResult>;
-    /**
-     * Secure fetch function for network requests (e.g., for `curl`).
-     * Only available when `network` option is configured in BashEnv.
-     */
     fetch?: SecureFetch;
-    /**
-     * Returns names of all registered commands.
-     * Available when running commands via BashEnv interpreter.
-     * Used by the `help` command.
-     */
     getRegisteredCommands?: () => string[];
-    /**
-     * Custom sleep implementation.
-     * If provided, used instead of real setTimeout.
-     * Useful for testing with mock clocks.
-     */
     sleep?: (ms: number) => Promise<void>;
-    /**
-     * File descriptors map for here-docs and process substitution.
-     * Maps FD numbers to their content (e.g., 3 -> "content from 3<<EOF").
-     * Note: FD 0 content is in `stdin`, but may also appear here for consistency.
-     */
     fileDescriptors?: Map<number, string>;
-    /**
-     * Whether xpg_echo shopt is enabled.
-     * When true, echo interprets backslash escapes by default (like echo -e).
-     */
     xpgEcho?: boolean;
-    /**
-     * Current command substitution nesting depth.
-     * Used to prevent stack exhaustion from deeply nested $(...).
-     */
     substitutionDepth?: number;
-    /**
-     * Feature coverage writer for fuzzing instrumentation.
-     * When provided, commands emit coverage hits for analysis.
-     */
     coverage?: FeatureCoverageWriter;
 }
 export interface Command {
@@ -146,3 +73,4 @@ export interface Command {
 }
 export type CommandRegistry = Map<string, Command>;
 export type { IFileSystem };
+export type { ByteStream };

package/dist/utils/bytes.d.ts

@@ -20,8 +20,6 @@ export declare function encode(s: string): Uint8Array;
 export declare function decode(bytes: Uint8Array): string;
 /** Concatenate two byte arrays. Fast path: if either is empty, return the other without copying. */
 export declare function concat(a: Uint8Array, b: Uint8Array): Uint8Array;
-/** Check if a byte array is empty (zero length) */
-export declare function isEmpty(bytes: Uint8Array): boolean;
 /** Convenience: decode an array of Uint8Array args to string[] via UTF-8 */
 export declare function decodeArgs(args: Uint8Array[]): string[];
 /** Get an env value as a decoded string, or return the fallback (default "") */

package/dist/utils/stream.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ByteStream — the streaming binary I/O format used across just-bash.
+ *
+ * A ByteStream is a Web-standard ReadableStream<Uint8Array>. Streams replace
+ * the previous single-Uint8Array I/O model: stdout/stderr/stdin and file
+ * contents are streams of byte chunks, which removes the per-allocation
+ * size cap and lets the pipeline backpressure-propagate.
+ *
+ * Storage of small things (env values, command args) is still Uint8Array —
+ * those are tiny and need random access.
+ *
+ * Chunk size convention: producers emit chunks of up to 64 KiB. Consumers
+ * MUST tolerate any chunk size including 0 (caller intent: keep going).
+ */
+export type ByteStream = ReadableStream<Uint8Array>;
+/** Default chunk size for buffered → stream conversions */
+export declare const CHUNK_SIZE: number;
+/** An empty stream that closes immediately. */
+export declare function emptyStream(): ByteStream;
+/** Wrap a single Uint8Array as a stream. Empty input → empty stream. */
+export declare function fromBytes(bytes: Uint8Array): ByteStream;
+/** Wrap an array of chunks as a stream. */
+export declare function fromChunks(chunks: Uint8Array[]): ByteStream;
+/** Encode a string and wrap as a stream. */
+export declare function fromString(s: string): ByteStream;
+/**
+ * Consume a stream to a single Uint8Array.
+ *
+ * This DEFEATS streaming — only use when a command genuinely needs the full
+ * input in memory (sort, awk, sed with multi-line patterns). Total size is
+ * capped at maxBytes (default: no cap) to surface runaway buffering.
+ */
+export declare function collectBytes(stream: ByteStream, maxBytes?: number): Promise<Uint8Array>;
+/** Consume a stream as a UTF-8 string. */
+export declare function collectText(stream: ByteStream): Promise<string>;
+/** Concatenate two streams: emit all chunks of `a`, then all of `b`.
+ *
+ * Lazy: input streams are not opened (i.e. no reader is acquired) until
+ * downstream pulls. This matters because the construction site is allowed
+ * to keep the inputs unlocked and even hand `a` to another consumer — only
+ * one of them will end up reading it, but neither call should fail at
+ * construction time.
+ */
+export declare function concatStreams(a: ByteStream, b: ByteStream): ByteStream;
+/** Tee a stream into two independent streams (e.g. for |&). */
+export declare function teeStream(s: ByteStream): [ByteStream, ByteStream];
+/**
+ * Async-iterate over the chunks of a stream.
+ * Convenience for `for await (const chunk of streamChunks(s))`.
+ */
+export declare function streamChunks(s: ByteStream): AsyncIterableIterator<Uint8Array>;
+/**
+ * Split a stream into lines (LF-delimited). Yields each line WITHOUT the
+ * trailing newline. A trailing partial line (no LF) is yielded last.
+ *
+ * Useful for line-oriented streaming commands like grep, head, tail.
+ */
+export declare function streamLines(s: ByteStream): AsyncIterableIterator<Uint8Array>;
+/** Drain a stream to /dev/null (consume and discard). */
+export declare function drain(s: ByteStream): Promise<void>;
+/**
+ * Map each chunk through `fn` and emit the result. `fn` may return null
+ * to drop the chunk.
+ */
+export declare function mapChunks(s: ByteStream, fn: (chunk: Uint8Array) => Uint8Array | null): ByteStream;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "just-binary",
-  "version": "2.9.9",
+  "version": "3.0.0",
   "description": "A simulated bash environment with virtual filesystem",
   "repository": {
     "type": "git",

package/dist/bin/chunks/alias-23G4Q2RS.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b,c,d}from"./chunk-FQX4G5RH.js";import"./chunk-227L3ACM.js";import"./chunk-RQSPCXDR.js";export{a as aliasCommand,c as flagsForFuzzing,b as unaliasCommand,d as unaliasFlagsForFuzzing};

package/dist/bin/chunks/awk2-Z6VRXKAK.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b}from"./chunk-ZI4TTZL5.js";import"./chunk-F46CSMUF.js";import"./chunk-SE4C7FJY.js";import"./chunk-QT2GMJRJ.js";import"./chunk-227L3ACM.js";import"./chunk-RQSPCXDR.js";export{a as awkCommand2,b as flagsForFuzzing};

package/dist/bin/chunks/base64-XCZKQZ7Z.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{a,b}from"./chunk-S23TISYL.js";import"./chunk-RUESYAVK.js";import"./chunk-KFLJ4EMB.js";import"./chunk-227L3ACM.js";import"./chunk-RQSPCXDR.js";export{a as base64Command,b as flagsForFuzzing};