publish-npm.yaml

# Publish to npm.
# Fires when a GitHub Release is published. Release Drafter keeps a rolling
# draft populated from merged PRs (see draft-release.yaml); promoting that
# draft to a real release triggers this workflow.
#
# On release: sets package.json to the release tag version, publishes to npm,
# then commits the version bump back to the default branch.
#
# Can also be triggered manually via workflow_dispatch to publish a prerelease
# (e.g. alpha, beta, rc). The published version is {package.json version}-{preid}
# under a matching npm dist-tag so it does not land on `latest`. No commit is
# made for prereleases.
#
# Required secret: NPM_TOKEN — an Automation token from npmjs.com. Create one
# at https://www.npmjs.com/settings/<user>/tokens (type: Automation, scope:
# this package). Add it under Settings → Secrets and variables → Actions.
name: Publish to npm

on:
  release:
    # `published` covers both "Publish release" and "Auto-publish on tag";
    # `created` would also fire for drafts, which we don't want.
    types: [published]

  workflow_dispatch:
    inputs:
      preid:
        description: 'Prerelease identifier, optionally with iteration (e.g. beta, rc.1, alpha.2). Published as {version}-{preid} under a dist-tag of the base name.'
        required: true
        type: string

# id-token: write is required for the npm provenance attestation below.
# contents: write is required to commit the version bump back on release.
permissions:
  contents: write
  id-token: write

jobs:
  publish:
    name: Publish package to npm
    runs-on: ubuntu-latest
    steps:
      # actions/checkout — https://github.com/actions/checkout
      # On release: checks out the tag commit.
      # On dispatch: checks out the selected branch (defaults to the default branch).
      - name: Check out repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      # actions/setup-node — https://github.com/actions/setup-node
      # `registry-url` is what makes setup-node write the auth line into ~/.npmrc;
      # without it, npm publish can't see NODE_AUTH_TOKEN.
      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version-file: '.node-version'
          registry-url: 'https://registry.npmjs.org'
          cache: 'npm'

      # Set package.json version to match the release tag so what gets published
      # is authoritative from the tag, not whatever happened to be in the file.
      - name: Set release version from tag
        if: github.event_name == 'release'
        run: npm version "${GITHUB_REF_NAME#v}" --no-git-tag-version

      # Temporarily set the prerelease version in package.json without committing.
      # The dist-tag (--tag) prevents this from becoming `latest`.
      - name: Apply prerelease version
        if: github.event_name == 'workflow_dispatch'
        run: |
          pkg_version="$(node -p 'require("./package.json").version')"
          npm version "${pkg_version}-${{ inputs.preid }}" --no-git-tag-version

      - name: Install dependencies
        run: npm ci

      # `--provenance` emits a signed SLSA attestation tying the tarball to
      # this workflow run — visible on the npm page as a "Provenance" badge.
      # `--access public` is a no-op for unscoped packages but is required if
      # the package is ever scoped (@owner/name) and kept here so the move is safe.
      - name: Publish to npm
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            dist_tag="${{ inputs.preid }}"
            npm publish --provenance --access public --tag "${dist_tag%%.*}"
          else
            npm publish --provenance --access public
          fi
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      # Commit the version bump to the default branch so package.json stays in
      # sync with what was published. Runs after a successful publish so a failed
      # publish does not leave a stray version commit in the repo.
      # Note: if branch protection requires PRs for the default branch, grant
      # GITHUB_TOKEN a bypass in Settings → Branches, or swap in a PAT.
      - name: Commit release version to default branch
        if: github.event_name == 'release'
        run: |
          git fetch origin "$DEFAULT_BRANCH" --depth=1
          git checkout "$DEFAULT_BRANCH"
          npm version "${GITHUB_REF_NAME#v}" --no-git-tag-version
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add package.json package-lock.json
          git commit -m "chore: release ${GITHUB_REF_NAME}"
          git push origin "$DEFAULT_BRANCH"
        env:
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}