Report the version the package actually is

[patchstackdave]

Five surfaces answer "which version is this?" — the manifest, the two places the lockfile records it, the tarball name npm pack derives, an SBOM built from a checkout, and patchstack-connect --version. Only the published tarball takes its answer from the tag; everything read out of the repository takes it from the committed manifest. For a package whose purpose is to shield known vulnerabilities, a manifest naming the wrong version means someone believing they have a fix they do not have.

What this establishes

The tag is the trigger and the source of truth for what is published, which is what lets a release happen with no pre-commit and therefore work with branch protection. After a successful publish, Publish opens a pull request on chore/record-published-version bringing package.json and package-lock.json to the version that was published. Never auto-merged. RELEASING.md describes this.

--version is new. It reads the manifest at run time rather than having a value baked in at build time, so a partial or stale build cannot report a wrong version, and it answers unknown rather than throwing, because no command should fail over a diagnostic string.

tests/package-version.test.ts holds the surfaces checkable from a checkout: a plain release version in the manifest, the lockfile agreeing in both places, the name agreeing, the tarball name following from the manifest, the built CLI reporting it, and the fallback answering unknown on exit 0 both when the manifest has no version and when there is no manifest at all. The consumer matrix covers the one link a checkout cannot — the installed bin reporting the version npm resolved, checked against the tarball's own manifest and rejecting unknown.

On this branch all six surfaces report 0.3.31, including a real git installation.

Publication, verification and recording are three things

npm publish cannot be undone, so the canary that installs the published tarball and attacks the engine inside it runs past the point of no return: its failure is a discovery about something already released.

Each is therefore its own step in the graph. publish ends when npm accepts the tarball and outputs the version. verify-published runs the registry canary, and a failure there turns the workflow red. record-version depends on both and is gated on needs.publish.result alone.

The same reasoning applies inside record-version, where it is easier to get wrong. A step condition containing no status-check function is implicitly ANDed with success(), so the in-job invariant check must not be able to gate the pull request: that step carries continue-on-error, the pull-request step carries !cancelled(), and a final step fails the job once the pull request exists. The body reports steps.verify.outcome and the tarball verification result, and says plainly when either failed — for a failed tarball, that the version is on npm, cannot be unpublished, and needs a deprecation decision before the pull request is treated as routine.

tests/workflow-shell.test.ts names the steps that must survive an earlier failure and asserts each keeps a status function in its condition, that the verification step stays continue-on-error, and that the final step's own script exits non-zero when executed. All three are load-bearing: without the flag the job stops regardless of any condition below it, and a final step that runs but exits zero leaves a green workflow over a release whose surfaces disagree.

Two things this also fixes about the release gate

The recommended release path is workflow_dispatch. release.yml invokes gh workflow run publish.yml, so a job conditioned on github.event_name == 'release' never runs there. The condition is on the publish result instead; a dry-run dispatch leaves publish skipped rather than successful and is excluded by it.

Publish validation builds before testing, matching the main CI, because several tests assert against dist/ and return early without it.

Checking the scripts that CI cannot reach

A run: block is a program nothing checks — not the type checker, and usually not CI either, because a job only runs on the events it is configured for. A release-only job's script is first executed during a release.

tests/workflow-shell.test.ts parses the workflows and puts every bash script through bash -n. A syntax check and nothing more, which is what this class of error needs. publish, verify-published and record-version are all named as jobs that must stay covered, since none of them runs on a pull request. Every bash script in every workflow is checked; the PowerShell steps it cannot check are named in the test, so a bash block acquiring shell: pwsh cannot leave coverage unnoticed.

One expression is worth noting: the verification result is read as needs['verify-published'].result. A hyphen in a dotted property path is ambiguous with subtraction in GitHub's expression grammar, and the failure mode is silent — an empty string, which would trip the warning branch on every successful release.

CI on the automated pull request

record-version dispatches CI on its branch and carries actions: write to do so, since job-level permissions replaces the default set rather than adding to it.

A dispatched run does not attach to a pull request and therefore does not satisfy a required status. It proves the branch is green; closing and reopening the pull request is what produces the required checks. Both facts are in the body it writes. Opening it with an app installation token instead of GITHUB_TOKEN is the only thing that removes the manual step.

1724 tests, typecheck, build and all 7 consumer shapes pass.

[coderbuds]

Comprehensive version-consistency overhaul with thorough CI and CLI support.

🎯 Quality: 93% Elite · 📦 Size: Large — consider splitting if possible

📈 This month: Your 150th PR — above team average · Averaging Excellent

_{See how your team is trending →}

[patchstackdave]

/review