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

moai_adk/__init__.py

@@ -9,6 +9,6 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("moai-adk")
 except PackageNotFoundError:
-    __version__ = "0.4.1-dev"
+    __version__ = "0.5.6-dev"
 
 __all__ = ["__version__"]

moai_adk/__main__.py

@@ -38,7 +38,7 @@ def show_logo() -> None:
     console.print(__version__, style="cyan bold")
     console.print()
     console.print("  Tip: Run ", style="yellow", end="")
-    console.print("python -m moai_adk --help", style="cyan", end="")
+    console.print("uv run moai-adk --help", style="cyan", end="")
     console.print(" to see available commands", style="yellow")
 
 
@@ -61,6 +61,48 @@ cli.add_command(backup)
 cli.add_command(update)
 
 
+# 링크 검증 명령
+@click.command(name='validate-links')
+@click.option('--file', '-f', default='README.ko.md', help='검증할 파일 경로 (기본값: README.ko.md)')
+@click.option('--max-concurrent', '-c', type=int, default=3, help='동시에 검증할 최대 링크 수 (기본값: 3)')
+@click.option('--timeout', '-t', type=int, default=8, help='요청 타임아웃 (초) (기본값: 8)')
+@click.option('--output', '-o', help='결과를 저장할 파일 경로')
+@click.option('--verbose', '-v', is_flag=True, help='상세한 진행 상황 표시')
+def validate_links(file, max_concurrent, timeout, output, verbose):
+    """온라인 문서 링크 검증"""
+    from moai_adk.cli.commands.validate_links import run_command as validate_links_run
+
+    # CLI 명령 실행
+    sys.exit(validate_links_run(locals()))
+
+
+# 사용자 경험 개선 명령
+@click.command(name='improve-ux')
+@click.option('--url', '-u', default='https://adk.mo.ai.kr', help='분석할 URL (기본값: https://adk.mo.ai.kr)')
+@click.option('--output', '-o', help='분석 결과를 저장할 파일 경로')
+@click.option('--format', '-f', type=click.Choice(['json', 'markdown', 'text']),
+              default='markdown', help='출력 형식 (기본값: markdown)')
+@click.option('--verbose', '-v', is_flag=True, help='상세한 진행 상황 표시')
+@click.option('--max-workers', '-w', type=int, default=5, help='동시에 처리할 최대 작업 수 (기본값: 5)')
+def improve_ux(url, output, format, verbose, max_workers):
+    """사용자 경험 개선 분석"""
+    # 임시 args 객체 생성
+    class Args:
+        def __init__(self, **kwargs):
+            for key, value in kwargs.items():
+                setattr(self, key, value)
+
+    args = Args(url=url, output=output, format=format, verbose=verbose, max_workers=max_workers)
+
+    # CLI 명령 실행
+    from moai_adk.cli.commands.improve_user_experience import run_command as improve_ux_run
+    sys.exit(improve_ux_run(args))
+
+
+cli.add_command(validate_links)
+cli.add_command(improve_ux)
+
+
 def main() -> int:
     """CLI entry point"""
     try:
@@ -82,3 +124,34 @@ def main() -> int:
 
 if __name__ == "__main__":
     sys.exit(main())
+
+
+# Sync 명령어 추가
+@click.command(name='sync')
+@click.option('--skip-docs', is_flag=True, help='문서 동기화 건너뛰기')
+@click.option('--skip-tags', is_flag=True, help='TAG 검증 건너뛰기')
+@click.option('--apply-dedup', is_flag=True, help='TAG 중복 제거 적용')
+@click.option('--dry-run', is_flag=True, default=True, help='시뮬레이션 모드 (기본값: True)')
+def sync_command_func(skip_docs, skip_tags, apply_dedup, dry_run):
+    """MoAI-ADK 프로젝트 동기화 (TAG 중복 제거 포함)"""
+    options = {
+        "skip_docs": skip_docs,
+        "skip_tags": skip_tags,
+        "apply_dedup": apply_dedup,
+        "dry_run": dry_run
+    }
+
+    from moai_adk.cli.commands.sync import sync as sync_cli
+    sys.exit(sync_cli(options))
+
+cli.add_command(sync_command_func)
+
+# Sync 명령어 추가
+def sync_command():
+    """Sync command wrapper"""
+    import sys
+    sys.path.insert(0, 'src')
+    from moai_adk.cli.commands.sync_main import main as sync_main
+    sys.exit(sync_main())
+
+cli.add_command(sync_command, name='sync')

moai_adk/cli/commands/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
+# @CODE:CLI-003 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
 """CLI command module
 
 Core commands:

moai_adk/cli/commands/analyze.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""
+Analyze command for MoAI-ADK
+
+Analyze Claude Code sessions and generate improvement suggestions.
+"""
+
+# @CODE:CLI-002 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
+
+from pathlib import Path
+from typing import Optional
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from moai_adk.core.analysis.session_analyzer import SessionAnalyzer
+
+console = Console()
+
+
+@click.command()
+@click.option("--days", "-d", default=7, help="Number of days to analyze (default: 7)")
+@click.option("--output", "-o", type=click.Path(), help="Output file path")
+@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
+@click.option("--report-only", "-r", is_flag=True, help="Generate report only (no console output)")
+@click.option("--project-path", "-p", type=click.Path(), help="Project root path (default: current directory)")
+def analyze(
+    days: int,
+    output: Optional[Path],
+    verbose: bool,
+    report_only: bool,
+    project_path: Optional[Path],
+):
+    """
+    Analyze Claude Code sessions from the last N days
+
+    Analyzes Claude Code session logs to identify usage patterns,
+    error frequencies, and generate improvement suggestions.
+
+    Examples:
+        moai-adk analyze session
+        moai-adk analyze session --days 14 --verbose
+        moai-adk analyze session --output /path/to/report.md
+    """
+    if project_path is None:
+        project_path = Path.cwd()
+
+    # Validate project path
+    if not (project_path / ".moai").exists():
+        console.print("[red]Error:[/red] Not a MoAI-ADK project (missing .moai directory)")
+        console.print(f"[blue]Current path:[/blue] {project_path}")
+        return
+
+    # Initialize analyzer
+    analyzer = SessionAnalyzer(days_back=days, verbose=verbose)
+
+    if not report_only:
+        console.print(f"[blue]📊 Analyzing sessions from last {days} days...[/blue]")
+
+    # Parse sessions
+    patterns = analyzer.parse_sessions()
+
+    if not report_only:
+        console.print(f"[green]✅ Analyzed {patterns['total_sessions']} sessions[/green]")
+        console.print(f"[blue]   Total events: {patterns['total_events']}[/blue]")
+
+        # Display summary table
+        table = Table(title="Session Summary")
+        table.add_column("Metric", style="cyan")
+        table.add_column("Value", style="green")
+
+        table.add_row("Total Sessions", str(patterns['total_sessions']))
+        table.add_row("Total Events", str(patterns['total_events']))
+        table.add_row("Failed Sessions", str(patterns['failed_sessions']))
+        table.add_row("Success Rate", f"{patterns.get('success_rate', 0):.1f}%")
+
+        console.print(table)
+
+        # Show top tools
+        if patterns['tool_usage']:
+            console.print("\n[bold]🔧 Top Tools Used:[/bold]")
+            top_tools = sorted(
+                patterns['tool_usage'].items(),
+                key=lambda x: x[1],
+                reverse=True
+            )[:10]
+
+            tools_table = Table()
+            tools_table.add_column("Tool", style="cyan")
+            tools_table.add_column("Usage", style="green")
+
+            for tool, count in top_tools:
+                tools_table.add_row(f"`{tool}`", str(count))
+
+            console.print(tools_table)
+
+    # Save report
+    output_path_obj = Path(output) if output else None
+    report_path = analyzer.save_report(output_path_obj, project_path)
+
+    if not report_only:
+        console.print(f"\n[green]📄 Report saved: {report_path}[/green]")
+
+        # Show key suggestions
+        report_content = analyzer.generate_report()
+        if "💡 개선 제안" in report_content:
+            console.print("\n[bold yellow]💡 Key Suggestions:[/bold yellow]")
+            # Extract suggestions section
+            suggestions_start = report_content.find("💡 개선 제안")
+            if suggestions_start != -1:
+                suggestions_section = report_content[suggestions_start:]
+                # Extract first few suggestions
+                lines = suggestions_section.split('\n')[2:]  # Skip header and empty line
+                for line in lines[:10]:  # Show first 10 lines
+                    if line.strip() and not line.startswith("---"):
+                        console.print(line)
+
+

moai_adk/cli/commands/backup.py

@@ -1,4 +1,28 @@
-"""Backup command"""
+"""Backup command
+
+Create a backup of the current project including:
+- .claude/ (entire directory)
+- .moai/ (excluding specs and reports)
+- CLAUDE.md
+
+Backup location: .moai-backups/YYYYMMDD-HHMMSS/
+
+## Skill Invocation Guide (English-Only)
+
+### Related Skills
+- **moai-foundation-git**: For Git workflow and backup management
+  - Trigger: Before creating critical backups, review Git state
+  - Invocation: `Skill("moai-foundation-git")` for backup naming conventions
+
+### When to Invoke Skills in Related Workflows
+1. **Before backup creation**:
+   - Run `Skill("moai-foundation-git")` to document current Git branch state
+   - Tag backup with feature branch name for easier recovery
+
+2. **After restoration from backup**:
+   - Verify with `Skill("moai-foundation-tags")` that TAGs are intact
+   - Run `Skill("moai-foundation-trust")` to validate toolchain
+"""
 from pathlib import Path
 
 import click

moai_adk/cli/commands/doctor.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_doctor.py
+# @CODE:CLI-003 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_doctor.py
 # @CODE:CLAUDE-COMMANDS-001:CLI | SPEC: SPEC-CLAUDE-COMMANDS-001/spec.md | TEST: tests/unit/test_slash_commands.py
 """MoAI-ADK doctor command
 
@@ -8,6 +8,30 @@ System diagnostics command:
 - Validate project structure
 - Inspect language-specific tool chains
 - Diagnose slash command loading issues (--check-commands)
+
+## Skill Invocation Guide (English-Only)
+
+### Related Skills
+- **moai-foundation-langs**: For language toolchain verification and detection
+  - Trigger: Use `--verbose` or `--fix` flag to inspect language-specific tools
+  - Invocation: `Skill("moai-foundation-langs")` for detailed language stack analysis
+
+- **moai-foundation-trust**: For TRUST 5-principles verification after fixing tools
+  - Trigger: After running doctor with `--fix` to validate improvements
+  - Invocation: `Skill("moai-foundation-trust")` to verify code quality toolchain
+
+### When to Invoke Skills in Related Workflows
+1. **After doctor diagnosis**:
+   - Run `Skill("moai-foundation-trust")` to validate that all TRUST tools are properly configured
+   - Run `Skill("moai-foundation-langs")` to confirm language-specific toolchains
+
+2. **When tools are missing** (`--fix` flag):
+   - Use suggested fixes from doctor command
+   - Follow up with `Skill("moai-foundation-langs")` to validate corrections
+
+3. **Debugging slash command issues** (`--check-commands`):
+   - Run `Skill("moai-cc-commands")` if commands fail to load
+   - Check `.claude/commands/` directory structure and permissions
 """
 
 import json
@@ -168,11 +192,13 @@ def _suggest_fixes(tools: dict[str, bool], language: str | None) -> None:
 
 def _get_install_command(tool: str, language: str | None) -> str:
     """Return the install command for a given tool (helper)"""
-    # Common tools
+    # Common tools with preferred package managers
     install_commands = {
-        "pytest": "pip install pytest",
-        "mypy": "pip install mypy",
-        "ruff": "pip install ruff",
+        # Python tools (prefer uv)
+        "pytest": "uv pip install pytest",
+        "mypy": "uv pip install mypy",
+        "ruff": "uv pip install ruff",
+        # JavaScript tools
         "vitest": "npm install -D vitest",
         "biome": "npm install -D @biomejs/biome",
         "eslint": "npm install -D eslint",

moai_adk/cli/commands/improve_user_experience.py

@@ -0,0 +1,307 @@
+# @CODE:USER-EXPERIENCE-CLI-001 | @TEST:USER-EXPERIENCE-CLI-001
+
+"""
+User Experience Improvement CLI Command
+사용자 경험 개선 CLI 명령어
+"""
+
+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:
+    """사용자 경험 개선 파서 생성"""
+    parser = subparsers.add_parser(
+        'improve-ux',
+        help='사용자 경험 개선 분석',
+        description='온라인 문서 포털의 사용자 경험을 분석하고 개선 계획을 제공합니다'
+    )
+
+    parser.add_argument(
+        '--url', '-u',
+        type=str,
+        default='https://adk.mo.ai.kr',
+        help='분석할 URL (기본값: https://adk.mo.ai.kr)'
+    )
+
+    parser.add_argument(
+        '--output', '-o',
+        type=str,
+        help='분석 결과를 저장할 파일 경로'
+    )
+
+    parser.add_argument(
+        '--format', '-f',
+        type=str,
+        choices=['json', 'markdown', 'text'],
+        default='markdown',
+        help='출력 형식 (기본값: markdown)'
+    )
+
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='상세한 진행 상황 표시'
+    )
+
+    parser.add_argument(
+        '--max-workers', '-w',
+        type=int,
+        default=5,
+        help='동시에 처리할 최대 작업 수 (기본값: 5)'
+    )
+
+    return parser
+
+
+def format_metrics_table(metrics: dict) -> Table:
+    """지표 테이블 형식화"""
+    table = Table(title="사용자 경험 지표")
+    table.add_column("분야", style="cyan")
+    table.add_column("점수", style="magenta")
+    table.add_column("상태", style="green")
+
+    # 성능 지표
+    perf = metrics.get('performance')
+    table.add_row("성능", f"{perf.success_rate if perf else 0:.2f}",
+                  "✅ 좋음" if (perf and perf.is_good) else "❌ 개선 필요")
+
+    # 네비게이션 지표
+    nav = metrics.get('navigation')
+    table.add_row("네비게이션", f"{nav.structure_score if nav else 0:.2f}",
+                  "✅ 좋음" if (nav and nav.is_good) else "❌ 개선 필요")
+
+    # 콘텐츠 지표
+    content = metrics.get('content')
+    table.add_row("콘텐츠", f"{content.accuracy_score if content else 0:.2f}",
+                  "✅ 좋음" if (content and content.is_good) else "❌ 개선 필요")
+
+    # 접근성 지표
+    acc = metrics.get('accessibility')
+    table.add_row("접근성", f"{1.0 if (acc and acc.is_good) else 0.0:.2f}",
+                  "✅ 좋음" if (acc and acc.is_good) else "❌ 개선 필요")
+
+    return table
+
+
+def format_recommendations(recommendations: list) -> Table:
+    """개선 제안 테이블 형식화"""
+    table = Table(title="개선 제안")
+    table.add_column("제안", style="yellow")
+    table.add_column("우선순위", style="red")
+
+    for i, rec in enumerate(recommendations, 1):
+        priority = "중간"  # 기본값
+        if "에러" in rec or "키보드" in rec or "정확성" in rec:
+            priority = "높음"
+        elif "성능" in rec or "구조" in rec:
+            priority = "중간"
+        else:
+            priority = "낮음"
+
+        table.add_row(f"{i}. {rec}", priority)
+
+    return table
+
+
+def format_timeline(timeline: dict) -> Table:
+    """실행 계획 테이블 형식화"""
+    table = Table(title="실행 계획")
+    table.add_column("기간", style="cyan")
+    table.add_column("작업", 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:
+    """사용자 경험 분석 수행"""
+    if verbose:
+        console.print(f"[blue]사용자 경험 분석 시작: {url}[/blue]")
+
+    analyzer = UserExperienceAnalyzer(url, max_workers=max_workers)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+        transient=True
+    ) as progress:
+        # 분석 작업 생성
+        analysis_task = progress.add_task("사용자 경험 분석 중...", total=None)
+
+        # 분석 실행
+        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:
+    """마크다운 보고서 생성"""
+    report = []
+
+    # 헤더
+    report.append("# 사용자 경험 개선 보고서")
+    report.append("")
+    report.append(f"**분석 대상**: {analysis_report.get('base_url', 'N/A')}")
+    report.append(f"**분석 시간**: {analysis_report.get('generated_at', 'N/A')}")
+    report.append("")
+
+    # 전체 점수
+    overall_score = analysis_report.get('overall_score', 0)
+    report.append(f"## 전체 점수: {overall_score:.2f}")
+    report.append("")
+
+    # 지표 상세
+    report.append("### 지표 상세")
+    report.append("")
+
+    # 성능 지표
+    performance = analysis_report.get('performance')
+    report.append("#### 성능")
+    report.append(f"- 성공률: {performance.success_rate if performance else 0:.2f}")
+    report.append(f"- 평균 로드 시간: {performance.load_time if performance else 0:.2f}초")
+    report.append(f"- 응답 시간: {performance.response_time if performance else 0:.2f}초")
+    report.append(f"- 에러율: {performance.error_rate if performance else 0:.2f}")
+    report.append("")
+
+    # 네비게이션 지표
+    navigation = analysis_report.get('navigation')
+    report.append("#### 네비게이션")
+    report.append(f"- 구조 점수: {navigation.structure_score if navigation else 0:.2f}")
+    report.append(f"- 링크 수: {navigation.link_count if navigation else 0}")
+    report.append(f"- 깊이: {navigation.depth if navigation else 0}")
+    report.append(f"- 완성도: {navigation.completeness if navigation else 0:.2f}")
+    report.append("")
+
+    # 콘텐츠 지표
+    content = analysis_report.get('content')
+    report.append("#### 콘텐츠")
+    report.append(f"- 정확성: {content.accuracy_score if content else 0:.2f}")
+    report.append(f"- 완성도: {content.completeness_score if content else 0:.2f}")
+    report.append(f"- 조직성: {content.organization_score if content else 0:.2f}")
+    report.append(f"- 가독성: {content.readability_score if content else 0:.2f}")
+    report.append("")
+
+    # 접근성 지표
+    accessibility = analysis_report.get('accessibility')
+    report.append("#### 접근성")
+    report.append(f"- 키보드 네비게이션: {'✅' if (accessibility and accessibility.keyboard_navigation) else '❌'}")
+    report.append(f"- 스크린 리더 지원: {'✅' if (accessibility and accessibility.screen_reader_support) else '❌'}")
+    report.append(f"- 색상 대비: {'✅' if (accessibility and accessibility.color_contrast) else '❌'}")
+    report.append(f"- 반응형 디자인: {'✅' if (accessibility and accessibility.responsive_design) else '❌'}")
+    report.append(f"- ARIA 레이블: {'✅' if (accessibility and accessibility.aria_labels) else '❌'}")
+    report.append("")
+
+    # 개선 제안
+    report.append("### 개선 제안")
+    report.append("")
+    for rec in analysis_report.get('recommendations', []):
+        report.append(f"- {rec}")
+    report.append("")
+
+    # 실행 계획
+    report.append("### 실행 계획")
+    report.append("")
+    report.append(f"**예상 소요 시간**: {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:
+    """사용자 경험 개선 명령 실행"""
+    try:
+        # 분석 실행
+        analysis_report = asyncio.run(
+            analyze_user_experience(args.url, args.max_workers, args.verbose)
+        )
+
+        # 개선 계획 생성
+        improvement_plan = generate_improvement_plan(analysis_report)
+
+        # 결과 출력
+        if args.verbose:
+            console.print(Panel.fit(
+                f"전체 점수: {analysis_report['overall_score']:.2f}",
+                title="분석 결과",
+                style="blue"
+            ))
+
+        # 지표 테이블 표시
+        metrics_table = format_metrics_table(analysis_report)
+        console.print(metrics_table)
+
+        # 개선 제안 표시
+        if analysis_report.get('recommendations'):
+            recommendations_table = format_recommendations(analysis_report['recommendations'])
+            console.print(recommendations_table)
+
+        # 실행 계획 표시
+        if improvement_plan.get('timeline'):
+            timeline_table = format_timeline(improvement_plan['timeline'])
+            console.print(timeline_table)
+
+        # 결과 저장
+        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]결과가 저장되었습니다:[/green] {output_path}")
+
+        # 종료 코드 반환
+        if analysis_report['overall_score'] >= 0.85:
+            console.print(
+            f"\n[green]✅ 사용자 경험이 우수합니다 (점수: {analysis_report['overall_score']:.2f})[/green]"
+        )
+            return 0
+        else:
+            console.print(
+                f"\n[yellow]⚠️  사용자 경험이 개선 필요합니다 (점수: {analysis_report['overall_score']:.2f})[/yellow]"
+            )
+            return 1
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]분석이 사용자에 의해 중단되었습니다.[/yellow]")
+        return 1
+    except Exception as e:
+        console.print(f"[red]오류 발생:[/red] {e}")
+        return 1