shadow_brain_core/brain/coding_tools.py

# -*- coding: utf-8 -*-
"""
🔱 [Imperial Coding Arsenal] 쉐도우 브레인 에이전틱 코딩 도구 세트

Claude Code 방식의 코딩 워크플로(탐색 → 읽기 → 수정 → 검증 → 반복)를
쉐도우 브레인에 이식하기 위한 도구 모음입니다.

- Gemini AFC 경로: CodingToolkit의 public 메서드를 callable로 직접 등록
- OpenAI 호환 경로(Copilot/Atlas/OpenRouter): OPENAI_SCHEMAS + execute() 디스패처
"""
import fnmatch
import os
import re
import subprocess
import logging

logger = logging.getLogger("ShadowBrain.Coding")

# 작업 루트 — 이 바깥의 파일은 건드리지 않는다 (안전 가드)
DEFAULT_ROOT = r"D:\Git_Work\jarvis_taemin"

# 검색/탐색 시 무시할 디렉토리
_SKIP_DIRS = {
    ".git", "node_modules", "venv", ".venv", "__pycache__", "dist", "build",
    ".next", ".dart_tool", "site-packages", ".pub-cache", "docker_data",
}

# 명백히 파괴적인 명령 차단 (마왕님 PC 보호)
_BLOCKED_CMD_PATTERNS = [
    r"\bformat\b", r"\brm\s+-rf\s+/", r"\bdel\s+/s\s+/q\s+[a-z]:\\\s*$",
    r"remove-item\s+-recurse\s+-force\s+[a-z]:\\\s*$", r"\bshutdown\b", r"\bmkfs\b",
]

_TEXT_EXT_HINT = {
    ".py", ".dart", ".js", ".ts", ".tsx", ".jsx", ".json", ".yaml", ".yml",
    ".md", ".txt", ".html", ".css", ".sh", ".ps1", ".bat", ".rb", ".erb",
    ".sql", ".toml", ".ini", ".cfg", ".xml", ".csv", ".env", ".mjs", ".cjs",
}


class CodingToolkit:
    """파일 탐색/읽기/수정/검색/명령 실행 도구. 모든 경로는 작업 루트 기준 상대/절대 둘 다 허용."""

    def __init__(self, root: str = None):
        self.root = os.path.abspath(root or os.environ.get("SHADOW_CODING_ROOT", DEFAULT_ROOT))

    # ── 내부 헬퍼 ──────────────────────────────────────────────
    def _resolve(self, path: str) -> str:
        p = (path or "").strip().strip('"')
        if not p or p in (".", "./"):
            return self.root
        if not os.path.isabs(p):
            p = os.path.join(self.root, p)
        p = os.path.abspath(p)
        if os.path.commonpath([p, self.root]) != self.root:
            raise ValueError(f"작업 루트({self.root}) 바깥 경로는 허용되지 않습니다: {p}")
        return p

    @staticmethod
    def _is_text_file(path: str) -> bool:
        ext = os.path.splitext(path)[1].lower()
        if ext in _TEXT_EXT_HINT:
            return True
        try:
            with open(path, "rb") as f:
                chunk = f.read(2048)
            return b"\x00" not in chunk
        except Exception:
            return False

    def _walk(self):
        for dirpath, dirnames, filenames in os.walk(self.root):
            dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS and not d.startswith(".")]
            yield dirpath, filenames

    # ── 도구: 탐색 ─────────────────────────────────────────────
    def code_list_dir(self, path: str = ".") -> str:
        """Lists files and subdirectories at the given path (relative to the project root). Use this first to understand project structure.
        Args:
            path: Directory path relative to project root (default: root)
        """
        try:
            target = self._resolve(path)
            if not os.path.isdir(target):
                return f"Error: 디렉토리가 아닙니다: {path}"
            entries = sorted(os.listdir(target))
            lines = []
            for e in entries:
                full = os.path.join(target, e)
                if os.path.isdir(full):
                    lines.append(f"[DIR]  {e}/")
                else:
                    try:
                        size = os.path.getsize(full)
                    except OSError:
                        size = 0
                    lines.append(f"[FILE] {e} ({size:,} bytes)")
            rel = os.path.relpath(target, self.root)
            return f"# {rel} ({len(entries)} entries)\n" + "\n".join(lines[:300])
        except Exception as e:
            return f"Error: {e}"

    def code_glob(self, pattern: str, max_results: int = 100) -> str:
        """Finds files matching a glob pattern (e.g. '**/*.py', 'portal-heimdall/lib/**/*.dart'). Returns matching paths relative to project root.
        Args:
            pattern: Glob pattern. '**' matches any directories.
            max_results: Maximum number of paths to return (default 100)
        """
        try:
            pattern = (pattern or "").replace("\\", "/").lstrip("/")
            results = []
            for dirpath, filenames in self._walk():
                rel_dir = os.path.relpath(dirpath, self.root).replace("\\", "/")
                for fn in filenames:
                    rel = fn if rel_dir == "." else f"{rel_dir}/{fn}"
                    # '**/x' 패턴이 루트 바로 아래 파일도 잡도록 보정
                    if fnmatch.fnmatch(rel, pattern) or (
                        pattern.startswith("**/") and fnmatch.fnmatch(rel, pattern[3:])
                    ):
                        results.append(rel)
                        if len(results) >= max_results:
                            return "\n".join(results) + f"\n... (max {max_results} reached)"
            return "\n".join(results) if results else f"No files match: {pattern}"
        except Exception as e:
            return f"Error: {e}"

    def code_grep(self, pattern: str, file_glob: str = None, max_results: int = 50) -> str:
        """Searches file CONTENTS for a regex pattern across the project. Returns 'path:line: text' matches. Essential for finding where something is defined or used.
        Args:
            pattern: Regular expression to search for
            file_glob: Optional filename filter (e.g. '*.py', '*.dart')
            max_results: Maximum matching lines to return (default 50)
        """
        try:
            rx = re.compile(pattern)
        except re.error as e:
            return f"Error: 잘못된 정규식: {e}"
        results = []
        try:
            for dirpath, filenames in self._walk():
                for fn in filenames:
                    if file_glob and not fnmatch.fnmatch(fn, file_glob):
                        continue
                    full = os.path.join(dirpath, fn)
                    if not self._is_text_file(full):
                        continue
                    rel = os.path.relpath(full, self.root)
                    try:
                        with open(full, "r", encoding="utf-8", errors="ignore") as f:
                            for i, line in enumerate(f, 1):
                                if rx.search(line):
                                    results.append(f"{rel}:{i}: {line.rstrip()[:200]}")
                                    if len(results) >= max_results:
                                        return "\n".join(results) + f"\n... (max {max_results} reached)"
                    except OSError:
                        continue
            return "\n".join(results) if results else f"No matches for: {pattern}"
        except Exception as e:
            return f"Error: {e}"

    # ── 도구: 읽기/쓰기 ────────────────────────────────────────
    def code_read_file(self, path: str, offset: int = 1, limit: int = 400) -> str:
        """Reads a text file with line numbers. ALWAYS read a file before editing it.
        Args:
            path: File path (relative to project root or absolute)
            offset: 1-based line number to start from (default 1)
            limit: Max lines to return (default 400)
        """
        try:
            full = self._resolve(path)
            if not os.path.isfile(full):
                return f"Error: 파일이 없습니다: {path}"
            with open(full, "r", encoding="utf-8", errors="replace") as f:
                lines = f.readlines()
            total = len(lines)
            start = max(int(offset or 1), 1)
            end = min(start - 1 + int(limit or 400), total)
            body = "".join(
                f"{i:>5}\t{lines[i - 1]}" for i in range(start, end + 1)
            )
            return f"# {path} (lines {start}-{end} of {total})\n{body}"
        except Exception as e:
            return f"Error: {e}"

    def code_write_file(self, path: str, content: str) -> str:
        """Creates or fully overwrites a file with the given content (UTF-8). For small changes to existing files, prefer code_edit_file.
        Args:
            path: File path (relative to project root or absolute)
            content: Full file content to write
        """
        try:
            full = self._resolve(path)
            os.makedirs(os.path.dirname(full), exist_ok=True)
            with open(full, "w", encoding="utf-8", newline="") as f:
                f.write(content or "")
            return f"OK: wrote {len(content or '')} chars to {path}"
        except Exception as e:
            return f"Error: {e}"

    def code_edit_file(self, path: str, old_string: str, new_string: str, replace_all: bool = False) -> str:
        """Edits a file by exact string replacement. old_string must match the file content EXACTLY (including indentation) and be unique unless replace_all=true. Read the file first to copy the exact text.
        Args:
            path: File path (relative to project root or absolute)
            old_string: Exact text to find (must be unique in the file unless replace_all)
            new_string: Replacement text
            replace_all: Replace every occurrence (default false)
        """
        try:
            full = self._resolve(path)
            if not os.path.isfile(full):
                return f"Error: 파일이 없습니다: {path}"
            with open(full, "r", encoding="utf-8") as f:
                text = f.read()
            if old_string not in text:
                return "Error: old_string을 파일에서 찾지 못했습니다. code_read_file로 정확한 원문(들여쓰기 포함)을 복사해 다시 시도하세요."
            count = text.count(old_string)
            if count > 1 and not replace_all:
                return f"Error: old_string이 {count}번 등장합니다. 더 길고 고유한 문자열을 쓰거나 replace_all=true를 지정하세요."
            new_text = text.replace(old_string, new_string) if replace_all else text.replace(old_string, new_string, 1)
            with open(full, "w", encoding="utf-8", newline="") as f:
                f.write(new_text)
            n = count if replace_all else 1
            return f"OK: {path} — {n}곳 수정 완료"
        except Exception as e:
            return f"Error: {e}"

    # ── 도구: 명령 실행(검증) ──────────────────────────────────
    def code_run_command(self, command: str, cwd: str = None, timeout: int = 120) -> str:
        """Runs a shell command (PowerShell on Windows) and returns stdout/stderr/exit code. Use to verify changes: run tests, compile checks (python -m py_compile, flutter analyze), git status, etc.
        Args:
            command: The command line to execute
            cwd: Working directory relative to project root (default: project root)
            timeout: Seconds before the command is killed (default 120, max 600)
        """
        try:
            low = (command or "").lower()
            for pat in _BLOCKED_CMD_PATTERNS:
                if re.search(pat, low):
                    return f"Error: 파괴적 명령이 차단되었습니다: {command}"
            workdir = self._resolve(cwd) if cwd else self.root
            timeout = min(max(int(timeout or 120), 5), 600)
            if os.name == "nt":
                cmd = ["powershell", "-NoProfile", "-NonInteractive", "-Command", command]
            else:
                cmd = ["bash", "-lc", command]
            proc = subprocess.run(
                cmd, cwd=workdir, capture_output=True, timeout=timeout,
            )
            out = proc.stdout.decode("utf-8", errors="replace")
            err = proc.stderr.decode("utf-8", errors="replace")
            res = f"[exit code: {proc.returncode}]\n"
            if out.strip():
                res += f"--- stdout ---\n{out[-6000:]}\n"
            if err.strip():
                res += f"--- stderr ---\n{err[-3000:]}\n"
            return res.strip()
        except subprocess.TimeoutExpired:
            return f"Error: 명령이 {timeout}초 안에 끝나지 않아 중단했습니다: {command}"
        except Exception as e:
            return f"Error: {e}"

    # ── OpenAI 호환 디스패처 ──────────────────────────────────
    TOOL_NAMES = (
        "code_list_dir", "code_glob", "code_grep",
        "code_read_file", "code_write_file", "code_edit_file", "code_run_command",
    )

    def handles(self, name: str) -> bool:
        return name in self.TOOL_NAMES

    def execute(self, name: str, args: dict) -> str:
        if not self.handles(name):
            return f"Error: unknown coding tool '{name}'"
        try:
            return getattr(self, name)(**(args or {}))
        except TypeError as e:
            return f"Error: 잘못된 인자: {e}"

    def callables(self):
        """Gemini AFC 경로용 — bound method 리스트."""
        return [getattr(self, n) for n in self.TOOL_NAMES]


def _schema(name, desc, props, required):
    return {
        "type": "function",
        "function": {
            "name": name,
            "description": desc,
            "parameters": {"type": "object", "properties": props, "required": required},
        },
    }


OPENAI_SCHEMAS = [
    _schema(
        "code_list_dir",
        "Lists files and subdirectories at a path inside the project. Use first to learn the project layout.",
        {"path": {"type": "string", "description": "Directory path relative to project root (default '.')"}},
        [],
    ),
    _schema(
        "code_glob",
        "Finds files by glob pattern, e.g. '**/*.py' or 'portal-heimdall/lib/**/*.dart'. Returns relative paths.",
        {
            "pattern": {"type": "string", "description": "Glob pattern ('**' = any directories)"},
            "max_results": {"type": "integer", "description": "Max paths (default 100)"},
        },
        ["pattern"],
    ),
    _schema(
        "code_grep",
        "Searches file CONTENTS with a regex across the project. Returns 'path:line: text'. Use to find where code is defined or used.",
        {
            "pattern": {"type": "string", "description": "Regular expression"},
            "file_glob": {"type": "string", "description": "Filename filter, e.g. '*.py'"},
            "max_results": {"type": "integer", "description": "Max matching lines (default 50)"},
        },
        ["pattern"],
    ),
    _schema(
        "code_read_file",
        "Reads a text file with line numbers. ALWAYS read before editing.",
        {
            "path": {"type": "string", "description": "File path (relative or absolute)"},
            "offset": {"type": "integer", "description": "1-based start line (default 1)"},
            "limit": {"type": "integer", "description": "Max lines (default 400)"},
        },
        ["path"],
    ),
    _schema(
        "code_write_file",
        "Creates or fully overwrites a file (UTF-8). Prefer code_edit_file for small changes.",
        {
            "path": {"type": "string", "description": "File path"},
            "content": {"type": "string", "description": "Full file content"},
        },
        ["path", "content"],
    ),
    _schema(
        "code_edit_file",
        "Edits a file by EXACT string replacement. old_string must match exactly (indentation included) and be unique unless replace_all.",
        {
            "path": {"type": "string", "description": "File path"},
            "old_string": {"type": "string", "description": "Exact text to find"},
            "new_string": {"type": "string", "description": "Replacement text"},
            "replace_all": {"type": "boolean", "description": "Replace all occurrences (default false)"},
        },
        ["path", "old_string", "new_string"],
    ),
    _schema(
        "code_run_command",
        "Runs a shell command (PowerShell) in the project and returns output + exit code. Use to VERIFY changes: tests, py_compile, flutter analyze, git status.",
        {
            "command": {"type": "string", "description": "Command line to run"},
            "cwd": {"type": "string", "description": "Working dir relative to project root"},
            "timeout": {"type": "integer", "description": "Seconds (default 120, max 600)"},
        },
        ["command"],
    ),
]


# 시스템 지시에 덧붙일 에이전틱 코딩 워크플로 가이드
CODING_AGENT_GUIDE = """

## 🛠️ 에이전틱 코딩 수칙 (Imperial Coding Protocol)
너는 코딩 도구(code_*)를 가진 자율 코딩 에이전트다. 코드 관련 요청을 받으면 추측으로 답하지 말고 반드시 도구로 확인하라.

작업 순서 (반드시 준수):
1. **탐색**: code_grep / code_glob / code_list_dir 로 관련 파일과 코드를 먼저 찾는다. 파일 위치를 추측하지 마라.
2. **읽기**: code_read_file 로 수정할 부분의 실제 코드를 읽는다. 읽지 않은 파일을 수정하는 것은 금지다.
3. **수정**: code_edit_file 로 정확한 원문(들여쓰기 포함)을 복사해 교체한다. 새 파일만 code_write_file 을 쓴다.
4. **검증**: code_run_command 로 검증한다 (python -m py_compile, flutter analyze, 테스트 실행 등). 검증 없이 "완료"라고 보고하지 마라.
5. **반복**: 검증이 실패하면 오류 메시지를 읽고 1번부터 다시 수행한다. 같은 실패를 반복하면 접근을 바꿔라.

규칙:
- 도구 결과(파일 내용, 검색 결과)에 근거해서만 말하라. 존재를 확인하지 않은 파일/함수를 언급하지 마라.
- 수정은 최소 범위로 하고, 주변 코드의 스타일을 따른다.
- 실패하면 솔직하게 실패했다고 보고하고 원인과 다음 시도를 설명한다.
"""