ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/tools/__init__.py

@@ -0,0 +1,220 @@
+"""MCP tool system for ctrl-code."""
+
+from pathlib import Path
+
+from .mcp import MCPClient, MCPTool
+from .registry import ToolRegistry, BuiltinTool
+from .executor import ToolExecutor, ToolCallResult
+from .explore import ExploreTools, EXPLORE_TOOL_SCHEMAS
+from .todo import TodoTools, TODO_TOOL_SCHEMAS
+from .bash import BashTools, BASH_TOOL_SCHEMAS
+from .webfetch import WebFetchTools, WEBFETCH_TOOL_SCHEMAS
+from .update import UpdateFileTools, UPDATE_TOOL_SCHEMAS
+from .observability import ObservabilityTools, OBSERVABILITY_TOOL_SCHEMAS
+from .browser import BrowserTools, BROWSER_TOOL_SCHEMAS, get_browser_tools
+
+
+def setup_explore_tools(registry: ToolRegistry, workspace_root: str | Path) -> None:
+    """
+    Register built-in exploration tools.
+
+    Args:
+        registry: Tool registry to register tools in
+        workspace_root: Root directory for file exploration
+    """
+    explore = ExploreTools(workspace_root)
+
+    # Register each tool with its schema and function
+    for schema in EXPLORE_TOOL_SCHEMAS:
+        tool_name = schema["name"]
+
+        # Map tool name to method
+        function = getattr(explore, tool_name)
+
+        registry.register_builtin(
+            name=tool_name,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+
+def setup_todo_tools(registry: ToolRegistry, data_dir: str | Path) -> None:
+    """
+    Register built-in todo tools.
+
+    Args:
+        registry: Tool registry to register tools in
+        data_dir: Data directory for storing todos
+    """
+    todo = TodoTools(data_dir)
+
+    # Register each tool with its schema and function
+    for schema in TODO_TOOL_SCHEMAS:
+        tool_name = schema["name"]
+
+        # Map tool name to method
+        function = getattr(todo, tool_name)
+
+        registry.register_builtin(
+            name=tool_name,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+        # Also register as task_* alias for user flexibility
+        task_alias = tool_name.replace("todo_", "task_")
+        registry.register_builtin(
+            name=task_alias,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+
+def setup_bash_tools(registry: ToolRegistry, workspace_root: str | Path) -> None:
+    """
+    Register built-in bash tools.
+
+    Args:
+        registry: Tool registry to register tools in
+        workspace_root: Root directory for command execution
+    """
+    bash = BashTools(workspace_root)
+
+    # Register each tool with its schema and function
+    for schema in BASH_TOOL_SCHEMAS:
+        tool_name = schema["name"]
+
+        # Map tool name to method
+        function = getattr(bash, tool_name)
+
+        registry.register_builtin(
+            name=tool_name,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+
+def setup_webfetch_tools(registry: ToolRegistry) -> None:
+    """
+    Register built-in web fetch tools.
+
+    Args:
+        registry: Tool registry to register tools in
+    """
+    webfetch = WebFetchTools()
+
+    # Register each tool with its schema and function
+    for schema in WEBFETCH_TOOL_SCHEMAS:
+        tool_name = schema["name"]
+
+        # Map tool name to method
+        function = getattr(webfetch, tool_name)
+
+        registry.register_builtin(
+            name=tool_name,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+
+def setup_update_tools(registry: ToolRegistry, workspace_root: str | Path) -> None:
+    """
+    Register built-in update file tools.
+
+    Args:
+        registry: Tool registry to register tools in
+        workspace_root: Root directory for file operations
+    """
+    update = UpdateFileTools(workspace_root)
+
+    # Register each tool with its schema and function
+    for schema in UPDATE_TOOL_SCHEMAS:
+        tool_name = schema["name"]
+
+        # Map tool name to method
+        function = getattr(update, tool_name)
+
+        registry.register_builtin(
+            name=tool_name,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+
+def setup_observability_tools(registry: ToolRegistry, log_dir: str | Path | None = None) -> None:
+    """
+    Register built-in observability tools.
+
+    Args:
+        registry: Tool registry to register tools in
+        log_dir: Directory containing log files (optional)
+    """
+    observability = ObservabilityTools(log_dir)
+
+    # Register each tool with its schema and function
+    for schema in OBSERVABILITY_TOOL_SCHEMAS:
+        tool_name = schema["name"]
+
+        # Map tool name to method
+        function = getattr(observability, tool_name)
+
+        registry.register_builtin(
+            name=tool_name,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+
+def setup_browser_tools(registry: ToolRegistry) -> None:
+    """
+    Register built-in browser automation tools.
+
+    Args:
+        registry: Tool registry to register tools in
+    """
+    browser = get_browser_tools()
+
+    # Register each tool with its schema and function
+    for schema in BROWSER_TOOL_SCHEMAS:
+        tool_name = schema["name"]
+
+        # Map tool name to method
+        function = getattr(browser, tool_name)
+
+        registry.register_builtin(
+            name=tool_name,
+            description=schema["description"],
+            input_schema=schema["input_schema"],
+            function=function,
+        )
+
+
+__all__ = [
+    "MCPClient",
+    "MCPTool",
+    "ToolRegistry",
+    "BuiltinTool",
+    "ToolExecutor",
+    "ToolCallResult",
+    "ExploreTools",
+    "TodoTools",
+    "BashTools",
+    "WebFetchTools",
+    "UpdateFileTools",
+    "ObservabilityTools",
+    "BrowserTools",
+    "setup_explore_tools",
+    "setup_todo_tools",
+    "setup_bash_tools",
+    "setup_webfetch_tools",
+    "setup_update_tools",
+    "setup_observability_tools",
+    "setup_browser_tools",
+]

ctrlcode/tools/bash.py

@@ -0,0 +1,112 @@
+"""Built-in bash execution tools for running shell commands."""
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+class BashTools:
+    """Built-in tools for executing bash commands."""
+
+    def __init__(self, workspace_root: str | Path):
+        """
+        Initialize bash tools.
+
+        Args:
+            workspace_root: Root directory for command execution
+        """
+        self.workspace_root = Path(workspace_root).resolve()
+
+    def run_command(
+        self,
+        command: str,
+        timeout: int = 30,
+        cwd: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a shell command.
+
+        Args:
+            command: Shell command to execute
+            timeout: Timeout in seconds (default 30, max 300)
+            cwd: Working directory for command (relative to workspace root)
+
+        Returns:
+            Dict with stdout, stderr, returncode, and metadata
+        """
+        try:
+            # Enforce timeout limits
+            if timeout > 300:
+                timeout = 300
+            if timeout < 1:
+                timeout = 1
+
+            # Determine working directory
+            work_dir = self.workspace_root
+            if cwd:
+                work_dir = (self.workspace_root / cwd).resolve()
+
+                # Security: ensure cwd is within workspace
+                if not str(work_dir).startswith(str(self.workspace_root)):
+                    return {"error": "Working directory outside workspace"}
+
+                if not work_dir.exists():
+                    return {"error": "Working directory does not exist"}
+
+                if not work_dir.is_dir():
+                    return {"error": "Working directory is not a directory"}
+
+            # Execute command
+            result = subprocess.run(
+                command,
+                shell=True,
+                cwd=work_dir,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+
+            return {
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+                "returncode": result.returncode,
+                "command": command,
+                "cwd": str(work_dir.relative_to(self.workspace_root)),
+                "success": result.returncode == 0,
+            }
+
+        except subprocess.TimeoutExpired:
+            return {
+                "error": f"Command timed out after {timeout} seconds",
+                "command": command,
+            }
+        except Exception as e:
+            return {"error": str(e), "command": command}
+
+
+# Tool schemas for LLM providers (Anthropic/OpenAI format)
+BASH_TOOL_SCHEMAS = [
+    {
+        "name": "run_command",
+        "description": "Execute a shell command in the workspace. Use for git operations, testing, build tools, etc. Commands run in a bash shell.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "Shell command to execute (e.g., 'git status', 'npm test', 'make build')",
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Timeout in seconds (default 30, max 300)",
+                    "default": 30,
+                },
+                "cwd": {
+                    "type": "string",
+                    "description": "Working directory relative to workspace root (e.g., 'src', 'tests')",
+                },
+            },
+            "required": ["command"],
+        },
+    },
+]

ctrlcode/tools/browser.py

@@ -0,0 +1,352 @@
+"""Browser automation tools for UI validation via Chrome DevTools Protocol."""
+
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class BrowserTools:
+    """Browser automation tools for screenshot capture and DOM inspection."""
+
+    def __init__(self):
+        """Initialize browser tools."""
+        self._playwright = None
+        self._browser = None
+
+    async def _ensure_browser(self):
+        """Ensure playwright browser is launched."""
+        if self._browser is not None:
+            return
+
+        try:
+            from playwright.async_api import async_playwright
+        except ImportError:
+            raise RuntimeError(
+                "playwright not installed. Run: uv add playwright && uv run playwright install chromium"
+            )
+
+        if self._playwright is None:
+            self._playwright = await async_playwright().start()
+
+        self._browser = await self._playwright.chromium.launch(headless=True)
+
+    async def _cleanup(self):
+        """Cleanup browser resources."""
+        if self._browser:
+            await self._browser.close()
+            self._browser = None
+        if self._playwright:
+            await self._playwright.stop()
+            self._playwright = None
+
+    async def screenshot(
+        self,
+        url: str,
+        output: str | None = None,
+        full_page: bool = True,
+        viewport_width: int = 1280,
+        viewport_height: int = 720,
+        wait_for: str | None = None,
+        timeout: int = 30000,
+    ) -> dict[str, Any]:
+        """
+        Capture screenshot of a web page.
+
+        Args:
+            url: URL to navigate to
+            output: Output file path (defaults to temp file)
+            full_page: Capture full scrollable page (default: True)
+            viewport_width: Viewport width in pixels (default: 1280)
+            viewport_height: Viewport height in pixels (default: 720)
+            wait_for: CSS selector to wait for before screenshot (optional)
+            timeout: Page load timeout in milliseconds (default: 30000)
+
+        Returns:
+            Dict with:
+                - success: Whether screenshot succeeded
+                - file_path: Path to screenshot file
+                - url: URL that was captured
+                - width: Image width
+                - height: Image height
+                - error: Error message if failed
+        """
+        try:
+            await self._ensure_browser()
+
+            # Create context with viewport
+            context = await self._browser.new_context(
+                viewport={"width": viewport_width, "height": viewport_height}
+            )
+
+            # Create page
+            page = await context.new_page()
+
+            # Navigate to URL
+            await page.goto(url, timeout=timeout, wait_until="networkidle")
+
+            # Wait for specific element if requested
+            if wait_for:
+                await page.wait_for_selector(wait_for, timeout=timeout)
+
+            # Determine output path
+            if output is None:
+                screenshots_dir = Path.cwd() / ".ctrlcode" / "screenshots"
+                screenshots_dir.mkdir(parents=True, exist_ok=True)
+                temp_file = tempfile.NamedTemporaryFile(
+                    suffix=".png", delete=False, dir=screenshots_dir
+                )
+                output = temp_file.name
+                temp_file.close()
+            else:
+                output = str(Path(output).resolve())
+                # Ensure output directory exists
+                Path(output).parent.mkdir(parents=True, exist_ok=True)
+
+            # Take screenshot
+            await page.screenshot(path=output, full_page=full_page)
+
+            # Get dimensions
+            if full_page:
+                dimensions = await page.evaluate(
+                    "() => ({ width: document.documentElement.scrollWidth, height: document.documentElement.scrollHeight })"
+                )
+            else:
+                dimensions = {"width": viewport_width, "height": viewport_height}
+
+            await context.close()
+
+            return {
+                "success": True,
+                "file_path": output,
+                "url": url,
+                "width": dimensions["width"],
+                "height": dimensions["height"],
+            }
+
+        except Exception as e:
+            logger.error(f"Screenshot failed: {e}", exc_info=True)
+            return {"success": False, "error": str(e), "url": url}
+
+    async def dom_snapshot(
+        self,
+        url: str,
+        selector: str | None = None,
+        include_styles: bool = False,
+        timeout: int = 30000,
+    ) -> dict[str, Any]:
+        """
+        Capture DOM structure snapshot for HTML inspection.
+
+        Args:
+            url: URL to navigate to
+            selector: CSS selector to extract (defaults to full page)
+            include_styles: Include computed styles (default: False)
+            timeout: Page load timeout in milliseconds (default: 30000)
+
+        Returns:
+            Dict with:
+                - success: Whether snapshot succeeded
+                - url: URL that was captured
+                - html: HTML content
+                - text_content: Extracted text content
+                - element_count: Number of elements
+                - links: List of links found
+                - forms: List of forms found
+                - error: Error message if failed
+        """
+        try:
+            await self._ensure_browser()
+
+            # Create context
+            context = await self._browser.new_context()
+            page = await context.new_page()
+
+            # Navigate to URL
+            await page.goto(url, timeout=timeout, wait_until="networkidle")
+
+            # Get element handle
+            if selector:
+                element = await page.query_selector(selector)
+                if not element:
+                    return {
+                        "success": False,
+                        "error": f"Selector '{selector}' not found",
+                        "url": url,
+                    }
+                html = await element.inner_html()
+                text_content = await element.text_content()
+            else:
+                html = await page.content()
+                text_content = await page.evaluate("() => document.body.textContent")
+
+            # Extract metadata
+            element_count = await page.evaluate("() => document.querySelectorAll('*').length")
+
+            # Extract links
+            links = await page.evaluate(
+                """() => {
+                    return Array.from(document.querySelectorAll('a[href]')).map(a => ({
+                        text: a.textContent.trim(),
+                        href: a.href,
+                        target: a.target
+                    }));
+                }"""
+            )
+
+            # Extract forms
+            forms = await page.evaluate(
+                """() => {
+                    return Array.from(document.querySelectorAll('form')).map(form => ({
+                        action: form.action,
+                        method: form.method,
+                        fields: Array.from(form.querySelectorAll('input, textarea, select')).map(field => ({
+                            name: field.name,
+                            type: field.type,
+                            id: field.id
+                        }))
+                    }));
+                }"""
+            )
+
+            await context.close()
+
+            return {
+                "success": True,
+                "url": url,
+                "html": html,
+                "text_content": text_content.strip() if text_content else "",
+                "element_count": element_count,
+                "links": links,
+                "forms": forms,
+            }
+
+        except Exception as e:
+            logger.error(f"DOM snapshot failed: {e}", exc_info=True)
+            return {"success": False, "error": str(e), "url": url}
+
+    async def close(self):
+        """Close browser and cleanup resources."""
+        await self._cleanup()
+
+
+# Singleton instance
+_browser_tools = None
+
+
+def get_browser_tools() -> BrowserTools:
+    """Get or create singleton BrowserTools instance."""
+    global _browser_tools
+    if _browser_tools is None:
+        _browser_tools = BrowserTools()
+    return _browser_tools
+
+
+async def cleanup_browser_tools():
+    """Cleanup singleton browser tools."""
+    global _browser_tools
+    if _browser_tools is not None:
+        await _browser_tools.close()
+        _browser_tools = None
+
+
+BROWSER_TOOL_SCHEMAS = [
+    {
+        "name": "screenshot",
+        "description": """Capture screenshot of a web page for UI validation.
+
+Useful for verifying:
+- Page renders correctly after changes
+- UI elements are visible and positioned correctly
+- Visual regressions
+- Responsive design at different viewports
+
+Returns file path to PNG screenshot that can be analyzed.
+
+Examples:
+- screenshot(url="http://localhost:8000") - Capture full page
+- screenshot(url="http://localhost:8000/login", wait_for=".login-form") - Wait for element
+- screenshot(url="http://localhost:8000", full_page=False) - Viewport only""",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "URL to navigate to and capture"
+                },
+                "output": {
+                    "type": "string",
+                    "description": "Output file path (optional, defaults to temp file)"
+                },
+                "full_page": {
+                    "type": "boolean",
+                    "description": "Capture full scrollable page (default: true)",
+                    "default": True
+                },
+                "viewport_width": {
+                    "type": "integer",
+                    "description": "Viewport width in pixels (default: 1280)",
+                    "default": 1280
+                },
+                "viewport_height": {
+                    "type": "integer",
+                    "description": "Viewport height in pixels (default: 720)",
+                    "default": 720
+                },
+                "wait_for": {
+                    "type": "string",
+                    "description": "CSS selector to wait for before screenshot (optional)"
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Page load timeout in milliseconds (default: 30000)",
+                    "default": 30000
+                }
+            },
+            "required": ["url"]
+        }
+    },
+    {
+        "name": "dom_snapshot",
+        "description": """Capture DOM structure snapshot for HTML inspection.
+
+Useful for:
+- Verifying page structure and content
+- Extracting text, links, forms
+- Debugging rendering issues
+- Validating SEO elements
+
+Returns HTML content, text, element count, links, and forms.
+
+Examples:
+- dom_snapshot(url="http://localhost:8000") - Full page snapshot
+- dom_snapshot(url="http://localhost:8000", selector=".main-content") - Specific element
+- dom_snapshot(url="http://localhost:8000/api/docs", include_styles=True) - With styles""",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "URL to navigate to and capture"
+                },
+                "selector": {
+                    "type": "string",
+                    "description": "CSS selector to extract (optional, defaults to full page)"
+                },
+                "include_styles": {
+                    "type": "boolean",
+                    "description": "Include computed styles (default: false)",
+                    "default": False
+                },
+                "timeout": {
+                    "type": "integer",
+                    "description": "Page load timeout in milliseconds (default: 30000)",
+                    "default": 30000
+                }
+            },
+            "required": ["url"]
+        }
+    }
+]