Merge master into production (#minor)

.github/release.yml

@@ -0,0 +1,23 @@
+# Categories for the notes GitHub generates when the deploy workflow creates a release.
+# The labels are set from the conventional-commit prefix of the pull request title by
+# .github/workflows/label-pr.yml.
+changelog:
+  exclude:
+    labels:
+      - internal
+      - release
+  categories:
+    - title: Breaking changes
+      labels:
+        - breaking
+    - title: New features
+      labels:
+        - feature
+    - title: Fixes
+      labels:
+        - fix
+    # Titles without a conventional prefix, typically outside contributions. Retitle the pull
+    # request to move it.
+    - title: Other changes
+      labels:
+        - '*'

.github/workflows/deploy.yml

@@ -1,13 +1,14 @@
 name: Deploy
 
 # About this workflow:
-# It is triggered on push events to branches production and testing. Then it performs a checkout of the current repo
-# and sets up a node environment (v12). Following, it will run `npm ci` to build the package. Next, it will look at your
+# It is triggered on push events to the production branch. Then it performs a checkout of the current repo
+# and sets up a node environment (see .nvmrc). Following, it will run `npm ci` to build the package. Next, it will look at your
 # commit message, if it includes '#patch', '#minor', or '#major' it will bump the package version accordingly.
-# Finally, the `npm publish` command will be run, when on branch testing it will run `npm publish --tag beta` to publish
-# it under the beta flag on npm. Note: if no '#patch', '#minor', or '#major' flag is present in the latest commit
-# AND the package version is not bumped manually the publish step will fail because we can not publish to an existing
-# version.
+# Finally, the `npm publish` command will be run. Note: if no '#patch', '#minor', or '#major' flag is present in the latest
+# commit AND the package version is not bumped manually the publish step will fail because we can not publish to an
+# existing version.
+# Once npm has accepted the version, a GitHub release with generated notes is created.
+# See .github/release.yml for how the notes are grouped.
 
 # GitHub repo configuration:
 # 1. Go to Manage access and add 'Github Actions' team with role: admin.
@@ -16,13 +17,12 @@ name: Deploy
 
 # Note: make sure to commit package-lock.json, this is needed for `npm ci`.
 
-# Defines the trigger for this action, in general you want it to run when pushing to production | testing. For more
+# Defines the trigger for this action, in general you want it to run when pushing to production. For more
 # information see: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows#about-workflow-events)
 on:
   push:
     branches:
       - production
-      - testing
   workflow_dispatch:
     inputs:
       versionBumpType:
@@ -33,10 +33,10 @@ jobs:
   deploy_to_npm:
     name: Version Bump & Deploy to NPM
 
-    # Only run this job if initiator is not the Homey Github Actions Bot to prevent loops and check if if a version bump is provided and current branch is production or testing
+    # Only run this job if initiator is not the Homey Github Actions Bot to prevent loops and check if a version bump is provided and current branch is production
     if: github.actor != 'homey-bot'
-        && (github.ref == 'refs/heads/production' || github.ref == 'refs/heads/testing')
-        && (github.event.inputs.versionBumpType == 'patch' || github.event.inputs.versionBumpType == 'minor' || github.event.inputs.versionBumpType == 'major' || contains(github.event.head_commit.message, '#patch') || contains(github.event.head_commit.message, '#minor') || contains(github.event.head_commit.message, '#major'))
+      && github.ref == 'refs/heads/production'
+      && (github.event.inputs.versionBumpType == 'patch' || github.event.inputs.versionBumpType == 'minor' || github.event.inputs.versionBumpType == 'major' || contains(github.event.head_commit.message, '#patch') || contains(github.event.head_commit.message, '#minor') || contains(github.event.head_commit.message, '#major'))
 
     runs-on: ubuntu-latest
 
@@ -47,13 +47,14 @@ jobs:
       id-token: write
 
     steps:
-
       # Checks out the current repository.
       - name: Checkout git repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           # The token below is only necessary if you want to push the version bump to a protected branch
           token: ${{ secrets.HOMEY_GITHUB_ACTIONS_BOT_PERSONAL_ACCESS_TOKEN }}
+          # Full history and tags, so the release step can find the previous tag.
+          fetch-depth: 0
 
       # Set git config to reflect Homey Github Actions Bot user
       - name: Set up HomeyGithubActionsBot git user
@@ -64,16 +65,32 @@ jobs:
       # Configures a Node.js environment pointed at the public npm registry so
       # `npm publish` uses OIDC against npmjs.org.
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version-file: .nvmrc
+          cache: 'npm'
           registry-url: https://registry.npmjs.org
 
-      # Run `npm ci && npm run build` to re-create your local environment (make sure to commit your - package-lock.json!).
-      - name: Build
+      # OIDC trusted publishing needs npm 11.5.1 or newer. Node 22 bundles npm 10,
+      # and setup-node installs whatever npm ships with the Node version.
+      - name: Upgrade npm for trusted publishing
+        run: npm install -g npm@^11.5.1
+
+      # Run `npm ci` to re-create your local environment (make sure to commit your - package-lock.json!).
+      - name: Install
+        run: npm ci
+
+      # Nothing below this point runs if the package does not lint, format or test
+      # cleanly, so nothing reaches npm that was never checked. Ahead of the docs build,
+      # which is the slowest step here.
+      - name: Validate
         run: |
-          npm ci
-          npm run build
+          npm run lint
+          npm run format:check
+          npm test
+
+      - name: Build
+        run: npm run build
 
       - name: Version bump patch
         if: github.event.inputs.versionBumpType == 'patch' || contains(github.event.head_commit.message, '#patch') && !contains(github.event.head_commit.message, '#minor') && !contains(github.event.head_commit.message, '#major')
@@ -96,20 +113,33 @@ jobs:
           git pull
           git push --follow-tags
 
-      # Publish when this action is running on branch production.
       # No NPM_AUTH_TOKEN: auth is brokered via OIDC against the npm
       # Trusted Publisher configured on the package on npmjs.com.
       - name: Publish
-        if: github.ref == 'refs/heads/production'
+        run: npm publish --provenance
+
+      # After the publish, and starting from the previous release rather than the previous tag,
+      # because a publish that fails after the version bump leaves a tag without an npm version
+      # behind (v2.7.0, v3.1.0). Until the first release exists, the start is the last version npm
+      # actually has, for the same reason. If this step fails, create the release by hand: a rerun
+      # would bump again.
+      - name: Create GitHub release
+        # Explicit, because only then does Actions add pipefail: without it a failing gh api still
+        # feeds the Node filter an empty input, and an empty release gets published.
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.HOMEY_GITHUB_ACTIONS_BOT_PERSONAL_ACCESS_TOKEN }}
         run: |
-          npm publish --provenance
           VERSION="$(node -p "require('./package.json').version")"
-          echo package_version=${VERSION} >> $GITHUB_ENV
-
-      # Publish to beta when this action is running on branch testing.
-      - name: Publish to beta
-        if: github.ref == 'refs/heads/testing'
-        run: |
-          npm publish --provenance --tag beta
-          VERSION="$(node -p "require('./package.json').version")@beta"
-          echo package_version=${VERSION} >> $GITHUB_ENV
+          TAG="v$VERSION"
+          if ! PREVIOUS_TAG="$(gh release view --json tagName -q .tagName)"; then
+            PREVIOUS_TAG="v$(npm view "zigbee-clusters@<$VERSION" version --json \
+              | node -p "[].concat(JSON.parse(require('node:fs').readFileSync(0, 'utf8'))).at(-1)")"
+          fi
+          # The notes list each pull request title as is. Drop its conventional-commit prefix, which the
+          # category heading above it already says.
+          gh api "repos/$GITHUB_REPOSITORY/releases/generate-notes" \
+            -f tag_name="$TAG" -f previous_tag_name="$PREVIOUS_TAG" --jq .body \
+            | node -e "process.stdout.write(require('node:fs').readFileSync(0, 'utf8').replace(/^\* \w+(\([^)]*\))?!?: (.)/gm, (_, _scope, first) => '* ' + first.toUpperCase()))" \
+            > release-notes.md
+          gh release create "$TAG" --verify-tag --title "$TAG" --notes-file release-notes.md

.github/workflows/docs.yml

@@ -15,34 +15,33 @@ name: Deploy Documentation To GitHub Pages
 
 # Note: make sure to commit package-lock.json, this is needed for `npm ci`.
 
-# Note: add `.github` to .npmignore
-
 on:
   push:
-    branches: [ production ]
+    branches: [production]
   workflow_dispatch:
 
 jobs:
   deploy:
     name: Build & Deploy to GitHub Pages
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version-file: .nvmrc
-
-      # Build
-    - name: Build
-      run: |
-        npm ci
-        npm run build
-
-    # Deploy
-    - name: Deploy To GitHub Pages
-      uses: peaceiris/actions-gh-pages@v3.8.0
-      with:
-        personal_token: ${{ secrets.HOMEY_GITHUB_ACTIONS_BOT_PERSONAL_ACCESS_TOKEN }}
-        publish_dir: ./build
+      - uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          cache: 'npm'
+
+        # Build
+      - name: Build
+        run: |
+          npm ci
+          npm run build
+
+      # Deploy
+      - name: Deploy To GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          personal_token: ${{ secrets.HOMEY_GITHUB_ACTIONS_BOT_PERSONAL_ACCESS_TOKEN }}
+          publish_dir: ./build

.github/workflows/generate-types.yml

@@ -4,14 +4,13 @@ on:
   push:
     branches-ignore:
       - production
-      - testing
     paths:
-      - "lib/clusters/**/*.js"
-      - "scripts/generate-types.mts"
-      - "scripts/template.d.ts.txt"
-      - "index.js"
-      - "lib/Cluster.js"
-      - "lib/constants.js"
+      - 'lib/clusters/**/*.js'
+      - 'scripts/generate-types.mts'
+      - 'scripts/template.d.ts.txt'
+      - 'index.js'
+      - 'lib/Cluster.js'
+      - 'lib/constants.js'
   workflow_dispatch:
 
 jobs:
@@ -23,16 +22,16 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           ref: ${{ github.ref_name }}
           token: ${{ secrets.HOMEY_GITHUB_ACTIONS_BOT_PERSONAL_ACCESS_TOKEN }}
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version-file: .nvmrc
-          cache: "npm"
+          cache: 'npm'
 
       - name: Install dependencies
         run: npm ci

.github/workflows/label-pr.yml

@@ -0,0 +1,67 @@
+name: Label pull request
+
+# Labels each pull request from the conventional-commit prefix of its title, so the release
+# notes can sort it (see .github/release.yml). Re-runs when the title or base branch is edited.
+# The five labels below follow the title alone: to move a pull request, retitle it.
+#
+# pull_request_target so pull requests from forks get a token that can label. This is safe
+# because the job never checks out or runs code from the pull request.
+on:
+  pull_request_target:
+    types: [opened, edited, reopened]
+
+permissions:
+  pull-requests: write
+
+# One run at a time per pull request, so two quick edits cannot each add a label the other
+# should have removed.
+concurrency:
+  group: label-pr-${{ github.event.pull_request.number }}
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v9
+        with:
+          script: |
+            const MANAGED_LABELS = ['breaking', 'feature', 'fix', 'internal', 'release'];
+            const INTERNAL_TYPES = ['build', 'chore', 'ci', 'docs', 'refactor', 'style', 'test'];
+
+            function labelFor(title, baseRef) {
+              if (baseRef === 'production') return 'release';
+              const match = /^(\w+)(?:\([^)]*\))?(!)?:/.exec(title);
+              if (!match) return null;
+              const [, type, breaking] = match;
+              if (breaking) return 'breaking';
+              if (type === 'feat') return 'feature';
+              if (type === 'fix' || type === 'perf') return 'fix';
+              if (INTERNAL_TYPES.includes(type)) return 'internal';
+              return null;
+            }
+
+            const { action, changes = {} } = context.payload;
+            // The label depends on the title and the base branch; other edits change nothing.
+            if (action === 'edited' && !changes.title && !changes.base) return;
+
+            // The payload is a snapshot from when the event fired. Read the pull request as it is
+            // now, so labels an earlier run added are seen and the latest title wins.
+            const { data: pullRequest } = await github.rest.pulls.get({
+              ...context.repo,
+              pull_number: context.payload.pull_request.number,
+            });
+
+            // The managed labels are a function of the current title and base only, so whichever
+            // runs happen to execute, the last one leaves them right. No prefix means none of them.
+            const wanted = labelFor(pullRequest.title, pullRequest.base.ref);
+            const current = pullRequest.labels.map(label => label.name);
+            const issue = { ...context.repo, issue_number: pullRequest.number };
+
+            for (const name of current) {
+              if (MANAGED_LABELS.includes(name) && name !== wanted) {
+                await github.rest.issues.removeLabel({ ...issue, name });
+              }
+            }
+            if (wanted && !current.includes(wanted)) {
+              await github.rest.issues.addLabels({ ...issue, labels: [wanted] });
+            }

.github/workflows/lint.yml

@@ -20,17 +20,19 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-
       # Checks out the current repository.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       # Configures a Node.js environment.
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version-file: .nvmrc
+          cache: 'npm'
 
       # Run `npm ci` to re-create your local environment (make sure to commit your package-lock.json!).
       # Finally run `npm run lint` (make sure you have defined a lint command in package.json e.g. "lint": "eslint .").
       - run: npm ci
 
       - run: npm run lint
+
+      - run: npm run format:check

.github/workflows/test.yml

@@ -22,12 +22,13 @@ jobs:
 
     steps:
       # Checks out the current repository.
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       # Configures a Node.js environment.
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version-file: .nvmrc
+          cache: 'npm'
 
       # Run `npm ci` to re-create your local environment (make sure to commit your package-lock.json!).
       # Finally run `npm test` (make sure you have defined a proper test command in package.json).

.npmrc

@@ -0,0 +1,3 @@
+# Both @athombv packages used here are published to npmjs.org. Without this, a
+# machine that points the @athombv scope at GitHub Packages fails to install them.
+@athombv:registry=https://registry.npmjs.org/

.nvmrc

@@ -1 +1 @@
-24
+22