Summary

Introduces — a runtime-agnostic bash interpreter with an in-memory filesystem, 80+ built-in commands, and pluggable backends for SQL, code execution, and HTML-to-Markdown conversion. Forked from just-bash (Apache-2.0, Vercel Labs) and substantially extended.

Also migrates @cloudflare/think from just-bash to @cloudflare/shell.

What's in the package

Core interpreter

• Full bash subset: pipes, redirects, variables, arithmetic, arrays, globbing, brace expansion, functions, heredocs, process substitution, set -euo pipefail
• 80+ built-in commands across I/O, filesystem, text processing, data, archives, network, and control flow
• In-memory POSIX-like filesystem with symlinks, permissions, /proc, /dev/null, /dev/urandom, lazy file loading
• defineCommand() API for registering custom TypeScript commands
• Configurable execution limits (18 knobs) to prevent resource exhaustion in multi-tenant environments
• RE2-based regex engine via re2js to avoid ReDoS from user-supplied patterns
• Network access disabled by default; opt-in via URL allow-list with optional SSRF protection (denyPrivateRanges)

Pluggable interface architecture

The core has zero WASM/native dependencies. Three small interfaces externalize heavyweight capabilities:

Entry points and adapters

• @cloudflare/shell — core shell, filesystem, interfaces, types
• @cloudflare/shell/workers — DOSqlExecutor (Durable Object SqlStorage), D1SqlExecutor (Cloudflare D1), DynamicIsolateExecutor (Worker Loader API for isolated V8 code execution), WorkersAIMarkdownConverter
• @cloudflare/shell/node — BetterSqlite3Executor, ChildProcessExecutor, TurndownConverter
• @cloudflare/shell/embedded — EmbeddedExecutor with QuickJS (~500KB WASM) and Pyodide (~10MB WASM)

Testing

• Syntax tests: pipes, redirects, variables, arithmetic, arrays, loops, functions, heredocs, set -e/-u/-o pipefail, command substitution, process substitution, brace/glob expansion
• Execution protection tests: all 18 execution limits
• Command tests: grep, sed, jq, awk, find, tar, curl, sqlite3, etc.
• Spec-compliance tests: BusyBox grep/sed test suites, GNU grep BRE/ERE/spencer test suites, jq upstream test suite, bash spec cases
• Workers integration tests: Durable Object SQL, code execution via Worker Loader
• Node.js integration tests: better-sqlite3, child_process, turndown
• E2E Playwright tests against a real deployed Worker

Differences from just-bash

• Pluggable adapters instead of bundled WASM — zero core dependencies on platform APIs
• RE2 regex engine instead of native RegExp
• 13 additional execution limits (just-bash has 5)
• SSRF protection via denyPrivateRanges
• xan and yq not ported (niche/overlapping with jq)

@cloudflare/think migration

• Replaces just-bash peer/dev dep with @cloudflare/shell
• Updates vitest optimizer config accordingly