# Changelog

All notable changes to LLMHosts will be documented in this file.

## [0.5.0] - 2026-02-28

### Added
- **TrustShield Security Platform**: PromptGuard injection detection, HMAC-chain audit ledger, adaptive rate limiting, mTLS mesh, transparency dashboard
- **Token AI Assistant**: Conversational fleet orchestrator with multi-agent routing (research via Sonnet, reasoning via R1, fleet management via Flash), cost analytics, proactive alerts, email notifications
- **Zero-Config Auto-Discovery**: Automatic GPU/engine detection, model inventory, VRAM-aware provisioning, savings calculator
- **Device Code Auth (RFC 8628)**: CLI-to-dashboard authentication flow for headless devices
- **Device Registration API**: Register, heartbeat, and manage fleet devices
- **`llmhosts up` Command**: 5-phase pipeline (assess → provision → start → connect → run) for one-command startup
- **Hive Mode (Phase 3)**: GPU pooling across LAN nodes via Headscale mesh
- **Three-tier Hybrid Router**: Rule-based + kNN (Tier 1), ModernBERT classifier (Tier 2), Qwen-0.5B (Tier 3) with IslandRun privacy routing
- **Three-tier Semantic Cache**: Exact hash → entity namespace → vCache (ICLR 2026)
- **OpenAI + Anthropic Compatible Proxy**: Full `/v1/chat/completions` and `/v1/messages` API compatibility
- **BYOK Encrypted Key Storage**: Fernet-encrypted API key management for cloud providers
- **Comprehensive Monitoring Stack**: Prometheus metrics export, Grafana dashboards, Loki log aggregation
- **Self-Healing CI Pipeline**: 17-check verification gate with auto-fix for lint/format issues
- **K8s Readiness**: `/ready` endpoint, Docker production images, Helm-ready architecture
- **Web Dashboard**: Next.js 16 with Auth.js, Stripe billing, API key management, usage analytics
- **Conversion Optimization**: Pricing anchor, testimonials, checkout friction reduction, onboarding flow, dunning/retention
- **WCAG AA Compliance**: Accessible color tokens, keyboard navigation, screen reader support

### Changed
- Brand rename: `llmhost` → `llmhosts` across entire codebase
- Config directory: `~/.llmhosts/`, env prefix: `LLMHOSTS_*`

### Fixed
- Fresh-server deployment bugs (volume mount, release workflow, stale env vars)
- All 18 ruff warnings resolved to zero
- Prisma client generation in Docker builds

## [0.2.0] - 2026-02-17

### Added — Authentication & Security
- Email verification flow with time-limited tokens (24-hour expiry)
- Email verification route (`/auth/verify-email?token=...&email=...`)
- Password reset functionality with email + token validation
- Forgot password route (`/auth/forgot-password`)
- Reset password route (`/auth/reset-password`)
- Case-insensitive email matching for all auth flows
- Prevention of login for unverified accounts
- One-time token consumption (tokens deleted after use)
- Email enumeration protection (same response for non-existent users)

### Added — Data Visualization (Recharts Integration)
- **Overview Page Enhanced** with 3 interactive charts:
  - Monthly Spending Trend: Line chart showing last 6 months by provider
  - Provider Breakdown: Pie chart with all-time spending distribution
  - Savings Projection: Area chart comparing actual vs. projected costs (35% savings estimate)
- Responsive chart containers (300px height)
- Dark theme styling for all charts (gray-800 backgrounds, gray-300 text)
- Custom tooltips with currency formatting
- Provider color coding (OpenAI: emerald, Anthropic: violet, etc.)
- Empty state handling for charts when no data exists

### Added — Testing Infrastructure
- **Vitest Integration** for frontend API route testing
  - 20 integration tests for auth routes (register, forgot-password, reset-password)
  - Full AAA pattern (Arrange-Act-Assert) with detailed comments
  - happy-dom environment for fast DOM testing (2-3x faster than jsdom)
  - Database mocking with vi.mock for isolated unit tests
  - bcryptjs and crypto mocking for deterministic test behavior
  - 100% pass rate in ~1.3s
  - Test coverage: `npm test`, `npm run test:ui`, `npm run test:coverage`

- **Playwright E2E Test Suite** for critical user journeys
  - 29 comprehensive end-to-end tests across 6 journeys
  - ~146 screenshots captured for visual regression testing
  - Console error tracking (0 tolerance) on every test
  - Database state verification with Prisma client
  - Test Journeys:
    1. Registration → Email Verification → Login (2 tests)
    2. Stripe Checkout → Upgrade to Pro → Billing Portal (4 tests)
    3. CRUD Cost Entries with Filters (5 tests)
    4. CRUD API Keys with Plan Limits (6 tests)
    5. Password Reset Full Flow (5 tests)
    6. Dashboard Navigation + Data Accuracy (7 tests)
  - Test helpers: createTestUser, loginUser, takeScreenshot, setupConsoleErrorTracking
  - Automatic Next.js dev server startup before tests
  - Retries: 2 in CI, 0 locally
  - Video recording on failure

- **CLI E2E Test Script** (`tests/e2e/cli_install.sh`)
  - 11 automated tests for CLI installation and core commands
  - Virtual environment creation and clean-up
  - Tests: version check, help command, setup wizard, doctor checks, key management, health endpoint, models endpoint
  - ASGI transport testing for API endpoints (no server needed)
  - Comprehensive logging to `/tmp/cli_e2e_test_*.log`
  - Exit code validation and output verification

### Changed
- Overview page now displays real data from `/api/costs` instead of placeholders
- Dashboard redesigned with charts in responsive grid layout (1-col mobile, 2-col desktop)
- Cost entry table limited to 5 most recent entries on Overview
- package.json: Added Vitest, Playwright, and testing utilities

### Fixed
- Email verification prevented immediate account access (security improvement)
- Password reset tokens now expire correctly (1 hour)
- Database cleanup in test suite prevents orphaned records

### Security
- Email verification tokens use crypto.randomBytes(32) for unpredictability
- Password reset tokens auto-delete on successful password change
- Expired tokens trigger cleanup (delete from database)
- Token validation includes email matching to prevent token reuse

### Infrastructure
- Vitest config with React plugin, happy-dom, and path aliases
- Playwright config with Chromium browser, automatic screenshots, video on failure
- Test setup mocks Next.js navigation (useRouter, useSearchParams, usePathname)
- Environment variables for testing: DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL

### Documentation
- Added comprehensive E2E test README (`frontend/e2e/README.md`)
- Test suite coverage summary table
- Testing section in frontend README with commands
- AAA pattern examples for contributors

## [0.1.0] - 2026-02-17

### Added — LLMHost CLI & Proxy (Backend)
- OpenAI-compatible proxy (`POST /v1/chat/completions`, `GET /v1/models`)
- Anthropic-compatible proxy (`POST /v1/messages`)
- Ollama auto-discovery and hardware detection
- BYOK cloud key management (encrypted at rest with Fernet)
- Three-tier hybrid router:
  - Tier 0: Rule-based routing with model aliases and cost optimization
  - Tier 1: kNN embedding router with FAISS + MiniLM [smart tier]
  - Tier 2: ModernBERT classification router with heuristic fallback [smart tier]
- Three-tier verified cache:
  - Tier 0: Exact hash cache with SHA-256 + SQLite/WAL
  - Tier 1: Entity namespace cache with domain-aware bucketing [smart tier]
  - Tier 2: vCache verified semantic cache with adaptive thresholds [smart tier]
- Unified cache manager with namespace/prefix support
- Cost tracking with SQLite persistence and savings reports
- Audit logging for all requests and routing decisions
- Real-time metrics with Prometheus/JSON/CSV export
- Multi-turn conversation context tracking
- Backend health monitoring with circuit breaker
- Fallback chain (local Ollama → cloud API)
- Latency-aware routing with rolling averages
- GPU-less smart routing for CPU-only users
- LiteLLM backend integration for 100+ cloud providers
- TUI dashboard (Textual) with real-time widgets
- CLI commands:
  - `llmhosts serve` — Full orchestration server
  - `llmhosts doctor` — Diagnostic checks (10 concurrent)
  - `llmhosts keys add/list/remove/validate` — BYOK key management
  - `llmhosts suggest-models` — Hardware-aware model suggestions
  - `llmhosts setup` — Interactive onboarding wizard
  - `llmhosts tunnel start/status/stop` — Tailscale/Cloudflare auto-detect
- Cloud-first hybrid startup (cloud immediate, local background)
- Tiered pip install: `llmhost` (~50MB), `llmhost[smart]` (~150MB), `llmhost[full]` (~2GB)
- TOML-based configuration with env var overrides
- 301 integration tests (all passing)

### Added — LLMHosts.com SaaS Platform (Frontend)
- Full Next.js 16 App Router dashboard at https://llmhosts.com
- Authentication (Auth.js v5) with email + password
- User registration with bcrypt password hashing
- Session management with JWT + database persistence
- Landing page with pricing, features, and legal footer
- Dashboard with 7 functional pages:
  - Overview — Real-time spending summary, provider breakdown, recent entries
  - Spending — Filterable cost table, sortable columns, delete entries
  - Add Entry — Create cost entries with provider/category/period/notes
  - Projections — Day-of-month pro-rating, 12-month forward forecast, confidence scoring
  - Achievements — Gamified savings milestones (real data for savings, placeholders for proxy metrics)
  - API Keys — CRUD operations with plan-based limits (free: 2, pro: 10, team: 50, enterprise: 100)
  - Settings — User profile management, plan display, Stripe billing integration
- Stripe integration (test mode):
  - Checkout session for plan upgrades
  - Billing portal for subscription management
  - Webhook handler for plan sync (checkout complete, subscription updated/deleted, payment failed)
  - Products: Pro ($29/mo), Team ($99/mo), Enterprise ($299/mo)
- Plan-based rate limiting and feature gating
- Cost entry tracking with SQLite + Prisma ORM
- API routes for auth, costs, API keys, user profile, Stripe checkout/portal
- Responsive UI with TailwindCSS 4, shadcn/ui components
- Dark theme with indigo accent
- OpenGraph and Twitter Card metadata
- SEO-optimized pages (terms, privacy)

### Infrastructure
- Docker Compose production deployment (Traefik + Next.js + Python backend)
- Traefik reverse proxy with automatic Let's Encrypt HTTPS
- PostgreSQL-compatible (SQLite for dev, Postgres for scale)
- Prisma migrations for schema versioning
- Docker healthchecks for both frontend and backend containers
- External proxy mode for integration with existing Traefik/Pangolin stacks
- Ruff linting (zero errors)
- pytest + pytest-asyncio test framework (301 tests passing)
- ASGI transport testing (no real server needed)

### Packages
- PyPI (TestPyPI): Published at https://test.pypi.org/project/llmhost/0.1.0/
- Docker Hub: `llmhostscom-frontend:latest` and `llmhost:latest`

### Changed
- Project renamed from LLMHost.com → LLMHosts.com (plural) across all branding
- Pricing adjusted to reflect value: Pro $29/mo (was $19), Team $99/mo (was $49), Enterprise $299/mo (was $50)
- Router confidence thresholds tuned based on real-world testing
- Cache manager now supports namespace prefixes for multi-tenant isolation
- Dashboard pages migrated from demo data to live API-backed data

### Fixed
- Traefik routing conflict: `/api/keys` was being routed to Python backend instead of Next.js frontend
- Provider value alignment: Frontend Select dropdowns now use lowercase values matching API validation
- Disabled input styling now properly shows `cursor-not-allowed` state
- Sign out flow now uses NextAuth's `signOut()` instead of `window.location.href`
- Projections page now uses day-of-month pro-rating instead of hard-coded mock data

### Security
- All passwords hashed with bcrypt (cost factor 12)
- API keys use `lh_sk_` prefix with cryptographically random generation
- Stripe webhook signature verification enforced
- Auth enforcement on all `/api/*` routes requiring user context
- Soft-delete pattern for API keys (revoke instead of hard delete)
- Session tokens stored with httpOnly, secure, sameSite flags

### Known Limitations
- Achievements page: Streak, cache hit rate, and routing badges show 0% until proxy metrics integration (Phase 3)
- Multi-region: Single region deployment only (US-East)
- Horizontal scaling: Single instance only (Kubernetes support in Phase 3)
