Bashkit

https://docs.rs/bashkit
Admin
Bashkit is an awesomely fast virtual sandbox with bash and file system for AI agents, CI/CD...
Tokens:1,069,762
Snippets:6,224
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Custom Builtin Implementation Example

Source: https://docs.rs/bashkit/latest/bashkit/custom_builtins_guide/index.html

A quick start example demonstrating how to implement a custom builtin command 'greet' that accepts an argument and prints a greeting.

```APIDOC
## Custom Builtin Implementation Example

This example shows a basic implementation of a custom builtin command named `greet`.

### Method
N/A (This is a code example, not an HTTP endpoint)

### Endpoint
N/A

### Request Example
```rust
use bashkit::{Bash, Builtin, BuiltinContext, ExecResult, async_trait};

struct MyCommand;

#[async_trait]
impl Builtin for MyCommand {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        let name = ctx.args.first().map(|s| s.as_str()).unwrap_or("World");
        Ok(ExecResult::ok(format!("Hello, {}!\n", name)))
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut bash = Bash::builder()
        .builtin("greet", Box::new(MyCommand))
        .build();

    let result = bash.exec("greet Alice").await?;
    assert_eq!(result.stdout, "Hello, Alice!\n");
    Ok(())
}
```

### Response
#### Success Response (200)
- **stdout** (string) - The standard output of the command.
- **stderr** (string) - The standard error of the command.
- **exit_code** (i32) - The exit code of the command.

#### Response Example
```json
{
  "stdout": "Hello, Alice!\n",
  "stderr": "",
  "exit_code": 0
}
```
```

--------------------------------

### Snapshot filesystem state example

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/memory.rs.html

Demonstrates the setup for capturing a filesystem snapshot.

```rust
    /// ```rust
    /// use bashkit::{FileSystem, InMemoryFs};
    /// use std::path::Path;
    ///
    /// # #[tokio::main]
    /// # async fn main() -> bashkit::Result<()> {
```

--------------------------------

### Usage Examples

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/jq.rs.html

Examples of how to use the jq builtin from the command line.

```bash
echo '{"name":"foo"}' | jq '.name'
jq '.[] | .id' < data.json
```

--------------------------------

### Get Full Help Documentation

Source: https://docs.rs/bashkit/latest/bashkit/tool/struct.BashTool.html

Generates the full documentation for the tool, including examples, formatted in Markdown. This is intended for comprehensive LLM understanding and display.

```rust
fn help(&self) -> String
```

--------------------------------

### BashTool Execution Example

Source: https://docs.rs/bashkit/latest/src/bashkit/tool.rs.html

Shows how to execute a command using BashTool and stream its output. Includes setup for asynchronous execution and assertion of output chunks.

```rust
use bashkit::{BashTool, Tool};
use futures::StreamExt;

# tokio_test::block_on(async {
let tool = BashTool::default();
let execution = tool
    .execution(serde_json::json!({"commands": "printf 'a\nb\n'"}))
    .expect("valid args");
let mut stream = execution.output_stream().expect("stream available");

let handle = tokio::spawn(async move { execution.execute().await.expect("execution succeeds") });
let first = stream.next().await.expect("first chunk");
assert_eq!(first.kind, "stdout");
assert!(first.data.as_str().is_some_and(|chunk| chunk.starts_with("a\n")));

let output = handle.await.expect("join");
assert_eq!(output.result["stdout"], "a\nb\n");
# });
```

--------------------------------

### Dummy File System Usage Example

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/traits.rs.html

Demonstrates the usage of the Dummy file system implementation by creating an instance and asserting its usage and limits. This example verifies that the dummy implementation correctly reports zero usage and maximum limits.

```rust
let d = Dummy;
        let usage = d.usage();
        assert_eq!(usage.total_bytes, 0);
        assert_eq!(usage.file_count, 0);
        assert_eq!(usage.dir_count, 0);

        let limits = d.limits();
        assert_eq!(limits.max_total_bytes, u64::MAX);
```

--------------------------------

### CLI Mount Read-Write Example

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/realfs.rs.html

Example of mounting the real filesystem in read-write mode via the CLI to write to a file.

```bash
bashkit --mount-rw /path/to/out:/mnt/out -c 'echo hi > /mnt/out/result.txt'
```

--------------------------------

### Setup for Test Cases

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/test.rs.html

Initializes an in-memory file system, sets the current working directory, and prepares a mutable HashMap for variables. This setup is common across multiple test cases.

```rust
async fn setup() -> (Arc<InMemoryFs>, PathBuf, HashMap<String, String>) {
        let fs = Arc::new(InMemoryFs::new());
        let cwd = PathBuf::from("/home/user");
        let variables = HashMap::new();
        fs.mkdir(&cwd, true).await.unwrap();
        (fs, cwd, variables)
    }
```

--------------------------------

### Bashkit wget Builtin Examples

Source: https://docs.rs/bashkit/latest/src/bashkit/network/mod.rs.html

Examples showcasing `wget` commands usable with bashkit after network configuration. Covers downloading files, checking URL existence, and making POST requests.

```bash
# Download file
wget -O /tmp/file.txt https://cdn.example.com/file.txt
```

```bash
# Check if URL exists
wget --spider https://cdn.example.com/file.txt
```

```bash
# POST request
wget --post-data='key=value' -O - https://api.example.com/submit
```

--------------------------------

### Example Implementation of Builtin Trait

Source: https://docs.rs/bashkit/latest/bashkit/trait.Builtin.html

A practical example demonstrating how to implement the `Builtin` trait for a custom command named 'Greet'.

```APIDOC
## §Example

```rust
use bashkit::{Bash, Builtin, BuiltinContext, ExecResult, async_trait};

struct Greet {
    default_name: String,
}

#[async_trait]
impl Builtin for Greet {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        let name = ctx.args.first()
            .map(|s| s.as_str())
            .unwrap_or(&self.default_name);
        Ok(ExecResult::ok(format!("Hello, {}!\n", name)))
    }
}

// Register the builtin
let bash = Bash::builder()
    .builtin("greet", Box::new(Greet { default_name: "World".into() }))
    .build();
```
```

--------------------------------

### Example Usage of BuiltinContext

Source: https://docs.rs/bashkit/latest/bashkit/struct.BuiltinContext.html

An example demonstrating how to implement a custom builtin command using the BuiltinContext to access arguments, environment variables, and stdin.

```APIDOC
## Example

```rust
use bashkit::{Builtin, BuiltinContext, ExecResult, async_trait};

struct Echo;

#[async_trait]
impl Builtin for Echo {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        // Access command arguments
        let output = ctx.args.join(" ");

        // Access environment variables
        let _home = ctx.env.get("HOME");

        // Access pipeline input
        if let Some(stdin) = ctx.stdin {
            return Ok(ExecResult::ok(stdin.to_string()));
        }

        Ok(ExecResult::ok(format!("{}\n", output)))
    }
}
```
```

--------------------------------

### Rust: Test Setup Function for bc-rs

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/bc.rs.html

Provides a setup function for tests in the bc-rs library. It initializes an in-memory file system, sets a current working directory, and prepares a mutable hash map for variables.

```rust
async fn setup() -> (Arc<InMemoryFs>, PathBuf, HashMap<String, String>) {
    let fs = Arc::new(InMemoryFs::new());
    let cwd = PathBuf::from("/home/user");
    let variables = HashMap::new();
    fs.mkdir(&cwd, true).await.unwrap();
    (fs, cwd, variables)
}
```

--------------------------------

### Get Span Start Line Number in Rust

Source: https://docs.rs/bashkit/latest/src/bashkit/parser/span.rs.html

Retrieves the line number of the starting position of the Span. Useful for reporting errors on specific lines.

```rust
pub fn line(&self) -> usize {
    self.start.line
}
```

--------------------------------

### Basic Mounting Example

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/mountable.rs.html

Demonstrates how to create a MountableFs, mount another filesystem to a specific path, and access it using the Bash utility.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs, MountableFs};
use std::path::Path;
use std::sync::Arc;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
// Create root and separate data filesystem
let root = Arc::new(InMemoryFs::new());
let data_fs = Arc::new(InMemoryFs::new());

// Pre-populate data filesystem
data_fs.write_file(Path::new("/users.json"), br#"["alice", "bob"]"#).await?;

// Create mountable filesystem
let mountable = MountableFs::new(root.clone());

// Mount data_fs at /mnt/data
mountable.mount("/mnt/data", data_fs.clone())?;

// Use with Bash
let mut bash = Bash::builder().fs(Arc::new(mountable)).build();

// Access mounted filesystem
let result = bash.exec("cat /mnt/data/users.json").await?;
assert!(result.stdout.contains("alice"));

// Access root filesystem
bash.exec("echo hello > /root.txt").await?;
# Ok(())
# }
```

--------------------------------

### Bashkit curl Builtin Examples

Source: https://docs.rs/bashkit/latest/src/bashkit/network/mod.rs.html

Examples demonstrating various `curl` commands that can be used with bashkit once network access is configured. These include GET, POST, saving to file, authentication, and compressed requests.

```bash
# GET request
curl -s https://api.example.com/data
```

```bash
# POST with data
curl -X POST -d '{"key":"value"}' -H "Content-Type: application/json" https://api.example.com
```

```bash
# Save to file
curl -o /tmp/data.json https://api.example.com/data
```

```bash
# With authentication
curl -u user:pass https://api.example.com/private
```

```bash
# Request compressed response
curl --compressed https://api.example.com/large-data
```

--------------------------------

### Initialize PosixFs with Bash

Source: https://docs.rs/bashkit/latest/bashkit/struct.PosixFs.html

Example showing how to wrap a storage backend with PosixFs and integrate it into a Bash interpreter.

```rust
use bashkit::{FsBackend, PosixFs, Bash};
use std::sync::Arc;

// Your simple storage backend
let backend = MyStorage::new();

// Wrap with PosixFs for POSIX semantics
let fs = Arc::new(PosixFs::new(backend));

// Use with Bash interpreter
let mut bash = Bash::builder().fs(fs).build();
```

--------------------------------

### Unsupported Bun Install Mode

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/typescript.rs.html

Initializes TypeScript executor for 'bun' runtime. This snippet is a setup for testing unsupported modes.

```rust
let ts = TypeScript::from_config(&TypeScriptConfig::default(), "bun");
```

--------------------------------

### Strip inline comments

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/tomlq.rs.html

Inline comments in TOML (starting with '#') are stripped from values when querying. This example shows a port number with an inline comment.

```rust
let toml = "port = 8080 # the port\n";
let r = run(&["port"], Some(toml)).await;
assert_eq!(r.exit_code, 0);
assert_eq!(r.stdout.trim(), "8080");
```

--------------------------------

### Test YAML comment ignoring functionality

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/yaml.rs.html

Verifies that the 'get' command correctly retrieves values from YAML input while ignoring lines starting with '#'.

```rust
#[tokio::test]
async fn test_comments_ignored() {
    let yaml = "# comment\nkey: value\n# another comment\n";
    let r = run(&["-r", "get", "key"], Some(yaml)).await;
    assert_eq!(r.exit_code, 0);
    assert_eq!(r.stdout.trim(), "value");
}
```

--------------------------------

### RealFs Initialization

Source: https://docs.rs/bashkit/latest/bashkit/struct.RealFs.html

Demonstrates how to create a new RealFs backend instance.

```APIDOC
## POST /api/realfs/new

### Description
Creates a new RealFs backend rooted at the given directory. The root path is canonicalized on creation. Returns an error if the path does not exist or is not a directory.

### Method
POST

### Endpoint
/api/realfs/new

### Parameters
#### Query Parameters
- **root** (string) - Required - The root directory path.
- **mode** (RealFsMode) - Required - The access mode for the RealFs backend (e.g., ReadOnly, ReadWrite).

### Request Example
```json
{
  "root": "/tmp",
  "mode": "ReadOnly"
}
```

### Response
#### Success Response (200)
- **RealFs** (object) - The newly created RealFs backend instance.

#### Response Example
```json
{
  "backend_id": "unique_backend_identifier"
}
```
```

--------------------------------

### Example: Creating and Using OverlayFs

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/overlay.rs.html

Demonstrates creating an OverlayFs with an InMemoryFs base, reading from the base, and writing new files to the overlay. Writes are isolated to the upper layer.

```rust
use bashkit::{FileSystem, InMemoryFs, OverlayFs};
use std::path::Path;
use std::sync::Arc;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
// Create base with some files
let base = Arc::new(InMemoryFs::new());
base.mkdir(Path::new("/data"), false).await?;
base.write_file(Path::new("/data/readme.txt"), b"Read me!").await?;

// Create overlay
let overlay = OverlayFs::new(base);

// Can read from base
let content = overlay.read_file(Path::new("/data/readme.txt")).await?;
assert_eq!(content, b"Read me!");

// Writes go to upper layer
overlay.write_file(Path::new("/data/new.txt"), b"New file").await?;
# Ok(())
# }
```

--------------------------------

### Setup Test Environment

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/realfs.rs.html

Sets up a temporary directory with sample files and a subdirectory for testing RealFs operations.

```rust
fn setup() -> TempDir {
            let dir = tempfile::tempdir().unwrap();
            // Create some test files
            std::fs::write(dir.path().join("hello.txt"), b"hello world").unwrap();
            std::fs::create_dir(dir.path().join("subdir")).unwrap();
            std::fs::write(dir.path().join("subdir/nested.txt"), b"nested content").unwrap();
            dir
        }
```

--------------------------------

### Quick Start: Live Mount and Unmount Filesystem

Source: https://docs.rs/bashkit/latest/bashkit/live_mounts_guide/index.html

Demonstrates creating an in-memory filesystem, writing data to it, mounting it live to a running Bash instance, executing a command to read the data, and then unmounting it. Requires `Bash`, `FileSystem`, `InMemoryFs`, `Path`, and `Arc`.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs};
use std::path::Path;
use std::sync::Arc;

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")?;

```

--------------------------------

### Get File Metadata Example

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/traits.rs.html

Demonstrates how to retrieve file metadata using `fs.stat()` and assert properties like file type, size, and default permissions.

```rust
use bashkit::{Bash, FileSystem, FileType};
use std::path::Path;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
let bash = Bash::new();
let fs = bash.fs();

fs.write_file(Path::new("/tmp/test.txt"), b"hello").await?;

let stat = fs.stat(Path::new("/tmp/test.txt")).await?;
assert!(stat.file_type.is_file());
assert_eq!(stat.size, 5);  // "hello" = 5 bytes
assert_eq!(stat.mode, 0o644);  // Default file permissions
# Ok(())
# }
```

--------------------------------

### Test Setup Helper

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/seq.rs.html

Initializes an in-memory file system and environment context for testing command execution.

```rust
    async fn setup() -> (Arc<InMemoryFs>, PathBuf, HashMap<String, String>) {
        let fs = Arc::new(InMemoryFs::new());
        let cwd = PathBuf::from("/home/user");
        let variables = HashMap::new();
        fs.mkdir(&cwd, true).await.unwrap();
        (fs, cwd, variables)
    }
```

--------------------------------

### JSON Request Examples

Source: https://docs.rs/bashkit/latest/src/bashkit/tool.rs.html

Example JSON payloads for executing bash commands.

```json
{"commands":"echo hello"}
```

```json
{"commands":"echo data > /tmp/f.txt && cat /tmp/f.txt","timeout_ms":5000}
```

--------------------------------

### Initialize and Use InMemoryFs

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/memory.rs.html

Demonstrates how to create an InMemoryFs instance, perform file operations like writing and reading, create directories, and check for existence. It also shows how to integrate the custom filesystem with the Bash executor.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs};
use std::path::Path;
use std::sync::Arc;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
// InMemoryFs is the default when using Bash::new()
let mut bash = Bash::new();

// Or create explicitly for direct filesystem access
let fs = Arc::new(InMemoryFs::new());

// Write files
fs.write_file(Path::new("/tmp/test.txt"), b"hello").await?;

// Read files
let content = fs.read_file(Path::new("/tmp/test.txt")).await?;
assert_eq!(content, b"hello");

// Create directories
fs.mkdir(Path::new("/data/nested/dir"), true).await?;

// Check existence
assert!(fs.exists(Path::new("/data/nested/dir")).await?);

// Use with Bash
let mut bash = Bash::builder().fs(fs.clone()).build();
bash.exec("echo 'from bash' >> /tmp/test.txt").await?;

let content = fs.read_file(Path::new("/tmp/test.txt")).await?;
assert_eq!(content, b"hellofrom bash\n");
# Ok(())
# }
```

--------------------------------

### Arc<T, A> Examples

Source: https://docs.rs/bashkit/latest/bashkit/scripted_tool/type.ToolCallback.html

Illustrative examples demonstrating the usage of Arc<T, A> and its related functions.

```APIDOC
## Arc<T, A> Examples

### Example 1: `Arc::into_raw_with_allocator` and `Arc::from_raw_in`
```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let x = Arc::new_in("hello".to_owned(), System);
let (x_ptr, alloc) = Arc::into_raw_with_allocator(x);

unsafe {
    // Convert back to an `Arc` to prevent leak.
    let x = Arc::from_raw_in(x_ptr, System);
    assert_eq!(&*x, "hello");

    // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.
}

// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!
```

### Example 2: Converting a slice back into its original array
```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let x: Arc<[u32], _> = Arc::new_in([1, 2, 3], System);
let x_ptr: *const [u32] = Arc::into_raw_with_allocator(x).0;

unsafe {
    let x: Arc<[u32; 3], _> = Arc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System);
    assert_eq!(&*x, &[1, 2, 3]);
}
```
```

--------------------------------

### Create Directory and Read Directory Contents

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/memory.rs.html

Shows how to create a directory, write a file into it, and then list the directory's contents.

```rust
    fs.mkdir(Path::new("/tmp/mydir"), false).await.unwrap();
    fs.write_file(Path::new("/tmp/mydir/file.txt"), b"test")
        .await
        .unwrap();

    let entries = fs.read_dir(Path::new("/tmp/mydir")).await.unwrap();
    assert_eq!(entries.len(), 1);
    assert_eq!(entries[0].name, "file.txt");
```

--------------------------------

### DirEntry Example Usage

Source: https://docs.rs/bashkit/latest/bashkit/struct.DirEntry.html

Example demonstrating how to use the DirEntry struct when reading directory contents.

```APIDOC
## Example
```rust
use bashkit::{Bash, FileSystem};
use std::path::Path;

let bash = Bash::new();
let fs = bash.fs();

fs.mkdir(Path::new("/data"), false).await?;
fs.write_file(Path::new("/data/file.txt"), b"content").await?;

let entries = fs.read_dir(Path::new("/data")).await?;
for entry in entries {
    println!("Name: {}, Size: {}", entry.name, entry.metadata.size);
}
```
```

--------------------------------

### Example: OverlayFs with Custom Limits

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/overlay.rs.html

Shows how to initialize an OverlayFs with specific filesystem limits, such as a maximum total byte count. The upper layer itself uses unlimited limits, with enforcement handled at the OverlayFs level.

```rust
use bashkit::{FileSystem, InMemoryFs, OverlayFs, FsLimits};
use std::path::Path;
use std::sync::Arc;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
let base = Arc::new(InMemoryFs::new());
let limits = FsLimits::new().max_total_bytes(10_000_000); // 10MB

let overlay = OverlayFs::with_limits(base, limits);
# Ok(())
# }
```

--------------------------------

### Initialize and Execute a Simple Command

Source: https://docs.rs/bashkit/latest/src/bashkit/lib.rs.html

Demonstrates how to create a new Bash instance and execute a simple 'echo' command, asserting the output and exit code.

```rust
use bashkit::Bash;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
let mut bash = Bash::new();
let result = bash.exec("echo 'Hello, World!'").await?;
assert_eq!(result.stdout, "Hello, World!\n");
assert_eq!(result.exit_code, 0);
# Ok(())
# }
```

--------------------------------

### CLI Mount Read-Only Example

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/realfs.rs.html

Example of mounting the real filesystem in read-only mode via the CLI to access a file.

```bash
bashkit --mount-ro /path/to/data:/mnt/data -c 'cat /mnt/data/file.txt'
```

--------------------------------

### Quick Start: Implement and Register a Custom Builtin

Source: https://docs.rs/bashkit/latest/bashkit/custom_builtins_guide/index.html

Demonstrates implementing the `Builtin` trait for a 'greet' command and registering it with Bashkit. Requires `tokio` for async execution.

```rust
use bashkit::{Bash, Builtin, BuiltinContext, ExecResult, async_trait};

struct MyCommand;

#[async_trait]
impl Builtin for MyCommand {
    async fn execute(&self, ctx: BuiltinContext<'_>) -> bashkit::Result<ExecResult> {
        let name = ctx.args.first().map(|s| s.as_str()).unwrap_or("World");
        Ok(ExecResult::ok(format!("Hello, {}!\n", name)))
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut bash = Bash::builder()
        .builtin("greet", Box::new(MyCommand))
        .build();

    let result = bash.exec("greet Alice").await?;
    assert_eq!(result.stdout, "Hello, Alice!\n");
    Ok(())
}
```

--------------------------------

### Dynamic Mount and Unmount Example

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/mountable.rs.html

Shows how to dynamically mount and unmount filesystems at runtime using the MountableFs.

```rust
use bashkit::{FileSystem, InMemoryFs, MountableFs};
use std::path::Path;
use std::sync::Arc;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
let root = Arc::new(InMemoryFs::new());
let plugin_fs = Arc::new(InMemoryFs::new());
plugin_fs.write_file(Path::new("/plugin.so"), b"binary").await?;

let mountable = MountableFs::new(root);

// Mount plugin filesystem
mountable.mount("/plugins", plugin_fs)?;
assert!(mountable.exists(Path::new("/plugins/plugin.so")).await?);

// Unmount when done
mountable.unmount("/plugins")?;
assert!(!mountable.exists(Path::new("/plugins/plugin.so")).await?);
# Ok(())
# }
```

--------------------------------

### Example: Simple Key-Value Storage Implementation

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/backend.rs.html

An example implementation of the FsBackend trait using a HashMap for simple key-value storage.

```APIDOC
## Example: Simple Key-Value Storage

```rust,ignore
use bashkit::{async_trait, FsBackend, Result, Metadata, DirEntry, FileType};
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::RwLock;

/// Simple storage backed by a HashMap.
pub struct KvStorage {
    data: RwLock<HashMap<PathBuf, Vec<u8>>>,
}

#[async_trait]
impl FsBackend for KvStorage {
    async fn read(&self, path: &Path) -> Result<Vec<u8>> {
        let data = self.data.read().unwrap();
        data.get(path)
            .cloned()
            .ok_or_else(|| std::io::Error::from(std::io::ErrorKind::NotFound).into())
    }

    async fn write(&self, path: &Path, content: &[u8]) -> Result<()> {
        let mut data = self.data.write().unwrap();
        data.insert(path.to_path_buf(), content.to_vec());
        Ok(())
    }

    // ... implement remaining methods
}
```
```

--------------------------------

### Perform basic mounting with MountableFs

Source: https://docs.rs/bashkit/latest/bashkit/struct.MountableFs.html

Demonstrates creating a root filesystem, mounting a secondary filesystem, and accessing files through the Bash interface.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs, MountableFs};
use std::path::Path;
use std::sync::Arc;

// Create root and separate data filesystem
let root = Arc::new(InMemoryFs::new());
let data_fs = Arc::new(InMemoryFs::new());

// Pre-populate data filesystem
data_fs.write_file(Path::new("/users.json"), br#"["alice", "bob"]"#).await?;

// Create mountable filesystem
let mountable = MountableFs::new(root.clone());

// Mount data_fs at /mnt/data
mountable.mount("/mnt/data", data_fs.clone())?;

// Use with Bash
let mut bash = Bash::builder().fs(Arc::new(mountable)).build();

// Access mounted filesystem
let result = bash.exec("cat /mnt/data/users.json").await?;
assert!(result.stdout.contains("alice"));

// Access root filesystem
bash.exec("echo hello > /root.txt").await?;
```

--------------------------------

### Arc::into_raw and Arc::from_raw Example

Source: https://docs.rs/bashkit/latest/bashkit/type.LazyLoader.html

An example demonstrating the use of `Arc::into_raw` and `Arc::from_raw` for manual memory management.

```APIDOC
## POST /api/orders

### Description
Creates a new order.

### Method
POST

### Endpoint
/api/orders

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user placing the order.
- **items** (array) - Required - A list of items to include in the order.
  - **itemId** (string) - Required - The ID of the item.
  - **quantity** (integer) - Required - The quantity of the item.

### Request Example
```json
{
  "userId": "user123",
  "items": [
    {
      "itemId": "item1",
      "quantity": 2
    },
    {
      "itemId": "item3",
      "quantity": 1
    }
  ]
}
```

### Response
#### Success Response (201)
- **orderId** (string) - The unique identifier for the newly created order.
- **userId** (string) - The ID of the user who placed the order.
- **status** (string) - The status of the order (e.g., "PENDING", "PROCESSING", "SHIPPED").
- **createdAt** (string) - The timestamp when the order was created.

#### Response Example
```json
{
  "orderId": "order987",
  "userId": "user123",
  "status": "PENDING",
  "createdAt": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Using a Custom FileSystem

Source: https://docs.rs/bashkit/latest/bashkit/trait.FileSystem.html

Demonstrates how to pass a custom filesystem implementation to the `Bash::builder()`.

```APIDOC
## Using Custom Filesystems
Pass your filesystem to `Bash::builder()`:
```rust
use bashkit::Bash;
use std::sync::Arc;

let custom_fs = Arc::new(MyFileSystem::new());
let mut bash = Bash::builder().fs(custom_fs).build();
```
```

--------------------------------

### Check for brace group start

Source: https://docs.rs/bashkit/latest/src/bashkit/parser/lexer.rs.html

Determines if a sequence starting with '{' qualifies as a brace group by checking for subsequent whitespace or newline characters.

```rust
    /// Check if { is followed by whitespace (brace group start)
    fn is_brace_group_start(&self) -> bool {
        let mut chars = self.chars.clone();
        // Skip the opening {
        if chars.next() != Some('{') {
            return false;
        }
        // If next char is whitespace or newline, it's a brace group
        matches!(chars.next(), Some(' ') | Some('\t') | Some('\n') | None)
    }
```

--------------------------------

### Basic OverlayFs Usage with Bash

Source: https://docs.rs/bashkit/latest/bashkit/struct.OverlayFs.html

Demonstrates creating an OverlayFs, reading from the base layer, modifying files (which go to the overlay), and verifying that the base layer remains unchanged.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs, OverlayFs};
use std::path::Path;
use std::sync::Arc;

// Create a base filesystem with template files
let base = Arc::new(InMemoryFs::new());
base.mkdir(Path::new("/config"), false).await?;
base.write_file(Path::new("/config/app.conf"), b"debug=false").await?;

// Create overlay - base is read-only, changes go to overlay
let overlay = Arc::new(OverlayFs::new(base.clone()));

// Use with Bash
let mut bash = Bash::builder().fs(overlay.clone()).build();

// Read from base layer
let result = bash.exec("cat /config/app.conf").await?;
assert_eq!(result.stdout, "debug=false");

// Modify - changes go to overlay only
bash.exec("echo 'debug=true' > /config/app.conf").await?;

// Overlay shows modified content
let result = bash.exec("cat /config/app.conf").await?;
assert_eq!(result.stdout, "debug=true\n");

// Base is unchanged!
let original = base.read_file(Path::new("/config/app.conf")).await?;
assert_eq!(original, b"debug=false");

```

--------------------------------

### Make GET Request

Source: https://docs.rs/bashkit/latest/src/bashkit/network/client.rs.html

Executes an HTTP GET request to the specified URL. This is a convenience method that calls the more general `request` method.

```rust
pub async fn get(&self, url: &str) -> Result<Response> {
    self.request(Method::Get, url, None).await
}
```

--------------------------------

### Tool Help Method

Source: https://docs.rs/bashkit/latest/bashkit/tool/trait.Tool.html

Returns full documentation for LLMs, including examples, typically in markdown format.

```rust
fn help(&self) -> String;
```

--------------------------------

### Initialize Virtual Filesystem

Source: https://docs.rs/bashkit/latest/bashkit/threat_model/index.html

Demonstrates the default in-memory filesystem isolation and how to configure explicit mounts for advanced use cases.

```rust
use bashkit::{Bash, InMemoryFs, MountableFs};
use std::sync::Arc;

// Default: fully isolated in-memory filesystem
let bash = Bash::new();

// Custom filesystem with explicit mounts (advanced)
let root = Arc::new(InMemoryFs::new());
let fs = Arc::new(MountableFs::new(root));
// fs.mount("/data", Arc::new(InMemoryFs::new()));  // Mount additional filesystems
```

--------------------------------

### Test HTTP Command: Simple GET Request

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/http.rs.html

Tests a basic GET request to a specified URL. Expects an exit code of 0 and the URL in stdout.

```rust
async fn test_simple_get() {
        let result = run_http(&["https://example.com/api"]).await;
        assert_eq!(result.exit_code, 0);
        assert!(result.stdout.contains("GET https://example.com/api"));
    }
```

--------------------------------

### Test Case: Get Non-existent JSON Path

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/json.rs.html

Tests the behavior when attempting to 'get' a path that does not exist in the JSON. Asserts an error code of 1 and specific stderr content.

```rust
    #[tokio::test]
    async fn test_get_not_found() {
        let r = run(&["get", ".missing"], Some(r#"{"a":1}"#), None).await;
        assert_eq!(r.exit_code, 1);
        assert!(r.stderr.contains("not found"));
    }
```

--------------------------------

### Test Case: Get Simple JSON Value

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/json.rs.html

Tests retrieving a simple value from a JSON object using the 'get' command. Asserts successful execution and correct stdout.

```rust
    #[tokio::test]
    async fn test_get_simple() {
        let r = run(&["get", ".name"], Some(r#"{"name":"alice"}"#), None).await;
        assert_eq!(r.exit_code, 0);
        assert_eq!(r.stdout.trim(), "alice");
    }
```

--------------------------------

### NetworkAllowlist Initialization and Configuration

Source: https://docs.rs/bashkit/latest/src/bashkit/network/allowlist.rs.html

Demonstrates how to create and configure a NetworkAllowlist, including setting up specific URL patterns or enabling 'allow all' mode.

```APIDOC
## NetworkAllowlist Initialization and Configuration

### Description

This section covers the initialization of the `NetworkAllowlist` struct and its configuration methods, including creating an empty allowlist, an allowlist that permits all URLs, and adding individual or multiple URL patterns.

### Methods

#### `NetworkAllowlist::new()`

- **Description**: Creates a new, empty `NetworkAllowlist`. An empty allowlist blocks all network access by default.
- **Returns**: A new `NetworkAllowlist` instance.

#### `NetworkAllowlist::allow_all()`

- **Description**: Creates a `NetworkAllowlist` that permits all URLs. Use with caution, as this bypasses all security checks.
- **Warning**: This is dangerous and should only be used for testing or when the script is fully trusted.
- **Returns**: A new `NetworkAllowlist` instance configured to allow all.

#### `NetworkAllowlist::allow(pattern: impl Into<String>)`

- **Description**: Adds a single URL pattern to the allowlist. The pattern can be a full URL, a host, or a host with a port. The path component of the pattern is treated as a prefix.
- **Parameters**:
  - **pattern** (String) - The URL pattern to add to the allowlist.
- **Returns**: The modified `NetworkAllowlist` instance for chaining.

#### `NetworkAllowlist::allow_many(patterns: impl IntoIterator<Item = impl Into<String>>)`

- **Description**: Adds multiple URL patterns to the allowlist from an iterator.
- **Parameters**:
  - **patterns** (Iterator of Strings) - An iterator yielding URL patterns to add.
- **Returns**: The modified `NetworkAllowlist` instance for chaining.

### Examples

```rust
use bashkit::NetworkAllowlist;

// Create an empty allowlist (blocks all by default)
let mut allowlist = NetworkAllowlist::new();

// Add specific URLs and paths
allowlist = allowlist.allow("https://api.example.com");
allowlist = allowlist.allow("https://cdn.example.com/assets/");

// Add multiple patterns at once
allowlist = allowlist.allow_many([
    "http://localhost:8080",
    "https://internal.service.net/api/v2",
]);

// Create an allowlist that allows everything (use carefully)
let allow_all_list = NetworkAllowlist::allow_all();
```
```

--------------------------------

### Check for '=' Prefix in Rust Token

Source: https://docs.rs/bashkit/latest/src/bashkit/parser/mod.rs.html

Checks if the current token starts with an equals sign (`=`). If it's an assignment token or a word starting with `=`, it returns the rest of the word after the `=`. Otherwise, it returns `None`.

```rust
fn current_token_starts_with_eq(&self) -> Option<String> {
        match &self.current_token {
            Some(tokens::Token::Assignment) => Some(String::new()),
            Some(tokens::Token::Word(w)) | Some(tokens::Token::LiteralWord(w)) => {
                w.strip_prefix('=').map(|rest| rest.to_string())
            }
            _ => None,
        }
    }
```

--------------------------------

### Choosing a Filesystem Implementation

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/mod.rs.html

Guidance on selecting the appropriate filesystem trait or type based on custom storage needs. Use `InMemoryFs` for default behavior, implement `FsBackend` + `PosixFs` for simple storage, or `FileSystem` directly for complex control.

```text
Do you need a custom filesystem?
    │
    ├─ NO → Use InMemoryFs (default with Bash::new())
    │
    └─ YES → Is your storage simple (key-value, database, cloud)?
              │
              ├─ YES → Implement FsBackend + wrap with PosixFs
              │        (POSIX checks are automatic)
              │
              └─ NO → Implement FileSystem directly
                      (full control, you handle all checks)

```

--------------------------------

### Execute Substring Extraction

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/expr.rs.html

Executes a substring extraction operation. The arguments are the string, start position (1-based), and length. Ensure the start position and length are within valid bounds to avoid unexpected results.

```rust
let args = vec![
            "substr".to_string(),
            "hello".to_string(),
            "1".to_string(),
            "3".to_string(),
        ];
        let ctx = Context::new_for_test(&args, &env, &mut variables, &mut cwd, fs.clone(), None);
        let result = Expr.execute(ctx).await.unwrap();
        assert_eq!(result.stdout.trim(), "ell");
```

--------------------------------

### Multiple Live Mounts Example

Source: https://docs.rs/bashkit/latest/bashkit/live_mounts_guide/index.html

Demonstrates mounting multiple distinct in-memory filesystems to different paths within a single running `Bash` instance. This allows for organizing and accessing different sets of data or configurations dynamically. Requires `Bash`, `FileSystem`, `InMemoryFs`, `Path`, and `Arc`.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs};
use std::path::Path;
use std::sync::Arc;

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");

```

--------------------------------

### Test Tail Command with +n from Start

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/headtail.rs.html

Tests the 'tail' command's ability to start output from a specific line number using the '+n' syntax, displaying lines from the second line onwards.

```rust
    #[tokio::test]
    async fn test_tail_plus_n_from_start() {
        let input = "header\nline1\nline2\nline3\n";
        let result = run_tail(&["-n", "+2"], Some(input)).await;
        assert_eq!(result.exit_code, 0);
        assert_eq!(result.stdout, "line1\nline2\nline3\n");
    }
```

--------------------------------

### Example Git Workflow in Bash

Source: https://docs.rs/bashkit/latest/src/bashkit/builtins/git.rs.html

Demonstrates a typical workflow using the git builtin command, including initializing a repository, adding a file, committing changes, and viewing the log.

```bash
git init /myrepo
cd /myrepo
echo "Hello" > README.md
git add README.md
git commit -m "Initial commit"
git log
```

--------------------------------

### Initialize OverlayFs with Limits

Source: https://docs.rs/bashkit/latest/bashkit/struct.OverlayFs.html

Demonstrates how to create an OverlayFs instance with a specified limit on total bytes. This is useful for controlling the maximum size of the overlay filesystem.

```rust
use bashkit::{FileSystem, InMemoryFs, OverlayFs, FsLimits};
use std::path::Path;
use std::sync::Arc;

let base = Arc::new(InMemoryFs::new());
let limits = FsLimits::new().max_total_bytes(10_000_000); // 10MB

let overlay = OverlayFs::with_limits(base, limits);
```

--------------------------------

### GET /fs

Source: https://docs.rs/bashkit/latest/src/bashkit/lib.rs.html

Accesses the underlying virtual filesystem.

```APIDOC
## GET /fs

### Description
Provides direct access to the virtual filesystem for pre-populating files, reading outputs, or injecting configuration.
```

--------------------------------

### Using a Custom Backend

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/backend.rs.html

Demonstrates how to wrap a custom FsBackend implementation with PosixFs to enable POSIX semantics.

```APIDOC
## Using Your Backend

Wrap with [`PosixFs`](super::PosixFs) to get POSIX semantics:

```rust,ignore
use bashkit::{Bash, PosixFs};
use std::sync::Arc;

let backend = KvStorage::new(); // Assuming KvStorage::new() is implemented
let fs = Arc::new(PosixFs::new(backend));
let mut bash = Bash::builder().fs(fs).build();

// POSIX checks are automatic:
// - Writing to a directory fails
// - mkdir on existing file fails
// - Parent directory must exist
```

See `examples/custom_backend.rs` for a complete working example.
```

--------------------------------

### GET /stat

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/posix.rs.html

Retrieves metadata for a file or directory.

```APIDOC
## GET /stat

### Description
Returns metadata for the object at the specified path.

### Method
GET

### Endpoint
/stat

### Parameters
#### Query Parameters
- **path** (Path) - Required - The path to query.
```

--------------------------------

### Create and Use OverlayFs with Bash

Source: https://docs.rs/bashkit/latest/src/bashkit/fs/overlay.rs.html

Demonstrates creating an OverlayFs with a base InMemoryFs, then using it with Bash to read from the base, modify files (which go to the overlay), and verify that the base remains unchanged.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs, OverlayFs};
use std::path::Path;
use std::sync::Arc;

# #[tokio::main]
# async fn main() -> bashkit::Result<()> {
// Create a base filesystem with template files
let base = Arc::new(InMemoryFs::new());
base.mkdir(Path::new("/config"), false).await?;
base.write_file(Path::new("/config/app.conf"), b"debug=false").await?;

// Create overlay - base is read-only, changes go to overlay
let overlay = Arc::new(OverlayFs::new(base.clone()));

// Use with Bash
let mut bash = Bash::builder().fs(overlay.clone()).build();

// Read from base layer
let result = bash.exec("cat /config/app.conf").await?;
assert_eq!(result.stdout, "debug=false");

// Modify - changes go to overlay only
bash.exec("echo 'debug=true' > /config/app.conf").await?;

// Overlay shows modified content
let result = bash.exec("cat /config/app.conf").await?;
assert_eq!(result.stdout, "debug=true\n");

// Base is unchanged!
let original = base.read_file(Path::new("/config/app.conf")).await?;
assert_eq!(original, b"debug=false");
# Ok(())
# }
```

--------------------------------

### GET /limits

Source: https://docs.rs/bashkit/latest/bashkit/struct.OverlayFs.html

Retrieves the current filesystem limits.

```APIDOC
## GET /limits

### Description
Get filesystem limits.

### Method
GET

### Endpoint
/limits

### Response
#### Success Response (200)
- **FsLimits** (object) - The current filesystem limits.
```

--------------------------------

### Initialize and Use InMemoryFs

Source: https://docs.rs/bashkit/latest/bashkit/struct.InMemoryFs.html

Demonstrates creating an InMemoryFs instance, performing file operations, and integrating it with a Bash environment.

```rust
use bashkit::{Bash, FileSystem, InMemoryFs};
use std::path::Path;
use std::sync::Arc;

// InMemoryFs is the default when using Bash::new()
let mut bash = Bash::new();

// Or create explicitly for direct filesystem access
let fs = Arc::new(InMemoryFs::new());

// Write files
fs.write_file(Path::new("/tmp/test.txt"), b"hello").await?;

// Read files
let content = fs.read_file(Path::new("/tmp/test.txt")).await?;
assert_eq!(content, b"hello");

// Create directories
fs.mkdir(Path::new("/data/nested/dir"), true).await?;

// Check existence
assert!(fs.exists(Path::new("/data/nested/dir")).await?);

// Use with Bash
let mut bash = Bash::builder().fs(fs.clone()).build();
bash.exec("echo 'from bash' >> /tmp/test.txt").await?;

let content = fs.read_file(Path::new("/tmp/test.txt")).await?;
assert_eq!(content, b"hellofrom bash\n");
```

--------------------------------

### GET /read_file

Source: https://docs.rs/bashkit/latest/bashkit/struct.InMemoryFs.html

Reads the contents of a file as bytes.

```APIDOC
## GET /read_file

### Description
Read a file’s contents as bytes.

### Parameters
#### Query Parameters
- **path** (string) - Required - Path to the file
```

--------------------------------

### Get Tool Locale

Source: https://docs.rs/bashkit/latest/src/bashkit/scripted_tool/execute.rs.html

Retrieves the locale string for the tool.

```rust
fn locale(&self) -> &str {
        &self.locale
    }
```

--------------------------------

### Initialize ScriptingToolSet with Discovery

Source: https://docs.rs/bashkit/latest/bashkit/scripted_tool/struct.DiscoverTool.html

Demonstrates how to build a ScriptingToolSet with discovery enabled, which includes the DiscoverTool. This setup is useful for LLMs to explore available tools.

```rust
use bashkit::{ScriptingToolSet, ToolArgs, ToolDef, Tool};

let toolset = ScriptingToolSet::builder("api")
    .tool(
        ToolDef::new("greet", "Greet someone").with_category("social"),
        |_args: &ToolArgs| Ok("hello\n".to_string()),
    )
    .with_discovery()
    .build();

let tools = toolset.tools();
assert_eq!(tools.len(), 2);

// Second tool is the DiscoverTool
let discover = &tools[1];
assert!(discover.name().ends_with("_discover"));
```

--------------------------------

### Arc::weak_count

Source: https://docs.rs/bashkit/latest/bashkit/scripted_tool/type.ToolCallback.html

Gets the number of `Weak` pointers to this allocation.

```APIDOC
#### pub fn weak_count(this: &Arc<T, A>) -> usize

Gets the number of `Weak` pointers to this allocation.

##### §Safety
This method by itself is safe, but using it correctly requires extra care. Another thread can change the weak count at any time, including potentially between calling this method and acting on the result.

##### §Examples
```rust
use std::sync::Arc;

let five = Arc::new(5);
let _weak_five = Arc::downgrade(&five);

// This assertion is deterministic because we haven't shared
// the `Arc` or `Weak` between threads.
assert_eq!(1, Arc::weak_count(&five));
```
```

--------------------------------

### GET /vfs_snapshot

Source: https://docs.rs/bashkit/latest/bashkit/struct.OverlayFs.html

Takes a snapshot of the filesystem contents for serialization.

```APIDOC
## GET /vfs_snapshot

### Description
Take a snapshot of the filesystem contents for serialization.

### Method
GET

### Endpoint
/vfs_snapshot

### Response
#### Success Response (200)
- **VfsSnapshot** (object) - The filesystem snapshot.
```
Tokens:
Raw