aegis-stack 0.1.0__py3-none-any.whl

aegis/core/template_generator.py

@@ -0,0 +1,163 @@
+"""
+Template generation and context building for Aegis Stack projects.
+
+This module handles the generation of cookiecutter context and manages
+the template rendering process based on selected components.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from .components import COMPONENTS
+
+
+class TemplateGenerator:
+    """Handles template context generation for cookiecutter."""
+
+    def __init__(self, project_name: str, selected_components: list[str]):
+        """
+        Initialize template generator.
+
+        Args:
+            project_name: Name of the project being generated
+            selected_components: List of component names to include
+        """
+        self.project_name = project_name
+        self.project_slug = project_name.lower().replace(" ", "-").replace("_", "-")
+        # Always include core components
+        all_components = ["backend", "frontend"] + selected_components
+        # Remove duplicates, preserve order
+        self.components = list(dict.fromkeys(all_components))
+        self.component_specs = {
+            name: COMPONENTS[name] for name in self.components if name in COMPONENTS
+        }
+
+    def get_template_context(self) -> dict[str, Any]:
+        """
+        Generate cookiecutter context from components.
+
+        Returns:
+            Dictionary containing all template variables
+        """
+        # Store the originally selected components (without core)
+        selected_only = [c for c in self.components if c not in ["backend", "frontend"]]
+
+        return {
+            "project_name": self.project_name,
+            "project_slug": self.project_slug,
+            # Component flags for template conditionals - cookiecutter needs yes/no
+            "include_redis": "yes" if "redis" in self.components else "no",
+            "include_worker": "yes" if "worker" in self.components else "no",
+            "include_scheduler": "yes" if "scheduler" in self.components else "no",
+            "include_database": "yes" if "database" in self.components else "no",
+            # Derived flags for template logic
+            "has_background_infrastructure": any(
+                name in self.components for name in ["worker", "scheduler"]
+            ),
+            "needs_redis": "redis" in self.components,
+            # Dependency lists for templates
+            "selected_components": selected_only,  # Original selection for context
+            "docker_services": self._get_docker_services(),
+            "pyproject_dependencies": self._get_pyproject_deps(),
+        }
+
+    def _get_docker_services(self) -> list[str]:
+        """
+        Collect all docker services needed.
+
+        Returns:
+            List of docker service names
+        """
+        services = []
+        for component_name in self.components:
+            if component_name in self.component_specs:
+                spec = self.component_specs[component_name]
+                if spec.docker_services:
+                    services.extend(spec.docker_services)
+        return list(dict.fromkeys(services))  # Preserve order, remove duplicates
+
+    def _get_pyproject_deps(self) -> list[str]:
+        """
+        Collect all Python dependencies.
+
+        Returns:
+            Sorted list of Python package dependencies
+        """
+        deps = []
+        for component_name in self.components:
+            if component_name in self.component_specs:
+                spec = self.component_specs[component_name]
+                if spec.pyproject_deps:
+                    deps.extend(spec.pyproject_deps)
+        return sorted(set(deps))  # Sort and deduplicate
+
+    def get_template_files(self) -> list[str]:
+        """
+        Get list of template files that should be included.
+
+        Returns:
+            List of template file paths
+        """
+        files = []
+        for component_name in self.components:
+            if component_name in self.component_specs:
+                spec = self.component_specs[component_name]
+                if spec.template_files:
+                    files.extend(spec.template_files)
+        return list(dict.fromkeys(files))  # Preserve order, remove duplicates
+
+    def get_entrypoints(self) -> list[str]:
+        """
+        Get list of entrypoints that will be created.
+
+        Returns:
+            List of entrypoint file paths
+        """
+        entrypoints = ["app/entrypoints/webserver.py"]  # Always included
+
+        # Check component specs for actual entrypoint files
+        for component_name in self.components:
+            if component_name in self.component_specs:
+                spec = self.component_specs[component_name]
+                if spec.template_files:
+                    for template_file in spec.template_files:
+                        if (
+                            template_file.startswith("app/entrypoints/")
+                            and template_file not in entrypoints
+                        ):
+                            entrypoints.append(template_file)
+
+        return entrypoints
+
+    def get_worker_queues(self) -> list[str]:
+        """
+        Get list of worker queue files that will be created.
+
+        Returns:
+            List of worker queue file paths
+        """
+        queues: list[str] = []
+
+        # Only check if worker component is included
+        if "worker" not in self.components:
+            return queues
+
+        # Discover queue files from the template directory
+        template_root = (
+            Path(__file__).parent.parent / "templates" / "cookiecutter-aegis-project"
+        )
+        worker_queues_dir = (
+            template_root
+            / "{{cookiecutter.project_slug}}"
+            / "app"
+            / "components"
+            / "worker"
+            / "queues"
+        )
+
+        if worker_queues_dir.exists():
+            for queue_file in worker_queues_dir.glob("*.py"):
+                if queue_file.stem != "__init__":
+                    queues.append(f"app/components/worker/queues/{queue_file.name}")
+
+        return sorted(queues)

aegis/templates/CLAUDE.md

@@ -0,0 +1,306 @@
+# Template Development Guide
+
+This guide covers template development patterns for Aegis Stack's Cookiecutter templates.
+
+## Template Architecture
+
+### Template Structure
+```
+aegis/templates/cookiecutter-aegis-project/
+├── cookiecutter.json                    # Template variables
+├── hooks/
+│   └── post_gen_project.py             # Template processing logic
+└── {{cookiecutter.project_slug}}/      # Generated project structure
+    ├── app/
+    │   ├── components/
+    │   │   ├── backend/                 # Always included
+    │   │   ├── frontend/                # Always included
+    │   │   ├── scheduler/               # Optional component
+    │   │   └── worker/                  # Optional component
+    │   ├── core/                        # Framework utilities
+    │   ├── entrypoints/                 # Execution modes
+    │   ├── integrations/                # App composition
+    │   └── services/                    # Business logic (empty)
+    ├── tests/
+    ├── docker-compose.yml.j2            # Conditional services
+    ├── Dockerfile.j2                    # Conditional entrypoints
+    ├── pyproject.toml.j2                # Dependencies and configuration
+    └── scripts/entrypoint.sh.j2         # Runtime dispatch
+```
+
+### Template Processing Flow
+1. **Cookiecutter generates** base project structure using `cookiecutter.json`
+2. **Post-generation hook** (`hooks/post_gen_project.py`) processes `.j2` files with Jinja2
+3. **Component selection** includes/excludes files based on user choices
+4. **Auto-formatting** runs `make fix` on generated project
+5. **Cleanup** removes unused template files and `.j2` originals
+
+## Cookiecutter Variables
+
+### Core Variables (cookiecutter.json)
+```json
+{
+    "project_name": "My Aegis Project",
+    "project_slug": "{{ cookiecutter.project_name|lower|replace(' ', '-')|replace('_', '-') }}",
+    "project_description": "A production-ready Python application",
+    "author_name": "Your Name",
+    "author_email": "your.email@example.com",
+    "version": "0.1.0",
+    "python_version": "3.11",
+    "include_scheduler": "no",
+    "include_worker": "no"
+}
+```
+
+### Variable Usage in Templates
+```jinja2
+# In any .j2 file
+{{ cookiecutter.project_name }}           # "My Aegis Project"
+{{ cookiecutter.project_slug }}           # "my-aegis-project"
+{{ cookiecutter.project_description }}    # Description text
+{{ cookiecutter.author_name }}            # Author info
+{{ cookiecutter.include_scheduler }}      # "yes" or "no"
+```
+
+## Jinja2 Template Patterns
+
+### Conditional Content
+```jinja2
+{% if cookiecutter.include_scheduler == "yes" %}
+# Scheduler-specific content
+{% endif %}
+
+{% if cookiecutter.include_worker == "yes" %}
+# Worker-specific content
+{% endif %}
+```
+
+### Conditional Files
+File names can be conditional:
+```
+{% if cookiecutter.include_scheduler == "yes" %}scheduler.py{% endif %}
+```
+
+### Variable Substitution in Code
+```python
+# In .j2 files
+CLI_NAME = "{{ cookiecutter.project_slug }}"
+PROJECT_NAME = "{{ cookiecutter.project_name }}"
+VERSION = "{{ cookiecutter.version }}"
+```
+
+### Dependencies Based on Components
+```toml
+# pyproject.toml.j2
+dependencies = [
+    "fastapi>=0.116.1",
+    "flet>=0.28.3",
+{% if cookiecutter.include_scheduler == "yes" %}
+    "apscheduler>=3.10.0",
+{% endif %}
+{% if cookiecutter.include_worker == "yes" %}
+    "arq>=0.26.1",
+    "redis>=5.2.1",
+{% endif %}
+]
+```
+
+## Post-Generation Hook Patterns
+
+### Hook Responsibilities
+The `hooks/post_gen_project.py` script:
+1. **Processes .j2 files** - Renders Jinja2 templates with cookiecutter context
+2. **Removes unused files** - Deletes component files when components not selected
+3. **Cleans up directories** - Removes empty directories after file cleanup
+4. **Auto-formats code** - Runs `make fix` to ensure generated code is clean
+
+### Adding New Component Logic
+```python
+# In hooks/post_gen_project.py
+if "{{ cookiecutter.include_new_component }}" != "yes":
+    # Remove component-specific files
+    remove_dir("app/components/new_component")
+    remove_file("app/entrypoints/new_component.py")
+    remove_file("tests/components/test_new_component.py")
+```
+
+### File Removal Patterns
+```python
+# Remove individual files
+remove_file("app/components/scheduler.py")
+remove_file("tests/components/test_scheduler.py")
+
+# Remove entire directories
+remove_dir("app/components/worker")
+```
+
+## Template Development Workflow
+
+### CRITICAL: Never Edit Generated Projects
+**Always follow this pattern:**
+
+1. **Edit template files** in `aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/`
+2. **Test template changes**: `make test-template`
+3. **If tests fail**: Fix the **template files** (step 1), never the generated projects
+4. **Repeat** until tests pass
+5. **Clean up**: `make clean-test-projects`
+
+### Adding New Template Files
+```bash
+# 1. Create template file
+vim aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/app/components/new_component.py
+
+# 2. If using variables, make it a .j2 file
+mv app/components/new_component.py app/components/new_component.py.j2
+
+# 3. Add conditional logic to hook if needed
+vim hooks/post_gen_project.py
+
+# 4. Test the changes
+make test-template
+```
+
+### Modifying Existing Templates
+```bash
+# 1. Find the template file
+find aegis/templates/ -name "*.py" -o -name "*.j2" | grep component_name
+
+# 2. Edit the template
+vim aegis/templates/cookiecutter-aegis-project/{{cookiecutter.project_slug}}/path/to/file.j2
+
+# 3. Test immediately
+make test-template-quick
+
+# 4. Full validation
+make test-template
+```
+
+## Template Testing Integration
+
+### Template Validation Process
+When you run `make test-template`:
+1. **Generates fresh project** using current templates
+2. **Processes .j2 files** through post-generation hook
+3. **Installs dependencies** in generated project
+4. **Runs quality checks** (lint, typecheck, tests)
+5. **Tests CLI installation** and functionality
+
+### Template-Specific Test Commands
+```bash
+make test-template                # Test basic project generation
+make test-template-with-components # Test with scheduler component
+make test-template-worker         # Test worker component
+make test-template-full           # Test all components
+```
+
+### Auto-Fixing in Templates
+The template system automatically:
+- **Fixes linting issues** in generated code
+- **Formats code** with ruff
+- **Ensures proper imports** and structure
+- **Validates type annotations**
+
+## Common Template Patterns
+
+### Configuration Management
+```python
+# Use in templates for environment-dependent values
+from app.core.config import settings
+
+# Template generates proper imports
+DATABASE_URL = settings.DATABASE_URL
+REDIS_URL = settings.REDIS_URL
+```
+
+### Component Registration
+```python
+# Backend component registration
+# In app/components/backend/startup/component_health.py.j2
+{% if cookiecutter.include_worker == "yes" %}
+from app.components.worker.health import register_worker_health_checks
+{% endif %}
+
+async def register_component_health_checks() -> None:
+    """Register health checks for all enabled components."""
+{% if cookiecutter.include_worker == "yes" %}
+    register_worker_health_checks()
+{% endif %}
+```
+
+### Docker Service Configuration
+```yaml
+# docker-compose.yml.j2
+services:
+  webserver:
+    # Always included
+    
+{% if cookiecutter.include_worker == "yes" %}
+  worker-system:
+    build: .
+    command: ["worker-system"]
+    depends_on:
+      - redis
+{% endif %}
+
+{% if cookiecutter.include_scheduler == "yes" %}
+  scheduler:
+    build: .
+    command: ["scheduler"]
+{% endif %}
+```
+
+## Template Debugging
+
+### Common Template Issues
+- **Jinja2 syntax errors** - Check bracket matching, endif statements
+- **Missing cookiecutter variables** - Verify variable names in cookiecutter.json
+- **Conditional logic errors** - Test with different component combinations
+- **File path issues** - Ensure proper directory structure
+
+### Debugging Template Generation
+```bash
+# Generate project manually for debugging
+uv run aegis init debug-project --output-dir ../debug --force --yes
+
+# Check generated files
+ls -la ../debug-project/
+
+# Look for remaining .j2 files (should be none)
+find ../debug-project/ -name "*.j2"
+
+# Check variable substitution
+grep -r "cookiecutter\." ../debug-project/ || echo "No unreplaced variables"
+```
+
+### Testing Individual Components
+```bash
+# Test specific component combinations
+make test-template-worker         # Just worker component
+make test-template-with-components # Just scheduler component
+make test-template-full           # All components
+
+# Clean up between tests
+make clean-test-projects
+```
+
+## Template Quality Standards
+
+### Code Generation Requirements
+- **No .j2 files** remain in generated projects
+- **All variables replaced** - no `{{ cookiecutter.* }}` in final code
+- **Proper imports** - only import what's needed based on components
+- **Type annotations** - all generated code must be properly typed
+- **Linting passes** - generated code passes ruff checks
+- **Tests included** - component tests generated with components
+
+### Component Isolation
+- **Independent components** - each component can be enabled/disabled
+- **Clean dependencies** - components only depend on what they need
+- **Proper cleanup** - unused files removed when components disabled
+- **No broken imports** - imports only exist when dependencies available
+
+### File Organization
+- **Consistent structure** - follow established patterns
+- **Logical grouping** - related files in same directories
+- **Clear naming** - descriptive file and directory names
+- **Proper permissions** - executable files marked as executable

aegis/templates/cookiecutter-aegis-project/cookiecutter.json

@@ -0,0 +1,27 @@
+{
+  "project_name": "My Aegis Stack Project",
+  "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '-').replace('_', '-') }}",
+  "project_description": "A production-ready async Python application built with Aegis Stack",
+  "author_name": "Your Name",
+  "author_email": "your.email@example.com", 
+  "github_username": "your-username",
+  "version": "0.1.0",
+  "python_version": "3.11",
+  
+  "_comment_components": "Component selection - these will be set by our CLI",
+  "include_scheduler": "no",
+  "include_redis": "no",
+  "include_worker": "no",
+  "include_database": "no", 
+  "include_cache": "no",
+  
+  "_comment_internal": "Internal variables for template logic",
+  "_has_additional_components": "{% if cookiecutter.include_scheduler == 'yes' or cookiecutter.include_redis == 'yes' or cookiecutter.include_worker == 'yes' or cookiecutter.include_database == 'yes' or cookiecutter.include_cache == 'yes' %}yes{% else %}no{% endif %}",
+  
+  "_comment_dependencies": "Component-specific dependencies",
+  "_scheduler_deps": "{% if cookiecutter.include_scheduler == 'yes' %}apscheduler>=3.10.0{% endif %}",
+  "_redis_deps": "{% if cookiecutter.include_redis == 'yes' %}redis>=5.0.0{% endif %}",
+  "_worker_deps": "{% if cookiecutter.include_worker == 'yes' %}arq>=0.25.0{% endif %}",
+  "_database_deps": "{% if cookiecutter.include_database == 'yes' %}sqlmodel>=0.0.14,sqlalchemy>=2.0.0,aiosqlite>=0.19.0{% endif %}",
+  "_cache_deps": "{% if cookiecutter.include_cache == 'yes' %}redis[hiredis]>=5.0.0{% endif %}"
+}

aegis/templates/cookiecutter-aegis-project/hooks/post_gen_project.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+from jinja2 import Environment
+
+PROJECT_DIRECTORY = os.path.realpath(os.path.curdir)
+
+
+def remove_file(filepath):
+    """Removes a file from the generated project."""
+    full_path = os.path.join(PROJECT_DIRECTORY, filepath)
+    if os.path.exists(full_path):
+        os.remove(full_path)
+
+
+def remove_dir(dirpath):
+    """Removes a directory from the generated project."""
+    full_path = os.path.join(PROJECT_DIRECTORY, dirpath)
+    if os.path.exists(full_path):
+        shutil.rmtree(full_path)
+
+
+def process_j2_templates():
+    """
+    Process all .j2 template files in the generated project.
+    Renders them with cookiecutter context and removes the .j2 originals.
+    Returns list of output files that were created.
+    """
+    # Cookiecutter context variables - these template strings are processed
+    # by cookiecutter before this hook runs, so they contain actual values
+    context = {
+        "cookiecutter": {
+            "project_name": "{{ cookiecutter.project_name }}",
+            "project_slug": "{{ cookiecutter.project_slug }}",
+            "project_description": "{{ cookiecutter.project_description }}",
+            "author_name": "{{ cookiecutter.author_name }}",
+            "author_email": "{{ cookiecutter.author_email }}",
+            "version": "{{ cookiecutter.version }}",
+            "python_version": "{{ cookiecutter.python_version }}",
+            "include_redis": "{{ cookiecutter.include_redis }}",
+            "include_scheduler": "{{ cookiecutter.include_scheduler }}",
+            "include_worker": "{{ cookiecutter.include_worker }}",
+            "include_database": "{{ cookiecutter.include_database }}",
+            "include_cache": "{{ cookiecutter.include_cache }}",
+        }
+    }
+
+    # Find all .j2 files in the project
+    project_path = Path(PROJECT_DIRECTORY)
+    j2_files = list(project_path.rglob("*.j2"))
+    processed_files = []
+
+    for j2_file in j2_files:
+        # Read the template content
+        with open(j2_file, encoding="utf-8") as f:
+            template_content = f.read()
+
+        # Create Jinja2 environment and render the template
+        env = Environment()
+        template = env.from_string(template_content)
+        rendered_content = template.render(context)
+
+        # Write the rendered content to the final file (without .j2 extension)
+        output_file = j2_file.with_suffix("")
+        with open(output_file, "w", encoding="utf-8") as f:
+            f.write(rendered_content)
+
+        # Remove the original .j2 file
+        j2_file.unlink()
+
+        # Track processed files for later reporting
+        processed_files.append(output_file)
+
+        # Ensure file ends with newline
+        if not rendered_content.endswith("\n"):
+            with open(output_file, "a", encoding="utf-8") as f:
+                f.write("\n")
+
+    return processed_files
+
+
+def run_auto_formatting():
+    """
+    Auto-format generated code by calling make fix.
+    Fixes linting issues and formats code for consistency.
+    """
+    try:
+        print("🎨 Auto-formatting generated code...")
+
+        # Call make fix to auto-format the generated project
+        result = subprocess.run(
+            ["make", "fix"],
+            cwd=PROJECT_DIRECTORY,
+            capture_output=True,
+            text=True,
+            timeout=60,  # Don't hang forever
+        )
+
+        if result.returncode == 0:
+            print("✅ Code formatting completed successfully")
+        else:
+            print(
+                "⚠️  Some formatting issues detected, but project created successfully"
+            )
+            print("💡 Run 'make fix' manually to resolve remaining issues")
+
+    except FileNotFoundError:
+        print("💡 Run 'make fix' to format code when ready")
+    except subprocess.TimeoutExpired:
+        print("⚠️  Formatting timeout - run 'make fix' manually when ready")
+    except Exception as e:
+        print(f"⚠️  Auto-formatting skipped: {e}")
+        print("💡 Run 'make fix' manually to format code")
+        # Don't fail project generation due to formatting issues
+
+
+def main():
+    """
+    Runs the post-generation cleanup to remove files for unselected
+    components and process template files.
+    """
+    # Process .j2 template files first
+    processed_files = process_j2_templates()
+
+    # Remove components not selected
+    if "{{ cookiecutter.include_scheduler }}" != "yes":
+        # Remove scheduler-specific files
+        remove_file("app/entrypoints/scheduler.py")
+        remove_dir("app/components/scheduler")
+        remove_file("tests/components/test_scheduler.py")
+        remove_file("docs/components/scheduler.md")
+
+    if "{{ cookiecutter.include_worker }}" != "yes":
+        # Remove worker-specific files
+        remove_dir("app/components/worker")
+        remove_file("app/cli/load_test.py")
+        remove_file("app/services/load_test.py")
+        remove_file("app/services/load_test_models.py")
+        remove_file("tests/services/test_load_test_models.py")
+        remove_file("tests/services/test_load_test_service.py")
+        remove_file("tests/services/test_worker_health_registration.py")
+
+    if "{{ cookiecutter.include_database }}" != "yes":
+        remove_file("app/core/db.py")
+
+    if "{{ cookiecutter.include_cache }}" != "yes":
+        # remove_file("app/services/cache_service.py")
+        pass  # Placeholder for cache component
+
+    # Clean up empty docs/components directory if no components selected
+    if (
+        "{{ cookiecutter.include_scheduler }}" != "yes"
+        and "{{ cookiecutter.include_worker }}" != "yes"
+        and "{{ cookiecutter.include_database }}" != "yes"
+        and "{{ cookiecutter.include_cache }}" != "yes"
+    ):
+        remove_dir("docs/components")
+
+    # Print only templates that survived cleanup
+    for file_path in processed_files:
+        if file_path.exists():
+            print(f"Processed template: {file_path.name}")
+
+    # Run auto-formatting after all processing is complete
+    run_auto_formatting()
+
+
+if __name__ == "__main__":
+    main()