package.yml

name: Package

on:
  pull_request:
    paths:
      - "lib/python/base_cli/**"
      - "pyproject.toml"
      - "VERSION"
      - "README.md"
      - "LICENSE"
      - "MANIFEST.in"
      - "scripts/validate_package_artifact.py"
      - "scripts/validate_installed_package.py"
      - "scripts/validate_examples.py"
      - "scripts/generate_release_metadata.py"
      - "scripts/validate_release_metadata.py"
      - "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"
      - "requirements/release.txt"
      - ".github/workflows/package.yml"
  push:
    branches:
      - main
    tags:
      - "v*"
  workflow_dispatch:
    inputs:
      publish_target:
        description: "Protected publication target"
        required: true
        type: choice
        options:
          - 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

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  PACKAGE_NAME: base-cli

jobs:
  build:
    name: Build and validate distributions
    runs-on: ubuntu-latest
    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
        with:
          python-version: "3.13"

      - name: Read package version
        id: metadata
        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 [[ "$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_EVENT_NAME" == workflow_dispatch && -z "$REQUESTED_RELEASE_TAG" ]]; then
            echo "Manual PyPI publication requires the release_tag input." >&2
            exit 1
          fi

      - name: Validate changelog
        run: python scripts/validate_changelog.py

      - name: Validate tagged release notes
        if: ${{ steps.metadata.outputs.source_ref_type == 'tag' }}
        env:
          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
          mkdir -p dist

      - name: Install build and validation tools
        run: python -m pip install --require-hashes --no-deps -r requirements/release.txt

      - name: Build sdist and wheel
        env:
          # 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 "$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'
          import gzip
          import os
          import tarfile
          from pathlib import Path

          epoch = int(os.environ["SOURCE_DATE_EPOCH"])
          for directory in (Path("dist-a"), Path("dist-b")):
              for path in directory.glob("*.tar.gz"):
                  with tarfile.open(path, "r:gz") as source:
                      members = [(member, source.extractfile(member).read() if member.isfile() else None) for member in source.getmembers()]
                  temporary = path.with_suffix(path.suffix + ".tmp")
                  with temporary.open("wb") as raw:
                      with gzip.GzipFile(filename=path.name, mode="wb", fileobj=raw, mtime=epoch) as compressed:
                          with tarfile.open(fileobj=compressed, mode="w|") as target:
                              for member, payload in sorted(members, key=lambda item: item[0].name):
                                  member.mtime = epoch
                                  member.uid = member.gid = 0
                                  member.uname = member.gname = ""
                                  member.pax_headers = {}
                                  target.addfile(member, None if payload is None else __import__("io").BytesIO(payload))
                  temporary.replace(path)
          PY
          (cd dist-a && sha256sum * | sort) > dist-a.SHA256SUMS
          (cd dist-b && sha256sum * | sort) > dist-b.SHA256SUMS
          diff -u dist-a.SHA256SUMS dist-b.SHA256SUMS
          cp dist-a/* dist/

      - name: Validate artifact contents and metadata
        run: python scripts/validate_package_artifact.py dist

      - name: Validate package indexes
        run: python -m twine check dist/*

      - name: Generate release checksums and SPDX SBOM
        env:
          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: ${{ steps.metadata.outputs.source_commit }}
        run: python scripts/validate_release_metadata.py dist

      - name: Upload reviewed distributions
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: base-cli-dist-${{ github.run_id }}
          path: |
            dist/*.whl
            dist/*.tar.gz
          if-no-files-found: error
          retention-days: 14

      - name: Upload release metadata
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: base-cli-release-metadata-${{ github.run_id }}
          path: |
            dist/SBOM.spdx.json
            dist/SHA256SUMS
            dist/RELEASE-BOM-ROW.json
          if-no-files-found: error
          retention-days: 90

  smoke:
    name: Install smoke test (Python ${{ matrix.python-version }})
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
    steps:
      - name: Check out 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
        with:
          python-version: ${{ matrix.python-version }}

      - name: Download reviewed distributions
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: base-cli-dist-${{ github.run_id }}
          path: dist

      - name: Install wheel and runtime dependencies
        run: python -m pip install dist/base_cli-*.whl

      - name: Verify installed package
        env:
          EXPECTED_VERSION: ${{ needs.build.outputs.version }}
        run: |
          python - <<'PY'
          import base_cli
          import importlib.metadata

          expected = __import__("os").environ["EXPECTED_VERSION"]
          assert base_cli.__version__ == expected, (base_cli.__version__, expected)
          assert importlib.metadata.version("base-cli") == expected
          assert hasattr(base_cli, "App")
          print(f"base-cli {base_cli.__version__} installed successfully")
          PY

      - name: Exercise installed wheel API and lifecycle
        env:
          EXPECTED_VERSION: ${{ needs.build.outputs.version }}
        run: python -I scripts/validate_installed_package.py

      - name: Check installed dependency consistency
        run: python -m pip check

  provenance:
    name: Verify reviewed release provenance
    needs: [build, smoke]
    if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || github.event_name == 'workflow_dispatch' }}
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    steps:
      - name: Check out source
        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"

      - name: Verify release provenance
        env:
          PUBLISH_TARGET: ${{ inputs.publish_target || '' }}
          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
    needs: [build, smoke, provenance]
    if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || github.event_name == 'workflow_dispatch' }}
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment:
      name: ${{ github.event_name == 'push' && 'pypi' || inputs.publish_target }}
      url: ${{ github.event_name == 'push' && 'https://pypi.org/p/base-cli' || 'https://test.pypi.org/p/base-cli' }}
    permissions:
      contents: read
      id-token: write
    steps:
      - name: Download reviewed distributions
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: base-cli-dist-${{ github.run_id }}
          path: dist

      - name: Publish to TestPyPI
        if: ${{ github.event_name == 'workflow_dispatch' && inputs.publish_target == 'testpypi' }}
        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@v1.14.2 # v1.14.2 image tag is required by this composite action
        with:
          packages-dir: dist

  attest:
    name: Attest reviewed release
    needs: [build, smoke, provenance]
    if: ${{ (github.event_name == 'push' && github.ref_type == 'tag') || github.event_name == 'workflow_dispatch' }}
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      id-token: write
      attestations: write
    steps:
      - name: Download reviewed distributions
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: base-cli-dist-${{ github.run_id }}
          path: dist

      - name: Download release metadata
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: base-cli-release-metadata-${{ github.run_id }}
          path: dist

      - name: Attest artifact provenance
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
        with:
          subject-checksums: dist/SHA256SUMS

      - name: Attest SPDX SBOM
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4
        with:
          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, 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:
      contents: write
      attestations: read
    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
        with:
          python-version: "3.13"

      - name: Download reviewed distributions
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: base-cli-dist-${{ github.run_id }}
          path: dist

      - name: Download release metadata
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: base-cli-release-metadata-${{ github.run_id }}
          path: dist

      - 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="$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" != "$source_commit" ]]; then
            echo "Release tag $tag resolves to $tag_commit, not reviewed commit $source_commit." >&2
            exit 1
          fi

          python scripts/validate_release_metadata.py dist
          for asset in dist/*.whl dist/*.tar.gz; do
            gh attestation verify "$asset" \
              --repo "$GITHUB_REPOSITORY" \
              --signer-workflow "github.com/$GITHUB_REPOSITORY/.github/workflows/package.yml" \
              --source-digest "$GITHUB_SHA" \
              --source-ref "$GITHUB_REF"
            gh attestation verify "$asset" \
              --repo "$GITHUB_REPOSITORY" \
              --signer-workflow "github.com/$GITHUB_REPOSITORY/.github/workflows/package.yml" \
              --source-digest "$GITHUB_SHA" \
              --source-ref "$GITHUB_REF" \
              --predicate-type "https://spdx.dev/Document"
          done

          release_tmp="$(mktemp -d "$RUNNER_TEMP/base-cli-release.XXXXXX")"
          trap 'rm -rf "$release_tmp"' EXIT
          release_json="$release_tmp/release.json"
          release_error="$release_tmp/release-error.txt"
          release_response="$release_tmp/release-response.txt"

          read_release_metadata() {
            local retry_404="${1:-false}"
            local attempt=1
            local status_line
            while :; do
              if gh api --include "repos/$GITHUB_REPOSITORY/releases/tags/$tag" \
                >"$release_response" 2>"$release_error"; then
                awk 'BEGIN { body = 0 } { sub(/\r$/, ""); if (body) print; else if ($0 == "") body = 1 }' \
                  "$release_response" >"$release_json"
                return 0
              fi
              status_line="$(sed -n '1s/\r$//p' "$release_response")"
              if [[ "$status_line" =~ ^HTTP/[0-9.]+[[:space:]]404[[:space:]] ]]; then
                if [[ "$retry_404" != true || "$attempt" -ge 5 ]]; then
                  return 1
                fi
                sleep $((attempt * 2))
                attempt=$((attempt + 1))
                continue
              fi
              cat "$release_error" >&2
              return 2
            done
          }

          verify_existing_release() {
            local existing_assets="$release_tmp/existing-assets"
            mkdir -p "$existing_assets"
            gh release download "$tag" --repo "$GITHUB_REPOSITORY" --dir "$existing_assets"
            python scripts/verify_release_assets.py \
              --expected-dir dist \
              --existing-dir "$existing_assets" \
              --release-json "$release_json" \
              --version-file VERSION \
              --tag "$tag" \
              --source-commit "$source_commit" \
              --resolved-tag-commit "$tag_commit"
          }

          if read_release_metadata; then
            verify_existing_release
            echo "Existing release $tag is byte-for-byte identical; leaving the immutable release unchanged."
            exit 0
          else
            release_status=$?
            if [[ "$release_status" -ne 1 ]]; then
              exit "$release_status"
            fi
          fi

          create_status=0
          gh release create "$tag" "${assets[@]}" \
            --repo "$GITHUB_REPOSITORY" \
            --title "$tag" \
            --notes "Published distributions and release metadata for $tag. See CHANGELOG.md for the reviewed release notes." \
            || create_status=$?

          if read_release_metadata true; then
            verify_existing_release
            if [[ "$create_status" -ne 0 ]]; then
              echo "gh release create failed with status $create_status; refusing to hide the publication error." >&2
              exit "$create_status"
            fi
            echo "Verified immutable release $tag after publication."
          else
            release_status=$?
            if [[ "$create_status" -ne 0 ]]; then
              exit "$create_status"
            fi
            echo "Release $tag was created but could not be read back (HTTP 404)." >&2
            exit "$release_status"
          fi