just-bash 0.1.5__py3-none-any.whl

just_bash/types.py

@@ -0,0 +1,180 @@
+"""Core types for just-bash."""
+
+from dataclasses import dataclass, field
+from typing import Protocol, Callable, Awaitable, Optional, Any
+
+
+@dataclass
+class ExecResult:
+    """Result of executing a command or script."""
+
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int = 0
+    env: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class BashExecResult(ExecResult):
+    """Extended result with environment state."""
+
+    pass
+
+
+# Convenience constants
+OK = ExecResult(stdout="", stderr="", exit_code=0)
+FAIL = ExecResult(stdout="", stderr="", exit_code=1)
+
+
+@dataclass
+class ExecutionLimits:
+    """Configurable execution limits for security."""
+
+    max_call_depth: int = 100
+    max_command_count: int = 100_000
+    max_loop_iterations: int = 10_000
+    max_awk_iterations: int = 10_000
+    max_sed_iterations: int = 10_000
+
+
+@dataclass
+class NetworkConfig:
+    """Network access configuration."""
+
+    allowed_url_prefixes: list[str] = field(default_factory=list)
+    allowed_methods: list[str] = field(default_factory=lambda: ["GET", "POST", "PUT", "DELETE"])
+    max_redirects: int = 10
+    timeout_ms: int = 30_000
+    dangerously_allow_full_internet_access: bool = False
+
+
+class IFileSystem(Protocol):
+    """Abstract filesystem interface."""
+
+    async def read_file(self, path: str, encoding: str = "utf-8") -> str:
+        """Read file contents as string."""
+        ...
+
+    async def read_file_bytes(self, path: str) -> bytes:
+        """Read file contents as bytes."""
+        ...
+
+    async def write_file(
+        self, path: str, content: str | bytes, encoding: str = "utf-8"
+    ) -> None:
+        """Write content to file."""
+        ...
+
+    async def append_file(self, path: str, content: str | bytes) -> None:
+        """Append content to file."""
+        ...
+
+    async def exists(self, path: str) -> bool:
+        """Check if path exists."""
+        ...
+
+    async def is_file(self, path: str) -> bool:
+        """Check if path is a file."""
+        ...
+
+    async def is_directory(self, path: str) -> bool:
+        """Check if path is a directory."""
+        ...
+
+    async def mkdir(self, path: str, recursive: bool = False) -> None:
+        """Create directory."""
+        ...
+
+    async def readdir(self, path: str) -> list[str]:
+        """List directory contents."""
+        ...
+
+    async def rm(self, path: str, recursive: bool = False, force: bool = False) -> None:
+        """Remove file or directory."""
+        ...
+
+    async def stat(self, path: str) -> "FsStat":
+        """Get file/directory stats."""
+        ...
+
+    async def chmod(self, path: str, mode: int) -> None:
+        """Change file mode."""
+        ...
+
+    async def symlink(self, target: str, link_path: str) -> None:
+        """Create symbolic link."""
+        ...
+
+    async def readlink(self, path: str) -> str:
+        """Read symbolic link target."""
+        ...
+
+    def resolve_path(self, base: str, path: str) -> str:
+        """Resolve path relative to base."""
+        ...
+
+
+@dataclass
+class FsStat:
+    """File/directory statistics."""
+
+    is_file: bool = False
+    is_directory: bool = False
+    is_symbolic_link: bool = False
+    mode: int = 0o644
+    size: int = 0
+    mtime: float = 0.0
+    nlink: int = 1
+
+
+@dataclass
+class CommandExecOptions:
+    """Options for exec calls within commands."""
+
+    cwd: str
+    """Working directory for the exec."""
+
+    env: dict[str, str] | None = None
+    """Environment variables to merge."""
+
+
+@dataclass
+class CommandContext:
+    """Context provided to command execution."""
+
+    fs: IFileSystem
+    """Virtual filesystem interface."""
+
+    cwd: str
+    """Current working directory."""
+
+    env: dict[str, str]
+    """Environment variables."""
+
+    stdin: str = ""
+    """Standard input content."""
+
+    limits: ExecutionLimits | None = None
+    """Execution limits configuration."""
+
+    exec: Optional[Callable[[str, dict[str, Any]], Awaitable[ExecResult]]] = None
+    """Execute a subcommand (for xargs, bash -c, etc.)."""
+
+    fetch: Optional[Any] = None
+    """Secure fetch function for network requests (for curl)."""
+
+    get_registered_commands: Optional[Callable[[], list[str]]] = None
+    """Returns names of all registered commands (for help)."""
+
+    sleep: Optional[Callable[[float], Awaitable[None]]] = None
+    """Custom sleep implementation for testing."""
+
+
+class Command(Protocol):
+    """Protocol for command implementations."""
+
+    name: str
+
+    async def execute(self, args: list[str], ctx: CommandContext) -> ExecResult:
+        """Execute the command with given arguments and context."""
+        ...

just_bash-0.1.5.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: just-bash
+Version: 0.1.5
+Summary: A pure Python bash interpreter with in-memory virtual filesystem
+Project-URL: Homepage, https://github.com/dbreunig/just-bash-py
+Project-URL: Repository, https://github.com/dbreunig/just-bash-py
+Author: Drew Breunig
+License-Expression: Apache-2.0
+Keywords: bash,interpreter,sandbox,shell,virtual-filesystem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: markdownify>=0.11
+Requires-Dist: nest-asyncio>=1.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# just-bash-py (pre-release)
+
+[![PyPI version](https://badge.fury.io/py/just-bash.svg)](https://pypi.org/project/just-bash/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+A pure Python bash interpreter with an in-memory virtual filesystem, designed for AI agents needing a secure, sandboxed bash environment.
+
+This is a Python port of [just-bash](https://github.com/vercel-labs/just-bash), the emulated bash interpreter for TypeScript, from Vercel.
+
+**This is a pre-release.** This as much a demonstration of coding agents' ability to implement software given a tight spec and high test coverage, as [discussed here](https://www.dbreunig.com/2026/01/08/a-software-library-with-no-code.html) and [here](https://github.com/dbreunig/whenwords).
+
+## Features
+
+- **Pure Python** - No external binaries, no WASM dependencies
+- **Flexible filesystems** - In-memory, real filesystem access, copy-on-write overlays, or mount multiple sources
+- **70+ commands** - grep, sed, awk, jq, curl, and more
+- **Full bash syntax** - Pipes, redirections, variables, arrays, functions, control flow
+- **32 shell builtins** - cd, export, declare, test, and more
+- **Async execution** - Built on asyncio for non-blocking operation
+- **Security limits** - Prevent infinite loops, excessive recursion, runaway execution
+
+## Installation
+
+```bash
+pip install just-bash
+```
+
+## Quick Start
+
+```python
+from just_bash import Bash
+
+bash = Bash()
+
+# Simple command
+result = await bash.exec('echo "Hello, World!"')
+print(result.stdout)  # Hello, World!
+
+# Pipes and text processing
+result = await bash.exec('echo "banana apple cherry" | tr " " "\\n" | sort')
+print(result.stdout)  # apple\nbanana\ncherry\n
+
+# Variables and arithmetic
+result = await bash.exec('x=5; echo $((x * 2))')
+print(result.stdout)  # 10
+
+# Arrays
+result = await bash.exec('arr=(a b c); echo "${arr[@]}"')
+print(result.stdout)  # a b c
+
+# In-memory files
+result = await bash.exec('echo "test" > /tmp/file.txt; cat /tmp/file.txt')
+print(result.stdout)  # test
+```
+
+A synchronous `bash.run()` wrapper is also available and works in any context, including Jupyter notebooks.
+
+## Demo
+
+Run the interactive demo to see all features in action:
+
+```bash
+python examples/demo.py
+```
+
+This demonstrates variables, arrays, control flow, pipes, text processing, JSON handling with jq, functions, and more.
+
+## API
+
+### Bash Class
+
+```python
+from just_bash import Bash
+
+# Create with optional initial files
+bash = Bash(files={
+    "/data/input.txt": "line1\nline2\nline3\n",
+    "/config.json": '{"key": "value"}'
+})
+
+# Execute commands
+result = await bash.exec("cat /data/input.txt | wc -l")
+
+# Result object
+print(result.stdout)     # Standard output
+print(result.stderr)     # Standard error
+print(result.exit_code)  # Exit code (0 = success)
+```
+
+### Configuration Options
+
+```python
+bash = Bash(
+    files={...},           # Initial filesystem contents
+    env={...},             # Environment variables
+    cwd="/home/user",      # Working directory
+    network=NetworkConfig(...),  # Network configuration (for curl)
+)
+```
+
+### Filesystem Options
+
+just-bash provides four filesystem implementations for different use cases:
+
+#### InMemoryFs (Default)
+
+Pure in-memory filesystem - completely sandboxed with no disk access.
+
+```python
+from just_bash import Bash
+
+# Default: in-memory filesystem with optional initial files
+bash = Bash(files={
+    "/data/input.txt": "hello world\n",
+    "/config.json": '{"key": "value"}'
+})
+
+result = await bash.exec("cat /data/input.txt")
+print(result.stdout)  # hello world
+```
+
+#### ReadWriteFs
+
+Direct access to the real filesystem, rooted at a specific directory. All paths are translated relative to the root.
+
+```python
+from just_bash import Bash
+from just_bash.fs import ReadWriteFs, ReadWriteFsOptions
+
+# Access real files under /path/to/project
+fs = ReadWriteFs(ReadWriteFsOptions(root="/path/to/project"))
+bash = Bash(fs=fs, cwd="/")
+
+# /src/main.py in bash maps to /path/to/project/src/main.py on disk
+result = await bash.exec("cat /src/main.py")
+```
+
+**Warning**: ReadWriteFs provides direct disk access. Use with caution.
+
+#### OverlayFs
+
+Copy-on-write overlay - reads from the real filesystem, but all writes go to an in-memory layer. The real filesystem is never modified.
+
+```python
+from just_bash import Bash
+from just_bash.fs import OverlayFs, OverlayFsOptions
+
+# Overlay real files at /home/user/project, changes stay in memory
+fs = OverlayFs(OverlayFsOptions(
+    root="/path/to/real/project",
+    mount_point="/home/user/project"
+))
+bash = Bash(fs=fs)
+
+# Read real files
+result = await bash.exec("cat /home/user/project/README.md")
+
+# Writes only affect the in-memory layer
+await bash.exec("echo 'modified' > /home/user/project/README.md")
+# Real file on disk is unchanged!
+```
+
+Use cases:
+- Safe experimentation with real project files
+- Testing scripts without modifying actual files
+- AI agents that need to read real code but not write to disk
+
+#### MountableFs
+
+Mount multiple filesystems at different paths, similar to Unix mount points.
+
+```python
+from just_bash import Bash
+from just_bash.fs import (
+    MountableFs, MountableFsOptions, MountConfig,
+    InMemoryFs, ReadWriteFs, ReadWriteFsOptions, OverlayFs, OverlayFsOptions
+)
+
+# Create a mountable filesystem with multiple sources
+fs = MountableFs(MountableFsOptions(
+    base=InMemoryFs(),  # Default for paths outside mounts
+    mounts=[
+        # Mount real project at /project (read-write)
+        MountConfig(
+            mount_point="/project",
+            filesystem=ReadWriteFs(ReadWriteFsOptions(root="/path/to/project"))
+        ),
+        # Mount another project as overlay (read-only to disk)
+        MountConfig(
+            mount_point="/reference",
+            filesystem=OverlayFs(OverlayFsOptions(
+                root="/path/to/other/project",
+                mount_point="/"
+            ))
+        ),
+    ]
+))
+
+bash = Bash(fs=fs)
+
+# Access different filesystems through unified paths
+await bash.exec("ls /project")      # Real filesystem
+await bash.exec("ls /reference")    # Overlay filesystem
+await bash.exec("ls /tmp")          # In-memory (base)
+```
+
+#### Direct Filesystem Access
+
+You can also access the filesystem directly through the `bash.fs` property:
+
+```python
+import asyncio
+from just_bash import Bash
+
+bash = Bash(files={"/data.txt": "initial content"})
+
+# Async filesystem operations
+async def main():
+    # Read
+    content = await bash.fs.read_file("/data.txt")
+
+    # Write
+    await bash.fs.write_file("/output.txt", "new content")
+
+    # Check existence
+    exists = await bash.fs.exists("/data.txt")
+
+    # List directory
+    files = await bash.fs.readdir("/")
+
+    # Get file stats
+    stat = await bash.fs.stat("/data.txt")
+    print(f"Size: {stat.size}, Mode: {oct(stat.mode)}")
+
+asyncio.run(main())
+```
+
+## Security
+
+- **No native execution** - All commands are pure Python implementations
+- **Network disabled by default** - curl requires explicit enablement
+- **Execution limits** - Prevents infinite loops and excessive resource usage
+- **Filesystem isolation** - Virtual filesystem keeps host system safe
+- **SQLite sandboxed** - Only in-memory databases allowed
+
+## Supported Features
+
+### Shell Syntax
+- Variables: `$VAR`, `${VAR}`, `${VAR:-default}`, `${VAR:+alt}`, `${#VAR}`
+- Arrays: `arr=(a b c)`, `${arr[0]}`, `${arr[@]}`, `${#arr[@]}`
+- Arithmetic: `$((expr))`, `((expr))`, increment/decrement, ternary
+- Quoting: Single quotes, double quotes, `$'...'`, escapes
+- Expansion: Brace `{a,b}`, tilde `~`, glob `*.txt`, command `$(cmd)`
+- Control flow: `if/then/else/fi`, `for/do/done`, `while`, `until`, `case`
+- Functions: `func() { ... }`, local variables, return values
+- Pipes: `cmd1 | cmd2 | cmd3`
+- Redirections: `>`, `>>`, `<`, `2>&1`, here-docs
+
+### Parameter Expansion
+- Default values: `${var:-default}`, `${var:=default}`
+- Substring: `${var:offset:length}`
+- Pattern removal: `${var#pattern}`, `${var##pattern}`, `${var%pattern}`, `${var%%pattern}`
+- Replacement: `${var/pattern/string}`, `${var//pattern/string}`
+- Case modification: `${var^^}`, `${var,,}`, `${var^}`, `${var,}`
+- Length: `${#var}`, `${#arr[@]}`
+- Indirection: `${!var}`, `${!prefix*}`, `${!arr[@]}`
+- Transforms: `${var@Q}`, `${var@a}`, `${var@A}`
+
+### Conditionals
+- Test command: `[ -f file ]`, `[ "$a" = "$b" ]`
+- Extended test: `[[ $var == pattern ]]`, `[[ $var =~ regex ]]`
+- Arithmetic test: `(( x > 5 ))`
+- File tests: `-e`, `-f`, `-d`, `-r`, `-w`, `-x`, `-s`, `-L`
+- String tests: `-z`, `-n`, `=`, `!=`, `<`, `>`
+- Numeric tests: `-eq`, `-ne`, `-lt`, `-le`, `-gt`, `-ge`
+
+## Shell Builtins
+
+```
+:         .         [         alias     break     builtin   cd        command
+continue  declare   eval      exec      exit      export    false     let
+local     mapfile   readarray readonly  return    set       shift     shopt
+source    test      true      type      typeset   unalias   unset     wait
+```
+
+## Available Commands
+
+### File Operations
+```
+cat       chmod     cp        find      ln        ls        mkdir     mv
+rm        stat      touch     tree
+```
+
+### Text Processing
+```
+awk       column    comm      cut       diff      expand    fold      grep
+egrep     fgrep     head      join      nl        od        paste     rev
+rg        sed       sort      split     strings   tac       tail      tee
+tr        unexpand  uniq      wc
+```
+
+### Data Processing
+```
+jq        yq        xan       sqlite3
+```
+
+#### xan - CSV Toolkit
+
+The `xan` command provides CSV manipulation capabilities. Most commands are implemented:
+
+**Implemented:**
+```
+headers     count       head        tail        slice       select
+drop        rename      filter      search      sort        reverse
+behead      enum        shuffle     sample      dedup       top
+cat         transpose   fixlengths  flatten     explode     implode
+split       view        stats       frequency   to json     from json
+```
+
+**Not Yet Implemented** (require expression evaluation):
+```
+join        agg         groupby     map         transform   pivot
+```
+
+Example usage:
+```python
+# Show column names
+await bash.exec("xan headers data.csv")
+
+# Filter and select
+await bash.exec("xan filter 'age > 30' data.csv | xan select name,age")
+
+# Convert to JSON
+await bash.exec("xan to json data.csv")
+
+# Sample random rows
+await bash.exec("xan sample 10 --seed 42 data.csv")
+```
+
+### Path Utilities
+```
+basename  dirname   pwd       readlink  which
+```
+
+### Compression & Encoding
+```
+base64    gzip      gunzip    zcat      md5sum    sha1sum   sha256sum tar
+```
+
+### System & Environment
+```
+alias     clear     date      du        echo      env       expr      false
+file      help      history   hostname  printenv  printf    read      seq
+sleep     timeout   true      unalias   xargs
+```
+
+### Network
+```
+curl      (disabled by default)
+```
+
+### Shell
+```
+bash      sh
+```
+
+## License
+
+Apache 2.0
+
+## Backlog
+
+Future improvements under consideration:
+
+- **Separate sync/async implementations**: Replace the current `nest_asyncio`-based `run()` wrapper with a truly synchronous implementation. This would follow the pattern used by libraries like httpx (`Client` vs `AsyncClient`) and the OpenAI SDK, providing cleaner separation without event loop patching.
+
+## Acknowledgments
+
+This project is a Python port of [just-bash](https://github.com/vercel-labs/just-bash) by Vercel. The TypeScript implementation provided the design patterns, test cases, and feature specifications that guided this Python implementation.