@nocville/npc 0.2.1 → 0.2.3

package/dist/cjs/npcs/process-watcher/process-scanner.js

@@ -1,10 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectTransitions = detectTransitions;
+exports.parsePsOutput = parsePsOutput;
+exports.matchesName = matchesName;
+exports.listProcesses = listProcesses;
+exports.matchProcesses = matchProcesses;
 exports.scanProcesses = scanProcesses;
 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);
+/** Bounds on the `ps` call: a wedged or enormous process table can't stall or flood us. */
+const PS_TIMEOUT_MS = 5000;
+const PS_MAX_BUFFER = 16 * 1024 * 1024;
+/** Linux truncates `comm` to 15 characters (TASK_COMM_LEN - 1). */
+const LINUX_COMM_LEN = 15;
 /**
  * Compare the previous and current running-process sets and return speech
  * strings for any transitions: "<name> died!" when a process disappears and
@@ -23,92 +32,77 @@ function detectTransitions(prev, curr) {
     return messages;
 }
 /**
- * Parse the output of `ps` into structured entries.
- * Expects columns: PID, %CPU, RSS (KB), COMMAND
+ * Parse header-less `ps -eo pid=,pcpu=,rss=,comm=` output. COMMAND is the rest
+ * of the line, so macOS paths with spaces ("Google Chrome") survive intact.
  */
 function parsePsOutput(stdout) {
-    const lines = stdout.trim().split('\n');
-    // Skip the header line
     const entries = [];
-    for (let i = 1; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (!line)
+    for (const line of stdout.split('\n')) {
+        const m = line.match(/^\s*(\d+)\s+([\d.]+)\s+(\d+)\s+(.+?)\s*$/);
+        if (!m)
             continue;
-        // Fields are whitespace-separated: PID, %CPU, RSS, COMMAND (may contain spaces)
-        const parts = line.split(/\s+/);
-        if (parts.length < 4)
-            continue;
-        const pid = parseInt(parts[0], 10);
-        const cpu = parseFloat(parts[1]);
-        const memKb = parseInt(parts[2], 10);
-        // COMMAND is everything from the 4th column onward
-        const comm = parts.slice(3).join(' ');
-        if (Number.isNaN(pid) || Number.isNaN(cpu) || Number.isNaN(memKb))
-            continue;
-        entries.push({ pid, cpu, memKb, comm });
+        entries.push({
+            pid: Number(m[1]),
+            cpu: Number(m[2]),
+            memKb: Number(m[3]),
+            comm: m[4],
+        });
     }
     return entries;
 }
 /**
- * Match a process name against a ps COMMAND column.
- * Matches if the basename of the command path equals the search name,
- * or if the command contains the search name.
+ * Does a ps COMMAND entry match a watched name? Case-insensitive on the
+ * executable's basename:
+ * - exact: `nginx` matches `/usr/sbin/nginx`;
+ * - version suffix: `python` matches `python3` and `python3.11`;
+ * - Linux truncation: a name longer than 15 chars matches its 15-char prefix;
+ * - a name containing `/` must equal the full path (macOS reports paths).
+ * Unlike a substring match, `sh` does not match `bash` or `ssh-agent`.
  */
 function matchesName(comm, searchName) {
-    // Get the basename of the command (strip path and arguments)
-    const basename = comm.split('/').pop()?.split(/\s/)[0] ?? '';
-    if (basename === searchName)
+    if (searchName.includes('/'))
+        return comm === searchName;
+    const base = (comm.split('/').pop() ?? comm).toLowerCase();
+    const name = searchName.toLowerCase();
+    if (base === name)
         return true;
-    // Also check if the full command string contains the name
-    // (handles cases like "python my-script.py" when searching for "python")
-    return comm.toLowerCase().includes(searchName.toLowerCase());
+    if (name.length > LINUX_COMM_LEN && base === name.slice(0, LINUX_COMM_LEN))
+        return true;
+    return base.startsWith(name) && /^\d[\d.]*$/.test(base.slice(name.length));
 }
-/**
- * Scan for processes by name and return their status and resource usage.
- * Works on macOS and Linux by using `ps` to list all processes.
- */
-async function scanProcesses(names) {
-    let psArgs;
-    if (process.platform === 'darwin') {
-        // macOS: -e selects all processes, -o specifies output columns
-        psArgs = ['-eo', 'pid,pcpu,rss,comm'];
-    }
-    else {
-        // Linux: -eo with similar columns
-        psArgs = ['-eo', 'pid,pcpu,rss,comm'];
-    }
-    let entries;
-    try {
-        const { stdout } = await execFileAsync('ps', psArgs);
-        entries = parsePsOutput(stdout);
-    }
-    catch {
-        // If ps fails, report all processes as unknown / not running
-        return names.map((name) => ({ name, running: false }));
-    }
-    const results = [];
-    for (const name of names) {
-        // Find all matching entries for this process name
+/** List every process. Throws if `ps` fails — callers must not read that as "all dead". */
+async function listProcesses() {
+    const { stdout } = await execFileAsync('ps', ['-eo', 'pid=,pcpu=,rss=,comm='], {
+        timeout: PS_TIMEOUT_MS,
+        maxBuffer: PS_MAX_BUFFER,
+        // Some locales print %CPU with a decimal comma ("1,5"); force "1.5".
+        env: { ...process.env, LC_ALL: 'C' },
+    });
+    return parsePsOutput(stdout);
+}
+/** Summarise each watched name against a process list (CPU and memory summed per name). */
+function matchProcesses(names, entries) {
+    return names.map((name) => {
         const matching = entries.filter((e) => matchesName(e.comm, name));
-        if (matching.length === 0) {
-            results.push({ name, running: false });
-            continue;
-        }
-        // Aggregate: take the first matching PID, sum CPU and memory across all instances
-        let totalCpu = 0;
-        let totalMemKb = 0;
-        for (const entry of matching) {
-            totalCpu += entry.cpu;
-            totalMemKb += entry.memKb;
-        }
-        results.push({
+        if (matching.length === 0)
+            return { name, running: false };
+        const totalCpu = matching.reduce((sum, e) => sum + e.cpu, 0);
+        const totalMemKb = matching.reduce((sum, e) => sum + e.memKb, 0);
+        return {
             name,
             running: true,
             pid: matching[0].pid,
+            count: matching.length,
             cpuPercent: Math.round(totalCpu * 100) / 100,
             memMb: Math.round((totalMemKb / 1024) * 100) / 100,
-        });
-    }
-    return results;
+        };
+    });
+}
+/**
+ * Scan for processes by name and return their status and resource usage.
+ * Works on macOS and Linux via `ps`. Throws when the process list is unavailable.
+ */
+async function scanProcesses(names) {
+    return matchProcesses(names, await listProcesses());
 }
 //# sourceMappingURL=process-scanner.js.map

package/dist/cjs/npcs/receptionist/defaults.js

@@ -4,6 +4,10 @@ exports.DEFAULTS = void 0;
 exports.DEFAULTS = {
     pollInterval: 60000, // 60s clock tick
     weatherRefreshMs: 15 * 60 * 1000, // refresh weather every 15 minutes
+    /** Drop a reading this old (repeated refresh failures) rather than show stale weather. */
+    weatherMaxAgeMs: 2 * 60 * 60 * 1000,
+    /** Wait this long before retrying a failed geocode / IP geo / weather call. */
+    retryBackoffMs: 5 * 60 * 1000,
     fetchTimeoutMs: 5000,
 };
 //# sourceMappingURL=defaults.js.map

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

@@ -2,24 +2,36 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReceptionistNPC = void 0;
 const polling_npc_js_1 = require("../../core/polling-npc.js");
+const errors_js_1 = require("../../core/errors.js");
 const defaults_js_1 = require("./defaults.js");
 const weather_js_1 = require("./weather.js");
 class ReceptionistNPC extends polling_npc_js_1.PollingNPC {
     explicitCoords;
     location;
     fahrenheit;
+    ipGeo;
     coords = null;
-    geoAttempted = false;
+    /** Earliest time to retry geocoding / IP geo after a failure. */
+    nextGeoAttempt = 0;
     weather = null;
-    lastWeatherFetch = 0;
+    weatherFetchedAt = 0;
+    /** Earliest time to retry the weather after a failure. */
+    nextWeatherAttempt = 0;
     constructor(config) {
         super({ ...config, pollInterval: config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval });
+        if ((config.lat === undefined) !== (config.lon === undefined)) {
+            throw new errors_js_1.NpcConfigError('--lat and --lon must be given together');
+        }
+        if (config.lat !== undefined && !(0, weather_js_1.validCoords)(config.lat, config.lon)) {
+            throw new errors_js_1.NpcConfigError('--lat must be within ±90 and --lon within ±180');
+        }
         this.explicitCoords =
             config.lat !== undefined && config.lon !== undefined
                 ? { lat: config.lat, lon: config.lon }
                 : null;
-        this.location = config.location;
+        this.location = config.location?.trim() || undefined;
         this.fahrenheit = config.fahrenheit ?? false;
+        this.ipGeo = config.ipGeo ?? true;
     }
     get name() {
         return 'receptionist';
@@ -78,41 +90,55 @@ class ReceptionistNPC extends polling_npc_js_1.PollingNPC {
         };
     }
     async refreshWeather() {
-        if (!this.coords) {
-            await this.resolveCoords();
-        }
+        const now = Date.now();
         if (!this.coords)
+            await this.resolveCoords(now);
+        // Don't show a reading that has gone stale through repeated failures.
+        if (this.weather && now - this.weatherFetchedAt > defaults_js_1.DEFAULTS.weatherMaxAgeMs) {
+            this.weather = null;
+        }
+        if (!this.coords || now < this.nextWeatherAttempt)
             return;
-        const now = Date.now();
-        if (this.weather && now - this.lastWeatherFetch < defaults_js_1.DEFAULTS.weatherRefreshMs)
+        if (this.weather && now - this.weatherFetchedAt < defaults_js_1.DEFAULTS.weatherRefreshMs)
             return;
         const w = await (0, weather_js_1.fetchWeather)(this.coords, defaults_js_1.DEFAULTS.fetchTimeoutMs);
         if (w) {
             this.weather = w;
-            this.lastWeatherFetch = now;
+            this.weatherFetchedAt = now;
+        }
+        else {
+            this.nextWeatherAttempt = now + defaults_js_1.DEFAULTS.retryBackoffMs;
         }
     }
-    async resolveCoords() {
+    async resolveCoords(now) {
         if (this.explicitCoords) {
             this.coords = this.explicitCoords;
             return;
         }
-        // Only attempt geocoding/geo-IP once per (failed) resolution to avoid
-        // hammering the keyless endpoints every poll.
-        if (this.geoAttempted)
+        // Back off after a failure rather than hitting the keyless endpoints every tick.
+        if (now < this.nextGeoAttempt)
             return;
-        this.geoAttempted = true;
+        this.nextGeoAttempt = now + defaults_js_1.DEFAULTS.retryBackoffMs;
         if (this.location) {
             this.coords = await (0, weather_js_1.geocodeLocation)(this.location, defaults_js_1.DEFAULTS.fetchTimeoutMs);
             if (this.coords)
                 return;
-            this.logger.warn(`Could not geocode "${this.location}", falling back to IP geo`);
+            this.logger.warn(`Could not geocode "${this.location}"` + (this.ipGeo ? ', falling back to IP geo' : ''));
+        }
+        if (!this.ipGeo) {
+            if (!this.location) {
+                this.nextGeoAttempt = Infinity; // nothing to resolve, ever
+                this.logger.info('No location set and IP geolocation disabled: time-only mode');
+            }
+            return;
         }
         this.coords = await (0, weather_js_1.autoGeo)(defaults_js_1.DEFAULTS.fetchTimeoutMs);
-        if (!this.coords) {
-            this.logger.warn('Weather geo unavailable — running in time-only mode');
-            // Allow a later retry.
-            this.geoAttempted = false;
+        if (this.coords) {
+            this.logger.info("Weather location estimated from this machine's IP via ipapi.co " +
+                '(set --location or --lat/--lon, or pass --no-ip-geo to disable)');
+        }
+        else {
+            this.logger.warn('Weather geo unavailable — running in time-only mode for now');
         }
     }
 }

package/dist/cjs/npcs/receptionist/weather.js

@@ -1,16 +1,20 @@
 "use strict";
-/**
- * Keyless weather + geolocation via open-meteo, with ipapi.co IP fallback.
- * All network helpers return null on failure so the receptionist can degrade
- * to a time-only mode without erroring.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.describeWmo = describeWmo;
+exports.validCoords = validCoords;
 exports.geocodeLocation = geocodeLocation;
 exports.autoGeo = autoGeo;
 exports.fetchWeather = fetchWeather;
 exports.toFahrenheit = toFahrenheit;
 exports.formatClock = formatClock;
+/**
+ * Keyless weather + geolocation via open-meteo, with an optional ipapi.co IP
+ * fallback. Every call is time- and size-bounded, validates the (untrusted)
+ * response, and returns null on failure so the receptionist can degrade to a
+ * time-only mode without erroring.
+ */
+const http_js_1 = require("../../core/http.js");
+const text_js_1 = require("../../core/text.js");
 // WMO weather-interpretation codes → human text + a glyph keyword the
 // welcome-sign renderer understands (matched by /sun|clear|partly|rain|snow|storm|fog/).
 const WMO = {
@@ -47,65 +51,56 @@ const WMO = {
 function describeWmo(code) {
     return WMO[code] ?? { text: 'Unknown', icon: 'cloud' };
 }
-async function fetchJson(url, timeoutMs) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const res = await fetch(url, {
-            signal: controller.signal,
-            headers: { 'User-Agent': 'nocville-npc' },
-        });
-        if (!res.ok)
-            return null;
-        return (await res.json());
-    }
-    catch {
-        return null;
-    }
-    finally {
-        clearTimeout(timer);
-    }
+/** A finite, in-range latitude/longitude pair. */
+function validCoords(lat, lon) {
+    const la = (0, http_js_1.finiteNumber)(lat);
+    const lo = (0, http_js_1.finiteNumber)(lon);
+    return la !== null && lo !== null && Math.abs(la) <= 90 && Math.abs(lo) <= 180;
 }
-/** Resolve a place name to coordinates via the open-meteo geocoding API. */
-async function geocodeLocation(name, timeoutMs = 5000) {
-    const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(name)}&count=1`;
-    const res = await fetchJson(url, timeoutMs);
-    const first = res?.['results']?.[0];
-    if (!first || typeof first['latitude'] !== 'number')
+function coordsFrom(rec, labelKey) {
+    if (!validCoords(rec['latitude'], rec['longitude']))
         return null;
+    const label = rec[labelKey];
     return {
-        lat: first['latitude'],
-        lon: first['longitude'],
-        label: first['name'] ?? name,
+        lat: rec['latitude'],
+        lon: rec['longitude'],
+        label: typeof label === 'string' ? (0, text_js_1.sanitizeText)(label, 60) : undefined,
     };
 }
-/** Best-effort IP geolocation via ipapi.co (keyless). */
+/** Resolve a place name to coordinates via the open-meteo geocoding API. */
+async function geocodeLocation(name, timeoutMs = 5000) {
+    const url = 'https://geocoding-api.open-meteo.com/v1/search' +
+        `?name=${encodeURIComponent(name.slice(0, 100))}&count=1`;
+    const results = (0, http_js_1.asRecord)(await (0, http_js_1.fetchJson)(url, { timeoutMs }))?.['results'];
+    const first = Array.isArray(results) ? (0, http_js_1.asRecord)(results[0]) : null;
+    return first ? coordsFrom(first, 'name') : null;
+}
+/**
+ * Best-effort IP geolocation via ipapi.co (keyless). This sends the machine's
+ * public IP to a third party, so the receptionist only calls it when no place
+ * was configured and the user hasn't opted out. Only the coordinates are used;
+ * nothing from the response is pushed to Nocville.
+ */
 async function autoGeo(timeoutMs = 5000) {
-    const res = await fetchJson('https://ipapi.co/json/', timeoutMs);
-    if (!res || typeof res['latitude'] !== 'number')
-        return null;
-    return {
-        lat: res['latitude'],
-        lon: res['longitude'],
-        label: res['city'],
-    };
+    const res = (0, http_js_1.asRecord)(await (0, http_js_1.fetchJson)('https://ipapi.co/json/', { timeoutMs }));
+    return res ? coordsFrom(res, 'city') : null;
 }
 /** Fetch current temperature, weather code, and wind for coordinates. */
 async function fetchWeather(coords, timeoutMs = 5000) {
     const url = `https://api.open-meteo.com/v1/forecast?latitude=${coords.lat}` +
         `&longitude=${coords.lon}&current=temperature_2m,weather_code,wind_speed_10m`;
-    const res = await fetchJson(url, timeoutMs);
-    const cur = res?.['current'];
-    if (!cur || typeof cur['temperature_2m'] !== 'number')
+    const cur = (0, http_js_1.asRecord)((0, http_js_1.asRecord)(await (0, http_js_1.fetchJson)(url, { timeoutMs }))?.['current']);
+    const temp = (0, http_js_1.finiteNumber)(cur?.['temperature_2m']);
+    if (!cur || temp === null || Math.abs(temp) > 100)
         return null;
-    const code = Number(cur['weather_code'] ?? 0);
+    const code = (0, http_js_1.finiteNumber)(cur['weather_code']) ?? -1;
     const { text, icon } = describeWmo(code);
     return {
-        tempC: Math.round(cur['temperature_2m']),
+        tempC: Math.round(temp),
         code,
         text,
         icon,
-        windKph: Math.round(Number(cur['wind_speed_10m'] ?? 0)),
+        windKph: Math.round(Math.max(0, (0, http_js_1.finiteNumber)(cur['wind_speed_10m']) ?? 0)),
     };
 }
 /** Convert Celsius to Fahrenheit, rounded. */

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