@narumitw/pi-starship 0.44.0 → 0.46.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.
Files changed (44) hide show
  1. package/README.md +246 -71
  2. package/package.json +2 -2
  3. package/src/command-inspector.ts +198 -0
  4. package/src/command-preview.ts +206 -0
  5. package/src/commands.ts +190 -154
  6. package/src/config.ts +177 -68
  7. package/src/format/style.ts +64 -45
  8. package/src/modules/activity.ts +1 -1
  9. package/src/modules/brand.ts +1 -1
  10. package/src/modules/cache.ts +1 -1
  11. package/src/modules/catalog.ts +62 -3
  12. package/src/modules/context.ts +13 -1
  13. package/src/modules/cost.ts +12 -1
  14. package/src/modules/development.ts +24 -7
  15. package/src/modules/directory.ts +141 -7
  16. package/src/modules/display.ts +14 -0
  17. package/src/modules/execution.ts +13 -2
  18. package/src/modules/extension-status.ts +1 -1
  19. package/src/modules/fill.ts +1 -1
  20. package/src/modules/git/branch.ts +14 -5
  21. package/src/modules/git/commit.ts +10 -3
  22. package/src/modules/git/metrics.ts +8 -2
  23. package/src/modules/git/runtime.ts +3 -0
  24. package/src/modules/git/state.ts +1 -1
  25. package/src/modules/git/status.ts +1 -1
  26. package/src/modules/git/worktree.ts +1 -1
  27. package/src/modules/github-pr.ts +1 -1
  28. package/src/modules/index.ts +13 -1
  29. package/src/modules/inspection.ts +138 -0
  30. package/src/modules/model.ts +15 -65
  31. package/src/modules/provider.ts +1 -1
  32. package/src/modules/render.ts +22 -3
  33. package/src/modules/terminal.ts +60 -0
  34. package/src/modules/thinking.ts +1 -1
  35. package/src/modules/time.ts +1 -1
  36. package/src/modules/tokens.ts +1 -1
  37. package/src/modules/truncation.ts +37 -0
  38. package/src/modules/turn.ts +1 -1
  39. package/src/modules/types.ts +22 -0
  40. package/src/pi-starship.ts +27 -1
  41. package/src/runtime/development.ts +1 -2
  42. package/src/runtime/execution.ts +19 -9
  43. package/src/runtime/types.ts +2 -0
  44. package/src/runtime/workspace.ts +21 -7
package/README.md CHANGED
@@ -8,8 +8,8 @@ A native Pi footer configured with Starship-style TOML. It parses and renders fo
8
8
 
9
9
  ## ✨ Features
10
10
 
11
- - Uses a readable built-in Tokyo Night configuration until the user explicitly saves settings.
12
- - Starship-style root/module formats, conditional groups, `$all`, styles, and palettes.
11
+ - Uses a readable, palette-free Starship-style built-in configuration until settings are saved.
12
+ - Starship-style root/module formats, conditional groups, `$all`, styles, and opt-in palettes.
13
13
  - Pi modules for model, thinking, activity, context, tokens, prompt cache, cost, turn, and extension statuses.
14
14
  - Cached Git branch, commit, operation state, line metrics, detailed status, and linked-worktree identity.
15
15
  - Native current-branch GitHub pull request links, checks, review state, and terminal-state retention.
@@ -17,7 +17,8 @@ A native Pi footer configured with Starship-style TOML. It parses and renders fo
17
17
  - Width-aware `$fill` alignment for native multiline left/right layouts.
18
18
  - Footer rendering is pure: no subprocess, network, filesystem, timer, or environment work runs from `render()`.
19
19
  - Multiline output wraps to the terminal width instead of truncating.
20
- - Goal-oriented `/starship` menu with configuration health, preview, confirmation, and recovery.
20
+ - Goal-oriented `/starship` menu with footer explanation, searchable module inspection,
21
+ configuration health, transactional preview, and recovery.
21
22
 
22
23
  ## 📦 Install
23
24
 
@@ -41,7 +42,11 @@ The only configuration source is:
41
42
  <getAgentDir()>/pi-starship.toml
42
43
  ```
43
44
 
44
- When this file is absent, the extension uses its readable Tokyo Night default without creating the file or parent directory. The first successful settings save creates it atomically. Existing malformed documents are never overwritten.
45
+ When this file is absent, the extension uses its readable palette-free default without creating the
46
+ file or parent directory. The built-in root is the explicit sequence `$brand$model$thinking$directory`
47
+ `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query. The first
48
+ successful settings save creates the file atomically. Existing malformed documents are never
49
+ overwritten.
45
50
 
46
51
  The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
47
52
 
@@ -51,74 +56,100 @@ Open the interactive menu in TUI mode:
51
56
  /starship
52
57
  ```
53
58
 
54
- Choose **Customize footer** to edit the TOML. Closing the editor validates the draft and opens a width-aware preview; saving happens only after a separate confirmation. Confirmed changes are atomically saved and applied immediately. Manual TOML edits load on the next `session_start`, including `/reload` and session replacement. Editor cancellation, preview cancellation, invalid drafts, write failures, and runtime application failures preserve the previous file and effective footer.
55
-
56
- The standard **Advanced** menu is one level deep and contains configuration details plus **Restore
57
- built-in**. Standard diagnostics, details, and help are Back-navigable detail screens. Restore still
58
- shows the specialized width-aware preview and requires explicit overwrite confirmation.
59
+ Choose **Customize footer** to edit the TOML. Closing the editor validates the draft and opens an
60
+ adaptive, scrollable preview whose **Apply changes…**, **Continue editing**, and **Discard draft**
61
+ actions remain reachable in short or narrow terminals. Saving happens only after a separate
62
+ confirmation. Confirmed changes are atomically saved and applied immediately. Manual TOML edits load
63
+ on the next `session_start`, including `/reload` and session replacement. Editor cancellation, preview
64
+ cancellation, component disposal, invalid drafts, write failures, and runtime application failures
65
+ preserve the previous file and effective footer.
66
+
67
+ The shallow main menu also exposes **Explain footer**, **Modules**, **Configuration**, **Help**, and
68
+ **Restore built-in…**. Explain footer uses the current immutable runtime snapshot to list each
69
+ currently showing non-empty module once with its rendered value and description; it starts no new
70
+ collection work. Modules opens a bounded searchable inspector for every registered module. Its
71
+ textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and
72
+ **Unavailable** only when the current footer cannot provide an inspection snapshot. Module detail
73
+ shows the current preview when available, description, root reference and reachability, format
74
+ variables, style fields, display rules, and the known reason for absent output. Both views are
75
+ read-only and never create or update the settings document.
76
+
77
+ Configuration combines state, source, path, health, and diagnostics. A healthy missing file is shown
78
+ as **Built-in defaults**, while **Built-in fallback** is reserved for read or parse errors. Restore is
79
+ disabled when no settings document exists or the exact built-in document is already saved. For a
80
+ custom or invalid document, Restore previews the result and warns that the complete document,
81
+ including custom settings, unknown fields, and comments, will be replaced without a post-success
82
+ backup before asking for confirmation.
59
83
 
60
84
  ### 📝 Example
61
85
 
62
86
  ```toml
63
- format = "$brand$provider$model$thinking\n$directory$git_branch$github_pr$git_status\n$activity$context$tokens$cache$cost$time$turn\n$extension_status"
64
- palette = "tokyo-night"
65
-
66
- [palettes.tokyo-night]
67
- header = "#7aa2f7"
68
- header_fg = "#1a1b26"
69
- custom = "208"
87
+ format = """
88
+ $brand\
89
+ $model\
90
+ $thinking\
91
+ $directory\
92
+ $git_branch\
93
+ $git_status\
94
+ $activity\
95
+ $context\
96
+ $time"""
70
97
 
71
98
  [model]
72
99
  format = "[ $symbol$model ]($style)"
73
100
  symbol = "◆ "
74
- style = "bold fg:header_fg bg:header"
75
- disabled = false
101
+ style = "bold blue"
76
102
  truncation_length = 36
77
103
  truncation_symbol = "…"
78
104
  truncation_direction = "middle"
79
105
 
80
- [activity]
81
- format = "([ $text ]($style))"
82
- style = "fg:custom"
106
+ [directory]
107
+ style = "cyan bold"
108
+
109
+ [git_branch]
110
+ style = "bold purple"
83
111
 
84
112
  [context]
85
113
  format = "[$symbol $percentage/$window ]($style)"
86
114
 
87
- [cache]
88
- format = "[$symbol (R$read )(W$write )(CH$rate )]($style)"
115
+ [[context.display]]
116
+ threshold = 0
117
+ style = "bold green"
118
+ hidden = true
119
+
120
+ [[context.display]]
121
+ threshold = 30
122
+ style = "bold green"
123
+ hidden = false
124
+
125
+ [[context.display]]
126
+ threshold = 60
127
+ style = "bold yellow"
128
+ hidden = false
129
+
130
+ [[context.display]]
131
+ threshold = 80
132
+ style = "bold red"
133
+ hidden = false
134
+
135
+ [git_metrics]
136
+ added_style = "bold green"
137
+ deleted_style = "bold red"
89
138
  disabled = false
90
139
 
91
- [cost]
92
- format = "[ $symbol \\$$cost( $subscription) ]($style)"
93
-
94
- [git_branch]
95
- format = "[ $symbol $branch ]($style)"
96
-
97
- [github_pr]
98
- format = "[ $symbol$link( · $status) ]($style)"
99
- symbol = "PR "
100
- style = "fg:git_fg bg:git"
101
- disabled = false
102
-
103
- [package]
104
- version_format = "v$raw"
105
-
106
- [nodejs]
107
- detect_files = ["package.json", "!deno.json"]
108
- detect_extensions = ["js", "ts"]
109
-
110
- [hostname]
111
- ssh_only = true
112
- trim_at = "."
113
- aliases = { "build.example.test" = "builder" }
140
+ [username]
141
+ style_user = "yellow bold"
142
+ style_root = "red bold"
114
143
 
115
144
  [extension_status]
116
145
  format = "([$statuses ]($style))"
117
146
  icons = { "foo:*" = "🧪", "third_party/key" = "◎", fallback = "•" }
118
147
  ```
119
148
 
120
- All module tables support `format`, `symbol`, `style`, and `disabled`. Module-specific
121
- options are catalog-owned, type-checked, and listed below; unknown options warn and stay inactive.
149
+ Every module table supports `format`, `symbol`, and `disabled`. Most modules also support one `style`.
150
+ The exceptions are `git_metrics` (`added_style` and `deleted_style`), `username` (`style_user` and
151
+ `style_root`), and the threshold-selected `context` and `cost` `display` arrays described below.
152
+ Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
122
153
  Version formats replace `$raw`. Detection arrays replace defaults when non-empty and inspect only one
123
154
  listing of the current directory. A leading `!` is supported by language detection arrays and rejects
124
155
  a matching project.
@@ -155,11 +186,91 @@ Style expressions support:
155
186
  - Hex RGB (`#7aa2f7`).
156
187
  - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
157
188
  - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
158
- - `none`, `fg:none`, and `bg:none`.
159
- - `prev_fg` and `prev_bg` to inherit the previous rendered chunk's colors.
160
- - Color names from the active `[palettes.<name>]` table. The active palette overlays the built-in Tokyo Night colors so the default module styles remain available.
189
+ - `none` and `fg:none`, which make the complete expression unstyled regardless of position.
190
+ - `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same
191
+ Starship-compatible reset behavior.
192
+ - `prev_fg` and `prev_bg`, which use the previous rendered chunk's colors when present and retain any
193
+ absolute foreground/background in the expression as the no-previous fallback.
194
+ - Direct color names from one explicitly selected `[palettes.<name>]` table.
161
195
 
162
- An invalid root format falls back to the built-in root format. An invalid module format or style falls back only for that module. `/starship status` reports warnings.
196
+ There is no built-in or fallback palette. A custom palette is active only when its table is explicitly
197
+ selected, and its values must be direct named, ANSI, or RGB colors—palette entries cannot reference
198
+ other entries. Palette names override terminal color names such as `blue`:
199
+
200
+ ```toml
201
+ palette = "company"
202
+
203
+ [palettes.company]
204
+ blue = "#86BBD8"
205
+ accent = "208"
206
+
207
+ [model]
208
+ style = "bold blue"
209
+ ```
210
+
211
+ Style tokens are case-insensitive and ordinary foreground/background colors are last-wins.
212
+ `prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists. Empty styled
213
+ groups still advance previous-color state. Invalid literal style expressions warn and render
214
+ unstyled. An invalid root format falls back to the built-in root format; an invalid module format or
215
+ catalog-owned style field falls back only at that field's module scope. `/starship status` reports
216
+ warnings.
217
+
218
+ The background-free direct defaults are: `brand = "bold white"`, `provider`/`model` = `"bold blue"`,
219
+ `thinking`/`git_branch`/`turn` = `"bold purple"`, `directory`/`git_worktree` = `"cyan bold"`,
220
+ `github_pr = "bold blue"`, `git_commit = "green bold"`, `git_state`/`activity`/`time` =
221
+ `"bold yellow"`, `git_status = "red bold"`, `tokens = "bold cyan"`, `cache = "bold green"`,
222
+ `extension_status = "dimmed white"`, `direnv = "bold bright-yellow"`, and `fill = "bold black"`.
223
+ Context, cost, Git metrics, and username use the state/multi-style defaults below.
224
+
225
+ ### State-selected styles
226
+
227
+ `context` and `cost` select the last entry at the highest threshold less than or equal to the current
228
+ value. A later entry wins when thresholds are equal. Each display entry requires a finite `threshold`,
229
+ a valid `style`, and boolean `hidden`. Invalid entries warn and are ignored; module defaults are used
230
+ if none remain.
231
+
232
+ The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and
233
+ `bold red` at `80`. The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red`
234
+ at `5`:
235
+
236
+ ```toml
237
+ [[cost.display]]
238
+ threshold = 0
239
+ style = "bold green"
240
+ hidden = true
241
+
242
+ [[cost.display]]
243
+ threshold = 1
244
+ style = "bold yellow"
245
+ hidden = false
246
+
247
+ [[cost.display]]
248
+ threshold = 5
249
+ style = "bold red"
250
+ hidden = false
251
+ ```
252
+
253
+ `git_metrics` exposes `$added_style` and `$deleted_style` in its module format. `username` still uses
254
+ `$style` in its format, but selects `style_user` or `style_root` from private execution metadata; the
255
+ selector is not a format variable.
256
+
257
+ ### Breaking palette migration
258
+
259
+ The previous implicit `tokyo-night` palette and its `lead`, `header`, `header_fg`, `directory`,
260
+ `directory_fg`, `git`, `git_fg`, `runtime`, `runtime_fg`, `meter`, `meter_fg`, and `extension` aliases
261
+ were removed. Existing files are not rewritten. Old alias-based module styles warn and fall back to
262
+ the module's new direct-color default; alias-based literal Powerline groups warn and render unstyled.
263
+
264
+ Choose one migration:
265
+
266
+ 1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or
267
+ `fg:#e3e5e5 bg:#769ff0`.
268
+ 2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with
269
+ `palette = "<name>"`.
270
+ 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new
271
+ plain nine-module configuration.
272
+
273
+ There is no hidden compatibility overlay or automatic migration.
163
274
 
164
275
  ## 🧱 Modules
165
276
 
@@ -218,33 +329,84 @@ An invalid root format falls back to the built-in root format. An invalid module
218
329
  - Cache `$read` and `$write` are cumulative. `$rate` uses only the latest assistant prompt:
219
330
  `cacheRead / (input + cacheRead + cacheWrite) * 100`. The module is empty when Pi has reported no
220
331
  cache reads or writes.
221
- - `cache` is disabled by default, but the built-in root format already contains `$cache`; users who
222
- inherit that format can enable it with only `[cache] disabled = false`. A custom root format must
223
- reference `$cache` or `$all` normally.
224
- - Context `$percentage` uses native one-decimal precision. For a native-style display, use
225
- `format = "[$symbol $percentage/$window ]($style)"` under `[context]`; the module name remains
332
+ - `cache` is disabled and absent from the built-in root. Enable it and add `$cache` to a custom root
333
+ format (or use `$all`) to display it.
334
+ - Context `$percentage` uses native one-decimal precision. Its default display hides values below 30%;
335
+ customize `[[context.display]]` when lower values should remain visible. The module name remains
226
336
  `context`, not `context_usage`.
227
337
  - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`. The dollar
228
338
  value is usage cost, not proof of an amount billed under a subscription.
229
339
  - Pi's public extension API does not expose the current auto-compaction toggle, so pi-starship cannot
230
340
  reliably provide the native `(auto)` marker.
231
341
 
232
- ### Model truncation
342
+ ### Directory, Git, and environment contraction
343
+
344
+ The analogous modules keep their display policy local and use Starship defaults:
345
+
346
+ ```toml
347
+ [directory]
348
+ truncation_length = 3
349
+ truncate_to_repo = true
350
+ fish_style_pwd_dir_length = 0
351
+ truncation_symbol = ""
352
+ home_symbol = "~"
353
+ use_os_path_sep = true
354
+ substitutions = { "/Volumes/network/path" = "/net" }
355
+
356
+ [git_branch]
357
+ truncation_length = 0 # pi-starship's bounded no-truncation sentinel
358
+ truncation_symbol = "…"
359
+
360
+ [git_commit]
361
+ commit_hash_length = 7
362
+
363
+ [conda]
364
+ ignore_base = true
365
+ truncation_length = 1
366
+
367
+ [hostname]
368
+ trim_at = "." # set to "" to keep the complete hostname
369
+ ```
370
+
371
+ Directory `$path` contracts the home directory and, by default, the current Git repository root
372
+ before retaining the last three path components. `$full_path` remains the unmodified absolute cwd.
373
+ A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no
374
+ substitution is configured. `substitutions` is an ordered TOML string table of literal replacements.
375
+ Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement
376
+ Starship's regex substitution array or repo-root-specific split style/format fields. Directory
377
+ rendering reads only immutable home and repository-root snapshot data and performs no filesystem or
378
+ Git work.
379
+
380
+ Git branch truncation retains the first `N` grapheme clusters and appends the first grapheme of
381
+ `truncation_symbol` only when truncation occurs. The same rule applies independently to `$branch`,
382
+ `$remote_name`, and `$remote_branch`. Upstream Starship represents its unlimited default as
383
+ `2^63 - 1`; pi-starship uses `0` for the same behavior because its settings integers are deliberately
384
+ bounded. `commit_hash_length` accepts 0 through 64.
233
385
 
234
- The model module accepts Starship-style `truncation_length` and `truncation_symbol` options plus the
235
- Pi-specific `truncation_direction` option:
386
+ Conda retains the last path component by default; `0` keeps the complete environment path. Hostname
387
+ trimming runs before exact alias lookup, matching Starship. These are display transformations only:
388
+ collectors retain bounded, control-sanitized source metadata.
389
+
390
+ ### Model aliases and truncation
391
+
392
+ The model module accepts exact `model_aliases`, Starship-style `truncation_length` and
393
+ `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
236
394
 
237
395
  ```toml
238
396
  [model]
397
+ model_aliases = { "/models/Qwen3.6-35B-Q4.gguf" = "Qwen 35B Q4" }
239
398
  truncation_length = 36
240
399
  truncation_symbol = "…"
241
400
  truncation_direction = "middle"
242
401
  ```
243
402
 
244
- `truncation_length` counts model grapheme clusters retained before the symbol; `0` disables
403
+ An exact alias is selected before the built-in Claude/GPT shortening rules, then the resulting label
404
+ is subject to the configured truncation. `truncation_length` counts model grapheme clusters retained
405
+ before the symbol; `0` disables
245
406
  truncation and is the default. The direction names the removed portion: `start` retains the suffix,
246
- `end` retains the prefix and is the default, and `middle` retains both ends. Truncation runs after the
247
- built-in Claude/GPT shortening rules and changes display only—the provider model ID is untouched.
407
+ `end` retains the prefix and is the default, and `middle` retains both ends. When no alias matches,
408
+ truncation runs after the built-in Claude/GPT shortening rules. It always changes display only—the
409
+ provider model ID is untouched.
248
410
  Terminal control sequences in model IDs and truncation symbols are removed at render time. An empty
249
411
  symbol truncates without a marker. For example, `middle` can retain both a Hugging Face model
250
412
  family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
@@ -309,8 +471,10 @@ disable or remove that extension when adopting the native module to avoid duplic
309
471
 
310
472
  ### 📦 Package and language modules
311
473
 
312
- The native behavior is inspired by Starship pinned at
313
- `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; it is not complete Starship compatibility.
474
+ Module behavior is inspired by Starship pinned at
475
+ `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved
476
+ multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`. This is not
477
+ complete Starship module or configuration compatibility.
314
478
 
315
479
  | Area | Adopted | Adapted | Intentionally omitted |
316
480
  | --- | --- | --- | --- |
@@ -429,12 +593,21 @@ Package's explicitly documented Cargo lookup is the only ancestor walk and is ca
429
593
  | `/starship status` | Show config source/path and diagnostics |
430
594
  | `/starship help` | Show command and configuration help |
431
595
 
432
- The standard main menu keeps frequent goals visible: **Customize footer**, **Check configuration**,
433
- and **Help**. It shows whether the footer uses the built-in or custom document and displays the
434
- current warning count. **Advanced** contains uncommon details and the confirmed restore action, with
435
- an explicit **Back** path. The TOML editor and live footer previews remain specialized extension UI.
596
+ The standard main menu keeps six goals on one level: **Customize footer**, **Explain footer**,
597
+ **Modules**, **Configuration**, **Help**, and **Restore built-in…**. It shows whether the footer uses
598
+ built-in defaults, a saved built-in document, a custom document, or an error-driven fallback,
599
+ together with the current health. Explain and Modules are menu-only read paths; they do not add
600
+ textual subcommands or change RPC, print, or JSON protocols. Restore remains last and unavailable
601
+ when there is no document to replace.
602
+
603
+ The TOML editor, adaptive live footer previews, Explain view, and searchable module inspector remain
604
+ specialized extension UI. Their hints follow Pi's injected keybindings; list and detail content stay
605
+ bounded across terminal resize. Escape returns from detail or to the main menu, while Ctrl+C closes
606
+ the whole workflow.
436
607
 
437
- Status and help remain safe in TUI, RPC, JSON, and print modes. RPC receives notifications but never opens custom terminal UI; print and JSON modes produce no ad hoc output. Footer/timer/Git lifecycle work starts only in TUI mode.
608
+ The direct routes accept no trailing arguments. Status and help remain safe in TUI, RPC, JSON, and
609
+ print modes. RPC receives notifications but never opens custom terminal UI; print and JSON modes
610
+ produce no ad hoc output. Footer/timer/Git lifecycle work starts only in TUI mode.
438
611
 
439
612
  ## 📐 Scope
440
613
 
@@ -460,7 +633,9 @@ Keep `extension_status` last in the catalog so arbitrary third-party statuses fo
460
633
  - `src/index.ts` — Pi package entrypoint.
461
634
  - `src/pi-starship.ts` — extension lifecycle, cached refresh binding, live preview, and footer.
462
635
  - `src/usage.ts` — native-aligned session usage and cache aggregation.
463
- - `src/commands.ts` — goal-oriented menu, preview/confirmation, diagnostics, and compatibility routes.
636
+ - `src/commands.ts` — goal-oriented menu, preview/confirmation flow, diagnostics, and compatibility routes.
637
+ - `src/command-inspector.ts` — adaptive Explain and searchable read-only module inspection surfaces.
638
+ - `src/command-preview.ts` — adaptive, scrollable, keybinding-aware preview action surface.
464
639
  - `src/config.ts` — TOML loading, draft validation, defaults, atomic persistence, and rollback.
465
640
  - `src/format/` — native format/style parser and renderer.
466
641
  - `src/modules/` — domain module definitions, ordered registry, reachability, and width-aware renderer.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-starship",
3
- "version": "0.44.0",
3
+ "version": "0.46.0",
4
4
  "description": "Native Starship-style TOML statusline for the Pi coding agent.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,7 +31,7 @@
31
31
  "typecheck": "tsc --noEmit"
32
32
  },
33
33
  "dependencies": {
34
- "@narumitw/pi-tui-kit": "^0.40.0",
34
+ "@narumitw/pi-tui-kit": "^0.45.0",
35
35
  "smol-toml": "^1.7.1",
36
36
  "yaml": "^2.9.0"
37
37
  },
@@ -0,0 +1,198 @@
1
+ import { stripVTControlCharacters } from "node:util";
2
+ import type { ExtensionCommandContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
3
+ import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
4
+ import type { StatuslineInspection } from "./modules/inspection.js";
5
+
6
+ const RESERVED_HOST_ROWS = 3;
7
+
8
+ export type InspectorResult = { kind: "back" } | { kind: "close" };
9
+
10
+ export function showFooterExplanation(
11
+ ctx: ExtensionCommandContext,
12
+ inspection: StatuslineInspection | undefined,
13
+ signal?: AbortSignal,
14
+ ): Promise<InspectorResult | undefined> {
15
+ if (signal?.aborted) return Promise.resolve({ kind: "close" });
16
+ return ctx.ui.custom<InspectorResult | undefined>((tui, theme, keybindings, done) => {
17
+ let scrollOffset = 0;
18
+ let lastMaximumScroll = 0;
19
+ let lastViewportSize = 1;
20
+ let disposed = false;
21
+ let settled = false;
22
+ let deferredAbort: ReturnType<typeof setImmediate> | undefined;
23
+ const finish = (result: InspectorResult) => {
24
+ if (disposed || settled) return;
25
+ settled = true;
26
+ done(result);
27
+ };
28
+ const closeForAbort = () => finish({ kind: "close" });
29
+ signal?.addEventListener("abort", closeForAbort, { once: true });
30
+ if (signal?.aborted) deferredAbort = setImmediate(closeForAbort);
31
+
32
+ return {
33
+ focused: false,
34
+ render(width: number): string[] {
35
+ const safeWidth = Math.max(1, width);
36
+ const availableRows = componentRows(tui.terminal.rows);
37
+ const content = explanationLines(inspection, safeWidth);
38
+ const layout = detailLayout(availableRows, content.length);
39
+ lastViewportSize = layout.contentRows;
40
+ lastMaximumScroll = Math.max(0, content.length - layout.contentRows);
41
+ scrollOffset = clamp(scrollOffset, 0, lastMaximumScroll);
42
+ const lines = [
43
+ ...(layout.titleRows ? [theme.fg("accent", theme.bold("Explain footer"))] : []),
44
+ ...content.slice(scrollOffset, scrollOffset + layout.contentRows),
45
+ ...(layout.positionRows
46
+ ? [theme.fg("dim", positionText(scrollOffset, layout.contentRows, content.length))]
47
+ : []),
48
+ ...(layout.hintRows ? [theme.fg("dim", detailHint(keybindings, "back"))] : []),
49
+ ];
50
+ return boundedLines(lines, safeWidth, availableRows);
51
+ },
52
+ invalidate() {},
53
+ handleInput(data: string) {
54
+ if (disposed || settled) return;
55
+ if (matchesKey(data, Key.ctrl("c"))) finish({ kind: "close" });
56
+ else if (keybindings.matches(data, "tui.select.cancel")) finish({ kind: "back" });
57
+ else if (keybindings.matches(data, "tui.select.up")) {
58
+ scrollOffset = clamp(scrollOffset - 1, 0, lastMaximumScroll);
59
+ } else if (keybindings.matches(data, "tui.select.down")) {
60
+ scrollOffset = clamp(scrollOffset + 1, 0, lastMaximumScroll);
61
+ } else if (keybindings.matches(data, "tui.select.pageUp")) {
62
+ scrollOffset = clamp(scrollOffset - lastViewportSize, 0, lastMaximumScroll);
63
+ } else if (keybindings.matches(data, "tui.select.pageDown")) {
64
+ scrollOffset = clamp(scrollOffset + lastViewportSize, 0, lastMaximumScroll);
65
+ } else if (matchesKey(data, Key.home)) scrollOffset = 0;
66
+ else if (matchesKey(data, Key.end)) scrollOffset = lastMaximumScroll;
67
+ tui.requestRender();
68
+ },
69
+ dispose() {
70
+ if (disposed) return;
71
+ disposed = true;
72
+ if (deferredAbort) clearImmediate(deferredAbort);
73
+ deferredAbort = undefined;
74
+ signal?.removeEventListener("abort", closeForAbort);
75
+ },
76
+ };
77
+ });
78
+ }
79
+
80
+ function explanationLines(inspection: StatuslineInspection | undefined, width: number): string[] {
81
+ if (!inspection) {
82
+ return wrapLines(
83
+ [
84
+ "Footer inspection is unavailable until the TUI footer is ready.",
85
+ "No collection work was started.",
86
+ ],
87
+ width,
88
+ );
89
+ }
90
+ if (inspection.showing.length === 0) {
91
+ return wrapLines(
92
+ [
93
+ "No modules are currently showing.",
94
+ "Open Modules to inspect empty, disabled, or unreachable modules.",
95
+ ],
96
+ width,
97
+ );
98
+ }
99
+ const lines = inspection.showing.flatMap((module, index) => [
100
+ ...(index > 0 ? [""] : []),
101
+ module.name,
102
+ ...previewLines(module.preview),
103
+ module.description,
104
+ ]);
105
+ return wrapLines(lines, width);
106
+ }
107
+
108
+ function previewLines(preview: string): string[] {
109
+ const lines = preview ? preview.split("\n") : ["(no text)"];
110
+ return lines.map((line, index) => `${index === 0 ? "Value: " : " "}${line}`);
111
+ }
112
+
113
+ function wrapLines(lines: readonly string[], width: number): string[] {
114
+ return lines.flatMap((line) => {
115
+ const safe = safeDisplayText(line);
116
+ return safe ? wrapTextWithAnsi(safe, width) : [""];
117
+ });
118
+ }
119
+
120
+ interface DetailLayout {
121
+ titleRows: number;
122
+ contentRows: number;
123
+ positionRows: number;
124
+ hintRows: number;
125
+ }
126
+
127
+ function detailLayout(availableRows: number, contentLength: number): DetailLayout {
128
+ if (availableRows === 1) {
129
+ return { titleRows: 0, contentRows: 1, positionRows: 0, hintRows: 0 };
130
+ }
131
+ const titleRows = availableRows >= 4 ? 1 : 0;
132
+ const hintRows = availableRows >= 3 ? 1 : 0;
133
+ let contentRows = Math.max(1, availableRows - titleRows - hintRows);
134
+ const positionRows = contentLength > contentRows && contentRows >= 2 ? 1 : 0;
135
+ contentRows -= positionRows;
136
+ return { titleRows, contentRows, positionRows, hintRows };
137
+ }
138
+
139
+ function componentRows(rows: number): number {
140
+ const terminalRows = Number.isFinite(rows) ? Math.floor(rows) : 24;
141
+ return Math.max(1, terminalRows - RESERVED_HOST_ROWS);
142
+ }
143
+
144
+ function positionText(offset: number, viewportSize: number, itemCount: number): string {
145
+ if (itemCount === 0) return "0/0";
146
+ return `${offset + 1}-${Math.min(itemCount, offset + viewportSize)}/${itemCount}`;
147
+ }
148
+
149
+ function boundedLines(lines: readonly string[], width: number, rows: number): string[] {
150
+ return lines.slice(0, rows).map((line) => truncateToWidth(line, width, ""));
151
+ }
152
+
153
+ function detailHint(
154
+ keybindings: Pick<KeybindingsManager, "getKeys">,
155
+ destination: "back" | "close",
156
+ ): string {
157
+ const up = bindingText(keybindings, "tui.select.up");
158
+ const down = bindingText(keybindings, "tui.select.down");
159
+ const cancel = bindingText(keybindings, "tui.select.cancel", "ctrl+c");
160
+ const pageUp = bindingText(keybindings, "tui.select.pageUp");
161
+ const pageDown = bindingText(keybindings, "tui.select.pageDown");
162
+ return [
163
+ ...(up || down ? [`${[up, down].filter(Boolean).join("/")} scroll`] : []),
164
+ ...(pageUp || pageDown ? [`${[pageUp, pageDown].filter(Boolean).join("/")} page`] : []),
165
+ ...(cancel ? [`${cancel} ${destination}`] : []),
166
+ "ctrl+c close",
167
+ ].join(" • ");
168
+ }
169
+
170
+ function bindingText(
171
+ keybindings: Pick<KeybindingsManager, "getKeys">,
172
+ binding: Parameters<KeybindingsManager["getKeys"]>[0],
173
+ excluded?: string,
174
+ ): string {
175
+ return keybindings
176
+ .getKeys(binding)
177
+ .filter((key) => key !== excluded)
178
+ .map((key) => {
179
+ if (key === "up") return "↑";
180
+ if (key === "down") return "↓";
181
+ if (key === "escape") return "esc";
182
+ if (key === "return") return "enter";
183
+ return safeDisplayText(key);
184
+ })
185
+ .filter(Boolean)
186
+ .join("/");
187
+ }
188
+
189
+ function safeDisplayText(value: string): string {
190
+ return Array.from(stripVTControlCharacters(value), (character) => {
191
+ const codePoint = character.codePointAt(0) ?? 0;
192
+ return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f) ? "" : character;
193
+ }).join("");
194
+ }
195
+
196
+ function clamp(value: number, minimum: number, maximum: number): number {
197
+ return Math.max(minimum, Math.min(value, maximum));
198
+ }