Add comprehensive inline metadata documentation to all BackTunnel scripts

scripts/backtunnel-access

@@ -1,5 +1,37 @@
 #!/usr/bin/env bash
-# Copyright (c) 2025. LUXIM d.o.o., Slovenia - Matjaž Mozetič.
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (c) 2025 LUXIM d.o.o., Slovenia
+# Author: Matjaž Mozetič
+#
+# Name: backtunnel-access
+# Summary: Mount a local folder exposed via a reverse SSH tunnel (SFTP over sshfs).
+# Description:
+#   Connects to a reverse SSH listener on the remote host's loopback (localhost:PORT),
+#   and mounts the specified local folder from the sharing side using sshfs.
+#   Performs basic checks (mountpoint readiness, auth hint, SFTP visibility) and
+#   sets sensible reconnect/keepalive options for a stable mount.
+#
+# Usage:
+#   backtunnel-access /path/to/folder from remoteuser:remotehost [-p PORT] [-m MOUNTPOINT]
+#
+# Examples:
+#   backtunnel-access ~/projects from alice@vps.example.com -p 2222 -m ~/remote-rssh
+#   backtunnel-access /data from bob:vps.example.com --port 4422 --mount-point /mnt/remote-rssh
+#
+# Dependencies:
+#   - bash
+#   - sshfs, sftp (OpenSSH), mountpoint
+#
+# Exit codes:
+#   0  success
+#   1  invalid usage/arguments or validation failure (e.g., mountpoint not writable)
+#   2+ runtime errors from underlying tools (sshfs/sftp/etc.)
+#
+# Notes:
+#   - Expects a reverse tunnel to be active on the remote side, binding localhost:PORT
+#     back to the sharer’s local sshd.
+#   - If passwordless auth isn’t set for $REMOTE_USER@localhost:$PORT, a one-time
+#     setup command is suggested; mount may still proceed with password prompts.
 
 # backtunnel-access: Mount a folder shared over reverse SSH
 # Usage: backtunnel-access /path/to/folder from remoteuser:remotehost [-p PORT] [-m MOUNTPOINT]
@@ -15,6 +47,7 @@ usage() {
 }
 
 # --- parse positional args ---
+# Purpose: enforce grammar "<folder> from <remote>" and collect required args.
 [[ $# -lt 3 ]] && usage
 
 FOLDER=$1
@@ -25,6 +58,7 @@ shift 3 || true
 [[ "$KEYWORD" != "from" ]] && usage
 
 # Optional flags
+# Purpose: allow custom tunnel port and mount destination.
 while [[ $# -gt 0 ]]; do
   case "$1" in
     -p|--port)
@@ -48,6 +82,7 @@ while [[ $# -gt 0 ]]; do
 done
 
 # --- normalize and prepare mount point ---
+# Purpose: make the mount point usable (expand ~, absolutize when possible, ensure perms).
 # Expand leading '~' even if quoted or passed via GUI
 # Note: default uses $HOME; still expand '~' if passed via CLI/GUI
 if [[ "${MOUNTPOINT:-}" == "~"* ]]; then
@@ -74,6 +109,7 @@ if [[ -n "$(ls -A -- "$MOUNTPOINT" 2>/dev/null || true)" ]]; then
 fi
 
 # --- split remote user/host (supports user:host or user@host) ---
+# Purpose: accept flexible remote formats commonly used in SSH tooling.
 REMOTE_USER=""
 REMOTE_HOST=""
 
@@ -89,6 +125,7 @@ else
 fi
 
 # --- deps check ---
+# Purpose: fail fast when core tools are missing.
 command -v sshfs >/dev/null 2>&1 || { echo "sshfs not found. Install sshfs first."; exit 1; }
 command -v mountpoint >/dev/null 2>&1 || { echo "mountpoint utility not found."; exit 1; }
 
@@ -103,6 +140,7 @@ fi
 echo "🔗 Mounting '$FOLDER' from '$REMOTE_USER@$REMOTE_HOST' via reverse-tunnel localhost:$PORT → '$MOUNTPOINT' ..."
 
 # --- ensure passwordless auth via tunnel (optional but user-friendly) ---
+# Purpose: detect whether a dedicated identity exists and hint user if passwordless setup is missing.
 SSH_IDENTITY_OPTS=()
 if [[ -f "$HOME/.ssh/id_ed25519_backtunnel" ]]; then
   SSH_IDENTITY_OPTS+=( -o IdentityFile="$HOME/.ssh/id_ed25519_backtunnel" -o IdentitiesOnly=yes )
@@ -125,12 +163,14 @@ fi
 
 echo "Checking remote path visibility via SFTP ..."
 
+# Purpose: quick sanity check that the target path is visible over SFTP before mounting.
 if ! sftp -q -P "$PORT" -o StrictHostKeyChecking=accept-new "${SFTP_ID_OPTS[@]}" \
          "$REMOTE_USER@localhost" <<< "ls -1 \"$FOLDER\"" >/dev/null 2>&1; then
   echo "⚠️  Remote path '$FOLDER' not listable via SFTP. It may not exist or permissions deny access." >&2
   echo "    Proceeding to mount; sshfs may fail if the path is invalid." >&2
 fi
 
+# Build ssh command used by sshfs (adds keepalive/connect-timeout, identity if present).
 SSH_CMD="ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=accept-new"
 # If identity options are present, append them to SSH_CMD
 if [[ ${#SSH_IDENTITY_OPTS[@]} -gt 0 ]]; then
@@ -140,6 +180,7 @@ if [[ ${#SSH_IDENTITY_OPTS[@]} -gt 0 ]]; then
   done
 fi
 
+# Perform the mount with reconnect/keepalive options for resilience.
 sshfs \
   -p "$PORT" \
   -o reconnect \