tlc-claude-code 1.2.29 → 1.3.0

package/server/lib/usage-command.test.js

@@ -0,0 +1,391 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const { UsageCommand, parseArgs } = await import('./usage-command.js');
+
+describe('usage-command', () => {
+  let usageCommand;
+  let tempDir;
+
+  beforeEach(() => {
+    // Create temp directory for tests
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'usage-cmd-test-'));
+  });
+
+  afterEach(() => {
+    // Clean up temp directory
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('parseArgs', () => {
+    it('parses empty args', () => {
+      const result = parseArgs([]);
+      expect(result).toEqual({
+        reset: false,
+        model: null,
+        json: false,
+      });
+    });
+
+    it('parses --reset flag', () => {
+      const result = parseArgs(['--reset']);
+      expect(result).toEqual({
+        reset: true,
+        model: null,
+        json: false,
+      });
+    });
+
+    it('parses --model flag with value', () => {
+      const result = parseArgs(['--model', 'openai']);
+      expect(result).toEqual({
+        reset: false,
+        model: 'openai',
+        json: false,
+      });
+    });
+
+    it('parses --json flag', () => {
+      const result = parseArgs(['--json']);
+      expect(result).toEqual({
+        reset: false,
+        model: null,
+        json: true,
+      });
+    });
+
+    it('parses multiple flags together', () => {
+      const result = parseArgs(['--model', 'deepseek', '--json']);
+      expect(result).toEqual({
+        reset: false,
+        model: 'deepseek',
+        json: true,
+      });
+    });
+
+    it('handles --model= syntax', () => {
+      const result = parseArgs(['--model=openai']);
+      expect(result).toEqual({
+        reset: false,
+        model: 'openai',
+        json: false,
+      });
+    });
+  });
+
+  describe('execute with mocked dependencies', () => {
+    let mockBudgetTracker;
+    let mockUsageHistory;
+    let mockBudgetAlerts;
+
+    beforeEach(() => {
+      mockBudgetTracker = {
+        getUsage: vi.fn().mockReturnValue({ daily: 5.00, monthly: 50.00, requests: 100 }),
+        reset: vi.fn(),
+      };
+
+      mockUsageHistory = {
+        getHistory: vi.fn().mockReturnValue([
+          { date: '2026-01-25', daily: 4.50, monthly: 45.00 },
+          { date: '2026-01-26', daily: 5.00, monthly: 50.00 },
+        ]),
+        getAllModels: vi.fn().mockReturnValue(['openai', 'deepseek']),
+      };
+
+      mockBudgetAlerts = {
+        checkThresholds: vi.fn().mockReturnValue([]),
+        resetAlerts: vi.fn(),
+      };
+
+      usageCommand = new UsageCommand({
+        budgetTracker: mockBudgetTracker,
+        usageHistory: mockUsageHistory,
+        budgetAlerts: mockBudgetAlerts,
+      });
+    });
+
+    const defaultConfig = {
+      openai: { budgetDaily: 10, budgetMonthly: 100 },
+      deepseek: { budgetDaily: 5, budgetMonthly: 50 },
+    };
+
+    it('shows usage summary', () => {
+      const result = usageCommand.execute([], defaultConfig);
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain('Usage Summary');
+      expect(result.output).toContain('openai');
+      expect(result.output).toContain('deepseek');
+    });
+
+    it('shows history chart in summary', () => {
+      const result = usageCommand.execute([], defaultConfig);
+
+      expect(result.output).toContain('7-Day Usage History');
+    });
+
+    it('filters by model when --model flag provided', () => {
+      const result = usageCommand.execute(['--model', 'openai'], defaultConfig);
+
+      expect(result.success).toBe(true);
+      expect(mockBudgetTracker.getUsage).toHaveBeenCalledWith('openai');
+      expect(mockBudgetTracker.getUsage).not.toHaveBeenCalledWith('deepseek');
+    });
+
+    it('outputs JSON format when --json flag provided', () => {
+      const result = usageCommand.execute(['--json'], defaultConfig);
+
+      expect(result.success).toBe(true);
+      expect(result.json).toBeDefined();
+      expect(result.json.models).toBeDefined();
+    });
+
+    it('includes usage data in JSON output', () => {
+      const result = usageCommand.execute(['--json'], defaultConfig);
+
+      expect(result.json.models.openai).toBeDefined();
+      expect(result.json.models.openai.daily).toBe(5.00);
+      expect(result.json.models.openai.monthly).toBe(50.00);
+    });
+
+    it('includes totals in JSON output', () => {
+      const result = usageCommand.execute(['--json'], defaultConfig);
+
+      expect(result.json.totals).toBeDefined();
+      expect(result.json.totals.daily).toBe(10); // 5 + 5
+      expect(result.json.totals.monthly).toBe(100); // 50 + 50
+    });
+
+    it('resets usage when --reset flag provided', () => {
+      const result = usageCommand.execute(['--reset'], defaultConfig);
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain('reset');
+      expect(mockBudgetTracker.reset).toHaveBeenCalled();
+      expect(mockBudgetAlerts.resetAlerts).toHaveBeenCalled();
+    });
+
+    it('resets only specified model with --reset --model', () => {
+      usageCommand.execute(['--reset', '--model', 'openai'], defaultConfig);
+
+      expect(mockBudgetTracker.reset).toHaveBeenCalledWith('openai');
+      expect(mockBudgetAlerts.resetAlerts).toHaveBeenCalledWith('openai');
+      expect(mockBudgetTracker.reset).toHaveBeenCalledTimes(1);
+    });
+
+    it('handles no usage data gracefully', () => {
+      mockBudgetTracker.getUsage.mockReturnValue({ daily: 0, monthly: 0, requests: 0 });
+      mockUsageHistory.getHistory.mockReturnValue([]);
+
+      const result = usageCommand.execute([], defaultConfig);
+
+      expect(result.success).toBe(true);
+      // Should still show the summary even with zero usage
+      expect(result.output).toContain('Usage Summary');
+    });
+
+    it('shows alerts if threshold crossed', () => {
+      const alert = {
+        model: 'openai',
+        threshold: 0.8,
+        currentSpend: 8.00,
+        budgetLimit: 10.00,
+        percentUsed: 80,
+        severity: 'caution',
+      };
+
+      mockBudgetAlerts.checkThresholds.mockReturnValue([alert]);
+
+      const result = usageCommand.execute([], defaultConfig);
+
+      expect(result.success).toBe(true);
+      expect(result.alerts).toBeDefined();
+      expect(result.alerts.length).toBeGreaterThan(0);
+      expect(result.alerts[0]).toContain('Budget Alert');
+    });
+
+    it('includes alerts in JSON output', () => {
+      const alert = {
+        model: 'openai',
+        threshold: 0.8,
+        currentSpend: 8.00,
+        budgetLimit: 10.00,
+        percentUsed: 80,
+        severity: 'caution',
+      };
+
+      mockBudgetAlerts.checkThresholds.mockReturnValue([alert]);
+
+      const result = usageCommand.execute(['--json'], defaultConfig);
+
+      expect(result.json.alerts).toBeDefined();
+      expect(result.json.alerts.length).toBeGreaterThan(0);
+    });
+
+    it('returns error for unknown model with --model flag', () => {
+      const result = usageCommand.execute(['--model', 'unknown'], defaultConfig);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('unknown');
+    });
+  });
+
+  describe('getUsageData', () => {
+    let mockBudgetTracker;
+
+    beforeEach(() => {
+      mockBudgetTracker = {
+        getUsage: vi.fn().mockReturnValue({ daily: 5.00, monthly: 50.00, requests: 100 }),
+        reset: vi.fn(),
+      };
+
+      usageCommand = new UsageCommand({
+        budgetTracker: mockBudgetTracker,
+        usageHistory: { getHistory: vi.fn(), getAllModels: vi.fn() },
+        budgetAlerts: { checkThresholds: vi.fn(), resetAlerts: vi.fn() },
+      });
+    });
+
+    it('collects usage data from all models', () => {
+      const data = usageCommand.getUsageData(['openai', 'deepseek']);
+
+      expect(data.openai).toBeDefined();
+      expect(data.deepseek).toBeDefined();
+      expect(mockBudgetTracker.getUsage).toHaveBeenCalledWith('openai');
+      expect(mockBudgetTracker.getUsage).toHaveBeenCalledWith('deepseek');
+    });
+
+    it('returns empty object for empty model list', () => {
+      const data = usageCommand.getUsageData([]);
+
+      expect(data).toEqual({});
+    });
+  });
+
+  describe('getHistoryData', () => {
+    let mockUsageHistory;
+
+    beforeEach(() => {
+      mockUsageHistory = {
+        getHistory: vi.fn().mockReturnValue([{ date: '2026-01-25', daily: 5.0 }]),
+        getAllModels: vi.fn(),
+      };
+
+      usageCommand = new UsageCommand({
+        budgetTracker: { getUsage: vi.fn(), reset: vi.fn() },
+        usageHistory: mockUsageHistory,
+        budgetAlerts: { checkThresholds: vi.fn(), resetAlerts: vi.fn() },
+      });
+    });
+
+    it('collects history from all models', () => {
+      usageCommand.getHistoryData(['openai', 'deepseek']);
+
+      expect(mockUsageHistory.getHistory).toHaveBeenCalledWith('openai');
+      expect(mockUsageHistory.getHistory).toHaveBeenCalledWith('deepseek');
+    });
+  });
+
+  describe('calculateTotals', () => {
+    beforeEach(() => {
+      usageCommand = new UsageCommand({
+        budgetTracker: { getUsage: vi.fn(), reset: vi.fn() },
+        usageHistory: { getHistory: vi.fn(), getAllModels: vi.fn() },
+        budgetAlerts: { checkThresholds: vi.fn(), resetAlerts: vi.fn() },
+      });
+    });
+
+    it('calculates totals across models', () => {
+      const usageData = {
+        openai: { daily: 5, monthly: 50, requests: 100 },
+        deepseek: { daily: 3, monthly: 30, requests: 60 },
+      };
+      const config = {
+        openai: { budgetDaily: 10, budgetMonthly: 100 },
+        deepseek: { budgetDaily: 5, budgetMonthly: 50 },
+      };
+
+      const totals = usageCommand.calculateTotals(usageData, config);
+
+      expect(totals.daily).toBe(8);
+      expect(totals.monthly).toBe(80);
+      expect(totals.requests).toBe(160);
+      expect(totals.budgetDaily).toBe(15);
+      expect(totals.budgetMonthly).toBe(150);
+      expect(totals.remainingDaily).toBe(7);
+      expect(totals.remainingMonthly).toBe(70);
+    });
+
+    it('handles missing config for model', () => {
+      const usageData = {
+        unknown: { daily: 1, monthly: 10, requests: 5 },
+      };
+      const config = {};
+
+      const totals = usageCommand.calculateTotals(usageData, config);
+
+      expect(totals.daily).toBe(1);
+      expect(totals.budgetDaily).toBe(0);
+      expect(totals.remainingDaily).toBe(0); // Can't be negative
+    });
+  });
+
+  describe('checkAlerts', () => {
+    let mockBudgetAlerts;
+
+    beforeEach(() => {
+      mockBudgetAlerts = {
+        checkThresholds: vi.fn().mockReturnValue([]),
+        resetAlerts: vi.fn(),
+      };
+
+      usageCommand = new UsageCommand({
+        budgetTracker: { getUsage: vi.fn(), reset: vi.fn() },
+        usageHistory: { getHistory: vi.fn(), getAllModels: vi.fn() },
+        budgetAlerts: mockBudgetAlerts,
+      });
+    });
+
+    it('checks thresholds for each model', () => {
+      const usageData = {
+        openai: { daily: 8, monthly: 80 },
+        deepseek: { daily: 4, monthly: 40 },
+      };
+      const config = {
+        openai: { budgetDaily: 10, budgetMonthly: 100 },
+        deepseek: { budgetDaily: 5, budgetMonthly: 50 },
+      };
+
+      usageCommand.checkAlerts(['openai', 'deepseek'], usageData, config);
+
+      expect(mockBudgetAlerts.checkThresholds).toHaveBeenCalledWith('openai', usageData.openai, config.openai);
+      expect(mockBudgetAlerts.checkThresholds).toHaveBeenCalledWith('deepseek', usageData.deepseek, config.deepseek);
+    });
+
+    it('aggregates alerts from all models', () => {
+      const alert1 = { model: 'openai', threshold: 0.8 };
+      const alert2 = { model: 'deepseek', threshold: 0.5 };
+
+      mockBudgetAlerts.checkThresholds
+        .mockReturnValueOnce([alert1])
+        .mockReturnValueOnce([alert2]);
+
+      const usageData = {
+        openai: { daily: 8, monthly: 80 },
+        deepseek: { daily: 2.5, monthly: 25 },
+      };
+      const config = {
+        openai: { budgetDaily: 10 },
+        deepseek: { budgetDaily: 5 },
+      };
+
+      const alerts = usageCommand.checkAlerts(['openai', 'deepseek'], usageData, config);
+
+      expect(alerts).toHaveLength(2);
+      expect(alerts).toContainEqual(alert1);
+      expect(alerts).toContainEqual(alert2);
+    });
+  });
+});

package/server/lib/usage-formatter.js

@@ -0,0 +1,192 @@
+/**
+ * Usage Formatter - Format usage data for display
+ */
+
+const BAR_WIDTH = 20;
+const BAR_CHAR = '\u2588'; // Full block character
+
+/**
+ * Format amount as currency with dollar sign and 2 decimals
+ * @param {number} amount - Amount in USD
+ * @returns {string} Formatted currency string
+ */
+function formatCurrency(amount) {
+  return '$' + amount.toLocaleString('en-US', {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  });
+}
+
+/**
+ * Format budget percentage
+ * @param {number} used - Amount used
+ * @param {number} budget - Budget limit
+ * @returns {string} Percentage string
+ */
+function formatBudgetPercentage(used, budget) {
+  if (budget === 0) {
+    return 'N/A';
+  }
+  const percentage = Math.round((used / budget) * 100);
+  return `${percentage}%`;
+}
+
+/**
+ * Format usage data as a table
+ * @param {Object} usageData - Usage data per model { model: { daily, monthly, requests } }
+ * @param {Object} budgets - Budget config per model { model: { budgetDaily, budgetMonthly } }
+ * @returns {string} Formatted table
+ */
+function formatUsageTable(usageData, budgets) {
+  const models = Object.keys(usageData);
+  if (models.length === 0) {
+    return 'No usage data available.';
+  }
+
+  // Calculate column widths
+  const headers = ['Model', 'Daily', 'Budget %', 'Monthly', 'Budget %', 'Requests'];
+  const rows = [];
+
+  for (const model of models) {
+    const usage = usageData[model];
+    const budget = budgets[model] || { budgetDaily: 0, budgetMonthly: 0 };
+
+    rows.push([
+      model,
+      formatCurrency(usage.daily),
+      formatBudgetPercentage(usage.daily, budget.budgetDaily),
+      formatCurrency(usage.monthly),
+      formatBudgetPercentage(usage.monthly, budget.budgetMonthly),
+      String(usage.requests),
+    ]);
+  }
+
+  // Calculate column widths
+  const colWidths = headers.map((h, i) => {
+    const dataWidths = rows.map(r => r[i].length);
+    return Math.max(h.length, ...dataWidths);
+  });
+
+  // Build table
+  const separator = '+' + colWidths.map(w => '-'.repeat(w + 2)).join('+') + '+';
+  const formatRow = (cols) => '| ' + cols.map((c, i) => c.padEnd(colWidths[i])).join(' | ') + ' |';
+
+  const lines = [
+    separator,
+    formatRow(headers),
+    separator,
+    ...rows.map(formatRow),
+    separator,
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate ASCII bar chart for usage history
+ * @param {Array} history - Array of { date, daily } snapshots
+ * @param {number} budgetDaily - Daily budget for scaling
+ * @returns {string} ASCII bar chart
+ */
+function generateBarChart(history, budgetDaily) {
+  if (!history || history.length === 0) {
+    return 'No usage history available.';
+  }
+
+  const lines = [];
+  lines.push('7-Day Usage History:');
+  lines.push('');
+
+  // Find max for scaling (use budget or max daily, whichever is larger)
+  const maxDaily = Math.max(...history.map(h => h.daily), budgetDaily);
+
+  for (const entry of history) {
+    const dateLabel = entry.date.slice(5); // MM-DD format
+    const percentage = maxDaily > 0 ? entry.daily / maxDaily : 0;
+    const barLength = Math.round(percentage * BAR_WIDTH);
+    const bar = BAR_CHAR.repeat(barLength);
+    const amount = formatCurrency(entry.daily);
+
+    // Mark over budget
+    const overBudget = entry.daily > budgetDaily;
+    const indicator = overBudget ? ' OVER!' : '';
+
+    lines.push(`${dateLabel} ${bar.padEnd(BAR_WIDTH)} ${amount}${indicator}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format complete usage summary
+ * @param {Object} usageData - Usage data per model
+ * @param {Object} budgets - Budget config per model
+ * @param {Object} history - History per model { model: [snapshots] }
+ * @returns {string} Complete formatted summary
+ */
+function formatUsageSummary(usageData, budgets, history) {
+  const models = Object.keys(usageData);
+
+  if (models.length === 0) {
+    return 'No usage data available.';
+  }
+
+  const lines = [];
+  lines.push('='.repeat(50));
+  lines.push('Usage Summary');
+  lines.push('='.repeat(50));
+  lines.push('');
+
+  // Usage table
+  lines.push(formatUsageTable(usageData, budgets));
+  lines.push('');
+
+  // Calculate totals
+  let totalDaily = 0;
+  let totalMonthly = 0;
+  let totalBudgetDaily = 0;
+  let totalBudgetMonthly = 0;
+
+  for (const model of models) {
+    const usage = usageData[model];
+    const budget = budgets[model] || { budgetDaily: 0, budgetMonthly: 0 };
+
+    totalDaily += usage.daily;
+    totalMonthly += usage.monthly;
+    totalBudgetDaily += budget.budgetDaily;
+    totalBudgetMonthly += budget.budgetMonthly;
+  }
+
+  // Totals section
+  lines.push('Totals:');
+  lines.push(`  Daily:   ${formatCurrency(totalDaily)} / ${formatCurrency(totalBudgetDaily)} (${formatBudgetPercentage(totalDaily, totalBudgetDaily)})`);
+  lines.push(`  Monthly: ${formatCurrency(totalMonthly)} / ${formatCurrency(totalBudgetMonthly)} (${formatBudgetPercentage(totalMonthly, totalBudgetMonthly)})`);
+  lines.push('');
+
+  // Remaining budget
+  lines.push('Remaining:');
+  lines.push(`  Daily:   ${formatCurrency(Math.max(0, totalBudgetDaily - totalDaily))}`);
+  lines.push(`  Monthly: ${formatCurrency(Math.max(0, totalBudgetMonthly - totalMonthly))}`);
+  lines.push('');
+
+  // History charts per model
+  for (const model of models) {
+    const modelHistory = history[model] || [];
+    if (modelHistory.length > 0) {
+      const budget = budgets[model] || { budgetDaily: 10 };
+      lines.push(`${model}:`);
+      lines.push(generateBarChart(modelHistory, budget.budgetDaily));
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  formatCurrency,
+  formatUsageTable,
+  formatBudgetPercentage,
+  generateBarChart,
+  formatUsageSummary,
+};