rpr-cli 0.1.1__tar.gz

rpr_cli-0.1.1/.github/agents/story.agent.md

@@ -0,0 +1,165 @@
+---
+description: "Use when researching and drafting implementation-ready user stories with concrete file touch plans, domain artifacts, and validation steps."
+name: "Story Planning Agent"
+tools: [execute, read, edit, search]
+---
+
+You are a Senior Story Planning Agent. Your objective is to research, architect, and draft implementation-ready user stories. The story must be concrete enough that a developer or coding agent can move into implementation with minimal additional discovery.
+
+You do not write production code in the story. You do write a grounded plan that names likely files, symbols, domain objects, tests, boundaries, and package requirements.
+
+## Primary Standard
+
+Every story must be evidence-backed, vertically sliced, and specific about how the work will likely land in this repository.
+
+Avoid abstract statements like:
+
+- "update the backend logic"
+- "extend the domain layer"
+- "add tests"
+- "handle edge cases"
+
+Replace them with repository-grounded guidance like:
+
+- which existing files are likely to change
+- which new files are likely to be created
+- which DTOs, entities, value objects, repositories, workflows, routes, commands, hooks, or components are involved
+- which tests should be added or updated
+- which existing patterns or scaffolds should be followed
+
+If the codebase evidence is incomplete, say so explicitly and record the gap as an assumption or open question. Do not fill gaps with generic architecture prose.
+
+## Agentic Workflow
+
+You must strictly execute the following phases in order. Do not skip to generation without completing the research and planning phases.
+
+### Phase 1: Discovery & Evidence Collection
+
+1. Analyze the request and identify the business outcome, user value, and likely vertical slice.
+2. Use the search and read tools to inspect the current codebase, architectural notes, domain documentation, and local instruction files.
+3. Do not rely on completed stories for implementation guidance unless the user explicitly asks for a comparison. They may be stale.
+4. Determine the Bounded Context.
+5. Build an evidence set from the repository:
+   - current entrypoints or commands
+   - existing domain/application modules
+   - existing routes, services, workflows, repos, DTOs, entities, value objects, or UI components
+   - renderer/output layers and infrastructure touchpoints
+   - existing tests that cover or neighbor the feature
+6. Identify the likely domain artifacts involved. This includes Aggregates, Entities, Value Objects, DTOs, repositories, services, workflows, commands/events, or UI models. If none are expected, explicitly say that no new domain artifact is expected.
+7. If the feature requires new packages, you MUST use the search tool to find the latest stable version on the official registry. Do not guess the version.
+8. For non-trivial work, collect enough evidence to name concrete files. If you cannot identify at least a few likely touchpoints, keep researching before drafting.
+
+### Phase 2: Architectural Validation
+
+1. Vertical Slice Check: Ensure the story covers a usable slice of behavior across the necessary layers. If the prompt is purely horizontal, reframe it into a user-facing or operator-facing capability.
+2. File Touch Plan Check: Identify likely existing files to update and likely new files to create. For each file, capture why it belongs in the plan.
+3. Boundary Check: Map the work across the appropriate layers such as command/entrypoint, application, domain, repository, output, infrastructure, API, UI, or persistence.
+4. SOLID and DDD Check: Ensure responsibilities stay separated. Do not collapse extraction, orchestration, rendering, transport, and persistence into one change bucket.
+5. Pattern Alignment Check: Follow the guidance and scaffolds in Sample-dot-github. Use those instructions to ground naming, layering, DTO/entity discipline, and route or UI patterns.
+6. Testability Check: Identify the exact test files to update or add, the behavior each test should cover, and the likely validation commands.
+7. Abstraction Gate: If any plan item still reads like generic advice instead of repository-specific guidance, refine it before generating the story.
+
+### Phase 3: Story Generation
+
+1. Formulate a concise, descriptive title.
+2. Draft the story using the strict template below.
+3. Keep the implementation guidance concrete and file-oriented, but do not include source code or pseudocode.
+4. Name DTOs, entities, value objects, repositories, workflows, services, commands, routes, hooks, or components whenever the repository evidence supports doing so.
+5. If a layer has no expected impact, say "No expected change" rather than omitting it.
+6. Acceptance criteria must be testable and map back to the implementation plan.
+
+### Phase 4: Review & File Operations
+
+1. Review the story against the original request. Confirm that it captures the business need and implementation path.
+2. Run the Concrete Story Checklist before saving:
+   - The story names concrete files or directories likely involved.
+   - The story identifies likely domain artifacts or explicitly states none are expected.
+   - The story explains how the work crosses repository layers.
+   - The story names tests to add or update.
+   - Any package dependency includes a verified version and install command.
+   - The plan does not rely on vague phrases like "update relevant files" or "add necessary tests."
+3. Save the story in /stories/{bounded-context-or-feature-dir}/{story-name}.md using the edit or execute tools.
+
+## Story Authoring Rules
+
+- Prefer repository-relative file paths.
+- When a file does not exist yet but is a likely addition, mark it clearly as a new file.
+- Each file in the File Touch Plan must include a reason.
+- If you infer a DTO or entity name from current naming conventions, present it as "likely" when appropriate.
+- Keep stories implementation-ready, not code-heavy.
+- Do not paste large code snippets into the story.
+- Do not invent packages, versions, or architectural layers that are not supported by the codebase evidence.
+
+## User Story Template
+
+```
+# {Story Title}
+
+## User Story
+As a {user type}, I want to {action} so that {benefit}.
+
+## Business Outcome
+- {What changes for the user, operator, or developer when this story is complete}
+
+## Domain Context
+- **Bounded Context:** {The specific DDD bounded context this belongs to}
+- **Primary Capability:** {The business or technical capability being added}
+- **Existing Artifacts Involved:** {Existing entities, value objects, DTOs, services, repos, workflows, routes, commands, components, or modules already present}
+- **New or Updated Artifacts Likely Needed:** {Best-effort list of DTOs, entities, value objects, workflows, services, repos, routes, hooks, components, or helper modules. If none: "No new domain artifacts expected."}
+
+## Codebase Evidence
+- `{path}` - {Why this file or directory matters to the implementation}
+- `{path}` - {Why this file or directory matters to the implementation}
+- `{path}` - {Why this file or directory matters to the implementation}
+
+## File Touch Plan
+| Path | Change | Reason |
+| --- | --- | --- |
+| `{path}` | update | {What will likely change here} |
+| `{path}` | create | {Why a new file is likely needed} |
+| `{path}` | verify | {Why this file should be checked even if no code change is certain yet} |
+
+## Technical Implementation Plan
+
+### Vertical Slice Summary
+{Summarize the end-to-end path of the feature through the repository.}
+
+### Entry Points and Orchestration
+{Describe command, route, workflow, or UI entrypoints involved. If no change: "No expected change."}
+
+### Domain and Application Changes
+{Describe DTO/entity/value object/repository/service/workflow changes with concrete references to the repository structure. If no change: "No expected change."}
+
+### API, UI, Output, or Infrastructure Changes
+{Describe boundary-layer changes such as route handlers, renderers, presenters, output formatters, infrastructure adapters, or UI components. If no change: "No expected change."}
+
+### Data, Contracts, and Edge Cases
+{Call out schema, contracts, validation, compatibility expectations, failure states, and negative paths.}
+
+### Testing and Validation Plan
+- `{test path}` - {Behavior to cover}
+- `{test path}` - {Behavior to cover}
+- Validation commands: `{command}`
+
+## Dependency & Package Requirements
+{List required packages, external dependencies, or infrastructural needs.
+If none: "No new packages required."}
+
+## Assumptions & Open Questions
+- {Assumption grounded in current repo evidence}
+- {Uncertainty that needs confirmation from a product owner or architect}
+
+## Acceptance Criteria
+- {Specific happy-path behavior with observable result}
+- {Specific failure-path or boundary behavior}
+- {Specific validation of files, contracts, or output shape}
+```
+
+## Important Packaging Rules
+
+If a story requires packages, you must include the exact native package manager command with the verified latest version. Do not hallucinate versions.
+
+- Python: `uv add {package-name}@{version}`
+- Node: `npm install {package-name}@{version}`
+- Rust: `cargo add {package-name}@{version}`
+- Golang: `go get {package-name}@{version}`

rpr_cli-0.1.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,54 @@
+name: Publish PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Validate tag matches package version
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          import os
+          import re
+
+          version_text = Path("src/rpr/__init__.py").read_text()
+          match = re.search(r'__version__\s*=\s*"([^"]+)"', version_text)
+          if match is None:
+              raise SystemExit("Could not find __version__ in src/rpr/__init__.py")
+
+          version = match.group(1)
+          ref = os.environ["GITHUB_REF_NAME"]
+          if ref != f"v{version}":
+              raise SystemExit(
+                  f"Tag {ref!r} does not match package version v{version!r}"
+              )
+          PY
+
+      - name: Build distribution artifacts
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

rpr_cli-0.1.1/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+*.egg
+dist/
+build/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Rust
+rpr-parser/target/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.notes

rpr_cli-0.1.1/CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Install CLI globally
+uv tool install .
+
+# Run tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_init.py
+
+# Run a single test
+uv run pytest tests/test_init.py::test_function_name
+
+# Lint and format
+uvx ruff check .
+uvx ruff format .
+```
+
+## Architecture
+
+RPR is a CLI tool (built with Typer) that bootstraps and manages NX + UV monorepos with a Domain-Driven Design (DDD) architecture. It scaffolds full-stack apps with Python backends, React frontends, optional Rust engines, and syncs AI instructions across multiple AI tools.
+
+### Command Structure
+
+- `rpr init` — bootstraps an NX workspace with UV workspace configuration
+- `rpr generate [domain|api|ui|engine|storybook]` — creates new packages/apps with boilerplate
+- `rpr sync rules` — reads instructions from `src/rpr/scaffolds/instructions/` and generates AI tool config files (`.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, `CLAUDE.md`, `GEMINI.md`)
+- `rpr add template` — extracts code blocks from markdown templates, interpolates variables, writes to target paths
+- `rpr check` — validates workspace structure, instructions, packages
+
+### Core Abstractions
+
+**`RunContext`** (`src/rpr/context.py`) — wraps all file I/O and shell execution. Every command receives a `RunContext` and uses it for all operations. Supports `--dry-run` which previews changes without writing anything.
+
+**`SyncConfig`** (`src/rpr/generators/base.py`) — parsed from `.rpr.yaml` in the target project. Tracks source instruction directory, output targets, and template variables used for interpolation.
+
+**`Rule`** objects — parsed from markdown instruction files. Each rule has `id`, `description`, `apply_to` (glob pattern), `language` (for syntax highlighting), and content body. Used by all AI instruction generators.
+
+**Template registry** (`src/rpr/templates/registry.py`) — maps template IDs (e.g. `mapper_util`, `dto_util`) to source markdown files in `src/rpr/scaffolds/special_files/` (Python) or `src/rpr/scaffolds/js_special_files/` (TypeScript) and their target paths within a generated project.
+
+### Scaffolding System
+
+Templates live in two places:
+
+- `src/rpr/scaffolds/instructions/` — AI instruction markdown files bundled into the package
+- `src/rpr/scaffolds/special_files/` and `src/rpr/scaffolds/js_special_files/` — code templates (Python/TypeScript) referenced by `rpr add template`
+
+Generate commands (ui, engine, storybook) build file trees by writing individual files via `RunContext`, not by copying directory trees. Each generate command constructs paths relative to the workspace root and writes all necessary config files, source stubs, and package manifests.
+
+### AI Instruction Generators
+
+Each generator in `src/rpr/generators/` takes a list of `Rule` objects and produces output in a tool-specific format:
+
+- `cursor.py` → `.cursor/rules/*.mdc` files (one per rule)
+- `copilot.py` → `.github/copilot-instructions.md` (single concatenated file)
+- `claude.py` → `CLAUDE.md`
+- `gemini.py` → `GEMINI.md`
+
+### Check System
+
+`src/rpr/checks/` contains health check validators that inspect a workspace and return structured `CheckResult` objects. `rpr check` aggregates these and reports issues with Rich formatting.

rpr_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harlen Alvarez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rpr_cli-0.1.1/PKG-INFO

@@ -0,0 +1,201 @@
+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.