@jimmy.codes/stet 0.7.0 → 0.7.2

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 (2) hide show
  1. package/README.md +33 -357
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -15,7 +15,10 @@ becoming part of the agent loop. It does not review code, approve changes, talk
15
15
  to the agent, or manage a workflow. It shows you the repo, the diff, and the
16
16
  problems. You decide what to say next.
17
17
 
18
- ![stet showing the repo tree beside a diff of a changed file](assets/screenshots/stet.png)
18
+ Stet is the proofreader's mark for "let it stand": strike a word out, add dots
19
+ beneath, and it stays.
20
+
21
+ ![stet showing the repo tree beside a diff of a changed file](docs/public/screenshots/stet.png)
19
22
 
20
23
  ## What it does
21
24
 
@@ -23,28 +26,24 @@ problems. You decide what to say next.
23
26
  not ignored by git.
24
27
  - Marks changed files in place, with staged, unstaged, mixed, and untracked
25
28
  states.
26
- - Opens unchanged files read-only, with syntax highlighting for any language Shiki supports.
29
+ - Opens unchanged files read-only, with syntax highlighting for any language
30
+ Shiki supports.
27
31
  - Opens changed files as diffs, with a toggle for the full file.
28
- - Finds text within the open file and cycles through the matches.
29
- - Searches file contents across the repo, scoped to the changes or the whole
30
- tree.
31
- - Switches scope from a picker: all changes, staged, unstaged, everything since
32
- stet launched, or just the last commit.
33
- - Switches between git worktrees in place, re-pointing the tree, diffs,
34
- refresh, and checks at the chosen worktree.
35
- - Watches the filesystem and refreshes the moment the agent changes something,
36
- then keeps the current file and selection stable as the view refreshes.
32
+ - Finds text within the open file, and searches file contents across the repo,
33
+ scoped to the changes or the whole tree.
34
+ - Switches scope from a picker (all changes, staged, unstaged, since launch, or
35
+ the last commit) and between git worktrees in place.
36
+ - Watches the filesystem and refreshes as the agent changes files, keeping the
37
+ current file and selection stable.
37
38
  - Marks recent activity and lets you jump to the latest touched file.
38
- - Shows diagnostics in the tree, in the viewer, and in a problems panel.
39
+ - Shows diagnostics in the tree, the viewer, and a problems panel.
39
40
  - Navigates code through read-only language-server pulls: go to definition, find
40
- references, find implementations, call hierarchy, hover for type and docs, and a
41
- symbol outline of the open file.
42
- - Copies a reference and snippet to paste back into the agent conversation: the
43
- file `path` in the tree and `path:line:col` in the viewer (`path:line` after
44
- clicking a line number).
41
+ references, find implementations, call hierarchy, hover, and a symbol outline.
42
+ - Copies a reference and snippet to paste back to the agent: `path` in the tree
43
+ and `path:line:col` in the viewer.
45
44
 
46
- The git-backed file tree renders first. Diagnostics come in later as decorations.
47
- That keeps the basic view useful even when checks are still running.
45
+ The git-backed file tree renders first. Diagnostics come in later as
46
+ decorations, so the basic view stays useful even when checks are still running.
48
47
 
49
48
  ## Install
50
49
 
@@ -59,358 +58,35 @@ npm i -g @jimmy.codes/stet
59
58
  brew install jimmy-guzman/tap/stet
60
59
  ```
61
60
 
62
- ## Upgrade
63
-
64
- ```sh
65
- stet upgrade
66
- ```
67
-
68
- Updates stet to the latest release using whichever channel it was installed
69
- through: a standalone install re-runs the install script, an npm install runs
70
- npm, and a Homebrew install runs `brew upgrade`. If the install channel cannot
71
- be determined, it prints the upgrade commands instead. It checks the latest
72
- GitHub release first and reports `stet X.Y.Z is already up to date` without
73
- running anything when you are current, falling back to the channel update if it
74
- cannot reach GitHub.
75
-
76
- stet also checks for a newer release in the background while it runs, and
77
- prints a one-line notice on clean exit when one is available, the way `gh` does.
78
- The check is non-blocking and never interrupts the session.
79
-
80
- ## Usage
81
-
82
- ```sh
83
- stet # whole repo, uncommitted vs HEAD
84
- stet main # compare against another ref
85
- stet --staged # start in the staged scope
86
- stet --unstaged # start in the unstaged scope
87
- stet --no-icons # plain tree without Nerd Font file-type icons
88
- stet --wrap # wrap long lines in the viewer instead of scrolling them horizontally
89
- stet --editor "nvim +{line} {file}" # terminal editor for the e key
90
- stet --ide "code --goto {file}:{line}" # GUI/IDE for the o key
91
- ```
92
-
93
- The tree shows a file-type icon next to each file and a folder glyph for each
94
- directory; symlinks get a distinct symlink icon and show their target path as
95
- content (the same thing git stores), not the file they point at. These are
96
- [Nerd Font](https://www.nerdfonts.com/) glyphs and only render with a Nerd Font
97
- selected in your terminal; without one they appear as empty boxes, so pass
98
- `--no-icons` to fall back to a plain tree.
99
-
100
- ## Features
101
-
102
- ### Read any file
103
-
104
- Open any file and read it with syntax highlighting for any language Shiki
105
- supports. Unchanged files open read-only with no diff gutters, just the source.
106
-
107
- ![read-only file view showing a source file with syntax highlighting and no diff gutters](assets/screenshots/read-only.png)
108
-
109
- ### Fold code
110
-
111
- Press `z` in the viewer to fold the block at the caret behind a `▸ N lines
112
- folded` marker (the header line stays), so a long file reads by structure instead
113
- of scrolling; `z` again unfolds it. Folding follows the file's structure: code
114
- folds by indentation, and markdown folds by heading section (down to the next
115
- same-or-higher heading). The same key expands a git-elided gap (the `⋯ N
116
- unmodified lines` marker) to reveal the unchanged lines around a hunk. Click any
117
- marker to toggle it. Folding is per file and resets when you switch files.
118
-
119
- ![a source diff with a function folded behind a "17 lines folded" marker](assets/screenshots/folding.png)
120
-
121
- ### Browse, go back, and pin tabs
122
-
123
- Browsing the tree previews files in a single view, so nothing piles up; the
124
- preview shows in italic to mark it as ephemeral. `<` and `>` step back and forward
125
- through where you've been, restoring each spot's cursor and scroll. When you want
126
- to keep a file while you look at another, `ctrl-t` pins it as a tab (and `ctrl-t`
127
- again unpins it), or double-click the tab or the file in the tree to pin it; `{` /
128
- `}` switch tabs and `ctrl-w` closes one. Each tab carries its own history and
129
- remembered position, and a tab's label is tinted by its diff status.
130
-
131
- ![tab strip with pinned, diff-status-tinted tabs and the active file](assets/screenshots/tabs.png)
132
-
133
- ### Switch scope
134
-
135
- Press `s` to pick what the diff compares. The scopes are grouped into changes
136
- (uncommitted, staged, or unstaged) and history (everything since stet launched,
137
- or just the last commit). The picker also drills into recent commits (`commits →`),
138
- so you can view any of them as its own diff.
139
-
140
- ![scope picker grouping the diff scopes under changes and history, with the active one marked](assets/screenshots/scope-picker.png)
141
-
142
- ### Switch worktrees
143
-
144
- Press `w` to jump between git worktrees without leaving the view. Type to
145
- filter by branch or path, `↑↓` to move, `⏎` to switch. The tree, diffs,
146
- polling, and checks all re-point at the chosen worktree.
147
-
148
- ![worktree combobox with a filter input listing worktrees, the current one marked](assets/screenshots/worktree-picker.png)
149
-
150
- ### Switch themes
151
-
152
- Press `t` to open the theme switcher: filter by name and move (or hover) to
153
- preview the whole UI live, `enter` to apply, `esc` to revert. The switch lasts the
154
- session; [config](#configuration) is where a theme is made permanent.
155
-
156
- ![theme switcher listing themes with color swatches, previewing the highlighted one live](assets/screenshots/theme-switcher.png)
157
-
158
- ### Go to file
159
-
160
- Press `ctrl-p` to fuzzy-search the whole repo and open any file.
161
-
162
- ![go-to-file overlay fuzzy-matching paths across the repo](assets/screenshots/go-to-file.png)
163
-
164
- ### Find in the viewer
165
-
166
- Press `/` to search within the open file. `n` and `N` cycle through matches, a
167
- counter tracks your place, and `esc` clears the search.
168
-
169
- ![find-in-viewer search highlighting matches in the open file with a match counter](assets/screenshots/find.png)
170
-
171
- ### Search file contents
172
-
173
- Press `ctrl-f` to open the project search pane in the main viewer area. Results
174
- group by file with syntax-highlighted context around each match; `ctrl-r`
175
- toggles regex, `ctrl-x` toggles case sensitivity, a filter field narrows by
176
- glob (`!` excludes, e.g. `src/ !*.test.ts`), `ctrl-g` toggles between the
177
- changed files and the whole tree, and `ctrl-s` picks the scope without leaving
178
- the pane. Jumping to a
179
- match keeps your query and results, so `ctrl-f` brings them right back.
180
-
181
- ![project content search listing matches for a term across several files in the repo](assets/screenshots/search.png)
182
-
183
- ### Go to definition
184
-
185
- Put the caret on a symbol and press `F12` to jump to its definition, backed by
186
- the same language servers that drive diagnostics. A cross-file jump records your
187
- spot, so `<` returns to the call site. When more than one definition matches (an
188
- overloaded symbol), the targets open in a results list to pick from rather than
189
- jumping to the first. It's a read-only LSP request, exactly like the diagnostics
190
- it shares servers with: it never writes to the repo.
61
+ Run `stet` inside any git repository; `stet upgrade` updates it in place.
191
62
 
192
- ### Find references
63
+ ## Documentation
193
64
 
194
- Put the caret on a symbol and press `Shift+F12` to list everywhere it's used.
195
- The results open in a palette-family overlay grouped by file, each row showing
196
- `path:line:col` and its source line. `↑`/`↓` move, `enter` or a click jumps to a
197
- result, `esc` closes. Same read-only LSP request family as go-to-definition,
198
- over the same servers.
199
-
200
- ### Find implementations
201
-
202
- Put the caret on an interface or abstract member and press `Shift+I` to jump past
203
- the abstraction to its concrete bodies. A single implementation jumps straight
204
- there; more than one opens the same overlay as find-references, grouped by file
205
- with each row's source line, to pick from. On a plain concrete symbol the server
206
- returns one location and it collapses to a jump. It's a read-only LSP request
207
- over the same servers as go-to-definition, distinct from it: definition lands on
208
- the abstract declaration, implementations land on the concrete bodies.
209
-
210
- ![find implementations overlay listing an interface's concrete implementations grouped by file, each with its source line](assets/screenshots/find-implementations.png)
211
-
212
- ### Call hierarchy
213
-
214
- Put the caret on a function or method and press `Shift+H` to list its callers in
215
- the same overlay as find-references. `Tab` flips direction: incoming calls (who
216
- calls this) to outgoing calls (what this calls) and back, the footer showing
217
- which way you're looking. `↑`/`↓` move, `enter` or a click jumps to a caller or
218
- callee, `esc` closes. It's a two-step read-only LSP request (prepare, then
219
- resolve the edges), over the same servers as go-to-definition.
220
-
221
- ![call hierarchy overlay listing the callers of a function grouped by file, each with its source line, and a direction toggle hint in the footer](assets/screenshots/call-hierarchy.png)
222
-
223
- ### Hover
224
-
225
- Press `K` with the caret on a symbol to show its type and docs in a small card
226
- anchored at the caret, the way an editor's hover does. The type signature is
227
- syntax-highlighted with the same theme as the diff; the docs read as plain text.
228
- The card clears as soon as you move the caret, scroll, switch files, or press
229
- `esc`. It's the same read-only LSP request family as go-to-definition.
230
-
231
- ![hover card anchored at the caret showing a syntax-highlighted type signature above its docs](assets/screenshots/hover.png)
232
-
233
- ### Find symbols
234
-
235
- Press `S` to list the open file's symbols in a palette-family overlay:
236
- classes, functions, methods, and the rest, each with its kind icon and
237
- `line:col`, nested to mirror the file's structure. `↑`/`↓` move, `enter` or a
238
- click jumps to a symbol, `esc` closes. Unlike go-to-definition it needs no
239
- caret, only an open file. Same read-only LSP request family, over the same
240
- servers.
241
-
242
- ![symbol outline overlay listing the open file's functions and methods with kind icons and line:col](assets/screenshots/find-symbols.png)
243
-
244
- ### Problems
245
-
246
- Diagnostics from the repo's language servers stream into a problems panel as
247
- checks finish: type errors from TypeScript and lint findings from oxlint, plus
248
- Biome's diagnostics in repos that use it (a `biome.json`/`biome.jsonc`), covering
249
- CSS and GraphQL on top of the JS/TS family. JSON (with JSONC) and YAML get
250
- schema-aware validation in any repo (Biome only lints JSON, and only where it's
251
- configured).
252
- Each is tagged with its source and pinpointed to its `line:col`. Press `p` to
253
- open it and `enter` to jump to a finding.
254
-
255
- No language server installed? stet fetches one on first use (preferring the
256
- repo's own, then your `PATH`), so diagnostics work out of the box. Pass
257
- `--no-lsp-download` to turn that off.
258
-
259
- ![problems panel docked below a diff, listing diagnostics with their file locations](assets/screenshots/problems.png)
260
-
261
- ## Keys
262
-
263
- ### navigation
264
-
265
- | Key | Action |
266
- | --------- | ------------------------------------------------ |
267
- | `j` / `k` | move in the tree, viewer, or problems panel |
268
- | `h` / `l` | collapse / expand folders, or word-hop the caret |
269
- | `tab` | switch focus between tree and viewer |
270
- | `enter` | open the focused item / jump to a problem |
271
- | `ctrl-p` | go to file: fuzzy-search the whole repo |
272
- | `.` | jump to the most recently changed file |
273
- | `n` | jump to the next file with findings |
274
-
275
- ### viewer
276
-
277
- | Key | Action |
278
- | ----------- | --------------------------------------------------------- |
279
- | `/` | find in the viewer; `n`/`N` cycle, `esc` clears |
280
- | `ctrl-f` | project search pane; regex/case/glob/scope toggles |
281
- | `v` | toggle diff <-> full file view for a changed file |
282
- | `z` | fold / unfold the region at the caret, or a git gap |
283
- | `x` | toggle long-line wrap in the viewer |
284
- | `f` | load full content when truncated |
285
- | `ctrl-d/u` | half-page cursor movement in the viewer |
286
- | `g` / `G` | jump to first / last line |
287
- | `F12` | go to definition of the symbol under the caret |
288
- | `Shift+F12` | find references to the symbol under the caret |
289
- | `Shift+I` | find implementations of the symbol under the caret |
290
- | `Shift+H` | call hierarchy of the symbol (`Tab` flips direction) |
291
- | `K` | hover: type and docs for the symbol under the caret |
292
- | `S` | find symbols: outline of the open file |
293
- | `<` / `>` | back / forward through viewer history |
294
- | `y` | copy `path`, `path:line`, or `path:line:col` |
295
- | `Y` | copy the entire contents of the viewed file |
296
- | `Shift+↑/↓` | extend a line selection (drag or shift-click also select) |
297
- | `C` | copy the selected lines (or the caret line) |
298
-
299
- ### tabs
300
-
301
- | Key | Action |
302
- | --------- | ------------------------------------- |
303
- | `ctrl-t` | pin / unpin the current file as a tab |
304
- | `ctrl-w` | close the active tab |
305
- | `{` / `}` | previous / next tab |
306
-
307
- ### workspace
308
-
309
- | Key | Action |
310
- | --- | ------------------------------------------------- |
311
- | `s` | scope picker: kinds, or drill into recent commits |
312
- | `t` | theme switcher: filter, live-preview, apply |
313
- | `w` | switch to another git worktree |
314
- | `c` | toggle changes-only filter for the tree |
315
- | `r` | re-run checks |
316
-
317
- ### layout
318
-
319
- | Key | Action |
320
- | --------- | ------------------------------------------------- |
321
- | `p` | toggle the problems panel |
322
- | `ctrl-b` | toggle the file tree sidebar |
323
- | `[` / `]` | shrink / grow the sidebar (shrink past min hides) |
324
- | `\` | reset the sidebar to its default width |
325
-
326
- ### app
327
-
328
- | Key | Action |
329
- | ----------- | ------------------------------------------------------ |
330
- | `e` | open file in terminal editor (suspends TUI) |
331
- | `o` | open file in GUI / IDE (renderer stays live) |
332
- | `Shift+F10` | context menu for the focused tree row or viewer symbol |
333
- | `?` | show all keybindings |
334
- | `q` | quit (confirm with `y`) |
335
-
336
- Press `?` anytime to see the full list in the app:
337
-
338
- ![keybindings help overlay showing all shortcuts](assets/screenshots/keys.png)
339
-
340
- ## Mouse
341
-
342
- The keyboard drives everything, but the mouse works too. Click a file to open
343
- it, a folder to expand or collapse it, a diff line to move the cursor there, or
344
- a problem to jump to it. Double-click a file in the tree, or a tab in the strip,
345
- to pin it as a tab. Clicks also work in the overlays and the search pane: a go-to-file result, a
346
- worktree to switch to, or a theme to apply (hovering a theme previews it
347
- live); a click on a search result selects it and a double-click opens it. Clicking a pane focuses it, and the wheel scrolls whichever
348
- pane the pointer is over. Right-click a tree row or a viewer symbol for a context
349
- menu of the actions that apply there (go to definition, find references, find
350
- implementations, call hierarchy, hover, copy, open in editor), the same menu
351
- `Shift+F10` opens on the focused pane.
352
-
353
- ## Configuration
354
-
355
- Optional, at `~/.config/stet/config.jsonc` (`$XDG_CONFIG_HOME` is honored;
356
- `config.json` also works). Without it, stet follows your terminal's light/dark.
357
- A malformed or invalid config never blocks startup: it falls back to defaults and
358
- shows a notice.
359
-
360
- Define themes under `themes` and pick one with `theme`: a single name, or a
361
- `{ "dark": ..., "light": ... }` pair that follows the terminal live (flip your
362
- terminal's appearance and stet re-themes). A theme is a full set of `#rrggbb` tokens, or
363
- `{ "base": <name>, ... }` that inherits another theme and overrides only the
364
- tokens you name. Its `"syntax"` is a bundled Shiki theme name, or an object
365
- overriding individual tokens (`keyword`, `string`, ...).
366
-
367
- Use `editor` and `ide` to set persistent command templates for `e` and `o`. Both
368
- use `{file}` and `{line}` as placeholders; `{line}` is omitted automatically
369
- when no cursor line is available. Without a config value, each key falls back to
370
- `STET_EDITOR` / `STET_IDE`, then `$EDITOR` / `$VISUAL`, then `vim` (editor
371
- only); `o` does nothing if nothing is configured. A bare editor name (no
372
- `{file}`) is expanded to a known template (`nvim` becomes `nvim +{line} {file}`,
373
- `code` becomes `code --goto {file}:{line}`, and so on). Templates are split on
374
- whitespace, so file paths with spaces in the editor binary path are not
375
- supported.
376
-
377
- ```jsonc
378
- {
379
- "editor": "nvim +{line} {file}",
380
- "ide": "code --goto {file}:{line}",
381
- }
382
- ```
383
-
384
- ```jsonc
385
- {
386
- // follow the terminal, with a custom theme on each side
387
- "theme": { "dark": "my-dark", "light": "my-light" },
388
- "themes": {
389
- "my-dark": { "base": "dark", "accent": { "primary": "#ffa7d9" } },
390
- "my-light": { "base": "light", "accent": { "primary": "#b4267a" } },
391
- "mocha": { "base": "dark", "syntax": "catppuccin-mocha" }, // stet chrome, Catppuccin code
392
- "tweaked": { "base": "dark", "syntax": { "keyword": "#ff8800" } }, // one token changed
393
- },
394
- }
395
- ```
65
+ Full documentation lives at **[stet.jimmy.codes](https://stet.jimmy.codes)**:
396
66
 
397
- Press `t` to open the theme switcher and try any of these without editing the
398
- config: filter by name, move (or hover) to preview the whole UI live, `enter`
399
- (or click) to apply, `esc` to revert. The switch lasts the session; `config` is
400
- still where a theme is made permanent.
67
+ - [Getting started](https://stet.jimmy.codes/docs): install, usage, flags, and
68
+ requirements
69
+ - [Guides](https://stet.jimmy.codes/docs/guides/reading-files-and-diffs):
70
+ reading files and diffs, search and navigation, code intelligence, scopes and
71
+ worktrees, and themes
72
+ - [Keybindings](https://stet.jimmy.codes/docs/reference/keybindings): every
73
+ shortcut (or press `?` in the app)
74
+ - [Configuration](https://stet.jimmy.codes/docs/reference/configuration): themes
75
+ and editor setup at `~/.config/stet/config.jsonc` (or `config.json`)
401
76
 
402
77
  ## Requirements
403
78
 
404
79
  - git
405
80
  - a clipboard tool for copy (`y`): `pbcopy` on macOS (built in), or `wl-copy`,
406
81
  `xclip`, or `xsel` on Linux
407
- - a Nerd Font for the tree's file-type icons (optional; use `--no-icons` without one)
82
+ - a Nerd Font for the tree's file-type icons (optional; use `--no-icons` without
83
+ one)
408
84
 
409
85
  ## Development
410
86
 
411
87
  ```sh
412
88
  bun install
413
- bun run src/main.tsx # run from source
89
+ bun run stet # run from source (the TUI lives in packages/tui)
414
90
  bun run check # tests + typecheck
415
91
  bun run build:dist # build standalone binaries for all targets
416
92
  ```
package/package.json CHANGED
@@ -16,11 +16,11 @@
16
16
  "license": "MIT",
17
17
  "name": "@jimmy.codes/stet",
18
18
  "optionalDependencies": {
19
- "stet-darwin-arm64": "0.7.0",
20
- "stet-darwin-x64": "0.7.0",
21
- "stet-linux-x64": "0.7.0",
22
- "stet-linux-arm64": "0.7.0"
19
+ "stet-darwin-arm64": "0.7.2",
20
+ "stet-darwin-x64": "0.7.2",
21
+ "stet-linux-x64": "0.7.2",
22
+ "stet-linux-arm64": "0.7.2"
23
23
  },
24
24
  "repository": "github:jimmy-guzman/stet",
25
- "version": "0.7.0"
25
+ "version": "0.7.2"
26
26
  }