rhiza 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

rhiza/commands/init.py

@@ -22,44 +22,60 @@ def init(target: Path):
 
     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/rhiza 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"
     rhiza_dir = github_dir / "rhiza"
+    logger.debug(f"Ensuring directory exists: {rhiza_dir}")
     rhiza_dir.mkdir(parents=True, exist_ok=True)
 
-    # check the old location and copy over if existent
-    # todo: remove this logic later
+    # 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():
-        # move the file into rhiza_dir
+        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
+    # Define the template file path (new location)
     template_file = rhiza_dir / "template.yml"
 
     if not template_file.exists():
-        # Create default 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/rhiza/template.yml")
@@ -69,5 +85,70 @@ Next steps:
   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,53 +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)
 
-    # init will make sure the template_file exists at the new location!
-
     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)
 
+    # 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)
 
-    # init will make sure the template_file exists at the new location!
-
+    # 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",
@@ -166,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,
@@ -182,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,
@@ -198,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:
@@ -207,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:
@@ -243,11 +318,54 @@ 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
+    # Clean up orphaned files
     # -----------------------
+    # Read the old .rhiza.history file to find files that are no longer
+    # part of the current materialization and should be deleted
     history_file = target / ".rhiza.history"
+    previously_tracked_files: set[Path] = set()
+
+    if history_file.exists():
+        logger.debug("Reading existing .rhiza.history file")
+        with history_file.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                # Skip comments and empty lines
+                if line and not line.startswith("#"):
+                    previously_tracked_files.add(Path(line))
+
+        logger.debug(f"Found {len(previously_tracked_files)} file(s) in previous .rhiza.history")
+
+    # Convert materialized_files list to a set for comparison
+    currently_materialized_files = set(materialized_files)
+
+    # Find orphaned files (in old history but not in new materialization)
+    orphaned_files = previously_tracked_files - currently_materialized_files
+
+    if orphaned_files:
+        logger.info(f"Found {len(orphaned_files)} orphaned file(s) no longer maintained by template")
+        for file_path in sorted(orphaned_files):
+            full_path = target / file_path
+            if full_path.exists():
+                try:
+                    full_path.unlink()
+                    logger.success(f"[DEL] {file_path}")
+                except Exception as e:
+                    logger.warning(f"Failed to delete {file_path}: {e}")
+            else:
+                logger.debug(f"Skipping {file_path} (already deleted)")
+    else:
+        logger.debug("No orphaned files to clean up")
+
+    # -----------------------
+    # 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")
     with history_file.open("w", encoding="utf-8") as f:
         f.write("# Rhiza Template History\n")
         f.write("# This file lists all files managed by the Rhiza template.\n")
@@ -255,10 +373,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"Updated {history_file.relative_to(target)} with {len(materialized_files)} file(s)")
 
     logger.success("Rhiza templates materialized successfully")
 

rhiza/commands/validate.py

@@ -25,49 +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 one of the possible template.yml exists
-    template_file = [target / ".github" / "rhiza" / "template.yml", target / ".github" / "template.yml"]
+    # 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 the exists
-    exists = [file.exists() for file in template_file]
+    # Check which file(s) exist
+    new_exists = new_location.exists()
+    deprecated_exists = deprecated_location.exists()
 
-    if not any(exists):
-        logger.error(f"No template file found: {template_file}")
+    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
 
-    if exists[0]:
-        logger.success(f"Template file exists: {template_file[0]}")
-        template_file = template_file[0]
+    # 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: {template_file[1]}")
-        template_file = template_file[1]
+        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,
@@ -75,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,7 +15,13 @@ 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"""
 ╭───────────────────────────────────────────────────────────────╮
 │                                                               │
@@ -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-0.6.0.dist-info → rhiza-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhiza
-Version: 0.6.0
+Version: 0.7.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
@@ -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

rhiza-0.7.0.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=jmXH9Fb3lkktxgdWtZ2cQk0wyURleWzHvQN6n_DNZ7U,16049
+rhiza/commands/validate.py,sha256=cxStfXbY_ifsc_yRDCg0TOnv8jG05hxE9rteta-X9hQ,8093
+rhiza/commands/welcome.py,sha256=w3BziR042o6oYincd3EqDsFzF6qqInU7iYhWjF3yJqY,2382
+rhiza-0.7.0.dist-info/METADATA,sha256=00UAERh_SGq5WoD8xZsbl83SdNZBO8QjBCP0Al-qQKM,22742
+rhiza-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+rhiza-0.7.0.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
+rhiza-0.7.0.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
+rhiza-0.7.0.dist-info/RECORD,,

rhiza-0.6.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-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=1JFvT-Y8eYcjqhM7xaaRCBmelKlQNmxaVgyCOeDvydw,2310
-rhiza/commands/materialize.py,sha256=aQcBp8VTBt5DPxyDC2VcgngqTdLDxqbYd5F_B2UF2_A,9534
-rhiza/commands/validate.py,sha256=oYCZnTxr39l20jr6DhBpFtMURv7jULSV8Ii6it8KHxs,5628
-rhiza/commands/welcome.py,sha256=gLgahbfBCBhmZPxWKywx7kYGBTMCVyyVVnly9uKdJv0,2007
-rhiza-0.6.0.dist-info/METADATA,sha256=GrFAnXe3MUq0evyRHFQDE4Yv3mUziu2LKz0wrYFN1fQ,22523
-rhiza-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-rhiza-0.6.0.dist-info/entry_points.txt,sha256=NAwZUpbXvfKv50a_Qq-PxMHl3lcjAyZO63IBeuUNgfY,45
-rhiza-0.6.0.dist-info/licenses/LICENSE,sha256=4m5X7LhqX-6D0Ks79Ys8CLpmza8cxDG34g4S9XSNAGY,1077
-rhiza-0.6.0.dist-info/RECORD,,