@nocville/npc 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,41 @@
+import { NocvilleClient } from '@nocville/node';
+import type { NpcConfig, NpcState, CollectedMetrics, Archetype, BehaviorHints, CompanionDecl } from './types.js';
+import { Logger } from './logger.js';
+export declare abstract class BaseNPC {
+    protected client: NocvilleClient;
+    protected logger: Logger;
+    protected config: NpcConfig;
+    protected state: NpcState;
+    private shutdownHandlers;
+    private authErrorLogged;
+    constructor(config: NpcConfig);
+    abstract get name(): string;
+    /**
+     * 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(): string | null;
+    /** Per-NPC default banner name. Overridden by each NPC; null means none. */
+    protected get defaultDisplayName(): string | null;
+    /** The banner name to send, clamped to the API's 32-char limit, or undefined. */
+    private pushName;
+    /** NPC archetype — steers movement speed and default behavior. Override per NPC. */
+    get archetype(): Archetype;
+    /** Base behavior hints sent on every push (merged with per-cycle overrides). */
+    get behavior(): BehaviorHints;
+    /** Companion pixel-art object to spawn alongside this NPC, or null for none. */
+    get companion(): CompanionDecl | null;
+    /** Heartbeat interval in seconds — the server marks the NPC unknown at 2x this. */
+    get heartbeatSeconds(): number;
+    protected abstract onStart(): Promise<void>;
+    protected abstract onStop(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    protected pushMetrics(metrics: CollectedMetrics): Promise<void>;
+    /** Log a push failure. A 401 gets a single actionable error; others warn each time. */
+    protected reportPushFailure(error?: string): void;
+    private attachSignalHandlers;
+    private detachSignalHandlers;
+}
+//# sourceMappingURL=base-npc.d.ts.map

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/session-filter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Which AI-agent sessions publish to the office (`~/.config/nocville/sessions.json`).
+ *
+ * - Empty lists (or no file): every session publishes — the default.
+ * - `deny` always wins.
+ * - If `allow` has any entry, only sessions matching one of them publish.
+ *
+ * Patterns are case-insensitive globs (`*` any run of characters, `?` one character).
+ * A `projects` pattern without a slash matches any folder name on the session's working
+ * directory path (so `client-*` also covers `~/work/client-acme/api`); with a slash (or a
+ * leading `~`) it matches that directory or anything inside it (`~/work/secret`,
+ * `~/work/*`). A `sessions` pattern matches the agent's session name (Claude Code's
+ * session title); sessions without a name never match it.
+ *
+ * Read on every push, so edits apply to running sessions without reinstalling hooks.
+ */
+export interface SessionRules {
+    projects: string[];
+    sessions: string[];
+}
+export interface SessionFilter {
+    allow: SessionRules;
+    deny: SessionRules;
+    /** Set when the file exists but can't be used; nothing publishes until it's fixed. */
+    error?: string;
+}
+export interface SessionIdentity {
+    /** The session's working directory. */
+    projectDir: string;
+    /** Session name/title, when the agent has one. */
+    name?: string;
+}
+export interface PublishDecision {
+    publish: boolean;
+    reason: string;
+}
+export declare const SESSION_FILTER_TEMPLATE: {
+    _help: string[];
+    allow: {
+        projects: never[];
+        sessions: never[];
+    };
+    deny: {
+        projects: never[];
+        sessions: never[];
+    };
+};
+/** `NOCVILLE_SESSIONS_CONFIG` overrides; otherwise `sessions.json` beside config.json. */
+export declare function sessionFilterPath(): string;
+/** Never throws. A missing file means "publish everything". */
+export declare function loadSessionFilter(path?: string): SessionFilter;
+/** Write the commented template if no file exists; returns the path. */
+export declare function ensureSessionFilterTemplate(path?: string): {
+    path: string;
+    created: boolean;
+};
+/** Decide whether a session may publish. Pure apart from `homedir()` for `~` patterns. */
+export declare function sessionPublishDecision(filter: SessionFilter, who: SessionIdentity): PublishDecision;
+//# sourceMappingURL=session-filter.d.ts.map