@nocville/npc 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubWatcherNPC = void 0;
+const polling_npc_js_1 = require("../../core/polling-npc.js");
+const text_js_1 = require("../../core/text.js");
+const defaults_js_1 = require("./defaults.js");
+const github_api_js_1 = require("./github-api.js");
+const format_js_1 = require("./format.js");
+class GitHubWatcherNPC extends polling_npc_js_1.PollingNPC {
+    repo;
+    token;
+    branch;
+    fetchFn;
+    etag = null;
+    lastSeenSha = null;
+    commits = [];
+    rateRemaining = null;
+    newCommitPollsLeft = 0;
+    constructor(config) {
+        super({ ...config, pollInterval: config.pollInterval ?? defaults_js_1.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 (0, github_api_js_1.fetchDefaultBranch)(this.repo, {
+                token: this.token,
+                timeoutMs: defaults_js_1.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 (0, github_api_js_1.fetchCommits)(this.repo, {
+            token: this.token,
+            etag: this.etag,
+            branch: this.branch,
+            timeoutMs: defaults_js_1.DEFAULTS.fetchTimeoutMs,
+            perPage: defaults_js_1.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 = (0, github_api_js_1.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_js_1.DEFAULTS.newCommitPolls;
+                return this.reportNewCommits(fresh);
+            }
+        }
+        return this.reportIdle();
+    }
+    reportNewCommits(fresh) {
+        const newest = fresh[0];
+        const latest = `${newest.author}: ${(0, text_js_1.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: ${(0, text_js_1.truncate)(newest.message, 80)} (${(0, format_js_1.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: (0, github_api_js_1.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: (0, text_js_1.truncate)(`${c.author}: ${c.message}`, 60),
+                color: recent ? 'green' : 'gray',
+            });
+        }
+        return { layout: 'commit-board', values };
+    }
+}
+exports.GitHubWatcherNPC = GitHubWatcherNPC;
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDns = checkDns;
+exports.checkHttp = checkHttp;
+exports.checkLatency = checkLatency;
+const node_dns_1 = require("node:dns");
+const node_net_1 = __importDefault(require("node:net"));
+async function checkDns(hosts) {
+    return Promise.all(hosts.map(resolveSingleDns));
+}
+async function resolveSingleDns(host) {
+    const start = performance.now();
+    try {
+        await node_dns_1.promises.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),
+        };
+    }
+}
+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);
+    }
+}
+async function checkLatency(hosts) {
+    return Promise.all(hosts.map(measureTcpConnect));
+}
+function measureTcpConnect(target) {
+    return new Promise((resolve) => {
+        const start = performance.now();
+        const socket = node_net_1.default.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/cjs/npcs/internet-connectivity/defaults.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULTS = void 0;
+exports.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/cjs/npcs/internet-connectivity/index.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InternetConnectivityNPC = void 0;
+exports.evaluateConnectivityStatus = evaluateConnectivityStatus;
+const polling_npc_js_1 = require("../../core/polling-npc.js");
+const thresholds_js_1 = require("../../core/thresholds.js");
+const screen_js_1 = require("../../core/screen.js");
+const config_js_1 = require("../../core/config.js");
+const checks_js_1 = require("./checks.js");
+const defaults_js_1 = require("./defaults.js");
+/**
+ * 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.
+ */
+function evaluateConnectivityStatus(sample, thresholds) {
+    if (sample.allFailed)
+        return 'critical';
+    const timeStatus = (0, thresholds_js_1.worstStatus)([
+        (0, thresholds_js_1.evaluateThreshold)(sample.dnsAvg, thresholds.dnsTime),
+        (0, thresholds_js_1.evaluateThreshold)(sample.httpAvg, thresholds.httpTime),
+        (0, thresholds_js_1.evaluateThreshold)(sample.latencyAvg, thresholds.latencyTime),
+    ]);
+    const failStatus = sample.anyFailed ? 'warning' : 'healthy';
+    return (0, thresholds_js_1.worstStatus)([timeStatus, failStatus]);
+}
+/** Scale a threshold set by a ratio, preserving direction. */
+function scaleThresholds(base, ratio) {
+    const scale = (t) => ({
+        warning: Math.round(t.warning * ratio),
+        critical: Math.round(t.critical * ratio),
+        direction: t.direction,
+    });
+    return {
+        dnsTime: scale(base.dnsTime),
+        httpTime: scale(base.httpTime),
+        latencyTime: scale(base.latencyTime),
+    };
+}
+class InternetConnectivityNPC extends polling_npc_js_1.PollingNPC {
+    dnsHosts;
+    httpUrls;
+    latencyHosts;
+    httpTimeout;
+    thresholds;
+    dnsHistory = [];
+    httpHistory = [];
+    latencyHistory = [];
+    constructor(config) {
+        super({
+            ...config,
+            pollInterval: config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval,
+        });
+        this.dnsHosts = config.dnsHosts ?? defaults_js_1.DEFAULTS.dnsHosts;
+        this.httpUrls = config.httpUrls ?? defaults_js_1.DEFAULTS.httpUrls;
+        this.latencyHosts = config.latencyHosts
+            ? parseLatencyHosts(config.latencyHosts)
+            : defaults_js_1.DEFAULTS.latencyHosts;
+        this.httpTimeout = config.httpTimeout ?? defaults_js_1.DEFAULTS.httpTimeout;
+        // Threshold resolution: explicit thresholds win; else if the legacy
+        // --slow-threshold differs from the default, scale the live thresholds by
+        // that ratio for back-compat; else use the defaults.
+        if (config.thresholds) {
+            this.thresholds = config.thresholds;
+        }
+        else if (config.slowThreshold && config.slowThreshold !== defaults_js_1.DEFAULTS.slowThreshold) {
+            this.thresholds = scaleThresholds(defaults_js_1.DEFAULTS.thresholds, config.slowThreshold / defaults_js_1.DEFAULTS.slowThreshold);
+        }
+        else {
+            this.thresholds = defaults_js_1.DEFAULTS.thresholds;
+        }
+    }
+    get name() {
+        return 'internet-connectivity';
+    }
+    get defaultDisplayName() {
+        return 'Internet';
+    }
+    get archetype() {
+        return 'gateway';
+    }
+    get behavior() {
+        return { idle: 'wander' };
+    }
+    get companion() {
+        return {
+            screenType: 'dashboard-wall',
+            size: { w: 2, h: 2 },
+            placement: 'adjacent-wall',
+            label: 'Internet',
+        };
+    }
+    async collect() {
+        const [dnsResults, httpResults, latencyResults] = await Promise.all([
+            (0, checks_js_1.checkDns)(this.dnsHosts),
+            (0, checks_js_1.checkHttp)(this.httpUrls, this.httpTimeout),
+            (0, checks_js_1.checkLatency)(this.latencyHosts),
+        ]);
+        const dnsOk = dnsResults.filter((r) => r.ok).length;
+        const dnsFail = dnsResults.length - dnsOk;
+        const httpOk = httpResults.filter((r) => r.ok).length;
+        const httpFail = httpResults.length - httpOk;
+        const dnsAvg = avgTime(dnsResults);
+        const httpAvg = avgTime(httpResults);
+        const latencyAvg = avgTime(latencyResults);
+        const isOnline = dnsOk > 0 || httpOk > 0;
+        const allFailed = dnsOk === 0 && httpOk === 0;
+        const anyFailed = dnsResults.some((r) => !r.ok) ||
+            httpResults.some((r) => !r.ok) ||
+            latencyResults.some((r) => !r.ok);
+        const status = evaluateConnectivityStatus({ allFailed, anyFailed, dnsAvg, httpAvg, latencyAvg }, this.thresholds);
+        const mood = statusToMood(status);
+        const message = allFailed
+            ? this.buildOfflineMessage(dnsResults, httpResults)
+            : this.buildOnlineMessage(dnsAvg, httpAvg, latencyAvg);
+        (0, screen_js_1.pushHistory)(this.dnsHistory, round(dnsAvg));
+        (0, screen_js_1.pushHistory)(this.httpHistory, round(httpAvg));
+        (0, screen_js_1.pushHistory)(this.latencyHistory, round(latencyAvg));
+        const screenData = {
+            layout: 'multi-metric',
+            values: [
+                {
+                    label: 'DNS',
+                    value: `${round(dnsAvg)}ms`,
+                    color: (0, screen_js_1.statusColor)((0, thresholds_js_1.evaluateThreshold)(dnsAvg, this.thresholds.dnsTime)),
+                    sparkline: [...this.dnsHistory],
+                },
+                {
+                    label: 'HTTP',
+                    value: `${round(httpAvg)}ms`,
+                    color: (0, screen_js_1.statusColor)((0, thresholds_js_1.evaluateThreshold)(httpAvg, this.thresholds.httpTime)),
+                    sparkline: [...this.httpHistory],
+                },
+                {
+                    label: 'TCP',
+                    value: `${round(latencyAvg)}ms`,
+                    color: (0, screen_js_1.statusColor)((0, thresholds_js_1.evaluateThreshold)(latencyAvg, this.thresholds.latencyTime)),
+                    sparkline: [...this.latencyHistory],
+                },
+                { label: 'NET', value: isOnline ? 'ONLINE' : 'OFFLINE', color: isOnline ? 'green' : 'red' },
+            ],
+        };
+        return {
+            status,
+            mood,
+            message,
+            subStatus: isOnline ? undefined : 'offline',
+            screenData,
+            metrics: {
+                dns_avg_ms: round(dnsAvg),
+                http_avg_ms: round(httpAvg),
+                latency_avg_ms: round(latencyAvg),
+                dns_ok_count: dnsOk,
+                dns_fail_count: dnsFail,
+                http_ok_count: httpOk,
+                http_fail_count: httpFail,
+                is_online: isOnline ? 1 : 0,
+            },
+        };
+    }
+    buildOnlineMessage(dnsAvg, httpAvg, latencyAvg) {
+        return `Online | DNS: ${round(dnsAvg)}ms | HTTP: ${round(httpAvg)}ms | Latency: ${round(latencyAvg)}ms`;
+    }
+    buildOfflineMessage(dnsResults, httpResults) {
+        const problems = [];
+        if (dnsResults.every((r) => !r.ok)) {
+            problems.push('DNS resolution failed');
+        }
+        if (httpResults.every((r) => !r.ok)) {
+            problems.push('no HTTP connectivity');
+        }
+        return `OFFLINE: ${problems.join(', ') || 'all checks failed'}`;
+    }
+    /**
+     * Build config from CLI flags. Merges with any programmatic overrides.
+     */
+    static configFromFlags(flags) {
+        const config = {};
+        const dnsHostsRaw = (0, config_js_1.stringFlag)(flags, 'dns-hosts');
+        if (dnsHostsRaw) {
+            config.dnsHosts = dnsHostsRaw.split(',').map((s) => s.trim());
+        }
+        const httpUrlsRaw = (0, config_js_1.stringFlag)(flags, 'http-urls');
+        if (httpUrlsRaw) {
+            config.httpUrls = httpUrlsRaw.split(',').map((s) => s.trim());
+        }
+        const latencyHostsRaw = (0, config_js_1.stringFlag)(flags, 'latency-hosts');
+        if (latencyHostsRaw) {
+            config.latencyHosts = latencyHostsRaw.split(',').map((s) => {
+                const trimmed = s.trim();
+                const colonIndex = trimmed.lastIndexOf(':');
+                if (colonIndex !== -1) {
+                    const host = trimmed.slice(0, colonIndex);
+                    const port = Number(trimmed.slice(colonIndex + 1));
+                    if (!Number.isNaN(port))
+                        return { host, port };
+                }
+                return { host: trimmed, port: 80 };
+            });
+        }
+        const slowThreshold = (0, config_js_1.numberFlag)(flags, 'slow-threshold');
+        if (slowThreshold !== undefined)
+            config.slowThreshold = slowThreshold;
+        const pollInterval = (0, config_js_1.numberFlag)(flags, 'poll-interval');
+        if (pollInterval !== undefined)
+            config.pollInterval = pollInterval;
+        return config;
+    }
+}
+exports.InternetConnectivityNPC = InternetConnectivityNPC;
+// ---------- Helpers ----------
+function avgTime(results) {
+    if (results.length === 0)
+        return 0;
+    const sum = results.reduce((acc, r) => acc + r.timeMs, 0);
+    return sum / results.length;
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}
+function statusToMood(status) {
+    switch (status) {
+        case 'healthy':
+            return 'happy';
+        case 'warning':
+            return 'concerned';
+        case 'critical':
+            return 'stressed';
+        default:
+            return 'idle';
+    }
+}
+/**
+ * Normalise latency hosts from either string[] (CLI) or LatencyHost[].
+ * String entries can be "host" or "host:port".
+ */
+function parseLatencyHosts(input) {
+    return input.map((item) => {
+        if (typeof item === 'object')
+            return item;
+        const colonIndex = item.lastIndexOf(':');
+        if (colonIndex !== -1) {
+            const host = item.slice(0, colonIndex);
+            const port = Number(item.slice(colonIndex + 1));
+            if (!Number.isNaN(port))
+                return { host, port };
+        }
+        return { host: item, port: 80 };
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/npcs/log-watcher/buffer.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyLine = classifyLine;
+exports.pushRecent = pushRecent;
+exports.buildLogScreen = buildLogScreen;
+exports.shouldEmitBurst = shouldEmitBurst;
+/** Classify a raw log line against the error/warning patterns. */
+function classifyLine(line, errorRe, warningRe) {
+    if (errorRe.test(line))
+        return 'error';
+    if (warningRe.test(line))
+        return 'warning';
+    return 'info';
+}
+/**
+ * Push a line into the bounded ring buffer: each entry is capped at `cap`
+ * characters and the buffer keeps only the last `max` entries.
+ */
+function pushRecent(buffer, line, level, max = 12, cap = 80) {
+    buffer.push({ text: line.slice(0, cap), level });
+    if (buffer.length > max)
+        buffer.splice(0, buffer.length - max);
+    return buffer;
+}
+/** Build a log-terminal screen payload from the ring buffer, colored per level. */
+function buildLogScreen(buffer) {
+    return {
+        layout: 'log-terminal',
+        values: buffer.map((l) => ({
+            label: '',
+            value: l.text,
+            color: l.level === 'error' ? 'red' : l.level === 'warning' ? 'amber' : 'green',
+        })),
+    };
+}
+/** True when enough time has elapsed since the last burst push to emit again. */
+function shouldEmitBurst(lastEmit, now, windowMs = 5000) {
+    return now - lastEmit >= windowMs;
+}
+//# sourceMappingURL=buffer.js.map

package/dist/cjs/npcs/log-watcher/defaults.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULTS = void 0;
+exports.DEFAULTS = {
+    reportInterval: 15000, // 15 seconds
+    windowSeconds: 300, // 5 minutes
+    errorPattern: 'ERROR|FATAL',
+    warningPattern: 'WARN',
+    errorWarn: 5, // errors in window before warning status
+    errorCrit: 20, // errors in window before critical status
+};
+//# sourceMappingURL=defaults.js.map