feat: add 7zz version locking and PR-only upstream updates (#25)

## Summary
- Lock the bundled 7zz version in `py7zz/7zz_version.txt` and surface it
via `py7zz --version` for reproducible builds.
- Add `scripts/get_7zz.sh` modes (detect/get/update) with download
verification and robust version comparison.
- Use the locked version across CI/release workflows; no dynamic fetch
during builds.
- Add a new check-upstream workflow that monitors upstream 7zz, updates
the lock file on a fixed branch, and opens/refreshes a single PR—no
direct push/tag/release; publishing stays owner-driven.

## Key Changes
- `py7zz/7zz_version.txt`: single source of truth for the bundled 7zz.
- `scripts/get_7zz.sh`: mode-based helper, fixes PATCH parsing for
pre-release suffixes, download verification.
- `py7zz/cli.py`: `--version` now shows both py7zz and bundled 7zz.
- Workflows:
- `.github/workflows/ci.yml`, `.github/workflows/release.yml`: consume
the locked version.
- `.github/workflows/check-upstream.yml`: new PR-only auto-update
(peter-evans/create-pull-request), fixed branch `chore/update-7zz`,
`dpkg --compare-versions`, deduped PRs, labels `dependencies`,
`automated`, `chore`, no auto tag/release.
- `REUSE.toml`: licensing metadata for the version file.
- Formatting cleanups (trailing whitespace/newlines).

## Behavior
- Daily (00:30 UTC) or manual check; when a newer 7zz is found, update
the lock file, verify download (artifacts gitignored), push to
`chore/update-7zz`, and create/update one PR.
- No automatic tag or release; the owner merges and triggers release
when ready.
- Changelog category: `chore` (dependency maintenance); includes CI
workflow addition for PR-only updates.

## Testing
- pre-commit hook: `ruff format` (check) + `ruff check` passed during
commit.
- No additional tests were run in this branch (existing suite remains
applicable).

Author: RxChi1d

.github/workflows/check-upstream.yml

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025 py7zz contributors
+
+name: Check Upstream 7zz
+
+on:
+  schedule:
+    - cron: '30 0 * * *'  # Run daily at 00:30 UTC (avoiding midnight congestion)
+  workflow_dispatch:      # Allow manual trigger
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  check-and-update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for git describe
+
+      - name: Check for updates
+        id: check
+        run: |
+          chmod +x scripts/get_7zz.sh
+
+          # Get latest version from online (with error handling)
+          echo "Detecting latest 7zz version from upstream..."
+          if ! LATEST_ONLINE=$(./scripts/get_7zz.sh --detect-latest 2>&1); then
+            echo "::error::Failed to detect latest 7zz version from upstream"
+            echo "Output: $LATEST_ONLINE"
+            exit 1
+          fi
+
+          # Validate version format (should be like "25.01")
+          if ! [[ "$LATEST_ONLINE" =~ ^[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Invalid version format detected: '$LATEST_ONLINE'"
+            exit 1
+          fi
+
+          # Get current bundled version (with error handling)
+          echo "Reading current bundled version..."
+          if ! CURRENT_BUNDLED=$(./scripts/get_7zz.sh --get-current 2>&1); then
+            echo "::error::Failed to read current bundled version"
+            echo "Output: $CURRENT_BUNDLED"
+            exit 1
+          fi
+
+          echo "Latest online 7zz: $LATEST_ONLINE"
+          echo "Current bundled 7zz: $CURRENT_BUNDLED"
+
+          # Compare versions
+          if dpkg --compare-versions "$LATEST_ONLINE" gt "$CURRENT_BUNDLED"; then
+            echo "✨ Update found: $CURRENT_BUNDLED -> $LATEST_ONLINE"
+            echo "update_needed=true" >> $GITHUB_OUTPUT
+            echo "new_version=$LATEST_ONLINE" >> $GITHUB_OUTPUT
+          else
+            echo "✅ Up to date"
+            echo "update_needed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Prepare 7zz version bump
+        if: steps.check.outputs.update_needed == 'true'
+        run: |
+          set -euo pipefail
+
+          NEW_VERSION="${{ steps.check.outputs.new_version }}"
+          CURRENT_VERSION=$(cat py7zz/7zz_version.txt | tr -d '[:space:]')
+
+          echo "$NEW_VERSION" > py7zz/7zz_version.txt
+
+          # Verify the new version can be downloaded (no artifacts committed; bin is gitignored)
+          if ! ./scripts/get_7zz.sh --version "$NEW_VERSION"; then
+            echo "::error::Failed to verify 7zz $NEW_VERSION download"
+            exit 1
+          fi
+
+          echo "CURRENT_VERSION=$CURRENT_VERSION" >> $GITHUB_ENV
+
+      - name: Create PR for 7zz Update
+        if: steps.check.outputs.update_needed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: chore/update-7zz
+          delete-branch: true
+          base: main
+          title: "chore: bump bundled 7zz to ${{ steps.check.outputs.new_version }}"
+          commit-message: "chore: bump bundled 7zz to ${{ steps.check.outputs.new_version }}"
+          labels: dependencies, automated, chore
+          add-paths: py7zz/7zz_version.txt
+          body: |
+            ## Summary
+            Detected a new 7-Zip release: **${{ steps.check.outputs.new_version }}**.
+
+            This PR updates the bundled 7zz version. Release and tagging remain manual so branch protection stays intact.
+
+            ## Changes
+            - Update `py7zz/7zz_version.txt`: ${{ env.CURRENT_VERSION }} → ${{ steps.check.outputs.new_version }}
+
+            ## Changelog Category
+            - chore (dependency maintenance)
+
+            ## Next Steps
+            - Review and merge this PR when ready
+            - Owner can run release workflow after merging to publish a new py7zz version
+
+            Generated by [Check Upstream 7zz workflow](https://github.com/${{ github.repository }}/actions/workflows/check-upstream.yml)

.github/workflows/ci.yml

@@ -91,11 +91,11 @@ jobs:
     - name: Download 7zz binary for testing
       shell: bash
       run: |
-        # Auto-detect latest 7-Zip version
-        echo "Detecting latest 7-Zip version..."
+        # Use locked version from file
+        echo "Reading configured 7-Zip version..."
         chmod +x scripts/get_7zz.sh
-        VERSION=$(./scripts/get_7zz.sh --detect-version)
-        echo "Detected version: $VERSION"
+        VERSION=$(./scripts/get_7zz.sh --get-current)
+        echo "Configured version: $VERSION"
         VERSION_FOR_ASSET=$(echo "$VERSION" | sed 's/\.//g')  # e.g., 25.01 -> 2501
 
         # Map platform to 7zz release naming (same logic as release.yml)

.github/workflows/release.yml

@@ -114,11 +114,11 @@ jobs:
           echo "Release type: Pre-release"
         fi
 
-        # Auto-detect latest 7zz version
-        echo "Detecting latest 7-Zip version..."
+        # Get 7zz version from locked file
+        echo "Reading configured 7-Zip version..."
         chmod +x scripts/get_7zz.sh
-        SEVEN_ZZ_VERSION=$(./scripts/get_7zz.sh --detect-version)
-        echo "Detected 7zz version: $SEVEN_ZZ_VERSION"
+        SEVEN_ZZ_VERSION=$(./scripts/get_7zz.sh --get-current)
+        echo "Configured 7zz version: $SEVEN_ZZ_VERSION"
 
         # Set outputs
         echo "git_tag=$TAG" >> $GITHUB_OUTPUT

.roo/rules/rules.md

@@ -0,0 +1 @@
+../../CLAUDE.md

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

REUSE.toml

@@ -6,3 +6,9 @@ path = "uv.lock"
 SPDX-FileCopyrightText = "NONE"
 SPDX-FileComment = "Autogenerated by uv; do not edit."
 SPDX-License-Identifier = "CC0-1.0"
+
+# Version lock file for bundled 7zz binary
+[[annotations]]
+path = "py7zz/7zz_version.txt"
+SPDX-FileCopyrightText = "2025 py7zz contributors"
+SPDX-License-Identifier = "MIT"

py7zz/7zz_version.txt

@@ -0,0 +1 @@
+25.01

py7zz/cli.py

@@ -7,7 +7,6 @@
 py7zz's value is in automatic binary management and providing Python API.
 """
 
-import os
 import subprocess
 import sys
 
@@ -32,11 +31,28 @@ def main() -> None:
             command = sys.argv[1]
 
             if command in ["--version", "-V"]:
-                # Handle quick version command: print only version string
+                # Handle quick version command: print version strings
                 try:
                     from .version import get_version as _get_version
 
-                    print(_get_version())
+                    # Get package version
+                    pkg_ver = _get_version()
+
+                    # Get bundled 7zz version from file
+                    bundled_ver = "unknown"
+                    try:
+                        import os
+
+                        current_dir = os.path.dirname(os.path.abspath(__file__))
+                        ver_file = os.path.join(current_dir, "7zz_version.txt")
+                        if os.path.exists(ver_file):
+                            with open(ver_file) as f:
+                                bundled_ver = f.read().strip()
+                    except Exception:
+                        pass
+
+                    print(f"py7zz {pkg_ver}")
+                    print(f"7zz   {bundled_ver} (bundled)")
                 except Exception as _e:
                     print(f"py7zz error: {_e}", file=sys.stderr)
                     sys.exit(1)

pyproject.toml

@@ -14,7 +14,8 @@ packages = ["py7zz"]
 # However, since they're in .gitignore, we use artifacts to include them when they exist
 # Note: Each platform wheel will only contain the relevant binary files for that platform
 artifacts = [
-    "py7zz/bin/*"
+    "py7zz/bin/*",
+    "py7zz/7zz_version.txt",
 ]
 
 # Include license and legal files