@nocville/npc 0.2.1 → 0.2.3

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

@@ -1,102 +1,139 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidRepo = isValidRepo;
 exports.fetchDefaultBranch = fetchDefaultBranch;
 exports.fetchCommits = fetchCommits;
+exports.parseCommit = parseCommit;
 exports.commitsWithin = commitsWithin;
 exports.newCommitsSince = newCommitsSince;
+const http_js_1 = require("../../core/http.js");
+const text_js_1 = require("../../core/text.js");
+/** Largest GitHub API response we read (10 commits are ~30-60 KB). */
+const MAX_BODY_BYTES = 512 * 1024;
+// GitHub owner and repository names: letters, digits, '-', '_' and '.'.
+const REPO_RE = /^([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100})$/;
+/**
+ * Validate an "owner/name" repository slug. It is interpolated into the API
+ * URL path, so anything else (`../`, extra segments, query characters) is
+ * rejected rather than letting it — and the token — reach another endpoint.
+ */
+function isValidRepo(repo) {
+    const m = repo.match(REPO_RE);
+    return !!m && m[2] !== '.' && m[2] !== '..';
+}
 function toNum(v) {
-    if (v === null)
+    if (v === null || v.trim() === '')
         return null;
     const n = Number(v);
-    return Number.isNaN(n) ? null : n;
+    return Number.isFinite(n) ? n : null;
 }
 function ghHeaders(opts) {
     const headers = {
         Accept: 'application/vnd.github+json',
-        'User-Agent': 'nocville-npc',
+        'User-Agent': http_js_1.NPC_USER_AGENT,
         'X-GitHub-Api-Version': '2022-11-28',
     };
     if (opts.token)
         headers['Authorization'] = `Bearer ${opts.token}`;
     return headers;
 }
+function doFetchFn(opts) {
+    return opts.fetchFn ?? globalThis.fetch;
+}
+async function readJson(res) {
+    const { text, truncated } = await (0, http_js_1.readTextCapped)(res, MAX_BODY_BYTES);
+    if (truncated)
+        throw new Error('response too large');
+    return JSON.parse(text);
+}
 /** Look up a repo's default branch (one call at startup). Null on failure. */
 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}`, {
+        const res = await doFetchFn(opts)(`https://api.github.com/repos/${repo}`, {
             headers: ghHeaders(opts),
-            signal: controller.signal,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
         });
         if (!res.ok)
             return null;
-        const body = (await res.json());
-        return body.default_branch ?? null;
+        const branch = (0, http_js_1.asRecord)(await readJson(res))?.['default_branch'];
+        return typeof branch === 'string' && branch.length > 0 && branch.length <= 255
+            ? (0, text_js_1.sanitizeText)(branch, 255)
+            : 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`.
+ * Passing the previous ETag yields a cheap 304 when nothing has changed (free
+ * of the rate limit for authenticated requests). Never throws — network
+ * errors and unreadable bodies surface as `status: 0`.
  */
 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);
+    const failed = {
+        notModified: false,
+        commits: [],
+        etag: null,
+        rateRemaining: null,
+        rateResetAt: null,
+        status: 0,
+    };
     try {
-        const res = await doFetch(url, { headers, signal: controller.signal });
+        const res = await doFetchFn(opts)(url, {
+            headers,
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
+        });
         const rateRemaining = toNum(res.headers.get('x-ratelimit-remaining'));
+        const resetSecs = toNum(res.headers.get('x-ratelimit-reset'));
+        const rateResetAt = resetSecs === null ? null : resetSecs * 1000;
         const etag = res.headers.get('etag');
+        const meta = { rateRemaining, rateResetAt, status: res.status };
         if (res.status === 304) {
-            return {
-                notModified: true,
-                commits: [],
-                etag: opts.etag ?? null,
-                rateRemaining,
-                status: 304,
-            };
+            return { ...meta, notModified: true, commits: [], etag: opts.etag ?? null };
         }
         if (!res.ok) {
-            await res.text().catch(() => undefined);
-            return { notModified: false, commits: [], etag, rateRemaining, status: res.status };
+            await res.body?.cancel().catch(() => undefined);
+            return { ...meta, notModified: false, commits: [], etag };
         }
-        const body = (await res.json());
-        const commits = body.map((c) => parseCommit(c));
-        return { notModified: false, commits, etag, rateRemaining, status: res.status };
+        const body = await readJson(res);
+        if (!Array.isArray(body))
+            return failed;
+        const commits = body.map(parseCommit).filter((c) => c !== null);
+        return { ...meta, notModified: false, commits, etag };
     }
     catch {
-        return { notModified: false, commits: [], etag: null, rateRemaining: null, status: 0 };
-    }
-    finally {
-        clearTimeout(timer);
+        return failed;
     }
 }
-function parseCommit(c) {
-    const commit = c['commit'] ?? {};
-    const commitAuthor = commit['author'] ?? {};
-    const ghAuthor = c['author'] ?? {};
-    const message = String(commit['message'] ?? '').split('\n')[0] ?? '';
+/**
+ * Extract the displayed fields from one (untrusted) commit object: a hex sha,
+ * the subject line and author name with control/bidi characters removed and
+ * lengths capped. Null for anything without a valid sha.
+ */
+function parseCommit(raw) {
+    const c = (0, http_js_1.asRecord)(raw);
+    const sha = c?.['sha'];
+    if (typeof sha !== 'string' || !/^[0-9a-f]{7,64}$/i.test(sha))
+        return null;
+    const commit = (0, http_js_1.asRecord)(c['commit']) ?? {};
+    const commitAuthor = (0, http_js_1.asRecord)(commit['author']) ?? {};
+    const ghAuthor = (0, http_js_1.asRecord)(c['author']) ?? {};
+    const str = (v) => (typeof v === 'string' && v.trim() ? v : null);
+    const message = str(commit['message'])?.split('\n')[0] ?? '';
+    const date = str(commitAuthor['date']) ?? '';
     return {
-        sha: String(c['sha'] ?? ''),
-        author: String(commitAuthor['name'] ?? ghAuthor['login'] ?? 'unknown'),
-        message,
-        date: String(commitAuthor['date'] ?? ''),
+        sha: sha.toLowerCase(),
+        author: (0, text_js_1.sanitizeText)(str(commitAuthor['name']) ?? str(ghAuthor['login']) ?? 'unknown', 40),
+        message: (0, text_js_1.sanitizeText)(message, 200),
+        date: Number.isFinite(Date.parse(date)) ? date : '',
     };
 }
 /** Count how many commits landed within the last `hours`. */

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: {