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

cmake -S . -B build
cmake --build build

The executable will be at build/pepm.

Commands

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. A validated native-architecture package can be produced with:

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