vimamsa 0.1.26 → 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/appimage.yml +93 -0
  3. data/.gitignore +4 -1
  4. data/Dockerfile +7 -4
  5. data/README.md +62 -16
  6. data/custom_example.rb +43 -13
  7. data/doc/TODO.md +461 -0
  8. data/doc/bundling_plan.md +569 -0
  9. data/doc/key_bindings_report_plan.md +168 -0
  10. data/doc/missing_vim_bindings.md +71 -0
  11. data/doc/modules_settings_plan.md +433 -0
  12. data/doc/refactor_dedup_plan.md +117 -0
  13. data/doc/unused_code_plan.md +120 -0
  14. data/doc/vim_compatibility_plan.md +296 -0
  15. data/doc/vimlike_vim_conflicts.md +254 -0
  16. data/doc/vm_snapshots_plan.md +146 -0
  17. data/exe/run_tests.rb +117 -3
  18. data/exe/vimamsa +24 -4
  19. data/fonts/OFL-Oxanium.txt +93 -0
  20. data/fonts/Oxanium[wght].ttf +0 -0
  21. data/icon.png +0 -0
  22. data/img/demo.gif +0 -0
  23. data/lang/hyperplaintext.lang +6 -0
  24. data/lib/vimamsa/ack.rb +11 -1
  25. data/lib/vimamsa/actions.rb +4 -1
  26. data/lib/vimamsa/appimage_env.rb +35 -0
  27. data/lib/vimamsa/audio.rb +2 -5
  28. data/lib/vimamsa/bookmarks.rb +302 -0
  29. data/lib/vimamsa/buffer.rb +593 -82
  30. data/lib/vimamsa/buffer_changetext.rb +102 -42
  31. data/lib/vimamsa/buffer_cursor.rb +7 -0
  32. data/lib/vimamsa/buffer_list.rb +4 -0
  33. data/lib/vimamsa/buffer_manager.rb +4 -1
  34. data/lib/vimamsa/bundled_fonts.rb +32 -0
  35. data/lib/vimamsa/clipboard.rb +3 -0
  36. data/lib/vimamsa/conf.rb +59 -3
  37. data/lib/vimamsa/constants.rb +3 -0
  38. data/lib/vimamsa/crash_handler.rb +149 -0
  39. data/lib/vimamsa/debug.rb +4 -1
  40. data/lib/vimamsa/desktop_install.rb +96 -0
  41. data/lib/vimamsa/diff_buffer.rb +39 -10
  42. data/lib/vimamsa/easy_jump.rb +3 -0
  43. data/lib/vimamsa/editor.rb +263 -57
  44. data/lib/vimamsa/encrypt.rb +78 -29
  45. data/lib/vimamsa/file_finder.rb +4 -19
  46. data/lib/vimamsa/file_history.rb +3 -0
  47. data/lib/vimamsa/file_manager.rb +30 -15
  48. data/lib/vimamsa/fold.rb +226 -0
  49. data/lib/vimamsa/gui.rb +520 -106
  50. data/lib/vimamsa/gui_command_line.rb +208 -0
  51. data/lib/vimamsa/gui_dialog.rb +94 -42
  52. data/lib/vimamsa/gui_file_panel.rb +356 -25
  53. data/lib/vimamsa/gui_form_generator.rb +59 -35
  54. data/lib/vimamsa/gui_func_panel.rb +67 -22
  55. data/lib/vimamsa/gui_image.rb +3 -0
  56. data/lib/vimamsa/gui_keylog_panel.rb +246 -0
  57. data/lib/vimamsa/gui_menu.rb +23 -11
  58. data/lib/vimamsa/gui_select_window.rb +19 -48
  59. data/lib/vimamsa/gui_settings.rb +78 -37
  60. data/lib/vimamsa/gui_sourceview.rb +273 -19
  61. data/lib/vimamsa/gui_sourceview_autocomplete.rb +319 -90
  62. data/lib/vimamsa/gui_text.rb +63 -2
  63. data/lib/vimamsa/gui_theme.rb +606 -0
  64. data/lib/vimamsa/hook.rb +3 -0
  65. data/lib/vimamsa/hyper_plain_text.rb +3 -0
  66. data/lib/vimamsa/key_actions.rb +112 -13
  67. data/lib/vimamsa/key_binding_tree.rb +242 -215
  68. data/lib/vimamsa/key_bindings_notepad.rb +43 -0
  69. data/lib/vimamsa/key_bindings_report.rb +261 -0
  70. data/lib/vimamsa/key_bindings_vim.rb +354 -0
  71. data/lib/vimamsa/key_bindings_vimlike.rb +65 -9
  72. data/lib/vimamsa/langservp.rb +271 -54
  73. data/lib/vimamsa/macro.rb +3 -0
  74. data/lib/vimamsa/main.rb +14 -8
  75. data/lib/vimamsa/rbvma.rb +26 -1
  76. data/lib/vimamsa/search.rb +3 -0
  77. data/lib/vimamsa/search_replace.rb +11 -10
  78. data/lib/vimamsa/string_util.rb +120 -40
  79. data/lib/vimamsa/terminal.rb +3 -0
  80. data/lib/vimamsa/test_framework.rb +28 -2
  81. data/lib/vimamsa/tests.rb +3 -0
  82. data/lib/vimamsa/text_objects.rb +353 -0
  83. data/lib/vimamsa/text_transforms.rb +14 -0
  84. data/lib/vimamsa/util.rb +46 -7
  85. data/lib/vimamsa/version.rb +1 -1
  86. data/lib/vimamsa.rb +0 -1
  87. data/modules/color_highlight/color_highlight.rb +118 -0
  88. data/modules/color_highlight/color_highlight_info.rb +3 -0
  89. data/modules/dictation/dictation.rb +1054 -0
  90. data/modules/dictation/dictation_info.rb +3 -0
  91. data/modules/dictation/whisper_worker.py +273 -0
  92. data/modules/ollama/ollama.rb +107 -0
  93. data/modules/ollama/ollama_info.rb +3 -0
  94. data/modules/tts/tts.rb +119 -0
  95. data/modules/tts/tts_info.rb +3 -0
  96. data/run_e2e_vm.sh +28 -0
  97. data/run_tests_vm.sh +130 -0
  98. data/scripts/appimage/AppRun +54 -0
  99. data/scripts/appimage/Dockerfile +18 -0
  100. data/scripts/appimage/build.sh +19 -0
  101. data/scripts/appimage/build_in_container.sh +192 -0
  102. data/scripts/appimage/smoke_test.sh +27 -0
  103. data/scripts/demo/demo_steps.txt +59 -0
  104. data/scripts/demo/record_demo.rb +177 -0
  105. data/scripts/demo/shapes.rb +28 -0
  106. data/styles/134272-molokai.xml +3 -0
  107. data/styles/molokai_cyber.xml +48 -0
  108. data/styles/molokai_edit.xml +1 -0
  109. data/tests/support/virtual_keyboard.rb +254 -0
  110. data/tests/support/virtual_mic.rb +67 -0
  111. data/tests/test_ack.rb +22 -0
  112. data/tests/test_auto_format.rb +122 -0
  113. data/tests/test_autocomplete.rb +211 -0
  114. data/tests/test_autosave.rb +145 -0
  115. data/tests/test_basic_editing.rb +33 -3
  116. data/tests/test_bookmarks.rb +206 -0
  117. data/tests/test_bracket_match.rb +85 -0
  118. data/tests/test_bundling.rb +92 -0
  119. data/tests/test_color_highlight.rb +92 -0
  120. data/tests/test_command_line.rb +79 -0
  121. data/tests/test_command_line_file.rb +27 -0
  122. data/tests/test_context_menu_file.rb +129 -0
  123. data/tests/test_copy_paste.rb +80 -0
  124. data/tests/test_crash_handler.rb +39 -0
  125. data/tests/test_custom_two_phase.rb +92 -0
  126. data/tests/test_dialog_callback_errors.rb +44 -0
  127. data/tests/test_dictation.rb +294 -0
  128. data/tests/test_diff_buffer_name.rb +51 -0
  129. data/tests/test_double_click.rb +41 -0
  130. data/tests/test_drag_selection.rb +125 -0
  131. data/tests/test_e2e_cmdline.rb +116 -0
  132. data/tests/test_e2e_dictation.rb +98 -0
  133. data/tests/test_e2e_replace_char.rb +58 -0
  134. data/tests/test_extract_file_links.rb +55 -0
  135. data/tests/test_file_format.rb +217 -0
  136. data/tests/test_file_manager.rb +72 -0
  137. data/tests/test_file_panel.rb +269 -0
  138. data/tests/test_flash.rb +78 -0
  139. data/tests/test_fold.rb +111 -0
  140. data/tests/test_font_refresh.rb +56 -0
  141. data/tests/test_func_panel.rb +68 -0
  142. data/tests/test_grep_apply.rb +46 -0
  143. data/tests/test_gtk_sync.rb +126 -0
  144. data/tests/test_hpt_highlight_visible.rb +75 -0
  145. data/tests/test_hpt_link_highlight.rb +82 -0
  146. data/tests/test_jump_to_file.rb +41 -0
  147. data/tests/test_key_bindings.rb +208 -0
  148. data/tests/test_keylog_panel.rb +101 -0
  149. data/tests/test_lsp_clangd.rb +281 -0
  150. data/tests/test_lsp_jump.rb +87 -0
  151. data/tests/test_lsp_position_encoding.rb +49 -0
  152. data/tests/test_lsp_symbols.rb +68 -0
  153. data/tests/test_macro.rb +137 -0
  154. data/tests/test_markdown_highlight.rb +57 -0
  155. data/tests/test_mode_badge.rb +41 -0
  156. data/tests/test_notepad_bindings.rb +67 -0
  157. data/tests/test_popup_queue.rb +51 -0
  158. data/tests/test_random_edit.rb +109 -0
  159. data/tests/test_revert.rb +127 -0
  160. data/tests/test_startup_file.rb +58 -0
  161. data/tests/test_status_area.rb +50 -0
  162. data/tests/test_text_objects.rb +163 -0
  163. data/tests/test_text_transforms.rb +329 -0
  164. data/tests/test_tts.rb +68 -0
  165. data/tests/test_vim_bindings.rb +252 -0
  166. data/tests/test_vim_conflicts.rb +63 -0
  167. data/tests/test_window_layout.rb +219 -0
  168. data/vimamsa.gemspec +3 -1
  169. data/vm_guest_run.sh +109 -0
  170. metadata +112 -10
@@ -0,0 +1,168 @@
1
+ # Plan: better organized "Show key bindings" page
2
+
3
+ ## Context
4
+
5
+ Help ▸ Show key bindings (`show_key_bindings`, `lib/vimamsa/key_bindings_report.rb:18`)
6
+ dumps lines like
7
+
8
+ [C] d i <char> : buf.text_object_op(:delete, <char>, :i)
9
+
10
+ into the catch-all **Others** section. The page should be organized by what the user
11
+ wants to do, with readable descriptions, and work the same way for every keybinding
12
+ scheme.
13
+
14
+ ## Why it's disorganized now (verified 2026-11-19)
15
+
16
+ 1. **Sections are hardcoded to the vimlike keywords.** The report asks
17
+ `get_by_keywords` for `intro`, `hyperplaintext`, `core` and `experimental`, and
18
+ everything else goes to Others. The `vim` scheme tags its bindings `vim motion`,
19
+ `vim edit`, `vim visual`, `vim insert`, `vim replace` and `vim misc`, and notepad
20
+ tags them `notepad`. With those schemes, **almost every binding ends up in Others.**
21
+ 2. **`core` is one bucket for about 205 bindings** (`key_bindings_vimlike.rb:114-390`):
22
+ motions, file and buffer handling, deleting, marks, macros, mode switches. The
23
+ file already has comment headers for these groups (`# MOVING`, `#### Deleting`,
24
+ `# Marks`, `# Macros`, `# Buffer handling`, …), but the keyword ignores them.
25
+ 3. **Bindings registered outside the scheme files have ad-hoc or no keywords, so they
26
+ land in Others.** These are text objects (`text_objects.rb:351`, keyword
27
+ `vim text objects`), the file manager (13 `bindkey`s), grep, bookmarks, the buffer
28
+ manager, diff view, the minor modes (`audio`, `macro`, `bmgr`, `bmark`, `grep`,
29
+ `diffview`, `fexp`) and modules (`ollama`, `tts`, `dictation`, `color_highlight`).
30
+ 4. **Template families show up as cryptic raw lines.** For example, text objects are
31
+ `ops × {i,a} × <char>`: 13 lines that all look the same and don't show which
32
+ objects exist (`iw`, `i(`, `it`, …).
33
+ 5. **Raw Ruby instead of descriptions.** This is a separate TODO item ("Descriptive
34
+ names for key bindings"), and this plan depends on it.
35
+ 6. **Raw conditions such as `I tab(vma.buf.view.autocp_active)`** are shown as Ruby
36
+ code.
37
+ 7. **Lines are sorted alphabetically by the whole `[Mode] keys` string**, so related
38
+ bindings are scattered, and the mode letter is the main sort key. Deduplication is
39
+ done by string-matching rendered lines (`done.concat(x.lines)`).
40
+
41
+ ## Design
42
+
43
+ ### 1. Structured binding list from the tree
44
+
45
+ Add `KeyBindingTree#bindings` → array of records
46
+ `{ mode:, keys:, action:, keywords:, eval_rule:, desc: }`, using the same traversal as
47
+ `get_by_keywords` (`key_binding_tree.rb:374`). Fill in `desc` through the
48
+ `action_description` helper from the descriptions TODO item. The report, the
49
+ free-bindings report and the vim-conflicts report are built from this data instead of
50
+ from parsed strings. `get_by_keywords` stays as a thin wrapper for existing callers and
51
+ tests.
52
+
53
+ ### 2. A fixed category list, tagged with `cat:<id>` keywords
54
+
55
+ One ordered list in `key_bindings_report.rb` (or a small `key_categories.rb`):
56
+
57
+ | id | Heading |
58
+ |---|---|
59
+ | `basic` | Basics (quick start) |
60
+ | `motion` | Moving the cursor |
61
+ | `search` | Searching and jumping (`/`, `n`, `*`, `f`/`t`, easy-jump, `gf`) |
62
+ | `insert` | Entering insert mode and typing |
63
+ | `edit` | Delete, change, copy, paste (operators and their motions) |
64
+ | `textobj` | Text objects |
65
+ | `case` | Case and text transforms |
66
+ | `visual` | Visual mode |
67
+ | `undo` | Undo, redo, repeat |
68
+ | `marks` | Marks and bookmarks |
69
+ | `macro` | Macros |
70
+ | `file` | Files (open, save, finder, history, file manager) |
71
+ | `buffer` | Buffers and windows (switch, close, two-column) |
72
+ | `view` | Panels and view (file/func/keylog panels, folding, font) |
73
+ | `grep` | Search across files (grep lines, ack) |
74
+ | `code` | Code (LSP, auto-format, comment, run line) |
75
+ | `hpt` | Hyper plaintext |
76
+ | `module:<name>` | Modules ▸ <name from `_info`> |
77
+ | `mode:<id>` | Minor modes (audio, macro, bmgr, bmark, grep, diffview, fexp) |
78
+ | `debug` | Debug / experimental |
79
+
80
+ - **Tagging.** `add_keys` keywords get a `cat:<id>` word, e.g. `add_keys "core cat:motion", {...}`.
81
+ The existing keywords stay, so nothing that queries them breaks.
82
+ - **Split vimlike's big `core` block** into several `add_keys` calls at its existing
83
+ comment headers. Do the same for the vim scheme's six sections and for notepad.
84
+ - **Automatic categories, so most code doesn't need manual tags:**
85
+ - a binding in a minor mode (first key is a minor-mode id) → `mode:<id>`
86
+ - a binding added from inside a module's `<name>_init` → `module:<name>`. Set a
87
+ "current module" context in `module_set_enabled` / the startup loop, and have
88
+ `bindkey` add the keyword.
89
+ - legacy keyword map: `vim motion` → `motion`, `vim text objects` → `textobj`,
90
+ `hyperplaintext` → `hpt`, `experimental` → `debug`, etc.
91
+ - **Basics stays independent of the scheme.** Instead of the vimlike-only `intro`
92
+ keyword, define `BASIC_ACTIONS` (save, quit, undo/redo, insert, esc, search, open
93
+ file, switch buffer, show key bindings, …) and show whatever keys the active scheme
94
+ binds them to. Those bindings still also appear in their own category.
95
+
96
+ ### 3. Page layout
97
+
98
+ ```
99
+ ❙Key bindings — scheme: vimlike❙
100
+ [C]=Command [I]=Insert [V]=Visual … <key>! = press and release alone
101
+
102
+ ◼ Moving the cursor
103
+ Command / Visual
104
+ h j k l Move left / down / up / right
105
+ w b e Next word start / previous word start / word end
106
+ <count> G Go to line <count>
107
+ Insert
108
+ ctrl-a Start of line
109
+ …
110
+ ◼ Text objects
111
+ Operators: d (delete) c (change) y (copy) gU gu g~ (case) v (select, Visual)
112
+ Objects: iw aw iW aW is as ip ap i" a" i' a' i` a` i( a( (ib ab) i[ a[
113
+ i{ a{ (iB aB) i< a< it at
114
+ Examples: d i w delete word · c i " change inside quotes · y a p copy paragraph
115
+ ```
116
+
117
+ - Within a category, bindings are grouped by **mode** as a subheading, not used as a
118
+ sort key. Inside a group they're kept in **definition order** (the order in the
119
+ scheme file, which is logical: hjkl together), not alphabetical.
120
+ - Keys that share one description are merged on one line (`"VCX up" / "VC k"` →
121
+ `k up`).
122
+ - Columns are aligned: keys | description. The raw action is dimmed after the
123
+ description only when it adds something (see the descriptions TODO), or always for
124
+ Ruby-string actions as `⟨code⟩`.
125
+ - **Template families get a custom renderer.** A category can provide a block that
126
+ draws its section. `textobj` draws the operator × object table above from the
127
+ text-object definitions in `text_objects.rb`, so it can't go out of date. `<char>`
128
+ / `<num>` bindings show as `d f <char>`, `d <count> e` with a description that
129
+ names the placeholder.
130
+ - **Conditions** (`eval_rule`) are shown as readable text through a small table
131
+ (`"vma.buf.view.autocp_active"` → "when the completion popup is open",
132
+ `"vma.kbd.next_command_count!=nil"` → "with a count"). Unknown rules are shown dimmed
133
+ as they are.
134
+ - Categories with no bindings in the active scheme are left out. The header says
135
+ which scheme is shown.
136
+
137
+ ### 4. Keep it organized: a test instead of Others
138
+
139
+ - For each scheme (via `load_scheme_kbd`, `key_bindings_report.rb`), every binding
140
+ resolves to exactly one known category. Any that don't are printed, so a new
141
+ binding without a category fails the suite. Others stays only as a runtime
142
+ fallback, for bindings users add in `custom.rb`, under the heading "Your bindings
143
+ (custom.rb)" if `bindkey` was called during custom.rb loading. Otherwise it's
144
+ "Uncategorized".
145
+ - Snapshot-ish test: the rendered page for vimlike contains the headings in order and
146
+ the text-object table, and contains no `buf.text_object_op(` line.
147
+
148
+ ### 5. Optional follow-ups
149
+
150
+ - Hyperplaintext folding per `◼` section, so long categories can be collapsed.
151
+ - `show_key_bindings` takes an optional filter (category or search string). Add menu
152
+ entries "Key bindings: Editing", …, or reuse Search for Actions for that.
153
+ - Show the category in Search for Actions results.
154
+
155
+ ## Implementation order
156
+
157
+ 1. `KeyBindingTree#bindings` (structured records) + tests. Port `show_key_bindings`
158
+ to it with the current sections. Output stays the same.
159
+ 2. Category list, `cat:` tagging, auto-categories (minor mode, module, legacy map).
160
+ Split the big vimlike `core` block and tag the vim/notepad sections. Add the
161
+ "no uncategorized bindings" test.
162
+ 3. New layout: grouping by mode, definition order, merged keys, aligned columns,
163
+ condition text, scheme in the header, Basics from `BASIC_ACTIONS`.
164
+ 4. Text-object renderer and `<char>`/`<num>` template rendering.
165
+ 5. Descriptions (the separate TODO item) fill in the description column. This can run
166
+ in parallel; until then the column shows the raw action.
167
+
168
+ Run the full suite in the VM after each step.
@@ -0,0 +1,71 @@
1
+ # Vim keybindings missing from Vimamsa
2
+
3
+ Comparison of Vimamsa's two Vim-style keymaps against standard Vim:
4
+
5
+ - `vimlike` (default) — `lib/vimamsa/key_bindings_vimlike.rb`
6
+ - `vim` (`cnf.keybindings.scheme = "vim"`) — `lib/vimamsa/key_bindings_vim.rb`
7
+
8
+ The scheme is selected in `lib/vimamsa/editor.rb` (`Editor#start`).
9
+
10
+ This list comes from reading the binding files, not from testing in the editor.
11
+ The generated [vimlike_vim_conflicts.md](vimlike_vim_conflicts.md) compares the two
12
+ keymaps binding by binding.
13
+
14
+ ## Root cause
15
+
16
+ There is no general operator + motion system. Each combination (`d e`, `c w`, ...)
17
+ is bound individually, so any combination nobody wrote out is missing.
18
+
19
+ ## Case changes
20
+
21
+ Done: `gUw`, `guw`, `g~w`, `gUU`, `guu`, `g~~` and `~` work in both keymaps, and
22
+ `vimlike` also has Visual `U`, `u`, `~`. Still missing: counts (`2gUw`) and other
23
+ motions or text objects after the operator (`gUe`, `gUiw`, ...), which need the
24
+ operator-pending layer below.
25
+
26
+ ## Operators: change, delete, yank
27
+
28
+ - `vimlike` has no change operator at all: no `c w`, `c c`, `C`, `S`, `D` or `Y`.
29
+ Its `C`, `s` and `S` are bound to other actions. The `vim` keymap has these.
30
+ - Many combinations are missing in both, such as `d b`, `c b`, `y b`, `d t x`,
31
+ `c f x`, `d G`, `d g g` and `d }`. `d j` and `d k` are missing in both keymaps
32
+ (in `vimlike` they're commented-out TODOs).
33
+ - A count after the operator (`d 3 w`, `y 2 y`, `d 2 f x`) works only for `d <num> e`
34
+ in `vimlike`. A count before the command (`3 d w`) works, because the action is
35
+ repeated.
36
+ - Text objects are done in both keymaps (`lib/vimamsa/text_objects.rb`): `iw aw iW aW
37
+ is as ip ap`, the quotes, the brackets and `it at`, after `d c y gU gu g~` and in
38
+ Visual mode. Counts work for brackets and tags (`2di(`). Not done yet: a count after
39
+ the operator (`d2i(`) and repeating `i(` in Visual mode to grow the selection.
40
+ - Indenting from Command mode (`>>`, `<<`, `=`) is missing. Visual `>` and `<` exist
41
+ only in the `vim` keymap.
42
+
43
+ ## Motions
44
+
45
+ - `t` / `T` (move to just before a character) and `,` (repeat `f` backwards).
46
+ - `W` / `B` / `E` (move by whitespace-separated "WORD"), and `ge`.
47
+ - `{` / `}` (paragraph), `(` / `)` (sentence) and `%` (matching bracket).
48
+ - `H` / `M` / `L` (top, middle and bottom of the screen).
49
+ - `#` (search backward for the word under the cursor).
50
+
51
+ ## Scrolling and jumps
52
+
53
+ - `ctrl-e` / `ctrl-y` (scroll by one line), and `zt` / `zb`.
54
+ - `ctrl-i` (jump forward). `ctrl-o` is only an approximation that goes to the last
55
+ edit.
56
+ - `ctrl-d` / `ctrl-u` scroll a full page instead of half a page.
57
+ - `gv` (reselect the last visual area) and `gi` (insert where you last inserted).
58
+
59
+ ## Visual mode and other editing
60
+
61
+ - Line-wise visual (`V`), block visual (`ctrl-v`) and `o` (swap selection ends) are
62
+ missing. `vimlike` binds `V` and `ctrl-v` to other actions.
63
+ - `ctrl-x` (decrement a number) is missing; `ctrl-a` exists only in the `vim` keymap.
64
+ - `gJ` (join lines without adding a space) and named registers (`"a` etc.) are
65
+ missing.
66
+
67
+ ## Suggested approach
68
+
69
+ A small generic operator-pending layer, where an operator (`d`, `c`, `y`, `gU`, `gu`,
70
+ `g~`, `>`) waits for any motion or text object, would cover most of the case-change,
71
+ operator and text-object gaps at once instead of adding dozens of separate bindings.
@@ -0,0 +1,433 @@
1
+ # Modules page: move module toggles out of Preferences into Settings ▸ Modules
2
+
3
+ ## Context
4
+
5
+ Module toggles currently live on the **Modules** tab of Settings ▸ Preferences. They're
6
+ built by `all_settings_defs` (`gui_settings.rb`), which scans `modules/*/` and calls
7
+ `<name>_info` for each. Each toggle is just a label with a switch. The user doesn't learn
8
+ what the module does or what it needs installed, so they can enable TTS or dictation and
9
+ get only a runtime error like "TTS: need 'piper' and 'aplay' on PATH".
10
+
11
+ Goal:
12
+ 1. A separate **Settings ▸ Modules...** menu item with its own dialog. The Modules tab
13
+ is removed from Preferences.
14
+ 2. Each module shows **what it does** and **what the user has to do** to make it work
15
+ (apt/pip installs, model downloads, a running service).
16
+ 3. **Experimental modules** (Embedded Terminal, Scientific Calculator) go in their own
17
+ section, apart from the stable ones.
18
+
19
+ ## Current state (verified)
20
+
21
+ - `lib/vimamsa/gui_settings.rb`
22
+ - `all_settings_defs` returns `SETTINGS_DEFS` plus a generated `"Modules"` section
23
+ (keys `[:modules, <name>, :enabled]`, `:no_restart` taken from info).
24
+ - `SettingsDialog#activate_no_restart_modules` loads the module and calls
25
+ `<name>_init` / `<name>_disable` when a switch changes with `no_restart: true`.
26
+ - `modules/<name>/<name>_info.rb` only returns `{ name:, no_restart: }`. All 6 modules
27
+ are `no_restart: true`.
28
+ - Startup loading: `editor.rb:229-243` (stays as it is).
29
+ - `gui_menu.rb:46` `Settings.Preferences` → `:show_settings` (`key_actions.rb:33`).
30
+ - There is already a top-level **Modules** menu (`Menu#add_module_action`) that holds
31
+ module *actions* such as "Insert Calculator". It is separate from this work but has
32
+ the same name (see open question 1).
33
+ - Tests that depend on the Modules section being inside `all_settings_defs`:
34
+ - `tests/test_module_interface.rb:79-97` (3 tests)
35
+ - `tests/test_color_highlight.rb:86-91` (`test_setting_exposed`)
36
+ - `tests/test_tts.rb`, `tests/test_dictation.rb` check `_info` structure (still valid,
37
+ will be extended).
38
+
39
+ ## Design
40
+
41
+ ### 1. Extend the `<name>_info` contract
42
+
43
+ The new keys are optional, so modules without them still work:
44
+
45
+ ```ruby
46
+ def tts_info
47
+ {
48
+ name: "Text to Speech",
49
+ no_restart: true,
50
+ experimental: false,
51
+ description: "Reads the selection or current line aloud using Piper neural TTS.",
52
+ requirements: [
53
+ { text: "Piper TTS engine", cmd: "pip install piper-tts", check: proc { which("piper") } },
54
+ { text: "aplay (ALSA utils)", cmd: "sudo apt install alsa-utils", check: proc { which("aplay") } },
55
+ { text: "A Piper voice in ~/piper-voices (default en_GB-alan-medium)",
56
+ check: proc { Dir.exist?(File.expand_path(cnf.tts.data_dir! || "~/piper-voices")) } },
57
+ ],
58
+ usage: "Key bindings: … (filled in from the module's add_keys)",
59
+ }
60
+ end
61
+ ```
62
+
63
+ - `description`: one or two sentences.
64
+ - `requirements`: an array of `{ text:, cmd: (optional), check: (optional proc → bool) }`.
65
+ An empty or missing array is displayed as "No extra setup needed".
66
+ - `check` lets the dialog mark each requirement ✓ found / ✗ missing. Checks must be
67
+ cheap (`which`, `File.exist?`, at most a fast `require` probe). No network calls.
68
+ Ollama is the exception: it's reported as "not checked" rather than pinging the port
69
+ while the dialog opens.
70
+ - `experimental: true` puts the module in the Experimental section.
71
+
72
+ ### 2. Per-module content and concrete setup actions
73
+
74
+ This section is the text that goes into each `_info.rb` and onto the dialog. It also
75
+ lists the **in-app setup actions**: buttons on a module's card that do a setup step for
76
+ the user, so they don't have to look it up.
77
+
78
+ The dialog supports three kinds of action:
79
+ - **copy**: copy a shell command to the clipboard, for anything that needs `sudo` or a
80
+ long download. Nothing privileged ever runs from inside the editor.
81
+ - **run**: run a command that needs no `sudo` in the external terminal
82
+ (`exec_in_terminal`), so the user sees its progress and output. One example is
83
+ `ollama pull`.
84
+ - **config**: write a `cnf.*` value, for example a detected path.
85
+
86
+ So in `_info`, a requirement or action entry can look like
87
+ `{ text:, cmd:, kind: :copy | :run | :config, check: }`.
88
+
89
+ Ubuntu 23.04+ blocks a system-wide `pip install` (PEP 668). Python dependencies
90
+ therefore get a vimamsa-owned venv at `~/.local/share/vimamsa/venv`, and the dialog's **run**
91
+ action creates it. This affects dictation and TTS.
92
+
93
+ Exact package names and commands below are best-effort. Verify them on the clean
94
+ test VM (`$VM_NAME`) while implementing (see the last implementation step).
95
+
96
+ #### Configuration info on the module page
97
+
98
+ Each module's card also lists its **settings**, meaning the `cnf.*` keys a user can set
99
+ in `~/.vimamsa/custom.rb` (or `settings.rb`). For now that information lives only in
100
+ the comments at the top of the source files, such as `dictation.rb:24-41` and
101
+ `tts.rb:15-17`.
102
+
103
+ - New `_info` key `config:`, an array of
104
+ `{ key: "dictation.model", default: "large-v3", desc: "faster-whisper model (tiny…large-v3)" }`.
105
+ The module's own code still applies the defaults (`cnf.x! || default`). `default:`
106
+ is there for display only.
107
+ - The card has a collapsible **"Settings (custom.rb)"** section (`Gtk::Expander`,
108
+ collapsed by default). It's a small grid with one row per key: `cnf.<key>` in
109
+ monospace, then the current value (`cnf_get`, shown dim when unset, with
110
+ "(default: …)"), then the description.
111
+ - Below the grid:
112
+ - **Copy snippet** puts a ready-to-paste block on the clipboard, one
113
+ `# cnf.<key> = <default> # <desc>` line per setting.
114
+ - **Open custom.rb** reuses the existing `:edit_customrb` action and closes the
115
+ dialog.
116
+ - The values are read-only on the page. Editing them in the dialog is a possible
117
+ follow-up. Read-only avoids a second, half-complete settings editor, and custom.rb
118
+ remains the single place where these values are written.
119
+ - The header comments in each module file are kept short. They point to `_info` as the
120
+ canonical list, so the two don't drift apart.
121
+ - Test: every `cnf.<module>.*` key read in a module's `.rb` (grep for
122
+ `cnf\.<name>\.[a-z_]+`) is listed in its `config:`. This catches undocumented
123
+ settings.
124
+
125
+ Settings per module, taken from the code:
126
+
127
+ | Module | Settings (`cnf.` prefix) |
128
+ |---|---|
129
+ | dictation | `dictation.python` ("python3"), `.worker` (bundled whisper_worker.py), `.model` ("large-v3"), `.language` ("en"), `.device` ("auto"), `.compute_type` ("float16"), `.normalize` (true), `.initial_prompt` (none), `.chunk_secs` (4), `.idle_timeout` (300), `.startup_timeout` (600), `.source` ("autoaudiosrc") |
130
+ | ollama | `ollama.model` ("qwen3.5:0.8b"), `.host` ("localhost"), `.port` (11434), `.timeout` (60), `.multi_temperature` (1.2) |
131
+ | tts | `tts.voice` ("en_GB-alan-medium"), `.data_dir` ("~/piper-voices"), `.rate` (taken from the voice's .json, else 22050), plus the new `.piper` path |
132
+ | color_highlight, calculator, terminal | none apart from the enable switch |
133
+ | ack (extracted) | `default_search_extensions` (shared with the search form). Rename it to `ack.extensions`, keeping the old key as a fallback. |
134
+ | auto_format (extracted) | `auto_format.formatters`, a hash `filetype → {cmd:, mode: :stdout/:inplace, ext:, ignore_exit_code:}`. The card shows the configured formatters, and the snippet includes the rubocop example from `conf.rb:190`. |
135
+ | audio (extracted) | none today |
136
+ | lsp (extracted) | `lsp.server.<name> = {name:, command:, type:, languages:}`, `workspace_folders`, `autocomplete.lsp.enabled`, `autocomplete.lsp.debounce`. The snippet is the solargraph/ruby-lsp/clangd block from `custom_example.rb:89-99`. |
137
+
138
+ #### Stable modules
139
+
140
+ **color_highlight — Hex Color Highlight** (default: on)
141
+ - Does: paints `#RGB` / `#RRGGBB` / `#RRGGBBAA` codes in any file with their own color.
142
+ - Requires: nothing. Toggle: `C , ; h c`.
143
+
144
+ **dictation — Voice Dictation**
145
+ - Does: records from the microphone. faster-whisper transcribes the audio and the text
146
+ is inserted at the cursor. A quick draft appears while recording and the final pass
147
+ replaces it.
148
+ - Requires and checks:
149
+ - ffmpeg: `sudo apt install ffmpeg` (copy). Check: `which("ffmpeg")`.
150
+ - GStreamer mic source: `sudo apt install gstreamer1.0-plugins-good gstreamer1.0-pulseaudio`
151
+ (copy). Check: `Gst::ElementFactory.find("autoaudiosrc")`.
152
+ - faster-whisper: **run**
153
+ `python3 -m venv ~/.local/share/vimamsa/venv && ~/.local/share/vimamsa/venv/bin/pip install faster-whisper`,
154
+ then **config** `cnf.dictation.python = "~/.local/share/vimamsa/venv/bin/python"`.
155
+ Check: `<python> -c "import faster_whisper"`. Run this check only when the user
156
+ presses "Check", because it takes about 1 s.
157
+ - Notes on the card:
158
+ - The first use downloads the model (default `large-v3`, about 3 GB).
159
+ - Without an NVIDIA GPU, use a smaller model. A "CPU mode" **config** button sets
160
+ `cnf.dictation.device = "cpu"`, `compute_type = "int8"` and `model = "small"`.
161
+
162
+ **ollama — Ollama**
163
+ - Does: rewrites or improves the selected text with a local LLM. `V , o i` makes one
164
+ rewrite; `V , o N i` makes N alternatives.
165
+ - Requires and checks:
166
+ - Ollama: `curl -fsSL https://ollama.com/install.sh | sh` (copy). Check: `which("ollama")`.
167
+ - The model: **run** `ollama pull qwen3.5:0.8b`, or whatever `cnf.ollama.model` is set to.
168
+ - The server running: a "Test connection" button does a short GET of `/api/tags` on
169
+ `cnf.ollama.host:port`, with a 1 s timeout, only when pressed.
170
+
171
+ **tts — Text to Speech**
172
+ - Does: reads the selection or current line aloud using a Piper neural voice.
173
+ - Requires and checks:
174
+ - piper: **run** `python3 -m venv ~/.local/share/vimamsa/venv && ~/.local/share/vimamsa/venv/bin/pip install piper-tts`,
175
+ then **config** to point the module at `~/.local/share/vimamsa/venv/bin/piper`. This needs a new
176
+ `cnf.tts.piper` setting, because today the module looks for `piper` on PATH.
177
+ Check: the binary exists.
178
+ - aplay: `sudo apt install alsa-utils` (copy). Check: `which("aplay")`.
179
+ - A voice: **run**
180
+ `~/.local/share/vimamsa/venv/bin/python -m piper.download_voices en_GB-alan-medium --data-dir ~/piper-voices`.
181
+ Check: `<data_dir>/<voice>.onnx` exists.
182
+
183
+ #### Experimental modules
184
+
185
+ **terminal — Embedded Terminal (VTE)**
186
+ - Does: embeds an interactive shell widget inside a buffer.
187
+ - Requires: the VTE GTK4 introspection data, `sudo apt install gir1.2-vte-3.91` (copy).
188
+ The `vte4` gem is already a runtime dependency in the gemspec.
189
+ Check: `require "vte4"` inside `begin/rescue LoadError`.
190
+
191
+ **calculator — Scientific Calculator**
192
+ - Does: inserts an inline calculator widget at the cursor (Modules ▸ Insert Calculator).
193
+ ↩ inserts the result.
194
+ - Requires: nothing.
195
+
196
+ For the modules extracted in section 7 below, the entries are listed there.
197
+
198
+ During implementation, read each module's header comment and `_init` to get the exact
199
+ bindings, actions and `cnf.*` settings. Copy them into `usage:` instead of guessing.
200
+
201
+ ### 3. Shared module helpers (`gui_settings.rb`, or a new `lib/vimamsa/modules_info.rb`)
202
+
203
+ Pull the scanning code out of `all_settings_defs`:
204
+
205
+ - `module_infos` → array of `{ dir:, id: "tts", info: {...}, key: [:modules, :tts, :enabled] }`,
206
+ sorted by name, with defaults filled in (`name` from the directory name,
207
+ `no_restart: false`, `experimental: false`, `requirements: []`).
208
+ - `module_set_enabled(id, enabled, was_enabled)`: the load + `_init` / `_disable` logic
209
+ moved out of `SettingsDialog#activate_no_restart_modules`, so the new dialog can use
210
+ it (and the tests can call it directly).
211
+ - `all_settings_defs` → returns only `SETTINGS_DEFS`. It can be inlined or kept as an
212
+ alias. Keeping it is less churn for the two tests that use it for non-module keys
213
+ (`test_autocomplete.rb:194`).
214
+
215
+ If a new file is created, add `require "vimamsa/modules_info"` to `rbvma.rb`.
216
+
217
+ ### 4. New `ModulesDialog` (`lib/vimamsa/gui_modules.rb`, required in `rbvma.rb`)
218
+
219
+ - `make_modal_window("Modules")` with a vertical box inside a `Gtk::ScrolledWindow`
220
+ (6+ cards won't fit otherwise). Default size about 600×600.
221
+ - Two headings: **Modules** and **Experimental modules**. Under the experimental
222
+ heading, a short dim note: "May be unstable or incomplete."
223
+ - One card per module (`Gtk::Frame`, using the existing `margin=` monkeypatch):
224
+ - Row 1: bold name + `Gtk::Switch` aligned right (+ "(requires restart)" if
225
+ `!no_restart`).
226
+ - Description label (`wrap = true`, `xalign = 0`).
227
+ - "Requires:" list with one line per requirement: ✓/✗ marker, text, and the command
228
+ in monospace, `selectable = true` so it can be copied. Optionally a small "Copy"
229
+ button that puts `cmd` on the clipboard through the existing clipboard helper.
230
+ With no requirements: "No extra setup needed."
231
+ - `usage` line, dim, if present.
232
+ - Buttons: Cancel / Save, as in Preferences. On Save: `cnf_set` each switch, run
233
+ `save_settings_to_file`, then `module_set_enabled` for every switch that changed.
234
+ The modal style and Save behavior match Preferences.
235
+ - When a module is switched on and its checks report something missing, it's still
236
+ enabled, and a `message("TTS enabled — missing: piper")` explains what's missing.
237
+ This doesn't block anything.
238
+ - `on_submit_escape(@window, escape: …)` as in `SettingsDialog`.
239
+
240
+ ### 5. Wiring
241
+
242
+ - `key_actions.rb`: `reg_act(:show_modules, proc { show_modules_dialog }, "Show modules")`.
243
+ - `gui_menu.rb`: `add_to_menu "Settings.Modules", { :label => "Modules...", :action => :show_modules }`
244
+ directly below Preferences.
245
+ - `SettingsDialog`: remove `activate_no_restart_modules` and the `:no_restart` /
246
+ `:prev_value` code that only existed for the module tab.
247
+ - Update the comments that point to the old place: `modules/calculator/calculator.rb:3`
248
+ ("Preferences → Modules"), `modules/color_highlight/color_highlight.rb:7`, and any
249
+ others found by `grep -rn "Modules" modules lib README.md`.
250
+
251
+ ### 6. Tests
252
+
253
+ Update:
254
+ - `test_module_interface.rb`: switch the 3 `all_settings_defs` tests to `module_infos`.
255
+ Add an assertion that `all_settings_defs` no longer contains a `"Modules"` section.
256
+ - `test_color_highlight.rb#test_setting_exposed`: check `module_infos` instead.
257
+
258
+ Add (`tests/test_modules_dialog.rb`):
259
+ - Every module's info has a non-empty `:description`, and `:requirements` is an Array.
260
+ - `calculator` and `terminal` are `experimental: true`; the others are not.
261
+ - `ModulesDialog.new` builds without error and produces one switch per module, split
262
+ into the two sections.
263
+ - Toggling calculator on in the dialog and pressing Save registers `:insert_calculator`;
264
+ toggling it off unregisters it. This replaces the coverage the old
265
+ `activate_no_restart_modules` path had.
266
+ - `:show_modules` is registered and in the Settings menu.
267
+
268
+ Run the full suite in the test VM (`./run_tests_vm.sh`, VM from `$VM_NAME`), not just the touched files.
269
+
270
+ ### 7. Core features to turn into modules
271
+
272
+ I surveyed `lib/vimamsa/*` for features that call external programs, pull in an
273
+ optional gem/library, or are already behind an on/off flag. Each candidate gets a
274
+ verdict below.
275
+
276
+ **General rules for an extraction:**
277
+ - Move the code to `modules/<name>/<name>.rb` and drop its `require` from `rbvma.rb` /
278
+ `editor.rb`.
279
+ - Add `<name>_info.rb`.
280
+ - Move its `reg_act`s, bindings and menu entries into `<name>_init`, and undo them in
281
+ `<name>_disable`.
282
+ - Bindings for all three schemes (vimlike, vim, notepad) move into `_init`. The init
283
+ code checks `cnf.keybindings.scheme` if they differ.
284
+ - **Keep current behavior by default.** Features that are on today get
285
+ `cnf.modules.<name>.enabled = true` in `conf.rb`, the same way color_highlight does.
286
+ - Old flags (`cnf.audio.enabled`, `cnf.lsp.enabled`) are mapped to the new key once,
287
+ after custom.rb phase 1, so existing user configs keep working.
288
+
289
+ #### Extract (recommended)
290
+
291
+ **A. ack — Content Search (ack)**
292
+ - Code: `ack.rb` (204 lines, `FileContentSearch` + `Ack`), `:ack_search` in
293
+ `key_actions.rb:124,151` (registered twice, so one copy can go), `C , a` in
294
+ `key_bindings_vimlike.rb:336`, and the commented-out menu entry `gui_menu.rb:89`.
295
+ - Why: hard dependency on the external `ack` binary. Today, with ack missing, the search
296
+ just returns nothing. Self-contained, with one entry point.
297
+ - Default: on. Stable.
298
+ - Does: searches file contents (`C , a`) in the project directory, that is, the nearest
299
+ parent directory containing `.git` / `.vma_project`. Results are grouped by folder
300
+ and you can jump to them.
301
+ - Requires:
302
+ - `sudo apt install ack` (copy). The package is `ack` on current Ubuntu; `ack-grep` is
303
+ the old name, and README.md:59 needs fixing.
304
+ - Check: `which("ack")`.
305
+ - Tests: `tests/test_ack.rb` loads or enables the module in setup.
306
+ - Effort: small. This makes it the pilot extraction that proves out the pattern.
307
+
308
+ **B. auto_format — Auto Format**
309
+ - Code: `Buffer#auto_format` (`buffer_changetext.rb:42-88`), which already has a
310
+ `# TODO: rename ot auto-format. separate module?` comment, plus
311
+ `cnf.auto_format.formatters` (`conf.rb:190-197`), `:auto_indent_buffer`
312
+ (`key_actions.rb:208`) and `C , v`.
313
+ - Why: every formatter is an external program, and the feature is self-contained.
314
+ - Default: on. Stable.
315
+ - Does: reformats the whole buffer with the formatter set for its file type (`C , v`).
316
+ - Requires: one entry for each formatter configured in `cnf.auto_format.formatters`,
317
+ generated from the first word of its `cmd`:
318
+ - clang-format (C, C++, JavaScript): `sudo apt install clang-format` (copy).
319
+ Check: `which`.
320
+ - rufo (Ruby): `gem install rufo` (copy, no sudo needed for a user gem dir).
321
+ Check: `which`.
322
+ - `Buffer#auto_format` stays as a thin method that calls the module, or `:auto_indent_buffer`
323
+ calls a module function directly. Pick whichever keeps `tests/test_auto_format.rb`
324
+ unchanged.
325
+ - Effort: small.
326
+
327
+ **C. audio — Audio Playback**
328
+ - Code: `audio.rb` (GStreamer `Audio` class), loaded by `editor.rb:218-220` behind
329
+ `cnf.audio.enabled`. Used by `⟦audio:path⟧` links in `hyper_plain_text.rb:31` and by
330
+ the `audio` minor mode plus bindings in `key_bindings_vimlike.rb:8,412,430-438` and
331
+ `key_bindings_vim.rb:22,346-350`. The vim file's comment already calls it "the audio
332
+ module".
333
+ - Why: it's already opt-in, already described as a module, and needs GStreamer codecs.
334
+ - Default: off. Stable.
335
+ - Does: plays audio files linked from text as `⟦audio:file.mp3⟧`. Audio mode
336
+ (`C , m a`): `f`/`←` seek, `space`/`s` stop.
337
+ - Requires:
338
+ - `sudo apt install gstreamer1.0-plugins-good gstreamer1.0-libav` for mp3 and other
339
+ codecs (copy).
340
+ - Check: `Gst::ElementFactory.find("playbin")`.
341
+ - Migration: map `cnf.audio.enabled` to `cnf.modules.audio.enabled`.
342
+ - `hyper_plain_text.rb` needs a guard: `defined?(Audio)` / `respond_to?`. A hook would be
343
+ cleaner (see color_highlight's `:view_*` hooks).
344
+ - Effort: small to medium, because of the minor-mode bindings.
345
+
346
+ **D. lsp — Language Server (LSP)**
347
+ - Code:
348
+ - `langservp.rb` (564 lines) and `gui_func_panel.rb` (172).
349
+ - Startup in `editor.rb:222-227`.
350
+ - LSP calls spread through `buffer.rb`, `gui_sourceview.rb` and
351
+ `gui_sourceview_autocomplete.rb`.
352
+ - Menu entries `View.FuncPanel` / `Actions.LspRestart`.
353
+ - Setup through `cnf.lsp.server.*` in custom.rb (`custom_example.rb:89-99`).
354
+ - Why: it's the biggest optional feature, already off by default, and needs external
355
+ servers. Setup is also the hardest part for users today: they must find and uncomment
356
+ config in custom.rb.
357
+ - Default: off. Stable.
358
+ - Does: jump to definition, a symbol/function panel and completion candidates, using a
359
+ language server for each language.
360
+ - Requires, one entry per known server:
361
+ - Ruby, solargraph: `gem install solargraph` (copy). Check: `which("solargraph")`.
362
+ - Ruby, ruby-lsp, as an alternative: `gem install ruby-lsp`.
363
+ - C/C++, clangd: `sudo apt install clangd` (copy). Check: `which("clangd")`.
364
+ The card also notes that clangd needs `compile_commands.json` or
365
+ `compile_flags.txt` in the project.
366
+ - Concrete simplification, **config**: built-in default `cnf.lsp.server` presets. When a
367
+ language has no server configured, `lsp_init` uses the first one found on PATH
368
+ (solargraph, ruby-lsp, clangd). Enabling the module then just works, with no
369
+ custom.rb edit. The card shows which server was picked for each language.
370
+ - Risk: the buffer, sourceview and autocomplete code calls into LSP directly. Those call
371
+ sites need nil-safe guards or hooks first. This one is a **refactor**, not a move.
372
+ - Migration: map `cnf.lsp.enabled` to `cnf.modules.lsp.enabled`. Keep the LSP tests
373
+ (`test_lsp_*.rb`) enabling it explicitly.
374
+ - Effort: large. Do it last, as its own commit series.
375
+
376
+ #### Keep in core (not worth a module)
377
+
378
+ - **Encryption** (`encrypt.rb`): no external deps (stdlib `openssl`). It's built into the
379
+ file open/save path (`editor.rb:648,717`, `buffer.rb:2008`). If it were disabled,
380
+ encrypted files would open as unreadable data and might be saved over. It has to stay
381
+ in core.
382
+ - **Diff / git diff** (`diff_buffer.rb`): needs only `diff`/`git`, which are almost
383
+ always installed and already checked with `if_cmd_exists`. Keep it. The card text
384
+ could still list it under core features, which is optional.
385
+ - **Grep lines** (`search_replace.rb`, `Grep`): pure Ruby, core navigation. This is a
386
+ different feature from ack.
387
+ - **Run line in external terminal** (`terminal.rb#exec_in_terminal`): small. Its only
388
+ problem is the hardcoded `gnome-terminal`. Leave it in core and add a
389
+ `cnf.terminal.command` setting (out of scope here; noted as a follow-up). It must not
390
+ be mixed up with the embedded VTE `terminal` module.
391
+ - **Image display** (`gui_image.rb`), **xdg-open**, **desktop_install**: no optional
392
+ deps, or deps that are always present.
393
+ - `xclip` (`buffer_changetext.rb:104`): it belongs to a workaround that's commented out
394
+ and never called. Nothing to do.
395
+
396
+ #### Resulting module list
397
+
398
+ - **Stable:** ack (on), auto_format (on), color_highlight (on), audio, dictation, lsp,
399
+ ollama, tts.
400
+ - **Experimental:** terminal, calculator.
401
+
402
+ ## Implementation order
403
+
404
+ 1. `module_infos` + `module_set_enabled`, and remove the Modules tab from Preferences.
405
+ Update the existing tests. Suite green.
406
+ 2. Extend the 6 existing `_info.rb` files with description / requirements /
407
+ experimental / usage / config.
408
+ 3. `ModulesDialog`, menu item, action, and copy/run/config setup buttons and checks.
409
+ 4. Extract **ack** (pilot), then **auto_format**, then **audio**: one commit each, full
410
+ suite after each.
411
+ 5. Shared `~/.local/share/vimamsa/venv` setup and the `cnf.tts.piper` setting.
412
+ 6. Fix README.md "optional features" so it points to Settings ▸ Modules (and `ack`, not
413
+ `ack-grep`).
414
+ 7. On a fresh snapshot of the test VM, follow every card's steps literally. Fix any command
415
+ that's wrong.
416
+ 8. **LSP** extraction plus presets, as a separate follow-up series.
417
+
418
+ ## Open questions
419
+
420
+ 1. **Naming clash**: the top-level **Modules** menu (module actions like "Insert
421
+ Calculator") and the new Settings ▸ Modules page. Keep both as they are (proposed),
422
+ or rename the top-level menu to something like "Tools"?
423
+ 2. Should experimental modules be hidden or disabled unless the existing
424
+ `cnf.experimental` ("Enable experimental features") is on? Proposed: no. They're
425
+ always visible in their own section, and `cnf.experimental` stays as it is.
426
+ 3. Apply switches immediately (no Save button) instead of Save/Cancel? Proposed:
427
+ Save/Cancel, to match Preferences.
428
+ 4. Should the **run** setup actions (venv + pip install, `ollama pull`, voice download)
429
+ be offered at all, or should every action be copy-only? Proposed: offer them. They
430
+ need no sudo and run visibly in a terminal.
431
+ 5. Should LSP be extracted now, or is it enough to add server auto-detection presets
432
+ and leave it in core? Proposed: presets first (that's what helps users most),
433
+ extraction later.