@nocville/npc 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessWatcherNPC = 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 process_scanner_js_1 = require("./process-scanner.js");
+const defaults_js_1 = require("./defaults.js");
+/** Max per-process panels on the companion dashboard. */
+const MAX_PANELS = 8;
+class ProcessWatcherNPC extends polling_npc_js_1.PollingNPC {
+    processes;
+    cpuWarn;
+    memWarn;
+    cpuHistories = new Map();
+    previousRunning = null;
+    constructor(config) {
+        if (process.platform === 'win32') {
+            throw new Error('process-watcher is not supported on Windows (relies on the POSIX `ps` command). ' +
+                'Run it under WSL/Linux, or use system-monitor instead.');
+        }
+        super(config);
+        this.processes = config.processes;
+        this.cpuWarn = config.cpuWarn ?? defaults_js_1.DEFAULTS.cpuWarn;
+        this.memWarn = config.memWarn ?? defaults_js_1.DEFAULTS.memWarn;
+    }
+    get name() {
+        return 'process-watcher';
+    }
+    get defaultDisplayName() {
+        return 'Processes';
+    }
+    get archetype() {
+        return 'service';
+    }
+    get heartbeatSeconds() {
+        return 30;
+    }
+    get companion() {
+        return {
+            screenType: 'dashboard-wall',
+            size: { w: 2, h: 2 },
+            placement: 'on-desk',
+            label: 'Processes',
+        };
+    }
+    async collect() {
+        const infos = await (0, process_scanner_js_1.scanProcesses)(this.processes);
+        const statuses = [];
+        const messageParts = [];
+        const metrics = {};
+        const panels = [];
+        let totalRunning = 0;
+        let totalMissing = 0;
+        for (const info of infos) {
+            const safeKey = info.name.replace(/[^a-zA-Z0-9_]/g, '_');
+            if (!info.running) {
+                statuses.push('critical');
+                messageParts.push(`${info.name}: NOT FOUND`);
+                metrics[`${safeKey}_running`] = 0;
+                metrics[`${safeKey}_cpu`] = 0;
+                metrics[`${safeKey}_mem_mb`] = 0;
+                totalMissing++;
+                if (panels.length < MAX_PANELS) {
+                    panels.push({ label: info.name, value: 'DOWN', color: 'red' });
+                }
+                continue;
+            }
+            totalRunning++;
+            const cpu = info.cpuPercent ?? 0;
+            metrics[`${safeKey}_running`] = 1;
+            metrics[`${safeKey}_cpu`] = cpu;
+            metrics[`${safeKey}_mem_mb`] = info.memMb ?? 0;
+            const history = this.cpuHistories.get(info.name) ?? [];
+            (0, screen_js_1.pushHistory)(history, cpu);
+            this.cpuHistories.set(info.name, history);
+            const cpuHigh = cpu >= this.cpuWarn;
+            const memHigh = (info.memMb ?? 0) >= this.memWarn;
+            if (cpuHigh || memHigh) {
+                statuses.push('warning');
+                const warnings = [];
+                if (cpuHigh)
+                    warnings.push(`cpu=${cpu}%`);
+                if (memHigh)
+                    warnings.push(`mem=${info.memMb}MB`);
+                messageParts.push(`${info.name}: WARN (${warnings.join(', ')})`);
+            }
+            else {
+                statuses.push('healthy');
+                messageParts.push(`${info.name}: OK`);
+            }
+            if (panels.length < MAX_PANELS) {
+                panels.push({
+                    label: info.name,
+                    value: `${cpu}%`,
+                    color: cpuHigh || memHigh ? 'amber' : 'green',
+                    sparkline: [...history],
+                });
+            }
+        }
+        metrics['total_watched'] = this.processes.length;
+        metrics['total_running'] = totalRunning;
+        metrics['total_missing'] = totalMissing;
+        // Transition speech: compare the running set to last poll's. On the first
+        // poll we only seed the set (no bogus "is back" for already-running procs).
+        const currentRunning = new Set(infos.filter((i) => i.running).map((i) => i.name));
+        let transitions = [];
+        if (this.previousRunning !== null) {
+            transitions = (0, process_scanner_js_1.detectTransitions)(this.previousRunning, currentRunning);
+        }
+        this.previousRunning = currentRunning;
+        const status = (0, thresholds_js_1.worstStatus)(statuses);
+        const mood = deriveMood(status);
+        // A death message takes over the bubble this cycle so it reads as an alert.
+        const message = transitions.length > 0 ? transitions.join(' · ') : messageParts.join(' | ');
+        const screenData = { layout: 'multi-metric', values: panels };
+        return {
+            status,
+            mood,
+            message,
+            subStatus: totalMissing > 0 ? 'process-down' : undefined,
+            screenData,
+            metrics,
+        };
+    }
+}
+exports.ProcessWatcherNPC = ProcessWatcherNPC;
+function deriveMood(status) {
+    switch (status) {
+        case 'healthy':
+            return 'happy';
+        case 'warning':
+            return 'concerned';
+        case 'critical':
+            return 'stressed';
+        default:
+            return 'idle';
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectTransitions = detectTransitions;
+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);
+/**
+ * Compare the previous and current running-process sets and return speech
+ * strings for any transitions: "<name> died!" when a process disappears and
+ * "<name> is back" when one returns.
+ */
+function detectTransitions(prev, curr) {
+    const messages = [];
+    for (const name of prev) {
+        if (!curr.has(name))
+            messages.push(`${name} died!`);
+    }
+    for (const name of curr) {
+        if (!prev.has(name))
+            messages.push(`${name} is back`);
+    }
+    return messages;
+}
+/**
+ * Parse the output of `ps` into structured entries.
+ * Expects columns: PID, %CPU, RSS (KB), COMMAND
+ */
+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)
+            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 });
+    }
+    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.
+ */
+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)
+        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());
+}
+/**
+ * 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
+        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({
+            name,
+            running: true,
+            pid: matching[0].pid,
+            cpuPercent: Math.round(totalCpu * 100) / 100,
+            memMb: Math.round((totalMemKb / 1024) * 100) / 100,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=process-scanner.js.map

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

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULTS = void 0;
+exports.DEFAULTS = {
+    pollInterval: 60000, // 60s clock tick
+    weatherRefreshMs: 15 * 60 * 1000, // refresh weather every 15 minutes
+    fetchTimeoutMs: 5000,
+};
+//# sourceMappingURL=defaults.js.map

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

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReceptionistNPC = void 0;
+const polling_npc_js_1 = require("../../core/polling-npc.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;
+    coords = null;
+    geoAttempted = false;
+    weather = null;
+    lastWeatherFetch = 0;
+    constructor(config) {
+        super({ ...config, pollInterval: config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval });
+        this.explicitCoords =
+            config.lat !== undefined && config.lon !== undefined
+                ? { lat: config.lat, lon: config.lon }
+                : null;
+        this.location = config.location;
+        this.fahrenheit = config.fahrenheit ?? false;
+    }
+    get name() {
+        return 'receptionist';
+    }
+    get defaultDisplayName() {
+        return 'Reception';
+    }
+    get archetype() {
+        return 'custom';
+    }
+    get behavior() {
+        return {
+            greetPlayers: true,
+            patrol: { everyMinutes: [15, 30], stops: 5 },
+            idle: 'stay',
+            home: { near: 'entrance' },
+        };
+    }
+    get companion() {
+        return {
+            screenType: 'welcome-sign',
+            size: { w: 2, h: 1 },
+            placement: 'adjacent-wall',
+            label: 'Welcome',
+        };
+    }
+    async collect() {
+        await this.refreshWeather();
+        const now = new Date();
+        const { day, date, time } = (0, weather_js_1.formatClock)(now);
+        const values = [
+            { label: 'time', value: time },
+            { label: 'day', value: day },
+            { label: 'date', value: date },
+        ];
+        let message = `${day} ${time}`;
+        const metrics = { weather_ok: this.weather ? 1 : 0 };
+        if (this.weather) {
+            const temp = this.fahrenheit
+                ? `${(0, weather_js_1.toFahrenheit)(this.weather.tempC)}°F`
+                : `${this.weather.tempC}°C`;
+            message += ` • ${temp} ${this.weather.text}`;
+            values.push({ label: 'temp', value: temp }, { label: 'condition', value: this.weather.text }, { label: 'icon', value: this.weather.icon });
+            metrics['temp_c'] = this.weather.tempC;
+            metrics['weather_code'] = this.weather.code;
+            metrics['wind_kph'] = this.weather.windKph;
+        }
+        // The receptionist is a greeter/clock — it stays healthy even when weather
+        // is unavailable (degraded time-only mode).
+        return {
+            status: 'healthy',
+            mood: 'happy',
+            message,
+            screenData: { layout: 'welcome-sign', values },
+            metrics,
+        };
+    }
+    async refreshWeather() {
+        if (!this.coords) {
+            await this.resolveCoords();
+        }
+        if (!this.coords)
+            return;
+        const now = Date.now();
+        if (this.weather && now - this.lastWeatherFetch < 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;
+        }
+    }
+    async resolveCoords() {
+        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)
+            return;
+        this.geoAttempted = true;
+        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.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;
+        }
+    }
+}
+exports.ReceptionistNPC = ReceptionistNPC;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,129 @@
+"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.geocodeLocation = geocodeLocation;
+exports.autoGeo = autoGeo;
+exports.fetchWeather = fetchWeather;
+exports.toFahrenheit = toFahrenheit;
+exports.formatClock = formatClock;
+// 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 = {
+    0: { text: 'Clear', icon: 'clear' },
+    1: { text: 'Mainly clear', icon: 'partly' },
+    2: { text: 'Partly cloudy', icon: 'partly' },
+    3: { text: 'Overcast', icon: 'cloud' },
+    45: { text: 'Fog', icon: 'fog' },
+    48: { text: 'Rime fog', icon: 'fog' },
+    51: { text: 'Light drizzle', icon: 'drizzle' },
+    53: { text: 'Drizzle', icon: 'drizzle' },
+    55: { text: 'Heavy drizzle', icon: 'drizzle' },
+    56: { text: 'Freezing drizzle', icon: 'drizzle' },
+    57: { text: 'Freezing drizzle', icon: 'drizzle' },
+    61: { text: 'Light rain', icon: 'rain' },
+    63: { text: 'Rain', icon: 'rain' },
+    65: { text: 'Heavy rain', icon: 'rain' },
+    66: { text: 'Freezing rain', icon: 'rain' },
+    67: { text: 'Freezing rain', icon: 'rain' },
+    71: { text: 'Light snow', icon: 'snow' },
+    73: { text: 'Snow', icon: 'snow' },
+    75: { text: 'Heavy snow', icon: 'snow' },
+    77: { text: 'Snow grains', icon: 'snow' },
+    80: { text: 'Rain showers', icon: 'shower' },
+    81: { text: 'Rain showers', icon: 'shower' },
+    82: { text: 'Violent showers', icon: 'shower' },
+    85: { text: 'Snow showers', icon: 'snow' },
+    86: { text: 'Snow showers', icon: 'snow' },
+    95: { text: 'Thunderstorm', icon: 'storm' },
+    96: { text: 'Thunderstorm', icon: 'storm' },
+    99: { text: 'Thunderstorm', icon: 'storm' },
+};
+/** Map a WMO weather code to display text + a renderer glyph keyword. */
+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);
+    }
+}
+/** 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')
+        return null;
+    return {
+        lat: first['latitude'],
+        lon: first['longitude'],
+        label: first['name'] ?? name,
+    };
+}
+/** Best-effort IP geolocation via ipapi.co (keyless). */
+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'],
+    };
+}
+/** 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')
+        return null;
+    const code = Number(cur['weather_code'] ?? 0);
+    const { text, icon } = describeWmo(code);
+    return {
+        tempC: Math.round(cur['temperature_2m']),
+        code,
+        text,
+        icon,
+        windKph: Math.round(Number(cur['wind_speed_10m'] ?? 0)),
+    };
+}
+/** Convert Celsius to Fahrenheit, rounded. */
+function toFahrenheit(c) {
+    return Math.round((c * 9) / 5 + 32);
+}
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+/** Format a Date into day/date/time parts for the welcome sign. */
+function formatClock(d) {
+    const day = DAYS[d.getDay()];
+    let h = d.getHours();
+    const m = d.getMinutes();
+    const ampm = h >= 12 ? 'PM' : 'AM';
+    h = h % 12;
+    if (h === 0)
+        h = 12;
+    const time = `${h}:${String(m).padStart(2, '0')} ${ampm}`;
+    const date = `${d.getMonth() + 1}/${d.getDate()}`;
+    return { day, date, time };
+}
+//# sourceMappingURL=weather.js.map

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

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCpuSampler = createCpuSampler;
+exports.collectMemory = collectMemory;
+exports.collectDisk = collectDisk;
+const node_os_1 = __importDefault(require("node:os"));
+const node_fs_1 = require("node:fs");
+function aggregate(cpus) {
+    let idle = 0;
+    let total = 0;
+    for (const cpu of cpus) {
+        const t = cpu.times;
+        idle += t.idle;
+        total += t.user + t.nice + t.sys + t.irq + t.idle;
+    }
+    return { idle, total };
+}
+/**
+ * Stateful CPU sampler that computes usage from the delta between consecutive
+ * `os.cpus()` snapshots — no blocking sleep. The first sample reports usage
+ * since system boot; subsequent samples report usage since the previous call.
+ *
+ * `readCpus`/`readLoad` are injectable for testing.
+ */
+function createCpuSampler(readCpus = () => node_os_1.default.cpus(), readLoad = () => node_os_1.default.loadavg()[0] ?? 0) {
+    let prev = null;
+    return {
+        sample() {
+            const cur = aggregate(readCpus());
+            const loadAvg1m = Math.round(readLoad() * 100) / 100;
+            const base = prev ?? { idle: 0, total: 0 };
+            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;
+            return { percent, loadAvg1m };
+        },
+    };
+}
+/**
+ * Collect memory usage from OS.
+ */
+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 };
+}
+/**
+ * Collect disk usage via fs.statfs (Node 18.15+).
+ */
+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 };
+}
+//# sourceMappingURL=collectors.js.map

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

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_THRESHOLDS = exports.DEFAULTS = void 0;
+exports.DEFAULTS = {
+    pollInterval: 15000,
+    diskPath: '/',
+};
+exports.DEFAULT_THRESHOLDS = {
+    cpu: { warning: 75, critical: 90, direction: 'above' },
+    mem: { warning: 75, critical: 90, direction: 'above' },
+    disk: { warning: 75, critical: 90, direction: 'above' },
+};
+//# sourceMappingURL=defaults.js.map