just-bash 0.1.2__tar.gz

just_bash-0.1.2/.gitignore

@@ -0,0 +1,99 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.claude/

just_bash-0.1.2/CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Project Overview
+
+just-bash-py is a Python port of the just-bash TypeScript library - a pure Python bash interpreter with an in-memory virtual filesystem. Designed for AI agents needing a secure, sandboxed bash environment.
+
+## Commands
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_commands/test_commands.py -v
+
+# Run tests matching pattern
+pytest tests/ -v -k "grep"
+
+# Type checking
+mypy src/
+
+# Format code
+ruff format src/ tests/
+ruff check src/ tests/ --fix
+```
+
+## Test-Driven Development (TDD)
+
+**CRITICAL: Always write tests FIRST, before implementing features.**
+
+### TDD Workflow
+
+1. **Write a failing test first** - Define the expected behavior before writing any implementation code
+2. **Run the test and watch it fail** - Verify the test fails for the right reason
+3. **Write minimal code to pass** - Implement just enough to make the test pass
+4. **Refactor** - Clean up while keeping tests green
+5. **Repeat** - Add more tests for edge cases and additional features
+
+### Test Structure
+
+```python
+import pytest
+from just_bash import Bash
+
+class TestNewCommand:
+    """Test new_command implementation."""
+
+    @pytest.mark.asyncio
+    async def test_basic_usage(self):
+        bash = Bash(files={"/input.txt": "content"})
+        result = await bash.exec("new_command /input.txt")
+        assert result.stdout == "expected output\n"
+        assert result.exit_code == 0
+
+    @pytest.mark.asyncio
+    async def test_with_flag(self):
+        bash = Bash(files={"/input.txt": "content"})
+        result = await bash.exec("new_command -f /input.txt")
+        assert result.stdout == "expected with flag\n"
+
+    @pytest.mark.asyncio
+    async def test_error_case(self):
+        bash = Bash()
+        result = await bash.exec("new_command /nonexistent")
+        assert "No such file" in result.stderr
+        assert result.exit_code == 1
+
+    @pytest.mark.asyncio
+    async def test_stdin(self):
+        bash = Bash()
+        result = await bash.exec("echo input | new_command")
+        assert result.stdout == "processed input\n"
+```
+
+### Test Guidelines
+
+- **Assert full stdout/stderr** - Don't use partial matches when exact output is known
+- **Test error cases** - Always test what happens with invalid input
+- **Test stdin** - If the command reads from stdin, test it with pipes
+- **Test flags** - Each flag should have at least one test
+- **Use descriptive test names** - `test_grep_ignore_case_flag` not `test_grep_2`
+
+## Architecture
+
+### Core Pipeline
+
+```
+Input Script → Parser (src/just_bash/parser/) → AST → Interpreter (src/just_bash/interpreter/) → ExecResult
+```
+
+### Key Modules
+
+- **Parser** (`src/just_bash/parser/`): Lexer and recursive descent parser
+- **Interpreter** (`src/just_bash/interpreter/`): AST execution, expansion, builtins
+- **Commands** (`src/just_bash/commands/`): External command implementations
+- **Filesystem** (`src/just_bash/fs/`): In-memory virtual filesystem
+
+### Adding Commands
+
+1. **Write tests first** in `tests/test_commands/test_commands.py`
+2. Run tests to see them fail
+3. Create command in `src/just_bash/commands/<name>/<name>.py`
+4. Add to registry in `src/just_bash/commands/registry.py`
+5. Run tests to see them pass
+
+Command implementation pattern:
+```python
+from ...types import CommandContext, ExecResult
+
+class NewCommand:
+    """The new_command."""
+
+    name = "new_command"
+
+    async def execute(self, args: list[str], ctx: CommandContext) -> ExecResult:
+        # Parse arguments
+        # Execute logic using ctx.fs, ctx.stdin, ctx.cwd, ctx.env
+        return ExecResult(stdout=output, stderr=errors, exit_code=code)
+```
+
+## File Locations
+
+- Commands: `src/just_bash/commands/<name>/<name>.py`
+- Command registry: `src/just_bash/commands/registry.py`
+- Tests: `tests/test_commands/test_commands.py`
+- Parser: `src/just_bash/parser/`
+- Interpreter: `src/just_bash/interpreter/`
+- Types: `src/just_bash/types.py`
+
+## Development Guidelines
+
+- **TDD first** - Write tests before implementation
+- Match real bash behavior, not convenience
+- Keep implementations simple and focused
+- Use `ctx.fs` for all filesystem operations
+- Handle errors gracefully with appropriate exit codes
+- Verify with `pytest tests/ -v` before finishing
+
+## Known Issues
+
+1. **Single-quote variable expansion** - Variables like `$0` are expanded even in single quotes. Workaround: use `-f` to load scripts from files, or escape with `\$`.

just_bash-0.1.2/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: just-bash
+Version: 0.1.2
+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
+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
+- **In-memory filesystem** - Sandboxed virtual filesystem for safe execution
+- **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 = bash.run('echo "Hello, World!"')
+print(result.stdout)  # Hello, World!
+
+# Pipes and text processing
+result = bash.run('echo "banana apple cherry" | tr " " "\\n" | sort')
+print(result.stdout)  # apple\nbanana\ncherry\n
+
+# Variables and arithmetic
+result = bash.run('x=5; echo $((x * 2))')
+print(result.stdout)  # 10
+
+# Arrays
+result = bash.run('arr=(a b c); echo "${arr[@]}"')
+print(result.stdout)  # a b c
+
+# In-memory files
+result = bash.run('echo "test" > /tmp/file.txt; cat /tmp/file.txt')
+print(result.stdout)  # test
+```
+
+For async contexts, use `await bash.exec()` instead of `bash.run()`.
+
+## 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_enabled=False, # Enable/disable network (curl)
+)
+```
+
+## 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
+```
+
+### 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
+
+## 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.

just_bash-0.1.2/README.md

@@ -0,0 +1,204 @@
+# 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
+- **In-memory filesystem** - Sandboxed virtual filesystem for safe execution
+- **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 = bash.run('echo "Hello, World!"')
+print(result.stdout)  # Hello, World!
+
+# Pipes and text processing
+result = bash.run('echo "banana apple cherry" | tr " " "\\n" | sort')
+print(result.stdout)  # apple\nbanana\ncherry\n
+
+# Variables and arithmetic
+result = bash.run('x=5; echo $((x * 2))')
+print(result.stdout)  # 10
+
+# Arrays
+result = bash.run('arr=(a b c); echo "${arr[@]}"')
+print(result.stdout)  # a b c
+
+# In-memory files
+result = bash.run('echo "test" > /tmp/file.txt; cat /tmp/file.txt')
+print(result.stdout)  # test
+```
+
+For async contexts, use `await bash.exec()` instead of `bash.run()`.
+
+## 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_enabled=False, # Enable/disable network (curl)
+)
+```
+
+## 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
+```
+
+### 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
+
+## 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.