@nocville/npc 0.2.2 → 0.3.0

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

@@ -3,6 +3,8 @@ 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 thresholds_js_1 = require("../../core/thresholds.js");
+const errors_js_1 = require("../../core/errors.js");
 const defaults_js_1 = require("./defaults.js");
 const github_api_js_1 = require("./github-api.js");
 const format_js_1 = require("./format.js");
@@ -15,12 +17,24 @@ class GitHubWatcherNPC extends polling_npc_js_1.PollingNPC {
     lastSeenSha = null;
     commits = [];
     rateRemaining = null;
+    /** While rate-limited, don't call GitHub again before this time (epoch ms). */
+    rateLimitedUntil = 0;
+    consecutiveFailures = 0;
     newCommitPollsLeft = 0;
     constructor(config) {
-        super({ ...config, pollInterval: config.pollInterval ?? defaults_js_1.DEFAULTS.pollInterval });
+        super({
+            ...config,
+            // Unauthenticated requests get 60/hour and 304s still count against
+            // them, so a 60s poll (plus the branch lookup) would hit the limit.
+            pollInterval: config.pollInterval ??
+                (config.token ? defaults_js_1.DEFAULTS.pollInterval : defaults_js_1.DEFAULTS.unauthenticatedPollInterval),
+        });
+        if (!(0, github_api_js_1.isValidRepo)(config.repo)) {
+            throw new errors_js_1.NpcConfigError(`--repo must look like owner/name (got "${(0, text_js_1.truncate)(config.repo, 80)}")`);
+        }
         this.repo = config.repo;
-        this.token = config.token;
-        this.branch = config.branch;
+        this.token = config.token || undefined;
+        this.branch = config.branch?.trim() || undefined;
         this.fetchFn = config.fetchFn;
     }
     get name() {
@@ -42,7 +56,8 @@ class GitHubWatcherNPC extends polling_npc_js_1.PollingNPC {
         };
     }
     async onStart() {
-        // Resolve the default branch once if the user didn't pin one.
+        // Resolve the default branch once if the user didn't pin one (it only
+        // labels the board; the commits API already defaults to that branch).
         if (!this.branch) {
             const def = await (0, github_api_js_1.fetchDefaultBranch)(this.repo, {
                 token: this.token,
@@ -57,6 +72,8 @@ class GitHubWatcherNPC extends polling_npc_js_1.PollingNPC {
         await super.onStart();
     }
     async collect() {
+        if (Date.now() < this.rateLimitedUntil)
+            return this.rateLimited();
         const result = await (0, github_api_js_1.fetchCommits)(this.repo, {
             token: this.token,
             etag: this.etag,
@@ -67,39 +84,68 @@ class GitHubWatcherNPC extends polling_npc_js_1.PollingNPC {
         });
         if (result.rateRemaining !== null)
             this.rateRemaining = result.rateRemaining;
-        if (result.status === 403) {
-            return this.report('warning', 'concerned', 'GitHub API rate-limited (403)', 'rate-limited');
+        const failure = this.classifyFailure(result);
+        if (failure)
+            return failure;
+        this.consecutiveFailures = 0;
+        if (result.notModified)
+            return this.reportIdle();
+        if (result.status === 409)
+            return this.report('healthy', 'Repository is empty');
+        this.etag = result.etag ?? this.etag;
+        if (result.commits.length === 0)
+            return this.reportIdle();
+        const fresh = (0, github_api_js_1.newCommitsSince)(result.commits, this.lastSeenSha);
+        this.commits = result.commits;
+        const seeded = this.lastSeenSha !== null;
+        this.lastSeenSha = result.commits[0].sha;
+        if (!seeded || fresh.length === 0)
+            return this.reportIdle();
+        this.newCommitPollsLeft = defaults_js_1.DEFAULTS.newCommitPolls;
+        return this.reportNewCommits(fresh);
+    }
+    /** Map an error response to a report, or null when the fetch succeeded. */
+    classifyFailure(result) {
+        const { status } = result;
+        if (status === 304 || status === 409 || (status >= 200 && status < 300))
+            return null;
+        if (status === 429 || (status === 403 && result.rateRemaining === 0)) {
+            this.rateLimitedUntil = result.rateResetAt ?? Date.now() + 15 * 60_000;
+            if (!this.token) {
+                this.logger.warn('GitHub rate limit reached; set GITHUB_TOKEN for a higher limit');
+            }
+            return this.rateLimited();
         }
-        if (result.status === 404) {
-            return this.report('warning', 'concerned', `Repo not found: ${this.repo}`, 'not-found');
+        if (status === 401) {
+            return this.report('warning', 'GitHub token rejected (401)', 'auth-failed');
         }
-        if (result.status === 0 && this.commits.length === 0) {
-            return this.report('warning', 'concerned', 'GitHub API unreachable', 'unreachable');
+        if (status === 403) {
+            return this.report('warning', `Access to ${this.repo} denied (403)`, 'forbidden');
         }
-        if (result.notModified) {
-            return this.reportIdle();
+        if (status === 404) {
+            const hint = this.token ? '' : ' (private repos need GITHUB_TOKEN)';
+            return this.report('warning', `Repo not found: ${this.repo}${hint}`, 'not-found');
         }
-        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);
-            }
+        // Network error, timeout or 5xx: ride out blips while there's a board to show.
+        this.consecutiveFailures++;
+        if (this.commits.length > 0 && this.consecutiveFailures < defaults_js_1.DEFAULTS.failuresBeforeWarning) {
+            return this.reportIdle();
         }
-        return this.reportIdle();
+        const what = status === 0 ? 'unreachable' : `error (HTTP ${status})`;
+        return this.report('warning', `GitHub API ${what}`, 'unreachable');
+    }
+    rateLimited() {
+        const resumes = new Date(this.rateLimitedUntil).toLocaleTimeString([], {
+            hour: '2-digit',
+            minute: '2-digit',
+        });
+        return this.report('warning', `GitHub API rate-limited until ${resumes}`, 'rate-limited');
     }
     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');
+        return this.report('healthy', message, 'new-commit');
     }
     reportIdle() {
         if (this.newCommitPollsLeft > 0)
@@ -109,16 +155,16 @@ class GitHubWatcherNPC extends polling_npc_js_1.PollingNPC {
         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);
+        return this.report('healthy', 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))
+    report(status, message, subStatus) {
+        const newestAt = Date.parse(this.commits[0]?.date ?? '');
+        const secondsSinceLast = Number.isFinite(newestAt)
+            ? Math.max(0, Math.round((Date.now() - newestAt) / 1000))
             : 0;
         return {
             status,
-            mood,
+            mood: (0, thresholds_js_1.moodForStatus)(status),
             message,
             subStatus,
             screenData: this.buildBoard(),
@@ -132,9 +178,9 @@ class GitHubWatcherNPC extends polling_npc_js_1.PollingNPC {
     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;
+        const values = [{ label: 'repo', value: (0, text_js_1.truncate)(header, 60) }];
+        for (const c of this.commits.slice(0, defaults_js_1.DEFAULTS.boardRows)) {
+            const recent = 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),

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

@@ -8,85 +8,88 @@ 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));
+const http_js_1 = require("../../core/http.js");
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
 }
-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();
+// ---------- DNS ----------
+/**
+ * Resolve each host's A records through a dedicated resolver with a bounded
+ * timeout (the default resolver retries for tens of seconds when DNS is down).
+ */
+async function checkDns(hosts, timeoutMs) {
+    const resolver = new node_dns_1.promises.Resolver({
+        timeout: Math.max(250, Math.floor(timeoutMs / 2)),
+        tries: 2,
+    });
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), timeoutMs);
+    });
     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),
-        };
+        return await Promise.all(hosts.map(async (host) => {
+            const start = performance.now();
+            try {
+                const outcome = await Promise.race([resolver.resolve4(host), deadline]);
+                if (outcome === 'timeout')
+                    return { target: host, ok: false, timeMs: 0, error: 'timeout' };
+                return { target: host, ok: true, timeMs: performance.now() - start };
+            }
+            catch (err) {
+                return { target: host, ok: false, timeMs: 0, error: errorText(err) };
+            }
+        }));
     }
     finally {
         clearTimeout(timer);
+        resolver.cancel();
     }
 }
-async function checkLatency(hosts) {
-    return Promise.all(hosts.map(measureTcpConnect));
+// ---------- HTTP ----------
+/**
+ * Time to response headers for each URL. The body is discarded unread, so a
+ * large or endless response costs nothing. Only 2xx counts as reachable.
+ */
+async function checkHttp(urls, timeoutMs) {
+    return Promise.all(urls.map(async (url) => {
+        const target = (0, http_js_1.displayUrl)(url); // never echo credentials or query tokens
+        const start = performance.now();
+        try {
+            const res = await fetch(url, {
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { 'User-Agent': http_js_1.NPC_USER_AGENT },
+            });
+            const timeMs = performance.now() - start;
+            await (0, http_js_1.discardBody)(res);
+            return res.ok
+                ? { target, ok: true, timeMs }
+                : { target, ok: false, timeMs: 0, error: `HTTP ${res.status}` };
+        }
+        catch (err) {
+            return { target, ok: false, timeMs: 0, error: errorText(err) };
+        }
+    }));
+}
+// ---------- Latency (TCP connect) ----------
+/** Time to establish a TCP connection to each host:port. */
+async function checkLatency(hosts, timeoutMs) {
+    return Promise.all(hosts.map((h) => measureTcpConnect(h, timeoutMs)));
 }
-function measureTcpConnect(target) {
+function measureTcpConnect(target, timeoutMs) {
+    const label = target.host.includes(':')
+        ? `[${target.host}]:${target.port}`
+        : `${target.host}:${target.port}`;
     return new Promise((resolve) => {
         const start = performance.now();
         const socket = node_net_1.default.connect({ host: target.host, port: target.port });
-        const timeout = setTimeout(() => {
+        const finish = (result) => {
+            clearTimeout(timer);
             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,
-            });
-        });
+            resolve(result);
+        };
+        const timer = setTimeout(() => finish({ target: label, ok: false, timeMs: 0, error: 'Connection timed out' }), timeoutMs);
+        socket.once('connect', () => finish({ target: label, ok: true, timeMs: performance.now() - start }));
+        socket.once('error', (err) => finish({ target: label, ok: false, timeMs: 0, error: err.message }));
     });
 }
 //# sourceMappingURL=checks.js.map

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

@@ -7,10 +7,13 @@ exports.DEFAULTS = {
     // 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'],
+    // 443, not 80: Google's 8.8.8.8 doesn't listen on port 80, so that default
+    // timed out on every poll and pinned the NPC at warning.
     latencyHosts: [
-        { host: '8.8.8.8', port: 80 },
-        { host: '1.1.1.1', port: 80 },
+        { host: '8.8.8.8', port: 443 },
+        { host: '1.1.1.1', port: 443 },
     ],
+    latencyPort: 80,
     slowThreshold: 1000, // ms
     httpTimeout: 5000, // ms
     thresholds: {