rhiza 0.5.0__tar.gz → 0.5.2__tar.gz

rhiza-0.5.2/.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.2/.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.2/.github/workflows/sync.yml

@@ -0,0 +1,139 @@
+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**.
+

rhiza-0.5.2/.rhiza.history

@@ -0,0 +1,45 @@
+# Rhiza Template History
+# This file lists all files managed by the Rhiza template.
+# Template repository: jebel-quant/rhiza
+# Template branch: main
+#
+# Files under template control:
+.editorconfig
+.github/README.md
+.github/TOKEN_SETUP.md
+.github/actions/setup-project/action.yml
+.github/renovate.json
+.github/scripts/book.sh
+.github/scripts/bump.sh
+.github/scripts/customisations/build-extras.sh
+.github/scripts/customisations/post-release.sh
+.github/scripts/marimushka.sh
+.github/scripts/release.sh
+.github/scripts/update-readme-help.sh
+.github/workflows/book.yml
+.github/workflows/ci.yml
+.github/workflows/deptry.yml
+.github/workflows/marimo.yml
+.github/workflows/pre-commit.yml
+.github/workflows/release.yml
+.github/workflows/scripts/version_matrix.py
+.github/workflows/scripts/version_max.py
+.github/workflows/sync.yml
+.gitignore
+.pre-commit-config.yaml
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+Makefile
+pytest.ini
+ruff.toml
+tests/test_rhiza/README.md
+tests/test_rhiza/conftest.py
+tests/test_rhiza/test_bump_script.py
+tests/test_rhiza/test_docstrings.py
+tests/test_rhiza/test_git_repo_fixture.py
+tests/test_rhiza/test_makefile.py
+tests/test_rhiza/test_marimushka_script.py
+tests/test_rhiza/test_readme.py
+tests/test_rhiza/test_release_script.py
+tests/test_rhiza/test_structure.py
+tests/test_rhiza/test_updatereadme_script.py

{rhiza-0.5.0 → rhiza-0.5.2}/CLI.md

@@ -83,6 +83,7 @@ rhiza materialize -b main -y                # Short form
 - Copies only specified files/directories
 - Respects exclude patterns
 - Skips existing files unless `--force` is used
+- Creates `.rhiza.history` file listing all files under template control
 
 ---
 
@@ -119,6 +120,41 @@ rhiza validate ..                 # Validate parent directory
 
 ---
 
+## Generated Files
+
+### .rhiza.history
+
+After running `rhiza materialize`, a `.rhiza.history` file is created in the project root. This file:
+
+- Lists all files managed by the template
+- Includes metadata about the template repository and branch
+- Is regenerated each time `rhiza materialize` runs
+- Should be committed to version control
+
+**Example:**
+```
+# Rhiza Template History
+# This file lists all files managed by the Rhiza template.
+# Template repository: jebel-quant/rhiza
+# Template branch: main
+#
+# Files under template control:
+.editorconfig
+.gitignore
+Makefile
+```
+
+**Usage:**
+```bash
+# View tracked files
+cat .rhiza.history
+
+# Check if a file is managed by template
+grep "myfile.txt" .rhiza.history
+```
+
+---
+
 ## Configuration File Reference
 
 ### Location

{rhiza-0.5.0 → rhiza-0.5.2}/Makefile

@@ -196,8 +196,8 @@ post-release: install-uv ## perform post-release tasks
 	fi
 
 ##@ Meta
-sync: ## sync with template repository as defined in .github/template.yml
-	@UVX_BIN rhisa inject .
+sync: install-uv ## sync with template repository as defined in .github/template.yml
+	@${UVX_BIN} rhiza materialize .
 
 help: ## Display this help message
 	+@printf "$(BOLD)Usage:$(RESET)\n"

{rhiza-0.5.0 → rhiza-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rhiza
-Version: 0.5.0
+Version: 0.5.2
 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
@@ -25,7 +25,7 @@ Requires-Dist: typer>=0.20.0
 Provides-Extra: dev
 Requires-Dist: marimo==0.18.4; extra == 'dev'
 Requires-Dist: pdoc>=16.0.0; extra == 'dev'
-Requires-Dist: pre-commit==4.5.0; extra == 'dev'
+Requires-Dist: pre-commit==4.5.1; extra == 'dev'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
 Requires-Dist: pytest-html>=4.1.1; extra == 'dev'
 Requires-Dist: pytest==9.0.2; extra == 'dev'
@@ -35,6 +35,9 @@ Description-Content-Type: text/markdown
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/rhiza.svg)](https://pypi.org/project/rhiza/)
+[![Coverage](https://img.shields.io/badge/coverage-report-brightgreen.svg)](https://jebel-quant.github.io/rhiza-cli/tests/html-coverage/index.html)
+[![Downloads](https://static.pepy.tech/personalized-badge/rhiza?period=month&units=international_system&left_color=black&right_color=orange&left_text=PyPI%20downloads%20per%20month)](https://pepy.tech/project/rhiza)
 
 Command-line interface for managing reusable configuration templates for modern Python projects.
 
@@ -675,9 +678,11 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Links
 
+- **PyPI:** https://pypi.org/project/rhiza/
 - **Repository:** https://github.com/jebel-quant/rhiza-cli
 - **Issues:** https://github.com/jebel-quant/rhiza-cli/issues
 - **Documentation:** Generated with `make docs`
+- **Companion Book:** https://jebel-quant.github.io/rhiza-cli/ (includes coverage report, API docs, and notebooks)
 
 ## Architecture
 

{rhiza-0.5.0 → rhiza-0.5.2}/README.md

@@ -2,6 +2,9 @@
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/pypi/v/rhiza.svg)](https://pypi.org/project/rhiza/)
+[![Coverage](https://img.shields.io/badge/coverage-report-brightgreen.svg)](https://jebel-quant.github.io/rhiza-cli/tests/html-coverage/index.html)
+[![Downloads](https://static.pepy.tech/personalized-badge/rhiza?period=month&units=international_system&left_color=black&right_color=orange&left_text=PyPI%20downloads%20per%20month)](https://pepy.tech/project/rhiza)
 
 Command-line interface for managing reusable configuration templates for modern Python projects.
 
@@ -642,9 +645,11 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Links
 
+- **PyPI:** https://pypi.org/project/rhiza/
 - **Repository:** https://github.com/jebel-quant/rhiza-cli
 - **Issues:** https://github.com/jebel-quant/rhiza-cli/issues
 - **Documentation:** Generated with `make docs`
+- **Companion Book:** https://jebel-quant.github.io/rhiza-cli/ (includes coverage report, API docs, and notebooks)
 
 ## Architecture
 

{rhiza-0.5.0 → rhiza-0.5.2}/USAGE.md

@@ -94,6 +94,36 @@ git add .
 git commit -m "chore: initialize project with rhiza templates"
 ```
 
+### Understanding the History File
+
+After materialization, Rhiza creates a `.rhiza.history` file that tracks all files under template control:
+
+```bash
+cat .rhiza.history
+```
+
+You'll see:
+```
+# Rhiza Template History
+# This file lists all files managed by the Rhiza template.
+# Template repository: jebel-quant/rhiza
+# Template branch: main
+#
+# Files under template control:
+.editorconfig
+.gitignore
+Makefile
+.github/workflows/ci.yml
+...
+```
+
+This file helps you:
+- Track which files are managed by the template
+- Understand what will be updated when you re-run `rhiza materialize`
+- Identify which files to be careful with when making local modifications
+
+**Important:** The `.rhiza.history` file is regenerated each time you run `rhiza materialize`, so you should commit it along with your other template files.
+
 ## Basic Workflows
 
 ### Workflow 1: Starting a New Project

{rhiza-0.5.0 → rhiza-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rhiza"
-version = "0.5.0"
+version = "0.5.2"
 description = "Reusable configuration templates for modern Python projects"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -42,7 +42,7 @@ dev = [
     "pytest-cov>=7.0.0",
     "pytest-html>=4.1.1",
     "pytest==9.0.2",
-    "pre-commit==4.5.0",
+    "pre-commit==4.5.1",
     "marimo==0.18.4",
     "pdoc>=16.0.0",
 ]

{rhiza-0.5.0 → rhiza-0.5.2}/src/rhiza/__init__.py

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

{rhiza-0.5.0 → rhiza-0.5.2}/src/rhiza/cli.py

@@ -8,9 +8,9 @@ from pathlib import Path
 
 import typer
 
-from rhiza.commands.init import init as init_cmd
-from rhiza.commands.materialize import materialize as materialize_cmd
-from rhiza.commands.validate import validate as validate_cmd
+from rhiza.commands import init as init_cmd
+from rhiza.commands import materialize as materialize_cmd
+from rhiza.commands import validate as validate_cmd
 
 app = typer.Typer(
     help="Rhiza - Manage reusable configuration templates for Python projects",

{rhiza-0.5.0 → rhiza-0.5.2}/src/rhiza/commands/__init__.py

@@ -3,3 +3,7 @@
 This package contains the functions that back Typer commands exposed by
 `rhiza.cli`, such as `hello` and `inject`.
 """
+
+from .init import init  # noqa: F401
+from .materialize import materialize  # noqa: F401
+from .validate import validate  # noqa: F401

{rhiza-0.5.0 → rhiza-0.5.2}/src/rhiza/commands/init.py

@@ -19,10 +19,8 @@ def init(target: Path):
     Creates a default .github/template.yml file if it doesn't exist,
     or validates an existing one.
 
-    Parameters
-    ----------
-    target:
-        Path to the target directory. Defaults to the current working directory.
+    Args:
+        target: Path to the target directory. Defaults to the current working directory.
     """
     # Convert to absolute path to avoid surprises
     target = target.resolve()