[jonathan-kosgei]

Summary

• Add a release job to the Lint and Test workflow that runs on pushes to the default branch after lint and test pass. It reads the version from package.json and, when v<version> is not tagged yet, creates the tag and the GitHub release (with generated notes) in one step.
• Make the Release workflow callable (workflow_call with a tag input) and call it from the same run when a tag was created, with inherited secrets, so the npm publish happens even though a tag created with the workflow token starts no other workflow. The tag trigger is kept, so pushing a tag by hand still publishes exactly as before; the publish steps and the secret they use are unchanged.
• Document the procedure in a new "Releasing" section of the README.

How it works

1. release (in default.yml) runs only for push events on the repository's default branch, needs lint and test, has contents: write, and is serialised through the release concurrency group without cancelling runs in progress.
2. It reads the version with sed -nE 's/^ *"version": *"([^"]+)".*/\1/p' package.json | head -1 and derives the tag v<version>.
3. git ls-remote --exit-code --tags origin refs/tags/<tag> decides what happens next: exit 0 means the tag exists and the job reports that nothing is released; exit 2 means it is missing and gh release create <tag> --target $GITHUB_SHA --title <tag> --generate-notes creates the tag and the release with GITHUB_TOKEN; any other exit code fails the job. The job exposes tag and created as outputs.
4. publish needs release, runs only when created == 'true', and calls ./.github/workflows/release.yml with the tag, secrets: inherit and contents: read / id-token: write (npm provenance needs the OIDC token).
5. release.yml gains the workflow_call trigger with a required tag input and checks out inputs.tag, falling back to github.ref when it is started by a tag push. Lint, test, build and npm publish --provenance --access public are unchanged.

Verification

• Both workflow files parse as YAML and pass actionlint 1.7.12 with no findings.
• Against the current checkout the version command prints 3.1.0; git ls-remote --exit-code returns 2 for the untagged v3.1.0 and 0 for the existing v3.0.1, and the step logic, run locally with the gh call stubbed, sets created=true for the first and created=false for the second.
• npm version x.y.z --no-git-tag-version, as recommended in the README, updates both package.json and package-lock.json.
• The pull request CI (lint and the Node 20/22/24 test matrix) runs unchanged on this branch; the release and publish jobs are skipped on pull requests and on pushes to branches other than the default one.
• The push-triggered path cannot run before this is merged. Note that package.json is already at 3.1.0 and v3.1.0 is not tagged, so merging this pull request will tag v3.1.0, create its release and publish 3.1.0 to npm.

🤖 Generated with Claude Code