cc-api-statusline 0.1.3 → 0.1.9

package/README.md

@@ -9,10 +9,11 @@ A high-performance TUI statusline tool that polls API usage data from Claude API
 - ⚡ **Fast piped mode** — <25ms warm cache, <100ms p95
 - 🎨 **Highly configurable** — Layouts, colors, bar styles, display modes
 - 🔌 **Provider autodetection** — Works with sub2api, claude-relay-service, custom providers
-- 💾 **Smart caching** — Disk cache with atomic writes, TTL validation
+- 💾 **Smart caching** — Disk cache with atomic writes, TTL validation, automatic garbage collection
 - 🎯 **Claude Code integration** — Auto-setup with `--install` command
 - 📊 **Multiple components** — Daily/weekly/monthly quotas, balance, tokens, rate limits
 - 🐛 **Debug logging** — Detailed execution logs for troubleshooting
+- 🔒 **Reliability** — No stale data display, race-condition-free writes, auto cache cleanup
 
 ## Installation
 
@@ -418,9 +419,16 @@ Cache validation:
 - Version match
 - Token hash match
 
+Cache garbage collection:
+- Automatic cleanup after successful cache writes
+- Deletes cache files older than 7 days
+- Maintains maximum of 20 cache files (deletes oldest)
+- Removes orphaned temporary files older than 1 hour
+- Best-effort operation (never blocks or throws)
+
 Exit code behavior:
-- Returns `0` when stale cache is shown with error indicators (output is still useful)
-- Returns `1` only when no data can be shown (prevents confusing `[Exit: 1]` in widgets)
+- Returns `0` for all error states (stale data is never shown, only error messages)
+- Ensures clean widget display without `[Exit: 1]` indicators
 
 ## Troubleshooting
 
@@ -521,9 +529,16 @@ bun run check
 
 ```
 ┌─────────────┐
-│   main.ts   │ ← Entry point, CLI orchestration, install/uninstall
+│   main.ts   │ ← Thin router: parse args → dispatch
 └──────┬──────┘
        │
+┌──────▼────────┐
+│    src/cli/   │ ← Argument parsing, install/uninstall, piped-mode
+│  - args.ts    │
+│  - commands.ts│
+│  - piped-mode │
+└──────┬────────┘
+       │
        ├──────────────────────────────────────┐
        │                                      │
 ┌──────▼────────┐                   ┌────────▼────────┐
@@ -532,22 +547,28 @@ bun run check
 │  - cache      │                   │  - relay        │
 │  - config     │                   │  - custom       │
 │  - settings   │ ← settings.json   │  - autodetect   │
-│  - logger     │ ← debug logging   └────────┬────────┘
+│  - logger     │ ← debug logging   │  - quota-window │
+│  - atomic-write│← atomic writes   │  - custom-mapping│
+│  - cache-gc   │ ← auto cleanup    │                 │
+│  - ensure-dir │← dir creation     └────────┬────────┘
 └──────┬────────┘                            │
        │                                      │
        ├──────────────────────────────────────┘
        │
 ┌──────▼────────┐
+│  src/core/    │
 │ execute-cycle │ ← Unified execution (Path A/B/C/D)
+│  constants.ts │ ← Shared constants
 └──────┬────────┘
        │
 ┌──────▼────────┐
 │   renderer/   │
-│  - component  │ ← Per-component rendering
+│  - component  │ ← Per-component rendering (RenderContext)
 │  - bar        │ ← Progress bars
 │  - colors     │ ← ANSI color system
 │  - countdown  │ ← Time-to-reset
 │  - error      │ ← Error states
+│  - transition │ ← Transition state detection
 │  - icons      │ ← Nerd-font glyphs
 │  - truncate   │ ← Terminal width
 │  - index      │ ← Main pipeline
@@ -556,11 +577,12 @@ bun run check
 
 ## Testing
 
-- **356 tests** across **21 test files**
-- Unit tests for all services and renderers
+- **550 tests** across **34 test files**
+- Unit tests for all services, renderers, and shared utilities
 - Core execution path tests (A/B/C/D)
 - E2E smoke tests with isolated environments
 - Performance tests (p95 < 600ms verification)
+- Cache garbage collection tests
 - CI/CD via GitHub Actions
 
 Run: `bun run check`
@@ -576,4 +598,4 @@ MIT
 - [TUI Style Spec](docs/spec-tui-style.md)
 - [API Polling Spec](docs/spec-api-polling.md)
 - [Custom Providers Spec](docs/spec-custom-providers.md)
-- [AGENTS.md](AGENTS.md) - Development handoff guide
+- [AGENTS.md](AGENTS.md) - Development handoff guide