claude-rpc 0.15.4 → 0.15.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.15.4",
+  "version": "0.15.6",
   "description": "Discord Rich Presence for Claude Code — live model, project, tokens, and lifetime stats driven by Claude Code's hook system.",
   "type": "module",
   "license": "MIT",

package/src/cli.js

@@ -18,7 +18,7 @@ import { runHookCli } from './hook.js';
 import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, mcpServerCommand, setupOutro } from './install.js';
 import { startTui } from './tui.js';
 import { generateInsights } from './insights.js';
-import { maybeNudge } from './nudge.js';
+import { maybeNudge, pickTodayMilestone } from './nudge.js';
 import { badgeSvg } from './badge.js';
 import { fmtCost } from './pricing.js';
 import { addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } from './privacy.js';
@@ -26,10 +26,10 @@ import { parseDuration, setPause, clearPause, pauseUntil } from './pause.js';
 import { loadConfig, hasUserConfig } from './config.js';
 import * as lb from './leaderboard.js';
 import { VERSION } from './version.js';
-import { fail, tailLines, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
+import { fail, tailLines, heat, sparkline, fmtDelta, topPercentile, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
 import { randomUUID } from 'node:crypto';
 import { createInterface } from 'node:readline';
-import { basename } from 'node:path';
+import { basename, join } from 'node:path';
 
 const cmd = process.argv[2];
 
@@ -144,24 +144,24 @@ function shortPath(p) {
   return home && p.startsWith(home) ? '~' + p.slice(home.length) : p;
 }
 
-// 24-bar histogram of hour-of-day activity.
+// 24-bar histogram of hour-of-day activity, heat-graded per hour — the
+// peak hour literally glows (bold rust) instead of relying on a color swap.
 function renderHourHistogram(byHour, opts = {}) {
   const heightChars = ' ▁▂▃▄▅▆▇█';
   let max = 0;
   for (let h = 0; h < 24; h++) max = Math.max(max, byHour?.[h]?.activeMs || 0);
   if (max <= 0) return ['  (no hourly data yet)'];
-  const bars = [];
+  const colored = [];
   for (let h = 0; h < 24; h++) {
     const ms = byHour?.[h]?.activeMs || 0;
     const idx = ms > 0 ? Math.max(1, Math.min(8, Math.round((ms / max) * 8))) : 0;
-    bars.push(heightChars[idx]);
+    const ch = heightChars[idx];
+    colored.push(h === opts.peakHour ? `${c.bold}${heat(1)}${ch}${c.reset}` : `${heat(ms / max)}${ch}${c.reset}`);
   }
-  const peakH = opts.peakHour ?? bars.findIndex((b) => b === heightChars[Math.min(8, ...bars.map((_, i) => i).filter(() => true))]);
-  const colored = bars.map((ch, h) => h === opts.peakHour ? `${c.magenta}${c.bold}${ch}${c.reset}` : `${c.green}${ch}${c.reset}`).join('');
   // Hour labels under every 3rd hour.
   const labels = '00  03  06  09  12  15  18  21  ';
   return [
-    `  ${colored}`,
+    `  ${colored.join('')}`,
     `  ${c.dim}${labels}${c.reset}`,
   ];
 }
@@ -196,13 +196,14 @@ function renderHeatmap(byDay, days = 91) {
   }
   const cols = Math.ceil(cells.length / 7);
 
-  // Quantize: 0 / >0 / >15m / >1h / >3h
+  // Quantize: 0 / >0 / >15m / >1h / >3h — mapped onto the shared heat ramp
+  // so the heatmap, bars, and histograms all speak the same temperature.
   const shade = (ms) => {
     if (ms <= 0) return `${c.dim}·${c.reset}`;
-    if (ms < 15 * 60_000) return `${c.gray}▪${c.reset}`;
-    if (ms < 60 * 60_000) return `${c.green}▪${c.reset}`;
-    if (ms < 3 * 3600_000) return `${c.green}${c.bold}▪${c.reset}`;
-    return `${c.magenta}${c.bold}▪${c.reset}`;
+    if (ms < 15 * 60_000) return `${heat(0.2)}▪${c.reset}`;
+    if (ms < 60 * 60_000) return `${heat(0.5)}▪${c.reset}`;
+    if (ms < 3 * 3600_000) return `${heat(0.8)}▪${c.reset}`;
+    return `${c.bold}${heat(1)}▪${c.reset}`;
   };
 
   // Month labels along the top (where the month changes within the visible window).
@@ -234,7 +235,7 @@ function renderHeatmap(byDay, days = 91) {
   }
 
   // Footer legend.
-  const legend = `     ${c.dim}less${c.reset}  ${c.dim}·${c.reset} ${c.gray}▪${c.reset} ${c.green}▪${c.reset} ${c.green}${c.bold}▪${c.reset} ${c.magenta}${c.bold}▪${c.reset}  ${c.dim}more${c.reset}`;
+  const legend = `     ${c.dim}less${c.reset}  ${c.dim}·${c.reset} ${heat(0.2)}▪${c.reset} ${heat(0.5)}▪${c.reset} ${heat(0.8)}▪${c.reset} ${c.bold}${heat(1)}▪${c.reset}  ${c.dim}more${c.reset}`;
   lines.push('');
   lines.push(legend);
   return lines;
@@ -244,11 +245,69 @@ function pair(label, value, valueColor = c.cyan) {
   return `${c.dim}${label.padEnd(14)}${c.reset} ${valueColor}${value}${c.reset}`;
 }
 
-// ASCII bar for a value relative to max.
+// ASCII bar for a value relative to max. Fill color is heat-graded by the
+// ratio (calm green → amber → rust), so intensity reads at a glance; with
+// colors off it degrades to the same monochrome bar as before.
 function bar(val, max, width = 22) {
   if (!max || max <= 0) return '';
   const filled = Math.max(0, Math.min(width, Math.round((val / max) * width)));
-  return `${c.magenta}${'█'.repeat(filled)}${c.dim}${'░'.repeat(width - filled)}${c.reset}`;
+  return `${heat(val / max) || c.magenta}${'█'.repeat(filled)}${c.reset}${c.dim}${'░'.repeat(width - filled)}${c.reset}`;
+}
+
+// The last n calendar days of byDay entries (oldest → today), null where a
+// day has no activity. Date-stepped rather than ms arithmetic so DST shifts
+// can't skip or duplicate a day.
+function lastDays(byDay, n) {
+  const out = [];
+  const d = new Date();
+  d.setHours(12, 0, 0, 0); // noon — immune to DST midnight edges
+  d.setDate(d.getDate() - (n - 1));
+  for (let i = 0; i < n; i++) {
+    out.push(byDay?.[dayKey(d.getTime())] || null);
+    d.setDate(d.getDate() + 1);
+  }
+  return out;
+}
+
+const dayTokens = (d) => d
+  ? (d.inputTokens || 0) + (d.outputTokens || 0) + (d.cacheReadTokens || 0) + (d.cacheWriteTokens || 0)
+  : 0;
+
+// The `today` box, shared by `claude-rpc today` and `claude-rpc status`.
+// Each headline metric carries its own context — a ▲/▼ against the trailing
+// 7-day average (today excluded), a percentile callout on standout days, the
+// day's cost, and a 14-day sparkline — so the numbers answer "is that a lot?"
+// instead of making you remember.
+function todayBoxLines(vars, aggregate) {
+  const byDay = aggregate?.byDay || {};
+  const series = lastDays(byDay, 15);
+  const today = series.at(-1);
+  const prior7 = series.slice(-8, -1);
+  const avg = (xs) => xs.reduce((a, b) => a + b, 0) / (xs.length || 1);
+
+  const dActive  = fmtDelta(today?.activeMs || 0,     avg(prior7.map((d) => d?.activeMs || 0)), { vs: 'vs 7-day avg' });
+  const dPrompts = fmtDelta(today?.userMessages || 0, avg(prior7.map((d) => d?.userMessages || 0)));
+  const dTokens  = fmtDelta(dayTokens(today),         avg(prior7.map(dayTokens)));
+  const pctLabel = topPercentile(Object.values(byDay).map((d) => d?.activeMs || 0), today?.activeMs || 0);
+
+  const lines = [
+    pair('active',     `${c.bold}${c.green}${vars.todayHours}${c.reset}${dActive ? `  ${dActive}` : ''}${pctLabel ? `  ${c.magenta}· ${pctLabel}${c.reset}` : ''}`, ''),
+    pair('prompts',    `${c.yellow}${vars.todayPrompts}${c.reset}${dPrompts ? `  ${dPrompts}` : ''}`, ''),
+    pair('tool calls', vars.todayToolsFmt, c.yellow),
+    pair('sessions',   String(vars.todaySessions || 0)),
+    pair('tokens',     `${c.bold}${vars.todayTokensFmt}${c.reset}  ${c.dim}grand total${c.reset}${dTokens ? `  ${dTokens}` : ''}`, ''),
+    pair('  in+out',   vars.todayTokensRealFmt, c.gray),
+    pair('  cache',    vars.todayCacheTokensFmt, c.gray),
+  ];
+  if (today?.cost) {
+    lines.push(pair('cost', `${c.green}≈${fmtCost(today.cost)}${c.reset}  ${c.dim}+${(today.linesAdded || 0).toLocaleString()} lines today${c.reset}`, ''));
+  }
+  const spark = sparkline(series.slice(1).map((d) => d?.activeMs || 0));
+  if (spark) {
+    lines.push('');
+    lines.push(pair('last 14d', `${spark}  ${c.dim}← today${c.reset}`, ''));
+  }
+  return lines;
 }
 
 function showStatus() {
@@ -295,15 +354,7 @@ function showStatus() {
   }
 
   if (aggregate) {
-    box('today', [
-      pair('active',     `${c.bold}${c.green}${vars.todayHours}${c.reset}`, ''),
-      pair('prompts',    String(vars.todayPrompts), c.yellow),
-      pair('tool calls', vars.todayToolsFmt, c.yellow),
-      pair('sessions',   String(vars.todaySessions || 0)),
-      pair('tokens',     `${c.bold}${vars.todayTokensFmt}${c.reset}  ${c.dim}grand total${c.reset}`, ''),
-      pair('  in+out',   vars.todayTokensRealFmt, c.gray),
-      pair('  cache',    vars.todayCacheTokensFmt, c.gray),
-    ]);
+    box('today', todayBoxLines(vars, aggregate));
     console.log('');
 
     box('streak', [
@@ -446,17 +497,15 @@ function showToday() {
   console.log(`  ${c.bold}${c.magenta}◆ Today${c.reset}  ${c.dim}— ${new Date().toLocaleDateString()}${c.reset}`);
   console.log('');
 
-  box('today', [
-    pair('active',     `${c.bold}${c.green}${vars.todayHours}${c.reset}`, ''),
-    pair('prompts',    String(vars.todayPrompts), c.yellow),
-    pair('tool calls', vars.todayToolsFmt, c.yellow),
-    pair('sessions',   String(vars.todaySessions || 0)),
-    pair('tokens',     `${c.bold}${vars.todayTokensFmt}${c.reset}  ${c.dim}grand total${c.reset}`, ''),
-    pair('  in+out',   vars.todayTokensRealFmt, c.gray),
-    pair('  cache',    vars.todayCacheTokensFmt, c.gray),
-  ]);
+  box('today', todayBoxLines(vars, aggregate));
   console.log('');
 
+  // One quiet celebration line on milestone days (token round numbers
+  // crossed today, day-N anniversaries). The share nudge below owns streak
+  // records and round session/hour counts — no overlap.
+  const milestone = pickTodayMilestone(aggregate, dayTokens(lastDays(aggregate?.byDay, 1)[0]));
+  if (milestone) console.log(`  ${c.magenta}✶${c.reset}  ${c.bold}${milestone}${c.reset}\n`);
+
   if (aggregate?.byHour && Object.keys(aggregate.byHour).length) {
     box('when you code · hour of day', renderHourHistogram(aggregate.byHour, { peakHour: vars.peakHourNum }), 40);
     console.log('');
@@ -481,12 +530,23 @@ function showWeek() {
   console.log(`  ${c.bold}${c.magenta}◆ This week${c.reset}  ${c.dim}— ${weekKey(Date.now())}${c.reset}`);
   console.log('');
 
+  // Week-over-week context: this week so far vs the whole of last week.
+  // Early in the week "▼" is expected — the vs label keeps that honest.
+  const prevRef = new Date();
+  prevRef.setHours(12, 0, 0, 0); // noon — immune to DST midnight edges
+  prevRef.setDate(prevRef.getDate() - 7);
+  const wkNow = aggregate?.byWeek?.[weekKey(Date.now())];
+  const wkPrev = aggregate?.byWeek?.[weekKey(prevRef.getTime())];
+  const dWkActive  = fmtDelta(wkNow?.activeMs || 0,     wkPrev?.activeMs || 0, { vs: 'vs last week' });
+  const dWkPrompts = fmtDelta(wkNow?.userMessages || 0, wkPrev?.userMessages || 0);
+  const dWkTokens  = fmtDelta(dayTokens(wkNow),         dayTokens(wkPrev));
+
   box('this week', [
-    pair('active',     `${c.bold}${c.green}${vars.weekHours}${c.reset}`, ''),
-    pair('prompts',    String(vars.weekPrompts), c.yellow),
+    pair('active',     `${c.bold}${c.green}${vars.weekHours}${c.reset}${dWkActive ? `  ${dWkActive}` : ''}`, ''),
+    pair('prompts',    `${c.yellow}${vars.weekPrompts}${c.reset}${dWkPrompts ? `  ${dWkPrompts}` : ''}`, ''),
     pair('tool calls', vars.weekToolsFmt, c.yellow),
     pair('sessions',   String(vars.weekSessions || 0)),
-    pair('tokens',     `${c.bold}${vars.weekTokensFmt}${c.reset}  ${c.dim}grand total${c.reset}`, ''),
+    pair('tokens',     `${c.bold}${vars.weekTokensFmt}${c.reset}  ${c.dim}grand total${c.reset}${dWkTokens ? `  ${dWkTokens}` : ''}`, ''),
   ]);
   console.log('');
 
@@ -513,7 +573,8 @@ function showWeek() {
       const h = ms / 3_600_000;
       const hStr = h < 1 ? `${Math.round(h * 60)}m` : (h < 10 ? `${h.toFixed(1)}h` : `${Math.round(h)}h`);
       const prefix = isToday ? `${c.bold}` : '';
-      return `${prefix}${label.padEnd(12)}${c.reset} ${bar(ms, maxMs)} ${c.cyan}${hStr.padStart(5)}${c.reset}${isToday ? ` ${c.dim}← today${c.reset}` : ''}`;
+      const peak = ms === maxMs && ms > 0 ? ` ${c.bold}${heat(1)}◆${c.reset}` : '';
+      return `${prefix}${label.padEnd(12)}${c.reset} ${bar(ms, maxMs)} ${c.cyan}${hStr.padStart(5)}${c.reset}${peak}${isToday ? ` ${c.dim}← today${c.reset}` : ''}`;
     });
     box('this week · daily breakdown', lines);
     console.log('');
@@ -1788,14 +1849,33 @@ const packagedDefault = IS_PACKAGED && !cmd;
       try {
         if (IS_NPX) {
           // Our own tree is npm's throwaway _npx cache; launch from the global
-          // install setup just promoted to, via the PATH-resolved bin.
+          // install setup just promoted to. The global copy must be resolved
+          // EXPLICITLY (npm root -g): inside an npx run, PATH has the _npx
+          // cache's .bin first, so a bare `claude-rpc` resolves right back
+          // into the cache we're escaping. And it must be spawned as a direct
+          // `node <script>` child — a shell+shim chain (cmd → .cmd → node)
+          // only hides the FIRST hop's window; the detached cmd loses its
+          // console, the grandchild node allocates a fresh one, and Windows 11
+          // pops it as a visible Windows Terminal window whose closure kills
+          // the daemon.
           if (!daemonPid()) {
-            const child = spawn('claude-rpc', ['daemon'], {
+            let script = null;
+            try {
+              const r = spawnSync('npm', ['root', '-g'], {
+                encoding: 'utf8', timeout: 8000, windowsHide: true,
+                shell: process.platform === 'win32',   // npm is npm.cmd on Windows
+              });
+              const root = (r.stdout || '').trim();
+              const candidate = root && join(root, 'claude-rpc', 'src', 'daemon.js');
+              if (candidate && existsSync(candidate)) script = candidate;
+            } catch { /* npm unavailable → fall back below */ }
+            // Fallback: run from this (npx) tree. Still invisible — only the
+            // npx-cache-eviction caveat remains, healed by the next setup.
+            const child = spawn(process.execPath, [script || DAEMON_SCRIPT], {
               detached: true, stdio: 'ignore', windowsHide: true,
-              shell: process.platform === 'win32',
             });
             child.unref();
-            console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}log ${shortPath(LOG_PATH)}${c.reset}`);
+            console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}pid ${c.reset}${c.cyan}${child.pid}${c.reset}${c.dim} · log ${shortPath(LOG_PATH)}${c.reset}`);
           } else {
             console.log(`  ${c.cyan}·${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}pid ${daemonPid()}${c.reset}`);
           }

package/src/nudge.js

@@ -63,6 +63,31 @@ export function pickShareNudge(agg) {
   return out[0];
 }
 
+// A quiet, local celebration line for `claude-rpc today`. Complements the
+// share nudges above — which own streak records and round session/hour
+// counts — without overlapping them: this detects lifetime-token round
+// numbers CROSSED TODAY (no state file needed — the crossing happened today
+// iff total ≥ mark and total − todayTokens < mark) and round "day N"
+// anniversaries (which are only true on the day itself). Returns one string
+// or null; the caller styles it.
+const TOKEN_MARKS = [1e9, 5e9, 1e10, 2.5e10, 5e10, 1e11, 2.5e11, 5e11, 1e12];
+const DAY_MARKS = new Set([50, 100, 200, 365, 500, 730, 1000]);
+const fmtTok = (n) => n >= 1e12 ? `${n / 1e12}T` : n >= 1e9 ? `${n / 1e9}B` : `${n / 1e6}M`;
+
+export function pickTodayMilestone(agg, todayTokens = 0) {
+  if (!agg || typeof agg !== 'object') return null;
+  const total = (agg.inputTokens || 0) + (agg.outputTokens || 0)
+    + (agg.cacheReadTokens || 0) + (agg.cacheWriteTokens || 0);
+  for (let i = TOKEN_MARKS.length - 1; i >= 0; i--) {
+    const mark = TOKEN_MARKS[i];
+    if (total >= mark && total - todayTokens < mark) {
+      return `crossed ${fmtTok(mark)} lifetime tokens today`;
+    }
+  }
+  if (DAY_MARKS.has(agg.daysSinceFirst || 0)) return `day ${agg.daysSinceFirst} with claude`;
+  return null;
+}
+
 function readLastKey(path = NUDGE_STATE) {
   try { return JSON.parse(readFileSync(path, 'utf8')).key || null; }
   catch { return null; }

package/src/tui.js

@@ -13,6 +13,7 @@ import { loadConfig } from './config.js';
 import { PID_PATH } from './paths.js';
 import { fmtCost } from './pricing.js';
 import { generateInsights } from './insights.js';
+import { heat } from './ui.js';
 
 // ── ANSI ────────────────────────────────────────────────────────────────────
 const ESC = '\x1b[';
@@ -74,10 +75,11 @@ function width()  { return Math.max(50, Math.min(120, process.stdout.columns ||
 function height() { return Math.max(20, process.stdout.rows || 24); }
 
 function rule(w) { return C.gray + '─'.repeat(w - 4) + C.reset; }
+// Heat-graded fill (same ramp as the CLI views) — intensity reads at a glance.
 function bar(value, max, w = 16) {
   if (!max || max <= 0) return ''.padEnd(w);
   const filled = Math.max(0, Math.min(w, Math.round((value / max) * w)));
-  return '█'.repeat(filled) + ' '.repeat(w - filled);
+  return `${heat(value / max) || C.magenta}${'█'.repeat(filled)}${C.reset}` + ' '.repeat(w - filled);
 }
 
 // Pad a (possibly ANSI-colored) line with spaces so its VISIBLE width hits n.
@@ -166,7 +168,7 @@ function tabToday(_, data) {
         const ms = agg.byHour?.[h]?.activeMs || 0;
         const idx = ms > 0 ? Math.max(1, Math.min(8, Math.round((ms / max) * 8))) : 0;
         const ch = heightChars[idx];
-        bars.push(h === v.peakHourNum ? `${C.magenta}${C.bold}${ch}${C.reset}` : `${C.green}${ch}${C.reset}`);
+        bars.push(h === v.peakHourNum ? `${C.bold}${heat(1)}${ch}${C.reset}` : `${heat(ms / max)}${ch}${C.reset}`);
       }
       out.push(bars.join(''));
       out.push(`${C.dim}00  03  06  09  12  15  18  21${C.reset}`);
@@ -212,7 +214,8 @@ function tabWeek(_, data) {
         const h = ms / 3_600_000;
         const hStr = h < 1 ? `${Math.round(h * 60)}m` : (h < 10 ? `${h.toFixed(1)}h` : `${Math.round(h)}h`);
         const prefix = isToday ? C.bold : '';
-        out.push(`${prefix}${label.padEnd(11)}${C.reset} ${C.magenta}${bar(ms, maxMs, 18)}${C.reset} ${C.cyan}${hStr.padStart(5)}${C.reset}${isToday ? `  ${C.dim}← today${C.reset}` : ''}`);
+        const peak = ms === maxMs && ms > 0 ? ` ${C.bold}${heat(1)}◆${C.reset}` : '';
+        out.push(`${prefix}${label.padEnd(11)}${C.reset} ${bar(ms, maxMs, 18)} ${C.cyan}${hStr.padStart(5)}${C.reset}${peak}${isToday ? `  ${C.dim}← today${C.reset}` : ''}`);
       }
     }
   }
@@ -267,7 +270,7 @@ function tabLifetime(_, data) {
       const h = p.activeMs / 3_600_000;
       const hStr = h < 1 ? `${Math.round(h * 60)}m` : (h < 10 ? `${h.toFixed(1)}h` : `${Math.round(h)}h`);
       const pretty = humanProject(name).slice(0, 18).padEnd(20);
-      out.push(`${pretty} ${C.magenta}${bar(p.activeMs, maxMs, 16)}${C.reset} ${C.cyan}${hStr.padStart(5)}${C.reset}`);
+      out.push(`${pretty} ${bar(p.activeMs, maxMs, 16)} ${C.cyan}${hStr.padStart(5)}${C.reset}`);
     }
   }
   return out;
@@ -291,7 +294,7 @@ function tabCost(_, data) {
     const max = byModel[0][1];
     for (const [m, val] of byModel) {
       const pretty = String(m).padEnd(20);
-      out.push(`${pretty} ${C.magenta}${bar(val, max, 18)}${C.reset} ${C.cyan}${fmtCost(val).padStart(8)}${C.reset}`);
+      out.push(`${pretty} ${bar(val, max, 18)} ${C.cyan}${fmtCost(val).padStart(8)}${C.reset}`);
     }
   }
 
@@ -330,7 +333,7 @@ function tabCode(_, data) {
     const max = langs[0][1].edits || 1;
     for (const [name, l] of langs) {
       const pretty = name.slice(0, 18).padEnd(20);
-      out.push(`${pretty} ${C.magenta}${bar(l.edits, max, 18)}${C.reset} ${C.cyan}${String(l.edits).padStart(6)}${C.reset}`);
+      out.push(`${pretty} ${bar(l.edits, max, 18)} ${C.cyan}${String(l.edits).padStart(6)}${C.reset}`);
     }
   }
 

package/src/ui.js

@@ -81,6 +81,68 @@ export function fail(label, { hint = '', code = EX_USER_ERROR } = {}) {
   process.exit(code);
 }
 
+// ── Heat / sparkline / comparison primitives ──────────────────────────────
+//
+// Shared by the focused views (today / week / status / TUI). All of these
+// degrade to plain glyphs when colors are off, so piped output stays clean.
+
+// Intensity 0..1 → a 256-color ramp matching the site palette: calm green
+// for light activity, amber for solid, rust for hot. `tty` is overridable so
+// the ramp is unit-testable in a non-TTY test runner.
+const HEAT_RAMP = [
+  [0.25, '\x1b[38;5;65m'],  // sage — barely warm
+  [0.45, '\x1b[38;5;71m'],  // green — steady
+  [0.65, '\x1b[38;5;178m'], // amber — solid
+  [0.85, '\x1b[38;5;208m'], // orange — heavy
+  [Infinity, '\x1b[38;5;166m'], // rust — peak
+];
+export function heat(t, { tty = TTY } = {}) {
+  if (!tty) return '';
+  if (!(t > 0)) return c.dim;
+  for (const [ceil, color] of HEAT_RAMP) if (t < ceil) return color;
+  return HEAT_RAMP.at(-1)[1];
+}
+
+// Heat-colored sparkline of a numeric series (▁▂▃▄▅▆▇█), scaled to its own
+// max. Zero/empty input → ''. With colors off this is just the glyphs.
+const SPARK_CHARS = ' ▁▂▃▄▅▆▇█';
+export function sparkline(values, { tty = TTY } = {}) {
+  const max = Math.max(0, ...values.map((v) => v || 0));
+  if (!(max > 0)) return '';
+  const out = values.map((raw) => {
+    const v = raw || 0;
+    const idx = v > 0 ? Math.max(1, Math.min(8, Math.round((v / max) * 8))) : 0;
+    return `${heat(v / max, { tty })}${SPARK_CHARS[idx]}`;
+  }).join('');
+  return out + (tty ? c.reset : '');
+}
+
+// "▲ +18% vs 7-day avg" — current vs a baseline, colored by direction.
+// A quiet day isn't a failure, so down renders gray, not red. Returns ''
+// when the baseline is too small to compare against (fresh installs).
+export function fmtDelta(current, baseline, { vs = '' } = {}) {
+  if (!(baseline > 0)) return '';
+  const pct = Math.round(((current || 0) - baseline) / baseline * 100);
+  const tail = vs ? ` ${c.dim}${vs}${c.reset}` : '';
+  if (pct === 0) return `${c.dim}≈ ${vs || 'usual'}${c.reset}`;
+  const up = pct > 0;
+  const shown = Math.min(Math.abs(pct), 999); // a 40×-average day reads "+999%", not noise
+  return `${up ? c.green : c.gray}${up ? '▲' : '▼'} ${up ? '+' : '−'}${shown}%${c.reset}${tail}`;
+}
+
+// Percentile callout for a standout value among its history ("top 10% day").
+// Quiet unless there's real history to rank against and the value is high —
+// a callout on every middling day would train the eye to skip it.
+export function topPercentile(values, v, { min = 14 } = {}) {
+  const past = values.filter((x) => x > 0);
+  if (past.length < min || !(v > 0)) return '';
+  const rank = past.filter((x) => x <= v).length / past.length;
+  if (rank >= 1) return 'best day yet';
+  if (rank >= 0.9) return 'top 10% day';
+  if (rank >= 0.75) return 'top 25% day';
+  return '';
+}
+
 // Return the last n lines of a log file's raw text, trimming the trailing
 // empty element that split('\n') produces when the file ends with a newline.
 // When the file lacks a trailing newline the last element is the last real

package/src/version.js

@@ -11,7 +11,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT } from './paths.js';
 
-const BAKED = '0.15.4';
+const BAKED = '0.15.6';
 
 function readPkgVersion() {
   try {