feat: SDK version-compat gate, health version surface, upgrade nudge#52
Merged
Conversation
Required-version gate via the X-OnePin-Required-Version header (and HTTP 426) for the CLI and programmatic SDK (onepin.make_client); server versions are PEP 440-validated before being pinned into the pip command, and the raw auth path surfaces 426 too. onepin health live/ready now report status + SDK/API/recommended/required versions. Hidden 'onepin upgrade-check' (PyPI source, dual-TTL cache, escalating snooze, --disable, --mark-upgrading) drives a gstack-style /onepin agent-skill upgrade prompt; the CLI never nags on stderr. AGENTS.md records the new hand-rolled module + the __init__ re-export patch. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
kj-podonos
force-pushed
the
kj-podonos/version-checks
branch
from
537163e to
05661bb
Compare
podonos-eunseo
approved these changes
Jun 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds SDK version-compatibility handling, a richer
onepin health, and a soft upgrade nudge.X-OnePin-Required-Versionoff API responses (and maps a server HTTP 426) → when the installedonepinis below the floor, the CLI stops with a yellow, copy-paste upgrade message + exit 1. Works for the CLI and for programmatic users viaonepin.make_client(...)(a version-gatedOnePinClientthat also corrects a stale bakedUser-Agent). The raw auth path (login/whoami) surfaces 426 too. Server-supplied versions are PEP 440-validated before being interpolated into thepipcommand (no copy-paste injection).onepin health live/readynow reportstatus,SDK version(local),API version(server), and the recommended/required versions.--jsonsupported; unknown sources renderunknown.onepin upgrade-check(PyPI source, daily/dual-TTL cache, escalating snooze,--disable,--mark-upgrading) drives a recurring upgrade prompt via the/onepinagent skill. The CLI itself never nags on stderr.Regen-safety
src/onepin/_version_gate.pyis preserved via.fernignoreand re-exported throughfern/generators.ymladditional_init_exports, sofrom onepin import make_clientsurvivesfern generate. CLI startup stays SDK-free (deferred imports; fast-startup test passes).Backend dependency (graceful degradation)
The gate is inert until the API emits the data — no header / offline PyPI / absent backend all degrade to no-ops, so this is safe to merge ahead of the server work. To activate: the API adds an
X-OnePin-Required-Versionresponse header (from a live-editable config value) and returns 426 with{error.code:"sdk_upgrade_required", required_version, upgrade_url}when the User-Agent version is below the floor.recommendedneeds no backend — it's the newest release on PyPI.Test Coverage
New:
tests/unit/test_version_gate.py,tests/unit/test_update_check.py,tests/cli/test_cli_health.py— gate logic (compare/validate/header parse, injection guard),make_clienthook + UA,upgrade-checkcache/snooze/disable/marker,healthhuman + JSON, required-stop via header and 426, auth-path 426.Reviews
JUST_UPGRADEDaddressed).Test plan
uv run pytest— 295 passedruff check+ruff format --checkcleanmypy -p onepin._clicleanpython -m build— wheel + sdist OK🤖 Generated with Claude Code