kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/tools/list_dir.py

@@ -0,0 +1,67 @@
+"""list_dir tool: list the entries of a directory in the workspace."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import (
+    PathError,
+    get_workspace_ignore,
+    resolve_for_read,
+)
+
+MAX_ENTRIES = 500
+
+
+def _list_dir(args: dict[str, Any], session: Session) -> ToolResult:
+    path = str(args.get("path", ".") or ".")
+    try:
+        resolved = resolve_for_read(
+            path,
+            session.workspace_root,
+            trusted=bool(getattr(session, "trusted_workspace", False)),
+        )
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+
+    if not resolved.exists():
+        return ToolResult.error(f"Directory not found: {path}")
+    if not resolved.is_dir():
+        return ToolResult.error(f"'{path}' is not a directory, use read_file")
+
+    ignore = get_workspace_ignore(session.workspace_root)
+    entries: list[str] = []
+    for child in sorted(resolved.iterdir(), key=lambda p: (p.is_file(), p.name)):
+        is_dir = child.is_dir()
+        if ignore.is_ignored(child, is_dir=is_dir):
+            continue
+        suffix = "/" if is_dir else ""
+        entries.append(child.name + suffix)
+        if len(entries) >= MAX_ENTRIES:
+            entries.append(f"... [truncated at {MAX_ENTRIES} entries]")
+            break
+
+    if not entries:
+        return ToolResult(content="[empty directory]")
+    return ToolResult(content="\n".join(entries))
+
+
+list_dir_tool = FunctionTool(
+    name="list_dir",
+    description="List the files and subdirectories of a directory in the workspace.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": (
+                    "Directory path relative to the workspace root. "
+                    + "Defaults to the workspace root."
+                ),
+            },
+        },
+    },
+    func=_list_dir,
+)

kiwimatecoder/tools/lsp.py

@@ -0,0 +1,254 @@
+"""Read-only LSP tools: diagnostics, definitions, and references.
+
+These tools never mutate the workspace (``writes=False, runs=False``). They
+report a clear error when LSP is disabled or no configured server matches the
+file, and they never start a server under an extension the presets/overrides do
+not claim.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from kiwimatecoder import config, lsp
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import PathError, display_path, resolve_in_workspace
+
+MAX_DIAGNOSTIC_FILES = 5
+
+
+def _disabled_error() -> ToolResult:
+    return ToolResult.error(lsp.LSP_DISABLED_MESSAGE)
+
+
+def format_diagnostic(path: str, diagnostic: dict[str, Any]) -> str:
+    line = (
+        f"{path}:{diagnostic['line']}:{diagnostic['character']} "
+        f"{diagnostic['severity']} {diagnostic['message']}"
+    )
+    source = diagnostic.get("source")
+    if source:
+        line += f" ({source})"
+    return line.rstrip()
+
+
+def _format_location(location: dict[str, Any], session: Session) -> str:
+    raw_path = str(location.get("path") or "")
+    display = raw_path
+    if raw_path:
+        try:
+            display = display_path(Path(raw_path), session.workspace_root)
+        except (OSError, ValueError):
+            display = raw_path
+    return f"{display}:{location.get('line')}:{location.get('character')}"
+
+
+def _parse_position(args: dict[str, Any]) -> tuple[int, int] | ToolResult:
+    raw_line = args.get("line")
+    raw_character = args.get("character")
+    if raw_line is None or raw_character is None:
+        return ToolResult.error("'line' and 'character' are required (1-based)")
+    try:
+        line = int(raw_line)
+        character = int(raw_character)
+    except (TypeError, ValueError):
+        return ToolResult.error("'line' and 'character' must be integers (1-based)")
+    if line < 1 or character < 1:
+        return ToolResult.error("'line' and 'character' are 1-based and must be >= 1")
+    return line, character
+
+
+def _include_declaration(args: dict[str, Any]) -> bool:
+    value = args.get("include_declaration")
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() not in {"false", "0", "no", "off"}
+
+
+def _lsp_diagnostics(args: dict[str, Any], session: Session) -> ToolResult:
+    if not config.get_lsp()["enabled"]:
+        return _disabled_error()
+    raw_path = str(args.get("path") or "").strip()
+    if raw_path:
+        targets = [raw_path]
+    else:
+        targets = list(session.touched_files)[-MAX_DIAGNOSTIC_FILES:]
+        if not targets:
+            return ToolResult.error(
+                "No file given and none have been touched yet; pass a path."
+            )
+
+    manager = lsp.ensure_manager(root=session.workspace_root)
+    lines: list[str] = []
+    failures: list[str] = []
+    for target in targets:
+        try:
+            resolved = resolve_in_workspace(target, session.workspace_root)
+        except PathError as exc:
+            failures.append(str(exc))
+            continue
+        display = display_path(resolved, session.workspace_root)
+        try:
+            diagnostics = manager.diagnostics_for(resolved)
+        except lsp.LspError as exc:
+            failures.append(f"{display}: {exc}")
+            continue
+        lines.extend(format_diagnostic(display, item) for item in diagnostics)
+
+    if lines:
+        return ToolResult(content="\n".join(lines))
+    if failures:
+        return ToolResult.error("; ".join(failures[:3]))
+    return ToolResult(content="No diagnostics.")
+
+
+def _lsp_definition(args: dict[str, Any], session: Session) -> ToolResult:
+    if not config.get_lsp()["enabled"]:
+        return _disabled_error()
+    path = str(args.get("path") or "").strip()
+    if not path:
+        return ToolResult.error("'path' is required")
+    position = _parse_position(args)
+    if isinstance(position, ToolResult):
+        return position
+    line, character = position
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+
+    manager = lsp.ensure_manager(root=session.workspace_root)
+    try:
+        locations = manager.definition(resolved, line, character)
+    except lsp.LspError as exc:
+        return ToolResult.error(str(exc))
+    if not locations:
+        return ToolResult(
+            content=f"No definition found at {path}:{line}:{character}."
+        )
+    return ToolResult(
+        content="\n".join(_format_location(item, session) for item in locations)
+    )
+
+
+def _lsp_references(args: dict[str, Any], session: Session) -> ToolResult:
+    if not config.get_lsp()["enabled"]:
+        return _disabled_error()
+    path = str(args.get("path") or "").strip()
+    if not path:
+        return ToolResult.error("'path' is required")
+    position = _parse_position(args)
+    if isinstance(position, ToolResult):
+        return position
+    line, character = position
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+
+    manager = lsp.ensure_manager(root=session.workspace_root)
+    try:
+        locations = manager.references(
+            resolved,
+            line,
+            character,
+            include_declaration=_include_declaration(args),
+        )
+    except lsp.LspError as exc:
+        return ToolResult.error(str(exc))
+    if not locations:
+        return ToolResult(
+            content=f"No references found at {path}:{line}:{character}."
+        )
+    return ToolResult(
+        content="\n".join(_format_location(item, session) for item in locations)
+    )
+
+
+lsp_diagnostics_tool = FunctionTool(
+    name="lsp_diagnostics",
+    description=(
+        "Get language-server diagnostics (errors, warnings) for a file, or for "
+        "the most recently touched files when no path is given. Requires LSP to "
+        "be enabled and a matching server installed. Use it after edits to "
+        "check the code compiles/type-checks."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "File to check, relative to the workspace root.",
+            },
+        },
+    },
+    func=_lsp_diagnostics,
+    writes=False,
+    runs=False,
+)
+
+lsp_definition_tool = FunctionTool(
+    name="lsp_definition",
+    description=(
+        "Find where the symbol at a 1-based line/character is defined using the "
+        "language server. Returns one location per line."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "File to inspect, relative to the workspace root.",
+            },
+            "line": {
+                "type": "integer",
+                "description": "1-based line number of the symbol.",
+            },
+            "character": {
+                "type": "integer",
+                "description": "1-based column number of the symbol.",
+            },
+        },
+        "required": ["path", "line", "character"],
+    },
+    func=_lsp_definition,
+    writes=False,
+    runs=False,
+)
+
+lsp_references_tool = FunctionTool(
+    name="lsp_references",
+    description=(
+        "Find every reference to the symbol at a 1-based line/character using "
+        "the language server. Returns one location per line."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "File to inspect, relative to the workspace root.",
+            },
+            "line": {
+                "type": "integer",
+                "description": "1-based line number of the symbol.",
+            },
+            "character": {
+                "type": "integer",
+                "description": "1-based column number of the symbol.",
+            },
+            "include_declaration": {
+                "type": "boolean",
+                "description": "Include the declaration itself (default true).",
+            },
+        },
+        "required": ["path", "line", "character"],
+    },
+    func=_lsp_references,
+    writes=False,
+    runs=False,
+)

kiwimatecoder/tools/memory.py

@@ -0,0 +1,115 @@
+"""remember (approval-gated) and recall (read-only) persistent-memory tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder import config
+from kiwimatecoder import memory as memory_module
+from kiwimatecoder.redaction import redact
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+
+def _remember(args: dict[str, Any], session: Session) -> ToolResult:
+    content = str(args.get("content") or "").strip()
+    if not content:
+        return ToolResult.error("'content' is required")
+    scope = str(args.get("scope") or "project").strip().lower()
+    try:
+        path = memory_module.append_memory(scope, session.workspace_root, content)
+    except ValueError as exc:
+        return ToolResult.error(str(exc))
+    return ToolResult(content=f"Remembered ({scope}): {path}\n- {content}")
+
+
+def _recall(args: dict[str, Any], session: Session) -> ToolResult:
+    query = str(args.get("query") or "").strip()
+    settings = config.get_memory()
+    cap = int(settings["max_bytes"])
+    sections: list[str] = []
+    for scope in memory_module.SCOPES:
+        text = memory_module.read_memory(scope, session.workspace_root, cap)
+        if not text:
+            continue
+        if query:
+            text = "\n".join(
+                line
+                for line in text.splitlines()
+                if query.lower() in line.lower()
+            )
+        if not text.strip():
+            continue
+        path = memory_module.memory_path(scope, session.workspace_root)
+        sections.append(f"{scope} memory ({path}):\n{text}")
+    if not sections:
+        if query:
+            return ToolResult(content=f"No memory entries match {query!r}.")
+        return ToolResult(content="No memory stored yet.")
+    body = "\n\n".join(sections)
+    if len(body) > cap:
+        body = body[:cap] + "\n[truncated]"
+    return ToolResult(content=body)
+
+
+def preview(args: dict[str, Any], session: Session) -> str:
+    """Show the target file and bullet for the approval prompt."""
+    scope = str(args.get("scope") or "project").strip().lower()
+    try:
+        path = memory_module.memory_path(scope, session.workspace_root)
+    except ValueError as exc:
+        return str(exc)
+    content = str(args.get("content") or "").strip()
+    if not content:
+        return f"Append to memory {path}: (empty; will be rejected)"
+    return f"Append to memory {path}:\n- {redact(content)}"
+
+
+remember_tool = FunctionTool(
+    name="remember",
+    description=(
+        "Persist a durable fact about the user or this project so it survives "
+        "future sessions. Use scope='project' for workspace-specific facts and "
+        "scope='user' for preferences that apply everywhere. Requires approval; "
+        "never store secrets, credentials, or API keys."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "content": {
+                "type": "string",
+                "description": "The fact to remember, as a short statement.",
+            },
+            "scope": {
+                "type": "string",
+                "enum": list(memory_module.SCOPES),
+                "description": (
+                    "Where to store it: project (this workspace) or user "
+                    "(all workspaces). Defaults to project."
+                ),
+            },
+        },
+        "required": ["content"],
+    },
+    func=_remember,
+    writes=True,
+)
+
+recall_tool = FunctionTool(
+    name="recall",
+    description=(
+        "Read persistent memory for the project and user. Pass a query to "
+        "filter entries by case-insensitive substring. Read-only, so it is "
+        "available in plan mode."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Optional case-insensitive filter.",
+            },
+        },
+    },
+    func=_recall,
+)

kiwimatecoder/tools/paths.py

@@ -0,0 +1,234 @@
+"""Workspace path resolution and sandboxing.
+
+Every file-touching tool resolves its path through :func:`resolve_in_workspace`,
+which rejects paths that escape the workspace root (via ``..`` or symlinks).
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path
+
+DEFAULT_SKIP_DIRS: set[str] = {
+    ".git",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "env",
+    "node_modules",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".eggs",
+}
+
+
+class WorkspaceIgnore:
+    """Evaluates whether paths should be ignored based on default skip dirs and .gitignore."""
+
+    workspace_root: Path
+    rules: list[tuple[bool, str, bool]]
+
+    def __init__(
+        self,
+        workspace_root: Path,
+        rules: list[tuple[bool, str, bool]] | None = None,
+    ) -> None:
+        self.workspace_root = workspace_root.resolve()
+        self.rules = (
+            rules if rules is not None else self._load_rules()
+        )
+
+    def _load_rules(self) -> list[tuple[bool, str, bool]]:
+        gitignore_path = self.workspace_root / ".gitignore"
+        if not gitignore_path.is_file():
+            return []
+        rules: list[tuple[bool, str, bool]] = []
+        try:
+            content = gitignore_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return []
+
+        for line in content.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            is_neg = line.startswith("!")
+            if is_neg:
+                line = line[1:].strip()
+            if not line:
+                continue
+            dir_only = line.endswith("/")
+            if dir_only:
+                line = line[:-1]
+            if line.startswith("/"):
+                line = line[1:]
+            rules.append((is_neg, line, dir_only))
+        return rules
+
+    def is_ignored(self, path: Path, is_dir: bool = False) -> bool:
+        """Check if path should be ignored."""
+        try:
+            resolved = path.resolve()
+        except OSError:
+            resolved = path
+
+        parts = resolved.parts
+        if any(part in DEFAULT_SKIP_DIRS for part in parts):
+            return True
+
+        if not self.rules:
+            return False
+
+        try:
+            rel = resolved.relative_to(self.workspace_root).as_posix()
+        except ValueError:
+            rel = path.as_posix()
+
+        ignored = False
+        name = resolved.name
+        for is_neg, pat, dir_only in self.rules:
+            matches = False
+            if dir_only:
+                if is_dir:
+                    if "/" in pat:
+                        matches = fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(
+                            rel, f"{pat}/*"
+                        )
+                    else:
+                        matches = (
+                            fnmatch.fnmatch(name, pat)
+                            or fnmatch.fnmatch(rel, f"**/{pat}")
+                            or fnmatch.fnmatch(rel, f"{pat}/*")
+                        )
+                else:
+                    if "/" in pat:
+                        matches = fnmatch.fnmatch(
+                            rel, f"{pat}/*"
+                        ) or fnmatch.fnmatch(rel, f"**/{pat}/*")
+                    else:
+                        matches = (
+                            fnmatch.fnmatch(rel, f"{pat}/*")
+                            or fnmatch.fnmatch(rel, f"**/{pat}/*")
+                            or (pat in resolved.parts)
+                        )
+            else:
+                if "/" in pat:
+                    matches = fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(
+                        rel, f"{pat}/*"
+                    )
+                else:
+                    matches = (
+                        fnmatch.fnmatch(name, pat)
+                        or fnmatch.fnmatch(rel, f"**/{pat}")
+                        or fnmatch.fnmatch(rel, f"{pat}/*")
+                    )
+
+            if matches:
+                ignored = not is_neg
+
+        return ignored
+
+
+_IGNORE_CACHE: dict[str, tuple[float, WorkspaceIgnore]] = {}
+
+
+def get_workspace_ignore(workspace_root: Path) -> WorkspaceIgnore:
+    """Return a cached WorkspaceIgnore instance for the given root."""
+    root = workspace_root.resolve()
+    key = str(root)
+    gi_path = root / ".gitignore"
+    try:
+        mtime = gi_path.stat().st_mtime if gi_path.exists() else 0.0
+    except OSError:
+        mtime = 0.0
+    cached = _IGNORE_CACHE.get(key)
+    if cached is not None and cached[0] == mtime:
+        return cached[1]
+    ignore = WorkspaceIgnore(root)
+    _IGNORE_CACHE[key] = (mtime, ignore)
+    return ignore
+
+
+class PathError(ValueError):
+    """Raised when a path escapes the workspace root."""
+
+
+def atomic_write_text(path: Path, content: str) -> None:
+    """Write ``content`` to ``path`` atomically as UTF-8.
+
+    Writes to a sibling temp file then ``os.replace``s it into place, so a
+    crash mid-write cannot truncate the destination. Parent directories must
+    already exist.
+    """
+    tmp = path.with_name(path.name + ".kiwi.tmp")
+    try:
+        tmp.write_text(content, encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+
+
+def resolve_in_workspace(path: str, workspace_root: Path) -> Path:
+    """Resolve ``path`` against ``workspace_root`` and ensure it stays inside.
+
+    Symlinks are resolved before the containment check so they cannot be used
+    to escape the sandbox.
+    """
+    root = workspace_root.resolve()
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    resolved = candidate.resolve()
+    if resolved != root and not resolved.is_relative_to(root):
+        raise PathError(
+            f"Path '{path}' is outside the workspace root ({root}). "
+            + "Access is restricted to the current project directory."
+        )
+    return resolved
+
+
+def resolve_for_read(
+    path: str, workspace_root: Path, trusted: bool = False
+) -> Path:
+    """Resolve a read-only path, allowing escapes only in trusted mode.
+
+    Trusted workspaces still prevent writes outside the root because only
+    read-only tools call this helper.
+    """
+    if not trusted:
+        return resolve_in_workspace(path, workspace_root)
+    candidate = Path(path).expanduser()
+    if not candidate.is_absolute():
+        candidate = workspace_root / candidate
+    return candidate.resolve()
+
+
+def display_path(path: Path, workspace_root: Path) -> str:
+    """Return a path relative to the workspace root for display, if possible."""
+    root = workspace_root.resolve()
+    try:
+        return str(path.resolve().relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def workspace_ref(path: Path, workspace_root: Path) -> str:
+    """Return the portable form of a workspace-relative path, for storing in the session.
+
+    Unlike :func:`display_path` this always uses forward slashes, so entries in
+    ``touched_files`` / ``context_files`` mean the same thing in a session JSON saved
+    on Windows and loaded on POSIX (or vice versa). A path outside the workspace is
+    returned unchanged.
+    """
+    root = workspace_root.resolve()
+    try:
+        return path.resolve().relative_to(root).as_posix()
+    except ValueError:
+        return str(path)