Metadata-Version: 2.2
Name: pepm
Version: 0.1.0
Summary: Python environment, package, code-flow, and Git dashboard manager
Keywords: python,packages,virtualenv,git,code-flow,developer-tools
Author: Rakshit Verma
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# pepm

`pepm` is an experimental C++ package/environment manager for Python projects. It borrows the structured-project idea from `npm`, while keeping the first version small and transparent.

## Build

```sh
cmake -S . -B build
cmake --build build
```

The executable will be at `build/pepm`.

## Commands

```sh
pepm init [name]
pepm add requests 2.32.3
pepm remove requests
pepm use 3.12.5
pepm python 3.12.5
pepm install
pepm run main.py
pepm list
pepm track --port 8000
pepm track --host 0.0.0.0 --port 8000 --watch-ms 750
```

`pepm python <version>` uses `pyenv install -s` when `pyenv` is available, then writes `.python-version` and `pepm.json`. If `pyenv` is not installed, `pepm use <version>` still records the requested version.

`pepm install` creates `.venv` and installs the packages exported to `requirements.txt`.

`pepm run <file.py> [args...]` prepares the environment and then runs Python code. It creates `.venv` when needed, installs `requirements.txt`, then runs with `.venv/bin/python`. Common import/package mismatches are normalized, such as `cv2` or `python-opencv` becoming `opencv-python`.

`pepm init [name]` creates `pepm.json`, `requirements.txt`, `.python-version`, a starter `main.py` when one does not already exist, and `flow.toml`. Existing `main.py` files are never overwritten.

`flow.toml` is the persistent code-understanding model. It records files, imports, functions/classes, line ranges, high-level explanations, calls, source, and rule-based line explanations. It is regenerated only when its generated content changes.

`pepm track` starts an animated tabbed dashboard. It shows:

- the selected Python version
- configured dependencies
- a compact main-function flow for source files
- an architecture board grouped into Entry, Input, Processing, State, Output, and Infrastructure
- file roles, plain-English architecture notes, and dependency explanations
- a searchable function inspector that displays one component at a time
- detected classes/functions, line ranges, signatures, purpose, call sites, and exact source
- optional line-by-line code explanations generated from syntax and operations rather than comments
- function contracts showing parameters, output, side effects, and next project calls
- a separate git-flow tab with create, checkout, merge, abort, resolve, commit, working-tree status, branch graph, and commit timeline
- a merge-conflict tab with conflict marker reasons, browser editing for resolved content, and commit controls

While `pepm track` is running, the dashboard checks for saved source changes and refreshes automatically. The selected tab and function are restored after refresh whenever they still exist.

Use `--no-watch` to disable browser polling. The server binds to `127.0.0.1` by default; use `--host 0.0.0.0` only when the dashboard must be reachable from another machine.

## Packaging

The CMake install target places `pepm` in the selected install prefix's `bin` directory. Debian/Ubuntu packaging instructions and the reproducible Docker build are in [`packaging/README.md`](packaging/README.md). A validated native-architecture package can be produced with:

```sh
docker build -f packaging/Dockerfile.deb -t pepm-deb-builder:0.1.0 .
```
