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

clouvel/tools/docs.py

@@ -0,0 +1,247 @@
+# -*- coding: utf-8 -*-
+"""Docs tools: PRD 템플릿, 가이드 등"""
+
+from datetime import datetime
+from mcp.types import TextContent
+
+
+async def get_prd_template(project_name: str, output_path: str) -> list[TextContent]:
+    """PRD 템플릿 생성"""
+    template = f"""# {project_name} PRD
+
+> 이 문서가 법. 여기 없으면 안 만듦.
+> 작성일: {datetime.now().strftime('%Y-%m-%d')}
+
+---
+
+## 1. 한 줄 요약
+<!-- 프로젝트가 뭔지 한 문장으로. 못 쓰면 정리 안 된 거임. -->
+
+[여기에 작성]
+
+---
+
+## 2. 핵심 원칙
+
+> 절대 안 변하는 것들. 이거 기준으로 기능 판단.
+
+1. [원칙 1]
+2. [원칙 2]
+3. [원칙 3]
+
+---
+
+## 3. 용어 정의
+
+| 용어 | 설명 |
+|------|------|
+| [용어1] | [설명] |
+
+---
+
+## 4. 입력 스펙
+
+> 외부에서 들어오는 거. 사용자 입력, API 요청 등.
+
+### 4.1 [입력 타입 1]
+- 형식:
+- 필수 필드:
+- 제한사항:
+
+---
+
+## 5. 출력 스펙
+
+> 외부로 나가는 거. UI, API 응답, 파일 등.
+
+### 5.1 [출력 타입 1]
+- 형식:
+- 필드:
+- 예시:
+
+---
+
+## 6. 에러 케이스
+
+> 터질 수 있는 모든 상황. 빠뜨리면 버그됨.
+
+| 상황 | 처리 방법 | 에러 코드 |
+|------|----------|-----------|
+| [상황1] | [방법] | [코드] |
+
+---
+
+## 7. 상태 머신
+
+> 있으면 그림으로. 상태 전이 명확하게.
+
+```
+[상태1] --이벤트--> [상태2]
+```
+
+---
+
+## 8. API 엔드포인트
+
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | /api/... | ... |
+
+---
+
+## 9. DB 스키마
+
+| 테이블 | 컬럼 | 타입 | 설명 |
+|--------|------|------|------|
+| | | | |
+
+---
+
+## 10. 검증 계획
+
+> 어떻게 테스트할 건지. 뭘 확인해야 하는지.
+
+### 10.1 단위 테스트
+- [ ] [테스트 케이스 1]
+
+### 10.2 통합 테스트
+- [ ] [테스트 케이스 1]
+
+---
+
+## 11. 변경 로그
+
+| 날짜 | 변경 내용 | 작성자 |
+|------|----------|--------|
+| {datetime.now().strftime('%Y-%m-%d')} | 최초 작성 | |
+
+"""
+    return [TextContent(type="text", text=f"```markdown\n{template}\n```\n\n출력 경로: `{output_path}`에 저장하세요.")]
+
+
+async def write_prd_section(section: str, content: str) -> list[TextContent]:
+    """PRD 섹션별 작성 가이드"""
+    guides = {
+        "summary": "한 줄 요약: 프로젝트가 뭔지 한 문장으로. 못 쓰면 정리 안 된 거임.",
+        "principles": "핵심 원칙: 절대 안 변하는 것들 3-5개. 기능 판단의 기준.",
+        "input_spec": "입력 스펙: 외부에서 들어오는 모든 것. 형식, 필수 필드, 제한사항 포함.",
+        "output_spec": "출력 스펙: 외부로 나가는 모든 것. 형식, 필드, 예시 포함.",
+        "errors": "에러 케이스: 터질 수 있는 모든 상황. 하나라도 빠뜨리면 버그됨.",
+        "state_machine": "상태 머신: 상태가 있으면 그림으로. 상태 전이 명확하게.",
+        "api_endpoints": "API 엔드포인트: Method, Path, 설명. RESTful하게.",
+        "db_schema": "DB 스키마: 테이블, 컬럼, 타입, 관계. 정규화 고려.",
+    }
+
+    guide = guides.get(section, "알 수 없는 섹션입니다.")
+    return [TextContent(type="text", text=f"## {section} 작성 가이드\n\n{guide}\n\n내용:\n{content if content else '(입력 필요)'}")]
+
+
+async def get_prd_guide() -> list[TextContent]:
+    """PRD 작성 가이드"""
+    return [TextContent(type="text", text="""# PRD 작성 가이드
+
+## 왜 PRD?
+- 코딩 전에 뭘 만들지 정리
+- 팀원/AI 간 인식 통일
+- 나중에 "이거 왜 이렇게 했지?" 방지
+
+## 작성 순서
+
+### 1단계: 핵심부터
+1. **한 줄 요약** - 못 쓰면 정리 안 된 거
+2. **핵심 원칙** - 절대 안 변하는 3가지
+
+### 2단계: 입출력
+3. **입력 스펙** - 뭐가 들어오나
+4. **출력 스펙** - 뭐가 나가나
+
+### 3단계: 예외처리
+5. **에러 케이스** - 터질 수 있는 거 다
+
+### 4단계: 상세
+6. **API** - 엔드포인트 목록
+7. **DB** - 테이블 구조
+8. **상태 머신** - 있으면
+
+### 5단계: 검증
+9. **테스트 계획** - 어떻게 확인할 건지
+
+## 팁
+- 완벽하게 쓰려고 하지 마. 일단 써.
+- 코딩하면서 업데이트해도 됨.
+- 근데 PRD에 없는 기능은 절대 안 만듦.
+""")]
+
+
+async def get_verify_checklist() -> list[TextContent]:
+    """검증 체크리스트"""
+    return [TextContent(type="text", text="""# 검증 체크리스트
+
+## PRD 검증
+- [ ] 한 줄 요약이 명확한가?
+- [ ] 핵심 원칙이 3개 이상인가?
+- [ ] 입력/출력 스펙이 구체적인가?
+- [ ] 에러 케이스가 빠짐없이 있는가?
+
+## 코드 검증
+- [ ] PRD에 명시된 기능만 구현했는가?
+- [ ] 에러 케이스 처리가 되어 있는가?
+- [ ] 테스트가 작성되어 있는가?
+
+## 배포 전 검증
+- [ ] 모든 테스트가 통과하는가?
+- [ ] lint 에러가 없는가?
+- [ ] 빌드가 성공하는가?
+""")]
+
+
+async def get_setup_guide(platform: str) -> list[TextContent]:
+    """설정 가이드"""
+    guides = {
+        "desktop": """## Claude Desktop 설정
+
+1. 설정 파일 열기: `%APPDATA%\\Claude\\claude_desktop_config.json`
+2. 아래 내용 추가:
+
+```json
+{
+  "mcpServers": {
+    "clouvel": {
+      "command": "uvx",
+      "args": ["clouvel"]
+    }
+  }
+}
+```
+
+3. Claude Desktop 재시작
+""",
+        "code": """## Claude Code (CLI) 설정
+
+```bash
+# 자동 설정
+clouvel init
+
+# 또는 수동
+clouvel init -p /path/to/project -l strict
+```
+""",
+        "vscode": """## VS Code 설정
+
+1. 확장 탭에서 "Clouvel" 검색
+2. 설치
+3. Command Palette (Ctrl+Shift+P) → "Clouvel: Setup MCP Server"
+""",
+        "cursor": """## Cursor 설정
+
+VS Code와 동일합니다. "Clouvel" 확장을 설치하세요.
+""",
+    }
+
+    if platform == "all":
+        result = "# Clouvel 설정 가이드\n\n"
+        for p, g in guides.items():
+            result += g + "\n---\n\n"
+        return [TextContent(type="text", text=result)]
+
+    return [TextContent(type="text", text=guides.get(platform, "알 수 없는 플랫폼입니다."))]

clouvel/tools/hooks.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+"""Hook tools (v0.8): hook_design, hook_verify"""
+
+import json
+from pathlib import Path
+from datetime import datetime
+from mcp.types import TextContent
+
+
+async def hook_design(path: str, trigger: str, checks: list, block_on_fail: bool) -> list[TextContent]:
+    """설계 훅 - 코드 작성 전 자동 체크포인트"""
+    project_path = Path(path)
+
+    if not project_path.exists():
+        return [TextContent(type="text", text=f"❌ 경로가 존재하지 않습니다: {path}")]
+
+    # 트리거별 기본 체크 항목
+    default_checks = {
+        "pre_code": ["prd_exists", "architecture_review", "scope_defined"],
+        "pre_feature": ["feature_in_prd", "api_spec_exists", "db_schema_ready"],
+        "pre_refactor": ["test_coverage", "backup_exists", "rollback_plan"],
+        "pre_api": ["api_spec_complete", "auth_defined", "error_codes_listed"]
+    }
+
+    # 체크 항목 설정 (사용자 지정 또는 기본값)
+    active_checks = checks if checks else default_checks.get(trigger, [])
+
+    # 훅 설정 파일 생성
+    hooks_dir = project_path / ".claude" / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    hook_config = {
+        "name": f"design_{trigger}",
+        "trigger": trigger,
+        "checks": active_checks,
+        "block_on_fail": block_on_fail,
+        "created": datetime.now().isoformat()
+    }
+
+    hook_file = hooks_dir / f"{trigger}.json"
+    hook_file.write_text(json.dumps(hook_config, indent=2, ensure_ascii=False), encoding='utf-8')
+
+    # 체크리스트 생성
+    checklist_md = "\n".join(f"- [ ] {check}" for check in active_checks)
+
+    return [TextContent(type="text", text=f"""# 설계 훅 생성 완료
+
+## 훅 설정
+
+| 항목 | 값 |
+|------|-----|
+| 트리거 | `{trigger}` |
+| 실패 시 차단 | {'예' if block_on_fail else '아니오'} |
+| 체크 항목 | {len(active_checks)}개 |
+
+## 체크리스트
+
+{checklist_md}
+
+## 저장 위치
+
+`{hook_file}`
+
+---
+
+## 사용법
+
+이 훅은 **{trigger}** 시점에 자동 트리거됩니다.
+
+```
+# 훅 실행 예시
+Claude가 코드 작성 전:
+1. can_code 확인
+2. {trigger} 훅 체크리스트 확인
+3. 모든 체크 통과 시 진행
+```
+
+**{'체크 실패 시 코드 작성이 차단됩니다.' if block_on_fail else '체크 실패해도 경고만 출력합니다.'}**
+""")]
+
+
+async def hook_verify(path: str, trigger: str, steps: list, parallel: bool, continue_on_error: bool) -> list[TextContent]:
+    """검증 훅 - 코드 완료 후 자동 검증 체크포인트"""
+    project_path = Path(path)
+
+    if not project_path.exists():
+        return [TextContent(type="text", text=f"❌ 경로가 존재하지 않습니다: {path}")]
+
+    # 트리거별 기본 단계
+    default_steps = {
+        "post_code": ["lint", "type_check"],
+        "post_feature": ["lint", "test", "build"],
+        "pre_commit": ["lint", "test", "security_scan"],
+        "pre_push": ["lint", "test", "build", "integration_test"]
+    }
+
+    # 단계 설정 (사용자 지정 또는 기본값)
+    active_steps = steps if steps else default_steps.get(trigger, ["lint", "test", "build"])
+
+    # 단계별 명령어 매핑
+    step_commands = {
+        "lint": {"cmd": "npm run lint || pylint . || ruff check .", "desc": "코드 스타일 검사"},
+        "type_check": {"cmd": "tsc --noEmit || mypy .", "desc": "타입 검사"},
+        "test": {"cmd": "npm test || pytest || go test ./...", "desc": "테스트 실행"},
+        "build": {"cmd": "npm run build || python -m build || go build", "desc": "빌드"},
+        "security_scan": {"cmd": "npm audit || safety check || gosec ./...", "desc": "보안 스캔"},
+        "integration_test": {"cmd": "npm run test:e2e || pytest tests/e2e", "desc": "통합 테스트"}
+    }
+
+    # 훅 설정 파일 생성
+    hooks_dir = project_path / ".claude" / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    hook_config = {
+        "name": f"verify_{trigger}",
+        "trigger": trigger,
+        "steps": active_steps,
+        "parallel": parallel,
+        "continue_on_error": continue_on_error,
+        "created": datetime.now().isoformat()
+    }
+
+    hook_file = hooks_dir / f"{trigger}.json"
+    hook_file.write_text(json.dumps(hook_config, indent=2, ensure_ascii=False), encoding='utf-8')
+
+    # 단계 목록 생성
+    steps_md = ""
+    for i, step in enumerate(active_steps, 1):
+        info = step_commands.get(step, {"cmd": step, "desc": "사용자 정의"})
+        steps_md += f"{i}. **{step}**: {info['desc']}\n   ```\n   {info['cmd']}\n   ```\n\n"
+
+    execution_mode = "병렬 (동시 실행)" if parallel else "순차 (하나씩 실행)"
+    error_handling = "계속 진행" if continue_on_error else "즉시 중단"
+
+    return [TextContent(type="text", text=f"""# 검증 훅 생성 완료
+
+## 훅 설정
+
+| 항목 | 값 |
+|------|-----|
+| 트리거 | `{trigger}` |
+| 실행 모드 | {execution_mode} |
+| 에러 처리 | {error_handling} |
+| 단계 수 | {len(active_steps)}개 |
+
+## 검증 단계
+
+{steps_md}
+
+## 저장 위치
+
+`{hook_file}`
+
+---
+
+## 실행 흐름
+
+```
+{trigger} 트리거 발생
+    |
+    v
+{'병렬 실행' if parallel else '순차 실행'}
+{' -> '.join(active_steps)}
+    |
+    v
+결과 리포트 생성
+```
+
+**트리거 시점: {trigger}**
+""")]