moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/core/claude_integration.py

@@ -0,0 +1,393 @@
+"""
+Claude Code CLI integration for advanced variable substitution and automation.
+
+Enables headless operation with template variable processing, JSON streaming,
+and multi-language support for commands, agents, and output styles.
+"""
+
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from .language_config import get_language_info
+from .template_engine import TemplateEngine
+
+
+class ClaudeCLIIntegration:
+    """
+    Advanced Claude CLI integration with template variable processing.
+
+    Features:
+    - Template variable substitution using MoAI-ADK's TemplateEngine
+    - JSON streaming input/output support
+    - Multi-language description processing
+    - Headless automation capabilities
+    - Configuration file generation and management
+    """
+
+    def __init__(self, template_engine: Optional[TemplateEngine] = None):
+        """Initialize Claude CLI integration.
+
+        Args:
+            template_engine: TemplateEngine instance for variable processing
+        """
+        self.template_engine = template_engine or TemplateEngine()
+
+    def generate_claude_settings(self, variables: Dict[str, Any], output_path: Optional[Path] = None) -> Path:
+        """Generate Claude settings JSON file with variables.
+
+        Args:
+            variables: Template variables to include
+            output_path: Path for settings file (auto-generated if None)
+
+        Returns:
+            Path to generated settings file
+        """
+        if output_path is None:
+            temp_file = tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False)
+            output_path = Path(temp_file.name)
+            temp_file.close()
+
+        settings = {
+            "variables": variables,
+            "template_context": {
+                "conversation_language": variables.get("CONVERSATION_LANGUAGE", "en"),
+                "conversation_language_name": variables.get("CONVERSATION_LANGUAGE_NAME", "English"),
+                "project_name": variables.get("PROJECT_NAME", ""),
+                "codebase_language": variables.get("CODEBASE_LANGUAGE", "python"),
+            },
+        }
+
+        output_path.write_text(json.dumps(settings, indent=2, ensure_ascii=False))
+        return output_path
+
+    def process_template_command(
+        self,
+        command_template: str,
+        variables: Dict[str, Any],
+        print_mode: bool = True,
+        output_format: str = "json",
+    ) -> Dict[str, Any]:
+        """Process Claude command with template variables.
+
+        Args:
+            command_template: Command template with {{VARIABLE}} placeholders
+            variables: Variables for substitution
+            print_mode: Use --print flag for non-interactive execution
+            output_format: Output format (text, json, stream-json)
+
+        Returns:
+            Process result dictionary
+        """
+        try:
+            # Process template variables
+            processed_command = self.template_engine.render_string(command_template, variables)
+
+            # Build Claude CLI command
+            cmd_parts = ["claude"]
+
+            if print_mode:
+                cmd_parts.extend(["--print"])
+                cmd_parts.extend(["--output-format", output_format])
+
+            # Add variable settings
+            settings_file = self.generate_claude_settings(variables)
+            cmd_parts.extend(["--settings", str(settings_file)])
+
+            # Add processed command
+            cmd_parts.append(processed_command)
+
+            # Execute Claude CLI
+            result = subprocess.run(cmd_parts, capture_output=True, text=True, encoding="utf-8")
+
+            # Cleanup settings file
+            try:
+                settings_file.unlink()
+            except OSError:
+                pass  # Ignore cleanup errors
+
+            return {
+                "success": result.returncode == 0,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "returncode": result.returncode,
+                "processed_command": processed_command,
+                "variables_used": variables,
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e),
+                "processed_command": command_template,
+                "variables_used": variables,
+            }
+
+    def generate_multilingual_descriptions(
+        self,
+        base_descriptions: Dict[str, str],
+        target_languages: Optional[list[str]] = None,
+    ) -> Dict[str, Dict[str, str]]:
+        """Generate multilingual descriptions for commands/agents.
+
+        Args:
+            base_descriptions: English base descriptions
+            target_languages: Target language codes (auto-detected if None)
+
+        Returns:
+            Multilingual descriptions dictionary
+        """
+        if target_languages is None:
+            # Auto-detect from variables or use common languages
+            target_languages = ["en", "ko", "ja", "es", "fr", "de"]
+
+        multilingual = {}
+
+        for item_id, base_desc in base_descriptions.items():
+            multilingual[item_id] = {"en": base_desc}
+
+            # Generate descriptions for target languages
+            for lang_code in target_languages:
+                if lang_code == "en":
+                    continue  # Already have base
+
+                lang_info = get_language_info(lang_code)
+                if not lang_info:
+                    continue
+
+                # Create language-specific description prompt
+                translation_prompt = f"""Translate the following Claude Code description to {lang_info["native_name"]}.
+Keep technical terms in English. Provide only the translation without explanation:
+
+Original: {base_desc}
+
+Translation:"""
+
+                # Use Claude CLI for translation
+                translation_result = self.process_template_command(
+                    translation_prompt,
+                    {"CONVERSATION_LANGUAGE": lang_code},
+                    print_mode=True,
+                    output_format="text",
+                )
+
+                if translation_result["success"]:
+                    # Extract translation from output
+                    translation = translation_result["stdout"].strip()
+                    if translation:
+                        multilingual[item_id][lang_code] = translation
+
+        return multilingual
+
+    def create_agent_with_multilingual_support(
+        self,
+        agent_name: str,
+        base_description: str,
+        tools: list[str],
+        model: str = "sonnet",
+        target_languages: Optional[list[str]] = None,
+    ) -> Dict[str, Any]:
+        """Create Claude agent with multilingual description support.
+
+        Args:
+            agent_name: Agent name (kebab-case)
+            base_description: English base description
+            tools: List of required tools
+            model: Claude model to use
+            target_languages: Target languages for descriptions
+
+        Returns:
+            Agent configuration dictionary
+        """
+        if target_languages is None:
+            target_languages = ["en", "ko", "ja", "es", "fr", "de"]
+
+        # Generate multilingual descriptions
+        descriptions = self.generate_multilingual_descriptions({agent_name: base_description}, target_languages)
+
+        agent_config = {
+            "name": agent_name,
+            "description": descriptions[agent_name]["en"],  # Primary English description
+            "tools": tools,
+            "model": model,
+            "descriptions": descriptions[agent_name],  # All language versions
+            "multilingual_support": True,
+        }
+
+        return agent_config
+
+    def create_command_with_multilingual_support(
+        self,
+        command_name: str,
+        base_description: str,
+        argument_hint: list[str],
+        tools: list[str],
+        model: str = "haiku",
+        target_languages: Optional[list[str]] = None,
+    ) -> Dict[str, Any]:
+        """Create Claude command with multilingual description support.
+
+        Args:
+            command_name: Command name (kebab-case)
+            base_description: English base description
+            argument_hint: List of argument hints
+            tools: List of required tools
+            model: Claude model to use
+            target_languages: Target languages for descriptions
+
+        Returns:
+            Command configuration dictionary
+        """
+        if target_languages is None:
+            target_languages = ["en", "ko", "ja", "es", "fr", "de"]
+
+        # Generate multilingual descriptions
+        descriptions = self.generate_multilingual_descriptions({command_name: base_description}, target_languages)
+
+        command_config = {
+            "name": command_name,
+            "description": descriptions[command_name]["en"],  # Primary English description
+            "argument-hint": argument_hint,
+            "tools": tools,
+            "model": model,
+            "descriptions": descriptions[command_name],  # All language versions
+            "multilingual_support": True,
+        }
+
+        return command_config
+
+    def process_json_stream_input(
+        self,
+        input_data: Union[Dict[str, Any], str],
+        variables: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Process JSON stream input for Claude CLI.
+
+        Args:
+            input_data: JSON data as dict or JSON string
+            variables: Additional variables for processing
+
+        Returns:
+            Processed input data
+        """
+        # Convert string to dict if needed
+        processed_data: Dict[str, Any]
+        if isinstance(input_data, str):
+            try:
+                processed_data = json.loads(input_data)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Invalid JSON input: {e}")
+        else:
+            processed_data = input_data
+
+        if variables:
+            # Process any string values in processed_data with variables
+            for key, value in processed_data.items():
+                if isinstance(value, str) and "{{" in value and "}}" in value:
+                    processed_data[key] = self.template_engine.render_string(value, variables)
+
+        return processed_data
+
+    def execute_headless_command(
+        self,
+        prompt_template: str,
+        variables: Dict[str, Any],
+        input_format: str = "stream-json",
+        output_format: str = "stream-json",
+        additional_options: Optional[list[str]] = None,
+    ) -> Dict[str, Any]:
+        """Execute Claude command in headless mode with full variable processing.
+
+        Args:
+            prompt_template: Prompt template with variables
+            variables: Variables for substitution
+            input_format: Input format (text, stream-json)
+            output_format: Output format (text, json, stream-json)
+            additional_options: Additional CLI options
+
+        Returns:
+            Command execution result
+        """
+        try:
+            # Process prompt template
+            processed_prompt = self.template_engine.render_string(prompt_template, variables)
+
+            # Build Claude command
+            cmd_parts = ["claude", "--print"]
+            cmd_parts.extend(["--input-format", input_format])
+            cmd_parts.extend(["--output-format", output_format])
+
+            # Add settings
+            settings_file = self.generate_claude_settings(variables)
+            cmd_parts.extend(["--settings", str(settings_file)])
+
+            # Add additional options
+            if additional_options:
+                cmd_parts.extend(additional_options)
+
+            # Add processed prompt
+            cmd_parts.append(processed_prompt)
+
+            # Execute with streaming support
+            if output_format == "stream-json":
+                # For streaming, use subprocess with real-time output
+                process = subprocess.Popen(
+                    cmd_parts,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                    encoding="utf-8",
+                )
+
+                stdout_lines = []
+                stderr_lines = []
+
+                # Stream output in real-time
+                while True:
+                    stdout_line = process.stdout.readline()
+                    stderr_line = process.stderr.readline()
+
+                    if stdout_line == "" and stderr_line == "" and process.poll() is not None:
+                        break
+
+                    if stdout_line:
+                        stdout_lines.append(stdout_line.strip())
+                        # You can process each line here for real-time handling
+
+                    if stderr_line:
+                        stderr_lines.append(stderr_line.strip())
+
+                returncode = process.poll()
+
+            else:
+                # Non-streaming execution
+                result = subprocess.run(cmd_parts, capture_output=True, text=True, encoding="utf-8")
+
+                stdout_lines = result.stdout.strip().split("\n") if result.stdout else []
+                stderr_lines = result.stderr.strip().split("\n") if result.stderr else []
+                returncode = result.returncode
+
+            # Cleanup
+            try:
+                settings_file.unlink()
+            except OSError:
+                pass
+
+            return {
+                "success": returncode == 0,
+                "stdout": stdout_lines,
+                "stderr": stderr_lines,
+                "returncode": returncode,
+                "processed_prompt": processed_prompt,
+                "variables": variables,
+            }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e),
+                "prompt_template": prompt_template,
+                "variables": variables,
+            }

moai_adk/core/command_helpers.py

@@ -0,0 +1,270 @@
+"""
+Command Helper Utilities
+
+Provides helper functions for commands to interact with ContextManager
+and perform common operations like context extraction and validation.
+"""
+
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+# Conditional import of ContextManager
+try:
+    from moai_adk.core.context_manager import (
+        ContextManager,
+        validate_and_convert_path,
+        validate_no_template_vars,
+    )
+
+    CONTEXT_MANAGER_AVAILABLE = True
+except ImportError:
+    CONTEXT_MANAGER_AVAILABLE = False
+
+
+def extract_project_metadata(project_root: str) -> Dict[str, Any]:
+    """
+    Extract project metadata from config.yaml.
+
+    Args:
+        project_root: Root directory of the project
+
+    Returns:
+        Dictionary containing project metadata
+
+    Raises:
+        FileNotFoundError: If config.yaml doesn't exist
+        yaml.YAMLError: If config.yaml is invalid
+    """
+    config_path = os.path.join(project_root, ".moai", "config", "config.yaml")
+
+    if not os.path.exists(config_path):
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    with open(config_path, "r", encoding="utf-8") as f:
+        config = yaml.safe_load(f) or {}
+
+    # Extract key metadata
+    metadata = {
+        "project_name": config.get("project", {}).get("name", "Unknown"),
+        "mode": config.get("project", {}).get("mode", "personal"),
+        "github_profile": config.get("github", {}).get("profile_name", ""),
+        "language": config.get("language", {}).get("conversation_language", "en"),
+        "tech_stack": [],  # To be detected separately
+    }
+
+    return metadata
+
+
+def detect_tech_stack(project_root: str) -> List[str]:
+    """
+    Detect primary tech stack from project structure.
+
+    Checks for common project indicator files.
+
+    Args:
+        project_root: Root directory of the project
+
+    Returns:
+        List of detected languages/frameworks
+    """
+    indicators = {
+        "pyproject.toml": "python",
+        "package.json": "javascript",
+        "go.mod": "go",
+        "Cargo.toml": "rust",
+        "pom.xml": "java",
+        "Gemfile": "ruby",
+    }
+
+    tech_stack = []
+
+    for indicator_file, language in indicators.items():
+        if os.path.exists(os.path.join(project_root, indicator_file)):
+            tech_stack.append(language)
+
+    # Default to python if nothing detected
+    if not tech_stack:
+        tech_stack.append("python")
+
+    return tech_stack
+
+
+def build_phase_result(
+    phase_name: str,
+    status: str,
+    outputs: Dict[str, Any],
+    files_created: List[str],
+    next_phase: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Build standardized phase result dictionary.
+
+    Args:
+        phase_name: Name of the phase (e.g., "0-project")
+        status: Phase status (completed/error/interrupted)
+        outputs: Dictionary of phase outputs
+        files_created: List of created files (absolute paths)
+        next_phase: Optional next phase name
+
+    Returns:
+        Standardized phase result dictionary
+    """
+    phase_result = {
+        "phase": phase_name,
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "status": status,
+        "outputs": outputs,
+        "files_created": files_created,
+    }
+
+    if next_phase:
+        phase_result["next_phase"] = next_phase
+
+    return phase_result
+
+
+def validate_phase_files(relative_paths: List[str], project_root: str) -> List[str]:
+    """
+    Validate and convert relative file paths to absolute paths.
+
+    Handles errors gracefully by logging warnings and skipping invalid paths.
+
+    Args:
+        relative_paths: List of relative file paths
+        project_root: Project root directory
+
+    Returns:
+        List of validated absolute paths
+    """
+    if not CONTEXT_MANAGER_AVAILABLE:
+        # Fallback: simple absolute path conversion
+        return [os.path.abspath(os.path.join(project_root, p)) for p in relative_paths]
+
+    absolute_paths = []
+
+    for rel_path in relative_paths:
+        try:
+            abs_path = validate_and_convert_path(rel_path, project_root)
+            absolute_paths.append(abs_path)
+        except (ValueError, FileNotFoundError) as e:
+            # Log warning but continue processing
+            print(f"Warning: Could not validate path '{rel_path}': {e}")
+
+    return absolute_paths
+
+
+def _prepare_phase_data(
+    phase_name: str,
+    status: str,
+    outputs: Dict[str, Any],
+    absolute_paths: List[str],
+    next_phase: Optional[str],
+) -> Dict[str, Any]:
+    """
+    Prepare phase data for saving.
+
+    Args:
+        phase_name: Name of the phase
+        status: Phase status
+        outputs: Phase outputs
+        absolute_paths: List of absolute file paths
+        next_phase: Optional next phase
+
+    Returns:
+        Phase data dictionary ready for saving
+    """
+    phase_data = build_phase_result(
+        phase_name=phase_name,
+        status=status,
+        outputs=outputs,
+        files_created=absolute_paths,
+        next_phase=next_phase,
+    )
+
+    # Validate no unsubstituted template variables
+    phase_json = json.dumps(phase_data)
+    validate_no_template_vars(phase_json)
+
+    return phase_data
+
+
+def _validate_and_save(context_mgr: Any, phase_data: Dict[str, Any]) -> str:
+    """
+    Validate and save phase data.
+
+    Args:
+        context_mgr: ContextManager instance
+        phase_data: Phase data to save
+
+    Returns:
+        Path to saved file
+    """
+    saved_path = context_mgr.save_phase_result(phase_data)
+    print(f"✓ Phase context saved: {os.path.basename(saved_path)}")
+    return saved_path
+
+
+def save_command_context(
+    phase_name: str,
+    project_root: str,
+    outputs: Dict[str, Any],
+    files_created: List[str],
+    next_phase: Optional[str] = None,
+    status: str = "completed",
+) -> Optional[str]:
+    """
+    Save command phase context using ContextManager.
+
+    This is a convenience wrapper for commands to save phase results
+    with proper error handling.
+
+    Args:
+        phase_name: Name of the phase (e.g., "0-project")
+        project_root: Project root directory
+        outputs: Phase-specific outputs
+        files_created: List of relative file paths
+        next_phase: Optional next phase recommendation
+        status: Phase status (default: "completed")
+
+    Returns:
+        Path to saved file, or None if save failed
+    """
+    if not CONTEXT_MANAGER_AVAILABLE:
+        print("Warning: ContextManager not available. Phase context not saved.")
+        return None
+
+    try:
+        context_mgr = ContextManager(project_root)
+        absolute_paths = validate_phase_files(files_created, project_root)
+        phase_data = _prepare_phase_data(phase_name, status, outputs, absolute_paths, next_phase)
+        return _validate_and_save(context_mgr, phase_data)
+
+    except Exception as e:
+        print(f"Warning: Failed to save phase context: {e}")
+        print("Command execution continues normally.")
+        return None
+
+
+def load_previous_phase(project_root: str) -> Optional[Dict[str, Any]]:
+    """
+    Load the most recent phase result.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        Phase result dictionary, or None if unavailable
+    """
+    if not CONTEXT_MANAGER_AVAILABLE:
+        return None
+
+    try:
+        context_mgr = ContextManager(project_root)
+        return context_mgr.load_latest_phase()
+    except Exception as e:
+        print(f"Warning: Could not load previous phase: {e}")
+        return None