@narumitw/pi-starship 0.59.2 → 0.60.1

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/src/commands.ts CHANGED
@@ -1,5 +1,13 @@
1
1
  import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
2
+ import { isKeyRelease, Key, matchesKey } from "@earendil-works/pi-tui";
2
3
  import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
4
+ import {
5
+ type CommitExpectation,
6
+ type CommitOptions,
7
+ captureCommitExpectation,
8
+ commitActiveDocument,
9
+ commitOwnerCurrent,
10
+ } from "./command-commit.js";
3
11
  import {
4
12
  type ConfigurationCommandOptions,
5
13
  configurationMenuScreen,
@@ -15,14 +23,8 @@ import { importSettingsGist, shareSettingsGist } from "./command-gist.js";
15
23
  import { formatFooterExplanation } from "./command-inspector.js";
16
24
  import { showPresetPicker } from "./command-preset-picker.js";
17
25
  import { type PreviewMenuResult, showPreviewActionMenu } from "./command-preview.js";
18
- import {
19
- atomicRestoreConfigDocument,
20
- atomicSaveConfigDocument,
21
- BUILT_IN_EXAMPLE,
22
- type LoadedStarshipConfig,
23
- removeConfigDocumentIfMatches,
24
- validateConfigDocument,
25
- } from "./config.js";
26
+ import { saveAsProfile, showHistory, showProfiles } from "./command-profiles.js";
27
+ import { BUILT_IN_EXAMPLE, type LoadedStarshipConfig, validateConfigDocument } from "./config.js";
26
28
  import type { GhApi } from "./gist.js";
27
29
  import { inspectUnavailableModules, type StatuslineInspection } from "./modules/inspection.js";
28
30
  import { getStarshipPreset, presetForDocument, STARSHIP_PRESETS, type StarshipPreset } from "./presets/catalog.js";
@@ -35,15 +37,17 @@ const MAIN_ACTIONS = {
35
37
  configuration: "configuration",
36
38
  help: "help",
37
39
  restore: "restore",
40
+ profiles: "profiles",
38
41
  } as const;
39
42
 
40
43
  const PREVIEW_ACTIONS = {
41
44
  continue: "continue",
42
45
  edit: "edit",
43
46
  cancel: "cancel",
47
+ saveProfile: "save-profile",
44
48
  } as const;
45
49
 
46
- export interface StarshipCommandOptions extends ConfigurationCommandOptions {
50
+ export interface StarshipCommandOptions extends ConfigurationCommandOptions, CommitOptions {
47
51
  getInspection?(): StatuslineInspection | undefined;
48
52
  preview?(loaded: LoadedStarshipConfig | undefined, ctx: ExtensionCommandContext): void;
49
53
  save?: (settingsPath: string, rawDocument: string) => LoadedStarshipConfig;
@@ -53,10 +57,12 @@ export interface StarshipCommandOptions extends ConfigurationCommandOptions {
53
57
  gistApi?: GhApi;
54
58
  }
55
59
 
56
- type ReviewIntent =
60
+ export type ReviewIntent =
57
61
  | { kind: "customize" }
58
62
  | { kind: "restore" }
59
63
  | { kind: "import" }
64
+ | { kind: "profile"; name: string }
65
+ | { kind: "history"; name?: string }
60
66
  | { kind: "preset"; preset: StarshipPreset };
61
67
 
62
68
  export function registerStarshipCommand(pi: ExtensionAPI, options: StarshipCommandOptions) {
@@ -72,6 +78,43 @@ export async function handleStarshipCommand(
72
78
  ctx: ExtensionCommandContext,
73
79
  options: StarshipCommandOptions,
74
80
  ) {
81
+ if (ctx.mode !== "tui") return runStarshipCommand(args, ctx, options);
82
+ const base = workflowOwner(options);
83
+ if (!isCurrentOwner(base)) return;
84
+ const controller = new AbortController();
85
+ const signal = AbortSignal.any([base.signal, controller.signal]);
86
+ const owner: WorkflowOwner = {
87
+ signal,
88
+ isCurrent: () => !signal.aborted && base.isCurrent(),
89
+ isSessionCurrent: () => base.isSessionCurrent?.() ?? base.isCurrent(),
90
+ };
91
+ // Pi delivers bracketed paste as one framed packet. Exact key matching does
92
+ // not treat controls inside pasted text as cancellation or consume native input.
93
+ const unsubscribe = ctx.ui.onTerminalInput((data) => {
94
+ if (!isKeyRelease(data) && matchesKey(data, Key.ctrl("c"))) {
95
+ // Let the current native dialog receive this input before abort restores
96
+ // focus; otherwise the same key can reach the underlying editor.
97
+ queueMicrotask(() => controller.abort());
98
+ }
99
+ return undefined;
100
+ });
101
+ let listening = true;
102
+ const release = () => {
103
+ if (!listening) return;
104
+ listening = false;
105
+ unsubscribe();
106
+ };
107
+ signal.addEventListener("abort", release, { once: true });
108
+ try {
109
+ return await runStarshipCommand(args, ctx, { ...options, getMenuOwner: () => owner });
110
+ } finally {
111
+ signal.removeEventListener("abort", release);
112
+ release();
113
+ controller.abort();
114
+ }
115
+ }
116
+
117
+ async function runStarshipCommand(args: string, ctx: ExtensionCommandContext, options: StarshipCommandOptions) {
75
118
  const normalized = args.trim();
76
119
  if (!normalized) {
77
120
  if (ctx.mode === "tui") await showMainMenu(ctx, options);
@@ -119,7 +162,15 @@ async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipComma
119
162
  | "configuration-effective"
120
163
  | "configuration-document"
121
164
  | "help";
122
- type Action = "customize" | "presets" | "configuration-reload" | "restore" | "gist-share" | "gist-import";
165
+ type Action =
166
+ | "customize"
167
+ | "presets"
168
+ | "profiles"
169
+ | "history"
170
+ | "configuration-reload"
171
+ | "restore"
172
+ | "gist-share"
173
+ | "gist-import";
123
174
  const menu = defineMenu<undefined, Screen, Action, ExtensionCommandContext>({
124
175
  start: "main",
125
176
  screens: {
@@ -174,6 +225,12 @@ async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipComma
174
225
  disabled: presentation.restoreDisabled,
175
226
  action: "restore",
176
227
  },
228
+ {
229
+ id: MAIN_ACTIONS.profiles,
230
+ label: "Profiles",
231
+ description: "Save, edit, manage, and live-preview named TOML documents",
232
+ action: "profiles",
233
+ },
177
234
  ],
178
235
  hint: "close",
179
236
  };
@@ -222,7 +279,9 @@ async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipComma
222
279
  title: "pi-starship help",
223
280
  lines: [
224
281
  "Customize footer opens the TOML editor, then previews and confirms before saving.",
225
- "Presets live-previews the cursor in the footer; Enter confirms apply and e customizes first.",
282
+ "Presets live-previews the cursor in the footer; Enter confirms apply, e customizes, and s saves a profile when available.",
283
+ "Profiles manages named TOML copies; selecting a document previews it without saving.",
284
+ "Configuration History reviews and restores recovery copies; external edits are not fully tracked.",
226
285
  "Explain footer breaks down the modules currently showing from the existing snapshot.",
227
286
  "Modules searches every supported module and explains its current read-only state.",
228
287
  "Configuration includes disk reload plus unlisted Gist sharing and reviewed Gist import through gh.",
@@ -241,6 +300,36 @@ async function showMainMenu(ctx: ExtensionCommandContext, options: StarshipComma
241
300
  const result = await choosePreset(ctx, options, owner);
242
301
  return result === "applied" || result === "close" ? { kind: "close" } : { kind: "stay" };
243
302
  },
303
+ profiles: async () => {
304
+ const result = await showProfiles(ctx, options, owner, async (loaded, guardedOwner, checkCandidate, name) => {
305
+ const applied = await reviewAndApply(
306
+ ctx,
307
+ options,
308
+ loaded,
309
+ { kind: "profile", name },
310
+ guardedOwner,
311
+ false,
312
+ checkCandidate,
313
+ );
314
+ return applied === "applied" ? "applied" : applied === "close" ? "close" : "stay";
315
+ });
316
+ return result === "close" ? { kind: "close" } : { kind: "stay" };
317
+ },
318
+ history: async () => {
319
+ const result = await showHistory(ctx, options, owner, async (loaded, guardedOwner, checkCandidate, name) => {
320
+ const applied = await reviewAndApply(
321
+ ctx,
322
+ options,
323
+ loaded,
324
+ { kind: "history", name },
325
+ guardedOwner,
326
+ false,
327
+ checkCandidate,
328
+ );
329
+ return applied === "applied" ? "applied" : applied === "close" ? "close" : "stay";
330
+ });
331
+ return result === "close" ? { kind: "close" } : { kind: "stay" };
332
+ },
244
333
  "gist-share": async () => {
245
334
  const result = await shareSettingsGist(ctx, options, owner, options.gistApi);
246
335
  return result === "close" ? { kind: "close" } : { kind: "stay" };
@@ -294,10 +383,12 @@ async function editSettings(
294
383
  if (ctx.hasUI) ctx.ui.notify(`Edit settings manually: ${options.settingsPath}`, "info");
295
384
  return "cancel";
296
385
  }
297
- let draft = options.getLoaded().rawDocument ?? BUILT_IN_EXAMPLE;
386
+ const expected = captureExpectation(ctx, options);
387
+ if (!expected) return "cancel";
388
+ let draft = expected.previous.rawDocument ?? BUILT_IN_EXAMPLE;
298
389
  while (true) {
299
390
  const edited = await ctx.ui.editor("Customize footer — close to preview", draft);
300
- if (!isCurrentOwner(owner) || edited === undefined) return "cancel";
391
+ if (!commitOwnerCurrent(options, owner, expected) || edited === undefined) return "cancel";
301
392
  draft = edited;
302
393
  let validated: LoadedStarshipConfig;
303
394
  try {
@@ -315,13 +406,22 @@ async function editSettings(
315
406
  owner.signal,
316
407
  owner.isCurrent,
317
408
  );
318
- if (!isCurrentOwner(owner)) return "cancel";
409
+ if (!commitOwnerCurrent(options, owner, expected)) return "cancel";
319
410
  if (action?.kind === "closed") return "close";
320
411
  if (selectedPreviewAction(action) === PREVIEW_ACTIONS.edit) continue;
321
412
  return "cancel";
322
413
  }
323
414
 
324
- const result = await reviewAndApply(ctx, options, validated, { kind: "customize" }, owner);
415
+ const result = await reviewAndApply(
416
+ ctx,
417
+ options,
418
+ validated,
419
+ { kind: "customize" },
420
+ owner,
421
+ false,
422
+ undefined,
423
+ expected,
424
+ );
325
425
  if (result === "edit") continue;
326
426
  return result;
327
427
  }
@@ -332,7 +432,9 @@ async function choosePreset(
332
432
  options: StarshipCommandOptions,
333
433
  owner: WorkflowOwner,
334
434
  ): Promise<"applied" | "cancel" | "close"> {
335
- const activePreset = presetForDocument(options.getLoaded().rawDocument);
435
+ const expected = captureExpectation(ctx, options);
436
+ if (!expected) return "cancel";
437
+ const activePreset = presetForDocument(expected.previous.rawDocument);
336
438
  const selection = await showPresetPicker(ctx, {
337
439
  presets: STARSHIP_PRESETS,
338
440
  activePresetId: activePreset?.id,
@@ -344,20 +446,31 @@ async function choosePreset(
344
446
  options.preview?.(loaded, ctx);
345
447
  },
346
448
  });
347
- if (!isCurrentOwner(owner)) {
348
- options.preview?.(undefined, ctx);
449
+ if (!commitOwnerCurrent(options, owner, expected)) {
450
+ clearSessionPreview(ctx, options, owner);
349
451
  return "cancel";
350
452
  }
351
453
  if (selection.kind === "back" || selection.kind === "close") {
352
- options.preview?.(undefined, ctx);
454
+ clearSessionPreview(ctx, options, owner);
353
455
  return selection.kind === "close" ? "close" : "cancel";
354
456
  }
355
457
 
356
458
  const preset = getStarshipPreset(selection.presetId);
357
459
  try {
358
- return await applyPreset(ctx, options, preset, selection.kind === "customize" ? "customize" : "confirm");
460
+ if (selection.kind === "save-profile") {
461
+ const saved = await saveAsProfile(ctx, options, owner, preset.rawDocument);
462
+ return saved === "close" ? "close" : "cancel";
463
+ }
464
+ return await applyPreset(
465
+ ctx,
466
+ options,
467
+ preset,
468
+ selection.kind === "customize" ? "customize" : "confirm",
469
+ expected,
470
+ owner,
471
+ );
359
472
  } finally {
360
- options.preview?.(undefined, ctx);
473
+ clearSessionPreview(ctx, options, owner);
361
474
  }
362
475
  }
363
476
 
@@ -366,13 +479,17 @@ async function applyPreset(
366
479
  options: StarshipCommandOptions,
367
480
  preset: StarshipPreset,
368
481
  start: "review" | "confirm" | "customize" = "review",
482
+ captured?: CommitExpectation,
483
+ capturedOwner?: WorkflowOwner,
369
484
  ): Promise<"applied" | "cancel" | "close"> {
370
- const owner = workflowOwner(options);
485
+ const owner = capturedOwner ?? workflowOwner(options);
371
486
  if (!isCurrentOwner(owner)) return "cancel";
487
+ const expected = captured ?? captureExpectation(ctx, options);
488
+ if (!expected) return "cancel";
372
489
  let draft = preset.rawDocument;
373
490
  if (start === "customize") {
374
491
  const edited = await ctx.ui.editor(`Customize ${preset.label} preset`, draft);
375
- if (!isCurrentOwner(owner) || edited === undefined) return "cancel";
492
+ if (!commitOwnerCurrent(options, owner, expected) || edited === undefined) return "cancel";
376
493
  draft = edited;
377
494
  }
378
495
  while (true) {
@@ -392,11 +509,11 @@ async function applyPreset(
392
509
  owner.signal,
393
510
  owner.isCurrent,
394
511
  );
395
- if (!isCurrentOwner(owner)) return "cancel";
512
+ if (!commitOwnerCurrent(options, owner, expected)) return "cancel";
396
513
  if (action?.kind === "closed") return "close";
397
514
  if (selectedPreviewAction(action) !== PREVIEW_ACTIONS.edit) return "cancel";
398
515
  const edited = await ctx.ui.editor(`Customize ${preset.label} preset`, draft);
399
- if (!isCurrentOwner(owner) || edited === undefined) return "cancel";
516
+ if (!commitOwnerCurrent(options, owner, expected) || edited === undefined) return "cancel";
400
517
  draft = edited;
401
518
  continue;
402
519
  }
@@ -408,10 +525,12 @@ async function applyPreset(
408
525
  { kind: "preset", preset },
409
526
  owner,
410
527
  start === "confirm",
528
+ undefined,
529
+ expected,
411
530
  );
412
531
  if (result !== "edit") return result;
413
532
  const edited = await ctx.ui.editor(`Customize ${preset.label} preset`, draft);
414
- if (!isCurrentOwner(owner) || edited === undefined) return "cancel";
533
+ if (!commitOwnerCurrent(options, owner, expected) || edited === undefined) return "cancel";
415
534
  draft = edited;
416
535
  }
417
536
  }
@@ -427,14 +546,19 @@ async function restoreBuiltIn(
427
546
  return result === "edit" ? "cancel" : result;
428
547
  }
429
548
 
430
- async function reviewAndApply(
549
+ export async function reviewAndApply(
431
550
  ctx: ExtensionCommandContext,
432
551
  options: StarshipCommandOptions,
433
552
  validated: LoadedStarshipConfig,
434
553
  intent: ReviewIntent,
435
554
  owner: WorkflowOwner,
436
555
  skipReview = false,
556
+ checkCandidate?: () => void,
557
+ captured?: CommitExpectation,
437
558
  ): Promise<"applied" | "edit" | "cancel" | "close"> {
559
+ if (ctx.mode !== "tui" || !isCurrentOwner(owner)) return "cancel";
560
+ const expected = captured ?? captureExpectation(ctx, options);
561
+ if (!expected) return "cancel";
438
562
  let reviewRequired = !skipReview;
439
563
  while (true) {
440
564
  const directAttempt = !reviewRequired;
@@ -445,7 +569,7 @@ async function reviewAndApply(
445
569
  (width) => reviewPreviewBody(ctx, options, validated, width, intent),
446
570
  [
447
571
  { value: PREVIEW_ACTIONS.continue, label: continueLabel(intent) },
448
- ...(intent.kind === "restore" || intent.kind === "import"
572
+ ...(intent.kind !== "customize" && intent.kind !== "preset"
449
573
  ? []
450
574
  : [
451
575
  {
@@ -462,60 +586,59 @@ async function reviewAndApply(
462
586
  ? "Choose another preset"
463
587
  : "Discard draft",
464
588
  },
589
+ ...(intent.kind === "customize" || intent.kind === "preset" || intent.kind === "import"
590
+ ? [{ value: PREVIEW_ACTIONS.saveProfile, label: "Save as profile…" }]
591
+ : []),
465
592
  ],
466
593
  owner.signal,
467
594
  owner.isCurrent,
468
595
  );
469
- if (!isCurrentOwner(owner)) return "cancel";
596
+ if (!commitOwnerCurrent(options, owner, expected)) return "cancel";
470
597
  if (selection?.kind === "closed") return "close";
471
598
  const selected = selectedPreviewAction(selection);
472
599
  if (selected === PREVIEW_ACTIONS.edit) return "edit";
600
+ if (selected === PREVIEW_ACTIONS.saveProfile) {
601
+ const saved = await saveAsProfile(ctx, options, owner, validated.rawDocument ?? BUILT_IN_EXAMPLE);
602
+ if (saved === "close") return "close";
603
+ if (!commitOwnerCurrent(options, owner, expected)) return "cancel";
604
+ continue;
605
+ }
473
606
  if (selected !== PREVIEW_ACTIONS.continue) return "cancel";
474
607
  }
475
608
  reviewRequired = true;
476
609
 
477
610
  const confirmed = await ctx.ui.confirm(
478
611
  confirmationTitle(intent),
479
- confirmationMessage(options.settingsPath, intent),
612
+ confirmationMessage(options.settingsPath, intent, expected.previous),
480
613
  { signal: owner.signal },
481
614
  );
482
- if (!isCurrentOwner(owner)) return "cancel";
615
+ if (!commitOwnerCurrent(options, owner, expected)) return "cancel";
483
616
  if (!confirmed) {
484
617
  if (directAttempt) return "cancel";
485
618
  continue;
486
619
  }
487
620
 
488
- const save = options.save ?? atomicSaveConfigDocument;
489
- const previous = options.getLoaded();
490
- let saved: LoadedStarshipConfig;
491
621
  try {
492
- saved = save(options.settingsPath, validated.rawDocument ?? BUILT_IN_EXAMPLE);
493
- } catch (error) {
494
- ctx.ui.notify(
495
- `Footer settings were not saved: ${safeText(formatError(error))}. The previous footer remains active.`,
496
- "error",
622
+ const result = await commitActiveDocument(
623
+ ctx,
624
+ options,
625
+ validated,
626
+ owner,
627
+ expected,
628
+ intent.kind === "restore" || intent.kind === "history" || intent.kind === "customize",
629
+ checkCandidate,
497
630
  );
498
- if (directAttempt) return "cancel";
499
- continue;
500
- }
501
-
502
- try {
503
- options.apply(saved, ctx);
631
+ if (!isSessionOwnerCurrent(owner) || result === "cancel") return "cancel";
504
632
  } catch (error) {
505
- const rollbackError = restorePreviousConfiguration(ctx, options, previous, saved);
506
- ctx.ui.notify(
507
- rollbackError
508
- ? `Footer settings could not be applied: ${safeText(formatError(error))}. Restoring the previous configuration also failed: ${safeText(formatError(rollbackError))}.`
509
- : `Footer settings could not be applied: ${safeText(formatError(error))}. The previous configuration was restored.`,
510
- "error",
511
- );
633
+ if (!isSessionOwnerCurrent(owner)) return "cancel";
634
+ ctx.ui.notify(safeText(formatError(error)), "error");
512
635
  if (directAttempt) return "cancel";
513
636
  continue;
514
637
  }
515
638
 
516
639
  const warningSuffix =
517
- saved.diagnostics.length > 0
518
- ? ` (${saved.diagnostics.length} warning${saved.diagnostics.length === 1 ? "" : "s"})`
640
+ validated.diagnostics.length > 0
641
+ ? ` (${validated.diagnostics.length} warning${validated.diagnostics.length === 1 ? "" : "s"})`
519
642
  : "";
520
643
  ctx.ui.notify(`${successMessage(intent)}${warningSuffix}.`, "info");
521
644
  return "applied";
@@ -530,6 +653,10 @@ function reviewTitle(intent: ReviewIntent): string {
530
653
  return "Restore preview";
531
654
  case "import":
532
655
  return "Gist footer preview";
656
+ case "profile":
657
+ return `${safeText(intent.name)} profile preview`;
658
+ case "history":
659
+ return "History recovery preview";
533
660
  case "preset":
534
661
  return `${intent.preset.label} preset preview`;
535
662
  }
@@ -543,6 +670,10 @@ function continueLabel(intent: ReviewIntent): string {
543
670
  return "Replace with built-in…";
544
671
  case "import":
545
672
  return "Replace with Gist settings…";
673
+ case "profile":
674
+ return `Apply ${safeText(intent.name)} profile…`;
675
+ case "history":
676
+ return "Restore history document…";
546
677
  case "preset":
547
678
  return `Apply ${intent.preset.label} preset…`;
548
679
  }
@@ -556,20 +687,32 @@ function confirmationTitle(intent: ReviewIntent): string {
556
687
  return "Restore built-in footer?";
557
688
  case "import":
558
689
  return "Replace settings with Gist?";
690
+ case "profile":
691
+ return `Apply ${safeText(intent.name)} profile?`;
692
+ case "history":
693
+ return "Restore settings from history?";
559
694
  case "preset":
560
695
  return `Apply ${intent.preset.label} preset?`;
561
696
  }
562
697
  }
563
698
 
564
- function confirmationMessage(settingsPath: string, intent: ReviewIntent): string {
565
- if (intent.kind === "customize") return "Save this configuration and apply it immediately?";
699
+ function confirmationMessage(settingsPath: string, intent: ReviewIntent, previous: LoadedStarshipConfig): string {
700
+ if (previous.diagnostics.some((item) => item.severity === "error")) {
701
+ return `Explicit recovery: replace the invalid settings file ${safeText(settingsPath)} entirely with the reviewed document? Its exact original bytes will be kept in History before replacement.`;
702
+ }
703
+ if (intent.kind === "customize")
704
+ return "Replace the entire settings document and apply it immediately? Its previous bytes will be kept in History.";
566
705
  const replacement =
567
706
  intent.kind === "restore"
568
707
  ? "the built-in configuration"
569
708
  : intent.kind === "import"
570
709
  ? "the reviewed Gist settings"
571
- : `the ${intent.preset.label} preset`;
572
- return `Replace ${safeText(settingsPath)} entirely with ${replacement}? All custom settings, unknown fields, and comments will be removed. No backup is kept after success.`;
710
+ : intent.kind === "profile"
711
+ ? `the ${safeText(intent.name)} profile`
712
+ : intent.kind === "history"
713
+ ? "the reviewed history document"
714
+ : `the ${intent.preset.label} preset`;
715
+ return `Replace ${safeText(settingsPath)} entirely with ${replacement}? All custom settings, unknown fields, and comments will be replaced. The previous document will be kept in History.`;
573
716
  }
574
717
 
575
718
  function successMessage(intent: ReviewIntent): string {
@@ -580,6 +723,10 @@ function successMessage(intent: ReviewIntent): string {
580
723
  return "Built-in footer restored and applied";
581
724
  case "import":
582
725
  return "Gist settings saved and applied";
726
+ case "profile":
727
+ return `${safeText(intent.name)} profile applied`;
728
+ case "history":
729
+ return "History document restored and applied";
583
730
  case "preset":
584
731
  return `${intent.preset.label} preset saved and applied`;
585
732
  }
@@ -600,24 +747,23 @@ function isCurrentOwner(owner: WorkflowOwner): boolean {
600
747
  return !owner.signal.aborted && owner.isCurrent();
601
748
  }
602
749
 
603
- function restorePreviousConfiguration(
750
+ function isSessionOwnerCurrent(owner: WorkflowOwner): boolean {
751
+ return !owner.signal.aborted && (owner.isSessionCurrent?.() ?? owner.isCurrent());
752
+ }
753
+
754
+ function clearSessionPreview(ctx: ExtensionCommandContext, options: StarshipCommandOptions, owner: WorkflowOwner) {
755
+ if (owner.isSessionCurrent?.() ?? owner.isCurrent()) options.preview?.(undefined, ctx);
756
+ }
757
+
758
+ function captureExpectation(
604
759
  ctx: ExtensionCommandContext,
605
760
  options: StarshipCommandOptions,
606
- previous: LoadedStarshipConfig,
607
- saved: LoadedStarshipConfig,
608
- ): unknown {
761
+ ): CommitExpectation | undefined {
609
762
  try {
610
- if (saved.rawDocument === undefined || saved.fileIdentity === undefined) {
611
- throw new Error("The saved settings document identity is unavailable");
612
- }
613
- removeConfigDocumentIfMatches(options.settingsPath, saved.rawDocument, saved.fileIdentity);
614
- if (previous.rawDocument !== undefined) {
615
- (options.restore ?? atomicRestoreConfigDocument)(options.settingsPath, previous.rawDocument);
616
- }
617
- options.apply(previous, ctx);
618
- return undefined;
763
+ return captureCommitExpectation(options);
619
764
  } catch (error) {
620
- return error;
765
+ ctx.ui.notify(`Footer settings were not saved: ${safeText(formatError(error))}`, "error");
766
+ return undefined;
621
767
  }
622
768
  }
623
769
 
@@ -629,7 +775,7 @@ function reviewPreviewBody(
629
775
  intent: ReviewIntent,
630
776
  ): string[] {
631
777
  if (intent.kind === "restore") return restorePreviewBody(ctx, options, loaded, width);
632
- if (intent.kind === "customize" || intent.kind === "import") return previewBody(ctx, options, loaded, width);
778
+ if (intent.kind !== "preset") return previewBody(ctx, options, loaded, width);
633
779
  const current = configurationPresentation(options.getLoaded());
634
780
  return [
635
781
  `Preset: ${intent.preset.label}`,
@@ -637,7 +783,7 @@ function reviewPreviewBody(
637
783
  `Current: ${current.state}`,
638
784
  `Path: ${safeText(options.settingsPath)}`,
639
785
  "Applying replaces the entire settings document, including custom settings, unknown fields, and comments.",
640
- "No backup is kept after a successful apply.",
786
+ "The previous document will be kept in History before replacement.",
641
787
  "",
642
788
  ...previewBody(ctx, options, loaded, width),
643
789
  ];
@@ -654,7 +800,7 @@ function restorePreviewBody(
654
800
  `Current: ${current.state}`,
655
801
  `Path: ${safeText(options.settingsPath)}`,
656
802
  "The entire settings document will be replaced, including custom settings, unknown fields, and comments.",
657
- "No backup is kept after a successful restore.",
803
+ "The previous document will be kept in History before replacement.",
658
804
  "",
659
805
  ...previewBody(ctx, options, loaded, width),
660
806
  ];
@@ -707,7 +853,7 @@ function showHelp(ctx: ExtensionCommandContext, settingsPath: string) {
707
853
  if (!canNotify(ctx)) return;
708
854
  ctx.ui.notify(
709
855
  [
710
- "/starship — customize, live-preview presets, explain, or inspect the footer in TUI mode",
856
+ "/starship — manage profiles, live-preview presets, recover history, explain, or inspect the footer in TUI mode",
711
857
  "/starship settings — customize, preview, and apply TOML",
712
858
  "/starship status — show source, path, and warnings",
713
859
  "/starship help — show this help",