repomatic 7.8.0__tar.gz → 7.9.0__tar.gz

{repomatic-7.8.0 → repomatic-7.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repomatic
-Version: 7.8.0
+Version: 7.9.0
 Summary: 🏭 Automate repository maintenance, releases, and CI/CD workflows
 Keywords: changelog-formatter,dependabot-alternative,github-actions,github-labels,github-workflow,gitignore,mailmap,mypy,nuitka,python-automation,release-automation,repository-automation,repository-management,reusable-workflows,software-factory,sphinx-doc,typo,uv,workflow-reusable
 Author: Kevin Deldycke
@@ -59,7 +59,7 @@ Requires-Dist: wcmatch>=10
 Requires-Python: >=3.10
 Project-URL: Changelog, https://github.com/kdeldycke/repomatic/blob/main/changelog.md
 Project-URL: Documentation, https://kdeldycke.github.io/repomatic
-Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.8.0
+Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.9.0
 Project-URL: Funding, https://github.com/sponsors/kdeldycke
 Project-URL: Homepage, https://github.com/kdeldycke/repomatic
 Project-URL: Issues, https://github.com/kdeldycke/repomatic/issues

{repomatic-7.8.0 → repomatic-7.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = ["uv-build>=0.8"]
 
 [project]
 name = "repomatic"
-version = "7.8.0"
+version = "7.9.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -92,7 +92,7 @@ email = "kevin@deldycke.com"
 [project.urls]
 Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 Documentation = "https://kdeldycke.github.io/repomatic"
-Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.8.0"
+Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.9.0"
 Funding = "https://github.com/sponsors/kdeldycke"
 Homepage = "https://github.com/kdeldycke/repomatic"
 Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -146,7 +146,7 @@ module-root = ""
 [tool.nuitka]
 copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed under GPL-2.0-or-later license."
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
-file-version = "7.8.0"
+file-version = "7.9.0"
 include-data-dir = [
     "repomatic/data/awesome_template=repomatic/data/awesome_template",
     "repomatic/data/skills=repomatic/data/skills",
@@ -156,7 +156,7 @@ include-package-data = ["click_extra"]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.8.0"
+product-version = "7.9.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -250,7 +250,7 @@ fail_under = 80
 precision = 2
 
 [tool.bumpversion]
-current_version = "7.8.0"
+current_version = "7.9.0"
 parse = '(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.dev(?P<dev>\d+))?'
 serialize = [
     "{major}.{minor}.{patch}.dev{dev}",

{repomatic-7.8.0 → repomatic-7.9.0}/pyproject.toml.orig

@@ -12,7 +12,7 @@ requires = [ "uv-build>=0.8" ]
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "repomatic"
-version = "7.8.0"
+version = "7.9.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -145,7 +145,7 @@ dependencies = [
 ]
 urls.Changelog = "https://github.com/kdeldycke/repomatic/blob/main/changelog.md"
 urls.Documentation = "https://kdeldycke.github.io/repomatic"
-urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.8.0"
+urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.9.0"
 urls.Funding = "https://github.com/sponsors/kdeldycke"
 urls.Homepage = "https://github.com/kdeldycke/repomatic"
 urls.Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -250,7 +250,7 @@ copyright = "Kevin Deldycke <kevin@deldycke.com> and contributors. Distributed u
 file-description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 # Numeric only: Nuitka rejects PEP 440 .devN suffixes. Kept in sync with the
 # package version by the dedicated [tool.bumpversion] rule that strips the suffix.
-file-version = "7.8.0"
+file-version = "7.9.0"
 include-data-dir = [
   "repomatic/data/awesome_template=repomatic/data/awesome_template",
   "repomatic/data/skills=repomatic/data/skills",
@@ -269,7 +269,7 @@ include-package-data = [ "click_extra" ]
 linux-icon = "docs/assets/icon.png"
 macos-app-icon = "docs/assets/icon.icns"
 product-name = "Repomatic"
-product-version = "7.8.0"
+product-version = "7.9.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -407,7 +407,7 @@ report.fail_under = 80
 report.precision = 2
 
 [tool.bumpversion]
-current_version = "7.8.0"
+current_version = "7.9.0"
 # Parse versions with an optional .devN suffix (PEP 440).
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(\\.dev(?P<dev>\\d+))?"
 serialize = [

{repomatic-7.8.0 → repomatic-7.9.0}/repomatic/__init__.py

@@ -17,5 +17,5 @@
 
 from __future__ import annotations
 
-__version__ = "7.8.0"
-__git_tag_sha__ = "ab43527b67361553b1c8539e8f3d9e6e2013b98c"
+__version__ = "7.9.0"
+__git_tag_sha__ = "292c4e8438249adeb269808d485409c9b56b49bd"

{repomatic-7.8.0 → repomatic-7.9.0}/repomatic/cli.py

@@ -104,7 +104,12 @@ from .docs import update_docs as _update_docs
 from .frontmatter import split_frontmatter
 from .git_ops import commit_and_push_files, create_and_push_tag
 from .github import token as _token_mod, unsubscribe as _unsub_mod
-from .github.actions import cancel_superseded_runs, format_multiline_output
+from .github.actions import (
+    AnnotationLevel,
+    cancel_superseded_runs,
+    emit_annotation,
+    format_multiline_output,
+)
 from .github.dev_release import (
     cleanup_dev_releases as _cleanup_dev_releases,
     sync_dev_release as _sync_dev_release,
@@ -144,7 +149,7 @@ from .github.unsubscribe import (
     unsubscribe_threads as _unsubscribe_threads,
 )
 from .github.workflow_sync import run_workflow_lint
-from .gitignore import build_gitignore
+from .gitignore import build_gitignore, orphaned_rules
 from .humanize import format_age, format_file_size
 from .images import (
     DEFAULT_MIN_SAVINGS_BYTES,
@@ -1244,8 +1249,16 @@ def close_stale_bump_pr(part: str) -> None:
     default=None,
     help=("Output path. Defaults to gitignore-location from [tool.repomatic] config."),
 )
+@option(
+    "--drop-orphans/--no-drop-orphans",
+    default=False,
+    help=(
+        "Overwrite rules found on disk but absent from the generated file, "
+        "instead of refusing to drop them."
+    ),
+)
 @pass_context
-def sync_gitignore(ctx: Context, output_path: Path | None) -> None:
+def sync_gitignore(ctx: Context, output_path: Path | None, drop_orphans: bool) -> None:
     """Sync a .gitignore file from gitignore.io templates.
 
     Fetches templates for a base set of categories plus any extras from
@@ -1253,6 +1266,11 @@ def sync_gitignore(ctx: Context, output_path: Path | None) -> None:
     Writes to the path specified by gitignore-location (default
     ./.gitignore).
 
+    The generated file is the whole file: nothing is read back from the copy on
+    disk. A rule added there by hand is therefore dropped on the next sync, so
+    the write aborts when it would lose one. Move the rule into
+    gitignore-extra-content to keep it, or pass --drop-orphans to let it go.
+
     \b
     Examples:
         # Generate .gitignore using config from pyproject.toml
@@ -1275,6 +1293,32 @@ def sync_gitignore(ctx: Context, output_path: Path | None) -> None:
     if output_path is None:
         output_path = Path(config.gitignore.location)
 
+    # Compare against what is already there before overwriting it. Skipped for
+    # stdout, which destroys nothing, and for a first run, which has nothing to
+    # destroy.
+    if not drop_orphans and str(output_path) != "-" and output_path.is_file():
+        orphans = orphaned_rules(output_path.read_text(encoding="UTF-8"), content)
+        if orphans:
+            emit_annotation(
+                AnnotationLevel.ERROR,
+                f"{output_path}: sync would drop {len(orphans)} hand-added "
+                f"rule(s): {', '.join(orphans)}",
+            )
+            echo(
+                f"Refusing to overwrite {output_path}: "
+                f"{len(orphans)} rule(s) on disk are absent from the generated "
+                "file and would be lost.",
+                err=True,
+            )
+            for rule in orphans:
+                echo(f"  {rule}", err=True)
+            echo(
+                "\nMove them into [tool.repomatic.gitignore] extra-content to "
+                "keep them, or re-run with --drop-orphans to discard them.",
+                err=True,
+            )
+            ctx.exit(1)
+
     log_output_target(".gitignore", output_path)
 
     echo(content.rstrip(), file=prep_path(output_path))
@@ -3166,6 +3210,7 @@ def lint_repo(
     exit_code = run_repo_lint(
         package_name=package_name,
         repo_name=repo_name,
+        is_package=metadata.is_python_package,
         is_sphinx=is_sphinx,
         project_description=project_description,
         keywords=keywords,

{repomatic-7.8.0 → repomatic-7.9.0}/repomatic/config.py

@@ -869,6 +869,21 @@ class Config:
     PAT with `notifications` scope stored as `REPOMATIC_NOTIFICATIONS_PAT`.
     """
 
+    nuitka_dev_targets: list[str] = field(
+        default_factory=lambda: ["linux-arm64"],
+        metadata={CONFIG_PATH_METADATA_KEY: "nuitka.dev-targets"},
+    )
+    """Nuitka build targets compiled on ordinary pushes, as a canary.
+
+    An ordinary push to the default branch rebuilds binaries only for these
+    targets: enough to catch a compilation break early, while freeing runner
+    slots the full fleet would occupy on every code push just to refresh the
+    rolling dev pre-release (a draft). The full target roster still builds on
+    release commits, on the weekly `schedule` trigger, and on
+    `workflow_dispatch`. Defaults to `["linux-arm64"]`, the fastest and
+    cheapest builder. Set to `[]` to skip dev builds entirely.
+    """
+
     nuitka_enabled: bool = field(
         default=True,
         metadata={CONFIG_PATH_METADATA_KEY: "nuitka.enabled"},

{repomatic-7.8.0 → repomatic-7.9.0}/repomatic/data/_release-engine.yaml

@@ -30,9 +30,10 @@ permissions: {}
 # Supply-chain cooldown: no package published within the window can be resolved by
 # any command in this workflow. Set here, not per command, so it also covers the
 # `metadata` bootstrap and any step added later; a workflow-level `env:` cannot
-# reference `needs`, so the window is a literal that tests/test_workflows.py holds
-# equal to `[tool.repomatic] minimum-release-age`. Deliberate bypasses are
-# per-package CLI flags (`--exclude-newer-package`, `--min-release-age-exclude`).
+# reference `needs`, so the window is a literal kept equal to `[tool.repomatic]
+# minimum-release-age`. repomatic's own test suite enforces that upstream; a
+# synced copy is kept in step by hand. Deliberate bypasses are per-package CLI
+# flags (`--exclude-newer-package`, `--min-release-age-exclude`).
 # See claude.md for the rationale.
 env:
   NPM_CONFIG_MIN_RELEASE_AGE: 7
@@ -64,7 +65,7 @@ jobs:
       - name: Run repomatic metadata
         id: metadata
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' metadata
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' metadata
           --format github-json --output "$GITHUB_OUTPUT"
           new_commits_matrix release_commits_matrix build_targets nuitka_matrix
           nuitka_extras is_python_project package_name current_version
@@ -102,10 +103,28 @@ jobs:
     container: ${{ matrix.container }}
     # We keep going when a job flagged as not stable fails.
     continue-on-error: ${{ matrix.state == 'unstable' }}
+    # Headroom over the slowest measured cold-cache compile job (17.4 min on
+    # windows-x64); see docs/nuitka.md § Compile caching for the full table.
+    # Without it a hung compile squats a runner-cap slot for the 360-min default.
+    timeout-minutes: 45
     permissions:
       id-token: write
       attestations: write
       contents: read
+    env:
+      # Relocate every Nuitka cache (ccache/clcache objects, downloads,
+      # bytecode) under the workspace, so the cache step below and Nuitka
+      # agree on one path both on VM jobs and inside the manylinux containers.
+      NUITKA_CACHE_DIR: ${{ github.workspace }}/.nuitka-cache
+      # Two ccache settings cross-VM hits depend on: hash the compiler
+      # binary's content (the default mtime+size check trips on runner VMs,
+      # which do not keep stable file timestamps) and tolerate
+      # __DATE__/__TIME__ macros. The cache-prep step below also writes both
+      # into $CCACHE_DIR/ccache.conf, so whichever channel reaches the
+      # wrapper carries the same values. Nuitka's internal clcache on MSVC
+      # ignores both settings.
+      CCACHE_COMPILERCHECK: content
+      CCACHE_SLOPPINESS: time_macros
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -113,6 +132,70 @@ jobs:
       - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           version: "0.12.1"
+      # Persist the Nuitka compile caches across runs: ccache objects on gcc
+      # targets, Nuitka's internal clcache objects on MSVC, plus downloads
+      # and demoted-module bytecode. The per-commit key never hits exactly,
+      # so every run saves a fresh snapshot and restores the latest previous
+      # one via the prefix; ccache/clcache hash compiler, flags and sources
+      # themselves, so a stale snapshot degrades to cache misses, never to
+      # wrong objects. Two exclusions:
+      # - Release commits build cold, on purpose: a cache entry is writable
+      #   by any code running in any main-ref workflow (the cache API is not
+      #   gated by `permissions:`), and its restore is a tar extraction into
+      #   the workspace, so a poisoned entry could reach a signed, published,
+      #   immutable binary. Skipping restore AND save on release commits
+      #   keeps every published artifact compiled from source on a fresh VM;
+      #   canary and weekly runs keep the warm-cache speed.
+      # - macOS is excluded entirely: its ccache scored 0/470 cross-VM hits
+      #   through every configuration channel tried (CCACHE_* env vars, then
+      #   ccache.conf inside this very cache dir), so persisting it only paid
+      #   restore/save overhead for entries that never hit. Capture Nuitka's
+      #   CCACHE_LOGFILE from a scheduled run to diagnose before re-enabling.
+      - name: Restore Nuitka compile cache
+        if: >-
+          matrix.platform_id != 'macos'
+          && !fromJSON(needs.metadata.outputs.metadata).release_commits_matrix
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .nuitka-cache
+          key: nuitka-${{ matrix.target }}-${{ matrix.commit }}
+          restore-keys: nuitka-${{ matrix.target }}-
+      # Two duties. Trim: Nuitka's clcache has no size cap or pruning (ccache
+      # self-prunes at 5 GiB), so left alone a restore-then-save cycle grows
+      # the cache without bound; reset past 2 GiB and let the next save start
+      # a fresh lineage. Configure: write ccache's settings inside the cache
+      # dir itself, the one channel that reliably reaches the wrapper (ccache
+      # always reads $CCACHE_DIR/ccache.conf, while the job-level CCACHE_*
+      # env vars above die with scons's scrubbed compiler environment).
+      - name: Prepare Nuitka cache
+        if: >-
+          matrix.platform_id != 'macos'
+          && !fromJSON(needs.metadata.outputs.metadata).release_commits_matrix
+        shell: bash
+        run: |
+          if [[ -d .nuitka-cache ]]; then
+            size_mb=$(du -sm .nuitka-cache | cut -f1)
+            echo "Nuitka cache restored at ${size_mb} MiB."
+            if (( size_mb > 2048 )); then
+              echo "Cache exceeds 2 GiB, resetting."
+              rm -rf .nuitka-cache
+            fi
+          fi
+          mkdir -p .nuitka-cache/ccache
+          printf 'compiler_check = content\nsloppiness = time_macros\n' \
+            > .nuitka-cache/ccache/ccache.conf
+      # The manylinux containers ship no ccache (Nuitka warns and compiles
+      # cold), so the canary target pays full C compilation on every push.
+      # EPEL is a distro archive, exempt from the install cooldown (see
+      # claude.md § Distro archives are out of scope). Non-fatal on mirror
+      # hiccups: a release build must not die for a missing cache helper.
+      - name: Install ccache in container
+        if: matrix.container
+        shell: bash
+        run: >
+          (dnf install --assumeyes --quiet epel-release
+          && dnf install --assumeyes --quiet ccache)
+          || echo "ccache unavailable, building uncached."
       - name: Setup venv
         # --managed-python forces uv's own python-build-standalone interpreter,
         # whose deployment floors are the ones we declare and verify (macOS
@@ -150,7 +233,7 @@ jobs:
           uv --no-progress sync --frozen ${flags}
       - name: Pre-bake build metadata
         if: contains(matrix.current_version, '.dev')
-        run: uvx --no-progress 'click-extra==8.8.0' prebake all
+        run: uvx --no-progress 'click-extra==8.8.1' prebake all
       - name: Build binary
         id: build-binary
         continue-on-error: true
@@ -162,6 +245,15 @@ jobs:
         # passes as a proper argv, so a plain word-split is enough here.
         env:
           NUITKA_PYTHON_FLAGS: ${{ matrix.nuitka_python_flags }}
+          # On macOS Nuitka auto-downloads a ccache binary from nuitka.net,
+          # with no checksum at the call site (SconsCaching.py's
+          # getCachedDownload passes none). Since the macOS cache is not
+          # persisted (0/470 cross-VM hits, see the cache step above), ccache
+          # brings zero benefit there and the unchecksummed download is pure
+          # supply-chain surface: disable it. Empty (and inert) elsewhere;
+          # Linux ccache and MSVC clcache are unaffected.
+          NUITKA_CCACHE_FLAG: >-
+            ${{ matrix.platform_id == 'macos' && '--disable-ccache' || '' }}
           BIN_NAME: ${{ matrix.bin_name }}
           MODULE_PATH: ${{ matrix.module_path }}
           # Pin the macOS floor: without it, compiled objects and processed
@@ -171,11 +263,11 @@ jobs:
             ${{ matrix.platform_id == 'macos' && matrix.min_os || '' }}
         shell: bash
         run: |
-          # NUITKA_PYTHON_FLAGS holds the entry point's --python-flag (if any),
+          # NUITKA_PYTHON_FLAGS and NUITKA_CCACHE_FLAG hold optional flags,
           # meant to word-split.
           # shellcheck disable=SC2086
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' run nuitka -- \
-            ${NUITKA_PYTHON_FLAGS} \
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' run nuitka -- \
+            ${NUITKA_PYTHON_FLAGS} ${NUITKA_CCACHE_FLAG} \
             --output-filename="${BIN_NAME}" "${MODULE_PATH}"
       - name: Upload Nuitka crash report
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -183,6 +275,11 @@ jobs:
           name: nuitka-crash-report-${{ matrix.os }}-${{ matrix.short_sha }}.xml
           if-no-files-found: ignore
           path: nuitka-crash-report.xml
+      # Sizing signal for the cache strategy: hit/miss counts are in Nuitka's
+      # own "Cached C files" log lines above, this step adds what they omit.
+      - name: Nuitka cache stats
+        shell: bash
+        run: du -sm .nuitka-cache/* 2>/dev/null || echo "No Nuitka cache dir."
       - if: steps.build-binary.outcome == 'failure'
         run: |
           echo "Nuitka build failed, skipping the rest of the steps."
@@ -199,8 +296,27 @@ jobs:
           BIN_NAME: ${{ matrix.bin_name }}
         shell: bash
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0'
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0'
           verify-binary --target "${TARGET}" --binary "${BIN_NAME}"
+      # On a non-release run, exercise the freshly-built binary in place: the
+      # standalone test-binaries job only runs for release commits, so canary
+      # and weekly-schedule builds still prove the binary works without paying
+      # a second runner-queue slot. Env mirrors the test-binaries job; see its
+      # comments for the UTF-8 and safe.directory rationale.
+      - name: Self-test binary
+        if: ${{ !fromJSON(needs.metadata.outputs.metadata).release_commits_matrix }}
+        env:
+          BIN_NAME: ${{ matrix.bin_name }}
+          PYTHONIOENCODING: utf8
+          GIT_CONFIG_COUNT: "1"
+          GIT_CONFIG_KEY_0: safe.directory
+          GIT_CONFIG_VALUE_0: "*"
+        shell: bash
+        run: >
+          uv --no-progress run --frozen --
+          click-extra test-suite
+          --binary "./${BIN_NAME}"
+          --jobs max
       - name: Upload binaries
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -232,7 +348,7 @@ jobs:
           BIN_NAME: ${{ matrix.bin_name }}
         shell: bash
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' run gh --
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' run gh --
           attestation verify "${BIN_NAME}"
           --repo "${{ github.repository }}"
           --signer-repo kdeldycke/repomatic
@@ -248,7 +364,7 @@ jobs:
           BUNDLE_PATH: ${{ steps.attest-binary.outputs.bundle-path }}
         shell: bash
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0'
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0'
           pack-attestation --bundle "${BUNDLE_PATH}"
       - name: Upload attestation bundle
         # Globbed rather than named, so the filename stays the CLI's to decide.
@@ -266,10 +382,15 @@ jobs:
     needs:
       - metadata
       - compile-binaries
-    # Skip binary tests for branches that don't affect code (e.g., update-mailmap, format-markdown).
+    # Release commits only: non-release builds self-test inside compile-binaries
+    # instead of paying a second runner-queue slot per target. This standalone
+    # job re-validates the artifact on a pristine VM, through the same
+    # upload/download round-trip a user's binary takes. Also skipped for
+    # branches that don't affect code (e.g., update-mailmap, format-markdown).
     if: >
       fromJSON(needs.metadata.outputs.metadata).nuitka_matrix
       && !(fromJSON(needs.metadata.outputs.metadata).skip_binary_build || false)
+      && fromJSON(needs.metadata.outputs.metadata).release_commits_matrix
     strategy:
       # Advisory matrix (default fail-fast): see docs/workflows.md "Matrix fail-fast strategy".
       # Fall back to an empty `{"include":[]}` matrix when nuitka_matrix is null
@@ -285,6 +406,8 @@ jobs:
     container: ${{ matrix.container }}
     # We keep going when a job flagged as not stable fails.
     continue-on-error: ${{ matrix.state == 'unstable' }}
+    # The suite runs in ~1-2 min; a hung run must not squat a runner-cap slot.
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -356,7 +479,7 @@ jobs:
           CURRENT_VERSION: ${{ matrix.current_version }}
           COMMIT: ${{ matrix.commit }}
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' git-tag
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' git-tag
           --tag "v${CURRENT_VERSION}"
           --commit "${COMMIT}"
           --skip-existing
@@ -398,7 +521,7 @@ jobs:
         continue-on-error: true
         env:
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
-        run: uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' sync-dev-release --live --delete
+        run: uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' sync-dev-release --live --delete
       - name: Create GitHub release draft
         # Idempotent: skips if release already exists (e.g. workflow re-run).
         # Notes carry the PyPI availability admonition from the start: baking it
@@ -510,7 +633,7 @@ jobs:
           BUNDLE_PATH: ${{ steps.attest-manpages.outputs.bundle-path }}
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
         run: |
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' \
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' \
             pack-attestation --bundle "${BUNDLE_PATH}" > upload-list.txt
           xargs gh release upload "v${CURRENT_VERSION}" \
             --repo "${{ github.repository }}" \
@@ -595,7 +718,7 @@ jobs:
           PACKAGE_NAME: ${{ fromJSON(needs.metadata.outputs.metadata).package_name }}
         shell: bash
         run: |
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' pack-attestation \
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' pack-attestation \
             --bundle "${BUNDLE_PATH}" \
             --dir release-assets \
             --name "${PACKAGE_NAME}-extra-assets" > upload-list.txt
@@ -673,7 +796,7 @@ jobs:
         # Python distributions live in the CLI; the shell only feeds the
         # printed list to `gh release upload`.
         run: |
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' pack-binaries \
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' pack-binaries \
             --version "${CURRENT_VERSION}" --dir ./compile-assets > upload-list.txt
           if [[ -s upload-list.txt ]]; then
             xargs gh release upload "v${CURRENT_VERSION}" \
@@ -706,6 +829,9 @@ jobs:
       # (rare) multi-release runs keeps them from racing on the same files.
       max-parallel: 1
     runs-on: ubuntu-slim
+    # Upload plus the 600 s --poll-timeout, with margin; a stuck poll must not
+    # squat a runner-cap slot for the 360-min default.
+    timeout-minutes: 15
     permissions:
       contents: write
     steps:
@@ -738,7 +864,7 @@ jobs:
           VIRUSTOTAL_API_KEY: ${{ secrets.VIRUSTOTAL_API_KEY }}
           CURRENT_VERSION: ${{ matrix.current_version }}
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' scan-virustotal
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' scan-virustotal
           --tag "v${CURRENT_VERSION}"
           --binaries-dir ./binaries
           --poll
@@ -751,7 +877,7 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' sync-binaries
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' sync-binaries
           --repo "${{ github.repository }}"
           --page docs/binaries.md
           --records docs/assets/virustotal-scans.json
@@ -766,7 +892,7 @@ jobs:
           CURRENT_VERSION: ${{ matrix.current_version }}
           DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' git-commit-push
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' git-commit-push
           --message "Record v${CURRENT_VERSION} binaries"
           --branch "${DEFAULT_BRANCH}"
           docs/binaries.md
@@ -814,5 +940,5 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: >
-          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.8.0' sync-dev-release --live
+          uvx --no-progress --exclude-newer-package repomatic=P0D 'repomatic==7.9.0' sync-dev-release --live
           --upload-assets release_assets

{repomatic-7.8.0 → repomatic-7.9.0}/repomatic/data/agent-sphinx-docs.md

@@ -541,7 +541,7 @@ Hand-written, but with a strict structure that downstream projects should mirror
 
 5. **Python compatibility matrix** — a `<!-- matrix python -->` / `<!-- matrix-end -->` comment-marker region whose embedded table is regenerated by `click-extra refresh-directives` (the fourth `repomatic update-docs` phase runs it automatically), so it refreshes on every release without manual intervention. click-extra's matrix machinery owns the generation logic: per-tag Python support from classifiers with `requires-python`/Poetry/`setup.py` fallbacks, release-date capping, and range grouping. Keep the marker form (not the live `{matrix}` fence) so the table also renders when browsing the file on GitHub. Rendering conventions the reader relies on: `✅` / `❌` glyph cells, consecutive same-support tags grouped into one row labelled `` `4.25.x` → `6.15.x` ``, newest ranges on top. Tags with no Python declaration at all are out of scope; note the cutoff in a sentence beneath the table rather than padding with blank rows.
 
-6. **Executables** table linking to GitHub Release binaries for each platform/architecture. Always points at `releases/latest/download/...` — never bake in version numbers that need bumping every release. The release pipeline uploads unversioned alias assets (`<package>-linux-arm64.bin`) alongside the version-stamped ones precisely so these evergreen URLs resolve.
+6. **Executables** table linking to GitHub Release binaries for each platform/architecture. Its URLs belong to the release freeze (`PrepareRelease.freeze_install_download_urls`), which ratchets them forward to `/releases/download/vX.Y.Z/<package>-X.Y.Z-linux-arm64.bin` on every release: a repo that has shipped once carries versioned URLs permanently, and there is no unfreeze step. A never-released repo starts from the evergreen `releases/latest/download/<package>-linux-arm64.bin` form, which resolves because the release pipeline uploads versionless alias assets alongside the version-stamped ones. Both spellings resolve, so neither is drift: never hand-edit one into the other.
 
 7. **Release verification** section showing `gh attestation verify` against the package's own repo, with the `--signer-repo` flag if the release workflow runs as a reusable workflow from another repo. Mirror exactly: a stale flag here breaks reader trust.
 
@@ -549,7 +549,7 @@ Sync rules:
 
 - Re-check the Repology page on every release. New distros get a new tab; dropped distros get the tab removed.
 - The Python compatibility matrix is auto-generated; never hand-edit it.
-- Version-number references in download URLs must use `releases/latest/download/...`, not pinned tags. Hand-pinned versions in install.md were a long-running source of doc drift.
+- Download URLs in `install.md` are generated, not hand-maintained, so a version number in one is expected rather than drift. The single manual intervention is the documented repair: when a release's binary lane failed, re-point the table at the last release that actually carries binaries, since the freeze pins the version optimistically before the binaries exist (`lint-repo` reports the gap but never repairs it; see `claude.md` § A published release freezes what is missing from it).
 - The Try it tab-set's `Specific version` tab does carry a pinned version as an example — that's intentional (it teaches the syntax). From repomatic `v7.4.0` on, the prepare-release freeze step bumps it automatically (`freeze_install_cli_version` rewrites `{package}@X.Y.Z` and `{package}==X.Y.Z` pins in `docs/install.md`); hand-bumping is only needed on repos pinned to older release engines.
 
 ### `packaging.md`: distribution and dependency reference
@@ -575,9 +575,10 @@ Primary toctree (user-facing), in this order:
 05. `tool-runner` — Only when the project ships a `repomatic run`-style tool runner.
 06. `workflows` — Only when the project publishes reusable workflows.
 07. `test-matrix` — Only when the project documents its CI test-matrix composition.
-08. `security` — Optional, and absent by default: a security page with nothing project-specific to say (no real threat model, no attack surface worth describing, no dedicated reporting channel) is boilerplate that dilutes the docs. Add it only when the project has a genuine security consideration. When present, single-source it as `docs/security.md`: GitHub's security tab detects the file in `docs/` as well as `.github/`, so no duplicate copy is needed.
-09. `skills`, `agents` — Only when the project ships Claude Code skills or agents (see § Recipes › skills/agents pages below).
-10. `benchmark` — Optional comparison page; only useful for projects positioning against alternatives. MyST docstring authoring needs no local page: it is canonically documented on the [click-extra MyST docstrings page](https://kdeldycke.github.io/click-extra/myst-docstrings.html), which also covers the `click-extra convert-to-myst` migration command.
+08. `nuitka` — Only for projects compiling standalone executables through the release engine: the canonical home for build targets, fleet cadence, compile caching and measured build times (the `binaries` page below stays the per-release catalog).
+09. `security` — Optional, and absent by default: a security page with nothing project-specific to say (no real threat model, no attack surface worth describing, no dedicated reporting channel) is boilerplate that dilutes the docs. Add it only when the project has a genuine security consideration. When present, single-source it as `docs/security.md`: GitHub's security tab detects the file in `docs/` as well as `.github/`, so no duplicate copy is needed.
+10. `skills`, `agents` — Only when the project ships Claude Code skills or agents (see § Recipes › skills/agents pages below).
+11. `benchmark` — Optional comparison page; only useful for projects positioning against alternatives. MyST docstring authoring needs no local page: it is canonically documented on the [click-extra MyST docstrings page](https://kdeldycke.github.io/click-extra/myst-docstrings.html), which also covers the `click-extra convert-to-myst` migration command.
 
 Development toctree, in this order:
 
@@ -641,6 +642,7 @@ Page-shape rules that apply across the roster:
   | `managers.md`              | `file-submodule`       |
   | `mkdocs.md`                | `markdown`             |
   | `myst-docstrings.md`       | `pencil`               |
+  | `nuitka.md`                | `file-binary`          |
   | `operation-contracts.md`   | `tasklist`             |
   | `overrides.md`             | `pin`                  |
   | `packaging.md`             | `package-dependents`   |
@@ -769,8 +771,9 @@ Strictness flags:
 
 Theme assets and OpenGraph:
 
-- `html_logo = "assets/logo-square.svg"` and `html_favicon = "assets/favicon.svg"` are the canonical paths. Both files live under `docs/assets/` and ship as SVG so the Furo theme's dark-mode swap works without a separate asset bundle. The `/brand-assets` skill is the canonical producer of these files: it manages the SVG sources (favicon, square logo, banner, social banner), exports light/dark PNG variants, and wires the new files into `docs/conf.py`. When `html_logo`/`html_favicon` are missing or out of date, run `/brand-assets` instead of editing the assets by hand.
-- `ogp_image` must be an **absolute** URL to the committed PNG on the GitHub raw host — `f"https://raw.githubusercontent.com/{github_user}/{project_id}/main/docs/assets/banner-social-light.png"` — never a site-relative `assets/...` path. `docs/assets/` is not copied into the built site (it is neither in `html_static_path` nor referenced by any doc body, so Sphinx's image collector never picks it up), so a relative `ogp_image` resolves against `ogp_site_url` to a URL that 404s for the social crawlers that only ever see the raw HTML. Set it when the project has a banner asset; without `ogp_image`, `sphinxext.opengraph` falls back to the favicon, which scales poorly. Still define `ogp_site_url = f"https://{github_user}.github.io/{project_id}/"` for the page-level `og:url` tag. The PNG is exported from `assets/banner-social.svg` by the `/brand-assets` skill (which also produces the dark variant for dark-mode social cards on platforms that support them).
+- The sidebar logo is Furo's `light_logo`/`dark_logo` **pair** of theme options, set to `"logo-square-light.png"` and `"logo-square-dark.png"`. Never `html_logo`: Furo performs no dark-mode swap on a single logo, so the light-only `assets/logo-square.svg` keeps its near-black wordmark on the dark theme, where it lands around 1.2:1 against Furo's background. Both options must be set for the pair to render at all, and `html_logo` must be unset, since Furo's `sidebar/brand.html` prefers it and skips the pair when it is present. Furo resolves both names against `_static/`, so each PNG needs its own `html_static_path` entry (that setting accepts individual files, which land at the root of `_static/`; listing `docs/assets/` wholesale would copy every screenshot and report along with them). The two PNGs are same-aspect exports of the same SVG, so the swap holds geometry.
+- `html_favicon = "assets/favicon.svg"` is the canonical path, an SVG since browsers handle SVG favicons natively. The `/brand-assets` skill is the canonical producer of every one of these files: it manages the SVG sources (favicon, square logo, banner, social banner), exports light/dark PNG variants, and wires the new files into `docs/conf.py`. When they are missing or out of date, run `/brand-assets` instead of editing the assets by hand.
+- `ogp_image` must be an **absolute** URL to the committed PNG on the GitHub raw host — `f"https://raw.githubusercontent.com/{github_user}/{project_id}/main/docs/assets/banner-social-light.png"` — never a site-relative `assets/...` path. `docs/assets/` is not copied into the built site (only the two sidebar logos are named in `html_static_path`, and no doc body references the banner, so Sphinx's image collector never picks it up), so a relative `ogp_image` resolves against `ogp_site_url` to a URL that 404s for the social crawlers that only ever see the raw HTML. Set it when the project has a banner asset; without `ogp_image`, `sphinxext.opengraph` falls back to the favicon, which scales poorly. Still define `ogp_site_url = f"https://{github_user}.github.io/{project_id}/"` for the page-level `og:url` tag. The PNG is exported from `assets/banner-social.svg` by the `/brand-assets` skill (which also produces the dark variant for dark-mode social cards on platforms that support them).
 - The Furo `announcement` banner template across this lineage references the same `github_user` constant defined at the top of `conf.py`. Rebuilding the announcement string locally inside `html_theme_options` avoids a per-theme override layer.
 
 Pruning checklist before merging any `conf.py` change: