moai-adk 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

moai_adk/core/issue_creator.py

@@ -0,0 +1,309 @@
+"""
+GitHub Issue Creator for MoAI-ADK quick issue reporting.
+
+Enables users to quickly create GitHub Issues with standardized templates
+using `/alfred:9-feedback` interactive dialog.
+
+@TAG:ISSUE-CREATOR-001 - GitHub issue creation system
+@TAG:QUICK-REPORTING-001 - Quick issue reporting functionality
+"""
+
+import subprocess
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class IssueType(Enum):
+    """Supported GitHub issue types."""
+    BUG = "bug"
+    FEATURE = "feature"
+    IMPROVEMENT = "improvement"
+    QUESTION = "question"
+
+
+class IssuePriority(Enum):
+    """Issue priority levels."""
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class IssueConfig:
+    """Configuration for issue creation."""
+    issue_type: IssueType
+    title: str
+    description: str
+    priority: IssuePriority = IssuePriority.MEDIUM
+    category: Optional[str] = None
+    assignees: Optional[List[str]] = None
+    custom_labels: Optional[List[str]] = None
+
+
+class GitHubIssueCreator:
+    """
+    Creates GitHub Issues using the `gh` CLI.
+
+    Supports:
+    - Multiple issue types (bug, feature, improvement, question)
+    - Priority levels and categories
+    - Standard templates for each type
+    - Label automation
+    - Priority emoji indicators
+    """
+
+    # Label mapping for issue types
+    LABEL_MAP = {
+        IssueType.BUG: ["bug", "reported"],
+        IssueType.FEATURE: ["feature-request", "enhancement"],
+        IssueType.IMPROVEMENT: ["improvement", "enhancement"],
+        IssueType.QUESTION: ["question", "help-wanted"],
+    }
+
+    # Priority emoji
+    PRIORITY_EMOJI = {
+        IssuePriority.CRITICAL: "🔴",
+        IssuePriority.HIGH: "🟠",
+        IssuePriority.MEDIUM: "🟡",
+        IssuePriority.LOW: "🟢",
+    }
+
+    # Issue type emoji
+    TYPE_EMOJI = {
+        IssueType.BUG: "🐛",
+        IssueType.FEATURE: "✨",
+        IssueType.IMPROVEMENT: "⚡",
+        IssueType.QUESTION: "❓",
+    }
+
+    def __init__(self, github_token: Optional[str] = None):
+        """
+        Initialize the GitHub Issue Creator.
+
+        Args:
+            github_token: GitHub API token. If not provided, uses GITHUB_TOKEN env var.
+        """
+        self.github_token = github_token
+        self._check_gh_cli()
+
+    def _check_gh_cli(self) -> None:
+        """
+        Check if `gh` CLI is installed and accessible.
+
+        Raises:
+            RuntimeError: If `gh` CLI is not found or not authenticated.
+        """
+        try:
+            result = subprocess.run(
+                ["gh", "auth", "status"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            if result.returncode != 0:
+                raise RuntimeError(
+                    "GitHub CLI (gh) is not authenticated. "
+                    "Run `gh auth login` to authenticate."
+                )
+        except FileNotFoundError:
+            raise RuntimeError(
+                "GitHub CLI (gh) is not installed. "
+                "Please install it: https://cli.github.com"
+            )
+
+    def create_issue(self, config: IssueConfig) -> Dict[str, Any]:
+        """
+        Create a GitHub issue with the given configuration.
+
+        Args:
+            config: Issue configuration
+
+        Returns:
+            Dictionary containing issue creation result:
+            {
+                "success": bool,
+                "issue_number": int,
+                "issue_url": str,
+                "message": str
+            }
+
+        Raises:
+            RuntimeError: If issue creation fails
+        """
+        # Build title with emoji and priority
+        emoji = self.TYPE_EMOJI.get(config.issue_type, "📋")
+        priority_emoji = self.PRIORITY_EMOJI.get(config.priority, "")
+        full_title = f"{emoji} [{config.issue_type.value.upper()}] {config.title}"
+        if priority_emoji:
+            full_title = f"{priority_emoji} {full_title}"
+
+        # Build body with template
+        body = self._build_body(config)
+
+        # Collect labels
+        labels = self.LABEL_MAP.get(config.issue_type, []).copy()
+        if config.priority:
+            labels.append(f"priority-{config.priority.value}")
+        if config.category:
+            labels.append(f"category-{config.category.lower().replace(' ', '-')}")
+        if config.custom_labels:
+            labels.extend(config.custom_labels)
+
+        # Build gh command
+        gh_command = [
+            "gh", "issue", "create",
+            "--title", full_title,
+            "--body", body,
+        ]
+
+        # Add labels
+        if labels:
+            gh_command.extend(["--label", ",".join(set(labels))])
+
+        # Add assignees if provided
+        if config.assignees:
+            gh_command.extend(["--assignee", ",".join(config.assignees)])
+
+        try:
+            result = subprocess.run(
+                gh_command,
+                capture_output=True,
+                text=True,
+                timeout=30
+            )
+
+            if result.returncode != 0:
+                error_msg = result.stderr or result.stdout
+                raise RuntimeError(f"Failed to create GitHub issue: {error_msg}")
+
+            # Parse issue URL from output
+            issue_url = result.stdout.strip()
+            issue_number = self._extract_issue_number(issue_url)
+
+            return {
+                "success": True,
+                "issue_number": issue_number,
+                "issue_url": issue_url,
+                "message": f"✅ GitHub Issue #{issue_number} created successfully",
+                "title": full_title,
+                "labels": labels,
+            }
+
+        except subprocess.TimeoutExpired:
+            raise RuntimeError("GitHub issue creation timed out")
+        except Exception as e:
+            raise RuntimeError(f"Error creating GitHub issue: {e}")
+
+    def _build_body(self, config: IssueConfig) -> str:
+        """
+        Build the issue body based on issue type.
+
+        Args:
+            config: Issue configuration
+
+        Returns:
+            Formatted issue body
+        """
+        body = config.description
+
+        # Add metadata footer
+        footer = "\n\n---\n\n"
+        footer += f"**Type**: {config.issue_type.value}  \n"
+        footer += f"**Priority**: {config.priority.value}  \n"
+        if config.category:
+            footer += f"**Category**: {config.category}  \n"
+        footer += f"**Created via**: `/alfred:9-feedback`"
+
+        return body + footer
+
+    @staticmethod
+    def _extract_issue_number(url: str) -> int:
+        """
+        Extract issue number from GitHub URL.
+
+        Args:
+            url: GitHub issue URL
+
+        Returns:
+            Issue number
+
+        Raises:
+            ValueError: If unable to extract issue number
+        """
+        try:
+            # URL format: https://github.com/owner/repo/issues/123
+            return int(url.strip().split("/")[-1])
+        except (ValueError, IndexError):
+            raise ValueError(f"Unable to extract issue number from URL: {url}")
+
+    def format_result(self, result: Dict[str, Any]) -> str:
+        """
+        Format the issue creation result for display.
+
+        Args:
+            result: Issue creation result
+
+        Returns:
+            Formatted result string
+        """
+        if result["success"]:
+            output = f"{result['message']}\n"
+            output += f"📋 Title: {result['title']}\n"
+            output += f"🔗 URL: {result['issue_url']}\n"
+            if result.get("labels"):
+                output += f"🏷️  Labels: {', '.join(result['labels'])}\n"
+            return output
+        else:
+            return f"❌ Failed to create issue: {result.get('message', 'Unknown error')}"
+
+
+class IssueCreatorFactory:
+    """
+    Factory for creating issue creators with predefined configurations.
+    """
+
+    @staticmethod
+    def create_bug_issue(title: str, description: str, priority: IssuePriority = IssuePriority.HIGH) -> IssueConfig:
+        """Create a bug report issue configuration."""
+        return IssueConfig(
+            issue_type=IssueType.BUG,
+            title=title,
+            description=description,
+            priority=priority,
+            category="Bug Report",
+        )
+
+    @staticmethod
+    def create_feature_issue(title: str, description: str, priority: IssuePriority = IssuePriority.MEDIUM) -> IssueConfig:
+        """Create a feature request issue configuration."""
+        return IssueConfig(
+            issue_type=IssueType.FEATURE,
+            title=title,
+            description=description,
+            priority=priority,
+            category="Feature Request",
+        )
+
+    @staticmethod
+    def create_improvement_issue(title: str, description: str, priority: IssuePriority = IssuePriority.MEDIUM) -> IssueConfig:
+        """Create an improvement issue configuration."""
+        return IssueConfig(
+            issue_type=IssueType.IMPROVEMENT,
+            title=title,
+            description=description,
+            priority=priority,
+            category="Improvement",
+        )
+
+    @staticmethod
+    def create_question_issue(title: str, description: str, priority: IssuePriority = IssuePriority.LOW) -> IssueConfig:
+        """Create a question/discussion issue configuration."""
+        return IssueConfig(
+            issue_type=IssueType.QUESTION,
+            title=title,
+            description=description,
+            priority=priority,
+            category="Question",
+        )

moai_adk/core/project/phase_executor.py

@@ -26,6 +26,7 @@ from moai_adk.core.project.backup_utils import (
     is_protected_path,
 )
 from moai_adk.core.project.validator import ProjectValidator
+from moai_adk.core.template.processor import TemplateProcessor
 
 console = Console()
 
@@ -136,8 +137,6 @@ class PhaseExecutor:
         )
 
         # Copy resources via TemplateProcessor in silent mode
-        from moai_adk.core.template import TemplateProcessor
-
         processor = TemplateProcessor(project_path)
 
         # Set template variable context (if provided)

moai_adk/core/template_engine.py

@@ -0,0 +1,253 @@
+"""
+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 = False):
+        """
+        Initialize the template engine.
+
+        Args:
+            strict_undefined: If True, raise error on undefined variables.
+                             If False, render undefined variables as empty strings.
+        """
+        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):
+                errors.append(f"Invalid type for {var_name}: expected {var_type.__name__}, got {type(variables[var_name]).__name__}")
+
+        # 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):
+                    type_names = " or ".join(t.__name__ for t in var_type) if isinstance(var_type, tuple) else var_type.__name__
+                    errors.append(f"Invalid type for {var_name}: expected {type_names}, got {type(variables[var_name]).__name__}")
+
+        return len(errors) == 0, errors

moai_adk/templates/.claude/agents/alfred/cc-manager.md

@@ -54,7 +54,7 @@ Alfred translates Claude Code configuration requirements to English before invok
 - `Skill("moai-alfred-git-workflow")` - Git strategy impact
 - Domain skills (CLI/Data Science/Database/etc) - When relevant
 - Language skills (23 available) - Based on detected language
-- `Skill("moai-alfred-interactive-questions")` - User clarification
+- `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` - User clarification
 
 ---
 

moai_adk/templates/.claude/agents/alfred/debug-helper.md

@@ -6,7 +6,7 @@ model: sonnet
 ---
 
 # Debug Helper - Integrated debugging expert
-> **Note**: Interactive prompts use `Skill("moai-alfred-interactive-questions")` for TUI selection menus. The skill is loaded on-demand when user interaction is required.
+> **Note**: Interactive prompts use `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` for TUI selection menus. The skill is loaded on-demand when user interaction is required.
 
 You are the integrated debugging expert responsible for **all errors**.
 
@@ -45,7 +45,7 @@ Alfred translates error reports and debugging requirements to English before inv
 - `Skill("moai-essentials-review")`: Loaded when structural problems or solutions to prevent recurrence need to be presented.
 - Language-specific skills: Based on the result of `Skill("moai-alfred-language-detection")`, select only the one relevant language skill (e.g., `Skill("moai-lang-python")`, `Skill("moai-lang-typescript")`, etc.).  
 - `Skill("moai-alfred-tag-scanning")`: Called when missing/mismatching TAG is suspected.
-- `Skill("moai-alfred-interactive-questions")`: Executed when user selection among multiple solutions is required.
+- `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)`: Executed when user selection among multiple solutions is required.
 
 ### Expert Traits
 

moai_adk/templates/.claude/agents/alfred/doc-syncer.md

@@ -6,7 +6,7 @@ model: haiku
 ---
 
 # Doc Syncer - Document Management/Synchronization Expert
-> **Note**: Interactive prompts use `Skill("moai-alfred-interactive-questions")` for TUI selection menus. The skill is loaded on-demand when user interaction is required.
+> **Note**: Interactive prompts use `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` for TUI selection menus. The skill is loaded on-demand when user interaction is required.
 
 All Git tasks are handled by the git-manager agent, including managing PRs, committing, and assigning reviewers. doc-syncer is only responsible for document synchronization.
 
@@ -47,7 +47,7 @@ Alfred translates document synchronization requirements to English before invoki
 - `Skill("moai-foundation-specs")`: Use only when SPEC metadata has changed or document consistency verification is required.
 - `Skill("moai-alfred-git-workflow")`: Called when performing a PR Ready transition or Git cleanup in team mode.
 - `Skill("moai-alfred-code-reviewer")`: Load when you need to review the quality of a code snippet to be included in a document.
-- `Skill("moai-alfred-interactive-questions")`: Executed when checking with the user whether to approve/skip the synchronization range.
+- `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)`: Executed when checking with the user whether to approve/skip the synchronization range.
 
 ### Expert Traits
 

moai_adk/templates/.claude/agents/alfred/git-manager.md

@@ -6,7 +6,7 @@ model: haiku
 ---
 
 # Git Manager - Agent dedicated to Git tasks
-> **Note**: Interactive prompts use `Skill("moai-alfred-interactive-questions")` for TUI selection menus. The skill is loaded on-demand when user interaction is required.
+> **Note**: Interactive prompts use `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` for TUI selection menus. The skill is loaded on-demand when user interaction is required.
 
 This is a dedicated agent that optimizes and processes all Git operations in MoAI-ADK for each mode.
 
@@ -45,7 +45,7 @@ This ensures git history is always in English for global team compatibility.
 - `Skill("moai-foundation-git")`: Called when this is a new repository or the Git standard needs to be redefined.
 - `Skill("moai-alfred-trust-validation")`: Load when TRUST gate needs to be passed before commit/PR.
 - `Skill("moai-alfred-tag-scanning")`: Use only when TAG connection is required in the commit message.
-- `Skill("moai-alfred-interactive-questions")`: Called when user approval is obtained before performing risky operations such as rebase/force push.
+- `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)`: Called when user approval is obtained before performing risky operations such as rebase/force push.
 
 ### Expert Traits
 
@@ -358,9 +358,10 @@ Git-manager automatically handles the following exception situations:
 **All commits created by git-manager follow this signature format**:
 
 ```
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
+🎩 Alfred@MoAI
+🔗 https://adk.mo.ai.kr
 
-Co-Authored-By: 🎩 Alfred@[MoAI](https://adk.mo.ai.kr)
+Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 This signature applies to all Git operations:
@@ -370,6 +371,28 @@ This signature applies to all Git operations:
 - Merge commits
 - Tag creation
 
+**Signature breakdown**:
+- `🎩 Alfred@MoAI` - Alfred 에이전트의 공식 식별자
+- `🔗 https://adk.mo.ai.kr` - MoAI-ADK 공식 홈페이지 링크
+- `Co-Authored-By: Claude <noreply@anthropic.com>` - Claude AI 협력자 표시
+
+**Implementation Example (HEREDOC)**:
+```bash
+git commit -m "$(cat <<'EOF'
+feat(update): Implement 3-stage workflow with config version comparison
+
+- Stage 2: Config version comparison (NEW)
+- 70-80% performance improvement
+- All tests passing
+
+🎩 Alfred@MoAI
+🔗 https://adk.mo.ai.kr
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
 ---
 
 **git-manager provides a simple and stable work environment with direct Git commands instead of complex scripts.**