Metadata-Version: 2.4
Name: rpr-cli
Version: 0.1.1
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

Scaffold a complete monorepo or add new apps and libraries.

```bash
rpr init my-app              # Scaffold a new monorepo (NX + UV)
rpr generate domain my-app   # Add a domain package (shared logic & types)
rpr generate api my-app      # Add a FastAPI application
rpr generate ui my-app       # Add a React UI library + application
rpr generate engine my-app   # Add a Rust/PyO3 computation engine
rpr generate storybook       # Add Storybook for UI component development
```

### 🧠 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 mapper_util # Add a common code template to your project
rpr add template --list      # List all available code templates
```

### 💬 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 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

### ⚙️ 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 generate api my-app --dry-run
```

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. Add a repository secret named `PYPI_API_TOKEN` with an API token that can upload that project.

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.
