kward 0.70.0 → 0.72.0

data/lib/kward/plugin_registry.rb

@@ -23,6 +23,15 @@ module Kward
       end
     end
 
+    # Registered interactive command that takes over the composer region with a
+    # Kward-driven render and input loop. Like a slash command but with canvas
+    # rendering capabilities for games, dashboards, viewers, and similar uses.
+    InteractiveCommand = Struct.new(:name, :description, :argument_hint, :rows, :fps, :path, :handler, keyword_init: true) do
+      def entry
+        { name: name, description: description, argument_hint: argument_hint }
+      end
+    end
+
     # Read-only event passed to plugin transcript observers.
     TranscriptEvent = Struct.new(:type, :payload, keyword_init: true) do
       def to_h
@@ -95,7 +104,19 @@ module Kward
       end
     end
 
-    # DSL object yielded by `Kward.plugin` blocks.
+    # Public DSL object yielded by `Kward.plugin` blocks.
+    #
+    # Plugin files normally interact with this object only through a block:
+    #
+    # @example Register a plugin command
+    #   Kward.plugin do |plugin|
+    #     plugin.command "hello", description: "Say hello" do |args, ctx|
+    #       name = args.strip.empty? ? "there" : args.strip
+    #       ctx.say "Hello, #{name}."
+    #     end
+    #   end
+    #
+    # @api public
     class DSL
       # Creates an object for trusted plugin loading and dispatch.
       def initialize(registry, path)
@@ -105,36 +126,74 @@ module Kward
 
       # Registers a slash command.
       #
+      # The command is available in the interactive CLI and through the RPC
+      # command bridge. Command names do not include the leading `/`.
+      #
       # @param name [String, #to_s] command name without the leading slash
       # @param description [String] short text shown in command listings
       # @param argument_hint [String] optional usage hint for arguments
       # @yieldparam args [String] text after the command name
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def command(name, description: "", argument_hint: "", &block)
         @registry.register_command(name, description: description, argument_hint: argument_hint, path: @path, &block)
       end
 
       # Registers or replaces the custom footer renderer.
       #
+      # Only one footer renderer is active. If multiple plugins register one,
+      # the later renderer replaces the earlier renderer.
+      #
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def footer(&block)
         @registry.register_footer(path: @path, &block)
       end
 
       # Registers a live transcript event observer.
       #
+      # Observer errors are caught and reported as warnings so a plugin cannot
+      # crash the active turn by raising from an event handler.
+      #
       # @yieldparam event [TranscriptEvent] normalized transcript event
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def on_transcript_event(&block)
         @registry.register_transcript_event(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
+      # be sent to the active model as part of Kward's system instructions.
+      #
       # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
       def prompt_context(&block)
         @registry.register_prompt_context(path: @path, &block)
       end
+
+      # Registers an interactive command that takes over the composer region with
+      # a Kward-driven render and input loop. The handler receives an
+      # interactive controller object with a canvas API for drawing colored
+      # cells and reading keys. Useful for games, dashboards, and viewers.
+      #
+      # @param name [String, #to_s] command name without the leading slash
+      # @param rows [Integer] fixed canvas height in terminal rows
+      # @param fps [Numeric] frame rate for tick callbacks (1-120, default 30)
+      # @param description [String] short text shown in command listings
+      # @param argument_hint [String] optional usage hint for arguments
+      # @yieldparam ui [Object] interactive controller with canvas and key API
+      # @yieldparam ctx [Context] plugin execution context
+      # @return [void]
+      # @api public
+      def interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", &block)
+        @registry.register_interactive_command(name, rows: rows, fps: fps, description: description, argument_hint: argument_hint, path: @path, &block)
+      end
     end
 
     # Mutable singleton guard used while loading trusted plugin files.
@@ -175,15 +234,20 @@ module Kward
     def initialize(reserved_commands: [])
       @reserved_commands = reserved_commands.map(&:to_s)
       @commands = {}
+      @interactive_commands = {}
       @footer = nil
       @footer_path = nil
       @transcript_event_handlers = []
       @prompt_context_renderers = []
+      @paths = []
     end
 
     # @return [String, nil] plugin file currently responsible for footer output
     attr_reader :footer_path
 
+    # @return [Array<String>] plugin files successfully loaded by this registry
+    attr_reader :paths
+
     def commands
       @commands.values
     end
@@ -192,6 +256,14 @@ module Kward
       @commands[name.to_s]
     end
 
+    def interactive_commands
+      @interactive_commands.values
+    end
+
+    def interactive_command_for(name)
+      @interactive_commands[name.to_s]
+    end
+
     def footer_renderer
       @footer
     end
@@ -233,6 +305,7 @@ module Kward
       self.class.loading_registry = self
       self.class.loading_path = path
       Kernel.load(path)
+      @paths << path
     rescue StandardError => e
       warn "Warning: skipping Kward plugin #{path}: #{e.message}"
     ensure
@@ -269,6 +342,31 @@ module Kward
       )
     end
 
+    def register_interactive_command(name, rows:, fps: 30, description: "", argument_hint: "", path: nil, &handler)
+      name = name.to_s
+      raise "Interactive command name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
+      raise "Interactive command /#{name} requires a handler" unless handler
+
+      if @reserved_commands.include?(name) || @commands.key?(name)
+        warn "Warning: skipping Kward interactive command /#{name}: reserved command"
+        return nil
+      end
+      if @interactive_commands.key?(name)
+        warn "Warning: skipping duplicate Kward interactive command /#{name}: #{path}"
+        return nil
+      end
+
+      @interactive_commands[name] = InteractiveCommand.new(
+        name: name,
+        description: description.to_s,
+        argument_hint: argument_hint.to_s,
+        rows: [[rows.to_i, 1].max, 1].max,
+        fps: [[fps.to_f, 1].max, 120].min,
+        path: path,
+        handler: handler
+      )
+    end
+
     def register_footer(path: nil, &renderer)
       raise "Plugin footer requires a renderer" unless renderer
 
@@ -329,6 +427,15 @@ module Kward
     end
   end
 
+  # Registers a trusted local plugin.
+  #
+  # This method is intended for Ruby files loaded from the user plugin
+  # directory. It raises if called outside plugin loading so workspace code
+  # cannot silently mutate Kward's runtime by merely being required.
+  #
+  # @yieldparam plugin [PluginRegistry::DSL] plugin registration DSL
+  # @return [Object, nil] the plugin block result
+  # @api public
   def self.plugin(&block)
     registry = PluginRegistry.loading_registry
     raise "Kward.plugin can only be called while loading a plugin" unless registry

data/lib/kward/project_files.rb

@@ -0,0 +1,52 @@
+require "find"
+require "open3"
+require "pathname"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Discovers project files for prompt UI features.
+  module ProjectFiles
+    module_function
+
+    def list(root: Dir.pwd)
+      paths = git_paths(root)
+      paths = scanned_paths(root) if paths.empty?
+      paths.reject { |path| path.empty? || path.end_with?("/") }.uniq.sort
+    end
+
+    def git_paths(root)
+      output, status = Open3.capture2("git", "ls-files", "--cached", "--others", "--exclude-standard", chdir: root)
+      return [] unless status.success?
+
+      output.lines.map(&:chomp).reject(&:empty?)
+    rescue StandardError
+      []
+    end
+
+    def scanned_paths(root)
+      root_path = Pathname.new(root)
+      paths = []
+      Find.find(root_path.to_s) do |path|
+        relative = Pathname.new(path).relative_path_from(root_path).to_s
+        if File.directory?(path)
+          Find.prune if ignored_directory?(relative)
+          next
+        end
+
+        paths << relative unless ignored_file?(relative)
+      end
+      paths
+    rescue StandardError
+      []
+    end
+
+    def ignored_directory?(relative)
+      ignored_directories = %w[.git .yardoc _yardoc node_modules rdoc tmp vendor/bundle]
+      ignored_directories.include?(relative) || relative.start_with?(".git/")
+    end
+
+    def ignored_file?(relative)
+      relative.start_with?(".git/")
+    end
+  end
+end

data/lib/kward/prompt_history.rb

@@ -0,0 +1,82 @@
+require "fileutils"
+require "json"
+require "time"
+require_relative "config_files"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Workspace-scoped JSONL persistence for terminal prompt history.
+  class PromptHistory
+    DEFAULT_LIMIT = 1_000
+
+    Entry = Struct.new(:value, :timestamp, keyword_init: true)
+
+    def initialize(config_dir: ConfigFiles.config_dir, cwd: Dir.pwd, limit: DEFAULT_LIMIT)
+      @config_dir = config_dir
+      @cwd = ConfigFiles.canonical_workspace_root(cwd)
+      @limit = limit.to_i.positive? ? limit.to_i : DEFAULT_LIMIT
+    end
+
+    attr_reader :cwd, :limit
+
+    def values
+      entries.map(&:value)
+    end
+
+    def append(value)
+      text = value.to_s
+      return false if text.strip.empty?
+
+      existing = entries
+      return false if existing.last&.value == text
+
+      write_entries((existing + [Entry.new(value: text, timestamp: Time.now.utc.iso8601(3))]).last(limit))
+      true
+    end
+
+    def path
+      ConfigFiles.prompt_history_path(@cwd, config_dir: @config_dir)
+    end
+
+    private
+
+    def entries
+      return [] unless File.file?(path)
+
+      File.readlines(path, chomp: true).filter_map do |line|
+        record = JSON.parse(line)
+        value = record["value"].to_s
+        next if value.strip.empty?
+
+        Entry.new(value: value, timestamp: record["timestamp"].to_s)
+      rescue JSON::ParserError
+        nil
+      end.last(limit)
+    rescue Errno::ENOENT
+      []
+    end
+
+    def write_entries(entries)
+      FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+        file.write(JSON.generate(history_header))
+        file.write("\n")
+        entries.each do |entry|
+          file.write(JSON.generate({ type: "prompt_history", version: 1, timestamp: entry.timestamp || Time.now.utc.iso8601(3), value: entry.value }))
+          file.write("\n")
+        end
+      end
+      File.chmod(0o600, path)
+    end
+
+    def history_header
+      {
+        type: "prompt_history_header",
+        version: 1,
+        workspace: @cwd,
+        workspaceHash: File.basename(path, ".jsonl"),
+        limit: limit
+      }
+    end
+  end
+end

data/lib/kward/prompt_interface/banner.rb

@@ -1,80 +1,45 @@
-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.
+  # Startup banner message renderer.
   class PromptInterface
     # Startup banner rendering data and helpers for the prompt interface.
     class Banner
-      LOGO_WIDTH = 32
-      LOGO_PIXEL_HEIGHT = 32
-      MIN_LOGO_HEIGHT = 4
-      LOGO_PIXELS = Kward::Resources::AvatarKwardLogo::PIXELS
       MESSAGE = "State your business.".freeze
 
-      def initialize(message:, pixels:, screen_height:, minimum_composer_rows: 3)
+      def initialize(message:, screen_height:, minimum_composer_rows: 3)
         @message = message.to_s
-        @pixels = pixels
         @screen_height = screen_height
         @minimum_composer_rows = minimum_composer_rows
-        @logo_cache = {}
       end
 
-      def rows(width)
-        return [] unless visible?(width)
+      def rows(width, message: nil)
+        content = message.nil? ? @message : message.to_s
+        return [] if content.empty? || max_banner_rows <= 0
 
-        rows = []
-        rows.concat(centered_image_rows(width)) if image_visible?(width)
-        rows << align_plain_row(@message, width) unless @message.empty?
-        rows << ""
-        rows
+        visible_lines(content) + [""]
       end
 
-      def logo_rows(width)
-        logo_width, logo_height = logo_dimensions(width)
-        return [] unless @pixels && max_logo_height >= MIN_LOGO_HEIGHT
-
-        key = [logo_width, logo_height]
-        @logo_cache[key] ||= Kward::PixelLogo.half_block_rows_from_pixels(@pixels, width: logo_width, pixel_height: logo_height)
+      def logo_rows(_width)
+        []
       end
 
       private
 
-      def visible?(width)
-        !@message.empty? || image_visible?(width)
-      end
-
-      def image_visible?(width)
-        !logo_rows(width).empty?
-      end
-
-      def centered_image_rows(width)
-        logo_width, = logo_dimensions(width)
-        padding = [[(width - logo_width) / 2, 0].max, width - 1].min
-        logo_rows(width).map { |row| (" " * padding) + row }
-      end
+      def visible_lines(content)
+        lines = content.lines(chomp: true)
+        return lines if lines.length <= max_banner_rows
+        return [lines.last] if max_banner_rows == 1
 
-      def logo_dimensions(width)
-        logo_width = [LOGO_WIDTH, [width - 2, 1].max].min
-        logo_height = [LOGO_PIXEL_HEIGHT, max_logo_height * 2].min
-        [logo_width, logo_height]
+        lines.first(max_banner_rows - 1) + [lines.last]
       end
 
-      def max_logo_height
-        message_rows = @message.empty? ? 0 : 1
-        blank_after_banner = 1
+      def max_banner_rows
         transcript_row = 1
-        reserved_rows = message_rows + blank_after_banner + @minimum_composer_rows + transcript_row
+        blank_after_banner = 1
+        reserved_rows = blank_after_banner + @minimum_composer_rows + transcript_row
         [@screen_height.call - reserved_rows, 0].max
       end
 
-      def align_plain_row(text, width)
-        plain_length = ANSI.strip(text).length
-        padding = [width - plain_length, 0].max / 2
-        (" " * padding) + text.to_s
-      end
     end
   end
 end