devstuff 2.9.0__tar.gz → 2.11.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.9.0 → devstuff-2.11.0}/CHANGELOG.md +22 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/CLAUDE.md +23 -1
- {devstuff-2.9.0 → devstuff-2.11.0}/PKG-INFO +59 -1
- {devstuff-2.9.0 → devstuff-2.11.0}/README.md +58 -0
- devstuff-2.11.0/docs/ROADMAP.md +177 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/README.md +1 -0
- devstuff-2.11.0/docs/specs/outdated/development-plan.md +78 -0
- devstuff-2.11.0/docs/specs/outdated/specifications.md +169 -0
- devstuff-2.11.0/docs/specs/outdated/stack-decisions.md +97 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/pyproject.toml +1 -1
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/cli.py +2 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/help_cmd.py +1 -0
- devstuff-2.11.0/src/dev_setup/commands/outdated_cmd.py +141 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/update_cmd.py +2 -20
- devstuff-2.11.0/src/dev_setup/configure/starship/icons.py +166 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/model.py +22 -2
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/render.py +39 -24
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/wizard.py +309 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/generic.py +107 -20
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/ui.py +9 -0
- devstuff-2.11.0/src/dev_setup/updates.py +148 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_starship.py +372 -1
- devstuff-2.11.0/tests/test_outdated_cmd.py +331 -0
- devstuff-2.11.0/tests/test_update_notes.py +77 -0
- devstuff-2.11.0/tests/test_updates.py +217 -0
- devstuff-2.11.0/tests/test_uv_probes.py +212 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/uv.lock +1 -1
- {devstuff-2.9.0 → devstuff-2.11.0}/.claude/skills/run-stuff/SKILL.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.claude/skills/run-stuff/smoke.sh +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.github/codex/review.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.github/workflows/agent.yml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.github/workflows/bump.yml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.github/workflows/ci.yml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.github/workflows/publish.yml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.github/workflows/test-installs.yml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/.gitignore +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/dev/Dockerfile +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/dev/Dockerfile.ci +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/dev/Makefile +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/dev/docker-compose.yml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/devstuff +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/github-agent.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/agent/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/agent/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/agent/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/ansible-config/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/ansible-config/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/ansible-config/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/bat-config/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/bat-config/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/bat-config/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/commitizen-config/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/commitizen-config/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/commitizen-config/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/docker-config/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/docker-config/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/docker-config/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/lazygit-config/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/lazygit-config/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/lazygit-config/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/precommit-config/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/precommit-config/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/precommit-config/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/starship-config/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/starship-config/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/starship-config/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/uv-backbone/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/uv-backbone/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/uv-backbone/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/verbose-mode/development-plan.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/verbose-mode/specifications.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/docs/specs/verbose-mode/stack-decisions.md +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/install.sh +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/__main__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/approval.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/bridges.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/catalog.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/completion.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/config.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/loop.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/ollama.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/preflight.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/primitives.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/registry.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/sandbox.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/session.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/transcript.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent_tools.schema.json +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/agent_tools.yaml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/base.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/catalog.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/add_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/agent_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/catalog_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/configure_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/delete_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/docs_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/doctor_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/functions_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/install_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/links_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/list_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/remove_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/run_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/commands/skills_cmd.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/detect.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/model.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/render.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/validate.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/ansible/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/detect.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/model.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/preview.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/render.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/bat/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/detect.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/model.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/render.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/validate.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/commitizen/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/detect.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/model.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/render.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/validate.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/docker/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/detect.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/model.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/render.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/validate.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/lazygit/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/detect.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/model.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/render.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/validate.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/precommit/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/reptyr/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/reptyr/wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/fonts.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/configure/starship/preview.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/doctor.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/function_runner.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/functions.schema.json +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/functions.yaml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/functions_catalog.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/functions_registry.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/links.schema.json +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/links.yaml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/links_catalog.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/links_registry.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/registry.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/tools.yaml +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/src/dev_setup/verbose.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/integration/__init__.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/integration/conftest.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/integration/test_agent_smoke.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/integration/test_agent_tui.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/integration/test_commitizen_config.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/integration/test_tools.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_agent.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_agent_completion.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_agent_loop.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_agent_sandbox.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_agent_tools.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_agent_wizard.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_catalog.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_ansible.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_bat.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_commitizen.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_docker.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_lazygit.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_precommit.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_configure_reptyr.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_doctor.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_functions.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_generic.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_links.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_registry.py +0 -0
- {devstuff-2.9.0 → devstuff-2.11.0}/tests/test_verbose.py +0 -0
|
@@ -1,3 +1,25 @@
|
|
|
1
|
+
## v2.11.0 (2026-10-10)
|
|
2
|
+
|
|
3
|
+
### Features
|
|
4
|
+
|
|
5
|
+
- **outdated**: add `devstuff outdated`, a read-only update report
|
|
6
|
+
- **updates**: classify tools into five honest states
|
|
7
|
+
|
|
8
|
+
### Bug Fixes
|
|
9
|
+
|
|
10
|
+
- **update**: a failed uv probe is unknown, not current; add UpdateStatus.note
|
|
11
|
+
- **update**: probe uv once per run instead of once per tool
|
|
12
|
+
|
|
13
|
+
### Refactors
|
|
14
|
+
|
|
15
|
+
- **update**: move the update collector into a shared module
|
|
16
|
+
|
|
17
|
+
## v2.10.0 (2026-10-10)
|
|
18
|
+
|
|
19
|
+
### Features
|
|
20
|
+
|
|
21
|
+
- **starship**: add per-section color and icon customization
|
|
22
|
+
|
|
1
23
|
## v2.9.0 (2026-10-10)
|
|
2
24
|
|
|
3
25
|
### Features
|
|
@@ -64,8 +64,9 @@ 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`
|
|
67
68
|
├── configure/ # Per-tool setup wizards (see "Configurators" below)
|
|
68
|
-
└── commands/ # One Click command per file: list, install, remove, add, delete, docs, catalog
|
|
69
|
+
└── commands/ # One Click command per file: list, install, remove, update, outdated, add, delete, docs, catalog
|
|
69
70
|
```
|
|
70
71
|
|
|
71
72
|
**Catalog precedence** (`catalog.load_effective_catalog`): bundled `tools.yaml` loads first →
|
|
@@ -133,6 +134,27 @@ through call signatures. Three things about it are load-bearing:
|
|
|
133
134
|
streaming output. At `-vv` script bodies run under `bash -x`, *except* eval-mode function
|
|
134
135
|
scripts — `set -x` there would persist in the caller's interactive shell.
|
|
135
136
|
|
|
137
|
+
**Update probing and `outdated`** (`updates.py`, spec in `docs/specs/outdated/`): `update`'s picker
|
|
138
|
+
and `devstuff outdated` share one collector and one classifier. Things that are load-bearing:
|
|
139
|
+
- **`available is False` must mean "the probe positively found nothing newer"** — never "the probe
|
|
140
|
+
failed". Every failure path in an `_UPDATE_CHECKERS` function returns an *empty* status (plus a
|
|
141
|
+
`note` saying why), which classifies as `unknown`. The uv checker once ignored its exit code:
|
|
142
|
+
`uv tool list --outdated` exits 2 offline with empty stdout, which read as every tool being current.
|
|
143
|
+
The unit tests had only faked a *successful* probe; it took running the real binary with the network
|
|
144
|
+
blocked to find it. A new checker needs a test for its failure path, not just its happy one.
|
|
145
|
+
- **`unsupported` is decided from the install *type*** (`generic.supports_update_check`), not from an
|
|
146
|
+
empty `UpdateStatus` — a `bash` tool and a failed `npm` probe return the same empty status and need
|
|
147
|
+
different remedies. Neither may ever render as `current`; there is a test that breaks the renderer to
|
|
148
|
+
prove the test can fail.
|
|
149
|
+
- **Shared probes use `_once`, not `functools.lru_cache`.** `lru_cache` memoises *results*; concurrent
|
|
150
|
+
first callers on the 8-worker pool all miss and each run the subprocess (measured: 6 `uv tool list`
|
|
151
|
+
calls where 2 suffice). `_once` holds a lock while computing. The memo is process-wide, so nothing may
|
|
152
|
+
read it after an install/update and expect to see the change.
|
|
153
|
+
- **`note` is set only by a checker that actually knows why** — the command layer never invents one — and
|
|
154
|
+
is free text, so the renderer escapes it (Rich reads `[docs]` as markup).
|
|
155
|
+
- **Exit status is "did the lookup run", not the answer** (the same rule as `run_cmd`), and `--json`
|
|
156
|
+
writes only the array to stdout, even at `-vv`.
|
|
157
|
+
|
|
136
158
|
**Two ways a tool gets defined**: built-in (an entry added directly to `src/dev_setup/tools.yaml`,
|
|
137
159
|
`builtin=True`) or custom (created via the `devstuff add` wizard, `devstuff catalog import`,
|
|
138
160
|
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.11.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,64 @@ 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
|
+
|
|
317
375
|
### `configure`
|
|
318
376
|
|
|
319
377
|
Set up an installed tool through a guided wizard, previewing the result before anything is
|
|
@@ -287,6 +287,64 @@ 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
|
+
|
|
290
348
|
### `configure`
|
|
291
349
|
|
|
292
350
|
Set up an installed tool through a guided wizard, previewing the result before anything is
|
|
@@ -0,0 +1,177 @@
|
|
|
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
|
+
A profile is a YAML file: catalog keys, optional pinned versions, optional configurator output.
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
version: 1
|
|
71
|
+
tools:
|
|
72
|
+
uv: {}
|
|
73
|
+
lazygit: { version: 0.45.0 }
|
|
74
|
+
starship: {}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Design commitments (to be written up in the spec)**
|
|
78
|
+
- **A snapshot is measured, not remembered.** It is built by probing `is_installed()` and
|
|
79
|
+
`get_version()` now. There is no separate "installed state" file to drift out of sync — the
|
|
80
|
+
same reason `doctor` and every configurator measure the real binary.
|
|
81
|
+
- **Reuse `catalog.py`'s validation style**: unknown fields and unknown keys fail loudly at load
|
|
82
|
+
time, consistent with "invalid catalogs fail loudly".
|
|
83
|
+
- **`diff` reports four states**: missing, extra, version drift, and *unverifiable* (a pinned
|
|
84
|
+
`script` tool whose version cannot be probed). The fourth state is the M1 lesson again.
|
|
85
|
+
- A profile references catalog keys only. It never embeds install scripts, so a profile file
|
|
86
|
+
cannot become a way to smuggle arbitrary commands past the catalog's validation.
|
|
87
|
+
|
|
88
|
+
**Done when**
|
|
89
|
+
- [ ] `profile snapshot` writes a valid profile; `profile diff` of a fresh snapshot against the
|
|
90
|
+
same machine reports no differences (round-trip test).
|
|
91
|
+
- [ ] Keys unknown to the effective catalog are reported, not silently dropped.
|
|
92
|
+
- [ ] Spec records the rejected alternative of extending `catalog export` instead, with reasons.
|
|
93
|
+
|
|
94
|
+
## M3 — `devstuff profile apply` and bundled bundles
|
|
95
|
+
|
|
96
|
+
Turn a profile into an install plan and run it.
|
|
97
|
+
|
|
98
|
+
- **Ordering** comes from the existing `requires` graph (including auto-inferred edges such as
|
|
99
|
+
`npm` → `nvm`). Do not write a second dependency resolver; if the existing one is not exposed in
|
|
100
|
+
a reusable form, factor it out first.
|
|
101
|
+
- **Plan before action**: reuse the `_plan.py` preview and the task-view progress bar that
|
|
102
|
+
`install`/`update` use, so `apply` shows what it will do and asks.
|
|
103
|
+
- **Failure policy** needs a decision in the spec: continue past a failed tool and summarise, or
|
|
104
|
+
stop. Recommendation: continue, skip anything whose `requires` failed, and report at the end —
|
|
105
|
+
a 40-tool apply that dies on tool 3 is worse than one that finishes 39.
|
|
106
|
+
- **Pins on `script`/`bash` tools** can only be honoured by a full reinstall. `apply` should say so
|
|
107
|
+
and confirm, matching `update`'s existing behaviour for those types.
|
|
108
|
+
- **Bundled bundles** (`@backend`, `@devops`, …) are profile files shipped in the package. They are
|
|
109
|
+
data, so they get a validation test and a CI check that every key they name exists in the
|
|
110
|
+
bundled catalog — the same two-direction enforcement as the CI-matrix test.
|
|
111
|
+
- **Configurator state**: restoring starship/lazygit/bat configuration is the differentiator over
|
|
112
|
+
a dotfiles repo, but several configurators do not round-trip (pre-commit and commitizen
|
|
113
|
+
explicitly do not). Scope M3 to tools only and treat configurator capture as a separate,
|
|
114
|
+
later decision recorded in the spec's open questions.
|
|
115
|
+
|
|
116
|
+
**Done when**
|
|
117
|
+
- [ ] `apply` on an empty container (the existing Docker integration harness) reproduces a
|
|
118
|
+
snapshot taken elsewhere.
|
|
119
|
+
- [ ] A failing tool does not abort the run; dependents are skipped with a stated reason.
|
|
120
|
+
- [ ] Every bundled bundle passes the key-exists test.
|
|
121
|
+
|
|
122
|
+
## M4 — Agent tools for `doctor` and `outdated`
|
|
123
|
+
|
|
124
|
+
Expose both as agent tools so the local model can answer "why is my nvm broken?" by running the
|
|
125
|
+
checks. Per `CLAUDE.md` this is mostly a YAML edit (`impl: catalog` / `impl: primitive` in
|
|
126
|
+
`agent_tools.yaml`); `agent_tools.schema.json` must be updated in the same change if any field is
|
|
127
|
+
added.
|
|
128
|
+
|
|
129
|
+
- `outdated` is read-only and safe to expose unconditionally.
|
|
130
|
+
- `doctor --fix` mutates the machine, so the agent gets the **check-only** form. A model
|
|
131
|
+
deciding to apply fixes is a separate question for the spec, not a default.
|
|
132
|
+
|
|
133
|
+
## M5 — Shell completion
|
|
134
|
+
|
|
135
|
+
`devstuff completion bash|zsh|fish`, built on Click's native completion support.
|
|
136
|
+
|
|
137
|
+
- The value is **dynamic completion of catalog keys** for `install`, `remove`, `update` and
|
|
138
|
+
`configure`, which means completing from the *effective* catalog (bundled + user), not a
|
|
139
|
+
generated static list.
|
|
140
|
+
- Completion runs on every `<TAB>`: it must not shell out to probes. Keys only, no
|
|
141
|
+
install-state lookups.
|
|
142
|
+
- Document the one-line install in README.md alongside the existing shell-integration notes.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Unscheduled candidates
|
|
147
|
+
|
|
148
|
+
**git / tmux configurator.** Same shape as the seven existing wizards, and the same first step
|
|
149
|
+
applies: before writing anything, find what the tool's own validator does *not* check. For git
|
|
150
|
+
that means measuring which `git config` keys are silently accepted and ignored.
|
|
151
|
+
|
|
152
|
+
**`devstuff sandbox <tool>`.** Try an install in a throwaway container before it touches the
|
|
153
|
+
host, reusing the Docker integration-test machinery. Not scheduled because it depends on Docker
|
|
154
|
+
being present, which the tool cannot assume, and because it overlaps `-vv` plan previews for the
|
|
155
|
+
"what will this do?" question.
|
|
156
|
+
|
|
157
|
+
## Non-goals
|
|
158
|
+
|
|
159
|
+
- **Not a configuration-management system.** `profile` converges a *developer machine* onto a
|
|
160
|
+
list of catalog tools. It is not Ansible and will not grow conditionals, templating, or
|
|
161
|
+
inventory.
|
|
162
|
+
- **No remote profile registry or sync service** in this roadmap. Profiles are files; sharing
|
|
163
|
+
them is the user's git repo.
|
|
164
|
+
- **No new install `type`s.** Nothing here adds a mechanism to `GenericTool`; every milestone
|
|
165
|
+
composes what exists.
|
|
166
|
+
- **No runtime dependencies.** Same rule the agent follows: devstuff is globally installed, and
|
|
167
|
+
every dependency is paid for by users who never run the new command.
|
|
168
|
+
|
|
169
|
+
## Risks
|
|
170
|
+
|
|
171
|
+
| Risk | Affects | Mitigation |
|
|
172
|
+
|------|---------|------------|
|
|
173
|
+
| 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 |
|
|
174
|
+
| `script`/`bash` tools dominate the catalog and are unverifiable | M1–M3 | Make "unknown" a first-class state everywhere rather than an edge case |
|
|
175
|
+
| `apply` partially succeeds and leaves a half-built machine | M3 | Plan preview, continue-and-summarise policy, dependents skipped with reasons |
|
|
176
|
+
| Profile format hardens before `apply` has been tried | M2 | Ship `snapshot`/`diff` as `version: 1` but mark the format provisional until M3 lands |
|
|
177
|
+
| Scope creep into configurator capture | M3 | Explicit non-goal above; revisit as its own spec |
|
|
@@ -47,3 +47,4 @@ 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) |
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# Development plan: `devstuff outdated`
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-10-10
|
|
4
|
+
**Status:** Complete (v1), 2026-10-10
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Milestones
|
|
9
|
+
|
|
10
|
+
| # | Milestone | Satisfies | State |
|
|
11
|
+
|---|-----------|-----------|-------|
|
|
12
|
+
| 1 | Fix redundant `uv` probes: lock/prime `_uv_outdated_map`, parse `uv tool list` once for all lookups | FR-19, NFR-2 | **Done** 2026-10-10 |
|
|
13
|
+
| 2 | Move the collector out of `update_cmd.py`; type it against `GenericTool`; drop the `type: ignore` | FR-15–17, SD-4 | **Done** 2026-10-10 |
|
|
14
|
+
| 3 | State classifier: `UpdateStatus` + `install_type` → one of five states | FR-5–8, SD-2/3 | **Done** 2026-10-10 |
|
|
15
|
+
| 4 | `commands/outdated_cmd.py`: table, footer, summary, flags, exit status; register in `cli._register_commands` | FR-1–4, 9–11, 13–14, 18 | **Done** 2026-10-10 |
|
|
16
|
+
| 5 | `--json` output and stdout-purity test at `-vv` | FR-12, NFR-1 | **Done** 2026-10-10 (landed with 4: `--json` is part of the command's contract) |
|
|
17
|
+
| 6 | `UpdateStatus.note`: add the field; set it in the uv checker (F-2) and on the npm/apt/git network-failure paths; render and emit it | FR-23, F-7 | **Done** 2026-10-10 |
|
|
18
|
+
| 7 | README (command reference), CLAUDE.md (architecture line), roadmap + specs index | — | **Done** 2026-10-10 |
|
|
19
|
+
|
|
20
|
+
Milestones 1 and 2 land first and **before any new command exists**: both are changes to
|
|
21
|
+
existing behaviour, so each is verifiable against `update`'s current output. Doing them first
|
|
22
|
+
means the new command is built on a corrected, shared base rather than copying the race.
|
|
23
|
+
|
|
24
|
+
M3 is deliberately a pure function with no I/O, so the five-state rule — the point of the
|
|
25
|
+
spec — is testable without a terminal or a network.
|
|
26
|
+
|
|
27
|
+
## Testing strategy
|
|
28
|
+
|
|
29
|
+
New file `tests/test_outdated.py`. Unit-only; no network and no real installs, so it stays in
|
|
30
|
+
the default ~0.3 s suite.
|
|
31
|
+
|
|
32
|
+
- **Classifier, exhaustively.** Parametrized over `(install_type, UpdateStatus)` → state: each
|
|
33
|
+
of the five states, plus the two that matter most — a `bash` tool and a failed `npm` probe both
|
|
34
|
+
have an empty status and must classify as `unsupported` and `unknown` respectively (SD-2).
|
|
35
|
+
- **Rendering distinguishes states** (FR-7/FR-20): capture the Rich output and assert the
|
|
36
|
+
`unknown` and `unsupported` renderings contain neither the `current` glyph nor its wording.
|
|
37
|
+
This is the test that fails if someone "tidies" the states back together.
|
|
38
|
+
- **`note` is optional and never invented** (FR-23): a checker that sets nothing yields an empty
|
|
39
|
+
note and unchanged output; the uv checker sets one for a tool on `PATH` but absent from
|
|
40
|
+
`uv tool list` (the `commitizen` case, F-2).
|
|
41
|
+
- **Counts sum to tools checked** (FR-11), including with `--updates-only` hiding rows.
|
|
42
|
+
- **Read-only** (FR-3): patch `install`/`remove`/`update` on the registry's tools to raise; the
|
|
43
|
+
command must complete.
|
|
44
|
+
- **Exit status** (FR-14): exit 0 with outdated tools present; exit 1 for an unknown key.
|
|
45
|
+
- **`--json` purity** (FR-22/NFR-1): run at `-vv` with `capfd`, assert stdout parses as a JSON
|
|
46
|
+
array and every record has exactly the six fields (`key`, `type`, `state`, `installed`, `latest`, `note`).
|
|
47
|
+
- **Collector parity** (FR-21): with probes stubbed, the shared collector returns what the
|
|
48
|
+
pre-move `_collect_update_candidates` did, and `update`'s picker is unchanged.
|
|
49
|
+
- **Probe count** (FR-19): stub `generic._probe` with a counter, run the collector over N≥3
|
|
50
|
+
fake uv tools concurrently, and assert `uv tool list` and `uv tool list --outdated` each ran
|
|
51
|
+
once (`tests/test_uv_probes.py`). This test must fail on the current code — it is the regression test for finding F-1,
|
|
52
|
+
and a version that passes before the fix proves nothing.
|
|
53
|
+
|
|
54
|
+
**Live verification** (not in the suite; recorded in the spec when done, like every configurator):
|
|
55
|
+
run against this machine with a mix of npm/uvx/bash tools, once online and once with the network
|
|
56
|
+
blocked, confirming offline turns `outdated` into `unknown` and never into `current`.
|
|
57
|
+
|
|
58
|
+
**Done 2026-10-10** (dead proxy + cold uv cache, then `UV_OFFLINE=1`): every checkable tool was `unknown` with a stated
|
|
59
|
+
reason; none read `current`. This caught F-7 — the uv probe ignored its exit code — which the unit tests had not,
|
|
60
|
+
because they only faked a *successful* probe.
|
|
61
|
+
|
|
62
|
+
## Risks
|
|
63
|
+
|
|
64
|
+
| Risk | Likelihood | Mitigation |
|
|
65
|
+
|------|-----------|------------|
|
|
66
|
+
| The command ships looking broken because two thirds of the catalog is `unsupported` | **High** — measured (F-5) | FR-10's footer states the count and names the tools; OQ-1 is the real fix and is the next spec, so v1's honesty is a stopgap with an owner |
|
|
67
|
+
| Moving the collector subtly changes `update`'s picker | Medium | M2 is a pure move with a parity test; do it as its own commit so a regression bisects to it |
|
|
68
|
+
| Fixing the uv race changes which tools read as current | Low | The race only duplicated work, never altered results; parity test covers it |
|
|
69
|
+
| `!=` comparison produces false `outdated` for prereleases / held packages (F-4) | Medium | Documented in the spec and README; not fixed in v1 (OQ-2) |
|
|
70
|
+
| Network-blocked environments make every checkable tool `unknown` | Medium | Intended — that is the correct answer. The summary line makes it obvious |
|
|
71
|
+
| A probe fails and reads as `current` (found live: F-7) | **Was real** | Fixed; each uv/npm/apt/git failure path now has a test, and the offline run is verified live |
|
|
72
|
+
| `-vv` probe logging from 8 threads interleaves on stderr | Low | stderr only, one line per call; if unreadable, serialise log writes in `verbose.py` rather than change the pool |
|
|
73
|
+
|
|
74
|
+
## Out of scope for this plan
|
|
75
|
+
|
|
76
|
+
OQ-1 (checkable `bash` tools) and OQ-2 (version ordering) were resolved as deferred follow-ups
|
|
77
|
+
(2026-10-10) and get their own spec directories; OQ-3 (`--exit-code`) waits for a concrete request. `profile` (M2/M3 of the roadmap) consumes this command's collector
|
|
78
|
+
and its five-state vocabulary, and should cite SD-2/SD-3 rather than re-deriving them.
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# Specification: `devstuff outdated`
|
|
2
|
+
|
|
3
|
+
**Date:** 2026-10-10
|
|
4
|
+
**Status:** Implemented (v1), 2026-10-10 — see development-plan.md
|
|
5
|
+
**Authors:** Sawyer + Claude
|
|
6
|
+
**Roadmap:** [M1](../../ROADMAP.md) — the foundation `profile diff` (M2) is built on.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Problem Statement & Goals
|
|
11
|
+
|
|
12
|
+
`devstuff update` is the only place that knows whether an installed tool is behind, and it
|
|
13
|
+
only tells you as a side effect of opening an interactive picker that ends in a mutation:
|
|
14
|
+
|
|
15
|
+
- **There is no read-only answer.** You cannot ask "what is behind?" from a script, a cron job
|
|
16
|
+
or a CI step. `update` with no arguments opens a questionary checkbox, which hangs in a
|
|
17
|
+
non-TTY shell (see CLAUDE.md, "Commands").
|
|
18
|
+
- **The gathered answer is private.** `_collect_update_candidates()` in `commands/update_cmd.py`
|
|
19
|
+
already probes every installed tool concurrently and returns `(tool, UpdateStatus)` pairs, but
|
|
20
|
+
nothing outside that one file can call it.
|
|
21
|
+
- **"Unknown" is the common case, and the picker undersells it.** On the bundled catalog 23 of
|
|
22
|
+
35 tools (66%) are `bash` installers, which have no update checker at all. The picker labels
|
|
23
|
+
them `unknown — reinstall to check`, which reads as a hint rather than as "devstuff cannot
|
|
24
|
+
see this tool". A report that is mostly blind needs to say so plainly.
|
|
25
|
+
|
|
26
|
+
**Goal:** a read-only, non-interactive command that reports installed vs. latest per tool,
|
|
27
|
+
shares one probing path with `update`, and never presents "could not check" as "up to date".
|
|
28
|
+
|
|
29
|
+
**Non-goals** (each one is a decision, with reasons in `stack-decisions.md`):
|
|
30
|
+
- No mutation of any kind. `outdated` never offers to update; that is `devstuff update`.
|
|
31
|
+
- No new update checkers for `script`/`bash` tools in v1 — see OQ-1.
|
|
32
|
+
- No version *ordering*. v1 reports "different from the latest", not "older than the latest" — see OQ-2.
|
|
33
|
+
- No persistent cache and no background refresh.
|
|
34
|
+
- No uninstalled tools, no checking for new *catalog* entries.
|
|
35
|
+
- No notification, cron or shell-prompt integration; `--json` is the integration surface.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 2. Functional Requirements
|
|
40
|
+
|
|
41
|
+
### Command surface
|
|
42
|
+
|
|
43
|
+
- **FR-1** `devstuff outdated [KEY…]`. With no keys, every **installed** tool is checked. With
|
|
44
|
+
keys, exactly those tools are checked. An unknown key prints an error and exits 1, matching
|
|
45
|
+
`update`. A known key that is not installed yields a `not-installed` row (FR-5), not an error.
|
|
46
|
+
- **FR-2** Never prompts, never opens a questionary widget, and works with stdin and stdout
|
|
47
|
+
redirected.
|
|
48
|
+
- **FR-3** Read-only. It must not call `install`, `remove`, `update`, `configure`, or write to
|
|
49
|
+
the catalog or any config directory. (Test: patch each to raise.)
|
|
50
|
+
- **FR-4** Two display flags: `--updates-only` hides every row that is not `outdated`;
|
|
51
|
+
`--all` shows the `unsupported` rows that are otherwise collapsed (FR-10).
|
|
52
|
+
|
|
53
|
+
### The five states
|
|
54
|
+
|
|
55
|
+
- **FR-5** Every checked tool lands in exactly one state:
|
|
56
|
+
|
|
57
|
+
| State | Meaning | Source |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| `outdated` | a different version is available | `UpdateStatus.available is True` |
|
|
60
|
+
| `current` | the checker found nothing newer | `available is False` |
|
|
61
|
+
| `unknown` | a checker exists but could not answer | `available is None`, type has a checker |
|
|
62
|
+
| `unsupported` | no checker exists for this install type | type absent from `_UPDATE_CHECKERS` |
|
|
63
|
+
| `not-installed` | named explicitly but not installed | `is_installed()` is False |
|
|
64
|
+
|
|
65
|
+
- **FR-6** `unsupported` is decided from the tool's `install_type` against the checker table,
|
|
66
|
+
**not** inferred from an empty `UpdateStatus`. An empty status is what a *failed* probe also
|
|
67
|
+
returns, so inferring would merge "cannot be checked" with "the check failed" — two states
|
|
68
|
+
whose remedies differ (nothing to do vs. check your network).
|
|
69
|
+
- **FR-7** `unknown` and `unsupported` are never rendered with the same glyph, colour or wording
|
|
70
|
+
as `current`, and are never counted in a "current" total. This is the requirement the whole
|
|
71
|
+
command exists to protect; it has a test per state (FR-20).
|
|
72
|
+
- **FR-8** `current` means "the checker found no newer version", which for `uvx` and `pip`
|
|
73
|
+
tools does not include the latest version number (see §4, finding F-3). The `Latest` column is
|
|
74
|
+
blank for those rows rather than echoing `Installed`.
|
|
75
|
+
|
|
76
|
+
### Output
|
|
77
|
+
|
|
78
|
+
- **FR-9** Table columns: `Package`, `Type`, `Installed`, `Latest`, `Status`. Rows sort
|
|
79
|
+
`outdated`, `unknown`, `current`, `not-installed`; alphabetical by key within a state.
|
|
80
|
+
- **FR-10** `unsupported` rows are collapsed by default into one dim footer line
|
|
81
|
+
(`23 tools can't be checked (bash installers): bat, gh, …`) and shown as rows with `--all`.
|
|
82
|
+
They are the majority on the bundled catalog and would otherwise bury the answer.
|
|
83
|
+
- **FR-11** A one-line summary closes the output, with all five counts that are non-zero:
|
|
84
|
+
`3 outdated · 6 current · 2 unknown · 23 unsupported`. Counts always sum to the number of
|
|
85
|
+
tools checked.
|
|
86
|
+
- **FR-12** `--json` writes a single JSON array to stdout and nothing else:
|
|
87
|
+
`{"key", "type", "state", "installed", "latest", "note"}`, with `null` for absent versions and
|
|
88
|
+
an empty string for an absent note (FR-23). `state`
|
|
89
|
+
uses the five names in FR-5. Everything else (banner, spinner, hints) is suppressed or goes
|
|
90
|
+
to stderr — see NFR-1.
|
|
91
|
+
- **FR-13** The banner and spinner are shown only when stdout is a TTY and `--json` is absent.
|
|
92
|
+
|
|
93
|
+
### Exit status
|
|
94
|
+
|
|
95
|
+
- **FR-14** Exit 0 whenever the lookup was performed, **regardless of what it found**. Non-zero
|
|
96
|
+
is reserved for "could not perform the lookup" (unknown key, catalog failure). This is the
|
|
97
|
+
`run_cmd` rule from CLAUDE.md: a correct answer must not arrive under a red failure banner.
|
|
98
|
+
|
|
99
|
+
### Probing
|
|
100
|
+
|
|
101
|
+
- **FR-15** Version information comes from `GenericTool.check_for_update()` and nothing else.
|
|
102
|
+
The command layer adds no subprocess call of its own; anything it did need would go through
|
|
103
|
+
`generic._probe`, per the verbosity rules.
|
|
104
|
+
- **FR-16** Probes run concurrently on a bounded pool (8 workers, as `list` and `update` use).
|
|
105
|
+
One tool raising or timing out yields an `unknown` row for that tool and never aborts the run.
|
|
106
|
+
- **FR-17** The gathering code is shared. `update`'s interactive picker and `outdated` call
|
|
107
|
+
**one** function that lives outside `update_cmd.py`; `update`'s picker output is unchanged by
|
|
108
|
+
the move (regression test, FR-21).
|
|
109
|
+
- **FR-18** Progress: a spinner while probing on a TTY, replaced by a plain logged line at `-v`
|
|
110
|
+
(`verbose.step`), as for every other command.
|
|
111
|
+
- **FR-19** Redundant probes are removed: one run invokes `uv tool list` at most once and
|
|
112
|
+
`uv tool list --outdated` at most once, however many `uv` tools are installed (see NFR-2).
|
|
113
|
+
|
|
114
|
+
- **FR-23** `UpdateStatus` gains one optional field, `note: str = ""`, a short human reason
|
|
115
|
+
(`"not installed via uv tool"`, `"registry unreachable"`). Checkers set it only where they
|
|
116
|
+
actually know why they could not answer; it is never invented by the command layer. It is
|
|
117
|
+
shown dimmed after the status text and carried in `--json`. A checker that does not set it
|
|
118
|
+
behaves exactly as before — the field defaults to empty, so no existing call site changes.
|
|
119
|
+
(Resolves OQ-4; motivated by finding F-2.) Implemented 2026-10-10 for uv (not managed by `uv tool`; probe failed; `UV_OFFLINE`), npm (registry unreachable), apt (no candidate; `apt-cache policy` failed) and git (no clone; remote unreachable). Rendered on a dim second line of the Status cell, markup-escaped, because a note is free text from a checker.
|
|
120
|
+
|
|
121
|
+
### Tests
|
|
122
|
+
|
|
123
|
+
- **FR-20** One test per state asserting its rendering differs from `current`'s, including a
|
|
124
|
+
real `bash`-type tool landing in `unsupported`.
|
|
125
|
+
- **FR-21** The shared collector returns what `update`'s picker consumed before the move.
|
|
126
|
+
- **FR-22** `outdated --json` at `-vv` parses as JSON (stdout purity, NFR-1).
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 3. Non-Functional Requirements
|
|
131
|
+
|
|
132
|
+
- **NFR-1** **stdout carries data only.** Under `--json`, even at `-vv`, stdout is exactly one
|
|
133
|
+
JSON document. Same invariant, same reason, as `verbose-mode` SD-3: a consumer is parsing it.
|
|
134
|
+
- **NFR-2** **Probe cost is bounded by the number of distinct questions, not tools.** Measured
|
|
135
|
+
baseline in §4 (F-1): six `uv tool list` calls for three installed uv tools, where two
|
|
136
|
+
suffice. After this work, the count is independent of how many uv tools are installed.
|
|
137
|
+
- **NFR-3** **Latency.** The measured baseline is 2.6 s for 13 installed tools on a warm
|
|
138
|
+
network. No target is set beyond "not regress"; per-probe timeouts (10–20 s) bound the worst
|
|
139
|
+
case, and there is deliberately no global timeout in v1 (OQ-5).
|
|
140
|
+
- **NFR-4** **No new runtime dependency.** Rich is already present; JSON is stdlib.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 4. Findings from measurement
|
|
145
|
+
|
|
146
|
+
Per the project convention (*measure the tool, don't recall it*), the existing probe path was
|
|
147
|
+
run before this spec was written. Date: 2026-10-10; 13 installed tools.
|
|
148
|
+
|
|
149
|
+
| # | Finding | Consequence |
|
|
150
|
+
|---|---------|-------------|
|
|
151
|
+
| F-1 | `uv tool list` ran **6** times for 3 installed uv tools; **2** are needed (one plain, one `--outdated`), however many tools there are. `_uv_outdated_map` is `@lru_cache(maxsize=1)`, but `lru_cache` does not stop *concurrent* first callers from each computing the value, so all three worker threads ran `uv tool list --outdated`. `_uv_tool_current_version` has no cache at all, so it runs once per tool. | FR-19 / NFR-2. **Fixed 2026-10-10 (milestone 1): 6 → 2 live, results unchanged.** The cache needs a lock (or the collector must prime it before fanning out) and the per-tool version lookup must read from one shared `uv tool list` parse. |
|
|
152
|
+
| F-2 | `commitizen` is reported installed (`cz` on `PATH`) but is not a `uv tool` — here it comes from the project venv under `uv run`. The uvx checker asks `uv tool list`, finds nothing, and returns an empty status: `unknown`. | `is_installed()` ("is the command present?") and the update checker ("does this mechanism manage it?") ask different questions and can disagree. `unknown` is the right answer; OQ-4 asks whether it should say *why*. |
|
|
153
|
+
| F-3 | For `uvx` tools the checker only knows the *absence* of a tool from `uv tool list --outdated`. `hey-dave` and `ipython` came back `available=False` with `latest=''`. | `current` for uvx is "not listed as outdated", so `Latest` is blank (FR-8). **Correction (2026-10-10):** an earlier draft of this row also claimed `uv … --outdated` ignores prereleases. That was written from memory and is false: with `hey-dave 0.1.0a1` installed in an isolated tool dir, uv listed `[latest: 0.2.0a1]`, so it follows prereleases when the installed version is itself one. |
|
|
154
|
+
| F-4 | `npm` and `apt` checkers decide `available` by `current != latest` — inequality, not ordering. | A locally newer version (a prerelease, a held or PPA package) reads as `outdated`. OQ-2. |
|
|
155
|
+
| F-5 | 23 of 35 bundled tools are `bash`; none has a checker. | The command is blind to two thirds of the catalog. FR-7 and FR-10 exist because of this; OQ-1 is the real fix. |
|
|
156
|
+
| F-6 | `check_for_update` exists on `GenericTool` but not on the `Tool` ABC; `update_cmd` suppresses the type error with `# type: ignore[attr-defined]`. | The shared collector either takes `GenericTool` or the ABC gains a default. Decided in SD-4. |
|
|
157
|
+
| F-7 | **A failed uv probe read as "current".** Measured 2026-10-10: with no network, `uv tool list --outdated` exits **2** with an error and empty stdout; `_uv_outdated_map` ignored the exit code, so every uv tool came back `available=False`. With `UV_OFFLINE` set and a cold cache uv exits **0** and prints nothing at all — indistinguishable from a real "all current". | A bug in already-shipped `update` code, and exactly the failure FR-7 forbids. Fixed in milestone 6: a non-zero exit is unknown ("couldn't reach the package index"), and `UV_OFFLINE` — the only signal there is — is checked before asking. `uv`'s config-file `offline = true` cannot be detected; documented, not fixed. |
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## 5. Open questions (all resolved)
|
|
162
|
+
|
|
163
|
+
| # | Question | Recommendation | Status |
|
|
164
|
+
|---|----------|----------------|--------|
|
|
165
|
+
| OQ-1 | Should `bash`/`script` tools be checkable — e.g. an optional catalog field naming where the latest version lives (`latest_from: github:owner/repo`)? | **Yes, but as its own spec after v1 ships.** It is a schema change (`SUPPORTED_FIELDS`, validation, README, schema docs) and decides how `profile diff` sees two thirds of the catalog, so it deserves its own design. v1 ships honest unknowns. | **Resolved 2026-10-10: yes, as its own spec after v1 ships.** v1 keeps honest `unsupported` rows. |
|
|
166
|
+
| OQ-2 | Compare versions by ordering instead of inequality? | Not in v1. Version grammars differ per ecosystem (PEP 440, semver, dpkg); a half-right comparator is worse than a documented `!=`. Revisit with OQ-1. | **Resolved 2026-10-10: not in v1.** Inequality stays, documented (F-4); revisit alongside OQ-1. |
|
|
167
|
+
| OQ-3 | An opt-in `--exit-code` (exit 1 when anything is outdated), `git diff --exit-code` style, for CI? | Probably yes, as a flag that is off by default so FR-14 stays true. Wait for a concrete request. | **Resolved 2026-10-10: deferred.** Not in v1; FR-14 stays true. Add as an opt-in flag on a concrete request. |
|
|
168
|
+
| OQ-4 | Should `UpdateStatus` carry a short `note` (`"not installed via uv tool"`, `"registry unreachable"`) so `unknown` can say why? | Yes — one optional string, default empty, populated only where a checker knows. Without it F-2 is indistinguishable from an offline failure. | **Resolved 2026-10-10: yes.** Specified as FR-23. |
|
|
169
|
+
| OQ-5 | A global timeout on the whole run? | No for v1: per-probe timeouts already bound it, and a global one would turn a slow-but-correct tool into `unknown`. | **Resolved 2026-10-10: no global timeout in v1.** |
|