rhiza 0.8.8__py3-none-any.whl → 0.9.1__py3-none-any.whl

rhiza/__init__.py

@@ -1,6 +1,6 @@
 """Rhiza — Manage reusable configuration templates for Python projects.
 
-Rhiza is a command‑line interface (CLI) that helps you maintain consistent
+Rhiza is a command-line interface (CLI) that helps you maintain consistent
 configuration across multiple Python projects using templates stored in a
 central repository. It can initialize projects with standard configuration,
 materialize (inject) template files into a target repository, and validate the
@@ -11,8 +11,8 @@ template configuration.
 - Template initialization for new or existing projects.
 - Template materialization with selective include/exclude support.
 - Configuration validation (syntax and basic semantics).
-- Multi‑host support (GitHub and GitLab).
-- Non‑destructive updates by default, with an explicit `--force` flag.
+- Multi-host support (GitHub and GitLab).
+- Non-destructive updates by default, with an explicit `--force` flag.
 
 ## Quick start
 
@@ -29,7 +29,7 @@ Validate your configuration:
 rhiza validate
 ```
 
-Customize `.github/rhiza/template.yml`, then materialize templates into your project:
+Customize `.rhiza/template.yml`, then materialize templates into your project:
 
 ```bash
 rhiza materialize

rhiza/__main__.py

@@ -11,7 +11,7 @@ import typer
 from rhiza.cli import app
 
 
-def load_plugins(app: typer.Typer):
+def load_plugins(app: typer.Typer) -> None:
     """Load plugins from entry points."""
     # 'rhiza.plugins' matches the group we defined in rhiza-tools
     plugin_entries = entry_points(group="rhiza.plugins")

rhiza/cli.py

@@ -5,6 +5,7 @@ Commands are thin wrappers around implementations in `rhiza.commands.*`.
 """
 
 from pathlib import Path
+from typing import Annotated
 
 import typer
 
@@ -13,6 +14,7 @@ from rhiza.commands import init as init_cmd
 from rhiza.commands import materialize as materialize_cmd
 from rhiza.commands import validate as validate_cmd
 from rhiza.commands.migrate import migrate as migrate_cmd
+from rhiza.commands.summarise import summarise as summarise_cmd
 from rhiza.commands.uninstall import uninstall as uninstall_cmd
 from rhiza.commands.welcome import welcome as welcome_cmd
 
@@ -21,14 +23,14 @@ app = typer.Typer(
         """
         Rhiza - Manage reusable configuration templates for Python projects
 
-        \x1b]8;;https://jebel-quant.github.io/rhiza-cli/\x1b\\https://jebel-quant.github.io/rhiza-cli/\x1b]8;;\x1b\\
+        https://jebel-quant.github.io/rhiza-cli/
         """
     ),
     add_completion=True,
 )
 
 
-def version_callback(value: bool):
+def version_callback(value: bool) -> None:
     """Print version information and exit.
 
     Args:
@@ -52,7 +54,7 @@ def main(
         callback=version_callback,
         is_eager=True,
     ),
-):
+) -> None:
     """Rhiza CLI main callback.
 
     This callback is executed before any command. It handles global options
@@ -65,13 +67,15 @@ def main(
 
 @app.command()
 def init(
-    target: Path = typer.Argument(
-        default=Path("."),  # default to current directory
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        help="Target directory (defaults to current directory)",
-    ),
+    target: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            help="Target directory (defaults to current directory)",
+        ),
+    ] = Path("."),
     project_name: str = typer.Option(
         None,
         "--project-name",
@@ -93,10 +97,20 @@ def init(
         help="Target Git hosting platform (github or gitlab). Determines which CI/CD files to include. "
         "If not provided, will prompt interactively.",
     ),
-):
-    r"""Initialize or validate .github/rhiza/template.yml.
+    template_repository: str = typer.Option(
+        None,
+        "--template-repository",
+        help="Custom template repository (format: owner/repo). Defaults to 'jebel-quant/rhiza'.",
+    ),
+    template_branch: str = typer.Option(
+        None,
+        "--template-branch",
+        help="Custom template branch. Defaults to 'main'.",
+    ),
+) -> None:
+    r"""Initialize or validate .rhiza/template.yml.
 
-    Creates a default `.github/rhiza/template.yml` configuration file if one
+    Creates a default `.rhiza/template.yml` configuration file if one
     doesn't exist, or validates the existing configuration.
 
     The default template includes common Python project files.
@@ -108,6 +122,8 @@ def init(
       rhiza init
       rhiza init --git-host github
       rhiza init --git-host gitlab
+      rhiza init --template-repository myorg/my-templates
+      rhiza init --template-repository myorg/my-templates --template-branch develop
       rhiza init /path/to/project
       rhiza init ..
     """
@@ -117,18 +133,22 @@ def init(
         package_name=package_name,
         with_dev_dependencies=with_dev_dependencies,
         git_host=git_host,
+        template_repository=template_repository,
+        template_branch=template_branch,
     )
 
 
 @app.command()
 def materialize(
-    target: Path = typer.Argument(
-        default=Path("."),  # default to current directory
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        help="Target git repository (defaults to current directory)",
-    ),
+    target: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            help="Target git repository (defaults to current directory)",
+        ),
+    ] = Path("."),
     branch: str = typer.Option("main", "--branch", "-b", help="Rhiza branch to use"),
     target_branch: str = typer.Option(
         None,
@@ -137,13 +157,13 @@ def materialize(
         help="Create and checkout a new branch in the target repository for changes",
     ),
     force: bool = typer.Option(False, "--force", "-y", help="Overwrite existing files"),
-):
+) -> None:
     r"""Inject Rhiza configuration templates into a target repository.
 
     Materializes configuration files from the template repository specified
-    in .github/rhiza/template.yml into your project. This command:
+    in .rhiza/template.yml into your project. This command:
 
-    - Reads .github/rhiza/template.yml configuration
+    - Reads .rhiza/template.yml configuration
     - Performs a sparse clone of the template repository
     - Copies specified files/directories to your project
     - Respects exclusion patterns defined in the configuration
@@ -161,17 +181,19 @@ def materialize(
 
 @app.command()
 def validate(
-    target: Path = typer.Argument(
-        default=Path("."),  # default to current directory
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        help="Target git repository (defaults to current directory)",
-    ),
-):
+    target: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            help="Target git repository (defaults to current directory)",
+        ),
+    ] = Path("."),
+) -> None:
     r"""Validate Rhiza template configuration.
 
-    Validates the .github/rhiza/template.yml file to ensure it is syntactically
+    Validates the .rhiza/template.yml file to ensure it is syntactically
     correct and semantically valid.
 
     Performs comprehensive validation:
@@ -196,14 +218,16 @@ def validate(
 
 @app.command()
 def migrate(
-    target: Path = typer.Argument(
-        default=Path("."),  # default to current directory
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        help="Target git repository (defaults to current directory)",
-    ),
-):
+    target: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            help="Target git repository (defaults to current directory)",
+        ),
+    ] = Path("."),
+) -> None:
     r"""Migrate project to the new .rhiza folder structure.
 
     This command helps transition projects to use the new `.rhiza/` folder
@@ -229,7 +253,7 @@ def migrate(
 
 
 @app.command()
-def welcome():
+def welcome() -> None:
     r"""Display a friendly welcome message and explain what Rhiza is.
 
     Shows a welcome message, explains Rhiza's purpose, key features,
@@ -243,20 +267,22 @@ def welcome():
 
 @app.command()
 def uninstall(
-    target: Path = typer.Argument(
-        default=Path("."),  # default to current directory
-        exists=True,
-        file_okay=False,
-        dir_okay=True,
-        help="Target git repository (defaults to current directory)",
-    ),
+    target: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            help="Target git repository (defaults to current directory)",
+        ),
+    ] = Path("."),
     force: bool = typer.Option(
         False,
         "--force",
         "-y",
         help="Skip confirmation prompt and proceed with deletion",
     ),
-):
+) -> None:
     r"""Remove all Rhiza-managed files from the repository.
 
     Reads the `.rhiza.history` file and removes all files that were
@@ -280,3 +306,50 @@ def uninstall(
         rhiza uninstall /path/to/project -y
     """
     uninstall_cmd(target, force)
+
+
+@app.command()
+def summarise(
+    target: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=False,
+            dir_okay=True,
+            help="Target git repository (defaults to current directory)",
+        ),
+    ] = Path("."),
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output file path (defaults to stdout)",
+        ),
+    ] = None,
+) -> None:
+    r"""Generate a summary of staged changes for PR descriptions.
+
+    Analyzes staged git changes and generates a structured PR description
+    that includes:
+
+    - Summary statistics (files added/modified/deleted)
+    - Changes categorized by type (workflows, configs, docs, tests, etc.)
+    - Template repository information
+    - Last sync date
+
+    This is useful when creating pull requests after running `rhiza materialize`
+    to provide reviewers with a clear overview of what changed.
+
+    Examples:
+        rhiza summarise
+        rhiza summarise --output pr-description.md
+        rhiza summarise /path/to/project -o description.md
+
+    Typical workflow:
+        rhiza materialize
+        git add .
+        rhiza summarise --output pr-body.md
+        gh pr create --title "chore: Sync with rhiza" --body-file pr-body.md
+    """
+    summarise_cmd(target, output)

rhiza/commands/__init__.py

@@ -8,7 +8,7 @@ configuration templates for Python projects.
 
 ### init
 
-Initialize or validate `.github/rhiza/template.yml` in a target directory.
+Initialize or validate `.rhiza/template.yml` in a target directory.
 
 Creates a default configuration file if it doesn't exist, or validates
 an existing one. The default configuration includes common Python project
@@ -29,7 +29,7 @@ is used.
 
 Validate Rhiza template configuration.
 
-Validates the `.github/rhiza/template.yml` file to ensure it is syntactically
+Validates the `.rhiza/template.yml` file to ensure it is syntactically
 correct and semantically valid. Performs comprehensive validation including
 YAML syntax checking, required field verification, field type validation,
 and repository format verification.
@@ -50,6 +50,8 @@ For more detailed usage examples and workflows, see the USAGE.md guide
 or try rhiza <command> --help
 """
 
-from .init import init  # noqa: F401
-from .materialize import materialize  # noqa: F401
-from .validate import validate  # noqa: F401
+from .init import init
+from .materialize import materialize
+from .validate import validate
+
+__all__ = ["init", "materialize", "validate"]

rhiza/commands/init.py

@@ -1,7 +1,7 @@
-"""Command to initialize or validate .github/rhiza/template.yml.
+"""Command to initialize or validate .rhiza/template.yml.
 
 This module provides the init command that creates or validates the
-.github/rhiza/template.yml file, which defines where templates come from
+.rhiza/template.yml file, which defines where templates come from
 and what paths are governed by Rhiza.
 """
 
@@ -52,7 +52,7 @@ def _validate_git_host(git_host: str | None) -> str | None:
         git_host = git_host.lower()
         if git_host not in ["github", "gitlab"]:
             logger.error(f"Invalid git-host: {git_host}. Must be 'github' or 'gitlab'")
-            raise ValueError(f"Invalid git-host: {git_host}. Must be 'github' or 'gitlab'")
+            raise ValueError(f"Invalid git-host: {git_host}. Must be 'github' or 'gitlab'")  # noqa: TRY003
     return git_host
 
 
@@ -81,7 +81,7 @@ def _prompt_git_host() -> str:
         git_host = "github"
         logger.debug("Non-interactive mode detected, defaulting to github")
 
-    return git_host
+    return str(git_host)
 
 
 def _get_include_paths_for_host(git_host: str) -> list[str]:
@@ -124,12 +124,19 @@ def _get_include_paths_for_host(git_host: str) -> list[str]:
         ]
 
 
-def _create_template_file(target: Path, git_host: str) -> None:
+def _create_template_file(
+    target: Path,
+    git_host: str,
+    template_repository: str | None = None,
+    template_branch: str | None = None,
+) -> None:
     """Create default template.yml file.
 
     Args:
         target: Target repository path.
         git_host: Git hosting platform.
+        template_repository: Custom template repository (format: owner/repo).
+        template_branch: Custom template branch.
     """
     rhiza_dir = target / ".rhiza"
     template_file = rhiza_dir / "template.yml"
@@ -141,9 +148,20 @@ def _create_template_file(target: Path, git_host: str) -> None:
     logger.debug("Using default template configuration")
 
     include_paths = _get_include_paths_for_host(git_host)
+
+    # Use custom template repository/branch if provided, otherwise use defaults
+    repo = template_repository or "jebel-quant/rhiza"
+    branch = template_branch or "main"
+
+    # Log when custom values are used
+    if template_repository:
+        logger.info(f"Using custom template repository: {repo}")
+    if template_branch:
+        logger.info(f"Using custom template branch: {branch}")
+
     default_template = RhizaTemplate(
-        template_repository="jebel-quant/rhiza",
-        template_branch="main",
+        template_repository=repo,
+        template_branch=branch,
         include=include_paths,
     )
 
@@ -243,10 +261,12 @@ def init(
     package_name: str | None = None,
     with_dev_dependencies: bool = False,
     git_host: str | None = None,
-):
-    """Initialize or validate .github/rhiza/template.yml in the target repository.
+    template_repository: str | None = None,
+    template_branch: str | None = None,
+) -> bool:
+    """Initialize or validate .rhiza/template.yml in the target repository.
 
-    Creates a default .github/rhiza/template.yml file if it doesn't exist,
+    Creates a default .rhiza/template.yml file if it doesn't exist,
     or validates an existing one.
 
     Args:
@@ -256,6 +276,9 @@ def init(
         with_dev_dependencies: Include development dependencies in pyproject.toml.
         git_host: Target Git hosting platform ("github" or "gitlab"). Determines which
             CI/CD configuration files to include. If None, will prompt user interactively.
+        template_repository: Custom template repository (format: owner/repo).
+            Defaults to 'jebel-quant/rhiza'.
+        template_branch: Custom template branch. Defaults to 'main'.
 
     Returns:
         bool: True if validation passes, False otherwise.
@@ -275,7 +298,7 @@ def init(
         git_host = _prompt_git_host()
 
     # Create template file
-    _create_template_file(target, git_host)
+    _create_template_file(target, git_host, template_repository, template_branch)
 
     # Bootstrap Python project structure
     if project_name is None:

rhiza/commands/materialize.py

@@ -8,7 +8,7 @@ into the target Git repository, and records managed files in
 
 import os
 import shutil
-import subprocess
+import subprocess  # nosec B404
 import sys
 import tempfile
 from pathlib import Path
@@ -20,6 +20,22 @@ from rhiza.models import RhizaTemplate
 from rhiza.subprocess_utils import get_git_executable
 
 
+def _log_git_stderr_errors(stderr: str | None) -> None:
+    """Extract and log only relevant error messages from git stderr.
+
+    Args:
+        stderr: Git command stderr output.
+    """
+    if stderr:
+        # Extract relevant error message from git stderr
+        stderr_lines = stderr.strip().split("\n")
+        # Show only the most relevant error lines, skip verbose git output
+        for line in stderr_lines:
+            line = line.strip()
+            if line and (line.startswith("fatal:") or line.startswith("error:")):
+                logger.error(line)
+
+
 def _handle_target_branch(
     target: Path, target_branch: str | None, git_executable: str, git_env: dict[str, str]
 ) -> None:
@@ -37,7 +53,7 @@ def _handle_target_branch(
     logger.info(f"Creating/checking out target branch: {target_branch}")
     try:
         # Check if branch already exists using git rev-parse
-        result = subprocess.run(
+        result = subprocess.run(  # nosec B603
             [git_executable, "rev-parse", "--verify", target_branch],
             cwd=target,
             capture_output=True,
@@ -48,23 +64,29 @@ def _handle_target_branch(
         if result.returncode == 0:
             # Branch exists, switch to it
             logger.info(f"Branch '{target_branch}' exists, checking out...")
-            subprocess.run(
+            subprocess.run(  # nosec B603
                 [git_executable, "checkout", target_branch],
                 cwd=target,
                 check=True,
+                capture_output=True,
+                text=True,
                 env=git_env,
             )
         else:
             # Branch doesn't exist, create it from current HEAD
             logger.info(f"Creating new branch '{target_branch}'...")
-            subprocess.run(
+            subprocess.run(  # nosec B603
                 [git_executable, "checkout", "-b", target_branch],
                 cwd=target,
                 check=True,
+                capture_output=True,
+                text=True,
                 env=git_env,
             )
     except subprocess.CalledProcessError as e:
-        logger.error(f"Failed to create/checkout branch '{target_branch}': {e}")
+        logger.error(f"Failed to create/checkout branch '{target_branch}'")
+        _log_git_stderr_errors(e.stderr)
+        logger.error("Please ensure you have no uncommitted changes or conflicts")
         sys.exit(1)
 
 
@@ -91,6 +113,9 @@ def _validate_and_load_template(target: Path, branch: str) -> tuple[RhizaTemplat
 
     # Extract template configuration settings
     rhiza_repo = template.template_repository
+    if not rhiza_repo:
+        logger.error("template-repository is not configured in template.yml")
+        raise RuntimeError("template-repository is required")  # noqa: TRY003
     rhiza_branch = template.template_branch or branch
     include_paths = template.include
     excluded_paths = template.exclude
@@ -99,7 +124,7 @@ def _validate_and_load_template(target: Path, branch: str) -> tuple[RhizaTemplat
     if not include_paths:
         logger.error("No include paths found in template.yml")
         logger.error("Add at least one path to the 'include' list in template.yml")
-        raise RuntimeError("No include paths found in template.yml")
+        raise RuntimeError("No include paths found in template.yml")  # noqa: TRY003
 
     # Log the paths we'll be including
     logger.info("Include paths:")
@@ -136,7 +161,7 @@ def _construct_git_url(rhiza_repo: str, rhiza_host: str) -> str:
     else:
         logger.error(f"Unsupported template-host: {rhiza_host}")
         logger.error("template-host must be 'github' or 'gitlab'")
-        raise ValueError(f"Unsupported template-host: {rhiza_host}. Must be 'github' or 'gitlab'.")
+        raise ValueError(f"Unsupported template-host: {rhiza_host}. Must be 'github' or 'gitlab'.")  # noqa: TRY003
     return git_url
 
 
@@ -161,7 +186,7 @@ def _clone_template_repository(
     # Clone the repository using sparse checkout
     try:
         logger.debug("Executing git clone with sparse checkout")
-        subprocess.run(
+        subprocess.run(  # nosec B603
             [
                 git_executable,
                 "clone",
@@ -181,16 +206,18 @@ def _clone_template_repository(
         )
         logger.debug("Git clone completed successfully")
     except subprocess.CalledProcessError as e:
-        logger.error(f"Failed to clone repository: {e}")
-        if e.stderr:
-            logger.error(f"Git error: {e.stderr.strip()}")
-        logger.error(f"Check that the repository exists and branch '{rhiza_branch}' is valid")
-        raise
+        logger.error(f"Failed to clone repository from {git_url}")
+        _log_git_stderr_errors(e.stderr)
+        logger.error("Please check that:")
+        logger.error("  - The repository exists and is accessible")
+        logger.error(f"  - Branch '{rhiza_branch}' exists in the repository")
+        logger.error("  - You have network access to the git hosting service")
+        sys.exit(1)
 
     # Initialize sparse checkout in cone mode
     try:
         logger.debug("Initializing sparse checkout")
-        subprocess.run(
+        subprocess.run(  # nosec B603
             [git_executable, "sparse-checkout", "init", "--cone"],
             cwd=tmp_dir,
             check=True,
@@ -200,15 +227,14 @@ def _clone_template_repository(
         )
         logger.debug("Sparse checkout initialized")
     except subprocess.CalledProcessError as e:
-        logger.error(f"Failed to initialize sparse checkout: {e}")
-        if e.stderr:
-            logger.error(f"Git error: {e.stderr.strip()}")
-        raise
+        logger.error("Failed to initialize sparse checkout")
+        _log_git_stderr_errors(e.stderr)
+        sys.exit(1)
 
     # Set sparse checkout paths
     try:
         logger.debug(f"Setting sparse checkout paths: {include_paths}")
-        subprocess.run(
+        subprocess.run(  # nosec B603
             [git_executable, "sparse-checkout", "set", "--skip-checks", *include_paths],
             cwd=tmp_dir,
             check=True,
@@ -218,10 +244,9 @@ def _clone_template_repository(
         )
         logger.debug("Sparse checkout paths configured")
     except subprocess.CalledProcessError as e:
-        logger.error(f"Failed to set sparse checkout paths: {e}")
-        if e.stderr:
-            logger.error(f"Git error: {e.stderr.strip()}")
-        raise
+        logger.error("Failed to configure sparse checkout paths")
+        _log_git_stderr_errors(e.stderr)
+        sys.exit(1)
 
 
 def _copy_files_to_target(

rhiza/commands/migrate.py

@@ -2,7 +2,7 @@
 
 This module implements the `migrate` command. It helps transition projects to use
 the new `.rhiza/` folder structure for storing Rhiza state and configuration files,
-separate from `.github/rhiza/` which contains template configuration.
+separate from `.github/` which contains GitHub-specific configurations.
 """
 
 import shutil