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

moai_adk/cli/commands/improve_user_experience.py

@@ -0,0 +1,348 @@
+"""
+User Experience Improvement CLI Command
+"""
+
+import argparse
+import asyncio
+from pathlib import Path
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+
+from moai_adk.utils.user_experience import (
+    UserExperienceAnalyzer,
+    generate_improvement_plan,
+)
+
+console = Console()
+
+
+def create_parser(subparsers) -> argparse.ArgumentParser:
+    """Create user experience improvement parser"""
+    parser = subparsers.add_parser(
+        "improve-ux",
+        help="Analyze user experience improvements",
+        description="Analyze user experience of online documentation portal and provide improvement plan",
+    )
+
+    parser.add_argument(
+        "--url",
+        "-u",
+        type=str,
+        default="https://adk.mo.ai.kr",
+        help="URL to analyze (default: https://adk.mo.ai.kr)",
+    )
+
+    parser.add_argument(
+        "--output", "-o", type=str, help="File path to save analysis results"
+    )
+
+    parser.add_argument(
+        "--format",
+        "-f",
+        type=str,
+        choices=["json", "markdown", "text"],
+        default="markdown",
+        help="Output format (default: markdown)",
+    )
+
+    parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Display detailed progress"
+    )
+
+    parser.add_argument(
+        "--max-workers",
+        "-w",
+        type=int,
+        default=5,
+        help="Maximum number of concurrent tasks (default: 5)",
+    )
+
+    return parser
+
+
+def format_metrics_table(metrics: dict) -> Table:
+    """Format metrics table"""
+    table = Table(title="User Experience Metrics")
+    table.add_column("Category", style="cyan")
+    table.add_column("Score", style="magenta")
+    table.add_column("Status", style="green")
+
+    # Performance metrics
+    perf = metrics.get("performance")
+    table.add_row(
+        "Performance",
+        f"{perf.success_rate if perf else 0:.2f}",
+        "✅ Good" if (perf and perf.is_good) else "❌ Needs Improvement",
+    )
+
+    # Navigation metrics
+    nav = metrics.get("navigation")
+    table.add_row(
+        "Navigation",
+        f"{nav.structure_score if nav else 0:.2f}",
+        "✅ Good" if (nav and nav.is_good) else "❌ Needs Improvement",
+    )
+
+    # Content metrics
+    content = metrics.get("content")
+    table.add_row(
+        "Content",
+        f"{content.accuracy_score if content else 0:.2f}",
+        "✅ Good" if (content and content.is_good) else "❌ Needs Improvement",
+    )
+
+    # Accessibility metrics
+    acc = metrics.get("accessibility")
+    table.add_row(
+        "Accessibility",
+        f"{1.0 if (acc and acc.is_good) else 0.0:.2f}",
+        "✅ Good" if (acc and acc.is_good) else "❌ Needs Improvement",
+    )
+
+    return table
+
+
+def format_recommendations(recommendations: list) -> Table:
+    """Format recommendations table"""
+    table = Table(title="Improvement Recommendations")
+    table.add_column("Recommendation", style="yellow")
+    table.add_column("Priority", style="red")
+
+    for i, rec in enumerate(recommendations, 1):
+        priority = "Medium"  # Default
+        if (
+            "error" in rec.lower()
+            or "keyboard" in rec.lower()
+            or "accuracy" in rec.lower()
+        ):
+            priority = "High"
+        elif "performance" in rec.lower() or "structure" in rec.lower():
+            priority = "Medium"
+        else:
+            priority = "Low"
+
+        table.add_row(f"{i}. {rec}", priority)
+
+    return table
+
+
+def format_timeline(timeline: dict) -> Table:
+    """Format timeline table"""
+    table = Table(title="Implementation Plan")
+    table.add_column("Period", style="cyan")
+    table.add_column("Tasks", style="magenta")
+
+    for period, tasks in timeline.items():
+        if tasks:
+            table.add_row(
+                period.replace("_", " ").title(),
+                "\n".join(f"• {task}" for task in tasks),
+            )
+
+    return table
+
+
+async def analyze_user_experience(
+    url: str, max_workers: int = 5, verbose: bool = False
+) -> dict:
+    """Perform user experience analysis"""
+    if verbose:
+        console.print(f"[blue]Starting user experience analysis: {url}[/blue]")
+
+    analyzer = UserExperienceAnalyzer(url, max_workers=max_workers)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+        transient=True,
+    ) as progress:
+        # Create analysis task
+        analysis_task = progress.add_task("Analyzing user experience...", total=None)
+
+        # Execute analysis
+        analysis_report = await analyzer.generate_report()
+
+        progress.update(analysis_task, completed=True)
+
+    return analysis_report
+
+
+def generate_markdown_report(analysis_report: dict, improvement_plan: dict) -> str:
+    """Generate markdown report"""
+    report = []
+
+    # Header
+    report.append("# User Experience Improvement Report")
+    report.append("")
+    report.append(f"**Analysis Target**: {analysis_report.get('base_url', 'N/A')}")
+    report.append(f"**Analysis Time**: {analysis_report.get('generated_at', 'N/A')}")
+    report.append("")
+
+    # Overall score
+    overall_score = analysis_report.get("overall_score", 0)
+    report.append(f"## Overall Score: {overall_score:.2f}")
+    report.append("")
+
+    # Metrics details
+    report.append("### Metrics Details")
+    report.append("")
+
+    # Performance metrics
+    performance = analysis_report.get("performance")
+    report.append("#### Performance")
+    report.append(
+        f"- Success Rate: {performance.success_rate if performance else 0:.2f}"
+    )
+    report.append(
+        f"- Average Load Time: {performance.load_time if performance else 0:.2f}s"
+    )
+    report.append(
+        f"- Response Time: {performance.response_time if performance else 0:.2f}s"
+    )
+    report.append(f"- Error Rate: {performance.error_rate if performance else 0:.2f}")
+    report.append("")
+
+    # Navigation metrics
+    navigation = analysis_report.get("navigation")
+    report.append("#### Navigation")
+    report.append(
+        f"- Structure Score: {navigation.structure_score if navigation else 0:.2f}"
+    )
+    report.append(f"- Link Count: {navigation.link_count if navigation else 0}")
+    report.append(f"- Depth: {navigation.depth if navigation else 0}")
+    report.append(f"- Completeness: {navigation.completeness if navigation else 0:.2f}")
+    report.append("")
+
+    # Content metrics
+    content = analysis_report.get("content")
+    report.append("#### Content")
+    report.append(f"- Accuracy: {content.accuracy_score if content else 0:.2f}")
+    report.append(f"- Completeness: {content.completeness_score if content else 0:.2f}")
+    report.append(f"- Organization: {content.organization_score if content else 0:.2f}")
+    report.append(f"- Readability: {content.readability_score if content else 0:.2f}")
+    report.append("")
+
+    # Accessibility metrics
+    accessibility = analysis_report.get("accessibility")
+    report.append("#### Accessibility")
+    report.append(
+        f"- Keyboard Navigation: {'✅' if (accessibility and accessibility.keyboard_navigation) else '❌'}"
+    )
+    report.append(
+        f"- Screen Reader Support: {'✅' if (accessibility and accessibility.screen_reader_support) else '❌'}"
+    )
+    report.append(
+        f"- Color Contrast: {'✅' if (accessibility and accessibility.color_contrast) else '❌'}"
+    )
+    report.append(
+        f"- Responsive Design: {'✅' if (accessibility and accessibility.responsive_design) else '❌'}"
+    )
+    report.append(
+        f"- ARIA Labels: {'✅' if (accessibility and accessibility.aria_labels) else '❌'}"
+    )
+    report.append("")
+
+    # Recommendations
+    report.append("### Improvement Recommendations")
+    report.append("")
+    for rec in analysis_report.get("recommendations", []):
+        report.append(f"- {rec}")
+    report.append("")
+
+    # Implementation plan
+    report.append("### Implementation Plan")
+    report.append("")
+    report.append(
+        f"**Estimated Duration**: {improvement_plan.get('estimated_duration', 'N/A')}"
+    )
+    report.append("")
+
+    timeline = improvement_plan.get("timeline", {})
+    for period, tasks in timeline.items():
+        if tasks:
+            report.append(f"#### {period.replace('_', ' ').title()}")
+            for task in tasks:
+                report.append(f"- {task}")
+            report.append("")
+
+    return "\n".join(report)
+
+
+def run_command(args) -> int:
+    """Run user experience improvement command"""
+    try:
+        # Execute analysis
+        analysis_report = asyncio.run(
+            analyze_user_experience(args.url, args.max_workers, args.verbose)
+        )
+
+        # Generate improvement plan
+        improvement_plan = generate_improvement_plan(analysis_report)
+
+        # Display results
+        if args.verbose:
+            console.print(
+                Panel.fit(
+                    f"Overall Score: {analysis_report['overall_score']:.2f}",
+                    title="Analysis Results",
+                    style="blue",
+                )
+            )
+
+        # Display metrics table
+        metrics_table = format_metrics_table(analysis_report)
+        console.print(metrics_table)
+
+        # Display recommendations
+        if analysis_report.get("recommendations"):
+            recommendations_table = format_recommendations(
+                analysis_report["recommendations"]
+            )
+            console.print(recommendations_table)
+
+        # Display implementation plan
+        if improvement_plan.get("timeline"):
+            timeline_table = format_timeline(improvement_plan["timeline"])
+            console.print(timeline_table)
+
+        # Save results
+        if args.output:
+            if args.format == "json":
+                import json
+
+                result = {
+                    "analysis": analysis_report,
+                    "improvement_plan": improvement_plan,
+                }
+                output_content = json.dumps(result, indent=2, ensure_ascii=False)
+            else:
+                output_content = generate_markdown_report(
+                    analysis_report, improvement_plan
+                )
+
+            output_path = Path(args.output)
+            output_path.write_text(output_content, encoding="utf-8")
+            console.print(f"\n[green]Results saved:[/green] {output_path}")
+
+        # Return exit code
+        if analysis_report["overall_score"] >= 0.85:
+            console.print(
+                f"\n[green]✅ User experience is excellent (score: {analysis_report['overall_score']:.2f})[/green]"
+            )
+            return 0
+        else:
+            console.print(
+                f"\n[yellow]⚠️  User experience needs improvement (score: {analysis_report['overall_score']:.2f})[/yellow]"
+            )
+            return 1
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Analysis interrupted by user.[/yellow]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]Error occurred:[/red] {e}")
+        return 1

moai_adk/cli/commands/init.py

@@ -1,4 +1,3 @@
-# @CODE:CLI-001 | @CODE:INIT-003:CLI
 # SPEC: SPEC-CLI-001.md, SPEC-INIT-003.md
 # TEST: tests/unit/test_cli_commands.py, tests/unit/test_init_reinit.py
 """MoAI-ADK init command
@@ -37,7 +36,9 @@ from rich.progress import BarColumn, Progress, SpinnerColumn, TaskID, TextColumn
 
 from moai_adk import __version__
 from moai_adk.cli.prompts import prompt_project_setup
+from moai_adk.core.mcp.setup import MCPSetupManager
 from moai_adk.core.project.initializer import ProjectInitializer
+from moai_adk.statusline.version_reader import VersionConfig, VersionReader
 from moai_adk.utils.banner import print_banner, print_welcome_message
 
 console = Console()
@@ -85,9 +86,9 @@ def create_progress_callback(progress: Progress, task_ids: Sequence[TaskID]):
 )
 @click.option(
     "--locale",
-    type=click.Choice(["ko", "en"]),
+    type=click.Choice(["ko", "en", "ja", "zh"]),
     default=None,
-    help="Preferred language (default: en)",
+    help="Preferred language (ko/en/ja/zh, default: en)",
 )
 @click.option(
     "--language",
@@ -95,6 +96,17 @@ def create_progress_callback(progress: Progress, task_ids: Sequence[TaskID]):
     default=None,
     help="Programming language (auto-detect if not specified)",
 )
+@click.option(
+    "--with-mcp",
+    multiple=True,
+    type=click.Choice(["context7", "figma", "playwright", "sequential-thinking"]),
+    help="Install MCP servers automatically (can be used multiple times)",
+)
+@click.option(
+    "--mcp-auto",
+    is_flag=True,
+    help="Auto-install all recommended MCP servers",
+)
 @click.option(
     "--force",
     is_flag=True,
@@ -106,6 +118,8 @@ def init(
     mode: str,
     locale: str,
     language: str | None,
+    with_mcp: tuple,
+    mcp_auto: bool,
     force: bool,
 ) -> None:
     """Initialize a new MoAI-ADK project
@@ -114,18 +128,38 @@ def init(
         path: Project directory path (default: current directory)
         non_interactive: Skip prompts and use defaults
         mode: Project mode (personal/team)
-        locale: Preferred language (ko/en). When omitted, defaults to en.
+        locale: Preferred language (ko/en/ja/zh). Interactive mode supports additional languages.
         language: Programming language
+        with_mcp: Install specific MCP servers (can be used multiple times)
+        mcp_auto: Auto-install all recommended MCP servers
         force: Force reinitialize without confirmation
     """
     try:
-        # 1. Print banner
+        # 1. Print banner with enhanced version info
         print_banner(__version__)
 
-        # 2. Check current directory mode
+        # 2. Enhanced version reading with error handling
+        try:
+            version_config = VersionConfig(
+                cache_ttl_seconds=10,  # Very short cache for CLI
+                fallback_version=__version__,
+                debug_mode=False,
+            )
+            version_reader = VersionReader(version_config)
+            current_version = version_reader.get_version()
+
+            # Log version info for debugging
+            console.print(f"[dim]Current MoAI-ADK version: {current_version}[/dim]")
+        except Exception as e:
+            console.print(f"[yellow]⚠️ Version read error: {e}[/yellow]")
+
+        # 3. Check current directory mode
         is_current_dir = path == "."
         project_path = Path(path).resolve()
 
+        # Initialize variables
+        custom_language = None
+
         # 3. Interactive vs Non-Interactive
         if non_interactive:
             # Non-Interactive Mode
@@ -134,10 +168,33 @@ def init(
             )
             project_name = project_path.name if is_current_dir else path
             locale = locale or "en"
+            # Language detection happens in /alfred:0-project, so default to None here
+            # This will become "generic" internally, but Summary will show more helpful message
+            if not language:
+                language = None
+
+            # Handle MCP options in non-interactive mode
+            if mcp_auto:
+                mcp_servers = ["context7", "playwright", "sequential-thinking"]
+                console.print(
+                    "[cyan]🔧 MCP servers:[/cyan] Auto-installing all recommended servers"
+                )
+            elif with_mcp:
+                mcp_servers = list(with_mcp)
+                console.print(f"[cyan]🔧 MCP servers:[/cyan] {', '.join(mcp_servers)}")
+            else:
+                mcp_servers = []
         else:
             # Interactive Mode
             print_welcome_message()
 
+            # Check for MCP CLI options in interactive mode (warn user)
+            if mcp_auto or with_mcp:
+                console.print(
+                    "[yellow]⚠️  MCP options ignored in interactive mode[/yellow]"
+                )
+                console.print("   Please use the interactive prompts instead.\n")
+
             # Interactive prompt
             answers = prompt_project_setup(
                 project_name=None if is_current_dir else path,
@@ -151,6 +208,8 @@ def init(
             locale = answers["locale"]
             language = answers["language"]
             project_name = answers["project_name"]
+            mcp_servers = answers.get("mcp_servers", [])
+            custom_language = answers.get("custom_language")
 
             console.print("\n[cyan]🚀 Starting installation...[/cyan]\n")
 
@@ -163,7 +222,9 @@ def init(
         if initializer.is_initialized():
             # Always reinitialize without confirmation (force mode by default)
             if non_interactive:
-                console.print("\n[green]🔄 Reinitializing project (force mode)...[/green]\n")
+                console.print(
+                    "\n[green]🔄 Reinitializing project (force mode)...[/green]\n"
+                )
             else:
                 # Interactive mode: Simple notification
                 console.print("\n[cyan]🔄 Reinitializing project...[/cyan]")
@@ -187,7 +248,7 @@ def init(
                     except Exception:
                         pass  # Ignore removal failures
 
-            config_path = project_path / ".moai" / "config.json"
+            config_path = project_path / ".moai" / "config" / "config.json"
             if config_path.exists():
                 try:
                     with open(config_path, "r", encoding="utf-8") as f:
@@ -196,7 +257,20 @@ def init(
                     # Update version and optimization flags
                     if "moai" not in config_data:
                         config_data["moai"] = {}
-                    config_data["moai"]["version"] = __version__
+
+                    # Use enhanced version reader for consistent version handling
+                    try:
+                        version_config = VersionConfig(
+                            cache_ttl_seconds=5,  # Very short cache for config update
+                            fallback_version=__version__,
+                            debug_mode=False,
+                        )
+                        version_reader = VersionReader(version_config)
+                        current_version = version_reader.get_version()
+                        config_data["moai"]["version"] = current_version
+                    except Exception:
+                        # Fallback to package version
+                        config_data["moai"]["version"] = __version__
 
                     if "project" not in config_data:
                         config_data["project"] = {}
@@ -230,6 +304,7 @@ def init(
                 mode=mode,
                 locale=locale,
                 language=language,
+                custom_language=custom_language,
                 backup_enabled=True,
                 progress_callback=callback,
                 reinit=True,  # Always allow reinit (force mode by default)
@@ -244,21 +319,41 @@ def init(
             console.print(separator)
             console.print("\n[cyan]📊 Summary:[/cyan]")
             console.print(f"  [dim]📁 Location:[/dim]  {result.project_path}")
-            console.print(f"  [dim]🌐 Language:[/dim]  {result.language}")
-            console.print(f"  [dim]🔧 Mode:[/dim]      {result.mode}")
-            console.print(
-                f"  [dim]🌍 Locale:[/dim]    {result.locale}"
+            # Show language more clearly - "generic" means auto-detect
+            language_display = (
+                "Auto-detect (use /alfred:0-project)"
+                if result.language == "generic"
+                else result.language
             )
+            console.print(f"  [dim]🌐 Language:[/dim]  {language_display}")
+            console.print(f"  [dim]🔧 Mode:[/dim]      {result.mode}")
+            console.print(f"  [dim]🌍 Locale:[/dim]    {result.locale}")
             console.print(
                 f"  [dim]📄 Files:[/dim]     {len(result.created_files)} created"
             )
             console.print(f"  [dim]⏱️  Duration:[/dim]  {result.duration}ms")
 
+            # Show MCP setup info
+            if mcp_servers:
+                console.print(f"  [dim]🔧 MCP Servers:[/dim] {', '.join(mcp_servers)}")
+
+            # MCP Setup (if servers selected)
+            if mcp_servers:
+                console.print("\n[cyan]🔧 Setting up MCP servers...[/cyan]")
+                mcp_manager = MCPSetupManager(project_path)
+                mcp_success = mcp_manager.setup_mcp_servers(mcp_servers)
+                if not mcp_success:
+                    console.print(
+                        "[yellow]⚠️  MCP setup completed with warnings[/yellow]"
+                    )
+
             # Show backup info if reinitialized
             if is_reinit:
                 backup_dir = project_path / ".moai-backups"
                 if backup_dir.exists():
-                    latest_backup = max(backup_dir.iterdir(), key=lambda p: p.stat().st_mtime)
+                    latest_backup = max(
+                        backup_dir.iterdir(), key=lambda p: p.stat().st_mtime
+                    )
                     console.print(f"  [dim]💾 Backup:[/dim]    {latest_backup.name}/")
 
             console.print(f"\n{separator}")
@@ -266,11 +361,19 @@ def init(
             # Show config merge notice if reinitialized
             if is_reinit:
                 console.print("\n[yellow]⚠️  Configuration Notice:[/yellow]")
-                console.print("  All template files have been [bold]force overwritten[/bold]")
-                console.print("  Previous files are backed up in [cyan].moai-backups/backup/[/cyan]")
+                console.print(
+                    "  All template files have been [bold]force overwritten[/bold]"
+                )
+                console.print(
+                    "  Previous files are backed up in [cyan].moai-backups/backup/[/cyan]"
+                )
                 console.print("\n  [cyan]To merge your previous config:[/cyan]")
-                console.print("  Run [bold]/alfred:0-project[/bold] command in Claude Code")
-                console.print("  It will merge backup config when [dim]optimized=false[/dim]\n")
+                console.print(
+                    "  Run [bold]/alfred:0-project[/bold] command in Claude Code"
+                )
+                console.print(
+                    "  It will merge backup config when [dim]optimized=false[/dim]\n"
+                )
 
             console.print("\n[cyan]🚀 Next Steps:[/cyan]")
             if not is_current_dir:
@@ -278,18 +381,40 @@ def init(
                     f"  [blue]1.[/blue] Run [bold]cd {project_name}[/bold] to enter the project"
                 )
                 console.print(
-                    "  [blue]2.[/blue] Check [bold].moai/config.json[/bold] for configuration"
+                    "  [blue]2.[/blue] Run [bold]/alfred:0-project[/bold] in Claude Code for full setup"
                 )
                 console.print(
-                    "  [blue]3.[/blue] Read [bold]CLAUDE.md[/bold] for development guide\n"
+                    "     (Configure: mode, language, report generation, etc.)"
                 )
             else:
                 console.print(
-                    "  [blue]1.[/blue] Check [bold].moai/config.json[/bold] for configuration"
+                    "  [blue]1.[/blue] Run [bold]/alfred:0-project[/bold] in Claude Code for full setup"
+                )
+                console.print(
+                    "     (Configure: mode, language, report generation, etc.)"
+                )
+
+            # Figma token setup guidance
+            if mcp_servers and "figma" in mcp_servers:
+                console.print("\n[yellow]🔐 Figma Access Token Setup:[/yellow]")
+                console.print(
+                    "  [dim]Figma MCP requires an access token to function:[/dim]"
+                )
+                console.print(
+                    "  1. Visit: https://www.figma.com/developers/api#access-tokens"
                 )
+                console.print("  2. Create a new access token")
                 console.print(
-                    "  [blue]2.[/blue] Read [bold]CLAUDE.md[/bold] for development guide\n"
+                    "  3. Run [bold]/alfred:0-project[/bold] and follow the Figma setup prompts"
                 )
+                console.print(
+                    "  4. The token will be securely stored in your environment\n"
+                )
+
+            if not is_current_dir:
+                console.print("  [blue]3.[/blue] Start developing with MoAI-ADK!\n")
+            else:
+                console.print("  [blue]2.[/blue] Start developing with MoAI-ADK!\n")
         else:
             console.print("\n[red bold]❌ Initialization Failed![/red bold]")
             if result.errors:
@@ -304,7 +429,9 @@ def init(
         raise click.Abort()
     except FileExistsError as e:
         console.print("\n[yellow]⚠ Project already initialized[/yellow]")
-        console.print("[dim]  Use 'python -m moai_adk status' to check configuration[/dim]\n")
+        console.print(
+            "[dim]  Use 'python -m moai_adk status' to check configuration[/dim]\n"
+        )
         raise click.Abort() from e
     except Exception as e:
         console.print(f"\n[red]✗ Initialization failed: {e}[/red]\n")