release.yml

name: Release

# Two-path release pipeline, keyed on the long-lived branch that got pushed:
#
# 1. push to `development`  → release-rc job
#      Every integration merge auto-publishes a new release candidate.
#      Reads the current base version from package.json, queries npm for
#      the highest existing `-rc.N` on that base, bumps to `-rc.N+1` via
#      `npm-version-suffix`, runs all gates, then `npm publish --tag next`
#      (so `npm install <pkg>@latest` stays on the stable release). After
#      a successful publish, commits the package.json bump, creates an
#      annotated `v<version>` tag, and pushes both back to development.
#
# 2. push to `master`        → release-stable job
#      A merge to master is a ship signal. Strips any `-rc.N` suffix that
#      RC runs left on package.json, runs gates, and `npm publish`
#      (no tag, so it becomes `latest`). Idempotent: if the clean version
#      is already on npm (e.g. master got a non-version-bumping commit),
#      the job skips the publish instead of failing loudly. Otherwise,
#      it commits, tags `v<version>`, and pushes. Manual
#      `workflow_dispatch` is preserved as an escape hatch for off-cycle
#      patches / re-publishes.
#
# Every successful publish leaves a matching annotated git tag as the
# authoritative reference — the tag points at the exact commit whose
# contents produced the npm artifact.
#
# Prerequisites (one-time, repo-owner does this):
#   - On npmjs.com: add a Trusted Publisher entry for this repo
#     (GitHub Actions, workflow filename `release.yml`, environment
#     blank). `npm publish --provenance` then authenticates via OIDC
#     using the job's `id-token: write` permission — no NPM_TOKEN
#     secret needed.
#   - On npmjs.com: set "Publishing access" → "Require 2FA and
#     disallow tokens" so the only publish path is through this
#     workflow's trusted OIDC exchange.
#   - On GitHub: Settings → Actions → General → Workflow permissions
#     → "Read and write permissions" (so the workflow can push back
#     the version bump commit + annotated tag).

on:
  push:
    branches: [development, master]
    # Only fire when the push actually changes something that ships.
    # Docs site, examples, README/CHANGELOG, CI config, test-fixtures,
    # Storybook, and in-source tests/benches/stories don't affect the
    # published artifact, so they shouldn't mint a new RC or stable.
    paths:
      - 'src/**'
      - '!src/__tests__/**'
      - '!src/**/*.test.ts'
      - '!src/**/*.test.tsx'
      - '!src/**/*.bench.ts'
      - '!src/**/*.stories.tsx'
      - 'package.json'
      - 'package-lock.json'
      - 'tsup.config.ts'
      - 'postcss.config.js'
      - 'tsconfig.json'
  workflow_dispatch:
    inputs:
      version:
        description: 'Override: publish this exact version to `latest` (e.g. 2.0.1). Runs the stable job.'
        required: true
        type: string

jobs:
  # --------------------------------------------------------------------
  # RC publish — every push to development produces a new -rc.N on npm
  # --------------------------------------------------------------------
  release-rc:
    if: github.event_name == 'push' && github.ref == 'refs/heads/development'
    runs-on: ubuntu-latest
    permissions:
      contents: write   # push version bump + tag
      id-token: write   # npm provenance (OIDC)
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          # registry-url is required so `npm publish` targets
          # registry.npmjs.org. The `.npmrc` setup-node writes
          # references NODE_AUTH_TOKEN — we don't set it (no token),
          # so `npm publish --provenance` falls through to OIDC using
          # the Trusted Publisher entry on npmjs.com.
          registry-url: 'https://registry.npmjs.org'

      # Ensure we're on a recent-enough npm CLI for Trusted Publishing
      # (seamless OIDC publish requires npm 11.5.1+; runners ship
      # older minor versions by default).
      - run: npm install -g npm@latest

      - run: npm ci

      - name: Gate — lint + typecheck
        run: |
          npm run lint
          npm run typecheck

      - name: Gate — test (one React peer here; the matrix runs on CI)
        run: npm test

      - name: Gate — build
        run: npm run build

      - name: Gate — API contract
        run: npm run check:api

      - name: Gate — bundle size
        run: npm run check:size

      - name: Bump RC version (reads `npm view` for latest -rc.N and +1)
        # The package has no CLI binary — invoke the script directly.
        # Starts at -rc.1 if no previous RC exists for this base version.
        # Base version comes from package.json's current "version" field;
        # maintainers bump that manually when starting a new minor/major
        # track (e.g. `npm version 2.1.0 --no-git-tag-version`) and push
        # the bump to development as the first commit of the new cycle.
        run: node ./node_modules/npm-version-suffix/run-add-suffix.js

      - name: Sync package-lock.json with the new version
        # `npm-version-suffix` only touches package.json; bring the lock
        # file to match so the committed state isn't half-bumped.
        run: npm install --package-lock-only --ignore-scripts

      - name: Read new version
        id: rc_version
        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT

      - name: Publish to npm (next dist-tag)
        # Authenticates via OIDC against the Trusted Publisher entry on
        # npmjs.com — no NPM_TOKEN secret needed. `--provenance` attests
        # the artifact's origin on npm's sigstore-backed transparency
        # log. `--access public` matches npm's documented TP example
        # and avoids an implicit-scope detection quirk.
        run: npm publish --tag next --provenance --access public

      - name: Tag the shipped commit
        # Runs only after npm publish succeeded — the tag is always a
        # reference to a shipped version. We DON'T try to push a
        # version-bump commit back to development: branch protection
        # rules block non-PR pushes, and the bump is only needed on
        # the runner so npm publish sees the -rc.N version. The tag
        # points at the workflow-triggering commit (HEAD of
        # development); `git describe` and the npm provenance both
        # reference the same SHA, so consumers can always trace a
        # published version back to its source.
        run: |
          VERSION="${{ steps.rc_version.outputs.version }}"
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          # Reset any in-runner bump commits so the tag lands on the
          # actual development HEAD (stashing the staged bump keeps
          # the runner workspace clean for post-step cleanup).
          git reset --hard HEAD
          git tag -a "v$VERSION" -m "Release candidate $VERSION"
          git push origin "v$VERSION"

  # --------------------------------------------------------------------
  # Stable publish — auto on push to master, plus workflow_dispatch escape
  # --------------------------------------------------------------------
  release-stable:
    if: |
      (github.event_name == 'push' && github.ref == 'refs/heads/master') ||
      github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          # registry-url is required so `npm publish` targets
          # registry.npmjs.org. The `.npmrc` setup-node writes
          # references NODE_AUTH_TOKEN — we don't set it (no token),
          # so `npm publish --provenance` falls through to OIDC using
          # the Trusted Publisher entry on npmjs.com.
          registry-url: 'https://registry.npmjs.org'

      # Ensure we're on a recent-enough npm CLI for Trusted Publishing
      # (seamless OIDC publish requires npm 11.5.1+; runners ship
      # older minor versions by default).
      - run: npm install -g npm@latest

      - run: npm ci

      - name: Gates
        run: |
          npm run lint
          npm run typecheck
          npm test
          npm run build
          npm run check:api
          npm run check:size

      - name: Set target version
        # workflow_dispatch path: caller provided an explicit version.
        # push path: whatever is in package.json after stripping `-rc.N`
        # (development's RC job committed that back; merging development →
        # master brings the suffix along). `run-remove-suffix` is a no-op
        # if the version is already clean.
        run: |
          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
            npm version "${{ inputs.version }}" --no-git-tag-version --allow-same-version
          else
            node ./node_modules/npm-version-suffix/run-remove-suffix.js || true
          fi

      - name: Sync package-lock.json with the new version
        run: npm install --package-lock-only --ignore-scripts

      - name: Check if this version is already on npm
        id: check
        # Idempotent guard: if a commit to master doesn't actually advance
        # the version (e.g. typo fix, doc tweak), don't re-publish — just
        # exit successfully.
        run: |
          VERSION=$(node -p "require('./package.json').version")
          echo "version=$VERSION" >> $GITHUB_OUTPUT
          if npm view "react-simple-tree-menu@$VERSION" version > /dev/null 2>&1; then
            echo "already_published=true" >> $GITHUB_OUTPUT
            echo "Version $VERSION is already on npm — skipping publish."
          else
            echo "already_published=false" >> $GITHUB_OUTPUT
          fi

      - name: Publish to npm (latest)
        # Same OIDC + provenance flow as the RC path — see the matching
        # note above.
        if: steps.check.outputs.already_published == 'false'
        run: npm publish --provenance --access public

      - name: Tag the shipped commit
        # Same pattern as the RC path — tag the workflow-triggering
        # commit on master; no version-bump commit is pushed back.
        # `-f` on tag + `--force` on push so a republish (e.g. after
        # an unpublish / clean-history reset) overwrites the stale
        # tag instead of exiting non-zero on "tag already exists."
        if: steps.check.outputs.already_published == 'false'
        run: |
          VERSION="${{ steps.check.outputs.version }}"
          git config user.name 'github-actions[bot]'
          git config user.email 'github-actions[bot]@users.noreply.github.com'
          git reset --hard HEAD
          git tag -f -a "v$VERSION" -m "Release $VERSION"
          git push --force origin "v$VERSION"