@narumitw/pi-starship 0.22.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 narumiruna
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICES.md ADDED
@@ -0,0 +1,21 @@
1
+ # Notices
2
+
3
+ pi-starship's format and style behavior is based in part on Starship.
4
+
5
+ ## Starship
6
+
7
+ ISC License
8
+
9
+ Copyright (c) 2019-2022, Starship Contributors
10
+
11
+ Permission to use, copy, modify, and/or distribute this software for any
12
+ purpose with or without fee is hereby granted, provided that the above
13
+ copyright notice and this permission notice appear in all copies.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
16
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
17
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
18
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
20
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
21
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,166 @@
1
+ # 🚀 pi-starship — Native Starship-style Statusline for Pi
2
+
3
+ [![npm](https://img.shields.io/npm/v/@narumitw/pi-starship)](https://www.npmjs.com/package/@narumitw/pi-starship) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
+
5
+ A native Pi footer configured with Starship-style TOML. It parses and renders formats itself—no `starship` executable or shell prompt required.
6
+
7
+ > **Different package:** the unscoped npm package `pi-starship` delegates to the Starship binary. This package is `@narumitw/pi-starship` and renders Pi-specific modules natively.
8
+
9
+ ## ✨ Features
10
+
11
+ - Automatically creates a readable Tokyo Night configuration on first session start.
12
+ - Starship-style root/module formats, conditional groups, `$all`, styles, and palettes.
13
+ - Pi modules for model, thinking, activity, context, tokens, cost, turn, and extension statuses.
14
+ - Cached Git branch/status rendering and linked-worktree identity; no subprocess runs during footer rendering.
15
+ - Multiline output wraps to the terminal width instead of truncating.
16
+ - Transactional TOML editing through `/starship settings`.
17
+
18
+ ## 📦 Install
19
+
20
+ ```bash
21
+ pi install npm:@narumitw/pi-starship
22
+ ```
23
+
24
+ Try it from a checkout:
25
+
26
+ ```bash
27
+ pi -e ./extensions/pi-starship
28
+ ```
29
+
30
+ Do not enable this together with `@narumitw/pi-statusline`: both own Pi's footer. `pi-starship` warns when it detects the conflict.
31
+
32
+ ## ⚙️ Configuration
33
+
34
+ The only configuration source is:
35
+
36
+ ```text
37
+ <getAgentDir()>/pi-starship.toml
38
+ ```
39
+
40
+ On the first session start, the extension atomically creates this file from its readable Tokyo Night default. It never overwrites an existing document, including a malformed one. If initialization fails, the built-in configuration remains active and the failure is reported as a warning.
41
+
42
+ The extension does **not** read project overrides, `pi-statusline.json`, `PI_STATUSLINE_PRESET`, or `~/.config/starship.toml`, and does not migrate statusline settings.
43
+
44
+ Open the file transactionally in TUI mode:
45
+
46
+ ```text
47
+ /starship settings
48
+ ```
49
+
50
+ A successful edit is validated, atomically saved, and applied immediately. Invalid or cancelled edits leave the previous file and effective config unchanged.
51
+
52
+ ### 📝 Example
53
+
54
+ ```toml
55
+ format = "$brand$provider$model$thinking\n$directory$git_branch$git_status\n$activity$context$tokens$cost$time$turn\n$extension_status"
56
+ palette = "tokyo-night"
57
+
58
+ [palettes.tokyo-night]
59
+ header = "#7aa2f7"
60
+ header_fg = "#1a1b26"
61
+ custom = "208"
62
+
63
+ [model]
64
+ format = "[ $symbol$model ]($style)"
65
+ symbol = "◆ "
66
+ style = "bold fg:header_fg bg:header"
67
+ disabled = false
68
+
69
+ [activity]
70
+ format = "([ $text ]($style))"
71
+ style = "fg:custom"
72
+
73
+ [git_branch]
74
+ format = "[ $symbol$branch$pr ]($style)"
75
+
76
+ [extension_status]
77
+ format = "([$statuses ]($style))"
78
+ icons = { "github-pr" = "PR", "@narumitw/pi-goal" = "◎", fallback = "•" }
79
+ ```
80
+
81
+ All module tables support `format`, `symbol`, `style`, and `disabled`. `[extension_status].icons` additionally maps exact status keys or installed package IDs; `fallback` controls unmatched statuses.
82
+
83
+ ## 🧩 Format grammar
84
+
85
+ - Variables: `$name` and `${name}`. Unknown variables render empty and produce a warning when loaded from TOML.
86
+ - Escapes: `\\$`, `\\[`, `\\]`, `\\(`, `\\)`, and `\\\\` render functional characters literally.
87
+ - Styled groups: `[format string](style string)`.
88
+ - Conditional groups: `(format string)` render only when a nested variable has a non-empty value.
89
+ - Nested groups are supported.
90
+ - `$all` expands enabled modules in the default order and omits modules already referenced explicitly.
91
+
92
+ Module formats can use `$style` in a style expression. Module output keeps its own style when embedded in an outer styled group.
93
+
94
+ ## 🎨 Styles and palettes
95
+
96
+ Style expressions support:
97
+
98
+ - Named colors and ANSI numbers `0`–`255`.
99
+ - Hex RGB (`#7aa2f7`).
100
+ - `fg:<color>` and `bg:<color>`; an unprefixed color is foreground.
101
+ - `bold`, `dimmed`, `italic`, `underline`, `blink`, `inverted`, `hidden`, and `strikethrough`.
102
+ - `none`, `fg:none`, and `bg:none`.
103
+ - `prev_fg` and `prev_bg` to inherit the previous rendered chunk's colors.
104
+ - Color names from the active `[palettes.<name>]` table. The active palette overlays the built-in Tokyo Night colors so the default module styles remain available.
105
+
106
+ An invalid root format falls back to the built-in root format. An invalid module format or style falls back only for that module. `/starship status` reports warnings.
107
+
108
+ ## 🧱 Modules
109
+
110
+ | Module | Format variables | Meaning |
111
+ | --- | --- | --- |
112
+ | `brand` | `$symbol` | Pi brand marker |
113
+ | `provider` | `$symbol`, `$provider` | Current model provider |
114
+ | `model` | `$symbol`, `$model` | Current model name |
115
+ | `thinking` | `$symbol`, `$level` | Thinking level |
116
+ | `directory` | `$symbol`, `$path`, `$full_path` | Current working directory |
117
+ | `git_worktree` | `$symbol`, `$name`, `$path` | Linked worktree name and top-level path |
118
+ | `git_branch` | `$symbol`, `$branch`, `$pr` | Cached branch and actionable PR state |
119
+ | `git_status` | `$symbol`, `$all_status`, `$ahead`, `$behind`, `$staged`, `$modified`, `$untracked`, `$conflicted` | Cached porcelain counters |
120
+ | `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$text` | Active tools, streaming, completion, or idle |
121
+ | `context` | `$symbol`, `$percentage`, `$tokens`, `$window` | Context-window use |
122
+ | `tokens` | `$symbol`, `$input`, `$output`, `$total` | Token totals |
123
+ | `cost` | `$symbol`, `$cost` | Session cost |
124
+ | `time` | `$symbol`, `$time` | Current local time |
125
+ | `turn` | `$symbol`, `$count` | User turn count |
126
+ | `extension_status` | `$symbol`, `$statuses`, `$count` | Pi extension statuses |
127
+
128
+ `git_worktree` is empty in the primary worktree. In a linked worktree it defaults to the top-level directory name; use `$path` when the full absolute path is needed.
129
+
130
+ If `$git_branch.$pr` is present in the module format, its selected PR token is removed from `extension_status` to avoid duplication.
131
+
132
+ ## 💬 Commands
133
+
134
+ | Command | Purpose |
135
+ | --- | --- |
136
+ | `/starship settings` | Edit, validate, save, and immediately apply TOML (TUI only) |
137
+ | `/starship status` | Show config source/path and diagnostics |
138
+ | `/starship help` | Show command and configuration help |
139
+
140
+ Status and help are safe in TUI, RPC, JSON, and print modes. Footer/timer/Git lifecycle work starts only in TUI mode.
141
+
142
+ ## 📐 Scope
143
+
144
+ The formatter grammar and style concepts follow Starship, but the module catalog is intentionally Pi-specific. This extension does not claim compatibility with Starship's shell module catalog or execute the Starship binary.
145
+
146
+ ## ➕ Adding a module
147
+
148
+ Create `src/modules/<name>.ts` with its format variables, defaults, and runtime value resolver, then register it in display order in `src/modules/catalog.ts`. Configuration names, validation variables, defaults, and `$all` ordering are derived from that catalog. Add the module to the built-in root format when it should be visible by default, then document and test its user-facing values.
149
+
150
+ Keep `extension_status` last in the catalog so earlier modules can consume extension-owned status values without rendering duplicates.
151
+
152
+ ## 🗂️ Package layout
153
+
154
+ - `src/pi-starship.ts` — extension lifecycle and footer.
155
+ - `src/config.ts` — TOML loading, validation, defaults, and persistence.
156
+ - `src/format/` — native format/style parser and renderer.
157
+ - `src/modules/` — module-per-file definitions, ordered registry, and statusline renderer.
158
+ - `src/modules/git/` — shared Git runtime plus branch, status, and worktree modules.
159
+
160
+ ## 🔎 Keywords
161
+
162
+ Pi Coding Agent, Starship statusline, Starship TOML, terminal footer, native statusline, Pi extension
163
+
164
+ ## 📄 License
165
+
166
+ MIT. See [`LICENSE`](./LICENSE). Starship attribution and its ISC license are included in [`NOTICES.md`](./NOTICES.md).
package/package.json ADDED
@@ -0,0 +1,52 @@
1
+ {
2
+ "name": "@narumitw/pi-starship",
3
+ "version": "0.22.0",
4
+ "description": "Native Starship-style TOML statusline for the Pi coding agent.",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "private": false,
8
+ "keywords": [
9
+ "pi-package",
10
+ "pi-extension",
11
+ "pi",
12
+ "starship",
13
+ "statusline",
14
+ "footer",
15
+ "toml"
16
+ ],
17
+ "files": [
18
+ "src",
19
+ "README.md",
20
+ "LICENSE",
21
+ "NOTICES.md"
22
+ ],
23
+ "pi": {
24
+ "extensions": [
25
+ "./src/pi-starship.ts"
26
+ ]
27
+ },
28
+ "scripts": {
29
+ "check": "biome check --vcs-use-ignore-file=false src test package.json tsconfig.json README.md NOTICES.md && npm run typecheck",
30
+ "format": "biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json README.md NOTICES.md",
31
+ "typecheck": "tsc --noEmit"
32
+ },
33
+ "dependencies": {
34
+ "smol-toml": "^1.7.0"
35
+ },
36
+ "peerDependencies": {
37
+ "@earendil-works/pi-coding-agent": "*",
38
+ "@earendil-works/pi-tui": "*"
39
+ },
40
+ "devDependencies": {
41
+ "@biomejs/biome": "2.5.3",
42
+ "@earendil-works/pi-coding-agent": "0.80.10",
43
+ "@earendil-works/pi-tui": "0.80.10",
44
+ "@types/node": "26.1.1",
45
+ "typescript": "7.0.2"
46
+ },
47
+ "repository": {
48
+ "type": "git",
49
+ "url": "https://github.com/narumiruna/pi-extensions",
50
+ "directory": "extensions/pi-starship"
51
+ }
52
+ }
@@ -0,0 +1,108 @@
1
+ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
2
+ import type { AutocompleteItem } from "@earendil-works/pi-tui";
3
+ import { atomicSaveConfigDocument, BUILT_IN_EXAMPLE, type LoadedStarshipConfig } from "./config.js";
4
+
5
+ const SUBCOMMANDS: AutocompleteItem[] = [
6
+ { value: "settings", label: "settings", description: "Edit pi-starship.toml" },
7
+ { value: "status", label: "status", description: "Show the effective settings source" },
8
+ { value: "help", label: "help", description: "Show configuration help" },
9
+ ];
10
+
11
+ export interface StarshipCommandOptions {
12
+ getLoaded(): LoadedStarshipConfig;
13
+ apply(loaded: LoadedStarshipConfig, ctx: ExtensionCommandContext): void;
14
+ settingsPath: string;
15
+ save?: (settingsPath: string, rawDocument: string) => LoadedStarshipConfig;
16
+ }
17
+
18
+ export function registerStarshipCommand(pi: ExtensionAPI, options: StarshipCommandOptions) {
19
+ pi.registerCommand("starship", {
20
+ description: "Edit or inspect the native Starship-style footer settings",
21
+ getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
22
+ const normalized = prefix.trim().toLowerCase();
23
+ const matches = SUBCOMMANDS.filter((item) => item.value.startsWith(normalized));
24
+ return matches.length > 0 ? matches : null;
25
+ },
26
+ handler: async (args, ctx) => {
27
+ const subcommand = args.trim().split(/\s+/u)[0]?.toLowerCase() || "help";
28
+ switch (subcommand) {
29
+ case "settings":
30
+ await editSettings(ctx, options);
31
+ return;
32
+ case "status":
33
+ showStatus(ctx, options);
34
+ return;
35
+ case "help":
36
+ showHelp(ctx, options.settingsPath);
37
+ return;
38
+ default:
39
+ if (canNotify(ctx)) {
40
+ ctx.ui.notify(`Unknown /starship subcommand: ${subcommand}`, "warning");
41
+ }
42
+ }
43
+ },
44
+ });
45
+ }
46
+
47
+ async function editSettings(ctx: ExtensionCommandContext, options: StarshipCommandOptions) {
48
+ if (ctx.mode !== "tui") {
49
+ if (ctx.hasUI) ctx.ui.notify(`Edit settings manually: ${options.settingsPath}`, "info");
50
+ return;
51
+ }
52
+ const current = options.getLoaded();
53
+ const edited = await ctx.ui.editor(
54
+ "pi-starship.toml — save and close to apply",
55
+ current.rawDocument ?? BUILT_IN_EXAMPLE,
56
+ );
57
+ if (edited === undefined) return;
58
+ try {
59
+ const loaded = (options.save ?? atomicSaveConfigDocument)(options.settingsPath, edited);
60
+ options.apply(loaded, ctx);
61
+ const warningSuffix =
62
+ loaded.diagnostics.length > 0
63
+ ? ` (${loaded.diagnostics.length} warning${loaded.diagnostics.length === 1 ? "" : "s"})`
64
+ : "";
65
+ ctx.ui.notify(`pi-starship settings saved and applied${warningSuffix}.`, "info");
66
+ } catch (error) {
67
+ ctx.ui.notify(`pi-starship settings were not saved: ${formatError(error)}`, "error");
68
+ }
69
+ }
70
+
71
+ function showStatus(ctx: ExtensionCommandContext, options: StarshipCommandOptions) {
72
+ if (!canNotify(ctx)) return;
73
+ const loaded = options.getLoaded();
74
+ const diagnostics = loaded.diagnostics
75
+ .slice(0, 5)
76
+ .map((item) => `${item.path || "root"}: ${item.message}`)
77
+ .join("; ");
78
+ ctx.ui.notify(
79
+ [
80
+ `pi-starship source: ${loaded.source}`,
81
+ `path: ${options.settingsPath}`,
82
+ diagnostics ? `warnings: ${diagnostics}` : "warnings: none",
83
+ ].join("\n"),
84
+ loaded.diagnostics.length > 0 ? "warning" : "info",
85
+ );
86
+ }
87
+
88
+ function showHelp(ctx: ExtensionCommandContext, settingsPath: string) {
89
+ if (!canNotify(ctx)) return;
90
+ ctx.ui.notify(
91
+ [
92
+ "/starship settings — edit and apply TOML",
93
+ "/starship status — show source, path, and warnings",
94
+ "/starship help — show this help",
95
+ `Settings: ${settingsPath}`,
96
+ "Format/module docs: https://github.com/narumiruna/pi-extensions/tree/main/extensions/pi-starship",
97
+ ].join("\n"),
98
+ "info",
99
+ );
100
+ }
101
+
102
+ function canNotify(ctx: ExtensionCommandContext): boolean {
103
+ return ctx.mode === "tui" || ctx.hasUI;
104
+ }
105
+
106
+ function formatError(error: unknown): string {
107
+ return error instanceof Error ? error.message : String(error);
108
+ }