fix: guard and document the external tools PR #168 flagged as unguarded

PR #168's Notes section named several functions with a real
external-tool dependency that no `type -q`/`command -q`/`command -v`/
`which` guard covers anywhere in the tree, deliberately left out of
DEPENDENCIES to avoid breaking test_dependencies_resolve. Adds the
guard each was missing, then declares the dependency now that it
resolves:

- bkg, detach: nohup
- gitui: gitui (self-shadow; type -q -f to skip the function itself)
- play-media: mpv, vlc -- already guarded via `type -q -f $p` in a
  loop, just never recognized as one (see next point)
- steam-dl: systemd-inhibit, steam
- wake-lock: systemd-inhibit
- split, spwin, tab: wezterm, konsole (kitty already declared)

docs/verify-manual.py's guard-detection regex only matched `type -q
<name>` immediately, so `type -q -f $p` (the `-f` flag excludes
functions from the match, needed wherever a wrapper shadows a binary
of its own name) was invisible to it -- both as a direct guard and
through the loop-variable indirection. Broadened both patterns to
skip over any flags between `-q` and the name/variable.

split/spwin/tab dispatch on $TERM/$TERM_PROGRAM/$KONSOLE_VERSION to
pick which terminal-specific binary to call, per this repo's C4
convention -- but those env vars only prove the terminal type, not
that its CLI binary is on $PATH: they propagate over ssh, so sshing
out from Kitty/WezTerm inherits the var on a remote host that never
installed the binary. Same latent gap in clone/clonet, whose
clone-in-kitty is a function Kitty's own shell integration injects,
not present on a remote shell that only inherited $TERM. All five now
check the actual thing they are about to call, not just the env var
that selects it.

Also guards and documents three more real, previously-undeclared
dependencies found by the same audit, unrelated to PR #168's named
list but the identical pattern: fast-cli (fast), lock (loginctl),
ports (lsof), screensleep (busctl).

docs/fish-config.md regenerated to match.
This commit is contained in:
2026-09-22 22:40:33 -04:00
parent 3bbda31eff
commit 8dcbc62359
17 changed files with 208 additions and 26 deletions
+49 -11
View File
@@ -1026,11 +1026,13 @@ functions). They are active in all interactive sessions.
Exit Status:
0 Repository cloned
1 Not running inside Kitty terminal
1 Not running inside Kitty terminal, or clone-in-kitty isn't available
Example:
clone https://github.com/user/repo.git
**Dependencies:** `clone-in-kitty`
### clonet
Synopsis: clonet [args...]
@@ -1043,11 +1045,13 @@ functions). They are active in all interactive sessions.
Exit Status:
0 Repository cloned
1 Not running inside Kitty terminal
1 Not running inside Kitty terminal, or clone-in-kitty isn't available
Example:
clonet https://github.com/user/repo.git
**Dependencies:** `clone-in-kitty`
## 5.3 Editors and Viewers
### edit
@@ -1335,9 +1339,17 @@ functions). They are active in all interactive sessions.
Arguments:
args... Arguments forwarded to the gitui command
Exit Status:
1 gitui is not installed
* Exit status of gitui otherwise
Example:
gitui
**Dependencies:** `gitui`
**Used by:** `gitui`
### gitup
Synopsis: gitup [args...]
@@ -1758,11 +1770,14 @@ functions). They are active in all interactive sessions.
Locks the current desktop session using loginctl lock-session.
Exit Status:
Exit status of loginctl lock-session
1 loginctl is not installed
* Exit status of loginctl lock-session otherwise
Example:
lock
**Dependencies:** `loginctl`
### ports
Synopsis: ports
@@ -1771,11 +1786,14 @@ functions). They are active in all interactive sessions.
port numbers and addresses without hostname resolution.
Exit Status:
Exit status of lsof
1 lsof is not installed
* Exit status of lsof otherwise
Example:
ports
**Dependencies:** `lsof`
### sbver
Synopsis: sbver [--brief]
@@ -1808,11 +1826,14 @@ functions). They are active in all interactive sessions.
PowerDevil "Turn Off Screen" global shortcut via busctl.
Exit Status:
Exit status of busctl
1 busctl is not installed
* Exit status of busctl otherwise
Example:
screensleep
**Dependencies:** `busctl`
### sudo-toggle
Synopsis: sudo-toggle
@@ -1880,6 +1901,8 @@ functions). They are active in all interactive sessions.
Example:
bkg firefox
**Dependencies:** `nohup`
**Used by:** `md`
### detach
@@ -1903,6 +1926,8 @@ functions). They are active in all interactive sessions.
Example:
detach rsync -a ./data remote:/backup/
**Dependencies:** `nohup`
### fish_mode_prompt
Synopsis: fish_mode_prompt
@@ -2035,7 +2060,7 @@ functions). They are active in all interactive sessions.
split
split -v nvim README.md
**Dependencies:** `kitty`
**Dependencies:** `kitty`, `wezterm`
### spwin
@@ -2054,7 +2079,7 @@ functions). They are active in all interactive sessions.
Example:
spwin
**Dependencies:** `kitty`
**Dependencies:** `kitty`, `wezterm`
### ssh
@@ -2093,7 +2118,7 @@ functions). They are active in all interactive sessions.
Example:
tab
**Dependencies:** `kitty`
**Dependencies:** `kitty`, `wezterm`, `konsole`
## 5.9 Clipboard
@@ -2181,6 +2206,8 @@ functions). They are active in all interactive sessions.
Example:
fast
**Used by:** `fast-cli`
### fast-cli
Synopsis: fast-cli [args...]
@@ -2190,9 +2217,15 @@ functions). They are active in all interactive sessions.
Arguments:
args... Arguments forwarded to the fast command
Exit Status:
1 fast is not installed
* Exit status of fast otherwise
Example:
fast-cli
**Dependencies:** `fast`
### gip
Synopsis: gip
@@ -2992,7 +3025,7 @@ functions). They are active in all interactive sessions.
play-media
play-media --player mpv
**Dependencies:** `_fzf_preview_media`, `_fzf_wrapper`, `fd`, `fdfind`, `file`, `xdg-mime`
**Dependencies:** `_fzf_preview_media`, `_fzf_wrapper`, `fd`, `fdfind`, `file`, `xdg-mime`, `mpv`, `vlc`
### spark
@@ -3022,11 +3055,14 @@ functions). They are active in all interactive sessions.
or sleeping during active downloads.
Exit Status:
Exit status of steam (via systemd-inhibit)
1 systemd-inhibit or steam is not installed
* Exit status of steam (via systemd-inhibit) otherwise
Example:
steam-dl
**Dependencies:** `systemd-inhibit`, `steam`
### yt-dlp
Synopsis: yt-dlp [args...] URL [URL...]
@@ -3615,11 +3651,13 @@ functions). They are active in all interactive sessions.
Exit Status:
0 Command ran and completed
1 No command provided
1 No command provided, or systemd-inhibit is not installed
Example:
wake-lock rsync -avz src/ dest/
**Dependencies:** `systemd-inhibit`
# 6. DEPENDENCY CATALOG
`fish-deps` manages these tools. Run `fish-deps` to check status,
+5 -2
View File
@@ -211,12 +211,15 @@ def test_dependencies_resolve():
repo = Path(__file__).parent.parent
functions = _parsed_functions()
known = {p.stem for p in (repo / "functions").glob("*.fish")} | set(functions)
guard_re = re.compile(r"(?:type -q|command -q|command -v|which)\s+([\w.\-]+)")
# `type` takes its own flags (e.g. `-f` to exclude functions from the
# match, as in `type -q -f $p`) that can sit between `-q` and the name
# -- skip over any of those so the guard is still recognized.
guard_re = re.compile(r"(?:type -q(?:\s+-\w+)*|command -q|command -v|which)\s+([\w.\-]+)")
for path in list(repo.glob("conf.d/*.fish")) + list((repo / "functions").glob("*.fish")):
text = path.read_text(encoding="utf-8")
known |= set(guard_re.findall(text))
for var, names in re.findall(r"for\s+(\w+)\s+in\s+([^\n;]+)", text):
if re.search(rf"type -q\s+\$\{{?{re.escape(var)}\}}?\b", text):
if re.search(rf"type -q(?:\s+-\w+)*\s+\$\{{?{re.escape(var)}\}}?\b", text):
known |= set(names.split())
dangling = []
for name, fn in functions.items():
+8
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 08-terminal-management
#
# DEPENDENCIES
# nohup
#
# SYNOPSIS
# bkg <command> [args...]
#
@@ -32,6 +35,11 @@ function bkg --description 'Execute bkg'
return 1
end
if not type -q nohup
echo (set_color red)"Error: nohup is not installed."(set_color normal) >&2
return 1
end
# Run the command using nohup to make it immune to hangups (like closing the terminal).
# Redirect both stdout and stderr to /dev/null to discard all output.
# The final ampersand (&) sends the entire process to the background.
+11 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 02-navigation
#
# DEPENDENCIES
# clone-in-kitty
#
# SYNOPSIS
# clone [args...]
#
@@ -16,7 +19,7 @@
#
# EXIT STATUS
# 0 Repository cloned
# 1 Not running inside Kitty terminal
# 1 Not running inside Kitty terminal, or clone-in-kitty isn't available
#
# EXAMPLE
# clone https://github.com/user/repo.git
@@ -25,5 +28,12 @@ function clone --wraps='clone-in-kitty' --description 'alias clone=clone-in-kitt
echo "Error: The 'clone' command requires Kitty terminal." >&2
return 1
end
# $TERM only proves the terminal type -- clone-in-kitty is a function
# Kitty's own shell integration injects, which doesn't happen over an
# ssh session that merely inherits $TERM from the local Kitty.
if not type -q clone-in-kitty
echo "Error: 'clone' detected Kitty but clone-in-kitty isn't available (shell integration not loaded)." >&2
return 1
end
clone-in-kitty $argv
end
+11 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 02-navigation
#
# DEPENDENCIES
# clone-in-kitty
#
# SYNOPSIS
# clonet [args...]
#
@@ -16,7 +19,7 @@
#
# EXIT STATUS
# 0 Repository cloned
# 1 Not running inside Kitty terminal
# 1 Not running inside Kitty terminal, or clone-in-kitty isn't available
#
# EXAMPLE
# clonet https://github.com/user/repo.git
@@ -25,5 +28,12 @@ function clonet --wraps='clone-in-kitty --type=tab' --description 'alias clonet=
echo "Error: The 'clonet' command requires Kitty terminal." >&2
return 1
end
# $TERM only proves the terminal type -- clone-in-kitty is a function
# Kitty's own shell integration injects, which doesn't happen over an
# ssh session that merely inherits $TERM from the local Kitty.
if not type -q clone-in-kitty
echo "Error: 'clonet' detected Kitty but clone-in-kitty isn't available (shell integration not loaded)." >&2
return 1
end
clone-in-kitty --type=tab $argv
end
+8
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 08-terminal-management
#
# DEPENDENCIES
# nohup
#
# SYNOPSIS
# detach [-h] [--version] <command> [args...]
#
@@ -66,5 +69,10 @@ function detach --description 'Execute detach'
return 1
end
if not type -q nohup
echo (set_color red)"Error: nohup is not installed."(set_color normal) >&2
return 1
end
nohup $args >/dev/null 2>&1 &
end
+11
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 10-network
#
# DEPENDENCIES
# fast
#
# SYNOPSIS
# fast-cli [args...]
#
@@ -13,8 +16,16 @@
# ARGUMENTS
# args... Arguments forwarded to the fast command
#
# EXIT STATUS
# 1 fast is not installed
# * Exit status of fast otherwise
#
# EXAMPLE
# fast-cli
function fast-cli --description "Run a speed test using fast.com"
if not type -q -f fast
echo (set_color red)"Error: fast is not installed."(set_color normal) >&2
return 1
end
command fast $argv
end
+12 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 04-git-and-version-control
#
# DEPENDENCIES
# gitui
#
# SYNOPSIS
# gitui [args...]
#
@@ -14,9 +17,17 @@
# ARGUMENTS
# args... Arguments forwarded to the gitui command
#
# EXIT STATUS
# 1 gitui is not installed
# * Exit status of gitui otherwise
#
# EXAMPLE
# gitui
function gitui --wraps='gitui' --description 'alias gitui=gitui -t mocha.ron'
if not type -q -f gitui
echo (set_color red)"Error: gitui is not installed."(set_color normal) >&2
return 1
end
command gitui -t frappe.ron $argv
end
+10 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 07-system-and-monitoring
#
# DEPENDENCIES
# loginctl
#
# SYNOPSIS
# lock
#
@@ -11,12 +14,18 @@
# Locks the current desktop session using loginctl lock-session.
#
# EXIT STATUS
# Exit status of loginctl lock-session
# 1 loginctl is not installed
# * Exit status of loginctl lock-session otherwise
#
# EXAMPLE
# lock
function lock --wraps='loginctl' --description 'alias lock=loginctl'
__fish_help_header (status current-function) $argv; and return 0
if not type -q loginctl
echo (set_color red)"Error: loginctl is not installed."(set_color normal) >&2
return 1
end
loginctl lock-session
end
+1 -1
View File
@@ -5,7 +5,7 @@
# 13-media-and-utilities
#
# DEPENDENCIES
# _fzf_preview_media, _fzf_wrapper, fd, fdfind, file, xdg-mime
# _fzf_preview_media, _fzf_wrapper, fd, fdfind, file, xdg-mime, mpv, vlc
#
# SYNOPSIS
# play-media [-p|--player <cmd>]
+10 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 07-system-and-monitoring
#
# DEPENDENCIES
# lsof
#
# SYNOPSIS
# ports
#
@@ -12,12 +15,18 @@
# port numbers and addresses without hostname resolution.
#
# EXIT STATUS
# Exit status of lsof
# 1 lsof is not installed
# * Exit status of lsof otherwise
#
# EXAMPLE
# ports
function ports --wraps='sudo' --description 'Show active network listeners'
__fish_help_header (status current-function) $argv; and return 0
if not type -q lsof
echo (set_color red)"Error: lsof is not installed."(set_color normal) >&2
return 1
end
sudo lsof -iTCP -sTCP:LISTEN -P -n
end
+10 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 07-system-and-monitoring
#
# DEPENDENCIES
# busctl
#
# SYNOPSIS
# screensleep
#
@@ -12,13 +15,19 @@
# PowerDevil "Turn Off Screen" global shortcut via busctl.
#
# EXIT STATUS
# Exit status of busctl
# 1 busctl is not installed
# * Exit status of busctl otherwise
#
# EXAMPLE
# screensleep
function screensleep --description 'Turn off the display using KDE PowerDevil'
__fish_help_header (status current-function) $argv; and return 0
if not type -q busctl
echo (set_color red)"Error: busctl is not installed."(set_color normal) >&2
return 1
end
# Optional: 1-second delay to ensure no keystrokes wake it immediately
sleep 1
busctl --user call \
+12 -1
View File
@@ -8,7 +8,7 @@
# integrations/window-mgmt
#
# DEPENDENCIES
# kitty
# kitty, wezterm
#
# SYNOPSIS
# split [-h | -v] [command...]
@@ -55,6 +55,17 @@ function split --description 'Run a command in a new terminal split'
return 1
end
# $TERM/$TERM_PROGRAM only prove the terminal type, not that its CLI
# binary is on $PATH -- e.g. sshing out from Kitty/WezTerm inherits the
# env var on the remote host without the binary. Check explicitly.
if test $is_kitty -eq 1; and not type -q kitty
echo "Error: 'split' detected Kitty but the kitty binary is not installed." >&2
return 1
else if test $is_wezterm -eq 1; and not type -q wezterm
echo "Error: 'split' detected WezTerm but the wezterm binary is not installed." >&2
return 1
end
set -l kitty_loc hsplit
set -l wez_loc --bottom
+12 -2
View File
@@ -8,7 +8,7 @@
# integrations/window-mgmt
#
# DEPENDENCIES
# kitty
# kitty, wezterm
#
# SYNOPSIS
# spwin [args...]
@@ -36,13 +36,23 @@ function spwin --wraps='~/.config/kitty/spawn-window.sh' --description 'spawn wi
return 1
end
# $TERM/$TERM_PROGRAM only prove the terminal type, not that its CLI
# binary is on $PATH -- e.g. sshing out from Kitty/WezTerm inherits the
# env var on the remote host without the binary. Check explicitly.
if test "$TERM" = xterm-kitty
if test -x ~/.config/kitty/spawn-window.sh
~/.config/kitty/spawn-window.sh $argv
else
else if type -q kitty
kitty @ launch --type=window $argv
else
echo "Error: 'spwin' detected Kitty but neither spawn-window.sh nor the kitty binary is available." >&2
return 1
end
else if test "$TERM_PROGRAM" = WezTerm
if not type -q wezterm
echo "Error: 'spwin' detected WezTerm but the wezterm binary is not installed." >&2
return 1
end
wezterm cli spawn $argv
else
echo "Error: The 'spwin' command requires Kitty or WezTerm." >&2
+12 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 13-media-and-utilities
#
# DEPENDENCIES
# systemd-inhibit, steam
#
# SYNOPSIS
# steam-dl
#
@@ -12,13 +15,21 @@
# or sleeping during active downloads.
#
# EXIT STATUS
# Exit status of steam (via systemd-inhibit)
# 1 systemd-inhibit or steam is not installed
# * Exit status of steam (via systemd-inhibit) otherwise
#
# EXAMPLE
# steam-dl
function steam-dl --description 'Run Steam while inhibiting system sleep'
__fish_help_header (status current-function) $argv; and return 0
for cmd in systemd-inhibit steam
if not type -q $cmd
echo (set_color red)"Error: $cmd is not installed."(set_color normal) >&2
return 1
end
end
echo "Inhibiting sleep while Steam downloads..."
systemd-inhibit --why="Active Download" --who="User" --what=idle:sleep steam
end
+17 -1
View File
@@ -8,7 +8,7 @@
# integrations/window-mgmt
#
# DEPENDENCIES
# kitty
# kitty, wezterm, konsole
#
# SYNOPSIS
# tab [args...]
@@ -42,11 +42,27 @@ function tab --description 'Spawn a new tab in the current terminal'
set dir "$PWD"
end
# $TERM/$TERM_PROGRAM/$KONSOLE_VERSION only prove the terminal type,
# not that its CLI binary is on $PATH -- e.g. sshing out from one of
# these inherits the env var on the remote host without the binary.
# Check explicitly.
if test "$TERM" = xterm-kitty
if not type -q kitty
echo "Error: 'tab' detected Kitty but the kitty binary is not installed." >&2
return 1
end
kitty @ launch --type=tab --cwd="$dir" $argv
else if test "$TERM_PROGRAM" = WezTerm
if not type -q wezterm
echo "Error: 'tab' detected WezTerm but the wezterm binary is not installed." >&2
return 1
end
wezterm cli spawn --cwd "$dir" $argv
else if set -q KONSOLE_VERSION
if not type -q konsole
echo "Error: 'tab' detected Konsole but the konsole binary is not installed." >&2
return 1
end
konsole --new-tab --workdir "$dir" $argv
else
echo "Error: No supported terminal found. Try Kitty, WezTerm, or Konsole." >&2
+9 -1
View File
@@ -4,6 +4,9 @@
# CATEGORY
# 14-miscellaneous
#
# DEPENDENCIES
# systemd-inhibit
#
# SYNOPSIS
# wake-lock <command> [args...]
#
@@ -17,7 +20,7 @@
#
# EXIT STATUS
# 0 Command ran and completed
# 1 No command provided
# 1 No command provided, or systemd-inhibit is not installed
#
# EXAMPLE
# wake-lock rsync -avz src/ dest/
@@ -30,6 +33,11 @@ function wake-lock --description 'Run a command while inhibiting system sleep'
return 1
end
if not type -q systemd-inhibit
echo (set_color red)"Error: systemd-inhibit is not installed."(set_color normal) >&2
return 1
end
echo "Running '$argv' with sleep inhibition active..."
# --what=idle:sleep prevents the system from auto-sleeping or being suspended