moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/core/template_engine.py

@@ -4,8 +4,11 @@ Template engine for parameterizing GitHub templates and other configuration file
 Supports Jinja2-style templating with variable substitution and conditional sections.
 Enables users to customize MoAI-ADK templates for their own projects.
 
+Performance: Jinja2 Environment instances are cached to avoid recreation overhead
+(40-60ms per render → ~1ms after caching).
 """
 
+from functools import lru_cache
 from pathlib import Path
 from typing import Any, Dict, Optional
 
@@ -20,6 +23,49 @@ from jinja2 import (
 )
 
 
+# Module-level cached Environment factory functions
+@lru_cache(maxsize=2)
+def _get_string_environment(strict: bool) -> Environment:
+    """
+    Get cached Jinja2 Environment for string rendering.
+
+    Args:
+        strict: If True, raise error on undefined variables
+
+    Returns:
+        Cached Environment instance
+
+    Performance: Cached to avoid Environment recreation overhead
+    """
+    return Environment(
+        undefined=StrictUndefined if strict else Undefined,
+        trim_blocks=False,
+        lstrip_blocks=False,
+    )
+
+
+@lru_cache(maxsize=8)
+def _get_file_environment(template_dir: str, strict: bool) -> Environment:
+    """
+    Get cached Jinja2 Environment for file rendering.
+
+    Args:
+        template_dir: Template directory path (string for hashability)
+        strict: If True, raise error on undefined variables
+
+    Returns:
+        Cached Environment instance with FileSystemLoader
+
+    Performance: Cached to avoid Environment recreation overhead
+    """
+    return Environment(
+        loader=FileSystemLoader(template_dir),
+        undefined=StrictUndefined if strict else Undefined,
+        trim_blocks=False,
+        lstrip_blocks=False,
+    )
+
+
 class TemplateEngine:
     """
     Jinja2-based template engine for MoAI-ADK configuration and GitHub templates.
@@ -59,13 +105,12 @@ class TemplateEngine:
         Raises:
             TemplateSyntaxError: If template syntax is invalid
             TemplateRuntimeError: If variable substitution fails in strict mode
+
+        Performance: Uses cached Environment instance (40-60ms → ~1ms)
         """
         try:
-            env = Environment(
-                undefined=self.undefined_behavior,
-                trim_blocks=False,
-                lstrip_blocks=False,
-            )
+            # Use cached Environment instead of creating new one
+            env = _get_string_environment(strict=self.strict_undefined)
             template = env.from_string(template_string)
             return template.render(**variables)
         except (TemplateSyntaxError, TemplateRuntimeError) as e:
@@ -92,6 +137,8 @@ class TemplateEngine:
             FileNotFoundError: If template file doesn't exist
             TemplateSyntaxError: If template syntax is invalid
             TemplateRuntimeError: If variable substitution fails in strict mode
+
+        Performance: Uses cached Environment instance (40-60ms → ~1ms)
         """
         if not template_path.exists():
             raise FileNotFoundError(f"Template file not found: {template_path}")
@@ -100,12 +147,8 @@ class TemplateEngine:
         template_name = template_path.name
 
         try:
-            env = Environment(
-                loader=FileSystemLoader(str(template_dir)),
-                undefined=self.undefined_behavior,
-                trim_blocks=False,
-                lstrip_blocks=False,
-            )
+            # Use cached Environment instead of creating new one
+            env = _get_file_environment(template_dir=str(template_dir), strict=self.strict_undefined)
             template = env.get_template(template_name)
             rendered = template.render(**variables)
 
@@ -115,9 +158,7 @@ class TemplateEngine:
 
             return rendered
         except TemplateNotFound:
-            raise FileNotFoundError(
-                f"Template not found in {template_dir}: {template_name}"
-            )
+            raise FileNotFoundError(f"Template not found in {template_dir}: {template_name}")
         except (TemplateSyntaxError, TemplateRuntimeError) as e:
             raise RuntimeError(f"Template rendering error in {template_path}: {e}")
 
@@ -168,12 +209,22 @@ class TemplateEngine:
         Extract template variables from project configuration.
 
         Args:
-            config: Project configuration dictionary (from .moai/config/config.json)
+            config: Project configuration dictionary (from section YAML files
+                   or legacy .moai/config/config.json)
+
+        Configuration sources (in priority order):
+        1. Section YAML files: .moai/config/sections/*.yaml
+           - project.yaml: Project settings (name, description, owner)
+           - language.yaml: Language settings
+           - user.yaml: User settings
+           - system.yaml: MoAI/GitHub settings
+        2. Legacy: .moai/config/config.json
 
         Returns:
             Dictionary of template variables
         """
-        github_config = config.get("github", {}).get("templates", {})
+        github_templates_config = config.get("github", {}).get("templates", {})
+        github_config = config.get("github", {})
         project_config = config.get("project", {})
         user_config = config.get("user", {})
 
@@ -181,28 +232,23 @@ class TemplateEngine:
             # Project information
             "PROJECT_NAME": project_config.get("name", "MyProject"),
             "PROJECT_DESCRIPTION": project_config.get("description", ""),
-            "PROJECT_OWNER": project_config.get("owner", ""),
+            "PROJECT_OWNER": project_config.get("owner", ""),  # GitHub username (project owner)
+            "GITHUB_PROFILE_NAME": github_config.get("profile_name", ""),
             "PROJECT_MODE": project_config.get("mode", "team"),  # team or personal
             "CODEBASE_LANGUAGE": project_config.get("codebase_language", "python"),
             # User information
             "USER_NAME": user_config.get("name", ""),
             # Directory structure
-            "SPEC_DIR": github_config.get("spec_directory", ".moai/specs"),
-            "DOCS_DIR": github_config.get("docs_directory", ".moai/docs"),
-            "TEST_DIR": github_config.get("test_directory", "tests"),
+            "SPEC_DIR": github_templates_config.get("spec_directory", ".moai/specs"),
+            "DOCS_DIR": github_templates_config.get("docs_directory", ".moai/docs"),
+            "TEST_DIR": github_templates_config.get("test_directory", "tests"),
             # Feature flags
             "ENABLE_TRUST_5": github_config.get("enable_trust_5", True),
-            "ENABLE_ALFRED_COMMANDS": github_config.get("enable_alfred_commands", True),
+            "ENABLE_ALFRED_COMMANDS": github_templates_config.get("enable_alfred_commands", True),
             # Language configuration
-            "CONVERSATION_LANGUAGE": config.get("language", {}).get(
-                "conversation_language", "en"
-            ),
-            "CONVERSATION_LANGUAGE_NAME": config.get("language", {}).get(
-                "conversation_language_name", "English"
-            ),
-            "AGENT_PROMPT_LANGUAGE": config.get("language", {}).get(
-                "agent_prompt_language", "english"
-            ),
+            "CONVERSATION_LANGUAGE": config.get("language", {}).get("conversation_language", "en"),
+            "CONVERSATION_LANGUAGE_NAME": config.get("language", {}).get("conversation_language_name", "English"),
+            "AGENT_PROMPT_LANGUAGE": config.get("language", {}).get("agent_prompt_language", "english"),
             # Additional metadata
             "MOAI_VERSION": config.get("moai", {}).get("version", "0.7.0"),
         }
@@ -253,25 +299,21 @@ class TemplateVariableValidator:
                 errors.append(f"Missing required variable: {var_name}")
             elif not isinstance(variables[var_name], var_type):
                 actual_type = type(variables[var_name]).__name__
-                errors.append(
-                    f"Invalid type for {var_name}: "
-                    f"expected {var_type.__name__}, got {actual_type}"
-                )
+                errors.append(f"Invalid type for {var_name}: expected {var_type.__name__}, got {actual_type}")
 
         # Check optional variables (if present)
         for var_name, var_type in cls.OPTIONAL_VARIABLES.items():
             if var_name in variables:
                 if not isinstance(variables[var_name], var_type):
                     if isinstance(var_type, tuple):
-                        type_names = " or ".join(
-                            getattr(t, "__name__", str(t)) for t in var_type
-                        )
+                        type_names = (
+                            " or ".join(getattr(t, "__name__", str(t)) for t in var_type)
+                            if var_type is not None
+                            else "unknown"
+                        )  # type: ignore[union-attr]
                     else:
                         type_names = getattr(var_type, "__name__", str(var_type))
                     actual_type = type(variables[var_name]).__name__
-                    errors.append(
-                        f"Invalid type for {var_name}: "
-                        f"expected {type_names}, got {actual_type}"
-                    )
+                    errors.append(f"Invalid type for {var_name}: expected {type_names}, got {actual_type}")
 
         return len(errors) == 0, errors

moai_adk/core/template_variable_synchronizer.py

@@ -0,0 +1,431 @@
+"""
+Template Variable Synchronizer for MoAI-ADK
+
+Handles synchronization of template variables when configuration is updated
+through /moai:0-project command or other configuration management operations.
+
+This module ensures that when language or user settings change, all template
+variables in the system are properly updated to reflect the new configuration.
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .language_config_resolver import get_resolver
+
+
+class TemplateVariableSynchronizer:
+    """
+    Synchronizes template variables across the MoAI-ADK system when configuration changes.
+
+    Responsible for:
+    - Detecting template variables that need updating
+    - Re-substituting variables in affected files
+    - Maintaining consistency between config and template files
+    - Tracking template variable usage across the project
+    """
+
+    # Template variable patterns to track and synchronize
+    TEMPLATE_PATTERNS = {
+        r"\{\{CONVERSATION_LANGUAGE\}\}",
+        r"\{\{CONVERSATION_LANGUAGE_NAME\}\}",
+        r"\{\{AGENT_PROMPT_LANGUAGE\}\}",
+        r"\{\{USER_NAME\}\}",
+        r"\{\{PERSONALIZED_GREETING\}\}",
+        r"\{\{LANGUAGE_CONFIG_SOURCE\}\}",
+    }
+
+    # Files that typically contain template variables
+    TEMPLATE_TRACKING_PATTERNS = [
+        ".claude/settings.json",
+        ".claude/settings.local.json",
+        ".moai/config/sections/*.yaml",  # Section YAML files (new)
+        ".moai/config/config.json",  # Legacy config.json (fallback)
+        ".claude/output-styles/**/*.md",
+        ".claude/hooks/**/*.py",
+        ".claude/commands/**/*.md",
+        ".claude/skills/**/*.md",
+        "CLAUDE.md",
+        "README.md",
+    ]
+
+    def __init__(self, project_root: str):
+        """
+        Initialize the synchronizer.
+
+        Args:
+            project_root: Root directory of the MoAI-ADK project
+        """
+        self.project_root = Path(project_root)
+        self.language_resolver = get_resolver(project_root)
+
+    def synchronize_after_config_change(self, changed_config_path: Optional[Path] = None) -> Dict[str, Any]:
+        """
+        Synchronize template variables after configuration changes.
+
+        Args:
+            changed_config_path: Path to the configuration file that was changed
+                                 (None if unknown or multiple files changed)
+
+        Returns:
+            Dictionary containing synchronization results
+        """
+        results: Dict[str, Any] = {
+            "files_updated": 0,
+            "variables_updated": [],
+            "errors": [],
+            "sync_status": "completed",
+        }
+
+        try:
+            # Get current resolved configuration
+            current_config = self.language_resolver.resolve_config(force_refresh=True)
+            template_vars = self.language_resolver.export_template_variables(current_config)
+
+            # Find files that need updating
+            files_to_update = self._find_files_with_template_variables(changed_config_path)
+
+            # Update each file
+            for file_path in files_to_update:
+                try:
+                    updated_vars = self._update_file_template_variables(file_path, template_vars)
+                    if updated_vars:
+                        files_updated: int = results["files_updated"]  # type: ignore[assignment]
+                        results["files_updated"] = files_updated + 1
+                        variables_updated: List[str] = results["variables_updated"]  # type: ignore[assignment]
+                        variables_updated.extend(updated_vars)
+
+                except Exception as e:
+                    error_msg = f"Failed to update {file_path}: {str(e)}"
+                    errors: List[str] = results["errors"]  # type: ignore[assignment]
+                    errors.append(error_msg)
+
+            # Special handling for certain file types
+            self._handle_special_file_updates(template_vars, results)
+
+        except Exception as e:
+            results["sync_status"] = "failed"
+            errors_list: List[str] = results["errors"]  # type: ignore[assignment]
+            errors_list.append(f"Synchronization failed: {str(e)}")
+
+        return results
+
+    def _find_files_with_template_variables(self, changed_config_path: Optional[Path]) -> List[Path]:
+        """
+        Find files that contain template variables and might need updating.
+
+        Args:
+            changed_config_path: Specific config file that changed, if known
+
+        Returns:
+            List of file paths that contain template variables
+        """
+        files_with_variables = []
+
+        # If a specific config file changed, prioritize files that depend on it
+        if changed_config_path:
+            dependency_map = {
+                # Section YAML file dependencies (new approach)
+                ".moai/config/sections/language.yaml": [
+                    ".claude/settings.json",
+                    ".claude/settings.local.json",
+                    ".claude/output-styles",
+                    ".claude/hooks",
+                ],
+                ".moai/config/sections/user.yaml": [
+                    ".claude/settings.json",
+                    ".claude/settings.local.json",
+                    ".claude/output-styles",
+                ],
+                # Legacy config.json dependencies (fallback)
+                ".moai/config/config.json": [
+                    ".claude/settings.json",
+                    ".claude/settings.local.json",
+                    ".claude/output-styles",
+                    ".claude/hooks",
+                ],
+            }
+
+            config_key = str(changed_config_path.relative_to(self.project_root))
+            if config_key in dependency_map:
+                for pattern in dependency_map[config_key]:
+                    files_with_variables.extend(self._glob_files(pattern))
+
+        # Always check common template files
+        common_patterns = [
+            ".claude/settings.json",
+            ".claude/settings.local.json",
+            ".claude/output-styles/**/*.md",
+            "CLAUDE.md",
+        ]
+
+        for pattern in common_patterns:
+            files_with_variables.extend(self._glob_files(pattern))
+
+        # Remove duplicates and sort
+        files_with_variables = list(set(files_with_variables))
+        files_with_variables.sort()
+
+        return [f for f in files_with_variables if f.exists() and f.is_file()]
+
+    def _glob_files(self, pattern: str) -> List[Path]:
+        """
+        Glob files matching a pattern.
+
+        Args:
+            pattern: Glob pattern (supports ** for recursive matching)
+
+        Returns:
+            List of matching file paths
+        """
+        try:
+            return list(self.project_root.glob(pattern))
+        except (OSError, ValueError):
+            return []
+
+    def _update_file_template_variables(self, file_path: Path, template_vars: Dict[str, str]) -> List[str]:
+        """
+        Update template variables in a specific file.
+
+        Args:
+            file_path: Path to the file to update
+            template_vars: Dictionary of template variables to substitute
+
+        Returns:
+            List of variable names that were updated in this file
+        """
+        if not file_path.exists():
+            return []
+
+        try:
+            content = file_path.read_text(encoding="utf-8")
+            original_content = content
+
+            # Track which variables were updated
+            updated_vars = []
+
+            # Apply each template variable substitution
+            for var_name, var_value in template_vars.items():
+                # Look for {{VARIABLE_NAME}} pattern
+                pattern = re.compile(r"\{\{" + re.escape(var_name) + r"\}\}")
+
+                if pattern.search(content):
+                    content = pattern.sub(var_value, content)
+                    updated_vars.append(var_name)
+
+            # Only write if content changed
+            if content != original_content:
+                file_path.write_text(content, encoding="utf-8")
+
+            return updated_vars
+
+        except (OSError, UnicodeDecodeError, UnicodeEncodeError):
+            # File read/write errors - skip this file
+            return []
+
+    def _handle_special_file_updates(self, template_vars: Dict[str, str], results: Dict[str, Any]) -> None:
+        """
+        Handle special cases for certain file types.
+
+        Args:
+            template_vars: Dictionary of template variables
+            results: Results dictionary to update
+        """
+        # Handle settings.json environment variables section
+        settings_file = self.project_root / ".claude" / "settings.json"
+        if settings_file.exists():
+            try:
+                self._update_settings_env_vars(settings_file, template_vars, results)
+            except Exception as e:
+                results["errors"].append(f"Failed to update settings.json env vars: {str(e)}")
+
+    def _update_settings_env_vars(
+        self,
+        settings_file: Path,
+        template_vars: Dict[str, str],
+        results: Dict[str, Any],
+    ) -> None:
+        """
+        Update the environment variables section in settings.json.
+
+        Args:
+            settings_file: Path to settings.json
+            template_vars: Template variables to use for env values
+            results: Results dictionary to update
+        """
+        try:
+            settings_data = json.loads(settings_file.read_text(encoding="utf-8"))
+
+            # Define environment variable mappings
+            env_mappings = {
+                "CONVERSATION_LANGUAGE": "MOAI_CONVERSATION_LANG",
+                "AGENT_PROMPT_LANGUAGE": "MOAI_AGENT_PROMPT_LANG",
+                "CONVERSATION_LANGUAGE_NAME": "MOAI_CONVERSATION_LANG_NAME",
+                "USER_NAME": "MOAI_USER_NAME",
+                "LANGUAGE_CONFIG_SOURCE": "MOAI_CONFIG_SOURCE",
+            }
+
+            # Update or create env section
+            if "env" not in settings_data:
+                settings_data["env"] = {}
+
+            updated_vars = []
+            for template_var, env_var in env_mappings.items():
+                if template_var in template_vars:
+                    old_value = settings_data["env"].get(env_var)
+                    new_value = template_vars[template_var]
+
+                    if old_value != new_value:
+                        settings_data["env"][env_var] = new_value
+                        updated_vars.append(f"{env_var}: {old_value} → {new_value}")
+
+            # Write back if changed
+            if updated_vars:
+                settings_file.write_text(
+                    json.dumps(settings_data, indent=2, ensure_ascii=False) + "\n",
+                    encoding="utf-8",
+                )
+                results["files_updated"] += 1
+                results["variables_updated"].extend(updated_vars)
+
+        except (json.JSONDecodeError, OSError, UnicodeDecodeError, UnicodeEncodeError):
+            # Skip if settings.json is malformed or can't be accessed
+            pass
+
+    def validate_template_variable_consistency(self) -> Dict[str, Any]:
+        """
+        Validate that template variables are consistent across the project.
+
+        Returns:
+            Dictionary containing validation results
+        """
+        validation_results = {
+            "status": "passed",
+            "inconsistencies": [],
+            "total_files_checked": 0,
+            "files_with_variables": 0,
+        }
+
+        try:
+            # Get current template variables
+            current_config = self.language_resolver.resolve_config()
+            current_vars = self.language_resolver.export_template_variables(current_config)
+
+            # Check files for template variable consistency
+            files_with_variables = self._find_files_with_template_variables(None)
+            validation_results["total_files_checked"] = len(files_with_variables)
+
+            for file_path in files_with_variables:
+                try:
+                    content = file_path.read_text(encoding="utf-8")
+                    file_inconsistencies: List[str] = []
+
+                    # Check each template variable
+                    for var_name, expected_value in current_vars.items():
+                        pattern = re.compile(r"\{\{" + re.escape(var_name) + r"\}\}")
+
+                        if pattern.search(content):
+                            files_with_vars: int = validation_results["files_with_variables"]  # type: ignore[assignment]
+                            validation_results["files_with_variables"] = files_with_vars + 1
+                            # Variable found but not substituted - this might be expected
+                            # Only report as inconsistency if we expect it to be substituted
+                            pass
+
+                    if file_inconsistencies:
+                        inconsistencies: List[Dict[str, Any]] = validation_results["inconsistencies"]  # type: ignore[assignment]
+                        inconsistencies.append(
+                            {
+                                "file": str(file_path.relative_to(self.project_root)),
+                                "issues": file_inconsistencies,
+                            }
+                        )
+
+                except (OSError, UnicodeDecodeError):
+                    # Skip files that can't be read
+                    continue
+
+            if validation_results["inconsistencies"]:
+                validation_results["status"] = "warning"
+
+        except Exception as e:
+            validation_results["status"] = "failed"
+            validation_results["error"] = str(e)
+
+        return validation_results
+
+    def get_template_variable_usage_report(self) -> Dict[str, Any]:
+        """
+        Generate a report of template variable usage across the project.
+
+        Returns:
+            Dictionary containing template variable usage statistics
+        """
+        usage_report = {
+            "total_files_with_variables": 0,
+            "variable_usage": {},
+            "files_by_variable": {},
+            "unsubstituted_variables": [],
+        }
+
+        try:
+            files_with_variables = self._find_files_with_template_variables(None)
+            usage_report["total_files_with_variables"] = len(files_with_variables)
+
+            for file_path in files_with_variables:
+                try:
+                    content = file_path.read_text(encoding="utf-8")
+                    relative_path = str(file_path.relative_to(self.project_root))
+
+                    # Check for each template variable pattern
+                    for pattern_str in self.TEMPLATE_PATTERNS:
+                        pattern = re.compile(pattern_str)
+                        matches = pattern.findall(content)
+
+                        if matches:
+                            var_name = pattern_str.strip(r"{}")
+                            variable_usage: Dict[str, int] = usage_report["variable_usage"]  # type: ignore[assignment]
+                            files_by_variable: Dict[str, List[str]] = usage_report["files_by_variable"]  # type: ignore[assignment]
+                            unsubstituted_variables: List[Dict[str, Any]] = usage_report["unsubstituted_variables"]  # type: ignore[assignment]
+
+                            if var_name not in variable_usage:
+                                variable_usage[var_name] = 0
+                                files_by_variable[var_name] = []
+
+                            variable_usage[var_name] += len(matches)
+                            files_by_variable[var_name].append(relative_path)
+
+                            # Track unsubstituted variables
+                            unsubstituted_variables.append(
+                                {
+                                    "file": relative_path,
+                                    "variable": var_name,
+                                    "count": len(matches),
+                                }
+                            )
+
+                except (OSError, UnicodeDecodeError):
+                    continue
+
+        except Exception as e:
+            usage_report["error"] = str(e)
+
+        return usage_report
+
+
+def synchronize_template_variables(project_root: str, changed_config_path: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Convenience function to synchronize template variables.
+
+    Args:
+        project_root: Root directory of the project
+        changed_config_path: Path to configuration file that changed
+
+    Returns:
+        Synchronization results
+    """
+    synchronizer = TemplateVariableSynchronizer(project_root)
+
+    config_path = Path(changed_config_path) if changed_config_path else None
+    return synchronizer.synchronize_after_config_change(config_path)