turnloop 0.1.0__py3-none-any.whl

turnloop/tools/edit.py

@@ -0,0 +1,238 @@
+"""Edit — exact-string replacement, applied atomically.
+
+One tool with a list of edits rather than separate Edit and MultiEdit. Two
+near-identical tool descriptions is a real cost on a 65k-token window, and the
+single-element list is barely more typing for the model.
+
+The behavior that earns its keep: edits are applied to an in-memory copy and the
+file is written once, so a batch either lands completely or not at all. A partial
+batch leaves a file in a state neither the model nor the user predicted, which is
+much worse than a clean error.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+from pydantic import BaseModel, Field
+
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+from turnloop.tools.textio import (
+    detect_newline,
+    has_bom,
+    preserve_trailing_newline,
+    read_text,
+    write_text,
+)
+
+
+class EditOp(BaseModel):
+    old_string: str = Field(description="Exact text to find, including indentation.")
+    new_string: str = Field(description="Replacement text. Empty string deletes.")
+    replace_all: bool = Field(
+        default=False, description="Replace every occurrence instead of requiring uniqueness."
+    )
+
+
+class EditArgs(BaseModel):
+    file_path: str = Field(description="Absolute or project-relative path to edit.")
+    edits: list[EditOp] = Field(
+        description="Edits applied in order. Use one element for a single change."
+    )
+
+
+class EditTool(Tool):
+    name = "Edit"
+    Args = EditArgs
+    read_only = False
+    parallel_safe = False
+
+    descriptions = {
+        "terse": """
+Replace exact strings in a file. `edits` is a list of {old_string, new_string}.
+Read the file first. `old_string` must be unique unless replace_all.
+All edits apply together or none do.
+""",
+        "normal": """
+Edit a file by exact string replacement.
+
+- Read the file first. Edits are rejected if the file was never read, or if it
+  changed on disk since.
+- `old_string` must match the file exactly, including indentation and line
+  breaks. Copy it from Read output, minus the line-number prefix.
+- `old_string` must be unique in the file, otherwise the edit is rejected with a
+  count — add surrounding context to disambiguate, or set `replace_all`.
+- Pass several edits in one call to make a coherent change. They are applied in
+  order against the file, and written atomically: if any edit fails, none are
+  applied.
+- To delete text, use an empty `new_string`.
+""",
+        "verbose": """
+Edit a file by exact string replacement.
+
+Arguments:
+- `file_path`: absolute, or relative to the working directory.
+- `edits`: a list of `{old_string, new_string, replace_all}`. One element is the
+  common case; several are applied in order.
+
+Matching rules:
+- `old_string` must match the file byte-for-byte, including leading whitespace.
+  When copying from Read output, strip the line-number prefix (the number and the
+  following tab) — including it is the most common cause of a failed edit.
+- `old_string` must appear exactly once. If it appears more than once the edit is
+  rejected and the match count is reported; extend `old_string` with surrounding
+  lines to make it unique, or set `replace_all: true` when every occurrence
+  really should change (renaming a local variable, for example).
+- `old_string` and `new_string` must differ.
+- An empty `new_string` deletes the matched text.
+
+Application semantics:
+- Edits apply sequentially to an in-memory copy, so a later edit can match text a
+  previous edit introduced.
+- The write is atomic across the batch: if any edit fails to match, the file is
+  left untouched and an error explains which edit failed. A half-applied batch
+  would leave the file in a state neither of us intended.
+- The file's newline style and trailing-newline convention are preserved, so a
+  one-line change does not produce a whole-file diff on a CRLF checkout.
+""",
+    }
+
+    async def run(self, args: EditArgs, ctx: ToolContext) -> ToolOutput:
+        path = ctx.resolve(args.file_path)
+
+        if ctx.readonly:
+            return ToolOutput.error("plan mode is read-only; Edit is not available")
+        if not args.edits:
+            return ToolOutput.error("no edits supplied")
+        if not ctx.within_allowed(path):
+            return ToolOutput.error(f"{path} is outside the project root ({ctx.root}).")
+        if not path.exists():
+            return ToolOutput.error(f"{path} does not exist. Use Write to create it.")
+        if not ctx.files.has_read(path):
+            return ToolOutput.error(
+                f"{path} has not been read in this session. Read it first — editing text you "
+                "have not seen is how unintended changes happen."
+            )
+        if ctx.files.is_stale(path):
+            return ToolOutput.error(
+                f"{path} changed on disk since you read it. Read it again, then retry."
+            )
+
+        original = read_text(path)
+        updated = original
+        applied: list[tuple[EditOp, int]] = []
+
+        for index, op in enumerate(args.edits):
+            if op.old_string == op.new_string:
+                return ToolOutput.error(
+                    f"edit {index + 1}: old_string and new_string are identical"
+                )
+            if not op.old_string:
+                return ToolOutput.error(
+                    f"edit {index + 1}: old_string is empty. Use Write to create content."
+                )
+
+            count = updated.count(op.old_string)
+            if count == 0:
+                return ToolOutput.error(_no_match_message(index, op, updated))
+            if count > 1 and not op.replace_all:
+                return ToolOutput.error(
+                    f"edit {index + 1}: old_string appears {count} times. Add surrounding "
+                    f"context to make it unique, or set replace_all: true.\n"
+                    f"{_occurrence_context(updated, op.old_string)}"
+                )
+
+            updated = (
+                updated.replace(op.old_string, op.new_string)
+                if op.replace_all
+                else updated.replace(op.old_string, op.new_string, 1)
+            )
+            applied.append((op, count))
+
+        if updated == original:
+            return ToolOutput.error("edits produced no change")
+
+        updated = preserve_trailing_newline(original, updated)
+        write_text(path, updated, newline=detect_newline(path), bom=has_bom(path))
+        ctx.files.record_write(path, updated)
+
+        diff = _unified_diff(original, updated, path.name)
+        replaced = sum(c if op.replace_all else 1 for op, c in applied)
+        return ToolOutput(
+            content=(
+                f"Applied {len(applied)} edit(s) to {path} "
+                f"({replaced} replacement(s)).\n\n{_diff_for_model(diff)}"
+            ),
+            display=diff,
+            metrics={"edits": len(applied), "replacements": replaced},
+        )
+
+    def summary(self, args: EditArgs) -> str:  # type: ignore[override]
+        n = len(args.edits)
+        return f"Edit {args.file_path}" + (f" ({n} edits)" if n > 1 else "")
+
+
+def _no_match_message(index: int, op: EditOp, content: str) -> str:
+    """Explain a failed match usefully.
+
+    Blank whitespace mismatches account for most failures, so name that
+    explicitly rather than making the model guess at re-reading the file.
+    """
+    stripped = op.old_string.strip()
+    hint = ""
+    if stripped and stripped in content:
+        hint = (
+            " The text exists but with different surrounding whitespace — copy the exact "
+            "indentation from Read output."
+        )
+    else:
+        first_line = op.old_string.splitlines()[0].strip() if op.old_string.strip() else ""
+        if first_line and first_line in content:
+            hint = (
+                f" Its first line ({first_line[:60]!r}) is present, so the later lines differ. "
+                "Re-read the file and copy the current text."
+            )
+        else:
+            candidates = difflib.get_close_matches(
+                op.old_string.splitlines()[0] if op.old_string.splitlines() else op.old_string,
+                content.splitlines(),
+                n=2,
+                cutoff=0.7,
+            )
+            if candidates:
+                hint = " Closest lines in the file: " + " | ".join(c.strip()[:70] for c in candidates)
+    return f"edit {index + 1}: old_string not found in the file.{hint}"
+
+
+def _occurrence_context(content: str, needle: str, limit: int = 3) -> str:
+    lines = content.splitlines()
+    first_needle_line = needle.splitlines()[0] if needle.splitlines() else needle
+    hits = [i + 1 for i, line in enumerate(lines) if first_needle_line in line][:limit]
+    if not hits:
+        return ""
+    return "Occurrences near lines: " + ", ".join(str(h) for h in hits)
+
+
+def _unified_diff(before: str, after: str, name: str) -> str:
+    diff = difflib.unified_diff(
+        before.splitlines(keepends=False),
+        after.splitlines(keepends=False),
+        fromfile=f"a/{name}",
+        tofile=f"b/{name}",
+        n=3,
+        lineterm="",
+    )
+    return "\n".join(diff)
+
+
+def _diff_for_model(diff: str, max_lines: int = 80) -> str:
+    """Send the model a bounded diff.
+
+    It needs confirmation of what changed, not the whole patch — a 400-line diff
+    echoed back into context is pure waste when the file is one Read away.
+    """
+    lines = diff.splitlines()
+    if len(lines) <= max_lines:
+        return diff
+    head = lines[:max_lines]
+    return "\n".join(head) + f"\n... [{len(lines) - max_lines} more diff lines]"

turnloop/tools/glob.py

@@ -0,0 +1,235 @@
+"""Glob — find files by name pattern.
+
+Ignore handling delegates to `git ls-files` when the project is a repository.
+Reimplementing .gitignore semantics (negations, directory-only patterns, nested
+ignore files, precedence) is a genuinely hard problem that git has already
+solved; falling back to a hardcoded skip list only when git is unavailable is
+strictly better than getting it subtly wrong everywhere.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from turnloop.permissions.rules import _glob_to_regex
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+
+MAX_RESULTS = 200
+
+ALWAYS_SKIP = {
+    ".git", "node_modules", "__pycache__", ".venv", "venv", ".mypy_cache",
+    ".pytest_cache", ".ruff_cache", "dist", "build", ".next", "target",
+    ".turnloop", ".idea", ".gradle", "vendor",
+}
+
+
+class GlobArgs(BaseModel):
+    pattern: str = Field(description="Glob pattern, e.g. '**/*.py' or 'src/**/test_*.py'.")
+    path: str | None = Field(default=None, description="Directory to search in. Defaults to cwd.")
+    limit: int | None = Field(default=None, description=f"Max results (default {MAX_RESULTS}).")
+
+
+class GlobTool(Tool):
+    name = "Glob"
+    Args = GlobArgs
+    read_only = True
+    parallel_safe = True
+
+    descriptions = {
+        "terse": """
+Find files by glob pattern (`**/*.py`). Returns paths, newest first.
+Ignored files (.git, node_modules, build output) are skipped.
+""",
+        "normal": """
+Find files by name pattern.
+
+- `pattern` supports `**` (any depth) and `*` (one path segment).
+- Results are sorted by modification time, newest first — recently touched files
+  are usually the relevant ones.
+- Files ignored by the repository's .gitignore are excluded, as are build and
+  dependency directories.
+- Use this to locate files by name. Use Grep to search their contents.
+""",
+        "verbose": """
+Find files by name pattern.
+
+Arguments:
+- `pattern`: a glob. `**` matches any number of directories, `*` matches within
+  one path segment, `?` matches one character. Examples: `**/*.ts`,
+  `src/**/test_*.py`, `*.md`.
+- `path`: directory to search under. Defaults to the working directory.
+- `limit`: maximum results, default 200.
+
+Behavior:
+- Results are ordered by modification time, newest first, on the theory that the
+  file you want is one somebody touched recently.
+- When the project is a git repository, .gitignore is honored by asking git
+  itself, so the ignore semantics match what the user sees. Otherwise a fixed
+  skip list is used (.git, node_modules, __pycache__, .venv, dist, build,
+  target, .next, vendor).
+- Output is truncated at the limit with an explicit note. If you hit it, narrow
+  the pattern rather than raising the limit — a 200-path list is already more
+  than a turn should spend context on.
+- This searches names only. To search file contents, use Grep.
+""",
+    }
+
+    async def run(self, args: GlobArgs, ctx: ToolContext) -> ToolOutput:
+        base = ctx.resolve(args.path) if args.path else ctx.cwd
+        if not base.is_dir():
+            return ToolOutput.error(f"{base} is not a directory")
+        if not ctx.within_allowed(base):
+            return ToolOutput.error(f"{base} is outside the project root ({ctx.root}).")
+
+        limit = args.limit or MAX_RESULTS
+        started = time.monotonic()
+
+        tracked = _git_tracked(base)
+        if tracked is not None:
+            matches = _match_against(tracked, args.pattern, base)
+        else:
+            matches = _walk_match(base, args.pattern)
+
+        matches.sort(key=lambda p: _mtime(p), reverse=True)
+        total = len(matches)
+        shown = matches[:limit]
+
+        if not shown:
+            return ToolOutput(
+                content=f"No files match {args.pattern!r} under {base}.",
+                metrics={"matches": 0, "elapsed_s": time.monotonic() - started},
+            )
+
+        rel = [_rel(p, ctx.cwd) for p in shown]
+        body = "\n".join(rel)
+        if total > limit:
+            body += f"\n\n[{total - limit} more matches not shown; narrow the pattern]"
+
+        return ToolOutput(
+            content=body,
+            display=f"Glob {args.pattern} → {total} file(s)",
+            metrics={"matches": total, "shown": len(shown), "used_git": tracked is not None},
+        )
+
+    def summary(self, args: GlobArgs) -> str:  # type: ignore[override]
+        return f"Glob {args.pattern}"
+
+
+def _git_tracked(base: Path) -> list[Path] | None:
+    """Files git knows about, honoring .gitignore. None if not a repo.
+
+    Also None if `base` itself is inside a git-ignored tree: `git ls-files`
+    never descends into an ignored directory, so it reports zero entries there
+    regardless of what actually exists on disk. Treating that the same as "not
+    a repo" (i.e. falling back to `_walk_match`) is deliberate — the caller
+    can't tell "nothing here" from "git refuses to look here" any other way,
+    and the alternative (trusting an empty result) is exactly the bug this
+    exists to avoid: Glob silently reporting no matches for a directory full
+    of real files just because some ancestor is .gitignore'd.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "ls-files", "--cached", "--others", "--exclude-standard"],
+            cwd=base,
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if proc.returncode != 0:
+        return None
+    out: list[Path] = []
+    for line in proc.stdout.splitlines():
+        if not line.strip():
+            continue
+        p = base / line
+        if p.is_file():
+            out.append(p)
+    if not out and _is_ignored(base):
+        return None
+    return out
+
+
+def _is_ignored(path: Path) -> bool:
+    """Whether git itself would refuse to track `path`.
+
+    Checked explicitly (rather than just "ls-files came back empty") because an
+    empty result also happens for a genuinely empty, non-ignored directory —
+    conflating the two would make Glob walk the filesystem and include files
+    that a normal, non-ignored empty directory would never have had, but worse,
+    it would also change nothing for the real failure mode this guards against.
+    The check is cheap and only runs on the already-rare empty-result path.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "check-ignore", "-q", str(path)],
+            cwd=path,
+            capture_output=True,
+            timeout=20,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return proc.returncode == 0
+
+
+def _match_against(paths: list[Path], pattern: str, base: Path) -> list[Path]:
+    import re
+
+    regex = re.compile(_glob_to_regex(_normalize_pattern(pattern)))
+    out = []
+    for p in paths:
+        try:
+            rel = p.relative_to(base).as_posix()
+        except ValueError:
+            continue
+        if regex.fullmatch(rel):
+            out.append(p)
+    return out
+
+
+def _walk_match(base: Path, pattern: str) -> list[Path]:
+    import os
+    import re
+
+    regex = re.compile(_glob_to_regex(_normalize_pattern(pattern)))
+    out: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(base):
+        dirnames[:] = [d for d in dirnames if d not in ALWAYS_SKIP and not d.startswith(".git")]
+        for name in filenames:
+            full = Path(dirpath) / name
+            rel = full.relative_to(base).as_posix()
+            if regex.fullmatch(rel):
+                out.append(full)
+    return out
+
+
+def _normalize_pattern(pattern: str) -> str:
+    """Make a bare pattern behave the way people expect.
+
+    `*.py` almost always means "python files anywhere here", not "python files in
+    exactly this directory". Anchoring it strictly produces empty results and a
+    confused model, so a leading `**/` is implied for patterns with no separator.
+    """
+    p = pattern.replace("\\", "/").lstrip("./")
+    if "/" not in p:
+        return f"**/{p}"
+    return p
+
+
+def _mtime(path: Path) -> float:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return 0.0
+
+
+def _rel(path: Path, base: Path) -> str:
+    try:
+        return path.resolve().relative_to(base.resolve()).as_posix()
+    except ValueError:
+        return str(path)