@narumitw/pi-starship 0.54.0 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +32 -626
  2. package/dist/chunks/{chunk-OZDBEKV2.js → chunk-UX6PBXVK.js} +2 -2
  3. package/dist/chunks/{chunk-OZDBEKV2.js.map → chunk-UX6PBXVK.js.map} +1 -1
  4. package/dist/chunks/{cloud-GEBXIN43.js → cloud-BKHYWCTA.js} +3 -3
  5. package/dist/chunks/cloud-BKHYWCTA.js.map +7 -0
  6. package/dist/chunks/{commands-Z3V7LRUY.js → commands-53ZO2JUK.js} +2 -2
  7. package/dist/chunks/{development-TOXV7LWE.js → development-BERD42HW.js} +2 -2
  8. package/dist/chunks/{development-TOXV7LWE.js.map → development-BERD42HW.js.map} +2 -2
  9. package/dist/chunks/{execution-QDYHQKST.js → execution-42JTEY3N.js} +2 -2
  10. package/dist/chunks/{execution-QDYHQKST.js.map → execution-42JTEY3N.js.map} +2 -2
  11. package/dist/chunks/{languages-QR3XPRVQ.js → languages-RMP6DW7H.js} +2 -2
  12. package/dist/chunks/languages-RMP6DW7H.js.map +7 -0
  13. package/dist/index.ts +6 -6
  14. package/package.json +12 -7
  15. package/skills/configuring-pi-starship/SKILL.md +113 -0
  16. package/skills/configuring-pi-starship/references/configuration.md +365 -0
  17. package/skills/configuring-pi-starship/references/module-catalog.md +978 -0
  18. package/skills/configuring-pi-starship/references/modules.md +230 -0
  19. package/skills/configuring-pi-starship/references/runtime-and-security.md +213 -0
  20. package/skills/configuring-pi-starship/scripts/apply.mjs +64 -0
  21. package/skills/configuring-pi-starship/scripts/config-path.mjs +11 -0
  22. package/skills/configuring-pi-starship/scripts/script-support.mjs +20 -0
  23. package/skills/configuring-pi-starship/scripts/validate.mjs +30 -0
  24. package/src/modules/catalog.ts +1 -1
  25. package/src/runtime/cloud.ts +3 -2
  26. package/src/runtime/development.ts +1 -1
  27. package/src/runtime/execution.ts +1 -1
  28. package/src/runtime/languages.ts +1 -1
  29. package/dist/chunks/cloud-GEBXIN43.js.map +0 -7
  30. package/dist/chunks/languages-QR3XPRVQ.js.map +0 -7
  31. /package/dist/chunks/{commands-Z3V7LRUY.js.map → commands-53ZO2JUK.js.map} +0 -0
@@ -0,0 +1,365 @@
1
+ # Configuration and Format Reference
2
+
3
+ Use this authoritative public reference for configuration location and persistence, presets, complete-document examples, format grammar, styles, palettes, and state-selected styles.
4
+
5
+ ## ⚙️ Settings
6
+
7
+ The only configuration source is:
8
+
9
+ ```text
10
+ <getAgentDir()>/pi-starship.toml
11
+ ```
12
+
13
+ When this file is absent, the extension uses its palette-free default without creating the file or its parent directory.
14
+ 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.
15
+ The first successful settings save creates the file atomically.
16
+ Existing malformed documents are never overwritten.
17
+
18
+ The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
19
+
20
+ Open the interactive menu in TUI mode:
21
+
22
+ ```text
23
+ /starship
24
+ ```
25
+
26
+ Choose **Customize footer** to edit the TOML.
27
+ Closing the editor validates the draft and opens a scrollable preview with **Apply changes…**, **Continue editing**, and **Discard draft**.
28
+ Saving requires separate confirmation, then atomically updates the file and active footer.
29
+ Manual TOML edits load at the next `session_start`, including `/reload` and session replacement.
30
+ Cancellation, disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and footer.
31
+
32
+ The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
33
+ 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.
34
+ Modules opens a bounded searchable inspector for every registered module.
35
+ Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
36
+ 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.
37
+ Both views are read-only and do not create or update the settings document.
38
+
39
+ Configuration contains **Overview**, **Effective configuration**, **Settings document**, and **Reload from disk** on one nested level.
40
+ Overview combines state, source, path, health, and bounded diagnostics.
41
+ 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.
42
+ Settings document shows the exact loaded UTF-8 text through a terminal-safe, cell-aware read-only review without changing the raw payload.
43
+ A missing file is **Built-in defaults**, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
44
+ 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.
45
+ A deleted document is a valid previewable transition to built-in defaults and creates no file.
46
+ 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.
47
+ 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.
48
+ Restore is disabled when no settings document exists or the exact built-in document is already saved.
49
+ 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.
50
+
51
+ ### 🎛️ Presets
52
+
53
+ Choose **Presets** from `/starship` to browse complete Pi-native starting points.
54
+ The catalog adapts all styles listed by `starship preset --list` in Starship 1.26.0, plus a Pi-specific Minimal option.
55
+ 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.
56
+
57
+ | Preset | Adapted visual treatment | Font requirement |
58
+ | --- | --- | --- |
59
+ | **Minimal** | Compact Pi essentials | Standard Unicode |
60
+ | **Bracketed Segments** | Balanced Pi and Git information in brackets | Standard Unicode |
61
+ | **Catppuccin Powerline** | Connected Catppuccin Mocha blocks; other Catppuccin palettes remain in the document for customization | Nerd Font |
62
+ | **Gruvbox Rainbow** | Warm Gruvbox connected segments | Nerd Font |
63
+ | **Jetpack** | Airy geometric activity/context and workspace columns joined by fill | Standard Unicode |
64
+ | **Nerd Font Symbols** | Balanced default layout with icon-rich symbols | Nerd Font |
65
+ | **No Empty Icons** | Conditional text labels that cannot appear without their values | Standard Unicode |
66
+ | **No Nerd Font** | Portable Unicode symbols without private-use glyphs | Standard Unicode |
67
+ | **No Runtime Versions** | Presence indicators without model or thinking details | Standard Unicode |
68
+ | **Pastel Powerline** | Connected magenta, coral, orange, blue, teal, and navy blocks | Nerd Font |
69
+ | **Plain Text Symbols** | Plain words replace pictograms | Standard Unicode |
70
+ | **Pure Preset** | Clean two-line workspace and session context | Standard Unicode |
71
+ | **Tokyo Night** | Connected cool blue Tokyo Night blocks | Nerd Font |
72
+
73
+ Moving through the preset picker temporarily renders the selected preset in the footer without writing settings or starting collectors.
74
+ Press Enter to confirm replacement, or press `e` to edit the selected complete TOML document before preview and confirmation.
75
+ Escape returns to the main menu, while Ctrl+C closes the workflow; both restore the active footer.
76
+
77
+ Presets are complete documents, not overlays.
78
+ After confirmation, applying one replaces all of `pi-starship.toml`, including custom settings, unknown fields, and comments; no backup is kept.
79
+ Cancellation, disposal, validation failure, write failure, and runtime-apply failure preserve the previous document and footer.
80
+ An exact match is **Currently applied** and cannot be selected again; editing any byte makes it custom.
81
+ Use **Restore built-in…** for deterministic recovery.
82
+
83
+ The bundled presets use only pi-starship's local Pi and Git snapshot modules.
84
+ They do not enable the GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors.
85
+ 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.
86
+ There is no `/starship preset` textual route and no remote preset download.
87
+
88
+ ### 📝 Example
89
+
90
+ ```toml
91
+ format = """
92
+ $brand\
93
+ $model\
94
+ $thinking\
95
+ $directory\
96
+ $git_branch\
97
+ $git_status\
98
+ $activity\
99
+ $context\
100
+ $time"""
101
+
102
+ [model]
103
+ format = "[ $symbol$model ]($style)"
104
+ symbol = "◆ "
105
+ style = "bold blue"
106
+ truncation_length = 36
107
+ truncation_symbol = "…"
108
+ truncation_direction = "middle"
109
+
110
+ [directory]
111
+ style = "cyan bold"
112
+
113
+ [git_branch]
114
+ style = "bold purple"
115
+
116
+ [context]
117
+ format = "[$symbol $percentage/$window ]($style)"
118
+
119
+ [[context.display]]
120
+ threshold = 0
121
+ style = "bold green"
122
+ hidden = true
123
+
124
+ [[context.display]]
125
+ threshold = 30
126
+ style = "bold green"
127
+ hidden = false
128
+
129
+ [[context.display]]
130
+ threshold = 60
131
+ style = "bold yellow"
132
+ hidden = false
133
+
134
+ [[context.display]]
135
+ threshold = 80
136
+ style = "bold red"
137
+ hidden = false
138
+
139
+ [git_metrics]
140
+ added_style = "bold green"
141
+ deleted_style = "bold red"
142
+ disabled = false
143
+
144
+ [username]
145
+ style_user = "yellow bold"
146
+ style_root = "red bold"
147
+
148
+ [extension_status]
149
+ format = "([$statuses ]($style))"
150
+ icons = { "foo:*" = "🧪", "third_party/key" = "◎", fallback = "•" }
151
+ ```
152
+
153
+ Every module table supports `format`, `symbol`, and `disabled`.
154
+ Most modules also support one `style`.
155
+ 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.
156
+ `thinking` retains its `style` fallback and also accepts the per-level overrides documented below.
157
+ Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
158
+ Version formats replace `$raw`.
159
+ Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
160
+ A leading `!` is supported by language detection arrays and rejects a matching project.
161
+ `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
162
+ Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`.
163
+ An empty configured icon suppresses only the icon.
164
+ `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
165
+
166
+ Pi does not expose status ownership, so exact raw keys are the reliable third-party contract.
167
+ pi-starship does not inspect installed packages, infer aliases, assign known-extension icons, or bridge compatibility keys.
168
+ Extension authors may use `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require it.
169
+
170
+ **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`.
171
+
172
+ ## Configuration schema and validation
173
+
174
+ ### Root fields
175
+
176
+ A settings document is one TOML table with these accepted root keys:
177
+
178
+ | Key | Type | Behavior |
179
+ | --- | --- | --- |
180
+ | `format` | string | Root layout whose variables are module names or `$all`. |
181
+ | `palette` | string | Selects one exact table name from `[palettes.<name>]`. |
182
+ | `palettes` | table of tables | Defines direct color names used by style expressions. |
183
+ | `<module>` | table | Configures one module listed in [the complete module catalog](module-catalog.md). |
184
+
185
+ Unknown root keys produce warnings and remain inactive.
186
+ The loader normalizes `palettes` before resolving `palette`, so their textual order in TOML does not matter.
187
+ An unknown selected palette warns and supplies no custom colors.
188
+
189
+ ### Shared module fields
190
+
191
+ Every module table accepts `format`, `symbol`, and `disabled`.
192
+ The exact accepted style fields, display arrays, module-specific options, defaults, enum values, and numeric ranges are listed in [the complete module catalog](module-catalog.md).
193
+
194
+ `format` and `symbol` must be strings.
195
+ `disabled` must be boolean.
196
+ A standard `style` field must be a valid style string.
197
+ `thinking` accepts `style` plus `style_off`, `style_minimal`, `style_low`, `style_medium`, `style_high`, `style_xhigh`, and `style_max`.
198
+ `git_metrics` accepts `added_style` and `deleted_style` instead of `style`.
199
+ `username` accepts `style_user` and `style_root` instead of `style`.
200
+ `context` and `cost` accept `display` arrays instead of a direct `style` field.
201
+
202
+ `[[context.display]]` and `[[cost.display]]` entries require these typed fields:
203
+
204
+ ```toml
205
+ threshold = 60 # finite number
206
+ style = "bold yellow" # valid style string
207
+ hidden = false # boolean
208
+ ```
209
+
210
+ Unknown display fields warn.
211
+ Invalid display entries are discarded independently.
212
+ When no valid entries remain, the complete module display default is restored.
213
+
214
+ `extension_status` additionally accepts `separator`, `max_statuses`, and `icons`.
215
+ `separator` is a string, `max_statuses` is an integer from 0 through 100, and `icons` is a string-to-string table.
216
+
217
+ ### Module option types
218
+
219
+ Module-specific options use these validation rules:
220
+
221
+ | Type | Accepted value |
222
+ | --- | --- |
223
+ | string | A TOML string; options marked non-empty reject `""`. |
224
+ | string enum | An exact case-sensitive listed string. |
225
+ | boolean | A TOML boolean, not a quoted string. |
226
+ | integer | An integer inside the inclusive range listed in the module catalog. |
227
+ | string array | An array containing only non-empty strings. |
228
+ | string-to-string table | A TOML table whose values are all strings. |
229
+
230
+ Language `detect_files`, `detect_extensions`, and `detect_folders` arrays allow entries beginning with `!` as rejection rules.
231
+ Other string-array options reject entries beginning with `!`.
232
+ Detection fallback and replacement behavior differs by module and is specified in [module behavior](modules.md).
233
+
234
+ ### Diagnostic and fallback behavior
235
+
236
+ | Failure | Result |
237
+ | --- | --- |
238
+ | Missing file | Use built-in defaults without creating a file or directory. |
239
+ | Read failure | Use built-in defaults and report an error diagnostic. |
240
+ | TOML syntax failure | Preserve the raw document, use built-in defaults, and report an error diagnostic. |
241
+ | Unknown root, module, option, or display field | Warn, ignore that field, and keep processing the document. |
242
+ | Wrong field type | Warn and retain the default for that field. |
243
+ | Invalid root `format` | Warn and restore only the built-in root format. |
244
+ | Invalid module `format` | Warn and restore only that module's default format. |
245
+ | Unknown format or style variable | Warn and render that variable empty. |
246
+ | Invalid literal group style | Warn and render that group unstyled. |
247
+ | Invalid module style field | Warn and restore only that style field's module default. |
248
+ | Invalid palette color | Warn and omit only that palette entry. |
249
+ | Invalid module option | Warn and restore only that option's default. |
250
+ | Invalid display entry | Warn and discard only that entry; restore defaults if none remain. |
251
+
252
+ TOML syntax and read failures are errors that block interactive saving or reload application.
253
+ Semantic warnings do not prevent a document from loading or being saved, but `/starship status` reports them.
254
+ Unknown fields and comments remain in the settings document even though they are excluded from the normalized effective configuration.
255
+
256
+ ## 🧩 Format grammar
257
+
258
+ - Variables: `$name` and `${name}`.
259
+ Unknown variables render empty and produce a warning when loaded from TOML.
260
+ - Escapes: `\\$`, `\\[`, `\\]`, `\\(`, `\\)`, and `\\\\` render functional characters literally.
261
+ - Styled groups: `[format string](style string)`.
262
+ - Conditional groups: `(format string)` render only when a nested variable has a non-empty value.
263
+ - Nested groups are supported.
264
+ - `$all` expands enabled modules in the default order and omits modules already referenced explicitly.
265
+
266
+ Module formats can use `$style` in a style expression.
267
+ Module output keeps its own style when embedded in an outer styled group.
268
+
269
+ ## 🎨 Styles and palettes
270
+
271
+ Style expressions support:
272
+
273
+ - Named colors and ANSI numbers `0`–`255`.
274
+ - Hex RGB (`#7aa2f7`), rendered as ANSI-256 when Pi's effective terminal capabilities disable true color.
275
+ - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
276
+ - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
277
+ - `none` and `fg:none`, which make the complete expression unstyled regardless of position.
278
+ - `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same Starship-compatible reset behavior.
279
+ - `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.
280
+ - Direct color names from one explicitly selected `[palettes.<name>]` table.
281
+
282
+ There is no built-in or fallback palette.
283
+ 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.
284
+ Palette names override terminal color names such as `blue`:
285
+
286
+ ```toml
287
+ palette = "company"
288
+
289
+ [palettes.company]
290
+ blue = "#86BBD8"
291
+ accent = "208"
292
+
293
+ [model]
294
+ style = "bold blue"
295
+ ```
296
+
297
+ Style tokens are case-insensitive and ordinary foreground/background colors are last-wins.
298
+ `prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists.
299
+ Empty styled groups still advance previous-color state.
300
+ Invalid literal style expressions warn and render unstyled.
301
+ 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.
302
+ `/starship status` reports warnings.
303
+
304
+ The background-free 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"`.
305
+ Context, cost, Git metrics, and username use the state/multi-style defaults below.
306
+
307
+ ### Thinking level styles
308
+
309
+ `thinking` can override its appearance for `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` independently:
310
+
311
+ ```toml
312
+ [thinking]
313
+ style = "bold purple"
314
+ style_low = "bold blue"
315
+ style_high = "bold yellow"
316
+ style_max = "bold red"
317
+ ```
318
+
319
+ The matching `style_<level>` wins when it is non-empty.
320
+ Every unset or empty level override uses the existing `style`, including levels added by a future Pi release.
321
+ Invalid fallback and level styles warn and fall back independently without changing other levels.
322
+
323
+ ### State-selected styles
324
+
325
+ `context` and `cost` select the last entry at the highest threshold less than or equal to the current value.
326
+ A later entry wins when thresholds are equal.
327
+ Each display entry requires a finite `threshold`, a valid `style`, and boolean `hidden`.
328
+ Invalid entries warn and are ignored; module defaults are used if none remain.
329
+
330
+ The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and `bold red` at `80`.
331
+ The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red` at `5`:
332
+
333
+ ```toml
334
+ [[cost.display]]
335
+ threshold = 0
336
+ style = "bold green"
337
+ hidden = true
338
+
339
+ [[cost.display]]
340
+ threshold = 1
341
+ style = "bold yellow"
342
+ hidden = false
343
+
344
+ [[cost.display]]
345
+ threshold = 5
346
+ style = "bold red"
347
+ hidden = false
348
+ ```
349
+
350
+ `git_metrics` exposes `$added_style` and `$deleted_style` in its module format.
351
+ `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.
352
+
353
+ ### Breaking palette migration
354
+
355
+ 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.
356
+ Existing files are not rewritten.
357
+ 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.
358
+
359
+ Choose one migration:
360
+
361
+ 1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or `fg:#e3e5e5 bg:#769ff0`.
362
+ 2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with `palette = "<name>"`.
363
+ 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new plain nine-module configuration.
364
+
365
+ There is no hidden compatibility overlay or automatic migration.