@nocville/npc 0.0.0-stage → 0.2.0

package/dist/cjs/core/base-npc.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseNPC = void 0;
+const node_1 = require("@nocville/node");
+const logger_js_1 = require("./logger.js");
+const text_js_1 = require("./text.js");
+class BaseNPC {
+    client;
+    logger;
+    config;
+    state = 'stopped';
+    shutdownHandlers = [];
+    authErrorLogged = false;
+    constructor(config) {
+        this.config = config;
+        // Logger prefix is set to a generic name; subclasses override via `name` getter
+        // We can't access `this.name` here since it's abstract, so use a placeholder
+        this.logger = new logger_js_1.Logger('npc', config.debug);
+        this.client = new node_1.NocvilleClient({
+            apiUrl: config.apiUrl,
+            apiKey: config.apiKey,
+            serviceId: config.serviceId,
+            debug: config.debug,
+            retries: 1,
+            timeout: 5000,
+        });
+    }
+    /**
+     * Friendly display name for the NPC banner, sent on every push. A `--name`
+     * flag / NOCVILLE_NAME env (via `config.name`) always wins; otherwise the
+     * per-NPC `defaultDisplayName`. null lets the server fall back to serviceId.
+     */
+    get displayName() {
+        return this.config.name ?? this.defaultDisplayName;
+    }
+    /** Per-NPC default banner name. Overridden by each NPC; null means none. */
+    get defaultDisplayName() {
+        return null;
+    }
+    /** The banner name to send, clamped to the API's 32-char limit, or undefined. */
+    pushName() {
+        const name = this.displayName;
+        return name ? (0, text_js_1.truncate)(name, 32) : undefined;
+    }
+    /** NPC archetype — steers movement speed and default behavior. Override per NPC. */
+    get archetype() {
+        return 'service';
+    }
+    /** Base behavior hints sent on every push (merged with per-cycle overrides). */
+    get behavior() {
+        return {};
+    }
+    /** Companion pixel-art object to spawn alongside this NPC, or null for none. */
+    get companion() {
+        return null;
+    }
+    /** Heartbeat interval in seconds — the server marks the NPC unknown at 2x this. */
+    get heartbeatSeconds() {
+        return 120;
+    }
+    async start() {
+        if (this.state === 'running') {
+            this.logger.warn('NPC already running');
+            return;
+        }
+        this.state = 'running';
+        // Update logger prefix now that `name` is available
+        this.logger = new logger_js_1.Logger(this.name, this.config.debug);
+        this.logger.info(`Starting ${this.name}`);
+        this.attachSignalHandlers();
+        await this.onStart();
+    }
+    async stop() {
+        if (this.state !== 'running')
+            return;
+        this.state = 'stopping';
+        this.logger.info(`Stopping ${this.name}`);
+        try {
+            await this.onStop();
+        }
+        catch (err) {
+            this.logger.error('Error during stop', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        // Announce clean shutdown so the server despawns the NPC promptly rather
+        // than waiting out the staleness window.
+        try {
+            await this.client.pushStatus({
+                status: 'unknown',
+                mood: 'idle',
+                name: this.pushName(),
+                message: 'Going offline',
+                subStatus: 'offline',
+                offline: true,
+                map: this.config.map,
+            });
+        }
+        catch {
+            // Best effort
+        }
+        this.detachSignalHandlers();
+        this.state = 'stopped';
+        this.logger.info(`${this.name} stopped`);
+    }
+    async pushMetrics(metrics) {
+        this.logger.debug('Pushing metrics', {
+            status: metrics.status,
+            message: metrics.message,
+        });
+        const behavior = { ...this.behavior, ...metrics.behavior };
+        const result = await this.client.pushStatus({
+            status: metrics.status,
+            mood: metrics.mood,
+            name: this.pushName(),
+            message: metrics.message ? (0, text_js_1.truncate)(metrics.message, 500) : undefined,
+            metrics: metrics.metrics,
+            archetype: this.archetype,
+            subStatus: metrics.subStatus,
+            screenData: metrics.screenData,
+            behavior: Object.keys(behavior).length > 0 ? behavior : undefined,
+            companion: this.companion ?? undefined,
+            alertConfig: { heartbeatInterval: this.heartbeatSeconds },
+            map: this.config.map,
+        });
+        if (!result.success) {
+            this.reportPushFailure(result.error);
+        }
+    }
+    /** Log a push failure. A 401 gets a single actionable error; others warn each time. */
+    reportPushFailure(error) {
+        if (error && /\b401\b/.test(error)) {
+            if (!this.authErrorLogged) {
+                this.authErrorLogged = true;
+                this.logger.error('API key rejected (HTTP 401) — check NOCVILLE_API_KEY / team settings');
+            }
+            return;
+        }
+        this.logger.warn('Failed to push metrics', { error });
+    }
+    attachSignalHandlers() {
+        const handler = () => {
+            void this.stop().then(() => process.exit(0));
+        };
+        process.on('SIGINT', handler);
+        process.on('SIGTERM', handler);
+        this.shutdownHandlers.push(() => {
+            process.removeListener('SIGINT', handler);
+            process.removeListener('SIGTERM', handler);
+        });
+    }
+    detachSignalHandlers() {
+        for (const cleanup of this.shutdownHandlers) {
+            cleanup();
+        }
+        this.shutdownHandlers = [];
+    }
+}
+exports.BaseNPC = BaseNPC;
+//# sourceMappingURL=base-npc.js.map

package/dist/cjs/core/config.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.resolveConfig = resolveConfig;
+exports.stringFlag = stringFlag;
+exports.boolFlag = boolFlag;
+exports.numberFlag = numberFlag;
+const user_config_js_1 = require("./user-config.js");
+/**
+ * Simple hand-rolled CLI arg parser.
+ * Supports: --key=value, --key value, --flag (boolean)
+ */
+function parseArgs(argv) {
+    const args = argv.slice(2); // skip node and script path
+    const flags = {};
+    let command;
+    let subcommand;
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const eqIndex = arg.indexOf('=');
+            if (eqIndex !== -1) {
+                const key = arg.slice(2, eqIndex);
+                const value = arg.slice(eqIndex + 1);
+                flags[key] = value;
+            }
+            else {
+                const key = arg.slice(2);
+                const next = args[i + 1];
+                if (next && !next.startsWith('--')) {
+                    flags[key] = next;
+                    i++;
+                }
+                else {
+                    flags[key] = true;
+                }
+            }
+        }
+        else if (!command) {
+            command = arg;
+        }
+        else if (!subcommand) {
+            subcommand = arg;
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { command, subcommand, args: rest, flags };
+}
+/**
+ * Resolves NPC config from: constructor options > CLI args > env vars >
+ * the saved user config (`nocville-npc init`, ~/.config/nocville/config.json).
+ */
+function resolveConfig(flags, overrides) {
+    const saved = (0, user_config_js_1.loadUserConfig)();
+    const apiUrl = overrides?.apiUrl ||
+        stringFlag(flags, 'api-url') ||
+        process.env['NOCVILLE_API_URL'] ||
+        saved.apiUrl ||
+        'https://nocville.com';
+    const apiKey = overrides?.apiKey ||
+        stringFlag(flags, 'api-key') ||
+        process.env['NOCVILLE_API_KEY'] ||
+        saved.apiKey ||
+        '';
+    const serviceId = overrides?.serviceId ||
+        stringFlag(flags, 'service-id') ||
+        process.env['NOCVILLE_SERVICE_ID'] ||
+        '';
+    const debug = overrides?.debug ??
+        boolFlag(flags, 'debug') ??
+        (process.env['NOCVILLE_DEBUG'] === '1' || false);
+    const map = overrides?.map ||
+        stringFlag(flags, 'map') ||
+        process.env['NOCVILLE_MAP'] ||
+        saved.map ||
+        undefined;
+    const name = overrides?.name || stringFlag(flags, 'name') || process.env['NOCVILLE_NAME'] || undefined;
+    return { apiUrl, apiKey, serviceId, debug, map, name };
+}
+function stringFlag(flags, key) {
+    const val = flags[key];
+    if (typeof val === 'string')
+        return val;
+    return undefined;
+}
+function boolFlag(flags, key) {
+    const val = flags[key];
+    if (typeof val === 'boolean')
+        return val;
+    if (val === 'true')
+        return true;
+    if (val === 'false')
+        return false;
+    return undefined;
+}
+function numberFlag(flags, key) {
+    const val = flags[key];
+    if (typeof val === 'string') {
+        const n = Number(val);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    return undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/cjs/core/event-npc.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventNPC = void 0;
+const base_npc_js_1 = require("./base-npc.js");
+class EventNPC extends base_npc_js_1.BaseNPC {
+    async onStart() {
+        await this.setupEventSource();
+    }
+    async onStop() {
+        await this.teardownEventSource();
+    }
+}
+exports.EventNPC = EventNPC;
+//# sourceMappingURL=event-npc.js.map

package/dist/cjs/core/logger.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const types_js_1 = require("./types.js");
+class Logger {
+    level;
+    prefix;
+    constructor(prefix, debug = false) {
+        this.prefix = prefix;
+        this.level = debug ? types_js_1.LOG_LEVELS.debug.value : types_js_1.LOG_LEVELS.info.value;
+    }
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    error(message, data) {
+        this.log('error', message, data);
+    }
+    log(level, message, data) {
+        const levelInfo = types_js_1.LOG_LEVELS[level];
+        if (levelInfo.value < this.level)
+            return;
+        const timestamp = new Date().toISOString();
+        const parts = [`[${timestamp}]`, `[${levelInfo.name}]`, `[${this.prefix}]`, message];
+        if (data && Object.keys(data).length > 0) {
+            parts.push(JSON.stringify(data));
+        }
+        const output = parts.join(' ');
+        // stdout belongs to hook protocols; diagnostics must never corrupt their JSON.
+        console.error(output);
+    }
+}
+exports.Logger = Logger;
+//# sourceMappingURL=logger.js.map

package/dist/cjs/core/polling-npc.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PollingNPC = void 0;
+const base_npc_js_1 = require("./base-npc.js");
+function clamp(n, min, max) {
+    return Math.min(max, Math.max(min, n));
+}
+class PollingNPC extends base_npc_js_1.BaseNPC {
+    timer = null;
+    collecting = false;
+    pollInterval;
+    constructor(config) {
+        super(config);
+        this.pollInterval = config.pollInterval ?? 15000;
+    }
+    /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
+    get heartbeatSeconds() {
+        return clamp(Math.ceil((this.pollInterval * 2) / 1000), 30, 3600);
+    }
+    async onStart() {
+        // Collect immediately on start
+        await this.runCollection();
+        // 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);
+        }
+    }
+    async onStop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.client.stopHeartbeat();
+    }
+    async runCollection() {
+        if (this.state !== 'running')
+            return;
+        // 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) {
+            this.logger.debug('Previous collection still in flight, skipping this tick');
+            return;
+        }
+        this.collecting = true;
+        try {
+            const metrics = await this.collect();
+            await this.pushMetrics(metrics);
+        }
+        catch (err) {
+            this.logger.error('Collection failed', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        finally {
+            this.collecting = false;
+        }
+    }
+}
+exports.PollingNPC = PollingNPC;
+//# sourceMappingURL=polling-npc.js.map

package/dist/cjs/core/screen.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusColor = statusColor;
+exports.pushHistory = pushHistory;
+/** Map a status to the color the client renderer uses for it. */
+function statusColor(status) {
+    switch (status) {
+        case 'healthy':
+            return 'green';
+        case 'warning':
+            return 'amber';
+        case 'critical':
+            return 'red';
+        default:
+            return 'gray';
+    }
+}
+/**
+ * Push a numeric sample into a bounded rolling history (oldest dropped past `max`).
+ * Mutates and returns the array. The API caps sparklines at 60 samples.
+ */
+function pushHistory(history, value, max = 60) {
+    history.push(value);
+    if (history.length > max)
+        history.splice(0, history.length - max);
+    return history;
+}
+//# sourceMappingURL=screen.js.map

package/dist/cjs/core/text.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncate = truncate;
+/**
+ * Truncate a string to at most `max` characters, appending an ellipsis when cut.
+ * Used to keep messages and screen lines within API limits.
+ */
+function truncate(s, max = 200) {
+    if (s.length <= max)
+        return s;
+    if (max <= 1)
+        return s.slice(0, Math.max(0, max));
+    return s.slice(0, max - 1) + '…';
+}
+//# sourceMappingURL=text.js.map

package/dist/cjs/core/thresholds.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateThreshold = evaluateThreshold;
+exports.worstStatus = worstStatus;
+/**
+ * Evaluate a numeric value against thresholds to determine status.
+ */
+function evaluateThreshold(value, config) {
+    const direction = config.direction ?? 'above';
+    if (direction === 'above') {
+        if (value >= config.critical)
+            return 'critical';
+        if (value >= config.warning)
+            return 'warning';
+        return 'healthy';
+    }
+    else {
+        if (value <= config.critical)
+            return 'critical';
+        if (value <= config.warning)
+            return 'warning';
+        return 'healthy';
+    }
+}
+const STATUS_SEVERITY = {
+    healthy: 0,
+    unknown: 1,
+    warning: 2,
+    critical: 3,
+};
+/**
+ * Returns the worst (most severe) status from an array.
+ */
+function worstStatus(statuses) {
+    if (statuses.length === 0)
+        return 'unknown';
+    let worst = 'healthy';
+    let worstSeverity = 0;
+    for (const s of statuses) {
+        const severity = STATUS_SEVERITY[s];
+        if (severity > worstSeverity) {
+            worst = s;
+            worstSeverity = severity;
+        }
+    }
+    return worst;
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/cjs/core/types.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_LEVELS = void 0;
+exports.LOG_LEVELS = {
+    debug: { name: 'DEBUG', value: 0 },
+    info: { name: 'INFO', value: 1 },
+    warn: { name: 'WARN', value: 2 },
+    error: { name: 'ERROR', value: 3 },
+};
+//# sourceMappingURL=types.js.map

package/dist/cjs/core/user-config.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userConfigPath = userConfigPath;
+exports.loadUserConfig = loadUserConfig;
+exports.saveUserConfig = saveUserConfig;
+exports.maskKey = maskKey;
+exports.persistCredentials = persistCredentials;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Location of the config file. `NOCVILLE_CONFIG` overrides (used by tests);
+ * otherwise `$XDG_CONFIG_HOME/nocville/config.json`, else `~/.config/nocville/config.json`.
+ */
+function userConfigPath() {
+    const override = process.env['NOCVILLE_CONFIG'];
+    if (override)
+        return override;
+    const xdg = process.env['XDG_CONFIG_HOME'];
+    const base = xdg && xdg.trim() ? xdg : (0, node_path_1.join)((0, node_os_1.homedir)(), '.config');
+    return (0, node_path_1.join)(base, 'nocville', 'config.json');
+}
+/** Read the user config; missing or unreadable files yield `{}` (never throws). */
+function loadUserConfig(path = userConfigPath()) {
+    try {
+        const raw = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf-8'));
+        const out = {};
+        if (typeof raw['apiUrl'] === 'string' && raw['apiUrl'])
+            out.apiUrl = raw['apiUrl'];
+        if (typeof raw['apiKey'] === 'string' && raw['apiKey'])
+            out.apiKey = raw['apiKey'];
+        if (typeof raw['map'] === 'string' && raw['map'])
+            out.map = raw['map'];
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge `patch` into the stored config and write it with owner-only perms
+ * (dir 0700, file 0600) via an atomic rename. Undefined fields are left as-is;
+ * an empty string clears a field. Returns the written path.
+ */
+function saveUserConfig(patch, path = userConfigPath()) {
+    const current = loadUserConfig(path);
+    const next = { ...current };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined)
+            continue;
+        if (v === '')
+            delete next[k];
+        else
+            next[k] = v;
+    }
+    const dir = (0, node_path_1.dirname)(path);
+    if (!(0, node_fs_1.existsSync)(dir))
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(next, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    (0, node_fs_1.renameSync)(tmp, path);
+    try {
+        (0, node_fs_1.chmodSync)(path, 0o600);
+    }
+    catch {
+        // best effort (e.g. Windows)
+    }
+    return path;
+}
+/** Mask an API key for display: keep a short prefix/suffix only. */
+function maskKey(key) {
+    if (!key)
+        return '(none)';
+    if (key.length <= 10)
+        return '****';
+    return `${key.slice(0, 4)}…${key.slice(-4)}`;
+}
+/**
+ * Save credentials (explicit flags win; else migrate any from a legacy hook
+ * command) and return the effective config. Shared by claude-code/codex setup.
+ */
+function persistCredentials(explicit, legacy = {}) {
+    const saved = loadUserConfig();
+    const patch = {
+        apiUrl: explicit.apiUrl ?? (saved.apiUrl ? undefined : legacy.apiUrl),
+        apiKey: explicit.apiKey ?? (saved.apiKey ? undefined : legacy.apiKey),
+        map: explicit.map,
+    };
+    const path = patch.apiUrl || patch.apiKey || patch.map ? saveUserConfig(patch) : userConfigPath();
+    return { ...loadUserConfig(), path };
+}
+//# sourceMappingURL=user-config.js.map