@profullstack/hqtui-demo 0.1.9 → 0.1.11

package/src/format.ts

@@ -1,8 +1,21 @@
+/**
+ * Every value here arrives from a parser reading a file or a command that may
+ * be absent, truncated or in an unexpected shape, so this is the last place a
+ * non-finite number can be stopped before it reaches the screen. `nvidia-smi`
+ * prints "[N/A]", a partial `df` yields "-", and both become NaN.
+ */
+const UNAVAILABLE = "\u2014";
+
+function finite(value: number): number | null {
+  return Number.isFinite(value) ? value : null;
+}
+
 /** Presentation helpers. Numbers in a dashboard must never jitter in width. */
 
 const UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
 
 export function bytes(value: number, digits = 2): string {
+  if (finite(value) === null) return UNAVAILABLE;
   let v = Math.max(0, value);
   let unit = 0;
   while (v >= 1024 && unit < UNITS.length - 1) {
@@ -13,6 +26,7 @@ export function bytes(value: number, digits = 2): string {
 }
 
 export function bitRate(bytesPerSecond: number): string {
+  if (finite(bytesPerSecond) === null) return UNAVAILABLE;
   const bits = Math.max(0, bytesPerSecond) * 8;
   if (bits >= 1e9) return `${(bits / 1e9).toFixed(1)} Gb/s`;
   if (bits >= 1e6) return `${(bits / 1e6).toFixed(1)} Mb/s`;
@@ -21,6 +35,7 @@ export function bitRate(bytesPerSecond: number): string {
 }
 
 export function byteRate(bytesPerSecond: number): string {
+  if (finite(bytesPerSecond) === null) return UNAVAILABLE;
   const v = Math.max(0, bytesPerSecond);
   if (v >= 1e9) return `${(v / 1e9).toFixed(1)} GB/s`;
   if (v >= 1e6) return `${(v / 1e6).toFixed(1)} MB/s`;
@@ -29,10 +44,12 @@ export function byteRate(bytesPerSecond: number): string {
 }
 
 export function percent(ratio: number, digits = 0): string {
+  if (finite(ratio) === null) return UNAVAILABLE;
   return `${(Math.max(0, Math.min(1, ratio)) * 100).toFixed(digits)}%`;
 }
 
 export function duration(seconds: number): string {
+  if (finite(seconds) === null) return UNAVAILABLE;
   const s = Math.max(0, Math.floor(seconds));
   const d = Math.floor(s / 86400);
   const h = Math.floor((s % 86400) / 3600);

package/src/main.ts

@@ -9,6 +9,7 @@
  */
 import { createApp, themeList, themes, type KeyEvent } from "@profullstack/hqtui";
 import { createCollector } from "./system/index.ts";
+import { intervalMs } from "./options.ts";
 import { createState, focusedPane, moveSelection, SCREENS, type ScreenName } from "./state.ts";
 import {
   componentsScreen, dashboardScreen, graphicsScreen, inputScreen, networkScreen, servicesScreen,
@@ -46,11 +47,11 @@ function parseArgs(argv: string[]): Options {
       case "--fps": options.fps = Number(value) || 30; i++; break;
       case "--theme": options.theme = value ?? "dark"; i++; break;
       case "--screen": options.screen = (value as ScreenName) ?? "dashboard"; i++; break;
-      case "--interval": options.interval = Number(value) || 1000; i++; break;
+      case "--interval": options.interval = intervalMs(value); i++; break;
       case "-h":
       case "--help": printHelp(); process.exit(0);
       case "-v":
-      case "--version": console.log("hqtui-demo 0.1.9"); process.exit(0);
+      case "--version": console.log("hqtui-demo 0.1.11"); process.exit(0);
     }
   }
   return options;
@@ -112,14 +113,33 @@ async function main(): Promise<void> {
   });
 
   // Metrics refresh on their own clock; rendering runs at the frame rate.
-  const dt = options.interval / 1000;
+  // One refresh at a time. Collecting can outrun the interval — the tick-15 path
+  // alone allows journalctl five seconds — and every concurrent call mutates the
+  // same sample, the same previous-counter state, and the same tick counter that
+  // drives the staggered cadences, while spawning its own ps, ss, df and
+  // journalctl.
+  let refreshing = false;
+  let lastRefreshAt = Date.now();
   const poll = setInterval(() => {
-    if (state.paused) return;
-    void collector.refresh(dt).then(() => {
-      state.sample = collector.current();
-      state.sensorNote = collector.sensorNote ?? state.sensorNote;
-      app.invalidate();
-    });
+    if (state.paused || refreshing) return;
+    // Every rate is a counter delta divided by this, so it has to be the time
+    // that actually passed. A fixed interval overstated every rate by the skip
+    // factor whenever a refresh outran its tick — and `sh()` alone allows four
+    // seconds per command.
+    const now = Date.now();
+    const elapsed = Math.max(0.001, (now - lastRefreshAt) / 1000);
+    lastRefreshAt = now;
+    refreshing = true;
+    void collector
+      .refresh(elapsed)
+      .then(() => {
+        state.sample = collector.current();
+        state.sensorNote = collector.sensorNote ?? state.sensorNote;
+        app.invalidate();
+      })
+      .finally(() => {
+        refreshing = false;
+      });
   }, options.interval);
   poll.unref?.();
 

package/src/options.ts

@@ -0,0 +1,20 @@
+/**
+ * Option parsing that is worth testing on its own, kept out of main.ts because
+ * importing that module starts the dashboard.
+ */
+
+/**
+ * A refresh interval `setInterval` will honour.
+ *
+ * Node resets any delay outside [1, 2^31-1] — and NaN, and Infinity — to *one
+ * millisecond*, so clamping only the floor leaves the failure wide open at the
+ * top. `--interval 1e12` asks for one refresh every thirty-one years and gets a
+ * one-millisecond loop forking ps, ss and journalctl. `--interval Infinity`
+ * additionally makes the elapsed time infinite and every rate derived from it
+ * NaN.
+ */
+export function intervalMs(value: string | undefined): number {
+  const requested = Number(value);
+  if (!Number.isFinite(requested)) return 1000;
+  return Math.min(3_600_000, Math.max(100, Math.round(requested)));
+}

package/src/screens/dashboard.ts

@@ -119,8 +119,10 @@ function systemPanel(ui: Container, state: DemoState, theme: Theme): void {
           q.keyValues([
             { label: "Uptime", value: duration(s.system.uptime), color: theme.accent },
             { label: "Procs", value: String(s.system.processCount || s.processes.length), color: theme.accent },
-            { label: "Threads", value: String(s.system.threadCount), color: theme.accent },
-            { label: "Ctx/s", value: `${(s.system.contextSwitches / 1000).toFixed(1)}K`, color: theme.accent },
+            { label: "Threads", value: s.system.threadCount ? String(s.system.threadCount) : "—", color: theme.accent },
+            // contextSwitches is cumulative since boot; the per-second rate is
+            // what the label claims, and what the Services screen already uses.
+            { label: "Ctx/s", value: `${(s.telemetry.kernel.contextSwitchRate / 1000).toFixed(1)}K`, color: theme.accent },
           ]);
         });
         r.panel({ title: "Memory" }, (q) => {

package/src/system/common.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { open, stat } from "node:fs/promises";
 import { promisify } from "node:util";
 import os from "node:os";
 import type { SystemSample } from "../simulation.ts";
@@ -6,16 +7,112 @@ import { emptyTelemetry } from "./telemetry.ts";
 
 const run = promisify(execFile);
 
-/** Run a command, returning "" instead of throwing when it is unavailable. */
+/**
+ * Run a command, returning "" instead of throwing when it is unavailable.
+ *
+ * Whatever it managed to write is kept even when it exits non-zero. `df` exits
+ * 1 if any single mount is unreadable while still reporting every other one, so
+ * discarding stdout on failure zeroed the capacity of every disk on the machine
+ * whenever one stale automount or a departed removable drive was listed.
+ */
 export async function sh(command: string, args: string[], timeout = 4000): Promise<string> {
   try {
     const { stdout } = await run(command, args, { timeout, maxBuffer: 8 * 1024 * 1024 });
     return stdout;
+  } catch (error) {
+    const partial = (error as { stdout?: string }).stdout;
+    return typeof partial === "string" ? partial : "";
+  }
+}
+
+/**
+ * The last `bytes` of a file, as text.
+ *
+ * Log files are read for their tail, and reading one whole to keep 40 lines is
+ * a habit that only shows up in production: a brute-forced auth.log reaching a
+ * few hundred MB blocks the event loop for the better part of a second on every
+ * refresh, and above the maximum string length it throws and the panel silently
+ * empties.
+ */
+export async function tailFile(path: string, bytes = 256 * 1024): Promise<string> {
+  try {
+    const info = await stat(path);
+    if (info.size === 0) return "";
+    const handle = await open(path, "r");
+    try {
+      const length = Math.min(bytes, info.size);
+      const buffer = Buffer.alloc(length);
+      // `bytesRead` matters: the file can be rotated or truncated between the
+      // stat and the read, and the untouched tail of the buffer is NUL bytes.
+      const { bytesRead } = await handle.read(buffer, 0, length, Math.max(0, info.size - length));
+      return buffer.subarray(0, bytesRead).toString("utf8");
+    } finally {
+      await handle.close();
+    }
   } catch {
     return "";
   }
 }
 
+/**
+ * A process name from its command line, used when `comm` is unavailable.
+ *
+ * `args` is argv joined by spaces, so an executable whose own path contains a
+ * space is ambiguous: "/tmp/Google Chrome 60" could be argv0 "/tmp/Google"
+ * with an argument, or "/tmp/Google Chrome" with one. Nothing in the string
+ * resolves it, which is why `comm` is read separately and preferred.
+ */
+export function processName(args: string): string {
+  const argv0 = args.trim().split(/\s+/)[0] ?? "";
+  // Kernel threads are already bracketed names, not paths.
+  if (argv0.startsWith("[")) return argv0;
+  return argv0.split("/").pop() || argv0 || "-";
+}
+
+/**
+ * Reconcile the two names a process has, neither of which is reliable alone.
+ *
+ * The accounting name (`comm` on Linux, `ucomm` on macOS) keeps spaces but is
+ * truncated — to 15 bytes on Linux, 16 on macOS. The name derived from argv[0]
+ * is untruncated but splits at the first space, because `args` is argv joined
+ * by spaces and nothing in it says where argv[0] ended.
+ *
+ * So: trust argv[0], and take the accounting name only when it *extends* it —
+ * which is exactly the case where argv[0] was cut at a space. Anything else the
+ * accounting name says is not corroborated, and it is not always a name at all:
+ * on macOS `ucomm` for one live process here reads "2.1.243".
+ *
+ *   argv0 "Web"                      comm  "Web Content"      -> "Web Content"
+ *   argv0 "StorageManagementService" ucomm "StorageManagemen" -> argv0's
+ *   argv0 "claude"                   ucomm "2.1.243"          -> argv0's
+ */
+export function bestName(accounting: string | undefined, fromArgs: string): string {
+  if (!fromArgs || fromArgs === "-") return accounting || fromArgs;
+  if (!accounting) return fromArgs;
+  return accounting.length > fromArgs.length && accounting.startsWith(fromArgs)
+    ? accounting
+    : fromArgs;
+}
+
+/**
+ * pid -> accounting name, read with that name as the only free-form column so
+ * its spaces cannot shift anything. Parsing it out of a combined `ps` row is
+ * what corrupted every column after it.
+ */
+export async function processNames(psArgs: string[]): Promise<Map<number, string>> {
+  const names = new Map<number, string>();
+  const text = await sh("ps", psArgs);
+  for (const line of text.trim().split("\n").slice(1)) {
+    const trimmed = line.trim();
+    const gap = trimmed.indexOf(" ");
+    if (gap < 0) continue;
+    const pid = Number(trimmed.slice(0, gap));
+    const comm = trimmed.slice(gap + 1).trim();
+    if (Number.isFinite(pid) && comm) names.set(pid, comm);
+  }
+  return names;
+}
+
 export function push(history: number[], value: number, limit = 240): void {
   history.push(value);
   if (history.length > limit) history.shift();

package/src/system/darwin.ts

@@ -1,6 +1,8 @@
 import os from "node:os";
 import type { Collector, SystemSample } from "./types.ts";
-import { baseSample, loadAverage, primaryInterface, push, ratePerSecond, sh } from "./common.ts";
+import {
+  baseSample, loadAverage, primaryInterface, bestName, processName, processNames, push, ratePerSecond, sh,
+} from "./common.ts";
 
 /**
  * macOS has no /proc, so everything comes from small command-line tools that
@@ -8,7 +10,7 @@ import { baseSample, loadAverage, primaryInterface, push, ratePerSecond, sh } fr
  */
 export class DarwinCollector implements Collector {
   source = "macOS sysctl";
-  unavailable = ["temperatures", "fan speed"];
+  unavailable = ["temperatures", "fan speed", "per-core CPU", "thread count"];
   private sample = baseSample();
   private prevCpu: { idle: number; total: number } | null = null;
   private prevNet: [number, number] | null = null;
@@ -28,12 +30,12 @@ export class DarwinCollector implements Collector {
     }
     const load = loadAverage();
     s.cpu.load = load;
+    // `top` reports one aggregate figure. Per-core detail would need
+    // host_processor_info, so every core shows the measured total rather than
+    // a synthesised spread around it — the README promises that anything a
+    // platform cannot provide is reported as unavailable, not fabricated.
     const cores = Math.max(1, os.cpus().length);
-    s.cpu.cores = Array.from({ length: cores }, (_, i) => {
-      // Spread total load across cores with a stable per-core offset.
-      const jitter = ((i * 37) % 17) / 100;
-      return Math.max(0, Math.min(1, s.cpu.total + jitter - 0.08));
-    });
+    s.cpu.cores = new Array(cores).fill(s.cpu.total);
     push(s.cpu.history, s.cpu.total * 100);
 
     // Memory via vm_stat page counts.
@@ -133,25 +135,36 @@ export class DarwinCollector implements Collector {
   }
 
   private async updateProcesses(): Promise<void> {
-    const text = await sh("ps", ["-Ao", "pid,comm,pcpu,pmem,rss,user,state,args", "-r"]);
-    if (!text) return;
-    const lines = text.trim().split("\n").slice(1, 60);
-    this.sample.processes = lines.map((line) => {
+    // `comm` is omitted: macOS truncates it to 16 characters, so taking the
+    // last path segment yields a fragment — "/System/Applicat" became
+    // "Applicat", and a 16-character path ending in "/" became "".
+    const text = await sh("ps", ["-Ao", "pid,pcpu,pmem,rss,user,state,args", "-r"]);
+    if (!text) {
+      if (!this.unavailable.includes("processes")) this.unavailable.push("processes");
+      return;
+    }
+    // `comm` in its own read, where its spaces cannot shift a column.
+    // macOS `comm` is the full path truncated to 16 characters; `ucomm` is the
+    // accounting name, which is what a process table wants.
+    const names = await processNames(["-Ao", "pid,ucomm"]);
+    const rows = text.trim().split("\n").slice(1);
+    this.sample.processes = rows.slice(0, 59).map((line) => {
       const parts = line.trim().split(/\s+/);
-      const name = (parts[1] ?? "-").split("/").pop() ?? "-";
+      const command = parts.slice(6).join(" ");
       return {
         pid: Number(parts[0]),
-        name,
-        cpu: Number(parts[2]) || 0,
-        mem: Number(parts[3]) || 0,
-        rss: (Number(parts[4]) || 0) * 1024,
+        name: bestName(names.get(Number(parts[0])), processName(command)),
+        cpu: Number(parts[1]) || 0,
+        mem: Number(parts[2]) || 0,
+        rss: (Number(parts[3]) || 0) * 1024,
         threads: 1,
-        user: parts[5] ?? "-",
-        state: parts[6] ?? "-",
-        command: parts.slice(7).join(" "),
+        user: parts[4] ?? "-",
+        state: parts[5] ?? "-",
+        command,
       };
     });
-    this.sample.system.processCount = this.sample.processes.length;
+    // Every row, not the truncated table.
+    this.sample.system.processCount = rows.length;
   }
 
   current(): SystemSample {

package/src/system/linux-telemetry.ts

@@ -1,6 +1,6 @@
 import { readFile, readdir } from "node:fs/promises";
 import os from "node:os";
-import { sh, push } from "./common.ts";
+import { sh, push, tailFile } from "./common.ts";
 import type {
   Connection, Container, Filesystem, Interface, JournalEntry, KernelStats,
   Listener, LoginEvent, ProcessStates, PowerStats, ServiceUnit, Session, Telemetry, GpuStats,
@@ -155,6 +155,7 @@ export async function interfaces(dt: number, history: Map<string, Interface>): P
   if (!netdev) return [];
   const addresses = os.networkInterfaces();
   const out: Interface[] = [];
+  const seen = new Set<string>();
 
   for (const line of netdev.split("\n").slice(2)) {
     const match = /^\s*([\w.@-]+):\s*(.*)$/.exec(line);
@@ -172,6 +173,7 @@ export async function interfaces(dt: number, history: Map<string, Interface>): P
     const txRate = previous && txBytes >= previous[1] ? (txBytes - previous[1]) / dt : 0;
     previousInterfaces[name] = [rxBytes, txBytes];
 
+    seen.add(name);
     const address = (addresses[name] ?? []).find((a) => a.family === "IPv4");
     const existing = history.get(name);
     const entry: Interface = {
@@ -194,6 +196,16 @@ export async function interfaces(dt: number, history: Map<string, Interface>): P
     history.set(name, entry);
     out.push(entry);
   }
+  // Both maps are keyed by interface name and neither was ever pruned. On a
+  // container host the veth* names churn constantly, and each retained entry
+  // holds two 240-element history arrays — unbounded growth over an uptime.
+  for (const name of Object.keys(previousInterfaces)) {
+    if (!seen.has(name)) delete previousInterfaces[name];
+  }
+  for (const name of history.keys()) {
+    if (!seen.has(name)) history.delete(name);
+  }
+
   return out;
 }
 
@@ -542,7 +554,8 @@ export async function journal(limit = 60): Promise<JournalEntry[]> {
   }
 
   for (const path of ["/var/log/syslog", "/var/log/messages"]) {
-    const raw = await read(path);
+    // Tailed, not read whole; only the last `limit` lines are used anyway.
+    const raw = await tailFile(path);
     if (!raw) continue;
     return raw.trim().split("\n").slice(-limit).map((line) => {
       const match = /^(\w+\s+\d+\s+[\d:]+)\s+\S+\s+([^:[]+)/.exec(line);

package/src/system/linux-traffic.ts

@@ -1,6 +1,5 @@
 import { readFile, stat } from "node:fs/promises";
-import { open } from "node:fs/promises";
-import { sh } from "./common.ts";
+import { sh, tailFile } from "./common.ts";
 
 /**
  * Protocol-level visibility without root: socket classification, kernel
@@ -224,7 +223,8 @@ export async function sshEvents(limit = 40): Promise<SshEvent[]> {
   const text = await sh("journalctl", [
     "-u", "ssh", "-u", "sshd", "-n", String(limit * 2), "--no-pager", "--output=short-iso",
   ], 5000);
-  const source = text || (await read("/var/log/auth.log"));
+  // Tailed, not read whole: this file grows without bound under a brute force.
+  const source = text || (await tailFile("/var/log/auth.log"));
   if (!source) return [];
 
   const events: SshEvent[] = [];
@@ -302,17 +302,11 @@ export async function http(tailBytes = 256 * 1024): Promise<HttpStats | null> {
   }
   if (!path) return null;
 
-  let text = "";
-  try {
-    const handle = await open(path, "r");
-    const start = Math.max(0, size - tailBytes);
-    const buffer = Buffer.alloc(Math.min(tailBytes, size));
-    await handle.read(buffer, 0, buffer.length, start);
-    await handle.close();
-    text = buffer.toString("utf8");
-  } catch {
-    return null;
-  }
+  // Shares `tailFile`'s handling of a rotation between the stat and the read,
+  // which otherwise leaves the tail of the buffer as NUL bytes — and those flow
+  // into `split("\n")` and into the request-rate denominator below.
+  const text = await tailFile(path, tailBytes);
+  if (!text) return null;
 
   const lines = text.split("\n").slice(1).filter(Boolean);
   const statusClasses = new Map<string, number>();

package/src/system/linux.ts

@@ -1,7 +1,10 @@
 import { readFile, readdir } from "node:fs/promises";
 import os from "node:os";
 import type { Collector, SystemSample } from "./types.ts";
-import { baseSample, loadAverage, primaryInterface, push, ratePerSecond, sh } from "./common.ts";
+import { bitRate } from "../format.ts";
+import {
+  baseSample, loadAverage, primaryInterface, bestName, processName, processNames, push, ratePerSecond, sh,
+} from "./common.ts";
 import type { Interface } from "./telemetry.ts";
 import * as telemetry from "./linux-telemetry.ts";
 import * as traffic from "./linux-traffic.ts";
@@ -92,7 +95,7 @@ export class LinuxCollector implements Collector {
     const ctxt = /^ctxt (\d+)/m.exec(stat);
     if (ctxt) s.system.contextSwitches = Number(ctxt[1]);
     const procs = /^procs_running (\d+)/m.exec(stat);
-    if (procs) s.system.threadCount = Number(procs[1]);
+    // `procs_running` is runnable processes; the thread total comes from ps.
 
     // Memory.
     const mem = parseMeminfo(meminfo);
@@ -172,7 +175,10 @@ export class LinuxCollector implements Collector {
     s.network.downPeak = Math.max(s.network.downPeak, s.network.downRate);
     s.network.upPeak = Math.max(s.network.upPeak, s.network.upRate);
     const speed = await read(`/sys/class/net/${iface.name}/speed`);
-    s.network.speed = speed.trim() && Number(speed) > 0 ? `${Number(speed) / 1000} Gb/s` : "-";
+    // /sys reports Mb/s. Dividing unconditionally rendered a 100 Mb/s NIC as
+    // "0.1 Gb/s"; bitRate picks the unit the number belongs in.
+    const mbps = Number(speed);
+    s.network.speed = speed.trim() && mbps > 0 ? bitRate((mbps * 1e6) / 8) : "-";
 
     await Promise.all([this.updateProcesses(), this.updateTemperatures()]);
     await this.updateTelemetry(dt);
@@ -294,27 +300,39 @@ export class LinuxCollector implements Collector {
   }
 
   private async updateProcesses(): Promise<void> {
-    const text = await sh("ps", ["-eo", "pid,comm,pcpu,pmem,rss,nlwp,user,state,args", "--sort=-pcpu"]);
+    // `comm` is deliberately absent: it can contain spaces, which shifts every
+    // column parsed after it. Every field here is space-free, so `args` — which
+    // may contain anything — is the only free-form one and it comes last.
+    const text = await sh("ps", ["-eo", "pid,pcpu,pmem,rss,nlwp,user,state,args", "--sort=-pcpu"]);
     if (!text) {
       if (!this.unavailable.includes("processes")) this.unavailable.push("processes");
       return;
     }
-    const lines = text.trim().split("\n").slice(1, 60);
-    this.sample.processes = lines.map((line) => {
+    // `comm` in its own read, where its spaces cannot shift a column.
+    const names = await processNames(["-eo", "pid,comm"]);
+    const rows = text.trim().split("\n").slice(1);
+    this.sample.processes = rows.slice(0, 59).map((line) => {
       const parts = line.trim().split(/\s+/);
+      const command = parts.slice(7).join(" ");
       return {
         pid: Number(parts[0]),
-        name: parts[1] ?? "-",
-        cpu: Number(parts[2]) || 0,
-        mem: Number(parts[3]) || 0,
-        rss: (Number(parts[4]) || 0) * 1024,
-        threads: Number(parts[5]) || 1,
-        user: parts[6] ?? "-",
-        state: parts[7] ?? "-",
-        command: parts.slice(8).join(" "),
+        name: bestName(names.get(Number(parts[0])), processName(command)),
+        cpu: Number(parts[1]) || 0,
+        mem: Number(parts[2]) || 0,
+        rss: (Number(parts[3]) || 0) * 1024,
+        threads: Number(parts[4]) || 1,
+        user: parts[5] ?? "-",
+        state: parts[6] ?? "-",
+        command,
       };
     });
-    this.sample.system.processCount = this.sample.processes.length;
+    // Count every row, not the truncated table: this used to overwrite the real
+    // total from /proc with at most 59, so the figure alternated every tick.
+    this.sample.system.processCount = rows.length;
+    this.sample.system.threadCount = rows.reduce(
+      (total, line) => total + (Number(line.trim().split(/\s+/)[4]) || 0),
+      0,
+    );
   }
 
   private async updateTemperatures(): Promise<void> {