feat: Add vim mode plugin with editor state refactoring

- Implement plugin architecture for extensible functionality
- Add full vim mode with motions, operators, text objects, command mode
- Rename vim_mode to editor_mode for clarity (INSERT/NORMAL states)
- Fix default editor mode escape/leader key behavior
- Allow navigation keys (e/q/r) to pass through in vim NORMAL mode

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Jake-Etherflow

sqlit/app.py

@@ -40,6 +40,7 @@
     UIStateMachine,
     get_leader_bindings,
 )
+from .plugins import Plugin, discover_plugins
 from .ui.mixins import (
     AutocompleteMixin,
     ConnectionMixin,
@@ -56,6 +57,7 @@
     ResultsFilterInput,
     SqlitDataTable,
     TreeFilterInput,
+    VimCommandLine,
     VimMode,
 )
 
@@ -112,6 +114,10 @@ class SSMSTUI(
         &:focus > .text-area--cursor-line {
             background: $surface-lighten-1;
         }
+        /* Make visual mode selection more visible with orange tint */
+        & > .text-area--selection {
+            background: $warning 40%;
+        }
     }
 
     DataTable.flash-cell:focus > .datatable--cursor,
@@ -339,7 +345,7 @@ def __init__(
         self.current_config: ConnectionConfig | None = None
         self.current_adapter: DatabaseAdapter | None = None
         self.current_ssh_tunnel: Any | None = None
-        self.vim_mode: VimMode = VimMode.NORMAL
+        self.editor_mode: VimMode = VimMode.INSERT  # Editor state (INSERT=editing, NORMAL=read-only)
         self._expanded_paths: set[str] = set()
         self._loading_nodes: set[str] = set()
         self._session: Any | None = None
@@ -369,6 +375,7 @@ def __init__(
         self._leader_timer: Timer | None = None
         self._leader_pending: bool = False
         self._dialog_open: bool = False
+        self._plugins: list[Plugin] = []  # Loaded plugins
         self._last_active_pane: str | None = None
         self._query_worker: Worker[Any] | None = None
         self._query_executing: bool = False
@@ -534,7 +541,7 @@ def compose(self) -> ComposeResult:
             with Horizontal(id="content"):
                 with Vertical(id="sidebar"):
                     yield TreeFilterInput(id="tree-filter")
-                    tree: Tree[Any] = Tree("Servers", id="object-tree")
+                    tree = Tree("Servers", id="object-tree")
                     tree.show_root = False
                     tree.guide_depth = 2
                     yield tree
@@ -548,6 +555,7 @@ def compose(self) -> ComposeResult:
                             read_only=True,
                         )
                         yield Lazy(AutocompleteDropdown(id="autocomplete-dropdown"))
+                        yield VimCommandLine(id="vim-command-line")
 
                     with Container(id="results-area"):
                         yield ResultsFilterInput(id="results-filter")
@@ -588,6 +596,10 @@ def on_mount(self) -> None:
         self.refresh_tree()
         self._startup_stamp("tree_refreshed")
 
+        # Load and initialize plugins
+        self._load_plugins(settings)
+        self._startup_stamp("plugins_initialized")
+
         self.object_tree.focus()
         self._startup_stamp("tree_focused")
         # Move cursor to first node if available
@@ -614,6 +626,27 @@ def _apply_mock_settings(self, settings: dict) -> None:
             self._mock_profile = mock_profile
             self._session_factory = self._create_mock_session_factory(mock_profile)
 
+    def _load_plugins(self, settings: dict) -> None:
+        """Load and initialize plugins."""
+        for plugin_cls in discover_plugins():
+            plugin = plugin_cls()
+            plugin.register(self)
+            plugin.on_settings_load(self, settings)
+            self._plugins.append(plugin)
+
+    def _get_vim_plugin(self) -> Any:
+        """Get the vim mode plugin if loaded."""
+        for plugin in self._plugins:
+            if plugin.name == "vim_mode":
+                return plugin
+        return None
+
+    @property
+    def vim_enabled(self) -> bool:
+        """Check if vim plugin is enabled (delegates to vim plugin)."""
+        vim_plugin = self._get_vim_plugin()
+        return vim_plugin.enabled if vim_plugin else False
+
     def _setup_startup_connection(self, config: ConnectionConfig) -> None:
         """Set up a startup connection to auto-connect after mount."""
         if not config.name:
@@ -816,3 +849,53 @@ def _apply_omarchy_theme(self) -> None:
         """Match and apply the current Omarchy theme."""
         matched_theme = get_matching_textual_theme(self.available_themes)
         self._apply_theme_safe(matched_theme)
+
+    def on_key(self, event: Any) -> None:
+        """Handle key events, routing through plugins."""
+        from textual.events import Key
+
+        if not isinstance(event, Key):
+            return
+
+        # Only handle keys when query input has focus
+        if not self.query_input.has_focus:
+            return
+
+        # Handle autocomplete navigation when dropdown is visible
+        # Works in INSERT mode (vim enabled) or always when vim is disabled
+        if self._autocomplete_visible and (not self.vim_enabled or self.editor_mode == VimMode.INSERT):
+            dropdown = self.autocomplete_dropdown
+            if event.key in ("down", "ctrl+n"):
+                dropdown.move_selection(1)
+                event.prevent_default()
+                event.stop()
+                return
+            elif event.key in ("up", "ctrl+p"):
+                dropdown.move_selection(-1)
+                event.prevent_default()
+                event.stop()
+                return
+            elif event.key in ("tab", "enter", "return") and dropdown.filtered_items:
+                self._apply_autocomplete()
+                event.prevent_default()
+                event.stop()
+                return
+            elif event.key == "escape":
+                self._hide_autocomplete()
+                event.prevent_default()
+                event.stop()
+                return
+
+        # In default mode NORMAL state, space triggers leader key
+        if not self.vim_enabled and self.editor_mode == VimMode.NORMAL and event.key == "space":
+            self.action_leader_key()
+            event.prevent_default()
+            event.stop()
+            return
+
+        # Route to plugins
+        for plugin in self._plugins:
+            if plugin.on_key(self, event):
+                event.prevent_default()
+                event.stop()
+                return

sqlit/keymap.py

@@ -90,6 +90,7 @@ def get_leader_commands(self) -> list[LeaderCommandDef]:
             # Actions
             LeaderCommandDef("z", "cancel_operation", "Cancel", "Actions", guard="query_executing"),
             LeaderCommandDef("t", "change_theme", "Change Theme", "Actions"),
+            LeaderCommandDef("v", "toggle_vim_mode", "Toggle Vim Mode", "Actions"),
             LeaderCommandDef("h", "show_help", "Help", "Actions"),
             LeaderCommandDef("q", "quit", "Quit", "Actions"),
         ]

sqlit/plugins/__init__.py

@@ -0,0 +1,144 @@
+"""Plugin system for sqlit.
+
+Plugins can extend sqlit with optional features like vim mode.
+Each plugin is a self-contained module that registers hooks with the app.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..app import SSMSTUI
+
+
+@dataclass
+class LeaderCommand:
+    """Definition of a leader command provided by a plugin."""
+
+    key: str  # The key to press (e.g., "v")
+    action: str  # The action name (e.g., "toggle_vim_mode")
+    label: str  # Display label (e.g., "Toggle Vim Mode")
+    category: str  # For grouping in menu ("Actions", "View", etc.)
+    guard: str | None = None  # Optional guard function name
+
+
+class Plugin(ABC):
+    """Base class for sqlit plugins.
+
+    Plugins extend sqlit with optional features. They:
+    - Register themselves with the app at startup
+    - Can intercept and handle key events
+    - Can provide leader commands (<space>+key)
+    - Can persist settings
+    """
+
+    name: str = "unnamed"  # Unique plugin identifier
+
+    @abstractmethod
+    def register(self, app: "SSMSTUI") -> None:
+        """Called when app initializes. Set up the plugin here.
+
+        Args:
+            app: The main application instance
+        """
+        pass
+
+    def on_key(self, app: "SSMSTUI", event: Any) -> bool:
+        """Handle a key event.
+
+        Args:
+            app: The main application instance
+            event: The key event from Textual
+
+        Returns:
+            True if the key was consumed, False to let it propagate
+        """
+        return False
+
+    def on_focus_change(self, app: "SSMSTUI", widget: Any) -> None:
+        """Called when focus changes in the app.
+
+        Args:
+            app: The main application instance
+            widget: The newly focused widget
+        """
+        pass
+
+    def get_leader_commands(self) -> list[LeaderCommand]:
+        """Return leader commands this plugin provides.
+
+        Returns:
+            List of LeaderCommand definitions
+        """
+        return []
+
+    def get_settings_defaults(self) -> dict[str, Any]:
+        """Return default settings for this plugin.
+
+        Returns:
+            Dictionary of setting_name -> default_value
+        """
+        return {}
+
+    def on_settings_load(self, app: "SSMSTUI", settings: dict[str, Any]) -> None:
+        """Called when settings are loaded.
+
+        Args:
+            app: The main application instance
+            settings: The loaded settings dictionary
+        """
+        pass
+
+    def on_settings_save(self, app: "SSMSTUI", settings: dict[str, Any]) -> None:
+        """Called before settings are saved. Modify settings dict to persist plugin state.
+
+        Args:
+            app: The main application instance
+            settings: The settings dictionary to be saved
+        """
+        pass
+
+
+# Plugin registry
+_plugins: list[type[Plugin]] = []
+
+
+def register_plugin(plugin_cls: type[Plugin]) -> type[Plugin]:
+    """Decorator to register a plugin class.
+
+    Usage:
+        @register_plugin
+        class MyPlugin(Plugin):
+            ...
+    """
+    _plugins.append(plugin_cls)
+    return plugin_cls
+
+
+def discover_plugins() -> list[type[Plugin]]:
+    """Discover and return all registered plugin classes.
+
+    This imports plugin modules which triggers their @register_plugin decorators.
+
+    Returns:
+        List of plugin classes
+    """
+    # Import plugin modules to trigger registration
+    try:
+        from . import vim_mode  # noqa: F401
+    except ImportError:
+        pass
+
+    return _plugins.copy()
+
+
+def get_registered_plugins() -> list[type[Plugin]]:
+    """Get already registered plugins without triggering discovery.
+
+    Returns:
+        List of registered plugin classes
+    """
+    return _plugins.copy()

sqlit/plugins/vim_mode/__init__.py

@@ -0,0 +1,13 @@
+"""Vim mode plugin for sqlit.
+
+This plugin provides vim-like keybindings for the query editor.
+Toggle with <space>v. Disabled by default.
+"""
+
+from ..  import register_plugin
+from .plugin import VimModePlugin
+
+# Register the plugin
+register_plugin(VimModePlugin)
+
+__all__ = ["VimModePlugin"]

sqlit/plugins/vim_mode/engine/__init__.py

@@ -0,0 +1,56 @@
+"""Vim emulation engine for sqlit.
+
+This module provides a vim-like editing experience for the query editor,
+inspired by prompt_toolkit's vi implementation but adapted for Textual's TextArea.
+
+Architecture:
+    VimEngine - Main controller that handles key events
+    VimState - Tracks mode, pending operator, registers, etc.
+    DocumentWrapper - Adapts TextArea to vim-style operations
+    VimKeymapConfig - Configurable key bindings
+
+Usage:
+    from sqlit.vim import VimEngine
+
+    engine = VimEngine(text_area)
+    engine.set_mode_callback(on_mode_change)
+
+    # In key handler:
+    result = engine.handle_key(key)
+    if result.consumed:
+        event.prevent_default()
+"""
+
+from .state import VimMode, VimState, TextObjectType
+from .document import DocumentWrapper
+from .engine import VimEngine, KeyResult
+from .keymap import (
+    VimBinding,
+    VimKeymapConfig,
+    VimKeymapProvider,
+    get_vim_keymap,
+    set_vim_keymap,
+)
+from .command import CommandAction, CommandResult, VimCommandHandler
+
+__all__ = [
+    # Core
+    "VimEngine",
+    "VimState",
+    "VimMode",
+    "KeyResult",
+    # Document
+    "DocumentWrapper",
+    # State types
+    "TextObjectType",
+    # Keymap
+    "VimBinding",
+    "VimKeymapConfig",
+    "VimKeymapProvider",
+    "get_vim_keymap",
+    "set_vim_keymap",
+    # Command mode
+    "CommandAction",
+    "CommandResult",
+    "VimCommandHandler",
+]