rhiza 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

rhiza/__init__.py

@@ -3,3 +3,7 @@
 This package groups small, user-facing utilities that can be invoked from
 the command line or other automation scripts.
 """
+
+from rhiza.models import RhizaTemplate
+
+__all__ = ["RhizaTemplate"]

rhiza/cli.py

@@ -8,16 +8,45 @@ from pathlib import Path
 
 import typer
 
-from rhiza.commands.hello import hello as hello_cmd
-from rhiza.commands.inject import inject as inject_cmd
+from rhiza.commands.init import init as init_cmd
+from rhiza.commands.materialize import materialize as materialize_cmd
+from rhiza.commands.validate import validate as validate_cmd
 
-app = typer.Typer(help="rhiza — configuration materialization tools")
+app = typer.Typer(
+    help="Rhiza - Manage reusable configuration templates for Python projects",
+    add_completion=True,
+)
 
 
 @app.command()
-def hello():
-    """Sanity check command."""
-    hello_cmd()
+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)",
+    ),
+):
+    """Initialize or validate .github/template.yml.
+
+    Creates a default .github/template.yml configuration file if one doesn't
+    exist, or validates the existing configuration.
+
+    The default template includes common Python project files:
+    - .github (workflows, actions, etc.)
+    - .editorconfig
+    - .gitignore
+    - .pre-commit-config.yaml
+    - Makefile
+    - pytest.ini
+
+    Examples:
+        rhiza init
+        rhiza init /path/to/project
+        rhiza init ..
+    """
+    init_cmd(target)
 
 
 @app.command()
@@ -32,16 +61,55 @@ def materialize(
     branch: str = typer.Option("main", "--branch", "-b", help="Rhiza branch to use"),
     force: bool = typer.Option(False, "--force", "-y", help="Overwrite existing files"),
 ):
-    """Inject Rhiza configuration into a target repository.
-
-    Parameters
-    ----------
-    target:
-        Path to the target Git repository directory. Defaults to the
-        current working directory.
-    branch:
-        Name of the Rhiza branch to use when sourcing templates.
-    force:
-        If True, overwrite existing files without prompting.
+    """Inject Rhiza configuration templates into a target repository.
+
+    Materializes configuration files from the template repository specified
+    in .github/template.yml into your project. This command:
+
+    1. Reads .github/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
+
+    Files that already exist will NOT be overwritten unless --force is used.
+
+    Examples:
+        rhiza materialize
+        rhiza materialize --branch develop
+        rhiza materialize --force
+        rhiza materialize /path/to/project -b v2.0 -y
+    """
+    materialize_cmd(target, branch, force)
+
+
+@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)",
+    ),
+):
+    """Validate Rhiza template configuration.
+
+    Validates the .github/template.yml file to ensure it is syntactically
+    correct and semantically valid. Performs comprehensive validation:
+
+    - Checks if template.yml exists
+    - Validates YAML syntax
+    - Verifies required fields are present (template-repository, include)
+    - Validates field types and formats
+    - Ensures repository name follows owner/repo format
+    - Confirms include paths are not empty
+
+    Returns exit code 0 on success, 1 on validation failure.
+
+    Examples:
+        rhiza validate
+        rhiza validate /path/to/project
+        rhiza validate ..
     """
-    inject_cmd(target, branch, force)
+    if not validate_cmd(target):
+        raise typer.Exit(code=1)

rhiza/commands/init.py

@@ -0,0 +1,66 @@
+"""Command to initialize or validate .github/template.yml.
+
+This module provides the init command that creates or validates the
+.github/template.yml file, which defines where templates come from
+and what paths are governed by Rhiza.
+"""
+
+from pathlib import Path
+
+from loguru import logger
+
+from rhiza.commands.validate import validate
+from rhiza.models import RhizaTemplate
+
+
+def init(target: Path):
+    """Initialize or validate .github/template.yml in the target repository.
+
+    Creates a default .github/template.yml file if it doesn't exist,
+    or validates an existing one.
+
+    Parameters
+    ----------
+    target:
+        Path to the target directory. Defaults to the current working directory.
+    """
+    # Convert to absolute path to avoid surprises
+    target = target.resolve()
+
+    logger.info(f"Initializing Rhiza configuration in: {target}")
+
+    # Create .github directory if it doesn't exist
+    github_dir = target / ".github"
+    github_dir.mkdir(parents=True, exist_ok=True)
+
+    # Define the template file path
+    template_file = github_dir / "template.yml"
+
+    if not template_file.exists():
+        # Create default template.yml
+        logger.info("Creating default .github/template.yml")
+
+        default_template = RhizaTemplate(
+            template_repository="jebel-quant/rhiza",
+            template_branch="main",
+            include=[
+                ".github",
+                ".editorconfig",
+                ".gitignore",
+                ".pre-commit-config.yaml",
+                "Makefile",
+                "pytest.ini",
+            ],
+        )
+
+        default_template.to_yaml(template_file)
+
+        logger.success("✓ Created .github/template.yml")
+        logger.info("""
+Next steps:
+  1. Review and customize .github/template.yml to match your project needs
+  2. Run 'rhiza materialize' to inject templates into your repository
+""")
+
+    # the template file exists, so validate it
+    validate(target)

rhiza/commands/{inject.py → materialize.py}

@@ -12,9 +12,11 @@ import sys
 import tempfile
 from pathlib import Path
 
-import yaml
 from loguru import logger
 
+from rhiza.commands.init import init
+from rhiza.models import RhizaTemplate
+
 
 def expand_paths(base_dir: Path, paths: list[str]) -> list[Path]:
     """Expand files/directories relative to base_dir into a flat list of files.
@@ -35,16 +37,11 @@ def expand_paths(base_dir: Path, paths: list[str]) -> list[Path]:
     return all_files
 
 
-def inject(target: Path, branch: str, force: bool):
+def materialize(target: Path, branch: str, force: bool):
     """Materialize rhiza templates into TARGET repository."""
     # Convert to absolute path to avoid surprises
     target = target.resolve()
 
-    # Validate target is a git repository
-    if not (target / ".git").is_dir():
-        logger.error(f"Target directory is not a git repository: {target}")
-        raise sys.exit(1)
-
     logger.info(f"Target repository: {target}")
     logger.info(f"Rhiza branch: {branch}")
 
@@ -52,38 +49,21 @@ def inject(target: Path, branch: str, force: bool):
     # Ensure template.yml
     # -----------------------
     template_file = target / ".github" / "template.yml"
-    template_file.parent.mkdir(parents=True, exist_ok=True)
-
-    if not template_file.exists():
-        logger.info("Creating default .github/template.yml")
-        template_content = {
-            "template-repository": "jebel-quant/rhiza",
-            "template-branch": branch,
-            "include": [
-                ".github",
-                ".editorconfig",
-                ".gitignore",
-                ".pre-commit-config.yaml",
-                "Makefile",
-                "pytest.ini",
-            ],
-        }
-        with open(template_file, "w") as f:
-            yaml.dump(template_content, f)
-        logger.success(".github/template.yml created")
-    else:
-        logger.info("Using existing .github/template.yml")
+    # template_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Initialize rhiza if not already initialized, e.g. construct a template.yml file
+    init(target)
 
     # -----------------------
     # Load template.yml
     # -----------------------
-    with open(template_file) as f:
-        config = yaml.safe_load(f)
+    template = RhizaTemplate.from_yaml(template_file)
 
-    rhiza_repo = config.get("template-repository")
-    rhiza_branch = config.get("template-branch", branch)
-    include_paths = config.get("include", [])
-    excluded_paths = config.get("exclude", [])
+    rhiza_repo = template.template_repository
+    # Use template branch if specified, otherwise fall back to CLI parameter
+    rhiza_branch = template.template_branch if template.template_branch else branch
+    include_paths = template.include
+    excluded_paths = template.exclude
 
     if not include_paths:
         logger.error("No include paths found in template.yml")

rhiza/commands/validate.py

@@ -0,0 +1,140 @@
+"""Command for validating Rhiza template configuration.
+
+This module provides functionality to validate .github/template.yml files
+to ensure they are syntactically correct and semantically valid.
+"""
+
+from pathlib import Path
+
+import yaml
+from loguru import logger
+
+
+def validate(target: Path) -> bool:
+    """Validate template.yml configuration in the target repository.
+
+    Performs authoritative validation of the template configuration:
+    - Checks if template.yml exists
+    - Validates YAML syntax
+    - Validates required fields
+    - Validates field values are appropriate
+
+    Parameters
+    ----------
+    target:
+        Path to the target Git repository directory.
+
+    Returns:
+    -------
+    bool
+        True if validation passes, False otherwise.
+    """
+    # Convert to absolute path
+    target = target.resolve()
+
+    # Check if target is a git repository
+    if not (target / ".git").is_dir():
+        logger.error(f"Target directory is not a git repository: {target}")
+        return False
+
+    logger.info(f"Validating template configuration in: {target}")
+
+    # Check if template.yml exists
+    template_file = target / ".github" / "template.yml"
+    if not template_file.exists():
+        logger.error(f"Template file not found: {template_file}")
+        logger.info("Run 'rhiza materialize' or 'rhiza inject' to create a default template.yml")
+        return False
+
+    logger.success(f"Found template file: {template_file}")
+
+    # Validate YAML syntax
+    try:
+        with open(template_file) as f:
+            config = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        logger.error(f"Invalid YAML syntax in template.yml: {e}")
+        return False
+
+    if config is None:
+        logger.error("template.yml is empty")
+        return False
+
+    logger.success("YAML syntax is valid")
+
+    # Validate required fields
+    required_fields = {
+        "template-repository": str,
+        "include": list,
+    }
+
+    validation_passed = True
+
+    for field, expected_type in required_fields.items():
+        if field not in config:
+            logger.error(f"Missing required field: {field}")
+            validation_passed = False
+        elif not isinstance(config[field], expected_type):
+            logger.error(
+                f"Field '{field}' must be of type {expected_type.__name__}, got {type(config[field]).__name__}"
+            )
+            validation_passed = False
+        else:
+            logger.success(f"Field '{field}' is present and valid")
+
+    # Validate template-repository format
+    if "template-repository" in config:
+        repo = config["template-repository"]
+        if not isinstance(repo, str):
+            logger.error(f"template-repository must be a string, got {type(repo).__name__}")
+            validation_passed = False
+        elif "/" not in repo:
+            logger.error(f"template-repository must be in format 'owner/repo', got: {repo}")
+            validation_passed = False
+        else:
+            logger.success(f"template-repository format is valid: {repo}")
+
+    # Validate include paths
+    if "include" in config:
+        include = config["include"]
+        if not isinstance(include, list):
+            logger.error(f"include must be a list, got {type(include).__name__}")
+            validation_passed = False
+        elif len(include) == 0:
+            logger.error("include list cannot be empty")
+            validation_passed = False
+        else:
+            logger.success(f"include list has {len(include)} path(s)")
+            for path in include:
+                if not isinstance(path, str):
+                    logger.warning(f"include path should be a string, got {type(path).__name__}: {path}")
+                else:
+                    logger.info(f"  - {path}")
+
+    # Validate optional fields
+    if "template-branch" in config:
+        branch = config["template-branch"]
+        if not isinstance(branch, str):
+            logger.warning(f"template-branch should be a string, got {type(branch).__name__}: {branch}")
+        else:
+            logger.success(f"template-branch is valid: {branch}")
+
+    if "exclude" in config:
+        exclude = config["exclude"]
+        if not isinstance(exclude, list):
+            logger.warning(f"exclude should be a list, got {type(exclude).__name__}")
+        else:
+            logger.success(f"exclude list has {len(exclude)} path(s)")
+            for path in exclude:
+                if not isinstance(path, str):
+                    logger.warning(f"exclude path should be a string, got {type(path).__name__}: {path}")
+                else:
+                    logger.info(f"  - {path}")
+
+    # Final verdict
+    if validation_passed:
+        logger.success("✓ Validation passed: template.yml is valid")
+        return True
+    else:
+        logger.error("✗ Validation failed: template.yml has errors")
+        return False

rhiza/models.py

@@ -0,0 +1,103 @@
+"""Data models for Rhiza configuration.
+
+This module defines dataclasses that represent the structure of Rhiza
+configuration files, making it easier to work with them without frequent
+YAML parsing.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class RhizaTemplate:
+    """Represents the structure of .github/template.yml.
+
+    Attributes:
+    ----------
+    template_repository : str | None
+        The GitHub repository containing templates (e.g., "jebel-quant/rhiza").
+        Can be None if not specified in the template file.
+    template_branch : str | None
+        The branch to use from the template repository.
+        Can be None if not specified in the template file (defaults to "main" when creating).
+    include : list[str]
+        List of paths to include from the template repository.
+    exclude : list[str]
+        List of paths to exclude from the template repository (default: empty list).
+    """
+
+    template_repository: str | None = None
+    template_branch: str | None = None
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_yaml(cls, file_path: Path) -> "RhizaTemplate":
+        """Load RhizaTemplate from a YAML file.
+
+        Parameters
+        ----------
+        file_path : Path
+            Path to the template.yml file.
+
+        Returns:
+        -------
+        RhizaTemplate
+            The loaded template configuration.
+
+        Raises:
+        ------
+        FileNotFoundError
+            If the file does not exist.
+        yaml.YAMLError
+            If the YAML is malformed.
+        ValueError
+            If the file is empty.
+        """
+        with open(file_path) as f:
+            config = yaml.safe_load(f)
+
+        if not config:
+            raise ValueError("Template file is empty")
+
+        return cls(
+            template_repository=config.get("template-repository"),
+            template_branch=config.get("template-branch"),
+            include=config.get("include", []),
+            exclude=config.get("exclude", []),
+        )
+
+    def to_yaml(self, file_path: Path) -> None:
+        """Save RhizaTemplate to a YAML file.
+
+        Parameters
+        ----------
+        file_path : Path
+            Path where the template.yml file should be saved.
+        """
+        # Ensure parent directory exists
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Convert to dictionary with YAML-compatible keys
+        config = {}
+
+        # Only include template-repository if it's not None
+        if self.template_repository:
+            config["template-repository"] = self.template_repository
+
+        # Only include template-branch if it's not None
+        if self.template_branch:
+            config["template-branch"] = self.template_branch
+
+        # Include is always present as it's a required field for the config to be useful
+        config["include"] = self.include
+
+        # Only include exclude if it's not empty
+        if self.exclude:
+            config["exclude"] = self.exclude
+
+        with open(file_path, "w") as f:
+            yaml.dump(config, f, default_flow_style=False, sort_keys=False)

rhiza-0.5.0.dist-info/METADATA

@@ -0,0 +1,773 @@
+Metadata-Version: 2.4
+Name: rhiza
+Version: 0.5.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
+Project-URL: Issues, https://github.com/jebel-quant/rhiza/issues-cli
+Author: Thomas Schmelzer
+License: MIT
+License-File: LICENSE
+Keywords: ci,configuration,ruff,taskfile,templates
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: typer>=0.20.0
+Provides-Extra: dev
+Requires-Dist: marimo==0.18.4; extra == 'dev'
+Requires-Dist: pdoc>=16.0.0; extra == 'dev'
+Requires-Dist: pre-commit==4.5.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-html>=4.1.1; extra == 'dev'
+Requires-Dist: pytest==9.0.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rhiza-cli
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Command-line interface for managing reusable configuration templates for modern Python projects.
+
+## Overview
+
+Rhiza is a CLI tool that helps you maintain consistent configuration across multiple Python projects by using templates stored in a central repository. It allows you to:
+
+- Initialize projects with standard configuration templates
+- Materialize (inject) templates into target repositories
+- Validate template configurations
+- Keep project configurations synchronized with template repositories
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [init](#rhiza-init)
+  - [materialize](#rhiza-materialize)
+  - [validate](#rhiza-validate)
+- [Configuration](#configuration)
+- [Examples](#examples)
+- [Development](#development)
+- [Additional Documentation](#additional-documentation)
+
+## Additional Documentation
+
+For more detailed information, see:
+
+- **[CLI Quick Reference](CLI.md)** - Command syntax and quick examples
+- **[Usage Guide](USAGE.md)** - Practical tutorials and workflows
+- **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute to the project
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
+
+## Installation
+
+### Using pip
+
+```bash
+pip install rhiza
+```
+
+### From source
+
+```bash
+git clone https://github.com/jebel-quant/rhiza-cli.git
+cd rhiza-cli
+pip install -e .
+```
+
+### Using uv (recommended for development)
+
+```bash
+git clone https://github.com/jebel-quant/rhiza-cli.git
+cd rhiza-cli
+make install
+```
+
+### Verify installation
+
+```bash
+rhiza --help
+```
+
+## Quick Start
+
+1. **Initialize a project with Rhiza templates:**
+
+   ```bash
+   cd your-project
+   rhiza init
+   ```
+
+   This creates a `.github/template.yml` file with default configuration.
+
+2. **Customize the template configuration:**
+
+   Edit `.github/template.yml` to specify which files/directories to include from your template repository.
+
+3. **Materialize templates into your project:**
+
+   ```bash
+   rhiza materialize
+   ```
+
+   This fetches and copies template files into your project.
+
+4. **Validate your configuration:**
+
+   ```bash
+   rhiza validate
+   ```
+
+   This checks that your `.github/template.yml` is correctly formatted and valid.
+
+## Commands
+
+### `rhiza init`
+
+Initialize or validate `.github/template.yml` in a target directory.
+
+**Usage:**
+
+```bash
+rhiza init [TARGET]
+```
+
+**Arguments:**
+
+- `TARGET` - Target directory (defaults to current directory)
+
+**Description:**
+
+Creates a default `.github/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`.
+
+**Examples:**
+
+```bash
+# Initialize in current directory
+rhiza init
+
+# Initialize in a specific directory
+rhiza init /path/to/project
+
+# Initialize in parent directory
+rhiza init ..
+```
+
+**Output:**
+
+When creating a new template file:
+```
+[INFO] Initializing Rhiza configuration in: /path/to/project
+[INFO] Creating default .github/template.yml
+✓ Created .github/template.yml
+
+Next steps:
+  1. Review and customize .github/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/template.yml
+✓ YAML syntax is valid
+✓ Field 'template-repository' is present and valid
+✓ Field 'include' is present and valid
+✓ template-repository format is valid: jebel-quant/rhiza
+✓ include list has 6 path(s)
+✓ Validation passed: template.yml is valid
+```
+
+---
+
+### `rhiza materialize`
+
+Inject Rhiza configuration templates into a target repository.
+
+**Usage:**
+
+```bash
+rhiza materialize [OPTIONS] [TARGET]
+```
+
+**Arguments:**
+
+- `TARGET` - Target git repository directory (defaults to current directory)
+
+**Options:**
+
+- `--branch, -b TEXT` - Rhiza branch to use [default: main]
+- `--force, -y` - Overwrite existing files without prompting
+- `--help` - Show help message and exit
+
+**Description:**
+
+Materializes template files from the configured template repository into your target project. This command:
+
+1. Reads the `.github/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
+
+**Examples:**
+
+```bash
+# Materialize templates in current directory
+rhiza materialize
+
+# Materialize templates from a specific branch
+rhiza materialize --branch develop
+
+# Materialize and overwrite existing files
+rhiza materialize --force
+
+# Materialize in a specific directory with custom branch
+rhiza materialize /path/to/project --branch v2.0 --force
+
+# Short form with all options
+rhiza materialize -b main -y
+```
+
+**Output:**
+
+```
+[INFO] Target repository: /path/to/project
+[INFO] Rhiza branch: main
+[INFO] Initializing Rhiza configuration in: /path/to/project
+[INFO] Include paths:
+  - .github
+  - .editorconfig
+  - .gitignore
+  - .pre-commit-config.yaml
+  - Makefile
+  - pytest.ini
+[INFO] Cloning jebel-quant/rhiza@main into temporary directory
+[ADD] .github/workflows/ci.yml
+[ADD] .editorconfig
+[ADD] .gitignore
+[ADD] Makefile
+✓ Rhiza templates materialized successfully
+
+Next steps:
+  1. Review changes:
+       git status
+       git diff
+
+  2. Commit:
+       git add .
+       git commit -m "chore: import rhiza templates"
+
+This is a one-shot snapshot.
+Re-run this script to update templates explicitly.
+```
+
+**Notes:**
+
+- Files that already exist will not be overwritten unless `--force` is used
+- The command performs a sparse clone for efficiency
+- Template files are copied with their original permissions
+- Excluded paths (if defined) are filtered out
+
+---
+
+### `rhiza validate`
+
+Validate Rhiza template configuration.
+
+**Usage:**
+
+```bash
+rhiza validate [TARGET]
+```
+
+**Arguments:**
+
+- `TARGET` - Target git repository directory (defaults to current directory)
+
+**Description:**
+
+Validates the `.github/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
+- Verifying required fields are present
+- Checking field types and formats
+- Validating repository name format
+- Ensuring include paths are not empty
+
+**Examples:**
+
+```bash
+# Validate configuration in current directory
+rhiza validate
+
+# Validate configuration in a specific directory
+rhiza validate /path/to/project
+
+# Validate parent directory
+rhiza validate ..
+```
+
+**Exit codes:**
+
+- `0` - Validation passed
+- `1` - Validation failed
+
+**Output (success):**
+
+```
+[INFO] Validating template configuration in: /path/to/project
+✓ Found template file: /path/to/project/.github/template.yml
+✓ YAML syntax is valid
+✓ Field 'template-repository' is present and valid
+✓ Field 'include' is present and valid
+✓ template-repository format is valid: jebel-quant/rhiza
+✓ include list has 6 path(s)
+  - .github
+  - .editorconfig
+  - .gitignore
+  - .pre-commit-config.yaml
+  - Makefile
+  - pytest.ini
+✓ Validation passed: template.yml is valid
+```
+
+**Output (failure):**
+
+```
+[ERROR] Target directory is not a git repository: /path/to/project
+```
+
+or
+
+```
+[ERROR] Template file not found: /path/to/project/.github/template.yml
+[INFO] Run 'rhiza materialize' or 'rhiza init' to create a default template.yml
+```
+
+---
+
+## Configuration
+
+Rhiza uses a `.github/template.yml` file to define template sources and what to include in your project.
+
+### Configuration File Format
+
+The `template.yml` file uses YAML format with the following structure:
+
+```yaml
+# Required: GitHub repository containing templates (format: owner/repo)
+template-repository: jebel-quant/rhiza
+
+# Optional: Branch to use from template repository (default: main)
+template-branch: main
+
+# Required: List of paths to include from template repository
+include:
+  - .github
+  - .editorconfig
+  - .gitignore
+  - .pre-commit-config.yaml
+  - Makefile
+  - pytest.ini
+  - ruff.toml
+
+# Optional: List of paths to exclude (filters out from included paths)
+exclude:
+  - .github/workflows/specific-workflow.yml
+  - .github/CODEOWNERS
+```
+
+### Configuration Fields
+
+#### `template-repository` (required)
+
+- **Type:** String
+- **Format:** `owner/repository`
+- **Description:** GitHub repository containing your configuration templates
+- **Example:** `jebel-quant/rhiza`, `myorg/python-templates`
+
+#### `template-branch` (optional)
+
+- **Type:** String
+- **Default:** `main`
+- **Description:** Git branch to use when fetching templates
+- **Example:** `main`, `develop`, `v2.0`
+
+#### `include` (required)
+
+- **Type:** List of strings
+- **Description:** Paths (files or directories) to copy from the template repository
+- **Notes:**
+  - Paths are relative to the repository root
+  - Can include both files and directories
+  - Directories are recursively copied
+  - Must contain at least one path
+
+**Example:**
+```yaml
+include:
+  - .github          # Entire directory
+  - .editorconfig    # Single file
+  - src/config       # Subdirectory
+```
+
+#### `exclude` (optional)
+
+- **Type:** List of strings
+- **Description:** Paths to exclude from the included set
+- **Notes:**
+  - Useful for excluding specific files from broader directory includes
+  - Paths are relative to the repository root
+
+**Example:**
+```yaml
+exclude:
+  - .github/workflows/deploy.yml  # Exclude specific workflow
+  - .github/CODEOWNERS            # Exclude specific file
+```
+
+### Complete Configuration Example
+
+```yaml
+template-repository: jebel-quant/rhiza
+template-branch: main
+include:
+  - .github
+  - .editorconfig
+  - .gitignore
+  - .pre-commit-config.yaml
+  - CODE_OF_CONDUCT.md
+  - CONTRIBUTING.md
+  - Makefile
+  - pytest.ini
+  - ruff.toml
+exclude:
+  - .github/workflows/release.yml
+  - .github/CODEOWNERS
+```
+
+## Examples
+
+### Example 1: Setting up a new Python project
+
+```bash
+# Create a new project directory
+mkdir my-python-project
+cd my-python-project
+
+# Initialize git
+git init
+
+# Initialize Rhiza
+rhiza init
+
+# Review the generated template.yml
+cat .github/template.yml
+
+# Materialize templates
+rhiza materialize
+
+# Review the imported files
+git status
+
+# Commit the changes
+git add .
+git commit -m "chore: initialize project with rhiza templates"
+```
+
+### Example 2: Updating existing project templates
+
+```bash
+# Navigate to your project
+cd existing-project
+
+# Validate current configuration
+rhiza validate
+
+# Update templates (overwrite existing)
+rhiza materialize --force
+
+# Review changes
+git diff
+
+# Commit if satisfied
+git add .
+git commit -m "chore: update rhiza templates"
+```
+
+### Example 3: Using a custom template repository
+
+Edit `.github/template.yml`:
+
+```yaml
+template-repository: myorg/my-templates
+template-branch: production
+include:
+  - .github/workflows
+  - pyproject.toml
+  - Makefile
+  - docker-compose.yml
+exclude:
+  - .github/workflows/experimental.yml
+```
+
+Then materialize:
+
+```bash
+rhiza materialize --force
+```
+
+### Example 4: Validating before CI/CD
+
+Add to your CI pipeline:
+
+```yaml
+# .github/workflows/validate-rhiza.yml
+name: Validate Rhiza Configuration
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install rhiza
+        run: pip install rhiza
+      - name: Validate configuration
+        run: rhiza validate
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.11 or higher
+- `uv` package manager (recommended) or `pip`
+- Git
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/jebel-quant/rhiza-cli.git
+cd rhiza-cli
+
+# Install dependencies
+make install
+
+# Run tests
+make test
+
+# Run linters and formatters
+make fmt
+
+# Generate documentation
+make docs
+```
+
+### Running Tests
+
+```bash
+# Run all tests with coverage
+make test
+
+# Run specific test file
+pytest tests/test_cli.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Code Quality
+
+The project uses:
+
+- **Ruff** for linting and formatting
+- **pytest** for testing
+- **pre-commit** hooks for automated checks
+
+```bash
+# Run all quality checks
+make fmt
+
+# Run dependency checks
+make deptry
+```
+
+### Building Documentation
+
+```bash
+# Generate API documentation
+make docs
+
+# Build complete documentation book
+make book
+```
+
+## Makefile Targets
+
+The project includes a comprehensive Makefile for common development tasks:
+
+```
+Bootstrap
+  install-uv       ensure uv/uvx is installed
+  install-extras   run custom build script (if exists)
+  install          install
+  clean            clean
+
+Development and Testing
+  test             run all tests
+  marimo           fire up Marimo server
+  marimushka       export Marimo notebooks to HTML
+  deptry           run deptry if pyproject.toml exists
+
+Documentation
+  docs             create documentation with pdoc
+  book             compile the companion book
+  fmt              check the pre-commit hooks and the linting
+  all              Run everything
+
+Releasing and Versioning
+  bump             bump version
+  release          create tag and push to remote with prompts
+  post-release     perform post-release tasks
+
+Meta
+  sync             sync with template repository as defined in .github/template.yml
+  help             Display this help message
+  customisations   list available customisation scripts
+  update-readme    update README.md with current Makefile help output
+```
+
+Run `make help` to see this list in your terminal.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Reporting Issues
+
+If you find a bug or have a feature request, please open an issue on [GitHub](https://github.com/jebel-quant/rhiza-cli/issues).
+
+### Code of Conduct
+
+This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Links
+
+- **Repository:** https://github.com/jebel-quant/rhiza-cli
+- **Issues:** https://github.com/jebel-quant/rhiza-cli/issues
+- **Documentation:** Generated with `make docs`
+
+## Architecture
+
+Rhiza follows a modular architecture:
+
+```
+src/rhiza/
+├── __init__.py         # Package initialization
+├── __main__.py         # Entry point for python -m rhiza
+├── cli.py              # Typer app and CLI command definitions
+├── models.py           # Data models (RhizaTemplate)
+└── commands/           # Command implementations
+    ├── __init__.py
+    ├── init.py         # Initialize template.yml
+    ├── materialize.py  # Materialize templates
+    └── validate.py     # Validate configuration
+```
+
+### Design Principles
+
+1. **Thin CLI Layer:** Commands in `cli.py` are thin wrappers that delegate to implementations in `commands/`
+2. **Separation of Concerns:** Each command has its own module with focused functionality
+3. **Type Safety:** Uses `pathlib.Path` for file operations and Typer for type-checked CLI arguments
+4. **Clear Logging:** Uses `loguru` for structured, colored logging output
+5. **Validation First:** Always validates configuration before performing operations
+
+## Troubleshooting
+
+### Command not found: rhiza
+
+Ensure the package is installed and your Python scripts directory is in your PATH:
+
+```bash
+pip install --user rhiza
+# Add ~/.local/bin to PATH if needed
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Template validation fails
+
+Check that:
+1. Your `.github/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`
+
+Run `rhiza validate` for detailed error messages.
+
+### Git clone fails during materialize
+
+Ensure:
+1. The template repository exists and is accessible
+2. The specified branch exists
+3. You have network connectivity to GitHub
+4. The repository is public (or you have appropriate credentials configured)
+
+### Files not being copied
+
+Check:
+1. The paths in `include` are correct relative to the template repository root
+2. The paths exist in the specified branch
+3. Any `exclude` patterns are not filtering out wanted files
+4. You're using `--force` if files already exist and need to be overwritten
+
+## FAQ
+
+**Q: Can I use Rhiza with private template repositories?**
+
+A: Yes, as long as you have Git credentials configured that allow access to the repository.
+
+**Q: Does Rhiza support template repositories hosted outside GitHub?**
+
+A: Currently, Rhiza is designed for GitHub repositories. Support for other Git hosting services could be added in the future.
+
+**Q: Can I materialize templates from multiple repositories?**
+
+A: Not directly. However, you can run `rhiza materialize` multiple times with different configurations, or combine templates manually.
+
+**Q: What's the difference between `rhiza init` and `rhiza materialize`?**
+
+A: `init` creates or validates the `.github/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?**
+
+A: Simply run `rhiza materialize --force` to fetch and overwrite with the latest versions from your template repository.
+
+**Q: Can I customize which files are included?**
+
+A: Yes, edit the `include` and `exclude` lists in `.github/template.yml` to control exactly which files are copied.
+
+## Acknowledgments
+
+Rhiza is developed and maintained by the Jebel Quant team as part of their effort to standardize Python project configurations across their portfolio.

rhiza-0.5.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+rhiza/__init__.py,sha256=fxaeT_K8bQAX5qt1DtRKWmyKpk7ABLomxhzZwL6Rml8,259
+rhiza/__main__.py,sha256=Lx0GqVZo6ymm0f18_uYB6E7_SOWwJNYjb73Vr31oLoM,236
+rhiza/cli.py,sha256=P130eveGtBUTby3A5LNDvgtJ2ekWcAiv84GqZ5kLcw4,3484
+rhiza/models.py,sha256=HbWgHPS-sWur4ax7a8tu2B6apr6YEdbGoxOpWxyeP9s,3220
+rhiza/commands/__init__.py,sha256=X5ZRDDl37X8mEbiMWoqjTGlLhebkYhZ2SaLJd4KcHdw,166
+rhiza/commands/init.py,sha256=wAVlcTdCiU8bN98Gsx8MGryo8fraFLQCvDl5ZlR1ySg,1953
+rhiza/commands/materialize.py,sha256=G1pDraC2gqIFuqC9nmIeXPnAHMna2KBIPfPAuLDllec,4412
+rhiza/commands/validate.py,sha256=rY04vz71C4ILAcLDaf4y4AtP3Bs5KcaIPCLoA074SA8,4874
+rhiza-0.5.0.dist-info/METADATA,sha256=OG-KEbNrDEd802tVMSUacQKuUH8SPOFV8pVxUbrAM3U,19323
+rhiza-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rhiza-0.5.0.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
+rhiza-0.5.0.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
+rhiza-0.5.0.dist-info/RECORD,,

rhiza/commands/hello.py

@@ -1,9 +0,0 @@
-"""Small demo CLI entrypoint for Rhiza tools.
-
-This module provides a minimal example command that prints a greeting.
-"""
-
-
-def hello():
-    """Print a friendly greeting from Rhiza."""
-    print("Hello from Rhiza!")

rhiza-0.4.0.dist-info/METADATA

@@ -1,35 +0,0 @@
-Metadata-Version: 2.4
-Name: rhiza
-Version: 0.4.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
-Project-URL: Issues, https://github.com/jebel-quant/rhiza/issues-cli
-Author: Thomas Schmelzer
-License: MIT
-License-File: LICENSE
-Keywords: ci,configuration,ruff,taskfile,templates
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Build Tools
-Requires-Python: >=3.11
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: pyyaml==6.0.3
-Requires-Dist: typer>=0.20.0
-Provides-Extra: dev
-Requires-Dist: marimo==0.18.4; extra == 'dev'
-Requires-Dist: pdoc>=16.0.0; extra == 'dev'
-Requires-Dist: pre-commit==4.5.0; extra == 'dev'
-Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
-Requires-Dist: pytest-html>=4.1.1; extra == 'dev'
-Requires-Dist: pytest==9.0.2; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# rhiza-cli
-Command line interface for Rhiza

rhiza-0.4.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-rhiza/__init__.py,sha256=wI9tfPnLnVJRkAZrjCmAOvU4cGn-2BOTN_MFZc0c0OQ,190
-rhiza/__main__.py,sha256=Lx0GqVZo6ymm0f18_uYB6E7_SOWwJNYjb73Vr31oLoM,236
-rhiza/cli.py,sha256=FCCqwWZMDRSeDm6GERvlXkck0RSxq3rzWqUh3Q0XVJk,1343
-rhiza/commands/__init__.py,sha256=X5ZRDDl37X8mEbiMWoqjTGlLhebkYhZ2SaLJd4KcHdw,166
-rhiza/commands/hello.py,sha256=_zhLoGLM21cm5XBYohwm5gbsNMpJ96ZxCcLwHrwhKVs,216
-rhiza/commands/inject.py,sha256=9MpS08TtOhjxIturzN2ejvEnrvGJUCGMjuS4JTuE2G4,5028
-rhiza-0.4.0.dist-info/METADATA,sha256=as92HkPHqiwg4HWlwGkR7CCCRdw5s8cLASHnP2luFek,1388
-rhiza-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-rhiza-0.4.0.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
-rhiza-0.4.0.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
-rhiza-0.4.0.dist-info/RECORD,,