@tokentop/ttop 0.2.2

package/src/agents/types.ts

@@ -0,0 +1,71 @@
+export type AgentName = string;
+
+export type AgentId = string;
+
+export interface TokenCounts {
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+/** Sum all token categories (input + cacheRead + cacheWrite + output). */
+export function totalTokenCount(t: TokenCounts): number {
+  return t.input + (t.cacheRead ?? 0) + (t.cacheWrite ?? 0) + t.output;
+}
+
+export interface StreamCostBreakdown {
+  total: number;
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+export interface AgentSessionStream {
+  providerId: string;
+  modelId: string;
+  tokens: TokenCounts;
+  requestCount: number;
+  costUsd?: number;
+  costBreakdown?: StreamCostBreakdown;
+  pricingSource?: 'models.dev' | 'fallback' | 'unknown';
+}
+
+export interface StreamWindowedTokens {
+  dayTokens: number;
+  weekTokens: number;
+  monthTokens: number;
+  totalTokens: number;
+}
+
+export interface AgentSessionAggregate {
+  sessionId: string;
+  sessionName?: string;
+  agentId: AgentId;
+  agentName: AgentName;
+  projectPath?: string;
+  startedAt: number;
+  lastActivityAt: number;
+  endedAt?: number;
+  status: 'active' | 'idle';
+  totals: TokenCounts;
+  totalCostUsd?: number;
+  requestCount: number;
+  streams: AgentSessionStream[];
+
+  costInDay: number;
+  costInWeek: number;
+  costInMonth: number;
+
+  /** @internal Keyed by `providerId::modelId`. Set by aggregator, consumed by costing. */
+  _streamWindowedTokens?: Map<string, StreamWindowedTokens>;
+}
+
+export interface AgentInfo {
+  agentId: AgentId;
+  name: AgentName;
+  installed: boolean;
+  sessionParsingSupported: boolean;
+  error?: string;
+}

package/src/cli.ts

@@ -0,0 +1,167 @@
+#!/usr/bin/env bun
+import * as path from 'path';
+import { startTui, type TuiOptions } from './tui/index.tsx';
+import type { DemoPreset } from './demo/simulator.ts';
+import { VERSION } from './version.ts';
+
+const DEMO_PRESETS: DemoPreset[] = ['light', 'normal', 'heavy'];
+
+function printHelp() {
+  console.log(`
+tokentop - htop for AI API usage
+
+Usage:
+  ttop [options]
+  ttop demo [options]
+
+Commands:
+  demo                    Run with demo data (no real providers)
+
+Options:
+  -r, --refresh <ms>      Refresh interval in milliseconds (default: 60000)
+  -p, --plugin <path>     Load a local plugin (file or directory, repeatable)
+  -d, --debug             Enable debug mode (verbose logging)
+  -h, --help              Show this help message
+  -v, --version           Show version
+
+Demo Options:
+  --seed <number>         Seed for deterministic demo data
+  --preset <preset>       Demo intensity: light, normal, heavy (default: normal)
+
+Keyboard shortcuts (in TUI):
+  q                     Quit
+  r                     Refresh all providers
+  d                     Toggle debug console
+
+Debug console shortcuts:
+  ESC                   Close debug console
+  c                     Clear logs
+  x                     Export logs to file (~/.local/share/tokentop/logs/)
+  y                     Copy all logs to clipboard
+  [select text]         Copies to clipboard on mouse release
+
+Examples:
+  ttop                        Start with default settings
+  ttop -r 30000               Refresh every 30 seconds
+  ttop -p ./my-plugin         Load a local plugin from a directory
+  ttop -d                     Start with debug logging enabled
+  ttop demo                   Start in demo mode
+  ttop demo --seed 42         Demo mode with seed 42 (reproducible)
+  ttop demo --preset heavy    Demo mode with high activity
+`);
+}
+
+function printVersion() {
+  console.log(`tokentop v${VERSION}`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  // Check for subcommands first
+  const subcommand = args[0] && !args[0].startsWith('-') ? args[0] : null;
+  const commandArgs = subcommand ? args.slice(1) : args;
+  
+  let refreshInterval = 60000;
+  let debug = false;
+  let demo = false;
+  let demoSeed: number | undefined;
+  let demoPreset: DemoPreset | undefined;
+  const cliPlugins: string[] = [];
+
+  // Handle demo subcommand
+  if (subcommand === 'demo') {
+    demo = true;
+  } else if (subcommand !== null) {
+    console.error(`Error: Unknown command "${subcommand}"`);
+    console.error('Run "ttop --help" for usage information');
+    process.exit(1);
+  }
+
+  for (let i = 0; i < commandArgs.length; i++) {
+    const arg = commandArgs[i];
+
+    if (arg === '-h' || arg === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+
+    if (arg === '-v' || arg === '--version') {
+      printVersion();
+      process.exit(0);
+    }
+
+    if (arg === '-d' || arg === '--debug') {
+      debug = true;
+    }
+
+    if (arg === '-p' || arg === '--plugin') {
+      const pluginPath = commandArgs[++i];
+      if (!pluginPath) {
+        console.error('Error: --plugin requires a path');
+        process.exit(1);
+      }
+      const resolved = path.resolve(pluginPath);
+      cliPlugins.push(resolved);
+    }
+
+    // Demo subcommand options
+    if (arg === '--seed') {
+      if (!demo) {
+        console.error('Error: --seed can only be used with the demo command');
+        process.exit(1);
+      }
+      const seedStr = commandArgs[++i];
+      const seed = seedStr ? parseInt(seedStr, 10) : NaN;
+      if (isNaN(seed)) {
+        console.error('Error: --seed requires a number');
+        process.exit(1);
+      }
+      demoSeed = seed;
+    }
+
+    if (arg === '--preset') {
+      if (!demo) {
+        console.error('Error: --preset can only be used with the demo command');
+        process.exit(1);
+      }
+      const preset = commandArgs[++i] as DemoPreset;
+      if (!preset || !DEMO_PRESETS.includes(preset)) {
+        console.error(`Error: --preset must be one of: ${DEMO_PRESETS.join(', ')}`);
+        process.exit(1);
+      }
+      demoPreset = preset;
+    }
+
+    if (arg === '-r' || arg === '--refresh') {
+      const intervalStr = commandArgs[++i];
+      const interval = intervalStr ? parseInt(intervalStr, 10) : NaN;
+      if (isNaN(interval) || interval < 1000) {
+        console.error('Error: --refresh must be a number >= 1000');
+        process.exit(1);
+      }
+      refreshInterval = interval;
+    }
+  }
+
+  const launchOptions: TuiOptions = {
+    refreshInterval,
+    debug,
+    demo,
+  };
+  if (cliPlugins.length > 0) {
+    launchOptions.cliPlugins = cliPlugins;
+  }
+  if (demoSeed !== undefined) {
+    launchOptions.demoSeed = demoSeed;
+  }
+  if (demoPreset !== undefined) {
+    launchOptions.demoPreset = demoPreset;
+  }
+  await startTui(launchOptions);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/src/config/schema.test.ts

@@ -0,0 +1,166 @@
+import * as fs from 'fs/promises';
+import { afterEach, describe, expect, spyOn, test } from 'bun:test';
+
+import { DEFAULT_CONFIG, loadConfig } from './schema.ts';
+
+const readFileSpies: Array<ReturnType<typeof spyOn<typeof fs, 'readFile'>>> = [];
+
+function mockReadFileWithJson(config: unknown) {
+  const spy = spyOn(fs, 'readFile');
+  spy.mockResolvedValue(JSON.stringify(config));
+  readFileSpies.push(spy);
+}
+
+function mockReadFileWithRaw(content: string) {
+  const spy = spyOn(fs, 'readFile');
+  spy.mockResolvedValue(content);
+  readFileSpies.push(spy);
+}
+
+function mockReadFileError(error: Error) {
+  const spy = spyOn(fs, 'readFile');
+  spy.mockRejectedValue(error);
+  readFileSpies.push(spy);
+}
+
+afterEach(() => {
+  for (const spy of readFileSpies) {
+    spy.mockRestore();
+  }
+  readFileSpies.length = 0;
+});
+
+describe('DEFAULT_CONFIG', () => {
+  test('has expected top-level structure', () => {
+    expect(Object.keys(DEFAULT_CONFIG).sort()).toEqual(
+      [
+        'alerts',
+        'budgets',
+        'configVersion',
+        'display',
+        'notifications',
+        'pluginConfig',
+        'plugins',
+        'providers',
+        'refresh',
+      ].sort()
+    );
+  });
+
+  test('uses expected default values', () => {
+    expect(DEFAULT_CONFIG.refresh.intervalMs).toBe(60000);
+    expect(DEFAULT_CONFIG.display.defaultTimeWindow).toBe('1h');
+    expect(DEFAULT_CONFIG.display.theme).toBe('tokyo-night');
+    expect(DEFAULT_CONFIG.display.colorScheme).toBe('auto');
+
+    expect(DEFAULT_CONFIG.budgets.daily).toBeNull();
+    expect(DEFAULT_CONFIG.budgets.weekly).toBeNull();
+    expect(DEFAULT_CONFIG.budgets.monthly).toBeNull();
+
+    expect(DEFAULT_CONFIG.alerts.warningPercent).toBe(80);
+    expect(DEFAULT_CONFIG.alerts.criticalPercent).toBe(95);
+
+    expect(DEFAULT_CONFIG.plugins.local).toEqual([]);
+    expect(DEFAULT_CONFIG.plugins.npm).toEqual([]);
+    expect(DEFAULT_CONFIG.plugins.disabled).toEqual([]);
+  });
+});
+
+describe('loadConfig', () => {
+  test("returns defaults when config file doesn't exist", async () => {
+    mockReadFileError(new Error('ENOENT'));
+
+    const loaded = await loadConfig();
+
+    expect(loaded).toEqual(DEFAULT_CONFIG);
+  });
+
+  test('merges partial overrides with defaults', async () => {
+    mockReadFileWithJson({
+      refresh: { intervalMs: 15000 },
+      budgets: { daily: 25 },
+      alerts: { warningPercent: 70 },
+      plugins: { local: ['~/plugins/local-theme.ts'] },
+    });
+
+    const loaded = await loadConfig();
+
+    expect(loaded.refresh.intervalMs).toBe(15000);
+    expect(loaded.refresh.pauseAutoRefresh).toBe(DEFAULT_CONFIG.refresh.pauseAutoRefresh);
+    expect(loaded.budgets.daily).toBe(25);
+    expect(loaded.budgets.weekly).toBeNull();
+    expect(loaded.alerts.warningPercent).toBe(70);
+    expect(loaded.alerts.criticalPercent).toBe(DEFAULT_CONFIG.alerts.criticalPercent);
+    expect(loaded.plugins.local).toEqual(['~/plugins/local-theme.ts']);
+    expect(loaded.plugins.npm).toEqual([]);
+  });
+
+  test('applies nested display overrides without dropping sibling defaults', async () => {
+    mockReadFileWithJson({
+      display: { theme: 'dracula' },
+    });
+
+    const loaded = await loadConfig();
+
+    expect(loaded.display.theme).toBe('dracula');
+    expect(loaded.display.defaultTimeWindow).toBe(DEFAULT_CONFIG.display.defaultTimeWindow);
+    expect(loaded.display.colorScheme).toBe(DEFAULT_CONFIG.display.colorScheme);
+    expect(loaded.display.timeFormat).toBe(DEFAULT_CONFIG.display.timeFormat);
+  });
+
+  test('deep merges display.sparkline.style while preserving other sparkline defaults', async () => {
+    mockReadFileWithJson({
+      display: {
+        sparkline: {
+          style: 'block',
+        },
+      },
+    });
+
+    const loaded = await loadConfig();
+
+    expect(loaded.display.sparkline.style).toBe('block');
+    expect(loaded.display.sparkline.orientation).toBe(DEFAULT_CONFIG.display.sparkline.orientation);
+    expect(loaded.display.sparkline.showBaseline).toBe(DEFAULT_CONFIG.display.sparkline.showBaseline);
+  });
+
+  test('falls back to defaults for invalid JSON', async () => {
+    mockReadFileWithRaw(`{
+      // comments are not valid JSON
+      "display": { "theme": "dracula" }
+    }`);
+
+    const loaded = await loadConfig();
+    expect(loaded.display.theme).toBe(DEFAULT_CONFIG.display.theme);
+  });
+
+  test('parses valid JSON with budget overrides', async () => {
+    mockReadFileWithRaw(`{
+      "budgets": { "daily": 100 }
+    }`);
+
+    const loaded = await loadConfig();
+    expect(loaded.budgets.daily).toBe(100);
+  });
+
+  test('parses valid JSON with multiple overrides', async () => {
+    mockReadFileWithRaw(`{
+      "budgets": { "daily": 50, "weekly": 200 },
+      "alerts": { "warningPercent": 90 }
+    }`);
+
+    const loaded = await loadConfig();
+    expect(loaded.budgets.daily).toBe(50);
+    expect(loaded.budgets.weekly).toBe(200);
+    expect(loaded.alerts.warningPercent).toBe(90);
+  });
+
+  test('does not strip // inside string values', async () => {
+    mockReadFileWithRaw(`{
+      "plugins": { "local": ["~/my-plugin // v2"] }
+    }`);
+
+    const loaded = await loadConfig();
+    expect(loaded.plugins.local).toEqual(['~/my-plugin // v2']);
+  });
+});

package/src/config/schema.ts

@@ -0,0 +1,165 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { PATHS } from '@/storage/paths.ts';
+
+export type TimeWindow = '5m' | '15m' | '1h' | '24h' | '7d' | '30d' | 'all';
+
+export interface BudgetConfig {
+  daily: number | null;
+  weekly: number | null;
+  monthly: number | null;
+  currency: 'USD' | 'EUR' | 'GBP';
+}
+
+export interface AlertThresholds {
+  warningPercent: number;
+  criticalPercent: number;
+}
+
+export type SparklineStyle = 'braille' | 'block';
+export type SparklineOrientation = 'up' | 'down';
+
+export interface SparklineConfig {
+  style: SparklineStyle;
+  orientation: SparklineOrientation;
+  showBaseline: boolean;
+}
+
+export interface PluginsConfig {
+  local: string[];
+  npm: string[];
+  disabled: string[];
+}
+
+export interface AppConfig {
+  configVersion: number;
+  refresh: {
+    intervalMs: number;
+    pauseAutoRefresh: boolean;
+    staleThresholdMs: number;
+  };
+  display: {
+    defaultTimeWindow: TimeWindow;
+    sidebarCollapsed: boolean;
+    timeFormat: '12h' | '24h';
+    numberFormat: 'full' | 'compact';
+    sparkline: SparklineConfig;
+    theme: string;
+    colorScheme: 'auto' | 'light' | 'dark';
+  };
+  notifications: {
+    toastsEnabled: boolean;
+    soundEnabled: boolean;
+  };
+  budgets: BudgetConfig;
+  alerts: AlertThresholds;
+  providers: {
+    hideUnconfigured: boolean;
+  };
+  plugins: PluginsConfig;
+  pluginConfig: Record<string, Record<string, unknown>>;
+}
+
+export const DEFAULT_CONFIG: AppConfig = {
+  configVersion: 1,
+  refresh: {
+    intervalMs: 60000,
+    pauseAutoRefresh: false,
+    staleThresholdMs: 300000,
+  },
+   display: {
+     defaultTimeWindow: '1h',
+     sidebarCollapsed: false,
+      timeFormat: '24h',
+     numberFormat: 'compact',
+     sparkline: {
+       style: 'braille',
+       orientation: 'up',
+       showBaseline: true,
+     },
+      theme: 'tokyo-night',
+      colorScheme: 'auto',
+    },
+  notifications: {
+    toastsEnabled: true,
+    soundEnabled: false,
+  },
+  budgets: {
+    daily: null,
+    weekly: null,
+    monthly: null,
+    currency: 'USD',
+  },
+  alerts: {
+    warningPercent: 80,
+    criticalPercent: 95,
+  },
+  providers: {
+    hideUnconfigured: false,
+  },
+  plugins: {
+    local: [],
+    npm: [],
+    disabled: [],
+  },
+  pluginConfig: {},
+};
+
+function deepMerge(target: AppConfig, source: Partial<AppConfig>): AppConfig {
+  return {
+    configVersion: source.configVersion ?? target.configVersion,
+    refresh: {
+      ...target.refresh,
+      ...(source.refresh ?? {}),
+    },
+    display: {
+      ...target.display,
+      ...(source.display ?? {}),
+      sparkline: {
+        ...target.display.sparkline,
+        ...(source.display?.sparkline ?? {}),
+      },
+    },
+    notifications: {
+      ...target.notifications,
+      ...(source.notifications ?? {}),
+    },
+    budgets: {
+      ...target.budgets,
+      ...(source.budgets ?? {}),
+    },
+    alerts: {
+      ...target.alerts,
+      ...(source.alerts ?? {}),
+    },
+    providers: {
+      ...target.providers,
+      ...(source.providers ?? {}),
+    },
+    plugins: {
+      ...target.plugins,
+      ...(source.plugins ?? {}),
+    },
+    pluginConfig: {
+      ...target.pluginConfig,
+      ...(source.pluginConfig ?? {}),
+    },
+  };
+}
+
+export async function loadConfig(): Promise<AppConfig> {
+  try {
+    const content = await fs.readFile(PATHS.config.file, 'utf-8');
+    const loaded = JSON.parse(content) as Partial<AppConfig>;
+    return deepMerge(DEFAULT_CONFIG, loaded);
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+export async function saveConfig(config: AppConfig): Promise<void> {
+  await fs.mkdir(path.dirname(PATHS.config.file), { recursive: true });
+  const tempFile = PATHS.config.file + '.tmp';
+  await fs.writeFile(tempFile, JSON.stringify(config, null, 2), 'utf-8');
+  await fs.rename(tempFile, PATHS.config.file);
+}