Metadata-Version: 2.4
Name: rpr-cli
Version: 0.1.28
Summary: RPR CLI -- React Python Rust monorepo scaffolding orchestrator
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: jinja2>=3.1.5
Requires-Dist: pathspec>=1.0.4
Requires-Dist: prompt-toolkit>=3.0.52
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=14.3.3
Requires-Dist: typer>=0.24.1
Description-Content-Type: text/markdown

# RPR CLI

React Python Rust monorepo scaffolding orchestrator.

## Installation

Published package name: `rpr-cli`

Once published to PyPI, install by name with either:

```bash
uv add rpr-cli
uv tool install rpr-cli
```

Both install the `rpr` command.

For development, editable install is fine:

```bash
uv tool install -e .
```

For an actual distributable install you can use in other projects, build the wheel first and install the built artifact:

```bash
uv build
uv tool install dist/rpr_cli-*.whl
```

From another local project you can also install the built artifact directly:

```bash
uv add ../project-getting-started/dist/rpr_cli-*.whl
```

## Usage

### 🚀 Scaffolding & Generation

Create a new NX + UV monorepo, then add apps and packages as needed.

> NX monorepo uses integrated mode.

```bash
rpr init my-app              # Create/init my-app with root NX + UV tooling and AI instructions
cd my-app
rpr generate domain my-app   # Add a Python domain package
rpr generate api my-app      # Add a FastAPI application
rpr generate ui my-app       # Add a React UI library and web app
rpr generate engine my-app   # Add a Rust/PyO3 computation engine
rpr generate storybook       # Add Storybook for UI component development
```

`rpr init <project-name>` creates the project directory when it does not exist. If the directory already exists and is not an NX workspace, RPR initializes Git and runs `nx init` inside that directory.

By default, `rpr init` scaffolds the root workspace and AI instructions only. To create project components during initialization, repeat `--scaffold` or pass a comma-separated list:

```bash
rpr init todo-list --scaffold common
rpr init todo-list --scaffold domain
rpr init todo-list --scaffold api --domain-migrations
rpr init todo-list --scaffold api --scaffold web --domain-migrations
```

Available scaffolds are:

- `common`: Alias for `instructions`, `domain`, `api`, `ui`, `web`, and `storybook`; excludes `engine`.
- `instructions`: AI instruction files for Cursor, Copilot, Claude Code, and Gemini.
- `domain`: Python DDD package at `packages/python/domain`.
- `api`: FastAPI app at `apps/<name>-api`; also scaffolds `domain`.
- `ui`: React UI library at `packages/node/<name>-ui`.
- `web`: React web app at `apps/<name>-web`; also scaffolds `ui`.
- `storybook`: Storybook host package; requires or scaffolds `ui`.
- `engine`: Rust/PyO3 package at `packages/python/<name>-engine`.

### Dependency Placement

RPR keeps dependencies close to the package that uses them.

- Root Python tooling such as Ruff, pytest, pyright, pre-commit, and maturin lives in the root `pyproject.toml`.
- Domain runtime dependencies such as `sqlmodel`, `asyncpg`, `pydantic-settings`, and optional `alembic` are added to `packages/python/domain/pyproject.toml`.
- API runtime dependencies such as `fastapi`, `uvicorn`, and the workspace domain package are added to `apps/<name>-api/pyproject.toml`.
- Node dependencies are written to the relevant package-level `package.json` files, and `npm install` runs from the root workspace.

Python dependency changes are made with `uv` so they are tracked in `pyproject.toml`. Node dependency changes are made through npm workspace package metadata and root `npm install`.

The scaffold version manifest that powers generated dependency specs and the synced AI tech-stack overview lives in `src/rpr/dependency_manifest_data.py`. Refresh it from upstream registries with `rpr refresh manifest` when you want the repo-owned defaults to move forward.

### 🧠 AI Instructions & Code Templates

Sync project context to your favorite AI tools and add common code patterns.

```bash
rpr sync rules                         # Sync AI instructions to Cursor, Copilot, Claude Code, and Gemini
rpr add template python mapper_util    # Add a Python code template to your project
rpr add template node sticky_navigation --include-tests
rpr add template node -l               # List available Node/TSX templates
rpr add template --list                # List all available code templates
```

Use `--output-dir` to write generated files to a different directory while keeping the template filenames. Templates with test companions can use `--include-tests`; Node browser-test templates print the extra npm dev dependencies and any Playwright setup notes they need. Existing config files such as `vitest.config.ts` are not merged automatically; RPR leaves them unchanged unless you rerun with `--force` to replace them.

### 💬 Interactive Shell

`rpr chat` is the primary interactive shell for the product. It runs a Rich-based session with slash commands for both chat controls and existing CLI workflows.

```bash
rpr chat                                 # Start the interactive shell
rpr chat --approval-mode auto-readonly   # Override the session approval mode
```

Inside the shell:

```text
/help        List supported slash commands
/settings    Inspect and update persisted settings in-shell
/init        Run workspace bootstrap from chat
/generate    Run scaffolding commands from chat
/sync        Sync AI instructions from chat
/add         Add a registered template from chat
/check       Run workspace health checks from chat
/map         Generate a code map from chat
/exit        End the session
```

There is no separate `--tui` mode. The unified shell is the default chat experience.

### 🛠️ Maintenance & Insights

Keep your project healthy and explore its structure.

```bash
rpr refresh manifest         # Refresh the scaffold dependency manifest from npm, PyPI, and crates.io
rpr check                    # Inspect project health and report setup status
rpr map                      # Generate a structured code map of your project
rpr settings                 # Inspect persisted shell settings
rpr settings set theme ocean # Update the terminal theme
rpr settings set approval_mode auto-all
rpr settings set startup_help false
```

Persisted settings currently include:

- `theme`: Rich console theme
- `approval_mode`: default chat approval mode (`ask`, `auto-readonly`, `auto-all`)
- `startup_help`: whether chat shows slash-command guidance on startup

`rpr refresh manifest` is a repo-maintenance command. It rewrites `src/rpr/dependency_manifest_data.py`, which feeds scaffold dependency versions in `rpr generate ...` and the versioned overview text produced by `rpr sync rules`. Use `--dry-run` to preview the manifest rewrite without writing the file.

### ⚙️ Common Flags

Most commands support these global flags:

- `--dry-run`: Preview changes without writing any files.
- `--help`: Show detailed help for any command or subcommand.

Example:

```bash
rpr init my-app --scaffold domain --dry-run
rpr generate api my-app --dry-run
```

Dry runs print the commands RPR would execute, the files/directories it would create or update, and the package dependencies it would add with their target scope.

The `check` command also supports:

- `--json`: Output machine-readable JSON for CI/CD integration.

The `chat` command also supports:

- `--provider`: Override the AI provider. The mock provider is the only supported provider today.
- `--model`: Override the active model name.
- `--approval-mode`: Override the session approval mode without changing persisted settings.

### Project Development

#### Setup

```bash
# Install Python dependencies
uv sync

# Build the Rust extension (rpr_parser) — required for rpr map acceleration
cd rpr-parser && uv run maturin develop && cd ..
```

> **Note:** `uv tool install dist/rpr-*.whl` uses the root hatchling build backend and does **not** build the
> Rust extension. You must run `maturin develop` separately before using `rpr map` with the Rust
> backend. Without it, `rpr map` falls back to the pure-Python implementation automatically.

#### Running Tests

```bash
# Full test suite (Python)
uv run pytest

# Single test file
uv run pytest tests/test_map_extractor.py

# Single test
uv run pytest tests/test_map_extractor.py::test_fallback_returns_correct_shape

# Rust unit tests (rpr_parser crate)
cd rpr-parser && cargo test && cd ..

# Lint and format
uv run ruff check .
uv run ruff format .
```

The Rust-path tests in `tests/test_map_extractor.py` are automatically skipped if the Rust
extension hasn't been built yet — run `maturin develop` first to enable them.

### Publishing To PyPI

This repo is set up to publish the package `rpr-cli` to PyPI from GitHub Actions.

One-time setup:

1. Create the PyPI project `rpr-cli`.
2. Create a PyPI Trusted Publisher for this repository using workflow `.github/workflows/publish-pypi.yml` and environment `pypi`.

No `PYPI_API_TOKEN` secret is required when publishing through GitHub Actions OIDC.

Release flow:

```bash
# update src/rpr/__init__.py with the new version
git commit -am "Release 0.1.2"
git tag v0.1.2
git push origin main --tags
```

The workflow in `.github/workflows/publish-pypi.yml` builds the sdist and wheel, checks that the tag matches the package version, and uploads `dist/*` to PyPI.
