repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

feat(neovim): give pivi help live editor view, nvim docs, and its own skill

63086f2d605740065c45e23ff3636ec2b4101023

Oliver Krylow <o.krylow@isp-insoft.de> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (18)

neovim/lua/bugabinga/pivi/AGENTS.md

Modified
55 55 `:Pi help` isolates session state only: `--no-session`, `--no-tools`, `--append-system-prompt`.
56 56 Specs assert this on both command builders; keep them.
57 57 A run started without the user's configuration proves nothing, and silently changes which providers exist.
58 -15. **Contract tests guard assumptions,** not features. They skip unless `pi` is on `PATH` and opt-in is set. When Pi changes behavior, they fail before users do.
58 +15. **Help context stays small and live.** `:Pi help` attaches only the visible region of the current window plus layout, selection, recent messages, and the last error; never whole buffers.
59 + Depth is fetched on demand: `nvim_help` for Neovim and plugin documentation, `pi-knowledge` for Pi, the `pivi` skill for pivi, `nvim_state` and `nvim_lua` for live values.
60 + Never answer a Neovim documentation question from model memory in this codebase: `nvim_help` resolves against the running version's runtime path, including plugin docs.
61 + Help is read-only by construction; keep mutating tools out of its allowlist.
63 +16. **Contract tests guard assumptions,** not features. They skip unless `pi` is on `PATH` and opt-in is set. When Pi changes behavior, they fail before users do.
60 65 ## Commands
66 71 just test-contract
74 +End-to-end proof that the companion extension answers from the live editor, when a tool changes:
76 +```
77 +nvim --headless --noplugin -u tests/minimal_init.lua --listen 127.0.0.1:6911
78 +PIVI_NVIM_ADDRESS=127.0.0.1:6911 PIVI_NVIM_CLIENT=$PWD/lua/bugabinga/pivi/extension/client.lua pi --mode rpc --no-session --thinking low --model hetzner/Qwen3.8-27B --tools nvim_help --skill lua/bugabinga/pivi/skills/pivi/SKILL.md -e lua/bugabinga/pivi/extension/index.ts
79 +```
69 81 `just drive` starts its own headless server, connects with
70 82 `vim.fn.sockconnect('tcp', address, { rpc = true })`, and drives it with
71 83 `vim.rpcrequest(channel, 'nvim_exec_lua' | 'nvim_input' | 'nvim_get_mode', ...)`.

neovim/lua/bugabinga/pivi/bridge.lua

Modified
1 1 local edit = require 'bugabinga.pivi.edit'
2 2 local context = require 'bugabinga.pivi.context'
3 3 local activity = require 'bugabinga.pivi.activity'
4 +local docs = require 'bugabinga.pivi.docs'
5 6 local failure = function( message )
6 7 return { ok = false, error = tostring( message ), }
70 71 return { ok = true, state = context.editor(), }
74 +actions.view = function()
75 + return { ok = true, view = context.visible(), }
76 +end
78 +--- Resolves help exactly as this Neovim would, plugin documentation included.
79 +actions.help = function( request )
80 + if type( request.tag ) ~= 'string' or request.tag == '' then return failure 'tag is required' end
81 + local result = docs.read( request.tag )
82 + if not result.found then
83 + return { ok = true, found = false, tag = result.tag, candidates = result.candidates, }
84 + end
85 + return {
86 + ok = true,
87 + found = true,
88 + tag = result.tag,
89 + file = result.file,
90 + path = result.path,
91 + line = result.line,
92 + text = result.text,
93 + }
94 +end
73 96 actions.lua = function( request )
74 97 if type( request.code ) ~= 'string' then return failure 'code is required' end
75 98 local chunk, problem = loadstring( request.code, 'pivi' )

neovim/lua/bugabinga/pivi/context.lua

Modified
1 1 local SURROUNDING_LINES = 40
2 +local VISIBLE_LINES = 120
3 +local MESSAGE_LINES = 20
3 5 local freeze = function( value )
4 6 if type( value ) ~= 'table' then return value end
145 +local messages = function()
146 + local ok, text = pcall( vim.api.nvim_exec2, 'messages', { output = true, } )
147 + if not ok or type( text.output ) ~= 'string' then return {} end
148 + local lines = vim.split( text.output, '\n', { plain = true, } )
149 + local first = math.max( 1, #lines - MESSAGE_LINES + 1 )
150 + return vim.list_slice( lines, first, #lines )
151 +end
153 +local window_entry = function( win, current )
154 + local bufnr = vim.api.nvim_win_get_buf( win )
155 + local name = vim.api.nvim_buf_get_name( bufnr )
156 + return {
157 + window = win,
158 + buffer = bufnr,
159 + path = name ~= '' and name or nil,
160 + filetype = vim.bo[bufnr].filetype,
161 + current = win == current,
163 +end
165 +--- Captures what the user is actually looking at right now.
166 +--- Only the visible region of the current window is read, never whole buffers,
167 +--- so an ephemeral question stays small.
168 +local visible = function()
169 + local win = vim.api.nvim_get_current_win()
170 + local bufnr = vim.api.nvim_win_get_buf( win )
172 + local view = vim.api.nvim_win_call( win, function()
173 + return { vim.fn.line 'w0', vim.fn.line 'w$', }
174 + end )
176 + local count = vim.api.nvim_buf_line_count( bufnr )
177 + local first, last = view[1], view[2]
178 + first = math.max( 1, first or 1 )
179 + last = math.min( count, math.max( first, last or first ) )
180 + if last - first + 1 > VISIBLE_LINES then last = first + VISIBLE_LINES - 1 end
182 + local windows = {}
183 + for _, other in ipairs( vim.api.nvim_tabpage_list_wins( 0 ) ) do
184 + table.insert( windows, window_entry( other, win ) )
185 + end
187 + local range = selection_range()
188 + local selected
189 + if range and vim.api.nvim_buf_is_valid( bufnr ) then
190 + local ok, text = pcall( text_between, bufnr, range )
191 + if ok then selected = text end
192 + end
194 + local name = vim.api.nvim_buf_get_name( bufnr )
196 + return {
197 + cwd = vim.uv.cwd(),
198 + mode = vim.api.nvim_get_mode().mode,
199 + buffer = bufnr,
200 + path = name ~= '' and name or nil,
201 + filetype = vim.bo[bufnr].filetype,
202 + modified = vim.bo[bufnr].modified,
203 + cursor = vim.api.nvim_win_get_cursor( win ),
204 + first_line = first,
205 + last_line = last,
206 + line_count = count,
207 + lines = vim.api.nvim_buf_get_lines( bufnr, first - 1, last, false ),
208 + selection_kind = range and range.kind or nil,
209 + selected_text = selected,
210 + windows = windows,
211 + tabpages = #vim.api.nvim_list_tabpages(),
212 + messages = messages(),
213 + error = vim.v.errmsg ~= '' and vim.v.errmsg or nil,
215 +end
217 +--- Renders the visible state as a bounded preamble for an ephemeral question.
218 +local render_visible = function( state )
219 + if not state then return '' end
221 + local lines = { '<editor-view>', }
222 + table.insert( lines, 'cwd: ' .. tostring( state.cwd ) )
223 + table.insert( lines, 'mode: ' .. tostring( state.mode ) )
224 + table.insert( lines, 'buffer: ' .. ( state.path or '[No Name]' ) ..
225 + ' (' .. ( state.filetype ~= '' and state.filetype or 'no filetype' ) .. ')' ..
226 + ( state.modified and ' unsaved' or '' ) )
227 + table.insert( lines, 'cursor: ' .. tostring( state.cursor[1] ) .. ':' .. tostring( state.cursor[2] ) )
229 + if #state.windows > 1 or state.tabpages > 1 then
230 + local described = {}
231 + for _, entry in ipairs( state.windows ) do
232 + local label = entry.path and vim.fs.basename( entry.path ) or ( entry.filetype ~= '' and entry.filetype or 'scratch' )
233 + table.insert( described, entry.current and ( '[' .. label .. ']' ) or label )
234 + end
235 + table.insert( lines, 'windows: ' .. table.concat( described, ' ' ) ..
236 + ( state.tabpages > 1 and ( ' tabs: ' .. tostring( state.tabpages ) ) or '' ) )
237 + end
239 + if state.selected_text then
240 + table.insert( lines, 'selection (' .. tostring( state.selection_kind ) .. '):' )
241 + table.insert( lines, state.selected_text )
242 + end
244 + table.insert( lines, 'on screen (lines ' .. tostring( state.first_line ) ..
245 + '-' .. tostring( state.last_line ) .. ' of ' .. tostring( state.line_count ) .. '):' )
246 + for offset, line in ipairs( state.lines ) do
247 + table.insert( lines, string.format( '%d\t%s', state.first_line + offset - 1, line ) )
248 + end
250 + if state.error then table.insert( lines, 'last error: ' .. state.error ) end
252 + local recent = {}
253 + for _, message in ipairs( state.messages ) do
254 + if message ~= '' then table.insert( recent, message ) end
255 + end
256 + if #recent > 0 then
257 + table.insert( lines, 'recent messages:' )
258 + for _, message in ipairs( recent ) do
259 + table.insert( lines, ' ' .. message )
260 + end
261 + end
263 + table.insert( lines, '</editor-view>' )
264 + table.insert( lines, '' )
265 + return table.concat( lines, '\n' )
266 +end
143 268 return {
269 + visible_lines = VISIBLE_LINES,
144 270 snapshot = snapshot,
145 271 render = render,
272 + visible = visible,
273 + render_visible = render_visible,
146 274 editor = editor,
147 275 selection_range = selection_range,

neovim/lua/bugabinga/pivi/docs.lua

Added
new file mode 100644
1 +local MAX_LINES = 80
2 +local MAX_CANDIDATES = 24
3 +local SEPARATOR = '^=====+'
5 +local tag_files = function()
6 + return vim.api.nvim_get_runtime_file( 'doc/tags', true )
7 +end
9 +--- Resolves a help tag against the tag files of the whole runtime path,
10 +--- so plugin documentation answers exactly like `:help` does here.
11 +--- @param tag string
12 +--- @return table? location file and tag
13 +local locate = function( tag )
14 + vim.validate( 'tag', tag, 'string' )
15 + for _, tags_path in ipairs( tag_files() ) do
16 + local directory = vim.fs.dirname( tags_path )
17 + local ok, lines = pcall( vim.fn.readfile, tags_path )
18 + if ok then
19 + for _, line in ipairs( lines ) do
20 + local found, file = line:match '^(%S+)\t(%S+)\t'
21 + if found == tag then
22 + return { tag = found, path = vim.fs.normalize( directory .. '/' .. file ), }
23 + end
24 + end
25 + end
26 + end
27 + return nil
28 +end
30 +local candidates = function( prefix )
31 + local ok, found = pcall( vim.fn.getcompletion, prefix, 'help' )
32 + if not ok then return {} end
33 + return vim.list_slice( found, 1, math.min( #found, MAX_CANDIDATES ) )
34 +end
36 +local section = function( lines, first )
37 + local collected = {}
38 + for index = first, math.min( #lines, first + MAX_LINES - 1 ) do
39 + local line = lines[index]
40 + if index > first + 4 and line:match( SEPARATOR ) then break end
41 + table.insert( collected, line )
42 + end
43 + while #collected > 0 and collected[#collected] == '' do
44 + table.remove( collected )
45 + end
46 + return collected
47 +end
49 +--- Reads the help text for a tag.
50 +--- @param tag string
51 +--- @return table result found flag, text, source file, or candidate tags
52 +local read = function( tag )
53 + vim.validate( 'tag', tag, 'string' )
55 + local location = locate( tag )
56 + if not location then
57 + return { found = false, tag = tag, candidates = candidates( tag ), }
58 + end
60 + local ok, lines = pcall( vim.fn.readfile, location.path )
61 + if not ok then
62 + return { found = false, tag = tag, candidates = candidates( tag ), }
63 + end
65 + local needle = '*' .. tag .. '*'
66 + local first
67 + for index, line in ipairs( lines ) do
68 + if line:find( needle, 1, true ) then
69 + first = index
70 + break
71 + end
72 + end
73 + if not first then first = 1 end
75 + return {
76 + found = true,
77 + tag = tag,
78 + path = location.path,
79 + file = vim.fs.basename( location.path ),
80 + line = first,
81 + text = table.concat( section( lines, first ), '\n' ),
82 + }
83 +end
85 +return {
86 + max_lines = MAX_LINES,
87 + locate = locate,
88 + candidates = candidates,
89 + read = read,

neovim/lua/bugabinga/pivi/extension/index.ts

Modified
30 30 content?: string;
31 31 source?: string;
32 32 state?: unknown;
33 + view?: unknown;
33 34 result?: string;
34 35 count?: number;
35 36 persisted?: boolean;
36 37 joined?: boolean;
38 + found?: boolean;
39 + tag?: string;
40 + file?: string;
41 + line?: number;
42 + text?: string;
43 + candidates?: string[];
39 46 const here = dirname(fileURLToPath(import.meta.url));
123 130 parameters: Type.Object({}),
124 131 async execute() {
125 132 const answer = await bridge({ action: "state" });
133 + // The visible view is attached to help questions already; this is the
134 + // wider ambient state a model asks for explicitly.
126 135 if (!answer.ok) {
127 136 return {
128 137 content: [{ type: "text" as const, text: `Neovim unavailable: ${answer.error}` }],
175 + pi.registerTool({
176 + name: "nvim_help",
177 + label: "Neovim help",
178 + description:
179 + "Read Neovim documentation for a help tag, resolved against this machine's runtime path, so the answer matches this Neovim version and the installed plugins. Equivalent to typing :help {tag}.",
180 + promptSnippet: "Read Neovim documentation for a help tag",
181 + promptGuidelines: [
182 + "Use nvim_help instead of recalling Neovim or plugin documentation; it reflects the running version.",
183 + "When nvim_help reports no match, pick one of the returned candidate tags and call it again.",
184 + ],
185 + parameters: Type.Object({
186 + tag: Type.String({ description: "Help tag, exactly as typed after :help" }),
187 + }),
188 + async execute(_id, params: { tag: string }) {
189 + const answer = await bridge({ action: "help", tag: params.tag });
190 + if (!answer.ok) {
191 + return {
192 + content: [{ type: "text" as const, text: `Help unavailable: ${answer.error}` }],
193 + details: { error: true },
194 + };
196 + if (!answer.found) {
197 + const candidates = answer.candidates ?? [];
198 + const hint = candidates.length > 0 ? `\nCandidates: ${candidates.join(", ")}` : "";
199 + return {
200 + content: [{ type: "text" as const, text: `No help tag "${params.tag}".${hint}` }],
201 + details: { found: false, candidates },
202 + };
204 + return {
205 + content: [
206 + { type: "text" as const, text: `${answer.file}:${answer.line}\n\n${answer.text ?? ""}` },
207 + ],
208 + details: { found: true, tag: answer.tag, file: answer.file, line: answer.line },
209 + };
210 + },
211 + });
166 213 pi.registerTool({
167 214 name: "nvim_findings",
168 215 label: "Neovim findings",

neovim/lua/bugabinga/pivi/help.lua

Modified
1 1 local rpc = require 'bugabinga.pivi.rpc'
2 2 local transcript = require 'bugabinga.pivi.transcript'
3 +local context = require 'bugabinga.pivi.context'
4 +local runtime = require 'bugabinga.pivi.runtime'
4 6 local BUFFER_NAME = 'help'
8 +--- Read-only tools. A help run answers about the editor; it never changes it.
9 +local TOOLS = 'read,grep,find,ls,nvim_help,nvim_state,nvim_lua'
6 11 local ORIENTATION = table.concat( {
7 - 'You answer one short question about Neovim or about pivi, the native Neovim integration for Pi.',
8 - 'pivi runs Pi as a JSONL RPC child process and presents sessions, edits, and findings through native Neovim surfaces.',
9 - 'Answer directly and briefly. Do not modify files.',
12 + 'You answer one short question about Neovim, about pivi, or about Pi itself.',
13 + 'The question carries what the user currently sees in Neovim.',
14 + 'Use nvim_help for Neovim and plugin documentation instead of recalling it.',
15 + 'Answer directly and briefly, and change nothing.',
10 16 }, ' ' )
12 18 local executable = function()
16 22 local build_command = function( options )
23 + options = options or {}
17 24 local command = {
18 25 executable(), '--mode', 'rpc',
19 26 '--no-session',
20 - '--no-tools',
27 + '--tools', TOOLS,
21 28 '--append-system-prompt', ORIENTATION,
31 + local extension = options.extension ~= false and runtime.extension_path() or nil
32 + if extension then
33 + table.insert( command, '-e' )
34 + table.insert( command, extension )
35 + end
37 + local skill = options.skill ~= false and runtime.skill_path() or nil
38 + if skill then
39 + table.insert( command, '--skill' )
40 + table.insert( command, skill )
41 + end
23 43 if options.model then
24 44 table.insert( command, '--model' )
25 45 table.insert( command, options.model )
30 50 return command
53 +--- Builds the question sent to the ephemeral run.
54 +--- The preamble describes the visible editor, not the whole project.
55 +local compose = function( question, options )
56 + if options and options.view == false then return question end
57 + local ok, view = pcall( context.visible )
58 + if not ok or not view then return question end
59 + return context.render_visible( view ) .. question
60 +end
33 62 --- Answers a question in an independent ephemeral run.
34 63 --- It owns its own process, buffer, and lifetime, so no working session's
35 64 --- history, queue, or status is touched.
36 65 --- @param question string
37 ---- @param options table? model, arguments, spawn, on_done
66 +--- @param options table? model, arguments, spawn, view, on_done
38 67 local ask = function( question, options )
39 68 vim.validate( 'question', question, 'string' )
40 69 options = options or {}
49 78 run.client = rpc.start {
50 79 command = build_command( options ),
51 80 cwd = options.cwd or vim.uv.cwd(),
81 + env = options.env or runtime.bridge_environment(),
52 82 spawn = options.spawn,
53 83 on_event = function( event )
54 84 if event.type == 'message_update' then
57 87 run.answer = run.answer .. ( delta.delta or '' )
58 88 transcript.append( bufnr, delta.delta or '' )
90 + elseif event.type == 'tool_execution_start' then
91 + transcript.line( bufnr, '' )
92 + transcript.line( bufnr, ' · ' .. tostring( event.toolName ) )
60 93 elseif event.type == 'message_end' and event.message and event.message.errorMessage then
61 94 transcript.line( bufnr, '! ' .. tostring( event.message.errorMessage ) )
62 95 elseif event.type == 'agent_settled' then
73 - run.client.request( { type = 'prompt', message = question, }, function( response )
106 + run.client.request( { type = 'prompt', message = compose( question, options ), }, function( response )
74 107 if response.success then return end
75 108 transcript.line( bufnr, '! ' .. tostring( response.error or 'help run rejected' ) )
76 109 run.done = true
85 118 return {
86 119 buffer_name = BUFFER_NAME,
120 + tools = TOOLS,
87 121 orientation = ORIENTATION,
88 122 build_command = build_command,
123 + compose = compose,
89 124 ask = ask,

neovim/lua/bugabinga/pivi/init.lua

Modified
10 10 local dialog = require 'bugabinga.pivi.dialog'
11 11 local context = require 'bugabinga.pivi.context'
12 12 local bridge = require 'bugabinga.pivi.bridge'
13 +local docs = require 'bugabinga.pivi.docs'
14 +local runtime = require 'bugabinga.pivi.runtime'
14 16 --- Reads cached status only. Safe to call from a statusline.
15 17 local summary = function( name ) return publish.summary( name ) end
35 37 dialog = dialog,
36 38 context = context,
37 39 bridge = bridge,
40 + docs = docs,
41 + runtime = runtime,
38 42 summary = summary,
39 43 reset = reset,

neovim/lua/bugabinga/pivi/runtime.lua

Added
new file mode 100644
1 +--- Locates the assets pivi ships and the address a child needs to reach back.
2 +--- Everything here is additive: pivi adds its companion extension and its skill
3 +--- to the user's own Pi, and never removes what the user configured.
5 +local runtime_file = function( relative )
6 + local found = vim.api.nvim_get_runtime_file( relative, false )[1]
7 + if found then return vim.fs.normalize( found ) end
8 + return nil
9 +end
11 +local extension_path = function()
12 + return runtime_file 'lua/bugabinga/pivi/extension/index.ts'
13 +end
15 +local client_path = function()
16 + return runtime_file 'lua/bugabinga/pivi/extension/client.lua'
17 +end
19 +local skill_path = function()
20 + return runtime_file 'lua/bugabinga/pivi/skills/pivi/SKILL.md'
21 +end
23 +--- Environment the companion extension needs to reach this Neovim instance.
24 +local bridge_environment = function()
25 + local address = vim.v.servername
26 + if address == nil or address == '' then return nil end
27 + return {
28 + PIVI_NVIM_ADDRESS = address,
29 + PIVI_NVIM_EXE = vim.v.progpath,
30 + PIVI_NVIM_CLIENT = client_path(),
31 + }
32 +end
34 +return {
35 + file = runtime_file,
36 + extension_path = extension_path,
37 + client_path = client_path,
38 + skill_path = skill_path,
39 + bridge_environment = bridge_environment,

neovim/lua/bugabinga/pivi/session.lua

Modified
9 9 local activity = require 'bugabinga.pivi.activity'
10 10 local follow = require 'bugabinga.pivi.follow'
11 11 local edit = require 'bugabinga.pivi.edit'
12 +local runtime = require 'bugabinga.pivi.runtime'
13 14 local registry = {}
14 15 local counter = 0
17 18 return vim.g.pivi_executable or 'pi'
20 -local runtime_file = function( relative )
21 - local found = vim.api.nvim_get_runtime_file( relative, false )[1]
22 - if found then return vim.fs.normalize( found ) end
23 - return nil
24 -end
26 -local extension_path = function()
27 - return runtime_file 'lua/bugabinga/pivi/extension/index.ts'
28 -end
30 ---- Environment the companion extension needs to reach this Neovim instance.
31 -local bridge_environment = function()
32 - local address = vim.v.servername
33 - if address == nil or address == '' then return nil end
34 - return {
35 - PIVI_NVIM_ADDRESS = address,
36 - PIVI_NVIM_EXE = vim.v.progpath,
37 - PIVI_NVIM_CLIENT = runtime_file 'lua/bugabinga/pivi/extension/client.lua',
38 - }
39 -end
41 21 local build_command = function( options )
42 22 options = options or {}
43 23 local command = { executable(), '--mode', 'rpc', }
44 - local extension = options.extension ~= false and extension_path() or nil
25 + local extension = options.extension ~= false and runtime.extension_path() or nil
45 26 if extension then
46 27 table.insert( command, '-e' )
47 28 table.insert( command, extension )
31 + local skill = options.skill ~= false and runtime.skill_path() or nil
32 + if skill then
33 + table.insert( command, '--skill' )
34 + table.insert( command, skill )
35 + end
49 36 if options.model then
50 37 table.insert( command, '--model' )
51 38 table.insert( command, options.model )
182 169 name = options.name,
183 170 arguments = options.arguments,
184 171 extension = options.extension,
172 + skill = options.skill,
186 174 cwd = cwd,
187 - env = options.env or bridge_environment(),
175 + env = options.env or runtime.bridge_environment(),
188 176 spawn = options.spawn,
189 177 on_event = function( event ) handle_event( self, event ) end,
190 178 on_stderr = function( data ) self.last_stderr = data end,

neovim/lua/bugabinga/pivi/skills/pivi/SKILL.md

Added
new file mode 100644
1 +---
2 +name: pivi
3 +description: "Use when a question concerns pivi, the running Neovim instance, Neovim behaviour or configuration, or why the editor looks or behaves the way it does. Also use when answering from inside a pivi session about the editor rather than the project."
4 +---
6 +# pivi
8 +pivi runs you inside Neovim instead of a terminal interface.
9 +You are a normal Pi process, started as a JSONL RPC child of a live Neovim.
10 +The user's own Pi configuration is loaded: providers, extensions, skills, prompt templates, and context files.
12 +## Where answers come from
14 +| Question is about | Do this |
15 +| --- | --- |
16 +| Neovim behaviour, options, functions, or a plugin's documentation | call `nvim_help` with the tag, exactly as `:help {tag}` would be typed |
17 +| What the user currently sees, has open, selected, or unsaved | the editor view is already attached to the question; call `nvim_state` only for detail beyond it |
18 +| Live editor values, buffers, windows, diagnostics, lists | call `nvim_lua` and return a value |
19 +| pivi itself | this skill |
20 +| Pi itself: models, extensions, sessions, settings, keybindings | the `pi-knowledge` skill and Pi's installed documentation |
21 +| The project and its code | ordinary file tools |
23 +Never answer a Neovim documentation question from memory when `nvim_help` can answer it.
24 +The tag resolves against this machine's runtime path, so plugin documentation and this exact Neovim version are covered.
25 +When the tag misses, the result carries candidate tags; pick one and try again rather than guessing prose.
27 +## What pivi is
29 +- A Pi session is an explicit task identity with persistent history and a working directory. Buffers and tabs never own it.
30 +- Loaded buffers, including unsaved ones, are authoritative. Reads see buffer content, not stale disk content.
31 +- Agent edits land in the buffer, stay undoable as one change, and are made visible to later filesystem work.
32 +- Activity is shown with pivi's own extmarks, signs, diagnostics, quickfix and location lists, never in another namespace.
33 +- Streaming edit intent may appear as ghost text; it never mutates a buffer before arguments are complete.
34 +- Follow mode is optional. It tracks located events in a dedicated window or tab and never steals the working window.
35 +- State is published through a native variable and `User` events; consumers read the cache and never trigger RPC.
37 +## Surfaces the user has
39 +| Command | Effect |
40 +| --- | --- |
41 +| `:Pi ask {text}` | submit to the active session, creating one when needed |
42 +| `:Pi steer {text}` / `:Pi follow-up {text}` | deliver during an active run |
43 +| `:Pi help {question}` | this ephemeral run: no persisted session, no working-session history, queue, or status touched |
44 +| `:Pi command [name]` | run a Pi slash command; `/` at the first character of a pivi input buffer opens the picker |
45 +| `:Pi prompt` | open a prompt buffer; `<c-s>` submits |
46 +| `:Pi start` / `stop` / `sessions` / `show` | session lifetime and presentation |
47 +| `:Pi abort` / `queue` / `clear` | run and queue control |
48 +| `:Pi follow [window\|tab\|current]` | toggle follow mode |
50 +`<Plug>(pivi-show)`, `<Plug>(pivi-prompt)`, `<Plug>(pivi-abort)`, and `<Plug>(pivi-follow)` exist; pivi sets no global mappings.
52 +## Answering
54 +Be short and concrete.
55 +Name the exact command, option, or help tag the user should use.
56 +Prefer one verified fact from `nvim_help` over three remembered ones.
57 +In a help run, do not modify anything: only read-only tools are available, and the question is meant to be cheap.

neovim/tests/bugabinga/pivi/bridge_spec.lua

Modified
119 119 assert.is_true( #answer.state.windows > 0 )
122 + it( 'answers a help tag from this neovim', function()
123 + local answer = bridge.handle { action = 'help', tag = 'quickfix', }
125 + assert.is_true( answer.ok )
126 + assert.is_true( answer.found )
127 + assert.equal( 'quickfix.txt', answer.file )
128 + assert.is_true( answer.text:find( 'quickfix', 1, true ) ~= nil )
129 + end )
131 + it( 'offers candidates for an unknown help tag', function()
132 + local answer = bridge.handle { action = 'help', tag = 'quickf', }
134 + assert.is_true( answer.ok )
135 + assert.is_false( answer.found )
136 + assert.is_true( #answer.candidates > 0 )
137 + end )
139 + it( 'refuses a help request without a tag', function()
140 + assert.is_false( bridge.handle( { action = 'help', } ).ok )
141 + end )
143 + it( 'reports what the user currently sees', function()
144 + local path = temp_file { 'visible one', 'visible two', }
145 + open( path )
147 + local answer = bridge.handle { action = 'view', }
149 + assert.is_true( answer.ok )
150 + assert.equal( 2, answer.view.line_count )
151 + assert.is_true( vim.list_contains( answer.view.lines, 'visible one' ) )
152 + end )
122 154 it( 'executes arbitrary lua and returns the inspected result', function()
123 155 local answer = bridge.handle { action = 'lua', code = 'return 1 + 1', }
124 156 assert.is_true( answer.ok )

neovim/tests/bugabinga/pivi/command_spec.lua

Modified
54 54 it( 'keeps ordinary search behavior away from the first character', function()
55 55 local channel = fake.new()
56 - local current = session.create { spawn = channel.spawn, name = 'spec', extension = false, env = {}, }
56 + local current = session.create { spawn = channel.spawn, name = 'spec', extension = false, skill = false, env = {}, }
57 57 local bufnr = command.open_prompt( current )
59 59 vim.api.nvim_buf_set_lines( bufnr, 0, -1, false, { 'hello', } )
100 100 describe( 'slash commands', function()
101 101 it( 'runs a named pi command through the session', function()
102 102 local channel = fake.new()
103 - session.create { spawn = channel.spawn, name = 'spec', extension = false, env = {}, }
103 + session.create { spawn = channel.spawn, name = 'spec', extension = false, skill = false, env = {}, }
105 105 command.subcommands.command 'compact focus on edits'
115 115 it( 'offers only the commands pi reports for this session', function()
116 116 local channel = fake.new()
117 - local current = session.create { spawn = channel.spawn, name = 'spec', extension = false, env = {}, }
117 + local current = session.create { spawn = channel.spawn, name = 'spec', extension = false, skill = false, env = {}, }
119 119 local offered
120 120 vim.ui.select = function( items, _, on_choice )
150 150 it( 'reports when pi offers no commands', function()
151 151 local channel = fake.new()
152 - session.create { spawn = channel.spawn, name = 'spec', extension = false, env = {}, }
152 + session.create { spawn = channel.spawn, name = 'spec', extension = false, skill = false, env = {}, }
154 154 command.subcommands.command ''

neovim/tests/bugabinga/pivi/context_spec.lua

Modified
82 82 assert.is_nil( context.snapshot { bufnr = bufnr, } )
83 83 end )
85 + describe( 'visible view', function()
86 + it( 'captures only the region the user can see', function()
87 + local many = {}
88 + for index = 1, 500 do many[index] = 'line ' .. index end
89 + scratch( many )
90 + vim.api.nvim_win_set_cursor( 0, { 250, 0, } )
91 + vim.cmd 'normal! zz'
93 + local view = context.visible()
95 + assert.is_true( view.first_line >= 1 )
96 + assert.is_true( view.last_line <= 500 )
97 + assert.equal( 500, view.line_count )
98 + assert.equal( view.last_line - view.first_line + 1, #view.lines )
99 + assert.is_true( #view.lines < 500 )
100 + assert.is_true( #view.lines <= context.visible_lines )
101 + end )
103 + it( 'describes the current buffer, cursor, and mode', function()
104 + local bufnr = scratch { 'alpha', 'beta', }
105 + vim.api.nvim_win_set_cursor( 0, { 2, 1, } )
107 + local view = context.visible()
109 + assert.equal( bufnr, view.buffer )
110 + assert.equal( 2, view.cursor[1] )
111 + assert.is_true( view.modified )
112 + assert.is_string( view.mode )
113 + assert.is_string( view.cwd )
114 + end )
116 + it( 'lists the windows of the current tabpage', function()
117 + scratch { 'one', }
118 + vim.cmd 'vsplit'
119 + local view = context.visible()
120 + vim.cmd 'only'
122 + assert.is_true( #view.windows >= 2 )
123 + local current = 0
124 + for _, entry in ipairs( view.windows ) do
125 + if entry.current then current = current + 1 end
126 + end
127 + assert.equal( 1, current )
128 + end )
130 + it( 'renders a bounded numbered preamble', function()
131 + scratch { 'alpha', 'beta', }
132 + local rendered = context.render_visible( context.visible() )
134 + assert.is_true( rendered:find( '<editor-view>', 1, true ) == 1 )
135 + assert.is_true( rendered:find( 'on screen (lines', 1, true ) ~= nil )
136 + assert.is_true( rendered:find( '1\talpha', 1, true ) ~= nil )
137 + assert.is_true( rendered:find( '</editor-view>', 1, true ) ~= nil )
138 + end )
140 + it( 'renders nothing without a view', function()
141 + assert.equal( '', context.render_visible( nil ) )
142 + end )
144 + it( 'carries recent messages and the last error', function()
145 + vim.v.errmsg = 'E42: something broke'
146 + vim.api.nvim_echo( { { 'a distinctive notice', }, }, true, {} )
147 + scratch { 'x', }
149 + local rendered = context.render_visible( context.visible() )
151 + assert.is_true( rendered:find( 'E42: something broke', 1, true ) ~= nil )
152 + assert.is_true( rendered:find( 'a distinctive notice', 1, true ) ~= nil )
153 + vim.v.errmsg = ''
154 + end )
155 + end )
85 157 it( 'reports ambient editor state on demand', function()
86 158 local bufnr = scratch { 'ambient', }
87 159 local state = context.editor()

neovim/tests/bugabinga/pivi/docs_spec.lua

Added
new file mode 100644
1 +---@diagnostic disable: duplicate-set-field, need-check-nil, param-type-mismatch, assign-type-mismatch
2 +local docs = require 'bugabinga.pivi.docs'
4 +describe( 'pivi docs', function()
5 + it( 'locates a core help tag in the runtime path', function()
6 + local location = docs.locate 'quickfix'
7 + assert.is_table( location )
8 + assert.equal( 'quickfix', location.tag )
9 + assert.is_true( location.path:find( 'quickfix.txt', 1, true ) ~= nil )
10 + end )
12 + it( 'reads the documentation of the running neovim', function()
13 + local result = docs.read 'quickfix'
15 + assert.is_true( result.found )
16 + assert.equal( 'quickfix.txt', result.file )
17 + assert.is_number( result.line )
18 + assert.is_true( #result.text > 0 )
19 + assert.is_true( result.text:find( '*quickfix*', 1, true ) ~= nil )
20 + end )
22 + it( 'resolves a tag that only this version documents', function()
23 + local result = docs.read 'vim.diagnostic.set()'
24 + assert.is_true( result.found )
25 + assert.is_true( result.text:find( 'diagnostic', 1, true ) ~= nil )
26 + end )
28 + it( 'bounds the returned section', function()
29 + local result = docs.read 'quickfix'
30 + local lines = vim.split( result.text, '\n', { plain = true, } )
31 + assert.is_true( #lines <= docs.max_lines )
32 + end )
34 + it( 'offers candidates instead of failing on a missing tag', function()
35 + local result = docs.read 'quickf'
37 + assert.is_false( result.found )
38 + assert.is_true( #result.candidates > 0 )
39 + assert.is_true( vim.list_contains( result.candidates, 'quickfix' ) )
40 + end )
42 + it( 'returns no candidates for nonsense', function()
43 + local result = docs.read 'zzz-not-a-help-tag-zzz'
44 + assert.is_false( result.found )
45 + assert.same( {}, result.candidates )
46 + end )
47 +end )

neovim/tests/bugabinga/pivi/help_spec.lua

Modified
14 14 fake.close_extra_windows()
15 15 end )
17 - it( 'runs without persisting a session and without tools', function()
17 + it( 'runs without persisting a session', function()
18 18 local channel = fake.new()
19 19 help.ask( 'what is a quickfix list', { spawn = channel.spawn, } )
21 21 assert.is_true( vim.list_contains( channel.command, '--no-session' ) )
22 - assert.is_true( vim.list_contains( channel.command, '--no-tools' ) )
23 22 assert.is_true( vim.list_contains( channel.command, '--append-system-prompt' ) )
23 + assert.is_false( vim.list_contains( channel.command, '--no-tools' ) )
24 + end )
26 + it( 'offers only read-only tools', function()
27 + local command = help.build_command {}
28 + local index = vim.fn.index( command, '--tools' ) + 1
29 + assert.is_true( index > 0 )
31 + local allowed = vim.split( command[index + 1], ',', { plain = true, } )
32 + assert.is_true( vim.list_contains( allowed, 'nvim_help' ) )
33 + assert.is_true( vim.list_contains( allowed, 'read' ) )
35 + for _, forbidden in ipairs { 'write', 'edit', 'bash', 'powershell', } do
36 + assert.is_false( vim.list_contains( allowed, forbidden ) )
37 + end
38 + end )
40 + it( 'carries the pivi skill', function()
41 + local command = help.build_command {}
42 + local index = vim.fn.index( command, '--skill' ) + 1
44 + assert.is_true( index > 0 )
45 + assert.is_true( command[index + 1]:find( 'SKILL.md', 1, true ) ~= nil )
46 + assert.is_true( command[index + 1]:find( 'pivi', 1, true ) ~= nil )
47 + end )
49 + it( 'attaches what the user currently sees to the question', function()
50 + vim.cmd 'enew'
51 + local bufnr = vim.api.nvim_get_current_buf()
52 + vim.api.nvim_buf_set_lines( bufnr, 0, -1, false, { 'a distinctive visible line', } )
54 + local channel = fake.new()
55 + help.ask( 'why does this look wrong', { spawn = channel.spawn, } )
57 + local sent = channel.commands[1].message
58 + assert.is_true( sent:find( '<editor-view>', 1, true ) ~= nil )
59 + assert.is_true( sent:find( 'a distinctive visible line', 1, true ) ~= nil )
60 + assert.is_true( sent:find( 'why does this look wrong', 1, true ) ~= nil )
61 + end )
63 + it( 'can ask without any view', function()
64 + local channel = fake.new()
65 + help.ask( 'plain question', { spawn = channel.spawn, view = false, } )
66 + assert.equal( 'plain question', channel.commands[1].message )
24 67 end )
26 69 it( 'still loads the user\'s own pi configuration', function()
65 108 spawn = work.spawn,
66 109 name = 'work',
67 110 extension = false,
111 + skill = false,
68 112 env = {},
70 114 working.submit( 'long task', { capture = false, } )
93 137 it( 'reports its own failure without disturbing a working session', function()
94 138 local work = fake.new()
95 - local working = session.create { spawn = work.spawn, name = 'work', extension = false, env = {}, }
139 + local working = session.create { spawn = work.spawn, name = 'work', extension = false, skill = false, env = {}, }
97 141 local channel = fake.new()
98 142 local run = help.ask( 'anything', { spawn = channel.spawn, } )

neovim/tests/bugabinga/pivi/session_spec.lua

Modified
13 13 options.spawn = channel.spawn
14 14 options.name = options.name or 'spec'
15 15 options.extension = false
16 + options.skill = false
16 17 options.env = {}
17 18 return session.create( options )
73 74 assert.is_false( vim.list_contains( built, '--no-tools' ) )
74 75 end )
76 - it( 'adds only its companion extension to the user\'s pi', function()
77 - local plain = session.build_command { extension = false, }
77 + it( 'adds only its companion extension and its skill to the user\'s pi', function()
78 + local plain = session.build_command { extension = false, skill = false, }
78 79 assert.same( { 'pi', '--mode', 'rpc', }, plain )
80 81 local built = session.build_command {}
81 - local extra = {}
82 - for index = 4, #built do table.insert( extra, built[index] ) end
84 - if #extra > 0 then
85 - assert.equal( '-e', extra[1] )
86 - assert.is_true( extra[2]:find( 'pivi', 1, true ) ~= nil )
87 - assert.equal( 2, #extra )
82 + for index = 4, #built, 2 do
83 + local flag = built[index]
84 + assert.is_true( flag == '-e' or flag == '--skill' )
85 + assert.is_true( built[index + 1]:find( 'pivi', 1, true ) ~= nil )
89 87 end )
89 + it( 'teaches a working session about pivi through its skill', function()
90 + local built = session.build_command {}
91 + local index = vim.fn.index( built, '--skill' ) + 1
92 + assert.is_true( index > 0 )
93 + assert.is_true( built[index + 1]:find( 'SKILL.md', 1, true ) ~= nil )
94 + end )
91 96 it( 'sends an idle submission as a plain prompt', function()
92 97 local channel = fake.new()
93 98 local current = create( channel )

neovim/tests/contract/pi_rpc_spec.lua

Modified
10 10 local jsonl = require 'bugabinga.pivi.jsonl'
11 11 local rpc = require 'bugabinga.pivi.rpc'
12 +local help = require 'bugabinga.pivi.help'
13 +local runtime = require 'bugabinga.pivi.runtime'
13 15 local enabled = vim.env.PIVI_CONTRACT == '1' and vim.fn.executable 'pi' == 1
15 -local ask = function( commands, predicate )
17 +local ask = function( commands, predicate, command_line )
16 18 local frames = {}
17 19 local client = rpc.start {
18 - command = { 'pi', '--mode', 'rpc', '--no-session', },
20 + command = command_line or { 'pi', '--mode', 'rpc', '--no-session', },
19 21 cwd = vim.uv.cwd(),
20 22 on_event = function( frame ) table.insert( frames, frame ) end,
21 23 on_response = function( frame ) table.insert( frames, frame ) end,
97 99 assert.is_true( next( sources ) ~= nil )
102 + it( 'accepts the flags a help run uses and loads the pivi skill', function()
103 + local frames = ask(
104 + { { type = 'get_commands', }, },
105 + function( seen ) return response_for( seen, 'get_commands' ) ~= nil end,
106 + help.build_command {}
109 + local answer = response_for( frames, 'get_commands' )
110 + assert.is_true( answer.success )
112 + local names = {}
113 + for _, entry in ipairs( answer.data.commands ) do
114 + names[entry.name] = true
115 + end
116 + assert.is_true( names['skill:pivi'] )
118 + for _, frame in ipairs( frames ) do
119 + assert.is_not.equal( 'extension_error', frame.type )
120 + end
121 + end )
123 + it( 'loads the companion extension without error', function()
124 + assert.is_string( runtime.extension_path() )
125 + assert.is_string( runtime.skill_path() )
126 + end )
100 128 it( 'frames every record as strict line feed delimited JSON', function()
101 129 local frames = ask( { { type = 'get_state', }, }, function( seen )
102 130 return response_for( seen, 'get_state' ) ~= nil

neovim/tests/drive/run.lua

Modified
131 131 expect( summary.running == 'pi:run', 'the cached statusline is wrong: ' .. tostring( summary.running ) )
134 +scenario( 'the companion client reaches the running neovim', function()
135 + local directory = vim.fn.tempname()
136 + vim.fn.mkdir( directory, 'p' )
137 + local request = directory .. '/request.json'
138 + local response = directory .. '/response.json'
140 + vim.fn.writefile( { vim.json.encode { action = 'help', tag = 'quickfix', }, }, request )
142 + local client = vim.system( {
143 + vim.v.progpath,
144 + '--headless', '--clean',
145 + '-l', 'lua/bugabinga/pivi/extension/client.lua',
146 + ADDRESS, request, response,
147 + }, { stdout = false, stderr = false, } ):wait( 30000 )
149 + expect( client.code == 0, 'the client exited with ' .. tostring( client.code ) )
151 + local answer = vim.json.decode( table.concat( vim.fn.readfile( response ), '\n' ) )
152 + expect( answer.ok == true, 'the bridge refused: ' .. tostring( answer.error ) )
153 + expect( answer.found == true, 'the help tag did not resolve' )
154 + expect( answer.file == 'quickfix.txt', 'unexpected help file: ' .. tostring( answer.file ) )
155 +end )
157 +scenario( 'the companion client reports an unreachable neovim', function()
158 + local directory = vim.fn.tempname()
159 + vim.fn.mkdir( directory, 'p' )
160 + local request = directory .. '/request.json'
161 + local response = directory .. '/response.json'
162 + vim.fn.writefile( { vim.json.encode { action = 'state', }, }, request )
164 + vim.system( {
165 + vim.v.progpath,
166 + '--headless', '--clean',
167 + '-l', 'lua/bugabinga/pivi/extension/client.lua',
168 + '127.0.0.1:6', request, response,
169 + }, { stdout = false, stderr = false, } ):wait( 30000 )
171 + local answer = vim.json.decode( table.concat( vim.fn.readfile( response ), '\n' ) )
172 + expect( answer.ok == false, 'an unreachable neovim was reported as success' )
173 +end )
134 175 pcall( vim.fn.chanclose, channel )
135 176 server:kill 'sigterm'