From 3919338ca4dc15e8a0eef369ac0a86c497c3f742 Mon Sep 17 00:00:00 2001 From: joaopluigi Date: Fri, 5 Sep 2025 14:48:05 -0300 Subject: [PATCH] move README.md content to docs/ directory --- README.md | 712 ++-------------------------------------- docs/configuration.md | 153 +++++++++ docs/development.md | 47 +++ docs/installation.md | 156 +++++++++ docs/troubleshooting.md | 65 ++++ docs/usage.md | 239 ++++++++++++++ 6 files changed, 691 insertions(+), 681 deletions(-) create mode 100644 docs/configuration.md create mode 100644 docs/development.md create mode 100644 docs/installation.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index b917b97..1e75efa 100644 --- a/README.md +++ b/README.md @@ -2,703 +2,53 @@ demo - -A modern Neovim plugin that integrates [ECA (Editor Code Assistant)](https://eca.dev/) directly into the editor, providing an integrated and intuitive AI experience. +A modern Neovim plugin that integrates [ECA (Editor Code Assistant)](https://eca.dev/) directly into the editor for an intuitive, streaming AI experience. ## โœจ Features - -- ๐Ÿค– **Integrated AI Chat**: Chat interface directly in Neovim -- ๐Ÿ“ **Smart Context**: Add files, directories and selections as context -- ๐Ÿš€ **Automatic Download**: ECA server downloads automatically -- โšก **Auto-start**: Server starts automatically with the plugin -- ๐ŸŽจ **Modern Interface**: Integrated sidebar with markdown support -- โŒจ๏ธ **Intuitive Commands**: Ctrl+S to send, Enter for new line -- ๐Ÿ”ง **Highly Configurable**: Customizable shortcuts, appearance and behavior -- ๐Ÿ“Š **Visual Feedback**: Status bar with server information -- ๐Ÿ”„ **Real-time Streaming**: Responses appear as they are generated - -## ๐Ÿ“ฆ Installation - -### ๐Ÿš€ [lazy.nvim](https://github.com/folke/lazy.nvim) (Recommended) - -#### Basic Configuration - -```lua -{ - "editor-code-assistant/eca-nvim", - dependencies = { - "MunifTanjim/nui.nvim", -- Required: UI framework - "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations - }, - opts = {} -} -``` - -#### Advanced Configuration - -```lua -{ - "editor-code-assistant/eca-nvim", - dependencies = { - "MunifTanjim/nui.nvim", -- Required: UI framework - "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations - }, - keys = { - { "ec", "EcaChat", desc = "Open ECA chat" }, - { "ef", "EcaFocus", desc = "Focus ECA sidebar" }, - { "et", "EcaToggle", desc = "Toggle ECA sidebar" }, - }, - opts = { - debug = false, - server_path = "", - behaviour = { - auto_set_keymaps = true, - auto_focus_sidebar = true, - }, - } -} -``` - -### ๐Ÿ“ฆ [packer.nvim](https://github.com/wbthomason/packer.nvim) - -```lua -use { - "editor-code-assistant/eca-nvim", - requires = { - "MunifTanjim/nui.nvim", -- Required: UI framework - "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations - }, - config = function() - require("eca").setup({ - -- Your configurations here - }) - end -} -``` - -### ๐Ÿ”Œ [vim-plug](https://github.com/junegunn/vim-plug) - -```vim -" In your init.vim or init.lua -Plug 'editor-code-assistant/eca-nvim' - -" Required dependencies -Plug 'MunifTanjim/nui.nvim' - -" Optional dependencies (enhanced async operations) -Plug 'nvim-lua/plenary.nvim' - -" After the plugins, add: -lua << EOF -require("eca").setup({ - -- Your configurations here -}) -EOF -``` - -### ๐Ÿ“‹ [dein.vim](https://github.com/Shougo/dein.vim) - -```vim -call dein#add('editor-code-assistant/eca-nvim') - -" Required dependencies -call dein#add('MunifTanjim/nui.nvim') - -" Optional dependencies (enhanced async operations) -call dein#add('nvim-lua/plenary.nvim') - -" Configuration -lua << EOF -require("eca").setup({ - -- Your configurations here -}) -EOF -``` - -### ๐Ÿฆ˜ [rocks.nvim](https://github.com/nvim-neorocks/rocks.nvim) - -```toml -# rocks.toml -[plugins] -"eca-nvim" = { git = "editor-code-assistant/eca-nvim" } - -# Required dependencies -"nui.nvim" = { git = "MunifTanjim/nui.nvim" } - -# Optional dependencies (enhanced async operations) -"plenary.nvim" = { git = "nvim-lua/plenary.nvim" } -``` - -### ๐ŸŒฑ [mini.deps](https://github.com/echasnovski/mini.nvim) - -```lua -local add = MiniDeps.add - -add({ - source = "editor-code-assistant/eca-nvim", - depends = { - "MunifTanjim/nui.nvim", -- Required: UI framework - "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations - } -}) - -require("eca").setup({ - -- Your configurations here -}) -``` +- ๐Ÿค– Integrated AI chat in Neovim +- ๐Ÿ“ Add files, directories and selections as context +- ๐Ÿš€ Automatic ECA server download and start +- ๐ŸŽจ Clean sidebar UI with Markdown rendering +- โŒจ๏ธ Intuitive defaults (Ctrl+S to send, Enter for newline) +- ๐Ÿ”ง Highly configurable windows, keymaps and behavior +- ๐Ÿ“Š Usage and status feedback ## โšก Quick Start +1. Install via your plugin manager (see Installation below) +2. Restart Neovim +3. Run `:EcaChat` or press `ec` +4. Type your message and press `Ctrl+S` +5. Add context with `:EcaAddFile` or `:EcaAddSelection` -1. **Install the plugin** using your favorite package manager -2. **Configure the plugin** (basic configuration is sufficient) -3. **Open the chat** with `:EcaChat` or `ec` -4. **Type your message** and press `Ctrl+S` to send -5. **Add context** using `:EcaAddFile` or `:EcaAddSelection` - -## ๐ŸŽฎ Available Commands - -| Command | Description | Example | -|---------|-------------|---------| -| `:EcaChat` | Opens ECA chat | `:EcaChat` | -| `:EcaToggle` | Toggles sidebar visibility | `:EcaToggle` | -| `:EcaFocus` | Focus on ECA sidebar | `:EcaFocus` | -| `:EcaClose` | Closes ECA sidebar | `:EcaClose` | -| `:EcaAddFile [file]` | Adds file as context | `:EcaAddFile src/main.lua` | -| `:EcaAddSelection` | Adds current selection as context | `:EcaAddSelection` | -| `:EcaServerStart` | Starts ECA server manually | `:EcaServerStart` | -| `:EcaServerStop` | Stops ECA server | `:EcaServerStop` | -| `:EcaServerRestart` | Restarts ECA server | `:EcaServerRestart` | -| `:EcaSend ` | Sends message directly | `:EcaSend Explain this function` | - -## โŒจ๏ธ Keyboard Shortcuts - -### Global Shortcuts (Default) - -| Shortcut | Action | Configuration | -|----------|--------|---------------| -| `ec` | Open/focus chat | `mappings.chat` | -| `ef` | Focus on sidebar | `mappings.focus` | -| `et` | Toggle sidebar | `mappings.toggle` | - -### Chat Shortcuts - -| Shortcut | Action | Context | -|----------|--------|---------| -| `Ctrl+S` | Send message | Insert/Normal mode | -| `Enter` | New line in message | Insert mode | -| `Esc` | Exit insert mode | Insert mode | - -## ๐Ÿ”ง Complete Configuration - -### All Available Options - -```lua -require("eca").setup({ - -- === BASIC SETTINGS === - - -- Enable debug mode (shows detailed logs) - debug = false, - - -- Path to ECA binary (empty = automatic download) - server_path = "", - - -- Extra arguments for ECA server - server_args = "--log-level info", - - -- Usage string format (tokens/cost) - usage_string_format = "{messageCost} / {sessionCost}", - - -- === BEHAVIOR === - behaviour = { - -- Set keymaps automatically - auto_set_keymaps = true, - - -- Focus sidebar automatically when opening - auto_focus_sidebar = true, - - -- Start server automatically - auto_start_server = true, - - -- Download server automatically if not found - auto_download = true, - - -- Show status updates in notifications - show_status_updates = true, - }, - - -- === KEY MAPPINGS === - mappings = { - chat = "ec", -- Open chat - focus = "ef", -- Focus sidebar - toggle = "et", -- Toggle sidebar - }, - - -- === WINDOW SETTINGS === - windows = { - -- Automatic line wrapping - wrap = true, - - -- Width as percentage of screen (1-100) - width = 40, - - -- Sidebar header configuration - sidebar_header = { - enabled = true, - align = "center", -- "left", "center", "right" - rounded = true, - }, - - -- Input area configuration - input = { - prefix = "> ", -- Input line prefix - height = 8, -- Input window height - }, - - -- Edit window configuration - edit = { - border = "rounded", -- "none", "single", "double", "rounded" - start_insert = true, -- Start in insert mode - }, - - -- Ask window configuration - ask = { - floating = false, -- Use floating window - start_insert = true, -- Start in insert mode - border = "rounded", - focus_on_apply = "ours", -- "ours" or "theirs" - }, - }, - - -- === HIGHLIGHTS AND COLORS === - highlights = { - diff = { - current = "DiffText", -- Highlight for current diff - incoming = "DiffAdd", -- Highlight for incoming diff - }, - }, -}) -``` - -### Configuration by Use Profile - -#### ๐ŸŽ๏ธ Minimalist Configuration - -```lua -require("eca").setup({ - behaviour = { show_status_updates = false }, - windows = { width = 30 }, -}) -``` - -#### ๐ŸŽจ Complete Visual Configuration - -```lua -require("eca").setup({ - behaviour = { auto_focus_sidebar = true }, - windows = { - width = 50, - wrap = true, - sidebar_header = { enabled = true, rounded = true }, - input = { prefix = "๐Ÿ’ฌ ", height = 10 }, - }, -}) -``` - -#### ๐Ÿš€ Development Configuration - -```lua -require("eca").setup({ - debug = true, - server_args = "--log-level debug", - behaviour = { - auto_start_server = true, - show_status_updates = true, - }, - mappings = { - chat = "", - toggle = "", - focus = "", - }, -}) -``` - -#### โšก Performance Configuration - -```lua -require("eca").setup({ - behaviour = { - auto_focus_sidebar = false, - show_status_updates = false, - }, - windows = { width = 25 }, -}) -``` - -## ๐Ÿ“ Detailed Usage Guide - -### ๐Ÿš€ Getting Started - -1. **Install the plugin** using any package manager -2. **Restart Neovim** or reload configuration -3. **Open a file** you want to analyze -4. **Run** `:EcaChat` or press `ec` -5. **Server will download automatically** on first run -6. **Type your question** and press `Ctrl+S` to send - -### ๐Ÿ’ฌ Using the Chat - -#### Sending Messages - -- **Type your message** in the line starting with `> ` -- **Press `Enter`** to break line (messages can have multiple lines) -- **Press `Ctrl+S`** to send the message -- **Wait for response** which appears in real time - -#### Message Examples - -```markdown -Explain what this function does -``` - -```markdown -Optimize this code: -[code will be added as context] -``` - -```markdown -How can I improve the performance of this function? -Consider readability and maintainability. -``` - -### ๐Ÿ“ Adding Context - -#### Current File - -```vim -:EcaAddFile -``` - -#### Specific File - -```vim -:EcaAddFile src/main.lua -:EcaAddFile /full/path/to/file.js -``` - -#### Code Selection - -1. Select code in visual mode (`v`, `V`, or `Ctrl+v`) -2. Run `:EcaAddSelection` -3. Selected code will be added as context - -#### Multiple Files - -```vim -:EcaAddFile src/utils.lua -:EcaAddFile src/config.lua -:EcaAddFile tests/test_utils.lua -``` - -### ๐ŸŽฏ Common Use Cases - -#### ๐Ÿ” Code Analysis - -```markdown -> Analyze this file and tell me if there are performance issues -``` - -#### ๐Ÿ› Debug and Problem Solving - -```markdown -> This code is returning an error. Can you help me identify the problem? -[add the file as context first] -``` - -#### ๐Ÿ“š Documentation - -```markdown -> Generate JSDoc documentation for these functions -``` - -#### โ™ป๏ธ Refactoring - -```markdown -> How can I refactor this code to use ES6+ features? -``` - -#### ๐Ÿงช Testing - -```markdown -> Create unit tests for this function -``` +> Requires Neovim >= 0.8.0, curl and unzip. -#### ๐Ÿ’ก Optimization +## ๐Ÿ“š Documentation +- Installation and system requirements: [docs/installation.md](./docs/installation.md) +- Usage guide (commands, keymaps, tips): [docs/usage.md](./docs/usage.md) +- Configuration reference and presets: [docs/configuration.md](./docs/configuration.md) +- Troubleshooting common issues: [docs/troubleshooting.md](./docs/troubleshooting.md) +- Development & contributing: [docs/development.md](./docs/development.md) -```markdown -> Suggest improvements to optimize this algorithm -``` - -### โŒจ๏ธ Recommended Workflow - -1. **Open the file** you want to analyze -2. **Add as context**: `:EcaAddFile` -3. **Open chat**: `ec` -4. **Ask your question**: - - ```markdown - > Explain what this function does and how I can improve it - ``` - -5. **Send with `Ctrl+S`** -6. **Read the response** and implement suggestions -7. **Continue conversation** for clarifications - -### ๐Ÿ”ง Advanced Commands - -#### Server Management - -```vim -" Restart if there are issues -:EcaServerRestart - -" Stop temporarily -:EcaServerStop - -" Start again -:EcaServerStart -``` - -#### Quick Commands - -```vim -" Send message directly (without opening chat) -:EcaSend Explain this line of code - -" Focus on chat if already open -:EcaFocus - -" Toggle chat visibility -:EcaToggle -``` - -## ๐Ÿ“‹ System Requirements - -### ๐Ÿ”ง Required - -- **Neovim >= 0.8.0** (Recommended: >= 0.9.0) -- **curl** (for automatic server download) -- **unzip** (for server extraction) -- **Internet connection** (for initial download and ECA functionality) - -### โœจ Optional - -- **[plenary.nvim](https://github.com/nvim-lua/plenary.nvim)** - Utility functions (some distributions) - -### ๐Ÿ’ป Tested Systems - -- โœ… **macOS** (Intel and Apple Silicon) -- โœ… **Linux** (Ubuntu, Arch, Fedora, etc.) -- โœ… **Windows** (WSL2 recommended) -- โœ… **FreeBSD** - -## ๐Ÿšจ Troubleshooting - -### โŒ Server won't start - -**Symptoms**: Chat doesn't respond, "server not running" error - -**Solutions**: - -- Check if `curl` and `unzip` are installed -- Try setting `server_path` manually with absolute path -- Check logs with `debug = true` in configuration -- Try `:EcaServerRestart` - -```lua --- Debug configuration -require("eca").setup({ - debug = true, - server_args = "--log-level debug", -}) -``` - -### ๐ŸŒ Connectivity issues - -**Symptoms**: Download fails, timeouts, network errors - -**Solutions**: - -- Check your internet connection -- Check if firewalls are not blocking -- Try restarting with `:EcaServerRestart` -- Configure proxy if necessary -- Download server manually and configure `server_path` - -### โŒจ๏ธ Shortcuts not working - -**Symptoms**: `ec` doesn't open chat - -**Solutions**: - -- Check if `behaviour.auto_set_keymaps = true` -- Confirm what your `` key is (default: `\`) -- Configure shortcuts manually: - -```lua -vim.keymap.set("n", "ec", ":EcaChat", { desc = "ECA Chat" }) -vim.keymap.set("n", "et", ":EcaToggle", { desc = "ECA Toggle" }) -``` - -### ๐Ÿ“ฑ Windows issues - -**Symptoms**: Path errors, server not found - -**Solutions**: - -- Use WSL2 for better compatibility -- Install curl and unzip on Windows -- Use forward slashes `/` in paths -- Configure `server_path` with `.exe` extension - -### ๐Ÿ”ง Performance issues - -**Symptoms**: Lag when typing, slow responses - -**Solutions**: - -- Reduce window width: `windows.width = 25` -- Disable visual updates: `behaviour.show_status_updates = false` -- Use minimalist configuration - -## ๐ŸŽ“ Tips and Tricks - -### ๐Ÿ’ก Productivity - -1. **Use `:EcaAddFile`** before asking questions about specific code -2. **Combine contexts**: Add multiple related files -3. **Be specific**: Detailed questions generate better responses -4. **Use markdown**: ECA understands markdown formatting in questions - -### ๐Ÿ”„ Workflows - -#### ๐Ÿ“ Code Review - -```markdown -> Analyze this code and suggest improvements: -- Performance -- Readability -- Best practices -- Possible bugs -``` - -#### ๐Ÿงช Test Creation - -```markdown -> Create comprehensive unit tests for this function, including: -- Success cases -- Error cases -- Edge cases -- Mocks if necessary -``` - -#### ๐Ÿ“š Documentation - -```markdown -> Generate complete documentation for this module: -- General description -- Parameters and types -- Usage examples -- Possible exceptions -``` - -### โŒจ๏ธ Custom Shortcuts - -```lua --- More convenient shortcuts -vim.keymap.set("n", "", ":EcaChat") -vim.keymap.set("n", "", ":EcaToggle") -vim.keymap.set("v", "ea", ":EcaAddSelection") - --- Shortcut to add current file -vim.keymap.set("n", "ef", function() - vim.cmd("EcaAddFile " .. vim.fn.expand("%")) -end) -``` - -## ๐Ÿค Development and Contribution - -### ๐Ÿ“ž Support - -- **Issues**: [GitHub Issues](https://github.com/editor-code-assistant/eca-nvim/issues) -- **Discussions**: [GitHub Discussions](https://github.com/editor-code-assistant/eca-nvim/discussions) -- **Wiki**: [GitHub Wiki](https://github.com/editor-code-assistant/eca-nvim/wiki) - -### ๐Ÿ”ง Local Development - -1. **Clone the repository**: - ```bash - git clone https://github.com/editor-code-assistant/eca-nvim.git - ``` - -2. **Configure local path**: - ```lua - require("eca").setup({ - debug = true, - -- Point to your local clone - -- server_path = "/path/to/eca-binary", - }) - ``` - -3. **Test changes**: - ```vim - :luafile % - :EcaServerRestart - ``` - -### ๐ŸŽฏ Contributing - -1. **Fork** the repository -2. **Create branch** for your feature: `git checkout -b feature/new-functionality` -3. **Commit** your changes: `git commit -m 'Add new functionality'` -4. **Push** to branch: `git push origin feature/new-functionality` -5. **Open Pull Request** - -### ๐Ÿงช Testing - -Run tests before submitting PR: - -```bash -# Unit tests -nvim --headless -c "lua require('eca.tests').run_all()" - -# Manual test -nvim -c "lua require('eca').setup({debug=true})" -``` +## ๐Ÿ”— Useful Links +- Official ECA Website: https://eca.dev/ +- ECA Documentation: https://docs.eca.dev/ +- VS Code Plugin: https://marketplace.visualstudio.com/items?itemName=editor-code-assistant.eca-vscode +- ECA GitHub: https://github.com/editor-code-assistant ## ๐Ÿ“„ License - -**MIT License** - see [LICENSE](LICENSE) for details. +MIT License โ€” see [LICENSE](LICENSE) for details. ## ๐Ÿ™ Acknowledgments - -This plugin was inspired and based on the work of: - -- **[avante.nvim](https://github.com/yetone/avante.nvim)** - Base structure and UI concepts -- **[eca-vscode](https://github.com/editor-code-assistant/eca-vscode)** - ECA server integration -- **Neovim Community** - For all the tools and inspiration - -## ๐Ÿ”— Useful Links - -- **[Official ECA Website](https://eca.dev/)** -- **[ECA Documentation](https://docs.eca.dev/)** -- **[VS Code Plugin](https://marketplace.visualstudio.com/items?itemName=editor-code-assistant.eca-vscode)** -- **[ECA GitHub](https://github.com/editor-code-assistant)** +Inspired by: +- avante.nvim โ€” base structure and UI concepts +- eca-vscode โ€” ECA server integration +- The Neovim community ---
-**โœจ Made with โค๏ธ for the Neovim community โœจ** +โœจ Made with โค๏ธ for the Neovim community โœจ [โญ Give a star if this plugin was useful!](https://github.com/editor-code-assistant/eca-nvim) diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..b9be743 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,153 @@ +# Configuration + +ECA is highly configurable. This page lists all available options and provides common presets. + +## Full configuration reference + +```lua +require("eca").setup({ + -- === BASIC SETTINGS === + + -- Enable debug mode (shows detailed logs) + debug = false, + + -- Path to ECA binary (empty = automatic download) + server_path = "", + + -- Extra arguments for ECA server + server_args = "--log-level info", + + -- Usage string format (tokens/cost) + usage_string_format = "{messageCost} / {sessionCost}", + + -- === BEHAVIOR === + behaviour = { + -- Set keymaps automatically + auto_set_keymaps = true, + + -- Focus sidebar automatically when opening + auto_focus_sidebar = true, + + -- Start server automatically + auto_start_server = true, + + -- Download server automatically if not found + auto_download = true, + + -- Show status updates in notifications + show_status_updates = true, + }, + + -- === KEY MAPPINGS === + mappings = { + chat = "ec", -- Open chat + focus = "ef", -- Focus sidebar + toggle = "et", -- Toggle sidebar + }, + + -- === WINDOW SETTINGS === + windows = { + -- Automatic line wrapping + wrap = true, + + -- Width as percentage of screen (1-100) + width = 40, + + -- Sidebar header configuration + sidebar_header = { + enabled = true, + align = "center", -- "left", "center", "right" + rounded = true, + }, + + -- Input area configuration + input = { + prefix = "> ", -- Input line prefix + height = 8, -- Input window height + }, + + -- Edit window configuration + edit = { + border = "rounded", -- "none", "single", "double", "rounded" + start_insert = true, -- Start in insert mode + }, + + -- Ask window configuration + ask = { + floating = false, -- Use floating window + start_insert = true, -- Start in insert mode + border = "rounded", + focus_on_apply = "ours", -- "ours" or "theirs" + }, + }, + + -- === HIGHLIGHTS AND COLORS === + highlights = { + diff = { + current = "DiffText", -- Highlight for current diff + incoming = "DiffAdd", -- Highlight for incoming diff + }, + }, +}) +``` + +--- + +## Presets + +### Minimalist +```lua +require("eca").setup({ + behaviour = { show_status_updates = false }, + windows = { width = 30 }, +}) +``` + +### Visual/UX focused +```lua +require("eca").setup({ + behaviour = { auto_focus_sidebar = true }, + windows = { + width = 50, + wrap = true, + sidebar_header = { enabled = true, rounded = true }, + input = { prefix = "๐Ÿ’ฌ ", height = 10 }, + }, +}) +``` + +### Development +```lua +require("eca").setup({ + debug = true, + server_args = "--log-level debug", + behaviour = { + auto_start_server = true, + show_status_updates = true, + }, + mappings = { + chat = "", + toggle = "", + focus = "", + }, +}) +``` + +### Performance-oriented +```lua +require("eca").setup({ + behaviour = { + auto_focus_sidebar = false, + show_status_updates = false, + }, + windows = { width = 25 }, +}) +``` + +--- + +## Notes +- Set `server_path` if you prefer using a local ECA binary. +- For noisy environments, disable `show_status_updates`. +- Adjust `windows.width` to fit your layout. +- Keymaps can be set manually by turning off `auto_set_keymaps`. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..0813acd --- /dev/null +++ b/docs/development.md @@ -0,0 +1,47 @@ +# Development and Contribution + +## Support +- Issues: https://github.com/editor-code-assistant/eca-nvim/issues +- Discussions: https://github.com/editor-code-assistant/eca-nvim/discussions +- Wiki: https://github.com/editor-code-assistant/eca-nvim/wiki + +## Local development + +1. Clone the repository + ```bash + git clone https://github.com/editor-code-assistant/eca-nvim.git + ``` + +2. Configure local path (optional) + ```lua + require("eca").setup({ + debug = true, + -- server_path = "/path/to/eca-binary", + }) + ``` + +3. Test changes + ```vim + :luafile % + :EcaServerRestart + ``` + +## Contributing + +1. Fork the repository +2. Create a branch: `git checkout -b feature/new-functionality` +3. Commit your changes: `git commit -m 'Add new functionality'` +4. Push to your branch: `git push origin feature/new-functionality` +5. Open a Pull Request + +## Testing + +Run tests before submitting a PR: + +```bash +# Unit tests +nvim --headless -c "lua require('eca.tests').run_all()" + +# Manual test +nvim -c "lua require('eca').setup({debug=true})" +``` diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..c5df383 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,156 @@ +# Installation + +This guide covers system requirements and how to install the ECA Neovim plugin with popular plugin managers. + +## System Requirements + +### Required +- Neovim >= 0.8.0 (Recommended: >= 0.9.0) +- curl (for automatic server download) +- unzip (for server extraction) +- Internet connection (for initial download and ECA functionality) + +### Optional +- plenary.nvim โ€” Utility functions used by some distributions + +### Tested Systems +- macOS (Intel and Apple Silicon) +- Linux (Ubuntu, Arch, Fedora, etc.) +- Windows (WSL2 recommended) +- FreeBSD + +--- + +## Install with popular plugin managers + +### lazy.nvim (recommended) + +```lua +{ + "editor-code-assistant/eca-nvim", + dependencies = { + "MunifTanjim/nui.nvim", -- Required: UI framework + "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations + }, + opts = {} +} +``` + +Advanced setup example: + +```lua +{ + "editor-code-assistant/eca-nvim", + dependencies = { + "MunifTanjim/nui.nvim", -- Required: UI framework + "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations + }, + keys = { + { "ec", "EcaChat", desc = "Open ECA chat" }, + { "ef", "EcaFocus", desc = "Focus ECA sidebar" }, + { "et", "EcaToggle", desc = "Toggle ECA sidebar" }, + }, + opts = { + debug = false, + server_path = "", + behaviour = { + auto_set_keymaps = true, + auto_focus_sidebar = true, + }, + } +} +``` + +### packer.nvim + +```lua +use { + "editor-code-assistant/eca-nvim", + requires = { + "MunifTanjim/nui.nvim", -- Required: UI framework + "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations + }, + config = function() + require("eca").setup({ + -- Your configurations here + }) + end +} +``` + +### vim-plug + +```vim +" In your init.vim or init.lua +Plug 'editor-code-assistant/eca-nvim' + +" Required dependencies +Plug 'MunifTanjim/nui.nvim' + +" Optional dependencies (enhanced async operations) +Plug 'nvim-lua/plenary.nvim' + +" After the plugins, add: +lua << EOF +require("eca").setup({ + -- Your configurations here +}) +EOF +``` + +### dein.vim + +```vim +call dein#add('editor-code-assistant/eca-nvim') + +" Required dependencies +call dein#add('MunifTanjim/nui.nvim') + +" Optional dependencies (enhanced async operations) +call dein#add('nvim-lua/plenary.nvim') + +" Configuration +lua << EOF +require("eca").setup({ + -- Your configurations here +}) +EOF +``` + +### rocks.nvim + +```toml +# rocks.toml +[plugins] +"eca-nvim" = { git = "editor-code-assistant/eca-nvim" } + +# Required dependencies +"nui.nvim" = { git = "MunifTanjim/nui.nvim" } + +# Optional dependencies (enhanced async operations) +"plenary.nvim" = { git = "nvim-lua/plenary.nvim" } +``` + +### mini.deps + +```lua +local add = MiniDeps.add + +add({ + source = "editor-code-assistant/eca-nvim", + depends = { + "MunifTanjim/nui.nvim", -- Required: UI framework + "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations + } +}) + +require("eca").setup({ + -- Your configurations here +}) +``` + +--- + +## Next steps +- See the Usage guide for getting started with chat and context: [docs/usage.md](./usage.md) +- Explore configuration options: [docs/configuration.md](./configuration.md) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..92df5c0 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,65 @@ +# Troubleshooting + +Common issues and how to fix them. + +## Server won't start + +Symptoms: Chat doesn't respond, "server not running" error + +Solutions: +- Check if `curl` and `unzip` are installed +- Try setting `server_path` manually with absolute path +- Check logs with `debug = true` in configuration +- Try `:EcaServerRestart` + +```lua +-- Debug configuration +require("eca").setup({ + debug = true, + server_args = "--log-level debug", +}) +``` + +## Connectivity issues + +Symptoms: Download fails, timeouts, network errors + +Solutions: +- Check your internet connection +- Ensure firewalls are not blocking requests +- Restart with `:EcaServerRestart` +- Configure a proxy if necessary +- Download the server manually and set `server_path` + +## Shortcuts not working + +Symptoms: `ec` doesn't open chat + +Solutions: +- Ensure `behaviour.auto_set_keymaps = true` +- Confirm your `` key (default: `\`) +- Configure shortcuts manually: + +```lua +vim.keymap.set("n", "ec", ":EcaChat", { desc = "ECA Chat" }) +vim.keymap.set("n", "et", ":EcaToggle", { desc = "ECA Toggle" }) +``` + +## Windows-specific + +Symptoms: Path errors, server not found + +Solutions: +- Use WSL2 for better compatibility +- Install curl and unzip on Windows +- Use forward slashes `/` in paths +- Configure `server_path` with `.exe` extension + +## Performance issues + +Symptoms: Lag when typing, slow responses + +Solutions: +- Reduce window width: `windows.width = 25` +- Disable visual updates: `behaviour.show_status_updates = false` +- Use the minimalist configuration preset diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..c69c219 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,239 @@ +# Usage + +Everything you need to get productive with ECA inside Neovim. + +## Quick Start + +1. Install the plugin using any package manager +2. Restart Neovim or reload your configuration +3. Open a file you want to analyze +4. Run `:EcaChat` or press `ec` +5. On first run, the server downloads automatically +6. Type your question and press `Ctrl+S` to send + +--- + +## Available Commands + +| Command | Description | Example | +|--------|-------------|---------| +| `:EcaChat` | Opens ECA chat | `:EcaChat` | +| `:EcaToggle` | Toggles sidebar visibility | `:EcaToggle` | +| `:EcaFocus` | Focus on ECA sidebar | `:EcaFocus` | +| `:EcaClose` | Closes ECA sidebar | `:EcaClose` | +| `:EcaAddFile [file]` | Adds file as context | `:EcaAddFile src/main.lua` | +| `:EcaAddSelection` | Adds current selection as context | `:EcaAddSelection` | +| `:EcaServerStart` | Starts ECA server manually | `:EcaServerStart` | +| `:EcaServerStop` | Stops ECA server | `:EcaServerStop` | +| `:EcaServerRestart` | Restarts ECA server | `:EcaServerRestart` | +| `:EcaSend ` | Sends message directly | `:EcaSend Explain this function` | + +--- + +## Keyboard Shortcuts + +### Global (default) + +| Shortcut | Action | +|----------|--------| +| `ec` | Open/focus chat | +| `ef` | Focus on sidebar | +| `et` | Toggle sidebar | + +### Chat + +| Shortcut | Action | Context | +|----------|--------|---------| +| `Ctrl+S` | Send message | Insert/Normal mode | +| `Enter` | New line | Insert mode | +| `Esc` | Exit insert mode | Insert mode | + +--- + +## Using the Chat + +### Sending messages +- Type in the input line starting with `> ` +- Press `Enter` to insert a new line +- Press `Ctrl+S` to send +- Responses stream in real time + +### Examples + +```markdown +Explain what this function does +``` + +```markdown +Optimize this code: +[code will be added as context] +``` + +```markdown +How can I improve the performance of this function? +Consider readability and maintainability. +``` + +--- + +## Adding Context + +### Current file + +```vim +:EcaAddFile +``` + +### Specific file + +```vim +:EcaAddFile src/main.lua +:EcaAddFile /full/path/to/file.js +``` + +### Code selection + +1. Select code in visual mode (`v`, `V`, or `Ctrl+v`) +2. Run `:EcaAddSelection` +3. Selected code will be added as context + +### Multiple files + +```vim +:EcaAddFile src/utils.lua +:EcaAddFile src/config.lua +:EcaAddFile tests/test_utils.lua +``` + +--- + +## Common Use Cases + +### Code analysis +```markdown +> Analyze this file and tell me if there are performance issues +``` + +### Debugging +```markdown +> This code is returning an error. Can you help me identify the problem? +[add the file as context first] +``` + +### Documentation +```markdown +> Generate JSDoc documentation for these functions +``` + +### Refactoring +```markdown +> How can I refactor this code to use ES6+ features? +``` + +### Testing +```markdown +> Create unit tests for this function +``` + +### Optimization +```markdown +> Suggest improvements to optimize this algorithm +``` + +--- + +## Recommended Workflow + +1. Open the file you want to analyze +2. Add as context: `:EcaAddFile` +3. Open chat: `ec` +4. Ask your question: + ```markdown + > Explain what this function does and how I can improve it + ``` +5. Send with `Ctrl+S` +6. Read the response and implement suggestions +7. Continue the conversation for clarifications + +--- + +## Advanced Commands + +### Server management + +```vim +" Restart if there are issues +:EcaServerRestart + +" Stop temporarily +:EcaServerStop + +" Start again +:EcaServerStart +``` + +### Quick commands + +```vim +" Send message directly (without opening chat) +:EcaSend Explain this line of code + +" Focus on chat if already open +:EcaFocus + +" Toggle chat visibility +:EcaToggle +``` + +--- + +## Tips and Tricks + +### Productivity +1. Use `:EcaAddFile` before asking about specific code +2. Combine contexts: add multiple related files +3. Be specific: detailed questions generate better responses +4. Use Markdown: ECA understands Markdown formatting + +### Workflows + +#### Code review +```markdown +> Analyze this code and suggest improvements: +- Performance +- Readability +- Best practices +- Possible bugs +``` + +#### Test creation +```markdown +> Create comprehensive unit tests for this function, including: +- Success cases +- Error cases +- Edge cases +- Mocks if necessary +``` + +#### Documentation +```markdown +> Generate complete documentation for this module: +- General description +- Parameters and types +- Usage examples +- Possible exceptions +``` + +### Custom shortcuts + +```lua +-- More convenient shortcuts +vim.keymap.set("n", "", ":EcaChat") +vim.keymap.set("n", "", ":EcaToggle") +vim.keymap.set("v", "ea", ":EcaAddSelection") + +-- Shortcut to add current file +vim.keymap.set("n", "ef", function() + vim.cmd("EcaAddFile " .. vim.fn.expand("%")) +end) +```