@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.
- package/README.md +246 -71
- package/package.json +2 -2
- package/src/command-inspector.ts +198 -0
- package/src/command-preview.ts +206 -0
- package/src/commands.ts +190 -154
- 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 +24 -7
- package/src/modules/directory.ts +141 -7
- package/src/modules/display.ts +14 -0
- package/src/modules/execution.ts +13 -2
- package/src/modules/extension-status.ts +1 -1
- package/src/modules/fill.ts +1 -1
- package/src/modules/git/branch.ts +14 -5
- package/src/modules/git/commit.ts +10 -3
- package/src/modules/git/metrics.ts +8 -2
- package/src/modules/git/runtime.ts +3 -0
- 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 +15 -65
- package/src/modules/provider.ts +1 -1
- package/src/modules/render.ts +22 -3
- package/src/modules/terminal.ts +60 -0
- package/src/modules/thinking.ts +1 -1
- package/src/modules/time.ts +1 -1
- package/src/modules/tokens.ts +1 -1
- package/src/modules/truncation.ts +37 -0
- package/src/modules/turn.ts +1 -1
- package/src/modules/types.ts +22 -0
- package/src/pi-starship.ts +27 -1
- package/src/runtime/development.ts +1 -2
- package/src/runtime/execution.ts +19 -9
- 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.
|
|
161
195
|
|
|
162
|
-
|
|
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
|
|
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.
|
|
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
|
-
###
|
|
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
|
-
|
|
235
|
-
|
|
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
|
-
|
|
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.
|
|
247
|
-
built-in Claude/GPT shortening rules
|
|
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
|
-
|
|
313
|
-
`9f4d07ed45804e280d6884bb8ced7ea3d3033093`;
|
|
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
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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
|
+
}
|