@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.
- package/README.md +188 -65
- package/package.json +2 -2
- package/src/command-inspector.ts +470 -0
- package/src/command-preview.ts +206 -0
- package/src/commands.ts +168 -158
- package/src/config.ts +177 -68
- package/src/format/style.ts +64 -45
- package/src/modules/activity.ts +1 -1
- package/src/modules/brand.ts +1 -1
- package/src/modules/cache.ts +1 -1
- package/src/modules/catalog.ts +62 -3
- package/src/modules/context.ts +13 -1
- package/src/modules/cost.ts +12 -1
- package/src/modules/development.ts +1 -1
- package/src/modules/directory.ts +1 -1
- package/src/modules/display.ts +14 -0
- package/src/modules/execution.ts +12 -1
- package/src/modules/extension-status.ts +1 -1
- package/src/modules/fill.ts +1 -1
- package/src/modules/git/branch.ts +1 -1
- package/src/modules/git/commit.ts +1 -1
- package/src/modules/git/metrics.ts +8 -2
- package/src/modules/git/state.ts +1 -1
- package/src/modules/git/status.ts +1 -1
- package/src/modules/git/worktree.ts +1 -1
- package/src/modules/github-pr.ts +1 -1
- package/src/modules/index.ts +13 -1
- package/src/modules/inspection.ts +138 -0
- package/src/modules/model.ts +1 -1
- package/src/modules/provider.ts +1 -1
- package/src/modules/render.ts +22 -3
- package/src/modules/thinking.ts +1 -1
- package/src/modules/time.ts +1 -1
- package/src/modules/tokens.ts +1 -1
- package/src/modules/turn.ts +1 -1
- package/src/modules/types.ts +19 -0
- package/src/pi-starship.ts +21 -0
- package/src/runtime/execution.ts +15 -3
- package/src/runtime/types.ts +2 -0
- 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
|
|
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
|
|
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
|
|
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
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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 = "
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
|
75
|
-
disabled = false
|
|
101
|
+
style = "bold blue"
|
|
76
102
|
truncation_length = 36
|
|
77
103
|
truncation_symbol = "β¦"
|
|
78
104
|
truncation_direction = "middle"
|
|
79
105
|
|
|
80
|
-
[
|
|
81
|
-
|
|
82
|
-
|
|
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
|
-
[
|
|
88
|
-
|
|
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
|
-
[
|
|
92
|
-
|
|
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
|
-
|
|
121
|
-
|
|
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
|
|
159
|
-
- `
|
|
160
|
-
-
|
|
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
|
-
|
|
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
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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
|
-
|
|
313
|
-
`9f4d07ed45804e280d6884bb8ced7ea3d3033093`;
|
|
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
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
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
|
|
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.
|
|
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.
|
|
34
|
+
"@narumitw/pi-tui-kit": "^0.43.0",
|
|
35
35
|
"smol-toml": "^1.7.1",
|
|
36
36
|
"yaml": "^2.9.0"
|
|
37
37
|
},
|