devstuff 2.2.1__tar.gz → 2.4.0__tar.gz

devstuff-2.4.0/.github/workflows/bump.yml

@@ -0,0 +1,180 @@
+name: Bump version
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - master
+
+# Serialize bump runs against master regardless of which PR triggered them.
+concurrency:
+  group: bump-master
+  cancel-in-progress: false
+
+jobs:
+  bump:
+    name: cz bump
+    runs-on: ubuntu-latest
+    # Only run for PRs that were actually merged, not closed unmerged.
+    # A raw `git push` — which is how this job publishes its own commit —
+    # never fires pull_request events, so there's no infinite-loop risk
+    # from this job triggering itself (unlike the old push-to-master
+    # trigger, which needed an explicit "bump:" message guard for that).
+    if: github.event.pull_request.merged == true
+    permissions:
+      contents: write
+    env:
+      # secrets can't be referenced directly in step `if:` conditions, so
+      # surface presence via an env var instead.
+      HAS_GH_PAT: ${{ secrets.GH_PAT != '' }}
+
+    steps:
+      - name: Require GH_PAT
+        # GH_PAT (a Personal Access Token with repo write scope) is required
+        # so that the tag push re-triggers publish.yml — GitHub Actions does
+        # not re-process events from pushes made with GITHUB_TOKEN. Fail loudly
+        # instead of silently pushing a tag that will never publish.
+        if: env.HAS_GH_PAT != 'true'
+        run: |
+          echo "::error::GH_PAT secret is not set. It is required so the tag push triggers publish.yml (GITHUB_TOKEN pushes are not re-processed by Actions)."
+          exit 1
+
+      - uses: actions/checkout@v4
+        with:
+          ref: master  # the merge already happened server-side by the time this runs
+          fetch-depth: 0  # commitizen needs full history to determine bump type
+          token: ${{ secrets.GH_PAT }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Run cz bump
+        id: bump
+        run: |
+          if uv run --group dev cz bump --yes; then
+            echo "bumped=true" >> "$GITHUB_OUTPUT"
+          else
+            EXIT=$?
+            if [ "$EXIT" -eq 21 ]; then
+              echo "No conventional commits found since last tag — nothing to bump."
+              echo "bumped=false" >> "$GITHUB_OUTPUT"
+            else
+              exit "$EXIT"
+            fi
+          fi
+
+      # Build-only PRs: `cz bump` exits 21 because `build` is deliberately not
+      # in bump_map (we don't want it consuming a PATCH slot from the main
+      # release line). Instead, ship a PEP 440 post-release — vX.Y.Z.postN —
+      # which is publishable to PyPI, sorts after vX.Y.Z but before the next
+      # vX.(Y+1).0, and is still recognised by `cz bump` as the current
+      # version tag (tag_format is `v$version` and `X.Y.Z.postN` is valid
+      # PEP 440), so the next regular bump stays coherent. A PR mixing `build`
+      # with feat/fix/etc. is handled by the `cz bump` path above — the build
+      # commits just fold into that release's changelog — so this step only
+      # fires when there was nothing else to release.
+      - name: Build-patch post-release
+        id: buildpatch
+        if: steps.bump.outputs.bumped == 'false'
+        run: |
+          set -euo pipefail
+
+          last_tag="$(git describe --tags --abbrev=0)"
+          commits="$(git log "${last_tag}..HEAD" --pretty=format:%s)"
+
+          # No build commits -> genuinely nothing to release.
+          if ! printf '%s\n' "$commits" | grep -qE '^build(\(.+\))?!?:'; then
+            echo "No build commits since ${last_tag} — nothing to release."
+            echo "buildpatch=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Safety net: if a higher-precedence release type slipped through,
+          # bail rather than ship a competing post-release. (cz bump exiting 21
+          # already implies this, but guard against future bump_map changes.)
+          if printf '%s\n' "$commits" | grep -qE '^(feat|fix|refactor|perf|deps)(\(.+\))?!?:'; then
+            echo "Higher-precedence release commits present alongside build — deferring to the main release track."
+            echo "buildpatch=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Current version -> release segment (strip any existing post/dev).
+          current_version="$(grep -E '^version = ' pyproject.toml | head -1 | sed -E 's/^version = "(.*)"$/\1/')"
+          base="$(printf '%s' "$current_version" | sed -E 's/(\.post[0-9]+|\.dev[0-9]+).*$//')"
+
+          # Next post number for this base (vX.Y.Z.post1, .post2, ...).
+          prev_n="$(git tag --list "v${base}.post*" | sed -E 's/^v.*\.post([0-9]+)$/\1/' | sort -n | tail -1 || true)"
+          next_n=$(( ${prev_n:-0} + 1 ))
+          new_version="${base}.post${next_n}"
+          new_tag="v${new_version}"
+
+          echo "Bumping build patch: ${current_version} -> ${new_version} (${new_tag})"
+
+          # Bump version in pyproject.toml.
+          sed -i -E "s/^version = \".*\"/version = \"${new_version}\"/" pyproject.toml
+
+          # Prepend a Build section to the changelog (matches cz's heading style).
+          date="$(date +%Y-%m-%d)"
+          build_entries="$(
+            printf '%s\n' "$commits" | grep -E '^build(\(.+\))?!?:' | while IFS= read -r subject; do
+              msg="$(printf '%s' "$subject" | sed -E 's/^build(\([^)]+\))?(!)?: //')"
+              scope="$(printf '%s' "$subject" | sed -nE 's/^build\(([^)]+)\).*/\1/p')"
+              if [ -n "$scope" ]; then
+                printf -- '- **%s**: %s\n' "$scope" "$msg"
+              else
+                printf -- '- %s\n' "$msg"
+              fi
+            done
+          )"
+          {
+            printf '## %s (%s)\n\n### Build\n\n%s\n' "$new_tag" "$date" "$build_entries"
+            cat CHANGELOG.md
+          } > CHANGELOG.md.new
+          mv CHANGELOG.md.new CHANGELOG.md
+
+          # Sync the lockfile against the new version before committing so the
+          # tag points at a single self-contained commit (no amend/retag needed).
+          uv lock
+          git add pyproject.toml CHANGELOG.md uv.lock
+          git commit -m "bump: version ${current_version} → ${new_version} (build patch)"
+          git tag -a "$new_tag" -m "$new_tag" HEAD
+
+          git push --follow-tags
+          if ! git ls-remote --exit-code --tags origin "refs/tags/${new_tag}" >/dev/null; then
+            echo "::error::${new_tag} was not found on origin after push --follow-tags (publish.yml build_patch job will not trigger)."
+            exit 1
+          fi
+
+          echo "buildpatch=true" >> "$GITHUB_OUTPUT"
+          echo "new_tag=${new_tag}" >> "$GITHUB_OUTPUT"
+
+      - name: Sync lockfile
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          uv lock
+          git add uv.lock
+          if ! git diff --staged --quiet; then
+            # cz bump already tagged the pre-lock commit; amending moves HEAD
+            # to a new SHA, so the tag must be recreated to point at it.
+            # Must stay annotated (-a) — `git push --follow-tags` only
+            # pushes annotated tags, so a lightweight retag here would
+            # silently never reach the remote.
+            tag="$(git describe --tags --exact-match HEAD)"
+            git commit --amend --no-edit
+            git tag -f -a "$tag" -m "$tag" HEAD
+          fi
+
+      - name: Push commit and tag
+        if: steps.bump.outputs.bumped == 'true'
+        run: |
+          git push --follow-tags
+          tag="$(git describe --tags --exact-match HEAD)"
+          if ! git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null; then
+            echo "::error::${tag} was not found on origin after push --follow-tags (publish.yml will not trigger)."
+            exit 1
+          fi

devstuff-2.4.0/.github/workflows/publish.yml

@@ -0,0 +1,96 @@
+name: Publish to PyPI
+
+# A `v*` tag push triggers this workflow. Two release tracks share that
+# prefix, so they're routed by job-level `if` conditions on the tag name
+# rather than by disjoint trigger globs (GitHub Actions globs can't negate,
+# so `v*` would match both and a glob-only split would double-publish):
+#
+#   - Regular releases    vX.Y.Z          -> build / publish
+#   - Build-patch post    vX.Y.Z.postN    -> build_patch / publish_build_patch
+#
+# The post-release track exists so a PR that contains only `build`-type
+# commits still ships a publishable, PEP 440-distinct version. bump.yml
+# decides which tag to create; this file only reacts to whichever one lands.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    if: ${{ !contains(github.ref, '.post') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and source distribution
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    if: ${{ !contains(github.ref, '.post') }}
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/devstuff
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  build_patch:
+    name: Build build-patch distribution
+    if: ${{ contains(github.ref, '.post') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and source distribution
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-build-patch
+          path: dist/
+
+  publish_build_patch:
+    name: Publish build-patch to PyPI
+    if: ${{ contains(github.ref, '.post') }}
+    needs: build_patch
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/devstuff
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-build-patch
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{devstuff-2.2.1 → devstuff-2.4.0}/.github/workflows/test-installs.yml

@@ -51,27 +51,32 @@ jobs:
       fail-fast: false  # let all tools run even when some fail
       matrix:
         tool:
+          - ansible       # uvx tool, requires uv
+          - ansible-vault # shares ansible's tool environment
           - aws
+          - bat
           - commitizen  # uvx tool, requires uv
-          - eza
           - gh
           - git-lfs
           - go
+          - homebrew    # slow: builds from source
           - htop
           - ipython     # uvx tool, requires uv
           - java
           - lazygit
+          - llm-checker # npm tool, installs nvm first via `requires`
+          - lmstudio
           - mkcert
           - nerd-font
           - nvm
           - php
           - pi          # installs nvm first via its declared `requires`
           - pre-commit  # uvx tool, requires uv
+          - python      # uv-managed CPython, requires uv
           - ruby        # compiles from source — this job takes ~15 minutes
           - saml2aws
           - starship
           - uv
-          - whichllm    # uvx tool, requires uv
           - yq
 
     steps:

{devstuff-2.2.1 → devstuff-2.4.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v2.4.0 (2026-08-20)
+
+### Features
+
+- **ci**: publish build-patch updates as PEP 440 post-releases
+
+## v2.3.0 (2026-08-13)
+
+### Features
+
+- make uv the install backbone, and fix ansible (#42)
+
 ## v2.2.1 (2026-08-05)
 
 ### Bug Fixes

{devstuff-2.2.1 → devstuff-2.4.0}/CLAUDE.md

@@ -83,6 +83,36 @@ pattern for upgrading an already-installed tool (latest or a pinned version); fo
 `bash` types "update" is a full reinstall, since there's no narrower mechanism, so the command
 layer confirms before re-running it.
 
+**uv is the backbone for Python-packaged tools** (spec in `docs/specs/uv-backbone/`). The
+`uvx`/`pip` types accept three optional fields beyond `pip_name` — `uv_with`,
+`uv_executables_from`, `uv_python` — assembled into argv by `_uv_install_flags` in `generic.py`
+and rejected by `validate_catalog()` on every other type. Three things about them are
+load-bearing:
+- **`uv tool install` only exposes console scripts of the *requested* package.** The `ansible`
+  distribution is a collections bundle declaring none of its own, so `pip_name: ansible` alone
+  installs one unusable `ansible-community` binary and reports success. `uv_executables_from:
+  [ansible-core]` is what produces the eleven real ones. Don't "simplify" it to
+  `pip_name: ansible-core` — that silently drops the bundled collections.
+- **`_update_uvx` never uses `uv tool upgrade`** — both paths are `uv tool install --force`
+  (`<pkg>==<ver>` pinned, `<pkg>@latest` otherwise). `uv tool upgrade` can't take a requirement
+  *and* is a no-op on an already-pinned tool, so the obvious pairing makes a pin a one-way door.
+  `--force` writes a fresh receipt, so the `uv_*` flags are re-passed on every update; that is
+  deliberate, since it also means a newly added `uv_with` applies on update, not just reinstall.
+  Anything printed telling a user how to escape a pin must be measured — two plausible remedies
+  ("re-run without `--version`", "run `devstuff install`") are both false, the second because
+  `install_cmd` returns early on `is_installed()`.
+- **The `python` entry provisions CPython through uv** (`uv python install --default`). Its
+  `check_cmd` is the delicate part: every host has a `python3`, so the check requires the default
+  shim to *resolve inside* `uv python dir`, uses `test -x` so a dangling shim from a removed
+  interpreter reads as absent, and guards `test -n "$d"` because an empty `uv python dir` would
+  collapse the `case` pattern to `/*` and match everything. Removal uninstalls only the version
+  the default shim points at — `uv python uninstall --all` would also destroy managed interpreters
+  that existing `uv tool` environments were built against.
+- **`_remove_uvx` honours an explicit `remove_script`**, mirroring `_remove_apt`. Two entries can
+  share one `pip_name` (`ansible-vault` shares `ansible`'s), and there `uv tool uninstall` would
+  tear out the shared environment. Extras need no field: `pip_name` reaches `subprocess` as one
+  argv element, never a shell, so `pip_name: "ansible-lint[lock]"` already works.
+
 **Verbosity** (`verbose.py`, spec in `docs/specs/verbose-mode/`): one process-wide level —
 `0` / `-v` / `-vv` — set by a Click callback and read by the subprocess helpers, never threaded
 through call signatures. Three things about it are load-bearing:
@@ -114,7 +144,15 @@ Add an entry to `src/dev_setup/tools.yaml` using an existing `type` (`npm`, `pip
 and per-type examples. Then:
 - Add the key to `.github/workflows/test-installs.yml`'s matrix (or to `_SKIP` in
   `tests/integration/test_tools.py` with a reason, if it can't run in CI).
-- Add it to the relevant table in README.md ("Built-in packages").
+  `test_ci_matrix_covers_every_builtin_tool` enforces this, in both directions — a stale matrix
+  entry names a pytest node id that matches nothing, so the job exits 4 and the workflow files a
+  GitHub issue every week. That went unnoticed for `eza`/`whichllm` from July until the test
+  existed, which is why it is a test and not a line in this file.
+- Add it to the relevant table in README.md ("Built-in packages"). Not enforced by a test —
+  the tables are prose-formatted and grouped loosely, so check by hand.
+- If it needs an executable that belongs to a *dependency* rather than the package itself, add
+  it to `_EXTRA_EXECUTABLES` in `tests/integration/test_tools.py`; `is_installed()` alone would
+  pass on a half-installed tool (see the `uvx` notes above).
 - No Python code changes needed — `GenericTool` already knows how to run every existing type.
 
 ## Adding a new tool *type* (e.g. a `composer`/PHP-package type)
@@ -194,6 +232,12 @@ through its exit code — only whether it ran. A "found nothing" answer should t
 say so, or the user gets a red "command failed" banner under a correct result; keep non-zero for
 "could not perform the lookup" (see `whats-on-port`'s comment on this).
 
+The way this rule actually gets broken is not a stray `exit 1` — it is **a bare `[ -n "$x" ] &&
+echo …` as the last statement of a branch**, which silently becomes the script's exit status when
+the test is false. `which-ansible` shipped that bug in its first draft: "no global ansible found",
+a correct answer, exited 1. Use a full `if`, and end such scripts with an explicit `exit 0`. It is
+only catchable by *running* every branch, not by reading them.
+
 Not yet built: an `add` wizard and `catalog import`/`export` for functions, analogous to the
 ones tools already have.
 

{devstuff-2.2.1 → devstuff-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: devstuff
-Version: 2.2.1
+Version: 2.4.0
 Summary: Development environment setup CLI for Linux
 Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
 Author-email: Sawyer <sawyerksu@gmail.com>
@@ -287,7 +287,7 @@ How "update" is performed depends on the package's install `type`:
 | Type | Latest | Specific version |
 |------|--------|-------------------|
 | `npm` | `npm install -g <pkg>@latest` | `npm install -g <pkg>@<version>` |
-| `pip` / `uvx` | `uv tool upgrade <pkg>` | `uv tool upgrade <pkg>==<version>` |
+| `pip` / `uvx` | `uv tool install --force <pkg>@latest` | `uv tool install --force <pkg>==<version>` |
 | `apt` | `apt-get install --only-upgrade` | `apt-get install <pkg>=<version>` (single package only) |
 | `git` | `git pull` (+ re-run `git_install_cmd`) | not supported — repos are cloned shallow (`--depth=1`) |
 | `script` / `bash` | Re-runs the install script | not supported — no version parameter to inject |
@@ -296,6 +296,17 @@ For `script`/`bash` packages, "update" is a full reinstall (the same script that
 `sudo` runs again), since there's no narrower update mechanism available. `devstuff update` asks
 for confirmation before doing this.
 
+`pip`/`uvx` packages go through `uv tool install` rather than `uv tool upgrade` in **both**
+columns. `uv tool upgrade` takes a tool *name*, so it cannot accept `<pkg>==<version>` at all, and
+it is a no-op on a tool that was previously pinned — using it for the "latest" column would mean
+pinning a package once left no way to move it again. `<pkg>@latest` re-resolves and clears any
+existing pin in one step. Pinning warns that the pin holds until the next `devstuff update`
+without `--version`.
+
+Any `uv_with` / `uv_executables_from` / `uv_python` fields on the package are re-applied on every
+update, so adding one to your catalog takes effect on the next update rather than needing a
+reinstall.
+
 ---
 
 ### `configure`
@@ -1132,6 +1143,7 @@ ones tools already have — for now, custom functions are hand-edited YAML at
 | `whats-on-port` | network | script | Find which process is listening on a port | `port`, `protocol` (optional: `tcp`/`udp`/`all`) |
 | `acc-check` | web-dev | script | Run the pi coding agent's `/dogfood` skill against a web URL | `url`, `instruction` (optional) |
 | `aws-saml-reauth` | web-dev | script | Reauthorize the AWS CLI via `saml2aws login --force` | `profile` (optional) |
+| `which-ansible` | validation | script | Show which ansible a directory will actually use — the project's uv venv or the global one | `path` (optional) |
 
 #### `whats-on-port`
 
@@ -1163,6 +1175,32 @@ so a missing `ss` names the apt package instead of surfacing "command not found"
 
 ---
 
+#### `which-ansible`
+
+```bash
+devstuff run which-ansible              # the current directory
+devstuff run which-ansible ~/infra      # somewhere else
+```
+
+Answers "if I type `ansible-playbook` here, which one runs?" — the project's own uv venv, or the
+global tool install. It walks up for a `pyproject.toml`/`uv.lock` the way uv does, then reports
+whichever applies:
+
+- a synced project venv, plus the `uv run ansible-playbook` invocation that uses it (and what a
+  bare `ansible-playbook` would pick instead);
+- ansible declared but not synced yet, pointing at `uv sync`;
+- no ansible in the project, or no project at all, naming the global one.
+
+Every one of those is a success and exits 0 — including "this project has no ansible", which is
+an answer, not a failure. Non-zero is reserved for not being able to look at all (no uv, or a
+path that isn't a directory).
+
+It exists because devstuff's ansible and a uv-managed ansible repo are now the *same shape* — both
+a uv-created venv — so the question stopped being "which tool is broken" and became "which
+environment am I in". See `docs/specs/uv-backbone/` for why the global one moved off apt.
+
+---
+
 ## Built-in packages
 
 ### Core
@@ -1182,13 +1220,18 @@ Optional utilities you may want on some machines.
 | Key | Name | Description | Help |
 |-----|------|-------------|------|
 | `ansible` | Ansible | Automation engine for configuration management and app deployment (`devstuff configure ansible`) | `ansible --help` |
+| `ansible-vault` | Ansible Vault | Encrypt and manage secrets within Ansible projects (bundled with Ansible) | `ansible-vault --help` |
 | `aws` | AWS CLI | Amazon Web Services CLI v2 | `aws help` |
 | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
 | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
-| `eza` | eza | Modern ls replacement with git status, icons, and tree view | `eza --help` |
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
+| `git-lfs` | Git LFS | Git extension for versioning large files | `git lfs --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |
+| `homebrew` | Homebrew | Package manager for Linux (and macOS) | `brew --help` |
+| `ipython` | IPython | Enhanced interactive Python shell with rich tab completion and magic commands | `ipython --help` |
 | `lazygit` | lazygit | TUI git client for fast, keyboard-driven git workflows (`devstuff configure lazygit`) | `lazygit --help` |
+| `llm-checker` | llm-checker | Check LLM compatibility with your hardware | `llm-checker --help` |
+| `lmstudio` | LM Studio | Run large language models locally with a GUI | `lms --help` |
 | `mkcert` | mkcert | Zero-config local HTTPS certificates | `mkcert --help` |
 | `nerd-font` | JetBrainsMono Nerd Font | Patched font supplying the icons Starship and other CLI tools draw | `fc-list \| grep -i "nerd font"` |
 | `ollama` | Ollama | Run large language models locally | `ollama --help` |
@@ -1205,6 +1248,7 @@ Optional utilities you may want on some machines.
 |-----|------|-------------|------|
 | `go` | Go | Go programming language toolchain | `go help` |
 | `java` | Java 21 (OpenJDK) | OpenJDK 21 LTS - JDK and JRE | `java --help` |
+| `python` | Python (uv-managed) | CPython provisioned by uv, installed as the default `python`/`python3` | `uv python list` |
 | `ruby` | Ruby (rbenv) | Ruby via rbenv version manager + ruby-build | `ruby --version` |
 
 ---
@@ -1247,7 +1291,10 @@ tools:
 | `docs_url` | no | URL opened by `devstuff docs <key>` |
 | `requires` | no | List of package keys that must already be installed |
 | `npm_name` | npm | npm package name |
-| `pip_name` | pip | PyPI package name |
+| `pip_name` | pip | PyPI package name. Extras work as-is: `pip_name: "ansible-lint[lock]"` |
+| `uv_with` | no (pip/uvx) | Extra packages installed into the tool's environment (`uv tool install --with`) |
+| `uv_executables_from` | no (pip/uvx) | Also expose console scripts from these packages (`--with-executables-from`). Needed when a package's entry points live in a dependency |
+| `uv_python` | no (pip/uvx) | Pin the tool environment's Python (`--python`), e.g. `"3.12"` |
 | `apt_packages` | apt | Space-separated list of apt packages |
 | `git_url` | git | Repository URL to clone |
 | `git_install_cmd` | git | Bash command run inside the cloned repo after clone |
@@ -1256,7 +1303,21 @@ tools:
 | `install_script` | bash | Full bash script to run on install |
 | `remove_script` | bash | Full bash script to run on remove |
 
-Unknown fields fail validation. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+Unknown fields fail validation — including the three `uv_*` fields on any type other than `pip`/`uvx`. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+
+`uv_executables_from` is worth understanding before you skip it: `uv tool install` exposes the console scripts of the *requested* package only. The `ansible` distribution is a collections bundle that declares none of its own — `ansible`, `ansible-playbook` and `ansible-vault` are all entry points of its `ansible-core` dependency — so without this field the install reports success and puts a single unusable `ansible-community` on `PATH`:
+
+```yaml
+version: 1
+tools:
+  ansible:
+    name: Ansible
+    type: uvx
+    check_cmd: ansible
+    pip_name: ansible
+    uv_executables_from:
+      - ansible-core
+```
 
 ### Examples
 

{devstuff-2.2.1 → devstuff-2.4.0}/README.md

@@ -260,7 +260,7 @@ How "update" is performed depends on the package's install `type`:
 | Type | Latest | Specific version |
 |------|--------|-------------------|
 | `npm` | `npm install -g <pkg>@latest` | `npm install -g <pkg>@<version>` |
-| `pip` / `uvx` | `uv tool upgrade <pkg>` | `uv tool upgrade <pkg>==<version>` |
+| `pip` / `uvx` | `uv tool install --force <pkg>@latest` | `uv tool install --force <pkg>==<version>` |
 | `apt` | `apt-get install --only-upgrade` | `apt-get install <pkg>=<version>` (single package only) |
 | `git` | `git pull` (+ re-run `git_install_cmd`) | not supported — repos are cloned shallow (`--depth=1`) |
 | `script` / `bash` | Re-runs the install script | not supported — no version parameter to inject |
@@ -269,6 +269,17 @@ For `script`/`bash` packages, "update" is a full reinstall (the same script that
 `sudo` runs again), since there's no narrower update mechanism available. `devstuff update` asks
 for confirmation before doing this.
 
+`pip`/`uvx` packages go through `uv tool install` rather than `uv tool upgrade` in **both**
+columns. `uv tool upgrade` takes a tool *name*, so it cannot accept `<pkg>==<version>` at all, and
+it is a no-op on a tool that was previously pinned — using it for the "latest" column would mean
+pinning a package once left no way to move it again. `<pkg>@latest` re-resolves and clears any
+existing pin in one step. Pinning warns that the pin holds until the next `devstuff update`
+without `--version`.
+
+Any `uv_with` / `uv_executables_from` / `uv_python` fields on the package are re-applied on every
+update, so adding one to your catalog takes effect on the next update rather than needing a
+reinstall.
+
 ---
 
 ### `configure`
@@ -1105,6 +1116,7 @@ ones tools already have — for now, custom functions are hand-edited YAML at
 | `whats-on-port` | network | script | Find which process is listening on a port | `port`, `protocol` (optional: `tcp`/`udp`/`all`) |
 | `acc-check` | web-dev | script | Run the pi coding agent's `/dogfood` skill against a web URL | `url`, `instruction` (optional) |
 | `aws-saml-reauth` | web-dev | script | Reauthorize the AWS CLI via `saml2aws login --force` | `profile` (optional) |
+| `which-ansible` | validation | script | Show which ansible a directory will actually use — the project's uv venv or the global one | `path` (optional) |
 
 #### `whats-on-port`
 
@@ -1136,6 +1148,32 @@ so a missing `ss` names the apt package instead of surfacing "command not found"
 
 ---
 
+#### `which-ansible`
+
+```bash
+devstuff run which-ansible              # the current directory
+devstuff run which-ansible ~/infra      # somewhere else
+```
+
+Answers "if I type `ansible-playbook` here, which one runs?" — the project's own uv venv, or the
+global tool install. It walks up for a `pyproject.toml`/`uv.lock` the way uv does, then reports
+whichever applies:
+
+- a synced project venv, plus the `uv run ansible-playbook` invocation that uses it (and what a
+  bare `ansible-playbook` would pick instead);
+- ansible declared but not synced yet, pointing at `uv sync`;
+- no ansible in the project, or no project at all, naming the global one.
+
+Every one of those is a success and exits 0 — including "this project has no ansible", which is
+an answer, not a failure. Non-zero is reserved for not being able to look at all (no uv, or a
+path that isn't a directory).
+
+It exists because devstuff's ansible and a uv-managed ansible repo are now the *same shape* — both
+a uv-created venv — so the question stopped being "which tool is broken" and became "which
+environment am I in". See `docs/specs/uv-backbone/` for why the global one moved off apt.
+
+---
+
 ## Built-in packages
 
 ### Core
@@ -1155,13 +1193,18 @@ Optional utilities you may want on some machines.
 | Key | Name | Description | Help |
 |-----|------|-------------|------|
 | `ansible` | Ansible | Automation engine for configuration management and app deployment (`devstuff configure ansible`) | `ansible --help` |
+| `ansible-vault` | Ansible Vault | Encrypt and manage secrets within Ansible projects (bundled with Ansible) | `ansible-vault --help` |
 | `aws` | AWS CLI | Amazon Web Services CLI v2 | `aws help` |
 | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
 | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
-| `eza` | eza | Modern ls replacement with git status, icons, and tree view | `eza --help` |
 | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
+| `git-lfs` | Git LFS | Git extension for versioning large files | `git lfs --help` |
 | `htop` | htop | Interactive process and resource monitor | `man htop` |
+| `homebrew` | Homebrew | Package manager for Linux (and macOS) | `brew --help` |
+| `ipython` | IPython | Enhanced interactive Python shell with rich tab completion and magic commands | `ipython --help` |
 | `lazygit` | lazygit | TUI git client for fast, keyboard-driven git workflows (`devstuff configure lazygit`) | `lazygit --help` |
+| `llm-checker` | llm-checker | Check LLM compatibility with your hardware | `llm-checker --help` |
+| `lmstudio` | LM Studio | Run large language models locally with a GUI | `lms --help` |
 | `mkcert` | mkcert | Zero-config local HTTPS certificates | `mkcert --help` |
 | `nerd-font` | JetBrainsMono Nerd Font | Patched font supplying the icons Starship and other CLI tools draw | `fc-list \| grep -i "nerd font"` |
 | `ollama` | Ollama | Run large language models locally | `ollama --help` |
@@ -1178,6 +1221,7 @@ Optional utilities you may want on some machines.
 |-----|------|-------------|------|
 | `go` | Go | Go programming language toolchain | `go help` |
 | `java` | Java 21 (OpenJDK) | OpenJDK 21 LTS - JDK and JRE | `java --help` |
+| `python` | Python (uv-managed) | CPython provisioned by uv, installed as the default `python`/`python3` | `uv python list` |
 | `ruby` | Ruby (rbenv) | Ruby via rbenv version manager + ruby-build | `ruby --version` |
 
 ---
@@ -1220,7 +1264,10 @@ tools:
 | `docs_url` | no | URL opened by `devstuff docs <key>` |
 | `requires` | no | List of package keys that must already be installed |
 | `npm_name` | npm | npm package name |
-| `pip_name` | pip | PyPI package name |
+| `pip_name` | pip | PyPI package name. Extras work as-is: `pip_name: "ansible-lint[lock]"` |
+| `uv_with` | no (pip/uvx) | Extra packages installed into the tool's environment (`uv tool install --with`) |
+| `uv_executables_from` | no (pip/uvx) | Also expose console scripts from these packages (`--with-executables-from`). Needed when a package's entry points live in a dependency |
+| `uv_python` | no (pip/uvx) | Pin the tool environment's Python (`--python`), e.g. `"3.12"` |
 | `apt_packages` | apt | Space-separated list of apt packages |
 | `git_url` | git | Repository URL to clone |
 | `git_install_cmd` | git | Bash command run inside the cloned repo after clone |
@@ -1229,7 +1276,21 @@ tools:
 | `install_script` | bash | Full bash script to run on install |
 | `remove_script` | bash | Full bash script to run on remove |
 
-Unknown fields fail validation. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+Unknown fields fail validation — including the three `uv_*` fields on any type other than `pip`/`uvx`. `requires` defaults to `["nvm"]` for `npm` tools and `["uv"]` for `pip`/`uvx` tools unless explicitly set.
+
+`uv_executables_from` is worth understanding before you skip it: `uv tool install` exposes the console scripts of the *requested* package only. The `ansible` distribution is a collections bundle that declares none of its own — `ansible`, `ansible-playbook` and `ansible-vault` are all entry points of its `ansible-core` dependency — so without this field the install reports success and puts a single unusable `ansible-community` on `PATH`:
+
+```yaml
+version: 1
+tools:
+  ansible:
+    name: Ansible
+    type: uvx
+    check_cmd: ansible
+    pip_name: ansible
+    uv_executables_from:
+      - ansible-core
+```
 
 ### Examples