New pack-attestation command

Author: kdeldycke

.github/workflows/_release-engine.yaml

@@ -237,28 +237,29 @@ jobs:
           --repo "${{ github.repository }}"
           --signer-repo kdeldycke/repomatic
       - name: Name the attestation bundle after its binary
-        # actions/attest writes every bundle to the same basename, so all matrix targets produce an `attestation.json`.
-        # The run artifacts keep them apart, but publish-release downloads them with `merge-multiple: true` into one
-        # directory, where identical filenames overwrite each other and only the last target's bundle reaches the
-        # release. Naming each after its subject fixes that, and makes the sidecar say which binary it covers.
+        # actions/attest writes every bundle to the same basename, so all matrix targets produce an `attestation.json`
+        # and publish-release's `merge-multiple: true` download would keep only the last. See
+        # repomatic/attestation.py, which owns the naming rule for every attested asset in this lane.
         if: >-
           github.ref == 'refs/heads/main'
           && fromJSON(needs.metadata.outputs.metadata).release_commits_matrix
           && steps.attest-binary.outputs.bundle-path
         env:
-          BIN_NAME: ${{ matrix.bin_name }}
           BUNDLE_PATH: ${{ steps.attest-binary.outputs.bundle-path }}
         shell: bash
-        run: cp "${BUNDLE_PATH}" "${BIN_NAME}.attestation.json"
+        run: >
+          uv --no-progress run --frozen -- repomatic
+          pack-attestation --bundle "${BUNDLE_PATH}"
       - name: Upload attestation bundle
+        # Globbed rather than named, so the filename stays the CLI's to decide.
         if: >-
           github.ref == 'refs/heads/main'
           && fromJSON(needs.metadata.outputs.metadata).release_commits_matrix
           && steps.attest-binary.outputs.bundle-path
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: attestation-${{ matrix.bin_name }}-${{ matrix.short_sha }}
-          path: ${{ matrix.bin_name }}.attestation.json
+          path: "*.attestation.json"
 
   test-binaries:
     name: "${{ matrix.state == 'stable' && '✅' || '⁉️' }} ${{ matrix.os }}, ${{ matrix.short_sha }} test"
@@ -502,21 +503,18 @@ jobs:
           --repo "${{ github.repository }}"
           --signer-repo kdeldycke/repomatic
       - name: Attach to release draft
+        # pack-attestation names the bundle after the tarball it attests and prints both paths, so neither filename
+        # is spelled here. See repomatic/attestation.py.
         env:
           CURRENT_VERSION: ${{ matrix.current_version }}
-          ASSET_NAME: >-
-            ${{
-              fromJSON(needs.metadata.outputs.metadata).manpages_asset_name
-              || format('{0}-manpages', fromJSON(needs.metadata.outputs.metadata).package_name)
-            }}
           BUNDLE_PATH: ${{ steps.attest-manpages.outputs.bundle-path }}
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
-        run: >
-          cp "${BUNDLE_PATH}" "${ASSET_NAME}.attestation.json" &&
-          gh release upload "v${CURRENT_VERSION}"
-          "${ASSET_NAME}.tar.gz" "${ASSET_NAME}.attestation.json"
-          --repo "${{ github.repository }}"
-          --clobber
+        run: |
+          uv --no-progress run --frozen -- repomatic \
+            pack-attestation --bundle "${BUNDLE_PATH}" > upload-list.txt
+          xargs gh release upload "v${CURRENT_VERSION}" \
+            --repo "${{ github.repository }}" \
+            --clobber < upload-list.txt
 
   # Attach the consumer-built extra assets declared by `release-assets` in `[tool.repomatic]`. Each declared filename
   # must arrive as a `release-asset-<filename>` run artifact, uploaded by a job the consumer defines in its own
@@ -542,6 +540,15 @@ jobs:
       contents: write
       id-token: write
     steps:
+      # Checkout first, before the download below: actions/checkout deletes everything in a workspace holding no
+      # `.git` of its own, so downloading the assets ahead of it drops them on the floor. The tree is what lets the
+      # final step resolve the CLI from `uv.lock`.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ matrix.commit }}
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.1"
       - name: Download asset artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
@@ -578,21 +585,23 @@ jobs:
               --signer-repo kdeldycke/repomatic
           done
       - name: Attach assets to release draft
-        # The bundle is named after the package rather than this job, so it sorts beside the assets it covers instead of
-        # landing under `e` on a release page listed alphabetically. Copied after the attest step, so it never ends up
-        # as a subject of itself.
+        # A repository declaring one asset gets a bundle named after it; several assets share one bundle, which then
+        # takes the `--name` set name because no single filename can claim it. The bundle lands after the attest step
+        # above, so it never ends up a subject of itself. See repomatic/attestation.py.
         env:
           GH_TOKEN: ${{ secrets.REPOMATIC_PAT || github.token }}
           CURRENT_VERSION: ${{ matrix.current_version }}
           BUNDLE_PATH: ${{ steps.attest-assets.outputs.bundle-path }}
           PACKAGE_NAME: ${{ fromJSON(needs.metadata.outputs.metadata).package_name }}
         shell: bash
         run: |
-          cp "${BUNDLE_PATH}" "release-assets/${PACKAGE_NAME}-extra-assets.attestation.json"
-          gh release upload "v${CURRENT_VERSION}" \
-            release-assets/* \
+          uv --no-progress run --frozen -- repomatic pack-attestation \
+            --bundle "${BUNDLE_PATH}" \
+            --dir release-assets \
+            --name "${PACKAGE_NAME}-extra-assets" > upload-list.txt
+          xargs gh release upload "v${CURRENT_VERSION}" \
             --repo "${{ github.repository }}" \
-            --clobber
+            --clobber < upload-list.txt
 
   publish-release:
     name: 🎉 Publish GitHub release (${{ matrix.short_sha }})
@@ -626,6 +635,14 @@ jobs:
     permissions:
       contents: write
     steps:
+      # Checkout first, before the download below: actions/checkout deletes everything in a workspace holding no
+      # `.git` of its own, so downloading the binaries ahead of it drops them on the floor. The CLI call further down
+      # resolves from `uv.lock`, so it needs the release commit's tree: upstream always runs the unfrozen form,
+      # whatever the freeze wrote. See repomatic/prepare_release.py for why.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        if: needs.compile-binaries.result != 'skipped'
+        with:
+          ref: ${{ matrix.commit }}
       - name: Download binary and attestation artifacts
         # Gate on != 'skipped' (not == 'success') so partial-matrix runs still
         # attach their healthy binaries: see docs/workflows.md "Matrix fail-fast strategy".
@@ -635,12 +652,6 @@ jobs:
           pattern: "*-${{ matrix.short_sha }}"
           path: ./compile-assets
           merge-multiple: true
-      # The CLI call below resolves from `uv.lock`, so it needs the release commit's tree: upstream always runs
-      # the unfrozen form, whatever the freeze wrote. See repomatic/prepare_release.py for why.
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        if: needs.compile-binaries.result != 'skipped'
-        with:
-          ref: ${{ matrix.commit }}
       - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         if: needs.compile-binaries.result != 'skipped'
         with:

changelog.md

@@ -5,6 +5,8 @@
 > [!WARNING]
 > This version is **not released yet** and is under active development.
 
+- **Breaking:** attestation bundles now carry the full filename of the asset they attest, so `repomatic-manpages.attestation.json` becomes `repomatic-manpages.tar.gz.attestation.json`. A repository declaring one extra asset gets `<filename>.attestation.json` in place of `<package-name>-extra-assets.attestation.json`.
+- New `pack-attestation` command names an attestation bundle after the asset it attests and prints the release upload list.
 - The release lane's `publish-release` job now checks out the repository, so uploading binaries to the release no longer fails with `Failed to spawn: repomatic`. `7.7.0` shipped with no standalone executables because of it.
 - `lint-changelog` re-confirms a release live before dropping its availability admonition, so a day-old cache no longer reports a just-published version as missing.
 - The readme's logo is now an absolute URL, so it renders on the PyPI project page instead of 404ing.

docs/repomatic.md

@@ -20,6 +20,15 @@
 
 ## Submodules
 
+## `repomatic.attestation` module
+
+```{eval-rst}
+.. automodule:: repomatic.attestation
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```
+
 ## `repomatic.awesome_toc` module
 
 ```{eval-rst}

docs/tests.md

@@ -27,6 +27,15 @@
    :undoc-members:
 ```
 
+## `tests.test_attestation` module
+
+```{eval-rst}
+.. automodule:: tests.test_attestation
+   :members:
+   :show-inheritance:
+   :undoc-members:
+```
+
 ## `tests.test_awesome_template` module
 
 ```{eval-rst}

docs/workflows.md

@@ -550,7 +550,7 @@ flowchart TD
 - Compiles standalone binaries using [`Nuitka`](https://github.com/Nuitka/Nuitka) for Linux/macOS/Windows on `x64`/`arm64`
 - Linux targets compile inside digest-pinned `manylinux_2_28` containers and macOS targets pin `MACOSX_DEPLOYMENT_TARGET`, so binaries keep the [documented OS floors](binaries.md#minimum-os-requirements) instead of inheriting the runner image's
 - Verifies each binary's architecture and measures its actual glibc / macOS floor against the declared one (`repomatic verify-binary`, parsing ELF/Mach-O/PE headers natively)
-- On release pushes, each binary is attested and its sigstore bundle renamed after the binary it covers (`<binary-name>.attestation.json`), so no two targets collide once the bundles are merged. Binaries and bundles leave the job as run artifacts, and [`publish-release`](#publish-release-publish-release) attaches them to the release
+- On release pushes, each binary is attested and its sigstore bundle renamed after the binary it covers (`<binary-name>.attestation.json`) by [`repomatic pack-attestation`](cli.md), so no two targets collide once the bundles are merged. Binaries and bundles leave the job as run artifacts, and [`publish-release`](#publish-release-publish-release) attaches them to the release
 - **Requires**:
   - Python package with [CLI entry points](https://docs.astral.sh/uv/concepts/projects/config/#entry-points) defined in `pyproject.toml`
 - **Skipped if** `[tool.repomatic] nuitka = false` is set in `pyproject.toml` (for projects with CLI entry points that don't need standalone binaries)
@@ -591,7 +591,7 @@ flowchart TD
 
 - Renders one roff `.1` file per (sub)command in the Click tree declared by `[tool.repomatic.manpages]` by shelling out to `click-extra wrap --man --output-dir man "${SCRIPT}"` against the consumer's already-synced venv
 - Bundles the pages as a single `<asset-name>.tar.gz` and uploads them to the GitHub release **draft** via `gh release upload --clobber`, before `publish-release` publishes and locks the release
-- The tarball is attested with the same provenance chain as the compiled binaries: its sigstore bundle rides along as an `<asset-name>.attestation.json` asset, and provenance verifies with `gh attestation verify <asset-name>.tar.gz --repo <consumer> --signer-repo kdeldycke/repomatic`
+- The tarball is attested with the same provenance chain as the compiled binaries: its sigstore bundle rides along as an `<asset-name>.tar.gz.attestation.json` asset, named by [`repomatic pack-attestation`](cli.md) after the file it covers, and provenance verifies with `gh attestation verify <asset-name>.tar.gz --repo <consumer> --signer-repo kdeldycke/repomatic`
 - **Requires**:
   - `manpages.script = "..."` in `[tool.repomatic]`. The value follows the same shape as `click-extra wrap --man SCRIPT`: a `module:function` path (preferred when the console-script entry point dispatches through a wrapper), an entry-point name, a `.py` file path, or a plain importable module name
   - The consumer's `click-extra` floor is `>= 8`: the `--output-dir DIR` option to `click-extra wrap --man` writes one `.1` file per resolved (sub)command into `DIR`, creating the directory if missing
@@ -604,7 +604,8 @@ flowchart TD
 
 - Attaches consumer-built assets declared by the `release-assets` filename list in `[tool.repomatic]`: each file must be uploaded as a `release-asset-<filename>` run artifact by a job the consumer defines in its own release workflow, the same caller-side handoff the wheel's `build` lane uses
 - The build code therefore stays in the downstream repository as regular workflow code, reviewed and linted there: the engine never executes consumer-supplied commands, it only downloads, attests, verifies, and uploads
-- Assets are attested with the same provenance chain as the compiled binaries and uploaded to the GitHub release **draft** together with their sigstore bundle (`<package-name>-extra-assets.attestation.json`), before `publish-release` publishes and locks the release; provenance verifies with `gh attestation verify <file> --repo <consumer> --signer-repo kdeldycke/repomatic`
+- Assets are attested with the same provenance chain as the compiled binaries and uploaded to the GitHub release **draft** together with their sigstore bundle, before `publish-release` publishes and locks the release; provenance verifies with `gh attestation verify <file> --repo <consumer> --signer-repo kdeldycke/repomatic`
+- [`repomatic pack-attestation`](cli.md) names that bundle. A repository declaring a single asset gets `<filename>.attestation.json`, matching the binaries and the man-page tarball, so the sidecar sorts directly beside what it covers. Several declared assets share one bundle (`actions/attest` emits a single attestation listing every subject), which then falls back to `<package-name>-extra-assets.attestation.json` because no one filename can claim it
 - A declared asset whose artifact never landed fails the job loudly, and that failure blocks `publish-release`, so a broken consumer build lane cannot silently ship a release without its asset. The release stays a draft, which is the recoverable state: re-run the lane, or attach the file by hand, then publish. Once published the release is immutable and the asset can never be added
 - **Requires**:
   - A non-empty `release-assets` list in the consumer's `pyproject.toml`, with space-free filenames