{"id":13412674,"url":"https://github.com/jbyuki/one-small-step-for-vimkind","last_synced_at":"2025-05-16T00:07:33.483Z","repository":{"id":39586369,"uuid":"350640627","full_name":"jbyuki/one-small-step-for-vimkind","owner":"jbyuki","description":"Debug adapter for Neovim plugins","archived":false,"fork":false,"pushed_at":"2025-05-10T14:22:57.000Z","size":219,"stargazers_count":474,"open_issues_count":5,"forks_count":13,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-10T15:24:54.288Z","etag":null,"topics":["dap-server","debugging","lua","neovim","nvim","nvim-dap"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbyuki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-23T08:49:30.000Z","updated_at":"2025-05-10T14:23:00.000Z","dependencies_parsed_at":"2024-01-03T03:30:36.007Z","dependency_job_id":"99673501-dcb9-4e94-a96a-db2e0882248a","html_url":"https://github.com/jbyuki/one-small-step-for-vimkind","commit_stats":{"total_commits":171,"total_committers":6,"mean_commits":28.5,"dds":0.04678362573099415,"last_synced_commit":"ad065ad2c814249cfb9e344ce5b2b35d36fbc09f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbyuki%2Fone-small-step-for-vimkind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbyuki%2Fone-small-step-for-vimkind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbyuki%2Fone-small-step-for-vimkind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbyuki%2Fone-small-step-for-vimkind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbyuki","download_url":"https://codeload.github.com/jbyuki/one-small-step-for-vimkind/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254442854,"owners_count":22071878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dap-server","debugging","lua","neovim","nvim","nvim-dap"],"created_at":"2024-07-30T20:01:27.663Z","updated_at":"2025-05-16T00:07:28.418Z","avatar_url":"https://github.com/jbyuki.png","language":"Lua","funding_links":[],"categories":["Neovim Lua Development","Lua"],"sub_categories":["Quickfix"],"readme":"# one-small-step-for-vimkind\n\n\n`one-small-step-for-vimkind` a.k.a. `osv` is an **adapter** for the Neovim lua language. See the [DAP protocol](https://microsoft.github.io/debug-adapter-protocol/overview) to know more about adapters. It allows you to debug any lua code running in a Neovim instance.\n\n## Install\n\nInstall using your prefered method for example using [vim-plug](https://github.com/junegunn/vim-plug)\n\n```vim\nPlug 'jbyuki/one-small-step-for-vimkind'\n\n\" You will also need a comptabile DAP client\n\nPlug 'mfussenegger/nvim-dap'\n```\n\nAfter installing `one-small-step-for-vimkind`, you will also need a DAP plugin which will allow you to interact with the adapter. There are mainly two available:\n\n  * [nvim-dap](https://github.com/mfussenegger/nvim-dap)\n  * [vimspector](https://github.com/puremourning/vimspector) \n\n## Configuration\n\nAdd these lines to work with [nvim-dap](https://github.com/mfussenegger/nvim-dap).\n\n```lua\nlocal dap = require\"dap\"\ndap.configurations.lua = { \n  { \n    type = 'nlua', \n    request = 'attach',\n    name = \"Attach to running Neovim instance\",\n  }\n}\n\ndap.adapters.nlua = function(callback, config)\n  callback({ type = 'server', host = config.host or \"127.0.0.1\", port = config.port or 8086 })\nend\n```\n\nSet keybindings to interact with the nvim-dap client.\n\n```lua\nvim.keymap.set('n', '\u003cleader\u003edb', require\"dap\".toggle_breakpoint, { noremap = true })\nvim.keymap.set('n', '\u003cleader\u003edc', require\"dap\".continue, { noremap = true })\nvim.keymap.set('n', '\u003cleader\u003edo', require\"dap\".step_over, { noremap = true })\nvim.keymap.set('n', '\u003cleader\u003edi', require\"dap\".step_into, { noremap = true })\n\nvim.keymap.set('n', '\u003cleader\u003edl', function() \n  require\"osv\".launch({port = 8086}) \nend, { noremap = true })\n\nvim.keymap.set('n', '\u003cleader\u003edw', function()\n  local widgets = require\"dap.ui.widgets\"\n  widgets.hover()\nend)\n\nvim.keymap.set('n', '\u003cleader\u003edf', function()\n  local widgets = require\"dap.ui.widgets\"\n  widgets.centered_float(widgets.frames)\nend)\n```\n\n## Quickstart\n\n* Launch the server in the debuggee using `\u003cleader\u003edl`\n* Open another Neovim instance with the source file\n* Place breakpoint with `\u003cleader\u003edb`\n* Connect using the DAP client with `\u003cleader\u003edc`\n* Run your script/plugin in the debuggee\n\nSee [osv.txt](https://github.com/jbyuki/lua-debug.nvim/blob/main/doc/osv.txt) for more detailed instructions.\n\n## Debug configuration files\n\nIt is now possible to debug configuration files (ex. `init.lua`).\nSee the corresponding section in [osv.txt](https://github.com/jbyuki/lua-debug.nvim/blob/main/doc/osv.txt#L198).\n\n## Troubleshoot\n\n### `flatten.nvim`\n\nSet `nest_if_no_args` to true. See [this issue](https://github.com/willothy/flatten.nvim/issues/41) for more informations.\n\n### `fzf-lua`\n\nUnder special circumstances, the headless instance can fail. See [this issue](https://github.com/jbyuki/one-small-step-for-vimkind/issues/45#issuecomment-2125749906) for more details.\n\n### Debugging plugins\n\nBreakpoints are path-sensitive so they should always be set in the executed file\neven though they might be multiple copies on the system.\n\nThis is the case for [packer.nvim](https://github.com/wbthomason/packer.nvim) when developing\nlocal plugins. packer.nvim will create a symlink to the plugins files in the `nvim-data` directory (\nit can be located using `:echo stdpath('data')`). Make sure to set the breakpoints inside \nthe source files in the `nvim-data` directory and not the local copy. The plugin directory\ncan be found in `nvim-data/site/pack/packer/start/YOUR_PLUGIN`.\n\nSee [osv.txt](https://github.com/jbyuki/lua-debug.nvim/blob/main/doc/osv.txt) for more detailed instructions.\n\n### Dropbox\n\nIf you're using a service like Dropbox to share your plugin file, there might be some issue arising with osv. The reason is that the path executed within Neovim and the path opened in dap doesn't match. Consequently, osv has no way to know if the current running script is the same file as the file opened inside the dap client. Try falling back to a local folder to see if this is the cause.\n\n### `Neovim is waiting for input at startup. Aborting`\n\nThis appears when the osv's spawned headless neovim instance has an error at startup. Vim will usually wait for an user input but in case of osv, the instance is simply blocked. Resolve any errors that you see at startup. If there are none, the error might be due to the \"headlessness\". Start using `nvim --headless` to see if there are any errors.\n\n### Breakpoint is not hit\n\n**Important** : Make sure osv is not running.\n\n1. Start tracing with `:lua require\"osv\".start_trace()`\n2. Perform the action that should be debugged (for ex. calling a function in your plugin)\n3. Stop tracing and display the results with `:lua =require\"osv\".stop_trace()` , the `=` will pretty print the resulting lua table.\n\nMake sure that the path is correct and the breakpoint is set to a line which effectively gets executed.\n\n## Status\n\nHandlers:\n\n* [x] attach\n* [x] scope\n* [x] setBreakpoints\n* [x] stackTrace\n* [x] threads\n* [x] variables\n* [x] stepIn\n* [x] next\n* [x] stepOut\n* [x] continue\n* [x] evaluate\n* [x] pause\n* [ ] terminate\n* [x] disconnect\n* [x] setVariable\n* [ ] setFunctionBreakpoints\n* [ ] setExceptionBreakpoints\n* [ ] breakpointLocations\n\nEvents:\n\n* [x] initialized\n* [x] stopped\n* [x] terminated\n* [x] exited\n* [ ] output\n\nCapabilities:\n\n* [x] supportsConditionalBreakpoints\n* [x] supportsHitConditionalBreakpoints\n* [x] supportsSetVariable\n* [x] supportTerminateDebuggee\n\n## Name\n\n\u003e it's a debugger for the moon language. - @tjdevries\n\n## Plugin architecture\n\nPlease refer to [ARCHITECTURE.md](ARCHITECTURE.md).\n\n## Credits\n\n* [mfussenegger/nvim-lua-debugger](https://github.com/mfussenegger/nvim-lua-debugger)\n\n## Alternatives\n\n* For an adapter limited to expression evaluation, see [mfussenegger/nluarepl](https://github.com/mfussenegger/nluarepl).\n \n## Contribute\n\nSee [here](https://github.com/jbyuki/ntangle.nvim/wiki/How-to-use-ntangle.nvim).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbyuki%2Fone-small-step-for-vimkind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbyuki%2Fone-small-step-for-vimkind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbyuki%2Fone-small-step-for-vimkind/lists"}