feat: catalog-driven bash-completion installation

AGENTS.md

@@ -104,6 +104,8 @@ This repo **is** a CLI tool manager, so the word "upgrade" is overloaded:
 | `make reset-pins` | Remove all version pins |
 | `make upgrade-all` | Full system upgrade (data + managers + tools) |
 | `./scripts/set_auto_update.sh <tool>` | Enable auto-update for a tool |
+| `make completions` | Install bash completions for all installed tools that declare one |
+| `make completion-<tool>` | Install bash completion for one tool (e.g. `make completion-gh`) |
 | `uv run python audit.py --versions` | Show multi-version runtime status |
 | `uv run python audit.py --versions php` | Show specific runtime versions |
 

Makefile

@@ -18,6 +18,7 @@ export
 	install-aws install-kubectl install-terraform install-ansible install-docker \
 	install-brew install-rust install-uv install-% upgrade-% uninstall-% reconcile-% \
 	reconcile-all reconcile-all-dry-run \
+	completions completion-% \
 	build build-dist build-wheel check-dist publish-test publish-prod \
 	clean clean-build clean-test clean-pyc clean-all \
 	scripts-perms audit-auto detect-managers upgrade-managed upgrade-dry-run \

Makefile.d/user.mk

@@ -236,6 +236,16 @@ reconcile-all: scripts-perms ## Remove duplicate installs across ALL tools (conf
 reconcile-all-dry-run: scripts-perms ## Preview duplicate-install cleanup across ALL tools (removes nothing)
 	@$(PYTHON) audit.py --reconcile --all
 
+# ----------------------------------------------------------------------------
+# BASH COMPLETION
+# ----------------------------------------------------------------------------
+
+completions: scripts-perms ## Install bash completions for all installed tools that declare them
+	@./scripts/install_completion.sh --all
+
+completion-%: scripts-perms ## Install bash completion for one tool (e.g., make completion-gh)
+	@./scripts/install_completion.sh "$*" install
+
 # ----------------------------------------------------------------------------
 # SYSTEM MANAGEMENT
 # ----------------------------------------------------------------------------

catalog/COVERAGE.md

@@ -63,3 +63,51 @@ Most now in catalog, one dedicated script:
 - **5 tools** are system packages only
 
 All installable tools either have catalog entries or use appropriate dedicated scripts.
+
+## Bash completion coverage
+
+Every catalog entry was audited for a bash-completion generator (sweep of
+2026-07-22; each generator was executed and its output validated against
+`complete -…` / `compgen ` / `COMPREPLY`, then checked to confirm it registers
+the entry's own `binary_name`).
+
+**40 entries declare `bash_completion`** — 39 `command`, 1 `source_path` (rbenv).
+
+Declared (`command`): ast-grep, bat, black, codex, composer, dasel, delta, dive,
+docker, fd, fx, gh, git-absorb, git-lfs, gitleaks, glab, golangci-lint, gup, jj,
+just, kubectl, mlr, node, npm, parallel, pip, pipx, pnpm, poetry, ripgrep, ruff,
+scc, symfony, trivy, uv, vhs, watchexec, yq, zellij
+
+Declared (`source_path`): rbenv (`completions/rbenv.bash`, under its `clone_path`)
+
+### Deliberately excluded (a generator exists but must not be used)
+
+The completion file is named after `binary_name`, so a script that registers a
+*different* command would silently shadow another tool's completion:
+
+| Tool | Why excluded |
+|------|--------------|
+| `gh-aw` | `gh-aw completion bash` emits **gh's** completion (`complete … __start_gh gh`); it never registers `gh-aw` and would shadow the distro `gh` completion |
+| `rga` | `rga --generate complete-bash` forwards to ripgrep and returns ripgrep's script verbatim (registers `rg`) |
+| `compose` | `binary_name` is `docker`; no compose-specific generator exists — `docker` already covers it |
+| `fzf` | `fzf --bash` is full shell *integration* (key bindings, a global `complete -D` handler), not a completion script. Use `eval "$(fzf --bash)"` in `.bashrc` instead |
+| `rust` | `rustup completions bash` registers `rustup`/`cargo`, never `rustc` |
+| `gcloud` | Ships `completion.bash.inc`, but the entry has no `clone_path` for `source_path` to resolve against, and the file registers three commands (`gcloud`, `bq`, `gsutil`) in one lazily-loaded file |
+
+### No bash completion available
+
+actionlint, ansible-core, aws, bandit, claude, ctags, curlie, difftastic,
+direnv, dust, entr, eslint, flake8, gam, gem, gemini, gh-aw-firewall, git,
+git-branchless, git-filter-repo, go, google-workspace-cli, gosec, httpie,
+hyperfine, isort, jq, ninja, opengrep, php, pre-commit, prename, prettier,
+python, qsv, rename.ul, ruby, ruby-build, sd, semgrep, shellcheck, shfmt,
+sponge, templ, terraform, tfsec, tmux, tokei, tree, wslu, xsv, yarn
+
+(`git` and `docker` already ship completions via the distro `bash-completion`
+package; `docker` is still declared so the generated script matches the
+installed daemon version, and the XDG user directory takes precedence.)
+
+**Not verifiable on the audit machine** — `codex`, `pip`, `pipx` were not
+installed, so their generators come from official documentation rather than a
+local run. The runtime validation makes this safe: if the command does not
+produce a valid completion script, nothing is written.

catalog/ast-grep.json

@@ -12,5 +12,8 @@
     "aarch64": "aarch64",
     "armv7l": "armv7"
   },
-  "auto_update": true
+  "auto_update": true,
+  "bash_completion": {
+    "command": "ast-grep completions bash"
+  }
 }

catalog/bat.json

@@ -6,7 +6,10 @@
   "homepage": "https://github.com/sharkdp/bat",
   "github_repo": "sharkdp/bat",
   "binary_name": "bat",
-  "candidates": ["bat", "batcat"],
+  "candidates": [
+    "bat",
+    "batcat"
+  ],
   "download_url_template": "https://github.com/sharkdp/bat/releases/download/{version}/bat-{version}-{arch}-unknown-linux-musl.tar.gz",
   "arch_map": {
     "x86_64": "x86_64",
@@ -40,5 +43,8 @@
   "requires": [],
   "tags": [
     "core"
-  ]
+  ],
+  "bash_completion": {
+    "command": "bat --completion bash"
+  }
 }

catalog/black.json

@@ -5,5 +5,8 @@
   "description": "The uncompromising Python code formatter",
   "homepage": "https://github.com/psf/black",
   "package_name": "black",
-  "version_command": "black --version 2>/dev/null | head -1"
+  "version_command": "black --version 2>/dev/null | head -1",
+  "bash_completion": {
+    "command": "_BLACK_COMPLETE=bash_source black"
+  }
 }

catalog/codex.json

@@ -7,12 +7,17 @@
   "github_repo": "openai/codex",
   "package_name": "@openai/codex",
   "binary_name": "codex",
-  "requires": ["node"],
+  "requires": [
+    "node"
+  ],
   "version_command": "codex --version 2>/dev/null | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' | head -1",
   "guide": {
     "display_name": "OpenAI Codex CLI",
     "install_action": "upgrade",
     "order": 401
   },
-  "notes": "OpenAI's open-source coding agent. Requires OPENAI_API_KEY. Supports multiple AI providers including third-party models."
+  "notes": "OpenAI's open-source coding agent. Requires OPENAI_API_KEY. Supports multiple AI providers including third-party models.",
+  "bash_completion": {
+    "command": "codex completion bash"
+  }
 }

catalog/composer.json

@@ -7,11 +7,16 @@
   "github_repo": "composer/composer",
   "binary_name": "composer",
   "script": "install_composer.sh",
-  "requires": ["php"],
+  "requires": [
+    "php"
+  ],
   "guide": {
     "display_name": "Composer",
     "install_action": "install",
     "order": 260
   },
-  "notes": "Installed from latest stable phar (https://getcomposer.org/download/latest-stable/composer.phar). Requires PHP."
+  "notes": "Installed from latest stable phar (https://getcomposer.org/download/latest-stable/composer.phar). Requires PHP.",
+  "bash_completion": {
+    "command": "composer completion bash"
+  }
 }

catalog/dasel.json

@@ -13,5 +13,8 @@
     "armv7l": "arm7"
   },
   "version_command": "dasel version 2>/dev/null | grep -oE 'v?[0-9]+\\.[0-9]+\\.[0-9]+'",
-  "auto_update": true
+  "auto_update": true,
+  "bash_completion": {
+    "command": "dasel completion bash"
+  }
 }

catalog/delta.json

@@ -38,5 +38,8 @@
   ],
   "tags": [
     "core"
-  ]
+  ],
+  "bash_completion": {
+    "command": "delta --generate-completion bash"
+  }
 }

catalog/dive.json

@@ -11,5 +11,8 @@
     "x86_64": "amd64",
     "aarch64": "arm64",
     "armv7l": "arm"
+  },
+  "bash_completion": {
+    "command": "dive completion bash"
   }
 }

catalog/docker.json

@@ -11,5 +11,8 @@
     "display_name": "Docker CLI",
     "install_action": "install",
     "order": 200
+  },
+  "bash_completion": {
+    "command": "docker completion bash"
   }
 }

catalog/fd.json

@@ -6,7 +6,10 @@
   "homepage": "https://github.com/sharkdp/fd",
   "github_repo": "sharkdp/fd",
   "binary_name": "fd",
-  "candidates": ["fd", "fdfind"],
+  "candidates": [
+    "fd",
+    "fdfind"
+  ],
   "download_url_template": "https://github.com/sharkdp/fd/releases/download/{version}/fd-{version}-{arch}-unknown-linux-musl.tar.gz",
   "arch_map": {
     "x86_64": "x86_64",
@@ -42,5 +45,8 @@
     "core",
     "search",
     "file-utils"
-  ]
+  ],
+  "bash_completion": {
+    "command": "fd --gen-completions bash"
+  }
 }

catalog/fx.json

@@ -11,5 +11,8 @@
     "x86_64": "amd64",
     "aarch64": "arm64",
     "armv7l": "armv6"
+  },
+  "bash_completion": {
+    "command": "fx --comp bash"
   }
 }

catalog/gh.json

@@ -11,5 +11,8 @@
     "x86_64": "amd64",
     "aarch64": "arm64",
     "armv7l": "armv6"
+  },
+  "bash_completion": {
+    "command": "gh completion -s bash"
   }
 }

catalog/git-absorb.json

@@ -12,5 +12,8 @@
     "x86_64": "x86_64",
     "armv7l": "arm"
   },
-  "notes": "Only x86_64 builds available; arm builds use different target triple"
+  "notes": "Only x86_64 builds available; arm builds use different target triple",
+  "bash_completion": {
+    "command": "git-absorb --gen-completions bash"
+  }
 }

catalog/git-lfs.json

@@ -11,5 +11,8 @@
     "x86_64": "amd64",
     "aarch64": "arm64",
     "armv7l": "arm"
+  },
+  "bash_completion": {
+    "command": "git-lfs completion bash"
   }
 }

catalog/gitleaks.json

@@ -11,5 +11,8 @@
     "x86_64": "x64",
     "aarch64": "arm64",
     "armv7l": "armv7"
+  },
+  "bash_completion": {
+    "command": "gitleaks completion bash"
   }
 }

catalog/glab.json

@@ -11,5 +11,8 @@
     "x86_64": "amd64",
     "aarch64": "arm64",
     "armv7l": "armv6"
+  },
+  "bash_completion": {
+    "command": "glab completion -s bash"
   }
 }

catalog/golangci-lint.json

@@ -13,5 +13,8 @@
     "aarch64": "arm64",
     "armv7l": "armv6"
   },
-  "auto_update": true
+  "auto_update": true,
+  "bash_completion": {
+    "command": "golangci-lint completion bash"
+  }
 }

catalog/gup.json

@@ -46,5 +46,8 @@
     "package-manager",
     "updater"
   ],
-  "auto_update": true
+  "auto_update": true,
+  "bash_completion": {
+    "command": "gup completion bash"
+  }
 }

catalog/jj.json

@@ -33,5 +33,8 @@
   "tags": [
     "git",
     "vcs"
-  ]
+  ],
+  "bash_completion": {
+    "command": "jj util completion bash"
+  }
 }

catalog/just.json

@@ -15,5 +15,8 @@
   "tags": [
     "core"
   ],
-  "auto_update": true
+  "auto_update": true,
+  "bash_completion": {
+    "command": "JUST_COMPLETE=bash just"
+  }
 }

catalog/kubectl.json

@@ -20,5 +20,8 @@
     "display_name": "kubectl",
     "install_action": "install",
     "order": 203
+  },
+  "bash_completion": {
+    "command": "kubectl completion bash"
   }
 }

catalog/mlr.json

@@ -17,5 +17,8 @@
     "csv",
     "json",
     "text-utils"
-  ]
+  ],
+  "bash_completion": {
+    "command": "mlr completion bash"
+  }
 }

catalog/node.json

@@ -28,5 +28,8 @@
       "package.json"
     ]
   },
-  "notes": "Managed via nvm (Node Version Manager). Supports multiple concurrent LTS versions."
+  "notes": "Managed via nvm (Node Version Manager). Supports multiple concurrent LTS versions.",
+  "bash_completion": {
+    "command": "node --completion-bash"
+  }
 }

catalog/npm.json

@@ -6,6 +6,11 @@
   "homepage": "https://www.npmjs.com/",
   "package_name": "npm",
   "binary_name": "npm",
-  "requires": ["node"],
-  "notes": "npm comes bundled with Node.js but can be upgraded independently using 'npm install -g npm@latest'"
+  "requires": [
+    "node"
+  ],
+  "notes": "npm comes bundled with Node.js but can be upgraded independently using 'npm install -g npm@latest'",
+  "bash_completion": {
+    "command": "npm completion"
+  }
 }

catalog/parallel.json

@@ -8,5 +8,8 @@
   "script": "install_parallel.sh",
   "ftp_url": "https://ftp.gnu.org/gnu/parallel/",
   "notes": "Installed from GNU FTP releases. Installs to ~/.local/bin/parallel.",
-  "auto_update": true
+  "auto_update": true,
+  "bash_completion": {
+    "command": "parallel --shellcompletion bash"
+  }
 }

catalog/pip.json

@@ -6,7 +6,13 @@
   "homepage": "https://pip.pypa.io/",
   "package_name": "pip",
   "binary_name": "pip",
-  "candidates": ["pip", "pip3"],
+  "candidates": [
+    "pip",
+    "pip3"
+  ],
   "script": "install_pip.sh",
-  "notes": "pip is bundled with Python 3. Use python3 -m pip if pip command is not available."
+  "notes": "pip is bundled with Python 3. Use python3 -m pip if pip command is not available.",
+  "bash_completion": {
+    "command": "pip completion --bash"
+  }
 }

catalog/pipx.json

@@ -11,5 +11,8 @@
     "brew": "pipx",
     "dnf": "pipx",
     "pacman": "python-pipx"
+  },
+  "bash_completion": {
+    "command": "register-python-argcomplete pipx"
   }
 }