Add full banner headers to all scripts across the codebase

Every script now has the established header format: PURPOSE with ─────── separator, OPERATIONAL MODEL, DESIGN PRINCIPLES, OPERATIONAL SAFEGUARDS, CONFIGURATION, and RUNTIME MODES — structured with full ====== banner sections throughout. Orchestrators converted from compact ── inline format to full banners. Stale emby-fallback and dirty sync references removed from Plugin/user_script_plug-in.sh.
2026-06-26 18:50:05 -04:00
parent 1003bee72a
commit f92ee4064b
51 changed files with 1822 additions and 563 deletions
@@ -2,35 +2,63 @@
 # ==============================================================================================
 # ================================= Git Pull & Execute =========================================
 # ==============================================================================================
-# Pulls the latest scripts from the Gitea repository via SSH.
-# Lives at the repo root — sources load_config.sh from the same directory.
 #
-# ── WHAT THIS SCRIPT DOES ─────────────────────────────────────────────────────────────────────
-# 1. Detects which server it's running on via detect_hosts() (MY_ID)
-# 2. Configures sparse checkout to exclude other servers' credential files
-#    Each server only pulls its own host*.conf — never sees peer credentials
-# 3. Pulls or clones latest scripts from Gitea
-# 4. Sets executable permissions on all .sh files
+# PURPOSE
+# ─────────────────────────────────────────────────────────────────────────────
+# Pulls the latest scripts from the Gitea repository via SSH. Lives at the repo
+# root — sources load_config.sh from the same directory.
 #
-# ── SPARSE CHECKOUT ───────────────────────────────────────────────────────────────────────────
-# Sparse checkout ensures each server only receives its own host conf:
-#   HOST1 pulls:  master.conf + host1.conf + all scripts
-#   HOST1 skips:  host2.conf, host3.conf etc.
-#   HOST2 pulls:  master.conf + host2.conf + all scripts
-#   HOST2 skips:  host1.conf, host3.conf etc.
+# ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
 #
-# Adding a new server:
-#   Create host3.conf in the repo
-#   All existing servers automatically exclude it on next pull
-#   New server gets only its own conf ✅
+#   1. detect_hosts() — identifies which server is running the pull (MY_ID)
+#   2. Configure sparse checkout — exclude other servers' credential files
+#   3. Pull or clone latest scripts from Gitea
+#   4. Set executable permissions on all .sh files
 #
-# ── GITEA LOCATION DETECTION ──────────────────────────────────────────────────────────────────
-# Detects where Gitea is running at runtime — works through fallback:
-#   Gitea local  → connects via local IP
-#   Gitea remote → connects via Tailscale IP
-#   Both fail    → falls back to GITEA_DOMAIN if configured
+# SPARSE CHECKOUT
+#   Each server only receives its own host conf — never peer credentials:
+#     HOST1 pulls:  master.conf + host1.conf + all scripts
+#     HOST1 skips:  host2.conf, host3.conf etc.
+#   Adding a new server: create host3.conf in the repo — all existing servers
+#   automatically exclude it on next pull; new server gets only its own conf.
+#
+# GITEA LOCATION DETECTION
+#   Detected at runtime — works through fallback:
+#     Gitea local  → connects via local IP
+#     Gitea remote → connects via Tailscale IP
+#     Both fail    → falls back to GITEA_DOMAIN if configured
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Credentials Stay Separated
+#   Sparse checkout is configured per-server on every pull, not just at clone
+#   time. Ensures newly added host confs are automatically excluded on all
+#   existing servers without any manual intervention.
+#
+# Runtime Location Detection
+#   Gitea's IP is never hardcoded — the script probes whether Gitea is local
+#   or remote on every run. Handles Gitea container restarts, migrations, and
+#   Tailscale address changes automatically.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+#   Root check      — git operations on /boot require root
+#   acquire_lock    — prevents concurrent pulls
+#   detect_hosts()  — MY_ID required to build correct sparse checkout rules
+#   Docker check    — Gitea container status probed before any SSH attempt
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+# master.conf
 #
-# ── CONFIGURATION (master.conf) ───────────────────────────────────────────────────────────────
 #   GITEA_CONTAINER  — Docker container name for Gitea
 #   GITEA_REPO_PATH  — repo path on Gitea (e.g. Varaverk/varaverk.git)
 #   GITEA_DOMAIN     — public domain fallback (optional)
@@ -38,11 +66,22 @@
 #   GITEA_SSH_KEY    — SSH key for Gitea authentication
 #   SSH_PORT         — Gitea SSH port (often 221 or 222)
 #
-# ── USAGE ─────────────────────────────────────────────────────────────────────────────────────
-#   git_pull_execute.sh              — normal pull
-#   git_pull_execute.sh --dry-run    — preview without making changes
-#   git_pull_execute.sh --log        — verbose output
-#   git_pull_execute.sh --status     — show config and exit
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# git_pull_execute.sh
+#     Normal pull.
+#
+# git_pull_execute.sh --dry-run
+#     Preview without making changes.
+#
+# git_pull_execute.sh --log
+#     Verbose output.
+#
+# git_pull_execute.sh --status
+#     Show config and exit.
+#
 # ==============================================================================================

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"