@nocville/npc 0.2.2 → 0.3.0

package/dist/core/config.js

@@ -89,11 +89,27 @@ export function boolFlag(flags, key) {
         return false;
     return undefined;
 }
+/**
+ * A comma-separated list flag (`--processes=nginx,redis`): entries trimmed,
+ * empties dropped, duplicates removed. Undefined when the flag is absent or empty.
+ */
+export function listFlag(flags, key) {
+    const raw = stringFlag(flags, key);
+    if (raw === undefined)
+        return undefined;
+    const items = [
+        ...new Set(raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)),
+    ];
+    return items.length > 0 ? items : undefined;
+}
 export function numberFlag(flags, key) {
     const val = flags[key];
-    if (typeof val === 'string') {
+    if (typeof val === 'string' && val.trim() !== '') {
         const n = Number(val);
-        if (!Number.isNaN(n))
+        if (Number.isFinite(n))
             return n;
     }
     return undefined;

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A user-facing configuration problem (bad flag value, unsupported platform).
+ * The CLI prints only its message and exits 1 — no stack trace — so throw it
+ * for anything the user can fix by changing how they run the NPC.
+ */
+export declare class NpcConfigError extends Error {
+    constructor(message: string);
+}
+/** Throw an NpcConfigError on Windows, for NPCs that rely on POSIX tools or paths. */
+export declare function assertPosix(npcName: string, hint: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.js

@@ -0,0 +1,18 @@
+/**
+ * A user-facing configuration problem (bad flag value, unsupported platform).
+ * The CLI prints only its message and exits 1 — no stack trace — so throw it
+ * for anything the user can fix by changing how they run the NPC.
+ */
+export class NpcConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NpcConfigError';
+    }
+}
+/** Throw an NpcConfigError on Windows, for NPCs that rely on POSIX tools or paths. */
+export function assertPosix(npcName, hint) {
+    if (process.platform === 'win32') {
+        throw new NpcConfigError(`${npcName} is not supported on Windows. ${hint}`);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/http.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Small, bounded HTTP helpers for NPCs that read untrusted remote content
+ * (weather/geo APIs, GitHub, watched web pages). Every call has a timeout and
+ * every body read has a byte cap, so a slow or hostile server can neither hang
+ * a collection nor balloon memory.
+ */
+/** The `User-Agent` sent by every NPC request. */
+export declare const NPC_USER_AGENT = "nocville-npc";
+/** Default cap for a response body read into memory. */
+export declare const DEFAULT_MAX_BODY_BYTES: number;
+/** True for an absolute http(s) URL (anything else — file:, data:, javascript: — is refused). */
+export declare function isHttpUrl(value: string): boolean;
+/** A URL rendered for logs/screens: scheme, host and path only — never credentials or query. */
+export declare function displayUrl(value: string): string;
+/** The minimal response surface the helpers read (global fetch satisfies it). */
+export interface ReadableResponse {
+    headers?: {
+        get(name: string): string | null;
+    };
+    body?: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+/**
+ * Read a response body as UTF-8, keeping at most `maxBytes`. Streams when the
+ * body is available (cancelling the rest); otherwise falls back to `text()`
+ * after rejecting an oversized declared Content-Length. Returns the (possibly
+ * truncated) text and whether it was truncated.
+ */
+export declare function readTextCapped(res: ReadableResponse, maxBytes?: number): Promise<{
+    text: string;
+    truncated: boolean;
+}>;
+/** Discard a response body without reading it (frees the connection). */
+export declare function discardBody(res: {
+    body?: ReadableStream<Uint8Array> | null;
+}): Promise<void>;
+export interface FetchJsonOptions {
+    timeoutMs: number;
+    headers?: Record<string, string>;
+    maxBytes?: number;
+}
+/**
+ * GET a JSON document with a timeout and size cap. Returns null on any network
+ * error, non-2xx status, oversized body or malformed JSON — callers degrade
+ * gracefully rather than throw.
+ */
+export declare function fetchJson(url: string, opts: FetchJsonOptions): Promise<unknown>;
+/** Narrow an unknown JSON value to a plain object (arrays and null excluded). */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/** A finite number from an unknown JSON value, else null. */
+export declare function finiteNumber(value: unknown): number | null;
+//# sourceMappingURL=http.d.ts.map

package/dist/core/http.js

@@ -0,0 +1,111 @@
+/**
+ * Small, bounded HTTP helpers for NPCs that read untrusted remote content
+ * (weather/geo APIs, GitHub, watched web pages). Every call has a timeout and
+ * every body read has a byte cap, so a slow or hostile server can neither hang
+ * a collection nor balloon memory.
+ */
+/** The `User-Agent` sent by every NPC request. */
+export const NPC_USER_AGENT = 'nocville-npc';
+/** Default cap for a response body read into memory. */
+export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+/** True for an absolute http(s) URL (anything else — file:, data:, javascript: — is refused). */
+export function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/** A URL rendered for logs/screens: scheme, host and path only — never credentials or query. */
+export function displayUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.protocol}//${url.host}${url.pathname === '/' ? '' : url.pathname}`;
+    }
+    catch {
+        return '(invalid url)';
+    }
+}
+/**
+ * Read a response body as UTF-8, keeping at most `maxBytes`. Streams when the
+ * body is available (cancelling the rest); otherwise falls back to `text()`
+ * after rejecting an oversized declared Content-Length. Returns the (possibly
+ * truncated) text and whether it was truncated.
+ */
+export async function readTextCapped(res, maxBytes = DEFAULT_MAX_BODY_BYTES) {
+    const reader = res.body?.getReader();
+    if (!reader) {
+        const declared = Number(res.headers?.get('content-length') ?? NaN);
+        if (Number.isFinite(declared) && declared > maxBytes)
+            return { text: '', truncated: true };
+        const text = await res.text();
+        return text.length > maxBytes
+            ? { text: text.slice(0, maxBytes), truncated: true }
+            : { text, truncated: false };
+    }
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (total + value.byteLength > maxBytes) {
+                chunks.push(value.subarray(0, maxBytes - total));
+                total = maxBytes;
+                truncated = true;
+                break;
+            }
+            chunks.push(value);
+            total += value.byteLength;
+        }
+    }
+    finally {
+        if (truncated)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+    return { text: new TextDecoder().decode(Buffer.concat(chunks)), truncated };
+}
+/** Discard a response body without reading it (frees the connection). */
+export async function discardBody(res) {
+    await res.body?.cancel().catch(() => undefined);
+}
+/**
+ * GET a JSON document with a timeout and size cap. Returns null on any network
+ * error, non-2xx status, oversized body or malformed JSON — callers degrade
+ * gracefully rather than throw.
+ */
+export async function fetchJson(url, opts) {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(opts.timeoutMs),
+            headers: { 'User-Agent': NPC_USER_AGENT, Accept: 'application/json', ...opts.headers },
+        });
+        if (!res.ok) {
+            await discardBody(res);
+            return null;
+        }
+        const { text, truncated } = await readTextCapped(res, opts.maxBytes ?? 256 * 1024);
+        if (truncated)
+            return null;
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Narrow an unknown JSON value to a plain object (arrays and null excluded). */
+export function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** A finite number from an unknown JSON value, else null. */
+export function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+//# sourceMappingURL=http.js.map

package/dist/core/pixel-art.d.ts

@@ -0,0 +1,38 @@
+import type { ScreenData } from '@nocville/node';
+export interface PixelArtFrames {
+    width: number;
+    height: number;
+    /** RGBA bytes per frame (width × height × 4). */
+    frames: Array<Uint8Array | Uint8ClampedArray>;
+    /** Animation speed when there is more than one frame (1–12, default 4). */
+    fps?: number;
+}
+/** Encode RGBA frames as `pixel-image` screen data. Throws with a fix-it message. */
+export declare function encodePixelArt(art: PixelArtFrames): ScreenData;
+/**
+ * Load a PNG (path or bytes) as pixel-device screen data. For animation, stack frames
+ * top to bottom in one PNG and pass `frameHeight`.
+ */
+export declare function pixelArtFromPng(png: string | Buffer, opts?: {
+    frameHeight?: number;
+    fps?: number;
+}): ScreenData;
+/**
+ * Companion declaration for a pixel device: `size` in tiles (art is 32px per tile).
+ * Freestanding by default so it sits on the floor next to the NPC's home.
+ */
+export declare function pixelDevice(opts: {
+    w: number;
+    h: number;
+    label?: string;
+    placement?: 'freestanding' | 'adjacent-wall' | 'on-desk';
+}): {
+    screenType: 'pixel-device';
+    size: {
+        w: number;
+        h: number;
+    };
+    placement: 'freestanding' | 'adjacent-wall' | 'on-desk';
+    label?: string;
+};
+//# sourceMappingURL=pixel-art.d.ts.map

package/dist/core/pixel-art.js

@@ -0,0 +1,105 @@
+import { readFileSync } from 'node:fs';
+import { PNG } from 'pngjs';
+/**
+ * Helpers for custom pixel-art companions (`screenType: 'pixel-device'`): your NPC's own
+ * device, sign or machine, drawn frameless beside it in the office.
+ *
+ * Art is 32 pixels per tile (a 2×3-tile device is 64×96, like the office furniture) and is
+ * sent as `pixel-image` screen data: a palette of up to 255 colours plus one byte per pixel.
+ * Fully transparent pixels (alpha < 128) become see-through, and several frames stacked top
+ * to bottom animate at `fps`. Push a new image whenever its state changes (e.g. an LED turns
+ * red); the server rate-limits pushes, so animate with frames rather than many pushes.
+ */
+/** Largest single screen-data value the API accepts (base64 pixels). */
+const MAX_VALUE = 220_000;
+const MAX_COLORS = 255;
+const MAX_FRAMES = 16;
+/** Encode RGBA frames as `pixel-image` screen data. Throws with a fix-it message. */
+export function encodePixelArt(art) {
+    const { width, height, frames } = art;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1)
+        throw new Error('Pixel art needs a positive whole-number width and height.');
+    if (width > 192 || height > 192)
+        throw new Error(`Pixel art is ${width}×${height}; keep it within 192×192 (6×6 tiles).`);
+    if (frames.length < 1 || frames.length > MAX_FRAMES)
+        throw new Error(`Pixel art needs 1–${MAX_FRAMES} frames (got ${frames.length}).`);
+    const size = width * height;
+    for (const frame of frames)
+        if (frame.length !== size * 4)
+            throw new Error(`Each frame must be ${width}×${height} RGBA (${size * 4} bytes).`);
+    // Index 0 is reserved for transparency when any pixel is see-through.
+    const transparent = frames.some((f) => {
+        for (let i = 3; i < f.length; i += 4)
+            if (f[i] < 128)
+                return true;
+        return false;
+    });
+    const colors = new Map();
+    const palette = transparent ? [0, 0, 0] : [];
+    const pixels = Buffer.alloc(size * frames.length);
+    frames.forEach((frame, f) => {
+        for (let i = 0; i < size; i++) {
+            const r = frame[i * 4], g = frame[i * 4 + 1], b = frame[i * 4 + 2];
+            if (transparent && frame[i * 4 + 3] < 128) {
+                pixels[f * size + i] = 0;
+                continue;
+            }
+            const key = (r << 16) | (g << 8) | b;
+            let index = colors.get(key);
+            if (index === undefined) {
+                index = palette.length / 3;
+                if (index > MAX_COLORS)
+                    throw new Error(`Pixel art uses more than ${MAX_COLORS} colours; reduce the palette (pixel art usually needs 8–32).`);
+                colors.set(key, index);
+                palette.push(r, g, b);
+            }
+            pixels[f * size + i] = index;
+        }
+    });
+    const tokens = [`idx8`, `${width}x${height}`, `p${palette.length / 3}`];
+    if (transparent)
+        tokens.push('t0');
+    if (frames.length > 1) {
+        const fps = Math.min(12, Math.max(1, Math.round(art.fps ?? 4)));
+        tokens.push(`f${frames.length}`, `fps${fps}`);
+    }
+    const encoded = pixels.toString('base64');
+    if (encoded.length > MAX_VALUE)
+        throw new Error('Pixel art is too large to send; use fewer frames or a smaller size.');
+    return {
+        layout: 'pixel-image',
+        values: [
+            { label: 'fmt', value: tokens.join(';') },
+            { label: 'palette', value: Buffer.from(palette).toString('base64') },
+            { label: 'pixels', value: encoded },
+        ],
+    };
+}
+/**
+ * Load a PNG (path or bytes) as pixel-device screen data. For animation, stack frames
+ * top to bottom in one PNG and pass `frameHeight`.
+ */
+export function pixelArtFromPng(png, opts = {}) {
+    const image = PNG.sync.read(typeof png === 'string' ? readFileSync(png) : png);
+    const frameHeight = opts.frameHeight ?? image.height;
+    if (frameHeight < 1 || image.height % frameHeight !== 0)
+        throw new Error(`PNG height ${image.height} is not a whole number of ${frameHeight}px frames.`);
+    const frameBytes = image.width * frameHeight * 4;
+    const frames = [];
+    for (let offset = 0; offset < image.data.length; offset += frameBytes)
+        frames.push(image.data.subarray(offset, offset + frameBytes));
+    return encodePixelArt({ width: image.width, height: frameHeight, frames, fps: opts.fps });
+}
+/**
+ * Companion declaration for a pixel device: `size` in tiles (art is 32px per tile).
+ * Freestanding by default so it sits on the floor next to the NPC's home.
+ */
+export function pixelDevice(opts) {
+    return {
+        screenType: 'pixel-device',
+        size: { w: opts.w, h: opts.h },
+        placement: opts.placement ?? 'freestanding',
+        ...(opts.label ? { label: opts.label } : {}),
+    };
+}
+//# sourceMappingURL=pixel-art.js.map

package/dist/core/polling-npc.d.ts

@@ -3,9 +3,21 @@ import type { NpcConfig, CollectedMetrics } from './types.js';
 export interface PollingNpcConfig extends NpcConfig {
     pollInterval?: number;
 }
+/**
+ * Lower bound for any poll interval, so a typo can't exhaust the API's
+ * per-service rate limit (60 pushes/min) or hammer the watched source.
+ */
+export declare const MIN_POLL_INTERVAL_MS = 5000;
 export declare abstract class PollingNPC extends BaseNPC {
     private timer;
-    private collecting;
+    private keepaliveTimer;
+    /** The running collection + push, if any (awaited by `onStop`). */
+    private inflight;
+    /** A `collectNow()` arrived while a collection was in flight: run once more after it. */
+    private rerunRequested;
+    /** The last successfully pushed cycle, replayed (without its screen) by the keepalive. */
+    private lastPushed;
+    private lastPushAt;
     protected pollInterval: number;
     constructor(config: PollingNpcConfig);
     /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
@@ -13,6 +25,15 @@ export declare abstract class PollingNPC extends BaseNPC {
     protected abstract collect(): Promise<CollectedMetrics>;
     protected onStart(): Promise<void>;
     protected onStop(): Promise<void>;
+    /**
+     * Collect and push now instead of waiting for the next tick — for NPCs that
+     * also react to events (e.g. a fresh error line). Coalesces: if a collection
+     * is already running, exactly one more runs after it.
+     */
+    protected collectNow(): void;
     private runCollection;
+    private collectAndPush;
+    /** Replay the last cycle (minus its screen, which the server keeps) if nothing was pushed recently. */
+    private keepalive;
 }
 //# sourceMappingURL=polling-npc.d.ts.map

package/dist/core/polling-npc.js

@@ -1,14 +1,31 @@
 import { BaseNPC } from './base-npc.js';
+/**
+ * Lower bound for any poll interval, so a typo can't exhaust the API's
+ * per-service rate limit (60 pushes/min) or hammer the watched source.
+ */
+export const MIN_POLL_INTERVAL_MS = 5000;
+/** How long `stop()` waits for an in-flight collection before pushing offline anyway. */
+const STOP_DRAIN_TIMEOUT_MS = 10_000;
 function clamp(n, min, max) {
     return Math.min(max, Math.max(min, n));
 }
 export class PollingNPC extends BaseNPC {
     timer = null;
-    collecting = false;
+    keepaliveTimer = null;
+    /** The running collection + push, if any (awaited by `onStop`). */
+    inflight = null;
+    /** A `collectNow()` arrived while a collection was in flight: run once more after it. */
+    rerunRequested = false;
+    /** The last successfully pushed cycle, replayed (without its screen) by the keepalive. */
+    lastPushed = null;
+    lastPushAt = 0;
     pollInterval;
     constructor(config) {
         super(config);
-        this.pollInterval = config.pollInterval ?? 15000;
+        const requested = config.pollInterval ?? 15000;
+        this.pollInterval = Number.isFinite(requested)
+            ? Math.max(MIN_POLL_INTERVAL_MS, requested)
+            : 15000;
     }
     /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
     get heartbeatSeconds() {
@@ -17,14 +34,22 @@ export class PollingNPC extends BaseNPC {
     async onStart() {
         // Collect immediately on start
         await this.runCollection();
+        // Stopped while the first collection ran: don't arm timers nobody will clear.
+        if (this.state !== 'running')
+            return;
         // Then on interval
         this.timer = setInterval(() => {
             void this.runCollection();
         }, this.pollInterval);
-        // For slow pollers, keep the NPC alive with a lightweight heartbeat between
-        // collections so it never falsely goes stale mid-interval.
-        if (this.pollInterval > 60_000) {
-            this.client.startHeartbeat(30_000);
+        // Only very slow pollers (> heartbeatSeconds, i.e. > 30 min given the clamp)
+        // could go stale between collections. Keep them alive by replaying the
+        // last cycle. The SDK's own heartbeat is not used: it omits `map`, `name`
+        // and `alertConfig`, so it would spawn a twin on the team's default map.
+        const heartbeatMs = this.heartbeatSeconds * 1000;
+        if (this.pollInterval > heartbeatMs) {
+            this.keepaliveTimer = setInterval(() => {
+                void this.keepalive(heartbeatMs);
+            }, heartbeatMs);
         }
     }
     async onStop() {
@@ -32,29 +57,89 @@ export class PollingNPC extends BaseNPC {
             clearInterval(this.timer);
             this.timer = null;
         }
-        this.client.stopHeartbeat();
+        if (this.keepaliveTimer) {
+            clearInterval(this.keepaliveTimer);
+            this.keepaliveTimer = null;
+        }
+        this.rerunRequested = false;
+        // Let an in-flight push land before the offline push, so it can't arrive
+        // afterwards and respawn the NPC. Bounded: a hung collector never blocks exit.
+        if (this.inflight) {
+            let timeout;
+            await Promise.race([
+                this.inflight,
+                new Promise((resolve) => {
+                    timeout = setTimeout(resolve, STOP_DRAIN_TIMEOUT_MS);
+                }),
+            ]);
+            clearTimeout(timeout);
+        }
     }
-    async runCollection() {
+    /**
+     * Collect and push now instead of waiting for the next tick — for NPCs that
+     * also react to events (e.g. a fresh error line). Coalesces: if a collection
+     * is already running, exactly one more runs after it.
+     */
+    collectNow() {
         if (this.state !== 'running')
             return;
+        if (this.inflight) {
+            this.rerunRequested = true;
+            return;
+        }
+        void this.runCollection();
+    }
+    runCollection() {
+        if (this.state !== 'running')
+            return Promise.resolve();
         // Overlap guard: if a slow collector is still running, skip this tick rather
         // than stacking collections (load-bearing for screenshot/render collectors).
-        if (this.collecting) {
+        if (this.inflight) {
             this.logger.debug('Previous collection still in flight, skipping this tick');
-            return;
+            return this.inflight;
         }
-        this.collecting = true;
+        const run = this.collectAndPush().finally(() => {
+            this.inflight = null;
+            if (this.rerunRequested && this.state === 'running') {
+                this.rerunRequested = false;
+                void this.runCollection();
+            }
+        });
+        this.inflight = run;
+        return run;
+    }
+    async collectAndPush() {
         try {
             const metrics = await this.collect();
+            // Stopped mid-collection: never push after (or race) the offline push.
+            if (this.state !== 'running')
+                return;
             await this.pushMetrics(metrics);
+            this.lastPushed = metrics;
+            this.lastPushAt = Date.now();
         }
         catch (err) {
+            if (this.state !== 'running')
+                return; // teardown aborted the collector
             this.logger.error('Collection failed', {
                 error: err instanceof Error ? err.message : String(err),
             });
         }
-        finally {
-            this.collecting = false;
+    }
+    /** Replay the last cycle (minus its screen, which the server keeps) if nothing was pushed recently. */
+    async keepalive(heartbeatMs) {
+        if (this.state !== 'running' || this.inflight || !this.lastPushed)
+            return;
+        if (Date.now() - this.lastPushAt < heartbeatMs / 2)
+            return;
+        try {
+            await this.pushMetrics({ ...this.lastPushed, screenData: undefined });
+            this.lastPushAt = Date.now();
+        }
+        catch (err) {
+            this.logger.debug('Keepalive push failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
         }
     }
 }

package/dist/core/text.d.ts

@@ -3,4 +3,10 @@
  * Used to keep messages and screen lines within API limits.
  */
 export declare function truncate(s: string, max?: number): string;
+/**
+ * Make untrusted remote text (commit messages, page titles, log lines) safe to
+ * display: drop control and bidi-override characters, collapse whitespace
+ * (including newlines and tabs) to single spaces, trim, and truncate.
+ */
+export declare function sanitizeText(s: string, max?: number): string;
 //# sourceMappingURL=text.d.ts.map

package/dist/core/text.js

@@ -9,4 +9,16 @@ export function truncate(s, max = 200) {
         return s.slice(0, Math.max(0, max));
     return s.slice(0, max - 1) + '…';
 }
+// C0/C1 controls (incl. ESC, so no terminal escapes) plus the bidi overrides,
+// isolates and marks that can visually reorder text on a banner.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_CHARS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F؜‎‏‪-‮⁦-⁩]/g;
+/**
+ * Make untrusted remote text (commit messages, page titles, log lines) safe to
+ * display: drop control and bidi-override characters, collapse whitespace
+ * (including newlines and tabs) to single spaces, trim, and truncate.
+ */
+export function sanitizeText(s, max = 200) {
+    return truncate(s.replace(UNSAFE_CHARS, '').replace(/\s+/g, ' ').trim(), max);
+}
 //# sourceMappingURL=text.js.map

package/dist/core/thresholds.d.ts

@@ -1,4 +1,4 @@
-import type { Status, ThresholdConfig } from './types.js';
+import type { Mood, Status, ThresholdConfig } from './types.js';
 /**
  * Evaluate a numeric value against thresholds to determine status.
  */
@@ -7,4 +7,12 @@ export declare function evaluateThreshold(value: number, config: ThresholdConfig
  * Returns the worst (most severe) status from an array.
  */
 export declare function worstStatus(statuses: Status[]): Status;
+/** The NPC mood that matches a status (drives the NPC's demeanour and emotes). */
+export declare function moodForStatus(status: Status): Mood;
+/**
+ * Validate a warning/critical pair from user flags: both finite, and critical
+ * at least as severe as warning for the threshold's direction. Returns an error
+ * message, or null when the pair is usable.
+ */
+export declare function thresholdProblem(label: string, t: ThresholdConfig): string | null;
 //# sourceMappingURL=thresholds.d.ts.map

package/dist/core/thresholds.js

@@ -41,4 +41,31 @@ export function worstStatus(statuses) {
     }
     return worst;
 }
+/** The NPC mood that matches a status (drives the NPC's demeanour and emotes). */
+export function moodForStatus(status) {
+    switch (status) {
+        case 'healthy':
+            return 'happy';
+        case 'warning':
+            return 'concerned';
+        case 'critical':
+            return 'stressed';
+        default:
+            return 'idle';
+    }
+}
+/**
+ * Validate a warning/critical pair from user flags: both finite, and critical
+ * at least as severe as warning for the threshold's direction. Returns an error
+ * message, or null when the pair is usable.
+ */
+export function thresholdProblem(label, t) {
+    if (!Number.isFinite(t.warning) || !Number.isFinite(t.critical)) {
+        return `${label}: thresholds must be numbers`;
+    }
+    const inverted = (t.direction ?? 'above') === 'above' ? t.critical < t.warning : t.critical > t.warning;
+    return inverted
+        ? `${label}: critical (${t.critical}) must be at least as severe as warning (${t.warning})`
+        : null;
+}
 //# sourceMappingURL=thresholds.js.map

package/dist/core/types.d.ts

@@ -14,6 +14,11 @@ export interface NpcConfig {
     map?: string;
     /** Friendly display name for the NPC banner. Overrides the per-NPC default. */
     name?: string;
+    /** Optional local observer for publishing health; never included in status payloads. */
+    onPushResult?: (result: {
+        success: boolean;
+        error?: string;
+    }) => void;
 }
 export interface CollectedMetrics {
     status: Status;