Adopt Release Please for human-gated npm releases

[dannysauer]

Why this needs changing

Publishing @herodevs/eol-shared is manual today. The human decision is useful; the machinery around that decision is the part we should replace.

release-build.yml currently builds the package and force-pushes it to the release-build branch. A maintainer then checks out that branch, creates a tag, and pushes it. Another workflow publishes the tag to npm and creates an empty GitHub Release. The build workflow itself creates neither tags nor releases.

Release Please gives us a better decision point. It can collect conventional commits in a release PR, calculate the next version, and wait for a maintainer to review and merge that PR.

The obvious implementation would create a tag and let a tag-triggered workflow publish it. That won't work with the default GITHUB_TOKEN: GitHub suppresses new workflow runs caused by events created with that token. The npm publish job therefore needs to run in the same workflow invocation that creates the release.

Proposed release flow

1. Release Please opens or updates a release PR after conventional commits land on main.
2. A maintainer reviews and merges that PR when we're ready to release.
3. Release Please creates the vX.Y.Z tag and GitHub Release.
4. A job in the same workflow builds and publishes that version to npm through the existing OIDC trusted-publisher connection.

Use Release Please's simple strategy so package.json and package-lock.json can remain at the repository's 1.0.0 placeholder. Release Please will maintain version.txt, CHANGELOG.md, and its manifest instead. The publish job will stamp the selected version into the package files in its workspace before it builds and publishes.

Bootstrap the release state at 0.1.23, using source commit dafcae1c228f81b31e914410233d2a36056ee536 as the boundary for the last published release. Use ordinary SemVer rules: fixes bump the patch version, features bump the minor version, and breaking changes bump the major version.

Keep the workflow filename npm-publish.yml because npm's trusted-publisher configuration names that file. The publish job should continue to use OIDC, avoid dependency caching in the privileged job, and pin every action to a full commit SHA with a full version comment.

Keep workflow_dispatch as a recovery path. If Release Please creates a release but npm publishing fails, a maintainer should be able to rerun publication for that existing tag.

Once this flow works, remove release-build.yml and update CONTRIBUTING.md. Leave the historical release-build branch in place.

Compatibility

Future tags will point to source commits on main, not generated commits on release-build.

The CLI and report-card currently install this package from GitHub tags. Installing the current source commit was tested: npm ran prepare, created dist/index.js, and successfully imported the package. Those consumers don't need to move to npm before this change, though we can migrate them separately later.

Acceptance criteria

• Release Please opens and maintains a release PR from conventional commits.
• Merging the release PR creates a vX.Y.Z tag and a GitHub Release.
• The same workflow run publishes that version to npm through OIDC.
• Published package metadata contains the release version.
• Tracked package.json and package-lock.json remain at 1.0.0.
• Manual dispatch can recover a failed npm publication for an existing release tag.
• Installing a source tag as a Git dependency builds and imports the package.
• The obsolete release-build workflow is removed and contributor instructions describe the new process.
• This work remains separate from PR Pin GitHub Actions and configure Renovate #33, which covers Renovate, .tool-versions, and pinned GitHub Actions.

[dannysauer]

CC: @rlmestre @facundo-herodevs @eduardoRoth , since I'm pretty sure I talked to at least one of you about trying this out to simplify / better automate future releases. 😅