ripperdoc 0.2.6__py3-none-any.whl

ripperdoc/tools/file_read_tool.py

@@ -0,0 +1,203 @@
+"""File reading tool.
+
+Allows the AI to read file contents.
+"""
+
+import os
+from pathlib import Path
+from typing import AsyncGenerator, List, Optional
+from pydantic import BaseModel, Field
+
+from ripperdoc.core.tool import (
+    Tool,
+    ToolUseContext,
+    ToolResult,
+    ToolOutput,
+    ToolUseExample,
+    ValidationResult,
+)
+from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.file_watch import record_snapshot
+from ripperdoc.utils.path_ignore import check_path_for_tool, is_path_ignored
+
+logger = get_logger()
+
+
+class FileReadToolInput(BaseModel):
+    """Input schema for FileReadTool."""
+
+    file_path: str = Field(description="Absolute path to the file to read")
+    offset: Optional[int] = Field(
+        default=None, description="Line number to start reading from (optional)"
+    )
+    limit: Optional[int] = Field(default=None, description="Number of lines to read (optional)")
+
+
+class FileReadToolOutput(BaseModel):
+    """Output from file reading."""
+
+    content: str
+    file_path: str
+    line_count: int
+    offset: int
+    limit: Optional[int]
+
+
+class FileReadTool(Tool[FileReadToolInput, FileReadToolOutput]):
+    """Tool for reading file contents."""
+
+    @property
+    def name(self) -> str:
+        return "View"
+
+    async def description(self) -> str:
+        return """Read the contents of a file. You can optionally specify an offset
+and limit to read only a portion of the file."""
+
+    @property
+    def input_schema(self) -> type[FileReadToolInput]:
+        return FileReadToolInput
+
+    def input_examples(self) -> List[ToolUseExample]:
+        return [
+            ToolUseExample(
+                description="Read the top of a file to understand structure",
+                example={"file_path": "/repo/src/main.py", "limit": 50},
+            ),
+            ToolUseExample(
+                description="Inspect a slice of a large log without loading everything",
+                example={"file_path": "/repo/logs/server.log", "offset": 200, "limit": 40},
+            ),
+        ]
+
+    async def prompt(self, safe_mode: bool = False) -> str:
+        return (
+            "Read a file from the local filesystem.\n\n"
+            "Usage:\n"
+            "- The file_path parameter must be an absolute path (not relative).\n"
+            "- By default, the entire file is read. You can optionally specify a line offset and limit (handy for long files); offset is zero-based and output line numbers start at 1.\n"
+            "- Lines longer than 2000 characters are truncated in the output.\n"
+            "- Results are returned with cat -n style numbering: spaces + line number + tab, then the file content.\n"
+            "- You can call multiple tools in a single response—speculatively read multiple potentially useful files together.\n"
+            "- It is okay to attempt reading a non-existent file; an error will be returned if the file is missing."
+        )
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def is_concurrency_safe(self) -> bool:
+        return True
+
+    def needs_permissions(self, input_data: Optional[FileReadToolInput] = None) -> bool:
+        return False
+
+    async def validate_input(
+        self, input_data: FileReadToolInput, context: Optional[ToolUseContext] = None
+    ) -> ValidationResult:
+        # Check if file exists
+        if not os.path.exists(input_data.file_path):
+            return ValidationResult(result=False, message=f"File not found: {input_data.file_path}")
+
+        # Check if it's a file (not a directory)
+        if not os.path.isfile(input_data.file_path):
+            return ValidationResult(
+                result=False, message=f"Path is not a file: {input_data.file_path}"
+            )
+
+        # Check if path is ignored (warning only for read operations)
+        file_path = Path(input_data.file_path)
+        should_proceed, warning_msg = check_path_for_tool(file_path, tool_name="Read", warn_only=True)
+        if warning_msg:
+            logger.info("[file_read_tool] %s", warning_msg)
+
+        return ValidationResult(result=True)
+
+    def render_result_for_assistant(self, output: FileReadToolOutput) -> str:
+        """Format output for the AI."""
+        lines = output.content.split("\n")
+        numbered_lines = []
+
+        for i, line in enumerate(lines, start=output.offset + 1):
+            # Truncate very long lines
+            if len(line) > 2000:
+                line = line[:2000] + "... [truncated]"
+            numbered_lines.append(f"{i:6d}\t{line}")
+
+        return "\n".join(numbered_lines)
+
+    def render_tool_use_message(self, input_data: FileReadToolInput, verbose: bool = False) -> str:
+        """Format the tool use for display."""
+        msg = f"Reading: {input_data.file_path}"
+        if input_data.offset or input_data.limit:
+            msg += f" (offset: {input_data.offset}, limit: {input_data.limit})"
+        return msg
+
+    async def call(
+        self, input_data: FileReadToolInput, context: ToolUseContext
+    ) -> AsyncGenerator[ToolOutput, None]:
+        """Read the file."""
+
+        try:
+            with open(input_data.file_path, "r", encoding="utf-8", errors="replace") as f:
+                lines = f.readlines()
+
+            offset = input_data.offset or 0
+            limit = input_data.limit
+
+            # Apply offset and limit
+            if limit is not None:
+                selected_lines = lines[offset : offset + limit]
+            else:
+                selected_lines = lines[offset:]
+
+            content = "".join(selected_lines)
+
+            # Remember what we read so we can detect user edits later.
+            # Use absolute path to ensure consistency with Edit tool's lookup
+            abs_file_path = os.path.abspath(input_data.file_path)
+            try:
+                record_snapshot(
+                    abs_file_path,
+                    content,
+                    getattr(context, "file_state_cache", {}),
+                    offset=offset,
+                    limit=limit,
+                )
+            except (OSError, IOError, RuntimeError) as exc:
+                logger.warning(
+                    "[file_read_tool] Failed to record file snapshot: %s: %s",
+                    type(exc).__name__, exc,
+                    extra={"file_path": input_data.file_path},
+                )
+
+            output = FileReadToolOutput(
+                content=content,
+                file_path=input_data.file_path,
+                line_count=len(selected_lines),
+                offset=offset,
+                limit=limit,
+            )
+
+            yield ToolResult(
+                data=output, result_for_assistant=self.render_result_for_assistant(output)
+            )
+
+        except (OSError, IOError, UnicodeDecodeError, ValueError) as e:
+            logger.warning(
+                "[file_read_tool] Error reading file: %s: %s",
+                type(e).__name__, e,
+                extra={"file_path": input_data.file_path},
+            )
+            # Create an error output
+            error_output = FileReadToolOutput(
+                content=f"Error reading file: {str(e)}",
+                file_path=input_data.file_path,
+                line_count=0,
+                offset=0,
+                limit=None,
+            )
+
+            yield ToolResult(
+                data=error_output,
+                result_for_assistant=f"Error reading file {input_data.file_path}: {str(e)}",
+            )

ripperdoc/tools/file_write_tool.py

@@ -0,0 +1,205 @@
+"""File writing tool.
+
+Allows the AI to create new files.
+"""
+
+import os
+from pathlib import Path
+from typing import AsyncGenerator, List, Optional
+from pydantic import BaseModel, Field
+
+from ripperdoc.core.tool import (
+    Tool,
+    ToolUseContext,
+    ToolResult,
+    ToolOutput,
+    ToolUseExample,
+    ValidationResult,
+)
+from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.file_watch import record_snapshot
+from ripperdoc.utils.path_ignore import check_path_for_tool
+
+logger = get_logger()
+
+
+class FileWriteToolInput(BaseModel):
+    """Input schema for FileWriteTool."""
+
+    file_path: str = Field(description="Absolute path to the file to create")
+    content: str = Field(description="Content to write to the file")
+
+
+class FileWriteToolOutput(BaseModel):
+    """Output from file writing."""
+
+    file_path: str
+    bytes_written: int
+    success: bool
+    message: str
+
+
+class FileWriteTool(Tool[FileWriteToolInput, FileWriteToolOutput]):
+    """Tool for creating new files."""
+
+    @property
+    def name(self) -> str:
+        return "Write"
+
+    async def description(self) -> str:
+        return """Create a new file with the specified content. This will overwrite
+the file if it already exists."""
+
+    @property
+    def input_schema(self) -> type[FileWriteToolInput]:
+        return FileWriteToolInput
+
+    def input_examples(self) -> List[ToolUseExample]:
+        return [
+            ToolUseExample(
+                description="Create a JSON fixture file",
+                example={
+                    "file_path": "/repo/tests/fixtures/sample.json",
+                    "content": '{\n  "items": []\n}\n',
+                },
+            ),
+            ToolUseExample(
+                description="Write a short markdown note",
+                example={
+                    "file_path": "/repo/docs/USAGE.md",
+                    "content": "# Usage\n\nRun `make test`.\n",
+                },
+            ),
+        ]
+
+    async def prompt(self, safe_mode: bool = False) -> str:
+        prompt = """Use the Write tool to create new files. """
+
+        if safe_mode:
+            prompt += """IMPORTANT: You must ALWAYS prefer editing existing files.
+NEVER write new files unless explicitly required by the user."""
+
+        return prompt
+
+    def is_read_only(self) -> bool:
+        return False
+
+    def is_concurrency_safe(self) -> bool:
+        return False
+
+    def needs_permissions(self, input_data: Optional[FileWriteToolInput] = None) -> bool:
+        return True
+
+    async def validate_input(
+        self, input_data: FileWriteToolInput, context: Optional[ToolUseContext] = None
+    ) -> ValidationResult:
+        # Check if parent directory exists
+        parent = Path(input_data.file_path).parent
+        if not parent.exists():
+            return ValidationResult(
+                result=False,
+                message=f"Parent directory does not exist: {parent}",
+                error_code=1,
+            )
+
+        file_path = os.path.abspath(input_data.file_path)
+
+        # If file doesn't exist, it's a new file - allow without reading first
+        if not os.path.exists(file_path):
+            return ValidationResult(result=True)
+
+        # File exists - check if it has been read before writing
+        file_state_cache = getattr(context, "file_state_cache", {}) if context else {}
+        file_snapshot = file_state_cache.get(file_path)
+
+        if not file_snapshot:
+            return ValidationResult(
+                result=False,
+                message="File has not been read yet. Read it first before writing to it.",
+                error_code=2,
+            )
+
+        # Check if file has been modified since it was read
+        try:
+            current_mtime = os.path.getmtime(file_path)
+            if current_mtime > file_snapshot.timestamp:
+                return ValidationResult(
+                    result=False,
+                    message="File has been modified since read, either by the user or by a linter. "
+                    "Read it again before attempting to write it.",
+                    error_code=3,
+                )
+        except OSError:
+            pass  # File mtime check failed, proceed anyway
+
+        # Check if path is ignored (warning for write operations)
+        file_path_obj = Path(file_path)
+        should_proceed, warning_msg = check_path_for_tool(file_path_obj, tool_name="Write", warn_only=True)
+        if warning_msg:
+            logger.warning("[file_write_tool] %s", warning_msg)
+
+        return ValidationResult(result=True)
+
+    def render_result_for_assistant(self, output: FileWriteToolOutput) -> str:
+        """Format output for the AI."""
+        return output.message
+
+    def render_tool_use_message(self, input_data: FileWriteToolInput, verbose: bool = False) -> str:
+        """Format the tool use for display."""
+        return f"Writing: {input_data.file_path} ({len(input_data.content)} bytes)"
+
+    async def call(
+        self, input_data: FileWriteToolInput, context: ToolUseContext
+    ) -> AsyncGenerator[ToolOutput, None]:
+        """Write the file."""
+
+        try:
+            # Write the file
+            with open(input_data.file_path, "w", encoding="utf-8") as f:
+                f.write(input_data.content)
+
+            bytes_written = len(input_data.content.encode("utf-8"))
+
+            # Use absolute path to ensure consistency with validation lookup
+            abs_file_path = os.path.abspath(input_data.file_path)
+            try:
+                record_snapshot(
+                    abs_file_path,
+                    input_data.content,
+                    getattr(context, "file_state_cache", {}),
+                )
+            except (OSError, IOError, RuntimeError) as exc:
+                logger.warning(
+                    "[file_write_tool] Failed to record file snapshot: %s: %s",
+                    type(exc).__name__, exc,
+                    extra={"file_path": abs_file_path},
+                )
+
+            output = FileWriteToolOutput(
+                file_path=input_data.file_path,
+                bytes_written=bytes_written,
+                success=True,
+                message=f"Successfully wrote {bytes_written} bytes to {input_data.file_path}",
+            )
+
+            yield ToolResult(
+                data=output, result_for_assistant=self.render_result_for_assistant(output)
+            )
+
+        except (OSError, IOError, PermissionError, UnicodeEncodeError) as e:
+            logger.warning(
+                "[file_write_tool] Error writing file: %s: %s",
+                type(e).__name__, e,
+                extra={"file_path": input_data.file_path},
+            )
+            error_output = FileWriteToolOutput(
+                file_path=input_data.file_path,
+                bytes_written=0,
+                success=False,
+                message=f"Error writing file: {str(e)}",
+            )
+
+            yield ToolResult(
+                data=error_output,
+                result_for_assistant=self.render_result_for_assistant(error_output),
+            )

ripperdoc/tools/glob_tool.py

@@ -0,0 +1,179 @@
+"""Glob pattern matching tool.
+
+Allows the AI to find files using glob patterns.
+"""
+
+from pathlib import Path
+from typing import AsyncGenerator, Optional, List
+from pydantic import BaseModel, Field
+
+from ripperdoc.core.tool import (
+    Tool,
+    ToolUseContext,
+    ToolResult,
+    ToolOutput,
+    ToolUseExample,
+    ValidationResult,
+)
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+
+GLOB_USAGE = (
+    "- Fast file pattern matching tool that works with any codebase size\n"
+    '- Supports glob patterns like "**/*.js" or "src/**/*.ts"\n'
+    "- Returns matching file paths sorted by modification time\n"
+    "- Use this tool when you need to find files by name patterns\n"
+    "- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead\n"
+    "- You have the capability to call multiple tools in a single response. It is always better to speculatively perform multiple searches as a batch that are potentially useful.\n"
+)
+
+RESULT_LIMIT = 100
+
+
+class GlobToolInput(BaseModel):
+    """Input schema for GlobTool."""
+
+    pattern: str = Field(description="Glob pattern to match files (e.g., '**/*.py')")
+    path: Optional[str] = Field(
+        default=None, description="Directory to search in (default: current working directory)"
+    )
+
+
+class GlobToolOutput(BaseModel):
+    """Output from glob pattern matching."""
+
+    matches: List[str]
+    pattern: str
+    count: int
+    truncated: bool = False
+
+
+class GlobTool(Tool[GlobToolInput, GlobToolOutput]):
+    """Tool for finding files using glob patterns."""
+
+    @property
+    def name(self) -> str:
+        return "Glob"
+
+    async def description(self) -> str:
+        return GLOB_USAGE
+
+    @property
+    def input_schema(self) -> type[GlobToolInput]:
+        return GlobToolInput
+
+    def input_examples(self) -> List[ToolUseExample]:
+        return [
+            ToolUseExample(
+                description="Find Python sources inside src",
+                example={"pattern": "src/**/*.py"},
+            ),
+            ToolUseExample(
+                description="Locate snapshot files within tests",
+                example={"pattern": "tests/**/__snapshots__/*.snap", "path": "/repo"},
+            ),
+        ]
+
+    async def prompt(self, _safe_mode: bool = False) -> str:
+        return GLOB_USAGE
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def is_concurrency_safe(self) -> bool:
+        return True
+
+    def needs_permissions(self, _input_data: Optional[GlobToolInput] = None) -> bool:
+        return False
+
+    async def validate_input(
+        self, _input_data: GlobToolInput, _context: Optional[ToolUseContext] = None
+    ) -> ValidationResult:
+        return ValidationResult(result=True)
+
+    def render_result_for_assistant(self, output: GlobToolOutput) -> str:
+        """Format output for the AI."""
+        if not output.matches:
+            return f"No files found matching pattern: {output.pattern}"
+
+        lines = list(output.matches)
+        if output.truncated:
+            lines.append("(Results are truncated. Consider using a more specific path or pattern.)")
+        return "\n".join(lines)
+
+    def render_tool_use_message(self, input_data: GlobToolInput, _verbose: bool = False) -> str:
+        """Format the tool use for display."""
+        if not input_data.pattern:
+            return "Glob"
+
+        base_path = Path.cwd()
+        rendered_path = ""
+        if input_data.path:
+            candidate_path = Path(input_data.path)
+            absolute_path = (
+                candidate_path
+                if candidate_path.is_absolute()
+                else (base_path / candidate_path).resolve()
+            )
+
+            try:
+                relative_path = absolute_path.relative_to(base_path)
+            except ValueError:
+                relative_path = None
+
+            if _verbose or not relative_path or str(relative_path) == ".":
+                rendered_path = str(absolute_path)
+            else:
+                rendered_path = str(relative_path)
+
+        path_fragment = f', path: "{rendered_path}"' if rendered_path else ""
+        return f'pattern: "{input_data.pattern}"{path_fragment}'
+
+    async def call(
+        self, input_data: GlobToolInput, _context: ToolUseContext
+    ) -> AsyncGenerator[ToolOutput, None]:
+        """Find files matching the pattern."""
+
+        try:
+            search_path = Path(input_data.path) if input_data.path else Path.cwd()
+            if not search_path.is_absolute():
+                search_path = (Path.cwd() / search_path).resolve()
+
+            def _mtime(path: Path) -> float:
+                try:
+                    return path.stat().st_mtime
+                except OSError:
+                    return float("-inf")
+
+            # Find matching files, sorted by modification time
+            paths = sorted(
+                (p for p in search_path.glob(input_data.pattern) if p.is_file()),
+                key=_mtime,
+            )
+
+            truncated = len(paths) > RESULT_LIMIT
+            paths = paths[:RESULT_LIMIT]
+
+            matches = [str(p) for p in paths]
+
+            output = GlobToolOutput(
+                matches=matches, pattern=input_data.pattern, count=len(matches), truncated=truncated
+            )
+
+            yield ToolResult(
+                data=output, result_for_assistant=self.render_result_for_assistant(output)
+            )
+
+        except (OSError, RuntimeError, ValueError) as e:
+            logger.warning(
+                "[glob_tool] Error executing glob: %s: %s",
+                type(e).__name__, e,
+                extra={"pattern": input_data.pattern, "path": input_data.path},
+            )
+            error_output = GlobToolOutput(matches=[], pattern=input_data.pattern, count=0)
+
+            yield ToolResult(
+                data=error_output, result_for_assistant=f"Error executing glob: {str(e)}"
+            )