Metadata-Version: 2.4
Name: binarybyte
Version: 0.3.1
Summary: Infrastructure layer for AI coding agents — evaluate, sync, and deploy agent configs across tools.
Project-URL: Homepage, https://github.com/BinaryByte-project/BinaryByte
Project-URL: Repository, https://github.com/BinaryByte-project/BinaryByte
Project-URL: Issues, https://github.com/BinaryByte-project/BinaryByte/issues
Author: BinaryByte Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,cli,deployment,evaluation,infrastructure
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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 :: Build Tools
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: docker>=7.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: sandbox
Requires-Dist: docker>=7.0.0; extra == 'sandbox'
Description-Content-Type: text/markdown

# BinaryByte

[![CI](https://github.com/Aryannovice/BinaryByte/actions/workflows/ci.yml/badge.svg)](https://github.com/Aryannovice/BinaryByte/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/binarybyte.svg)](https://pypi.org/project/binarybyte/)
[![Python](https://img.shields.io/pypi/pyversions/binarybyte.svg)](https://pypi.org/project/binarybyte/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**BinaryByte is CI/CD for AI coding agents**: evaluate agent-proposed diffs, version shared agent state, and deploy verified rules to multiple targets (Cursor, Gemini CLI, Claude Code, Windsurf, Copilot, plus plugins).

**Current version:** 0.3.0

---

## Why BinaryByte

When you switch between editors and agents, rules and context drift. It’s also easy to merge risky diffs.

BinaryByte gives you:

- **Eval** — run checks on a patch file or a `git diff` range; write a **verdict** + a **state snapshot** per version label.
- **State** — keep one canonical `state.yaml` (memory + conventions) that can be deployed everywhere.
- **Deploy (gated)** — render that state into each tool’s native file format **only if** the chosen version’s verdict **passed**.

---

## Quickstart (60 seconds)

```bash
pip install binarybyte
binarybyte init .
binarybyte state add --key "stack" --value "Python 3.11, pytest"
binarybyte eval run --git-range HEAD~1..HEAD --version demo-1
binarybyte deploy run --version demo-1
```

---

## Install

```bash
pip install binarybyte
binarybyte --version
```

Optional extras:

- `pip install "binarybyte[sandbox]"` (Docker-based sandbox eval)
- `pip install "binarybyte[all]"`

From source (development):

```bash
git clone https://github.com/Aryannovice/BinaryByte.git
cd BinaryByte
pip install -e ".[dev]"
pytest
ruff check .
```

> Sandbox evaluation uses the Docker CLI when enabled in config.

---

## CLI commands (quick reference)

Global help:

```bash
binarybyte --help
binarybyte state --help
binarybyte eval --help
binarybyte deploy --help
```

Setup:

- Create `.binarybyte/`: `binarybyte init` (or `binarybyte init path/to/project`)

State:

- Add memory: `binarybyte state add --key K --value "V" [--source manual]`
- List entries: `binarybyte state list`
- List snapshots: `binarybyte state snapshots`
- Compare snapshots: `binarybyte state diff --from v1 --to v2`
- Restore state from snapshot: `binarybyte state rollback --version v1`

Eval:

- Evaluate a patch file: `binarybyte eval run --diff changes.patch [--version v1]`
- Evaluate a git range: `binarybyte eval run --git-range HEAD~1..HEAD [--version v1]`

Deploy:

- Deploy current state (defaults to latest verdict): `binarybyte deploy run [--version latest|v1]`
- Deploy from a previous snapshot: `binarybyte deploy rollback --version v1`
- Show deploy history: `binarybyte deploy history`
- List available targets (built-ins + plugins): `binarybyte deploy targets`

---

## Use in CI

BinaryByte is CI-friendly: `binarybyte eval run` exits non-zero when the verdict fails, so it can gate merges/releases.

Example:

```bash
binarybyte init .
binarybyte eval run --git-range "$BASE_SHA...$HEAD_SHA" --version "pr-123"
```

---

## What gets written on disk

After `init`, BinaryByte writes per project:

```
.binarybyte/
  config.yaml
  state.yaml
  results/<version>/verdict.json
  results/<version>/state_snapshot.yaml
  deploy_log.json
  plugins/*.py
  checks/*.py
```

---

## Deploy targets

Built-in deploy targets (when listed in `agents.targets` in `.binarybyte/config.yaml`):

| Target id | Output |
|-----------|--------|
| `cursor` | `.cursor/rules/binarybyte.mdc` |
| `gemini-cli` | `GEMINI.md` |
| `claude-code` | `CLAUDE.md` |
| `windsurf` | `.windsurfrules` |
| `copilot` | `.github/copilot-instructions.md` |

See the config template in `examples/sample-config.yaml`.

---

## Built-in evaluation (summary)

- **Safety** — denied command patterns + denied paths + optional secret scanning.
- **Imports** — flags new third-party imports that don’t resolve.
- **Secrets** — scans added lines for API-key-like patterns (configurable).
- **Plugins** — add custom checks under `.binarybyte/checks/`.
- **Sandbox (optional)** — run commands in a Docker container against a temp project copy with the patch applied.

---

## Plugins

Deploy adapters:

- Drop Python files into `.binarybyte/plugins/` that subclass `BaseAdapter`.
- See `examples/plugin_example.py`.

Eval checks:

- Add Python files under `.binarybyte/checks/` exposing `check(diff_text, config) -> CheckResult`.

---

## Extending to new tools

Agent tools change frequently. BinaryByte is designed so new targets can be added **without** changing the core package.

The recommended approach is:

1. Add a deploy adapter as a **project-local plugin** under `.binarybyte/plugins/`.
2. Add its `NAME` to `agents.targets` in `.binarybyte/config.yaml`.

See `examples/plugin_example.py` for a working adapter template.

### Requesting a new built-in target

If you want BinaryByte to support a new tool out of the box, open an issue with:

- Tool name + website/docs link
- Exact output file path(s) it expects
- Required format (Markdown/YAML/JSON) and a minimal example
- Any constraints (max size, headings, frontmatter, etc.)

We usually start by shipping it as a plugin adapter first, then promote it to a built-in target once it’s stable.

---

## Releasing (maintainers)

1. Bump the version in `pyproject.toml`.
2. Tag and push `vX.Y.Z`.
3. GitHub Actions builds, validates (`twine check`), and publishes to PyPI via OIDC (Trusted Publishing).

---

## Contributing

Contributions are welcome—new adapters, new checks, docs, and examples.

- Run `pytest -q` and `ruff check .` before opening a PR.
- Keep PRs focused and add tests where practical.

See `CONTRIBUTING.md` for the full dev workflow.

---

## License

MIT — see [LICENSE](LICENSE).
