Metadata-Version: 2.4
Name: thump
Version: 0.2.0
Summary: Thumper's semantic harness — a structured, event-emitting layer over the Bun runtime (NDJSON events, native-runner promotion)
Author: Thumper Contributors
License: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/New1Direction/thumper
Project-URL: Repository, https://github.com/New1Direction/thumper
Project-URL: Issues, https://github.com/New1Direction/thumper/issues
Keywords: bun,harness,events,ndjson,thumper,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Provides-Extra: dev
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == "dev"
Requires-Dist: build<2.0.0,>=1.0.0; extra == "dev"
Requires-Dist: twine<7.0.0,>=5.0.0; extra == "dev"
Dynamic: license-file

# thump (Thumper Bun harness)

**Semantic harness for Bun** — a clean, observable, agent-native layer over the Bun JavaScript runtime.

Part of the Thumper project (`thump` binary). The Rust side now provides the preferred native execution path.

This Python package provides a structured, event-driven interface for running Bun commands (`bun run`, `bun add`, `bun install`, `bun remove`, etc.) while emitting a stable NDJSON event stream.

It is designed to be used from:
- Command line
- TUI / IDE integrations
- AI agents (via ACP / stdio)

## Features

- **Stable event envelope** — every operation emits structured events (`*.started`, `process.stdout`, `process.exited`, etc.) with `op_id` / `session_id` correlation.
- **Raw output preservation** — stdout/stderr from Bun is never lost.
- **Operation abstraction** — clean success/error paths with normalized error model.
- **Live process streaming** — subprocess execution with real-time event emission.
- **First-class commands**:
  - `script run`
  - `package add` / `install` / `remove`
- Works great from Rust, Python, or directly on the CLI.

## Installation (development)

```bash
git clone https://github.com/New1Direction/thumper.git
cd thumper/thump   # or pip install -e . from the thump/ directory
pip install -e .
```

Or run directly:

```bash
python -m thump --help
```

## Usage

### From Python

```python
from thump import script_run, package_add

result = script_run("dev", cwd="my-project")
result = package_add(["hono", "zod"], cwd="my-project", dev=True)
```

### From CLI

```bash
python -m thump script run dev
python -m thump package add hono --dev
python -m thump package install
```

### Streaming events

All commands emit NDJSON to stdout. Each line is either:

- A structured event (with `event`, `op_id`, `data`, etc.)
- A final result object (`{"ok": true, "operation": "..."}`)

This makes it trivial to consume from Rust, Go, another Python process, or an agent.

## Architecture

```
Bun CLI
   ↓
thump (Python semantic layer)
   ↓
Stable NDJSON event stream + final results
   ↓
Consumers: CLI • TUI Jobs • ACP agents • Rust adapter
```

## Related Projects

- [thumper](https://github.com/New1Direction/thumper) — The Rust TUI/CLI (Thumper) — primary binary with native Bun execution.

## Status

This is the Python-first implementation (Phase 1) as described in the design document.  
A native Rust implementation of the same protocol is planned for later.

## License

MIT
