claude-token-saver 2.0.3 → 2.2.0

package/src/formatters/statusline.js

@@ -49,6 +49,39 @@ function formatTimer(remainingSec) {
   return `${m}:${String(s).padStart(2, '0')}`;
 }
 
+/**
+ * Pick the cap-warn chip ({ kind, usedPct, resetsAt, label }) that should
+ * surface, or null if neither window is at 90%+. When both windows are warning,
+ * the one that resets sooner wins (it's the more imminent block).
+ */
+export function pickCapWarn(caps) {
+  if (!caps) return null;
+  const candidates = [];
+  if (caps.fiveHour && caps.fiveHour.usedPct >= 90) {
+    candidates.push({
+      kind: 'five_hour',
+      label: '5H',
+      usedPct: caps.fiveHour.usedPct,
+      resetsAt: caps.fiveHour.resetsAt,
+    });
+  }
+  if (caps.sevenDay && caps.sevenDay.usedPct >= 90) {
+    candidates.push({
+      kind: 'seven_day',
+      label: '7D',
+      usedPct: caps.sevenDay.usedPct,
+      resetsAt: caps.sevenDay.resetsAt,
+    });
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => {
+    const ar = Number.isFinite(a.resetsAt) ? a.resetsAt : Infinity;
+    const br = Number.isFinite(b.resetsAt) ? b.resetsAt : Infinity;
+    return ar - br;
+  });
+  return candidates[0];
+}
+
 /**
  * @param {object} data - output of main report pipeline (summary, ttl, cost, options, lastActivity)
  * @param {object} [opts]
@@ -56,9 +89,10 @@ function formatTimer(remainingSec) {
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
+ * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, hit, ttl, saved, ctx, period. Null/undefined = all.
  */
-export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text' } = {}) {
-  const { summary, ttl, cost, options, lastActivity, contextWindow, spikeChip } = data;
+export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null } = {}) {
+  const { summary, ttl, cost, options, lastActivity, contextWindow, spikeChip, caps } = data;
   const { hitRate } = summary;
 
   // Hit rate → color signal
@@ -87,25 +121,31 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     : 'Cache hit';
   const hitSeg = `${c(BOLD)}${hitLabel}${c(RESET)} ${c(hitColor)}${formatPct(hitRate)}${c(RESET)}`;
 
-  //   text:       "Cost saved $1.5K"                |  same in verbose
-  //   icon:       "💰 $1.5K"                          |  verbose: "💰 Cost saved $1.5K"
+  //   text:       "Cache saved $1.5K"                |  same in verbose
+  //   icon:       "💰 $1.5K"                          |  verbose: "💰 Cache saved $1.5K"
   const saveLabel = isIcon
-    ? (verbose ? '💰 Cost saved' : '💰')
-    : 'Cost saved';
+    ? (verbose ? '💰 Cache saved' : '💰')
+    : 'Cache saved';
   const saveSeg = `${c(CYAN)}${saveLabel}${c(RESET)} ${formatMoney(savings)}`;
 
+  // Period label honors hour-precision configs (`mode 6h` → "6h", `mode 1d` → "1d").
+  // Fall back to legacy `${days}d` when callers haven't supplied a label.
+  const periodLabel = options.windowLabel || `${options.days}d`;
   const periodSeg = verbose
-    ? `${c(GRAY)}last ${options.days}d${c(RESET)}`
-    : `${c(GRAY)}${options.days}d${c(RESET)}`;
+    ? `${c(GRAY)}last ${periodLabel}${c(RESET)}`
+    : `${c(GRAY)}${periodLabel}${c(RESET)}`;
 
   // TTL countdown — how much time is left on the last API call's cache entry.
   // Matches Anthropic's actual prompt-cache behaviour: each call starts a fresh
   // TTL window, and the next call (hit) within that window resets it. So the
   // countdown visibly ticks down between prompts, and "resets" happens as a
   // jump back toward the bucket max the moment you send another message.
-  //   text compact:   "Expires 1h 59:58"
+  // Compact modes drop the bucket label — it's read as part of the clock
+  // ("1h 59:58" gets parsed as "1 hour 59 minutes 58 seconds"). The bucket
+  // is plan-determined and rarely changes, so verbose mode is where it belongs.
+  //   text compact:   "Expires 59:58"
   //   text verbose:   "1h bucket · expires in 59:58"
-  //   icon compact:   "⏳ 1h 59:58"
+  //   icon compact:   "⏳ 59:58"
   //   icon verbose:   "⏳ Expires 1h 59:58"
   let ttlSeg;
   if (timer && lastActivity) {
@@ -119,22 +159,28 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       pct > 0.10 ? YELLOW :
       RED;
 
-    if (isIcon) {
-      const prefix = verbose ? '⏳ Expires ' : '⏳ ';
-      ttlSeg = `${c(bucketColor)}${prefix}${bucketLabel}${c(RESET)} ${c(timerColor)}${text}${c(RESET)}`;
+    if (isIcon && verbose) {
+      // Drop bucket here too — `⏳ Expires 1h 57:20` reads as "1h 57m 20s left"
+      // for the same reason the compact form did. The bucket lives in the
+      // text-verbose layout where the "bucket" word + `·` separator make it
+      // unambiguous.
+      ttlSeg = `${c(timerColor)}⏳ Cache expires ${text}${c(RESET)}`;
+    } else if (isIcon) {
+      ttlSeg = `${c(timerColor)}⏳ ${text}${c(RESET)}`;
     } else if (verbose) {
-      ttlSeg = `${c(bucketColor)}${bucketLabel} bucket${c(RESET)} · ${c(timerColor)}expires in ${text}${c(RESET)}`;
+      ttlSeg = `${c(bucketColor)}Cache ${bucketLabel} bucket${c(RESET)} · ${c(timerColor)}expires in ${text}${c(RESET)}`;
     } else {
-      ttlSeg = `${c(bucketColor)}Expires ${bucketLabel}${c(RESET)} ${c(timerColor)}${text}${c(RESET)}`;
+      ttlSeg = `${c(timerColor)}Cache expires ${text}${c(RESET)}`;
     }
   } else {
+    // No-timer fallback: only the bucket is available, so we show just that.
     if (isIcon) {
-      const prefix = verbose ? '⏳ Bucket ' : '⏳ ';
+      const prefix = verbose ? '⏳ Cache bucket ' : '⏳ ';
       ttlSeg = `${c(bucketColor)}${prefix}${bucketLabel}${c(RESET)}`;
     } else if (verbose) {
-      ttlSeg = `${c(bucketColor)}${bucketLabel} bucket${c(RESET)}`;
+      ttlSeg = `${c(bucketColor)}Cache ${bucketLabel} bucket${c(RESET)}`;
     } else {
-      ttlSeg = `${c(bucketColor)}Bucket ${bucketLabel}${c(RESET)}`;
+      ttlSeg = `${c(bucketColor)}Cache bucket ${bucketLabel}${c(RESET)}`;
     }
   }
 
@@ -144,7 +190,9 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   if (contextWindow && contextWindow.size && contextWindow.size !== 'unknown') {
     const label = contextWindow.size === '1M' ? '1M' : '200k';
     const ctxColor = contextWindow.size === '1M' ? RED : GREEN;
-    if (isIcon) {
+    if (isIcon && verbose) {
+      ctxSeg = `${c(ctxColor)}📦 Context ${label}${c(RESET)}`;
+    } else if (isIcon) {
       ctxSeg = `${c(ctxColor)}📦 ${label}${c(RESET)}`;
     } else if (verbose) {
       ctxSeg = `${c(ctxColor)}Context ${label}${c(RESET)}`;
@@ -156,9 +204,40 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // Spike chip — one word only, keeps the statusline single-line.
   const spikeSeg = spikeChip ? `${c(RED)}${spikeChip}${c(RESET)}` : null;
 
-  const segs = [hitSeg, ttlSeg, saveSeg];
-  if (ctxSeg) segs.push(ctxSeg);
-  if (spikeSeg) segs.push(spikeSeg);
-  segs.push(periodSeg);
+  // Cap-warn chip — leads everything when ANY rate-limit window is at 90%+.
+  // It's the most actionable signal we can show: no point optimizing cache
+  // hits if you're about to be rate-limited anyway. The chip body matches the
+  // English shape `🚨 5H 94%` / `🚨 7D 92%` so history parsers can dedupe on it.
+  const capWarn = pickCapWarn(caps);
+  let capWarnSeg = null;
+  if (capWarn) {
+    const pct = Math.round(capWarn.usedPct);
+    if (isIcon && verbose) {
+      capWarnSeg = `${c(BOLD)}${c(RED)}🚨 ${capWarn.label} cap ${pct}%${c(RESET)}`;
+    } else if (isIcon) {
+      capWarnSeg = `${c(BOLD)}${c(RED)}🚨 ${capWarn.label} ${pct}%${c(RESET)}`;
+    } else if (verbose) {
+      capWarnSeg = `${c(BOLD)}${c(RED)}${capWarn.label} cap ${pct}%${c(RESET)}`;
+    } else {
+      capWarnSeg = `${c(BOLD)}${c(RED)}${capWarn.label} ${pct}%${c(RESET)}`;
+    }
+  }
+
+  // Warning chip leads — a glance at the statusline catches "something's wrong"
+  // before parsing any numbers. Healthy states have no chip and look unchanged.
+  // Cap-warn outranks spike: an imminent rate-limit block is more urgent than
+  // a single spiking session.
+  const allow = segments && segments.length
+    ? new Set(segments.map((s) => s.toLowerCase()))
+    : null;
+  const want = (name) => !allow || allow.has(name);
+  const segs = [];
+  if (capWarnSeg && want('cap-warn')) segs.push(capWarnSeg);
+  if (spikeSeg && want('spike')) segs.push(spikeSeg);
+  if (want('hit')) segs.push(hitSeg);
+  if (want('ttl')) segs.push(ttlSeg);
+  if (want('saved')) segs.push(saveSeg);
+  if (ctxSeg && want('ctx')) segs.push(ctxSeg);
+  if (want('period')) segs.push(periodSeg);
   return segs.join(' · ');
 }

package/src/formatters/table.js

@@ -64,11 +64,11 @@ function formatContextSize(n) {
 
 function renderSpikeSection(spikes, contextWindow) {
   const lines = [];
-  lines.push('  ⚠ 토큰 급증 감지');
+  lines.push('  ⚠ Token spike detected');
   lines.push(`  ${'─'.repeat(50)}`);
   if (contextWindow && contextWindow.size === '1M') {
     lines.push(
-      `  컨텍스트 모드 추정: 1M  (최근 단일 요청 최대 ${formatContextSize(contextWindow.maxContext)} 토큰)`,
+      `  Context mode: 1M  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`,
     );
     lines.push('');
   }
@@ -77,11 +77,11 @@ function renderSpikeSection(spikes, contextWindow) {
     const ratioLabel = spike.ratio ? `${spike.ratio.toFixed(1)}× p95` : 'single-request > 250k';
     lines.push(
       `  • ${shortSessionId(m.sessionId)} [${m.projectDir || 'unknown'}]  ` +
-        `총 입력 ${formatContextSize(m.totalInput)}  (${ratioLabel}, 요청 ${m.requestCount}회)`,
+        `total input ${formatContextSize(m.totalInput)}  (${ratioLabel}, ${m.requestCount} requests)`,
     );
     if (m.maxContextPerRequest > 0) {
       lines.push(
-        `      단일 요청 최대 컨텍스트: ${formatContextSize(m.maxContextPerRequest)} 토큰`,
+        `      max single-request context: ${formatContextSize(m.maxContextPerRequest)} tokens`,
       );
     }
     for (const issue of spike.issues) {
@@ -104,7 +104,7 @@ function renderSpikeSection(spikes, contextWindow) {
     }
   }
   if (uniqueIssues.length > 0) {
-    lines.push('  권장 액션');
+    lines.push('  Recommended actions');
     lines.push(`  ${'─'.repeat(50)}`);
     for (const issue of uniqueIssues) {
       const info = ISSUE_MESSAGES[issue.code];
@@ -123,17 +123,57 @@ function renderSpikeSection(spikes, contextWindow) {
   return lines;
 }
 
-export function formatReport({ summary: sum, trend, ttl, anomalies, cost, options, spikeReport, contextWindow }) {
+function formatResetIn(resetsAt, now = new Date()) {
+  if (!Number.isFinite(resetsAt)) return null;
+  const remaining = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
+  if (remaining <= 0) return '0m';
+  const h = Math.floor(remaining / 3600);
+  const m = Math.floor((remaining % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+function renderCapWarnSection(caps) {
+  const warning = [];
+  if (caps.fiveHour && caps.fiveHour.usedPct >= 90) {
+    warning.push({ label: '5-hour window', info: caps.fiveHour });
+  }
+  if (caps.sevenDay && caps.sevenDay.usedPct >= 90) {
+    warning.push({ label: '7-day window', info: caps.sevenDay });
+  }
+  if (warning.length === 0) return [];
+  const lines = [];
+  lines.push('  🚨 Rate-limit cap is closing in');
+  lines.push(`  ${'─'.repeat(50)}`);
+  for (const { label, info } of warning) {
+    const reset = formatResetIn(info.resetsAt);
+    const tail = reset ? `, resets in ${reset}` : '';
+    lines.push(`  • ${label}: ${Math.round(info.usedPct)}% used${tail}`);
+  }
+  lines.push('');
+  lines.push('  Back up work before the cap hits:');
+  lines.push('    claude-token-saver handoff');
+  lines.push('  (writes a HANDOFF-*.md so a fresh session can pick up.)');
+  lines.push('');
+  return lines;
+}
+
+export function formatReport({ summary: sum, trend, ttl, anomalies, cost, options, spikeReport, contextWindow, caps }) {
   const lines = [];
 
   // Header
   lines.push('');
-  lines.push(`  Claude 토큰 아껴쓰기 — Last ${options.days} days`);
+  lines.push(`  Claude Token Saver — Last ${options.days} day${options.days === 1 ? '' : 's'}`);
   lines.push(`  (claude-token-saver v${options.version || ''})`.trimEnd());
   lines.push(`  ${'═'.repeat(50)}`);
   lines.push('');
 
-  // Spike section goes FIRST — it's what the user acts on.
+  // Cap warning leads — it's the most time-sensitive signal we can show.
+  if (caps) {
+    lines.push(...renderCapWarnSection(caps));
+  }
+
+  // Spike section goes next — it's what the user acts on.
   if (spikeReport && spikeReport.spikes.length > 0) {
     lines.push(...renderSpikeSection(spikeReport.spikes, contextWindow));
   }
@@ -142,10 +182,10 @@ export function formatReport({ summary: sum, trend, ttl, anomalies, cost, option
   if (contextWindow && contextWindow.size !== 'unknown') {
     const note =
       contextWindow.size === '1M'
-        ? '⚠ 1M 컨텍스트 사용 중 (Opus 4.7+ Max 기본값). 필요 없으면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1'
-        : '✓ 200k 컨텍스트 (표준)';
+        ? '⚠ 1M context active (Opus 4.7+ Max default). Disable with CLAUDE_CODE_DISABLE_1M_CONTEXT=1'
+        : '✓ 200k context (standard)';
     lines.push(`  Context window: ${contextWindow.size}  ${note}`);
-    lines.push(`  (최근 단일 요청 최대 ${formatContextSize(contextWindow.maxContext)} 토큰)`);
+    lines.push(`  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`);
     lines.push('');
   }
 

package/src/handoff.js

@@ -0,0 +1,162 @@
+/**
+ * Handoff template — captures enough state at session-cap time that a fresh
+ * Claude Code session can pick up the work without a long prelude.
+ *
+ * Output: `./HANDOFF-YYYY-MM-DD-HHMM.md` in the caller's cwd. We never
+ * overwrite — if the path is taken we add a `-N` suffix.
+ *
+ * What goes in:
+ *   - Header: timestamp, cwd, git branch / HEAD / dirty file list
+ *   - Cap snapshot: 5h/7d % and resets-in (when known)
+ *   - Empty fillable sections the user pastes context into
+ *   - A one-line resume prompt for the next session
+ */
+
+import { writeFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+
+function pad(n) {
+  return String(n).padStart(2, '0');
+}
+
+function ymd(d = new Date()) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+function hhmm(d = new Date()) {
+  return `${pad(d.getHours())}${pad(d.getMinutes())}`;
+}
+
+function safeGit(cmd, cwd) {
+  try {
+    return execSync(`git ${cmd}`, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function gitSnapshot(cwd) {
+  // `rev-parse --git-dir` succeeds in any repo, including a freshly-init'd one
+  // with no commits yet (where `rev-parse HEAD` would fail). We use it as the
+  // "is this a repo?" probe.
+  const gitDir = safeGit('rev-parse --git-dir', cwd);
+  if (!gitDir) return null;
+  const branch = safeGit('rev-parse --abbrev-ref HEAD', cwd) || '(no commits)';
+  const head = safeGit('rev-parse --short HEAD', cwd);
+  const status = safeGit('status --short', cwd);
+  return { branch, head, status };
+}
+
+function formatResetIn(resetsAt, now = new Date()) {
+  if (!Number.isFinite(resetsAt)) return null;
+  const remaining = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
+  if (remaining <= 0) return '0m';
+  const h = Math.floor(remaining / 3600);
+  const m = Math.floor((remaining % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+function pickPath(cwd, now) {
+  const stem = `HANDOFF-${ymd(now)}-${hhmm(now)}`;
+  const direct = join(cwd, `${stem}.md`);
+  if (!existsSync(direct)) return direct;
+  for (let i = 2; i < 100; i++) {
+    const candidate = join(cwd, `${stem}-${i}.md`);
+    if (!existsSync(candidate)) return candidate;
+  }
+  return join(cwd, `${stem}-${Date.now()}.md`);
+}
+
+function renderTemplate({ now, cwd, git, caps }) {
+  const lines = [];
+  lines.push(`# Handoff — ${ymd(now)} ${pad(now.getHours())}:${pad(now.getMinutes())}`);
+  lines.push('');
+  lines.push(`Generated by \`claude-token-saver handoff\`.`);
+  lines.push('');
+  lines.push('## Context');
+  lines.push('');
+  lines.push(`- cwd: \`${cwd}\``);
+  if (git) {
+    lines.push(`- git branch: \`${git.branch}\`${git.head ? ` @ \`${git.head}\`` : ''}`);
+    if (git.status) {
+      lines.push('- dirty files:');
+      lines.push('  ```');
+      for (const line of git.status.split('\n')) lines.push(`  ${line}`);
+      lines.push('  ```');
+    } else {
+      lines.push('- working tree: clean');
+    }
+  } else {
+    lines.push('- git: (not a repo)');
+  }
+  lines.push('');
+
+  lines.push('## Cap snapshot');
+  lines.push('');
+  if (caps) {
+    const fmtRow = (label, info) => {
+      if (!info) return `- ${label}: (unknown — stdin had no rate-limit info)`;
+      const reset = formatResetIn(info.resetsAt, now);
+      const tail = reset ? `, resets in ${reset}` : '';
+      return `- ${label}: ${Math.round(info.usedPct)}%${tail}`;
+    };
+    lines.push(fmtRow('5-hour window', caps.fiveHour));
+    lines.push(fmtRow('7-day window', caps.sevenDay));
+  } else {
+    lines.push('- (no cap data — run `handoff` from a Claude Code session for live numbers)');
+  }
+  lines.push('');
+
+  lines.push('## What I just did');
+  lines.push('');
+  lines.push('- _(fill in: 1–3 bullets describing the most recent work)_');
+  lines.push('');
+
+  lines.push('## What\'s left (TODO)');
+  lines.push('');
+  lines.push('- [ ] _(fill in)_');
+  lines.push('');
+
+  lines.push('## Where to pick up next');
+  lines.push('');
+  lines.push('- _(file paths, function names, the exact next step)_');
+  lines.push('');
+
+  lines.push('## Watch out for');
+  lines.push('');
+  lines.push('- _(non-obvious gotchas, half-finished refactors, failing tests)_');
+  lines.push('');
+
+  lines.push('## Resume prompt for the next Claude Code session');
+  lines.push('');
+  lines.push('```');
+  lines.push('Read the most recent HANDOFF-*.md in this directory and continue the work.');
+  lines.push('```');
+  lines.push('');
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Write a handoff file in the given cwd.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {object|null} [opts.caps] - { fiveHour, sevenDay } from extractCaps
+ * @param {Date} [opts.now=new Date()]
+ * @returns {{ path: string, git: { branch: string, head: string, status: string } | null }}
+ */
+export function writeHandoff({ cwd = process.cwd(), caps = null, now = new Date() } = {}) {
+  const absCwd = resolve(cwd);
+  const git = gitSnapshot(absCwd);
+  const path = pickPath(absCwd, now);
+  const body = renderTemplate({ now, cwd: absCwd, git, caps });
+  writeFileSync(path, body);
+  return { path, git };
+}