@narumitw/pi-starship 0.60.0 → 0.62.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 +63 -6
- package/dist/chunks/chunk-43VIENBN.ts +1586 -0
- package/dist/chunks/chunk-43VIENBN.ts.map +7 -0
- package/dist/chunks/chunk-HPZTMIZS.ts +646 -0
- package/dist/chunks/chunk-HPZTMIZS.ts.map +7 -0
- package/dist/chunks/chunk-IYDZ3R2T.ts +69 -0
- package/dist/chunks/chunk-IYDZ3R2T.ts.map +7 -0
- package/dist/chunks/chunk-KP33I6BR.ts +579 -0
- package/dist/chunks/chunk-KP33I6BR.ts.map +7 -0
- package/dist/chunks/{chunk-KZZKGGFW.ts → chunk-PWTSHSP3.ts} +853 -1001
- package/dist/chunks/chunk-PWTSHSP3.ts.map +7 -0
- package/dist/chunks/{chunk-PD457PX5.ts → chunk-S2KBLHE2.ts} +75 -10
- package/dist/chunks/chunk-S2KBLHE2.ts.map +7 -0
- package/dist/chunks/chunk-XQUIQO2G.ts +20 -0
- package/dist/chunks/chunk-XQUIQO2G.ts.map +7 -0
- package/dist/chunks/{chunk-ADX4CY27.ts → chunk-XTLQ4WUL.ts} +1 -1
- package/dist/chunks/chunk-XTLQ4WUL.ts.map +7 -0
- package/dist/chunks/{cloud-EPAEV4ZB.ts → cloud-J2ZOE3HE.ts} +6 -2
- package/dist/chunks/cloud-J2ZOE3HE.ts.map +7 -0
- package/dist/chunks/command-configuration-menu-S2LXCOJG.ts +147 -0
- package/dist/chunks/command-configuration-menu-S2LXCOJG.ts.map +7 -0
- package/dist/chunks/command-settings-chat-O34BEU4X.ts +1041 -0
- package/dist/chunks/command-settings-chat-O34BEU4X.ts.map +7 -0
- package/dist/chunks/commands-ZYIJVIEJ.ts +1022 -0
- package/dist/chunks/commands-ZYIJVIEJ.ts.map +7 -0
- package/dist/chunks/{deployment-7J54EHNR.ts → deployment-NOJ2KCLI.ts} +85 -5
- package/dist/chunks/deployment-NOJ2KCLI.ts.map +7 -0
- package/dist/chunks/{development-IWJAAAEV.ts → development-T3XXVVDP.ts} +67 -15
- package/dist/chunks/development-T3XXVVDP.ts.map +7 -0
- package/dist/chunks/directory-OX6BWJZA.ts +31 -0
- package/dist/chunks/directory-OX6BWJZA.ts.map +7 -0
- package/dist/chunks/{execution-P4WZALW2.ts → execution-R2OHIP2L.ts} +8 -4
- package/dist/chunks/execution-R2OHIP2L.ts.map +7 -0
- package/dist/chunks/jujutsu-XLDYKSX2.ts +174 -0
- package/dist/chunks/jujutsu-XLDYKSX2.ts.map +7 -0
- package/dist/chunks/languages-CBQNNYXM.ts +262 -0
- package/dist/chunks/languages-CBQNNYXM.ts.map +7 -0
- package/dist/chunks/{package-H24VJEX3.ts → package-7KVAK3TC.ts} +6 -2
- package/dist/chunks/package-7KVAK3TC.ts.map +7 -0
- package/dist/chunks/system-574MHB4R.ts +165 -0
- package/dist/chunks/system-574MHB4R.ts.map +7 -0
- package/dist/index.ts +558 -150
- package/dist/index.ts.map +4 -4
- package/package.json +5 -1
- package/skills/configure-pi-starship/SKILL.md +29 -1
- package/skills/configure-pi-starship/references/configuration.md +109 -24
- package/skills/configure-pi-starship/references/module-catalog.md +278 -25
- package/skills/configure-pi-starship/references/modules.md +213 -36
- package/skills/configure-pi-starship/references/runtime-and-security.md +88 -28
- package/skills/configure-pi-starship/scripts/config-path.mjs +63 -3
- package/src/command-configuration-menu.ts +155 -0
- package/src/command-configuration.ts +9 -84
- package/src/command-preview.ts +3 -3
- package/src/command-settings-chat.ts +210 -0
- package/src/commands.ts +54 -98
- package/src/config/module-options.ts +112 -0
- package/src/config.ts +17 -53
- package/src/effective-config.ts +5 -4
- package/src/format/bounded-regex.ts +66 -0
- package/src/format/version.ts +24 -0
- package/src/modules/catalog.ts +10 -0
- package/src/modules/cloud.ts +1 -0
- package/src/modules/deployment.ts +8 -0
- package/src/modules/development.ts +20 -2
- package/src/modules/directory.ts +171 -51
- package/src/modules/execution.ts +2 -0
- package/src/modules/git/branch.ts +19 -4
- package/src/modules/git/commit.ts +9 -2
- package/src/modules/git/metrics.ts +9 -4
- package/src/modules/git/runtime.ts +122 -33
- package/src/modules/git/state.ts +23 -2
- package/src/modules/git/status-templates.ts +58 -0
- package/src/modules/git/status.ts +96 -30
- package/src/modules/jujutsu.ts +225 -0
- package/src/modules/languages.ts +26 -2
- package/src/modules/package.ts +1 -0
- package/src/modules/render.ts +42 -16
- package/src/modules/system.ts +54 -0
- package/src/modules/time-format.ts +188 -0
- package/src/modules/time.ts +11 -5
- package/src/modules/types.ts +42 -4
- package/src/pi-starship.ts +56 -12
- package/src/profile-store.ts +5 -0
- package/src/runtime/cloud.ts +3 -0
- package/src/runtime/command.ts +1 -1
- package/src/runtime/deployment.ts +120 -4
- package/src/runtime/development.ts +86 -13
- package/src/runtime/directory.ts +33 -0
- package/src/runtime/execution.ts +12 -2
- package/src/runtime/helpers.ts +57 -8
- package/src/runtime/jujutsu.ts +225 -0
- package/src/runtime/languages.ts +106 -19
- package/src/runtime/package.ts +3 -0
- package/src/runtime/system.ts +202 -0
- package/src/runtime/types.ts +3 -0
- package/src/runtime/version-requirements.ts +30 -0
- package/src/runtime/workspace.ts +12 -1
- package/src/settings-agent.ts +80 -0
- package/src/settings-chat-transcript.ts +140 -0
- package/src/settings-chat-ui.ts +426 -0
- package/src/settings-draft.ts +260 -0
- package/src/settings-snapshots.ts +41 -0
- package/dist/chunks/chunk-ADX4CY27.ts.map +0 -7
- package/dist/chunks/chunk-KZZKGGFW.ts.map +0 -7
- package/dist/chunks/chunk-PD457PX5.ts.map +0 -7
- package/dist/chunks/cloud-EPAEV4ZB.ts.map +0 -7
- package/dist/chunks/commands-C2VJ6ZBN.ts +0 -3374
- package/dist/chunks/commands-C2VJ6ZBN.ts.map +0 -7
- package/dist/chunks/deployment-7J54EHNR.ts.map +0 -7
- package/dist/chunks/development-IWJAAAEV.ts.map +0 -7
- package/dist/chunks/execution-P4WZALW2.ts.map +0 -7
- package/dist/chunks/languages-JO6R2PHL.ts +0 -168
- package/dist/chunks/languages-JO6R2PHL.ts.map +0 -7
- package/dist/chunks/package-H24VJEX3.ts.map +0 -7
- package/src/command-inspector.ts +0 -41
|
@@ -9,6 +9,20 @@ disable-model-invocation: true
|
|
|
9
9
|
|
|
10
10
|
Answer pi-starship configuration questions or make the requested `pi-starship.toml` change.
|
|
11
11
|
|
|
12
|
+
## Hosted preview-only chat
|
|
13
|
+
|
|
14
|
+
When the host explicitly supplies an owned draft path and identifies this as the hosted preview-only workflow, use this section instead of the standalone path-resolution and publication steps below.
|
|
15
|
+
Read and edit only that draft for configuration changes; never write or edit the active settings file.
|
|
16
|
+
The host provides `read`, `write`, and `edit`, validates each completed mutation, and updates the footer preview without `/reload`.
|
|
17
|
+
Read the relevant bundled references using their paths relative to this skill directory.
|
|
18
|
+
Use `read` before `edit`, preserve comments and unknown fields, and repair errors reported by the host.
|
|
19
|
+
A rejected preview can leave invalid text in the draft; fix that text rather than assuming the write was rolled back.
|
|
20
|
+
Do not run or request the resolver, validator, backup, or apply scripts in this workflow.
|
|
21
|
+
Do not request shell access, publish settings, or tell the user that settings were saved.
|
|
22
|
+
Only the user can choose the host's reviewed Save draft as profile action and enter its name.
|
|
23
|
+
The host then asks separately whether to apply the saved profile; declining keeps the profile without changing active settings.
|
|
24
|
+
Closing or discarding before that user save does not save the preview.
|
|
25
|
+
|
|
12
26
|
## Choose the task path
|
|
13
27
|
|
|
14
28
|
For a configuration question, load only the smallest relevant reference and answer with the exact supported names, values, defaults, and behavior.
|
|
@@ -47,9 +61,23 @@ Read [runtime and security](references/runtime-and-security.md) before enabling
|
|
|
47
61
|
|
|
48
62
|
Use an explicit user-provided path when present.
|
|
49
63
|
|
|
50
|
-
Otherwise resolve the active path through Pi's `getAgentDir()` API
|
|
64
|
+
Otherwise resolve the active path through Pi's `getAgentDir()` API with the bundled resolver:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
skill_dir="<directory containing this SKILL.md>"
|
|
68
|
+
node "$skill_dir/scripts/config-path.mjs"
|
|
69
|
+
```
|
|
51
70
|
|
|
71
|
+
Keep the current working directory unchanged so relative agent-directory settings retain their meaning.
|
|
52
72
|
The resolver prints a JSON string containing the exact absolute path, including correct expansion of a configured `~`.
|
|
73
|
+
It first resolves Pi from the skill's module tree; when Pi is absent there, it resolves beside the first `pi` executable on `PATH`, following symbolic links.
|
|
74
|
+
This supports separate npm or Bun global Pi installations without assuming a fixed global directory.
|
|
75
|
+
Make sure `PATH` selects the intended Pi installation when multiple installations exist.
|
|
76
|
+
Shell wrappers or compiled launchers without a nearby Pi package can still fail resolution.
|
|
77
|
+
|
|
78
|
+
If resolution fails, report the error and stop before reading or writing a guessed settings path.
|
|
79
|
+
Ask for the exact settings path or the intended Pi executable to be made available on `PATH`.
|
|
80
|
+
Do not install another Pi copy, modify `node_modules`, hard-code a Bun global directory, or use an ad hoc loader hook to bypass the failure.
|
|
53
81
|
|
|
54
82
|
Read the existing document before editing it.
|
|
55
83
|
|
|
@@ -23,33 +23,52 @@ Open the interactive menu in TUI mode:
|
|
|
23
23
|
/starship
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
Choose **
|
|
26
|
+
Choose **Configure with agent** for edits and explanations.
|
|
27
|
+
The compatibility command `/starship settings` retains the raw TOML editor.
|
|
27
28
|
Closing the editor validates the draft and opens a scrollable preview with **Apply changes…**, **Continue editing**, and **Discard draft**.
|
|
28
29
|
Saving requires separate confirmation, then atomically updates the file and active footer.
|
|
29
30
|
Manual TOML edits load at the next `session_start`, including `/reload` and session replacement.
|
|
30
31
|
Cancellation, disposal, invalid drafts, write failures, and runtime application failures preserve the previous file and footer.
|
|
31
32
|
|
|
32
|
-
|
|
33
|
+
Choose **Configure with agent** for a separate, temporary configuration conversation with the bundled skill and `read`, `write`, and `edit` tools.
|
|
34
|
+
The agent can write only its private draft, not the active settings file; validated mutations update the preview without `/reload`, and invalid mutations retain the last valid preview.
|
|
35
|
+
Reads cover immutable disk and loaded-document snapshots, normalized active public TOML, source/path/health/diagnostics, module inspection, the private draft, and bundled skill/source documents; the draft is limited to 64 KiB.
|
|
36
|
+
These read-only documents are fixed at chat opening and do not change with draft previews or later runtime updates.
|
|
37
|
+
The disk baseline can differ from the loaded document after external edits; normalized TOML excludes comments, unknown fields, parser ASTs, and private selectors while preserving effective replacement order.
|
|
38
|
+
Module inspection includes states, current previews, reachability, variables, style-rule metadata, display rules, and reasons from existing runtime data without starting collectors.
|
|
39
|
+
When runtime inspection or loaded text is unavailable, report that limit instead of guessing.
|
|
40
|
+
The ordinary main-session skill has no live runtime access; direct active-state questions to this hosted chat.
|
|
41
|
+
The preview uses cached data without starting module commands or network requests.
|
|
42
|
+
During a response, normal submission queues steering for the next assistant turn; the configured app.message.followUp action queues work after natural completion and submits normally when idle.
|
|
43
|
+
The app.message.dequeue action restores pending messages to the editor; these message actions use Pi's native precedence, including explicit history bindings.
|
|
44
|
+
The configured cancel action stops a response and restores undelivered messages, or opens review when idle; editor actions win review-key collisions, with Escape as a review fallback unless assigned to an editor action.
|
|
45
|
+
Failed or aborted responses restore undelivered input without automatic restart.
|
|
46
|
+
Ctrl+C discards the flow, clears both queues, and restores the active footer unless its session was replaced.
|
|
47
|
+
When idle with a valid draft, Ctrl+S opens the Save draft as profile flow directly; its gray editor-border hint switches to F2 if Ctrl+S is reserved, or is omitted when both keys conflict.
|
|
48
|
+
The review menu retains the same save action.
|
|
49
|
+
Saving requires exact-draft review and a profile name; invalid or existing names are rejected without overwriting a profile.
|
|
50
|
+
After saving, the host asks whether to apply that profile through managed History and atomic replacement; declining keeps the profile without changing active settings.
|
|
51
|
+
Cancelling naming returns to the chat without saving; closing or session replacement removes the temporary draft, not any saved profile.
|
|
52
|
+
Application checks the initial disk snapshot, loaded revision, and saved profile identity, blocks detected concurrent changes, and warns before explicitly repairing an invalid original.
|
|
53
|
+
Chat content and settings read by the agent go to the selected model provider; the child uses the opening model/thinking selection with Pi authentication, has no shell tool, and does not persist its transcript or change the main conversation.
|
|
54
|
+
The fullscreen view uses Pi's native user/assistant/tool message components. Short gray status and control labels sit on the editor borders; the live preview ends at the terminal bottom, in the saved footer's position.
|
|
55
|
+
It shows recent output with expanded, read-only tool results; review actions expose the complete transcript and exact draft.
|
|
56
|
+
Choose **Continue** to leave a document/transcript review; cancelling the review discards the flow without publishing.
|
|
57
|
+
|
|
58
|
+
Outside this hosted chat, the bundled `configure-pi-starship` skill uses a separate external-edit workflow.
|
|
33
59
|
Before its apply script replaces an existing document, it preserves the inspected document under `<getAgentDir()>/pi-starship/pi-starship-YYYYMMDDHHmm.toml`; these backups use local time and remain after a successful apply.
|
|
34
60
|
Backups are written and flushed under a private temporary name, atomically renamed to their final private file, and followed by flushes of the backup directory and its parent directory before publication continues; a recoverable failure removes the owned temporary file and preserves the active document.
|
|
35
61
|
If configuration publication fails after that backup is durable, the failure reports its retained path; cleanup failures report both their operation and cause without hiding the primary failure.
|
|
36
62
|
A missing document creates no backup, and a backup with the same minute name blocks publication when observed before rename; this check does not provide cross-process locking.
|
|
37
63
|
The interactive `/starship` flows do not invoke this script. They preserve replaced documents in the separate recovery history described below; existing skill backups remain available read-only in History.
|
|
38
64
|
|
|
39
|
-
The main menu
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
Module detail shows the current preview when available, description, root reference and reachability, format variables, style fields, supported style-rule selectors, configured rule count, display rules, and the known reason for absent output.
|
|
44
|
-
Both views are read-only and do not create or update the settings document.
|
|
45
|
-
|
|
46
|
-
Configuration contains **Overview**, **Effective configuration**, **Settings document**, **Reload from disk**, **History**, **Share settings as Gist…**, and **Import settings from Gist…** on one nested level.
|
|
65
|
+
The main menu orders **Configure with agent**, **Presets**, **Profiles**, **Configuration**, **Restore built-in…**, and **Help**.
|
|
66
|
+
Configuration shows state, source, settings path, health, and all current warnings above **Reload from disk…**, **Share settings as Gist…**, **Import settings from Gist…**, and **History**.
|
|
67
|
+
Configured selection page-up/page-down actions scroll the summary without moving the selected action; selection and cancellation bindings take priority when bindings conflict.
|
|
68
|
+
The focused action remains visible at small terminal heights; enlarge an extremely short terminal to read the summary.
|
|
47
69
|
Gist actions use `gh` authentication for github.com and transfer only `pi-starship.toml`, limited to 64 KiB; sharing includes comments and unknown fields and requires review and confirmation before creating an unlisted Gist.
|
|
48
70
|
Unlisted Gists are readable by anyone with the link; remove sensitive data before sharing, and check GitHub before retrying a cancelled or failed upload because a remote Gist may already exist.
|
|
49
71
|
Import accepts a Gist ID or URL, validates the complete document, requires raw TOML review, footer preview, and full-replacement confirmation, and preserves the previous document before applying; review untrusted settings for command execution and network access before accepting.
|
|
50
|
-
Overview combines state, source, path, health, and bounded diagnostics.
|
|
51
|
-
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.
|
|
52
|
-
Settings document shows the exact loaded UTF-8 text through a terminal-safe, cell-aware read-only review without changing the raw payload.
|
|
53
72
|
A missing file is **Built-in defaults**, an exact bundled document uses its preset name, and read or parse errors are **Built-in fallback**.
|
|
54
73
|
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.
|
|
55
74
|
A deleted document is a valid previewable transition to built-in defaults and creates no file.
|
|
@@ -93,7 +112,7 @@ The native Pi editor has no public abort method; session cancellation removes th
|
|
|
93
112
|
### Recovery history
|
|
94
113
|
|
|
95
114
|
Managed active-file replacements preserve the previous document in `<getAgentDir()>/pi-starship/history/<timestamp>-<random-id>.toml` before writing the replacement.
|
|
96
|
-
Editor, preset, profile, restore, and Gist application use this policy.
|
|
115
|
+
Editor, configuration-chat save, preset, profile, restore, and Gist application use this policy.
|
|
97
116
|
A missing file or a byte-identical no-op creates no recovery copy.
|
|
98
117
|
Backup failure blocks replacement; runtime-application failure attempts guarded disk/runtime restoration and retains the backup.
|
|
99
118
|
A recovery copy can therefore come from an unsuccessful application attempt; it is not proof that a candidate was applied.
|
|
@@ -237,12 +256,13 @@ styles = { "foo:*" = "bold green", "foo:error" = "bold red", fallback = "dimmed
|
|
|
237
256
|
|
|
238
257
|
Every module table supports `format`, `symbol`, and `disabled`.
|
|
239
258
|
Most modules also support one `style`.
|
|
240
|
-
The exceptions
|
|
259
|
+
The exceptions include Git/Jujutsu metrics (`added_style` and `deleted_style`), `jj_change` (prefix/suffix/offset styles), `username` (`style_user` and `style_root`), and threshold-selected `context`, `cost`, and `battery` `display` arrays.
|
|
260
|
+
Directory root/read-only styles and Node.js/Go requirement styles supplement their ordinary `style`; see [module behavior](modules.md).
|
|
241
261
|
`thinking` retains its `style` fallback and also accepts the per-level overrides documented below.
|
|
242
262
|
Module-specific options are catalog-owned and type-checked; unknown options warn and stay inactive.
|
|
243
|
-
Version formats
|
|
244
|
-
Detection arrays
|
|
245
|
-
|
|
263
|
+
[Version formats](#version-formats) support raw and numeric component variables.
|
|
264
|
+
Detection arrays inspect one bounded listing of the current directory; replacement and fallback rules are [module-specific](modules.md#reachability-and-collection-rules).
|
|
265
|
+
Language and Kubernetes file detectors support leading `!` rejection rules; [environment detectors](modules.md#environment-detection-and-messages) have separate presence rules.
|
|
246
266
|
`[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
|
|
247
267
|
Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`.
|
|
248
268
|
An empty configured icon suppresses only the icon.
|
|
@@ -283,11 +303,14 @@ The exact accepted style fields, display arrays, module-specific options, defaul
|
|
|
283
303
|
A standard `style` field must be a valid style string.
|
|
284
304
|
`thinking` accepts `style` plus `style_off`, `style_minimal`, `style_low`, `style_medium`, `style_high`, `style_xhigh`, and `style_max`.
|
|
285
305
|
`provider`, `model`, and `thinking` additionally accept the ordered `style_rules` arrays described under [Content-selected styles](#content-selected-styles).
|
|
286
|
-
`git_metrics`
|
|
306
|
+
`git_metrics` and `jj_metrics` accept `added_style` and `deleted_style` instead of `style`.
|
|
307
|
+
`jj_change` accepts `prefix_style`, `suffix_style`, and `change_offset_style` instead of `style`.
|
|
308
|
+
`directory` additionally accepts `repo_root_style`, `before_repo_root_style`, and `read_only_style`.
|
|
309
|
+
`nodejs` and `golang` additionally accept `not_capable_style`; its exact default `"none"` disables requirement checks.
|
|
287
310
|
`username` accepts `style_user` and `style_root` instead of `style`.
|
|
288
|
-
`context` and `
|
|
311
|
+
`context`, `cost`, and `battery` accept `display` arrays instead of a direct `style` field.
|
|
289
312
|
|
|
290
|
-
`[[context.display]]` and `[[
|
|
313
|
+
`[[context.display]]`, `[[cost.display]]`, and `[[battery.display]]` entries require these typed fields:
|
|
291
314
|
|
|
292
315
|
```toml
|
|
293
316
|
threshold = 60 # finite number
|
|
@@ -313,13 +336,71 @@ Module-specific options use these validation rules:
|
|
|
313
336
|
| string enum | An exact case-sensitive listed string. |
|
|
314
337
|
| boolean | A TOML boolean, not a quoted string. |
|
|
315
338
|
| integer | An integer inside the inclusive range listed in the module catalog. |
|
|
339
|
+
| number | A finite number inside the inclusive range listed in the module catalog; fractions are accepted. |
|
|
316
340
|
| string array | An array containing only non-empty strings. |
|
|
317
341
|
| string-to-string table | A TOML table whose values are all strings. |
|
|
342
|
+
| command alternatives | One command string, or at most 16 command strings/argv arrays; see below. |
|
|
343
|
+
| context rules | At most 64 ordered Kubernetes rule tables; see below. |
|
|
344
|
+
| substitutions | A legacy string-to-string table or at most 64 ordered structured rows; see below. |
|
|
318
345
|
|
|
319
|
-
Language `detect_files`, `detect_extensions`, and `detect_folders` arrays allow entries beginning with `!` as rejection rules.
|
|
346
|
+
Language and Kubernetes `detect_files`, `detect_extensions`, and `detect_folders` arrays allow entries beginning with `!` as rejection rules.
|
|
347
|
+
`detect_env_vars` allows negation for `python`, `conda`, `direnv`, `gcloud`, `hostname`, and `kubernetes`; `username` retains positive-only detection.
|
|
320
348
|
Other string-array options reject entries beginning with `!`.
|
|
321
349
|
Detection fallback and replacement behavior differs by module and is specified in [module behavior](modules.md).
|
|
322
350
|
|
|
351
|
+
### Version formats
|
|
352
|
+
|
|
353
|
+
`version_format` applies to package, language, Pixi, and Terraform/OpenTofu versions and defaults to `v$raw`.
|
|
354
|
+
It uses the [format grammar](#-format-grammar): `$raw`, `$major`, `$minor`, `$patch`, their `${name}` forms, escapes, and conditional groups, but returns plain text without ANSI styles.
|
|
355
|
+
One leading lowercase `v` is removed from `$raw`; suffixes and leading zeroes remain in that raw value.
|
|
356
|
+
Numeric components are available only for a dotted numeric release with an optional suffix matching `[-+][0-9A-Za-z.+_-]+` or `[A-Za-z][0-9A-Za-z.+_-]*`.
|
|
357
|
+
A single numeric component is valid; missing minor/patch values are empty, extra components after patch are ignored, and component leading zeroes are removed.
|
|
358
|
+
For example, `01.002.0003-rc1` exposes `1`, `2`, `3`, and raw `01.002.0003-rc1`; malformed `1..2` exposes only raw text.
|
|
359
|
+
Unknown variables render empty, and an empty template hides the version.
|
|
360
|
+
Custom formats now use formatter variable boundaries and escapes, not raw substring replacement: use `${raw}_suffix` for appended identifier text and `\$` for a literal dollar sign.
|
|
361
|
+
Malformed format syntax or a template over 4,096 characters falls back to `v` plus the raw value.
|
|
362
|
+
Python's explicit pyenv-label mode bypasses this formatter.
|
|
363
|
+
|
|
364
|
+
### Bounded regex and structured options
|
|
365
|
+
|
|
366
|
+
Directory regex substitutions and Kubernetes context patterns use RE2JS, not JavaScript's backtracking regex engine.
|
|
367
|
+
Patterns are limited to 512 source characters; input and replacement strings to 4,096 characters; replacement output to 8,192 characters; the cache retains at most 64 compiled patterns, including invalid-pattern entries.
|
|
368
|
+
Backreferences and lookaround are unsupported and rejected.
|
|
369
|
+
Replacement fields are `$1`/`${1}`, `$name`/`${name}`, or `$$` for a literal dollar; unknown captures become empty.
|
|
370
|
+
These are regex capture fields, not footer module variables.
|
|
371
|
+
|
|
372
|
+
`directory.substitutions` accepts either an ordered legacy literal map or ordered `{ from, to, regex }` rows.
|
|
373
|
+
Each structured row requires string `from` (at most 512 characters) and `to` (at most 4,096 characters); optional boolean `regex` defaults to `false`.
|
|
374
|
+
No other row keys are accepted; empty `from`/`to` strings are allowed.
|
|
375
|
+
Literal rules replace all occurrences with literal text and skip empty search strings; regex rules replace only the first match, including an empty regex match.
|
|
376
|
+
The legacy map has no schema row/string bound, but rendering skips the complete sequence when it has more than 64 rules; all sequences have a 16,384-character intermediate path bound.
|
|
377
|
+
See [directory behavior](modules.md#directory-git-and-environment-contraction) for order and runtime-failure fallback.
|
|
378
|
+
|
|
379
|
+
`kubernetes.contexts` requires `context_pattern` and allows only `user_pattern`, `context_alias`, `user_alias`, `symbol`, and `style` as optional strings.
|
|
380
|
+
Both patterns use the 512-character bound; other strings use the 4,096-character bound, and `style` must be a valid style under the selected palette.
|
|
381
|
+
Rules match bounded source context/user labels before aliases with AND and first-match semantics; [Kubernetes behavior](modules.md#kubernetes-detection-and-context-rules) defines exact-match precedence and alias order.
|
|
382
|
+
An invalid row, unsupported regex, unknown row key, or oversized array rejects the entire corresponding substitutions/rules option with a warning and restores its default, not just the failing row.
|
|
383
|
+
Unknown document fields still remain on disk.
|
|
384
|
+
|
|
385
|
+
### Python command alternatives
|
|
386
|
+
|
|
387
|
+
`python_binary = []` preserves the existing active-virtualenv interpreter or `python` fallback.
|
|
388
|
+
A scalar such as `python_binary = "python3"` becomes one alternative; a non-empty array replaces that choice, for example `python_binary = ["python3", ["py", "-3"]]`.
|
|
389
|
+
Each string is one executable name/path, not a shell command line; each nested argv array contains 1–16 elements including its executable.
|
|
390
|
+
A flat string array lists alternative executables, not arguments to one executable.
|
|
391
|
+
There can be at most 16 alternatives, and each element must contain 1–1,024 characters without C0/C1 controls (`U+0000`–`U+001F`, `U+007F`–`U+009F`).
|
|
392
|
+
The runner appends `--version`, never starts an implicit shell, and stops at the first successful command even if its version output is malformed.
|
|
393
|
+
Invalid settings warn and restore the empty-array default.
|
|
394
|
+
Only use trusted executables and arguments: direct argv execution does not make a configured program safe.
|
|
395
|
+
|
|
396
|
+
### Status templates
|
|
397
|
+
|
|
398
|
+
Git's 20 status options and Jujutsu status options use the normal format grammar with at most 4,096 characters and 16 nested groups.
|
|
399
|
+
Static group styles and the selected palette are supported; style variables such as `$style` are not.
|
|
400
|
+
Counted states accept only `$count`/`${count}`; Git `diverged` accepts only `ahead_count` and `behind_count`; clean/boolean/description templates accept no variables.
|
|
401
|
+
Invalid templates warn and restore that field's default; empty templates suppress that state.
|
|
402
|
+
See [Git status behavior](modules.md#git-display-controls-and-status-templates) and [Jujutsu behavior](modules.md#jujutsu-modules) for count formatting, activation, and ordering.
|
|
403
|
+
|
|
323
404
|
### Diagnostic and fallback behavior
|
|
324
405
|
|
|
325
406
|
| Failure | Result |
|
|
@@ -396,7 +477,7 @@ An invalid root format falls back to the built-in root format; an invalid module
|
|
|
396
477
|
`/starship status` reports warnings.
|
|
397
478
|
|
|
398
479
|
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"`.
|
|
399
|
-
Context, cost,
|
|
480
|
+
Context, cost, battery, metrics, Jujutsu IDs, and username use state/multi-style fields; see below and the [complete module catalog](module-catalog.md).
|
|
400
481
|
|
|
401
482
|
### Pi theme colors
|
|
402
483
|
|
|
@@ -533,7 +614,11 @@ style = "bold red"
|
|
|
533
614
|
hidden = false
|
|
534
615
|
```
|
|
535
616
|
|
|
536
|
-
`git_metrics`
|
|
617
|
+
`git_metrics` and `jj_metrics` expose `$added_style` and `$deleted_style` in their module formats.
|
|
618
|
+
`jj_change` styles its composite IDs with `prefix_style`, `suffix_style`, and `change_offset_style`.
|
|
619
|
+
`battery` uses upper bounds: it selects the lowest threshold greater than or equal to the raw charge percentage, with the first entry winning a tie; no match or `hidden = true` hides the module.
|
|
620
|
+
Its default display is visible through 10% with `red bold`, not a context-style lower-bound rule.
|
|
621
|
+
`memory_usage.threshold` is a finite number from -100 through 10,000 (default 75); it gates the rounded native RAM percentage and is not a display array.
|
|
537
622
|
`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.
|
|
538
623
|
|
|
539
624
|
### Breaking palette migration
|