kward 0.71.0 → 0.72.0

data/lib/kward/ekwsh.rb

@@ -0,0 +1,362 @@
+require "open3"
+require "shellwords"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Kward-native embedded shell command runner.
+  class Ekwsh
+    Result = Struct.new(:output, :exit_status, :exit_shell, :clear, :open_editor_path, keyword_init: true)
+    Completion = Struct.new(:range, :replacement, :candidates, keyword_init: true)
+    BUILTINS = %w[alias cd pwd export unset clear exit logout].freeze
+
+    attr_reader :cwd
+
+    def initialize(cwd: Dir.pwd, env: ENV.to_h, shell: ENV["SHELL"], configured_env: {}, aliases: {})
+      @cwd = File.expand_path(cwd.to_s.empty? ? Dir.pwd : cwd.to_s)
+      @previous_cwd = nil
+      @env = env.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+      @env.merge!(configured_env.to_h.transform_keys(&:to_s).transform_values(&:to_s))
+      @env["PWD"] = @cwd
+      configure_rbenv_environment
+      configure_color_environment
+      @aliases = aliases.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+      @shell = shell.to_s.empty? ? "/bin/sh" : shell.to_s
+    end
+
+    def prompt_label
+      "Shell #{display_cwd} $"
+    end
+
+    def run(input)
+      command = input.to_s.strip
+      return Result.new(output: "", exit_status: 0) if command.empty?
+      return Result.new(output: command_echo(command), exit_status: 0, exit_shell: true) if exit_command?(command)
+
+      builtin_result(command) || run_expanded_command(command)
+    end
+
+    def complete(input, cursor)
+      token = completion_token(input.to_s, cursor.to_i)
+      return nil if token[:command] && token[:text].empty?
+
+      candidates = if token[:command] && !path_like_token?(token[:text])
+                     command_candidates(token[:text])
+                   else
+                     path_candidates(token[:text], directories_only: cd_completion?(input, token))
+                   end
+      return nil if candidates.empty?
+
+      replacement = completion_replacement(token[:text], candidates)
+      Completion.new(range: token[:range], replacement: replacement, candidates: candidates)
+    end
+
+    private
+
+    def configure_rbenv_environment
+      root = @env["RBENV_ROOT"].to_s
+      root = File.expand_path("~/.rbenv") if root.empty?
+      root = File.expand_path(root)
+      paths = [File.join(root, "shims"), File.join(root, "bin")].select { |path| Dir.exist?(path) }
+      return if paths.empty?
+
+      @env["RBENV_ROOT"] = root
+      @env["PATH"] = prepend_path_entries(@env["PATH"], paths)
+    rescue ArgumentError
+      nil
+    end
+
+    def prepend_path_entries(path, entries)
+      current = path.to_s.split(File::PATH_SEPARATOR)
+      (entries + current).uniq.join(File::PATH_SEPARATOR)
+    end
+
+    def configure_color_environment
+      @env["CLICOLOR"] ||= "1"
+      @env["COLORTERM"] ||= "truecolor"
+      @env["TERM"] = "xterm-256color" if @env["TERM"].to_s.empty? || @env["TERM"] == "dumb"
+    end
+
+    def completion_token(input, cursor)
+      cursor = [[cursor, 0].max, input.length].min
+      start_index = cursor
+      start_index -= 1 while start_index.positive? && token_character?(input, start_index - 1)
+      text = input[start_index...cursor].to_s
+      before = input[0...start_index].to_s
+      { range: (start_index...cursor), text: text, command: before.strip.empty? }
+    end
+
+    def token_character?(input, index)
+      return true unless input[index].match?(/\s/)
+
+      escaped_character?(input, index)
+    end
+
+    def escaped_character?(input, index)
+      backslashes = 0
+      cursor = index - 1
+      while cursor >= 0 && input[cursor] == "\\"
+        backslashes += 1
+        cursor -= 1
+      end
+      backslashes.odd?
+    end
+
+    def cd_completion?(input, token)
+      input[0...token[:range].begin].to_s.strip == "cd"
+    end
+
+    def path_like_token?(text)
+      text.to_s.include?("/")
+    end
+
+    def command_candidates(prefix)
+      (BUILTINS + @aliases.keys + path_executables).uniq.grep(/\A#{Regexp.escape(prefix)}/).sort
+    end
+
+    def path_executables
+      @env.fetch("PATH", "").split(File::PATH_SEPARATOR).flat_map do |path|
+        next [] unless File.directory?(path)
+
+        Dir.children(path).filter_map do |entry|
+          full_path = File.join(path, entry)
+          entry if File.file?(full_path) && File.executable?(full_path)
+        end
+      rescue SystemCallError
+        []
+      end
+    end
+
+    def path_candidates(prefix, directories_only: false)
+      raw_dir, raw_base = split_path_prefix(prefix)
+      dir = File.expand_path(unescape_path(raw_dir.empty? ? "." : raw_dir), @cwd)
+      return [] unless File.directory?(dir)
+
+      Dir.children(dir).filter_map do |entry|
+        next unless entry.start_with?(unescape_path(raw_base))
+
+        path = File.join(dir, entry)
+        directory = File.directory?(path)
+        next if directories_only && !directory
+
+        completed = "#{raw_dir}#{Shellwords.escape(entry)}"
+        completed = "#{completed}/" if directory
+        completed
+      end.sort
+    rescue SystemCallError
+      []
+    end
+
+    def split_path_prefix(prefix)
+      index = prefix.rindex("/")
+      return ["", prefix] unless index
+
+      [prefix[0..index], prefix[(index + 1)..].to_s]
+    end
+
+    def unescape_path(value)
+      value.to_s.gsub(/\\(.)/, "\\1")
+    end
+
+    def completion_replacement(prefix, candidates)
+      return add_completion_suffix(candidates.first) if candidates.length == 1
+
+      common = common_prefix(candidates)
+      common.length > prefix.length ? common : prefix
+    end
+
+    def add_completion_suffix(candidate)
+      candidate.end_with?("/") ? candidate : "#{candidate} "
+    end
+
+    def common_prefix(values)
+      first = values.first.to_s
+      values.drop(1).reduce(first) do |prefix, value|
+        prefix = prefix[0...-1] until value.start_with?(prefix) || prefix.empty?
+        prefix
+      end
+    end
+
+    def display_cwd
+      home = Dir.home.to_s
+      return "~" if @cwd == home
+      return "~#{@cwd.delete_prefix(home)}" if !home.empty? && @cwd.start_with?("#{home}/")
+
+      @cwd
+    rescue ArgumentError
+      @cwd
+    end
+
+    def command_echo(command)
+      "$ #{command}\n"
+    end
+
+    def exit_command?(command)
+      ["exit", "logout"].include?(command)
+    end
+
+    def builtin_result(command)
+      words = shell_words(command)
+      return nil if words.empty?
+
+      case words.first
+      when "alias"
+        list_aliases(command, words)
+      when "cd"
+        change_directory(command, words)
+      when "pwd"
+        Result.new(output: "#{command_echo(command)}#{@cwd}\n", exit_status: 0)
+      when "export"
+        export_variables(command, words)
+      when "unset"
+        unset_variables(command, words)
+      when "clear"
+        Result.new(output: "", exit_status: 0, clear: true)
+      else
+        nil
+      end
+    rescue ArgumentError => e
+      Result.new(output: "#{command_echo(command)}ekwsh: #{e.message}\n", exit_status: 2)
+    end
+
+    def shell_words(command)
+      Shellwords.shellsplit(command)
+    end
+
+    def list_aliases(command, words)
+      assignments, names = words.drop(1).partition { |word| word.include?("=") }
+      invalid = []
+      assignments.each do |assignment|
+        name, value = assignment.split("=", 2)
+        if valid_alias_name?(name)
+          @aliases[name] = value.to_s
+        else
+          invalid << name
+        end
+      end
+      return Result.new(output: "#{command_echo(command)}ekwsh: alias: invalid name: #{invalid.join(" ")}\n", exit_status: 2) unless invalid.empty?
+
+      names = @aliases.keys.sort if names.empty? && assignments.empty?
+      lines = names.filter_map { |name| @aliases[name] ? "#{name}=#{Shellwords.escape(@aliases.fetch(name))}" : nil }
+      suffix = lines.empty? ? "" : "#{lines.join("\n")}\n"
+      Result.new(output: "#{command_echo(command)}#{suffix}", exit_status: 0)
+    end
+
+    def valid_alias_name?(name)
+      name.to_s.match?(/\A[A-Za-z_][A-Za-z0-9_-]*\z/) && !BUILTINS.include?(name.to_s)
+    end
+
+    def expand_alias(command)
+      words = shell_words(command)
+      return command if words.empty? || BUILTINS.include?(words.first)
+      return command unless @aliases[words.first]
+
+      rest = command.sub(/\A\s*#{Regexp.escape(words.first)}\b\s*/, "")
+      [@aliases.fetch(words.first), rest].reject(&:empty?).join(" ")
+    rescue ArgumentError
+      command
+    end
+
+    def run_expanded_command(command)
+      expanded_command = expand_alias(command)
+      kward_result = kward_command_result(expanded_command, display_command: command)
+      return kward_result if kward_result
+
+      execute(expanded_command, display_command: command)
+    end
+
+    def kward_command_result(command, display_command: command)
+      words = shell_words(command)
+      return nil unless kward_edit_command?(words)
+
+      unless words.length == 3
+        return Result.new(output: "#{command_echo(display_command)}Usage: kward edit <filename>\n", exit_status: 2)
+      end
+
+      path = File.expand_path(words[2], @cwd)
+      Result.new(output: command_echo(display_command), exit_status: 0, open_editor_path: path)
+    rescue ArgumentError => e
+      Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 2)
+    end
+
+    def kward_edit_command?(words)
+      return false unless words[1] == "edit"
+
+      File.basename(words[0].to_s) == "kward"
+    end
+
+    def change_directory(command, words)
+      target = words[1]
+      target = Dir.home if target.nil? || target.empty?
+      target = @previous_cwd || @cwd if target == "-"
+      path = File.expand_path(target, @cwd)
+      unless File.directory?(path)
+        return Result.new(output: "#{command_echo(command)}ekwsh: cd: no such directory: #{target}\n", exit_status: 1)
+      end
+
+      @previous_cwd = @cwd
+      @cwd = path
+      @env["OLDPWD"] = @previous_cwd
+      @env["PWD"] = @cwd
+      output = command_echo(command)
+      output << "#{@cwd}\n" if words[1] == "-"
+      Result.new(output: output, exit_status: 0)
+    end
+
+    def export_variables(command, words)
+      if words.length == 1
+        lines = @env.keys.sort.map { |key| "export #{key}=#{Shellwords.escape(@env.fetch(key))}" }
+        return Result.new(output: "#{command_echo(command)}#{lines.join("\n")}\n", exit_status: 0)
+      end
+
+      invalid = []
+      words.drop(1).each do |assignment|
+        key, value = assignment.split("=", 2)
+        if value.nil? || !valid_env_key?(key)
+          invalid << assignment
+        else
+          @env[key] = value
+        end
+      end
+
+      if invalid.empty?
+        Result.new(output: command_echo(command), exit_status: 0)
+      else
+        Result.new(output: "#{command_echo(command)}ekwsh: export: invalid assignment: #{invalid.join(" ")}\n", exit_status: 2)
+      end
+    end
+
+    def unset_variables(command, words)
+      invalid = words.drop(1).reject { |key| valid_env_key?(key) }
+      words.drop(1).each { |key| @env.delete(key) if valid_env_key?(key) }
+
+      if invalid.empty?
+        Result.new(output: command_echo(command), exit_status: 0)
+      else
+        Result.new(output: "#{command_echo(command)}ekwsh: unset: invalid name: #{invalid.join(" ")}\n", exit_status: 2)
+      end
+    end
+
+    def valid_env_key?(key)
+      key.to_s.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+    end
+
+    def execute(command, display_command: command)
+      stdout, stderr, status = Open3.capture3(@env, @shell, "-c", command, chdir: @cwd)
+      exit_status = status.exitstatus || 1
+      output = command_echo(display_command)
+      output << clean_output(stdout)
+      output << clean_output(stderr)
+      output << "Exit status: #{exit_status}\n" unless exit_status.zero?
+      Result.new(output: output, exit_status: exit_status)
+    rescue Errno::ENOENT => e
+      Result.new(output: "#{command_echo(display_command)}ekwsh: #{e.message}\n", exit_status: 127)
+    end
+
+    def clean_output(value)
+      text = value.to_s.dup
+      text.force_encoding(Encoding::UTF_8)
+      text = text.valid_encoding? ? text : text.scrub
+      text.end_with?("\n") || text.empty? ? text : "#{text}\n"
+    end
+  end
+end

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
@@ -167,6 +176,24 @@ module Kward
       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.
@@ -207,6 +234,7 @@ module Kward
     def initialize(reserved_commands: [])
       @reserved_commands = reserved_commands.map(&:to_s)
       @commands = {}
+      @interactive_commands = {}
       @footer = nil
       @footer_path = nil
       @transcript_event_handlers = []
@@ -228,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
@@ -306,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
 

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