@nocville/npc 0.0.0-stage → 0.2.1

package/dist/npcs/internet-connectivity/index.js

@@ -0,0 +1,246 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import { evaluateThreshold, worstStatus } from '../../core/thresholds.js';
+import { statusColor, pushHistory } from '../../core/screen.js';
+import { numberFlag, stringFlag } from '../../core/config.js';
+import { checkDns, checkHttp, checkLatency } from './checks.js';
+import { DEFAULTS } from './defaults.js';
+/**
+ * Derive overall status from live per-check thresholds. All checks failing is
+ * critical; any partial failure is at least a warning; slow-but-working checks
+ * escalate per their own thresholds.
+ */
+export function evaluateConnectivityStatus(sample, thresholds) {
+    if (sample.allFailed)
+        return 'critical';
+    const timeStatus = worstStatus([
+        evaluateThreshold(sample.dnsAvg, thresholds.dnsTime),
+        evaluateThreshold(sample.httpAvg, thresholds.httpTime),
+        evaluateThreshold(sample.latencyAvg, thresholds.latencyTime),
+    ]);
+    const failStatus = sample.anyFailed ? 'warning' : 'healthy';
+    return worstStatus([timeStatus, failStatus]);
+}
+/** Scale a threshold set by a ratio, preserving direction. */
+function scaleThresholds(base, ratio) {
+    const scale = (t) => ({
+        warning: Math.round(t.warning * ratio),
+        critical: Math.round(t.critical * ratio),
+        direction: t.direction,
+    });
+    return {
+        dnsTime: scale(base.dnsTime),
+        httpTime: scale(base.httpTime),
+        latencyTime: scale(base.latencyTime),
+    };
+}
+export class InternetConnectivityNPC extends PollingNPC {
+    dnsHosts;
+    httpUrls;
+    latencyHosts;
+    httpTimeout;
+    thresholds;
+    dnsHistory = [];
+    httpHistory = [];
+    latencyHistory = [];
+    constructor(config) {
+        super({
+            ...config,
+            pollInterval: config.pollInterval ?? DEFAULTS.pollInterval,
+        });
+        this.dnsHosts = config.dnsHosts ?? DEFAULTS.dnsHosts;
+        this.httpUrls = config.httpUrls ?? DEFAULTS.httpUrls;
+        this.latencyHosts = config.latencyHosts
+            ? parseLatencyHosts(config.latencyHosts)
+            : DEFAULTS.latencyHosts;
+        this.httpTimeout = config.httpTimeout ?? DEFAULTS.httpTimeout;
+        // Threshold resolution: explicit thresholds win; else if the legacy
+        // --slow-threshold differs from the default, scale the live thresholds by
+        // that ratio for back-compat; else use the defaults.
+        if (config.thresholds) {
+            this.thresholds = config.thresholds;
+        }
+        else if (config.slowThreshold && config.slowThreshold !== DEFAULTS.slowThreshold) {
+            this.thresholds = scaleThresholds(DEFAULTS.thresholds, config.slowThreshold / DEFAULTS.slowThreshold);
+        }
+        else {
+            this.thresholds = DEFAULTS.thresholds;
+        }
+    }
+    get name() {
+        return 'internet-connectivity';
+    }
+    get defaultDisplayName() {
+        return 'Internet';
+    }
+    get archetype() {
+        return 'gateway';
+    }
+    get behavior() {
+        return { idle: 'wander' };
+    }
+    get companion() {
+        return {
+            screenType: 'dashboard-wall',
+            size: { w: 2, h: 2 },
+            placement: 'adjacent-wall',
+            label: 'Internet',
+        };
+    }
+    async collect() {
+        const [dnsResults, httpResults, latencyResults] = await Promise.all([
+            checkDns(this.dnsHosts),
+            checkHttp(this.httpUrls, this.httpTimeout),
+            checkLatency(this.latencyHosts),
+        ]);
+        const dnsOk = dnsResults.filter((r) => r.ok).length;
+        const dnsFail = dnsResults.length - dnsOk;
+        const httpOk = httpResults.filter((r) => r.ok).length;
+        const httpFail = httpResults.length - httpOk;
+        const dnsAvg = avgTime(dnsResults);
+        const httpAvg = avgTime(httpResults);
+        const latencyAvg = avgTime(latencyResults);
+        const isOnline = dnsOk > 0 || httpOk > 0;
+        const allFailed = dnsOk === 0 && httpOk === 0;
+        const anyFailed = dnsResults.some((r) => !r.ok) ||
+            httpResults.some((r) => !r.ok) ||
+            latencyResults.some((r) => !r.ok);
+        const status = evaluateConnectivityStatus({ allFailed, anyFailed, dnsAvg, httpAvg, latencyAvg }, this.thresholds);
+        const mood = statusToMood(status);
+        const message = allFailed
+            ? this.buildOfflineMessage(dnsResults, httpResults)
+            : this.buildOnlineMessage(dnsAvg, httpAvg, latencyAvg);
+        pushHistory(this.dnsHistory, round(dnsAvg));
+        pushHistory(this.httpHistory, round(httpAvg));
+        pushHistory(this.latencyHistory, round(latencyAvg));
+        const screenData = {
+            layout: 'multi-metric',
+            values: [
+                {
+                    label: 'DNS',
+                    value: `${round(dnsAvg)}ms`,
+                    color: statusColor(evaluateThreshold(dnsAvg, this.thresholds.dnsTime)),
+                    sparkline: [...this.dnsHistory],
+                },
+                {
+                    label: 'HTTP',
+                    value: `${round(httpAvg)}ms`,
+                    color: statusColor(evaluateThreshold(httpAvg, this.thresholds.httpTime)),
+                    sparkline: [...this.httpHistory],
+                },
+                {
+                    label: 'TCP',
+                    value: `${round(latencyAvg)}ms`,
+                    color: statusColor(evaluateThreshold(latencyAvg, this.thresholds.latencyTime)),
+                    sparkline: [...this.latencyHistory],
+                },
+                { label: 'NET', value: isOnline ? 'ONLINE' : 'OFFLINE', color: isOnline ? 'green' : 'red' },
+            ],
+        };
+        return {
+            status,
+            mood,
+            message,
+            subStatus: isOnline ? undefined : 'offline',
+            screenData,
+            metrics: {
+                dns_avg_ms: round(dnsAvg),
+                http_avg_ms: round(httpAvg),
+                latency_avg_ms: round(latencyAvg),
+                dns_ok_count: dnsOk,
+                dns_fail_count: dnsFail,
+                http_ok_count: httpOk,
+                http_fail_count: httpFail,
+                is_online: isOnline ? 1 : 0,
+            },
+        };
+    }
+    buildOnlineMessage(dnsAvg, httpAvg, latencyAvg) {
+        return `Online | DNS: ${round(dnsAvg)}ms | HTTP: ${round(httpAvg)}ms | Latency: ${round(latencyAvg)}ms`;
+    }
+    buildOfflineMessage(dnsResults, httpResults) {
+        const problems = [];
+        if (dnsResults.every((r) => !r.ok)) {
+            problems.push('DNS resolution failed');
+        }
+        if (httpResults.every((r) => !r.ok)) {
+            problems.push('no HTTP connectivity');
+        }
+        return `OFFLINE: ${problems.join(', ') || 'all checks failed'}`;
+    }
+    /**
+     * Build config from CLI flags. Merges with any programmatic overrides.
+     */
+    static configFromFlags(flags) {
+        const config = {};
+        const dnsHostsRaw = stringFlag(flags, 'dns-hosts');
+        if (dnsHostsRaw) {
+            config.dnsHosts = dnsHostsRaw.split(',').map((s) => s.trim());
+        }
+        const httpUrlsRaw = stringFlag(flags, 'http-urls');
+        if (httpUrlsRaw) {
+            config.httpUrls = httpUrlsRaw.split(',').map((s) => s.trim());
+        }
+        const latencyHostsRaw = stringFlag(flags, 'latency-hosts');
+        if (latencyHostsRaw) {
+            config.latencyHosts = latencyHostsRaw.split(',').map((s) => {
+                const trimmed = s.trim();
+                const colonIndex = trimmed.lastIndexOf(':');
+                if (colonIndex !== -1) {
+                    const host = trimmed.slice(0, colonIndex);
+                    const port = Number(trimmed.slice(colonIndex + 1));
+                    if (!Number.isNaN(port))
+                        return { host, port };
+                }
+                return { host: trimmed, port: 80 };
+            });
+        }
+        const slowThreshold = numberFlag(flags, 'slow-threshold');
+        if (slowThreshold !== undefined)
+            config.slowThreshold = slowThreshold;
+        const pollInterval = numberFlag(flags, 'poll-interval');
+        if (pollInterval !== undefined)
+            config.pollInterval = pollInterval;
+        return config;
+    }
+}
+// ---------- Helpers ----------
+function avgTime(results) {
+    if (results.length === 0)
+        return 0;
+    const sum = results.reduce((acc, r) => acc + r.timeMs, 0);
+    return sum / results.length;
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+function statusToMood(status) {
+    switch (status) {
+        case 'healthy':
+            return 'happy';
+        case 'warning':
+            return 'concerned';
+        case 'critical':
+            return 'stressed';
+        default:
+            return 'idle';
+    }
+}
+/**
+ * Normalise latency hosts from either string[] (CLI) or LatencyHost[].
+ * String entries can be "host" or "host:port".
+ */
+function parseLatencyHosts(input) {
+    return input.map((item) => {
+        if (typeof item === 'object')
+            return item;
+        const colonIndex = item.lastIndexOf(':');
+        if (colonIndex !== -1) {
+            const host = item.slice(0, colonIndex);
+            const port = Number(item.slice(colonIndex + 1));
+            if (!Number.isNaN(port))
+                return { host, port };
+        }
+        return { host: item, port: 80 };
+    });
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,18 @@
+import type { ScreenData } from '../../core/types.js';
+export type LogLineLevel = 'error' | 'warning' | 'info';
+export interface RecentLine {
+    text: string;
+    level: LogLineLevel;
+}
+/** Classify a raw log line against the error/warning patterns. */
+export declare function classifyLine(line: string, errorRe: RegExp, warningRe: RegExp): LogLineLevel;
+/**
+ * Push a line into the bounded ring buffer: each entry is capped at `cap`
+ * characters and the buffer keeps only the last `max` entries.
+ */
+export declare function pushRecent(buffer: RecentLine[], line: string, level: LogLineLevel, max?: number, cap?: number): RecentLine[];
+/** Build a log-terminal screen payload from the ring buffer, colored per level. */
+export declare function buildLogScreen(buffer: RecentLine[]): ScreenData;
+/** True when enough time has elapsed since the last burst push to emit again. */
+export declare function shouldEmitBurst(lastEmit: number, now: number, windowMs?: number): boolean;
+//# sourceMappingURL=buffer.d.ts.map

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

@@ -0,0 +1,34 @@
+/** Classify a raw log line against the error/warning patterns. */
+export function classifyLine(line, errorRe, warningRe) {
+    if (errorRe.test(line))
+        return 'error';
+    if (warningRe.test(line))
+        return 'warning';
+    return 'info';
+}
+/**
+ * Push a line into the bounded ring buffer: each entry is capped at `cap`
+ * characters and the buffer keeps only the last `max` entries.
+ */
+export function pushRecent(buffer, line, level, max = 12, cap = 80) {
+    buffer.push({ text: line.slice(0, cap), level });
+    if (buffer.length > max)
+        buffer.splice(0, buffer.length - max);
+    return buffer;
+}
+/** Build a log-terminal screen payload from the ring buffer, colored per level. */
+export function buildLogScreen(buffer) {
+    return {
+        layout: 'log-terminal',
+        values: buffer.map((l) => ({
+            label: '',
+            value: l.text,
+            color: l.level === 'error' ? 'red' : l.level === 'warning' ? 'amber' : 'green',
+        })),
+    };
+}
+/** True when enough time has elapsed since the last burst push to emit again. */
+export function shouldEmitBurst(lastEmit, now, windowMs = 5000) {
+    return now - lastEmit >= windowMs;
+}
+//# sourceMappingURL=buffer.js.map

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

@@ -0,0 +1,9 @@
+export declare const DEFAULTS: {
+    reportInterval: number;
+    windowSeconds: number;
+    errorPattern: string;
+    warningPattern: string;
+    errorWarn: number;
+    errorCrit: number;
+};
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1,9 @@
+export const DEFAULTS = {
+    reportInterval: 15000, // 15 seconds
+    windowSeconds: 300, // 5 minutes
+    errorPattern: 'ERROR|FATAL',
+    warningPattern: 'WARN',
+    errorWarn: 5, // errors in window before warning status
+    errorCrit: 20, // errors in window before critical status
+};
+//# sourceMappingURL=defaults.js.map

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