fix(plugin-manager): explain why an update failed validation (cause + remediation)

Classify the validation failure in pre_plugin_checks instead of surfacing the
raw txz error: distinguish low disk space (reporting actual free space), a
download/network failure, and a genuine bad hash. Store a short summary plus a
full actionable message in the marker.

ShowPlugins.php shows the short cause as a visible second line under the
"update validation failed" status and puts the full guidance in the tooltip,
so the status answers "why did this fail and what do I do" instead of raising
questions.

Wording follows existing GUI conventions: lowercase status label like the other
plugin statuses (up-to-date, cannot check, not available) and terse messages in
the style of "Not enough free space, need at least %s MB". The hook runs without
the gettext setup, so its strings are plain (the prior code also echoed
untranslated reasons); only ShowPlugins.php uses _().

Author: elibosley

emhttp/plugins/dynamix.plugin.manager/include/ShowPlugins.php

@@ -196,17 +196,19 @@
         $info   = json_decode(file_get_contents($invalid),true) ?: [];
         $newver = (string)($info['version'] ?? '');
         if ($newver !== '' && strcmp($newver,$version) > 0) {
-          $reason  = trim((string)($info['reason'] ?? ''));
+          $summary = trim((string)($info['summary'] ?? $info['reason'] ?? ''));
+          $message = trim((string)($info['message'] ?? $summary));
           $version .= "<br><span class='red-text'>$newver</span>";
-          $status  = "<span class='warning'".($reason ? " title='".htmlspecialchars($reason,ENT_QUOTES)."'" : "")."><i class='fa fa-exclamation-triangle' aria-hidden='true'></i> "._('Update validation failed')."</span>";
+          $status  = "<span class='warning'".($message ? " title='".htmlspecialchars($message,ENT_QUOTES)."'" : "")."><i class='fa fa-exclamation-triangle' aria-hidden='true'></i> "._('update validation failed')."</span>";
+          if ($summary !== '') $status .= "<br><span class='orange-text' style='font-size:smaller'>".htmlspecialchars($summary,ENT_QUOTES)."</span>";
         } else {
           @unlink($invalid);
         }
       }
     }
     if (strpos($status,'update')!==false) $rank = '0';
     elseif (strpos($status,'install')!==false) $rank = '1';
-    elseif (strpos($status,'Update validation failed')!==false) $rank = '0';
+    elseif (strpos($status,'update validation failed')!==false) $rank = '0';
     elseif ($status=='need check') $rank = '2';
     elseif ($status=='up-to-date') $rank = '3';
     else $rank = '4';

emhttp/plugins/dynamix.plugin.manager/pre-hooks/pre_plugin_checks

@@ -49,12 +49,36 @@ case 'plugin':
       exec("$docroot/plugins/dynamix.plugin.manager/scripts/plugin validate ".escapeshellarg($new_plugin)." 2>&1", $output, $retval);
       if ($retval != 0) {
         $reason = trim(preg_replace('/^plugin:\s*/m', '', implode("\n", $output)));
-        echo ($reason ?: 'validation failed')."\n";
-        // An update is available but failed validation. Record why so the webGUI
-        // can surface it, instead of silently reverting to "up-to-date". The most
-        // common cause is the update files not downloading because the root
-        // filesystem is full.
-        file_put_contents($invalid, json_encode(['version'=>$new_version, 'reason'=>$reason]));
+        // Classify the failure so the webGUI can explain it (and what to do)
+        // instead of silently reverting to "up-to-date". Validation downloads
+        // the update's files to /tmp (rootfs) and checks their hash, so the
+        // usual culprits are a full root filesystem, a transient network error,
+        // or a genuine bad hash.
+        $free_kb = (int)trim((string)@shell_exec("df -Pk /tmp 2>/dev/null | awk 'NR==2{print \$4}'"));
+        $free_mb = $free_kb > 0 ? intdiv($free_kb, 1024) : 0;
+        if (stripos($reason, 'hash') !== false) {
+          $category = 'integrity';
+          $summary  = 'integrity check failed (bad hash)';
+          $message  = 'The update failed its integrity check (bad hash). The download may be incomplete or corrupt. Check for updates again shortly.';
+        } elseif ($free_kb > 0 && $free_kb < 102400) {
+          $category = 'diskspace';
+          $summary  = 'low on disk space';
+          $message  = sprintf('Not enough free space to download and verify the update (%s MB free). Free up space and check for updates again.', $free_mb);
+        } else {
+          $category = 'download';
+          $summary  = 'update files could not be downloaded';
+          $message  = 'Could not download the update files to verify them. This may be a temporary network problem. Check for updates again shortly.';
+        }
+        echo "$message\n";
+        // An update is available but failed validation. Record the available
+        // version and the classified reason so the webGUI can surface it.
+        file_put_contents($invalid, json_encode([
+          'version'  => $new_version,
+          'category' => $category,
+          'summary'  => $summary,
+          'message'  => $message,
+          'reason'   => $reason,
+        ]));
         // restore original plugin and undo update
         copy($plugin, $new_plugin);
       } else {