@nocville/npc 0.2.1 → 0.2.3

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

@@ -1,6 +1,7 @@
 import { PollingNPC } from '../../core/polling-npc.js';
-import { worstStatus } from '../../core/thresholds.js';
-import { pushHistory } from '../../core/screen.js';
+import { evaluateThreshold, worstStatus, moodForStatus } from '../../core/thresholds.js';
+import { statusColor, pushHistory } from '../../core/screen.js';
+import { NpcConfigError, assertPosix } from '../../core/errors.js';
 import { scanProcesses, detectTransitions } from './process-scanner.js';
 import { DEFAULTS } from './defaults.js';
 /** Max per-process panels on the companion dashboard. */
@@ -12,14 +13,17 @@ export class ProcessWatcherNPC extends PollingNPC {
     cpuHistories = new Map();
     previousRunning = null;
     constructor(config) {
-        if (process.platform === 'win32') {
-            throw new Error('process-watcher is not supported on Windows (relies on the POSIX `ps` command). ' +
-                'Run it under WSL/Linux, or use system-monitor instead.');
-        }
+        assertPosix('process-watcher', 'It relies on the POSIX `ps` command; run it under WSL/Linux, or use system-monitor instead.');
         super(config);
-        this.processes = config.processes;
+        this.processes = [...new Set(config.processes.map((p) => p.trim()).filter(Boolean))];
+        if (this.processes.length === 0) {
+            throw new NpcConfigError('process-watcher needs at least one process name (--processes)');
+        }
         this.cpuWarn = config.cpuWarn ?? DEFAULTS.cpuWarn;
         this.memWarn = config.memWarn ?? DEFAULTS.memWarn;
+        if (!(this.cpuWarn > 0) || !(this.memWarn > 0)) {
+            throw new NpcConfigError('--cpu-warn and --mem-warn must be positive numbers');
+        }
     }
     get name() {
         return 'process-watcher';
@@ -30,9 +34,6 @@ export class ProcessWatcherNPC extends PollingNPC {
     get archetype() {
         return 'service';
     }
-    get heartbeatSeconds() {
-        return 30;
-    }
     get companion() {
         return {
             screenType: 'dashboard-wall',
@@ -42,22 +43,28 @@ export class ProcessWatcherNPC extends PollingNPC {
         };
     }
     async collect() {
-        const infos = await scanProcesses(this.processes);
+        let infos;
+        try {
+            infos = await scanProcesses(this.processes);
+        }
+        catch (err) {
+            // Not knowing is different from "everything died": report unknown and
+            // leave the transition baseline alone so recovery doesn't say "is back".
+            return this.scanFailed(err);
+        }
         const statuses = [];
-        const messageParts = [];
+        const problems = [];
         const metrics = {};
         const panels = [];
         let totalRunning = 0;
-        let totalMissing = 0;
         for (const info of infos) {
             const safeKey = info.name.replace(/[^a-zA-Z0-9_]/g, '_');
             if (!info.running) {
                 statuses.push('critical');
-                messageParts.push(`${info.name}: NOT FOUND`);
+                problems.push(`${info.name} DOWN`);
                 metrics[`${safeKey}_running`] = 0;
                 metrics[`${safeKey}_cpu`] = 0;
                 metrics[`${safeKey}_mem_mb`] = 0;
-                totalMissing++;
                 if (panels.length < MAX_PANELS) {
                     panels.push({ label: info.name, value: 'DOWN', color: 'red' });
                 }
@@ -65,72 +72,75 @@ export class ProcessWatcherNPC extends PollingNPC {
             }
             totalRunning++;
             const cpu = info.cpuPercent ?? 0;
+            const memMb = info.memMb ?? 0;
             metrics[`${safeKey}_running`] = 1;
             metrics[`${safeKey}_cpu`] = cpu;
-            metrics[`${safeKey}_mem_mb`] = info.memMb ?? 0;
+            metrics[`${safeKey}_mem_mb`] = memMb;
             const history = this.cpuHistories.get(info.name) ?? [];
             pushHistory(history, cpu);
             this.cpuHistories.set(info.name, history);
-            const cpuHigh = cpu >= this.cpuWarn;
-            const memHigh = (info.memMb ?? 0) >= this.memWarn;
-            if (cpuHigh || memHigh) {
-                statuses.push('warning');
-                const warnings = [];
-                if (cpuHigh)
-                    warnings.push(`cpu=${cpu}%`);
-                if (memHigh)
-                    warnings.push(`mem=${info.memMb}MB`);
-                messageParts.push(`${info.name}: WARN (${warnings.join(', ')})`);
-            }
-            else {
-                statuses.push('healthy');
-                messageParts.push(`${info.name}: OK`);
+            // Single warning thresholds: no critical level for resource use.
+            const cpuStatus = evaluateThreshold(cpu, { warning: this.cpuWarn, critical: Infinity });
+            const memStatus = evaluateThreshold(memMb, { warning: this.memWarn, critical: Infinity });
+            const status = worstStatus([cpuStatus, memStatus]);
+            statuses.push(status);
+            if (status !== 'healthy') {
+                const high = [];
+                if (cpuStatus !== 'healthy')
+                    high.push(`cpu ${cpu}%`);
+                if (memStatus !== 'healthy')
+                    high.push(`mem ${Math.round(memMb)}MB`);
+                problems.push(`${info.name} high ${high.join(', ')}`);
             }
             if (panels.length < MAX_PANELS) {
                 panels.push({
                     label: info.name,
                     value: `${cpu}%`,
-                    color: cpuHigh || memHigh ? 'amber' : 'green',
+                    color: statusColor(status),
                     sparkline: [...history],
                 });
             }
         }
+        const totalMissing = infos.length - totalRunning;
         metrics['total_watched'] = this.processes.length;
         metrics['total_running'] = totalRunning;
         metrics['total_missing'] = totalMissing;
         // Transition speech: compare the running set to last poll's. On the first
         // poll we only seed the set (no bogus "is back" for already-running procs).
         const currentRunning = new Set(infos.filter((i) => i.running).map((i) => i.name));
-        let transitions = [];
-        if (this.previousRunning !== null) {
-            transitions = detectTransitions(this.previousRunning, currentRunning);
-        }
+        const transitions = this.previousRunning === null ? [] : detectTransitions(this.previousRunning, currentRunning);
         this.previousRunning = currentRunning;
         const status = worstStatus(statuses);
-        const mood = deriveMood(status);
-        // A death message takes over the bubble this cycle so it reads as an alert.
-        const message = transitions.length > 0 ? transitions.join(' · ') : messageParts.join(' | ');
-        const screenData = { layout: 'multi-metric', values: panels };
+        const summary = problems.length === 0
+            ? `All ${infos.length} running`
+            : `${totalRunning}/${infos.length} running · ${problems.join(' · ')}`;
+        // A death/return takes over the bubble this cycle so it reads as an alert.
+        const message = transitions.length > 0 ? transitions.join(' · ') : summary;
         return {
             status,
-            mood,
+            mood: moodForStatus(status),
             message,
             subStatus: totalMissing > 0 ? 'process-down' : undefined,
-            screenData,
+            screenData: { layout: 'multi-metric', values: panels },
             metrics,
         };
     }
-}
-function deriveMood(status) {
-    switch (status) {
-        case 'healthy':
-            return 'happy';
-        case 'warning':
-            return 'concerned';
-        case 'critical':
-            return 'stressed';
-        default:
-            return 'idle';
+    scanFailed(err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        this.logger.warn('Cannot list processes', { error: reason });
+        return {
+            status: 'unknown',
+            mood: moodForStatus('unknown'),
+            message: 'Cannot list processes (ps failed)',
+            subStatus: 'scan-failed',
+            screenData: {
+                layout: 'multi-metric',
+                values: this.processes
+                    .slice(0, MAX_PANELS)
+                    .map((name) => ({ label: name, value: '?', color: 'gray' })),
+            },
+            metrics: { total_watched: this.processes.length },
+        };
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/npcs/process-watcher/process-scanner.d.ts

@@ -2,6 +2,8 @@ export interface ProcessInfo {
     name: string;
     running: boolean;
     pid?: number;
+    /** Instances matched (all are summed into cpu/mem). */
+    count?: number;
     cpuPercent?: number;
     memMb?: number;
 }
@@ -11,9 +13,35 @@ export interface ProcessInfo {
  * "<name> is back" when one returns.
  */
 export declare function detectTransitions(prev: Set<string>, curr: Set<string>): string[];
+export interface PsEntry {
+    pid: number;
+    cpu: number;
+    memKb: number;
+    /** Executable name (Linux) or path (macOS); may contain spaces. */
+    comm: string;
+}
+/**
+ * Parse header-less `ps -eo pid=,pcpu=,rss=,comm=` output. COMMAND is the rest
+ * of the line, so macOS paths with spaces ("Google Chrome") survive intact.
+ */
+export declare function parsePsOutput(stdout: string): PsEntry[];
+/**
+ * Does a ps COMMAND entry match a watched name? Case-insensitive on the
+ * executable's basename:
+ * - exact: `nginx` matches `/usr/sbin/nginx`;
+ * - version suffix: `python` matches `python3` and `python3.11`;
+ * - Linux truncation: a name longer than 15 chars matches its 15-char prefix;
+ * - a name containing `/` must equal the full path (macOS reports paths).
+ * Unlike a substring match, `sh` does not match `bash` or `ssh-agent`.
+ */
+export declare function matchesName(comm: string, searchName: string): boolean;
+/** List every process. Throws if `ps` fails — callers must not read that as "all dead". */
+export declare function listProcesses(): Promise<PsEntry[]>;
+/** Summarise each watched name against a process list (CPU and memory summed per name). */
+export declare function matchProcesses(names: string[], entries: PsEntry[]): ProcessInfo[];
 /**
  * Scan for processes by name and return their status and resource usage.
- * Works on macOS and Linux by using `ps` to list all processes.
+ * Works on macOS and Linux via `ps`. Throws when the process list is unavailable.
  */
 export declare function scanProcesses(names: string[]): Promise<ProcessInfo[]>;
 //# sourceMappingURL=process-scanner.d.ts.map

package/dist/npcs/process-watcher/process-scanner.js

@@ -1,6 +1,11 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
+/** Bounds on the `ps` call: a wedged or enormous process table can't stall or flood us. */
+const PS_TIMEOUT_MS = 5000;
+const PS_MAX_BUFFER = 16 * 1024 * 1024;
+/** Linux truncates `comm` to 15 characters (TASK_COMM_LEN - 1). */
+const LINUX_COMM_LEN = 15;
 /**
  * Compare the previous and current running-process sets and return speech
  * strings for any transitions: "<name> died!" when a process disappears and
@@ -19,92 +24,77 @@ export function detectTransitions(prev, curr) {
     return messages;
 }
 /**
- * Parse the output of `ps` into structured entries.
- * Expects columns: PID, %CPU, RSS (KB), COMMAND
+ * Parse header-less `ps -eo pid=,pcpu=,rss=,comm=` output. COMMAND is the rest
+ * of the line, so macOS paths with spaces ("Google Chrome") survive intact.
  */
-function parsePsOutput(stdout) {
-    const lines = stdout.trim().split('\n');
-    // Skip the header line
+export function parsePsOutput(stdout) {
     const entries = [];
-    for (let i = 1; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (!line)
+    for (const line of stdout.split('\n')) {
+        const m = line.match(/^\s*(\d+)\s+([\d.]+)\s+(\d+)\s+(.+?)\s*$/);
+        if (!m)
             continue;
-        // Fields are whitespace-separated: PID, %CPU, RSS, COMMAND (may contain spaces)
-        const parts = line.split(/\s+/);
-        if (parts.length < 4)
-            continue;
-        const pid = parseInt(parts[0], 10);
-        const cpu = parseFloat(parts[1]);
-        const memKb = parseInt(parts[2], 10);
-        // COMMAND is everything from the 4th column onward
-        const comm = parts.slice(3).join(' ');
-        if (Number.isNaN(pid) || Number.isNaN(cpu) || Number.isNaN(memKb))
-            continue;
-        entries.push({ pid, cpu, memKb, comm });
+        entries.push({
+            pid: Number(m[1]),
+            cpu: Number(m[2]),
+            memKb: Number(m[3]),
+            comm: m[4],
+        });
     }
     return entries;
 }
 /**
- * Match a process name against a ps COMMAND column.
- * Matches if the basename of the command path equals the search name,
- * or if the command contains the search name.
+ * Does a ps COMMAND entry match a watched name? Case-insensitive on the
+ * executable's basename:
+ * - exact: `nginx` matches `/usr/sbin/nginx`;
+ * - version suffix: `python` matches `python3` and `python3.11`;
+ * - Linux truncation: a name longer than 15 chars matches its 15-char prefix;
+ * - a name containing `/` must equal the full path (macOS reports paths).
+ * Unlike a substring match, `sh` does not match `bash` or `ssh-agent`.
  */
-function matchesName(comm, searchName) {
-    // Get the basename of the command (strip path and arguments)
-    const basename = comm.split('/').pop()?.split(/\s/)[0] ?? '';
-    if (basename === searchName)
+export function matchesName(comm, searchName) {
+    if (searchName.includes('/'))
+        return comm === searchName;
+    const base = (comm.split('/').pop() ?? comm).toLowerCase();
+    const name = searchName.toLowerCase();
+    if (base === name)
         return true;
-    // Also check if the full command string contains the name
-    // (handles cases like "python my-script.py" when searching for "python")
-    return comm.toLowerCase().includes(searchName.toLowerCase());
+    if (name.length > LINUX_COMM_LEN && base === name.slice(0, LINUX_COMM_LEN))
+        return true;
+    return base.startsWith(name) && /^\d[\d.]*$/.test(base.slice(name.length));
 }
-/**
- * Scan for processes by name and return their status and resource usage.
- * Works on macOS and Linux by using `ps` to list all processes.
- */
-export async function scanProcesses(names) {
-    let psArgs;
-    if (process.platform === 'darwin') {
-        // macOS: -e selects all processes, -o specifies output columns
-        psArgs = ['-eo', 'pid,pcpu,rss,comm'];
-    }
-    else {
-        // Linux: -eo with similar columns
-        psArgs = ['-eo', 'pid,pcpu,rss,comm'];
-    }
-    let entries;
-    try {
-        const { stdout } = await execFileAsync('ps', psArgs);
-        entries = parsePsOutput(stdout);
-    }
-    catch {
-        // If ps fails, report all processes as unknown / not running
-        return names.map((name) => ({ name, running: false }));
-    }
-    const results = [];
-    for (const name of names) {
-        // Find all matching entries for this process name
+/** List every process. Throws if `ps` fails — callers must not read that as "all dead". */
+export async function listProcesses() {
+    const { stdout } = await execFileAsync('ps', ['-eo', 'pid=,pcpu=,rss=,comm='], {
+        timeout: PS_TIMEOUT_MS,
+        maxBuffer: PS_MAX_BUFFER,
+        // Some locales print %CPU with a decimal comma ("1,5"); force "1.5".
+        env: { ...process.env, LC_ALL: 'C' },
+    });
+    return parsePsOutput(stdout);
+}
+/** Summarise each watched name against a process list (CPU and memory summed per name). */
+export function matchProcesses(names, entries) {
+    return names.map((name) => {
         const matching = entries.filter((e) => matchesName(e.comm, name));
-        if (matching.length === 0) {
-            results.push({ name, running: false });
-            continue;
-        }
-        // Aggregate: take the first matching PID, sum CPU and memory across all instances
-        let totalCpu = 0;
-        let totalMemKb = 0;
-        for (const entry of matching) {
-            totalCpu += entry.cpu;
-            totalMemKb += entry.memKb;
-        }
-        results.push({
+        if (matching.length === 0)
+            return { name, running: false };
+        const totalCpu = matching.reduce((sum, e) => sum + e.cpu, 0);
+        const totalMemKb = matching.reduce((sum, e) => sum + e.memKb, 0);
+        return {
             name,
             running: true,
             pid: matching[0].pid,
+            count: matching.length,
             cpuPercent: Math.round(totalCpu * 100) / 100,
             memMb: Math.round((totalMemKb / 1024) * 100) / 100,
-        });
-    }
-    return results;
+        };
+    });
+}
+/**
+ * Scan for processes by name and return their status and resource usage.
+ * Works on macOS and Linux via `ps`. Throws when the process list is unavailable.
+ */
+export async function scanProcesses(names) {
+    return matchProcesses(names, await listProcesses());
 }
 //# sourceMappingURL=process-scanner.js.map

package/dist/npcs/receptionist/defaults.d.ts

@@ -1,6 +1,10 @@
 export declare const DEFAULTS: {
     pollInterval: number;
     weatherRefreshMs: number;
+    /** Drop a reading this old (repeated refresh failures) rather than show stale weather. */
+    weatherMaxAgeMs: number;
+    /** Wait this long before retrying a failed geocode / IP geo / weather call. */
+    retryBackoffMs: number;
     fetchTimeoutMs: number;
 };
 //# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/receptionist/defaults.js

@@ -1,6 +1,10 @@
 export const DEFAULTS = {
     pollInterval: 60000, // 60s clock tick
     weatherRefreshMs: 15 * 60 * 1000, // refresh weather every 15 minutes
+    /** Drop a reading this old (repeated refresh failures) rather than show stale weather. */
+    weatherMaxAgeMs: 2 * 60 * 60 * 1000,
+    /** Wait this long before retrying a failed geocode / IP geo / weather call. */
+    retryBackoffMs: 5 * 60 * 1000,
     fetchTimeoutMs: 5000,
 };
 //# sourceMappingURL=defaults.js.map

package/dist/npcs/receptionist/index.d.ts

@@ -7,15 +7,25 @@ export interface ReceptionistConfig extends PollingNpcConfig {
     location?: string;
     /** Display temperature in Fahrenheit instead of Celsius. */
     fahrenheit?: boolean;
+    /**
+     * Fall back to IP geolocation (ipapi.co) when no --lat/--lon or --location
+     * is given. Default true; false keeps the receptionist in time-only mode
+     * rather than sending this machine's IP to a third party.
+     */
+    ipGeo?: boolean;
 }
 export declare class ReceptionistNPC extends PollingNPC {
     private explicitCoords;
     private location?;
     private fahrenheit;
+    private ipGeo;
     private coords;
-    private geoAttempted;
+    /** Earliest time to retry geocoding / IP geo after a failure. */
+    private nextGeoAttempt;
     private weather;
-    private lastWeatherFetch;
+    private weatherFetchedAt;
+    /** Earliest time to retry the weather after a failure. */
+    private nextWeatherAttempt;
     constructor(config: ReceptionistConfig);
     get name(): string;
     protected get defaultDisplayName(): string;

package/dist/npcs/receptionist/index.js

@@ -1,22 +1,34 @@
 import { PollingNPC } from '../../core/polling-npc.js';
+import { NpcConfigError } from '../../core/errors.js';
 import { DEFAULTS } from './defaults.js';
-import { fetchWeather, geocodeLocation, autoGeo, formatClock, toFahrenheit } from './weather.js';
+import { fetchWeather, geocodeLocation, autoGeo, formatClock, toFahrenheit, validCoords, } from './weather.js';
 export class ReceptionistNPC extends PollingNPC {
     explicitCoords;
     location;
     fahrenheit;
+    ipGeo;
     coords = null;
-    geoAttempted = false;
+    /** Earliest time to retry geocoding / IP geo after a failure. */
+    nextGeoAttempt = 0;
     weather = null;
-    lastWeatherFetch = 0;
+    weatherFetchedAt = 0;
+    /** Earliest time to retry the weather after a failure. */
+    nextWeatherAttempt = 0;
     constructor(config) {
         super({ ...config, pollInterval: config.pollInterval ?? DEFAULTS.pollInterval });
+        if ((config.lat === undefined) !== (config.lon === undefined)) {
+            throw new NpcConfigError('--lat and --lon must be given together');
+        }
+        if (config.lat !== undefined && !validCoords(config.lat, config.lon)) {
+            throw new NpcConfigError('--lat must be within ±90 and --lon within ±180');
+        }
         this.explicitCoords =
             config.lat !== undefined && config.lon !== undefined
                 ? { lat: config.lat, lon: config.lon }
                 : null;
-        this.location = config.location;
+        this.location = config.location?.trim() || undefined;
         this.fahrenheit = config.fahrenheit ?? false;
+        this.ipGeo = config.ipGeo ?? true;
     }
     get name() {
         return 'receptionist';
@@ -75,41 +87,55 @@ export class ReceptionistNPC extends PollingNPC {
         };
     }
     async refreshWeather() {
-        if (!this.coords) {
-            await this.resolveCoords();
-        }
+        const now = Date.now();
         if (!this.coords)
+            await this.resolveCoords(now);
+        // Don't show a reading that has gone stale through repeated failures.
+        if (this.weather && now - this.weatherFetchedAt > DEFAULTS.weatherMaxAgeMs) {
+            this.weather = null;
+        }
+        if (!this.coords || now < this.nextWeatherAttempt)
             return;
-        const now = Date.now();
-        if (this.weather && now - this.lastWeatherFetch < DEFAULTS.weatherRefreshMs)
+        if (this.weather && now - this.weatherFetchedAt < DEFAULTS.weatherRefreshMs)
             return;
         const w = await fetchWeather(this.coords, DEFAULTS.fetchTimeoutMs);
         if (w) {
             this.weather = w;
-            this.lastWeatherFetch = now;
+            this.weatherFetchedAt = now;
+        }
+        else {
+            this.nextWeatherAttempt = now + DEFAULTS.retryBackoffMs;
         }
     }
-    async resolveCoords() {
+    async resolveCoords(now) {
         if (this.explicitCoords) {
             this.coords = this.explicitCoords;
             return;
         }
-        // Only attempt geocoding/geo-IP once per (failed) resolution to avoid
-        // hammering the keyless endpoints every poll.
-        if (this.geoAttempted)
+        // Back off after a failure rather than hitting the keyless endpoints every tick.
+        if (now < this.nextGeoAttempt)
             return;
-        this.geoAttempted = true;
+        this.nextGeoAttempt = now + DEFAULTS.retryBackoffMs;
         if (this.location) {
             this.coords = await geocodeLocation(this.location, DEFAULTS.fetchTimeoutMs);
             if (this.coords)
                 return;
-            this.logger.warn(`Could not geocode "${this.location}", falling back to IP geo`);
+            this.logger.warn(`Could not geocode "${this.location}"` + (this.ipGeo ? ', falling back to IP geo' : ''));
+        }
+        if (!this.ipGeo) {
+            if (!this.location) {
+                this.nextGeoAttempt = Infinity; // nothing to resolve, ever
+                this.logger.info('No location set and IP geolocation disabled: time-only mode');
+            }
+            return;
         }
         this.coords = await autoGeo(DEFAULTS.fetchTimeoutMs);
-        if (!this.coords) {
-            this.logger.warn('Weather geo unavailable — running in time-only mode');
-            // Allow a later retry.
-            this.geoAttempted = false;
+        if (this.coords) {
+            this.logger.info("Weather location estimated from this machine's IP via ipapi.co " +
+                '(set --location or --lat/--lon, or pass --no-ip-geo to disable)');
+        }
+        else {
+            this.logger.warn('Weather geo unavailable — running in time-only mode for now');
         }
     }
 }

package/dist/npcs/receptionist/weather.d.ts

@@ -1,8 +1,3 @@
-/**
- * Keyless weather + geolocation via open-meteo, with ipapi.co IP fallback.
- * All network helpers return null on failure so the receptionist can degrade
- * to a time-only mode without erroring.
- */
 export interface Coords {
     lat: number;
     lon: number;
@@ -20,9 +15,16 @@ export declare function describeWmo(code: number): {
     text: string;
     icon: string;
 };
+/** A finite, in-range latitude/longitude pair. */
+export declare function validCoords(lat: unknown, lon: unknown): boolean;
 /** Resolve a place name to coordinates via the open-meteo geocoding API. */
 export declare function geocodeLocation(name: string, timeoutMs?: number): Promise<Coords | null>;
-/** Best-effort IP geolocation via ipapi.co (keyless). */
+/**
+ * Best-effort IP geolocation via ipapi.co (keyless). This sends the machine's
+ * public IP to a third party, so the receptionist only calls it when no place
+ * was configured and the user hasn't opted out. Only the coordinates are used;
+ * nothing from the response is pushed to Nocville.
+ */
 export declare function autoGeo(timeoutMs?: number): Promise<Coords | null>;
 /** Fetch current temperature, weather code, and wind for coordinates. */
 export declare function fetchWeather(coords: Coords, timeoutMs?: number): Promise<Weather | null>;