sprag-cli 3.40.0

package/src/formatters/table.js

@@ -0,0 +1,299 @@
+/**
+ * Terminal table formatter — zero dependencies.
+ */
+import { ISSUE_MESSAGES } from '../advice.js';
+import { formatResetIn, formatResetClock } from '../format-time.js';
+import { labelForKey } from '../window-labels.js';
+
+const C = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  blink:  '\x1b[5m',
+  red:    '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+};
+// Wrap text with ANSI codes — gracefully strips to plain when NO_COLOR set.
+const colorOk = !process.env.NO_COLOR;
+const r  = (s) => colorOk ? `${C.red}${s}${C.reset}` : s;
+const rb = (s) => colorOk ? `${C.bold}${C.red}${s}${C.reset}` : s;
+const rbl = (s) => colorOk ? `${C.blink}${C.bold}${C.red}${s}${C.reset}` : s;
+const y  = (s) => colorOk ? `${C.yellow}${s}${C.reset}` : s;
+const b  = (s) => colorOk ? `${C.bold}${s}${C.reset}` : s;
+
+function pad(str, len, align = 'left') {
+  const s = String(str);
+  if (align === 'right') return s.padStart(len);
+  return s.padEnd(len);
+}
+
+function pct(n) {
+  return (n * 100).toFixed(1) + '%';
+}
+
+function millions(n) {
+  return (n / 1_000_000).toFixed(2) + 'M';
+}
+
+function thousands(n) {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + 'M';
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + 'K';
+  return String(n);
+}
+
+function hr(len) {
+  return '─'.repeat(len);
+}
+
+function tableRow(cols, widths, aligns) {
+  return (
+    '│ ' +
+    cols.map((c, i) => pad(c, widths[i], aligns[i])).join(' │ ') +
+    ' │'
+  );
+}
+
+function tableSep(widths) {
+  return '├─' + widths.map((w) => hr(w)).join('─┼─') + '─┤';
+}
+
+function tableTop(widths) {
+  return '┌─' + widths.map((w) => hr(w)).join('─┬─') + '─┐';
+}
+
+function tableBot(widths) {
+  return '└─' + widths.map((w) => hr(w)).join('─┴─') + '─┘';
+}
+
+/**
+ * Format the full report for terminal output.
+ */
+function shortSessionId(id) {
+  if (!id) return '(unknown)';
+  return id.length > 8 ? id.slice(0, 8) : id;
+}
+
+function formatContextSize(n) {
+  if (!n) return '0';
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(2) + 'M';
+  if (n >= 1_000) return (n / 1_000).toFixed(0) + 'k';
+  return String(n);
+}
+
+function renderSpikeSection(spikes, contextWindow) {
+  const lines = [];
+  lines.push(rbl('  ⚠ Token spike detected'));
+  lines.push(r(`  ${'─'.repeat(50)}`));
+  if (contextWindow && contextWindow.overWarn) {
+    lines.push(
+      r(`  Context usage exceeded 500k  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`),
+    );
+    lines.push('');
+  }
+  for (const spike of spikes) {
+    const m = spike.metrics;
+    const ratioLabel = spike.ratio ? `${spike.ratio.toFixed(1)}× p95` : 'single-request > 250k';
+    lines.push(
+      r(`  • ${shortSessionId(m.sessionId)} [${m.projectDir || 'unknown'}]  `) +
+        rb(`total input ${formatContextSize(m.totalInput)}`) +
+        r(`  (${ratioLabel}, ${m.requestCount} requests)`),
+    );
+    if (m.maxContextPerRequest > 0) {
+      lines.push(
+        r(`      max single-request context: ${formatContextSize(m.maxContextPerRequest)} tokens`),
+      );
+    }
+    for (const issue of spike.issues) {
+      const info = ISSUE_MESSAGES[issue.code];
+      if (!info) continue;
+      lines.push(r(`      · ${info.title}`));
+    }
+    lines.push('');
+  }
+
+  // De-dupe action blocks — if multiple spikes share the same issue, show
+  // the remediation once per run, not once per spike.
+  const seen = new Set();
+  const uniqueIssues = [];
+  for (const spike of spikes) {
+    for (const issue of spike.issues) {
+      if (seen.has(issue.code)) continue;
+      seen.add(issue.code);
+      uniqueIssues.push(issue);
+    }
+  }
+  if (uniqueIssues.length > 0) {
+    lines.push(rb('  Recommended actions'));
+    lines.push(r(`  ${'─'.repeat(50)}`));
+    for (const issue of uniqueIssues) {
+      const info = ISSUE_MESSAGES[issue.code];
+      if (!info) continue;
+      lines.push(rb(`  ▸ ${info.title}`));
+      lines.push(r(`    ${info.explain}`));
+      for (const action of info.actions()) {
+        lines.push(r(`    - ${action.label}`));
+        for (const cmd of action.commands) {
+          lines.push(r(`        ${cmd}`));
+        }
+      }
+      lines.push('');
+    }
+  }
+  lines.push(rbl('  ▶ 상세 처치법: ') + rb('claude-token-saver last'));
+  lines.push('');
+  return lines;
+}
+
+function renderCapWarnSection(caps) {
+  if (!caps || !Array.isArray(caps.windows)) return [];
+  const warning = caps.windows.filter(
+    (w) => Number.isFinite(w.usedPct) && w.usedPct >= 90,
+  );
+  if (warning.length === 0) return [];
+  const lines = [];
+  lines.push(rbl('  🚨 Rate-limit cap is closing in'));
+  lines.push(r(`  ${'─'.repeat(50)}`));
+  for (const win of warning) {
+    const label = labelForKey(win.key).long;
+    const reset = formatResetIn(win.resetsAt);
+    const clock = formatResetClock(win.resetsAt);
+    let tail = '';
+    if (reset && clock) tail = `, resets in ${reset} (at ${clock})`;
+    else if (reset) tail = `, resets in ${reset}`;
+    else if (clock) tail = `, resets at ${clock}`;
+    lines.push(rb(`  • ${label}: ${Math.round(win.usedPct)}% used${tail}`));
+  }
+  lines.push('');
+  lines.push(r('  Back up work before the cap hits:'));
+  lines.push(rb('    claude-token-saver handoff'));
+  lines.push(r('  (writes a HANDOFF-*.md so a fresh session can pick up.)'));
+  lines.push('');
+  lines.push(rbl('  ▶ 상세 처치법: ') + rb('claude-token-saver last'));
+  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 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('');
+
+  // 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));
+  }
+
+  // Context window chip for the normal case too
+  if (contextWindow && contextWindow.size !== 'unknown') {
+    const note =
+      contextWindow.overWarn
+        ? '⚠ Context exceeded 500k in recent requests — big contexts re-bill every turn and drain the 5H/7D caps. Use /compact or /clear.'
+        : contextWindow.size === '1M'
+          ? '✓ 1M window in use, under the 500k warn line'
+          : '✓ 200k context (standard)';
+    lines.push(`  Context window: ${contextWindow.size}  ${note}`);
+    lines.push(`  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`);
+    lines.push('');
+  }
+
+  // Overall summary
+  lines.push('  Summary');
+  lines.push(`  Sessions: ${sum.sessions}  |  API calls: ${sum.apiCalls.toLocaleString()}  |  Model: ${cost.tier}`);
+  lines.push(`  Cache hit rate: ${pct(sum.hitRate)}  |  Total input: ${millions(sum.totalInput)} tokens`);
+  lines.push('');
+
+  // TTL breakdown
+  lines.push('  TTL Breakdown');
+  const ttlW = [18, 16, 16];
+  const ttlA = ['left', 'right', 'right'];
+  lines.push('  ' + tableTop(ttlW));
+  lines.push('  ' + tableRow(['', '5m Ephemeral', '1h Extended'], ttlW, ttlA));
+  lines.push('  ' + tableSep(ttlW));
+  lines.push(
+    '  ' +
+      tableRow(
+        [
+          'Cache writes',
+          `${thousands(ttl.ephemeral5m)} (${pct(ttl.pct5m)})`,
+          `${thousands(ttl.ephemeral1h)} (${pct(ttl.pct1h)})`,
+        ],
+        ttlW,
+        ttlA,
+      ),
+  );
+  lines.push('  ' + tableBot(ttlW));
+  lines.push('');
+
+  // Cost impact
+  lines.push('  Cost Impact (estimated)');
+  const costW = [24, 12];
+  const costA = ['left', 'right'];
+  lines.push('  ' + tableTop(costW));
+  lines.push('  ' + tableRow(['Actual cost', `$${cost.actual}`], costW, costA));
+  lines.push('  ' + tableRow(['Without cache', `$${cost.noCacheCost}`], costW, costA));
+  lines.push('  ' + tableSep(costW));
+  lines.push('  ' + tableRow(['Savings', `$${cost.savings} (${pct(cost.savingsRate)})`], costW, costA));
+  // Only worth asking of someone who has 1h writes to lose. Everyone else got
+  // a `+$0` that read as an endorsement of the 5m bucket they were already
+  // stuck in.
+  if (cost.extraCostIf5mApplicable === false) {
+    lines.push('  ' + tableRow(['Already 5m-only', ttl.gatewayObserved ? 'gateway' : 'yes'], costW, costA));
+  } else {
+    lines.push('  ' + tableRow(['Extra cost if 5m-only', `+$${cost.extraCostIf5m}`], costW, costA));
+  }
+  lines.push('  ' + tableBot(costW));
+  lines.push('');
+
+  // Daily trend
+  lines.push('  Daily Trend');
+  const tw = [10, 8, 7, 10, 10, 5];
+  const ta = ['left', 'right', 'right', 'right', 'right', 'right'];
+  lines.push('  ' + tableTop(tw));
+  lines.push('  ' + tableRow(['Date', 'HitRate', 'Calls', 'Read', 'Write', '5m%'], tw, ta));
+  lines.push('  ' + tableSep(tw));
+
+  const recentTrend = trend.slice(-14); // last 14 days
+  for (const d of recentTrend) {
+    const ccTotal = d.ephemeral5m + d.ephemeral1h;
+    const pct5m = ccTotal > 0 ? pct(d.ephemeral5m / ccTotal) : '-';
+    lines.push(
+      '  ' +
+        tableRow(
+          [d.date, pct(d.hitRate), String(d.apiCalls), millions(d.cacheRead), millions(d.cacheCreation), pct5m],
+          tw,
+          ta,
+        ),
+    );
+  }
+  lines.push('  ' + tableBot(tw));
+
+  if (trend.length > 14) {
+    lines.push(`  ... ${trend.length - 14} earlier days omitted (use --format json for full data)`);
+  }
+  lines.push('');
+
+  // Anomalies
+  if (anomalies.length > 0) {
+    lines.push('  ⚠ Anomalies Detected');
+    for (const a of anomalies) {
+      lines.push(
+        `    ${a.date}: hit rate ${pct(a.hitRate)} (7-day avg: ${pct(a.avgHitRate)}, drop: -${pct(a.drop)}) [${a.apiCalls} calls]`,
+      );
+    }
+  } else {
+    lines.push('  ✓ No anomalies detected');
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}

package/src/handoff.js

@@ -0,0 +1,161 @@
+/**
+ * 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';
+
+import { formatResetIn, formatResetClock } from './format-time.js';
+import { labelForKey } from './window-labels.js';
+
+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 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 && Array.isArray(caps.windows) && caps.windows.length > 0) {
+    for (const win of caps.windows) {
+      const label = labelForKey(win.key).long;
+      if (!Number.isFinite(win.usedPct)) {
+        lines.push(`- ${label}: (unknown)`);
+        continue;
+      }
+      const reset = formatResetIn(win.resetsAt, now);
+      const clock = formatResetClock(win.resetsAt, now);
+      let tail = '';
+      if (reset && clock) tail = `, resets in ${reset} (at ${clock})`;
+      else if (reset) tail = `, resets in ${reset}`;
+      else if (clock) tail = `, resets at ${clock}`;
+      lines.push(`- ${label}: ${Math.round(win.usedPct)}%${tail}`);
+    }
+  } 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] - { windows: [...] } 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 };
+}