rhiza 0.8.8__py3-none-any.whl → 0.9.0__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/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
 
@@ -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.",
     ),
+    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'.",
+    ),
 ):
-    r"""Initialize or validate .github/rhiza/template.yml.
+    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,
@@ -141,9 +161,9 @@ def materialize(
     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("."),
 ):
     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,13 +218,15 @@ 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("."),
 ):
     r"""Migrate project to the new .rhiza folder structure.
 
@@ -243,13 +267,15 @@ 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",
@@ -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,
+):
+    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.

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
 
 
@@ -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,
+    template_repository: str | None = None,
+    template_branch: str | None = None,
 ):
-    """Initialize or validate .github/rhiza/template.yml in the target repository.
+    """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
@@ -37,7 +37,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,7 +48,7 @@ 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,
@@ -57,7 +57,7 @@ def _handle_target_branch(
         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,
@@ -99,7 +99,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 +136,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 +161,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",
@@ -190,7 +190,7 @@ def _clone_template_repository(
     # 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,
@@ -208,7 +208,7 @@ def _clone_template_repository(
     # 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,

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

rhiza/commands/summarise.py

@@ -0,0 +1,416 @@
+"""Command for generating PR descriptions from staged changes.
+
+This module provides functionality to analyze staged git changes and generate
+structured PR descriptions for rhiza sync operations.
+"""
+
+import subprocess  # nosec B404
+import sys
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+
+from loguru import logger
+
+
+def run_git_command(args: list[str], cwd: Path | None = None) -> str:
+    """Run a git command and return the output.
+
+    Args:
+        args: Git command arguments (without 'git' prefix)
+        cwd: Working directory for the command
+
+    Returns:
+        Command output as string
+    """
+    try:
+        result = subprocess.run(  # nosec B603 B607
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Error running git {' '.join(args)}: {e.stderr}")
+        return ""
+
+
+def get_staged_changes(repo_path: Path) -> dict[str, list[str]]:
+    """Get list of staged changes categorized by type.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Dictionary with keys 'added', 'modified', 'deleted' containing file lists
+    """
+    changes = {
+        "added": [],
+        "modified": [],
+        "deleted": [],
+    }
+
+    # Get staged changes
+    output = run_git_command(["diff", "--cached", "--name-status"], cwd=repo_path)
+
+    for line in output.split("\n"):
+        if not line:
+            continue
+        parts = line.split("\t", 1)
+        if len(parts) != 2:
+            continue
+        status, filepath = parts
+
+        if status == "A":
+            changes["added"].append(filepath)
+        elif status == "M":
+            changes["modified"].append(filepath)
+        elif status == "D":
+            changes["deleted"].append(filepath)
+        elif status.startswith("R"):
+            # Renamed file - treat as modified
+            changes["modified"].append(filepath)
+
+    return changes
+
+
+def _get_config_files() -> set[str]:
+    """Get set of known configuration files.
+
+    Returns:
+        Set of configuration file names
+    """
+    return {
+        "Makefile",
+        "ruff.toml",
+        "pytest.ini",
+        ".editorconfig",
+        ".gitignore",
+        ".pre-commit-config.yaml",
+        "renovate.json",
+        ".python-version",
+    }
+
+
+def _categorize_by_directory(first_dir: str, filepath: str) -> str | None:
+    """Categorize file based on its first directory.
+
+    Args:
+        first_dir: First directory in the path
+        filepath: Full file path
+
+    Returns:
+        Category name or None if no match
+    """
+    if first_dir == ".github":
+        path_parts = Path(filepath).parts
+        if len(path_parts) > 1 and path_parts[1] == "workflows":
+            return "GitHub Actions Workflows"
+        return "GitHub Configuration"
+
+    if first_dir == ".rhiza":
+        if "script" in filepath.lower():
+            return "Rhiza Scripts"
+        if "Makefile" in filepath:
+            return "Makefiles"
+        return "Rhiza Configuration"
+
+    if first_dir == "tests":
+        return "Tests"
+
+    if first_dir == "book":
+        return "Documentation"
+
+    return None
+
+
+def _categorize_single_file(filepath: str) -> str:
+    """Categorize a single file path.
+
+    Args:
+        filepath: File path to categorize
+
+    Returns:
+        Category name
+    """
+    path_parts = Path(filepath).parts
+
+    if not path_parts:
+        return "Other"
+
+    # Try directory-based categorization first
+    category = _categorize_by_directory(path_parts[0], filepath)
+    if category:
+        return category
+
+    # Check file-based categories
+    if filepath.endswith(".md"):
+        return "Documentation"
+
+    if filepath in _get_config_files():
+        return "Configuration Files"
+
+    return "Other"
+
+
+def categorize_files(files: list[str]) -> dict[str, list[str]]:
+    """Categorize files by type.
+
+    Args:
+        files: List of file paths
+
+    Returns:
+        Dictionary mapping category names to file lists
+    """
+    categories = defaultdict(list)
+
+    for filepath in files:
+        category = _categorize_single_file(filepath)
+        categories[category].append(filepath)
+
+    return dict(categories)
+
+
+def get_template_info(repo_path: Path) -> tuple[str, str]:
+    """Get template repository and branch from template.yml.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Tuple of (template_repo, template_branch)
+    """
+    template_file = repo_path / ".rhiza" / "template.yml"
+
+    if not template_file.exists():
+        return ("jebel-quant/rhiza", "main")
+
+    template_repo = "jebel-quant/rhiza"
+    template_branch = "main"
+
+    with open(template_file) as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith("template-repository:"):
+                template_repo = line.split(":", 1)[1].strip().strip('"')
+            elif line.startswith("template-branch:"):
+                template_branch = line.split(":", 1)[1].strip().strip('"')
+
+    return template_repo, template_branch
+
+
+def get_last_sync_date(repo_path: Path) -> str | None:
+    """Get the date of the last sync commit.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        ISO format date string or None if not found
+    """
+    # Look for the most recent commit with "rhiza" in the message
+    output = run_git_command(
+        ["log", "--grep=rhiza", "--grep=Sync", "--grep=template", "-i", "--format=%cI", "-1"], cwd=repo_path
+    )
+
+    if output:
+        return output
+
+    # Fallback: try to get date from history file if it exists
+    history_file = repo_path / ".rhiza" / "history"
+    if history_file.exists():
+        # Get the file modification time
+        stat = history_file.stat()
+        return datetime.fromtimestamp(stat.st_mtime).isoformat()
+
+    return None
+
+
+def _format_file_list(files: list[str], status_emoji: str) -> list[str]:
+    """Format a list of files with the given status emoji.
+
+    Args:
+        files: List of file paths
+        status_emoji: Emoji to use (✅ for added, 📝 for modified, ❌ for deleted)
+
+    Returns:
+        List of formatted lines
+    """
+    lines = []
+    for f in sorted(files):
+        lines.append(f"- {status_emoji} `{f}`")
+    return lines
+
+
+def _add_category_section(lines: list[str], title: str, count: int, files: list[str], emoji: str) -> None:
+    """Add a collapsible section for a category and change type.
+
+    Args:
+        lines: List to append lines to
+        title: Section title (e.g., "Added", "Modified")
+        count: Number of files
+        files: List of file paths
+        emoji: Status emoji
+    """
+    if not files:
+        return
+
+    lines.append("<details>")
+    lines.append(f"<summary>{title} ({count})</summary>")
+    lines.append("")
+    lines.extend(_format_file_list(files, emoji))
+    lines.append("")
+    lines.append("</details>")
+    lines.append("")
+
+
+def _build_header(template_repo: str) -> list[str]:
+    """Build the PR description header.
+
+    Args:
+        template_repo: Template repository name
+
+    Returns:
+        List of header lines
+    """
+    return [
+        "## 🔄 Template Synchronization",
+        "",
+        f"This PR synchronizes the repository with the [{template_repo}](https://github.com/{template_repo}) template.",
+        "",
+    ]
+
+
+def _build_summary(changes: dict[str, list[str]]) -> list[str]:
+    """Build the change summary section.
+
+    Args:
+        changes: Dictionary of changes by type
+
+    Returns:
+        List of summary lines
+    """
+    return [
+        "### 📊 Change Summary",
+        "",
+        f"- **{len(changes['added'])}** files added",
+        f"- **{len(changes['modified'])}** files modified",
+        f"- **{len(changes['deleted'])}** files deleted",
+        "",
+    ]
+
+
+def _build_footer(template_repo: str, template_branch: str, last_sync: str | None) -> list[str]:
+    """Build the PR description footer with metadata.
+
+    Args:
+        template_repo: Template repository name
+        template_branch: Template branch name
+        last_sync: Last sync date string or None
+
+    Returns:
+        List of footer lines
+    """
+    lines = [
+        "---",
+        "",
+        "**🤖 Generated by [rhiza](https://github.com/jebel-quant/rhiza-cli)**",
+        "",
+        f"- Template: `{template_repo}@{template_branch}`",
+    ]
+    if last_sync:
+        lines.append(f"- Last sync: {last_sync}")
+    lines.append(f"- Sync date: {datetime.now().astimezone().isoformat()}")
+    return lines
+
+
+def generate_pr_description(repo_path: Path) -> str:
+    """Generate PR description based on staged changes.
+
+    Args:
+        repo_path: Path to the repository
+
+    Returns:
+        Formatted PR description
+    """
+    changes = get_staged_changes(repo_path)
+    template_repo, template_branch = get_template_info(repo_path)
+    last_sync = get_last_sync_date(repo_path)
+
+    # Build header
+    lines = _build_header(template_repo)
+
+    # Check if there are any changes
+    total_changes = sum(len(files) for files in changes.values())
+    if total_changes == 0:
+        lines.append("No changes detected.")
+        return "\n".join(lines)
+
+    # Add summary
+    lines.extend(_build_summary(changes))
+
+    # Add detailed changes by category
+    all_changed_files = changes["added"] + changes["modified"] + changes["deleted"]
+    categories = categorize_files(all_changed_files)
+
+    if categories:
+        lines.append("### 📁 Changes by Category")
+        lines.append("")
+
+        for category, files in sorted(categories.items()):
+            lines.append(f"#### {category}")
+            lines.append("")
+
+            # Group files by change type
+            category_added = [f for f in files if f in changes["added"]]
+            category_modified = [f for f in files if f in changes["modified"]]
+            category_deleted = [f for f in files if f in changes["deleted"]]
+
+            _add_category_section(lines, "Added", len(category_added), category_added, "✅")
+            _add_category_section(lines, "Modified", len(category_modified), category_modified, "📝")
+            _add_category_section(lines, "Deleted", len(category_deleted), category_deleted, "❌")
+
+    # Add footer
+    lines.extend(_build_footer(template_repo, template_branch, last_sync))
+
+    return "\n".join(lines)
+
+
+def summarise(target: Path, output: Path | None = None) -> None:
+    """Generate a summary of staged changes for rhiza sync operations.
+
+    This command analyzes staged git changes and generates a structured
+    PR description with:
+    - Summary statistics (files added/modified/deleted)
+    - Changes categorized by type (workflows, configs, docs, tests, etc.)
+    - Template repository information
+    - Last sync date
+
+    Args:
+        target: Path to the target repository.
+        output: Optional output file path. If not provided, prints to stdout.
+    """
+    target = target.resolve()
+    logger.info(f"Target repository: {target}")
+
+    # Check if target is a git repository
+    if not (target / ".git").is_dir():
+        logger.error(f"Target directory is not a git repository: {target}")
+        logger.error("Initialize a git repository with 'git init' first")
+        sys.exit(1)
+
+    # Generate the PR description
+    description = generate_pr_description(target)
+
+    # Output the description
+    if output:
+        output_path = output.resolve()
+        output_path.write_text(description)
+        logger.success(f"PR description written to {output_path}")
+    else:
+        # Print to stdout
+        print(description)
+
+    logger.success("Summary generated successfully")

rhiza/commands/uninstall.py

@@ -143,10 +143,11 @@ def _remove_history_file(history_file: Path, target: Path) -> tuple[int, int]:
     try:
         history_file.unlink()
         logger.success(f"[DEL] {history_file.relative_to(target)}")
-        return 1, 0
     except Exception as e:
         logger.error(f"Failed to delete {history_file.relative_to(target)}: {e}")
         return 0, 1
+    else:
+        return 1, 0
 
 
 def _print_summary(removed_count: int, skipped_count: int, empty_dirs_removed: int, error_count: int) -> None:

rhiza/commands/validate.py

@@ -91,7 +91,7 @@ def _check_template_file_exists(target: Path) -> tuple[bool, Path]:
         logger.info("  • If you have an existing configuration, run: rhiza migrate")
         logger.info("")
         logger.info("The 'rhiza migrate' command will move your configuration from")
-        logger.info("  .github/rhiza/template.yml → .rhiza/template.yml")
+        logger.info("  the old location → .rhiza/template.yml")
         return False, template_file
 
     logger.success(f"Template file exists: {template_file.relative_to(target)}")

rhiza/commands/welcome.py

@@ -44,7 +44,7 @@ Python projects using reusable templates stored in a central repository.
   1. Initialize a project:
      $ rhiza init
 
-  2. Customize .github/rhiza/template.yml to match your needs
+  2. Customize .rhiza/template.yml to match your needs
 
   3. Materialize templates into your project:
      $ rhiza materialize

rhiza/models.py

@@ -36,7 +36,7 @@ def _normalize_to_list(value: str | list[str] | None) -> list[str]:
 
 @dataclass
 class RhizaTemplate:
-    """Represents the structure of .github/rhiza/template.yml.
+    """Represents the structure of .rhiza/template.yml.
 
     Attributes:
         template_repository: The GitHub or GitLab repository containing templates (e.g., "jebel-quant/rhiza").
@@ -74,7 +74,7 @@ class RhizaTemplate:
             config = yaml.safe_load(f)
 
         if not config:
-            raise ValueError("Template file is empty")
+            raise ValueError("Template file is empty")  # noqa: TRY003
 
         return cls(
             template_repository=config.get("template-repository"),

{rhiza-0.8.8.dist-info → rhiza-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhiza
-Version: 0.8.8
+Version: 0.9.0
 Summary: Reusable configuration templates for modern Python projects
 Project-URL: Homepage, https://github.com/jebel-quant/rhiza-cli
 Project-URL: Repository, https://github.com/jebel-quant/rhiza-cli
@@ -146,11 +146,11 @@ rhiza --help
    rhiza init
    ```
 
-   This creates a `.github/rhiza/template.yml` file with default configuration.
+   This creates a `.rhiza/template.yml` file with default configuration.
 
 2. **Customize the template configuration:**
 
-   Edit `.github/rhiza/template.yml` to specify which files/directories to include from your template repository.
+   Edit `.rhiza/template.yml` to specify which files/directories to include from your template repository.
 
 3. **Materialize templates into your project:**
 
@@ -166,27 +166,38 @@ rhiza --help
    rhiza validate
    ```
 
-   This checks that your `.github/rhiza/template.yml` is correctly formatted and valid.
+   This checks that your `.rhiza/template.yml` is correctly formatted and valid.
 
 ## Commands
 
 ### `rhiza init`
 
-Initialize or validate `.github/rhiza/template.yml` in a target directory.
+Initialize or validate `.rhiza/template.yml` in a target directory.
 
 **Usage:**
 
 ```bash
-rhiza init [TARGET]
+rhiza init [OPTIONS] [TARGET]
 ```
 
 **Arguments:**
 
 - `TARGET` - Target directory (defaults to current directory)
 
+**Options:**
+
+- `--project-name <name>` - Custom project name (defaults to directory name)
+- `--package-name <name>` - Custom package name (defaults to normalized project name)
+- `--with-dev-dependencies` - Include development dependencies in pyproject.toml
+- `--git-host <host>` - Target Git hosting platform (github or gitlab). Determines which CI/CD files to include. If not provided, will prompt interactively.
+- `--template-repository <owner/repo>` - Custom template repository (format: owner/repo). Defaults to 'jebel-quant/rhiza'.
+- `--template-branch <branch>` - Custom template branch. Defaults to 'main'.
+
 **Description:**
 
-Creates a default `.github/rhiza/template.yml` file if it doesn't exist, or validates an existing one. The default configuration includes common Python project files like `.github`, `.editorconfig`, `.gitignore`, `.pre-commit-config.yaml`, `Makefile`, and `pytest.ini`.
+Creates a default `.rhiza/template.yml` file if it doesn't exist, or validates an existing one. The default configuration includes common Python project files like `.github`, `.editorconfig`, `.gitignore`, `.pre-commit-config.yaml`, `Makefile`, and `pytest.ini`.
+
+You can customize the template source by specifying your own template repository and branch using the `--template-repository` and `--template-branch` options.
 
 **Examples:**
 
@@ -197,6 +208,15 @@ rhiza init
 # Initialize in a specific directory
 rhiza init /path/to/project
 
+# Initialize with GitLab CI configuration
+rhiza init --git-host gitlab
+
+# Use a custom template repository
+rhiza init --template-repository myorg/my-templates
+
+# Use a custom template repository and branch
+rhiza init --template-repository myorg/my-templates --template-branch develop
+
 # Initialize in parent directory
 rhiza init ..
 ```
@@ -206,18 +226,18 @@ rhiza init ..
 When creating a new template file:
 ```
 [INFO] Initializing Rhiza configuration in: /path/to/project
-[INFO] Creating default .github/rhiza/template.yml
-✓ Created .github/rhiza/template.yml
+[INFO] Creating default .rhiza/template.yml
+✓ Created .rhiza/template.yml
 
 Next steps:
-  1. Review and customize .github/rhiza/template.yml to match your project needs
+  1. Review and customize .rhiza/template.yml to match your project needs
   2. Run 'rhiza materialize' to inject templates into your repository
 ```
 
 When validating an existing file:
 ```
 [INFO] Validating template configuration in: /path/to/project
-✓ Found template file: /path/to/project/.github/rhiza/template.yml
+✓ Found template file: /path/to/project/.rhiza/template.yml
 ✓ YAML syntax is valid
 ✓ Field 'template-repository' is present and valid
 ✓ Field 'include' is present and valid
@@ -252,7 +272,7 @@ rhiza materialize [OPTIONS] [TARGET]
 
 Materializes template files from the configured template repository into your target project. This command:
 
-1. Reads the `.github/rhiza/template.yml` configuration
+1. Reads the `.rhiza/template.yml` configuration
 2. Performs a sparse clone of the template repository
 3. Copies specified files/directories to your project
 4. Respects exclusion patterns defined in the configuration
@@ -366,7 +386,7 @@ rhiza migrate /path/to/project
 [INFO] This will create the .rhiza folder and migrate configuration files
 [INFO] Creating .rhiza directory at: .rhiza
 ✓ Created .rhiza
-[INFO] Found template.yml at: .github/rhiza/template.yml
+[INFO] Found template.yml at: .rhiza/template.yml
 [INFO] Moving to new location: .rhiza/template.yml
 ✓ Moved template.yml to .rhiza/template.yml
 ✓ Migration completed successfully
@@ -414,7 +434,7 @@ rhiza validate [TARGET]
 
 **Description:**
 
-Validates the `.github/rhiza/template.yml` file to ensure it is syntactically correct and semantically valid. This performs authoritative validation including:
+Validates the `.rhiza/template.yml` file to ensure it is syntactically correct and semantically valid. This performs authoritative validation including:
 
 - Checking if the file exists
 - Validating YAML syntax
@@ -445,7 +465,7 @@ rhiza validate ..
 
 ```
 [INFO] Validating template configuration in: /path/to/project
-✓ Found template file: /path/to/project/.github/rhiza/template.yml
+✓ Found template file: /path/to/project/.rhiza/template.yml
 ✓ YAML syntax is valid
 ✓ Field 'template-repository' is present and valid
 ✓ Field 'include' is present and valid
@@ -469,7 +489,7 @@ rhiza validate ..
 or
 
 ```
-[ERROR] Template file not found: /path/to/project/.github/rhiza/template.yml
+[ERROR] Template file not found: /path/to/project/.rhiza/template.yml
 [INFO] Run 'rhiza materialize' or 'rhiza init' to create a default template.yml
 ```
 
@@ -477,7 +497,7 @@ or
 
 ## Configuration
 
-Rhiza uses a `.github/rhiza/template.yml` file to define template sources and what to include in your project.
+Rhiza uses a `.rhiza/template.yml` file to define template sources and what to include in your project.
 
 ### Configuration File Format
 
@@ -618,7 +638,7 @@ git init
 rhiza init
 
 # Review the generated template.yml
-cat .github/rhiza/template.yml
+cat .rhiza/template.yml
 
 # Materialize templates
 rhiza materialize
@@ -653,7 +673,7 @@ git commit -m "chore: update rhiza templates"
 
 ### Example 3: Using a custom template repository
 
-Edit `.github/rhiza/template.yml`:
+Edit `.rhiza/template.yml`:
 
 ```yaml
 template-repository: myorg/my-templates
@@ -675,7 +695,7 @@ rhiza materialize --force
 
 ### Example 4: Using a GitLab template repository
 
-Edit `.github/rhiza/template.yml`:
+Edit `.rhiza/template.yml`:
 
 ```yaml
 template-repository: mygroup/python-templates
@@ -815,7 +835,7 @@ Releasing and Versioning
   post-release     perform post-release tasks
 
 Meta
-  sync             sync with template repository as defined in .github/rhiza/template.yml
+  sync             sync with template repository as defined in .rhiza/template.yml
   help             Display this help message
   customisations   list available customisation scripts
   update-readme    update README.md with current Makefile help output
@@ -887,7 +907,7 @@ export PATH="$HOME/.local/bin:$PATH"
 ### Template validation fails
 
 Check that:
-1. Your `.github/rhiza/template.yml` file exists
+1. Your `.rhiza/template.yml` file exists
 2. The YAML syntax is valid
 3. Required fields (`template-repository` and `include`) are present
 4. The repository format is `owner/repo`
@@ -919,11 +939,11 @@ A: Yes, as long as you have Git credentials configured that allow access to the
 
 **Q: Does Rhiza support template repositories hosted outside GitHub?**
 
-A: Yes! Rhiza supports both GitHub and GitLab repositories. Use the `template-host` field in your `.github/rhiza/template.yml` to specify "github" (default) or "gitlab".
+A: Yes! Rhiza supports both GitHub and GitLab repositories. Use the `template-host` field in your `.rhiza/template.yml` to specify "github" (default) or "gitlab".
 
 **Q: How do I use a GitLab repository as a template source?**
 
-A: Add `template-host: gitlab` to your `.github/rhiza/template.yml` file. For example:
+A: Add `template-host: gitlab` to your `.rhiza/template.yml` file. For example:
 ```yaml
 template-repository: mygroup/myproject
 template-host: gitlab
@@ -938,7 +958,7 @@ A: Not directly. However, you can run `rhiza materialize` multiple times with di
 
 **Q: What's the difference between `rhiza init` and `rhiza materialize`?**
 
-A: `init` creates or validates the `.github/rhiza/template.yml` configuration file. `materialize` reads that configuration and actually copies the template files into your project.
+A: `init` creates or validates the `.rhiza/template.yml` configuration file. `materialize` reads that configuration and actually copies the template files into your project.
 
 **Q: How do I update my project's templates?**
 
@@ -954,7 +974,7 @@ A: The update method depends on how you installed rhiza:
 
 **Q: Can I customize which files are included?**
 
-A: Yes, edit the `include` and `exclude` lists in `.github/rhiza/template.yml` to control exactly which files are copied.
+A: Yes, edit the `include` and `exclude` lists in `.rhiza/template.yml` to control exactly which files are copied.
 
 ## Acknowledgments
 

rhiza-0.9.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+rhiza/__init__.py,sha256=4-Dy7AKbJneQNBfv30WhSsUin4y-g4Yp4veO6-YdjVg,1926
+rhiza/__main__.py,sha256=Q02upTGaJceknkDABdCwq5_vdMdGY8Cg3ej6WZIHs_s,829
+rhiza/cli.py,sha256=uU0tenEgTe0Wz5lIj0SZIeXy5n_9-8xtUMMP_i71CWA,10609
+rhiza/models.py,sha256=f4TT3XPMEE7ciyrpsXllje4eGJRkYOgpZOoFeRC-rVI,4225
+rhiza/subprocess_utils.py,sha256=Pr5TysIKP76hc64fmqhTd6msMGn5DU43hOSR_v_GFb8,745
+rhiza/_templates/basic/__init__.py.jinja2,sha256=gs8qN4LAKcdFd6iO9gZVLuVetODmZP_TGuEjWrbinC0,27
+rhiza/_templates/basic/main.py.jinja2,sha256=uTCahxf9Bftao1IghHue4cSZ9YzBYmBEXeIhEmK9UXQ,362
+rhiza/_templates/basic/pyproject.toml.jinja2,sha256=Mizpnnd_kFQd-pCWOxG-KWhvg4_ZhZaQppTt2pz0WOc,695
+rhiza/commands/__init__.py,sha256=QWEEVvdW3gKV-FpKgHRJL_H8FpQqvfck9JvnFMDz3gY,1834
+rhiza/commands/init.py,sha256=dpLwFbURyndkgw-v4O6gD0gg6ov6q023uOmaWGup2oA,9785
+rhiza/commands/materialize.py,sha256=1YmzlPz9-IxnV4znDZQijZ3cjfbBXdepmps963z4Hsg,18668
+rhiza/commands/migrate.py,sha256=A5t4nw7CrdtILCwuSoAqtmM0LpMK8KmX87gzlNgi7fQ,7522
+rhiza/commands/summarise.py,sha256=KJ8v4lHSbn8AIt3tJM_lSCizzZ2Bv2mqTfI0z7-kyxI,11736
+rhiza/commands/uninstall.py,sha256=6oO7kdv11Bq4JXjrBg9rsFtoRgttQ4m30zGr6NhZrkQ,7479
+rhiza/commands/validate.py,sha256=VriXJxyuhvGJajw0qiAUmXYKRMbpgKiZ5_MMtE6WlSo,10801
+rhiza/commands/welcome.py,sha256=u197cIlY1tXm-CN6YpyUX4Eq06pLeV0hGyNvT35tE8U,2375
+rhiza-0.9.0.dist-info/METADATA,sha256=6AIK6bVC54vxBE0NB9jdLkBuTUcn9W0jod6ixm1-EB0,26298
+rhiza-0.9.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rhiza-0.9.0.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
+rhiza-0.9.0.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
+rhiza-0.9.0.dist-info/RECORD,,

rhiza-0.8.8.dist-info/RECORD

@@ -1,20 +0,0 @@
-rhiza/__init__.py,sha256=iW3niLBjwRKxcMhIV_1eb78putjUTo2tbZsadofluJk,1939
-rhiza/__main__.py,sha256=Q02upTGaJceknkDABdCwq5_vdMdGY8Cg3ej6WZIHs_s,829
-rhiza/cli.py,sha256=xIsyfKjSFjVLjCS7o2om5o_YLZx9lIhsI0MTMI5Zs2k,8594
-rhiza/models.py,sha256=o_iD8P7d7RAHH6J91tSPmD6lY-2HUsCaIl8auWqm2NM,4216
-rhiza/subprocess_utils.py,sha256=Pr5TysIKP76hc64fmqhTd6msMGn5DU43hOSR_v_GFb8,745
-rhiza/_templates/basic/__init__.py.jinja2,sha256=gs8qN4LAKcdFd6iO9gZVLuVetODmZP_TGuEjWrbinC0,27
-rhiza/_templates/basic/main.py.jinja2,sha256=uTCahxf9Bftao1IghHue4cSZ9YzBYmBEXeIhEmK9UXQ,362
-rhiza/_templates/basic/pyproject.toml.jinja2,sha256=Mizpnnd_kFQd-pCWOxG-KWhvg4_ZhZaQppTt2pz0WOc,695
-rhiza/commands/__init__.py,sha256=Z5CeMh7ylX27H6dvwqRbEKzYo5pwQq-5TyTxABUSaQg,1848
-rhiza/commands/init.py,sha256=73MLPLp-M8U4fP8J5RXghS6FsZjx2PpeeBbKRZvLQ7U,8882
-rhiza/commands/materialize.py,sha256=U6MouBNrg_GjYIPD0vBb3nacFBKGP4l8RD-HH0u-mYk,18538
-rhiza/commands/migrate.py,sha256=pT8izKuX2eXCAkmNfcy4AU5HTB1DoOZoBXcZo2AOpXs,7520
-rhiza/commands/uninstall.py,sha256=MJbQtmdTgbzMvQz0gGLW3aw6S1dSV8nLv0SqWSDpyPk,7469
-rhiza/commands/validate.py,sha256=pg7SpgavvrjDyuZIphJ_GOMnXkwdVs9WtL2caa1XjcM,10811
-rhiza/commands/welcome.py,sha256=w3BziR042o6oYincd3EqDsFzF6qqInU7iYhWjF3yJqY,2382
-rhiza-0.8.8.dist-info/METADATA,sha256=PGkXXTlS2XGjxAm5ODJmDvrRerXnEmG1ZoUcJvYhiyo,25395
-rhiza-0.8.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-rhiza-0.8.8.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
-rhiza-0.8.8.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
-rhiza-0.8.8.dist-info/RECORD,,