claude-code-runrate 0.1.0

package/src/render/resume.js

@@ -0,0 +1,51 @@
+// @ts-check
+'use strict';
+// src/render/resume.js — renders the resume-cost advisor. Pure function of
+// advisor rows (see src/resume.js); selection stays with `claude --resume`.
+
+const { dim, bold, green, yellow, red, cyan, tok } = require('./shared');
+
+/** @param {number} m minutes → coarse age */
+function fmtAge(m) {
+  if (m >= 1440) return Math.round(m / 1440) + 'd';
+  if (m >= 60) return Math.round(m / 60) + 'h';
+  return Math.max(0, m) + 'm';
+}
+/** @param {string} s @param {number} n */
+function trunc(s, n) { s = String(s); return s.length <= n ? s : s.slice(0, Math.max(0, n - 1)) + '…'; }
+
+/**
+ * @param {{ sessionId: string, title: string, branch: string|null, ageMin: number, ctx: number, winPct: number, cold: boolean }[]} rows
+ * @param {{ scope?: 'cwd'|'all' }} [opts]
+ * @returns {string}
+ */
+function renderResume(rows, opts = {}) {
+  const scopeLabel = opts.scope === 'all' ? 'all projects' : 'this project';
+  if (!rows.length) {
+    let s = '  ' + dim(`no resumable sessions in ${scopeLabel}.`);
+    if (opts.scope !== 'all') s += '\n  ' + dim('try ') + cyan('ccr resume all');
+    return s;
+  }
+
+  const out = [bold('recent sessions') + dim('  ·  ' + scopeLabel), ''];
+  const cols = ['age'.padStart(5), 'ctx'.padStart(5), 'win%'.padStart(5), 'cache'.padEnd(4), 'title'];
+  out.push('  ' + dim(cols.join('  ')));
+
+  for (const r of rows) {
+    const age = fmtAge(r.ageMin).padStart(5);
+    const ctx = tok(r.ctx).padStart(5);
+    const winS = (r.winPct + '%').padStart(5);
+    const winCol = r.winPct >= 80 ? red : r.winPct >= 50 ? yellow : green;
+    const cache = (r.cold ? yellow : green)((r.cold ? 'cold' : 'warm').padEnd(4));
+    const title = trunc(r.title, 40);
+    const branch = r.branch ? dim('  ' + r.branch) : '';
+    const nearClear = r.winPct >= 80 ? red(' ⚠ near /clear') : '';
+    out.push('  ' + dim(age) + '  ' + ctx + '  ' + winCol(winS) + '  ' + cache + '  ' + title + branch + nearClear);
+  }
+
+  out.push('');
+  out.push('  ' + dim('cold = first turn re-pays full context · select with ') + cyan('claude --resume'));
+  return out.join('\n');
+}
+
+module.exports = { renderResume, fmtAge };

package/src/render/shared.js

@@ -0,0 +1,49 @@
+// @ts-check
+'use strict';
+// src/render/shared.js — ANSI + formatting helpers shared by renderers.
+
+const e = (/** @type {string} */ c, /** @type {string} */ s) => `\x1b[${c}m${s}\x1b[0m`;
+const dim = (/** @type {string} */ s) => e('2', s);
+const bold = (/** @type {string} */ s) => e('1', s);
+const green = (/** @type {string} */ s) => e('32', s);
+const red = (/** @type {string} */ s) => e('31', s);
+const yellow = (/** @type {string} */ s) => e('33', s);
+const cyan = (/** @type {string} */ s) => e('36', s);
+
+// Imminent flash: inverse video on the "on" tick, solid red on the "off" tick.
+// Width is preserved (no padding) so rows don't shift between frames.
+const flash = (/** @type {boolean} */ tick, /** @type {string} */ s) => (tick ? e('7;1;31', s) : e('1;31', s));
+
+const pctColor = (/** @type {number} */ p) => (p >= 75 ? red : p >= 60 ? yellow : green);
+
+function bar(/** @type {number} */ p, w = 10) {
+  const f = Math.max(0, Math.min(w, Math.round((p / 100) * w)));
+  return '▓'.repeat(f) + '░'.repeat(w - f);
+}
+
+function tok(/** @type {number|null} */ n) {
+  if (n == null) return '?';
+  if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
+  if (n >= 1e3) return Math.round(n / 1e3) + 'K';
+  return String(Math.round(n));
+}
+
+function fmtMins(/** @type {number|null} */ m) {
+  if (m == null || !isFinite(m)) return '?';
+  m = Math.max(0, Math.round(m));
+  if (m >= 1440) { const d = Math.floor(m / 1440), hh = Math.floor((m % 1440) / 60); return hh ? `${d}d${hh}h` : `${d}d`; }
+  const h = Math.floor(m / 60), r = m % 60;
+  if (h >= 1) return r ? `${h}h${String(r).padStart(2, '0')}m` : `${h}h`;
+  return `${m}m`;
+}
+
+function fmtReset(/** @type {number|null} */ min) {
+  if (min == null) return '';
+  min = Math.round(min); // round to whole minutes FIRST so 239.97 → 240 → 4h, not 3h60m
+  const d = Math.floor(min / 1440), h = Math.floor((min % 1440) / 60), m = min % 60;
+  if (d > 0) return `${d}d${h > 0 ? h + 'h' : ''}`;
+  if (h > 0) return `${h}h${String(m).padStart(2, '0')}m`;
+  return `${m}m`;
+}
+
+module.exports = { e, dim, bold, green, red, yellow, cyan, flash, pctColor, bar, tok, fmtMins, fmtReset };

package/src/render/statusline.js

@@ -0,0 +1,48 @@
+// @ts-check
+'use strict';
+// src/render/statusline.js — compact one-line economy summary for CC's status bar.
+// Plain text (no ANSI) so it renders cleanly wherever the status line appears.
+
+const { windowEstimate, binding } = require('../burn');
+const { fmtMins } = require('./shared');
+
+/**
+ * @param {any} view normalized economy data
+ * @returns {string} one line, e.g. "Sonnet 4.6 · weekly · Sonnet ~5h · ctx 15% · $2.50"
+ */
+function renderStatusline(view) {
+  const parts = [];
+  if (view.model) parts.push(view.model);
+
+  const windows = Array.isArray(view.windows) ? view.windows : [];
+  if (!windows.length) {
+    parts.push('API · no limits');
+  } else {
+    const rows = windows.map((/** @type {any} */ wd) => ({
+      key: wd.key,
+      label: wd.label || wd.key,
+      est: windowEstimate({ usedPct: wd.usedPct, rate: wd.rate, minutesToReset: wd.minutesToReset, windowMinutes: wd.windowMinutes }),
+      reset: wd.minutesToReset,
+    }));
+    const live = rows
+      .filter((r) => r.est.minutesLeft != null && r.reset != null && r.est.minutesLeft < r.reset)
+      .map((r) => ({ key: r.key, est: r.est, reset: r.reset }));
+    const b = binding(live);
+    if (b && b.minutesLeft != null) {
+      const row = rows.find((r) => r.key === b.window);
+      const imminent = b.minutesLeft <= 30 ? '⚠ ' : '';
+      parts.push(`${imminent}${row ? row.label : b.window} ~${fmtMins(b.minutesLeft)}`);
+    } else {
+      parts.push('within limits');
+    }
+  }
+
+  if (view.contextTokens != null && view.windowSize) {
+    parts.push(`ctx ${Math.round((view.contextTokens / view.windowSize) * 100)}%`);
+  }
+  if (view.costUsd != null) parts.push('$' + view.costUsd.toFixed(2));
+
+  return parts.join(' · ');
+}
+
+module.exports = { renderStatusline };

package/src/resume.js

@@ -0,0 +1,74 @@
+// @ts-check
+'use strict';
+// src/resume.js — the resume-cost ADVISOR (not a picker). Claude Code's own
+// `--resume` picker is good; ccr only adds the economics it can't show, then
+// hands selection back to `claude --resume`.
+//
+// For each recent session: how heavy is it to bring back (last turn's input-side
+// tokens ≈ the context re-fed), as a share of the model's context window, and
+// whether its cache is cold (stale ⇒ the first turn re-pays full cache-creation).
+// We deliberately do NOT express cost as a % of the rate-limit window — ccr
+// doesn't know its absolute token cap, so that would be fabricated.
+
+const { listSessionFiles, readSession } = require('./transcripts');
+const { inferWindow } = require('./burn');
+
+const COLD_MS = 5 * 60 * 1000;   // cache TTL: older than this ⇒ cold
+const SCAN_CAP = 80;             // bound work: parse at most this many files
+
+/** Context re-fed on resume ≈ the last assistant turn's input side. @param {any} parsed */
+function contextTokens(parsed) {
+  const t = parsed && parsed.stats && parsed.stats.lastTurn;
+  return t ? (t.input || 0) + (t.cacheRead || 0) + (t.cacheCreate || 0) : 0;
+}
+
+/**
+ * Build one advisor row from a parsed transcript + its file metadata. Pure.
+ * @param {any} parsed  result of parseEvents/readSession
+ * @param {{ sessionId: string, mtimeMs: number }} file
+ * @param {number} now  epoch ms
+ * @returns {{ sessionId: string, title: string, branch: string|null, cwd: string|null, ageMin: number, ctx: number, winPct: number, cold: boolean }}
+ */
+function buildRow(parsed, file, now) {
+  const ctx = contextTokens(parsed);
+  const win = inferWindow({ model: parsed.stats.lastModel || undefined });
+  const ageMs = Math.max(0, now - file.mtimeMs);
+  return {
+    sessionId: file.sessionId,
+    title: parsed.title || parsed.lastPrompt || '(untitled)',
+    branch: parsed.meta.gitBranch,
+    cwd: parsed.meta.cwd,
+    ageMin: Math.round(ageMs / 60000),
+    ctx,
+    winPct: win ? Math.round((ctx / win) * 100) : 0,
+    cold: ageMs > COLD_MS,
+  };
+}
+
+/**
+ * Gather recent sessions as advisor rows, newest first.
+ * @param {{ limit?: number, scope?: 'cwd'|'all', cwd?: string, now?: number, files?: any[] }} [opts]
+ * @returns {ReturnType<typeof buildRow>[]}
+ */
+function gather(opts = {}) {
+  const limit = opts.limit || 12;
+  const scope = opts.scope || 'cwd';
+  const cwd = opts.cwd || process.cwd();
+  const now = opts.now || Date.now();
+  const files = opts.files || listSessionFiles();
+  /** @type {ReturnType<typeof buildRow>[]} */
+  const rows = [];
+  let scanned = 0;
+  for (const f of files) {
+    if (rows.length >= limit || scanned >= SCAN_CAP) break;
+    scanned++;
+    const parsed = readSession(f.path);
+    if (!parsed) continue;
+    if (scope === 'cwd' && parsed.meta.cwd && parsed.meta.cwd !== cwd) continue;
+    if (!contextTokens(parsed) && !parsed.title) continue; // skip empty/aborted
+    rows.push(buildRow(parsed, f, now));
+  }
+  return rows;
+}
+
+module.exports = { buildRow, gather, contextTokens, COLD_MS, SCAN_CAP };

package/src/sanitize.js

@@ -0,0 +1,31 @@
+// @ts-check
+'use strict';
+// src/sanitize.js — strip terminal control characters from externally-sourced
+// text before it is rendered.
+//
+// Transcript titles/prompts/tool-args and status-JSON fields (model name,
+// rate-limit labels) can contain arbitrary bytes — web content the assistant
+// fetched, pasted data, a planted snapshot. Emitting raw ANSI/control sequences
+// to a terminal enables output spoofing (and worse on some terminals). These are
+// all single-line display fields, so we drop every C0/C1 control + DEL
+// (including ESC, newline, tab). Applied at the ingestion choke points
+// (parseEvents, normalizeStatus, discoverWindows) so every renderer is covered.
+//
+// `ccr economy --json` needs no extra escaping layer: its string fields (model,
+// rate-limit labels) come from the SAME sanitized ingestion (normalizeStatus /
+// discoverWindows), so they are already control-char-free. (Note JSON.stringify
+// alone is NOT sufficient — it escapes C0 but leaves DEL/C1 bytes raw — which is
+// exactly why we sanitize at ingestion rather than rely on the serializer.)
+
+// C0 controls (00-1F, incl. ESC/newline/tab), DEL (7F), and C1 controls (80-9F).
+const CONTROL_RE = /[\x00-\x1f\x7f-\x9f]/g;
+
+/**
+ * @param {any} s
+ * @returns {any} the string with control chars removed; non-strings pass through
+ */
+function stripControl(s) {
+  return typeof s === 'string' ? s.replace(CONTROL_RE, '') : s;
+}
+
+module.exports = { stripControl };

package/src/sidecar.js

@@ -0,0 +1,94 @@
+// @ts-check
+'use strict';
+// src/sidecar.js — the live economy panel that runs in the tmux sidebar.
+// Reads the per-session snapshot that `ccr statusline` writes (CCR_STATE_DIR),
+// re-renders the economy screen every second (so the imminent band flashes),
+// and shows a clean ended/​waiting state. Pure Node, zero dependencies.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { normalizeStatus } = require('./normalize');
+const { renderEconomy } = require('./render/economy');
+const { renderFeed } = require('./render/feed');
+const { currentTranscriptPath, readNewLines, parseEvents } = require('./transcripts');
+
+const STATE_DIR = process.env.CCR_STATE_DIR || path.join(os.homedir(), '.ccr');
+const SNAPSHOT = path.join(STATE_DIR, 'last-status.json');
+const EXITED = path.join(STATE_DIR, 'exited');
+
+// Live feed accumulator: tail the current transcript incrementally (by byte
+// offset) and roll up tool/skill events + per-session stats. Reset on session
+// switch. Best-effort — must never break the economy panel.
+const FEED_CAP = 200;
+const feedState = { path: /** @type {string|null} */ (null), offset: 0, events: /** @type {any[]} */ ([]), tools: /** @type {Record<string,number>} */ ({}), commands: 0, tokens: { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 }, files: new Set() };
+
+/** @param {string} tpath @returns {any} feed view for renderFeed */
+function updateFeed(tpath) {
+  if (feedState.path !== tpath) {           // new session → start clean
+    feedState.path = tpath; feedState.offset = 0; feedState.events = []; feedState.tools = {};
+    feedState.commands = 0; feedState.tokens = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 }; feedState.files = new Set();
+  }
+  const { offset, lines } = readNewLines(tpath, feedState.offset);
+  feedState.offset = offset;
+  if (lines.length) {
+    const p = parseEvents(lines);
+    for (const e of p.events) feedState.events.push(e);
+    if (feedState.events.length > FEED_CAP) feedState.events.splice(0, feedState.events.length - FEED_CAP);
+    for (const k of Object.keys(p.stats.tools)) feedState.tools[k] = (feedState.tools[k] || 0) + p.stats.tools[k];
+    feedState.commands += p.stats.commands;
+    feedState.tokens.input += p.stats.tokens.input;
+    feedState.tokens.output += p.stats.tokens.output;
+    feedState.tokens.cacheRead += p.stats.tokens.cacheRead;
+    feedState.tokens.cacheCreate += p.stats.tokens.cacheCreate;
+    for (const f of p.stats.files) feedState.files.add(f);
+  }
+  return { events: feedState.events, tools: feedState.tools, commands: feedState.commands, tokens: feedState.tokens, files: [...feedState.files] };
+}
+
+const dim = (/** @type {string} */ s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (/** @type {string} */ s) => `\x1b[1m${s}\x1b[0m`;
+
+let prev = '';
+function draw(/** @type {string} */ s) {
+  if (s === prev) return;
+  prev = s;
+  // Cursor home, clear-to-EOL per line, then clear below — flicker-free.
+  process.stdout.write('\x1b[H' + s.replace(/\n/g, '\x1b[K\n') + '\x1b[J');
+}
+
+function frame() {
+  if (fs.existsSync(EXITED)) { draw(bold('ccr') + '  ' + dim('session ended') + '\n'); return; }
+  let raw = '';
+  try { raw = fs.readFileSync(SNAPSHOT, 'utf8'); } catch { /* none yet */ }
+  if (!raw.trim()) { draw(dim('ccr · waiting for the first status tick…') + '\n'); return; }
+  let state;
+  try { state = JSON.parse(raw); } catch { draw(dim('ccr · status unreadable') + '\n'); return; }
+  let out;
+  try {
+    out = renderEconomy(normalizeStatus(state), { tick: Math.floor(Date.now() / 1000) % 2 === 0 });
+  } catch (e) {
+    out = dim('ccr render error: ' + (e && e instanceof Error ? e.message : String(e)));
+  }
+  // Live tool/skills feed below the panel — best-effort; never break the panel.
+  try {
+    const tpath = currentTranscriptPath(state);
+    if (tpath) {
+      const feedStr = renderFeed(updateFeed(tpath), { max: 6 });
+      if (feedStr) out += '\n\n' + feedStr;
+    }
+  } catch { /* feed is optional */ }
+  draw(out.endsWith('\n') ? out : out + '\n');
+}
+
+function run() {
+  frame();
+  const id = setInterval(frame, 1000);
+  const stop = () => { clearInterval(id); process.exit(0); };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+// `updateFeed` is exported for tests (the incremental tail + session-switch
+// reset is the subtle part); the live loop uses `run`.
+module.exports = { run, updateFeed };

package/src/state-dir.js

@@ -0,0 +1,21 @@
+// @ts-check
+'use strict';
+// src/state-dir.js — ccr keeps its local state under the user's home (~/.ccr),
+// never in world-shared /tmp. Captured status includes the transcript path,
+// cost, and usage %, so the directory is created owner-only (0700) to keep other
+// local users from reading it. Best-effort: state I/O must never break the
+// status line, so callers wrap this in try/catch.
+
+const fs = require('node:fs');
+
+/**
+ * Create (or tighten to owner-only) a state directory.
+ * @param {string} dir
+ */
+function ensureSecureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // mkdir's mode only applies to dirs it creates; tighten a pre-existing one.
+  try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
+}
+
+module.exports = { ensureSecureDir };

package/src/theme.js

@@ -0,0 +1,37 @@
+// @ts-check
+'use strict';
+// src/theme.js — UI lexicon and theme gating.
+//
+// Default ("plain") is accessible: "the wall" works as the everyday "hit the
+// wall" idiom for hitting your limit. The "mary" theme (Proud Mary — CCR) swaps
+// in the full classic-rock vocabulary. It auto-enables on the CCR debut-album
+// anniversary, and can be forced any day via the innocuous env switch
+// CCR_ENABLE_MARY_INTERFACE (a "subtle startup switch" that gives nothing away).
+
+const THEMES = {
+  plain: { wall: 'the wall', within: 'within limits', imminent: 'limit imminent', looming: 'next limit', clearKey: 'F2·clear' },
+  mary:  { wall: 'the wall', within: 'comfortably numb', imminent: 'bad moon rising', looming: 'up around the bend', clearKey: 'F2·wipe out' },
+};
+
+// Creedence Clearwater Revival — self-titled debut LP, released July 5, 1968.
+const CCR_DEBUT = { month: 7, day: 5 };
+
+/**
+ * @param {Date} [now]
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {'plain'|'mary'}
+ */
+function resolveTheme(now, env) {
+  const e = env || process.env;
+  if (e.CCR_ENABLE_MARY_INTERFACE) return 'mary';
+  const d = now || new Date();
+  if (d.getMonth() + 1 === CCR_DEBUT.month && d.getDate() === CCR_DEBUT.day) return 'mary';
+  return 'plain';
+}
+
+/** @param {string} [name] */
+function lexicon(name) {
+  return THEMES[name === 'mary' ? 'mary' : 'plain'];
+}
+
+module.exports = { THEMES, CCR_DEBUT, resolveTheme, lexicon };