kward 0.71.0 → 0.72.0

data/lib/kward/prompt_interface/file_overlay.rb

@@ -0,0 +1,211 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # File-mention completion overlay behavior.
+  class PromptInterface
+    # Composer @file mention overlay support.
+    module FileOverlay
+      private
+
+      FILE_MENTION_RESULT_LIMIT = 200
+
+      def reset_file_selection
+        @file_selection_index = 0
+      end
+
+      def dismiss_file_overlay
+        return false unless file_overlay_visible?
+
+        if file_open_overlay_visible?
+          @file_open_dismissed_token = active_file_open_token
+          @file_editor_open_status = nil
+        else
+          @file_overlay_dismissed_token = active_file_mention_token
+        end
+        reset_file_selection
+        true
+      end
+
+      def file_overlay_visible?
+        file_open_overlay_visible? || file_mention_overlay_visible?
+      end
+
+      def file_mention_overlay_visible?
+        token = active_file_mention_token
+        return false unless token
+        return false if @file_overlay_dismissed_token == token
+
+        true
+      end
+
+      def file_open_overlay_visible?
+        token = active_file_open_token
+        return false unless token
+        return false if @file_open_dismissed_token == token
+
+        true
+      end
+
+      def active_file_mention_token
+        mention = active_file_mention
+        return nil unless mention
+
+        mention[:token]
+      end
+
+      def active_file_mention
+        active_file_token("@")
+      end
+
+      def active_file_open_token
+        open = active_file_open
+        return nil unless open
+
+        open[:token]
+      end
+
+      def active_file_open
+        token = active_file_token("$")
+        return nil unless token && token[:start].zero?
+
+        token
+      end
+
+      def active_file_token(prefix)
+        input = composer_input.to_s
+        cursor = composer_cursor
+        return nil if cursor.negative? || cursor > input.length
+
+        before_cursor = input[0...cursor].to_s
+        prefix_index = before_cursor.rindex(prefix)
+        return nil unless prefix_index
+        return nil if before_cursor[prefix_index...cursor].to_s.match?(/\s/)
+
+        { start: prefix_index, finish: cursor, query: before_cursor[(prefix_index + 1)...cursor].to_s, token: before_cursor[prefix_index...cursor].to_s }
+      end
+
+      def file_overlay_matches
+        token = active_file_open || active_file_mention
+        return [] unless token
+
+        query = token[:query].downcase
+        matches = []
+        project_file_path_entries.each do |entry|
+          next unless file_mention_match?(entry[:downcase], query)
+
+          matches << entry[:path]
+          break if matches.length >= FILE_MENTION_RESULT_LIMIT
+        end
+        matches
+      end
+
+      def file_mention_match?(path, query)
+        return true if query.empty?
+        return true if path.include?(query)
+
+        query_chars = query.chars
+        query_chars.all? do |char|
+          index = path.index(char)
+          if index
+            path = path[(index + 1)..].to_s
+            true
+          else
+            false
+          end
+        end
+      end
+
+      def project_file_paths
+        @file_mention_paths ||= discover_project_file_paths
+      end
+
+      def project_file_path_entries
+        paths = project_file_paths
+        return @file_mention_path_entries if @file_mention_path_entries_paths.equal?(paths) && @file_mention_path_entries
+
+        @file_mention_path_entries_paths = paths
+        @file_mention_path_entries = paths.map { |path| { path: path, downcase: path.downcase } }
+      end
+
+      def discover_project_file_paths
+        paths = git_project_file_paths
+        paths = scanned_project_file_paths if paths.empty?
+        paths.reject { |path| path.empty? || path.end_with?("/") }.uniq.sort
+      end
+
+      def git_project_file_paths
+        ProjectFiles.git_paths(Dir.pwd)
+      end
+
+      def scanned_project_file_paths
+        ProjectFiles.scanned_paths(Dir.pwd)
+      end
+
+      def selected_file_mention_path
+        selected_file_overlay_path if file_mention_overlay_visible?
+      end
+
+      def selected_file_open_path
+        selected_file_overlay_path if file_open_overlay_visible?
+      end
+
+      def selected_file_overlay_path
+        return nil unless file_overlay_visible?
+
+        matches = file_overlay_matches
+        return nil if matches.empty?
+
+        matches[[@file_selection_index, matches.length - 1].min]
+      end
+
+      def select_previous_file_mention
+        matches = file_overlay_matches
+        return if matches.empty?
+
+        @file_selection_index = previous_list_selection_index(@file_selection_index, matches.length)
+      end
+
+      def select_next_file_mention
+        matches = file_overlay_matches
+        return if matches.empty?
+
+        @file_selection_index = next_list_selection_index(@file_selection_index, matches.length)
+      end
+
+      def complete_selected_file_mention
+        mention = active_file_mention
+        path = selected_file_mention_path
+        return false unless mention && path
+
+        self.composer_input = composer_input[0...mention[:start]].to_s + "@#{path}" + composer_input[mention[:finish]..].to_s
+        self.composer_cursor = mention[:start] + path.length + 1
+        reset_file_selection
+        true
+      end
+
+      def file_overlay_rows(width, height: screen_height)
+        return [] unless file_overlay_visible?
+
+        matches = file_overlay_matches
+        if matches.empty?
+          return overlay_card_rows("Files", [overlay_text_line("No matching files", :muted)], width)
+        end
+
+        visible = visible_file_overlay_matches(matches, height: height)
+        start_index = visible[:start]
+        lines = []
+        lines << overlay_text_line(@file_editor_open_status, :muted) if @file_editor_open_status && file_open_overlay_visible?
+        lines.concat(visible[:paths].each_with_index.map do |path, offset|
+          index = start_index + offset
+          overlay_choice_line(path, selected: index == @file_selection_index)
+        end)
+        overlay_card_rows(file_open_overlay_visible? ? "Open file" : "Files", lines, width)
+      end
+
+      def visible_file_overlay_matches(matches, height: screen_height)
+        max_rows = max_overlay_list_rows(height)
+        start = centered_list_window_start(@file_selection_index, matches.length, max_rows)
+        { start: start, paths: matches[start, max_rows] || [] }
+      end
+    end
+  end
+end

data/lib/kward/prompt_interface/git_prompt.rb

@@ -0,0 +1,299 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Interactive terminal UI used by the CLI frontend.
+  class PromptInterface
+    # Git status/commit modal overlay support.
+    module GitPrompt
+      def git_commit_message(status_lines)
+        start
+        @mutex.synchronize do
+          prepare_modal_input_locked("Git>", clear_attachments: true)
+          @git_state = git_state_for(status_lines)
+          render_prompt_locked
+        end
+
+        loop do
+          key = read_key(nonblock: true)
+          result = nil
+          @mutex.synchronize do
+            if key.nil?
+              resized = handle_resize_locked
+              footer_refreshed = tick_footer_locked
+              render_prompt_locked if resized || footer_refreshed
+            else
+              result = handle_git_key(key)
+              render_prompt_locked unless result.is_a?(String) || result == SELECT_CANCEL || git_action?(result)
+            end
+          end
+
+          if git_action?(result)
+            action_result = block_given? ? yield(result) : status_lines
+            refreshed_status = git_action_status_lines(action_result)
+            open_git_diff_viewer(action_result[:diff]) if action_result.is_a?(Hash) && action_result[:diff]
+            @mutex.synchronize do
+              selected_index = @git_state ? @git_state[:selected_index].to_i : 0
+              @git_state = git_state_for(refreshed_status, selected_index: selected_index)
+              @prompt_label = "Git>"
+              render_prompt_locked
+            end
+          elsif result.is_a?(String) || result == SELECT_CANCEL
+            finish_git_prompt
+            return result == SELECT_CANCEL ? nil : result
+          end
+
+          sleep 0.02 if key.nil?
+        end
+      end
+
+      private
+
+      def handle_git_key(key)
+        return git_submit_message if key.nil?
+        return if handle_git_bracketed_paste_key(key)
+        return if git_composing? && handle_shift_enter_key(key)
+
+        csi_result = handle_git_csi_u_key(key)
+        return csi_result unless csi_result == false
+
+        return true if handle_bundled_key(key) { |token| handle_git_key(token) }
+
+        case key
+        when "\n", "\r"
+          return git_submit_message if git_composing?
+          return git_open_selected_file_diff
+        when "\t"
+          return git_composing? ? git_return_to_overlay : git_begin_message
+        when "\b", "\x7F"
+          return delete_before_cursor if git_composing?
+        when "\e"
+          return SELECT_CANCEL
+        end
+
+        key_name = key_name_for(key)
+        named_result = handle_git_named_key(key_name) if key_name
+        return named_result unless named_result == false || named_result.nil?
+
+        binding_result = handle_composer_key_binding(key) if git_composing?
+        return binding_result unless binding_result == false || binding_result.nil?
+
+        return git_toggle_selected_file if key == "s" && !git_composing?
+
+        insert_key(key) if git_composing?
+      end
+
+      def handle_git_csi_u_key(key)
+        sequence = parse_csi_u_key(key)
+        return false unless sequence
+
+        code = sequence[:code]
+        modifier = sequence[:modifier]
+        queue_pending_keys(sequence[:remaining]) if sequence[:remaining] && !sequence[:remaining].empty?
+
+        case code
+        when 9
+          git_composing? ? git_return_to_overlay : git_begin_message
+        when 13
+          git_composing? ? git_submit_message : git_open_selected_file_diff
+        when 27
+          SELECT_CANCEL
+        when 8, 127
+          git_composing? && alt_modifier?(modifier) ? delete_word_before_cursor : delete_before_cursor if git_composing?
+          nil
+        when 4
+          delete_at_cursor if git_composing?
+          nil
+        else
+          if !git_composing? && code == "s".ord && (sequence[:modifiers].to_s.empty? || sequence[:modifiers].to_s == "1")
+            return git_toggle_selected_file
+          end
+          return false unless git_composing?
+
+          modified_result = handle_modified_csi_u_key(code, modifier)
+          return modified_result unless modified_result == false
+
+          insert_csi_u_text(sequence)
+        end
+      end
+
+      def handle_git_bracketed_paste_key(key)
+        paste = read_bracketed_paste(key)
+        return false unless paste
+
+        insert_string(normalize_paste(paste[:content])) if git_composing?
+        queue_pending_keys(paste[:remaining]) if paste[:remaining] && !paste[:remaining].empty?
+        true
+      end
+
+      def handle_git_named_key(key_name)
+        case key_name
+        when :return, :enter
+          git_composing? ? git_submit_message : git_open_selected_file_diff
+        when :backspace
+          delete_before_cursor if git_composing?
+        when :delete
+          delete_at_cursor if git_composing?
+        when :left
+          move_cursor_left if git_composing?
+        when :right
+          move_cursor_right if git_composing?
+        when :up
+          git_composing? ? false : git_move_selection(-1)
+        when :down
+          git_composing? ? false : git_move_selection(1)
+        when :home
+          move_to_start_of_line if git_composing?
+        when :end
+          move_to_end_of_line if git_composing?
+        else
+          false
+        end
+      end
+
+      def handle_git_escape_sequence
+        pending_sequence = read_pending_escape_sequence
+        return SELECT_CANCEL if pending_sequence.empty?
+
+        full_sequence = "\e#{pending_sequence}"
+        sequence = next_key_token(full_sequence)
+        queue_pending_keys(full_sequence[sequence.length..]) if full_sequence.length > sequence.length
+        return SELECT_CANCEL if sequence == "\e"
+
+        handle_git_named_key(key_name_for(sequence))
+      end
+
+      def git_state_for(status_lines, selected_index: 0)
+        lines = Array(status_lines).map(&:to_s)
+        selected_index = [[selected_index.to_i, 0].max, [lines.length - 1, 0].max].min
+        { status_lines: lines, composing: false, selected_index: selected_index, message_draft: "", message_cursor: 0 }
+      end
+
+      def git_action?(result)
+        result.is_a?(Hash) && result[:action]
+      end
+
+      def git_move_selection(delta)
+        return false unless @git_state
+
+        count = @git_state[:status_lines].length
+        return true if count.zero?
+
+        @git_state[:selected_index] = [[@git_state[:selected_index].to_i + delta, 0].max, count - 1].min
+        true
+      end
+
+      def git_toggle_selected_file
+        return true unless @git_state
+        return true if @git_state[:status_lines].empty?
+
+        { action: :toggle_stage, index: @git_state[:selected_index].to_i }
+      end
+
+      def git_open_selected_file_diff
+        return true unless @git_state
+        return true if @git_state[:status_lines].empty?
+
+        { action: :open_diff, index: @git_state[:selected_index].to_i }
+      end
+
+      def git_action_status_lines(action_result)
+        return action_result[:status_lines] if action_result.is_a?(Hash) && action_result.key?(:status_lines)
+
+        action_result
+      end
+
+      def open_git_diff_viewer(diff)
+        return unless diff.respond_to?(:[])
+
+        @mutex.synchronize do
+          open_diff_viewer(diff[:path].to_s, diff[:content].to_s)
+          render_prompt_locked
+        end
+        read_editor_until_closed
+      end
+
+      def read_editor_until_closed
+        while editor_active?
+          key = read_key(nonblock: true)
+          @mutex.synchronize do
+            if key.nil?
+              resized = handle_resize_locked
+              footer_refreshed = tick_footer_locked
+              render_prompt_locked if resized || footer_refreshed
+            else
+              handle_editor_key(key)
+              render_prompt_locked if editor_active?
+            end
+          end
+          sleep 0.02 if key.nil?
+        end
+      end
+
+      def git_begin_message
+        return true if git_composing?
+
+        @git_state[:composing] = true if @git_state
+        @prompt_label = "Commit>"
+        self.composer_input = @git_state.fetch(:message_draft, "")
+        self.composer_cursor = [[@git_state.fetch(:message_cursor, composer_input.length).to_i, 0].max, composer_input.length].min
+        true
+      end
+
+      def git_return_to_overlay
+        return true unless git_composing?
+
+        @git_state[:message_draft] = composer_input.dup
+        @git_state[:message_cursor] = composer_cursor
+        @git_state[:composing] = false
+        @prompt_label = "Git>"
+        self.composer_input = ""
+        self.composer_cursor = 0
+        true
+      end
+
+      def git_submit_message
+        return false unless git_composing?
+
+        value = composer_input.dup
+        add_history(composer_input)
+        value
+      end
+
+      def git_composing?
+        @git_state && @git_state[:composing]
+      end
+
+      def finish_git_prompt
+        @mutex.synchronize do
+          @git_state = nil
+          self.composer_input = ""
+          self.composer_cursor = 0
+          @asking = true
+          render_prompt_locked
+          @output_io.flush
+        end
+      end
+
+      def git_overlay_rows(width, height: screen_height)
+        return [] unless @git_state
+
+        help = git_composing? ? "Type commit message · Enter commit · Tab overlay · Esc cancel" : "↑/↓ select · Enter diff · s stage/unstage · Tab message · Esc cancel"
+        lines = [overlay_text_line(help, :muted), overlay_blank_line]
+        status_lines = @git_state[:status_lines]
+        status_lines = ["No uncommitted changes."] if status_lines.empty?
+        max_status_rows = [max_overlay_list_rows(height), 1].max
+        selected_index = @git_state[:selected_index].to_i
+        start_index = centered_list_window_start(selected_index, status_lines.length, max_status_rows)
+        visible_status_lines = status_lines[start_index, max_status_rows] || []
+        lines << overlay_text_line("… #{start_index} above", :muted) if start_index.positive?
+        visible_status_lines.each_with_index do |line, offset|
+          index = start_index + offset
+          marker = index == selected_index ? "› " : "  "
+          lines << overlay_text_line("#{marker}#{line}")
+        end
+        hidden_below = status_lines.length - start_index - visible_status_lines.length
+        lines << overlay_text_line("… #{hidden_below} more", :muted) if hidden_below.positive?
+        overlay_card_rows("Git", lines, width)
+      end
+    end
+  end
+end

data/lib/kward/prompt_interface/interactive/controller.rb

@@ -0,0 +1,186 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Interactive terminal UI used by the CLI frontend.
+  class PromptInterface
+    # Controller object passed to interactive plugin commands. Owns the canvas
+    # buffer and exposes the plugin-facing API for drawing colored cells,
+    # reading keys, and controlling the loop lifecycle.
+    #
+    # Kward manages the actual terminal rendering: the plugin fills the canvas
+    # via {#put} and {#clear_frame}, then calls {#render} to mark it dirty.
+    # Kward flushes the canvas to the composer region on the next frame write.
+    class InteractiveController
+      # Creates a controller with the given canvas dimensions and frame rate.
+      #
+      # @param width [Integer] canvas width in terminal columns
+      # @param height [Integer] canvas height in terminal rows
+      # @param fps [Numeric] target frame rate for tick callbacks
+      def initialize(width:, height:, fps:)
+        @width = [width.to_i, 1].max
+        @height = [height.to_i, 1].max
+        @fps = [[fps.to_f, 1].max, 120].min
+        @cells = Array.new(@height) { Array.new(@width) { blank_cell } }
+        @dirty = true
+        @keys = []
+        @exited = false
+        @on_tick = nil
+      end
+
+      # @return [Integer] canvas width in terminal columns
+      attr_reader :width
+
+      # @return [Integer] canvas height in terminal rows
+      attr_reader :height
+
+      # @return [Numeric] target frame rate
+      attr_reader :fps
+
+      # Sets the tick callback invoked by Kward on each frame. The block
+      # receives this controller. Returning `:exit` or calling {#exit}
+      # ends the loop.
+      #
+      # @yieldparam ui [InteractiveController] self
+      # @return [void]
+      def on_tick(&block)
+        @on_tick = block
+      end
+
+      # Places a character at the given canvas position with optional color.
+      #
+      # @param row [Integer] zero-based row
+      # @param col [Integer] zero-based column
+      # @param char [String] single character to display
+      # @param color [Symbol, String, nil] ANSI style name or raw SGR code
+      # @return [void]
+      def put(row, col, char, *colors)
+        row = row.to_i
+        col = col.to_i
+        return if row.negative? || row >= @height
+        return if col.negative? || col >= @width
+
+        @cells[row][col] = { char: char.to_s[0] || " ", colors: colors.flatten }
+        @dirty = true
+      end
+
+      # Clears all canvas cells to blank.
+      #
+      # @return [void]
+      def clear_frame
+        @cells = Array.new(@height) { Array.new(@width) { blank_cell } }
+        @dirty = true
+      end
+
+      # Marks the canvas as ready for Kward to render. Called after the plugin
+      # has finished drawing a frame via {#put} and {#clear_frame}.
+      #
+      # @return [void]
+      def render
+        @dirty = true
+      end
+
+      # Whether the canvas has changes pending render. Kward checks this to
+      # decide whether to write cells to the terminal.
+      #
+      # @return [Boolean]
+      def dirty?
+        @dirty
+      end
+
+      # Returns the canvas cells as a 2D array of `{ char:, colors: }` hashes.
+      # Kward calls this to render the frame. Resets the dirty flag.
+      #
+      # @return [Array<Array<Hash>>]
+      def cells
+        @dirty = false
+        @cells
+      end
+
+      # Returns the next pending key, or nil if none. Keys are routed by
+      # Kward's main input loop via {#push_key}. Non-blocking.
+      #
+      # @return [String, Symbol, nil]
+      def poll_key
+        @keys.shift
+      end
+
+      # Requests that the interactive loop exit. Kward detects this and tears
+      # down the canvas, restoring the prior composer state.
+      #
+      # @return [void]
+      def exit
+        @exited = true
+      end
+
+      # Whether exit has been requested by the plugin or forced by Kward.
+      #
+      # @return [Boolean]
+      def exited?
+        @exited
+      end
+
+      # Whether a tick callback has been registered.
+      #
+      # @return [Boolean]
+      def tickable?
+        !@on_tick.nil?
+      end
+
+      # Invokes the registered tick callback. Kward calls this on each frame.
+      # Returns `:exit` if the callback requests exit.
+      #
+      # @return [Object, :exit, nil]
+      def invoke_tick
+        return nil unless @on_tick
+
+        result = @on_tick.call(self)
+        result == :exit ? :exit : nil
+      end
+
+      # Resizes the canvas dimensions. Called by Kward when the terminal
+      # resizes during interactive mode.
+      #
+      # @param width [Integer] new canvas width
+      # @param height [Integer] new canvas height (kept at original row count)
+      # @return [void]
+      def resize(width:, height: @height)
+        @width = [width.to_i, 1].max
+        new_height = [height.to_i, 1].max
+        if new_height != @height
+          @height = new_height
+          clear_frame
+          return
+        end
+
+        @cells.each do |row|
+          if row.length < @width
+            row.fill(blank_cell, row.length...@width)
+          else
+            row.slice!(@width..)
+          end
+        end
+        @dirty = true
+      end
+
+      # Pushes a key into the internal queue. Called by Kward's input loop.
+      #
+      # @param key [String, Symbol] key to enqueue
+      # @return [void]
+      def push_key(key)
+        @keys << key
+      end
+
+      # Marks the controller as exited. Called by Kward on forced exit.
+      #
+      # @return [void]
+      def force_exit
+        @exited = true
+      end
+
+      private
+
+      def blank_cell
+        { char: " ", colors: [] }
+      end
+    end
+  end
+end