@nocville/npc 0.0.0-stage → 0.2.0

package/dist/core/base-npc.js

@@ -0,0 +1,156 @@
+import { NocvilleClient } from '@nocville/node';
+import { Logger } from './logger.js';
+import { truncate } from './text.js';
+export 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('npc', config.debug);
+        this.client = new 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 ? 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(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 ? 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 = [];
+    }
+}
+//# sourceMappingURL=base-npc.js.map

package/dist/core/config.d.ts

@@ -0,0 +1,22 @@
+import type { NpcConfig } from './types.js';
+export interface ParsedArgs {
+    command: string | undefined;
+    subcommand: string | undefined;
+    /** Positional args after the subcommand. */
+    args: string[];
+    flags: Record<string, string | boolean>;
+}
+/**
+ * Simple hand-rolled CLI arg parser.
+ * Supports: --key=value, --key value, --flag (boolean)
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Resolves NPC config from: constructor options > CLI args > env vars >
+ * the saved user config (`nocville-npc init`, ~/.config/nocville/config.json).
+ */
+export declare function resolveConfig(flags: Record<string, string | boolean>, overrides?: Partial<NpcConfig>): NpcConfig;
+export declare function stringFlag(flags: Record<string, string | boolean>, key: string): string | undefined;
+export declare function boolFlag(flags: Record<string, string | boolean>, key: string): boolean | undefined;
+export declare function numberFlag(flags: Record<string, string | boolean>, key: string): number | undefined;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -0,0 +1,101 @@
+import { loadUserConfig } from './user-config.js';
+/**
+ * Simple hand-rolled CLI arg parser.
+ * Supports: --key=value, --key value, --flag (boolean)
+ */
+export 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).
+ */
+export function resolveConfig(flags, overrides) {
+    const saved = 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 };
+}
+export function stringFlag(flags, key) {
+    const val = flags[key];
+    if (typeof val === 'string')
+        return val;
+    return undefined;
+}
+export 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;
+}
+export 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/core/event-npc.d.ts

@@ -0,0 +1,8 @@
+import { BaseNPC } from './base-npc.js';
+export declare abstract class EventNPC extends BaseNPC {
+    protected abstract setupEventSource(): Promise<void>;
+    protected abstract teardownEventSource(): Promise<void>;
+    protected onStart(): Promise<void>;
+    protected onStop(): Promise<void>;
+}
+//# sourceMappingURL=event-npc.d.ts.map

package/dist/core/event-npc.js

@@ -0,0 +1,10 @@
+import { BaseNPC } from './base-npc.js';
+export class EventNPC extends BaseNPC {
+    async onStart() {
+        await this.setupEventSource();
+    }
+    async onStop() {
+        await this.teardownEventSource();
+    }
+}
+//# sourceMappingURL=event-npc.js.map

package/dist/core/logger.d.ts

@@ -0,0 +1,11 @@
+export declare class Logger {
+    private level;
+    private prefix;
+    constructor(prefix: string, debug?: boolean);
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    private log;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.js

@@ -0,0 +1,35 @@
+import { LOG_LEVELS } from './types.js';
+export class Logger {
+    level;
+    prefix;
+    constructor(prefix, debug = false) {
+        this.prefix = prefix;
+        this.level = debug ? LOG_LEVELS.debug.value : 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 = 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);
+    }
+}
+//# sourceMappingURL=logger.js.map

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

@@ -0,0 +1,18 @@
+import { BaseNPC } from './base-npc.js';
+import type { NpcConfig, CollectedMetrics } from './types.js';
+export interface PollingNpcConfig extends NpcConfig {
+    pollInterval?: number;
+}
+export declare abstract class PollingNPC extends BaseNPC {
+    private timer;
+    private collecting;
+    protected pollInterval: number;
+    constructor(config: PollingNpcConfig);
+    /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
+    get heartbeatSeconds(): number;
+    protected abstract collect(): Promise<CollectedMetrics>;
+    protected onStart(): Promise<void>;
+    protected onStop(): Promise<void>;
+    private runCollection;
+}
+//# sourceMappingURL=polling-npc.d.ts.map

package/dist/core/polling-npc.js

@@ -0,0 +1,61 @@
+import { BaseNPC } from './base-npc.js';
+function clamp(n, min, max) {
+    return Math.min(max, Math.max(min, n));
+}
+export class PollingNPC extends 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;
+        }
+    }
+}
+//# sourceMappingURL=polling-npc.js.map

package/dist/core/screen.d.ts

@@ -0,0 +1,11 @@
+import type { Status } from './types.js';
+/** A ScreenValue color token understood by the client screen renderer. */
+export type ScreenColor = 'green' | 'amber' | 'red' | 'gray';
+/** Map a status to the color the client renderer uses for it. */
+export declare function statusColor(status: Status): ScreenColor;
+/**
+ * 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.
+ */
+export declare function pushHistory(history: number[], value: number, max?: number): number[];
+//# sourceMappingURL=screen.d.ts.map

package/dist/core/screen.js

@@ -0,0 +1,24 @@
+/** Map a status to the color the client renderer uses for it. */
+export 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.
+ */
+export 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/core/text.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Truncate a string to at most `max` characters, appending an ellipsis when cut.
+ * Used to keep messages and screen lines within API limits.
+ */
+export declare function truncate(s: string, max?: number): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/core/text.js

@@ -0,0 +1,12 @@
+/**
+ * Truncate a string to at most `max` characters, appending an ellipsis when cut.
+ * Used to keep messages and screen lines within API limits.
+ */
+export 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/core/thresholds.d.ts

@@ -0,0 +1,10 @@
+import type { Status, ThresholdConfig } from './types.js';
+/**
+ * Evaluate a numeric value against thresholds to determine status.
+ */
+export declare function evaluateThreshold(value: number, config: ThresholdConfig): Status;
+/**
+ * Returns the worst (most severe) status from an array.
+ */
+export declare function worstStatus(statuses: Status[]): Status;
+//# sourceMappingURL=thresholds.d.ts.map

package/dist/core/thresholds.js

@@ -0,0 +1,44 @@
+/**
+ * Evaluate a numeric value against thresholds to determine status.
+ */
+export 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.
+ */
+export 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/core/types.d.ts

@@ -0,0 +1,60 @@
+import type { Status, Mood, ScreenData, BehaviorHints, CompanionSpec } from '@nocville/node';
+export type { Status, Mood } from '@nocville/node';
+export type { ScreenData, ScreenValue, BehaviorHints, CompanionSpec } from '@nocville/node';
+/** NPC archetype — drives server-side movement speed and default behavior. */
+export type Archetype = 'service' | 'database' | 'trading' | 'ai-agent' | 'pipeline' | 'gateway' | 'custom';
+/** A companion declaration is the SDK's CompanionSpec. */
+export type CompanionDecl = CompanionSpec;
+export interface NpcConfig {
+    apiUrl: string;
+    apiKey: string;
+    serviceId: string;
+    debug?: boolean;
+    /** Target map for status pushes — a map id or name. Omit for the team default. */
+    map?: string;
+    /** Friendly display name for the NPC banner. Overrides the per-NPC default. */
+    name?: string;
+}
+export interface CollectedMetrics {
+    status: Status;
+    mood?: Mood;
+    message: string;
+    metrics: Record<string, number | string>;
+    /** Granular sub-state (e.g. 'offline', 'new-commit', 'degraded'). */
+    subStatus?: string;
+    /** Companion screen payload for this cycle. */
+    screenData?: ScreenData;
+    /** Per-cycle behavior override, merged over the NPC's base `behavior`. */
+    behavior?: BehaviorHints;
+}
+export interface ThresholdConfig {
+    warning: number;
+    critical: number;
+    /** 'above' means value > threshold triggers; 'below' means value < threshold triggers */
+    direction?: 'above' | 'below';
+}
+export type NpcState = 'stopped' | 'running' | 'stopping';
+export interface LogLevel {
+    name: string;
+    value: number;
+}
+export declare const LOG_LEVELS: {
+    readonly debug: {
+        readonly name: "DEBUG";
+        readonly value: 0;
+    };
+    readonly info: {
+        readonly name: "INFO";
+        readonly value: 1;
+    };
+    readonly warn: {
+        readonly name: "WARN";
+        readonly value: 2;
+    };
+    readonly error: {
+        readonly name: "ERROR";
+        readonly value: 3;
+    };
+};
+export type LogLevelName = keyof typeof LOG_LEVELS;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.js

@@ -0,0 +1,7 @@
+export const 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/core/user-config.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Persisted per-user CLI config (`nocville-npc init`). Lets hook commands and
+ * long-running NPCs run without `--api-key` flags or env vars — the key never
+ * has to appear in ~/.claude/settings.json, ~/.codex/hooks.json or `ps` output.
+ */
+export interface UserConfig {
+    apiUrl?: string;
+    apiKey?: string;
+    map?: string;
+}
+/**
+ * Location of the config file. `NOCVILLE_CONFIG` overrides (used by tests);
+ * otherwise `$XDG_CONFIG_HOME/nocville/config.json`, else `~/.config/nocville/config.json`.
+ */
+export declare function userConfigPath(): string;
+/** Read the user config; missing or unreadable files yield `{}` (never throws). */
+export declare function loadUserConfig(path?: string): UserConfig;
+/**
+ * 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.
+ */
+export declare function saveUserConfig(patch: UserConfig, path?: string): string;
+/** Mask an API key for display: keep a short prefix/suffix only. */
+export declare function maskKey(key: string | undefined): string;
+/**
+ * Save credentials (explicit flags win; else migrate any from a legacy hook
+ * command) and return the effective config. Shared by claude-code/codex setup.
+ */
+export declare function persistCredentials(explicit: {
+    apiUrl?: string;
+    apiKey?: string;
+    map?: string;
+}, legacy?: {
+    apiUrl?: string;
+    apiKey?: string;
+}): {
+    apiUrl?: string;
+    apiKey?: string;
+    map?: string;
+    path: string;
+};
+//# sourceMappingURL=user-config.d.ts.map