Metadata-Version: 2.4
Name: mrmd-bash
Version: 0.1.2
Summary: MRP (MRMD Runtime Protocol) server for Bash
Author: MRMD Team
License: MIT
License-File: LICENSE
Keywords: bash,mrmd,mrp,notebook,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Requires-Dist: sse-starlette>=1.6.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.22.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# mrmd-bash

MRP (MRMD Runtime Protocol) server for Bash. Enables notebook-style editors to execute Bash code with persistent sessions, completions, and variable inspection.

## Installation

```bash
pip install mrmd-bash
```

Or with uv:

```bash
uv pip install mrmd-bash
```

## Usage

Start the server:

```bash
mrmd-bash --port 8001
```

The server will be available at `http://localhost:8001/mrp/v1/`.

### Options

```
--host HOST       Host to bind to (default: 127.0.0.1)
--port PORT       Port to bind to (default: 8001)
--cwd PATH        Working directory for bash sessions
--log-level LEVEL Log level: debug, info, warning, error (default: info)
--reload          Enable auto-reload for development
```

## Features

| Feature | Support | Notes |
|---------|---------|-------|
| `execute` | ✅ | Run code and return result |
| `executeStream` | ✅ | Stream output via SSE |
| `interrupt` | ✅ | Cancel running execution (SIGINT) |
| `complete` | ✅ | Completions via compgen |
| `inspect` | ❌ | Not supported |
| `hover` | ✅ | Variable values and command types |
| `variables` | ✅ | Environment and shell variables |
| `variableExpand` | ❌ | Bash variables are flat |
| `reset` | ✅ | Restart bash session |
| `isComplete` | ✅ | Detect incomplete statements |
| `format` | ❌ | Not supported |
| `assets` | ❌ | Not supported |

## API Examples

### Check capabilities

```bash
curl http://localhost:8001/mrp/v1/capabilities
```

### Execute code

```bash
curl -X POST http://localhost:8001/mrp/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "echo Hello, World!"}'
```

### Get completions

```bash
curl -X POST http://localhost:8001/mrp/v1/complete \
  -H "Content-Type: application/json" \
  -d '{"code": "ec", "cursor": 2}'
```

### List variables

```bash
curl -X POST http://localhost:8001/mrp/v1/variables \
  -H "Content-Type: application/json" \
  -d '{"session": "default"}'
```

### Stream execution

```bash
curl -X POST http://localhost:8001/mrp/v1/execute/stream \
  -H "Content-Type: application/json" \
  -d '{"code": "for i in 1 2 3; do echo $i; sleep 1; done"}'
```

## Sessions

Sessions maintain persistent Bash state:
- Environment variables persist between executions
- Working directory changes persist
- Shell functions and aliases persist

```bash
# Create a session
curl -X POST http://localhost:8001/mrp/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"id": "my-session"}'

# Execute in session
curl -X POST http://localhost:8001/mrp/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "export MY_VAR=hello", "session": "my-session"}'

# Variable persists
curl -X POST http://localhost:8001/mrp/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "echo $MY_VAR", "session": "my-session"}'

# Reset session (clear state)
curl -X POST http://localhost:8001/mrp/v1/sessions/my-session/reset

# Delete session
curl -X DELETE http://localhost:8001/mrp/v1/sessions/my-session
```

## Completions

The server provides completions via bash's `compgen`:

- **Commands**: builtins, functions, aliases, executables
- **Files**: paths with `/` prefix
- **Variables**: names with `$` prefix

## Development

```bash
# Clone and install in development mode
git clone <repo>
cd mrmd-bash
pip install -e ".[dev]"

# Run with auto-reload
mrmd-bash --reload

# Run tests
pytest
```

## Protocol

This server implements the [MRMD Runtime Protocol (MRP)](../mrmd-editor/PROTOCOL.md).

## License

MIT
