feat: kit upgrade, update notices, and an attested release pipeline

[imjohnbo]

Follows the spec catch-up stack (#14 through #21), which merged while this was in
progress. Rebased onto main, so this targets main directly.

Release plumbing, not spec catch-up. Three commits: the pipeline, the semver
gate, and the package rename.

What makes a release publish to npm

A pushed version tag, and a manual approval. Nothing else.

npm version patch          # bumps package.json, commits, creates the tag
git push --follow-tags     # pushing the tag starts the workflow

.github/workflows/release.yml runs three jobs.

Job	Runs on	Stops the release when
verify	Node 18, 20, 22	A test fails
verify-package	Once	The version breaks a semver rule, or the tarball does not match the source
publish	After approval	The repacked tarball differs from the verified one

The publish job targets an npm-publish environment. Add a required reviewer to
it, and a pushed tag can no longer ship anything on its own.

A prerelease tag such as v0.1.0-rc.1 also triggers the workflow. It publishes
under the next dist-tag, so a prerelease cannot push kit upgrade users onto an
unstable version.

Attestation

Three checks, each answering a different question.

1. npm provenance. Links the package to this workflow run and commit. Verify
   with npm audit signatures.
2. GitHub artifact attestation. Covers the release asset. Verify with
   gh attestation verify.
3. Source equals tarball. The one that answers the original question.

Layers 1 and 2 prove where a tarball was built. Neither proves the tarball
matches the source. A step between checkout and publish could edit a file and
still produce valid provenance.

kit-cli has no build step and no devDependencies, so the published tarball is the
source. CI proves it: pack the tree, unpack the tarball, diff the two, and fail
the release on any difference.

I verified both assumptions locally before relying on them.

• npm does not normalize package.json when it packs, so the diff is exact.
• npm pack is reproducible here, so the publish job can assert the repacked
  tarball matches the one CI verified.

That assertion is in the workflow. The npm package, the attested artifact, and the
release asset are the same bytes.

publishConfig.provenance is true, so a local npm publish fails rather than
shipping an unattested build. That is deliberate.

Enforcing semantic versioning

npm run check:semver runs four checks. CI runs the same script on every tagged
release.

1. The version is valid semver.
2. The git tag matches package.json.
3. The version is newer than what npm already serves.
4. A breaking change carries a big enough bump.

Check 4 is the only one that enforces the meaning of a version, and it needs a
machine-readable public surface. For a library that would be the exported
symbols. For a CLI it is the command tree: the commands, their arguments, and
their flags. Removing or renaming any of those breaks a caller's script. Adding
one does not.

spec/cli-surface.json holds that surface, 103 commands. A test asserts the
committed snapshot matches the current tree, so a surface change has to be
committed on purpose and shows up in review. On release, the gate reads the
snapshot from the previous tag and compares.

Below 1.0.0 a breaking change needs a minor bump, not a major one. Semver
leaves 0.x unstable, but npm's caret range treats minor as the breaking axis
there, and the ecosystem reads it that way.

I exercised all four paths against a real temporary tag rather than trusting the
unit tests alone:

Change	Bump	Result
Removed a command	patch	Refused, named removed command: kit tags remove-by-email
Removed a command	minor	Allowed
Added a command	patch	Refused
No surface change	patch	Allowed

What this cannot catch. The gate sees shape, not behavior. A flag that keeps
its name and changes its meaning, a changed output format, or a changed exit code
will all pass. Those still need a human. docs/RELEASING.md says so plainly, so
nobody mistakes the gate for a guarantee it does not give.

Action versions

Every pin in my first draft was stale. I had assumed rather than checked. Queried
against the API:

Action	Was	Now
checkout	v4	v7.0.1
setup-node	v4	v7.0.0
upload-artifact	v4	v7.0.1
download-artifact	v4	v8.0.1
attest-build-provenance	v2	v4.2.2
github-script	v7	v9.0.0

All six are pinned to a commit SHA with the version in a trailing comment. A tag
is mutable, so @v7 is a promise from the action's owner rather than a guarantee,
and these jobs hold id-token: write. Dependabot reads the version comment and
keeps it in step with the SHA.

This also fixes test.yml and check-api-spec.yml, which carried the same stale
pins.

Version 0.0.1, and the blocker it found

The project is pre-release, so it starts at 0.0.1 rather than 1.0.0.

Setting that immediately tripped the new gate. The unscoped kit-cli on npm
belongs to another author, since 2015, currently at 0.0.4. Check 3 refused
0.0.1 as not newer than the published 0.0.4. The gate earned its keep before
the first release.

The package therefore publishes as @imjohnbo/kit-cli. Only package.json
changed, because src/package-info.js reads the name. The installed command is
still kit, because bin names it separately. I verified the registry serves a
scoped packument at an unencoded path, so the update check still resolves.

Moving to @kit/cli later is one edit plus a deprecation on the old name. The
runbook documents that path.

kit upgrade

kit upgrade              # detect the installer, delegate to it
kit upgrade --check      # report the newest version, install nothing
kit upgrade --dry-run    # print the command that would run

upgrade detects how the CLI was installed, then runs that package manager. It
never downloads or unpacks a release itself.

That is the security decision worth reviewing. Delegating keeps npm's integrity
check and provenance verification in the trust path. A bespoke updater that
fetched a tarball and unpacked it over itself would replace all of that with code
nobody audits. Running from a git checkout is detected and reported, since
npm link is what the README describes for development.

The command table holds argv arrays, never shell strings, and a test asserts no
entry carries a shell metacharacter.

Update notices

A one-line notice on stderr when a newer version exists.

It reads a cached version number from config, so it never delays a command and
never fails one. A background request refreshes the cache at most once a day. It
goes to stderr, which keeps --format json parseable, matching the
printWarnings decision from part 5.

It makes an outbound request, so it is documented and easy to turn off:

kit config set-update-check false
export KIT_NO_UPDATE_CHECK=1

It also stays off whenever CI is set. Flagging the default: the check is on
out of the box. Update notices are themselves a security mechanism, so that felt
right, but it is a one-line change if you would rather ship it off.

Version and name drift

package.json is the only place either value lives. src/package-info.js reads
both at run time.

src/package-info.js exists as its own module rather than living in
program.js, because commands need these values and program.js imports the
commands. Putting it there created an import cycle.

isNewer moved to src/semver.js so the release script can import version logic
without starting the config store. One implementation, three callers.

Guards against a second copy appearing:

• a test asserting no file in src/ hardcodes the version string
• a test asserting kit --version equals package.json
• tests asserting the registry URL and the upgrade target derive from the name
• a CI step repeating the version check, so a mismatched tag cannot publish

src/config.js keeps its own fixed projectName. That names the directory
holding a user's credentials, so it must not follow the package name.

Two bugs fixed on the way

package.json pointed at github.com/yourusername/kit-cli. npm provenance
rejects a repository URL that does not match the publishing repo. Releases would
have failed at the last step.

npm test wrote to the real config. The suite mutated
~/Library/Preferences/kit-cli-nodejs/config.json, so running it clobbered the
developer's stored API key and OAuth tokens. conf also rewrites the whole file
on every set, so parallel test files lost each other's writes. That is the flake
I saw earlier in this work and wrongly dismissed as truncated output. The new
update-check tests made it reproduce every time.

config.js now honors KIT_CONFIG_DIR, which also gives users one profile per
Kit account. scripts/run-tests.js gives each test file its own config
directory. npm test runs through that script and prints the same # tests and
# pass summary lines as before, so CI needs no change.

Review notes

Tests: 378 before, 497 after.

docs/RELEASING.md is the runbook. It covers the one-time setup, the checklist,
how a user verifies a release, how the semver gate reads a change, what the gate
cannot catch, action pinning, and what to do when a bad version ships. It also
records why the no-build-step property matters, so nobody adds a build step
without seeing what it costs.

Nothing here is spec catch-up. It was written on top of the stack because it needs
src/program.js from #21.

Before merging

Two things need doing outside this PR.

1. Create the npm-publish GitHub environment and add a required reviewer.
2. Set up npm trusted publishing for @imjohnbo/kit-cli, or store an automation
   token in that environment as NPM_TOKEN.