perfect-payload 1.2.0 → 1.2.2-beta.0

package/.github/workflows/publish.yml

@@ -2,22 +2,157 @@ name: Stage npm package
 
 on:
   push:
+    # Beta:
+    # Run for pushes to every branch except main.
     branches:
-      - main
+      - "**"
+      - "!main"
+
+    # Production:
+    # Run only when a version tag is pushed.
+    # Examples: v1.3.0, v1.3.1, v2.0.0
+    tags:
+      - "v*.*.*"
 
 permissions:
   contents: read
   id-token: write
 
 jobs:
-  stage:
+  # ==========================================================
+  # 1. PACKAGE INFO
+  # ==========================================================
+  package-info:
+    name: Package Info
+    runs-on: ubuntu-latest
+
+    outputs:
+      name: ${{ steps.package.outputs.name }}
+      version: ${{ steps.package.outputs.version }}
+      release_type: ${{ steps.package.outputs.release_type }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Read package information
+        id: package
+        shell: bash
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+
+          echo "name=$NAME" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+          if [[ "$GITHUB_REF_TYPE" == "tag" ]]; then
+            RELEASE_TYPE="production"
+          else
+            RELEASE_TYPE="beta"
+          fi
+
+          echo "release_type=$RELEASE_TYPE" >> "$GITHUB_OUTPUT"
+
+          echo "======================================"
+          echo "PACKAGE INFORMATION"
+          echo "======================================"
+          echo "Package:      $NAME"
+          echo "Version:      $VERSION"
+          echo "Release type: $RELEASE_TYPE"
+          echo "Git ref:      $GITHUB_REF_NAME"
+          echo "Git ref type: $GITHUB_REF_TYPE"
+          echo "======================================"
+
+  # ==========================================================
+  # 2. VALIDATE RELEASE
+  # ==========================================================
+  validate-release:
+    name: Validate Release
+    needs: package-info
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Validate branch / tag and version
+        shell: bash
+        run: |
+          VERSION="${{ needs.package-info.outputs.version }}"
+
+          echo "Version:  $VERSION"
+          echo "Ref:      $GITHUB_REF_NAME"
+          echo "Ref type: $GITHUB_REF_TYPE"
+
+          # --------------------------------------------------
+          # PRODUCTION
+          # Must come from a Git tag.
+          #
+          # Tag:             v1.3.0
+          # package version: 1.3.0
+          # --------------------------------------------------
+          if [[ "$GITHUB_REF_TYPE" == "tag" ]]; then
+
+            TAG="$GITHUB_REF_NAME"
+
+            if [[ "$VERSION" == *"-beta"* ]]; then
+              echo "::error::Production releases cannot contain -beta."
+              echo "::error::Current package version: $VERSION"
+              exit 1
+            fi
+
+            EXPECTED_TAG="v$VERSION"
+
+            if [[ "$TAG" != "$EXPECTED_TAG" ]]; then
+              echo "::error::Git tag does not match package.json version."
+              echo "::error::Tag:          $TAG"
+              echo "::error::Expected tag: $EXPECTED_TAG"
+              exit 1
+            fi
+
+            echo "Valid production release."
+            echo "Tag $TAG matches package version $VERSION."
+
+          # --------------------------------------------------
+          # BETA
+          # Any non-main branch.
+          #
+          # Example:
+          # feature/custom-validator
+          # package version: 1.3.0-beta.0
+          # --------------------------------------------------
+          else
+
+            if [[ "$GITHUB_REF_NAME" == "main" ]]; then
+              echo "::error::Production releases from main pushes are disabled."
+              echo "::error::Create a Git tag to release production."
+              exit 1
+            fi
+
+            if [[ "$VERSION" != *"-beta"* ]]; then
+              echo "::error::Non-main branches must contain a beta version."
+              echo "::error::Current version: $VERSION"
+              echo "::error::Expected something like 1.3.0-beta.0"
+              exit 1
+            fi
+
+            echo "Valid beta release."
+            echo "Branch:  $GITHUB_REF_NAME"
+            echo "Version: $VERSION"
+
+          fi
+
+  # ==========================================================
+  # 3. INSTALL DEPENDENCIES
+  # ==========================================================
+  install:
+    name: Install Dependencies
+    needs:
+      - package-info
+      - validate-release
+
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
-        with:
-          fetch-depth: 2
 
       - name: Setup Node.js
         uses: actions/setup-node@v7
@@ -37,88 +172,161 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+  # ==========================================================
+  # 4. RUN TESTS
+  # ==========================================================
+  test:
+    name: Run Tests
+    needs: install
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          package-manager-cache: false
+
+      - name: Install dependencies
+        run: npm ci
+
       - name: Run tests
         run: npm test -- --passWithNoTests
 
-      - name: Get package information
-        id: package
+  # ==========================================================
+  # 5. CHECK NPM VERSION
+  # ==========================================================
+  check-npm:
+    name: Check npm Version
+    needs:
+      - package-info
+      - validate-release
+      - test
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - name: Check whether version already exists
         shell: bash
         run: |
-          NAME=$(node -p "require('./package.json').name")
-          VERSION=$(node -p "require('./package.json').version")
+          NAME="${{ needs.package-info.outputs.name }}"
+          VERSION="${{ needs.package-info.outputs.version }}"
 
-          echo "name=$NAME" >> "$GITHUB_OUTPUT"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Checking npm for $NAME@$VERSION..."
 
-          if [[ "$VERSION" == *"-beta."* ]]; then
-            echo "release_type=beta" >> "$GITHUB_OUTPUT"
-          else
-            echo "release_type=production" >> "$GITHUB_OUTPUT"
+          if npm view "$NAME@$VERSION" version >/dev/null 2>&1; then
+            echo "::error::$NAME@$VERSION is already published."
+            echo "::error::Use a new package version."
+            exit 1
           fi
 
-          echo "Package: $NAME"
-          echo "Version: $VERSION"
+          echo "$NAME@$VERSION is not published."
+          echo "Release is ready to stage."
 
-      - name: Check whether version changed
-        id: version
-        shell: bash
-        run: |
-          CURRENT_VERSION="${{ steps.package.outputs.version }}"
-
-          PREVIOUS_VERSION=$(git show HEAD^:package.json 2>/dev/null | \
-            node -e "
-              let data = '';
-              process.stdin.on('data', chunk => data += chunk);
-              process.stdin.on('end', () => {
-                try {
-                  console.log(JSON.parse(data).version || '');
-                } catch {
-                  console.log('');
-                }
-              });
-            ")
-
-          echo "Previous version: $PREVIOUS_VERSION"
-          echo "Current version:  $CURRENT_VERSION"
-
-          if [[ "$CURRENT_VERSION" == "$PREVIOUS_VERSION" ]]; then
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-            echo "Package version did not change. Nothing to stage."
-          else
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-            echo "New package version detected."
-          fi
+  # ==========================================================
+  # 6. STAGE NPM PACKAGE
+  #
+  # This environment can optionally have a GitHub
+  # Required Reviewer configured.
+  #
+  # npm itself still requires approval + 2FA after staging.
+  # ==========================================================
+  stage-npm:
+    name: Stage npm Package
+    needs:
+      - package-info
+      - check-npm
+
+    runs-on: ubuntu-latest
 
-      - name: Check whether version is already published
-        if: steps.version.outputs.changed == 'true'
-        id: published
+    environment:
+      name: npm-stage
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - name: Setup npm
+        run: npm install --global npm@11.19.1
+
+      - name: Show release information
         shell: bash
         run: |
-          NAME="${{ steps.package.outputs.name }}"
-          VERSION="${{ steps.package.outputs.version }}"
+          echo "======================================"
+          echo "READY TO STAGE"
+          echo "======================================"
+          echo "Package: ${{ needs.package-info.outputs.name }}"
+          echo "Version: ${{ needs.package-info.outputs.version }}"
+          echo "Type:    ${{ needs.package-info.outputs.release_type }}"
+          echo "Ref:     $GITHUB_REF_NAME"
+          echo "======================================"
 
-          if npm view "$NAME@$VERSION" version >/dev/null 2>&1; then
-            echo "exists=true" >> "$GITHUB_OUTPUT"
-            echo "$NAME@$VERSION is already published."
-          else
-            echo "exists=false" >> "$GITHUB_OUTPUT"
-            echo "$NAME@$VERSION is not published."
-          fi
-
-      - name: Stage beta release
+      # ------------------------------------------------------
+      # BETA
+      # Triggered only from non-main branch pushes.
+      # ------------------------------------------------------
+      - name: Stage Beta Package
         if: >
-          steps.version.outputs.changed == 'true' &&
-          steps.published.outputs.exists == 'false' &&
-          steps.package.outputs.release_type == 'beta'
+          github.ref_type == 'branch' &&
+          needs.package-info.outputs.release_type == 'beta'
         run: |
-          echo "Staging beta ${{ steps.package.outputs.version }}"
+          echo "Staging beta package..."
+          echo "${{ needs.package-info.outputs.name }}@${{ needs.package-info.outputs.version }}"
+
           npm stage publish --tag beta
 
-      - name: Stage production release
+      # ------------------------------------------------------
+      # PRODUCTION
+      # Triggered ONLY from Git tags.
+      # ------------------------------------------------------
+      - name: Stage Production Package
         if: >
-          steps.version.outputs.changed == 'true' &&
-          steps.published.outputs.exists == 'false' &&
-          steps.package.outputs.release_type == 'production'
+          github.ref_type == 'tag' &&
+          needs.package-info.outputs.release_type == 'production'
         run: |
-          echo "Staging production ${{ steps.package.outputs.version }}"
+          echo "Staging production package..."
+          echo "${{ needs.package-info.outputs.name }}@${{ needs.package-info.outputs.version }}"
+
           npm stage publish
+
+  # ==========================================================
+  # 7. COMPLETION
+  # ==========================================================
+  complete:
+    name: npm Package Staged
+    needs:
+      - package-info
+      - stage-npm
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Staging completed
+        run: |
+          echo "======================================"
+          echo "NPM STAGING COMPLETED"
+          echo "======================================"
+          echo "Package: ${{ needs.package-info.outputs.name }}"
+          echo "Version: ${{ needs.package-info.outputs.version }}"
+          echo "Type:    ${{ needs.package-info.outputs.release_type }}"
+          echo ""
+          echo "The package has been staged on npm."
+          echo "Review and approve it on npm with 2FA."
+          echo "======================================"