Metadata-Version: 2.4
Name: xadabra
Version: 0.1.0
Summary: Paste-once runner for AI shell blocks with interactive placeholders
Project-URL: Homepage, https://github.com/librarynth2/xadabra
Author: librarynth2
License-Expression: MIT
License-File: LICENSE
Keywords: ai,assistant,cli,paste,placeholder,shell
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# xadabra

Paste-once runner for AI shell blocks. No more hand-editing `{{placeholders}}` in command blocks.

Part of the spell family: **binabra** → **keyabra** → **xadabra**.

## Install

```bash
pip install xadabra
```

## Example

An AI gives you this block:

```bash
#!/bin/zsh
cd {{FOLDER|path:Where is the folder?}}
export API_KEY={{!API_KEY:Paste the API key}}
./deploy.sh
```

Copy it, then:

```bash
xadabra
```

`xadabra` reads your clipboard, prompts once per placeholder (API key hidden), shows a masked preview, asks `Run? [y/N]`, then executes via zsh.

## Placeholder syntax

| Form | Meaning |
|------|---------|
| `{{NAME}}` | Prompt `NAME:` |
| `{{NAME:Question}}` | Custom prompt |
| `{{NAME:Question:default}}` | Default if you press Enter |
| `{{!NAME:Question}}` | Secret (`getpass`, masked in preview) |
| `{{NAME\|path:Question}}` | Must be an existing path (`~`, quotes, `\\ ` unescaped) |

Each unique `NAME` is prompted once and substituted everywhere.

## Usage

```bash
xadabra              # read script from clipboard (pbpaste)
xadabra script.sh    # read from file
xadabra - <<'EOF'    # read from stdin
echo hello {{WHO:Who?}}
EOF

xadabra --dry-run    # preview only
xadabra --yes        # skip confirmation
```

## Safety

- No network, no telemetry
- Optional local history: `~/.xadabra/history.jsonl` (scripts only — **never** placeholder values)
- Secrets masked as `*****` in previews and history

## Publish

```bash
pip install binabra keyabra build twine
cd ~/Projects/xadabra && python3 -m build
keyabra pypi publish
```

## Tests

```bash
cd ~/Projects/xadabra
python3 -m unittest discover -s tests -v
```
