codemaster-cli 1.0.1__py3-none-any.whl

vibe/core/tools/builtins/grep.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator
+from enum import StrEnum, auto
+from pathlib import Path
+import shutil
+from typing import TYPE_CHECKING, ClassVar
+
+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 GrepBackend(StrEnum):
+    RIPGREP = auto()
+    GNU_GREP = auto()
+
+
+class GrepToolConfig(BaseToolConfig):
+    permission: ToolPermission = ToolPermission.ALWAYS
+
+    max_output_bytes: int = Field(
+        default=64_000, description="Hard cap for the total size of matched lines."
+    )
+    default_max_matches: int = Field(
+        default=100, description="Default maximum number of matches to return."
+    )
+    default_timeout: int = Field(
+        default=60, description="Default timeout for the search command in seconds."
+    )
+    exclude_patterns: list[str] = Field(
+        default=[
+            ".venv/",
+            "venv/",
+            ".env/",
+            "env/",
+            "node_modules/",
+            ".git/",
+            "__pycache__/",
+            ".pytest_cache/",
+            ".mypy_cache/",
+            ".tox/",
+            ".nox/",
+            ".coverage/",
+            "htmlcov/",
+            "dist/",
+            "build/",
+            ".idea/",
+            ".vscode/",
+            "*.egg-info",
+            "*.pyc",
+            "*.pyo",
+            "*.pyd",
+            ".DS_Store",
+            "Thumbs.db",
+        ],
+        description="List of glob patterns to exclude from search (dirs should end with /).",
+    )
+    codeignore_file: str = Field(
+        default=".vibeignore",
+        description="Name of the file to read for additional exclusion patterns.",
+    )
+
+
+class GrepState(BaseToolState):
+    search_history: list[str] = Field(default_factory=list)
+
+
+class GrepArgs(BaseModel):
+    pattern: str
+    path: str = "."
+    max_matches: int | None = Field(
+        default=None, description="Override the default maximum number of matches."
+    )
+    use_default_ignore: bool = Field(
+        default=True, description="Whether to respect .gitignore and .ignore files."
+    )
+
+
+class GrepResult(BaseModel):
+    matches: str
+    match_count: int
+    was_truncated: bool = Field(
+        description="True if output was cut short by max_matches or max_output_bytes."
+    )
+
+
+class Grep(
+    BaseTool[GrepArgs, GrepResult, GrepToolConfig, GrepState],
+    ToolUIData[GrepArgs, GrepResult],
+):
+    description: ClassVar[str] = (
+        "Recursively search files for a regex pattern using ripgrep (rg) or grep. "
+        "Respects .gitignore and .codeignore files by default when using ripgrep."
+    )
+
+    def _detect_backend(self) -> GrepBackend:
+        if shutil.which("rg"):
+            return GrepBackend.RIPGREP
+        if shutil.which("grep"):
+            return GrepBackend.GNU_GREP
+        raise ToolError(
+            "Neither ripgrep (rg) nor grep is installed. "
+            "Please install ripgrep: https://github.com/BurntSushi/ripgrep#installation"
+        )
+
+    async def run(
+        self, args: GrepArgs, ctx: InvokeContext | None = None
+    ) -> AsyncGenerator[ToolStreamEvent | GrepResult, None]:
+        backend = self._detect_backend()
+        self._validate_args(args)
+        self.state.search_history.append(args.pattern)
+
+        exclude_patterns = self._collect_exclude_patterns()
+        cmd = self._build_command(args, exclude_patterns, backend)
+        stdout = await self._execute_search(cmd)
+
+        yield self._parse_output(
+            stdout, args.max_matches or self.config.default_max_matches
+        )
+
+    def _validate_args(self, args: GrepArgs) -> None:
+        if not args.pattern.strip():
+            raise ToolError("Empty search pattern provided.")
+
+        path_obj = Path(args.path).expanduser()
+        if not path_obj.is_absolute():
+            path_obj = Path.cwd() / path_obj
+
+        if not path_obj.exists():
+            raise ToolError(f"Path does not exist: {args.path}")
+
+    def _collect_exclude_patterns(self) -> list[str]:
+        patterns = list(self.config.exclude_patterns)
+
+        codeignore_path = Path.cwd() / self.config.codeignore_file
+        if codeignore_path.is_file():
+            patterns.extend(self._load_codeignore_patterns(codeignore_path))
+
+        return patterns
+
+    def _load_codeignore_patterns(self, codeignore_path: Path) -> list[str]:
+        patterns = []
+        try:
+            content = codeignore_path.read_text("utf-8")
+            for line in content.splitlines():
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    patterns.append(line)
+        except OSError:
+            pass
+
+        return patterns
+
+    def _build_command(
+        self, args: GrepArgs, exclude_patterns: list[str], backend: GrepBackend
+    ) -> list[str]:
+        if backend == GrepBackend.RIPGREP:
+            return self._build_ripgrep_command(args, exclude_patterns)
+        return self._build_gnu_grep_command(args, exclude_patterns)
+
+    def _build_ripgrep_command(
+        self, args: GrepArgs, exclude_patterns: list[str]
+    ) -> list[str]:
+        max_matches = args.max_matches or self.config.default_max_matches
+
+        cmd = [
+            "rg",
+            "--line-number",
+            "--no-heading",
+            "--smart-case",
+            "--no-binary",
+            # Request one extra to detect truncation
+            "--max-count",
+            str(max_matches + 1),
+        ]
+
+        if not args.use_default_ignore:
+            cmd.append("--no-ignore")
+
+        for pattern in exclude_patterns:
+            cmd.extend(["--glob", f"!{pattern}"])
+
+        cmd.extend(["-e", args.pattern, args.path])
+
+        return cmd
+
+    def _build_gnu_grep_command(
+        self, args: GrepArgs, exclude_patterns: list[str]
+    ) -> list[str]:
+        max_matches = args.max_matches or self.config.default_max_matches
+
+        cmd = ["grep", "-r", "-n", "-I", "-E", f"--max-count={max_matches + 1}"]
+
+        if args.pattern.islower():
+            cmd.append("-i")
+
+        for pattern in exclude_patterns:
+            if pattern.endswith("/"):
+                dir_pattern = pattern.rstrip("/")
+                cmd.append(f"--exclude-dir={dir_pattern}")
+            else:
+                cmd.append(f"--exclude={pattern}")
+
+        cmd.extend(["-e", args.pattern, args.path])
+
+        return cmd
+
+    async def _execute_search(self, cmd: list[str]) -> str:
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+            )
+
+            try:
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                    proc.communicate(), timeout=self.config.default_timeout
+                )
+            except TimeoutError:
+                proc.kill()
+                await proc.wait()
+                raise ToolError(
+                    f"Search timed out after {self.config.default_timeout}s"
+                )
+
+            stdout = (
+                stdout_bytes.decode("utf-8", errors="ignore") if stdout_bytes else ""
+            )
+            stderr = (
+                stderr_bytes.decode("utf-8", errors="ignore") if stderr_bytes else ""
+            )
+
+            if proc.returncode not in {0, 1}:
+                error_msg = stderr or f"Process exited with code {proc.returncode}"
+                raise ToolError(f"grep error: {error_msg}")
+
+            return stdout
+
+        except ToolError:
+            raise
+        except Exception as exc:
+            raise ToolError(f"Error running grep: {exc}") from exc
+
+    def _parse_output(self, stdout: str, max_matches: int) -> GrepResult:
+        output_lines = stdout.splitlines() if stdout else []
+
+        truncated_lines = output_lines[:max_matches]
+        truncated_output = "\n".join(truncated_lines)
+
+        was_truncated = (
+            len(output_lines) > max_matches
+            or len(truncated_output) > self.config.max_output_bytes
+        )
+
+        final_output = truncated_output[: self.config.max_output_bytes]
+
+        return GrepResult(
+            matches=final_output,
+            match_count=len(truncated_lines),
+            was_truncated=was_truncated,
+        )
+
+    @classmethod
+    def get_call_display(cls, event: ToolCallEvent) -> ToolCallDisplay:
+        if not isinstance(event.args, GrepArgs):
+            return ToolCallDisplay(summary="grep")
+
+        summary = f"Grepping '{event.args.pattern}'"
+        if event.args.path != ".":
+            summary += f" in {event.args.path}"
+        if event.args.max_matches:
+            summary += f" (max {event.args.max_matches} matches)"
+        if not event.args.use_default_ignore:
+            summary += " [no-ignore]"
+
+        return ToolCallDisplay(summary=summary)
+
+    @classmethod
+    def get_result_display(cls, event: ToolResultEvent) -> ToolResultDisplay:
+        if not isinstance(event.result, GrepResult):
+            return ToolResultDisplay(
+                success=False, message=event.error or event.skip_reason or "No result"
+            )
+
+        message = f"Found {event.result.match_count} matches"
+        if event.result.was_truncated:
+            message += " (truncated)"
+
+        warnings = []
+        if event.result.was_truncated:
+            warnings.append("Output was truncated due to size/match limits")
+
+        return ToolResultDisplay(success=True, message=message, warnings=warnings)
+
+    @classmethod
+    def get_status_text(cls) -> str:
+        return "Searching files"

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

@@ -0,0 +1,84 @@
+Use `ask_user_question` to gather information from the user when you need clarification, want to validate assumptions, or need help making a decision. **Don't hesitate to use this tool** - it's better to ask than to guess wrong.
+
+## When to Use
+
+- **Clarifying requirements**: Ambiguous instructions, unclear scope
+- **Technical decisions**: Architecture choices, library selection, tradeoffs
+- **Preference gathering**: UI style, naming conventions, approach options
+- **Validation**: Confirming understanding before starting significant work
+- **Multiple valid paths**: When several approaches could work and you want user input
+
+## Question Structure
+
+Each question has these fields:
+
+- `question`: The full question text (be specific and clear)
+- `header`: A short label displayed as a chip (max 12 characters, e.g., "Auth", "Database", "Approach")
+- `options`: 2-4 choices (an "Other" option is automatically added for free text)
+- `multi_select`: Set to `true` if user can pick multiple options (default: `false`)
+
+### Options Structure
+
+Each option has:
+- `label`: Short display text (1-5 words)
+- `description`: Brief explanation of what this choice means or its implications
+
+## Examples
+
+**Single question with recommended option:**
+```json
+{
+  "questions": [{
+    "question": "Which authentication method should we use?",
+    "header": "Auth",
+    "options": [
+      {"label": "JWT tokens (Recommended)", "description": "Stateless, scalable, works well with APIs"},
+      {"label": "Session cookies", "description": "Traditional approach, requires session storage"},
+      {"label": "OAuth 2.0", "description": "Third-party auth, more complex setup"}
+    ],
+    "multi_select": false
+  }]
+}
+```
+
+**Multiple questions (displayed as tabs):**
+```json
+{
+  "questions": [
+    {
+      "question": "Which database should we use?",
+      "header": "Database",
+      "options": [
+        {"label": "PostgreSQL", "description": "Relational, ACID compliant"},
+        {"label": "MongoDB", "description": "Document store, flexible schema"}
+      ],
+      "multi_select": false
+    },
+    {
+      "question": "Which features should be included in v1?",
+      "header": "Features",
+      "options": [
+        {"label": "User auth", "description": "Login, signup, password reset"},
+        {"label": "Search", "description": "Full-text search across content"},
+        {"label": "Export", "description": "CSV and PDF export"}
+      ],
+      "multi_select": true
+    }
+  ]
+}
+```
+
+## Key Constraints
+
+- **Header max length**: 12 characters (keeps UI clean)
+- **Options count**: 2-4 per question (plus automatic "Other")
+- **Questions count**: 1-4 per call
+- **Label length**: Keep to 1-5 words for readability
+
+## Tips
+
+1. **Put recommended option first** and add "(Recommended)" to its label
+2. **Use descriptive headers** that categorize the question type
+3. **Keep descriptions concise** but informative about tradeoffs
+4. **Use multi_select** when choices aren't mutually exclusive (e.g., features to include)
+5. **Ask early** - it's better to clarify before starting than to redo work

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

@@ -0,0 +1,73 @@
+Use the `bash` tool to run one-off shell commands.
+
+**Key characteristics:**
+- **Stateless**: Each command runs independently in a fresh environment
+
+**Timeout:**
+- The `timeout` argument controls how long the command can run before being killed
+- When `timeout` is not specified (or set to `None`), the config default is used
+- If a command is timing out, do not hesitate to increase the timeout using the `timeout` argument
+
+**IMPORTANT: Use dedicated tools if available instead of these bash commands:**
+
+**File Operations - DO NOT USE:**
+- `cat filename` → Use `read_file(path="filename")`
+- `head -n 20 filename` → Use `read_file(path="filename", limit=20)`
+- `tail -n 20 filename` → Read with offset: `read_file(path="filename", offset=<line_number>, limit=20)`
+- `sed -n '100,200p' filename` → Use `read_file(path="filename", offset=99, limit=101)`
+- `less`, `more`, `vim`, `nano` → Use `read_file` with offset/limit for navigation
+- `echo "content" > file` → Use `write_file(path="file", content="content")`
+- `echo "content" >> file` → Read first, then `write_file` with overwrite=true
+
+**Search Operations - DO NOT USE:**
+- `grep -r "pattern" .` → Use `grep(pattern="pattern", path=".")`
+- `find . -name "*.py"` → Use `bash("ls -la")` for current dir or `grep` with appropriate pattern
+- `ag`, `ack`, `rg` commands → Use the `grep` tool
+- `locate` → Use `grep` tool
+
+**File Modification - DO NOT USE:**
+- `sed -i 's/old/new/g' file` → Use `search_replace` tool
+- `awk` for file editing → Use `search_replace` tool
+- Any in-place file editing → Use `search_replace` tool
+
+**APPROPRIATE bash uses:**
+- System information: `pwd`, `whoami`, `date`, `uname -a`
+- Directory listings: `ls -la`, `tree` (if available)
+- Git operations: `git status`, `git log --oneline -10`, `git diff`
+- Process info: `ps aux | grep process`, `top -n 1`
+- Network checks: `ping -c 1 google.com`, `curl -I https://example.com`
+- Package management: `pip list`, `npm list`
+- Environment checks: `env | grep VAR`, `which python`
+- File metadata: `stat filename`, `file filename`, `wc -l filename`
+
+**Example: Reading a large file efficiently**
+
+WRONG:
+```bash
+bash("cat large_file.txt")  # May hit size limits
+bash("head -1000 large_file.txt")  # Inefficient
+```
+
+RIGHT:
+```python
+# First chunk
+read_file(path="large_file.txt", limit=1000)
+# If was_truncated=true, read next chunk
+read_file(path="large_file.txt", offset=1000, limit=1000)
+```
+
+**Example: Searching for patterns**
+
+WRONG:
+```bash
+bash("grep -r 'TODO' src/")  # Don't use bash for grep
+bash("find . -type f -name '*.py' | xargs grep 'import'")  # Too complex
+```
+
+RIGHT:
+```python
+grep(pattern="TODO", path="src/")
+grep(pattern="import", path=".")
+```
+
+**Remember:** Bash is best for quick system checks and git operations. For file operations, searching, and editing, always use the dedicated tools when they are available.

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

@@ -0,0 +1,43 @@
+## git_clone
+
+Clone a public GitHub repository into the current working directory.
+
+### Parameters
+
+- `repo` (string, required): The GitHub repository to clone. Accepts:
+  - Full URL: `https://github.com/owner/repo`
+  - Full URL with .git: `https://github.com/owner/repo.git`
+  - Short form: `owner/repo`
+  - SSH URL: `git@github.com:owner/repo.git`
+- `destination` (string, optional): Target directory name. Defaults to the repository name.
+- `branch` (string, optional): Specific branch to clone. Defaults to the repository's default branch.
+- `depth` (integer, optional): Create a shallow clone with the specified number of commits. Use `1` for the shallowest clone.
+- `sparse_paths` (array of strings, optional): Only checkout specific directories/files. Useful for large monorepos.
+
+### Usage Guidelines
+
+- Use this tool when the user asks to clone, download, fetch, or pull a GitHub repository.
+- Always confirm the repository URL with the user if ambiguous.
+- For large repositories, suggest using `depth: 1` for faster cloning.
+- For monorepos where only a subdirectory is needed, use `sparse_paths`.
+- The destination directory must not already exist.
+- Only public GitHub repositories are supported.
+- After cloning, briefly summarize what was cloned (branch, file count, top-level structure).
+
+### Examples
+
+Clone a repository:
+
+    git_clone(repo="facebook/react")
+
+Clone to a specific directory:
+
+    git_clone(repo="https://github.com/facebook/react", destination="react-source")
+
+Shallow clone of a specific branch:
+
+    git_clone(repo="torvalds/linux", branch="v6.5", depth=1)
+
+Sparse checkout (only specific directories):
+
+    git_clone(repo="google/jax", sparse_paths=["jax/numpy", "tests/numpy_test.py"])

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

@@ -0,0 +1,38 @@
+You are GitMaster, a specialized agent within CodeMaster focused on cloning and exploring GitHub repositories.
+
+## Your Primary Capabilities
+
+1. **Repository Cloning**: You can clone any public GitHub repository using the `git_clone` tool.
+2. **Codebase Exploration**: After cloning, you help users understand the repository structure, key files, and architecture.
+3. **Smart Suggestions**: You proactively suggest optimal clone strategies (shallow vs full, sparse checkout for monorepos).
+
+## Workflow
+
+When a user asks you to clone a repository:
+
+1. **Parse the request**: Extract the repository URL/identifier from the user's natural language request.
+2. **Confirm if needed**: If the request is ambiguous, ask for clarification using `ask_user_question`.
+3. **Optimize**: For repositories known to be large, suggest shallow cloning or sparse checkout.
+4. **Clone**: Use the `git_clone` tool with appropriate parameters.
+5. **Explore**: After cloning, automatically provide an overview of the repository:
+   - Read the README.md if it exists
+   - Summarize the project structure
+   - Identify the primary language/framework
+   - Note any setup instructions
+
+## Guidelines
+
+- Always use the `git_clone` tool for cloning — never use `bash` with raw `git clone` commands.
+- If the user provides just a repo name without an owner (e.g., "clone react"), ask which owner/organization they mean or suggest the most popular one.
+- After cloning, offer to help explore specific parts of the codebase.
+- If cloning fails, diagnose the issue and suggest solutions.
+- You can use `grep`, `read_file`, and other exploration tools to help users understand cloned repositories.
+- Track your progress using the `todo` tool when handling complex multi-step requests.
+- You can delegate exploration tasks to subagents using the `task` tool.
+
+## Response Style
+
+- Be concise but informative.
+- Use emoji sparingly for status indicators (✅ success, ❌ error, 📦 repo info).
+- When presenting repository structure, use tree-like formatting.
+- Always confirm the clone location to the user.

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

@@ -0,0 +1,4 @@
+Use `grep` to recursively search for a regular expression pattern in files.
+
+- It's very fast and automatically ignores files that you should not read like .pyc files, .venv directories, etc.
+- Use this to find where functions are defined, how variables are used, or to locate specific error messages.

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

@@ -0,0 +1,13 @@
+Use `read_file` to read the content of a file. It's designed to handle large files safely.
+
+- By default, it reads from the beginning of the file.
+- Use `offset` (line number) and `limit` (number of lines) to read specific parts or chunks of a file. This is efficient for exploring large files.
+- The result includes `was_truncated: true` if the file content was cut short due to size limits.
+
+**Strategy for large files:**
+
+1. Call `read_file` with a `limit` (e.g., 1000 lines) to get the start of the file.
+2. If `was_truncated` is true, you know the file is large.
+3. To read the next chunk, call `read_file` again with an `offset`. For example, `offset=1000, limit=1000`.
+
+This is more efficient than using `bash` with `cat` or `wc`.

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

@@ -0,0 +1,43 @@
+Use `search_replace` to make targeted changes to files using SEARCH/REPLACE blocks. This tool finds exact text matches and replaces them.
+
+Arguments:
+- `file_path`: The path to the file to modify
+- `content`: The SEARCH/REPLACE blocks defining the changes
+
+The content format is:
+
+```
+<<<<<<< SEARCH
+[exact text to find in the file]
+=======
+[exact text to replace it with]
+>>>>>>> REPLACE
+```
+
+You can include multiple SEARCH/REPLACE blocks to make multiple changes to the same file:
+
+```
+<<<<<<< SEARCH
+def old_function():
+    return "old value"
+=======
+def new_function():
+    return "new value"
+>>>>>>> REPLACE
+
+<<<<<<< SEARCH
+import os
+=======
+import os
+import sys
+>>>>>>> REPLACE
+```
+
+IMPORTANT:
+
+- The SEARCH text must match EXACTLY (including whitespace, indentation, and line endings)
+- The SEARCH text must appear exactly once in the file - if it appears multiple times, the tool will error
+- Use at least 5 equals signs (=====) between SEARCH and REPLACE sections
+- The tool will provide detailed error messages showing context if search text is not found
+- Each search/replace block is applied in order, so later blocks see the results of earlier ones
+- Be careful with escape sequences in string literals - use \n not \\n for newlines in code

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

@@ -0,0 +1,24 @@
+Use `task` to delegate work to a subagent for independent execution.
+
+## When to Use This Tool
+
+- **Context management**: Delegate tasks that would consume too much main conversation context
+- **Specialized work**: Use the appropriate subagent for the type of task (exploration, research, etc.)
+- **Parallel execution**: Launch multiple subagents for independent tasks
+- **Autonomous work**: Tasks that don't require back-and-forth with the user
+
+## Best Practices
+
+1. **Write clear, detailed task descriptions** - The subagent works autonomously, so provide enough context for it to succeed independently
+
+2. **Choose the right subagent** - Match the subagent to the task type (see available subagents in system prompt)
+
+3. **Prefer direct tools for simple operations** - If you know exactly which file to read or pattern to search, use those tools directly instead of spawning a subagent
+
+4. **Trust the subagent's judgment** - Let it explore and find information without micromanaging the approach
+
+## Limitations
+
+- Subagents cannot write or modify files
+- Subagents cannot ask the user questions
+- Results are returned as text when the subagent completes