swarm_cli 2.1.13 → 3.0.0.alpha2

data/lib/swarm_cli/v3/command_completer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module V3
+    # Command completion logic for slash commands.
+    #
+    # CommandCompleter provides methods to extract command targets from text buffers
+    # and find matching slash commands. It has no knowledge of the UI or display.
+    #
+    # @example Extracting command word
+    #   buffer = "/mem"
+    #   cursor = 4  # After "mem"
+    #   result = CommandCompleter.extract_command_word(buffer, cursor)
+    #   # => ["", "/mem", ""]
+    #
+    # @example Finding matches
+    #   matches = CommandCompleter.find_matches("/mem")
+    #   # => ["/memory"]
+    class CommandCompleter
+      # Available slash commands
+      COMMANDS = [
+        "/clear",
+        "/memory",
+        "/defrag",
+        "/queue",
+        "/reboot",
+        "/exit",
+        "/quit",
+      ].freeze
+
+      class << self
+        # Extract the command at cursor position.
+        #
+        # Searches backward from cursor to find a `/` at the start of the line,
+        # then extracts from that `/` to the cursor position.
+        #
+        # @param buffer [String] the full text buffer
+        # @param cursor [Integer] the cursor position (0-based index)
+        #
+        # @return [Array<String>, nil] [pre, target, post] or nil if no / found
+        #   - pre: text before the /
+        #   - target: the / and characters up to cursor
+        #   - post: text after cursor
+        #
+        # @example Cursor at end of command
+        #   extract_command_word("/mem", 4)
+        #   # => ["", "/mem", ""]
+        #
+        # @example Cursor in middle of command
+        #   extract_command_word("/memory", 4)
+        #   # => ["", "/mem", "ory"]
+        #
+        # @example No / at start of line
+        #   extract_command_word("check /mem", 10)
+        #   # => nil (slash not at start)
+        def extract_command_word(buffer, cursor)
+          # Command must be at start of line
+          return unless buffer.start_with?("/")
+
+          # Find end of command after cursor (next space or end of buffer)
+          target_end = cursor
+          target_end += 1 while target_end < buffer.length && buffer[target_end] !~ /\s/
+
+          pre = ""
+          target = buffer[0...cursor]
+          post = buffer[cursor...target_end] || ""
+
+          [pre, target, post]
+        end
+
+        # Find matching commands for a query (with / prefix).
+        #
+        # @param target [String] the search target (must start with /)
+        # @param max [Integer] maximum number of results to return
+        # @param skills [Array<String>] additional skill names to include
+        #
+        # @return [Array<String>] array of matching commands (with / prefix)
+        #
+        # @example Exact match
+        #   find_matches("/clear")
+        #   # => ["/clear"]
+        #
+        # @example Prefix match
+        #   find_matches("/me")
+        #   # => ["/memory"]
+        #
+        # @example With skills
+        #   find_matches("/an", skills: ["analyze", "annotate"])
+        #   # => ["/analyze", "/annotate"]
+        #
+        # @example Multiple matches
+        #   find_matches("/")
+        #   # => ["/clear", "/memory", "/defrag", "/queue", "/reboot"]
+        def find_matches(target, max: 5, skills: [])
+          return [] unless target.start_with?("/")
+
+          query = target.downcase
+
+          # Combine built-in commands with skill names
+          skill_commands = skills.map { |name| "/#{name}" }
+          all_commands = COMMANDS + skill_commands
+
+          # Find commands that start with the query
+          matches = all_commands.select { |cmd| cmd.downcase.start_with?(query) }
+
+          # Sort by length (shorter = more specific)
+          matches.sort_by(&:length).first(max)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_cli/v3/display.rb

@@ -0,0 +1,607 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module V3
+    # Mutex-protected coordinator for terminal output.
+    #
+    # Owns a {TextInput} and an {ActivityIndicator}, and ensures all screen
+    # writes are serialized so agent events and user keystrokes never visually
+    # collide. The input line (prompt + buffer) is always visible at the bottom;
+    # agent output "slides in" above it.
+    #
+    # The footer is composed of (top to bottom):
+    #   1. Optional working indicator (blank line + "Working..." line)
+    #   2. Horizontal separator
+    #   3. Prompt line (may wrap and span multiple lines)
+    class Display
+      # @return [TextInput] the text input model (read-only access for reader)
+      attr_reader :text_input
+
+      # @param io [IO] output stream (defaults to $stdout, use StringIO for tests)
+      # @param width [Integer, nil] terminal width override (nil = auto-detect)
+      def initialize(io: $stdout, width: nil)
+        @io = io
+        @width_override = width
+        @mutex = Mutex.new
+        @active = false
+        @text_input = TextInput.new
+        @indicator = ActivityIndicator.new(on_tick: -> { tick })
+        # Tracks which row of the prompt area the terminal cursor is on
+        # (0 = first line of prompt, relative to prompt start).
+        # Used by reposition_cursor to navigate from current position.
+        @terminal_cursor_row = 0
+        @hint_message = nil
+        @hint_timer = nil
+        @status_message = nil # Persistent status message
+        @dropdown = nil # Dropdown instance when autocomplete is active
+      end
+
+      # Start showing the input footer.
+      #
+      # @return [void]
+      def activate
+        @mutex.synchronize do
+          @active = true
+          redraw_footer
+        end
+      end
+
+      # Stop showing the input footer and clear it from the screen.
+      #
+      # @return [void]
+      def deactivate
+        @mutex.synchronize do
+          return unless @active
+
+          clear_footer
+          @active = false
+        end
+      end
+
+      # Signal that the agent is working.
+      #
+      # @return [void]
+      def start_working
+        @mutex.synchronize do
+          if @active
+            clear_footer
+            @indicator.start
+            redraw_footer
+          else
+            @indicator.start
+          end
+        end
+      end
+
+      # Update the activity indicator status suffix.
+      #
+      # @param text [String, nil] status text to show
+      # @return [void]
+      def update_activity(text)
+        @mutex.synchronize do
+          return unless @indicator.working?
+
+          @indicator.status = text
+        end
+      end
+
+      # Signal that the agent has finished working.
+      #
+      # @return [void]
+      def stop_working
+        @mutex.synchronize do
+          return unless @indicator.working?
+
+          clear_footer if @active
+          @indicator.stop
+          redraw_footer if @active
+        end
+      end
+
+      # Echo a typed character at the cursor position.
+      #
+      # @param char [String] single character
+      # @return [void]
+      def type_char(char)
+        @mutex.synchronize do
+          old_lines = @text_input.wrapped_lines(terminal_width)
+          @text_input.type_char(char)
+
+          # Always redraw to ensure bottom separator is present
+          redraw_prompt_with_separator_from(old_lines)
+        end
+      end
+
+      # Handle a backspace keypress.
+      #
+      # @return [void]
+      def backspace
+        @mutex.synchronize do
+          old_lines = @text_input.wrapped_lines(terminal_width)
+          @text_input.backspace
+
+          # Always redraw to ensure bottom separator is present
+          redraw_prompt_with_separator_from(old_lines)
+        end
+      end
+
+      # Move cursor left.
+      #
+      # @return [void]
+      def move_left
+        @mutex.synchronize do
+          @text_input.move_left
+          reposition_cursor
+        end
+      end
+
+      # Move cursor right.
+      #
+      # @return [void]
+      def move_right
+        @mutex.synchronize do
+          @text_input.move_right
+          reposition_cursor
+        end
+      end
+
+      # Move cursor up one line within multiline buffer.
+      #
+      # @return [Boolean] true if cursor moved, false if already on first line
+      def move_up
+        @mutex.synchronize do
+          old = @text_input.cursor
+          @text_input.move_up
+          moved = @text_input.cursor != old
+          reposition_cursor if moved
+          moved
+        end
+      end
+
+      # Move cursor down one line within multiline buffer.
+      #
+      # @return [Boolean] true if cursor moved, false if already on last line
+      def move_down
+        @mutex.synchronize do
+          old = @text_input.cursor
+          @text_input.move_down
+          moved = @text_input.cursor != old
+          reposition_cursor if moved
+          moved
+        end
+      end
+
+      # Finalize the current input line and return the buffer text.
+      #
+      # @return [String] the submitted text
+      def enter
+        @mutex.synchronize do
+          line = @text_input.submit
+          clear_footer if @active
+          write("#{@text_input.render}#{line}\n")
+          redraw_footer if @active
+          flush
+          line
+        end
+      end
+
+      # Replace the buffer contents (for history navigation).
+      #
+      # @param text [String, nil] replacement text
+      # @return [void]
+      def replace_buffer(text)
+        @mutex.synchronize do
+          old_lines = @text_input.wrapped_lines(terminal_width)
+          @text_input.replace(text)
+          redraw_prompt_with_separator_from(old_lines) if @active
+        end
+      end
+
+      # Clear the input buffer (for double-ESC).
+      #
+      # @return [void]
+      def clear_input
+        @mutex.synchronize do
+          old_lines = @text_input.wrapped_lines(terminal_width)
+          @text_input.replace("")
+          @hint_message = nil # Clear hint directly
+          clear_hint_timer
+          redraw_prompt_with_separator_from(old_lines) if @active
+        end
+      end
+
+      # Show a temporary hint message below the input area.
+      #
+      # @param message [String] the hint text to display
+      # @param duration [Float] seconds to show the hint (default 1.5)
+      # @return [void]
+      def show_hint(message, duration: 1.5)
+        @mutex.synchronize do
+          clear_hint_timer
+          @hint_message = message
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+
+          @hint_timer = Thread.new do
+            sleep(duration)
+            @mutex.synchronize do
+              @hint_message = nil
+              @hint_timer = nil
+
+              if @active
+                old_lines = @text_input.wrapped_lines(terminal_width)
+                redraw_prompt_with_separator_from(old_lines)
+              end
+            end
+          end
+        end
+      end
+
+      # Clear the hint message immediately.
+      #
+      # @return [void]
+      def clear_hint
+        return unless @hint_message
+
+        clear_hint_timer
+        @hint_message = nil
+
+        if @active
+          old_lines = @text_input.wrapped_lines(terminal_width)
+          redraw_prompt_with_separator_from(old_lines)
+        end
+      end
+
+      # Show a persistent status message in the status area.
+      # Unlike hints, status messages don't auto-clear.
+      #
+      # @param message [String] the status text to display
+      # @return [void]
+      def show_status(message)
+        @mutex.synchronize do
+          @status_message = message
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+        end
+      end
+
+      # Clear the persistent status message.
+      #
+      # @return [void]
+      def clear_status
+        return unless @status_message
+
+        @status_message = nil
+
+        if @active
+          old_lines = @text_input.wrapped_lines(terminal_width)
+          redraw_prompt_with_separator_from(old_lines)
+        end
+      end
+
+      # Show dropdown in status area.
+      #
+      # @param dropdown [Dropdown] the dropdown to display
+      # @return [void]
+      def show_dropdown(dropdown)
+        @mutex.synchronize do
+          @dropdown = dropdown
+          @hint_message = nil    # Clear hints when dropdown shows
+          @status_message = nil  # Clear status when dropdown shows
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+        end
+      end
+
+      # Navigate dropdown selection to next item.
+      #
+      # @return [void]
+      def dropdown_select_next
+        @mutex.synchronize do
+          return unless @dropdown
+
+          @dropdown.select_next
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+        end
+      end
+
+      # Navigate dropdown selection to previous item.
+      #
+      # @return [void]
+      def dropdown_select_previous
+        @mutex.synchronize do
+          return unless @dropdown
+
+          @dropdown.select_previous
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+        end
+      end
+
+      # Get selected item and close dropdown.
+      #
+      # @return [String, nil] the selected item or nil if no dropdown active
+      def dropdown_accept
+        @mutex.synchronize do
+          return unless @dropdown
+
+          selected = @dropdown.selected_item
+          @dropdown = nil
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+
+          selected
+        end
+      end
+
+      # Get first item and close dropdown (for Tab behavior).
+      #
+      # @return [String, nil] the first item or nil if no dropdown active
+      def dropdown_accept_first
+        @mutex.synchronize do
+          return unless @dropdown
+
+          first = @dropdown.first_item
+          @dropdown = nil
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+
+          first
+        end
+      end
+
+      # Close dropdown without selection.
+      #
+      # @return [void]
+      def dropdown_close
+        @mutex.synchronize do
+          return unless @dropdown
+
+          @dropdown = nil
+
+          if @active
+            old_lines = @text_input.wrapped_lines(terminal_width)
+            redraw_prompt_with_separator_from(old_lines)
+          end
+        end
+      end
+
+      # Check whether dropdown is active.
+      #
+      # @return [Boolean] true if dropdown is shown
+      def dropdown_active?
+        @mutex.synchronize { !@dropdown.nil? }
+      end
+
+      # Return a copy of the current input buffer (thread-safe).
+      #
+      # @return [String]
+      def current_buffer
+        @mutex.synchronize { @text_input.buffer.dup }
+      end
+
+      # Print agent output above the always-visible footer.
+      #
+      # @param text [String] output text to display
+      # @return [void]
+      def agent_print(text)
+        @mutex.synchronize do
+          if @active
+            clear_footer
+            write(text)
+            write("\n") unless text.end_with?("\n")
+            redraw_footer
+          else
+            write(text)
+            write("\n") unless text.end_with?("\n")
+          end
+          flush
+        end
+      end
+
+      private
+
+      # Called by the ActivityIndicator ticker thread.
+      def tick
+        @mutex.synchronize do
+          return unless @indicator.working? && @active
+
+          clear_footer
+          redraw_footer
+        end
+      end
+
+      def terminal_width
+        @width_override || IO.console&.winsize&.last || 80
+      end
+
+      def cursor_at_end?
+        @text_input.cursor == @text_input.buffer.length
+      end
+
+      # Clear the entire footer from the screen.
+      # Navigates from the tracked cursor row, not from an assumed position.
+      def clear_footer
+        width = terminal_width
+        @text_input.wrapped_lines(width)
+
+        # From current cursor row, move up to start of indicator/separator area
+        # @terminal_cursor_row is the line within the text input (0 = first line)
+        # We need to move up (cursor_row + 1) to reach the top separator
+        lines_above_cursor = @terminal_cursor_row + 1
+        lines_above_cursor += @indicator.footer_lines
+        lines_above_cursor += status_area_lines # Account for status area if shown
+
+        lines_above_cursor.times { write("\e[A") }
+        write("\r\e[J")
+        @terminal_cursor_row = 0
+      end
+
+      # Redraw the full footer: indicator, top separator, prompt, bottom separator, status area, then position cursor.
+      def redraw_footer
+        indicator_line = @indicator.render
+        write(indicator_line) if indicator_line
+        write_separator
+        write(@text_input.render)
+        write_bottom_separator
+        write_status_area
+        place_cursor
+        flush
+      end
+
+      # Redraw just the prompt line (single-line, cursor at end).
+      def redraw_prompt_line
+        write("\r\e[K#{@text_input.render}")
+        write_bottom_separator
+        place_cursor
+        flush
+      end
+
+      # Redraw separator + prompt area using a pre-captured line count.
+      #
+      # @param old_prompt_lines [Integer] number of wrapped lines before the change
+      # @param had_hint [Boolean] whether a hint was shown in the previous display (unused, kept for compatibility)
+      def redraw_prompt_with_separator_from(old_prompt_lines, had_hint: false)
+        # Navigate up from tracked cursor position to top separator
+        # @terminal_cursor_row is 0 for first line of input, 1 for second line, etc.
+        # We need to move up (cursor_row + 1) to reach the top separator
+        # The status area is BELOW the cursor, so it doesn't affect upward navigation
+        up = @terminal_cursor_row + 1
+        up.times { write("\e[A") }
+        write("\r\e[J")
+        write_separator
+        write(@text_input.render)
+        write_bottom_separator
+        write_status_area
+        place_cursor
+        flush
+      end
+
+      def write_separator
+        write(ANSIColors.dim("\u{2500}" * terminal_width))
+        write("\n")
+      end
+
+      def write_bottom_separator
+        write("\n")
+        write(ANSIColors.dim("\u{2500}" * terminal_width))
+      end
+
+      # Write the status area (dropdown, hints, or persistent status).
+      # Dropdown takes priority, then hints, then status messages.
+      def write_status_area
+        if @dropdown
+          # Render dropdown (multiple lines)
+          @dropdown.render.each do |line|
+            write("\n")
+            write(line)
+          end
+        elsif @hint_message
+          write("\n")
+          write(ANSIColors.dim(@hint_message))
+        elsif @status_message
+          write("\n")
+          write(ANSIColors.italic(@status_message))
+        end
+      end
+
+      # Count how many lines the status area occupies
+      def status_area_lines
+        if @dropdown
+          @dropdown.render.size
+        elsif @hint_message || @status_message
+          1
+        else
+          0
+        end
+      end
+
+      def clear_hint_timer
+        return unless @hint_timer
+
+        @hint_timer.kill
+        @hint_timer = nil
+      end
+
+      # Position the terminal cursor at the TextInput cursor location
+      # and update @terminal_cursor_row tracking.
+      #
+      # After rendering, terminal cursor is at the end of the bottom separator line (or status area if shown).
+      # We need to move up to the correct position in the text input.
+      def place_cursor
+        width = terminal_width
+        extra_lines = @text_input.wrapped_lines(width)
+        cursor_row, cursor_col = @text_input.cursor_position(width)
+
+        # wrapped_lines returns EXTRA lines from wrapping (0 for single line)
+        # Total terminal lines = extra_lines + 1 (for the base line)
+        # We're on the separator line (or status area), need to move up to cursor_row
+        # From separator/status to last text line = 1 line up (+ status_area_lines if shown)
+        # From last text line to cursor_row = (extra_lines - cursor_row) lines up
+        up = (extra_lines - cursor_row) + 1
+        up += status_area_lines # Extra lines for status area
+        up.times { write("\e[A") } if up > 0
+
+        # Move to cursor column
+        write("\r")
+        write("\e[#{cursor_col}C") if cursor_col > 0
+
+        @terminal_cursor_row = cursor_row
+      end
+
+      # Reposition cursor for arrow key movement (no content change).
+      # Uses tracked @terminal_cursor_row to navigate from current position.
+      def reposition_cursor
+        width = terminal_width
+        return if width <= 0
+
+        cursor_row, cursor_col = @text_input.cursor_position(width)
+
+        # Navigate from current row to target row
+        row_delta = cursor_row - @terminal_cursor_row
+        if row_delta < 0
+          (-row_delta).times { write("\e[A") }
+        elsif row_delta > 0
+          row_delta.times { write("\e[B") }
+        end
+
+        # Move to cursor column
+        write("\r")
+        write("\e[#{cursor_col}C") if cursor_col > 0
+
+        @terminal_cursor_row = cursor_row
+        flush
+      end
+
+      def write(text)
+        @io.write(text)
+      end
+
+      def flush
+        @io.flush
+      end
+    end
+  end
+end