rhiza 0.5.6__py3-none-any.whl → 0.6.1__py3-none-any.whl

rhiza/__init__.py

@@ -29,7 +29,7 @@ Validate your configuration:
 rhiza validate
 ```
 
-Customize `.github/template.yml`, then materialize templates into your project:
+Customize `.github/rhiza/template.yml`, then materialize templates into your project:
 
 ```bash
 rhiza materialize

rhiza/cli.py

@@ -71,10 +71,10 @@ def init(
         help="Target directory (defaults to current directory)",
     ),
 ):
-    r"""Initialize or validate .github/template.yml.
+    r"""Initialize or validate .github/rhiza/template.yml.
 
     \b
-    Creates a default `.github/template.yml` configuration file if one
+    Creates a default `.github/rhiza/template.yml` configuration file if one
     doesn't exist, or validates the existing configuration.
 
     \b
@@ -117,10 +117,10 @@ def materialize(
 
     \b
     Materializes configuration files from the template repository specified
-    in .github/template.yml into your project. This command:
+    in .github/rhiza/template.yml into your project. This command:
 
     \b
-    - Reads .github/template.yml configuration
+    - Reads .github/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
@@ -149,7 +149,7 @@ def validate(
 ):
     r"""Validate Rhiza template configuration.
 
-    Validates the .github/template.yml file to ensure it is syntactically
+    Validates the .github/rhiza/template.yml file to ensure it is syntactically
     correct and semantically valid.
 
     \b

rhiza/commands/__init__.py

@@ -8,7 +8,7 @@ configuration templates for Python projects.
 
 ### init
 
-Initialize or validate `.github/template.yml` in a target directory.
+Initialize or validate `.github/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/template.yml` file to ensure it is syntactically
+Validates the `.github/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,10 +1,11 @@
-"""Command to initialize or validate .github/template.yml.
+"""Command to initialize or validate .github/rhiza/template.yml.
 
 This module provides the init command that creates or validates the
-.github/template.yml file, which defines where templates come from
+.github/rhiza/template.yml file, which defines where templates come from
 and what paths are governed by Rhiza.
 """
 
+import shutil
 from pathlib import Path
 
 from loguru import logger
@@ -14,51 +15,140 @@ from rhiza.models import RhizaTemplate
 
 
 def init(target: Path):
-    """Initialize or validate .github/template.yml in the target repository.
+    """Initialize or validate .github/rhiza/template.yml in the target repository.
 
-    Creates a default .github/template.yml file if it doesn't exist,
+    Creates a default .github/rhiza/template.yml file if it doesn't exist,
     or validates an existing one.
 
     Args:
         target: Path to the target directory. Defaults to the current working directory.
+
+    Returns:
+        bool: True if validation passes, False otherwise.
     """
     # 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
+    # Create .github/rhiza directory structure if it doesn't exist
+    # This is where Rhiza stores its configuration
     github_dir = target / ".github"
-    github_dir.mkdir(parents=True, exist_ok=True)
+    rhiza_dir = github_dir / "rhiza"
+    logger.debug(f"Ensuring directory exists: {rhiza_dir}")
+    rhiza_dir.mkdir(parents=True, exist_ok=True)
 
-    # Define the template file path
+    # Check for old location and migrate if necessary
+    # TODO: This migration logic can be removed in a future version
+    # after users have had time to migrate
     template_file = github_dir / "template.yml"
+    if template_file.exists():
+        logger.warning(f"Found template.yml in old location: {template_file}")
+        logger.info(f"Copying to new location: {rhiza_dir / 'template.yml'}")
+        # Copy the file to the new location (not move, to preserve old one temporarily)
+        shutil.copyfile(template_file, rhiza_dir / "template.yml")
+
+    # Define the template file path (new location)
+    template_file = rhiza_dir / "template.yml"
 
     if not template_file.exists():
-        # Create default template.yml
-        logger.info("Creating default .github/template.yml")
+        # Create default template.yml with sensible defaults
+        logger.info("Creating default .github/rhiza/template.yml")
+        logger.debug("Using default template configuration")
 
+        # Default template points to the jebel-quant/rhiza repository
+        # and includes common Python project configuration files
         default_template = RhizaTemplate(
             template_repository="jebel-quant/rhiza",
             template_branch="main",
             include=[
-                ".github",
-                ".editorconfig",
-                ".gitignore",
-                ".pre-commit-config.yaml",
-                "Makefile",
-                "pytest.ini",
+                ".github",  # GitHub configuration and workflows
+                ".editorconfig",  # Editor configuration
+                ".gitignore",  # Git ignore patterns
+                ".pre-commit-config.yaml",  # Pre-commit hooks
+                "Makefile",  # Build and development tasks
+                "pytest.ini",  # Pytest configuration
+                "book",  # Documentation book
+                "presentation",  # Presentation materials
+                "tests",  # Test structure
             ],
         )
 
+        # Write the default template to the file
+        logger.debug(f"Writing default template to: {template_file}")
         default_template.to_yaml(template_file)
 
-        logger.success("✓ Created .github/template.yml")
+        logger.success("✓ Created .github/rhiza/template.yml")
         logger.info("""
 Next steps:
-  1. Review and customize .github/template.yml to match your project needs
+  1. Review and customize .github/rhiza/template.yml to match your project needs
   2. Run 'rhiza materialize' to inject templates into your repository
 """)
 
-    # the template file exists, so validate it
+    # Bootstrap basic Python project structure if it doesn't exist
+    # Get the name of the parent directory to use as package name
+    parent = target.parent.name
+    logger.debug(f"Parent directory name: {parent}")
+
+    # Create src/{parent} directory structure following src-layout
+    src_folder = target / "src" / parent
+    if not src_folder.exists():
+        logger.info(f"Creating Python package structure: {src_folder}")
+        src_folder.mkdir(parents=True)
+
+        # Create __init__.py to make it a proper Python package
+        init_file = src_folder / "__init__.py"
+        logger.debug(f"Creating {init_file}")
+        init_file.touch()
+
+        # Create main.py with a simple "Hello World" example
+        main_file = src_folder / "main.py"
+        logger.debug(f"Creating {main_file} with example code")
+        main_file.touch()
+
+        # Write example code to main.py
+        code = """\
+        def say_hello(name: str) -> str:
+            return f"Hello, {name}!"
+
+        def main():
+            print(say_hello("World"))
+
+        if __name__ == "__main__":
+            main()
+        """
+        main_file.write_text(code)
+        logger.success(f"Created Python package structure in {src_folder}")
+
+    # Create pyproject.toml if it doesn't exist
+    # This is the standard Python package metadata file (PEP 621)
+    pyproject_file = target / "pyproject.toml"
+    if not pyproject_file.exists():
+        logger.info("Creating pyproject.toml with basic project metadata")
+        pyproject_file.touch()
+
+        # Write minimal pyproject.toml content
+        code = f'''\
+        [project]
+        name = "{parent}"
+        version = "0.1.0"
+        description = "Add your description here"
+        readme = "README.md"
+        requires-python = ">=3.11"
+        dependencies = []
+        '''
+        pyproject_file.write_text(code)
+        logger.success("Created pyproject.toml")
+
+    # Create README.md if it doesn't exist
+    # Every project should have a README
+    readme_file = target / "README.md"
+    if not readme_file.exists():
+        logger.info("Creating README.md")
+        readme_file.touch()
+        logger.success("Created README.md")
+
+    # Validate the template file to ensure it's correct
+    # This will catch any issues early
+    logger.debug("Validating template configuration")
     return validate(target)

rhiza/commands/materialize.py

@@ -24,16 +24,27 @@ def __expand_paths(base_dir: Path, paths: list[str]) -> list[Path]:
 
     Given a list of paths relative to ``base_dir``, return a flat list of all
     individual files.
+
+    Args:
+        base_dir: The base directory to resolve paths against.
+        paths: List of relative path strings (files or directories).
+
+    Returns:
+        A flat list of Path objects representing all individual files found.
     """
     all_files = []
     for p in paths:
         full_path = base_dir / p
+        # Check if the path is a regular file
         if full_path.is_file():
             all_files.append(full_path)
+        # If it's a directory, recursively find all files within it
         elif full_path.is_dir():
             all_files.extend([f for f in full_path.rglob("*") if f.is_file()])
         else:
-            # Path does not exist — could log a warning
+            # Path does not exist in the cloned repository - skip it silently
+            # This can happen if the template repo doesn't have certain paths
+            logger.debug(f"Path not found in template repository: {p}")
             continue
     return all_files
 
@@ -52,22 +63,28 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
             the target repository.
         force (bool): Whether to overwrite existing files.
     """
+    # Resolve to absolute path to avoid any ambiguity
     target = target.resolve()
 
     logger.info(f"Target repository: {target}")
     logger.info(f"Rhiza branch: {branch}")
 
     # Set environment to prevent git from prompting for credentials
+    # This ensures non-interactive behavior during git operations
     git_env = os.environ.copy()
     git_env["GIT_TERMINAL_PROMPT"] = "0"
 
     # -----------------------
     # Handle target branch creation/checkout if specified
     # -----------------------
+    # When a target branch is specified, we either checkout an existing branch
+    # or create a new one. This allows users to materialize templates onto a
+    # separate branch for review before merging to main.
     if target_branch:
         logger.info(f"Creating/checking out target branch: {target_branch}")
         try:
-            # Check if branch already exists
+            # Check if branch already exists using git rev-parse
+            # Returns 0 if the branch exists, non-zero otherwise
             result = subprocess.run(
                 ["git", "rev-parse", "--verify", target_branch],
                 cwd=target,
@@ -77,7 +94,7 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
             )
 
             if result.returncode == 0:
-                # Branch exists, checkout
+                # Branch exists, switch to it
                 logger.info(f"Branch '{target_branch}' exists, checking out...")
                 subprocess.run(
                     ["git", "checkout", target_branch],
@@ -86,7 +103,7 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
                     env=git_env,
                 )
             else:
-                # Branch doesn't exist, create and checkout
+                # Branch doesn't exist, create it from current HEAD
                 logger.info(f"Creating new branch '{target_branch}'...")
                 subprocess.run(
                     ["git", "checkout", "-b", target_branch],
@@ -101,49 +118,81 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
     # -----------------------
     # Ensure Rhiza is initialized
     # -----------------------
+    # The init function creates template.yml if missing and validates it
+    # Returns True if valid, False otherwise
     valid = init(target)
 
     if not valid:
-        logger.error(f"Rhiza template is invalid. {target}")
+        logger.error(f"Rhiza template is invalid in: {target}")
+        logger.error("Please fix validation errors and try again")
         sys.exit(1)
 
-    template_file = target / ".github" / "template.yml"
+    # Load the template configuration from the validated file
+    template_file = target / ".github" / "rhiza" / "template.yml"
+    logger.debug(f"Loading template configuration from: {template_file}")
     template = RhizaTemplate.from_yaml(template_file)
 
+    # Extract template configuration settings
+    # These define where to clone from and what to materialize
     rhiza_repo = template.template_repository
+    # Use CLI arg if template doesn't specify a branch
     rhiza_branch = template.template_branch or branch
+    # Default to GitHub if not specified
     rhiza_host = template.template_host or "github"
     include_paths = template.include
     excluded_paths = template.exclude
 
+    # Validate that we have paths to include
     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")
 
+    # Log the paths we'll be including for transparency
     logger.info("Include paths:")
     for p in include_paths:
         logger.info(f"  - {p}")
 
+    # Log excluded paths if any are defined
+    if excluded_paths:
+        logger.info("Exclude paths:")
+        for p in excluded_paths:
+            logger.info(f"  - {p}")
+
     # -----------------------
     # Construct git clone URL based on host
     # -----------------------
+    # Support both GitHub and GitLab template repositories
     if rhiza_host == "gitlab":
         git_url = f"https://gitlab.com/{rhiza_repo}.git"
+        logger.debug(f"Using GitLab repository: {git_url}")
     elif rhiza_host == "github":
         git_url = f"https://github.com/{rhiza_repo}.git"
+        logger.debug(f"Using GitHub repository: {git_url}")
     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'.")
 
     # -----------------------
     # Sparse clone template repo
     # -----------------------
+    # Create a temporary directory for the sparse clone
+    # This will be cleaned up in the finally block
     tmp_dir = Path(tempfile.mkdtemp())
     materialized_files: list[Path] = []
 
     logger.info(f"Cloning {rhiza_repo}@{rhiza_branch} from {rhiza_host} into temporary directory")
+    logger.debug(f"Temporary directory: {tmp_dir}")
 
     try:
-        # Clone the repository - capture output to avoid blocking
+        # Clone the repository using sparse checkout for efficiency
+        # --depth 1: Only fetch the latest commit (shallow clone)
+        # --filter=blob:none: Don't download file contents initially
+        # --sparse: Enable sparse checkout mode
+        # This combination allows us to clone only the paths we need
         try:
+            logger.debug("Executing git clone with sparse checkout")
             subprocess.run(
                 [
                     "git",
@@ -162,14 +211,18 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
                 text=True,
                 env=git_env,
             )
+            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 '{rhiza_repo}' exists and branch '{rhiza_branch}' is valid")
             raise
 
-        # Initialize sparse checkout
+        # Initialize sparse checkout in cone mode
+        # Cone mode is more efficient and uses pattern matching
         try:
+            logger.debug("Initializing sparse checkout")
             subprocess.run(
                 ["git", "sparse-checkout", "init", "--cone"],
                 cwd=tmp_dir,
@@ -178,14 +231,17 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
                 text=True,
                 env=git_env,
             )
+            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
 
-        # Set sparse checkout paths
+        # Set sparse checkout paths to only checkout the files/directories we need
+        # --skip-checks: Don't validate that patterns match existing files
         try:
+            logger.debug(f"Setting sparse checkout paths: {include_paths}")
             subprocess.run(
                 ["git", "sparse-checkout", "set", "--skip-checks", *include_paths],
                 cwd=tmp_dir,
@@ -194,6 +250,7 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
                 text=True,
                 env=git_env,
             )
+            logger.debug("Sparse checkout paths configured")
         except subprocess.CalledProcessError as e:
             logger.error(f"Failed to set sparse checkout paths: {e}")
             if e.stderr:
@@ -203,35 +260,57 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
         # -----------------------
         # Expand include/exclude paths
         # -----------------------
+        # Convert directory paths to individual file paths for precise control
+        logger.debug("Expanding included paths to individual files")
         all_files = __expand_paths(tmp_dir, include_paths)
+        logger.info(f"Found {len(all_files)} file(s) in included paths")
 
+        # Create a set of excluded files for fast lookup
+        logger.debug("Expanding excluded paths to individual files")
         excluded_files = {f.resolve() for f in __expand_paths(tmp_dir, excluded_paths)}
+        if excluded_files:
+            logger.info(f"Excluding {len(excluded_files)} file(s) based on exclude patterns")
 
+        # Filter out excluded files from the list of files to copy
         files_to_copy = [f for f in all_files if f.resolve() not in excluded_files]
+        logger.info(f"Will materialize {len(files_to_copy)} file(s) to target repository")
 
         # -----------------------
         # Copy files into target repo
         # -----------------------
+        # Copy each file from the temporary clone to the target repository
+        # Preserve file metadata (timestamps, permissions) with copy2
+        logger.info("Copying files to target repository...")
         for src_file in files_to_copy:
+            # Calculate destination path maintaining relative structure
             dst_file = target / src_file.relative_to(tmp_dir)
             relative_path = dst_file.relative_to(target)
 
+            # Track this file for .rhiza.history
             materialized_files.append(relative_path)
 
+            # Check if file already exists and handle based on force flag
             if dst_file.exists() and not force:
                 logger.warning(f"{relative_path} already exists — use --force to overwrite")
                 continue
 
+            # Create parent directories if they don't exist
             dst_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Copy file with metadata preservation
             shutil.copy2(src_file, dst_file)
             logger.success(f"[ADD] {relative_path}")
 
     finally:
+        # Clean up the temporary directory
+        logger.debug(f"Cleaning up temporary directory: {tmp_dir}")
         shutil.rmtree(tmp_dir)
 
     # -----------------------
     # Warn about workflow files
     # -----------------------
+    # GitHub Actions workflow files require special permissions to modify
+    # Check if any of the materialized files are workflow files
     workflow_files = [p for p in materialized_files if p.parts[:2] == (".github", "workflows")]
 
     if workflow_files:
@@ -239,10 +318,14 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
             "Workflow files were materialized. Updating these files requires "
             "a token with the 'workflow' permission in GitHub Actions."
         )
+        logger.info(f"Workflow files affected: {len(workflow_files)}")
 
     # -----------------------
     # Write .rhiza.history
     # -----------------------
+    # This file tracks which files were materialized by Rhiza
+    # Useful for understanding which files came from the template
+    logger.debug("Writing .rhiza.history file")
     history_file = target / ".rhiza.history"
     with history_file.open("w", encoding="utf-8") as f:
         f.write("# Rhiza Template History\n")
@@ -251,10 +334,11 @@ def materialize(target: Path, branch: str, target_branch: str | None, force: boo
         f.write(f"# Template branch: {rhiza_branch}\n")
         f.write("#\n")
         f.write("# Files under template control:\n")
+        # Sort files for consistent ordering
         for file_path in sorted(materialized_files):
             f.write(f"{file_path}\n")
 
-    logger.info(f"Created {history_file.relative_to(target)} with {len(materialized_files)} files")
+    logger.info(f"Created {history_file.relative_to(target)} with {len(materialized_files)} file(s)")
 
     logger.success("Rhiza templates materialized successfully")
 

rhiza/commands/validate.py

@@ -1,6 +1,6 @@
 """Command for validating Rhiza template configuration.
 
-This module provides functionality to validate .github/template.yml files
+This module provides functionality to validate .github/rhiza/template.yml files
 to ensure they are syntactically correct and semantically valid.
 """
 
@@ -25,40 +25,65 @@ def validate(target: Path) -> bool:
     Returns:
         True if validation passes, False otherwise.
     """
-    # Convert to absolute path
+    # Convert to absolute path to avoid path resolution issues
     target = target.resolve()
 
-    # Check if target is a git repository
+    # Check if target is a git repository by looking for .git directory
+    # Rhiza only works with git repositories
     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")
         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}")
+    # Check for template.yml in both new and old locations
+    # New location: .github/rhiza/template.yml
+    # Old location: .github/template.yml (deprecated but still supported)
+    new_location = target / ".github" / "rhiza" / "template.yml"
+    deprecated_location = target / ".github" / "template.yml"
+
+    # Check which file(s) exist
+    new_exists = new_location.exists()
+    deprecated_exists = deprecated_location.exists()
+
+    if not (new_exists or deprecated_exists):
+        logger.error(f"No template file found at: {new_location}")
+        logger.error(f"Also checked deprecated location: {deprecated_location}")
         logger.info("Run 'rhiza init' to create a default template.yml")
         return False
 
-    logger.success(f"Found template file: {template_file}")
+    # Prefer the new location but support the old one with a warning
+    if new_exists:
+        logger.success(f"Template file exists: {new_location}")
+        template_file = new_location
+    else:
+        logger.warning(f"Template file exists but in old location: {deprecated_location}")
+        logger.warning("Consider moving it to .github/rhiza/template.yml")
+        template_file = deprecated_location
 
-    # Validate YAML syntax
+    # Validate YAML syntax by attempting to parse the file
+    logger.debug(f"Parsing YAML file: {template_file}")
     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}")
+        logger.error("Fix the YAML syntax errors and try again")
         return False
 
+    # Check if the file is completely empty
     if config is None:
         logger.error("template.yml is empty")
+        logger.error("Add configuration to template.yml or run 'rhiza init' to generate defaults")
         return False
 
     logger.success("YAML syntax is valid")
 
-    # Validate required fields
+    # Validate required fields exist and have correct types
+    # template-repository: Must be a string in 'owner/repo' format
+    # include: Must be a non-empty list of paths
+    logger.debug("Validating required fields")
     required_fields = {
         "template-repository": str,
         "include": list,
@@ -66,81 +91,103 @@ def validate(target: Path) -> bool:
 
     validation_passed = True
 
+    # Check each required field
     for field, expected_type in required_fields.items():
         if field not in config:
             logger.error(f"Missing required field: {field}")
+            logger.error(f"Add '{field}' to your template.yml")
             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__}"
             )
+            logger.error(f"Fix the type of '{field}' in template.yml")
             validation_passed = False
         else:
             logger.success(f"Field '{field}' is present and valid")
 
     # Validate template-repository format
+    # Must be in 'owner/repo' format (e.g., 'jebel-quant/rhiza')
+    logger.debug("Validating 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__}")
+            logger.error("Example: 'owner/repository'")
             validation_passed = False
         elif "/" not in repo:
             logger.error(f"template-repository must be in format 'owner/repo', got: {repo}")
+            logger.error("Example: 'jebel-quant/rhiza'")
             validation_passed = False
         else:
             logger.success(f"template-repository format is valid: {repo}")
 
     # Validate include paths
+    # Must be a non-empty list of strings
+    logger.debug("Validating 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__}")
+            logger.error("Example: include: ['.github', '.gitignore']")
             validation_passed = False
         elif len(include) == 0:
             logger.error("include list cannot be empty")
+            logger.error("Add at least one path to materialize")
             validation_passed = False
         else:
             logger.success(f"include list has {len(include)} path(s)")
+            # Log each included path for transparency
             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
+    # Validate optional fields if present
+    # template-branch: Branch name in the template repository
+    logger.debug("Validating 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}")
+            logger.warning("Example: 'main' or 'develop'")
         else:
             logger.success(f"template-branch is valid: {branch}")
 
+    # template-host: Git hosting platform (github or gitlab)
     if "template-host" in config:
         host = config["template-host"]
         if not isinstance(host, str):
             logger.warning(f"template-host should be a string, got {type(host).__name__}: {host}")
+            logger.warning("Must be 'github' or 'gitlab'")
         elif host not in ("github", "gitlab"):
             logger.warning(f"template-host should be 'github' or 'gitlab', got: {host}")
+            logger.warning("Other hosts are not currently supported")
         else:
             logger.success(f"template-host is valid: {host}")
 
+    # exclude: Optional list of paths to exclude from materialization
     if "exclude" in config:
         exclude = config["exclude"]
         if not isinstance(exclude, list):
             logger.warning(f"exclude should be a list, got {type(exclude).__name__}")
+            logger.warning("Example: exclude: ['.github/workflows/ci.yml']")
         else:
             logger.success(f"exclude list has {len(exclude)} path(s)")
+            # Log each excluded path for transparency
             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
+    # Final verdict on validation
+    logger.debug("Validation complete, determining final result")
     if validation_passed:
         logger.success("✓ Validation passed: template.yml is valid")
         return True
     else:
         logger.error("✗ Validation failed: template.yml has errors")
-        # raise AssertionError("Invalid template.yml")
+        logger.error("Fix the errors above and run 'rhiza validate' again")
         return False

rhiza/commands/welcome.py

@@ -15,11 +15,17 @@ def welcome():
 
     Shows a friendly greeting, explains Rhiza's purpose, and provides
     next steps for getting started with the tool.
+
+    This command is useful for new users to understand what Rhiza does
+    and how to get started. It provides a high-level overview without
+    performing any operations on the file system.
     """
+    # Construct a nicely formatted welcome message with ASCII art border
+    # The version is dynamically inserted from the package metadata
     welcome_message = f"""
 ╭───────────────────────────────────────────────────────────────╮
 │                                                               │
-│  🌿 Welcome to Rhiza v{__version__:<43} │
+│  🌿 Welcome to Rhiza v{__version__:<39} │
 │                                                               │
 ╰───────────────────────────────────────────────────────────────╯
 
@@ -38,7 +44,7 @@ Python projects using reusable templates stored in a central repository.
   1. Initialize a project:
      $ rhiza init
 
-  2. Customize .github/template.yml to match your needs
+  2. Customize .github/rhiza/template.yml to match your needs
 
   3. Materialize templates into your project:
      $ rhiza materialize
@@ -52,4 +58,5 @@ Python projects using reusable templates stored in a central repository.
 Happy templating! 🎉
 """
 
+    # Print the welcome message to stdout
     print(welcome_message)

rhiza/models.py

@@ -13,7 +13,7 @@ import yaml
 
 @dataclass
 class RhizaTemplate:
-    """Represents the structure of .github/template.yml.
+    """Represents the structure of .github/rhiza/template.yml.
 
     Attributes:
         template_repository: The GitHub or GitLab repository containing templates (e.g., "jebel-quant/rhiza").

{rhiza-0.5.6.dist-info → rhiza-0.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhiza
-Version: 0.5.6
+Version: 0.6.1
 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
@@ -41,6 +41,8 @@ Description-Content-Type: text/markdown
 
 Command-line interface for managing reusable configuration templates for modern Python projects.
 
+**📖 New to Rhiza? Check out the [Getting Started Guide](GETTING_STARTED.md) for a beginner-friendly introduction!**
+
 ## 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:
@@ -68,6 +70,7 @@ Rhiza is a CLI tool that helps you maintain consistent configuration across mult
 
 For more detailed information, see:
 
+- **[Getting Started Guide](GETTING_STARTED.md)** - Beginner-friendly introduction and walkthrough
 - **[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
@@ -81,6 +84,35 @@ For more detailed information, see:
 pip install rhiza
 ```
 
+To update to the latest version:
+
+```bash
+pip install --upgrade rhiza
+```
+
+### Using uvx (run without installation)
+
+[uvx](https://docs.astral.sh/uv/) is part of the `uv` package manager and allows you to run CLI tools directly without installing them:
+
+```bash
+uvx rhiza --help
+```
+
+With uvx, you don't need to install rhiza globally. Each time you run `uvx rhiza`, it will automatically use the latest version available on PyPI. To ensure you're using the latest version, simply run your command - uvx will fetch updates as needed:
+
+```bash
+# Always uses the latest version
+uvx rhiza init
+uvx rhiza materialize
+uvx rhiza validate
+```
+
+If you want to use a specific version:
+
+```bash
+uvx rhiza@0.5.6 --help
+```
+
 ### From source
 
 ```bash
@@ -112,11 +144,11 @@ rhiza --help
    rhiza init
    ```
 
-   This creates a `.github/template.yml` file with default configuration.
+   This creates a `.github/rhiza/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.
+   Edit `.github/rhiza/template.yml` to specify which files/directories to include from your template repository.
 
 3. **Materialize templates into your project:**
 
@@ -132,13 +164,13 @@ rhiza --help
    rhiza validate
    ```
 
-   This checks that your `.github/template.yml` is correctly formatted and valid.
+   This checks that your `.github/rhiza/template.yml` is correctly formatted and valid.
 
 ## Commands
 
 ### `rhiza init`
 
-Initialize or validate `.github/template.yml` in a target directory.
+Initialize or validate `.github/rhiza/template.yml` in a target directory.
 
 **Usage:**
 
@@ -152,7 +184,7 @@ rhiza init [TARGET]
 
 **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`.
+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`.
 
 **Examples:**
 
@@ -172,18 +204,18 @@ rhiza init ..
 When creating a new template file:
 ```
 [INFO] Initializing Rhiza configuration in: /path/to/project
-[INFO] Creating default .github/template.yml
-✓ Created .github/template.yml
+[INFO] Creating default .github/rhiza/template.yml
+✓ Created .github/rhiza/template.yml
 
 Next steps:
-  1. Review and customize .github/template.yml to match your project needs
+  1. Review and customize .github/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/template.yml
+✓ Found template file: /path/to/project/.github/rhiza/template.yml
 ✓ YAML syntax is valid
 ✓ Field 'template-repository' is present and valid
 ✓ Field 'include' is present and valid
@@ -218,7 +250,7 @@ rhiza materialize [OPTIONS] [TARGET]
 
 Materializes template files from the configured template repository into your target project. This command:
 
-1. Reads the `.github/template.yml` configuration
+1. Reads the `.github/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
@@ -300,7 +332,7 @@ rhiza validate [TARGET]
 
 **Description:**
 
-Validates the `.github/template.yml` file to ensure it is syntactically correct and semantically valid. This performs authoritative validation including:
+Validates the `.github/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
@@ -331,7 +363,7 @@ rhiza validate ..
 
 ```
 [INFO] Validating template configuration in: /path/to/project
-✓ Found template file: /path/to/project/.github/template.yml
+✓ Found template file: /path/to/project/.github/rhiza/template.yml
 ✓ YAML syntax is valid
 ✓ Field 'template-repository' is present and valid
 ✓ Field 'include' is present and valid
@@ -355,7 +387,7 @@ rhiza validate ..
 or
 
 ```
-[ERROR] Template file not found: /path/to/project/.github/template.yml
+[ERROR] Template file not found: /path/to/project/.github/rhiza/template.yml
 [INFO] Run 'rhiza materialize' or 'rhiza init' to create a default template.yml
 ```
 
@@ -363,7 +395,7 @@ or
 
 ## Configuration
 
-Rhiza uses a `.github/template.yml` file to define template sources and what to include in your project.
+Rhiza uses a `.github/rhiza/template.yml` file to define template sources and what to include in your project.
 
 ### Configuration File Format
 
@@ -504,7 +536,7 @@ git init
 rhiza init
 
 # Review the generated template.yml
-cat .github/template.yml
+cat .github/rhiza/template.yml
 
 # Materialize templates
 rhiza materialize
@@ -539,7 +571,7 @@ git commit -m "chore: update rhiza templates"
 
 ### Example 3: Using a custom template repository
 
-Edit `.github/template.yml`:
+Edit `.github/rhiza/template.yml`:
 
 ```yaml
 template-repository: myorg/my-templates
@@ -561,7 +593,7 @@ rhiza materialize --force
 
 ### Example 4: Using a GitLab template repository
 
-Edit `.github/template.yml`:
+Edit `.github/rhiza/template.yml`:
 
 ```yaml
 template-repository: mygroup/python-templates
@@ -701,7 +733,7 @@ Releasing and Versioning
   post-release     perform post-release tasks
 
 Meta
-  sync             sync with template repository as defined in .github/template.yml
+  sync             sync with template repository as defined in .github/rhiza/template.yml
   help             Display this help message
   customisations   list available customisation scripts
   update-readme    update README.md with current Makefile help output
@@ -773,7 +805,7 @@ export PATH="$HOME/.local/bin:$PATH"
 ### Template validation fails
 
 Check that:
-1. Your `.github/template.yml` file exists
+1. Your `.github/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`
@@ -805,11 +837,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/template.yml` to specify "github" (default) or "gitlab".
+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".
 
 **Q: How do I use a GitLab repository as a template source?**
 
-A: Add `template-host: gitlab` to your `.github/template.yml` file. For example:
+A: Add `template-host: gitlab` to your `.github/rhiza/template.yml` file. For example:
 ```yaml
 template-repository: mygroup/myproject
 template-host: gitlab
@@ -824,15 +856,23 @@ 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/template.yml` configuration file. `materialize` reads that configuration and actually copies the template files into your project.
+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.
 
 **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: How do I update rhiza-cli itself?**
+
+A: The update method depends on how you installed rhiza:
+
+- **Using pip**: Run `pip install --upgrade rhiza`
+- **Using uvx**: No action needed! `uvx` automatically uses the latest version each time you run it. Just run your command: `uvx rhiza <command>`
+- **From source**: Run `git pull` in the repository directory and then `pip install -e .` again
+
 **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.
+A: Yes, edit the `include` and `exclude` lists in `.github/rhiza/template.yml` to control exactly which files are copied.
 
 ## Acknowledgments
 

rhiza-0.6.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+rhiza/__init__.py,sha256=iW3niLBjwRKxcMhIV_1eb78putjUTo2tbZsadofluJk,1939
+rhiza/__main__.py,sha256=Lx0GqVZo6ymm0f18_uYB6E7_SOWwJNYjb73Vr31oLoM,236
+rhiza/cli.py,sha256=faCIOKDzEDRvL4doLZhiIAyHUUGESGrwWLtjLjimCUY,5111
+rhiza/models.py,sha256=fW9lofkkid-bghk2bXEgBdGbZ4scSqG726fMrVfKX_M,3454
+rhiza/commands/__init__.py,sha256=Z5CeMh7ylX27H6dvwqRbEKzYo5pwQq-5TyTxABUSaQg,1848
+rhiza/commands/init.py,sha256=Hrox_o8hnyWMkx4SuE0rd4jqGIBEl_V_wh7BAiW9IFU,5726
+rhiza/commands/materialize.py,sha256=Sxuvh9GLDRkcl6LVTjvWo5bkYzQ5GLwlhOwLo2jNptI,14387
+rhiza/commands/validate.py,sha256=cxStfXbY_ifsc_yRDCg0TOnv8jG05hxE9rteta-X9hQ,8093
+rhiza/commands/welcome.py,sha256=w3BziR042o6oYincd3EqDsFzF6qqInU7iYhWjF3yJqY,2382
+rhiza-0.6.1.dist-info/METADATA,sha256=tx98rTT3r_muUBFnlZ_L8KxDbzhQqC_sAocefsoGLf8,22742
+rhiza-0.6.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rhiza-0.6.1.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
+rhiza-0.6.1.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
+rhiza-0.6.1.dist-info/RECORD,,

rhiza-0.5.6.dist-info/RECORD

@@ -1,14 +0,0 @@
-rhiza/__init__.py,sha256=1jfkGAONm7dH4KwYjvNEyuxrQ-1m2YncxREYCJnTrHA,1933
-rhiza/__main__.py,sha256=Lx0GqVZo6ymm0f18_uYB6E7_SOWwJNYjb73Vr31oLoM,236
-rhiza/cli.py,sha256=Jqe285OWOvbvembO5DXTVITfnFefsjVGZCJuK3EKRT8,5081
-rhiza/models.py,sha256=R2nu_bf-j-U0kPfQXg6u-MSykrdGO9ixOzZoWy8mLCc,3448
-rhiza/commands/__init__.py,sha256=lIkN15MIat-wn9CB1cgUjTzTUQB95LBBAKFK1sGHdCc,1836
-rhiza/commands/init.py,sha256=QsOV_VBnRfSPebydH-fMe3haadboNIAYlOpAIYHtgUs,1936
-rhiza/commands/materialize.py,sha256=FUStZGUr2oDEC-M8V61JnV3W7USj-VS0EHI10a0Mn6Y,9378
-rhiza/commands/validate.py,sha256=_0t9kfylMncm9JmKULn5e7V71XcQdFjlrtuOqZeshPM,5282
-rhiza/commands/welcome.py,sha256=GpDbRSIUigaxS7Di9RIpl2jCOFOlhlQT2vNvCzBR-8U,2001
-rhiza-0.5.6.dist-info/METADATA,sha256=PI_8F886fva98V4uq_toyZ9O8gC8tnOPy-FPSUn0eE4,21278
-rhiza-0.5.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-rhiza-0.5.6.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
-rhiza-0.5.6.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
-rhiza-0.5.6.dist-info/RECORD,,