repomatic 7.0.0__tar.gz → 7.1.0__tar.gz

{repomatic-7.0.0 → repomatic-7.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repomatic
-Version: 7.0.0
+Version: 7.1.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
@@ -46,7 +46,7 @@ Classifier: Typing :: Typed
 Requires-Dist: arrow>=1.3
 Requires-Dist: backports-strenum>=1 ; python_full_version < '3.11'
 Requires-Dist: boltons>=25
-Requires-Dist: click-extra>=8.1
+Requires-Dist: click-extra>=8.3
 Requires-Dist: extra-platforms>=12.0.2
 Requires-Dist: packaging>=17
 Requires-Dist: py-walk>=0.3.1
@@ -58,7 +58,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.0.0
+Project-URL: Download, https://github.com/kdeldycke/repomatic/releases/tag/v7.1.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.0.0 → repomatic-7.1.0}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "uv-build>=0.9" ]
 [project]
 # Docs: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
 name = "repomatic"
-version = "7.0.0"
+version = "7.1.0"
 description = "🏭 Automate repository maintenance, releases, and CI/CD workflows"
 readme = "readme.md"
 keywords = [
@@ -84,10 +84,10 @@ dependencies = [
   "backports-strenum>=1; python_version<'3.11'",
   # boltons 25.0.0 dropped Python 3.9, matching our requires-python >= 3.10.
   "boltons>=25",
-  # 8.1.0 is the first release carrying the APIs repomatic uses: the `test-suite`
-  # engine (renamed from `test-plan`) and the `CONFIG_PATH_METADATA_KEY` /
-  # `NORMALIZE_KEYS_METADATA_KEY` schema-metadata constants.
-  "click-extra>=8.1",
+  # click-extra 8.3 adds the `click:config` Sphinx directive and the
+  # `schema_field_infos()` introspection API that `configuration.md` and
+  # `show-config` are built on.
+  "click-extra>=8.3",
   # extra-platforms 12.0.2 reimplemented is_macos() with sys.platform, avoiding
   # the platform.platform() shell-out to ``cmd /c ver`` on Windows that broke
   # under patched subprocess in tests and triggered a CPython 3.10.x bug.
@@ -122,7 +122,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.0.0"
+urls.Download = "https://github.com/kdeldycke/repomatic/releases/tag/v7.1.0"
 urls.Funding = "https://github.com/sponsors/kdeldycke"
 urls.Homepage = "https://github.com/kdeldycke/repomatic"
 urls.Issues = "https://github.com/kdeldycke/repomatic/issues"
@@ -162,6 +162,9 @@ docs = [
   "sphinx-autodoc-typehints>=2.4",
   # sphinx-copybutton 0.5.2 stabilized the copy button behavior for code blocks.
   "sphinx-copybutton>=0.5.2",
+  # sphinx-datatables 1.0.0 is the first stable release; makes the binaries
+  # catalog table searchable and sortable client-side (pulls sphinxcontrib-jquery).
+  "sphinx-datatables>=1",
   # sphinx-design 0.6 introduced the current directive syntax for cards, grids, and tabs.
   "sphinx-design>=0.6",
   # sphinxcontrib-mermaid 1.2.3 fixed mermaid_d3_zoom configuration support.
@@ -170,12 +173,14 @@ docs = [
   "sphinxext-opengraph>=0.13",
 ]
 # types-boltons: first stub release covering boltons 25.0 API (FrozenDict, unique, flatten,
-# strip_ansi). types-pyyaml: stub release covering PyYAML 6.0 (safe_load, safe_dump, full_load).
+# strip_ansi). types-docutils: covers the docutils.nodes imports in docs/conf.py.
+# types-pyyaml: stub release covering PyYAML 6.0 (safe_load, safe_dump, full_load).
 typing = [
   # backports-strenum: provides StrEnum stubs for mypy --python-version 3.10 analysis;
   # not in main deps (version-gated to Python<3.11 there), so added here unconditionally.
   "backports-strenum>=1",
   "types-boltons>=25.0.0.20250822",
+  "types-docutils>=0.22.3.20251115",
   "types-pyyaml>=6.0.12.9",
 ]
 
@@ -200,10 +205,8 @@ exclude-newer = "1 week"
 # bypasses at that date and prunes each entry once its held version ages past
 # `exclude-newer`, returning the package to the normal cooldown. repomatic is
 # pinned to git main (no PyPI release to freeze), so it keeps a permanent
-# "0 day" span. click-extra is held at its 8.1.0 release date so the lock adopts
-# it before the 1-week cooldown elapses; sync-uv-lock prunes this entry once
-# 8.1.0 ages past `exclude-newer`.
-exclude-newer-package = { repomatic = "0 day" }
+# "0 day" span.
+exclude-newer-package = { click-extra = "2026-07-10T00:00:00Z", repomatic = "0 day" }
 # Package is at root level, not in "./src/".
 build-backend.module-root = ""
 
@@ -216,7 +219,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.0.0"
+file-version = "7.1.0"
 include-data-dir = [
   "repomatic/data/awesome_template=repomatic/data/awesome_template",
 ]
@@ -234,7 +237,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.0.0"
+product-version = "7.1.0"
 windows-icon-from-ico = "docs/assets/icon.ico"
 
 [tool.ruff]
@@ -315,6 +318,7 @@ warn_unused_configs = true
 overrides = [
   { module = [
     "py_walk.*",
+    "sphinxcontrib.mermaid",
     "vt",
   ], ignore_missing_imports = true },
 ]
@@ -340,7 +344,7 @@ run.source = [ "repomatic" ]
 report.precision = 2
 
 [tool.bumpversion]
-current_version = "7.0.0"
+current_version = "7.1.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 = [
@@ -422,6 +426,9 @@ exclude = [
   "archive\\.ph",
   # npmjs.com returns 403 to bots.
   "^https://www\\.npmjs\\.com/package/.*$",
+  # VirusTotal analysis pages are a JS app that rate-limits bots, and the
+  # binaries page links one per released binary.
+  "^https://www\\.virustotal\\.com/gui/.*$",
   # star-history.com fragments are JS-rendered and invisible to lychee.
   "^https://star-history\\.com/.*$",
   # githubstatus.com returns 405 to HEAD requests from bots.

{repomatic-7.0.0 → repomatic-7.1.0}/repomatic/__init__.py

@@ -17,5 +17,5 @@
 
 from __future__ import annotations
 
-__version__ = "7.0.0"
-__git_tag_sha__ = "36523e5a56f287e814210042ca7b852147a95498"
+__version__ = "7.1.0"
+__git_tag_sha__ = "8d3bdd26cb0a91c422f1b7210cb978ba75865822"

repomatic-7.1.0/repomatic/binaries_page.py

@@ -0,0 +1,448 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+"""Generate the binaries catalog: a CSV data file and its `docs/binaries.md` page.
+
+The catalog inventories every compiled binary the repository ever released,
+one CSV row per binary: version (linking to the GitHub release), platform
+target (linking to the direct download), release date, and the VirusTotal
+detection snapshot (linking to the live analysis). It gives alpha and beta
+testers a single place to grab binaries from, and the maintainer an overview
+of how antivirus engines treat each release.
+
+The data lives in `docs/assets/binaries.csv`, regenerated wholesale on every
+release from the GitHub Releases API (the single source of truth for
+published assets) and the JSON scan history maintained by `scan-virustotal`.
+The Markdown page renders it through a single `csv-table` directive and is
+otherwise static: it is created once from {data}`PAGE_TEMPLATE` and only its
+marker-delimited region (the detection trend chart) is rewritten afterwards,
+so the intro and section prose stay hand-editable per repository.
+
+```{note}
+On the documentation site, the table is searchable and sortable client-side
+via the `sphinx-datatables` extension, which activates on the
+`sphinx-datatable` CSS class. The extension is optional: without it the
+`csv-table` directive still renders a plain table, and on GitHub the CSV
+file itself gets the built-in searchable grid viewer.
+```
+
+```{note}
+Development builds are only linked, not cataloged: the rolling dev
+pre-release is refreshed on every push to the default branch, so any row
+frozen into the CSV would be stale within hours, while the workflow run
+artifacts behind the link always are the current builds.
+```
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+import logging
+from pathlib import Path
+
+from packaging.version import InvalidVersion, Version
+
+from .binary import NUITKA_BUILD_TARGETS
+from .virustotal import VIRUSTOTAL_GUI_URL
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from .github.releases import ReleaseAsset, ReleaseWithAssets
+    from .virustotal import ScanRecord
+
+BINARY_ASSET_SUFFIXES = (".bin", ".exe")
+"""File extensions identifying compiled binaries among release assets.
+
+Same set the `scan-virustotal` command uploads and the release workflow
+downloads (`--pattern` flags in `_release-engine.yaml`).
+"""
+
+CSV_HEADERS = (
+    "Version",
+    "Platform",
+    "Released",
+    "VirusTotal",
+)
+"""Column headers of the binaries CSV.
+
+Deliberately compact: the version cell carries the link to the GitHub
+release, the platform cell the direct binary download, and the VirusTotal
+cell the analysis link, so no column holds a bare URL, filename, or
+64-character checksum.
+"""
+
+FLAGGED_DANGER_PCT = 10
+"""Flagged-verdict share (percent) at which the catalog shield turns red.
+
+Below it, a flagged binary is the routine Nuitka false-positive tail worth a
+warning tint; from one engine in ten upward, the release deserves a
+false-positive submission round (see the `/av-false-positive` skill).
+"""
+
+PAGE_END_MARKER = "<!-- binaries-end -->"
+"""Closing marker of the generated chart region in the binaries page."""
+
+PAGE_START_MARKER = "<!-- binaries-start -->"
+"""Opening marker of the generated chart region in the binaries page."""
+
+PAGE_TEMPLATE = """\
+---
+orphan: true
+---
+
+# Binaries
+
+All standalone executables published by this repository, one row per binary, newest release first. The version links to its GitHub release, the platform to the direct binary download, and the VirusTotal cell to the file's public analysis.
+
+Compiled Python binaries are regularly flagged by heuristic antivirus engines, so every release is submitted to [VirusTotal](https://www.virustotal.com/): this seeds vendor databases with the new signatures and keeps false positives in check. The VirusTotal cell tracks those false positives: a green check marks binaries no engine flags, and flagged binaries show the share of engine verdicts flagging them, snapshotted minutes after publication and before false-positive reports get processed. The live analysis behind the link supersedes it.
+
+## Development builds
+
+Fresh binaries are compiled from every push to the default branch by the [release workflow]({repo_url}/actions/workflows/release.yaml). To try the latest development build: open the most recent successful run and download the artifact matching your platform (a GitHub account is required, and the binary comes wrapped in a zip). The same builds are also attached to a rolling dev pre-release, a draft only visible to repository maintainers.
+
+<!-- binaries-start -->
+
+<!-- binaries-end -->
+
+## Catalog
+
+The table is searchable and sortable on the documentation site; the raw data lives in [`binaries.csv`](assets/binaries.csv).
+
+```{csv-table}
+:file: assets/binaries.csv
+:header-rows: 1
+:class: sphinx-datatable
+```
+"""
+"""Initial page content, used when the page does not exist yet.
+
+The `{repo_url}` placeholder is substituted with `str.replace` (not
+`str.format`, which would choke on the csv-table directive's braces).
+Everything outside the marker pair is written once and never touched again:
+repositories can reword the prose without fighting the generator.
+
+:meta hide-value:
+"""
+
+
+def _platform_target(name: str) -> str:
+    """Extract the platform-arch target from a binary filename.
+
+    Matches against the known Nuitka build targets (`linux-arm64`, …), the
+    same vocabulary the compile matrix uses. Falls back to the full filename
+    for foreign naming schemes, so the cell always identifies the file.
+    """
+    for target in NUITKA_BUILD_TARGETS:
+        if target in name:
+            return target
+    return name
+
+
+def _release_version(tag: str) -> Version | None:
+    """Parse a release tag as a version, or `None` for foreign tag schemes."""
+    try:
+        return Version(tag.removeprefix("v"))
+    except InvalidVersion:
+        return None
+
+
+def _binary_assets(release: ReleaseWithAssets) -> list[ReleaseAsset]:
+    """Return the release's compiled binaries, sorted by filename."""
+    return sorted(
+        (a for a in release.assets if a.name.endswith(BINARY_ASSET_SUFFIXES)),
+        key=lambda asset: asset.name,
+    )
+
+
+def _at_scan_records(records: Sequence[ScanRecord]) -> dict[str, ScanRecord]:
+    """Index records by SHA-256, keeping the earliest snapshot per file.
+
+    The earliest record is the at-release snapshot; later re-scans of the
+    same file reflect vendor whitelisting, not the state the binary shipped
+    in, so they are excluded from the catalog and chart.
+    """
+    earliest: dict[str, ScanRecord] = {}
+    for record in records:
+        current = earliest.get(record.sha256)
+        if current is None or record.scanned < current.scanned:
+            earliest[record.sha256] = record
+    return earliest
+
+
+def render_chart_section(records: Sequence[ScanRecord]) -> str:
+    """Render the detection trend across releases as a Chart.js timeline.
+
+    Plots the share of antivirus engine verdicts flagging each release's
+    binaries (all platforms aggregated), using the at-release snapshot of
+    every file, on a true time axis: spacing reflects the actual gaps
+    between releases. Points reuse the catalog shields' color language,
+    read at view time from sphinx-design's CSS variables so they match the
+    theme exactly (with hardcoded fallbacks). The data is embedded in the
+    page rather than fetched, so the chart also works on `file://`
+    previews; only the Chart.js bundle comes from its CDN, mirroring how
+    the table's DataTables assets load.
+
+    :return: A `## VirusTotal detections` section with a `raw` HTML fence,
+        or an empty string when fewer than two releases have records (a
+        one-point trend is not a trend).
+    """
+    at_scan = _at_scan_records(records).values()
+    per_tag: dict[str, tuple[str, int, int]] = {}
+    for record in at_scan:
+        date, flagged, total = per_tag.get(record.tag, (record.scanned, 0, 0))
+        per_tag[record.tag] = (
+            min(date, record.scanned),
+            flagged + record.stats.flagged,
+            total + record.stats.total,
+        )
+
+    points = []
+    for tag, (date, flagged, total) in per_tag.items():
+        version = _release_version(tag)
+        if version is None:
+            continue
+        if total:
+            points.append((version, tag, date, flagged, total))
+    points.sort()
+    if len(points) < 2:
+        return ""
+
+    payload = json.dumps(
+        [
+            {
+                "date": date,
+                "flagged": flagged,
+                "pct": round(100 * flagged / total, 1),
+                "tag": tag,
+                "total": total,
+            }
+            for _version, tag, date, flagged, total in points
+        ],
+        sort_keys=True,
+    )
+    return (
+        "## VirusTotal detections\n\n"
+        "Share of antivirus engine verdicts flagging the binaries of each "
+        "release, at scan time. Colors follow the catalog shields: green "
+        f"for zero detections, amber below {FLAGGED_DANGER_PCT}%, red from "
+        "there up.\n\n"
+        "```{raw} html\n"
+        '<div style="height: 320px;"><canvas id="vt-trend"></canvas></div>\n'
+        '<script src="https://cdn.jsdelivr.net/npm/chart.js@4.5.0/dist/'
+        'chart.umd.min.js"></script>\n'
+        "<script>\n"
+        f"const VT_TREND = {payload};\n"
+        f"const VT_DANGER_PCT = {FLAGGED_DANGER_PCT};\n"
+        "const vtCss = getComputedStyle(document.documentElement);\n"
+        "const vtColor = (name, fallback) =>\n"
+        "    vtCss.getPropertyValue(name).trim() || fallback;\n"
+        "const vtTint = (p) => {\n"
+        '    if (p.pct === 0) { return vtColor("--sd-color-success", "#28a745"); }\n'
+        "    return p.pct >= VT_DANGER_PCT\n"
+        '        ? vtColor("--sd-color-danger", "#dc3545")\n'
+        '        : vtColor("--sd-color-warning", "#f0b37e");\n'
+        "};\n"
+        'new Chart(document.getElementById("vt-trend"), {\n'
+        '    type: "line",\n'
+        "    data: {\n"
+        "        datasets: [{\n"
+        "            data: VT_TREND.map((p) => ({x: Date.parse(p.date), y: p.pct})),\n"
+        '            borderColor: "#88888866",\n'
+        "            pointBackgroundColor: VT_TREND.map(vtTint),\n"
+        "            pointBorderColor: VT_TREND.map(vtTint),\n"
+        "            pointRadius: 4,\n"
+        "            tension: 0.2,\n"
+        "        }],\n"
+        "    },\n"
+        "    options: {\n"
+        "        maintainAspectRatio: false,\n"
+        "        plugins: {\n"
+        "            legend: {display: false},\n"
+        "            tooltip: {callbacks: {\n"
+        "                title: (items) => VT_TREND[items[0].dataIndex].tag,\n"
+        "                label: (item) => {\n"
+        "                    const p = VT_TREND[item.dataIndex];\n"
+        '                    return p.flagged + " / " + p.total\n'
+        '                        + " verdicts flagged (" + p.pct + "%)";\n'
+        "                },\n"
+        "            }},\n"
+        "        },\n"
+        "        scales: {\n"
+        "            x: {\n"
+        '                type: "linear",\n'
+        "                ticks: {\n"
+        "                    maxTicksLimit: 8,\n"
+        "                    callback: (value) =>\n"
+        "                        new Date(value).toISOString().slice(0, 10),\n"
+        "                },\n"
+        "            },\n"
+        "            y: {\n"
+        "                beginAtZero: true,\n"
+        '                title: {display: true, text: "Flagged verdicts (%)"},\n'
+        "            },\n"
+        "        },\n"
+        "    },\n"
+        "});\n"
+        "</script>\n"
+        "```"
+    )
+
+
+def render_binaries_csv(
+    repo_slug: str,
+    releases: Sequence[ReleaseWithAssets],
+    records: Sequence[ScanRecord],
+) -> str:
+    """Render the catalog data as CSV, one row per released binary.
+
+    Rows cover every published release carrying compiled binaries, ordered
+    by descending version then filename. Cells hold Markdown links (parsed
+    by MyST inside the `csv-table` directive): the version to the GitHub
+    release, the platform to the binary download, and the VirusTotal cell to
+    the file's analysis. The VirusTotal cell renders the at-release snapshot
+    as a green check when no engine flags the binary, as the flagged-verdict
+    share (tinted by {data}`FLAGGED_DANGER_PCT`) otherwise, and as a bare
+    `analysis` link when no snapshot exists. Assets without a digest get an
+    empty VirusTotal cell.
+
+    ```{caution}
+    The version and platform cells decorate their links with sphinx-design's
+    `octicon` role, so the rendering repository needs `sphinx-design` in its
+    documentation build (already true across this ecosystem's docs stacks).
+    ```
+
+    :param repo_slug: Repository in `owner/repo` form.
+    :param releases: Releases from
+        {func}`repomatic.github.releases.get_releases_with_assets`.
+    :param records: Detection snapshots from the scan history file.
+    :return: The full CSV content, header row included.
+    """
+    versioned = [
+        (version, release)
+        for release in releases
+        if not release.draft and (version := _release_version(release.tag)) is not None
+    ]
+    versioned.sort(key=lambda pair: pair[0], reverse=True)
+
+    at_scan = _at_scan_records(records)
+    buffer = io.StringIO()
+    writer = csv.writer(buffer, lineterminator="\n")
+    writer.writerow(CSV_HEADERS)
+    for version, release in versioned:
+        release_url = f"https://github.com/{repo_slug}/releases/tag/{release.tag}"
+        for asset in _binary_assets(release):
+            if asset.sha256:
+                vt_url = VIRUSTOTAL_GUI_URL.format(sha256=asset.sha256)
+                record = at_scan.get(asset.sha256)
+                if record and record.stats.total:
+                    # The KPI is the distance to the goal (zero false
+                    # positives), so flagged rows show the failure share and
+                    # clean rows reduce to a green check: exceptions stand
+                    # out, the goal state stays calm.
+                    if record.stats.flagged == 0:
+                        vt_cell = (
+                            f"[{{octicon}}`shield-check;1em;sd-text-success`]({vt_url})"
+                        )
+                    else:
+                        pct = 100 * record.stats.flagged / record.stats.total
+                        tint = (
+                            "sd-text-danger"
+                            if pct >= FLAGGED_DANGER_PCT
+                            else "sd-text-warning"
+                        )
+                        vt_cell = (
+                            f"[{{octicon}}`shield;1em;{tint}` {pct:.1f}%]({vt_url})"
+                        )
+                else:
+                    vt_cell = f"[{{octicon}}`shield` analysis]({vt_url})"
+            else:
+                vt_cell = ""
+            # The octicon role comes from sphinx-design, same as the icons in
+            # the docs page titles; the icons are part of the link text so
+            # they stay clickable with their label.
+            writer.writerow((
+                f"[`{version}` {{octicon}}`link-external`]({release_url})",
+                f"[{{octicon}}`download` `{_platform_target(asset.name)}`]"
+                f"({asset.download_url})",
+                release.date,
+                vt_cell,
+            ))
+    return buffer.getvalue()
+
+
+def update_binaries_csv(csv_path: Path, content: str) -> bool:
+    """Write the catalog CSV, creating parent directories as needed.
+
+    :param csv_path: Path to the CSV file.
+    :param content: Rendered CSV from {func}`render_binaries_csv`.
+    :return: `True` when the file was created or its content changed.
+    """
+    if csv_path.exists() and csv_path.read_text(encoding="UTF-8") == content:
+        logging.info(f"Binaries CSV {csv_path} already up to date.")
+        return False
+    csv_path.parent.mkdir(parents=True, exist_ok=True)
+    csv_path.write_text(content, encoding="UTF-8")
+    logging.info(f"Wrote binaries CSV {csv_path}.")
+    return True
+
+
+def update_binaries_page(page_path: Path, chart_section: str, repo_slug: str) -> bool:
+    """Create the binaries page if missing and refresh its chart region.
+
+    A missing page is created (with parent directories) from
+    {data}`PAGE_TEMPLATE`. On an existing page only the region between
+    {data}`PAGE_START_MARKER` and {data}`PAGE_END_MARKER` is replaced,
+    leaving all surrounding prose untouched.
+
+    :param page_path: Path to the Markdown page.
+    :param chart_section: Rendered chart from {func}`render_chart_section`,
+        or an empty string to leave the region empty.
+    :param repo_slug: Repository in `owner/repo` form, interpolated into the
+        template on first creation.
+    :return: `True` when the file was created or its content changed.
+    :raises ValueError: When the page exists but lacks the markers. Loud on
+        purpose: a page not written by this generator must never be
+        overwritten.
+    """
+    original = None
+    if page_path.exists():
+        original = page_path.read_text(encoding="UTF-8")
+        if PAGE_START_MARKER not in original or PAGE_END_MARKER not in original:
+            raise ValueError(
+                f"{page_path} lacks the {PAGE_START_MARKER} / {PAGE_END_MARKER} "
+                "markers, refusing to overwrite it."
+            )
+        text = original
+    else:
+        text = PAGE_TEMPLATE.replace("{repo_url}", f"https://github.com/{repo_slug}")
+
+    before, rest = text.split(PAGE_START_MARKER, 1)
+    _, after = rest.split(PAGE_END_MARKER, 1)
+    section = chart_section.strip()
+    between = f"\n\n{section}\n\n" if section else "\n\n"
+    new_text = before + PAGE_START_MARKER + between + PAGE_END_MARKER + after
+
+    if new_text == original:
+        logging.info(f"Binaries page {page_path} already up to date.")
+        return False
+    page_path.parent.mkdir(parents=True, exist_ok=True)
+    page_path.write_text(new_text, encoding="UTF-8")
+    logging.info(f"Wrote binaries page {page_path}.")
+    return True

{repomatic-7.0.0 → repomatic-7.1.0}/repomatic/binary.py

@@ -112,6 +112,7 @@ FLAT_BUILD_TARGETS = [
 
 
 BINARY_AFFECTING_PATHS: Final[tuple[str, ...]] = (
+    ".github/workflows/_release-engine.yaml",
     ".github/workflows/release.yaml",
     "pyproject.toml",
     "tests/",
@@ -122,6 +123,12 @@ BINARY_AFFECTING_PATHS: Final[tuple[str, ...]] = (
 Project-specific source directories (derived from `[project.scripts]` in
 `pyproject.toml`) are added dynamically by
 {attr}`~repomatic.metadata.Metadata.binary_affecting_paths`.
+
+The release workflow entries cover both layouts: upstream keeps the
+`_release-engine.yaml` lane (which defines the Nuitka compile and binary
+self-test jobs) in-repo, while downstream repos call the engine cross-repo
+from their generated `release.yaml`, so a pin bump there rightly triggers a
+rebuild.
 """
 
 SKIP_BINARY_BUILD_BRANCHES: Final[frozenset[str]] = frozenset((

{repomatic-7.0.0 → repomatic-7.1.0}/repomatic/cache.py

@@ -248,6 +248,12 @@ def store_binary(
         tmp_path = Path(tmp)
         shutil.copy2(source, tmp_path)
         tmp_path.chmod(0o755)
+        # copy2 preserves the source mtime, which for a binary extracted from
+        # a release archive is the upstream build date. Purging ages entries
+        # by mtime, so an old build date would get the entry deleted by the
+        # auto_purge() call below, before this store even returns. Stamp the
+        # store time instead.
+        os.utime(tmp_path)
         tmp_path.replace(dest)
     except BaseException:
         # Clean up partial writes on any failure.