feat(cli): add auto-update checker and discovery update command#61
Open
matt-chan wants to merge 4 commits into
Open
feat(cli): add auto-update checker and discovery update command#61matt-chan wants to merge 4 commits into
discovery update command#61matt-chan wants to merge 4 commits into
Conversation
Adds a Copilot-CLI-style auto-update flow to the Discovery
supercomputer CLI:
* New `discovery.common.auto_update` module:
* Per-user cache at `~/.discovery/update-check.json` (24h throttle).
* Daemon-thread background refresh on every invocation; never blocks
the foreground command, never raises into user code.
* `atexit`-driven one-line notification when a newer release exists.
* Subdirectory-aware comparison via GitHub's compare API — only
notifies when `utilities/supercomputer-cli/` actually changed,
avoiding false positives from unrelated monorepo activity.
* Discovers a GitHub token from `DISCOVERY_GITHUB_TOKEN`,
`GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` (the repo is
private; without a token the check fails silently).
* Opt-out via `DISCOVERY_NO_UPDATE_CHECK=1` (per-invocation) or
`discovery update --disable` (persistent).
* New `discovery update` Typer command:
* `--check` for check-only mode, `-y` for non-interactive install,
`--enable`/`--disable` to toggle background checks.
* Synchronous check + `uv tool upgrade discovery` to apply.
* Distinct exit codes: 0 success, 1 generic failure, 2 bad usage,
3 network/auth failure.
* Wiring:
* Root callback (and the eager `--version` callback) schedule the
background check and register the at-exit notification.
* `discovery doctor` reports update-checker status + pending updates.
* Update-check helpers are auto-disabled in the test suite so
nothing accidentally hits the live GitHub API.
* Tests: 71 new test cases covering cache I/O, opt-out, staleness,
token resolution, network failures, the notification idempotency
guard, and the full CLI surface.
* README: documents the new command and the auth requirement.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Allows the auto-update checker to compare against a ref other than main — useful for release-candidate channels, fork validation, and end-to-end testing of the update flow without merging to main. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The microsoft/discovery repository is going public, so the auto-update checker no longer needs to assume authentication is required. Changes: * New public API `check_for_update()` raises `UpdateCheckError` with a categorical `reason` (rate_limited / unauthorized / not_found / network / http_error / parse_error / ineligible), so callers can emit tailored hints. The legacy `fetch_update_info()` still returns `None` on any failure for silent-mode callers. * `discovery update` now prints a specific actionable hint per category: rate-limited users are told to set GITHUB_TOKEN or run `gh auth login` to raise the limit from 60/hr to 5000/hr; 404 users are told about DISCOVERY_UPDATE_REPO/REF or force-push scenarios; etc. The old 'repo is private' message is gone. * Module docstring + README reframe authentication as optional and recommended only for shared/CI environments hitting the anonymous rate limit. * Live no-token check verified against octocat/Hello-World (200 OK with no Authorization header). * 7 new tests covering each error classification. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
matt-chan
requested review from
anzaman,
charwen,
ffrachon,
karthikananth,
leijgao,
mukesh-dua and
surajmb
as code owners
github-actions
Bot
added
needs-human-review
✅ Automated Check Results — All checks passedAll structural, schema, content, documentation, and secret scan checks passed. This PR is ready for human review. The maintainers have been automatically requested.
|
The previous `/compare/{base}...{head}` endpoint returned the full
unified-diff patch for every changed file — 70-95% of the payload was
patch text we never read. Live-measured: 99 KB for a 2-commit diff,
1.3 MB for a multi-month stale install.
Two changes:
1. **Switch endpoint** to
`/commits?sha={ref}&path=utilities/supercomputer-cli/&per_page=1`
which returns just the newest CLI-touching commit's metadata. The
server already does the path filtering we used to do client-side,
and `per_page=1` caps the response at a single commit object.
Live: ~3 KB body regardless of how far behind the user is.
2. **HTTP ETag / If-None-Match** conditional GET. The fetcher records
the response's ETag (bound to its URL so changes to
DISCOVERY_UPDATE_REF / _REPO invalidate cleanly) and sends
If-None-Match on subsequent requests. The steady-state-unchanged
case returns 304 Not Modified — ~200 bytes body + ~1 KB headers,
and per GitHub's docs does NOT count against the rate limit.
`UpdateCacheState` gained `etag` + `etag_url` fields (forward-
compatible: older cache files still load).
`check_for_update()` signature changed to return
`tuple[UpdateInfo, str | None]` so callers can participate in the
etag protocol; the silent-failure `fetch_update_info()` wrapper is
unchanged in shape.
Live measurements (against matt-chan/discovery on a real network):
| Scenario | Before | After (fresh) | After (304) |
| --------------------- | --------------- | ------------- | ----------- |
| Tiny update | 99 KB | 3 KB body | 0 body |
| Cold install | 1.3 MB | 3 KB body | 0 body |
| Annual bandwidth/user | ~36 MB - 365 MB | ~440 KB | (free) |
5 new tests cover the etag protocol end-to-end (sent on URL match,
skipped on URL mismatch, 304 handled correctly, worker round-trip
preserves the etag and updates last_checked).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
Bot
added
pr-validation-passed
✅ Automated Check Results — All checks passedAll structural, schema, content, documentation, and secret scan checks passed. This PR is ready for human review. The maintainers have been automatically requested.
|
anzaman
approved these changes
Jun 2, 2026
auto-merge was automatically disabled
June 2, 2026 21:55
Head branch was pushed to by a user without write access
auto-merge was automatically disabled
June 2, 2026 22:05
Pull Request is not mergeable
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
2 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 a Copilot-CLI-style auto-update flow to the Discovery supercomputer CLI: every invocation does a daemon-thread background check (24h-throttled), and emits a single line at exit when a newer release is available. Users can run
discovery updateto apply it.Design
Background check (
discovery.common.auto_update)~/.discovery/update-check.jsoncache. If it's stale (>24h) a daemon thread refreshes it asynchronously. Failures are swallowed silently.utilities/supercomputer-cli/. Avoids "your CLI is out of date" noise from unrelated monorepo activity (catalog edits, doc tweaks, other utilities).DISCOVERY_GITHUB_TOKEN,GITHUB_TOKEN,GH_TOKEN, orgh auth tokento raise the rate limit from 60/hr to 5000/hr — no setup required for most developers.discovery updatecommanddiscovery update— interactive check + confirm + installdiscovery update --check— check only (exit 0 = up to date, 3 = network/auth failure)discovery update -y— install without confirmationdiscovery update --enable/--disable— toggle persistent background checksInstalls are applied via
uv tool upgrade discovery. On any failure the CLI prints a categorized hint (rate-limited → suggestsGITHUB_TOKENorgh auth login; 404 → points atDISCOVERY_UPDATE_REPO/REF; network → suggests checking proxy/DNS).Environment toggles
DISCOVERY_NO_UPDATE_CHECK=1DISCOVERY_GITHUB_TOKEN,GITHUB_TOKEN,GH_TOKENDISCOVERY_UPDATE_REF=<ref>DISCOVERY_UPDATE_REPO=<owner/name>Other surfaces
discovery doctorgained a section reporting cache state and any pending update.api.github.com.End-to-end verification
Done against my fork (
matt-chan/discovery) usingDISCOVERY_UPDATE_REPO/REFto simulate "real" upstream activity without merging an extra commit tomain. Flow:uv tool install discovery --from "git+https://github.com/matt-chan/discovery.git@feat/cli-auto-update#subdirectory=utilities/supercomputer-cli/discovery"→ installed at1633c830749f5010) on the same branchdiscovery update --checkcorrectly reported the new commit:discovery update -yranuv tool upgrade discovery, refetched the branch, installed the new SHAdiscovery --versionthen reported0.1.0+g749f5010discovery update --checkreported "You are on the latest version" (idempotency guard verified)The no-token path was separately verified anonymously against
octocat/Hello-World(200 OK, noAuthorizationheader).Test coverage
71 new test cases in
tests/test_auto_update.pyandtests/test_cli_update.py, covering:gh auth token→ none)rate_limited,unauthorized,not_found,network,http_error,parse_error,ineligible)uvmissing → typedUpgradeError--versioneager-callback wiring (regression test for an early bug where--versionexited before the auto-update was armed)Full suite: 427 passed (excluding 10 pre-existing failures from a missing
tests/artifacts/response.jsonfixture, unrelated to this change).ruff checkandmypy --exclude .venvclean on all changed files.Out of scope / future work
discovery update --rollback) — could re-pin to the prior commit recorded incurrent_at_check.DISCOVERY_UPDATE_REFis the building block; a~/.discovery-sc-configsetting could persist the choice.