feat(cli): warn when a newer spec-kit release is available (#1320) by ATelbay · Pull Request #2212 · github/spec-kit

ATelbay · 2026-04-14T07:58:24Z

Summary

Addresses #1320 — the CLI now prints a one-line upgrade hint on launch when a newer release is available. Suppressed for non-interactive shells, CI=1, or SPECIFY_SKIP_UPDATE_CHECK=1. Cached for 24h in the platform user-cache dir. Every network / parse failure is swallowed — the user's command is never blocked.

Motivation

Observed in the wild: users running older CLIs (for example v0.3.0 still installed from PyPI, or v0.4.2 as in #2185) hit No matching release asset found for claude when they try specify init --ai claude. The legacy asset-download path was removed in the Stage 6 migration (#2063) and the release workflow stopped producing those assets starting v0.4.5, so old clients have no recovery path and no signal that the fix is to upgrade the CLI. A launch-time update warning turns this silent failure into actionable guidance.

This PR implements the spec in #1320:

Check latest release on launch
Display upgrade command
Env-var opt-out
Graceful offline handling
Cache ≤ 1 check per 24h

Changes

`src/specify_cli/init.py`

New private helpers (near get_speckit_version()):
- _parse_version_tuple() — tolerant parser (drops PEP 440 pre/post/dev/local segments)
- _update_check_cache_path() / _read_update_check_cache() / _write_update_check_cache() — JSON cache in platformdirs.user_cache_dir(\"specify-cli\")
- _fetch_latest_version() — urllib.request GET with 2s timeout; never raises
- _should_skip_update_check() — env-var / CI / non-TTY guard
- _check_for_updates() — top-level wrapper; all errors swallowed
callback() invokes _check_for_updates() for any non-version subcommand (version already surfaces the installed version, so we skip to avoid double-printing).
No new third-party deps — platformdirs is already a declared dependency.

`tests/test_update_check.py`

25 new tests covering:

Version-tuple parsing (happy paths, PEP 440 tails, garbage input)
Cache read/write (fresh, stale, missing, corrupt)
urlopen success / network error / malformed JSON / missing tag
End-to-end helper behavior: warning text, no-op when up-to-date, cache-hit skips network, network failure is silent, SPECIFY_SKIP_UPDATE_CHECK=1 short-circuits

`CHANGELOG.md`

Entry under new ## [Unreleased] section.

`docs/installation.md`

Short "Update Notifications" subsection listing the opt-out conditions.

Test plan

uv run pytest tests/test_update_check.py — 25 passed
uv run pytest — full suite: 1299 passed, 20 skipped, 1 failed. The single failure (tests/integrations/test_cli.py::TestForceExistingDirectory::test_without_force_errors_on_existing_dir) also fails on unmodified main — it's a pre-existing brittleness where Rich wraps already exists across panel lines. Not caused by this PR.
Manual smoke test — simulated outdated version, cache miss, verified warning text and cache write
SPECIFY_SKIP_UPDATE_CHECK=1 uv run specify --help — banner renders, no warning, no crash

Manual warning output

⚠  A new spec-kit version is available: v0.6.2 (you have v0.3.0)
   Upgrade: uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@v0.6.2
   (set SPECIFY_SKIP_UPDATE_CHECK=1 to silence this check)

Notes for reviewers

Opened as Draft per the CONTRIBUTING guidance on larger changes. The feature scope matches the maintainer-spec'd issue #1320 verbatim; happy to split, pare back, or rework before un-drafting if there's a preferred approach. Also related (but out of scope here): #2185 is a direct downstream symptom of the same class of problem this PR mitigates.

Print a one-line upgrade hint on every launch when the installed CLI is older than the latest GitHub release. Cached for 24h and suppressed when SPECIFY_SKIP_UPDATE_CHECK is set, CI=1 is set, or stdout is not a TTY. Any network / parse failure is swallowed — the command the user invoked is never blocked. Closes github#1320.

Copilot

Pull request overview

Adds a best-effort “new version available” notice to the specify CLI startup flow to help users discover they need to upgrade when running an outdated specify-cli release.

Changes:

Implement a cached (24h) GitHub release check in specify_cli.__init__ and print an upgrade hint when a newer tag is available.
Add a new tests/test_update_check.py suite covering version parsing, cache behavior, network/JSON failure swallowing, and end-to-end output behavior.
Document update notifications in docs/installation.md and add an Unreleased changelog entry.

Show a summary per file

File	Description
`src/specify_cli/__init__.py`	Adds update-check helpers and invokes the check from the Typer callback.
`tests/test_update_check.py`	New tests validating parsing/caching/network handling and printed warning behavior.
`docs/installation.md`	Documents update-check behavior and opt-out/skip conditions.
`CHANGELOG.md`	Adds an Unreleased entry describing the new update warning behavior.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

src/specify_cli/init.py:1648

_write_update_check_cache uses path.write_text(...) without an explicit encoding. For consistency with other file writes/reads in this module and to avoid platform default-encoding issues, specify encoding="utf-8" here as well.

        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps({"checked_at": time.time(), "latest": latest}))
    except Exception:

Files reviewed: 4/4 changed files
Comments generated: 5

mnriem

Please address Copilot feedback and be aware that this MUST be an opt-in and NOT an opt-out as air-gapped / network-constrained environments will not have access to GitHub perse

Addresses CHANGES_REQUESTED on github#2212. The update check now only runs when SPECIFY_ENABLE_UPDATE_CHECK=1 (or true/yes/on) is set, so air-gapped and network-constrained environments never attempt to reach GitHub by default. Also addresses the Copilot review findings: - Widen `_parse_version_tuple(version: str | None)` signature and guard with `isinstance` (matches what the tests were already passing). - Use explicit `encoding="utf-8"` for the update-check cache read and write, consistent with the rest of the module. - Reword the "never blocks" claim in the module comment and in docs/installation.md to "never fails the command", and note the possible small startup delay on cache miss. - Include the `None` `invoked_subcommand` case (bare `specify` launch) so the check runs alongside the banner when opted in. Tests: - Replace the opt-out short-circuit test with an opt-in default-off test. - Add tests asserting `SPECIFY_ENABLE_UPDATE_CHECK=1` allows the fetch and that `CI=1` still suppresses it. - `uv run pytest tests/test_update_check.py` → 27 passed. - Full suite: 1301 passed, 20 skipped, 1 pre-existing unrelated failure (`test_without_force_errors_on_existing_dir`, Rich panel-wrap on `already exists`).

# Conflicts: # CHANGELOG.md

Copilot

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 4/4 changed files
Comments generated: 2

Copilot · 2026-04-21T13:09:31Z

+def _should_skip_update_check() -> bool:
+    # Opt-in only: skip unless the user has explicitly enabled the check.
+    # Air-gapped / network-constrained environments cannot reach GitHub, so a
+    # default-on network call is a non-starter; keeping this off by default
+    # also means users never pay the fetch latency unless they asked for it.
+    if os.environ.get("SPECIFY_ENABLE_UPDATE_CHECK", "").strip().lower() not in ("1", "true", "yes", "on"):
+        return True
+    # Belt-and-suspenders: even when opted in, suppress in CI and when the


The PR description says the update warning is shown by default and suppressed via SPECIFY_SKIP_UPDATE_CHECK=1, but the implementation is opt-in via SPECIFY_ENABLE_UPDATE_CHECK (and there is no SPECIFY_SKIP_UPDATE_CHECK handling). Please reconcile by either updating the PR description/spec or adjusting the skip logic/env-var naming so the documented behavior matches the shipped behavior.

Copilot · 2026-04-21T13:09:32Z

+    def test_ci_suppresses_even_when_opted_in(self, monkeypatch, tmp_path):
+        """Belt-and-suspenders: CI=1 wins over the opt-in flag."""
+        monkeypatch.setenv("SPECIFY_ENABLE_UPDATE_CHECK", "1")
+        monkeypatch.setenv("CI", "1")
+
+        fetched = {"called": False}
+
+        def _fetch():
+            fetched["called"] = True
+            return "v99.0.0"
+
+        monkeypatch.setattr("specify_cli._fetch_latest_version", _fetch)
+        monkeypatch.setattr("specify_cli.get_speckit_version", lambda: "0.0.1")
+        monkeypatch.setattr(
+            "specify_cli._update_check_cache_path", lambda: tmp_path / "vc.json"
+        )
+
+        _check_for_updates()
+
+        assert fetched["called"] is False


test_ci_suppresses_even_when_opted_in can pass even if the CI check is removed because sys.stdout.isatty() is often false under pytest capture. Patch sys.stdout.isatty to return True in this test (like the opt-in test does) so it deterministically verifies that CI=1 is the reason the network call is suppressed.

mnriem

Please address Copilot feedback

ATelbay marked this pull request as ready for review April 14, 2026 08:08

ATelbay requested a review from mnriem as a code owner April 14, 2026 08:08

mnriem requested a review from Copilot April 14, 2026 12:05

Copilot started reviewing on behalf of mnriem April 14, 2026 12:05 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

Comment thread src/specify_cli/__init__.py Outdated

Comment thread src/specify_cli/__init__.py

Comment thread docs/installation.md Outdated

Comment thread src/specify_cli/__init__.py

Comment thread src/specify_cli/__init__.py Outdated

mnriem requested changes Apr 14, 2026

View reviewed changes

ATelbay added 2 commits April 21, 2026 12:27

Merge remote-tracking branch 'upstream/main' into feat/update-check-1320

e45a36a

# Conflicts: # CHANGELOG.md

mnriem requested a review from Copilot April 21, 2026 13:05

Copilot started reviewing on behalf of mnriem April 21, 2026 13:06 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

mnriem self-requested a review April 21, 2026 13:13

mnriem requested changes Apr 21, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): warn when a newer spec-kit release is available (#1320)#2212

feat(cli): warn when a newer spec-kit release is available (#1320)#2212
ATelbay wants to merge 3 commits intogithub:mainfrom
ATelbay:feat/update-check-1320

ATelbay commented Apr 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

Copilot AI Apr 21, 2026

Uh oh!

mnriem left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

ATelbay commented Apr 14, 2026

Summary

Motivation

Changes

src/specify_cli/__init__.py

tests/test_update_check.py

CHANGELOG.md

docs/installation.md

Test plan

Manual warning output

Notes for reviewers

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot's findings

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`src/specify_cli/init.py`

`tests/test_update_check.py`

`CHANGELOG.md`

`docs/installation.md`