@narumitw/pi-starship 0.44.0 → 0.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +188 -65
  2. package/package.json +2 -2
  3. package/src/command-inspector.ts +470 -0
  4. package/src/command-preview.ts +206 -0
  5. package/src/commands.ts +168 -158
  6. package/src/config.ts +177 -68
  7. package/src/format/style.ts +64 -45
  8. package/src/modules/activity.ts +1 -1
  9. package/src/modules/brand.ts +1 -1
  10. package/src/modules/cache.ts +1 -1
  11. package/src/modules/catalog.ts +62 -3
  12. package/src/modules/context.ts +13 -1
  13. package/src/modules/cost.ts +12 -1
  14. package/src/modules/development.ts +1 -1
  15. package/src/modules/directory.ts +1 -1
  16. package/src/modules/display.ts +14 -0
  17. package/src/modules/execution.ts +12 -1
  18. package/src/modules/extension-status.ts +1 -1
  19. package/src/modules/fill.ts +1 -1
  20. package/src/modules/git/branch.ts +1 -1
  21. package/src/modules/git/commit.ts +1 -1
  22. package/src/modules/git/metrics.ts +8 -2
  23. package/src/modules/git/state.ts +1 -1
  24. package/src/modules/git/status.ts +1 -1
  25. package/src/modules/git/worktree.ts +1 -1
  26. package/src/modules/github-pr.ts +1 -1
  27. package/src/modules/index.ts +13 -1
  28. package/src/modules/inspection.ts +138 -0
  29. package/src/modules/model.ts +1 -1
  30. package/src/modules/provider.ts +1 -1
  31. package/src/modules/render.ts +22 -3
  32. package/src/modules/thinking.ts +1 -1
  33. package/src/modules/time.ts +1 -1
  34. package/src/modules/tokens.ts +1 -1
  35. package/src/modules/turn.ts +1 -1
  36. package/src/modules/types.ts +19 -0
  37. package/src/pi-starship.ts +21 -0
  38. package/src/runtime/execution.ts +15 -3
  39. package/src/runtime/types.ts +2 -0
  40. package/src/runtime/workspace.ts +21 -7
package/src/config.ts CHANGED
@@ -18,7 +18,11 @@ import {
18
18
  } from "./format/formatter.js";
19
19
  import { type ColorPalette, isValidStyle, parseColor } from "./format/style.js";
20
20
  import { MODULE_DEFINITIONS, MODULE_NAMES, type ModuleName } from "./modules/catalog.js";
21
- import type { ModuleOptionSchema, ModuleOptionValue } from "./modules/types.js";
21
+ import type {
22
+ ModuleDisplayConfig,
23
+ ModuleOptionSchema,
24
+ ModuleOptionValue,
25
+ } from "./modules/types.js";
22
26
 
23
27
  export const CONFIG_FILE_NAME = "pi-starship.toml";
24
28
  export { MODULE_NAMES, type ModuleName } from "./modules/catalog.js";
@@ -32,6 +36,8 @@ export interface ModuleConfig {
32
36
  formatAst: FormatNode[];
33
37
  symbol: string;
34
38
  style: string;
39
+ styles: Record<string, string>;
40
+ display: ModuleDisplayConfig[];
35
41
  disabled: boolean;
36
42
  options: Record<string, ModuleOptionValue>;
37
43
  }
@@ -45,7 +51,7 @@ export interface ExtensionStatusConfig {
45
51
  export interface StarshipConfig {
46
52
  format: string;
47
53
  formatAst: FormatNode[];
48
- palette: string;
54
+ palette?: string;
49
55
  palettes: Record<string, Record<string, string>>;
50
56
  modules: Record<ModuleName, ModuleConfig>;
51
57
  extensionStatus: ExtensionStatusConfig;
@@ -67,52 +73,26 @@ export interface LoadedStarshipConfig {
67
73
  }
68
74
 
69
75
  const BUILT_IN_FORMAT_DOCUMENT = String.raw`format = """
70
- [░▒▓](lead)\
71
76
  $brand\
72
- $provider\
73
77
  $model\
74
78
  $thinking\
75
- [](fg:header bg:directory)\
76
79
  $directory\
77
- [](fg:directory bg:git)\
78
- $git_worktree\
79
80
  $git_branch\
80
- $github_pr\
81
81
  $git_status\
82
- [](fg:git bg:runtime)\
83
82
  $activity\
84
83
  $context\
85
- $tokens\
86
- $cache\
87
- [](fg:runtime bg:meter)\
88
- $cost\
89
- $time\
90
- [](fg:meter)\
91
- (\n$extension_status)"""`;
84
+ $time"""`;
92
85
 
93
86
  const BUILT_IN_FORMAT = parseBuiltInFormat(BUILT_IN_FORMAT_DOCUMENT);
94
87
 
95
- const BUILT_IN_PALETTE = {
96
- lead: "#a3aed2",
97
- header: "#a3aed2",
98
- header_fg: "#090c0c",
99
- directory: "#769ff0",
100
- directory_fg: "#e3e5e5",
101
- git: "#394260",
102
- git_fg: "#769ff0",
103
- runtime: "#212736",
104
- runtime_fg: "#769ff0",
105
- meter: "#1d2230",
106
- meter_fg: "#a0a9cb",
107
- extension: "#a0a9cb",
108
- };
109
-
110
88
  const BUILT_IN_MODULES = Object.fromEntries(
111
- MODULE_DEFINITIONS.map(({ name, defaults, options }) => [
89
+ MODULE_DEFINITIONS.map(({ name, defaults, styleDefaults, displayDefaults, options }) => [
112
90
  name,
113
91
  {
114
92
  ...defaults,
115
93
  formatAst: parseFormat(defaults.format),
94
+ styles: { ...styleDefaults },
95
+ display: structuredClone(displayDefaults ?? []),
116
96
  options: Object.fromEntries(
117
97
  Object.entries(options ?? {}).map(([key, schema]) => [
118
98
  key,
@@ -126,17 +106,13 @@ const BUILT_IN_MODULES = Object.fromEntries(
126
106
  export const BUILT_IN_CONFIG: StarshipConfig = {
127
107
  format: BUILT_IN_FORMAT,
128
108
  formatAst: parseFormat(BUILT_IN_FORMAT),
129
- palette: "tokyo-night",
130
- palettes: { "tokyo-night": BUILT_IN_PALETTE },
109
+ palette: undefined,
110
+ palettes: {},
131
111
  modules: BUILT_IN_MODULES,
132
112
  extensionStatus: { separator: " • ", maxStatuses: 5, icons: {} },
133
113
  };
134
114
 
135
- export const BUILT_IN_EXAMPLE = `# Native Pi modules with Starship-compatible format and style syntax.\n${BUILT_IN_FORMAT_DOCUMENT}\npalette = "tokyo-night"\n\n[palettes.tokyo-night]\n${Object.entries(
136
- BUILT_IN_PALETTE,
137
- )
138
- .map(([name, color]) => `${name} = "${color}"`)
139
- .join("\n")}\n`;
115
+ export const BUILT_IN_EXAMPLE = `# Native Pi modules with Starship-compatible format and style syntax.\n${BUILT_IN_FORMAT_DOCUMENT}\n`;
140
116
 
141
117
  function parseBuiltInFormat(document: string): string {
142
118
  const format = parse(document).format;
@@ -253,11 +229,14 @@ export function normalizeConfig(value: unknown): {
253
229
 
254
230
  if (value.palette !== undefined) {
255
231
  if (typeof value.palette !== "string") diagnostics.push(typeDiagnostic("palette", "string"));
256
- else if (!Object.hasOwn(config.palettes, value.palette)) {
257
- diagnostics.push(
258
- diagnostic("warning", "palette", `Unknown palette ${JSON.stringify(value.palette)}`),
259
- );
260
- } else config.palette = value.palette;
232
+ else {
233
+ config.palette = value.palette;
234
+ if (!Object.hasOwn(config.palettes, value.palette)) {
235
+ diagnostics.push(
236
+ diagnostic("warning", "palette", `Unknown palette ${JSON.stringify(value.palette)}`),
237
+ );
238
+ }
239
+ }
261
240
  }
262
241
 
263
242
  for (const name of MODULE_NAMES) {
@@ -278,7 +257,9 @@ export function normalizeConfig(value: unknown): {
278
257
  );
279
258
  validateStyleVariables(config.formatAst, new Set(), "format", diagnostics);
280
259
  const palette = activePalette(config);
281
- for (const name of MODULE_NAMES) {
260
+ validateLiteralStyles(config.formatAst, palette, "format", diagnostics);
261
+ for (const definition of MODULE_DEFINITIONS) {
262
+ const name = definition.name;
282
263
  const module = config.modules[name];
283
264
  validateFormatVariables(
284
265
  module.formatAst,
@@ -286,16 +267,19 @@ export function normalizeConfig(value: unknown): {
286
267
  `${name}.format`,
287
268
  diagnostics,
288
269
  );
289
- validateStyleVariables(module.formatAst, new Set(["style"]), `${name}.format`, diagnostics);
290
- if (!isValidStyle(module.style, palette)) {
291
- diagnostics.push(
292
- diagnostic(
293
- "warning",
294
- `${name}.style`,
295
- `Invalid style ${JSON.stringify(module.style)}; using the module default`,
296
- ),
297
- );
298
- module.style = BUILT_IN_CONFIG.modules[name].style;
270
+ validateStyleVariables(
271
+ module.formatAst,
272
+ new Set(definition.styleVariables ?? ["style"]),
273
+ `${name}.format`,
274
+ diagnostics,
275
+ );
276
+ validateLiteralStyles(module.formatAst, palette, `${name}.format`, diagnostics);
277
+ if (definition.styleDefaults) {
278
+ for (const field of Object.keys(definition.styleDefaults)) {
279
+ validateModuleStyleField(name, field, module, palette, diagnostics);
280
+ }
281
+ } else if (!definition.displayDefaults) {
282
+ validateModuleStyleField(name, "style", module, palette, diagnostics);
299
283
  }
300
284
  }
301
285
 
@@ -309,8 +293,13 @@ function normalizeModule(
309
293
  diagnostics: ConfigDiagnostic[],
310
294
  ) {
311
295
  const definition = MODULE_DEFINITIONS.find((candidate) => candidate.name === name);
312
- const optionSchemas: Readonly<Record<string, ModuleOptionSchema>> = definition?.options ?? {};
313
- const known = new Set(["format", "symbol", "style", "disabled", ...Object.keys(optionSchemas)]);
296
+ if (!definition) return;
297
+ const optionSchemas: Readonly<Record<string, ModuleOptionSchema>> = definition.options ?? {};
298
+ const known = new Set(["format", "symbol", "disabled", ...Object.keys(optionSchemas)]);
299
+ if (definition.styleDefaults) {
300
+ for (const field of Object.keys(definition.styleDefaults)) known.add(field);
301
+ } else if (!definition.displayDefaults) known.add("style");
302
+ if (definition.displayDefaults) known.add("display");
314
303
  if (name === "extension_status") {
315
304
  known.add("separator");
316
305
  known.add("max_statuses");
@@ -338,11 +327,31 @@ function normalizeModule(
338
327
  }
339
328
  }
340
329
  }
341
- for (const field of ["symbol", "style"] as const) {
342
- if (value[field] === undefined) continue;
343
- if (typeof value[field] !== "string") {
344
- diagnostics.push(typeDiagnostic(`${name}.${field}`, "string"));
345
- } else module[field] = value[field];
330
+ if (value.symbol !== undefined) {
331
+ if (typeof value.symbol !== "string") {
332
+ diagnostics.push(typeDiagnostic(`${name}.symbol`, "string"));
333
+ } else module.symbol = value.symbol;
334
+ }
335
+ if (definition.styleDefaults) {
336
+ for (const field of Object.keys(definition.styleDefaults)) {
337
+ if (value[field] === undefined) continue;
338
+ if (typeof value[field] !== "string") {
339
+ diagnostics.push(typeDiagnostic(`${name}.${field}`, "string"));
340
+ } else module.styles[field] = value[field];
341
+ }
342
+ } else if (!definition.displayDefaults && value.style !== undefined) {
343
+ if (typeof value.style !== "string") {
344
+ diagnostics.push(typeDiagnostic(`${name}.style`, "string"));
345
+ } else module.style = value.style;
346
+ }
347
+ if (definition.displayDefaults && value.display !== undefined) {
348
+ module.display = normalizeDisplay(
349
+ name,
350
+ value.display,
351
+ definition.displayDefaults,
352
+ activePalette(config),
353
+ diagnostics,
354
+ );
346
355
  }
347
356
  if (value.disabled !== undefined) {
348
357
  if (typeof value.disabled !== "boolean") {
@@ -514,6 +523,8 @@ function cloneBuiltInConfig(): StarshipConfig {
514
523
  {
515
524
  ...BUILT_IN_CONFIG.modules[name],
516
525
  formatAst: structuredClone(BUILT_IN_CONFIG.modules[name].formatAst),
526
+ styles: { ...BUILT_IN_CONFIG.modules[name].styles },
527
+ display: structuredClone(BUILT_IN_CONFIG.modules[name].display),
517
528
  options: structuredClone(BUILT_IN_CONFIG.modules[name].options),
518
529
  },
519
530
  ]),
@@ -561,6 +572,107 @@ function validateStyleVariables(
561
572
  }
562
573
  }
563
574
 
575
+ function validateModuleStyleField(
576
+ name: ModuleName,
577
+ field: string,
578
+ module: ModuleConfig,
579
+ palette: ColorPalette,
580
+ diagnostics: ConfigDiagnostic[],
581
+ ) {
582
+ const style = field === "style" ? module.style : module.styles[field];
583
+ if (style === undefined || isValidStyle(style, palette)) return;
584
+ diagnostics.push(
585
+ diagnostic(
586
+ "warning",
587
+ `${name}.${field}`,
588
+ `Invalid style ${JSON.stringify(style)}; using the module default`,
589
+ ),
590
+ );
591
+ if (field === "style") module.style = BUILT_IN_CONFIG.modules[name].style;
592
+ else {
593
+ const fallback = BUILT_IN_CONFIG.modules[name].styles[field];
594
+ if (fallback !== undefined) module.styles[field] = fallback;
595
+ }
596
+ }
597
+
598
+ function normalizeDisplay(
599
+ name: ModuleName,
600
+ value: unknown,
601
+ defaults: readonly ModuleDisplayConfig[],
602
+ palette: ColorPalette,
603
+ diagnostics: ConfigDiagnostic[],
604
+ ): ModuleDisplayConfig[] {
605
+ if (!Array.isArray(value)) {
606
+ diagnostics.push(typeDiagnostic(`${name}.display`, "array of tables"));
607
+ return defaults.map((entry) => ({ ...entry }));
608
+ }
609
+ const result: ModuleDisplayConfig[] = [];
610
+ for (const [index, entry] of value.entries()) {
611
+ const path = `${name}.display.${index}`;
612
+ if (!isRecord(entry)) {
613
+ diagnostics.push(typeDiagnostic(path, "table"));
614
+ continue;
615
+ }
616
+ for (const field of Object.keys(entry)) {
617
+ if (!new Set(["threshold", "style", "hidden"]).has(field)) {
618
+ diagnostics.push(unknownDiagnostic(`${path}.${field}`));
619
+ }
620
+ }
621
+ let valid = true;
622
+ if (typeof entry.threshold !== "number" || !Number.isFinite(entry.threshold)) {
623
+ diagnostics.push(diagnostic("warning", `${path}.threshold`, "Expected a finite number"));
624
+ valid = false;
625
+ }
626
+ if (typeof entry.style !== "string" || !isValidStyle(entry.style, palette)) {
627
+ diagnostics.push(
628
+ diagnostic("warning", `${path}.style`, "Expected a valid Starship style string"),
629
+ );
630
+ valid = false;
631
+ }
632
+ if (typeof entry.hidden !== "boolean") {
633
+ diagnostics.push(typeDiagnostic(`${path}.hidden`, "boolean"));
634
+ valid = false;
635
+ }
636
+ if (valid) {
637
+ result.push({
638
+ threshold: entry.threshold as number,
639
+ style: entry.style as string,
640
+ hidden: entry.hidden as boolean,
641
+ });
642
+ }
643
+ }
644
+ if (result.length > 0) return result;
645
+ diagnostics.push(
646
+ diagnostic("warning", `${name}.display`, "Expected at least one valid entry; using defaults"),
647
+ );
648
+ return defaults.map((entry) => ({ ...entry }));
649
+ }
650
+
651
+ function validateLiteralStyles(
652
+ ast: readonly FormatNode[],
653
+ palette: ColorPalette,
654
+ path: string,
655
+ diagnostics: ConfigDiagnostic[],
656
+ ) {
657
+ for (const node of ast) {
658
+ if (node.type === "group" && node.style.every((part) => part.type === "text")) {
659
+ const style = node.style.map((part) => (part.type === "text" ? part.value : "")).join("");
660
+ if (!isValidStyle(style, palette)) {
661
+ diagnostics.push(
662
+ diagnostic(
663
+ "warning",
664
+ path,
665
+ `Invalid literal style ${JSON.stringify(style)}; rendered unstyled`,
666
+ ),
667
+ );
668
+ }
669
+ }
670
+ if (node.type === "group" || node.type === "conditional") {
671
+ validateLiteralStyles(node.children, palette, path, diagnostics);
672
+ }
673
+ }
674
+ }
675
+
564
676
  function normalizeModuleOption(
565
677
  value: unknown,
566
678
  schema: ModuleOptionSchema,
@@ -667,15 +779,12 @@ function formatError(error: unknown): string {
667
779
  }
668
780
 
669
781
  export function activePalette(config: StarshipConfig): ColorPalette {
670
- return {
671
- ...ownPalette(config.palettes, BUILT_IN_CONFIG.palette),
672
- ...ownPalette(config.palettes, config.palette),
673
- };
782
+ return ownPalette(config.palettes, config.palette) ?? {};
674
783
  }
675
784
 
676
785
  function ownPalette(
677
786
  palettes: Readonly<Record<string, Record<string, string>>>,
678
- name: string,
787
+ name: string | undefined,
679
788
  ): Record<string, string> | undefined {
680
- return Object.hasOwn(palettes, name) ? palettes[name] : undefined;
789
+ return name !== undefined && Object.hasOwn(palettes, name) ? palettes[name] : undefined;
681
790
  }
@@ -19,12 +19,15 @@ export type NamedColor =
19
19
  export type ColorSpec =
20
20
  | { kind: "named"; name: NamedColor }
21
21
  | { kind: "fixed"; value: number }
22
- | { kind: "rgb"; red: number; green: number; blue: number }
23
- | { kind: "previous"; source: "foreground" | "background" };
22
+ | { kind: "rgb"; red: number; green: number; blue: number };
23
+
24
+ export type PreviousColorSource = "foreground" | "background";
24
25
 
25
26
  export interface TextStyle {
26
27
  foreground?: ColorSpec;
27
28
  background?: ColorSpec;
29
+ foregroundPrevious?: PreviousColorSource;
30
+ backgroundPrevious?: PreviousColorSource;
28
31
  bold?: boolean;
29
32
  italic?: boolean;
30
33
  underline?: boolean;
@@ -35,6 +38,10 @@ export interface TextStyle {
35
38
  strikethrough?: boolean;
36
39
  }
37
40
 
41
+ export type StyleParseResult =
42
+ | { valid: true; style: TextStyle | undefined }
43
+ | { valid: false; style: undefined };
44
+
38
45
  export interface StyledChunk {
39
46
  text: string;
40
47
  style?: TextStyle;
@@ -92,41 +99,53 @@ const FOREGROUND_CODES: Record<NamedColor, number> = {
92
99
  };
93
100
 
94
101
  export function isValidStyle(styleString: string, palette: ColorPalette = {}): boolean {
95
- for (const rawToken of styleString.split(/\s+/u).filter(Boolean)) {
96
- const token = rawToken.toLowerCase();
97
- if (token === "none" || token === "fg:none" || token === "bg:none") continue;
98
- const probe: TextStyle = {};
99
- if (applyModifier(probe, token)) continue;
100
- const colorToken = token.startsWith("fg:") || token.startsWith("bg:") ? token.slice(3) : token;
101
- if (!parseColor(colorToken, palette)) return false;
102
- }
103
- return true;
102
+ return parseStyleResult(styleString, palette).valid;
104
103
  }
105
104
 
106
- export function parseStyle(styleString: string, palette: ColorPalette = {}): TextStyle | undefined {
105
+ export function parseStyleResult(
106
+ styleString: string,
107
+ palette: ColorPalette = {},
108
+ ): StyleParseResult {
109
+ const tokens = styleString.split(/\s+/u).filter(Boolean).map(normalizeStyleToken);
110
+ if (tokens.some(({ token, foreground }) => foreground && token === "none")) {
111
+ return { valid: true, style: undefined };
112
+ }
113
+
107
114
  const style: TextStyle = {};
108
- for (const rawToken of styleString.split(/\s+/u).filter(Boolean)) {
109
- const token = rawToken.toLowerCase();
110
- if (token === "none") return undefined;
111
- if (token === "fg:none") {
112
- delete style.foreground;
115
+ for (const { token, foreground } of tokens) {
116
+ if (applyModifier(style, token)) continue;
117
+ if (token === "prev_fg" || token === "prev_bg") {
118
+ const source = token === "prev_fg" ? "foreground" : "background";
119
+ if (foreground) style.foregroundPrevious = source;
120
+ else style.backgroundPrevious = source;
113
121
  continue;
114
122
  }
115
- if (applyModifier(style, token)) continue;
116
-
117
- const foreground = token.startsWith("fg:");
118
- const background = token.startsWith("bg:");
119
- const colorToken = foreground || background ? token.slice(3) : token;
120
- if (background && colorToken === "none") {
123
+ const color = parseColor(token, palette);
124
+ if (!foreground && !color) {
121
125
  delete style.background;
122
126
  continue;
123
127
  }
124
- const color = parseColor(colorToken, palette);
125
- if (!color) return undefined;
126
- if (background) style.background = color;
127
- else style.foreground = color;
128
+ if (!color) return { valid: false, style: undefined };
129
+ if (foreground) style.foreground = color;
130
+ else style.background = color;
128
131
  }
129
- return Object.keys(style).length > 0 ? style : undefined;
132
+ return { valid: true, style };
133
+ }
134
+
135
+ export function parseStyle(styleString: string, palette: ColorPalette = {}): TextStyle | undefined {
136
+ return parseStyleResult(styleString, palette).style;
137
+ }
138
+
139
+ function normalizeStyleToken(rawToken: string): { token: string; foreground: boolean } {
140
+ let token = rawToken.toLowerCase();
141
+ if (token.startsWith("fg:")) {
142
+ return { token: token.replace(/^(?:fg:)+/u, ""), foreground: true };
143
+ }
144
+ if (token.startsWith("bg:")) {
145
+ token = token.replace(/^(?:bg:)+/u, "");
146
+ return { token, foreground: false };
147
+ }
148
+ return { token, foreground: true };
130
149
  }
131
150
 
132
151
  function applyModifier(style: TextStyle, token: string): boolean {
@@ -161,8 +180,6 @@ function applyModifier(style: TextStyle, token: string): boolean {
161
180
  }
162
181
 
163
182
  export function parseColor(token: string, palette: ColorPalette = {}): ColorSpec | undefined {
164
- if (token === "prev_fg") return { kind: "previous", source: "foreground" };
165
- if (token === "prev_bg") return { kind: "previous", source: "background" };
166
183
  const paletteValue = Object.hasOwn(palette, token) ? palette[token] : undefined;
167
184
  if (paletteValue !== undefined) return parseColor(paletteValue.toLowerCase(), {});
168
185
  if (NAMED_COLORS.has(token as NamedColor)) {
@@ -182,9 +199,13 @@ export function parseColor(token: string, palette: ColorPalette = {}): ColorSpec
182
199
  };
183
200
  }
184
201
 
185
- interface ResolvedStyle extends Omit<TextStyle, "foreground" | "background"> {
186
- foreground?: Exclude<ColorSpec, { kind: "previous" }>;
187
- background?: Exclude<ColorSpec, { kind: "previous" }>;
202
+ interface ResolvedStyle
203
+ extends Omit<
204
+ TextStyle,
205
+ "foreground" | "background" | "foregroundPrevious" | "backgroundPrevious"
206
+ > {
207
+ foreground?: ColorSpec;
208
+ background?: ColorSpec;
188
209
  }
189
210
 
190
211
  export function renderChunksToAnsi(chunks: readonly LayoutChunk[]): string {
@@ -215,20 +236,21 @@ function resolveStyle(
215
236
  previous: ResolvedStyle | undefined,
216
237
  ): ResolvedStyle {
217
238
  if (!style) return {};
239
+ const { foregroundPrevious, backgroundPrevious, ...resolved } = style;
218
240
  return {
219
- ...style,
220
- foreground: resolveColor(style.foreground, previous),
221
- background: resolveColor(style.background, previous),
241
+ ...resolved,
242
+ foreground: resolveColor(style.foreground, foregroundPrevious, previous),
243
+ background: resolveColor(style.background, backgroundPrevious, previous),
222
244
  };
223
245
  }
224
246
 
225
247
  function resolveColor(
226
- color: ColorSpec | undefined,
248
+ fallback: ColorSpec | undefined,
249
+ source: PreviousColorSource | undefined,
227
250
  previous: ResolvedStyle | undefined,
228
- ): ResolvedStyle["foreground"] {
229
- if (!color) return undefined;
230
- if (color.kind !== "previous") return color;
231
- return color.source === "foreground" ? previous?.foreground : previous?.background;
251
+ ): ColorSpec | undefined {
252
+ if (!source || !previous) return fallback;
253
+ return source === "foreground" ? previous.foreground : previous.background;
232
254
  }
233
255
 
234
256
  function ansiCodes(style: ResolvedStyle): string[] {
@@ -246,10 +268,7 @@ function ansiCodes(style: ResolvedStyle): string[] {
246
268
  return codes;
247
269
  }
248
270
 
249
- function colorCodes(
250
- color: Exclude<ColorSpec, { kind: "previous" }>,
251
- background: boolean,
252
- ): string[] {
271
+ function colorCodes(color: ColorSpec, background: boolean): string[] {
253
272
  if (color.kind === "named") {
254
273
  const foreground = FOREGROUND_CODES[color.name];
255
274
  return [`${background ? foreground + 10 : foreground}`];
@@ -6,7 +6,7 @@ export const activityModule = defineModule({
6
6
  defaults: {
7
7
  format: "[ $text ]($style)",
8
8
  symbol: "⚙",
9
- style: "fg:runtime_fg bg:runtime",
9
+ style: "bold yellow",
10
10
  disabled: false,
11
11
  },
12
12
  values: ({ runtime, symbol }) => {
@@ -6,7 +6,7 @@ export const brandModule = defineModule({
6
6
  defaults: {
7
7
  format: "[ $symbol ]($style)",
8
8
  symbol: "π",
9
- style: "bold fg:header_fg bg:header",
9
+ style: "bold white",
10
10
  disabled: false,
11
11
  },
12
12
  values: () => ({}),
@@ -7,7 +7,7 @@ export const cacheModule = defineModule({
7
7
  defaults: {
8
8
  format: "[$symbol (CH$rate )]($style)",
9
9
  symbol: "📦",
10
- style: "fg:runtime_fg bg:runtime",
10
+ style: "bold green",
11
11
  disabled: true,
12
12
  },
13
13
  values: ({ runtime }) => {
@@ -27,7 +27,7 @@ import { tokensModule } from "./tokens.js";
27
27
  import { turnModule } from "./turn.js";
28
28
  import type { ModuleDefinition } from "./types.js";
29
29
 
30
- export const MODULE_DEFINITIONS = [
30
+ const MODULE_IMPLEMENTATIONS = [
31
31
  brandModule,
32
32
  providerModule,
33
33
  modelModule,
@@ -58,8 +58,67 @@ export const MODULE_DEFINITIONS = [
58
58
  extensionStatusModule,
59
59
  ] as const satisfies readonly ModuleDefinition<string>[];
60
60
 
61
- export type ModuleName = (typeof MODULE_DEFINITIONS)[number]["name"];
61
+ export type ModuleName = (typeof MODULE_IMPLEMENTATIONS)[number]["name"];
62
62
 
63
- export const MODULE_NAMES: readonly ModuleName[] = MODULE_DEFINITIONS.map(
63
+ const MODULE_DESCRIPTIONS = {
64
+ activity: "Current Pi activity or most recently completed tool.",
65
+ aws: "Active AWS profile and region.",
66
+ azure: "Active Azure subscription and optional username.",
67
+ brand: "pi-starship brand mark.",
68
+ bun: "Bun version detected in the current workspace.",
69
+ cache: "Prompt-cache usage and latest cache hit rate.",
70
+ conda: "Active Conda environment.",
71
+ container: "Current container or remote development environment.",
72
+ context: "Current model context-window usage.",
73
+ cost: "Reported estimated session cost or subscription state.",
74
+ deno: "Deno version detected in the current workspace.",
75
+ directory: "Current working directory.",
76
+ direnv: "Current direnv loading and permission state.",
77
+ docker_context: "Active Docker context.",
78
+ extension_status: "Statuses published through Pi's extension-neutral status map.",
79
+ fill: "Flexible spacing that aligns content within the footer width.",
80
+ gcloud: "Active Google Cloud project, account, and region.",
81
+ git_branch: "Current Git branch and upstream identity.",
82
+ git_commit: "Current Git commit hash or tag.",
83
+ git_metrics: "Added and deleted lines in the current Git worktree.",
84
+ git_state: "Current Git operation such as merge, rebase, or cherry-pick.",
85
+ git_status: "Current Git worktree and index status summary.",
86
+ git_worktree: "Current linked Git worktree identity.",
87
+ github_pr: "Current branch's GitHub pull request state, checks, and review.",
88
+ golang: "Go version detected in the current workspace.",
89
+ guix_shell: "Current Guix shell state.",
90
+ hostname: "Current host name, normally shown for remote sessions.",
91
+ kubernetes: "Active Kubernetes context, namespace, cluster, and user.",
92
+ mise: "Current mise configuration health.",
93
+ model: "Current Pi model.",
94
+ nix_shell: "Current Nix shell state, name, and nesting level.",
95
+ nodejs: "Node.js version detected in the current workspace.",
96
+ openstack: "Active OpenStack cloud and project.",
97
+ os: "Current operating system identity.",
98
+ package: "Current workspace package name and version.",
99
+ pixi: "Active Pixi environment and project.",
100
+ provider: "Current Pi model provider.",
101
+ python: "Python version, virtual environment, and pyenv state.",
102
+ rust: "Rust toolchain detected in the current workspace.",
103
+ terraform: "Active Terraform workspace and version.",
104
+ thinking: "Current Pi thinking level or streaming state.",
105
+ time: "Current local time.",
106
+ tokens: "Session input and output token totals.",
107
+ turn: "Current user-turn count.",
108
+ username: "Current user identity when configured to display.",
109
+ } as const satisfies Record<ModuleName, string>;
110
+
111
+ export type CatalogModuleDefinition<Name extends string = ModuleName> = ModuleDefinition<Name> & {
112
+ readonly description: string;
113
+ };
114
+
115
+ export const MODULE_DEFINITIONS: readonly CatalogModuleDefinition[] = MODULE_IMPLEMENTATIONS.map(
116
+ (definition) => ({
117
+ ...definition,
118
+ description: MODULE_DESCRIPTIONS[definition.name],
119
+ }),
120
+ );
121
+
122
+ export const MODULE_NAMES: readonly ModuleName[] = MODULE_IMPLEMENTATIONS.map(
64
123
  (definition) => definition.name,
65
124
  );
@@ -1,3 +1,4 @@
1
+ import { resolveDisplayStyle } from "./display.js";
1
2
  import { formatCount } from "./helpers.js";
2
3
  import { defineModule } from "./types.js";
3
4
 
@@ -7,9 +8,20 @@ export const contextModule = defineModule({
7
8
  defaults: {
8
9
  format: "[$symbol ctx $percentage ]($style)",
9
10
  symbol: "🪟",
10
- style: "fg:runtime_fg bg:runtime",
11
+ style: "none",
11
12
  disabled: false,
12
13
  },
14
+ displayDefaults: [
15
+ { threshold: 0, style: "bold green", hidden: true },
16
+ { threshold: 30, style: "bold green", hidden: false },
17
+ { threshold: 60, style: "bold yellow", hidden: false },
18
+ { threshold: 80, style: "bold red", hidden: false },
19
+ ],
20
+ styleVariables: ["style"],
21
+ resolveStyleVariables: ({ runtime, display }) => {
22
+ const style = resolveDisplayStyle(display, runtime.contextUsage?.percent);
23
+ return style === undefined ? undefined : { style };
24
+ },
13
25
  values: ({ runtime }) => {
14
26
  const percent = runtime.contextUsage?.percent;
15
27
  return {