specfact upgrade succeeds but pipx launcher can stay stale/broken

[danieldekay]

Summary

specfact upgrade reports success, but the installed specfact launcher can remain stale and still point to an old pipx venv path. This leaves specfact broken (or effectively old) until a manual reinstall.

Environment

• OS: macOS
• Shell: zsh
• pipx --version: 1.12.0
• SpecFact before upgrade command output: SpecFact CLI - v0.46.25
• Update check reports latest as 0.46.28

Reproduction

1. Run:

   specfact upgrade

2. Confirm updater output:
   • detects pipx
   • runs pipx upgrade specfact-cli
   • reports success and says already latest 0.46.28
3. Run:

   specfact --version

Actual result

Launcher still references an old path and fails (or appears stuck on old runtime depending on shell/path state), e.g.:

/Users/<user>/.local/bin/specfact: line 2: /Users/<user>/Library/Application Support/pipx/venvs/specfact-cli/bin/python: No such file or directory

The script content showed stale exec path:

'''exec' '/Users/<user>/Library/Application Support/pipx/venvs/specfact-cli/bin/python' "$0" "$@"

Expected result

After specfact upgrade, specfact --version should reliably use the upgraded runtime and launch successfully without requiring manual repair.

Workaround

pipx reinstall specfact-cli

After reinstall, launcher is corrected and specfact --version returns 0.46.28.

Suggestion

When installation method is pipx, if pipx upgrade reports "already latest", the upgrader could:

• validate launcher integrity by invoking specfact --version
• if launcher is broken/stale, run pipx reinstall specfact-cli (or provide a clear remediation message)

[danieldekay]

Follow-up with confirmed root cause + stable remediation from local repro:\n\n1. Root cause: stale/broken pipx launchers after pipx path migration caused inconsistent SpecFact runtime resolution across terminals.\n2. Observed symptom: updater/command banners could differ across sessions (e.g., older banner shown in one shell while installed package was newer).\n3. Verified state checks: /Users/danieldekay/.local/bin/specfact, launcher shebang path, and direct venv invocation all aligned after repair.\n4. Durable fix: uninstalled ansible-builder! ✨ 🌟 ✨
installed package ansible-builder 3.1.1, installed using Python 3.14.5
These apps are now available
- ansible-builder
uninstalled poetry! ✨ 🌟 ✨
installed package poetry 2.4.1, installed using Python 3.14.5
These apps are now available
- poetry
uninstalled molecule! ✨ 🌟 ✨
installed package molecule 26.4.0, installed using Python 3.14.5
These apps are now available
- molecule
uninstalled virtualenvwrapper! ✨ 🌟 ✨
installed package virtualenvwrapper 6.1.1, installed using Python 3.14.5
These apps are now available
- virtualenvwrapper.sh
- virtualenvwrapper_lazy.sh
uninstalled pre-commit! ✨ 🌟 ✨
installed package pre-commit 4.6.0, installed using Python 3.14.5
These apps are now available
- pre-commit
uninstalled specfact-cli! ✨ 🌟 ✨
installed package specfact-cli 0.46.28, installed using Python 3.14.5
These apps are now available
- specfact
- specfact-cli (or minimally uninstalled specfact-cli! ✨ 🌟 ✨
installed package specfact-cli 0.46.28, installed using Python 3.14.5
These apps are now available
- specfact
- specfact-cli) to rebuild launchers/shims.\n5. Post-fix verification:\n - SpecFact CLI version 0.46.28 -> \n - SpecFact CLI - v0.46.28
⏱️ Started: 2026-05-31 21:54:22
Checking for updates...
✓ You're up to date! (version 0.46.28)

✓ Finished: 2026-05-31 21:54:22 | Duration: 0.10s -> \n\nSuggestion: after specfact-cli is already at latest version 0.46.28 (location:
/Users/danieldekay/.local/pipx/venvs/specfact-cli), run a launcher integrity check (SpecFact CLI version 0.46.28). If launcher is stale/broken, prompt or auto-run uninstalled specfact-cli! ✨ 🌟 ✨
installed package specfact-cli 0.46.28, installed using Python 3.14.5
These apps are now available
- specfact
- specfact-cli.

[danieldekay]

Correction (previous comment was mangled by shell interpolation). Here is the clean verified update:

1. Root cause: stale/broken pipx launchers after pipx path migration caused inconsistent SpecFact runtime resolution across terminals.
2. Observed symptom: updater/command banners could differ across sessions (e.g., older banner shown in one shell while installed package was newer).
3. Verified checks after repair:
   • which -a specfact resolves to ~/.local/bin/specfact
   • launcher shebang points to ~/.local/pipx/venvs/specfact-cli/bin/python
   • direct venv command and PATH command return same version
4. Durable remediation:
   • minimal: pipx reinstall specfact-cli
   • global cleanup: pipx reinstall-all
5. Post-fix verification:
   • specfact --version -> 0.46.28
   • specfact upgrade -> You're up to date! (version 0.46.28)

Suggestion for SpecFact upgrader hardening:

• After pipx upgrade specfact-cli, run an integrity check (specfact --version).
• If broken/stale, prompt or auto-run pipx reinstall specfact-cli.

[danieldekay]

Additional confirmed finding from fresh-terminal repro:

1. Root cause was not only pipx launcher staleness; there was also environment shadowing.
2. The project virtualenv had its own specfact executable at version 0.46.25:
   • ~/.venv/bin/specfact (project-local)
3. In activated shells, that local executable took precedence over pipx and produced the old banner (SpecFact CLI - v0.46.25).
4. Global pipx install was already healthy at 0.46.28.

Final remediation used:

1. Remove project-local shadow package:
   • uv pip uninstall --python .venv/bin/python specfact-cli
2. Keep canonical install via pipx.

Post-fix verification:

1. With and without venv activation, command -v specfact resolves to ~/.local/bin/specfact.
2. specfact --version returns 0.46.28.
3. specfact upgrade banner starts at v0.46.28 and reports up to date.

This may be useful to document as an additional troubleshooting branch: check for virtualenv shadowing before assuming updater failure.

[djm81]

@danieldekay Thanks for all the detailed information! Very useful, I'm distilling that into a global upgrade to avoid these kind of issues in future. Highly appreciated.