devstuff 2.10.0__tar.gz → 2.12.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 (205) hide show
  1. {devstuff-2.10.0 → devstuff-2.12.0}/CHANGELOG.md +26 -0
  2. {devstuff-2.10.0 → devstuff-2.12.0}/CLAUDE.md +55 -1
  3. {devstuff-2.10.0 → devstuff-2.12.0}/PKG-INFO +163 -1
  4. {devstuff-2.10.0 → devstuff-2.12.0}/README.md +162 -0
  5. devstuff-2.12.0/docs/ROADMAP.md +189 -0
  6. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/README.md +2 -0
  7. devstuff-2.12.0/docs/specs/outdated/development-plan.md +78 -0
  8. devstuff-2.12.0/docs/specs/outdated/specifications.md +169 -0
  9. devstuff-2.12.0/docs/specs/outdated/stack-decisions.md +97 -0
  10. devstuff-2.12.0/docs/specs/profile/development-plan.md +127 -0
  11. devstuff-2.12.0/docs/specs/profile/specifications.md +213 -0
  12. devstuff-2.12.0/docs/specs/profile/stack-decisions.md +134 -0
  13. {devstuff-2.10.0 → devstuff-2.12.0}/pyproject.toml +1 -1
  14. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/cli.py +4 -0
  15. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/help_cmd.py +2 -0
  16. devstuff-2.12.0/src/dev_setup/commands/outdated_cmd.py +141 -0
  17. devstuff-2.12.0/src/dev_setup/commands/profile_cmd.py +199 -0
  18. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/update_cmd.py +2 -20
  19. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/generic.py +185 -26
  20. devstuff-2.12.0/src/dev_setup/profile.py +353 -0
  21. devstuff-2.12.0/src/dev_setup/snapshot.py +131 -0
  22. devstuff-2.12.0/src/dev_setup/updates.py +148 -0
  23. devstuff-2.12.0/tests/test_installed_version.py +213 -0
  24. devstuff-2.12.0/tests/test_outdated_cmd.py +331 -0
  25. devstuff-2.12.0/tests/test_pin_support.py +120 -0
  26. devstuff-2.12.0/tests/test_profile.py +340 -0
  27. devstuff-2.12.0/tests/test_profile_diff.py +333 -0
  28. devstuff-2.12.0/tests/test_profile_diff_cmd.py +521 -0
  29. devstuff-2.12.0/tests/test_profile_snapshot_cmd.py +294 -0
  30. devstuff-2.12.0/tests/test_snapshot.py +188 -0
  31. devstuff-2.12.0/tests/test_update_checker_parity.py +120 -0
  32. devstuff-2.12.0/tests/test_update_notes.py +77 -0
  33. devstuff-2.12.0/tests/test_updates.py +217 -0
  34. devstuff-2.12.0/tests/test_uv_probes.py +212 -0
  35. {devstuff-2.10.0 → devstuff-2.12.0}/uv.lock +1 -1
  36. {devstuff-2.10.0 → devstuff-2.12.0}/.claude/skills/run-stuff/SKILL.md +0 -0
  37. {devstuff-2.10.0 → devstuff-2.12.0}/.claude/skills/run-stuff/smoke.sh +0 -0
  38. {devstuff-2.10.0 → devstuff-2.12.0}/.github/codex/review.md +0 -0
  39. {devstuff-2.10.0 → devstuff-2.12.0}/.github/workflows/agent.yml +0 -0
  40. {devstuff-2.10.0 → devstuff-2.12.0}/.github/workflows/bump.yml +0 -0
  41. {devstuff-2.10.0 → devstuff-2.12.0}/.github/workflows/ci.yml +0 -0
  42. {devstuff-2.10.0 → devstuff-2.12.0}/.github/workflows/publish.yml +0 -0
  43. {devstuff-2.10.0 → devstuff-2.12.0}/.github/workflows/test-installs.yml +0 -0
  44. {devstuff-2.10.0 → devstuff-2.12.0}/.gitignore +0 -0
  45. {devstuff-2.10.0 → devstuff-2.12.0}/dev/Dockerfile +0 -0
  46. {devstuff-2.10.0 → devstuff-2.12.0}/dev/Dockerfile.ci +0 -0
  47. {devstuff-2.10.0 → devstuff-2.12.0}/dev/Makefile +0 -0
  48. {devstuff-2.10.0 → devstuff-2.12.0}/dev/docker-compose.yml +0 -0
  49. {devstuff-2.10.0 → devstuff-2.12.0}/devstuff +0 -0
  50. {devstuff-2.10.0 → devstuff-2.12.0}/docs/github-agent.md +0 -0
  51. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/agent/development-plan.md +0 -0
  52. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/agent/specifications.md +0 -0
  53. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/agent/stack-decisions.md +0 -0
  54. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/ansible-config/development-plan.md +0 -0
  55. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/ansible-config/specifications.md +0 -0
  56. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
  57. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/bat-config/development-plan.md +0 -0
  58. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/bat-config/specifications.md +0 -0
  59. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/bat-config/stack-decisions.md +0 -0
  60. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/commitizen-config/development-plan.md +0 -0
  61. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/commitizen-config/specifications.md +0 -0
  62. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
  63. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/docker-config/development-plan.md +0 -0
  64. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/docker-config/specifications.md +0 -0
  65. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/docker-config/stack-decisions.md +0 -0
  66. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/lazygit-config/development-plan.md +0 -0
  67. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/lazygit-config/specifications.md +0 -0
  68. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
  69. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/precommit-config/development-plan.md +0 -0
  70. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/precommit-config/specifications.md +0 -0
  71. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
  72. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/starship-config/development-plan.md +0 -0
  73. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/starship-config/specifications.md +0 -0
  74. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/starship-config/stack-decisions.md +0 -0
  75. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/uv-backbone/development-plan.md +0 -0
  76. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/uv-backbone/specifications.md +0 -0
  77. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
  78. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/verbose-mode/development-plan.md +0 -0
  79. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/verbose-mode/specifications.md +0 -0
  80. {devstuff-2.10.0 → devstuff-2.12.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
  81. {devstuff-2.10.0 → devstuff-2.12.0}/install.sh +0 -0
  82. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/__init__.py +0 -0
  83. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/__main__.py +0 -0
  84. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/__init__.py +0 -0
  85. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/approval.py +0 -0
  86. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/bridges.py +0 -0
  87. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/catalog.py +0 -0
  88. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/completion.py +0 -0
  89. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/config.py +0 -0
  90. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/loop.py +0 -0
  91. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/ollama.py +0 -0
  92. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/preflight.py +0 -0
  93. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/primitives.py +0 -0
  94. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/registry.py +0 -0
  95. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/sandbox.py +0 -0
  96. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/session.py +0 -0
  97. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/transcript.py +0 -0
  98. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent/wizard.py +0 -0
  99. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent_tools.schema.json +0 -0
  100. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/agent_tools.yaml +0 -0
  101. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/base.py +0 -0
  102. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/catalog.py +0 -0
  103. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/__init__.py +0 -0
  104. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/add_cmd.py +0 -0
  105. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/agent_cmd.py +0 -0
  106. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
  107. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/configure_cmd.py +0 -0
  108. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/delete_cmd.py +0 -0
  109. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/docs_cmd.py +0 -0
  110. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
  111. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/functions_cmd.py +0 -0
  112. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/install_cmd.py +0 -0
  113. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/links_cmd.py +0 -0
  114. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/list_cmd.py +0 -0
  115. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/remove_cmd.py +0 -0
  116. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/run_cmd.py +0 -0
  117. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/commands/skills_cmd.py +0 -0
  118. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/__init__.py +0 -0
  119. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
  120. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/detect.py +0 -0
  121. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/model.py +0 -0
  122. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/render.py +0 -0
  123. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/validate.py +0 -0
  124. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
  125. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/__init__.py +0 -0
  126. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/detect.py +0 -0
  127. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/model.py +0 -0
  128. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/preview.py +0 -0
  129. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/render.py +0 -0
  130. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/wizard.py +0 -0
  131. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
  132. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
  133. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/model.py +0 -0
  134. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/render.py +0 -0
  135. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
  136. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
  137. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/__init__.py +0 -0
  138. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/detect.py +0 -0
  139. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/model.py +0 -0
  140. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/render.py +0 -0
  141. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/validate.py +0 -0
  142. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/wizard.py +0 -0
  143. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
  144. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
  145. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/model.py +0 -0
  146. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/render.py +0 -0
  147. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
  148. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
  149. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
  150. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/detect.py +0 -0
  151. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/model.py +0 -0
  152. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/render.py +0 -0
  153. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/validate.py +0 -0
  154. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
  155. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
  156. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
  157. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/__init__.py +0 -0
  158. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/fonts.py +0 -0
  159. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/icons.py +0 -0
  160. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/model.py +0 -0
  161. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/preview.py +0 -0
  162. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/render.py +0 -0
  163. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/wizard.py +0 -0
  164. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/doctor.py +0 -0
  165. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/function_runner.py +0 -0
  166. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/functions.schema.json +0 -0
  167. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/functions.yaml +0 -0
  168. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/functions_catalog.py +0 -0
  169. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/functions_registry.py +0 -0
  170. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/links.schema.json +0 -0
  171. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/links.yaml +0 -0
  172. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/links_catalog.py +0 -0
  173. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/links_registry.py +0 -0
  174. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/registry.py +0 -0
  175. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/tools.yaml +0 -0
  176. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/ui.py +0 -0
  177. {devstuff-2.10.0 → devstuff-2.12.0}/src/dev_setup/verbose.py +0 -0
  178. {devstuff-2.10.0 → devstuff-2.12.0}/tests/__init__.py +0 -0
  179. {devstuff-2.10.0 → devstuff-2.12.0}/tests/integration/__init__.py +0 -0
  180. {devstuff-2.10.0 → devstuff-2.12.0}/tests/integration/conftest.py +0 -0
  181. {devstuff-2.10.0 → devstuff-2.12.0}/tests/integration/test_agent_smoke.py +0 -0
  182. {devstuff-2.10.0 → devstuff-2.12.0}/tests/integration/test_agent_tui.py +0 -0
  183. {devstuff-2.10.0 → devstuff-2.12.0}/tests/integration/test_commitizen_config.py +0 -0
  184. {devstuff-2.10.0 → devstuff-2.12.0}/tests/integration/test_tools.py +0 -0
  185. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_agent.py +0 -0
  186. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_agent_completion.py +0 -0
  187. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_agent_loop.py +0 -0
  188. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_agent_sandbox.py +0 -0
  189. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_agent_tools.py +0 -0
  190. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_agent_wizard.py +0 -0
  191. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_catalog.py +0 -0
  192. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_ansible.py +0 -0
  193. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_bat.py +0 -0
  194. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_commitizen.py +0 -0
  195. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_docker.py +0 -0
  196. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_lazygit.py +0 -0
  197. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_precommit.py +0 -0
  198. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_reptyr.py +0 -0
  199. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_configure_starship.py +0 -0
  200. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_doctor.py +0 -0
  201. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_functions.py +0 -0
  202. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_generic.py +0 -0
  203. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_links.py +0 -0
  204. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_registry.py +0 -0
  205. {devstuff-2.10.0 → devstuff-2.12.0}/tests/test_verbose.py +0 -0
@@ -1,3 +1,29 @@
1
+ ## v2.12.0 (2026-10-10)
2
+
3
+ ### Features
4
+
5
+ - **profile**: add `devstuff profile diff`
6
+ - **profile**: add the diff classifier
7
+ - **profile**: add `devstuff profile snapshot`
8
+ - **generic**: add installed_version() and supports_pin() for profiles
9
+ - **profile**: add the profile file model, strict loader and dumper
10
+
11
+ ## v2.11.0 (2026-10-10)
12
+
13
+ ### Features
14
+
15
+ - **outdated**: add `devstuff outdated`, a read-only update report
16
+ - **updates**: classify tools into five honest states
17
+
18
+ ### Bug Fixes
19
+
20
+ - **update**: a failed uv probe is unknown, not current; add UpdateStatus.note
21
+ - **update**: probe uv once per run instead of once per tool
22
+
23
+ ### Refactors
24
+
25
+ - **update**: move the update collector into a shared module
26
+
1
27
  ## v2.10.0 (2026-10-10)
2
28
 
3
29
  ### Features
@@ -64,8 +64,11 @@ 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`
68
+ ├── profile.py # Profile file format (strict load, deterministic dump) + the seven-state diff classifier — pure
69
+ ├── snapshot.py # Asks the machine: builds a Profile / the facts `profile.compare` needs
67
70
  ├── configure/ # Per-tool setup wizards (see "Configurators" below)
68
- └── commands/ # One Click command per file: list, install, remove, add, delete, docs, catalog
71
+ └── commands/ # One Click command per file: list, install, remove, update, outdated, profile, add, delete, docs, catalog
69
72
  ```
70
73
 
71
74
  **Catalog precedence** (`catalog.load_effective_catalog`): bundled `tools.yaml` loads first →
@@ -133,6 +136,57 @@ through call signatures. Three things about it are load-bearing:
133
136
  streaming output. At `-vv` script bodies run under `bash -x`, *except* eval-mode function
134
137
  scripts — `set -x` there would persist in the caller's interactive shell.
135
138
 
139
+ **Update probing and `outdated`** (`updates.py`, spec in `docs/specs/outdated/`): `update`'s picker
140
+ and `devstuff outdated` share one collector and one classifier. Things that are load-bearing:
141
+ - **`available is False` must mean "the probe positively found nothing newer"** — never "the probe
142
+ failed". Every failure path in an `_UPDATE_CHECKERS` function returns an *empty* status (plus a
143
+ `note` saying why), which classifies as `unknown`. The uv checker once ignored its exit code:
144
+ `uv tool list --outdated` exits 2 offline with empty stdout, which read as every tool being current.
145
+ The unit tests had only faked a *successful* probe; it took running the real binary with the network
146
+ blocked to find it. A new checker needs a test for its failure path, not just its happy one.
147
+ - **`unsupported` is decided from the install *type*** (`generic.supports_update_check`), not from an
148
+ empty `UpdateStatus` — a `bash` tool and a failed `npm` probe return the same empty status and need
149
+ different remedies. Neither may ever render as `current`; there is a test that breaks the renderer to
150
+ prove the test can fail.
151
+ - **Shared probes use `_once`, not `functools.lru_cache`.** `lru_cache` memoises *results*; concurrent
152
+ first callers on the 8-worker pool all miss and each run the subprocess (measured: 6 `uv tool list`
153
+ calls where 2 suffice). `_once` holds a lock while computing. The memo is process-wide, so nothing may
154
+ read it after an install/update and expect to see the change.
155
+ - **`note` is set only by a checker that actually knows why** — the command layer never invents one — and
156
+ is free text, so the renderer escapes it (Rich reads `[docs]` as markup).
157
+ - **Exit status is "did the lookup run", not the answer** (the same rule as `run_cmd`), and `--json`
158
+ writes only the array to stdout, even at `-vv`.
159
+
160
+ **Profiles** (`profile.py`, `snapshot.py`, `commands/profile_cmd.py`; spec in `docs/specs/profile/`):
161
+ `devstuff profile snapshot` / `diff` describe and compare a machine; `apply` is not built (roadmap M3), so the
162
+ file format is provisional. Things that are load-bearing:
163
+ - **`profile.py` is pure and `snapshot.py` asks the machine.** `compare()` takes *facts* (`MachineTool`), not tool
164
+ objects, so the whole decision table is testable without a registry — and is, exhaustively, one case per
165
+ combination of its six inputs.
166
+ - **Loading refuses what YAML silently corrupts**: `version: 1.10` → float `1.1`, `0.40` → `0.4`, `1:30` → int 90
167
+ (sexagesimal), a date → a date object, a duplicate key → the first dropped, a tool key `on`/`yes` → `True`. The
168
+ original text is gone by the time Python sees it, so the loader rejects instead of coercing. `Entry` enforces the
169
+ same rule at construction, so a version `snapshot` builds can always be read back. Emission is safe only because
170
+ `yaml.safe_dump` quotes numeric-looking strings; don't hand-roll it.
171
+ - **Versions come from `GenericTool.installed_version()`** — per-type, local-only readers for the types that can be
172
+ pinned (`npm`, `pip`/`uvx`, single-package `apt`). Never from `get_version()`, which is free text (`'bat 0.26.1
173
+ (979ba22)'`), and never from `check_for_update()`, which also hits the network. A regex over `get_version()` was
174
+ measured at 12 of 13 correct on today's catalog and rejected anyway: its failure is a *wrong pin written silently*.
175
+ - **`supports_pin()` is an explicit set tied to the updaters by a test** (`tests/test_pin_support.py`): a pin must
176
+ actually reach a command, and a refusal must be a refusal *of the pin*, not some other failure that happens to
177
+ raise. Add an updater and that test forces you to say whether it can pin.
178
+ - **Three states mean "could not compare" and are never `ok`**: `unverifiable`, `unpinnable`, `unknown-key`.
179
+ `unpinnable` is decided *before* the version is looked at, so a `bash` tool whose text version equals the pin
180
+ can't read as a match. Same rule as `outdated`'s `unknown`/`unsupported`; it is the point of both commands.
181
+ - **A profile names keys, never definitions or scripts** — otherwise applying one would be arbitrary code execution
182
+ past the catalog's validation. A custom tool is reported as `unknown-key` and moved with `catalog export`/`import`.
183
+ - **Exit status: `2` is a bad profile, `1` is "differs"** (`--exit-code` only). Don't merge them: a CI gate has to
184
+ tell a drifted machine from a typo. Output to stdout is the data and nothing else, at every `-v`.
185
+ - **Tests must be able to reach the guard they claim to test.** CliRunner's stdout is not a TTY, so a "no banner
186
+ under `--json`" test passes whatever the code does unless `isatty()` is forced true (and a counter-test shows the
187
+ banner *does* appear for a person). Likewise defensive `except` around a reader that never raises needs a fake
188
+ reader that does.
189
+
136
190
  **Two ways a tool gets defined**: built-in (an entry added directly to `src/dev_setup/tools.yaml`,
137
191
  `builtin=True`) or custom (created via the `devstuff add` wizard, `devstuff catalog import`,
138
192
  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.12.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,168 @@ 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
+
375
+ ### `profile`
376
+
377
+ Describe which tools a machine should have as a small file, and compare a machine against one.
378
+ Both subcommands are **read-only** and **local** — they ask the machine, never the network — so
379
+ they work offline.
380
+
381
+ ```bash
382
+ devstuff profile snapshot > work.yaml # the tools installed here, as a file
383
+ devstuff profile snapshot --versions -o work.yaml # ...and the versions of the ones that can be pinned
384
+ devstuff profile diff work.yaml # how this machine differs from the file
385
+ devstuff profile diff work.yaml --exit-code # exit 1 if it differs: a gate for CI
386
+ ```
387
+
388
+ > **The file format is provisional until `profile apply` exists.** It is `version: 1`, and a later
389
+ > breaking change will bump that number. There is no `apply` yet — nothing here installs anything.
390
+
391
+ A profile names catalog **keys**, and optionally a version. It never contains an install script or
392
+ a tool definition, so a profile from somewhere else can't run anything your own catalog doesn't
393
+ already define.
394
+
395
+ ```yaml
396
+ version: 1
397
+ tools:
398
+ uv: {} # present, any version
399
+ ipython:
400
+ version: 9.17.1 # present, at exactly this version
401
+ ```
402
+
403
+ **Quote any version that looks like a number.** YAML reads `version: 1.10` as the number 1.1 and
404
+ `0.40` as 0.4, and the original text can't be recovered — so devstuff refuses it and says to quote
405
+ it (`version: '1.10'`). It also refuses a duplicate key, which YAML would otherwise resolve by
406
+ silently dropping the first, an unknown field, and a tool key that YAML reads as something other
407
+ than text (`on`, `yes`, `123`). `snapshot` always writes versions correctly quoted.
408
+
409
+ #### `snapshot`
410
+
411
+ Writes a profile of every installed tool, to stdout or to `-o FILE`. By default it records **keys
412
+ only**: a profile that pins versions goes stale the day a tool updates, and then reports drift
413
+ nobody intended. `--versions` adds the installed version for the tools that can be pinned — `npm`,
414
+ `pip`/`uvx`, and single-package `apt`; `git`, `script` and `bash` tools can't be installed at a
415
+ chosen version, so a version recorded for them could never be acted on and is left out.
416
+
417
+ - If a pinnable tool's version can't be read (say it is on your `PATH` but isn't a `uv tool`), it is
418
+ written without one and a warning on stderr names it and says why — it is never dropped silently.
419
+ - Tools defined in your own catalog are included, with one stderr note that another machine won't
420
+ know them: move their definitions with `devstuff catalog export` / `import`.
421
+ - Output is **deterministic** — sorted, with a fixed header and no timestamp, hostname or path — so
422
+ a profile kept in git shows only real changes.
423
+ - `-o` refuses to overwrite an existing file (exit 2) unless you pass `--force`.
424
+ - With no `-o`, stdout is exactly the YAML; warnings and notes go to stderr.
425
+
426
+ #### `diff`
427
+
428
+ ```
429
+ ╭──────────────────────────────────────────────────────────────────────────────╮
430
+ │ Package Type Profile Installed Status │
431
+ ├──────────────────────────────────────────────────────────────────────────────┤
432
+ │ reptyr apt ✘ missing │
433
+ │ ipython uvx 9.0.0 9.17.1 ≠ drift │
434
+ │ commitizen uvx 4.16.4 ? unverifiable │
435
+ │ uv doesn't list it as a tool │
436
+ │ (is it installed another │
437
+ │ way?) │
438
+ │ starship bash 1.0.0 – unpinnable │
439
+ │ a bash install can't be │
440
+ │ pinned, so the pin is ignored │
441
+ │ not-a-real-tool ? unknown-key │
442
+ │ not in this machine's catalog │
443
+ │ — if it is a custom tool, │
444
+ │ bring its definition over │
445
+ │ with `devstuff catalog │
446
+ │ import` │
447
+ ╰──────────────────────────────────────────────────────────────────────────────╯
448
+ 1 installed tool isn't in the profile: gh (--all lists them)
449
+ 1 missing · 1 drift · 1 unverifiable · 1 unpinnable · 1 unknown-key · 1 extra · 9 ok
450
+ ```
451
+
452
+ | State | Meaning |
453
+ |-------|---------|
454
+ | `ok` | In the profile and installed; and, if pinned, at the pinned version. |
455
+ | `missing` | In the profile and the catalog, but not installed. |
456
+ | `drift` | Pinned and installed, but at a different version. |
457
+ | `unverifiable` | Pinned and installed, but the installed version can't be read. |
458
+ | `unpinnable` | Pinned, but this tool's install type can't honour a pin — the pin is ignored. |
459
+ | `unknown-key` | In the profile but not in this machine's catalog. |
460
+ | `extra` | Installed, but not in the profile. |
461
+
462
+ `unverifiable`, `unpinnable` and `unknown-key` are three different reasons the comparison couldn't
463
+ be made, each with a different remedy, and **none of them is ever reported as `ok`**. Versions are
464
+ compared as text: `0.45` is not `0.45.0`, and a *newer* installed version is as much drift as an
465
+ older one.
466
+
467
+ By default only differences are listed; the matching tools are counted in the last line, and
468
+ `--all` lists them (and the extras) as rows. `--json` writes one array — every state, always — of
469
+ `{"key", "state", "type", "pinned", "installed", "note"}` objects and nothing else, even at `-vv`.
470
+
471
+ **Exit status.** `0` whenever the comparison ran, whatever it found. With `--exit-code` it is `1`
472
+ if the machine differs; an installed tool that isn't in the profile counts as a difference unless
473
+ you also pass `--ignore-extras`, which affects only this exit status and never hides a real
474
+ difference. A profile that is missing, unreadable or invalid is always `2`, so `1` can only ever
475
+ mean "differs".
476
+
477
+ ---
478
+
317
479
  ### `configure`
318
480
 
319
481
  Set up an installed tool through a guided wizard, previewing the result before anything is
@@ -287,6 +287,168 @@ 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
+
348
+ ### `profile`
349
+
350
+ Describe which tools a machine should have as a small file, and compare a machine against one.
351
+ Both subcommands are **read-only** and **local** — they ask the machine, never the network — so
352
+ they work offline.
353
+
354
+ ```bash
355
+ devstuff profile snapshot > work.yaml # the tools installed here, as a file
356
+ devstuff profile snapshot --versions -o work.yaml # ...and the versions of the ones that can be pinned
357
+ devstuff profile diff work.yaml # how this machine differs from the file
358
+ devstuff profile diff work.yaml --exit-code # exit 1 if it differs: a gate for CI
359
+ ```
360
+
361
+ > **The file format is provisional until `profile apply` exists.** It is `version: 1`, and a later
362
+ > breaking change will bump that number. There is no `apply` yet — nothing here installs anything.
363
+
364
+ A profile names catalog **keys**, and optionally a version. It never contains an install script or
365
+ a tool definition, so a profile from somewhere else can't run anything your own catalog doesn't
366
+ already define.
367
+
368
+ ```yaml
369
+ version: 1
370
+ tools:
371
+ uv: {} # present, any version
372
+ ipython:
373
+ version: 9.17.1 # present, at exactly this version
374
+ ```
375
+
376
+ **Quote any version that looks like a number.** YAML reads `version: 1.10` as the number 1.1 and
377
+ `0.40` as 0.4, and the original text can't be recovered — so devstuff refuses it and says to quote
378
+ it (`version: '1.10'`). It also refuses a duplicate key, which YAML would otherwise resolve by
379
+ silently dropping the first, an unknown field, and a tool key that YAML reads as something other
380
+ than text (`on`, `yes`, `123`). `snapshot` always writes versions correctly quoted.
381
+
382
+ #### `snapshot`
383
+
384
+ Writes a profile of every installed tool, to stdout or to `-o FILE`. By default it records **keys
385
+ only**: a profile that pins versions goes stale the day a tool updates, and then reports drift
386
+ nobody intended. `--versions` adds the installed version for the tools that can be pinned — `npm`,
387
+ `pip`/`uvx`, and single-package `apt`; `git`, `script` and `bash` tools can't be installed at a
388
+ chosen version, so a version recorded for them could never be acted on and is left out.
389
+
390
+ - If a pinnable tool's version can't be read (say it is on your `PATH` but isn't a `uv tool`), it is
391
+ written without one and a warning on stderr names it and says why — it is never dropped silently.
392
+ - Tools defined in your own catalog are included, with one stderr note that another machine won't
393
+ know them: move their definitions with `devstuff catalog export` / `import`.
394
+ - Output is **deterministic** — sorted, with a fixed header and no timestamp, hostname or path — so
395
+ a profile kept in git shows only real changes.
396
+ - `-o` refuses to overwrite an existing file (exit 2) unless you pass `--force`.
397
+ - With no `-o`, stdout is exactly the YAML; warnings and notes go to stderr.
398
+
399
+ #### `diff`
400
+
401
+ ```
402
+ ╭──────────────────────────────────────────────────────────────────────────────╮
403
+ │ Package Type Profile Installed Status │
404
+ ├──────────────────────────────────────────────────────────────────────────────┤
405
+ │ reptyr apt ✘ missing │
406
+ │ ipython uvx 9.0.0 9.17.1 ≠ drift │
407
+ │ commitizen uvx 4.16.4 ? unverifiable │
408
+ │ uv doesn't list it as a tool │
409
+ │ (is it installed another │
410
+ │ way?) │
411
+ │ starship bash 1.0.0 – unpinnable │
412
+ │ a bash install can't be │
413
+ │ pinned, so the pin is ignored │
414
+ │ not-a-real-tool ? unknown-key │
415
+ │ not in this machine's catalog │
416
+ │ — if it is a custom tool, │
417
+ │ bring its definition over │
418
+ │ with `devstuff catalog │
419
+ │ import` │
420
+ ╰──────────────────────────────────────────────────────────────────────────────╯
421
+ 1 installed tool isn't in the profile: gh (--all lists them)
422
+ 1 missing · 1 drift · 1 unverifiable · 1 unpinnable · 1 unknown-key · 1 extra · 9 ok
423
+ ```
424
+
425
+ | State | Meaning |
426
+ |-------|---------|
427
+ | `ok` | In the profile and installed; and, if pinned, at the pinned version. |
428
+ | `missing` | In the profile and the catalog, but not installed. |
429
+ | `drift` | Pinned and installed, but at a different version. |
430
+ | `unverifiable` | Pinned and installed, but the installed version can't be read. |
431
+ | `unpinnable` | Pinned, but this tool's install type can't honour a pin — the pin is ignored. |
432
+ | `unknown-key` | In the profile but not in this machine's catalog. |
433
+ | `extra` | Installed, but not in the profile. |
434
+
435
+ `unverifiable`, `unpinnable` and `unknown-key` are three different reasons the comparison couldn't
436
+ be made, each with a different remedy, and **none of them is ever reported as `ok`**. Versions are
437
+ compared as text: `0.45` is not `0.45.0`, and a *newer* installed version is as much drift as an
438
+ older one.
439
+
440
+ By default only differences are listed; the matching tools are counted in the last line, and
441
+ `--all` lists them (and the extras) as rows. `--json` writes one array — every state, always — of
442
+ `{"key", "state", "type", "pinned", "installed", "note"}` objects and nothing else, even at `-vv`.
443
+
444
+ **Exit status.** `0` whenever the comparison ran, whatever it found. With `--exit-code` it is `1`
445
+ if the machine differs; an installed tool that isn't in the profile counts as a difference unless
446
+ you also pass `--ignore-extras`, which affects only this exit status and never hides a real
447
+ difference. A profile that is missing, unreadable or invalid is always `2`, so `1` can only ever
448
+ mean "differs".
449
+
450
+ ---
451
+
290
452
  ### `configure`
291
453
 
292
454
  Set up an installed tool through a guided wizard, previewing the result before anything is
@@ -0,0 +1,189 @@
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
+ **Spec:** [`specs/profile/`](specs/profile/) — **done** (v1, 2026-10-10): `snapshot` and `diff`. `apply` (M3) gets its own requirements.
68
+
69
+ A profile is a YAML file: catalog keys and optional pinned versions. Configurator output is **not** part of it
70
+ (several configurators don't round-trip); capturing it is a separate, later decision.
71
+
72
+ ```yaml
73
+ version: 1
74
+ tools:
75
+ uv: {}
76
+ lazygit: { version: 0.45.0 }
77
+ starship: {}
78
+ ```
79
+
80
+ **Built** (v1, 2026-10-10): `profile snapshot` and `profile diff` (spec milestones P1–P6). The format is **provisional**
81
+ until M3 exists. What the design turned into, where it differs from the first sketch:
82
+ - **Versions are read locally, per type** (`installed_version()`), never from `get_version()`'s free text and never
83
+ via the update checkers, which hit the network. Only types that can be pinned (`npm`, `pip`/`uvx`, single-package
84
+ `apt`) ever get a version. So `snapshot` works offline.
85
+ - **`diff` reports seven states**, not four: `ok`, `missing`, `drift`, `unverifiable`, `unpinnable`, `unknown-key`,
86
+ `extra`. The three "could not compare" ones are never `ok` — the M1 lesson, applied again.
87
+ - **Loading is strict beyond the catalog's own rules**: YAML silently turns `version: 1.10` into `1.1` and drops
88
+ duplicate keys, so both are errors rather than coerced.
89
+ - A profile references catalog keys only and never embeds install scripts, so a profile file can't smuggle commands
90
+ past the catalog's validation. A custom tool is `unknown-key` on a machine without it; `catalog export`/`import`
91
+ moves definitions.
92
+ - `--exit-code` shipped in v1 (`1` = differs, `2` = bad profile), unlike `outdated`'s, because drift-gating is this
93
+ feature's headline use.
94
+
95
+ **Done when**
96
+ - [x] `profile snapshot` writes a valid profile; `profile diff` of a fresh snapshot against the same machine reports
97
+ no differences — tested on a fake machine, and live on a real one (`13 ok`, exit 0).
98
+ - [x] Keys unknown to the effective catalog are reported, not silently dropped (`unknown-key`).
99
+ - [x] Spec records the rejected alternative of extending `catalog export` instead, with reasons (`stack-decisions.md` SD-1).
100
+
101
+ ## M3 — `devstuff profile apply` and bundled bundles
102
+
103
+ Turn a profile into an install plan and run it.
104
+
105
+ - **Ordering** comes from the existing `requires` graph (including auto-inferred edges such as
106
+ `npm` → `nvm`). Do not write a second dependency resolver; if the existing one is not exposed in
107
+ a reusable form, factor it out first.
108
+ - **Plan before action**: `apply` shows what it will do and asks first. The plan-preview helper
109
+ `install`/`update` are gaining lives on the unmerged UI branch (`commands/_plan.py`); reuse it if it
110
+ has landed, rather than writing a second one.
111
+ - **Failure policy** needs a decision in the spec: continue past a failed tool and summarise, or
112
+ stop. Recommendation: continue, skip anything whose `requires` failed, and report at the end —
113
+ a 40-tool apply that dies on tool 3 is worse than one that finishes 39.
114
+ - **Pins on `git`/`script`/`bash` tools cannot be honoured at all** — `update(version=…)` raises for them
115
+ (spec F-2) — and `diff` already reports them `unpinnable`. `apply` must say so rather than quietly
116
+ install latest.
117
+ - **A pinned install is install-then-update**: `install()` takes no version (spec F-4), so applying a pin
118
+ means installing the latest and then calling `update(version=…)` — two installs, and for `apt` a
119
+ downgrade. Whether to teach the `npm`/`uvx`/`apt` installers a version instead is an M3 decision.
120
+ - **Bundled bundles** (`@backend`, `@devops`, …) are profile files shipped in the package. They are
121
+ data, so they get a validation test and a CI check that every key they name exists in the
122
+ bundled catalog — the same two-direction enforcement as the CI-matrix test.
123
+ - **Configurator state**: restoring starship/lazygit/bat configuration is the differentiator over
124
+ a dotfiles repo, but several configurators do not round-trip (pre-commit and commitizen
125
+ explicitly do not). Scope M3 to tools only and treat configurator capture as a separate,
126
+ later decision recorded in the spec's open questions.
127
+
128
+ **Done when**
129
+ - [ ] `apply` on an empty container (the existing Docker integration harness) reproduces a
130
+ snapshot taken elsewhere.
131
+ - [ ] A failing tool does not abort the run; dependents are skipped with a stated reason.
132
+ - [ ] Every bundled bundle passes the key-exists test.
133
+
134
+ ## M4 — Agent tools for `doctor` and `outdated`
135
+
136
+ Expose both as agent tools so the local model can answer "why is my nvm broken?" by running the
137
+ checks. Per `CLAUDE.md` this is mostly a YAML edit (`impl: catalog` / `impl: primitive` in
138
+ `agent_tools.yaml`); `agent_tools.schema.json` must be updated in the same change if any field is
139
+ added.
140
+
141
+ - `outdated` is read-only and safe to expose unconditionally.
142
+ - `doctor --fix` mutates the machine, so the agent gets the **check-only** form. A model
143
+ deciding to apply fixes is a separate question for the spec, not a default.
144
+
145
+ ## M5 — Shell completion
146
+
147
+ `devstuff completion bash|zsh|fish`, built on Click's native completion support.
148
+
149
+ - The value is **dynamic completion of catalog keys** for `install`, `remove`, `update` and
150
+ `configure`, which means completing from the *effective* catalog (bundled + user), not a
151
+ generated static list.
152
+ - Completion runs on every `<TAB>`: it must not shell out to probes. Keys only, no
153
+ install-state lookups.
154
+ - Document the one-line install in README.md alongside the existing shell-integration notes.
155
+
156
+ ---
157
+
158
+ ## Unscheduled candidates
159
+
160
+ **git / tmux configurator.** Same shape as the seven existing wizards, and the same first step
161
+ applies: before writing anything, find what the tool's own validator does *not* check. For git
162
+ that means measuring which `git config` keys are silently accepted and ignored.
163
+
164
+ **`devstuff sandbox <tool>`.** Try an install in a throwaway container before it touches the
165
+ host, reusing the Docker integration-test machinery. Not scheduled because it depends on Docker
166
+ being present, which the tool cannot assume, and because it overlaps `-vv` plan previews for the
167
+ "what will this do?" question.
168
+
169
+ ## Non-goals
170
+
171
+ - **Not a configuration-management system.** `profile` converges a *developer machine* onto a
172
+ list of catalog tools. It is not Ansible and will not grow conditionals, templating, or
173
+ inventory.
174
+ - **No remote profile registry or sync service** in this roadmap. Profiles are files; sharing
175
+ them is the user's git repo.
176
+ - **No new install `type`s.** Nothing here adds a mechanism to `GenericTool`; every milestone
177
+ composes what exists.
178
+ - **No runtime dependencies.** Same rule the agent follows: devstuff is globally installed, and
179
+ every dependency is paid for by users who never run the new command.
180
+
181
+ ## Risks
182
+
183
+ | Risk | Affects | Mitigation |
184
+ |------|---------|------------|
185
+ | 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 |
186
+ | `script`/`bash` tools dominate the catalog and are unverifiable | M1–M3 | Make "unknown" a first-class state everywhere rather than an edge case |
187
+ | `apply` partially succeeds and leaves a half-built machine | M3 | Plan preview, continue-and-summarise policy, dependents skipped with reasons |
188
+ | Profile format hardens before `apply` has been tried | M2 | Ship `snapshot`/`diff` as `version: 1` but mark the format provisional until M3 lands |
189
+ | Scope creep into configurator capture | M3 | Explicit non-goal above; revisit as its own spec |
@@ -47,3 +47,5 @@ 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) |
51
+ | [`profile/`](profile/) — `devstuff profile snapshot` / `diff`, a portable description of a machine's tools | Complete (v1: snapshot, diff; apply is M3) |