@narumitw/pi-starship 0.52.2 → 0.54.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 +93 -68
- package/dist/chunks/{chunk-6D6VEVE5.js → chunk-OZDBEKV2.js} +124 -25
- package/dist/chunks/chunk-OZDBEKV2.js.map +7 -0
- package/dist/chunks/{commands-T73QN435.js → commands-Z3V7LRUY.js} +3 -2
- package/dist/chunks/{commands-T73QN435.js.map → commands-Z3V7LRUY.js.map} +2 -2
- package/dist/index.ts +27 -6
- package/dist/index.ts.map +3 -3
- package/package.json +6 -9
- package/src/config.ts +9 -0
- package/src/effective-config.ts +1 -0
- package/src/format/style.ts +14 -6
- package/src/modules/activity.ts +57 -4
- package/src/modules/catalog.ts +1 -1
- package/src/modules/provider.ts +19 -1
- package/src/modules/render.ts +2 -1
- package/src/modules/thinking.ts +24 -0
- package/src/modules/types.ts +3 -0
- package/src/pi-starship.ts +24 -3
- package/src/runtime/github-pr.ts +2 -1
- package/dist/chunks/chunk-6D6VEVE5.js.map +0 -7
package/README.md
CHANGED
|
@@ -2,9 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-starship) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
Build a
|
|
6
|
-
|
|
7
|
-
No `starship` executable or shell prompt is required because this extension parses and renders the footer itself.
|
|
5
|
+
Build a customizable Pi footer with Starship-style TOML, native Pi modules, conditional formats, palettes, and responsive multiline layout.
|
|
6
|
+
The extension parses and renders the footer itself, so it does not need the `starship` executable or a shell prompt.
|
|
8
7
|
|
|
9
8
|
> **Different package:** The unscoped npm package `pi-starship` delegates to the Starship binary.
|
|
10
9
|
> This package is `@narumitw/pi-starship` and renders Pi-specific modules natively.
|
|
@@ -38,15 +37,35 @@ npm --workspace @narumitw/pi-starship run build
|
|
|
38
37
|
pi -e ./packages/pi-starship
|
|
39
38
|
```
|
|
40
39
|
|
|
41
|
-
The package declares `dist/index.ts`, so an unbuilt local checkout
|
|
42
|
-
|
|
43
|
-
Do not enable this
|
|
40
|
+
The package declares `dist/index.ts`, so build an unbuilt local checkout before Pi loads the package directory.
|
|
41
|
+
Install only from sources you trust because Pi extensions run with Pi's permissions.
|
|
42
|
+
Do not enable this with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
|
|
44
43
|
|
|
45
44
|
## 🚀 Quick start
|
|
46
45
|
|
|
47
46
|
Start Pi with the extension to use the built-in footer without creating a settings file.
|
|
48
47
|
Run `/starship` to inspect the footer, choose a preset, or customize the configuration.
|
|
49
48
|
|
|
49
|
+
## 💬 Commands
|
|
50
|
+
|
|
51
|
+
| Command | Purpose |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `/starship` | Open the current-state menu in TUI mode; show help in RPC |
|
|
54
|
+
| `/starship settings` | Edit, preview, and confirm TOML in TUI; show the file path in RPC |
|
|
55
|
+
| `/starship status` | Show the configuration source, path, and diagnostics in TUI or RPC |
|
|
56
|
+
| `/starship help` | Show command and configuration help in TUI or RPC |
|
|
57
|
+
|
|
58
|
+
The main menu keeps seven actions on one level: **Customize footer**, **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
|
|
59
|
+
It shows the current source and configuration health.
|
|
60
|
+
Presets, Explain, Modules, and Configuration are menu-only; they do not add textual subcommands.
|
|
61
|
+
Restore is unavailable when there is no document to replace.
|
|
62
|
+
|
|
63
|
+
The TOML editor, live footer previews, Explain view, module inspector, and configuration reviews use specialized TUI screens.
|
|
64
|
+
Their content and key hints adapt to terminal width and Pi's configured keybindings.
|
|
65
|
+
Escape returns to the previous screen, while Ctrl+C closes the workflow.
|
|
66
|
+
Direct routes reject trailing arguments.
|
|
67
|
+
Print and JSON modes produce no ad hoc output, and footer lifecycle work runs only in TUI mode.
|
|
68
|
+
|
|
50
69
|
## ⚙️ Settings
|
|
51
70
|
|
|
52
71
|
The only configuration source is:
|
|
@@ -55,7 +74,7 @@ The only configuration source is:
|
|
|
55
74
|
<getAgentDir()>/pi-starship.toml
|
|
56
75
|
```
|
|
57
76
|
|
|
58
|
-
When this file is absent, the extension uses its
|
|
77
|
+
When this file is absent, the extension uses its palette-free default without creating the file or its parent directory.
|
|
59
78
|
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
79
|
The first successful settings save creates the file atomically.
|
|
61
80
|
Existing malformed documents are never overwritten.
|
|
@@ -69,24 +88,23 @@ Open the interactive menu in TUI mode:
|
|
|
69
88
|
```
|
|
70
89
|
|
|
71
90
|
Choose **Customize footer** to edit the TOML.
|
|
72
|
-
Closing the editor validates the draft and opens
|
|
73
|
-
Saving
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
Editor cancellation, preview cancellation, component disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and effective footer.
|
|
91
|
+
Closing the editor validates the draft and opens a scrollable preview with **Apply changes…**, **Continue editing**, and **Discard draft**.
|
|
92
|
+
Saving requires separate confirmation, then atomically updates the file and active footer.
|
|
93
|
+
Manual TOML edits load at the next `session_start`, including `/reload` and session replacement.
|
|
94
|
+
Cancellation, disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and footer.
|
|
77
95
|
|
|
78
96
|
The shallow main menu also exposes **Presets**, **Explain footer**, **Modules**, **Configuration**, **Help**, and **Restore built-in…**.
|
|
79
97
|
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
98
|
Modules opens a bounded searchable inspector for every registered module.
|
|
81
99
|
Its textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and **Unavailable** only when the current footer cannot provide an inspection snapshot.
|
|
82
100
|
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
|
|
101
|
+
Both views are read-only and do not create or update the settings document.
|
|
84
102
|
|
|
85
103
|
Configuration contains **Overview**, **Effective configuration**, **Settings document**, and **Reload from disk** on one nested level.
|
|
86
104
|
Overview combines state, source, path, health, and bounded diagnostics.
|
|
87
105
|
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
106
|
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
|
|
107
|
+
A missing file is **Built-in defaults**, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
|
|
90
108
|
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
109
|
A deleted document is a valid previewable transition to built-in defaults and creates no file.
|
|
92
110
|
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.
|
|
@@ -116,16 +134,15 @@ Colors, separators, typography, and layout follow the named Starship preset; mod
|
|
|
116
134
|
| **Pure Preset** | Clean two-line workspace and session context | Standard Unicode |
|
|
117
135
|
| **Tokyo Night** | Connected cool blue Tokyo Night blocks | Nerd Font |
|
|
118
136
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
Escape returns to the main menu, while Ctrl+C closes the complete workflow; both restore the previously effective footer.
|
|
137
|
+
Moving through the preset picker temporarily renders the selected preset in the footer without writing settings or starting collectors.
|
|
138
|
+
Press Enter to confirm replacement, or press `e` to edit the selected complete TOML document before preview and confirmation.
|
|
139
|
+
Escape returns to the main menu, while Ctrl+C closes the workflow; both restore the active footer.
|
|
123
140
|
|
|
124
141
|
Presets are complete documents, not overlays.
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
**Restore built-in…**
|
|
142
|
+
After confirmation, applying one replaces all of `pi-starship.toml`, including custom settings, unknown fields, and comments; no backup is kept.
|
|
143
|
+
Cancellation, disposal, validation failure, write failure, and runtime-apply failure preserve the previous document and footer.
|
|
144
|
+
An exact match is **Currently applied** and cannot be selected again; editing any byte makes it custom.
|
|
145
|
+
Use **Restore built-in…** for deterministic recovery.
|
|
129
146
|
|
|
130
147
|
The bundled presets use only pi-starship's local Pi and Git snapshot modules.
|
|
131
148
|
They do not enable the GitHub PR query, cloud/deployment readers, or optional command-backed workspace collectors.
|
|
@@ -200,6 +217,7 @@ icons = { "foo:*" = "🧪", "third_party/key" = "◎", fallback = "•" }
|
|
|
200
217
|
Every module table supports `format`, `symbol`, and `disabled`.
|
|
201
218
|
Most modules also support one `style`.
|
|
202
219
|
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.
|
|
220
|
+
`thinking` retains its `style` fallback and also accepts the per-level overrides documented below.
|
|
203
221
|
Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
|
|
204
222
|
Version formats replace `$raw`.
|
|
205
223
|
Detection arrays replace defaults when non-empty and inspect only one listing of the current directory.
|
|
@@ -209,8 +227,9 @@ Icon matching uses the exact key, the longest `:*` wildcard, a leading status em
|
|
|
209
227
|
An empty configured icon suppresses only the icon.
|
|
210
228
|
`foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
|
|
211
229
|
|
|
212
|
-
Pi does not expose
|
|
213
|
-
|
|
230
|
+
Pi does not expose status ownership, so exact raw keys are the reliable third-party contract.
|
|
231
|
+
pi-starship does not inspect installed packages, infer aliases, assign known-extension icons, or bridge compatibility keys.
|
|
232
|
+
Extension authors may use `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require it.
|
|
214
233
|
|
|
215
234
|
**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`.
|
|
216
235
|
|
|
@@ -232,7 +251,7 @@ Module output keeps its own style when embedded in an outer styled group.
|
|
|
232
251
|
Style expressions support:
|
|
233
252
|
|
|
234
253
|
- Named colors and ANSI numbers `0`–`255`.
|
|
235
|
-
- Hex RGB (`#7aa2f7`).
|
|
254
|
+
- Hex RGB (`#7aa2f7`), rendered as ANSI-256 when Pi's effective terminal capabilities disable true color.
|
|
236
255
|
- `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
|
|
237
256
|
- `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
|
|
238
257
|
- `none` and `fg:none`, which make the complete expression unstyled regardless of position.
|
|
@@ -262,9 +281,25 @@ Invalid literal style expressions warn and render unstyled.
|
|
|
262
281
|
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
282
|
`/starship status` reports warnings.
|
|
264
283
|
|
|
265
|
-
The background-free
|
|
284
|
+
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"`.
|
|
266
285
|
Context, cost, Git metrics, and username use the state/multi-style defaults below.
|
|
267
286
|
|
|
287
|
+
### Thinking level styles
|
|
288
|
+
|
|
289
|
+
`thinking` can override its appearance for `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max` independently:
|
|
290
|
+
|
|
291
|
+
```toml
|
|
292
|
+
[thinking]
|
|
293
|
+
style = "bold purple"
|
|
294
|
+
style_low = "bold blue"
|
|
295
|
+
style_high = "bold yellow"
|
|
296
|
+
style_max = "bold red"
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
The matching `style_<level>` wins when it is non-empty.
|
|
300
|
+
Every unset or empty level override uses the existing `style`, including levels added by a future Pi release.
|
|
301
|
+
Invalid fallback and level styles warn and fall back independently without changing other levels.
|
|
302
|
+
|
|
268
303
|
### State-selected styles
|
|
269
304
|
|
|
270
305
|
`context` and `cost` select the last entry at the highest threshold less than or equal to the current value.
|
|
@@ -325,7 +360,7 @@ There is no hidden compatibility overlay or automatic migration.
|
|
|
325
360
|
| `git_state` | `$symbol`, `$state`, `$progress_current`, `$progress_total` | Rebase, merge, revert, cherry-pick, bisect, or mail-apply state |
|
|
326
361
|
| `git_metrics` | `$symbol`, `$added`, `$deleted` | Added/deleted line totals from the working tree diff |
|
|
327
362
|
| `git_status` | `$symbol`, `$all_status`, `$ahead_behind`, `$ahead`, `$behind`, `$diverged`, `$up_to_date`, `$conflicted`, `$stashed`, `$deleted`, `$renamed`, `$modified`, `$typechanged`, `$staged`, `$untracked`, and detailed index/worktree counters | Cached porcelain-v2 counters |
|
|
328
|
-
| `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$text` |
|
|
363
|
+
| `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$kind`, `$title`, `$text` | Extension UI waits, active tools, streaming, completion, or idle |
|
|
329
364
|
| `context` | `$symbol`, `$percentage`, `$tokens`, `$window` | Context-window use |
|
|
330
365
|
| `tokens` | `$symbol`, `$input`, `$output`, `$total` | Token totals |
|
|
331
366
|
| `cache` | `$symbol`, `$rate`, `$read`, `$write` | Prompt-cache reads, writes, and latest hit rate; disabled by default |
|
|
@@ -360,6 +395,8 @@ There is no hidden compatibility overlay or automatic migration.
|
|
|
360
395
|
|
|
361
396
|
### Usage semantics
|
|
362
397
|
|
|
398
|
+
- During a blocking extension UI prompt, `activity` sets `$state` to `waiting`, `$kind` to the prompt kind, and `$title` to the sanitized bounded title or an empty string.
|
|
399
|
+
- Prompt waiting takes precedence without losing the underlying tool, streaming, completed, or idle state, which returns when the prompt closes.
|
|
363
400
|
- `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer.
|
|
364
401
|
This includes assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned branches retained in the session.
|
|
365
402
|
- Cache `$read` and `$write` are cumulative.
|
|
@@ -373,7 +410,6 @@ There is no hidden compatibility overlay or automatic migration.
|
|
|
373
410
|
The module name remains `context`, not `context_usage`.
|
|
374
411
|
- Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
|
|
375
412
|
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.
|
|
377
413
|
|
|
378
414
|
### Directory, Git, and environment contraction
|
|
379
415
|
|
|
@@ -421,7 +457,7 @@ Hostname trimming runs before exact alias lookup, matching Starship.
|
|
|
421
457
|
These transformations affect display only.
|
|
422
458
|
Collectors retain bounded, control-sanitized source metadata.
|
|
423
459
|
|
|
424
|
-
### Model aliases and truncation
|
|
460
|
+
### Model and provider aliases and model truncation
|
|
425
461
|
|
|
426
462
|
The model module accepts exact `model_aliases`, Starship-style `truncation_length` and `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
|
|
427
463
|
|
|
@@ -437,9 +473,19 @@ An exact alias is selected before the built-in Claude/GPT shortening rules, then
|
|
|
437
473
|
`truncation_length` counts model grapheme clusters retained before the symbol; `0` disables truncation and is the default.
|
|
438
474
|
The direction names the removed portion: `start` retains the suffix, `end` retains the prefix and is the default, and `middle` retains both ends.
|
|
439
475
|
When no alias matches, truncation runs after the built-in Claude/GPT shortening rules.
|
|
440
|
-
|
|
476
|
+
Truncation changes display only; the provider model ID is untouched.
|
|
441
477
|
Terminal control sequences in model IDs and truncation symbols are removed at render time.
|
|
442
478
|
An empty symbol truncates without a marker.
|
|
479
|
+
|
|
480
|
+
The provider module accepts exact display aliases without changing the selected provider or model:
|
|
481
|
+
|
|
482
|
+
```toml
|
|
483
|
+
[provider]
|
|
484
|
+
provider_aliases = { "openai-codex" = "codex", "amazon-bedrock" = "bedrock" }
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
An empty alias hides only the provider text.
|
|
488
|
+
Provider names and aliases are stripped of terminal controls at render time.
|
|
443
489
|
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
490
|
pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names.
|
|
445
491
|
|
|
@@ -452,6 +498,8 @@ In a linked worktree it defaults to the top-level directory name; use `$path` wh
|
|
|
452
498
|
Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default.
|
|
453
499
|
`$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
|
|
454
500
|
|
|
501
|
+
## 🔒 Security and privacy
|
|
502
|
+
|
|
455
503
|
### 🔎 Native GitHub pull requests
|
|
456
504
|
|
|
457
505
|
`$github_pr` is independent of `pi-github-pr`; installing that extension is not required.
|
|
@@ -473,7 +521,7 @@ It never mutates Pi's environment, calls the GitHub API directly, or manages tok
|
|
|
473
521
|
Variables have these values:
|
|
474
522
|
|
|
475
523
|
- `$number`: digits such as `123`.
|
|
476
|
-
- `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL, otherwise plain `#123`.
|
|
524
|
+
- `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL when Pi's effective terminal capabilities enable hyperlinks, otherwise plain `#123`.
|
|
477
525
|
- `$state`: `open`, `draft`, `merged`, or `closed`.
|
|
478
526
|
- `$checks`: all non-zero check counts in passed, failed, pending order, or `-` when no checks exist.
|
|
479
527
|
- `$review`: `R✓` for approved, `R×` for changes requested, `R?` for review required, or empty when unknown.
|
|
@@ -532,7 +580,7 @@ Branch changes clear the old PR before querying the new branch.
|
|
|
532
580
|
Closed and merged PRs remain visible for 24 hours, then expire without waiting for the next refresh.
|
|
533
581
|
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.
|
|
534
582
|
|
|
535
|
-
The query sends the repository
|
|
583
|
+
The query sends the repository and current branch through authenticated `gh` to the repository's configured GitHub host.
|
|
536
584
|
It requests only the fields above—never comments, review bodies, inline comments, or review threads.
|
|
537
585
|
Footer rendering and previews read only the immutable cached snapshot and perform no network or subprocess work.
|
|
538
586
|
|
|
@@ -577,8 +625,8 @@ Names and paths are control-sanitized and bounded before publication.
|
|
|
577
625
|
### 🚢 Deployment and cloud context
|
|
578
626
|
|
|
579
627
|
These modules read inert local metadata only.
|
|
580
|
-
They do **not** contact Docker,
|
|
581
|
-
|
|
628
|
+
They do **not** contact Docker, Kubernetes, Terraform/OpenTofu backends, cloud APIs, OAuth flows, credential helpers, or metadata services.
|
|
629
|
+
They remain opt-in because context labels may be sensitive.
|
|
582
630
|
|
|
583
631
|
- `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`.
|
|
584
632
|
The `default` context is suppressed.
|
|
@@ -613,6 +661,8 @@ Negated username detection names are rejected.
|
|
|
613
661
|
Ordinary local hostname/username sessions stay empty.
|
|
614
662
|
All identity labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
|
|
615
663
|
|
|
664
|
+
## 📐 Layout and lifecycle
|
|
665
|
+
|
|
616
666
|
### ↔️ Fill layout
|
|
617
667
|
|
|
618
668
|
Add `${fill}` between left and right root content (braces disambiguate adjacent text):
|
|
@@ -646,48 +696,23 @@ Bounded local filesystem operations may finish, but stale generations cannot pub
|
|
|
646
696
|
Execution identity is retained rather than re-read by the periodic fallback.
|
|
647
697
|
Render and live preview consume snapshots synchronously and perform zero reads or commands.
|
|
648
698
|
|
|
649
|
-
Missing, unreadable, malformed, oversized, timed-out, or unavailable sources
|
|
650
|
-
Workspace
|
|
699
|
+
Missing, unreadable, malformed, oversized, timed-out, or unavailable sources produce empty values.
|
|
700
|
+
Workspace and Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make no network calls.
|
|
651
701
|
The native GitHub PR query is the documented network exception.
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
## 💬 Commands
|
|
655
|
-
|
|
656
|
-
| Command | Purpose |
|
|
657
|
-
| --- | --- |
|
|
658
|
-
| `/starship` | Open the current-state menu in TUI mode; retain help behavior outside TUI |
|
|
659
|
-
| `/starship settings` | Open the compatible direct edit → preview → confirm flow (TUI only) |
|
|
660
|
-
| `/starship status` | Show config source/path and diagnostics |
|
|
661
|
-
| `/starship help` | Show command and configuration help |
|
|
662
|
-
|
|
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.
|
|
667
|
-
|
|
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.
|
|
671
|
-
|
|
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.
|
|
676
|
-
|
|
677
|
-
## 📐 Scope
|
|
702
|
+
The Cargo package lookup is the only ancestor walk and stops after eight parents.
|
|
678
703
|
|
|
679
|
-
|
|
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.
|
|
704
|
+
## 🚧 Limitations
|
|
682
705
|
|
|
683
|
-
|
|
684
|
-
The
|
|
706
|
+
- The formatter and modules are Starship-inspired, not fully compatible with Starship.
|
|
707
|
+
- The extension does not load `starship.toml`, invoke the Starship binary, run custom shell modules, or provide unrestricted `env_var` behavior.
|
|
708
|
+
- JVM/.NET, other long-tail languages, alternative version-control systems, system monitoring, and additional DevOps modules are not implemented.
|
|
709
|
+
- Pi does not expose the auto-compaction toggle, so the footer cannot reliably show Pi's native `(auto)` marker.
|
|
685
710
|
|
|
686
711
|
## ➕ Adding a module
|
|
687
712
|
|
|
688
713
|
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
714
|
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.
|
|
715
|
+
Add the module to the built-in root format only when it should be visible by default, then document and test its user-facing values.
|
|
691
716
|
|
|
692
717
|
Keep `extension_status` last in the catalog so arbitrary third-party statuses follow native module output.
|
|
693
718
|
|