Metadata-Version: 2.2
Name: pepm
Version: 0.3.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
Requires-Dist: uv>=0.8
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 python install 3.11.9
pepm python list
pepm python remove 3.11.9
pepm doctor
pepm install
pepm run main.py
pepm list
pepm track --port 8000
pepm track --host 0.0.0.0 --port 8000 --watch-ms 750
```

The PyPI package installs and uses `uv` as its runtime backend, so Python versions are downloaded as prebuilt managed distributions instead of compiled locally. `pepm python <version>` and `pepm use <version>` select that version, update `.python-version` and `pepm.json`, and rebuild `.venv` when its interpreter changes. Native packages without uv keep the pinned pyenv implementation as a compatibility fallback.

Pyenv builds most CPython releases from source. Run `pepm doctor` to check for Git, Make, curl, and a C compiler before installing a version. Operating-system development libraries may still be required for complete Python builds.

`pepm install` creates `.venv` from the selected pepm-managed Python 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, `flow.toml`, and `.venv` in the current directory. Existing `main.py` files are never overwritten.
On a minimal system without `python3`, initialization bootstraps managed Python 3.12.3; otherwise it starts from the available system Python version and installs the matching managed interpreter.

`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 expandable mind map rooted at `main`, revealing only direct calls at each depth
- an animated per-function statement flow with editable example inputs
- project-local function execution with typed JSON arguments and captured output
- 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.3.0 .
```
