@eidos.space/just-bash 3.0.2

package/dist/AGENTS.md

@@ -0,0 +1,325 @@
+
+# AGENTS.md - just-bash
+
+Instructions for AI agents using just-bash in projects.
+
+## What is just-bash?
+
+A sandboxed bash interpreter with an in-memory virtual filesystem. Use it when you need to:
+
+- Execute shell commands without real filesystem access
+- Run untrusted scripts safely
+- Process text with standard Unix tools (grep, sed, awk, jq, etc.)
+
+## For AI Agents
+
+If you're building an AI agent that needs a bash tool, use [`bash-tool`](https://github.com/vercel-labs/bash-tool) which is optimized for just-bash:
+
+```sh
+npm install bash-tool
+```
+
+```typescript
+import { createBashTool } from "bash-tool";
+import { generateText } from "ai";
+
+const bashTool = createBashTool({
+  files: { "/data/users.json": '[{"name": "Alice"}, {"name": "Bob"}]' },
+});
+
+const result = await generateText({
+  model: "anthropic/claude-sonnet-4",
+  tools: { bash: bashTool },
+  prompt: "Count the users in /data/users.json",
+});
+```
+
+See the [bash-tool documentation](https://github.com/vercel-labs/bash-tool) for more details.
+
+## Quick Reference
+
+```typescript
+import { Bash } from "just-bash";
+
+const bash = new Bash({
+  files: { "/data/input.txt": "content" }, // Initial files
+  cwd: "/data", // Working directory
+});
+
+const result = await bash.exec("cat input.txt | grep pattern");
+// result.stdout  - command output
+// result.stderr  - error output
+// result.exitCode - 0 = success, non-zero = failure
+```
+
+## Key Behaviors
+
+1. **Isolation**: Each `exec()` call is isolated. Environment variables, functions, and cwd changes don't persist between calls. Only filesystem changes persist.
+
+2. **No real filesystem**: By default, commands only see the virtual filesystem. Use `OverlayFs` to read from a real directory (writes stay in memory).
+
+3. **No network by default**: `curl` doesn't exist unless you configure `network` options with URL allowlists.
+
+4. **No binaries/WASM**: Only built-in commands work. You cannot run node, python, or other binaries.
+
+5. **ReadWriteFs root separation**: If you use `ReadWriteFs`, point it at a workspace directory, not at the installed `just-bash` package or other trusted runtime code.
+
+## Available Commands
+
+**Text processing**: `awk`, `cat`, `column`, `comm`, `cut`, `egrep`, `expand`, `fgrep`, `fold`, `grep`, `head`, `join`, `nl`, `paste`, `rev`, `rg`, `sed`, `sort`, `strings`, `tac`, `tail`, `tr`, `unexpand`, `uniq`, `wc`, `xargs`
+
+**Data processing**: `jq` (JSON), `js-exec` (JavaScript/TypeScript via QuickJS), `python3`/`python` (Python via WASM/CPython), `sqlite3` (SQLite), `xan` (CSV), `yq` (YAML/XML/TOML/CSV)
+
+**File operations**: `basename`, `chmod`, `cp`, `dirname`, `du`, `file`, `find`, `ln`, `ls`, `mkdir`, `mv`, `od`, `pwd`, `readlink`, `rm`, `rmdir`, `split`, `stat`, `touch`, `tree`
+
+**Utilities**: `alias`, `base64`, `bash`, `clear`, `curl`, `date`, `diff`, `echo`, `env`, `expr`, `false`, `gzip`, `gunzip`, `help`, `history`, `hostname`, `html-to-markdown`, `md5sum`, `printenv`, `printf`, `seq`, `sh`, `sha1sum`, `sha256sum`, `sleep`, `tar`, `tee`, `time`, `timeout`, `true`, `unalias`, `which`, `whoami`, `zcat`
+
+All commands support `--help` for usage details.
+
+## Tools by File Format
+
+### JSON - `jq`
+
+```bash
+# Extract field
+jq '.name' data.json
+
+# Filter array
+jq '.users[] | select(.active == true)' data.json
+
+# Transform structure
+jq '[.items[] | {id, name}]' data.json
+
+# From stdin
+echo '{"x":1}' | jq '.x'
+```
+
+### YAML - `yq`
+
+```bash
+# Extract value
+yq '.config.database.host' config.yaml
+
+# Output as JSON
+yq -o json '.' config.yaml
+
+# Filter with jq syntax
+yq '.users[] | select(.role == "admin")' users.yaml
+
+# Modify file in-place
+yq -i '.version = "2.0"' config.yaml
+```
+
+### TOML - `yq`
+
+```bash
+# Read TOML (auto-detected from .toml extension)
+yq '.package.name' Cargo.toml
+yq '.tool.poetry.version' pyproject.toml
+
+# Convert TOML to JSON
+yq -o json '.' config.toml
+
+# Convert YAML to TOML
+yq -o toml '.' config.yaml
+```
+
+### CSV/TSV - `yq -p csv`
+
+```bash
+# Read CSV (auto-detects from .csv/.tsv extension)
+yq '.[0].name' data.csv
+yq '.[0].name' data.tsv
+
+# Filter rows
+yq '[.[] | select(.status == "active")]' data.csv
+
+# Convert CSV to JSON
+yq -o json '.' data.csv
+```
+
+### Front-matter - `yq --front-matter`
+
+```bash
+# Extract YAML front-matter from markdown
+yq --front-matter '.title' post.md
+yq -f '.tags[]' blog-post.md
+
+# Works with TOML front-matter (+++) too
+yq -f '.date' hugo-post.md
+```
+
+### XML - `yq -p xml`
+
+```bash
+# Extract element
+yq '.root.users.user[0].name' data.xml
+
+# Access attributes (use +@ prefix)
+yq '.root.item["+@id"]' data.xml
+
+# Convert XML to JSON
+yq -p xml -o json '.' data.xml
+```
+
+### INI - `yq -p ini`
+
+```bash
+# Read INI section value
+yq '.database.host' config.ini
+
+# Convert INI to JSON
+yq -p ini -o json '.' config.ini
+```
+
+### HTML - `html-to-markdown`
+
+```bash
+# Convert HTML to markdown
+html-to-markdown page.html
+
+# From stdin
+echo '<h1>Title</h1><p>Text</p>' | html-to-markdown
+```
+
+### Format Conversion with yq
+
+```bash
+# JSON to YAML
+yq -p json '.' data.json
+
+# YAML to JSON
+yq -o json '.' data.yaml
+
+# YAML to TOML
+yq -o toml '.' config.yaml
+
+# TOML to JSON
+yq -o json '.' Cargo.toml
+
+# CSV to JSON
+yq -p csv -o json '.' data.csv
+
+# XML to YAML
+yq -p xml '.' data.xml
+```
+
+## Common Patterns
+
+### Process JSON with jq
+
+```bash
+cat data.json | jq '.items[] | select(.active) | .name'
+```
+
+### Find and process files
+
+```bash
+find . -name "*.ts" -type f | xargs grep -l "TODO"
+```
+
+### Text transformation pipeline
+
+```bash
+cat input.txt | grep -v "^#" | sort | uniq -c | sort -rn | head -10
+```
+
+### AWK for columnar data
+
+```bash
+cat data.csv | awk -F',' '{sum += $3} END {print sum}'
+```
+
+## Limitations
+
+- **32-bit integers only**: Arithmetic operations use 32-bit signed integers
+- **No job control**: No `&`, `bg`, `fg`, or process suspension
+- **No external binaries**: Only built-in commands are available
+- **Execution limits**: Loops, recursion, command counts, and output sizes have configurable limits to prevent runaway execution (exit code 126 when exceeded)
+
+## Error Handling
+
+Always check `exitCode`:
+
+```typescript
+import { Bash } from "just-bash";
+
+const bash = new Bash({ files: { "/file.txt": "some content" } });
+const result = await bash.exec("grep pattern file.txt");
+if (result.exitCode !== 0) {
+  // Command failed - check result.stderr for details
+}
+```
+
+Common exit codes:
+
+- `0` - Success
+- `1` - General error or no matches (grep)
+- `2` - Misuse of command (invalid options)
+- `126` - Execution limit exceeded (loops, output size, string length)
+- `127` - Command not found
+
+## Debugging Tips
+
+1. **Check stderr**: Error messages go to `result.stderr`
+2. **Use --help**: All commands support `--help` for usage
+3. **Test incrementally**: Build pipelines step by step
+4. **Quote variables**: Use `"$var"` to handle spaces in values
+
+## Security Model
+
+- Virtual filesystem is isolated from the real system
+- Network access requires explicit URL allowlists
+- Execution limits prevent infinite loops and resource exhaustion
+- No shell injection possible (commands are parsed, not eval'd)
+
+### Execution Limits
+
+All limits are configurable via `executionLimits` in `BashOptions`:
+
+```typescript
+const bash = new Bash({
+  executionLimits: {
+    maxCommandCount: 10000,      // Max commands per exec()
+    maxLoopIterations: 10000,    // Max bash loop iterations
+    maxCallDepth: 100,           // Max function recursion depth
+    maxStringLength: 10485760,   // Max string size (10MB)
+    maxArrayElements: 100000,    // Max array elements
+    maxGlobOperations: 100000,   // Max glob filesystem operations
+    maxAwkIterations: 10000,     // Max AWK loop iterations
+    maxSedIterations: 10000,     // Max sed branch loop iterations
+    maxJqIterations: 10000,      // Max jq loop iterations
+    maxSubstitutionDepth: 50,    // Max $() nesting depth
+    maxHeredocSize: 10485760,    // Max heredoc size (10MB)
+  },
+});
+```
+
+**Output size limits**: AWK, sed, jq, and printf enforce `maxStringLength` on their output buffers. Commands that exceed the limit exit with code 126.
+
+**File read size limits**: `OverlayFs` and `ReadWriteFs` default to a 10MB max file read size. Override with `maxFileReadSize` in filesystem options (set to `0` to disable).
+
+**Network response size**: `maxResponseSize` in `NetworkConfig` caps HTTP response bodies (default: 10MB).
+
+## Discovering Types
+
+TypeScript types are available in the `.d.ts` files. Use JSDoc-style exploration to understand the API:
+
+```bash
+# Find all type definition files
+find node_modules/just-bash/dist -name "*.d.ts" | head -20
+
+# View main exports and their types
+cat node_modules/just-bash/dist/index.d.ts
+
+# View Bash class options
+grep -A 30 "interface BashOptions" node_modules/just-bash/dist/Bash.d.ts
+
+# Search for specific types
+grep -r "interface.*Options" node_modules/just-bash/dist/*.d.ts
+```
+
+Key types to explore:
+- `BashOptions` - Constructor options for `new Bash()`
+- `ExecResult` - Return type of `bash.exec()`
+- `InitialFiles` - File specification format

package/dist/Bash.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Bash - Bash Shell Environment
+ *
+ * A complete bash-like shell environment using a proper AST-based architecture:
+ *   Input → Parser → AST → Interpreter → Output
+ *
+ * This class provides the shell environment (filesystem, commands, variables)
+ * and delegates execution to the Interpreter.
+ */
+import "./timers.js";
+import { type CommandName } from "./commands/registry.js";
+import { type CustomCommand } from "./custom-commands.js";
+import type { IFileSystem, InitialFiles } from "./fs/interface.js";
+import { type ExecutionLimits } from "./limits.js";
+import { type NetworkConfig, type SecureFetch } from "./network/index.js";
+import type { DefenseInDepthConfig } from "./security/types.js";
+import type { BashTransformResult, TransformPlugin } from "./transform/types.js";
+import type { BashExecResult, Command, FeatureCoverageWriter, TraceCallback } from "./types.js";
+export type { ExecutionLimits } from "./limits.js";
+/**
+ * Logger interface for Bash execution logging.
+ * Implement this interface to receive execution logs.
+ */
+export interface BashLogger {
+    /** Log informational messages (exec commands, stderr, exit codes) */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Log debug messages (stdout output) */
+    debug(message: string, data?: Record<string, unknown>): void;
+}
+export interface JavaScriptConfig {
+    /** Bootstrap JavaScript code to run before user scripts */
+    bootstrap?: string;
+    /**
+     * Tool invocation hook. When provided, code running in `js-exec` gets a
+     * global `tools` proxy that routes calls through this callback synchronously
+     * (the worker blocks via `Atomics.wait` while the host resolves the call).
+     *
+     * - `path`: dot-separated tool path (e.g. `"math.add"`). The proxy builds
+     *   it from JS property access — `tools.math.add(...)` becomes `"math.add"`.
+     * - `argsJson`: JSON-stringified args object, or empty string for no args.
+     * - return: JSON-stringified result, or empty string for `undefined`.
+     * - throw: propagates as a catchable exception inside the sandbox.
+     *
+     * Setting `invokeTool` implicitly enables `js-exec` (no separate
+     * `javascript: true` needed). Pair with `customCommands` if you want the
+     * same tools available as bash commands. The companion package
+     * `@just-bash/executor` produces a matching `invokeTool` + `commands` pair
+     * from inline tools and/or `@executor-js/sdk` discovery.
+     */
+    invokeTool?: (path: string, argsJson: string) => Promise<string>;
+}
+export interface BashOptions {
+    files?: InitialFiles;
+    env?: Record<string, string>;
+    cwd?: string;
+    fs?: IFileSystem;
+    /**
+     * Execution limits to prevent runaway compute.
+     * See ExecutionLimits interface for available options.
+     */
+    executionLimits?: ExecutionLimits;
+    /**
+     * @deprecated Use executionLimits.maxCallDepth instead
+     */
+    maxCallDepth?: number;
+    /**
+     * @deprecated Use executionLimits.maxCommandCount instead
+     */
+    maxCommandCount?: number;
+    /**
+     * @deprecated Use executionLimits.maxLoopIterations instead
+     */
+    maxLoopIterations?: number;
+    /**
+     * Custom secure fetch function. When provided, used instead of creating one
+     * from NetworkConfig. Enables wrapping the fetch layer with custom logic
+     * (e.g., policy evaluation) while keeping built-in curl unmodified.
+     * Network commands (curl, wget) are registered when either `fetch` or `network` is provided.
+     */
+    fetch?: SecureFetch;
+    /**
+     * Network configuration for commands like curl.
+     * Network access is disabled by default - you must explicitly configure allowed URLs.
+     */
+    network?: NetworkConfig;
+    /**
+     * Enable python3/python commands.
+     * Python is disabled by default as it introduces additional security surface
+     * (arbitrary code execution via CPython Emscripten).
+     */
+    python?: boolean;
+    /**
+     * Enable js-exec command for sandboxed JavaScript execution via QuickJS.
+     * Disabled by default. Can be a boolean or a config object with bootstrap code.
+     */
+    javascript?: boolean | JavaScriptConfig;
+    /**
+     * Optional list of command names to register.
+     * If not provided, all built-in commands are available.
+     * Use this to restrict which commands can be executed.
+     */
+    commands?: CommandName[];
+    /**
+     * Optional sleep function for the sleep command.
+     * If provided, used instead of real setTimeout.
+     * Useful for testing with mock clocks.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Custom commands to register alongside built-in commands.
+     * These take precedence over built-ins with the same name.
+     *
+     * @example
+     * ```ts
+     * import { defineCommand } from "just-bash";
+     *
+     * const hello = defineCommand("hello", async (args) => ({
+     *   stdout: `Hello, ${args[0] || "world"}!\n`,
+     *   stderr: "",
+     *   exitCode: 0,
+     * }));
+     *
+     * const bash = new Bash({ customCommands: [hello] });
+     * ```
+     */
+    customCommands?: CustomCommand[];
+    /**
+     * Optional logger for execution tracing.
+     * When provided, logs exec commands (info), stdout (debug), stderr (info), and exit codes (info).
+     * Disabled by default.
+     */
+    logger?: BashLogger;
+    /**
+     * Optional trace callback for performance profiling.
+     * When provided, commands emit timing events for analysis.
+     * Useful for identifying performance bottlenecks.
+     */
+    trace?: TraceCallback;
+    /**
+     * Defense-in-depth configuration.
+     *
+     * When enabled, monkey-patches dangerous JavaScript globals (Function, eval,
+     * setTimeout, process, etc.) during script execution to block potential
+     * escape vectors.
+     *
+     * IMPORTANT: This is a SECONDARY defense layer. It should never be relied
+     * upon as the primary security mechanism. The primary security comes from
+     * proper sandboxing, input validation, and architectural constraints.
+     *
+     * @example
+     * ```ts
+     * // Simple enable
+     * const bash = new Bash({ defenseInDepth: true });
+     *
+     * // With custom configuration
+     * const bash = new Bash({
+     *   defenseInDepth: {
+     *     enabled: true,
+     *     auditMode: false, // Set to true to log but not block
+     *     onViolation: (v) => console.warn('Violation:', v),
+     *   },
+     * });
+     * ```
+     */
+    defenseInDepth?: DefenseInDepthConfig | boolean;
+    /**
+     * Feature coverage writer for fuzzing instrumentation.
+     * When provided, interpreter emits coverage hits for analysis.
+     */
+    coverage?: FeatureCoverageWriter;
+    /**
+     * Virtual process info for sandboxed environment.
+     * Overrides the default virtual PID/UID values exposed via $$, $PPID, $UID, $EUID, $BASHPID,
+     * and /proc/self/status. Real host process info is never exposed.
+     */
+    processInfo?: {
+        pid?: number;
+        ppid?: number;
+        uid?: number;
+        gid?: number;
+    };
+}
+export interface ExecOptions {
+    /**
+     * Environment variables to set for this execution only.
+     * These are merged with the current environment and restored after execution.
+     */
+    env?: Record<string, string>;
+    /**
+     * If true, start execution with an empty environment and then apply `env`.
+     * If false/omitted, `env` is merged into the current environment.
+     */
+    replaceEnv?: boolean;
+    /**
+     * Working directory for this execution only.
+     * Restored to original after execution.
+     */
+    cwd?: string;
+    /**
+     * If true, skip normalizing the script (trimming leading whitespace from lines).
+     * Useful when running scripts where leading whitespace is significant (e.g., here-docs).
+     * Default: false
+     */
+    rawScript?: boolean;
+    /**
+     * Standard input to pass to the script.
+     * This will be available to commands via stdin (e.g., for `bash -c 'cat'`).
+     */
+    stdin?: string;
+    /**
+     * Shape of {@link stdin} — see `CommandExecOptions.stdinKind`.
+     * Defaults to `"text"` (UTF-8 encoded into bytes for byte consumers
+     * inside the script). Pass `"bytes"` when you've prepared a latin1
+     * byte buffer (e.g. `Buffer.from(buf).toString("latin1")`) and want
+     * it forwarded verbatim.
+     */
+    stdinKind?: "text" | "bytes";
+    /**
+     * Abort signal for cooperative cancellation.
+     * When aborted, the interpreter stops executing at the next statement boundary.
+     */
+    signal?: AbortSignal;
+    /**
+     * Additional argv entries appended to the first executed command at the interpreter level.
+     * Values bypass shell parsing entirely — no escaping, splitting, or globbing.
+     * Like child_process.spawnSync(cmd, args). These do not set or modify the shell's
+     * positional parameters ($1, $2, "$@", etc.).
+     */
+    args?: string[];
+}
+export declare class Bash {
+    readonly fs: IFileSystem;
+    private commands;
+    private useDefaultLayout;
+    private limits;
+    private secureFetch?;
+    private sleepFn?;
+    private traceFn?;
+    private logger?;
+    private defenseInDepthConfig?;
+    private coverageWriter?;
+    private jsBootstrapCode?;
+    private invokeToolFn?;
+    private transformPlugins;
+    private state;
+    private isConstructing;
+    constructor(options?: BashOptions);
+    registerCommand(command: Command): void;
+    private logResult;
+    exec(commandLine: string, options?: ExecOptions): Promise<BashExecResult>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    getCwd(): string;
+    getEnv(): Record<string, string>;
+    registerTransformPlugin(plugin: TransformPlugin<any>): void;
+    transform(commandLine: string): BashTransformResult;
+}