diff --git a/conf.d/cheat.fish b/completions/cheat.fish similarity index 100% rename from conf.d/cheat.fish rename to completions/cheat.fish diff --git a/conf.d/tailscale.fish b/completions/tailscale.fish similarity index 93% rename from conf.d/tailscale.fish rename to completions/tailscale.fish index dce3602..b682131 100644 --- a/conf.d/tailscale.fish +++ b/completions/tailscale.fish @@ -228,16 +228,15 @@ function __tailscale_prepare_completions return 0 end -# Since Fish completions are only loaded once the user triggers them, we trigger them ourselves -# so we can properly delete any completions provided by another script. -# Only do this if the program can be found, or else fish may print some errors; besides, -# the existing completions will only be loaded if the program can be found. -if type -q "tailscale" - # The space after the program name is essential to trigger completion for the program - # and not completion of the program name itself. - # Also, we use '> /dev/null 2>&1' since '&>' is not supported in older versions of fish. - complete --do-complete "tailscale " > /dev/null 2>&1 -end +# REMOVED (2026-09-07): Cobra's self-priming block — +# if type -q "tailscale"; complete --do-complete "tailscale " >/dev/null 2>&1; end +# It existed to force any pre-existing tailscale completions to load so the +# `complete -c tailscale -e` below could erase them. From completions/ it has +# no job: fish autoloads only the FIRST match on $fish_complete_path, and +# $__fish_config_dir/completions precedes /usr/share/fish/vendor_completions.d, +# so the vendor file is never sourced and there is nothing to erase. It also +# executed the tailscale binary at startup. Verified: completion output is +# byte-identical with and without it. See AGENTS/specs/2026-09-07-startup-latency-design.md D2. # Remove any pre-existing completions for the program since we will be handling all of them. complete -c tailscale -e diff --git a/conf.d/abbr.fish b/conf.d/abbr.fish index 5771e32..b8016d1 100644 --- a/conf.d/abbr.fish +++ b/conf.d/abbr.fish @@ -12,6 +12,9 @@ # site abbr-integrations: integrations/terminal-abbrs # site abbr-overrides: overrides/key-bindings +# Abbreviations only expand in the line editor; a script can never use one. +status is-interactive; or return + # Neovim # @category Editors # @desc nvim diff --git a/conf.d/auto-pull.fish b/conf.d/auto-pull.fish index 852559a..db4f7f5 100644 --- a/conf.d/auto-pull.fish +++ b/conf.d/auto-pull.fish @@ -13,6 +13,11 @@ # # Manage the registry with: auto-pull add / remove / list / status +# Registers an --on-variable PWD handler that backgrounds a git fetch. In a +# script that cd's, that is both wasted work and AGENTS.md Task #4's +# credential-prompt hazard fired from a background job. +status is-interactive; or return + # C2 guard: when auto-execution is disabled, do not register the handler. __fish_config_op_enabled (status basename); or exit diff --git a/conf.d/bash_expands.fish b/conf.d/bash_expands.fish index d81dc91..89c5bf7 100644 --- a/conf.d/bash_expands.fish +++ b/conf.d/bash_expands.fish @@ -7,6 +7,10 @@ # Provides bash-style history expansion functions for abbreviations. # These functions are gated by the C3 overrides switch. +# The six expand_* functions are reachable only through abbr --function +# (conf.d/abbr.fish:677-697), i.e. only during interactive expansion. +status is-interactive; or return + # Execute expand_bang_all function expand_bang_all --description 'Execute expand_bang_all' # Opinionated guard (C3): no expansion when overrides are disabled. diff --git a/conf.d/key_bindings.fish b/conf.d/key_bindings.fish index 588e073..e6143ab 100644 --- a/conf.d/key_bindings.fish +++ b/conf.d/key_bindings.fish @@ -47,6 +47,10 @@ # This allows for rapid-fire math without leaving the current shell. # ────────────────────────────────────────────────────────────────────── +# Defines only fish_user_key_bindings, which fish calls from the interactive +# reader and nowhere else. +status is-interactive; or return + function fish_user_key_bindings # Custom key chords are opinionated (C3 overrides); skip them entirely diff --git a/conf.d/logging-events.fish b/conf.d/logging-events.fish index 892f518..53e1287 100644 --- a/conf.d/logging-events.fish +++ b/conf.d/logging-events.fish @@ -13,6 +13,12 @@ # solely in functions/ are never registered and their --on-variable triggers # never fire. +# Calls __fish_config_sync_logging at every shell start, which mkdir+touches +# the C5 sentinel on disk. Its only consumers — the Kitty watcher and the +# paru/yay wrappers — are interactive-context; every interactive shell still +# refreshes it. +status is-interactive; or return + function __fish_config_logging_changed --on-variable __fish_config_op_logging \ --description 'C5 event handler: sync logging state when __fish_config_op_logging changes' __fish_config_sync_logging diff --git a/conf.d/paru-wrapper.fish b/conf.d/paru-wrapper.fish index bef1e54..e5e629e 100644 --- a/conf.d/paru-wrapper.fish +++ b/conf.d/paru-wrapper.fish @@ -10,6 +10,10 @@ # site paru-autoexec: autoexec/pkg-wrappers # site paru-logging: logging/pkg-logs +# Defines nothing; its only effect is generating ~/.local/bin/paru, an +# idempotent write every interactive session already performs. +status is-interactive; or return + # Auto-generating a wrapper in ~/.local/bin is opinionated (C2 auto-exec). # Wrapper generation is also gated by C5 (Logging & Capture). __fish_config_op_enabled (status basename) paru-autoexec; or return diff --git a/conf.d/starship.fish b/conf.d/starship.fish index fc9673e..adee42b 100644 --- a/conf.d/starship.fish +++ b/conf.d/starship.fish @@ -9,6 +9,10 @@ # Without starship, fish's built-in prompt already emits OSC 133;A # on the prompt line itself, so no wrapper is needed. +# Defines fish_prompt; no script renders a prompt. Checked before the +# op-guard so the builtin short-circuits ahead of three function autoloads. +status is-interactive; or return + # Replacing the prompt is opinionated (C3 overrides) __fish_config_op_enabled (status basename); or return diff --git a/conf.d/theme.fish b/conf.d/theme.fish index 5944728..26bc834 100644 --- a/conf.d/theme.fish +++ b/conf.d/theme.fish @@ -20,6 +20,11 @@ if not __fish_config_op_enabled (status basename) return end +# Below the cleanup block on purpose: that branch erases a stale universal +# FZF_DEFAULT_OPTS and must keep running wherever it runs today. Everything +# past here is fish_color_* for the syntax highlighter, interactive-only. +status is-interactive; or return + # ────────────────────── Syntax highlighting colors ────────────────────── set --global fish_color_autosuggestion 6c7086 set --global fish_color_cancel f38ba8 diff --git a/conf.d/tricks.fish b/conf.d/tricks.fish index a3a5474..6c82fb1 100644 --- a/conf.d/tricks.fish +++ b/conf.d/tricks.fish @@ -18,20 +18,32 @@ if test -f ~/.fish_profile source ~/.fish_profile end -# Append unique directories to $PATH (fish_add_path handles duplicates automatically) -fish_add_path ~/.local/bin -fish_add_path ~/Applications/depot_tools +# This file is sourced twice per shell on CachyOS (once by the conf.d +# autoload, once forced by config.fish to re-win over the distro's own +# tricks.fish). The PATH/MANPAGER setup below doesn't need to repeat on +# the second pass -- only the functions/aliases further down do, since +# those are what re-assert over the distro config. Gate the expensive +# calls (fish_add_path, type -q bat) behind a once-per-session guard. +# ponytail: per-session guard, not per-value; if this file grows more +# expensive one-time setup, extend the same guard rather than adding more. +if not set -q __fish_config_tricks_env_applied + set -g __fish_config_tricks_env_applied 1 -# Expose user-local man pages -if not contains ~/.local/share/man $MANPATH - set -gx MANPATH ~/.local/share/man $MANPATH -end + # Append unique directories to $PATH (fish_add_path handles duplicates automatically) + fish_add_path ~/.local/bin + fish_add_path ~/Applications/depot_tools -# Format man pages using bat (only if bat is installed) -# Overriding $MANPAGER is opinionated (C3 overrides) -if type -q bat; and __fish_config_op_enabled (status basename) tricks-manpager - set -gx MANROFFOPT -c - set -gx MANPAGER "sh -c 'col -bx | bat -l man -p'" + # Expose user-local man pages + if not contains ~/.local/share/man $MANPATH + set -gx MANPATH ~/.local/share/man $MANPATH + end + + # Format man pages using bat (only if bat is installed) + # Overriding $MANPAGER is opinionated (C3 overrides) + if type -q bat; and __fish_config_op_enabled (status basename) tricks-manpager + set -gx MANROFFOPT -c + set -gx MANPAGER "sh -c 'col -bx | bat -l man -p'" + end end # Set settings for https://github.com/franciscolourenco/done diff --git a/conf.d/wakatime.fish b/conf.d/wakatime.fish index db97a43..e4568bf 100644 --- a/conf.d/wakatime.fish +++ b/conf.d/wakatime.fish @@ -9,6 +9,10 @@ # site wakatime-autoexec: autoexec/telemetry # site wakatime-hook: integrations/notifications +# Registers a fish_postexec handler; that event is emitted only by the +# interactive reader, so the handler is dead weight in a script. +status is-interactive; or return + # Local modification: opinionated guard (AGENTS.md Task #3). WakaTime # reporting is classified under both C2 auto-execution and C4 integrations; # disabling either category skips registering the hook. diff --git a/conf.d/yay-wrapper.fish b/conf.d/yay-wrapper.fish index 53da589..6f43360 100644 --- a/conf.d/yay-wrapper.fish +++ b/conf.d/yay-wrapper.fish @@ -10,6 +10,10 @@ # site yay-autoexec: autoexec/pkg-wrappers # site yay-logging: logging/pkg-logs +# Defines nothing; its only effect is generating ~/.local/bin/yay, an +# idempotent write every interactive session already performs. +status is-interactive; or return + # Auto-generating a wrapper in ~/.local/bin is opinionated (C2 auto-exec). # Wrapper generation is also gated by C5 (Logging & Capture). __fish_config_op_enabled (status basename) yay-autoexec; or return diff --git a/docs/fish-config.md b/docs/fish-config.md index 2dccaed..5edcf39 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -46,7 +46,6 @@ The configuration uses a structured file tree: ├── conf.d/ │ ├── abbr.fish All abbreviations │ ├── autopair.fish Auto-pair brackets and quotes - │ ├── cheat.fish cheat.sh tab completions │ ├── done.fish Desktop notifications for long commands │ ├── first_run.fish One-time init: Fisher bootstrap, theme │ ├── key_bindings.fish Custom key bindings and Vi mode @@ -58,14 +57,13 @@ The configuration uses a structured file tree: │ ├── zellij-logging.fish C5 fish_exit handler for zellij │ ├── sponge_privacy.fish Sponge privacy patterns │ ├── starship.fish fish_prompt shell-integration markers - │ ├── tailscale.fish Tailscale CLI tab completions │ ├── theme.fish Catppuccin syntax highlight colors │ ├── tricks.fish PATH, bang-bang helpers, bat man pages │ ├── wakatime.fish WakaTime shell hook │ ├── yay-wrapper.fish Auto-generates yay logging wrapper │ └── zoxide.fish Zoxide z/zi integration; overrides cd ├── functions/ Custom functions, one per file - ├── completions/ Tab completion scripts + ├── completions/ Tab completion scripts, autoloaded on demand ├── integrations/ │ └── fzf.fish FZF Catppuccin theme and key bindings ├── scripts/ @@ -245,7 +243,8 @@ Every shell command is reported to WakaTime for time-tracking. Set ### Tailscale -Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`. +Full tab completion for the `tailscale` CLI is provided via +`completions/tailscale.fish`, autoloaded on the first `tailscale`. ### Done Notifications diff --git a/docs/manual/01-configuration-variables.md b/docs/manual/01-configuration-variables.md index f37299d..b898cbd 100644 --- a/docs/manual/01-configuration-variables.md +++ b/docs/manual/01-configuration-variables.md @@ -118,7 +118,8 @@ Every shell command is reported to WakaTime for time-tracking. Set ### Tailscale -Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`. +Full tab completion for the `tailscale` CLI is provided via +`completions/tailscale.fish`, autoloaded on the first `tailscale`. ### Done Notifications diff --git a/docs/manual/index.md b/docs/manual/index.md index 3017947..5c4d402 100644 --- a/docs/manual/index.md +++ b/docs/manual/index.md @@ -35,7 +35,6 @@ The configuration uses a structured file tree: ├── conf.d/ │ ├── abbr.fish All abbreviations │ ├── autopair.fish Auto-pair brackets and quotes - │ ├── cheat.fish cheat.sh tab completions │ ├── done.fish Desktop notifications for long commands │ ├── first_run.fish One-time init: Fisher bootstrap, theme │ ├── key_bindings.fish Custom key bindings and Vi mode @@ -47,14 +46,13 @@ The configuration uses a structured file tree: │ ├── zellij-logging.fish C5 fish_exit handler for zellij │ ├── sponge_privacy.fish Sponge privacy patterns │ ├── starship.fish fish_prompt shell-integration markers - │ ├── tailscale.fish Tailscale CLI tab completions │ ├── theme.fish Catppuccin syntax highlight colors │ ├── tricks.fish PATH, bang-bang helpers, bat man pages │ ├── wakatime.fish WakaTime shell hook │ ├── yay-wrapper.fish Auto-generates yay logging wrapper │ └── zoxide.fish Zoxide z/zi integration; overrides cd ├── functions/ Custom functions, one per file - ├── completions/ Tab completion scripts + ├── completions/ Tab completion scripts, autoloaded on demand ├── integrations/ │ └── fzf.fish FZF Catppuccin theme and key bindings ├── scripts/ diff --git a/functions/__fish_config_sync_logging.fish b/functions/__fish_config_sync_logging.fish index 2d61e86..493a383 100644 --- a/functions/__fish_config_sync_logging.fish +++ b/functions/__fish_config_sync_logging.fish @@ -28,84 +28,38 @@ function __fish_config_sync_logging --description 'Sync C5 logging state: sentin set config_home "$HOME/.config" end set -l sentinel "$config_home/fish/.logging_disabled" - set -l paru_wrapper "$HOME/.local/bin/paru" - set -l yay_wrapper "$HOME/.local/bin/yay" - set -l wrapper_version 1 if __fish_config_op_enabled (status current-function) - # Logging enabled: remove sentinel and regenerate wrappers if binaries exist + # Logging enabled: remove sentinel rm -f $sentinel # Restart tmux pipe-pane for the current pane if inside tmux _tmux_pipe_log - - if test -x /usr/bin/paru - mkdir -p (dirname $paru_wrapper) - printf '%s\n' \ - '#!/usr/bin/env bash' \ - "# paru-wrapper-version: $wrapper_version" \ - '# Auto-generated by conf.d/paru-wrapper.fish — do not edit by hand.' \ - '# Tees paru output to a timestamped log file and prunes old ones.' \ - 'set -o pipefail' \ - '' \ - 'log_dir="${SCROLLBACK_HISTORY_DIR:-$HOME/.terminal_history}"' \ - 'mkdir -p "$log_dir"' \ - 'log_file="$log_dir/paru_$(date +%Y-%m-%d_%H-%M-%S).log"' \ - '' \ - '/usr/bin/paru "$@" 2>&1 | tee "$log_file"' \ - '' \ - 'max_files="${SCROLLBACK_HISTORY_MAX_FILES:-100}"' \ - 'mapfile -t logs < <(ls -1t "$log_dir"/paru_*.log 2>/dev/null)' \ - 'excess=$(( ${#logs[@]} - max_files ))' \ - 'for (( i = ${#logs[@]} - 1; i >= ${#logs[@]} - excess && i >= 0; i-- )); do' \ - ' rm -f "${logs[$i]}"' \ - 'done' \ - >$paru_wrapper - chmod +x $paru_wrapper - end - - if test -x /usr/bin/yay - mkdir -p (dirname $yay_wrapper) - printf '%s\n' \ - '#!/usr/bin/env bash' \ - "# yay-wrapper-version: $wrapper_version" \ - '# Auto-generated by conf.d/yay-wrapper.fish — do not edit by hand.' \ - '# Tees yay output to a timestamped log file and prunes old ones.' \ - 'set -o pipefail' \ - '' \ - 'log_dir="${SCROLLBACK_HISTORY_DIR:-$HOME/.terminal_history}"' \ - 'mkdir -p "$log_dir"' \ - 'log_file="$log_dir/yay_$(date +%Y-%m-%d_%H-%M-%S).log"' \ - '' \ - '/usr/bin/yay "$@" 2>&1 | tee "$log_file"' \ - '' \ - 'max_files="${SCROLLBACK_HISTORY_MAX_FILES:-100}"' \ - 'mapfile -t logs < <(ls -1t "$log_dir"/yay_*.log 2>/dev/null)' \ - 'excess=$(( ${#logs[@]} - max_files ))' \ - 'for (( i = ${#logs[@]} - 1; i >= ${#logs[@]} - excess && i >= 0; i-- )); do' \ - ' rm -f "${logs[$i]}"' \ - 'done' \ - >$yay_wrapper - chmod +x $yay_wrapper - end else - # Logging disabled: create sentinel and remove any generated wrappers + # Logging disabled: create sentinel mkdir -p (dirname $sentinel) touch $sentinel - if test -f $paru_wrapper - and grep -q "# paru-wrapper-version:" $paru_wrapper 2>/dev/null - rm -f $paru_wrapper - end - - if test -f $yay_wrapper - and grep -q "# yay-wrapper-version:" $yay_wrapper 2>/dev/null - rm -f $yay_wrapper - end - # Stop tmux pipe-pane for the current pane if inside tmux if set -q TMUX tmux pipe-pane 2>/dev/null end end + + # Delegate paru/yay wrapper (re)generation and removal to the canonical + # generators. They resolve the real binary via __fish_real_command + # (never /usr/bin-assumed) and independently gate on their own C2/C5 + # keys, so sourcing them here covers both the enabled-regenerate and + # disabled-remove cases without duplicating that logic. Previously this + # function carried its own inferior copy (tee instead of a PTY, no + # progress-bar rendering, hard-coded /usr/bin/paru|yay), which fought + # the canonical generator for the wrapper file on every version-marker + # mismatch. See startup-latency-JOB-BRIEF-FINDINGS.md §2. + # + # Routed through _fish_source_scoped: both files `return` early on + # several guard checks, and a sourced `return` exits the *calling* + # function, which would otherwise abort this function and skip + # whichever of paru/yay hadn't run yet. + _fish_source_scoped "$__fish_config_dir/conf.d/paru-wrapper.fish" + _fish_source_scoped "$__fish_config_dir/conf.d/yay-wrapper.fish" end diff --git a/functions/__fish_help_header.fish b/functions/__fish_help_header.fish new file mode 100644 index 0000000..68920be --- /dev/null +++ b/functions/__fish_help_header.fish @@ -0,0 +1,141 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later + +# SYNOPSIS +# __fish_help_header [args...] +# +# DESCRIPTION +# Prints 's man-page comment header as a help menu on stdout. +# Intended as the first statement of a user-facing function's body: +# +# __fish_help_header (status current-function) $argv; and return 0 +# +# Returns 1 -- printing nothing -- ONLY when args[1] is not a help flag. +# Every other outcome, including an unreadable or headerless source +# file, prints something and returns 0. That asymmetry is load-bearing: +# a return of 1 means "run the real body", and the real body of upgrade +# is `paru -Syu --noconfirm`. A parse failure must never return 1. +# +# Only args[1] is inspected, never the whole list. wake-lock, bkg, +# split and spwin take a command to run as their arguments, so +# scanning all of $argv would make `wake-lock rsync --help` print +# wake-lock's own help instead of running rsync. +# +# The header is read from the caller's source at call time rather than +# from the generated manual, so it cannot go stale between a header +# edit and a docs rebuild. +# +# ARGUMENTS +# name The calling function's name, from (status current-function) +# args... The caller's $argv, forwarded verbatim +# +# EXIT STATUS +# 0 Help was printed, including the degraded fallback +# 1 args[1] is not -h/--help; the caller should carry on +# +# EXAMPLE +# __fish_help_header (status current-function) $argv; and return 0 +# +# NOTES +# Section labels are those of the manual SSOT parser in +# docs/manualtools.py. CATEGORY, COMPONENT and DEPENDENCIES are build +# metadata and are suppressed; SYNOPSIS renders as USAGE and EXAMPLE as +# EXAMPLES. +function __fish_help_header --argument-names name + # First argument only -- see DESCRIPTION. + contains -- "$argv[2]" -h --help; or return 1 + + set -l c_ttl (set_color --bold) + set -l c_sec (set_color --bold brblue) + set -l c_rst (set_color normal) + set -l miss " No documentation header found. Try: help config $name" + + set -l file (functions -D -- $name 2>/dev/null) + if not test -f "$file" + # Quoted: set_color yields an EMPTY LIST under TERM=dumb, and an + # unquoted empty list in a concatenation annihilates the whole + # word -- the title line would silently vanish wherever colour is + # off, which is exactly where a test would be reading it. + echo "$c_ttl$name$c_rst" + echo $miss + return 0 + end + + # Collect the contiguous comment run directly above `function `, + # walking backwards. This resolves multi-header files (fish-deps, gi, + # y) without reimplementing manualtools._block_identity, and is more + # accurate at runtime: in dops.fish it finds the header above + # `function docker` rather than attributing it to the file stem. + # One blank separator line is tolerated -- sponge_filter_secrets.fish + # is the only file that has one, and JOB-BRIEF-FINDINGS.md records it + # so this skip is not mistaken for dead code. + set -l lines (string split \n -- (command cat $file)) + set -l pat '^\s*function\s+'(string escape --style=regex -- $name)'(\s|$)' + set -l start 0 + for i in (seq (count $lines)) + if string match -qr -- $pat $lines[$i] + set start $i + break + end + end + + set -l header + if test $start -gt 1 + set -l j (math $start - 1) + if test -z (string trim -- "$lines[$j]") + set j (math $j - 1) + end + while test $j -ge 1; and string match -q '#*' -- $lines[$j] + set -p header $lines[$j] + set j (math $j - 1) + end + end + + # Render. Comment lines before the first `# LABEL` -- the copyright + # preamble -- carry no label and are dropped, matching + # manualtools._header_blocks. + set -l skip CATEGORY COMPONENT DEPENDENCIES + set -l label "" + set -l out + for line in $header + set -l m (string match -r -- '^#\s+([A-Z][A-Z ]*[A-Z])\s*$' $line) + if set -q m[2] + set label $m[2] + contains -- $label $skip; and continue + set -l shown (string replace SYNOPSIS USAGE -- $label) + set shown (string replace EXAMPLE EXAMPLES -- $shown) + # One blank line before a heading, never two: the header's own + # `#` separator has usually already emitted one. + if set -q out[1]; and test -n (string trim -- "$out[-1]") + set -a out "" + end + set -a out "$c_sec$shown$c_rst" + continue + end + test -n "$label"; or continue + contains -- $label $skip; and continue + set -l body (string sub -s 2 -- $line) + if string match -q ' *' -- $body + set -a out " "(string sub -s 4 -- $body) + else + set -a out (string trim -- $body) + end + end + + # Trim the trailing blank separator, mirroring + # manualtools._trailing_blanks. + while set -q out[-1]; and test -z (string trim -- "$out[-1]") + set -e out[-1] + end + + echo "$c_ttl$name$c_rst" + if test (count $out) -eq 0 + echo $miss + else + # out[1] is always a heading -- a body line cannot precede the + # first label -- so this blank is never doubled. + echo "" + printf '%s\n' $out + end + return 0 +end diff --git a/functions/_fish_source_scoped.fish b/functions/_fish_source_scoped.fish new file mode 100644 index 0000000..41446a8 --- /dev/null +++ b/functions/_fish_source_scoped.fish @@ -0,0 +1,26 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later + +# SYNOPSIS +# _fish_source_scoped +# +# DESCRIPTION +# Sources inside its own function-call boundary. `source` runs +# in the caller's own scope, so a bare `return` in a sourced file -- +# used by several conf.d guards as an early exit -- would otherwise +# unwind whatever function called `source` directly, not just the +# sourced file. Calling through this helper contains it to here. +# +# ARGUMENTS +# file Path to the fish script to source +# +# EXIT STATUS +# 0 File does not exist (nothing to do) +# Exit status of the sourced file otherwise +# +# EXAMPLE +# _fish_source_scoped $__fish_config_dir/conf.d/paru-wrapper.fish +function _fish_source_scoped --argument-names file + test -f $file; or return 0 + source $file +end diff --git a/functions/bd-pull.fish b/functions/bd-pull.fish index 87b60de..0def40d 100644 --- a/functions/bd-pull.fish +++ b/functions/bd-pull.fish @@ -23,6 +23,8 @@ # bd-pull myuser/myproject # bd-pull rootiest/fish-config function bd-pull --description 'Pull new Gitea issues into local Beads and link them' + __fish_help_header (status current-function) $argv; and return 0 + if not set -q argv[1]; echo "Need repo owner/name"; return 1; end if not set -q GITEA_TOKEN; echo "\$GITEA_TOKEN not set"; return 1; end diff --git a/functions/bkg.fish b/functions/bkg.fish index 2fc9927..5bffc67 100644 --- a/functions/bkg.fish +++ b/functions/bkg.fish @@ -23,6 +23,8 @@ # EXAMPLE # bkg firefox function bkg --description 'Execute bkg' + __fish_help_header (status current-function) $argv; and return 0 + # Check if a command was provided as an argument. if test -z "$argv[1]" __fish_palette diff --git a/functions/branch.fish b/functions/branch.fish index 836320d..6143685 100644 --- a/functions/branch.fish +++ b/functions/branch.fish @@ -21,6 +21,8 @@ # EXAMPLE # branch feature/new-ui function branch --description 'Switch to or create a git branch' + __fish_help_header (status current-function) $argv; and return 0 + if not git rev-parse --is-inside-work-tree >/dev/null 2>&1 echo "Not a git repo." return 1 diff --git a/functions/check_fish_deps.fish b/functions/check_fish_deps.fish index 9bae21b..3be6cb5 100644 --- a/functions/check_fish_deps.fish +++ b/functions/check_fish_deps.fish @@ -11,8 +11,13 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + fish-deps status end diff --git a/functions/claude-docs.fish b/functions/claude-docs.fish index a4979b5..699d814 100644 --- a/functions/claude-docs.fish +++ b/functions/claude-docs.fish @@ -12,8 +12,13 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + claude "Analyze the recent changes and update the README.md to ensure all features, setup instructions, and examples are 100% accurate. Prune any obsolete information." end diff --git a/functions/claude-pr.fish b/functions/claude-pr.fish index 507d753..02bd88c 100644 --- a/functions/claude-pr.fish +++ b/functions/claude-pr.fish @@ -12,8 +12,13 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + claude "Act as a senior engineer. Execute this sequence: 1. Create a new git branch (kebab-case). 2. Stage changes and write a Conventional Commit message. 3. Self-verify the changes by running relevant build/test commands or linting. 4. Push to remote. 5. Create a PR to 'main' including a summary of changes and a 'Manual Verification' section containing a Markdown checklist (- [ ]) of specific, bite-sized steps required to manually verify the functionality." end diff --git a/functions/cleanup.fish b/functions/cleanup.fish index eaa30db..17e7612 100644 --- a/functions/cleanup.fish +++ b/functions/cleanup.fish @@ -11,9 +11,15 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + set -l orphans (pacman -Qtdq) if test -n "$orphans" echo "📝 Logging orphans to ~/.removed_orphans..." 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/functions/fast.fish b/functions/fast.fish index 5cc0dfe..59d8fe6 100644 --- a/functions/fast.fish +++ b/functions/fast.fish @@ -33,9 +33,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + # ANSI Escape Codes (Standard 16-color palette) set -l bold "\e[1m" set -l italic "\e[3m" diff --git a/functions/fc.fish b/functions/fc.fish index 5abb0a1..a65e230 100644 --- a/functions/fc.fish +++ b/functions/fc.fish @@ -24,6 +24,8 @@ # fc # fc git function fc --description 'Edit and execute the last command (Bash-style fc)' + __fish_help_header (status current-function) $argv; and return 0 + set -l tmpfile (mktemp /tmp/fish_fc.XXXXXX).fish if count $argv >/dev/null diff --git a/functions/fish-deps.fish b/functions/fish-deps.fish index acf9aba..850de30 100644 --- a/functions/fish-deps.fish +++ b/functions/fish-deps.fish @@ -66,6 +66,13 @@ function fish-deps --description 'Manage fish shell dependencies' _fish_deps_status case install _fish_deps_install $flags + case -h --help + # Reuse the existing menu rather than the header renderer: it + # is richer, and it is already the text the unknown-subcommand + # path prints. Previously --help fell into `case '*'` and + # exited 1 with "Unknown subcommand: --help". + __fish_deps_help + return 0 case update _fish_deps_update case sync diff --git a/functions/fzf-update.fish b/functions/fzf-update.fish index 1a403ed..b0c5ae9 100644 --- a/functions/fzf-update.fish +++ b/functions/fzf-update.fish @@ -11,9 +11,15 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if test -d ~/.fzf echo "Updating fzf..." git -C ~/.fzf pull --ff-only diff --git a/functions/gip.fish b/functions/gip.fish index 19cbd91..bbbd9dd 100644 --- a/functions/gip.fish +++ b/functions/gip.fish @@ -11,9 +11,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + echo -n "IPv4: " curl -4 -s --max-time 2 https://icanhazip.com || echo "Not detected" echo -n "IPv6: " diff --git a/functions/gip4.fish b/functions/gip4.fish index 9a71d1f..a8f54b4 100644 --- a/functions/gip4.fish +++ b/functions/gip4.fish @@ -10,8 +10,13 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + curl -4 -s https://icanhazip.com end diff --git a/functions/gip6.fish b/functions/gip6.fish index 735ffc6..52ca05c 100644 --- a/functions/gip6.fish +++ b/functions/gip6.fish @@ -21,6 +21,8 @@ # EXAMPLE # gip6 function gip6 --description 'Get public IPv6 address' + __fish_help_header (status current-function) $argv; and return 0 + # Use -6 to force IPv6 and --fail to catch network errors set -l ip (curl -6 -s --fail https://icanhazip.com 2>/dev/null) diff --git a/functions/hist.fish b/functions/hist.fish index 66ecc11..c8e0dbd 100644 --- a/functions/hist.fish +++ b/functions/hist.fish @@ -14,9 +14,15 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + # Opinionated guard (C4): integrations disabled if not __fish_config_op_enabled (status current-function) __fish_palette diff --git a/functions/lD.fish b/functions/lD.fish index 10ee313..2a78257 100644 --- a/functions/lD.fish +++ b/functions/lD.fish @@ -14,9 +14,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if which eza >/dev/null 2>&1 eza --only-dirs --long --icons --color=auto --hyperlink $argv else if which lsd >/dev/null 2>&1 diff --git a/functions/ld.fish b/functions/ld.fish index 5bc6b4a..4baa58e 100644 --- a/functions/ld.fish +++ b/functions/ld.fish @@ -17,6 +17,8 @@ # EXAMPLE # ld function ld --description 'Run lazydocker on the current Docker context' + __fish_help_header (status current-function) $argv; and return 0 + if not type -q docker echo "ld: docker is not installed" >&2 return 1 diff --git a/functions/limine-edit.fish b/functions/limine-edit.fish index f22a652..f130e35 100644 --- a/functions/limine-edit.fish +++ b/functions/limine-edit.fish @@ -13,9 +13,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + # 1. Open the config with sudoedit sudoedit /boot/limine.conf diff --git a/functions/lock.fish b/functions/lock.fish index c1e61bc..16f4043 100644 --- a/functions/lock.fish +++ b/functions/lock.fish @@ -10,8 +10,13 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + loginctl lock-session end diff --git a/functions/lsr.fish b/functions/lsr.fish index 344530d..a51bbe8 100644 --- a/functions/lsr.fish +++ b/functions/lsr.fish @@ -14,9 +14,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if which eza >/dev/null 2>&1 eza --oneline --sort=modified --reverse --icons --color=auto --hyperlink $argv else if which lsd >/dev/null 2>&1 diff --git a/functions/lss.fish b/functions/lss.fish index 9973905..7118254 100644 --- a/functions/lss.fish +++ b/functions/lss.fish @@ -14,9 +14,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if which eza >/dev/null 2>&1 eza --oneline --long --all --sort=size --icons --color=auto --hyperlink --color-scale=size --color-scale-mode=gradient $argv else if which lsd >/dev/null 2>&1 diff --git a/functions/lstree.fish b/functions/lstree.fish index 49993ea..f74da5d 100644 --- a/functions/lstree.fish +++ b/functions/lstree.fish @@ -14,9 +14,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if which eza >/dev/null 2>&1 eza --tree --icons --color=auto --hyperlink=auto $argv else if which lsd >/dev/null 2>&1 diff --git a/functions/lt.fish b/functions/lt.fish index 6e0fcfe..29ca192 100644 --- a/functions/lt.fish +++ b/functions/lt.fish @@ -14,9 +14,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if which eza >/dev/null 2>&1 eza --tree --level=2 --icons --color=auto --hyperlink $argv else if which lsd >/dev/null 2>&1 diff --git a/functions/ltr.fish b/functions/ltr.fish index 11e80ab..c9d34e0 100644 --- a/functions/ltr.fish +++ b/functions/ltr.fish @@ -15,9 +15,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if which eza >/dev/null 2>&1 eza --long --all --sort=modified --icons --hyperlink --color=auto --color-scale=age --color-scale-mode=gradient $argv else if which lsd >/dev/null 2>&1 diff --git a/functions/lx.fish b/functions/lx.fish index 663be39..ea10d4d 100644 --- a/functions/lx.fish +++ b/functions/lx.fish @@ -14,9 +14,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + if which eza >/dev/null 2>&1 eza --long --all --sort=extension --icons --color=auto --hyperlink $argv else if which lsd >/dev/null 2>&1 diff --git a/functions/parur.fish b/functions/parur.fish index 62a65e1..6f6f92c 100644 --- a/functions/parur.fish +++ b/functions/parur.fish @@ -19,6 +19,8 @@ # EXAMPLE # parur function parur --description 'Interactively search and remove an installed package using fzf' + __fish_help_header (status current-function) $argv; and return 0 + set -l aur "" if type -q paru set aur paru diff --git a/functions/poke.fish b/functions/poke.fish index 8cff1c5..ea9bd59 100644 --- a/functions/poke.fish +++ b/functions/poke.fish @@ -21,6 +21,8 @@ # EXAMPLE # poke ~/projects/new/src/main.fish function poke --description 'touch with automatic parent directory creation' + __fish_help_header (status current-function) $argv; and return 0 + if test (count $argv) -eq 0 echo (set_color red)"poke: no file specified"(set_color normal) >&2 return 1 diff --git a/functions/ports.fish b/functions/ports.fish index 19c0e57..c57e7ec 100644 --- a/functions/ports.fish +++ b/functions/ports.fish @@ -11,8 +11,13 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + sudo lsof -iTCP -sTCP:LISTEN -P -n end diff --git a/functions/qr.fish b/functions/qr.fish index 804ded5..268c7be 100644 --- a/functions/qr.fish +++ b/functions/qr.fish @@ -15,10 +15,15 @@ # 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 function qr --description 'Generate a QR code from text or pipe' + __fish_help_header (status current-function) $argv; and return 0 + if type -q qrencode if set -q argv[1] echo $argv | qrencode -t utf8 diff --git a/functions/sbver.fish b/functions/sbver.fish index b9a807d..87d7965 100644 --- a/functions/sbver.fish +++ b/functions/sbver.fish @@ -24,6 +24,8 @@ # sbver # sbver --brief function sbver --description 'Verifies Secure Boot status of EFI binaries using sbctl' + __fish_help_header (status current-function) $argv; and return 0 + if not type -q sbctl echo "Error: 'sbctl' is not installed." return 1 diff --git a/functions/screensleep.fish b/functions/screensleep.fish index 452ff9e..4496031 100644 --- a/functions/screensleep.fish +++ b/functions/screensleep.fish @@ -11,9 +11,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + # 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 539cd67..2b4bad6 100644 --- a/functions/split.fish +++ b/functions/split.fish @@ -29,6 +29,10 @@ # split # split -v nvim README.md function split --description 'Run a command in a new terminal split' + # -h is --horizontal here (see this function's own ARGUMENTS), + # so only the long form may reach the renderer. + test "$argv[1]" = --help; and __fish_help_header (status current-function) --help; and return 0 + # Opinionated guard (C4): integrations disabled if not __fish_config_op_enabled (status current-function) __fish_palette 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 -- \ diff --git a/functions/spwin.fish b/functions/spwin.fish index 954d3d1..50532b7 100644 --- a/functions/spwin.fish +++ b/functions/spwin.fish @@ -24,6 +24,8 @@ # EXAMPLE # spwin function spwin --wraps='~/.config/kitty/spawn-window.sh' --description 'spawn window in kitty or wezterm' + __fish_help_header (status current-function) $argv; and return 0 + # Opinionated guard (C4): integrations disabled if not __fish_config_op_enabled (status current-function) __fish_palette diff --git a/functions/steam-dl.fish b/functions/steam-dl.fish index 3c4395d..24583bd 100644 --- a/functions/steam-dl.fish +++ b/functions/steam-dl.fish @@ -11,9 +11,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + echo "Inhibiting sleep while Steam downloads..." systemd-inhibit --why="Active Download" --who="User" --what=idle:sleep steam end diff --git a/functions/sudo-toggle.fish b/functions/sudo-toggle.fish index e46547f..c218e98 100644 --- a/functions/sudo-toggle.fish +++ b/functions/sudo-toggle.fish @@ -19,6 +19,8 @@ # EXAMPLE # sudo-toggle function sudo-toggle --description 'Toggle sudo password requirement on/off' + __fish_help_header (status current-function) $argv; and return 0 + # Check the file size using sudo stat to see if our bypass rule is active set -l file_size (sudo stat -c %s /etc/sudoers.d/nofail-toggle 2>/dev/null) diff --git a/functions/swapstat.fish b/functions/swapstat.fish index 55a26fe..0ffa51a 100644 --- a/functions/swapstat.fish +++ b/functions/swapstat.fish @@ -12,9 +12,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + set -l swappiness (sysctl -n vm.swappiness) set -l zdata (zramctl --bytes --noheadings --output DATA,TOTAL /dev/zram0 2>/dev/null) diff --git a/functions/tab.fish b/functions/tab.fish index 092acd0..601b4d1 100644 --- a/functions/tab.fish +++ b/functions/tab.fish @@ -25,6 +25,8 @@ # EXAMPLE # tab function tab --description 'Spawn a new tab in the current terminal' + __fish_help_header (status current-function) $argv; and return 0 + # Opinionated guard (C4): integrations disabled if not __fish_config_op_enabled (status current-function) __fish_palette diff --git a/functions/tmux-clean.fish b/functions/tmux-clean.fish index cf775c4..6d878e8 100644 --- a/functions/tmux-clean.fish +++ b/functions/tmux-clean.fish @@ -11,9 +11,14 @@ # 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' + __fish_help_header (status current-function) $argv; and return 0 + # Get a list of all session names that are NOT currently attached set sessions (tmux list-sessions -F '#{session_name} #{session_attached}' | string match -rv ' 1$' | string split -f1 ' ') diff --git a/functions/upgrade.fish b/functions/upgrade.fish index 38443de..9139801 100644 --- a/functions/upgrade.fish +++ b/functions/upgrade.fish @@ -21,6 +21,8 @@ # EXAMPLE # upgrade function upgrade --description 'Full system upgrade via paru or yay' + __fish_help_header (status current-function) $argv; and return 0 + # Opinionated guard (C4): integrations disabled if not __fish_config_op_enabled (status current-function) __fish_palette diff --git a/functions/wake-lock.fish b/functions/wake-lock.fish index c71e44f..0f11920 100644 --- a/functions/wake-lock.fish +++ b/functions/wake-lock.fish @@ -22,6 +22,8 @@ # EXAMPLE # wake-lock rsync -avz src/ dest/ function wake-lock --description 'Run a command while inhibiting system sleep' + __fish_help_header (status current-function) $argv; and return 0 + if test (count $argv) -eq 0 __fish_palette echo "$c_head""Usage:$c_reset $c_cmd""wake-lock$c_reset $c_arg""[command] [args...]$c_reset" diff --git a/tests/functional.fish b/tests/functional.fish deleted file mode 100644 index 590068c..0000000 --- a/tests/functional.fish +++ /dev/null @@ -1,188 +0,0 @@ -# Copyright (C) 2026 Rootiest -# SPDX-License-Identifier: AGPL-3.0-or-later -# -# Functional checks for foundational config behavior. Sourced inside a -# fully-loaded, sandboxed interactive fish session by tests/run-tests.fish -# -- see that file for the sandbox setup. Each test_* function returns 0 -# on pass, non-zero on fail; functional_test_main collects and runs them. - -function test_xdg_defaults - test -n "$XDG_CONFIG_HOME" -a -n "$XDG_CACHE_HOME" \ - -a -n "$XDG_DATA_HOME" -a -n "$XDG_STATE_HOME" -end - -function test_path_additions - contains -- "$HOME/.local/bin" $PATH -end - -function test_cdpath - contains -- "$HOME/projects" $CDPATH -end - -function test_vi_key_bindings - test "$fish_key_bindings" = fish_vi_key_bindings -end - -function test_abbreviations_loaded - abbr -q n -end - -function test_core_functions_defined - for f in cat logs config-help fish-deps check_fish_deps config-settings - if not functions -q $f - echo " missing function: $f" - return 1 - end - end -end - -function test_exit_rewired - functions -q exit - and functions exit | string match -q '*smart_exit*' -end - -function test_op_registry_lookup - functions -q __fish_config_op_registry_lookup - or return 1 - set -l tags (__fish_config_op_registry_lookup config cdpath) - test $status -eq 0 -a (count $tags) -gt 0 -end - -function test_privacy_variables - test "$DO_NOT_TRACK" = "1" -a "$DISABLE_TELEMETRY" = "1" -end - -function test_privacy_op_registry_lookup - functions -q __fish_config_op_registry_lookup - or return 1 - set -l tags (__fish_config_op_registry_lookup config privacy) - test $status -eq 0 -a "$tags" = "overrides/privacy" -end - -function test_op_enabled_fail_open - # An identity/site pair with no registry entry must resolve to - # enabled -- the documented fail-open default. - __fish_config_op_enabled __fish_config_test_never_registered somesite -end - -function test_greeting_function_defined - functions -q fish_greeting -end - -function test_agents_vault_defined - for f in agents-vault _agents_vault_dir _agents_repo_slug \ - _agents_repo_ensure_symlink _agents_repo_sync \ - _agents_repo_install_tools - if not functions -q $f - echo " missing function: $f" - return 1 - end - end -end - -function test_wrappers_call_agents_vault - functions -q claude; or return 1 - functions claude | string match -q '*agents-vault*'; or return 1 - functions -q agy; or return 1 - functions agy | string match -q '*agents-vault*' -end - -function test_vault_dir_honors_override - set -l saved - set -q __fish_agent_vault_dir; and set saved $__fish_agent_vault_dir - set -g __fish_agent_vault_dir /tmp/vault-override-check - set -l got (_agents_vault_dir) - set -e __fish_agent_vault_dir - test (count $saved) -gt 0; and set -g __fish_agent_vault_dir $saved - test "$got" = /tmp/vault-override-check -end - -function test_palette_roles_defined - functions -q __fish_palette - or begin - echo " __fish_palette is not defined" - return 1 - end - # Called from inside a function, the palette must land in THIS scope. - __fish_palette - set -l missing - for role in c_reset c_head c_cmd c_arg c_flag c_warn c_err c_ok \ - c_accent c_dim c_sel c_hi - if not set -q $role; or test -z "$$role" - set -a missing $role - end - end - if test (count $missing) -gt 0 - echo " palette roles empty or unset: $missing" - return 1 - end - # Nothing may leak to global scope. - if set -q -g c_reset - echo " __fish_palette leaked c_reset into global scope" - return 1 - end - return 0 -end - -# Every user-facing function that renders a coloured --help must still emit -# escape sequences. -# -# This is deliberately a RUNTIME check, never a static grep for -# __fish_palette. Measured on a deliberately broken functions/logs.fish -- -# the palette call de-duplicated per indentation depth instead of per -# contiguous run, so the --help block lost its declarations without gaining -# a call: -# -# fish tests/palette-bytes.fish -# FAIL logs --help stdout=DIFF stderr=ok -# baseline 431 B -> broken 150 B (every escape stripped) -# -# fish -n functions/logs.fish -> exit 0 (lint PASSES) -# grep -c '__fish_palette' logs.fish -> 1 (grep PASSES) -# -# Both cheap checks are green on a file whose help output has lost all of -# its colour. Only running the function and looking for an \e byte catches -# it. The full test suite was also green throughout. -# -# functions/fish_prompt.fish is excluded BY NAME. It interpolates $c_dim -# from its own Catppuccin hex palette -- those are colour arguments passed -# to set_color, not captured escapes -- so it legitimately never calls -# __fish_palette and would otherwise look unconverted forever. -# -# qc is absent from the list on purpose: its --help shells out to aichat, -# which is not installed in CI, so its colour path is unreachable here. -# tests/palette-bytes.fish stubs aichat and does cover it. -function test_functions_keep_their_palette - set -l colored agents-init agents-vault auto-pull config-settings \ - config-update detach dng2avif dockup edit jobrunner kitty-logging \ - logs mkcd open-url p pkg play-media rand_string replay repo-open \ - scrub smart_exit spark y - set -l uncolored - for fn in $colored - functions -q $fn; or continue - if not $fn --help 2>&1 | string match -qr \e - set -a uncolored $fn - end - end - if test (count $uncolored) -gt 0 - echo " --help lost its colour: $uncolored" - return 1 - end - return 0 -end - -function functional_test_main - set -l names (functions -a | string match 'test_*' | sort) - set -l failed 0 - for name in $names - if $name - echo " PASS $name" - else - echo " FAIL $name" - set failed (math $failed + 1) - end - end - echo "" - echo (math (count $names) - $failed)"/"(count $names)" passed" - return $failed -end diff --git a/tests/lib.fish b/tests/lib.fish new file mode 100644 index 0000000..2edfc91 --- /dev/null +++ b/tests/lib.fish @@ -0,0 +1,62 @@ +#!/usr/bin/env fish +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later +# +# Shared assertion and reporting core for tests/test-*.fish. +# +# One assertion: `check