@hasna/statusline 0.0.8 → 0.0.9

package/README.md

@@ -22,7 +22,7 @@ That's it — Claude Code picks it up on the next status refresh (no restart nee
 ## Segments
 
 `statusline list` shows a compact, enabled-first summary of your segments (use
-`statusline list --all` for every row). The table below is the full catalog — all 30
+`statusline list --all` for every row). The table below is the full catalog — all 31
 segment ids from `src/segments/index.ts`.
 
 `renderLine` walks your configured segment order, renders each one, and **drops**
@@ -36,6 +36,7 @@ anything that returns `null` or throws. A failed segment never breaks the host U
 | `git-branch` | off | Current Git branch | `git branch --show-current` in `cwd` | outside git or detached | `main` |
 | `commit-age` | on | Time since last commit (compact) | `git log -1` epoch vs now | no commits / not a repo | `12h` |
 | `loc` | on | Lines of code tracked by Git (compact) | `git ls-files` + `wc -l` in repo root | outside git or zero lines | `1.2k` |
+| `disk-free` | off | Free space on the volume holding the working directory | one `fs.statfsSync` syscall on `StatusContext.cwd` — no subprocess, no polling, no cache | the volume cannot be read (missing cwd, unsupported filesystem) | `disk 24.1G` · `disk 8G low` |
 | `current-dir` | off | Current working directory (basename) | `StatusContext.cwd` | never (always renders basename) | `statusline` |
 | `cwd` | off | Current working directory (full path) | `StatusContext.cwd`, home directory abbreviated to `~`, head elided past 40 chars | no cwd in the payload | `~/work/statusline` |
 | `model` | off | Current model name (no context tag) | `StatusContext.model.id` via friendly formatter | no model id | `fable 5` |
@@ -126,6 +127,9 @@ separators are never coloured.
   80% and above (the same shape the rate-limit segments use);
 - the rate-limit segments escalate from yellow to red at 80%;
 - `cwd` uses a calm blue accent and elides the head of long paths;
+- `disk-free` stays dim while the volume has headroom, turns yellow below 20%
+  free and red below 10%, and appends a `low` marker so the warning survives
+  `NO_COLOR`;
 - model, cost and duration render dim, so they never compete with a warning.
 
 ```bash
@@ -231,6 +235,14 @@ The `newline` segment starts a new row; empty rows are removed. Segments
 that need more than the payload offers (e.g. `context-remaining`) read the session
 transcript to compute it. A segment failure is never fatal — it's simply omitted.
 
+There is no long-running statusline process, so nothing polls. `disk-free` reads
+free space once per render with `fs.statfsSync` (about half a microsecond), the
+same way the host re-runs the command for each refresh; shelling out to `df`
+would fork a process every time and cost roughly a millisecond. That one reading
+is shared by the segment's text and its colour, so they cannot disagree. The
+segment adds under 2 µs to an in-process render, which is below the noise of the
+~17 ms process invocation.
+
 ## SDK
 
 The package root is a side-effect-free SDK surface:

package/dist/cli.js

@@ -157,6 +157,23 @@ function compactNum(n) {
     return `${trimmed(n / 1000)}k`;
   return `${n}`;
 }
+var BYTE_UNITS = ["K", "M", "G", "T", "P"];
+function compactBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0)
+    return "";
+  if (bytes < 1024)
+    return `${Math.floor(bytes)}B`;
+  let value = bytes / 1024;
+  let unit = 0;
+  while (unit < BYTE_UNITS.length - 1) {
+    const rounded = Number(value.toFixed(1));
+    if (rounded < 1024)
+      break;
+    value /= 1024;
+    unit += 1;
+  }
+  return `${trimmed(value)}${BYTE_UNITS[unit]}`;
+}
 function money(n) {
   return `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 }
@@ -416,6 +433,95 @@ function windowSize(ctx) {
   return ctx.model?.id?.includes("[1m]") ? 1e6 : 200000;
 }
 
+// src/disk.ts
+import { statfsSync } from "fs";
+var DISK_MEMO = Symbol("statusline.disk-free");
+var DISK_WARN_PERCENT = 20;
+var DISK_CRITICAL_PERCENT = 10;
+function finiteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function readDiskStats(path) {
+  if (typeof statfsSync !== "function")
+    return null;
+  try {
+    const stats = statfsSync(path);
+    if (!stats)
+      return null;
+    return {
+      bsize: Number(stats.bsize),
+      blocks: Number(stats.blocks),
+      bavail: Number(stats.bavail)
+    };
+  } catch {
+    return null;
+  }
+}
+function diskFree(path, reader = readDiskStats) {
+  let stats;
+  try {
+    stats = reader(path);
+  } catch {
+    return null;
+  }
+  if (!stats)
+    return null;
+  const bsize = finiteNonNegative(stats.bsize);
+  const blocks = finiteNonNegative(stats.blocks);
+  const bavail = finiteNonNegative(stats.bavail);
+  if (bsize === null || blocks === null || bavail === null)
+    return null;
+  if (bsize <= 0 || blocks <= 0)
+    return null;
+  const available = Math.min(bavail, blocks);
+  const totalBytes = bsize * blocks;
+  const freeBytes = bsize * available;
+  if (!Number.isFinite(totalBytes) || !Number.isFinite(freeBytes))
+    return null;
+  return {
+    freeBytes,
+    totalBytes,
+    freePercent: available / blocks * 100
+  };
+}
+function diskFreeFor(path, memo, reader = readDiskStats) {
+  if (!memo)
+    return diskFree(path, reader);
+  const hit = memo.get(DISK_MEMO);
+  if (hit && hit.path === path)
+    return hit.value;
+  const value = diskFree(path, reader);
+  memo.set(DISK_MEMO, { path, value });
+  return value;
+}
+function diskLevel(freePercent) {
+  if (!Number.isFinite(freePercent))
+    return null;
+  if (freePercent < DISK_CRITICAL_PERCENT)
+    return "critical";
+  if (freePercent < DISK_WARN_PERCENT)
+    return "low";
+  return null;
+}
+function formatDiskFree(disk) {
+  const value = compactBytes(disk.freeBytes);
+  if (!value)
+    return "";
+  return diskLevel(disk.freePercent) ? `disk ${value} low` : `disk ${value}`;
+}
+function diskColor(disk) {
+  if (!disk)
+    return null;
+  switch (diskLevel(disk.freePercent)) {
+    case "critical":
+      return "red";
+    case "low":
+      return "yellow";
+    default:
+      return "dim";
+  }
+}
+
 // src/accounts.ts
 import { existsSync as existsSync5, readFileSync as readFileSync4, realpathSync } from "fs";
 import { homedir as homedir4 } from "os";
@@ -804,6 +910,16 @@ var segments = [
       return n ? compactNum(n) : null;
     }
   },
+  {
+    id: "disk-free",
+    description: "Free space on the volume holding the working directory",
+    defaultEnabled: false,
+    color: (ctx, memo) => diskColor(diskFreeFor(dir(ctx), memo)),
+    render(ctx, memo) {
+      const disk = diskFreeFor(dir(ctx), memo);
+      return disk ? formatDiskFree(disk) || null : null;
+    }
+  },
   {
     id: "current-dir",
     description: "Current working directory (basename)",
@@ -1051,13 +1167,14 @@ function colorsEnabled(cfg, env = process.env) {
     return false;
   return cfg.colors !== false;
 }
-function paint(segment, text, ctx) {
-  const color = typeof segment.color === "function" ? segment.color(ctx) : segment.color;
+function paint(segment, text, ctx, memo) {
+  const color = typeof segment.color === "function" ? segment.color(ctx, memo) : segment.color;
   const code = color ? ANSI[color] : undefined;
   return code ? `${code}${text}${RESET}` : text;
 }
 async function renderLine(ctx, cfg) {
   const colorize = colorsEnabled(cfg);
+  const memo = new Map;
   const rows = [[]];
   for (const id of cfg.segments) {
     if (id === "newline") {
@@ -1068,9 +1185,9 @@ async function renderLine(ctx, cfg) {
     if (!segment)
       continue;
     try {
-      const out = await segment.render(ctx);
+      const out = await segment.render(ctx, memo);
       if (out)
-        rows[rows.length - 1].push(colorize ? paint(segment, out, ctx) : out);
+        rows[rows.length - 1].push(colorize ? paint(segment, out, ctx, memo) : out);
     } catch {}
   }
   return rows.map((parts) => parts.join(cfg.separator)).filter((row) => row.length > 0).join(`
@@ -1079,7 +1196,7 @@ async function renderLine(ctx, cfg) {
 // package.json
 var package_default = {
   name: "@hasna/statusline",
-  version: "0.0.8",
+  version: "0.0.9",
   description: "Tiny composable statusline CLI for AI coding agents \u2014 pre-built toggleable segments for Claude Code, with a provider model for others",
   license: "Apache-2.0",
   type: "module",

package/dist/disk.d.ts

@@ -0,0 +1,51 @@
+import type { RenderMemo, SegmentColor } from "./providers/types.js";
+/** The statfs fields this module needs; node's StatFs carries more. */
+export interface DiskStats {
+    bsize: number;
+    blocks: number;
+    bavail: number;
+}
+/** Injectable reader: tests pass a fake, the render uses the real syscall. */
+export type DiskStatfsReader = (path: string) => DiskStats | null;
+export interface DiskFree {
+    freeBytes: number;
+    totalBytes: number;
+    /** Blocks available to an unprivileged user, as a percentage. */
+    freePercent: number;
+}
+/** Below 20% free a disk is worth flagging; below 10% it is critical. */
+export declare const DISK_WARN_PERCENT = 20;
+export declare const DISK_CRITICAL_PERCENT = 10;
+export type DiskLevel = "low" | "critical";
+/**
+ * Read a filesystem's stats with one syscall. Returns null when the runtime
+ * has no `statfs` or the call fails (missing path, permission, unsupported
+ * filesystem), so the caller can omit the segment instead of guessing.
+ */
+export declare function readDiskStats(path: string): DiskStats | null;
+/**
+ * Free bytes for `path`'s volume, or null when the reading is unusable.
+ *
+ * Unreadable or missing fields are null, never zero: a rendered zero has to
+ * mean "the disk really is full", not "this runtime could not tell me".
+ */
+export declare function diskFree(path: string, reader?: DiskStatfsReader): DiskFree | null;
+/**
+ * Free space for `path`, read at most once per render.
+ *
+ * The memo belongs to a single `renderLine` call and is shared by a segment's
+ * text and colour, so the volume is read once instead of once per consumer. It
+ * is discarded when that render ends: the next invocation reads afresh, so this
+ * is not a cache and cannot show a figure from a previous render.
+ */
+export declare function diskFreeFor(path: string, memo?: RenderMemo, reader?: DiskStatfsReader): DiskFree | null;
+/** Severity for a free percentage; null while the volume has headroom. */
+export declare function diskLevel(freePercent: number): DiskLevel | null;
+/**
+ * `disk 24G` while healthy, `disk 8.2G low` below the warning line. The
+ * textual marker is deliberate: colour alone disappears under `NO_COLOR`,
+ * where a nearly-full disk still has to be visible at a glance.
+ */
+export declare function formatDiskFree(disk: DiskFree): string;
+/** Healthy disks stay dim; low space escalates yellow, then red. */
+export declare function diskColor(disk: DiskFree | null): SegmentColor | null;

package/dist/format.d.ts

@@ -1,4 +1,11 @@
 export declare function compactAge(seconds: number): string;
 export declare function compactNum(n: number): string;
+/**
+ * Byte count in binary units, one decimal at most: `461k`, `24.1G`, `512B`.
+ * Unit letters match `df -h` (K/M/G/T are 1024-based here) so the number
+ * agrees with what an operator sees in a shell. An unusable value — negative,
+ * NaN, Infinity — returns "" rather than a plausible-looking number.
+ */
+export declare function compactBytes(bytes: number): string;
 export declare function money(n: number): string;
 export declare function compactDuration(ms: number): string;

package/dist/index.js

@@ -156,6 +156,23 @@ function compactNum(n) {
     return `${trimmed(n / 1000)}k`;
   return `${n}`;
 }
+var BYTE_UNITS = ["K", "M", "G", "T", "P"];
+function compactBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0)
+    return "";
+  if (bytes < 1024)
+    return `${Math.floor(bytes)}B`;
+  let value = bytes / 1024;
+  let unit = 0;
+  while (unit < BYTE_UNITS.length - 1) {
+    const rounded = Number(value.toFixed(1));
+    if (rounded < 1024)
+      break;
+    value /= 1024;
+    unit += 1;
+  }
+  return `${trimmed(value)}${BYTE_UNITS[unit]}`;
+}
 function money(n) {
   return `$${n.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
 }
@@ -415,6 +432,95 @@ function windowSize(ctx) {
   return ctx.model?.id?.includes("[1m]") ? 1e6 : 200000;
 }
 
+// src/disk.ts
+import { statfsSync } from "fs";
+var DISK_MEMO = Symbol("statusline.disk-free");
+var DISK_WARN_PERCENT = 20;
+var DISK_CRITICAL_PERCENT = 10;
+function finiteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function readDiskStats(path) {
+  if (typeof statfsSync !== "function")
+    return null;
+  try {
+    const stats = statfsSync(path);
+    if (!stats)
+      return null;
+    return {
+      bsize: Number(stats.bsize),
+      blocks: Number(stats.blocks),
+      bavail: Number(stats.bavail)
+    };
+  } catch {
+    return null;
+  }
+}
+function diskFree(path, reader = readDiskStats) {
+  let stats;
+  try {
+    stats = reader(path);
+  } catch {
+    return null;
+  }
+  if (!stats)
+    return null;
+  const bsize = finiteNonNegative(stats.bsize);
+  const blocks = finiteNonNegative(stats.blocks);
+  const bavail = finiteNonNegative(stats.bavail);
+  if (bsize === null || blocks === null || bavail === null)
+    return null;
+  if (bsize <= 0 || blocks <= 0)
+    return null;
+  const available = Math.min(bavail, blocks);
+  const totalBytes = bsize * blocks;
+  const freeBytes = bsize * available;
+  if (!Number.isFinite(totalBytes) || !Number.isFinite(freeBytes))
+    return null;
+  return {
+    freeBytes,
+    totalBytes,
+    freePercent: available / blocks * 100
+  };
+}
+function diskFreeFor(path, memo, reader = readDiskStats) {
+  if (!memo)
+    return diskFree(path, reader);
+  const hit = memo.get(DISK_MEMO);
+  if (hit && hit.path === path)
+    return hit.value;
+  const value = diskFree(path, reader);
+  memo.set(DISK_MEMO, { path, value });
+  return value;
+}
+function diskLevel(freePercent) {
+  if (!Number.isFinite(freePercent))
+    return null;
+  if (freePercent < DISK_CRITICAL_PERCENT)
+    return "critical";
+  if (freePercent < DISK_WARN_PERCENT)
+    return "low";
+  return null;
+}
+function formatDiskFree(disk) {
+  const value = compactBytes(disk.freeBytes);
+  if (!value)
+    return "";
+  return diskLevel(disk.freePercent) ? `disk ${value} low` : `disk ${value}`;
+}
+function diskColor(disk) {
+  if (!disk)
+    return null;
+  switch (diskLevel(disk.freePercent)) {
+    case "critical":
+      return "red";
+    case "low":
+      return "yellow";
+    default:
+      return "dim";
+  }
+}
+
 // src/accounts.ts
 import { existsSync as existsSync5, readFileSync as readFileSync4, realpathSync } from "fs";
 import { homedir as homedir4 } from "os";
@@ -803,6 +909,16 @@ var segments = [
       return n ? compactNum(n) : null;
     }
   },
+  {
+    id: "disk-free",
+    description: "Free space on the volume holding the working directory",
+    defaultEnabled: false,
+    color: (ctx, memo) => diskColor(diskFreeFor(dir(ctx), memo)),
+    render(ctx, memo) {
+      const disk = diskFreeFor(dir(ctx), memo);
+      return disk ? formatDiskFree(disk) || null : null;
+    }
+  },
   {
     id: "current-dir",
     description: "Current working directory (basename)",
@@ -1050,13 +1166,14 @@ function colorsEnabled(cfg, env = process.env) {
     return false;
   return cfg.colors !== false;
 }
-function paint(segment, text, ctx) {
-  const color = typeof segment.color === "function" ? segment.color(ctx) : segment.color;
+function paint(segment, text, ctx, memo) {
+  const color = typeof segment.color === "function" ? segment.color(ctx, memo) : segment.color;
   const code = color ? ANSI[color] : undefined;
   return code ? `${code}${text}${RESET}` : text;
 }
 async function renderLine(ctx, cfg) {
   const colorize = colorsEnabled(cfg);
+  const memo = new Map;
   const rows = [[]];
   for (const id of cfg.segments) {
     if (id === "newline") {
@@ -1067,9 +1184,9 @@ async function renderLine(ctx, cfg) {
     if (!segment)
       continue;
     try {
-      const out = await segment.render(ctx);
+      const out = await segment.render(ctx, memo);
       if (out)
-        rows[rows.length - 1].push(colorize ? paint(segment, out, ctx) : out);
+        rows[rows.length - 1].push(colorize ? paint(segment, out, ctx, memo) : out);
     } catch {}
   }
   return rows.map((parts) => parts.join(cfg.separator)).filter((row) => row.length > 0).join(`
@@ -1078,7 +1195,7 @@ async function renderLine(ctx, cfg) {
 // package.json
 var package_default = {
   name: "@hasna/statusline",
-  version: "0.0.8",
+  version: "0.0.9",
   description: "Tiny composable statusline CLI for AI coding agents \u2014 pre-built toggleable segments for Claude Code, with a provider model for others",
   license: "Apache-2.0",
   type: "module",