localgate 0.7.0__py3-none-any.whl

localgate/agent/render.py

@@ -0,0 +1,64 @@
+"""Terminal rendering for the coding agent: colored diffs and status lines.
+
+Kept separate from `cli.py` so the line-classification logic (`diff_lines`) is
+testable without a terminal — golden-file tests assert on the returned
+``(text, style)`` pairs directly rather than parsing captured ANSI output.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+from rich.console import Console
+from rich.syntax import Syntax
+from rich.text import Text
+
+_STYLE_FOR_PREFIX = (
+    ("+++", "dim"),
+    ("---", "dim"),
+    ("@@", "cyan"),
+    ("+", "green"),
+    ("-", "red"),
+)
+
+
+def diff_lines(path: str, old_content: str, new_content: str) -> list[tuple[str, str]]:
+    """A unified diff between ``old_content`` and ``new_content``, one (line, style) pair
+    per line. ``old_content`` of ``""`` renders as an all-additions diff, which is
+    exactly right for a brand-new file.
+    """
+    diff = difflib.unified_diff(
+        old_content.splitlines(keepends=True),
+        new_content.splitlines(keepends=True),
+        fromfile=path,
+        tofile=path,
+    )
+    lines: list[tuple[str, str]] = []
+    for raw in diff:
+        line = raw.rstrip("\n")
+        style = "default"
+        for prefix, prefix_style in _STYLE_FOR_PREFIX:
+            if line.startswith(prefix):
+                style = prefix_style
+                break
+        lines.append((line, style))
+    return lines
+
+
+def print_diff(console: Console, path: str, old_content: str, new_content: str) -> None:
+    """Render a colored unified diff for a pending write, or the new file's
+    contents with syntax highlighting when there's nothing to diff against.
+    """
+    if not old_content:
+        console.print(f"[dim]--- new file {path} ---[/dim]")
+        console.print(Syntax(new_content, _lexer_for(path), theme="ansi_dark", line_numbers=True))
+        return
+    console.rule(f"[bold]{path}[/bold]")
+    for line, style in diff_lines(path, old_content, new_content):
+        console.print(Text(line, style=style))
+    console.rule()
+
+
+def _lexer_for(path: str) -> str:
+    suffix = path.rsplit(".", 1)[-1] if "." in path else ""
+    return suffix or "text"

localgate/agent/repl.py

@@ -0,0 +1,238 @@
+"""Interactive REPL for `localgate code`, and the write-safety plumbing it shares
+with the single-shot invocation: a dirty-tree gate, colored diffs before every
+write, a spinner while waiting on the model, and `/undo`.
+
+Kept out of `cli.py` because none of this is Typer-specific — it is pure asyncio
+and Rich, and is exercised directly in tests without going through the CLI layer.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from localgate.agent import gitutil
+from localgate.agent.loop import AgentSession, AgentTurnLimitExceeded
+from localgate.agent.memory import AgentMemory
+from localgate.agent.render import print_diff
+from localgate.agent.tools import ToolCallResult, execute_tool_call
+
+HELP_TEXT = "[dim]/exit  /clear  /model <name>  /undo[/dim]"
+
+
+class WriteGate:
+    """Confirms writes with a diff, gates once on a dirty tree, and tracks what
+    changed so `/undo` and `--auto-commit` have something to act on.
+    """
+
+    def __init__(
+        self,
+        console: Console,
+        root: Path,
+        *,
+        auto_approve: bool = False,
+        force: bool = False,
+        auto_commit: bool = False,
+    ) -> None:
+        self.console = console
+        self.root = root
+        self.auto_approve = auto_approve
+        self.force = force
+        self.auto_commit = auto_commit
+        self.is_repo = gitutil.is_repo(root)
+        self._dirty_checked = False
+        self.last_written_path: str | None = None
+        self.writes_this_turn: list[str] = []
+
+    def _dirty_tree_ok(self) -> bool:
+        """Warn about a dirty tree once per session; the user opts back in or bails."""
+        if self._dirty_checked or not self.is_repo:
+            self._dirty_checked = True
+            return True
+        self._dirty_checked = True
+        if self.force or not gitutil.is_dirty(self.root):
+            return True
+        self.console.print(
+            "[yellow]! uncommitted changes exist in this project — agent writes may be "
+            "hard to distinguish from your own edits.[/yellow]"
+        )
+        return typer.confirm("Continue anyway?", default=False)
+
+    def confirm_write(self, path: str, content: str) -> bool:
+        if not self._dirty_tree_ok():
+            return False
+
+        target = self.root / path
+        old_content = ""
+        if target.is_file():
+            try:
+                old_content = target.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                old_content = ""
+        print_diff(self.console, path, old_content, content)
+
+        if self.auto_approve:
+            return True
+        return typer.confirm(f"Write {path}?", default=False)
+
+    def tracking_executor(
+        self, root: Path, tool_call_id: str, name: str, arguments: dict[str, Any]
+    ) -> ToolCallResult:
+        """Wraps the default tool executor to record successful writes."""
+        result = execute_tool_call(root, tool_call_id, name, arguments)
+        if name == "write_file" and not result.is_error:
+            path = arguments.get("path", "?")
+            self.last_written_path = path
+            self.writes_this_turn.append(path)
+        return result
+
+    def after_turn(self, summary: str) -> None:
+        """Auto-commit whatever was written this turn, if that's enabled."""
+        if self.auto_commit and self.is_repo and self.writes_this_turn:
+            message = f"{gitutil.AGENT_COMMIT_PREFIX} {summary[:60]}"
+            gitutil.commit_all(self.root, message)
+        self.writes_this_turn = []
+
+    def undo(self) -> str:
+        if not self.is_repo:
+            return "Not a git repository — nothing to undo automatically."
+        if self.auto_commit:
+            message = gitutil.last_commit_message(self.root)
+            if message is None or not message.startswith(gitutil.AGENT_COMMIT_PREFIX):
+                return "The last commit wasn't made by the agent — refusing to reset it."
+            gitutil.reset_hard_last(self.root)
+            return f"Reset the last agent commit: {message}"
+        if self.last_written_path is None:
+            return "Nothing written yet this session to undo."
+        outcome = gitutil.undo_file(self.root, self.last_written_path)
+        self.last_written_path = None
+        return outcome
+
+
+async def run_turn(
+    console: Console,
+    session: AgentSession,
+    gate: WriteGate,
+    user_input: str,
+    memory: AgentMemory | None = None,
+) -> str:
+    """Run one turn with a spinner that clears the moment the model produces
+    anything — streamed text or a tool-call event — auto-commit afterward, and
+    record the turn into conversation history/memory if a session is attached.
+    """
+    status = console.status("[dim]thinking...[/dim]", spinner="dots")
+    status.start()
+    stopped = False
+
+    def stop() -> None:
+        nonlocal stopped
+        if not stopped:
+            status.stop()
+            stopped = True
+
+    def on_token(text: str) -> None:
+        stop()
+        console.print(text, end="")
+
+    def on_event(line: str) -> None:
+        stop()
+        console.print(f"[cyan]  {line}[/cyan]")
+
+    session.on_token = on_token
+    session.on_event = on_event
+    if memory is not None:
+        session.augment = memory.augment
+    try:
+        result = await session.send(user_input)
+    finally:
+        stop()
+
+    gate.after_turn(user_input)
+    console.print()
+    if memory is not None:
+        await memory.record_turn(user_input, result)
+    return result
+
+
+async def run_repl(
+    backend: Any,
+    model: str,
+    root: Path,
+    *,
+    auto_approve: bool = False,
+    force: bool = False,
+    auto_commit: bool = False,
+    memory: AgentMemory | None = None,
+) -> None:
+    """A persistent chat session in `root`, until `/exit` or EOF (Ctrl+D)."""
+    console = Console()
+    gate = WriteGate(console, root, auto_approve=auto_approve, force=force, auto_commit=auto_commit)
+    session = AgentSession(
+        backend, model, root, confirm_write=gate.confirm_write, tool_executor=gate.tracking_executor
+    )
+
+    console.print(f"[bold]localgate code[/bold] — {root}")
+    console.print(HELP_TEXT)
+    console.print()
+
+    while True:
+        try:
+            line = console.input("[bold green]> [/bold green]")
+        except EOFError:
+            console.print()
+            break
+        line = line.strip()
+        if not line:
+            continue
+
+        if line == "/exit":
+            break
+        if line == "/clear":
+            session.reset()
+            gate.writes_this_turn = []
+            console.print("[dim]conversation cleared[/dim]")
+            continue
+        if line.startswith("/model"):
+            parts = line.split(maxsplit=1)
+            if len(parts) == 2:
+                session.model = parts[1].strip()
+                console.print(f"[dim]model set to {session.model}[/dim]")
+            else:
+                console.print(f"[dim]current model: {session.model}[/dim]")
+            continue
+        if line == "/undo":
+            console.print(f"[yellow]{gate.undo()}[/yellow]")
+            continue
+        if line.startswith("/"):
+            console.print(f"[dim]unknown command {line!r} — {HELP_TEXT}[/dim]")
+            continue
+
+        try:
+            await run_turn(console, session, gate, line, memory=memory)
+        except AgentTurnLimitExceeded as exc:
+            console.print(f"[red]{exc}[/red]")
+        except KeyboardInterrupt:
+            console.print("\n[yellow]cancelled — session still open[/yellow]")
+
+
+async def run_single_shot(
+    backend: Any,
+    model: str,
+    root: Path,
+    task: str,
+    *,
+    auto_approve: bool = False,
+    force: bool = False,
+    auto_commit: bool = False,
+    memory: AgentMemory | None = None,
+) -> str:
+    """One task, one turn, with the same diff/spinner/streaming UI as the REPL."""
+    console = Console()
+    gate = WriteGate(console, root, auto_approve=auto_approve, force=force, auto_commit=auto_commit)
+    session = AgentSession(
+        backend, model, root, confirm_write=gate.confirm_write, tool_executor=gate.tracking_executor
+    )
+    return await run_turn(console, session, gate, task, memory=memory)

localgate/agent/tools.py

@@ -0,0 +1,292 @@
+"""Tools available to the coding agent: filesystem access, a project-wide search,
+and read-only git awareness.
+
+Every tool is confined to a single project root. The model only ever sees paths
+relative to that root, and every path is resolved and checked against it before
+any filesystem operation runs — a `../../etc/passwd` or an absolute path from the
+model is rejected rather than followed. Paths matching `.gitignore` or
+`.localgateignore` are invisible to every tool too, layered on top of that same
+check, so secrets and generated directories stay out of the model's reach even if
+it asks by name. This is the one piece of this module that must not have a bug:
+it's the entire difference between "the agent edits your project" and "the agent
+edits your filesystem."
+
+There is deliberately no `run_command`/shell-execution tool. That's the single
+riskiest capability a coding agent can have, and CODING_AGENT_PLAN.md calls for
+adding it — if ever — behind mandatory per-call confirmation and a real sandbox,
+not as a peer to these four read/write tools.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from localgate.agent import gitutil
+from localgate.agent.ignore import is_ignored, load_patterns
+
+#: OpenAI-style tool definitions, passed as `tools` on the chat completions request.
+TOOL_SCHEMAS: list[dict[str, Any]] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read the full contents of a text file in the project.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path relative to the project root, e.g. 'src/app.py'.",
+                    }
+                },
+                "required": ["path"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": (
+                "Create or overwrite a text file in the project with the given content. "
+                "Always read the file first if it already exists, so the write is an "
+                "intentional full replacement rather than a guess."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path relative to the project root.",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "The complete new contents of the file.",
+                    },
+                },
+                "required": ["path", "content"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_directory",
+            "description": "List files and subdirectories at a path in the project.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path relative to the project root. Defaults to '.'.",
+                    }
+                },
+                "required": [],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "search_files",
+            "description": (
+                "Search file contents in the project for a regular expression, like grep. "
+                "Returns matching lines as 'path:line: text'. Use this to find relevant code "
+                "without already knowing the exact filename."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string", "description": "A regular expression."},
+                    "path": {
+                        "type": "string",
+                        "description": (
+                            "Directory to search under, relative to the project root. "
+                            "Defaults to '.'."
+                        ),
+                    },
+                },
+                "required": ["pattern"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "git_status",
+            "description": "Show which files are modified, staged, or untracked — read-only.",
+            "parameters": {"type": "object", "properties": {}},
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "git_diff",
+            "description": "Show unstaged changes, optionally limited to one file — read-only.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Limit the diff to this file, relative to the project root.",
+                    }
+                },
+                "required": [],
+            },
+        },
+    },
+]
+
+TOOL_NAMES = frozenset(schema["function"]["name"] for schema in TOOL_SCHEMAS)
+
+
+class PathEscapeError(ValueError):
+    """Raised when a tool argument would resolve outside the project root."""
+
+
+class IgnoredPathError(ValueError):
+    """Raised when a tool argument matches .gitignore/.localgateignore."""
+
+
+def resolve_within(root: Path, relative: str) -> Path:
+    """Resolve ``relative`` against ``root`` and refuse anything that escapes it.
+
+    Handles both `../` traversal and absolute paths (which `Path.__truediv__`
+    would otherwise happily accept, silently discarding ``root``).
+    """
+    root = root.resolve()
+    candidate = (root / relative).resolve()
+    with contextlib.suppress(ValueError):
+        candidate.relative_to(root)
+        return candidate
+    raise PathEscapeError(f"{relative!r} resolves outside the project root ({root})")
+
+
+def ensure_visible(root: Path, candidate: Path) -> None:
+    """Refuse a path excluded by `.gitignore`/`.localgateignore` (or inside `.git`)."""
+    if is_ignored(root, candidate, load_patterns(root)):
+        relative = candidate.relative_to(root.resolve())
+        raise IgnoredPathError(f"{relative} is excluded by .gitignore/.localgateignore")
+
+
+def read_file(root: Path, path: str) -> str:
+    target = resolve_within(root, path)
+    ensure_visible(root, target)
+    if not target.is_file():
+        raise FileNotFoundError(f"No such file: {path}")
+    return target.read_text(encoding="utf-8", errors="replace")
+
+
+def write_file(root: Path, path: str, content: str) -> None:
+    target = resolve_within(root, path)
+    ensure_visible(root, target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+
+
+def list_directory(root: Path, path: str = ".") -> list[str]:
+    target = resolve_within(root, path)
+    ensure_visible(root, target)
+    if not target.is_dir():
+        raise NotADirectoryError(f"Not a directory: {path}")
+    root = root.resolve()
+    patterns = load_patterns(root)
+    entries = sorted(target.iterdir(), key=lambda p: (p.is_file(), p.name))
+    return [
+        f"{entry.name}/" if entry.is_dir() else entry.name
+        for entry in entries
+        if not is_ignored(root, entry, patterns)
+    ]
+
+
+def search_files(root: Path, pattern: str, path: str = ".", max_results: int = 200) -> list[str]:
+    """Grep-like content search under ``path``, skipping ignored and binary files."""
+    start = resolve_within(root, path)
+    ensure_visible(root, start)
+    if not start.is_dir():
+        raise NotADirectoryError(f"Not a directory: {path}")
+
+    root = root.resolve()
+    patterns = load_patterns(root)
+    regex = re.compile(pattern)
+    results: list[str] = []
+
+    for file_path in sorted(start.rglob("*")):
+        if not file_path.is_file() or is_ignored(root, file_path, patterns):
+            continue
+        try:
+            raw = file_path.read_bytes()
+        except OSError:
+            continue
+        if b"\0" in raw:
+            continue  # a NUL byte is the cheap, standard heuristic for "this is binary"
+        try:
+            text = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+        relative = file_path.relative_to(root).as_posix()
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            if regex.search(line):
+                results.append(f"{relative}:{lineno}: {line.strip()}")
+                if len(results) >= max_results:
+                    return results
+    return results
+
+
+def git_status(root: Path) -> str:
+    if not gitutil.is_repo(root):
+        return "Not a git repository."
+    return gitutil.status(root) or "Working tree clean."
+
+
+def git_diff(root: Path, path: str | None = None) -> str:
+    if not gitutil.is_repo(root):
+        return "Not a git repository."
+    if path is not None:
+        ensure_visible(root, resolve_within(root, path))
+    return gitutil.diff(root, path) or "No changes."
+
+
+@dataclass(frozen=True)
+class ToolCallResult:
+    """The outcome of executing one tool call, ready to feed back to the model."""
+
+    tool_call_id: str
+    name: str
+    content: str
+    is_error: bool = False
+
+
+def execute_tool_call(
+    root: Path, tool_call_id: str, name: str, arguments: dict[str, Any]
+) -> ToolCallResult:
+    """Run one tool call and turn any failure into a result the model can react to.
+
+    A tool that raises would kill the whole agent loop over something as mundane
+    as a typo'd filename; the model should see "No such file: foo.py" as a tool
+    result and try again, not crash the CLI.
+    """
+    try:
+        if name == "read_file":
+            content = read_file(root, arguments["path"])
+        elif name == "write_file":
+            write_file(root, arguments["path"], arguments["content"])
+            content = f"Wrote {len(arguments['content'])} bytes to {arguments['path']}"
+        elif name == "list_directory":
+            content = "\n".join(list_directory(root, arguments.get("path", ".")))
+        elif name == "search_files":
+            matches = search_files(root, arguments["pattern"], arguments.get("path", "."))
+            content = "\n".join(matches) if matches else "No matches."
+        elif name == "git_status":
+            content = git_status(root)
+        elif name == "git_diff":
+            content = git_diff(root, arguments.get("path"))
+        else:
+            return ToolCallResult(tool_call_id, name, f"Unknown tool: {name}", is_error=True)
+    except Exception as exc:  # noqa: BLE001 — any failure becomes a tool-result the model reads
+        return ToolCallResult(tool_call_id, name, f"{type(exc).__name__}: {exc}", is_error=True)
+    return ToolCallResult(tool_call_id, name, content)