ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/tools/executor.py

@@ -0,0 +1,153 @@
+"""Tool execution coordinator."""
+
+import logging
+from typing import Any
+from dataclasses import dataclass
+
+from .registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ToolCallResult:
+    """Result of a tool call."""
+
+    tool_name: str
+    call_id: str
+    success: bool
+    result: Any = None
+    error: str | None = None
+
+
+class ToolExecutor:
+    """Executes tool calls (both MCP and built-in)."""
+
+    def __init__(self, registry: ToolRegistry):
+        """
+        Initialize tool executor.
+
+        Args:
+            registry: Tool registry with MCP clients and built-in tools
+        """
+        self.registry = registry
+
+    async def execute(
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        call_id: str,
+    ) -> ToolCallResult:
+        """
+        Execute a tool call.
+
+        Args:
+            tool_name: Name of tool to call
+            arguments: Tool arguments
+            call_id: Unique call identifier
+
+        Returns:
+            ToolCallResult with execution result
+        """
+        # Get tool definition
+        tool = self.registry.get_tool(tool_name)
+        if not tool:
+            logger.error(f"Tool not found: {tool_name}")
+            return ToolCallResult(
+                tool_name=tool_name,
+                call_id=call_id,
+                success=False,
+                error=f"Tool '{tool_name}' not found",
+            )
+
+        # Execute based on tool type
+        try:
+            if self.registry.is_builtin(tool_name):
+                # Built-in tool - call function directly
+                from .registry import BuiltinTool
+                import inspect
+                builtin_tool = tool
+                assert isinstance(builtin_tool, BuiltinTool)
+
+                # Check if function is async and await if needed
+                if inspect.iscoroutinefunction(builtin_tool.function):
+                    result = await builtin_tool.function(**arguments)
+                else:
+                    result = builtin_tool.function(**arguments)
+
+                # Check if tool returned an error (error key exists and is not None)
+                if isinstance(result, dict) and "error" in result and result["error"] is not None:
+                    logger.error(f"Built-in tool '{tool_name}' returned error: {result['error']}")
+                    return ToolCallResult(
+                        tool_name=tool_name,
+                        call_id=call_id,
+                        success=False,
+                        error=result["error"],
+                    )
+
+                logger.info(f"Built-in tool '{tool_name}' executed successfully")
+                return ToolCallResult(
+                    tool_name=tool_name,
+                    call_id=call_id,
+                    success=True,
+                    result=result,
+                )
+
+            else:
+                # MCP tool - call via client
+                from .mcp import MCPTool
+                mcp_tool = tool
+                assert isinstance(mcp_tool, MCPTool)
+
+                client = self.registry.get_client(mcp_tool.server_name)
+                if not client:
+                    logger.error(f"Client not found for server: {mcp_tool.server_name}")
+                    return ToolCallResult(
+                        tool_name=tool_name,
+                        call_id=call_id,
+                        success=False,
+                        error=f"Server '{mcp_tool.server_name}' not available",
+                    )
+
+                result = await client.call_tool(tool_name, arguments)
+                logger.info(f"MCP tool '{tool_name}' executed successfully")
+
+                return ToolCallResult(
+                    tool_name=tool_name,
+                    call_id=call_id,
+                    success=True,
+                    result=result,
+                )
+
+        except Exception as e:
+            logger.error(f"Tool execution failed: {e}")
+            return ToolCallResult(
+                tool_name=tool_name,
+                call_id=call_id,
+                success=False,
+                error=str(e),
+            )
+
+    async def execute_batch(
+        self,
+        tool_calls: list[dict[str, Any]]
+    ) -> list[ToolCallResult]:
+        """
+        Execute multiple tool calls.
+
+        Args:
+            tool_calls: List of tool call dicts with name, arguments, call_id
+
+        Returns:
+            List of results
+        """
+        results = []
+        for call in tool_calls:
+            result = await self.execute(
+                tool_name=call["name"],
+                arguments=call["arguments"],
+                call_id=call["call_id"],
+            )
+            results.append(result)
+
+        return results

ctrlcode/tools/explore.py

@@ -0,0 +1,486 @@
+"""Built-in exploration tools for codebase navigation."""
+
+import os
+import subprocess
+from pathlib import Path
+from dataclasses import dataclass
+from typing import Any
+
+from ..permissions import request_permission
+
+
+@dataclass
+class SearchResult:
+    """Result from code search."""
+
+    file: str
+    line: int
+    content: str
+    context_before: list[str] | None = None
+    context_after: list[str] | None = None
+
+
+class ExploreTools:
+    """Built-in tools for exploring codebases."""
+
+    def __init__(self, workspace_root: str | Path):
+        """
+        Initialize exploration tools.
+
+        Args:
+            workspace_root: Root directory for exploration
+        """
+        self.workspace_root = Path(workspace_root).resolve()
+
+    def search_files(self, pattern: str, max_results: int = 100) -> list[str]:
+        """
+        Search for files matching glob pattern.
+
+        Args:
+            pattern: Glob pattern (e.g., "**/*.py", "src/**/*.ts")
+            max_results: Maximum results to return
+
+        Returns:
+            List of file paths relative to workspace root
+        """
+        try:
+            matches = []
+            for path in self.workspace_root.glob(pattern):
+                if path.is_file():
+                    rel_path = path.relative_to(self.workspace_root)
+                    matches.append(str(rel_path))
+
+                    if len(matches) >= max_results:
+                        break
+
+            return sorted(matches)
+
+        except Exception as e:
+            return [f"Error: {e}"]
+
+    def search_code(
+        self,
+        query: str,
+        file_pattern: str = "**/*",
+        context_lines: int = 2,
+        max_results: int = 50,
+    ) -> list[dict[str, Any]]:
+        """
+        Search code content using ripgrep.
+
+        Args:
+            query: Search query (regex supported)
+            file_pattern: Glob pattern to limit search
+            context_lines: Lines of context before/after match
+            max_results: Maximum results to return
+
+        Returns:
+            List of search results with file, line, content, context
+        """
+        try:
+            # Use ripgrep for fast search
+            cmd = [
+                "rg",
+                "--json",
+                "-C", str(context_lines),
+                "--max-count", str(max_results),
+                query,
+            ]
+
+            # Add file pattern if specified
+            if file_pattern != "**/*":
+                cmd.extend(["-g", file_pattern])
+
+            # Add explicit search path (required for subprocess to work correctly)
+            cmd.append(".")
+
+            result = subprocess.run(
+                cmd,
+                cwd=self.workspace_root,
+                capture_output=True,
+                text=True,
+            )
+
+            if result.returncode != 0 and result.returncode != 1:
+                return [{"error": result.stderr}]
+
+            # Parse JSON output
+            results = []
+            for line in result.stdout.splitlines():
+                if not line.strip():
+                    continue
+
+                import json
+                data = json.loads(line)
+
+                if data.get("type") == "match":
+                    match_data = data["data"]
+                    # Path from rg is relative to cwd, resolve to absolute then make relative to workspace
+                    abs_path = (self.workspace_root / match_data["path"]["text"]).resolve()
+                    rel_path = abs_path.relative_to(self.workspace_root)
+                    results.append({
+                        "file": str(rel_path),
+                        "line": match_data["line_number"],
+                        "content": match_data["lines"]["text"].rstrip(),
+                    })
+
+            return results[:max_results]
+
+        except FileNotFoundError:
+            # Fallback to basic grep if ripgrep not available
+            return self._fallback_search(query, file_pattern, max_results)
+
+        except Exception as e:
+            return [{"error": str(e)}]
+
+    def _fallback_search(
+        self, query: str, file_pattern: str, max_results: int
+    ) -> list[dict[str, Any]]:
+        """Fallback to Python-based search if ripgrep unavailable."""
+        results = []
+
+        try:
+            for path in self.workspace_root.glob(file_pattern):
+                if not path.is_file():
+                    continue
+
+                # Skip binary files
+                try:
+                    with open(path, "r", encoding="utf-8") as f:
+                        for line_num, line in enumerate(f, 1):
+                            if query.lower() in line.lower():
+                                results.append({
+                                    "file": str(path.relative_to(self.workspace_root)),
+                                    "line": line_num,
+                                    "content": line.rstrip(),
+                                })
+
+                                if len(results) >= max_results:
+                                    return results
+                except (UnicodeDecodeError, PermissionError):
+                    continue
+
+        except Exception as e:
+            return [{"error": str(e)}]
+
+        return results
+
+    def read_file(
+        self,
+        path: str,
+        start_line: int | None = None,
+        end_line: int | None = None,
+    ) -> dict[str, Any]:
+        """
+        Read file contents.
+
+        Args:
+            path: File path relative to workspace root
+            start_line: Start line (1-indexed, inclusive)
+            end_line: End line (1-indexed, inclusive)
+
+        Returns:
+            Dict with content, total_lines, and metadata
+        """
+        try:
+            file_path = (self.workspace_root / path).resolve()
+
+            # Security: ensure path is within workspace
+            if not str(file_path).startswith(str(self.workspace_root)):
+                return {"error": "Path outside workspace"}
+
+            if not file_path.exists():
+                return {"error": "File not found"}
+
+            if not file_path.is_file():
+                return {"error": "Not a file"}
+
+            with open(file_path, "r", encoding="utf-8") as f:
+                lines = f.readlines()
+
+            total_lines = len(lines)
+
+            # Apply line range
+            if start_line is not None or end_line is not None:
+                start = (start_line - 1) if start_line else 0
+                end = end_line if end_line else total_lines
+                lines = lines[start:end]
+
+            content = "".join(lines)
+
+            return {
+                "content": content,
+                "total_lines": total_lines,
+                "lines_returned": len(lines),
+                "path": str(path),
+            }
+
+        except UnicodeDecodeError:
+            return {"error": "File is binary or uses unsupported encoding"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def write_file(self, path: str, content: str) -> dict[str, Any]:
+        """
+        Write content to a file.
+
+        Args:
+            path: File path relative to workspace root
+            content: Content to write to file
+
+        Returns:
+            Dict with success status and metadata
+        """
+        try:
+            file_path = (self.workspace_root / path).resolve()
+
+            # Check if path is outside workspace - request permission if so
+            outside_workspace = not str(file_path).startswith(str(self.workspace_root))
+
+            if outside_workspace:
+                # Request user approval for writing outside workspace
+                approved = await request_permission(
+                    operation="write_file",
+                    path=str(file_path),
+                    reason=f"Write file outside workspace ({self.workspace_root})",
+                    details={"workspace": str(self.workspace_root), "requested_path": path}
+                )
+
+                if not approved:
+                    return {"error": "Permission denied: path outside workspace"}
+
+            # Create parent directories if needed
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write file
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+            return {
+                "success": True,
+                "path": str(file_path),  # Return absolute path so TUI can read it back
+                "bytes_written": len(content.encode("utf-8")),
+            }
+
+        except Exception as e:
+            return {"error": str(e)}
+
+    def list_directory(
+        self, path: str = ".", max_depth: int = 1
+    ) -> dict[str, Any]:
+        """
+        List directory contents.
+
+        Args:
+            path: Directory path relative to workspace root
+            max_depth: How deep to recurse (1 = immediate children only)
+
+        Returns:
+            Dict with directories and files
+        """
+        try:
+            dir_path = (self.workspace_root / path).resolve()
+
+            # Security: ensure path is within workspace
+            if not str(dir_path).startswith(str(self.workspace_root)):
+                return {"error": "Path outside workspace"}
+
+            if not dir_path.exists():
+                return {"error": "Directory not found"}
+
+            if not dir_path.is_dir():
+                return {"error": "Not a directory"}
+
+            directories = []
+            files = []
+
+            # Use os.walk for recursive listing
+            for root, dirs, filenames in os.walk(dir_path):
+                root_path = Path(root)
+                depth = len(root_path.relative_to(dir_path).parts)
+
+                if depth >= max_depth:
+                    dirs.clear()  # Don't recurse deeper
+                    continue
+
+                for d in sorted(dirs):
+                    rel_path = (root_path / d).relative_to(self.workspace_root)
+                    directories.append(str(rel_path))
+
+                for f in sorted(filenames):
+                    rel_path = (root_path / f).relative_to(self.workspace_root)
+                    file_path = root_path / f
+                    files.append({
+                        "path": str(rel_path),
+                        "size": file_path.stat().st_size,
+                    })
+
+            return {
+                "path": str(Path(path)),
+                "directories": directories[:100],  # Limit results
+                "files": files[:100],
+            }
+
+        except Exception as e:
+            return {"error": str(e)}
+
+    def get_file_info(self, path: str) -> dict[str, Any]:
+        """
+        Get file metadata.
+
+        Args:
+            path: File path relative to workspace root
+
+        Returns:
+            Dict with size, modified time, type, etc.
+        """
+        try:
+            file_path = (self.workspace_root / path).resolve()
+
+            # Security: ensure path is within workspace
+            if not str(file_path).startswith(str(self.workspace_root)):
+                return {"error": "Path outside workspace"}
+
+            if not file_path.exists():
+                return {"error": "File not found"}
+
+            stat = file_path.stat()
+
+            return {
+                "path": str(path),
+                "size": stat.st_size,
+                "modified": stat.st_mtime,
+                "is_file": file_path.is_file(),
+                "is_directory": file_path.is_dir(),
+                "extension": file_path.suffix,
+            }
+
+        except Exception as e:
+            return {"error": str(e)}
+
+
+# Tool schemas for LLM providers (Anthropic/OpenAI format)
+EXPLORE_TOOL_SCHEMAS = [
+    {
+        "name": "search_files",
+        "description": "Search for files in the codebase using glob patterns. Use this to find files by name or extension.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "pattern": {
+                    "type": "string",
+                    "description": "Glob pattern to match files (e.g., '**/*.py' for all Python files, 'src/**/*.ts' for TypeScript in src/)",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of results to return",
+                    "default": 100,
+                },
+            },
+            "required": ["pattern"],
+        },
+    },
+    {
+        "name": "search_code",
+        "description": "Search for code content across files. Use this to find where specific functions, classes, or patterns are used.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query (supports regex). E.g., 'class FuzzingOrchestrator', 'def process_turn'",
+                },
+                "file_pattern": {
+                    "type": "string",
+                    "description": "Limit search to files matching this glob pattern",
+                    "default": "**/*",
+                },
+                "context_lines": {
+                    "type": "integer",
+                    "description": "Number of context lines before/after match",
+                    "default": 2,
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Maximum number of results to return",
+                    "default": 50,
+                },
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "read_file",
+        "description": "Read contents of a file. Use this to examine specific files found through search.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "File path relative to workspace root",
+                },
+                "start_line": {
+                    "type": "integer",
+                    "description": "Start line number (1-indexed, inclusive). Omit to read from beginning.",
+                },
+                "end_line": {
+                    "type": "integer",
+                    "description": "End line number (1-indexed, inclusive). Omit to read to end.",
+                },
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "write_file",
+        "description": "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Parent directories are created automatically.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "File path relative to workspace root (e.g., 'fizzbuzz.py', 'src/utils.py'). NEVER use absolute paths.",
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Content to write to the file",
+                },
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "list_directory",
+        "description": "List contents of a directory. Use this to understand project structure.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Directory path relative to workspace root",
+                    "default": ".",
+                },
+                "max_depth": {
+                    "type": "integer",
+                    "description": "How deep to recurse (1 = immediate children only)",
+                    "default": 1,
+                },
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "get_file_info",
+        "description": "Get metadata about a file (size, modified time, type).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "File path relative to workspace root",
+                },
+            },
+            "required": ["path"],
+        },
+    },
+]