kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/tools/edit_file.py

@@ -0,0 +1,143 @@
+"""edit_file tool: replace a unique string in an existing file."""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import (
+    PathError,
+    atomic_write_text,
+    display_path,
+    resolve_in_workspace,
+    workspace_ref,
+)
+
+
+class EditError(ValueError):
+    """Raised when an edit cannot be applied unambiguously."""
+
+
+def compute_edit(text: str, old: str, new: str, replace_all: bool) -> str:
+    """Apply the edit to ``text`` or raise :class:`EditError`."""
+    if old == new:
+        raise EditError("old_string and new_string are identical")
+    count = text.count(old)
+    if count == 0:
+        raise EditError("old_string not found in file")
+    if count > 1 and not replace_all:
+        raise EditError(
+            f"old_string is not unique ({count} matches); add surrounding context to disambiguate or set replace_all=true"
+        )
+    if replace_all:
+        return text.replace(old, new)
+    return text.replace(old, new, 1)
+
+
+def _edit_from_args(text: str, args: dict[str, Any]) -> str:
+    """Compute the edit described by ``args``; raises :class:`EditError`."""
+    return compute_edit(
+        text,
+        str(args.get("old_string") or ""),
+        str(args.get("new_string") or ""),
+        bool(args.get("replace_all")),
+    )
+
+
+def compute_new_content(old_text: str, args: dict[str, Any]) -> str | None:
+    """Return the content after applying ``args``, or None when it can't apply."""
+    try:
+        return _edit_from_args(old_text, args)
+    except EditError:
+        return None
+
+
+def _diff(old_text: str, new_text: str, rel: str) -> str:
+    return "".join(
+        difflib.unified_diff(
+            old_text.splitlines(keepends=True),
+            new_text.splitlines(keepends=True),
+            fromfile=rel,
+            tofile=rel,
+            n=3,
+        )
+    )
+
+
+def preview(args: dict[str, Any], session: Session) -> str:
+    """Return a unified diff for the approval prompt."""
+    path = str(args.get("path") or "")
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError as exc:
+        return str(exc)
+    if not resolved.exists():
+        return f"(file not found: {path})"
+    rel = display_path(resolved, session.workspace_root)
+    old_text = resolved.read_text(encoding="utf-8", errors="replace")
+    try:
+        new_text = _edit_from_args(old_text, args)
+    except EditError as exc:
+        return f"(cannot apply edit: {exc})"
+    return _diff(old_text, new_text, rel) or "(no changes)"
+
+
+def _edit_file(args: dict[str, Any], session: Session) -> ToolResult:
+    path = str(args.get("path") or "")
+    if not path:
+        return ToolResult.error("'path' is required")
+    try:
+        resolved = resolve_in_workspace(path, session.workspace_root)
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+    if not resolved.exists():
+        return ToolResult.error(f"File not found: {path}")
+
+    old_text = resolved.read_text(encoding="utf-8", errors="replace")
+    try:
+        new_text = _edit_from_args(old_text, args)
+    except EditError as exc:
+        return ToolResult.error(str(exc))
+
+    try:
+        atomic_write_text(resolved, new_text)
+    except OSError as exc:
+        return ToolResult.error(f"Could not write file: {exc}")
+    session.record_touched(workspace_ref(resolved, session.workspace_root))
+    return ToolResult(content=f"Edited {path}.")
+
+
+edit_file_tool = FunctionTool(
+    name="edit_file",
+    description=(
+        "Replace an exact string in an existing file. old_string must match "
+        "uniquely unless replace_all is true. Include enough surrounding context "
+        "to make the match unambiguous."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Path relative to the workspace root.",
+            },
+            "old_string": {
+                "type": "string",
+                "description": "Exact text to find and replace.",
+            },
+            "new_string": {
+                "type": "string",
+                "description": "Replacement text.",
+            },
+            "replace_all": {
+                "type": "boolean",
+                "description": "Replace every occurrence instead of requiring uniqueness.",
+            },
+        },
+        "required": ["path", "old_string", "new_string"],
+    },
+    func=_edit_file,
+    writes=True,
+)

kiwimatecoder/tools/forge.py

@@ -0,0 +1,207 @@
+"""forge (read-only) and forge_write (approval-gated) tools.
+
+Both delegate to the official forge CLI (``gh``/``glab``) so the user's
+existing login is used. Only list/view and create actions are exposed; merge,
+close, and delete are intentionally not implemented.
+"""
+
+from __future__ import annotations
+
+import shlex
+from typing import Any
+
+from kiwimatecoder import forge as forge_module
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+READ_ACTIONS = forge_module.READ_ACTIONS
+WRITE_ACTIONS = forge_module.WRITE_ACTIONS
+
+
+def _truncate(text: str) -> str:
+    if len(text) > forge_module.MAX_OUTPUT:
+        return text[: forge_module.MAX_OUTPUT] + "\n... [output truncated]"
+    return text
+
+
+def _render(cli: str, action: str, code: int, output: str) -> ToolResult:
+    output = output.strip()
+    body = output if output else "(no output)"
+    content = f"{cli} {action}:\n{_truncate(body)}\n[exit code: {code}]"
+    return ToolResult(content=content, ok=code == 0)
+
+
+def _resolve(session: Session) -> tuple[str | None, str | None, ToolResult | None]:
+    """Detect the forge and CLI, or return a clear error result."""
+    remote = forge_module.current_remote_url(session)
+    if not remote:
+        return (
+            None,
+            None,
+            ToolResult.error(
+                "No git remote 'origin' found in this workspace. Add one with "
+                "`git remote add origin <url>` and try again."
+            ),
+        )
+    kind = forge_module.detect_forge(remote)
+    if kind is None:
+        return (
+            None,
+            None,
+            ToolResult.error(
+                f"Remote '{remote}' is not a supported forge host. Only "
+                "github.com and gitlab.com remotes are supported."
+            ),
+        )
+    cli = forge_module.forge_cli(kind)
+    if not cli or not forge_module.cli_available(cli):
+        return (
+            None,
+            None,
+            ToolResult.error(
+                f"The '{cli or kind}' CLI is required for {kind} but was not "
+                "found on PATH. Install and authenticate it, then try again."
+            ),
+        )
+    return kind, cli, None
+
+
+def _number(args: dict[str, Any]) -> tuple[int | None, ToolResult | None]:
+    raw = args.get("number")
+    if raw is None:
+        return None, ToolResult.error("'number' must be an integer")
+    try:
+        number = int(raw)
+    except (TypeError, ValueError):
+        return None, ToolResult.error("'number' must be an integer")
+    if number < 1:
+        return None, ToolResult.error("'number' must be a positive integer")
+    return number, None
+
+
+def _forge(args: dict[str, Any], session: Session) -> ToolResult:
+    kind, cli, error = _resolve(session)
+    if error is not None:
+        return error
+    assert kind is not None and cli is not None
+
+    action = str(args.get("action") or "").strip().lower()
+    if action not in READ_ACTIONS:
+        return ToolResult.error(
+            f"Unknown forge action '{action}'. Choose: {', '.join(READ_ACTIONS)}."
+        )
+
+    command: list[str]
+    if action == "pr_list":
+        command = forge_module.pr_list_args(kind)
+    elif action == "issue_list":
+        command = forge_module.issue_list_args()
+    elif action == "pr_view":
+        number, number_error = _number(args)
+        if number_error is not None:
+            return number_error
+        command = forge_module.pr_view_args(number if number is not None else 0, forge=kind)
+    else:  # issue_view
+        number, number_error = _number(args)
+        if number_error is not None:
+            return number_error
+        command = forge_module.issue_view_args(number if number is not None else 0)
+
+    code, output = forge_module.run_forge(cli, command, session)
+    return _render(cli, action, code, output)
+
+
+def _forge_write(args: dict[str, Any], session: Session) -> ToolResult:
+    kind, cli, error = _resolve(session)
+    if error is not None:
+        return error
+    assert kind is not None and cli is not None
+
+    try:
+        command = forge_module.build_write_args(kind, args)
+    except ValueError as exc:
+        return ToolResult.error(str(exc))
+
+    code, output = forge_module.run_forge(cli, command, session)
+    action = str(args.get("action") or "").strip().lower()
+    return _render(cli, action, code, output)
+
+
+def preview(args: dict[str, Any], session: Session) -> str:
+    """Return the exact CLI command line for the approval prompt."""
+    kind, cli, error = _resolve(session)
+    if error is not None:
+        return error.content
+    assert kind is not None and cli is not None
+    try:
+        command = forge_module.build_write_args(kind, args)
+    except ValueError as exc:
+        return str(exc)
+    return f"{cli} " + " ".join(shlex.quote(part) for part in command)
+
+
+forge_tool = FunctionTool(
+    name="forge",
+    description=(
+        "Read GitHub/GitLab data through the gh/glab CLI: list or view pull "
+        "requests (merge requests on GitLab) and issues. The forge is detected "
+        "from the origin remote. Requires the matching CLI to be installed and "
+        "authenticated."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": list(READ_ACTIONS),
+                "description": "Which forge query to run.",
+            },
+            "number": {
+                "type": "integer",
+                "description": "PR/MR or issue number for the view actions.",
+            },
+        },
+        "required": ["action"],
+    },
+    func=_forge,
+    writes=False,
+    runs=False,
+)
+
+forge_write_tool = FunctionTool(
+    name="forge_write",
+    description=(
+        "Create a pull request (merge request on GitLab) or an issue using "
+        "gh/glab. Requires user approval. Merge, close, and delete are "
+        "intentionally unavailable."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": list(WRITE_ACTIONS),
+                "description": "Which forge object to create.",
+            },
+            "title": {
+                "type": "string",
+                "description": "Title for the PR/MR or issue.",
+            },
+            "body": {
+                "type": "string",
+                "description": "Body text for the PR/MR or issue.",
+            },
+            "base": {
+                "type": "string",
+                "description": "Base/target branch for a PR/MR.",
+            },
+            "draft": {
+                "type": "boolean",
+                "description": "Open a PR/MR as a draft.",
+            },
+        },
+        "required": ["action", "title"],
+    },
+    func=_forge_write,
+    writes=True,
+)

kiwimatecoder/tools/git.py

@@ -0,0 +1,158 @@
+"""git (read-only) and git_write (approval-gated) tools.
+
+The read-only tool is safe to advertise in plan mode. ``git_write`` is marked
+``writes=True`` so the permission gate prompts with the exact command as
+preview. Checkpointing only covers file tools, so git actions rely on the
+approval prompt instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder import git as git_module
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+READ_ACTIONS = ("status", "diff", "log", "show", "branches")
+WRITE_ACTIONS = git_module.WRITE_ACTIONS
+
+_LOG_LIMIT_DEFAULT = 20
+
+
+def _truncate(text: str) -> str:
+    if len(text) > git_module.MAX_OUTPUT:
+        return text[: git_module.MAX_OUTPUT] + "\n... [output truncated]"
+    return text
+
+
+def _render(code: int, output: str) -> ToolResult:
+    output = output.strip()
+    body = output if output else "(no output)"
+    content = f"{_truncate(body)}\n[exit code: {code}]"
+    return ToolResult(content=content, ok=code == 0)
+
+
+def _git(args: dict[str, Any], session: Session) -> ToolResult:
+    action = str(args.get("action") or "status").strip().lower()
+    if action not in READ_ACTIONS:
+        return ToolResult.error(
+            f"Unknown git action '{action}'. Choose: {', '.join(READ_ACTIONS)}."
+        )
+    path = args.get("path")
+    path_text = str(path).strip() if path is not None else None
+    ref = args.get("ref")
+    ref_text = str(ref).strip() if ref is not None else None
+
+    if action == "status":
+        command = git_module.status_args()
+    elif action == "diff":
+        command = git_module.diff_args(
+            staged=bool(args.get("staged", False)), path=path_text, ref=ref_text
+        )
+    elif action == "log":
+        raw_limit = args.get("limit")
+        try:
+            limit = int(raw_limit) if raw_limit is not None else _LOG_LIMIT_DEFAULT
+        except (TypeError, ValueError):
+            return ToolResult.error("'limit' must be an integer")
+        command = git_module.log_args(limit, path=path_text, oneline=True)
+    elif action == "show":
+        command = git_module.show_args(ref_text or "HEAD")
+    else:
+        command = git_module.branch_args()
+
+    code, output = git_module.run_git(command, session)
+    return _render(code, output)
+
+
+def _git_write(args: dict[str, Any], session: Session) -> ToolResult:
+    action = str(args.get("action") or "").strip().lower()
+    if action not in WRITE_ACTIONS:
+        return ToolResult.error(
+            f"Unknown git_write action '{action}'. Choose: {', '.join(WRITE_ACTIONS)}."
+        )
+    try:
+        command = git_module.build_write_args(args)
+    except ValueError as exc:
+        return ToolResult.error(str(exc))
+
+    code, output = git_module.run_git(command, session, timeout=60)
+    return _render(code, output)
+
+
+git_tool = FunctionTool(
+    name="git",
+    description=(
+        "Inspect the repository (read-only): status, diff (staged or not, "
+        "optionally against a ref), log (1-100 commits), show a ref, or list "
+        "branches. Use it before staging or committing to check what changed."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": list(READ_ACTIONS),
+                "description": "Which read-only git command to run.",
+            },
+            "path": {
+                "type": "string",
+                "description": "Limit diff/log to this path.",
+            },
+            "ref": {
+                "type": "string",
+                "description": "Commit/branch for diff or show (defaults to HEAD).",
+            },
+            "staged": {
+                "type": "boolean",
+                "description": "Diff the staged changes instead of the working tree.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Number of log entries (1-100, default 20).",
+            },
+        },
+        "required": ["action"],
+    },
+    func=_git,
+    writes=False,
+    runs=False,
+)
+
+git_write_tool = FunctionTool(
+    name="git_write",
+    description=(
+        "Make a git change: stage paths, unstage paths, commit with a message, "
+        "or create and switch to a new branch. Requires user approval. Push, "
+        "reset, and clean are intentionally unavailable."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "action": {
+                "type": "string",
+                "enum": list(WRITE_ACTIONS),
+                "description": "Which git mutation to perform.",
+            },
+            "paths": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Paths to stage or unstage.",
+            },
+            "message": {
+                "type": "string",
+                "description": "Commit message (required for commit).",
+            },
+            "branch": {
+                "type": "string",
+                "description": "New branch name (required for checkout_branch).",
+            },
+        },
+        "required": ["action"],
+    },
+    func=_git_write,
+    writes=True,
+)
+
+preview = git_module.preview