@nocville/npc 0.2.2 → 0.3.0

package/README.md

@@ -140,26 +140,64 @@ on your map automatically and despawns when you press Ctrl-C. Once you've run
 #   --debug                  Verbose logging
 ```
 
-| NPC                     | What it does                                       | Example                                                |
-| ----------------------- | -------------------------------------------------- | ------------------------------------------------------ |
-| `system-monitor`        | CPU / memory / disk / load with sparklines         | `nocville-npc system-monitor --cpu-warn=75`            |
-| `internet-connectivity` | DNS, HTTP and TCP latency checks                   | `nocville-npc internet-connectivity`                   |
-| `process-watcher`       | Watches named processes, calls out deaths          | `nocville-npc process-watcher --processes=nginx,redis` |
-| `log-watcher`           | Error bursts in log files, last lines on a monitor | `nocville-npc log-watcher --files=/var/log/app.log`    |
-| `receptionist`          | Time and weather at the entrance, greets players   | `nocville-npc receptionist --location="Berlin"`        |
-| `github-watcher`        | New commits on a commit board                      | `nocville-npc github-watcher --repo=owner/name`        |
-| `web-page-watcher`      | A web page rendered as a pixel-art TV              | `nocville-npc web-page-watcher --url=https://…`        |
-
-Run `nocville-npc --help` to see every flag. A few notes:
-
+| NPC                      | What it does                                               | Example                                                |
+| ------------------------ | ---------------------------------------------------------- | ------------------------------------------------------ |
+| `system-monitor`         | CPU / memory / disk / load with sparklines                 | `nocville-npc system-monitor --cpu-warn=75`            |
+| `internet-connectivity`  | DNS, HTTP and TCP latency checks                           | `nocville-npc internet-connectivity`                   |
+| `process-watcher`        | Watches named processes, calls out deaths                  | `nocville-npc process-watcher --processes=nginx,redis` |
+| `log-watcher`            | Error bursts in log files, last lines on a monitor         | `nocville-npc log-watcher --files=/var/log/app.log`    |
+| `receptionist`           | Lobby greetings, check-ins and front desk jokes            | `nocville-npc receptionist`                            |
+| `security`               | Indoor/outdoor patrols and exterior door watch             | `nocville-npc security`                                |
+| `janitor`                | Mops suspicious spots and complains about bugs everywhere. | `nocville-npc janitor`                                 |
+| `barista`                | Your coffee order is getting a little out of hand.         | `nocville-npc barista`                                 |
+| `office-cat`             | Your desk belongs to the cat now.                          | `nocville-npc office-cat`                              |
+| `office-dog`             | Chief morale officer. Easily distracted.                   | `nocville-npc office-dog`                              |
+| `plant-caretaker`        | Every fern deserves a performance review.                  | `nocville-npc plant-caretaker`                         |
+| `it-technician`          | Have you tried turning it off and on again?                | `nocville-npc it-technician`                           |
+| `out-of-touch-executive` | Big ideas. Long coffee breaks. Your overtime.              | `nocville-npc out-of-touch-executive`                  |
+| `github-watcher`         | New commits on a commit board                              | `nocville-npc github-watcher --repo=owner/name`        |
+| `web-page-watcher`       | A web page rendered as a pixel-art TV                      | `nocville-npc web-page-watcher --url=https://…`        |
+
+Run `nocville-npc --help` to see every flag. Poll intervals below 5 seconds are raised to 5
+seconds. A few notes:
+
+- **system-monitor**: `--disk-path=/data` picks the volume; thresholds are percentages
+  (`--cpu-warn`/`--cpu-crit`, `--mem-…`, `--disk-…`). On macOS, memory counts the file cache as
+  available, like Activity Monitor.
+- **internet-connectivity**: `--dns-hosts`, `--http-urls` (http/https only) and
+  `--latency-hosts` take comma-separated lists; latency targets accept `host:port` or
+  `[ipv6]:port`. `--timeout=<ms>` bounds each check (default 5000).
+- **process-watcher**: matches executable names, so `--processes=python` also finds `python3.11`
+  but `sh` does not match `bash`. Works on macOS and Linux via `ps`, and Windows via
+  PowerShell/CIM performance counters. Windows accepts names with or without `.exe` and
+  reports CPU as a percentage of total machine capacity. Full-path matching is available
+  where the OS reports paths (macOS); use executable names on Windows and Linux.
 - **log-watcher**: `--error-pattern="ERROR|FATAL" --window=300 --error-warn=5 --error-crit=20`.
-- **receptionist**: weather comes from the keyless open-meteo API. Set the place with
-  `--lat=52.5 --lon=13.4` or `--location=…` (otherwise it uses IP geolocation). Add
-  `--fahrenheit` for °F.
-- **github-watcher**: uses ETag polling. Pass `--token=$GITHUB_TOKEN` for a higher rate limit.
+  Files are followed across log rotation and may be created after the watcher starts. Lines
+  shown in the office have anything that looks like a secret (tokens, passwords, keys, URL
+  credentials) redacted, but treat the screen as visible to your whole team.
+- **receptionist**: claims a free desk in a room named Lobby, Reception, Foyer or Entrance
+  (or its assigned work room). Without a desk, uses an open spot. Greets each arrival,
+  checks on a teammate every 2–4 minutes and makes a desk-side joke every 1–2 minutes.
+  No screen, weather requests or geolocation; old weather options are accepted but ignored.
+- **security**: continuously visits rooms and reachable outdoor areas, pausing beside
+  exterior doors for 15–30 seconds. Does not claim a desk. An explicit work-room rule
+  still confines its route, so leave it unassigned for office-wide rounds.
+- **office characters**: `janitor`, `barista`, `office-cat`, `office-dog`,
+  `plant-caretaker`, `it-technician` and `out-of-touch-executive` run without screens or
+  external service credentials. They share the usual API key, name, service ID and map
+  options. Run each as its own process. Their routes and conversation are synchronized by
+  the server, and work-room rules apply. Missing furniture or coworkers cause quiet walks
+  or floor rests instead. The technician's reboots and executive's requests are pretend.
+  Animals have custom walk, sleep and tail animations; staff carry their tools or coffee.
+- **github-watcher**: uses ETag polling. Set `GITHUB_TOKEN` for private repos and a higher rate
+  limit (`--token` also works, but flags are visible to other users in the process list).
+  Without a token it polls every 90 seconds to stay within GitHub's 60 requests per hour.
 - **web-page-watcher**: the pixel-art TV needs `npm i puppeteer-core` and a local
   Chrome/Chromium (`--chrome-path` or `CHROME_PATH`). Without them it falls back to a
-  title/status ticker. Other options: `--mode=auto|screenshot|basic` and `--screen=160x120`.
+  title/status ticker. Other options: `--mode=auto|screenshot|basic` and `--screen=160x120`
+  (up to 320x240). Only `http(s)` URLs are accepted. Chrome runs with its sandbox unless you're
+  root or pass `--no-chrome-sandbox`; only disable it for pages you trust.
 
 ## Programmatic use
 

package/dist/cjs/cli.js

@@ -38,6 +38,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const config_js_1 = require("./core/config.js");
+const errors_js_1 = require("./core/errors.js");
 const logger_js_1 = require("./core/logger.js");
 const session_filter_js_1 = require("./core/session-filter.js");
 // NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
@@ -81,7 +82,15 @@ 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
   github-watcher          Call out new commits on a repo
   web-page-watcher        Render a watched web page as a pixel-art TV
 
@@ -112,17 +121,23 @@ Internet Connectivity Options:
   --poll-interval=<ms>    Poll interval in ms (default: 30000)
   --dns-hosts=<list>      Comma-separated DNS hosts (default: google.com,cloudflare.com)
   --http-urls=<list>      Comma-separated HTTP URLs to check
-  --latency-hosts=<list>  Comma-separated hosts for latency checks
+  --latency-hosts=<list>  Comma-separated TCP latency targets: host, host:port or
+                          [ipv6]:port (default: 8.8.8.8:443,1.1.1.1:443;
+                          port 80 when omitted)
   --slow-threshold=<ms>   Slow response threshold in ms (default: 1000)
+  --timeout=<ms>          Per-check timeout in ms (default: 5000)
 
 Process Watcher Options:
   --poll-interval=<ms>    Poll interval in ms (default: 15000)
-  --processes=<list>      Comma-separated process names to watch
+  --processes=<list>      Comma-separated executable names to watch (python
+                          also matches python3.11; a /path matches exactly)
   --cpu-warn=<n>          CPU warning threshold % (default: 80)
   --mem-warn=<n>          Memory warning threshold MB (default: 500)
 
 Log Watcher Options:
-  --files=<list>          Comma-separated log file paths
+  --files=<list>          Comma-separated log file paths (followed across
+                          rotation; files may appear later). Lines shown on
+                          the screen have secrets redacted.
   --error-pattern=<regex> Error pattern (default: ERROR|FATAL)
   --warning-pattern=<regex> Warning pattern (default: WARN)
   --window=<seconds>      Sliding window in seconds (default: 300)
@@ -130,26 +145,28 @@ 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 (else IP geo)
-  --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)
   --branch=<name>         Branch to watch (default: repo default branch)
-  --token=<token>         GitHub token (or GITHUB_TOKEN env)
-  --poll-interval=<ms>    Poll interval in ms (default: 60000)
+  --token=<token>         GitHub token (prefer the GITHUB_TOKEN env: flags are
+                          visible in the process list)
+  --poll-interval=<ms>    Poll interval in ms (default: 60000 with a token,
+                          90000 without, to stay under GitHub's 60/hour)
 
 Web Page Watcher Options:
-  --url=<url>             Page to watch (required)
+  --url=<url>             http(s) page to watch (required)
   --mode=<auto|screenshot|basic>  Render mode (default: auto)
   --interval=<ms>         Poll interval in ms (default: 60000, floor 15000)
-  --viewport=<WxH>        Browser viewport (default: screen x 8)
-  --screen=<WxH>          TV pixel resolution (default: 160x120; e.g. 160x100)
-  --wait-until=<event>    Puppeteer waitUntil (default: networkidle2)
+  --viewport=<WxH>        Browser viewport (default: screen x 8, max 4096x4096)
+  --screen=<WxH>          TV pixel resolution (default: 160x120, max 320x240)
+  --wait-until=<event>    load, domcontentloaded, networkidle0 or networkidle2
+                          (default: networkidle2)
   --chrome-path=<path>    Chrome executable (or CHROME_PATH env)
+  --no-chrome-sandbox     Run Chrome without its sandbox (only for trusted
+                          pages; automatic when running as root)
   (needs puppeteer-core + Chrome for the pixel-art TV; falls back to basic)
 `.trim();
 async function main() {
@@ -310,18 +327,10 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'internet-connectivity';
             }
-            const dnsHosts = (0, config_js_1.stringFlag)(parsed.flags, 'dns-hosts')?.split(',');
-            const httpUrls = (0, config_js_1.stringFlag)(parsed.flags, 'http-urls')?.split(',');
-            const latencyHostsRaw = (0, config_js_1.stringFlag)(parsed.flags, 'latency-hosts')?.split(',');
-            const latencyHosts = latencyHostsRaw?.map((h) => ({ host: h.trim(), port: 80 }));
             const { InternetConnectivityNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/internet-connectivity/index.js')));
             const npc = new InternetConnectivityNPC({
                 ...config,
-                pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
-                dnsHosts,
-                httpUrls,
-                latencyHosts,
-                slowThreshold: (0, config_js_1.numberFlag)(parsed.flags, 'slow-threshold'),
+                ...InternetConnectivityNPC.configFromFlags(parsed.flags),
             });
             logger.info('Starting internet-connectivity NPC');
             await npc.start();
@@ -331,8 +340,8 @@ async function main() {
             if (!config.serviceId) {
                 config.serviceId = 'process-watcher';
             }
-            const processesStr = (0, config_js_1.stringFlag)(parsed.flags, 'processes');
-            if (!processesStr) {
+            const processes = (0, config_js_1.listFlag)(parsed.flags, 'processes');
+            if (!processes) {
                 console.error('Error: --processes is required (comma-separated list)');
                 process.exit(1);
             }
@@ -340,7 +349,7 @@ async function main() {
             const npc = new ProcessWatcherNPC({
                 ...config,
                 pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
-                processes: processesStr.split(','),
+                processes,
                 cpuWarn: (0, config_js_1.numberFlag)(parsed.flags, 'cpu-warn'),
                 memWarn: (0, config_js_1.numberFlag)(parsed.flags, 'mem-warn'),
             });
@@ -349,8 +358,8 @@ async function main() {
             break;
         }
         case 'log-watcher': {
-            const filesStr = (0, config_js_1.stringFlag)(parsed.flags, 'files');
-            if (!filesStr) {
+            const files = (0, config_js_1.listFlag)(parsed.flags, 'files');
+            if (!files) {
                 console.error('Error: --files is required (comma-separated list)');
                 process.exit(1);
             }
@@ -360,7 +369,7 @@ async function main() {
             const { LogWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/log-watcher/index.js')));
             const npc = new LogWatcherNPC({
                 ...config,
-                files: filesStr.split(','),
+                files,
                 errorPattern: (0, config_js_1.stringFlag)(parsed.flags, 'error-pattern'),
                 warningPattern: (0, config_js_1.stringFlag)(parsed.flags, 'warning-pattern'),
                 windowSeconds: (0, config_js_1.numberFlag)(parsed.flags, 'window'),
@@ -384,11 +393,43 @@ async function main() {
                 lon: (0, config_js_1.numberFlag)(parsed.flags, 'lon'),
                 location: (0, config_js_1.stringFlag)(parsed.flags, 'location'),
                 fahrenheit: (0, config_js_1.boolFlag)(parsed.flags, 'fahrenheit') ?? false,
+                ipGeo: (0, config_js_1.boolFlag)(parsed.flags, 'no-ip-geo') !== true,
             });
             logger.info('Starting receptionist NPC');
             await npc.start();
             break;
         }
+        case 'security': {
+            if (!config.serviceId)
+                config.serviceId = 'security';
+            const { SecurityNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/security/index.js')));
+            const npc = new SecurityNPC({
+                ...config,
+                pollInterval: (0, config_js_1.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': {
+            if (!config.serviceId)
+                config.serviceId = parsed.command;
+            const { OFFICE_CHARACTER_NPCS } = await Promise.resolve().then(() => __importStar(require('./npcs/office-characters/index.js')));
+            const NPCClass = OFFICE_CHARACTER_NPCS[parsed.command];
+            const npc = new NPCClass({
+                ...config,
+                pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
+            });
+            logger.info(`Starting ${parsed.command} NPC`);
+            await npc.start();
+            break;
+        }
         case 'github-watcher': {
             const repo = (0, config_js_1.stringFlag)(parsed.flags, 'repo');
             if (!repo) {
@@ -400,11 +441,15 @@ async function main() {
                 config.serviceId = `github-${shortName.replace(/[^a-zA-Z0-9_-]/g, '-')}`.slice(0, 100);
             }
             const { GitHubWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/github-watcher/index.js')));
+            const tokenFlag = (0, config_js_1.stringFlag)(parsed.flags, 'token');
+            if (tokenFlag) {
+                logger.warn('--token is visible to other local users in the process list; prefer GITHUB_TOKEN');
+            }
             const npc = new GitHubWatcherNPC({
                 ...config,
                 repo,
                 branch: (0, config_js_1.stringFlag)(parsed.flags, 'branch'),
-                token: (0, config_js_1.stringFlag)(parsed.flags, 'token') ?? process.env['GITHUB_TOKEN'],
+                token: tokenFlag ?? process.env['GITHUB_TOKEN'],
                 pollInterval: (0, config_js_1.numberFlag)(parsed.flags, 'poll-interval'),
             });
             logger.info('Starting github-watcher NPC');
@@ -420,22 +465,28 @@ async function main() {
             const { hostnameOf } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/basic-mode.js')));
             const { parseDimensions } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/defaults.js')));
             const { WebPageWatcherNPC } = await Promise.resolve().then(() => __importStar(require('./npcs/web-page-watcher/index.js')));
-            const parseWxH = (v) => v ? (parseDimensions(v) ?? undefined) : undefined;
+            const parseWxH = (flag) => {
+                const v = (0, config_js_1.stringFlag)(parsed.flags, flag);
+                if (v === undefined)
+                    return undefined;
+                const dims = parseDimensions(v);
+                if (!dims)
+                    throw new errors_js_1.NpcConfigError(`--${flag} must look like 160x120`);
+                return dims;
+            };
             if (!config.serviceId) {
                 config.serviceId = `webpage-${hostnameOf(url)}`
                     .replace(/[^a-zA-Z0-9_.-]/g, '-')
                     .slice(0, 100);
             }
-            const modeFlag = (0, config_js_1.stringFlag)(parsed.flags, 'mode');
-            const mode = modeFlag === 'auto' || modeFlag === 'screenshot' || modeFlag === 'basic'
-                ? modeFlag
-                : undefined;
-            const viewport = parseWxH((0, config_js_1.stringFlag)(parsed.flags, 'viewport'));
-            const screen = parseWxH((0, config_js_1.stringFlag)(parsed.flags, 'screen'));
+            const viewport = parseWxH('viewport');
+            const screen = parseWxH('screen');
             const npc = new WebPageWatcherNPC({
                 ...config,
                 url,
-                mode,
+                // Validated (with a clear error) by the constructor.
+                mode: (0, config_js_1.stringFlag)(parsed.flags, 'mode'),
+                chromeSandbox: (0, config_js_1.boolFlag)(parsed.flags, 'no-chrome-sandbox') !== true,
                 chromePath: (0, config_js_1.stringFlag)(parsed.flags, 'chrome-path'),
                 waitUntil: (0, config_js_1.stringFlag)(parsed.flags, 'wait-until'),
                 viewportWidth: viewport?.width,
@@ -578,6 +629,10 @@ main().catch((err) => {
         process.stdout.write('{}\n');
         return;
     }
+    if (err instanceof errors_js_1.NpcConfigError) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     console.error('Fatal error:', err);
     process.exit(1);
 });

package/dist/cjs/core/base-npc.js

@@ -42,6 +42,13 @@ class BaseNPC {
         const name = this.displayName;
         return name ? (0, text_js_1.truncate)(name, 32) : undefined;
     }
+    /**
+     * NPC type sent as the push `kind` (groups NPCs for per-type rules such as "all process
+     * watchers work in the Server Room"). Defaults to `name` when it is a valid slug.
+     */
+    get kind() {
+        return /^[a-z0-9][a-z0-9-]{0,39}$/.test(this.name) ? this.name : undefined;
+    }
     /** NPC archetype — steers movement speed and default behavior. Override per NPC. */
     get archetype() {
         return 'service';
@@ -116,6 +123,7 @@ class BaseNPC {
             message: metrics.message ? (0, text_js_1.truncate)(metrics.message, 500) : undefined,
             metrics: metrics.metrics,
             archetype: this.archetype,
+            kind: this.kind,
             subStatus: metrics.subStatus,
             screenData: metrics.screenData,
             behavior: Object.keys(behavior).length > 0 ? behavior : undefined,
@@ -123,6 +131,13 @@ 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/cjs/core/config.js

@@ -4,6 +4,7 @@ exports.parseArgs = parseArgs;
 exports.resolveConfig = resolveConfig;
 exports.stringFlag = stringFlag;
 exports.boolFlag = boolFlag;
+exports.listFlag = listFlag;
 exports.numberFlag = numberFlag;
 const user_config_js_1 = require("./user-config.js");
 /**
@@ -96,11 +97,27 @@ function boolFlag(flags, key) {
         return false;
     return undefined;
 }
+/**
+ * A comma-separated list flag (`--processes=nginx,redis`): entries trimmed,
+ * empties dropped, duplicates removed. Undefined when the flag is absent or empty.
+ */
+function listFlag(flags, key) {
+    const raw = stringFlag(flags, key);
+    if (raw === undefined)
+        return undefined;
+    const items = [
+        ...new Set(raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)),
+    ];
+    return items.length > 0 ? items : undefined;
+}
 function numberFlag(flags, key) {
     const val = flags[key];
-    if (typeof val === 'string') {
+    if (typeof val === 'string' && val.trim() !== '') {
         const n = Number(val);
-        if (!Number.isNaN(n))
+        if (Number.isFinite(n))
             return n;
     }
     return undefined;

package/dist/cjs/core/errors.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NpcConfigError = void 0;
+exports.assertPosix = assertPosix;
+/**
+ * A user-facing configuration problem (bad flag value, unsupported platform).
+ * The CLI prints only its message and exits 1 — no stack trace — so throw it
+ * for anything the user can fix by changing how they run the NPC.
+ */
+class NpcConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NpcConfigError';
+    }
+}
+exports.NpcConfigError = NpcConfigError;
+/** Throw an NpcConfigError on Windows, for NPCs that rely on POSIX tools or paths. */
+function assertPosix(npcName, hint) {
+    if (process.platform === 'win32') {
+        throw new NpcConfigError(`${npcName} is not supported on Windows. ${hint}`);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/cjs/core/http.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Small, bounded HTTP helpers for NPCs that read untrusted remote content
+ * (weather/geo APIs, GitHub, watched web pages). Every call has a timeout and
+ * every body read has a byte cap, so a slow or hostile server can neither hang
+ * a collection nor balloon memory.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_BODY_BYTES = exports.NPC_USER_AGENT = void 0;
+exports.isHttpUrl = isHttpUrl;
+exports.displayUrl = displayUrl;
+exports.readTextCapped = readTextCapped;
+exports.discardBody = discardBody;
+exports.fetchJson = fetchJson;
+exports.asRecord = asRecord;
+exports.finiteNumber = finiteNumber;
+/** The `User-Agent` sent by every NPC request. */
+exports.NPC_USER_AGENT = 'nocville-npc';
+/** Default cap for a response body read into memory. */
+exports.DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+/** True for an absolute http(s) URL (anything else — file:, data:, javascript: — is refused). */
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/** A URL rendered for logs/screens: scheme, host and path only — never credentials or query. */
+function displayUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.protocol}//${url.host}${url.pathname === '/' ? '' : url.pathname}`;
+    }
+    catch {
+        return '(invalid url)';
+    }
+}
+/**
+ * Read a response body as UTF-8, keeping at most `maxBytes`. Streams when the
+ * body is available (cancelling the rest); otherwise falls back to `text()`
+ * after rejecting an oversized declared Content-Length. Returns the (possibly
+ * truncated) text and whether it was truncated.
+ */
+async function readTextCapped(res, maxBytes = exports.DEFAULT_MAX_BODY_BYTES) {
+    const reader = res.body?.getReader();
+    if (!reader) {
+        const declared = Number(res.headers?.get('content-length') ?? NaN);
+        if (Number.isFinite(declared) && declared > maxBytes)
+            return { text: '', truncated: true };
+        const text = await res.text();
+        return text.length > maxBytes
+            ? { text: text.slice(0, maxBytes), truncated: true }
+            : { text, truncated: false };
+    }
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (total + value.byteLength > maxBytes) {
+                chunks.push(value.subarray(0, maxBytes - total));
+                total = maxBytes;
+                truncated = true;
+                break;
+            }
+            chunks.push(value);
+            total += value.byteLength;
+        }
+    }
+    finally {
+        if (truncated)
+            await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+    return { text: new TextDecoder().decode(Buffer.concat(chunks)), truncated };
+}
+/** Discard a response body without reading it (frees the connection). */
+async function discardBody(res) {
+    await res.body?.cancel().catch(() => undefined);
+}
+/**
+ * GET a JSON document with a timeout and size cap. Returns null on any network
+ * error, non-2xx status, oversized body or malformed JSON — callers degrade
+ * gracefully rather than throw.
+ */
+async function fetchJson(url, opts) {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(opts.timeoutMs),
+            headers: { 'User-Agent': exports.NPC_USER_AGENT, Accept: 'application/json', ...opts.headers },
+        });
+        if (!res.ok) {
+            await discardBody(res);
+            return null;
+        }
+        const { text, truncated } = await readTextCapped(res, opts.maxBytes ?? 256 * 1024);
+        if (truncated)
+            return null;
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** Narrow an unknown JSON value to a plain object (arrays and null excluded). */
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** A finite number from an unknown JSON value, else null. */
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+//# sourceMappingURL=http.js.map