rpr-cli 0.1.1__py3-none-any.whl

rpr/scaffolds/special_files/domain_container.md

@@ -0,0 +1,76 @@
+## Domain Container Template
+
+Target path: `packages/python/domain/src/{name_underscore}_domain/config/container.py`
+
+Use this template when scaffolding the domain DI container. It wires the core infrastructure providers — database engine and HTTP client — as singletons driven by `Settings`.
+
+The first Python block is the generated file used by `rpr generate domain` and `rpr add template domain_container`.
+
+```python
+from __future__ import annotations
+
+import httpx
+from dependency_injector import containers, providers
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from your_app_domain.config.settings import Settings
+
+
+class Container(containers.DeclarativeContainer):
+    wiring_config = containers.WiringConfiguration(modules=[])
+
+    config = providers.Singleton(Settings)
+
+    db_engine = providers.Singleton(
+        lambda settings: create_async_engine(
+            settings.database_url,
+            echo=settings.db_echo,
+            pool_pre_ping=True,
+            pool_recycle=3600,
+        ),
+        settings=config,
+    )
+
+    http_client = providers.Singleton(
+        httpx.AsyncClient,
+        timeout=config.provided.http_timeout,
+        limits=providers.Factory(
+            httpx.Limits,
+            max_connections=config.provided.httpx_max_connections,
+            max_keepalive_connections=config.provided.http_max_keepalive,
+        ),
+    )
+
+    # To add lifecycle methods (startup/shutdown hooks), override __new__:
+    #
+    #   def __new__(cls):
+    #       instance = super().__new__(cls)
+    #       return add_lifecycle_methods(instance)
+    #
+    # Implement add_lifecycle_methods() in this module to attach
+    # startup and shutdown handlers to the container instance.
+```
+
+## What This Template Provides
+
+- `config`: a singleton `Settings` instance that reads from `.env`.
+- `db_engine`: a singleton async SQLAlchemy engine built from `settings.database_url`, with connection-pool tuning defaults (`pool_pre_ping`, `pool_recycle`).
+- `http_client`: a singleton `httpx.AsyncClient` with timeout and connection limits sourced from `Settings`.
+
+## Lifecycle Extension Pattern
+
+If the project needs startup or shutdown hooks (e.g., acquiring a connection pool, registering signal handlers), override `__new__` on `Container`:
+
+```python
+def __new__(cls):
+    instance = super().__new__(cls)
+    return add_lifecycle_methods(instance)
+```
+
+Define `add_lifecycle_methods(instance)` in the same module to attach `on_startup` and `on_shutdown` handlers without modifying the provider declarations.
+
+## Usage Notes
+
+- Register new services and repositories as providers directly on `Container`; do not subclass it.
+- Inject the container into FastAPI (or the framework of your choice) via its `wire()` method in the app factory.
+- Keep transport-specific clients (e.g., third-party API clients) as additional `providers.Singleton` entries, bound to `config` for their credentials.

rpr/scaffolds/special_files/domain_settings.md

@@ -0,0 +1,57 @@
+## Domain Settings Template
+
+Target path: `packages/python/domain/src/{name_underscore}_domain/config/settings.py`
+
+Use this template when scaffolding the domain configuration layer. It provides a Pydantic `BaseSettings` class that loads from `.env` and defines all core infrastructure settings needed by the DI container.
+
+The first Python block is the generated file used by `rpr generate domain` and `rpr add template domain_settings`.
+
+```python
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    db_host: str = Field(default="localhost", description="Database host")
+    db_port: int = Field(default=5432, description="Database port")
+    db_name: str = Field(default="postgres", description="Database name")
+    db_user: str = Field(default="postgres", description="Database user")
+    db_password: str = Field(default="", description="Database password")
+    db_sslmode: str = Field(default="prefer", description="Database SSL mode")
+    db_echo: bool = Field(default=False, description="Enable SQL query logging")
+    db_encrypt_key: bytes | None = Field(default=None, description="Fernet encryption key")
+
+    http_timeout: float = Field(default=30.0, description="HTTP client timeout in seconds")
+    httpx_max_connections: int = Field(default=100, description="Maximum HTTP connections")
+    http_max_keepalive: int = Field(default=20, description="Maximum keepalive HTTP connections")
+
+    @property
+    def database_url(self) -> str:
+        return (
+            f"postgresql+asyncpg://{self.db_user}:{self.db_password}"
+            f"@{self.db_host}:{self.db_port}/{self.db_name}"
+            f"?sslmode={self.db_sslmode}"
+        )
+```
+
+## What This Template Provides
+
+- Reads all settings from `.env` with `case_sensitive=False` and `extra="ignore"` so unknown keys never raise errors.
+- Defines the full set of database fields used to build `database_url` in the `@property`.
+- Defines `http_timeout`, `httpx_max_connections`, and `http_max_keepalive` so the container's `http_client` provider can bind them without extra lookups.
+- `db_encrypt_key` is `bytes | None` to pair with the `encrypted_column` utility when needed.
+
+## Usage Notes
+
+- Add corresponding keys to `.env.example` for each field (see `special_files.md` ENV section).
+- Extend `Settings` in the domain package to add app-specific fields; do not modify this base set.
+- `database_url` is a computed property — it is not read from `.env` directly.

rpr/scaffolds/special_files/dto_util.md

@@ -0,0 +1,62 @@
+## DTO Helper Template
+
+Target path: `/packages/python/domain/src/{name_underscore}_domain/utils/dto_util.py`
+
+Use this helper when the same DTO mapper should support both a single entity and a list of entities without requiring separate functions.
+
+The first Python block is the generated file used by `rpr add template dto_util`.
+
+```python
+from functools import wraps
+from typing import Any, Callable, overload
+
+class DtoHelper[ModelType, R]:
+    """A smart DTO helper that can convert a single entity or a list of entities to DTO(s) without requiring separate functions."""
+    def __init__(self, to_dto_func: Callable[[ModelType], R]):
+        self.to_dto_func = to_dto_func
+        wraps(to_dto_func)(self)
+
+    @overload
+    def __call__(self, model: ModelType, *args, **kwargs) -> R: ...
+
+    @overload
+    def __call__(self, model: list[ModelType], *args, **kwargs) -> list[R]: ...
+
+    def __call__(self, model: Any, *args, **kwargs) -> Any:
+        if isinstance(model, list):
+            return [
+                self.to_dto_func(*m, *args, **kwargs)
+                if isinstance(m, tuple)
+                else self.to_dto_func(m, *args, **kwargs)
+                for m in model
+            ]
+        return self.to_dto_func(model, *args, **kwargs)
+
+def dto_helper[ModelType, R](to_dto_func: Callable[[ModelType], R]) -> DtoHelper[ModelType, R]:
+    return DtoHelper(to_dto_func)
+```
+
+## Why This Exists
+
+- It removes repeated `[to_dto(item) for item in items]` boilerplate.
+- It keeps the mapper call site the same whether the caller has one entity or many.
+- It pairs naturally with repository and service code that already works with ORM models.
+
+### Usage
+
+```python
+from your_app_domain.utils.dto_util import dto_helper
+from your_app_domain.models.entities import User
+from your_app_domain.models.dtos import UserDTO
+
+# Define a function that converts a model to a DTO
+@dto_helper
+def user_to_dto(user: User) -> UserDTO:
+    return UserDTO(id=user.id, name=user.name)
+
+# Convert a single user
+dto = user_to_dto(user)
+
+# Convert a list of users
+dtos = user_to_dto([user1, user2, user3])
+```

rpr/scaffolds/special_files/encrypted_column.md

@@ -0,0 +1,98 @@
+## Encrypted Column Template
+
+Target path: `/packages/python/domain/src/{name_underscore}_domain/utils/encrypted_column.py`
+
+Use this template when a SQLModel field must be stored encrypted at rest without changing the rest of the model or repository code.
+
+Dependency: `uv add cryptography`
+
+The first Python block is the generated file used by `rpr add template encrypted_column`.
+
+```python
+import json
+from typing import Any
+
+from cryptography.fernet import Fernet
+from sqlalchemy import Column
+from sqlalchemy.types import TypeDecorator
+from sqlmodel import Field, SQLModel
+from sqlmodel.sql.sqltypes import AutoString
+
+def _get_fernet_key() -> bytes:
+    """
+    Return the Fernet encryption key.
+
+    Replace this with your project's settings / secret manager lookup.
+    return b"your-fernet-key-here"
+    """
+    # Important this is sample or temp code, the key should not come from env but from a secure secret manager, like GCP, Doppler, AWS Secrets Manager, etc.
+    import os
+    key = os.environ.get("FERNET_KEY")
+    if key is None:
+        raise RuntimeError("FERNET_KEY environment variable is not set")
+    return key.encode()
+
+class EncryptedColumn(TypeDecorator):
+    """
+    SQLAlchemy column type that transparently encrypts and decrypts values using Fernet symmetric encryption.
+
+    Stores the encrypted value as a string in the database.
+    Supports any JSON serializable Python value (str, dict, list, int, etc.).
+
+    Usage in a SQLModel:
+
+    class MyModel(SQLModel, table=True):
+        api_token: str | None = Field(
+          default=None,
+          sa_column=Column(EncryptedColumn())
+        )
+
+    """
+    impl = AutoString(length=1000)
+    cache_ok = True
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._fernet = Fernet(_get_fernet_key())
+
+    def process_bind_param(self, value: Any, dialect) -> str | None:
+        """
+        Encrypt the value before storing it in the database.
+        """
+        if value is None:
+            return None
+        try:
+            json_value = json.dumps(value)
+            encrypted = self._fernet.encrypt(json_value.encode("utf-8"))
+            return encrypted.decode("utf-8")
+        except Exception as e:
+            raise ValueError(f"Error encrypting value: {e}")
+
+    def process_result_value(self, value: str | None, dialect) -> Any:
+        """
+        Decrypt the value when loading it from the database.
+        """
+        if value is None:
+            return None
+        try:
+            decrypted_value = self._fernet.decrypt(value.encode("utf-8"))
+            return json.loads(decrypted_value.decode("utf-8"))
+        except Exception as e:
+            # log error
+            # Return None if decryption fails, we don't want the app to crash unless the consumer needs it to crash
+            return None
+```
+
+## Security Notes
+
+- Replace `_get_fernet_key()` with the project's real secret-loading path before using this in production.
+- Prefer a secrets manager over environment variables for long-lived deployments.
+- Decide whether decryption failures should return `None`, be logged, or raise loudly based on the sensitivity of the consuming workflow.
+
+## Key Generation
+
+```python
+from cryptography.fernet import Fernet
+key = Fernet.generate_key().decode()
+# Store in secrets manager
+```

rpr/scaffolds/special_files/mapper_util.md

@@ -0,0 +1,159 @@
+## Mapper Utility Template
+
+Target path: `/packages/python/domain/src/{name_underscore}_domain/utils/mapper_util.py`
+
+Use this template when repository methods should support both raw ORM access and deferred DTO conversion through `.to_dto()`.
+
+The first Python block is the generated file used by `rpr add template mapper_util`.
+
+```python
+from __future__ import annotations
+import inspect
+from functools import wraps
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Awaitable,
+    Callable,
+    Concatenate,
+    cast,
+    overload
+)
+
+if TYPE_CHECKING:
+    from your_app_domain.repos import BaseRepo # Another special file
+
+class Mapper[RepoResult, DtoResult]:
+    """
+    Wraps a repository coroutine and provides deferred DTO conversion.
+    - Await the mapper directly to get the raw ORM result.
+    - Call `.to_dto()` on the mapper to get the converted DTO result.
+    """
+    def __init__(self, coro: Awaitable[RepoResult], dto_func: Callable[[RepoResult], DtoResult]):
+        self._coro = coro
+        self._dto_func = dto_func
+
+    def __await__(self):
+        return self._coro.__await__()
+
+    async def to_dto(self) -> DtoResult | None:
+        obj = await self._coro
+        if obj is None:
+            return None
+
+        if isinstance(obj, tuple):
+            actual_func = inspect.unwrap(self._dto_func)
+            sig = inspect.signature(actual_func)
+            params = list(sig.parameters.values())
+            if len(params) == 1:
+                return self._dto_func(obj)
+            else:
+                return self._dto_func(*obj)
+
+        return self._dto_func(obj)
+
+@overload
+def mapper[Repo, RepoResult, **P](
+    method: Callable[Concatenate[Repo, P], Awaitable[RepoResult]],
+) -> Callable[Concatenate[Repo, P], Mapper[RepoResult, Any]]: ...
+
+@overload
+def mapper[Repo, RepoResult, DtoResult, **P](
+    *,
+    dto_func: Callable[[RepoResult], DtoResult],
+) -> Callable[
+    [Callable[Concatenate[Repo, P], Awaitable[RepoResult]]],
+    Callable[Concatenate[Repo, P], Mapper[RepoResult, DtoResult]],
+]: ...
+
+def mapper(
+    method: Callable[..., Awaitable[Any]] | None = None,
+    *,
+    dto_func: Callable[[Any], Any] | None = None,
+):
+    """
+    Decorator for repository methods that returns a Mapper instance.
+
+    The Mapper can then be:
+     - awaited directly -> returns the raw ORM result
+        - call .to_dto() -> returns the converted DTO result
+
+     use @mapper alone to use the repository's default dto_func
+     use @mapper(dto_func=your_custom_dto_func) to override the default dto_func for that specific method.
+
+     Examples:
+       @mapper
+       async def get_by_id(self, id: str) -> TEntity | None:
+
+       @mapper(dto_func=custom_dto_func)
+       async def get_by_id_custom(self, id: str) -> dict[str, TEntity] | None:
+    """
+    def decorate_with_default[Repo, RepoResult, **P](
+        func: Callable[Concatenate[Repo, P], Awaitable[RepoResult]],
+    ) -> Callable[Concatenate[Repo, P], Mapper[RepoResult, Any]]:
+        @wraps(func)
+        def wrapper(
+            self: BaseRepo, *args: P.args, **kwargs: P.kwargs
+        ) -> Mapper[RepoResult, Any]:
+            return Mapper(func(self, *args, **kwargs), self.dto_func)
+        return wrapper
+
+    if method is not None:
+        return decorate_with_default(method)
+
+    def decorator[Repo, RepoResult, DtoResult, **P](
+        func: Callable[Concatenate[Repo, P], Awaitable[RepoResult]],
+    ) -> Callable[Concatenate[Repo, P], Mapper[RepoResult, DtoResult]]:
+        if dto_func is None:
+            raise ValueError("dto_func must be provided when using @mapper(...)")
+        typed_dto_func = cast(Callable[[RepoResult], DtoResult], dto_func)
+
+        @wraps(func)
+        def wrapper(
+            self: BaseRepo, *args: P.args, **kwargs: P.kwargs
+        ) -> Mapper[RepoResult, DtoResult]:
+            return Mapper(func(self, *args, **kwargs), typed_dto_func)
+
+        return wrapper
+
+    return decorator
+```
+
+Usage
+
+```python
+from your_app_domain.repos import BaseRepo
+from your_app_domain.utils import mapper
+from your_app_domain.models.entities import SomeEntity
+from your_app_domain.models.dtos import some_entity_to_dto, custom_dto_func
+
+class MyRepo(BaseRepo[SomeEntity]):
+    def __init__(self, engine):
+        super().__init__(SomeEntity, engine, some_entity_to_dto) # Pass the default DTO conversion function
+
+    @mapper
+    async def get_by_id(self, id: str) -> SomeEntity | None:
+        ...
+
+    @mapper(dto_func=custom_dto_func)
+    async def get_by_id_custom(self, id: str) -> dict[str, SomeEntity] | None:
+        ...
+
+# Usage
+repo = MyRepo(engine)
+result = await repo.get_by_id("some_id")  # Returns raw ORM result
+dto_result = await repo.get_by_id("some_id").to_dto()  # Returns DTO result
+custom_dto_result = await repo.get_by_id_custom("some_id").to_dto()  # Returns custom DTO result
+```
+
+## What This Template Solves
+
+- Repository callers can choose between awaiting the raw ORM result and calling `.to_dto()` when they need mapped DTOs.
+- The repository keeps a default mapper while still allowing per-method overrides.
+- Tuple results are supported for methods that return composite values into a mapper function.
+
+## Usage Notes
+
+- Use `@mapper` on repository methods that should expose `.to_dto()`.
+- Use `@mapper(dto_func=...)` only when a method needs a different mapping strategy than the repository default.
+- Pair this with `dto_util` when the DTO mapper itself should support both single values and lists.

rpr/scaffolds/special_files/partial_update.md

@@ -0,0 +1,61 @@
+## Partial Update Utility Template
+
+Target path: `/packages/python/domain/src/{name_underscore}_domain/utils/partial_update.py`
+
+Use this helper when a PATCH-style DTO should update only the fields that were explicitly provided by the caller.
+
+The first Python block is the generated file used by `rpr add template partial_update`.
+
+```python
+from __future__ import annotations
+from typing import TypeVar
+from my_app_domain.models.entities import BaseEntity
+from pydantic import BaseModel
+
+EntityT = TypeVar("EntityT", bound="BaseEntity")
+EXCLUDED_FIELDS = frozenset({'id', 'created_at', 'updated_at', 'created_by', 'updated_by'})
+
+def apply_partial_update(entity: EntityT, partial_dto: BaseModel, *, field_mapping: dict[str, str] | None = None) -> EntityT:
+    """
+    Apply explicitly set fields from a partial update DTO onto the current Entity.
+    Iterates over model_fields_set (only fields explicitly included in the request payload),
+    excluding id, created_at, and updated_at, and sets the corresponding attribute on current_entity.
+    Fields absent from the payload are left unchanged.
+
+    When field names differ between the DTO and the Entity, provide a field_mapping dict mapping DTO field name => entity attribute name.
+    entity: The ORM entity to update.
+    partial_dto: The Pydantic model containing the fields to update.
+    field_mapping: Optional dictionary mapping DTO field names to entity attribute names.
+
+    Returns:
+      The same entity instance, mutated in place.
+    """
+    field_mapping = field_mapping or {}
+
+    for field_name in partial_dto.model_fields_set:
+        if field_name in EXCLUDED_FIELDS:
+            continue
+
+        value = getattr(partial_dto, field_name)
+        target_attr = field_mapping.get(field_name, field_name)
+        setattr(entity, target_attr, value)
+    return entity
+```
+
+### Usage:
+
+```python
+# PATCH endpoint handler
+async def update_user(id: str, body: UpdateUserDto) -> UserDto:
+    user = await repo.get_user_by_id(id)
+    user = apply_partial_update(user, body)
+
+#with field names mismatch
+apply_partial_update(entity, dto, field_mapping={"displayName": "name"})
+```
+
+## Notes
+
+- The helper mutates the existing entity in place and returns that same instance for convenience.
+- `model_fields_set` ensures omitted fields are left untouched.
+- Use `field_mapping` when DTO field names and entity attribute names differ.

rpr/templates/registry.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TemplateEntry:
+    id: str
+    description: str
+    source_filename: str
+    source_subdir: str
+    target_path: str
+    language: str
+
+
+TEMPLATES: dict[str, TemplateEntry] = {
+    "mapper_util": TemplateEntry(
+        id="mapper_util",
+        description="Mapper decorator for repo methods with DTO conversion",
+        source_filename="mapper_util.md",
+        source_subdir="special_files",
+        target_path="packages/python/domain/src/{name_underscore}_domain/utils/mapper_util.py",
+        language="python",
+    ),
+    "dto_util": TemplateEntry(
+        id="dto_util",
+        description="DtoHelper for single/list entity-to-DTO conversion",
+        source_filename="dto_util.md",
+        source_subdir="special_files",
+        target_path="packages/python/domain/src/{name_underscore}_domain/utils/dto_util.py",
+        language="python",
+    ),
+    "partial_update": TemplateEntry(
+        id="partial_update",
+        description="apply_partial_update utility for PATCH endpoints",
+        source_filename="partial_update.md",
+        source_subdir="special_files",
+        target_path="packages/python/domain/src/{name_underscore}_domain/utils/partial_update.py",
+        language="python",
+    ),
+    "encrypted_column": TemplateEntry(
+        id="encrypted_column",
+        description="SQLAlchemy EncryptedColumn TypeDecorator using Fernet",
+        source_filename="encrypted_column.md",
+        source_subdir="special_files",
+        target_path="packages/python/domain/src/{name_underscore}_domain/utils/encrypted_column.py",
+        language="python",
+    ),
+    "domain_settings": TemplateEntry(
+        id="domain_settings",
+        description="Pydantic BaseSettings with .env loading and DB/HTTP fields",
+        source_filename="domain_settings.md",
+        source_subdir="special_files",
+        target_path="packages/python/domain/src/{name_underscore}_domain/config/settings.py",
+        language="python",
+    ),
+    "domain_container": TemplateEntry(
+        id="domain_container",
+        description="Dependency Injector Container with db_engine and http_client providers",
+        source_filename="domain_container.md",
+        source_subdir="special_files",
+        target_path="packages/python/domain/src/{name_underscore}_domain/config/container.py",
+        language="python",
+    ),
+    "sticky_navigation": TemplateEntry(
+        id="sticky_navigation",
+        description="useStateNavigation React hook for URL-based state",
+        source_filename="sticky-navigation.md",
+        source_subdir="js_special_files",
+        target_path="packages/node/{name}-ui/src/hooks/useStateNavigation.ts",
+        language="typescript",
+    ),
+    "fetch_service": TemplateEntry(
+        id="fetch_service",
+        description="Centralized API service with auth, error handling, fetch",
+        source_filename="fetch.service.md",
+        source_subdir="js_special_files",
+        target_path="packages/node/{name}-ui/src/services/base/api.service.ts",
+        language="typescript",
+    ),
+}

rpr/ui/console.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import sys
+
+from rich.console import Console
+from rpr.ui.theme import theme_manager
+
+
+def get_console() -> Console:
+    return Console(theme=theme_manager.get_theme(), color_system="auto")
+
+
+# Shared console instance
+# Note: In a real app, you might want to re-initialize this if the theme changes
+console = get_console()
+
+
+def refresh_console():
+    """Refresh the shared console instance with the current theme."""
+    global console
+    console = get_console()
+
+    for module_name in (
+        "rpr.ui.markdown",
+        "rpr.ui.renderers",
+        "rpr.context",
+        "rpr.commands.chat",
+        "rpr.commands.settings",
+    ):
+        module = sys.modules.get(module_name)
+        if module is not None:
+            setattr(module, "console", console)