codemaster-cli 1.0.1__py3-none-any.whl

vibe/core/tools/builtins/prompts/todo.md

@@ -0,0 +1,199 @@
+Use the `todo` tool to manage a simple task list. This tool helps you track tasks and their progress.
+
+## How it works
+
+- **Reading:** Use `action: "read"` to view the current todo list
+- **Writing:** Use `action: "write"` with the complete `todos` list to update. You must provide the ENTIRE list - this replaces everything.
+
+## Todo Structure
+Each todo item has:
+- `id`: A unique string identifier (e.g., "1", "2", "task-a")
+- `content`: The task description
+- `status`: One of: "pending", "in_progress", "completed", "cancelled"
+- `priority`: One of: "high", "medium", "low"
+
+## When to Use This Tool
+
+**Use proactively for:**
+- Complex multi-step tasks (3+ distinct steps)
+- Non-trivial tasks requiring careful planning
+- Multiple tasks provided by the user (numbered or comma-separated)
+- Tracking progress on ongoing work
+- After receiving new instructions - immediately capture requirements
+- When starting work - mark task as in_progress BEFORE beginning
+- After completing work - mark as completed and add any follow-up tasks discovered
+
+**Skip this tool for:**
+- Single, straightforward tasks
+- Trivial operations (< 3 simple steps)
+- Purely conversational or informational requests
+- Tasks that provide no organizational benefit
+
+## Task Management Best Practices
+
+1. **Status Management:**
+   - Only ONE task should be `in_progress` at a time
+   - Mark tasks `in_progress` BEFORE starting work on them
+   - Mark tasks `completed` IMMEDIATELY after finishing
+   - Keep tasks `in_progress` if blocked or encountering errors
+
+2. **Task Completion Rules:**
+   - ONLY mark as `completed` when FULLY accomplished
+   - Never mark complete if tests are failing, implementation is partial, or errors are unresolved
+   - When blocked, create a new task describing what needs resolution
+
+3. **Task Organization:**
+   - Create specific, actionable items
+   - Break complex tasks into manageable steps
+   - Use clear, descriptive task names
+   - Remove irrelevant tasks entirely (don't just mark cancelled)
+
+## Examples
+
+**Example 1: Reading todos**
+```json
+{
+  "action": "read"
+}
+```
+
+**Example 2: Initial task creation (user requests multiple features)**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Add dark mode toggle to settings",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "Implement theme context/state management",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update components for theme switching",
+      "status": "pending",
+      "priority": "medium"
+    },
+    {
+      "id": "4",
+      "content": "Run tests and verify build",
+      "status": "pending",
+      "priority": "medium"
+    }
+  ]
+}
+```
+
+**Example 3: Starting work (marking one task in_progress)**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Add dark mode toggle to settings",
+      "status": "in_progress",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "Implement theme context/state management",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update components for theme switching",
+      "status": "pending",
+      "priority": "medium"
+    },
+    {
+      "id": "4",
+      "content": "Run tests and verify build",
+      "status": "pending",
+      "priority": "medium"
+    }
+  ]
+}
+```
+
+**Example 4: Completing task and adding discovered subtask**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Add dark mode toggle to settings",
+      "status": "completed",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "Implement theme context/state management",
+      "status": "in_progress",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update components for theme switching",
+      "status": "pending",
+      "priority": "medium"
+    },
+    {
+      "id": "4",
+      "content": "Fix TypeScript errors in theme types",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "5",
+      "content": "Run tests and verify build",
+      "status": "pending",
+      "priority": "medium"
+    }
+  ]
+}
+```
+
+**Example 5: Handling blockers (keeping task in_progress)**
+```json
+{
+  "action": "write",
+  "todos": [
+    {
+      "id": "1",
+      "content": "Deploy to production",
+      "status": "in_progress",
+      "priority": "high"
+    },
+    {
+      "id": "2",
+      "content": "BLOCKER: Fix failing deployment pipeline",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "3",
+      "content": "Update documentation",
+      "status": "pending",
+      "priority": "low"
+    }
+  ]
+}
+```
+
+## Common Scenarios
+
+**Multi-file refactoring:** Create todos for each file that needs updating
+**Performance optimization:** List specific bottlenecks as individual tasks
+**Bug fixing:** Track reproduction, diagnosis, fix, and verification as separate tasks
+**Feature implementation:** Break down into UI, logic, tests, and documentation tasks
+
+Remember: When writing, you must include ALL todos you want to keep. Any todo not in the list will be removed. Be proactive with task management to demonstrate thoroughness and ensure all requirements are completed successfully.

vibe/core/tools/builtins/prompts/write_file.md

@@ -0,0 +1,42 @@
+Use `write_file` to write content to a file.
+
+**Arguments:**
+- `path`: The file path (relative or absolute)
+- `content`: The content to write to the file
+- `overwrite`: Must be set to `true` to overwrite an existing file (default: `false`)
+
+**IMPORTANT SAFETY RULES:**
+
+- By default, the tool will **fail if the file already exists** to prevent accidental data loss
+- To **overwrite** an existing file, you **MUST** set `overwrite: true`
+- To **create a new file**, just provide the `path` and `content` (overwrite defaults to false)
+- If parent directories don't exist, they will be created automatically
+
+**BEST PRACTICES:**
+
+- **ALWAYS** use the `read_file` tool first before overwriting an existing file to understand its current contents
+- **ALWAYS** prefer using `search_replace` to edit existing files rather than overwriting them completely
+- **NEVER** write new files unless explicitly required - prefer modifying existing files
+- **NEVER** proactively create documentation files (*.md) or README files unless explicitly requested
+- **AVOID** using emojis in file content unless the user explicitly requests them
+
+**Usage Examples:**
+
+```python
+# Create a new file (will error if file exists)
+write_file(
+    path="src/new_module.py",
+    content="def hello():\n    return 'Hello World'"
+)
+
+# Overwrite an existing file (must read it first!)
+# First: read_file(path="src/existing.py")
+# Then:
+write_file(
+    path="src/existing.py",
+    content="# Updated content\ndef new_function():\n    pass",
+    overwrite=True
+)
+```
+
+**Remember:** For editing existing files, prefer `search_replace` over `write_file` to preserve unchanged portions and avoid accidental data loss.

vibe/core/tools/builtins/read_file.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, NamedTuple, final
+
+import anyio
+from pydantic import BaseModel, Field
+
+from vibe.core.tools.base import (
+    BaseTool,
+    BaseToolConfig,
+    BaseToolState,
+    InvokeContext,
+    ToolError,
+    ToolPermission,
+)
+from vibe.core.tools.ui import ToolCallDisplay, ToolResultDisplay, ToolUIData
+from vibe.core.types import ToolStreamEvent
+
+if TYPE_CHECKING:
+    from vibe.core.types import ToolCallEvent, ToolResultEvent
+
+
+class _ReadResult(NamedTuple):
+    lines: list[str]
+    bytes_read: int
+    was_truncated: bool
+
+
+class ReadFileArgs(BaseModel):
+    path: str
+    offset: int = Field(
+        default=0,
+        description="Line number to start reading from (0-indexed, inclusive).",
+    )
+    limit: int | None = Field(
+        default=None, description="Maximum number of lines to read."
+    )
+
+
+class ReadFileResult(BaseModel):
+    path: str
+    content: str
+    lines_read: int
+    was_truncated: bool = Field(
+        description="True if the reading was stopped due to the max_read_bytes limit."
+    )
+
+
+class ReadFileToolConfig(BaseToolConfig):
+    permission: ToolPermission = ToolPermission.ALWAYS
+
+    max_read_bytes: int = Field(
+        default=64_000, description="Maximum total bytes to read from a file in one go."
+    )
+    max_state_history: int = Field(
+        default=10, description="Number of recently read files to remember in state."
+    )
+
+
+class ReadFileState(BaseToolState):
+    recently_read_files: list[str] = Field(default_factory=list)
+
+
+class ReadFile(
+    BaseTool[ReadFileArgs, ReadFileResult, ReadFileToolConfig, ReadFileState],
+    ToolUIData[ReadFileArgs, ReadFileResult],
+):
+    description: ClassVar[str] = (
+        "Read a UTF-8 file, returning content from a specific line range. "
+        "Reading is capped by a byte limit for safety."
+    )
+
+    @final
+    async def run(
+        self, args: ReadFileArgs, ctx: InvokeContext | None = None
+    ) -> AsyncGenerator[ToolStreamEvent | ReadFileResult, None]:
+        file_path = self._prepare_and_validate_path(args)
+
+        read_result = await self._read_file(args, file_path)
+
+        self._update_state_history(file_path)
+
+        yield ReadFileResult(
+            path=str(file_path),
+            content="".join(read_result.lines),
+            lines_read=len(read_result.lines),
+            was_truncated=read_result.was_truncated,
+        )
+
+    def check_allowlist_denylist(self, args: ReadFileArgs) -> ToolPermission | None:
+        import fnmatch
+
+        file_path = Path(args.path).expanduser()
+        if not file_path.is_absolute():
+            file_path = Path.cwd() / file_path
+        file_str = str(file_path)
+
+        for pattern in self.config.denylist:
+            if fnmatch.fnmatch(file_str, pattern):
+                return ToolPermission.NEVER
+
+        for pattern in self.config.allowlist:
+            if fnmatch.fnmatch(file_str, pattern):
+                return ToolPermission.ALWAYS
+
+        return None
+
+    def _prepare_and_validate_path(self, args: ReadFileArgs) -> Path:
+        self._validate_inputs(args)
+
+        file_path = Path(args.path).expanduser()
+        if not file_path.is_absolute():
+            file_path = Path.cwd() / file_path
+
+        self._validate_path(file_path)
+        return file_path
+
+    async def _read_file(self, args: ReadFileArgs, file_path: Path) -> _ReadResult:
+        try:
+            lines_to_return: list[str] = []
+            bytes_read = 0
+            was_truncated = False
+
+            async with await anyio.Path(file_path).open(
+                encoding="utf-8", errors="ignore"
+            ) as f:
+                line_index = 0
+                async for line in f:
+                    if line_index < args.offset:
+                        line_index += 1
+                        continue
+
+                    if args.limit is not None and len(lines_to_return) >= args.limit:
+                        break
+
+                    line_bytes = len(line.encode("utf-8"))
+                    if bytes_read + line_bytes > self.config.max_read_bytes:
+                        was_truncated = True
+                        break
+
+                    lines_to_return.append(line)
+                    bytes_read += line_bytes
+                    line_index += 1
+
+            return _ReadResult(
+                lines=lines_to_return,
+                bytes_read=bytes_read,
+                was_truncated=was_truncated,
+            )
+
+        except OSError as exc:
+            raise ToolError(f"Error reading {file_path}: {exc}") from exc
+
+    def _validate_inputs(self, args: ReadFileArgs) -> None:
+        if not args.path.strip():
+            raise ToolError("Path cannot be empty")
+        if args.offset < 0:
+            raise ToolError("Offset cannot be negative")
+        if args.limit is not None and args.limit <= 0:
+            raise ToolError("Limit, if provided, must be a positive number")
+
+    def _validate_path(self, file_path: Path) -> None:
+        try:
+            resolved_path = file_path.resolve()
+        except ValueError:
+            raise ToolError(
+                f"Security error: Cannot read path '{file_path}' outside of the project directory '{Path.cwd()}'."
+            )
+        except FileNotFoundError:
+            raise ToolError(f"File not found at: {file_path}")
+
+        if not resolved_path.exists():
+            raise ToolError(f"File not found at: {file_path}")
+        if resolved_path.is_dir():
+            raise ToolError(f"Path is a directory, not a file: {file_path}")
+
+    def _update_state_history(self, file_path: Path) -> None:
+        self.state.recently_read_files.append(str(file_path.resolve()))
+        if len(self.state.recently_read_files) > self.config.max_state_history:
+            self.state.recently_read_files.pop(0)
+
+    @classmethod
+    def get_call_display(cls, event: ToolCallEvent) -> ToolCallDisplay:
+        if not isinstance(event.args, ReadFileArgs):
+            return ToolCallDisplay(summary="read_file")
+
+        summary = f"Reading {event.args.path}"
+        if event.args.offset > 0 or event.args.limit is not None:
+            parts = []
+            if event.args.offset > 0:
+                parts.append(f"from line {event.args.offset}")
+            if event.args.limit is not None:
+                parts.append(f"limit {event.args.limit} lines")
+            summary += f" ({', '.join(parts)})"
+
+        return ToolCallDisplay(summary=summary)
+
+    @classmethod
+    def get_result_display(cls, event: ToolResultEvent) -> ToolResultDisplay:
+        if not isinstance(event.result, ReadFileResult):
+            return ToolResultDisplay(
+                success=False, message=event.error or event.skip_reason or "No result"
+            )
+
+        path_obj = Path(event.result.path)
+        message = f"Read {event.result.lines_read} line{'' if event.result.lines_read <= 1 else 's'} from {path_obj.name}"
+        if event.result.was_truncated:
+            message += " (truncated)"
+
+        return ToolResultDisplay(
+            success=True,
+            message=message,
+            warnings=["File was truncated due to size limit"]
+            if event.result.was_truncated
+            else [],
+        )
+
+    @classmethod
+    def get_status_text(cls) -> str:
+        return "Reading file"