devstuff 2.11.0__tar.gz → 2.12.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {devstuff-2.11.0 → devstuff-2.12.0}/CHANGELOG.md +10 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/CLAUDE.md +33 -1
- {devstuff-2.11.0 → devstuff-2.12.0}/PKG-INFO +105 -1
- {devstuff-2.11.0 → devstuff-2.12.0}/README.md +104 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/ROADMAP.md +31 -19
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/README.md +1 -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.11.0 → devstuff-2.12.0}/pyproject.toml +1 -1
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/cli.py +2 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/help_cmd.py +1 -0
- devstuff-2.12.0/src/dev_setup/commands/profile_cmd.py +199 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/generic.py +78 -6
- 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/tests/test_installed_version.py +213 -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.11.0 → devstuff-2.12.0}/uv.lock +1 -1
- {devstuff-2.11.0 → devstuff-2.12.0}/.claude/skills/run-stuff/SKILL.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.claude/skills/run-stuff/smoke.sh +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.github/codex/review.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/agent.yml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/bump.yml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/ci.yml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/publish.yml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.github/workflows/test-installs.yml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/.gitignore +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/dev/Dockerfile +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/dev/Dockerfile.ci +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/dev/Makefile +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/dev/docker-compose.yml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/devstuff +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/github-agent.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/agent/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/agent/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/agent/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/ansible-config/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/ansible-config/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/bat-config/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/bat-config/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/bat-config/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/commitizen-config/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/commitizen-config/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/docker-config/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/docker-config/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/docker-config/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/lazygit-config/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/lazygit-config/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/outdated/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/outdated/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/outdated/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/precommit-config/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/precommit-config/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/starship-config/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/starship-config/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/starship-config/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/uv-backbone/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/uv-backbone/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/verbose-mode/development-plan.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/verbose-mode/specifications.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/install.sh +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/__main__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/approval.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/bridges.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/catalog.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/completion.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/config.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/loop.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/ollama.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/preflight.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/primitives.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/registry.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/sandbox.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/session.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/transcript.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent_tools.schema.json +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/agent_tools.yaml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/base.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/catalog.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/add_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/agent_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/configure_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/delete_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/docs_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/functions_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/install_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/links_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/list_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/outdated_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/remove_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/run_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/skills_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/commands/update_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/detect.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/model.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/render.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/validate.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/detect.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/model.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/preview.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/render.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/bat/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/model.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/render.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/detect.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/model.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/render.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/validate.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/docker/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/model.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/render.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/detect.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/model.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/render.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/validate.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/fonts.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/icons.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/model.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/preview.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/render.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/configure/starship/wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/doctor.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/function_runner.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions.schema.json +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions.yaml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions_catalog.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/functions_registry.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links.schema.json +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links.yaml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links_catalog.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/links_registry.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/registry.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/tools.yaml +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/ui.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/updates.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/src/dev_setup/verbose.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/__init__.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/conftest.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_agent_smoke.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_agent_tui.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_commitizen_config.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/integration/test_tools.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_completion.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_loop.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_sandbox.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_tools.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_agent_wizard.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_catalog.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_ansible.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_bat.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_commitizen.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_docker.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_lazygit.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_precommit.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_reptyr.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_configure_starship.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_doctor.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_functions.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_generic.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_links.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_outdated_cmd.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_registry.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_update_notes.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_updates.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_uv_probes.py +0 -0
- {devstuff-2.11.0 → devstuff-2.12.0}/tests/test_verbose.py +0 -0
|
@@ -1,3 +1,13 @@
|
|
|
1
|
+
## v2.12.0 (2026-10-10)
|
|
2
|
+
|
|
3
|
+
### Features
|
|
4
|
+
|
|
5
|
+
- **profile**: add `devstuff profile diff`
|
|
6
|
+
- **profile**: add the diff classifier
|
|
7
|
+
- **profile**: add `devstuff profile snapshot`
|
|
8
|
+
- **generic**: add installed_version() and supports_pin() for profiles
|
|
9
|
+
- **profile**: add the profile file model, strict loader and dumper
|
|
10
|
+
|
|
1
11
|
## v2.11.0 (2026-10-10)
|
|
2
12
|
|
|
3
13
|
### Features
|
|
@@ -65,8 +65,10 @@ src/dev_setup/
|
|
|
65
65
|
├── ui.py # Rich console + questionary wrappers (spinners, prompts, styled output)
|
|
66
66
|
├── verbose.py # Process-wide -v/-vv level + the stderr logger built on it
|
|
67
67
|
├── updates.py # Update probing + the five-state classifier, shared by `update` and `outdated`
|
|
68
|
+
├── profile.py # Profile file format (strict load, deterministic dump) + the seven-state diff classifier — pure
|
|
69
|
+
├── snapshot.py # Asks the machine: builds a Profile / the facts `profile.compare` needs
|
|
68
70
|
├── configure/ # Per-tool setup wizards (see "Configurators" below)
|
|
69
|
-
└── commands/ # One Click command per file: list, install, remove, update, outdated, add, delete, docs, catalog
|
|
71
|
+
└── commands/ # One Click command per file: list, install, remove, update, outdated, profile, add, delete, docs, catalog
|
|
70
72
|
```
|
|
71
73
|
|
|
72
74
|
**Catalog precedence** (`catalog.load_effective_catalog`): bundled `tools.yaml` loads first →
|
|
@@ -155,6 +157,36 @@ and `devstuff outdated` share one collector and one classifier. Things that are
|
|
|
155
157
|
- **Exit status is "did the lookup run", not the answer** (the same rule as `run_cmd`), and `--json`
|
|
156
158
|
writes only the array to stdout, even at `-vv`.
|
|
157
159
|
|
|
160
|
+
**Profiles** (`profile.py`, `snapshot.py`, `commands/profile_cmd.py`; spec in `docs/specs/profile/`):
|
|
161
|
+
`devstuff profile snapshot` / `diff` describe and compare a machine; `apply` is not built (roadmap M3), so the
|
|
162
|
+
file format is provisional. Things that are load-bearing:
|
|
163
|
+
- **`profile.py` is pure and `snapshot.py` asks the machine.** `compare()` takes *facts* (`MachineTool`), not tool
|
|
164
|
+
objects, so the whole decision table is testable without a registry — and is, exhaustively, one case per
|
|
165
|
+
combination of its six inputs.
|
|
166
|
+
- **Loading refuses what YAML silently corrupts**: `version: 1.10` → float `1.1`, `0.40` → `0.4`, `1:30` → int 90
|
|
167
|
+
(sexagesimal), a date → a date object, a duplicate key → the first dropped, a tool key `on`/`yes` → `True`. The
|
|
168
|
+
original text is gone by the time Python sees it, so the loader rejects instead of coercing. `Entry` enforces the
|
|
169
|
+
same rule at construction, so a version `snapshot` builds can always be read back. Emission is safe only because
|
|
170
|
+
`yaml.safe_dump` quotes numeric-looking strings; don't hand-roll it.
|
|
171
|
+
- **Versions come from `GenericTool.installed_version()`** — per-type, local-only readers for the types that can be
|
|
172
|
+
pinned (`npm`, `pip`/`uvx`, single-package `apt`). Never from `get_version()`, which is free text (`'bat 0.26.1
|
|
173
|
+
(979ba22)'`), and never from `check_for_update()`, which also hits the network. A regex over `get_version()` was
|
|
174
|
+
measured at 12 of 13 correct on today's catalog and rejected anyway: its failure is a *wrong pin written silently*.
|
|
175
|
+
- **`supports_pin()` is an explicit set tied to the updaters by a test** (`tests/test_pin_support.py`): a pin must
|
|
176
|
+
actually reach a command, and a refusal must be a refusal *of the pin*, not some other failure that happens to
|
|
177
|
+
raise. Add an updater and that test forces you to say whether it can pin.
|
|
178
|
+
- **Three states mean "could not compare" and are never `ok`**: `unverifiable`, `unpinnable`, `unknown-key`.
|
|
179
|
+
`unpinnable` is decided *before* the version is looked at, so a `bash` tool whose text version equals the pin
|
|
180
|
+
can't read as a match. Same rule as `outdated`'s `unknown`/`unsupported`; it is the point of both commands.
|
|
181
|
+
- **A profile names keys, never definitions or scripts** — otherwise applying one would be arbitrary code execution
|
|
182
|
+
past the catalog's validation. A custom tool is reported as `unknown-key` and moved with `catalog export`/`import`.
|
|
183
|
+
- **Exit status: `2` is a bad profile, `1` is "differs"** (`--exit-code` only). Don't merge them: a CI gate has to
|
|
184
|
+
tell a drifted machine from a typo. Output to stdout is the data and nothing else, at every `-v`.
|
|
185
|
+
- **Tests must be able to reach the guard they claim to test.** CliRunner's stdout is not a TTY, so a "no banner
|
|
186
|
+
under `--json`" test passes whatever the code does unless `isatty()` is forced true (and a counter-test shows the
|
|
187
|
+
banner *does* appear for a person). Likewise defensive `except` around a reader that never raises needs a fake
|
|
188
|
+
reader that does.
|
|
189
|
+
|
|
158
190
|
**Two ways a tool gets defined**: built-in (an entry added directly to `src/dev_setup/tools.yaml`,
|
|
159
191
|
`builtin=True`) or custom (created via the `devstuff add` wizard, `devstuff catalog import`,
|
|
160
192
|
or hand-edited YAML, landing in the user catalog). Both use the identical schema — the only
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: devstuff
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.12.0
|
|
4
4
|
Summary: Development environment setup CLI for Linux
|
|
5
5
|
Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
|
|
6
6
|
Author-email: Sawyer <sawyerksu@gmail.com>
|
|
@@ -372,6 +372,110 @@ includes the `unsupported` rows; `--updates-only` applies to it too.
|
|
|
372
372
|
|
|
373
373
|
---
|
|
374
374
|
|
|
375
|
+
### `profile`
|
|
376
|
+
|
|
377
|
+
Describe which tools a machine should have as a small file, and compare a machine against one.
|
|
378
|
+
Both subcommands are **read-only** and **local** — they ask the machine, never the network — so
|
|
379
|
+
they work offline.
|
|
380
|
+
|
|
381
|
+
```bash
|
|
382
|
+
devstuff profile snapshot > work.yaml # the tools installed here, as a file
|
|
383
|
+
devstuff profile snapshot --versions -o work.yaml # ...and the versions of the ones that can be pinned
|
|
384
|
+
devstuff profile diff work.yaml # how this machine differs from the file
|
|
385
|
+
devstuff profile diff work.yaml --exit-code # exit 1 if it differs: a gate for CI
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
> **The file format is provisional until `profile apply` exists.** It is `version: 1`, and a later
|
|
389
|
+
> breaking change will bump that number. There is no `apply` yet — nothing here installs anything.
|
|
390
|
+
|
|
391
|
+
A profile names catalog **keys**, and optionally a version. It never contains an install script or
|
|
392
|
+
a tool definition, so a profile from somewhere else can't run anything your own catalog doesn't
|
|
393
|
+
already define.
|
|
394
|
+
|
|
395
|
+
```yaml
|
|
396
|
+
version: 1
|
|
397
|
+
tools:
|
|
398
|
+
uv: {} # present, any version
|
|
399
|
+
ipython:
|
|
400
|
+
version: 9.17.1 # present, at exactly this version
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
**Quote any version that looks like a number.** YAML reads `version: 1.10` as the number 1.1 and
|
|
404
|
+
`0.40` as 0.4, and the original text can't be recovered — so devstuff refuses it and says to quote
|
|
405
|
+
it (`version: '1.10'`). It also refuses a duplicate key, which YAML would otherwise resolve by
|
|
406
|
+
silently dropping the first, an unknown field, and a tool key that YAML reads as something other
|
|
407
|
+
than text (`on`, `yes`, `123`). `snapshot` always writes versions correctly quoted.
|
|
408
|
+
|
|
409
|
+
#### `snapshot`
|
|
410
|
+
|
|
411
|
+
Writes a profile of every installed tool, to stdout or to `-o FILE`. By default it records **keys
|
|
412
|
+
only**: a profile that pins versions goes stale the day a tool updates, and then reports drift
|
|
413
|
+
nobody intended. `--versions` adds the installed version for the tools that can be pinned — `npm`,
|
|
414
|
+
`pip`/`uvx`, and single-package `apt`; `git`, `script` and `bash` tools can't be installed at a
|
|
415
|
+
chosen version, so a version recorded for them could never be acted on and is left out.
|
|
416
|
+
|
|
417
|
+
- If a pinnable tool's version can't be read (say it is on your `PATH` but isn't a `uv tool`), it is
|
|
418
|
+
written without one and a warning on stderr names it and says why — it is never dropped silently.
|
|
419
|
+
- Tools defined in your own catalog are included, with one stderr note that another machine won't
|
|
420
|
+
know them: move their definitions with `devstuff catalog export` / `import`.
|
|
421
|
+
- Output is **deterministic** — sorted, with a fixed header and no timestamp, hostname or path — so
|
|
422
|
+
a profile kept in git shows only real changes.
|
|
423
|
+
- `-o` refuses to overwrite an existing file (exit 2) unless you pass `--force`.
|
|
424
|
+
- With no `-o`, stdout is exactly the YAML; warnings and notes go to stderr.
|
|
425
|
+
|
|
426
|
+
#### `diff`
|
|
427
|
+
|
|
428
|
+
```
|
|
429
|
+
╭──────────────────────────────────────────────────────────────────────────────╮
|
|
430
|
+
│ Package Type Profile Installed Status │
|
|
431
|
+
├──────────────────────────────────────────────────────────────────────────────┤
|
|
432
|
+
│ reptyr apt ✘ missing │
|
|
433
|
+
│ ipython uvx 9.0.0 9.17.1 ≠ drift │
|
|
434
|
+
│ commitizen uvx 4.16.4 ? unverifiable │
|
|
435
|
+
│ uv doesn't list it as a tool │
|
|
436
|
+
│ (is it installed another │
|
|
437
|
+
│ way?) │
|
|
438
|
+
│ starship bash 1.0.0 – unpinnable │
|
|
439
|
+
│ a bash install can't be │
|
|
440
|
+
│ pinned, so the pin is ignored │
|
|
441
|
+
│ not-a-real-tool ? unknown-key │
|
|
442
|
+
│ not in this machine's catalog │
|
|
443
|
+
│ — if it is a custom tool, │
|
|
444
|
+
│ bring its definition over │
|
|
445
|
+
│ with `devstuff catalog │
|
|
446
|
+
│ import` │
|
|
447
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
448
|
+
1 installed tool isn't in the profile: gh (--all lists them)
|
|
449
|
+
1 missing · 1 drift · 1 unverifiable · 1 unpinnable · 1 unknown-key · 1 extra · 9 ok
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
| State | Meaning |
|
|
453
|
+
|-------|---------|
|
|
454
|
+
| `ok` | In the profile and installed; and, if pinned, at the pinned version. |
|
|
455
|
+
| `missing` | In the profile and the catalog, but not installed. |
|
|
456
|
+
| `drift` | Pinned and installed, but at a different version. |
|
|
457
|
+
| `unverifiable` | Pinned and installed, but the installed version can't be read. |
|
|
458
|
+
| `unpinnable` | Pinned, but this tool's install type can't honour a pin — the pin is ignored. |
|
|
459
|
+
| `unknown-key` | In the profile but not in this machine's catalog. |
|
|
460
|
+
| `extra` | Installed, but not in the profile. |
|
|
461
|
+
|
|
462
|
+
`unverifiable`, `unpinnable` and `unknown-key` are three different reasons the comparison couldn't
|
|
463
|
+
be made, each with a different remedy, and **none of them is ever reported as `ok`**. Versions are
|
|
464
|
+
compared as text: `0.45` is not `0.45.0`, and a *newer* installed version is as much drift as an
|
|
465
|
+
older one.
|
|
466
|
+
|
|
467
|
+
By default only differences are listed; the matching tools are counted in the last line, and
|
|
468
|
+
`--all` lists them (and the extras) as rows. `--json` writes one array — every state, always — of
|
|
469
|
+
`{"key", "state", "type", "pinned", "installed", "note"}` objects and nothing else, even at `-vv`.
|
|
470
|
+
|
|
471
|
+
**Exit status.** `0` whenever the comparison ran, whatever it found. With `--exit-code` it is `1`
|
|
472
|
+
if the machine differs; an installed tool that isn't in the profile counts as a difference unless
|
|
473
|
+
you also pass `--ignore-extras`, which affects only this exit status and never hides a real
|
|
474
|
+
difference. A profile that is missing, unreadable or invalid is always `2`, so `1` can only ever
|
|
475
|
+
mean "differs".
|
|
476
|
+
|
|
477
|
+
---
|
|
478
|
+
|
|
375
479
|
### `configure`
|
|
376
480
|
|
|
377
481
|
Set up an installed tool through a guided wizard, previewing the result before anything is
|
|
@@ -345,6 +345,110 @@ includes the `unsupported` rows; `--updates-only` applies to it too.
|
|
|
345
345
|
|
|
346
346
|
---
|
|
347
347
|
|
|
348
|
+
### `profile`
|
|
349
|
+
|
|
350
|
+
Describe which tools a machine should have as a small file, and compare a machine against one.
|
|
351
|
+
Both subcommands are **read-only** and **local** — they ask the machine, never the network — so
|
|
352
|
+
they work offline.
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
devstuff profile snapshot > work.yaml # the tools installed here, as a file
|
|
356
|
+
devstuff profile snapshot --versions -o work.yaml # ...and the versions of the ones that can be pinned
|
|
357
|
+
devstuff profile diff work.yaml # how this machine differs from the file
|
|
358
|
+
devstuff profile diff work.yaml --exit-code # exit 1 if it differs: a gate for CI
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
> **The file format is provisional until `profile apply` exists.** It is `version: 1`, and a later
|
|
362
|
+
> breaking change will bump that number. There is no `apply` yet — nothing here installs anything.
|
|
363
|
+
|
|
364
|
+
A profile names catalog **keys**, and optionally a version. It never contains an install script or
|
|
365
|
+
a tool definition, so a profile from somewhere else can't run anything your own catalog doesn't
|
|
366
|
+
already define.
|
|
367
|
+
|
|
368
|
+
```yaml
|
|
369
|
+
version: 1
|
|
370
|
+
tools:
|
|
371
|
+
uv: {} # present, any version
|
|
372
|
+
ipython:
|
|
373
|
+
version: 9.17.1 # present, at exactly this version
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
**Quote any version that looks like a number.** YAML reads `version: 1.10` as the number 1.1 and
|
|
377
|
+
`0.40` as 0.4, and the original text can't be recovered — so devstuff refuses it and says to quote
|
|
378
|
+
it (`version: '1.10'`). It also refuses a duplicate key, which YAML would otherwise resolve by
|
|
379
|
+
silently dropping the first, an unknown field, and a tool key that YAML reads as something other
|
|
380
|
+
than text (`on`, `yes`, `123`). `snapshot` always writes versions correctly quoted.
|
|
381
|
+
|
|
382
|
+
#### `snapshot`
|
|
383
|
+
|
|
384
|
+
Writes a profile of every installed tool, to stdout or to `-o FILE`. By default it records **keys
|
|
385
|
+
only**: a profile that pins versions goes stale the day a tool updates, and then reports drift
|
|
386
|
+
nobody intended. `--versions` adds the installed version for the tools that can be pinned — `npm`,
|
|
387
|
+
`pip`/`uvx`, and single-package `apt`; `git`, `script` and `bash` tools can't be installed at a
|
|
388
|
+
chosen version, so a version recorded for them could never be acted on and is left out.
|
|
389
|
+
|
|
390
|
+
- If a pinnable tool's version can't be read (say it is on your `PATH` but isn't a `uv tool`), it is
|
|
391
|
+
written without one and a warning on stderr names it and says why — it is never dropped silently.
|
|
392
|
+
- Tools defined in your own catalog are included, with one stderr note that another machine won't
|
|
393
|
+
know them: move their definitions with `devstuff catalog export` / `import`.
|
|
394
|
+
- Output is **deterministic** — sorted, with a fixed header and no timestamp, hostname or path — so
|
|
395
|
+
a profile kept in git shows only real changes.
|
|
396
|
+
- `-o` refuses to overwrite an existing file (exit 2) unless you pass `--force`.
|
|
397
|
+
- With no `-o`, stdout is exactly the YAML; warnings and notes go to stderr.
|
|
398
|
+
|
|
399
|
+
#### `diff`
|
|
400
|
+
|
|
401
|
+
```
|
|
402
|
+
╭──────────────────────────────────────────────────────────────────────────────╮
|
|
403
|
+
│ Package Type Profile Installed Status │
|
|
404
|
+
├──────────────────────────────────────────────────────────────────────────────┤
|
|
405
|
+
│ reptyr apt ✘ missing │
|
|
406
|
+
│ ipython uvx 9.0.0 9.17.1 ≠ drift │
|
|
407
|
+
│ commitizen uvx 4.16.4 ? unverifiable │
|
|
408
|
+
│ uv doesn't list it as a tool │
|
|
409
|
+
│ (is it installed another │
|
|
410
|
+
│ way?) │
|
|
411
|
+
│ starship bash 1.0.0 – unpinnable │
|
|
412
|
+
│ a bash install can't be │
|
|
413
|
+
│ pinned, so the pin is ignored │
|
|
414
|
+
│ not-a-real-tool ? unknown-key │
|
|
415
|
+
│ not in this machine's catalog │
|
|
416
|
+
│ — if it is a custom tool, │
|
|
417
|
+
│ bring its definition over │
|
|
418
|
+
│ with `devstuff catalog │
|
|
419
|
+
│ import` │
|
|
420
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
421
|
+
1 installed tool isn't in the profile: gh (--all lists them)
|
|
422
|
+
1 missing · 1 drift · 1 unverifiable · 1 unpinnable · 1 unknown-key · 1 extra · 9 ok
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
| State | Meaning |
|
|
426
|
+
|-------|---------|
|
|
427
|
+
| `ok` | In the profile and installed; and, if pinned, at the pinned version. |
|
|
428
|
+
| `missing` | In the profile and the catalog, but not installed. |
|
|
429
|
+
| `drift` | Pinned and installed, but at a different version. |
|
|
430
|
+
| `unverifiable` | Pinned and installed, but the installed version can't be read. |
|
|
431
|
+
| `unpinnable` | Pinned, but this tool's install type can't honour a pin — the pin is ignored. |
|
|
432
|
+
| `unknown-key` | In the profile but not in this machine's catalog. |
|
|
433
|
+
| `extra` | Installed, but not in the profile. |
|
|
434
|
+
|
|
435
|
+
`unverifiable`, `unpinnable` and `unknown-key` are three different reasons the comparison couldn't
|
|
436
|
+
be made, each with a different remedy, and **none of them is ever reported as `ok`**. Versions are
|
|
437
|
+
compared as text: `0.45` is not `0.45.0`, and a *newer* installed version is as much drift as an
|
|
438
|
+
older one.
|
|
439
|
+
|
|
440
|
+
By default only differences are listed; the matching tools are counted in the last line, and
|
|
441
|
+
`--all` lists them (and the extras) as rows. `--json` writes one array — every state, always — of
|
|
442
|
+
`{"key", "state", "type", "pinned", "installed", "note"}` objects and nothing else, even at `-vv`.
|
|
443
|
+
|
|
444
|
+
**Exit status.** `0` whenever the comparison ran, whatever it found. With `--exit-code` it is `1`
|
|
445
|
+
if the machine differs; an installed tool that isn't in the profile counts as a difference unless
|
|
446
|
+
you also pass `--ignore-extras`, which affects only this exit status and never hides a real
|
|
447
|
+
difference. A profile that is missing, unreadable or invalid is always `2`, so `1` can only ever
|
|
448
|
+
mean "differs".
|
|
449
|
+
|
|
450
|
+
---
|
|
451
|
+
|
|
348
452
|
### `configure`
|
|
349
453
|
|
|
350
454
|
Set up an installed tool through a guided wizard, previewing the result before anything is
|
|
@@ -64,7 +64,10 @@ over an existing probe and an existing collector, not new probing.
|
|
|
64
64
|
|
|
65
65
|
## M2 — `devstuff profile snapshot` and `diff`
|
|
66
66
|
|
|
67
|
-
|
|
67
|
+
**Spec:** [`specs/profile/`](specs/profile/) — **done** (v1, 2026-10-10): `snapshot` and `diff`. `apply` (M3) gets its own requirements.
|
|
68
|
+
|
|
69
|
+
A profile is a YAML file: catalog keys and optional pinned versions. Configurator output is **not** part of it
|
|
70
|
+
(several configurators don't round-trip); capturing it is a separate, later decision.
|
|
68
71
|
|
|
69
72
|
```yaml
|
|
70
73
|
version: 1
|
|
@@ -74,22 +77,26 @@ tools:
|
|
|
74
77
|
starship: {}
|
|
75
78
|
```
|
|
76
79
|
|
|
77
|
-
**
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
80
|
+
**Built** (v1, 2026-10-10): `profile snapshot` and `profile diff` (spec milestones P1–P6). The format is **provisional**
|
|
81
|
+
until M3 exists. What the design turned into, where it differs from the first sketch:
|
|
82
|
+
- **Versions are read locally, per type** (`installed_version()`), never from `get_version()`'s free text and never
|
|
83
|
+
via the update checkers, which hit the network. Only types that can be pinned (`npm`, `pip`/`uvx`, single-package
|
|
84
|
+
`apt`) ever get a version. So `snapshot` works offline.
|
|
85
|
+
- **`diff` reports seven states**, not four: `ok`, `missing`, `drift`, `unverifiable`, `unpinnable`, `unknown-key`,
|
|
86
|
+
`extra`. The three "could not compare" ones are never `ok` — the M1 lesson, applied again.
|
|
87
|
+
- **Loading is strict beyond the catalog's own rules**: YAML silently turns `version: 1.10` into `1.1` and drops
|
|
88
|
+
duplicate keys, so both are errors rather than coerced.
|
|
89
|
+
- A profile references catalog keys only and never embeds install scripts, so a profile file can't smuggle commands
|
|
90
|
+
past the catalog's validation. A custom tool is `unknown-key` on a machine without it; `catalog export`/`import`
|
|
91
|
+
moves definitions.
|
|
92
|
+
- `--exit-code` shipped in v1 (`1` = differs, `2` = bad profile), unlike `outdated`'s, because drift-gating is this
|
|
93
|
+
feature's headline use.
|
|
87
94
|
|
|
88
95
|
**Done when**
|
|
89
|
-
- [
|
|
90
|
-
|
|
91
|
-
- [
|
|
92
|
-
- [
|
|
96
|
+
- [x] `profile snapshot` writes a valid profile; `profile diff` of a fresh snapshot against the same machine reports
|
|
97
|
+
no differences — tested on a fake machine, and live on a real one (`13 ok`, exit 0).
|
|
98
|
+
- [x] Keys unknown to the effective catalog are reported, not silently dropped (`unknown-key`).
|
|
99
|
+
- [x] Spec records the rejected alternative of extending `catalog export` instead, with reasons (`stack-decisions.md` SD-1).
|
|
93
100
|
|
|
94
101
|
## M3 — `devstuff profile apply` and bundled bundles
|
|
95
102
|
|
|
@@ -98,13 +105,18 @@ Turn a profile into an install plan and run it.
|
|
|
98
105
|
- **Ordering** comes from the existing `requires` graph (including auto-inferred edges such as
|
|
99
106
|
`npm` → `nvm`). Do not write a second dependency resolver; if the existing one is not exposed in
|
|
100
107
|
a reusable form, factor it out first.
|
|
101
|
-
- **Plan before action**:
|
|
102
|
-
`install`/`update`
|
|
108
|
+
- **Plan before action**: `apply` shows what it will do and asks first. The plan-preview helper
|
|
109
|
+
`install`/`update` are gaining lives on the unmerged UI branch (`commands/_plan.py`); reuse it if it
|
|
110
|
+
has landed, rather than writing a second one.
|
|
103
111
|
- **Failure policy** needs a decision in the spec: continue past a failed tool and summarise, or
|
|
104
112
|
stop. Recommendation: continue, skip anything whose `requires` failed, and report at the end —
|
|
105
113
|
a 40-tool apply that dies on tool 3 is worse than one that finishes 39.
|
|
106
|
-
- **Pins on `script`/`bash` tools
|
|
107
|
-
and
|
|
114
|
+
- **Pins on `git`/`script`/`bash` tools cannot be honoured at all** — `update(version=…)` raises for them
|
|
115
|
+
(spec F-2) — and `diff` already reports them `unpinnable`. `apply` must say so rather than quietly
|
|
116
|
+
install latest.
|
|
117
|
+
- **A pinned install is install-then-update**: `install()` takes no version (spec F-4), so applying a pin
|
|
118
|
+
means installing the latest and then calling `update(version=…)` — two installs, and for `apt` a
|
|
119
|
+
downgrade. Whether to teach the `npm`/`uvx`/`apt` installers a version instead is an M3 decision.
|
|
108
120
|
- **Bundled bundles** (`@backend`, `@devops`, …) are profile files shipped in the package. They are
|
|
109
121
|
data, so they get a validation test and a CI check that every key they name exists in the
|
|
110
122
|
bundled catalog — the same two-direction enforcement as the CI-matrix test.
|
|
@@ -48,3 +48,4 @@ They are most useful when they capture:
|
|
|
48
48
|
| [`lazygit-config/`](lazygit-config/) — `devstuff configure lazygit`, the icons/pager/panels wizard | Complete (v1) |
|
|
49
49
|
| [`verbose-mode/`](verbose-mode/) — `-v`/`-vv`, the process-wide verbosity level | Complete (v1) |
|
|
50
50
|
| [`outdated/`](outdated/) — `devstuff outdated`, the read-only installed-vs-latest report | Complete (v1) |
|
|
51
|
+
| [`profile/`](profile/) — `devstuff profile snapshot` / `diff`, a portable description of a machine's tools | Complete (v1: snapshot, diff; apply is M3) |
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Development plan: `devstuff profile` (snapshot, diff)
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-10-10
|
|
4
|
+
**Status:** Complete (v1), 2026-10-10
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Milestones
|
|
9
|
+
|
|
10
|
+
Each milestone is one commit. Ordering puts the pure, no-I/O pieces first so the rules that matter
|
|
11
|
+
are tested before any command exists — the order that worked for `outdated`.
|
|
12
|
+
|
|
13
|
+
| # | Milestone | Satisfies | State |
|
|
14
|
+
|---|-----------|-----------|-------|
|
|
15
|
+
| P1 | `dev_setup/profile.py`: `Profile` model, strict loader (duplicate-key detecting), deterministic dumper | FR-1–6, FR-9, FR-24, NFR-4 | **Done** 2026-10-10 |
|
|
16
|
+
| P2 | `GenericTool.installed_version()` (local readers factored out of the checkers), `supports_pin`, and the test tying it to `update(version=…)` | FR-10–12, FR-25–26, SD-3/4/10 | **Done** 2026-10-10 |
|
|
17
|
+
| P3 | `devstuff profile snapshot` (group + command, `-o`, `--versions`, `--force`, stderr notes), registered in the CLI and help table | FR-7–8, 13–14, 23, NFR-1/2 | **Done** 2026-10-10 |
|
|
18
|
+
| P4 | Diff classifier — pure function over (profile, installed state, catalog) → seven states, counts, ordering | FR-16–18, 20 | **Done** 2026-10-10 |
|
|
19
|
+
| P5 | `devstuff profile diff` (table, footer, `--all`, `--json`, `--exit-code`, `--ignore-extras`, exit 2 on bad profile) | FR-15, 19, 21–22, NFR-1 | **Done** 2026-10-10 |
|
|
20
|
+
| P6 | README command reference, CLAUDE.md rules, roadmap + specs index | — | **Done** 2026-10-10 |
|
|
21
|
+
|
|
22
|
+
P2 is the only milestone that changes existing behaviour (it factors the `dpkg-query` read out of
|
|
23
|
+
`_check_update_apt`; the npm and uv reads were already separate functions). It lands before any command uses
|
|
24
|
+
it, and its parity test pins that `check_for_update` returns what it did before.
|
|
25
|
+
|
|
26
|
+
## Testing strategy
|
|
27
|
+
|
|
28
|
+
Unit-only; no network, no real installs — default suite, ~0.3 s each file.
|
|
29
|
+
|
|
30
|
+
- **Loader, exhaustively (P1).** One parametrized test over every rejection in FR-3–5: unknown
|
|
31
|
+
top-level field, unknown entry field, `tools` not a mapping, entry not a mapping, file version
|
|
32
|
+
`2`, a duplicate key, and each of `1.10`, `0.40`, `2`, `2026-09-30` as an unquoted `version`
|
|
33
|
+
(the F-5 inputs, verbatim). Each asserts the error names the file and the key. And the accepted
|
|
34
|
+
spellings: `uv: {}`, bare `uv:`, `version: '1.10'`.
|
|
35
|
+
- **Round trip (P1, NFR-4).** `load(dump(p)) == p` over versions that look numeric — `'0.45'`,
|
|
36
|
+
`'1.10'`, `'2'` — since that is exactly where a hand-rolled emitter would fail and `safe_dump`
|
|
37
|
+
must be proven to hold.
|
|
38
|
+
- **Determinism (P1/P3, FR-9).** Two snapshots of the same fake machine are byte-identical, and the
|
|
39
|
+
output contains no hostname, username, home path or digits that look like a date.
|
|
40
|
+
- **Pinnability matches reality (P2, FR-26).** For every install type, build a minimal tool, call
|
|
41
|
+
`update(version="1.2.3")` with the installers stubbed out, and assert it raises *iff*
|
|
42
|
+
`supports_pin` is False. This must fail if someone teaches `git` to pin without updating the
|
|
43
|
+
predicate — verified by temporarily breaking one side, like `outdated`'s renderer mutation check.
|
|
44
|
+
- **Local readers never touch the network (P2, NFR-2).** Stub `_probe` to record argv and assert
|
|
45
|
+
`installed_version()` issues only `npm list`, `uv tool list` or `dpkg-query` and never `npm view`,
|
|
46
|
+
`uv tool list --outdated`, `apt-cache policy` or `git ls-remote`.
|
|
47
|
+
- **Readers never raise (P2, FR-25).** A stub raising `RuntimeError` or timing out → `""`.
|
|
48
|
+
- **Snapshot (P3).** Default has no `version` keys; `--versions` adds them only for pinnable types;
|
|
49
|
+
an unreadable pinnable tool yields an entry *without* a version plus a stderr warning naming it
|
|
50
|
+
(FR-12); `-o` writes the file and leaves stdout empty; an existing `-o` target is refused without
|
|
51
|
+
`--force`; custom-catalog tools are included and counted on stderr (FR-13).
|
|
52
|
+
- **Stdout purity (P3/P5, NFR-1).** `snapshot` and `diff --json` at `-vv` with a fake tool whose
|
|
53
|
+
probe logs: stdout parses as YAML/JSON, stderr is non-empty so the test is not vacuous.
|
|
54
|
+
- **Classifier, exhaustively (P4).** One row per state, plus the pairs that must stay apart: a
|
|
55
|
+
pinned `bash` key (`unpinnable`) vs a pinned `npm` key whose version cannot be read
|
|
56
|
+
(`unverifiable`) vs a key the catalog lacks (`unknown-key`). Counts sum to keys considered, and
|
|
57
|
+
none of the three folds into `ok` (FR-17). A rendering test breaks the renderer so `unverifiable`
|
|
58
|
+
shows as `ok` and asserts the test fails — the guard that `outdated` needed and had.
|
|
59
|
+
- **Exit status (P5, FR-22).** Default `0` with differences present; `--exit-code` `1` on a
|
|
60
|
+
difference and `0` on a clean match; `extra` flips it unless `--ignore-extras`; a malformed
|
|
61
|
+
profile and a missing file are `2` both with and without `--exit-code`.
|
|
62
|
+
- **Read-only (P5, FR-15).** Fakes whose `install`/`remove`/`update` raise; the command completes.
|
|
63
|
+
- **Self-diff (NFR-4).** On a fake machine, `diff(snapshot())` reports no differences, and with
|
|
64
|
+
`--versions` too.
|
|
65
|
+
|
|
66
|
+
**Live verification** (not in the suite; recorded here when done): on a real machine, `snapshot
|
|
67
|
+
--versions` then `diff` reports clean; then pin one tool to a wrong version, uninstall nothing, add
|
|
68
|
+
a bogus key, and check the report shows exactly `drift` and `unknown-key` and exits `1` under
|
|
69
|
+
`--exit-code`. Repeat `snapshot` with the network blocked — it must succeed, since it asks the
|
|
70
|
+
network nothing (NFR-2). `outdated`'s equivalent step found a real bug (its F-7) that the unit tests
|
|
71
|
+
could not, so this step is not optional.
|
|
72
|
+
|
|
73
|
+
**P2 verification, 2026-10-10.** 65 tests across `test_update_checker_parity.py` (baseline written and run against the
|
|
74
|
+
*unrefactored* code first), `test_pin_support.py` and `test_installed_version.py`. Twelve deliberate breakages were each caught
|
|
75
|
+
— but only after strengthening three tests that the first round let survive: the pin test treated *any* `RuntimeError` as
|
|
76
|
+
"refused the pin" (so an updater that quietly accepted one, then failed on a missing clone, passed); the never-raises test
|
|
77
|
+
never reached the outer guard because the inner readers swallow their own errors; and a get_version() trap raised inside
|
|
78
|
+
a function that swallows exceptions. Live on a real machine: `commitizen` is pinnable by type but unreadable (not a `uv tool`),
|
|
79
|
+
which is precisely the `unverifiable` state; results are identical with the network blocked.
|
|
80
|
+
|
|
81
|
+
**P3 verification, 2026-10-10.** 42 tests (`test_snapshot.py`, `test_profile_snapshot_cmd.py`); 17 deliberate breakages, 16 caught
|
|
82
|
+
first time. The survivor was real: `snapshot` guards against an `installed_version()` that raises, but the real one never does, so
|
|
83
|
+
nothing exercised the guard — now tested. Live on a real machine: default output is keys only; `--versions` pins exactly the four
|
|
84
|
+
readable tools and writes `commitizen` bare with a warning naming it and why; a second `-o` is refused with exit 2; with the network
|
|
85
|
+
blocked it succeeds in 1.9 s with output byte-identical to online; three runs hash identically; no hostname, user, home path or
|
|
86
|
+
year appears in the output.
|
|
87
|
+
|
|
88
|
+
**P4 verification, 2026-10-10.** 109 tests in `test_profile_diff.py`, 72 of them one parametrized case per valid combination of
|
|
89
|
+
(in profile, pin, catalog knows, installed, pinnable, version read) — 96 raw, less the 24 that would pin a key not in the profile: each asserts the spec's rule for that combination, and a
|
|
90
|
+
second test asserts the grid reaches all seven states, so a state the table never produces cannot hide. The FR-17 property is
|
|
91
|
+
also stated directly — `ok` implies the comparison genuinely succeeded. 18 deliberate breakages, all caught first time: each
|
|
92
|
+
"could not compare" state rendered as `ok`, the precedence between `missing`/`unpinnable`/`unknown-key`, version comparison made
|
|
93
|
+
to normalise or to order, extras handling in `differs`, and a summary that omits zero counts.
|
|
94
|
+
|
|
95
|
+
**P5 verification, 2026-10-10.** 49 tests in `test_profile_diff_cmd.py`; 28 deliberate breakages, 25 caught first time. The three
|
|
96
|
+
survivors were each a real gap: the shared fixture's only missing tool was *unpinned* so nothing tempted a read of a pinned,
|
|
97
|
+
uninstalled tool; no test made a version reader raise during a diff; and the notes in real use are fixed strings, so only a direct
|
|
98
|
+
call could prove bracket-escaping. All now tested. One test needed `isatty()` forced true on CliRunner's stream — under a plain
|
|
99
|
+
runner the banner/spinner guard is never reached, so "no banner under --json" passes whatever the code does.
|
|
100
|
+
|
|
101
|
+
Live on a real machine: a fresh `snapshot --versions` diffs clean (`13 ok`, exit 0). Then, with `ipython` pinned wrong, `starship`
|
|
102
|
+
(bash) pinned, `commitizen` pinned (it is on PATH but not a `uv tool`), `gh` removed, an uninstalled tool and a bogus key added,
|
|
103
|
+
the report named exactly `missing`, `drift`, `unverifiable`, `unpinnable`, `unknown-key` and `extra`, and `--exit-code` gave 1. A
|
|
104
|
+
pin written `1.10` and a missing file both gave 2. With the network blocked: 1.5 s, same answer.
|
|
105
|
+
|
|
106
|
+
**P6, 2026-10-10.** README command reference, CLAUDE.md rules, roadmap and specs index. Re-reading the roadmap against what was
|
|
107
|
+
built found its M2 section stale in three ways (it said a snapshot probes `get_version()`, that `diff` has four states, and its
|
|
108
|
+
done-when boxes were unticked) and its M3 section wrong in two (it pointed at `_plan.py`, which exists only on the unmerged UI
|
|
109
|
+
branch, and said pins on `script`/`bash` could be honoured by a reinstall, when `update(version=…)` raises for them). All fixed
|
|
110
|
+
in the same change, per `docs/specs/README.md`: "keep them current, or delete them".
|
|
111
|
+
|
|
112
|
+
## Risks
|
|
113
|
+
|
|
114
|
+
| Risk | Likelihood | Mitigation |
|
|
115
|
+
|------|-----------|------------|
|
|
116
|
+
| The format hardens before `apply` has been tried (roadmap risk) | Medium | Mark the file format provisional in the README until M3 lands; `version: 1` stays reserved for the stabilised shape, and a later breaking change bumps it |
|
|
117
|
+
| Factoring local reads out of the update checkers (P2) subtly changes `outdated`/`update` | Medium | A parity test over each checker before and after; P2 is its own commit so a regression bisects to it |
|
|
118
|
+
| A profile pins a version the registry no longer serves, and `diff` reports `drift` forever | Medium | Intended — drift is what it says. `apply` (M3) decides what to do about an unobtainable pin |
|
|
119
|
+
| `unknown-key` is common because the user catalog differs between machines | High | It is a first-class state with its own wording and a pointer to `catalog export`/`import`, not an error |
|
|
120
|
+
| `--exit-code` gets wired into CI by people who then set `--ignore-extras` everywhere | Low | Not a risk to correctness; the flag exists for it |
|
|
121
|
+
| `apt` pins are flaky (a version string that exists only on one release) | Medium | Reported as `drift`/`unverifiable` truthfully; `apply` is where the cost lands, and it is deferred |
|
|
122
|
+
|
|
123
|
+
## Out of scope for this plan
|
|
124
|
+
|
|
125
|
+
`apply`, bundled bundles, and configurator capture. `apply` needs its own requirements and a
|
|
126
|
+
decision on each constraint in `specifications.md` §6. Configurator capture is a separate spec
|
|
127
|
+
and does not block M3.
|