fix(release): harden toolkit/react release asset staging (#198)

* fix(release): stage assets before publishing

* fix(release): harden staged asset validation

Author: diogo-filipe-costa

.github/workflows/release-contract.yml

@@ -10,9 +10,11 @@ on:
       - 'docs/**'
       - 'package.json'
       - 'pnpm-lock.yaml'
+      - 'packages/toolkit/gulpfile.js'
       - 'packages/toolkit/package.json'
       - 'packages/react-components/package.json'
       - 'packages/react-components/README.md'
+      - 'packages/react-components/scripts/**'
       - 'scripts/release/**'
 
 jobs:
@@ -38,5 +40,5 @@ jobs:
       - name: Validate docs and release templates
         run: pnpm docs:release-contract
 
-      - name: Smoke test current release artifacts
+      - name: Prepare and smoke test current release artifacts
         run: pnpm smoke:release-artifacts

.github/workflows/release.yml

@@ -41,57 +41,53 @@ jobs:
       - name: Validate release contract docs
         run: pnpm docs:release-contract
 
-      - name: Determine package and version
+      - name: Determine package from tag
         id: package_info
         run: |
           TAG=${GITHUB_REF#refs/tags/}
           if [[ $TAG == react-v* ]]; then
             echo "PACKAGE=react-components" >> $GITHUB_OUTPUT
-            echo "PACKAGE_SCOPE=@ourfuturehealth/react-components" >> $GITHUB_OUTPUT
             echo "PACKAGE_DIR=packages/react-components" >> $GITHUB_OUTPUT
-            echo "VERSION=${TAG#react-v}" >> $GITHUB_OUTPUT
           elif [[ $TAG == toolkit-v* ]]; then
             echo "PACKAGE=toolkit" >> $GITHUB_OUTPUT
-            echo "PACKAGE_SCOPE=@ourfuturehealth/toolkit" >> $GITHUB_OUTPUT
             echo "PACKAGE_DIR=packages/toolkit" >> $GITHUB_OUTPUT
-            echo "VERSION=${TAG#toolkit-v}" >> $GITHUB_OUTPUT
           else
             # Assume v* tags are toolkit (backward compatibility)
             echo "PACKAGE=toolkit" >> $GITHUB_OUTPUT
-            echo "PACKAGE_SCOPE=@ourfuturehealth/toolkit" >> $GITHUB_OUTPUT
             echo "PACKAGE_DIR=packages/toolkit" >> $GITHUB_OUTPUT
-            echo "VERSION=${TAG#v}" >> $GITHUB_OUTPUT
           fi
 
-      - name: Build release artifacts
+      - name: Prepare release assets
+        id: release_assets
         run: |
-          if [ "${{ steps.package_info.outputs.PACKAGE }}" == "toolkit" ]; then
-            pnpm --filter=@ourfuturehealth/toolkit run zip
+          ./scripts/release/prepare-release-artifacts.sh \
+            "${{ steps.package_info.outputs.PACKAGE }}" \
+            --stage-dir "${RUNNER_TEMP}/release-assets-${{ github.run_id }}-${{ github.run_attempt }}-${{ steps.package_info.outputs.PACKAGE }}" \
+            --github-output "${GITHUB_OUTPUT}"
+
+      - name: Validate tag version matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          if [[ "${TAG}" == react-v* ]]; then
+            EXPECTED_VERSION="${TAG#react-v}"
+          elif [[ "${TAG}" == toolkit-v* ]]; then
+            EXPECTED_VERSION="${TAG#toolkit-v}"
           else
-            pnpm --filter=@ourfuturehealth/react-components run build
+            EXPECTED_VERSION="${TAG#v}"
           fi
 
-      - name: Pack release tarball
-        id: tarball
-        run: |
-          TARBALL_NAME=$(npm pack "./${{ steps.package_info.outputs.PACKAGE_DIR }}" --ignore-scripts | tail -n 1)
-          echo "ASSET_NAME=${TARBALL_NAME}" >> $GITHUB_OUTPUT
-          echo "ASSET_PATH=${GITHUB_WORKSPACE}/${TARBALL_NAME}" >> $GITHUB_OUTPUT
+          ACTUAL_VERSION="${{ steps.release_assets.outputs.VERSION }}"
 
-      - name: Resolve toolkit asset details
-        if: steps.package_info.outputs.PACKAGE == 'toolkit'
-        id: toolkit_asset
-        run: |
-          ASSET_PATH=$(ls -1 ./packages/toolkit/dist/ofh-design-system-toolkit-*.zip | head -n 1)
-          ASSET_NAME=$(basename "$ASSET_PATH")
-          echo "ASSET_PATH=$ASSET_PATH" >> $GITHUB_OUTPUT
-          echo "ASSET_NAME=$ASSET_NAME" >> $GITHUB_OUTPUT
+          if [[ "${EXPECTED_VERSION}" != "${ACTUAL_VERSION}" ]]; then
+            echo "Tag version '${EXPECTED_VERSION}' does not match package version '${ACTUAL_VERSION}' for tag '${TAG}'." >&2
+            exit 1
+          fi
 
       - name: Smoke test release tarball
         run: |
           ./scripts/release/smoke-package-tarball.sh \
             --package-dir "${{ github.workspace }}/${{ steps.package_info.outputs.PACKAGE_DIR }}" \
-            --tarball "${{ steps.tarball.outputs.ASSET_PATH }}" \
+            --tarball "${{ steps.release_assets.outputs.TARBALL_PATH }}" \
             --managers 'yarn,npm,pnpm'
 
       - name: Render release notes
@@ -102,15 +98,15 @@ jobs:
             ./scripts/release/render-release-notes.sh \
               --package "${{ steps.package_info.outputs.PACKAGE }}" \
               --tag "${GITHUB_REF_NAME}" \
-              --version "${{ steps.package_info.outputs.VERSION }}" \
-              --tarball "${{ steps.tarball.outputs.ASSET_NAME }}" \
-              --zip "${{ steps.toolkit_asset.outputs.ASSET_NAME }}" > "${NOTES_PATH}"
+              --version "${{ steps.release_assets.outputs.VERSION }}" \
+              --tarball "${{ steps.release_assets.outputs.TARBALL_NAME }}" \
+              --zip "${{ steps.release_assets.outputs.ZIP_NAME }}" > "${NOTES_PATH}"
           else
             ./scripts/release/render-release-notes.sh \
               --package "${{ steps.package_info.outputs.PACKAGE }}" \
               --tag "${GITHUB_REF_NAME}" \
-              --version "${{ steps.package_info.outputs.VERSION }}" \
-              --tarball "${{ steps.tarball.outputs.ASSET_NAME }}" > "${NOTES_PATH}"
+              --version "${{ steps.release_assets.outputs.VERSION }}" \
+              --tarball "${{ steps.release_assets.outputs.TARBALL_NAME }}" > "${NOTES_PATH}"
           fi
           echo "NOTES_PATH=${NOTES_PATH}" >> $GITHUB_OUTPUT
 
@@ -136,14 +132,14 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          gh release upload "${GITHUB_REF_NAME}" "${{ steps.toolkit_asset.outputs.ASSET_PATH }}" \
+          gh release upload "${GITHUB_REF_NAME}" "${{ steps.release_assets.outputs.ZIP_PATH }}" \
             --clobber \
             --repo "${GITHUB_REPOSITORY}"
 
       - name: Upload package tarball asset
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          gh release upload "${GITHUB_REF_NAME}" "${{ steps.tarball.outputs.ASSET_PATH }}" \
+          gh release upload "${GITHUB_REF_NAME}" "${{ steps.release_assets.outputs.TARBALL_PATH }}" \
             --clobber \
             --repo "${GITHUB_REPOSITORY}"

docs/release-process.md

@@ -74,12 +74,11 @@ When a release tag is pushed, [.github/workflows/release.yml](../.github/workflo
 1. installs dependencies with pnpm
 2. runs linting and tests
 3. validates the release-contract docs
-4. builds the package being released
-5. packs the package with `npm pack --ignore-scripts`
-6. smoke-tests the tarball with Yarn 1, npm, and pnpm
-7. renders release notes with the tarball install URL
-8. creates or updates the GitHub release
-9. uploads release assets
+4. prepares the package release assets in a dedicated staging directory outside the package tree
+5. smoke-tests the tarball with Yarn 1, npm, and pnpm
+6. renders release notes with the tarball install URL
+7. creates or updates the GitHub release
+8. uploads release assets
 
 Toolkit releases upload:
 
@@ -145,6 +144,7 @@ pnpm smoke:release-artifacts
 ```
 
 This validates the public docs and then tests the current branch tarballs with Yarn 1, npm, and pnpm.
+It uses the same staged-asset preparation path as the tag-driven release workflow, so PR validation exercises the same artifact handoff that production releases rely on.
 
 For local iteration you can scope this wrapper to one package and one or more package managers:
 
@@ -153,6 +153,17 @@ For local iteration you can scope this wrapper to one package and one or more pa
 ./scripts/release/smoke-current-release-artifacts.sh react-components --managers npm,pnpm
 ```
 
+### Prepare release assets directly
+
+If you need to inspect the exact staged assets before tagging:
+
+```bash
+./scripts/release/prepare-release-artifacts.sh toolkit
+./scripts/release/prepare-release-artifacts.sh react-components
+```
+
+The script prints the package, version, and staged asset paths. Toolkit releases must stage both the versioned `.zip` and the package tarball before the workflow can create or update the GitHub release.
+
 ### Test unreleased changes locally in another consumer
 
 Toolkit:
@@ -184,6 +195,18 @@ Common causes:
 - smoke test failures for the tarball install contract
 - stale docs or release templates that still mention the old git-subdirectory syntax
 
+### Why release assets are staged outside the package tree
+
+The release workflow deliberately copies built assets into a dedicated staging directory before it runs `npm pack`.
+
+This is intentional. CI previously showed the toolkit `createZip` step completing successfully, then failed later when the workflow tried to rediscover the versioned zip from `packages/toolkit/dist/`. Local reproduction did not show the same disappearance, and the local/CI npm versions differed, so the release flow now treats the package working tree as unstable across later packaging steps.
+
+The staged asset copy is the source of truth for:
+
+- tarball smoke testing
+- toolkit compiled-file uploads
+- release note asset references
+
 ### Consumer installation failed
 
 Check that: