DSE-415 :: Fix release artifacts for external consumers (#194)

* fix(release): publish tested release tarballs

* feat(example-react-consumer-app): model external tarball consumption

* fix(release): avoid validator self-match

* fix(pr): address review feedback

Author: diogo-filipe-costa

.github/workflows/release-contract.yml

@@ -0,0 +1,42 @@
+name: Release contract
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/release.yml'
+      - '.github/workflows/release-contract.yml'
+      - 'README.md'
+      - 'UPGRADING.md'
+      - 'docs/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'packages/toolkit/package.json'
+      - 'packages/react-components/package.json'
+      - 'packages/react-components/README.md'
+      - 'scripts/release/**'
+
+jobs:
+  validate:
+    name: Validate release contract
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22.x'
+
+      - name: Enable Corepack and pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.29.2 --activate
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Validate docs and release templates
+        run: pnpm docs:release-contract
+
+      - name: Smoke test current release artifacts
+        run: pnpm smoke:release-artifacts

.github/workflows/release.yml

@@ -38,33 +38,46 @@ jobs:
       - name: Run tests
         run: pnpm test
 
+      - name: Validate release contract docs
+        run: pnpm docs:release-contract
+
       - name: Determine package and version
         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
-            echo "BUILD_CMD=build" >> $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
-            echo "BUILD_CMD=zip" >> $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
-            echo "BUILD_CMD=zip" >> $GITHUB_OUTPUT
           fi
 
-      - name: Build release artifact
+      - name: Build release artifacts
         run: |
           if [ "${{ steps.package_info.outputs.PACKAGE }}" == "toolkit" ]; then
             pnpm --filter=@ourfuturehealth/toolkit run zip
           else
             pnpm --filter=@ourfuturehealth/react-components run build
           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
+
       - name: Resolve toolkit asset details
         if: steps.package_info.outputs.PACKAGE == 'toolkit'
         id: toolkit_asset
@@ -74,30 +87,48 @@ jobs:
           echo "ASSET_PATH=$ASSET_PATH" >> $GITHUB_OUTPUT
           echo "ASSET_NAME=$ASSET_NAME" >> $GITHUB_OUTPUT
 
+      - 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 }}" \
+            --managers 'yarn,npm,pnpm'
+
+      - name: Render release notes
+        id: release_notes
+        run: |
+          NOTES_PATH="${GITHUB_WORKSPACE}/release-notes.md"
+          if [ "${{ steps.package_info.outputs.PACKAGE }}" == "toolkit" ]; then
+            ./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}"
+          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}"
+          fi
+          echo "NOTES_PATH=${NOTES_PATH}" >> $GITHUB_OUTPUT
+
       - name: Create or update release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           TAG="${GITHUB_REF_NAME}"
-          RELEASE_BODY=$(cat <<EOF
-          Release of **${{ steps.package_info.outputs.PACKAGE }}** version ${{ steps.package_info.outputs.VERSION }}
-
-          ## Installation
-
-          \`\`\`json
-          {
-            "dependencies": {
-              "@ourfuturehealth/${{ steps.package_info.outputs.PACKAGE }}": "github:ourfuturehealth/design-system-toolkit#${{ github.ref_name }}:packages/${{ steps.package_info.outputs.PACKAGE }}"
-            }
-          }
-          \`\`\`
-          EOF
-          )
-
-          if gh release view "$TAG" >/dev/null 2>&1; then
-            gh release edit "$TAG" --title "$TAG" --notes "$RELEASE_BODY"
+          if gh release view "$TAG" --repo "${GITHUB_REPOSITORY}" >/dev/null 2>&1; then
+            gh release edit "$TAG" \
+              --repo "${GITHUB_REPOSITORY}" \
+              --title "$TAG" \
+              --notes-file "${{ steps.release_notes.outputs.NOTES_PATH }}"
           else
-            gh release create "$TAG" --title "$TAG" --notes "$RELEASE_BODY"
+            gh release create "$TAG" \
+              --repo "${GITHUB_REPOSITORY}" \
+              --title "$TAG" \
+              --notes-file "${{ steps.release_notes.outputs.NOTES_PATH }}"
           fi
 
       - name: Upload toolkit zip asset
@@ -108,3 +139,11 @@ jobs:
           gh release upload "${GITHUB_REF_NAME}" "${{ steps.toolkit_asset.outputs.ASSET_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 }}" \
+            --clobber \
+            --repo "${GITHUB_REPOSITORY}"

.gitignore

@@ -24,6 +24,7 @@ bower_components
 # Lock files (using pnpm, so ignore npm/yarn lock files)
 package-lock.json
 yarn.lock
+!packages/example-react-consumer-app/package-lock.json
 
 # Editors
 .idea

README.md

@@ -13,7 +13,7 @@ This repository is organized as a monorepo containing:
 
 - **Core toolkit** - SCSS/CSS design system and vanilla JavaScript components
 - **React components** (`packages/react-components/`) - React implementation of the design system
-- **Example consumer app** (`packages/example-react-consumer-app/`) - Demonstration of consuming React components
+- **Example consumer app** (`packages/example-react-consumer-app/`) - Standalone in-repo example of consuming the published React tarball contract
 
 ## Prerequisites
 
@@ -53,7 +53,7 @@ pnpm install
 # Development workflows
 pnpm storybook                  # React component documentation (Storybook)
 pnpm dev:react-components       # React component library development
-pnpm dev:react-consumer         # Example consumer app with library watch
+pnpm dev:react-consumer         # Example consumer app dev server (run npm install in that directory first)
 pnpm dev:site                   # Documentation site development
 pnpm dev:toolkit                # Core toolkit development
 pnpm dev                        # Run all dev servers concurrently