publish: a release you can resume, and announce last

[ralyodio]

Fixes #93.

What went wrong

Run 33854645746 published @profullstack/hqtui@0.1.10, failed in the demo's build, and left the v0.1.10 release public for a version nobody could install in full. Retrying the workflow reached the already-published library first, which npm refuses, so recovery burned 0.1.11.

publish.yml still ran two unconditional npm publish steps after a release: published trigger, so any later registry, network or auth failure reproduces the same split state.

What this does

scripts/publish.mjs splits the release into pack and publish, following the three steps the issue asked for.

1. Build and pack both packages before either upload, and keep the artifacts. Both tarballs are packed first, so a build failure happens while nothing is public, and they are uploaded as a run artifact (release-<tag>) before the first npm publish so a failed run can be resumed from the exact bytes.

pack also refuses a tarball that is missing its build. It checks every path package.json promises, then follows the relative imports inside the tarball — apps/demo's entry point is one line, import "../dist/main.js", so the declared entry point can be present in a tarball that installs nothing runnable. Removing the dist and packing reproduces the 0.1.10 failure shape:

@profullstack/hqtui-demo packed with imports it does not contain:
  bin/hqtui-demo.mjs imports ../dist/main.js

2. Distinguish a verified match from an absent version. Every package is looked up before anything is uploaded, and the answer is one of three states, never a guess: absent, present with a shasum, or indeterminate. Absent is published, a verified match is skipped, and a conflict or an unreadable registry fails the run before any upload. An unreachable registry read as "absent" is how you publish twice; read as "present" is how you skip a package that never shipped.

Sameness is decided on contents rather than gzip bytes: if dist.shasum differs, the published tarball is downloaded and compared file by file, because two packs of one commit can differ in packing without differing in what they install. Only a real content difference is a conflict.

3. Verify both packages before finalizing the release. publish waits for both versions to be readable, and the GitHub release is announced last.

A draft cannot start the workflow — GitHub does not trigger workflows for the created activity type on draft releases — so the tag push is the way in: write the notes as a draft, push the tag, and the workflow flips that draft to public once npm has both packages. With no draft it creates the release from the commit log. Publishing a release by hand still works and still publishes both packages; it just announces first, which is the ordering that made this possible.

Also: the dist-tag now comes from the version, so a prerelease publishes as next and its release is marked as one, instead of failing the guard on the release path.

Tests

packages/hqtui/test/publish.test.ts, 21 tests under both bun and node --test, with the registry and npm as functions. Including the issue's regression scenario:

• library published, demo not, recovery uploads only the demo, no version bump;
• the same version published with different contents stops the run with nothing uploaded;
• a byte-different but content-identical repack is skipped rather than fought over;
• an unreadable registry fails instead of guessing.

Verified against the real tree and the live registry: pack produces both tarballs with no false positives from the new guards, and a dry-run publish correctly classifies @profullstack/hqtui-demo@0.6.3 as an identical skip while flagging the library as changed since it was published (#94 touched ui.ts after that publish).

Full suite: 426 tests pass on bun and Node, bun run typecheck clean.

docs/RELEASING.md writes down the flow and the recovery, which is now "re-run the failed run".

Unrelated observation while testing: 0.6.3 is on npm but has no v0.6.3 tag or GitHub release.

🤖 Generated with Claude Code