@hienlh/ppm 0.23.6 → 0.23.7

package/src/services/system-metrics/linux-fs.ts

@@ -0,0 +1,43 @@
+/**
+ * Injectable filesystem access for the /proc and /sys collectors, so every parser
+ * is fixture-tested without a real host. Each call returns null instead of
+ * throwing: a device or a process vanishing between a directory listing and the
+ * read is the normal case here, not an error worth a stack trace per tick.
+ */
+import { existsSync, readdirSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+
+export type FileReader = (path: string) => string | null;
+export type DirLister = (path: string) => string[] | null;
+export type LinkReader = (path: string) => string | null;
+
+export interface LinuxFs {
+  read: FileReader;
+  list: DirLister;
+  /** The link's own target, as written (often relative: `../../devices/...`). */
+  readlink: LinkReader;
+  /** Fully resolved absolute path, or null when it does not resolve. */
+  realpath: LinkReader;
+  exists: (path: string) => boolean;
+}
+
+export const realLinuxFs: LinuxFs = {
+  read: (path) => { try { return readFileSync(path, "utf-8"); } catch { return null; } },
+  list: (path) => { try { return readdirSync(path); } catch { return null; } },
+  readlink: (path) => { try { return readlinkSync(path); } catch { return null; } },
+  realpath: (path) => { try { return realpathSync(path); } catch { return null; } },
+  exists: (path) => existsSync(path),
+};
+
+/** A sysfs attribute as a trimmed string, or undefined when absent or blank. */
+export function readAttr(fs: Pick<LinuxFs, "read">, path: string): string | undefined {
+  const v = fs.read(path)?.trim();
+  return v ? v : undefined;
+}
+
+/** A sysfs attribute as a finite number, or undefined. */
+export function readNumber(fs: Pick<LinuxFs, "read">, path: string): number | undefined {
+  const v = readAttr(fs, path);
+  if (v === undefined) return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}

package/src/services/system-metrics/memory-darwin.ts

@@ -0,0 +1,91 @@
+/**
+ * macOS swap, which is the one memory figure the platform publishes and `node:os`
+ * does not.
+ *
+ * Off Linux every swap field was absent, and the memory page renders an absent
+ * field as an em dash — i.e. as the claim "this host's swap cannot be measured".
+ * On a Mac it can: `vm.swapusage` is a single sysctl. On the host this was found
+ * on it read **8047 MB of 9216 MB in use**, which is the most consequential thing
+ * that page could have been saying about the machine and was saying nothing about.
+ *
+ * `vm_stat` is deliberately not used here. It carries page counts but no swap at
+ * all, and the page counts are not needed: `os.freemem()` on darwin agrees with
+ * what `top` calls unused (75 MB against PPM's 124 MB on the same host, sampled
+ * seconds apart), so the cross-platform figure is already the one Activity
+ * Monitor shows. Do not "fix" it against `memory_pressure`, whose free
+ * percentage measures what could be reclaimed under duress and read 56% on a
+ * machine `top` called 31G used.
+ *
+ * The per-tick cost was measured rather than assumed, because this runs on every
+ * tick: **1.33 ms/call**, against the 1.7 ms `/proc/<pid>/io` already costs per
+ * tick on Linux. It stays `spawnSync` because `collectMemory` is synchronous and
+ * making the whole memory step async for one number is the larger change.
+ */
+import type { MemoryMetrics } from "../../types/system-metrics.ts";
+
+type SwapFields = Pick<MemoryMetrics, "swapTotalMB" | "swapUsedMB">;
+
+/** `total = 9216.00M  used = 8047.00M  free = 1169.00M  (encrypted)` */
+const SWAP_RE = /total\s*=\s*([\d.]+)([KMGT])?\b[\s\S]*?used\s*=\s*([\d.]+)([KMGT])?\b/i;
+
+const MB_PER_UNIT: Record<string, number> = { K: 1 / 1024, M: 1, G: 1024, T: 1024 * 1024 };
+
+const round1 = (n: number): number => Math.round(n * 10) / 10;
+
+/**
+ * Pure half, so the format can be tested without a Mac.
+ *
+ * `undefined` rather than zeroes when the text does not parse: a shape this code
+ * does not recognise is a host it did not measure, and 0 would be a claim that
+ * the machine has no swap.
+ */
+export function parseSwapUsage(text: string | null | undefined): SwapFields | undefined {
+  if (!text) return undefined;
+  const m = SWAP_RE.exec(text);
+  if (!m) return undefined;
+
+  const toMB = (value: string, unit: string | undefined): number | null => {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0) return null;
+    // A bare number is bytes. The format normally carries a suffix, but a swap
+    // file of zero prints as `0.00M` on some releases and `0` on others, and
+    // reading that second form as megabytes would invent 0 MB either way — it
+    // is only correct here because the value is zero.
+    return unit ? n * (MB_PER_UNIT[unit.toUpperCase()] ?? 1) : n / (1024 * 1024);
+  };
+
+  const total = toMB(m[1]!, m[2]);
+  const used = toMB(m[3]!, m[4]);
+  if (total === null || used === null) return undefined;
+
+  return {
+    swapTotalMB: round1(total),
+    // Clamped, because a used figure above the total is not a bigger swap, it is
+    // a sample taken while the file was being resized.
+    swapUsedMB: round1(Math.min(Math.max(used, 0), total)),
+  };
+}
+
+/**
+ * `null` on every platform but darwin, so nothing is spawned where the figure
+ * already comes from `/proc/meminfo` or from CIM.
+ */
+export function readSwapUsage(): string | null {
+  if (process.platform !== "darwin") return null;
+  try {
+    const result = Bun.spawnSync(["sysctl", "-n", "vm.swapusage"], {
+      stdout: "pipe",
+      stderr: "ignore",
+      stdin: "ignore",
+    });
+    if (result.exitCode !== 0) return null;
+    return new TextDecoder().decode(result.stdout);
+  } catch {
+    // `Bun.spawn` raises `Executable not found in $PATH` *synchronously* for a
+    // missing binary rather than reporting it through an exit code, and
+    // `spawnSync` is no different — the same trap `spawn-runner.ts` carries a
+    // comment about. A stripped-down host without `sysctl` gets an em dash, not
+    // a collector that throws mid-tick.
+    return null;
+  }
+}

package/src/services/system-metrics/memory-linux.ts

@@ -0,0 +1,156 @@
+/**
+ * Mission Center's memory page: the composition bar and the figures under it,
+ * all from `/proc/meminfo`, plus the populated slots from the SMBIOS table udev
+ * already decoded into its database (the raw table needs root; this does not).
+ */
+import type { MemoryMetrics } from "../../types/system-metrics.ts";
+import type { MemoryDeviceInfo, MemoryInfo } from "../../types/system-hardware.ts";
+import { realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+import { readUdevProperties, udevValue } from "./udev-db.ts";
+
+/** udev's own name for the SMBIOS record. */
+export const DMI_UDEV_DEVICE = "+dmi:id";
+const MB = 1024 * 1024;
+
+/** Every `Key: N kB` line as BYTES. Values without a unit (the HugePages counts)
+ *  are kept verbatim, which is what they mean. */
+export function parseMeminfo(text: string): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const line of text.split("\n")) {
+    const sep = line.indexOf(":");
+    if (sep < 0) continue;
+    const rest = line.slice(sep + 1).trim();
+    const [rawValue, unit] = rest.split(/\s+/);
+    const n = Number(rawValue);
+    if (!Number.isFinite(n)) continue;
+    out.set(line.slice(0, sep), unit === "kB" ? n * 1024 : n);
+  }
+  return out;
+}
+
+/**
+ * Adds the composition and the swap/commit figures to the cross-platform base.
+ *
+ * The four parts add up to the total EXACTLY and "in use" is exactly the headline
+ * `usedMB` (total - MemAvailable), so the bar and the figure beside it can never
+ * disagree. Standby is the rest of what the kernel would hand back on demand
+ * (MemAvailable - MemFree), and modified is carved out of it rather than added —
+ * a dirty page is also a cached page, so adding the two would overflow the bar.
+ */
+export function enrichMemory(
+  base: MemoryMetrics,
+  text: string | null,
+  zram: ZramTotals | undefined = undefined,
+): MemoryMetrics {
+  if (!text) return base;
+  const m = parseMeminfo(text);
+  const total = m.get("MemTotal");
+  if (total === undefined || total <= 0) return base;
+
+  const get = (k: string) => m.get(k) ?? 0;
+  const free = clamp(get("MemFree"), 0, total);
+  const available = clamp(m.get("MemAvailable") ?? free, free, total);
+  const reclaimable = available - free;
+  const modified = clamp(get("Dirty") + get("Writeback"), 0, reclaimable);
+  const swapTotal = get("SwapTotal");
+
+  return {
+    ...base,
+    inUseBytes: total - available,
+    modifiedBytes: modified,
+    standbyBytes: reclaimable - modified,
+    freeBytes: free,
+    cachedMB: round1(get("Cached") / MB),
+    committedMB: round1(get("Committed_AS") / MB),
+    commitLimitMB: round1(get("CommitLimit") / MB),
+    swapTotalMB: round1(swapTotal / MB),
+    swapUsedMB: round1(Math.max(swapTotal - get("SwapFree"), 0) / MB),
+    ...(zram
+      ? {
+          zramCompressedMB: round1(zram.compressedBytes / MB),
+          zramSavingsMB: round1(zram.savingsBytes / MB),
+        }
+      : {}),
+  };
+}
+
+export interface ZramTotals {
+  compressedBytes: number;
+  savingsBytes: number;
+}
+
+/**
+ * `/sys/block/zram<N>/mm_stat`, summed over every device — a host can have one
+ * per CPU. Undefined when there is no zram at all, which is a different answer
+ * from a zram holding nothing: the Memory page hides the rows in the first case
+ * and shows zeroes in the second.
+ *
+ * Field order (Documentation/admin-guide/blockdev/zram.rst): orig_data_size,
+ * compr_data_size, mem_used_total, mem_limit, mem_used_max, same_pages,
+ * pages_compacted, huge_pages. Savings is orig minus compr, which is what
+ * Mission Center shows — NOT orig minus mem_used_total, which also subtracts
+ * zram's own allocator overhead and reads several percent low.
+ */
+export function readZramTotals(fs: LinuxFs = realLinuxFs): ZramTotals | undefined {
+  const devices = (fs.list("/sys/block") ?? []).filter((n) => /^zram\d+$/.test(n));
+  if (devices.length === 0) return undefined;
+  let compressedBytes = 0;
+  let savingsBytes = 0;
+  let any = false;
+  for (const dev of devices) {
+    const stat = fs.read(`/sys/block/${dev}/mm_stat`)?.trim().split(/\s+/);
+    if (!stat || stat.length < 2) continue;
+    const orig = Number(stat[0]);
+    const compr = Number(stat[1]);
+    if (!Number.isFinite(orig) || !Number.isFinite(compr)) continue;
+    any = true;
+    compressedBytes += compr;
+    savingsBytes += Math.max(0, orig - compr);
+  }
+  return any ? { compressedBytes, savingsBytes } : undefined;
+}
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(Math.max(v, lo), hi);
+
+/** The populated slots, in board order. `MEMORY_DEVICE_<n>_*` is udev's decode of
+ *  SMBIOS type 17; an empty slot has no `SIZE`, so it simply does not appear. */
+export function readMemoryInfo(fs: Pick<LinuxFs, "read"> = realLinuxFs): MemoryInfo {
+  const props = readUdevProperties(DMI_UDEV_DEVICE, fs.read);
+  const devices: MemoryDeviceInfo[] = [];
+
+  for (let i = 0; ; i++) {
+    const prefix = `MEMORY_DEVICE_${i}_`;
+    const locator = udevValue(props, `${prefix}LOCATOR`);
+    const size = Number(udevValue(props, `${prefix}SIZE`));
+    // udev numbers the slots contiguously, so the first gap is the end of the list.
+    if (!locator && !Number.isFinite(size)) break;
+    if (i > 64) break;
+    if (!locator || !Number.isFinite(size) || size <= 0) continue;
+    devices.push({
+      locator,
+      sizeBytes: size,
+      ...defined("bankLocator", udevValue(props, `${prefix}BANK_LOCATOR`)),
+      ...defined("formFactor", udevValue(props, `${prefix}FORM_FACTOR`)),
+      ...defined("ramType", udevValue(props, `${prefix}TYPE`)),
+      ...defined("speedMts", positive(udevValue(props, `${prefix}SPEED_MTS`))),
+      ...defined("manufacturer", udevValue(props, `${prefix}MANUFACTURER`)),
+      ...defined("rank", positive(udevValue(props, `${prefix}RANK`))),
+    });
+  }
+
+  return {
+    devices,
+    ...defined("maxCapacityBytes", positive(udevValue(props, "MEMORY_ARRAY_MAX_CAPACITY"))),
+  };
+}
+
+const round1 = (n: number) => Math.round(n * 10) / 10;
+
+function positive(raw: string | undefined): number | undefined {
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+function defined<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
+  return value === undefined ? {} : ({ [key]: value } as Record<K, V>);
+}

package/src/services/system-metrics/net-devices-linux.ts

@@ -0,0 +1,114 @@
+/**
+ * Per-interface figures for the Performance page's network entries, from
+ * `/sys/class/net/<if>/`. Throughput is the same counter Mission Center reads
+ * (`statistics/rx_bytes`, `tx_bytes`); the link state comes from the kernel's
+ * own `operstate`/`carrier` rather than from NetworkManager, so it is right on a
+ * host that does not run NetworkManager at all.
+ */
+import type { NicMetrics, NicState } from "../../types/system-metrics.ts";
+import { readAttr, readNumber, realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+
+export const SYS_NET = "/sys/class/net";
+/** ARPHRD_LOOPBACK. Mission Center drops interfaces named `lo*`; the type is exact. */
+const ARPHRD_LOOPBACK = 772;
+const IFF_UP = 0x1;
+
+export interface NicSample {
+  atSec: number;
+  rx: number;
+  tx: number;
+}
+
+/** Previous sample per interface name. */
+export type NicSampleState = Map<string, NicSample>;
+
+/** Live wireless facts for one interface; the collector takes them as data so it
+ *  never spawns anything itself. */
+export interface WirelessStatus {
+  ssid?: string;
+  signalPercent?: number;
+  frequencyMHz?: number;
+}
+
+export function listNetInterfaces(fs: Pick<LinuxFs, "list" | "read"> = realLinuxFs): string[] {
+  const names = fs.list(SYS_NET);
+  if (!names) return [];
+  return names.filter((n) => readNumber(fs, `${SYS_NET}/${n}/type`) !== ARPHRD_LOOPBACK).sort();
+}
+
+/** `operstate` is RFC 2863's, verbatim. `unknown` is what tun, wireguard and
+ *  other virtual interfaces report for their whole life, so those are decided by
+ *  carrier plus the admin flag instead. */
+export function nicState(
+  operstate: string | undefined,
+  carrier: string | undefined,
+  flags: string | undefined,
+): NicState {
+  switch (operstate) {
+    case "up": return "connected";
+    case "dormant":
+    case "testing": return "connecting";
+    case "down": return "disconnected";
+    case "notpresent":
+    case "lowerlayerdown": return "unavailable";
+    case "unknown": {
+      const up = (Number.parseInt(flags ?? "0", 16) & IFF_UP) !== 0;
+      return carrier === "1" && up ? "connected" : "unknown";
+    }
+    default: return "unknown";
+  }
+}
+
+export interface NicDeviceCollection {
+  nics: NicMetrics[];
+  next: NicSampleState;
+}
+
+export function collectLinuxNicDevices(
+  prev: NicSampleState,
+  fs: Pick<LinuxFs, "list" | "read"> = realLinuxFs,
+  now: () => number = Date.now,
+  wireless: ReadonlyMap<string, WirelessStatus> = new Map(),
+): NicDeviceCollection {
+  const atSec = now() / 1000;
+  const next: NicSampleState = new Map();
+  const nics: NicMetrics[] = [];
+
+  for (const id of listNetInterfaces(fs)) {
+    const rx = readNumber(fs, `${SYS_NET}/${id}/statistics/rx_bytes`);
+    const tx = readNumber(fs, `${SYS_NET}/${id}/statistics/tx_bytes`);
+    if (rx === undefined || tx === undefined) continue;
+    const sample: NicSample = { atSec, rx, tx };
+    next.set(id, sample);
+
+    // `speed` is -1 with no link, and reading it EINVALs on a virtual interface.
+    const speed = readNumber(fs, `${SYS_NET}/${id}/speed`);
+    nics.push({
+      ...toNicMetrics(id, prev.get(id) ?? null, sample),
+      state: nicState(
+        readAttr(fs, `${SYS_NET}/${id}/operstate`),
+        readAttr(fs, `${SYS_NET}/${id}/carrier`),
+        readAttr(fs, `${SYS_NET}/${id}/flags`),
+      ),
+      ...(speed !== undefined && speed > 0 ? { linkMbps: speed } : {}),
+      ...(wireless.get(id) ?? {}),
+    });
+  }
+  return { nics, next };
+}
+
+/** Rates only — the caller adds state and link facts. */
+export function toNicMetrics(id: string, prev: NicSample | null, next: NicSample): NicMetrics {
+  const base: NicMetrics = {
+    id, available: false, rxBps: 0, txBps: 0, rxTotal: next.rx, txTotal: next.tx, state: "unknown",
+  };
+  const dt = prev ? next.atSec - prev.atSec : 0;
+  // The kernel zeroes these when an interface is recreated under the same name.
+  if (!prev || !Number.isFinite(dt) || dt <= 0 || next.rx < prev.rx || next.tx < prev.tx) return base;
+  return {
+    ...base,
+    available: true,
+    rxBps: Math.round((next.rx - prev.rx) / dt),
+    txBps: Math.round((next.tx - prev.tx) / dt),
+  };
+}

package/src/services/system-metrics/net-inventory-linux.ts

@@ -0,0 +1,100 @@
+/**
+ * Static facts about each network interface: what kind it is, the adapter's
+ * marketing name, its driver, MAC and addresses.
+ *
+ * Mission Center classifies by NetworkManager's device type and falls back to a
+ * table of name prefixes — and its type read always fails (it asks for a u64
+ * where NM publishes a u32), so in practice the prefix table is all that ever
+ * runs. PPM asks sysfs and udev first, which are exact, and keeps that same
+ * prefix table only as the last resort.
+ */
+import { networkInterfaces } from "node:os";
+import type { NicInfo, NicKind } from "../../types/system-hardware.ts";
+import { readAttr, readNumber, realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+import { readUdevProperties, udevValue } from "./udev-db.ts";
+import { listNetInterfaces, SYS_NET } from "./net-devices-linux.ts";
+
+const ARPHRD_INFINIBAND = 32;
+/** `tun_flags` bit 0: a TUN (layer 3) device, i.e. a tunnel rather than a tap. */
+const IFF_TUN = 0x1;
+
+export function readNicInventory(
+  fs: LinuxFs = realLinuxFs,
+  addresses: () => AddressMap = readAddresses,
+): NicInfo[] {
+  const addrs = addresses();
+  return listNetInterfaces(fs).map((id) => readNicInfo(id, fs, addrs[id]));
+}
+
+export function readNicInfo(id: string, fs: LinuxFs, addr: Addresses | undefined): NicInfo {
+  const udev = readUdevProperties(`n${readAttr(fs, `${SYS_NET}/${id}/ifindex`) ?? ""}`, fs.read);
+  const driver = udevValue(udev, "ID_NET_DRIVER")
+    ?? basename(fs.readlink(`${SYS_NET}/${id}/device/driver`) ?? "");
+
+  return {
+    id,
+    kind: nicKind(id, fs),
+    ...optional("deviceName", udevValue(udev, "ID_MODEL_FROM_DATABASE")),
+    ...optional("driver", driver || undefined),
+    ...optional("mac", readAttr(fs, `${SYS_NET}/${id}/address`)),
+    ipv4: addr?.ipv4 ?? [],
+    ipv6: addr?.ipv6 ?? [],
+  };
+}
+
+/** sysfs facts first, Mission Center's prefix table only when none of them apply. */
+export function nicKind(id: string, fs: Pick<LinuxFs, "read" | "exists">): NicKind {
+  const devtype = uevent(fs, id).get("DEVTYPE");
+  if (devtype === "wireguard") return "vpn";
+  if (devtype === "wlan" || fs.exists(`${SYS_NET}/${id}/wireless`)) return "wireless";
+  if (readNumber(fs, `${SYS_NET}/${id}/type`) === ARPHRD_INFINIBAND) return "infiniband";
+  if (devtype === "bridge") return id.startsWith("docker") ? "docker" : "bridge";
+  // A TUN device is a tunnel by construction — Mission Center has no rule for
+  // these and files every one of them (tailscale0, tun0, nordlynx) under "other".
+  const tunFlags = readAttr(fs, `${SYS_NET}/${id}/tun_flags`);
+  if (tunFlags && (Number.parseInt(tunFlags, 16) & IFF_TUN) !== 0) return "vpn";
+  return kindFromName(id);
+}
+
+/** Mission Center's `connection_kind_from_name`, order included. */
+export function kindFromName(id: string): NicKind {
+  if (id.startsWith("bn")) return "bluetooth";
+  if (id.startsWith("br") || id.startsWith("virbr")) return "bridge";
+  if (id.startsWith("docker")) return "docker";
+  if (id.startsWith("eth") || id.startsWith("en")) return "wired";
+  if (id.startsWith("ib")) return "infiniband";
+  if (id.startsWith("mp")) return "multipass";
+  if (id.startsWith("veth")) return "virtual";
+  if (id.startsWith("vpn") || id.startsWith("wg")) return "vpn";
+  if (id.startsWith("wl") || id.startsWith("ww")) return "wireless";
+  return "other";
+}
+
+function uevent(fs: Pick<LinuxFs, "read">, id: string): Map<string, string> {
+  const props = new Map<string, string>();
+  for (const line of (fs.read(`${SYS_NET}/${id}/uevent`) ?? "").split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq > 0) props.set(line.slice(0, eq), line.slice(eq + 1).trim());
+  }
+  return props;
+}
+
+export interface Addresses { ipv4: string[]; ipv6: string[] }
+export type AddressMap = Record<string, Addresses>;
+
+export function readAddresses(): AddressMap {
+  const map: AddressMap = {};
+  for (const [name, addrs] of Object.entries(networkInterfaces())) {
+    for (const a of addrs ?? []) {
+      const entry = (map[name] ??= { ipv4: [], ipv6: [] });
+      (a.family === "IPv4" ? entry.ipv4 : entry.ipv6).push(a.address);
+    }
+  }
+  return map;
+}
+
+const basename = (p: string) => p.slice(p.lastIndexOf("/") + 1);
+
+function optional<K extends string>(key: K, value: string | undefined): Partial<Record<K, string>> {
+  return value === undefined ? {} : ({ [key]: value } as Record<K, string>);
+}

package/src/services/system-metrics/partitions-linux.ts

@@ -0,0 +1,158 @@
+/**
+ * Partitions of a whole disk, with what is mounted on them and how full it is —
+ * Mission Center's Partitions section on the drive page.
+ *
+ * Mission Center asks udisks2 over D-Bus. This reads sysfs for the partition
+ * list, `/proc/self/mountinfo` for the mounts and `statfs` for the usage, so it
+ * needs neither a system bus nor root.
+ *
+ * The usage figures are read with the ASYNC `statfs`, deliberately: PPM serves
+ * every request and every chat session from one event loop, and `statfsSync` on
+ * a mount whose device is spinning up (or an autofs mount that is cold) blocks
+ * that loop for as long as the kernel takes. It is also why this is not on the
+ * 2 s tick — it belongs to the inventory, which is fetched on demand.
+ */
+import type { DiskInfo, PartitionInfo, PartitionMount } from "../../types/system-hardware.ts";
+import { readAttr, readNumber, realLinuxFs, type LinuxFs } from "./linux-fs.ts";
+import { readUdevProperties, udevValue } from "./udev-db.ts";
+import { SYS_BLOCK } from "./disk-devices-linux.ts";
+
+const SECTOR_BYTES = 512;
+const MOUNTINFO = "/proc/self/mountinfo";
+
+/** One mount as `/proc/self/mountinfo` describes it. */
+export interface MountEntry {
+  /** mountinfo's major:minor. For ext4 this is the block device's own, but a
+   *  filesystem that can span devices registers an ANONYMOUS one instead — every
+   *  btrfs mount on this host reports `0:35` rather than `259:2` — so this alone
+   *  finds no mount at all on a btrfs root, which is most Arch installs. */
+  deviceId: string;
+  /** The device as the kernel records it, "/dev/nvme0n1p2". This is what matches
+   *  a btrfs partition; `deviceId` is what still matches when the source is a
+   *  label or a stacked device. Both are needed. */
+  source: string;
+  /** Which part of the filesystem is mounted: "/" for the whole thing, "/@home"
+   *  for a btrfs subvolume, a directory for a bind mount. */
+  root: string;
+  mountPoint: string;
+  filesystem: string;
+}
+
+/**
+ * mountinfo's variable-length optional-fields group ends at a literal `-`, so the
+ * tail cannot be indexed from the start of the line. Splitting on the separator
+ * first is what makes `fstype` findable at all.
+ *
+ * Paths are escaped by the kernel — a mount under `/mnt/my drive` arrives as
+ * `/mnt/my\040drive`, and leaving it that way means the statfs below fails on
+ * exactly the mounts whose names have spaces.
+ */
+export function parseMountInfo(text: string): MountEntry[] {
+  const out: MountEntry[] = [];
+  for (const line of text.split("\n")) {
+    const sep = line.indexOf(" - ");
+    if (sep < 0) continue;
+    const head = line.slice(0, sep).split(" ");
+    const tail = line.slice(sep + 3).split(" ");
+    const deviceId = head[2];
+    const root = head[3];
+    const mountPoint = head[4];
+    const filesystem = tail[0];
+    if (!deviceId || !root || !mountPoint || !filesystem) continue;
+    out.push({
+      deviceId,
+      source: unescapeMountPath(tail[1] ?? ""),
+      root: unescapeMountPath(root),
+      mountPoint: unescapeMountPath(mountPoint),
+      filesystem,
+    });
+  }
+  return out;
+}
+
+/** The four sequences the kernel escapes: space, tab, newline, backslash. */
+export function unescapeMountPath(path: string): string {
+  return path.replace(/\\(040|011|012|134)/g, (_, code) =>
+    ({ "040": " ", "011": "\t", "012": "\n", "134": "\\" })[code as string] ?? _);
+}
+
+/** Partition directories of a whole disk: sysfs nests them under the disk and
+ *  marks each with a `partition` attribute, which is what tells `sda1` apart from
+ *  `queue` or `holders`. */
+export function listPartitions(diskId: string, fs: LinuxFs = realLinuxFs): string[] {
+  return (fs.list(`${SYS_BLOCK}/${diskId}`) ?? [])
+    .filter((name) => fs.exists(`${SYS_BLOCK}/${diskId}/${name}/partition`))
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+}
+
+/** The static half: everything but the usage, which needs a syscall per mount. */
+export function readPartitions(
+  diskId: string,
+  fs: LinuxFs = realLinuxFs,
+  mounts: MountEntry[] = parseMountInfo(fs.read(MOUNTINFO) ?? ""),
+): PartitionInfo[] {
+  return listPartitions(diskId, fs).map((id) => {
+    const base = `${SYS_BLOCK}/${diskId}/${id}`;
+    const deviceId = readAttr(fs, `${base}/dev`);
+    const udev = readUdevProperties(deviceId ? `b${deviceId}` : "", fs.read);
+    const sectors = readNumber(fs, `${base}/size`) ?? 0;
+    const devicePath = `/dev/${id}`;
+    const mine = mounts.filter((m) => (deviceId && m.deviceId === deviceId) || m.source === devicePath);
+    // udev knows the type even for a partition nothing has mounted, which is the
+    // case the mountinfo scan cannot answer at all.
+    const filesystem = udevValue(udev, "ID_FS_TYPE") ?? mine[0]?.filesystem;
+    return {
+      id,
+      devicePath,
+      sizeBytes: sectors * SECTOR_BYTES,
+      ...(filesystem ? { filesystem } : {}),
+      mounts: mine.map((m) => ({ mountPoint: m.mountPoint, filesystem: m.filesystem })),
+    };
+  });
+}
+
+export type StatfsReader = (path: string) => Promise<{ blocks: number; bavail: number; bfree: number; bsize: number }>;
+
+const realStatfs: StatfsReader = async (path) => {
+  const { statfs } = await import("node:fs/promises");
+  return statfs(path) as unknown as ReturnType<StatfsReader> extends Promise<infer T> ? T : never;
+};
+
+/**
+ * `used` is computed against the blocks a non-root user may actually have, not
+ * against the total: ext4 reserves 5% for root, so `blocks - bfree` reports a
+ * fresh filesystem as several percent full while `df` says 1%. This is `df`'s own
+ * arithmetic — total is what you can use plus what is used.
+ */
+export function usageFromStatfs(s: { blocks: number; bavail: number; bfree: number; bsize: number }): PartitionMount {
+  const used = (s.blocks - s.bfree) * s.bsize;
+  const total = used + s.bavail * s.bsize;
+  return { mountPoint: "", filesystem: "", usedBytes: used, totalBytes: total };
+}
+
+/**
+ * Fills in every mount's usage, in parallel. A mount that refuses is left with no
+ * figures rather than zeroes — an unreadable filesystem is not an empty one.
+ */
+export async function attachPartitionUsage(
+  disks: DiskInfo[],
+  statfs: StatfsReader = realStatfs,
+): Promise<void> {
+  const jobs: Promise<void>[] = [];
+  for (const disk of disks) {
+    for (const part of disk.partitions ?? []) {
+      for (const mount of part.mounts) {
+        jobs.push(
+          statfs(mount.mountPoint)
+            .then((s) => {
+              const { usedBytes, totalBytes } = usageFromStatfs(s);
+              mount.usedBytes = usedBytes;
+              mount.totalBytes = totalBytes;
+            })
+            .catch(() => {}),
+        );
+      }
+    }
+  }
+  await Promise.all(jobs);
+}