base-cli 0.5.0__tar.gz → 0.5.1__tar.gz

{base_cli-0.5.0 → base_cli-0.5.1}/.github/workflows/package.yml

@@ -17,12 +17,17 @@ on:
       - "scripts/verify_release_assets.py"
       - "scripts/validate_changelog.py"
       - "scripts/validate_release_ref.py"
+      - "scripts/validate_release_docs.py"
       - "scripts/validate_release_provenance.py"
+      - "scripts/verify_pypi_metadata.py"
       - "CHANGELOG.md"
       - "examples/**"
       - "compatibility/**"
       - "docs/releasing.md"
       - "tests/test_package_workflow.py"
+      - "tests/test_validate_package_artifact.py"
+      - "tests/test_validate_release_docs.py"
+      - "tests/test_verify_pypi_metadata.py"
       - "tests/test_verify_release_assets.py"
       - "tests/test_validate_release_provenance.py"
       - "requirements/release.in"
@@ -43,6 +48,11 @@ on:
           - testpypi
           - pypi
         default: testpypi
+      release_tag:
+        description: "Annotated version tag to publish when dispatching from the default branch"
+        required: false
+        type: string
+        default: ""
 
 permissions:
   contents: read
@@ -61,11 +71,15 @@ jobs:
     timeout-minutes: 10
     outputs:
       version: ${{ steps.metadata.outputs.version }}
+      source_commit: ${{ steps.metadata.outputs.source_commit }}
+      release_tag: ${{ steps.metadata.outputs.release_tag }}
+      source_ref_type: ${{ steps.metadata.outputs.source_ref_type }}
     steps:
       - name: Check out source
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -74,18 +88,44 @@ jobs:
 
       - name: Read package version
         id: metadata
-        run: echo "version=$(tr -d '\\r\\n' < VERSION)" >> "$GITHUB_OUTPUT"
+        env:
+          REQUESTED_RELEASE_TAG: ${{ inputs.release_tag || '' }}
+        run: |
+          version="$(tr -d '\\r\\n' < VERSION)"
+          release_tag="$REQUESTED_RELEASE_TAG"
+          if [[ -n "$release_tag" ]]; then
+            source_ref_type=tag
+            source_commit="$(git rev-parse --verify "refs/tags/$release_tag^{}")"
+          else
+            source_ref_type="$GITHUB_REF_TYPE"
+            source_commit="$GITHUB_SHA"
+            if [[ "$source_ref_type" == tag ]]; then
+              release_tag="$GITHUB_REF_NAME"
+            fi
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "source_commit=$source_commit" >> "$GITHUB_OUTPUT"
+          echo "release_tag=$release_tag" >> "$GITHUB_OUTPUT"
+          echo "source_ref_type=$source_ref_type" >> "$GITHUB_OUTPUT"
 
       - name: Validate release ref
         env:
           PUBLISH_TARGET: ${{ inputs.publish_target || '' }}
+          REQUESTED_RELEASE_TAG: ${{ inputs.release_tag || '' }}
+          SOURCE_REF_TYPE: ${{ steps.metadata.outputs.source_ref_type }}
+          RELEASE_TAG: ${{ steps.metadata.outputs.release_tag }}
+          VERSION: ${{ steps.metadata.outputs.version }}
         run: |
-          if [[ "$GITHUB_REF_TYPE" == "tag" && "$GITHUB_REF_NAME" != "v${{ steps.metadata.outputs.version }}" ]]; then
-            echo "Release tag must be v${{ steps.metadata.outputs.version }}; got $GITHUB_REF_NAME" >&2
+          if [[ "$SOURCE_REF_TYPE" == "tag" && "$RELEASE_TAG" != "v$VERSION" ]]; then
+            echo "Release tag must be v$VERSION; got $RELEASE_TAG" >&2
+            exit 1
+          fi
+          if [[ "$PUBLISH_TARGET" == "pypi" && "$SOURCE_REF_TYPE" != "tag" ]]; then
+            echo "PyPI publication requires a matching version tag." >&2
             exit 1
           fi
-          if [[ "$PUBLISH_TARGET" == "pypi" && "$GITHUB_REF_TYPE" != "tag" ]]; then
-            echo "PyPI publication requires dispatching this workflow from the matching version tag." >&2
+          if [[ "$PUBLISH_TARGET" == "pypi" && "$GITHUB_EVENT_NAME" == workflow_dispatch && -z "$REQUESTED_RELEASE_TAG" ]]; then
+            echo "Manual PyPI publication requires the release_tag input." >&2
             exit 1
           fi
 
@@ -93,11 +133,16 @@ jobs:
         run: python scripts/validate_changelog.py
 
       - name: Validate tagged release notes
-        if: ${{ github.ref_type == 'tag' }}
+        if: ${{ steps.metadata.outputs.source_ref_type == 'tag' }}
         env:
-          RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_TAG: ${{ steps.metadata.outputs.release_tag }}
         run: python scripts/validate_release_ref.py
 
+      - name: Validate release-facing documentation
+        env:
+          RELEASE_TAG: ${{ steps.metadata.outputs.release_tag }}
+        run: python scripts/validate_release_docs.py
+
       - name: Prepare clean artifact destination
         run: |
           git clean -ffdx
@@ -111,12 +156,13 @@ jobs:
           # Keep the reproducibility input numeric; push-event timestamps are
           # ISO-8601 strings and are not accepted by wheel/build backends.
           SOURCE_DATE_EPOCH: '0'
+          SOURCE_COMMIT: ${{ steps.metadata.outputs.source_commit }}
         run: |
           rm -rf dist-a dist-b "$RUNNER_TEMP/base-cli-build-a" "$RUNNER_TEMP/base-cli-build-b"
           mkdir -p dist-a dist-b
           mkdir -p "$RUNNER_TEMP/base-cli-build-a" "$RUNNER_TEMP/base-cli-build-b"
-          git archive "$GITHUB_SHA" | tar -x -C "$RUNNER_TEMP/base-cli-build-a"
-          git archive "$GITHUB_SHA" | tar -x -C "$RUNNER_TEMP/base-cli-build-b"
+          git archive "$SOURCE_COMMIT" | tar -x -C "$RUNNER_TEMP/base-cli-build-a"
+          git archive "$SOURCE_COMMIT" | tar -x -C "$RUNNER_TEMP/base-cli-build-b"
           (cd "$RUNNER_TEMP/base-cli-build-a" && python -m build --sdist --wheel --outdir "$GITHUB_WORKSPACE/dist-a")
           (cd "$RUNNER_TEMP/base-cli-build-b" && python -m build --sdist --wheel --outdir "$GITHUB_WORKSPACE/dist-b")
           python - <<'PY'
@@ -155,13 +201,13 @@ jobs:
 
       - name: Generate release checksums and SPDX SBOM
         env:
-          SOURCE_REVISION: ${{ github.sha }}
+          SOURCE_REVISION: ${{ steps.metadata.outputs.source_commit }}
           SOURCE_DATE_EPOCH: '0'
         run: python scripts/generate_release_metadata.py dist
 
       - name: Validate release checksums and SPDX SBOM
         env:
-          SOURCE_REVISION: ${{ github.sha }}
+          SOURCE_REVISION: ${{ steps.metadata.outputs.source_commit }}
         run: python scripts/validate_release_metadata.py dist
 
       - name: Upload reviewed distributions
@@ -199,6 +245,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          ref: ${{ needs.build.outputs.source_commit }}
 
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -250,6 +297,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          ref: ${{ needs.build.outputs.source_commit }}
 
       - name: Fetch trusted main history
         run: git fetch --no-tags --prune origin "refs/heads/main:refs/remotes/origin/main"
@@ -257,7 +305,15 @@ jobs:
       - name: Verify release provenance
         env:
           PUBLISH_TARGET: ${{ inputs.publish_target || '' }}
-        run: python scripts/validate_release_provenance.py
+          SOURCE_REF_TYPE: ${{ needs.build.outputs.source_ref_type }}
+          RELEASE_TAG: ${{ needs.build.outputs.release_tag }}
+          SOURCE_COMMIT: ${{ needs.build.outputs.source_commit }}
+        run: |
+          python scripts/validate_release_provenance.py \
+            --ref-type "$SOURCE_REF_TYPE" \
+            --tag "$RELEASE_TAG" \
+            --publish-target "$PUBLISH_TARGET" \
+            --source-commit "$SOURCE_COMMIT"
 
   publish:
     name: Publish reviewed distribution
@@ -280,14 +336,14 @@ jobs:
 
       - name: Publish to TestPyPI
         if: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_target == 'testpypi' }}
-        uses: pypa/gh-action-pypi-publish@4bb033805d9e19112d8c697528791ff53f6c2f74
+        uses: pypa/gh-action-pypi-publish@v1.14.2 # v1.14.2 image tag is required by this composite action
         with:
           packages-dir: dist
           repository-url: https://test.pypi.org/legacy/
 
       - name: Publish to PyPI
         if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || (github.event_name == 'workflow_dispatch' && inputs.publish_target == 'pypi') }}
-        uses: pypa/gh-action-pypi-publish@4bb033805d9e19112d8c697528791ff53f6c2f74
+        uses: pypa/gh-action-pypi-publish@v1.14.2 # v1.14.2 image tag is required by this composite action
         with:
           packages-dir: dist
 
@@ -325,10 +381,32 @@ jobs:
           subject-checksums: dist/SHA256SUMS
           sbom-path: dist/SBOM.spdx.json
 
+  verify_pypi:
+    name: Verify published PyPI metadata
+    needs: [build, publish, attest]
+    if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || (github.event_name == 'workflow_dispatch' && inputs.publish_target == 'pypi' && inputs.release_tag != '') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.build.outputs.source_commit }}
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+
+      - name: Verify PyPI description and version
+        run: python scripts/verify_pypi_metadata.py --version "${{ needs.build.outputs.version }}"
+
   release:
     name: Create GitHub Release
-    needs: [build, smoke, provenance, publish, attest]
-    if: ${{ github.event_name == 'push' && github.ref_type == 'tag' }}
+    needs: [build, smoke, provenance, publish, attest, verify_pypi]
+    if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || (github.event_name == 'workflow_dispatch' && inputs.publish_target == 'pypi' && inputs.release_tag != '') }}
     runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
@@ -337,6 +415,9 @@ jobs:
     steps:
       - name: Check out the tag source
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.build.outputs.source_commit }}
 
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
@@ -358,13 +439,17 @@ jobs:
       - name: Verify and create immutable GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
+          SOURCE_REVISION: ${{ needs.build.outputs.source_commit }}
+          RELEASE_TAG: ${{ needs.build.outputs.release_tag }}
+          SOURCE_COMMIT: ${{ needs.build.outputs.source_commit }}
         run: |
           set -euo pipefail
-          tag="$GITHUB_REF_NAME"
+          tag="$RELEASE_TAG"
+          source_commit="$SOURCE_COMMIT"
           assets=(dist/*.whl dist/*.tar.gz dist/SHA256SUMS dist/SBOM.spdx.json dist/RELEASE-BOM-ROW.json)
           tag_commit="$(gh api "repos/$GITHUB_REPOSITORY/commits/$tag" --jq .sha)"
-          if [[ "$tag_commit" != "$GITHUB_SHA" ]]; then
-            echo "Release tag $tag resolves to $tag_commit, not reviewed commit $GITHUB_SHA." >&2
+          if [[ "$tag_commit" != "$source_commit" ]]; then
+            echo "Release tag $tag resolves to $tag_commit, not reviewed commit $source_commit." >&2
             exit 1
           fi
 
@@ -424,7 +509,7 @@ jobs:
               --release-json "$release_json" \
               --version-file VERSION \
               --tag "$tag" \
-              --source-commit "$GITHUB_SHA" \
+              --source-commit "$source_commit" \
               --resolved-tag-commit "$tag_commit"
           }
 
@@ -443,7 +528,6 @@ jobs:
           gh release create "$tag" "${assets[@]}" \
             --repo "$GITHUB_REPOSITORY" \
             --title "$tag" \
-            --generate-notes \
             --notes "Published distributions and release metadata for $tag. See CHANGELOG.md for the reviewed release notes." \
             || create_status=$?
 

{base_cli-0.5.0 → base_cli-0.5.1}/CHANGELOG.md

@@ -15,6 +15,15 @@ and versions are tracked in the repo-root `VERSION` file.
 
 - Include `uv.lock` freshness in the authoritative local validation aggregate (#424).
 
+## [0.5.1] - 2026-10-10
+
+### Changed
+
+- Align the release-facing README and reference-consumer documentation with the
+  published `base-cli` 0.5.x and `base-cli-demo` 0.2.0 lines.
+- Add release preflight, package-description, and PyPI metadata readback gates so
+  published documentation stays bound to the reviewed tag.
+
 ## [0.5.0] - 2026-10-03
 
 ### Added
@@ -401,7 +410,8 @@ the API stability policy and migration guide before upgrading from `0.3.x`.
 - Pinned the build backend to metadata compatible with the bundled publication
   action and made license-file validation portable across setuptools versions.
 
-[Unreleased]: https://github.com/basefoundry/base-cli/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/basefoundry/base-cli/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/basefoundry/base-cli/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/basefoundry/base-cli/compare/v0.4.3...v0.5.0
 [0.4.3]: https://github.com/basefoundry/base-cli/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/basefoundry/base-cli/compare/v0.4.1...v0.4.2

{base_cli-0.5.0 → base_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: base-cli
-Version: 0.5.0
+Version: 0.5.1
 Summary: The production lifecycle layer for Click and Typer Python CLIs
 Author: Base Foundry
 License: Apache-2.0
@@ -66,11 +66,10 @@ Dynamic: license-file
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.3` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.3](https://github.com/basefoundry/base-cli/releases/tag/v0.4.3) |
+| `0.5.1` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.5.1](https://github.com/basefoundry/base-cli/releases/tag/v0.5.1) |
 
-Source release candidate: 0.5.0. Publication is pending the [release checklist](docs/release-0.5.0-checklist.md); PyPI remains the authority for available versions.
-The adopter documentation uses `~=0.5.0` for the release-preparation target;
-use that pin only after the 0.5.0 artifact is published and verified.
+The 0.5.1 release is bound to the immutable `v0.5.1` tag; PyPI remains the authority for available versions.
+The adopter documentation uses `~=0.5.0` for the supported minor-release line.
 
 `base-cli` is the production lifecycle layer for Click and Typer Python CLIs.
 It standardizes context, logging, configuration, cleanup, and machine-readable
@@ -132,9 +131,8 @@ options are documented below.
 
 For a complete maintained example, see the independent
 [`base-cli-demo`](https://github.com/basefoundry/base-cli-demo) reference
-consumer. It is versioned separately (`0.1.0`) and currently tests the released
-`base-cli>=0.4.3,<0.5` line; its 0.5.0 upgrade is tracked in
-[base-cli-demo#47](https://github.com/basefoundry/base-cli-demo/issues/47).
+consumer. It is versioned separately (`0.2.0`) and currently tests the released
+`base-cli>=0.5.0,<0.6` line.
 
 Release builds, TestPyPI rehearsals, and protected PyPI publication are
 documented in [`docs/releasing.md`](https://basefoundry.github.io/base-cli/releasing/). The package exposes

{base_cli-0.5.0 → base_cli-0.5.1}/README.md

@@ -7,11 +7,10 @@
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.3` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.3](https://github.com/basefoundry/base-cli/releases/tag/v0.4.3) |
+| `0.5.1` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.5.1](https://github.com/basefoundry/base-cli/releases/tag/v0.5.1) |
 
-Source release candidate: 0.5.0. Publication is pending the [release checklist](docs/release-0.5.0-checklist.md); PyPI remains the authority for available versions.
-The adopter documentation uses `~=0.5.0` for the release-preparation target;
-use that pin only after the 0.5.0 artifact is published and verified.
+The 0.5.1 release is bound to the immutable `v0.5.1` tag; PyPI remains the authority for available versions.
+The adopter documentation uses `~=0.5.0` for the supported minor-release line.
 
 `base-cli` is the production lifecycle layer for Click and Typer Python CLIs.
 It standardizes context, logging, configuration, cleanup, and machine-readable
@@ -73,9 +72,8 @@ options are documented below.
 
 For a complete maintained example, see the independent
 [`base-cli-demo`](https://github.com/basefoundry/base-cli-demo) reference
-consumer. It is versioned separately (`0.1.0`) and currently tests the released
-`base-cli>=0.4.3,<0.5` line; its 0.5.0 upgrade is tracked in
-[base-cli-demo#47](https://github.com/basefoundry/base-cli-demo/issues/47).
+consumer. It is versioned separately (`0.2.0`) and currently tests the released
+`base-cli>=0.5.0,<0.6` line.
 
 Release builds, TestPyPI rehearsals, and protected PyPI publication are
 documented in [`docs/releasing.md`](https://basefoundry.github.io/base-cli/releasing/). The package exposes

base_cli-0.5.1/VERSION

@@ -0,0 +1 @@
+0.5.1

{base_cli-0.5.0 → base_cli-0.5.1}/docs/adoption-evidence.md

@@ -31,14 +31,12 @@ tests. Base, base-demo, `base-cli-demo`, and other adjacent repositories are
 explicitly excluded from the independent-adopter count.
 
 `base-cli-demo` is a maintained reference and learning consumer, versioned
-independently (`0.1.0`). Its CI demonstrates that a real consumer can exercise
+independently (`0.2.0`). Its CI demonstrates that a real consumer can exercise
 the public facade, lifecycle, output, error, and optional-integration paths for
 the exact framework dependency line it declares; it is not an independent
 adopter result or a substitute for a dated compatibility-fixture artifact.
-While its current released line is `base-cli>=0.4.3,<0.5`, the 0.5.0 upgrade is
-tracked in [base-cli-demo#47](https://github.com/basefoundry/base-cli-demo/issues/47)
-and must be green against the published framework before being described as
-0.5.0 evidence.
+Its current released line is `base-cli>=0.5.0,<0.6`, and its release evidence is
+maintained against the published framework package.
 
 ## Adopter program
 

{base_cli-0.5.0 → base_cli-0.5.1}/docs/index.md

@@ -96,6 +96,6 @@ Continue with the framework guides:
 - [`base-cli-demo`](https://github.com/basefoundry/base-cli-demo) for the
   maintained end-to-end reference consumer, optional integration scenarios,
   and runnable documentation examples. It is versioned independently and its
-  current released dependency line is `base-cli>=0.4.3,<0.5`.
+  current released dependency line is `base-cli>=0.5.0,<0.6`.
 - [Installation and packaging](adopter-readiness.md) for dependency extras,
   distribution checks, and release guidance.

{base_cli-0.5.0 → base_cli-0.5.1}/docs/releasing.md

@@ -125,6 +125,22 @@ the downloaded artifact's digest with `SHA256SUMS`, confirm the SBOM namespace
 contains the expected tag commit, and inspect the attestation's workflow and
 repository identity before installation.
 
+## Release-facing documentation guardrails
+
+The package README is part of the published PyPI metadata. Before any tagged
+build, the Package workflow runs `scripts/validate_release_docs.py` to require a
+single release row whose version and GitHub release link match `VERSION` and to
+reject pre-publication wording. `scripts/validate_package_artifact.py` then
+compares the wheel metadata and sdist `PKG-INFO` description with the tagged
+README, and the release BOM records the README SHA-256.
+
+After a production PyPI upload, the workflow runs
+`scripts/verify_pypi_metadata.py` before creating the GitHub Release. It reads
+the published PyPI JSON metadata, retries propagation delays, and requires the
+published version and long description to match the reviewed source. A mismatch
+blocks release completion; published PyPI bytes remain immutable and require a
+new patch version for correction.
+
 ## Changelog and release notes
 
 `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

{base_cli-0.5.0 → base_cli-0.5.1}/lib/python/base_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: base-cli
-Version: 0.5.0
+Version: 0.5.1
 Summary: The production lifecycle layer for Click and Typer Python CLIs
 Author: Base Foundry
 License: Apache-2.0
@@ -66,11 +66,10 @@ Dynamic: license-file
 
 | Version | License | Install | Release notes |
 | --- | --- | --- | --- |
-| `0.4.3` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.4.3](https://github.com/basefoundry/base-cli/releases/tag/v0.4.3) |
+| `0.5.1` | [Apache-2.0](LICENSE) | `python -m pip install base-cli` | [v0.5.1](https://github.com/basefoundry/base-cli/releases/tag/v0.5.1) |
 
-Source release candidate: 0.5.0. Publication is pending the [release checklist](docs/release-0.5.0-checklist.md); PyPI remains the authority for available versions.
-The adopter documentation uses `~=0.5.0` for the release-preparation target;
-use that pin only after the 0.5.0 artifact is published and verified.
+The 0.5.1 release is bound to the immutable `v0.5.1` tag; PyPI remains the authority for available versions.
+The adopter documentation uses `~=0.5.0` for the supported minor-release line.
 
 `base-cli` is the production lifecycle layer for Click and Typer Python CLIs.
 It standardizes context, logging, configuration, cleanup, and machine-readable
@@ -132,9 +131,8 @@ options are documented below.
 
 For a complete maintained example, see the independent
 [`base-cli-demo`](https://github.com/basefoundry/base-cli-demo) reference
-consumer. It is versioned separately (`0.1.0`) and currently tests the released
-`base-cli>=0.4.3,<0.5` line; its 0.5.0 upgrade is tracked in
-[base-cli-demo#47](https://github.com/basefoundry/base-cli-demo/issues/47).
+consumer. It is versioned separately (`0.2.0`) and currently tests the released
+`base-cli>=0.5.0,<0.6` line.
 
 Release builds, TestPyPI rehearsals, and protected PyPI publication are
 documented in [`docs/releasing.md`](https://basefoundry.github.io/base-cli/releasing/). The package exposes

{base_cli-0.5.0 → base_cli-0.5.1}/lib/python/base_cli.egg-info/SOURCES.txt

@@ -164,10 +164,12 @@ scripts/validate_docs.py
 scripts/validate_examples.py
 scripts/validate_installed_package.py
 scripts/validate_package_artifact.py
+scripts/validate_release_docs.py
 scripts/validate_release_metadata.py
 scripts/validate_release_provenance.py
 scripts/validate_release_ref.py
 scripts/validate_schemas.py
+scripts/verify_pypi_metadata.py
 scripts/verify_release_assets.py
 tests/conftest.py
 tests/test_adversarial_regressions.py
@@ -237,8 +239,10 @@ tests/test_validate_consumer_typing.py
 tests/test_validate_coverage.py
 tests/test_validate_docs.py
 tests/test_validate_package_artifact.py
+tests/test_validate_release_docs.py
 tests/test_validate_release_provenance.py
 tests/test_validate_release_ref.py
 tests/test_validate_schemas.py
+tests/test_verify_pypi_metadata.py
 tests/test_verify_release_assets.py
 tests/test_windows_retention.py

{base_cli-0.5.0 → base_cli-0.5.1}/scripts/generate_release_metadata.py

@@ -136,6 +136,7 @@ def generate(dist: Path, root: Path) -> None:
         "version": version,
         "tag": f"v{version}",
         "commit": revision,
+        "readme_sha256": sha256_file(root / "README.md"),
         "source_mode": "release",
         "api_schema_version": f"base-cli-api@{version}",
         "platforms": ["macos", "ubuntu", "windows"],

{base_cli-0.5.0 → base_cli-0.5.1}/scripts/validate_package_artifact.py

@@ -67,7 +67,31 @@ def expected_package_files() -> set[str]:
     return {path.relative_to(package_root).as_posix() for path in package_root.rglob("*") if path.is_file()}
 
 
-def validate_wheel(path: Path, expected_version: str, package_files: set[str]) -> None:
+def read_expected_readme() -> str:
+    readme_path = Path(__file__).resolve().parents[1] / "README.md"
+    try:
+        return readme_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        fail(f"could not read the source README.md: {exc}")
+
+
+def normalized_text(value: str) -> str:
+    return value.replace("\r\n", "\n").strip()
+
+
+def validate_metadata_description(metadata: email.message.Message, expected_readme: str, artifact_name: str) -> None:
+    payload = metadata.get_payload(decode=True)
+    if not isinstance(payload, bytes):
+        fail(f"{artifact_name} has no text long description")
+    try:
+        description = payload.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        fail(f"{artifact_name} long description is not UTF-8: {exc}")
+    if normalized_text(description) != normalized_text(expected_readme):
+        fail(f"{artifact_name} long description does not match the source README.md")
+
+
+def validate_wheel(path: Path, expected_version: str, package_files: set[str], expected_readme: str) -> None:
     with zipfile.ZipFile(path) as archive:
         names = archive.namelist()
         metadata_names = [name for name in names if name.endswith(".dist-info/METADATA")]
@@ -84,6 +108,7 @@ def validate_wheel(path: Path, expected_version: str, package_files: set[str]) -
         for header, expected in expected_headers.items():
             if metadata.get(header) != expected:
                 fail(f"{path.name} has {header}={metadata.get(header)!r}; expected {expected!r}")
+        validate_metadata_description(metadata, expected_readme, path.name)
 
         dependencies = set(metadata.get_all("Requires-Dist", []))
         for dependency in REQUIRED_DEPENDENCIES:
@@ -131,7 +156,7 @@ def validate_wheel(path: Path, expected_version: str, package_files: set[str]) -
             fail(f"{path.name} contains non-allowlisted archive member {name!r}")
 
 
-def validate_sdist(path: Path, expected_version: str) -> None:
+def validate_sdist(path: Path, expected_version: str, expected_readme: str) -> None:
     with tarfile.open(path, "r:gz") as archive:
         members = archive.getmembers()
         names = [member.name for member in members]
@@ -160,6 +185,22 @@ def validate_sdist(path: Path, expected_version: str) -> None:
         version_text = archive.extractfile(version_members[0])
         if version_text is None or version_text.read().decode().splitlines()[0].strip() != expected_version:
             fail(f"{path.name} VERSION does not match {expected_version}")
+        readme_members = [member for member in members if member.name == f"{root_prefix}README.md"]
+        if len(readme_members) != 1:
+            fail(f"{path.name} must contain exactly one README.md")
+        readme_text = archive.extractfile(readme_members[0])
+        if readme_text is None or normalized_text(readme_text.read().decode("utf-8")) != normalized_text(
+            expected_readme
+        ):
+            fail(f"{path.name} README.md does not match the source README.md")
+        pkg_info_members = [member for member in members if member.name == f"{root_prefix}PKG-INFO"]
+        if len(pkg_info_members) != 1:
+            fail(f"{path.name} must contain exactly one PKG-INFO")
+        pkg_info = archive.extractfile(pkg_info_members[0])
+        if pkg_info is None:
+            fail(f"{path.name} PKG-INFO could not be read")
+        metadata = email.message_from_bytes(pkg_info.read())
+        validate_metadata_description(metadata, expected_readme, path.name)
 
 
 def main() -> None:
@@ -178,8 +219,9 @@ def main() -> None:
     if not wheels[0].name.startswith(expected_stem) or not sdists[0].name.startswith(expected_stem):
         fail(f"artifact filenames do not match version {expected_version}")
 
-    validate_wheel(wheels[0], expected_version, expected_package_files())
-    validate_sdist(sdists[0], expected_version)
+    expected_readme = read_expected_readme()
+    validate_wheel(wheels[0], expected_version, expected_package_files(), expected_readme)
+    validate_sdist(sdists[0], expected_version, expected_readme)
     print(f"Validated {PACKAGE_NAME} {expected_version}: wheel, sdist, metadata, package data, and test boundary.")
 
 

base_cli-0.5.1/scripts/validate_release_docs.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Validate release-facing documentation before building a tagged package."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from pathlib import Path
+
+VERSION_PATTERN = re.compile(r"^[0-9]+(?:\.[0-9]+)+(?:[-+][0-9A-Za-z.-]+)?$")
+RELEASE_ROW_PATTERN = re.compile(
+    r"^\| `(?P<version>[^`]+)` \| \[Apache-2\.0\]\(LICENSE\) \| "
+    r"`python -m pip install base-cli` \| \[v(?P<link_version>[^]]+)\]"
+    r"\(https://github\.com/basefoundry/base-cli/releases/tag/v(?P<tag_version>[^)]+)\) \|$"
+)
+
+
+def validate_release_docs(version_path: Path, readme_path: Path, tag: str = "") -> list[str]:
+    """Return release documentation violations for *version_path* and README."""
+
+    errors: list[str] = []
+    version = version_path.read_text(encoding="utf-8").strip()
+    if not VERSION_PATTERN.fullmatch(version):
+        errors.append(f"VERSION is not a valid release version: {version!r}")
+        return errors
+    expected_tag = f"v{version}"
+    if tag and tag != expected_tag:
+        errors.append(f"release tag {tag!r} does not match VERSION {version!r}")
+
+    readme = readme_path.read_text(encoding="utf-8")
+    rows = [RELEASE_ROW_PATTERN.match(line) for line in readme.splitlines()]
+    matching_rows = [match for match in rows if match is not None]
+    if len(matching_rows) != 1:
+        errors.append("README.md must contain exactly one canonical release row")
+    else:
+        row = matching_rows[0]
+        assert row is not None
+        values = (row.group("version"), row.group("link_version"), row.group("tag_version"))
+        if values != (version, version, version):
+            errors.append(f"README.md release row versions {values!r} do not match {version!r}")
+
+    lowered = readme.casefold()
+    for forbidden in ("source release candidate", "publication is pending"):
+        if forbidden in lowered:
+            errors.append(f"README.md still contains pre-publication wording: {forbidden!r}")
+    return errors
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--version-file", type=Path, default=Path("VERSION"))
+    parser.add_argument("--readme", type=Path, default=Path("README.md"))
+    parser.add_argument("--tag", default=os.environ.get("RELEASE_TAG", ""))
+    args = parser.parse_args()
+    errors = validate_release_docs(args.version_file, args.readme, args.tag)
+    if errors:
+        for error in errors:
+            print(f"release documentation validation failed: {error}")
+        raise SystemExit(1)
+    version = args.version_file.read_text(encoding="utf-8").strip()
+    print(f"Validated release-facing documentation for {args.tag or version}.")
+
+
+if __name__ == "__main__":
+    main()

{base_cli-0.5.0 → base_cli-0.5.1}/scripts/validate_release_metadata.py

@@ -71,6 +71,9 @@ def main() -> None:
         _fail(f"{BOM_ROW_NAME} repository must be basefoundry/base-cli")
     if bom_row.get("version") != version or bom_row.get("tag") != f"v{version}":
         _fail(f"{BOM_ROW_NAME} version/tag does not match the release")
+    readme_path = Path(__file__).resolve().parents[1] / "README.md"
+    if bom_row.get("readme_sha256") != sha256_file(readme_path):
+        _fail(f"{BOM_ROW_NAME} README hash is not bound to the reviewed source")
     commit = bom_row.get("commit")
     if not isinstance(commit, str) or not SHA_RE.fullmatch(commit):
         _fail(f"{BOM_ROW_NAME} commit must be a lowercase full 40-character SHA")