feat: add enhanced vim mode with cursor shapes and autosuggestion support

Add comprehensive vim mode enhancements including:
- Dynamic cursor shapes (block/beam/underline) for vim modes
- Fish/zsh-style autosuggestion acceptance with 'l' and arrow keys in normal mode
- Vim-style completion navigation (Ctrl+j/k)
- Toggle autocompletion with Ctrl+Space
- Improved key binding documentation in pgclirc

Technical improvements:
- Idempotent setup_vim_cursor_shapes() with guard flag
- Extracted _set_cursor_shape() helper to reduce code duplication
- Fixed string encoding in terminal escape sequences
- Simplified suggestion handlers by removing redundant checks

Author: devadathanmb

pgcli/key_bindings.py

@@ -1,18 +1,77 @@
 import logging
+import sys
 from prompt_toolkit.enums import EditingMode
 from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.key_binding.vi_state import InputMode, ViState
 from prompt_toolkit.filters import (
     completion_is_selected,
     is_searching,
     has_completions,
     has_selection,
     vi_mode,
+    vi_insert_mode,
+    vi_navigation_mode,
 )
 
 from .pgbuffer import buffer_should_be_handled, safe_multi_line_mode
 
 _logger = logging.getLogger(__name__)
 
+# Track whether ViState has been patched to avoid redundant monkeypatching
+_vim_cursor_shapes_configured = False
+
+
+def _set_cursor_shape(shape_code):
+    """
+    Send terminal escape sequence to change cursor shape.
+
+    Args:
+        shape_code: Cursor shape code (1=block, 3=underline, 5=beam)
+    """
+    out = getattr(sys.stdout, 'buffer', sys.stdout)
+    try:
+        # Write escape sequence as bytes
+        out.write(f'\x1b[{shape_code} q'.encode('ascii'))
+        sys.stdout.flush()
+    except (AttributeError, OSError):
+        # Silently ignore if terminal doesn't support cursor shape changes
+        pass
+
+
+def setup_vim_cursor_shapes():
+    """
+    Configure cursor shape changes for vim modes (idempotent).
+
+    Uses terminal escape sequences to change cursor appearance:
+    - Block cursor (█) in navigation/normal mode
+    - Beam cursor (|) in insert mode
+    - Underline cursor (_) in replace mode
+
+    This function can be called multiple times safely - it only patches ViState once.
+    """
+    global _vim_cursor_shapes_configured
+
+    # Only patch ViState once to avoid issues with multiple calls
+    if _vim_cursor_shapes_configured:
+        return
+
+    def set_input_mode(self, mode):
+        # Cursor shape codes: 1=block, 3=underline, 5=beam
+        shape = {
+            InputMode.NAVIGATION: 1,  # Block cursor for normal mode
+            InputMode.REPLACE: 3,      # Underline cursor for replace mode
+            InputMode.INSERT: 5,       # Beam cursor for insert mode
+        }.get(mode, 5)
+
+        _set_cursor_shape(shape)
+        self._input_mode = mode
+
+    # Patch ViState to include cursor shape changes
+    ViState._input_mode = InputMode.INSERT
+    ViState.input_mode = property(lambda self: self._input_mode, set_input_mode)
+
+    _vim_cursor_shapes_configured = True
+
 
 def pgcli_bindings(pgcli):
     """Custom key bindings for pgcli."""
@@ -39,6 +98,11 @@ def _(event):
         pgcli.vi_mode = not pgcli.vi_mode
         event.app.editing_mode = EditingMode.VI if pgcli.vi_mode else EditingMode.EMACS
 
+        if pgcli.vi_mode:
+            setup_vim_cursor_shapes()
+        else:
+            _set_cursor_shape(5)
+
     @kb.add("f5")
     def _(event):
         """Toggle between Vi and Emacs mode."""
@@ -73,21 +137,43 @@ def _(event):
     @kb.add("c-space")
     def _(event):
         """
-        Initialize autocompletion at cursor.
+        Toggle autocompletion at cursor.
 
         If the autocompletion menu is not showing, display it with the
         appropriate completions for the context.
 
-        If the menu is showing, select the next completion.
+        If the menu is showing, close it (toggle off).
         """
         _logger.debug("Detected <C-Space> key.")
 
         b = event.app.current_buffer
         if b.complete_state:
-            b.complete_next()
+            # Close completion menu (toggle off)
+            b.complete_state = None
         else:
+            # Open completion menu (toggle on)
             b.start_completion(select_first=False)
 
+    @kb.add("c-j", filter=has_completions)
+    def _(event):
+        """
+        Navigate to next completion (down) in autocomplete menu.
+
+        Works like Ctrl+n but uses Vim-style j (down) binding.
+        """
+        _logger.debug("Detected <C-j> key.")
+        event.current_buffer.complete_next()
+
+    @kb.add("c-k", filter=has_completions)
+    def _(event):
+        """
+        Navigate to previous completion (up) in autocomplete menu.
+
+        Works like Ctrl+p but uses Vim-style k (up) binding.
+        """
+        _logger.debug("Detected <C-k> key.")
+        event.current_buffer.complete_previous()
+
     @kb.add("enter", filter=completion_is_selected)
     def _(event):
         """Makes the enter key work as the tab key only when showing the menu.
@@ -129,4 +215,49 @@ def _(event):
         """Move down in history."""
         event.current_buffer.history_forward(count=event.arg)
 
+    # Add these bindings with eager=True to take precedence when suggestions are available
+    # This is key for fish/zsh-style autosuggestion acceptance in vim normal mode
+    from prompt_toolkit.filters import Condition
+
+    @Condition
+    def has_suggestion_at_end():
+        """Check if there's a suggestion and cursor is at end of line."""
+        from prompt_toolkit.application.current import get_app
+        app = get_app()
+        buffer = app.current_buffer
+        return (
+            buffer.suggestion is not None
+            and buffer.document.is_cursor_at_the_end_of_line
+        )
+
+    @kb.add("l", filter=vi_navigation_mode & has_suggestion_at_end, eager=True)
+    def _(event):
+        """
+        Accept autosuggestion with 'l' in vi normal mode when at end of line.
+
+        This takes precedence over normal 'l' movement when a suggestion is available.
+        """
+        _logger.debug("Accepting suggestion with 'l' in normal mode")
+        buff = event.current_buffer
+        buff.insert_text(buff.suggestion.text)
+
+    @kb.add("l", filter=vi_navigation_mode, eager=False)
+    def _(event):
+        """Normal 'l' forward movement when no suggestion or not at end."""
+        buff = event.current_buffer
+        buff.cursor_position += buff.document.get_cursor_right_position()
+
+    @kb.add("right", filter=vi_navigation_mode & has_suggestion_at_end, eager=True)
+    def _(event):
+        """Accept autosuggestion with right arrow in vi normal mode when at end of line."""
+        _logger.debug("Accepting suggestion with right arrow in normal mode")
+        buff = event.current_buffer
+        buff.insert_text(buff.suggestion.text)
+
+    @kb.add("right", filter=vi_navigation_mode, eager=False)
+    def _(event):
+        """Normal right arrow forward movement when no suggestion or not at end."""
+        buff = event.current_buffer
+        buff.cursor_position += buff.document.get_cursor_right_position()
+
     return kb

pgcli/main.py

@@ -67,7 +67,7 @@
     get_config,
     get_config_filename,
 )
-from .key_bindings import pgcli_bindings
+from .key_bindings import pgcli_bindings, setup_vim_cursor_shapes
 from .packages.formatter.sqlformatter import register_new_formatter
 from .packages.prompt_utils import confirm, confirm_destructive_query
 from .packages.parseutils import is_destructive
@@ -991,6 +991,10 @@ def handle_watch_command(self, text):
     def _build_cli(self, history):
         key_bindings = pgcli_bindings(self)
 
+        # Setup cursor shape changes for vim mode
+        if self.vi_mode:
+            setup_vim_cursor_shapes()
+
         def get_message():
             if self.dsn_alias and self.prompt_dsn_format is not None:
                 prompt_format = self.prompt_dsn_format

pgcli/pgclirc

@@ -136,6 +136,19 @@ syntax_style = default
 # When Vi mode is enabled you can use modal editing features offered by Vi in the REPL.
 # When Vi mode is disabled emacs keybindings such as Ctrl-A for home and Ctrl-E
 # for end are available in the REPL.
+#
+# Available key bindings:
+#   F2           - Toggle smart completion on/off
+#   F3           - Toggle multiline mode on/off
+#   F4           - Toggle between Vi and Emacs mode
+#   F5           - Toggle EXPLAIN mode on/off
+#   Tab          - Trigger/cycle through completions
+#   Esc          - Close completion menu
+#   Ctrl+Space   - Toggle completion menu on/off
+#   Ctrl+j       - Navigate to next completion (down) - Vim style
+#   Ctrl+k       - Navigate to previous completion (up) - Vim style
+#   Ctrl+p       - Move up in history
+#   Ctrl+n       - Move down in history
 vi = False
 
 # Error handling