feat: TTL eviction, disk guard, debug logging, and extended cache API

[chanphiromsok]

Summary

• TTL-based cache eviction — files older than cacheTTLDays (default 2) are deleted on server start; fits daily-feed use cases where yesterday's segments are always stale
• Disk space guard — if free disk drops below 500 MB, oldest files are evicted automatically during prune()
• JS-controlled debug logging — pass debugLogging: true to startServer() to enable [HLSCache] stdout logs; gated by #if DEBUG so the flag is a compile-time no-op in release builds
• Extended API — stopServer(), isRunning, invalidateUrl(url), getCacheStats() (fills gaps from CLAUDE.md TODO list)
• FLOW_GUIDE.md — full technical reference: request lifecycle, eviction flow, design pattern map, API reference, debug log table

New API

// Lifecycle
await stopServer()
isServerRunning()  // synchronous boolean

// Cache management
await invalidateUrl("https://cdn.example.com/video.m3u8")  // single-URL eviction
const stats = await getCacheStats()
// → { fileCount, totalSizeBytes, freeDiskSpaceBytes }

// startServer — new optional params
await startServer(9000, 1_073_741_824, true, 2, true)
//                port  maxCacheSize  head ttl debug

Design patterns applied

Pattern	Where
Cache-Aside	DataSource.start()
Strategy	prune() — TTL / disk guard / LRU passes
Bulkhead	DispatchSemaphore(value: 32) in NetworkDownloader
Singleton	CacheLogger.shared, NetworkDownloader.shared
Delegate chain	ProxyConnectionDelegate → DataSourceDelegate → NetworkDownloaderDelegate

Test plan

• startServer() with debugLogging: true — verify [HLSCache] lines appear in Xcode console
• startServer() with release build — verify no log output and no binary strings
• Play a video, call getCacheStats() — verify fileCount > 0 and totalSizeBytes > 0
• Call invalidateUrl(url) on a cached URL, replay — verify MISS log on next request
• Call stopServer(), verify isServerRunning() returns false
• Start server again after stopServer() — verify playback resumes normally
• Set cacheTTLDays: 0.00001, restart — verify all old files pruned on next startServer()
• Run yarn nitrogen to verify bridge regenerates cleanly with new interface

https://claude.ai/code/session_016aKiYNJycuCWkNYogZNqsY