kward 0.67.1 → 0.68.0

data/lib/kward/plugin_registry.rb

@@ -1,11 +1,17 @@
 require_relative "config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Loads trusted user plugin files and provides the plugin DSL.
   #
   # Plugins live in the user plugin directory, run as local Ruby code, and can
   # register slash commands, one footer renderer, prompt context, and live
   # transcript-event observers for CLI and RPC frontends.
+  #
+  # This registry is intentionally trust-based, not a sandbox. Keep plugin loading
+  # restricted to `ConfigFiles.plugin_paths`, keep workspace-local code out of the
+  # load path, and expose immutable transcript views so plugins can observe state
+  # without corrupting active conversations.
   class PluginRegistry
     COMMAND_NAME_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.freeze
 
@@ -26,6 +32,7 @@ module Kward
 
     # Read-only transcript view exposed to plugin code.
     class Transcript
+      # Creates an object for trusted plugin loading and dispatch.
       def initialize(conversation)
         @conversation = conversation
       end
@@ -43,6 +50,7 @@ module Kward
     class Context
       attr_reader :args, :workspace_root
 
+      # Creates an object for trusted plugin loading and dispatch.
       def initialize(conversation:, args: "", session: nil, workspace_root: Dir.pwd, say_callback: nil)
         @conversation = conversation
         @args = args.to_s
@@ -89,6 +97,7 @@ module Kward
 
     # DSL object yielded by `Kward.plugin` blocks.
     class DSL
+      # Creates an object for trusted plugin loading and dispatch.
       def initialize(registry, path)
         @registry = registry
         @path = path
@@ -128,6 +137,7 @@ module Kward
       end
     end
 
+    # Mutable singleton guard used while loading trusted plugin files.
     class << self
       attr_accessor :loading_registry, :loading_path
 
@@ -161,6 +171,7 @@ module Kward
       end
     end
 
+    # Creates an object for trusted plugin loading and dispatch.
     def initialize(reserved_commands: [])
       @reserved_commands = reserved_commands.map(&:to_s)
       @commands = {}
@@ -170,6 +181,7 @@ module Kward
       @prompt_context_renderers = []
     end
 
+    # @return [String, nil] plugin file currently responsible for footer output
     attr_reader :footer_path
 
     def commands

data/lib/kward/private_file.rb

@@ -1,7 +1,9 @@
 require "fileutils"
 require "json"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Writes sensitive JSON files with private filesystem permissions.
   module PrivateFile
     module_function
 

data/lib/kward/prompt_interface/banner.rb

@@ -2,8 +2,11 @@ require_relative "../ansi"
 require_relative "../resources/avatar_kward_logo"
 require_relative "../resources/pixel_logo"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Startup banner logo and message renderer.
   class PromptInterface
+    # Startup banner rendering data and helpers for the prompt interface.
     class Banner
       LOGO_WIDTH = 32
       LOGO_PIXEL_HEIGHT = 32

data/lib/kward/prompt_interface/composer_controller.rb

@@ -0,0 +1,262 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # High-level composer input loop and submission controller.
+  class PromptInterface
+    # Text composer state transitions for keyboard input, paste, history, and submission.
+    module ComposerController
+      private
+
+      def composer_input
+        @composer.input
+      end
+
+      def composer_input=(value)
+        @composer.input = value.to_s
+      end
+
+      def composer_cursor
+        @composer.cursor
+      end
+
+      def composer_cursor=(value)
+        @composer.cursor = value.to_i
+      end
+
+      def composer_attachments
+        @composer.attachments
+      end
+
+      def composer_kill_buffer
+        @composer.kill_buffer
+      end
+
+      def composer_kill_buffer=(value)
+        @composer.kill_buffer = value.to_s
+      end
+
+      def insert_key(key)
+        return unless key.is_a?(String) && key.length == 1 && key.match?(/[[:print:]]/)
+
+        insert_string(key)
+      end
+
+      def insert_string(string)
+        return if string.empty?
+
+        reset_slash_selection
+        reset_history_navigation
+        @slash_overlay_dismissed_input = nil
+              @composer.insert_string(string)
+            end
+
+      def insert_paste(string)
+        parsed = parse_attachments(string)
+        Array(parsed[:attachments]).each { |attachment| add_attachment(attachment) }
+        insert_string(parsed[:text].to_s) unless parsed[:text].to_s.empty?
+      end
+
+      def parse_attachments(string)
+        return { text: string.to_s, attachments: [] } unless @attachment_parser
+
+        result = @attachment_parser.call(string.to_s)
+        return { text: string.to_s, attachments: [] } unless result.is_a?(Hash)
+
+        {
+          text: result[:text] || result["text"] || "",
+          attachments: result[:attachments] || result["attachments"] || []
+        }
+      rescue StandardError
+        { text: string.to_s, attachments: [] }
+      end
+
+      def add_attachment(attachment)
+              @composer.add_attachment(attachment)
+            end
+
+      def delete_before_cursor
+              if @composer.cursor.zero?
+          remove_last_attachment
+          return
+        end
+
+        reset_slash_selection
+        reset_history_navigation
+        @composer.delete_before_cursor
+            end
+
+      def remove_last_attachment
+              return unless @composer.remove_last_attachment
+
+        reset_slash_selection
+        reset_history_navigation
+        @slash_overlay_dismissed_input = nil
+            end
+
+      def delete_at_cursor
+              return unless @composer.cursor < @composer.input.length
+
+        reset_slash_selection
+        reset_history_navigation
+        @slash_overlay_dismissed_input = nil
+        @composer.delete_at_cursor
+            end
+
+      def move_cursor_left
+              @composer.move_cursor_left
+            end
+
+      def move_cursor_right
+              @composer.move_cursor_right
+            end
+
+      def move_to_start_of_line
+              @composer.move_to_start_of_line
+            end
+
+      def move_to_end_of_line
+              @composer.move_to_end_of_line
+            end
+
+      def move_to_previous_word
+              @composer.move_to_previous_word
+            end
+
+      def move_to_next_word
+              @composer.move_to_next_word
+            end
+
+      def delete_at_cursor_or_exit
+        composer_input.empty? ? exit_input : delete_at_cursor
+      end
+
+      def delete_word_before_cursor
+        reset_slash_selection
+        reset_history_navigation
+              @composer.delete_word_before_cursor
+            end
+
+      def delete_word_after_cursor
+        reset_slash_selection
+        reset_history_navigation
+              @composer.delete_word_after_cursor
+            end
+
+      def kill_line_before_cursor
+        reset_slash_selection
+        reset_history_navigation
+              @composer.kill_line_before_cursor
+            end
+
+      def kill_line_after_cursor
+        reset_slash_selection
+        reset_history_navigation
+              @composer.kill_line_after_cursor
+            end
+
+      def kill_range(start_index, end_index)
+              return unless @composer.kill_range(start_index, end_index)
+
+        reset_slash_selection
+        reset_history_navigation
+            end
+
+      def yank_kill_buffer
+              @composer.yank_kill_buffer
+            end
+
+      def previous_word_boundary(index)
+              @composer.previous_word_boundary(index)
+      end
+
+      def next_word_boundary(index)
+              @composer.next_word_boundary(index)
+      end
+
+      def word_separator?(char)
+        @composer.word_separator?(char)
+      end
+
+      def add_history(value)
+              @composer.add_history(value)
+            end
+
+      def recall_previous_history
+              @composer.recall_previous_history
+            end
+
+      def recall_next_history
+              @composer.recall_next_history
+            end
+
+      def replace_input(value)
+        @composer.replace_input(value)
+            end
+
+      def prefill_input(value)
+        @mutex.synchronize do
+          @composer.prefill_input = value.to_s
+        end
+      end
+
+      def reset_history_navigation
+              @composer.reset_history_navigation
+            end
+
+
+      def submit_input
+        value = submitted_input
+        add_history(composer_input)
+        if @busy
+          clear_prompt_for_output_locked
+          self.composer_input = ""
+          self.composer_cursor = 0
+          @composer.clear_attachments
+          reset_history_navigation
+          @asking = true
+          render_prompt_after_output_locked
+        else
+          clear_prompt_locked
+          self.composer_input = ""
+          self.composer_cursor = 0
+          @composer.clear_attachments
+          @asking = false
+          @rendered_rows = 0
+          @cursor_rendered_row = 0
+        end
+        @output_io.flush
+        value
+      end
+
+      def submitted_input
+        return composer_input if composer_attachments.empty?
+
+        sources = composer_attachments.map { |attachment| attachment[:source_text].to_s }.reject(&:empty?)
+        display_input = composer_input.to_s.rstrip
+        full_input = [display_input, *sources].reject { |part| part.to_s.strip.empty? }.join("\n")
+        SubmittedInput.new(full_input, display_input: display_input)
+      end
+
+      def exit_input
+        if @busy
+          clear_prompt_for_output_locked
+          self.composer_input = ""
+          self.composer_cursor = 0
+          @composer.clear_attachments
+          @asking = true
+          render_prompt_after_output_locked
+        else
+          clear_prompt_locked
+          self.composer_input = ""
+          self.composer_cursor = 0
+          @composer.clear_attachments
+          @asking = false
+          @rendered_rows = 0
+          @cursor_rendered_row = 0
+        end
+        @output_io.flush
+        EXIT_INPUT
+      end
+
+    end
+  end
+end

data/lib/kward/prompt_interface/composer_renderer.rb

@@ -0,0 +1,172 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Renderer for the editable composer text area.
+  class PromptInterface
+    # Renderer for the editable prompt composer area.
+    module ComposerRenderer
+      private
+
+      def composer_layout(width, height = screen_height)
+        return compact_composer_layout(width) if height < 4
+        return question_composer_layout(width, height) if @question_state
+
+        content_width = [width - 4, 1].max
+        input_layout_rows, input_cursor_row, input_cursor_col = input_layout(content_width)
+        attachment_rows = attachment_badge_rows(content_width)
+        overlay_rows = active_overlay_rows(width, height: height)
+        footer_text = footer_text()
+        max_input_rows = max_visible_input_rows(attachment_rows.length, overlay_rows.length, footer_text.empty? ? 0 : 1, height: height)
+        visible_start = [[input_cursor_row - max_input_rows + 1, 0].max, [input_layout_rows.length - max_input_rows, 0].max].min
+        visible_rows = input_layout_rows[visible_start, max_input_rows] || [""]
+        rows = overlay_rows + [top_border(width)]
+        rows.concat(attachment_rows)
+        rows.concat(visible_rows.map { |row| box_content_row(row, content_width) })
+        rows << footer_row(content_width, footer_text) unless footer_text.empty?
+        rows << bottom_border(width)
+        cursor_row = overlay_rows.length + 1 + attachment_rows.length + input_cursor_row - visible_start
+        cursor_col = 2 + [input_cursor_col, content_width - 1].min
+        [rows, cursor_row, cursor_col]
+      end
+
+      def compact_composer_layout(width)
+        cursor_line, cursor_col = cursor_logical_position
+        prefix = "#{@prompt_label} "
+        line = input_lines[cursor_line] || ""
+        input_width = [width - prefix.length, 1].max
+        visible_start = [[cursor_col - input_width + 1, 0].max, [line.length - input_width, 0].max].min
+        visible = line[visible_start, input_width].to_s
+        row = "#{prefix}#{visible}"[0, width].to_s.ljust(width)
+        [[row], 0, [prefix.length + cursor_col - visible_start, width - 1].min]
+      end
+
+      def input_layout(content_width)
+        cursor_line, cursor_col = cursor_logical_position
+        rows = []
+        cursor_row = 0
+        rendered_row_offset = 0
+
+        input_lines.each_with_index do |line, index|
+          prefix = input_prefix(index)
+          continuation_prefix = " " * prefix.length
+          available = [content_width - prefix.length, 1].max
+          chunks = line.scan(/.{1,#{available}}/m)
+          chunks = [""] if chunks.empty?
+          if index == cursor_line && cursor_col == line.length && line.length.positive? && (line.length % available).zero?
+            chunks << ""
+          end
+
+          if index == cursor_line
+            cursor_row = rendered_row_offset + (cursor_col / available)
+          end
+
+          chunks.each_with_index do |chunk, chunk_index|
+            rows << "#{chunk_index.zero? ? prefix : continuation_prefix}#{chunk}"
+          end
+          rendered_row_offset += chunks.length
+        end
+
+        prefix = input_prefix(cursor_line)
+        available = [content_width - prefix.length, 1].max
+        cursor_col_in_row = prefix.length + (cursor_col % available)
+        [rows, cursor_row, cursor_col_in_row]
+      end
+
+      def top_border(width)
+        title = composer_title
+        status = composer_status_text
+        if status
+          gap = width - 2 - ANSI.strip(title).length - ANSI.strip(status).length
+          if gap >= 0
+            return colored("╭", :primary_green) + title + colored("─" * gap, :primary_green) + status + colored("╮", :primary_green)
+          end
+        end
+        plain_title = ANSI.strip(title)
+        "#{colored("╭", :primary_green)}#{title}#{colored("─" * [width - plain_title.length - 2, 0].max, :primary_green)}#{colored("╮", :primary_green)}"
+      end
+
+      def composer_title
+        label = @prompt_label.delete_suffix(">")
+        if @busy && @queued_count.positive?
+          status_composer_text(busy_title("#{label} · #{@queued_count} queued"))
+        elsif @busy && @steered_count.to_i.positive?
+          status_composer_text(busy_title("#{label} · #{spinner_frame} steering"))
+        elsif @busy
+          status_composer_text(busy_title("#{label} · #{spinner_frame} #{@busy_activity}"))
+        else
+          status_composer_text(label)
+        end
+      end
+
+      def busy_title(text)
+        @busy_help ? "#{text} · #{BUSY_HELP_TEXT}" : text
+      end
+
+      def composer_status_text
+        text = @composer_status&.call.to_s
+        return nil if text.empty?
+
+        status_composer_text(text)
+      end
+
+      def status_composer_text(text)
+        " #{text} "
+      end
+
+      def bottom_border(width)
+        colored("╰#{"─" * [width - 2, 0].max}╯", :primary_green)
+      end
+
+      def box_content_row(row, content_width)
+        "#{colored("│", :primary_green)} #{row[0, content_width].to_s.ljust(content_width)} #{colored("│", :primary_green)}"
+      end
+
+      def footer_row(content_width, text = footer_text)
+        return nil if text.empty?
+
+        box_content_row(visible_truncate(text, content_width), content_width)
+      end
+
+      def footer_text
+        return "" unless @footer
+
+        @footer.call.to_s.gsub(/\s+/, " ").strip
+      rescue StandardError
+        ""
+      end
+
+      def attachment_badge_rows(content_width)
+        attachment_badge_texts.map { |text| box_content_row(visible_truncate(text, content_width), content_width) }
+      end
+
+      def attachment_badge_texts
+        return [] unless @attachment_badges
+
+        Array(@attachment_badges.call(composer_input, composer_attachments)).map(&:to_s).reject(&:empty?)
+      rescue ArgumentError
+        Array(@attachment_badges.call(composer_input)).map(&:to_s).reject(&:empty?)
+      rescue StandardError
+        []
+      end
+
+      def max_visible_input_rows(attachment_count = 0, overlay_count = active_overlay_rows(screen_width).length, footer_count = footer_text.to_s.empty? ? 0 : 1, height: screen_height)
+        input_cap = [COMPOSER_MAX_INPUT_ROWS - attachment_count, 1].max
+        [[input_cap, height - 3 - overlay_count - footer_count - attachment_count].min, 1].max
+      end
+
+      def input_lines
+        lines = composer_input.split("\n", -1)
+        lines.empty? ? [""] : lines
+      end
+
+      def input_prefix(_index)
+        ""
+      end
+
+      def cursor_logical_position
+        before_cursor = composer_input[0...composer_cursor]
+        [before_cursor.count("\n"), (before_cursor.split("\n", -1).last || "").length]
+      end
+
+    end
+  end
+end