kward 0.84.0 → 0.85.0

data/lib/kward/cli.rb

@@ -3,26 +3,26 @@ require "json"
 require "thread"
 require "tty-prompt"
 require_relative "agent"
-require_relative "ansi"
+require_relative "terminal/ansi"
 require_relative "version"
 require_relative "model/client"
 require_relative "compactor"
 require_relative "config_files"
-require_relative "clipboard"
+require_relative "terminal/clipboard"
 require_relative "cancellation"
-require_relative "editor_prompt"
-require_relative "editor_prompt_session"
-require_relative "shell_prompt"
-require_relative "shell_prompt_session"
-require_relative "cli_transcript_formatter"
+require_relative "cli/editor_prompt"
+require_relative "cli/editor_prompt_session"
+require_relative "shell/prompt"
+require_relative "shell/prompt_session"
+require_relative "cli/transcript_formatter"
 require_relative "model/context_usage"
 require_relative "events"
-require_relative "export_path"
-require_relative "kwsh"
-require_relative "persistent_shell_session"
-require_relative "interactive_pty_runner"
-require_relative "adaptive_pty_output_sink"
-require_relative "pty_transcript_normalizer"
+require_relative "transcripts/export_path"
+require_relative "shell/kwsh"
+require_relative "shell/persistent_session"
+require_relative "pty/interactive_runner"
+require_relative "pty/adaptive_output_sink"
+require_relative "pty/transcript_normalizer"
 require_relative "auth/anthropic_oauth"
 require_relative "auth/api_key_store"
 require_relative "auth/github_oauth"
@@ -30,7 +30,7 @@ require_relative "auth/openrouter_api_key"
 require_relative "image_attachments"
 require_relative "memory/manager"
 require_relative "memory/turn_context"
-require_relative "transcript_export"
+require_relative "transcripts/transcript_export"
 require_relative "message_access"
 require_relative "model/model_info"
 require_relative "model/azure_openai_config"
@@ -38,18 +38,18 @@ require_relative "model/provider_catalog"
 require_relative "model/catalog"
 require_relative "auth/openai_oauth"
 require_relative "pan/server"
-require_relative "plugin_registry"
+require_relative "plugins/registry"
 require_relative "prompts/commands"
 require_relative "model/retry_message"
 require_relative "rpc/server"
 require_relative "transport/runtime"
-require_relative "session_diff"
-require_relative "session_store"
-require_relative "session_naming"
-require_relative "tab_store"
-require_relative "tab_driver"
-require_relative "session_trash"
-require_relative "session_tree_renderer"
+require_relative "sessions/diff"
+require_relative "sessions/store"
+require_relative "sessions/naming"
+require_relative "tabs/store"
+require_relative "tabs/driver"
+require_relative "sessions/trash"
+require_relative "sessions/tree_renderer"
 require_relative "skills/capture"
 require_relative "starter_pack_installer"
 require_relative "steering"
@@ -57,8 +57,8 @@ require_relative "update_check"
 require_relative "tools/tool_call"
 require_relative "tools/registry"
 require_relative "telemetry/stats"
-require_relative "workspace_factory"
-require_relative "git_worktree_manager"
+require_relative "workspace/factory"
+require_relative "workspace/git_worktree_manager"
 require_relative "cli/commands"
 require_relative "cli/auth_commands"
 require_relative "cli/doctor"
@@ -167,6 +167,7 @@ module Kward
       warn runtime_error_message(e)
       exit 1
     ensure
+      shutdown_plugins if respond_to?(:shutdown_plugins, true)
       ConfigFiles.skip_config = false
     end
 
@@ -424,6 +425,7 @@ module Kward
         tool_registry: ToolRegistry.new(
           workspace: configured_workspace,
           prompt: @prompt,
+          plugin_tools: plugin_registry.tools,
           hook_manager: hook_manager,
           hook_context: hook_context
         ),

data/lib/kward/compactor.rb

@@ -1,5 +1,6 @@
 require "json"
 require_relative "model/chat_invocation"
+require_relative "cancellation"
 require_relative "compaction/file_operation_tracker"
 require_relative "compaction/token_estimator"
 require_relative "config_files"
@@ -671,29 +672,33 @@ module Kward
         @prompt_builder = prompt_builder
       end
 
-      def summarize(preparation, custom_instructions: nil)
+      def summarize(preparation, custom_instructions: nil, cancellation: nil)
         summary = chat(
           @prompt_builder.build(preparation, custom_instructions: custom_instructions),
-          max_tokens: @prompt_builder.normal_summary_max_tokens(preparation.settings, model_max_tokens: model_max_tokens)
+          max_tokens: @prompt_builder.normal_summary_max_tokens(preparation.settings, model_max_tokens: model_max_tokens),
+          cancellation: cancellation
         )
         if preparation.split_turn && !preparation.turn_prefix_messages.empty?
           turn_summary = chat(
             @prompt_builder.build_split(preparation),
-            max_tokens: @prompt_builder.split_turn_max_tokens(preparation.settings, model_max_tokens: model_max_tokens)
+            max_tokens: @prompt_builder.split_turn_max_tokens(preparation.settings, model_max_tokens: model_max_tokens),
+            cancellation: cancellation
           )
           summary = "#{summary}\n\n---\n\n**Turn Context (split turn):**\n\n#{turn_summary}"
         end
         summary.to_s.strip
       rescue Cancelled
         raise
+      rescue Kward::Cancellation::CancelledError
+        raise
       rescue StandardError => e
         raise SummarizationFailed, e.message
       end
 
       private
 
-      def chat(messages, max_tokens: nil)
-        message = ChatInvocation.call(@client, messages, { tools: [], max_tokens: max_tokens })
+      def chat(messages, max_tokens: nil, cancellation: nil)
+        message = ChatInvocation.call(@client, messages, { tools: [], max_tokens: max_tokens, cancellation: cancellation })
         content = message_content(message)
         text = message_content_text(content).strip
         raise SummarizationFailed, "Compaction produced an empty summary; context was not changed." if text.empty?
@@ -752,13 +757,19 @@ module Kward
       false
     end
 
-    def compact(custom_instructions: nil, compaction_summary: true)
+    def compact(custom_instructions: nil, compaction_summary: true, cancellation: nil)
+      cancellation&.raise_if_cancelled!
       old_count = @conversation.messages.length
       preparation = prepare
-      summary = @summarizer.summarize(preparation, custom_instructions: custom_instructions)
+      summary = if cancellation
+        @summarizer.summarize(preparation, custom_instructions: custom_instructions, cancellation: cancellation)
+      else
+        @summarizer.summarize(preparation, custom_instructions: custom_instructions)
+      end
       summary = append_files_section(summary, preparation.file_ops)
       raise Compaction::SummarizationFailed, "Compaction produced an empty summary; context was not changed." if summary.strip.empty?
 
+      cancellation&.raise_if_cancelled!
       @conversation.compact!(
         summary,
         compaction_summary: compaction_summary,

data/lib/kward/config/core.rb

@@ -0,0 +1,389 @@
+# Core configuration paths, persistence, and shared configuration values.
+module Kward
+  module ConfigFiles
+    class ConfigError < StandardError
+      attr_reader :path, :format, :detail
+
+      def initialize(path:, format:, detail:)
+        @path = path
+        @format = format
+        @detail = detail
+        super("Invalid Kward config #{format}: #{path}: #{detail}")
+      end
+    end
+
+    MAX_SKILL_FILE_BYTES = 100_000
+    MAX_PROMPT_FILE_BYTES = 32 * 1024
+    DEFAULT_OVERLAY_SETTINGS = { "alignment" => "center", "width" => "maximum" }.freeze
+    PROJECT_BROWSER_ICON_THEMES = %w[off nerd-font].freeze
+    DEFAULT_PERSONAS = {
+      "characters" => [
+        {
+          "key" => "kward",
+          "label" => "Kward",
+          "instruction" => "Your name is Kward, the grim Andruid - robotic keeper of the Forest of Code, protecting the nature of good engineering principles. Speak like an old druid, be suspicious of everyone, but with good intent."
+        }
+      ],
+      "default" => "kward"
+    }.freeze
+    OVERLAY_ALIGNMENTS = %w[left center right].freeze
+    OVERLAY_WIDTHS = %w[capped maximum].freeze
+
+    Skill = Struct.new(:name, :description, :folder, :path, :license, :compatibility, :metadata, :allowed_tools, keyword_init: true)
+    PromptTemplate = Struct.new(:command, :description, :argument_hint, :body, :path, keyword_init: true) do
+      def expand(arguments)
+        body.gsub("$ARGUMENTS", arguments.to_s)
+      end
+    end
+
+    @skip_config = false
+    @warning_sink = nil
+
+    module Core
+      extend self
+
+      def skip_config=(value)
+        @skip_config = value
+      end
+
+      def warning_sink=(sink)
+        @warning_sink = sink
+      end
+
+      def warning_sink
+        @warning_sink
+      end
+
+      def skip_config?
+        @skip_config == true
+      end
+
+      # Directory that contains Kward's user config and adjacent prompt/skill
+      # data. Defaults to `~/.kward`, or the directory of `KWARD_CONFIG_PATH`.
+      #
+      # @return [String] expanded config directory path
+      def config_dir
+        config_path = ENV["KWARD_CONFIG_PATH"]
+        return File.expand_path(File.dirname(config_path)) if config_path && !config_path.empty?
+
+        File.expand_path("~/.kward")
+      end
+
+      # @return [String] expanded JSON config file path
+      def config_path
+        File.expand_path(ENV["KWARD_CONFIG_PATH"] || File.join(config_dir, "config.json"))
+      end
+
+      # @return [String] directory containing reusable local caches
+      def cache_dir
+        File.join(config_dir, "cache")
+      end
+
+      # @return [String] embedded-shell rc config path
+      def kwshrc_path
+        File.join(config_dir, "kwshrc")
+      end
+
+      # @return [Array<String>] embedded-shell rc config paths in load order
+      def kwshrc_paths
+        [kwshrc_path, File.expand_path("~/.kwshrc")].uniq
+      end
+
+      def workspace_hooks_path(root = Dir.pwd)
+        File.join(File.expand_path(root), ".kward", "hooks.json")
+      end
+
+      def trusted_workspace_hooks_path
+        File.join(config_dir, "trusted_workspace_hooks.json")
+      end
+
+      # Returns a fresh default config suitable for first-run persistence.
+      #
+      # @return [Hash] deep-mutable config defaults
+      def default_config
+        {
+          "personas" => JSON.parse(JSON.generate(DEFAULT_PERSONAS)),
+          "memory" => {
+            "enabled" => false,
+            "auto_summary" => false
+          },
+          "composer" => {
+            "busy_help" => true,
+            "tab_keybindings" => "auto"
+          },
+          "editor" => {
+            "mode" => "modern",
+            "agent" => {},
+            "runners" => {},
+            "auto_indent" => true,
+            "auto_close_pairs" => true,
+            "soft_wrap" => true,
+            "bar_cursor" => true,
+            "line_numbers" => "absolute",
+            "diff_view" => "auto"
+          },
+          "overlay" => DEFAULT_OVERLAY_SETTINGS.dup,
+          "project_browser" => {
+            "icons" => "off"
+          },
+          "web_search" => {
+            "enabled" => true,
+            "provider" => "auto",
+            "allow_model_providers" => false
+          },
+          "updates" => {
+            "check" => true
+          },
+          "sessions" => {
+            "auto_resume" => false
+          },
+          "skills" => {
+            "trust_project" => false
+          },
+          "enforce_workspace_agents_file" => false,
+          "system_prompt" => {
+            "include_principles" => true
+          },
+          "mcpServers" => {},
+          "plugins" => {},
+          "transports" => {},
+          "tools" => {
+            "workspace_guardrails" => true
+          },
+          "permissions" => {
+            "enabled" => false,
+            "mode" => "ask"
+          },
+          "sandbox" => {
+            "mode" => "off",
+            "network" => "deny",
+            "writable_roots" => [],
+            "protect_git_metadata" => true
+          }
+        }
+      end
+
+      # Performs ensure default config for configuration file and path handling.
+      def ensure_default_config!(path = config_path)
+        path = File.expand_path(path)
+        return false if skip_config? && path == config_path
+        return false if File.exist?(path)
+
+        write_config(default_config, path)
+        true
+      end
+
+      def code_search_cache_dir
+        File.join(cache_dir, "code_search")
+      end
+
+      def openrouter_models_cache_path
+        File.join(cache_dir, "openrouter_models.json")
+      end
+
+      def model_catalog_cache_path(provider_id)
+        provider = provider_id.to_s.gsub(/[^a-z0-9_-]/i, "_")
+        raise ArgumentError, "Provider id must be a non-empty string" if provider.empty?
+
+        File.join(cache_dir, "models", "#{provider}.json")
+      end
+
+      def update_check_cache_path
+        File.join(cache_dir, "update_check.json")
+      end
+
+      def project_browser_state_path
+        File.join(cache_dir, "project_browser_state.json")
+      end
+
+      def prompt_history_path(cwd, config_dir: self.config_dir, kind: "prompt")
+        key = Digest::SHA256.hexdigest(canonical_workspace_root(cwd))[0, 24]
+        return File.join(config_dir, "history", "#{key}.jsonl") if kind.to_s == "prompt"
+
+        File.join(config_dir, "history", kind.to_s, "#{key}.jsonl")
+      end
+
+      # @return [String] directory containing structured memory files
+      def memory_dir
+        File.join(config_dir, "memory")
+      end
+
+      def memory_core_path
+        File.join(memory_dir, "core.json")
+      end
+
+      def memory_soft_path
+        File.join(memory_dir, "soft.jsonl")
+      end
+
+      def memory_events_path
+        File.join(memory_dir, "events.jsonl")
+      end
+
+      # Reads the JSON config file.
+      #
+      # Missing files are treated as an empty config. Invalid JSON raises a
+      # user-facing error that includes the file path. This method does not merge
+      # defaults; callers should apply feature-specific defaults at the point where
+      # behavior is decided.
+      #
+      # @param path [String] config file path
+      # @return [Hash] parsed config object
+      def read_config(path = config_path)
+        path = File.expand_path(path)
+        return {} if skip_config? && path == config_path
+        return {} unless File.exist?(path)
+
+        config = JSON.parse(File.read(path))
+        return config if config.is_a?(Hash)
+
+        raise ConfigError.new(path: path, format: "JSON", detail: "top-level value must be an object")
+      rescue JSON::ParserError => e
+        raise ConfigError.new(path: path, format: "JSON", detail: e.message)
+      end
+
+      # Writes config JSON using private file permissions.
+      #
+      # @param config [Hash] config object to persist
+      # @param path [String] config file path
+      def write_config(config, path = config_path)
+        path = File.expand_path(path)
+        raise "Cannot write Kward config while --skip-config is active: #{path}" if skip_config? && path == config_path
+
+        PrivateFile.write_json(path, config)
+      end
+
+      def lifecycle_hooks_config(workspace_root = Dir.pwd)
+        config = read_config
+        workspace_config = read_trusted_workspace_hooks_config(workspace_root)
+        return config if workspace_config.empty?
+
+        merge_hooks_config(config, workspace_config)
+      end
+
+      def read_trusted_workspace_hooks_config(workspace_root = Dir.pwd)
+        path = workspace_hooks_path(workspace_root)
+        return {} unless workspace_hooks_trusted?(workspace_root)
+
+        read_config(path)
+      end
+
+      def workspace_hooks_trusted?(workspace_root = Dir.pwd)
+        path = workspace_hooks_path(workspace_root)
+        return false unless File.file?(path)
+
+        trusted = read_trusted_workspace_hooks
+        trusted[File.expand_path(path)] == workspace_hooks_digest(workspace_root)
+      end
+
+      def trust_workspace_hooks!(workspace_root = Dir.pwd)
+        path = workspace_hooks_path(workspace_root)
+        raise "No workspace hook config found: #{path}" unless File.file?(path)
+
+        trusted = read_trusted_workspace_hooks
+        trusted[File.expand_path(path)] = workspace_hooks_digest(workspace_root)
+        PrivateFile.write_json(trusted_workspace_hooks_path, trusted)
+      end
+
+      def untrust_workspace_hooks!(workspace_root = Dir.pwd)
+        path = File.expand_path(workspace_hooks_path(workspace_root))
+        trusted = read_trusted_workspace_hooks
+        trusted.delete(path)
+        PrivateFile.write_json(trusted_workspace_hooks_path, trusted)
+      end
+
+      def workspace_hooks_digest(workspace_root = Dir.pwd)
+        Digest::SHA256.file(workspace_hooks_path(workspace_root)).hexdigest
+      end
+
+      def read_trusted_workspace_hooks
+        config = read_config(trusted_workspace_hooks_path)
+        config.is_a?(Hash) ? config : {}
+      rescue ConfigError
+        {}
+      end
+
+      def merge_hooks_config(config, workspace_config)
+        merged = JSON.parse(JSON.generate(config || {}))
+        merged["hooks"] = merge_hook_maps(merged["hooks"], workspace_config["hooks"] || workspace_config[:hooks])
+        merged
+      end
+
+      def merge_hook_maps(left, right)
+        left = left.is_a?(Hash) ? left : {}
+        right = right.is_a?(Hash) ? right : {}
+        merged = JSON.parse(JSON.generate(left))
+        right.each do |event, entries|
+          merged[event.to_s] = Array(merged[event.to_s]) + Array(entries)
+        end
+        merged
+      end
+
+      def read_kwsh_config
+        config = {
+          shell: Kwsh::DEFAULT_SHELL,
+          timeout_seconds: Kwsh::DEFAULT_TIMEOUT_SECONDS,
+          max_output_bytes: Kwsh::DEFAULT_MAX_OUTPUT_BYTES,
+          history_limit: Kwsh::DEFAULT_HISTORY_LIMIT,
+          env: {},
+          aliases: {}
+        }
+        rc_config = read_kwshrc_config
+        config[:env].merge!(rc_config[:env])
+        config[:aliases].merge!(rc_config[:aliases])
+        config
+      end
+
+      def read_kwshrc_config(paths = kwshrc_paths, env: ENV.to_h)
+        Kwshrc.read(paths, env: env)
+      rescue Kwshrc::ParseError => e
+        raise "Invalid kwshrc config: #{e.message}"
+      end
+
+      # Merges top-level config values and writes the updated config privately.
+      def update_config(values, path = config_path)
+        raise "Config values must be an object" unless values.is_a?(Hash)
+
+        config = read_config(path)
+        values.each { |key, value| config[key.to_s] = value }
+        write_config(config, path)
+        config
+      end
+
+      # Merges values into a one-level nested config section and writes privately.
+      def update_nested_config(section, values, path = config_path)
+        raise "Config values must be an object" unless values.is_a?(Hash)
+
+        config = read_config(path)
+        current = config[section.to_s].is_a?(Hash) ? config[section.to_s].dup : {}
+        config[section.to_s] = current.merge(values.transform_keys(&:to_s))
+        write_config(config, path)
+        config
+      end
+
+      # Removes a top-level config key when it exists.
+      def delete_config_key(key, path = config_path)
+        config = read_config(path)
+        existed = config.key?(key.to_s)
+        config.delete(key.to_s)
+        write_config(config, path) if existed
+        existed
+      end
+
+      # Returns the first present non-empty string value among several config keys.
+      def config_value(config, *keys)
+        keys.each do |key|
+          text = presence(config[key])
+          return text if text
+        end
+        nil
+      end
+
+      # Returns validated overlay settings with defaults for missing or invalid
+      # values.
+      #
+      # @param config [Hash] parsed config object
+      # @return [Hash] overlay settings with `alignment` and `width`
+    end
+  end
+end

data/lib/kward/config/extensions.rb

@@ -0,0 +1,96 @@
+# Configuration extensions behavior.
+module Kward
+  module ConfigFiles
+    module Extensions
+      extend self
+
+      # Lists configured skills discovered under the config directory.
+      #
+      # @return [Array<Skill>] skill metadata available to the model
+      def skills(workspace_root: Dir.pwd, warning_sink: nil, project_skill_paths: nil)
+        skills_registry(workspace_root: workspace_root, warning_sink: warning_sink, project_skill_paths: project_skill_paths).skills
+      end
+
+      def project_skill_candidates(workspace_root: Dir.pwd, warning_sink: nil)
+        skills_registry(workspace_root: workspace_root, warning_sink: warning_sink).project_skill_candidates
+      end
+
+      # @return [String] trusted user plugin directory
+      def plugin_dir
+        File.expand_path("~/.kward/plugins")
+      end
+
+      # Finds trusted plugin files and package entrypoints.
+      #
+      # Plugins are intentionally loaded only from `~/.kward/plugins`, not from a
+      # workspace or custom `KWARD_CONFIG_PATH` directory.
+      #
+      # @return [Array<String>] sorted plugin file paths
+      def plugin_paths(warning_sink: nil)
+        plugins_root = plugin_dir
+        return [] unless Dir.exist?(plugins_root)
+
+        paths = Dir.glob(File.join(plugins_root, "*.rb"))
+        paths.concat(Dir.glob(File.join(plugins_root, "*", "plugin.rb")))
+        paths.sort
+      rescue StandardError => e
+        emit_warning("Warning: skipping Kward plugins in #{plugins_root}: #{e.message}", warning_sink: warning_sink)
+        []
+      end
+
+      # Lists prompt templates exposed as slash commands.
+      #
+      # @param reserved_commands [Array<String>] command names unavailable to templates
+      # @return [Array<PromptTemplate>] prompt template metadata and bodies
+      def prompt_templates(reserved_commands: [])
+        prompt_template_registry.prompt_templates(reserved_commands: reserved_commands)
+      end
+
+      # Reads a skill file by skill name and optional relative path.
+      #
+      # @param name [String] configured skill name
+      # @param relative_path [String, nil] path inside the skill directory
+      # @return [String] file contents or an error string
+      def read_skill_file(name, relative_path = nil, workspace_root: Dir.pwd)
+        skills_registry(workspace_root: workspace_root).read_skill_file(name, relative_path)
+      end
+
+      def skills_registry(workspace_root: Dir.pwd, warning_sink: nil, project_skill_paths: nil)
+        Skills::Registry.new(
+          config_dir: config_dir,
+          workspace_root: workspace_root,
+          project_skills_trusted: project_skills_trusted?,
+          skill_class: Skill,
+          max_file_bytes: MAX_SKILL_FILE_BYTES,
+          markdown_parser: ->(path) { Frontmatter.markdown_parts(path, lenient: true) },
+          inside_directory: method(:inside_directory?),
+          warning_sink: warning_sink || @warning_sink,
+          project_skill_paths: project_skill_paths
+        )
+      end
+
+      def prompt_template_registry
+        ::Kward::Prompts::Templates.new(
+          config_dir: config_dir,
+          template_class: PromptTemplate,
+          markdown_parser: ->(path) { Frontmatter.markdown_parts(path) },
+          warning_sink: @warning_sink
+        )
+      end
+
+      def emit_warning(message, warning_sink: nil)
+        sink = warning_sink || @warning_sink
+        sink ? sink.call(message) : warn(message)
+      end
+
+      def inside_directory?(path, base)
+        PathGuard.inside?(path, base)
+      end
+
+      def presence(value)
+        text = value.to_s
+        text.empty? ? nil : text
+      end
+    end
+  end
+end