@yourfam/yf-vitals 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YourFam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# yf-vitals
+
+Live CPU, RAM, disk, and network bars (plus GPU when the OS exposes it) in your terminal.
+
+Works on any machine with **Node 20+**. No git repo. No API key. Press **q** to quit.
+
+- **Source / README:** https://github.com/YourFam/yf-vitals
+- **npm:** https://www.npmjs.com/package/@yourfam/yf-vitals
+- **Unscoped alias:** https://www.npmjs.com/package/yf-vitals
+- **Issues:** https://github.com/YourFam/yf-vitals/issues
+
+## Install
+
+Node 20+.
+
+```bash
+npx yf-vitals
+npx yf-vitals --low-power
+npx yf-vitals --interval 0.5
+
+npm install -g @yourfam/yf-vitals
+yf-vitals
+```
+
+Friend one-liners: `npx @yourfam/yf-vitals` **and** `npx yf-vitals`.
+
+`npx yf-vitals` is the unscoped alias of `@yourfam/yf-vitals` (same CLI, same version). Both are yours.
+
+The command is `yf-vitals`. It does not need a git work tree; `cwd` can be anywhere.
+
+## What you see
+
+One live dashboard. Refresh every **1.0s** (or `--interval`, or **2.0s** with `--low-power`).
+
+| Row | Meaning |
+|---|---|
+| **CPU** | Overall utilization 0–100%, plus physical / logical core counts |
+| **RAM** | Percent used, plus used / total (`GiB` / `MiB`) |
+| **DSK** | Read and write **rates** (KiB/s, MiB/s, GiB/s) |
+| **NET** | Send ↑ and receive ↓ in **Mbps** (1 Mbps = 1e6 bit/s) |
+| **GPU** | Utilization and VRAM when telemetry exists; **the row is omitted** when it does not |
+
+Header: `yf-vitals` · hostname · OS · `NP/NL` cores · RAM total · tick interval.
+
+Each percent row has a 20-cell bar and a sparkline of the last 60 ticks. Disk and net sparklines scale to the **max in that buffer** (rates have no 100% ceiling). CPU / RAM / GPU sparklines are percent 0–100.
+
+First disk/net tick may show `—` while counters settle.
+
+`NO_COLOR` turns off ANSI. `YF_VITALS_ASCII=1` forces `#`/`-` bars and `_-=#` sparks (also used when `WT_SESSION` is missing and `TERM` looks dumb).
+
+Pipes and CI print `yf-vitals needs a terminal.` and exit 1 (no redraw loop).
+
+## Flags
+
+| Token | Default | Meaning |
+|---|---|---|
+| *(none)* | | Live dashboard, 1.0s tick |
+| `--interval <seconds>` | `1` | Tick period, `0.25`–`10`. Also `--interval=1` |
+| `--low-power` | off | Tick **2.0s** (wins over `--interval`) |
+| `--help` / `-h` | | Usage. Exit 0 |
+| `--version` / `-V` | | Package version. Exit 0 |
+
+Quit: `q` / `Q` / Ctrl+C. The terminal is restored (cursor on, no leftover alt-screen).

package/bin/yf-vitals.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from "../src/index.js";
+
+run(process.argv);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@yourfam/yf-vitals",
+  "version": "0.1.0",
+  "description": "Live terminal dashboard for CPU, RAM, disk, net, and optional GPU",
+  "type": "module",
+  "bin": {
+    "yf-vitals": "bin/yf-vitals.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "yf-vitals": "node ./bin/yf-vitals.js"
+  },
+  "keywords": [
+    "cli",
+    "cpu",
+    "ram",
+    "dashboard",
+    "sysmon"
+  ],
+  "author": {
+    "name": "YourFam",
+    "email": "kamal@yourfam.co",
+    "url": "https://github.com/YourFam"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YourFam/yf-vitals.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YourFam/yf-vitals/issues"
+  },
+  "homepage": "https://github.com/YourFam/yf-vitals#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "systeminformation": "^5.27.11"
+  }
+}

package/src/args.js

@@ -0,0 +1,104 @@
+import { CliError } from "./errors.js";
+
+const MIN_INTERVAL = 0.25;
+const MAX_INTERVAL = 10;
+const DEFAULT_INTERVAL = 1;
+const LOW_POWER_INTERVAL = 2;
+
+/**
+ * @typedef {object} ParsedArgs
+ * @property {boolean} help
+ * @property {boolean} version
+ * @property {number} interval
+ * @property {boolean} lowPower
+ */
+
+/**
+ * @param {string} flag
+ * @param {string | undefined} value
+ */
+function parseIntervalValue(flag, value) {
+  if (value == null || value === "" || value.startsWith("-")) {
+    throw new CliError(
+      `Flag ${flag} requires a number from ${MIN_INTERVAL} to ${MAX_INTERVAL}.\nSee yf-vitals --help`,
+    );
+  }
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < MIN_INTERVAL || n > MAX_INTERVAL) {
+    throw new CliError(
+      `Flag ${flag} requires a number from ${MIN_INTERVAL} to ${MAX_INTERVAL}.\nSee yf-vitals --help`,
+    );
+  }
+  return n;
+}
+
+/**
+ * @param {string[]} argv process.argv
+ * @returns {ParsedArgs}
+ */
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  let help = false;
+  let version = false;
+  let interval = DEFAULT_INTERVAL;
+  let intervalSet = false;
+  let lowPower = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if (a === "--help" || a === "-h") {
+      help = true;
+    } else if (a === "--version" || a === "-V") {
+      version = true;
+    } else if (a === "--low-power") {
+      lowPower = true;
+    } else if (a === "--interval") {
+      interval = parseIntervalValue("--interval", args[i + 1]);
+      intervalSet = true;
+      i += 1;
+    } else if (a.startsWith("--interval=")) {
+      interval = parseIntervalValue("--interval", a.slice("--interval=".length));
+      intervalSet = true;
+    } else if (a.startsWith("-")) {
+      throw new CliError(`Unknown flag: ${a}\nSee yf-vitals --help`);
+    } else {
+      throw new CliError(`Unknown argument: ${a}\nSee yf-vitals --help`);
+    }
+  }
+
+  if (help || version) {
+    return {
+      help,
+      version,
+      interval: DEFAULT_INTERVAL,
+      lowPower: false,
+    };
+  }
+
+  if (lowPower) {
+    interval = LOW_POWER_INTERVAL;
+  } else if (!intervalSet) {
+    interval = DEFAULT_INTERVAL;
+  }
+
+  return { help: false, version: false, interval, lowPower };
+}
+
+export function helpText() {
+  return `yf-vitals — live CPU, RAM, disk, net (and GPU) bars in the terminal
+
+Usage:
+  yf-vitals
+  yf-vitals --low-power
+  yf-vitals --interval 0.5
+
+  --interval <seconds>   Tick period (${MIN_INTERVAL}–${MAX_INTERVAL}, default ${DEFAULT_INTERVAL})
+  --low-power            Tick every ${LOW_POWER_INTERVAL}s (wins over --interval)
+  --help, -h             This text
+  --version, -V          Package version
+
+q / Q / Ctrl+C quit. GPU row is omitted when the OS has no GPU telemetry.
+Disk rates are MiB/s; network rates are Mbps.
+Disk / net sparklines scale to the max in the last 60 ticks (no 100% ceiling).
+Needs a terminal (no pipes). Node 20+.`;
+}

package/src/ascii.js

@@ -0,0 +1,12 @@
+const DUMB_TERM = /^(dumb|unknown)?$/i;
+
+/**
+ * ASCII bars when YF_VITALS_ASCII=1, or when WT_SESSION is missing and TERM looks dumb.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function useAscii(env = process.env) {
+  if (env.YF_VITALS_ASCII === "1") return true;
+  const term = env.TERM ?? "";
+  const dumb = DUMB_TERM.test(term);
+  return !env.WT_SESSION && dumb;
+}

package/src/bar.js

@@ -0,0 +1,83 @@
+export const BAR_WIDTH = 20;
+export const HISTORY_SIZE = 60;
+export const SPARK_MIN = 16;
+export const SPARK_MAX = 60;
+export const SPARK_GUTTER = 36;
+
+export const UNI_BAR_FILLED = "█";
+export const UNI_BAR_EMPTY = "░";
+export const ASC_BAR_FILLED = "#";
+export const ASC_BAR_EMPTY = "-";
+
+export const UNI_SPARK = "▁▂▃▄▅▆▇█";
+export const ASC_SPARK = "_-=#";
+
+/**
+ * @param {number} percent
+ * @param {number} width
+ * @param {{ filled?: string, empty?: string }} [opts]
+ */
+export function bar(percent, width, opts = {}) {
+  const filled = opts.filled ?? UNI_BAR_FILLED;
+  const empty = opts.empty ?? UNI_BAR_EMPTY;
+  const w = Math.max(0, Math.floor(width));
+  const n = Number(percent);
+  const p = Number.isFinite(n) ? Math.min(100, Math.max(0, n)) : 0;
+  const fillCount = w === 0 ? 0 : Math.round((p / 100) * w);
+  return filled.repeat(fillCount) + empty.repeat(w - fillCount);
+}
+
+/**
+ * @param {boolean} ascii
+ */
+export function barCharset(ascii) {
+  return ascii
+    ? { filled: ASC_BAR_FILLED, empty: ASC_BAR_EMPTY }
+    : { filled: UNI_BAR_FILLED, empty: UNI_BAR_EMPTY };
+}
+
+/**
+ * @param {number} columns
+ */
+export function sparkWidth(columns) {
+  const cols = Number(columns);
+  const available = Number.isFinite(cols) && cols > 0 ? cols - SPARK_GUTTER : SPARK_MAX;
+  return Math.max(SPARK_MIN, Math.min(SPARK_MAX, available));
+}
+
+/**
+ * @param {number[]} values
+ * @param {number} width
+ * @param {{ ascii?: boolean, max?: number }} [opts]
+ */
+export function sparkline(values, width, opts = {}) {
+  const w = Math.max(0, Math.floor(width));
+  if (w === 0) return "";
+  const charset = opts.ascii ? ASC_SPARK : UNI_SPARK;
+  const list = Array.isArray(values) ? values : [];
+  if (list.length === 0) {
+    return " ".repeat(w);
+  }
+  const slice = list.slice(-w);
+  const pad = w - slice.length;
+  const explicitMax = opts.max;
+  const dataMax = slice.reduce((m, v) => (v > m ? v : m), 0);
+  const max = explicitMax != null ? explicitMax : dataMax;
+  const chars = slice.map((v) => sparkChar(v, max, charset));
+  return " ".repeat(pad) + chars.join("");
+}
+
+/**
+ * @param {number} value
+ * @param {number} max
+ * @param {string} charset
+ */
+function sparkChar(value, max, charset) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0 || !Number.isFinite(max) || max <= 0) {
+    return charset[0];
+  }
+  const ratio = Math.min(1, n / max);
+  const idx = Math.round(ratio * (charset.length - 1));
+  return charset[idx];
+}

package/src/color.js

@@ -0,0 +1,24 @@
+import picocolors from "picocolors";
+
+/**
+ * @param {{ isTTY: boolean, env: NodeJS.ProcessEnv }} opts
+ */
+export function createColor(opts) {
+  const enabled = Boolean(opts.isTTY) && opts.env.NO_COLOR === undefined;
+  const pc = picocolors.createColors(enabled);
+  return {
+    enabled,
+    cyan: (value) => pc.cyan(String(value)),
+    magenta: (value) => pc.magenta(String(value)),
+    green: (value) => pc.green(String(value)),
+    yellow: (value) => pc.yellow(String(value)),
+    dim: (value) => pc.dim(String(value)),
+  };
+}
+
+/**
+ * @param {string} value
+ */
+export function stripAnsi(value) {
+  return String(value).replace(/\u001b\[[0-9;]*m/g, "");
+}

package/src/dashboard.js

@@ -0,0 +1,125 @@
+import { appendHistory, createHistory } from "./history.js";
+import { renderFrame } from "./render.js";
+import { createSampler, mergeLastGood } from "./sample.js";
+import { CLEAR_HOME, enterTerminal, restoreTerminal } from "./tty.js";
+
+const CTRL_C = 0x03;
+
+/**
+ * @param {Buffer | string} chunk
+ */
+function isQuitKey(chunk) {
+  if (chunk == null) return false;
+  const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+  if (buf.length === 0) return false;
+  if (buf[0] === CTRL_C) return true;
+  const s = buf.toString("utf8");
+  return s.includes("q") || s.includes("Q");
+}
+
+/**
+ * @param {number} ms
+ * @param {() => boolean} shouldStop
+ */
+export function sleep(ms, shouldStop) {
+  const n = Math.max(0, Number(ms) || 0);
+  return new Promise((resolve) => {
+    if (n === 0 || shouldStop()) {
+      resolve();
+      return;
+    }
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(t);
+      clearInterval(iv);
+      resolve();
+    };
+    const t = setTimeout(done, n);
+    const iv = setInterval(() => {
+      if (shouldStop()) done();
+    }, 50);
+  });
+}
+
+/**
+ * @param {import("./args.js").ParsedArgs} args
+ * @param {object} deps
+ */
+export async function runDashboard(args, deps) {
+  const write = deps.write;
+  const stdin = deps.stdin;
+  let quit = false;
+  let restored = false;
+  const shouldStop = () => quit || Boolean(deps.shouldStop?.());
+
+  const restore = () => {
+    if (restored) return;
+    restored = true;
+    restoreTerminal(write, stdin);
+  };
+
+  enterTerminal(write, stdin);
+
+  const onData = (chunk) => {
+    if (isQuitKey(chunk)) quit = true;
+  };
+  const onSig = () => {
+    quit = true;
+  };
+
+  const proc = deps.process ?? process;
+  if (stdin && typeof stdin.on === "function") stdin.on("data", onData);
+  if (proc && typeof proc.on === "function") {
+    proc.on("SIGINT", onSig);
+    proc.on("SIGTERM", onSig);
+  }
+
+  /** @type {{ sample: Function, close?: Function } | null} */
+  let sampler = null;
+  try {
+    sampler = deps.sampler || createSampler();
+    let history = createHistory();
+    /** @type {import("./sample.js").Snapshot | null} */
+    let last = null;
+
+    while (!shouldStop()) {
+      let snap;
+      try {
+        snap = await sampler.sample();
+      } catch {
+        snap = last;
+      }
+      if (!snap) {
+        await (deps.sleep || sleep)(args.interval * 1000, shouldStop);
+        continue;
+      }
+      snap = mergeLastGood(last, snap);
+      last = snap;
+      history = appendHistory(history, snap);
+      const frame = renderFrame(snap, history, {
+        columns: deps.columns(),
+        env: deps.env,
+        isTTY: true,
+        intervalSec: args.interval,
+      });
+      write(CLEAR_HOME + frame);
+      if (shouldStop()) break;
+      await (deps.sleep || sleep)(args.interval * 1000, shouldStop);
+    }
+    return 0;
+  } finally {
+    try {
+      sampler?.close?.();
+    } catch {
+      // ignore
+    }
+    if (stdin && typeof stdin.off === "function") stdin.off("data", onData);
+    if (proc && typeof proc.off === "function") {
+      proc.off("SIGINT", onSig);
+      proc.off("SIGTERM", onSig);
+    }
+    restore();
+  }
+}

package/src/disk.js

@@ -0,0 +1,110 @@
+import { spawn } from "node:child_process";
+
+const PS_DISK = `
+$ErrorActionPreference = 'SilentlyContinue'
+while (($line = [Console]::In.ReadLine()) -ne $null) {
+  if ($line -eq 'q') { break }
+  $d = Get-CimInstance -ClassName Win32_PerfRawData_PerfDisk_PhysicalDisk -Filter "Name='_Total'"
+  if ($d) { Write-Output ("{0} {1}" -f $d.DiskReadBytesPersec, $d.DiskWriteBytesPersec) }
+  else { Write-Output "n n" }
+}
+`.trim();
+
+/**
+ * @param {string} line
+ * @returns {{ rx: number, wx: number } | null}
+ */
+export function parseDiskCounterLine(line) {
+  const m = String(line || "").trim().match(/^(\d+)\s+(\d+)$/);
+  if (!m) return null;
+  return { rx: Number(m[1]), wx: Number(m[2]) };
+}
+
+function encodedCommand(script) {
+  return Buffer.from(script, "utf16le").toString("base64");
+}
+
+/**
+ * Long-lived PowerShell so WMI stays warm (~10ms/tick after first query).
+ */
+export function createWindowsDiskReader() {
+  let child = null;
+  let buf = "";
+  /** @type {{ resolve: (v: { rx: number, wx: number } | null) => void }[]} */
+  let pending = [];
+  let closed = false;
+
+  function flushLine(line) {
+    const job = pending.shift();
+    if (job) job.resolve(parseDiskCounterLine(line));
+  }
+
+  function ensure() {
+    if (child || closed) return;
+    child = spawn(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-EncodedCommand", encodedCommand(PS_DISK)],
+      { windowsHide: true, stdio: ["pipe", "pipe", "ignore"] },
+    );
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      buf += chunk;
+      let idx;
+      while ((idx = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, idx);
+        buf = buf.slice(idx + 1);
+        flushLine(line);
+      }
+    });
+    child.on("exit", () => {
+      child = null;
+      buf = "";
+      while (pending.length) {
+        pending.shift()?.resolve(null);
+      }
+    });
+  }
+
+  return {
+    /**
+     * @returns {Promise<{ rx: number, wx: number } | null>}
+     */
+    read() {
+      if (closed) return Promise.resolve(null);
+      ensure();
+      if (!child || !child.stdin.writable) return Promise.resolve(null);
+      return new Promise((resolve) => {
+        const t = setTimeout(() => {
+          const i = pending.findIndex((p) => p.resolve === done);
+          if (i >= 0) pending.splice(i, 1);
+          resolve(null);
+        }, 2500);
+        const done = (v) => {
+          clearTimeout(t);
+          resolve(v);
+        };
+        pending.push({ resolve: done });
+        try {
+          child.stdin.write("g\n");
+        } catch {
+          clearTimeout(t);
+          resolve(null);
+        }
+      });
+    },
+    close() {
+      closed = true;
+      try {
+        child?.stdin.write("q\n");
+      } catch {
+        // ignore
+      }
+      try {
+        child?.kill();
+      } catch {
+        // ignore
+      }
+      child = null;
+    },
+  };
+}

package/src/errors.js

@@ -0,0 +1,11 @@
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} [exitCode]
+   */
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+  }
+}