devstuff 2.11.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.11.0 → devstuff-2.12.0}/CHANGELOG.md +10 -0
  2. {devstuff-2.11.0 → devstuff-2.12.0}/CLAUDE.md +33 -1
  3. {devstuff-2.11.0 → devstuff-2.12.0}/PKG-INFO +105 -1
  4. {devstuff-2.11.0 → devstuff-2.12.0}/README.md +104 -0
  5. {devstuff-2.11.0 → devstuff-2.12.0}/docs/ROADMAP.md +31 -19
  6. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/README.md +1 -0
  7. devstuff-2.12.0/docs/specs/profile/development-plan.md +127 -0
  8. devstuff-2.12.0/docs/specs/profile/specifications.md +213 -0
  9. devstuff-2.12.0/docs/specs/profile/stack-decisions.md +134 -0
  10. {devstuff-2.11.0 → devstuff-2.12.0}/pyproject.toml +1 -1
  11. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/cli.py +2 -0
  12. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/help_cmd.py +1 -0
  13. devstuff-2.12.0/src/dev_setup/commands/profile_cmd.py +199 -0
  14. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/generic.py +78 -6
  15. devstuff-2.12.0/src/dev_setup/profile.py +353 -0
  16. devstuff-2.12.0/src/dev_setup/snapshot.py +131 -0
  17. devstuff-2.12.0/tests/test_installed_version.py +213 -0
  18. devstuff-2.12.0/tests/test_pin_support.py +120 -0
  19. devstuff-2.12.0/tests/test_profile.py +340 -0
  20. devstuff-2.12.0/tests/test_profile_diff.py +333 -0
  21. devstuff-2.12.0/tests/test_profile_diff_cmd.py +521 -0
  22. devstuff-2.12.0/tests/test_profile_snapshot_cmd.py +294 -0
  23. devstuff-2.12.0/tests/test_snapshot.py +188 -0
  24. devstuff-2.12.0/tests/test_update_checker_parity.py +120 -0
  25. {devstuff-2.11.0 → devstuff-2.12.0}/uv.lock +1 -1
  26. {devstuff-2.11.0 → devstuff-2.12.0}/.claude/skills/run-stuff/SKILL.md +0 -0
  27. {devstuff-2.11.0 → devstuff-2.12.0}/.claude/skills/run-stuff/smoke.sh +0 -0
  28. {devstuff-2.11.0 → devstuff-2.12.0}/.github/codex/review.md +0 -0
  29. {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/agent.yml +0 -0
  30. {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/bump.yml +0 -0
  31. {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/ci.yml +0 -0
  32. {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/publish.yml +0 -0
  33. {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/test-installs.yml +0 -0
  34. {devstuff-2.11.0 → devstuff-2.12.0}/.gitignore +0 -0
  35. {devstuff-2.11.0 → devstuff-2.12.0}/dev/Dockerfile +0 -0
  36. {devstuff-2.11.0 → devstuff-2.12.0}/dev/Dockerfile.ci +0 -0
  37. {devstuff-2.11.0 → devstuff-2.12.0}/dev/Makefile +0 -0
  38. {devstuff-2.11.0 → devstuff-2.12.0}/dev/docker-compose.yml +0 -0
  39. {devstuff-2.11.0 → devstuff-2.12.0}/devstuff +0 -0
  40. {devstuff-2.11.0 → devstuff-2.12.0}/docs/github-agent.md +0 -0
  41. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/agent/development-plan.md +0 -0
  42. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/agent/specifications.md +0 -0
  43. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/agent/stack-decisions.md +0 -0
  44. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/ansible-config/development-plan.md +0 -0
  45. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/ansible-config/specifications.md +0 -0
  46. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
  47. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/bat-config/development-plan.md +0 -0
  48. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/bat-config/specifications.md +0 -0
  49. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/bat-config/stack-decisions.md +0 -0
  50. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/commitizen-config/development-plan.md +0 -0
  51. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/commitizen-config/specifications.md +0 -0
  52. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
  53. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/docker-config/development-plan.md +0 -0
  54. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/docker-config/specifications.md +0 -0
  55. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/docker-config/stack-decisions.md +0 -0
  56. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/lazygit-config/development-plan.md +0 -0
  57. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/lazygit-config/specifications.md +0 -0
  58. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
  59. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/outdated/development-plan.md +0 -0
  60. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/outdated/specifications.md +0 -0
  61. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/outdated/stack-decisions.md +0 -0
  62. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/precommit-config/development-plan.md +0 -0
  63. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/precommit-config/specifications.md +0 -0
  64. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
  65. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/starship-config/development-plan.md +0 -0
  66. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/starship-config/specifications.md +0 -0
  67. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/starship-config/stack-decisions.md +0 -0
  68. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/uv-backbone/development-plan.md +0 -0
  69. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/uv-backbone/specifications.md +0 -0
  70. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
  71. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/verbose-mode/development-plan.md +0 -0
  72. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/verbose-mode/specifications.md +0 -0
  73. {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
  74. {devstuff-2.11.0 → devstuff-2.12.0}/install.sh +0 -0
  75. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/__init__.py +0 -0
  76. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/__main__.py +0 -0
  77. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/__init__.py +0 -0
  78. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/approval.py +0 -0
  79. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/bridges.py +0 -0
  80. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/catalog.py +0 -0
  81. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/completion.py +0 -0
  82. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/config.py +0 -0
  83. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/loop.py +0 -0
  84. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/ollama.py +0 -0
  85. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/preflight.py +0 -0
  86. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/primitives.py +0 -0
  87. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/registry.py +0 -0
  88. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/sandbox.py +0 -0
  89. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/session.py +0 -0
  90. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/transcript.py +0 -0
  91. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/wizard.py +0 -0
  92. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent_tools.schema.json +0 -0
  93. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent_tools.yaml +0 -0
  94. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/base.py +0 -0
  95. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/catalog.py +0 -0
  96. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/__init__.py +0 -0
  97. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/add_cmd.py +0 -0
  98. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/agent_cmd.py +0 -0
  99. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
  100. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/configure_cmd.py +0 -0
  101. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/delete_cmd.py +0 -0
  102. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/docs_cmd.py +0 -0
  103. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
  104. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/functions_cmd.py +0 -0
  105. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/install_cmd.py +0 -0
  106. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/links_cmd.py +0 -0
  107. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/list_cmd.py +0 -0
  108. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/outdated_cmd.py +0 -0
  109. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/remove_cmd.py +0 -0
  110. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/run_cmd.py +0 -0
  111. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/skills_cmd.py +0 -0
  112. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/update_cmd.py +0 -0
  113. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/__init__.py +0 -0
  114. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
  115. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/detect.py +0 -0
  116. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/model.py +0 -0
  117. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/render.py +0 -0
  118. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/validate.py +0 -0
  119. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
  120. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/__init__.py +0 -0
  121. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/detect.py +0 -0
  122. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/model.py +0 -0
  123. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/preview.py +0 -0
  124. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/render.py +0 -0
  125. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/wizard.py +0 -0
  126. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
  127. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
  128. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/model.py +0 -0
  129. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/render.py +0 -0
  130. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
  131. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
  132. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/__init__.py +0 -0
  133. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/detect.py +0 -0
  134. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/model.py +0 -0
  135. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/render.py +0 -0
  136. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/validate.py +0 -0
  137. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/wizard.py +0 -0
  138. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
  139. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
  140. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/model.py +0 -0
  141. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/render.py +0 -0
  142. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
  143. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
  144. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
  145. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/detect.py +0 -0
  146. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/model.py +0 -0
  147. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/render.py +0 -0
  148. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/validate.py +0 -0
  149. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
  150. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
  151. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
  152. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/__init__.py +0 -0
  153. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/fonts.py +0 -0
  154. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/icons.py +0 -0
  155. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/model.py +0 -0
  156. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/preview.py +0 -0
  157. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/render.py +0 -0
  158. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/wizard.py +0 -0
  159. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/doctor.py +0 -0
  160. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/function_runner.py +0 -0
  161. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions.schema.json +0 -0
  162. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions.yaml +0 -0
  163. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions_catalog.py +0 -0
  164. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions_registry.py +0 -0
  165. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links.schema.json +0 -0
  166. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links.yaml +0 -0
  167. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links_catalog.py +0 -0
  168. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links_registry.py +0 -0
  169. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/registry.py +0 -0
  170. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/tools.yaml +0 -0
  171. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/ui.py +0 -0
  172. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/updates.py +0 -0
  173. {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/verbose.py +0 -0
  174. {devstuff-2.11.0 → devstuff-2.12.0}/tests/__init__.py +0 -0
  175. {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/__init__.py +0 -0
  176. {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/conftest.py +0 -0
  177. {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_agent_smoke.py +0 -0
  178. {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_agent_tui.py +0 -0
  179. {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_commitizen_config.py +0 -0
  180. {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_tools.py +0 -0
  181. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent.py +0 -0
  182. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_completion.py +0 -0
  183. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_loop.py +0 -0
  184. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_sandbox.py +0 -0
  185. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_tools.py +0 -0
  186. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_wizard.py +0 -0
  187. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_catalog.py +0 -0
  188. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_ansible.py +0 -0
  189. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_bat.py +0 -0
  190. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_commitizen.py +0 -0
  191. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_docker.py +0 -0
  192. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_lazygit.py +0 -0
  193. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_precommit.py +0 -0
  194. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_reptyr.py +0 -0
  195. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_starship.py +0 -0
  196. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_doctor.py +0 -0
  197. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_functions.py +0 -0
  198. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_generic.py +0 -0
  199. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_links.py +0 -0
  200. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_outdated_cmd.py +0 -0
  201. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_registry.py +0 -0
  202. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_update_notes.py +0 -0
  203. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_updates.py +0 -0
  204. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_uv_probes.py +0 -0
  205. {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_verbose.py +0 -0
@@ -1,3 +1,13 @@
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
+
1
11
  ## v2.11.0 (2026-10-10)
2
12
 
3
13
  ### Features
@@ -65,8 +65,10 @@ src/dev_setup/
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
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
68
70
  ├── configure/ # Per-tool setup wizards (see "Configurators" below)
69
- └── commands/ # One Click command per file: list, install, remove, update, outdated, add, delete, docs, catalog
71
+ └── commands/ # One Click command per file: list, install, remove, update, outdated, profile, add, delete, docs, catalog
70
72
  ```
71
73
 
72
74
  **Catalog precedence** (`catalog.load_effective_catalog`): bundled `tools.yaml` loads first →
@@ -155,6 +157,36 @@ and `devstuff outdated` share one collector and one classifier. Things that are
155
157
  - **Exit status is "did the lookup run", not the answer** (the same rule as `run_cmd`), and `--json`
156
158
  writes only the array to stdout, even at `-vv`.
157
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
+
158
190
  **Two ways a tool gets defined**: built-in (an entry added directly to `src/dev_setup/tools.yaml`,
159
191
  `builtin=True`) or custom (created via the `devstuff add` wizard, `devstuff catalog import`,
160
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.11.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>
@@ -372,6 +372,110 @@ includes the `unsupported` rows; `--updates-only` applies to it too.
372
372
 
373
373
  ---
374
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
+
375
479
  ### `configure`
376
480
 
377
481
  Set up an installed tool through a guided wizard, previewing the result before anything is
@@ -345,6 +345,110 @@ includes the `unsupported` rows; `--updates-only` applies to it too.
345
345
 
346
346
  ---
347
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
+
348
452
  ### `configure`
349
453
 
350
454
  Set up an installed tool through a guided wizard, previewing the result before anything is
@@ -64,7 +64,10 @@ over an existing probe and an existing collector, not new probing.
64
64
 
65
65
  ## M2 — `devstuff profile snapshot` and `diff`
66
66
 
67
- A profile is a YAML file: catalog keys, optional pinned versions, optional configurator output.
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.
68
71
 
69
72
  ```yaml
70
73
  version: 1
@@ -74,22 +77,26 @@ tools:
74
77
  starship: {}
75
78
  ```
76
79
 
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.
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.
87
94
 
88
95
  **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.
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).
93
100
 
94
101
  ## M3 — `devstuff profile apply` and bundled bundles
95
102
 
@@ -98,13 +105,18 @@ Turn a profile into an install plan and run it.
98
105
  - **Ordering** comes from the existing `requires` graph (including auto-inferred edges such as
99
106
  `npm` → `nvm`). Do not write a second dependency resolver; if the existing one is not exposed in
100
107
  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.
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.
103
111
  - **Failure policy** needs a decision in the spec: continue past a failed tool and summarise, or
104
112
  stop. Recommendation: continue, skip anything whose `requires` failed, and report at the end —
105
113
  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.
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.
108
120
  - **Bundled bundles** (`@backend`, `@devops`, …) are profile files shipped in the package. They are
109
121
  data, so they get a validation test and a CI check that every key they name exists in the
110
122
  bundled catalog — the same two-direction enforcement as the CI-matrix test.
@@ -48,3 +48,4 @@ They are most useful when they capture:
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
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) |
@@ -0,0 +1,127 @@
1
+ # Development plan: `devstuff profile` (snapshot, diff)
2
+
3
+ **Date:** 2026-10-10
4
+ **Status:** Complete (v1), 2026-10-10
5
+
6
+ ---
7
+
8
+ ## Milestones
9
+
10
+ Each milestone is one commit. Ordering puts the pure, no-I/O pieces first so the rules that matter
11
+ are tested before any command exists — the order that worked for `outdated`.
12
+
13
+ | # | Milestone | Satisfies | State |
14
+ |---|-----------|-----------|-------|
15
+ | P1 | `dev_setup/profile.py`: `Profile` model, strict loader (duplicate-key detecting), deterministic dumper | FR-1–6, FR-9, FR-24, NFR-4 | **Done** 2026-10-10 |
16
+ | P2 | `GenericTool.installed_version()` (local readers factored out of the checkers), `supports_pin`, and the test tying it to `update(version=…)` | FR-10–12, FR-25–26, SD-3/4/10 | **Done** 2026-10-10 |
17
+ | P3 | `devstuff profile snapshot` (group + command, `-o`, `--versions`, `--force`, stderr notes), registered in the CLI and help table | FR-7–8, 13–14, 23, NFR-1/2 | **Done** 2026-10-10 |
18
+ | P4 | Diff classifier — pure function over (profile, installed state, catalog) → seven states, counts, ordering | FR-16–18, 20 | **Done** 2026-10-10 |
19
+ | P5 | `devstuff profile diff` (table, footer, `--all`, `--json`, `--exit-code`, `--ignore-extras`, exit 2 on bad profile) | FR-15, 19, 21–22, NFR-1 | **Done** 2026-10-10 |
20
+ | P6 | README command reference, CLAUDE.md rules, roadmap + specs index | — | **Done** 2026-10-10 |
21
+
22
+ P2 is the only milestone that changes existing behaviour (it factors the `dpkg-query` read out of
23
+ `_check_update_apt`; the npm and uv reads were already separate functions). It lands before any command uses
24
+ it, and its parity test pins that `check_for_update` returns what it did before.
25
+
26
+ ## Testing strategy
27
+
28
+ Unit-only; no network, no real installs — default suite, ~0.3 s each file.
29
+
30
+ - **Loader, exhaustively (P1).** One parametrized test over every rejection in FR-3–5: unknown
31
+ top-level field, unknown entry field, `tools` not a mapping, entry not a mapping, file version
32
+ `2`, a duplicate key, and each of `1.10`, `0.40`, `2`, `2026-09-30` as an unquoted `version`
33
+ (the F-5 inputs, verbatim). Each asserts the error names the file and the key. And the accepted
34
+ spellings: `uv: {}`, bare `uv:`, `version: '1.10'`.
35
+ - **Round trip (P1, NFR-4).** `load(dump(p)) == p` over versions that look numeric — `'0.45'`,
36
+ `'1.10'`, `'2'` — since that is exactly where a hand-rolled emitter would fail and `safe_dump`
37
+ must be proven to hold.
38
+ - **Determinism (P1/P3, FR-9).** Two snapshots of the same fake machine are byte-identical, and the
39
+ output contains no hostname, username, home path or digits that look like a date.
40
+ - **Pinnability matches reality (P2, FR-26).** For every install type, build a minimal tool, call
41
+ `update(version="1.2.3")` with the installers stubbed out, and assert it raises *iff*
42
+ `supports_pin` is False. This must fail if someone teaches `git` to pin without updating the
43
+ predicate — verified by temporarily breaking one side, like `outdated`'s renderer mutation check.
44
+ - **Local readers never touch the network (P2, NFR-2).** Stub `_probe` to record argv and assert
45
+ `installed_version()` issues only `npm list`, `uv tool list` or `dpkg-query` and never `npm view`,
46
+ `uv tool list --outdated`, `apt-cache policy` or `git ls-remote`.
47
+ - **Readers never raise (P2, FR-25).** A stub raising `RuntimeError` or timing out → `""`.
48
+ - **Snapshot (P3).** Default has no `version` keys; `--versions` adds them only for pinnable types;
49
+ an unreadable pinnable tool yields an entry *without* a version plus a stderr warning naming it
50
+ (FR-12); `-o` writes the file and leaves stdout empty; an existing `-o` target is refused without
51
+ `--force`; custom-catalog tools are included and counted on stderr (FR-13).
52
+ - **Stdout purity (P3/P5, NFR-1).** `snapshot` and `diff --json` at `-vv` with a fake tool whose
53
+ probe logs: stdout parses as YAML/JSON, stderr is non-empty so the test is not vacuous.
54
+ - **Classifier, exhaustively (P4).** One row per state, plus the pairs that must stay apart: a
55
+ pinned `bash` key (`unpinnable`) vs a pinned `npm` key whose version cannot be read
56
+ (`unverifiable`) vs a key the catalog lacks (`unknown-key`). Counts sum to keys considered, and
57
+ none of the three folds into `ok` (FR-17). A rendering test breaks the renderer so `unverifiable`
58
+ shows as `ok` and asserts the test fails — the guard that `outdated` needed and had.
59
+ - **Exit status (P5, FR-22).** Default `0` with differences present; `--exit-code` `1` on a
60
+ difference and `0` on a clean match; `extra` flips it unless `--ignore-extras`; a malformed
61
+ profile and a missing file are `2` both with and without `--exit-code`.
62
+ - **Read-only (P5, FR-15).** Fakes whose `install`/`remove`/`update` raise; the command completes.
63
+ - **Self-diff (NFR-4).** On a fake machine, `diff(snapshot())` reports no differences, and with
64
+ `--versions` too.
65
+
66
+ **Live verification** (not in the suite; recorded here when done): on a real machine, `snapshot
67
+ --versions` then `diff` reports clean; then pin one tool to a wrong version, uninstall nothing, add
68
+ a bogus key, and check the report shows exactly `drift` and `unknown-key` and exits `1` under
69
+ `--exit-code`. Repeat `snapshot` with the network blocked — it must succeed, since it asks the
70
+ network nothing (NFR-2). `outdated`'s equivalent step found a real bug (its F-7) that the unit tests
71
+ could not, so this step is not optional.
72
+
73
+ **P2 verification, 2026-10-10.** 65 tests across `test_update_checker_parity.py` (baseline written and run against the
74
+ *unrefactored* code first), `test_pin_support.py` and `test_installed_version.py`. Twelve deliberate breakages were each caught
75
+ — but only after strengthening three tests that the first round let survive: the pin test treated *any* `RuntimeError` as
76
+ "refused the pin" (so an updater that quietly accepted one, then failed on a missing clone, passed); the never-raises test
77
+ never reached the outer guard because the inner readers swallow their own errors; and a get_version() trap raised inside
78
+ a function that swallows exceptions. Live on a real machine: `commitizen` is pinnable by type but unreadable (not a `uv tool`),
79
+ which is precisely the `unverifiable` state; results are identical with the network blocked.
80
+
81
+ **P3 verification, 2026-10-10.** 42 tests (`test_snapshot.py`, `test_profile_snapshot_cmd.py`); 17 deliberate breakages, 16 caught
82
+ first time. The survivor was real: `snapshot` guards against an `installed_version()` that raises, but the real one never does, so
83
+ nothing exercised the guard — now tested. Live on a real machine: default output is keys only; `--versions` pins exactly the four
84
+ readable tools and writes `commitizen` bare with a warning naming it and why; a second `-o` is refused with exit 2; with the network
85
+ blocked it succeeds in 1.9 s with output byte-identical to online; three runs hash identically; no hostname, user, home path or
86
+ year appears in the output.
87
+
88
+ **P4 verification, 2026-10-10.** 109 tests in `test_profile_diff.py`, 72 of them one parametrized case per valid combination of
89
+ (in profile, pin, catalog knows, installed, pinnable, version read) — 96 raw, less the 24 that would pin a key not in the profile: each asserts the spec's rule for that combination, and a
90
+ second test asserts the grid reaches all seven states, so a state the table never produces cannot hide. The FR-17 property is
91
+ also stated directly — `ok` implies the comparison genuinely succeeded. 18 deliberate breakages, all caught first time: each
92
+ "could not compare" state rendered as `ok`, the precedence between `missing`/`unpinnable`/`unknown-key`, version comparison made
93
+ to normalise or to order, extras handling in `differs`, and a summary that omits zero counts.
94
+
95
+ **P5 verification, 2026-10-10.** 49 tests in `test_profile_diff_cmd.py`; 28 deliberate breakages, 25 caught first time. The three
96
+ survivors were each a real gap: the shared fixture's only missing tool was *unpinned* so nothing tempted a read of a pinned,
97
+ uninstalled tool; no test made a version reader raise during a diff; and the notes in real use are fixed strings, so only a direct
98
+ call could prove bracket-escaping. All now tested. One test needed `isatty()` forced true on CliRunner's stream — under a plain
99
+ runner the banner/spinner guard is never reached, so "no banner under --json" passes whatever the code does.
100
+
101
+ Live on a real machine: a fresh `snapshot --versions` diffs clean (`13 ok`, exit 0). Then, with `ipython` pinned wrong, `starship`
102
+ (bash) pinned, `commitizen` pinned (it is on PATH but not a `uv tool`), `gh` removed, an uninstalled tool and a bogus key added,
103
+ the report named exactly `missing`, `drift`, `unverifiable`, `unpinnable`, `unknown-key` and `extra`, and `--exit-code` gave 1. A
104
+ pin written `1.10` and a missing file both gave 2. With the network blocked: 1.5 s, same answer.
105
+
106
+ **P6, 2026-10-10.** README command reference, CLAUDE.md rules, roadmap and specs index. Re-reading the roadmap against what was
107
+ built found its M2 section stale in three ways (it said a snapshot probes `get_version()`, that `diff` has four states, and its
108
+ done-when boxes were unticked) and its M3 section wrong in two (it pointed at `_plan.py`, which exists only on the unmerged UI
109
+ branch, and said pins on `script`/`bash` could be honoured by a reinstall, when `update(version=…)` raises for them). All fixed
110
+ in the same change, per `docs/specs/README.md`: "keep them current, or delete them".
111
+
112
+ ## Risks
113
+
114
+ | Risk | Likelihood | Mitigation |
115
+ |------|-----------|------------|
116
+ | The format hardens before `apply` has been tried (roadmap risk) | Medium | Mark the file format provisional in the README until M3 lands; `version: 1` stays reserved for the stabilised shape, and a later breaking change bumps it |
117
+ | Factoring local reads out of the update checkers (P2) subtly changes `outdated`/`update` | Medium | A parity test over each checker before and after; P2 is its own commit so a regression bisects to it |
118
+ | A profile pins a version the registry no longer serves, and `diff` reports `drift` forever | Medium | Intended — drift is what it says. `apply` (M3) decides what to do about an unobtainable pin |
119
+ | `unknown-key` is common because the user catalog differs between machines | High | It is a first-class state with its own wording and a pointer to `catalog export`/`import`, not an error |
120
+ | `--exit-code` gets wired into CI by people who then set `--ignore-extras` everywhere | Low | Not a risk to correctness; the flag exists for it |
121
+ | `apt` pins are flaky (a version string that exists only on one release) | Medium | Reported as `drift`/`unverifiable` truthfully; `apply` is where the cost lands, and it is deferred |
122
+
123
+ ## Out of scope for this plan
124
+
125
+ `apply`, bundled bundles, and configurator capture. `apply` needs its own requirements and a
126
+ decision on each constraint in `specifications.md` §6. Configurator capture is a separate spec
127
+ and does not block M3.