@narumitw/pi-starship 0.54.0 → 0.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +32 -626
  2. package/dist/chunks/{chunk-OZDBEKV2.js → chunk-UX6PBXVK.js} +2 -2
  3. package/dist/chunks/{chunk-OZDBEKV2.js.map → chunk-UX6PBXVK.js.map} +1 -1
  4. package/dist/chunks/{cloud-GEBXIN43.js → cloud-BKHYWCTA.js} +3 -3
  5. package/dist/chunks/cloud-BKHYWCTA.js.map +7 -0
  6. package/dist/chunks/{commands-Z3V7LRUY.js → commands-53ZO2JUK.js} +2 -2
  7. package/dist/chunks/{development-TOXV7LWE.js → development-BERD42HW.js} +2 -2
  8. package/dist/chunks/{development-TOXV7LWE.js.map → development-BERD42HW.js.map} +2 -2
  9. package/dist/chunks/{execution-QDYHQKST.js → execution-42JTEY3N.js} +2 -2
  10. package/dist/chunks/{execution-QDYHQKST.js.map → execution-42JTEY3N.js.map} +2 -2
  11. package/dist/chunks/{languages-QR3XPRVQ.js → languages-RMP6DW7H.js} +2 -2
  12. package/dist/chunks/languages-RMP6DW7H.js.map +7 -0
  13. package/dist/index.ts +6 -6
  14. package/package.json +12 -7
  15. package/skills/configuring-pi-starship/SKILL.md +113 -0
  16. package/skills/configuring-pi-starship/references/configuration.md +365 -0
  17. package/skills/configuring-pi-starship/references/module-catalog.md +978 -0
  18. package/skills/configuring-pi-starship/references/modules.md +230 -0
  19. package/skills/configuring-pi-starship/references/runtime-and-security.md +213 -0
  20. package/skills/configuring-pi-starship/scripts/apply.mjs +64 -0
  21. package/skills/configuring-pi-starship/scripts/config-path.mjs +11 -0
  22. package/skills/configuring-pi-starship/scripts/script-support.mjs +20 -0
  23. package/skills/configuring-pi-starship/scripts/validate.mjs +30 -0
  24. package/src/modules/catalog.ts +1 -1
  25. package/src/runtime/cloud.ts +3 -2
  26. package/src/runtime/development.ts +1 -1
  27. package/src/runtime/execution.ts +1 -1
  28. package/src/runtime/languages.ts +1 -1
  29. package/dist/chunks/cloud-GEBXIN43.js.map +0 -7
  30. package/dist/chunks/languages-QR3XPRVQ.js.map +0 -7
  31. /package/dist/chunks/{commands-Z3V7LRUY.js.map → commands-53ZO2JUK.js.map} +0 -0
@@ -0,0 +1,230 @@
1
+ # Module Reference
2
+
3
+ Use this authoritative public reference whenever a question or change involves a module, format variable, display rule, alias, truncation rule, or module-specific option.
4
+
5
+ ## 🧱 Modules
6
+
7
+ | Module | Format variables | Meaning |
8
+ | --- | --- | --- |
9
+ | `brand` | `$symbol` | Pi brand marker |
10
+ | `provider` | `$symbol`, `$provider` | Current model provider |
11
+ | `model` | `$symbol`, `$model` | Current model name |
12
+ | `thinking` | `$symbol`, `$level` | Thinking level |
13
+ | `directory` | `$symbol`, `$path`, `$full_path` | Current working directory |
14
+ | `git_worktree` | `$symbol`, `$name`, `$path` | Linked worktree name and top-level path |
15
+ | `git_branch` | `$symbol`, `$branch`, `$remote_name`, `$remote_branch` | Local branch and upstream |
16
+ | `github_pr` | `$symbol`, `$number`, `$link`, `$state`, `$checks`, `$review`, `$status` | Current-branch GitHub pull request |
17
+ | `git_commit` | `$symbol`, `$hash`, `$tag` | Seven-character HEAD hash and optional exact tag |
18
+ | `git_state` | `$symbol`, `$state`, `$progress_current`, `$progress_total` | Rebase, merge, revert, cherry-pick, bisect, or mail-apply state |
19
+ | `git_metrics` | `$symbol`, `$added`, `$deleted` | Added/deleted line totals from the working tree diff |
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
+ | `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$kind`, `$title`, `$text` | Extension UI waits, active tools, streaming, completion, or idle |
22
+ | `context` | `$symbol`, `$percentage`, `$tokens`, `$window` | Context-window use |
23
+ | `tokens` | `$symbol`, `$input`, `$output`, `$total` | Token totals |
24
+ | `cache` | `$symbol`, `$rate`, `$read`, `$write` | Prompt-cache reads, writes, and latest hit rate; disabled by default |
25
+ | `cost` | `$symbol`, `$cost`, `$subscription` | Session cost and optional `(sub)` marker |
26
+ | `time` | `$symbol`, `$time` | Current local time |
27
+ | `turn` | `$symbol`, `$count` | User turn count |
28
+ | `package` | `$symbol`, `$version`, `$source` | Direct project manifest version |
29
+ | `nodejs` | `$symbol`, `$version`, `$engines_version` | Detected Node.js project/runtime |
30
+ | `python` | `$symbol`, `$version`, `$virtualenv`, `$pyenv_prefix` | Python runtime and allowlisted environment name |
31
+ | `rust` | `$symbol`, `$version`, `$numver`, `$toolchain` | Safe native `rustc` runtime and allowlisted toolchain name |
32
+ | `golang` | `$symbol`, `$version`, `$mod_version` | Go runtime (`$mod_version` is reserved and currently empty) |
33
+ | `bun` / `deno` | `$symbol`, `$version` | Bun or Deno runtime |
34
+ | `mise` | `$symbol`, `$health` | Bounded mise health result |
35
+ | `direnv` | `$symbol`, `$rc_path`, `$allowed`, `$loaded` | Inert direnv status; `.envrc` is never sourced |
36
+ | `conda` | `$symbol`, `$environment` | Active Conda environment name |
37
+ | `pixi` | `$symbol`, `$version`, `$environment`, `$project_name` | Pixi project and environment |
38
+ | `nix_shell` | `$symbol`, `$state`, `$name`, `$level` | Allowlisted Nix shell activation metadata |
39
+ | `guix_shell` | `$symbol`, `$state` | Guix shell activation marker |
40
+ | `docker_context` | `$symbol`, `$context` | Non-default local Docker context |
41
+ | `kubernetes` | `$symbol`, `$context`, `$namespace`, `$cluster`, `$user` | Current inert kubeconfig metadata |
42
+ | `terraform` | `$symbol`, `$workspace`, `$version` | Local Terraform/OpenTofu workspace and optional version |
43
+ | `aws` | `$symbol`, `$profile`, `$region` | AWS profile/region metadata, never credentials |
44
+ | `gcloud` | `$symbol`, `$active`, `$account`, `$domain`, `$project`, `$region` | Active gcloud configuration metadata |
45
+ | `azure` | `$symbol`, `$subscription`, `$username` | Default Azure subscription; username is separately enabled |
46
+ | `openstack` | `$symbol`, `$cloud`, `$project` | Selected OpenStack cloud/project metadata |
47
+ | `os` | `$symbol`, `$type`, `$name`, `$version`, `$edition`, `$codename` | Platform/OS metadata; disabled by default |
48
+ | `container` | `$symbol`, `$name`, `$type` | Known container, WSL, or Dev Container context |
49
+ | `hostname` | `$symbol`, `$hostname`, `$ssh_symbol` | Hostname, SSH-only by default |
50
+ | `username` | `$symbol`, `$user` | Contextual login identity |
51
+ | `fill` | `$symbol` | Flexible width-aware root-layout marker |
52
+ | `extension_status` | `$symbol`, `$statuses`, `$count` | Pi extension statuses |
53
+
54
+ For exact default formats, symbols, enabled state, accepted style fields, display defaults, option types, numeric ranges, and enum values, use [the complete module catalog](module-catalog.md).
55
+
56
+ ## Reachability and collection rules
57
+
58
+ A module contributes work only when it is enabled and reachable from the root `format` directly or through `$all`.
59
+ Reachability activates that module's collector at module scope, even when its module format references only `$symbol`.
60
+ 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, while its version command, Node engine-file read, and optional Python or Rust environment values are collected only when their corresponding variables are referenced.
62
+ 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.
63
+ A disabled module is absent even when the root format names it or `$all` is present.
64
+
65
+ Workspace detection uses at most one direct listing of the current working directory, stops at 2,048 entries, and never recurses.
66
+ A positive file, extension, or folder rule must match for direct detection to succeed.
67
+ Any matching `!` rule rejects the module before positive matches are considered.
68
+ Extensions may be configured with or without a leading dot, but defaults omit the dot.
69
+
70
+ For language modules, each non-empty `detect_files`, `detect_extensions`, or `detect_folders` array replaces only that category's built-in defaults.
71
+ An empty category keeps its built-in defaults.
72
+ For `mise`, `direnv`, and `pixi`, an empty `detect_files` uses the listed default files while configured extension and folder arrays remain additive detector categories.
73
+
74
+ ## Exact language defaults
75
+
76
+ | Module | Default files | Default extensions | Default folders | Version command |
77
+ | --- | --- | --- | --- | --- |
78
+ | `nodejs` | `package.json`, `.node-version`, `.nvmrc`, `!bun.lock`, `!bun.lockb`, `!deno.json`, `!deno.jsonc` | `js`, `mjs`, `cjs`, `ts`, `mts`, `cts` | `node_modules` | `node --version` |
79
+ | `python` | `pyproject.toml`, `requirements.txt`, `Pipfile`, `poetry.lock`, `.python-version` | `py` | `.venv`, `venv` | existing active virtualenv interpreter, otherwise `python --version` |
80
+ | `rust` | `Cargo.toml` | `rs` | none | safe native `rustc --version` |
81
+ | `golang` | `go.mod`, `go.sum`, `go.work` | `go` | none | `go version` |
82
+ | `bun` | `bun.lock`, `bun.lockb`, `bunfig.toml` | none | none | `bun --version` |
83
+ | `deno` | `deno.json`, `deno.jsonc`, `deno.lock` | none | none | `deno -V` |
84
+
85
+ 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
+ Rust `$toolchain` reads `RUSTUP_TOOLCHAIN`.
90
+ 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
+
93
+ Every language `version_format` defaults to `v$raw` and replaces every `$raw` occurrence with the parsed version without a leading `v`.
94
+ Malformed, multiline, replacement-character, failed, killed, timed-out, or oversized version output leaves the command-backed value empty.
95
+
96
+ ## Exact environment and deployment defaults
97
+
98
+ | Module | Activation default | Optional command or read |
99
+ | --- | --- | --- |
100
+ | `mise` | direct `mise.toml`, `.mise.toml`, or `.tool-versions` | `mise doctor` only for `$health` |
101
+ | `direnv` | direct `.envrc` | `direnv status --json` only for `$rc_path`, `$allowed`, or `$loaded` |
102
+ | `conda` | non-empty `CONDA_DEFAULT_ENV`, excluding exact `base` by default | none |
103
+ | `pixi` | direct `pixi.toml` or `pixi.lock` | `pixi --version` only for `$version`; direct `pixi.toml` may supply project/workspace name |
104
+ | `nix_shell` | `IN_NIX_SHELL` is exactly `pure` or `impure` | none |
105
+ | `guix_shell` | non-empty `GUIX_ENVIRONMENT` | none |
106
+ | `docker_context` | a non-default Docker context; project files are not required by default | `DOCKER_CONTEXT`, then Docker `config.json` |
107
+ | `kubernetes` | a current context from `KUBECONFIG` or `~/.kube/config` | reads at most 8 config files by default |
108
+ | `terraform` | direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform` | workspace metadata; `terraform version`, then `tofu version`, only for `$version` |
109
+
110
+ `mise` maps recognized healthy output to `healthy`, recognized warning/problem output to `issues`, and otherwise leaves `$health` empty.
111
+ `direnv` never reads or sources `.envrc`.
112
+ `direnv` maps `foundRC.allowed` to `allowed` or `denied`, reports loaded state as `loaded` or `not loaded`, and accepts a bounded legacy `Found RC path ...` fallback.
113
+ `pixi` hides the exact environment name `default` unless `show_default_environment = true`.
114
+ `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 when its state is valid.
116
+ `guix_shell` reports only the literal state `active`.
117
+
118
+ When `[docker_context].only_with_files = true`, default detection checks `Dockerfile`, `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, and `compose.yaml`.
119
+ Non-empty Docker detection arrays replace or extend those direct categories as described above.
120
+ Docker suppresses the exact context `default`.
121
+
122
+ Terraform differs from category-by-category language fallback.
123
+ When any Terraform detection array is non-empty, only the complete configured file, extension, and folder arrays are used.
124
+ When all three are empty, the built-in `.tf`, `.tfplan`, `.tfstate`, and `.terraform` rules apply.
125
+ Terraform workspace precedence is `TF_WORKSPACE`, `TF_DATA_DIR/environment`, then `.terraform/environment`.
126
+
127
+ ### Usage semantics
128
+
129
+ - 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.
130
+ - Prompt waiting takes precedence without losing the underlying tool, streaming, completed, or idle state, which returns when the prompt closes.
131
+ - `tokens`, `cache`, and `cost` total every usage-bearing session entry, matching Pi's native footer.
132
+ This includes assistant messages, nested-LLM tool results, compactions, and branch summaries, including abandoned branches retained in the session.
133
+ - Cache `$read` and `$write` are cumulative.
134
+ `$rate` uses only the latest assistant prompt with `cacheRead / (input + cacheRead + cacheWrite) * 100`.
135
+ The module is empty when Pi has reported no cache reads or writes.
136
+ - `cache` is disabled and absent from the built-in root.
137
+ Enable it and add `$cache` to a custom root format (or use `$all`) to display it.
138
+ - Context `$percentage` uses native one-decimal precision.
139
+ Its default display hides values below 30%.
140
+ Customize `[[context.display]]` when lower values should remain visible.
141
+ The module name remains `context`, not `context_usage`.
142
+ - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
143
+ The dollar value is usage cost, not proof of an amount billed under a subscription.
144
+
145
+ ### Directory, Git, and environment contraction
146
+
147
+ The analogous modules keep their display policy local and use Starship defaults:
148
+
149
+ ```toml
150
+ [directory]
151
+ truncation_length = 3
152
+ truncate_to_repo = true
153
+ fish_style_pwd_dir_length = 0
154
+ truncation_symbol = ""
155
+ home_symbol = "~"
156
+ use_os_path_sep = true
157
+ substitutions = { "/Volumes/network/path" = "/net" }
158
+
159
+ [git_branch]
160
+ truncation_length = 0 # pi-starship's bounded no-truncation sentinel
161
+ truncation_symbol = "…"
162
+
163
+ [git_commit]
164
+ commit_hash_length = 7
165
+
166
+ [conda]
167
+ ignore_base = true
168
+ truncation_length = 1
169
+
170
+ [hostname]
171
+ trim_at = "." # set to "" to keep the complete hostname
172
+ ```
173
+
174
+ Directory `$path` contracts the home directory and, by default, the current Git repository root before retaining the last three path components.
175
+ `$full_path` remains the unmodified absolute cwd.
176
+ A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no substitution is configured.
177
+ `substitutions` is an ordered TOML string table of literal replacements applied to the already home- or repository-contracted display path, before component truncation.
178
+ Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement Starship's regex substitution array or repo-root-specific split style/format fields.
179
+ Directory rendering reads only immutable home and repository-root snapshot data and performs no filesystem or Git work.
180
+
181
+ Git branch truncation retains the first `N` grapheme clusters and appends the first grapheme of `truncation_symbol` only when truncation occurs.
182
+ The same rule applies independently to `$branch`, `$remote_name`, and `$remote_branch`.
183
+ Upstream Starship represents its unlimited default as `2^63 - 1`; pi-starship uses `0` for the same behavior because its settings integers are deliberately bounded.
184
+ `commit_hash_length` accepts 0 through 64.
185
+
186
+ Conda retains the last path component by default; `0` keeps the complete environment path.
187
+ Hostname trimming runs before exact alias lookup, matching Starship.
188
+ These transformations affect display only.
189
+ Collectors retain bounded, control-sanitized source metadata.
190
+
191
+ ### Model and provider aliases and model truncation
192
+
193
+ The model module accepts exact `model_aliases`, Starship-style `truncation_length` and `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
194
+
195
+ ```toml
196
+ [model]
197
+ model_aliases = { "/models/Qwen3.6-35B-Q4.gguf" = "Qwen 35B Q4" }
198
+ truncation_length = 36
199
+ truncation_symbol = "…"
200
+ truncation_direction = "middle"
201
+ ```
202
+
203
+ An exact alias replaces the label that the built-in Claude/GPT shortening rules would otherwise produce, bypasses those rules, and is then subject to the configured truncation.
204
+ `truncation_length` counts model grapheme clusters retained before the symbol; `0` disables truncation and is the default.
205
+ The direction names the removed portion: `start` retains the suffix, `end` retains the prefix and is the default, and `middle` retains both ends.
206
+ When no alias matches, truncation runs after the built-in Claude/GPT shortening rules.
207
+ Truncation changes display only; the provider model ID is untouched.
208
+ Terminal control sequences in model IDs and truncation symbols are removed at render time.
209
+ An empty symbol truncates without a marker.
210
+
211
+ The provider module accepts exact display aliases without changing the selected provider or model:
212
+
213
+ ```toml
214
+ [provider]
215
+ provider_aliases = { "openai-codex" = "codex", "amazon-bedrock" = "bedrock" }
216
+ ```
217
+
218
+ An empty alias hides only the provider text.
219
+ Provider names and aliases are stripped of terminal controls at render time.
220
+ For example, `middle` can retain both a Hugging Face model family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
221
+ pi-starship treats model IDs as opaque strings and does not parse paths, repositories, GGUF suffixes, or quantization names.
222
+
223
+ `truncation_direction` is a pi-starship adaptation; upstream Starship has no model module or generic truncation-direction setting.
224
+
225
+ `git_worktree` is empty in the primary worktree.
226
+ In a linked worktree it defaults to the top-level directory name; use `$path` when the full absolute path is needed.
227
+
228
+ `git_commit`, `git_state`, and `git_metrics` are intentionally not present in the built-in root format.
229
+ Add their variables to `format` to opt in; also set `[git_metrics].disabled = false`, matching Starship's opt-in metrics default.
230
+ `$tag` resolves only an exact tag on HEAD and is queried only when the configured `git_commit` format references it.
@@ -0,0 +1,213 @@
1
+ # Runtime and Security Reference
2
+
3
+ Use this authoritative public reference before enabling or explaining network, command-backed, development, cloud, deployment, host, user, or width-sensitive modules, and when checking runtime limitations.
4
+
5
+ ## 🔒 Security and privacy
6
+
7
+ ### 🔎 Native GitHub pull requests
8
+
9
+ `$github_pr` is independent of `pi-github-pr`; installing that extension is not required.
10
+ It runs one bounded GitHub CLI query for the current branch:
11
+
12
+ ```text
13
+ gh pr view --json number,isDraft,url,state,closedAt,mergedAt,reviewDecision,statusCheckRollup
14
+ ```
15
+
16
+ Install and authenticate `gh` first:
17
+
18
+ ```bash
19
+ gh auth login
20
+ ```
21
+
22
+ For GitHub Enterprise Server, authenticate the repository host and keep that host in the repository remote, for example `gh auth login --hostname github.example.com`. pi-starship starts `gh` directly with child-only environment data that omits ambient `GH_HOST` and `GH_REPO` overrides, so `gh` resolves the correct repository and host from the current checkout.
23
+ It never mutates Pi's environment, calls the GitHub API directly, or manages tokens.
24
+
25
+ Variables have these values:
26
+
27
+ - `$number`: digits such as `123`.
28
+ - `$link`: an OSC 8 `#123` link for a safe HTTP(S) URL when Pi's effective terminal capabilities enable hyperlinks, otherwise plain `#123`.
29
+ - `$state`: `open`, `draft`, `merged`, or `closed`.
30
+ - `$checks`: all non-zero check counts in passed, failed, pending order, or `-` when no checks exist.
31
+ - `$review`: `R✓` for approved, `R×` for changes requested, `R?` for review required, or empty when unknown.
32
+ - `$status`: one result selected in this order: merged, closed, draft, failing checks, changes requested, pending checks, approved, review required, passing checks, then no checks.
33
+
34
+ The compact symbols are font-safe and distinct from Git's default `$`, `!`, and `?` worktree markers:
35
+
36
+ | Compact value | Meaning |
37
+ | --- | --- |
38
+ | `✓<n>` | Checks that passed, including successful, skipped, and neutral conclusions |
39
+ | `×<n>` | Checks that failed |
40
+ | `…<n>` | Checks that are pending |
41
+ | `R✓` | Review approved |
42
+ | `R×` | Changes requested |
43
+ | `R?` | Review required |
44
+ | `M` / `C` / `D` | Merged, closed, or draft PR |
45
+ | `-` | No checks |
46
+
47
+ The unchanged default module format uses `$status` and now renders compact output:
48
+
49
+ ```text
50
+ PR #123 · ×2
51
+ PR #123 · R✓
52
+ PR #123 · M
53
+ ```
54
+
55
+ Use the existing `$checks` and `$review` variables together when every check category and the review result should remain visible:
56
+
57
+ ```toml
58
+ [github_pr]
59
+ format = "[$symbol$link( $checks)( $review) ]($style)"
60
+ ```
61
+
62
+ ```text
63
+ PR #123 ✓12 ×2 …7 R×
64
+ ```
65
+
66
+ This is a breaking display migration for custom formats that use these variables:
67
+
68
+ | Previous value | Compact value |
69
+ | --- | --- |
70
+ | `checks passing` | `✓<n>` |
71
+ | `<n> failing` | `×<n>` |
72
+ | `<n> pending` | `…<n>` |
73
+ | `no checks` | `-` |
74
+ | `approved` / `changes requested` / `review required` | `R✓` / `R×` / `R?` |
75
+ | `merged` / `closed` / `draft` | `M` / `C` / `D` |
76
+
77
+ The old English values have no verbose aliases.
78
+ The variable names and default module format remain unchanged, so no TOML field migration is needed.
79
+
80
+ The query runs only in TUI sessions when the enabled module is reachable from the root format.
81
+ It refreshes at session start, immediately after a branch change, after each agent run, after accepted settings changes, and every 60 seconds.
82
+ Each query has a 10-second timeout.
83
+ Branch changes clear the old PR before querying the new branch.
84
+ Closed and merged PRs remain visible for 24 hours, then expire without waiting for the next refresh.
85
+ Missing `gh`, missing authentication, no current PR, timeout, malformed or oversized output, and network failures all render an empty module without exposing raw errors or credentials.
86
+
87
+ The query sends the repository and current branch through authenticated `gh` to the repository's configured GitHub host.
88
+ It requests only the fields above—never comments, review bodies, inline comments, or review threads.
89
+ Footer rendering and previews read only the immutable cached snapshot and perform no network or subprocess work.
90
+
91
+ **Breaking migration:** `$git_branch.$pr` has been removed without a compatibility alias or automatic migration.
92
+ Replace it with root `$github_pr` and an optional `[github_pr]` table.
93
+ If `pi-github-pr` remains installed, its independent `github-pr` status can also appear under `$extension_status`.
94
+ Disable or remove that extension when adopting the native module to avoid duplicate information.
95
+
96
+ ### 📦 Package and language modules
97
+
98
+ Module behavior is inspired by Starship pinned at `9f4d07ed45804e280d6884bb8ced7ea3d3033093`; formatter style semantics and the approved multi/state-style surfaces are aligned with the checked-in Starship source at `cad50cd8`.
99
+ This is not complete Starship module or configuration compatibility.
100
+
101
+ | Area | Adopted | Adapted | Intentionally omitted |
102
+ | --- | --- | --- | --- |
103
+ | `package` | `package.json` → Cargo → PEP 621/Poetry precedence, `$version` | Direct manifests only; Cargo workspace version lookup is capped at eight ancestors | Other package ecosystems, dynamic Python versions, package-manager execution |
104
+ | Node.js | Direct markers/extensions, `node --version`, package engine text | Bun/Deno markers suppress Node's default detection | Constraint checks and manager/shim evaluation |
105
+ | Python | Direct markers, selected interpreter `--version`, virtualenv name | Interpreter selection uses only an existing active virtualenv path or `python` | Python code execution and broad environment discovery |
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 and `go version` | `$mod_version` stays empty | `go list`, module downloads, and constraint enforcement |
108
+ | Bun / Deno | Direct markers and `bun --version` / `deno -V` | Negative detection avoids overlapping Node defaults | Runtime installation and recursive source detection |
109
+
110
+ All runtime commands use argv execution in `ctx.cwd`, a 2-second timeout, and 64 KiB accepted output.
111
+ Commands run only when the reachable module format references the command-backed variable.
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`.
114
+
115
+ ### 🧰 Development environments
116
+
117
+ | Module | Detection / allowed inputs | Optional command | Options |
118
+ | --- | --- | --- | --- |
119
+ | `mise` | Direct `mise.toml`, `.mise.toml`, or `.tool-versions` | `mise doctor` only for `$health` | Detection arrays |
120
+ | `direnv` | Direct `.envrc`; the file is never read or sourced | `direnv status --json` only for status variables | Detection arrays |
121
+ | `conda` | `CONDA_DEFAULT_ENV` only | None | `ignore_base` (default `true`) |
122
+ | `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 | None |
124
+ | `guix_shell` | Presence of `GUIX_ENVIRONMENT` | None | None |
125
+
126
+ The extension never enumerates the process environment, activates a shell, evaluates Nix, lists installed tools, or publishes arbitrary environment values.
127
+ Names and paths are control-sanitized and bounded before publication.
128
+
129
+ ### 🚢 Deployment and cloud context
130
+
131
+ These modules read inert local metadata only.
132
+ They do **not** contact Docker, Kubernetes, Terraform/OpenTofu backends, cloud APIs, OAuth flows, credential helpers, or metadata services.
133
+ They remain opt-in because context labels may be sensitive.
134
+
135
+ - `docker_context`: `DOCKER_CONTEXT`, then `DOCKER_CONFIG/config.json` or `~/.docker/config.json`.
136
+ The `default` context is suppressed.
137
+ `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.
139
+ Only context, namespace, cluster name, and user name are selected.
140
+ Exact `context_aliases`, `namespace_aliases`, `cluster_aliases`, and `user_aliases` apply.
141
+ - `terraform`: direct `.tf`, `.tfplan`, `.tfstate`, or `.terraform`; workspace precedence is `TF_WORKSPACE` → `TF_DATA_DIR/environment` → `.terraform/environment`.
142
+ `terraform version`, then `tofu version`, runs only for `$version`.
143
+ Workspace, init, provider, and state commands never run.
144
+ - `aws`: `AWS_PROFILE`/`AWS_DEFAULT_PROFILE`, `AWS_REGION`/`AWS_DEFAULT_REGION`, then the selected AWS config section.
145
+ The credentials file is never read.
146
+ Exact profile/region aliases are supported.
147
+ - `gcloud`: active selector plus allowlisted `core.account`, `core.project`, and `compute.region` INI keys.
148
+ Exact project/region aliases are supported.
149
+ - `azure`: the default local `azureProfile.json` subscription name.
150
+ `show_username` defaults to `false`; exact subscription aliases are supported.
151
+ - `openstack`: `OS_CLOUD`, `OS_PROJECT_NAME`, or the selected `clouds.yaml` `auth.project_name` only.
152
+ Exact cloud/project aliases are supported.
153
+
154
+ Cloud files often colocate credentials with labels.
155
+ Parsers allowlist fields while reading and discard source documents; token, key, password, auth URL, tenant, and credential-derived duration fields never enter snapshots, diagnostics, notifications, or rendered output.
156
+ Presence indicates only selected local metadata—not valid credentials or connectivity.
157
+
158
+ ### 🖥️ Execution context
159
+
160
+ `hostname` is SSH-only by default and supports `ssh_only`, `trim_at`, and exact `aliases`.
161
+ `username` appears only for `show_always`, SSH, root/Administrator, a login-user mismatch, or configured `detect_env_vars`; it supports exact aliases.
162
+ Negated username detection names are rejected.
163
+ `os` is disabled by default and supports an exact `symbols` map.
164
+ `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.
166
+ All identity labels are bounded and stripped of C0/C1 controls, ANSI, newlines, and OSC control bytes.
167
+
168
+ ## 📐 Layout and lifecycle
169
+
170
+ ### ↔️ Fill layout
171
+
172
+ Add `${fill}` between left and right root content (braces disambiguate adjacent text):
173
+
174
+ ```toml
175
+ format = "$directory$git_branch${fill}$model$context"
176
+
177
+ [fill]
178
+ symbol = " " # native invisible default; use "·" for a visible pattern
179
+ style = "dimmed"
180
+ ```
181
+
182
+ Fill resolves independently on each logical line before ANSI serialization and wrapping.
183
+ Multiple fills divide remaining cells left-to-right; complete positive-width patterns repeat and any remainder uses styled spaces.
184
+ Empty/zero-width patterns become spaces.
185
+ Fixed content is never truncated: when it already meets or exceeds the width, fill contributes zero and normal ANSI-aware wrapping applies.
186
+ Unicode wide/combining symbols, palettes, `prev_fg`/`prev_bg`, ANSI, and OSC hyperlinks use Pi TUI visible-width semantics.
187
+ `$all` deliberately includes enabled fill, so use `$all` only when that whole-catalog layout is intended.
188
+ There is no `line_break` module; use literal newlines in `format`.
189
+
190
+ ### 🔄 Cached refresh lifecycle
191
+
192
+ Workspace, Git, and GitHub PR readers start only in TUI sessions and only for reachable enabled modules.
193
+ Root format reachability, `$all`, module `disabled`, and module-format variables determine file and command requirements.
194
+ Workspace/Git refreshes run at session start, after accepted settings, branch changes, tool/turn completion, and a 30-second fallback.
195
+ GitHub PR uses the narrower lifecycle and 60-second network refresh described above.
196
+ One read runs with at most one latest pending refresh.
197
+ Immutable snapshot equality suppresses redraws, and session or request generations reject stale results.
198
+ 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.
199
+ Bounded local filesystem operations may finish, but stale generations cannot publish them.
200
+ Execution identity is retained rather than re-read by the periodic fallback.
201
+ Render and live preview consume snapshots synchronously and perform zero reads or commands.
202
+
203
+ Missing, unreadable, malformed, oversized, timed-out, or unavailable sources produce empty values.
204
+ Workspace and Git readers cap direct files at 64 KiB, use one bounded current-directory listing, never recurse, and make no network calls.
205
+ The native GitHub PR query is the documented network exception.
206
+ The Cargo package lookup is the only ancestor walk and stops after eight parents.
207
+
208
+ ## 🚧 Limitations
209
+
210
+ - The formatter and modules are Starship-inspired, not fully compatible with Starship.
211
+ - The extension does not load `starship.toml`, invoke the Starship binary, run custom shell modules, or provide unrestricted `env_var` behavior.
212
+ - JVM/.NET, other long-tail languages, alternative version-control systems, system monitoring, and additional DevOps modules are not implemented.
213
+ - Pi does not expose the auto-compaction toggle, so the footer cannot reliably show Pi's native `(auto)` marker.
@@ -0,0 +1,64 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { randomUUID } from "node:crypto";
4
+ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
5
+ import { basename, dirname, isAbsolute, join } from "node:path";
6
+ import { parse } from "smol-toml";
7
+ import { formatDisplayValue, formatError } from "./script-support.mjs";
8
+
9
+ const [draftPath, destinationPath, expectedPath, ...extraArguments] = process.argv.slice(2);
10
+
11
+ if (!draftPath || !destinationPath || !expectedPath || extraArguments.length > 0) {
12
+ console.error(
13
+ "Usage: node scripts/apply.mjs <draft-path> <absolute-pi-starship.toml-path> <expected-path|--expect-missing>",
14
+ );
15
+ process.exitCode = 2;
16
+ } else if (!isAbsolute(destinationPath) || basename(destinationPath) !== "pi-starship.toml") {
17
+ console.error("The destination must be an absolute path named pi-starship.toml.");
18
+ process.exitCode = 2;
19
+ } else {
20
+ let temporaryPath;
21
+ try {
22
+ const draft = await readFile(draftPath, "utf8");
23
+ const expectMissing = expectedPath === "--expect-missing";
24
+ const expected = expectMissing ? undefined : await readFile(expectedPath, "utf8");
25
+ await mkdir(dirname(destinationPath), { recursive: true });
26
+ temporaryPath = join(dirname(destinationPath), `.pi-starship.toml.${randomUUID()}.tmp`);
27
+ await writeFile(temporaryPath, draft, { encoding: "utf8", flag: "wx" });
28
+ parse(await readFile(temporaryPath, "utf8"));
29
+ await assertDestinationUnchanged(destinationPath, expectMissing, expected);
30
+ await rename(temporaryPath, destinationPath);
31
+ temporaryPath = undefined;
32
+ console.log(`Applied valid TOML atomically to ${formatDisplayValue(destinationPath)}`);
33
+ } catch (error) {
34
+ console.error(
35
+ `Draft was not applied to ${formatDisplayValue(destinationPath)}: ${formatError(error)}`,
36
+ );
37
+ process.exitCode = 1;
38
+ } finally {
39
+ if (temporaryPath) {
40
+ try {
41
+ await rm(temporaryPath, { force: true });
42
+ } catch {
43
+ // Cleanup is best-effort and must not obscure the original failure.
44
+ }
45
+ }
46
+ }
47
+ }
48
+
49
+ async function assertDestinationUnchanged(destinationPath, expectMissing, expected) {
50
+ let current;
51
+ try {
52
+ current = await readFile(destinationPath, "utf8");
53
+ } catch (error) {
54
+ if (error && typeof error === "object" && error.code === "ENOENT") {
55
+ if (expectMissing) return;
56
+ throw new Error("The active pi-starship.toml was removed after inspection.");
57
+ }
58
+ throw error;
59
+ }
60
+ if (!expectMissing && current === expected) return;
61
+ throw new Error(
62
+ "The active pi-starship.toml changed after inspection; the newer file was preserved.",
63
+ );
64
+ }
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { resolve } from "node:path";
4
+ import { getAgentDir } from "@earendil-works/pi-coding-agent";
5
+
6
+ if (process.argv.length > 2) {
7
+ console.error("Usage: node scripts/config-path.mjs");
8
+ process.exitCode = 2;
9
+ } else {
10
+ process.stdout.write(`${JSON.stringify(resolve(getAgentDir(), "pi-starship.toml"))}\n`);
11
+ }
@@ -0,0 +1,20 @@
1
+ import { sanitizeTerminalText } from "@narumitw/pi-tui-kit/terminal-text";
2
+
3
+ const MAX_ERROR_LENGTH = 1000;
4
+ const MAX_ERROR_SOURCE_LENGTH = 8000;
5
+ const MAX_DISPLAY_VALUE_LENGTH = 500;
6
+
7
+ export function formatError(error) {
8
+ const raw = error instanceof Error ? error.message : String(error);
9
+ return sanitizeAndBound(raw, MAX_ERROR_LENGTH, MAX_ERROR_SOURCE_LENGTH);
10
+ }
11
+
12
+ export function formatDisplayValue(value) {
13
+ return JSON.stringify(sanitizeAndBound(String(value), MAX_DISPLAY_VALUE_LENGTH, 4000));
14
+ }
15
+
16
+ function sanitizeAndBound(value, maximumLength, maximumSourceLength) {
17
+ const result = sanitizeTerminalText(value.slice(0, maximumSourceLength));
18
+ const truncated = value.length > maximumSourceLength || result.length > maximumLength;
19
+ return truncated ? `${result.slice(0, Math.max(0, maximumLength - 1))}…` : result;
20
+ }
@@ -0,0 +1,30 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { readFile } from "node:fs/promises";
4
+ import { parse } from "smol-toml";
5
+ import { formatDisplayValue, formatError } from "./script-support.mjs";
6
+
7
+ const [filePath, ...extraArguments] = process.argv.slice(2);
8
+
9
+ if (!filePath || extraArguments.length > 0) {
10
+ console.error("Usage: node scripts/validate.mjs <absolute-pi-starship.toml-path>");
11
+ process.exitCode = 2;
12
+ } else {
13
+ let document;
14
+ try {
15
+ document = await readFile(filePath, "utf8");
16
+ } catch (error) {
17
+ console.error(`Unable to read ${formatDisplayValue(filePath)}: ${formatError(error)}`);
18
+ process.exitCode = 1;
19
+ }
20
+
21
+ if (document !== undefined) {
22
+ try {
23
+ parse(document);
24
+ console.log(`Valid TOML: ${formatDisplayValue(filePath)}`);
25
+ } catch (error) {
26
+ console.error(`Invalid TOML in ${formatDisplayValue(filePath)}: ${formatError(error)}`);
27
+ process.exitCode = 1;
28
+ }
29
+ }
30
+ }
@@ -95,7 +95,7 @@ const MODULE_DESCRIPTIONS = {
95
95
  nodejs: "Node.js version detected in the current workspace.",
96
96
  openstack: "Active OpenStack cloud and project.",
97
97
  os: "Current operating system identity.",
98
- package: "Current workspace package name and version.",
98
+ package: "Current workspace package version and manifest source.",
99
99
  pixi: "Active Pixi environment and project.",
100
100
  provider: "Current Pi model provider.",
101
101
  python: "Python version, virtual environment, and pyenv state.",
@@ -35,8 +35,9 @@ export async function collectCloud(context: CollectorContext): Promise<MutableMo
35
35
 
36
36
  async function collectAws(context: CollectorContext): Promise<Record<string, string> | undefined> {
37
37
  const env = context.input.environment;
38
- const profile = safeMetadata(env.AWS_PROFILE ?? env.AWS_DEFAULT_PROFILE) ?? "default";
39
- let region = safeMetadata(env.AWS_REGION ?? env.AWS_DEFAULT_REGION);
38
+ const profile =
39
+ safeMetadata(env.AWS_PROFILE) ?? safeMetadata(env.AWS_DEFAULT_PROFILE) ?? "default";
40
+ let region = safeMetadata(env.AWS_REGION) ?? safeMetadata(env.AWS_DEFAULT_REGION);
40
41
  if (!region) {
41
42
  const configPath =
42
43
  safeMetadata(env.AWS_CONFIG_FILE, 1_024) ?? joinHome(context.input, ".aws", "config");
@@ -141,7 +141,7 @@ async function readPixiProject(context: CollectorContext): Promise<string | unde
141
141
  const document = parse(source);
142
142
  const project = isRecord(document.project) ? document.project : undefined;
143
143
  const workspace = isRecord(document.workspace) ? document.workspace : undefined;
144
- return safeMetadata(project?.name ?? workspace?.name);
144
+ return safeMetadata(project?.name) ?? safeMetadata(workspace?.name);
145
145
  } catch {
146
146
  return undefined;
147
147
  }
@@ -109,7 +109,7 @@ function usernameValues(context: CollectorContext): Record<string, string> | und
109
109
  const user = safeMetadata(context.input.username);
110
110
  if (!user) return undefined;
111
111
  const env = context.input.environment;
112
- const login = safeMetadata(env.LOGNAME ?? env.USER ?? env.USERNAME);
112
+ const login = safeMetadata(env.LOGNAME) ?? safeMetadata(env.USER) ?? safeMetadata(env.USERNAME);
113
113
  const privileged = /^(?:root|administrator)$/iu.test(user);
114
114
  const detected = optionStrings(context, "username", "detect_env_vars").some(
115
115
  (name) => safeMetadata(env[name]) !== undefined,
@@ -95,7 +95,7 @@ function addEnvironmentValues(
95
95
  ): void {
96
96
  const env = context.input.environment;
97
97
  if (name === "python") {
98
- const virtualenv = safeMetadata(env.VIRTUAL_ENV ?? env.CONDA_DEFAULT_ENV);
98
+ const virtualenv = safeMetadata(env.VIRTUAL_ENV) ?? safeMetadata(env.CONDA_DEFAULT_ENV);
99
99
  if (virtualenv && context.needs(name, "virtualenv")) values.virtualenv = pathName(virtualenv);
100
100
  const pyenv = safeMetadata(env.PYENV_VERSION);
101
101
  if (pyenv && context.needs(name, "pyenv_prefix")) values.pyenv_prefix = pyenv;