zrb 1.13.1__py3-none-any.whl → 1.21.17__py3-none-any.whl

zrb/builtin/llm/tool/file.py

@@ -2,17 +2,15 @@ import fnmatch
 import json
 import os
 import re
-from typing import Any, Dict, List, Optional
+from typing import Any, Optional
 
 from zrb.builtin.llm.tool.sub_agent import create_sub_agent_tool
 from zrb.config.config import CFG
 from zrb.config.llm_rate_limitter import llm_rate_limitter
 from zrb.context.any_context import AnyContext
+from zrb.task.llm.file_tool_model import FileReplacement, FileToRead, FileToWrite
 from zrb.util.file import read_file, read_file_with_line_numbers, write_file
 
-_EXTRACT_INFO_FROM_FILE_SYSTEM_PROMPT = CFG.LLM_FILE_EXTRACTOR_SYSTEM_PROMPT
-
-
 DEFAULT_EXCLUDED_PATTERNS = [
     # Common Python artifacts
     "__pycache__",
@@ -84,26 +82,25 @@ DEFAULT_EXCLUDED_PATTERNS = [
 
 def list_files(
     path: str = ".",
-    recursive: bool = True,
     include_hidden: bool = False,
+    depth: int = 3,
     excluded_patterns: Optional[list[str]] = None,
-) -> str:
+) -> dict[str, list[str]]:
     """
-    Lists the files and directories within a specified path.
+    Lists files recursively up to a specified depth.
 
-    This is a fundamental tool for exploring the file system. Use it to discover the structure of a directory, find specific files, or get a general overview of the project layout before performing other operations.
+    Example:
+    list_files(path='src', include_hidden=False, depth=2)
 
     Args:
-        path (str, optional): The directory path to list. Defaults to the current directory (".").
-        recursive (bool, optional): If True, lists files and directories recursively. If False, lists only the top-level contents. Defaults to True.
-        include_hidden (bool, optional): If True, includes hidden files and directories (those starting with a dot). Defaults to False.
-        excluded_patterns (list[str], optional): A list of glob patterns to exclude from the listing. This is useful for ignoring irrelevant files like build artifacts or virtual environments. Defaults to a standard list of common exclusion patterns.
+        path (str): Directory path. Defaults to current directory.
+        include_hidden (bool): Include hidden files. Defaults to False.
+        depth (int): Maximum depth to traverse. Defaults to 3.
+            Minimum depth is 1 (current directory only).
+        excluded_patterns (list[str]): Glob patterns to exclude.
 
     Returns:
-        str: A JSON string containing a list of file and directory paths relative to the input path.
-             Example: '{"files": ["src/main.py", "README.md"]}'
-    Raises:
-        FileNotFoundError: If the specified path does not exist.
+        dict: {'files': [relative_paths]}
     """
     all_files: list[str] = []
     abs_path = os.path.abspath(os.path.expanduser(path))
@@ -117,50 +114,31 @@ def list_files(
         if excluded_patterns is not None
         else DEFAULT_EXCLUDED_PATTERNS
     )
+    if depth <= 0:
+        depth = 1
     try:
-        if recursive:
-            for root, dirs, files in os.walk(abs_path, topdown=True):
-                # Filter directories in-place
-                dirs[:] = [
-                    d
-                    for d in dirs
-                    if (include_hidden or not _is_hidden(d))
-                    and not is_excluded(d, patterns_to_exclude)
-                ]
-                # Process files
-                for filename in files:
-                    if (include_hidden or not _is_hidden(filename)) and not is_excluded(
-                        filename, patterns_to_exclude
-                    ):
-                        full_path = os.path.join(root, filename)
-                        # Check rel path for patterns like '**/node_modules/*'
-                        rel_full_path = os.path.relpath(full_path, abs_path)
-                        is_rel_path_excluded = is_excluded(
-                            rel_full_path, patterns_to_exclude
-                        )
-                        if not is_rel_path_excluded:
-                            all_files.append(full_path)
-        else:
-            # Non-recursive listing (top-level only)
-            for item in os.listdir(abs_path):
-                full_path = os.path.join(abs_path, item)
-                # Include both files and directories if not recursive
-                if (include_hidden or not _is_hidden(item)) and not is_excluded(
-                    item, patterns_to_exclude
+        initial_depth = abs_path.rstrip(os.sep).count(os.sep)
+        for root, dirs, files in os.walk(abs_path, topdown=True):
+            current_depth = root.rstrip(os.sep).count(os.sep) - initial_depth
+            if current_depth >= depth - 1:
+                del dirs[:]
+            dirs[:] = [
+                d
+                for d in dirs
+                if (include_hidden or not _is_hidden(d))
+                and not is_excluded(d, patterns_to_exclude)
+            ]
+
+            for filename in files:
+                if (include_hidden or not _is_hidden(filename)) and not is_excluded(
+                    filename, patterns_to_exclude
                 ):
-                    all_files.append(full_path)
-        # Return paths relative to the original path requested
-        try:
-            rel_files = [os.path.relpath(f, abs_path) for f in all_files]
-            return json.dumps({"files": sorted(rel_files)})
-        except (
-            ValueError
-        ) as e:  # Handle case where path is '.' and abs_path is CWD root
-            if "path is on mount '" in str(e) and "' which is not on mount '" in str(e):
-                # If paths are on different mounts, just use absolute paths
-                rel_files = all_files
-                return json.dumps({"files": sorted(rel_files)})
-            raise
+                    full_path = os.path.join(root, filename)
+                    rel_full_path = os.path.relpath(full_path, abs_path)
+                    if not is_excluded(rel_full_path, patterns_to_exclude):
+                        all_files.append(rel_full_path)
+        return {"files": sorted(all_files)}
+
     except (OSError, IOError) as e:
         raise OSError(f"Error listing files in {path}: {e}")
     except Exception as e:
@@ -197,97 +175,142 @@ def is_excluded(name: str, patterns: list[str]) -> bool:
 
 
 def read_from_file(
-    path: str,
-    start_line: Optional[int] = None,
-    end_line: Optional[int] = None,
-) -> str:
+    file: FileToRead | list[FileToRead],
+) -> dict[str, Any]:
     """
-    Reads the content of a file, optionally from a specific start line to an end line.
+    Reads content from one or more files, optionally specifying line ranges.
+
+    Examples:
+    # Read entire content of a single file
+    read_from_file(file={'path': 'path/to/file.txt'})
 
-    This tool is essential for inspecting file contents. It can read both text and PDF files. The returned content is prefixed with line numbers, which is crucial for providing context when you need to modify the file later with the `apply_diff` tool.
+    # Read specific lines from a file
+    # The content will be returned with line numbers in the format: "LINE_NUMBER | line content"
+    read_from_file(file={'path': 'path/to/large_file.log', 'start_line': 100, 'end_line': 150})
 
-    Use this tool to:
-    - Examine the source code of a file.
-    - Read configuration files.
-    - Check the contents of a document.
+    # Read multiple files
+    read_from_file(file=[
+        {'path': 'path/to/file1.txt'},
+        {'path': 'path/to/file2.txt', 'start_line': 1, 'end_line': 5}
+    ])
 
     Args:
-        path (str): The path to the file to read.
-        start_line (int, optional): The 1-based line number to start reading from. If omitted, reading starts from the beginning of the file.
-        end_line (int, optional): The 1-based line number to stop reading at (inclusive). If omitted, reads to the end of the file.
+        file (FileToRead | list[FileToRead]): A single file configuration or a list of them.
 
     Returns:
-        str: A JSON object containing the file path, the requested content with line numbers, the start and end lines, and the total number of lines in the file.
-             Example: '{"path": "src/main.py", "content": "1| import os\n2| \n3| print(\"Hello, World!\")", "start_line": 1, "end_line": 3, "total_lines": 3}'
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
+        dict: Content and metadata for a single file, or a dict of results for multiple files.
+        The `content` field in the returned dictionary will have line numbers in the format: "LINE_NUMBER | line content"
     """
-    abs_path = os.path.abspath(os.path.expanduser(path))
-    # Check if file exists
-    if not os.path.exists(abs_path):
-        raise FileNotFoundError(f"File not found: {path}")
-    try:
-        content = read_file_with_line_numbers(abs_path)
-        lines = content.splitlines()
-        total_lines = len(lines)
-        # Adjust line indices (convert from 1-based to 0-based)
-        start_idx = (start_line - 1) if start_line is not None else 0
-        end_idx = end_line if end_line is not None else total_lines
-        # Validate indices
-        if start_idx < 0:
-            start_idx = 0
-        if end_idx > total_lines:
-            end_idx = total_lines
-        if start_idx > end_idx:
-            start_idx = end_idx
-        # Select the lines for the result
-        selected_lines = lines[start_idx:end_idx]
-        content_result = "\n".join(selected_lines)
-        return json.dumps(
-            {
+    is_list = isinstance(file, list)
+    files = file if is_list else [file]
+
+    results = {}
+    for file_config in files:
+        path = file_config["path"]
+        start_line = file_config.get("start_line", None)
+        end_line = file_config.get("end_line", None)
+        try:
+            abs_path = os.path.abspath(os.path.expanduser(path))
+            if not os.path.exists(abs_path):
+                raise FileNotFoundError(f"File not found: {path}")
+
+            content = read_file_with_line_numbers(abs_path)
+            lines = content.splitlines()
+            total_lines = len(lines)
+
+            start_idx = (start_line - 1) if start_line is not None else 0
+            end_idx = end_line if end_line is not None else total_lines
+
+            if start_idx < 0:
+                start_idx = 0
+            if end_idx > total_lines:
+                end_idx = total_lines
+            if start_idx > end_idx:
+                start_idx = end_idx
+
+            selected_lines = lines[start_idx:end_idx]
+            content_result = "\n".join(selected_lines)
+
+            results[path] = {
                 "path": path,
                 "content": content_result,
-                "start_line": start_idx + 1,  # Convert back to 1-based for output
-                "end_line": end_idx,  # end_idx is already exclusive upper bound
+                "start_line": start_idx + 1,
+                "end_line": end_idx,
                 "total_lines": total_lines,
             }
-        )
-    except (OSError, IOError) as e:
-        raise OSError(f"Error reading file {path}: {e}")
-    except Exception as e:
-        raise RuntimeError(f"Unexpected error reading file {path}: {e}")
+        except Exception as e:
+            if not is_list:
+                if isinstance(e, (OSError, IOError)):
+                    raise OSError(f"Error reading file {path}: {e}") from e
+                raise RuntimeError(f"Unexpected error reading file {path}: {e}") from e
+            results[path] = f"Error reading file: {e}"
+
+    if is_list:
+        return results
+
+    return results[files[0]["path"]]
 
 
 def write_to_file(
-    path: str,
-    content: str,
-) -> str:
+    file: FileToWrite | list[FileToWrite],
+) -> str | dict[str, Any]:
     """
-    Writes content to a file, completely overwriting it if it exists or creating it if it doesn't.
-
-    Use this tool to create new files or to replace the entire content of existing files. This is a destructive operation, so be certain of your actions. Always read the file first to understand its contents before overwriting it, unless you are creating a new file.
+    Writes content to one or more files, with options for overwrite, append, or exclusive
+    creation.
+
+    **CRITICAL - PREVENT JSON ERRORS:**
+    1. **ESCAPING:** Do NOT double-escape quotes.
+       - CORRECT: "content": "He said \"Hello\""
+       - WRONG:   "content": "He said \\"Hello\\""  <-- This breaks JSON parsing!
+    2. **SIZE LIMIT:** Content MUST NOT exceed 4000 characters.
+       - Exceeding this causes truncation and EOF errors.
+       - Split larger content into multiple sequential calls (first 'w', then 'a').
+
+    Examples:
+    # Overwrite 'file.txt' with initial content
+    write_to_file(file={'path': 'path/to/file.txt', 'content': 'Initial content.'})
+
+    # Append a second chunk to 'file.txt' (note the newline at the beginning of the content)
+    write_to_file(file={'path': 'path/to/file.txt', 'content': '\nSecond chunk.', 'mode': 'a'})
+
+    # Write to multiple files
+    write_to_file(file=[
+        {'path': 'path/to/file1.txt', 'content': 'Content for file 1'},
+        {'path': 'path/to/file2.txt', 'content': 'Content for file 2', 'mode': 'w'}
+    ])
 
     Args:
-        path (str): The path to the file to write to.
-        content (str): The full, complete content to be written to the file. Do not use partial content or omit any lines.
+        file (FileToWrite | list[FileToWrite]): A single file configuration or a list of them.
 
     Returns:
-        str: A JSON object indicating success or failure.
-             Example: '{"success": true, "path": "new_file.txt"}'
+        Success message for single file, or dict with success/errors for multiple files.
     """
-    try:
-        abs_path = os.path.abspath(os.path.expanduser(path))
-        # Ensure directory exists
-        directory = os.path.dirname(abs_path)
-        if directory and not os.path.exists(directory):
-            os.makedirs(directory, exist_ok=True)
-        write_file(abs_path, content)
-        result_data = {"success": True, "path": path}
-        return json.dumps(result_data)
-    except (OSError, IOError) as e:
-        raise OSError(f"Error writing file {path}: {e}")
-    except Exception as e:
-        raise RuntimeError(f"Unexpected error writing file {path}: {e}")
+    # Normalize to list
+    files = file if isinstance(file, list) else [file]
+
+    success = []
+    errors = {}
+    for file_config in files:
+        path = file_config["path"]
+        content = file_config["content"]
+        mode = file_config.get("mode", "w")
+        try:
+            abs_path = os.path.abspath(os.path.expanduser(path))
+            # The underlying utility creates the directory, so we don't need to do it here.
+            write_file(abs_path, content, mode=mode)
+            success.append(path)
+        except Exception as e:
+            errors[path] = f"Error writing file: {e}"
+
+    # Return appropriate response based on input type
+    if isinstance(file, list):
+        return {"success": success, "errors": errors}
+    else:
+        if errors:
+            raise RuntimeError(
+                f"Error writing file {file['path']}: {errors[file['path']]}"
+            )
+        return f"Successfully wrote to file: {file['path']} in mode '{file.get('mode', 'w')}'"
 
 
 def search_files(
@@ -295,22 +318,21 @@ def search_files(
     regex: str,
     file_pattern: Optional[str] = None,
     include_hidden: bool = True,
-) -> str:
+) -> dict[str, Any]:
     """
-    Searches for a regular expression (regex) pattern within files in a specified directory.
+    Searches for a regex pattern in files within a directory.
 
-    This tool is invaluable for finding specific code, configuration, or text across multiple files. Use it to locate function definitions, variable assignments, error messages, or any other text pattern.
+    Example:
+    search_files(path='src', regex='class \\w+', file_pattern='*.py', include_hidden=False)
 
     Args:
-        path (str): The directory path to start the search from.
-        regex (str): The Python-compatible regular expression pattern to search for.
-        file_pattern (str, optional): A glob pattern to filter which files get searched (e.g., "*.py", "*.md"). If omitted, all files are searched.
-        include_hidden (bool, optional): If True, the search will include hidden files and directories. Defaults to True.
+        path (str): Directory to search.
+        regex (str): Regex pattern.
+        file_pattern (str): Glob pattern filter.
+        include_hidden (bool): Include hidden files.
 
     Returns:
-        str: A JSON object containing a summary of the search and a list of results. Each result includes the file path and a list of matches, with each match showing the line number, line content, and a few lines of context from before and after the match.
-    Raises:
-        ValueError: If the provided `regex` pattern is invalid.
+        dict: Summary and list of matches.
     """
     try:
         pattern = re.compile(regex)
@@ -357,9 +379,7 @@ def search_files(
                 f"Found {match_count} matches in {file_match_count} files "
                 f"(searched {searched_file_count} files)."
             )
-        return json.dumps(
-            search_results
-        )  # No need for pretty printing for LLM consumption
+        return search_results
     except (OSError, IOError) as e:
         raise OSError(f"Error searching files in {path}: {e}")
     except Exception as e:
@@ -367,7 +387,9 @@ def search_files(
 
 
 def _get_file_matches(
-    file_path: str, pattern: re.Pattern, context_lines: int = 2
+    file_path: str,
+    pattern: re.Pattern,
+    context_lines: int = 2,
 ) -> list[dict[str, Any]]:
     """Search for regex matches in a file with context."""
     try:
@@ -398,69 +420,109 @@ def _get_file_matches(
 
 
 def replace_in_file(
-    path: str,
-    old_string: str,
-    new_string: str,
-) -> str:
+    file: FileReplacement | list[FileReplacement],
+) -> str | dict[str, Any]:
     """
-    Replaces the first occurrence of a string in a file.
-
-    This tool is for making targeted modifications to a file. It is a single-step operation that is generally safer and more ergonomic than `write_to_file` for small changes.
+    Replaces exact text in files.
+
+    **CRITICAL INSTRUCTIONS:**
+    1. **READ FIRST:** Use `read_file` to get exact content. Do not guess.
+    2. **EXACT MATCH:** `old_text` must match file content EXACTLY (whitespace, newlines).
+    3. **ESCAPING:** Do NOT double-escape quotes in `new_text`. Use `\"`, not `\\"`.
+    4. **SIZE LIMIT:** `new_text` MUST NOT exceed 4000 chars to avoid truncation/EOF errors.
+    5. **MINIMAL CONTEXT:** Keep `old_text` small (target lines + 2-3 context lines).
+    6. **DEFAULT:** Replaces **ALL** occurrences. Set `count=1` for first occurrence only.
+
+    Examples:
+    # Replace ALL occurrences
+    replace_in_file(file=[
+        {'path': 'file.txt', 'old_text': 'foo', 'new_text': 'bar'},
+        {'path': 'file.txt', 'old_text': 'baz', 'new_text': 'qux'}
+    ])
+
+    # Replace ONLY the first occurrence
+    replace_in_file(
+        file={'path': 'file.txt', 'old_text': 'foo', 'new_text': 'bar', 'count': 1}
+    )
 
-    To ensure the replacement is applied correctly and to avoid ambiguity, the `old_string` parameter should be a unique, multi-line string that includes context from before and after the code you want to change.
+    # Replace code block (include context for safety)
+    replace_in_file(
+        file={
+            'path': 'app.py',
+            'old_text': '    def old_fn():\n        pass',
+            'new_text': '    def new_fn():\n        pass'
+        }
+    )
 
     Args:
-        path (str): The path of the file to modify.
-        old_string (str): The exact, verbatim string to search for and replace. This should be a unique, multi-line block of text.
-        new_string (str): The new string that will replace the `old_string`.
+        file: Single replacement config or list of them.
 
     Returns:
-        str: A JSON object indicating the success or failure of the operation.
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
-        ValueError: If the `old_string` is not found in the file.
+        Success message or error dict.
     """
-    abs_path = os.path.abspath(os.path.expanduser(path))
-    if not os.path.exists(abs_path):
-        raise FileNotFoundError(f"File not found: {path}")
-    try:
-        content = read_file(abs_path)
-        if old_string not in content:
-            raise ValueError(f"old_string not found in file: {path}")
-        new_content = content.replace(old_string, new_string, 1)
-        write_file(abs_path, new_content)
-        return json.dumps({"success": True, "path": path})
-    except ValueError as e:
-        raise e
-    except (OSError, IOError) as e:
-        raise OSError(f"Error applying replacement to {path}: {e}")
-    except Exception as e:
-        raise RuntimeError(f"Unexpected error applying replacement to {path}: {e}")
+    # Normalize to list
+    file_replacements = file if isinstance(file, list) else [file]
+    # Group replacements by file path to minimize file I/O
+    replacements_by_path: dict[str, list[FileReplacement]] = {}
+    for r in file_replacements:
+        path = r["path"]
+        if path not in replacements_by_path:
+            replacements_by_path[path] = []
+        replacements_by_path[path].append(r)
+    success = []
+    errors = {}
+    for path, replacements in replacements_by_path.items():
+        try:
+            abs_path = os.path.abspath(os.path.expanduser(path))
+            if not os.path.exists(abs_path):
+                raise FileNotFoundError(f"File not found: {path}")
+            content = read_file(abs_path)
+            original_content = content
+            # Apply all replacements for this file
+            for replacement in replacements:
+                old_text = replacement["old_text"]
+                new_text = replacement["new_text"]
+                count = replacement.get("count", -1)
+                if old_text not in content:
+                    raise ValueError(f"old_text not found in file: {path}")
+                # Replace occurrences
+                content = content.replace(old_text, new_text, count)
+            # Only write if content actually changed
+            if content != original_content:
+                write_file(abs_path, content)
+                success.append(path)
+            else:
+                success.append(f"{path} (no changes needed)")
+        except Exception as e:
+            errors[path] = f"Error applying replacement to {path}: {e}"
+    # Return appropriate response based on input type
+    if isinstance(file, list):
+        return {"success": success, "errors": errors}
+    path = file["path"]
+    if errors:
+        error_message = errors[path]
+        raise RuntimeError(f"Error applying replacement to {path}: {error_message}")
+    return f"Successfully applied replacement(s) to {path}"
 
 
 async def analyze_file(
     ctx: AnyContext, path: str, query: str, token_limit: int | None = None
-) -> str:
+) -> dict[str, Any]:
     """
-    Performs a deep, goal-oriented analysis of a single file using a sub-agent.
-
-    This tool is ideal for complex questions about a single file that go beyond simple reading or searching. It uses a specialized sub-agent to analyze the file's content in relation to a specific query.
+    Analyzes a file using a sub-agent for complex questions.
 
-    Use this tool to:
-    - Summarize the purpose and functionality of a script or configuration file.
-    - Extract the structure of a file (e.g., "List all the function names in this Python file").
-    - Perform a detailed code review of a specific file.
-    - Answer complex questions like, "How is the 'User' class used in this file?".
+    Example:
+    analyze_file(path='src/main.py', query='Summarize the main function.')
 
     Args:
-        path (str): The path to the file to be analyzed.
-        query (str): A clear and specific question or instruction about what to analyze in the file.
-        token_limit (int, optional): The maximum token length of the file content to be passed to the analysis sub-agent.
+        ctx (AnyContext): The execution context.
+        path (str): The path to the file to analyze.
+        query (str): A specific analysis query with clear guidelines and
+            necessary information.
+        token_limit (int | None): Max tokens.
 
     Returns:
-        str: A detailed, markdown-formatted analysis of the file, tailored to the specified query.
-    Raises:
-        FileNotFoundError: If the specified file does not exist.
+        Analysis results.
     """
     if token_limit is None:
         token_limit = CFG.LLM_FILE_ANALYSIS_TOKEN_LIMIT
@@ -470,71 +532,20 @@ async def analyze_file(
     file_content = read_file(abs_path)
     _analyze_file = create_sub_agent_tool(
         tool_name="analyze_file",
-        tool_description="analyze file with LLM capability",
+        tool_description=(
+            "Analyze file content using LLM sub-agent "
+            "for complex questions about code structure, documentation "
+            "quality, or file-specific analysis. Use for questions that "
+            "require understanding beyond simple text reading."
+        ),
         system_prompt=CFG.LLM_FILE_EXTRACTOR_SYSTEM_PROMPT,
         tools=[read_from_file, search_files],
     )
     payload = json.dumps(
-        {"instruction": query, "file_path": abs_path, "file_content": file_content}
+        {
+            "instruction": query,
+            "file_path": abs_path,
+            "file_content": llm_rate_limitter.clip_prompt(file_content, token_limit),
+        }
     )
-    clipped_payload = llm_rate_limitter.clip_prompt(payload, token_limit)
-    return await _analyze_file(ctx, clipped_payload)
-
-
-def read_many_files(paths: List[str]) -> str:
-    """
-    Reads and returns the full content of multiple files at once.
-
-    This tool is highly efficient for gathering context from several files simultaneously. Use it when you need to understand how different files in a project relate to each other, or when you need to inspect a set of related configuration or source code files.
-
-    Args:
-        paths (List[str]): A list of paths to the files you want to read. It is crucial to provide accurate paths. Use the `list_files` tool first if you are unsure about the exact file locations.
-
-    Returns:
-        str: A JSON object where keys are the file paths and values are their corresponding contents, prefixed with line numbers. If a file cannot be read, its value will be an error message.
-             Example: '{"results": {"src/api.py": "1| import ...", "config.yaml": "1| key: value"}}'
-    """
-    results = {}
-    for path in paths:
-        try:
-            abs_path = os.path.abspath(os.path.expanduser(path))
-            if not os.path.exists(abs_path):
-                raise FileNotFoundError(f"File not found: {path}")
-            content = read_file_with_line_numbers(abs_path)
-            results[path] = content
-        except Exception as e:
-            results[path] = f"Error reading file: {e}"
-    return json.dumps({"results": results})
-
-
-def write_many_files(files: Dict[str, str]) -> str:
-    """
-    Writes content to multiple files in a single, atomic operation.
-
-    This tool is for applying widespread changes to a project, such as creating a set of new files from a template, updating multiple configuration files, or performing a large-scale refactoring.
-
-    Each file's content is completely replaced. If a file does not exist, it will be created. If it exists, its current content will be entirely overwritten. Therefore, you must provide the full, intended content for each file.
-
-    Args:
-        files (Dict[str, str]): A dictionary where keys are the file paths and values are the complete contents to be written to those files.
-
-    Returns:
-        str: A JSON object summarizing the operation, listing successfully written files and any files that failed, along with corresponding error messages.
-             Example: '{"success": ["file1.py", "file2.txt"], "errors": {}}'
-    """
-    success = []
-    errors = {}
-    for path, content in files.items():
-        try:
-            abs_path = os.path.abspath(os.path.expanduser(path))
-            directory = os.path.dirname(abs_path)
-            if directory and not os.path.exists(directory):
-                os.makedirs(directory, exist_ok=True)
-            write_file(abs_path, content)
-            success.append(path)
-        except Exception as e:
-            errors[path] = f"Error writing file: {e}"
-    return json.dumps({"success": success, "errors": errors})
-
-
-apply_diff = replace_in_file
+    return await _analyze_file(ctx, payload)