Metadata-Version: 2.4
Name: prs-progress-bar
Version: 0.2.0
Summary: Animated PRS progress bars that automatically intercept terminal commands and re-render their real progress.
Author-email: Shrimurali <prsshrimurali@gmail.com>
Keywords: progress,progress-bar,terminal,cli,spinner,interceptor
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# PRS Progress Bar

Animated PRS progress bars that **automatically intercept terminal commands**
and re-render their real progress with a smooth block bar, spinners, stats
and a mandatory credit footer.

Built by **Shrimurali**.

```
⠋ Installing packages...            <- spinner during init phases
████████████░░░░ 78%  12.4MB / 500MB  ⚡ 3.2MB/s  ⏱ ETA 00:12
✓ pip completed

PRS-Progress-Bar built by 'Shrimurali'
```

## What it does

Installing this package registers console scripts that shadow common
terminal commands wherever the Python environment's `Scripts`/`bin`
directory is on your `PATH`:

- **Package managers & web tools**: `pip`, `npm`, `yarn`, `pnpm`, `bun`,
  `cargo`, `composer`, `wget`, `curl`
- **AI tools & CLI utilities**: `ollama`, `git`, `docker`, `prisma`
- **Testing & compilers**: `pytest`, `gcc`, `g++`, `clang`
- **File, archive & media**: `zip`, `unzip`, `tar`, `ffmpeg`, `cp`, `mv`,
  `mkdir`, `rmdir`, `del`, `copy`, `move`

Each wrapper:

1. locates the **real** executable on `PATH` (skipping its own shims, so
   there is no recursion),
2. captures stdout/stderr **in real time** (pseudo-tty on POSIX so tools
   emit progress, pipes on Windows),
3. auto-detects progress frames - `45%`, `12.4MB/500MB`, `[====>   ]`,
   braille spinners - and **suppresses** them,
4. re-renders the progress with the PRS block bar plus stats (speed, byte
   counts, counters, ETA),
5. passes all other output through untouched,
6. prints a `✓` / `✗` status and the credits footer when the command ends.

## Install

```bash
python -m pip install -e .
```

> ⚠️ **Direct shadowing**: because the scripts are named exactly like the
> real commands, any shell where the environment's `Scripts`/`bin` folder is
> first on `PATH` will route `git`, `pip`, `docker`, ... through PRS. Set
> `PRS_DISABLE=1` to bypass interception for a single command, or
> `prs-disable-global` / uninstall to remove everything.

## Usage

```bash
prs git clone https://github.com/octocat/Hello-World.git
prs pip install requests
prs docker pull python:3.12
prs ffmpeg -i in.mp4 out.mp4
prs npm run build
prs wget https://example.com/file.zip
prs --list          # list intercepted commands
```

You can also call the engine programmatically:

```python
from prs_progress_bar.cli import run_intercepted_command
rc = run_intercepted_command(["pip", "install", "requests"])
```

The same commands also work directly (`git clone ...`, `pip install ...`)
thanks to the registered console scripts.

## Enabling global shell hooks

PATH shadowing cannot cover everything:

- **cmd.exe built-ins** (`mkdir`, `rmdir`, `del`, `copy`, `move`) always
  beat PATH executables;
- **PowerShell** prefers aliases/cmdlets (`del`, `copy`, `move`, `cp`,
  `mv`, `mkdir`, `rmdir`, `wget`) over external executables.

Run the hook installer to add per-shell wrappers that send those through
`prs` too:

```bash
prs-enable-global            # auto-detect the current shell
prs-enable-global bash       # or: zsh | powershell | cmd
```

What it installs:

| Shell       | Mechanism                                                                 |
| ----------- | ------------------------------------------------------------------------- |
| bash / zsh  | marker-guarded functions in `~/.bashrc` / `~/.zshrc`                       |
| PowerShell  | functions in `$PROFILE` (and removes the conflicting built-in aliases)     |
| cmd         | doskey macros in `~/.prs-progress-bar/prs-macros.doskey`, registered in the `HKCU\Software\Microsoft\Command Processor` **AutoRun** registry value |

Remove the hooks anytime:

```bash
prs-disable-global [bash|zsh|powershell|cmd]
```

### Hook limitations

- bash/zsh hooks apply only to shells that source the rc files.
- doskey macros apply only to **interactive** cmd.exe sessions, not batch
  files or non-interactive cmd launches.
- PowerShell functions apply to interactive and scripted PowerShell
  sessions that load the profile.
- `g++` is not a valid shell function name, so it is installed as a bash
  alias and a PowerShell `Function:`-drive entry instead (still fully
  intercepted).

## How progress parsing works

A generic stream reader splits captured output on newlines *and* carriage
returns, then classifies each segment:

- `45%`, `[====>   ]`, `⠙` … → progress frame → suppressed, block bar
  rendered with any detected percent / bytes / counters / speed / ETA;
- everything else → echoed through verbatim.

Tool-specific tweaks keep the data flowing:

- `pip` runs with `PIP_PROGRESS_BAR=raw` so downloads emit parseable
  progress even without a tty;
- `curl` gets `--progress-bar` (unless you already passed `-s`/`-#`);
- `git` gets `GIT_PAGER=cat` so pagers never hijack the capture;
- `ffmpeg` never prints a percent, so its `Duration:` / `time=` stderr
  lines are used to derive one (`██████████░░░░ 50%` as it encodes);
- `docker` build step lines like `[+] Building 12.5s (5/12)` drive the bar
  with the `5/12` step counter.

Fully interactive invocations (`ollama run/chat/serve`, `docker exec`,
`docker attach`, `docker run -it`, `git commit` without `-m`) are detected
and run with the real terminal attached - only the credits footer is added
on exit.

## Windows notes

- There is no pseudo-tty for child processes on Windows, so tools that only
  draw progress on a tty (e.g. `wget`, `git clone`'s bar) will simply pass
  through - you still get the spinner, `✓` status and credits.
- `pip` progress is captured even without a tty (see above).
- `cp`/`mv`/`mkdir`/`rmdir`/`del`/`copy`/`move` fall back to `cmd /c` when
  no real binary exists in `PATH`.

## Escape hatch

```bash
PRS_DISABLE=1 git clone https://github.com/octocat/Hello-World.git
```

## Demo commands (legacy)

`remove`, `download` and `ask` are standalone simulations kept for backward
compatibility - they animate fake progress directly, without running a real
tool.
