@nordbyte/nordrelay-auto-updater 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ricardo
+
+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

@@ -0,0 +1,139 @@
+# NordRelay Auto Updater Plugin
+
+Auto Updater is a NordRelay plugin that shows update visibility for Linux/macOS
+package managers and global npm packages on every peer where it is installed
+and enabled. Admins can explicitly run selected updates, update all listed
+updates, or uninstall global npm packages from the WebUI panel.
+
+The plugin is self-contained. NordRelay provides plugin installation, peer
+routing, scheduling, permissions, and the WebUI panel container; all update
+checks, parsing, history, cleanup, and rendering logic lives in this plugin.
+
+## Install
+
+Install on the current node:
+
+```sh
+nordrelay plugin install github:nordbyte/nordrelay-plugin-auto-updater --enable --approve
+```
+
+Install from a local checkout:
+
+```sh
+nordrelay plugin install /path/to/nordrelay-plugin-auto-updater --enable --approve
+```
+
+The npm package is published as:
+
+```text
+@nordbyte/nordrelay-auto-updater
+```
+
+In the WebUI, open **Plugins**, select the target node in the header, and install
+the GitHub source. Use **Install on all enabled peers** to install the same
+plugin on reachable peers.
+
+## Capabilities
+
+- Collector: `updates.snapshot`
+- Commands: `refresh`, `latest`, `panel-data`, `os-updates`, `npm-packages`,
+  `update-os`, `update-npm`, `configure-npm-auto`, `uninstall-npm`,
+  `history`, `export`, `storage-health`, `cleanup`
+- Web panel: `dashboard`
+- Diagnostics: enabled
+
+Required permissions:
+
+```text
+system.packages.read
+system.packages.write
+system.updates.read
+system.updates.write
+```
+
+The dashboard aggregates data only from peers where this plugin is installed,
+enabled, and approved.
+
+## What It Checks
+
+Linux package managers:
+
+- `apt list --upgradable`
+- `dnf check-update`
+- `pacman -Qu`
+- `zypper list-updates`
+- `snap refresh --list`
+- `flatpak remote-ls --updates`
+
+macOS:
+
+- `softwareupdate -l`
+- `brew outdated --json=v2`
+
+All platforms:
+
+- `npm ls -g --depth=0 --json --long`
+- `npm outdated -g --json --long`
+
+Windows currently reports npm package status only.
+
+Update, uninstall, and automatic npm install actions run as the same
+operating-system user that runs NordRelay. The plugin does not use `sudo`, so
+package managers that require root privileges must be handled by running
+NordRelay with the required permissions or by using package managers that allow
+user-level updates.
+
+Global npm packages can be configured individually for automatic installation.
+Each package has its own interval in hours or days. By default the automatic
+action installs only when the package is outdated; enabling **Install latest**
+also runs `npm install -g <package>@latest` when the package already reports the
+latest version.
+
+## Settings
+
+| Setting | Default | Description |
+| --- | ---: | --- |
+| `checkIntervalMs` | `1800000` | Preferred collector interval in milliseconds |
+| `retentionDays` | `30` | Snapshot history retention in days |
+| `commandTimeoutMs` | `20000` | Timeout for individual package-manager commands |
+| `updateTimeoutMs` | `600000` | Timeout for package update or uninstall commands |
+| `enableOsUpdates` | `true` | Check Linux/macOS package-manager updates |
+| `enableNpmPackages` | `true` | Check global npm package versions |
+| `npmRegistry` | `https://registry.npmjs.org` | Registry used by npm outdated checks |
+| `refreshPackageIndexes` | `false` | Reserved for future explicit index refresh flows |
+
+## Data
+
+Snapshots are stored in the plugin data directory:
+
+```text
+~/.nordrelay/plugins/data/auto-updater/
+```
+
+The plugin writes:
+
+- `updates.sqlite`
+
+Useful commands:
+
+```sh
+nordrelay plugin invoke auto-updater command refresh
+nordrelay plugin invoke auto-updater command panel-data
+nordrelay plugin invoke auto-updater command os-updates
+nordrelay plugin invoke auto-updater command npm-packages
+nordrelay plugin invoke auto-updater command update-os --input-json '{"packages":[{"manager":"apt","name":"openssl"}]}'
+nordrelay plugin invoke auto-updater command update-npm --input-json '{"packages":["typescript"]}'
+nordrelay plugin invoke auto-updater command configure-npm-auto --input-json '{"package":"typescript","enabled":true,"intervalValue":12,"intervalUnit":"hours","installLatest":false}'
+nordrelay plugin invoke auto-updater command uninstall-npm --input-json '{"packages":["typescript"]}'
+nordrelay plugin invoke auto-updater command history --input-json '{"range":"30d","limit":500}'
+nordrelay plugin invoke auto-updater command export --input-json '{"format":"csv","range":"30d"}'
+nordrelay plugin invoke auto-updater command storage-health
+nordrelay plugin invoke auto-updater command cleanup
+```
+
+## Development
+
+```sh
+npm run check
+npm test
+```

package/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runPlugin } from "./src/runtime.js";
+
+export * from "./src/runtime.js";
+export * from "./src/os-updates.js";
+export * from "./src/npm-packages.js";
+export * from "./src/package-managers.js";
+export * from "./src/update-actions.js";
+export * from "./src/subprocess.js";
+export * from "./src/storage.js";
+export * from "./src/render-panel.js";
+export * from "./src/format.js";
+export * from "./src/commands.js";
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runPlugin().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.stdout.write(`${JSON.stringify({ ok: false, stderr: message })}\n`);
+    process.exitCode = 1;
+  });
+}

package/nordrelay.plugin.json

@@ -0,0 +1,293 @@
+{
+  "id": "auto-updater",
+  "name": "Auto Updater",
+  "version": "0.1.0",
+  "description": "Checks Linux/macOS package-manager updates and global npm package versions across NordRelay peers.",
+  "author": "Ricardo <github@nordbyte.de>",
+  "homepage": "https://github.com/nordbyte/nordrelay-plugin-auto-updater",
+  "repository": "https://github.com/nordbyte/nordrelay-plugin-auto-updater",
+  "license": "MIT",
+  "nordrelay": ">=0.9.12",
+  "entry": "index.js",
+  "permissions": [
+    "runtime.read",
+    "peers.read",
+    "system.packages.read",
+    "system.packages.write",
+    "system.updates.read",
+    "system.updates.write",
+    "network"
+  ],
+  "capabilities": {
+    "collectors": [
+      {
+        "id": "updates.snapshot",
+        "title": "Collect update snapshot",
+        "description": "Checks available OS package-manager updates and global npm package versions on this node.",
+        "intervalMs": 1800000,
+        "runOnStart": true,
+        "timeoutMs": 120000
+      }
+    ],
+    "commands": [
+      {
+        "name": "refresh",
+        "title": "Refresh update data",
+        "description": "Run a fresh read-only update check and persist the snapshot.",
+        "timeoutMs": 120000
+      },
+      {
+        "name": "latest",
+        "title": "Latest update snapshot",
+        "description": "Return the latest snapshot, collecting one if none exists.",
+        "timeoutMs": 120000
+      },
+      {
+        "name": "panel-data",
+        "title": "Panel data",
+        "description": "Return latest update data, history, storage health, and diagnostics for the WebUI panel.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "force": {
+              "type": "boolean",
+              "title": "Force refresh",
+              "default": false
+            }
+          }
+        },
+        "timeoutMs": 120000
+      },
+      {
+        "name": "os-updates",
+        "title": "OS updates",
+        "description": "Return the latest available OS package-manager updates.",
+        "timeoutMs": 30000
+      },
+      {
+        "name": "npm-packages",
+        "title": "npm packages",
+        "description": "Return global npm packages with installed and latest versions.",
+        "timeoutMs": 30000
+      },
+      {
+        "name": "update-os",
+        "title": "Update OS packages",
+        "description": "Install selected OS package-manager updates on this node.",
+        "permission": "system.updates.write",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "packages": {
+              "type": "array",
+              "title": "Packages"
+            },
+            "all": {
+              "type": "boolean",
+              "title": "Update all selected packages",
+              "default": false
+            }
+          }
+        },
+        "timeoutMs": 600000
+      },
+      {
+        "name": "update-npm",
+        "title": "Update npm packages",
+        "description": "Update selected global npm packages or all global npm packages on this node.",
+        "permission": "system.packages.write",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "packages": {
+              "type": "array",
+              "title": "Packages"
+            },
+            "all": {
+              "type": "boolean",
+              "title": "Update all packages",
+              "default": false
+            }
+          }
+        },
+        "timeoutMs": 600000
+      },
+      {
+        "name": "configure-npm-auto",
+        "title": "Configure npm auto install",
+        "description": "Configure automatic global npm install checks for a package on this node.",
+        "permission": "system.packages.write",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "package": {
+              "type": "string",
+              "title": "Package"
+            },
+            "enabled": {
+              "type": "boolean",
+              "title": "Enabled",
+              "default": false
+            },
+            "intervalValue": {
+              "type": "number",
+              "title": "Interval",
+              "default": 24
+            },
+            "intervalUnit": {
+              "type": "string",
+              "title": "Interval unit",
+              "default": "hours"
+            },
+            "installLatest": {
+              "type": "boolean",
+              "title": "Install even when latest",
+              "default": false
+            }
+          }
+        },
+        "timeoutMs": 30000
+      },
+      {
+        "name": "uninstall-npm",
+        "title": "Uninstall npm packages",
+        "description": "Uninstall selected global npm packages from this node.",
+        "permission": "system.packages.write",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "packages": {
+              "type": "array",
+              "title": "Packages"
+            }
+          }
+        },
+        "timeoutMs": 600000
+      },
+      {
+        "name": "history",
+        "title": "Update history",
+        "description": "Return snapshot history for charts and trend tables.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "range": {
+              "type": "string",
+              "title": "Range",
+              "default": "7d"
+            },
+            "limit": {
+              "type": "number",
+              "title": "Limit",
+              "default": 200
+            }
+          }
+        },
+        "timeoutMs": 30000
+      },
+      {
+        "name": "export",
+        "title": "Export update data",
+        "description": "Export latest data or history as JSON or CSV.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "format": {
+              "type": "string",
+              "title": "Format",
+              "default": "json"
+            },
+            "range": {
+              "type": "string",
+              "title": "Range",
+              "default": "30d"
+            }
+          }
+        },
+        "timeoutMs": 30000
+      },
+      {
+        "name": "storage-health",
+        "title": "Storage health",
+        "description": "Return SQLite storage health for the plugin database.",
+        "timeoutMs": 10000
+      },
+      {
+        "name": "cleanup",
+        "title": "Cleanup old snapshots",
+        "description": "Delete snapshots older than the configured retention window.",
+        "timeoutMs": 30000
+      }
+    ],
+    "webPanels": [
+      {
+        "id": "dashboard",
+        "title": "Auto Updater",
+        "description": "Peer-aware OS and npm update overview.",
+        "aggregateCommand": "panel-data",
+        "allowClientScript": true,
+        "placement": "plugins",
+        "timeoutMs": 120000
+      }
+    ],
+    "diagnostics": true
+  },
+  "settings": [
+    {
+      "key": "checkIntervalMs",
+      "label": "Collector interval",
+      "type": "number",
+      "default": 1800000,
+      "description": "Preferred interval in milliseconds between scheduled update checks."
+    },
+    {
+      "key": "retentionDays",
+      "label": "Retention days",
+      "type": "number",
+      "default": 30,
+      "description": "How long snapshot history is kept in SQLite."
+    },
+    {
+      "key": "commandTimeoutMs",
+      "label": "Command timeout",
+      "type": "number",
+      "default": 20000,
+      "description": "Timeout for individual package-manager commands."
+    },
+    {
+      "key": "updateTimeoutMs",
+      "label": "Update timeout",
+      "type": "number",
+      "default": 600000,
+      "description": "Timeout for package update or uninstall commands."
+    },
+    {
+      "key": "enableOsUpdates",
+      "label": "Check OS updates",
+      "type": "boolean",
+      "default": true,
+      "description": "Enable Linux/macOS read-only package-manager update checks."
+    },
+    {
+      "key": "enableNpmPackages",
+      "label": "Check npm packages",
+      "type": "boolean",
+      "default": true,
+      "description": "Enable global npm package version checks."
+    },
+    {
+      "key": "npmRegistry",
+      "label": "npm registry",
+      "type": "string",
+      "default": "https://registry.npmjs.org",
+      "description": "Registry used by npm outdated checks."
+    },
+    {
+      "key": "refreshPackageIndexes",
+      "label": "Refresh package indexes",
+      "type": "boolean",
+      "default": false,
+      "description": "Reserved for future explicit index refresh flows. The plugin never runs privileged updates automatically."
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nordbyte/nordrelay-auto-updater",
+  "version": "0.1.0",
+  "description": "Update visibility plugin for NordRelay peers, OS package managers, and global npm packages.",
+  "type": "module",
+  "homepage": "https://github.com/nordbyte/nordrelay-plugin-auto-updater#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nordbyte/nordrelay-plugin-auto-updater.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nordbyte/nordrelay-plugin-auto-updater/issues"
+  },
+  "main": "./index.js",
+  "files": [
+    "index.js",
+    "src",
+    "nordrelay.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check index.js && node --check src/runtime.js && node --check src/os-updates.js && node --check src/npm-packages.js && node --check src/package-managers.js && node --check src/update-actions.js && node --check src/subprocess.js && node --check src/storage.js && node --check src/render-panel.js && node --check src/format.js && node --check src/commands.js",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm run check && npm test"
+  },
+  "keywords": [
+    "nordrelay",
+    "plugin",
+    "updates",
+    "npm",
+    "package-manager"
+  ],
+  "author": "Ricardo <github@nordbyte.de>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands.js

@@ -0,0 +1,20 @@
+export const COMMANDS = new Set([
+  "refresh",
+  "latest",
+  "panel-data",
+  "os-updates",
+  "npm-packages",
+  "update-os",
+  "update-npm",
+  "configure-npm-auto",
+  "uninstall-npm",
+  "history",
+  "export",
+  "storage-health",
+  "cleanup",
+]);
+
+export function normalizeCommand(request) {
+  const command = String(request.command || request.capabilityId || request.input?.command || "").trim().toLowerCase();
+  return COMMANDS.has(command) ? command : command || "latest";
+}

package/src/format.js

@@ -0,0 +1,90 @@
+export function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export function attr(value) {
+  return escapeHtml(value);
+}
+
+export function badge(text, status = "disabled") {
+  return `<span class="badge ${statusClass(status)}">${escapeHtml(text)}</span>`;
+}
+
+export function metric(label, value, detail = "", status = "") {
+  const statusAttr = status ? ` data-status="${attr(status)}"` : "";
+  return `<div class="metric"${statusAttr}><div class="label">${escapeHtml(label)}</div><div class="value">${escapeHtml(value)}</div>${detail ? `<small>${escapeHtml(detail)}</small>` : ""}</div>`;
+}
+
+export function table(headers, rows, empty = "No data available.") {
+  if (!rows.length) {
+    return `<div class="empty-state">${escapeHtml(empty)}</div>`;
+  }
+  const head = headers.map((header) => `<th>${escapeHtml(header)}</th>`).join("");
+  return `<div class="data-table-wrap"><table class="data-table"><thead><tr>${head}</tr></thead><tbody>${rows.join("")}</tbody></table></div>`;
+}
+
+export function truncate(value, max = 120) {
+  const text = String(value ?? "");
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+export function formatDuration(ms) {
+  const value = Math.max(0, Number(ms) || 0);
+  if (value < 1000) return `${Math.round(value)}ms`;
+  const seconds = Math.round(value / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m ${seconds % 60}s`;
+}
+
+export function formatAge(iso) {
+  const ts = Date.parse(iso || "");
+  if (!Number.isFinite(ts)) return "-";
+  const seconds = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ${minutes % 60}m ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ${hours % 24}h ago`;
+}
+
+export function statusForCount(count) {
+  return Number(count) > 0 ? "warning" : "enabled";
+}
+
+export function statusClass(status) {
+  switch (status) {
+    case "ok":
+    case "enabled":
+    case "latest":
+      return "enabled";
+    case "warn":
+    case "warning":
+    case "outdated":
+      return "warning";
+    case "error":
+    case "failed":
+      return "failed";
+    default:
+      return "disabled";
+  }
+}
+
+export function parseRangeMs(range, fallbackMs = 24 * 60 * 60 * 1000) {
+  const text = String(range || "").trim().toLowerCase();
+  const match = /^(\d+)(m|h|d)$/.exec(text);
+  if (!match) return fallbackMs;
+  const value = Number(match[1]);
+  if (!Number.isFinite(value) || value <= 0) return fallbackMs;
+  if (match[2] === "m") return value * 60 * 1000;
+  if (match[2] === "h") return value * 60 * 60 * 1000;
+  return value * 24 * 60 * 60 * 1000;
+}
+