@yourfam/yf-vitals 0.1.0

package/src/format.js

@@ -0,0 +1,86 @@
+const KIB = 1024;
+const MIB = 1024 * 1024;
+const GIB = 1024 * 1024 * 1024;
+
+/**
+ * @param {number} bytes
+ */
+export function formatBytes(bytes) {
+  const n = Number(bytes);
+  if (!Number.isFinite(n) || n < 0) return "n/a";
+  if (n >= GIB) return `${(n / GIB).toFixed(1)} GiB`;
+  return `${(n / MIB).toFixed(1)} MiB`;
+}
+
+/**
+ * @param {number} used
+ * @param {number} total
+ */
+export function formatBytePair(used, total) {
+  const t = Number(total);
+  const u = Number(used);
+  if (!Number.isFinite(t) || t < 0 || !Number.isFinite(u) || u < 0) return "n/a";
+  const unit = t >= GIB ? "GiB" : "MiB";
+  const div = unit === "GiB" ? GIB : MIB;
+  return `${(u / div).toFixed(1)} / ${(t / div).toFixed(1)} ${unit}`;
+}
+
+/**
+ * Disk throughput. `null` → em dash (first tick).
+ * @param {number | null | undefined} bytesPerSec
+ */
+export function formatByteRate(bytesPerSec) {
+  if (bytesPerSec == null) return "—";
+  const n = Number(bytesPerSec);
+  if (!Number.isFinite(n) || n < 0) return "—";
+  if (n >= GIB) return `${(n / GIB).toFixed(1)} GiB/s`;
+  if (n >= MIB) return `${(n / MIB).toFixed(1)} MiB/s`;
+  return `${(n / KIB).toFixed(1)} KiB/s`;
+}
+
+/**
+ * Network throughput in decimal Mbps (1 Mbps = 1e6 bit/s).
+ * @param {number | null | undefined} bytesPerSec
+ */
+export function formatBitRate(bytesPerSec) {
+  if (bytesPerSec == null) return "—";
+  const n = Number(bytesPerSec);
+  if (!Number.isFinite(n) || n < 0) return "—";
+  const mbps = (n * 8) / 1e6;
+  return `${mbps.toFixed(1)} Mbps`;
+}
+
+/**
+ * @param {number} percent
+ */
+export function formatPercent(percent) {
+  const n = Number(percent);
+  if (!Number.isFinite(n)) return "n/a";
+  const p = Math.min(100, Math.max(0, Math.round(n)));
+  return `${String(p).padStart(3, " ")}%`;
+}
+
+/**
+ * @param {number} seconds
+ */
+export function formatInterval(seconds) {
+  const n = Number(seconds);
+  if (!Number.isFinite(n)) return "1.0s";
+  return `${n.toFixed(1)}s`;
+}
+
+/**
+ * @param {number} physical
+ * @param {number} logical
+ */
+export function formatCores(physical, logical) {
+  const p = Number(physical);
+  const l = Number(logical);
+  const ps = Number.isFinite(p) && p > 0 ? String(Math.round(p)) : "?";
+  const ls = Number.isFinite(l) && l > 0 ? String(Math.round(l)) : "?";
+  return `${ps}P/${ls}L`;
+}
+
+export function formatCoresDetail(physical, logical) {
+  return formatCores(physical, logical).replace("/", " / ");
+}

package/src/history.js

@@ -0,0 +1,58 @@
+import { HISTORY_SIZE } from "./bar.js";
+
+/**
+ * @typedef {object} History
+ * @property {number[]} cpu
+ * @property {number[]} ram
+ * @property {number[]} gpu
+ * @property {number[]} dsk
+ * @property {number[]} net
+ */
+
+export function createHistory() {
+  return { cpu: [], ram: [], gpu: [], dsk: [], net: [] };
+}
+
+/**
+ * @param {number[]} buf
+ * @param {number | null | undefined} value
+ * @param {number} [size]
+ */
+export function pushSample(buf, value, size = HISTORY_SIZE) {
+  if (value == null || Number.isNaN(Number(value))) return buf;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return buf;
+  const next = buf.length >= size ? buf.slice(buf.length - size + 1) : buf.slice();
+  next.push(n);
+  return next;
+}
+
+/**
+ * @param {History} history
+ * @param {import("./sample.js").Snapshot} snap
+ * @returns {History}
+ */
+export function appendHistory(history, snap) {
+  const cpu = snap.cpu?.percent;
+  const ram = snap.ram?.percent;
+  const gpu = snap.gpu?.percent;
+  const read = snap.disk?.readBps;
+  const write = snap.disk?.writeBps;
+  const tx = snap.net?.txBps;
+  const rx = snap.net?.rxBps;
+  let dsk;
+  if (read != null || write != null) {
+    dsk = (read ?? 0) + (write ?? 0);
+  }
+  let net;
+  if (tx != null || rx != null) {
+    net = (tx ?? 0) + (rx ?? 0);
+  }
+  return {
+    cpu: pushSample(history.cpu, cpu),
+    ram: pushSample(history.ram, ram),
+    gpu: pushSample(history.gpu, gpu),
+    dsk: pushSample(history.dsk, dsk),
+    net: pushSample(history.net, net),
+  };
+}

package/src/index.js

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { helpText, parseArgs } from "./args.js";
+import { runDashboard } from "./dashboard.js";
+import { CliError } from "./errors.js";
+import { restoreTerminal } from "./tty.js";
+
+const pkg = JSON.parse(
+  readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+    "utf8",
+  ),
+);
+
+function defaultDeps() {
+  return {
+    env: process.env,
+    version: pkg.version,
+    log: (msg) => console.log(msg),
+    err: (msg) => console.error(msg),
+    write: (s) => process.stdout.write(s),
+    isTTY: () => Boolean(process.stdout.isTTY),
+    columns: () => process.stdout.columns || 80,
+    stdin: process.stdin,
+    process,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {Partial<ReturnType<typeof defaultDeps>> & { dashboard?: Function }} [overrides]
+ * @returns {Promise<number>}
+ */
+export async function main(argv, overrides = {}) {
+  const deps = { ...defaultDeps(), ...overrides };
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    if (err instanceof CliError) {
+      deps.err(err.message);
+      return err.exitCode;
+    }
+    throw err;
+  }
+
+  if (args.help) {
+    deps.log(helpText());
+    return 0;
+  }
+  if (args.version) {
+    deps.log(deps.version);
+    return 0;
+  }
+
+  if (!deps.isTTY()) {
+    deps.err("yf-vitals needs a terminal.");
+    return 1;
+  }
+
+  const dash = deps.dashboard || runDashboard;
+  return dash(args, deps);
+}
+
+/**
+ * @param {string[]} argv
+ */
+export async function run(argv) {
+  let entered = false;
+  const wrapWrite = (s) => process.stdout.write(s);
+  try {
+    const code = await main(argv, {
+      write: (s) => {
+        entered = entered || s.includes("\u001b[?1049h");
+        wrapWrite(s);
+      },
+    });
+    process.exit(typeof code === "number" ? code : 0);
+  } catch (err) {
+    if (entered) {
+      try {
+        restoreTerminal(wrapWrite, process.stdin);
+      } catch {
+        // last-ditch
+      }
+    }
+    const message = err instanceof CliError ? err.message : err?.message || String(err);
+    console.error(message);
+    process.exit(err instanceof CliError ? err.exitCode : 1);
+  }
+}

package/src/rates.js

@@ -0,0 +1,21 @@
+/**
+ * Bytes/s (or any counter/s) from two cumulative counters.
+ * First sample returns null. Counter wrap or non-positive elapsed → null.
+ *
+ * @param {number | null | undefined} prev
+ * @param {number | null | undefined} current
+ * @param {number | null | undefined} prevTs
+ * @param {number | null | undefined} currentTs
+ * @returns {number | null}
+ */
+export function rateFromCounters(prev, current, prevTs, currentTs) {
+  if (prev == null || current == null || prevTs == null || currentTs == null) {
+    return null;
+  }
+  const dtMs = Number(currentTs) - Number(prevTs);
+  if (!Number.isFinite(dtMs) || dtMs <= 0) return null;
+  const a = Number(prev);
+  const b = Number(current);
+  if (!Number.isFinite(a) || !Number.isFinite(b) || b < a) return null;
+  return (b - a) / (dtMs / 1000);
+}

package/src/render.js

@@ -0,0 +1,153 @@
+import { useAscii } from "./ascii.js";
+import { BAR_WIDTH, bar, barCharset, sparkWidth, sparkline } from "./bar.js";
+import { createColor, stripAnsi } from "./color.js";
+import {
+  formatBitRate,
+  formatBytePair,
+  formatByteRate,
+  formatBytes,
+  formatCores,
+  formatCoresDetail,
+  formatInterval,
+  formatPercent,
+} from "./format.js";
+
+/**
+ * @param {string} line
+ * @param {number} columns
+ */
+export function fitLine(line, columns) {
+  const cols = Number(columns);
+  if (!Number.isFinite(cols) || cols < 8) return line;
+  const plain = stripAnsi(line);
+  if (plain.length <= cols) return line;
+  if (plain === line) return line.slice(0, cols);
+  let out = "";
+  let visible = 0;
+  for (let i = 0; i < line.length; i += 1) {
+    if (line[i] === "\u001b") {
+      const end = line.indexOf("m", i);
+      if (end === -1) break;
+      out += line.slice(i, end + 1);
+      i = end;
+      continue;
+    }
+    if (visible >= cols) break;
+    out += line[i];
+    visible += 1;
+  }
+  return out;
+}
+
+/**
+ * @param {import("./sample.js").GpuSample | null | undefined} gpu
+ * @param {{ history: number[], ascii: boolean, color: ReturnType<typeof createColor>, sparkW: number }} opts
+ * @returns {string[] | null}
+ */
+export function buildGpuRow(gpu, opts) {
+  if (gpu == null) return null;
+  const { ascii, color, sparkW, history } = opts;
+  const cs = barCharset(ascii);
+  const pct = gpu.percent;
+  const barStr =
+    pct == null ? null : bar(pct, BAR_WIDTH, cs);
+  const pctStr = pct == null ? "n/a" : formatPercent(pct);
+  const mem =
+    gpu.used != null && gpu.total != null ? formatBytePair(gpu.used, gpu.total) : "";
+  const label = color.green("GPU");
+  const head =
+    barStr == null
+      ? `${label}  ${pctStr}${mem ? `   ${mem}` : ""}`
+      : `${label}  [${color.green(barStr)}]  ${pctStr}${mem ? `   ${mem}` : ""}`;
+  const spark = color.green(sparkline(history, sparkW, { ascii, max: 100 }));
+  return [head, `     ${spark}`];
+}
+
+/**
+ * @param {import("./sample.js").Snapshot} snap
+ * @param {import("./history.js").History} history
+ * @param {{ columns?: number, env?: NodeJS.ProcessEnv, isTTY?: boolean, intervalSec?: number }} [opts]
+ */
+export function renderFrame(snap, history, opts = {}) {
+  const columns = opts.columns ?? 80;
+  const env = opts.env ?? {};
+  const ascii = useAscii(env);
+  const color = createColor({ isTTY: Boolean(opts.isTTY), env });
+  const sparkW = sparkWidth(columns);
+  const cs = barCharset(ascii);
+  const interval = formatInterval(opts.intervalSec ?? 1);
+  const cores = formatCores(snap.physical, snap.logical);
+  const ramTot = formatBytes(snap.ramTotal);
+  const header = [
+    "yf-vitals",
+    snap.hostname || "localhost",
+    snap.osName || "unknown",
+    cores,
+    ramTot,
+    interval,
+  ].join("   ");
+
+  /** @type {string[]} */
+  const lines = [header, ""];
+
+  if (snap.cpu) {
+    const b = color.cyan(bar(snap.cpu.percent, BAR_WIDTH, cs));
+    const detail = formatCoresDetail(snap.physical, snap.logical);
+    lines.push(
+      `${color.cyan("CPU")}  [${b}]  ${formatPercent(snap.cpu.percent)}   ${detail}`,
+    );
+    lines.push(`     ${color.cyan(sparkline(history.cpu, sparkW, { ascii, max: 100 }))}`);
+  } else {
+    lines.push(`${color.cyan("CPU")}  n/a`);
+    lines.push(`     ${color.cyan(sparkline(history.cpu, sparkW, { ascii, max: 100 }))}`);
+  }
+  lines.push("");
+
+  if (snap.ram) {
+    const b = color.magenta(bar(snap.ram.percent, BAR_WIDTH, cs));
+    lines.push(
+      `${color.magenta("RAM")}  [${b}]  ${formatPercent(snap.ram.percent)}   ${formatBytePair(snap.ram.used, snap.ram.total)}`,
+    );
+    lines.push(`     ${color.magenta(sparkline(history.ram, sparkW, { ascii, max: 100 }))}`);
+  } else {
+    lines.push(`${color.magenta("RAM")}  n/a`);
+    lines.push(`     ${color.magenta(sparkline(history.ram, sparkW, { ascii, max: 100 }))}`);
+  }
+  lines.push("");
+
+  const gpuLines = buildGpuRow(snap.gpu, {
+    history: history.gpu,
+    ascii,
+    color,
+    sparkW,
+  });
+  if (gpuLines) {
+    lines.push(...gpuLines);
+    lines.push("");
+  }
+
+  if (snap.disk) {
+    const r = formatByteRate(snap.disk.readBps);
+    const w = formatByteRate(snap.disk.writeBps);
+    lines.push(`${color.green("DSK")}  R  ${r.padStart(11)}   W  ${w.padStart(11)}`);
+    lines.push(`     ${color.green(sparkline(history.dsk, sparkW, { ascii }))}`);
+  } else {
+    lines.push(`${color.green("DSK")}  n/a`);
+    lines.push(`     ${color.green(sparkline(history.dsk, sparkW, { ascii }))}`);
+  }
+  lines.push("");
+
+  if (snap.net) {
+    const up = formatBitRate(snap.net.txBps);
+    const down = formatBitRate(snap.net.rxBps);
+    lines.push(`${color.yellow("NET")}  ↑  ${up.padStart(10)}    ↓  ${down.padStart(10)}`);
+    lines.push(`     ${color.yellow(sparkline(history.net, sparkW, { ascii }))}`);
+  } else {
+    lines.push(`${color.yellow("NET")}  n/a`);
+    lines.push(`     ${color.yellow(sparkline(history.net, sparkW, { ascii }))}`);
+  }
+  lines.push("");
+  lines.push("q quit");
+
+  return lines.map((ln) => fitLine(ln, columns)).join("\n");
+}