pi-vim-tree 0.0.0-stage → 0.1.0

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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ - Branch motion is now `h` / `l` (next / previous branch head), matching `ctrl+j` / `ctrl+k`. Branch-head jumps also enter the jump list, so `ctrl+o` walks back through the branches you visited.
6
+ - Half-page scroll added on `u` / `d`, matching `ctrl+u` / `ctrl+d`.
7
+ - Removed the `d{m}` single-mark delete. `d` is half-page scroll now; `M` still clears every mark.
8
+ - Label editing and label timestamps moved to uppercase only: `L` / `T`. Lowercase `l` is branch motion, lowercase `t` is unbound.
9
+ - `q` closes the tree (native `esc` behaviour is unchanged; `ctrl+l` stays the way to clear a pending command or the search highlight).
10
+
11
+ ## [0.1.0] - 2026-11-10
12
+
13
+ - Initial release.
14
+ - Vim folding: `zc` / `zo` / `za` / `zC` / `zO` / `zA` / `zm` / `zr` / `zM` / `zR` / `zj` / `zk` / `zv`.
15
+ - Stable line numbers: folding never renumbers rows, so `G`, `{n}G`, `gg` and `%` always mean the same row.
16
+ - Logical cursor row, jump list (`ctrl+o` / `ctrl+i`), marks (`m{x}`, `` ` ``{x}, `d{x}`), and a showcmd-style status bar.
17
+ - Fixed-height list with a side preview.
18
+ - `/vim-tree on|off` restores Pi's native tree exactly.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ooostrich
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,314 @@
1
- # Temporary Holding Version
1
+ > Pi can create extensions. Ask it to build one for your use case.
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # pi-vim-tree
4
+
5
+ A Vim-flavoured patch for Pi's built-in `/tree` view. It adds Vim-style folding, motion, and status feedback on top of the native tree, and hands everything else back to Pi unchanged.
6
+
7
+ The extension patches the native tree in place. It never replaces `/tree`, never changes what the tree contains, and can be turned off at runtime to restore the original behaviour exactly.
8
+
9
+ **Key capabilities:**
10
+ - **Vim folding** - `zc`/`zo`/`za`/`zC`/`zO`/`zA`/`zm`/`zr`/`zM`/`zR`/`zj`/`zk`/`zv` with Vim's semantics
11
+ - **Stable line numbers** - folding never renumbers rows, so `G`, `{n}G`, `gg`, and `%` always mean the same row
12
+ - **Logical cursor row** - folding hides the row under the cursor but keeps its place, and restores it when the fold opens again
13
+ - **Jump list** - `ctrl+o` and `ctrl+i` walk backwards and forwards through your jumps, the way Vim's jump list does
14
+ - **Marks** - `m` plus a letter or digit sets a mark, backtick plus the same name jumps back to it
15
+ - **Showcmd status bar** - pending prefixes and executed commands echo the way Vim's `showcmd` does
16
+ - **Fixed-height layout** - the list never resizes, so filtering or folding never makes the panel jump
17
+ - **Side preview** - the selected message body is shown next to the tree, fzf `--preview-window` style
18
+
19
+ **Example use cases:**
20
+ - Navigating long sessions without losing your place
21
+ - Collapsing noisy branches while keeping jump targets stable
22
+ - Reaching a collapsed branch with a single keystroke (`zA`, `zv`)
23
+ - Working with the tree in a fixed-size panel inside larger terminal layouts
24
+
25
+ ## Table of Contents
26
+
27
+ - [Installation](#installation)
28
+ - [Requirements](#requirements)
29
+ - [Commands](#commands)
30
+ - [Key Bindings](#key-bindings)
31
+ - [Folding](#folding)
32
+ - [Motion](#motion)
33
+ - [Search](#search)
34
+ - [Preview](#preview)
35
+ - [Folding Model](#folding-model)
36
+ - [Line Numbers and Jumps](#line-numbers-and-jumps)
37
+ - [Logical Cursor Row](#logical-cursor-row)
38
+ - [Marks](#marks)
39
+ - [Jump List](#jump-list)
40
+ - [Status Bar](#status-bar)
41
+ - [Layout](#layout)
42
+ - [Compatibility](#compatibility)
43
+ - [Troubleshooting](#troubleshooting)
44
+ - [Differences from Vim](#differences-from-vim)
45
+ - [Development](#development)
46
+
47
+ ## Installation
48
+
49
+ Install it as a Pi package:
50
+
51
+ ```bash
52
+ pi install npm:pi-vim-tree
53
+ ```
54
+
55
+ Or try it for a single run without adding it to your settings:
56
+
57
+ ```bash
58
+ pi -e npm:pi-vim-tree
59
+ ```
60
+
61
+ Without npm, copy `extensions/vim-tree.ts` into Pi's global extension directory:
62
+
63
+ ```bash
64
+ mkdir -p ~/.pi/agent/extensions
65
+ cp extensions/vim-tree.ts ~/.pi/agent/extensions/vim-tree.ts
66
+ ```
67
+
68
+ Restart Pi, or hot-reload the extension with `/reload`. Extensions in `~/.pi/agent/extensions/` are auto-discovered and can be reloaded without restarting the session.
69
+
70
+ To disable the patch at startup, set `PI_VIM_TREE=0` in the environment. Pi then loads the extension but applies nothing.
71
+
72
+ ## Requirements
73
+
74
+ Pi 1.5.1 or newer. The extension works by patching Pi's internal tree component, so it needs access to those internals - it locates them by content rather than by file name, because the bundle's chunk names change with every release.
75
+
76
+ When Pi changes the internals in a way the extension does not recognise, it stays silent and leaves the native tree alone. `/vim-tree` then reports why.
77
+
78
+ Node.js 22.19 or newer, same as Pi itself. The extension adds no runtime dependencies.
79
+
80
+ ## Commands
81
+
82
+ | Command | Description |
83
+ | --- | --- |
84
+ | `/vim-tree` | Report the current state (on/off, build id, and the reason if the patch could not be applied) |
85
+ | `/vim-tree on` | Apply the patch to `/tree` |
86
+ | `/vim-tree off` | Remove every patch and restore native behaviour |
87
+
88
+ `off` is a full undo: each patched method is registered in an undo registry and reverted in reverse order, including the tree instance's filter handling and the search state.
89
+
90
+ The tree *instance* is restored as well. While it is active the extension changes the list height, the filter mode, the fold state and the label-timestamp flag - all of them native fields - so `off` puts the original values back, clears the search box and resets the mode. Without that the native tree would come back with the wrong number of rows, a filter still applied, or folds left over.
91
+
92
+ While the label editor is open, the extension steps aside completely and hands every key to Pi, so labels are typed exactly the way Pi types them.
93
+
94
+ ## Key Bindings
95
+
96
+ Native tree keys (`j`/`k`, `enter`, `L` label, `T` label time, `/` search) keep working. Label and label time are on the uppercase keys only - lowercase `l` is branch motion now, and lowercase `t` is unbound. The extension adds:
97
+
98
+ ### Folding
99
+
100
+ | Key | Action |
101
+ | --- | --- |
102
+ | `zc` | Close the fold under the cursor |
103
+ | `zo` | Open the fold under the cursor |
104
+ | `za` | Toggle the fold under the cursor |
105
+ | `zC` | Close the fold and the whole subtree |
106
+ | `zO` | Open the fold and the whole subtree |
107
+ | `zA` | Toggle recursively - open the entire subtree, or close every fold in it |
108
+ | `zm` | Fold one level deeper |
109
+ | `zr` | Unfold one level |
110
+ | `zM` | Close all folds |
111
+ | `zR` | Open all folds |
112
+ | `zj` / `zk` | Jump to the next / previous fold |
113
+ | `zv` | Open just enough folds to reveal the row that was folded away |
114
+
115
+ ### Motion
116
+
117
+ | Key | Action |
118
+ | --- | --- |
119
+ | `h` / `l` | Previous / next branch head (wraps) |
120
+ | `ctrl+j` / `shift+down` | Next branch head (wraps) |
121
+ | `ctrl+k` / `shift+up` | Previous branch head (wraps) |
122
+ | `g0` | Jump to the current session branch |
123
+ | `gg` | Jump to the first row |
124
+ | `G` / `{n}G` | Jump to the last row / to row `{n}` |
125
+ | `%` | Jump to the matching branch |
126
+ | `gt` / `gl` / `gu` / `ga` / `gd` | Filter: no tools / labelled only / user only / all / default |
127
+ | `ctrl+f` / `ctrl+b` | Page down / up |
128
+ | `u` / `d` | Half page up / down |
129
+ | `ctrl+u` / `ctrl+d` | Half page up / down (same as `u` / `d`) |
130
+
131
+ ### Leaving
132
+
133
+ | Key | Action |
134
+ | --- | --- |
135
+ | `q` | Close the tree (like `q` in a Vim help/preview window, or in `less` / `fzf`) |
136
+
137
+ `esc` keeps its native meaning (cancel the search box, otherwise leave the tree) - nothing is layered on top of it. Clearing a pending command or the search highlight is `ctrl+l`'s job, matching the `ctrl+l` mapping people already have in Vim.
138
+
139
+ ### Search
140
+
141
+ | Key | Action |
142
+ | --- | --- |
143
+ | `/` | Native search box (incremental, backspace works) |
144
+ | `n` / `N` | Next / previous match |
145
+ | `p` | Previous match |
146
+ | `ctrl+l` | Clear the search term and the highlight |
147
+
148
+ ### Preview
149
+
150
+ | Key | Action |
151
+ | --- | --- |
152
+ | `ctrl+h` (or `F4`) | Toggle the side preview |
153
+ | `ctrl+e` / `ctrl+y` | Scroll the preview by one line |
154
+
155
+ ## Folding Model
156
+
157
+ Pi's native tree marks the rows that can be folded with `⊟`, and shows `⊞` once a fold is closed. pi-vim-tree folds exactly those rows, and nothing else:
158
+
159
+ - Only branch points fold. Leaf rows and the root row have no fold marker, so they never fold.
160
+ - A fold closes the whole subtree below the row.
161
+ - `zm` and `zr` work on *levels*, not on individual rows. Levels are numbered consecutively (like Vim's `foldlevel`) because Pi's own indent only increments at branch points, which would otherwise produce a `1 -> 3 -> 5` sequence.
162
+
163
+ The current level and the total number of levels are shown in the title bar:
164
+
165
+ ```
166
+ Session Tree Fold 2/5 · Match 1/3
167
+ ```
168
+
169
+ ## Line Numbers and Jumps
170
+
171
+ Line numbers are computed against the **unfolded** list, the way Vim counts buffer lines. Folding a branch hides the rows inside it and leaves their numbers blank; it never renumbers the rows below.
172
+
173
+ Because of that, every jump command resolves against the same fixed list:
174
+
175
+ - `G` and `{n}G` jump to an absolute row number
176
+ - `gg` jumps to the first row
177
+ - `%` jumps to the matching branch
178
+
179
+ If the target row is hidden inside a fold, the fold is opened first and the jump lands on the row itself. `g0` follows the same rule.
180
+
181
+ ## Logical Cursor Row
182
+
183
+ Pi-vim-tree keeps a single *logical cursor row* - the row the cursor really belongs to, even when it is hidden.
184
+
185
+ - Folding does not change it.
186
+ - While it is hidden, the cursor is displayed on its nearest visible ancestor (the fold row).
187
+ - When the fold opens again and the row becomes visible, the cursor returns to it.
188
+ - Only moving the cursor replaces it.
189
+
190
+ The number of folds covering that row is derived from the parent chain, so folds in unrelated branches are never counted.
191
+
192
+ `zv` remembers the row that a fold hid. Moving the cursor afterwards does not throw that memory away, so `zv` still brings you back to it - unlike the logical cursor row, which follows the cursor by Vim's rules.
193
+
194
+ ## Marks
195
+
196
+ Marks work like in Vim. `m` followed by a letter or a digit stores the current row under that name; backtick followed by the same name jumps back to it. If the marked row is hidden inside a fold, the fold is opened first.
197
+
198
+ | Key | Action |
199
+ | --- | --- |
200
+ | `m` + letter or digit | Set a mark on the current row |
201
+ | `` ` `` + letter or digit | Jump to that mark |
202
+ | `` ` `` + `` ` `` | Jump back to the position before the last jump - press it again to come back, and again to go back |
203
+ | `M` | Delete all marks (Vim's `:delmarks!`) |
204
+
205
+ There are 62 mark names: `a` to `z`, `A` to `Z` and `0` to `9`.
206
+
207
+ There is no single-mark delete key: `d` is half-page scroll now, so a mark goes away by clearing them all with `M` or by overwriting it. Setting a mark again under the same name simply replaces the old position.
208
+
209
+ Marks live in the extension rather than in the tree view, so they survive closing and reopening `/tree`. They are cleared when the session changes, because the row ids they point at belong to the old session.
210
+
211
+ Backtick backtick jumps to the position you were at before the last jump - Vim's "previous context" mark. It toggles: the next press brings you forward again, and the next one takes you back, so you can move between the two positions without re-typing the key. A fresh jump resets it to "back".
212
+
213
+ ## Jump List
214
+
215
+ `ctrl+o` and `ctrl+i` move through the jump list, exactly like Vim in normal mode: `ctrl+o` goes to the previous jump, `ctrl+i` goes to the next one.
216
+
217
+ | Key | Action |
218
+ | --- | --- |
219
+ | `ctrl+o` / `ctrl+i` | Older / newer position in the jump list |
220
+ | `J` | Clear the jump list (Vim's `:clearjumps`) |
221
+
222
+ Only *jumps* are recorded - `gg`, `G`, `{n}G`, `%`, `g0`, a branch-head jump (`h` / `l`, `ctrl+j` / `ctrl+k`, `shift+down` / `shift+up`), a mark jump, a committed search, and `n` / `N` / `p`. Branch-head jumps are structural jumps, the same class as Vim's `{` / `}`, so scanning branches with `h`/`l` and then pressing `ctrl+o` walks back through them one branch at a time. Line movement (`j` / `k`), scrolling (`u` / `d`, `ctrl+f/b`, `ctrl+u/d`) and fold jumps (`zj` / `zk`) do not enter the list, same as in Vim.
223
+
224
+ The list behaves like browser history: jumping somewhere new truncates the entries ahead of the current position, so `ctrl+i` no longer walks into a branch you have left. A count works too - `{n}` followed by `ctrl+o` jumps back several entries at once.
225
+
226
+ Entries are deduplicated by row, so a round of `l`/`h` branch scanning never piles up the same branch twice.
227
+
228
+ Two limits match Vim:
229
+
230
+ - **At most 100 entries.** The oldest entries are dropped first.
231
+ - **No duplicates.** Jumping to a row you visited before removes the older copy, so `ctrl+o` returns to that position once, not twice.
232
+
233
+ ## Status Bar
234
+
235
+ The status bar follows Vim's `showcmd` behaviour in three tiers:
236
+
237
+ | State | Behaviour |
238
+ | --- | --- |
239
+ | Waiting for a second key (`11`, `g`, `z`) | The prefix stays on screen |
240
+ | Command finished (`j`, `11G`) | The command flashes briefly and is then cleared |
241
+ | Unmatched key | Nothing is shown |
242
+
243
+ The mode badge (`NORMAL` / `SEARCH`) is followed by the pending input in the default foreground colour.
244
+
245
+ The counters next to the `Session Tree` title follow the same rule as the fold counter - they appear only when there is something to report, and disappear when it is gone:
246
+
247
+ ```
248
+ Session Tree Fold 2/5 · Match 1/3 · Jump 4/9 · Mark a,b
249
+ ```
250
+
251
+ `Jump x/y` is your position in the jump list and how long the list is. `Mark a,b` lists the marks you have set. Clear the jump list with `J` and the marks with `M`, and both counters vanish again.
252
+
253
+ ## Layout
254
+
255
+ The list keeps a fixed height - 60% of the available space, capped at 30 rows - so folding, filtering, or a shorter session never resizes the panel and never makes surrounding UI shift.
256
+
257
+ The preview occupies the right 55% of the width, fzf `--preview-window right:55%` style. Because the list height is fixed and the preview only takes horizontal space, toggling the preview causes no reflow at all.
258
+
259
+ ## Compatibility
260
+
261
+ The patch works on Pi's internal tree classes, which live in the compiled bundle. Chunk file names change between releases (`chunk-44DLKSKE.js` in 1.5.0, `chunk-ZKNSXGL5.js` in 1.5.1), so the extension locates the chunk by its content, imports it dynamically, and patches the prototype.
262
+
263
+ Because it relies on private fields, it self-checks on startup. If Pi's internals change shape, the extension stays silent and falls back to native behaviour, and `/vim-tree` reports the reason.
264
+
265
+ ## Troubleshooting
266
+
267
+ **`/vim-tree` says "not applied".** Pi's internals changed in a way the extension does not recognise. Update Pi and reload; if it still fails, the reason is printed by `/vim-tree`.
268
+
269
+ **The keys do nothing.** The extension is off (`/vim-tree on`), or the tree does not have keyboard focus. Native tree keys keep working in both cases.
270
+
271
+ **The tree looks shorter than before.** The list height is fixed at 60% of the terminal (30 rows max) so that folding and filtering never make the panel jump. Resize the terminal to get more rows.
272
+
273
+ **The tree shows a lot of `remote-pi` rows.** Those are custom messages the remote-pi package appends to the session history, one per rename. Pi's tree filter has no way to hide custom messages.
274
+
275
+ ## Releasing
276
+
277
+ The package is published from this directory:
278
+
279
+ ```bash
280
+ npm publish --access public
281
+ ```
282
+
283
+ Publishing needs a second factor. Use the code from your authenticator app, or the browser confirmation flow - do **not** use a recovery code: npm treats that as a security-sensitive action and can suspend the account.
284
+
285
+ For unattended releases, configure **trusted publishing** (OpenID Connect) on the npm package and point it at a GitHub Actions workflow. That removes the need for tokens entirely.
286
+
287
+ ## Differences from Vim
288
+
289
+ These are deliberate:
290
+
291
+ | Behaviour | Vim | pi-vim-tree |
292
+ | --- | --- | --- |
293
+ | `g0` | Go to column 0 | Jumps to the session's active branch - a tree has no columns, so Vim's `g0` has nothing to do here |
294
+ | `zm` / `zr` | Reset manually closed folds | Manual folds survive |
295
+ | `zm` | Decrements a counter, so closing several levels takes several presses | Steps one level immediately |
296
+ | Folding the root | Not possible | Falls back to folding the root when a chain has no branch point |
297
+ | Search scope | Searches the whole buffer, including hidden lines | Searches the visible rows only |
298
+ | `zX` / `zE` | Operate on manually closed folds | Not implemented - the tree has a single kind of fold |
299
+ | Mark names | `a`-`z`, `A`-`Z` (digits are numbered-buffer marks) | The same 62 names, and `m0`-`m9` set marks too |
300
+
301
+ ## Development
302
+
303
+ The extension is a single file with no build step. `npm` is only needed to publish it as a package.
304
+
305
+ The test suite drives the **real** Pi `TreeSelectorComponent`, loaded from the installed bundle, and feeds it real key bytes:
306
+
307
+ ```bash
308
+ ./test/setup.sh # 把已安装的 pi 里的 node_modules 链过来(裸 node 需要能 import pi-tui)
309
+ npm test
310
+ ```
311
+
312
+ It asserts on the visible rows, the selected row, the counters in the title bar, the fold markers, the jump list and the marks. A failing assertion prints the actual and expected values, and the exit code is non-zero.
313
+
314
+ The suite also covers the `/vim-tree off` path: after turning the extension off, the tree must render byte for byte like a tree that was never patched.