Metadata-Version: 2.4
Name: binabra
Version: 0.1.0
Summary: Portable bin-directory anchor for shell scripts — use sibling tools from anywhere
Project-URL: Homepage, https://github.com/librarynth2/binabra
Author: librarynth2
License-Expression: MIT
License-File: LICENSE
Keywords: abra,bin,cli,path,scripts,shell
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# binabra

Portable **bin directory anchor** for shell scripts. Install once, reuse the same header anywhere.

- **PyPI:** `binabra`
- **CLI:** `abra` (the spell name stays short)
- **Next in family:** `kadabra` (related tool, coming later)

## Install

```bash
pip install binabra
```

Ensure pip's script dir is on PATH (macOS example):

```bash
export PATH="$HOME/Library/Python/3.9/bin:$PATH"
```

## Use anywhere

At the top of any shell script:

```bash
source "$(abra sh)"
exec "$BIN/my-sibling-tool" "$@"
```

`BIN` becomes the directory **containing your script**.

## Bootstrap a project

```bash
abra init          # creates ./bin/abra
abra colocate bin  # copy abra into existing bin/
```

Co-located scripts:

```bash
source "$(dirname "${BASH_SOURCE[0]}")/abra"
exec "$BIN/other-script" "$@"
```

## CLI

| Command | Purpose |
|---------|---------|
| `abra sh` | Path to `anchor.sh` for sourcing |
| `abra embed` | Print `source "$(abra sh)"` |
| `abra dir` | Discover bin (`ABRA_BIN`, project `bin/`, `~/.local/bin`) |
| `abra exec tool args` | Run sibling from discovered bin |
| `abra init [dir]` | Create `bin/abra` in a project |
| `abra colocate [dest]` | Copy `abra` into a bin folder |

## Publish to PyPI

### 1. Create an API token

https://pypi.org/manage/account/token/

- Scope: **Entire account** (first time) or **Project: binabra** (after first upload)
- Copy the token (`pypi-...`)

### 2. Build

```bash
cd ~/Projects/binabra
python3 -m pip install --user build twine
python3 -m build
```

### 3. Upload

```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-YOUR-TOKEN-HERE
twine upload dist/*
```

Or enter credentials when prompted:

```bash
twine upload dist/*
# username: __token__
# password: pypi-...
```

### 4. Verify

```bash
pip install binabra
abra --version
abra embed
```

PyPI project page: https://pypi.org/project/binabra/

## Python API

```python
from binabra import anchor_dir, sibling, discover_bin

anchor_dir(__file__)
sibling("run.sh", __file__)
discover_bin()
```
