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