@nocville/npc 0.2.3 → 0.3.1

package/dist/cjs/npcs/receptionist/index.js

@@ -2,36 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReceptionistNPC = void 0;
 const polling_npc_js_1 = require("../../core/polling-npc.js");
-const errors_js_1 = require("../../core/errors.js");
-const defaults_js_1 = require("./defaults.js");
-const weather_js_1 = require("./weather.js");
 class ReceptionistNPC extends polling_npc_js_1.PollingNPC {
-    explicitCoords;
-    location;
-    fahrenheit;
-    ipGeo;
-    coords = null;
-    /** Earliest time to retry geocoding / IP geo after a failure. */
-    nextGeoAttempt = 0;
-    weather = null;
-    weatherFetchedAt = 0;
-    /** Earliest time to retry the weather after a failure. */
-    nextWeatherAttempt = 0;
     constructor(config) {
-        super({ ...config, pollInterval: config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval });
-        if ((config.lat === undefined) !== (config.lon === undefined)) {
-            throw new errors_js_1.NpcConfigError('--lat and --lon must be given together');
-        }
-        if (config.lat !== undefined && !(0, weather_js_1.validCoords)(config.lat, config.lon)) {
-            throw new errors_js_1.NpcConfigError('--lat must be within ±90 and --lon within ±180');
-        }
-        this.explicitCoords =
-            config.lat !== undefined && config.lon !== undefined
-                ? { lat: config.lat, lon: config.lon }
-                : null;
-        this.location = config.location?.trim() || undefined;
-        this.fahrenheit = config.fahrenheit ?? false;
-        this.ipGeo = config.ipGeo ?? true;
+        super({ ...config, pollInterval: config.pollInterval ?? 60_000 });
     }
     get name() {
         return 'receptionist';
@@ -44,102 +17,16 @@ class ReceptionistNPC extends polling_npc_js_1.PollingNPC {
     }
     get behavior() {
         return {
+            role: 'receptionist',
+            activity: 'idle',
             greetPlayers: true,
-            patrol: { everyMinutes: [15, 30], stops: 5 },
             idle: 'stay',
-            home: { near: 'entrance' },
-        };
-    }
-    get companion() {
-        return {
-            screenType: 'welcome-sign',
-            size: { w: 2, h: 1 },
-            placement: 'adjacent-wall',
-            label: 'Welcome',
+            idlePose: 'sit',
         };
     }
     async collect() {
-        await this.refreshWeather();
-        const now = new Date();
-        const { day, date, time } = (0, weather_js_1.formatClock)(now);
-        const values = [
-            { label: 'time', value: time },
-            { label: 'day', value: day },
-            { label: 'date', value: date },
-        ];
-        let message = `${day} ${time}`;
-        const metrics = { weather_ok: this.weather ? 1 : 0 };
-        if (this.weather) {
-            const temp = this.fahrenheit
-                ? `${(0, weather_js_1.toFahrenheit)(this.weather.tempC)}°F`
-                : `${this.weather.tempC}°C`;
-            message += ` • ${temp} ${this.weather.text}`;
-            values.push({ label: 'temp', value: temp }, { label: 'condition', value: this.weather.text }, { label: 'icon', value: this.weather.icon });
-            metrics['temp_c'] = this.weather.tempC;
-            metrics['weather_code'] = this.weather.code;
-            metrics['wind_kph'] = this.weather.windKph;
-        }
-        // The receptionist is a greeter/clock — it stays healthy even when weather
-        // is unavailable (degraded time-only mode).
-        return {
-            status: 'healthy',
-            mood: 'happy',
-            message,
-            screenData: { layout: 'welcome-sign', values },
-            metrics,
-        };
-    }
-    async refreshWeather() {
-        const now = Date.now();
-        if (!this.coords)
-            await this.resolveCoords(now);
-        // Don't show a reading that has gone stale through repeated failures.
-        if (this.weather && now - this.weatherFetchedAt > defaults_js_1.DEFAULTS.weatherMaxAgeMs) {
-            this.weather = null;
-        }
-        if (!this.coords || now < this.nextWeatherAttempt)
-            return;
-        if (this.weather && now - this.weatherFetchedAt < defaults_js_1.DEFAULTS.weatherRefreshMs)
-            return;
-        const w = await (0, weather_js_1.fetchWeather)(this.coords, defaults_js_1.DEFAULTS.fetchTimeoutMs);
-        if (w) {
-            this.weather = w;
-            this.weatherFetchedAt = now;
-        }
-        else {
-            this.nextWeatherAttempt = now + defaults_js_1.DEFAULTS.retryBackoffMs;
-        }
-    }
-    async resolveCoords(now) {
-        if (this.explicitCoords) {
-            this.coords = this.explicitCoords;
-            return;
-        }
-        // Back off after a failure rather than hitting the keyless endpoints every tick.
-        if (now < this.nextGeoAttempt)
-            return;
-        this.nextGeoAttempt = now + defaults_js_1.DEFAULTS.retryBackoffMs;
-        if (this.location) {
-            this.coords = await (0, weather_js_1.geocodeLocation)(this.location, defaults_js_1.DEFAULTS.fetchTimeoutMs);
-            if (this.coords)
-                return;
-            this.logger.warn(`Could not geocode "${this.location}"` + (this.ipGeo ? ', falling back to IP geo' : ''));
-        }
-        if (!this.ipGeo) {
-            if (!this.location) {
-                this.nextGeoAttempt = Infinity; // nothing to resolve, ever
-                this.logger.info('No location set and IP geolocation disabled: time-only mode');
-            }
-            return;
-        }
-        this.coords = await (0, weather_js_1.autoGeo)(defaults_js_1.DEFAULTS.fetchTimeoutMs);
-        if (this.coords) {
-            this.logger.info("Weather location estimated from this machine's IP via ipapi.co " +
-                '(set --location or --lat/--lon, or pass --no-ip-geo to disable)');
-        }
-        else {
-            this.logger.warn('Weather geo unavailable — running in time-only mode for now');
-        }
+        // The server handles conversation and movement. Heartbeats stay quiet.
+        return { status: 'healthy', mood: 'happy', message: '', metrics: {} };
     }
 }
 exports.ReceptionistNPC = ReceptionistNPC;

package/dist/cjs/npcs/security/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityNPC = void 0;
+const polling_npc_js_1 = require("../../core/polling-npc.js");
+class SecurityNPC extends polling_npc_js_1.PollingNPC {
+    constructor(config) {
+        super({ ...config, pollInterval: config.pollInterval ?? 60_000 });
+    }
+    get name() {
+        return 'security';
+    }
+    get defaultDisplayName() {
+        return 'Security';
+    }
+    get archetype() {
+        return 'custom';
+    }
+    get behavior() {
+        return { role: 'security', activity: 'idle', idlePose: 'stand' };
+    }
+    async collect() {
+        return { status: 'healthy', mood: 'happy', message: '', metrics: {} };
+    }
+}
+exports.SecurityNPC = SecurityNPC;
+//# sourceMappingURL=index.js.map

package/dist/cjs/npcs/web-page-watcher/basic.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTitle = extractTitle;
+exports.statusFromHttp = statusFromHttp;
+exports.basicCheck = basicCheck;
+exports.hostnameOf = hostnameOf;
+/** Extract the <title> text from an HTML string (empty if none). */
+function extractTitle(html) {
+    const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    return m ? m[1].replace(/\s+/g, ' ').trim().slice(0, 80) : '';
+}
+/** Map an HTTP status to NPC status: 2xx/3xx ok, 4xx/timeout warn, 5xx/refused crit. */
+function statusFromHttp(code, timedOut = false) {
+    if (code >= 200 && code < 400)
+        return 'healthy';
+    if (code >= 400 && code < 500)
+        return 'warning';
+    if (code >= 500)
+        return 'critical';
+    return timedOut ? 'warning' : 'critical'; // 0 = network error
+}
+/** Fetch a page and extract HTTP status + <title> (basic, no browser). */
+async function basicCheck(url, timeoutMs = 8000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            signal: controller.signal,
+            headers: { 'User-Agent': 'nocville-npc' },
+            redirect: 'follow',
+        });
+        let title = '';
+        try {
+            title = extractTitle(await res.text());
+        }
+        catch {
+            // body unavailable; leave title blank
+        }
+        return { status: res.status, title, ok: res.ok, timedOut: false };
+    }
+    catch (err) {
+        const timedOut = err instanceof Error && err.name === 'AbortError';
+        return { status: 0, title: '', ok: false, timedOut };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Best-effort hostname for a URL, falling back to the raw string. */
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url.slice(0, 40);
+    }
+}
+//# sourceMappingURL=basic.js.map

package/dist/cjs/npcs/web-page-watcher/capture.js

@@ -5,6 +5,7 @@ exports.chromeArgs = chromeArgs;
 exports.runningAsRoot = runningAsRoot;
 exports.loadPuppeteer = loadPuppeteer;
 exports.browserConnected = browserConnected;
+const node_path_1 = require("node:path");
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
 const MAC_PATHS = [
@@ -50,6 +51,25 @@ function findChrome(explicit) {
                 return p;
         return null;
     }
+    if (process.platform === 'win32') {
+        const roots = [
+            process.env['LOCALAPPDATA'],
+            process.env['PROGRAMFILES'],
+            process.env['PROGRAMFILES(X86)'],
+        ].filter((p) => !!p);
+        for (const root of roots)
+            for (const relative of [
+                ['Google', 'Chrome', 'Application', 'chrome.exe'],
+                ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
+                ['Chromium', 'Application', 'chrome.exe'],
+                ['BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'],
+            ]) {
+                const path = (0, node_path_1.join)(root, ...relative);
+                if ((0, node_fs_1.existsSync)(path))
+                    return path;
+            }
+        return null;
+    }
     if (process.platform === 'linux') {
         for (const bin of LINUX_BINARIES) {
             const resolved = which(bin);
@@ -83,6 +103,12 @@ function runningAsRoot() {
  */
 async function loadPuppeteer() {
     try {
+        // Prefer CommonJS in bundled runtimes so Electron resolves through its
+        // ASAR loader. Native ESM installations use the optional dynamic import below.
+        if (typeof require === 'function') {
+            const mod = require('puppeteer-core');
+            return mod.default ?? mod;
+        }
         const dynImport = new Function('m', 'return import(m)');
         const mod = await dynImport('puppeteer-core');
         return (mod.default ?? mod);

package/dist/cjs/npcs/web-page-watcher/chrome.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findChrome = findChrome;
+exports.loadPuppeteer = loadPuppeteer;
+exports.browserConnected = browserConnected;
+const node_fs_1 = require("node:fs");
+const CHROME_PATHS = {
+    darwin: [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    ],
+    linux: [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/usr/bin/microsoft-edge',
+        '/snap/bin/chromium',
+    ],
+};
+/** Find a usable Chrome/Chromium executable: explicit path → env → known paths. */
+function findChrome(explicit) {
+    const envPath = process.env['CHROME_PATH'];
+    const candidates = [
+        ...(explicit ? [explicit] : []),
+        ...(envPath ? [envPath] : []),
+        ...(CHROME_PATHS[process.platform] ?? []),
+    ];
+    for (const p of candidates) {
+        if (p && (0, node_fs_1.existsSync)(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Load the optional `puppeteer-core` peer dependency without a static import,
+ * so the package builds and runs when it isn't installed. Returns null if the
+ * module is absent.
+ */
+async function loadPuppeteer() {
+    try {
+        // Indirect dynamic import so TypeScript/bundlers don't require the module
+        // at build time.
+        const dynImport = new Function('m', 'return import(m)');
+        const mod = await dynImport('puppeteer-core');
+        return (mod.default ?? mod);
+    }
+    catch {
+        return null;
+    }
+}
+/** True if the browser reports a live connection. */
+function browserConnected(browser) {
+    if (typeof browser.connected === 'boolean')
+        return browser.connected;
+    if (typeof browser.isConnected === 'function')
+        return browser.isConnected();
+    return true;
+}
+//# sourceMappingURL=chrome.js.map

package/dist/cli.js

@@ -47,7 +47,16 @@ Monitoring NPC types:
   internet-connectivity   Monitor network connectivity
   process-watcher         Watch for running processes
   log-watcher             Watch log files for errors
-  receptionist            Greeter showing time + local weather
+  receptionist            Lobby greeter with office check-ins and jokes
+  security                Indoor/outdoor patrols and exterior door watch
+  janitor                 Mops suspicious spots and hunts office bugs
+  barista                 Takes increasingly absurd coffee orders
+  office-cat              Naps on desks and supervises keyboards
+  office-dog              Naps, barks at coworkers and runs around
+  plant-caretaker         Waters plants and reviews their performance
+  it-technician           Inspects tech gear and recommends reboots
+  out-of-touch-executive  Interrupts coworkers between long lounge breaks
+  slightly-inappropriate-hr  Desk-based HR with questionable people skills
   github-watcher          Call out new commits on a repo
   web-page-watcher        Render a watched web page as a pixel-art TV
 
@@ -102,13 +111,8 @@ Log Watcher Options:
   --error-crit=<n>        Error count for critical status (default: 20)
   --report-interval=<ms>  Report interval in ms (default: 15000)
 
-Receptionist Options:
-  --poll-interval=<ms>    Clock tick in ms (default: 60000)
-  --lat=<n> --lon=<n>     Explicit coordinates for weather
-  --location=<name>       Place name to geocode (open-meteo)
-  --no-ip-geo             Without --lat/--lon or --location, don't look up
-                          this machine's IP location (ipapi.co); show time only
-  --fahrenheit            Show temperature in °F (default: °C)
+Office Character Options:
+  --poll-interval=<ms>    Heartbeat interval in ms (default: 60000)
 
 GitHub Watcher Options:
   --repo=<owner/name>     Repository to watch (required)
@@ -361,6 +365,38 @@ async function main() {
             await npc.start();
             break;
         }
+        case 'security': {
+            if (!config.serviceId)
+                config.serviceId = 'security';
+            const { SecurityNPC } = await import('./npcs/security/index.js');
+            const npc = new SecurityNPC({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+            });
+            logger.info('Starting security NPC');
+            await npc.start();
+            break;
+        }
+        case 'janitor':
+        case 'barista':
+        case 'office-cat':
+        case 'office-dog':
+        case 'plant-caretaker':
+        case 'it-technician':
+        case 'out-of-touch-executive':
+        case 'slightly-inappropriate-hr': {
+            if (!config.serviceId)
+                config.serviceId = parsed.command;
+            const { OFFICE_CHARACTER_NPCS } = await import('./npcs/office-characters/index.js');
+            const NPCClass = OFFICE_CHARACTER_NPCS[parsed.command];
+            const npc = new NPCClass({
+                ...config,
+                pollInterval: numberFlag(parsed.flags, 'poll-interval'),
+            });
+            logger.info(`Starting ${parsed.command} NPC`);
+            await npc.start();
+            break;
+        }
         case 'github-watcher': {
             const repo = stringFlag(parsed.flags, 'repo');
             if (!repo) {

package/dist/core/base-npc.js

@@ -128,6 +128,13 @@ export class BaseNPC {
             alertConfig: { heartbeatInterval: this.heartbeatSeconds },
             map: this.config.map,
         });
+        // An observer cannot interrupt monitoring or retries.
+        try {
+            this.config.onPushResult?.({ success: result.success, error: result.error });
+        }
+        catch {
+            /* observer only */
+        }
         if (!result.success) {
             this.reportPushFailure(result.error);
         }

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

@@ -2,6 +2,8 @@ import { BaseNPC } from './base-npc.js';
 import type { NpcConfig, CollectedMetrics } from './types.js';
 export interface PollingNpcConfig extends NpcConfig {
     pollInterval?: number;
+    /** Local diagnostics; never included in published payloads. */
+    onCollection?: (metrics: CollectedMetrics) => void;
 }
 /**
  * Lower bound for any poll interval, so a typo can't exhaust the API's
@@ -19,6 +21,7 @@ export declare abstract class PollingNPC extends BaseNPC {
     private lastPushed;
     private lastPushAt;
     protected pollInterval: number;
+    private onCollection?;
     constructor(config: PollingNpcConfig);
     /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
     get heartbeatSeconds(): number;

package/dist/core/polling-npc.js

@@ -20,8 +20,10 @@ export class PollingNPC extends BaseNPC {
     lastPushed = null;
     lastPushAt = 0;
     pollInterval;
+    onCollection;
     constructor(config) {
         super(config);
+        this.onCollection = config.onCollection;
         const requested = config.pollInterval ?? 15000;
         this.pollInterval = Number.isFinite(requested)
             ? Math.max(MIN_POLL_INTERVAL_MS, requested)
@@ -114,6 +116,12 @@ export class PollingNPC extends BaseNPC {
             // Stopped mid-collection: never push after (or race) the offline push.
             if (this.state !== 'running')
                 return;
+            try {
+                this.onCollection?.(metrics);
+            }
+            catch {
+                /* Diagnostics cannot stop publishing. */
+            }
             await this.pushMetrics(metrics);
             this.lastPushed = metrics;
             this.lastPushAt = Date.now();

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;

package/dist/index.d.ts

@@ -41,4 +41,6 @@ export type { GeminiSetupOptions } from './npcs/gemini/index.js';
 export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent, setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './npcs/cursor/index.js';
 export type { CursorSetupOptions } from './npcs/cursor/index.js';
 export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
+export { SecurityNPC } from './npcs/security/index.js';
+export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, SlightlyInappropriateHRNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -25,4 +25,6 @@ export { WebPageWatcherNPC } from './npcs/web-page-watcher/index.js';
 export { GEMINI_DEFAULTS, GEMINI_ADAPTER, geminiTransition, geminiServiceId, handleGeminiHookEvent, setupGeminiHooks, uninstallGeminiHooks, installGeminiHooksInto, GEMINI_HOOK_EVENTS, } from './npcs/gemini/index.js';
 export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent, setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './npcs/cursor/index.js';
 export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
+export { SecurityNPC } from './npcs/security/index.js';
+export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, SlightlyInappropriateHRNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
 //# sourceMappingURL=index.js.map

package/dist/npcs/agent-common/shim.js

@@ -77,13 +77,19 @@ try {
 if (neutral) process.stdout.write('{}\\n');
 `;
 export function installHookShim(nodePath, cliPath) {
+    // Desktop ships this same CLI with Electron's Node runtime. Keep the flag in
+    // the launcher (never globally), inherited by flush/watchdog child processes.
+    const electron = !!process.versions['electron'];
     writeChanged(RUNTIME_POINTER(), JSON.stringify({ node: nodePath, cli: cliPath }, null, 2) + '\n', 0o600);
     writeChanged(join(dirname(RUNTIME_POINTER()), 'node-path'), nodePath + '\n', 0o600);
     writeChanged(join(dirname(SHIM_PATH()), 'launch.cjs'), LAUNCHER, 0o600);
-    writeChanged(SHIM_PATH(), SHIM, 0o755);
+    writeChanged(SHIM_PATH(), electron ? SHIM.replace('exec "$NODE"', 'export ELECTRON_RUN_AS_NODE=1\nexec "$NODE"') : SHIM, 0o755);
     chmodSync(SHIM_PATH(), 0o755);
     // Both launchers use the same bootstrap, including imported-Cursor detection.
-    writeChanged(SHIM_PATH() + '.cmd', WINDOWS_SHIM.replace(/\n/g, '\r\n'), 0o755);
+    const windowsShim = electron
+        ? WINDOWS_SHIM.replace(':launch\n', ':launch\nset "ELECTRON_RUN_AS_NODE=1"\n')
+        : WINDOWS_SHIM;
+    writeChanged(SHIM_PATH() + '.cmd', windowsShim.replace(/\n/g, '\r\n'), 0o755);
     pruneOldRuntimes(dirname(RUNTIME_POINTER()));
     return SHIM_PATH();
 }

package/dist/npcs/github-watcher/github.d.ts

@@ -0,0 +1,39 @@
+export interface CommitInfo {
+    sha: string;
+    author: string;
+    message: string;
+    date: string;
+}
+export interface FetchCommitsResult {
+    /** 304 Not Modified — the ETag matched, nothing changed, no rate-limit cost. */
+    notModified: boolean;
+    commits: CommitInfo[];
+    etag: string | null;
+    rateRemaining: number | null;
+    status: number;
+}
+export interface FetchOptions {
+    token?: string;
+    etag?: string | null;
+    timeoutMs?: number;
+    perPage?: number;
+}
+/**
+ * Fetch recent commits from the GitHub REST API using conditional requests.
+ * Passing the previous ETag yields a 304 (which does not count against the
+ * unauthenticated 60/hour limit) when nothing has changed. Never throws —
+ * network errors surface as `status: 0`.
+ */
+export declare function fetchCommits(repo: string, opts?: FetchOptions): Promise<FetchCommitsResult>;
+/** Count how many commits landed within the last `hours`. */
+export declare function commitsWithin(commits: CommitInfo[], hours: number, now?: number): number;
+/** Short relative-time string like "3m ago", "2h ago", "1d ago". */
+export declare function relativeTime(iso: string, now?: number): string;
+/**
+ * Return the commits newer than `lastSeenSha`, newest-first. When the sha isn't
+ * present in the window (more than a page of new commits, or rewritten history)
+ * every fetched commit is treated as new. An undefined sha means "not seeded
+ * yet" — returns empty so the caller can seed without a spurious announcement.
+ */
+export declare function newCommitsSince(commits: CommitInfo[], lastSeenSha: string | null): CommitInfo[];
+//# sourceMappingURL=github.d.ts.map

package/dist/npcs/github-watcher/github.js

@@ -0,0 +1,103 @@
+function toNum(v) {
+    if (v === null)
+        return null;
+    const n = Number(v);
+    return Number.isNaN(n) ? null : n;
+}
+/**
+ * Fetch recent commits from the GitHub REST API using conditional requests.
+ * Passing the previous ETag yields a 304 (which does not count against the
+ * unauthenticated 60/hour limit) when nothing has changed. Never throws —
+ * network errors surface as `status: 0`.
+ */
+export async function fetchCommits(repo, opts = {}) {
+    const perPage = opts.perPage ?? 10;
+    const url = `https://api.github.com/repos/${repo}/commits?per_page=${perPage}`;
+    const headers = {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'nocville-npc',
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+    if (opts.token)
+        headers['Authorization'] = `Bearer ${opts.token}`;
+    if (opts.etag)
+        headers['If-None-Match'] = opts.etag;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
+    try {
+        const res = await fetch(url, { headers, signal: controller.signal });
+        const rateRemaining = toNum(res.headers.get('x-ratelimit-remaining'));
+        const etag = res.headers.get('etag');
+        if (res.status === 304) {
+            return { notModified: true, commits: [], etag: opts.etag ?? null, rateRemaining, status: 304 };
+        }
+        if (!res.ok) {
+            // Drain the body so the socket can be reused.
+            await res.text().catch(() => undefined);
+            return { notModified: false, commits: [], etag, rateRemaining, status: res.status };
+        }
+        const body = (await res.json());
+        const commits = body.map((c) => parseCommit(c));
+        return { notModified: false, commits, etag, rateRemaining, status: res.status };
+    }
+    catch {
+        return { notModified: false, commits: [], etag: null, rateRemaining: null, status: 0 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parseCommit(c) {
+    const commit = c['commit'] ?? {};
+    const commitAuthor = commit['author'] ?? {};
+    const ghAuthor = c['author'] ?? {};
+    const message = String(commit['message'] ?? '').split('\n')[0] ?? '';
+    return {
+        sha: String(c['sha'] ?? ''),
+        author: String(commitAuthor['name'] ?? ghAuthor['login'] ?? 'unknown'),
+        message,
+        date: String(commitAuthor['date'] ?? ''),
+    };
+}
+/** Count how many commits landed within the last `hours`. */
+export function commitsWithin(commits, hours, now = Date.now()) {
+    const cutoff = now - hours * 3600_000;
+    return commits.filter((c) => {
+        const t = Date.parse(c.date);
+        return Number.isFinite(t) && t >= cutoff;
+    }).length;
+}
+/** Short relative-time string like "3m ago", "2h ago", "1d ago". */
+export function relativeTime(iso, now = Date.now()) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return 'unknown';
+    const secs = Math.max(0, Math.round((now - t) / 1000));
+    if (secs < 60)
+        return `${secs}s ago`;
+    const mins = Math.round(secs / 60);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hrs = Math.round(mins / 60);
+    if (hrs < 24)
+        return `${hrs}h ago`;
+    const days = Math.round(hrs / 24);
+    return `${days}d ago`;
+}
+/**
+ * Return the commits newer than `lastSeenSha`, newest-first. When the sha isn't
+ * present in the window (more than a page of new commits, or rewritten history)
+ * every fetched commit is treated as new. An undefined sha means "not seeded
+ * yet" — returns empty so the caller can seed without a spurious announcement.
+ */
+export function newCommitsSince(commits, lastSeenSha) {
+    if (!lastSeenSha)
+        return [];
+    const idx = commits.findIndex((c) => c.sha === lastSeenSha);
+    if (idx === 0)
+        return []; // newest is already seen
+    if (idx === -1)
+        return commits; // fell out of the window — treat all as new
+    return commits.slice(0, idx);
+}
+//# sourceMappingURL=github.js.map