@narumitw/pi-starship 0.51.4 β 0.52.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 -300
- package/dist/chunks/chunk-2BNGNI6Y.ts +10 -0
- package/dist/chunks/chunk-2BNGNI6Y.ts.map +7 -0
- package/dist/chunks/chunk-GS2UE7CF.ts +2446 -0
- package/dist/chunks/chunk-GS2UE7CF.ts.map +7 -0
- package/dist/chunks/chunk-PV5KIAAP.ts +218 -0
- package/dist/chunks/chunk-PV5KIAAP.ts.map +7 -0
- package/dist/chunks/cloud-RFUL56GP.ts +142 -0
- package/dist/chunks/cloud-RFUL56GP.ts.map +7 -0
- package/dist/chunks/commands-X3VM2UGT.ts +1917 -0
- package/dist/chunks/commands-X3VM2UGT.ts.map +7 -0
- package/dist/chunks/deployment-RDEDDCLG.ts +172 -0
- package/dist/chunks/deployment-RDEDDCLG.ts.map +7 -0
- package/dist/chunks/development-N7EARF34.ts +132 -0
- package/dist/chunks/development-N7EARF34.ts.map +7 -0
- package/dist/chunks/execution-YGXH4DK6.ts +132 -0
- package/dist/chunks/execution-YGXH4DK6.ts.map +7 -0
- package/dist/chunks/languages-RGO3PWDR.ts +184 -0
- package/dist/chunks/languages-RGO3PWDR.ts.map +7 -0
- package/dist/chunks/package-WM7PK5OH.ts +104 -0
- package/dist/chunks/package-WM7PK5OH.ts.map +7 -0
- package/dist/index.ts +1333 -0
- package/dist/index.ts.map +7 -0
- package/package.json +10 -6
- package/src/command-configuration.ts +363 -0
- package/src/commands.ts +33 -97
- package/src/effective-config.ts +65 -0
- package/src/pi-starship.ts +4 -0
package/README.md
CHANGED
|
@@ -1,25 +1,23 @@
|
|
|
1
|
-
# π pi-starship β
|
|
1
|
+
# π pi-starship β Build Pi's Footer with Starship-style TOML
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-starship) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Build a deeply customizable Pi footer with Starship-style TOML, native Pi modules, conditional formats, palettes, and responsive multiline layout.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
No `starship` executable or shell prompt is required because this extension parses and renders the footer itself.
|
|
8
|
+
|
|
9
|
+
> **Different package:** The unscoped npm package `pi-starship` delegates to the Starship binary.
|
|
10
|
+
> This package is `@narumitw/pi-starship` and renders Pi-specific modules natively.
|
|
8
11
|
|
|
9
12
|
## β¨ Features
|
|
10
13
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
- Pi
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
- Footer rendering is pure: no subprocess, network, filesystem, timer, or environment work runs from `render()`.
|
|
19
|
-
- Multiline output wraps to the terminal width instead of truncating.
|
|
20
|
-
- Goal-oriented `/starship` menu with every Starship 1.26 preset style plus a Pi-native Minimal
|
|
21
|
-
preset, footer explanation, searchable module inspection, configuration health, transactional
|
|
22
|
-
preview, and recovery.
|
|
14
|
+
- Starts with a readable built-in footer and offers Starship presets plus a Pi-native Minimal preset.
|
|
15
|
+
- Supports root and module formats, conditional groups, `$all`, styles, palettes, and width-aware `$fill` alignment.
|
|
16
|
+
- Provides Pi, model, usage, Git, pull request, package, language, environment, deployment, cloud, and execution modules.
|
|
17
|
+
- Wraps native multiline layouts to terminal width instead of truncating them.
|
|
18
|
+
- Keeps rendering pure while refreshing filesystem, process, and network-derived data through bounded caches.
|
|
19
|
+
- Uses `/starship` for presets, preview, configuration health, searchable module details, customization, and recovery.
|
|
20
|
+
- Loads a generated split runtime to reduce Pi package startup work.
|
|
23
21
|
|
|
24
22
|
## π¦ Install
|
|
25
23
|
|
|
@@ -27,15 +25,29 @@ A native Pi footer configured with Starship-style TOML. It parses and renders fo
|
|
|
27
25
|
pi install npm:@narumitw/pi-starship
|
|
28
26
|
```
|
|
29
27
|
|
|
30
|
-
Try
|
|
28
|
+
Try the published package without installing it permanently:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pi -e npm:@narumitw/pi-starship
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Build the generated runtime and try the local package from this repository:
|
|
31
35
|
|
|
32
36
|
```bash
|
|
33
|
-
|
|
37
|
+
npm --workspace @narumitw/pi-starship run build
|
|
38
|
+
pi -e ./packages/pi-starship
|
|
34
39
|
```
|
|
35
40
|
|
|
41
|
+
The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
|
|
42
|
+
|
|
36
43
|
Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
|
|
37
44
|
|
|
38
|
-
##
|
|
45
|
+
## π Quick start
|
|
46
|
+
|
|
47
|
+
Start Pi with the extension to use the built-in footer without creating a settings file.
|
|
48
|
+
Run `/starship` to inspect the footer, choose a preset, or customize the configuration.
|
|
49
|
+
|
|
50
|
+
## βοΈ Settings
|
|
39
51
|
|
|
40
52
|
The only configuration source is:
|
|
41
53
|
|
|
@@ -43,11 +55,10 @@ The only configuration source is:
|
|
|
43
55
|
<getAgentDir()>/pi-starship.toml
|
|
44
56
|
```
|
|
45
57
|
|
|
46
|
-
When this file is absent, the extension uses its readable palette-free default without creating the
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
overwritten.
|
|
58
|
+
When this file is absent, the extension uses its readable palette-free default without creating the file or parent directory.
|
|
59
|
+
The built-in root is the explicit sequence `$brand$model$thinking$directory` `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query.
|
|
60
|
+
The first successful settings save creates the file atomically.
|
|
61
|
+
Existing malformed documents are never overwritten.
|
|
51
62
|
|
|
52
63
|
The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
|
|
53
64
|
|
|
@@ -57,38 +68,37 @@ Open the interactive menu in TUI mode:
|
|
|
57
68
|
/starship
|
|
58
69
|
```
|
|
59
70
|
|
|
60
|
-
Choose **Customize footer** to edit the TOML.
|
|
61
|
-
adaptive, scrollable preview whose **Apply changesβ¦**, **Continue editing**, and **Discard draft**
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
on the next `session_start`, including `/reload` and session replacement.
|
|
65
|
-
cancellation, component disposal, invalid drafts, write failures, and runtime application failures
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
backup before asking for confirmation.
|
|
71
|
+
Choose **Customize footer** to edit the TOML.
|
|
72
|
+
Closing the editor validates the draft and opens an adaptive, scrollable preview whose **Apply changesβ¦**, **Continue editing**, and **Discard draft** actions remain reachable in short or narrow terminals.
|
|
73
|
+
Saving happens only after a separate confirmation.
|
|
74
|
+
Confirmed changes are atomically saved and applied immediately.
|
|
75
|
+
Manual TOML edits load on the next `session_start`, including `/reload` and session replacement.
|
|
76
|
+
Editor cancellation, preview cancellation, component disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and effective footer.
|
|
77
|
+
|
|
78
|
+
The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-inβ¦**.
|
|
79
|
+
Explain footer uses the current immutable runtime snapshot to list each currently showing non-empty module once with its rendered value and description; it starts no new collection work.
|
|
80
|
+
Modules opens a bounded searchable inspector for every registered module.
|
|
81
|
+
Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
|
|
82
|
+
Module detail shows the current preview when available, description, root reference and reachability, format variables, style fields, display rules, and the known reason for absent output.
|
|
83
|
+
Both views are read-only and never create or update the settings document.
|
|
84
|
+
|
|
85
|
+
Configuration contains **Overview**, **Effective configuration**, **Settings document**, and **Reload from disk** on one nested level.
|
|
86
|
+
Overview combines state, source, path, health, and bounded diagnostics.
|
|
87
|
+
Effective configuration shows deterministic catalog-ordered public TOML from the normalized state currently in use; comments, unknown fields, parser ASTs, and private runtime selectors are excluded.
|
|
88
|
+
Settings document shows the exact loaded UTF-8 text through a terminal-safe, cell-aware read-only review without changing the raw payload.
|
|
89
|
+
A healthy missing file is shown as **Built-in defaults**, an exact bundled document is shown as its named preset, and **Built-in fallback** is reserved for read or parse errors.
|
|
90
|
+
Reload from disk reads only after the explicit action, validates and previews the current external state from the existing runtime snapshot, and asks for separate confirmation before changing the active session.
|
|
91
|
+
A deleted document is a valid previewable transition to built-in defaults and creates no file.
|
|
92
|
+
An unchanged document is a no-op, while read or parse failure, cancellation, disposal, external changes after preview, session replacement, shutdown, or runtime apply failure preserves the prior effective footer and every file byte.
|
|
93
|
+
Reload re-reads immediately after confirmation and rejects a different external snapshot; it does not claim cross-process locking or continuing synchronization with later edits.
|
|
94
|
+
Restore is disabled when no settings document exists or the exact built-in document is already saved.
|
|
95
|
+
For a custom or invalid document, Restore previews the result and warns that the complete document, including custom settings, unknown fields, and comments, will be replaced without a post-success backup before asking for confirmation.
|
|
85
96
|
|
|
86
97
|
### ποΈ Presets
|
|
87
98
|
|
|
88
|
-
Choose **Presets** from `/starship` to browse complete Pi-native starting points.
|
|
89
|
-
all styles listed by `starship preset --list` in Starship 1.26.0, plus a Pi-specific Minimal option.
|
|
90
|
-
Colors, separators, typography, and layout follow the named Starship preset; modules are deliberately
|
|
91
|
-
selected for Pi's model, thinking, workspace, Git, activity, context, and time snapshots.
|
|
99
|
+
Choose **Presets** from `/starship` to browse complete Pi-native starting points.
|
|
100
|
+
The catalog adapts all styles listed by `starship preset --list` in Starship 1.26.0, plus a Pi-specific Minimal option.
|
|
101
|
+
Colors, separators, typography, and layout follow the named Starship preset; modules are deliberately selected for Pi's model, thinking, workspace, Git, activity, context, and time snapshots.
|
|
92
102
|
|
|
93
103
|
| Preset | Adapted visual treatment | Font requirement |
|
|
94
104
|
| --- | --- | --- |
|
|
@@ -106,25 +116,21 @@ selected for Pi's model, thinking, workspace, Git, activity, context, and time s
|
|
|
106
116
|
| **Pure Preset** | Clean two-line workspace and session context | Standard Unicode |
|
|
107
117
|
| **Tokyo Night** | Connected cool blue Tokyo Night blocks | Nerd Font |
|
|
108
118
|
|
|
109
|
-
The preset cursor is a live footer preview.
|
|
110
|
-
Home, or End temporarily renders the selected preset in the actual footer without writing settings or
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors. They are
|
|
125
|
-
Pi-native adaptations of the color and format treatments emitted by Starship 1.26.0; they do not copy
|
|
126
|
-
Starship's module selections because Pi exposes different runtime information. There is no
|
|
127
|
-
`/starship preset` textual route and no remote preset download.
|
|
119
|
+
The preset cursor is a live footer preview.
|
|
120
|
+
Opening the picker and moving with Up/Down, Page Up/Down, Home, or End temporarily renders the selected preset in the actual footer without writing settings or starting new collectors.
|
|
121
|
+
Press Enter to start the named preset's replacement confirmation, or press `e` to customize the selected complete TOML document before its normal editor preview and confirmation.
|
|
122
|
+
Escape returns to the main menu, while Ctrl+C closes the complete workflow; both restore the previously effective footer.
|
|
123
|
+
|
|
124
|
+
Presets are complete documents, not overlays.
|
|
125
|
+
Applying one replaces `pi-starship.toml`, including custom settings, unknown fields, and comments, only after a separate confirmation; no post-success backup is kept.
|
|
126
|
+
Cursor movement, confirmation cancellation, disposal, validation failure, write failure, and runtime-apply failure retain the previous valid document and effective footer.
|
|
127
|
+
Exact unedited matches are shown as **Currently applied** and cannot be redundantly selected; editing any byte makes the document custom again.
|
|
128
|
+
**Restore built-inβ¦** remains the deterministic recovery path.
|
|
129
|
+
|
|
130
|
+
The bundled presets use only pi-starship's local Pi and Git snapshot modules.
|
|
131
|
+
They do not enable the GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors.
|
|
132
|
+
They are Pi-native adaptations of the color and format treatments emitted by Starship 1.26.0; they do not copy Starship's module selections because Pi exposes different runtime information.
|
|
133
|
+
There is no `/starship preset` textual route and no remote preset download.
|
|
128
134
|
|
|
129
135
|
### π Example
|
|
130
136
|
|
|
@@ -191,37 +197,35 @@ format = "([$statuses ]($style))"
|
|
|
191
197
|
icons = { "foo:*" = "π§ͺ", "third_party/key" = "β", fallback = "β’" }
|
|
192
198
|
```
|
|
193
199
|
|
|
194
|
-
Every module table supports `format`, `symbol`, and `disabled`.
|
|
195
|
-
|
|
196
|
-
`style_root`), and the threshold-selected `context` and `cost` `display` arrays described below.
|
|
200
|
+
Every module table supports `format`, `symbol`, and `disabled`.
|
|
201
|
+
Most modules also support one `style`.
|
|
202
|
+
The exceptions are `git_metrics` (`added_style` and `deleted_style`), `username` (`style_user` and `style_root`), and the threshold-selected `context` and `cost` `display` arrays described below.
|
|
197
203
|
Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
|
|
198
|
-
Version formats replace `$raw`.
|
|
199
|
-
|
|
200
|
-
a matching project.
|
|
201
|
-
`[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
Pi does not expose which package owns a status, so exact raw keys are the reliable third-party
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
**Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons,
|
|
212
|
-
or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a
|
|
213
|
-
leading emoji in the status value, or `fallback`.
|
|
204
|
+
Version formats replace `$raw`.
|
|
205
|
+
Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
|
|
206
|
+
A leading `!` is supported by language detection arrays and rejects a matching project.
|
|
207
|
+
`[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
|
|
208
|
+
Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`π`.
|
|
209
|
+
An empty configured icon suppresses only the icon.
|
|
210
|
+
`foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
|
|
211
|
+
|
|
212
|
+
Pi does not expose which package owns a status, so exact raw keys are the reliable third-party contract. pi-starship does not inspect installed packages, infer package aliases, assign icons to known extensions, or bridge compatibility keys.
|
|
213
|
+
Extension authors may adopt `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require that convention.
|
|
214
|
+
|
|
215
|
+
**Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons, or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a leading emoji in the status value, or `fallback`.
|
|
214
216
|
|
|
215
217
|
## π§© Format grammar
|
|
216
218
|
|
|
217
|
-
- Variables: `$name` and `${name}`.
|
|
219
|
+
- Variables: `$name` and `${name}`.
|
|
220
|
+
Unknown variables render empty and produce a warning when loaded from TOML.
|
|
218
221
|
- Escapes: `\\$`, `\\[`, `\\]`, `\\(`, `\\)`, and `\\\\` render functional characters literally.
|
|
219
222
|
- Styled groups: `[format string](style string)`.
|
|
220
223
|
- Conditional groups: `(format string)` render only when a nested variable has a non-empty value.
|
|
221
224
|
- Nested groups are supported.
|
|
222
225
|
- `$all` expands enabled modules in the default order and omits modules already referenced explicitly.
|
|
223
226
|
|
|
224
|
-
Module formats can use `$style` in a style expression.
|
|
227
|
+
Module formats can use `$style` in a style expression.
|
|
228
|
+
Module output keeps its own style when embedded in an outer styled group.
|
|
225
229
|
|
|
226
230
|
## π¨ Styles and palettes
|
|
227
231
|
|
|
@@ -232,15 +236,13 @@ Style expressions support:
|
|
|
232
236
|
- `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
|
|
233
237
|
- `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
|
|
234
238
|
- `none` and `fg:none`, which make the complete expression unstyled regardless of position.
|
|
235
|
-
- `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same
|
|
236
|
-
|
|
237
|
-
- `prev_fg` and `prev_bg`, which use the previous rendered chunk's colors when present and retain any
|
|
238
|
-
absolute foreground/background in the expression as the no-previous fallback.
|
|
239
|
+
- `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same Starship-compatible reset behavior.
|
|
240
|
+
- `prev_fg` and `prev_bg`, which use the previous rendered chunk's colors when present and retain any absolute foreground/background in the expression as the no-previous fallback.
|
|
239
241
|
- Direct color names from one explicitly selected `[palettes.<name>]` table.
|
|
240
242
|
|
|
241
|
-
There is no built-in or fallback palette.
|
|
242
|
-
selected, and its values must be direct named, ANSI, or RGB colorsβpalette entries cannot reference
|
|
243
|
-
|
|
243
|
+
There is no built-in or fallback palette.
|
|
244
|
+
A custom palette is active only when its table is explicitly selected, and its values must be direct named, ANSI, or RGB colorsβpalette entries cannot reference other entries.
|
|
245
|
+
Palette names override terminal color names such as `blue`:
|
|
244
246
|
|
|
245
247
|
```toml
|
|
246
248
|
palette = "company"
|
|
@@ -254,29 +256,24 @@ style = "bold blue"
|
|
|
254
256
|
```
|
|
255
257
|
|
|
256
258
|
Style tokens are case-insensitive and ordinary foreground/background colors are last-wins.
|
|
257
|
-
`prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists.
|
|
258
|
-
groups still advance previous-color state.
|
|
259
|
-
|
|
260
|
-
catalog-owned style field falls back only at that field's module scope.
|
|
261
|
-
warnings.
|
|
262
|
-
|
|
263
|
-
The background-free direct defaults are: `brand = "bold white"`, `provider`/`model` = `"bold blue"`,
|
|
264
|
-
`thinking`/`git_branch`/`turn` = `"bold purple"`, `directory`/`git_worktree` = `"cyan bold"`,
|
|
265
|
-
`github_pr = "bold blue"`, `git_commit = "green bold"`, `git_state`/`activity`/`time` =
|
|
266
|
-
`"bold yellow"`, `git_status = "red bold"`, `tokens = "bold cyan"`, `cache = "bold green"`,
|
|
267
|
-
`extension_status = "dimmed white"`, `direnv = "bold bright-yellow"`, and `fill = "bold black"`.
|
|
259
|
+
`prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists.
|
|
260
|
+
Empty styled groups still advance previous-color state.
|
|
261
|
+
Invalid literal style expressions warn and render unstyled.
|
|
262
|
+
An invalid root format falls back to the built-in root format; an invalid module format or catalog-owned style field falls back only at that field's module scope.
|
|
263
|
+
`/starship status` reports warnings.
|
|
264
|
+
|
|
265
|
+
The background-free direct defaults are: `brand = "bold white"`, `provider`/`model` = `"bold blue"`, `thinking`/`git_branch`/`turn` = `"bold purple"`, `directory`/`git_worktree` = `"cyan bold"`, `github_pr = "bold blue"`, `git_commit = "green bold"`, `git_state`/`activity`/`time` = `"bold yellow"`, `git_status = "red bold"`, `tokens = "bold cyan"`, `cache = "bold green"`, `extension_status = "dimmed white"`, `direnv = "bold bright-yellow"`, and `fill = "bold black"`.
|
|
268
266
|
Context, cost, Git metrics, and username use the state/multi-style defaults below.
|
|
269
267
|
|
|
270
268
|
### State-selected styles
|
|
271
269
|
|
|
272
|
-
`context` and `cost` select the last entry at the highest threshold less than or equal to the current
|
|
273
|
-
|
|
274
|
-
a valid `style`, and boolean `hidden`.
|
|
275
|
-
if none remain.
|
|
270
|
+
`context` and `cost` select the last entry at the highest threshold less than or equal to the current value.
|
|
271
|
+
A later entry wins when thresholds are equal.
|
|
272
|
+
Each display entry requires a finite `threshold`, a valid `style`, and boolean `hidden`.
|
|
273
|
+
Invalid entries warn and are ignored; module defaults are used if none remain.
|
|
276
274
|
|
|
277
|
-
The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and
|
|
278
|
-
|
|
279
|
-
at `5`:
|
|
275
|
+
The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and `bold red` at `80`.
|
|
276
|
+
The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red` at `5`:
|
|
280
277
|
|
|
281
278
|
```toml
|
|
282
279
|
[[cost.display]]
|
|
@@ -295,25 +292,20 @@ style = "bold red"
|
|
|
295
292
|
hidden = false
|
|
296
293
|
```
|
|
297
294
|
|
|
298
|
-
`git_metrics` exposes `$added_style` and `$deleted_style` in its module format.
|
|
299
|
-
`$style` in its format, but selects `style_user` or `style_root` from private execution metadata; the
|
|
300
|
-
selector is not a format variable.
|
|
295
|
+
`git_metrics` exposes `$added_style` and `$deleted_style` in its module format.
|
|
296
|
+
`username` still uses `$style` in its format, but selects `style_user` or `style_root` from private execution metadata; the selector is not a format variable.
|
|
301
297
|
|
|
302
298
|
### Breaking palette migration
|
|
303
299
|
|
|
304
|
-
The previous implicit `tokyo-night` palette and its `lead`, `header`, `header_fg`, `directory`,
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
the module's new direct-color default; alias-based literal Powerline groups warn and render unstyled.
|
|
300
|
+
The previous implicit `tokyo-night` palette and its `lead`, `header`, `header_fg`, `directory`, `directory_fg`, `git`, `git_fg`, `runtime`, `runtime_fg`, `meter`, `meter_fg`, and `extension` aliases were removed.
|
|
301
|
+
Existing files are not rewritten.
|
|
302
|
+
Old alias-based module styles warn and fall back to the module's new direct-color default; alias-based literal Powerline groups warn and render unstyled.
|
|
308
303
|
|
|
309
304
|
Choose one migration:
|
|
310
305
|
|
|
311
|
-
1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
`palette = "<name>"`.
|
|
315
|
-
3. Use **Restore built-inβ¦** from `/starship` to review and replace the complete document with the new
|
|
316
|
-
plain nine-module configuration.
|
|
306
|
+
1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or `fg:#e3e5e5 bg:#769ff0`.
|
|
307
|
+
2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with `palette = "<name>"`.
|
|
308
|
+
3. Use **Restore built-inβ¦** from `/starship` to review and replace the complete document with the new plain nine-module configuration.
|
|
317
309
|
|
|
318
310
|
There is no hidden compatibility overlay or automatic migration.
|
|
319
311
|
|
|
@@ -368,21 +360,20 @@ There is no hidden compatibility overlay or automatic migration.
|
|
|
368
360
|
|
|
369
361
|
### Usage semantics
|
|
370
362
|
|
|
371
|
-
- `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer
|
|
372
|
-
assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
`context`, not `context_usage`.
|
|
382
|
-
- Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
|
|
383
|
-
value is usage cost, not proof of an amount billed under a subscription.
|
|
384
|
-
- Pi's public extension API does not expose the current auto-compaction toggle, so pi-starship cannot
|
|
385
|
-
reliably provide the native `(auto)` marker.
|
|
363
|
+
- `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer.
|
|
364
|
+
This includes assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned branches retained in the session.
|
|
365
|
+
- Cache `$read` and `$write` are cumulative.
|
|
366
|
+
`$rate` uses only the latest assistant prompt with `cacheRead / (input + cacheRead + cacheWrite) * 100`.
|
|
367
|
+
The module is empty when Pi has reported no cache reads or writes.
|
|
368
|
+
- `cache` is disabled and absent from the built-in root.
|
|
369
|
+
Enable it and add `$cache` to a custom root format (or use `$all`) to display it.
|
|
370
|
+
- Context `$percentage` uses native one-decimal precision.
|
|
371
|
+
Its default display hides values below 30%.
|
|
372
|
+
Customize `[[context.display]]` when lower values should remain visible.
|
|
373
|
+
The module name remains `context`, not `context_usage`.
|
|
374
|
+
- Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
|
|
375
|
+
The dollar value is usage cost, not proof of an amount billed under a subscription.
|
|
376
|
+
- Pi's public extension API does not expose the current auto-compaction toggle, so pi-starship cannot reliably provide the native `(auto)` marker.
|
|
386
377
|
|
|
387
378
|
### Directory, Git, and environment contraction
|
|
388
379
|
|
|
@@ -413,29 +404,26 @@ truncation_length = 1
|
|
|
413
404
|
trim_at = "." # set to "" to keep the complete hostname
|
|
414
405
|
```
|
|
415
406
|
|
|
416
|
-
Directory `$path` contracts the home directory and, by default, the current Git repository root
|
|
417
|
-
|
|
418
|
-
A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no
|
|
419
|
-
|
|
420
|
-
Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
Git
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
`
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
trimming runs before exact alias lookup, matching Starship. These are display transformations only:
|
|
433
|
-
collectors retain bounded, control-sanitized source metadata.
|
|
407
|
+
Directory `$path` contracts the home directory and, by default, the current Git repository root before retaining the last three path components.
|
|
408
|
+
`$full_path` remains the unmodified absolute cwd.
|
|
409
|
+
A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no substitution is configured.
|
|
410
|
+
`substitutions` is an ordered TOML string table of literal replacements.
|
|
411
|
+
Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement Starship's regex substitution array or repo-root-specific split style/format fields.
|
|
412
|
+
Directory rendering reads only immutable home and repository-root snapshot data and performs no filesystem or Git work.
|
|
413
|
+
|
|
414
|
+
Git branch truncation retains the first `N` grapheme clusters and appends the first grapheme of `truncation_symbol` only when truncation occurs.
|
|
415
|
+
The same rule applies independently to `$branch`, `$remote_name`, and `$remote_branch`.
|
|
416
|
+
Upstream Starship represents its unlimited default as `2^63 - 1`; pi-starship uses `0` for the same behavior because its settings integers are deliberately bounded.
|
|
417
|
+
`commit_hash_length` accepts 0 through 64.
|
|
418
|
+
|
|
419
|
+
Conda retains the last path component by default; `0` keeps the complete environment path.
|
|
420
|
+
Hostname trimming runs before exact alias lookup, matching Starship.
|
|
421
|
+
These transformations affect display only.
|
|
422
|
+
Collectors retain bounded, control-sanitized source metadata.
|
|
434
423
|
|
|
435
424
|
### Model aliases and truncation
|
|
436
425
|
|
|
437
|
-
The model module accepts exact `model_aliases`, Starship-style `truncation_length` and
|
|
438
|
-
`truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
|
|
426
|
+
The model module accepts exact `model_aliases`, Starship-style `truncation_length` and `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
|
|
439
427
|
|
|
440
428
|
```toml
|
|
441
429
|
[model]
|
|
@@ -445,30 +433,29 @@ truncation_symbol = "β¦"
|
|
|
445
433
|
truncation_direction = "middle"
|
|
446
434
|
```
|
|
447
435
|
|
|
448
|
-
An exact alias is selected before the built-in Claude/GPT shortening rules, then the resulting label
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
|
|
458
|
-
pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes,
|
|
459
|
-
or quantization names.
|
|
436
|
+
An exact alias is selected before the built-in Claude/GPT shortening rules, then the resulting label is subject to the configured truncation.
|
|
437
|
+
`truncation_length` counts model grapheme clusters retained before the symbol; `0` disables truncation and is the default.
|
|
438
|
+
The direction names the removed portion: `start` retains the suffix, `end` retains the prefix and is the default, and `middle` retains both ends.
|
|
439
|
+
When no alias matches, truncation runs after the built-in Claude/GPT shortening rules.
|
|
440
|
+
It always changes display onlyβthe provider model ID is untouched.
|
|
441
|
+
Terminal control sequences in model IDs and truncation symbols are removed at render time.
|
|
442
|
+
An empty symbol truncates without a marker.
|
|
443
|
+
For example, `middle` can retain both a Hugging Face model family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
|
|
444
|
+
pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names.
|
|
460
445
|
|
|
461
|
-
`truncation_direction` is a pi-starship adaptation; upstream Starship has no model module or generic
|
|
462
|
-
truncation-direction setting.
|
|
446
|
+
`truncation_direction` is a pi-starship adaptation; upstream Starship has no model module or generic truncation-direction setting.
|
|
463
447
|
|
|
464
|
-
`git_worktree` is empty in the primary worktree.
|
|
448
|
+
`git_worktree` is empty in the primary worktree.
|
|
449
|
+
In a linked worktree it defaults to the top-level directory name; use `$path` when the full absolute path is needed.
|
|
465
450
|
|
|
466
|
-
`git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format.
|
|
451
|
+
`git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format.
|
|
452
|
+
Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default.
|
|
453
|
+
`$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
|
|
467
454
|
|
|
468
455
|
### π Native GitHub pull requests
|
|
469
456
|
|
|
470
|
-
`$github_pr` is independent of `pi-github-pr`; installing that extension is not required.
|
|
471
|
-
bounded GitHub CLI query for the current branch:
|
|
457
|
+
`$github_pr` is independent of `pi-github-pr`; installing that extension is not required.
|
|
458
|
+
It runs one bounded GitHub CLI query for the current branch:
|
|
472
459
|
|
|
473
460
|
```text
|
|
474
461
|
gh pr view --json number,isDraft,url,state,closedAt,mergedAt,reviewDecision,statusCheckRollup
|
|
@@ -480,11 +467,8 @@ Install and authenticate `gh` first:
|
|
|
480
467
|
gh auth login
|
|
481
468
|
```
|
|
482
469
|
|
|
483
|
-
For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository
|
|
484
|
-
|
|
485
|
-
with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves
|
|
486
|
-
the correct repository and host from the current checkout. It never mutates Pi's environment, calls
|
|
487
|
-
the GitHub API directly, or manages tokens.
|
|
470
|
+
For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository remote, for example `gh auth login --hostname github.example.com`. pi-starship starts `gh` directly with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves the correct repository and host from the current checkout.
|
|
471
|
+
It never mutates Pi's environment, calls the GitHub API directly, or manages tokens.
|
|
488
472
|
|
|
489
473
|
Variables have these values:
|
|
490
474
|
|
|
@@ -492,10 +476,8 @@ Variables have these values:
|
|
|
492
476
|
- `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL, otherwise plain `#123`.
|
|
493
477
|
- `$state`: `open`, `draft`, `merged`, or `closed`.
|
|
494
478
|
- `$checks`: all non-zero check counts in passed, failed, pending order, or `-` when no checks exist.
|
|
495
|
-
- `$review`: `Rβ` for approved, `RΓ` for changes requested, `R?` for review required, or empty
|
|
496
|
-
|
|
497
|
-
- `$status`: one result selected in this order: merged, closed, draft, failing checks, changes
|
|
498
|
-
requested, pending checks, approved, review required, passing checks, then no checks.
|
|
479
|
+
- `$review`: `Rβ` for approved, `RΓ` for changes requested, `R?` for review required, or empty when unknown.
|
|
480
|
+
- `$status`: one result selected in this order: merged, closed, draft, failing checks, changes requested, pending checks, approved, review required, passing checks, then no checks.
|
|
499
481
|
|
|
500
482
|
The compact symbols are font-safe and distinct from Git's default `$`, `!`, and `?` worktree markers:
|
|
501
483
|
|
|
@@ -518,8 +500,7 @@ PR #123 Β· Rβ
|
|
|
518
500
|
PR #123 Β· M
|
|
519
501
|
```
|
|
520
502
|
|
|
521
|
-
Use the existing `$checks` and `$review` variables together when every check category and the review
|
|
522
|
-
result should remain visible:
|
|
503
|
+
Use the existing `$checks` and `$review` variables together when every check category and the review result should remain visible:
|
|
523
504
|
|
|
524
505
|
```toml
|
|
525
506
|
[github_pr]
|
|
@@ -544,30 +525,26 @@ This is a breaking display migration for custom formats that use these variables
|
|
|
544
525
|
The old English values have no verbose aliases.
|
|
545
526
|
The variable names and default module format remain unchanged, so no TOML field migration is needed.
|
|
546
527
|
|
|
547
|
-
The query runs only in TUI sessions when the enabled module is reachable from the root format.
|
|
548
|
-
refreshes at session start, immediately after a branch change, after each agent run, after accepted
|
|
549
|
-
|
|
550
|
-
old PR before querying the new branch.
|
|
551
|
-
|
|
552
|
-
malformed or oversized output, and network failures all render an empty module without exposing raw
|
|
553
|
-
errors or credentials.
|
|
528
|
+
The query runs only in TUI sessions when the enabled module is reachable from the root format.
|
|
529
|
+
It refreshes at session start, immediately after a branch change, after each agent run, after accepted settings changes, and every 60 seconds.
|
|
530
|
+
Each query has a 10-second timeout.
|
|
531
|
+
Branch changes clear the old PR before querying the new branch.
|
|
532
|
+
Closed and merged PRs remain visible for 24 hours, then expire without waiting for the next refresh.
|
|
533
|
+
Missing `gh`, missing authentication, no current PR, timeout, malformed or oversized output, and network failures all render an empty module without exposing raw errors or credentials.
|
|
554
534
|
|
|
555
|
-
The query sends the repository/current-branch context through authenticated `gh` to the GitHub host
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
snapshot and perform no network or subprocess work.
|
|
535
|
+
The query sends the repository/current-branch context through authenticated `gh` to the GitHub host configured by the repository.
|
|
536
|
+
It requests only the fields aboveβnever comments, review bodies, inline comments, or review threads.
|
|
537
|
+
Footer rendering and previews read only the immutable cached snapshot and perform no network or subprocess work.
|
|
559
538
|
|
|
560
|
-
**Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic
|
|
561
|
-
|
|
562
|
-
remains installed, its independent `github-pr` status can also appear under `$extension_status
|
|
563
|
-
|
|
539
|
+
**Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic migration.
|
|
540
|
+
Replace it with root `$github_pr` and an optional `[github_pr]` table.
|
|
541
|
+
If `pi-github-pr` remains installed, its independent `github-pr` status can also appear under `$extension_status`.
|
|
542
|
+
Disable or remove that extension when adopting the native module to avoid duplicate information.
|
|
564
543
|
|
|
565
544
|
### π¦ Package and language modules
|
|
566
545
|
|
|
567
|
-
Module behavior is inspired by Starship pinned at
|
|
568
|
-
|
|
569
|
-
multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`. This is not
|
|
570
|
-
complete Starship module or configuration compatibility.
|
|
546
|
+
Module behavior is inspired by Starship pinned at `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`.
|
|
547
|
+
This is not complete Starship module or configuration compatibility.
|
|
571
548
|
|
|
572
549
|
| Area | Adopted | Adapted | Intentionally omitted |
|
|
573
550
|
| --- | --- | --- | --- |
|
|
@@ -579,10 +556,9 @@ complete Starship module or configuration compatibility.
|
|
|
579
556
|
| Bun / Deno | Direct markers and `bun --version` / `deno -V` | Negative detection avoids overlapping Node defaults | Runtime installation and recursive source detection |
|
|
580
557
|
|
|
581
558
|
All runtime commands use argv execution in `ctx.cwd`, a 2-second timeout, and 64 KiB accepted output.
|
|
582
|
-
Commands run only when the reachable module format references the command-backed variable.
|
|
583
|
-
killed, oversized, or malformed commands clear that value independently.
|
|
584
|
-
`detect_files`, `detect_extensions`, and `detect_folders` are available on language modules; package
|
|
585
|
-
supports `version_format`.
|
|
559
|
+
Commands run only when the reachable module format references the command-backed variable.
|
|
560
|
+
Missing, killed, oversized, or malformed commands clear that value independently.
|
|
561
|
+
`version_format`, `detect_files`, `detect_extensions`, and `detect_folders` are available on language modules; package supports `version_format`.
|
|
586
562
|
|
|
587
563
|
### π§° Development environments
|
|
588
564
|
|
|
@@ -595,48 +571,47 @@ supports `version_format`.
|
|
|
595
571
|
| `nix_shell` | `IN_NIX_SHELL`, `NIX_SHELL_NAME`, `NIX_SHELL_LEVEL` | None | None |
|
|
596
572
|
| `guix_shell` | Presence of `GUIX_ENVIRONMENT` | None | None |
|
|
597
573
|
|
|
598
|
-
The extension never enumerates the process environment, activates a shell, evaluates Nix, lists
|
|
599
|
-
|
|
600
|
-
bounded before publication.
|
|
574
|
+
The extension never enumerates the process environment, activates a shell, evaluates Nix, lists installed tools, or publishes arbitrary environment values.
|
|
575
|
+
Names and paths are control-sanitized and bounded before publication.
|
|
601
576
|
|
|
602
577
|
### π’ Deployment and cloud context
|
|
603
578
|
|
|
604
|
-
These modules read inert local metadata only.
|
|
605
|
-
a Terraform/OpenTofu backend, a cloud API, an OAuth flow, a credential helper, or a metadata service.
|
|
606
|
-
The deployment/cloud safety review retained opt-in root behavior: context labels may be sensitive and
|
|
607
|
-
there is no usage evidence justifying more default footer density.
|
|
579
|
+
These modules read inert local metadata only.
|
|
580
|
+
They do **not** contact Docker, a Kubernetes cluster, a Terraform/OpenTofu backend, a cloud API, an OAuth flow, a credential helper, or a metadata service.
|
|
581
|
+
The deployment/cloud safety review retained opt-in root behavior: context labels may be sensitive and there is no usage evidence justifying more default footer density.
|
|
608
582
|
|
|
609
|
-
- `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json
|
|
610
|
-
`default` is suppressed.
|
|
611
|
-
|
|
612
|
-
|
|
583
|
+
- `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`.
|
|
584
|
+
The `default` context is suppressed.
|
|
585
|
+
`only_with_files` and detection arrays are supported.
|
|
586
|
+
- `kubernetes`: at most `max_config_files` (default 8) from `KUBECONFIG` or `~/.kube/config`, with first-wins merge semantics.
|
|
587
|
+
Only context, namespace, cluster name, and user name are selected.
|
|
613
588
|
Exact `context_aliases`, `namespace_aliases`, `cluster_aliases`, and `user_aliases` apply.
|
|
614
|
-
- `terraform`: direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform`; workspace precedence is
|
|
615
|
-
`
|
|
616
|
-
|
|
617
|
-
- `aws`: `AWS_PROFILE`/`AWS_DEFAULT_PROFILE`, `AWS_REGION`/`AWS_DEFAULT_REGION`, then the selected AWS
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
fields never enter snapshots, diagnostics, notifications, or rendered output.
|
|
629
|
-
selected local metadataβnot valid credentials or connectivity.
|
|
589
|
+
- `terraform`: direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform`; workspace precedence is `TF_WORKSPACE` β `TF_DATA_DIR/environment` β `.terraform/environment`.
|
|
590
|
+
`terraform version`, then `tofu version`, runs only for `$version`.
|
|
591
|
+
Workspace, init, provider, and state commands never run.
|
|
592
|
+
- `aws`: `AWS_PROFILE`/`AWS_DEFAULT_PROFILE`, `AWS_REGION`/`AWS_DEFAULT_REGION`, then the selected AWS config section.
|
|
593
|
+
The credentials file is never read.
|
|
594
|
+
Exact profile/region aliases are supported.
|
|
595
|
+
- `gcloud`: active selector plus allowlisted `core.account`, `core.project`, and `compute.region` INI keys.
|
|
596
|
+
Exact project/region aliases are supported.
|
|
597
|
+
- `azure`: the default local `azureProfile.json` subscription name.
|
|
598
|
+
`show_username` defaults to `false`; exact subscription aliases are supported.
|
|
599
|
+
- `openstack`: `OS_CLOUD`, `OS_PROJECT_NAME`, or the selected `clouds.yaml` `auth.project_name` only.
|
|
600
|
+
Exact cloud/project aliases are supported.
|
|
601
|
+
|
|
602
|
+
Cloud files often colocate credentials with labels.
|
|
603
|
+
Parsers allowlist fields while reading and discard source documents; token, key, password, auth URL, tenant, and credential-derived duration fields never enter snapshots, diagnostics, notifications, or rendered output.
|
|
604
|
+
Presence indicates only selected local metadataβnot valid credentials or connectivity.
|
|
630
605
|
|
|
631
606
|
### π₯οΈ Execution context
|
|
632
607
|
|
|
633
|
-
`hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, and exact `aliases`.
|
|
634
|
-
appears only for `show_always`, SSH, root/Administrator, a login-user mismatch, or configured
|
|
635
|
-
|
|
636
|
-
disabled by default and supports an exact `symbols` map.
|
|
637
|
-
markers, WSL metadata, `/.dockerenv`, `/run/.containerenv`, and `/run/systemd/container`; it does not
|
|
638
|
-
|
|
639
|
-
labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
|
|
608
|
+
`hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, and exact `aliases`.
|
|
609
|
+
`username` appears only for `show_always`, SSH, root/Administrator, a login-user mismatch, or configured `detect_env_vars`; it supports exact aliases.
|
|
610
|
+
Negated username detection names are rejected.
|
|
611
|
+
`os` is disabled by default and supports an exact `symbols` map.
|
|
612
|
+
`container` uses only Dev Container/Codespaces markers, WSL metadata, `/.dockerenv`, `/run/.containerenv`, and `/run/systemd/container`; it does not scan process tables or cgroups.
|
|
613
|
+
Ordinary local hostname/username sessions stay empty.
|
|
614
|
+
All identity labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
|
|
640
615
|
|
|
641
616
|
### βοΈ Fill layout
|
|
642
617
|
|
|
@@ -650,31 +625,30 @@ symbol = " " # native invisible default; use "Β·" for a visible pattern
|
|
|
650
625
|
style = "dimmed"
|
|
651
626
|
```
|
|
652
627
|
|
|
653
|
-
Fill resolves independently on each logical line before ANSI serialization and wrapping.
|
|
654
|
-
fills divide remaining cells left-to-right; complete positive-width patterns repeat and any remainder
|
|
655
|
-
|
|
656
|
-
already meets or exceeds the width, fill contributes zero and normal ANSI-aware wrapping applies.
|
|
657
|
-
Unicode wide/combining symbols, palettes, `prev_fg`/`prev_bg`, ANSI, and OSC hyperlinks use Pi TUI
|
|
658
|
-
|
|
659
|
-
|
|
628
|
+
Fill resolves independently on each logical line before ANSI serialization and wrapping.
|
|
629
|
+
Multiple fills divide remaining cells left-to-right; complete positive-width patterns repeat and any remainder uses styled spaces.
|
|
630
|
+
Empty/zero-width patterns become spaces.
|
|
631
|
+
Fixed content is never truncated: when it already meets or exceeds the width, fill contributes zero and normal ANSI-aware wrapping applies.
|
|
632
|
+
Unicode wide/combining symbols, palettes, `prev_fg`/`prev_bg`, ANSI, and OSC hyperlinks use Pi TUI visible-width semantics.
|
|
633
|
+
`$all` deliberately includes enabled fill, so use `$all` only when that whole-catalog layout is intended.
|
|
634
|
+
There is no `line_break` module; use literal newlines in `format`.
|
|
660
635
|
|
|
661
636
|
### π Cached refresh lifecycle
|
|
662
637
|
|
|
663
|
-
Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
synchronously and perform zero reads or commands.
|
|
638
|
+
Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled modules.
|
|
639
|
+
Root format reachability, `$all`, module `disabled`, and module-format variables determine file and command requirements.
|
|
640
|
+
Workspace/Git refreshes run at session start, after accepted settings, branch changes, tool/turn completion, and a 30-second fallback.
|
|
641
|
+
GitHub PR uses the narrower lifecycle and 60-second network refresh described above.
|
|
642
|
+
One read runs with at most one latest pending refresh.
|
|
643
|
+
Immutable snapshot equality suppresses redraws, and session or request generations reject stale results.
|
|
644
|
+
Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command work before starting replacements; disabling `github_pr` also stops its query and timers.
|
|
645
|
+
Bounded local filesystem operations may finish, but stale generations cannot publish them.
|
|
646
|
+
Execution identity is retained rather than re-read by the periodic fallback.
|
|
647
|
+
Render and live preview consume snapshots synchronously and perform zero reads or commands.
|
|
674
648
|
|
|
675
649
|
Missing, unreadable, malformed, oversized, timed-out, or unavailable sources fail to empty values.
|
|
676
|
-
Workspace/Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never
|
|
677
|
-
|
|
650
|
+
Workspace/Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make no network calls.
|
|
651
|
+
The native GitHub PR query is the documented network exception.
|
|
678
652
|
Package's explicitly documented Cargo lookup is the only ancestor walk and is capped at eight parents.
|
|
679
653
|
|
|
680
654
|
## π¬ Commands
|
|
@@ -686,49 +660,48 @@ Package's explicitly documented Cargo lookup is the only ancestor walk and is ca
|
|
|
686
660
|
| `/starship status` | Show config source/path and diagnostics |
|
|
687
661
|
| `/starship help` | Show command and configuration help |
|
|
688
662
|
|
|
689
|
-
The standard main menu keeps seven goals on one level: **Customize footer**, **Presets**,
|
|
690
|
-
|
|
691
|
-
the
|
|
692
|
-
|
|
693
|
-
together with the current health. Presets, Explain, and Modules are menu-only paths; they do not add
|
|
694
|
-
textual subcommands or change RPC, print, or JSON protocols. Restore remains last and unavailable
|
|
695
|
-
when there is no document to replace.
|
|
663
|
+
The standard main menu keeps seven goals on one level: **Customize footer**, **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-inβ¦**.
|
|
664
|
+
It shows whether the footer uses built-in defaults, a saved built-in document, a named preset, a custom document, or an error-driven fallback, together with the current health.
|
|
665
|
+
Presets, Explain, Modules, and the nested Configuration capabilities are menu-only paths; they do not add textual subcommands or change RPC, print, or JSON protocols.
|
|
666
|
+
Restore remains last and unavailable when there is no document to replace.
|
|
696
667
|
|
|
697
|
-
The TOML editor, adaptive live footer previews, Explain view,
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
the whole workflow.
|
|
668
|
+
The TOML editor, adaptive live footer previews, Explain view, searchable module inspector, and Configuration document reviews remain specialized extension UI.
|
|
669
|
+
Their hints follow Pi's injected keybindings; list, detail, and exact-document content stay bounded across terminal resize.
|
|
670
|
+
Escape returns from detail or to the main menu, while Ctrl+C closes the whole workflow.
|
|
701
671
|
|
|
702
|
-
The direct routes accept no trailing arguments.
|
|
703
|
-
|
|
704
|
-
|
|
672
|
+
The direct routes accept no trailing arguments.
|
|
673
|
+
Status and help remain safe in TUI, RPC, JSON, and print modes.
|
|
674
|
+
RPC receives notifications but never opens custom terminal UI; print and JSON modes produce no ad hoc output.
|
|
675
|
+
Footer/timer/Git lifecycle work starts only in TUI mode.
|
|
705
676
|
|
|
706
677
|
## π Scope
|
|
707
678
|
|
|
708
|
-
The formatter, style concepts, and selected contextual modules are Starship-inspired, while Pi owns
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
shell modules, or expose unrestricted `env_var` behavior. JVM/.NET, other long-tail languages,
|
|
712
|
-
alternative VCS, system-monitor, and additional DevOps modules remain demand-gated; the first-wave
|
|
713
|
-
review found no issue/discussion evidence for a coherent follow-up batch, so no second wave is added.
|
|
679
|
+
The formatter, style concepts, and selected contextual modules are Starship-inspired, while Pi owns the lifecycle, snapshots, privacy boundary, and footer layout.
|
|
680
|
+
This extension does not load `starship.toml`, claim complete module/config compatibility, invoke the Starship binary, run custom shell modules, or expose unrestricted `env_var` behavior.
|
|
681
|
+
JVM/.NET, other long-tail languages, alternative VCS, system-monitor, and additional DevOps modules remain demand-gated; the first-wave review found no issue/discussion evidence for a coherent follow-up batch, so no second wave is added.
|
|
714
682
|
|
|
715
|
-
Pi-native model, context, cache, cost, Git metrics, and activity remain owned by the existing modules.
|
|
716
|
-
lifecycle design rejects provider-specific duplicates and ambiguous `turn_duration`/`last_result`
|
|
717
|
-
modules until separately approved semantics exist.
|
|
683
|
+
Pi-native model, context, cache, cost, Git metrics, and activity remain owned by the existing modules.
|
|
684
|
+
The lifecycle design rejects provider-specific duplicates and ambiguous `turn_duration`/`last_result` modules until separately approved semantics exist.
|
|
718
685
|
|
|
719
686
|
## β Adding a module
|
|
720
687
|
|
|
721
|
-
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`.
|
|
688
|
+
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`.
|
|
689
|
+
Configuration names, validation variables, defaults, and `$all` ordering are derived from that catalog.
|
|
690
|
+
Add the module to the built-in root format when it should be visible by default, then document and test its user-facing values.
|
|
722
691
|
|
|
723
692
|
Keep `extension_status` last in the catalog so arbitrary third-party statuses follow native module output.
|
|
724
693
|
|
|
725
694
|
## ποΈ Package layout
|
|
726
695
|
|
|
727
|
-
- `
|
|
696
|
+
- `dist/` β generated split TypeScript runtime loaded through Pi's Jiti loader.
|
|
697
|
+
- `scripts/build-runtime.mjs` β deterministic runtime bundler and eager-boundary validator.
|
|
698
|
+
- `src/index.ts` β thin authoritative source entrypoint.
|
|
728
699
|
- `src/pi-starship.ts` β authoritative extension lifecycle, cached refresh binding, live preview, and footer.
|
|
729
700
|
- `src/usage.ts` β native-aligned session usage and cache aggregation.
|
|
730
701
|
- `src/command-contract.ts` β lightweight command routes and completions loaded at startup.
|
|
731
|
-
- `src/commands.ts` β lazily loaded menu, preview/confirmation
|
|
702
|
+
- `src/commands.ts` β lazily loaded top-level menu, preview/confirmation workflows, and compatibility routes.
|
|
703
|
+
- `src/command-configuration.ts` β nested configuration presentation, exact document views, and safe runtime-only disk reload.
|
|
704
|
+
- `src/effective-config.ts` β explicit catalog-ordered public TOML projection and deterministic serialization.
|
|
732
705
|
- `src/command-preset-picker.ts` β lifecycle-owned preset cursor and temporary footer-preview UI.
|
|
733
706
|
- `src/presets/` β bundled complete TOML documents and stable preset metadata.
|
|
734
707
|
- `src/command-inspector.ts` β adaptive Explain and searchable read-only module inspection surfaces.
|
|
@@ -743,9 +716,10 @@ Keep `extension_status` last in the catalog so arbitrary third-party statuses fo
|
|
|
743
716
|
|
|
744
717
|
## π Keywords
|
|
745
718
|
|
|
746
|
-
Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, GitHub pull
|
|
747
|
-
request, prompt cache, cache hit rate, Pi extension
|
|
719
|
+
Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, GitHub pull request, prompt cache, cache hit rate, Pi extension
|
|
748
720
|
|
|
749
721
|
## π License
|
|
750
722
|
|
|
751
|
-
MIT.
|
|
723
|
+
MIT.
|
|
724
|
+
See [`LICENSE`](./LICENSE).
|
|
725
|
+
Starship attribution and its ISC license are included in [`NOTICES.md`](./NOTICES.md).
|