@jerryan/just-bash 3.5.0

package/dist/custom-commands.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Custom Commands API
+ *
+ * Provides types and utilities for registering user-provided TypeScript commands.
+ */
+import { type ByteString } from "./encoding.js";
+import type { IFileSystem } from "./fs/interface.js";
+import { type ExecutionLimitProfile, type ExecutionLimits } from "./limits.js";
+import type { Command, CommandContext, ExecResult, ResolvedCommandContext, RuntimeCommandContext } from "./types.js";
+/**
+ * A custom command - either a Command object or a lazy loader.
+ */
+export type CustomCommand = Command | LazyCommand;
+/**
+ * Lazy-loaded custom command (for code-splitting).
+ */
+export interface LazyCommand {
+    name: string;
+    /**
+     * Set false to run through the restricted extension boundary. Commands are
+     * trusted by default for compatibility with existing host integrations.
+     */
+    trusted?: boolean;
+    load: () => Promise<Command>;
+}
+/** Inputs for a complete standalone command context, primarily for tests. */
+export interface CommandContextOptions extends Omit<Partial<CommandContext>, "fs" | "limits" | "stdin"> {
+    fs: IFileSystem;
+    stdin?: ByteString;
+    executionLimits?: ExecutionLimits;
+    executionLimitProfile?: ExecutionLimitProfile;
+}
+/**
+ * Build the same resolved public context shape that the interpreter gives a
+ * custom command. This avoids hand-maintained test objects drifting whenever
+ * an internal execution limit is added.
+ */
+export declare function createCommandContext(options: CommandContextOptions): RuntimeCommandContext;
+/**
+ * Type guard to check if a custom command is lazy-loaded.
+ */
+export declare function isLazyCommand(cmd: CustomCommand): cmd is LazyCommand;
+/**
+ * Define a TypeScript command with type inference.
+ * Convenience wrapper - you can also just use the Command interface directly.
+ *
+ * @example
+ * ```ts
+ * const hello = defineCommand("hello", async (args, ctx) => {
+ *   const name = args[0] || "world";
+ *   return { stdout: `Hello, ${name}!\n`, stderr: "", exitCode: 0 };
+ * });
+ *
+ * const bash = new Bash({ customCommands: [hello] });
+ * await bash.exec("hello Alice"); // "Hello, Alice!\n"
+ * ```
+ */
+export declare function defineCommand(name: string, execute: (args: string[], ctx: ResolvedCommandContext) => Promise<ExecResult>, options?: {
+    trusted?: boolean;
+}): Command;
+/**
+ * Create a lazy-loaded wrapper for a custom command.
+ * The command is only loaded when first executed.
+ */
+export declare function createLazyCustomCommand(lazy: LazyCommand): Command;

package/dist/encoding.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Byte/text boundary types for the shell pipeline.
+ *
+ * Shell pipes carry bytes, not text. Internally we represent a byte buffer as
+ * a JS string where `s.charCodeAt(i)` is the i-th byte (0–255), the same
+ * convention as `Buffer.from(s, "latin1")`. That's a space-cheap byte buffer,
+ * but the type system can't tell it apart from a real `string`, and command
+ * authors keep writing `ctx.stdin.split(...)` / `RegExp.test(ctx.stdin)` /
+ * `JSON.parse(ctx.stdin)` over data that is actually UTF-8 packed in latin1.
+ * The result is silent mojibake — every multibyte codepoint gets misread as
+ * several latin1 chars, then re-encoded as UTF-8 on the way out.
+ *
+ * `ByteString` is opaque (deliberately not assignable to/from `string`) so
+ * you cannot accidentally call string methods on it. The only ways out are
+ * `latin1FromBytes` (passthrough — stay byte-clean) and `decodeBytesToUtf8`
+ * (decode — process as text). Pick one explicitly per call site.
+ */
+declare const __byteString: unique symbol;
+export interface ByteString {
+    readonly [__byteString]: true;
+}
+/** Return UTF-8 byte length without allocating an encoded copy. */
+export declare function utf8ByteLength(value: string): number;
+/**
+ * Tag a latin1 byte buffer (each char = one byte) as a `ByteString`. Use at
+ * the pipeline edge: `cmdCtx.stdin = unsafeBytesFromLatin1(prevStdout)`.
+ * Avoid inside command implementations.
+ */
+export declare function unsafeBytesFromLatin1(s: string): ByteString;
+/**
+ * Reveal the underlying latin1 byte buffer. Use when a command intentionally
+ * forwards bytes unchanged (cat, head, tee, base64 -d, gzip, ...). Calling
+ * regex / parse / `.length-as-chars` on the result re-introduces the
+ * mojibake bug — if you need text, use `decodeBytesToUtf8` instead.
+ */
+export declare function latin1FromBytes(b: ByteString): string;
+/**
+ * Decode a `ByteString` as UTF-8. Use when a command interprets stdin as
+ * text (jq, sed, grep, awk, ...). Returns proper Unicode where multibyte
+ * codepoints occupy a single JS char, so regex and parsers work correctly.
+ *
+ * Falls back to the raw latin1 view if the bytes are not valid UTF-8 (e.g.
+ * a binary stream piped into grep). Callers that want hard failure on
+ * invalid UTF-8 should encode + decode manually with `{ fatal: true }`.
+ */
+export declare function decodeBytesToUtf8(b: ByteString, maxBytes?: number): string;
+/**
+ * UTF-8 encode `s` (treating every char as a Unicode codepoint) into a
+ * `ByteString`. Use at sites that *know* their input is decoded Unicode
+ * text and need to emit it back as bytes — typically the inverse of an
+ * earlier `decodeBytesToUtf8` call inside the same command.
+ */
+export declare function encodeUtf8ToBytes(s: string, maxBytes?: number): ByteString;
+/** The empty `ByteString`. */
+export declare const EMPTY_BYTES: ByteString;
+/**
+ * Convert a `Uint8Array` to a `ByteString`. Each byte becomes one char.
+ * The reverse is `Uint8Array.from(latin1FromBytes(b), (c) => c.charCodeAt(0))`.
+ */
+export declare function bytesFromUint8Array(buf: Uint8Array, maxBytes?: number): ByteString;
+/**
+ * Read a file's raw bytes from any `IFileSystem`. Prefers the optional
+ * {@link IFileSystem.readFileBytes} method (built-in filesystems implement
+ * it natively), falling back to {@link IFileSystem.readFileBuffer} +
+ * conversion for external/custom filesystems written before
+ * `readFileBytes` existed. Use this from internal commands instead of
+ * calling `fs.readFileBytes` directly so user-supplied filesystems keep
+ * working.
+ */
+export declare function readBytesFrom(fs: {
+    readFileBytes?(path: string): Promise<ByteString>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+}, path: string): Promise<ByteString>;
+/** Either-or shape of a command's `stdout`. */
+export type OutputKind = "text" | "bytes";
+/**
+ * Read the explicit shape of a command's stdout. Falls back to the legacy
+ * `stdoutEncoding === "binary"` flag for results produced before the
+ * `stdoutKind` field existed; defaults to `"text"` otherwise.
+ */
+export declare function stdoutKind(result: {
+    stdoutKind?: OutputKind;
+    stdoutEncoding?: "binary";
+}): OutputKind;
+/**
+ * Coerce a command's stdout to a `ByteString` for the byte-shaped pipe.
+ * Text gets UTF-8 encoded once (codepoints → bytes); bytes pass through.
+ */
+export declare function stdoutAsBytes(result: {
+    stdout: string;
+    stdoutKind?: OutputKind;
+    stdoutEncoding?: "binary";
+}): ByteString;
+/**
+ * Normalize a command's stdout to decoded UTF-8 text, consulting its explicit
+ * `stdoutKind` (or legacy `stdoutEncoding`) rather than guessing from string
+ * contents. Byte-shaped output is UTF-8 decoded once (falling back to the raw
+ * latin1 view for non-UTF-8 bytes); text-shaped output is returned unchanged so
+ * it is never re-decoded. Used at the statement/script concatenation and
+ * command-substitution boundaries so interleaved text and byte producers
+ * combine into a single, consistently-decoded string.
+ */
+export declare function decodedTextFromResult(result: {
+    stdout: string;
+    stdoutKind?: OutputKind;
+    stdoutEncoding?: "binary";
+}): string;
+/**
+ * Build an `ExecResult`-shaped object whose stdout is decoded text. Sets
+ * `stdoutKind: "text"` so the pipe knows to UTF-8 encode it on handoff
+ * and redirects know to write it as UTF-8. Use for command authors that
+ * decode their input and emit Unicode text — they no longer have to
+ * manually re-encode for downstream byte consumers.
+ */
+export declare function textOutput(data: string): {
+    stdout: string;
+    stdoutKind: "text";
+};
+/**
+ * Build an `ExecResult`-shaped object whose stdout is a latin1 byte view.
+ * Sets both `stdoutKind: "bytes"` (new contract) and `stdoutEncoding:
+ * "binary"` (legacy alias) so older code paths keep working through the
+ * migration. Use for command authors that emit raw bytes (cat, gzip,
+ * tar, base64 -d, ...).
+ */
+export declare function bytesOutput(data: ByteString): {
+    stdout: string;
+    stdoutKind: "bytes";
+    stdoutEncoding: "binary";
+};
+export {};

package/dist/execution-output.d.ts

@@ -0,0 +1,28 @@
+import type { ExecutionScope } from "./execution-scope.js";
+import type { ExecResult } from "./types.js";
+/**
+ * Chunked interpreter-output sink backed by the one top-level execution
+ * budget. Accounting metadata follows bytes as compound commands relay child
+ * results, avoiding both budget refreshes and double charging.
+ */
+export declare class ExecutionOutputAccumulator {
+    private readonly scope;
+    private readonly site;
+    private readonly stdoutChunks;
+    private readonly stderrChunks;
+    private stdoutBytes;
+    private stderrBytes;
+    private readonly attachedErrors;
+    constructor(scope: ExecutionScope, site: string);
+    append(stream: "stdout" | "stderr", chunk: string, alreadyAccountedBytes?: number, kind?: "text" | "bytes"): void;
+    /**
+     * Attach output retained before a fatal/control-flow error exactly once for
+     * this accumulator. The bytes have already been charged by the shared scope,
+     * so propagation updates accounting metadata without charging them again.
+     */
+    prependTo(error: unknown): void;
+    appendResult(result: ExecResult, stdout?: string): void;
+    build(exitCode: number, extra?: Partial<ExecResult>): ExecResult;
+    get stdout(): string;
+    get stderr(): string;
+}

package/dist/execution-scope.d.ts

@@ -0,0 +1,110 @@
+import { ExecutionAbortedError } from "./interpreter/errors.js";
+import type { ExecutionLimits } from "./limits.js";
+import type { ExecResult } from "./types.js";
+export interface ResourceLease {
+    release(): void;
+}
+/**
+ * Accounting capability exposed to commands. Administrative lifecycle and
+ * result-accounting operations intentionally remain on ExecutionScope only.
+ */
+export interface CommandExecutionBudget {
+    readonly remainingLiveBytes: number;
+    consumeWork(units?: number, site?: string): number;
+    consumeLimited(kind: string, count: number, maximum: number, site?: string): number;
+    consumeInput(bytes: number, site?: string): number;
+    reserveBytes(bytes: number, site?: string): ResourceLease;
+    reserveBytes(kind: string, bytes: number, site?: string): ResourceLease;
+    enterDepth(kind: string, site?: string): ResourceLease;
+    enterDepth(kind: string, maximum: number, site?: string): ResourceLease;
+    throwIfAborted(site?: string): void;
+    remainingTimeMs(): number;
+    registerCleanup(cleanup: Cleanup): () => void;
+}
+type Cleanup = () => void | Promise<void>;
+/**
+ * Security-sensitive accounting shared by every interpreter descended from a
+ * single public Bash.exec() call. This object is never accepted from callers;
+ * nested exec functions capture it in a closure instead. It also funnels
+ * command-resolution-miss records (unresolvedCommands) from every nesting
+ * level into one per-exec list.
+ *
+ * Keep reservations centralized here so future output/byte/filesystem budgets
+ * cannot accidentally be refreshed by starting a child interpreter.
+ */
+export declare class ExecutionScope {
+    private readonly limits;
+    private readonly signal;
+    /**
+     * When true, a command-resolution miss aborts the whole execution
+     * (UnresolvedCommandError) instead of continuing bash-style with 127.
+     */
+    readonly abortOnUnresolvedCommands: boolean;
+    private commandCount;
+    private workUnits;
+    private liveBytes;
+    private inputBytes;
+    private outputBytes;
+    private readonly countersByKind;
+    private readonly bytesByKind;
+    private readonly depthByKind;
+    private readonly cleanupCallbacks;
+    private poisoned;
+    private closed;
+    private readonly startedAt;
+    private readonly unresolvedCommands;
+    /** Bytes still available for prospective intermediate allocations. */
+    get remainingLiveBytes(): number;
+    /** Snapshot used to prove accounting inherited from a nested execution. */
+    get outputBytesUsed(): number;
+    constructor(limits: Required<ExecutionLimits>, signal?: AbortSignal | undefined, 
+    /**
+     * When true, a command-resolution miss aborts the whole execution
+     * (UnresolvedCommandError) instead of continuing bash-style with 127.
+     */
+    abortOnUnresolvedCommands?: boolean);
+    /**
+     * Record a command-resolution miss ("command not found"), deduplicated
+     * in first-encountered order. Misses anywhere in the execution funnel
+     * here — subshells, pipelines, command substitutions, nested `bash -c`.
+     */
+    recordUnresolvedCommand(name: string): void;
+    /** Names that failed command resolution during this execution. */
+    get unresolvedCommandNames(): string[];
+    private fail;
+    /** Permanently reject later work after an extension misses cancellation. */
+    poisonAfterAbort(error: ExecutionAbortedError): void;
+    private assertUsable;
+    chargeCommand(): number;
+    consumeWork(units?: number, site?: string): number;
+    /** Charge both the aggregate work budget and a narrower operation budget. */
+    consumeLimited(kind: string, count: number, maximum: number, site?: string): number;
+    consumeInput(bytes: number, site?: string): number;
+    consume(kind: string, count?: number, site?: string): number;
+    reserveBytes(bytes: number, site?: string): ResourceLease;
+    reserveBytes(kind: string, bytes: number, site?: string): ResourceLease;
+    appendOutput(stream: "stdout" | "stderr", chunk: string, site?: string, alreadyAccountedBytes?: number, kind?: "text" | "bytes"): number;
+    accountResult(result: ExecResult, site?: string, maximumPriorBytes?: number): ExecResult;
+    /**
+     * Relinquish bytes that were charged while a result was retained but have
+     * since become a transient pipeline input. This is deliberately limited to
+     * bytes carried by internal accounting metadata; callers must not use it to
+     * refund arbitrary output.
+     */
+    /** @internal Use relinquishPipelineOutput; the authority prevents extensions
+     * that receive an ExecutionScope from refunding their own output. */
+    relinquishOutput(bytes: number, site: string, authority: object): void;
+    enterDepth(kind: string, site?: string): ResourceLease;
+    enterDepth(kind: string, maximum: number, site?: string): ResourceLease;
+    throwIfAborted(site?: string): void;
+    remainingTimeMs(): number;
+    registerCleanup(cleanup: Cleanup): () => void;
+    close(): Promise<void>;
+    assertExecDepth(depth: number): void;
+}
+/** Build a least-authority view for command implementations. */
+export declare function createCommandExecutionBudget(scope: ExecutionScope): CommandExecutionBudget;
+/** Release a checked pipeline intermediate without exposing refund authority
+ * through the ExecutionScope capability supplied to custom commands. */
+export declare function relinquishPipelineOutput(scope: ExecutionScope, bytes: number, site?: string): void;
+export {};

package/dist/fatal-execution-error.d.ts

@@ -0,0 +1,27 @@
+import { ExecutionAbortedError, ExecutionLimitError, UnresolvedCommandError } from "./interpreter/errors.js";
+import { SecurityViolationError } from "./security/defense-in-depth-box.js";
+/**
+ * Fatal execution errors come in two tiers:
+ *
+ * 1. NEVER-CONTAINED (this module): errors that no catch block may turn
+ *    into an ordinary command result, at any nesting level — execution
+ *    limits, host aborts, security violations, and the
+ *    abort-on-unresolved unwind. They must propagate to the top of the
+ *    exec call.
+ * 2. BOUNDARY-SPECIFIC (per-site lists): ExitError, ReturnError,
+ *    ErrexitError, etc. — contained at specific boundaries (subshells,
+ *    functions, pipelines) by design.
+ *
+ * Every broad catch block must route tier-1 errors through this module
+ * FIRST (call rethrowFatalExecutionError, or test isFatalExecutionError
+ * when the site needs to prepend output before rethrowing), then handle
+ * its tier-2 errors. Adding a new tier-1 class here then protects every
+ * compliant site at once; a site that hand-lists tier-1 classes is a bug
+ * waiting to happen (and has been: see handleLoopError history).
+ */
+export declare function isFatalExecutionError(error: unknown): error is ExecutionLimitError | ExecutionAbortedError | SecurityViolationError | UnresolvedCommandError;
+/**
+ * Rethrow errors that command-level recovery must never turn into ordinary
+ * command failures. Call this first in broad catch blocks.
+ */
+export declare function rethrowFatalExecutionError(error: unknown): void;

package/dist/fs/encoding.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared utilities for filesystem implementations
+ */
+import type { BufferEncoding, ReadFileOptions, WriteFileOptions } from "./interface.js";
+export type FileContent = string | Uint8Array;
+/**
+ * Helper to convert content to Uint8Array
+ */
+export declare function toBuffer(content: FileContent, encoding?: BufferEncoding): Uint8Array;
+/**
+ * Helper to convert Uint8Array to string with encoding
+ */
+export declare function fromBuffer(buffer: Uint8Array, encoding?: BufferEncoding | null): string;
+/**
+ * Helper to get encoding from options
+ */
+export declare function getEncoding(options?: ReadFileOptions | WriteFileOptions | BufferEncoding | string | null): BufferEncoding | undefined;

package/dist/fs/identity.d.ts

@@ -0,0 +1,9 @@
+import type { IFileSystem } from "./interface.js";
+/**
+ * Return an inert identity token for a filesystem. The token deliberately has
+ * no prototype or reference back to the filesystem: consumers may safely use
+ * it as a WeakMap key without acquiring filesystem authority.
+ */
+export declare function getFileSystemIdentity(fs: IFileSystem): object;
+/** True only for inert tokens created by getFileSystemIdentity(). */
+export declare function isFileSystemIdentity(value: object): boolean;

package/dist/fs/in-memory-fs/in-memory-fs.d.ts

@@ -0,0 +1,98 @@
+import { type ByteString } from "../../encoding.js";
+import type { BufferEncoding, CpOptions, DirectoryEntry, DirentEntry, FileContent, FileEntry, FsEntry, FsStat, IFileSystem, InitialFiles, LazyFileEntry, MkdirOptions, ReadFileOptions, RmOptions, SymlinkEntry, WriteFileOptions } from "../interface.js";
+export type { BufferEncoding, FileContent, FileEntry, LazyFileEntry, DirectoryEntry, SymlinkEntry, FsEntry, FsStat, IFileSystem, };
+export interface FsData {
+    [path: string]: FsEntry;
+}
+export interface InMemoryFsOptions {
+    /** Aggregate materialized file bytes retained by this filesystem. */
+    maxTotalBytes?: number;
+}
+export declare class InMemoryFs implements IFileSystem {
+    private data;
+    private entryIdentities;
+    private nextEntryIdentity;
+    private readonly maxTotalBytes;
+    private retainedBytes;
+    /** Number of directory entries retaining each hard-link-compatible buffer. */
+    private contentReferences;
+    private materializedContent;
+    private storedByteLength;
+    private wouldReleaseBytes;
+    /**
+     * Check a newly allocated, unique file body before creating its buffer.
+     * Replacing the final reference to an old body credits those bytes.
+     */
+    private assertCanAllocate;
+    /** Replace one path while updating retained storage in constant time. */
+    private setEntry;
+    private deleteEntry;
+    private contentByteLength;
+    private identityFor;
+    constructor(initialFiles?: InitialFiles, options?: InMemoryFsOptions);
+    private ensureParentDirs;
+    writeFileSync(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding, metadata?: {
+        mode?: number;
+        mtime?: Date;
+    }): void;
+    /**
+     * Store a lazy file entry whose content is provided by a function on first read.
+     * Writing to the path replaces the lazy entry, so the function is never called.
+     */
+    writeFileLazy(path: string, lazy: () => string | Uint8Array | Promise<string | Uint8Array>, metadata?: {
+        mode?: number;
+        mtime?: Date;
+    }): void;
+    /**
+     * Materialize a lazy file entry, replacing it with a concrete FileEntry.
+     * Returns the materialized FileEntry.
+     */
+    private materializeLazy;
+    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>;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    /**
+     * Resolve symlinks in intermediate path components only (not the final component).
+     * Used by lstat which should not follow the final symlink.
+     */
+    private resolveIntermediateSymlinks;
+    /**
+     * Resolve all symlinks in a path, including intermediate components.
+     * For example: /home/user/linkdir/file.txt where linkdir is a symlink to "subdir"
+     * would resolve to /home/user/subdir/file.txt
+     */
+    private resolvePathWithSymlinks;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    /**
+     * Synchronous version of mkdir
+     */
+    mkdirSync(path: string, options?: MkdirOptions): void;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    getAllPaths(): string[];
+    resolvePath(base: string, path: string): string;
+    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>;
+    /**
+     * 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 (ignored, kept for API compatibility)
+     * @param mtime - Modification time
+     */
+    utimes(path: string, _atime: Date, mtime: Date): Promise<void>;
+}

package/dist/fs/in-memory-fs/index.d.ts

@@ -0,0 +1 @@
+export { InMemoryFs } from "./in-memory-fs.js";

package/dist/fs/init.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Filesystem Initialization
+ *
+ * Sets up the default filesystem structure for the bash environment
+ * including /dev, /proc, and common directories.
+ */
+import type { IFileSystem } from "./interface.js";
+/**
+ * Virtual process info for /proc filesystem initialization.
+ */
+interface VirtualProcessInfo {
+    pid: number;
+    ppid: number;
+    uid: number;
+    gid: number;
+}
+/**
+ * Initialize the filesystem with standard directories and files
+ * Works with both InMemoryFs and OverlayFs (both write to memory)
+ */
+export declare function initFilesystem(fs: IFileSystem, useDefaultLayout: boolean, processInfo?: VirtualProcessInfo): void;
+export {};