Skip to content

Edit file

edit_file

EditFileTool — find-and-replace text in a file.

Registered as edit_file via the axm.tools entry point.

EditFileTool

Find and replace text in a single file.

Performs a single-occurrence replacement by default. Errors if the target text is not found or appears multiple times (unless count is specified). Registered as edit_file via axm.tools entry point.

Source code in packages/axm-edit/src/axm_edit/tools/edit_file.py
Python
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
class EditFileTool:
    """Find and replace text in a single file.

    Performs a single-occurrence replacement by default. Errors if
    the target text is not found or appears multiple times (unless
    ``count`` is specified).
    Registered as ``edit_file`` via axm.tools entry point.
    """

    agent_hint: str = (
        "Find-and-replace in a file, confined to a project root."
        " Args: path (root), file (relative), old, new."
        " Replaces first occurrence. Errors if text not found"
        " or ambiguous (multiple matches)."
    )

    @property
    def name(self) -> str:
        """Tool name used for MCP registration."""
        return "edit_file"

    @staticmethod
    def _validate_args(
        file: str | None, old: str | None, new: str | None, count: int
    ) -> str | None:
        """Return an error message if required args are invalid, else None."""
        if not file:
            return "Missing required argument: file"
        if old is None:
            return "Missing required argument: old"
        if new is None:
            return "Missing required argument: new"
        if count != -1 and count < 1:
            return "count must be -1 (all) or a positive integer"
        return None

    @staticmethod
    def _check_occurrences(old: str, occurrences: int, count: int) -> str | None:
        """Return an error message if occurrence count is invalid, else None."""
        if occurrences == 0:
            return "Text not found in file"
        if occurrences > 1 and count == 1:
            return (
                f"Ambiguous: found {occurrences} occurrences. "
                f"Use count={occurrences} or count=-1 to replace all."
            )
        return None

    @staticmethod
    def _resolve_target(root_str: str, file_rel: str) -> Path | ToolResult:
        """Resolve *file_rel* under *root_str*, confined via ``resolve_safe``.

        Returns the resolved ``Path`` on success, or a ``ToolResult`` error
        when the root is not a directory, the target escapes the root, or the
        file does not exist.
        """
        root = Path(root_str).resolve()
        if not root.is_dir():
            return ToolResult(
                success=False,
                error=f"Root is not a directory: {root_str}",
            )
        target = resolve_safe(root, file_rel)
        if target is None:
            return ToolResult(
                success=False,
                error=f"Path escapes project root (confinement barrier): {file_rel}",
            )
        if not target.is_file():
            return ToolResult(success=False, error=f"File not found: {file_rel}")
        return target

    def execute(
        self,
        *,
        path: str = ".",
        file: str | None = None,
        old: str | None = None,
        new: str | None = None,
        count: int = 1,
        **kwargs: object,
    ) -> ToolResult:
        """Find and replace text in a file, confined under a project root.

        Args:
            path: Project root directory (default ".").
            file: Path to the file to edit, relative to ``path``.
            old: Text to find (exact match).
            new: Replacement text.
            count: Max replacements (default 1). Use -1 for all.

        Returns:
            ToolResult with replacement details. A ``file`` that escapes
            ``path`` (absolute outside root, or ``..`` traversal) is
            refused with ``success=False``.
        """
        root_str = path
        file_rel = file

        validation_error = self._validate_args(file_rel, old, new, count)
        if validation_error:
            return ToolResult(success=False, error=validation_error)

        # After validation, file/old/new are guaranteed non-None
        assert file_rel is not None
        assert old is not None
        assert new is not None

        resolved = self._resolve_target(root_str, file_rel)
        if isinstance(resolved, ToolResult):
            return resolved
        target = resolved

        try:
            content = target.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError) as exc:
            return ToolResult(success=False, error=f"Read failed: {exc}")

        occurrences = content.count(old)
        occurrence_error = self._check_occurrences(old, occurrences, count)
        if occurrence_error:
            return ToolResult(success=False, error=occurrence_error)

        # Perform replacement
        if count == -1:
            new_content = content.replace(old, new)
            replaced = occurrences
        else:
            new_content = content.replace(old, new, count)
            replaced = min(count, occurrences)

        try:
            target.write_text(new_content, encoding="utf-8")
        except OSError as exc:
            return ToolResult(success=False, error=f"Write failed: {exc}")

        # Find line number of first occurrence
        line_num = content[: content.index(old)].count("\n") + 1

        logger.debug(
            "edit %s: replaced %d occurrence(s) at line %d",
            file_rel,
            replaced,
            line_num,
        )

        target_path = str(target)
        return ToolResult(
            success=True,
            data={
                "path": target_path,
                "replacements": replaced,
                "first_line": line_num,
            },
            text=render_text(
                path=target_path,
                replacements=replaced,
                first_line=line_num,
            ),
        )
name property

Tool name used for MCP registration.

execute(*, path='.', file=None, old=None, new=None, count=1, **kwargs)

Find and replace text in a file, confined under a project root.

Parameters:

Name Type Description Default
path str

Project root directory (default ".").

 '.'
file str | None

Path to the file to edit, relative to path.

 None
old str | None

Text to find (exact match).

 None
new str | None

Replacement text.

 None
count int

Max replacements (default 1). Use -1 for all.

 1

Returns:

Type Description
ToolResult

ToolResult with replacement details. A file that escapes
ToolResult

path (absolute outside root, or .. traversal) is
ToolResult

refused with success=False.
Source code in packages/axm-edit/src/axm_edit/tools/edit_file.py
Python
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def execute(
    self,
    *,
    path: str = ".",
    file: str | None = None,
    old: str | None = None,
    new: str | None = None,
    count: int = 1,
    **kwargs: object,
) -> ToolResult:
    """Find and replace text in a file, confined under a project root.

    Args:
        path: Project root directory (default ".").
        file: Path to the file to edit, relative to ``path``.
        old: Text to find (exact match).
        new: Replacement text.
        count: Max replacements (default 1). Use -1 for all.

    Returns:
        ToolResult with replacement details. A ``file`` that escapes
        ``path`` (absolute outside root, or ``..`` traversal) is
        refused with ``success=False``.
    """
    root_str = path
    file_rel = file

    validation_error = self._validate_args(file_rel, old, new, count)
    if validation_error:
        return ToolResult(success=False, error=validation_error)

    # After validation, file/old/new are guaranteed non-None
    assert file_rel is not None
    assert old is not None
    assert new is not None

    resolved = self._resolve_target(root_str, file_rel)
    if isinstance(resolved, ToolResult):
        return resolved
    target = resolved

    try:
        content = target.read_text(encoding="utf-8")
    except (OSError, UnicodeDecodeError) as exc:
        return ToolResult(success=False, error=f"Read failed: {exc}")

    occurrences = content.count(old)
    occurrence_error = self._check_occurrences(old, occurrences, count)
    if occurrence_error:
        return ToolResult(success=False, error=occurrence_error)

    # Perform replacement
    if count == -1:
        new_content = content.replace(old, new)
        replaced = occurrences
    else:
        new_content = content.replace(old, new, count)
        replaced = min(count, occurrences)

    try:
        target.write_text(new_content, encoding="utf-8")
    except OSError as exc:
        return ToolResult(success=False, error=f"Write failed: {exc}")

    # Find line number of first occurrence
    line_num = content[: content.index(old)].count("\n") + 1

    logger.debug(
        "edit %s: replaced %d occurrence(s) at line %d",
        file_rel,
        replaced,
        line_num,
    )

    target_path = str(target)
    return ToolResult(
        success=True,
        data={
            "path": target_path,
            "replacements": replaced,
            "first_line": line_num,
        },
        text=render_text(
            path=target_path,
            replacements=replaced,
            first_line=line_num,
        ),
    )

render_text(*, path, replacements, first_line)

Render a compact, git-style LLM-facing view of an edit result.

The header carries the global status (✓), the edited path, the exact number of replacements applied, and the 1-indexed line of the first match. All three values mirror data verbatim — only the JSON structure (braces, quotes, keys) is dropped, so no information is lost relative to data. (The success path always applies at least one replacement; the no-match and ambiguous cases are surfaced earlier via error and never reach this renderer.)

Source code in packages/axm-edit/src/axm_edit/tools/edit_file.py
Python
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def render_text(*, path: str, replacements: int, first_line: int) -> str:
    """Render a compact, ``git``-style LLM-facing view of an edit result.

    The header carries the global status (``✓``), the edited path, the exact
    number of replacements applied, and the 1-indexed line of the first
    match. All three values mirror ``data`` verbatim — only the JSON
    structure (braces, quotes, keys) is dropped, so no information is lost
    relative to ``data``. (The success path always applies at least one
    replacement; the no-match and ambiguous cases are surfaced earlier via
    ``error`` and never reach this renderer.)
    """
    plural = "s" if replacements != 1 else ""
    return (
        f"edit_file | ✓ | {path} · {replacements} replacement{plural} @ L{first_line}"
    )