diff --git a/docs/fish-config.md b/docs/fish-config.md index 193159d..9ff79b8 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -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, diff --git a/docs/verify-manual.py b/docs/verify-manual.py index 703d9ec..4500fb7 100644 --- a/docs/verify-manual.py +++ b/docs/verify-manual.py @@ -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(): diff --git a/functions/bkg.fish b/functions/bkg.fish index 5bffc67..30f4336 100644 --- a/functions/bkg.fish +++ b/functions/bkg.fish @@ -4,6 +4,9 @@ # CATEGORY # 08-terminal-management # +# DEPENDENCIES +# nohup +# # SYNOPSIS # bkg [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. diff --git a/functions/clone.fish b/functions/clone.fish index 338476a..cbbaf86 100644 --- a/functions/clone.fish +++ b/functions/clone.fish @@ -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 diff --git a/functions/clonet.fish b/functions/clonet.fish index f9bac1b..38b5c38 100644 --- a/functions/clonet.fish +++ b/functions/clonet.fish @@ -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 diff --git a/functions/detach.fish b/functions/detach.fish index 997e511..cf20ae5 100644 --- a/functions/detach.fish +++ b/functions/detach.fish @@ -4,6 +4,9 @@ # CATEGORY # 08-terminal-management # +# DEPENDENCIES +# nohup +# # SYNOPSIS # detach [-h] [--version] [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 diff --git a/functions/fast-cli.fish b/functions/fast-cli.fish index ecd9b6f..08fc306 100644 --- a/functions/fast-cli.fish +++ b/functions/fast-cli.fish @@ -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 diff --git a/functions/gitui.fish b/functions/gitui.fish index fa488cf..c942a42 100644 --- a/functions/gitui.fish +++ b/functions/gitui.fish @@ -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' - command gitui -t frappe.ron $argv + 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 diff --git a/functions/lock.fish b/functions/lock.fish index dcb0785..895a441 100644 --- a/functions/lock.fish +++ b/functions/lock.fish @@ -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 diff --git a/functions/play-media.fish b/functions/play-media.fish index f0c13f5..6332ee2 100644 --- a/functions/play-media.fish +++ b/functions/play-media.fish @@ -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 ] diff --git a/functions/ports.fish b/functions/ports.fish index 7b2f35a..7c59211 100644 --- a/functions/ports.fish +++ b/functions/ports.fish @@ -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 diff --git a/functions/screensleep.fish b/functions/screensleep.fish index ba1e18b..ddbafc5 100644 --- a/functions/screensleep.fish +++ b/functions/screensleep.fish @@ -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 \ diff --git a/functions/split.fish b/functions/split.fish index c225fdb..7de0544 100644 --- a/functions/split.fish +++ b/functions/split.fish @@ -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 diff --git a/functions/spwin.fish b/functions/spwin.fish index d01fae0..e327a8a 100644 --- a/functions/spwin.fish +++ b/functions/spwin.fish @@ -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 diff --git a/functions/steam-dl.fish b/functions/steam-dl.fish index 5223a2d..c7a6818 100644 --- a/functions/steam-dl.fish +++ b/functions/steam-dl.fish @@ -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 diff --git a/functions/tab.fish b/functions/tab.fish index a5c9a8b..d57ea76 100644 --- a/functions/tab.fish +++ b/functions/tab.fish @@ -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 diff --git a/functions/wake-lock.fish b/functions/wake-lock.fish index 0f11920..50ce7e5 100644 --- a/functions/wake-lock.fish +++ b/functions/wake-lock.fish @@ -4,6 +4,9 @@ # CATEGORY # 14-miscellaneous # +# DEPENDENCIES +# systemd-inhibit +# # SYNOPSIS # wake-lock [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