aegis-stack 0.1.0__py3-none-any.whl

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/scripts/entrypoint.sh.j2

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+
+set -e
+
+# More comprehensive venv cleanup to prevent Docker container conflicts
+if [ -d ".venv" ]; then
+    echo "🧹 Found existing .venv directory, checking compatibility..."
+    
+    # Check if .venv has issues (broken symlinks, wrong Python version, etc.)
+    if [ -L ".venv/bin/python3" ] && [ ! -e ".venv/bin/python3" ]; then
+        echo "🧹 Cleaning up broken venv symlinks..."
+        rm -rf .venv
+    elif [ -f ".venv/bin/python3" ]; then
+        # Check if the Python executable is compatible and accessible
+        if ! .venv/bin/python3 --version > /dev/null 2>&1; then
+            echo "🧹 Cleaning up incompatible venv..."
+            rm -rf .venv
+        fi
+    elif [ ! -w ".venv" ] || [ ! -x ".venv" ]; then
+        # Check for permission issues in Docker containers
+        echo "🧹 Cleaning up venv with permission issues..."
+        rm -rf .venv
+    else
+        # If directory exists but has no python executable, clean it up
+        if [ ! -f ".venv/bin/python3" ] && [ ! -f ".venv/bin/python" ]; then
+            echo "🧹 Cleaning up incomplete venv..."
+            rm -rf .venv
+        fi
+    fi
+fi
+
+# Configure UV environment based on execution context
+if [ -n "$DOCKER_CONTAINER" ] || [ "$USER" = "root" ]; then
+    echo "🐳 Running in Docker container, configuring UV for containerized environment..."
+    
+    # Set Docker-specific UV configuration
+    export UV_PROJECT_ENVIRONMENT=/code/.venv
+    export UV_LINK_MODE=copy
+    export VIRTUAL_ENV=/code/.venv
+    
+    # Ensure .venv path is in PATH for CLI commands
+    export PATH="/code/.venv/bin:$PATH"
+    
+    echo "✅ UV configured for Docker: UV_PROJECT_ENVIRONMENT=/code/.venv"
+else
+    echo "🖥️  Running in local environment, UV will use project defaults"
+    
+    # Ensure we don't inherit Docker environment variables
+    unset UV_PROJECT_ENVIRONMENT
+    unset UV_SYSTEM_PYTHON
+    
+    # Let UV auto-detect local .venv
+    echo "✅ UV configured for local development"
+fi
+
+# Pop run_command from arguments
+run_command="$1"
+shift
+
+if [ "$run_command" = "webserver" ]; then
+    # Web server (FastAPI + Flet)
+    uv run python -m app.entrypoints.webserver
+elif [ "$run_command" = "scheduler" ]; then
+    # Scheduler component
+    uv run python -m app.entrypoints.scheduler
+elif [ "$run_command" = "worker" ]; then
+    # Worker component using STANDARD arq CLI
+    queue_type="${1:-system}"  # Default to system queue if not specified
+    shift
+    
+    # Build the module path for the queue
+    worker_module="app.components.worker.queues.${queue_type}.WorkerSettings"
+    
+    # Development mode auto-reload (APP_ENV from .env or WORKER_WATCH override)
+    if [ "$APP_ENV" = "dev" ] || [ "$WORKER_WATCH" = "true" ]; then
+        echo "🔄 Starting ${queue_type} worker with auto-reload..."
+        exec uv run python -m arq "${worker_module}" --watch /code/app "$@"
+    else
+        echo "🚀 Starting ${queue_type} worker..."
+        exec uv run python -m arq "${worker_module}" "$@"
+    fi
+elif [ "$run_command" = "lint" ]; then
+    uv run ruff check .
+elif [ "$run_command" = "typecheck" ]; then
+    uv run mypy .
+elif [ "$run_command" = "test" ]; then
+    uv run pytest "$@"
+elif [ "$run_command" = "health" ]; then
+    uv run python -m app.cli.health check "$@"
+elif [ "$run_command" = "help" ]; then
+    echo "Available commands:"
+    echo "  webserver   - Run FastAPI + Flet web server"
+    echo "  scheduler   - Run scheduler component"
+    echo "  worker      - Run arq worker (standard arq CLI patterns)"
+    echo "  health      - Check system health status"
+    echo "  lint        - Run ruff linting"
+    echo "  typecheck   - Run mypy type checking"
+    echo "  test        - Run pytest test suite"
+    echo "  help        - Show this help message"
+else
+    echo "Unknown command: $run_command"
+    echo "Available commands: webserver, scheduler, worker, health, lint, typecheck, test, help"
+    exit 1
+fi

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/scripts/gen_docs.py

@@ -0,0 +1,16 @@
+# scripts/gen_docs.py
+"""
+A script to dynamically generate documentation files for MkDocs.
+This is run automatically by the mkdocs-gen-files plugin.
+"""
+
+import mkdocs_gen_files  # noqa: F401
+
+print("--- Running gen_docs.py ---")
+
+# Copy the root README.md to be the documentation's index page.
+# This allows us to maintain a single source of truth for the project's
+# main landing page, which is visible on both GitHub and the docs site.
+with open("README.md") as readme, open("docs/index.md", "w") as index:
+    index.write(readme.read())
+    print("✓ Copied README.md to docs/index.md")

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/tests/api/__init__.py

@@ -0,0 +1 @@
+# API tests package

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/tests/api/test_health_endpoints.py.j2

@@ -0,0 +1,239 @@
+"""
+Tests for health API endpoints.
+
+These tests focus on the HTTP endpoints that CLI health commands call,
+ensuring API responses match expected CLI input format and handle errors correctly.
+"""
+
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from app.integrations.main import create_integrated_app
+
+
+class TestHealthEndpoints:
+    """Test health API endpoints with various component states."""
+
+    @pytest.fixture
+    async def async_client(self) -> AsyncClient:
+        """Async HTTP client for testing."""
+        app = create_integrated_app()
+        
+        # Manually trigger startup for health check registration
+        from app.components.backend.hooks import backend_hooks
+        await backend_hooks.discover_lifespan_hooks()
+        await backend_hooks.execute_startup_hooks()
+        
+        transport = ASGITransport(app=app)
+        async with AsyncClient(
+            transport=transport, base_url="http://test"
+        ) as client:
+            yield client
+            
+        # Clean up after test
+        await backend_hooks.execute_shutdown_hooks()
+
+    @pytest.mark.asyncio
+    async def test_basic_health_endpoint_accessible(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test /health/ endpoint is accessible."""
+        response = await async_client.get("/health/")
+        
+        # Should return a valid response (200 for healthy, 503 for unhealthy)
+        assert response.status_code in [200, 503]
+        data = response.json()
+        
+        # Verify response structure matches HealthResponse model
+        assert "healthy" in data
+        assert "status" in data
+        assert "components" in data
+        assert "timestamp" in data
+        
+        # Verify components are included
+        assert isinstance(data["components"], dict)
+
+    @pytest.mark.asyncio
+    async def test_detailed_health_endpoint_accessible(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test /health/detailed endpoint is accessible."""
+        response = await async_client.get("/health/detailed")
+        
+        # Should return a valid response
+        assert response.status_code in [200, 503]
+        data = response.json()
+        
+        if response.status_code == 200:
+            # Verify response structure matches DetailedHealthResponse model
+            assert "healthy" in data
+            assert "status" in data
+            assert "service" in data
+            assert "version" in data
+            assert "components" in data
+            assert "system_info" in data
+            assert "timestamp" in data
+            assert "healthy_components" in data
+            assert "unhealthy_components" in data
+            assert "health_percentage" in data
+        else:
+            # For 503 responses, check error structure
+            assert "detail" in data
+
+    @pytest.mark.asyncio
+    async def test_health_endpoints_json_format(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that health endpoints return valid JSON for CLI consumption."""
+        
+        # Test both endpoints
+        endpoints = ["/health/", "/health/detailed"]
+        
+        for endpoint in endpoints:
+            response = await async_client.get(endpoint)
+            assert response.status_code in [200, 503]
+            
+            # Should be valid JSON
+            data = response.json()
+            assert isinstance(data, dict)
+            
+            # Should have basic health information
+            if response.status_code == 200:
+                assert isinstance(data.get("healthy"), bool)
+                assert isinstance(data.get("components"), dict)
+            elif response.status_code == 503:
+                # Error response should have detail
+                assert "detail" in data
+
+    @pytest.mark.asyncio
+    async def test_health_endpoint_component_structure(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that component structure is suitable for CLI tree display."""
+        
+        response = await async_client.get("/health/detailed")
+        assert response.status_code in [200, 503]
+        
+        data = response.json()
+        
+        if response.status_code == 200:
+            components = data["components"]
+            
+            # Should have aegis root component
+            assert "aegis" in components
+            aegis_component = components["aegis"]
+            
+            # Aegis component should have required fields for CLI display
+            assert "name" in aegis_component
+            assert "healthy" in aegis_component
+            assert "message" in aegis_component
+            
+            # Should have sub-components for tree structure
+            if "sub_components" in aegis_component:
+                sub_components = aegis_component["sub_components"]
+                assert isinstance(sub_components, dict)
+                
+                # Each sub-component should have required fields
+                for comp_name, comp_data in sub_components.items():
+                    assert "name" in comp_data
+                    assert "healthy" in comp_data
+                    assert "message" in comp_data
+
+{%- if cookiecutter.include_worker == "yes" %}
+
+    @pytest.mark.asyncio
+    async def test_worker_component_appears_in_health_response(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that worker component appears in health responses when included."""
+        
+        response = await async_client.get("/health/detailed")
+        assert response.status_code in [200, 503]
+        
+        data = response.json()
+        
+        if response.status_code == 200:
+            components = data["components"]
+            
+            # Should have aegis root component
+            assert "aegis" in components
+            aegis_component = components["aegis"]
+            
+            if "sub_components" in aegis_component:
+                sub_components = aegis_component["sub_components"]
+                
+                # Worker component should be present
+                assert "worker" in sub_components, (
+                    f"Worker component missing from health response. "
+                    f"Available components: {list(sub_components.keys())}"
+                )
+                
+                worker_component = sub_components["worker"]
+                
+                # Worker component should have required structure
+                assert "name" in worker_component
+                assert worker_component["name"] == "worker"
+                assert "healthy" in worker_component
+                assert "message" in worker_component
+                assert isinstance(worker_component["healthy"], bool)
+                
+                # Worker should have queue sub-components
+                if "sub_components" in worker_component:
+                    worker_sub_components = worker_component["sub_components"]
+                    
+                    # Should have queues component
+                    if "queues" in worker_sub_components:
+                        queues_component = worker_sub_components["queues"]
+                        assert "name" in queues_component
+                        assert "healthy" in queues_component
+                        assert "message" in queues_component
+                        
+                        # Check for individual queue health if available
+                        if "sub_components" in queues_component:
+                            queue_sub_components = queues_component["sub_components"]
+                            
+                            # Should have system and load_test queues
+                            for queue_name in ["system", "load_test"]:
+                                if queue_name in queue_sub_components:
+                                    queue_comp = queue_sub_components[queue_name]
+                                    assert "name" in queue_comp
+                                    assert "healthy" in queue_comp
+                                    assert "message" in queue_comp
+                                    
+                                    # Verify queue metadata exists
+                                    if "metadata" in queue_comp:
+                                        metadata = queue_comp["metadata"]
+                                        assert "queue_type" in metadata
+                                        assert metadata["queue_type"] == queue_name
+
+    @pytest.mark.asyncio 
+    async def test_basic_health_includes_worker_in_components(
+        self, async_client: AsyncClient
+    ) -> None:
+        """Test that basic health endpoint includes worker in components dict."""
+        
+        response = await async_client.get("/health/")
+        assert response.status_code in [200, 503]
+        
+        data = response.json()
+        
+        if response.status_code == 200:
+            components = data["components"]
+            
+            # Should have aegis root component with worker
+            assert "aegis" in components
+            aegis_component = components["aegis"]
+            
+            if "sub_components" in aegis_component:
+                sub_components = aegis_component["sub_components"]
+                
+                # Worker should be present in basic health too
+                assert "worker" in sub_components, (
+                    "Worker component should appear in basic health response"
+                )
+                
+                worker_component = sub_components["worker"]
+                assert worker_component["name"] == "worker"
+                assert isinstance(worker_component["healthy"], bool)
+
+{%- endif %}

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/tests/components/test_scheduler.py

@@ -0,0 +1,76 @@
+"""
+Tests for scheduler functionality.
+
+Note: The scheduler focuses entirely on system service monitoring.
+We test the service functions directly rather than complex scheduler components.
+
+For integration tests of the actual scheduler, see the CLI tests that generate
+complete projects and validate they work correctly.
+"""
+
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+import pytest
+
+from app.components.scheduler.main import _check_scheduler_health, create_scheduler
+from app.services.system.health import check_system_status
+
+
+@pytest.mark.asyncio
+async def test_scheduler_basic_setup() -> None:
+    """Test that the scheduler can be set up and jobs can be added."""
+    scheduler = AsyncIOScheduler()
+
+    # Add a simple job
+    scheduler.add_job(check_system_status, trigger="interval", minutes=5, id="test_job")
+
+    # Check job was added
+    jobs = scheduler.get_jobs()
+    assert len(jobs) == 1
+    assert jobs[0].id == "test_job"
+
+
+@pytest.mark.asyncio
+async def test_system_service_can_be_scheduled() -> None:
+    """Test that our system service functions work with APScheduler."""
+    scheduler = AsyncIOScheduler()
+
+    # Test that our system service function can be scheduled without errors
+    scheduler.add_job(check_system_status, trigger="interval", seconds=1, id="system")
+
+    assert len(scheduler.get_jobs()) == 1
+
+    # Get job function
+    system_job = scheduler.get_job("system")
+
+    assert system_job.func == check_system_status
+
+
+@pytest.mark.asyncio
+async def test_scheduler_health_check() -> None:
+    """Test the scheduler health check functionality."""
+    # Test health check when scheduler is not initialized
+    health_status = await _check_scheduler_health()
+    assert not health_status.healthy
+    assert "not initialized" in health_status.message
+
+    # Test with created but not started scheduler
+    scheduler = create_scheduler()
+    import app.components.scheduler.main as scheduler_module
+
+    scheduler_module._scheduler = scheduler
+
+    health_status = await _check_scheduler_health()
+    assert not health_status.healthy
+    assert "not running" in health_status.message
+
+    # Test with running scheduler
+    scheduler.start()
+    try:
+        health_status = await _check_scheduler_health()
+        assert health_status.healthy
+        assert "running with" in health_status.message
+        assert health_status.metadata is not None
+        assert "job_count" in health_status.metadata
+    finally:
+        scheduler.shutdown()
+        scheduler_module._scheduler = None

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/tests/conftest.py.j2

@@ -0,0 +1,81 @@
+"""
+Pytest configuration and fixtures for test suite.
+
+Provides common fixtures and configuration for all tests.
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Generator
+
+import pytest
+
+# Add project root to Python path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+{% if cookiecutter.include_database == "yes" %}
+from sqlalchemy import create_engine, event
+from sqlalchemy.engine.base import Engine
+from sqlalchemy.orm import sessionmaker
+from sqlmodel import Session, SQLModel
+
+
+@pytest.fixture(scope="session")
+def engine() -> Engine:
+    """
+    Create in-memory SQLite database engine for tests.
+
+    Uses :memory: database that exists only in RAM for maximum speed
+    and perfect test isolation. Each test session gets a fresh database.
+
+    Returns:
+        SQLAlchemy Engine connected to in-memory SQLite database
+    """
+    engine = create_engine(
+        "sqlite:///:memory:",
+        echo=False,  # Set to True for SQL debugging
+        connect_args={"check_same_thread": False}  # Allow multi-threaded access
+    )
+    
+    # Critical: Enable foreign key constraints in SQLite
+    # SQLite has foreign keys disabled by default for backwards compatibility
+    @event.listens_for(engine, "connect")
+    def set_sqlite_pragma(dbapi_connection, connection_record):
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.close()
+    
+    # Create all tables once per test session
+    SQLModel.metadata.create_all(engine)
+    
+    return engine
+
+
+@pytest.fixture(scope="function")
+def db_session(engine: Engine) -> Generator[Session, None, None]:
+    """
+    Provide transactional database session with automatic rollback.
+
+    Each test gets a fresh transaction that's rolled back after the test,
+    ensuring perfect isolation between tests. Uses the same transaction
+    pattern as PostgreSQL for consistency.
+
+    Args:
+        engine: Database engine from session-scoped fixture
+
+    Yields:
+        SQLModel Session for database operations
+    """
+    connection = engine.connect()
+    transaction = connection.begin()
+    session_local = sessionmaker(bind=connection)
+    session = session_local()
+    
+    yield session
+    
+    # Clean up: rollback transaction and close connection
+    session.close()
+    transaction.rollback()
+    connection.close()
+{% endif %}

aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/tests/services/__init__.py

@@ -0,0 +1 @@
+# Service tests