just-bash-mcp 2.7.0 → 2.9.0

package/README.md

@@ -7,15 +7,20 @@ An MCP (Model Context Protocol) server that provides a sandboxed bash environmen
 
 Execute bash commands in a secure, isolated environment with an in-memory virtual filesystem.
 
-Built on top of [`just-bash`](https://github.com/vercel-labs/just-bash) v2.5.2.
+Built on top of [`just-bash`](https://github.com/vercel-labs/just-bash) v2.9.6.
 
-## What's New in v2.1.0
+## What's New in v2.8.0
 
+- **Synced with upstream `just-bash` v2.9.6** - Latest security hardening, defense-in-depth, fuzzing, jq fixes, and large file support
+- **Defense-in-depth mode** - Opt-in monkey-patching of dangerous JS globals (`JUST_BASH_DEFENSE_IN_DEPTH=true`)
+- **Python support** - Python3 via Pyodide (`JUST_BASH_ENABLE_PYTHON=true`)
+- **Vercel Sandbox API** - Compatible `bash_sandbox_*` tools for isolated execution
+- **oxlint/oxfmt toolchain** - Replaced tsc/biome with faster oxlint and oxfmt
+- **Configurable limits** - Fine-grained control over glob ops, string length, array size, heredoc size, and more
 - **`rg` (ripgrep)** - Fast regex search with `--files`, `-d`, `--stats`, `-t markdown`
 - **`tar`** - Archive support with compression
 - **MountableFS** - Mount multiple filesystems at different paths
 - **ReadWriteFS** - Direct read-write access to real directories
-- **Multi-level glob patterns** - Improved `**/*.ts` style matching
 
 ## Features
 
@@ -120,6 +125,16 @@ Add to your MCP settings:
 | `JUST_BASH_MAX_CALL_DEPTH` | Maximum function recursion depth | `100` |
 | `JUST_BASH_MAX_COMMAND_COUNT` | Maximum total commands per execution | `10000` |
 | `JUST_BASH_MAX_LOOP_ITERATIONS` | Maximum iterations per loop | `10000` |
+| `JUST_BASH_ENABLE_PYTHON` | Enable Python3 via Pyodide (`true`/`false`) | `false` |
+| `JUST_BASH_DEFENSE_IN_DEPTH` | Enable defense-in-depth mode (`true`/`false`) | `false` |
+| `JUST_BASH_DEFENSE_IN_DEPTH_AUDIT` | Audit mode: log violations but don't block | `false` |
+| `JUST_BASH_DEFENSE_IN_DEPTH_LOG` | Log violations to console | `false` |
+| `JUST_BASH_OVERLAY_READ_ONLY` | OverlayFS read-only mode | `false` |
+| `JUST_BASH_MAX_RESPONSE_SIZE` | Max network response body size (bytes) | `10485760` |
+| `JUST_BASH_MAX_FILE_READ_SIZE` | Max file read size for OverlayFs/ReadWriteFs | `10485760` |
+| `JUST_BASH_ALLOWED_COMMANDS` | Comma-separated command allow-list | all |
+| `JUST_BASH_ENABLE_LOGGING` | Enable execution logging | `false` |
+| `JUST_BASH_ENABLE_TRACING` | Enable performance tracing | `false` |
 
 ## Tools
 
@@ -149,9 +164,28 @@ Reset the persistent bash environment, clearing all files and state.
 
 File operations in the persistent environment.
 
+### `bash_direct_read` / `bash_direct_write`
+
+Direct filesystem read/write operations (bypass shell execution).
+
 ### `bash_info`
 
-Get information about the bash environment configuration.
+Get information about the bash environment configuration, including defense-in-depth violation stats.
+
+### `bash_get_cwd` / `bash_get_env`
+
+Get current working directory or environment variables.
+
+### Vercel Sandbox API
+
+Compatible with the Vercel Sandbox API:
+
+- `bash_sandbox_run` - Run a command in the sandbox
+- `bash_sandbox_write_files` - Write multiple files at once
+- `bash_sandbox_read_file` - Read a file (supports base64 encoding)
+- `bash_sandbox_mkdir` - Create a directory
+- `bash_sandbox_stop` - Stop and clean up the sandbox
+- `bash_sandbox_reset` - Reset the sandbox state
 
 ## Supported Commands
 
@@ -235,6 +269,26 @@ Get information about the bash environment configuration.
 - Execution limits protect against infinite loops and recursion
 - No binary/WASM execution
 - Network disabled by default; when enabled, URL and method allow-lists enforced
+- **Defense-in-depth mode** (opt-in): Monkey-patches dangerous JS globals (`Function`, `eval`, `setTimeout`, `process`, etc.) during script execution to block escape vectors
+- **SecurityViolationLogger**: Tracks all defense-in-depth violations with full stats accessible via `bash_info`
+- **Rich network error classification**: `NetworkAccessDeniedError`, `TooManyRedirectsError`, `RedirectNotAllowedError` for precise error messages
+
+## Upstream API Coverage
+
+This wrapper integrates the full public API surface of `just-bash` v2.9.6:
+
+| Category | Exports Used |
+|----------|-------------|
+| Core | `Bash`, `BashOptions`, `ExecOptions`, `BashExecResult` |
+| Commands | `CommandName`, `AllCommandName`, `getCommandNames`, `getNetworkCommandNames`, `getPythonCommandNames` |
+| Custom Commands | `defineCommand`, `CustomCommand`, `LazyCommand` |
+| Filesystem | `InMemoryFs`, `OverlayFs`, `ReadWriteFs`, `MountableFs`, `IFileSystem` |
+| Network | `NetworkConfig`, `NetworkAccessDeniedError`, `TooManyRedirectsError`, `RedirectNotAllowedError` |
+| Sandbox | `Sandbox`, `SandboxCommand`, `SandboxOptions`, `OutputMessage` |
+| Security | `DefenseInDepthBox`, `SecurityViolationLogger`, `SecurityViolationError`, `createConsoleViolationCallback` |
+| Trace | `TraceCallback`, `TraceEvent` |
+
+All types are re-exported from `src/types.ts` for downstream consumers.
 
 ## License
 

package/package.json

@@ -1,33 +1,33 @@
 {
 	"name": "just-bash-mcp",
-	"version": "2.7.0",
+	"version": "2.9.0",
 	"description": "MCP server providing a sandboxed bash environment using just-bash",
 	"type": "module",
-	"main": "./build/index.js",
-	"types": "./build/index.d.ts",
+	"main": "./src/index.ts",
 	"exports": {
 		".": {
-			"types": "./build/index.d.ts",
-			"import": "./build/index.js"
+			"import": "./src/index.ts"
 		}
 	},
 	"bin": {
-		"just-bash-mcp": "build/index.js"
+		"just-bash-mcp": "src/index.ts"
 	},
 	"files": [
-		"build",
+		"src",
+		"tsconfig.json",
 		"README.md",
 		"LICENSE"
 	],
 	"scripts": {
-		"build": "tsc",
-		"start": "node build/index.js",
-		"dev": "bun src/index.ts",
-		"typecheck": "bun tsc --noEmit",
-		"lint": "bunx @biomejs/biome@latest lint",
-		"format": "bunx @biomejs/biome@latest format --write",
-		"check": "bunx @biomejs/biome@latest check --write",
-		"prepublishOnly": "bun run build"
+		"start": "node src/index.ts",
+		"dev": "node --watch src/index.ts",
+		"lint": "oxlint --type-aware",
+		"lint:fix": "oxlint --type-aware --fix",
+		"typecheck": "oxlint --type-aware --type-check",
+		"format": "oxfmt --write src/",
+		"format:check": "oxfmt --check src/",
+		"check": "oxlint --type-aware --type-check && oxfmt --check src/",
+		"ci": "oxlint --type-aware --type-check && oxfmt --check src/"
 	},
 	"keywords": [
 		"mcp",
@@ -56,16 +56,18 @@
 	},
 	"homepage": "https://github.com/dalist1/just-bash-mcp#readme",
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=22.0.0"
 	},
+	"packageManager": "bun@1.3.8",
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.25.2",
-		"just-bash": "^2.7.0",
-		"zod": "^4.3.5"
+		"@modelcontextprotocol/sdk": "^1.26.0",
+		"just-bash": "^2.9.6",
+		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.3.11",
-		"@types/node": "^25.0.6",
-		"typescript": "^5.9.3"
+		"@types/node": "^25.2.2",
+		"oxfmt": "^0.28.0",
+		"oxlint": "^1.43.0",
+		"oxlint-tsgolint": "^0.11.5"
 	}
 }

package/src/config/index.ts

@@ -0,0 +1,402 @@
+/**
+ * Configuration module for just-bash-mcp
+ * Handles environment variable parsing and configuration building
+ */
+
+import {
+	type BashLogger,
+	type BashOptions,
+	type CommandName,
+	type DefenseInDepthConfig,
+	type MountConfig,
+	type NetworkConfig,
+	type TraceCallback,
+	type TraceEvent,
+	OverlayFs,
+	ReadWriteFs,
+	SecurityViolationLogger,
+	createConsoleViolationCallback,
+} from "just-bash";
+
+// Re-export upstream types used by other modules
+export type { DefenseInDepthConfig, TraceCallback, TraceEvent };
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+
+// ============================================================================
+// Environment Variable Parsing
+// ============================================================================
+
+function parseEnvString(key: string, defaultValue: string): string {
+	return process.env[key] || defaultValue;
+}
+
+function parseEnvBoolean(key: string, defaultValue: boolean): boolean {
+	return process.env[key] === "true" ? true : defaultValue;
+}
+
+function parseEnvInt(key: string, defaultValue: number): number {
+	const value = process.env[key];
+	if (!value) return defaultValue;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? defaultValue : parsed;
+}
+
+function parseEnvStringArray(key: string): string[] {
+	return process.env[key]?.split(",").filter(Boolean) || [];
+}
+
+// ============================================================================
+// Configuration Constants
+// ============================================================================
+
+export interface Config {
+	readonly VERSION: string;
+	readonly SERVER_NAME: string;
+	readonly OVERLAY_ROOT: string | undefined;
+	readonly READ_WRITE_ROOT: string | undefined;
+	readonly MOUNTS_CONFIG: string | undefined;
+	readonly INITIAL_CWD: string;
+	readonly ALLOW_NETWORK: boolean;
+	readonly ALLOWED_URL_PREFIXES: string[];
+	readonly ALLOWED_METHODS: HttpMethod[];
+	readonly MAX_REDIRECTS: number;
+	readonly NETWORK_TIMEOUT_MS: number;
+	readonly MAX_RESPONSE_SIZE: number | undefined;
+	readonly MAX_CALL_DEPTH: number;
+	readonly MAX_COMMAND_COUNT: number;
+	readonly MAX_LOOP_ITERATIONS: number;
+	readonly MAX_AWK_ITERATIONS: number;
+	readonly MAX_SED_ITERATIONS: number;
+	readonly MAX_JQ_ITERATIONS: number;
+	readonly MAX_GLOB_OPERATIONS: number;
+	readonly MAX_STRING_LENGTH: number;
+	readonly MAX_ARRAY_ELEMENTS: number;
+	readonly MAX_HEREDOC_SIZE: number;
+	readonly MAX_SUBSTITUTION_DEPTH: number;
+	readonly MAX_SQLITE_TIMEOUT_MS: number;
+	readonly MAX_PYTHON_TIMEOUT_MS: number;
+	readonly MAX_OUTPUT_LENGTH: number;
+	readonly MAX_FILE_READ_SIZE: number | undefined;
+	readonly ENABLE_LOGGING: boolean;
+	readonly ENABLE_TRACING: boolean;
+	readonly ENABLE_PYTHON: boolean;
+	readonly ENABLE_DEFENSE_IN_DEPTH: boolean;
+	readonly DEFENSE_IN_DEPTH_AUDIT: boolean;
+	readonly DEFENSE_IN_DEPTH_LOG: boolean;
+	readonly OVERLAY_READ_ONLY: boolean;
+	readonly ALLOWED_COMMANDS: CommandName[] | undefined;
+}
+
+function getAllowedMethods(): HttpMethod[] {
+	const methods = parseEnvStringArray("JUST_BASH_ALLOWED_METHODS");
+	return methods.length > 0 ? (methods as HttpMethod[]) : ["GET", "HEAD"];
+}
+
+function getAllowedCommands(): CommandName[] | undefined {
+	const commands = parseEnvStringArray("JUST_BASH_ALLOWED_COMMANDS");
+	return commands.length > 0 ? (commands as CommandName[]) : undefined;
+}
+
+function parseEnvOptionalInt(key: string): number | undefined {
+	const value = process.env[key];
+	if (!value) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+export const config: Config = {
+	// Server info
+	VERSION: "2.8.0",
+	SERVER_NAME: "just-bash-mcp",
+
+	// Filesystem configuration
+	OVERLAY_ROOT: process.env.JUST_BASH_OVERLAY_ROOT,
+	READ_WRITE_ROOT: process.env.JUST_BASH_READ_WRITE_ROOT,
+	MOUNTS_CONFIG: process.env.JUST_BASH_MOUNTS,
+	INITIAL_CWD: parseEnvString("JUST_BASH_CWD", "/home/user"),
+
+	// Network configuration
+	ALLOW_NETWORK: parseEnvBoolean("JUST_BASH_ALLOW_NETWORK", false),
+	ALLOWED_URL_PREFIXES: parseEnvStringArray("JUST_BASH_ALLOWED_URLS"),
+	ALLOWED_METHODS: getAllowedMethods(),
+	MAX_REDIRECTS: parseEnvInt("JUST_BASH_MAX_REDIRECTS", 20),
+	NETWORK_TIMEOUT_MS: parseEnvInt("JUST_BASH_NETWORK_TIMEOUT_MS", 30000),
+	MAX_RESPONSE_SIZE: parseEnvOptionalInt("JUST_BASH_MAX_RESPONSE_SIZE"),
+
+	// Execution limits
+	MAX_CALL_DEPTH: parseEnvInt("JUST_BASH_MAX_CALL_DEPTH", 100),
+	MAX_COMMAND_COUNT: parseEnvInt("JUST_BASH_MAX_COMMAND_COUNT", 10000),
+	MAX_LOOP_ITERATIONS: parseEnvInt("JUST_BASH_MAX_LOOP_ITERATIONS", 10000),
+	MAX_AWK_ITERATIONS: parseEnvInt("JUST_BASH_MAX_AWK_ITERATIONS", 10000),
+	MAX_SED_ITERATIONS: parseEnvInt("JUST_BASH_MAX_SED_ITERATIONS", 10000),
+	MAX_JQ_ITERATIONS: parseEnvInt("JUST_BASH_MAX_JQ_ITERATIONS", 10000),
+	MAX_GLOB_OPERATIONS: parseEnvInt("JUST_BASH_MAX_GLOB_OPERATIONS", 100000),
+	MAX_STRING_LENGTH: parseEnvInt("JUST_BASH_MAX_STRING_LENGTH", 10485760),
+	MAX_ARRAY_ELEMENTS: parseEnvInt("JUST_BASH_MAX_ARRAY_ELEMENTS", 100000),
+	MAX_HEREDOC_SIZE: parseEnvInt("JUST_BASH_MAX_HEREDOC_SIZE", 10485760),
+	MAX_SUBSTITUTION_DEPTH: parseEnvInt("JUST_BASH_MAX_SUBSTITUTION_DEPTH", 50),
+	MAX_SQLITE_TIMEOUT_MS: parseEnvInt("JUST_BASH_MAX_SQLITE_TIMEOUT_MS", 5000),
+	MAX_PYTHON_TIMEOUT_MS: parseEnvInt("JUST_BASH_MAX_PYTHON_TIMEOUT_MS", 30000),
+
+	// Output limits
+	MAX_OUTPUT_LENGTH: parseEnvInt("JUST_BASH_MAX_OUTPUT_LENGTH", 30000),
+
+	// Filesystem limits
+	MAX_FILE_READ_SIZE: parseEnvOptionalInt("JUST_BASH_MAX_FILE_READ_SIZE"),
+
+	// Debugging
+	ENABLE_LOGGING: parseEnvBoolean("JUST_BASH_ENABLE_LOGGING", false),
+	ENABLE_TRACING: parseEnvBoolean("JUST_BASH_ENABLE_TRACING", false),
+
+	// Feature flags
+	ENABLE_PYTHON: parseEnvBoolean("JUST_BASH_ENABLE_PYTHON", false),
+	ENABLE_DEFENSE_IN_DEPTH: parseEnvBoolean("JUST_BASH_DEFENSE_IN_DEPTH", false),
+	DEFENSE_IN_DEPTH_AUDIT: parseEnvBoolean("JUST_BASH_DEFENSE_IN_DEPTH_AUDIT", false),
+	DEFENSE_IN_DEPTH_LOG: parseEnvBoolean("JUST_BASH_DEFENSE_IN_DEPTH_LOG", false),
+	OVERLAY_READ_ONLY: parseEnvBoolean("JUST_BASH_OVERLAY_READ_ONLY", false),
+
+	// Command filtering
+	ALLOWED_COMMANDS: getAllowedCommands(),
+};
+
+// ============================================================================
+// Logger and Trace Callback
+// ============================================================================
+
+export const bashLogger: BashLogger | undefined = config.ENABLE_LOGGING
+	? {
+			info(message: string, data?: Record<string, unknown>): void {
+				if (data) {
+					console.error(`[just-bash] INFO: ${message}`, data);
+				} else {
+					console.error(`[just-bash] INFO: ${message}`);
+				}
+			},
+			debug(message: string, data?: Record<string, unknown>): void {
+				if (data) {
+					console.error(`[just-bash] DEBUG: ${message}`, data);
+				} else {
+					console.error(`[just-bash] DEBUG: ${message}`);
+				}
+			},
+		}
+	: undefined;
+
+export const traceCallback: TraceCallback | undefined = config.ENABLE_TRACING
+	? (event: TraceEvent) => {
+			if (event.details) {
+				console.error(
+					`[just-bash] TRACE: ${event.category}/${event.name} ${event.durationMs}ms`,
+					JSON.stringify(event.details),
+				);
+			} else {
+				console.error(`[just-bash] TRACE: ${event.category}/${event.name} ${event.durationMs}ms`);
+			}
+		}
+	: undefined;
+
+// ============================================================================
+// Defense-in-Depth Configuration
+// ============================================================================
+
+/**
+ * Shared SecurityViolationLogger instance for tracking violations across
+ * all Bash instances. Exposed so info-tools can report violation stats.
+ */
+export const violationLogger = new SecurityViolationLogger();
+
+/**
+ * Build the defense-in-depth configuration from environment variables.
+ * Returns `false` when disabled, or a full DefenseInDepthConfig object.
+ */
+export function buildDefenseInDepthConfig(): DefenseInDepthConfig | false {
+	if (!config.ENABLE_DEFENSE_IN_DEPTH) {
+		return false;
+	}
+
+	const consoleCallback = config.DEFENSE_IN_DEPTH_LOG
+		? createConsoleViolationCallback()
+		: undefined;
+
+	return {
+		enabled: true,
+		auditMode: config.DEFENSE_IN_DEPTH_AUDIT,
+		onViolation: (violation) => {
+			violationLogger.record(violation);
+			consoleCallback?.(violation);
+		},
+	};
+}
+
+// ============================================================================
+// Configuration Builders
+// ============================================================================
+
+export function buildNetworkConfig(): NetworkConfig | undefined {
+	if (!config.ALLOW_NETWORK) {
+		return undefined;
+	}
+
+	if (config.ALLOWED_URL_PREFIXES.length > 0) {
+		return {
+			allowedUrlPrefixes: config.ALLOWED_URL_PREFIXES,
+			allowedMethods: config.ALLOWED_METHODS,
+			maxRedirects: config.MAX_REDIRECTS,
+			timeoutMs: config.NETWORK_TIMEOUT_MS,
+			...(config.MAX_RESPONSE_SIZE !== undefined && {
+				maxResponseSize: config.MAX_RESPONSE_SIZE,
+			}),
+		};
+	}
+
+	return {
+		dangerouslyAllowFullInternetAccess: true,
+		maxRedirects: config.MAX_REDIRECTS,
+		timeoutMs: config.NETWORK_TIMEOUT_MS,
+		...(config.MAX_RESPONSE_SIZE !== undefined && {
+			maxResponseSize: config.MAX_RESPONSE_SIZE,
+		}),
+	};
+}
+
+export function buildExecutionLimits(): NonNullable<BashOptions["executionLimits"]> {
+	return {
+		maxCallDepth: config.MAX_CALL_DEPTH,
+		maxCommandCount: config.MAX_COMMAND_COUNT,
+		maxLoopIterations: config.MAX_LOOP_ITERATIONS,
+		maxAwkIterations: config.MAX_AWK_ITERATIONS,
+		maxSedIterations: config.MAX_SED_ITERATIONS,
+		maxJqIterations: config.MAX_JQ_ITERATIONS,
+		maxGlobOperations: config.MAX_GLOB_OPERATIONS,
+		maxStringLength: config.MAX_STRING_LENGTH,
+		maxArrayElements: config.MAX_ARRAY_ELEMENTS,
+		maxHeredocSize: config.MAX_HEREDOC_SIZE,
+		maxSubstitutionDepth: config.MAX_SUBSTITUTION_DEPTH,
+		maxSqliteTimeoutMs: config.MAX_SQLITE_TIMEOUT_MS,
+		maxPythonTimeoutMs: config.MAX_PYTHON_TIMEOUT_MS,
+	};
+}
+
+export function parseMountsConfig(): MountConfig[] {
+	if (!config.MOUNTS_CONFIG) return [];
+	try {
+		const parsed: unknown = JSON.parse(config.MOUNTS_CONFIG);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.map(
+			(mount: { mountPoint: string; root: string; type?: string; readOnly?: boolean }) => {
+				const fsType = mount.type || "overlay";
+				const maxFileReadSize = config.MAX_FILE_READ_SIZE;
+				const filesystem =
+					fsType === "readwrite"
+						? new ReadWriteFs({
+								root: mount.root,
+								...(maxFileReadSize !== undefined && { maxFileReadSize }),
+							})
+						: new OverlayFs({
+								root: mount.root,
+								readOnly: mount.readOnly,
+								...(maxFileReadSize !== undefined && { maxFileReadSize }),
+							});
+				return { mountPoint: mount.mountPoint, filesystem };
+			},
+		);
+	} catch {
+		return [];
+	}
+}
+
+// ============================================================================
+// Environment Variables Documentation
+// ============================================================================
+
+export const ENVIRONMENT_VARIABLES = {
+	JUST_BASH_OVERLAY_ROOT: "Real directory to mount as overlay (read from disk, write to memory)",
+	JUST_BASH_OVERLAY_READ_ONLY:
+		"If true, all writes to overlay filesystem throw errors (default: false)",
+	JUST_BASH_READ_WRITE_ROOT: "Real directory with read-write access",
+	JUST_BASH_MOUNTS: "JSON array of mount configurations (supports type, readOnly fields)",
+	JUST_BASH_CWD: "Initial working directory (default: /home/user)",
+	JUST_BASH_ALLOW_NETWORK: "Enable network access (default: false)",
+	JUST_BASH_ALLOWED_URLS: "Comma-separated URL prefixes to allow",
+	JUST_BASH_ALLOWED_METHODS: "Comma-separated HTTP methods (default: GET,HEAD)",
+	JUST_BASH_ALLOWED_COMMANDS: "Comma-separated list of allowed commands",
+	JUST_BASH_MAX_REDIRECTS: "Max HTTP redirects (default: 20)",
+	JUST_BASH_NETWORK_TIMEOUT_MS: "Network timeout in ms (default: 30000)",
+	JUST_BASH_MAX_RESPONSE_SIZE: "Max network response body size in bytes (default: 10MB)",
+	JUST_BASH_MAX_CALL_DEPTH: "Max recursion depth (default: 100)",
+	JUST_BASH_MAX_COMMAND_COUNT: "Max commands per execution (default: 10000)",
+	JUST_BASH_MAX_LOOP_ITERATIONS: "Max bash loop iterations (default: 10000)",
+	JUST_BASH_MAX_AWK_ITERATIONS: "Max AWK while/for loop iterations (default: 10000)",
+	JUST_BASH_MAX_SED_ITERATIONS: "Max sed branch loop iterations (default: 10000)",
+	JUST_BASH_MAX_JQ_ITERATIONS: "Max jq loop iterations (default: 10000)",
+	JUST_BASH_MAX_GLOB_OPERATIONS: "Max glob filesystem operations (default: 100000)",
+	JUST_BASH_MAX_STRING_LENGTH: "Max string length in bytes (default: 10485760 = 10MB)",
+	JUST_BASH_MAX_ARRAY_ELEMENTS: "Max array elements (default: 100000)",
+	JUST_BASH_MAX_HEREDOC_SIZE: "Max heredoc size in bytes (default: 10485760 = 10MB)",
+	JUST_BASH_MAX_SUBSTITUTION_DEPTH: "Max command substitution nesting depth (default: 50)",
+	JUST_BASH_MAX_SQLITE_TIMEOUT_MS: "SQLite timeout in ms (default: 5000)",
+	JUST_BASH_MAX_PYTHON_TIMEOUT_MS: "Python timeout in ms (default: 30000)",
+	JUST_BASH_MAX_OUTPUT_LENGTH: "Max output length (default: 30000)",
+	JUST_BASH_MAX_FILE_READ_SIZE:
+		"Max file read size in bytes for OverlayFs/ReadWriteFs (default: 10MB)",
+	JUST_BASH_ENABLE_LOGGING: "Enable debug logging (default: false)",
+	JUST_BASH_ENABLE_TRACING: "Enable performance tracing (default: false)",
+	JUST_BASH_ENABLE_PYTHON: "Enable python3/python commands via Pyodide (default: false)",
+	JUST_BASH_DEFENSE_IN_DEPTH:
+		"Enable defense-in-depth mode that patches dangerous JS globals (default: false)",
+	JUST_BASH_DEFENSE_IN_DEPTH_AUDIT:
+		"Audit mode: log violations but don't block them (default: false, requires DEFENSE_IN_DEPTH=true)",
+	JUST_BASH_DEFENSE_IN_DEPTH_LOG:
+		"Log violations to console via createConsoleViolationCallback (default: false)",
+} as const;
+
+// ============================================================================
+// Command Categories Documentation
+// ============================================================================
+
+export const COMMAND_CATEGORIES = {
+	fileOperations: "cat, cp, file, ln, ls, mkdir, mv, readlink, rm, rmdir, split, stat, touch, tree",
+	textProcessing:
+		"awk, base64, column, comm, cut, diff, expand, fold, grep (egrep, fgrep), head, join, md5sum, nl, od, paste, printf, rev, rg (ripgrep), sed, sha1sum, sha256sum, sort, strings, tac, tail, tr, unexpand, uniq, wc, xargs",
+	dataProcessing:
+		"jq (JSON), python3/python (Python via Pyodide), sqlite3 (SQLite), xan (CSV), yq (YAML/XML/TOML/CSV)",
+	compression: "gzip (gunzip, zcat), tar",
+	navigation:
+		"basename, cd, dirname, du, echo, env, export, find, hostname, printenv, pwd, tee, whoami",
+	shellUtilities:
+		"alias, bash, chmod, clear, date, expr, false, help, history, seq, sh, sleep, time, timeout, true, unalias, which",
+	network: "curl, html-to-markdown (when network enabled)",
+} as const;
+
+// ============================================================================
+// Features Documentation
+// ============================================================================
+
+export const FEATURES = {
+	customCommands:
+		"Define custom TypeScript commands using defineCommand() from just-bash, supports lazy-loading via LazyCommand",
+	rawScript: "Preserve leading whitespace in scripts (useful for here-docs)",
+	logger: "Optional execution logging via BashLogger interface",
+	trace: "Performance profiling via TraceCallback (upstream type)",
+	commandFilter: "Restrict available commands via JUST_BASH_ALLOWED_COMMANDS env var",
+	sandboxApi:
+		"Vercel Sandbox compatible API via bash_sandbox_* tools (run, write, read, mkdir, stop, reset)",
+	python: "Python support via Pyodide (opt-in via JUST_BASH_ENABLE_PYTHON=true)",
+	defenseInDepth:
+		"Defense-in-depth with SecurityViolationLogger, audit mode, and console logging (opt-in via JUST_BASH_DEFENSE_IN_DEPTH=true)",
+	overlayReadOnly:
+		"Read-only overlay filesystem mode (opt-in via JUST_BASH_OVERLAY_READ_ONLY=true)",
+	networkResponseSize:
+		"Configurable max network response body size via JUST_BASH_MAX_RESPONSE_SIZE",
+	fileReadSizeLimit:
+		"Configurable max file read size for OverlayFs/ReadWriteFs via JUST_BASH_MAX_FILE_READ_SIZE",
+	networkErrorHandling:
+		"Rich network error classification: NetworkAccessDeniedError, TooManyRedirectsError, RedirectNotAllowedError",
+	securityViolationTracking:
+		"SecurityViolationLogger tracks all defense-in-depth violations with stats via bash_info",
+} as const;

package/{build/index.js → src/index.ts}

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 /**
  * just-bash-mcp - MCP Server for sandboxed bash execution
  *
@@ -8,23 +9,28 @@
  * @see https://github.com/vercel-labs/just-bash
  * @see https://modelcontextprotocol.io
  */
+
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { config } from "./config/index.js";
-import { registerAllTools } from "./tools/index.js";
+
+import { config } from "./config/index.ts";
+import { registerAllTools } from "./tools/index.ts";
+
 // ============================================================================
 // Server Initialization
 // ============================================================================
+
 const server = new McpServer({
-    name: config.SERVER_NAME,
-    version: config.VERSION,
+	name: config.SERVER_NAME,
+	version: config.VERSION,
 });
+
 // Register all tools with the server
 registerAllTools(server);
+
 // ============================================================================
 // Start Server
 // ============================================================================
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`${config.SERVER_NAME} server v${config.VERSION} running on stdio`);
-//# sourceMappingURL=index.js.map