From bdf97e949909a5f5500f26e77a43311b4d022b48 Mon Sep 17 00:00:00 2001
From: "CanbiZ (MickLesk)" <47820557+MickLesk@users.noreply.github.com>
Date: Mon, 2 Mar 2026 09:54:15 +0100
Subject: [PATCH] Add tools/addon exit codes and use them

Introduce exit codes 232-238 for Tools & Addon scripts in misc/api.func and misc/error_handler.func. Update addon scripts (tools/addon/adguardhome-sync.sh, tools/addon/copyparty.sh, tools/addon/cronmaster.sh) to return specific codes instead of generic exit 1: 238 for unsupported OS and 233 when the application is not installed/upgrade prerequisites are missing. This makes failures more descriptive and aligns scripts with the central error explanations.
---
 misc/api.func                   | 10 ++++++++++
 misc/error_handler.func         | 10 ++++++++++
 tools/addon/adguardhome-sync.sh |  4 ++--
 tools/addon/copyparty.sh        |  4 ++--
 tools/addon/cronmaster.sh       |  4 ++--
 5 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/misc/api.func b/misc/api.func
index 9507ef2fd..9e1a50702 100644
--- a/misc/api.func
+++ b/misc/api.func
@@ -132,6 +132,7 @@ detect_repo_source
 #   * MySQL/MariaDB errors (180-183)
 #   * MongoDB errors (190-193)
 #   * Proxmox custom codes (200-231)
+#   * Tools & Addon Scripts (232-238)
 #   * Node.js/npm errors (239, 243, 245-249)
 # - Returns description string for given exit code
 # ------------------------------------------------------------------------------
@@ -302,6 +303,15 @@ explain_exit_code() {
   225) echo "Proxmox: No template available for OS/Version" ;;
   231) echo "Proxmox: LXC stack upgrade failed" ;;
 
+  # --- Tools & Addon Scripts (232-238) ---
+  232) echo "Tools: Wrong execution environment (run on PVE host, not inside LXC)" ;;
+  233) echo "Tools: Application not installed (update prerequisite missing)" ;;
+  234) echo "Tools: No LXC containers found or available" ;;
+  235) echo "Tools: Backup or restore operation failed" ;;
+  236) echo "Tools: Required hardware not detected" ;;
+  237) echo "Tools: Dependency package installation failed" ;;
+  238) echo "Tools: OS or distribution not supported for this addon" ;;
+
   # --- Node.js / npm / pnpm / yarn (239-249) ---
   239) echo "npm/Node.js: Unexpected runtime error or dependency failure" ;;
   243) echo "Node.js: Out of memory (JavaScript heap out of memory)" ;;
diff --git a/misc/error_handler.func b/misc/error_handler.func
index 85b755008..5f4a6258b 100644
--- a/misc/error_handler.func
+++ b/misc/error_handler.func
@@ -178,6 +178,16 @@ if ! declare -f explain_exit_code &>/dev/null; then
     224) echo "Proxmox: PBS storage is for backups only" ;;
     225) echo "Proxmox: No template available for OS/Version" ;;
     231) echo "Proxmox: LXC stack upgrade failed" ;;
+
+    # --- Tools & Addon Scripts (232-238) ---
+    232) echo "Tools: Wrong execution environment (run on PVE host, not inside LXC)" ;;
+    233) echo "Tools: Application not installed (update prerequisite missing)" ;;
+    234) echo "Tools: No LXC containers found or available" ;;
+    235) echo "Tools: Backup or restore operation failed" ;;
+    236) echo "Tools: Required hardware not detected" ;;
+    237) echo "Tools: Dependency package installation failed" ;;
+    238) echo "Tools: OS or distribution not supported for this addon" ;;
+
     239) echo "npm/Node.js: Unexpected runtime error or dependency failure" ;;
     243) echo "Node.js: Out of memory (JavaScript heap out of memory)" ;;
     245) echo "Node.js: Invalid command-line option" ;;
diff --git a/tools/addon/adguardhome-sync.sh b/tools/addon/adguardhome-sync.sh
index 480f7f198..4f597b536 100644
--- a/tools/addon/adguardhome-sync.sh
+++ b/tools/addon/adguardhome-sync.sh
@@ -69,7 +69,7 @@ elif [[ -f "/etc/debian_version" ]]; then
   SERVICE_PATH="/etc/systemd/system/adguardhome-sync.service"
 else
   msg_error "Unsupported OS detected. Exiting."
-  exit 1
+  exit 238
 fi
 
 # ==============================================================================
@@ -312,7 +312,7 @@ if [[ "${type:-}" == "update" ]]; then
     update
   else
     msg_error "${APP} is not installed. Nothing to update."
-    exit 1
+    exit 233
   fi
   exit 0
 fi
diff --git a/tools/addon/copyparty.sh b/tools/addon/copyparty.sh
index f13bfa2c1..b0ba19b77 100644
--- a/tools/addon/copyparty.sh
+++ b/tools/addon/copyparty.sh
@@ -49,7 +49,7 @@ elif grep -qE 'ID=debian|ID=ubuntu' /etc/os-release; then
   SERVICE_PATH="/etc/systemd/system/copyparty.service"
 else
   msg_error "Unsupported OS detected. Exiting."
-  exit 1
+  exit 238
 fi
 
 # ==============================================================================
@@ -318,7 +318,7 @@ if [[ "${type:-}" == "update" ]]; then
     update
   else
     msg_error "${APP} is not installed. Nothing to update."
-    exit 1
+    exit 233
   fi
   exit 0
 fi
diff --git a/tools/addon/cronmaster.sh b/tools/addon/cronmaster.sh
index 8645f6a30..8973188d4 100644
--- a/tools/addon/cronmaster.sh
+++ b/tools/addon/cronmaster.sh
@@ -51,7 +51,7 @@ EOF
 # ==============================================================================
 if ! grep -qE 'ID=debian|ID=ubuntu' /etc/os-release 2>/dev/null; then
   echo -e "${CROSS} Unsupported OS detected. This script only supports Debian and Ubuntu."
-  exit 1
+  exit 238
 fi
 
 # ==============================================================================
@@ -183,7 +183,7 @@ if [[ "${type:-}" == "update" ]]; then
     update
   else
     msg_error "${APP} is not installed. Nothing to update."
-    exit 1
+    exit 233
   fi
   exit 0
 fi