superqode 0.1.5__py3-none-any.whl

superqode/tools/shell_tools.py

@@ -0,0 +1,259 @@
+"""
+Shell Tools - Simple Command Execution.
+
+NO command parsing, NO permission trees, NO complex safety checks.
+Just run the command and return output.
+
+Safety is handled at a higher level (user confirmation if enabled).
+Git operations are blocked during QE sessions to maintain immutable repo guarantee.
+
+Performance features:
+- Streaming output as command runs (via ctx.on_output callback)
+- Non-blocking execution with proper timeout handling
+"""
+
+import asyncio
+from pathlib import Path
+from typing import Any, Dict
+
+from .base import Tool, ToolResult, ToolContext
+from .validation import validate_working_dir_parameter
+
+
+class BashTool(Tool):
+    """Execute shell commands.
+
+    Simple, transparent shell execution with streaming output.
+    Git operations are blocked during QE sessions.
+
+    Performance:
+        When ctx.on_output is set, output is streamed in real-time
+        as it's produced, instead of waiting for command completion.
+    """
+
+    DEFAULT_TIMEOUT = 120  # 2 minutes
+    MAX_OUTPUT = 50000  # 50KB output limit
+    CHUNK_SIZE = 1024  # Read chunks for streaming
+
+    def __init__(self, git_guard_enabled: bool = True):
+        """
+        Initialize BashTool.
+
+        Args:
+            git_guard_enabled: If True, block git write operations during QE.
+        """
+        self._git_guard_enabled = git_guard_enabled
+
+    @property
+    def name(self) -> str:
+        return "bash"
+
+    @property
+    def description(self) -> str:
+        return "Execute a shell command and return its output."
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string", "description": "The shell command to execute"},
+                "working_dir": {
+                    "type": "string",
+                    "description": "Working directory for the command (optional)",
+                },
+                "timeout": {"type": "integer", "description": "Timeout in seconds (default: 120)"},
+            },
+            "required": ["command"],
+        }
+
+    async def execute(self, args: Dict[str, Any], ctx: ToolContext) -> ToolResult:
+        command = args.get("command", "")
+        working_dir = args.get("working_dir")
+        timeout = args.get("timeout", self.DEFAULT_TIMEOUT)
+
+        if not command.strip():
+            return ToolResult(success=False, output="", error="Empty command")
+
+        # Check Git Guard - block git write operations during QE
+        if self._git_guard_enabled:
+            try:
+                from superqode.workspace.git_guard import get_git_guard, GitOperationBlocked
+
+                guard = get_git_guard()
+                if guard.enabled:
+                    guard.check_command(command)
+            except GitOperationBlocked as e:
+                return ToolResult(
+                    success=False,
+                    output="",
+                    error=f"🛡️ Git operation blocked: {e.reason}\n\n"
+                    f"💡 {e.suggestion}\n\n"
+                    "SuperQode runs in ephemeral mode - all changes are "
+                    "automatically tracked and reverted after QE completes. "
+                    "Findings are preserved in .superqode/qe-artifacts/",
+                    metadata={"blocked_by": "git_guard", "command": command},
+                )
+            except ImportError:
+                pass  # Git guard not available, continue
+
+        # Validate and resolve working directory - ensures it stays within ctx.working_directory
+        try:
+            cwd = validate_working_dir_parameter(working_dir, ctx.working_directory)
+        except ValueError as e:
+            return ToolResult(success=False, output="", error=str(e))
+
+        # Emit initial progress
+        await ctx.emit_progress(0.0, f"Running: {command[:50]}...")
+
+        try:
+            # PERFORMANCE: Use streaming mode if callback is set
+            if ctx.on_output:
+                return await self._execute_streaming(command, cwd, timeout, ctx)
+            else:
+                return await self._execute_buffered(command, cwd, timeout, ctx)
+
+        except Exception as e:
+            return ToolResult(success=False, output="", error=str(e))
+
+    async def _execute_buffered(
+        self,
+        command: str,
+        cwd: Path,
+        timeout: int,
+        ctx: ToolContext,
+    ) -> ToolResult:
+        """Execute command and buffer all output (original behavior)."""
+        process = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(cwd),
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
+        except asyncio.TimeoutError:
+            process.kill()
+            return ToolResult(
+                success=False, output="", error=f"Command timed out after {timeout} seconds"
+            )
+
+        # Decode output
+        stdout_str = stdout.decode("utf-8", errors="replace")
+        stderr_str = stderr.decode("utf-8", errors="replace")
+
+        # Combine output
+        output = stdout_str
+        if stderr_str:
+            output += f"\n[stderr]\n{stderr_str}" if output else stderr_str
+
+        # Truncate if too long
+        if len(output) > self.MAX_OUTPUT:
+            output = (
+                output[: self.MAX_OUTPUT] + f"\n\n[Output truncated at {self.MAX_OUTPUT} bytes]"
+            )
+
+        success = process.returncode == 0
+        await ctx.emit_progress(1.0, "Complete" if success else "Failed")
+
+        return ToolResult(
+            success=success,
+            output=output,
+            error=None if success else f"Exit code: {process.returncode}",
+            metadata={"exit_code": process.returncode, "command": command, "cwd": str(cwd)},
+        )
+
+    async def _execute_streaming(
+        self,
+        command: str,
+        cwd: Path,
+        timeout: int,
+        ctx: ToolContext,
+    ) -> ToolResult:
+        """Execute command with streaming output to callback."""
+        process = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(cwd),
+        )
+
+        output_chunks = []
+        total_bytes = 0
+        truncated = False
+
+        async def read_stream(stream, is_stderr: bool = False):
+            """Read from a stream and emit chunks."""
+            nonlocal total_bytes, truncated
+
+            while True:
+                try:
+                    chunk = await asyncio.wait_for(
+                        stream.read(self.CHUNK_SIZE),
+                        timeout=1.0,  # Check timeout every second
+                    )
+                except asyncio.TimeoutError:
+                    continue  # Keep reading
+
+                if not chunk:
+                    break
+
+                text = chunk.decode("utf-8", errors="replace")
+
+                # Check size limit
+                if total_bytes + len(text) > self.MAX_OUTPUT:
+                    remaining = self.MAX_OUTPUT - total_bytes
+                    if remaining > 0:
+                        text = text[:remaining]
+                        output_chunks.append(text)
+                        await ctx.emit_output(text)
+                    truncated = True
+                    break
+
+                total_bytes += len(text)
+
+                # Prefix stderr
+                if is_stderr and text.strip():
+                    text = f"[stderr] {text}"
+
+                output_chunks.append(text)
+                await ctx.emit_output(text)
+
+        # Create timeout task
+        try:
+            # Read both streams concurrently
+            await asyncio.wait_for(
+                asyncio.gather(
+                    read_stream(process.stdout, is_stderr=False),
+                    read_stream(process.stderr, is_stderr=True),
+                ),
+                timeout=timeout,
+            )
+            await process.wait()
+        except asyncio.TimeoutError:
+            process.kill()
+            return ToolResult(
+                success=False,
+                output="".join(output_chunks),
+                error=f"Command timed out after {timeout} seconds",
+            )
+
+        output = "".join(output_chunks)
+        if truncated:
+            output += f"\n\n[Output truncated at {self.MAX_OUTPUT} bytes]"
+
+        success = process.returncode == 0
+        await ctx.emit_progress(1.0, "Complete" if success else "Failed")
+
+        return ToolResult(
+            success=success,
+            output=output,
+            error=None if success else f"Exit code: {process.returncode}",
+            metadata={
+                "exit_code": process.returncode,
+                "command": command,
+                "cwd": str(cwd),
+                "streamed": True,
+            },
+        )

superqode/tools/todo_tools.py

@@ -0,0 +1,121 @@
+"""
+TODO Management Tools - Task planning and tracking.
+
+Helps models plan and track multi-step tasks with status updates.
+"""
+
+import json
+from typing import Any, Dict, List
+
+from .base import Tool, ToolResult, ToolContext
+
+# Session-based in-memory storage: session_id -> list of todo items
+_todo_store: Dict[str, List[Dict[str, Any]]] = {}
+
+
+class TodoWriteTool(Tool):
+    """Create or update the TODO list for the current session."""
+
+    @property
+    def name(self) -> str:
+        return "todo_write"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Create and manage a structured task list for the current coding session. "
+            "Use for complex multi-step tasks (3+ steps), non-trivial work, or when the user "
+            "provides multiple tasks. Track progress with status: pending, in_progress, completed, cancelled. "
+            "Mark tasks in_progress when starting and completed when done. Keep only ONE in_progress at a time."
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "todos": {
+                    "type": "array",
+                    "description": "The full list of todo items (replaces existing list)",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "id": {
+                                "type": "string",
+                                "description": "Unique identifier for the todo item",
+                            },
+                            "content": {
+                                "type": "string",
+                                "description": "Brief description of the task",
+                            },
+                            "status": {
+                                "type": "string",
+                                "description": "Current status: pending, in_progress, completed, cancelled",
+                                "enum": ["pending", "in_progress", "completed", "cancelled"],
+                            },
+                            "priority": {
+                                "type": "string",
+                                "description": "Priority: high, medium, low (default: medium)",
+                                "enum": ["high", "medium", "low"],
+                            },
+                        },
+                        "required": ["id", "content", "status"],
+                    },
+                }
+            },
+            "required": ["todos"],
+        }
+
+    async def execute(self, args: Dict[str, Any], ctx: ToolContext) -> ToolResult:
+        todos = args.get("todos", [])
+        session_id = getattr(ctx, "session_id", None) or ""
+        # Normalize: ensure each item has id, content, status; optional priority
+        normalized = []
+        for t in todos:
+            item = {
+                "id": str(t.get("id", "")),
+                "content": str(t.get("content", "")),
+                "status": str(t.get("status", "pending")).lower(),
+                "priority": str(t.get("priority", "medium")).lower(),
+            }
+            if item["status"] not in ("pending", "in_progress", "completed", "cancelled"):
+                item["status"] = "pending"
+            if item["priority"] not in ("high", "medium", "low"):
+                item["priority"] = "medium"
+            normalized.append(item)
+        _todo_store[session_id] = normalized
+        pending = sum(1 for t in normalized if t["status"] not in ("completed", "cancelled"))
+        return ToolResult(
+            success=True,
+            output=f"Todo list updated. {len(normalized)} items, {pending} pending.",
+            metadata={"todos": normalized, "count": len(normalized)},
+        )
+
+
+class TodoReadTool(Tool):
+    """Read the current TODO list for the session."""
+
+    @property
+    def name(self) -> str:
+        return "todo_read"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Read the current todo list for the session. Use at the start of work, before starting "
+            "new tasks, or when uncertain about next steps. Returns items with id, content, status, priority. "
+            "If no todos exist, returns an empty list. Leave parameters empty."
+        )
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {"type": "object", "properties": {}, "required": []}
+
+    async def execute(self, args: Dict[str, Any], ctx: ToolContext) -> ToolResult:
+        session_id = getattr(ctx, "session_id", None) or ""
+        todos = _todo_store.get(session_id, [])
+        return ToolResult(
+            success=True,
+            output=json.dumps(todos, indent=2),
+            metadata={"todos": todos, "count": len(todos)},
+        )

superqode/tools/validation.py

@@ -0,0 +1,80 @@
+"""
+Path Validation Utilities.
+
+Provides functions to validate that file paths stay within the working directory,
+preventing directory traversal attacks and unauthorized file access.
+"""
+
+from pathlib import Path
+import os
+from typing import Optional
+
+
+def validate_path_in_working_directory(path: str, working_directory: Path) -> Path:
+    """Validate that a path stays within working_directory.
+
+    This function prevents directory traversal attacks by ensuring that:
+    - Relative paths with `../` cannot escape the working directory
+    - Absolute paths outside the working directory are rejected
+    - All paths are resolved and normalized before validation
+
+    Args:
+        path: Path to validate (can be relative or absolute)
+        working_directory: The allowed working directory (must be absolute)
+
+    Returns:
+        Resolved absolute path within working_directory
+
+    Raises:
+        ValueError: If path escapes working_directory or working_directory is not absolute
+    """
+    # Ensure working_directory is absolute without resolving symlinks.
+    working_dir = Path(working_directory).absolute()
+    working_dir_real = Path(os.path.realpath(working_dir))
+
+    # Resolve the input path without collapsing symlinks so /var stays /var on macOS.
+    input_path = Path(path)
+    if input_path.is_absolute():
+        resolved = Path(os.path.abspath(input_path))
+    else:
+        resolved = Path(os.path.abspath(working_dir / input_path))
+
+    resolved_real = Path(os.path.realpath(resolved))
+
+    try:
+        resolved.relative_to(working_dir)
+        return resolved
+    except ValueError:
+        pass
+
+    try:
+        resolved_real.relative_to(working_dir_real)
+    except ValueError:
+        raise ValueError(
+            f"Path '{path}' resolves to '{resolved_real}' which is outside "
+            f"working directory '{working_dir_real}'. Access denied for security."
+        )
+
+    # Rebase to the non-symlink working directory for consistent relative paths.
+    return working_dir / resolved_real.relative_to(working_dir_real)
+
+
+def validate_working_dir_parameter(working_dir: Optional[str], ctx_working_directory: Path) -> Path:
+    """Validate a working_dir parameter for shell commands.
+
+    Ensures that the working_dir parameter stays within the context's working directory.
+
+    Args:
+        working_dir: Optional working directory parameter from tool call
+        ctx_working_directory: The context's working directory (base for validation)
+
+    Returns:
+        Validated absolute path within ctx_working_directory
+
+    Raises:
+        ValueError: If working_dir escapes ctx_working_directory
+    """
+    if working_dir is None:
+        return ctx_working_directory.resolve()
+
+    return validate_path_in_working_directory(working_dir, ctx_working_directory)