diff --git a/docs/manual/06-dependency-catalog.md b/docs/manual/06-dependency-catalog.md index c8417a4..4cd7d88 100644 --- a/docs/manual/06-dependency-catalog.md +++ b/docs/manual/06-dependency-catalog.md @@ -8,8 +8,10 @@ helpKeywords: - deps-catalog --- -fish-deps manages these tools. Run `fish-deps` to check status, or -`fish-deps install` to install missing ones. +fish-deps manages these tools. Run `fish-deps` to check status, +`fish-deps install` to install missing Required/Recommended ones, or add +`--optional`, `--terminals`, or `--all` to also include the Optional and/or +Terminal Emulators tiers. ## Required @@ -18,13 +20,6 @@ fish-deps manages these tools. Run `fish-deps` to check status, or | `fish` | Fish shell >= 4.0 | | `fzf` | Fuzzy finder | -## Integrations - -| Tool | Description | -|---|---| -| `wakatime` | Developer time tracking | -| `tailscale` | Mesh VPN client | - ## Recommended | Tool | Description | @@ -39,19 +34,50 @@ fish-deps manages these tools. Run `fish-deps` to check status, or | `zoxide` | Smart cd with frecency | | `lsd` | `ls` replacement (fallback to `eza`) | | `bat` | Syntax-highlighted `cat` | -| `btop` | Modern resource monitor | -| `dust` | Disk usage tree (Rust) | -| `duf` | Disk usage/free overview | -| `prettyping` | Colorized ping wrapper | -| `ov` | Modern pager (replaces `less`) | +| `ov` | Modern pager (replaces `less`); also backs the `logs` viewer. Not a Rust crate, despite the name collision with an unrelated `ov` crate on crates.io. Prefers `go install github.com/noborus/ov@latest` when `go` is available (always gets the latest release, and covers distros like Debian/Ubuntu that don't package `ov` in their base repos); falls back to the system PM (AUR on Arch) otherwise. | | `ripgrep` | Fast line search | -| `lazygit` | Terminal git UI | -| `lazydocker` | Terminal docker UI | -| `trash` | Safe delete (`trash-cli`) | -| `kitty` | GPU-accelerated terminal (primary) | -| `wezterm` | GPU-accelerated terminal (alternative) | +| `trash` | Safe delete (`trash-cli`); backs the `rm` and `scrub` wrappers. | | `python3` | Standalone interpreter — used by the `paru`/`yay` log cleaner. Note: `uv` does not provide `python3` on PATH, and Arch's base does not include it, so it is listed separately. All consumers degrade gracefully without it. | -| `yt-dlp` | Video/media downloader; backs the `yt-dlp` wrapper function. Optional — the wrapper falls back to the system `yt-dlp` and the rest of the config works without it. | + +## Optional + +Single-purpose tools that back one wrapper function (or less) and only +matter if you already use that specific tool. Skipped by +`fish-deps install`/`sync` unless you pass `--optional`. + +| Tool | Description | +|---|---| +| `btop` | Modern resource monitor; backs the `top` wrapper (falls back to system `top`). | +| `dust` | Disk usage tree (Rust); one of two backends for the `du` wrapper (falls back to system `du`). | +| `duf` | Disk usage/free overview; the other backend for the `du` wrapper (falls back to system `du`). | +| `prettyping` | Colorized ping wrapper; backs the `ping` wrapper (falls back to system `ping`). | +| `go` | Go toolchain; only used to install `ov` via `go install` (see below), which gets the latest release and doesn't depend on your distro packaging `ov`. Package name varies by distro (`go` on Arch/Homebrew, `golang`/`golang-go` on Debian/Fedora) — install manually if the listed package name doesn't resolve on your system. | +| `lazygit` | Terminal git UI; only referenced by the `lg` abbreviation. | +| `lazydocker` | Terminal docker UI; backs the `ld` wrapper. | +| `docker` | Container runtime; gates the Docker context indicator in the right prompt and backs the `ld` wrapper. Both consumers are guarded with `type -q docker` and degrade gracefully without it. Installing the daemon package does not enable/start the service — do that yourself if you want it running. | +| `yt-dlp` | Video/media downloader; backs the `yt-dlp` wrapper function. The wrapper falls back to the system `yt-dlp` and the rest of the config works without it. | +| `screen` | GNU screen; fallback backend for `jobrunner` when `tmux` is unavailable. | + +## Terminal Emulators + +GPU-accelerated terminal emulators. Only one is ever relevant to a given +user — the one matching `$TERM` — so neither is installed by default. +Skipped by `fish-deps install`/`sync` unless you pass `--terminals` (or +`--all`). + +| Tool | Description | +|---|---| +| `kitty` | GPU-accelerated terminal; unlocks kitty-specific abbreviations and `--hyperlink-format=kitty` in the `rg` wrapper when `$TERM = xterm-kitty`. | +| `wezterm` | GPU-accelerated terminal; unlocks WezTerm-specific abbreviations when it's the active terminal. | + +## Integrations + +Opt-in third-party services that require their own account/setup. + +| Tool | Description | +|---|---| +| `wakatime` | Developer time tracking | +| `tailscale` | Mesh VPN client | ## Install Methods @@ -59,8 +85,9 @@ The install priority for each tool: | Method | Packages | |---|---| -| `cargo` | Rust tools (`eza`, `lsd`, `bat`, `dust`, `ov`, `ripgrep`, `trashy`, `zoxide`, `starship`) — always gets the latest crate version | -| system PM | `paru` / `apt` / `brew` / `dnf` / etc. — for tools without a crate | +| `cargo` | Rust tools (`eza`, `lsd`, `bat`, `dust`, `ripgrep`, `trashy`, `zoxide`, `starship`) — always gets the latest crate version | +| `go install` | `ov` — preferred over the system PM when `go` is available; always gets the latest release | +| system PM | `paru` / `apt` / `brew` / `dnf` / etc. — for tools without a crate or `go install` path | | `git clone` | `fzf` — installed from GitHub to `~/.fzf/` | | `curl` | `starship` installer, `fisher` bootstrap, `uv` installer | diff --git a/functions/_fish_deps_catalog.fish b/functions/_fish_deps_catalog.fish index 09db70c..36ea98b 100644 --- a/functions/_fish_deps_catalog.fish +++ b/functions/_fish_deps_catalog.fish @@ -9,6 +9,26 @@ # _fdc_pm, _fdc_special) describing every managed shell dependency. # Must be called before accessing any _fdc_* array. # +# Tiers: +# req Required — the shell does not function without these. +# rec Recommended — meaningfully enhance the experience across +# multiple functions; the bulk of the +# catalog. +# opt Optional — minor, single-purpose wrapper +# conveniences (e.g. backs one wrapper +# function) that only matter if you already +# use that specific tool. Skipped by +# `fish-deps install`/`sync` unless +# `--optional` (or `--all`) is passed. +# term Terminal Emulators — GPU-accelerated terminal emulators +# (kitty, wezterm) that only matter if one +# of them is your actual terminal. Skipped +# by `fish-deps install`/`sync` unless +# `--terminals` (or `--all`) is passed. +# int Integrations — opt-in third-party services requiring +# their own account/setup (wakatime, +# tailscale). +# # EXAMPLE # _fish_deps_catalog # echo $_fdc_bins @@ -16,27 +36,27 @@ function _fish_deps_catalog set -g _fdc_bins \ uv cargo fish starship fzf zoxide direnv paru yay \ wakatime tailscale \ - eza lsd bat btop dust duf prettyping ov rg lazygit lazydocker trash kitty wezterm python3 yt-dlp screen + eza lsd bat btop dust duf prettyping go ov rg lazygit lazydocker docker trash kitty wezterm python3 yt-dlp screen set -g _fdc_tiers \ rec rec req rec req rec rec rec rec \ int int \ - rec rec rec rec rec rec rec rec rec rec rec rec rec rec rec rec rec + rec rec rec opt opt opt opt opt rec rec opt opt opt rec term term rec opt opt set -g _fdc_cargo \ "" "" "" starship "" zoxide "" "" "" \ "" "" \ - eza lsd bat "" du-dust "" "" ov ripgrep "" "" trashy "" "" "" "" "" + eza lsd bat "" du-dust "" "" "" "" ripgrep "" "" "" trashy "" "" "" "" "" set -g _fdc_pm \ uv cargo fish starship fzf zoxide direnv "" yay \ wakatime tailscale \ - eza lsd bat btop dust duf prettyping ov ripgrep lazygit lazydocker trash kitty wezterm python yt-dlp screen + eza lsd bat btop dust duf prettyping go ov ripgrep lazygit lazydocker docker trash kitty wezterm python yt-dlp screen set -g _fdc_special \ curl-uv rustup-installer git-cargo-fish curl-installer fzf-update "" "" paru-build yay-build \ wakatime-binary "" \ - "" "" "" "" "" "" "" "" "" "" curl-lazydocker "" "" "" "" "" "" + "" "" "" "" "" "" "" "" go-ov "" "" curl-lazydocker "" "" "" "" "" "" "" end # SYNOPSIS diff --git a/functions/_fish_deps_install.fish b/functions/_fish_deps_install.fish index 5003830..8ff3e54 100644 --- a/functions/_fish_deps_install.fish +++ b/functions/_fish_deps_install.fish @@ -9,16 +9,61 @@ # For each missing entry, prompts yes/no and the preferred install method # when multiple options are available. # +# Optional-tier and Terminal-Emulator-tier dependencies are skipped by +# default; pass --optional / --terminals to include them individually, or +# --all to include both. +# +# ARGUMENTS +# --optional Also offer to install Optional-tier dependencies +# --terminals Also offer to install Terminal-Emulator-tier dependencies +# --all Shorthand for --optional --terminals +# # EXAMPLE # _fish_deps_install +# _fish_deps_install --optional +# _fish_deps_install --terminals +# _fish_deps_install --all function _fish_deps_install _fish_deps_catalog + set -l include_optional 0 + set -l include_terminals 0 + if contains -- --all $argv + set include_optional 1 + set include_terminals 1 + end + if contains -- --optional $argv + set include_optional 1 + end + if contains -- --terminals $argv + set include_terminals 1 + end + set -l pm (_fish_deps_detect_pm) set -l installed_any 0 + set -l skipped_optional 0 + set -l skipped_terminals 0 set -l i 1 for bin in $_fdc_bins + # Optional-tier deps are opt-in: skip unless --optional/--all was passed. + if test "$_fdc_tiers[$i]" = opt; and test $include_optional -eq 0 + if not command -q $bin + set skipped_optional (math $skipped_optional + 1) + end + set i (math $i + 1) + continue + end + + # Terminal-emulator-tier deps are opt-in: skip unless --terminals/--all was passed. + if test "$_fdc_tiers[$i]" = term; and test $include_terminals -eq 0 + if not command -q $bin + set skipped_terminals (math $skipped_terminals + 1) + end + set i (math $i + 1) + continue + end + # Determine if this dep needs attention: missing, or fish < 4.0 set -l needs_install 0 set -l upgrade_label Install @@ -81,6 +126,15 @@ function _fish_deps_install case wakatime-binary set -a methods special-wakatime set -a method_labels "binary download (github releases)" + case go-ov + if type -q go + set -a methods special-go-ov + set -a method_labels "go install (github.com/noborus/ov@latest)" + else + set_color brblack + echo " note: go not found — install go first for the latest $bin (not all distros package $bin in their base repos)" + set_color normal + end end # System PM — after cargo and preferred specials @@ -172,6 +226,25 @@ function _fish_deps_install echo " cargo not yet in PATH — restart your shell if subsequent installs fail." set_color normal end + case special-go-ov + go install github.com/noborus/ov@latest + set -l _go_status $status + # go install places binaries in $GOBIN, falling back to + # $GOPATH/bin (default ~/go/bin) — ask go itself rather + # than guessing, since GOPATH may be customized. + set -l _gobin (go env GOBIN) + if test -z "$_gobin" + set _gobin (go env GOPATH)/bin + end + if test -d "$_gobin" + fish_add_path "$_gobin" + end + if test $_go_status -eq 0; and not type -q ov + set_color yellow + echo " ov not yet in PATH — restart your shell if subsequent installs fail." + set_color normal + end + test $_go_status -eq 0 case special-lazydocker curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | bash case special-wakatime @@ -272,4 +345,20 @@ function _fish_deps_install if test $installed_any -eq 0 echo "Nothing to install." end + + if test $skipped_optional -gt 0 + set -l _plural dependencies + test $skipped_optional -eq 1; and set _plural dependency + set_color brblack + echo "Skipped $skipped_optional optional $_plural. Run 'fish-deps install --optional' to include them." + set_color normal + end + + if test $skipped_terminals -gt 0 + set -l _plural "terminal emulators" + test $skipped_terminals -eq 1; and set _plural "terminal emulator" + set_color brblack + echo "Skipped $skipped_terminals $_plural. Run 'fish-deps install --terminals' to include them." + set_color normal + end end diff --git a/functions/_fish_deps_status.fish b/functions/_fish_deps_status.fish index 20532cd..6bbbc90 100644 --- a/functions/_fish_deps_status.fish +++ b/functions/_fish_deps_status.fish @@ -6,7 +6,8 @@ # # DESCRIPTION # Prints a colored installed/missing status report for all managed fish shell -# dependencies, grouped by tier (required, integrations, recommended). +# dependencies, grouped by tier (required, recommended, optional, terminal +# emulators, integrations). # # EXAMPLE # _fish_deps_status @@ -31,18 +32,23 @@ function _fish_deps_status set_color green; echo -n " ✓ "; set_color normal echo -n "$bin " set_color brblack; echo "(Found at "(__fish_real_command $bin)")"; set_color normal + else if test "$tier" = req + set_color red; echo -n " ✗ "; set_color normal + echo -n "$bin " + set_color brblack; echo "(Not installed)"; set_color normal else if test "$tier" = rec set_color yellow; echo -n " ⚠ "; set_color normal echo -n "$bin " set_color brblack; echo "(Not installed)"; set_color normal else - set_color red; echo -n " ✗ "; set_color normal + # opt / term / int: absence is expected and not alarming + set_color brblack; echo -n " – "; set_color normal echo -n "$bin " set_color brblack; echo "(Not installed)"; set_color normal end end - for tier_label in "Required Dependencies:req" "Integrations:int" "Recommended Dependencies:rec" + for tier_label in "Required Dependencies:req" "Recommended Dependencies:rec" "Optional Dependencies:opt" "Terminal Emulators:term" "Integrations:int" set -l label (string split : $tier_label)[1] set -l tier (string split : $tier_label)[2] set_color cyan; echo $label; set_color normal diff --git a/functions/_fish_deps_update.fish b/functions/_fish_deps_update.fish index 1555fd5..8082506 100644 --- a/functions/_fish_deps_update.fish +++ b/functions/_fish_deps_update.fish @@ -72,6 +72,21 @@ function _fish_deps_update continue end + # ov: prefer go install (always fetches latest); fall back to system PM + if test "$special" = go-ov + if type -q go + echo "Updating $bin..." + go install github.com/noborus/ov@latest + set updated_any 1 + else if test -n "$pm_pkg"; and test -n "$pm" + echo "Updating $bin (go unavailable, using system PM)..." + _fish_deps_pm_upgrade $pm_pkg + set updated_any 1 + end + set i (math $i + 1) + continue + end + # lazydocker: re-run the official install/update script if test "$special" = curl-lazydocker echo "Updating $bin..." diff --git a/functions/fish-deps.fish b/functions/fish-deps.fish index 3012adf..001ef13 100644 --- a/functions/fish-deps.fish +++ b/functions/fish-deps.fish @@ -5,7 +5,7 @@ # 06-dependency-management # # SYNOPSIS -# fish-deps [status|install|update|sync] +# fish-deps [status|install|update|sync] [--optional] [--terminals] [--all] # # DESCRIPTION # Unified command for managing all tools this configuration depends on, @@ -21,19 +21,29 @@ # # When multiple methods are available you are prompted to choose. # -# Dependencies are grouped into three tiers: +# Dependencies are grouped into five tiers: # -# Required fish, fzf, zoxide -# Integrations wakatime, tailscale -# Recommended cargo, starship, uv, direnv, paru, yay, eza, lsd, bat, -# btop, dust, duf, prettyping, ov, ripgrep, lazygit, -# lazydocker, trash, kitty, wezterm, python3, yt-dlp +# Required fish, fzf +# Recommended cargo, starship, uv, zoxide, direnv, paru, yay, +# eza, lsd, bat, ov, ripgrep, trash, python3 +# Optional btop, dust, duf, prettyping, go, lazygit, +# lazydocker, docker, yt-dlp, screen — single-purpose +# wrapper conveniences that only matter if you +# already use that tool; skipped by `install`/`sync` +# unless --optional (or --all) is passed +# Terminal Emulators kitty, wezterm — only matter if one of them is +# your actual terminal; skipped by `install`/`sync` +# unless --terminals (or --all) is passed +# Integrations wakatime, tailscale # # ARGUMENTS -# status Report installed/missing deps (default) -# install Install missing deps interactively -# update Update all installed deps -# sync Install missing deps, then update all +# status Report installed/missing deps (default) +# install Install missing deps interactively +# update Update all installed deps +# sync Install missing deps, then update all +# --optional With install/sync: also offer Optional-tier deps +# --terminals With install/sync: also offer Terminal-Emulator-tier deps +# --all With install/sync: shorthand for --optional --terminals # # EXIT STATUS # 0 Subcommand completed @@ -43,20 +53,24 @@ # fish-deps sync # fish-deps # fish-deps install +# fish-deps install --optional +# fish-deps install --terminals +# fish-deps install --all # fish-deps update function fish-deps --description 'Manage fish shell dependencies' set -l subcmd $argv[1] + set -l flags $argv[2..] switch $subcmd case status '' _fish_deps_status case install - _fish_deps_install + _fish_deps_install $flags case update _fish_deps_update case sync echo "=== Installing missing deps ===" - _fish_deps_install + _fish_deps_install $flags echo "" echo "=== Updating installed deps ===" _fish_deps_update @@ -82,10 +96,15 @@ function __fish_deps_help set_color cyan; echo "fish-deps — manage fish shell dependencies"; set_color normal echo "" echo "Usage:" - echo " fish-deps [status] Check installed/missing deps (default)" - echo " fish-deps install Install missing deps interactively" - echo " fish-deps update Update all installed deps" - echo " fish-deps sync Install missing, then update all" + echo " fish-deps [status] Check installed/missing deps (default)" + echo " fish-deps install Install missing deps interactively" + echo " fish-deps update Update all installed deps" + echo " fish-deps sync Install missing, then update all" + echo "" + echo " install/sync accept:" + echo " --optional Also offer Optional-tier deps (skipped by default)" + echo " --terminals Also offer Terminal-Emulator-tier deps (skipped by default)" + echo " --all Shorthand for --optional --terminals" echo "" echo "Install method priority: cargo > system PM > git/curl/pipx" echo "When multiple methods are available, you will be prompted to choose." diff --git a/functions/fish_right_prompt.fish b/functions/fish_right_prompt.fish index 7695e65..f658e71 100644 --- a/functions/fish_right_prompt.fish +++ b/functions/fish_right_prompt.fish @@ -9,10 +9,9 @@ # # DESCRIPTION # Renders the right-side prompt. Always shows a dim timestamp. When the last -# command failed, prefixes it with a red ✘ and the exit code. When starship -# is installed and C3 overrides are enabled, also shows the active Docker -# context (if non-default) — that block is paired with the starship prompt -# which already guards on both conditions. +# command failed, prefixes it with a red ✘ and the exit code. When docker +# and starship are both installed and C3 overrides are enabled, also shows +# the active Docker context (if non-default). # # EXIT STATUS # 0 Always @@ -29,8 +28,10 @@ function fish_right_prompt set_color normal end - # Docker context — only relevant alongside the starship prompt - if type -q starship; and __fish_config_op_enabled __fish_config_op_overrides + # Docker context — only relevant alongside the starship prompt, and only + # when docker is actually installed (guarded like every other optional + # integration in this config). + if type -q docker; and type -q starship; and __fish_config_op_enabled __fish_config_op_overrides set -l docker_ctx (docker context show 2>/dev/null) if test -n "$docker_ctx"; and test "$docker_ctx" != default set_color blue diff --git a/functions/ld.fish b/functions/ld.fish index fa08974..5bc6b4a 100644 --- a/functions/ld.fish +++ b/functions/ld.fish @@ -11,9 +11,21 @@ # Launches lazydocker targeting the currently active Docker context by # resolving the host endpoint from docker context inspect. # +# EXIT STATUS +# 1 docker or lazydocker is not installed +# # EXAMPLE # ld function ld --description 'Run lazydocker on the current Docker context' + if not type -q docker + echo "ld: docker is not installed" >&2 + return 1 + end + if not type -q lazydocker + echo "ld: lazydocker is not installed" >&2 + return 1 + end + # Fetch the host endpoint of the currently active Docker context set -l current_host (docker context inspect --format '{{.Endpoints.docker.Host}}')