aegis-stack 0.2.0rc2__py3-none-any.whl

aegis/core/component_utils.py

@@ -0,0 +1,220 @@
+"""
+Component name parsing utilities for Aegis Stack.
+
+This module provides centralized utilities for parsing component names with engine
+information (e.g., 'database[sqlite]') to eliminate code duplication and improve
+robustness throughout the codebase.
+"""
+
+import re
+
+
+def parse_component_name(component: str) -> tuple[str, str | None]:
+    """
+    Parse a component name with optional engine information.
+
+    Args:
+        component: Component name like 'database[sqlite]' or 'scheduler'
+
+    Returns:
+        Tuple of (base_name, engine) where engine is None if not specified
+
+    Examples:
+        parse_component_name('database[sqlite]') -> ('database', 'sqlite')
+        parse_component_name('scheduler') -> ('scheduler', None)
+        parse_component_name('database[]') -> ('database', None)
+
+    Raises:
+        ValueError: If component name format is invalid
+    """
+    if not component or not isinstance(component, str):
+        raise ValueError(
+            f"Component name must be a non-empty string, got: {component!r}"
+        )
+
+    component = component.strip()
+    if not component:
+        raise ValueError("Component name cannot be empty or whitespace")
+
+    # Use regex for robust parsing
+    pattern = r"^([a-zA-Z][a-zA-Z0-9_-]*?)(?:\[([a-zA-Z0-9_-]*)\])?$"
+    match = re.match(pattern, component)
+
+    if not match:
+        raise ValueError(
+            f"Invalid component name format: '{component}'. "
+            "Expected format: 'name' or 'name[engine]'"
+        )
+
+    base_name, engine = match.groups()
+
+    # Handle empty engine brackets
+    if engine == "":
+        engine = None
+
+    return base_name, engine
+
+
+def extract_base_component_name(component: str) -> str:
+    """
+    Extract the base component name without engine information.
+
+    Args:
+        component: Component name like 'database[sqlite]' or 'scheduler'
+
+    Returns:
+        Base component name
+
+    Examples:
+        extract_base_component_name('database[sqlite]') -> 'database'
+        extract_base_component_name('scheduler') -> 'scheduler'
+    """
+    base_name, _ = parse_component_name(component)
+    return base_name
+
+
+def extract_engine_info(component: str) -> str | None:
+    """
+    Extract engine information from a component name.
+
+    Args:
+        component: Component name like 'database[sqlite]' or 'scheduler'
+
+    Returns:
+        Engine name or None if not specified
+
+    Examples:
+        extract_engine_info('database[sqlite]') -> 'sqlite'
+        extract_engine_info('scheduler') -> None
+        extract_engine_info('database[]') -> None
+    """
+    _, engine = parse_component_name(component)
+    return engine
+
+
+def format_component_with_engine(base: str, engine: str | None) -> str:
+    """
+    Format a component name with engine information.
+
+    Args:
+        base: Base component name
+        engine: Engine name or None
+
+    Returns:
+        Formatted component name
+
+    Examples:
+        format_component_with_engine('database', 'sqlite') -> 'database[sqlite]'
+        format_component_with_engine('scheduler', None) -> 'scheduler'
+    """
+    if not base or not isinstance(base, str):
+        raise ValueError(
+            f"Base component name must be a non-empty string, got: {base!r}"
+        )
+
+    base = base.strip()
+    if not base:
+        raise ValueError("Base component name cannot be empty or whitespace")
+
+    if engine is not None:
+        if not isinstance(engine, str) or not engine.strip():
+            raise ValueError(f"Engine must be a non-empty string, got: {engine!r}")
+        return f"{base}[{engine.strip()}]"
+
+    return base
+
+
+def clean_component_names(components: list[str]) -> list[str]:
+    """
+    Extract base component names from a list, removing engine information.
+
+    Args:
+        components: List of component names (some may have engine info)
+
+    Returns:
+        List of base component names
+
+    Examples:
+        clean_component_names(['redis', 'database[sqlite]']) -> ['redis', 'database']
+    """
+    return [extract_base_component_name(comp) for comp in components]
+
+
+def restore_engine_info(
+    resolved_components: list[str], original_components: list[str]
+) -> list[str]:
+    """
+    Restore engine information from original components to resolved components.
+
+    This function matches resolved base component names with their original
+    engine-specific versions and restores the engine information.
+
+    Args:
+        resolved_components: List of resolved base component names
+        original_components: List of original components with engine info
+
+    Returns:
+        List with engine information restored where applicable
+
+    Examples:
+        resolved = ['redis', 'database', 'scheduler']
+        original = ['database[sqlite]', 'scheduler']
+        restore_engine_info(resolved, original)
+        -> ['redis', 'database[sqlite]', 'scheduler']
+    """
+    # Build mapping of base names to original components with engine info
+    engine_mapping: dict[str, str] = {}
+    for orig in original_components:
+        base_name = extract_base_component_name(orig)
+        if base_name != orig:  # Has engine info
+            engine_mapping[base_name] = orig
+
+    # Restore engine info where available
+    result = []
+    for comp in resolved_components:
+        if comp in engine_mapping:
+            result.append(engine_mapping[comp])
+        else:
+            result.append(comp)
+
+    return result
+
+
+def find_components_with_engine(components: list[str], base_name: str) -> list[str]:
+    """
+    Find all components that match a base name (with or without engine info).
+
+    Args:
+        components: List of component names to search
+        base_name: Base component name to match
+
+    Returns:
+        List of matching components
+
+    Examples:
+        components = ['redis', 'database[sqlite]', 'database[postgres]', 'scheduler']
+        find_components_with_engine(components, 'database')
+        -> ['database[sqlite]', 'database[postgres]']
+    """
+    matches = []
+    for comp in components:
+        if extract_base_component_name(comp) == base_name:
+            matches.append(comp)
+    return matches
+
+
+def has_engine_info(component: str) -> bool:
+    """
+    Check if a component name includes engine information.
+
+    Args:
+        component: Component name to check
+
+    Returns:
+        True if component has engine info, False otherwise
+
+    Examples:
+        has_engine_info('database[sqlite]') -> True
+        has_engine_info('scheduler') -> False
+    """
+    return extract_engine_info(component) is not None

aegis/core/components.py

@@ -0,0 +1,127 @@
+"""
+Component registry and specifications for Aegis Stack.
+
+This module defines all available components, their dependencies, and metadata
+used for project generation and validation.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ComponentType(Enum):
+    """Component type classifications."""
+
+    CORE = "core"  # Always included (backend, frontend)
+    INFRASTRUCTURE = "infra"  # Redis, workers - foundation for services to use
+
+
+class SchedulerBackend(str, Enum):
+    """Scheduler backend options for task persistence."""
+
+    MEMORY = "memory"  # In-memory (no persistence, default)
+    SQLITE = "sqlite"  # SQLite database (requires database component)
+    POSTGRES = "postgres"  # PostgreSQL (future support)
+
+
+# Core components that are always included in every project
+CORE_COMPONENTS = ["backend", "frontend"]
+
+
+@dataclass
+class ComponentSpec:
+    """Specification for a single component."""
+
+    name: str
+    type: ComponentType
+    description: str
+    requires: list[str] | None = None  # Hard dependencies
+    recommends: list[str] | None = None  # Soft dependencies
+    conflicts: list[str] | None = None  # Mutual exclusions
+    docker_services: list[str] | None = None
+    pyproject_deps: list[str] | None = None
+    template_files: list[str] | None = None
+
+    def __post_init__(self) -> None:
+        """Ensure all list fields are initialized."""
+        if self.requires is None:
+            self.requires = []
+        if self.recommends is None:
+            self.recommends = []
+        if self.conflicts is None:
+            self.conflicts = []
+        if self.docker_services is None:
+            self.docker_services = []
+        if self.pyproject_deps is None:
+            self.pyproject_deps = []
+        if self.template_files is None:
+            self.template_files = []
+
+
+# Component registry - single source of truth
+COMPONENTS: dict[str, ComponentSpec] = {
+    "backend": ComponentSpec(
+        name="backend",
+        type=ComponentType.CORE,
+        description="FastAPI backend server",
+        pyproject_deps=["fastapi==0.116.1", "uvicorn==0.35.0"],
+        template_files=["app/components/backend/"],
+    ),
+    "frontend": ComponentSpec(
+        name="frontend",
+        type=ComponentType.CORE,
+        description="Flet frontend interface",
+        pyproject_deps=["flet==0.28.3"],
+        template_files=["app/components/frontend/"],
+    ),
+    "redis": ComponentSpec(
+        name="redis",
+        type=ComponentType.INFRASTRUCTURE,
+        description="Redis cache and message broker",
+        docker_services=["redis"],
+        pyproject_deps=["redis==5.0.8"],
+    ),
+    "worker": ComponentSpec(
+        name="worker",
+        type=ComponentType.INFRASTRUCTURE,
+        description="Background task processing infrastructure with arq",
+        requires=["redis"],  # Hard dependency
+        pyproject_deps=["arq==0.25.0"],
+        docker_services=["worker-system", "worker-load-test"],
+        template_files=["app/components/worker/"],
+    ),
+    "scheduler": ComponentSpec(
+        name="scheduler",
+        type=ComponentType.INFRASTRUCTURE,
+        description="Scheduled task execution infrastructure",
+        pyproject_deps=["apscheduler==3.10.4"],
+        docker_services=["scheduler"],
+        template_files=["app/components/scheduler.py", "app/entrypoints/scheduler.py"],
+    ),
+    "database": ComponentSpec(
+        name="database",
+        type=ComponentType.INFRASTRUCTURE,
+        description="SQLite database with SQLModel ORM",
+        pyproject_deps=["sqlmodel>=0.0.14", "sqlalchemy>=2.0.0", "aiosqlite>=0.19.0"],
+        template_files=["app/core/db.py"],
+    ),
+}
+
+
+def get_component(name: str) -> ComponentSpec:
+    """Get component specification by name."""
+    if name not in COMPONENTS:
+        raise ValueError(f"Unknown component: {name}")
+    return COMPONENTS[name]
+
+
+def get_components_by_type(component_type: ComponentType) -> dict[str, ComponentSpec]:
+    """Get all components of a specific type."""
+    return {
+        name: spec for name, spec in COMPONENTS.items() if spec.type == component_type
+    }
+
+
+def list_available_components() -> list[str]:
+    """Get list of all available component names."""
+    return list(COMPONENTS.keys())

aegis/core/copier_manager.py

@@ -0,0 +1,315 @@
+"""
+Copier template engine integration.
+
+This module provides Copier template generation functionality alongside
+the existing Cookiecutter engine. It's designed to maintain feature parity
+during the migration period.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from copier import run_copy, run_update
+
+from .post_gen_tasks import cleanup_components, run_post_generation_tasks
+from .template_generator import TemplateGenerator
+
+
+def generate_with_copier(template_gen: TemplateGenerator, output_dir: Path) -> Path:
+    """
+    Generate project using Copier template engine.
+
+    Args:
+        template_gen: Template generator with project configuration
+        output_dir: Directory to create the project in
+
+    Returns:
+        Path to the generated project
+
+    Note:
+        This function uses the Copier template which is currently incomplete
+        (missing conditional _exclude patterns). Projects will include all
+        components regardless of selection until template is fixed.
+    """
+    import subprocess
+
+    # Get cookiecutter context from template generator
+    cookiecutter_context = template_gen.get_template_context()
+
+    # Convert cookiecutter context to Copier data format
+    # Copier uses boolean values instead of "yes"/"no" strings
+    copier_data = {
+        "project_name": cookiecutter_context["project_name"],
+        "project_slug": cookiecutter_context["project_slug"],
+        "project_description": cookiecutter_context.get(
+            "project_description",
+            "A production-ready async Python application built with Aegis Stack",
+        ),
+        "author_name": cookiecutter_context.get("author_name", "Your Name"),
+        "author_email": cookiecutter_context.get(
+            "author_email", "your.email@example.com"
+        ),
+        "github_username": cookiecutter_context.get("github_username", "your-username"),
+        "version": cookiecutter_context.get("version", "0.1.0"),
+        "python_version": cookiecutter_context.get("python_version", "3.11"),
+        # Convert yes/no strings to booleans
+        "include_scheduler": cookiecutter_context["include_scheduler"] == "yes",
+        "scheduler_backend": cookiecutter_context["scheduler_backend"],
+        "scheduler_with_persistence": cookiecutter_context["scheduler_with_persistence"]
+        == "yes",
+        "include_worker": cookiecutter_context["include_worker"] == "yes",
+        "include_redis": cookiecutter_context["include_redis"] == "yes",
+        "include_database": cookiecutter_context["include_database"] == "yes",
+        "include_cache": False,  # Default to no
+        "include_auth": cookiecutter_context.get("include_auth", "no") == "yes",
+        "include_ai": cookiecutter_context.get("include_ai", "no") == "yes",
+        "ai_providers": cookiecutter_context.get("ai_providers", "openai"),
+    }
+
+    # Get copier template path - point directly at template directory
+    # This prevents copying aegis-stack repo files into generated projects
+    # The repo root path is set later in .copier-answers.yml for git-aware updates
+    template_path = Path(__file__).parent.parent / "templates" / "copier-aegis-project"
+
+    # Generate project - Copier creates the project_slug directory automatically
+    # NOTE: _tasks removed from copier.yml - we run them ourselves below
+    run_copy(
+        str(
+            template_path
+        ),  # Use template directory (not repo root) to avoid copying extra files
+        output_dir,
+        data=copier_data,
+        defaults=True,  # Use template defaults, overridden by our explicit data
+        unsafe=False,  # No tasks in copier.yml anymore - we run them ourselves
+        vcs_ref=None,  # Don't use git for template versioning - prevents git submodule errors in CI
+    )
+
+    # Copier creates the project in output_dir/project_slug
+    project_path = output_dir / cookiecutter_context["project_slug"]
+
+    # Clean up unwanted component files based on selection
+    # This must happen BEFORE post-generation tasks (which run linting on the remaining files)
+    cleanup_components(project_path, copier_data)
+
+    # Run post-generation tasks with explicit working directory control
+    # This ensures consistent behavior with Cookiecutter
+    include_auth = copier_data.get("include_auth", False)
+    run_post_generation_tasks(project_path, include_auth=include_auth)
+
+    # Initialize git repository for Copier updates
+    # Copier requires a git-tracked project to perform updates
+
+    try:
+        # Configure git user in case CI environment doesn't have it set
+        # This is needed for commits to work in CI
+        subprocess.run(
+            ["git", "config", "user.name", "Aegis Stack"],
+            cwd=project_path,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["git", "config", "user.email", "noreply@aegis-stack.dev"],
+            cwd=project_path,
+            capture_output=True,
+        )
+
+        subprocess.run(
+            ["git", "init"],
+            cwd=project_path,
+            check=True,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["git", "add", "."],
+            cwd=project_path,
+            check=True,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["git", "commit", "-m", "Initial commit from Aegis Stack"],
+            cwd=project_path,
+            check=True,
+            capture_output=True,
+        )
+        print("✅ Git repository initialized")
+    except subprocess.CalledProcessError as e:
+        print(f"⚠️  Failed to initialize git repository: {e}")
+        print("💡 Run 'git init && git add . && git commit' manually")
+
+    # CRITICAL: Update .copier-answers.yml for future updates to work
+    # We need to:
+    # 1. Store git commit hash (_commit) - tells Copier which template version was used
+    # 2. Update template path (_src_path) - point to repo root, not subdirectory
+    #    (repo root has .git so Copier can detect version changes)
+    try:
+        # Get current commit hash from aegis-stack repo
+        template_root = Path(__file__).parent.parent.parent
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=template_root,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        commit_hash = result.stdout.strip()
+
+        # Update .copier-answers.yml with commit hash AND repo root path
+        answers_file = project_path / ".copier-answers.yml"
+        if answers_file.exists():
+            with open(answers_file) as f:
+                answers = yaml.safe_load(f)
+
+            # Update _commit field (was None, now has actual hash)
+            answers["_commit"] = commit_hash
+
+            # Update _src_path to point to repo root (where .git exists)
+            # The copier.yml at repo root has _subdirectory setting to find actual template
+            answers["_src_path"] = str(template_root)
+
+            with open(answers_file, "w") as f:
+                yaml.safe_dump(answers, f, default_flow_style=False, sort_keys=False)
+
+            # Commit the updated .copier-answers.yml
+            try:
+                subprocess.run(
+                    ["git", "add", ".copier-answers.yml"],
+                    cwd=project_path,
+                    check=True,
+                    capture_output=True,
+                )
+                subprocess.run(
+                    [
+                        "git",
+                        "commit",
+                        "-m",
+                        "Update .copier-answers.yml with template version",
+                    ],
+                    cwd=project_path,
+                    check=True,
+                    capture_output=True,
+                )
+            except subprocess.CalledProcessError:
+                # If commit fails (e.g., no changes), that's OK
+                pass
+
+    except Exception:
+        # If we can't get commit hash, that's OK - updates won't work but
+        # project generation succeeded. This can happen in non-git environments.
+        pass
+
+    return project_path
+
+
+def is_copier_project(project_path: Path) -> bool:
+    """
+    Check if a project was generated with Copier.
+
+    Args:
+        project_path: Path to the project directory
+
+    Returns:
+        True if project has .copier-answers.yml file
+    """
+    answers_file = project_path / ".copier-answers.yml"
+    return answers_file.exists()
+
+
+def load_copier_answers(project_path: Path) -> dict[str, Any]:
+    """
+    Load existing Copier answers from a project.
+
+    Args:
+        project_path: Path to the project directory
+
+    Returns:
+        Dictionary of Copier answers
+
+    Raises:
+        FileNotFoundError: If .copier-answers.yml doesn't exist
+        yaml.YAMLError: If answers file is corrupted
+    """
+    answers_file = project_path / ".copier-answers.yml"
+
+    if not answers_file.exists():
+        raise FileNotFoundError(
+            f"No .copier-answers.yml found in {project_path}. "
+            "This doesn't appear to be a Copier-generated project."
+        )
+
+    try:
+        with open(answers_file) as f:
+            answers = yaml.safe_load(f)
+            if answers is None:
+                return {}
+            return answers
+    except yaml.YAMLError as e:
+        raise yaml.YAMLError(f"Failed to parse .copier-answers.yml: {e}") from e
+
+
+def update_with_copier(
+    project_path: Path,
+    additional_data: dict[str, Any] | None = None,
+    conflict_mode: str = "rej",
+) -> None:
+    """
+    Update an existing Copier-generated project with new data.
+
+    This function uses Copier's update mechanism to add new components
+    or update existing project configuration.
+
+    Args:
+        project_path: Path to the existing project directory
+        additional_data: New data to merge (e.g., {"include_scheduler": True})
+        conflict_mode: How to handle conflicts - "rej" (separate files) or "inline" (markers)
+
+    Raises:
+        FileNotFoundError: If project doesn't have .copier-answers.yml
+        Exception: If Copier update fails
+
+    Example:
+        # Add scheduler component to existing project
+        update_with_copier(
+            Path("my-project"),
+            {"include_scheduler": True, "scheduler_backend": "memory"}
+        )
+    """
+    # Validate it's a Copier project
+    if not is_copier_project(project_path):
+        raise FileNotFoundError(
+            f"Project at {project_path} was not generated with Copier.\n"
+            f"The 'aegis add' command only works with Copier-generated projects.\n"
+            f"To add components, regenerate the project with the new components included."
+        )
+
+    # Load existing answers to validate state
+    try:
+        load_copier_answers(project_path)
+    except yaml.YAMLError as e:
+        raise Exception(
+            f"Failed to read project configuration: {e}\n"
+            f"The .copier-answers.yml file may be corrupted."
+        ) from e
+
+    # Prepare update data
+    update_data = additional_data or {}
+
+    # Run Copier update
+    # NOTE: We do NOT pass src_path - Copier will read it from .copier-answers.yml
+    # This is the key to making updates work!
+    try:
+        run_update(
+            dst_path=str(project_path),
+            data=update_data,
+            defaults=True,  # Use existing answers as defaults
+            overwrite=True,  # Allow overwriting files
+            conflict=conflict_mode,  # How to handle conflicts
+            unsafe=True,  # Allow running tasks (uv sync, make fix)
+            vcs_ref="HEAD",  # Use latest template (no versioning needed yet)
+        )
+    except Exception as e:
+        raise Exception(
+            f"Failed to update project: {e}\n"
+            f"This may be due to conflicts with manually modified files.\n"
+            f"Check for .rej files in the project directory for details."
+        ) from e