clouvel 0.3.1__py3-none-any.whl → 0.6.3__py3-none-any.whl

clouvel/tools/__init__.py

@@ -0,0 +1,75 @@
+# Clouvel Tools Package
+# 모듈별로 도구 구현을 분리
+# Free 기능만 포함 (v0.8까지)
+
+from .core import (
+    can_code,
+    scan_docs,
+    analyze_docs,
+    init_docs,
+    REQUIRED_DOCS,
+)
+
+from .docs import (
+    get_prd_template,
+    write_prd_section,
+    get_prd_guide,
+    get_verify_checklist,
+    get_setup_guide,
+)
+
+from .setup import (
+    init_clouvel,
+    setup_cli,
+)
+
+from .rules import (
+    init_rules,
+    get_rule,
+    add_rule,
+)
+
+from .verify import (
+    verify,
+    gate,
+    handoff,
+)
+
+from .planning import (
+    init_planning,
+    save_finding,
+    refresh_goals,
+    update_progress,
+)
+
+from .agents import (
+    spawn_explore,
+    spawn_librarian,
+)
+
+from .hooks import (
+    hook_design,
+    hook_verify,
+)
+
+# Pro 기능은 clouvel-pro 패키지로 분리됨
+# pip install clouvel-pro
+
+__all__ = [
+    # core
+    "can_code", "scan_docs", "analyze_docs", "init_docs", "REQUIRED_DOCS",
+    # docs
+    "get_prd_template", "write_prd_section", "get_prd_guide", "get_verify_checklist", "get_setup_guide",
+    # setup
+    "init_clouvel", "setup_cli",
+    # rules (v0.5)
+    "init_rules", "get_rule", "add_rule",
+    # verify (v0.5)
+    "verify", "gate", "handoff",
+    # planning (v0.6)
+    "init_planning", "save_finding", "refresh_goals", "update_progress",
+    # agents (v0.7)
+    "spawn_explore", "spawn_librarian",
+    # hooks (v0.8)
+    "hook_design", "hook_verify",
+]

clouvel/tools/agents.py

@@ -0,0 +1,245 @@
+# -*- coding: utf-8 -*-
+"""Agent tools (v0.7): spawn_explore, spawn_librarian"""
+
+from pathlib import Path
+from datetime import datetime
+from mcp.types import TextContent
+
+
+async def spawn_explore(path: str, query: str, scope: str, save_findings: bool) -> list[TextContent]:
+    """탐색 전문 에이전트"""
+    project_path = Path(path)
+
+    if not project_path.exists():
+        return [TextContent(type="text", text=f"❌ 경로가 존재하지 않습니다: {path}")]
+
+    # 스코프별 탐색 전략
+    scope_strategies = {
+        "file": {
+            "description": "단일 파일 분석",
+            "actions": ["파일 내용 읽기", "함수/클래스 구조 파악", "의존성 확인"],
+            "depth": 1
+        },
+        "folder": {
+            "description": "폴더 내 파일들 분석",
+            "actions": ["폴더 구조 스캔", "관련 파일 식별", "패턴 매칭"],
+            "depth": 2
+        },
+        "project": {
+            "description": "프로젝트 전체 탐색",
+            "actions": ["디렉토리 구조 파악", "엔트리포인트 찾기", "모듈 관계 분석"],
+            "depth": 3
+        },
+        "deep": {
+            "description": "심층 분석 (병렬 조사)",
+            "actions": ["전체 스캔", "크로스 레퍼런스", "의존성 그래프", "데드코드 탐지"],
+            "depth": 5
+        }
+    }
+
+    strategy = scope_strategies.get(scope, scope_strategies["project"])
+
+    # 탐색 프롬프트 생성
+    explore_prompt = f"""# 탐색 에이전트 활성화
+
+## 목표
+{query}
+
+## 탐색 전략: {strategy['description']}
+
+### 실행할 액션 (병렬 권장)
+{chr(10).join(f"- [ ] {action}" for action in strategy['actions'])}
+
+### 2-Action Rule 적용
+> view/browser 작업 2개 후 반드시 결과 저장
+
+탐색 중 발견한 내용은 즉시 기록하세요:
+- 파일 위치: `파일경로:라인번호`
+- 핵심 발견: 한 줄 요약
+- 다음 액션: 추가 탐색 필요 여부
+
+### 탐색 범위
+- 경로: `{path}`
+- 깊이: {strategy['depth']} 레벨
+- 스코프: {scope}
+
+---
+
+## 체크리스트
+
+1. [ ] 관련 파일 식별
+2. [ ] 핵심 코드 위치 파악
+3. [ ] 의존성/호출 관계 확인
+4. [ ] 결과 정리
+
+---
+
+**탐색 시작!** 위 액션들을 병렬로 실행하세요.
+"""
+
+    # findings.md에 저장 (옵션)
+    if save_findings:
+        planning_dir = project_path / ".claude" / "planning"
+        findings_file = planning_dir / "findings.md"
+
+        if findings_file.exists():
+            timestamp = datetime.now().strftime('%Y-%m-%d %H:%M')
+            finding_entry = f"""
+---
+
+## [{timestamp}] 탐색: {query}
+
+- **스코프**: {scope}
+- **상태**: 진행중
+- **결과**: *(탐색 후 업데이트)*
+
+"""
+            existing = findings_file.read_text(encoding='utf-8')
+            findings_file.write_text(existing + finding_entry, encoding='utf-8')
+
+    return [TextContent(type="text", text=explore_prompt)]
+
+
+async def spawn_librarian(path: str, topic: str, research_type: str, depth: str) -> list[TextContent]:
+    """라이브러리언 에이전트"""
+    project_path = Path(path)
+
+    if not project_path.exists():
+        return [TextContent(type="text", text=f"❌ 경로가 존재하지 않습니다: {path}")]
+
+    # 조사 타입별 전략
+    type_strategies = {
+        "library": {
+            "focus": "라이브러리 사용법",
+            "sources": ["공식 문서", "GitHub README", "npm/PyPI 페이지"],
+            "questions": [
+                "설치 방법은?",
+                "기본 사용법은?",
+                "주요 API는?",
+                "버전별 차이는?"
+            ]
+        },
+        "api": {
+            "focus": "API 스펙 조사",
+            "sources": ["API 문서", "Swagger/OpenAPI", "예제 코드"],
+            "questions": [
+                "엔드포인트 목록은?",
+                "인증 방식은?",
+                "요청/응답 형식은?",
+                "에러 코드는?"
+            ]
+        },
+        "migration": {
+            "focus": "마이그레이션 가이드",
+            "sources": ["마이그레이션 문서", "CHANGELOG", "Breaking Changes"],
+            "questions": [
+                "주요 변경사항은?",
+                "호환성 이슈는?",
+                "마이그레이션 단계는?",
+                "롤백 방법은?"
+            ]
+        },
+        "best_practice": {
+            "focus": "베스트 프랙티스",
+            "sources": ["공식 가이드", "커뮤니티 블로그", "Stack Overflow"],
+            "questions": [
+                "권장 패턴은?",
+                "안티패턴은?",
+                "성능 최적화는?",
+                "보안 고려사항은?"
+            ]
+        }
+    }
+
+    # 깊이별 조사 수준
+    depth_levels = {
+        "quick": {"time": "5분", "detail": "핵심만", "sources_count": 1},
+        "standard": {"time": "15분", "detail": "기본 + 예제", "sources_count": 2},
+        "thorough": {"time": "30분+", "detail": "심층 분석", "sources_count": 3}
+    }
+
+    strategy = type_strategies.get(research_type, type_strategies["library"])
+    level = depth_levels.get(depth, depth_levels["standard"])
+
+    # 라이브러리언 프롬프트 생성
+    librarian_prompt = f"""# 라이브러리언 에이전트 활성화
+
+## 조사 주제
+**{topic}**
+
+## 조사 전략: {strategy['focus']}
+
+### 참고할 소스 (우선순위 순)
+{chr(10).join(f"{i+1}. {src}" for i, src in enumerate(strategy['sources'][:level['sources_count']]))}
+
+### 답해야 할 질문
+{chr(10).join(f"- [ ] {q}" for q in strategy['questions'])}
+
+---
+
+## 조사 깊이: {depth.upper()}
+
+| 항목 | 값 |
+|------|-----|
+| 예상 시간 | {level['time']} |
+| 상세도 | {level['detail']} |
+| 소스 수 | {level['sources_count']}개 |
+
+---
+
+## 2-Action Rule
+
+> 외부 문서 2개 확인 후 반드시 findings.md에 기록
+
+### 기록 형식
+```markdown
+## [주제]
+
+### 질문
+(찾고 있던 것)
+
+### 발견
+(핵심 내용)
+
+### 소스
+(링크/문서명)
+
+### 결론
+(다음 액션)
+```
+
+---
+
+## 체크리스트
+
+1. [ ] 공식 문서 확인
+2. [ ] 예제 코드 수집
+3. [ ] 버전 호환성 확인
+4. [ ] 결과 정리 및 저장
+
+---
+
+**조사 시작!** `save_finding` 도구로 결과를 저장하세요.
+"""
+
+    # findings.md에 조사 시작 기록
+    planning_dir = project_path / ".claude" / "planning"
+    findings_file = planning_dir / "findings.md"
+
+    if findings_file.exists():
+        timestamp = datetime.now().strftime('%Y-%m-%d %H:%M')
+        finding_entry = f"""
+---
+
+## [{timestamp}] 조사: {topic}
+
+- **타입**: {research_type}
+- **깊이**: {depth}
+- **상태**: 진행중
+- **결과**: *(조사 후 업데이트)*
+
+"""
+        existing = findings_file.read_text(encoding='utf-8')
+        findings_file.write_text(existing + finding_entry, encoding='utf-8')
+
+    return [TextContent(type="text", text=librarian_prompt)]

clouvel/tools/core.py

@@ -0,0 +1,315 @@
+# -*- coding: utf-8 -*-
+"""Core tools: can_code, scan_docs, analyze_docs, init_docs"""
+
+import re
+from pathlib import Path
+from datetime import datetime
+from mcp.types import TextContent
+
+# 필수 문서 정의
+REQUIRED_DOCS = [
+    {"type": "prd", "name": "PRD", "patterns": [r"prd", r"product.?requirement"], "priority": "critical"},
+    {"type": "architecture", "name": "아키텍처", "patterns": [r"architect", r"arch", r"module"], "priority": "warn"},  # B4: WARN으로 변경
+    {"type": "api_spec", "name": "API 스펙", "patterns": [r"api", r"swagger", r"openapi"], "priority": "warn"},
+    {"type": "db_schema", "name": "DB 스키마", "patterns": [r"schema", r"database", r"db"], "priority": "warn"},
+    {"type": "verification", "name": "검증 계획", "patterns": [r"verif", r"test.?plan"], "priority": "warn"},
+]
+
+# PRD 필수 섹션 (B4: acceptance 없으면 BLOCK)
+REQUIRED_PRD_SECTIONS = [
+    {"name": "acceptance", "patterns": [r"##\s*(acceptance|완료\s*기준|수락\s*조건|done\s*when)"], "priority": "critical"},
+    {"name": "scope", "patterns": [r"##\s*(scope|범위|목표)"], "priority": "warn"},
+    {"name": "non_goals", "patterns": [r"##\s*(non.?goals?|하지\s*않을|제외|out\s*of\s*scope)"], "priority": "warn"},
+]
+
+
+def _find_prd_file(docs_path: Path) -> Path | None:
+    """PRD 파일 찾기"""
+    for f in docs_path.iterdir():
+        if f.is_file():
+            name_lower = f.name.lower()
+            if "prd" in name_lower or "product" in name_lower and "requirement" in name_lower:
+                return f
+    return None
+
+
+def _check_prd_sections(prd_path: Path) -> tuple[list[str], list[str], list[str]]:
+    """PRD 파일 내용에서 필수 섹션 확인
+    Returns: (found_critical, missing_critical, missing_warn)
+    """
+    try:
+        content = prd_path.read_text(encoding='utf-8')
+    except Exception:
+        return [], ["acceptance"], []
+
+    found_critical = []
+    missing_critical = []
+    missing_warn = []
+
+    for section in REQUIRED_PRD_SECTIONS:
+        found = False
+        for pattern in section["patterns"]:
+            if re.search(pattern, content, re.IGNORECASE | re.MULTILINE):
+                found = True
+                break
+
+        if found:
+            if section["priority"] == "critical":
+                found_critical.append(section["name"])
+        else:
+            if section["priority"] == "critical":
+                missing_critical.append(section["name"])
+            else:
+                missing_warn.append(section["name"])
+
+    return found_critical, missing_critical, missing_warn
+
+
+def _check_tests(project_path: Path) -> tuple[int, list[str]]:
+    """테스트 파일 확인
+    Returns: (test_count, test_files)
+    """
+    test_patterns = [r"test_.*\.py$", r".*_test\.py$", r".*\.test\.(ts|js)$", r".*\.spec\.(ts|js)$"]
+    test_files = []
+
+    # 프로젝트 루트와 하위 폴더에서 테스트 파일 검색
+    search_paths = [project_path]
+    for subdir in ["tests", "test", "src", "__tests__"]:
+        subpath = project_path / subdir
+        if subpath.exists():
+            search_paths.append(subpath)
+
+    for search_path in search_paths:
+        if not search_path.exists():
+            continue
+        try:
+            for f in search_path.rglob("*"):
+                try:
+                    if f.is_file():
+                        for pattern in test_patterns:
+                            if re.match(pattern, f.name, re.IGNORECASE):
+                                test_files.append(str(f.relative_to(project_path)))
+                                break
+                except (OSError, PermissionError):
+                    # 심볼릭 링크 깨짐, 접근 권한 없음 등 무시
+                    continue
+        except (OSError, PermissionError):
+            continue
+
+    return len(test_files), test_files[:5]  # 최대 5개만 반환
+
+
+async def can_code(path: str) -> list[TextContent]:
+    """코딩 가능 여부 확인 - 핵심 기능 (B4: 품질 게이트 확장)"""
+    docs_path = Path(path)
+    project_path = docs_path.parent if docs_path.name == "docs" else docs_path
+
+    if not docs_path.exists():
+        return [TextContent(type="text", text=f"""
+# ⛔ BLOCK: 코딩 금지
+
+## 이유
+docs 폴더가 없습니다: `{path}`
+
+## 지금 해야 할 것
+1. `docs` 폴더를 생성하세요
+2. PRD(제품 요구사항 문서)를 먼저 작성하세요
+3. `get_prd_template` 도구로 템플릿을 생성할 수 있습니다
+
+## 왜?
+PRD 없이 코딩하면:
+- 요구사항 불명확 → 재작업
+- 예외 케이스 누락 → 버그
+- 팀원 간 인식 차이 → 충돌
+
+**문서 먼저, 코딩은 나중에.**
+
+사용자에게 PRD 작성을 도와주겠다고 말하세요.
+""")]
+
+    files = [f for f in docs_path.iterdir() if f.is_file()]
+    file_names = [f.name.lower() for f in files]
+
+    detected_critical = []
+    detected_warn = []
+    missing_critical = []
+    missing_warn = []
+
+    for req in REQUIRED_DOCS:
+        found = False
+        for filename in file_names:
+            for pattern in req["patterns"]:
+                if re.search(pattern, filename, re.IGNORECASE):
+                    if req["priority"] == "critical":
+                        detected_critical.append(req["name"])
+                    else:
+                        detected_warn.append(req["name"])
+                    found = True
+                    break
+            if found:
+                break
+        if not found:
+            if req["priority"] == "critical":
+                missing_critical.append(req["name"])
+            else:
+                missing_warn.append(req["name"])
+
+    # B4: PRD 내용 검사 (acceptance 섹션 필수)
+    prd_file = _find_prd_file(docs_path)
+    prd_sections_found = []
+    prd_sections_missing_critical = []
+    prd_sections_missing_warn = []
+
+    if prd_file:
+        prd_sections_found, prd_sections_missing_critical, prd_sections_missing_warn = _check_prd_sections(prd_file)
+
+    # B4: 테스트 파일 확인
+    test_count, test_files = _check_tests(project_path)
+
+    # BLOCK 조건: PRD 없음 OR acceptance 섹션 없음
+    if missing_critical or prd_sections_missing_critical:
+        all_missing_critical = missing_critical + [f"PRD의 {s} 섹션" for s in prd_sections_missing_critical]
+        detected_list = "\n".join(f"- {d}" for d in detected_critical + detected_warn) if (detected_critical or detected_warn) else "없음"
+
+        return [TextContent(type="text", text=f"""
+# ⛔ BLOCK: 코딩 금지
+
+## 현재 상태
+✅ 있음:
+{detected_list}
+
+❌ 없음 (필수 - BLOCK):
+{chr(10).join(f'- {m}' for m in all_missing_critical)}
+
+## 지금 해야 할 것
+코드를 작성하지 마세요. 대신:
+
+1. 누락된 문서/섹션을 먼저 작성하세요
+2. **PRD에 acceptance(완료 기준) 섹션이 필수입니다**
+3. `get_prd_guide` 도구로 작성법을 확인하세요
+4. `get_prd_template` 도구로 템플릿을 생성하세요
+
+## 사용자에게 전달할 메시지
+"코드를 작성하기 전에 먼저 문서를 준비해야 합니다.
+필수 항목이 없습니다: {', '.join(all_missing_critical)}
+제가 PRD 작성을 도와드릴까요?"
+
+**절대 코드를 작성하지 마세요. 문서 작성을 도와주세요.**
+""")]
+
+    # WARN 조건: 아키텍처 없음, 테스트 0개 등
+    warn_count = len(missing_warn) + len(prd_sections_missing_warn) + (1 if test_count == 0 else 0)
+
+    # 짧은 요약 형식
+    found_docs = ", ".join(detected_critical) if detected_critical else "없음"
+    warn_items = missing_warn + [f"PRD.{s}" for s in prd_sections_missing_warn]
+    if test_count == 0:
+        warn_items.append("테스트")
+    warn_summary = ", ".join(warn_items) if warn_items else "없음"
+
+    test_info = f" | 테스트 {test_count}개" if test_count > 0 else ""
+
+    if warn_count > 0:
+        return [TextContent(type="text", text=f"✅ PASS | ⚠️ WARN {warn_count}개 | 필수: {found_docs} ✓{test_info} | 권장 없음: {warn_summary}")]
+    else:
+        return [TextContent(type="text", text=f"✅ PASS | 필수: {found_docs} ✓{test_info} | 코딩 시작 가능")]
+
+
+async def scan_docs(path: str) -> list[TextContent]:
+    """docs 폴더 스캔"""
+    docs_path = Path(path)
+
+    if not docs_path.exists():
+        return [TextContent(type="text", text=f"경로 없음: {path}")]
+
+    if not docs_path.is_dir():
+        return [TextContent(type="text", text=f"디렉토리 아님: {path}")]
+
+    files = []
+    for f in sorted(docs_path.iterdir()):
+        if f.is_file():
+            stat = f.stat()
+            files.append(f"{f.name} ({stat.st_size:,} bytes)")
+
+    result = f"📁 {path}\n총 {len(files)}개 파일\n\n"
+    result += "\n".join(files)
+
+    return [TextContent(type="text", text=result)]
+
+
+async def analyze_docs(path: str) -> list[TextContent]:
+    """docs 폴더 분석"""
+    docs_path = Path(path)
+
+    if not docs_path.exists():
+        return [TextContent(type="text", text=f"경로 없음: {path}")]
+
+    files = [f.name.lower() for f in docs_path.iterdir() if f.is_file()]
+    detected = []
+    missing = []
+
+    for req in REQUIRED_DOCS:
+        found = False
+        for filename in files:
+            for pattern in req["patterns"]:
+                if re.search(pattern, filename, re.IGNORECASE):
+                    detected.append(req["name"])
+                    found = True
+                    break
+            if found:
+                break
+        if not found:
+            missing.append(req["name"])
+
+    critical_total = len([r for r in REQUIRED_DOCS if r["priority"] == "critical"])
+    critical_found = len([r for r in REQUIRED_DOCS if r["priority"] == "critical" and r["name"] in detected])
+    coverage = critical_found / critical_total if critical_total > 0 else 1.0
+
+    result = f"## 분석 결과: {path}\n\n"
+    result += f"커버리지: {coverage:.0%}\n\n"
+
+    if detected:
+        result += "### 있음\n" + "\n".join(f"- {d}" for d in detected) + "\n\n"
+
+    if missing:
+        result += "### 없음 (작성 필요)\n" + "\n".join(f"- {m}" for m in missing) + "\n\n"
+
+    if not missing:
+        result += "✅ 필수 문서 다 있음. 바이브코딩 시작해도 됨.\n"
+    else:
+        result += f"⛔ {len(missing)}개 문서 먼저 작성하고 코딩 시작할 것.\n"
+
+    return [TextContent(type="text", text=result)]
+
+
+async def init_docs(path: str, project_name: str) -> list[TextContent]:
+    """docs 폴더 초기화 + 템플릿 생성"""
+    project_path = Path(path)
+    docs_path = project_path / "docs"
+
+    docs_path.mkdir(parents=True, exist_ok=True)
+
+    templates = {
+        "PRD.md": f"# {project_name} PRD\n\n> 작성일: {datetime.now().strftime('%Y-%m-%d')}\n\n## 한 줄 요약\n\n[작성 필요]\n\n## Acceptance (완료 기준)\n\n- [ ] [완료 조건 1]\n- [ ] [완료 조건 2]\n- [ ] [완료 조건 3]\n",
+        "ARCHITECTURE.md": f"# {project_name} 아키텍처\n\n## 시스템 구조\n\n[작성 필요]\n",
+        "API.md": f"# {project_name} API 스펙\n\n## 엔드포인트\n\n[작성 필요]\n",
+        "DATABASE.md": f"# {project_name} DB 스키마\n\n## 테이블\n\n[작성 필요]\n",
+        "VERIFICATION.md": f"# {project_name} 검증 계획\n\n## 테스트 케이스\n\n[작성 필요]\n",
+    }
+
+    created = []
+    for filename, content in templates.items():
+        file_path = docs_path / filename
+        if not file_path.exists():
+            file_path.write_text(content, encoding='utf-8')
+            created.append(filename)
+
+    result = f"## docs 폴더 초기화 완료\n\n경로: `{docs_path}`\n\n"
+    if created:
+        result += "### 생성된 파일\n" + "\n".join(f"- {f}" for f in created) + "\n\n"
+    else:
+        result += "모든 파일이 이미 존재합니다.\n\n"
+
+    result += "### 다음 단계\n1. PRD.md부터 작성하세요\n2. `get_prd_guide` 도구로 작성법을 확인하세요\n"
+
+    return [TextContent(type="text", text=result)]