rhiza 0.4.0__tar.gz → 0.5.1__tar.gz

rhiza-0.5.1/.github/README.md

@@ -0,0 +1,33 @@
+# GitHub Configuration
+
+This directory contains the GitHub-specific configuration for the repository.
+
+## Important Documentation
+
+- **[TOKEN_SETUP.md](TOKEN_SETUP.md)** - Instructions for setting up the `PAT_TOKEN` secret required for the SYNC workflow
+
+## Workflows
+
+The repository uses several automated workflows:
+
+- **SYNC** (`workflows/sync.yml`) - Synchronizes with the template repository
+  - **Requires:** `PAT_TOKEN` secret with `workflow` scope when modifying workflow files
+  - See [TOKEN_SETUP.md](TOKEN_SETUP.md) for configuration
+- **CI** (`workflows/ci.yml`) - Continuous integration tests
+- **Pre-commit** (`workflows/pre-commit.yml`) - Code quality checks
+- **Book** (`workflows/book.yml`) - Documentation deployment
+- **Release** (`workflows/release.yml`) - Package publishing
+- **Deptry** (`workflows/deptry.yml`) - Dependency checks
+- **Marimo** (`workflows/marimo.yml`) - Interactive notebooks
+
+## Template Synchronization
+
+This repository is synchronized with the template repository defined in `template.yml`.
+
+The synchronization includes:
+- GitHub workflows and actions
+- Development tools configuration (`.editorconfig`, `ruff.toml`, etc.)
+- Testing infrastructure
+- Documentation templates
+
+See `template.yml` for the complete list of synchronized files and exclusions.

rhiza-0.5.1/.github/TOKEN_SETUP.md

@@ -0,0 +1,102 @@
+# GitHub Personal Access Token (PAT) Setup
+
+This document explains how to set up a Personal Access Token (PAT) for the repository's automated workflows.
+
+## Why is PAT_TOKEN needed?
+
+The repository uses the `SYNC` workflow (`.github/workflows/sync.yml`) to automatically synchronize with a template repository. When this workflow modifies files in `.github/workflows/`, GitHub requires special permissions that the default `GITHUB_TOKEN` doesn't have.
+
+According to GitHub's security policy:
+- The default `GITHUB_TOKEN` **cannot** create or update workflow files (`.github/workflows/*.yml`)
+- A Personal Access Token with the `workflow` scope **is required** to push changes to workflow files
+
+## Creating a PAT with workflow scope
+
+Follow these steps to create a properly scoped Personal Access Token:
+
+### 1. Navigate to GitHub Settings
+
+1. Go to [GitHub.com](https://github.com)
+2. Click your profile picture (top-right corner)
+3. Click **Settings**
+4. Scroll down and click **Developer settings** (bottom of left sidebar)
+5. Click **Personal access tokens** → **Tokens (classic)**
+
+### 2. Generate a new token
+
+1. Click **Generate new token** → **Generate new token (classic)**
+2. Give your token a descriptive name, e.g., `TinyCTA Workflow Sync Token`
+3. Set an expiration date (recommended: 90 days or less for security)
+
+### 3. Select the required scopes
+
+**Required scopes:**
+- ✅ `repo` (Full control of private repositories)
+  - This automatically includes all repo sub-scopes
+- ✅ `workflow` (Update GitHub Action workflows)
+  - **This is critical** - without this scope, pushing workflow changes will fail
+
+**Optional but recommended:**
+- `write:packages` (if the workflow publishes packages)
+
+### 4. Generate and copy the token
+
+1. Click **Generate token** at the bottom
+2. **Important:** Copy the token immediately - you won't be able to see it again!
+3. Store it securely (e.g., in a password manager)
+
+### 5. Add the token to repository secrets
+
+1. Navigate to your repository on GitHub
+2. Click **Settings** tab
+3. Click **Secrets and variables** → **Actions** (left sidebar)
+4. Click **New repository secret**
+5. Name: `PAT_TOKEN`
+6. Value: Paste the token you copied
+7. Click **Add secret**
+
+## Verifying the setup
+
+After adding the `PAT_TOKEN` secret:
+
+1. Navigate to **Actions** tab in your repository
+2. Find the **SYNC** workflow
+3. Click **Run workflow** to manually trigger it
+4. If workflow files are modified, the workflow should successfully push them
+
+## Troubleshooting
+
+### Error: "refusing to allow a GitHub App to create or update workflow"
+
+This error means either:
+- The `PAT_TOKEN` secret is not set
+- The `PAT_TOKEN` exists but lacks the `workflow` scope
+
+**Solution:** Create a new token with the `workflow` scope and update the `PAT_TOKEN` secret.
+
+### Error: "push_succeeded=false"
+
+This usually indicates:
+- The token has expired
+- The token was revoked
+- The token lacks necessary permissions
+
+**Solution:** Generate a new token following the steps above and update the secret.
+
+## Security best practices
+
+1. **Limit scope:** Only grant the minimum required scopes (`repo` and `workflow`)
+2. **Set expiration:** Use short-lived tokens (30-90 days) and rotate them regularly
+3. **Monitor usage:** Regularly review your token usage in GitHub settings
+4. **Revoke unused tokens:** Delete tokens that are no longer needed
+5. **Use separate tokens:** Don't reuse tokens across multiple projects
+
+## Alternative: GitHub App (Advanced)
+
+For organizations, consider using a GitHub App instead of PAT:
+- More secure and granular permissions
+- Better audit logging
+- No expiration issues
+- Requires more setup complexity
+
+Refer to [GitHub's documentation](https://docs.github.com/en/apps) for details on creating GitHub Apps.

rhiza-0.5.1/.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.1/.github/workflows/sync.yml

@@ -0,0 +1,142 @@
+name: SYNC
+# This workflow synchronizes the repository with its template.
+# IMPORTANT: When workflow files (.github/workflows/*.yml) are modified,
+# a Personal Access Token (PAT) with 'workflow' scope is required.
+# The PAT_TOKEN secret must be set in repository secrets.
+# See .github/TOKEN_SETUP.md for setup instructions.
+permissions:
+  contents: write
+  pull-requests: write
+
+
+on:
+  workflow_dispatch:
+    inputs:
+      create-pr:
+        description: "Create a pull request"
+        type: boolean
+        default: true
+  schedule:
+    - cron: '0 0 * * 1'  # Weekly on Monday
+
+jobs:
+  sync:
+    if: ${{ github.repository != 'jebel-quant/rhiza' && github.ref_name != 'rhiza_update' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.PAT_TOKEN }}
+          fetch-depth: 0
+
+      - name: Check PAT_TOKEN configuration
+        shell: bash
+        env:
+          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: |
+          if [ -z "$PAT_TOKEN" ]; then
+            echo "::warning::PAT_TOKEN secret is not configured."
+            echo "::warning::If this sync modifies workflow files, the push will fail."
+            echo "::warning::See .github/TOKEN_SETUP.md for setup instructions."
+          else
+            echo "✓ PAT_TOKEN is configured."
+          fi
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Validate repository
+        shell: bash
+        run: |
+          uvx rhiza validate .
+
+      - name: Sync template
+        id: sync
+        shell: bash
+        env:
+          PAT_TOKEN: ${{ secrets.PAT_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          git checkout -B rhiza_update
+
+          uvx rhiza materialize --force .
+
+          git add -A
+
+          if git diff --cached --quiet; then
+            echo "No changes detected."
+            {
+              echo "changes_detected=false"
+              echo "workflows_changed=false"
+              echo "push_succeeded=false"
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "changes_detected=true" >> "$GITHUB_OUTPUT"
+
+          workflows_changed=false
+          can_push=true
+
+          if git diff --cached --name-only | grep -q '^\.github/workflows/'; then
+            workflows_changed=true
+            echo "workflows_changed=true" >> "$GITHUB_OUTPUT"
+            echo "⚠️ Workflow files modified."
+            echo ""
+            echo "ℹ️  Pushing workflow changes requires a PAT with 'workflow' scope."
+
+            if [ -n "$PAT_TOKEN" ]; then
+              git remote set-url origin \
+                "https://x-access-token:${PAT_TOKEN}@github.com/${{ github.repository }}.git"
+              echo "✓ Using PAT_TOKEN for authentication."
+            else
+              echo "::error::Workflow files changed but PAT_TOKEN secret is not set."
+              echo "::error::GitHub's security policy requires a Personal Access Token with 'workflow' scope to push workflow changes."
+              echo "::error::See .github/TOKEN_SETUP.md for instructions on creating and configuring the PAT_TOKEN secret."
+              can_push=false
+            fi
+          else
+            echo "workflows_changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git commit -m "chore: Update via rhiza"
+
+          if [ "$can_push" = true ]; then
+            if git push origin HEAD:rhiza_update --force-with-lease; then
+              echo "push_succeeded=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "push_succeeded=false" >> "$GITHUB_OUTPUT"
+              echo "::error::Failed to push branch 'rhiza_update'."
+              echo "::error::If workflow files were changed, this is likely because:"
+              echo "::error::  1. PAT_TOKEN secret is not set, OR"
+              echo "::error::  2. PAT_TOKEN lacks the 'workflow' scope"
+              echo "::error::See .github/TOKEN_SETUP.md for setup instructions."
+              exit 1
+            fi
+          else
+            echo "push_succeeded=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create pull request
+        if: ${{ inputs.create-pr && steps.sync.outputs.changes_detected == 'true' && steps.sync.outputs.push_succeeded == 'true' }}
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.PAT_TOKEN || github.token }}
+          base: ${{ github.event.repository.default_branch }}
+          branch: rhiza_update
+          delete-branch: false
+          title: "chore: Update via rhiza"
+          body: |
+            This pull request synchronizes the repository with its template.
+
+            Changes were generated automatically using **rhiza**.
+
+      - name: Delete branch
+        if: ${{ steps.sync.outputs.changes_detected == 'false' }}
+        run: git push origin --delete rhiza_update