ci: automate releases (tag -> test -> npm publish -> GitHub Release) #47

Goal

Make cutting a version tag → CI publishes, not a manual npm publish. Establish a 1:1 chain: git tag vX.Y.Z ↔ npm X.Y.Z ↔ CHANGELOG [X.Y.Z] ↔ GitHub Release vX.Y.Z.

Builds on #35 (test CI) — the release workflow should run the test suite as a gate once that lands.

Proposed .github/workflows/release.yml

name: Release
on:
  push:
    tags: ['v*']
permissions:
  contents: write          # create the GitHub Release
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: npm ci
      - run: npm test --if-present        # becomes a hard gate after #35
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}
      - name: GitHub Release from CHANGELOG
        run: gh release create \"\$GITHUB_REF_NAME\" --title \"\$GITHUB_REF_NAME\" --notes-file release-notes.md
        env:
          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}

(Extract the matching CHANGELOG section into release-notes.md in a prior step — or adopt release-please to auto-open a release PR that bumps the version + CHANGELOG and tags on merge.)

Prerequisites

• Add NPM_TOKEN repo secret (npm automation token)
• Guard step: fail if tag version ≠ package.json version
• Decide: manual npm version + tag vs release-please

Acceptance criteria

• Pushing a vX.Y.Z tag publishes to npm and creates the matching GitHub Release with CHANGELOG notes
• Test suite gates the publish (after test: Vitest unit suite with mocked Postmark client + CI #35)
• Process documented in README / CONTRIBUTING

Release cadence (decision)

Release per semver version, not per PR — merged PRs accumulate under CHANGELOG [Unreleased] until a meaningful version is cut.