Merge pull request #250 from lbedner/changelog

Changelog

Author: lbedner

CHANGELOG.md

@@ -5,6 +5,182 @@
   The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
   and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+  ## [0.2.0] - 2025-11-05
+
+  ### 🌟 Major Features
+
+  #### Dynamic Component Management
+  - **NEW**: `aegis add` command - Add components to existing projects post-generation
+  - **NEW**: `aegis remove` command - Remove components from existing projects
+  - **NEW**: `aegis update` command - Update projects with latest template changes
+  - **NEW**: Copier template engine support with version tracking
+  - Projects can now evolve after creation (Copier-based projects only)
+  - Intelligent dependency resolution (e.g., worker auto-adds Redis, auth auto-adds database)
+  - File-level component management without full project regeneration
+  - Automatic dependency installation and code formatting after changes
+
+  #### Services Architecture (Business Logic Layer)
+  - **NEW**: Authentication Service (`--services auth`)
+    - JWT-based authentication with access and refresh tokens
+    - User registration, login, and profile management
+    - Password hashing with bcrypt
+    - Protected API routes with FastAPI dependency injection
+    - Database migrations via Alembic
+    - User management CLI commands (`create-user`, `list-users`, `delete-user`, etc.)
+    - Comprehensive test suite with 52+ authentication tests
+    - Automatically includes database component
+
+  - **NEW**: AI Service (`--services ai`)
+    - PydanticAI integration for type-safe AI interactions
+    - Multi-provider support (OpenAI, Anthropic, Gemini, Groq)
+    - Streaming chat responses with markdown rendering
+    - Conversation memory and persistence to database
+    - Interactive CLI chat interface with rich formatting
+    - Health monitoring for AI provider connectivity
+    - Environment variable configuration
+    - API endpoints for chat operations
+
+  #### Enhanced Scheduler Component
+  - **NEW**: SQLite-backed persistence option (`--scheduler-backend sqlite`)
+  - Automatic database backup jobs when scheduler + database combined
+  - Task monitoring API endpoints
+  - Interactive CLI for viewing and managing scheduled tasks
+  - Enhanced health checks with task execution tracking
+  - Job statistics and history
+
+  ### ✨ Added
+
+  #### CLI Commands
+  - `aegis add` - Add components to existing projects
+  - `aegis remove` - Remove components from projects
+  - `aegis update` - Update projects with latest templates
+  - `aegis services` - List available services
+  - `aegis components` - Show detailed component information
+  - `aegis version` - Display CLI version
+  - Template engine selection via `--engine` flag (copier or cookiecutter)
+  - Interactive service selection during project creation
+  - Component backend selection (e.g., `--scheduler-backend sqlite`)
+
+  #### Developer Experience
+  - **uvx support** - Run without installation (`uvx aegis-stack init my-project`)
+  - Enhanced dashboard with component and service health cards:
+    - Auth service card (user count, health status, database connection)
+    - AI service card (provider status, model info, conversation stats)
+    - Scheduler card (job stats, task history, next run times)
+    - Worker card (queue stats, job history, worker health)
+    - FastAPI card (route inspection, middleware detection)
+    - Database card (table stats, connection pool info)
+    - Redis card (memory usage, connection statistics)
+  - Load testing CLI with visual progress indicators
+  - FastAPI middleware and route inspection utilities
+  - Rich terminal formatting for AI chat (markdown, code blocks, tables)
+  - Comprehensive CLI tools for component management
+
+  #### Testing & Quality
+  - Migrated from mypy to `ty` for faster type checking
+  - Extensive test coverage for auth service (52+ tests)
+  - Extensive test coverage for AI service
+  - Template parity tests (Cookiecutter vs Copier output validation)
+  - Component addition/removal integration tests
+  - Auth integration tests (registration, login, JWT flows, protected routes)
+  - AI conversation persistence tests
+  - Middleware and route inspection tests
+  - Extended test matrix for component combinations
+  - Clean validation workflow for template testing
+
+  #### Documentation
+  - Complete auth service documentation (API reference, CLI commands, integration guide, examples)
+  - Complete AI service documentation (provider setup, API reference, CLI commands, integration)
+  - Services architecture guide and dashboard integration docs
+  - "Evolving Your Stack" guide - post-generation component management philosophy
+  - Scheduler persistence and CLI documentation
+  - Enhanced installation guide (uvx, uv tool, pip methods)
+  - Integration patterns documentation
+  - Component-specific CLAUDE.md files for AI development context
+  - Release process documentation with PyPI/TestPyPI workflow
+
+  #### Infrastructure
+  - GitHub Actions workflow for automated PyPI releases
+  - TestPyPI pre-flight testing workflow
+  - PyPI Trusted Publishing (OIDC, no API tokens)
+  - Template versioning and compatibility tracking
+  - Copier template infrastructure with `.copier-answers.yml`
+  - Post-generation task system refactored
+  - Component file management utilities
+  - Service dependency resolver
+  - Manual updater for Cookiecutter-based projects
+
+  ### 🔧 Changed
+
+  - **Default template engine** is now Copier (Cookiecutter still fully supported via `--engine cookiecutter`)
+  - Type checker migrated from mypy to `ty` for improved performance
+  - Enhanced dashboard UI with modern card-based architecture
+  - Improved component dependency resolution logic
+  - Better error messages with actionable suggestions
+  - Scheduler component refactored with service layer separation
+  - Worker health check registration improved
+  - Database health checks enhanced with connection pool monitoring
+  - Restructured CLI command organization into separate modules
+  - Dashboard rendering optimizations
+
+  ### 🐛 Fixed
+
+  - Dashboard rendering bugs with component state management
+  - Worker type annotations and kwargs handling
+  - arq worker info retrieval issues
+  - Scheduler component integration edge cases
+  - Database card rendering and refactoring issues
+  - Redis component card state updates
+  - FastAPI middleware detection for edge cases
+  - Template generation with various component combinations
+  - Health check caching race conditions
+
+  ### 🔐 Security
+
+  - JWT-based authentication with secure token handling
+  - Password hashing with bcrypt (cost factor 12)
+  - Protected API routes with dependency injection patterns
+  - Secure user model implementation
+  - API key handling for AI providers
+  - Environment variable-based secrets management
+
+  ### ⚡ Performance
+
+  - Faster type checking with `ty` replacing mypy
+  - Optimized component dependency resolution
+  - Improved dashboard rendering performance
+  - Enhanced health check caching strategies
+  - Reduced template generation time
+
+  ### 📊 Statistics
+
+  - 62 pull requests merged since v0.1.0
+  - 456 files changed (72,387 insertions, 4,590 deletions)
+  - 8 new CLI commands
+  - 2 new services (auth, AI)
+  - 13+ new documentation files
+  - 100+ new test files
+  - 10 weeks of development (Aug 28 - Nov 5, 2025)
+
+  ### 🎯 Highlights for Users
+
+  1. **Your stack can now evolve** - Add/remove components after project creation
+  2. **Authentication ready** - Production JWT auth with one command (`--services auth`)
+  3. **AI-ready** - Multi-provider AI integration built-in (`--services ai`)
+  4. **No installation needed** - Run with `uvx aegis-stack init my-project`
+  5. **Scheduler persistence** - SQLite-backed job storage for reliability
+  6. **Enhanced DX** - Rich CLI tools, better dashboard, comprehensive health monitoring
+
+  ### 📝 Notes
+
+  - Copier is now the default template engine, enabling `aegis add/remove/update` commands
+  - Both Copier and Cookiecutter templates are fully supported
+  - Auth service automatically includes Alembic for database migrations
+  - AI service supports OpenAI, Anthropic, Gemini, and Groq providers
+  - Scheduler persistence requires database component
+  - Template version compatibility tracked in `.copier-answers.yml` (Copier projects)
+  - Worker component still requires explicit Redis component specification
+
   ## [0.1.0] - 2025-08-27
 
   ### Added
@@ -36,4 +212,5 @@
   - Worker (arq/Redis) - Optional
   - Scheduler (APScheduler) - Optional
 
+  [0.2.0]: https://github.com/lbedner/aegis-stack/compare/v0.1.0...v0.2.0
   [0.1.0]: https://github.com/lbedner/aegis-stack/releases/tag/v0.1.0

docs/cli-reference.md

@@ -384,6 +384,130 @@ aegis remove --interactive
 
 ---
 
+## aegis update
+
+Update an existing Copier-based project to the latest template version.
+
+**Usage:**
+```bash
+aegis update [OPTIONS]
+```
+
+**Options:**
+
+- `--project-path PATH` - Path to project to update (default: current directory)
+- `--version TEXT` - Update to specific template version (default: latest)
+- `--force, -f` - Accept all template changes automatically (skip conflict resolution)
+- `--yes, -y` - Skip confirmation prompt
+- `--dry-run` - Preview changes without applying them
+
+**Examples:**
+```bash
+# Update current project to latest template
+aegis update
+
+# Update specific project
+aegis update --project-path ../my-project
+
+# Update to specific template version
+aegis update --version 0.2.0
+
+# Preview changes without applying
+aegis update --dry-run
+
+# Auto-accept all updates
+aegis update --force --yes
+```
+
+**How It Works:**
+
+1. Validates project was generated with Copier (required for updates)
+2. Checks current template version from `.copier-answers.yml`
+3. Fetches latest template version (or specified version)
+4. Compares current files with template updates
+5. Shows diff of changes to be applied
+6. Prompts for conflict resolution (which version to keep)
+7. Applies updates and creates backup files for conflicts
+8. Runs `uv sync` to update dependencies
+9. Runs `make fix` to format updated code
+
+**What Gets Updated:**
+
+- ✅ Template infrastructure files (configuration, base components)
+- ✅ Shared files (docker-compose.yml, pyproject.toml, Makefile)
+- ✅ Component implementations (if you haven't customized them)
+- ✅ Test infrastructure
+- ✅ Documentation templates
+
+**What's Preserved:**
+
+- ✅ Your custom business logic
+- ✅ Your environment variables (.env)
+- ✅ Your database migrations
+- ✅ Your custom models and services
+- ✅ Files you've modified (marked as conflicts for manual resolution)
+
+**Conflict Resolution:**
+
+When the template has changed a file you've also modified:
+
+```bash
+# Option 1: Keep your version
+[1] Keep my changes
+
+# Option 2: Use template version
+[2] Use template version
+
+# Option 3: View diff
+[3] Show diff
+
+# Option 4: Manual merge
+[4] I'll merge manually
+```
+
+Conflict files are backed up to:
+- Original: `app/components/backend/api/router.py.backup-TIMESTAMP`
+- Template: `app/components/backend/api/router.py.copier-TIMESTAMP`
+
+**Important Notes:**
+
+- **Cookiecutter projects cannot use this command** - Only Copier-based projects support updates
+- **Always commit before updating**: `git add . && git commit -m "Pre-update checkpoint"`
+- **Review changes carefully**: Don't blindly accept all updates
+- **Test after updating**: Run `make check` to verify everything works
+- **Backup files are created**: Check `.backup-*` and `.copier-*` files after conflicts
+- **Major version updates**: May require manual intervention and migration steps
+
+**Troubleshooting:**
+
+```bash
+# Error: "Not a Copier project"
+# Solution: This project was created with Cookiecutter
+# See docs/upgrading.md for migration options
+
+# Error: "Uncommitted changes"
+# Solution: Commit your changes first
+git add . && git commit -m "Save current work"
+
+# Many conflicts after update
+# Solution: Review .copier-answers.yml to see what changed
+# Use --dry-run first to preview changes
+
+# Update breaks tests
+# Solution: Roll back and review changes
+git reset --hard HEAD~1  # Undo update
+aegis update --dry-run    # Preview what changed
+```
+
+**See Also:**
+
+- [Upgrading Guide](upgrading.md) - Comprehensive upgrade documentation
+- [Versioning](versioning.md) - Understanding version compatibility
+- `aegis add` - Add new components to existing projects
+- `aegis remove` - Remove components from projects
+
+---
+
 ## Development Workflow
 
 After creating a project: