kward 0.73.1 → 0.75.0

data/lib/kward/plugin_registry.rb

@@ -1,4 +1,6 @@
 require_relative "config_files"
+require_relative "deep_copy"
+require_relative "hooks"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -39,6 +41,9 @@ module Kward
       end
     end
 
+    # Registered lifecycle hook handler.
+    HookHandler = Struct.new(:event, :id, :description, :path, :order, :match, :failure_policy, :handler, keyword_init: true)
+
     # Read-only transcript view exposed to plugin code.
     class Transcript
       # Creates an object for trusted plugin loading and dispatch.
@@ -50,7 +55,7 @@ module Kward
       #
       # @return [Array<Hash>] immutable transcript message data
       def messages
-        PluginRegistry.deep_freeze(PluginRegistry.deep_dup(@conversation.messages))
+        DeepCopy.freeze(DeepCopy.dup(@conversation.messages))
       end
     end
 
@@ -102,6 +107,34 @@ module Kward
         @conversation.refresh_system_message! if @conversation.respond_to?(:refresh_system_message!)
         nil
       end
+
+      def allow(message = nil, metadata: nil)
+        Hooks::Decision.allow(message, metadata: metadata)
+      end
+
+      def deny(message = nil, metadata: nil)
+        Hooks::Decision.deny(message, metadata: metadata)
+      end
+
+      def ask(message = nil, metadata: nil)
+        Hooks::Decision.ask(message, metadata: metadata)
+      end
+
+      def modify(payload, message: nil, metadata: nil)
+        Hooks::Decision.modify(payload, message: message, metadata: metadata)
+      end
+
+      def warn(message = nil, metadata: nil)
+        Hooks::Decision.warn(message, metadata: metadata)
+      end
+
+      def retry(message = nil, payload: nil, metadata: nil)
+        Hooks::Decision.retry(message, payload: payload, metadata: metadata)
+      end
+
+      def defer(message = nil, payload: nil, metadata: nil)
+        Hooks::Decision.defer(message, payload: payload, metadata: metadata)
+      end
     end
 
     # Public DSL object yielded by `Kward.plugin` blocks.
@@ -165,6 +198,25 @@ module Kward
         @registry.register_transcript_event(path: @path, &block)
       end
 
+      # Registers a lifecycle hook handler.
+      #
+      # Hooks are deterministic runtime callbacks around Kward lifecycle events.
+      # They can return a {Hooks::Decision}, a decision hash, a decision string,
+      # or nil to allow the operation.
+      #
+      # @param event [String, #to_s] lifecycle event name
+      # @param id [String, nil] stable hook identifier for logs and diagnostics
+      # @param description [String] short human-readable purpose
+      # @param order [Integer] lower values run first
+      # @param match [Hash, nil] optional event selector
+      # @yieldparam event [Hooks::Event] immutable lifecycle event
+      # @yieldparam ctx [Context] plugin execution context and decision helpers
+      # @return [void]
+      # @api public
+      def hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, &block)
+        @registry.register_hook(event, id: id, description: description, order: order, match: match, failure_policy: failure_policy, path: @path, &block)
+      end
+
       # Registers prompt context text injected into future system prompts.
       #
       # Keep this text short and never include secrets. The returned string can
@@ -205,29 +257,6 @@ module Kward
         paths.each { |path| registry.load_file(path) }
         registry
       end
-
-      def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) { |(key, item), result| result[key] = deep_dup(item) }
-        when Array
-          value.map { |item| deep_dup(item) }
-        else
-          value.dup
-        end
-      rescue TypeError
-        value
-      end
-
-      def deep_freeze(value)
-        case value
-        when Hash
-          value.each_value { |item| deep_freeze(item) }
-        when Array
-          value.each { |item| deep_freeze(item) }
-        end
-        value.freeze
-      end
     end
 
     # Creates an object for trusted plugin loading and dispatch.
@@ -239,6 +268,7 @@ module Kward
       @footer_path = nil
       @transcript_event_handlers = []
       @prompt_context_renderers = []
+      @hook_handlers = []
       @paths = []
     end
 
@@ -276,6 +306,20 @@ module Kward
       @prompt_context_renderers.map { |entry| entry[:renderer] }
     end
 
+    def hook_handlers
+      @hook_handlers.dup
+    end
+
+    def hook_manager
+      manager = Hooks::Manager.new
+      @hook_handlers.each do |hook|
+        manager.register(hook.event, id: hook.id, source: hook.path, order: hook.order, match: hook.match, failure_policy: hook.failure_policy) do |event, context|
+          hook.handler.call(event, context)
+        end
+      end
+      manager
+    end
+
     def prompt_context(context)
       parts = []
       @prompt_context_renderers.each do |entry|
@@ -387,6 +431,23 @@ module Kward
       @prompt_context_renderers << { path: path, renderer: renderer }
     end
 
+    def register_hook(event, id: nil, description: "", order: 100, match: nil, failure_policy: nil, path: nil, &handler)
+      event = event.to_s
+      raise "Plugin hook event is required" if event.empty?
+      raise "Plugin hook #{event} requires a handler" unless handler
+
+      @hook_handlers << HookHandler.new(
+        event: event,
+        id: id&.to_s || "#{File.basename(path.to_s.empty? ? "plugin" : path)}:#{event}:#{@hook_handlers.length + 1}",
+        description: description.to_s,
+        path: path,
+        order: order.to_i,
+        match: match,
+        failure_policy: failure_policy,
+        handler: handler
+      )
+    end
+
     private
 
     def transcript_event_for(event)
@@ -422,7 +483,7 @@ module Kward
     def transcript_event(type, payload)
       TranscriptEvent.new(
         type: type,
-        payload: PluginRegistry.deep_freeze(PluginRegistry.deep_dup(payload))
+        payload: DeepCopy.freeze(DeepCopy.dup(payload))
       ).freeze
     end
   end

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

@@ -112,7 +112,9 @@ module Kward
       end
 
       def open_diff_viewer(path, content)
-        @editor_state = EditorState.new(path: path.to_s, content: content.to_s, new_file: true, editor_mode: current_editor_mode, readonly: true, diff_view: true)
+        diff_view_mode = current_diff_view_mode
+        viewer_content = diff_view_mode == DiffViewMode::SIDE_BY_SIDE ? side_by_side_diff_content(content.to_s) : content.to_s
+        @editor_state = EditorState.new(path: path.to_s, content: viewer_content, new_file: true, editor_mode: current_editor_mode, readonly: true, diff_view: diff_view_mode)
         @prompt_label = "Diff>"
         self.composer_input = ""
         self.composer_cursor = 0
@@ -131,6 +133,63 @@ module Kward
         @editor_mode
       end
 
+      def current_diff_view_mode
+        configured = @diff_view_source.respond_to?(:call) ? @diff_view_source.call : @diff_view
+        DiffViewMode.resolve(configured, terminal_width: screen_width)
+      rescue StandardError
+        DiffViewMode.resolve(@diff_view, terminal_width: screen_width)
+      end
+
+      def side_by_side_diff_content(content)
+        width = side_by_side_diff_column_width
+        rows = []
+        pending_deletions = []
+
+        content.to_s.each_line(chomp: true) do |line|
+          if side_by_side_diff_metadata_line?(line)
+            rows.concat(flush_side_by_side_deletions(pending_deletions, width))
+            rows << line
+          elsif line.start_with?("-")
+            pending_deletions << line[1..].to_s
+          elsif line.start_with?("+")
+            deleted = pending_deletions.shift
+            rows << side_by_side_diff_row(deleted && "- #{deleted}", "+ #{line[1..]}", width)
+          else
+            rows.concat(flush_side_by_side_deletions(pending_deletions, width))
+            text = line.start_with?(" ") ? line[1..].to_s : line
+            rows << side_by_side_diff_row("  #{text}", "  #{text}", width)
+          end
+        end
+
+        rows.concat(flush_side_by_side_deletions(pending_deletions, width))
+        rows.join("\n")
+      end
+
+      def side_by_side_diff_metadata_line?(line)
+        line.start_with?("diff --git", "index ", "---", "+++", "@@")
+      end
+
+      def flush_side_by_side_deletions(lines, width)
+        lines.shift(lines.length).map { |line| side_by_side_diff_row("- #{line}", nil, width) }
+      end
+
+      def side_by_side_diff_row(left, right, width)
+        left_text = side_by_side_diff_cell(left, width)
+        right_text = side_by_side_diff_cell(right, width)
+        "#{left_text.ljust(width)} │ #{right_text}"
+      end
+
+      def side_by_side_diff_cell(text, width)
+        value = text.nil? ? "" : text.to_s
+        visible_truncate(value, width)
+      end
+
+      def side_by_side_diff_column_width
+        content_width = [screen_width - 4, 1].max
+        gutter_width = [[999.to_s.length, 4].max + 3, 1].max
+        [[(content_width - gutter_width - 3) / 2, 10].max, 80].min
+      end
+
       def current_editor_soft_wrap?
         return @editor_soft_wrap_source.call != false if @editor_soft_wrap_source.respond_to?(:call)
 
@@ -279,6 +338,34 @@ module Kward
         end
       end
 
+      def handle_editor_search_csi_u_key(sequence, enter: :confirm, restore_cursor_on_cancel: true)
+        result = case sequence[:code]
+                 when 13
+                   if enter == :repeat
+                     shift_modifier?(sequence[:modifier]) ? editor_search_repeat(:backward) : editor_search_repeat(:forward)
+                   else
+                     editor_search_confirm
+                   end
+                 when 27
+                   editor_search_cancel(restore_cursor: restore_cursor_on_cancel)
+                 when 8, 127
+                   editor_search_delete_character
+                 else
+                   normalized_code = ctrl_code(sequence[:code])
+                   if ctrl_modifier?(sequence[:modifier]) && normalized_code == 103
+                     shift_modifier?(sequence[:modifier]) ? editor_search_repeat(:backward) : editor_search_repeat(:forward)
+                   elsif (text = csi_u_printable_text(sequence))
+                     editor_search_append(text)
+                   elsif csi_u_text_field?(sequence)
+                     true
+                   else
+                     false
+                   end
+                 end
+        queue_pending_keys(sequence[:remaining]) if result != false && sequence[:remaining] && !sequence[:remaining].empty?
+        result
+      end
+
       def handle_editor_mouse_key(key)
         event = parse_editor_mouse_key(key)
         return false unless event
@@ -902,32 +989,40 @@ module Kward
 
       def editor_search_begin(direction = :forward)
         @editor_state.begin_search(direction)
+        ensure_editor_cursor_visible
         true
       end
 
       def editor_search_append(text)
         @editor_state.append_search(text)
+        ensure_editor_cursor_visible
         true
       end
 
       def editor_search_delete_character
         @editor_state.delete_search_character
+        ensure_editor_cursor_visible
         true
       end
 
-      def editor_search_confirm
+      def editor_search_confirm(clear_highlights: true)
         @editor_state.confirm_search
+        @editor_state.clear_search_highlights if clear_highlights
+        ensure_editor_cursor_visible
         true
       end
 
-      def editor_search_cancel
-        @editor_state.cancel_search
+      def editor_search_cancel(restore_cursor: true)
+        @editor_state.cancel_search(restore_cursor: restore_cursor)
+        ensure_editor_cursor_visible
         true
       end
 
       def editor_search_repeat(direction = nil)
         direction ||= @editor_state.search_direction
         @editor_state.repeat_search(direction)
+        @editor_state.clear_search_highlights unless @editor_state.search_active
+        ensure_editor_cursor_visible
         true
       end
 
@@ -939,6 +1034,31 @@ module Kward
         end
 
         @editor_state.repeat_search(direction, query)
+        @editor_state.clear_search_highlights
+        ensure_editor_cursor_visible
+        true
+      end
+
+      def ensure_editor_cursor_visible
+        return false unless @editor_state
+
+        content_width = [screen_width - 4, 1].max
+        visible_count = editor_visible_line_count
+        line_index, column = @editor_state.cursor_line_and_column
+        gutter_width = editor_line_number_gutter_width
+        text_width = editor_text_width(content_width, gutter_width)
+        sync_editor_wrap_state(text_width)
+
+        if current_editor_soft_wrap?
+          cursor_visual_row = editor_visual_row_for(line_index, column, text_width)
+          @editor_state.viewport_row = [[@editor_state.viewport_row, cursor_visual_row - visible_count + 1].max, cursor_visual_row].min
+          @editor_state.viewport_row = [@editor_state.viewport_row, 0].max
+        else
+          @editor_state.viewport_row = [[@editor_state.viewport_row, line_index - visible_count + 1].max, line_index].min
+          @editor_state.viewport_row = [@editor_state.viewport_row, 0].max
+          @editor_state.viewport_column = [[@editor_state.viewport_column.to_i, column - text_width + 1].max, column].min
+          @editor_state.viewport_column = [@editor_state.viewport_column, 0].max
+        end
         true
       end
 

data/lib/kward/prompt_interface/editor/modes/emacs.rb

@@ -112,6 +112,10 @@ module Kward
       def handle_emacs_csi_u_key(key)
         sequence = parse_csi_u_key(key)
         return false unless sequence
+        if editor_search_active?
+          search_result = handle_editor_search_csi_u_key(sequence)
+          return search_result unless search_result == false
+        end
 
         code = sequence[:code]
         modifier = sequence[:modifier]

data/lib/kward/prompt_interface/editor/modes/modern.rb

@@ -37,16 +37,18 @@ module Kward
 
         case key
         when "\n", "\r"
-          return editor_search_confirm if editor_search_active?
+          return editor_search_repeat(:forward) if editor_search_active?
           modern_record_undo { modern_insert_text("\n") }
         when "\t"
           modern_record_undo { editor_insert_tab unless editor_search_active? }
         when "\b", "\x7F"
           editor_search_active? ? editor_search_delete_character : modern_record_undo { modern_delete_before_cursor }
+        when "\a"
+          return editor_search_repeat(:forward) if editor_search_active?
         when TerminalKeys::CTRL_C
           return editor_search_cancel if editor_search_active?
         when "\e"
-          return editor_search_cancel if editor_search_active?
+          return editor_search_cancel(restore_cursor: false) if editor_search_active?
           return @editor_state.collapse_to_primary_selection if @editor_state.multi_cursor?
           return @editor_state.clear_selection if @editor_state.selection_active?
         when "/"
@@ -79,6 +81,10 @@ module Kward
       def handle_modern_csi_u_key(key)
         sequence = parse_csi_u_key(key)
         return false unless sequence
+        if editor_search_active?
+          search_result = handle_editor_search_csi_u_key(sequence, enter: :repeat, restore_cursor_on_cancel: false)
+          return search_result unless search_result == false
+        end
 
         code = sequence[:code]
         modifier = sequence[:modifier]
@@ -197,7 +203,7 @@ module Kward
         when TerminalKeys::CTRL_C
           editor_search_active? ? editor_search_cancel : copy_editor_selection
         when TerminalKeys::CTRL_F
-          @editor_state.move_right unless editor_search_active?
+          editor_search_begin(:forward) unless editor_search_active?
         when TerminalKeys::CTRL_V
           modern_record_undo { @editor_state.yank_kill_buffer } unless editor_search_active?
         when TerminalKeys::CTRL_X
@@ -229,7 +235,7 @@ module Kward
 
           @editor_state.add_next_occurrence_selection
         when 102
-          @editor_state.move_right unless editor_search_active?
+          editor_search_begin(:forward) unless editor_search_active?
         when 118
           modern_record_undo { @editor_state.yank_kill_buffer } unless editor_search_active?
         when 120