kward 0.70.0 → 0.72.0

data/examples/plugins/space_invaders.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+# Space Invaders — a full classic arcade game built as a Kward interactive
+# plugin command.
+#
+# Install: copy this file to ~/.kward/plugins/ and run `/invaders` in the
+# Kward TUI.
+#
+# Controls:
+#   ←/→  Move
+#   Space  Fire
+#   Q / Esc  Quit
+#   Ctrl+C  Force quit (handled by Kward)
+#
+# The game renders colored sprites and particle-burst explosions inside the
+# composer canvas region using the interactive mode API.
+
+Kward.plugin do |plugin|
+  plugin.interactive_command "invaders", rows: 18, fps: 30, description: "Space Invaders arcade game" do |ui, ctx|
+    game = SpaceInvadersGame.new(width: ui.width, height: ui.height)
+    ui.on_tick { |ui| game.tick(ui) }
+  end
+end
+
+# rubocop:disable Metrics/ClassLength, Metrics/MethodLength
+class SpaceInvadersGame
+  PLAYER_CHAR = "▲"
+  PLAYER_COLOR = :cyan
+  BULLET_CHAR = "│"
+  BULLET_COLOR = :yellow
+  BOMB_CHAR = "V"
+  BOMB_COLOR = :magenta
+  SCORE_LABEL = "Score"
+  LIVES_LABEL = "Lives"
+
+  INVADER_ROWS = [
+    { char: "M", color: :red,    points: 30 },
+    { char: "M", color: :red,    points: 30 },
+    { char: "W", color: :yellow, points: 20 },
+    { char: "W", color: :yellow, points: 20 },
+    { char: "A", color: :green,  points: 10 }
+  ].freeze
+
+  PARTICLE_CHARS = %w[* + . o].freeze
+  PARTICLE_COLORS = %i[red yellow].freeze
+  PARTICLE_LIFE = 6
+
+  MOVE_EVERY = 12
+  BULLET_SPEED = 2
+  BOMB_SPEED = 1
+  MAX_BULLETS = 3
+  FIRE_COOLDOWN = 8
+  BOMB_CHANCE = 0.015
+
+  def initialize(width:, height:)
+    @width = width
+    @height = height
+    @phase = :playing
+    @tick_count = 0
+    @score = 0
+    @lives = 3
+    @wave = 1
+    @fire_cooldown = 0
+    @invader_dir = 1
+    @invaders = []
+    @bullets = []
+    @bombs = []
+    @explosions = []
+    @message_timer = 0
+    spawn_invaders
+    place_player
+  end
+
+  def tick(ui)
+    drain_keys(ui)
+    case @phase
+    when :playing
+      update_playing
+      render_playing(ui)
+    when :game_over, :won
+      update_message_phase
+      render_message(ui)
+    end
+    ui.render
+  end
+
+  private
+
+  def drain_keys(ui)
+    while (key = ui.poll_key)
+      case key
+      when :escape, "q", "Q"
+        ui.exit
+      when :left
+        @player_col -= 1 if @phase == :playing
+      when :right
+        @player_col += 1 if @phase == :playing
+      when :space
+        fire_bullet if @phase == :playing
+      when :return, :enter
+        restart if @phase != :playing
+      end
+    end
+  end
+
+  def place_player
+    @player_col = @width / 2
+    @player_row = @height - 2
+  end
+
+  # ---- Invader spawning ----
+
+  def spawn_invaders
+    @invaders = []
+    rows = INVADER_ROWS.length
+    cols = [(@width - 4) / 4, 6].min
+    cols = [cols, 3].max
+    start_row = 2
+    start_col = (@width - cols * 4) / 2
+    start_col = [start_col, 1].max
+
+    rows.times do |row|
+      config = INVADER_ROWS[row]
+      cols.times do |col|
+        @invaders << {
+          row: start_row + row,
+          col: start_col + col * 4,
+          char: config[:char],
+          color: config[:color],
+          points: config[:points],
+          alive: true
+        }
+      end
+    end
+    @invader_dir = 1
+  end
+
+  # ---- Playing phase updates ----
+
+  def update_playing
+    @tick_count += 1
+    @fire_cooldown = [@fire_cooldown - 1, 0].max if @fire_cooldown.positive?
+
+    move_invaders if (@tick_count % move_interval).zero?
+    move_bullets
+    move_bombs
+    maybe_drop_bomb
+    update_explosions
+    check_collisions
+    check_win_lose
+  end
+
+  def move_interval
+    alive = @invaders.count { |inv| inv[:alive] }
+    total = @invaders.length
+    return MOVE_EVERY if total.zero?
+
+    speedup = ((total - alive) * MOVE_EVERY) / (total * 2)
+    [MOVE_EVERY - speedup, 2].max
+  end
+
+  def move_invaders
+    living = @invaders.select { |inv| inv[:alive] }
+    return if living.empty?
+
+    min_col = living.map { |inv| inv[:col] }.min
+    max_col = living.map { |inv| inv[:col] }.max
+
+    if @invader_dir.positive? && max_col >= @width - 2
+      @invader_dir = -1
+      @invaders.each { |inv| inv[:row] += 1 if inv[:alive] }
+    elsif @invader_dir.negative? && min_col <= 1
+      @invader_dir = 1
+      @invaders.each { |inv| inv[:row] += 1 if inv[:alive] }
+    else
+      @invaders.each { |inv| inv[:col] += @invader_dir if inv[:alive] }
+    end
+  end
+
+  def fire_bullet
+    return if @bullets.length >= MAX_BULLETS
+    return if @fire_cooldown.positive?
+
+    @bullets << { row: @player_row - 1, col: @player_col }
+    @fire_cooldown = FIRE_COOLDOWN
+  end
+
+  def move_bullets
+    @bullets.each { |b| b[:row] -= BULLET_SPEED }
+    @bullets.reject! { |b| b[:row] < 0 }
+  end
+
+  def move_bombs
+    @bombs.each { |b| b[:row] += BOMB_SPEED }
+    @bombs.reject! { |b| b[:row] >= @height }
+  end
+
+  def maybe_drop_bomb
+    return if rand > BOMB_CHANCE
+
+    living = @invaders.select { |inv| inv[:alive] }
+    return if living.empty?
+
+    # Drop from a random bottom-most invader per column
+    columns = living.group_by { |inv| inv[:col] }
+    col, invaders = columns.min_by { rand }
+    return unless invaders
+
+    bottom = invaders.max_by { |inv| inv[:row] }
+    @bombs << { row: bottom[:row] + 1, col: bottom[:col] } if bottom
+  end
+
+  # ---- Explosions ----
+
+  def spawn_explosion(row, col, color = :red)
+    PARTICLE_LIFE.times do |i|
+      angle = (i * 360 / PARTICLE_LIFE) * Math::PI / 180
+      dx = (Math.cos(angle) * (i + 1)).round
+      dy = (Math.sin(angle) * (i + 1)).round
+      @explosions << {
+        row: row + dy,
+        col: col + dx,
+        char: PARTICLE_CHARS[i % PARTICLE_CHARS.length],
+        color: PARTICLE_COLORS[i % PARTICLE_COLORS.length],
+        life: PARTICLE_LIFE
+      }
+    end
+  end
+
+  def update_explosions
+    @explosions.each { |e| e[:life] -= 1 }
+    @explosions.reject! { |e| e[:life] <= 0 }
+  end
+
+  # ---- Collisions ----
+
+  def check_collisions
+    check_bullet_invader_hits
+    check_bomb_player_hits
+  end
+
+  def check_bullet_invader_hits
+    @bullets.reject! do |bullet|
+      hit = @invaders.find { |inv| inv[:alive] && inv[:row] == bullet[:row] && inv[:col] == bullet[:col] }
+      next false unless hit
+
+      hit[:alive] = false
+      @score += hit[:points]
+      spawn_explosion(hit[:row], hit[:col], hit[:color])
+      true
+    end
+  end
+
+  def check_bomb_player_hits
+    @bombs.reject! do |bomb|
+      hit = bomb[:row] == @player_row && bomb[:col] == @player_col
+      next false unless hit
+
+      @lives -= 1
+      spawn_explosion(@player_row, @player_col, :cyan)
+      @phase = :game_over if @lives <= 0
+      true
+    end
+  end
+
+  def check_win_lose
+    return unless @phase == :playing
+
+    @phase = :won if @invaders.none? { |inv| inv[:alive] }
+
+    return unless @invaders.any? { |inv| inv[:alive] && inv[:row] >= @player_row }
+
+    @phase = :game_over
+    spawn_explosion(@player_row, @player_col, :cyan)
+  end
+
+  # ---- Message phase ----
+
+  def update_message_phase
+    @message_timer += 1
+  end
+
+  def restart
+    @score = 0
+    @lives = 3
+    @wave = 1
+    @tick_count = 0
+    @bullets.clear
+    @bombs.clear
+    @explosions.clear
+    @fire_cooldown = 0
+    @invader_dir = 1
+    spawn_invaders
+    place_player
+    @phase = :playing
+    @message_timer = 0
+  end
+
+  # ---- Rendering ----
+
+  def render_playing(ui)
+    ui.clear_frame
+
+    render_hud(ui)
+    render_invaders(ui)
+    render_bullets(ui)
+    render_bombs(ui)
+    render_explosions(ui)
+    ui.put(@player_row, @player_col, PLAYER_CHAR, PLAYER_COLOR)
+  end
+
+  def render_hud(ui)
+    score_text = "#{SCORE_LABEL}: #{@score}"
+    lives_text = "#{LIVES_LABEL}: #{@lives}"
+    wave_text = "Wave: #{@wave}"
+
+    score_text.chars.each_with_index do |char, i|
+      ui.put(0, i, char, :green)
+    end
+    lives_col = @width - lives_text.length
+    lives_text.chars.each_with_index do |char, i|
+      ui.put(0, lives_col + i, char, :cyan)
+    end
+    wave_col = (@width - wave_text.length) / 2
+    wave_text.chars.each_with_index do |char, i|
+      ui.put(0, wave_col + i, char, :gray)
+    end
+  end
+
+  def render_invaders(ui)
+    @invaders.each do |inv|
+      next unless inv[:alive]
+
+      ui.put(inv[:row], inv[:col], inv[:char], inv[:color])
+    end
+  end
+
+  def render_bullets(ui)
+    @bullets.each { |b| ui.put(b[:row], b[:col], BULLET_CHAR, BULLET_COLOR) }
+  end
+
+  def render_bombs(ui)
+    @bombs.each { |b| ui.put(b[:row], b[:col], BOMB_CHAR, BOMB_COLOR) }
+  end
+
+  def render_explosions(ui)
+    @explosions.each do |e|
+      ui.put(e[:row], e[:col], e[:char], e[:color])
+    end
+  end
+
+  def render_message(ui)
+    ui.clear_frame
+    render_invaders(ui)
+    render_explosions(ui)
+
+    if @phase == :won
+      message = "YOU WIN!"
+      color = :green
+    else
+      message = "GAME OVER"
+      color = :red
+    end
+
+    center_text(ui, @height / 2, message, color)
+    center_text(ui, @height / 2 + 2, "Score: #{@score}", :yellow)
+    center_text(ui, @height / 2 + 4, "Enter: restart  Q: quit", :gray)
+  end
+
+  def center_text(ui, row, text, color)
+    col = (@width - text.length) / 2
+    text.chars.each_with_index do |char, i|
+      ui.put(row, col + i, char, color)
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength, Metrics/MethodLength

data/lib/kward/agent.rb

@@ -31,7 +31,7 @@ module Kward
       @telemetry_logger = telemetry_logger
     end
 
-    attr_reader :conversation
+    attr_reader :conversation, :tool_registry
 
     # Adds a user message, compacts context when needed, and runs the turn.
     #

data/lib/kward/cli/commands.rb

@@ -48,11 +48,14 @@ module Kward
           #{heading.call("Usage")}
             #{command.call("kward")}                              Start an interactive chat
             #{command.call("kward")} #{option.call('"Explain this project"')}       Run a one-shot prompt
+            #{command.call("kward --filter")} #{option.call('"Translate"')}          Filter stdin with an instruction
             #{command.call("kward login")}                        Sign in or save provider credentials
             #{command.call("kward auth status")}                  Show saved credential status
             #{command.call("kward init")}                         Install starter prompts and PRINCIPLES.md
             #{command.call("kward doctor")}                       Check local Kward setup
+            #{command.call("kward edit")} #{option.call("<filename>")}              Open a file in the integrated editor
             #{command.call("kward sysprompt")}                    Inspect the effective system prompt
+            #{command.call("kward openrouter refresh")}           Refresh cached OpenRouter models
             #{command.call("kward pan")}                          Start Pan mode web UI
             #{command.call("kward rpc")}                          Start the experimental JSON-RPC backend
 
@@ -63,21 +66,28 @@ module Kward
             #{command.call("auth status|logout")}                 Show or clear saved credentials
             #{command.call("init")}                               Install starter prompts and PRINCIPLES.md
             #{command.call("doctor")}                             Check local Kward setup
+            #{command.call("edit")} #{option.call("<filename>")}                  Open a file in the integrated editor
             #{command.call("sysprompt")} [--raw]                  Inspect the effective system prompt
             #{command.call("stats tokens")} [range] [options]      Export local token telemetry as CSV
+            #{command.call("openrouter refresh|list")}             Refresh or list cached OpenRouter models
             #{command.call("pan")}                                Start Pan mode web UI
             #{command.call("rpc")}                                Run the JSON-RPC backend for UI clients
 
           #{heading.call("Options")}
             #{option.call("--working-directory=PATH")}             Run Kward from PATH
+            #{option.call("--mode=MODE")}                          Execution mode: auto, chat, oneshot, filter
+            #{option.call("--filter")}                              Shortcut for --mode filter
             #{option.call("--help")}, #{option.call("-h")}                         Show this help
             #{option.call("--version")}, #{option.call("-v")}                      Show the installed version
 
           #{heading.call("Examples")}
             #{command.call("kward")}
-            #{command.call("kward")} #{option.call('"Review this diff"')}
-            #{command.call("git diff | kward")} #{option.call('"Review this diff"')}
+            #{command.call("kward")} #{option.call('"Explain this project"')}
+            #{command.call("git diff | kward")} #{option.call('"Summarize the main changes"')}
+            #{command.call("echo Hello | kward --filter")} #{option.call('"Translate to German"')}
             #{command.call("kward login openrouter")}
+            #{command.call("kward edit lib/main.rb")}
+            #{command.call("kward openrouter refresh")}
             #{command.call("kward stats tokens today --bucket hour")}
 
           Command names take precedence. Anything else is sent as a one-shot prompt.
@@ -116,6 +126,11 @@ module Kward
             description: "Check local Kward configuration, workspace, auth hints, and writable directories.",
             examples: ["kward doctor", "kward --working-directory ~/code/project doctor"]
           },
+          "edit" => {
+            usage: "kward edit <filename>",
+            description: "Open a file in the integrated editor.",
+            examples: ["kward edit lib/main.rb", "kward edit ~/notes/todo.md"]
+          },
           "sysprompt" => {
             usage: "kward sysprompt [--raw]",
             description: "Inspect the effective system prompt for a new conversation in the current workspace.",
@@ -126,6 +141,11 @@ module Kward
             description: "Export local token telemetry as CSV.",
             examples: ["kward stats tokens today", "kward stats tokens today --bucket hour", "kward stats tokens week --output tokens.csv"]
           },
+          "openrouter" => {
+            usage: "kward openrouter refresh|list",
+            description: "Refresh or list cached text-capable OpenRouter models available to your API key.",
+            examples: ["kward openrouter refresh", "kward openrouter --refresh", "kward openrouter list"]
+          },
           "pan" => {
             usage: "kward pan",
             description: "Start Pan mode, a minimal LAN web UI with a prompt textarea and transcript.",
@@ -192,6 +212,17 @@ module Kward
             @prompt_delimited = true
             remaining.concat(arguments[(index + 1)..] || [])
             break
+          when "--experimental-workers"
+            @experimental_workers = true
+          when "--filter"
+            @requested_mode = "filter"
+          when "--mode"
+            index += 1
+            raise ArgumentError, "Missing value for --mode" if index >= arguments.length
+
+            @requested_mode = normalized_execution_mode(arguments[index])
+          when /\A--mode=(.*)\z/
+            @requested_mode = normalized_execution_mode(Regexp.last_match(1))
           when "--working-directory"
             index += 1
             raise ArgumentError, "Missing value for --working-directory" if index >= arguments.length
@@ -207,6 +238,14 @@ module Kward
         remaining
       end
 
+      def normalized_execution_mode(value)
+        mode = value.to_s.strip.downcase
+        modes = ["auto", "chat", "oneshot", "filter"]
+        raise ArgumentError, "Unknown mode: #{value}. Expected one of: #{modes.join(", ")}" unless modes.include?(mode)
+
+        mode
+      end
+
       def expanded_working_directory(path)
         value = path.to_s.strip
         raise ArgumentError, "Missing value for --working-directory" if value.empty?

data/lib/kward/cli/git.rb

@@ -0,0 +1,150 @@
+require "open3"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Command-line frontend that coordinates terminal interaction, sessions, tools, and model turns.
+  class CLI
+    # Interactive Git status and commit helpers.
+    module GitCommands
+      private
+
+      def handle_git_command(agent)
+        unless @prompt.respond_to?(:git_commit_message)
+          runtime_output("/git is available in the interactive overlay only.")
+          return
+        end
+
+        root = interactive_workspace_root(agent)
+        git_root = git_repository_root(root)
+        if git_root.empty?
+          runtime_output("Not a Git repository: #{root}")
+          return
+        end
+
+        status = git_status_lines(git_root)
+        message = @prompt.git_commit_message(status) do |action|
+          result = handle_git_prompt_action(git_root, status, action)
+          status = result.is_a?(Hash) && result.key?(:status_lines) ? result[:status_lines] : result
+          result
+        end
+        return if message.nil?
+
+        result = run_busy_local_command_and_requeue(activity: "committing") do
+          git_commit(git_root, message)
+        end
+        print_git_commit_result(result)
+      end
+
+      def git_repository_root(root)
+        output, status = Open3.capture2e("git", "rev-parse", "--show-toplevel", chdir: root.to_s)
+        return "" unless status.success?
+
+        output.lines.first.to_s.strip
+      rescue StandardError
+        ""
+      end
+
+      def git_status_lines(root)
+        output, status = Open3.capture2e("git", "status", "--short", "--untracked-files=normal", chdir: root.to_s)
+        return ["Unable to read Git status: #{output.strip}"] unless status.success?
+
+        output.lines.map(&:chomp)
+      rescue StandardError => e
+        ["Unable to read Git status: #{e.message}"]
+      end
+
+      def handle_git_prompt_action(root, current_status, action)
+        case action[:action]
+        when :toggle_stage
+          toggle_git_stage(root, current_status[action[:index].to_i])
+          git_status_lines(root)
+        when :open_diff
+          status_line = current_status[action[:index].to_i]
+          { status_lines: git_status_lines(root), diff: git_diff_view(root, status_line) }
+        else
+          git_status_lines(root)
+        end
+      end
+
+      def git_diff_view(root, status_line)
+        entry = parse_git_status_line(status_line)
+        return { path: "Git diff", content: "Unable to read Git status entry.\n" } if entry.nil?
+
+        output = entry[:untracked] ? git_untracked_file_diff(root, entry[:path]) : git_tracked_file_diff(root, entry[:path])
+        { path: entry[:path], content: output.empty? ? "No diff for #{entry[:path]}\n" : output }
+      end
+
+      def git_tracked_file_diff(root, path)
+        output, status = Open3.capture2e("git", "diff", "HEAD", "--", path, chdir: root.to_s)
+        status.success? ? output : "Unable to read diff for #{path}:\n#{output}"
+      rescue StandardError => e
+        "Unable to read diff for #{path}: #{e.message}\n"
+      end
+
+      def git_untracked_file_diff(root, path)
+        full_path = File.expand_path(path, root.to_s)
+        content = File.file?(full_path) ? File.read(full_path) : ""
+        lines = ["diff --git a/#{path} b/#{path}", "new file mode 100644", "--- /dev/null", "+++ b/#{path}", "@@ -0,0 +1,#{content.lines.length} @@"]
+        lines.concat(content.lines(chomp: true).map { |line| "+#{line}" })
+        lines << "\" if !content.empty? && !content.end_with?("\n")
+        lines.join("\n") + "\n"
+      rescue StandardError => e
+        "Unable to read diff for #{path}: #{e.message}\n"
+      end
+
+      def toggle_git_stage(root, status_line)
+        entry = parse_git_status_line(status_line)
+        return if entry.nil?
+
+        command = entry[:staged] ? ["restore", "--staged", "--", entry[:path]] : ["add", "--", entry[:path]]
+        Open3.capture2e("git", *command, chdir: root.to_s)
+      rescue StandardError
+        nil
+      end
+
+      def parse_git_status_line(line)
+        text = line.to_s
+        return nil if text.length < 4
+
+        status = text[0, 2]
+        path = text[3..].to_s
+        path = path.split(" -> ", 2).last if status.include?("R") || status.include?("C")
+        return nil if path.empty?
+
+        { path: path, staged: status[0] != " " && status[0] != "?", untracked: status == "??" }
+      end
+
+      def git_commit(root, message)
+        return git_commit_staged(root, message) if git_staged_changes?(root)
+
+        add_output, add_status = Open3.capture2e("git", "add", "--all", chdir: root.to_s)
+        return { success: false, output: add_output } unless add_status.success?
+
+        git_commit_staged(root, message)
+      rescue StandardError => e
+        { success: false, output: e.message }
+      end
+
+      def git_staged_changes?(root)
+        _output, status = Open3.capture2e("git", "diff", "--cached", "--quiet", chdir: root.to_s)
+        !status.success?
+      rescue StandardError
+        false
+      end
+
+      def git_commit_staged(root, message)
+        commit_output, commit_status = Open3.capture2e("git", "commit", "-m", message.to_s, chdir: root.to_s)
+        { success: commit_status.success?, output: commit_output }
+      rescue StandardError => e
+        { success: false, output: e.message }
+      end
+
+      def print_git_commit_result(result)
+        output = result[:output].to_s.strip
+        output = result[:success] ? "Commit created." : "Git commit failed." if output.empty?
+        status = result[:success] ? "Git commit succeeded" : "Git commit failed"
+        runtime_output("#{status}\n#{output}")
+      end
+    end
+  end
+end