euron-code 0.1.0__py3-none-any.whl

euron_code/tools/fs.py

@@ -0,0 +1,412 @@
+"""File tools: read_file, write_file, edit_file, multi_edit, list_dir."""
+
+from __future__ import annotations
+
+import difflib
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from euron_code.permissions import Request
+from euron_code.tools.base import Tool, ToolContext, ToolError, ToolResult, opt_int, require, truncate
+from euron_code.tools.ignore import ALWAYS_SKIP_DIRS, GitIgnore, is_binary_bytes
+
+DEFAULT_READ_LIMIT = 400
+MAX_LINE_CHARS = 1000
+MAX_FILE_BYTES = 5 * 1024 * 1024
+
+
+# ---------------------------------------------------------------- text helpers
+
+class TextFile:
+    """A decoded text file that remembers its BOM so writes round-trip."""
+
+    def __init__(self, text: str, bom: bool):
+        self.text = text
+        self.bom = bom
+
+    @property
+    def crlf(self) -> bool:
+        return "\r\n" in self.text
+
+
+def load_text(path: Path) -> TextFile:
+    if not path.exists():
+        raise ToolError(f"File not found: {path}")
+    if path.is_dir():
+        raise ToolError(f"{path} is a directory. Use list_dir.")
+    size = path.stat().st_size
+    if size > MAX_FILE_BYTES:
+        raise ToolError(f"{path} is {size // 1024} KB, too large to load. Use grep or read a line range.")
+    data = path.read_bytes()
+    if is_binary_bytes(data):
+        raise ToolError(f"{path} looks like a binary file; not reading it.")
+    bom = data.startswith(b"\xef\xbb\xbf")
+    if bom:
+        data = data[3:]
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        raise ToolError(f"{path} is not UTF-8 text.")
+    return TextFile(text, bom)
+
+
+def save_text(path: Path, tf: TextFile) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = tf.text.encode("utf-8")
+    if tf.bom:
+        data = b"\xef\xbb\xbf" + data
+    tmp = path.with_name(path.name + ".euron-tmp")
+    with open(tmp, "wb") as f:
+        f.write(data)
+    try:
+        if path.exists():
+            os.chmod(tmp, path.stat().st_mode)
+    except OSError:
+        pass
+    os.replace(tmp, path)
+
+
+def make_diff(old: str, new: str, label: str) -> str:
+    a = old.replace("\r\n", "\n").splitlines(keepends=True)
+    b = new.replace("\r\n", "\n").splitlines(keepends=True)
+    lines = difflib.unified_diff(a, b, fromfile=f"a/{label}", tofile=f"b/{label}", n=3)
+    out = []
+    for ln in lines:
+        out.append(ln if ln.endswith("\n") else ln + "\n\\n")
+    return "".join(out)
+
+
+def _adapt_newlines(s: str, crlf: bool) -> str:
+    if crlf and "\r\n" not in s:
+        return s.replace("\n", "\r\n")
+    return s
+
+
+def _near_miss_hint(text: str, old: str) -> str:
+    first = next((ln for ln in old.splitlines() if ln.strip()), "").strip()
+    if not first:
+        return ""
+    lines = text.splitlines()
+    stripped = [ln.strip() for ln in lines]
+    if first in stripped:
+        n = stripped.index(first) + 1
+        return (f" A line matching the first line of old_string exists at line {n}, so the "
+                "difference is probably indentation or whitespace. Re-read that range and copy it exactly.")
+    close = difflib.get_close_matches(first, stripped, n=1, cutoff=0.7)
+    if close:
+        n = stripped.index(close[0]) + 1
+        return f" The closest line is {n}: {lines[n - 1].strip()[:120]!r}. Re-read the file before retrying."
+    return " Re-read the file; it may have changed."
+
+
+def apply_edit(text: str, old: str, new: str, replace_all: bool = False) -> Tuple[str, int]:
+    """Exact string replacement with a unique-match check. Returns (new_text, count)."""
+    if old == "":
+        raise ToolError("old_string is empty. To create or overwrite a file use write_file.")
+    if old == new:
+        raise ToolError("old_string and new_string are identical; nothing to change.")
+    crlf = "\r\n" in text
+    old_a, new_a = _adapt_newlines(old, crlf), _adapt_newlines(new, crlf)
+    count = text.count(old_a)
+    if count == 0 and old_a != old:
+        old_a, new_a = old, new
+        count = text.count(old_a)
+    if count == 0:
+        raise ToolError("old_string was not found in the file." + _near_miss_hint(text, old))
+    if count > 1 and not replace_all:
+        raise ToolError(
+            f"old_string matches {count} places. Add more surrounding lines to make it unique, "
+            "or set replace_all to true to change every occurrence."
+        )
+    return text.replace(old_a, new_a), count
+
+
+# ---------------------------------------------------------------- read_file
+
+class ReadFile(Tool):
+    name = "read_file"
+    read_only = True
+    description = (
+        "Read a text file from the project. Output has line numbers (`  12\\tcode`); the numbers "
+        "are not part of the file. Reads up to 400 lines by default; use offset/limit for long files. "
+        "Always read a file before editing it."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File path, relative to the project root or absolute."},
+            "offset": {"type": "integer", "description": "1-based line to start from (default 1)."},
+            "limit": {"type": "integer", "description": "Maximum number of lines (default 400)."},
+        },
+        "required": ["path"],
+    }
+
+    def permission(self, args, ctx):
+        return Request("Read", self.name, paths=[ctx.resolve(require(args, "path"))])
+
+    def describe(self, args, ctx):
+        s = ctx.rel(ctx.resolve(args.get("path", "")))
+        if args.get("offset") or args.get("limit"):
+            s += f" (from line {args.get('offset') or 1}, {args.get('limit') or DEFAULT_READ_LIMIT} lines)"
+        return s
+
+    def run(self, args, ctx):
+        path = ctx.resolve(require(args, "path"))
+        offset = max(1, opt_int(args, "offset", 1) or 1)
+        limit = max(1, min(opt_int(args, "limit", DEFAULT_READ_LIMIT) or DEFAULT_READ_LIMIT, 2000))
+        rng = (offset, limit)
+        if ctx.tracker.already_has(path, rng):
+            return ToolResult(
+                f"{ctx.rel(path)} has not changed since you read lines {offset}-{offset + limit - 1} "
+                "earlier in this conversation. Use that earlier output.",
+                preview="(unchanged since last read)",
+            )
+        tf = load_text(path)
+        lines = tf.text.replace("\r\n", "\n").split("\n")
+        if lines and lines[-1] == "":
+            lines.pop()
+        total = len(lines)
+        if total == 0:
+            ctx.tracker.mark_read(path, rng)
+            return ToolResult(f"{ctx.rel(path)} is empty.")
+        if offset > total:
+            raise ToolError(f"offset {offset} is past the end of the file ({total} lines).")
+        chunk = lines[offset - 1: offset - 1 + limit]
+        out = []
+        for i, ln in enumerate(chunk, start=offset):
+            if len(ln) > MAX_LINE_CHARS:
+                ln = ln[:MAX_LINE_CHARS] + f"... [line truncated, {len(ln)} chars]"
+            out.append(f"{i:>6}\t{ln}")
+        end = offset + len(chunk) - 1
+        body = "\n".join(out)
+        if offset > 1 or end < total:
+            body += f"\n\n(Showing lines {offset}-{end} of {total}. Use offset/limit to read more.)"
+        ctx.tracker.mark_read(path, rng)
+        return ToolResult(truncate(body, ctx.max_output_chars, "read a smaller range"),
+                          preview=f"read {len(chunk)} lines ({offset}-{end} of {total})")
+
+
+# ---------------------------------------------------------------- write_file
+
+class WriteFile(Tool):
+    name = "write_file"
+    description = (
+        "Create a new file or completely replace an existing one. For changes to an existing file "
+        "prefer edit_file. You must read_file an existing file before overwriting it."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File path relative to the project root."},
+            "content": {"type": "string", "description": "The full file content."},
+        },
+        "required": ["path", "content"],
+    }
+
+    def permission(self, args, ctx):
+        return Request("Edit", self.name, paths=[ctx.resolve(require(args, "path"))])
+
+    def describe(self, args, ctx):
+        p = ctx.resolve(args.get("path", ""))
+        return ("overwrite " if p.exists() else "create ") + ctx.rel(p)
+
+    def _check(self, args, ctx):
+        path = ctx.resolve(require(args, "path"))
+        content = require(args, "content")
+        old = ""
+        bom = False
+        if path.exists():
+            if path.is_dir():
+                raise ToolError(f"{path} is a directory.")
+            if not ctx.tracker.was_read(path):
+                raise ToolError(f"{ctx.rel(path)} already exists. Read it with read_file before overwriting it.")
+            if not ctx.tracker.unchanged_since_read(path):
+                raise ToolError(f"{ctx.rel(path)} changed since you last read it. Read it again first.")
+            tf = load_text(path)
+            old, bom = tf.text, tf.bom
+            if tf.crlf and "\r\n" not in content:
+                content = content.replace("\n", "\r\n")
+        return path, old, content, bom
+
+    def preview(self, args, ctx):
+        path, old, content, _ = self._check(args, ctx)
+        return make_diff(old, content, ctx.rel(path))
+
+    def run(self, args, ctx):
+        path, old, content, bom = self._check(args, ctx)
+        existed = path.exists()
+        save_text(path, TextFile(content, bom))
+        ctx.tracker.mark_written(path)
+        n = content.count("\n") + (0 if content.endswith("\n") or not content else 1)
+        verb = "Updated" if existed else "Created"
+        return ToolResult(f"{verb} {ctx.rel(path)} ({n} lines).")
+
+
+# ---------------------------------------------------------------- edit_file / multi_edit
+
+class EditFile(Tool):
+    name = "edit_file"
+    description = (
+        "Replace an exact string in a file. old_string must match the file exactly (including "
+        "indentation) and must be unique unless replace_all is true. Do not include the line-number "
+        "prefix from read_file. Read the file first."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+            "old_string": {"type": "string", "description": "Exact text to replace."},
+            "new_string": {"type": "string", "description": "Replacement text."},
+            "replace_all": {"type": "boolean", "description": "Replace every occurrence (default false)."},
+        },
+        "required": ["path", "old_string", "new_string"],
+    }
+
+    def permission(self, args, ctx):
+        return Request("Edit", self.name, paths=[ctx.resolve(require(args, "path"))])
+
+    def describe(self, args, ctx):
+        return ctx.rel(ctx.resolve(args.get("path", "")))
+
+    def edits(self, args) -> List[Dict[str, Any]]:
+        return [{"old_string": require(args, "old_string"), "new_string": require(args, "new_string"),
+                 "replace_all": bool(args.get("replace_all"))}]
+
+    def _compute(self, args, ctx):
+        path = ctx.resolve(require(args, "path"))
+        if not path.exists():
+            raise ToolError(f"File not found: {ctx.rel(path)}. Use write_file to create it.")
+        if not ctx.tracker.was_read(path):
+            raise ToolError(f"Read {ctx.rel(path)} with read_file before editing it.")
+        if not ctx.tracker.unchanged_since_read(path):
+            raise ToolError(f"{ctx.rel(path)} changed since you last read it. Read it again first.")
+        tf = load_text(path)
+        text = tf.text
+        total = 0
+        for i, e in enumerate(self.edits(args), start=1):
+            if not isinstance(e, dict):
+                raise ToolError(f"edit {i} must be an object.")
+            try:
+                text, n = apply_edit(text, e.get("old_string", ""), e.get("new_string", ""),
+                                     bool(e.get("replace_all")))
+            except ToolError as err:
+                prefix = f"Edit {i} failed: " if self.name == "multi_edit" else ""
+                raise ToolError(prefix + str(err) + (" No edits were applied." if self.name == "multi_edit" else ""))
+            total += n
+        return path, tf, text, total
+
+    def preview(self, args, ctx):
+        path, tf, text, _ = self._compute(args, ctx)
+        return make_diff(tf.text, text, ctx.rel(path))
+
+    def run(self, args, ctx):
+        path, tf, text, total = self._compute(args, ctx)
+        diff = make_diff(tf.text, text, ctx.rel(path))
+        save_text(path, TextFile(text, tf.bom))
+        ctx.tracker.mark_written(path)
+        added = sum(1 for ln in diff.splitlines() if ln.startswith("+") and not ln.startswith("+++"))
+        removed = sum(1 for ln in diff.splitlines() if ln.startswith("-") and not ln.startswith("---"))
+        return ToolResult(
+            f"Edited {ctx.rel(path)}: {total} replacement(s), +{added} -{removed} lines.\n"
+            + truncate(diff, 3000, "diff shortened"),
+            preview=f"+{added} -{removed} lines",
+        )
+
+
+class MultiEdit(EditFile):
+    name = "multi_edit"
+    description = (
+        "Apply several exact-string edits to ONE file in order, atomically: if any edit fails, none "
+        "are applied. Each edit sees the result of the previous one. Read the file first."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"},
+            "edits": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "old_string": {"type": "string"},
+                        "new_string": {"type": "string"},
+                        "replace_all": {"type": "boolean"},
+                    },
+                    "required": ["old_string", "new_string"],
+                },
+            },
+        },
+        "required": ["path", "edits"],
+    }
+
+    def edits(self, args):
+        edits = args.get("edits")
+        if not isinstance(edits, list) or not edits:
+            raise ToolError("`edits` must be a non-empty list.")
+        return edits
+
+    def describe(self, args, ctx):
+        n = len(args.get("edits") or [])
+        return f"{ctx.rel(ctx.resolve(args.get('path', '')))} ({n} edits)"
+
+
+# ---------------------------------------------------------------- list_dir
+
+class ListDir(Tool):
+    name = "list_dir"
+    read_only = True
+    description = "List a directory as a tree (directories end with /). Skips .git, node_modules, venvs and git-ignored files."
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Directory (default: project root)."},
+            "depth": {"type": "integer", "description": "How many levels to show, 1-4 (default 2)."},
+        },
+    }
+
+    def permission(self, args, ctx):
+        return Request("Read", self.name, paths=[ctx.resolve(args.get("path") or ".")])
+
+    def describe(self, args, ctx):
+        return ctx.rel(ctx.resolve(args.get("path") or ".")) or "."
+
+    def run(self, args, ctx):
+        base = ctx.resolve(args.get("path") or ".")
+        depth = max(1, min(opt_int(args, "depth", 2) or 2, 4))
+        if not base.exists():
+            raise ToolError(f"Directory not found: {base}")
+        if not base.is_dir():
+            raise ToolError(f"{base} is a file. Use read_file.")
+        gi = GitIgnore(ctx.root)
+        out: List[str] = []
+        limit = 400
+
+        def walk(d: Path, level: int) -> None:
+            try:
+                entries = sorted(d.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+            except OSError as e:
+                out.append("  " * level + f"[cannot list: {e}]")
+                return
+            for p in entries:
+                if len(out) >= limit:
+                    return
+                is_dir = p.is_dir()
+                try:
+                    rel = p.relative_to(ctx.root).as_posix()
+                except ValueError:
+                    rel = p.name
+                if is_dir and p.name in ALWAYS_SKIP_DIRS:
+                    out.append("  " * level + p.name + "/  (skipped)")
+                    continue
+                if gi.ignored(rel, is_dir):
+                    continue
+                out.append("  " * level + p.name + ("/" if is_dir else ""))
+                if is_dir and level + 1 < depth:
+                    walk(p, level + 1)
+
+        walk(base, 0)
+        if len(out) >= limit:
+            out.append(f"[... stopped at {limit} entries; list a subdirectory for more]")
+        body = "\n".join(out) if out else "(empty directory)"
+        return ToolResult(truncate(body, ctx.max_output_chars), preview=f"{len(out)} entries")

euron_code/tools/ignore.py

@@ -0,0 +1,75 @@
+"""Best-effort ignore rules for the Python fallbacks of glob/grep/list_dir."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path
+from typing import Iterator, List, Tuple
+
+ALWAYS_SKIP_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "__pycache__", ".venv", "venv", "env", ".tox",
+    ".mypy_cache", ".pytest_cache", ".ruff_cache", ".next", ".nuxt", "dist", "build",
+    ".idea", ".gradle", "target", ".cache", "coverage", ".turbo", ".parcel-cache",
+}
+
+
+class GitIgnore:
+    """A small subset of .gitignore: root .gitignore, simple globs, dir patterns, negation ignored."""
+
+    def __init__(self, root: Path):
+        self.root = root
+        self.patterns: List[Tuple[str, bool]] = []  # (pattern, dir_only)
+        try:
+            with open(root / ".gitignore", "r", encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#") or line.startswith("!"):
+                        continue
+                    dir_only = line.endswith("/")
+                    self.patterns.append((line.strip("/"), dir_only))
+        except OSError:
+            pass
+
+    def ignored(self, rel_posix: str, is_dir: bool) -> bool:
+        name = rel_posix.rsplit("/", 1)[-1]
+        for pat, dir_only in self.patterns:
+            if dir_only and not is_dir:
+                continue
+            if "/" in pat:
+                if fnmatch.fnmatch(rel_posix, pat.lstrip("/")) or fnmatch.fnmatch(rel_posix, pat.lstrip("/") + "/*"):
+                    return True
+            elif fnmatch.fnmatch(name, pat):
+                return True
+        return False
+
+
+def walk_files(base: Path, root: Path) -> Iterator[Path]:
+    gi = GitIgnore(root)
+    for dirpath, dirnames, filenames in os.walk(base):
+        dp = Path(dirpath)
+        keep = []
+        for d in dirnames:
+            if d in ALWAYS_SKIP_DIRS:
+                continue
+            try:
+                rel = (dp / d).relative_to(root).as_posix()
+            except ValueError:
+                rel = d
+            if gi.ignored(rel, True):
+                continue
+            keep.append(d)
+        dirnames[:] = sorted(keep)
+        for fn in sorted(filenames):
+            p = dp / fn
+            try:
+                rel = p.relative_to(root).as_posix()
+            except ValueError:
+                rel = fn
+            if gi.ignored(rel, False):
+                continue
+            yield p
+
+
+def is_binary_bytes(data: bytes) -> bool:
+    return b"\x00" in data[:8192]

euron_code/tools/search.py

@@ -0,0 +1,204 @@
+"""glob and grep. grep uses ripgrep when installed, else a Python fallback."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import List
+
+from euron_code.permissions import Request
+from euron_code.tools.base import Tool, ToolError, ToolResult, opt_int, require, truncate
+from euron_code.tools.ignore import is_binary_bytes, walk_files
+
+
+def ripgrep_path():
+    return shutil.which("rg")
+
+
+def _glob_match(rel: str, pattern: str) -> bool:
+    pat = pattern.replace("\\", "/")
+    if pat.startswith("./"):
+        pat = pat[2:]
+    if fnmatch.fnmatch(rel, pat):
+        return True
+    # `**/x` should also match `x` at the top level
+    if pat.startswith("**/") and fnmatch.fnmatch(rel, pat[3:]):
+        return True
+    # a pattern without a slash matches the basename anywhere (like `*.py`)
+    if "/" not in pat and fnmatch.fnmatch(rel.rsplit("/", 1)[-1], pat):
+        return True
+    return False
+
+
+class Glob(Tool):
+    name = "glob"
+    read_only = True
+    description = (
+        "Find files by glob pattern, e.g. `**/*.py` or `src/**/test_*.ts`. Results are relative paths, "
+        "newest first, skipping .git, node_modules, venvs and git-ignored files."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string"},
+            "path": {"type": "string", "description": "Directory to search in (default: project root)."},
+        },
+        "required": ["pattern"],
+    }
+
+    def permission(self, args, ctx):
+        return Request("Read", self.name, paths=[ctx.resolve(args.get("path") or ".")])
+
+    def describe(self, args, ctx):
+        return args.get("pattern", "")
+
+    def run(self, args, ctx):
+        pattern = require(args, "pattern")
+        base = ctx.resolve(args.get("path") or ".")
+        if not base.is_dir():
+            raise ToolError(f"Not a directory: {base}")
+        hits = []
+        for p in walk_files(base, ctx.root):
+            try:
+                rel = p.relative_to(base).as_posix()
+            except ValueError:
+                continue
+            if _glob_match(rel, pattern):
+                try:
+                    hits.append((p.stat().st_mtime, p))
+                except OSError:
+                    continue
+            if len(hits) > 5000:
+                break
+        hits.sort(key=lambda t: -t[0])
+        limit = 200
+        lines = [ctx.rel(p) for _, p in hits[:limit]]
+        if not lines:
+            return ToolResult(f"No files match {pattern!r}.", preview="0 files")
+        body = "\n".join(lines)
+        if len(hits) > limit:
+            body += f"\n[... {len(hits) - limit} more files; narrow the pattern]"
+        return ToolResult(truncate(body, ctx.max_output_chars), preview=f"{len(hits)} files")
+
+
+class Grep(Tool):
+    name = "grep"
+    read_only = True
+    description = (
+        "Search file contents with a regular expression. output_mode: `content` (matching lines with "
+        "file:line), `files_with_matches` (default), or `count`. Use `glob` (e.g. `*.py`) to filter files."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {"type": "string", "description": "Regular expression."},
+            "path": {"type": "string", "description": "File or directory (default: project root)."},
+            "glob": {"type": "string", "description": "Only search files matching this glob."},
+            "output_mode": {"type": "string", "enum": ["content", "files_with_matches", "count"]},
+            "ignore_case": {"type": "boolean"},
+            "context": {"type": "integer", "description": "Lines of context around matches (content mode)."},
+            "head_limit": {"type": "integer", "description": "Max lines of output (default 200)."},
+        },
+        "required": ["pattern"],
+    }
+
+    def permission(self, args, ctx):
+        return Request("Read", self.name, paths=[ctx.resolve(args.get("path") or ".")])
+
+    def describe(self, args, ctx):
+        s = repr(args.get("pattern", ""))
+        if args.get("glob"):
+            s += f" in {args['glob']}"
+        return s
+
+    def run(self, args, ctx):
+        pattern = require(args, "pattern")
+        base = ctx.resolve(args.get("path") or ".")
+        mode = args.get("output_mode") or "files_with_matches"
+        if mode not in ("content", "files_with_matches", "count"):
+            raise ToolError("output_mode must be content, files_with_matches or count.")
+        head = max(1, opt_int(args, "head_limit", 200) or 200)
+        context = max(0, min(opt_int(args, "context", 0) or 0, 10))
+        icase = bool(args.get("ignore_case"))
+        glob = args.get("glob")
+        if not base.exists():
+            raise ToolError(f"Path not found: {base}")
+        rg = ripgrep_path()
+        if rg and not ctx.settings.get("_forcePythonGrep"):
+            lines = self._rg(rg, pattern, base, ctx, mode, icase, glob, context)
+        else:
+            lines = self._py(pattern, base, ctx, mode, icase, glob, context)
+        if not lines:
+            return ToolResult(f"No matches for {pattern!r}.", preview="no matches")
+        total = len(lines)
+        body = "\n".join(lines[:head])
+        if total > head:
+            body += f"\n[... {total - head} more lines; refine the pattern or raise head_limit]"
+        return ToolResult(truncate(body, ctx.max_output_chars), preview=f"{total} result lines")
+
+    def _rg(self, rg, pattern, base, ctx, mode, icase, glob, context) -> List[str]:
+        cmd = [rg, "--color", "never", "--no-heading", "--no-messages"]
+        if icase:
+            cmd.append("-i")
+        if glob:
+            cmd += ["-g", glob]
+        if mode == "files_with_matches":
+            cmd.append("-l")
+        elif mode == "count":
+            cmd.append("-c")
+        else:
+            cmd.append("-n")
+            if context:
+                cmd += ["-C", str(context)]
+        target = ctx.rel(base)  # relative inside the project, absolute outside
+        cmd += ["-e", pattern, "--", target or "."]
+        try:
+            proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8",
+                                  errors="replace", timeout=60, cwd=str(ctx.root))
+        except subprocess.TimeoutExpired:
+            raise ToolError("grep timed out after 60 s; narrow the path or pattern.")
+        if proc.returncode not in (0, 1):
+            raise ToolError(f"ripgrep error: {proc.stderr.strip()[:500]}")
+        return proc.stdout.splitlines()
+
+    def _py(self, pattern, base, ctx, mode, icase, glob, context) -> List[str]:
+        try:
+            rx = re.compile(pattern, re.IGNORECASE if icase else 0)
+        except re.error as e:
+            raise ToolError(f"Invalid regular expression: {e}")
+        files = [base] if base.is_file() else list(walk_files(base, ctx.root))
+        out: List[str] = []
+        for p in files:
+            if glob and not _glob_match(p.name if "/" not in glob else ctx.rel(p), glob):
+                continue
+            try:
+                data = p.read_bytes()
+            except OSError:
+                continue
+            if len(data) > 5 * 1024 * 1024 or is_binary_bytes(data):
+                continue
+            text = data.decode("utf-8", errors="replace")
+            lines = text.splitlines()
+            idx = [i for i, ln in enumerate(lines) if rx.search(ln)]
+            if not idx:
+                continue
+            rel = ctx.rel(p)
+            if mode == "files_with_matches":
+                out.append(rel)
+            elif mode == "count":
+                out.append(f"{rel}:{len(idx)}")
+            else:
+                shown = set()
+                for i in idx:
+                    for j in range(max(0, i - context), min(len(lines), i + context + 1)):
+                        if j in shown:
+                            continue
+                        shown.add(j)
+                        sep = ":" if j == i or j in idx else "-"
+                        out.append(f"{rel}{sep}{j + 1}{sep}{lines[j][:500]}")
+            if len(out) > 5000:
+                break
+        return out