ruby_coded 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45aa4262fb573ca03510db92e2d3bd9795136b935fe7ffe8ba02821a570b107b
-  data.tar.gz: ed299052fcaa75af5a03951d18fbae6021fccd2463d28f73ea7f57cacdca28d7
+  metadata.gz: c0c96bdf1a87ce1f830d0a36b9fb78600f8ee1df2bd81603630f7bf87b0cac08
+  data.tar.gz: 3a08a46116afd6c8b1f82ec0c085c4758b65f349631854a47027883578ff3c3c
 SHA512:
-  metadata.gz: f06c04df1359024f169e00185535ab2f8be8f24a6eee94f3f231c130dc31d385a48163072a843330ac83a79060e553d94a59dc4224e5a93679066894d5642e81
-  data.tar.gz: 66e264de72737cbe9b3158267faf941de67156c2e05b855e7cf679ca640ceb3ecaa16c15f694aa5c2e549578004b8851aeb2ed7513a358bcb8396603eb217f34
+  metadata.gz: 9a5f8e7e7587b8e87dd830b9a2a20976611ec4d04a2b61f6c805a2877727e4b9299865b947a89929b3e83a71149ac0f5a868de69fbdd02262d00de1b86595c6a
+  data.tar.gz: 3739c33f411b92918553b02816218f7ea54a11664802b10a7f15fa37138b9f4631315373e2624fbfd2a4246c44f27455454f0111385ccc855f88b08e3e75e597

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-04
+
+### Added
+
+- **Highlight the users' messages in the chat section**: Now the chat sections highlights and spots the users' mesagges in blocks
+for a easely reading of the chat
+- **Rich text support in the TUI chat renderer**: Added rich text rendering support for chat output in the terminal UI.
+- **Project-local skills system**: RubyCoded can now load Markdown skill files from `.rubycoded/skills/` using YAML frontmatter metadata (`name`, `description`, `modes`, optional `tags`, `trigger`, and `priority`) and expose them as reusable project instructions.
+- **Skill management commands**: Added `/skills reload` and `/skills list` to reload and inspect project-local skills without restarting the application.
+- **Skill validation and cataloging**: Added a dedicated `RubyCoded::Skills` subsystem with a markdown loader, normalized skill definitions, duplicate detection, invalid file reporting, and mode-aware in-memory cataloging.
+
+### Changed
+
+- **Refactor chat panel rendering system into multiple modules**
+- **Prompt construction now supports project skills**: Chat, plan, and agent mode instructions now append relevant project-local skills so project-specific guidance is consistently available across runtime modes, including Codex-backed sessions.
+- **Ruby-conventional predicate names on bridges**: `LLMBridge` and `CodexBridge` now expose `agentic_mode?` and `plan_mode?` (previously `agentic_mode` / `plan_mode`). Plugins that read these predicates need to update the call site.
+- **Internal chat bridge refactor**: Extracted `RuntimeMode` as the single source of truth for chat/agent/plan modes, `BridgeFactory` for backend selection, `Tools::ExecutionPolicy` for centralized risk/approval/limits, `PromptBuilder` for mode-aware system instructions, and `BridgeCommon` (`ModeTransitions`, `ToolFlow`, `AutoSwitch`) to share behavior between `LLMBridge` and `CodexBridge`.
+- **Tool execution pipeline**: Added `Tools::ExecutionPipeline` and `BaseTool#run_pipeline` to standardize path validation, project-root guarding and filesystem error normalization for side-effecting tools; adopted in `WriteFileTool`, `EditFileTool` and `DeletePathTool`.
+- **Extension model documented**: The README now describes the boundary between commands, skills and plugins.
+
 ## [0.3.1] - 2026-06-28
 
 ### Added

data/README.md

@@ -28,7 +28,7 @@ An AI-powered terminal coding assistant built in Ruby. Chat with LLMs, let an ag
 - **Tool confirmation** — Write and dangerous operations require explicit approval; safe operations (read, list) run automatically
 - **Token & cost tracking** — Live status bar showing token usage, estimated session cost, and auth mode indicator
 - **Plugin system** — Extend the chat with custom state, input handlers, renderer overlays, and commands
-- **Slash commands** — `/agent`, `/plan`, `/model`, `/login`, `/history`, `/tokens`, `/commands reload`, `/commands list`, `/help`, and more
+- **Slash commands** — `/agent`, `/plan`, `/model`, `/login`, `/history`, `/tokens`, `/commands reload`, `/commands list`, `/skills reload`, `/skills list`, `/help`, and more
 
 ## Requirements
 
@@ -64,6 +64,8 @@ On first launch you'll be asked to authenticate with a provider. After that, you
 | `/login` | Authenticate with a provider (OpenAI, Anthropic) |
 | `/commands reload` | Reload custom markdown commands from the current project |
 | `/commands list` | List currently loaded custom markdown commands |
+| `/skills reload` | Reload project-local skills from the current project |
+| `/skills list` | List currently loaded project-local skills |
 | `/tokens` | Show detailed token usage breakdown |
 | `/history` | Show conversation history |
 | `/clear` | Clear the conversation |
@@ -93,6 +95,22 @@ Safe tools run without asking. Confirm and dangerous tools show the operation de
 
 Plan mode restricts the model to read-only tools and a planning-oriented system prompt. The model will analyze your project and propose a structured plan. If the model needs clarification, it presents interactive options you can select or answer with custom text.
 
+### Extension model
+
+RubyCoded exposes three distinct extension mechanisms. When adding new behavior, pick the one that matches the intent:
+
+| Mechanism | What it is | Trigger | Where it lives |
+|---|---|---|---|
+| **Commands** | Explicit user-invoked actions (built-in or Markdown-defined slash commands) | User types `/foo` | `lib/ruby_coded/chat/command_handler/` (built-in) or `.ruby_coded/commands/*.md` (project-local) |
+| **Skills** | Automatic instruction overlays merged into the system prompt when they match the active mode/context | Mode + optional tags/trigger match the current request | `.rubycoded/skills/*.md` (project-local) |
+| **Plugins** | Code-level extensions that hook into state, input, renderer, or add new commands at runtime | Loaded on startup | Ruby classes registered via `RubyCoded::Plugins` |
+
+Rule of thumb:
+
+- Use a **command** if the user should invoke it explicitly.
+- Use a **skill** if you want extra instructions injected automatically for a mode.
+- Use a **plugin** if you need Ruby code to observe or mutate runtime behavior.
+
 ### Custom commands
 
 You can define your own project-specific slash commands using Markdown files inside:
@@ -173,6 +191,100 @@ List currently loaded custom commands:
 - Plugin commands also take precedence over custom Markdown commands.
 - Invalid Markdown command files are ignored during reload.
 
+### Project skills
+
+RubyCoded also supports project-local skills: reusable Markdown instructions that are automatically injected into chat, plan, and agent behavior when they match the active mode.
+
+Skills are loaded from:
+
+```bash
+.rubycoded/skills/
+```
+
+This path is intentionally different from custom commands, which use:
+
+```bash
+.ruby_coded/commands/
+```
+
+Each `.md` file defines one skill.
+
+#### Skill file format
+
+Use YAML frontmatter followed by the skill body:
+
+```md
+---
+name: Rails Migration Safety
+description: Improve safety when changing schema or migrations
+modes:
+  - agent
+  - plan
+tags:
+  - rails
+  - migration
+trigger: schema
+priority: 10
+---
+
+Before proposing or applying migration changes:
+- inspect existing schema and recent migrations
+- prefer additive, reversible changes
+- call out data backfill or locking risks explicitly
+```
+
+#### Required fields
+
+- `name` — unique skill name within the project
+- `description` — short explanation shown in `/skills list`
+- `modes` — one or more supported modes: `chat`, `plan`, `agent`
+
+#### Optional fields
+
+- `tags` — keywords used for simple relevance matching
+- `trigger` — plain-text trigger checked against the current request
+- `priority` — higher-priority skills are listed first and applied first
+
+#### How skills are activated
+
+Current behavior is intentionally simple:
+
+- all skills compatible with the active mode are loaded
+- if a request matches skill `tags` or `trigger`, matching skills are preferred
+- if nothing matches, all mode-compatible skills remain available
+
+This means skills are useful immediately without requiring manual activation UI.
+
+#### Managing skills
+
+Reload skills after adding, editing, or deleting skill files:
+
+```bash
+/skills reload
+```
+
+List the currently loaded skills:
+
+```bash
+/skills list
+```
+
+The reload command reports:
+
+- how many skills were added
+- how many were removed
+- how many are currently available
+- how many invalid files were ignored
+- how many duplicate skill names were ignored
+
+#### Skill behavior notes
+
+- Skills are project-local and loaded relative to the current project root.
+- Skills are injected into system instructions for `chat`, `plan`, and `agent` modes.
+- If a skill conflicts with higher-priority system instructions or the user’s explicit request, the higher-priority instruction should win.
+- Invalid or malformed skill files are ignored during reload.
+- If duplicate skill names exist, the first loaded definition wins and later duplicates are ignored.
+
 ## Keyboard shortcuts
 
 | Key | Action |

data/lib/ruby_coded/chat/app.rb

@@ -10,9 +10,7 @@ require_relative "state"
 require_relative "input_handler"
 require_relative "renderer"
 require_relative "command_handler"
-require_relative "llm_bridge"
-require_relative "codex_bridge"
-require_relative "codex_models"
+require_relative "bridge_factory"
 require_relative "../commands/catalog"
 require_relative "../auth/credentials_store"
 require_relative "../auth/jwt_decoder"
@@ -42,16 +40,31 @@ module RubyCoded
       end
 
       def build_components!
+        build_catalogs!
+        @state = State.new(model: @model, command_catalog: @command_catalog)
+        @credentials_store = Auth::CredentialsStore.new(user_config: @user_config)
+        @bridge_factory = build_bridge_factory
+        @llm_bridge = @bridge_factory.build
+        @input_handler = InputHandler.new(@state)
+        @command_handler = build_command_handler
+      end
+
+      def build_catalogs!
         @command_catalog = RubyCoded::Commands::Catalog.new(
           project_root: Dir.pwd,
           plugin_registry: RubyCoded.plugin_registry
         )
+        @skill_catalog = RubyCoded::Skills::Catalog.new(project_root: Dir.pwd)
+      end
 
-        @state = State.new(model: @model, command_catalog: @command_catalog)
-        @credentials_store = Auth::CredentialsStore.new(user_config: @user_config)
-        @llm_bridge = create_bridge
-        @input_handler = InputHandler.new(@state)
-        @command_handler = build_command_handler
+      def build_bridge_factory
+        BridgeFactory.new(
+          state: @state,
+          credentials_store: @credentials_store,
+          auth_manager: @auth_manager,
+          skill_catalog: @skill_catalog,
+          user_config: @user_config
+        )
       end
 
       IDLE_POLL_TIMEOUT = 0.016
@@ -109,7 +122,8 @@ module RubyCoded
           user_config: @user_config,
           credentials_store: @credentials_store,
           auth_manager: @auth_manager,
-          command_catalog: @command_catalog
+          command_catalog: @command_catalog,
+          skill_catalog: @skill_catalog
         )
       end
 
@@ -125,7 +139,7 @@ module RubyCoded
       end
 
       def enable_default_agent_mode!
-        return if @llm_bridge.agentic_mode
+        return if @llm_bridge.agentic_mode?
 
         @llm_bridge.toggle_agentic_mode!(true)
       end
@@ -149,34 +163,21 @@ module RubyCoded
         @state.add_message(:system, "Model switched to #{model_name}.")
       end
 
-      def create_bridge
-        openai_creds = @credentials_store.retrieve(:openai)
-        if openai_creds && openai_creds["auth_method"] == "oauth"
-          @state.codex_mode = true
-          ensure_valid_codex_model!
-          CodexBridge.new(@state, credentials_store: @credentials_store, auth_manager: @auth_manager)
-        else
-          @state.codex_mode = false
-          LLMBridge.new(@state)
-        end
-      end
-
-      def ensure_valid_codex_model!
-        return if CodexModels.codex_model?(@state.model)
-
-        @state.model = CodexBridge::DEFAULT_MODEL
-        @user_config&.set_config("model", CodexBridge::DEFAULT_MODEL)
-      end
-
       def recreate_bridge!
         @command_catalog.reload!
-        agentic = @llm_bridge.agentic_mode
-        plan = @llm_bridge.plan_mode
-        @llm_bridge = create_bridge
-        @llm_bridge.toggle_agentic_mode!(agentic) if agentic
-        @llm_bridge.toggle_plan_mode!(plan) if plan
+        @skill_catalog.reload!
+        previous_mode = @llm_bridge.mode
+        @llm_bridge = @bridge_factory.build
+        restore_bridge_mode!(previous_mode)
         @command_handler = build_command_handler
       end
+
+      def restore_bridge_mode!(mode)
+        case mode.name
+        when :agent then @llm_bridge.toggle_agentic_mode!(true)
+        when :plan then @llm_bridge.toggle_plan_mode!(true)
+        end
+      end
     end
   end
 end

data/lib/ruby_coded/chat/bridge_common/auto_switch.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyCoded
+  module Chat
+    module BridgeCommon
+      # Recognizes "please implement the plan" style messages and
+      # switches the runtime from plan mode to agent mode so that
+      # write tools become available for execution.
+      module AutoSwitch
+        IMPLEMENTATION_PATTERNS = [
+          /\bimplement/i,
+          /\bgo ahead/i,
+          /\bproceed/i,
+          /\bexecut/i,
+          /\bejecutar?/i,
+          /\bcomenz/i,
+          /\bcomienz/i,
+          /\bhazlo/i,
+          /\bconstru[iy]/i,
+          /\badelante/i,
+          /\bdale\b/i,
+          /\bdo it/i,
+          /\bbuild it/i
+        ].freeze
+
+        private
+
+        def should_auto_switch_to_agent?(input)
+          @mode.plan? && @state.respond_to?(:current_plan) && @state.current_plan &&
+            implementation_request?(input)
+        end
+
+        def implementation_request?(input)
+          IMPLEMENTATION_PATTERNS.any? { |pattern| input.match?(pattern) }
+        end
+
+        def auto_switch_to_agent!
+          toggle_agentic_mode!(true)
+          @state.add_message(:system,
+                             "Plan mode disabled — switching to agent mode to implement the plan.")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_coded/chat/bridge_common/mode_transitions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../runtime_mode"
+
+module RubyCoded
+  module Chat
+    module BridgeCommon
+      # Encapsulates transitions between chat/agent/plan modes and
+      # keeps the associated State flags (agentic_mode, plan tracking,
+      # auto-approve) consistent.
+      module ModeTransitions
+        def agentic_mode?
+          @mode.agent?
+        end
+
+        def plan_mode?
+          @mode.plan?
+        end
+
+        def toggle_agentic_mode!(enabled)
+          if enabled
+            transition_to_agent!
+          else
+            transition_out_of_agent!
+          end
+          after_mode_change!
+        end
+
+        def toggle_plan_mode!(enabled)
+          if enabled
+            transition_to_plan!
+          elsif @mode.plan?
+            @mode = RuntimeMode.chat
+          end
+          after_mode_change!
+        end
+
+        private
+
+        # Override in the concrete bridge when reconfiguration is
+        # needed after a mode change (e.g. re-registering tools).
+        def after_mode_change!
+          nil
+        end
+
+        def transition_to_agent!
+          was_plan = @mode.plan?
+          @mode = RuntimeMode.agent
+          @state.agentic_mode = true
+          @state.deactivate_plan_mode! if was_plan
+        end
+
+        def transition_out_of_agent!
+          @mode = RuntimeMode.chat if @mode.agent?
+          @state.agentic_mode = false
+          @state.disable_auto_approve!
+        end
+
+        def transition_to_plan!
+          was_agent = @mode.agent?
+          @mode = RuntimeMode.plan
+          return unless was_agent
+
+          @state.agentic_mode = false
+          @state.disable_auto_approve!
+        end
+      end
+    end
+  end
+end

data/lib/ruby_coded/chat/bridge_common/tool_flow.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../../tools/agent_cancelled_error"
+require_relative "../../tools/tool_rejected_error"
+
+module RubyCoded
+  module Chat
+    module BridgeCommon
+      # Shared tool-confirmation flow and cancellation signaling.
+      # Uses the State's condition variable to block the streaming
+      # thread until the TUI supplies a decision (approve/reject/cancel).
+      module ToolFlow
+        def cancel!
+          @cancel_requested = true
+          @state.mutex.synchronize { @state.tool_cv.signal }
+        end
+
+        def approve_tool!
+          @state.tool_confirmation_response = :approved
+        end
+
+        def approve_all_tools!
+          @state.enable_auto_approve!
+          @state.tool_confirmation_response = :approved
+        end
+
+        def reject_tool!
+          @state.tool_confirmation_response = :rejected
+        end
+
+        private
+
+        def poll_tool_decision
+          @state.mutex.synchronize do
+            loop do
+              return :cancelled if @cancel_requested
+
+              resp = @state.instance_variable_get(:@tool_confirmation_response)
+              return resp if %i[approved rejected].include?(resp)
+
+              @state.tool_cv.wait(@state.mutex, 0.1)
+            end
+          end
+        end
+
+        def apply_tool_decision(decision, display_name)
+          case decision
+          when :cancelled
+            @state.clear_tool_confirmation!
+            raise Tools::AgentCancelledError, "Operation cancelled by user"
+          when :approved
+            @state.resolve_tool_confirmation!(:approved)
+          when :rejected
+            @state.resolve_tool_confirmation!(:rejected)
+            raise Tools::ToolRejectedError, "User rejected #{display_name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_coded/chat/bridge_common.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "runtime_mode"
+require_relative "bridge_common/mode_transitions"
+require_relative "bridge_common/tool_flow"
+require_relative "bridge_common/auto_switch"
+
+module RubyCoded
+  module Chat
+    # Shared behavior between LLMBridge and CodexBridge.
+    #
+    # Composes three concerns:
+    #
+    # - {ModeTransitions} — chat/agent/plan transitions + State sync,
+    # - {ToolFlow}        — approve/reject/cancel + poll/apply decision,
+    # - {AutoSwitch}      — "implement the plan" → agent mode heuristic.
+    #
+    # Consumers must:
+    # - initialize `@mode = RuntimeMode.chat` (or another mode),
+    # - initialize `@cancel_requested = false`,
+    # - override `after_mode_change!` if the backend needs to
+    #   reconfigure state (e.g. the RubyLLM chat instance).
+    module BridgeCommon
+      def self.included(base)
+        base.include(ModeTransitions)
+        base.include(ToolFlow)
+        base.include(AutoSwitch)
+      end
+    end
+  end
+end

data/lib/ruby_coded/chat/bridge_factory.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "llm_bridge"
+require_relative "codex_bridge"
+require_relative "codex_models"
+
+module RubyCoded
+  module Chat
+    # Decides which bridge (LLMBridge vs CodexBridge) to instantiate
+    # based on the stored OpenAI credentials.
+    #
+    # Extracted from Chat::App so that backend selection remains a
+    # single, testable responsibility and App stays focused on
+    # orchestration.
+    class BridgeFactory
+      def initialize(state:, credentials_store:, auth_manager:, skill_catalog:, user_config: nil)
+        @state = state
+        @credentials_store = credentials_store
+        @auth_manager = auth_manager
+        @skill_catalog = skill_catalog
+        @user_config = user_config
+      end
+
+      def build
+        return build_llm_bridge unless codex_backend?
+
+        build_codex_bridge
+      end
+
+      private
+
+      def codex_backend?
+        credentials = @credentials_store.retrieve(:openai)
+        credentials && credentials["auth_method"] == "oauth"
+      end
+
+      def build_codex_bridge
+        @state.codex_mode = true
+        ensure_valid_codex_model!
+        CodexBridge.new(
+          @state,
+          credentials_store: @credentials_store,
+          auth_manager: @auth_manager,
+          skill_catalog: @skill_catalog
+        )
+      end
+
+      def build_llm_bridge
+        @state.codex_mode = false
+        LLMBridge.new(@state, skill_catalog: @skill_catalog)
+      end
+
+      def ensure_valid_codex_model!
+        return if CodexModels.codex_model?(@state.model)
+
+        @state.model = CodexBridge::DEFAULT_MODEL
+        @user_config&.set_config("model", CodexBridge::DEFAULT_MODEL)
+      end
+    end
+  end
+end

data/lib/ruby_coded/chat/codex_bridge/error_handling.rb

@@ -4,13 +4,7 @@ module RubyCoded
   module Chat
     class CodexBridge
       # Retry logic and error message formatting for the Codex API client.
-      # rubocop:disable Metrics/ModuleLength
       module ErrorHandling
-        AGENT_SWITCH_PATTERN = /
-          \b(implement|go[ ]ahead|proceed|execut|ejecutar?|comenz|
-          comienz|hazlo|constru[iy]|adelante|dale|do[ ]it|build[ ]it)\b
-        /ix
-
         UNSUPPORTED_MODEL_PATTERN = /not supported when using Codex with a ChatGPT account/i
 
         private
@@ -23,8 +17,7 @@ module RubyCoded
         end
 
         def reset_call_counts
-          @tool_call_count = 0
-          @write_tool_call_count = 0
+          @policy.reset_counters!
         end
 
         def prepare_send(input)
@@ -35,17 +28,6 @@ module RubyCoded
           @state.add_message(:assistant, "")
         end
 
-        def should_auto_switch_to_agent?(input)
-          @plan_mode && @state.respond_to?(:current_plan) && @state.current_plan &&
-            input.match?(AGENT_SWITCH_PATTERN)
-        end
-
-        def auto_switch_to_agent!
-          toggle_agentic_mode!(true)
-          @state.add_message(:system,
-                             "Plan mode disabled — switching to agent mode to implement the plan.")
-        end
-
         def attempt_with_retries(input, retries = 0, fallback_attempted: false)
           perform_codex_request(input)
         rescue Tools::AgentCancelledError, Tools::AgentIterationLimitError, Tools::ToolRejectedError => e
@@ -145,7 +127,6 @@ module RubyCoded
           MSG
         end
       end
-      # rubocop:enable Metrics/ModuleLength
     end
   end
 end

data/lib/ruby_coded/chat/codex_bridge/request_builder.rb

@@ -12,9 +12,6 @@ module RubyCoded
           "OpenAI-Beta" => "responses=experimental"
         }.freeze
 
-        DEFAULT_INSTRUCTIONS = "You are a helpful coding assistant. " \
-                               "Answer concisely and provide code examples when relevant."
-
         private
 
         def codex_headers
@@ -29,7 +26,7 @@ module RubyCoded
 
         def build_request_body
           body = base_request_body
-          body[:tools] = build_tools_spec if @agentic_mode || @plan_mode
+          body[:tools] = build_tools_spec if @mode.allows_tools?
           body
         end
 
@@ -68,20 +65,11 @@ module RubyCoded
         end
 
         def build_instructions
-          if @agentic_mode
-            Tools::SystemPrompt.build(
-              project_root: @project_root, max_write_rounds: MAX_WRITE_TOOL_ROUNDS,
-              max_total_rounds: MAX_TOTAL_TOOL_ROUNDS
-            )
-          elsif @plan_mode
-            Tools::PlanSystemPrompt.build(project_root: @project_root)
-          else
-            DEFAULT_INSTRUCTIONS
-          end
+          @prompt_builder.build(@mode)
         end
 
         def build_tools_spec
-          tool_instances = if @agentic_mode
+          tool_instances = if @mode.allows_mutation?
                              @tool_registry.build_tools
                            else
                              @tool_registry.build_readonly_tools