ci: harden distribution smoke workflow

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ulises-jeremias

.github/workflows/smoke-distribution.yml

@@ -15,6 +15,10 @@ on:
 permissions:
   contents: read
 
+env:
+  PACKAGE_NAME: create-awesome-python-app
+  DOCKER_IMAGE: ulisesjeremias/create-awesome-python-app
+
 concurrency:
   group: smoke-distribution
   cancel-in-progress: true
@@ -28,27 +32,38 @@ jobs:
       - name: Smoke uvx
         run: |
           set -euo pipefail
-          uvx create-awesome-python-app@latest --version
-          uvx create-awesome-python-app@latest --help | head -5
+          VERSION="$(uvx "$PACKAGE_NAME@latest" --version 2>&1)"
+          echo "uvx version: $VERSION"
+          echo "$VERSION" | grep -qE '[0-9]+\.[0-9]+\.[0-9]+' || {
+            echo "::error::Unexpected uvx version output: $VERSION"
+            exit 1
+          }
+
+          uvx "$PACKAGE_NAME@latest" --help > /tmp/cpa-help.txt
+          test -s /tmp/cpa-help.txt
+          python3 -c "from pathlib import Path; print('\n'.join(Path('/tmp/cpa-help.txt').read_text().splitlines()[:5]))"
 
   docker:
     name: Docker Hub
     runs-on: ubuntu-latest
     steps:
       - name: Pull image
-        run: docker pull ulisesjeremias/create-awesome-python-app:latest
+        run: docker pull "$DOCKER_IMAGE:latest"
 
       - name: Verify --version
         run: |
           VERSION=$(docker run --rm ulisesjeremias/create-awesome-python-app:latest --version 2>&1)
           echo "docker version: $VERSION"
-          echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$' || {
+          echo "$VERSION" | grep -qE '[0-9]+\.[0-9]+\.[0-9]+' || {
             echo "::error::Unexpected version output: $VERSION"
             exit 1
           }
 
       - name: Verify --help
-        run: docker run --rm ulisesjeremias/create-awesome-python-app:latest --help | head -5
+        run: |
+          docker run --rm "$DOCKER_IMAGE:latest" --help > /tmp/cpa-help.txt
+          test -s /tmp/cpa-help.txt
+          python3 -c "from pathlib import Path; print('\n'.join(Path('/tmp/cpa-help.txt').read_text().splitlines()[:5]))"
 
   homebrew:
     name: Homebrew (Create-Python-App/tap)
@@ -64,13 +79,16 @@ jobs:
         run: |
           VERSION=$(create-awesome-python-app --version 2>&1)
           echo "homebrew version: $VERSION"
-          echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$' || {
+          echo "$VERSION" | grep -qE '[0-9]+\.[0-9]+\.[0-9]+' || {
             echo "::error::Unexpected version output: $VERSION"
             exit 1
           }
 
       - name: Verify --help
-        run: create-awesome-python-app --help | head -5
+        run: |
+          create-awesome-python-app --help > /tmp/cpa-help.txt
+          test -s /tmp/cpa-help.txt
+          python3 -c "from pathlib import Path; print('\n'.join(Path('/tmp/cpa-help.txt').read_text().splitlines()[:5]))"
 
   aur:
     name: AUR (archlinux container)
@@ -105,11 +123,13 @@ jobs:
           su builder -c "
             VERSION=\$(create-awesome-python-app --version 2>&1)
             echo \"aur version: \$VERSION\"
-            echo \"\$VERSION\" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+\$' || exit 1
+            echo \"\$VERSION\" | grep -qE '[0-9]+\.[0-9]+\.[0-9]+' || exit 1
           "
 
       - name: Verify --help
-        run: su builder -c "create-awesome-python-app --help | head -5"
+        run: |
+          su builder -c "create-awesome-python-app --help > /tmp/cpa-help.txt && test -s /tmp/cpa-help.txt"
+          python3 -c "from pathlib import Path; print('\n'.join(Path('/tmp/cpa-help.txt').read_text().splitlines()[:5]))"
 
   versions:
     name: Cross-check published versions
@@ -127,7 +147,9 @@ jobs:
           )
 
           DOCKER=$(
-            docker run --rm ulisesjeremias/create-awesome-python-app:latest --version 2>&1 \
+            docker run --rm "$DOCKER_IMAGE:latest" --version 2>&1 \
+              | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' \
+              | head -1 \
               || echo "unavailable"
           )
 
@@ -152,6 +174,17 @@ jobs:
           echo "  homebrew: $HOMEBREW"
           echo "  aur:      $AUR"
 
+          {
+            echo "## Distribution smoke versions"
+            echo
+            echo "| Channel | Version |"
+            echo "|---------|---------|"
+            echo "| PyPI | $PYPI |"
+            echo "| Docker | $DOCKER |"
+            echo "| Homebrew | $HOMEBREW |"
+            echo "| AUR | $AUR |"
+          } >> "$GITHUB_STEP_SUMMARY"
+
           for CHANNEL_VER in "$DOCKER" "$HOMEBREW"; do
             if [ "$CHANNEL_VER" != "unavailable" ] && [ "$CHANNEL_VER" != "$PYPI" ]; then
               echo "::warning::Version mismatch vs pypi=$PYPI: $CHANNEL_VER"

docs/DISTRIBUTION_SETUP.md

@@ -127,6 +127,21 @@ brew install create-awesome-python-app && create-awesome-python-app --version
 yay -S create-awesome-python-app && create-awesome-python-app --version
 ```
 
+## Scheduled distribution smoke
+
+`Distribution smoke tests` runs daily and can also be dispatched manually:
+
+```bash
+gh workflow run "Distribution smoke tests" --repo Create-Python-App/create-python-app
+gh run list --workflow smoke-distribution.yml --repo Create-Python-App/create-python-app --limit 5
+```
+
+Before closing distribution issues, link a green run that covers all published
+channels: PyPI via `uvx`, Docker Hub, Homebrew, AUR, and the cross-channel
+version summary. Channel version mismatches are warnings when a downstream
+package can legitimately lag PyPI, but install/help/version failures must stay
+red.
+
 ## After secrets are in place
 
 Every subsequent release only requires tagging `create-awesome-python-app@X.Y.Z`.