vmcode-cli 1.0.0

package/src/utils/tools/__init__.py

@@ -0,0 +1,55 @@
+"""Tool execution utilities.
+
+This package provides command execution, file editing, and result formatting
+capabilities for the vmCode AI assistant.
+"""
+
+# Command execution
+from .command_executor import (
+    confirm_tool,
+    run_shell_command,
+)
+# File editing
+from .file_editor import (
+    _resolve_repo_path,
+    preview_edit_file,
+    run_edit_file,
+)
+
+# Result formatting
+from .formatters import (
+    format_tool_result,
+    format_file_result,
+    _build_diff,
+    _detect_newline,
+)
+
+# File operations
+from .directory import list_directory
+from .create_file import create_file
+from .file_reader import read_file
+
+# Tool definitions
+from .definitions import TOOLS, _tools_for_mode
+
+__all__ = [
+    # Command execution
+    'confirm_tool',
+    'run_shell_command',
+    # File editing
+    '_resolve_repo_path',
+    'preview_edit_file',
+    'run_edit_file',
+    # Formatters
+    'format_tool_result',
+    'format_file_result',
+    '_build_diff',
+    '_detect_newline',
+    # File operations
+    'read_file',
+    'list_directory',
+    'create_file',
+    # Tool definitions
+    'TOOLS',
+    '_tools_for_mode',
+]

package/src/utils/tools/command_executor.py

@@ -0,0 +1,217 @@
+"""Command execution via shell (PowerShell on Windows, /bin/sh on Unix/Linux) or direct execution (rg)."""
+
+import subprocess
+import shlex
+import os
+from pathlib import Path
+from rich.panel import Panel
+from llm.config import TOOLS_REQUIRE_CONFIRMATION
+from utils.settings import tool_settings
+from exceptions import CommandExecutionError
+
+from .formatters import format_tool_result
+
+
+def normalize_command(command, rg_exe_path):
+    """Parse command and return (executable, args_list, needs_shell).
+
+    Returns:
+        tuple: (executable_path, args_list, needs_shell)
+            - executable_path: Path object for rg.exe, or None for shell commands
+            - args_list: List of arguments for direct execution, or command string for shell
+            - needs_shell: Boolean indicating if command should run through shell
+    """
+    command = command.strip()
+
+    # Handle rg commands
+    if command.startswith("rg ") or command == "rg":
+        if command == "rg":
+            return rg_exe_path, [], False
+
+        args_str = command[3:].strip()  # Everything after "rg "
+        # Parse only the arguments, not the full command string.
+        # On Windows, posix=False preserves backslashes in paths.
+        use_posix = os.name != "nt"
+        args = shlex.split(args_str, posix=use_posix) if args_str else []
+        args = [arg[1:-1] if len(arg) >= 2 and arg[0] == arg[-1] and arg[0] in ("'", '"') else arg for arg in args]
+        return rg_exe_path, args, False
+
+    # Other commands go through shell
+    return None, command, True
+
+
+def confirm_tool(command, console, reason=None, requires_approval=True, prompt_session=None):
+    """Prompt user for tool execution confirmation.
+
+    Args:
+        command: Command to execute
+        console: Rich console for output
+        reason: Optional reason for requiring confirmation
+        requires_approval: Whether this command specifically requires approval (overrides global flag when True)
+        prompt_session: PromptSession instance for input (optional, for Linux compatibility)
+
+    Returns:
+        tuple: (action, guidance_text) where action is "execute", "reject", or "guide"
+               and guidance_text contains the user's input when action is "guide"
+    """
+    # Skip confirmation only if: global flag is off AND command doesn't require approval
+    if not TOOLS_REQUIRE_CONFIRMATION and not requires_approval:
+        return ("execute", None)
+
+    # Simple title line with tool details
+    console.print("[cyan]───[/][bold white] Tool Confirmation [/][cyan]───[/]")
+    if reason:
+        console.print(f"Tool request: {command}")
+        console.print(f"Details: {reason}")
+    else:
+        console.print(f"Tool request: {command}")
+    console.print("[bold white]Approve tool? (y/n/guidance):[/]")
+
+    try:
+        # Use prompt_session.prompt() if available (for Linux compatibility)
+        if prompt_session:
+            response = prompt_session.prompt("> ").strip()
+        else:
+            response = input("> ").strip()
+    except (EOFError, OSError):
+        # stdin not available - reject command by default
+        console.print("[red]User input not available - command rejected[/red]")
+        return ("reject", None)
+
+    console.print()
+
+    if response.lower() in ("y", "yes"):
+        return ("execute", None)
+    elif response.lower() in ("n", "no"):
+        return ("reject", None)
+    else:
+        return ("guide", response)
+
+
+def _prepare_execution_environment(repo_root, rg_exe_path):
+    """Prepare environment variables for command execution.
+
+    Returns:
+        dict: Environment variables with updated PATH
+    """
+    env = os.environ.copy()
+    rg_parent = Path(rg_exe_path).parent if rg_exe_path else None
+
+    if rg_parent and rg_parent.exists():
+        bin_path = str(rg_parent)
+    else:
+        bin_path = str(repo_root / "bin")
+
+    env["PATH"] = f"{bin_path}{os.pathsep}{env.get('PATH', '')}"
+    return env
+
+
+def _execute_direct_command(cmd_list, repo_root, env, debug_mode, console):
+    """Execute command directly (rg.exe) without PowerShell.
+
+    Returns:
+        subprocess.CompletedProcess
+    """
+    if debug_mode and console:
+        console.print(f"[dim]→ Executing: {cmd_list}[/dim]")
+        console.print(f"[dim]→ Working dir: {repo_root}[/dim]")
+
+    result = subprocess.run(
+        cmd_list,
+        capture_output=True,
+        text=True,
+        encoding='utf-8',
+        errors='replace',
+        timeout=tool_settings.command_timeout_sec,
+        cwd=str(repo_root),
+        env=env,
+    )
+
+    if debug_mode and console:
+        console.print(f"[dim]→ Exit code: {result.returncode}[/dim]")
+
+    return result
+
+
+def _execute_shell_command(command, repo_root, env, debug_mode, console):
+    """Execute command via shell (PowerShell on Windows, /bin/sh on Unix/Linux).
+
+    Returns:
+        subprocess.CompletedProcess
+    """
+    # Detect platform and use appropriate shell
+    is_windows = os.name == 'nt'
+
+    if is_windows:
+        shell_cmd = ["powershell", "-NoProfile", "-NonInteractive", "-Command", str(command)]
+        shell_name = "PowerShell"
+    else:
+        shell_cmd = ["/bin/sh", "-c", str(command)]
+        shell_name = "/bin/sh"
+
+    if debug_mode and console:
+        console.print(f"[dim]→ Executing via {shell_name}: {command}[/dim]")
+        console.print(f"[dim]→ Working dir: {repo_root}[/dim]")
+
+    result = subprocess.run(
+        shell_cmd,
+        capture_output=True,
+        text=True,
+        encoding='utf-8',
+        errors='replace',
+        timeout=tool_settings.command_timeout_sec,
+        cwd=str(repo_root),
+        env=env,
+    )
+
+    if debug_mode and console:
+        console.print(f"[dim]→ Exit code: {result.returncode}[/dim]")
+
+    return result
+
+
+def run_shell_command(command, repo_root, rg_exe_path, console, debug_mode, gitignore_spec=None):
+    """Execute command via rg (direct) or shell (PowerShell on Windows, /bin/sh on Unix/Linux).
+
+    Args:
+        command: Command string to execute
+        repo_root: Path to repository root
+        rg_exe_path: Path to rg.exe
+        console: Rich console for output
+        debug_mode: Whether to show debug output
+
+    Returns:
+        str: Formatted tool result
+
+    Raises:
+        CommandExecutionError: If command execution fails
+    """
+    try:
+        env = _prepare_execution_environment(repo_root, rg_exe_path)
+        executable, args, needs_shell = normalize_command(command, rg_exe_path)
+
+        if not needs_shell:
+            # Direct execution (rg)
+            cmd_list = [str(executable)] + args
+            result = _execute_direct_command(cmd_list, repo_root, env, debug_mode, console)
+            # AI gets truncated results (via format_tool_result); user sees summary via _display_tool_feedback
+            formatted_result = format_tool_result(result, command=command, is_rg=True, debug_mode=True)
+        else:
+            # Shell execution (PowerShell on Windows, /bin/sh on Unix/Linux)
+            result = _execute_shell_command(args, repo_root, env, debug_mode, console)
+            # AI gets full results; user sees summary via _display_tool_feedback
+            formatted_result = format_tool_result(result, command=command, debug_mode=True)
+
+        if debug_mode and console:
+            console.print()
+            console.print(f"[dim]→ AI receives:\n{formatted_result}[/dim]")
+
+        return formatted_result
+    except CommandExecutionError:
+        # Re-raise our custom exceptions
+        raise
+    except Exception as exc:
+        raise CommandExecutionError(
+            f"Command execution failed",
+            details={"command": command, "original_error": str(exc)}
+        )

package/src/utils/tools/create_file.py

@@ -0,0 +1,143 @@
+"""File creation operations."""
+
+import os
+from pathlib import Path
+from typing import Optional, Tuple
+
+from utils.settings import MAX_FILE_PREVIEW_LINES
+from .file_helpers import (
+    _is_fast_ignored,
+    _is_ignored_cached,
+    _register_gitignore_spec,
+    _is_reserved_windows_name
+)
+from .formatters import format_file_result
+
+
+def _validate_create_path(
+    path_str: str,
+    repo_root: Path,
+    gitignore_spec
+) -> Tuple[Optional[Path], Optional[str]]:
+    """Validate and resolve path for file creation.
+
+    Args:
+        path_str: Path string to validate
+        repo_root: Repository root directory
+        gitignore_spec: Optional PathSpec for .gitignore filtering
+
+    Returns:
+        (resolved_path, error_message) - error_message is None if valid
+
+    Checks:
+    - Windows filename validation (invalid chars, reserved names)
+    - Path resolution
+    - Gitignore filtering (only within repo)
+    """
+    try:
+        # Windows validation
+        if os.name == 'nt':
+            invalid_chars = '<>:"|?*'
+            if any(char in path_str for char in invalid_chars):
+                return None, f"Filename contains invalid characters: {invalid_chars}"
+
+            filename = Path(path_str).name
+            if _is_reserved_windows_name(filename):
+                return None, f"Filename is a reserved Windows device name: {filename}"
+
+        # Resolve path
+        raw_path = Path(path_str)
+        if not raw_path.is_absolute():
+            raw_path = repo_root / raw_path
+        resolved = raw_path.resolve()
+
+        # Check gitignore (only applies to paths within repo)
+        if gitignore_spec is not None:
+            if _is_fast_ignored(resolved):
+                return None, f"File blocked by .gitignore: {resolved.relative_to(repo_root)}"
+
+            spec_key = _register_gitignore_spec(gitignore_spec)
+            if _is_ignored_cached(str(resolved), str(repo_root), spec_key):
+                return None, f"File blocked by .gitignore: {resolved.relative_to(repo_root)}"
+
+        return resolved, None
+
+    except Exception as e:
+        return None, str(e)
+
+
+def create_file(
+    path_str: str,
+    repo_root: Path,
+    content: Optional[str] = None,
+    gitignore_spec = None
+) -> str:
+    """Create a new file with optional initial content.
+
+    Creates a new file at the specified path, creating parent directories
+    if needed. The file must not already exist. Respects .gitignore.
+
+    Args:
+        path_str: Path string to the file to create
+        repo_root: Repository root directory (for path resolution)
+        content: Optional initial content for the file. If omitted, creates empty file.
+        gitignore_spec: Optional PathSpec for .gitignore filtering
+
+    Returns:
+        str: Formatted result with exit_code and status, including preview
+    """
+    try:
+        # Validate path
+        resolved, error = _validate_create_path(path_str, repo_root, gitignore_spec)
+        if error:
+            return format_file_result(exit_code=1, error=error, path=path_str)
+
+        # Check if already exists
+        if resolved.exists():
+            return format_file_result(
+                exit_code=1,
+                error="File already exists",
+                path=str(resolved.relative_to(repo_root))
+            )
+
+        # Create parent directories if needed
+        parent_dir = resolved.parent
+        if parent_dir != repo_root and not parent_dir.exists():
+            parent_dir.mkdir(parents=True, exist_ok=True)
+
+        # Write content or create empty file
+        if content is not None:
+            resolved.write_text(content, encoding="utf-8", newline="")
+        else:
+            content = ""
+            resolved.touch()
+
+        # Build result with content for display (truncate preview if needed)
+        result_lines = []
+        result_lines.append(f"exit_code=0")
+        result_lines.append(f"path={resolved.relative_to(repo_root)}")
+        result_lines.append(f"content=File created successfully")
+        result_lines.append("")
+        result_lines.append(f"=== FILE_CONTENT ===")
+
+        # Truncate content for preview if it exceeds max lines
+        if content:
+            content_lines = content.splitlines(keepends=True)
+            if len(content_lines) > MAX_FILE_PREVIEW_LINES:
+                truncated_content = "".join(content_lines[:MAX_FILE_PREVIEW_LINES])
+                omitted = len(content_lines) - MAX_FILE_PREVIEW_LINES
+                result_lines.append(truncated_content)
+                result_lines.append(f"\n... ({omitted} more lines omitted from preview)")
+            else:
+                result_lines.append(content)
+
+        result_lines.append("=== END_FILE_CONTENT ===")
+
+        return "\n".join(result_lines) + "\n\n"
+
+    except PermissionError:
+        return format_file_result(exit_code=1, error="Permission denied", path=path_str)
+    except OSError as e:
+        return format_file_result(exit_code=1, error=f"Invalid filename: {e}", path=path_str)
+    except Exception as e:
+        return format_file_result(exit_code=1, error=str(e), path=path_str)

package/src/utils/tools/definitions.py

@@ -0,0 +1,193 @@
+"""Tool definitions for OpenAI-style function calling.
+
+This module contains the schema definitions for all available tools,
+and utilities to filter them based on interaction mode.
+"""
+
+# Tool definition for OpenAI-style function calling
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "rg",
+            "description": "A powerful search tool built on ripgrep. Works on any directory in the filesystem.\n\n**Usage:**\n- ALWAYS use rg for search tasks. NEVER invoke `grep` or `rg` as a shell command. The rg tool has been optimized for correct permissions and access.\n- Supports full regex syntax (e.g., \"log.*Error\", \"function\\s+\\w+\")\n- Filter files with glob parameter (e.g., \"*.js\", \"**/*.tsx\") or type parameter (e.g., \"js\", \"py\", \"rust\")\n- Output modes: \"content\" shows matching lines, \"files_with_matches\" shows only file paths (default), \"count\" shows match counts\n- Use sub_agent tool for open-ended searches requiring multiple rounds\n- Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)\n- Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \\{[\\s\\S]*?field`, use `multiline: true`",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string", "description": "The regular expression pattern to search for in file contents"},
+                    "path": {"type": "string", "description": "File or directory to search in (rg PATH). Defaults to current working directory. Works anywhere on the filesystem."},
+                    "glob": {"type": "string", "description": "Glob pattern to filter files (e.g. \"*.js\", \"*.{ts,tsx}\") - maps to rg --glob"},
+                    "output_mode": {"type": "string", "enum": ["content", "files_with_matches", "count"], "description": "Output mode: \"content\" shows matching lines (supports -B/-A/-C context, -n line numbers), \"files_with_matches\" shows file paths, \"count\" shows match counts. Defaults to \"files_with_matches\"."},
+                    "-B": {"type": "number", "description": "Number of lines to show before each match (rg -B). Requires output_mode: \"content\", ignored otherwise."},
+                    "-A": {"type": "number", "description": "Number of lines to show after each match (rg -A). Requires output_mode: \"content\", ignored otherwise."},
+                    "-C": {"type": "number", "description": "Number of lines to show before and after each match (rg -C). Requires output_mode: \"content\", ignored otherwise."},
+                    "-n": {"type": "boolean", "description": "Show line numbers in output (rg -n). Requires output_mode: \"content\", ignored otherwise."},
+                    "-i": {"type": "boolean", "description": "Case insensitive search (rg -i)"},
+                    "type": {"type": "string", "description": "File type to search (rg --type). Common types: js, py, rust, go, java, etc. More efficient than include for standard file types."},
+                    "multiline": {"type": "boolean", "description": "Enable multiline mode where . matches newlines and patterns can span lines (rg -U --multiline-dotall). Default: false."}
+                },
+                "required": ["pattern"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_command",
+            "description": "Execute shell commands for git, system tasks, debugging, and file operations.\n\n**Use for:**\n- Git operations: git clone, pull, push, status, etc.\n- System debugging: ps, lsof, netstat, journalctl, systemctl\n- File operations: rm, mv, cp, mkdir (system-wide)\n- Network tools: ping, curl, wget, ssh\n- Package management: pacman, pip, npm, apt\n- Path navigation: cd /path && command (use && for chaining)\n\n**Important:**\n- All commands execute from repository root\n- Use && for conditional chaining (stops on error)\n- Absolute paths allowed for system debugging\n\n**Do NOT use for:**\n- Code search (use rg tool)\n- Reading files (use read_file)\n- Listing directories (use list_directory)\n- Creating/editing files (use create_file/edit_file)\n- NO chaining with ;, |, >, <, ` (only && allowed)",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {"type": "string", "description": "Command to execute. Examples: 'git status', 'ps aux', 'cd /var/log && tail -f syslog'"}
+                },
+                "required": ["command"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read file contents using Python file reader. Use this to view a file (or a specific line range). Prefer this over rg when you already know the file path. Works on any file in the filesystem.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to read (works anywhere on filesystem)"},
+                    "max_lines": {"type": "integer", "description": "Max lines to read (omit for full file)"},
+                    "start_line": {"type": "integer", "description": "1-based starting line number (default: 1). Use with max_lines to read a specific excerpt."}
+                },
+                "required": ["path"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_directory",
+            "description": "List directory contents using Python file lister (preferred over PowerShell). Works on any directory in the filesystem.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to list (default: '.', works anywhere on filesystem)"},
+                    "recursive": {"type": "boolean", "description": "List recursively (default: false)"},
+                    "show_files": {"type": "boolean", "description": "Include files (default: true)"},
+                    "show_dirs": {"type": "boolean", "description": "Include directories (default: true)"},
+                    "pattern": {"type": "string", "description": "Glob pattern to filter results (e.g., \"*.py\")"}
+                },
+                "required": ["path"]
+            }
+        }
+    },
+        {
+            "type": "function",
+            "function": {
+            "name": "create_file",
+            "description": "Create a new file with optional initial content. File must not exist. For small files, include content directly. Creates a preview of the written content (up to 200 lines) with syntax highlighting. Works on any path in the filesystem.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to create (works anywhere on filesystem)"},                        "content": {"type": "string", "description": "Initial content (omit for empty file)"}
+                    },
+                    "required": ["path"]
+                }
+            }
+        },    {
+        "type": "function",
+        "function": {
+            "name": "edit_file",
+            "description": "Apply search/replace edit to file. Search text must appear exactly once. Works on any file in the filesystem.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Path to edit (works anywhere on filesystem)"},
+                    "search": {"type": "string", "description": "Exact text to find. Must be unique. Include context. Multi-line supported."},
+                    "replace": {"type": "string", "description": "Replacement text. Multi-line supported."},
+                    "context_lines": {"type": "integer", "description": "Context lines in diff (default: 3)"},
+                    "color": {"type": "string", "description": "Color mode: 'auto', 'on', 'off' (default: 'auto')"}
+                },
+                "required": ["path", "search", "replace"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "web_search",
+            "description": "Search web for info, docs, current events using DuckDuckGo (no API key needed).",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query to execute"},
+                    "num_results": {"type": "integer", "description": "Results to return (default: 5, max: 10)"}
+                },
+                "required": ["query"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "sub_agent",
+            "description": "MANDATORY: MUST CALL THIS FIRST before ANY rg or read_file when answering: 'how something works', architecture, patterns, multi-file flows, or broad exploration. DO NOT search manually - this tool is 10x faster. Examples: 'How does authentication work?', 'Explain the data flow', 'Where is X handled?'",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Task query, e.g. 'How does the chat manager handle history?'"}
+                },
+                "required": ["query"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "create_task_list",
+            "description": "Create or replace an in-session task list for tracking long EDIT workflows.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "tasks": {"type": "array", "items": {"type": "string"}, "description": "Task descriptions. Non-empty after trimming."},
+                    "title": {"type": "string", "description": "Optional short title for the task list."}
+                },
+                "required": ["tasks"]
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "complete_task",
+            "description": "Mark one or more tasks complete in the current in-session task list.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "integer", "description": "Zero-based index of a single task to mark complete."},
+                    "task_ids": {"type": "array", "items": {"type": "integer"}, "description": "Array of zero-based task indices to mark complete."}
+                }
+            }
+        }
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "show_task_list",
+            "description": "Show the current in-session task list without modifying it.",
+            "parameters": {"type": "object", "properties": {}}
+        }
+    }
+]
+
+
+def _tools_for_mode(interaction_mode):
+    """Filter tools based on interaction mode.
+
+    Args:
+        interaction_mode: 'plan', 'edit', or 'learn'
+
+    Returns:
+        List of tool definitions suitable for the mode
+    """
+    if interaction_mode in ("learn", "plan"):
+        allowed = {"rg", "read_file", "list_directory", "sub_agent", "web_search"}
+        return [tool for tool in TOOLS if tool["function"]["name"] in allowed]
+    return TOOLS