From 23420b3235ff361d84cd8b6fd2cb85f81557d304 Mon Sep 17 00:00:00 2001 From: Rootiest Date: Tue, 8 Sep 2026 01:11:49 -0400 Subject: [PATCH 1/3] fix(functions): split dops.fish into dops and docker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit dops.fish defined `docker`, not `dops`. dops was never defined; docker was only conditionally defined as a side effect of the failed dops autoload, so its behavior could silently change mid-session. See JOB-BRIEF-FINDINGS.md §1. - functions/dops.fish now defines dops: a real enhanced `docker ps` listing (custom Names/Image/Status/Ports table), with its own --help. - functions/docker.fish is a new file holding the ps-redirect wrapper, fixed to actually call dops (previously called the still-undefined dops from inside itself). - Bare `docker` with no arguments no longer falls through an if-with-no-else (the fish false-zero, AGENTS.md standing gotcha #5) and does nothing; it now runs the real docker binary, which prints its own usage. - tests/functional.fish: updated the now-stale comment explaining why the help-flag check resolves the real function name instead of the file stem. --- functions/docker.fish | 41 +++++++++++++++++++++++++++++++++++++++++ functions/dops.fish | 33 +++++++++++++++++---------------- tests/functional.fish | 5 +++-- 3 files changed, 61 insertions(+), 18 deletions(-) create mode 100644 functions/docker.fish diff --git a/functions/docker.fish b/functions/docker.fish new file mode 100644 index 0000000..52c3115 --- /dev/null +++ b/functions/docker.fish @@ -0,0 +1,41 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later + +# CATEGORY +# 12-ai-and-developer-tools +# +# DEPENDENCIES +# dops +# +# SYNOPSIS +# docker [subcommand] [args...] +# +# DESCRIPTION +# Wrapper for docker that intercepts the ps subcommand and redirects it to +# the dops function for enhanced container listing. All other subcommands, +# and a bare invocation with no subcommand, are passed through to the real +# docker binary. +# +# ARGUMENTS +# subcommand Docker subcommand (ps is redirected to dops) +# args... Arguments forwarded to docker or dops +# +# EXIT STATUS +# Exit status of dops (for ps), or of the real docker binary otherwise +# +# EXAMPLE +# docker ps +# docker +function docker --description 'Execute docker, redirecting ps to the enhanced dops listing' + if test -z "$argv[1]" + command docker + return + end + + switch $argv[1] + case ps + dops $argv[2..-1] + case '*' + command docker $argv[1..-1] + end +end diff --git a/functions/dops.fish b/functions/dops.fish index 36703a4..b1b5422 100644 --- a/functions/dops.fish +++ b/functions/dops.fish @@ -4,27 +4,28 @@ # CATEGORY # 12-ai-and-developer-tools # +# DEPENDENCIES +# docker +# # SYNOPSIS -# docker [subcommand] [args...] +# dops [args...] # # DESCRIPTION -# Wrapper for docker that intercepts the ps subcommand and redirects it to -# the dops function for enhanced container listing. All other subcommands are -# passed through to the real docker binary. +# Enhanced container listing: runs docker ps with a clean custom table +# (Names, Image, Status, Ports) instead of docker's noisier default +# columns. Extra arguments (e.g. -a) are forwarded to docker ps. # # ARGUMENTS -# subcommand Docker subcommand (ps is redirected to dops) -# args... Arguments forwarded to docker or dops +# args... Arguments forwarded to `docker ps` +# +# EXIT STATUS +# Exit status of `docker ps` # # EXAMPLE -# docker ps -function docker --description 'Execute docker' - if test -n "$argv[1]" - switch $argv[1] - case ps - dops $argv[2..-1] - case '*' - command docker $argv[1..-1] - end - end +# dops +# dops -a +function dops --description 'Enhanced, formatted docker ps listing' + __fish_help_header (status current-function) $argv; and return 0 + + command docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}' $argv end diff --git a/tests/functional.fish b/tests/functional.fish index 759188b..beb73bf 100644 --- a/tests/functional.fish +++ b/tests/functional.fish @@ -316,8 +316,9 @@ function test_every_user_facing_function_has_help # Published == carries a `# CATEGORY` block, matching # manualtools.parse_functions. contains -- "# CATEGORY" (string trim -- $lines); or continue - # Resolve the real defined name; the file stem can disagree - # (dops.fish defines `docker` -- see JOB-BRIEF-FINDINGS.md §1). + # Resolve the real defined name; the file stem can disagree with it + # (formerly dops.fish defined `docker` -- see JOB-BRIEF-FINDINGS.md + # §1, fixed by splitting it into dops.fish and docker.fish). set -l name (string match -rg '^\s*function\s+(\S+)' -- $lines)[1] test -n "$name"; or continue set name (string trim -c "'\"" -- $name) -- 2.54.0 From 3aa462a2b872af6dd2e40d73edb3609d032af6a7 Mon Sep 17 00:00:00 2001 From: Rootiest Date: Tue, 8 Sep 2026 01:11:56 -0400 Subject: [PATCH 2/3] style(functions): remove blank line in sponge_filter_secrets.fish header MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The man-page comment header was separated from the function line by a blank line -- the only file in functions/ with that gap. Cosmetic, no runtime effect (manualtools and the help-flag renderer both tolerate it by walking past a blank separator). See JOB-BRIEF-FINDINGS.md §2; the renderer's tolerance for this case is left in place deliberately, it is not dead code. --- functions/sponge_filter_secrets.fish | 1 - 1 file changed, 1 deletion(-) diff --git a/functions/sponge_filter_secrets.fish b/functions/sponge_filter_secrets.fish index 509fc6d..da7d374 100644 --- a/functions/sponge_filter_secrets.fish +++ b/functions/sponge_filter_secrets.fish @@ -31,7 +31,6 @@ # EXAMPLE # # Register with sponge (done automatically by conf.d/sponge_privacy.fish): # set -U -a sponge_filters sponge_filter_secrets - function sponge_filter_secrets --argument-names command # Find all exported variables with security-sensitive names set -l sensitive_vars (set --names --export | string match --regex -- \ -- 2.54.0 From dccf897c9f360f120c38297a081d6af97f6a1437 Mon Sep 17 00:00:00 2001 From: Rootiest Date: Tue, 8 Sep 2026 01:12:04 -0400 Subject: [PATCH 3/3] docs(functions): add missing EXIT STATUS header docs Fills the gaps recorded in JOB-BRIEF-FINDINGS.md for the functions converted to header-driven --help: 16 argument-less functions gain an EXIT STATUS section (check_fish_deps, claude-docs, claude-pr, cleanup, fast, fzf-update, gip, gip4, hist, limine-edit, lock, ports, screensleep, steam-dl, swapstat, tmux-clean), and 8 functions that already document ARGUMENTS gain EXIT STATUS too (lD, lsr, lss, lstree, lt, ltr, lx, qr). Not touched: gip6, ld, parur, sudo-toggle, upgrade, the JOB-BRIEF's 'missing ARGUMENTS' group. Re-checked their bodies against that claim -- none of the five take a positional argument ($argv only appears forwarded to the --help check), so an ARGUMENTS section would document something that doesn't exist. All five already have EXIT STATUS. --- functions/check_fish_deps.fish | 3 +++ functions/claude-docs.fish | 3 +++ functions/claude-pr.fish | 3 +++ functions/cleanup.fish | 4 ++++ functions/fast.fish | 3 +++ functions/fzf-update.fish | 4 ++++ functions/gip.fish | 3 +++ functions/gip4.fish | 3 +++ functions/hist.fish | 4 ++++ functions/lD.fish | 3 +++ functions/limine-edit.fish | 3 +++ functions/lock.fish | 3 +++ functions/lsr.fish | 3 +++ functions/lss.fish | 3 +++ functions/lstree.fish | 3 +++ functions/lt.fish | 3 +++ functions/ltr.fish | 3 +++ functions/lx.fish | 3 +++ functions/ports.fish | 3 +++ functions/qr.fish | 3 +++ functions/screensleep.fish | 3 +++ functions/steam-dl.fish | 3 +++ functions/swapstat.fish | 3 +++ functions/tmux-clean.fish | 3 +++ 24 files changed, 75 insertions(+) diff --git a/functions/check_fish_deps.fish b/functions/check_fish_deps.fish index fd24581..3be6cb5 100644 --- a/functions/check_fish_deps.fish +++ b/functions/check_fish_deps.fish @@ -11,6 +11,9 @@ # Backwards-compatibility wrapper that delegates to fish-deps status to # report which fish shell dependencies are installed or missing. # +# EXIT STATUS +# Exit status of `fish-deps status` +# # EXAMPLE # check_fish_deps function check_fish_deps --description 'Check all fish-related dependencies' diff --git a/functions/claude-docs.fish b/functions/claude-docs.fish index 1d7717b..699d814 100644 --- a/functions/claude-docs.fish +++ b/functions/claude-docs.fish @@ -12,6 +12,9 @@ # README.md, ensuring all features and examples are accurate and pruning # obsolete content. # +# EXIT STATUS +# Exit status of the `claude` invocation +# # EXAMPLE # claude-docs function claude-docs --description 'Claude-code: Sync README with recent changes' diff --git a/functions/claude-pr.fish b/functions/claude-pr.fish index d38f36e..02bd88c 100644 --- a/functions/claude-pr.fish +++ b/functions/claude-pr.fish @@ -12,6 +12,9 @@ # branch, write a Conventional Commit, run verification, push, and open a # pull request with a manual verification checklist. # +# EXIT STATUS +# Exit status of the `claude` invocation +# # EXAMPLE # claude-pr function claude-pr --description 'Claude-code: New branch, commit, push, and PR' diff --git a/functions/cleanup.fish b/functions/cleanup.fish index b908ee7..17e7612 100644 --- a/functions/cleanup.fish +++ b/functions/cleanup.fish @@ -11,6 +11,10 @@ # Identifies and removes Arch Linux orphan packages using pacman. Logs # package names and versions to ~/.removed_orphans before removal. # +# EXIT STATUS +# 0 No orphans found, or orphans removed successfully +# Nonzero `sudo pacman -Rns` failed +# # EXAMPLE # cleanup function cleanup --description 'Log orphans to ~/.removed_orphans and remove them' diff --git a/functions/fast.fish b/functions/fast.fish index 7fec3cb..59d8fe6 100644 --- a/functions/fast.fish +++ b/functions/fast.fish @@ -33,6 +33,9 @@ # Displays a styled message indicating that the fast command is unavailable # and suggests using fast-cli instead. # +# EXIT STATUS +# 0 Always +# # EXAMPLE # fast function fast --description 'Placeholder for future fast utility' diff --git a/functions/fzf-update.fish b/functions/fzf-update.fish index 5297dc8..b0c5ae9 100644 --- a/functions/fzf-update.fish +++ b/functions/fzf-update.fish @@ -11,6 +11,10 @@ # Installs or upgrades fzf from git HEAD into ~/.fzf. Pulls the latest # changes if ~/.fzf already exists, or clones the repository if not. # +# EXIT STATUS +# 0 fzf installed or updated successfully +# Nonzero git or the fzf install script failed +# # EXAMPLE # fzf-update function fzf-update --description 'Install or upgrade fzf from git HEAD' diff --git a/functions/gip.fish b/functions/gip.fish index cc73b11..bbbd9dd 100644 --- a/functions/gip.fish +++ b/functions/gip.fish @@ -11,6 +11,9 @@ # Fetches and prints both the public IPv4 and IPv6 addresses using # icanhazip.com. Shows "Not detected" for any address that times out. # +# EXIT STATUS +# 0 Always (network failures print "Not detected" instead of failing) +# # EXAMPLE # gip function gip --description 'Show all public IP addresses' diff --git a/functions/gip4.fish b/functions/gip4.fish index 5431be4..a8f54b4 100644 --- a/functions/gip4.fish +++ b/functions/gip4.fish @@ -10,6 +10,9 @@ # DESCRIPTION # Fetches and prints the machine's public IPv4 address using icanhazip.com. # +# EXIT STATUS +# Exit status of curl +# # EXAMPLE # gip4 function gip4 --wraps='curl' --description 'Get public IPv4 address' diff --git a/functions/hist.fish b/functions/hist.fish index 4536efa..56ba689 100644 --- a/functions/hist.fish +++ b/functions/hist.fish @@ -14,6 +14,10 @@ # Searches fish history interactively using fzf, inserts the selected command # into the command line, and copies it to the clipboard via wl-copy. # +# EXIT STATUS +# 0 Command selected and inserted, or fzf was cancelled +# 1 Disabled by __fish_config_op_integrations +# # EXAMPLE # hist function hist --description 'Search fish history and put it in the prompt' diff --git a/functions/lD.fish b/functions/lD.fish index 9849199..2a78257 100644 --- a/functions/lD.fish +++ b/functions/lD.fish @@ -14,6 +14,9 @@ # ARGUMENTS # args... Arguments forwarded to the listing command # +# EXIT STATUS +# Exit status of eza, lsd, or ls, whichever ran +# # EXAMPLE # lD ~/projects function lD --description 'List directories only' diff --git a/functions/limine-edit.fish b/functions/limine-edit.fish index 9f3b502..f130e35 100644 --- a/functions/limine-edit.fish +++ b/functions/limine-edit.fish @@ -13,6 +13,9 @@ # files tracked by sbctl. Combines the edit and sign steps into a single # command. # +# EXIT STATUS +# 0 Always (individual step failures are not propagated) +# # EXAMPLE # limine-edit function limine-edit --description 'Safely edit and re-verify Limine configuration' diff --git a/functions/lock.fish b/functions/lock.fish index 302d29d..16f4043 100644 --- a/functions/lock.fish +++ b/functions/lock.fish @@ -10,6 +10,9 @@ # DESCRIPTION # Locks the current desktop session using loginctl lock-session. # +# EXIT STATUS +# Exit status of `loginctl lock-session` +# # EXAMPLE # lock function lock --wraps='loginctl' --description 'alias lock=loginctl' diff --git a/functions/lsr.fish b/functions/lsr.fish index d680556..a51bbe8 100644 --- a/functions/lsr.fish +++ b/functions/lsr.fish @@ -14,6 +14,9 @@ # ARGUMENTS # args... Arguments forwarded to the listing command # +# EXIT STATUS +# Exit status of eza, lsd, or ls, whichever ran +# # EXAMPLE # lsr ~/projects function lsr --description 'Reversed time-sorted listing' diff --git a/functions/lss.fish b/functions/lss.fish index d0d09a8..7118254 100644 --- a/functions/lss.fish +++ b/functions/lss.fish @@ -14,6 +14,9 @@ # ARGUMENTS # args... Arguments forwarded to the listing command # +# EXIT STATUS +# Exit status of eza, lsd, or ls, whichever ran +# # EXAMPLE # lss ~/downloads function lss --description 'Size-sorted listing' diff --git a/functions/lstree.fish b/functions/lstree.fish index 7c1be9f..f74da5d 100644 --- a/functions/lstree.fish +++ b/functions/lstree.fish @@ -14,6 +14,9 @@ # ARGUMENTS # args... Arguments forwarded to the listing command # +# EXIT STATUS +# Exit status of eza, lsd, or ls, whichever ran +# # EXAMPLE # lstree ~/projects/myapp function lstree --description 'Full recursive tree listing' diff --git a/functions/lt.fish b/functions/lt.fish index b16a526..29ca192 100644 --- a/functions/lt.fish +++ b/functions/lt.fish @@ -14,6 +14,9 @@ # ARGUMENTS # args... Arguments forwarded to the listing command # +# EXIT STATUS +# Exit status of eza, lsd, or ls, whichever ran +# # EXAMPLE # lt ~/projects function lt --description 'Tree listing, depth 2' diff --git a/functions/ltr.fish b/functions/ltr.fish index 35d6910..c9d34e0 100644 --- a/functions/ltr.fish +++ b/functions/ltr.fish @@ -15,6 +15,9 @@ # ARGUMENTS # args... Arguments forwarded to the listing command # +# EXIT STATUS +# Exit status of eza, lsd, or ls, whichever ran +# # EXAMPLE # ltr ~/projects function ltr --description 'Reversed time-sorted listing' diff --git a/functions/lx.fish b/functions/lx.fish index f467d11..ea10d4d 100644 --- a/functions/lx.fish +++ b/functions/lx.fish @@ -14,6 +14,9 @@ # ARGUMENTS # args... Arguments forwarded to the listing command # +# EXIT STATUS +# Exit status of eza, lsd, or ls, whichever ran +# # EXAMPLE # lx ~/projects function lx --description 'Extension-sorted listing' diff --git a/functions/ports.fish b/functions/ports.fish index 6836c2c..c57e7ec 100644 --- a/functions/ports.fish +++ b/functions/ports.fish @@ -11,6 +11,9 @@ # Lists all active TCP listeners on the system using lsof, showing # port numbers and addresses without hostname resolution. # +# EXIT STATUS +# Exit status of `lsof` +# # EXAMPLE # ports function ports --wraps='sudo' --description 'Show active network listeners' diff --git a/functions/qr.fish b/functions/qr.fish index 50af5d7..268c7be 100644 --- a/functions/qr.fish +++ b/functions/qr.fish @@ -15,6 +15,9 @@ # ARGUMENTS # text... Text to encode; reads from stdin if omitted # +# EXIT STATUS +# Exit status of qrencode, or curl if qrencode is unavailable +# # EXAMPLE # qr "https://example.com" # echo "hello" | qr diff --git a/functions/screensleep.fish b/functions/screensleep.fish index 0bb4442..4496031 100644 --- a/functions/screensleep.fish +++ b/functions/screensleep.fish @@ -11,6 +11,9 @@ # Turns off the display after a 1-second delay by invoking the KDE # PowerDevil "Turn Off Screen" global shortcut via busctl. # +# EXIT STATUS +# Exit status of `busctl` +# # EXAMPLE # screensleep function screensleep --description 'Turn off the display using KDE PowerDevil' diff --git a/functions/steam-dl.fish b/functions/steam-dl.fish index 7c7ab1c..24583bd 100644 --- a/functions/steam-dl.fish +++ b/functions/steam-dl.fish @@ -11,6 +11,9 @@ # Launches Steam with systemd-inhibit to prevent the system from idling # or sleeping during active downloads. # +# EXIT STATUS +# Exit status of `steam` (via systemd-inhibit) +# # EXAMPLE # steam-dl function steam-dl --description 'Run Steam while inhibiting system sleep' diff --git a/functions/swapstat.fish b/functions/swapstat.fish index f379d4c..0ffa51a 100644 --- a/functions/swapstat.fish +++ b/functions/swapstat.fish @@ -12,6 +12,9 @@ # zRAM compression ratio, zRAM device details (via zramctl), and # active swap priority (via swapon). # +# EXIT STATUS +# 0 Always +# # EXAMPLE # swapstat function swapstat --description 'View colorized zRAM and swappiness status' diff --git a/functions/tmux-clean.fish b/functions/tmux-clean.fish index c31765e..6d878e8 100644 --- a/functions/tmux-clean.fish +++ b/functions/tmux-clean.fish @@ -11,6 +11,9 @@ # Kills all detached (unattached) tmux sessions, leaving any currently # attached sessions running. # +# EXIT STATUS +# 0 Always +# # EXAMPLE # tmux-clean function tmux-clean --description 'Kill all tmux sessions except the current one' -- 2.54.0