@nocville/npc 0.0.0-stage → 0.2.0

package/dist/npcs/log-watcher/index.d.ts

@@ -0,0 +1,45 @@
+import { BaseNPC } from '../../core/base-npc.js';
+import type { NpcConfig, Archetype, BehaviorHints, CompanionDecl } from '../../core/types.js';
+export interface LogWatcherConfig extends NpcConfig {
+    files: string[];
+    errorPattern?: string;
+    warningPattern?: string;
+    windowSeconds?: number;
+    errorWarn?: number;
+    errorCrit?: number;
+    reportInterval?: number;
+}
+export declare class LogWatcherNPC extends BaseNPC {
+    private tailers;
+    private timer;
+    private entries;
+    private recentLines;
+    private lastBurstPush;
+    private errorRegex;
+    private warningRegex;
+    private windowMs;
+    private errorWarn;
+    private errorCrit;
+    private reportInterval;
+    private files;
+    constructor(config: LogWatcherConfig);
+    get name(): string;
+    protected get defaultDisplayName(): string;
+    get archetype(): Archetype;
+    get heartbeatSeconds(): number;
+    get behavior(): BehaviorHints;
+    get companion(): CompanionDecl;
+    protected onStart(): Promise<void>;
+    protected onStop(): Promise<void>;
+    private handleLine;
+    /** A fresh error triggers an immediate push, debounced to at most once / 5s. */
+    private onErrorBurst;
+    private pruneWindow;
+    private report;
+    /**
+     * Build and push the current status. If `overrideMessage` is set (burst push),
+     * it drives the bubble and the status floors at warning.
+     */
+    private pushReport;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/npcs/log-watcher/index.js

@@ -0,0 +1,157 @@
+import { basename } from 'node:path';
+import { BaseNPC } from '../../core/base-npc.js';
+import { evaluateThreshold, worstStatus } from '../../core/thresholds.js';
+import { truncate } from '../../core/text.js';
+import { createTailer } from './tail.js';
+import { classifyLine, pushRecent, buildLogScreen, shouldEmitBurst } from './buffer.js';
+import { DEFAULTS } from './defaults.js';
+export class LogWatcherNPC extends BaseNPC {
+    tailers = [];
+    timer = null;
+    entries = [];
+    recentLines = [];
+    lastBurstPush = 0;
+    errorRegex;
+    warningRegex;
+    windowMs;
+    errorWarn;
+    errorCrit;
+    reportInterval;
+    files;
+    constructor(config) {
+        super(config);
+        this.files = config.files;
+        this.errorRegex = new RegExp(config.errorPattern ?? DEFAULTS.errorPattern);
+        this.warningRegex = new RegExp(config.warningPattern ?? DEFAULTS.warningPattern);
+        this.windowMs = (config.windowSeconds ?? DEFAULTS.windowSeconds) * 1000;
+        this.errorWarn = config.errorWarn ?? DEFAULTS.errorWarn;
+        this.errorCrit = config.errorCrit ?? DEFAULTS.errorCrit;
+        this.reportInterval = config.reportInterval ?? DEFAULTS.reportInterval;
+    }
+    get name() {
+        return 'log-watcher';
+    }
+    get defaultDisplayName() {
+        const first = this.files[0];
+        return first ? `Logs: ${basename(first)}` : 'Logs';
+    }
+    get archetype() {
+        return 'service';
+    }
+    get heartbeatSeconds() {
+        return 30;
+    }
+    get behavior() {
+        return { idle: 'wander' };
+    }
+    get companion() {
+        return {
+            screenType: 'log-terminal',
+            size: { w: 2, h: 2 },
+            placement: 'adjacent-wall',
+            label: this.files[0] ? basename(this.files[0]) : 'log',
+        };
+    }
+    async onStart() {
+        for (const filePath of this.files) {
+            this.logger.info(`Tailing ${filePath}`);
+            const tailer = createTailer(filePath, (line) => {
+                this.handleLine(line);
+            });
+            this.tailers.push(tailer);
+        }
+        // Report immediately, then on interval
+        await this.report();
+        this.timer = setInterval(() => {
+            void this.report();
+        }, this.reportInterval);
+    }
+    async onStop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        for (const tailer of this.tailers) {
+            tailer.close();
+        }
+        this.tailers = [];
+    }
+    handleLine(line) {
+        const now = Date.now();
+        const level = classifyLine(line, this.errorRegex, this.warningRegex);
+        // Ring buffer holds ALL lines (matched ones flagged) for the log TV.
+        pushRecent(this.recentLines, line, level);
+        if (level === 'error') {
+            this.entries.push({ timestamp: now, type: 'error', message: line });
+            this.onErrorBurst(line);
+        }
+        else if (level === 'warning') {
+            this.entries.push({ timestamp: now, type: 'warning', message: line });
+        }
+    }
+    /** A fresh error triggers an immediate push, debounced to at most once / 5s. */
+    onErrorBurst(line) {
+        const now = Date.now();
+        if (!shouldEmitBurst(this.lastBurstPush, now))
+            return;
+        this.lastBurstPush = now;
+        void this.pushReport(truncate(line, 200), 'error');
+    }
+    pruneWindow() {
+        const cutoff = Date.now() - this.windowMs;
+        this.entries = this.entries.filter((e) => e.timestamp >= cutoff);
+    }
+    async report() {
+        if (this.state !== 'running')
+            return;
+        await this.pushReport();
+    }
+    /**
+     * Build and push the current status. If `overrideMessage` is set (burst push),
+     * it drives the bubble and the status floors at warning.
+     */
+    async pushReport(overrideMessage, subStatus) {
+        if (this.state !== 'running')
+            return;
+        this.pruneWindow();
+        const errorCount = this.entries.filter((e) => e.type === 'error').length;
+        const warningCount = this.entries.filter((e) => e.type === 'warning').length;
+        const windowSeconds = this.windowMs / 1000;
+        let status = evaluateThreshold(errorCount, {
+            warning: this.errorWarn,
+            critical: this.errorCrit,
+            direction: 'above',
+        });
+        if (overrideMessage)
+            status = worstStatus([status, 'warning']);
+        const mood = status === 'critical' ? 'stressed' : status === 'warning' ? 'concerned' : 'happy';
+        const lastError = this.entries.filter((e) => e.type === 'error').at(-1);
+        const message = overrideMessage ??
+            (errorCount > 0
+                ? `${errorCount} error${errorCount !== 1 ? 's' : ''} in last ${windowSeconds / 60}min across ${this.files.length} file${this.files.length !== 1 ? 's' : ''}`
+                : `No errors in last ${windowSeconds / 60}min`);
+        const metrics = {
+            status,
+            mood,
+            message,
+            subStatus,
+            screenData: buildLogScreen(this.recentLines),
+            metrics: {
+                error_count: errorCount,
+                warning_count: warningCount,
+                window_seconds: windowSeconds,
+                files_watched: this.files.length,
+                last_error_message: lastError?.message ?? '',
+            },
+        };
+        try {
+            await this.pushMetrics(metrics);
+        }
+        catch (err) {
+            this.logger.error('Failed to push metrics', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/npcs/log-watcher/tail.d.ts

@@ -0,0 +1,9 @@
+export interface FileTailer {
+    close(): void;
+}
+/**
+ * Tail a file by watching for changes and reading new lines from the last
+ * known byte offset. Handles file rotation (size shrinks -> reset to 0).
+ */
+export declare function createTailer(filePath: string, onLine: (line: string) => void): FileTailer;
+//# sourceMappingURL=tail.d.ts.map

package/dist/npcs/log-watcher/tail.js

@@ -0,0 +1,78 @@
+import { watch, createReadStream, promises as fsp } from 'node:fs';
+import { createInterface } from 'node:readline';
+/**
+ * Tail a file by watching for changes and reading new lines from the last
+ * known byte offset. Handles file rotation (size shrinks -> reset to 0).
+ */
+export function createTailer(filePath, onLine) {
+    let offset = 0;
+    let reading = false;
+    let watcher = null;
+    let closed = false;
+    async function init() {
+        // Start at the end of the file so we only read new lines
+        try {
+            const stats = await fsp.stat(filePath);
+            offset = stats.size;
+        }
+        catch {
+            // File may not exist yet; start at 0
+            offset = 0;
+        }
+        watcher = watch(filePath, () => {
+            if (!closed) {
+                void readNewLines();
+            }
+        });
+        // Ignore watcher errors (e.g. file deleted then recreated)
+        watcher.on('error', () => { });
+    }
+    async function readNewLines() {
+        if (reading || closed)
+            return;
+        reading = true;
+        try {
+            const stats = await fsp.stat(filePath);
+            // File rotation detected: size smaller than our offset
+            if (stats.size < offset) {
+                offset = 0;
+            }
+            // Nothing new to read
+            if (stats.size === offset) {
+                reading = false;
+                return;
+            }
+            const stream = createReadStream(filePath, {
+                start: offset,
+                encoding: 'utf-8',
+            });
+            const rl = createInterface({ input: stream, crlfDelay: Infinity });
+            let bytesRead = 0;
+            for await (const line of rl) {
+                if (closed)
+                    break;
+                // Account for line content + newline character
+                bytesRead += Buffer.byteLength(line, 'utf-8') + 1;
+                onLine(line);
+            }
+            offset += bytesRead;
+        }
+        catch {
+            // File may have been removed; ignore and wait for next change
+        }
+        finally {
+            reading = false;
+        }
+    }
+    void init();
+    return {
+        close() {
+            closed = true;
+            if (watcher) {
+                watcher.close();
+                watcher = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=tail.js.map

package/dist/npcs/process-watcher/defaults.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULTS: {
+    pollInterval: number;
+    cpuWarn: number;
+    memWarn: number;
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/process-watcher/defaults.js

@@ -0,0 +1,6 @@
+export const DEFAULTS = {
+    pollInterval: 15000, // 15 seconds
+    cpuWarn: 80, // percent
+    memWarn: 500, // MB
+};
+//# sourceMappingURL=defaults.js.map

package/dist/npcs/process-watcher/index.d.ts

@@ -0,0 +1,26 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import type { PollingNpcConfig } from '../../core/polling-npc.js';
+import type { CollectedMetrics, Archetype, CompanionDecl } from '../../core/types.js';
+export interface ProcessWatcherConfig extends PollingNpcConfig {
+    /** List of process names to watch */
+    processes: string[];
+    /** CPU usage percent threshold for warning status (default: 80) */
+    cpuWarn?: number;
+    /** Memory usage MB threshold for warning status (default: 500) */
+    memWarn?: number;
+}
+export declare class ProcessWatcherNPC extends PollingNPC {
+    private processes;
+    private cpuWarn;
+    private memWarn;
+    private cpuHistories;
+    private previousRunning;
+    constructor(config: ProcessWatcherConfig);
+    get name(): string;
+    protected get defaultDisplayName(): string;
+    get archetype(): Archetype;
+    get heartbeatSeconds(): number;
+    get companion(): CompanionDecl;
+    protected collect(): Promise<CollectedMetrics>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,136 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import { worstStatus } from '../../core/thresholds.js';
+import { pushHistory } from '../../core/screen.js';
+import { scanProcesses, detectTransitions } from './process-scanner.js';
+import { DEFAULTS } from './defaults.js';
+/** Max per-process panels on the companion dashboard. */
+const MAX_PANELS = 8;
+export class ProcessWatcherNPC extends 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.cpuWarn;
+        this.memWarn = config.memWarn ?? 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 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) ?? [];
+            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 = detectTransitions(this.previousRunning, currentRunning);
+        }
+        this.previousRunning = currentRunning;
+        const status = 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,
+        };
+    }
+}
+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/npcs/process-watcher/process-scanner.d.ts

@@ -0,0 +1,19 @@
+export interface ProcessInfo {
+    name: string;
+    running: boolean;
+    pid?: number;
+    cpuPercent?: number;
+    memMb?: number;
+}
+/**
+ * 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.
+ */
+export declare function detectTransitions(prev: Set<string>, curr: Set<string>): string[];
+/**
+ * Scan for processes by name and return their status and resource usage.
+ * Works on macOS and Linux by using `ps` to list all processes.
+ */
+export declare function scanProcesses(names: string[]): Promise<ProcessInfo[]>;
+//# sourceMappingURL=process-scanner.d.ts.map

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

@@ -0,0 +1,110 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(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.
+ */
+export 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.
+ */
+export 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/npcs/receptionist/defaults.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULTS: {
+    pollInterval: number;
+    weatherRefreshMs: number;
+    fetchTimeoutMs: number;
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/receptionist/defaults.js

@@ -0,0 +1,6 @@
+export const DEFAULTS = {
+    pollInterval: 60000, // 60s clock tick
+    weatherRefreshMs: 15 * 60 * 1000, // refresh weather every 15 minutes
+    fetchTimeoutMs: 5000,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/npcs/receptionist/index.d.ts

@@ -0,0 +1,29 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import type { PollingNpcConfig } from '../../core/polling-npc.js';
+import type { CollectedMetrics, Archetype, BehaviorHints, CompanionDecl } from '../../core/types.js';
+export interface ReceptionistConfig extends PollingNpcConfig {
+    lat?: number;
+    lon?: number;
+    location?: string;
+    /** Display temperature in Fahrenheit instead of Celsius. */
+    fahrenheit?: boolean;
+}
+export declare class ReceptionistNPC extends PollingNPC {
+    private explicitCoords;
+    private location?;
+    private fahrenheit;
+    private coords;
+    private geoAttempted;
+    private weather;
+    private lastWeatherFetch;
+    constructor(config: ReceptionistConfig);
+    get name(): string;
+    protected get defaultDisplayName(): string;
+    get archetype(): Archetype;
+    get behavior(): BehaviorHints;
+    get companion(): CompanionDecl;
+    protected collect(): Promise<CollectedMetrics>;
+    private refreshWeather;
+    private resolveCoords;
+}
+//# sourceMappingURL=index.d.ts.map