bashkit 0.1.12__tar.gz → 0.1.13__tar.gz

{bashkit-0.1.12 → bashkit-0.1.13}/Cargo.lock

@@ -218,7 +218,7 @@ checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
 [[package]]
 name = "bashkit"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -256,7 +256,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-bench"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -272,7 +272,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-cli"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "anyhow",
  "bashkit",
@@ -285,7 +285,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-eval"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -301,7 +301,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-js"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "bashkit",
  "napi",
@@ -314,7 +314,7 @@ dependencies = [
 
 [[package]]
 name = "bashkit-python"
-version = "0.1.12"
+version = "0.1.13"
 dependencies = [
  "bashkit",
  "num-bigint",
@@ -1447,9 +1447,9 @@ checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
 [[package]]
 name = "iri-string"
-version = "0.7.10"
+version = "0.7.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c91338f0783edbd6195decb37bae672fd3b165faffb89bf7b9e6942f8b1a731a"
+checksum = "d8e7418f59cc01c88316161279a7f665217ae316b388e58a0d10e29f54f1e5eb"
 dependencies = [
  "memchr",
  "serde",
@@ -1547,7 +1547,7 @@ dependencies = [
  "cesu8",
  "cfg-if",
  "combine",
- "jni-sys",
+ "jni-sys 0.3.1",
  "log",
  "thiserror 1.0.69",
  "walkdir",
@@ -1556,9 +1556,31 @@ dependencies = [
 
 [[package]]
 name = "jni-sys"
-version = "0.3.0"
+version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8eaf4bc02d17cbdd7ff4c7438cafcdf7fb9a4613313ad11b4f8fefe7d3fa0130"
+checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258"
+dependencies = [
+ "jni-sys 0.4.1",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2"
+dependencies = [
+ "jni-sys-macros",
+]
+
+[[package]]
+name = "jni-sys-macros"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"
+dependencies = [
+ "quote",
+ "syn",
+]
 
 [[package]]
 name = "jobserver"

{bashkit-0.1.12 → bashkit-0.1.13}/Cargo.toml

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

{bashkit-0.1.12 → bashkit-0.1.13}/PKG-INFO

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

{bashkit-0.1.12 → bashkit-0.1.13}/bashkit/__init__.py

@@ -26,17 +26,21 @@ Framework integrations:
 
 from bashkit._bashkit import (
     Bash,
+    BashError,
     BashTool,
     ExecResult,
     ScriptedTool,
     create_langchain_tool_spec,
+    get_version,
 )
 
 __version__ = "0.1.2"
 __all__ = [
     "Bash",
+    "BashError",
     "BashTool",
     "ExecResult",
     "ScriptedTool",
     "create_langchain_tool_spec",
+    "get_version",
 ]

{bashkit-0.1.12 → bashkit-0.1.13}/bashkit/_bashkit.pyi

@@ -47,6 +47,8 @@ class Bash:
     ) -> None: ...
     async def execute(self, commands: str) -> ExecResult: ...
     def execute_sync(self, commands: str) -> ExecResult: ...
+    async def execute_or_throw(self, commands: str) -> ExecResult: ...
+    def execute_sync_or_throw(self, commands: str) -> ExecResult: ...
     def cancel(self) -> None: ...
     def reset(self) -> None: ...
 
@@ -88,6 +90,8 @@ class BashTool:
     ) -> None: ...
     async def execute(self, commands: str) -> ExecResult: ...
     def execute_sync(self, commands: str) -> ExecResult: ...
+    async def execute_or_throw(self, commands: str) -> ExecResult: ...
+    def execute_sync_or_throw(self, commands: str) -> ExecResult: ...
     def cancel(self) -> None: ...
     def description(self) -> str: ...
     def help(self) -> str: ...
@@ -140,6 +144,13 @@ class ScriptedTool:
     def input_schema(self) -> str: ...
     def output_schema(self) -> str: ...
 
+class BashError(Exception):
+    """Exception raised when a bash command exits with non-zero status."""
+
+    exit_code: int
+    stderr: str
+    stdout: str
+
 def create_langchain_tool_spec() -> dict[str, Any]:
     """Create a LangChain-compatible tool specification.
 
@@ -147,3 +158,7 @@ def create_langchain_tool_spec() -> dict[str, Any]:
         Dict with name, description, and args_schema
     """
     ...
+
+def get_version() -> str:
+    """Get the bashkit version string."""
+    ...

bashkit-0.1.13/crates/bashkit/docs/live_mounts.md

@@ -0,0 +1,193 @@
+# Live Mount/Unmount Guide
+
+Bashkit supports attaching and detaching filesystems on a **running** interpreter
+without rebuilding it. Shell state — environment variables, working directory,
+history, aliases — is fully preserved across mount operations.
+
+## Motivation
+
+Before live mounts, the only way to add a filesystem after `build()` was to
+accumulate mount configs and call `reset()`, which rebuilds the entire
+interpreter and loses all in-flight state. Live mounts solve this by exposing
+the internal [`MountableFs`] layer that wraps every `Bash` instance.
+
+Common use cases:
+
+- **Agent workflows**: attach a host directory mid-session when a tool needs it
+- **Plugin systems**: mount/unmount plugin filesystems without restarting
+- **Hot-swap deployments**: replace a mounted app filesystem with a new version
+- **Testing**: inject mock data at specific paths during a test
+
+## Quick Start
+
+```rust
+use bashkit::{Bash, FileSystem, InMemoryFs};
+use std::path::Path;
+use std::sync::Arc;
+
+# #[tokio::main]
+# async fn main() -> bashkit::Result<()> {
+let mut bash = Bash::new();
+
+// Create and populate a filesystem
+let data_fs = Arc::new(InMemoryFs::new());
+data_fs.write_file(Path::new("/users.json"), br#"["alice"]"#).await?;
+
+// Mount it live — no rebuild needed
+bash.mount("/mnt/data", data_fs)?;
+
+let result = bash.exec("cat /mnt/data/users.json").await?;
+assert!(result.stdout.contains("alice"));
+
+// Unmount when done
+bash.unmount("/mnt/data")?;
+# Ok(())
+# }
+```
+
+## API
+
+### `Bash::mount(vfs_path, fs)`
+
+Mounts `fs` at `vfs_path`. The mount takes effect immediately — subsequent
+`exec()` calls see files from the mounted filesystem. If a mount already exists
+at `vfs_path`, it is replaced (hot-swap).
+
+```rust
+# use bashkit::{Bash, FileSystem, InMemoryFs};
+# use std::sync::Arc;
+# use std::path::Path;
+# #[tokio::main]
+# async fn main() -> bashkit::Result<()> {
+let bash = Bash::new();
+let fs = Arc::new(InMemoryFs::new());
+bash.mount("/mnt/data", fs)?;
+# Ok(())
+# }
+```
+
+**Errors:** Returns `Err` if `vfs_path` is not absolute (after normalization).
+
+### `Bash::unmount(vfs_path)`
+
+Removes the mount at `vfs_path`. Paths that previously resolved to the mounted
+filesystem fall back to the root filesystem or the next shorter mount prefix.
+
+```rust
+# use bashkit::{Bash, FileSystem, InMemoryFs};
+# use std::sync::Arc;
+# #[tokio::main]
+# async fn main() -> bashkit::Result<()> {
+# let bash = Bash::new();
+# let fs = Arc::new(InMemoryFs::new());
+# bash.mount("/mnt/data", fs)?;
+bash.unmount("/mnt/data")?;
+# Ok(())
+# }
+```
+
+**Errors:** Returns `Err` if nothing is mounted at `vfs_path`.
+
+## How It Works
+
+Every `Bash` instance wraps its filesystem stack in a [`MountableFs`] as the
+outermost layer. This layer uses longest-prefix matching to route path
+operations to the correct mounted filesystem:
+
+```text
+┌──────────────────────────────┐
+│  MountableFs (live mounts)   │  ← Bash::mount() / unmount()
+├──────────────────────────────┤
+│  OverlayFs (text mounts)     │  ← BashBuilder::mount_text()
+├──────────────────────────────┤
+│  MountableFs (real mounts)   │  ← BashBuilder::mount_real_*_at()
+├──────────────────────────────┤
+│  Base filesystem             │  ← InMemoryFs or custom
+└──────────────────────────────┘
+```
+
+Because the interpreter holds an `Arc<dyn FileSystem>` pointing to the
+outermost `MountableFs`, any mount/unmount operation is visible to the
+interpreter immediately — no rebuild or state transfer required.
+
+## Builder Mounts vs Live Mounts
+
+| | Builder mounts | Live mounts |
+|---|---|---|
+| **When** | Before `build()` | After `build()` |
+| **Method** | `BashBuilder::mount_text()`, `mount_real_*()` | `Bash::mount()` |
+| **State** | N/A (no interpreter yet) | Fully preserved |
+| **Use case** | Initial configuration | Dynamic attachment |
+
+Both approaches can be combined: configure initial mounts with the builder, then
+add/remove mounts at runtime.
+
+## Examples
+
+### Multiple Mounts
+
+```rust
+use bashkit::{Bash, FileSystem, InMemoryFs};
+use std::path::Path;
+use std::sync::Arc;
+
+# #[tokio::main]
+# async fn main() -> bashkit::Result<()> {
+let mut bash = Bash::new();
+
+let logs = Arc::new(InMemoryFs::new());
+logs.write_file(Path::new("/app.log"), b"started\n").await?;
+
+let config = Arc::new(InMemoryFs::new());
+config.write_file(Path::new("/app.toml"), b"port = 8080\n").await?;
+
+bash.mount("/var/log", logs)?;
+bash.mount("/etc/app", config)?;
+
+let result = bash.exec("cat /var/log/app.log").await?;
+assert_eq!(result.stdout, "started\n");
+
+let result = bash.exec("cat /etc/app/app.toml").await?;
+assert_eq!(result.stdout, "port = 8080\n");
+# Ok(())
+# }
+```
+
+### Hot-Swap
+
+Re-mounting at the same path replaces the filesystem atomically:
+
+```rust
+use bashkit::{Bash, FileSystem, InMemoryFs};
+use std::path::Path;
+use std::sync::Arc;
+
+# #[tokio::main]
+# async fn main() -> bashkit::Result<()> {
+let mut bash = Bash::new();
+
+let v1 = Arc::new(InMemoryFs::new());
+v1.write_file(Path::new("/version"), b"1.0").await?;
+bash.mount("/app", v1)?;
+
+let result = bash.exec("cat /app/version").await?;
+assert_eq!(result.stdout, "1.0");
+
+// Hot-swap to v2
+let v2 = Arc::new(InMemoryFs::new());
+v2.write_file(Path::new("/version"), b"2.0").await?;
+bash.mount("/app", v2)?;
+
+let result = bash.exec("cat /app/version").await?;
+assert_eq!(result.stdout, "2.0");
+# Ok(())
+# }
+```
+
+## See Also
+
+- [`MountableFs`] — the underlying mount infrastructure
+- [`BashBuilder::mount_text`] — pre-build text file mounts
+- [`BashBuilder::fs`] — custom filesystem injection
+- [`Bash::fs`] — direct filesystem access
+- [VFS specification](https://github.com/everruns/bashkit/blob/main/specs/003-vfs.md)

bashkit-0.1.13/crates/bashkit/examples/live_mounts.rs

@@ -0,0 +1,138 @@
+//! Live mount/unmount example
+//!
+//! Demonstrates attaching and detaching filesystems on a running Bash
+//! instance without rebuilding the interpreter or losing shell state.
+//!
+//! Run with: cargo run --example live_mounts
+
+use bashkit::{Bash, FileSystem, InMemoryFs};
+use std::path::Path;
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    println!("=== Live Mount/Unmount Example ===\n");
+
+    basic_live_mount().await?;
+    println!();
+    state_preservation().await?;
+    println!();
+    hot_swap_mount().await?;
+
+    Ok(())
+}
+
+/// Mount a filesystem on a running interpreter.
+async fn basic_live_mount() -> anyhow::Result<()> {
+    println!("--- Basic Live Mount ---");
+
+    let mut bash = Bash::new();
+
+    // Create a data filesystem and populate it
+    let data_fs = Arc::new(InMemoryFs::new());
+    data_fs
+        .write_file(
+            Path::new("/users.json"),
+            br#"[{"name": "alice"}, {"name": "bob"}]"#,
+        )
+        .await?;
+    data_fs
+        .write_file(Path::new("/readme.txt"), b"Welcome to the data store")
+        .await?;
+
+    // Mount it live — no builder, no rebuild
+    bash.mount("/mnt/data", data_fs)?;
+
+    let result = bash.exec("cat /mnt/data/readme.txt").await?;
+    println!("Data store: {}", result.stdout);
+
+    let result = bash.exec("ls /mnt/data").await?;
+    println!("Files: {}", result.stdout);
+
+    // Unmount when done
+    bash.unmount("/mnt/data")?;
+    println!("Unmounted /mnt/data");
+
+    let result = bash.exec("ls /mnt/data 2>&1; echo \"exit=$?\"").await?;
+    println!("After unmount: {}", result.stdout.trim());
+
+    Ok(())
+}
+
+/// Shell state (env vars, cwd) is preserved across mount operations.
+async fn state_preservation() -> anyhow::Result<()> {
+    println!("--- State Preservation ---");
+
+    let mut bash = Bash::builder().env("APP_ENV", "production").build();
+
+    // Set up shell state
+    bash.exec("export SESSION_ID=abc123").await?;
+    bash.exec("cd /tmp").await?;
+    bash.exec("counter=0").await?;
+
+    println!("Before mount:");
+    let result = bash
+        .exec("echo env=$APP_ENV session=$SESSION_ID cwd=$(pwd)")
+        .await?;
+    print!("  {}", result.stdout);
+
+    // Mount a plugin filesystem
+    let plugin_fs = Arc::new(InMemoryFs::new());
+    plugin_fs
+        .write_file(Path::new("/init.sh"), b"echo 'Plugin loaded'")
+        .await?;
+    bash.mount("/plugins/auth", plugin_fs)?;
+
+    println!("After mount:");
+    let result = bash
+        .exec("echo env=$APP_ENV session=$SESSION_ID cwd=$(pwd)")
+        .await?;
+    print!("  {}", result.stdout);
+
+    // Use the mount
+    let result = bash.exec("source /plugins/auth/init.sh").await?;
+    println!("  Plugin: {}", result.stdout.trim());
+
+    // Unmount — state still preserved
+    bash.unmount("/plugins/auth")?;
+
+    println!("After unmount:");
+    let result = bash
+        .exec("echo env=$APP_ENV session=$SESSION_ID cwd=$(pwd)")
+        .await?;
+    print!("  {}", result.stdout);
+
+    Ok(())
+}
+
+/// Hot-swap a mounted filesystem to simulate a rolling update.
+async fn hot_swap_mount() -> anyhow::Result<()> {
+    println!("--- Hot-Swap Mount ---");
+
+    let mut bash = Bash::new();
+
+    // Version 1
+    let v1 = Arc::new(InMemoryFs::new());
+    v1.write_file(Path::new("/version"), b"1.0.0").await?;
+    v1.write_file(Path::new("/greeting"), b"Hello from v1")
+        .await?;
+
+    bash.mount("/app", v1)?;
+    let result = bash.exec("cat /app/version").await?;
+    println!("App version: {}", result.stdout.trim());
+
+    // Hot-swap to version 2 — just re-mount at the same path
+    let v2 = Arc::new(InMemoryFs::new());
+    v2.write_file(Path::new("/version"), b"2.0.0").await?;
+    v2.write_file(Path::new("/greeting"), b"Hello from v2")
+        .await?;
+
+    bash.mount("/app", v2)?;
+    let result = bash.exec("cat /app/version").await?;
+    println!("App version: {}", result.stdout.trim());
+
+    let result = bash.exec("cat /app/greeting").await?;
+    println!("Greeting: {}", result.stdout.trim());
+
+    Ok(())
+}

{bashkit-0.1.12 → bashkit-0.1.13}/crates/bashkit/src/builtins/ls.rs

@@ -9,7 +9,7 @@ use std::path::Path;
 use super::{Builtin, Context, ExecutionPlan, SubCommand, resolve_path};
 use crate::error::Result;
 use crate::fs::FileType;
-use crate::interpreter::ExecResult;
+use crate::interpreter::{ControlFlow, ExecResult};
 
 /// Options for ls command
 struct LsOptions {
@@ -472,10 +472,13 @@ async fn collect_find_paths(
     for path_str in search_paths {
         let path = resolve_path(ctx.cwd, path_str);
         if !ctx.fs.exists(&path).await.unwrap_or(false) {
-            // Skip non-existent paths in collection phase
             continue;
         }
-        find_recursive(ctx, &path, path_str, &temp_opts, 0, &mut output).await?;
+        // Intentionally swallowing errors (`let _ =`) rather than propagating (`?`):
+        // this feeds execution_plan(), which is only an optimization hint. Propagating
+        // would bubble up as Err and abort the entire command. Real error handling
+        // (stderr messages, exit codes) lives in execute(), which is always called.
+        let _ = find_recursive(ctx, &path, path_str, &temp_opts, 0, &mut output).await;
     }
     // Parse the output back into paths (each line is a path)
     for line in output.lines() {
@@ -547,24 +550,34 @@ impl Builtin for Find {
             Err(e) => return Ok(e),
         };
 
-        // Check paths exist
+        let mut output = String::new();
+        let mut errors = String::new();
+        let mut had_error = false;
+
         for path_str in &search_paths {
             let path = resolve_path(ctx.cwd, path_str);
             if !ctx.fs.exists(&path).await.unwrap_or(false) {
-                return Ok(ExecResult::err(
-                    format!("find: '{}': No such file or directory\n", path_str),
-                    1,
+                errors.push_str(&format!(
+                    "find: '{}': No such file or directory\n",
+                    path_str
                 ));
+                had_error = true;
+                continue;
             }
-        }
 
-        let mut output = String::new();
-        for path_str in &search_paths {
-            let path = resolve_path(ctx.cwd, path_str);
-            find_recursive(&ctx, &path, path_str, &opts, 0, &mut output).await?;
+            if let Err(e) = find_recursive(&ctx, &path, path_str, &opts, 0, &mut output).await {
+                errors.push_str(&format!("find: '{}': {}\n", path_str, e));
+                had_error = true;
+            }
         }
 
-        Ok(ExecResult::ok(output))
+        Ok(ExecResult {
+            stdout: output,
+            stderr: errors,
+            exit_code: if had_error { 1 } else { 0 },
+            control_flow: ControlFlow::None,
+            ..Default::default()
+        })
     }
 
     async fn execution_plan(&self, ctx: &Context<'_>) -> Result<Option<ExecutionPlan>> {
@@ -578,15 +591,7 @@ impl Builtin for Find {
             return Ok(None);
         }
 
-        // Check paths exist
-        for path_str in &search_paths {
-            let path = resolve_path(ctx.cwd, path_str);
-            if !ctx.fs.exists(&path).await.unwrap_or(false) {
-                return Ok(None); // Let execute() handle errors
-            }
-        }
-
-        // Collect matched paths
+        // Collect matched paths (collect_find_paths skips missing paths)
         let matched_paths = collect_find_paths(ctx, &search_paths, &opts).await?;
         if matched_paths.is_empty() {
             return Ok(None);

{bashkit-0.1.12 → bashkit-0.1.13}/crates/bashkit/src/fs/mountable.rs

@@ -490,6 +490,12 @@ impl FileSystemExt for MountableFs {
         // Return root filesystem limits as the overall limits
         self.root.limits()
     }
+
+    async fn mkfifo(&self, path: &Path, mode: u32) -> Result<()> {
+        self.validate_path(path)?;
+        let (fs, resolved) = self.resolve(path);
+        fs.mkfifo(&resolved, mode).await
+    }
 }
 
 #[cfg(test)]