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
@@ -1,19 +1,77 @@
 #!/bin/bash
-# Varaverk job runner — wraps script execution with JSON status tracking.
-# Called by /etc/cron.d/varaverk for every scheduled job.
+# ==============================================================================================
+# ============================= Job Runner =====================================================
+# ==============================================================================================
 #
-# Usage: bash run_job.sh <job_id> <script_path> [flags...]
+# PURPOSE
+# ─────────────────────────────────────────────────────────────────────────────
+# Wraps every scheduled script execution with JSON status tracking and log
+# management. Called by /etc/cron.d/varaverk for every scheduled job. The PHP
+# dashboard polls the JSON files to show live job status without running scripts.
 #
-# Flags consumed by run_job.sh (stripped before passing to script):
-#   --manual   — marks a UI-triggered run; writes a sentinel on completion so
-#                the next cron fire is suppressed if it falls within the job's
-#                own cron interval (prevents double-firing after manual run).
+# ==============================================================================================
+# OPERATIONAL MODEL
+# ==============================================================================================
 #
-# Writes: /var/log/varaverk/<id>.json — status, timestamps, exit code, pid
-#         /var/log/varaverk/<id>.log  — appended per run, trimmed to LOG_MAX_LINES
-#         /var/log/varaverk/<id>.manual_ts — sentinel: epoch of last manual completion
+# Invocation: bash run_job.sh <job_id> <script_path> [flags...]
+#
+# Writes three files per job to /var/log/varaverk/:
+#   <id>.json       — status, timestamps, exit code, pid (polled by WebGUI)
+#   <id>.log        — appended per run, trimmed to LOG_MAX_LINES lines
+#   <id>.manual_ts  — sentinel: epoch of last manual completion (interval suppression)
 #
 # Status values: running → ok (exit 0) | warn (exit 1) | error (exit 2+)
+#
+# MANUAL FLAG
+#   --manual marks a UI-triggered run. On completion, writes a manual_ts sentinel.
+#   The next cron fire reads the sentinel and suppresses itself if the elapsed time
+#   is within the job's own cron interval — prevents double-firing after a manual run.
+#   Static schedules (e.g. "30 2 * * 0") are never suppressed — only */N intervals.
+#
+# ==============================================================================================
+# DESIGN PRINCIPLES
+# ==============================================================================================
+#
+# Suppress Double-Fire
+#   When a user triggers a job from the UI, the next cron fire within the job's
+#   own interval is skipped. A 30-minute cron job triggered at HH:14 won't fire
+#   again at HH:30 — it waits for HH:44. Static schedules are never suppressed.
+#
+# Status as Ground Truth
+#   The JSON file is overwritten atomically on every state change (start → end).
+#   The WebGUI polls it directly — no additional IPC or database needed.
+#
+# Log Trim on Every Write
+#   The log file is trimmed to LOG_MAX_LINES after every run. Never grows
+#   unbounded regardless of how long the server runs or how often the job fires.
+#
+# ==============================================================================================
+# OPERATIONAL SAFEGUARDS
+# ==============================================================================================
+#
+#   --manual stripped   — flag consumed here, never passed to the wrapped script
+#   mkdir -p            — log dir created if missing before any write
+#   Log trim            — tail -n LOG_MAX_LINES via tmp file + mv (atomic)
+#   Sentinel cleanup    — manual_ts removed after it's used or expired
+#
+# ==============================================================================================
+# CONFIGURATION
+# ==============================================================================================
+#
+#   LOG_DIR        /var/log/varaverk    (hardcoded — tmpfs on Unraid, cleared on reboot)
+#   LOG_MAX_LINES  1000                 (hardcoded — trim threshold per job log)
+#
+# ==============================================================================================
+# RUNTIME MODES
+# ==============================================================================================
+#
+# bash run_job.sh <job_id> <script_path> [script_flags...]
+#     Normal cron-triggered run.
+#
+# bash run_job.sh <job_id> <script_path> --manual [script_flags...]
+#     UI-triggered run. Suppresses next cron fire within the job's interval.
+#
+# ==============================================================================================

 JOB_ID="$1"
 SCRIPT="$2"