@nocville/npc 0.2.2 → 0.3.0

package/dist/cjs/npcs/security/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityNPC = void 0;
+const polling_npc_js_1 = require("../../core/polling-npc.js");
+class SecurityNPC extends polling_npc_js_1.PollingNPC {
+    constructor(config) {
+        super({ ...config, pollInterval: config.pollInterval ?? 60_000 });
+    }
+    get name() {
+        return 'security';
+    }
+    get defaultDisplayName() {
+        return 'Security';
+    }
+    get archetype() {
+        return 'custom';
+    }
+    get behavior() {
+        return { role: 'security', activity: 'idle', idlePose: 'stand' };
+    }
+    async collect() {
+        return { status: 'healthy', mood: 'happy', message: '', metrics: {} };
+    }
+}
+exports.SecurityNPC = SecurityNPC;
+//# sourceMappingURL=index.js.map

package/dist/cjs/npcs/system-monitor/collectors.js

@@ -4,10 +4,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCpuSampler = createCpuSampler;
+exports.parseVmStat = parseVmStat;
+exports.readAvailableMemory = readAvailableMemory;
 exports.collectMemory = collectMemory;
 exports.collectDisk = collectDisk;
 const node_os_1 = __importDefault(require("node:os"));
 const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
 function aggregate(cpus) {
     let idle = 0;
     let total = 0;
@@ -18,6 +23,12 @@ function aggregate(cpus) {
     }
     return { idle, total };
 }
+function gb(bytes) {
+    return Math.round((bytes / 1024 ** 3) * 100) / 100;
+}
+function percentOf(part, whole) {
+    return whole > 0 ? Math.min(100, Math.max(0, Math.round((part / whole) * 100))) : 0;
+}
 /**
  * Stateful CPU sampler that computes usage from the delta between consecutive
  * `os.cpus()` snapshots — no blocking sleep. The first sample reports usage
@@ -35,34 +46,72 @@ function createCpuSampler(readCpus = () => node_os_1.default.cpus(), readLoad =
             const idleDiff = cur.idle - base.idle;
             const totalDiff = cur.total - base.total;
             prev = cur;
-            const percent = totalDiff > 0 ? Math.round((1 - idleDiff / totalDiff) * 100) : 0;
+            const percent = totalDiff > 0 ? percentOf(totalDiff - idleDiff, totalDiff) : 0;
             return { percent, loadAvg1m };
         },
     };
 }
 /**
- * Collect memory usage from OS.
+ * Parse `vm_stat` output into reclaimable ("available") bytes: free +
+ * inactive + speculative pages, the same estimate psutil uses on macOS.
+ * Returns null when the output is unrecognised.
+ */
+function parseVmStat(stdout) {
+    const pageSize = Number(stdout.match(/page size of (\d+) bytes/)?.[1]);
+    if (!Number.isFinite(pageSize) || pageSize <= 0)
+        return null;
+    const pages = (label) => {
+        const m = stdout.match(new RegExp(`^Pages ${label}:\\s+(\\d+)`, 'm'));
+        return m ? Number(m[1]) : null;
+    };
+    const free = pages('free');
+    const inactive = pages('inactive');
+    if (free === null || inactive === null)
+        return null;
+    return (free + inactive + (pages('speculative') ?? 0)) * pageSize;
+}
+/**
+ * Bytes of memory available to new work. On macOS `os.freemem()` counts only
+ * never-used pages (the file cache is "used"), which reads ~95% full on any
+ * healthy Mac, so the reclaimable estimate comes from `vm_stat` instead. Linux
+ * (`MemAvailable`) and Windows report a meaningful value through Node.
  */
-function collectMemory() {
-    const totalBytes = node_os_1.default.totalmem();
-    const freeBytes = node_os_1.default.freemem();
-    const usedBytes = totalBytes - freeBytes;
-    const totalGb = Math.round((totalBytes / 1024 ** 3) * 100) / 100;
-    const usedGb = Math.round((usedBytes / 1024 ** 3) * 100) / 100;
-    const percent = Math.round((usedBytes / totalBytes) * 100);
-    return { percent, usedGb, totalGb };
+async function readAvailableMemory() {
+    if (process.platform === 'darwin') {
+        try {
+            const { stdout } = await execFileAsync('vm_stat', [], { timeout: 2000 });
+            const available = parseVmStat(stdout);
+            if (available !== null)
+                return Math.min(available, node_os_1.default.totalmem());
+        }
+        catch {
+            // Fall through to Node's figure.
+        }
+    }
+    return node_os_1.default.freemem();
+}
+/** Memory usage from the total and the available byte count. */
+function collectMemory(availableBytes = node_os_1.default.freemem(), totalBytes = node_os_1.default.totalmem()) {
+    const usedBytes = Math.max(0, totalBytes - availableBytes);
+    return {
+        percent: percentOf(usedBytes, totalBytes),
+        usedGb: gb(usedBytes),
+        totalGb: gb(totalBytes),
+    };
 }
 /**
- * Collect disk usage via fs.statfs (Node 18.15+).
+ * Disk usage via fs.statfs, computed like `df`: used / (used + available to
+ * unprivileged users), so blocks reserved for root don't hide a full disk.
  */
 async function collectDisk(path) {
     const stats = await node_fs_1.promises.statfs(path);
     const totalBytes = stats.blocks * stats.bsize;
-    const freeBytes = stats.bavail * stats.bsize;
-    const usedBytes = totalBytes - freeBytes;
-    const totalGb = Math.round((totalBytes / 1024 ** 3) * 100) / 100;
-    const usedGb = Math.round((usedBytes / 1024 ** 3) * 100) / 100;
-    const percent = totalBytes > 0 ? Math.round((usedBytes / totalBytes) * 100) : 0;
-    return { percent, usedGb, totalGb };
+    const usedBytes = (stats.blocks - stats.bfree) * stats.bsize;
+    const availBytes = stats.bavail * stats.bsize;
+    return {
+        percent: percentOf(usedBytes, usedBytes + availBytes),
+        usedGb: gb(usedBytes),
+        totalGb: gb(totalBytes),
+    };
 }
 //# sourceMappingURL=collectors.js.map

package/dist/cjs/npcs/system-monitor/index.js

@@ -4,6 +4,7 @@ exports.SystemMonitorNPC = void 0;
 const polling_npc_js_1 = require("../../core/polling-npc.js");
 const thresholds_js_1 = require("../../core/thresholds.js");
 const screen_js_1 = require("../../core/screen.js");
+const errors_js_1 = require("../../core/errors.js");
 const collectors_js_1 = require("./collectors.js");
 const defaults_js_1 = require("./defaults.js");
 class SystemMonitorNPC extends polling_npc_js_1.PollingNPC {
@@ -14,15 +15,21 @@ class SystemMonitorNPC extends polling_npc_js_1.PollingNPC {
     cpuSampler = (0, collectors_js_1.createCpuSampler)();
     cpuHistory = [];
     memHistory = [];
+    diskErrorLogged = false;
     constructor(config) {
         super({
             ...config,
             pollInterval: config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval,
         });
         this.diskPath = config.diskPath ?? defaults_js_1.DEFAULTS.diskPath;
-        this.cpuThreshold = config.cpuThreshold ?? defaults_js_1.DEFAULT_THRESHOLDS['cpu'];
-        this.memThreshold = config.memThreshold ?? defaults_js_1.DEFAULT_THRESHOLDS['mem'];
-        this.diskThreshold = config.diskThreshold ?? defaults_js_1.DEFAULT_THRESHOLDS['disk'];
+        this.cpuThreshold = config.cpuThreshold ?? defaults_js_1.DEFAULT_THRESHOLDS.cpu;
+        this.memThreshold = config.memThreshold ?? defaults_js_1.DEFAULT_THRESHOLDS.mem;
+        this.diskThreshold = config.diskThreshold ?? defaults_js_1.DEFAULT_THRESHOLDS.disk;
+        const problem = (0, thresholds_js_1.thresholdProblem)('CPU', this.cpuThreshold) ??
+            (0, thresholds_js_1.thresholdProblem)('Memory', this.memThreshold) ??
+            (0, thresholds_js_1.thresholdProblem)('Disk', this.diskThreshold);
+        if (problem)
+            throw new errors_js_1.NpcConfigError(problem);
     }
     get name() {
         return 'system-monitor';
@@ -33,9 +40,6 @@ class SystemMonitorNPC extends polling_npc_js_1.PollingNPC {
     get archetype() {
         return 'service';
     }
-    get heartbeatSeconds() {
-        return 30;
-    }
     get behavior() {
         return { idle: 'wander' };
     }
@@ -49,19 +53,20 @@ class SystemMonitorNPC extends polling_npc_js_1.PollingNPC {
     }
     async collect() {
         const cpu = this.cpuSampler.sample();
-        const mem = (0, collectors_js_1.collectMemory)();
-        const disk = await (0, collectors_js_1.collectDisk)(this.diskPath);
+        const mem = (0, collectors_js_1.collectMemory)(await (0, collectors_js_1.readAvailableMemory)());
+        const disk = await this.readDisk();
         const cpuStatus = (0, thresholds_js_1.evaluateThreshold)(cpu.percent, this.cpuThreshold);
         const memStatus = (0, thresholds_js_1.evaluateThreshold)(mem.percent, this.memThreshold);
-        const diskStatus = (0, thresholds_js_1.evaluateThreshold)(disk.percent, this.diskThreshold);
+        // An unreadable disk (unmounted volume, bad --disk-path) is a warning, not a crash.
+        const diskStatus = disk
+            ? (0, thresholds_js_1.evaluateThreshold)(disk.percent, this.diskThreshold)
+            : 'warning';
         const status = (0, thresholds_js_1.worstStatus)([cpuStatus, memStatus, diskStatus]);
-        const mood = status === 'critical'
-            ? 'stressed'
-            : status === 'warning'
-                ? 'concerned'
-                : 'happy';
         (0, screen_js_1.pushHistory)(this.cpuHistory, cpu.percent);
         (0, screen_js_1.pushHistory)(this.memHistory, mem.percent);
+        const diskText = disk ? `${disk.percent}%` : 'n/a';
+        // Windows has no load average (os.loadavg() is always zeros there).
+        const loadText = process.platform === 'win32' ? 'n/a' : cpu.loadAvg1m.toFixed(2);
         const screenData = {
             layout: 'multi-metric',
             values: [
@@ -77,29 +82,48 @@ class SystemMonitorNPC extends polling_npc_js_1.PollingNPC {
                     color: (0, screen_js_1.statusColor)(memStatus),
                     sparkline: [...this.memHistory],
                 },
-                { label: 'DISK', value: `${disk.percent}%`, color: (0, screen_js_1.statusColor)(diskStatus) },
-                { label: 'LOAD', value: cpu.loadAvg1m.toFixed(2), color: 'gray' },
+                { label: 'DISK', value: diskText, color: (0, screen_js_1.statusColor)(diskStatus) },
+                { label: 'LOAD', value: loadText, color: 'gray' },
             ],
         };
+        const metrics = {
+            cpu_percent: cpu.percent,
+            mem_percent: mem.percent,
+            mem_used_gb: mem.usedGb,
+            mem_total_gb: mem.totalGb,
+            load_avg_1m: cpu.loadAvg1m,
+        };
+        if (disk) {
+            metrics['disk_percent'] = disk.percent;
+            metrics['disk_used_gb'] = disk.usedGb;
+            metrics['disk_total_gb'] = disk.totalGb;
+        }
         return {
             status,
-            mood,
-            message: `CPU: ${cpu.percent}% | Mem: ${mem.percent}% | Disk: ${disk.percent}%`,
+            mood: (0, thresholds_js_1.moodForStatus)(status),
+            message: `CPU: ${cpu.percent}% | Mem: ${mem.percent}% | Disk: ${disk ? diskText : 'unavailable'}`,
             screenData,
             // When strained, go find a desk and get to work; otherwise wander.
             behavior: status !== 'healthy' ? { busy: 'seek-desk' } : undefined,
-            metrics: {
-                cpu_percent: cpu.percent,
-                mem_percent: mem.percent,
-                mem_used_gb: mem.usedGb,
-                mem_total_gb: mem.totalGb,
-                disk_percent: disk.percent,
-                disk_used_gb: disk.usedGb,
-                disk_total_gb: disk.totalGb,
-                load_avg_1m: cpu.loadAvg1m,
-            },
+            metrics,
         };
     }
+    async readDisk() {
+        try {
+            const disk = await (0, collectors_js_1.collectDisk)(this.diskPath);
+            this.diskErrorLogged = false;
+            return disk;
+        }
+        catch (err) {
+            if (!this.diskErrorLogged) {
+                this.diskErrorLogged = true;
+                this.logger.warn(`Cannot read disk usage for ${this.diskPath}`, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            return null;
+        }
+    }
 }
 exports.SystemMonitorNPC = SystemMonitorNPC;
 //# sourceMappingURL=index.js.map

package/dist/cjs/npcs/web-page-watcher/basic-mode.js

@@ -4,10 +4,31 @@ exports.extractTitle = extractTitle;
 exports.statusFromHttp = statusFromHttp;
 exports.basicCheck = basicCheck;
 exports.hostnameOf = hostnameOf;
-/** Extract the <title> text from an HTML string (empty if none). */
+const http_js_1 = require("../../core/http.js");
+const text_js_1 = require("../../core/text.js");
+/** Bytes of HTML read to find the <title> (it lives in <head>). */
+const MAX_HTML_BYTES = 512 * 1024;
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+function decodeEntities(s) {
+    return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+        if (e[0] === '#') {
+            const code = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : m;
+        }
+        return ENTITIES[e.toLowerCase()] ?? m;
+    });
+}
+/** Extract the <title> text from (untrusted) HTML: entities decoded, sanitized, ≤80 chars. */
 function extractTitle(html) {
     const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
-    return m ? m[1].replace(/\s+/g, ' ').trim().slice(0, 80) : '';
+    return m ? (0, text_js_1.sanitizeText)(decodeEntities(m[1]), 80) : '';
 }
 /** Map an HTTP status to NPC status: 2xx/3xx ok, 4xx/timeout warn, 5xx/refused crit. */
 function statusFromHttp(code, timedOut = false) {
@@ -21,17 +42,15 @@ function statusFromHttp(code, timedOut = false) {
 }
 /** Fetch a page and extract HTTP status + <title> (basic, no browser). */
 async function basicCheck(url, timeoutMs = 8000) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const res = await fetch(url, {
-            signal: controller.signal,
-            headers: { 'User-Agent': 'nocville-npc' },
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { 'User-Agent': http_js_1.NPC_USER_AGENT },
             redirect: 'follow',
         });
         let title = '';
         try {
-            title = extractTitle(await res.text());
+            title = extractTitle((await (0, http_js_1.readTextCapped)(res, MAX_HTML_BYTES)).text);
         }
         catch {
             // body unavailable; leave title blank
@@ -39,20 +58,17 @@ async function basicCheck(url, timeoutMs = 8000) {
         return { status: res.status, title, ok: res.ok, timedOut: false };
     }
     catch (err) {
-        const timedOut = err instanceof Error && err.name === 'AbortError';
+        const timedOut = err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError');
         return { status: 0, title: '', ok: false, timedOut };
     }
-    finally {
-        clearTimeout(timer);
-    }
 }
-/** Best-effort hostname for a URL, falling back to the raw string. */
+/** Hostname of a URL for labels and service ids (never credentials or path). */
 function hostnameOf(url) {
     try {
-        return new URL(url).hostname;
+        return new URL(url).hostname || 'page';
     }
     catch {
-        return url.slice(0, 40);
+        return 'invalid-url';
     }
 }
 //# sourceMappingURL=basic-mode.js.map

package/dist/cjs/npcs/web-page-watcher/capture.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findChrome = findChrome;
+exports.chromeArgs = chromeArgs;
+exports.runningAsRoot = runningAsRoot;
 exports.loadPuppeteer = loadPuppeteer;
 exports.browserConnected = browserConnected;
 const node_fs_1 = require("node:fs");
@@ -21,7 +23,11 @@ const LINUX_BINARIES = [
 ];
 function which(bin) {
     try {
-        const out = (0, node_child_process_1.execFileSync)('which', [bin], { encoding: 'utf-8' }).trim();
+        const out = (0, node_child_process_1.execFileSync)('which', [bin], {
+            encoding: 'utf-8',
+            timeout: 2000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
         return out || null;
     }
     catch {
@@ -54,6 +60,22 @@ function findChrome(explicit) {
     }
     return null;
 }
+/**
+ * Chrome launch flags. The watched page is untrusted content, so Chrome's
+ * sandbox stays on unless it can't work: as root on Linux (Chrome refuses to
+ * start sandboxed, typical in containers) or when explicitly disabled.
+ */
+function chromeArgs(opts) {
+    const args = ['--disable-gpu', '--hide-scrollbars', '--mute-audio', '--no-first-run'];
+    const sandboxed = opts.sandbox && !opts.isRoot;
+    if (!sandboxed)
+        args.push('--no-sandbox', '--disable-setuid-sandbox');
+    return { args, sandboxed };
+}
+/** True when this process runs as root (POSIX only). */
+function runningAsRoot() {
+    return typeof process.getuid === 'function' && process.getuid() === 0;
+}
 /**
  * Load the optional `puppeteer-core` peer dependency without a static import,
  * so the package builds and runs when it isn't installed. Returns null if the

package/dist/cjs/npcs/web-page-watcher/defaults.js

@@ -1,11 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULTS = void 0;
+exports.WAIT_UNTIL = exports.WATCH_MODES = exports.LIMITS = exports.DEFAULTS = void 0;
 exports.parseDimensions = parseDimensions;
+exports.screenSizeProblem = screenSizeProblem;
+exports.viewportProblem = viewportProblem;
 exports.DEFAULTS = {
     pollInterval: 60000, // 60s
     minPollInterval: 15000, // floor
     navTimeoutMs: 15000,
+    /** Extra time for screenshot + encode before a capture counts as hung. */
+    captureGraceMs: 15000,
+    /** Wait before relaunching Chrome after it failed to start. */
+    relaunchBackoffMs: 10 * 60 * 1000,
     maxColors: 32,
     /** Polls to keep the 'changed' sub-status active after a page change. */
     changedPolls: 2,
@@ -18,6 +24,21 @@ exports.DEFAULTS = {
     scaleDivisor: 8,
     waitUntil: 'networkidle2',
 };
+/**
+ * Size limits. The pixel payload is base64(W×H) and the API caps a screen value
+ * at 220 KB, so W×H must stay under ~165k; 320×240 leaves headroom. The
+ * viewport bound keeps Chrome's raster (and the PNG decode) to sane memory.
+ */
+exports.LIMITS = {
+    screenMin: 16,
+    screenMaxSide: 320,
+    screenMaxPixels: 320 * 240,
+    viewportMin: 64,
+    viewportMax: 4096,
+};
+exports.WATCH_MODES = ['auto', 'screenshot', 'basic'];
+/** puppeteer `waitUntil` values. */
+exports.WAIT_UNTIL = ['load', 'domcontentloaded', 'networkidle0', 'networkidle2'];
 /** Parse a "WxH" string into a {width, height} pair, or null if malformed. */
 function parseDimensions(s) {
     const m = s
@@ -26,6 +47,27 @@ function parseDimensions(s) {
         .match(/^(\d+)x(\d+)$/);
     if (!m)
         return null;
-    return { width: parseInt(m[1], 10), height: parseInt(m[2], 10) };
+    const width = parseInt(m[1], 10);
+    const height = parseInt(m[2], 10);
+    return width > 0 && height > 0 ? { width, height } : null;
+}
+/** Why a TV resolution is unusable, or null when it is fine. */
+function screenSizeProblem(w, h) {
+    const { screenMin, screenMaxSide, screenMaxPixels } = exports.LIMITS;
+    if (!Number.isInteger(w) || !Number.isInteger(h) || w < screenMin || h < screenMin) {
+        return `--screen must be at least ${screenMin}x${screenMin}`;
+    }
+    if (w > screenMaxSide || h > screenMaxSide || w * h > screenMaxPixels) {
+        return `--screen must fit within ${screenMaxSide}x${screenMaxSide} and ${screenMaxPixels} pixels (e.g. 320x240)`;
+    }
+    return null;
+}
+/** Why a browser viewport is unusable, or null when it is fine. */
+function viewportProblem(w, h) {
+    const { viewportMin, viewportMax } = exports.LIMITS;
+    const ok = (n) => Number.isInteger(n) && n >= viewportMin && n <= viewportMax;
+    return ok(w) && ok(h)
+        ? null
+        : `--viewport sides must be between ${viewportMin} and ${viewportMax} pixels`;
 }
 //# sourceMappingURL=defaults.js.map