diff --git a/.gitignore b/.gitignore index 2c1ed14..3d1bc61 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ # GitIgnore for Fish-config -# id: gitig-boilerplate-7f0528027e23f210196ae4583c408e5b +# id: gitig-boilerplate-a27b89403ff9f0bb3340ede87b42f93e # ╭──────────────────────────────────────────────────────────╮ # │ GitIgnore Boilerplate Template │ # ╰──────────────────────────────────────────────────────────╯ @@ -93,8 +93,9 @@ functions/sponge_*.fish [Aa][nN][Tt][Ii][Gg][Rr][Aa][Vv][Ii][Tt][Yy].[Mm][Dd] .[Aa][Nn][Tt][Ii][Gg][Rr][Aa][Vv]* -# Matches AGENTS.md, .remember, etc. +# Matches AGENTS.md, .agents/ (agy), .remember, etc. [Aa][Gg][Ee][Nn][Tt][Ss].[Mm][Dd] +.[Aa][Gg][Ee][Nn][Tt][Ss]* .[Rr][Ee][Mm][Ee][Mm][Bb][Ee][Rr] # ────────────────────────────────────────────────────────────── 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/__config_settings_draw.fish b/functions/__config_settings_draw.fish index 04a1c71..f4d975b 100644 --- a/functions/__config_settings_draw.fish +++ b/functions/__config_settings_draw.fish @@ -38,9 +38,7 @@ function __config_settings_draw set -l cur_scope $argv[2] set -l vars $argv[3..] - set -l c_dim (set_color brblack) - set -l c_head (set_color --bold cyan) - set -l c_reset (set_color normal) + __fish_palette set -l labels Aliases Auto-exec Overrides Integrations Logging Greeting Master diff --git a/functions/__config_settings_draw_subcat.fish b/functions/__config_settings_draw_subcat.fish index 9c05200..6920ece 100644 --- a/functions/__config_settings_draw_subcat.fish +++ b/functions/__config_settings_draw_subcat.fish @@ -41,9 +41,7 @@ function __config_settings_draw_subcat set -l cur_scope $argv[2] set -l category_var $argv[3] - set -l c_dim (set_color brblack) - set -l c_head (set_color --bold cyan) - set -l c_reset (set_color normal) + __fish_palette set -l rows (__config_settings_subcats $category_var) set -l n (count $rows) diff --git a/functions/__config_settings_draw_value.fish b/functions/__config_settings_draw_value.fish index 49e91ae..1d7136f 100644 --- a/functions/__config_settings_draw_value.fish +++ b/functions/__config_settings_draw_value.fish @@ -33,10 +33,7 @@ function __config_settings_draw_value set -l edit_mode $argv[3] set -l edit_buf $argv[4] - set -l c_ok (set_color green) - set -l c_dim (set_color brblack) - set -l c_head (set_color --bold cyan) - set -l c_reset (set_color normal) + __fish_palette # ── Page row metadata (parallel lists) ──────────────────────────────── set -l title diff --git a/functions/__config_settings_pagetab.fish b/functions/__config_settings_pagetab.fish index 024ce01..b9d5a49 100644 --- a/functions/__config_settings_pagetab.fish +++ b/functions/__config_settings_pagetab.fish @@ -27,8 +27,7 @@ function __config_settings_pagetab set -l active $argv[1] set -l iw $argv[2] - set -l c_hi (set_color --bold white) - set -l c_reset (set_color normal) + __fish_palette set -l names Universal Session Sponge Paths set -l strip ' ' 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_palette.fish b/functions/__fish_palette.fish new file mode 100644 index 0000000..7097f39 --- /dev/null +++ b/functions/__fish_palette.fish @@ -0,0 +1,63 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later + +# SYNOPSIS +# __fish_palette +# +# DESCRIPTION +# Defines the shared terminal-output colour roles used by the +# user-facing functions in this configuration. Declared +# --no-scope-shadowing and using a bare `set`, so the variables are +# created in the CALLER's scope -- a consumer just calls it and then +# interpolates $c_head, $c_err and friends exactly as it did when the +# declarations were inline. +# +# Call it where the local declarations used to sit, once per contiguous +# block that needs the palette. set_color runs at call time, so the +# values track $TERM exactly as inline declarations did. (Measured: +# set_color output is identical across every TERM tested except +# TERM=dumb, which yields empty strings, and is unaffected by whether +# stdout is a tty or a pipe.) +# +# A role is a semantic slot, not a colour. c_flag and c_warn are both +# yellow but stay separate, as do c_ok and c_accent (both green) -- +# merging either pair would foreclose ever restyling one without the +# other. c_accent is the command name in logs and smart_exit, which +# style it green where the rest of the config styles it bold. +# +# ARGUMENTS +# none +# +# EXIT STATUS +# 0 always +# +# EXAMPLE +# function mytool +# __fish_palette +# echo "$c_head""Usage:$c_reset $c_cmd""mytool$c_reset" +# end +# +# NOTES +# Calling this at top level (outside any function) creates GLOBAL +# variables. Every consumer calls it from inside a function, where the +# variables stay function-local and do not leak. +# +# functions/fish_prompt.fish deliberately does NOT use this palette. Its +# c_* values are Catppuccin hex strings passed as ARGUMENTS to set_color +# (`set_color --bold $c_green`), not captured escape sequences -- colour +# inputs rather than rendered output, a different concern. + +function __fish_palette --no-scope-shadowing --description 'Define the shared output colour palette in the caller scope' + set c_reset (set_color normal) + set c_head (set_color --bold cyan) + set c_cmd (set_color --bold) + set c_arg (set_color cyan) + set c_flag (set_color yellow) + set c_warn (set_color yellow) + set c_err (set_color red) + set c_ok (set_color green) + set c_accent (set_color green) + set c_dim (set_color brblack) + set c_sel (set_color --bold magenta) + set c_hi (set_color --bold white) +end diff --git a/functions/_agents_init_ensure_gitignore.fish b/functions/_agents_init_ensure_gitignore.fish index 45d4c9f..f8b9ee3 100644 --- a/functions/_agents_init_ensure_gitignore.fish +++ b/functions/_agents_init_ensure_gitignore.fish @@ -31,8 +31,7 @@ # EXAMPLE # _agents_init_ensure_gitignore /home/user/myproject "agents-init" "AGENTS/" "/AGENTS.md" function _agents_init_ensure_gitignore - set -l c_ok (set_color green) - set -l c_reset (set_color normal) + __fish_palette if test (count $argv) -lt 3 echo (set_color red)"_agents_init_ensure_gitignore: requires