Skip to content

Commit 2575bad

Browse files
yaadatayaadata
committed
refactor(nvim): move global keymaps to lazy.nvim keys
1 parent 13c8868 commit 2575bad

File tree

11 files changed

+234
-601
lines changed

11 files changed

+234
-601
lines changed

‎README.md‎

Lines changed: 175 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,81 @@ Neovim plugin for running the Codex CLI in an embedded terminal.
2222
```lua
2323
{
2424
url = "https://codeberg.org/yaadata/codex.nvim.git",
25-
version = '0.3.0',
25+
version = "0.3.0",
26+
keys = {
27+
{
28+
"<leader>ot",
29+
function()
30+
require("codex").toggle()
31+
end,
32+
desc = "Codex: Toggle terminal",
33+
mode = { "n", "v" },
34+
},
35+
{
36+
"<leader>oo",
37+
function()
38+
require("codex").open(true)
39+
end,
40+
desc = "Codex: Open and focus",
41+
mode = { "n", "v" },
42+
},
43+
{
44+
"<leader>of",
45+
function()
46+
require("codex").focus()
47+
end,
48+
desc = "Codex: Focus terminal",
49+
mode = { "n", "v" },
50+
},
51+
{
52+
"<leader>ox",
53+
function()
54+
require("codex").close()
55+
end,
56+
desc = "Codex: Close session",
57+
mode = { "n", "v" },
58+
},
59+
{
60+
"<leader>os",
61+
function()
62+
require("codex").send_buffer()
63+
end,
64+
desc = "Codex: Add current buffer",
65+
mode = "n",
66+
},
67+
{
68+
"<leader>os",
69+
function()
70+
require("codex").send_selection()
71+
end,
72+
desc = "Codex: Send selection",
73+
mode = "x",
74+
},
75+
{
76+
"<leader>om",
77+
function()
78+
require("codex").mention_file()
79+
end,
80+
desc = "Codex: Mention current file",
81+
mode = { "n", "v" },
82+
},
83+
{
84+
"<leader>oM",
85+
function()
86+
require("codex").mention_directory()
87+
end,
88+
desc = "Codex: Mention current directory",
89+
mode = { "n", "v" },
90+
},
91+
{
92+
"<leader>oi",
93+
function()
94+
require("codex").show_status()
95+
end,
96+
desc = "Codex: Show status",
97+
mode = { "n", "v" },
98+
},
99+
},
26100
config = function()
27101
require("codex").setup({})
28102
end,
@@ -74,22 +148,6 @@ require("codex").setup({
74148
},
75149
},
76150
},
77-
keymaps = {
78-
toggle = "<leader>ot",
79-
open = "<leader>oo",
80-
focus = "<leader>of",
81-
close = "<leader>ox",
82-
send = "<leader>os",
83-
mention_file = "<leader>om",
84-
mention_dir = "<leader>oM",
85-
resume = "<leader>or",
86-
status = "<leader>oi",
87-
permissions = "<leader>op",
88-
compact = "<leader>oc",
89-
review = "<leader>oR",
90-
diff = "<leader>od",
91-
},
92-
keymaps_force = false, -- do not override existing mappings unless true
93151
})
94152
```
95153

@@ -120,59 +178,110 @@ For detailed command behavior and component interactions, see
120178

121179
## Keymaps
122180

123-
Default keymaps are registered under `<leader>o`:
181+
codex.nvim does not register global keymaps in `setup()`. Define global mappings
182+
in your lazy.nvim plugin spec `keys`:
124183

125184
```lua
126-
require("codex").setup({
127-
keymaps = {
128-
toggle = "<leader>ot",
129-
open = "<leader>oo",
130-
focus = "<leader>of",
131-
close = "<leader>ox",
132-
send = "<leader>os",
133-
mention_file = "<leader>om",
134-
mention_dir = "<leader>oM",
135-
resume = "<leader>or",
136-
status = "<leader>oi",
137-
permissions = "<leader>op",
138-
compact = "<leader>oc",
139-
review = "<leader>oR",
140-
diff = "<leader>od",
141-
},
142-
keymaps_force = false, -- keep existing user mappings by default
143-
})
144-
```
145-
146-
Override examples:
147-
148-
```lua
149-
-- Disable all default mappings
150-
require("codex").setup({
151-
keymaps = false,
152-
})
153-
154-
-- Override one mapping and disable another
155-
require("codex").setup({
156-
keymaps = {
157-
toggle = "<leader>xx",
158-
status = false,
185+
{
186+
url = "https://codeberg.org/yaadata/codex.nvim.git",
187+
version = "0.3.0",
188+
keys = {
189+
{
190+
"<leader>ot",
191+
function()
192+
require("codex").toggle()
193+
end,
194+
desc = "Codex: Toggle terminal",
195+
mode = { "n", "v" },
196+
},
197+
{
198+
"<leader>os",
199+
function()
200+
require("codex").send_buffer()
201+
end,
202+
desc = "Codex: Add current buffer",
203+
mode = "n",
204+
},
205+
{
206+
"<leader>os",
207+
function()
208+
require("codex").send_selection()
209+
end,
210+
desc = "Codex: Send selection",
211+
mode = "x",
212+
},
213+
{
214+
"<leader>om",
215+
function()
216+
require("codex").mention_file()
217+
end,
218+
desc = "Codex: Mention current file",
219+
mode = { "n", "v" },
220+
},
221+
{
222+
"<leader>oM",
223+
function()
224+
require("codex").mention_directory()
225+
end,
226+
desc = "Codex: Mention current directory",
227+
mode = { "n", "v" },
228+
},
229+
{
230+
"<leader>or",
231+
function()
232+
require("codex").resume()
233+
end,
234+
desc = "Codex: Resume session",
235+
mode = { "n", "v" },
236+
},
237+
{
238+
"<leader>oi",
239+
function()
240+
require("codex").show_status()
241+
end,
242+
desc = "Codex: Show status",
243+
mode = { "n", "v" },
244+
},
245+
{
246+
"<leader>op",
247+
function()
248+
require("codex").show_permissions()
249+
end,
250+
desc = "Codex: Permissions",
251+
mode = { "n", "v" },
252+
},
253+
{
254+
"<leader>oc",
255+
function()
256+
require("codex").compact()
257+
end,
258+
desc = "Codex: Compact context",
259+
mode = { "n", "v" },
260+
},
261+
{
262+
"<leader>oR",
263+
function()
264+
require("codex").review()
265+
end,
266+
desc = "Codex: Review changes",
267+
mode = { "n", "v" },
268+
},
269+
{
270+
"<leader>od",
271+
function()
272+
require("codex").show_diff()
273+
end,
274+
desc = "Codex: Show diff",
275+
mode = { "n", "v" },
276+
},
159277
},
160-
})
161-
162-
-- Intentionally overwrite existing mappings
163-
require("codex").setup({
164-
keymaps_force = true,
165-
})
278+
config = function()
279+
require("codex").setup({})
280+
end,
281+
}
166282
```
167283

168-
Set `vim.g.mapleader` before calling `require("codex").setup()` so `<leader>`
169-
expands to the expected key.
170-
171-
`keymaps.send` is mode-aware:
172-
173-
- Normal mode sends current buffer as `@path` (`:CodexAddBuffer`).
174-
- Visual mode sends selection as ACP line reference plus fenced code block
175-
(`:CodexSend`).
284+
Set `vim.g.mapleader` before plugin setup so `<leader>` expands as expected.
176285

177286
Terminal-local keymaps inside the Codex terminal buffer are configured
178287
separately via `terminal.keymaps`:
@@ -204,8 +313,7 @@ navigation keymaps, or set individual directions to `false`.
204313

205314
## Lua API
206315

207-
- `require("codex").setup(opts)` initialize plugin config, commands, and
208-
keymaps.
316+
- `require("codex").setup(opts)` initialize plugin config and commands.
209317
- `require("codex").open(focus)` open terminal session.
210318
- `require("codex").close()` close active session.
211319
- `require("codex").toggle()` toggle terminal visibility.

‎docs/architecture.md‎

Lines changed: 26 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ lua/codex/init.lua (public API facade, DI container, setup wiring)
1919
├──► config.lua (defaults, validation, deep merge)
2020
├──► logger.lua (level-gated vim.notify wrapper)
2121
├──► nvim/commands.lua (user command registration)
22-
├──► nvim/keymaps.lua (default keymap registration)
2322
├──► providers/init.lua (provider registry + auto-resolution)
2423
│ ├── native.lua
2524
│ └── snacks.lua
@@ -57,8 +56,6 @@ codex.nvim/
5756
│ ├── nvim/
5857
│ │ ├── commands.lua # Registers all :Codex* user commands. Each command
5958
│ │ # delegates to the corresponding init.lua API function.
60-
│ │ └── keymaps.lua # Registers default keymaps, skips collisions by default,
61-
│ │ # supports keymaps_force overrides, and handles re-register.
6259
│ ├── providers/
6360
│ │ ├── init.lua # Provider registry. Maps names to module paths,
6461
│ │ │ # lazy-loads on first resolve, implements auto-resolution
@@ -224,7 +221,6 @@ local default_deps = {
224221
session_store = require("codex.state.session_store"),
225222
send_queue = require("codex.runtime.send_queue"),
226223
commands = require("codex.nvim.commands"),
227-
keymaps = require("codex.nvim.keymaps"),
228224
formatter = require("codex.context.formatter"),
229225
selection = require("codex.context.selection"),
230226
path = require("codex.context.path"),
@@ -249,6 +245,10 @@ After resolving deps and config, `setup()` wires the constructor modules:
249245
This wiring order allows `send_dispatch` to reference the send queue (via
250246
closure) even though the queue is created after the dispatch instance.
251247

248+
After wiring, setup registers `:Codex*` commands and cleanup autocmds. Global
249+
keymaps are intentionally not managed in runtime setup; users configure them in
250+
their plugin manager (for example lazy.nvim `keys`).
251+
252252
### Error Handling
253253

254254
The codebase uses two error-reporting strategies:
@@ -292,29 +292,28 @@ and `---@alias` annotations. This file contains no runtime code (`return {}`).
292292

293293
Key types:
294294

295-
| Type | Kind | Purpose |
296-
| ---------------------------- | ----- | ------------------------------------------------------------- |
297-
| `codex.Config` | class | Merged configuration after `setup()` |
298-
| `codex.TerminalConfig` | class | Nested terminal-specific options |
299-
| `codex.WindowType` | alias | Window mode union: `vsplit`, `hsplit`, `float` |
300-
| `codex.VsplitConfig` | class | Vertical split options (`side`, `size_pct`) |
301-
| `codex.HsplitConfig` | class | Horizontal split options (`side`, `size_pct`) |
302-
| `codex.FloatConfig` | class | Floating window options (size, border, title, title_pos) |
303-
| `codex.TerminalKeymapConfig` | class | Terminal-local keymaps (`toggle`, `clear_input`, `close`) |
304-
| `codex.KeymapConfig` | class | Keymap action table (`string` or `false` per action) |
305-
| `codex.ProviderName` | alias | Union of valid provider name strings |
306-
| `codex.LogLevel` | alias | Union of log level strings |
307-
| `codex.Provider` | class | 9-method structural interface for providers |
308-
| `codex.ProviderHandle` | alias | Opaque handle (`table`) returned by `provider.open()` |
309-
| `codex.Session` | class | Session record extending `codex.SessionSpec` |
310-
| `codex.SessionSpec` | class | Spec for creating a new session |
311-
| `codex.SelectionSpec` | class | Visual selection data (defined in `formatter.lua`) |
312-
| `codex.SelectionOpts` | class | Options for selection extraction (defined in `selection.lua`) |
313-
| `codex.UserCommandOpts` | class | Neovim user command callback argument shape |
314-
| `codex.PendingSend` | class | Queued send item (defined in `send_dispatch.lua`) |
315-
| `codex.DispatchSendOpts` | class | Options for dispatch_send (defined in `send_dispatch.lua`) |
316-
| `codex.ResumeOpts` | class | Options for the resume API (defined in `init.lua`) |
317-
| `codex.SendResult` | alias | Boolean result alias (defined in `init.lua`) |
295+
| Type | Kind | Purpose |
296+
| ---------------------------- | ----- | ---------------------------------------------------------------- |
297+
| `codex.Config` | class | Merged configuration after `setup()` |
298+
| `codex.TerminalConfig` | class | Nested terminal-specific options |
299+
| `codex.WindowType` | alias | Window mode union: `vsplit`, `hsplit`, `float` |
300+
| `codex.VsplitConfig` | class | Vertical split options (`side`, `size_pct`) |
301+
| `codex.HsplitConfig` | class | Horizontal split options (`side`, `size_pct`) |
302+
| `codex.FloatConfig` | class | Floating window options (size, border, title, title_pos) |
303+
| `codex.TerminalKeymapConfig` | class | Terminal-local keymaps (`toggle`, `clear_input`, `close`, `nav`) |
304+
| `codex.ProviderName` | alias | Union of valid provider name strings |
305+
| `codex.LogLevel` | alias | Union of log level strings |
306+
| `codex.Provider` | class | 9-method structural interface for providers |
307+
| `codex.ProviderHandle` | alias | Opaque handle (`table`) returned by `provider.open()` |
308+
| `codex.Session` | class | Session record extending `codex.SessionSpec` |
309+
| `codex.SessionSpec` | class | Spec for creating a new session |
310+
| `codex.SelectionSpec` | class | Visual selection data (defined in `formatter.lua`) |
311+
| `codex.SelectionOpts` | class | Options for selection extraction (defined in `selection.lua`) |
312+
| `codex.UserCommandOpts` | class | Neovim user command callback argument shape |
313+
| `codex.PendingSend` | class | Queued send item (defined in `send_dispatch.lua`) |
314+
| `codex.DispatchSendOpts` | class | Options for dispatch_send (defined in `send_dispatch.lua`) |
315+
| `codex.ResumeOpts` | class | Options for the resume API (defined in `init.lua`) |
316+
| `codex.SendResult` | alias | Boolean result alias (defined in `init.lua`) |
318317

319318
`codex.ProviderHandle` is intentionally opaque (`table`). Providers define their
320319
own internal handle structure; the core never inspects handle contents.

‎docs/command-interactions.md‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,6 @@ init.lua setup()
4242
|- send_queue.new({ process = send_dispatch.process_pending_send_item })
4343
|- mention.create({ get_deps, get_config, dispatch_send })
4444
|- commands.register()
45-
|- keymaps.register(config)
46-
| |- unregister stale Codex keymaps from previous setup
47-
| |- skip keymaps when keymaps=false
48-
| |- skip mapping collisions unless keymaps_force=true
49-
| \- register n/x mappings for Codex actions
5045
\- register VimLeavePre cleanup autocmd
5146
```
5247

0 commit comments

Comments
 (0)