refactor(api): extract functionality into API module (#41)

- ✨ Create dedicated API abstraction layer for better organization
- 🏗️ Move implementation details from init.lua to api.lua
- 🧪 Add comprehensive tests for all API methods
- 🔄 Update command implementations to use the new API

Author: GeorgesAlkhouri

README.md

@@ -5,7 +5,7 @@
 <img width="1280" alt="screenshot_1" src="https://github.com/user-attachments/assets/5d779f73-5441-4d24-8cce-e6dfdc5bf787" />
 <img width="1280" alt="screenshot_2" src="https://github.com/user-attachments/assets/3c122846-ca27-42d3-8cbf-f6e5f9b10f69" />
 
-> 🚧 This plugin is in initial development. Expect breaking changes and rough edges.  
+> 🚧 This plugin is in initial development. Expect breaking changes and rough edges.
 > _October 17, 2024_
 
 ## 🌟 Features
@@ -17,6 +17,8 @@
 - [x] 📤 Send buffers or selections to Aider
 - [x] 💬 Optional user prompt for buffer and selection sends
 - [x] 🔍 Aider command selection UI with fuzzy search and input prompt
+- [x] 🔌 Fully documented [Lua API](lua/nvim_aider/api.lua) for
+      programmatic interaction and custom integrations
 - [x] 🌲➕ [Neo-tree](https://github.com/nvim-neo-tree/neo-tree.nvim)
       integration also with multi-file/directory selection with visual mode support
 - [x] 🌳 Integration with [nvim-tree.lua](https://github.com/nvim-tree/nvim-tree.lua)
@@ -41,9 +43,9 @@
 
 ## 🔗 Requirements
 
-🐍 Python: Install `aider-chat`  
-📋 System: **Neovim** >= 0.9.4, ~~Working clipboard~~ thanks to @milanglacier  
-🌙 Lua: `folke/snacks.nvim`,  
+🐍 Python: Install `aider-chat`
+📋 System: **Neovim** >= 0.9.4, ~~Working clipboard~~ thanks to @milanglacier
+🌙 Lua: `folke/snacks.nvim`,
 _optionals_ `catppuccin/nvim`, `nvim-neo-tree/neo-tree.nvim`, `nvim-tree.lua`
 
 ## 📦 Installation
@@ -135,6 +137,134 @@ require("nvim_aider").setup({
 })
 ```
 
+## 📚 API Reference
+
+The plugin provides a structured API for programmatic integration. Access via `require("nvim_aider").api`
+
+### Core Functions
+
+```lua
+local api = require("nvim_aider").api
+```
+
+#### `health_check()`
+
+Verify plugin health status
+
+```lua
+api.health_check()
+```
+
+#### `toggle_terminal(opts?)`
+
+Toggle Aider terminal window
+
+```lua
+api.toggle_terminal()
+```
+
+---
+
+### Terminal Operations
+
+#### `send_to_terminal(text, opts?)`
+
+Send raw text directly to Aider
+
+```lua
+api.send_to_terminal("Fix the login validation")
+```
+
+#### `send_command(command, input?, opts?)`
+
+Execute specific Aider command
+
+```lua
+api.send_command("/commit", "Add error handling")
+```
+
+---
+
+### File Management
+
+#### `add_file(filepath)`
+
+Add specific file to session
+
+```lua
+api.add_file("/src/utils.lua")
+```
+
+#### `drop_file(filepath)`
+
+Remove file from session
+
+```lua
+api.drop_file("/outdated/legacy.py")
+```
+
+#### `add_current_file()`
+
+Add current buffer's file (uses `add_file` internally)
+
+```lua
+vim.api.nvim_create_autocmd("BufWritePost", {
+  callback = function()
+    api.add_current_file()
+  end
+})
+```
+
+#### `drop_current_file()`
+
+Remove current buffer's file
+
+```lua
+api.drop_current_file()
+```
+
+#### `add_read_only_file()`
+
+Add current buffer as read-only reference
+
+```lua
+api.add_read_only_file()
+```
+
+---
+
+### Buffer Operations
+
+#### `send_buffer_with_prompt(opts?)`
+
+Send entire buffer content with optional prompt
+
+```lua
+api.send_buffer_with_prompt()
+```
+
+---
+
+### UI Components
+
+#### `open_command_picker(opts?, callback?)`
+
+Interactive command selector with custom handling
+
+```lua
+api.open_command_picker(nil, function(picker, item)
+  if item.text == "/custom" then
+    -- Implement custom command handling
+  else
+    -- Default behavior
+    picker:close()
+    api.send_command(item.text)
+  end
+end)
+```
+
+---
+
 ## 🧩 Other Aider Neovim plugins
 
 - [aider.nvim](https://github.com/joshuavial/aider.nvim)

lua/nvim_aider/api.lua

@@ -0,0 +1,124 @@
+local M = {}
+local commands = require("nvim_aider.commands")
+local config = require("nvim_aider.config")
+local picker = require("nvim_aider.picker")
+local terminal = require("nvim_aider.terminal")
+local utils = require("nvim_aider.utils")
+
+---Run health check
+function M.health_check()
+  vim.cmd([[checkhealth nvim_aider]])
+end
+
+---Toggle aider terminal
+---@param opts? table Optional configuration override
+function M.toggle_terminal(opts)
+  terminal.toggle(opts or {})
+end
+
+---Send text to aider terminal
+---@param text string Text to send
+---@param opts? table Optional configuration override
+function M.send_to_terminal(text, opts)
+  terminal.send(text, opts or {})
+end
+
+---Send command to aider terminal
+---@param command string Aider command to execute
+---@param input? string Additional input for the command
+---@param opts? table Optional configuration override
+function M.send_command(command, input, opts)
+  terminal.command(command, input, opts or {})
+end
+
+---Send buffer contents with optional prompt
+---@param opts? table Optional configuration override
+function M.send_buffer_with_prompt(opts)
+  local selected_text = table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), "\n")
+  local file_type = vim.bo.filetype
+  file_type = file_type == "" and "text" or file_type
+
+  vim.ui.input({ prompt = "Add a prompt to your buffer (empty to skip):" }, function(input)
+    if input ~= nil then
+      if input ~= "" then
+        selected_text = selected_text .. "\n> " .. input
+      end
+      terminal.send(selected_text, opts or {}, true)
+    end
+  end)
+end
+
+---Add specific file to session
+---@param filepath string Path to file to add
+---@param opts? table Optional configuration override
+function M.add_file(filepath, opts)
+  if filepath then
+    terminal.command(commands.add.value, filepath, opts or {})
+  else
+    vim.notify("No file path provided", vim.log.levels.ERROR)
+  end
+end
+
+---Add current file to session
+---@param opts? table Optional configuration override
+function M.add_current_file(opts)
+  local filepath = utils.get_absolute_path()
+  if filepath then
+    M.add_file(filepath, opts)
+  else
+    vim.notify("No valid file in current buffer", vim.log.levels.INFO)
+  end
+end
+
+---Remove specific file from session
+---@param filepath string Path to file to remove
+---@param opts? table Optional configuration override
+function M.drop_file(filepath, opts)
+  if filepath then
+    terminal.command(commands.drop.value, filepath, opts or {})
+  else
+    vim.notify("No file path provided", vim.log.levels.ERROR)
+  end
+end
+
+---Remove current file from session
+---@param opts? table Optional configuration override
+function M.drop_current_file(opts)
+  local filepath = utils.get_absolute_path()
+  if filepath then
+    M.drop_file(filepath, opts)
+  else
+    vim.notify("No valid file in current buffer", vim.log.levels.INFO)
+  end
+end
+
+---Add current file as read-only
+---@param opts? table Optional configuration override
+function M.add_read_only_file(opts)
+  local filepath = utils.get_absolute_path()
+  if filepath then
+    terminal.command(commands["read-only"].value, filepath, opts)
+  else
+    vim.notify("No valid file in current buffer", vim.log.levels.INFO)
+  end
+end
+
+---Open command picker
+---@param opts? table Optional configuration override
+---@param callback? function Custom callback handler
+function M.open_command_picker(opts, callback)
+  picker.create(opts, callback or function(picker_instance, item)
+    if item.category == "input" then
+      vim.ui.input({ prompt = "Enter input for `" .. item.text .. "` (empty to skip):" }, function(input)
+        if input then
+          terminal.command(item.text, input, opts)
+        end
+      end)
+    else
+      terminal.command(item.text, nil, opts)
+    end
+    picker_instance:close()
+  end)
+end
+
+return M