bashkit 0.3.0__tar.gz → 0.4.0__tar.gz

{bashkit-0.3.0 → bashkit-0.4.0}/Cargo.lock

@@ -345,12 +345,13 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bashkit"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "async-trait",
  "base64",
  "chrono",
+ "clap",
  "criterion",
  "ed25519-dalek 2.2.0",
  "fail",
@@ -392,7 +393,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-bench"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -406,7 +407,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-cli"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -422,7 +423,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-eval"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -439,7 +440,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-js"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "bashkit",
  "napi",
@@ -452,7 +453,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-python"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "bashkit",
  "num-bigint",
@@ -2811,8 +2812,8 @@ dependencies = [
 
 [[package]]
 name = "monty"
-version = "0.0.11"
-source = "git+https://github.com/pydantic/monty?rev=2e9df4b#2e9df4b508e8a9ac80f3a6a26ed680242d1f460d"
+version = "0.0.17"
+source = "git+https://github.com/pydantic/monty?rev=49faa4c#49faa4c8ae94490eae286e76259adcc35f64f0a5"
 dependencies = [
  "ahash",
  "bytemuck",
@@ -2827,11 +2828,12 @@ dependencies = [
  "num-integer",
  "num-traits",
  "postcard",
- "pyo3-build-config",
  "ruff_python_ast",
  "ruff_python_parser",
+ "ruff_python_stdlib",
  "ruff_text_size",
  "serde",
+ "serde_json",
  "smallvec",
  "speedate",
  "strum 0.27.2",
@@ -4246,6 +4248,15 @@ dependencies = [
  "unicode_names2",
 ]
 
+[[package]]
+name = "ruff_python_stdlib"
+version = "0.0.0"
+source = "git+https://github.com/astral-sh/ruff.git?rev=6ded4bed1651e30b34dd04cdaa50c763036abb0d#6ded4bed1651e30b34dd04cdaa50c763036abb0d"
+dependencies = [
+ "bitflags",
+ "unicode-ident",
+]
+
 [[package]]
 name = "ruff_python_trivia"
 version = "0.0.0"

{bashkit-0.3.0 → bashkit-0.4.0}/Cargo.toml

@@ -7,7 +7,7 @@ resolver = "2"
 members = ["crates/*"]
 
 [workspace.package]
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 license = "MIT"
 authors = ["Everruns"]

{bashkit-0.3.0 → bashkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bashkit
-Version: 0.3.0
+Version: 0.4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{bashkit-0.3.0 → bashkit-0.4.0}/crates/bashkit/Cargo.toml

@@ -77,8 +77,11 @@ hmac = "0.13"
 # Logging/tracing (optional)
 tracing = { workspace = true, optional = true }
 
+# CLI-style argument parsing for custom builtins.
+clap = { workspace = true, optional = true }
+
 # Embedded Python interpreter (optional)
-monty = { git = "https://github.com/pydantic/monty", rev = "2e9df4b", optional = true }
+monty = { git = "https://github.com/pydantic/monty", rev = "49faa4c", optional = true }
 
 # Embedded TypeScript interpreter (optional)
 zapcode-core = { version = "1.5", optional = true }
@@ -88,7 +91,9 @@ zapcode-core = { version = "1.5", optional = true }
 turso_core = { workspace = true, optional = true }
 
 [features]
-default = []
+default = ["clap-builtins"]
+# Enable `ClapBuiltin` for custom builtins with `#[derive(clap::Parser)]`.
+clap-builtins = ["dep:clap"]
 # Enable jq builtin via embedded jaq interpreter
 # Usage: cargo build --features jq
 jq = ["dep:jaq-core", "dep:jaq-std", "dep:jaq-json"]
@@ -153,6 +158,11 @@ serial_test = { workspace = true }
 name = "parallel_execution"
 harness = false
 
+[[bench]]
+name = "sqlite"
+harness = false
+required-features = ["sqlite"]
+
 [[example]]
 name = "agent_tool"
 required-features = ["http_client"]

bashkit-0.4.0/crates/bashkit/benches/sqlite.rs

@@ -0,0 +1,424 @@
+//! SQLite builtin benchmark for Bashkit
+//!
+//! Targets the `sqlite` builtin (Turso, in-process) along the dimensions
+//! that actually matter for users:
+//!
+//! - **Workload shapes**: bulk INSERT, batched UPDATE, indexed vs full-scan
+//!   SELECT, aggregate (GROUP BY + COUNT/SUM/AVG).
+//! - **Output modes**: list (default), CSV, JSON, markdown — exercise the
+//!   formatter on the same row set.
+//! - **Backends**: `Memory` (load whole DB into turso's `MemoryIO`) vs `Vfs`
+//!   (custom IO trait talking to bashkit's FileSystem).
+//! - **Persistence cost**: opening a fresh DB per invocation (load + flush)
+//!   vs `:memory:` (zero VFS round-trip).
+//! - **Concurrency**: N parallel sqlite sessions over a shared VFS, each
+//!   with its own DB file — measures the cooperative-IO path under load.
+//!
+//! Each bench prints a single-row sentinel so successful execution can be
+//! eyeballed in `cargo bench` output without parsing Criterion JSON.
+
+use bashkit::{Bash, FileSystem, InMemoryFs, SqliteBackend, SqliteLimits};
+use criterion::{BenchmarkId, Criterion, Throughput, criterion_group, criterion_main};
+use std::sync::Arc;
+use tokio::runtime::Runtime;
+
+/// Row counts to exercise scaling. Kept modest so a full `cargo bench` run
+/// finishes in reasonable time on CI hardware; tune up locally if you need
+/// more signal.
+const ROW_COUNTS: &[usize] = &[100, 1_000, 10_000];
+
+/// Concurrency levels for the parallel-sessions group.
+const SESSION_COUNTS: &[usize] = &[4, 16, 64];
+
+/// Build a Bash with sqlite enabled and the opt-in env set. Optionally
+/// share a filesystem so multiple sessions hit the same VFS.
+fn make_bash(backend: SqliteBackend, fs: Option<Arc<dyn FileSystem>>) -> Bash {
+    let mut builder = Bash::builder()
+        .sqlite_with_limits(
+            SqliteLimits::default()
+                .backend(backend)
+                // Lift caps so large-N benches don't trip the defaults.
+                .max_rows_per_query(1_000_000)
+                .max_statements(1_000_000)
+                .max_script_bytes(64 * 1024 * 1024),
+        )
+        .env("BASHKIT_ALLOW_INPROCESS_SQLITE", "1");
+    if let Some(fs) = fs {
+        builder = builder.fs(fs);
+    }
+    builder.build()
+}
+
+/// SQL that seeds a `kv(id, k, v)` table with `n` rows using a recursive CTE.
+/// Faster than emitting `n` literal `INSERT` statements through the parser.
+fn seed_kv_sql(n: usize) -> String {
+    format!(
+        r#"
+CREATE TABLE IF NOT EXISTS kv(id INTEGER PRIMARY KEY, k TEXT, v INTEGER);
+WITH RECURSIVE seq(i) AS (
+    SELECT 1 UNION ALL SELECT i+1 FROM seq WHERE i < {n}
+)
+INSERT INTO kv(k, v) SELECT 'key' || i, i*7 % 113 FROM seq;
+"#
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Workload helpers (each takes a fresh Bash, runs the workload, returns).
+// ---------------------------------------------------------------------------
+
+async fn bench_insert(backend: SqliteBackend, n: usize) {
+    let mut bash = make_bash(backend, None);
+    let script = format!(
+        "sqlite /tmp/bench.sqlite \"{}; SELECT count(*) FROM kv\"",
+        seed_kv_sql(n).replace('"', "\\\"")
+    );
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_update(backend: SqliteBackend, n: usize) {
+    let mut bash = make_bash(backend, None);
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    let script = format!(
+        "sqlite /tmp/bench.sqlite \"{setup}; UPDATE kv SET v = v + 1 WHERE k LIKE 'key1%'; SELECT changes()\""
+    );
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_index_create_and_query(backend: SqliteBackend, n: usize) {
+    let mut bash = make_bash(backend, None);
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    // Without index → with index → repeat the same point-query, measuring
+    // the combined "schema change + indexed lookup" path. The point-query
+    // alone is benched in `bench_query_indexed` below.
+    let script = format!(
+        "sqlite /tmp/bench.sqlite \"{setup}; CREATE INDEX IF NOT EXISTS idx_kv_k ON kv(k); SELECT v FROM kv WHERE k = 'key42'\""
+    );
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_query_indexed(backend: SqliteBackend, n: usize) {
+    let mut bash = make_bash(backend, None);
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    let script = format!(
+        "sqlite /tmp/bench.sqlite \"{setup}; CREATE INDEX idx_kv_k ON kv(k); SELECT count(*) FROM kv WHERE k IN ('key1','key100','key1000','key9999')\""
+    );
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_query_full_scan(backend: SqliteBackend, n: usize) {
+    let mut bash = make_bash(backend, None);
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    // No index → forces a full scan with a LIKE predicate that the planner
+    // cannot satisfy from sqlite_master.
+    let script = format!(
+        "sqlite /tmp/bench.sqlite \"{setup}; SELECT count(*) FROM kv WHERE k LIKE '%99%'\""
+    );
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_aggregate(backend: SqliteBackend, n: usize) {
+    let mut bash = make_bash(backend, None);
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    let script = format!(
+        "sqlite /tmp/bench.sqlite \"{setup}; SELECT v % 10 AS bucket, count(*), sum(v), avg(v) FROM kv GROUP BY bucket ORDER BY bucket\""
+    );
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_output_mode(backend: SqliteBackend, n: usize, mode_flag: &str) {
+    let mut bash = make_bash(backend, None);
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    // Materialise the full row set through the formatter — this is what
+    // changes between modes; the underlying scan is identical.
+    let script = format!(
+        "sqlite {mode_flag} -header /tmp/bench.sqlite \"{setup}; SELECT id, k, v FROM kv ORDER BY id\""
+    );
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_persistence_per_invocation(backend: SqliteBackend, n: usize) {
+    // Two invocations: write, then read — measures load+flush per call.
+    let fs: Arc<dyn FileSystem> = Arc::new(InMemoryFs::new());
+    let mut bash = make_bash(backend, Some(Arc::clone(&fs)));
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    let _ = bash
+        .exec(&format!("sqlite /tmp/persist.sqlite \"{setup}\""))
+        .await;
+    let _ = bash
+        .exec("sqlite /tmp/persist.sqlite 'SELECT count(*) FROM kv'")
+        .await;
+}
+
+async fn bench_in_memory_only(n: usize) {
+    let mut bash = make_bash(SqliteBackend::Memory, None);
+    let setup = seed_kv_sql(n).replace('"', "\\\"");
+    // `:memory:` skips the VFS entirely; isolates pure engine cost.
+    let script = format!("sqlite :memory: \"{setup}; SELECT count(*) FROM kv\"");
+    let _ = bash.exec(&script).await;
+}
+
+async fn bench_parallel_sessions(sessions: usize, rows: usize, backend: SqliteBackend) {
+    // Shared VFS, distinct DB file per session — tests the cooperative-IO
+    // path without contending on a single sqlite file (which the builtin
+    // doesn't try to coordinate; see `specs/sqlite-builtin.md`).
+    let fs: Arc<dyn FileSystem> = Arc::new(InMemoryFs::new());
+    let handles: Vec<_> = (0..sessions)
+        .map(|i| {
+            let fs = Arc::clone(&fs);
+            tokio::spawn(async move {
+                let mut bash = make_bash(backend, Some(fs));
+                let setup = seed_kv_sql(rows).replace('"', "\\\"");
+                let script = format!(
+                    "sqlite /tmp/sess_{i}.sqlite \"{setup}; SELECT count(*), sum(v) FROM kv\""
+                );
+                let _ = bash.exec(&script).await;
+            })
+        })
+        .collect();
+    for h in handles {
+        let _ = h.await;
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Criterion groups
+// ---------------------------------------------------------------------------
+
+fn bench_crud(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let mut group = c.benchmark_group("sqlite_crud");
+    group.sample_size(20);
+
+    for &n in ROW_COUNTS {
+        group.throughput(Throughput::Elements(n as u64));
+
+        group.bench_with_input(BenchmarkId::new("insert_mem", n), &n, |b, &n| {
+            b.to_async(&rt)
+                .iter(|| bench_insert(SqliteBackend::Memory, n));
+        });
+        group.bench_with_input(BenchmarkId::new("insert_vfs", n), &n, |b, &n| {
+            b.to_async(&rt).iter(|| bench_insert(SqliteBackend::Vfs, n));
+        });
+
+        group.bench_with_input(BenchmarkId::new("update_mem", n), &n, |b, &n| {
+            b.to_async(&rt)
+                .iter(|| bench_update(SqliteBackend::Memory, n));
+        });
+        group.bench_with_input(BenchmarkId::new("update_vfs", n), &n, |b, &n| {
+            b.to_async(&rt).iter(|| bench_update(SqliteBackend::Vfs, n));
+        });
+    }
+
+    group.finish();
+}
+
+fn bench_indexing(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let mut group = c.benchmark_group("sqlite_index");
+    group.sample_size(20);
+
+    for &n in ROW_COUNTS {
+        group.throughput(Throughput::Elements(n as u64));
+
+        group.bench_with_input(BenchmarkId::new("create_index_mem", n), &n, |b, &n| {
+            b.to_async(&rt)
+                .iter(|| bench_index_create_and_query(SqliteBackend::Memory, n));
+        });
+        group.bench_with_input(BenchmarkId::new("indexed_lookup_mem", n), &n, |b, &n| {
+            b.to_async(&rt)
+                .iter(|| bench_query_indexed(SqliteBackend::Memory, n));
+        });
+        group.bench_with_input(BenchmarkId::new("full_scan_mem", n), &n, |b, &n| {
+            b.to_async(&rt)
+                .iter(|| bench_query_full_scan(SqliteBackend::Memory, n));
+        });
+    }
+
+    group.finish();
+}
+
+fn bench_queries(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let mut group = c.benchmark_group("sqlite_query");
+    group.sample_size(20);
+
+    for &n in ROW_COUNTS {
+        group.throughput(Throughput::Elements(n as u64));
+
+        group.bench_with_input(BenchmarkId::new("aggregate_mem", n), &n, |b, &n| {
+            b.to_async(&rt)
+                .iter(|| bench_aggregate(SqliteBackend::Memory, n));
+        });
+        group.bench_with_input(BenchmarkId::new("aggregate_vfs", n), &n, |b, &n| {
+            b.to_async(&rt)
+                .iter(|| bench_aggregate(SqliteBackend::Vfs, n));
+        });
+        group.bench_with_input(BenchmarkId::new("aggregate_in_memory", n), &n, |b, &n| {
+            b.to_async(&rt).iter(|| bench_in_memory_only(n));
+        });
+    }
+
+    group.finish();
+}
+
+fn bench_output_modes(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let mut group = c.benchmark_group("sqlite_output_mode");
+    group.sample_size(20);
+
+    let n = 1_000;
+    group.throughput(Throughput::Elements(n as u64));
+    for (label, flag) in [
+        ("list", ""),
+        ("csv", "-csv"),
+        ("json", "-json"),
+        ("markdown", "-markdown"),
+        ("box", "-box"),
+    ] {
+        group.bench_function(label, |b| {
+            b.to_async(&rt)
+                .iter(|| bench_output_mode(SqliteBackend::Memory, n, flag));
+        });
+    }
+
+    group.finish();
+}
+
+fn bench_persistence(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let mut group = c.benchmark_group("sqlite_persistence");
+    group.sample_size(20);
+
+    let n = 1_000;
+    group.throughput(Throughput::Elements(n as u64));
+    group.bench_function("two_invocations_mem", |b| {
+        b.to_async(&rt)
+            .iter(|| bench_persistence_per_invocation(SqliteBackend::Memory, n));
+    });
+    group.bench_function("two_invocations_vfs", |b| {
+        b.to_async(&rt)
+            .iter(|| bench_persistence_per_invocation(SqliteBackend::Vfs, n));
+    });
+    group.bench_function("memory_db_baseline", |b| {
+        b.to_async(&rt).iter(|| bench_in_memory_only(n));
+    });
+
+    group.finish();
+}
+
+fn bench_parallel(c: &mut Criterion) {
+    let rt = Runtime::new().unwrap();
+    let mut group = c.benchmark_group("sqlite_parallel");
+    group.sample_size(15);
+
+    let rows = 500;
+    for &sessions in SESSION_COUNTS {
+        group.throughput(Throughput::Elements((sessions * rows) as u64));
+        group.bench_with_input(BenchmarkId::new("mem", sessions), &sessions, |b, &s| {
+            b.to_async(&rt)
+                .iter(|| bench_parallel_sessions(s, rows, SqliteBackend::Memory));
+        });
+        group.bench_with_input(BenchmarkId::new("vfs", sessions), &sessions, |b, &s| {
+            b.to_async(&rt)
+                .iter(|| bench_parallel_sessions(s, rows, SqliteBackend::Vfs));
+        });
+    }
+
+    group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Smoke-test harness — runs as part of `cargo test --features sqlite` so a
+// regression in the benched code path breaks the build, not just a silent
+// 0ns measurement.
+// ---------------------------------------------------------------------------
+
+#[test]
+fn verify_insert_and_count() {
+    let rt = Runtime::new().unwrap();
+    rt.block_on(async {
+        let mut bash = make_bash(SqliteBackend::Memory, None);
+        let setup = seed_kv_sql(50).replace('"', "\\\"");
+        let r = bash
+            .exec(&format!(
+                "sqlite /tmp/v.sqlite \"{setup}; SELECT count(*) FROM kv\""
+            ))
+            .await
+            .unwrap();
+        assert_eq!(r.exit_code, 0, "stderr={}", r.stderr);
+        assert_eq!(r.stdout.trim(), "50");
+    });
+}
+
+#[test]
+fn verify_aggregate_groups() {
+    let rt = Runtime::new().unwrap();
+    rt.block_on(async {
+        let mut bash = make_bash(SqliteBackend::Memory, None);
+        let setup = seed_kv_sql(100).replace('"', "\\\"");
+        let r = bash
+            .exec(&format!(
+                "sqlite -header /tmp/v.sqlite \"{setup}; SELECT count(DISTINCT v % 10) FROM kv\""
+            ))
+            .await
+            .unwrap();
+        assert_eq!(r.exit_code, 0, "stderr={}", r.stderr);
+        // 10 buckets max — the exact count depends on the v distribution.
+        let count: i64 = r.stdout.lines().last().unwrap().trim().parse().unwrap();
+        assert!(
+            (1..=10).contains(&count),
+            "unexpected bucket count: {count}"
+        );
+    });
+}
+
+#[test]
+fn verify_index_lookup_matches_scan() {
+    let rt = Runtime::new().unwrap();
+    rt.block_on(async {
+        let mut bash = make_bash(SqliteBackend::Memory, None);
+        let setup = seed_kv_sql(200).replace('"', "\\\"");
+        let r = bash
+            .exec(&format!(
+                "sqlite /tmp/v.sqlite \"{setup}; CREATE INDEX i ON kv(k); SELECT v FROM kv WHERE k='key42'\""
+            ))
+            .await
+            .unwrap();
+        assert_eq!(r.exit_code, 0, "stderr={}", r.stderr);
+        // 42 * 7 % 113 = 294 % 113 = 68.
+        assert_eq!(r.stdout.trim(), "68");
+    });
+}
+
+#[test]
+fn verify_persistence_across_invocations() {
+    let rt = Runtime::new().unwrap();
+    rt.block_on(async {
+        let fs: Arc<dyn FileSystem> = Arc::new(InMemoryFs::new());
+        let mut bash = make_bash(SqliteBackend::Memory, Some(Arc::clone(&fs)));
+        let setup = seed_kv_sql(25).replace('"', "\\\"");
+        let r1 = bash
+            .exec(&format!("sqlite /tmp/persist.sqlite \"{setup}\""))
+            .await
+            .unwrap();
+        assert_eq!(r1.exit_code, 0, "stderr={}", r1.stderr);
+        let r2 = bash
+            .exec("sqlite /tmp/persist.sqlite 'SELECT count(*) FROM kv'")
+            .await
+            .unwrap();
+        assert_eq!(r2.exit_code, 0, "stderr={}", r2.stderr);
+        assert_eq!(r2.stdout.trim(), "25");
+    });
+}
+
+criterion_group!(
+    benches,
+    bench_crud,
+    bench_indexing,
+    bench_queries,
+    bench_output_modes,
+    bench_persistence,
+    bench_parallel,
+);
+criterion_main!(benches);

{bashkit-0.3.0 → bashkit-0.4.0}/crates/bashkit/docs/custom_builtins.md

@@ -7,6 +7,7 @@ virtual filesystem.
 
 **See also:**
 - [API Documentation](https://docs.rs/bashkit) - Full API reference
+- [Clap Builtins](../../../docs/clap-builtins.md) - Derive parser structs for custom builtin args
 - [Hooks](./hooks.md) - Interceptor hooks for the execution pipeline
 - [Compatibility Reference](./compatibility.md) - Supported bash features
 - [Threat Model](./threat-model.md) - Security considerations
@@ -113,6 +114,39 @@ let result = bash
 assert_eq!(result.stdout, "req-123\n");
 ```
 
+## Extensions
+
+Use an `Extension` when one capability contributes multiple builtins.
+
+```rust,ignore
+use bashkit::{Bash, Builtin, BuiltinContext, ExecResult, Extension, async_trait};
+
+struct Hello;
+
+#[async_trait]
+impl Builtin for Hello {
+    async fn execute(&self, _ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
+        Ok(ExecResult::ok("hello\n".to_string()))
+    }
+}
+
+struct MyExtension;
+
+impl Extension for MyExtension {
+    fn builtins(&self) -> Vec<(String, Box<dyn Builtin>)> {
+        vec![("hello".to_string(), Box::new(Hello))]
+    }
+}
+
+let mut bash = Bash::builder().extension(MyExtension).build();
+let result = bash.exec("hello").await?;
+assert_eq!(result.stdout, "hello\n");
+```
+
+The same extension can be added to `BashTool::builder().extension(...)`.
+`TypeScriptExtension` uses this model to register the embedded
+TypeScript/JavaScript builtins.
+
 ### Arguments
 
 Arguments are passed as a slice of strings, excluding the command name itself:
@@ -122,6 +156,11 @@ Arguments are passed as a slice of strings, excluding the command name itself:
 let first_arg = ctx.args.first().map(|s| s.as_str()).unwrap_or("default");
 ```
 
+For custom builtins with richer flags, options, or subcommands, enable the
+default `clap-builtins` feature and implement `ClapBuiltin` with a
+`#[derive(clap::Parser)]` argument type. See the `clap_builtins_guide` rustdoc
+module for tested examples.
+
 ### Environment Variables
 
 Read-only access to environment variables set via `BashBuilder::env()` or `export`:

{bashkit-0.3.0 → bashkit-0.4.0}/crates/bashkit/docs/threat-model.md

@@ -580,6 +580,43 @@ Monty runs directly in the host process. Resource limits (memory, allocations,
 time, recursion) are enforced by Monty's own runtime. All VFS operations are
 bridged through the host process — Python code never touches the real filesystem.
 
+### SQLite Security (TM-SQL-*)
+
+The `sqlite`/`sqlite3` builtins embed Turso's pure-Rust SQLite-compatible engine.
+This is experimental and **opt-in for now**. Library callers must enable the
+`sqlite` feature, register the builtin with `.sqlite()` or `.sqlite_with_limits(...)`,
+and set `BASHKIT_ALLOW_INPROCESS_SQLITE=1` before SQL executes. Without the
+runtime opt-in, registered commands fail closed with a disabled error.
+
+SQLite database files live in Bashkit's virtual filesystem, or in `:memory:`.
+The default backend loads and flushes database bytes through the VFS at command
+boundaries; the VFS backend implements Turso's IO trait over `Arc<dyn FileSystem>`.
+Both paths are tested so SQL cannot intentionally read host files.
+
+| Threat | Attack Example | Mitigation | Status |
+|--------|---------------|------------|--------|
+| BETA engine execution (TM-SQL-001) | `sqlite :memory: 'SELECT 1'` without opt-in | Feature + builder registration + runtime opt-in gate | MITIGATED |
+| Host FS escape (TM-SQL-002) | Open `/etc/passwd` as a database | All paths resolve through Bashkit VFS | MITIGATED |
+| Large SQL input (TM-SQL-003) | Multi-MB SQL script | `max_script_bytes` | MITIGATED |
+| Huge result set (TM-SQL-004) | Query returns millions of rows | `max_rows_per_query` | MITIGATED |
+| Huge DB file (TM-SQL-005) | Load or grow oversized `.sqlite` file | `max_db_bytes` on both backends | MITIGATED |
+| Wall-clock burn (TM-SQL-005a) | Expensive query/CTE | Per-step deadline + interrupt | MITIGATED |
+| Statement flood (TM-SQL-005b) | Millions of `;` statements | `max_statements` | MITIGATED |
+| Binary truncation (TM-SQL-006) | BLOB contains NUL bytes | `Vec<u8>` values, tested round-trip | MITIGATED |
+| CSV injection/escape failure (TM-SQL-007) | Blob/text contains separator | RFC-4180 quoting | MITIGATED |
+| Recursive `.read` (TM-SQL-008) | Script `.read`s itself | `MAX_DOT_READ_DEPTH` | MITIGATED |
+| Cross-database access (TM-SQL-009) | `ATTACH DATABASE '/tmp/x'` | `ATTACH`/`DETACH` rejected by policy | MITIGATED |
+| Dangerous PRAGMAs (TM-SQL-010) | `PRAGMA main."cache_size"=...` | Default `pragma_deny` list, including quoted/schema-qualified names | MITIGATED |
+| Host path errors (TM-SQL-011) | Upstream error includes `/rustc/...` | Sanitizer strips host path annotations | MITIGATED |
+
+Black-box coverage drives `Bash::exec` through
+`tests/sqlite_integration_tests.rs` and `tests/sqlite_security_tests.rs`.
+White-box coverage in `builtins/sqlite/tests.rs` exercises parser, policy,
+formatter, sanitizer, backend, and dot-command internals directly.
+Exploratory probing found and fixed two policy/limit gaps: quoted
+schema-qualified PRAGMAs bypassed the deny list, and VFS-backed databases did
+not honor custom `max_db_bytes` while growing.
+
 ### Git Security (TM-GIT-*)
 
 Optional virtual git operations via the `git` feature. All operations are confined
@@ -744,6 +781,7 @@ All threats use stable IDs in the format `TM-<CATEGORY>-<NUMBER>`:
 | TM-LOG | Logging Security |
 | TM-GIT | Git Security |
 | TM-PY | Python/Monty Security |
+| TM-SQL | SQLite Security |
 | TM-UNI | Unicode Security |
 
 Full threat analysis: [`specs/threat-model.md`][spec]