devstuff 2.10.0__tar.gz → 2.11.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. {devstuff-2.10.0 → devstuff-2.11.0}/CHANGELOG.md +16 -0
  2. {devstuff-2.10.0 → devstuff-2.11.0}/CLAUDE.md +23 -1
  3. {devstuff-2.10.0 → devstuff-2.11.0}/PKG-INFO +59 -1
  4. {devstuff-2.10.0 → devstuff-2.11.0}/README.md +58 -0
  5. devstuff-2.11.0/docs/ROADMAP.md +177 -0
  6. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/README.md +1 -0
  7. devstuff-2.11.0/docs/specs/outdated/development-plan.md +78 -0
  8. devstuff-2.11.0/docs/specs/outdated/specifications.md +169 -0
  9. devstuff-2.11.0/docs/specs/outdated/stack-decisions.md +97 -0
  10. {devstuff-2.10.0 → devstuff-2.11.0}/pyproject.toml +1 -1
  11. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/cli.py +2 -0
  12. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/help_cmd.py +1 -0
  13. devstuff-2.11.0/src/dev_setup/commands/outdated_cmd.py +141 -0
  14. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/update_cmd.py +2 -20
  15. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/generic.py +107 -20
  16. devstuff-2.11.0/src/dev_setup/updates.py +148 -0
  17. devstuff-2.11.0/tests/test_outdated_cmd.py +331 -0
  18. devstuff-2.11.0/tests/test_update_notes.py +77 -0
  19. devstuff-2.11.0/tests/test_updates.py +217 -0
  20. devstuff-2.11.0/tests/test_uv_probes.py +212 -0
  21. {devstuff-2.10.0 → devstuff-2.11.0}/uv.lock +1 -1
  22. {devstuff-2.10.0 → devstuff-2.11.0}/.claude/skills/run-stuff/SKILL.md +0 -0
  23. {devstuff-2.10.0 → devstuff-2.11.0}/.claude/skills/run-stuff/smoke.sh +0 -0
  24. {devstuff-2.10.0 → devstuff-2.11.0}/.github/codex/review.md +0 -0
  25. {devstuff-2.10.0 → devstuff-2.11.0}/.github/workflows/agent.yml +0 -0
  26. {devstuff-2.10.0 → devstuff-2.11.0}/.github/workflows/bump.yml +0 -0
  27. {devstuff-2.10.0 → devstuff-2.11.0}/.github/workflows/ci.yml +0 -0
  28. {devstuff-2.10.0 → devstuff-2.11.0}/.github/workflows/publish.yml +0 -0
  29. {devstuff-2.10.0 → devstuff-2.11.0}/.github/workflows/test-installs.yml +0 -0
  30. {devstuff-2.10.0 → devstuff-2.11.0}/.gitignore +0 -0
  31. {devstuff-2.10.0 → devstuff-2.11.0}/dev/Dockerfile +0 -0
  32. {devstuff-2.10.0 → devstuff-2.11.0}/dev/Dockerfile.ci +0 -0
  33. {devstuff-2.10.0 → devstuff-2.11.0}/dev/Makefile +0 -0
  34. {devstuff-2.10.0 → devstuff-2.11.0}/dev/docker-compose.yml +0 -0
  35. {devstuff-2.10.0 → devstuff-2.11.0}/devstuff +0 -0
  36. {devstuff-2.10.0 → devstuff-2.11.0}/docs/github-agent.md +0 -0
  37. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/agent/development-plan.md +0 -0
  38. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/agent/specifications.md +0 -0
  39. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/agent/stack-decisions.md +0 -0
  40. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/ansible-config/development-plan.md +0 -0
  41. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/ansible-config/specifications.md +0 -0
  42. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
  43. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/bat-config/development-plan.md +0 -0
  44. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/bat-config/specifications.md +0 -0
  45. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/bat-config/stack-decisions.md +0 -0
  46. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/commitizen-config/development-plan.md +0 -0
  47. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/commitizen-config/specifications.md +0 -0
  48. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
  49. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/docker-config/development-plan.md +0 -0
  50. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/docker-config/specifications.md +0 -0
  51. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/docker-config/stack-decisions.md +0 -0
  52. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/lazygit-config/development-plan.md +0 -0
  53. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/lazygit-config/specifications.md +0 -0
  54. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
  55. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/precommit-config/development-plan.md +0 -0
  56. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/precommit-config/specifications.md +0 -0
  57. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
  58. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/starship-config/development-plan.md +0 -0
  59. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/starship-config/specifications.md +0 -0
  60. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/starship-config/stack-decisions.md +0 -0
  61. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/uv-backbone/development-plan.md +0 -0
  62. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/uv-backbone/specifications.md +0 -0
  63. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
  64. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/verbose-mode/development-plan.md +0 -0
  65. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/verbose-mode/specifications.md +0 -0
  66. {devstuff-2.10.0 → devstuff-2.11.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
  67. {devstuff-2.10.0 → devstuff-2.11.0}/install.sh +0 -0
  68. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/__init__.py +0 -0
  69. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/__main__.py +0 -0
  70. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/__init__.py +0 -0
  71. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/approval.py +0 -0
  72. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/bridges.py +0 -0
  73. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/catalog.py +0 -0
  74. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/completion.py +0 -0
  75. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/config.py +0 -0
  76. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/loop.py +0 -0
  77. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/ollama.py +0 -0
  78. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/preflight.py +0 -0
  79. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/primitives.py +0 -0
  80. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/registry.py +0 -0
  81. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/sandbox.py +0 -0
  82. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/session.py +0 -0
  83. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/transcript.py +0 -0
  84. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent/wizard.py +0 -0
  85. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent_tools.schema.json +0 -0
  86. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/agent_tools.yaml +0 -0
  87. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/base.py +0 -0
  88. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/catalog.py +0 -0
  89. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/__init__.py +0 -0
  90. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/add_cmd.py +0 -0
  91. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/agent_cmd.py +0 -0
  92. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
  93. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/configure_cmd.py +0 -0
  94. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/delete_cmd.py +0 -0
  95. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/docs_cmd.py +0 -0
  96. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
  97. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/functions_cmd.py +0 -0
  98. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/install_cmd.py +0 -0
  99. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/links_cmd.py +0 -0
  100. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/list_cmd.py +0 -0
  101. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/remove_cmd.py +0 -0
  102. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/run_cmd.py +0 -0
  103. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/commands/skills_cmd.py +0 -0
  104. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/__init__.py +0 -0
  105. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
  106. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/detect.py +0 -0
  107. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/model.py +0 -0
  108. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/render.py +0 -0
  109. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/validate.py +0 -0
  110. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
  111. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/__init__.py +0 -0
  112. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/detect.py +0 -0
  113. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/model.py +0 -0
  114. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/preview.py +0 -0
  115. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/render.py +0 -0
  116. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/wizard.py +0 -0
  117. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
  118. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
  119. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/model.py +0 -0
  120. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/render.py +0 -0
  121. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
  122. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
  123. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/__init__.py +0 -0
  124. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/detect.py +0 -0
  125. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/model.py +0 -0
  126. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/render.py +0 -0
  127. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/validate.py +0 -0
  128. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/wizard.py +0 -0
  129. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
  130. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
  131. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/model.py +0 -0
  132. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/render.py +0 -0
  133. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
  134. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
  135. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
  136. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/detect.py +0 -0
  137. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/model.py +0 -0
  138. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/render.py +0 -0
  139. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/validate.py +0 -0
  140. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
  141. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
  142. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
  143. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/__init__.py +0 -0
  144. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/fonts.py +0 -0
  145. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/icons.py +0 -0
  146. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/model.py +0 -0
  147. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/preview.py +0 -0
  148. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/render.py +0 -0
  149. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/wizard.py +0 -0
  150. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/doctor.py +0 -0
  151. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/function_runner.py +0 -0
  152. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/functions.schema.json +0 -0
  153. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/functions.yaml +0 -0
  154. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/functions_catalog.py +0 -0
  155. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/functions_registry.py +0 -0
  156. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/links.schema.json +0 -0
  157. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/links.yaml +0 -0
  158. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/links_catalog.py +0 -0
  159. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/links_registry.py +0 -0
  160. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/registry.py +0 -0
  161. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/tools.yaml +0 -0
  162. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/ui.py +0 -0
  163. {devstuff-2.10.0 → devstuff-2.11.0}/src/dev_setup/verbose.py +0 -0
  164. {devstuff-2.10.0 → devstuff-2.11.0}/tests/__init__.py +0 -0
  165. {devstuff-2.10.0 → devstuff-2.11.0}/tests/integration/__init__.py +0 -0
  166. {devstuff-2.10.0 → devstuff-2.11.0}/tests/integration/conftest.py +0 -0
  167. {devstuff-2.10.0 → devstuff-2.11.0}/tests/integration/test_agent_smoke.py +0 -0
  168. {devstuff-2.10.0 → devstuff-2.11.0}/tests/integration/test_agent_tui.py +0 -0
  169. {devstuff-2.10.0 → devstuff-2.11.0}/tests/integration/test_commitizen_config.py +0 -0
  170. {devstuff-2.10.0 → devstuff-2.11.0}/tests/integration/test_tools.py +0 -0
  171. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_agent.py +0 -0
  172. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_agent_completion.py +0 -0
  173. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_agent_loop.py +0 -0
  174. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_agent_sandbox.py +0 -0
  175. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_agent_tools.py +0 -0
  176. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_agent_wizard.py +0 -0
  177. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_catalog.py +0 -0
  178. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_ansible.py +0 -0
  179. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_bat.py +0 -0
  180. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_commitizen.py +0 -0
  181. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_docker.py +0 -0
  182. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_lazygit.py +0 -0
  183. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_precommit.py +0 -0
  184. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_reptyr.py +0 -0
  185. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_configure_starship.py +0 -0
  186. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_doctor.py +0 -0
  187. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_functions.py +0 -0
  188. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_generic.py +0 -0
  189. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_links.py +0 -0
  190. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_registry.py +0 -0
  191. {devstuff-2.10.0 → devstuff-2.11.0}/tests/test_verbose.py +0 -0
@@ -1,3 +1,19 @@
1
+ ## v2.11.0 (2026-10-10)
2
+
3
+ ### Features
4
+
5
+ - **outdated**: add `devstuff outdated`, a read-only update report
6
+ - **updates**: classify tools into five honest states
7
+
8
+ ### Bug Fixes
9
+
10
+ - **update**: a failed uv probe is unknown, not current; add UpdateStatus.note
11
+ - **update**: probe uv once per run instead of once per tool
12
+
13
+ ### Refactors
14
+
15
+ - **update**: move the update collector into a shared module
16
+
1
17
  ## v2.10.0 (2026-10-10)
2
18
 
3
19
  ### Features
@@ -64,8 +64,9 @@ src/dev_setup/
64
64
  ├── links.yaml # Bundled link catalog (+ links_catalog.py / links_registry.py / links.schema.json)
65
65
  ├── ui.py # Rich console + questionary wrappers (spinners, prompts, styled output)
66
66
  ├── verbose.py # Process-wide -v/-vv level + the stderr logger built on it
67
+ ├── updates.py # Update probing + the five-state classifier, shared by `update` and `outdated`
67
68
  ├── configure/ # Per-tool setup wizards (see "Configurators" below)
68
- └── commands/ # One Click command per file: list, install, remove, add, delete, docs, catalog
69
+ └── commands/ # One Click command per file: list, install, remove, update, outdated, add, delete, docs, catalog
69
70
  ```
70
71
 
71
72
  **Catalog precedence** (`catalog.load_effective_catalog`): bundled `tools.yaml` loads first →
@@ -133,6 +134,27 @@ through call signatures. Three things about it are load-bearing:
133
134
  streaming output. At `-vv` script bodies run under `bash -x`, *except* eval-mode function
134
135
  scripts — `set -x` there would persist in the caller's interactive shell.
135
136
 
137
+ **Update probing and `outdated`** (`updates.py`, spec in `docs/specs/outdated/`): `update`'s picker
138
+ and `devstuff outdated` share one collector and one classifier. Things that are load-bearing:
139
+ - **`available is False` must mean "the probe positively found nothing newer"** — never "the probe
140
+ failed". Every failure path in an `_UPDATE_CHECKERS` function returns an *empty* status (plus a
141
+ `note` saying why), which classifies as `unknown`. The uv checker once ignored its exit code:
142
+ `uv tool list --outdated` exits 2 offline with empty stdout, which read as every tool being current.
143
+ The unit tests had only faked a *successful* probe; it took running the real binary with the network
144
+ blocked to find it. A new checker needs a test for its failure path, not just its happy one.
145
+ - **`unsupported` is decided from the install *type*** (`generic.supports_update_check`), not from an
146
+ empty `UpdateStatus` — a `bash` tool and a failed `npm` probe return the same empty status and need
147
+ different remedies. Neither may ever render as `current`; there is a test that breaks the renderer to
148
+ prove the test can fail.
149
+ - **Shared probes use `_once`, not `functools.lru_cache`.** `lru_cache` memoises *results*; concurrent
150
+ first callers on the 8-worker pool all miss and each run the subprocess (measured: 6 `uv tool list`
151
+ calls where 2 suffice). `_once` holds a lock while computing. The memo is process-wide, so nothing may
152
+ read it after an install/update and expect to see the change.
153
+ - **`note` is set only by a checker that actually knows why** — the command layer never invents one — and
154
+ is free text, so the renderer escapes it (Rich reads `[docs]` as markup).
155
+ - **Exit status is "did the lookup run", not the answer** (the same rule as `run_cmd`), and `--json`
156
+ writes only the array to stdout, even at `-vv`.
157
+
136
158
  **Two ways a tool gets defined**: built-in (an entry added directly to `src/dev_setup/tools.yaml`,
137
159
  `builtin=True`) or custom (created via the `devstuff add` wizard, `devstuff catalog import`,
138
160
  or hand-edited YAML, landing in the user catalog). Both use the identical schema — the only
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.10.0
3
+ Version: 2.11.0
4
4
  Summary: Development environment setup CLI for Linux
5
5
  Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
6
6
  Author-email: Sawyer <sawyerksu@gmail.com>
@@ -314,6 +314,64 @@ reinstall.
314
314
 
315
315
  ---
316
316
 
317
+ ### `outdated`
318
+
319
+ Show which installed packages have a newer version available. It is **read-only** — nothing is
320
+ installed, updated or written — so it is safe in scripts and CI. `devstuff update` is what acts on
321
+ the answer.
322
+
323
+ ```bash
324
+ devstuff outdated # every installed package
325
+ devstuff outdated codex nvm # just these (one that isn't installed is reported as such)
326
+ devstuff outdated --updates-only # hide everything except packages with an update
327
+ devstuff outdated --all # list the packages that can't be checked, instead of one footer line
328
+ devstuff outdated --json # machine-readable; nothing else is written to stdout
329
+ ```
330
+
331
+ ```
332
+ ╭────────────────────────────────────────────────────────────────────────╮
333
+ │ Package Type Installed Latest Status │
334
+ ├────────────────────────────────────────────────────────────────────────┤
335
+ │ codex npm 0.162.0 0.162.1 ⬆ outdated │
336
+ │ commitizen uvx ? unknown │
337
+ │ not installed via `uv tool` │
338
+ │ claude-code npm 2.1.296 2.1.296 ✔ current │
339
+ ╰────────────────────────────────────────────────────────────────────────╯
340
+ 8 tools can't be checked (bash installers): bat, devin, gh, nerd-font, nvm, pi, starship, uv
341
+ 1 outdated · 1 current · 1 unknown · 8 unsupported
342
+ ```
343
+
344
+ Every package lands in exactly one state:
345
+
346
+ | State | Meaning |
347
+ |-------|---------|
348
+ | `outdated` | A different version is available. |
349
+ | `current` | The check ran and found nothing newer. |
350
+ | `unknown` | A check exists for this install type but couldn't answer — offline, or the package isn't managed by that mechanism. A dim line says why when devstuff knows. |
351
+ | `unsupported` | This install type has no way to check at all. That is every `script`/`bash` package, which on the bundled catalog is most of them. |
352
+ | `not-installed` | Named explicitly on the command line, but not installed. |
353
+
354
+ `unknown` and `unsupported` are never reported as `current`, and the summary counts them
355
+ separately, so "could not check" can't be mistaken for "up to date". Unsupported packages collapse
356
+ to one footer line (still naming them); `--all` expands them.
357
+
358
+ - **"Outdated" means *different*, not *older*.** The `npm` and `apt` checks compare for inequality,
359
+ so a locally newer version (a prerelease, a held package) is reported as outdated. For `uvx`/`pip`
360
+ packages the check is "uv doesn't list it as outdated", so there is no latest version to show for
361
+ a `current` row.
362
+ - **`apt` reflects your last `apt update`.** devstuff doesn't refresh package lists for a read-only report.
363
+ - **uv offline.** With `UV_OFFLINE` set, uv answers from cache or says nothing, which can't be told
364
+ from "all current" — so devstuff reports `unknown` rather than ask. A `offline = true` in uv's
365
+ config file can't be detected.
366
+
367
+ The exit status says whether the lookup ran, not what it found: `0` even when updates are
368
+ available, `1` only for an unknown package name. With `--json`, stdout is one array — even at
369
+ `-vv`, whose log lines go to stderr — of `{"key", "type", "state", "installed", "latest", "note"}`
370
+ objects, with `null` for an absent version and an empty `note` when no reason is known. `--json`
371
+ includes the `unsupported` rows; `--updates-only` applies to it too.
372
+
373
+ ---
374
+
317
375
  ### `configure`
318
376
 
319
377
  Set up an installed tool through a guided wizard, previewing the result before anything is
@@ -287,6 +287,64 @@ reinstall.
287
287
 
288
288
  ---
289
289
 
290
+ ### `outdated`
291
+
292
+ Show which installed packages have a newer version available. It is **read-only** — nothing is
293
+ installed, updated or written — so it is safe in scripts and CI. `devstuff update` is what acts on
294
+ the answer.
295
+
296
+ ```bash
297
+ devstuff outdated # every installed package
298
+ devstuff outdated codex nvm # just these (one that isn't installed is reported as such)
299
+ devstuff outdated --updates-only # hide everything except packages with an update
300
+ devstuff outdated --all # list the packages that can't be checked, instead of one footer line
301
+ devstuff outdated --json # machine-readable; nothing else is written to stdout
302
+ ```
303
+
304
+ ```
305
+ ╭────────────────────────────────────────────────────────────────────────╮
306
+ │ Package Type Installed Latest Status │
307
+ ├────────────────────────────────────────────────────────────────────────┤
308
+ │ codex npm 0.162.0 0.162.1 ⬆ outdated │
309
+ │ commitizen uvx ? unknown │
310
+ │ not installed via `uv tool` │
311
+ │ claude-code npm 2.1.296 2.1.296 ✔ current │
312
+ ╰────────────────────────────────────────────────────────────────────────╯
313
+ 8 tools can't be checked (bash installers): bat, devin, gh, nerd-font, nvm, pi, starship, uv
314
+ 1 outdated · 1 current · 1 unknown · 8 unsupported
315
+ ```
316
+
317
+ Every package lands in exactly one state:
318
+
319
+ | State | Meaning |
320
+ |-------|---------|
321
+ | `outdated` | A different version is available. |
322
+ | `current` | The check ran and found nothing newer. |
323
+ | `unknown` | A check exists for this install type but couldn't answer — offline, or the package isn't managed by that mechanism. A dim line says why when devstuff knows. |
324
+ | `unsupported` | This install type has no way to check at all. That is every `script`/`bash` package, which on the bundled catalog is most of them. |
325
+ | `not-installed` | Named explicitly on the command line, but not installed. |
326
+
327
+ `unknown` and `unsupported` are never reported as `current`, and the summary counts them
328
+ separately, so "could not check" can't be mistaken for "up to date". Unsupported packages collapse
329
+ to one footer line (still naming them); `--all` expands them.
330
+
331
+ - **"Outdated" means *different*, not *older*.** The `npm` and `apt` checks compare for inequality,
332
+ so a locally newer version (a prerelease, a held package) is reported as outdated. For `uvx`/`pip`
333
+ packages the check is "uv doesn't list it as outdated", so there is no latest version to show for
334
+ a `current` row.
335
+ - **`apt` reflects your last `apt update`.** devstuff doesn't refresh package lists for a read-only report.
336
+ - **uv offline.** With `UV_OFFLINE` set, uv answers from cache or says nothing, which can't be told
337
+ from "all current" — so devstuff reports `unknown` rather than ask. A `offline = true` in uv's
338
+ config file can't be detected.
339
+
340
+ The exit status says whether the lookup ran, not what it found: `0` even when updates are
341
+ available, `1` only for an unknown package name. With `--json`, stdout is one array — even at
342
+ `-vv`, whose log lines go to stderr — of `{"key", "type", "state", "installed", "latest", "note"}`
343
+ objects, with `null` for an absent version and an empty `note` when no reason is known. `--json`
344
+ includes the `unsupported` rows; `--updates-only` applies to it too.
345
+
346
+ ---
347
+
290
348
  ### `configure`
291
349
 
292
350
  Set up an installed tool through a guided wizard, previewing the result before anything is
@@ -0,0 +1,177 @@
1
+ # Roadmap
2
+
3
+ Proposed next work for `devstuff`, in build order. This is a plan, not a commitment: each item
4
+ gets a `docs/specs/<feature>/` directory (see [`specs/README.md`](specs/README.md)) *before*
5
+ implementation starts, and that spec — not this file — is where requirements are numbered and
6
+ rejected alternatives are recorded.
7
+
8
+ Last revised: 2026-10-10.
9
+
10
+ ## Theme
11
+
12
+ `devstuff` is good at *one tool at a time*. Nothing yet answers *"is this machine in the state I
13
+ want?"* or *"make this machine look like that one"*. The first four milestones build toward that;
14
+ M5 is independent polish that can be slotted in anywhere.
15
+
16
+ ## Order and why
17
+
18
+ | # | Milestone | Effort | Depends on | Spec directory |
19
+ |---|-----------|--------|------------|----------------|
20
+ | M1 | `devstuff outdated` | Low | — | `outdated/` |
21
+ | M2 | `devstuff profile snapshot` / `diff` | Medium | M1 | `profile/` |
22
+ | M3 | `devstuff profile apply` + bundled bundles | Medium–high | M2 | `profile/` (same) |
23
+ | M4 | Agent tools for `doctor` / `outdated` | Low | M1 | `agent/` (amend) |
24
+ | M5 | Shell completion | Low | — | `completion/` |
25
+ | — | git / tmux configurator | Medium | — | `git-config/` (unscheduled) |
26
+ | — | `devstuff sandbox <tool>` | Medium | — | `sandbox/` (unscheduled) |
27
+
28
+ M1 comes first because it is useful on its own and builds the one thing M2 and M3 both need: a
29
+ trustworthy "what version is installed, and is it behind?" answer. Shipping it alone also tests
30
+ that answer against real machines before anything is built on top of it.
31
+
32
+ ---
33
+
34
+ ## M1 — `devstuff outdated`
35
+
36
+ A read-only, non-interactive table of installed vs. latest version per tool.
37
+
38
+ **Spec:** [`specs/outdated/`](specs/outdated/) — **done**, 2026-10-10 (v1; all seven spec milestones).
39
+
40
+ **Why it is small.** `GenericTool.check_for_update()` already returns an `UpdateStatus`
41
+ (`current`, `latest`, `available`) for `npm`, `pip`, `uvx`, `apt` and `git`, and `devstuff update`
42
+ already probes every installed tool concurrently for its picker. This milestone is a new command
43
+ over an existing probe and an existing collector, not new probing.
44
+
45
+ **What is actually hard** (revised after measuring the existing path — see the spec's §4).
46
+ - **Two thirds of the bundled catalog cannot be checked.** 23 of 35 tools are `bash` installers
47
+ with no update checker. `available is None` is "unknown", never "current", and a *missing*
48
+ checker must be told apart from a *failed* probe — hence five states, not three. Making `bash`
49
+ tools checkable is the real fix and is a follow-up spec, not part of M1.
50
+ - **The existing uv probes are redundant and racy.** One run issued 6 `uv tool list` calls where
51
+ 2 suffice, however many uv tools are installed: `lru_cache` does not stop concurrent first callers from each computing the value.
52
+ Fix this before building on it.
53
+ - **The collector is private to `update_cmd.py`.** It has to move somewhere both commands can
54
+ import, as a pure refactor with a parity test.
55
+ - **Probes go through `_probe`**, per the verbosity rules in `CLAUDE.md` — no direct
56
+ `subprocess.run`.
57
+
58
+ **Done when**
59
+ - [ ] `devstuff outdated [keys…]` prints a table; installed tools only by default.
60
+ - [ ] Unknown is visibly distinct from up-to-date, and a test pins that for a `script` tool.
61
+ - [ ] `--json` for scripting; exit code is 0 regardless of findings (the `run_cmd` lesson: exit
62
+ status is for "could not perform the lookup", not for the answer).
63
+ - [ ] `update`'s picker and `outdated` share one code path rather than two copies of the probe loop.
64
+
65
+ ## M2 — `devstuff profile snapshot` and `diff`
66
+
67
+ A profile is a YAML file: catalog keys, optional pinned versions, optional configurator output.
68
+
69
+ ```yaml
70
+ version: 1
71
+ tools:
72
+ uv: {}
73
+ lazygit: { version: 0.45.0 }
74
+ starship: {}
75
+ ```
76
+
77
+ **Design commitments (to be written up in the spec)**
78
+ - **A snapshot is measured, not remembered.** It is built by probing `is_installed()` and
79
+ `get_version()` now. There is no separate "installed state" file to drift out of sync — the
80
+ same reason `doctor` and every configurator measure the real binary.
81
+ - **Reuse `catalog.py`'s validation style**: unknown fields and unknown keys fail loudly at load
82
+ time, consistent with "invalid catalogs fail loudly".
83
+ - **`diff` reports four states**: missing, extra, version drift, and *unverifiable* (a pinned
84
+ `script` tool whose version cannot be probed). The fourth state is the M1 lesson again.
85
+ - A profile references catalog keys only. It never embeds install scripts, so a profile file
86
+ cannot become a way to smuggle arbitrary commands past the catalog's validation.
87
+
88
+ **Done when**
89
+ - [ ] `profile snapshot` writes a valid profile; `profile diff` of a fresh snapshot against the
90
+ same machine reports no differences (round-trip test).
91
+ - [ ] Keys unknown to the effective catalog are reported, not silently dropped.
92
+ - [ ] Spec records the rejected alternative of extending `catalog export` instead, with reasons.
93
+
94
+ ## M3 — `devstuff profile apply` and bundled bundles
95
+
96
+ Turn a profile into an install plan and run it.
97
+
98
+ - **Ordering** comes from the existing `requires` graph (including auto-inferred edges such as
99
+ `npm` → `nvm`). Do not write a second dependency resolver; if the existing one is not exposed in
100
+ a reusable form, factor it out first.
101
+ - **Plan before action**: reuse the `_plan.py` preview and the task-view progress bar that
102
+ `install`/`update` use, so `apply` shows what it will do and asks.
103
+ - **Failure policy** needs a decision in the spec: continue past a failed tool and summarise, or
104
+ stop. Recommendation: continue, skip anything whose `requires` failed, and report at the end —
105
+ a 40-tool apply that dies on tool 3 is worse than one that finishes 39.
106
+ - **Pins on `script`/`bash` tools** can only be honoured by a full reinstall. `apply` should say so
107
+ and confirm, matching `update`'s existing behaviour for those types.
108
+ - **Bundled bundles** (`@backend`, `@devops`, …) are profile files shipped in the package. They are
109
+ data, so they get a validation test and a CI check that every key they name exists in the
110
+ bundled catalog — the same two-direction enforcement as the CI-matrix test.
111
+ - **Configurator state**: restoring starship/lazygit/bat configuration is the differentiator over
112
+ a dotfiles repo, but several configurators do not round-trip (pre-commit and commitizen
113
+ explicitly do not). Scope M3 to tools only and treat configurator capture as a separate,
114
+ later decision recorded in the spec's open questions.
115
+
116
+ **Done when**
117
+ - [ ] `apply` on an empty container (the existing Docker integration harness) reproduces a
118
+ snapshot taken elsewhere.
119
+ - [ ] A failing tool does not abort the run; dependents are skipped with a stated reason.
120
+ - [ ] Every bundled bundle passes the key-exists test.
121
+
122
+ ## M4 — Agent tools for `doctor` and `outdated`
123
+
124
+ Expose both as agent tools so the local model can answer "why is my nvm broken?" by running the
125
+ checks. Per `CLAUDE.md` this is mostly a YAML edit (`impl: catalog` / `impl: primitive` in
126
+ `agent_tools.yaml`); `agent_tools.schema.json` must be updated in the same change if any field is
127
+ added.
128
+
129
+ - `outdated` is read-only and safe to expose unconditionally.
130
+ - `doctor --fix` mutates the machine, so the agent gets the **check-only** form. A model
131
+ deciding to apply fixes is a separate question for the spec, not a default.
132
+
133
+ ## M5 — Shell completion
134
+
135
+ `devstuff completion bash|zsh|fish`, built on Click's native completion support.
136
+
137
+ - The value is **dynamic completion of catalog keys** for `install`, `remove`, `update` and
138
+ `configure`, which means completing from the *effective* catalog (bundled + user), not a
139
+ generated static list.
140
+ - Completion runs on every `<TAB>`: it must not shell out to probes. Keys only, no
141
+ install-state lookups.
142
+ - Document the one-line install in README.md alongside the existing shell-integration notes.
143
+
144
+ ---
145
+
146
+ ## Unscheduled candidates
147
+
148
+ **git / tmux configurator.** Same shape as the seven existing wizards, and the same first step
149
+ applies: before writing anything, find what the tool's own validator does *not* check. For git
150
+ that means measuring which `git config` keys are silently accepted and ignored.
151
+
152
+ **`devstuff sandbox <tool>`.** Try an install in a throwaway container before it touches the
153
+ host, reusing the Docker integration-test machinery. Not scheduled because it depends on Docker
154
+ being present, which the tool cannot assume, and because it overlaps `-vv` plan previews for the
155
+ "what will this do?" question.
156
+
157
+ ## Non-goals
158
+
159
+ - **Not a configuration-management system.** `profile` converges a *developer machine* onto a
160
+ list of catalog tools. It is not Ansible and will not grow conditionals, templating, or
161
+ inventory.
162
+ - **No remote profile registry or sync service** in this roadmap. Profiles are files; sharing
163
+ them is the user's git repo.
164
+ - **No new install `type`s.** Nothing here adds a mechanism to `GenericTool`; every milestone
165
+ composes what exists.
166
+ - **No runtime dependencies.** Same rule the agent follows: devstuff is globally installed, and
167
+ every dependency is paid for by users who never run the new command.
168
+
169
+ ## Risks
170
+
171
+ | Risk | Affects | Mitigation |
172
+ |------|---------|------------|
173
+ | Version probes disagree with what a tool actually is (e.g. a shim) | M1–M3 | Probe only through `get_version()`/`check_for_update()`; add live tests against the real binary, per project convention |
174
+ | `script`/`bash` tools dominate the catalog and are unverifiable | M1–M3 | Make "unknown" a first-class state everywhere rather than an edge case |
175
+ | `apply` partially succeeds and leaves a half-built machine | M3 | Plan preview, continue-and-summarise policy, dependents skipped with reasons |
176
+ | Profile format hardens before `apply` has been tried | M2 | Ship `snapshot`/`diff` as `version: 1` but mark the format provisional until M3 lands |
177
+ | Scope creep into configurator capture | M3 | Explicit non-goal above; revisit as its own spec |
@@ -47,3 +47,4 @@ They are most useful when they capture:
47
47
  | [`ansible-config/`](ansible-config/) — `devstuff configure ansible`, the ansible.cfg wizard | Complete (v1) |
48
48
  | [`lazygit-config/`](lazygit-config/) — `devstuff configure lazygit`, the icons/pager/panels wizard | Complete (v1) |
49
49
  | [`verbose-mode/`](verbose-mode/) — `-v`/`-vv`, the process-wide verbosity level | Complete (v1) |
50
+ | [`outdated/`](outdated/) — `devstuff outdated`, the read-only installed-vs-latest report | Complete (v1) |
@@ -0,0 +1,78 @@
1
+ # Development plan: `devstuff outdated`
2
+
3
+ **Date:** 2026-10-10
4
+ **Status:** Complete (v1), 2026-10-10
5
+
6
+ ---
7
+
8
+ ## Milestones
9
+
10
+ | # | Milestone | Satisfies | State |
11
+ |---|-----------|-----------|-------|
12
+ | 1 | Fix redundant `uv` probes: lock/prime `_uv_outdated_map`, parse `uv tool list` once for all lookups | FR-19, NFR-2 | **Done** 2026-10-10 |
13
+ | 2 | Move the collector out of `update_cmd.py`; type it against `GenericTool`; drop the `type: ignore` | FR-15–17, SD-4 | **Done** 2026-10-10 |
14
+ | 3 | State classifier: `UpdateStatus` + `install_type` → one of five states | FR-5–8, SD-2/3 | **Done** 2026-10-10 |
15
+ | 4 | `commands/outdated_cmd.py`: table, footer, summary, flags, exit status; register in `cli._register_commands` | FR-1–4, 9–11, 13–14, 18 | **Done** 2026-10-10 |
16
+ | 5 | `--json` output and stdout-purity test at `-vv` | FR-12, NFR-1 | **Done** 2026-10-10 (landed with 4: `--json` is part of the command's contract) |
17
+ | 6 | `UpdateStatus.note`: add the field; set it in the uv checker (F-2) and on the npm/apt/git network-failure paths; render and emit it | FR-23, F-7 | **Done** 2026-10-10 |
18
+ | 7 | README (command reference), CLAUDE.md (architecture line), roadmap + specs index | — | **Done** 2026-10-10 |
19
+
20
+ Milestones 1 and 2 land first and **before any new command exists**: both are changes to
21
+ existing behaviour, so each is verifiable against `update`'s current output. Doing them first
22
+ means the new command is built on a corrected, shared base rather than copying the race.
23
+
24
+ M3 is deliberately a pure function with no I/O, so the five-state rule — the point of the
25
+ spec — is testable without a terminal or a network.
26
+
27
+ ## Testing strategy
28
+
29
+ New file `tests/test_outdated.py`. Unit-only; no network and no real installs, so it stays in
30
+ the default ~0.3 s suite.
31
+
32
+ - **Classifier, exhaustively.** Parametrized over `(install_type, UpdateStatus)` → state: each
33
+ of the five states, plus the two that matter most — a `bash` tool and a failed `npm` probe both
34
+ have an empty status and must classify as `unsupported` and `unknown` respectively (SD-2).
35
+ - **Rendering distinguishes states** (FR-7/FR-20): capture the Rich output and assert the
36
+ `unknown` and `unsupported` renderings contain neither the `current` glyph nor its wording.
37
+ This is the test that fails if someone "tidies" the states back together.
38
+ - **`note` is optional and never invented** (FR-23): a checker that sets nothing yields an empty
39
+ note and unchanged output; the uv checker sets one for a tool on `PATH` but absent from
40
+ `uv tool list` (the `commitizen` case, F-2).
41
+ - **Counts sum to tools checked** (FR-11), including with `--updates-only` hiding rows.
42
+ - **Read-only** (FR-3): patch `install`/`remove`/`update` on the registry's tools to raise; the
43
+ command must complete.
44
+ - **Exit status** (FR-14): exit 0 with outdated tools present; exit 1 for an unknown key.
45
+ - **`--json` purity** (FR-22/NFR-1): run at `-vv` with `capfd`, assert stdout parses as a JSON
46
+ array and every record has exactly the six fields (`key`, `type`, `state`, `installed`, `latest`, `note`).
47
+ - **Collector parity** (FR-21): with probes stubbed, the shared collector returns what the
48
+ pre-move `_collect_update_candidates` did, and `update`'s picker is unchanged.
49
+ - **Probe count** (FR-19): stub `generic._probe` with a counter, run the collector over N≥3
50
+ fake uv tools concurrently, and assert `uv tool list` and `uv tool list --outdated` each ran
51
+ once (`tests/test_uv_probes.py`). This test must fail on the current code — it is the regression test for finding F-1,
52
+ and a version that passes before the fix proves nothing.
53
+
54
+ **Live verification** (not in the suite; recorded in the spec when done, like every configurator):
55
+ run against this machine with a mix of npm/uvx/bash tools, once online and once with the network
56
+ blocked, confirming offline turns `outdated` into `unknown` and never into `current`.
57
+
58
+ **Done 2026-10-10** (dead proxy + cold uv cache, then `UV_OFFLINE=1`): every checkable tool was `unknown` with a stated
59
+ reason; none read `current`. This caught F-7 — the uv probe ignored its exit code — which the unit tests had not,
60
+ because they only faked a *successful* probe.
61
+
62
+ ## Risks
63
+
64
+ | Risk | Likelihood | Mitigation |
65
+ |------|-----------|------------|
66
+ | The command ships looking broken because two thirds of the catalog is `unsupported` | **High** — measured (F-5) | FR-10's footer states the count and names the tools; OQ-1 is the real fix and is the next spec, so v1's honesty is a stopgap with an owner |
67
+ | Moving the collector subtly changes `update`'s picker | Medium | M2 is a pure move with a parity test; do it as its own commit so a regression bisects to it |
68
+ | Fixing the uv race changes which tools read as current | Low | The race only duplicated work, never altered results; parity test covers it |
69
+ | `!=` comparison produces false `outdated` for prereleases / held packages (F-4) | Medium | Documented in the spec and README; not fixed in v1 (OQ-2) |
70
+ | Network-blocked environments make every checkable tool `unknown` | Medium | Intended — that is the correct answer. The summary line makes it obvious |
71
+ | A probe fails and reads as `current` (found live: F-7) | **Was real** | Fixed; each uv/npm/apt/git failure path now has a test, and the offline run is verified live |
72
+ | `-vv` probe logging from 8 threads interleaves on stderr | Low | stderr only, one line per call; if unreadable, serialise log writes in `verbose.py` rather than change the pool |
73
+
74
+ ## Out of scope for this plan
75
+
76
+ OQ-1 (checkable `bash` tools) and OQ-2 (version ordering) were resolved as deferred follow-ups
77
+ (2026-10-10) and get their own spec directories; OQ-3 (`--exit-code`) waits for a concrete request. `profile` (M2/M3 of the roadmap) consumes this command's collector
78
+ and its five-state vocabulary, and should cite SD-2/SD-3 rather than re-deriving them.
@@ -0,0 +1,169 @@
1
+ # Specification: `devstuff outdated`
2
+
3
+ **Date:** 2026-10-10
4
+ **Status:** Implemented (v1), 2026-10-10 — see development-plan.md
5
+ **Authors:** Sawyer + Claude
6
+ **Roadmap:** [M1](../../ROADMAP.md) — the foundation `profile diff` (M2) is built on.
7
+
8
+ ---
9
+
10
+ ## 1. Problem Statement & Goals
11
+
12
+ `devstuff update` is the only place that knows whether an installed tool is behind, and it
13
+ only tells you as a side effect of opening an interactive picker that ends in a mutation:
14
+
15
+ - **There is no read-only answer.** You cannot ask "what is behind?" from a script, a cron job
16
+ or a CI step. `update` with no arguments opens a questionary checkbox, which hangs in a
17
+ non-TTY shell (see CLAUDE.md, "Commands").
18
+ - **The gathered answer is private.** `_collect_update_candidates()` in `commands/update_cmd.py`
19
+ already probes every installed tool concurrently and returns `(tool, UpdateStatus)` pairs, but
20
+ nothing outside that one file can call it.
21
+ - **"Unknown" is the common case, and the picker undersells it.** On the bundled catalog 23 of
22
+ 35 tools (66%) are `bash` installers, which have no update checker at all. The picker labels
23
+ them `unknown — reinstall to check`, which reads as a hint rather than as "devstuff cannot
24
+ see this tool". A report that is mostly blind needs to say so plainly.
25
+
26
+ **Goal:** a read-only, non-interactive command that reports installed vs. latest per tool,
27
+ shares one probing path with `update`, and never presents "could not check" as "up to date".
28
+
29
+ **Non-goals** (each one is a decision, with reasons in `stack-decisions.md`):
30
+ - No mutation of any kind. `outdated` never offers to update; that is `devstuff update`.
31
+ - No new update checkers for `script`/`bash` tools in v1 — see OQ-1.
32
+ - No version *ordering*. v1 reports "different from the latest", not "older than the latest" — see OQ-2.
33
+ - No persistent cache and no background refresh.
34
+ - No uninstalled tools, no checking for new *catalog* entries.
35
+ - No notification, cron or shell-prompt integration; `--json` is the integration surface.
36
+
37
+ ---
38
+
39
+ ## 2. Functional Requirements
40
+
41
+ ### Command surface
42
+
43
+ - **FR-1** `devstuff outdated [KEY…]`. With no keys, every **installed** tool is checked. With
44
+ keys, exactly those tools are checked. An unknown key prints an error and exits 1, matching
45
+ `update`. A known key that is not installed yields a `not-installed` row (FR-5), not an error.
46
+ - **FR-2** Never prompts, never opens a questionary widget, and works with stdin and stdout
47
+ redirected.
48
+ - **FR-3** Read-only. It must not call `install`, `remove`, `update`, `configure`, or write to
49
+ the catalog or any config directory. (Test: patch each to raise.)
50
+ - **FR-4** Two display flags: `--updates-only` hides every row that is not `outdated`;
51
+ `--all` shows the `unsupported` rows that are otherwise collapsed (FR-10).
52
+
53
+ ### The five states
54
+
55
+ - **FR-5** Every checked tool lands in exactly one state:
56
+
57
+ | State | Meaning | Source |
58
+ |---|---|---|
59
+ | `outdated` | a different version is available | `UpdateStatus.available is True` |
60
+ | `current` | the checker found nothing newer | `available is False` |
61
+ | `unknown` | a checker exists but could not answer | `available is None`, type has a checker |
62
+ | `unsupported` | no checker exists for this install type | type absent from `_UPDATE_CHECKERS` |
63
+ | `not-installed` | named explicitly but not installed | `is_installed()` is False |
64
+
65
+ - **FR-6** `unsupported` is decided from the tool's `install_type` against the checker table,
66
+ **not** inferred from an empty `UpdateStatus`. An empty status is what a *failed* probe also
67
+ returns, so inferring would merge "cannot be checked" with "the check failed" — two states
68
+ whose remedies differ (nothing to do vs. check your network).
69
+ - **FR-7** `unknown` and `unsupported` are never rendered with the same glyph, colour or wording
70
+ as `current`, and are never counted in a "current" total. This is the requirement the whole
71
+ command exists to protect; it has a test per state (FR-20).
72
+ - **FR-8** `current` means "the checker found no newer version", which for `uvx` and `pip`
73
+ tools does not include the latest version number (see §4, finding F-3). The `Latest` column is
74
+ blank for those rows rather than echoing `Installed`.
75
+
76
+ ### Output
77
+
78
+ - **FR-9** Table columns: `Package`, `Type`, `Installed`, `Latest`, `Status`. Rows sort
79
+ `outdated`, `unknown`, `current`, `not-installed`; alphabetical by key within a state.
80
+ - **FR-10** `unsupported` rows are collapsed by default into one dim footer line
81
+ (`23 tools can't be checked (bash installers): bat, gh, …`) and shown as rows with `--all`.
82
+ They are the majority on the bundled catalog and would otherwise bury the answer.
83
+ - **FR-11** A one-line summary closes the output, with all five counts that are non-zero:
84
+ `3 outdated · 6 current · 2 unknown · 23 unsupported`. Counts always sum to the number of
85
+ tools checked.
86
+ - **FR-12** `--json` writes a single JSON array to stdout and nothing else:
87
+ `{"key", "type", "state", "installed", "latest", "note"}`, with `null` for absent versions and
88
+ an empty string for an absent note (FR-23). `state`
89
+ uses the five names in FR-5. Everything else (banner, spinner, hints) is suppressed or goes
90
+ to stderr — see NFR-1.
91
+ - **FR-13** The banner and spinner are shown only when stdout is a TTY and `--json` is absent.
92
+
93
+ ### Exit status
94
+
95
+ - **FR-14** Exit 0 whenever the lookup was performed, **regardless of what it found**. Non-zero
96
+ is reserved for "could not perform the lookup" (unknown key, catalog failure). This is the
97
+ `run_cmd` rule from CLAUDE.md: a correct answer must not arrive under a red failure banner.
98
+
99
+ ### Probing
100
+
101
+ - **FR-15** Version information comes from `GenericTool.check_for_update()` and nothing else.
102
+ The command layer adds no subprocess call of its own; anything it did need would go through
103
+ `generic._probe`, per the verbosity rules.
104
+ - **FR-16** Probes run concurrently on a bounded pool (8 workers, as `list` and `update` use).
105
+ One tool raising or timing out yields an `unknown` row for that tool and never aborts the run.
106
+ - **FR-17** The gathering code is shared. `update`'s interactive picker and `outdated` call
107
+ **one** function that lives outside `update_cmd.py`; `update`'s picker output is unchanged by
108
+ the move (regression test, FR-21).
109
+ - **FR-18** Progress: a spinner while probing on a TTY, replaced by a plain logged line at `-v`
110
+ (`verbose.step`), as for every other command.
111
+ - **FR-19** Redundant probes are removed: one run invokes `uv tool list` at most once and
112
+ `uv tool list --outdated` at most once, however many `uv` tools are installed (see NFR-2).
113
+
114
+ - **FR-23** `UpdateStatus` gains one optional field, `note: str = ""`, a short human reason
115
+ (`"not installed via uv tool"`, `"registry unreachable"`). Checkers set it only where they
116
+ actually know why they could not answer; it is never invented by the command layer. It is
117
+ shown dimmed after the status text and carried in `--json`. A checker that does not set it
118
+ behaves exactly as before — the field defaults to empty, so no existing call site changes.
119
+ (Resolves OQ-4; motivated by finding F-2.) Implemented 2026-10-10 for uv (not managed by `uv tool`; probe failed; `UV_OFFLINE`), npm (registry unreachable), apt (no candidate; `apt-cache policy` failed) and git (no clone; remote unreachable). Rendered on a dim second line of the Status cell, markup-escaped, because a note is free text from a checker.
120
+
121
+ ### Tests
122
+
123
+ - **FR-20** One test per state asserting its rendering differs from `current`'s, including a
124
+ real `bash`-type tool landing in `unsupported`.
125
+ - **FR-21** The shared collector returns what `update`'s picker consumed before the move.
126
+ - **FR-22** `outdated --json` at `-vv` parses as JSON (stdout purity, NFR-1).
127
+
128
+ ---
129
+
130
+ ## 3. Non-Functional Requirements
131
+
132
+ - **NFR-1** **stdout carries data only.** Under `--json`, even at `-vv`, stdout is exactly one
133
+ JSON document. Same invariant, same reason, as `verbose-mode` SD-3: a consumer is parsing it.
134
+ - **NFR-2** **Probe cost is bounded by the number of distinct questions, not tools.** Measured
135
+ baseline in §4 (F-1): six `uv tool list` calls for three installed uv tools, where two
136
+ suffice. After this work, the count is independent of how many uv tools are installed.
137
+ - **NFR-3** **Latency.** The measured baseline is 2.6 s for 13 installed tools on a warm
138
+ network. No target is set beyond "not regress"; per-probe timeouts (10–20 s) bound the worst
139
+ case, and there is deliberately no global timeout in v1 (OQ-5).
140
+ - **NFR-4** **No new runtime dependency.** Rich is already present; JSON is stdlib.
141
+
142
+ ---
143
+
144
+ ## 4. Findings from measurement
145
+
146
+ Per the project convention (*measure the tool, don't recall it*), the existing probe path was
147
+ run before this spec was written. Date: 2026-10-10; 13 installed tools.
148
+
149
+ | # | Finding | Consequence |
150
+ |---|---------|-------------|
151
+ | F-1 | `uv tool list` ran **6** times for 3 installed uv tools; **2** are needed (one plain, one `--outdated`), however many tools there are. `_uv_outdated_map` is `@lru_cache(maxsize=1)`, but `lru_cache` does not stop *concurrent* first callers from each computing the value, so all three worker threads ran `uv tool list --outdated`. `_uv_tool_current_version` has no cache at all, so it runs once per tool. | FR-19 / NFR-2. **Fixed 2026-10-10 (milestone 1): 6 → 2 live, results unchanged.** The cache needs a lock (or the collector must prime it before fanning out) and the per-tool version lookup must read from one shared `uv tool list` parse. |
152
+ | F-2 | `commitizen` is reported installed (`cz` on `PATH`) but is not a `uv tool` — here it comes from the project venv under `uv run`. The uvx checker asks `uv tool list`, finds nothing, and returns an empty status: `unknown`. | `is_installed()` ("is the command present?") and the update checker ("does this mechanism manage it?") ask different questions and can disagree. `unknown` is the right answer; OQ-4 asks whether it should say *why*. |
153
+ | F-3 | For `uvx` tools the checker only knows the *absence* of a tool from `uv tool list --outdated`. `hey-dave` and `ipython` came back `available=False` with `latest=''`. | `current` for uvx is "not listed as outdated", so `Latest` is blank (FR-8). **Correction (2026-10-10):** an earlier draft of this row also claimed `uv … --outdated` ignores prereleases. That was written from memory and is false: with `hey-dave 0.1.0a1` installed in an isolated tool dir, uv listed `[latest: 0.2.0a1]`, so it follows prereleases when the installed version is itself one. |
154
+ | F-4 | `npm` and `apt` checkers decide `available` by `current != latest` — inequality, not ordering. | A locally newer version (a prerelease, a held or PPA package) reads as `outdated`. OQ-2. |
155
+ | F-5 | 23 of 35 bundled tools are `bash`; none has a checker. | The command is blind to two thirds of the catalog. FR-7 and FR-10 exist because of this; OQ-1 is the real fix. |
156
+ | F-6 | `check_for_update` exists on `GenericTool` but not on the `Tool` ABC; `update_cmd` suppresses the type error with `# type: ignore[attr-defined]`. | The shared collector either takes `GenericTool` or the ABC gains a default. Decided in SD-4. |
157
+ | F-7 | **A failed uv probe read as "current".** Measured 2026-10-10: with no network, `uv tool list --outdated` exits **2** with an error and empty stdout; `_uv_outdated_map` ignored the exit code, so every uv tool came back `available=False`. With `UV_OFFLINE` set and a cold cache uv exits **0** and prints nothing at all — indistinguishable from a real "all current". | A bug in already-shipped `update` code, and exactly the failure FR-7 forbids. Fixed in milestone 6: a non-zero exit is unknown ("couldn't reach the package index"), and `UV_OFFLINE` — the only signal there is — is checked before asking. `uv`'s config-file `offline = true` cannot be detected; documented, not fixed. |
158
+
159
+ ---
160
+
161
+ ## 5. Open questions (all resolved)
162
+
163
+ | # | Question | Recommendation | Status |
164
+ |---|----------|----------------|--------|
165
+ | OQ-1 | Should `bash`/`script` tools be checkable — e.g. an optional catalog field naming where the latest version lives (`latest_from: github:owner/repo`)? | **Yes, but as its own spec after v1 ships.** It is a schema change (`SUPPORTED_FIELDS`, validation, README, schema docs) and decides how `profile diff` sees two thirds of the catalog, so it deserves its own design. v1 ships honest unknowns. | **Resolved 2026-10-10: yes, as its own spec after v1 ships.** v1 keeps honest `unsupported` rows. |
166
+ | OQ-2 | Compare versions by ordering instead of inequality? | Not in v1. Version grammars differ per ecosystem (PEP 440, semver, dpkg); a half-right comparator is worse than a documented `!=`. Revisit with OQ-1. | **Resolved 2026-10-10: not in v1.** Inequality stays, documented (F-4); revisit alongside OQ-1. |
167
+ | OQ-3 | An opt-in `--exit-code` (exit 1 when anything is outdated), `git diff --exit-code` style, for CI? | Probably yes, as a flag that is off by default so FR-14 stays true. Wait for a concrete request. | **Resolved 2026-10-10: deferred.** Not in v1; FR-14 stays true. Add as an opt-in flag on a concrete request. |
168
+ | OQ-4 | Should `UpdateStatus` carry a short `note` (`"not installed via uv tool"`, `"registry unreachable"`) so `unknown` can say why? | Yes — one optional string, default empty, populated only where a checker knows. Without it F-2 is indistinguishable from an offline failure. | **Resolved 2026-10-10: yes.** Specified as FR-23. |
169
+ | OQ-5 | A global timeout on the whole run? | No for v1: per-probe timeouts already bound it, and a global one would turn a slow-but-correct tool into `unknown`. | **Resolved 2026-10-10: no global timeout in v1.** |