Commit Graph
2 Commits
Author SHA1 Message Date
c1dae5adae fix(update-check): skip releases with no files and do not fall back to an uninstallable version (#4560)
## Description

`_select_latest` (`headroom/update_check.py:153-193`) promises the
newest non-yanked release, but it treated a release whose file list is
empty as installable, and when no release was installable it fell back
to `info.version`, which names one of those releases. The update banner
could then advise a version `pip` cannot install. Releases with an empty
file list are now skipped like fully yanked ones, and when `releases`
lists versions but none is installable the function returns `None`; the
`info.version` fallback is kept for a payload with no `releases`. Item 3
of #4546.

Refs #4546

This PR used to carry all three items of #4546; per the
one-logical-change-per-PR rule the other two are now #4562 (null
thinking block) and #4563 (interior blank CSV rows).

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/update_check.py`: skip a release when its file list is empty
or every file is yanked; return `None` instead of the `info.version`
fallback when releases are listed but none is installable.
- `tests/test_update_check.py`:
`test_select_latest_skips_release_with_no_files`,
`test_select_latest_no_fallback_when_every_release_is_unavailable`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# fail before (source at a2d4fe72, new tests kept)
FAILED tests/test_update_check.py::test_select_latest_skips_release_with_no_files  (assert '9.9.9' == '1.0.0')
FAILED tests/test_update_check.py::test_select_latest_no_fallback_when_every_release_is_unavailable

# pass after: tests/test_update_check.py tests/test_update_helpers.py
74 passed

# ruff check / ruff format --check: All checks passed! / 2 files already formatted
```

## Real Behavior Proof

- Environment: Ubuntu (WSL2) on Windows 11, Python 3.12.15, `headroom`
Python source at `a2d4fe72` and at this branch, offline.
- Exact command / steps: `_select_latest({"info": {"version": "1.0.0"},
"releases": {"1.0.0": [{"yanked": False}], "9.9.9": []}},
allow_pre=False)` and `_select_latest({"releases": {"9.9.9": []},
"info": {"version": "9.9.9"}}, allow_pre=False)`.
- Observed result: on `a2d4fe72`: `9.9.9` and `9.9.9`. On this branch:
`1.0.0` and `None`.
- Not tested: whether PyPI's JSON API ever lists a release with no files
(the fix follows the function's own docstring); the full suite and
`mypy`.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A
- Stable/default behavior changed: Only for payloads where every listed
release is uninstallable; the banner then stays quiet instead of naming
an uninstallable version.
- Kill switch / disable path: `HEADROOM_UPDATE_CHECK=off` (existing).
- Unsafe override required: No
- Qualification impact: None expected
- Rollback path: revert this PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
reproduction was run on my machine against a clone of the repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-04 23:19:58 -06:00
Focused Instability 26be2c39cb feat(cli): add headroom update command and release banner (#1088)
## Description

Adds a `headroom update` self-update command and a passive "update
available" banner, so users no longer need to remember the right
`pip`/`pipx`/`uv` incantation for their environment, and long-running
proxies get nudged when they drift behind a release.

Closes #1087

## Type of Change

- [x] New feature (non-breaking change that adds functionality)
- [x] Documentation update

## Changes Made

- `headroom/cli/update.py` — `headroom update` command.
`detect_install_method()` resolves the install (git checkout, editable,
Docker, pipx, uv tool, venv/conda, `pip --user`, externally-managed
system Python per PEP 668, writable global) and builds the matching
upgrade. pip path always uses `sys.executable -m pip` so it can't touch
the wrong interpreter. Refuses with guidance where self-update is
unsafe. Flags: `--check`, `--yes`, `--pre`, `--extras`.
- `headroom/update_check.py` — best-effort PyPI check (stdlib `urllib`,
no new dep). Split into a daemon-thread probe that caches to
`~/.headroom/update_check.json` (≤ once/day) and a cache-only
`format_update_notice()`. Opt-out `HEADROOM_UPDATE_CHECK=off`; skipped
in `--stateless`, CI, Docker, checkouts.
- `headroom/cli/main.py`, `headroom/cli/__init__.py` — register
`update`; fire the background check from the group callback (skipped for
`update`).
- `headroom/cli/proxy.py` — render the one-line notice after the startup
banner (best-effort, never blocks).
- `README.md` — "Updating" section + opt-out env var.
- Tests: `tests/test_update_check.py`, `tests/test_cli_update.py`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest tests/test_update_check.py tests/test_cli_update.py -q
42 passed in 1.63s

$ ruff check headroom/cli/update.py headroom/update_check.py headroom/cli/main.py
All checks passed!

$ mypy headroom/update_check.py headroom/cli/update.py
Success: no issues found in 2 source files
```

## Real Behavior Proof

- Environment: macOS, Python 3.11, source checkout
- Exact command / steps: `python -m headroom.cli update --help`;
`detect_install_method()` in the checkout
- Observed result: command + flags render; in a checkout
`detect_install_method()` returns `kind=checkout, can_self_update=False`
("update with `git pull`") and `format_update_notice()` returns `None`
(dev tree not nagged)
- Not tested: live PyPI fetch and a real pipx/uv-tool upgrade on this
machine (covered by unit tests with mocked `urllib`/`subprocess`)

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Additional Notes

- CHANGELOG.md is release-please-managed, so it is intentionally not
hand-edited (N/A above).
- Update check uses stdlib `urllib` because `httpx` lives only in the
`[proxy]` extra — the base CLI must stay dependency-light.
2026-06-18 11:22:20 -05:00