Metadata-Version: 2.3
Name: zush
Version: 2.0.0
Summary: zack's useful dynamic shell
Author: ZackaryW
Author-email: ZackaryW <36378555+ZackaryW@users.noreply.github.com>
Requires-Dist: click>=8.1
Requires-Dist: typer>=0.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# zush

zack's useful dynamic shell — a **static-index command launcher** you extend with plugins.

You declare commands in a plugin; `zush rebuild` / `zush sync` indexes them once into
`~/.zush/*.json`; then `zush a.b.c` imports (Python) or runs (script) only that one
target. No runtime scanning.

## How it works

- Two indexes under `~/.zush/`: `pyindex.json` (Python packages, built by `zush rebuild`)
  and `repoindex.json` (repos, built by `zush sync`).
- Dispatch of `zush a.b.c`: resolve in either index → fire matching `pre` hooks → run the
  command → fire `post` (or `error`) hooks.
- Hooks and services work across **both** plugin types.

## Plugin types & features

| Topic | File |
|---|---|
| Python package plugins (`__zush__.py`) | [docs/python-packages.md](docs/python-packages.md) |
| Repo plugins (committed `.zush/` tree) | [docs/repos.md](docs/repos.md) |
| Commands: the manifest tree & argument parsing | [docs/commands.md](docs/commands.md) |
| Hooks: `pre`/`post`/`error` with `[]` wildcards | [docs/hooks.md](docs/hooks.md) |
| Services: shared `ctx` (config, clients, live servers) | [docs/services.md](docs/services.md) |
| CLI reference & environment variables | [docs/cli.md](docs/cli.md) |
| Why the rewrite (old vs new philosophy) | [docs/philosophy.md](docs/philosophy.md) |

## Install

From source (requires Python ≥ 3.12); installs the `zush` command:

```sh
pip install -e .        # or: uv pip install -e .
```

## Commands

```sh
zush rebuild            # index installed Python-package plugins
zush sync <repo>        # clone/update a repo plugin and index it
zush a.b.c [args]       # run a command
zush --help             # list every indexed command
```

## Develop

```sh
uvx --with typer --with click behave                 # tests (Windows: set PYTHONUTF8=1)
uvx ruff check src features                           # lint
```
