@narumitw/pi-starship 0.43.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 +274 -89
- package/package.json +2 -2
- package/src/command-inspector.ts +470 -0
- package/src/command-preview.ts +206 -0
- package/src/commands.ts +187 -152
- package/src/config.ts +177 -67
- 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 +65 -4
- 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 +7 -98
- package/src/modules/fill.ts +1 -1
- package/src/modules/git/branch.ts +3 -37
- package/src/modules/git/commit.ts +1 -1
- package/src/modules/git/metrics.ts +8 -2
- package/src/modules/git/runtime.ts +5 -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 +24 -0
- package/src/modules/index.ts +15 -6
- 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 +23 -19
- 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 +32 -5
- package/src/pi-starship.ts +149 -27
- package/src/runtime/command.ts +46 -8
- package/src/runtime/execution.ts +15 -3
- package/src/runtime/github-pr.ts +332 -0
- package/src/runtime/helpers.ts +1 -0
- package/src/runtime/refresh-controller.ts +30 -8
- package/src/runtime/types.ts +4 -0
- package/src/runtime/workspace.ts +27 -10
- package/src/installed-packages.ts +0 -84
package/README.md
CHANGED
|
@@ -8,15 +8,17 @@ 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
|
+
- Native current-branch GitHub pull request links, checks, review state, and terminal-state retention.
|
|
15
16
|
- Opt-in package, language, development-shell, deployment, cloud, and execution-context modules.
|
|
16
17
|
- Width-aware `$fill` alignment for native multiline left/right layouts.
|
|
17
18
|
- Footer rendering is pure: no subprocess, network, filesystem, timer, or environment work runs from `render()`.
|
|
18
19
|
- Multiline output wraps to the terminal width instead of truncating.
|
|
19
|
-
- Goal-oriented `/starship` menu with
|
|
20
|
+
- Goal-oriented `/starship` menu with footer explanation, searchable module inspection,
|
|
21
|
+
configuration health, transactional preview, and recovery.
|
|
20
22
|
|
|
21
23
|
## π¦ Install
|
|
22
24
|
|
|
@@ -30,7 +32,7 @@ Try it from a checkout:
|
|
|
30
32
|
pi -e ./extensions/pi-starship
|
|
31
33
|
```
|
|
32
34
|
|
|
33
|
-
Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer
|
|
35
|
+
Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
|
|
34
36
|
|
|
35
37
|
## βοΈ Configuration
|
|
36
38
|
|
|
@@ -40,7 +42,11 @@ The only configuration source is:
|
|
|
40
42
|
<getAgentDir()>/pi-starship.toml
|
|
41
43
|
```
|
|
42
44
|
|
|
43
|
-
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.
|
|
44
50
|
|
|
45
51
|
The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
|
|
46
52
|
|
|
@@ -50,82 +56,116 @@ Open the interactive menu in TUI mode:
|
|
|
50
56
|
/starship
|
|
51
57
|
```
|
|
52
58
|
|
|
53
|
-
Choose **Customize footer** to edit the TOML. Closing the editor validates the draft and opens
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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.
|
|
58
83
|
|
|
59
84
|
### π Example
|
|
60
85
|
|
|
61
86
|
```toml
|
|
62
|
-
format = "
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
87
|
+
format = """
|
|
88
|
+
$brand\
|
|
89
|
+
$model\
|
|
90
|
+
$thinking\
|
|
91
|
+
$directory\
|
|
92
|
+
$git_branch\
|
|
93
|
+
$git_status\
|
|
94
|
+
$activity\
|
|
95
|
+
$context\
|
|
96
|
+
$time"""
|
|
69
97
|
|
|
70
98
|
[model]
|
|
71
99
|
format = "[ $symbol$model ]($style)"
|
|
72
100
|
symbol = "β "
|
|
73
|
-
style = "bold
|
|
74
|
-
disabled = false
|
|
101
|
+
style = "bold blue"
|
|
75
102
|
truncation_length = 36
|
|
76
103
|
truncation_symbol = "β¦"
|
|
77
104
|
truncation_direction = "middle"
|
|
78
105
|
|
|
79
|
-
[
|
|
80
|
-
|
|
81
|
-
|
|
106
|
+
[directory]
|
|
107
|
+
style = "cyan bold"
|
|
108
|
+
|
|
109
|
+
[git_branch]
|
|
110
|
+
style = "bold purple"
|
|
82
111
|
|
|
83
112
|
[context]
|
|
84
113
|
format = "[$symbol $percentage/$window ]($style)"
|
|
85
114
|
|
|
86
|
-
[
|
|
87
|
-
|
|
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"
|
|
88
138
|
disabled = false
|
|
89
139
|
|
|
90
|
-
[
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
[git_branch]
|
|
94
|
-
format = "[ $symbol$branch$pr ]($style)"
|
|
95
|
-
|
|
96
|
-
[package]
|
|
97
|
-
version_format = "v$raw"
|
|
98
|
-
|
|
99
|
-
[nodejs]
|
|
100
|
-
detect_files = ["package.json", "!deno.json"]
|
|
101
|
-
detect_extensions = ["js", "ts"]
|
|
102
|
-
|
|
103
|
-
[hostname]
|
|
104
|
-
ssh_only = true
|
|
105
|
-
trim_at = "."
|
|
106
|
-
aliases = { "build.example.test" = "builder" }
|
|
140
|
+
[username]
|
|
141
|
+
style_user = "yellow bold"
|
|
142
|
+
style_root = "red bold"
|
|
107
143
|
|
|
108
144
|
[extension_status]
|
|
109
145
|
format = "([$statuses ]($style))"
|
|
110
|
-
icons = { "
|
|
146
|
+
icons = { "foo:*" = "π§ͺ", "third_party/key" = "β", fallback = "β’" }
|
|
111
147
|
```
|
|
112
148
|
|
|
113
|
-
|
|
114
|
-
|
|
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.
|
|
115
153
|
Version formats replace `$raw`. Detection arrays replace defaults when non-empty and inspect only one
|
|
116
154
|
listing of the current directory. A leading `!` is supported by language detection arrays and rejects
|
|
117
155
|
a matching project.
|
|
118
|
-
`[extension_status].icons` accepts arbitrary exact Pi status keys
|
|
119
|
-
wildcards such as `foo
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
`<extension-id
|
|
127
|
-
|
|
128
|
-
|
|
156
|
+
`[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace
|
|
157
|
+
wildcards such as `foo:*`; `fallback` controls unmatched statuses. Icon matching uses the exact key,
|
|
158
|
+
the longest `:*` wildcard, a leading status emoji, then `fallback`/`π`. An empty configured icon
|
|
159
|
+
suppresses only the icon. `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
|
|
160
|
+
|
|
161
|
+
Pi does not expose which package owns a status, so exact raw keys are the reliable third-party
|
|
162
|
+
contract. pi-starship does not inspect installed packages, infer package aliases, assign icons to
|
|
163
|
+
known extensions, or bridge compatibility keys. Extension authors may adopt `<extension-id>` or
|
|
164
|
+
`<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require that convention.
|
|
165
|
+
|
|
166
|
+
**Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons,
|
|
167
|
+
or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a
|
|
168
|
+
leading emoji in the status value, or `fallback`.
|
|
129
169
|
|
|
130
170
|
## π§© Format grammar
|
|
131
171
|
|
|
@@ -146,11 +186,91 @@ Style expressions support:
|
|
|
146
186
|
- Hex RGB (`#7aa2f7`).
|
|
147
187
|
- `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
|
|
148
188
|
- `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
|
|
149
|
-
- `none
|
|
150
|
-
- `
|
|
151
|
-
-
|
|
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`:
|
|
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.
|
|
152
224
|
|
|
153
|
-
|
|
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.
|
|
154
274
|
|
|
155
275
|
## π§± Modules
|
|
156
276
|
|
|
@@ -162,7 +282,8 @@ An invalid root format falls back to the built-in root format. An invalid module
|
|
|
162
282
|
| `thinking` | `$symbol`, `$level` | Thinking level |
|
|
163
283
|
| `directory` | `$symbol`, `$path`, `$full_path` | Current working directory |
|
|
164
284
|
| `git_worktree` | `$symbol`, `$name`, `$path` | Linked worktree name and top-level path |
|
|
165
|
-
| `git_branch` | `$symbol`, `$branch`, `$remote_name`, `$remote_branch
|
|
285
|
+
| `git_branch` | `$symbol`, `$branch`, `$remote_name`, `$remote_branch` | Local branch and upstream |
|
|
286
|
+
| `github_pr` | `$symbol`, `$number`, `$link`, `$state`, `$checks`, `$review`, `$status` | Current-branch GitHub pull request |
|
|
166
287
|
| `git_commit` | `$symbol`, `$hash`, `$tag` | Seven-character HEAD hash and optional exact tag |
|
|
167
288
|
| `git_state` | `$symbol`, `$state`, `$progress_current`, `$progress_total` | Rebase, merge, revert, cherry-pick, bisect, or mail-apply state |
|
|
168
289
|
| `git_metrics` | `$symbol`, `$added`, `$deleted` | Added/deleted line totals from the working tree diff |
|
|
@@ -208,11 +329,10 @@ An invalid root format falls back to the built-in root format. An invalid module
|
|
|
208
329
|
- Cache `$read` and `$write` are cumulative. `$rate` uses only the latest assistant prompt:
|
|
209
330
|
`cacheRead / (input + cacheRead + cacheWrite) * 100`. The module is empty when Pi has reported no
|
|
210
331
|
cache reads or writes.
|
|
211
|
-
- `cache` is disabled
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
`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
|
|
216
336
|
`context`, not `context_usage`.
|
|
217
337
|
- Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`. The dollar
|
|
218
338
|
value is usage cost, not proof of an amount billed under a subscription.
|
|
@@ -248,12 +368,61 @@ truncation-direction setting.
|
|
|
248
368
|
|
|
249
369
|
`git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format. Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default. `$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
|
|
250
370
|
|
|
251
|
-
|
|
371
|
+
### π Native GitHub pull requests
|
|
372
|
+
|
|
373
|
+
`$github_pr` is independent of `pi-github-pr`; installing that extension is not required. It runs one
|
|
374
|
+
bounded GitHub CLI query for the current branch:
|
|
375
|
+
|
|
376
|
+
```text
|
|
377
|
+
gh pr view --json number,isDraft,url,state,closedAt,mergedAt,reviewDecision,statusCheckRollup
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
Install and authenticate `gh` first:
|
|
381
|
+
|
|
382
|
+
```bash
|
|
383
|
+
gh auth login
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository
|
|
387
|
+
remote, for example `gh auth login --hostname github.example.com`. pi-starship starts `gh` directly
|
|
388
|
+
with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves
|
|
389
|
+
the correct repository and host from the current checkout. It never mutates Pi's environment, calls
|
|
390
|
+
the GitHub API directly, or manages tokens.
|
|
391
|
+
|
|
392
|
+
Variables have these values:
|
|
393
|
+
|
|
394
|
+
- `$number`: digits such as `123`.
|
|
395
|
+
- `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL, otherwise plain `#123`.
|
|
396
|
+
- `$state`: `open`, `draft`, `merged`, or `closed`.
|
|
397
|
+
- `$checks`: `checks passing`, `<n> failing`, `<n> pending`, or `no checks`.
|
|
398
|
+
- `$review`: `approved`, `changes requested`, `review required`, or empty when unknown.
|
|
399
|
+
- `$status`: one compact result selected in this order: merged, closed, draft, failing, changes
|
|
400
|
+
requested, pending, approved, review required, passing, then no checks.
|
|
401
|
+
|
|
402
|
+
The query runs only in TUI sessions when the enabled module is reachable from the root format. It
|
|
403
|
+
refreshes at session start, immediately after a branch change, after each agent run, after accepted
|
|
404
|
+
settings changes, and every 60 seconds. Each query has a 10-second timeout. Branch changes clear the
|
|
405
|
+
old PR before querying the new branch. Closed and merged PRs remain visible for 24 hours, then expire
|
|
406
|
+
without waiting for the next refresh. Missing `gh`, missing authentication, no current PR, timeout,
|
|
407
|
+
malformed or oversized output, and network failures all render an empty module without exposing raw
|
|
408
|
+
errors or credentials.
|
|
409
|
+
|
|
410
|
+
The query sends the repository/current-branch context through authenticated `gh` to the GitHub host
|
|
411
|
+
configured by the repository. It requests only the fields aboveβnever comments, review bodies,
|
|
412
|
+
inline comments, or review threads. Footer rendering and previews read only the immutable cached
|
|
413
|
+
snapshot and perform no network or subprocess work.
|
|
414
|
+
|
|
415
|
+
**Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic
|
|
416
|
+
migration. Replace it with root `$github_pr` and an optional `[github_pr]` table. If `pi-github-pr`
|
|
417
|
+
remains installed, its independent `github-pr` status can also appear under `$extension_status`;
|
|
418
|
+
disable or remove that extension when adopting the native module to avoid duplicate information.
|
|
252
419
|
|
|
253
420
|
### π¦ Package and language modules
|
|
254
421
|
|
|
255
|
-
|
|
256
|
-
`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.
|
|
257
426
|
|
|
258
427
|
| Area | Adopted | Adapted | Intentionally omitted |
|
|
259
428
|
| --- | --- | --- | --- |
|
|
@@ -346,19 +515,22 @@ whole-catalog layout is intended. There is no `line_break` module; use literal n
|
|
|
346
515
|
|
|
347
516
|
### π Cached refresh lifecycle
|
|
348
517
|
|
|
349
|
-
Workspace and
|
|
350
|
-
format reachability, `$all`, module `disabled`, and module-format variables determine
|
|
351
|
-
requirements.
|
|
352
|
-
completion, and a 30-second fallback.
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
518
|
+
Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled
|
|
519
|
+
modules. Root format reachability, `$all`, module `disabled`, and module-format variables determine
|
|
520
|
+
file and command requirements. Workspace/Git refreshes run at session start, after accepted settings,
|
|
521
|
+
branch changes, tool/turn completion, and a 30-second fallback. GitHub PR uses the narrower lifecycle
|
|
522
|
+
and 60-second network refresh described above. One read runs with at most one latest pending refresh;
|
|
523
|
+
immutable snapshot equality suppresses redraws, and session/request generations reject stale results.
|
|
524
|
+
Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command
|
|
525
|
+
work before starting replacements; disabling `github_pr` also stops its query and timers. Bounded local
|
|
526
|
+
filesystem operations may finish, but stale generations cannot publish them. Execution identity is
|
|
527
|
+
retained rather than re-read by the periodic fallback. Render and live preview consume snapshots
|
|
528
|
+
synchronously and perform zero reads or commands.
|
|
357
529
|
|
|
358
530
|
Missing, unreadable, malformed, oversized, timed-out, or unavailable sources fail to empty values.
|
|
359
|
-
|
|
360
|
-
no network calls.
|
|
361
|
-
at eight parents.
|
|
531
|
+
Workspace/Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never
|
|
532
|
+
recurse, and make no network calls. The native GitHub PR query is the documented network exception.
|
|
533
|
+
Package's explicitly documented Cargo lookup is the only ancestor walk and is capped at eight parents.
|
|
362
534
|
|
|
363
535
|
## π¬ Commands
|
|
364
536
|
|
|
@@ -369,12 +541,21 @@ at eight parents.
|
|
|
369
541
|
| `/starship status` | Show config source/path and diagnostics |
|
|
370
542
|
| `/starship help` | Show command and configuration help |
|
|
371
543
|
|
|
372
|
-
The standard main menu keeps
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
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.
|
|
376
555
|
|
|
377
|
-
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.
|
|
378
559
|
|
|
379
560
|
## π Scope
|
|
380
561
|
|
|
@@ -393,24 +574,28 @@ modules until separately approved semantics exist.
|
|
|
393
574
|
|
|
394
575
|
Create `src/modules/<name>.ts` with its format variables, defaults, and runtime value resolver, then register it in display order in `src/modules/catalog.ts`. Configuration names, validation variables, defaults, and `$all` ordering are derived from that catalog. Add the module to the built-in root format when it should be visible by default, then document and test its user-facing values.
|
|
395
576
|
|
|
396
|
-
Keep `extension_status` last in the catalog so
|
|
577
|
+
Keep `extension_status` last in the catalog so arbitrary third-party statuses follow native module output.
|
|
397
578
|
|
|
398
579
|
## ποΈ Package layout
|
|
399
580
|
|
|
400
581
|
- `src/index.ts` β Pi package entrypoint.
|
|
401
582
|
- `src/pi-starship.ts` β extension lifecycle, cached refresh binding, live preview, and footer.
|
|
402
583
|
- `src/usage.ts` β native-aligned session usage and cache aggregation.
|
|
403
|
-
- `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.
|
|
404
587
|
- `src/config.ts` β TOML loading, draft validation, defaults, atomic persistence, and rollback.
|
|
405
588
|
- `src/format/` β native format/style parser and renderer.
|
|
406
589
|
- `src/modules/` β domain module definitions, ordered registry, reachability, and width-aware renderer.
|
|
407
|
-
- `src/modules/git/` β bounded Git reader plus branch, status, and worktree modules.
|
|
590
|
+
- `src/modules/git/` β bounded local Git reader plus branch, status, and worktree modules.
|
|
591
|
+
- `src/modules/github-pr.ts` β pure native GitHub PR snapshot presentation.
|
|
592
|
+
- `src/runtime/github-pr.ts` β bounded `gh` query, validation, terminal-safe links, and expiry data.
|
|
408
593
|
- `src/runtime/` β shared refresh controller and bounded package/language/context collectors.
|
|
409
594
|
|
|
410
595
|
## π Keywords
|
|
411
596
|
|
|
412
|
-
Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline,
|
|
413
|
-
cache hit rate, Pi extension
|
|
597
|
+
Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, GitHub pull
|
|
598
|
+
request, prompt cache, cache hit rate, Pi extension
|
|
414
599
|
|
|
415
600
|
## π License
|
|
416
601
|
|
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
|
},
|