fix: report GitHub icon indexing failures clearly (#7008)

apps/docs/docs/advanced/icons/index.mdx

@@ -23,6 +23,8 @@ Icons in Homarr are automatically requested from multiple sources:
 Using these icon sources, Homarr provides a total collection of over 11,000 icons at your fingertips.
 The image picker searches this collection after a short typing delay. When a name is available, such as an app or search engine name, the picker uses it as the initial search. Results show your locally uploaded images first, followed by SVG icons and then other image formats.
 
+GitHub icon indexes are refreshed on startup and weekly. A GitHub rate limit can temporarily prevent Dashboard Icons, selfh.st, and Simple Icons from refreshing; previously cached icons remain available. Invalid or incomplete GitHub tree responses also leave the cached provider icons intact. The server log reports the HTTP status and, when GitHub provides them, remaining request quota and reset time (Unix seconds). After the limit resets, an administrator can rerun **Icons Updater** under **Manage → Tools → Tasks**. Direct image URLs and local uploads remain usable while indexing is unavailable.
+
 ### Finding Missing Icons
 
 If you can't find the icon you're looking for in Homarr's built-in picker, we strongly recommend checking [Dashboard Icons](https://dashboardicons.com/). It offers a modern, user-friendly interface and a curated collection of high-quality icons specifically designed for dashboards and app directories.

packages/icons/src/repositories/github.icon-repository.ts

@@ -2,6 +2,7 @@ import { parse } from "path";
 
 import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";
 import { withTimeoutAsync } from "@homarr/core/infrastructure/http/timeout";
+import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
 
 import type { IconRepositoryLicense } from "../types/icon-repository-license";
 import type { RepositoryIconGroup } from "../types/repository-icon-group";
@@ -26,7 +27,26 @@ export class GitHubIconRepository extends IconRepository {
     }
 
     const response = await withTimeoutAsync(async (signal) => fetchWithTrustedCertificatesAsync(url, { signal }));
-    const listOfFiles = (await response.json()) as GitHubApiResponse;
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new ErrorWithMetadata("GitHub icon index request failed", {
+        status: response.status,
+        rateLimitRemaining: response.headers.get("x-ratelimit-remaining"),
+        rateLimitReset: response.headers.get("x-ratelimit-reset"),
+        retryAfter: response.headers.get("retry-after"),
+      });
+    }
+
+    const listOfFiles = (await response.json()) as GitHubApiResponse | null;
+    if (!listOfFiles || !Array.isArray(listOfFiles.tree)) {
+      throw new Error("GitHub icon index response does not contain a file tree");
+    }
+    if (typeof listOfFiles.truncated !== "boolean") {
+      throw new Error("GitHub icon index response does not contain a boolean truncated flag");
+    }
+    if (listOfFiles.truncated) {
+      throw new Error("GitHub icon index response contains a truncated file tree");
+    }
 
     return {
       success: true,