@narumitw/pi-starship 0.44.0 β†’ 0.45.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 (40) hide show
  1. package/README.md +188 -65
  2. package/package.json +2 -2
  3. package/src/command-inspector.ts +470 -0
  4. package/src/command-preview.ts +206 -0
  5. package/src/commands.ts +168 -158
  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 +1 -1
  15. package/src/modules/directory.ts +1 -1
  16. package/src/modules/display.ts +14 -0
  17. package/src/modules/execution.ts +12 -1
  18. package/src/modules/extension-status.ts +1 -1
  19. package/src/modules/fill.ts +1 -1
  20. package/src/modules/git/branch.ts +1 -1
  21. package/src/modules/git/commit.ts +1 -1
  22. package/src/modules/git/metrics.ts +8 -2
  23. package/src/modules/git/state.ts +1 -1
  24. package/src/modules/git/status.ts +1 -1
  25. package/src/modules/git/worktree.ts +1 -1
  26. package/src/modules/github-pr.ts +1 -1
  27. package/src/modules/index.ts +13 -1
  28. package/src/modules/inspection.ts +138 -0
  29. package/src/modules/model.ts +1 -1
  30. package/src/modules/provider.ts +1 -1
  31. package/src/modules/render.ts +22 -3
  32. package/src/modules/thinking.ts +1 -1
  33. package/src/modules/time.ts +1 -1
  34. package/src/modules/tokens.ts +1 -1
  35. package/src/modules/turn.ts +1 -1
  36. package/src/modules/types.ts +19 -0
  37. package/src/pi-starship.ts +21 -0
  38. package/src/runtime/execution.ts +15 -3
  39. package/src/runtime/types.ts +2 -0
  40. 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.
195
+
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`:
161
199
 
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.
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,11 +329,10 @@ 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.
@@ -309,8 +419,10 @@ disable or remove that extension when adopting the native module to avoid duplic
309
419
 
310
420
  ### πŸ“¦ Package and language modules
311
421
 
312
- The native behavior is inspired by Starship pinned at
313
- `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; it is not complete Starship compatibility.
422
+ Module behavior is inspired by Starship pinned at
423
+ `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved
424
+ multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`. This is not
425
+ complete Starship module or configuration compatibility.
314
426
 
315
427
  | Area | Adopted | Adapted | Intentionally omitted |
316
428
  | --- | --- | --- | --- |
@@ -429,12 +541,21 @@ Package's explicitly documented Cargo lookup is the only ancestor walk and is ca
429
541
  | `/starship status` | Show config source/path and diagnostics |
430
542
  | `/starship help` | Show command and configuration help |
431
543
 
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.
544
+ The standard main menu keeps six goals on one level: **Customize footer**, **Explain footer**,
545
+ **Modules**, **Configuration**, **Help**, and **Restore built-in…**. It shows whether the footer uses
546
+ built-in defaults, a saved built-in document, a custom document, or an error-driven fallback,
547
+ together with the current health. Explain and Modules are menu-only read paths; they do not add
548
+ textual subcommands or change RPC, print, or JSON protocols. Restore remains last and unavailable
549
+ when there is no document to replace.
550
+
551
+ The TOML editor, adaptive live footer previews, Explain view, and searchable module inspector remain
552
+ specialized extension UI. Their hints follow Pi's injected keybindings; list and detail content stay
553
+ bounded across terminal resize. Escape returns from detail or to the main menu, while Ctrl+C closes
554
+ the whole workflow.
436
555
 
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.
556
+ The direct routes accept no trailing arguments. Status and help remain safe in TUI, RPC, JSON, and
557
+ print modes. RPC receives notifications but never opens custom terminal UI; print and JSON modes
558
+ produce no ad hoc output. Footer/timer/Git lifecycle work starts only in TUI mode.
438
559
 
439
560
  ## πŸ“ Scope
440
561
 
@@ -460,7 +581,9 @@ Keep `extension_status` last in the catalog so arbitrary third-party statuses fo
460
581
  - `src/index.ts` β€” Pi package entrypoint.
461
582
  - `src/pi-starship.ts` β€” extension lifecycle, cached refresh binding, live preview, and footer.
462
583
  - `src/usage.ts` β€” native-aligned session usage and cache aggregation.
463
- - `src/commands.ts` β€” goal-oriented menu, preview/confirmation, diagnostics, and compatibility routes.
584
+ - `src/commands.ts` β€” goal-oriented menu, preview/confirmation flow, diagnostics, and compatibility routes.
585
+ - `src/command-inspector.ts` β€” adaptive Explain and searchable read-only module inspection surfaces.
586
+ - `src/command-preview.ts` β€” adaptive, scrollable, keybinding-aware preview action surface.
464
587
  - `src/config.ts` β€” TOML loading, draft validation, defaults, atomic persistence, and rollback.
465
588
  - `src/format/` β€” native format/style parser and renderer.
466
589
  - `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.45.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.43.0",
35
35
  "smol-toml": "^1.7.1",
36
36
  "yaml": "^2.9.0"
37
37
  },