cereale/.github/workflows/release.yml

name: Publish to npm

# Deliberately manual. Pushing a tag does NOT publish — a tag is a decision to cut a release,
# not a decision to make it public and immutable, and npm's 72-hour unpublish window makes the
# second one hard to take back. Run this workflow from the Actions tab when you mean it.
#
# Authentication is by **trusted publishing** (OIDC): npm exchanges the workflow's
# short-lived GitHub identity token for a publish token scoped to this package, so no
# long-lived npm token has to exist. To enable it, on npmjs.com → the cereale package →
# Settings → Trusted publisher → GitHub Actions, set:
#
#   Organization or user: avalon-vanguard
#   Repository:           cereale
#   Workflow filename:    release.yml
#   Environment:          (leave blank — this workflow does not use one)
#
# The workflow filename must match this file's name, and the Environment field must be
# blank unless a matching `environment:` is added to the publish job; npm checks both
# against the OIDC claims and refuses the exchange if either disagrees.
#
# NPM_TOKEN is kept as a fallback. npm's OIDC step is deliberately non-throwing — if the
# trusted publisher is not configured, or the CLI is too old, it logs and falls through
# to token auth. That makes the switch safe to land before the registry side is set up.
# Once a real run shows OIDC working, the NPM_TOKEN secret can be deleted.
#
# Before a real run:
#   1. Run once with dry_run left as `true` and read the file list it prints.
#   2. Run again with dry_run set to `false`.
on:
  workflow_dispatch:
    inputs:
      dry_run:
        description: 'Resolve and pack everything, but do not publish'
        type: boolean
        default: true

permissions:
  contents: read
  id-token: write        # the OIDC identity npm exchanges, and provenance

jobs:
  publish:
    name: ${{ inputs.dry_run && 'Dry run' || 'Publish' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Tags are not fetched at the default depth, and the version gate below
          # resolves one — without this it fails on every release, tag or no tag.
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22.x
          cache: 'npm'
          registry-url: 'https://registry.npmjs.org'

      # Node 22 bundles npm 10.x, which has no OIDC support at all — it would skip
      # trusted publishing in silence and fall back to token auth. Trusted publishing
      # landed in npm 11.5.0 (lib/utils/oidc.js), so the version is raised and then
      # asserted rather than assumed.
      - name: Use an npm that can do trusted publishing
        run: |
          npm install -g npm@latest
          V=$(npm --version)
          echo "npm $V"
          MAJ=${V%%.*}; REST=${V#*.}; MIN=${REST%%.*}
          if [ "$MAJ" -lt 11 ] || { [ "$MAJ" -eq 11 ] && [ "$MIN" -lt 5 ]; }; then
            echo "::error::npm $V has no OIDC support; trusted publishing needs >= 11.5.0"
            exit 1
          fi

      - name: Install dependencies
        run: npm ci

      # The tag and the manifest disagreeing is the classic way to publish 0.3.0 as 0.2.0.
      - name: Tag and package.json version must agree
        run: |
          VERSION=$(node -p "require('./package.json').version")
          echo "package.json version: $VERSION"
          if git rev-parse "v$VERSION" >/dev/null 2>&1; then
            echo "tag v$VERSION exists"
          else
            echo "::error::No tag v$VERSION. Tag the release commit before publishing."
            exit 1
          fi
          if [ "$(git rev-parse HEAD)" != "$(git rev-parse "v$VERSION^{commit}")" ]; then
            echo "::error::v$VERSION does not point at the commit being published."
            exit 1
          fi

      - name: Refuse to republish a version already on the registry
        run: |
          VERSION=$(node -p "require('./package.json').version")
          NAME=$(node -p "require('./package.json').name")
          if npm view "$NAME@$VERSION" version >/dev/null 2>&1; then
            echo "::error::$NAME@$VERSION is already published. Bump the version."
            exit 1
          fi
          echo "$NAME@$VERSION is not on the registry yet."

      # The same gate that guards every push: type-check, lint, 259 tests, build, and the
      # checks that the published types stand alone and the landing page has no CDN deps.
      - name: Verify
        run: npm run verify

      - name: Show exactly what would ship
        # `npm publish --dry-run` performs the OIDC token exchange before it short-circuits
        # (publish.js calls oidc() ahead of every dryRun branch), so this step is also the
        # trusted-publishing smoke test — a dry run proves the exchange without publishing.
        #
        # verbose, because npm's OIDC step is non-throwing: at the default log level a
        # successful exchange and a silent fallback to token auth look identical. Success
        # prints `oidc Successfully retrieved and set token`; if that line is missing,
        # trusted publishing did not engage. (The reasons it skips are logged at silly.)
        env:
          NPM_CONFIG_LOGLEVEL: verbose
        run: npm publish --dry-run

      - name: Publish
        if: ${{ inputs.dry_run == false }}
        # --provenance stays explicit. Under OIDC npm would enable it on its own for a
        # public repo, but only when the flag was left at its default; asking for it
        # directly just skips that auto-enable and reaches the same place. On the token
        # fallback path it is the only thing that produces an attestation at all.
        run: npm publish --provenance --access public
        env:
          # Fallback only. Ignored once the trusted publisher is configured, because npm
          # sets its own short-lived token before reading credentials.
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Summary
        run: |
          VERSION=$(node -p "require('./package.json').version")
          {
            echo "### cereale@$VERSION"
            if [ "${{ inputs.dry_run }}" = "true" ]; then
              echo "Dry run — nothing was published."
            else
              echo "Published to https://www.npmjs.com/package/cereale/v/$VERSION"
            fi
          } >> "$GITHUB_STEP_SUMMARY"