release.yml

name: Auto-release

# Every push to main that lands a new `changelog/<pkg>/<version>.md`
# file becomes:
#   1. A published npm.com package via scripts/publish-npm.js.
#   2. A published GitHub Packages copy via scripts/publish-github-packages.js
#      (so the repo's Packages sidebar lists each version).
#   3. A GitHub Release via scripts/publish-release.js.
#
# All three scripts are idempotent: they skip when the version is
# already on the destination registry / a release with the tag
# already exists. So workflow retries and force-pushes never
# duplicate or error on previously-published versions.
#
# Order matters: npm.com runs first, then GitHub Packages, then GH
# Releases. If any step fails (auth, network, transient registry
# error), later steps are skipped and the workflow fails. A
# re-run picks up where it left off thanks to the idempotency
# checks.
#
# Triggered only on changelog/** changes so unrelated pushes do
# not run the job. workflow_dispatch is also wired so a one-time
# bootstrap can republish every existing changelog file to GitHub
# Packages without needing a fresh changelog file. Cost on public
# repos: $0 (Actions has unlimited free minutes for public repos
# on ubuntu-latest).
#
# npm auth is TRUSTED PUBLISHING (OIDC), so there is no NPM_TOKEN
# secret to store, rotate, or let expire. Each of the 8 published
# packages carries its own Trusted Publisher configuration on
# npmjs.com naming owner `webjsdev`, repo `webjs`, and workflow
# `release.yml`. Renaming THIS FILE breaks every publish until all
# 8 are updated, and it fails as an opaque 404 on the publish PUT
# rather than as an auth error. See framework-dev.md.

on:
  push:
    branches: [main]
    paths:
      - 'changelog/**'
  workflow_dispatch:
    inputs:
      bootstrap_github_packages:
        description: 'Republish every existing changelog file to GitHub Packages (one-time bootstrap; npm.com + GH Releases steps are skipped)'
        type: boolean
        default: false
      lockstep_only:
        description: 'Only (re)publish the unscoped wrappers (create-webjs, webjsdev) at the current @webjsdev/cli version. Use to recover a release whose wrapper publish did not land.'
        type: boolean
        default: false
      republish_paths:
        description: 'Space or comma separated changelog paths to (re)publish to npm, e.g. "changelog/core/0.7.52.md changelog/server/0.8.66.md". Recovery path for a release whose npm publish failed. Leave empty for a normal run.'
        type: string
        default: ''

permissions:
  contents: write   # gh release create needs write access to the repo
  packages: write   # npm publish to GitHub Packages
  id-token: write   # mint the OIDC credential npm trusted publishing exchanges

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      # Pinned to v6: both actions ship a Node 24 runtime, which is
      # what GitHub Actions will default to from June 2nd, 2026. v4
      # / v5 ran on Node 20 and triggered the deprecation banner.
      - uses: actions/checkout@v6
        with:
          fetch-depth: 2

      # `registry-url` is REQUIRED for trusted publishing, not optional
      # decoration: it writes the .npmrc that points npm at the registry
      # the OIDC exchange authenticates against. Removing it breaks the
      # exchange even though no token is involved any more.
      #
      # Node 24 bundles npm 11.19.x, which clears trusted publishing's
      # npm >= 11.5.1 floor. Do NOT add `npm install -g npm@latest` to
      # "make sure npm is new enough": npm `latest` is 12.x, and npm 12
      # turns on the install-time security defaults (`allowScripts` off),
      # which blocks esbuild's postinstall, which means packages/core/dist
      # never builds. The bundled 11.19.x satisfies OIDC without opting
      # into that.
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm install --no-audit --no-fund

      - name: Find new changelog files
        id: diff
        run: |
          set -euo pipefail
          # Three modes:
          #   1. push event: diff HEAD~1..HEAD for newly added changelog files.
          #   2. workflow_dispatch with bootstrap_github_packages=true: list
          #      every changelog/**.md file currently in the tree. The
          #      publish-github-packages.js step is idempotent (skips
          #      already-published versions) so a re-run is safe.
          #   3. workflow_dispatch with republish_paths set: publish exactly
          #      the named files. This is the recovery path for a release
          #      whose npm publish failed, and it exists because RE-RUNNING
          #      the failed run does NOT work: a re-run replays the workflow
          #      file from its ORIGINAL commit, so a run that predates a fix
          #      to this file never sees the fix. Every publish script is
          #      idempotent, so naming an already-published version is a
          #      no-op rather than an error.
          BOOTSTRAP='${{ inputs.bootstrap_github_packages }}'
          REPUBLISH='${{ inputs.republish_paths }}'
          if [ -n "$REPUBLISH" ]; then
            # Validate every path BEFORE publishing anything: a typo that
            # silently published nothing would look identical to success.
            mapfile -t REQUESTED < <(printf '%s' "$REPUBLISH" | tr ', ' '\n\n' | grep -v '^$')
            for f in "${REQUESTED[@]}"; do
              if [ ! -f "$f" ]; then
                echo "republish_paths: no such changelog file: $f" >&2
                exit 1
              fi
            done
            # Sort the requested set by `date:` ASC exactly as the push path
            # does, so core still publishes before server and the npm
            # `latest` tag lands on the newest version rather than whichever
            # was typed last.
            mapfile -t NEW < <(
              printf '%s\n' "${REQUESTED[@]}" \
                | while read -r f; do
                    ts=$(awk '/^date:/ { print $2; exit }' "$f")
                    printf '%s\t%s\n' "$ts" "$f"
                  done \
                | sort -k1,1 -k2,2r \
                | cut -f2-
            )
          elif [ "$BOOTSTRAP" = 'true' ]; then
            mapfile -t NEW < <(
              find changelog -name '*.md' -not -name 'README.md' \
                | while read -r f; do
                    ts=$(awk '/^date:/ { print $2; exit }' "$f")
                    printf '%s\t%s\n' "$ts" "$f"
                  done \
                | sort -k1,1 -k2,2r \
                | cut -f2-
            )
          else
            # Sort by the `date:` timestamp inside each file's
            # frontmatter, ASCending. GitHub Releases lists releases by
            # created_at DESC, so publishing oldest-first means newest
            # entries end up at the top of the Releases page.
            #
            # Within tied timestamps (multiple packages bumped in one
            # PR), sort the filename DESC so the alphabetically-first
            # package publishes LAST, gets the latest created_at, and
            # ends up at the top of the GH list. The website's
            # /changelog page iterates package dirs alphabetically
            # too, so this produces matching order on both surfaces.
            mapfile -t NEW < <(
              git diff --name-only --diff-filter=A HEAD~1 HEAD -- 'changelog/**.md' \
                | while read -r f; do
                    ts=$(awk '/^date:/ { print $2; exit }' "$f")
                    printf '%s\t%s\n' "$ts" "$f"
                  done \
                | sort -k1,1 -k2,2r \
                | cut -f2-
            )
          fi
          if [ ${#NEW[@]} -eq 0 ]; then
            echo "No new changelog files in this push; skipping."
            echo "count=0" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          printf '  + %s\n' "${NEW[@]}"
          printf '%s\n' "${NEW[@]}" > .new-changelog-files.txt
          echo "count=${#NEW[@]}" >> "$GITHUB_OUTPUT"
          echo "bootstrap=$BOOTSTRAP" >> "$GITHUB_OUTPUT"

      # No NODE_AUTH_TOKEN: this publishes via npm trusted publishing
      # (OIDC). The npm CLI detects the Actions OIDC environment and
      # exchanges the job's id-token for a short-lived, workflow-scoped
      # credential before it would ever fall back to a token, so
      # scripts/publish-npm.js needs no change (its auth comment already
      # says it relies on standard npm publish token resolution).
      #
      # Each of the 8 published packages has a Trusted Publisher
      # configured on npmjs.com naming owner `webjsdev`, repo `webjs`,
      # and workflow `release.yml`. Renaming this FILE therefore breaks
      # every publish until those 8 configurations are updated to match.
      - name: Publish to npm
        if: steps.diff.outputs.count != '0' && steps.diff.outputs.bootstrap != 'true'
        run: |
          set -euo pipefail
          while IFS= read -r f; do
            [ -z "$f" ] && continue
            node scripts/publish-npm.js "$f"
          done < .new-changelog-files.txt

      - name: Publish to GitHub Packages
        if: steps.diff.outputs.count != '0'
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          while IFS= read -r f; do
            [ -z "$f" ] && continue
            node scripts/publish-github-packages.js "$f"
          done < .new-changelog-files.txt

      - name: Create GitHub Releases
        if: steps.diff.outputs.count != '0' && steps.diff.outputs.bootstrap != 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          while IFS= read -r f; do
            [ -z "$f" ] && continue
            node scripts/publish-release.js "$f"
          done < .new-changelog-files.txt

      # Lockstep-publish the unscoped wrapper packages (`create-webjs`,
      # `webjsdev`) at the new @webjsdev/cli version whenever this push
      # landed a new cli changelog. The wrappers exist purely as version
      # mirrors of cli, so their npm versions MUST equal cli's version
      # exactly; otherwise the npx cache serves an outdated cli through
      # them (a wrapper cached at 0.8.4 keeps resolving cli@0.8.4 even
      # after cli@0.8.5 publishes, because the wrapper's pkg-version is
      # what npx keys its cache on).
      #
      # This step does NOT write back to the repo. Earlier designs tried
      # to commit the wrapper bumps (direct push, then PR + merge), but
      # the webjsdev org disables write permissions for GITHUB_TOKEN:
      # direct pushes are refused by branch protection and `gh pr create`
      # is refused with "GitHub Actions is not permitted to create or
      # approve pull requests". Since the wrapper version is recomputed
      # from CLI_VERSION here on every release, the repo copy of the
      # wrapper package.json is irrelevant to publishing, so we simply
      # set the version in the runner's working tree and `npm publish`.
      # The repo's wrapper package.json versions intentionally drift (npm
      # is the source of truth for them); nothing reads them.
      #
      # Publishing is idempotent: a wrapper already on the registry at
      # CLI_VERSION is skipped, so re-runs and the `lockstep_only`
      # manual dispatch are safe.
      #
      # `lockstep_only` (workflow_dispatch input) runs ONLY this step at
      # the current CLI_VERSION: the recovery path for a release whose
      # wrapper publish did not land.
      # Also publishes over OIDC, so no NODE_AUTH_TOKEN here either.
      # `create-webjs` and `webjsdev` each carry their own Trusted
      # Publisher configuration, since trusted publishing is per package
      # rather than per repo. This step is the easily-missed second
      # consumer of the old NPM_TOKEN secret.
      - name: Lockstep-publish wrappers to match @webjsdev/cli
        if: inputs.lockstep_only || (steps.diff.outputs.count != '0' && steps.diff.outputs.bootstrap != 'true')
        run: |
          set -euo pipefail

          # In a normal release run, only proceed if a cli changelog
          # landed in this push. The lockstep_only dispatch skips this
          # gate (there is no .new-changelog-files.txt to consult).
          if [ "${{ inputs.lockstep_only }}" != "true" ]; then
            if ! grep -q '^changelog/cli/' .new-changelog-files.txt; then
              echo "No new @webjsdev/cli changelog in this push; skipping wrapper lockstep."
              exit 0
            fi
          fi

          CLI_VERSION=$(node -p "require('./packages/cli/package.json').version")
          echo "Lockstep-publishing create-webjs + webjsdev at @webjsdev/cli@${CLI_VERSION}"

          for pkg in create-webjs webjsdev; do
            # Set the version + cli dep range in the runner's working
            # tree only (never committed). npm publish reads from here.
            node -e "
              const fs = require('node:fs');
              const path = './packages/wrappers/${pkg}/package.json';
              const j = JSON.parse(fs.readFileSync(path, 'utf8'));
              j.version = '${CLI_VERSION}';
              if (j.dependencies && j.dependencies['@webjsdev/cli']) {
                j.dependencies['@webjsdev/cli'] = '^${CLI_VERSION}';
              }
              fs.writeFileSync(path, JSON.stringify(j, null, 2) + '\n');
            "
            REMOTE=$(npm view "${pkg}@${CLI_VERSION}" version 2>/dev/null || echo "")
            if [ "$REMOTE" = "${CLI_VERSION}" ]; then
              echo "  skip ${pkg}@${CLI_VERSION}: already on registry"
            else
              echo "  publishing ${pkg}@${CLI_VERSION}..."
              npm publish --workspace="${pkg}" --access=public --ignore-scripts=false
            fi
          done