devstuff 2.24.0__tar.gz → 2.26.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 (284) hide show
  1. {devstuff-2.24.0 → devstuff-2.26.0}/.github/workflows/test-installs.yml +1 -0
  2. {devstuff-2.24.0 → devstuff-2.26.0}/AGENTS.md +4 -3
  3. {devstuff-2.24.0 → devstuff-2.26.0}/CHANGELOG.md +17 -0
  4. {devstuff-2.24.0 → devstuff-2.26.0}/CLAUDE.md +62 -2
  5. {devstuff-2.24.0 → devstuff-2.26.0}/PKG-INFO +39 -1
  6. {devstuff-2.24.0 → devstuff-2.26.0}/README.md +38 -0
  7. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/README.md +2 -0
  8. devstuff-2.26.0/docs/specs/btop-config/development-plan.md +86 -0
  9. devstuff-2.26.0/docs/specs/btop-config/specifications.md +213 -0
  10. devstuff-2.26.0/docs/specs/btop-config/stack-decisions.md +150 -0
  11. devstuff-2.26.0/docs/specs/managed-by/development-plan.md +68 -0
  12. devstuff-2.26.0/docs/specs/managed-by/specifications.md +105 -0
  13. devstuff-2.26.0/docs/specs/managed-by/stack-decisions.md +53 -0
  14. {devstuff-2.24.0 → devstuff-2.26.0}/pyproject.toml +1 -1
  15. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/catalog.py +8 -0
  16. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/install_cmd.py +20 -9
  17. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/list_cmd.py +11 -7
  18. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/__init__.py +6 -0
  19. devstuff-2.26.0/src/dev_setup/configure/btop/__init__.py +2 -0
  20. devstuff-2.26.0/src/dev_setup/configure/btop/capability.py +107 -0
  21. devstuff-2.26.0/src/dev_setup/configure/btop/detect.py +370 -0
  22. devstuff-2.26.0/src/dev_setup/configure/btop/model.py +306 -0
  23. devstuff-2.26.0/src/dev_setup/configure/btop/render.py +242 -0
  24. devstuff-2.26.0/src/dev_setup/configure/btop/validate.py +429 -0
  25. devstuff-2.26.0/src/dev_setup/configure/btop/wizard.py +513 -0
  26. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/generic.py +3 -0
  27. devstuff-2.26.0/src/dev_setup/managers.py +281 -0
  28. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/tools.yaml +17 -0
  29. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_catalog.py +58 -0
  30. devstuff-2.26.0/tests/test_configure_btop.py +789 -0
  31. devstuff-2.26.0/tests/test_managers.py +535 -0
  32. {devstuff-2.24.0 → devstuff-2.26.0}/uv.lock +1 -1
  33. {devstuff-2.24.0 → devstuff-2.26.0}/.claude/skills/run-stuff/SKILL.md +0 -0
  34. {devstuff-2.24.0 → devstuff-2.26.0}/.claude/skills/run-stuff/smoke.sh +0 -0
  35. {devstuff-2.24.0 → devstuff-2.26.0}/.github/codex/review.md +0 -0
  36. {devstuff-2.24.0 → devstuff-2.26.0}/.github/workflows/agent.yml +0 -0
  37. {devstuff-2.24.0 → devstuff-2.26.0}/.github/workflows/bump.yml +0 -0
  38. {devstuff-2.24.0 → devstuff-2.26.0}/.github/workflows/ci.yml +0 -0
  39. {devstuff-2.24.0 → devstuff-2.26.0}/.github/workflows/publish.yml +0 -0
  40. {devstuff-2.24.0 → devstuff-2.26.0}/.gitignore +0 -0
  41. {devstuff-2.24.0 → devstuff-2.26.0}/dev/Dockerfile +0 -0
  42. {devstuff-2.24.0 → devstuff-2.26.0}/dev/Dockerfile.ci +0 -0
  43. {devstuff-2.24.0 → devstuff-2.26.0}/dev/Makefile +0 -0
  44. {devstuff-2.24.0 → devstuff-2.26.0}/dev/docker-compose.yml +0 -0
  45. {devstuff-2.24.0 → devstuff-2.26.0}/devstuff +0 -0
  46. {devstuff-2.24.0 → devstuff-2.26.0}/docs/ROADMAP.md +0 -0
  47. {devstuff-2.24.0 → devstuff-2.26.0}/docs/github-agent.md +0 -0
  48. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/agent/development-plan.md +0 -0
  49. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/agent/specifications.md +0 -0
  50. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/agent/stack-decisions.md +0 -0
  51. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/ansible-config/development-plan.md +0 -0
  52. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/ansible-config/specifications.md +0 -0
  53. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
  54. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/bat-config/development-plan.md +0 -0
  55. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/bat-config/specifications.md +0 -0
  56. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/bat-config/stack-decisions.md +0 -0
  57. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/commitizen-config/development-plan.md +0 -0
  58. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/commitizen-config/specifications.md +0 -0
  59. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
  60. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/docker-config/development-plan.md +0 -0
  61. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/docker-config/specifications.md +0 -0
  62. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/docker-config/stack-decisions.md +0 -0
  63. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/fmhy-picks/development-plan.md +0 -0
  64. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/fmhy-picks/specifications.md +0 -0
  65. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/fmhy-picks/stack-decisions.md +0 -0
  66. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/lazygit-config/development-plan.md +0 -0
  67. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/lazygit-config/specifications.md +0 -0
  68. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
  69. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/mcp/development-plan.md +0 -0
  70. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/mcp/specifications.md +0 -0
  71. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/mcp/stack-decisions.md +0 -0
  72. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/outdated/development-plan.md +0 -0
  73. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/outdated/specifications.md +0 -0
  74. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/outdated/stack-decisions.md +0 -0
  75. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/plan-and-progress/specifications.md +0 -0
  76. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/precommit-config/development-plan.md +0 -0
  77. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/precommit-config/specifications.md +0 -0
  78. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
  79. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/profile/development-plan.md +0 -0
  80. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/profile/specifications.md +0 -0
  81. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/profile/stack-decisions.md +0 -0
  82. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/profile-apply/development-plan.md +0 -0
  83. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/profile-apply/specifications.md +0 -0
  84. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/profile-apply/stack-decisions.md +0 -0
  85. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/starship-config/development-plan.md +0 -0
  86. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/starship-config/specifications.md +0 -0
  87. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/starship-config/stack-decisions.md +0 -0
  88. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/syncthing-config/development-plan.md +0 -0
  89. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/syncthing-config/specifications.md +0 -0
  90. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/syncthing-config/stack-decisions.md +0 -0
  91. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/uv-backbone/development-plan.md +0 -0
  92. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/uv-backbone/specifications.md +0 -0
  93. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
  94. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/verbose-mode/development-plan.md +0 -0
  95. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/verbose-mode/specifications.md +0 -0
  96. {devstuff-2.24.0 → devstuff-2.26.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
  97. {devstuff-2.24.0 → devstuff-2.26.0}/install.sh +0 -0
  98. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/__init__.py +0 -0
  99. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/__main__.py +0 -0
  100. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/__init__.py +0 -0
  101. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/approval.py +0 -0
  102. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/bridges.py +0 -0
  103. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/catalog.py +0 -0
  104. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/completion.py +0 -0
  105. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/config.py +0 -0
  106. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/loop.py +0 -0
  107. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/ollama.py +0 -0
  108. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/preflight.py +0 -0
  109. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/primitives.py +0 -0
  110. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/registry.py +0 -0
  111. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/sandbox.py +0 -0
  112. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/session.py +0 -0
  113. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/transcript.py +0 -0
  114. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent/wizard.py +0 -0
  115. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent_tools.schema.json +0 -0
  116. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/agent_tools.yaml +0 -0
  117. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/apply_exec.py +0 -0
  118. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/apply_plan.py +0 -0
  119. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/base.py +0 -0
  120. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/bundles/ai-agents.yaml +0 -0
  121. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/bundles/ai-local.yaml +0 -0
  122. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/bundles/devops.yaml +0 -0
  123. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/bundles/essentials.yaml +0 -0
  124. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/bundles/languages.yaml +0 -0
  125. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/bundles/python.yaml +0 -0
  126. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/bundles.py +0 -0
  127. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/cli.py +0 -0
  128. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/__init__.py +0 -0
  129. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/_plan.py +0 -0
  130. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/add_cmd.py +0 -0
  131. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/agent_cmd.py +0 -0
  132. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
  133. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/configure_cmd.py +0 -0
  134. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/delete_cmd.py +0 -0
  135. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/docs_cmd.py +0 -0
  136. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
  137. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/functions_cmd.py +0 -0
  138. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/help_cmd.py +0 -0
  139. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/links_cmd.py +0 -0
  140. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/mcp_cmd.py +0 -0
  141. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/outdated_cmd.py +0 -0
  142. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/profile_cmd.py +0 -0
  143. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/remove_cmd.py +0 -0
  144. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/run_cmd.py +0 -0
  145. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/skills_cmd.py +0 -0
  146. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/commands/update_cmd.py +0 -0
  147. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
  148. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/ansible/detect.py +0 -0
  149. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/ansible/model.py +0 -0
  150. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/ansible/render.py +0 -0
  151. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/ansible/validate.py +0 -0
  152. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
  153. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/bat/__init__.py +0 -0
  154. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/bat/detect.py +0 -0
  155. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/bat/model.py +0 -0
  156. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/bat/preview.py +0 -0
  157. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/bat/render.py +0 -0
  158. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/bat/wizard.py +0 -0
  159. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
  160. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
  161. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/commitizen/model.py +0 -0
  162. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/commitizen/render.py +0 -0
  163. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
  164. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
  165. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/docker/__init__.py +0 -0
  166. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/docker/detect.py +0 -0
  167. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/docker/model.py +0 -0
  168. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/docker/render.py +0 -0
  169. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/docker/validate.py +0 -0
  170. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/docker/wizard.py +0 -0
  171. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
  172. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
  173. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/lazygit/model.py +0 -0
  174. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/lazygit/render.py +0 -0
  175. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
  176. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
  177. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
  178. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/precommit/detect.py +0 -0
  179. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/precommit/model.py +0 -0
  180. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/precommit/render.py +0 -0
  181. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/precommit/validate.py +0 -0
  182. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
  183. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
  184. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
  185. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/starship/__init__.py +0 -0
  186. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/starship/fonts.py +0 -0
  187. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/starship/icons.py +0 -0
  188. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/starship/model.py +0 -0
  189. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/starship/preview.py +0 -0
  190. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/starship/render.py +0 -0
  191. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/starship/wizard.py +0 -0
  192. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/syncthing/__init__.py +0 -0
  193. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/syncthing/api.py +0 -0
  194. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/syncthing/detect.py +0 -0
  195. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/syncthing/model.py +0 -0
  196. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/configure/syncthing/wizard.py +0 -0
  197. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/doctor.py +0 -0
  198. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/function_runner.py +0 -0
  199. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/functions.schema.json +0 -0
  200. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/functions.yaml +0 -0
  201. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/functions_catalog.py +0 -0
  202. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/functions_registry.py +0 -0
  203. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/links.schema.json +0 -0
  204. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/links.yaml +0 -0
  205. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/links_catalog.py +0 -0
  206. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/links_registry.py +0 -0
  207. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/__init__.py +0 -0
  208. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/core.py +0 -0
  209. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/http.py +0 -0
  210. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/openapi.py +0 -0
  211. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/printconfig.py +0 -0
  212. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/process.py +0 -0
  213. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/stdio.py +0 -0
  214. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/mcp/token.py +0 -0
  215. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/profile.py +0 -0
  216. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/registry.py +0 -0
  217. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/snapshot.py +0 -0
  218. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/ui.py +0 -0
  219. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/updates.py +0 -0
  220. {devstuff-2.24.0 → devstuff-2.26.0}/src/dev_setup/verbose.py +0 -0
  221. {devstuff-2.24.0 → devstuff-2.26.0}/tests/__init__.py +0 -0
  222. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/__init__.py +0 -0
  223. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/conftest.py +0 -0
  224. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/test_agent_smoke.py +0 -0
  225. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/test_agent_tui.py +0 -0
  226. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/test_commitizen_config.py +0 -0
  227. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/test_mcp_claude.py +0 -0
  228. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/test_mcp_conformance.py +0 -0
  229. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/test_profile_apply.py +0 -0
  230. {devstuff-2.24.0 → devstuff-2.26.0}/tests/integration/test_tools.py +0 -0
  231. {devstuff-2.24.0 → devstuff-2.26.0}/tests/mcp_http_support.py +0 -0
  232. {devstuff-2.24.0 → devstuff-2.26.0}/tests/mcp_process_support.py +0 -0
  233. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_agent.py +0 -0
  234. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_agent_bridges.py +0 -0
  235. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_agent_completion.py +0 -0
  236. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_agent_loop.py +0 -0
  237. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_agent_sandbox.py +0 -0
  238. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_agent_tools.py +0 -0
  239. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_agent_wizard.py +0 -0
  240. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_apply_exec.py +0 -0
  241. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_apply_plan.py +0 -0
  242. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_apply_run.py +0 -0
  243. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_bundles.py +0 -0
  244. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_catalog_scripts.py +0 -0
  245. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_ansible.py +0 -0
  246. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_bat.py +0 -0
  247. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_commitizen.py +0 -0
  248. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_docker.py +0 -0
  249. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_lazygit.py +0 -0
  250. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_precommit.py +0 -0
  251. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_reptyr.py +0 -0
  252. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_starship.py +0 -0
  253. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_configure_syncthing.py +0 -0
  254. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_doctor.py +0 -0
  255. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_functions.py +0 -0
  256. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_generic.py +0 -0
  257. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_installed_version.py +0 -0
  258. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_lifecycle_cmds.py +0 -0
  259. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_links.py +0 -0
  260. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_classify.py +0 -0
  261. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_core.py +0 -0
  262. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_http.py +0 -0
  263. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_http_cmd.py +0 -0
  264. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_openapi.py +0 -0
  265. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_printconfig.py +0 -0
  266. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_process.py +0 -0
  267. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_stdio.py +0 -0
  268. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_mcp_token.py +0 -0
  269. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_outdated_cmd.py +0 -0
  270. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_pin_support.py +0 -0
  271. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_plan_and_select.py +0 -0
  272. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_profile.py +0 -0
  273. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_profile_apply_cmd.py +0 -0
  274. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_profile_diff.py +0 -0
  275. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_profile_diff_cmd.py +0 -0
  276. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_profile_snapshot_cmd.py +0 -0
  277. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_registry.py +0 -0
  278. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_snapshot.py +0 -0
  279. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_ui.py +0 -0
  280. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_update_checker_parity.py +0 -0
  281. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_update_notes.py +0 -0
  282. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_updates.py +0 -0
  283. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_uv_probes.py +0 -0
  284. {devstuff-2.24.0 → devstuff-2.26.0}/tests/test_verbose.py +0 -0
@@ -56,6 +56,7 @@ jobs:
56
56
  - arcane-cli # release binary into /usr/local/bin
57
57
  - aws
58
58
  - bat
59
+ - btop # apt
59
60
  - bubblewrap # apt: bubblewrap + socat for Claude Code /sandbox
60
61
  - claude-code # npm tool, installs nvm first via `requires`
61
62
  - codex # npm tool, installs nvm first via `requires`
@@ -66,9 +66,9 @@ didn't have, is stated as exactly that: not as passing.
66
66
 
67
67
  Refresh with the `gh pr list` command above when this looks stale.
68
68
 
69
- | PR | Branch | Base | Notes |
70
- |---|---|---|---|
71
- | [#77](https://github.com/thesawdawg/dev-setup-py/pull/77) `delta`, `ripgrep`, `shellcheck`, `fzf`, `opencode` tools; lazygit wizard's delta install offer; five FMHY links | `feat/fmhy-picks` | `master` | Opened 2026-10-13. Also carries the AGENTS.md #76 follow-up commit. Not yet run: a real install of any of the five (no Docker on the dev host), so the CI canary is their first run; the lazygit wizard under a pty. |
69
+ | PR | Branch → base | What |
70
+ |---|---|---|
71
+ | [#78](https://github.com/thesawdawg/dev-setup-py/pull/78) | `feat/managed-by` → `master` | Manager notes (uv/nvm, system copies) in `list` and the `install` picker; `managed_by` catalog field |
72
72
 
73
73
  ### Closed as dropped
74
74
 
@@ -91,3 +91,4 @@ commits rather than merging `master` in.
91
91
  | [#62](https://github.com/thesawdawg/dev-setup-py/pull/62) plan preview, live progress view and the guided `add` wizard (merged 2026-10-11, released as 2.14.0) | (1) About ten older sites still put error text into `ui.error`/`ui.dim` unescaped, which raises `MarkupError` on a `[/…]`-shaped string: `configure_cmd`, `doctor_cmd`, `run_cmd`, `skills_cmd`, the commitizen and reptyr wizards, `add_cmd`. Escape with `rich.markup.escape` when touching one (see `docs/specs/plan-and-progress/`, F-1). (2) Not run live: `update` and its picker, the `install`/`remove` pickers, and the `npm`, `apt` and `git` installers under the progress view; unit-tested only. (3) Open design points, deliberately unchanged: a missing requirement asks three questions, and the `add` step counter reads `1/7` then `2/8`. |
92
92
  | [#75](https://github.com/thesawdawg/dev-setup-py/pull/75) `syncthing` tool and `configure syncthing` pairing wizard (merged 2026-10-12, released as 2.22.0) | (1) The first real `devstuff install syncthing`: the weekly `test-installs.yml` canary is its first run, where the no-user-session branch is the expected path. (2) The interactive wizard against a live user service, and `sudo loginctl enable-linger` itself. Both are unit-tested only, with a fake API client; the real-binary tests drive two throwaway daemons, not the wizard. When either happens, update "What was run and what was not" in `docs/specs/syncthing-config/development-plan.md` and the status row in `docs/specs/README.md`. |
93
93
  | [#76](https://github.com/thesawdawg/dev-setup-py/pull/76) `tmux`, `gum`, `bubblewrap` (+ `socat`) tools; Druid, Homepage, Server Box and tmux wiki links (merged 2026-10-13, released as 2.23.0) | The first real install of `tmux`, `gum` and `bubblewrap`: the dev host has no Docker, so the weekly `test-installs.yml` canary is their first run. The bubblewrap remove refusal and both-binaries check are tested with fake `apt-get`/`sudo` only. |
94
+ | [#77](https://github.com/thesawdawg/dev-setup-py/pull/77) `delta`, `ripgrep`, `shellcheck`, `fzf`, `opencode` tools; lazygit wizard's delta install offer; five FMHY links (merged 2026-10-13, released as 2.24.0) | (1) The first real install of all five: the weekly `test-installs.yml` canary is their first run. For fzf it confirms the binary and the `~/.bashrc` marker, not that the key bindings load (the CI image's fzf 0.44 has no `--bash`, and the minimized image likely lacks the fallback file). (2) The lazygit wizard's delta offer under a pty; tested with stubbed prompts only. When either happens, update "What was run and what was not" in `docs/specs/fmhy-picks/development-plan.md` and the status row in `docs/specs/README.md`. (3) Known, unfixed: an `apt` entry silently ignores `install_script` and `validate_catalog` accepts it (`docs/specs/fmhy-picks/stack-decisions.md`, D-3). |
@@ -1,3 +1,20 @@
1
+ ## v2.26.0 (2026-10-19)
2
+
3
+ ### Features
4
+
5
+ - **tools**: add btop and the 'devstuff configure btop' wizard
6
+
7
+ ### Bug Fixes
8
+
9
+ - **btop**: don't escape questionary prompts
10
+ - **btop**: escape check details at display, getcap parsing, rewrite detection
11
+
12
+ ## v2.25.0 (2026-10-13)
13
+
14
+ ### Features
15
+
16
+ - **list**: note which catalog tool manages, or could manage, each tool
17
+
1
18
  ## v2.24.0 (2026-10-13)
2
19
 
3
20
  ### Features
@@ -64,6 +64,7 @@ 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
+ ├── managers.py # Who manages a tool's installs (uv/nvm) — the notes `list` and the `install` picker show
67
68
  ├── updates.py # Update probing + the five-state classifier, shared by `update` and `outdated`
68
69
  ├── profile.py # Profile file format (strict load, deterministic dump) + the seven-state diff classifier — pure
69
70
  ├── snapshot.py # Asks the machine: builds a Profile / the facts `profile.compare` needs
@@ -160,6 +161,22 @@ and `devstuff outdated` share one collector and one classifier. Things that are
160
161
  - **Exit status is "did the lookup run", not the answer** (the same rule as `run_cmd`), and `--json`
161
162
  writes only the array to stdout, even at `-vv`.
162
163
 
164
+ **Manager notes** (`managers.py`, spec in `docs/specs/managed-by/`): `list` and the `install` picker
165
+ annotate a tool with the catalog manager that owns its installs — derived from the install type
166
+ (`uvx`/`pip` → uv, `npm` → nvm) or explicit via `managed_by` (python, pi). Things that are load-bearing:
167
+ - **Two signals, both measured on the machine.** The *type signal* reuses `outdated`'s probes —
168
+ `uv tool list` membership for uvx/pip, `npm ls -g` inside a sourced nvm for npm — so `list` and
169
+ `outdated` never disagree. The *path signal* is for explicit `managed_by` on other types: resolve
170
+ the tool's `version_cmd`/`check_cmd` binary and test `Path.is_relative_to` against the manager's
171
+ own reported roots (`uv tool dir`, `uv python dir`, `$NVM_DIR`). Never `str.startswith` —
172
+ `uv/python-other` shares a textual prefix with `uv/python` and is not inside it.
173
+ - **`outside` has no install remedy on purpose.** `install_cmd` returns early on `is_installed()`,
174
+ so "run devstuff install" advice on an installed-outside-uv row would be false. `system-copy` can
175
+ carry the remedy because the tool reads *not* installed — there, install actually runs.
176
+ - **`unknown` is not `managed`.** A probe that cannot answer (failed `uv tool list`, unparseable
177
+ npm JSON, missing manager) renders "couldn't confirm", and a `managed_by` typo or absent key
178
+ yields no note at all rather than a wrong one.
179
+
163
180
  **Profiles** (`profile.py`, `snapshot.py`, `commands/profile_cmd.py`; spec in `docs/specs/profile/`):
164
181
  `devstuff profile snapshot` / `diff` describe and compare a machine; `apply` (below) changes one. Things that are
165
182
  load-bearing:
@@ -375,7 +392,7 @@ ones tools already have.
375
392
  ## Configurators (`configure/`) — tool-specific wizards, deliberately *not* catalog-driven
376
393
 
377
394
  `src/dev_setup/configure/` holds per-tool setup wizards (`devstuff configure <tool>`), registered
378
- in a `CONFIGURATORS` dict keyed by catalog tool key. There are nine:
395
+ in a `CONFIGURATORS` dict keyed by catalog tool key. There are ten:
379
396
  `configure/starship/{model,render,preview,fonts,wizard}.py`,
380
397
  `configure/commitizen/{model,render,detect,validate,wizard}.py`,
381
398
  `configure/precommit/{model,render,detect,validate,wizard}.py` (the package can't be named
@@ -384,6 +401,7 @@ in a `CONFIGURATORS` dict keyed by catalog tool key. There are nine:
384
401
  `configure/bat/{model,render,detect,preview,wizard}.py`,
385
402
  `configure/ansible/{model,render,detect,validate,wizard}.py`,
386
403
  `configure/lazygit/{model,render,detect,validate,wizard}.py`,
404
+ `configure/btop/{model,render,detect,validate,capability,wizard}.py`,
387
405
  `configure/reptyr/wizard.py` and
388
406
  `configure/syncthing/{model,api,detect,wizard}.py` (the only one that configures a *running
389
407
  service* through its REST API rather than writing a file — `--output` is refused).
@@ -678,8 +696,50 @@ changed.** Everything below was measured against syncthing v2.1.6; full reasonin
678
696
  (1.29), and its remove deliberately leaves the apt source, keyring, config and linger in
679
697
  place.
680
698
 
699
+ **Within the btop configurator, the tool rewrites its own config file — and validates in
700
+ three classes.** Everything below was measured against 1.3.0 (Ubuntu 24.04 apt), 1.4.6
701
+ (Ubuntu 26.04 apt, GPU build) and 1.4.7 (upstream static musl); full reasoning in
702
+ `docs/specs/btop-config/`.
703
+
704
+ **Things learned from the real binary — don't "simplify" these away:**
705
+ - **btop rewrites the whole file, or leaves it alone.** The rewrite (every key, its own
706
+ comments, anything else gone) fires on a wrong-version `#?` first line, a rejected value,
707
+ or an in-app change (`save_config_on_exit = true`; 1.3.0 has no such key and always
708
+ saves). Otherwise the file is byte-identical — comments, unknown keys, partial files
709
+ included. `render.to_text` therefore *splices*: it replaces a value inside its own line
710
+ and appends only absent-and-non-default keys. There is no "generated by" marker — btop's
711
+ next save would erase it, so overwrite is always diff + confirm.
712
+ - **The three validation classes decide which check sees what.** Rejected-and-logged
713
+ (`update_ms = "abc"`, `vim_keys = yes`, a bad `graph_symbol`); rejected-silently
714
+ (`shown_boxes` with an unknown token); kept-silently (`proc_sorting = "bogus"`, an
715
+ unknown `color_theme`). The pty `launch` check — which diffs what btop saved back — can
716
+ only see the first two; `verify` carries the enum/theme/boxes checks, and the launch's
717
+ own detail says so. btop.log WARNINGs are never the signal: the GPU build logs a PMU
718
+ warning on every start.
719
+ - **`found.keys` comes from the binary, and `None` is a real answer.** The key set varies
720
+ by version *and* build flags (1.4.7's `disable_mouse`, the apt GPU build's `shown_gpus`,
721
+ 1.3.0 missing `save_config_on_exit`). `--default-config` provides it on 1.4+; on 1.3.0 a
722
+ first-run probe reads the file a pty'd btop writes. `None` means "could not ask" — the
723
+ wizard offers every setting then; it never means "no keys".
724
+ - **The `#?` header is taken verbatim from the binary** — `#? Config file for btop v.1.4.6`
725
+ vs `v. 1.3.0` (a space). Constructing it would guess at exactly the string the rewrite
726
+ check keys on.
727
+ - **A `"` can never appear inside a string value** — `clock_format = "a"b"` saves back as
728
+ `"a"` (a quoted value ends at the second quote). `verify` refuses what cannot be written.
729
+ - **The live check isolates HOME, never `-c`** — 1.3.0 has no `-c` flag; a minimal env
730
+ (HOME, TERM, LANG, PATH) keeps a stray `XDG_CONFIG_HOME` from redirecting the sandbox at
731
+ the user's real config.
732
+ - **No preset may set `save_config_on_exit`** — it changes how btop treats the file itself
733
+ (a running btop with in-app changes overwrites external edits; measured). It is only ever
734
+ the user's explicit answer.
735
+ - **The `cap_perfmon` offer verifies with `getcap`, nothing more** — upstream's `make
736
+ setcap` is required for CPU package watts and Intel GPU stats, apt drops it on upgrade,
737
+ and whether watts appear is unknowable where power counters are hidden. It is refused
738
+ when the binary is not root-owned or is group/other-writable — a capability others can
739
+ replace is a privilege hole, not a fix.
740
+
681
741
  Not yet built: configurators for anything other than starship, commitizen, pre-commit, docker,
682
- bat, ansible, lazygit, reptyr and syncthing; `repo: local` pre-commit hook authoring and hooks outside the curated
742
+ bat, ansible, lazygit, btop, reptyr and syncthing; `repo: local` pre-commit hook authoring and hooks outside the curated
683
743
  catalog; lazygit keybindings and `customCommands` authoring (both preserved, never edited);
684
744
  ansible fact-caching backends; the syncthing `sendonly`/`receiveencrypted` folder modes,
685
745
  sharing more than one folder per run, and automating the server-side approval (still a manual
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.24.0
3
+ Version: 2.26.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>
@@ -238,6 +238,7 @@ devstuff list --available # only packages not yet installed
238
238
  ```
239
239
 
240
240
  Output columns: status (✔/✘), package key, description, install type, version (if installed), help command.
241
+ Tools another catalog tool manages or could manage get a second line — `✓ managed by uv`, `installed outside nvm`, `uv can manage this`, or a warning that a system copy (e.g. `/usr/bin/python3`) exists outside the manager — probed against the machine, not inferred from the catalog.
241
242
 
242
243
  ---
243
244
 
@@ -576,6 +577,7 @@ devstuff configure starship --output /tmp/try.toml # write elsewhere, leave th
576
577
  | `reptyr` | Temporary or persistent Linux ptrace permissions; command-line usage guidance |
577
578
  | `ansible` | `ansible.cfg` — inventory paths, forks, pipelining, become and vault |
578
579
  | `bat` | Theme, decorations, paging, and the man-page/`cat` shell integration |
580
+ | `btop` | Theme, boxes, graph glyphs, update rate and the process list in `btop.conf` |
579
581
  | `commitizen` | Commit types, what each one bumps, git tags, and changelog sections |
580
582
  | `docker` | `daemon.json` — log rotation, address pools and daemon behaviour |
581
583
  | `lazygit` | Icons, diff pager, panels and git behaviour |
@@ -591,6 +593,7 @@ varies a lot, and the wizards say so rather than implying more than they know:
591
593
  |------|-----------------------------|--------------------------------------|
592
594
  | `ansible` | unknown keys, unknown sections, wrong types | **whether ansible actually *read* each setting** (`ansible-config dump`) — a key in a retired section validates and does nothing |
593
595
  | `bat` | a bad `--style` component (hard error) | **theme names** — a bad theme is a stderr warning and exit 0, so a typo silently gives you the default forever |
596
+ | `btop` | wrong types, out-of-range `update_ms`, bad graph symbols — logged, reset to the default, and the file rewritten | **the values it *keeps* silently** — a bad enum or unknown theme is stored verbatim and falls back without a word, so a live launch can only see half the problem |
594
597
  | `docker` | key typos, malformed CIDRs, numeric log options | **five configs `dockerd --validate` accepts that stop every container from starting** |
595
598
  | `lazygit` | wrong types (refuses to start) | **unknown keys and invalid enum values** — both silently ignored |
596
599
  | `pre-commit` | the file's shape | **hook ids** — `validate-config` never opens a repository |
@@ -1054,6 +1057,39 @@ Icons are gated on the Nerd Font check the starship wizard already uses — incl
1054
1057
  "can't tell" answer, which means stay silent rather than nag. Your `customCommands` and
1055
1058
  `keybinding` trees are preserved untouched; the wizard models neither.
1056
1059
 
1060
+ #### btop wizard
1061
+
1062
+ btop's config validation comes in three classes, two of them silent: a wrong type or range
1063
+ is *reset* on load (and btop rewrites the whole file when it happens), an unknown
1064
+ `shown_boxes` token is reset *without* a log line, and a bad enum value or unknown theme is
1065
+ *kept verbatim* and silently fallen back from. The wizard checks all three: `verify` runs
1066
+ offline before every save, and the "check" menu item — also run once at save time — starts
1067
+ the real btop in a hidden terminal and diffs what it saved back. It says what that proves,
1068
+ too: a passing launch cannot vouch for an enum value or the theme, which btop keeps
1069
+ silently.
1070
+
1071
+ It also works around the file itself: btop rewrites `btop.conf` — every key and its own
1072
+ comments — whenever the header isn't this version's, a value was rejected, or you changed
1073
+ a setting in-app; otherwise it leaves the file byte-identical. So the wizard *splices*
1074
+ into the existing file (values replaced in place, keys appended only when non-default),
1075
+ carries no "generated by" marker that btop's next save would erase, and always shows the
1076
+ diff before overwriting. The key set is read from the binary — 1.3.0 has no
1077
+ `save_config_on_exit`, 1.4.7 adds `disable_mouse`, and only a GPU build knows `gpu0`…`gpu5`
1078
+ boxes.
1079
+
1080
+ | Preset | What it sets |
1081
+ |--------|--------------|
1082
+ | **btop's defaults** | Stock — nothing changed |
1083
+ | **Lower overhead** | 3 s sampling, no per-process CPU graphs, no redraws behind menus |
1084
+ | **Basic glyphs** | Block graphs and square corners (pick the `tty` graph for a real Linux console) |
1085
+ | **Processes front and centre** | Just the cpu and proc boxes, process list as a tree |
1086
+ | **Whatever is configured now** | Start from the existing `btop.conf` |
1087
+
1088
+ After a save the wizard can offer `sudo setcap cap_perfmon=+ep` on the binary — upstream's
1089
+ documented requirement for CPU package watts and Intel GPU stats, preferred over setuid.
1090
+ It says what it verifies (the capability, via `getcap`) and what it cannot (whether watts
1091
+ appear), that it applies to every user of the binary, and that an apt upgrade drops it.
1092
+
1057
1093
  ---
1058
1094
 
1059
1095
  ### `add`
@@ -1646,6 +1682,7 @@ links:
1646
1682
 
1647
1683
  | `arcane-cli` | Arcane CLI | Command-line client for an Arcane Docker management server (needs a running server) | `arcane-cli --help` |
1648
1684
  | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
1685
+ | `btop` | btop | Resource monitor — CPU, memory, disks, network, processes and GPUs (`devstuff configure btop`) | `btop --help` |
1649
1686
  | `bubblewrap` | bubblewrap + socat | Unprivileged sandbox (bwrap) and network relay (socat) — what Claude Code's /sandbox needs on Linux | `bwrap --help` |
1650
1687
  | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
1651
1688
  | `delta` | delta | Syntax-highlighting pager for git diffs — the `devstuff configure lazygit` wizard can install it for you | `delta --help` |
@@ -1729,6 +1766,7 @@ tools:
1729
1766
  | `help_cmd` | no | Command shown in `list` under the package entry |
1730
1767
  | `docs_url` | no | URL opened by `devstuff docs <key>` |
1731
1768
  | `requires` | no | List of package keys that must already be installed |
1769
+ | `managed_by` | no | Catalog key of the tool that manages this one's installs (e.g. `uv`, `nvm`). Implied for `npm` → `nvm` and `pip`/`uvx` → `uv`; set it only when the type doesn't imply one |
1732
1770
  | `npm_name` | npm | npm package name |
1733
1771
  | `pip_name` | pip | PyPI package name. Extras work as-is: `pip_name: "ansible-lint[lock]"` |
1734
1772
  | `uv_with` | no (pip/uvx) | Extra packages installed into the tool's environment (`uv tool install --with`) |
@@ -211,6 +211,7 @@ devstuff list --available # only packages not yet installed
211
211
  ```
212
212
 
213
213
  Output columns: status (✔/✘), package key, description, install type, version (if installed), help command.
214
+ Tools another catalog tool manages or could manage get a second line — `✓ managed by uv`, `installed outside nvm`, `uv can manage this`, or a warning that a system copy (e.g. `/usr/bin/python3`) exists outside the manager — probed against the machine, not inferred from the catalog.
214
215
 
215
216
  ---
216
217
 
@@ -549,6 +550,7 @@ devstuff configure starship --output /tmp/try.toml # write elsewhere, leave th
549
550
  | `reptyr` | Temporary or persistent Linux ptrace permissions; command-line usage guidance |
550
551
  | `ansible` | `ansible.cfg` — inventory paths, forks, pipelining, become and vault |
551
552
  | `bat` | Theme, decorations, paging, and the man-page/`cat` shell integration |
553
+ | `btop` | Theme, boxes, graph glyphs, update rate and the process list in `btop.conf` |
552
554
  | `commitizen` | Commit types, what each one bumps, git tags, and changelog sections |
553
555
  | `docker` | `daemon.json` — log rotation, address pools and daemon behaviour |
554
556
  | `lazygit` | Icons, diff pager, panels and git behaviour |
@@ -564,6 +566,7 @@ varies a lot, and the wizards say so rather than implying more than they know:
564
566
  |------|-----------------------------|--------------------------------------|
565
567
  | `ansible` | unknown keys, unknown sections, wrong types | **whether ansible actually *read* each setting** (`ansible-config dump`) — a key in a retired section validates and does nothing |
566
568
  | `bat` | a bad `--style` component (hard error) | **theme names** — a bad theme is a stderr warning and exit 0, so a typo silently gives you the default forever |
569
+ | `btop` | wrong types, out-of-range `update_ms`, bad graph symbols — logged, reset to the default, and the file rewritten | **the values it *keeps* silently** — a bad enum or unknown theme is stored verbatim and falls back without a word, so a live launch can only see half the problem |
567
570
  | `docker` | key typos, malformed CIDRs, numeric log options | **five configs `dockerd --validate` accepts that stop every container from starting** |
568
571
  | `lazygit` | wrong types (refuses to start) | **unknown keys and invalid enum values** — both silently ignored |
569
572
  | `pre-commit` | the file's shape | **hook ids** — `validate-config` never opens a repository |
@@ -1027,6 +1030,39 @@ Icons are gated on the Nerd Font check the starship wizard already uses — incl
1027
1030
  "can't tell" answer, which means stay silent rather than nag. Your `customCommands` and
1028
1031
  `keybinding` trees are preserved untouched; the wizard models neither.
1029
1032
 
1033
+ #### btop wizard
1034
+
1035
+ btop's config validation comes in three classes, two of them silent: a wrong type or range
1036
+ is *reset* on load (and btop rewrites the whole file when it happens), an unknown
1037
+ `shown_boxes` token is reset *without* a log line, and a bad enum value or unknown theme is
1038
+ *kept verbatim* and silently fallen back from. The wizard checks all three: `verify` runs
1039
+ offline before every save, and the "check" menu item — also run once at save time — starts
1040
+ the real btop in a hidden terminal and diffs what it saved back. It says what that proves,
1041
+ too: a passing launch cannot vouch for an enum value or the theme, which btop keeps
1042
+ silently.
1043
+
1044
+ It also works around the file itself: btop rewrites `btop.conf` — every key and its own
1045
+ comments — whenever the header isn't this version's, a value was rejected, or you changed
1046
+ a setting in-app; otherwise it leaves the file byte-identical. So the wizard *splices*
1047
+ into the existing file (values replaced in place, keys appended only when non-default),
1048
+ carries no "generated by" marker that btop's next save would erase, and always shows the
1049
+ diff before overwriting. The key set is read from the binary — 1.3.0 has no
1050
+ `save_config_on_exit`, 1.4.7 adds `disable_mouse`, and only a GPU build knows `gpu0`…`gpu5`
1051
+ boxes.
1052
+
1053
+ | Preset | What it sets |
1054
+ |--------|--------------|
1055
+ | **btop's defaults** | Stock — nothing changed |
1056
+ | **Lower overhead** | 3 s sampling, no per-process CPU graphs, no redraws behind menus |
1057
+ | **Basic glyphs** | Block graphs and square corners (pick the `tty` graph for a real Linux console) |
1058
+ | **Processes front and centre** | Just the cpu and proc boxes, process list as a tree |
1059
+ | **Whatever is configured now** | Start from the existing `btop.conf` |
1060
+
1061
+ After a save the wizard can offer `sudo setcap cap_perfmon=+ep` on the binary — upstream's
1062
+ documented requirement for CPU package watts and Intel GPU stats, preferred over setuid.
1063
+ It says what it verifies (the capability, via `getcap`) and what it cannot (whether watts
1064
+ appear), that it applies to every user of the binary, and that an apt upgrade drops it.
1065
+
1030
1066
  ---
1031
1067
 
1032
1068
  ### `add`
@@ -1619,6 +1655,7 @@ links:
1619
1655
 
1620
1656
  | `arcane-cli` | Arcane CLI | Command-line client for an Arcane Docker management server (needs a running server) | `arcane-cli --help` |
1621
1657
  | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
1658
+ | `btop` | btop | Resource monitor — CPU, memory, disks, network, processes and GPUs (`devstuff configure btop`) | `btop --help` |
1622
1659
  | `bubblewrap` | bubblewrap + socat | Unprivileged sandbox (bwrap) and network relay (socat) — what Claude Code's /sandbox needs on Linux | `bwrap --help` |
1623
1660
  | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
1624
1661
  | `delta` | delta | Syntax-highlighting pager for git diffs — the `devstuff configure lazygit` wizard can install it for you | `delta --help` |
@@ -1702,6 +1739,7 @@ tools:
1702
1739
  | `help_cmd` | no | Command shown in `list` under the package entry |
1703
1740
  | `docs_url` | no | URL opened by `devstuff docs <key>` |
1704
1741
  | `requires` | no | List of package keys that must already be installed |
1742
+ | `managed_by` | no | Catalog key of the tool that manages this one's installs (e.g. `uv`, `nvm`). Implied for `npm` → `nvm` and `pip`/`uvx` → `uv`; set it only when the type doesn't imply one |
1705
1743
  | `npm_name` | npm | npm package name |
1706
1744
  | `pip_name` | pip | PyPI package name. Extras work as-is: `pip_name: "ansible-lint[lock]"` |
1707
1745
  | `uv_with` | no (pip/uvx) | Extra packages installed into the tool's environment (`uv tool install --with`) |
@@ -46,8 +46,10 @@ They are most useful when they capture:
46
46
  | [`bat-config/`](bat-config/) — `devstuff configure bat`, the theme and decoration wizard | Complete (v1) |
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
+ | [`btop-config/`](btop-config/) — the `btop` tool plus `devstuff configure btop`, the btop.conf wizard and the `cap_perfmon` offer | Complete (v1; first real install is the CI canary, and grant/revoke are unit-tested only — no sudo on the dev host) |
49
50
  | [`syncthing-config/`](syncthing-config/) — the `syncthing` tool plus `devstuff configure syncthing`, device pairing over the local API | Complete (v1; first real install and live wizard run pending) |
50
51
  | [`fmhy-picks/`](fmhy-picks/) — five tools (delta, ripgrep, ShellCheck, fzf, OpenCode) and five links chosen from the FMHY wiki, plus the lazygit wizard's delta install offer | Implemented 2026-10-13 (first real installs pending: the CI canary is their first run) |
52
+ | [`managed-by/`](managed-by/) — manager notes in `list` and the `install` picker (`managed_by` field + uv/nvm probes + system-copy flags) | Implemented 2026-10-13 |
51
53
  | [`verbose-mode/`](verbose-mode/) — `-v`/`-vv`, the process-wide verbosity level | Complete (v1) |
52
54
  | [`outdated/`](outdated/) — `devstuff outdated`, the read-only installed-vs-latest report | Complete (v1) |
53
55
  | [`profile/`](profile/) — `devstuff profile snapshot` / `diff`, a portable description of a machine's tools | Complete (v1: snapshot, diff; apply is its own spec) |
@@ -0,0 +1,86 @@
1
+ # btop tool + configurator — development plan
2
+
3
+ One branch (`feat/btop-tool-and-wizard`) and one PR.
4
+
5
+ ## Milestones
6
+
7
+ - **M-1 Measurements.** Extracted btop 1.3.0 (Ubuntu 24.04 apt), 1.4.6
8
+ (Ubuntu 26.04 apt, GPU build) and 1.4.7 (upstream static musl); recorded the
9
+ rewrite rules, the three validation classes, the per-version/build key sets
10
+ and the capability facts. *Done 2026-10-19* (see `FINDINGS.md` in the task
11
+ record; the load-bearing results are in `model.py`'s docstring and §5 of the
12
+ specification).
13
+ - **M-2 Catalog.** `tools.yaml` entry, `test-installs.yml` matrix row, README
14
+ table row (FR-1). *Done 2026-10-19.*
15
+ - **M-3 Model + splice.** `model.py` (settings, presets, the
16
+ `save_config_on_exit` rule) and `render.py` (parse/splice/`matches`)
17
+ (FR-2…FR-9). *Done 2026-10-19.*
18
+ - **M-4 Detection + validation.** `detect.py` (key set, themes, running procs,
19
+ `from_existing`), `validate.py` (`verify`, `launch`, `rejections`, the pty
20
+ runner) (FR-10…FR-18). *Done 2026-10-19.*
21
+ - **M-5 Wizard + capability.** `wizard.py` (report, preset, review loop, save
22
+ path) and `capability.py` (the `cap_perfmon` offer) (FR-19…FR-22).
23
+ *Done 2026-10-19.*
24
+ - **M-6 Tests + docs.** `tests/test_configure_btop.py`, this spec directory,
25
+ README and CLAUDE.md. *Done 2026-10-19.*
26
+
27
+ ## Testing
28
+
29
+ - Unit: `uv run pytest tests/test_configure_btop.py` — needs no btop and no
30
+ network; live tests skip without `btop` on PATH.
31
+ - Live: the same file run against each extracted binary via a PATH override
32
+ (`/tmp/btop-measure/{r130,root,up/…}/usr|…/bin`). Live tests cover the
33
+ defaults drift, a clean launch per preset, the can-fail case, the
34
+ kept-silently asymmetry, and the byte-identical stability claim.
35
+ - Catalog: `test_ci_matrix_covers_every_builtin_tool` pins the matrix row.
36
+
37
+ ## What was run and what was not
38
+
39
+ Run on the dev host, 2026-10-19 (btop is *not* installed here; three extracted
40
+ binaries stood in via PATH overrides):
41
+
42
+ - `uv run pytest tests/test_configure_btop.py -q` with no btop on PATH —
43
+ 60 passed, 9 skipped (the live tests).
44
+ - The same file under `PATH=/tmp/btop-measure/root/usr/bin:$PATH` (1.4.6 apt,
45
+ GPU build), `PATH=/tmp/btop-measure/r130/usr/bin:$PATH` (1.3.0) and
46
+ `PATH=/tmp/btop-measure/up/btop/bin:$PATH` (1.4.7 static) — **69 passed on
47
+ each**, including:
48
+ - the strict defaults-drift test — no drift on any of the three;
49
+ - every preset surviving a real launch with zero rejections;
50
+ - `update_ms = "abc"` and `vim_keys = yes` both reported as rejections (the
51
+ check can fail);
52
+ - `proc_sorting = "bogus"` kept with no rejection (the asymmetry, on 1.4.6
53
+ and 1.4.7; on 1.3.0 the same holds — it also keeps it);
54
+ - a generated file left byte-identical by a real run on all three.
55
+ - The wizard driven end-to-end under a pty against the 1.4.6 binary with a
56
+ throwaway HOME: fresh-config save with a preset and one change (live check
57
+ ran), then a second run over the existing file showing the diff and the
58
+ overwrite confirm with a timestamped backup. The capability step printed its
59
+ refusal (the extracted binary is not root-owned) and the grant command —
60
+ the actual confirm could not be reached without a root-owned binary.
61
+ Transcript: `/tmp/btop-measure/wizard-run.txt`.
62
+ - `uv run pytest tests/test_catalog.py tests/test_registry.py
63
+ tests/integration/test_tools.py -q` and a full `uv run pytest -q`; `uv run
64
+ ruff check` on the changed files.
65
+
66
+ Not run:
67
+
68
+ - **No real `devstuff install btop`** — btop is not installed on the dev host
69
+ and there is no Docker; the weekly `test-installs.yml` canary is the
70
+ install's first run (the CI image's apt has 1.3.0 — the same binary the
71
+ live tests here ran).
72
+ - **No sudo**: `grant`/`revoke` were exercised with faked `_run`/`getcap` only;
73
+ the first real grant (and the "apt upgrade drops the capability" re-run) is
74
+ untested against real sudo.
75
+ - The wizard's questionary flow was driven through one pty session; the
76
+ per-key menu branches were exercised by unit tests with stubbed prompts.
77
+
78
+ ## Risks
79
+
80
+ - Ubuntu's apt version lags upstream; a new archive version changes the key
81
+ set — absorbed by run-time detection (SD-7) and by the live drift test if CI
82
+ ever gains a btop.
83
+ - The live check's ~5 s cost at save time could read as a hang — the UI states
84
+ it; a hung btop run is bounded by the quit timeout plus SIGKILL.
85
+ - An apt upgrade drops `cap_perfmon` — stated in the offer text; nothing
86
+ reinstates it automatically.
@@ -0,0 +1,213 @@
1
+ # Specification: `devstuff configure btop` and the `btop` catalog tool
2
+
3
+ **Date:** 2026-10-19
4
+ **Status:** Implemented (v1)
5
+ **Authors:** Sawyer + Devin
6
+
7
+ ---
8
+
9
+ ## 1. Problem Statement & Goals
10
+
11
+ btop's validation is asymmetric in *three* classes, and two of them are silent.
12
+ Measured against 1.3.0 (Ubuntu 24.04 apt), 1.4.6 (Ubuntu 26.04 apt, GPU build) and
13
+ 1.4.7 (upstream static musl):
14
+
15
+ | what you write | btop's reaction |
16
+ |-----------------------------------------|--------------------------------------------------|
17
+ | `update_ms = "abc"`, `vim_keys = yes`, `graph_symbol = "bad"` | rejected, reset to default, WARNING in btop.log |
18
+ | `shown_boxes = "cpu foo"` | rejected, reset, **nothing logged** |
19
+ | `proc_sorting = "bogus"`, `temp_scale = "bogus"`, an unknown `color_theme` | **kept verbatim**, silently falls back, nothing logged |
20
+
21
+ So a hand-edited `btop.conf` can carry values that are dead (reset on every load)
22
+ and values that are alive-but-wrong (kept and silently ignored), and btop will
23
+ not distinguish either. The live check — run btop and diff what it saved back —
24
+ only sees the first two classes; the third needs an offline check, which is why
25
+ the wizard has both halves and why neither is redundant.
26
+
27
+ The second problem is what btop does to the file itself: it rewrites the *whole*
28
+ config — every key and its own comments — whenever the first line is not this
29
+ version's `#?` header, when a value was rejected on load, or when a setting was
30
+ changed in-app (`save_config_on_exit = true`; 1.3.0 always saves). Otherwise it
31
+ leaves the file byte-identical, comments and unknown keys included. A wizard that
32
+ rewrote the file on every save would destroy comments it didn't write; a
33
+ "generated by devstuff" marker would be a lie the first time btop saves.
34
+
35
+ Third: the key set varies by version *and* build flags — `disable_mouse` arrives
36
+ in 1.4.7, `shown_gpus` exists only on GPU builds, `save_config_on_exit` doesn't
37
+ exist before 1.4. A fixed table is wrong on every other binary.
38
+
39
+ **Goals**
40
+
41
+ - Splice into the existing file — replace values in place, append only needed
42
+ keys, never delete or reorder anything.
43
+ - Check offline before every save; check live against the real binary (it is the
44
+ only authority on what it keeps), and say what each check cannot prove.
45
+ - Ask only about keys this build knows, and never write one it does not.
46
+ - Offer the `cap_perfmon` capability grant — documented upstream as required for
47
+ CPU package watts and Intel GPU stats — with the privilege-hole refusals and
48
+ the apt-upgrade caveat stated.
49
+ - Nothing written until confirmed; an existing file is always diffed first.
50
+
51
+ **Non-goals**
52
+
53
+ - The `presets` string and per-box layout editing (`cpu:1:default,…` — a
54
+ different, much more positional format; btop's own UI is where that lives).
55
+ - Per-box graph symbols (`graph_symbol_cpu` etc.) — one global `graph_symbol`.
56
+ - GPU/disk/network filters (`disks_filter`, `net_iface`, `shown_gpus`
57
+ membership), `cpu_graph_*` selections — machine-specific pickers.
58
+ - Custom theme authoring.
59
+ - `setuid` — `cap_perfmon` is upstream's preferred mechanism.
60
+ - `profile` support — pins/install only; out of scope here.
61
+
62
+ ---
63
+
64
+ ## 2. Functional Requirements
65
+
66
+ ### Catalog
67
+
68
+ - **FR-1** `btop` is a built-in `apt` tool (`apt_packages: btop`) with
69
+ `check_cmd: btop`, in the `test-installs.yml` matrix and the README table.
70
+
71
+ ### Model
72
+
73
+ - **FR-2** Settings are data in `configure/btop/model.py`: `SETTINGS` is ordered
74
+ (declaration order is prompt order), each `Setting` carries `kind`
75
+ (`bool|int|str|enum|theme|boxes`), `default`, `label`, `description`, optional
76
+ `choices`/`minimum`/`maximum`, and `group`. Enum `choices` are the values
77
+ btop's own `--default-config` comments list.
78
+ - **FR-3** `BtopConfig` carries one field per setting and `field default ==
79
+ Setting.default` — a test pins the pairing.
80
+ - **FR-4** Five presets: `defaults`, `low-overhead`, `basic-glyphs`,
81
+ `processes`, `current` (offered only when a config exists). **No preset sets
82
+ `save_config_on_exit`** — it changes how btop treats the file; only the user's
83
+ explicit answer may (a test).
84
+
85
+ ### The file
86
+
87
+ - **FR-5** `render.to_text` splices: base = existing file text if the target
88
+ exists, else a minimal new file whose first line is *this binary's* `#?`
89
+ header verbatim (never constructed — `v.1.4.6` vs `v. 1.3.0` differ) plus a
90
+ comment explaining the rewrite-on-save behaviour.
91
+ - **FR-6** For every modelled key the binary knows: an existing line's value is
92
+ replaced in place iff the parsed value differs (keeping spacing, comments and
93
+ every other byte); an absent key is appended only when it differs from the
94
+ effective default (`found.defaults` parsed, falling back to `Setting.default`).
95
+ Lines are never deleted; a key the binary does not know is never written.
96
+ - **FR-7** `render.parse` keeps every original line and reads values the way
97
+ btop does: `"s"` ends at the second quote, `true`/`false` are case-insensitive,
98
+ a trailing ` # comment` is stripped, a bare word is a string.
99
+ - **FR-8** `render.matches` parses the result back and compares — the splice
100
+ verifies itself like commitizen's pyproject splice.
101
+ - **FR-9** `--output <path>` writes elsewhere; the try-it hint names `btop -c`
102
+ only when the detected version supports it (1.4+; 1.3.0 has no `-c`).
103
+
104
+ ### Detection
105
+
106
+ - **FR-10** The config dir is `$XDG_CONFIG_HOME/btop` when set and non-empty,
107
+ else `~/.config/btop`; the file is `btop.conf`.
108
+ - **FR-11** The key set, header and raw defaults come from
109
+ `btop --default-config` when it works, else a first-run probe: btop under a
110
+ pty in a throwaway HOME writes the same file. `keys` is `None` when neither
111
+ could be read — the difference between "not installed" and "no keys".
112
+ - **FR-12** Themes = `Default`, `TTY`, plus `*.theme` stems in
113
+ `<binary>/../share/btop/themes`, `/usr/local/share/btop/themes`,
114
+ `/usr/share/btop/themes` and `<config_dir>/themes`, deduplicated. A full path
115
+ is never a theme value.
116
+ - **FR-13** `detect.running` lists pids of `btop` processes owned by this user —
117
+ a running btop reads the config only at start and can overwrite the file on
118
+ exit.
119
+ - **FR-14** An existing config is read back into wizard state (`preset
120
+ "current"`). A value btop itself would reject — wrong type for kind, an int
121
+ out of range or negative, a bad `graph_symbol`, an unknown `shown_boxes`
122
+ token — becomes the effective default and is recorded in `invalid_existing`
123
+ for the report. A silently-kept value (`proc_sorting = "Memory"`, an unknown
124
+ theme, an empty `shown_boxes`) is carried as-is so `verify` can flag it.
125
+
126
+ ### Verification
127
+
128
+ - **FR-15** `validate.verify` runs offline before every save: splice round-trip;
129
+ types and ranges; enum values in their choices; the theme exists in
130
+ `found.themes` (a list that could not be read passes with an "unverified"
131
+ detail, never a false accusation); `shown_boxes` tokens valid (gpuN only when
132
+ `shown_gpus` is in the key set) and non-empty; no `"` or newline inside a
133
+ string value; every wanted non-default key known to this binary (the check
134
+ passes with an explanatory detail when the key set is unknown).
135
+ - **FR-16** `validate.launch` writes the candidate to `<tmp>/.config/btop/
136
+ btop.conf`, starts the real binary under a pty with a minimal environment
137
+ (HOME, TERM, LANG, PATH only — no `-c` flag exists before 1.4, no inherited
138
+ XDG), answers `ESC[6n`, quits with `q`, reaps, and diffs what the file says
139
+ now. A `Rejection` is a modelled key saved back with a different value, or a
140
+ candidate key that vanished from a *rewritten* file. btop.log lines mentioning
141
+ the key attach as detail; a WARNING alone is never a rejection.
142
+ - **FR-17** A btop that did not start is a failed check with an escaped tail of
143
+ its output. A passing launch is stated as not proving enum values or the
144
+ theme — btop keeps those silently.
145
+ - **FR-18** `launch` is an explicit menu action and runs once at save time when
146
+ btop is installed. A failed check at save asks "Save anyway?" (default No); it
147
+ never silently blocks.
148
+
149
+ ### The capability
150
+
151
+ - **FR-19** After a successful save — only when the real config was written and
152
+ btop is installed — the wizard offers `sudo setcap cap_perfmon=+ep <binary>`,
153
+ default No, explaining: required for CPU package watts and Intel GPU stats
154
+ (upstream `make setcap`, preferred over setuid); applies to every user of the
155
+ binary; an apt upgrade replaces the binary and drops it. If already set, it
156
+ offers removal (default No). It is verified by `getcap`, not by whether watts
157
+ appear — unknowable where power counters are hidden.
158
+ - **FR-20** The grant is refused — with the reason and the command printed —
159
+ when `setcap` is missing, the binary is not root-owned, or it is
160
+ group/other-writable (a capability others can replace is a privilege hole).
161
+ Never offered under `--output`.
162
+
163
+ ### Saving
164
+
165
+ - **FR-21** An existing target is always diffed and confirmed (default No) —
166
+ there is no reliable generated-by marker because btop rewrites the file. A
167
+ timestamped `<name>.bak.<YYYYmmdd-HHMMSS>` is kept.
168
+ - **FR-22** After saving, running btop processes are called out (restart to
169
+ pick it up; one started with save-on-exit can overwrite the file).
170
+
171
+ ---
172
+
173
+ ## 3. Non-Functional Requirements
174
+
175
+ - **NFR-1** Zero new runtime dependencies (stdlib pty/fcntl for the live check).
176
+ - **NFR-2** Unit tests require neither btop nor the network; live tests skip
177
+ without `btop` on PATH.
178
+ - **NFR-3** No import of the wizard at CLI start-up.
179
+ - **NFR-4** `verify()` is instant; `launch()` costs ~5 s and the UI says so.
180
+ - **NFR-5** Every failure path returns `None`, an empty value or a failed
181
+ `Check` — nothing raises into the wizard.
182
+ - **NFR-6** Outside text — log lines, file values, paths, exception text — is
183
+ escaped with `rich.markup.escape` before it reaches `ui.*`.
184
+
185
+ ---
186
+
187
+ ## 4. Open Questions
188
+
189
+ | # | Question | Status |
190
+ |---|----------|--------|
191
+ | 1 | Install via apt or the upstream static binary? | **Resolved 2026-10-19 — apt.** User decision; the static musl build has no GPU support, and the apt package tracks the distro. |
192
+ | 2 | Should the wizard edit `presets`/per-box layouts? | **Resolved 2026-10-19 — no.** Non-goal; btop's own menu edits them. |
193
+ | 3 | Can `getcap` prove watts appear? | **Resolved 2026-10-19 — no.** It proves the capability only; the UI says exactly that. |
194
+
195
+ ---
196
+
197
+ ## 5. Findings That Changed the Design
198
+
199
+ - **The three validation classes** (§1). The live check is real and useful —
200
+ and blind to the kept-silently class, so `verify` carries the enum/theme/boxes
201
+ checks. Both halves are tested as able to fail.
202
+ - **btop rewrites or leaves alone, never merges** (§1). Hence the splice, the
203
+ "always diff before overwrite" rule and the absence of a generated marker.
204
+ - **`--default-config` does not exist before 1.4**, and neither does `-c` — so
205
+ detection falls back to a first-run pty probe and the live check isolates
206
+ HOME instead of passing a config path.
207
+ - **The key set depends on build flags too** — the apt 1.4.6 GPU build has
208
+ `shown_gpus`/`graph_symbol_gpu`/`custom_gpu_name0..5` that upstream's static
209
+ 1.4.7 lacks, and 1.4.7 has `disable_mouse`/`proc_follow_detailed` that 1.4.6
210
+ lacks. Only the binary's own dump is authoritative.
211
+ - **`save_config_on_exit` can never be preset-decided** — with it on, a running
212
+ btop you touch rewrites this file on exit (measured); with it off, the file is
213
+ authoritative and in-app changes are session-only. The wizard explains both.