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

clouvel/tools/planning.py

@@ -0,0 +1,320 @@
+# -*- coding: utf-8 -*-
+"""Planning tools (v0.6): init_planning, save_finding, refresh_goals, update_progress"""
+
+from pathlib import Path
+from datetime import datetime
+from mcp.types import TextContent
+
+
+async def init_planning(path: str, task: str, goals: list) -> list[TextContent]:
+    """영속적 컨텍스트 초기화"""
+    project_path = Path(path)
+
+    if not project_path.exists():
+        return [TextContent(type="text", text=f"❌ 경로가 존재하지 않습니다: {path}")]
+
+    planning_dir = project_path / ".claude" / "planning"
+    planning_dir.mkdir(parents=True, exist_ok=True)
+
+    # task_plan.md 생성
+    goals_md = "\n".join(f"- [ ] {g}" for g in goals) if goals else "- [ ] (목표 정의 필요)"
+
+    task_plan_content = f"""# Task Plan
+
+> 생성일: {datetime.now().strftime('%Y-%m-%d %H:%M')}
+
+---
+
+## 현재 작업
+
+{task}
+
+---
+
+## 목표
+
+{goals_md}
+
+---
+
+## 접근 방식
+
+(작업 시작 전 계획 작성)
+
+---
+
+## 제약 조건
+
+- PRD에 명시된 범위 내에서만 작업
+- 테스트 없이 배포 금지
+
+---
+
+> 💡 `refresh_goals` 도구로 현재 목표를 리마인드할 수 있습니다.
+"""
+
+    # findings.md 생성
+    findings_content = f"""# Findings
+
+> 조사 결과 기록
+> 생성일: {datetime.now().strftime('%Y-%m-%d %H:%M')}
+
+---
+
+## 2-Action Rule
+
+> view/browser 작업 2개 후 반드시 여기에 기록!
+
+---
+
+(아직 기록 없음)
+"""
+
+    # progress.md 생성
+    progress_content = f"""# Progress
+
+> 마지막 업데이트: {datetime.now().strftime('%Y-%m-%d %H:%M')}
+
+---
+
+## 완료 (Completed)
+
+*(아직 없음)*
+
+---
+
+## 진행중 (In Progress)
+
+*(없음)*
+
+---
+
+## 블로커 (Blockers)
+
+*(없음)*
+
+---
+
+## 다음 할 일 (Next)
+
+*(결정 필요)*
+
+---
+
+> 💡 업데이트: `update_progress` 도구 호출
+"""
+
+    # 파일 생성
+    (planning_dir / "task_plan.md").write_text(task_plan_content, encoding='utf-8')
+    (planning_dir / "findings.md").write_text(findings_content, encoding='utf-8')
+    (planning_dir / "progress.md").write_text(progress_content, encoding='utf-8')
+
+    return [TextContent(type="text", text=f"""# 영속적 컨텍스트 초기화 완료
+
+## 생성된 파일
+
+| 파일 | 용도 |
+|------|------|
+| `task_plan.md` | 작업 계획 + 목표 |
+| `findings.md` | 조사 결과 기록 |
+| `progress.md` | 진행 상황 추적 |
+
+## 경로
+`{planning_dir}`
+
+## 다음 단계
+
+1. 목표 확인: `refresh_goals`
+2. 조사 기록: `save_finding`
+3. 진행 업데이트: `update_progress`
+
+**긴 세션에서도 목표를 잃지 마세요!**
+""")]
+
+
+async def save_finding(path: str, topic: str, question: str, findings: str, source: str, conclusion: str) -> list[TextContent]:
+    """조사 결과 저장"""
+    project_path = Path(path)
+    findings_file = project_path / ".claude" / "planning" / "findings.md"
+
+    if not findings_file.exists():
+        return [TextContent(type="text", text="❌ findings.md가 없습니다. 먼저 `init_planning` 도구로 초기화하세요.")]
+
+    timestamp = datetime.now().strftime('%Y-%m-%d %H:%M')
+    finding_entry = f"""
+---
+
+## [{timestamp}] {topic}
+
+### 질문
+{question if question else '(명시되지 않음)'}
+
+### 발견
+{findings}
+
+### 소스
+{source if source else '(없음)'}
+
+### 결론
+{conclusion if conclusion else '(추가 조사 필요)'}
+
+"""
+
+    existing = findings_file.read_text(encoding='utf-8')
+    findings_file.write_text(existing + finding_entry, encoding='utf-8')
+
+    return [TextContent(type="text", text=f"""# Finding 저장 완료
+
+## 요약
+
+| 항목 | 내용 |
+|------|------|
+| 주제 | {topic} |
+| 질문 | {question or '없음'} |
+| 소스 | {source or '없음'} |
+
+## 저장 위치
+`{findings_file}`
+
+---
+
+**2-Action Rule 준수!**
+""")]
+
+
+async def refresh_goals(path: str) -> list[TextContent]:
+    """목표 리마인드"""
+    project_path = Path(path)
+    task_plan_file = project_path / ".claude" / "planning" / "task_plan.md"
+    progress_file = project_path / ".claude" / "planning" / "progress.md"
+
+    if not task_plan_file.exists():
+        return [TextContent(type="text", text="❌ task_plan.md가 없습니다. 먼저 `init_planning` 도구로 초기화하세요.")]
+
+    task_plan = task_plan_file.read_text(encoding='utf-8')
+    progress = progress_file.read_text(encoding='utf-8') if progress_file.exists() else "(없음)"
+
+    # 목표 추출
+    goals = []
+    in_goals_section = False
+    for line in task_plan.split("\n"):
+        if "## 목표" in line:
+            in_goals_section = True
+        elif line.startswith("## "):
+            in_goals_section = False
+        elif in_goals_section and line.strip().startswith("- "):
+            goals.append(line.strip())
+
+    goals_md = "\n".join(goals) if goals else "*(목표 없음)*"
+
+    return [TextContent(type="text", text=f"""# 목표 리마인드
+
+## 현재 작업
+
+(task_plan.md 참조)
+
+## 목표
+
+{goals_md}
+
+---
+
+## 현재 진행 상황
+
+{progress[:500]}{'...' if len(progress) > 500 else ''}
+
+---
+
+## 다음 액션
+
+1. 위 목표 중 하나를 선택
+2. 해당 목표에 집중
+3. 완료되면 `update_progress`로 기록
+
+**"지금 뭐하고 있었지?" → 위 목표를 확인하세요!**
+""")]
+
+
+async def update_progress(path: str, completed: list, in_progress: str, blockers: list, next_item: str) -> list[TextContent]:
+    """진행 상황 업데이트"""
+    project_path = Path(path)
+    progress_file = project_path / ".claude" / "planning" / "progress.md"
+
+    if not progress_file.exists():
+        return [TextContent(type="text", text="❌ progress.md가 없습니다. 먼저 `init_planning` 도구로 초기화하세요.")]
+
+    existing = progress_file.read_text(encoding='utf-8')
+
+    # 기존 완료 항목 파싱
+    existing_completed = []
+    in_completed_section = False
+
+    for line in existing.split("\n"):
+        if "## 완료" in line:
+            in_completed_section = True
+        elif line.startswith("## "):
+            in_completed_section = False
+        elif in_completed_section and line.strip().startswith("- "):
+            item = line.strip()[2:]
+            if item and item != "*(아직 없음)*":
+                existing_completed.append(item)
+
+    # 새 완료 항목 추가
+    all_completed = existing_completed + list(completed)
+    completed_md = "\n".join(f"- {c}" for c in all_completed) if all_completed else "*(아직 없음)*"
+    blockers_md = "\n".join(f"- {b}" for b in blockers) if blockers else "*(없음)*"
+
+    # 새 progress.md 생성
+    new_progress = f"""# Progress
+
+> 마지막 업데이트: {datetime.now().strftime('%Y-%m-%d %H:%M')}
+
+---
+
+## 완료 (Completed)
+
+{completed_md}
+
+---
+
+## 진행중 (In Progress)
+
+{f"- {in_progress}" if in_progress else "*(없음)*"}
+
+---
+
+## 블로커 (Blockers)
+
+{blockers_md}
+
+---
+
+## 다음 할 일 (Next)
+
+{next_item if next_item else "*(결정 필요)*"}
+
+---
+
+> 💡 업데이트: `update_progress` 도구 호출
+"""
+
+    progress_file.write_text(new_progress, encoding='utf-8')
+
+    return [TextContent(type="text", text=f"""# Progress 업데이트 완료
+
+## 요약
+
+| 항목 | 개수/내용 |
+|------|----------|
+| 완료 | {len(all_completed)}개 |
+| 진행중 | {in_progress if in_progress else '없음'} |
+| 블로커 | {len(blockers)}개 |
+| 다음 | {next_item if next_item else '미정'} |
+
+## 저장 위치
+`{progress_file}`
+
+---
+
+**진행 상황이 기록되었습니다!**
+""")]

clouvel/tools/rules.py

@@ -0,0 +1,223 @@
+# -*- coding: utf-8 -*-
+"""Rules tools (v0.5): init_rules, get_rule, add_rule"""
+
+import json
+from pathlib import Path
+from datetime import datetime
+from mcp.types import TextContent
+
+
+async def init_rules(path: str, template: str) -> list[TextContent]:
+    """규칙 모듈화 초기화"""
+    project_path = Path(path)
+
+    if not project_path.exists():
+        return [TextContent(type="text", text=f"❌ 경로가 존재하지 않습니다: {path}")]
+
+    rules_dir = project_path / ".claude" / "rules"
+    rules_dir.mkdir(parents=True, exist_ok=True)
+
+    # 템플릿별 규칙 파일
+    templates = {
+        "minimal": ["global.md", "security.md"],
+        "web": ["global.md", "security.md", "frontend.md"],
+        "api": ["global.md", "security.md", "api.md", "database.md"],
+        "fullstack": ["global.md", "security.md", "frontend.md", "api.md", "database.md"],
+    }
+
+    files_to_create = templates.get(template, templates["minimal"])
+    created = []
+
+    # 규칙 파일 내용
+    rule_contents = {
+        "global.md": """# Global Rules
+
+## ALWAYS
+- Read before Edit
+- Check PRD before implementing
+- Update progress after completing
+
+## NEVER
+- Skip documentation
+- Implement features not in PRD
+- Commit without tests
+""",
+        "security.md": """# Security Rules
+
+## ALWAYS
+- Validate user input
+- Use parameterized queries
+- Escape output for XSS prevention
+
+## NEVER
+- Store passwords in plain text
+- Expose sensitive data in logs
+- Trust client-side validation alone
+""",
+        "frontend.md": """# Frontend Rules
+
+## ALWAYS
+- Use semantic HTML
+- Handle loading/error states
+- Support keyboard navigation
+
+## NEVER
+- Use inline styles for complex CSS
+- Mutate props directly
+- Skip accessibility attributes
+""",
+        "api.md": """# API Rules
+
+## ALWAYS
+- Return consistent response format
+- Include proper HTTP status codes
+- Document all endpoints
+
+## NEVER
+- Expose internal errors to clients
+- Use GET for state-changing operations
+- Skip rate limiting
+""",
+        "database.md": """# Database Rules
+
+## ALWAYS
+- Use migrations for schema changes
+- Index foreign keys
+- Use transactions for multi-step operations
+
+## NEVER
+- Store JSON for relational data
+- Skip backup before migration
+- Use SELECT * in production
+""",
+    }
+
+    for filename in files_to_create:
+        file_path = rules_dir / filename
+        if not file_path.exists():
+            file_path.write_text(rule_contents.get(filename, f"# {filename}\n\n[규칙 작성]"), encoding='utf-8')
+            created.append(filename)
+
+    # rules.index.json 생성
+    index_content = {
+        "version": "0.5.0",
+        "template": template,
+        "rules": [
+            {"file": f, "scope": "**/*", "priority": 100 - i * 10}
+            for i, f in enumerate(files_to_create)
+        ]
+    }
+    index_file = rules_dir / "rules.index.json"
+    index_file.write_text(json.dumps(index_content, indent=2, ensure_ascii=False), encoding='utf-8')
+
+    created_list = "\n".join(f"- {f}" for f in created) if created else "없음 (이미 존재)"
+
+    return [TextContent(type="text", text=f"""# 규칙 모듈화 완료
+
+## 템플릿
+**{template}**
+
+## 생성된 파일
+{created_list}
+
+## 경로
+`{rules_dir}`
+
+## 사용법
+- `get_rule`로 파일별 규칙 로딩
+- `add_rule`로 새 규칙 추가
+
+**컨텍스트 절약 50%+ 효과!**
+""")]
+
+
+async def get_rule(path: str, context: str) -> list[TextContent]:
+    """경로 기반 규칙 로딩"""
+    file_path = Path(path)
+
+    # 프로젝트 루트 찾기
+    current = file_path if file_path.is_dir() else file_path.parent
+    rules_dir = None
+
+    for _ in range(10):  # 최대 10레벨 상위까지
+        potential = current / ".claude" / "rules"
+        if potential.exists():
+            rules_dir = potential
+            break
+        if current.parent == current:
+            break
+        current = current.parent
+
+    if not rules_dir:
+        return [TextContent(type="text", text="❌ .claude/rules/ 폴더를 찾을 수 없습니다. `init_rules`로 먼저 생성하세요.")]
+
+    # 규칙 파일 로딩
+    rules = []
+    for rule_file in rules_dir.glob("*.md"):
+        rules.append(f"## {rule_file.stem}\n\n{rule_file.read_text(encoding='utf-8')}")
+
+    if not rules:
+        return [TextContent(type="text", text="❌ 규칙 파일이 없습니다.")]
+
+    context_note = f"\n\n> 컨텍스트: {context}" if context != "coding" else ""
+
+    return [TextContent(type="text", text=f"""# 적용 규칙
+
+경로: `{path}`{context_note}
+
+---
+
+{chr(10).join(rules)}
+""")]
+
+
+async def add_rule(path: str, rule_type: str, content: str, category: str) -> list[TextContent]:
+    """새 규칙 추가"""
+    project_path = Path(path)
+    rules_dir = project_path / ".claude" / "rules"
+
+    if not rules_dir.exists():
+        return [TextContent(type="text", text="❌ .claude/rules/ 폴더가 없습니다. `init_rules`로 먼저 생성하세요.")]
+
+    # 카테고리 파일 선택
+    category_files = {
+        "api": "api.md",
+        "frontend": "frontend.md",
+        "database": "database.md",
+        "security": "security.md",
+        "general": "global.md",
+    }
+    target_file = rules_dir / category_files.get(category, "global.md")
+
+    # 파일이 없으면 생성
+    if not target_file.exists():
+        target_file.write_text(f"# {category.title()} Rules\n\n", encoding='utf-8')
+
+    # 규칙 추가
+    existing = target_file.read_text(encoding='utf-8')
+    rule_section = f"\n## {rule_type.upper()}\n- {content}\n"
+
+    # 같은 타입 섹션이 있으면 거기에 추가
+    if f"## {rule_type.upper()}" in existing:
+        existing = existing.replace(f"## {rule_type.upper()}\n", f"## {rule_type.upper()}\n- {content}\n")
+        target_file.write_text(existing, encoding='utf-8')
+    else:
+        target_file.write_text(existing + rule_section, encoding='utf-8')
+
+    return [TextContent(type="text", text=f"""# 규칙 추가 완료
+
+## 상세
+
+| 항목 | 값 |
+|------|-----|
+| 타입 | {rule_type.upper()} |
+| 카테고리 | {category} |
+| 파일 | {target_file.name} |
+
+## 내용
+{content}
+
+---
+
+규칙이 `{target_file}`에 추가되었습니다.
+""")]

clouvel/tools/setup.py

@@ -0,0 +1,166 @@
+# -*- coding: utf-8 -*-
+"""Setup tools: init_clouvel, setup_cli"""
+
+import json
+from pathlib import Path
+from mcp.types import TextContent
+
+
+async def init_clouvel(platform: str) -> list[TextContent]:
+    """Clouvel 온보딩"""
+    if platform == "ask":
+        return [TextContent(type="text", text="""# Clouvel 온보딩
+
+어떤 환경에서 사용하시나요?
+
+1. **Claude Desktop** - GUI 앱
+2. **VS Code / Cursor** - IDE 확장
+3. **Claude Code (CLI)** - 터미널
+
+선택해 주시면 맞춤 설정을 안내해 드립니다.
+
+예: "Claude Code에서 사용할 거야" 또는 "1번"
+""")]
+
+    guides = {
+        "desktop": """# Claude Desktop 설정 완료!
+
+MCP 서버가 이미 연결되어 있습니다.
+
+## 사용법
+대화에서 "코딩해도 돼?" 또는 "can_code로 확인해줘" 라고 말하세요.
+
+## 주요 도구
+- `can_code` - 코딩 가능 여부 확인
+- `init_docs` - 문서 템플릿 생성
+- `get_prd_guide` - PRD 작성 가이드
+""",
+        "vscode": """# VS Code / Cursor 설정 안내
+
+## 설치 방법
+1. 확장 탭에서 "Clouvel" 검색
+2. 설치
+3. Command Palette (Ctrl+Shift+P)
+4. "Clouvel: Setup MCP Server" 실행
+
+## CLI도 설정하시겠어요?
+"CLI도 설정해줘" 라고 말씀하시면 추가 설정을 진행합니다.
+""",
+        "cli": """# Claude Code (CLI) 설정 안내
+
+## 자동 설정
+```bash
+clouvel init
+```
+
+## 수동 설정
+```bash
+clouvel init -p /path/to/project -l strict
+```
+
+## 강제 수준
+- `remind` - 경고만
+- `strict` - 커밋 차단 (추천)
+- `full` - Hooks + 커밋 차단
+
+어떤 수준으로 설정할까요?
+""",
+    }
+
+    return [TextContent(type="text", text=guides.get(platform, guides["cli"]))]
+
+
+async def setup_cli(path: str, level: str) -> list[TextContent]:
+    """CLI 환경 설정"""
+    project_path = Path(path).resolve()
+
+    if not project_path.exists():
+        return [TextContent(type="text", text=f"❌ 경로가 존재하지 않습니다: {path}")]
+
+    created_files = []
+
+    # 1. .claude 폴더 생성
+    claude_dir = project_path / ".claude"
+    claude_dir.mkdir(exist_ok=True)
+
+    # 2. hooks.json (remind, full)
+    if level in ["remind", "full"]:
+        hooks_content = {
+            "hooks": {
+                "preToolUse": [
+                    {
+                        "matcher": "Edit|Write|NotebookEdit",
+                        "hooks": [
+                            {
+                                "type": "command",
+                                "command": "echo '[Clouvel] 코드 작성 전 can_code 도구로 문서 상태를 확인하세요!'"
+                            }
+                        ]
+                    }
+                ]
+            }
+        }
+        hooks_file = claude_dir / "hooks.json"
+        hooks_file.write_text(json.dumps(hooks_content, indent=2, ensure_ascii=False), encoding='utf-8')
+        created_files.append(".claude/hooks.json")
+
+    # 3. CLAUDE.md 규칙
+    claude_md = project_path / "CLAUDE.md"
+    clouvel_rule = """
+## Clouvel 규칙 (자동 생성)
+
+> 이 규칙은 Clouvel이 자동으로 추가했습니다.
+
+### 필수 준수 사항
+1. **코드 작성 전 문서 체크**: Edit/Write 도구 사용 전 반드시 `can_code` 도구를 먼저 호출
+2. **can_code 실패 시 코딩 금지**: 필수 문서가 없으면 PRD 작성부터
+3. **PRD가 법**: docs/PRD.md에 없는 기능은 구현하지 않음
+"""
+
+    if claude_md.exists():
+        existing = claude_md.read_text(encoding='utf-8')
+        if "Clouvel 규칙" not in existing:
+            claude_md.write_text(existing + "\n" + clouvel_rule, encoding='utf-8')
+            created_files.append("CLAUDE.md (규칙 추가)")
+    else:
+        claude_md.write_text(f"# {project_path.name}\n" + clouvel_rule, encoding='utf-8')
+        created_files.append("CLAUDE.md (생성)")
+
+    # 4. pre-commit hook (strict, full)
+    if level in ["strict", "full"]:
+        git_hooks_dir = project_path / ".git" / "hooks"
+        if git_hooks_dir.exists():
+            pre_commit = git_hooks_dir / "pre-commit"
+            pre_commit_content = '''#!/bin/sh
+# Clouvel pre-commit hook
+DOCS_DIR="./docs"
+if ! ls "$DOCS_DIR"/*[Pp][Rr][Dd]* 1> /dev/null 2>&1; then
+    echo "[Clouvel] BLOCKED: No PRD document found."
+    echo "Please create docs/PRD.md first."
+    exit 1
+fi
+echo "[Clouvel] Document check passed."
+'''
+            pre_commit.write_text(pre_commit_content, encoding='utf-8')
+            created_files.append(".git/hooks/pre-commit")
+
+    files_list = "\n".join(f"- {f}" for f in created_files) if created_files else "없음"
+
+    return [TextContent(type="text", text=f"""# CLI 설정 완료
+
+## 프로젝트
+`{project_path}`
+
+## 강제 수준
+**{level}**
+
+## 생성/수정된 파일
+{files_list}
+
+## 다음 단계
+1. `docs/PRD.md` 생성
+2. Claude에게 "코딩해도 돼?" 질문
+3. PRD 없으면 코딩 차단됨
+
+**PRD 없으면 코딩 없다!**
+""")]