@narumitw/pi-starship 0.43.0 β†’ 0.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +274 -89
  2. package/package.json +2 -2
  3. package/src/command-inspector.ts +470 -0
  4. package/src/command-preview.ts +206 -0
  5. package/src/commands.ts +187 -152
  6. package/src/config.ts +177 -67
  7. package/src/format/style.ts +64 -45
  8. package/src/modules/activity.ts +1 -1
  9. package/src/modules/brand.ts +1 -1
  10. package/src/modules/cache.ts +1 -1
  11. package/src/modules/catalog.ts +65 -4
  12. package/src/modules/context.ts +13 -1
  13. package/src/modules/cost.ts +12 -1
  14. package/src/modules/development.ts +1 -1
  15. package/src/modules/directory.ts +1 -1
  16. package/src/modules/display.ts +14 -0
  17. package/src/modules/execution.ts +12 -1
  18. package/src/modules/extension-status.ts +7 -98
  19. package/src/modules/fill.ts +1 -1
  20. package/src/modules/git/branch.ts +3 -37
  21. package/src/modules/git/commit.ts +1 -1
  22. package/src/modules/git/metrics.ts +8 -2
  23. package/src/modules/git/runtime.ts +5 -2
  24. package/src/modules/git/state.ts +1 -1
  25. package/src/modules/git/status.ts +1 -1
  26. package/src/modules/git/worktree.ts +1 -1
  27. package/src/modules/github-pr.ts +24 -0
  28. package/src/modules/index.ts +15 -6
  29. package/src/modules/inspection.ts +138 -0
  30. package/src/modules/model.ts +1 -1
  31. package/src/modules/provider.ts +1 -1
  32. package/src/modules/render.ts +23 -19
  33. package/src/modules/thinking.ts +1 -1
  34. package/src/modules/time.ts +1 -1
  35. package/src/modules/tokens.ts +1 -1
  36. package/src/modules/turn.ts +1 -1
  37. package/src/modules/types.ts +32 -5
  38. package/src/pi-starship.ts +149 -27
  39. package/src/runtime/command.ts +46 -8
  40. package/src/runtime/execution.ts +15 -3
  41. package/src/runtime/github-pr.ts +332 -0
  42. package/src/runtime/helpers.ts +1 -0
  43. package/src/runtime/refresh-controller.ts +30 -8
  44. package/src/runtime/types.ts +4 -0
  45. package/src/runtime/workspace.ts +27 -10
  46. package/src/installed-packages.ts +0 -84
package/README.md CHANGED
@@ -8,15 +8,17 @@ A native Pi footer configured with Starship-style TOML. It parses and renders fo
8
8
 
9
9
  ## ✨ Features
10
10
 
11
- - Uses a readable built-in Tokyo Night configuration until the user explicitly saves settings.
12
- - Starship-style root/module formats, conditional groups, `$all`, styles, and palettes.
11
+ - Uses a readable, palette-free Starship-style built-in configuration until settings are saved.
12
+ - Starship-style root/module formats, conditional groups, `$all`, styles, and opt-in palettes.
13
13
  - Pi modules for model, thinking, activity, context, tokens, prompt cache, cost, turn, and extension statuses.
14
14
  - Cached Git branch, commit, operation state, line metrics, detailed status, and linked-worktree identity.
15
+ - Native current-branch GitHub pull request links, checks, review state, and terminal-state retention.
15
16
  - Opt-in package, language, development-shell, deployment, cloud, and execution-context modules.
16
17
  - Width-aware `$fill` alignment for native multiline left/right layouts.
17
18
  - Footer rendering is pure: no subprocess, network, filesystem, timer, or environment work runs from `render()`.
18
19
  - Multiline output wraps to the terminal width instead of truncating.
19
- - Goal-oriented `/starship` menu with configuration health, preview, confirmation, and recovery.
20
+ - Goal-oriented `/starship` menu with footer explanation, searchable module inspection,
21
+ configuration health, transactional preview, and recovery.
20
22
 
21
23
  ## πŸ“¦ Install
22
24
 
@@ -30,7 +32,7 @@ Try it from a checkout:
30
32
  pi -e ./extensions/pi-starship
31
33
  ```
32
34
 
33
- Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer. `pi-starship` warns when it detects the conflict.
35
+ Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer, and Pi does not arbitrate that conflict.
34
36
 
35
37
  ## βš™οΈ Configuration
36
38
 
@@ -40,7 +42,11 @@ The only configuration source is:
40
42
  <getAgentDir()>/pi-starship.toml
41
43
  ```
42
44
 
43
- When this file is absent, the extension uses its readable Tokyo Night default without creating the file or parent directory. The first successful settings save creates it atomically. Existing malformed documents are never overwritten.
45
+ When this file is absent, the extension uses its readable palette-free default without creating the
46
+ file or parent directory. The built-in root is the explicit sequence `$brand$model$thinking$directory`
47
+ `$git_branch$git_status$activity$context$time`; it does not start the opt-in GitHub PR query. The first
48
+ successful settings save creates the file atomically. Existing malformed documents are never
49
+ overwritten.
44
50
 
45
51
  The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
46
52
 
@@ -50,82 +56,116 @@ Open the interactive menu in TUI mode:
50
56
  /starship
51
57
  ```
52
58
 
53
- Choose **Customize footer** to edit the TOML. Closing the editor validates the draft and opens a width-aware preview; saving happens only after a separate confirmation. Confirmed changes are atomically saved and applied immediately. Editor cancellation, preview cancellation, invalid drafts, write failures, and runtime application failures preserve the previous file and effective footer.
54
-
55
- The standard **Advanced** menu is one level deep and contains configuration details plus **Restore
56
- built-in**. Standard diagnostics, details, and help are Back-navigable detail screens. Restore still
57
- shows the specialized width-aware preview and requires explicit overwrite confirmation.
59
+ Choose **Customize footer** to edit the TOML. Closing the editor validates the draft and opens an
60
+ adaptive, scrollable preview whose **Apply changes…**, **Continue editing**, and **Discard draft**
61
+ actions remain reachable in short or narrow terminals. Saving happens only after a separate
62
+ confirmation. Confirmed changes are atomically saved and applied immediately. Manual TOML edits load
63
+ on the next `session_start`, including `/reload` and session replacement. Editor cancellation, preview
64
+ cancellation, component disposal, invalid drafts, write failures, and runtime application failures
65
+ preserve the previous file and effective footer.
66
+
67
+ The shallow main menu also exposes **Explain footer**, **Modules**, **Configuration**, **Help**, and
68
+ **Restore built-in…**. Explain footer uses the current immutable runtime snapshot to list each
69
+ currently showing non-empty module once with its rendered value and description; it starts no new
70
+ collection work. Modules opens a bounded searchable inspector for every registered module. Its
71
+ textual states distinguish **Showing**, **Empty**, **Disabled**, **Not in format**, and
72
+ **Unavailable** only when the current footer cannot provide an inspection snapshot. Module detail
73
+ shows the current preview when available, description, root reference and reachability, format
74
+ variables, style fields, display rules, and the known reason for absent output. Both views are
75
+ read-only and never create or update the settings document.
76
+
77
+ Configuration combines state, source, path, health, and diagnostics. A healthy missing file is shown
78
+ as **Built-in defaults**, while **Built-in fallback** is reserved for read or parse errors. Restore is
79
+ disabled when no settings document exists or the exact built-in document is already saved. For a
80
+ custom or invalid document, Restore previews the result and warns that the complete document,
81
+ including custom settings, unknown fields, and comments, will be replaced without a post-success
82
+ backup before asking for confirmation.
58
83
 
59
84
  ### πŸ“ Example
60
85
 
61
86
  ```toml
62
- format = "$brand$provider$model$thinking\n$directory$git_branch$git_status\n$activity$context$tokens$cache$cost$time$turn\n$extension_status"
63
- palette = "tokyo-night"
64
-
65
- [palettes.tokyo-night]
66
- header = "#7aa2f7"
67
- header_fg = "#1a1b26"
68
- custom = "208"
87
+ format = """
88
+ $brand\
89
+ $model\
90
+ $thinking\
91
+ $directory\
92
+ $git_branch\
93
+ $git_status\
94
+ $activity\
95
+ $context\
96
+ $time"""
69
97
 
70
98
  [model]
71
99
  format = "[ $symbol$model ]($style)"
72
100
  symbol = "β—† "
73
- style = "bold fg:header_fg bg:header"
74
- disabled = false
101
+ style = "bold blue"
75
102
  truncation_length = 36
76
103
  truncation_symbol = "…"
77
104
  truncation_direction = "middle"
78
105
 
79
- [activity]
80
- format = "([ $text ]($style))"
81
- style = "fg:custom"
106
+ [directory]
107
+ style = "cyan bold"
108
+
109
+ [git_branch]
110
+ style = "bold purple"
82
111
 
83
112
  [context]
84
113
  format = "[$symbol $percentage/$window ]($style)"
85
114
 
86
- [cache]
87
- format = "[$symbol (R$read )(W$write )(CH$rate )]($style)"
115
+ [[context.display]]
116
+ threshold = 0
117
+ style = "bold green"
118
+ hidden = true
119
+
120
+ [[context.display]]
121
+ threshold = 30
122
+ style = "bold green"
123
+ hidden = false
124
+
125
+ [[context.display]]
126
+ threshold = 60
127
+ style = "bold yellow"
128
+ hidden = false
129
+
130
+ [[context.display]]
131
+ threshold = 80
132
+ style = "bold red"
133
+ hidden = false
134
+
135
+ [git_metrics]
136
+ added_style = "bold green"
137
+ deleted_style = "bold red"
88
138
  disabled = false
89
139
 
90
- [cost]
91
- format = "[ $symbol \\$$cost( $subscription) ]($style)"
92
-
93
- [git_branch]
94
- format = "[ $symbol$branch$pr ]($style)"
95
-
96
- [package]
97
- version_format = "v$raw"
98
-
99
- [nodejs]
100
- detect_files = ["package.json", "!deno.json"]
101
- detect_extensions = ["js", "ts"]
102
-
103
- [hostname]
104
- ssh_only = true
105
- trim_at = "."
106
- aliases = { "build.example.test" = "builder" }
140
+ [username]
141
+ style_user = "yellow bold"
142
+ style_root = "red bold"
107
143
 
108
144
  [extension_status]
109
145
  format = "([$statuses ]($style))"
110
- icons = { "github-pr" = "PR", "foo:*" = "πŸ§ͺ", "@narumitw/pi-goal" = "β—Ž", fallback = "β€’" }
146
+ icons = { "foo:*" = "πŸ§ͺ", "third_party/key" = "β—Ž", fallback = "β€’" }
111
147
  ```
112
148
 
113
- All module tables support `format`, `symbol`, `style`, and `disabled`. Module-specific
114
- options are catalog-owned, type-checked, and listed below; unknown options warn and stay inactive.
149
+ Every module table supports `format`, `symbol`, and `disabled`. Most modules also support one `style`.
150
+ The exceptions are `git_metrics` (`added_style` and `deleted_style`), `username` (`style_user` and
151
+ `style_root`), and the threshold-selected `context` and `cost` `display` arrays described below.
152
+ Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
115
153
  Version formats replace `$raw`. Detection arrays replace defaults when non-empty and inspect only one
116
154
  listing of the current directory. A leading `!` is supported by language detection arrays and rejects
117
155
  a matching project.
118
- `[extension_status].icons` accepts arbitrary exact Pi status keys, explicit colon namespace
119
- wildcards such as `foo:*`, and installed package IDs; `fallback` controls unmatched statuses. Icon
120
- matching uses exact key, longest `:*` wildcard, unambiguous package alias, leading status emoji,
121
- built-in icon, then `fallback`/`πŸ”Œ`. An empty icon suppresses only the icon. `foo:*` matches
122
- `foo:server` but not `foo`, `foobar`, or `foo/server`.
123
-
124
- Pi does not expose which package owns a status, so package aliases are best-effort conveniences and
125
- exact raw keys are the reliable third-party contract. Extension authors may adopt
126
- `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship cannot
127
- require that convention. Canonical built-ins use `sync` and `retry`; compatibility mappings keep
128
- `pisync` and `unknown-error-retry` settings and older producer versions working.
156
+ `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace
157
+ wildcards such as `foo:*`; `fallback` controls unmatched statuses. Icon matching uses the exact key,
158
+ the longest `:*` wildcard, a leading status emoji, then `fallback`/`πŸ”Œ`. An empty configured icon
159
+ suppresses only the icon. `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
160
+
161
+ Pi does not expose which package owns a status, so exact raw keys are the reliable third-party
162
+ contract. pi-starship does not inspect installed packages, infer package aliases, assign icons to
163
+ known extensions, or bridge compatibility keys. Extension authors may adopt `<extension-id>` or
164
+ `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require that convention.
165
+
166
+ **Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons,
167
+ or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a
168
+ leading emoji in the status value, or `fallback`.
129
169
 
130
170
  ## 🧩 Format grammar
131
171
 
@@ -146,11 +186,91 @@ Style expressions support:
146
186
  - Hex RGB (`#7aa2f7`).
147
187
  - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
148
188
  - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
149
- - `none`, `fg:none`, and `bg:none`.
150
- - `prev_fg` and `prev_bg` to inherit the previous rendered chunk's colors.
151
- - Color names from the active `[palettes.<name>]` table. The active palette overlays the built-in Tokyo Night colors so the default module styles remain available.
189
+ - `none` and `fg:none`, which make the complete expression unstyled regardless of position.
190
+ - `bg:none`, which clears only the absolute background; an unknown `bg:<value>` has the same
191
+ Starship-compatible reset behavior.
192
+ - `prev_fg` and `prev_bg`, which use the previous rendered chunk's colors when present and retain any
193
+ absolute foreground/background in the expression as the no-previous fallback.
194
+ - Direct color names from one explicitly selected `[palettes.<name>]` table.
195
+
196
+ There is no built-in or fallback palette. A custom palette is active only when its table is explicitly
197
+ selected, and its values must be direct named, ANSI, or RGB colorsβ€”palette entries cannot reference
198
+ other entries. Palette names override terminal color names such as `blue`:
199
+
200
+ ```toml
201
+ palette = "company"
202
+
203
+ [palettes.company]
204
+ blue = "#86BBD8"
205
+ accent = "208"
206
+
207
+ [model]
208
+ style = "bold blue"
209
+ ```
210
+
211
+ Style tokens are case-insensitive and ordinary foreground/background colors are last-wins.
212
+ `prev_fg`/`prev_bg` override their absolute fallback only when a previous chunk exists. Empty styled
213
+ groups still advance previous-color state. Invalid literal style expressions warn and render
214
+ unstyled. An invalid root format falls back to the built-in root format; an invalid module format or
215
+ catalog-owned style field falls back only at that field's module scope. `/starship status` reports
216
+ warnings.
217
+
218
+ The background-free direct defaults are: `brand = "bold white"`, `provider`/`model` = `"bold blue"`,
219
+ `thinking`/`git_branch`/`turn` = `"bold purple"`, `directory`/`git_worktree` = `"cyan bold"`,
220
+ `github_pr = "bold blue"`, `git_commit = "green bold"`, `git_state`/`activity`/`time` =
221
+ `"bold yellow"`, `git_status = "red bold"`, `tokens = "bold cyan"`, `cache = "bold green"`,
222
+ `extension_status = "dimmed white"`, `direnv = "bold bright-yellow"`, and `fill = "bold black"`.
223
+ Context, cost, Git metrics, and username use the state/multi-style defaults below.
152
224
 
153
- An invalid root format falls back to the built-in root format. An invalid module format or style falls back only for that module. `/starship status` reports warnings.
225
+ ### State-selected styles
226
+
227
+ `context` and `cost` select the last entry at the highest threshold less than or equal to the current
228
+ value. A later entry wins when thresholds are equal. Each display entry requires a finite `threshold`,
229
+ a valid `style`, and boolean `hidden`. Invalid entries warn and are ignored; module defaults are used
230
+ if none remain.
231
+
232
+ The default context thresholds are hidden at `0`, `bold green` at `30`, `bold yellow` at `60`, and
233
+ `bold red` at `80`. The default cost thresholds are hidden at `0`, `bold yellow` at `1`, and `bold red`
234
+ at `5`:
235
+
236
+ ```toml
237
+ [[cost.display]]
238
+ threshold = 0
239
+ style = "bold green"
240
+ hidden = true
241
+
242
+ [[cost.display]]
243
+ threshold = 1
244
+ style = "bold yellow"
245
+ hidden = false
246
+
247
+ [[cost.display]]
248
+ threshold = 5
249
+ style = "bold red"
250
+ hidden = false
251
+ ```
252
+
253
+ `git_metrics` exposes `$added_style` and `$deleted_style` in its module format. `username` still uses
254
+ `$style` in its format, but selects `style_user` or `style_root` from private execution metadata; the
255
+ selector is not a format variable.
256
+
257
+ ### Breaking palette migration
258
+
259
+ The previous implicit `tokyo-night` palette and its `lead`, `header`, `header_fg`, `directory`,
260
+ `directory_fg`, `git`, `git_fg`, `runtime`, `runtime_fg`, `meter`, `meter_fg`, and `extension` aliases
261
+ were removed. Existing files are not rewritten. Old alias-based module styles warn and fall back to
262
+ the module's new direct-color default; alias-based literal Powerline groups warn and render unstyled.
263
+
264
+ Choose one migration:
265
+
266
+ 1. Replace old aliases with direct styles such as `cyan bold`, `bold bright-yellow`, or
267
+ `fg:#e3e5e5 bg:#769ff0`.
268
+ 2. Define every needed alias under your own `[palettes.<name>]` table and explicitly select it with
269
+ `palette = "<name>"`.
270
+ 3. Use **Restore built-in…** from `/starship` to review and replace the complete document with the new
271
+ plain nine-module configuration.
272
+
273
+ There is no hidden compatibility overlay or automatic migration.
154
274
 
155
275
  ## 🧱 Modules
156
276
 
@@ -162,7 +282,8 @@ An invalid root format falls back to the built-in root format. An invalid module
162
282
  | `thinking` | `$symbol`, `$level` | Thinking level |
163
283
  | `directory` | `$symbol`, `$path`, `$full_path` | Current working directory |
164
284
  | `git_worktree` | `$symbol`, `$name`, `$path` | Linked worktree name and top-level path |
165
- | `git_branch` | `$symbol`, `$branch`, `$remote_name`, `$remote_branch`, `$pr` | Branch, upstream, and actionable PR state |
285
+ | `git_branch` | `$symbol`, `$branch`, `$remote_name`, `$remote_branch` | Local branch and upstream |
286
+ | `github_pr` | `$symbol`, `$number`, `$link`, `$state`, `$checks`, `$review`, `$status` | Current-branch GitHub pull request |
166
287
  | `git_commit` | `$symbol`, `$hash`, `$tag` | Seven-character HEAD hash and optional exact tag |
167
288
  | `git_state` | `$symbol`, `$state`, `$progress_current`, `$progress_total` | Rebase, merge, revert, cherry-pick, bisect, or mail-apply state |
168
289
  | `git_metrics` | `$symbol`, `$added`, `$deleted` | Added/deleted line totals from the working tree diff |
@@ -208,11 +329,10 @@ An invalid root format falls back to the built-in root format. An invalid module
208
329
  - Cache `$read` and `$write` are cumulative. `$rate` uses only the latest assistant prompt:
209
330
  `cacheRead / (input + cacheRead + cacheWrite) * 100`. The module is empty when Pi has reported no
210
331
  cache reads or writes.
211
- - `cache` is disabled by default, but the built-in root format already contains `$cache`; users who
212
- inherit that format can enable it with only `[cache] disabled = false`. A custom root format must
213
- reference `$cache` or `$all` normally.
214
- - Context `$percentage` uses native one-decimal precision. For a native-style display, use
215
- `format = "[$symbol $percentage/$window ]($style)"` under `[context]`; the module name remains
332
+ - `cache` is disabled and absent from the built-in root. Enable it and add `$cache` to a custom root
333
+ format (or use `$all`) to display it.
334
+ - Context `$percentage` uses native one-decimal precision. Its default display hides values below 30%;
335
+ customize `[[context.display]]` when lower values should remain visible. The module name remains
216
336
  `context`, not `context_usage`.
217
337
  - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`. The dollar
218
338
  value is usage cost, not proof of an amount billed under a subscription.
@@ -248,12 +368,61 @@ truncation-direction setting.
248
368
 
249
369
  `git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format. Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default. `$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
250
370
 
251
- If `$git_branch.$pr` is present in the module format, its selected PR token is removed from `extension_status` to avoid duplication.
371
+ ### πŸ”Ž Native GitHub pull requests
372
+
373
+ `$github_pr` is independent of `pi-github-pr`; installing that extension is not required. It runs one
374
+ bounded GitHub CLI query for the current branch:
375
+
376
+ ```text
377
+ gh pr view --json number,isDraft,url,state,closedAt,mergedAt,reviewDecision,statusCheckRollup
378
+ ```
379
+
380
+ Install and authenticate `gh` first:
381
+
382
+ ```bash
383
+ gh auth login
384
+ ```
385
+
386
+ For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository
387
+ remote, for example `gh auth login --hostname github.example.com`. pi-starship starts `gh` directly
388
+ with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves
389
+ the correct repository and host from the current checkout. It never mutates Pi's environment, calls
390
+ the GitHub API directly, or manages tokens.
391
+
392
+ Variables have these values:
393
+
394
+ - `$number`: digits such as `123`.
395
+ - `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL, otherwise plain `#123`.
396
+ - `$state`: `open`, `draft`, `merged`, or `closed`.
397
+ - `$checks`: `checks passing`, `<n> failing`, `<n> pending`, or `no checks`.
398
+ - `$review`: `approved`, `changes requested`, `review required`, or empty when unknown.
399
+ - `$status`: one compact result selected in this order: merged, closed, draft, failing, changes
400
+ requested, pending, approved, review required, passing, then no checks.
401
+
402
+ The query runs only in TUI sessions when the enabled module is reachable from the root format. It
403
+ refreshes at session start, immediately after a branch change, after each agent run, after accepted
404
+ settings changes, and every 60 seconds. Each query has a 10-second timeout. Branch changes clear the
405
+ old PR before querying the new branch. Closed and merged PRs remain visible for 24 hours, then expire
406
+ without waiting for the next refresh. Missing `gh`, missing authentication, no current PR, timeout,
407
+ malformed or oversized output, and network failures all render an empty module without exposing raw
408
+ errors or credentials.
409
+
410
+ The query sends the repository/current-branch context through authenticated `gh` to the GitHub host
411
+ configured by the repository. It requests only the fields aboveβ€”never comments, review bodies,
412
+ inline comments, or review threads. Footer rendering and previews read only the immutable cached
413
+ snapshot and perform no network or subprocess work.
414
+
415
+ **Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic
416
+ migration. Replace it with root `$github_pr` and an optional `[github_pr]` table. If `pi-github-pr`
417
+ remains installed, its independent `github-pr` status can also appear under `$extension_status`;
418
+ disable or remove that extension when adopting the native module to avoid duplicate information.
252
419
 
253
420
  ### πŸ“¦ Package and language modules
254
421
 
255
- The native behavior is inspired by Starship pinned at
256
- `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; it is not complete Starship compatibility.
422
+ Module behavior is inspired by Starship pinned at
423
+ `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved
424
+ multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`. This is not
425
+ complete Starship module or configuration compatibility.
257
426
 
258
427
  | Area | Adopted | Adapted | Intentionally omitted |
259
428
  | --- | --- | --- | --- |
@@ -346,19 +515,22 @@ whole-catalog layout is intended. There is no `line_break` module; use literal n
346
515
 
347
516
  ### πŸ”„ Cached refresh lifecycle
348
517
 
349
- Workspace and Git readers start only in TUI sessions and only for reachable enabled modules. Root
350
- format reachability, `$all`, module `disabled`, and module-format variables determine file and command
351
- requirements. Refreshes run at session start, after accepted settings, branch changes, tool/turn
352
- completion, and a 30-second fallback. One read runs with at most one latest pending refresh; immutable
353
- snapshot equality suppresses redraws, and session/config generations reject stale results. Shutdown,
354
- replacement, and footer disposal stop timers, clear pending work, and prevent late publication.
355
- Execution identity is retained rather than re-read by the periodic fallback. Render and live preview
356
- consume snapshots synchronously and perform zero reads or commands.
518
+ Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled
519
+ modules. Root format reachability, `$all`, module `disabled`, and module-format variables determine
520
+ file and command requirements. Workspace/Git refreshes run at session start, after accepted settings,
521
+ branch changes, tool/turn completion, and a 30-second fallback. GitHub PR uses the narrower lifecycle
522
+ and 60-second network refresh described above. One read runs with at most one latest pending refresh;
523
+ immutable snapshot equality suppresses redraws, and session/request generations reject stale results.
524
+ Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command
525
+ work before starting replacements; disabling `github_pr` also stops its query and timers. Bounded local
526
+ filesystem operations may finish, but stale generations cannot publish them. Execution identity is
527
+ retained rather than re-read by the periodic fallback. Render and live preview consume snapshots
528
+ synchronously and perform zero reads or commands.
357
529
 
358
530
  Missing, unreadable, malformed, oversized, timed-out, or unavailable sources fail to empty values.
359
- Readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make
360
- no network calls. Package's explicitly documented Cargo lookup is the only ancestor walk and is capped
361
- at eight parents.
531
+ Workspace/Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never
532
+ recurse, and make no network calls. The native GitHub PR query is the documented network exception.
533
+ Package's explicitly documented Cargo lookup is the only ancestor walk and is capped at eight parents.
362
534
 
363
535
  ## πŸ’¬ Commands
364
536
 
@@ -369,12 +541,21 @@ at eight parents.
369
541
  | `/starship status` | Show config source/path and diagnostics |
370
542
  | `/starship help` | Show command and configuration help |
371
543
 
372
- The standard main menu keeps frequent goals visible: **Customize footer**, **Check configuration**,
373
- and **Help**. It shows whether the footer uses the built-in or custom document and displays the
374
- current warning count. **Advanced** contains uncommon details and the confirmed restore action, with
375
- an explicit **Back** path. The TOML editor and live footer previews remain specialized extension UI.
544
+ The standard main menu keeps six goals on one level: **Customize footer**, **Explain footer**,
545
+ **Modules**, **Configuration**, **Help**, and **Restore built-in…**. It shows whether the footer uses
546
+ built-in defaults, a saved built-in document, a custom document, or an error-driven fallback,
547
+ together with the current health. Explain and Modules are menu-only read paths; they do not add
548
+ textual subcommands or change RPC, print, or JSON protocols. Restore remains last and unavailable
549
+ when there is no document to replace.
550
+
551
+ The TOML editor, adaptive live footer previews, Explain view, and searchable module inspector remain
552
+ specialized extension UI. Their hints follow Pi's injected keybindings; list and detail content stay
553
+ bounded across terminal resize. Escape returns from detail or to the main menu, while Ctrl+C closes
554
+ the whole workflow.
376
555
 
377
- Status and help remain safe in TUI, RPC, JSON, and print modes. RPC receives notifications but never opens custom terminal UI; print and JSON modes produce no ad hoc output. Footer/timer/Git lifecycle work starts only in TUI mode.
556
+ The direct routes accept no trailing arguments. Status and help remain safe in TUI, RPC, JSON, and
557
+ print modes. RPC receives notifications but never opens custom terminal UI; print and JSON modes
558
+ produce no ad hoc output. Footer/timer/Git lifecycle work starts only in TUI mode.
378
559
 
379
560
  ## πŸ“ Scope
380
561
 
@@ -393,24 +574,28 @@ modules until separately approved semantics exist.
393
574
 
394
575
  Create `src/modules/<name>.ts` with its format variables, defaults, and runtime value resolver, then register it in display order in `src/modules/catalog.ts`. Configuration names, validation variables, defaults, and `$all` ordering are derived from that catalog. Add the module to the built-in root format when it should be visible by default, then document and test its user-facing values.
395
576
 
396
- Keep `extension_status` last in the catalog so earlier modules can consume extension-owned status values without rendering duplicates.
577
+ Keep `extension_status` last in the catalog so arbitrary third-party statuses follow native module output.
397
578
 
398
579
  ## πŸ—‚οΈ Package layout
399
580
 
400
581
  - `src/index.ts` β€” Pi package entrypoint.
401
582
  - `src/pi-starship.ts` β€” extension lifecycle, cached refresh binding, live preview, and footer.
402
583
  - `src/usage.ts` β€” native-aligned session usage and cache aggregation.
403
- - `src/commands.ts` β€” goal-oriented menu, preview/confirmation, diagnostics, and compatibility routes.
584
+ - `src/commands.ts` β€” goal-oriented menu, preview/confirmation flow, diagnostics, and compatibility routes.
585
+ - `src/command-inspector.ts` β€” adaptive Explain and searchable read-only module inspection surfaces.
586
+ - `src/command-preview.ts` β€” adaptive, scrollable, keybinding-aware preview action surface.
404
587
  - `src/config.ts` β€” TOML loading, draft validation, defaults, atomic persistence, and rollback.
405
588
  - `src/format/` β€” native format/style parser and renderer.
406
589
  - `src/modules/` β€” domain module definitions, ordered registry, reachability, and width-aware renderer.
407
- - `src/modules/git/` β€” bounded Git reader plus branch, status, and worktree modules.
590
+ - `src/modules/git/` β€” bounded local Git reader plus branch, status, and worktree modules.
591
+ - `src/modules/github-pr.ts` β€” pure native GitHub PR snapshot presentation.
592
+ - `src/runtime/github-pr.ts` β€” bounded `gh` query, validation, terminal-safe links, and expiry data.
408
593
  - `src/runtime/` β€” shared refresh controller and bounded package/language/context collectors.
409
594
 
410
595
  ## πŸ”Ž Keywords
411
596
 
412
- Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, prompt cache,
413
- cache hit rate, Pi extension
597
+ Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, GitHub pull
598
+ request, prompt cache, cache hit rate, Pi extension
414
599
 
415
600
  ## πŸ“„ License
416
601
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-starship",
3
- "version": "0.43.0",
3
+ "version": "0.45.0",
4
4
  "description": "Native Starship-style TOML statusline for the Pi coding agent.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,7 +31,7 @@
31
31
  "typecheck": "tsc --noEmit"
32
32
  },
33
33
  "dependencies": {
34
- "@narumitw/pi-tui-kit": "^0.40.0",
34
+ "@narumitw/pi-tui-kit": "^0.43.0",
35
35
  "smol-toml": "^1.7.1",
36
36
  "yaml": "^2.9.0"
37
37
  },