feat(release): add preview publish history command

[jasonkuhrt]

Summary

• add a root release history command for reading preview publish state and embedded publish records
• reuse the existing preview metadata model and add deterministic publish-history ordering
• cover metadata ordering, history resolution, help text, and report rendering with tests

Verification

• bun run --cwd packages/release test packages/release/src/cli/commands/pr-lib.test.ts packages/release/src/api/commentator/metadata.test.ts packages/release/src/cli/commands/history-lib.test.ts packages/release/src/cli/help.test.ts
• bun run --cwd packages/release check:types
• bun run release:verify
• git diff --check

Closes #166

[github-actions]

Release Forecast

39 packages · 35 primary · 4 cascades · head 8b855b7

How release calculation works

Primary — packages with commits directly touching their source in this PR.
Cascade — packages that depend on a primary release; re-published for consistency.

Context	Version Format
Ephemeral (PR)	0.0.0-pr.<N>.<iter>.<sha>
Candidate	<base>-next.<N>
Official	Semver bump from conventional commits

Bump rules: feat() → minor · fix() → patch · ! → major
Cascades inherit patch bump.

Projected Release Header

feat(bldr, cli, conventional-commits, core, env, fs, git, group, idx, json, num, oak, oxlint-rules, paka, resource, syn, test, tex, tree)!, feat(color, doc-inject, html, http, log, mod, name, npm-registry, release, sch, semver, url, ware), fix(flo, github, kitz)

Current PR header: feat(release)
Current PR title: feat(release): add preview publish history command

Doctor

Check	Status	Notes
Publish channel	manual	Declared as manual. Merging does not publish automatically.
Release header	error	PR title header is out of sync with the projected squash-merge header.
Release kind	pass	PR title kind matches the changed source files.
Package visibility	pass	All 39 planned packages are publishable and not marked private: true.
License metadata	pass	All 39 planned packages declare a license.
Repository metadata	pass	All 39 planned packages declare repository metadata.
Repository provenance	pass	All 39 planned packages point at jasonkuhrt/kitz.
Version availability	pass	All 39 planned package versions are still unpublished on npm.
Tag uniqueness	pass	No planned release tags collide with existing git tags.

Guidance (1)

• Release header: PR title header is out of sync with the projected squash-merge header.
  Expected header feat(bldr, cli, conventional-commits, core, env, fs, git, group, idx, json, num, oak, oxlint-rules, paka, resource, syn, test, tex, tree)!, feat(color, doc-inject, html, http, log, mod, name, npm-registry, release, sch, semver, url, ware), fix(flo, github, kitz), but PR title header is feat(release).
  Fix: Apply the canonical release header to the connected PR title.
  Command: release pr title apply
  Fix docs: GitHub squash merge defaults
  Hint: Rename the PR title header so GitHub’s default squash-merge title starts with the computed release header.
  Docs: GitHub squash merge defaults

Manual Preview Runbook

1. bun run release:build
2. PR_NUMBER=200 bun run release plan --lifecycle ephemeral
3. bun run release doctor
4. bun run release apply --yes

Step 2 writes the exact ephemeral publish plan to .release/plan.json. Step 4 publishes those packages to the pr-200 dist-tag automatically.

Could Still Go Wrong Locally

This comment cannot verify your local machine. Before applying the manual preview release, these checks still need to pass:

• env.npm-authenticated: prevents npm publish failing because your npm session or token is missing, expired, or scoped incorrectly. Check with bun run release doctor --onlyRule env.npm-authenticated.
• env.git-clean: prevents publishing from a dirty working tree and tagging code that does not match committed source. Check with bun run release doctor --onlyRule env.git-clean.
• env.git-remote: prevents tag push failures because the release remote is missing, misnamed, or unreachable. Check with bun run release doctor --onlyRule env.git-remote.

---

Primary (35)

• ■ @kitz/test — 40 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +35
  0.1.0 major (from new)

• ■ @kitz/release — 30 commits
  8b855b7 b854e14 c14319f c50105d 5a200ea +25
  0.1.0 minor (from new)

• ■ @kitz/paka — 25 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +20
  0.1.0 major (from new)

• ■ @kitz/fs — 24 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +19
  0.1.0 major (from new)

• ■ @kitz/cli — 20 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +15
  0.1.0 major (from new)

• ■ @kitz/num — 11 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +6
  0.1.0 major (from new)

• ■ @kitz/json — 10 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +5
  0.1.0 major (from new)

• ■ @kitz/idx — 9 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +4
  0.1.0 major (from new)

• ■ @kitz/group — 9 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +4
  0.1.0 major (from new)

• ■ @kitz/http — 9 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +4
  0.1.0 minor (from new)

• ■ @kitz/oak — 8 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +3
  0.1.0 major (from new)

• ■ @kitz/tree — 8 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +3
  0.1.0 major (from new)

• ■ @kitz/resource — 8 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +3
  0.1.0 major (from new)

• ■ @kitz/syn — 7 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +2
  0.1.0 major (from new)

• ■ @kitz/mod — 7 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +2
  0.1.0 minor (from new)

• ■ @kitz/ware — 7 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +2
  0.1.0 minor (from new)

• ■ @kitz/bldr — 7 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +2
  0.1.0 major (from new)

• ■ @kitz/core — 7 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +2
  0.1.0 major (from new)

• ■ @kitz/log — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 minor (from new)

• ■ @kitz/name — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 minor (from new)

• ■ @kitz/tex — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 major (from new)

• ■ @kitz/url — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 minor (from new)

• ■ @kitz/html — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 minor (from new)

• ■ @kitz/color — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 minor (from new)

• ■ @kitz/env — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 major (from new)

• ■ @kitz/sch — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 minor (from new)

• ■ @kitz/semver — 6 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f +1
  0.1.0 minor (from new)

• ■ @kitz/flo — 5 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f
0.0.1 patch (from new)

• ■ @kitz/github — 5 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f
0.0.1 patch (from new)

• ■ @kitz/conventional-commits — 5 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f
0.1.0 major (from new)

• ■ kitz — 5 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f
0.0.1 patch (from new)

• ■ @kitz/npm-registry — 5 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f
0.1.0 minor (from new)

• ■ @kitz/oxlint-rules — 5 commits
  eba40f4 c343f5c bd6ac95 b1306bb 8a135aa
0.1.0 major (from new)

• ■ @kitz/git — 5 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f
0.1.0 major (from new)

• ■ @kitz/doc-inject — 5 commits
  c343f5c bd6ac95 b1306bb 8a135aa b22617f
0.1.0 minor (from new)

Cascades (4)

• ■ @kitz/conf via @kitz/mod, @kitz/fs, @kitz/env, @kitz/sch, @kitz/core
0.0.1

• ■ @kitz/pkg via @kitz/resource, @kitz/fs, @kitz/env, @kitz/core, @kitz/semver
0.0.1

• ■ @kitz/monorepo via @kitz/resource, @kitz/fs, @kitz/env, @kitz/core
0.0.1

• ■ @kitz/assert via @kitz/core
0.0.1

Tree

release forecast · 39 packages
├─ primary (35)
│  ├─ @kitz/test ·············· 40 commits  c343f5c feat!: use Schema.toTaggedUnion, migrate oxlint 1.55, fix ephemeral SHA (#133)
│  ├─ @kitz/release ··········· 30 commits  8b855b7 feat: add preview publish history command
│  ├─ @kitz/paka ·············· 25 commits  c343f5c feat!: use Schema.toTaggedUnion, migrate oxlint 1.55, fix ephemeral SHA (#133)
│  ├─ @kitz/fs ················ 24 commits  c343f5c feat!: use Schema.toTaggedUnion, migrate oxlint 1.55, fix ephemeral SHA (#133)
│  ├─ @kitz/cli ··············· 20 commits  c343f5c feat!: use Schema.toTaggedUnion, migrate oxlint 1.55, fix ephemeral SHA (#133)
│     ... 30 more
│
└─ cascades (4)
├─ @kitz/conf ·············· via @kitz/mod, @kitz/fs, @kitz/env, @kitz/sch, @kitz/core
├─ @kitz/pkg ··············· via @kitz/resource, @kitz/fs, @kitz/env, @kitz/core, @kitz/semver
├─ @kitz/monorepo ·········· via @kitz/resource, @kitz/fs, @kitz/env, @kitz/core
└─ @kitz/assert ············ via @kitz/core