@narumitw/pi-starship 0.45.0 → 0.49.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 CHANGED
@@ -339,22 +339,74 @@ There is no hidden compatibility overlay or automatic migration.
339
339
  - Pi's public extension API does not expose the current auto-compaction toggle, so pi-starship cannot
340
340
  reliably provide the native `(auto)` marker.
341
341
 
342
- ### Model truncation
342
+ ### Directory, Git, and environment contraction
343
343
 
344
- The model module accepts Starship-style `truncation_length` and `truncation_symbol` options plus the
345
- Pi-specific `truncation_direction` option:
344
+ The analogous modules keep their display policy local and use Starship defaults:
345
+
346
+ ```toml
347
+ [directory]
348
+ truncation_length = 3
349
+ truncate_to_repo = true
350
+ fish_style_pwd_dir_length = 0
351
+ truncation_symbol = ""
352
+ home_symbol = "~"
353
+ use_os_path_sep = true
354
+ substitutions = { "/Volumes/network/path" = "/net" }
355
+
356
+ [git_branch]
357
+ truncation_length = 0 # pi-starship's bounded no-truncation sentinel
358
+ truncation_symbol = "…"
359
+
360
+ [git_commit]
361
+ commit_hash_length = 7
362
+
363
+ [conda]
364
+ ignore_base = true
365
+ truncation_length = 1
366
+
367
+ [hostname]
368
+ trim_at = "." # set to "" to keep the complete hostname
369
+ ```
370
+
371
+ Directory `$path` contracts the home directory and, by default, the current Git repository root
372
+ before retaining the last three path components. `$full_path` remains the unmodified absolute cwd.
373
+ A positive `fish_style_pwd_dir_length` abbreviates otherwise omitted parent components when no
374
+ substitution is configured. `substitutions` is an ordered TOML string table of literal replacements.
375
+ Pi exposes one cwd rather than separate logical and physical paths, and pi-starship does not implement
376
+ Starship's regex substitution array or repo-root-specific split style/format fields. Directory
377
+ rendering reads only immutable home and repository-root snapshot data and performs no filesystem or
378
+ Git work.
379
+
380
+ Git branch truncation retains the first `N` grapheme clusters and appends the first grapheme of
381
+ `truncation_symbol` only when truncation occurs. The same rule applies independently to `$branch`,
382
+ `$remote_name`, and `$remote_branch`. Upstream Starship represents its unlimited default as
383
+ `2^63 - 1`; pi-starship uses `0` for the same behavior because its settings integers are deliberately
384
+ bounded. `commit_hash_length` accepts 0 through 64.
385
+
386
+ Conda retains the last path component by default; `0` keeps the complete environment path. Hostname
387
+ trimming runs before exact alias lookup, matching Starship. These are display transformations only:
388
+ collectors retain bounded, control-sanitized source metadata.
389
+
390
+ ### Model aliases and truncation
391
+
392
+ The model module accepts exact `model_aliases`, Starship-style `truncation_length` and
393
+ `truncation_symbol` options, plus the Pi-specific `truncation_direction` option:
346
394
 
347
395
  ```toml
348
396
  [model]
397
+ model_aliases = { "/models/Qwen3.6-35B-Q4.gguf" = "Qwen 35B Q4" }
349
398
  truncation_length = 36
350
399
  truncation_symbol = "…"
351
400
  truncation_direction = "middle"
352
401
  ```
353
402
 
354
- `truncation_length` counts model grapheme clusters retained before the symbol; `0` disables
403
+ An exact alias is selected before the built-in Claude/GPT shortening rules, then the resulting label
404
+ is subject to the configured truncation. `truncation_length` counts model grapheme clusters retained
405
+ before the symbol; `0` disables
355
406
  truncation and is the default. The direction names the removed portion: `start` retains the suffix,
356
- `end` retains the prefix and is the default, and `middle` retains both ends. Truncation runs after the
357
- built-in Claude/GPT shortening rules and changes display only—the provider model ID is untouched.
407
+ `end` retains the prefix and is the default, and `middle` retains both ends. When no alias matches,
408
+ truncation runs after the built-in Claude/GPT shortening rules. It always changes display only—the
409
+ provider model ID is untouched.
358
410
  Terminal control sequences in model IDs and truncation symbols are removed at render time. An empty
359
411
  symbol truncates without a marker. For example, `middle` can retain both a Hugging Face model
360
412
  family and its variant, while `start` is useful when a llama.cpp server reports an absolute model path.
@@ -581,7 +633,8 @@ Keep `extension_status` last in the catalog so arbitrary third-party statuses fo
581
633
  - `src/index.ts` — Pi package entrypoint.
582
634
  - `src/pi-starship.ts` — extension lifecycle, cached refresh binding, live preview, and footer.
583
635
  - `src/usage.ts` — native-aligned session usage and cache aggregation.
584
- - `src/commands.ts` — goal-oriented menu, preview/confirmation flow, diagnostics, and compatibility routes.
636
+ - `src/command-contract.ts` — lightweight command routes and completions loaded at startup.
637
+ - `src/commands.ts` — lazily loaded menu, preview/confirmation flow, diagnostics, and compatibility routes.
585
638
  - `src/command-inspector.ts` — adaptive Explain and searchable read-only module inspection surfaces.
586
639
  - `src/command-preview.ts` — adaptive, scrollable, keybinding-aware preview action surface.
587
640
  - `src/config.ts` — TOML loading, draft validation, defaults, atomic persistence, and rollback.
@@ -590,7 +643,7 @@ Keep `extension_status` last in the catalog so arbitrary third-party statuses fo
590
643
  - `src/modules/git/` — bounded local Git reader plus branch, status, and worktree modules.
591
644
  - `src/modules/github-pr.ts` — pure native GitHub PR snapshot presentation.
592
645
  - `src/runtime/github-pr.ts` — bounded `gh` query, validation, terminal-safe links, and expiry data.
593
- - `src/runtime/` — shared refresh controller and bounded package/language/context collectors.
646
+ - `src/runtime/` — shared refresh controller and requirement-gated, lazily loaded package/language/context collectors.
594
647
 
595
648
  ## 🔎 Keywords
596
649
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-starship",
3
- "version": "0.45.0",
3
+ "version": "0.49.0",
4
4
  "description": "Native Starship-style TOML statusline for the Pi coding agent.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -31,7 +31,7 @@
31
31
  "typecheck": "tsc --noEmit"
32
32
  },
33
33
  "dependencies": {
34
- "@narumitw/pi-tui-kit": "^0.43.0",
34
+ "@narumitw/pi-tui-kit": "^0.46.0",
35
35
  "smol-toml": "^1.7.1",
36
36
  "yaml": "^2.9.0"
37
37
  },
@@ -0,0 +1,13 @@
1
+ import type { AutocompleteItem } from "@earendil-works/pi-tui";
2
+
3
+ export const STARSHIP_SUBCOMMANDS: readonly AutocompleteItem[] = [
4
+ { value: "settings", label: "settings", description: "Customize the footer TOML" },
5
+ { value: "status", label: "status", description: "Show configuration health and source" },
6
+ { value: "help", label: "help", description: "Show configuration help" },
7
+ ];
8
+
9
+ export function completeStarshipArguments(prefix: string): AutocompleteItem[] | null {
10
+ const normalized = prefix.trim().toLowerCase();
11
+ const matches = STARSHIP_SUBCOMMANDS.filter((item) => item.value.startsWith(normalized));
12
+ return matches.length > 0 ? [...matches] : null;
13
+ }
@@ -1,22 +1,12 @@
1
1
  import { stripVTControlCharacters } from "node:util";
2
2
  import type { ExtensionCommandContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
3
- import {
4
- type Component,
5
- type Focusable,
6
- Input,
7
- Key,
8
- matchesKey,
9
- truncateToWidth,
10
- wrapTextWithAnsi,
11
- } from "@earendil-works/pi-tui";
12
- import type { ModuleInspection, StatuslineInspection } from "./modules/inspection.js";
3
+ import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
4
+ import type { StatuslineInspection } from "./modules/inspection.js";
13
5
 
14
6
  const RESERVED_HOST_ROWS = 3;
15
7
 
16
8
  export type InspectorResult = { kind: "back" } | { kind: "close" };
17
9
 
18
- type DisposableComponent = Component & Focusable & { dispose(): void };
19
-
20
10
  export function showFooterExplanation(
21
11
  ctx: ExtensionCommandContext,
22
12
  inspection: StatuslineInspection | undefined,
@@ -87,181 +77,6 @@ export function showFooterExplanation(
87
77
  });
88
78
  }
89
79
 
90
- export function showModuleBrowser(
91
- ctx: ExtensionCommandContext,
92
- inspection: StatuslineInspection,
93
- signal?: AbortSignal,
94
- ): Promise<InspectorResult | undefined> {
95
- if (signal?.aborted) return Promise.resolve({ kind: "close" });
96
- return ctx.ui.custom<InspectorResult | undefined>((tui, theme, keybindings, done) => {
97
- const input = new Input();
98
- let filtered = [...inspection.modules];
99
- let selectedIndex = 0;
100
- let listOffset = 0;
101
- let detailScrollOffset = 0;
102
- let lastListRows = 1;
103
- let searchInputVisible = true;
104
- let lastDetailRows = 1;
105
- let lastDetailMaximumScroll = 0;
106
- let view: "list" | "detail" = "list";
107
- let focused = false;
108
- let disposed = false;
109
- let settled = false;
110
- let deferredAbort: ReturnType<typeof setImmediate> | undefined;
111
- const finish = (result: InspectorResult) => {
112
- if (disposed || settled) return;
113
- settled = true;
114
- done(result);
115
- };
116
- const closeForAbort = () => finish({ kind: "close" });
117
- signal?.addEventListener("abort", closeForAbort, { once: true });
118
- if (signal?.aborted) deferredAbort = setImmediate(closeForAbort);
119
- const selected = () => filtered[selectedIndex];
120
- const syncFocus = () => {
121
- input.focused = focused && view === "list";
122
- };
123
- const select = (index: number) => {
124
- if (filtered.length === 0) return;
125
- selectedIndex = (index + filtered.length) % filtered.length;
126
- };
127
- const applySearch = () => {
128
- const sanitized = safeSearchText(input.getValue());
129
- if (sanitized !== input.getValue()) input.setValue(sanitized);
130
- filtered = filterModules(inspection.modules, sanitized);
131
- selectedIndex = 0;
132
- listOffset = 0;
133
- };
134
-
135
- const component: DisposableComponent = {
136
- get focused() {
137
- return focused;
138
- },
139
- set focused(value: boolean) {
140
- focused = value;
141
- syncFocus();
142
- },
143
- render(width: number): string[] {
144
- const safeWidth = Math.max(1, width);
145
- const availableRows = componentRows(tui.terminal.rows);
146
- if (view === "detail") {
147
- const module = selected();
148
- const content = moduleDetailLines(module, safeWidth);
149
- const layout = detailLayout(availableRows, content.length);
150
- lastDetailRows = layout.contentRows;
151
- lastDetailMaximumScroll = Math.max(0, content.length - layout.contentRows);
152
- detailScrollOffset = clamp(detailScrollOffset, 0, lastDetailMaximumScroll);
153
- const lines = [
154
- ...(layout.titleRows ? [theme.fg("accent", theme.bold(module?.name ?? "Module"))] : []),
155
- ...content.slice(detailScrollOffset, detailScrollOffset + layout.contentRows),
156
- ...(layout.positionRows
157
- ? [
158
- theme.fg(
159
- "dim",
160
- positionText(detailScrollOffset, layout.contentRows, content.length),
161
- ),
162
- ]
163
- : []),
164
- ...(layout.hintRows ? [theme.fg("dim", detailHint(keybindings, "back"))] : []),
165
- ];
166
- return boundedLines(lines, safeWidth, availableRows);
167
- }
168
-
169
- const layout = listLayout(availableRows, filtered.length);
170
- lastListRows = layout.itemRows;
171
- searchInputVisible = layout.inputRows > 0;
172
- listOffset = listWindowStart(selectedIndex, filtered.length, layout.itemRows);
173
- const rows =
174
- filtered.length === 0
175
- ? [theme.fg("dim", " No matching modules")]
176
- : filtered.slice(listOffset, listOffset + layout.itemRows).map((module, index) => {
177
- const absoluteIndex = listOffset + index;
178
- const prefix = absoluteIndex === selectedIndex ? "→ " : " ";
179
- const text = `${prefix}${module.name} [${module.state}]`;
180
- return theme.fg(absoluteIndex === selectedIndex ? "accent" : "text", text);
181
- });
182
- const description = selected()?.description;
183
- const lines = [
184
- ...(layout.titleRows ? [theme.fg("accent", theme.bold("Modules · type to search"))] : []),
185
- ...(layout.inputRows ? input.render(safeWidth) : []),
186
- ...rows,
187
- ...(layout.positionRows
188
- ? [theme.fg("dim", positionText(listOffset, layout.itemRows, filtered.length))]
189
- : []),
190
- ...(layout.descriptionRows && description
191
- ? [theme.fg("muted", safeDisplayText(description))]
192
- : []),
193
- ...(layout.hintRows ? [theme.fg("dim", browserHint(keybindings))] : []),
194
- ];
195
- return boundedLines(lines, safeWidth, availableRows);
196
- },
197
- invalidate() {
198
- input.invalidate();
199
- },
200
- handleInput(data: string) {
201
- if (disposed || settled) return;
202
- if (matchesKey(data, Key.ctrl("c"))) {
203
- finish({ kind: "close" });
204
- } else if (keybindings.matches(data, "tui.select.cancel")) {
205
- if (view === "detail") {
206
- view = "list";
207
- detailScrollOffset = 0;
208
- syncFocus();
209
- } else finish({ kind: "back" });
210
- } else if (view === "detail") {
211
- if (keybindings.matches(data, "tui.select.up")) {
212
- detailScrollOffset = clamp(detailScrollOffset - 1, 0, lastDetailMaximumScroll);
213
- } else if (keybindings.matches(data, "tui.select.down")) {
214
- detailScrollOffset = clamp(detailScrollOffset + 1, 0, lastDetailMaximumScroll);
215
- } else if (keybindings.matches(data, "tui.select.pageUp")) {
216
- detailScrollOffset = clamp(
217
- detailScrollOffset - lastDetailRows,
218
- 0,
219
- lastDetailMaximumScroll,
220
- );
221
- } else if (keybindings.matches(data, "tui.select.pageDown")) {
222
- detailScrollOffset = clamp(
223
- detailScrollOffset + lastDetailRows,
224
- 0,
225
- lastDetailMaximumScroll,
226
- );
227
- } else if (matchesKey(data, Key.home)) detailScrollOffset = 0;
228
- else if (matchesKey(data, Key.end)) {
229
- detailScrollOffset = lastDetailMaximumScroll;
230
- }
231
- } else if (keybindings.matches(data, "tui.select.up")) {
232
- select(selectedIndex - 1);
233
- } else if (keybindings.matches(data, "tui.select.down")) {
234
- select(selectedIndex + 1);
235
- } else if (keybindings.matches(data, "tui.select.pageUp")) {
236
- select(selectedIndex - lastListRows);
237
- } else if (keybindings.matches(data, "tui.select.pageDown")) {
238
- select(selectedIndex + lastListRows);
239
- } else if (matchesKey(data, Key.home)) selectedIndex = 0;
240
- else if (matchesKey(data, Key.end)) selectedIndex = Math.max(0, filtered.length - 1);
241
- else if (keybindings.matches(data, "tui.select.confirm")) {
242
- if (selected()) {
243
- view = "detail";
244
- detailScrollOffset = 0;
245
- syncFocus();
246
- }
247
- } else if (searchInputVisible) {
248
- input.handleInput(data);
249
- applySearch();
250
- }
251
- tui.requestRender();
252
- },
253
- dispose() {
254
- if (disposed) return;
255
- disposed = true;
256
- if (deferredAbort) clearImmediate(deferredAbort);
257
- deferredAbort = undefined;
258
- signal?.removeEventListener("abort", closeForAbort);
259
- },
260
- };
261
- return component;
262
- });
263
- }
264
-
265
80
  function explanationLines(inspection: StatuslineInspection | undefined, width: number): string[] {
266
81
  if (!inspection) {
267
82
  return wrapLines(
@@ -290,34 +105,11 @@ function explanationLines(inspection: StatuslineInspection | undefined, width: n
290
105
  return wrapLines(lines, width);
291
106
  }
292
107
 
293
- function moduleDetailLines(module: ModuleInspection | undefined, width: number): string[] {
294
- if (!module) return ["No matching module."];
295
- return wrapLines(
296
- [
297
- `State: ${module.state}`,
298
- module.description,
299
- `Root: ${module.rootReferenced ? "Referenced" : "Not referenced"}`,
300
- `Reachable: ${module.reachable ? "Yes" : "No"}`,
301
- ...detailPreviewLines(module.preview),
302
- `Reason: ${module.reason}`,
303
- `Variables: ${module.variables.join(", ") || "none"}`,
304
- `Style fields: ${module.styleFields.join(", ") || "none"}`,
305
- `Display rules: ${module.displayRules.join(" · ") || "none"}`,
306
- ],
307
- width,
308
- );
309
- }
310
-
311
108
  function previewLines(preview: string): string[] {
312
109
  const lines = preview ? preview.split("\n") : ["(no text)"];
313
110
  return lines.map((line, index) => `${index === 0 ? "Value: " : " "}${line}`);
314
111
  }
315
112
 
316
- function detailPreviewLines(preview: string): string[] {
317
- const lines = preview ? preview.split("\n") : ["(no current preview)"];
318
- return lines.map((line, index) => `${index === 0 ? "Preview: " : " "}${line}`);
319
- }
320
-
321
113
  function wrapLines(lines: readonly string[], width: number): string[] {
322
114
  return lines.flatMap((line) => {
323
115
  const safe = safeDisplayText(line);
@@ -325,15 +117,6 @@ function wrapLines(lines: readonly string[], width: number): string[] {
325
117
  });
326
118
  }
327
119
 
328
- function filterModules(modules: readonly ModuleInspection[], query: string): ModuleInspection[] {
329
- const terms = query.toLowerCase().trim().split(/\s+/u).filter(Boolean);
330
- if (terms.length === 0) return [...modules];
331
- return modules.filter((module) => {
332
- const candidate = `${module.name} ${module.description} ${module.state}`.toLowerCase();
333
- return terms.every((term) => candidate.includes(term));
334
- });
335
- }
336
-
337
120
  interface DetailLayout {
338
121
  titleRows: number;
339
122
  contentRows: number;
@@ -353,46 +136,11 @@ function detailLayout(availableRows: number, contentLength: number): DetailLayou
353
136
  return { titleRows, contentRows, positionRows, hintRows };
354
137
  }
355
138
 
356
- interface ListLayout {
357
- titleRows: number;
358
- inputRows: number;
359
- itemRows: number;
360
- positionRows: number;
361
- descriptionRows: number;
362
- hintRows: number;
363
- }
364
-
365
- function listLayout(availableRows: number, itemCount: number): ListLayout {
366
- if (availableRows === 1) {
367
- return {
368
- titleRows: 0,
369
- inputRows: 0,
370
- itemRows: 1,
371
- positionRows: 0,
372
- descriptionRows: 0,
373
- hintRows: 0,
374
- };
375
- }
376
- const titleRows = availableRows >= 4 ? 1 : 0;
377
- const inputRows = availableRows >= 3 ? 1 : 0;
378
- const hintRows = availableRows >= 3 ? 1 : 0;
379
- const descriptionRows = availableRows >= 7 ? 1 : 0;
380
- let itemRows = Math.max(1, availableRows - titleRows - inputRows - hintRows - descriptionRows);
381
- const positionRows = itemCount > itemRows && itemRows >= 2 ? 1 : 0;
382
- itemRows -= positionRows;
383
- return { titleRows, inputRows, itemRows, positionRows, descriptionRows, hintRows };
384
- }
385
-
386
139
  function componentRows(rows: number): number {
387
140
  const terminalRows = Number.isFinite(rows) ? Math.floor(rows) : 24;
388
141
  return Math.max(1, terminalRows - RESERVED_HOST_ROWS);
389
142
  }
390
143
 
391
- function listWindowStart(selectedIndex: number, itemCount: number, viewportSize: number): number {
392
- if (itemCount <= viewportSize) return 0;
393
- return Math.max(0, Math.min(selectedIndex, itemCount - viewportSize));
394
- }
395
-
396
144
  function positionText(offset: number, viewportSize: number, itemCount: number): string {
397
145
  if (itemCount === 0) return "0/0";
398
146
  return `${offset + 1}-${Math.min(itemCount, offset + viewportSize)}/${itemCount}`;
@@ -402,19 +150,6 @@ function boundedLines(lines: readonly string[], width: number, rows: number): st
402
150
  return lines.slice(0, rows).map((line) => truncateToWidth(line, width, ""));
403
151
  }
404
152
 
405
- function browserHint(keybindings: Pick<KeybindingsManager, "getKeys">): string {
406
- const up = bindingText(keybindings, "tui.select.up");
407
- const down = bindingText(keybindings, "tui.select.down");
408
- const confirm = bindingText(keybindings, "tui.select.confirm");
409
- const cancel = bindingText(keybindings, "tui.select.cancel", "ctrl+c");
410
- return [
411
- ...(up || down ? [`${[up, down].filter(Boolean).join("/")} navigate`] : []),
412
- ...(confirm ? [`${confirm} details`] : []),
413
- ...(cancel ? [`${cancel} back`] : []),
414
- "ctrl+c close",
415
- ].join(" • ");
416
- }
417
-
418
153
  function detailHint(
419
154
  keybindings: Pick<KeybindingsManager, "getKeys">,
420
155
  destination: "back" | "close",
@@ -451,13 +186,6 @@ function bindingText(
451
186
  .join("/");
452
187
  }
453
188
 
454
- function safeSearchText(value: string): string {
455
- return Array.from(stripVTControlCharacters(value), (character) => {
456
- const codePoint = character.codePointAt(0) ?? 0;
457
- return codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f) ? "" : character;
458
- }).join("");
459
- }
460
-
461
189
  function safeDisplayText(value: string): string {
462
190
  return Array.from(stripVTControlCharacters(value), (character) => {
463
191
  const codePoint = character.codePointAt(0) ?? 0;
package/src/commands.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
2
- import type { AutocompleteItem } from "@earendil-works/pi-tui";
3
2
  import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
4
- import { showFooterExplanation, showModuleBrowser } from "./command-inspector.js";
3
+ import { completeStarshipArguments, STARSHIP_SUBCOMMANDS } from "./command-contract.js";
4
+ import { showFooterExplanation } from "./command-inspector.js";
5
5
  import { type PreviewMenuResult, showPreviewActionMenu } from "./command-preview.js";
6
6
  import {
7
7
  atomicRestoreConfigDocument,
@@ -13,12 +13,6 @@ import {
13
13
  } from "./config.js";
14
14
  import { inspectUnavailableModules, type StatuslineInspection } from "./modules/inspection.js";
15
15
 
16
- const SUBCOMMANDS: AutocompleteItem[] = [
17
- { value: "settings", label: "settings", description: "Customize the footer TOML" },
18
- { value: "status", label: "status", description: "Show configuration health and source" },
19
- { value: "help", label: "help", description: "Show configuration help" },
20
- ];
21
-
22
16
  const MAIN_ACTIONS = {
23
17
  customize: "customize",
24
18
  explain: "explain",
@@ -58,54 +52,56 @@ interface WorkflowOwner {
58
52
  export function registerStarshipCommand(pi: ExtensionAPI, options: StarshipCommandOptions) {
59
53
  pi.registerCommand("starship", {
60
54
  description: "Customize or inspect the native Starship-style footer",
61
- getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
62
- const normalized = prefix.trim().toLowerCase();
63
- const matches = SUBCOMMANDS.filter((item) => item.value.startsWith(normalized));
64
- return matches.length > 0 ? matches : null;
65
- },
66
- handler: async (args, ctx) => {
67
- const normalized = args.trim();
68
- if (!normalized) {
69
- if (ctx.mode === "tui") await showMainMenu(ctx, options);
70
- else showHelp(ctx, options.settingsPath);
71
- return;
72
- }
73
-
74
- const [subcommand = "", ...trailing] = normalized.split(/\s+/u);
75
- const route = subcommand.toLowerCase();
76
- if (trailing.length > 0 || !SUBCOMMANDS.some((item) => item.value === route)) {
77
- if (canNotify(ctx)) {
78
- const reason =
79
- trailing.length > 0
80
- ? `Unexpected arguments for /starship ${safeText(route)}.`
81
- : `Unknown /starship subcommand: ${safeText(route)}.`;
82
- ctx.ui.notify(`${reason} Usage: /starship [settings|status|help]`, "warning");
83
- }
84
- return;
85
- }
86
- switch (route) {
87
- case "settings":
88
- await editSettings(ctx, options);
89
- return;
90
- case "status":
91
- showStatus(ctx, options);
92
- return;
93
- case "help":
94
- showHelp(ctx, options.settingsPath);
95
- return;
96
- }
97
- },
55
+ getArgumentCompletions: completeStarshipArguments,
56
+ handler: (args, ctx) => handleStarshipCommand(args, ctx, options),
98
57
  });
99
58
  }
100
59
 
60
+ export async function handleStarshipCommand(
61
+ args: string,
62
+ ctx: ExtensionCommandContext,
63
+ options: StarshipCommandOptions,
64
+ ) {
65
+ const normalized = args.trim();
66
+ if (!normalized) {
67
+ if (ctx.mode === "tui") await showMainMenu(ctx, options);
68
+ else showHelp(ctx, options.settingsPath);
69
+ return;
70
+ }
71
+
72
+ const [subcommand = "", ...trailing] = normalized.split(/\s+/u);
73
+ const route = subcommand.toLowerCase();
74
+ if (trailing.length > 0 || !STARSHIP_SUBCOMMANDS.some((item) => item.value === route)) {
75
+ if (canNotify(ctx)) {
76
+ const reason =
77
+ trailing.length > 0
78
+ ? `Unexpected arguments for /starship ${safeText(route)}.`
79
+ : `Unknown /starship subcommand: ${safeText(route)}.`;
80
+ ctx.ui.notify(`${reason} Usage: /starship [settings|status|help]`, "warning");
81
+ }
82
+ return;
83
+ }
84
+ switch (route) {
85
+ case "settings":
86
+ await editSettings(ctx, options);
87
+ return;
88
+ case "status":
89
+ showStatus(ctx, options);
90
+ return;
91
+ case "help":
92
+ showHelp(ctx, options.settingsPath);
93
+ return;
94
+ }
95
+ }
96
+
101
97
  async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipCommandOptions) {
102
98
  const fallbackController = new AbortController();
103
99
  const owner = options.getMenuOwner?.() ?? {
104
100
  signal: fallbackController.signal,
105
101
  isCurrent: () => !fallbackController.signal.aborted,
106
102
  };
107
- type Screen = "main" | "configuration" | "help";
108
- type Action = "customize" | "explain" | "modules" | "restore";
103
+ type Screen = "main" | "modules" | "configuration" | "help";
104
+ type Action = "customize" | "explain" | "restore";
109
105
  const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
110
106
  start: "main",
111
107
  screens: {
@@ -133,7 +129,7 @@ async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipComma
133
129
  id: MAIN_ACTIONS.modules,
134
130
  label: "Modules",
135
131
  description: "Browse supported modules and current states",
136
- action: "modules",
132
+ to: "modules",
137
133
  },
138
134
  {
139
135
  id: MAIN_ACTIONS.configuration,
@@ -158,6 +154,34 @@ async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipComma
158
154
  hint: "close",
159
155
  };
160
156
  },
157
+ modules: () => {
158
+ const inspection =
159
+ options.getInspection?.() ?? inspectUnavailableModules(options.getLoaded().config);
160
+ return {
161
+ kind: "browse",
162
+ title: "Modules",
163
+ items: inspection.modules.map((module) => ({
164
+ id: module.name,
165
+ label: module.name,
166
+ statusText: module.state,
167
+ description: module.description,
168
+ searchText: [...module.variables, ...module.styleFields, ...module.displayRules].join(
169
+ " ",
170
+ ),
171
+ details: [
172
+ `Root: ${module.rootReferenced ? "Referenced" : "Not referenced"}`,
173
+ `Reachable: ${module.reachable ? "Yes" : "No"}`,
174
+ ...modulePreviewDetails(module.preview),
175
+ `Reason: ${module.reason}`,
176
+ `Variables: ${module.variables.join(", ") || "none"}`,
177
+ `Style fields: ${module.styleFields.join(", ") || "none"}`,
178
+ `Display rules: ${module.displayRules.join(" · ") || "none"}`,
179
+ ],
180
+ })),
181
+ viewportSize: "adaptive",
182
+ hint: "back",
183
+ };
184
+ },
161
185
  configuration: () => {
162
186
  const loaded = options.getLoaded();
163
187
  const presentation = configurationPresentation(loaded);
@@ -197,13 +221,6 @@ async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipComma
197
221
  if (!isCurrentOwner(owner)) return { kind: "stay" };
198
222
  return result?.kind === "back" ? { kind: "stay" } : { kind: "close" };
199
223
  },
200
- modules: async () => {
201
- const inspection =
202
- options.getInspection?.() ?? inspectUnavailableModules(options.getLoaded().config);
203
- const result = await showModuleBrowser(ctx, inspection, owner.signal);
204
- if (!isCurrentOwner(owner)) return { kind: "stay" };
205
- return result?.kind === "back" ? { kind: "stay" } : { kind: "close" };
206
- },
207
224
  restore: async () => {
208
225
  const presentation = configurationPresentation(options.getLoaded());
209
226
  if (presentation.restoreDisabled) {
@@ -366,6 +383,11 @@ async function reviewAndApply(
366
383
  }
367
384
  }
368
385
 
386
+ function modulePreviewDetails(preview: string): string[] {
387
+ const lines = preview ? preview.split("\n") : ["(no current preview)"];
388
+ return lines.map((line, index) => `${index === 0 ? "Preview: " : " "}${line}`);
389
+ }
390
+
369
391
  function workflowOwner(options: StarshipCommandOptions): WorkflowOwner {
370
392
  if (options.getMenuOwner) return options.getMenuOwner();
371
393
  const controller = new AbortController();