feat(cli): tell interactive users when a newer release exists

[cjroebuck]

The CLI had no way of telling users a newer release was out. urlbox upgrade existed, but it ran the package manager blind. This adds a once-a-day "new version" notice, makes upgrade check before acting, and has doctor report available updates.

New-version notice

After a command finishes, interactive users may see one faint line on stderr:

A new version of urlbox is available: 1.2.0 → 1.3.0. Run `urlbox upgrade` to update.

• Source: the GitHub releases API, the same place every installer downloads from. The answer is cached for 24h in update-check.json next to config.json, so it costs at most one request a day.
• Cost: the check runs while the command runs, with a 2s cap. A failed check is silent and still recorded, so an offline machine waits a day before trying again.
• When it shows: text output with a terminal on stderr only. It never shows for JSON, quiet, --jq or piped output, when CI is set, or for local dev builds. It's also skipped for upgrade and shell completion.
• Opt-out: URLBOX_NO_UPDATE_NOTIFIER=1.

urlbox upgrade

• Checks for the latest release first. If you're already on it, it says so and doesn't run the package manager.
• Otherwise it prints Upgrading urlbox 1.2.0 → 1.3.0, and the summary becomes Upgraded 1.2.0 → 1.3.0 via Homebrew.
• The envelope gains latestVersion and upToDate. Both are omitted if the lookup fails, and a failed lookup never blocks the upgrade.
• Fix: it now follows the PATH symlink to the real binary. Before, Intel-Mac Homebrew installs (/usr/local/bin/urlbox → Cellar) weren't detected and got manual instructions instead of an upgrade.

urlbox doctor

The version check now says 1.2.0 (1.3.0 available) as a warning, or (latest). A failed lookup stays ok, so doctor still works as a CI health check and won't fail on GitHub rate limits.

Version comparison

• New internal/update package: semver comparison, the GitHub lookup, and the cache.
• Pre-releases are never offered as upgrades.
• make build stamps git describe versions like v1.2.0-1-gc9d96d6-dirty, which means a commit after the tag. Those are treated as unversioned, so local builds are never told to "upgrade" backwards to 1.2.0.

Docs

• README: a new "Staying up to date" section, and the Install block now lists curl -fsSL https://cli.urlbox.com/install.sh | sh. That host is new (urlbox/urlbox-devops#863) and serves scripts/install.sh from the latest release tag.
• CHANGELOG: entry under Unreleased.
• skills/SKILL.md: the upgrade row is updated.

Testing

• make ci passes: gofumpt, golangci-lint v2.11.4 with 0 issues, go test -race ./..., build, and the surface check. SURFACE.txt is unchanged, since there are no new flags.
• New tests cover: semver edge cases, the GitHub response shape and errors, cache round-trip, file mode and staleness, every notice gate, the notice printing after a failed command, upgrade being a no-op when current, upgrade naming its target, a failed check still upgrading, symlink detection, and doctor's version states.
• End to end: a binary stamped v1.1.0, run against the real GitHub API, printed the 1.1.0 → 1.2.0 notice and wrote the cache. The next run used the cache. JSON, piped and opted-out runs were silent, and doctor warned. The GitHub lookup took about 0.7s.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EseBeLTnUNujV1szk76ttH