@nocville/npc 0.2.2 → 0.2.3

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

@@ -1,46 +1,84 @@
-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 { existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { PollingNPC } from '../../core/polling-npc.js';
+import { evaluateThreshold, worstStatus, moodForStatus, thresholdProblem, } from '../../core/thresholds.js';
+import { NpcConfigError } from '../../core/errors.js';
 import { createTailer } from './tail.js';
-import { classifyLine, pushRecent, buildLogScreen, shouldEmitBurst } from './buffer.js';
+import { classifyLine, cleanLogLine, pushRecent, buildLogScreen, shouldEmitBurst, WindowCounter, } from './buffer.js';
 import { DEFAULTS } from './defaults.js';
-export class LogWatcherNPC extends BaseNPC {
+/** Lines shown on the log terminal, and their width. */
+const SCREEN_LINES = 12;
+const SCREEN_LINE_CHARS = 80;
+function compilePattern(flag, source) {
+    try {
+        return new RegExp(source);
+    }
+    catch (err) {
+        throw new NpcConfigError(`${flag}: invalid regular expression (${err instanceof Error ? err.message : String(err)})`);
+    }
+}
+/** "45s", "5min", "1.5h" */
+function formatWindow(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.round((seconds / 60) * 10) / 10}min`;
+    return `${Math.round((seconds / 3600) * 10) / 10}h`;
+}
+/**
+ * Tails log files and reports error bursts. A periodic report (every
+ * `reportInterval`) carries the error count over the sliding window and the
+ * last lines for the log terminal; a fresh error line also triggers an
+ * immediate report, debounced to one per 5s, so a burst shows up at once.
+ * Every report is one composed push, never a push per line.
+ */
+export class LogWatcherNPC extends PollingNPC {
     tailers = [];
-    timer = null;
-    entries = [];
+    counter;
     recentLines = [];
-    lastBurstPush = 0;
+    lastError = null;
+    /** The error line that triggered an immediate report, consumed by the next collect(). */
+    burstLine = null;
+    lastBurstAt = 0;
     errorRegex;
     warningRegex;
     windowMs;
-    errorWarn;
-    errorCrit;
-    reportInterval;
+    errorThreshold;
     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;
+        super({
+            ...config,
+            pollInterval: config.reportInterval ?? config.pollInterval ?? DEFAULTS.reportInterval,
+        });
+        this.files = [...new Set(config.files.map((f) => f.trim()).filter(Boolean))].map((f) => resolve(f));
+        if (this.files.length === 0) {
+            throw new NpcConfigError('log-watcher needs at least one file (--files)');
+        }
+        this.errorRegex = compilePattern('--error-pattern', config.errorPattern ?? DEFAULTS.errorPattern);
+        this.warningRegex = compilePattern('--warning-pattern', config.warningPattern ?? DEFAULTS.warningPattern);
+        const windowSeconds = config.windowSeconds ?? DEFAULTS.windowSeconds;
+        if (!(windowSeconds > 0))
+            throw new NpcConfigError('--window must be a positive number of seconds');
+        this.windowMs = windowSeconds * 1000;
+        this.counter = new WindowCounter(this.windowMs);
+        this.errorThreshold = {
+            warning: config.errorWarn ?? DEFAULTS.errorWarn,
+            critical: config.errorCrit ?? DEFAULTS.errorCrit,
+            direction: 'above',
+        };
+        const problem = thresholdProblem('--error-warn/--error-crit', this.errorThreshold);
+        if (problem)
+            throw new NpcConfigError(problem);
     }
     get name() {
         return 'log-watcher';
     }
     get defaultDisplayName() {
-        const first = this.files[0];
-        return first ? `Logs: ${basename(first)}` : 'Logs';
+        return `Logs: ${basename(this.files[0])}`;
     }
     get archetype() {
         return 'service';
     }
-    get heartbeatSeconds() {
-        return 30;
-    }
     get behavior() {
         return { idle: 'wander' };
     }
@@ -49,109 +87,77 @@ export class LogWatcherNPC extends BaseNPC {
             screenType: 'log-terminal',
             size: { w: 2, h: 2 },
             placement: 'adjacent-wall',
-            label: this.files[0] ? basename(this.files[0]) : 'log',
+            label: basename(this.files[0]),
         };
     }
     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);
+            if (existsSync(filePath)) {
+                this.logger.info(`Tailing ${filePath}`);
+            }
+            else {
+                this.logger.warn(`${filePath} does not exist yet; will tail it once it appears`);
+            }
+            this.tailers.push(createTailer(filePath, (line) => this.handleLine(line), {
+                onError: (err) => this.logger.warn(`Cannot read ${filePath}`, { error: err.message }),
+            }));
         }
-        // Report immediately, then on interval
-        await this.report();
-        this.timer = setInterval(() => {
-            void this.report();
-        }, this.reportInterval);
+        await super.onStart();
     }
     async onStop() {
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = null;
-        }
-        for (const tailer of this.tailers) {
+        for (const tailer of this.tailers)
             tailer.close();
-        }
         this.tailers = [];
+        await super.onStop();
     }
-    handleLine(line) {
-        const now = Date.now();
+    /** Visible for tests: feed one raw line as if a tailer had read it. */
+    handleLine(line, 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))
+        // The ring buffer holds ALL lines (matched ones flagged) for the log TV.
+        pushRecent(this.recentLines, cleanLogLine(line, SCREEN_LINE_CHARS), level, SCREEN_LINES);
+        if (level === 'info')
             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')
+        this.counter.add(level, now);
+        if (level !== 'error')
             return;
-        await this.pushReport();
+        const text = cleanLogLine(line);
+        this.lastError = { text, at: now };
+        if (shouldEmitBurst(this.lastBurstAt, now)) {
+            this.lastBurstAt = now;
+            this.burstLine = text;
+            this.collectNow();
+        }
     }
-    /**
-     * 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)
+    async collect() {
+        const now = Date.now();
+        const { errors, warnings } = this.counter.counts(now);
+        const window = formatWindow(this.windowMs / 1000);
+        const burst = this.burstLine;
+        this.burstLine = null;
+        let status = evaluateThreshold(errors, this.errorThreshold);
+        // A burst report drives the bubble with the error itself and floors at warning.
+        if (burst)
             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 = {
+        const fileCount = `${this.files.length} file${this.files.length !== 1 ? 's' : ''}`;
+        const message = burst ??
+            (errors > 0
+                ? `${errors} error${errors !== 1 ? 's' : ''} in last ${window} across ${fileCount}`
+                : `No errors in last ${window}`);
+        const lastErrorInWindow = this.lastError && now - this.lastError.at <= this.windowMs ? this.lastError.text : '';
+        return {
             status,
-            mood,
+            mood: moodForStatus(status),
             message,
-            subStatus,
+            subStatus: burst ? 'error' : undefined,
             screenData: buildLogScreen(this.recentLines),
             metrics: {
-                error_count: errorCount,
-                warning_count: warningCount,
-                window_seconds: windowSeconds,
+                error_count: errors,
+                warning_count: warnings,
+                window_seconds: this.windowMs / 1000,
                 files_watched: this.files.length,
-                last_error_message: lastError?.message ?? '',
+                last_error_message: lastErrorInWindow,
             },
         };
-        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

@@ -1,9 +1,29 @@
 export interface FileTailer {
     close(): void;
 }
+export interface TailerOptions {
+    /** How often to stat the file for growth/rotation (ms). */
+    pollMs?: number;
+    /** Longest line kept, in characters; the rest of a longer line is dropped. */
+    maxLineChars?: number;
+    /** Max bytes read per poll. */
+    maxReadBytes?: number;
+    /** When more than this many bytes are pending, skip ahead to the newest data. */
+    maxBacklogBytes?: number;
+    /** Called (once per distinct error) when the file can't be read. */
+    onError?: (err: Error) => 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).
+ * Follow a growing file like `tail -F`: emit each complete new line, starting
+ * from the end of the file as it is now (or from the start of a file created
+ * later).
+ *
+ * Polls with `stat` instead of `fs.watch`: watchers follow the inode, so they
+ * go deaf after logrotate's rename-and-recreate, and they throw for files that
+ * don't exist yet. Rotation (new inode) and truncation (size shrinks) restart
+ * from offset 0. Reads are bounded per poll, a partial last line is held until
+ * its newline arrives, over-long lines are cut, and a backlog beyond
+ * `maxBacklogBytes` (a runaway logger) is skipped so the watcher stays current.
  */
-export declare function createTailer(filePath: string, onLine: (line: string) => void): FileTailer;
+export declare function createTailer(filePath: string, onLine: (line: string) => void, options?: TailerOptions): FileTailer;
 //# sourceMappingURL=tail.d.ts.map

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

@@ -1,77 +1,124 @@
-import { watch, createReadStream, promises as fsp } from 'node:fs';
-import { createInterface } from 'node:readline';
+import { promises as fsp } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+const DEFAULTS = {
+    pollMs: 1000,
+    maxLineChars: 16 * 1024,
+    maxReadBytes: 1024 * 1024,
+    maxBacklogBytes: 8 * 1024 * 1024,
+};
+function isNotFound(err) {
+    return err?.code === 'ENOENT';
+}
 /**
- * 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).
+ * Follow a growing file like `tail -F`: emit each complete new line, starting
+ * from the end of the file as it is now (or from the start of a file created
+ * later).
+ *
+ * Polls with `stat` instead of `fs.watch`: watchers follow the inode, so they
+ * go deaf after logrotate's rename-and-recreate, and they throw for files that
+ * don't exist yet. Rotation (new inode) and truncation (size shrinks) restart
+ * from offset 0. Reads are bounded per poll, a partial last line is held until
+ * its newline arrives, over-long lines are cut, and a backlog beyond
+ * `maxBacklogBytes` (a runaway logger) is skipped so the watcher stays current.
  */
-export function createTailer(filePath, onLine) {
+export function createTailer(filePath, onLine, options = {}) {
+    const opts = { ...DEFAULTS, ...options };
     let offset = 0;
-    let reading = false;
-    let watcher = null;
+    let inode = null;
+    let partial = '';
+    let decoder = new StringDecoder('utf8');
+    let busy = false;
     let closed = false;
-    async function init() {
-        // Start at the end of the file so we only read new lines
+    /** False until the first successful stat (or ENOENT) fixes the starting offset. */
+    let started = false;
+    let lastError = '';
+    const reset = () => {
+        offset = 0;
+        partial = '';
+        decoder = new StringDecoder('utf8');
+    };
+    const reportError = (err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (error.message === lastError)
+            return;
+        lastError = error.message;
+        opts.onError?.(error);
+    };
+    const emitText = (text) => {
+        const pieces = (partial + text).split('\n');
+        partial = pieces.pop().slice(0, opts.maxLineChars);
+        for (const piece of pieces) {
+            if (closed)
+                return;
+            onLine(piece.replace(/\r$/, '').slice(0, opts.maxLineChars));
+        }
+    };
+    async function readNew(size) {
+        if (size - offset > opts.maxBacklogBytes) {
+            // Too far behind: jump to the newest data rather than lag forever.
+            offset = size - opts.maxReadBytes;
+            partial = '';
+            decoder = new StringDecoder('utf8');
+        }
+        const length = Math.min(size - offset, opts.maxReadBytes);
+        const handle = await fsp.open(filePath, 'r');
         try {
-            const stats = await fsp.stat(filePath);
-            offset = stats.size;
+            const buf = Buffer.alloc(length);
+            const { bytesRead } = await handle.read(buf, 0, length, offset);
+            offset += bytesRead;
+            emitText(decoder.write(buf.subarray(0, bytesRead)));
         }
-        catch {
-            // File may not exist yet; start at 0
-            offset = 0;
+        finally {
+            await handle.close();
         }
-        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)
+    async function poll() {
+        if (busy || closed)
             return;
-        reading = true;
+        busy = 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;
+            const st = await fsp.stat(filePath);
+            if (!started) {
+                // Start at the current end of the file so only new lines are reported.
+                started = true;
+                inode = st.ino;
+                offset = st.size;
+                lastError = '';
                 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;
+            if (inode !== null && st.ino !== inode)
+                reset(); // rotated: a new file took the name
+            inode = st.ino;
+            if (st.size < offset)
+                reset(); // truncated in place
+            if (st.size > offset)
+                await readNew(st.size);
+            lastError = '';
         }
-        catch {
-            // File may have been removed; ignore and wait for next change
+        catch (err) {
+            if (isNotFound(err)) {
+                started = true;
+                // Rotated away and not yet recreated (or never created): start the
+                // replacement from its first byte.
+                if (inode !== null)
+                    reportError(new Error(`${filePath} disappeared; waiting for it`));
+                inode = null;
+                reset();
+            }
+            else {
+                reportError(err);
+            }
         }
         finally {
-            reading = false;
+            busy = false;
         }
     }
-    void init();
+    const timer = setInterval(() => void poll(), opts.pollMs);
+    void poll();
     return {
         close() {
             closed = true;
-            if (watcher) {
-                watcher.close();
-                watcher = null;
-            }
+            clearInterval(timer);
         },
     };
 }

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

@@ -19,8 +19,8 @@ export declare class ProcessWatcherNPC extends PollingNPC {
     get name(): string;
     protected get defaultDisplayName(): string;
     get archetype(): Archetype;
-    get heartbeatSeconds(): number;
     get companion(): CompanionDecl;
     protected collect(): Promise<CollectedMetrics>;
+    private scanFailed;
 }
 //# sourceMappingURL=index.d.ts.map