aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/startup/component_health.py.j2

@@ -0,0 +1,418 @@
+"""
+Component health registration startup hook.
+
+Automatically detects available components and registers their health checks
+with the system health service using Python's import system.
+"""
+
+from app.core.log import logger
+from app.services.system.health import register_health_check
+from app.services.system.models import ComponentStatus, ComponentStatusType
+from app.components.backend.main import get_configured_app
+from app.services.backend.route_inspector import get_fastapi_route_metadata, RouteMetadata
+from app.services.backend.middleware_inspector import get_fastapi_middleware_metadata, MiddlewareMetadata
+
+# Cache for route metadata - initialized once at startup
+_cached_route_metadata: RouteMetadata | None = None
+# Cache for middleware metadata - initialized once at startup  
+_cached_middleware_metadata: MiddlewareMetadata | None = None
+
+
+def _initialize_route_metadata_cache() -> None:
+    """
+    Initialize route and middleware metadata caches using the configured FastAPI app.
+    Called once during startup to avoid recreating the app on every health check.
+    """
+    global _cached_route_metadata, _cached_middleware_metadata
+    
+    if _cached_route_metadata is not None and _cached_middleware_metadata is not None:
+        return  # Already initialized
+    
+    try:
+        app = get_configured_app()
+        if app is not None:
+            # Cache route metadata
+            if _cached_route_metadata is None:
+                _cached_route_metadata = get_fastapi_route_metadata(app)
+                logger.info(
+                    f"Route metadata cached: "
+                    f"{_cached_route_metadata.total_routes} routes, "
+                    f"{_cached_route_metadata.total_endpoints} endpoints"
+                )
+            
+            # Cache middleware metadata
+            if _cached_middleware_metadata is None:
+                _cached_middleware_metadata = get_fastapi_middleware_metadata(app)
+                logger.info(
+                    f"Middleware metadata cached: "
+                    f"{_cached_middleware_metadata.total_middleware} middleware, "
+                    f"{_cached_middleware_metadata.security_count} security layers"
+                )
+        else:
+            logger.warning(
+                "FastAPI app not yet configured - route and middleware metadata "
+                "cache will be initialized later"
+            )
+    except Exception as e:
+        logger.error(f"Failed to initialize route and middleware metadata cache: {e}")
+
+
+async def _backend_component_health() -> ComponentStatus:
+    """
+    FastAPI backend health check with route and middleware introspection.
+
+    In test environment, reports as healthy since the app is loaded.
+    In production, uses internal check to avoid circular dependency.
+    Includes comprehensive route and middleware metadata for dashboard display.
+    """
+    import os
+    global _cached_route_metadata, _cached_middleware_metadata
+
+    # Check if we're in test environment
+    if os.getenv("PYTEST_CURRENT_TEST") or "pytest" in os.getenv("_", ""):
+        # Even in test mode, try to get route and middleware information if possible
+        try:
+            
+            # Initialize cache if not already done (might happen in tests)
+            if _cached_route_metadata is None or _cached_middleware_metadata is None:
+                _initialize_route_metadata_cache()
+            
+            route_metadata = _cached_route_metadata
+            middleware_metadata = _cached_middleware_metadata
+            
+            # Handle case where metadata is not available in test mode
+            if route_metadata is None or middleware_metadata is None:
+                return ComponentStatus(
+                    name="backend",
+                    status=ComponentStatusType.HEALTHY,
+                    message="FastAPI backend available (test mode)",
+                    response_time_ms=None,
+                    metadata={
+                        "type": "component_check",
+                        "environment": "test",
+                        "note": "Backend component loaded successfully",
+                        "route_introspection": "unavailable",
+                        "middleware_introspection": "unavailable",
+                    },
+                )
+            
+            # Create message with both route and middleware info
+            message_parts = [f"{route_metadata.total_routes} routes"]
+            if middleware_metadata.security_count > 0:
+                message_parts.append(
+                    f"{middleware_metadata.security_count} security layers"
+                )
+            
+            return ComponentStatus(
+                name="backend",
+                status=ComponentStatusType.HEALTHY,
+                message=(
+                    f"FastAPI backend available (test mode): "
+                    f"{', '.join(message_parts)}"
+                ),
+                response_time_ms=None,
+                metadata={
+                    "type": "component_check",
+                    "environment": "test",
+                    "note": "Backend component loaded successfully",
+                    **route_metadata.model_dump_for_metadata(),
+                    **middleware_metadata.model_dump_for_metadata(),
+                },
+            )
+        except Exception as e:
+            logger.warning(
+                f"Could not get route and middleware metadata in test mode: {e}"
+            )
+            return ComponentStatus(
+                name="backend",
+                status=ComponentStatusType.HEALTHY,
+                message="FastAPI backend available (test mode)",
+                response_time_ms=None,
+                metadata={
+                    "type": "component_check",
+                    "environment": "test",
+                    "note": "Backend component loaded successfully",
+                    "route_introspection_error": str(e),
+                    "middleware_introspection_error": str(e),
+                },
+            )
+
+    # In production, use cached route and middleware information
+    try:
+        # Initialize cache if not already done (fallback safety)
+        if _cached_route_metadata is None or _cached_middleware_metadata is None:
+            logger.warning(
+                "Route and middleware metadata cache not initialized at startup, "
+                "initializing now..."
+            )
+            _initialize_route_metadata_cache()
+        
+        route_metadata = _cached_route_metadata
+        middleware_metadata = _cached_middleware_metadata
+        
+        # Handle case where metadata is still not available
+        if route_metadata is None or middleware_metadata is None:
+            return ComponentStatus(
+                name="backend",
+                status=ComponentStatusType.HEALTHY,
+                message=(
+                    "FastAPI backend active (introspection unavailable)"
+                ),
+                response_time_ms=None,
+                metadata={
+                    "type": "internal_component_check",
+                    "note": (
+                        "Backend is running but route/middleware metadata unavailable"
+                    ),
+                    "check_method": "internal_execution",
+                },
+            )
+        
+        # Create descriptive message based on route and middleware data
+        total_routes = route_metadata.total_routes
+        total_endpoints = route_metadata.total_endpoints
+        method_counts = route_metadata.method_counts
+        security_count = middleware_metadata.security_count
+        
+        # Format method summary (e.g., "12 GET, 5 POST")
+        method_summary = ", ".join([
+            f"{count} {method}" 
+            for method, count in sorted(method_counts.items())
+        ])
+        
+        message_parts = [f"{total_routes} routes"]
+        if total_endpoints != total_routes:
+            message_parts.append(f"{total_endpoints} endpoints")
+        if security_count > 0:
+            message_parts.append(f"{security_count} security layers")
+        if method_summary:
+            message_parts.append(f"({method_summary})")
+        
+        message = f"FastAPI backend active: {', '.join(message_parts)}"
+        
+        return ComponentStatus(
+            name="backend",
+            status=ComponentStatusType.HEALTHY,
+            message=message,
+            response_time_ms=None,
+            metadata={
+                "type": "internal_component_check",
+                "note": (
+                    "Backend is running since this health check executed"
+                ),
+                "check_method": "internal_execution",
+                **route_metadata.model_dump_for_metadata(),
+                **middleware_metadata.model_dump_for_metadata(),
+            },
+        )
+    except Exception as e:
+        return ComponentStatus(
+            name="backend",
+            status=ComponentStatusType.UNHEALTHY,
+            message=f"Backend component check failed: {str(e)}",
+            response_time_ms=None,
+            metadata={
+                "type": "internal_component_check",
+                "error": "import_or_execution_error",
+                "error_details": str(e),
+            },
+        )
+
+
+async def _frontend_component_health() -> ComponentStatus:
+    """
+    Flet frontend health check.
+
+    Since the frontend runs in the same process as the backend,
+    we check if the frontend component is properly initialized.
+    """
+    try:
+        # Check if frontend component is available
+        from app.components.frontend.main import create_frontend_app
+
+        # Verify the frontend app factory function works
+        create_frontend_app()
+
+        return ComponentStatus(
+            name="frontend",
+            status=ComponentStatusType.HEALTHY,
+            message="Flet frontend component available",
+            response_time_ms=None,
+            metadata={
+                "type": "component_check",
+                "framework": "flet",
+                "note": "Frontend integrated with FastAPI",
+            },
+        )
+
+    except ImportError as e:
+        return ComponentStatus(
+            name="frontend",
+            status=ComponentStatusType.UNHEALTHY,
+            message="Frontend component not found",
+            response_time_ms=None,
+            metadata={
+                "type": "component_check",
+                "error": "import_error",
+                "error_details": str(e),
+            },
+        )
+    except Exception as e:
+        return ComponentStatus(
+            name="frontend",
+            status=ComponentStatusType.UNHEALTHY,
+            message=f"Frontend component error: {str(e)}",
+            response_time_ms=None,
+            metadata={
+                "type": "component_check",
+                "error": "unexpected_error",
+                "error_details": str(e),
+            },
+        )
+
+{%- if cookiecutter.include_scheduler == "yes" %}
+
+
+async def _scheduler_component_health() -> ComponentStatus:
+    """
+    Check scheduler component health from backend.
+{%- if cookiecutter.scheduler_backend != "memory" %}
+
+    With persistence: Gets real task data from database
+{%- else %}
+
+    Without persistence: Shows component as activated only
+{%- endif %}
+    """
+    {% if cookiecutter.scheduler_backend != "memory" %}
+    try:
+        from app.services.scheduler.task_monitor import TaskHealthMonitor
+        monitor = TaskHealthMonitor()
+        # No scheduler instance available in backend
+        health_data = await monitor.get_health_metadata(None)
+        
+        # Format message based on task data
+        total_tasks = health_data.total_tasks
+        if total_tasks > 0:
+            message = f"Scheduler running with {total_tasks} tasks"
+        else:
+            message = "Scheduler running (no tasks)"
+        
+        return ComponentStatus(
+            name="scheduler",
+            status=ComponentStatusType.HEALTHY,
+            message=message,
+            response_time_ms=None,
+            metadata=health_data.model_dump(),
+        )
+    except Exception as e:
+        logger.error("Failed to get scheduler health data", error=str(e))
+        # Fallback to basic status
+        return ComponentStatus(
+            name="scheduler",
+            status=ComponentStatusType.WARNING,
+            message="Scheduler enabled, health data unavailable",
+            response_time_ms=None,
+            metadata={
+                "type": "component_status",
+                "error": "health_check_failed",
+                "error_details": str(e),
+            },
+        )
+    {% else %}
+    return ComponentStatus(
+        name="scheduler",
+        status=ComponentStatusType.HEALTHY,
+        message="Scheduler component activated",
+        response_time_ms=None,
+        metadata={
+            "type": "component_status",
+            "deployment": "separate_container",
+            "status": "activated",
+            "note": "Memory-only mode - no cross-container health monitoring",
+        },
+    )
+    {% endif %}
+{%- endif %}
+
+
+async def startup_hook() -> None:
+    """
+    Auto-detect available components and register their health checks.
+
+    Always registers core components (backend, frontend) and detects
+    optional components using Python's import system.
+    """
+    logger.info("Registering component health checks...")
+
+    # Initialize route metadata cache once at startup
+    _initialize_route_metadata_cache()
+
+    # Always register core components
+    register_health_check("backend", _backend_component_health)
+    logger.info("Backend component health check registered")
+
+    register_health_check("frontend", _frontend_component_health)
+    logger.info("️Frontend component health check registered")
+
+    {%- if cookiecutter.include_scheduler == "yes" %}
+    # Register scheduler component health check
+    register_health_check("scheduler", _scheduler_component_health)
+    {% if cookiecutter.scheduler_backend != "memory" %}
+    logger.info("Scheduler component health check registered (with task data)")
+    {% else %}
+    logger.info("Scheduler component enabled (shows as activated)")
+    {% endif %}
+    {%- endif %}
+
+    {%- if cookiecutter.include_worker == "yes" %}
+    # Register worker health check (shows queue status and job metrics)
+    from app.services.system.health import check_worker_health
+    register_health_check("worker", check_worker_health)
+    logger.info("Worker component health check registered")
+    {%- endif %}
+
+    {%- if cookiecutter.include_redis == "yes" %}
+    # Register cache health check (Redis connectivity and operations)
+    from app.services.system.health import check_cache_health
+    register_health_check("cache", check_cache_health)
+    logger.info("Cache component health check registered")
+    {%- endif %}
+
+    {%- if cookiecutter.include_database == "yes" %}
+    # Register database health check (SQLite connectivity and basic operations)
+    from app.services.system.health import check_database_health
+    register_health_check("database", check_database_health)
+    logger.info("Database component health check registered")
+    {%- endif %}
+
+    logger.info("✅ Component health detection complete")
+
+    # ==========================================
+    # Service Health Checks Registration
+    # ==========================================
+
+    from app.services.system.health import register_service_health_check
+
+    logger.info("🔧 Registering service health checks...")
+
+    {%- if cookiecutter.include_auth == "yes" %}
+    # Register auth service health check
+    from app.services.auth.health import check_auth_service_health
+    register_service_health_check("auth", check_auth_service_health)
+    logger.info("Auth service health check registered")
+    {%- endif %}
+
+    {%- if cookiecutter.include_ai == "yes" %}
+    # Register AI service health check
+    from app.services.ai.health import check_ai_service_health
+    register_service_health_check("ai", check_ai_service_health)
+    logger.info("AI service health check registered")
+    {%- endif %}
+
+    # Future services will be registered here:
+    # Example:
+    #     from app.services.payment.health import check_payment_service_health
+    #     register_service_health_check("payment", check_payment_service_health)
+
+    logger.info("✅ Service health detection complete")

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/backend/startup/database_init.py.j2

@@ -0,0 +1,83 @@
+"""
+Database initialization startup hook.
+
+Ensures database directory structure exists and verifies connectivity
+when the backend starts up (only when database component is included).
+"""
+{% if cookiecutter.include_database == "yes" %}
+
+from pathlib import Path
+from app.core.db import init_database
+from app.core.log import logger
+
+{% if cookiecutter.include_auth == "yes" %}
+# Import models to register them with SQLModel metadata
+from app.models.user import User  # noqa: F401
+{% endif %}
+
+
+async def startup_database_init() -> None:
+    """
+    Initialize database directory structure and verify connectivity.
+
+    This hook runs when the backend starts to ensure the database
+    directory exists and connection works. For auth service projects,
+    migrations should already be applied during project generation.
+    """
+    try:
+        # Ensure database directory exists
+        from app.core.db import DATABASE_PATH
+        db_path = Path(DATABASE_PATH)
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        {% if cookiecutter.include_auth == "yes" %}
+        # Auth service - verify database and migration status
+        try:
+            from app.core.db import db_session
+            from sqlmodel import select, func, text
+            from sqlalchemy import inspect
+
+            with db_session(autocommit=False) as session:
+                # Check 1: Basic database connectivity
+                session.exec(text("SELECT 1"))
+
+                # Check 2: Auth tables exist (User table specifically)
+                session.exec(select(func.count()).select_from(User))
+
+                # Check 3: Alembic migration system is set up
+                inspector = inspect(session.connection())
+                table_names = inspector.get_table_names()
+
+                if "alembic_version" in table_names:
+                    logger.info(
+                        "✅ Database connectivity and auth schema verified "
+                        "(migrations applied)"
+                    )
+                else:
+                    logger.warning(
+                        "⚠️  alembic_version table missing - migrations may not be "
+                        "fully applied"
+                    )
+                    logger.warning(
+                        "💡 Run 'alembic upgrade head' to ensure all migrations "
+                        "are applied"
+                    )
+
+        except Exception as e:
+            logger.warning(f"⚠️  Database check failed: {e}")
+            logger.warning("💡 Run 'alembic upgrade head' to apply migrations")
+            # Don't fail startup - let the app run and show clear errors
+        {% else %}
+        # Database component only - ensure tables exist
+        init_database()
+        logger.info("🗃️  Database initialization completed")
+        {% endif %}
+
+    except Exception as e:
+        logger.error(f"❌ Database initialization failed: {e}")
+        raise
+
+
+# Export the startup hook function
+startup_hook = startup_database_init
+{% endif %}

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/frontend/__init__.py

@@ -0,0 +1,5 @@
+"""Simple Flet frontend dashboard component."""
+
+from .main import create_frontend_app
+
+__all__ = ["create_frontend_app"]

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/frontend/controls/__init__.py

@@ -0,0 +1,27 @@
+"""Frontend UI controls for styled components."""
+
+from .table import (
+    TableCellText,
+    TableHeaderText,
+    TableNameText,
+)
+from .text import (
+    ConfirmationText,
+    LabelText,
+    MetricText,
+    PrimaryText,
+    SecondaryText,
+    TitleText,
+)
+
+__all__ = [
+    "PrimaryText",
+    "SecondaryText",
+    "TitleText",
+    "ConfirmationText",
+    "MetricText",
+    "LabelText",
+    "TableHeaderText",
+    "TableCellText",
+    "TableNameText",
+]

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/frontend/controls/table.py

@@ -0,0 +1,78 @@
+"""
+Table-specific text controls for consistent styling across cards.
+
+These controls provide standardized text styling for table headers, cells, and
+entity names to ensure consistency between worker, database, and other component cards.
+"""
+
+from typing import Any
+
+import flet as ft
+
+
+class TableHeaderText(ft.Text):  # type: ignore[misc]
+    """
+    Table header text control with consistent styling.
+
+    Used for column headers in component cards. Provides medium weight text
+    with reduced opacity for visual hierarchy.
+    """
+
+    def __init__(self, text: str, **kwargs: Any) -> None:
+        # Set defaults that can be overridden
+        defaults = {
+            "weight": ft.FontWeight.W_500,
+            "size": 12,
+            "color": ft.Colors.GREY_600,
+        }
+        defaults.update(kwargs)
+
+        super().__init__(
+            text,
+            **defaults,
+        )
+
+
+class TableCellText(ft.Text):  # type: ignore[misc]
+    """
+    Table cell text control for data values.
+
+    Used for displaying data values in table cells. Provides consistent
+    sizing and coloring for tabular data.
+    """
+
+    def __init__(self, text: str, **kwargs: Any) -> None:
+        # Set defaults that can be overridden
+        defaults = {
+            "size": 11,
+            "color": ft.Colors.ON_SURFACE,
+        }
+        defaults.update(kwargs)
+
+        super().__init__(
+            text,
+            **defaults,
+        )
+
+
+class TableNameText(ft.Text):  # type: ignore[misc]
+    """
+    Table entity name text control.
+
+    Used for displaying entity names (queues, tables, etc.) in table rows.
+    Provides consistent styling for entity identifiers.
+    """
+
+    def __init__(self, text: str, **kwargs: Any) -> None:
+        # Set defaults that can be overridden
+        defaults = {
+            "weight": ft.FontWeight.W_400,
+            "size": 11,
+            "color": ft.Colors.ON_SURFACE,
+        }
+        defaults.update(kwargs)
+
+        super().__init__(
+            text,
+            **defaults,
+        )