Add comprehensive inline metadata documentation to all BackTunnel scripts

completions/backtunnel.bash

@@ -1,4 +1,29 @@
 #!/usr/bin/env bash
+# Name: BackTunnel Bash Completion
+# Summary: Programmable completion for backtunnel-share and backtunnel-access.
+# Description:
+#   Provides contextual tab-completion for BackTunnel CLI tools, including positional
+#   scaffolding ("with"/"from", "for", duration suggestions), @profile expansion,
+#   SSH host suggestions from known_hosts and ~/.ssh/config, key-name and *.pub completion,
+#   and directory completion for mount paths.
+#
+# Usage:
+#   - Source in your shell (for current session):
+#       source /path/to/backtunnel.bash
+#   - Install system-wide or in your completion.d directory (auto-sourced by bash-completion).
+#
+# Dependencies:
+#   - bash with programmable completion (bash-completion recommended)
+#   - awk (for profile parsing)
+#
+# Compatibility:
+#   - Targets Bash completion v1 (COMP_WORDS, COMPREPLY, compgen, compopt).
+#
+# Notes:
+#   - Reads profiles from ${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/profiles.ini,
+#     /etc/backtunnel/profiles.ini, and /usr/share/backtunnel/profiles.ini when present.
+#   - Best-effort parsing and host extraction; hashed known_hosts entries are ignored.
+
 # BackTunnel bash completion for:
 #   - backtunnel-share
 #   - backtunnel-access
@@ -10,10 +35,12 @@
 # - --allow-known completes names from ~/.config/backtunnel/authorized/*.pub
 # - SSH host completion from known_hosts and ssh config Host entries
 # - Path completion for first positional and --invite-mount / --mount-point
-# - Option-aware value completion (-p/-l suggest typical ports)
 
 # ---------- helpers ----------
 
+# _bt_cfg_files: print existing profiles.ini files in precedence order (high → low).
+# Arguments: none
+# Output: absolute paths, one per line
 _bt_cfg_files() {
   local u="${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/profiles.ini"
   local s="/etc/backtunnel/profiles.ini"
@@ -23,6 +50,9 @@ _bt_cfg_files() {
   [[ -f "$p" ]] && printf '%s\n' "$p"
 }
 
+# _bt_list_profiles: list profile section names (excluding [default]) from all config files.
+# Arguments: none
+# Output: profile names, one per line (deduplicated)
 _bt_list_profiles() {
   # Output section names excluding [default]
   local f
@@ -35,6 +65,9 @@ _bt_list_profiles() {
   done < <(_bt_cfg_files) 2>/dev/null | sort -u
 }
 
+# _bt_list_authorized_names: list stored accessor key names from the authorized store.
+# Arguments: none
+# Output: key names (basename without .pub), one per line
 _bt_list_authorized_names() {
   # From ~/.config/backtunnel/authorized/*.pub → basename w/o .pub
   local d="${XDG_CONFIG_HOME:-$HOME/.config}/backtunnel/authorized"
@@ -46,6 +79,10 @@ _bt_list_authorized_names() {
   done
 }
 
+# _bt_list_ssh_hosts: gather SSH host candidates from known_hosts and ~/.ssh/config.
+# Arguments: none
+# Output: hostnames (best-effort), one per line
+# Notes: skips hashed known_hosts entries and wildcards; filters out plain IP literals.
 _bt_list_ssh_hosts() {
   # Collect hosts from known_hosts and ~/.ssh/config Host entries (best effort)
   local out=()
@@ -76,11 +113,17 @@ _bt_list_ssh_hosts() {
   fi
 }
 
+# Predicates to distinguish which command is being completed
 _bt_is_backtunnel_share() { [[ ${COMP_WORDS[0]} == backtunnel-share ]]; }
 _bt_is_backtunnel_access(){ [[ ${COMP_WORDS[0]} == backtunnel-access ]]; }
 
 # ---------- main completer ----------
 
+# _backtunnel_complete: top-level completion function for both commands.
+# Arguments:
+#   Uses global completion variables: COMP_WORDS, COMP_CWORD
+# Output:
+#   Sets COMPREPLY array with candidates appropriate to the current cursor position.
 _backtunnel_complete() {
   local cur prev
   cur="${COMP_WORDS[COMP_CWORD]}"
@@ -198,4 +241,4 @@ _backtunnel_complete() {
 
 # Register for both commands
 complete -F _backtunnel_complete backtunnel-share
-complete -F _backtunnel_complete backtunnel-access
+complete -F _backtunnel_complete backtunnel-access