cade-cli 0.3.3__py3-none-any.whl

cadecoder/tools/builtin.py

@@ -0,0 +1,644 @@
+"""Builtin tools for CadeCoder."""
+
+import fnmatch
+import json
+import pathlib
+import subprocess
+from collections.abc import Callable
+from typing import Annotated, Any, Literal
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.errors import ToolExecutionError
+
+from cadecoder.core.constants import (
+    DEFAULT_IGNORE_PATTERNS,
+    MAX_LIST_DEPTH,
+    MAX_LIST_RESULTS,
+    MAX_PREVIEW_BYTES,
+    MODE_APPEND,
+    MODE_OVERWRITE,
+)
+from cadecoder.core.logging import log
+from cadecoder.tools.filesystem import (
+    generate_diff_from_content,
+    read_text_file,
+    write_text_file,
+)
+from cadecoder.tools.git import get_current_branch_name, get_status
+
+
+def get_project_root() -> pathlib.Path:
+    """Get the project root directory."""
+    return pathlib.Path.cwd()
+
+
+PROJECT_ROOT = get_project_root()
+
+
+class PathResolver:
+    """Resolve and validate paths safely."""
+
+    @staticmethod
+    def resolve_safe_path(path_str: str, base_dir: pathlib.Path) -> pathlib.Path:
+        """Resolve a path safely within a base directory."""
+        path = pathlib.Path(path_str)
+        if path.is_absolute():
+            resolved = path.resolve()
+        else:
+            resolved = (base_dir / path).resolve()
+        return resolved
+
+
+# --- Helper Functions ---
+
+
+def _should_ignore(path: pathlib.Path, ignore_patterns: list[str]) -> bool:
+    """Check if a path should be ignored based on patterns."""
+    path_str = str(path)
+    name = path.name
+
+    for pattern in ignore_patterns:
+        if pattern.startswith("*."):
+            if name.endswith(pattern[1:]):
+                return True
+        elif "*" in pattern:
+            if fnmatch.fnmatch(name, pattern):
+                return True
+        else:
+            if pattern in path_str.split("/"):
+                return True
+            if name == pattern:
+                return True
+    return False
+
+
+# --- File Management Tools ---
+
+
+@tool(
+    name="Local_ListFiles",
+    desc="List files in a directory (recursively up to a depth limit).",
+)
+def list_files_tool(
+    context: ToolContext,
+    directory: Annotated[
+        str | None,
+        "Directory path to list (relative to project root). Defaults to current directory.",
+    ] = ".",
+    recursive: Annotated[bool, "Whether to list files recursively."] = True,
+    depth: Annotated[
+        int, "Maximum depth for listing files. 0 means no depth limit."
+    ] = MAX_LIST_DEPTH,
+) -> Annotated[dict, "Output containing a list of files and an optional message."]:
+    """Lists files and directories within a specified path."""
+    if not 0 <= depth <= MAX_LIST_DEPTH:
+        raise ToolExecutionError(f"Depth must be between 0 and {MAX_LIST_DEPTH}")
+
+    base_path = PathResolver.resolve_safe_path(directory or ".", PROJECT_ROOT)
+    if not base_path.is_dir():
+        raise ToolExecutionError(f"Not a directory: {directory or '.'}")
+
+    listed_paths: list[str] = []
+    if not recursive:
+        for item in base_path.iterdir():
+            try:
+                if _should_ignore(item, DEFAULT_IGNORE_PATTERNS):
+                    continue
+                relative_to_project = item.relative_to(PROJECT_ROOT)
+                listed_paths.append(str(relative_to_project))
+                if len(listed_paths) >= MAX_LIST_RESULTS:
+                    break
+            except ValueError:
+                continue
+            except OSError as e:
+                log.warning(f"Error processing path {item}: {e}")
+                continue
+    else:
+        queue: list[tuple[pathlib.Path, int]] = [
+            (child, 0)
+            for child in base_path.iterdir()
+            if not _should_ignore(child, DEFAULT_IGNORE_PATTERNS)
+        ]
+
+        while queue:
+            if len(listed_paths) >= MAX_LIST_RESULTS:
+                break
+            current_item, item_depth = queue.pop(0)
+
+            if item_depth > depth:
+                continue
+
+            try:
+                relative_to_project = current_item.relative_to(PROJECT_ROOT)
+                listed_paths.append(str(relative_to_project))
+
+                if current_item.is_dir() and item_depth < depth:
+                    for child in current_item.iterdir():
+                        if not _should_ignore(child, DEFAULT_IGNORE_PATTERNS):
+                            queue.append((child, item_depth + 1))
+            except ValueError:
+                continue
+            except OSError as e:
+                log.warning(f"Error processing path {current_item}: {e}")
+                continue
+
+    message = None
+    if len(listed_paths) >= MAX_LIST_RESULTS:
+        message = f"... (truncated at {MAX_LIST_RESULTS} entries)"
+
+    listed_paths.sort()
+
+    return {
+        "files": listed_paths,
+        "message": message if message else "Files listed successfully.",
+    }
+
+
+@tool(
+    name="Local_ReadFile",
+    desc="Read the entire content of a text file from the workspace.",
+)
+def read_file_tool(
+    context: ToolContext,
+    file_path_arg: Annotated[str, "Path to the file to read (relative or absolute)."],
+) -> Annotated[dict, "Output containing the file content and an optional message."]:
+    """Reads content of a specified file."""
+    file_path = PathResolver.resolve_safe_path(file_path_arg, PROJECT_ROOT)
+    if not file_path.is_file():
+        raise ToolExecutionError(f"File not found: {file_path_arg} (resolved: {file_path})")
+
+    try:
+        size = file_path.stat().st_size
+        if size > MAX_PREVIEW_BYTES:
+            log.warning(f"File {file_path_arg} exceeds preview limit. Truncating.")
+            with file_path.open("rb") as f:
+                start_bytes = f.read(MAX_PREVIEW_BYTES // 2)
+                f.seek(max(0, size - MAX_PREVIEW_BYTES // 2))
+                end_bytes = f.read(MAX_PREVIEW_BYTES // 2)
+            start_str = start_bytes.decode("utf-8", errors="replace")
+            end_str = end_bytes.decode("utf-8", errors="replace")
+            content = start_str + f"\n... (file truncated, size: {size} bytes) ...\n" + end_str
+            return {"content": content, "message": "File was truncated due to size."}
+        else:
+            content = read_text_file(file_path)
+            return {"content": content, "message": "File read successfully."}
+    except OSError as e:
+        raise ToolExecutionError(f"Error accessing file {file_path_arg}: {e}") from e
+
+
+@tool(
+    name="Local_WriteFile",
+    desc="Write content to a file, creating/overwriting or appending.",
+)
+def write_file_tool(
+    context: ToolContext,
+    file_path_arg: Annotated[str, "Path of the file to write."],
+    content: Annotated[str, "The complete content to write into the file."],
+    mode: Annotated[
+        Literal["overwrite", "append"],
+        f"How to write: '{MODE_OVERWRITE}' to replace all content, '{MODE_APPEND}' to add to the end.",
+    ] = "overwrite",
+) -> Annotated[dict, "Result of the write operation."]:
+    """Writes content to a file."""
+    resolved_path = PathResolver.resolve_safe_path(file_path_arg, PROJECT_ROOT)
+
+    try:
+        if mode == MODE_APPEND and resolved_path.exists():
+            existing_content = read_text_file(resolved_path)
+            content = existing_content + content
+
+        write_text_file(resolved_path, content)
+        return {
+            "success": True,
+            "message": f"Successfully wrote to {file_path_arg}",
+        }
+    except Exception as e:
+        raise ToolExecutionError(f"Failed to write file {file_path_arg}: {e}") from e
+
+
+# --- Command Execution Tools ---
+
+
+@tool(name="Local_ExecuteCommand", desc="Execute a shell command. Use with caution.")
+def execute_command_tool(
+    context: ToolContext,
+    command: Annotated[str, "The shell command to execute."],
+    cwd: Annotated[
+        str | None,
+        "Working directory for the command (relative to project root).",
+    ] = None,
+    timeout: Annotated[int, "Timeout for the command in seconds."] = 30,
+) -> Annotated[dict, "Output of the command execution."]:
+    """Executes a shell command."""
+    if cwd:
+        working_dir = PathResolver.resolve_safe_path(cwd, PROJECT_ROOT)
+        if not working_dir.is_dir():
+            raise ToolExecutionError(f"Working directory not found: {cwd}")
+    else:
+        working_dir = PROJECT_ROOT
+
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            cwd=str(working_dir),
+            capture_output=True,
+            text=True,
+            timeout=timeout if timeout > 0 else None,
+        )
+
+        return {
+            "stdout": result.stdout if result.stdout else "no output",
+            "stderr": result.stderr if result.stderr else "no stderr",
+            "exit_code": result.returncode,
+            "success": result.returncode == 0,
+        }
+    except subprocess.TimeoutExpired:
+        raise ToolExecutionError(f"Command timed out after {timeout} seconds")
+    except Exception as e:
+        log.error(f"Command execution failed: {e}")
+        raise ToolExecutionError(f"Command execution failed: {e}") from e
+
+
+# --- Search Tool (Simple ripgrep-based) ---
+
+
+@tool(
+    name="Local_SearchCode",
+    desc="Search for files containing specific text or patterns using ripgrep.",
+)
+def search_code_tool(
+    context: ToolContext,
+    pattern: Annotated[str, "Text or regex pattern to search for."],
+    directory: Annotated[str, "Directory to search in (relative to project root)."] = ".",
+    file_extensions: Annotated[
+        list[str] | None,
+        "File extensions to search (e.g., ['py', 'js']). None searches all.",
+    ] = None,
+    case_sensitive: Annotated[bool, "Whether search should be case sensitive."] = False,
+    max_results: Annotated[int, "Maximum number of results to return."] = 100,
+) -> Annotated[dict[str, Any], "Search results with file paths and matching lines."]:
+    """Searches for files containing specific patterns using ripgrep."""
+    if not pattern or not pattern.strip():
+        raise ToolExecutionError("Search pattern cannot be empty.")
+
+    safe_dir = PathResolver.resolve_safe_path(directory, PROJECT_ROOT)
+    if not safe_dir.exists() or not safe_dir.is_dir():
+        return {
+            "results": [],
+            "summary": {
+                "total_matches": 0,
+                "error": f"Directory '{directory}' not found or not a directory",
+            },
+        }
+
+    # Build ripgrep command
+    rg_cmd = ["rg", "--json", "-m", str(max_results)]
+    if not case_sensitive:
+        rg_cmd.append("-i")
+    if file_extensions:
+        for ext in file_extensions:
+            rg_cmd.extend(["-g", f"*.{ext.lstrip('.')}"])
+
+    # Add ignore patterns
+    for ignore in DEFAULT_IGNORE_PATTERNS:
+        rg_cmd.extend(["-g", f"!{ignore}"])
+
+    rg_cmd.append(pattern)
+    rg_cmd.append(str(safe_dir))
+
+    try:
+        result = subprocess.run(
+            rg_cmd,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+
+        results = []
+        files_with_matches = set()
+
+        for line in result.stdout.strip().split("\n"):
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                if data.get("type") == "match":
+                    match_data = data.get("data", {})
+                    path = match_data.get("path", {}).get("text", "")
+                    line_num = match_data.get("line_number", 0)
+                    line_text = match_data.get("lines", {}).get("text", "").strip()
+
+                    # Make path relative
+                    try:
+                        rel_path = str(pathlib.Path(path).relative_to(PROJECT_ROOT))
+                    except ValueError:
+                        rel_path = path
+
+                    results.append(
+                        {
+                            "file": rel_path,
+                            "line": line_num,
+                            "content": line_text,
+                        }
+                    )
+                    files_with_matches.add(rel_path)
+            except json.JSONDecodeError:
+                continue
+
+        return {
+            "results": results,
+            "summary": {
+                "total_matches": len(results),
+                "files_with_matches": len(files_with_matches),
+                "pattern_searched": pattern,
+            },
+        }
+    except FileNotFoundError:
+        # ripgrep not installed, fall back to grep
+        log.warning("ripgrep not found, falling back to grep")
+        return _search_with_grep(pattern, safe_dir, case_sensitive, max_results)
+    except subprocess.TimeoutExpired:
+        raise ToolExecutionError("Search timed out")
+    except Exception as e:
+        log.error(f"Search failed: {e}")
+        raise ToolExecutionError(f"Search failed: {e}") from e
+
+
+def _search_with_grep(
+    pattern: str,
+    directory: pathlib.Path,
+    case_sensitive: bool,
+    max_results: int,
+) -> dict[str, Any]:
+    """Fallback search using grep."""
+    grep_cmd = ["grep", "-rn"]
+    if not case_sensitive:
+        grep_cmd.append("-i")
+    grep_cmd.extend([pattern, str(directory)])
+
+    try:
+        result = subprocess.run(
+            grep_cmd,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+
+        results = []
+        files_with_matches = set()
+
+        for line in result.stdout.strip().split("\n")[:max_results]:
+            if not line:
+                continue
+            # Parse grep output: file:line:content
+            parts = line.split(":", 2)
+            if len(parts) >= 3:
+                try:
+                    rel_path = str(pathlib.Path(parts[0]).relative_to(PROJECT_ROOT))
+                except ValueError:
+                    rel_path = parts[0]
+
+                results.append(
+                    {
+                        "file": rel_path,
+                        "line": int(parts[1]) if parts[1].isdigit() else 0,
+                        "content": parts[2].strip(),
+                    }
+                )
+                files_with_matches.add(rel_path)
+
+        return {
+            "results": results,
+            "summary": {
+                "total_matches": len(results),
+                "files_with_matches": len(files_with_matches),
+                "pattern_searched": pattern,
+            },
+        }
+    except Exception as e:
+        return {
+            "results": [],
+            "summary": {"total_matches": 0, "error": str(e)},
+        }
+
+
+# --- Git Tools ---
+
+
+@tool(name="Local_GitStatus", desc="Check git status of the repository.")
+def git_status_tool(
+    context: ToolContext,
+) -> Annotated[dict, "Git status information."]:
+    """Gets the current git status."""
+    stdout, stderr = get_status()
+
+    if stderr:
+        raise ToolExecutionError(f"Git status failed: {stderr}")
+
+    files = []
+    for line in stdout.split("\n"):
+        if line.strip():
+            if len(line) >= 3:
+                status = line[:2]
+                filename = line[3:].strip()
+                files.append({"status": status, "file": filename})
+
+    branch_stdout, branch_stderr = get_current_branch_name()
+    current_branch = branch_stdout if not branch_stderr else "unknown"
+
+    return {
+        "branch": current_branch,
+        "files": files if files else "no files",
+        "clean": len(files) == 0,
+        "raw_output": stdout if stdout else "no output",
+    }
+
+
+# --- Edit File Tool ---
+
+
+@tool(
+    name="Local_EditFile",
+    desc="Edit a file by replacing specific text. Use for targeted changes.",
+)
+def edit_file_tool(
+    context: ToolContext,
+    file_path_arg: Annotated[str, "Path to the file to edit."],
+    old_string: Annotated[
+        str,
+        "The exact text to find and replace. Must match exactly including whitespace.",
+    ],
+    new_string: Annotated[str, "The text to replace old_string with."],
+    expected_count: Annotated[
+        int | None,
+        "Expected number of replacements. If provided, fails if count doesn't match.",
+    ] = None,
+) -> Annotated[dict, "Result of the edit operation including diff."]:
+    """Edit a file by finding and replacing specific text.
+
+    This tool performs precise text replacement in files. The old_string must
+    match exactly (including whitespace and indentation). Use this for targeted
+    edits rather than full file rewrites.
+
+    Args:
+        context: Tool context
+        file_path_arg: Path to file to edit
+        old_string: Exact text to find
+        new_string: Text to replace with
+        expected_count: Optional expected replacement count for validation
+
+    Returns:
+        Dict with success status, diff, and replacement count
+    """
+    resolved_path = PathResolver.resolve_safe_path(file_path_arg, PROJECT_ROOT)
+
+    if not resolved_path.is_file():
+        raise ToolExecutionError(f"File not found: {file_path_arg}")
+
+    try:
+        original_content = read_text_file(resolved_path)
+    except Exception as e:
+        raise ToolExecutionError(f"Failed to read file: {e}") from e
+
+    # Count occurrences
+    count = original_content.count(old_string)
+
+    if count == 0:
+        # Provide helpful context for debugging
+        preview_len = 100
+        old_preview = old_string[:preview_len]
+        if len(old_string) > preview_len:
+            old_preview += "..."
+
+        return {
+            "success": False,
+            "error": "old_string not found in file",
+            "old_string_preview": old_preview,
+            "file_size": len(original_content),
+            "suggestion": "Check whitespace, indentation, and exact character match",
+        }
+
+    if expected_count is not None and count != expected_count:
+        return {
+            "success": False,
+            "error": f"Expected {expected_count} occurrences but found {count}",
+            "actual_count": count,
+        }
+
+    # Perform replacement
+    new_content = original_content.replace(old_string, new_string)
+
+    # Generate diff for review
+    diff = generate_diff_from_content(
+        original_content,
+        new_content,
+        filename=file_path_arg,
+        context_lines=3,
+    )
+
+    # Write the file
+    try:
+        write_text_file(resolved_path, new_content)
+    except Exception as e:
+        raise ToolExecutionError(f"Failed to write file: {e}") from e
+
+    return {
+        "success": True,
+        "message": f"Successfully edited {file_path_arg}",
+        "replacements": count,
+        "diff": diff if diff else "(no visible diff - content may be identical)",
+    }
+
+
+@tool(
+    name="Local_EditFileInsert",
+    desc="Insert text at a specific line number in a file.",
+)
+def edit_file_insert_tool(
+    context: ToolContext,
+    file_path_arg: Annotated[str, "Path to the file to edit."],
+    line_number: Annotated[int, "Line number to insert at (1-indexed). 0 = end of file."],
+    content: Annotated[str, "The text to insert."],
+    position: Annotated[
+        Literal["before", "after"],
+        "Insert before or after the specified line.",
+    ] = "before",
+) -> Annotated[dict, "Result of the insert operation including diff."]:
+    """Insert text at a specific line in a file.
+
+    Args:
+        context: Tool context
+        file_path_arg: Path to file to edit
+        line_number: Line number (1-indexed) to insert at. 0 means end of file.
+        content: Text to insert
+        position: Insert 'before' or 'after' the specified line
+
+    Returns:
+        Dict with success status and diff
+    """
+    resolved_path = PathResolver.resolve_safe_path(file_path_arg, PROJECT_ROOT)
+
+    if not resolved_path.is_file():
+        raise ToolExecutionError(f"File not found: {file_path_arg}")
+
+    try:
+        original_content = read_text_file(resolved_path)
+    except Exception as e:
+        raise ToolExecutionError(f"Failed to read file: {e}") from e
+
+    lines = original_content.splitlines(keepends=True)
+
+    # Handle line number
+    if line_number == 0:
+        # Append to end
+        if lines and not lines[-1].endswith("\n"):
+            lines[-1] += "\n"
+        lines.append(content if content.endswith("\n") else content + "\n")
+    elif line_number < 0 or line_number > len(lines) + 1:
+        raise ToolExecutionError(
+            f"Line number {line_number} out of range (file has {len(lines)} lines)"
+        )
+    else:
+        # Convert to 0-indexed
+        idx = line_number - 1
+        insert_content = content if content.endswith("\n") else content + "\n"
+
+        if position == "before":
+            lines.insert(idx, insert_content)
+        else:  # after
+            lines.insert(idx + 1, insert_content)
+
+    new_content = "".join(lines)
+
+    # Generate diff
+    diff = generate_diff_from_content(
+        original_content,
+        new_content,
+        filename=file_path_arg,
+        context_lines=3,
+    )
+
+    # Write the file
+    try:
+        write_text_file(resolved_path, new_content)
+    except Exception as e:
+        raise ToolExecutionError(f"Failed to write file: {e}") from e
+
+    return {
+        "success": True,
+        "message": f"Successfully inserted content at line {line_number}",
+        "diff": diff,
+    }
+
+
+# --- Tool Registration Helper ---
+
+
+def get_all_tools() -> list[Callable]:
+    """Returns a list of all tool functions defined in this module."""
+    tool_functions = []
+    for name, obj in globals().items():
+        if callable(obj) and hasattr(obj, "__tool_name__") and hasattr(obj, "__tool_description__"):
+            tool_functions.append(obj)
+    return tool_functions