From 0ec8ecaf12239e5c7222e0f4905a297d4f41cd2f Mon Sep 17 00:00:00 2001 From: Mykhailo Chalyi Date: Tue, 26 May 2026 04:24:00 +0000 Subject: [PATCH] chore: normalize Bashkit capitalization Replace stray "BashKit" occurrences across specs, docs, examples, builtins, and tests with the official "Bashkit". Preserved the CHANGELOG entry that records the original rename and the architecture spec line that intentionally cites the wrong spelling. --- crates/bashkit-eval/README.md | 2 +- crates/bashkit/docs/threat-model.md | 6 ++-- crates/bashkit/examples/python_scripts.rs | 6 ++-- crates/bashkit/examples/typescript_scripts.rs | 4 +-- crates/bashkit/src/builtins/python.rs | 12 +++---- crates/bashkit/src/builtins/typescript.rs | 4 +-- crates/bashkit/src/credential.rs | 2 +- crates/bashkit/tests/threat_model_tests.rs | 8 ++--- .../tests/typescript_security_tests.rs | 4 +-- specs/python-builtin.md | 20 +++++------ specs/threat-model.md | 34 +++++++++---------- specs/zapcode-runtime.md | 16 ++++----- 12 files changed, 59 insertions(+), 59 deletions(-) diff --git a/crates/bashkit-eval/README.md b/crates/bashkit-eval/README.md index 14af27df0..97ec75670 100644 --- a/crates/bashkit-eval/README.md +++ b/crates/bashkit-eval/README.md @@ -1,4 +1,4 @@ -# BashKit Eval +# Bashkit Eval LLM evaluation harness for bashkit tool usage. Measures how well models use bashkit's bash tool in agentic workloads. diff --git a/crates/bashkit/docs/threat-model.md b/crates/bashkit/docs/threat-model.md index 1a059a370..0adacc7eb 100644 --- a/crates/bashkit/docs/threat-model.md +++ b/crates/bashkit/docs/threat-model.md @@ -563,8 +563,8 @@ Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem. | Shell escape (TM-PY-004) | `os.system()` | Monty has no os.system/subprocess | MITIGATED | | Real FS access (TM-PY-005) | `open()` | Monty has no open() builtin | MITIGATED | | Error info leak (TM-PY-006) | Errors go to stdout | Errors go to stderr, not stdout | MITIGATED | -| Real FS read (TM-PY-015) | `Path.read_text()` | VFS bridge reads only from BashKit VFS | MITIGATED | -| Real FS write (TM-PY-016) | `Path.write_text()` | VFS bridge writes only to BashKit VFS | MITIGATED | +| Real FS read (TM-PY-015) | `Path.read_text()` | VFS bridge reads only from Bashkit VFS | MITIGATED | +| Real FS write (TM-PY-016) | `Path.write_text()` | VFS bridge writes only to Bashkit VFS | MITIGATED | | Path traversal (TM-PY-017) | `../../etc/passwd` | VFS path normalization | MITIGATED | | Bash/Python VFS isolation (TM-PY-018) | Cross-tenant access | Shared VFS by design; no cross-tenant | MITIGATED | | Crash on missing file (TM-PY-019) | Missing file panic | FileNotFoundError raised, not panic | MITIGATED | @@ -581,7 +581,7 @@ Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem. **Architecture:** ```text -Python code → Monty VM → OsCall pause → BashKit VFS bridge → resume +Python code → Monty VM → OsCall pause → Bashkit VFS bridge → resume ``` Monty runs directly in the host process. Resource limits (memory, allocations, diff --git a/crates/bashkit/examples/python_scripts.rs b/crates/bashkit/examples/python_scripts.rs index fdc55da44..db553e965 100644 --- a/crates/bashkit/examples/python_scripts.rs +++ b/crates/bashkit/examples/python_scripts.rs @@ -1,9 +1,9 @@ //! Python Scripts Example //! -//! Demonstrates running Python code inside BashKit's virtual environment using the +//! Demonstrates running Python code inside Bashkit's virtual environment using the //! embedded Monty interpreter. Python runs entirely in-memory with //! resource limits. Python pathlib.Path operations are bridged to -//! BashKit's virtual filesystem. +//! Bashkit's virtual filesystem. //! //! Run with: cargo run --features python --example python_scripts @@ -11,7 +11,7 @@ use bashkit::Bash; #[tokio::main] async fn main() -> anyhow::Result<()> { - println!("=== BashKit Python Integration ===\n"); + println!("=== Bashkit Python Integration ===\n"); let mut bash = Bash::builder() .python() diff --git a/crates/bashkit/examples/typescript_scripts.rs b/crates/bashkit/examples/typescript_scripts.rs index 8cf9c2ebd..8da85351f 100644 --- a/crates/bashkit/examples/typescript_scripts.rs +++ b/crates/bashkit/examples/typescript_scripts.rs @@ -1,6 +1,6 @@ //! TypeScript Scripts Example //! -//! Demonstrates running TypeScript code inside BashKit's virtual environment +//! Demonstrates running TypeScript code inside Bashkit's virtual environment //! using the embedded ZapCode interpreter. TypeScript runs entirely in-memory //! with resource limits. VFS operations are bridged via external function //! suspend/resume. @@ -11,7 +11,7 @@ use bashkit::Bash; #[tokio::main] async fn main() -> anyhow::Result<()> { - println!("=== BashKit TypeScript Integration ===\n"); + println!("=== Bashkit TypeScript Integration ===\n"); let mut bash = Bash::builder().typescript().build(); diff --git a/crates/bashkit/src/builtins/python.rs b/crates/bashkit/src/builtins/python.rs index 0f86554a0..6a82df4cc 100644 --- a/crates/bashkit/src/builtins/python.rs +++ b/crates/bashkit/src/builtins/python.rs @@ -9,7 +9,7 @@ //! # Overview //! //! Virtual Python execution with resource limits and VFS access. -//! Python `pathlib.Path` operations are bridged to BashKit's virtual filesystem +//! Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem //! via Monty's OsCall pause/resume mechanism. No real filesystem or network access. //! //! Supports: `python -c "code"`, `python script.py`, stdin piping. @@ -181,7 +181,7 @@ impl std::fmt::Debug for PythonExternalFns { /// The python/python3 builtin command. /// /// Executes Python code using the embedded Monty interpreter (pydantic/monty). -/// Python `pathlib.Path` operations are bridged to BashKit's VFS — files +/// Python `pathlib.Path` operations are bridged to Bashkit's VFS — files /// created by bash (`cat > file`) are readable from Python, and vice versa. /// /// # Usage @@ -456,7 +456,7 @@ impl Builtin for Python { /// Execute Python code via Monty with resource limits and VFS bridging. /// /// Uses Monty's start/resume API: execution pauses at filesystem operations -/// (OsCall), we bridge them to BashKit's VFS, then resume. +/// (OsCall), we bridge them to Bashkit's VFS, then resume. async fn run_python( code: &str, filename: &str, @@ -598,7 +598,7 @@ async fn run_python( } // --------------------------------------------------------------------------- -// VFS bridging: Monty OsCall → BashKit FileSystem +// VFS bridging: Monty OsCall → Bashkit FileSystem // --------------------------------------------------------------------------- /// Dispatch a Monty OsCall to the appropriate VFS operation. @@ -768,7 +768,7 @@ async fn handle_os_call( } } OsFunction::Resolve | OsFunction::Absolute => { - // No symlink resolution in BashKit VFS; just return absolute path + // No symlink resolution in Bashkit VFS; just return absolute path ExtFunctionResult::Return(MontyObject::Path(path.to_string_lossy().to_string())) } // Getenv/GetEnviron handled above @@ -797,7 +797,7 @@ fn resolve_python_path(path_str: &str, cwd: &Path) -> PathBuf { } } -/// Map a BashKit VFS error to a Python exception via ExtFunctionResult. +/// Map a Bashkit VFS error to a Python exception via ExtFunctionResult. fn map_vfs_error(e: crate::Error, path: &Path) -> ExtFunctionResult { let msg = e.to_string(); let path_str = path.display().to_string(); diff --git a/crates/bashkit/src/builtins/typescript.rs b/crates/bashkit/src/builtins/typescript.rs index 8df06d159..bbd19ca2c 100644 --- a/crates/bashkit/src/builtins/typescript.rs +++ b/crates/bashkit/src/builtins/typescript.rs @@ -642,7 +642,7 @@ impl Builtin for TypeScript { /// Execute TypeScript code via ZapCode with resource limits and VFS bridging. /// /// Uses ZapCode's start/resume API: execution suspends at external function calls -/// (VFS operations), we bridge them to BashKit's VFS, then resume. +/// (VFS operations), we bridge them to Bashkit's VFS, then resume. async fn run_typescript( code: &str, fs: Arc, @@ -769,7 +769,7 @@ async fn handle_external_call( } // --------------------------------------------------------------------------- -// VFS bridging: ZapCode external functions → BashKit FileSystem +// VFS bridging: ZapCode external functions → Bashkit FileSystem // --------------------------------------------------------------------------- /// Extract a path string from the first arg, resolve relative to cwd. diff --git a/crates/bashkit/src/credential.rs b/crates/bashkit/src/credential.rs index ada659ab8..c3382bc58 100644 --- a/crates/bashkit/src/credential.rs +++ b/crates/bashkit/src/credential.rs @@ -132,7 +132,7 @@ const PLACEHOLDER_PREFIX: &str = "bk_placeholder_"; /// # Security /// /// The placeholder acts like a bearer capability inside scripts: if a script -/// sends the placeholder value to a URL matching a credential rule, BashKit +/// sends the placeholder value to a URL matching a credential rule, Bashkit /// injects the real credential-owned header. The token therefore must come /// from a security-grade RNG so it cannot be predicted, brute-forced, or /// reproduced from observed program state. diff --git a/crates/bashkit/tests/threat_model_tests.rs b/crates/bashkit/tests/threat_model_tests.rs index a74abd4e8..b345f1837 100644 --- a/crates/bashkit/tests/threat_model_tests.rs +++ b/crates/bashkit/tests/threat_model_tests.rs @@ -1430,7 +1430,7 @@ mod python_security { assert_ne!(result.exit_code, 0); } - /// TM-PY-014: Python with BashKit resource limits + /// TM-PY-014: Python with Bashkit resource limits #[tokio::test] async fn threat_python_respects_bash_limits() { let limits = ExecutionLimits::new().max_commands(5); @@ -1448,7 +1448,7 @@ mod python_security { // --- VFS Security Tests --- - /// TM-PY-015: Python VFS reads only from BashKit's virtual filesystem + /// TM-PY-015: Python VFS reads only from Bashkit's virtual filesystem #[tokio::test] async fn threat_python_vfs_no_real_fs() { let mut bash = bash_with_python(); @@ -1540,7 +1540,7 @@ mod python_security { ); } - /// TM-PY-020: Python VFS operations respect BashKit sandbox boundaries + /// TM-PY-020: Python VFS operations respect Bashkit sandbox boundaries #[tokio::test] async fn threat_python_vfs_no_network() { let mut bash = bash_with_python(); @@ -4172,7 +4172,7 @@ mod typescript_security { assert_ne!(result.exit_code, 0, "Stack overflow should not succeed"); } - /// TM-TS-005: TypeScript VFS reads only from BashKit VFS + /// TM-TS-005: TypeScript VFS reads only from Bashkit VFS #[tokio::test] async fn threat_ts_vfs_no_real_fs() { let mut bash = bash_with_ts(); diff --git a/crates/bashkit/tests/typescript_security_tests.rs b/crates/bashkit/tests/typescript_security_tests.rs index f70467559..c402dce7a 100644 --- a/crates/bashkit/tests/typescript_security_tests.rs +++ b/crates/bashkit/tests/typescript_security_tests.rs @@ -315,7 +315,7 @@ mod whitebox_vfs_security { .await .unwrap(); // Verify file doesn't exist on real host (we're in VFS) - // The bash `test -f` in BashKit also operates on VFS, so this + // The bash `test -f` in Bashkit also operates on VFS, so this // verifies the write went to VFS, not a real assertion about host fs let r = bash.exec("cat /tmp/ts_escape_test").await.unwrap(); assert_eq!(r.exit_code, 0); @@ -415,7 +415,7 @@ mod whitebox_error_handling { mod whitebox_bash_integration { use super::*; - /// TM-TS-018: TypeScript respects BashKit command limits + /// TM-TS-018: TypeScript respects Bashkit command limits #[tokio::test] async fn threat_ts_respects_bash_limits() { let limits = ExecutionLimits::new().max_commands(5); diff --git a/specs/python-builtin.md b/specs/python-builtin.md index bcd49291b..a04122510 100644 --- a/specs/python-builtin.md +++ b/specs/python-builtin.md @@ -10,7 +10,7 @@ Implemented (experimental) ## Decision -BashKit provides sandboxed Python execution via `python` and `python3` builtins, +Bashkit provides sandboxed Python execution via `python` and `python3` builtins, powered by the [Monty](https://github.com/pydantic/monty) embedded Python interpreter written in Rust. @@ -82,7 +82,7 @@ python3 -V ### Resource Limits -Monty enforces its own resource limits independent of BashKit's shell limits. +Monty enforces its own resource limits independent of Bashkit's shell limits. All limits are configurable via `PythonLimits`: | Limit | Default | Builder Method | Purpose | @@ -143,7 +143,7 @@ Monty implements a subset of Python 3.12: ### VFS Bridging -Python `pathlib.Path` operations are bridged to BashKit's virtual filesystem +Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem via Monty's OsCall pause/resume mechanism. This enables Python code to read and write files that are shared with the bash environment. @@ -181,16 +181,16 @@ python3 -c "import os; print(os.getenv('HOME'))" **Architecture:** ``` -Python code → Monty VM → OsCall(ReadText, path) → BashKit VFS → resume +Python code → Monty VM → OsCall(ReadText, path) → Bashkit VFS → resume ``` Monty pauses execution at filesystem operations, yields an `OsCall` event -with the operation type and arguments, BashKit bridges it to the VFS, and +with the operation type and arguments, Bashkit bridges it to the VFS, and resumes execution with the result (or a Python exception). > **Note:** Monty 0.0.10+ includes native filesystem mounting (`MountTable`, > `MountDir`, `MountMode`) that can handle file operations directly against -> host directories. BashKit uses the OsCall bridge instead because our VFS is +> host directories. Bashkit uses the OsCall bridge instead because our VFS is > in-memory and may not be backed by host directories. The native mount system > is suited for real-filesystem use cases where Monty is used standalone. @@ -277,11 +277,11 @@ by-design consistent with all other builtins. Use single quotes to prevent expansion: `python3 -c 'print("hello")'`. #### Threat: Resource exhaustion -Monty enforces independent resource limits. Even if BashKit's shell limits +Monty enforces independent resource limits. Even if Bashkit's shell limits are generous, Python code cannot exceed Monty's allocation/time/memory caps. #### Threat: Sandbox escape via filesystem -All `pathlib.Path` operations go through BashKit's virtual filesystem. +All `pathlib.Path` operations go through Bashkit's virtual filesystem. Python code cannot access the real host filesystem. `/etc/passwd` in Python reads from VFS (where it doesn't exist), not the host. @@ -312,13 +312,13 @@ a hint to `help()` and `system_prompt()` documenting its limitations: > python/python3: Embedded Python (Monty). Stdlib: math, pathlib, os.getenv, sys, typing. File I/O via pathlib.Path only (no open()). No HTTP/network. No classes. No third-party imports. -Regex module `re` is intentionally disabled in BashKit due to catastrophic +Regex module `re` is intentionally disabled in Bashkit due to catastrophic backtracking DoS risk in untrusted code execution. This uses the general `Builtin::llm_hint()` mechanism — any builtin can provide hints that are automatically deduplicated and included in LLM-facing documentation. -### Integration with BashKit +### Integration with Bashkit - `python`/`python3` both map to the same builtin - Works in pipelines: `echo "data" | python3 -c "import sys; ..."` diff --git a/specs/threat-model.md b/specs/threat-model.md index ba55c2d6a..5f570d40a 100644 --- a/specs/threat-model.md +++ b/specs/threat-model.md @@ -1662,19 +1662,19 @@ The following components are fuzz-tested for robustness: > undiscovered crash or security bugs. Resource limits are enforced by Monty's > runtime. This integration should be treated as experimental. -BashKit embeds the Monty Python interpreter (pydantic/monty) with VFS bridging. -Python `pathlib.Path` operations are bridged to BashKit's virtual filesystem via +Bashkit embeds the Monty Python interpreter (pydantic/monty) with VFS bridging. +Python `pathlib.Path` operations are bridged to Bashkit's virtual filesystem via Monty's OsCall pause/resume mechanism. This section covers threats specific to the Python builtin. ### Architecture ``` -Python code → Monty VM → OsCall pause → BashKit VFS bridge → resume +Python code → Monty VM → OsCall pause → Bashkit VFS bridge → resume ``` Monty never touches the real filesystem. All `Path.*` operations yield `OsCall` -events that BashKit intercepts and dispatches to the VFS. +events that Bashkit intercepts and dispatches to the VFS. ### Threats @@ -1686,8 +1686,8 @@ events that BashKit intercepts and dispatches to the VFS. | TM-PY-004 | Shell escape via os.system/subprocess | Critical | Monty has no os.system/subprocess implementation | `threat_python_no_os_operations` | | TM-PY-005 | Real filesystem access via open() | Critical | Monty has no open() builtin | `threat_python_no_filesystem` | | TM-PY-006 | Error info leakage via stdout | Medium | Errors go to stderr, not stdout | `threat_python_error_isolation` | -| TM-PY-015 | Real filesystem read via pathlib | Critical | VFS bridge reads only from BashKit VFS, not host | `threat_python_vfs_no_real_fs` | -| TM-PY-016 | Real filesystem write via pathlib | Critical | VFS bridge writes only to BashKit VFS | `threat_python_vfs_write_sandboxed` | +| TM-PY-015 | Real filesystem read via pathlib | Critical | VFS bridge reads only from Bashkit VFS, not host | `threat_python_vfs_no_real_fs` | +| TM-PY-016 | Real filesystem write via pathlib | Critical | VFS bridge writes only to Bashkit VFS | `threat_python_vfs_write_sandboxed` | | TM-PY-017 | Path traversal (../../etc/passwd) | High | VFS resolves paths within sandbox boundaries | `threat_python_vfs_path_traversal` | | TM-PY-018 | Bash/Python VFS isolation breach | Medium | Shared VFS by design; no cross-tenant access | `threat_python_vfs_bash_python_isolation` | | TM-PY-019 | Crash on missing file | Medium | FileNotFoundError raised, not panic | `threat_python_vfs_error_handling` | @@ -1737,7 +1737,7 @@ and this information has low sensitivity. No filesystem or network access is gra ### VFS Bridge Security Properties -1. **No real filesystem access**: All Path operations go through BashKit's VFS. +1. **No real filesystem access**: All Path operations go through Bashkit's VFS. `/etc/passwd` in Python reads from VFS, not the host. 2. **Shared VFS with bash**: Files written by `echo > file` are readable by Python's `Path(file).read_text()`, and vice versa. This is intentional. @@ -1746,7 +1746,7 @@ and this information has low sensitivity. No filesystem or network access is gra 4. **Error mapping**: VFS errors are mapped to standard Python exceptions (FileNotFoundError, IsADirectoryError, etc.), not raw panics. 5. **Resource isolation**: Monty's own limits (time, memory, allocations, - recursion) are enforced independently of BashKit's shell limits. + recursion) are enforced independently of Bashkit's shell limits. ### Direct Integration @@ -1791,7 +1791,7 @@ filesystem. > explicit `.typescript()` call on the builder. Without both, these commands > are unavailable. -BashKit embeds the ZapCode TypeScript interpreter (zapcode-core) with VFS +Bashkit embeds the ZapCode TypeScript interpreter (zapcode-core) with VFS bridging via external function suspend/resume. TypeScript code can access the virtual filesystem through registered external functions. This section covers threats specific to the TypeScript builtin. @@ -1799,11 +1799,11 @@ threats specific to the TypeScript builtin. ### Architecture ``` -TypeScript code → ZapCode VM → ExternalFn suspend → BashKit VFS bridge → resume +TypeScript code → ZapCode VM → ExternalFn suspend → Bashkit VFS bridge → resume ``` ZapCode never touches the real filesystem. External function calls suspend the -VM, BashKit intercepts and dispatches to the VFS, then resumes execution. +VM, Bashkit intercepts and dispatches to the VFS, then resumes execution. ### Opt-in Design @@ -1823,20 +1823,20 @@ are not available even if compiled. This matches the Python builtin pattern. | TM-TS-002 | Memory exhaustion via large allocation | High | ZapCode max_memory (64MB) + max_allocations (1M) | `threat_ts_memory_exhaustion` | | TM-TS-003 | Stack overflow via deep recursion | High | ZapCode max_stack_depth (512) | `threat_ts_stack_overflow` | | TM-TS-004 | Allocation bomb (many small objects) | High | ZapCode max_allocations (1M) | `threat_ts_allocation_bomb` | -| TM-TS-005 | Real filesystem access via VFS | Critical | VFS bridge reads only from BashKit VFS, not host | `threat_ts_vfs_no_real_fs` | -| TM-TS-006 | VFS write escapes to host | Critical | VFS bridge writes only to BashKit VFS | `threat_ts_vfs_write_sandboxed` | +| TM-TS-005 | Real filesystem access via VFS | Critical | VFS bridge reads only from Bashkit VFS, not host | `threat_ts_vfs_no_real_fs` | +| TM-TS-006 | VFS write escapes to host | Critical | VFS bridge writes only to Bashkit VFS | `threat_ts_vfs_write_sandboxed` | | TM-TS-007 | Path traversal (../../etc/passwd) | High | VFS resolves paths within sandbox boundaries | `threat_ts_vfs_path_traversal` | | TM-TS-008 | Bash/TypeScript VFS data corruption | Medium | Shared VFS by design; no cross-tenant access | `threat_ts_vfs_bash_ts_shared` | | TM-TS-009 | Crash on missing file | Medium | Error string returned, not panic | `threat_ts_vfs_error_handling` | | TM-TS-010 | VFS mkdir escape | Medium | mkdir operates only in VFS | `threat_ts_vfs_mkdir_sandboxed` | -| TM-TS-011 | VFS operations escape to host /tmp | Critical | All operations go through BashKit VFS | `threat_ts_vfs_no_host_escape` | +| TM-TS-011 | VFS operations escape to host /tmp | Critical | All operations go through Bashkit VFS | `threat_ts_vfs_no_host_escape` | | TM-TS-012 | Error info leakage via stdout | Medium | Errors go to stderr, not stdout | `threat_ts_error_isolation` | | TM-TS-013 | Syntax error crashes host | Medium | Non-zero exit code, error on stderr | `threat_ts_syntax_error_exit` | | TM-TS-014 | Exit code not propagated | Low | Exit code flows to bash $? | `threat_ts_exit_code_propagation` | | TM-TS-015 | Empty code crashes | Low | Non-zero exit, error message | `threat_ts_empty_code` | | TM-TS-016 | Pipeline error leakage | Medium | Errors on stderr, not passed to pipe | `threat_ts_pipeline_error_handling` | | TM-TS-017 | Unknown options accepted | Low | Unknown flags return non-zero | `threat_ts_unknown_options` | -| TM-TS-018 | TypeScript bypasses BashKit limits | Medium | Command budget still enforced | `threat_ts_respects_bash_limits` | +| TM-TS-018 | TypeScript bypasses Bashkit limits | Medium | Command budget still enforced | `threat_ts_respects_bash_limits` | | TM-TS-019 | Command subst captures errors | Medium | Only stdout captured by $() | `threat_ts_subst_captures_stdout` | | TM-TS-020 | Bash var expansion injection | Medium | By-design; use single quotes to prevent | `threat_ts_variable_expansion` | | TM-TS-021 | Shell command execution from TS | Critical | No process/subprocess/exec globals | `threat_ts_no_shell_exec` | @@ -1860,7 +1860,7 @@ ZapCode blocks these at the language level (not just runtime): ### VFS Bridge Security Properties -1. **No real filesystem access**: All VFS-bridged functions go through BashKit's +1. **No real filesystem access**: All VFS-bridged functions go through Bashkit's VFS. `/etc/passwd` in TypeScript reads from VFS, not the host. 2. **Shared VFS with bash**: Files written by `echo > file` are readable by TypeScript's `readFile()`, and vice versa. This is intentional. @@ -1868,7 +1868,7 @@ ZapCode blocks these at the language level (not just runtime): Path traversal (`../..`) is constrained by VFS path normalization. 4. **Error handling**: VFS errors return error strings to TypeScript, not panics. 5. **Resource isolation**: ZapCode's own limits (time, memory, stack, allocations) - are enforced independently of BashKit's shell limits. + are enforced independently of Bashkit's shell limits. ### Supported VFS Operations diff --git a/specs/zapcode-runtime.md b/specs/zapcode-runtime.md index c6ea0ee55..da8bf390e 100644 --- a/specs/zapcode-runtime.md +++ b/specs/zapcode-runtime.md @@ -9,7 +9,7 @@ Implemented (experimental) ## Decision -BashKit provides sandboxed TypeScript/JavaScript execution via `typescript`, +Bashkit provides sandboxed TypeScript/JavaScript execution via `typescript`, `ts`, `node`, `deno`, and `bun` builtins, powered by the [ZapCode](https://github.com/TheUncharted/zapcode) embedded TypeScript interpreter written in Rust. @@ -114,7 +114,7 @@ The `-c` and `-e` flags are both accepted by all aliases for convenience. ### Resource Limits -ZapCode enforces its own resource limits independent of BashKit's shell limits. +ZapCode enforces its own resource limits independent of Bashkit's shell limits. All limits are configurable via `TypeScriptLimits`: | Limit | Default | Builder Method | Purpose | @@ -162,7 +162,7 @@ ZapCode implements a TypeScript/JavaScript subset: ### VFS Bridging -TypeScript code can access BashKit's virtual filesystem through external +TypeScript code can access Bashkit's virtual filesystem through external functions registered by the builtin. These functions are available as globals in the TypeScript environment: @@ -193,10 +193,10 @@ ts -c "const entries = await readDir('/tmp'); console.log(entries)" **Architecture:** ``` -TS code → ZapCode VM → ExternalFn("readFile", [path]) → BashKit VFS → resume +TS code → ZapCode VM → ExternalFn("readFile", [path]) → Bashkit VFS → resume ``` -ZapCode suspends execution at external function calls, BashKit bridges the +ZapCode suspends execution at external function calls, Bashkit bridges the call to the VFS, and resumes execution with the result. **Limitation: stdout after VFS calls.** `ZapcodeSnapshot::resume()` returns @@ -273,12 +273,12 @@ by-design consistent with all other builtins. Use single quotes to prevent expansion: `ts -c 'console.log("hello")'`. #### Threat: Resource exhaustion -ZapCode enforces independent resource limits. Even if BashKit's shell limits +ZapCode enforces independent resource limits. Even if Bashkit's shell limits are generous, TypeScript code cannot exceed ZapCode's time/memory/stack caps. #### Threat: Sandbox escape via filesystem TypeScript code has no direct filesystem access. VFS-bridged functions go -through BashKit's virtual filesystem. `/etc/passwd` reads from VFS, not host. +through Bashkit's virtual filesystem. `/etc/passwd` reads from VFS, not host. #### Threat: Sandbox escape via eval/import ZapCode blocks `eval()`, `Function()`, `import`, and `require` at the language @@ -305,7 +305,7 @@ contributes a hint to `help()` and `system_prompt()`: > File I/O via readFile()/writeFile() async functions. No npm/import/require. > No HTTP/network. No eval(). -### Integration with BashKit +### Integration with Bashkit - `ts`/`typescript`/`node`/`deno`/`bun` all map to the same builtin - Works in pipelines: `echo "data" | ts -c "..."`