moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/core/template/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
+# @CODE:TEMPLATE-MODULE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
 """Template management module."""
 
 from moai_adk.core.template.backup import TemplateBackup

moai_adk/core/template/backup.py

@@ -1,4 +1,4 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
+# @CODE:TEMPLATE-BACKUP-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
 """Template backup manager (SPEC-INIT-003 v0.3.0).
 
 Creates and manages backups to protect user data during template updates.

moai_adk/core/template/merger.py

@@ -1,4 +1,4 @@
-# @CODE:TEMPLATE-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
+# @CODE:TEMPLATE-MERGER-001 | SPEC: SPEC-INIT-003/spec.md | Chain: TEMPLATE-001
 """Template file merger (SPEC-INIT-003 v0.3.0).
 
 Intelligently merges existing user files with new templates.
@@ -182,3 +182,52 @@ class TemplateMerger:
             json.dumps(merged, indent=2, ensure_ascii=False) + "\n",
             encoding="utf-8"
         )
+
+    def merge_github_workflows(self, template_dir: Path, existing_dir: Path) -> None:
+        """Smart merge for .github/workflows/ directory.
+
+        Rules:
+        - Preserve existing user workflows (never delete)
+        - Add/update only MoAI-ADK managed workflows (moai-*.yml)
+        - Copy other template directories (ISSUE_TEMPLATE/, PULL_REQUEST_TEMPLATE.md)
+
+        Args:
+            template_dir: Template .github directory.
+            existing_dir: Existing .github directory.
+        """
+        import shutil
+
+        # Ensure workflows directory exists
+        workflows_dir = existing_dir / "workflows"
+        workflows_dir.mkdir(exist_ok=True)
+
+        # Track existing user workflows for preservation
+        user_workflows = set()
+        if workflows_dir.exists():
+            for workflow_file in workflows_dir.glob("*.yml"):
+                user_workflows.add(workflow_file.name)
+
+        # Copy template contents with smart merge for workflows
+        for item in template_dir.rglob("*"):
+            if item.is_file():
+                rel_path = item.relative_to(template_dir)
+                dst_item = existing_dir / rel_path
+
+                # Handle workflow files specially
+                if rel_path.parent.name == "workflows" and rel_path.name.endswith(".yml"):
+                    # Only update MoAI-ADK managed workflows (moai-*.yml)
+                    if rel_path.name.startswith("moai-"):
+                        dst_item.parent.mkdir(parents=True, exist_ok=True)
+                        shutil.copy2(item, dst_item)
+                    # Skip non-moai workflows to preserve user custom workflows
+                    continue
+
+                # Copy non-workflow files normally
+                dst_item.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(item, dst_item)
+
+            elif item.is_dir():
+                # Create directories as needed
+                rel_path = item.relative_to(template_dir)
+                dst_item = existing_dir / rel_path
+                dst_item.mkdir(parents=True, exist_ok=True)

moai_adk/core/template/processor.py

@@ -65,6 +65,15 @@ class TemplateProcessor:
         """
         warnings = []
 
+        # Detect common template variables and provide helpful suggestions
+        common_variables = {
+            "HOOK_PROJECT_DIR": "Cross-platform hook path (update moai-adk to fix)",
+            "PROJECT_NAME": "Project name (run /alfred:0-project to set)",
+            "AUTHOR": "Project author (run /alfred:0-project to set)",
+            "CONVERSATION_LANGUAGE": "Interface language (run /alfred:0-project to set)",
+            "MOAI_VERSION": "MoAI-ADK version (should be set automatically)",
+        }
+
         # Perform variable substitution
         for key, value in self.context.items():
             placeholder = f"{{{{{key}}}}}"  # {{KEY}}
@@ -72,11 +81,23 @@ class TemplateProcessor:
                 safe_value = self._sanitize_value(value)
                 content = content.replace(placeholder, safe_value)
 
-        # Detect unsubstituted variables
+        # Detect unsubstituted variables with enhanced error messages
         remaining = re.findall(r'\{\{([A-Z_]+)\}\}', content)
         if remaining:
             unique_remaining = sorted(set(remaining))
-            warnings.append(f"Unsubstituted variables: {', '.join(unique_remaining)}")
+
+            # Build detailed warning message
+            warning_parts = []
+            for var in unique_remaining:
+                if var in common_variables:
+                    suggestion = common_variables[var]
+                    warning_parts.append(f"{{{{{var}}}}} → {suggestion}")
+                else:
+                    warning_parts.append(f"{{{{{var}}}}} → Unknown variable (check template)")
+
+            warnings.append("Template variables not substituted:")
+            warnings.extend(f"  • {part}" for part in warning_parts)
+            warnings.append("💡 Run 'uv run moai-adk update' to fix template variables")
 
         return content, warnings
 
@@ -110,8 +131,59 @@ class TemplateProcessor:
         }
         return file_path.suffix.lower() in text_extensions
 
+    def _localize_yaml_description(self, content: str, language: str = "en") -> str:
+        """Localize multilingual YAML description field.
+
+        Converts multilingual description maps to single-language strings:
+        description:
+          en: "English text"
+          ko: "Korean text"
+        →
+        description: "Korean text"  (if language="ko")
+
+        Args:
+            content: File content.
+            language: Target language code (en, ko, ja, zh).
+
+        Returns:
+            Content with localized descriptions.
+        """
+        import yaml
+
+        # Pattern to match YAML frontmatter
+        frontmatter_pattern = r'^---\n(.*?)\n---'
+        match = re.match(frontmatter_pattern, content, re.DOTALL)
+
+        if not match:
+            return content
+
+        try:
+            yaml_content = match.group(1)
+            yaml_data = yaml.safe_load(yaml_content)
+
+            # Check if description is a dict (multilingual)
+            if isinstance(yaml_data.get('description'), dict):
+                # Select language (fallback to English)
+                descriptions = yaml_data['description']
+                selected_desc = descriptions.get(language, descriptions.get('en', ''))
+
+                # Replace description with selected language
+                yaml_data['description'] = selected_desc
+
+                # Reconstruct frontmatter
+                new_yaml = yaml.dump(yaml_data, allow_unicode=True, sort_keys=False)
+                # Preserve the rest of the content
+                rest_content = content[match.end():]
+                return f"---\n{new_yaml}---{rest_content}"
+
+        except Exception:
+            # If YAML parsing fails, return original content
+            pass
+
+        return content
+
     def _copy_file_with_substitution(self, src: Path, dst: Path) -> list[str]:
-        """Copy file with variable substitution for text files.
+        """Copy file with variable substitution and description localization for text files.
 
         Args:
             src: Source file path.
@@ -127,6 +199,14 @@ class TemplateProcessor:
             try:
                 content = src.read_text(encoding='utf-8')
                 content, file_warnings = self._substitute_variables(content)
+
+                # Apply description localization for command/output-style files
+                if src.suffix == '.md' and (
+                    'commands/alfred' in str(src) or 'output-styles/alfred' in str(src)
+                ):
+                    lang = self.context.get('CONVERSATION_LANGUAGE', 'en')
+                    content = self._localize_yaml_description(content, lang)
+
                 dst.write_text(content, encoding='utf-8')
                 warnings.extend(file_warnings)
             except UnicodeDecodeError:
@@ -231,7 +311,7 @@ class TemplateProcessor:
     def _copy_claude(self, silent: bool = False) -> None:
         """.claude/ directory copy with variable substitution (selective with alfred folder overwrite).
 
-        @CODE:INIT-004:ALFRED-001 | Copy all 4 Alfred command files from templates
+        @CODE:INIT-TEMPLATE-001:ALFRED-001 | Copy all 4 Alfred command files from templates
         @REQ:COMMAND-GENERATION-001 | SPEC-INIT-004: Automatic generation of Alfred command files
         @SPEC:TEMPLATE-PROCESSING-001 | Template processor integration for Alfred command files
 
@@ -252,8 +332,8 @@ class TemplateProcessor:
         # Create .claude directory if not exists
         dst.mkdir(parents=True, exist_ok=True)
 
-        # @CODE:INIT-004:ALFRED-002 | Alfred command files must always be overwritten
-        # @CODE:INIT-004:ALFRED-COPY | Copy all 4 Alfred command files from templates
+        # @CODE:INIT-ALFRED-002 | Alfred command files must always be overwritten
+        # @CODE:INIT-COMMAND-003 | Copy all 4 Alfred command files from templates
         # Alfred folders to copy wholesale (overwrite)
         alfred_folders = [
             "hooks/alfred",
@@ -292,8 +372,14 @@ class TemplateProcessor:
                 # Smart merge for settings.json
                 if item.name == "settings.json":
                     self._merge_settings_json(item, dst_item)
+                    # Apply variable substitution to merged settings.json (for cross-platform Hook paths)
+                    if self.context:
+                        content = dst_item.read_text(encoding='utf-8')
+                        content, file_warnings = self._substitute_variables(content)
+                        dst_item.write_text(content, encoding='utf-8')
+                        all_warnings.extend(file_warnings)
                     if not silent:
-                        console.print("   🔄 settings.json merged (env variables preserved)")
+                        console.print("   🔄 settings.json merged (Hook paths configured for your OS)")
                 else:
                     # FORCE OVERWRITE: Always copy other files (no skip)
                     warnings = self._copy_file_with_substitution(item, dst_item)
@@ -358,7 +444,7 @@ class TemplateProcessor:
             console.print("   ✅ .moai/ copy complete (variables substituted)")
 
     def _copy_github(self, silent: bool = False) -> None:
-        """.github/ directory copy with variable substitution."""
+        """.github/ directory copy with smart merge (preserves user workflows)."""
         src = self.template_root / ".github"
         dst = self.target_path / ".github"
 
@@ -367,13 +453,15 @@ class TemplateProcessor:
                 console.print("⚠️ .github/ template not found")
             return
 
+        # Smart merge: preserve existing user workflows
         if dst.exists():
-            shutil.rmtree(dst)
-
-        self._copy_dir_with_substitution(src, dst)
+            self._merge_github_workflows(src, dst)
+        else:
+            # First time: just copy
+            self._copy_dir_with_substitution(src, dst)
 
         if not silent:
-            console.print("   ✅ .github/ copy complete (variables substituted)")
+            console.print("   🔄 .github/ merged (user workflows preserved, variables substituted)")
 
     def _copy_claude_md(self, silent: bool = False) -> None:
         """Copy CLAUDE.md with smart merge (preserves \"## Project Information\" section)."""
@@ -388,8 +476,17 @@ class TemplateProcessor:
         # Smart merge: preserve existing "## Project Information" section
         if dst.exists():
             self._merge_claude_md(src, dst)
+            # Substitute variables in the merged content
+            if self.context:
+                content = dst.read_text(encoding='utf-8')
+                content, warnings = self._substitute_variables(content)
+                dst.write_text(content, encoding='utf-8')
+                if warnings and not silent:
+                    console.print("[yellow]⚠️ Template warnings:[/yellow]")
+                    for warning in set(warnings):
+                        console.print(f"   {warning}")
             if not silent:
-                console.print("   🔄 CLAUDE.md merged (project information preserved)")
+                console.print("   🔄 CLAUDE.md merged (project information preserved, variables substituted)")
         else:
             # First time: just copy
             self._copy_file_with_substitution(src, dst)
@@ -405,6 +502,15 @@ class TemplateProcessor:
         """
         self.merger.merge_claude_md(src, dst)
 
+    def _merge_github_workflows(self, src: Path, dst: Path) -> None:
+        """Delegate the smart merge for .github/workflows/.
+
+        Args:
+            src: Template .github directory.
+            dst: Project .github directory.
+        """
+        self.merger.merge_github_workflows(src, dst)
+
     def _merge_settings_json(self, src: Path, dst: Path) -> None:
         """Delegate the smart merge for settings.json.
 

moai_adk/core/template_engine.py

@@ -0,0 +1,268 @@
+"""
+Template engine for parameterizing GitHub templates and other configuration files.
+
+Supports Jinja2-style templating with variable substitution and conditional sections.
+Enables users to customize MoAI-ADK templates for their own projects.
+
+@TAG:TEMPLATE-ENGINE-001 - Template variable substitution system
+@TAG:GITHUB-CUSTOMIZATION-001 - GitHub template parameterization
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from jinja2 import (
+    Environment,
+    FileSystemLoader,
+    StrictUndefined,
+    TemplateNotFound,
+    TemplateRuntimeError,
+    TemplateSyntaxError,
+)
+
+
+class TemplateEngine:
+    """
+    Jinja2-based template engine for MoAI-ADK configuration and GitHub templates.
+
+    Supports:
+    - Variable substitution: {{PROJECT_NAME}}, {{SPEC_DIR}}, etc.
+    - Conditional sections: {{#ENABLE_TRUST_5}}...{{/ENABLE_TRUST_5}}
+    - File-based and string-based template rendering
+    """
+
+    def __init__(self, strict_undefined: bool = True):
+        """
+        Initialize the template engine.
+
+        Args:
+            strict_undefined: If True, raise error on undefined variables (default: True).
+                             If False, render undefined variables as empty strings.
+
+        Note:
+            Changed to strict_undefined=True (v0.10.2+) for safer template rendering.
+            Variables must be explicitly provided to avoid silent template failures.
+        """
+        self.strict_undefined = strict_undefined
+        self.undefined_behavior = StrictUndefined if strict_undefined else None
+
+    def render_string(
+        self,
+        template_string: str,
+        variables: Dict[str, Any]
+    ) -> str:
+        """
+        Render a Jinja2 template string with provided variables.
+
+        Args:
+            template_string: The template content as a string
+            variables: Dictionary of variables to substitute
+
+        Returns:
+            Rendered template string
+
+        Raises:
+            TemplateSyntaxError: If template syntax is invalid
+            TemplateRuntimeError: If variable substitution fails in strict mode
+        """
+        try:
+            env = Environment(
+                undefined=self.undefined_behavior,
+                trim_blocks=False,
+                lstrip_blocks=False
+            )
+            template = env.from_string(template_string)
+            return template.render(**variables)
+        except (TemplateSyntaxError, TemplateRuntimeError) as e:
+            raise RuntimeError(f"Template rendering error: {e}")
+
+    def render_file(
+        self,
+        template_path: Path,
+        variables: Dict[str, Any],
+        output_path: Optional[Path] = None
+    ) -> str:
+        """
+        Render a Jinja2 template file with provided variables.
+
+        Args:
+            template_path: Path to the template file
+            variables: Dictionary of variables to substitute
+            output_path: If provided, write rendered content to this path
+
+        Returns:
+            Rendered template content
+
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+            TemplateSyntaxError: If template syntax is invalid
+            TemplateRuntimeError: If variable substitution fails in strict mode
+        """
+        if not template_path.exists():
+            raise FileNotFoundError(f"Template file not found: {template_path}")
+
+        template_dir = template_path.parent
+        template_name = template_path.name
+
+        try:
+            env = Environment(
+                loader=FileSystemLoader(str(template_dir)),
+                undefined=self.undefined_behavior,
+                trim_blocks=False,
+                lstrip_blocks=False
+            )
+            template = env.get_template(template_name)
+            rendered = template.render(**variables)
+
+            if output_path:
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                output_path.write_text(rendered, encoding='utf-8')
+
+            return rendered
+        except TemplateNotFound:
+            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}")
+
+    def render_directory(
+        self,
+        template_dir: Path,
+        output_dir: Path,
+        variables: Dict[str, Any],
+        pattern: str = "**/*.{md,yml,yaml,json}"
+    ) -> Dict[str, str]:
+        """
+        Render all template files in a directory.
+
+        Args:
+            template_dir: Source directory containing templates
+            output_dir: Destination directory for rendered files
+            variables: Dictionary of variables to substitute
+            pattern: Glob pattern for files to process (default: template files)
+
+        Returns:
+            Dictionary mapping input paths to rendered content
+
+        Raises:
+            FileNotFoundError: If template directory doesn't exist
+        """
+        if not template_dir.exists():
+            raise FileNotFoundError(f"Template directory not found: {template_dir}")
+
+        results = {}
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        for template_file in template_dir.glob(pattern):
+            if template_file.is_file():
+                relative_path = template_file.relative_to(template_dir)
+                output_file = output_dir / relative_path
+
+                try:
+                    rendered = self.render_file(template_file, variables, output_file)
+                    results[str(relative_path)] = rendered
+                except Exception as e:
+                    raise RuntimeError(f"Error rendering {relative_path}: {e}")
+
+        return results
+
+    @staticmethod
+    def get_default_variables(config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Extract template variables from project configuration.
+
+        Args:
+            config: Project configuration dictionary (from .moai/config.json)
+
+        Returns:
+            Dictionary of template variables
+        """
+        github_config = config.get("github", {}).get("templates", {})
+        project_config = config.get("project", {})
+
+        return {
+            # Project information
+            "PROJECT_NAME": project_config.get("name", "MyProject"),
+            "PROJECT_DESCRIPTION": project_config.get("description", ""),
+            "PROJECT_MODE": project_config.get("mode", "team"),  # team or personal
+
+            # 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"),
+
+            # Feature flags
+            "ENABLE_TRUST_5": github_config.get("enable_trust_5", True),
+            "ENABLE_TAG_SYSTEM": github_config.get("enable_tag_system", True),
+            "ENABLE_ALFRED_COMMANDS": github_config.get("enable_alfred_commands", True),
+
+            # Language configuration
+            "CONVERSATION_LANGUAGE": project_config.get("conversation_language", "en"),
+            "CONVERSATION_LANGUAGE_NAME": project_config.get("conversation_language_name", "English"),
+
+            # Additional metadata
+            "MOAI_VERSION": config.get("moai", {}).get("version", "0.7.0"),
+        }
+
+
+class TemplateVariableValidator:
+    """
+    Validates template variables for completeness and correctness.
+    Ensures all required variables are present before rendering.
+    """
+
+    REQUIRED_VARIABLES = {
+        "PROJECT_NAME": str,
+        "SPEC_DIR": str,
+        "DOCS_DIR": str,
+        "TEST_DIR": str,
+    }
+
+    OPTIONAL_VARIABLES = {
+        "PROJECT_DESCRIPTION": (str, type(None)),
+        "PROJECT_MODE": str,
+        "ENABLE_TRUST_5": bool,
+        "ENABLE_TAG_SYSTEM": bool,
+        "ENABLE_ALFRED_COMMANDS": bool,
+        "CONVERSATION_LANGUAGE": str,
+        "CONVERSATION_LANGUAGE_NAME": str,
+    }
+
+    @classmethod
+    def validate(cls, variables: Dict[str, Any]) -> tuple[bool, list[str]]:
+        """
+        Validate template variables.
+
+        Args:
+            variables: Dictionary of variables to validate
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        errors = []
+
+        # Check required variables
+        for var_name, var_type in cls.REQUIRED_VARIABLES.items():
+            if var_name not in variables:
+                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}"
+                )
+
+        # 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(t.__name__ for t in var_type)
+                    else:
+                        type_names = var_type.__name__
+                    actual_type = type(variables[var_name]).__name__
+                    errors.append(
+                        f"Invalid type for {var_name}: "
+                        f"expected {type_names}, got {actual_type}"
+                    )
+
+        return len(errors) == 0, errors