rhiza 0.3.0__tar.gz → 0.5.0__tar.gz

{rhiza-0.3.0 → rhiza-0.5.0}/.github/actions/setup-project/action.yml

@@ -4,8 +4,7 @@
 # Action: Setup Project (composite action)
 #
 # Purpose: Bootstrap a Python project in GitHub Actions by:
-#   - Installing Task, uv, and uvx into a local ./bin directory
-#   - Optionally rendering the repository from a Copier template for tests
+#   - Installing Task, uv, and uvx
 #   - Detecting presence of pyproject.toml and exposing it as an output
 #   - Creating a virtual environment with uv and syncing dependencies
 #
@@ -43,28 +42,7 @@ runs:
     - name: Install uv
       uses: astral-sh/setup-uv@v7
       with:
-        version: "0.9.17"
-
-    - name: Render the project
-      if: hashFiles('tests/resources/render.yml') != ''
-      shell: bash
-      run: |
-        pip install copier
-
-        # Render the current folder in-place
-        copier copy . . \
-          --data-file ./tests/resources/render.yml \
-          --force \
-          --overwrite \
-          --quiet
-
-        # Delete all remaining .jinja files
-        find . -type f -name "*.jinja" -exec rm -f {} +
-
-        # Delete all folders that still contain {{ ... }}
-        find . -depth -type d -name "*{{*}}*" -exec rm -rf {} +
-
-        ls -R
+        version: "0.9.18"
 
     - name: Check for pyproject.toml
       id: check_pyproject

rhiza-0.5.0/.github/copilot-instructions.md

@@ -0,0 +1,349 @@
+# GitHub Copilot Instructions for rhiza-cli
+
+## Project Overview
+
+Rhiza is a command-line interface (CLI) tool for managing reusable configuration templates for modern Python projects. It provides commands for initializing, validating, and materializing configuration templates across projects.
+
+**Repository:** <https://github.com/jebel-quant/rhiza-cli>
+
+## Technology Stack
+
+- **Language:** Python 3.11+ (supports 3.11, 3.12, 3.13, 3.14)
+- **Package Manager:** uv (fast Python package installer and resolver)
+- **CLI Framework:** Typer
+- **Testing:** pytest with coverage reporting
+- **Linting/Formatting:** Ruff
+- **Build System:** Hatchling
+- **Pre-commit Hooks:** YAML/TOML validation, Ruff, markdownlint, actionlint
+
+## Project Structure
+
+```text
+rhiza-cli/
+├── src/rhiza/          # Main source code
+│   ├── cli.py          # CLI entry points (Typer app)
+│   └── commands/       # Command implementations
+├── tests/              # Test suite
+├── book/               # Documentation and Marimo notebooks
+├── .github/            # GitHub workflows and scripts
+├── pyproject.toml      # Project configuration
+├── ruff.toml           # Linting configuration
+└── Makefile            # Development tasks
+```
+
+## Coding Standards
+
+### Python Style
+
+- **Line length:** Maximum 120 characters
+- **Quotes:** Use double quotes for strings
+- **Indentation:** 4 spaces (no tabs)
+- **Docstrings:** Google style convention (required for all public modules, classes, and functions)
+- **Type hints:** Not strictly enforced but encouraged
+- **Import sorting:** Automatic via isort (part of Ruff)
+
+### Linting Rules
+
+The project uses Ruff with the following rule sets:
+
+- **D** (pydocstyle): Docstring style enforcement
+- **E** (pycodestyle): PEP 8 style guide errors
+- **F** (pyflakes): Logical error detection
+- **I** (isort): Import sorting
+- **N** (pep8-naming): PEP 8 naming conventions
+- **W** (pycodestyle): PEP 8 warnings
+- **UP** (pyupgrade): Modern Python syntax
+
+**Exception:** Tests allow assert statements (S101 ignored in tests/)
+
+### Docstring Requirements
+
+- All public modules, classes, functions, and methods must have docstrings
+- Use Google docstring convention
+- Include magic methods like `__init__` (D105, D107 enforced)
+- Use multi-line format with summary line, then blank line, then details
+
+Example:
+
+```python
+def my_function(arg1: str, arg2: int) -> bool:
+    """Short summary of what the function does.
+
+    Longer description if needed. Explain complex behavior,
+    side effects, or important context.
+
+    Args:
+        arg1: Description of arg1
+        arg2: Description of arg2
+
+    Returns:
+        Description of return value (bool)
+    """
+    return True
+```
+
+## Development Workflow
+
+### Setup
+
+```bash
+make install    # Install dependencies with uv
+```
+
+### Common Commands
+
+```bash
+make fmt        # Run linters and formatters (pre-commit)
+make test       # Run tests with coverage
+make docs       # Generate documentation with pdoc
+make clean      # Clean build artifacts
+make help       # Show all available commands
+```
+
+### Testing
+
+- Use pytest for all tests
+- Place tests in `tests/` directory
+- Test files should match pattern `test_*.py`
+- Aim for good coverage of new code
+- Run tests with `make test` before submitting changes
+
+### Pre-commit Hooks
+
+The project uses pre-commit hooks that run automatically on commit:
+
+- YAML/TOML validation
+- Ruff linting and formatting
+- Markdown linting (MD013 disabled for long lines)
+- GitHub workflow validation
+- Renovate config validation
+- README.md auto-update with Makefile help
+
+## Architecture Notes
+
+### CLI Structure
+
+The CLI uses Typer for command definitions. Commands are thin wrappers in `cli.py` that delegate to implementations in `rhiza.commands.*`:
+
+- `init`: Initialize or validate `.github/template.yml`
+- `materialize` (alias `inject`): Apply templates to a target repository
+- `validate`: Validate template configuration
+
+### Command Implementation Pattern
+
+1. Command defined in `src/rhiza/cli.py` using Typer decorators
+2. Implementation logic in `src/rhiza/commands/*.py`
+3. Commands use `loguru` for logging
+4. Use `Path` from `pathlib` for file operations
+
+## Best Practices
+
+1. **Minimal changes:** Make surgical, focused changes
+2. **Type hints:** Use when they improve clarity
+3. **Error handling:** Use appropriate exceptions, log errors clearly
+4. **Documentation:** Update docstrings when changing function signatures
+5. **Tests:** Add tests for new functionality
+6. **Imports:** Keep imports organized (isort handles this automatically)
+7. **File headers:** Include repository attribution comment at top of new files:
+
+   ```python
+   # This file is part of the jebel-quant/rhiza repository
+   # (https://github.com/jebel-quant/rhiza).
+   #
+   ```
+
+## Dependencies
+
+### Core Dependencies
+
+See `pyproject.toml` for exact versions. Key dependencies:
+
+- `typer` - CLI framework
+- `loguru` - Logging
+- `PyYAML` - YAML parsing
+
+### Development Dependencies
+
+See `pyproject.toml` for complete list. Key dev dependencies:
+
+- `pytest`, `pytest-cov`, `pytest-html` - Testing
+- `pre-commit` - Git hooks
+- `marimo` - Notebook support
+- `pdoc` - Documentation generation
+
+## Common Patterns
+
+### Path Handling
+
+```python
+from pathlib import Path
+
+target = Path(".")  # Use Path objects, not strings
+if target.exists():
+    # Do something
+```
+
+### Logging
+
+```python
+from loguru import logger
+
+logger.info("Starting operation")
+logger.error("Something went wrong")
+```
+
+### CLI Arguments
+
+```python
+import typer
+
+@app.command()
+def my_command(
+    target: Path = typer.Argument(
+        default=Path("."),
+        exists=True,
+        help="Description"
+    ),
+):
+    """Command docstring."""
+```
+
+## Security Considerations
+
+- **No secrets in code:** Never commit API keys, passwords, or sensitive data
+- **Path traversal:** Always use `Path.resolve()` to normalize paths and prevent directory traversal attacks
+- **Input validation:** Validate all user inputs, especially file paths and command arguments
+- **YAML parsing:** Use safe YAML loading (PyYAML uses safe loading by default)
+- **File permissions:** Be mindful of file permissions when creating files
+
+## Error Handling Patterns
+
+### Exception Handling
+
+```python
+from loguru import logger
+from pathlib import Path
+
+def safe_operation(path: Path):
+    """Safe operation with proper error handling."""
+    try:
+        # Normalize path to prevent traversal
+        path = path.resolve()
+        
+        if not path.exists():
+            logger.error(f"Path does not exist: {path}")
+            raise FileNotFoundError(f"Path not found: {path}")
+            
+        # Perform operation
+        return True
+        
+    except PermissionError as e:
+        logger.error(f"Permission denied: {e}")
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
+        raise
+```
+
+### CLI Exit Codes
+
+Use Typer's `Exit` for non-zero exit codes on errors:
+
+```python
+import typer
+
+if not success:
+    raise typer.Exit(code=1)
+```
+
+## Common Tasks
+
+### Adding a New Command
+
+1. Create a new file in `src/rhiza/commands/` (e.g., `newcommand.py`)
+2. Implement the command logic with proper docstrings
+3. Add a wrapper in `src/rhiza/cli.py` using Typer decorators
+4. Add tests in `tests/` for the new command
+5. Update documentation if needed
+
+Example:
+
+```python
+# In src/rhiza/commands/newcommand.py
+from pathlib import Path
+from loguru import logger
+
+def my_new_command(target: Path):
+    """Execute the new command.
+    
+    Parameters
+    ----------
+    target:
+        Path to the target directory.
+    """
+    target = target.resolve()
+    logger.info(f"Running new command on: {target}")
+    # Implementation here
+```
+
+```python
+# In src/rhiza/cli.py
+from rhiza.commands.newcommand import my_new_command
+
+@app.command()
+def newcommand(
+    target: Path = typer.Argument(
+        default=Path("."),
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        help="Target directory"
+    ),
+):
+    """Short description of the command."""
+    my_new_command(target)
+```
+
+### Running the CLI in Development
+
+```bash
+# Install in editable mode
+make install
+
+# Run the CLI
+uv run rhiza --help
+uv run rhiza init
+uv run rhiza materialize --branch main
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Import errors after adding dependencies:**
+- Run `make install` to sync dependencies
+- Ensure `pyproject.toml` is updated with new dependencies
+
+**Linting failures:**
+- Run `make fmt` to auto-fix most issues
+- Check `ruff.toml` for configured rules
+- Ensure docstrings follow Google convention
+
+**Test failures:**
+- Run `make test` to see detailed output
+- Check test coverage report in `_tests/html-coverage/`
+- Ensure new code has corresponding tests
+
+**Pre-commit hook failures:**
+- Run `make fmt` to fix formatting issues
+- Check `.pre-commit-config.yaml` for hook configuration
+- Install hooks with `uv run pre-commit install`
+
+## When Making Changes
+
+1. Run `make fmt` to ensure code follows style guidelines
+2. Run `make test` to verify tests pass
+3. Update docstrings if changing public APIs
+4. Add tests for new functionality
+5. Keep changes focused and minimal
+6. Follow existing code patterns and conventions

rhiza-0.5.0/.github/scripts/sync.sh

@@ -0,0 +1,310 @@
+#!/bin/sh
+# Sync configuration files from template repository
+# - Reads configuration from .github/template.yml
+# - Downloads specified files from the template repository
+# - Copies them to the current repository
+#
+# This script is POSIX-sh compatible and provides manual sync capability
+# for repositories that use jebel-quant/rhiza as a template.
+
+set -e
+
+BLUE="\033[36m"
+RED="\033[31m"
+GREEN="\033[32m"
+YELLOW="\033[33m"
+RESET="\033[0m"
+
+TEMPLATE_CONFIG=".github/template.yml"
+TEMP_DIR="/tmp/rhiza-sync-$$"
+
+show_usage() {
+  printf "Usage: %s [OPTIONS]\n\n" "$0"
+  printf "Sync configuration files from the template repository.\n\n"
+  printf "Options:\n"
+  printf "  -h, --help     Show this help message\n"
+  printf "  --dry-run      Show what would be synced without making changes\n\n"
+  printf "Configuration:\n"
+  printf "  Reads from %s to determine:\n" "$TEMPLATE_CONFIG"
+  printf "  - template-repository: Source repository (e.g., 'jebel-quant/rhiza')\n"
+  printf "  - template-branch: Branch to sync from (e.g., 'main')\n"
+  printf "  - include: Files/directories to sync\n"
+  printf "  - exclude: Files/directories to skip (optional)\n\n"
+  printf "Example %s:\n" "$TEMPLATE_CONFIG"
+  printf "  template-repository: \"jebel-quant/rhiza\"\n"
+  printf "  template-branch: \"main\"\n"
+  printf "  include: |\n"
+  printf "    .github\n"
+  printf "    Makefile\n"
+  printf "    ruff.toml\n"
+}
+
+DRY_RUN=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help)
+      show_usage
+      exit 0
+      ;;
+    --dry-run)
+      DRY_RUN="true"
+      shift
+      ;;
+    *)
+      printf "%b[ERROR] Unknown option: %s%b\n" "$RED" "$1" "$RESET"
+      show_usage
+      exit 1
+      ;;
+  esac
+done
+
+# Check if template.yml exists
+if [ ! -f "$TEMPLATE_CONFIG" ]; then
+  printf "%b[ERROR] Template configuration not found: %s%b\n" "$RED" "$TEMPLATE_CONFIG" "$RESET"
+  printf "\nThis repository is not configured for template syncing.\n"
+  printf "Create %s with the following content:\n\n" "$TEMPLATE_CONFIG"
+  printf "  template-repository: \"jebel-quant/rhiza\"\n"
+  printf "  template-branch: \"main\"\n"
+  printf "  include: |\n"
+  printf "    .github\n"
+  printf "    Makefile\n"
+  printf "    ruff.toml\n"
+  exit 1
+fi
+
+# Parse template.yml to extract configuration
+# This is a simple parser that works with basic YAML structure
+printf "%b[INFO] Reading configuration from %s...%b\n" "$BLUE" "$TEMPLATE_CONFIG" "$RESET"
+
+TEMPLATE_REPO=""
+TEMPLATE_BRANCH=""
+INCLUDE_LIST=""
+EXCLUDE_LIST=""
+
+# Simple YAML parser
+in_multiline=""
+
+while IFS= read -r line || [ -n "$line" ]; do
+  # Skip comments and empty lines
+  case "$line" in
+    \#*|"") continue ;;
+  esac
+
+  # Check if line starts with spaces by looking at first character
+  first_char=$(printf '%s' "$line" | cut -c1)
+
+  if [ "$first_char" = " " ] || [ "$first_char" = "$(printf '\t')" ]; then
+    # This is indented content (part of a multiline block)
+    if [ -n "$in_multiline" ]; then
+      # Remove leading spaces
+      item=$(echo "$line" | sed 's/^[[:space:]]*//')
+      if [ -n "$item" ]; then
+        if [ "$in_multiline" = "include" ]; then
+          INCLUDE_LIST="${INCLUDE_LIST}${item}
+"
+        elif [ "$in_multiline" = "exclude" ]; then
+          EXCLUDE_LIST="${EXCLUDE_LIST}${item}
+"
+        fi
+      fi
+    fi
+  else
+    # This is a key line (not indented)
+    case "$line" in
+      template-repository:*)
+        TEMPLATE_REPO=$(echo "$line" | sed 's/^template-repository:[[:space:]]*//' | sed 's/"//g' | sed "s/'//g")
+        in_multiline=""
+        ;;
+      template-branch:*)
+        TEMPLATE_BRANCH=$(echo "$line" | sed 's/^template-branch:[[:space:]]*//' | sed 's/"//g' | sed "s/'//g")
+        in_multiline=""
+        ;;
+      include:*)
+        in_multiline="include"
+        ;;
+      exclude:*)
+        in_multiline="exclude"
+        ;;
+    esac
+  fi
+done < "$TEMPLATE_CONFIG"
+
+# Validate required fields
+if [ -z "$TEMPLATE_REPO" ]; then
+  printf "%b[ERROR] template-repository not found in %s%b\n" "$RED" "$TEMPLATE_CONFIG" "$RESET"
+  exit 1
+fi
+
+if [ -z "$TEMPLATE_BRANCH" ]; then
+  printf "%b[WARN] template-branch not specified, using 'main'%b\n" "$YELLOW" "$RESET"
+  TEMPLATE_BRANCH="main"
+fi
+
+if [ -z "$INCLUDE_LIST" ]; then
+  printf "%b[ERROR] include list is empty in %s%b\n" "$RED" "$TEMPLATE_CONFIG" "$RESET"
+  exit 1
+fi
+
+printf "%b[INFO] Template repository: %s%b\n" "$GREEN" "$TEMPLATE_REPO" "$RESET"
+printf "%b[INFO] Template branch: %s%b\n" "$GREEN" "$TEMPLATE_BRANCH" "$RESET"
+printf "%b[INFO] Files to sync:%b\n" "$GREEN" "$RESET"
+echo "$INCLUDE_LIST" | while IFS= read -r item; do
+  [ -n "$item" ] && printf "  - %s\n" "$item"
+done || true
+
+if [ -n "$EXCLUDE_LIST" ]; then
+  printf "%b[INFO] Files to exclude:%b\n" "$YELLOW" "$RESET"
+  echo "$EXCLUDE_LIST" | while IFS= read -r item; do
+    [ -n "$item" ] && printf "  - %s\n" "$item"
+  done || true
+fi
+
+if [ -n "$DRY_RUN" ]; then
+  printf "\n%b[DRY RUN] No changes will be made%b\n" "$YELLOW" "$RESET"
+  exit 0
+fi
+
+# Create temporary directory
+mkdir -p "$TEMP_DIR"
+trap 'rm -rf "$TEMP_DIR"' EXIT INT TERM
+
+# Backup this script to avoid being overwritten during sync
+SELF_SCRIPT=".github/scripts/sync.sh"
+if [ -f "$SELF_SCRIPT" ]; then
+  cp "$SELF_SCRIPT" "$TEMP_DIR/sync.sh.bak"
+fi
+
+# Clone the template repository
+printf "\n%b[INFO] Cloning template repository...%b\n" "$BLUE" "$RESET"
+REPO_URL="https://github.com/${TEMPLATE_REPO}.git"
+
+if ! git clone --depth 1 --branch "$TEMPLATE_BRANCH" "$REPO_URL" "$TEMP_DIR/template" 2>/dev/null; then
+  printf "%b[ERROR] Failed to clone template repository from %s%b\n" "$RED" "$REPO_URL" "$RESET"
+  exit 1
+fi
+
+# Function to check if a file path should be excluded
+is_file_excluded() {
+  file_path="$1"
+  if [ -z "$EXCLUDE_LIST" ]; then
+    return 1  # Not excluded (false)
+  fi
+
+  while IFS= read -r exclude_item || [ -n "$exclude_item" ]; do
+    [ -z "$exclude_item" ] && continue
+    if [ "$file_path" = "$exclude_item" ]; then
+      return 0  # Is excluded (true)
+    fi
+  done <<EOF_EXCLUDE_CHECK
+$EXCLUDE_LIST
+EOF_EXCLUDE_CHECK
+
+  return 1  # Not excluded (false)
+}
+
+# Copy files from template to current directory
+printf "%b[INFO] Syncing files...%b\n" "$BLUE" "$RESET"
+
+synced_count=0
+skipped_count=0
+# Track whether .github (containing this script) was synced and whether a direct self update was requested
+synced_dotgithub="false"
+deferred_self_update="false"
+
+# Use here-document instead of pipeline to avoid subshell
+while IFS= read -r item || [ -n "$item" ]; do
+  [ -z "$item" ] && continue
+
+  # Check if this item is in the exclude list
+  if is_file_excluded "$item"; then
+    printf "  %b[SKIP]%b %s (excluded)\n" "$YELLOW" "$RESET" "$item"
+    skipped_count=$((skipped_count + 1))
+    continue
+  fi
+
+  # Defer updating this script to the very end to avoid mid-run overwrite
+  if [ "$item" = ".github/scripts/sync.sh" ]; then
+    deferred_self_update="true"
+    printf "  %b[DEFER]%b %s (will update at end)\n" "$YELLOW" "$RESET" "$item"
+    continue
+  fi
+
+  src_path="$TEMP_DIR/template/$item"
+  dest_path="./$item"
+
+  if [ -e "$src_path" ]; then
+    # Create parent directory if needed
+    dest_dir=$(dirname "$dest_path")
+    mkdir -p "$dest_dir"
+
+    # Copy the file or directory
+    if [ -d "$src_path" ]; then
+      # Ensure destination directory exists
+      mkdir -p "$dest_path"
+      # Copy contents of the source directory into the destination directory
+      # to avoid nesting (e.g., .github/.github or tests/tests)
+      cp -R "$src_path"/. "$dest_path"/
+      # Mark if we synced the .github directory so we can safely update sync.sh at the end
+      if [ "$item" = ".github" ]; then
+        synced_dotgithub="true"
+      fi
+
+      # Remove excluded files from the copied directory
+      if [ -n "$EXCLUDE_LIST" ]; then
+        while IFS= read -r exclude_item || [ -n "$exclude_item" ]; do
+          [ -z "$exclude_item" ] && continue
+          # Check if the excluded item is a child of the current item
+          # e.g., if item=".github" and exclude_item=".github/workflows/docker.yml"
+          case "$exclude_item" in
+            "$item"/*)
+              # This is a nested file that should be excluded
+              excluded_file_path="./$exclude_item"
+              if [ -e "$excluded_file_path" ]; then
+                rm -rf "$excluded_file_path"
+                printf "  %b[EXCLUDE]%b %s (removed from synced directory)\n" "$YELLOW" "$RESET" "$exclude_item"
+              fi
+              ;;
+          esac
+        done <<EOF_EXCLUDE_NESTED
+$EXCLUDE_LIST
+EOF_EXCLUDE_NESTED
+      fi
+
+      # If we just synced the .github directory, restore this script immediately to avoid mid-run overwrite issues
+      if [ "$item" = ".github" ] && [ -f "$TEMP_DIR/sync.sh.bak" ]; then
+        cp "$TEMP_DIR/sync.sh.bak" "$SELF_SCRIPT"
+      fi
+      printf "  %b[SYNC]%b %s (directory contents)\n" "$GREEN" "$RESET" "$item"
+    else
+      cp "$src_path" "$dest_path"
+      printf "  %b[SYNC]%b %s\n" "$GREEN" "$RESET" "$item"
+    fi
+    synced_count=$((synced_count + 1))
+  else
+    printf "  %b[WARN]%b %s (not found in template)\n" "$YELLOW" "$RESET" "$item"
+    skipped_count=$((skipped_count + 1))
+  fi
+done <<EOF_INCLUDE
+$INCLUDE_LIST
+EOF_INCLUDE
+
+# Finalize self-update of sync.sh if applicable
+TEMPLATE_SELF_SH="$TEMP_DIR/template/.github/scripts/sync.sh"
+if [ -f "$TEMPLATE_SELF_SH" ] && { [ "$deferred_self_update" = "true" ] || [ "$synced_dotgithub" = "true" ]; }; then
+  if is_file_excluded ".github/scripts/sync.sh"; then
+    printf "  %b[SKIP]%b .github/scripts/sync.sh (excluded from final update)\n" "$YELLOW" "$RESET"
+  else
+    cp "$TEMPLATE_SELF_SH" "$SELF_SCRIPT"
+    chmod +x "$SELF_SCRIPT" 2>/dev/null || true
+    printf "  %b[SYNC]%b .github/scripts/sync.sh (finalized)\n" "$GREEN" "$RESET"
+  fi
+fi
+
+printf "\n%b[INFO] Sync complete!%b\n" "$GREEN" "$RESET"
+printf "  Synced: %d files/directories\n" "$synced_count"
+if [ "$skipped_count" -gt 0 ]; then
+  printf "  Skipped: %d files/directories\n" "$skipped_count"
+fi
+
+printf "\n%b[INFO] Review the changes with: git status%b\n" "$BLUE" "$RESET"
+printf "%b[INFO] Commit the changes with: git add . && git commit -m 'chore: sync template files'%b\n" "$BLUE" "$RESET"