@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
|
@@ -10,26 +10,32 @@ Use this authoritative public reference whenever a question or change involves a
|
|
|
10
10
|
| `provider` | `$symbol`, `$provider` | Current model provider |
|
|
11
11
|
| `model` | `$symbol`, `$model` | Current model name |
|
|
12
12
|
| `thinking` | `$symbol`, `$level` | Thinking level |
|
|
13
|
-
| `directory` | `$symbol`, `$path`, `$full_path` | Current
|
|
13
|
+
| `directory` | `$symbol`, `$path`, `$full_path`, `$before_root_path`, `$repo_root`, `$read_only` | Current directory and optional cached metadata |
|
|
14
14
|
| `git_worktree` | `$symbol`, `$name`, `$path` | Linked worktree name and top-level path |
|
|
15
15
|
| `git_branch` | `$symbol`, `$branch`, `$remote_name`, `$remote_branch` | Local branch and upstream |
|
|
16
16
|
| `github_pr` | `$symbol`, `$number`, `$link`, `$state`, `$checks`, `$review`, `$status` | Current-branch GitHub pull request |
|
|
17
|
-
| `git_commit` | `$symbol`, `$hash`, `$tag` |
|
|
17
|
+
| `git_commit` | `$symbol`, `$hash`, `$tag` | HEAD hash (seven characters by default) and optional tag |
|
|
18
18
|
| `git_state` | `$symbol`, `$state`, `$progress_current`, `$progress_total` | Rebase, merge, revert, cherry-pick, bisect, or mail-apply state |
|
|
19
19
|
| `git_metrics` | `$symbol`, `$added`, `$deleted` | Added/deleted line totals from the working tree diff |
|
|
20
20
|
| `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 |
|
|
21
|
+
| `jj_bookmark` | `$symbol`, `$bookmark`, `$remote`, `$diverged`, `$overflow_count` | Recorded Jujutsu change/ancestor bookmarks; disabled by default |
|
|
22
|
+
| `jj_change` | `$change`, `$commit`, `$change_prefix`, `$change_suffix`, `$change_offset`, `$commit_prefix`, `$commit_suffix` | Recorded Jujutsu IDs; disabled by default |
|
|
23
|
+
| `jj_metrics` | `$added`, `$deleted` | Recorded Jujutsu line totals; disabled by default |
|
|
24
|
+
| `jj_status` | `$all`, `$conflicted`, `$description`, `$hidden`, `$immutable`, `$added`, `$copied`, `$deleted`, `$modified`, `$renamed` | Recorded Jujutsu flags/counters; disabled by default |
|
|
25
|
+
| `memory_usage` | `$symbol`, `$ram`, `$ram_pct`, `$swap`, `$swap_pct` | Native system RAM and optional Linux swap; disabled by default |
|
|
26
|
+
| `battery` | `$symbol`, `$percentage` | Linux sysfs battery charge; disabled by default |
|
|
21
27
|
| `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$kind`, `$title`, `$text` | Extension UI waits, active tools, streaming, completion, or idle |
|
|
22
28
|
| `context` | `$symbol`, `$percentage`, `$tokens`, `$window` | Context-window use |
|
|
23
29
|
| `tokens` | `$symbol`, `$input`, `$output`, `$total` | Token totals |
|
|
24
30
|
| `cache` | `$symbol`, `$rate`, `$read`, `$write` | Prompt-cache reads, writes, and latest hit rate; disabled by default |
|
|
25
31
|
| `cost` | `$symbol`, `$cost`, `$subscription` | Session cost and optional `(sub)` marker |
|
|
26
|
-
| `time` | `$symbol`, `$time` |
|
|
32
|
+
| `time` | `$symbol`, `$time` | Formatted clock; local `HH:mm` by default |
|
|
27
33
|
| `turn` | `$symbol`, `$count` | User turn count |
|
|
28
34
|
| `package` | `$symbol`, `$version`, `$source` | Direct project manifest version |
|
|
29
35
|
| `nodejs` | `$symbol`, `$version`, `$engines_version` | Detected Node.js project/runtime |
|
|
30
36
|
| `python` | `$symbol`, `$version`, `$virtualenv`, `$pyenv_prefix` | Python runtime and allowlisted environment name |
|
|
31
37
|
| `rust` | `$symbol`, `$version`, `$numver`, `$toolchain` | Safe native `rustc` runtime and allowlisted toolchain name |
|
|
32
|
-
| `golang` | `$symbol`, `$version`, `$mod_version` | Go runtime
|
|
38
|
+
| `golang` | `$symbol`, `$version`, `$mod_version` | Go runtime and direct `go.mod` minimum version |
|
|
33
39
|
| `bun` / `deno` | `$symbol`, `$version` | Bun or Deno runtime |
|
|
34
40
|
| `mise` | `$symbol`, `$health` | Bounded mise health result |
|
|
35
41
|
| `direnv` | `$symbol`, `$rc_path`, `$allowed`, `$loaded` | Inert direnv status; `.envrc` is never sourced |
|
|
@@ -58,14 +64,17 @@ For exact default formats, symbols, enabled state, accepted style fields, displa
|
|
|
58
64
|
A module contributes work only when it is enabled and reachable from the root `format` directly or through `$all`.
|
|
59
65
|
Reachability activates that module's collector at module scope, even when its module format references only `$symbol`.
|
|
60
66
|
Omitting a data variable does not prevent the package, deployment, cloud, or execution collectors from reading that reachable module's allowlisted files and environment metadata.
|
|
61
|
-
Language project detection also runs at module scope
|
|
67
|
+
Language project detection also runs at module scope. Version commands, requirement-file reads, and optional Python/Rust values are variable-gated, except for explicitly enabled Node.js/Go requirement styling as described below.
|
|
62
68
|
The mise health, direnv status, Pixi version, and Terraform/OpenTofu version commands are likewise variable-gated, but their module-level detection and non-command metadata reads still occur when reachable.
|
|
69
|
+
Directory physical-path and permission probes consider the union of its main format and configured alternate root format; defaults request neither probe.
|
|
70
|
+
A reachable Jujutsu module starts one shared query even for a symbol-only format. Reachable memory/battery modules sample their native sources at module scope; swap is separately variable-gated.
|
|
63
71
|
A disabled module is absent even when the root format names it or `$all` is present.
|
|
64
72
|
|
|
65
73
|
Workspace detection uses at most one direct listing of the current working directory, stops at 2,048 entries, and never recurses.
|
|
66
74
|
A positive file, extension, or folder rule must match for direct detection to succeed.
|
|
67
|
-
Any matching `!` rule rejects the
|
|
68
|
-
|
|
75
|
+
Any matching `!` rule rejects the direct file scan before positive matches are considered.
|
|
76
|
+
Language extensions may be configured with or without a leading dot, but defaults omit the dot.
|
|
77
|
+
Kubernetes uses its distinct suffix and detector-precedence rules [below](#kubernetes-detection-and-context-rules).
|
|
69
78
|
|
|
70
79
|
For language modules, each non-empty `detect_files`, `detect_extensions`, or `detect_folders` array replaces only that category's built-in defaults.
|
|
71
80
|
An empty category keeps its built-in defaults.
|
|
@@ -83,16 +92,49 @@ For `mise`, `direnv`, and `pixi`, an empty `detect_files` uses the listed defaul
|
|
|
83
92
|
| `deno` | `deno.json`, `deno.jsonc`, `deno.lock` | none | none | `deno -V` |
|
|
84
93
|
|
|
85
94
|
Node's negative file defaults prevent Bun and Deno projects from matching Node solely through overlapping JavaScript or TypeScript files.
|
|
86
|
-
Node `$engines_version` reads only `engines.node` from a direct `package.json` and does not evaluate the constraint.
|
|
87
|
-
Python `$virtualenv` uses the basename of `VIRTUAL_ENV`, then `CONDA_DEFAULT_ENV` when no virtualenv is active.
|
|
88
|
-
Python `$pyenv_prefix` reads `PYENV_VERSION` without invoking pyenv.
|
|
89
95
|
Rust `$toolchain` reads `RUSTUP_TOOLCHAIN`.
|
|
90
96
|
Rust rejects compiler paths beneath `.cargo` or `.rustup` and does not invoke rustup because a shim may install a toolchain.
|
|
91
|
-
Go `$mod_version` is reserved and remains empty.
|
|
92
97
|
|
|
93
|
-
Every language `version_format` defaults to `v$raw
|
|
98
|
+
Every language `version_format` defaults to `v$raw`; the shared [version grammar](configuration.md#version-formats) also supports braced raw/component variables and partial versions.
|
|
94
99
|
Malformed, multiline, replacement-character, failed, killed, timed-out, or oversized version output leaves the command-backed value empty.
|
|
95
100
|
|
|
101
|
+
### Node.js and Go requirements
|
|
102
|
+
|
|
103
|
+
Node `$engines_version` reads only `engines.node` from direct `package.json` and exposes at most 80 sanitized characters.
|
|
104
|
+
Go `$mod_version` reads the first standalone `go M.N` or `go M.N.P` directive in direct `go.mod`; each numeric component has 1–9 digits, horizontal whitespace and a trailing `//` comment are allowed, and `toolchain` is ignored.
|
|
105
|
+
Both variables remain visible when the runtime satisfies the requirement; they are not upstream-style mismatch-only output.
|
|
106
|
+
Without these variables or explicit requirement styling, neither requirement file is read.
|
|
107
|
+
|
|
108
|
+
`not_capable_style` defaults to the exact sentinel `"none"`, which disables checks and preserves the normal module style.
|
|
109
|
+
A non-empty different value opts in only when the module format uses `$style` and at least one of `$version` or its requirement variable.
|
|
110
|
+
An available requirement can then trigger a version command even when only the requirement variable is displayed; symbol-only formats never trigger these reads or commands.
|
|
111
|
+
A valid unsatisfied requirement selects the configured style; missing, invalid, or unavailable versions/requirements retain the normal style.
|
|
112
|
+
Node uses npm-semver ranges (comparators, `^`, `~`, wildcards, hyphen ranges, `||`, and npm prerelease rules), limited to 256 characters drawn from letters, digits, `. + * | < > = ^ ~ -`, spaces, and tabs; runtime versions are limited to 80 characters.
|
|
113
|
+
Go compares a numeric `M.N[.P]` minimum, treating a missing patch as zero; prerelease/non-numeric inputs do not select the incapable style.
|
|
114
|
+
No package manager, `go list`, download, or toolchain installation is used.
|
|
115
|
+
|
|
116
|
+
### Python interpreter and environment labels
|
|
117
|
+
|
|
118
|
+
By default, `$version` uses an existing `VIRTUAL_ENV/bin/python` (`Scripts/python.exe` on Windows), otherwise `python --version`.
|
|
119
|
+
Explicit `python_binary` [command alternatives](configuration.md#python-command-alternatives) replace that selection; the first successful command owns parsing even if the output is empty or malformed.
|
|
120
|
+
No shell is started, but configured programs and arguments must be trusted.
|
|
121
|
+
|
|
122
|
+
`pyenv_version_name = true` replaces the runtime version with sanitized `PYENV_VERSION`, or bounded `pyenv version-name` only when that variable is absent.
|
|
123
|
+
An empty present value stays empty without a command fallback; `version_format` is not applied to this label.
|
|
124
|
+
In this mode `$pyenv_prefix` uses the configurable string `pyenv_prefix` (default `"pyenv "`).
|
|
125
|
+
With the default `pyenv_version_name = false`, `$pyenv_prefix` preserves Pi's existing `PYENV_VERSION` text and does not invoke pyenv.
|
|
126
|
+
These optional values are collected only when referenced.
|
|
127
|
+
|
|
128
|
+
`$virtualenv` uses the basename of non-empty `VIRTUAL_ENV`, then non-empty `CONDA_DEFAULT_ENV`.
|
|
129
|
+
`generic_venv_names` defaults to `[]`; an exact matching basename is replaced by its parent-directory basename, so `".venv"` can display the project name.
|
|
130
|
+
A non-empty `detect_env_vars` is an alternative to project-file detection, not an additional requirement or a veto over a matching file.
|
|
131
|
+
|
|
132
|
+
### Package visibility
|
|
133
|
+
|
|
134
|
+
`package` tries direct `package.json`, Cargo, then PEP 621/Poetry versions; only inherited Cargo workspace versions can search up to eight parents.
|
|
135
|
+
`display_private = true` preserves private npm-package visibility.
|
|
136
|
+
Setting it to `false` skips only a `package.json` with boolean `private = true` and can continue to a Cargo/Python manifest; it does not infer privacy for other ecosystems.
|
|
137
|
+
|
|
96
138
|
## Exact environment and deployment defaults
|
|
97
139
|
|
|
98
140
|
| Module | Activation default | Optional command or read |
|
|
@@ -107,13 +149,31 @@ Malformed, multiline, replacement-character, failed, killed, timed-out, or overs
|
|
|
107
149
|
| `kubernetes` | a current context from `KUBECONFIG` or `~/.kube/config` | reads at most 8 config files by default |
|
|
108
150
|
| `terraform` | direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform` | workspace metadata; `terraform version`, then `tofu version`, only for `$version` |
|
|
109
151
|
|
|
110
|
-
|
|
152
|
+
### Environment detection and messages
|
|
153
|
+
|
|
154
|
+
`detect_env_vars` defaults to `[]` for Python, Conda, direnv, gcloud, hostname, and Kubernetes.
|
|
155
|
+
Names use `[A-Za-z_][A-Za-z0-9_]*`, optionally prefixed with `!`.
|
|
156
|
+
Presence includes an empty string: positive names use OR, any present negative name vetoes that environment detector, and a negative-only list passes when all named variables are absent.
|
|
157
|
+
An empty list adds no condition; an invalid name makes that detector fail.
|
|
158
|
+
For Conda, gcloud, and hostname this is an additional gate, not activation by itself; hostname's default SSH gate still applies.
|
|
159
|
+
For Python and direnv a non-empty list is an alternative to matching project files, so its veto does not reject a separately matching file.
|
|
160
|
+
Kubernetes has the precedence described below.
|
|
161
|
+
`username` retains its older positive-only, non-empty-value detector.
|
|
162
|
+
Only explicitly named detector values enter the allowlisted runtime/child environment; detector values are not added to footer output.
|
|
163
|
+
|
|
164
|
+
`mise` maps recognized healthy output through `healthy_symbol` (default `"healthy"`) and warning/problem output through `unhealthy_symbol` (default `"issues"`); unrecognized output leaves `$health` empty.
|
|
111
165
|
`direnv` never reads or sources `.envrc`.
|
|
112
|
-
|
|
166
|
+
Its nested JSON `state.foundRC.allowed` values `0`, `1`, and `2` select `allowed_msg`, `not_allowed_msg`, and `denied_msg` (defaults `"allowed"`, `"not allowed"`, `"denied"`).
|
|
167
|
+
Nested `loadedRC.allowed = 0` selects `loaded_msg` (default `"loaded"`); no loaded record or another valid state selects `unloaded_msg` (default `"not loaded"`).
|
|
168
|
+
Malformed nested status yields no values.
|
|
169
|
+
Legacy top-level snapshots retain boolean/0-or-1 interpretation (`true`/`1` allowed, `false`/`0` denied; a loaded record means loaded).
|
|
170
|
+
Bounded `Found RC path ...` text is also accepted, with `0`/`true` allowed, `1` not allowed, and `2`/`false` denied.
|
|
113
171
|
`pixi` hides the exact environment name `default` unless `show_default_environment = true`.
|
|
114
172
|
`pixi` prefers `PIXI_PROJECT_NAME`, then reads `project.name` or `workspace.name` from direct `pixi.toml`.
|
|
115
|
-
`nix_shell` publishes allowlisted `NIX_SHELL_NAME` and `NIX_SHELL_LEVEL` only
|
|
173
|
+
`nix_shell` publishes allowlisted `NIX_SHELL_NAME` and `NIX_SHELL_LEVEL` only for exact `pure`/`impure` activation, with `$state` selected by `pure_msg`/`impure_msg` (defaults `"pure"`/`"impure"`).
|
|
174
|
+
`unknown_msg` and `heuristic` are not supported: unknown-shell discovery would require the excluded PATH heuristic.
|
|
116
175
|
`guix_shell` reports only the literal state `active`.
|
|
176
|
+
`hostname.ssh_symbol` defaults to `"🌐 "` and appears only for SSH; setting `ssh_only = false` does not add it to local output.
|
|
117
177
|
|
|
118
178
|
When `[docker_context].only_with_files = true`, default detection checks `Dockerfile`, `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, and `compose.yaml`.
|
|
119
179
|
Non-empty Docker detection arrays replace or extend those direct categories as described above.
|
|
@@ -124,6 +184,24 @@ When any Terraform detection array is non-empty, only the complete configured fi
|
|
|
124
184
|
When all three are empty, the built-in `.tf`, `.tfplan`, `.tfstate`, and `.terraform` rules apply.
|
|
125
185
|
Terraform workspace precedence is `TF_WORKSPACE`, `TF_DATA_DIR/environment`, then `.terraform/environment`.
|
|
126
186
|
|
|
187
|
+
### Kubernetes detection and context rules
|
|
188
|
+
|
|
189
|
+
With all file/extension/folder detectors empty, `detect_env_vars` controls reading kubeconfig; its empty default permits the existing current-context behavior.
|
|
190
|
+
If any file/extension/folder detector is configured, only that direct scan is used and environment detectors are ignored.
|
|
191
|
+
Positive file/folder/suffix rules use OR; any matching negative rule rejects the scan, and a negative-only scan cannot activate it.
|
|
192
|
+
Only regular entries are considered, symlinks are not followed, hidden files supply no extensions, and both the last suffix and full compound suffix match (`yaml` or `tar.gz`, without a leading dot).
|
|
193
|
+
|
|
194
|
+
`contexts` accepts at most 64 [bounded rules](configuration.md#bounded-regex-and-structured-options).
|
|
195
|
+
Each requires `context_pattern`; an optional `user_pattern` must also match, including the requirement that a user label exists.
|
|
196
|
+
Rules are checked in order and the first complete match wins, even when it declares no overrides.
|
|
197
|
+
A pattern first checks literal equality, then whole-label RE2JS matching; an empty pattern is not a wildcard.
|
|
198
|
+
`context_alias` and `user_alias` are literal on the equality branch and use regex capture replacement otherwise.
|
|
199
|
+
A `user_alias` without `user_pattern` can supply a display-only user when none exists.
|
|
200
|
+
Optional `symbol` and `style` override presentation for that rule; an explicit empty value clears that presentation.
|
|
201
|
+
Legacy `context_aliases`, `user_aliases`, `namespace_aliases`, and `cluster_aliases` remain exact maps and apply after rule aliases.
|
|
202
|
+
Missing namespace defaults to `default`; cluster/user values normally require matching named kubeconfig entries, except a rule can explicitly supply the user label.
|
|
203
|
+
These are inert labels, not evidence of cluster access or valid credentials.
|
|
204
|
+
|
|
127
205
|
### Usage semantics
|
|
128
206
|
|
|
129
207
|
- 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.
|
|
@@ -144,7 +222,7 @@ Terraform workspace precedence is `TF_WORKSPACE`, `TF_DATA_DIR/environment`, the
|
|
|
144
222
|
|
|
145
223
|
### Directory, Git, and environment contraction
|
|
146
224
|
|
|
147
|
-
|
|
225
|
+
These modules keep their display policy local. Existing Pi defaults remain unchanged:
|
|
148
226
|
|
|
149
227
|
```toml
|
|
150
228
|
[directory]
|
|
@@ -171,22 +249,128 @@ truncation_length = 1
|
|
|
171
249
|
trim_at = "." # set to "" to keep the complete hostname
|
|
172
250
|
```
|
|
173
251
|
|
|
174
|
-
Directory `$path` contracts the
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
`
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
`
|
|
252
|
+
Directory `$path` contracts to the Git repository name by default when cwd is inside a repository whose root is not home; otherwise it contracts home where applicable.
|
|
253
|
+
It then keeps the last three components.
|
|
254
|
+
`use_logical_path = true` preserves Pi's cwd; `false` uses cached `realpath` metadata, falling back to cwd on failure.
|
|
255
|
+
`$full_path` is the selected absolute path without contraction/substitution/truncation; terminal controls are still removed.
|
|
256
|
+
A positive `fish_style_pwd_dir_length` abbreviates omitted parents only when no substitution is configured.
|
|
257
|
+
Ordered literal maps or structured regex/literal [substitution rows](configuration.md#bounded-regex-and-structured-options) run after contraction and before component truncation.
|
|
258
|
+
A runtime substitution failure discards the whole sequence and preserves the pre-substitution display path, not a partially transformed path.
|
|
259
|
+
|
|
260
|
+
`repo_root_format = ""` inherits the main format.
|
|
261
|
+
A non-empty `repo_root_format` selects an alternate format only when a repository root remains in the visible path and can be split without changing the output.
|
|
262
|
+
A non-empty `repo_root_style` with no explicit alternate format selects the built-in split format with `$before_root_path`, `$repo_root`, `$path`, and `$read_only`, preserving Pi's symbol and spacing.
|
|
263
|
+
`before_repo_root_style` alone does not activate that format; unset/empty root styles inherit `style`.
|
|
264
|
+
Truncation that omits the root, an out-of-tree logical symlink, or a substitution crossing a style boundary falls back to the main format.
|
|
265
|
+
Alternate formats accept only directory variables/styles and at most 4,096 characters; invalid syntax/variables warn and restore the empty sentinel.
|
|
266
|
+
|
|
267
|
+
`read_only` defaults to `"🔒"` with `read_only_style = "red"`, but the normal default format does not display or probe it.
|
|
268
|
+
A referenced non-empty indicator requests cached `fs.access(W_OK)` metadata; only known permission/read-only-filesystem denial displays it.
|
|
269
|
+
Unknown/error results hide it. This is a current-process writability approximation, not an ACL or future-write guarantee.
|
|
270
|
+
Rendering and previews perform no filesystem or Git work.
|
|
185
271
|
|
|
186
272
|
Conda retains the last path component by default; `0` keeps the complete environment path.
|
|
187
|
-
Hostname trimming runs before exact alias lookup
|
|
273
|
+
Hostname trimming runs before exact alias lookup.
|
|
188
274
|
These transformations affect display only.
|
|
189
|
-
|
|
275
|
+
|
|
276
|
+
### Git display controls and status templates
|
|
277
|
+
|
|
278
|
+
`git_worktree` is empty in the primary worktree; a linked worktree defaults to its top-level directory name, with `$path` available for the absolute path.
|
|
279
|
+
`git_commit`, `git_state`, and `git_metrics` are absent from the built-in root; metrics also requires `disabled = false`.
|
|
280
|
+
|
|
281
|
+
`git_branch` keeps detached output by default (`only_attached = false`) and suppresses bare repositories by default (`ignore_bare_repo = true`); setting the latter to `false` enables bounded bare-repository identity probes.
|
|
282
|
+
`ignore_branches` compares exact sanitized branch names before truncation; it is not a glob/regex list.
|
|
283
|
+
`always_show_remote = true` preserves Pi's remote fields even when branch labels agree.
|
|
284
|
+
When `false`, both remote fields are suppressed if the truncated remote branch is empty or equals the truncated local branch.
|
|
285
|
+
`ignore_remotes` compares exact remote names and suppresses only `$remote_name`, not `$remote_branch`.
|
|
286
|
+
Truncation independently retains `N` grapheme clusters of each field and appends the first grapheme of `truncation_symbol` when needed; `truncation_length = 0` is Pi's bounded unlimited sentinel, not upstream's very large integer.
|
|
287
|
+
|
|
288
|
+
`git_commit.only_detached = false` keeps attached and detached hashes visible; `true` restricts the module to detached HEAD.
|
|
289
|
+
`commit_hash_length` accepts 0–64 (default 7).
|
|
290
|
+
`$tag` is queried only when referenced and `tag_disabled = false` (default); `tag_symbol` defaults to the existing `" 🏷 "` prefix.
|
|
291
|
+
`tag_max_candidates = 0` preserves exact-HEAD tags; 1–100 selects `git describe --tags --first-parent --abbrev=0 --candidates=N HEAD`, which can show an ancestor tag.
|
|
292
|
+
`git_metrics.only_nonzero_diffs = true` hides each zero count; `false` exposes zeroes, including a clean `+0 -0`.
|
|
293
|
+
Its `ignore_submodules = false` preserves existing diffs; `true` excludes all submodule changes and disables external diff/text conversion for that metrics query.
|
|
294
|
+
The separate `git_status.ignore_submodules = true` ignores dirt inside submodules but retains changed gitlinks (`--ignore-submodules=dirty`).
|
|
295
|
+
`git_state` labels are configurable through `rebase`, `merge`, `revert`, `cherry_pick`, `bisect`, `am`, and `am_or_rebase`, preserving `REBASING`, `MERGING`, `REVERTING`, `CHERRY-PICKING`, `BISECTING`, `AM`, and `AM/REBASE` by default; progress is unchanged.
|
|
296
|
+
|
|
297
|
+
All 20 `git_status` state templates are supported: `stashed`, `ahead`, `behind`, `up_to_date`, `diverged`, `conflicted`, `deleted`, `renamed`, `modified`, `staged`, `untracked`, `typechanged`, the four `worktree_{added,deleted,modified,typechanged}`, and the four `index_{added,deleted,modified,typechanged}` options.
|
|
298
|
+
They use the [bounded status grammar](configuration.md#status-templates).
|
|
299
|
+
Positive safe-integer counts activate counted states; zero does not render even a literal template.
|
|
300
|
+
`$count`, `$ahead_count`, and `$behind_count` preserve Pi compact formatting: integers below 1,000, one-decimal `k` below 10,000, integer `k` below 1,000,000, then one-decimal `m`.
|
|
301
|
+
`$all_status` joins conflicted, stashed, deleted, renamed, modified, typechanged, staged, and untracked in that order with spaces.
|
|
302
|
+
Aggregates preserve Pi counters: deleted = index+worktree deleted; modified = worktree modified+added; staged = index modified+added+typechanged; typechanged = worktree typechanged.
|
|
303
|
+
`$ahead_behind` selects divergence when both counts are positive, otherwise ahead, behind, or up-to-date.
|
|
304
|
+
Up-to-date requires a known tracked zero/zero relation, not merely absent upstream metadata, and its default template is empty.
|
|
305
|
+
Clean output, symbols, count style, and ordering remain unchanged unless configured.
|
|
306
|
+
|
|
307
|
+
### Time formats, zones, and ranges
|
|
308
|
+
|
|
309
|
+
Time defaults to local `%H:%M`; `use_12hr = true` changes only the fallback to `%I:%M %p`.
|
|
310
|
+
A non-empty valid `time_format` overrides that choice and accepts at most 256 characters, literal text, and only these directives:
|
|
311
|
+
|
|
312
|
+
| Tokens | Output |
|
|
313
|
+
| --- | --- |
|
|
314
|
+
| `%%` | Literal `%` |
|
|
315
|
+
| `%H`, `%I`, `%M`, `%S` | Two-digit 24-hour, 12-hour, minute, second |
|
|
316
|
+
| `%p`, `%P` | `AM`/`PM`, `am`/`pm` |
|
|
317
|
+
| `%R`, `%T` | `HH:MM`, `HH:MM:SS` |
|
|
318
|
+
| `%r` | Unpadded 12-hour `h:MM:SS AM/PM` |
|
|
319
|
+
| `%Y`, `%m`, `%d`, `%F` | Year, two-digit month/day, `YYYY-MM-DD` |
|
|
320
|
+
| `%z`, `%:z` | Signed offset `HHMM`, `HH:MM` (minute precision) |
|
|
321
|
+
|
|
322
|
+
Unsupported directives/flags, a trailing `%`, empty format, or an oversized format use the configured 12/24-hour fallback.
|
|
323
|
+
`utc_time_offset` accepts at most 128 characters and defaults to exact `local`; it also accepts `UTC`, a runtime-supported IANA zone matching `[A-Za-z_]+(/[A-Za-z0-9_+.-]+)+`, or numeric hours matching `[+-]?\d{1,2}(\.\d{1,6})?` strictly between -24 and 24.
|
|
324
|
+
Numeric offsets truncate to whole seconds; colon offsets, surrounding whitespace, and unsupported/unknown zones fall back to local time.
|
|
325
|
+
IANA output follows the runtime's timezone data, including DST; it is not a fixed-offset approximation.
|
|
326
|
+
|
|
327
|
+
`time_range` defaults to `"-"` (unrestricted), has a 64-character runtime limit, and always gates against local wall time, not the output zone.
|
|
328
|
+
Use exactly one `-` between optional `HH:MM`, `HH:MM:SS`, or `HH:MM:SS.sss` endpoints (1–3 fractional digits, hours 00–23, minutes/seconds 00–59).
|
|
329
|
+
Endpoints are exclusive; a start later than the end crosses midnight, and equal endpoints exclude only that exact local wall time.
|
|
330
|
+
Invalid endpoints are ignored independently; missing/repeated separators or an oversized range disable the gate.
|
|
331
|
+
An out-of-range or invalid Date hides the whole module, including literal text.
|
|
332
|
+
Second-level formats do not add a one-second timer; refresh remains the [30-second fallback](runtime-and-security.md#-cached-refresh-lifecycle).
|
|
333
|
+
A configured range also re-evaluates visibility for symbol-only or static module formats.
|
|
334
|
+
|
|
335
|
+
### Jujutsu modules
|
|
336
|
+
|
|
337
|
+
`jj_bookmark`, `jj_change`, `jj_metrics`, and `jj_status` are disabled and absent from the built-in root.
|
|
338
|
+
Enable each wanted module with `disabled = false` and name it in `format` (or use `$all`).
|
|
339
|
+
They share one read-only `jj show` query with `--ignore-working-copy --no-integrate-operation`: values describe the recorded change, not newly captured dirty files.
|
|
340
|
+
See [runtime/security](runtime-and-security.md#jujutsu-and-native-system-reads) before enabling them.
|
|
341
|
+
|
|
342
|
+
`jj_bookmark` uses current-change bookmarks followed by those on the latest bookmark ancestor selected by `latest(bookmarks() & ::@, 1)`.
|
|
343
|
+
It shows the first remaining bookmark plus optional remote/divergence marker and the number of additional entries.
|
|
344
|
+
Exact `ignore_names` and `ignore_remotes` filter raw name and remote fields before independent grapheme truncation; literal `@`, quotes, or trailing `*` in a name are not parsed as display syntax.
|
|
345
|
+
An unsynced, non-conflicted local bookmark or tracked remote bookmark selects `diverged_symbol` (default `"*"`).
|
|
346
|
+
The mutable conflict ancestor contributes conflict state, not additional bookmark names.
|
|
347
|
+
`truncation_length` is 0–65,535 (default 65,535; zero disables truncation), and `truncation_symbol` defaults to `"…"`.
|
|
348
|
+
`jj_change` exposes composite styled IDs and plain prefix/suffix fields; configured lengths are 0–255 (default 7) but never cut a shortest-unique prefix.
|
|
349
|
+
A divergent change adds `/<offset>` to `$change`; `$change_offset` itself contains only digits.
|
|
350
|
+
`jj_metrics` shows recorded line additions/deletions and hides each zero by default; `only_nonzero_diffs = false` exposes zeroes.
|
|
351
|
+
`jj_status.$all` concatenates conflict, description, hidden, immutable, added, copied, deleted, modified, and renamed without separators.
|
|
352
|
+
Conflict includes the selected latest mutable conflicted ancestor; the description flag tests only presence, not description text.
|
|
353
|
+
Its templates use the same bounded status grammar: only the five file states accept `$count`, using unshortened integer counts; flag/description states accept no variables.
|
|
354
|
+
Missing CLI, unsupported CLI syntax, no repository, cancellation, timeout, and invalid/oversized output leave the modules empty.
|
|
355
|
+
Git and Jujutsu can be enabled together without treating either as an alias for the other.
|
|
356
|
+
|
|
357
|
+
### Native memory and battery
|
|
358
|
+
|
|
359
|
+
`memory_usage` and `battery` are disabled and absent from the built-in root, including `$all` until explicitly enabled.
|
|
360
|
+
Memory samples native `totalmem()`/`freemem()`; `$ram` is used/total in floored binary units (B through PiB), and `$ram_pct` is rounded to an integer percent.
|
|
361
|
+
Used bytes are clamped at zero; invalid/zero totals hide the module.
|
|
362
|
+
The finite `threshold` is -100–10,000 (default 75) and compares the rounded RAM percent; negative values always show valid samples and values above 100 hide them.
|
|
363
|
+
Only requested `$swap`/`$swap_pct` can read Linux `/proc/meminfo`, after the RAM threshold passes; they use the same usage/percentage formats, and absent/zero/invalid swap totals leave swap empty.
|
|
364
|
+
No other native swap reader is implemented.
|
|
365
|
+
|
|
366
|
+
Battery reads Linux sysfs only and uses energy-weighted totals across usable present batteries, not a mean of percentages.
|
|
367
|
+
It uses `ENERGY_NOW`/`ENERGY_FULL`, or `CHARGE_NOW`/`CHARGE_FULL` converted with positive design/current voltage; capacity-only devices have no fallback.
|
|
368
|
+
The displayed percentage is rounded, but `display` compares the raw percentage against upper bounds: lowest matching threshold wins, first entry wins ties, and no match/hidden rule hides the module.
|
|
369
|
+
Default `display` shows at most 10% in `red bold`; symbols are independently configurable through `full_symbol`, `charging_symbol`, `discharging_symbol`, `unknown_symbol`, and `empty_symbol`.
|
|
370
|
+
Charging takes priority over discharging when combining states; any remaining mixture of full and empty is unknown, regardless of device order.
|
|
371
|
+
Otherwise unknown states yield to a known full or empty state.
|
|
372
|
+
Unsupported platforms, no usable battery, or unavailable sources leave battery empty.
|
|
373
|
+
Physical charging, discharging, full, empty, and multi-battery transitions remain unverified; this reader is not a cross-platform hardware guarantee.
|
|
190
374
|
|
|
191
375
|
### Model and provider aliases and model truncation
|
|
192
376
|
|
|
@@ -225,10 +409,3 @@ For example, `middle` can retain both a Hugging Face model family and its varian
|
|
|
225
409
|
pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names.
|
|
226
410
|
|
|
227
411
|
`truncation_direction` is a pi-starship adaptation; upstream Starship has no model module or generic truncation-direction setting.
|
|
228
|
-
|
|
229
|
-
`git_worktree` is empty in the primary worktree.
|
|
230
|
-
In a linked worktree it defaults to the top-level directory name; use `$path` when the full absolute path is needed.
|
|
231
|
-
|
|
232
|
-
`git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format.
|
|
233
|
-
Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default.
|
|
234
|
-
`$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
|
|
@@ -95,35 +95,47 @@ Disable or remove that extension when adopting the native module to avoid duplic
|
|
|
95
95
|
|
|
96
96
|
### 📦 Package and language modules
|
|
97
97
|
|
|
98
|
-
Module behavior
|
|
99
|
-
This is not complete Starship module or configuration compatibility.
|
|
98
|
+
Module behavior and formatter syntax are inspired by Starship, with explicit Pi default and safety adaptations.
|
|
99
|
+
This is not complete Starship module or configuration compatibility; [module behavior](modules.md) and [configuration grammar](configuration.md) define the supported contract.
|
|
100
100
|
|
|
101
101
|
| Area | Adopted | Adapted | Intentionally omitted |
|
|
102
102
|
| --- | --- | --- | --- |
|
|
103
|
-
| `package` | `package.json` → Cargo → PEP 621/Poetry precedence, `$version
|
|
104
|
-
| Node.js | Direct markers/extensions, `node --version`, package engine text | Bun/Deno markers suppress
|
|
105
|
-
| Python | Direct markers, selected interpreter `--version`, virtualenv name |
|
|
103
|
+
| `package` | `package.json` → Cargo → PEP 621/Poetry precedence, `$version`, private npm visibility control | Direct manifests only; Cargo workspace version lookup is capped at eight ancestors; private versions remain visible by default | Other package ecosystems, dynamic Python versions, package-manager execution |
|
|
104
|
+
| Node.js | Direct markers/extensions, `node --version`, package engine text, optional npm-semver checks | Bun/Deno markers suppress default detection; requirement text stays visible; checks require explicit styling | Manager/shim evaluation and runtime installation |
|
|
105
|
+
| Python | Direct markers, selected interpreter `--version`, virtualenv name, explicit argv alternatives and pyenv labels | Default selection remains an existing active virtualenv interpreter or `python`; explicit label mode can run `pyenv version-name` | Generated Python code, shell activation, and broad environment discovery |
|
|
106
106
|
| Rust | Direct markers and native `rustc --version` | `.cargo`/`.rustup` shim paths are rejected to avoid toolchain installation | Falling back to rustup or any installing probe |
|
|
107
|
-
| Go | Direct markers
|
|
107
|
+
| Go | Direct markers, `go version`, direct `go.mod` minimum, optional minimum check | Requirement text stays visible; checks require explicit styling | `go list`, module downloads, and toolchain installation |
|
|
108
108
|
| Bun / Deno | Direct markers and `bun --version` / `deno -V` | Negative detection avoids overlapping Node defaults | Runtime installation and recursive source detection |
|
|
109
109
|
|
|
110
|
-
|
|
111
|
-
|
|
110
|
+
Workspace runtime commands use argv execution in `ctx.cwd`, a 2-second timeout per command, and a 64 KiB combined stdout/stderr limit.
|
|
111
|
+
Language version commands run only for reachable modules and required values; explicit Node.js/Go requirement styling can also request a version command, but a symbol-only language format cannot.
|
|
112
112
|
Missing, killed, oversized, or malformed commands clear that value independently.
|
|
113
|
-
`version_format`, `detect_files`, `detect_extensions`, and `detect_folders` are available on language modules; package supports `version_format`.
|
|
113
|
+
`version_format`, `detect_files`, `detect_extensions`, and `detect_folders` are available on language modules; package supports `version_format` and `display_private`.
|
|
114
|
+
Node/Go requirement reads use only direct `package.json`/`go.mod`, capped at 64 KiB, with no manager or network access.
|
|
115
|
+
See [requirement behavior](modules.md#nodejs-and-go-requirements) for the opt-in `not_capable_style` sentinel and failure behavior.
|
|
116
|
+
|
|
117
|
+
Python alternatives are bounded to 16 commands, 16 argv elements per alternative, and 1,024 characters per element; the runner appends `--version` without shell parsing.
|
|
118
|
+
A configured executable or argument can still execute arbitrary program logic. Review imported `python_binary` settings before applying them.
|
|
119
|
+
`pyenv_version_name` can read `PYENV_VERSION` or run only `pyenv version-name`; no Python script, shell initialization, or pyenv activation is generated.
|
|
120
|
+
See [command grammar](configuration.md#python-command-alternatives) and [Python labels](modules.md#python-interpreter-and-environment-labels).
|
|
114
121
|
|
|
115
122
|
### 🧰 Development environments
|
|
116
123
|
|
|
117
124
|
| Module | Detection / allowed inputs | Optional command | Options |
|
|
118
125
|
| --- | --- | --- | --- |
|
|
119
|
-
| `mise` | Direct `mise.toml`, `.mise.toml`, or `.tool-versions` | `mise doctor` only for `$health` | Detection arrays |
|
|
120
|
-
| `direnv` | Direct `.envrc
|
|
121
|
-
| `conda` | `CONDA_DEFAULT_ENV
|
|
126
|
+
| `mise` | Direct `mise.toml`, `.mise.toml`, or `.tool-versions` | `mise doctor` only for `$health` | Detection arrays, healthy/unhealthy labels |
|
|
127
|
+
| `direnv` | Direct `.envrc` or explicitly configured environment detection; the file is never read or sourced | `direnv status --json` only for status variables | Detection arrays, `detect_env_vars`, permission/load messages |
|
|
128
|
+
| `conda` | Non-empty `CONDA_DEFAULT_ENV`, with an optional detector gate | None | `ignore_base` (default `true`), `detect_env_vars`, truncation |
|
|
122
129
|
| `pixi` | Direct `pixi.toml`/`pixi.lock`, `PIXI_ENVIRONMENT_NAME`, `PIXI_PROJECT_NAME` | `pixi --version` only for `$version` | Detection arrays, `version_format`, `show_default_environment` |
|
|
123
|
-
| `nix_shell` | `IN_NIX_SHELL`, `NIX_SHELL_NAME`, `NIX_SHELL_LEVEL` | None |
|
|
124
|
-
| `guix_shell` |
|
|
125
|
-
|
|
126
|
-
The
|
|
130
|
+
| `nix_shell` | `IN_NIX_SHELL`, `NIX_SHELL_NAME`, `NIX_SHELL_LEVEL` | None | Pure/impure messages; no unknown-shell heuristic |
|
|
131
|
+
| `guix_shell` | Non-empty `GUIX_ENVIRONMENT` | None | None |
|
|
132
|
+
|
|
133
|
+
The workspace collector never enumerates the process environment, activates a shell, evaluates Nix, lists installed tools, or publishes arbitrary environment values.
|
|
134
|
+
It copies a fixed allowlist plus valid names explicitly configured in `detect_env_vars` into its runtime/child environment; a leading `!` is removed from those names.
|
|
135
|
+
Presence includes empty strings, positive names use OR, and present negatives veto the environment detector; file/environment precedence is [module-specific](modules.md#environment-detection-and-messages).
|
|
136
|
+
Configured detector values are not output, but can be passed to workspace subprocesses: do not name credentials merely to test their presence.
|
|
137
|
+
Python's known labels use `VIRTUAL_ENV`, `CONDA_DEFAULT_ENV`, `PYENV_VERSION`; Rust uses `RUSTC`, `RUSTUP_TOOLCHAIN`, and `PATH`.
|
|
138
|
+
No unrestricted `env_var` output is provided.
|
|
127
139
|
Names and paths are control-sanitized and bounded before publication.
|
|
128
140
|
|
|
129
141
|
### 🚢 Deployment and cloud context
|
|
@@ -135,9 +147,12 @@ They remain opt-in because context labels may be sensitive.
|
|
|
135
147
|
- `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`.
|
|
136
148
|
The `default` context is suppressed.
|
|
137
149
|
`only_with_files` and detection arrays are supported.
|
|
138
|
-
- `kubernetes`: at most `max_config_files` (default 8) from `KUBECONFIG` or `~/.kube/config`, with first-wins merge semantics.
|
|
150
|
+
- `kubernetes`: at most `max_config_files` (1–32, default 8) from `KUBECONFIG` or `~/.kube/config`, with first-wins merge semantics.
|
|
139
151
|
Only context, namespace, cluster name, and user name are selected.
|
|
140
|
-
|
|
152
|
+
Configured direct detectors take precedence over environment detectors; with none configured, the optional environment gate applies.
|
|
153
|
+
Up to 64 ordered context/user rules use whole-label bounded RE2JS matching (AND, first match) and can set aliases, symbol, and style; legacy alias maps remain exact and run afterward.
|
|
154
|
+
Patterns, replacement bounds, unsupported syntax, and rule failures are defined in [configuration grammar](configuration.md#bounded-regex-and-structured-options).
|
|
155
|
+
Kubeconfig `exec`, auth-provider, token files, certificates, and cluster URLs are never executed, followed, or contacted.
|
|
141
156
|
- `terraform`: direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform`; workspace precedence is `TF_WORKSPACE` → `TF_DATA_DIR/environment` → `.terraform/environment`.
|
|
142
157
|
`terraform version`, then `tofu version`, runs only for `$version`.
|
|
143
158
|
Workspace, init, provider, and state commands never run.
|
|
@@ -145,7 +160,7 @@ They remain opt-in because context labels may be sensitive.
|
|
|
145
160
|
The credentials file is never read.
|
|
146
161
|
Exact profile/region aliases are supported.
|
|
147
162
|
- `gcloud`: active selector plus allowlisted `core.account`, `core.project`, and `compute.region` INI keys.
|
|
148
|
-
|
|
163
|
+
`detect_env_vars` adds a presence gate before config reads; exact project/region aliases are supported.
|
|
149
164
|
- `azure`: the default local `azureProfile.json` subscription name.
|
|
150
165
|
`show_username` defaults to `false`; exact subscription aliases are supported.
|
|
151
166
|
- `openstack`: `OS_CLOUD`, `OS_PROJECT_NAME`, or the selected `clouds.yaml` `auth.project_name` only.
|
|
@@ -157,14 +172,55 @@ Presence indicates only selected local metadata—not valid credentials or conne
|
|
|
157
172
|
|
|
158
173
|
### 🖥️ Execution context
|
|
159
174
|
|
|
160
|
-
`hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, and
|
|
175
|
+
`hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, exact `aliases`, a configurable SSH-only `ssh_symbol`, and an additional `detect_env_vars` presence gate.
|
|
161
176
|
`username` appears only for `show_always`, SSH, root/Administrator, a login-user mismatch, or configured `detect_env_vars`; it supports exact aliases.
|
|
162
177
|
Negated username detection names are rejected.
|
|
163
178
|
`os` is disabled by default and supports an exact `symbols` map.
|
|
164
179
|
`container` uses only Dev Container/Codespaces markers, WSL metadata, `/.dockerenv`, `/run/.containerenv`, and `/run/systemd/container`; it does not scan process tables or cgroups.
|
|
165
|
-
Ordinary local hostname/username sessions stay empty.
|
|
180
|
+
Ordinary local hostname/username sessions stay empty by default.
|
|
166
181
|
All identity labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
|
|
167
182
|
|
|
183
|
+
### Directory and Git metadata
|
|
184
|
+
|
|
185
|
+
Directory defaults add no physical-path or permission probes.
|
|
186
|
+
`use_logical_path = false` requests cached `realpath` only for referenced path variables; failure keeps Pi's cwd.
|
|
187
|
+
A non-empty `$read_only` indicator in the main or enabled alternate root format requests `fs.access(W_OK)` on cwd, following symlinks.
|
|
188
|
+
Only `EACCES`, `EPERM`, or `EROFS` means known denial; other failures mean unknown and hide the indicator.
|
|
189
|
+
This is a cached current-process writability approximation, not proof of ACL state or a future write result.
|
|
190
|
+
No file contents are read for these probes.
|
|
191
|
+
|
|
192
|
+
Git identity/status queries have a 3-second timeout per command and a 64 KiB accepted combined-output limit.
|
|
193
|
+
Optional tag, metrics, submodule, and bare-repository queries are controlled by the [Git settings](modules.md#git-display-controls-and-status-templates).
|
|
194
|
+
They do not fetch, pull, push, or intentionally modify the checkout; Git and its local configuration remain trusted executable inputs.
|
|
195
|
+
All new format/template/substitution output is terminal-sanitized before display; raw stored settings and snapshots are not rewritten for display.
|
|
196
|
+
|
|
197
|
+
### Jujutsu and native system reads
|
|
198
|
+
|
|
199
|
+
`jj_bookmark`, `jj_change`, `jj_metrics`, `jj_status`, `memory_usage`, and `battery` are disabled by default and absent from the built-in root.
|
|
200
|
+
They add no reads or commands until explicitly enabled and reachable, including through `$all`.
|
|
201
|
+
Rendering, inspection, and live previews use only existing immutable snapshots.
|
|
202
|
+
|
|
203
|
+
Jujutsu discovery checks at most 64 directories, starting at cwd, for a directory named `.jj`; each listing is bounded to 2,048 entries and does not recurse into children.
|
|
204
|
+
One shared bounded `jj show` query uses fixed argv with `--color never --ignore-working-copy --no-integrate-operation --no-pager --quiet --repository <root>`, `--no-patch`, a fixed revset, and a fixed template.
|
|
205
|
+
It selects the recorded working-copy change, latest mutable conflicted ancestor head, and latest bookmark ancestor.
|
|
206
|
+
The query does not snapshot dirty files or integrate pending operations, so unrecorded worktree changes are deliberately absent.
|
|
207
|
+
It collects IDs/unique-prefix lengths, bookmark labels, boolean flags, line totals, and file-status counts, not description text or patches.
|
|
208
|
+
There is no fetch/push, shell command, credential lookup, or network request added by this collector.
|
|
209
|
+
Missing/unsupported `jj`, timeout, cancellation, malformed output, or the 64 KiB output bound makes the result unavailable.
|
|
210
|
+
The installed CLI and repository configuration must still be trusted.
|
|
211
|
+
|
|
212
|
+
Memory uses Node's native `totalmem()` and `freemem()`, not a subprocess or process-table scan.
|
|
213
|
+
Only referenced swap variables, after the RAM threshold passes, can read Linux `/proc/meminfo` (64 KiB) for `SwapTotal`/`SwapFree`.
|
|
214
|
+
Other platforms and unavailable/zero swap totals omit swap; no cross-platform swap reader is claimed.
|
|
215
|
+
|
|
216
|
+
Battery is Linux sysfs only: it lists `/sys/class/power_supply`, rejects enumerations over 32 entries, and reads each accepted device's `uevent` at most 8,192 bytes.
|
|
217
|
+
Only `Battery` sources with `POWER_SUPPLY_PRESENT` omitted or equal to `1` and valid energy totals are usable.
|
|
218
|
+
Charge conversion uses valid `VOLTAGE_MIN_DESIGN` when available, otherwise `VOLTAGE_NOW`; a missing or non-positive selected voltage makes charge-only data unusable.
|
|
219
|
+
Totals are energy-weighted, and capacity-only or invalid sources have no percentage fallback.
|
|
220
|
+
No external command, privileged probe, device installation, or alternate-platform reader is used.
|
|
221
|
+
Charging/discharging/full/empty, physical multi-battery transitions, and native behavior on other hardware remain unverified; deterministic fixtures do not establish cross-platform hardware support.
|
|
222
|
+
See [native module behavior](modules.md#native-memory-and-battery) for threshold, state, and display rules.
|
|
223
|
+
|
|
168
224
|
## 📐 Layout and lifecycle
|
|
169
225
|
|
|
170
226
|
### ↔️ Fill layout
|
|
@@ -189,15 +245,16 @@ There is no `line_break` module; use literal newlines in `format`.
|
|
|
189
245
|
|
|
190
246
|
### 🔄 Cached refresh lifecycle
|
|
191
247
|
|
|
192
|
-
Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled modules.
|
|
248
|
+
Workspace (including optional Jujutsu/system readers), Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled modules.
|
|
193
249
|
Root format reachability, `$all`, module `disabled`, and module-format variables determine file and command requirements.
|
|
194
250
|
Workspace/Git refreshes run at session start, after accepted settings, branch changes, tool/turn completion, and a 30-second fallback.
|
|
195
251
|
GitHub PR uses the narrower lifecycle and 60-second network refresh described above.
|
|
196
252
|
One read runs with at most one latest pending refresh.
|
|
197
253
|
Immutable snapshot equality suppresses collector-driven redraws, and session or request generations reject stale results.
|
|
198
254
|
The 30-second fallback does not request a redraw for unchanged snapshots.
|
|
199
|
-
|
|
200
|
-
|
|
255
|
+
For a reachable time module referencing `$time`, or using a non-empty `time_range` other than `"-"`, the fallback also re-evaluates clock output and range visibility from the last rendered snapshot without re-reading session history.
|
|
256
|
+
This includes range-gated symbol-only/static formats; seconds, dates, and ranges use the existing 30-second fallback, not a one-second timer.
|
|
257
|
+
Only changed rendered lines request that redraw; unrelated Pi events can also redraw the footer.
|
|
201
258
|
Background collection continues even when a terminal pane is not visible.
|
|
202
259
|
Shutdown, replacement, footer disposal, branch changes, and accepted settings abort active command work before starting replacements; disabling `github_pr` also stops its query and timers.
|
|
203
260
|
Bounded local filesystem operations may finish, but stale generations cannot publish them.
|
|
@@ -205,13 +262,16 @@ Execution identity is retained rather than re-read by the periodic fallback.
|
|
|
205
262
|
Render and live preview consume snapshots synchronously and perform zero reads or commands.
|
|
206
263
|
|
|
207
264
|
Missing, unreadable, malformed, oversized, timed-out, or unavailable sources produce empty values.
|
|
208
|
-
Workspace
|
|
209
|
-
|
|
210
|
-
The Cargo package lookup is the
|
|
265
|
+
Workspace metadata files are capped at 64 KiB unless a smaller bound is stated; direct project detection shares one bounded current-directory listing and never recurses.
|
|
266
|
+
Git command output is capped as described above; Git operation/progress markers are local reads.
|
|
267
|
+
The Cargo package lookup stops after eight parents; Jujutsu root discovery is the separate bounded ancestor walk described above.
|
|
268
|
+
These collectors make no network calls; the native GitHub PR query is the documented background network exception.
|
|
211
269
|
|
|
212
270
|
## 🚧 Limitations
|
|
213
271
|
|
|
214
272
|
- The formatter and modules are Starship-inspired, not fully compatible with Starship.
|
|
215
273
|
- The extension does not load `starship.toml`, invoke the Starship binary, run custom shell modules, or provide unrestricted `env_var` behavior.
|
|
216
|
-
- JVM/.NET
|
|
274
|
+
- JVM/.NET and other long-tail languages, VCS integrations beyond Git/Jujutsu, system monitoring beyond the documented RAM/Linux battery readers, and additional DevOps modules remain outside this package's supported surface.
|
|
275
|
+
- AWS credential inspection/expiration and `force_display`, Nix heuristic discovery, `terraform.commands`, and `pixi.pixi_binary` remain intentionally unsupported.
|
|
276
|
+
- Battery has no non-Linux or capacity-only fallback; native hardware transitions remain unverified. Memory has no non-Linux swap reader.
|
|
217
277
|
- Pi does not expose the auto-compaction toggle, so the footer cannot reliably show Pi's native `(auto)` marker.
|