@nocville/npc 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,120 @@
+function toNum(v) {
+    if (v === null)
+        return null;
+    const n = Number(v);
+    return Number.isNaN(n) ? null : n;
+}
+function ghHeaders(opts) {
+    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}`;
+    return headers;
+}
+/** Look up a repo's default branch (one call at startup). Null on failure. */
+export async function fetchDefaultBranch(repo, opts = {}) {
+    const doFetch = opts.fetchFn ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
+    try {
+        const res = await doFetch(`https://api.github.com/repos/${repo}`, {
+            headers: ghHeaders(opts),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return body.default_branch ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 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 doFetch = opts.fetchFn ?? globalThis.fetch;
+    let url = `https://api.github.com/repos/${repo}/commits?per_page=${perPage}`;
+    if (opts.branch)
+        url += `&sha=${encodeURIComponent(opts.branch)}`;
+    const headers = ghHeaders(opts);
+    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 doFetch(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) {
+            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;
+}
+/**
+ * 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-api.js.map

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

@@ -0,0 +1,35 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import type { PollingNpcConfig } from '../../core/polling-npc.js';
+import type { CollectedMetrics, Archetype, CompanionDecl } from '../../core/types.js';
+import type { FetchFn } from './github-api.js';
+export interface GitHubWatcherConfig extends PollingNpcConfig {
+    /** "owner/name" */
+    repo: string;
+    token?: string;
+    branch?: string;
+    /** Injectable fetch (for tests). */
+    fetchFn?: FetchFn;
+}
+export declare class GitHubWatcherNPC extends PollingNPC {
+    private repo;
+    private token?;
+    private branch?;
+    private fetchFn?;
+    private etag;
+    private lastSeenSha;
+    private commits;
+    private rateRemaining;
+    private newCommitPollsLeft;
+    constructor(config: GitHubWatcherConfig);
+    get name(): string;
+    protected get defaultDisplayName(): string;
+    get archetype(): Archetype;
+    get companion(): CompanionDecl;
+    protected onStart(): Promise<void>;
+    protected collect(): Promise<CollectedMetrics>;
+    private reportNewCommits;
+    private reportIdle;
+    private report;
+    private buildBoard;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,144 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import { truncate } from '../../core/text.js';
+import { DEFAULTS } from './defaults.js';
+import { fetchCommits, fetchDefaultBranch, newCommitsSince, commitsWithin } from './github-api.js';
+import { relativeTime } from './format.js';
+export class GitHubWatcherNPC extends PollingNPC {
+    repo;
+    token;
+    branch;
+    fetchFn;
+    etag = null;
+    lastSeenSha = null;
+    commits = [];
+    rateRemaining = null;
+    newCommitPollsLeft = 0;
+    constructor(config) {
+        super({ ...config, pollInterval: config.pollInterval ?? DEFAULTS.pollInterval });
+        this.repo = config.repo;
+        this.token = config.token;
+        this.branch = config.branch;
+        this.fetchFn = config.fetchFn;
+    }
+    get name() {
+        return 'github-watcher';
+    }
+    get defaultDisplayName() {
+        const repoName = this.repo.split('/').pop() || this.repo;
+        return `GitHub: ${repoName}`;
+    }
+    get archetype() {
+        return 'pipeline';
+    }
+    get companion() {
+        return {
+            screenType: 'commit-board',
+            size: { w: 3, h: 2 },
+            placement: 'adjacent-wall',
+            label: this.repo,
+        };
+    }
+    async onStart() {
+        // Resolve the default branch once if the user didn't pin one.
+        if (!this.branch) {
+            const def = await fetchDefaultBranch(this.repo, {
+                token: this.token,
+                timeoutMs: DEFAULTS.fetchTimeoutMs,
+                fetchFn: this.fetchFn,
+            });
+            if (def) {
+                this.branch = def;
+                this.logger.info(`Watching default branch "${def}"`);
+            }
+        }
+        await super.onStart();
+    }
+    async collect() {
+        const result = await fetchCommits(this.repo, {
+            token: this.token,
+            etag: this.etag,
+            branch: this.branch,
+            timeoutMs: DEFAULTS.fetchTimeoutMs,
+            perPage: DEFAULTS.perPage,
+            fetchFn: this.fetchFn,
+        });
+        if (result.rateRemaining !== null)
+            this.rateRemaining = result.rateRemaining;
+        if (result.status === 403) {
+            return this.report('warning', 'concerned', 'GitHub API rate-limited (403)', 'rate-limited');
+        }
+        if (result.status === 404) {
+            return this.report('warning', 'concerned', `Repo not found: ${this.repo}`, 'not-found');
+        }
+        if (result.status === 0 && this.commits.length === 0) {
+            return this.report('warning', 'concerned', 'GitHub API unreachable', 'unreachable');
+        }
+        if (result.notModified) {
+            return this.reportIdle();
+        }
+        if (result.commits.length > 0) {
+            const fresh = newCommitsSince(result.commits, this.lastSeenSha);
+            this.commits = result.commits;
+            this.etag = result.etag ?? this.etag;
+            if (this.lastSeenSha === null) {
+                this.lastSeenSha = result.commits[0].sha;
+                return this.reportIdle();
+            }
+            if (fresh.length > 0) {
+                this.lastSeenSha = result.commits[0].sha;
+                this.newCommitPollsLeft = DEFAULTS.newCommitPolls;
+                return this.reportNewCommits(fresh);
+            }
+        }
+        return this.reportIdle();
+    }
+    reportNewCommits(fresh) {
+        const newest = fresh[0];
+        const latest = `${newest.author}: ${truncate(newest.message, 120)} (${newest.sha.slice(0, 7)})`;
+        const message = fresh.length > 1 ? `${fresh.length} new commits — latest: ${latest}` : latest;
+        return this.report('healthy', 'happy', message, 'new-commit');
+    }
+    reportIdle() {
+        if (this.newCommitPollsLeft > 0)
+            this.newCommitPollsLeft--;
+        const subStatus = this.newCommitPollsLeft > 0 ? 'new-commit' : undefined;
+        const newest = this.commits[0];
+        const message = newest
+            ? `Last: ${truncate(newest.message, 80)} (${relativeTime(newest.date)})`
+            : `Watching ${this.repo}`;
+        return this.report('healthy', 'happy', message, subStatus);
+    }
+    report(status, mood, message, subStatus) {
+        const newest = this.commits[0];
+        const secondsSinceLast = newest && newest.date
+            ? Math.max(0, Math.round((Date.now() - Date.parse(newest.date)) / 1000))
+            : 0;
+        return {
+            status,
+            mood,
+            message,
+            subStatus,
+            screenData: this.buildBoard(),
+            metrics: {
+                seconds_since_last_commit: secondsSinceLast,
+                commits_last_24h: commitsWithin(this.commits, 24),
+                api_rate_remaining: this.rateRemaining ?? -1,
+            },
+        };
+    }
+    buildBoard() {
+        const now = Date.now();
+        const header = this.branch ? `${this.repo}@${this.branch}` : this.repo;
+        const values = [{ label: 'repo', value: header }];
+        for (const c of this.commits.slice(0, 8)) {
+            const recent = c.date && now - Date.parse(c.date) < 3600_000;
+            values.push({
+                label: c.sha.slice(0, 7),
+                value: truncate(`${c.author}: ${c.message}`, 60),
+                color: recent ? 'green' : 'gray',
+            });
+        }
+        return { layout: 'commit-board', values };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/npcs/internet-connectivity/checks.d.ts

@@ -0,0 +1,24 @@
+import type { LatencyHost } from './defaults.js';
+export interface DnsCheckResult {
+    host: string;
+    ok: boolean;
+    timeMs: number;
+    error?: string;
+}
+export declare function checkDns(hosts: string[]): Promise<DnsCheckResult[]>;
+export interface HttpCheckResult {
+    url: string;
+    ok: boolean;
+    timeMs: number;
+    statusCode?: number;
+    error?: string;
+}
+export declare function checkHttp(urls: string[], timeout: number): Promise<HttpCheckResult[]>;
+export interface LatencyCheckResult {
+    host: string;
+    ok: boolean;
+    timeMs: number;
+    error?: string;
+}
+export declare function checkLatency(hosts: LatencyHost[]): Promise<LatencyCheckResult[]>;
+//# sourceMappingURL=checks.d.ts.map

package/dist/npcs/internet-connectivity/checks.js

@@ -0,0 +1,84 @@
+import { promises as dns } from 'node:dns';
+import net from 'node:net';
+export async function checkDns(hosts) {
+    return Promise.all(hosts.map(resolveSingleDns));
+}
+async function resolveSingleDns(host) {
+    const start = performance.now();
+    try {
+        await dns.resolve(host);
+        return { host, ok: true, timeMs: performance.now() - start };
+    }
+    catch (err) {
+        return {
+            host,
+            ok: false,
+            timeMs: performance.now() - start,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export async function checkHttp(urls, timeout) {
+    return Promise.all(urls.map((url) => fetchSingleUrl(url, timeout)));
+}
+async function fetchSingleUrl(url, timeout) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    const start = performance.now();
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        // Consume body to ensure connection is completed
+        await response.text();
+        return {
+            url,
+            ok: response.ok,
+            timeMs: performance.now() - start,
+            statusCode: response.status,
+        };
+    }
+    catch (err) {
+        return {
+            url,
+            ok: false,
+            timeMs: performance.now() - start,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function checkLatency(hosts) {
+    return Promise.all(hosts.map(measureTcpConnect));
+}
+function measureTcpConnect(target) {
+    return new Promise((resolve) => {
+        const start = performance.now();
+        const socket = net.connect({ host: target.host, port: target.port });
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve({
+                host: target.host,
+                ok: false,
+                timeMs: performance.now() - start,
+                error: 'Connection timed out',
+            });
+        }, 5000);
+        socket.on('connect', () => {
+            clearTimeout(timeout);
+            const timeMs = performance.now() - start;
+            socket.destroy();
+            resolve({ host: target.host, ok: true, timeMs });
+        });
+        socket.on('error', (err) => {
+            clearTimeout(timeout);
+            resolve({
+                host: target.host,
+                ok: false,
+                timeMs: performance.now() - start,
+                error: err.message,
+            });
+        });
+    });
+}
+//# sourceMappingURL=checks.js.map

package/dist/npcs/internet-connectivity/defaults.d.ts

@@ -0,0 +1,20 @@
+import type { ThresholdConfig } from '../../core/types.js';
+export interface LatencyHost {
+    host: string;
+    port: number;
+}
+export interface InternetConnectivityDefaults {
+    pollInterval: number;
+    dnsHosts: string[];
+    httpUrls: string[];
+    latencyHosts: LatencyHost[];
+    slowThreshold: number;
+    httpTimeout: number;
+    thresholds: {
+        dnsTime: ThresholdConfig;
+        httpTime: ThresholdConfig;
+        latencyTime: ThresholdConfig;
+    };
+}
+export declare const DEFAULTS: InternetConnectivityDefaults;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/internet-connectivity/defaults.js

@@ -0,0 +1,19 @@
+export const DEFAULTS = {
+    pollInterval: 30000, // 30 seconds
+    dnsHosts: ['google.com', 'cloudflare.com'],
+    // gstatic generate_204 is a stable, low-latency 204 endpoint used by many
+    // OSes for connectivity checks (replaces the flaky httpbin.org default).
+    httpUrls: ['https://1.1.1.1/cdn-cgi/trace', 'https://www.gstatic.com/generate_204'],
+    latencyHosts: [
+        { host: '8.8.8.8', port: 80 },
+        { host: '1.1.1.1', port: 80 },
+    ],
+    slowThreshold: 1000, // ms
+    httpTimeout: 5000, // ms
+    thresholds: {
+        dnsTime: { warning: 500, critical: 2000, direction: 'above' },
+        httpTime: { warning: 1000, critical: 3000, direction: 'above' },
+        latencyTime: { warning: 300, critical: 1000, direction: 'above' },
+    },
+};
+//# sourceMappingURL=defaults.js.map

package/dist/npcs/internet-connectivity/index.d.ts

@@ -0,0 +1,55 @@
+import { PollingNPC } from '../../core/polling-npc.js';
+import type { PollingNpcConfig } from '../../core/polling-npc.js';
+import type { CollectedMetrics, Status, ThresholdConfig, Archetype, BehaviorHints, CompanionDecl } from '../../core/types.js';
+import type { LatencyHost } from './defaults.js';
+export interface ConnectivityThresholds {
+    dnsTime: ThresholdConfig;
+    httpTime: ThresholdConfig;
+    latencyTime: ThresholdConfig;
+}
+export interface InternetConnectivityConfig extends PollingNpcConfig {
+    dnsHosts?: string[];
+    httpUrls?: string[];
+    latencyHosts?: LatencyHost[] | string[];
+    slowThreshold?: number;
+    httpTimeout?: number;
+    thresholds?: ConnectivityThresholds;
+}
+interface ConnectivitySample {
+    allFailed: boolean;
+    anyFailed: boolean;
+    dnsAvg: number;
+    httpAvg: number;
+    latencyAvg: number;
+}
+/**
+ * Derive overall status from live per-check thresholds. All checks failing is
+ * critical; any partial failure is at least a warning; slow-but-working checks
+ * escalate per their own thresholds.
+ */
+export declare function evaluateConnectivityStatus(sample: ConnectivitySample, thresholds: ConnectivityThresholds): Status;
+export declare class InternetConnectivityNPC extends PollingNPC {
+    private dnsHosts;
+    private httpUrls;
+    private latencyHosts;
+    private httpTimeout;
+    private thresholds;
+    private dnsHistory;
+    private httpHistory;
+    private latencyHistory;
+    constructor(config: InternetConnectivityConfig);
+    get name(): string;
+    protected get defaultDisplayName(): string;
+    get archetype(): Archetype;
+    get behavior(): BehaviorHints;
+    get companion(): CompanionDecl;
+    protected collect(): Promise<CollectedMetrics>;
+    private buildOnlineMessage;
+    private buildOfflineMessage;
+    /**
+     * Build config from CLI flags. Merges with any programmatic overrides.
+     */
+    static configFromFlags(flags: Record<string, string | boolean>): Partial<InternetConnectivityConfig>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map