Merge pull request 'feat(deps): add Optional/Terminal Emulator tiers, fix docker prompt hang and ov install path' (#104) from feat-fish-deps-optional-tiers into main

Reviewed-on: #104

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 |
 

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

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

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

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..."

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."

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

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}}')