@silentjma/n8n-nodes-unraid 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this package. Versions follow [semver](https://semver.org/).
+
+## Unreleased
+
+### Project
+- Community files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, SUPPORT, issue and pull request templates, Dependabot.
+- CI on every push and pull request. A release workflow publishes to npm with provenance when a `v*` tag is pushed.
+- Buy Me a Coffee funding link.
+
+## 0.1.0 - 2026-10-25
+
+First release.
+
+### Nodes
+- **Unraid** action node:
+  - System: health report with suggested next steps, info, metrics.
+  - Array: status, start, stop, parity check start, pause, resume and cancel, parity history.
+  - Disks and shares.
+  - Docker: list, get, logs (analysed), update status, check for updates, start, stop, restart, pause, unpause, update one or more containers, update all.
+  - VMs: list, start, stop, force stop, pause, resume, reboot, reset.
+  - Log files: list and read, with a regex filter and severity analysis.
+  - Notifications: create (optionally only if unique), list, overview, warnings and alerts, archive.
+  - Custom GraphQL.
+- **Unraid Trigger** polling events: log file lines, container log lines, health problems (optionally resolved ones too), new notifications, container state changes, container updates available.
+- **Unraid API** credential: server URL, `x-api-key`, and an option to accept self-signed certificates. The credential test fails on a revoked or invalid key, even though Unraid answers those with HTTP 200.
+- Containers can be given by name, ID or command-safe name (`plex_media_server`).
+- Built-in rules for log lines and health findings, each with next steps:
+  - Logs: disk I/O, filesystem corruption, OOM, hardware/MCE, kernel traces, disk space, parity, auth failures, segfaults, Docker, network, temperature, application fatal errors.
+  - Health: array state, disk status, errors, temperature (separate HDD and SSD thresholds) and usage, SMART, parity, stopped autostart containers, updates, memory, CPU, Unraid alerts.
+
+### Workflows
+- `unraid-alerts.json`, `unraid-docker.json` and `unraid-sysadmin-bot.json`: alerts, Docker updates and on-demand actions, and sysadmin commands, all managed from a Telegram bot.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Ayoub Jabane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# @silentjma/n8n-nodes-unraid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@silentjma/n8n-nodes-unraid?logo=npm)](https://www.npmjs.com/package/@silentjma/n8n-nodes-unraid)
+[![CI](https://github.com/SilentJMA/n8n-nodes-unraid/actions/workflows/ci.yml/badge.svg)](https://github.com/SilentJMA/n8n-nodes-unraid/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-support-FFDD00?logo=buymeacoffee&logoColor=black)](https://www.buymeacoffee.com/kilwanitrod)
+
+Unofficial n8n community nodes for the [Unraid API](https://docs.unraid.net/API/) (GraphQL, [unraid/api](https://github.com/unraid/api)).
+
+- **Unraid**: an action node for System, Array, Disk, Share, Docker Container, Virtual Machine, Log File and Notification, plus a Custom GraphQL operation.
+- **Unraid Trigger**: a polling trigger for new log lines (syslog or a container log), health problems, notifications, container state changes and container updates.
+
+Both nodes use the same built-in rules ([src/lib/analysis.ts](src/lib/analysis.ts)). The rules tag log lines and health findings as `info`, `warning` or `critical` and attach **suggested next steps**.
+
+## Installation
+
+**Community Nodes (recommended):** in n8n, open **Settings › Community Nodes › Install** and enter `@silentjma/n8n-nodes-unraid`.
+
+**Manual / custom folder:** run `npm pack` and extract the tarball's `package/` folder into `~/.n8n/custom/n8n-nodes-unraid`. In Docker that is `/home/node/.n8n/custom`, which on Unraid is usually `/mnt/user/appdata/n8n/custom`. Then restart n8n.
+
+Prefer workflows without a community node? [n8n-unraid-telegram-workflows](https://github.com/SilentJMA/n8n-unraid-telegram-workflows) has the same three workflows built only from n8n's built-in nodes.
+
+## Requirements
+
+- Unraid 7.2+ has the API built in. Older versions need the Unraid Connect plugin.
+- An API key, created in **Settings › Management Access › API Keys** or with `unraid-api apikey --create`. Read operations work with a read-only role. Updates, restarts and array/VM control need **admin**.
+
+## Credential: Unraid API
+
+| Field | Notes |
+| --- | --- |
+| Server URL | WebGUI base URL, e.g. `https://192.168.1.10`. Requests go to `<url>/graphql` with header `x-api-key`. Use https when SSL is enabled: Unraid redirects http, and the request body is lost. |
+| API Key | The key from the WebGUI |
+| Ignore SSL Issues | For self-signed certificates |
+
+## Unraid node operations
+
+| Resource | Operations |
+| --- | --- |
+| System | Get Health Report (findings + next steps), Get Info, Get Metrics |
+| Array | Get Status, Start, Stop, Start / Pause / Resume / Cancel Parity Check, Get Parity History |
+| Disk / Share | Get Many |
+| Docker Container | Get, Get Many (filters: state, updates only, autostart, name), Get Logs (analysed), Get Update Status, Check for Updates, Start, Stop, Restart, Pause, Unpause, Update (one or many), Update All |
+| Virtual Machine | Get Many, Start, Stop, Force Stop, Pause, Resume, Reboot, Reset |
+| Log File | Get Many (`/var/log`), Read (last N lines or from a line; regex filter; analysis; one item or one per line) |
+| Notification | Create (optionally only if unique), Get Many, Get Overview, Get Warnings and Alerts, Archive, Archive All |
+| Custom GraphQL | Execute any query or mutation |
+
+Containers can be given by **name** (`plex`) or ID.
+
+## Unraid Trigger events
+
+| Event | Fires on |
+| --- | --- |
+| Log File Line | New lines in a `/var/log` file at or above the minimum severity. Tracks the line count and handles log rotation. |
+| Container Log Line | New lines in a container's log (cursor based) |
+| Health Problem | A finding not reported before. Can also emit "resolved" items. |
+| New Notification | New unread Unraid notification at or above an importance |
+| Container State Changed | Start / stop / pause / removal |
+| Container Update Available | A container newly has an image update |
+
+On the first poll, the trigger only records a baseline. Turn on *Emit Existing on First Poll* to also get what already exists. Manual "Fetch Test Event" always returns current data.
+
+## Workflows (managed from Telegram)
+
+`npm run workflow` ([scripts/build-workflows.mjs](scripts/build-workflows.mjs)) generates three workflows in [workflows/](workflows/):
+
+| Workflow | Triggers | What it does |
+| --- | --- | --- |
+| [Unraid · Alerts](workflows/unraid-alerts.json) | Syslog every minute, health report every 5 min | Sends each new problem to Telegram with suggested next steps and tappable follow-up commands (`/logs_sonarr`, `/disks`…). Repeats are throttled (60 min per alert key). Optional: AI triage (disabled by default), an Unraid notification as well, and automatic restart of stopped autostart containers. |
+| [Unraid · Docker updates & actions](workflows/unraid-docker.json) | Weekly (Sun 04:00), and called by the bot | Weekly: updates every container that has a new image, except `cfg.excludeFromUpdates`. It reports only when something changed. Also answers the Docker commands. |
+| [Unraid · Sysadmin & Telegram bot](workflows/unraid-sysadmin-bot.json) | Telegram Trigger | The bot. Answers the sysadmin commands and forwards Docker commands to the Docker workflow. |
+
+A Telegram bot delivers updates to a single webhook, so **only the bot workflow has a Telegram Trigger**. The other two just send messages.
+
+### Commands
+
+| Server | Docker |
+| --- | --- |
+| `/status`: health report with next steps | `/containers`: list with quick actions |
+| `/info`: uptime, CPU, RAM, array usage | `/updates`: check for image updates |
+| `/disks`: status, temperature, usage, errors | `/update_all`: update all (asks first) |
+| `/parity`, `/parity_start` (asks first), `/parity_pause`, `/parity_resume`, `/parity_cancel` | `/update_<name>`, `/restart_<name>`, `/start_<name>` |
+| `/syslog`: recent warnings with next steps | `/stop_<name>` (asks first) |
+| `/notifications`, `/archive_all` | `/logs_<name>`: last lines, analysed |
+| `/vms`, `/help` | |
+
+Telegram commands allow only `a-z0-9_`, so container names are written with underscores: `Plex-Media-Server` becomes `/logs_plex_media_server`. Actions that ask first reply with a `…_confirm` command to tap.
+
+For autocomplete, send this to @BotFather with `/setcommands`:
+
+```text
+status - Health report with next steps
+info - Uptime, CPU, RAM, array usage
+disks - Disk status and temperatures
+containers - Docker containers with quick actions
+updates - Check for container updates
+syslog - Recent syslog warnings
+parity - Parity check status
+notifications - Unread Unraid notifications
+help - All commands
+```
+
+### Setup
+
+1. Create a bot with @BotFather and add a **Telegram** credential in n8n with its token.
+2. Import the three workflows. In each one, select the **Unraid API** credential (`https://192.168.178.2`, Ignore SSL Issues on) and the Telegram credential.
+3. Publish the **Sysadmin & Telegram bot** workflow and send the bot any message. While `cfg.allowedChatIds` is empty, the bot only replies with your chat ID and runs nothing else.
+4. Put that ID in **Bot settings › cfg.allowedChatIds**, **Alert settings › cfg.telegramChatId** and **Settings › cfg.telegramChatId** (Docker workflow). After that, the bot ignores every other chat.
+5. In the bot's **Run Docker workflow** node, pick *Unraid · Docker updates & actions*. Alternatively, regenerate with `DOCKER_WORKFLOW_ID=<id> npm run workflow` and re-import.
+6. Publish the Docker and Alerts workflows.
+
+Keep **n8n** in `cfg.excludeFromUpdates`. Updating it recreates the container that is running the workflow, so the run is cut off and no report arrives.
+
+The workflows use node types `CUSTOM.unraid` / `CUSTOM.unraidTrigger`, which n8n uses for nodes in `~/.n8n/custom`. If you install the package through Community Nodes, generate with `UNRAID_NODE_PREFIX=@silentjma/n8n-nodes-unraid npm run workflow`.
+
+## Development
+
+See [AGENT.md](AGENT.md) for the full maintenance and release procedure.
+
+```bash
+npm install
+npm run build && npm run lint && npm run typecheck && npm test
+npm pack   # -> silentjma-n8n-nodes-unraid-0.1.0.tgz
+```
+
+The queries in [src/lib/queries.ts](src/lib/queries.ts) are written against `api/generated-schema.graphql` from the unraid/api repository. Check them again when Unraid changes the schema.
+
+## Support and contributing
+
+- **Questions:** [Discussions › Q&A](https://github.com/SilentJMA/n8n-nodes-unraid/discussions/categories/q-a). Common problems are listed in [SUPPORT.md](SUPPORT.md).
+- **Bugs and feature requests:** [open an issue](https://github.com/SilentJMA/n8n-nodes-unraid/issues/new/choose) using the templates. Never paste API keys or tokens.
+- **Security:** report privately, see [SECURITY.md](SECURITY.md).
+- **Contributing:** pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+If these nodes save you time, you can support the project:
+
+<a href="https://www.buymeacoffee.com/kilwanitrod"><img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=kilwanitrod&button_colour=FFDD00&font_colour=000000&font_family=Inter&outline_colour=000000&coffee_colour=ffffff" alt="Buy me a coffee" height="40"></a>
+
+## License
+
+[MIT](LICENSE). Not affiliated with or endorsed by Lime Technology / Unraid.

package/dist/credentials/UnraidApi.credentials.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnraidApi = void 0;
+class UnraidApi {
+    name = 'unraidApi';
+    displayName = 'Unraid API';
+    documentationUrl = 'https://docs.unraid.net/API/how-to-use-the-api/';
+    properties = [
+        {
+            displayName: 'Server URL',
+            name: 'serverUrl',
+            type: 'string',
+            default: 'https://tower.local',
+            placeholder: 'https://192.168.1.10',
+            required: true,
+            description: 'Base URL of the Unraid WebGUI; requests go to /graphql. Use https:// when SSL is enabled (Unraid redirects http:// and the request would fail).',
+        },
+        {
+            displayName: 'API Key',
+            name: 'apiKey',
+            type: 'string',
+            typeOptions: { password: true },
+            default: '',
+            required: true,
+            description: 'Created in Settings › Management Access › API Keys (or "unraid-api apikey --create"). Docker updates, array and VM control need the admin role.',
+        },
+        {
+            displayName: 'Ignore SSL Issues',
+            name: 'allowUnauthorizedCerts',
+            type: 'boolean',
+            default: false,
+            description: 'Whether to connect even if the server uses a self-signed or otherwise invalid certificate (the default for Unraid on a LAN IP)',
+        },
+    ];
+    authenticate = {
+        type: 'generic',
+        properties: {
+            headers: {
+                'x-api-key': '={{$credentials.apiKey}}',
+            },
+        },
+    };
+    test = {
+        request: {
+            baseURL: '={{$credentials.serverUrl.replace(/\\/+$/, "")}}',
+            url: '/graphql',
+            method: 'POST',
+            skipSslCertificateValidation: '={{$credentials.allowUnauthorizedCerts}}',
+            headers: { 'Content-Type': 'application/json' },
+            body: { query: '{ online info { os { hostname } } }' },
+        },
+        // Unraid answers HTTP 200 with a GraphQL error for a bad key, so check the body.
+        rules: [
+            {
+                type: 'responseSuccessBody',
+                properties: { key: 'errors[0].extensions.code', value: 'UNAUTHENTICATED', message: 'Invalid or revoked API key' },
+            },
+            {
+                type: 'responseSuccessBody',
+                properties: { key: 'errors[0].extensions.code', value: 'FORBIDDEN', message: 'The API key may not read server info; give it at least a read role' },
+            },
+        ],
+    };
+}
+exports.UnraidApi = UnraidApi;

package/dist/lib/analysis.js

@@ -0,0 +1,398 @@
+"use strict";
+// Pure analysis helpers: turn Unraid API snapshots and log lines into findings with suggested next steps.
+// No n8n imports so the rules can be unit-tested and reused by both nodes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_HEALTH_OPTIONS = exports.LOG_RULE_NAMES = void 0;
+exports.severityAtLeast = severityAtLeast;
+exports.sortFindings = sortFindings;
+exports.containerName = containerName;
+exports.classifyLogLine = classifyLogLine;
+exports.analyzeHealth = analyzeHealth;
+exports.summarizeFindings = summarizeFindings;
+const SEVERITY_RANK = { info: 0, warning: 1, critical: 2 };
+function severityAtLeast(severity, minimum) {
+    return SEVERITY_RANK[severity] >= SEVERITY_RANK[minimum];
+}
+function sortFindings(findings) {
+    return [...findings].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity] || a.key.localeCompare(b.key));
+}
+/** Docker names come back as ["/plex"]; the first one without the slash is what the WebGUI shows. */
+function containerName(container) {
+    const first = container.names?.find((n) => n) ?? container.id ?? '';
+    return first.replace(/^\//, '');
+}
+const num = (value) => {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+const pct = (used, total) => {
+    const u = num(used);
+    const t = num(total);
+    return u !== undefined && t ? Math.round((u / t) * 1000) / 10 : undefined;
+};
+const LOG_RULES = [
+    {
+        rule: 'disk-io-error',
+        pattern: /\b(I\/O error|blk_update_request|critical medium error|Buffer I\/O error|md: disk\d+ (read|write) error|ata\d+(\.\d+)?: .*(failed command|exception|hard resetting link|link is slow|SError)|UNC\b|end_request)/i,
+        severity: 'critical',
+        category: 'disk',
+        nextSteps: [
+            'Identify the disk from the ataX / sdX / diskN in the line (Tools › System Devices or Main tab).',
+            'Run a SMART extended test on that disk and check reallocated / pending sector counts.',
+            'Reseat or replace the SATA/SAS cable and power cable; link resets are usually cabling.',
+            'If the disk is disabled in the array, do not write to it; rebuild from parity once the cause is fixed.',
+        ],
+    },
+    {
+        rule: 'filesystem-corruption',
+        pattern: /\b(BTRFS (error|critical|warning)|XFS \(.*\): (Corruption|Metadata|Internal error|log I\/O error)|EXT4-fs error|ZFS.*(error|faulted|degraded)|checksum error|csum failed|parent transid verify failed)/i,
+        severity: 'critical',
+        category: 'filesystem',
+        nextSteps: [
+            'Note the affected device (e.g. md1p1, nvme0n1p1) and stop writing to it.',
+            'Start the array in maintenance mode and run a filesystem check (Main › disk › Check Filesystem Status).',
+            'For BTRFS pools run a scrub; for ZFS run "zpool status -v" and a scrub.',
+            'Run memtest if checksum errors keep appearing on several devices (bad RAM causes them).',
+        ],
+    },
+    {
+        rule: 'out-of-memory',
+        pattern: /\b(Out of memory|oom-kill|oom_reaper|invoked oom-killer|Killed process \d+)/i,
+        severity: 'critical',
+        category: 'memory',
+        nextSteps: [
+            'Find the killed process / container in the line and set a memory limit on it (--memory=… in Extra Parameters).',
+            'Check for containers writing to RAM (paths mapped to /tmp or not to /mnt/user) filling the rootfs.',
+            'Review VM memory allocations against total RAM.',
+        ],
+    },
+    {
+        rule: 'hardware-mce',
+        pattern: /\b(Machine check|mce: \[Hardware Error\]|Hardware Error|EDAC .*(error|CE|UE)|PCIe Bus Error|AER: (Corrected|Uncorrected))/i,
+        severity: 'critical',
+        category: 'hardware',
+        nextSteps: [
+            'Install mcelog (NerdTools / Nerd Pack) to decode the machine check, or check the BIOS event log.',
+            'Run memtest86 for at least one full pass.',
+            'Update the BIOS and check CPU / VRM temperatures and PSU health.',
+        ],
+    },
+    {
+        rule: 'kernel-trace',
+        pattern: /\b(Call Trace|kernel BUG|general protection fault|Kernel panic|BUG: unable to handle|watchdog: BUG: soft lockup|rcu_sched self-detected stall|macvlan.*(call trace|broadcast))/i,
+        severity: 'critical',
+        category: 'kernel',
+        nextSteps: [
+            'Download diagnostics (Tools › Diagnostics) while the trace is still in the syslog.',
+            'If the trace mentions macvlan, switch Docker custom networks to ipvlan (Settings › Docker).',
+            'Check that Unraid and plugins are up to date; post the diagnostics on the Unraid forum if it repeats.',
+        ],
+    },
+    {
+        rule: 'disk-space',
+        pattern: /\b(No space left on device|disk quota exceeded|cache.*(full|is full)|docker\.img.*(full|100%)|ENOSPC)/i,
+        severity: 'critical',
+        category: 'storage',
+        nextSteps: [
+            'Check docker.img / cache / array usage on the Main tab.',
+            'Run the Mover if the cache is full, and set a minimum free space on shares.',
+            'Find containers writing inside docker.img (Docker › Container Size) and map their paths to appdata.',
+        ],
+    },
+    {
+        rule: 'parity-errors',
+        pattern: /\b(parity (check|sync).*(error|incorrect)|sync errors?|Parity.*finished.*\d+ errors)/i,
+        severity: 'warning',
+        category: 'parity',
+        nextSteps: [
+            'If this follows an unclean shutdown, run a correcting parity check.',
+            'If errors repeat on consecutive checks, run memtest and check disk SMART data.',
+        ],
+    },
+    {
+        rule: 'auth-failure',
+        pattern: /\b(authentication failure|Failed password|Invalid user|Failed login|webGUI: Unsuccessful login|refused connect|Bad protocol version)/i,
+        severity: 'warning',
+        category: 'security',
+        nextSteps: [
+            'Check the source IP: if it is not on your LAN, the server is exposed to the internet.',
+            'Disable port forwarding for SSH / WebGUI; use WireGuard, Tailscale or Unraid Connect remote access instead.',
+            'Set a strong root password and consider disabling SSH password login.',
+        ],
+    },
+    {
+        rule: 'segfault',
+        pattern: /\b(segfault at|traps: .* (general protection|trap divide error)|core dumped)/i,
+        severity: 'warning',
+        category: 'application',
+        nextSteps: [
+            'Identify the process; if it belongs to a container, restart it and check for an image update.',
+            'Repeated segfaults across processes can point to bad RAM; run memtest.',
+        ],
+    },
+    {
+        rule: 'docker-error',
+        pattern: /\b(dockerd|containerd|docker)\b.*\b(error|failed|cannot|unable)\b/i,
+        severity: 'warning',
+        category: 'docker',
+        nextSteps: [
+            'Check the named container\'s own log (Docker › container › Logs) for the root cause.',
+            'Restart the container; if Docker itself fails, check that docker.img is not full or corrupted.',
+        ],
+    },
+    {
+        rule: 'network',
+        pattern: /\b(Link is Down|NIC Link is Down|link down|carrier lost|bond\d+: .*(link status definitely down|No active)|duplicate address detected|DHCP.*(failed|timeout))/i,
+        severity: 'warning',
+        category: 'network',
+        nextSteps: [
+            'Check the network cable, switch port and NIC; note which interface went down.',
+            'If it flaps, check for duplicate IPs and bonding / bridging settings (Settings › Network).',
+        ],
+    },
+    {
+        rule: 'temperature',
+        pattern: /\b(temperature above threshold|cpu clock throttled|Package temperature|overheat|thermal)\b/i,
+        severity: 'warning',
+        category: 'temperature',
+        nextSteps: [
+            'Check fans, airflow and dust; confirm CPU cooler mounting.',
+            'Review fan curves (Dynamix Auto Fan Control) and disk temperature thresholds.',
+        ],
+    },
+    {
+        rule: 'app-fatal',
+        pattern: /\b(fatal( error)?:|panic:|unhandled exception|uncaught exception|traceback \(most recent call last\)|database disk image is malformed|database is locked|corrupt(ed|ion)\b)/i,
+        severity: 'warning',
+        category: 'application',
+        nextSteps: [
+            'Read the lines before this one in the container log for the root cause.',
+            'For database corruption: stop the container, back up its appdata, then repair or restore the database.',
+            'Check the appdata path is on a healthy disk / pool and not full.',
+        ],
+    },
+    {
+        rule: 'generic-error',
+        pattern: /\b(error|failed|failure|fatal|critical|panic|denied)\b/i,
+        severity: 'info',
+        category: 'general',
+        nextSteps: ['Look at the surrounding log lines for context; repeated occurrences deserve a closer look.'],
+    },
+];
+const BENIGN = [
+    /ACPI (Error|Warning|BIOS Error).*(AE_NOT_FOUND|AE_ALREADY_EXISTS)/i, // Common BIOS table noise.
+    /\bcorrected error\b.*\bPCIe\b.*\bReceiver Error\b/i,
+    /\b(error|failed)=0\b/i,
+];
+function classifyLogLine(line) {
+    if (!line.trim() || BENIGN.some((p) => p.test(line)))
+        return null;
+    for (const r of LOG_RULES) {
+        if (r.pattern.test(line))
+            return { severity: r.severity, category: r.category, rule: r.rule, nextSteps: r.nextSteps };
+    }
+    return null;
+}
+exports.LOG_RULE_NAMES = LOG_RULES.map((r) => r.rule);
+exports.DEFAULT_HEALTH_OPTIONS = {
+    diskUsageWarningPercent: 90,
+    diskUsageCriticalPercent: 97,
+    defaultTempWarning: 45,
+    defaultTempCritical: 55,
+    defaultSsdTempWarning: 60,
+    defaultSsdTempCritical: 70,
+    memoryWarningPercent: 90,
+    cpuWarningPercent: 95,
+    reportStoppedAutostartContainers: true,
+    reportContainerUpdates: true,
+    includeUnraidNotifications: true,
+    ignoreContainers: [],
+};
+const diskLabel = (d) => d.name || d.device || d.id;
+function analyzeHealth(snapshot, options = {}) {
+    const o = { ...exports.DEFAULT_HEALTH_OPTIONS, ...options };
+    const findings = [];
+    const array = snapshot.array;
+    if (array?.state && array.state !== 'STARTED') {
+        findings.push({
+            key: `array:state:${array.state}`,
+            severity: 'critical',
+            category: 'array',
+            title: `Array is ${array.state}`,
+            details: `The Unraid array is in state ${array.state}; shares, Docker and VMs on the array are unavailable.`,
+            nextSteps: array.state === 'STOPPED'
+                ? ['If this was not intentional, check the Main tab for missing disks before starting the array.', 'Start the array once all disks are present.']
+                : ['Open the Main tab: the state names the problem (missing / wrong / too small disk).', 'Do not start the array or format anything until the disk assignment is correct.'],
+            suggestedAction: array.state === 'STOPPED' ? { resource: 'array', operation: 'start' } : undefined,
+        });
+    }
+    const arrayDisks = [...(array?.parities ?? []), ...(array?.disks ?? []), ...(array?.caches ?? [])];
+    for (const d of arrayDisks) {
+        const label = diskLabel(d);
+        if (d.status && !['DISK_OK', 'DISK_NP'].includes(d.status)) {
+            findings.push({
+                key: `disk:status:${d.id}:${d.status}`,
+                severity: 'critical',
+                category: 'disk',
+                title: `${label} is ${d.status.replace(/^DISK_/, '').toLowerCase()}`,
+                details: `${d.type ?? 'Disk'} ${label} (${d.device ?? 'no device'}) reports status ${d.status}.`,
+                nextSteps: d.status.includes('DSBL') || d.status === 'DISK_INVALID'
+                    ? [
+                        'The disk is disabled (red X) and is being emulated from parity. Do not write heavily to the array.',
+                        'Check SMART data and cabling, then download diagnostics before changing anything.',
+                        'Rebuild onto the same disk (if healthy) or a replacement: stop array, unassign, start, stop, reassign, start.',
+                    ]
+                    : ['Check the Main tab for the disk assignment and whether the disk is physically connected.', 'Download diagnostics before reassigning disks.'],
+            });
+        }
+        const errors = num(d.numErrors);
+        if (errors && errors > 0) {
+            findings.push({
+                key: `disk:errors:${d.id}`,
+                severity: 'warning',
+                category: 'disk',
+                title: `${label} has ${errors} read/write error(s)`,
+                details: `The array driver recorded ${errors} unrecoverable I/O errors on ${label} since the counters were last cleared.`,
+                nextSteps: ['Run a SMART extended test on the disk.', 'Check / replace the SATA and power cables.', 'Clear the statistics after fixing so new errors stand out.'],
+            });
+        }
+        if (d.temp !== null && d.temp !== undefined) {
+            const ssd = d.rotational === false;
+            const crit = d.critical ?? (ssd ? o.defaultSsdTempCritical : o.defaultTempCritical);
+            const warn = d.warning ?? (ssd ? o.defaultSsdTempWarning : o.defaultTempWarning);
+            const level = d.temp >= crit ? 'critical' : d.temp >= warn ? 'warning' : null;
+            if (level) {
+                findings.push({
+                    key: `disk:temp:${d.id}:${level}`,
+                    severity: level,
+                    category: 'temperature',
+                    title: `${label} is at ${d.temp}°C`,
+                    details: `${label} temperature ${d.temp}°C exceeds the ${level} threshold (${level === 'critical' ? crit : warn}°C).`,
+                    nextSteps: ['Check case fans and airflow over the drive cage.', 'Pause a running parity check if it is driving the temperature up.', 'Review fan control and per-disk thresholds (Settings › Disk Settings).'],
+                });
+            }
+        }
+        const usage = pct(d.fsUsed, d.fsSize);
+        if (usage !== undefined && usage >= o.diskUsageWarningPercent) {
+            const level = usage >= o.diskUsageCriticalPercent ? 'critical' : 'warning';
+            findings.push({
+                key: `disk:usage:${d.id}:${level}`,
+                severity: level,
+                category: 'storage',
+                title: `${label} is ${usage}% full`,
+                details: `Filesystem on ${label} is ${usage}% used.`,
+                nextSteps: d.type === 'CACHE'
+                    ? ['Run the Mover (Main › Move) and check share cache settings.', 'Set a minimum free space on the pool so writes overflow to the array.']
+                    : ['Set a minimum free space on shares and check the split level / allocation method.', 'Plan a new or larger disk if all data disks are filling up.'],
+            });
+        }
+    }
+    const parity = array?.parityCheckStatus;
+    if (parity?.status === 'FAILED') {
+        findings.push({
+            key: 'parity:failed',
+            severity: 'critical',
+            category: 'parity',
+            title: 'Last parity check failed',
+            details: 'The most recent parity check did not finish successfully.',
+            nextSteps: ['Check the syslog around the end of the check for disk errors.', 'Run the check again once disk issues are fixed.'],
+        });
+    }
+    else if (parity && (parity.errors ?? 0) > 0 && !parity.running) {
+        findings.push({
+            key: `parity:errors:${parity.errors}`,
+            severity: 'warning',
+            category: 'parity',
+            title: `Parity check found ${parity.errors} error(s)`,
+            details: `The last parity check (${parity.status}) reported ${parity.errors} sync errors.`,
+            nextSteps: ['After an unclean shutdown, run a correcting check once.', 'If errors return on the next non-correcting check, run memtest and inspect SMART data.'],
+        });
+    }
+    for (const d of snapshot.disks ?? []) {
+        if (d.smartStatus && d.smartStatus !== 'OK' && d.smartStatus !== 'UNKNOWN') {
+            findings.push({
+                key: `smart:${d.id}:${d.smartStatus}`,
+                severity: 'critical',
+                category: 'disk',
+                title: `SMART status of ${d.name || d.device} is ${d.smartStatus}`,
+                details: `Physical disk ${d.device} reports SMART status ${d.smartStatus}.`,
+                nextSteps: ['Back up anything on this disk that is not protected by parity.', 'Order a replacement and run an extended SMART test to confirm.'],
+            });
+        }
+    }
+    const ignored = new Set(o.ignoreContainers.map((n) => n.trim().toLowerCase()).filter(Boolean));
+    for (const c of snapshot.docker?.containers ?? []) {
+        const name = containerName(c);
+        if (ignored.has(name.toLowerCase()))
+            continue;
+        if (o.reportStoppedAutostartContainers && c.autoStart && c.state && c.state !== 'RUNNING') {
+            findings.push({
+                key: `container:down:${name}`,
+                severity: 'warning',
+                category: 'docker',
+                title: `Container ${name} is ${c.state.toLowerCase()}`,
+                details: `${name} (${c.image}) has autostart enabled but is ${c.state} — ${c.status ?? ''}`.trim(),
+                nextSteps: [
+                    `Read the last log lines of ${name} for the exit reason.`,
+                    `Restart ${name}; if it exits again, check its appdata paths and recent image changes.`,
+                ],
+                suggestedAction: { resource: 'dockerContainer', operation: c.state === 'PAUSED' ? 'unpause' : 'start', id: c.id, name },
+            });
+        }
+        if (o.reportContainerUpdates && c.isUpdateAvailable) {
+            findings.push({
+                key: `container:update:${name}`,
+                severity: 'info',
+                category: 'docker-update',
+                title: `Update available for ${name}`,
+                details: `A newer image is available for ${name} (${c.image}).`,
+                nextSteps: [`Read the release notes of ${c.image} for breaking changes.`, `Update ${name} (back up its appdata first for databases).`],
+                suggestedAction: { resource: 'dockerContainer', operation: 'update', id: c.id, name },
+            });
+        }
+    }
+    if (o.includeUnraidNotifications) {
+        for (const n of snapshot.notifications?.warningsAndAlerts ?? []) {
+            findings.push({
+                key: `notification:${n.id}`,
+                severity: n.importance === 'ALERT' ? 'critical' : 'warning',
+                category: 'unraid-notification',
+                title: n.subject || n.title || 'Unraid notification',
+                details: [n.title, n.description].filter(Boolean).join(' — '),
+                nextSteps: ['Open the notification in the Unraid WebGUI and archive it once handled.'],
+            });
+        }
+    }
+    const mem = snapshot.metrics?.memory?.percentTotal;
+    if (mem !== undefined && mem >= o.memoryWarningPercent) {
+        findings.push({
+            key: 'memory:high',
+            severity: 'warning',
+            category: 'memory',
+            title: `Memory usage at ${Math.round(mem)}%`,
+            details: `RAM usage is ${Math.round(mem)}% (swap ${Math.round(snapshot.metrics?.memory?.percentSwapTotal ?? 0)}%).`,
+            nextSteps: ['Find the heaviest containers (Docker › Advanced view / ctop).', 'Set memory limits on containers and check VM allocations.'],
+        });
+    }
+    const cpu = snapshot.metrics?.cpu?.percentTotal;
+    if (cpu !== undefined && cpu >= o.cpuWarningPercent) {
+        findings.push({
+            key: 'cpu:high',
+            severity: 'info',
+            category: 'cpu',
+            title: `CPU usage at ${Math.round(cpu)}%`,
+            details: `Total CPU usage is ${Math.round(cpu)}% at the time of the check.`,
+            nextSteps: ['Check whether a parity check, mover, transcode or backup is running.', 'Pin heavy containers / VMs to specific cores if this is persistent.'],
+        });
+    }
+    return sortFindings(findings);
+}
+function summarizeFindings(findings) {
+    const counts = { critical: 0, warning: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    const status = counts.critical ? 'critical' : counts.warning ? 'warning' : counts.info ? 'info' : 'ok';
+    return { status, counts, total: findings.length };
+}