sc-016.md

← Back to Backlog

[SC-016] Modernize WSL Manager TUI with PwshSpectreConsole

Status: In Progress Priority: High Component: lib/wsl/manager.ps1, lib/wsl/commands.ps1, tools/wsl-manager/wsl-manager.ps1 Depends on: SC-029 Blocks: SC-030, SC-031

Summary: As a user, I want the WSL Manager to have a modern, beautiful terminal interface with arrow-key navigation, rich tables, and instant input so that the interactive experience feels responsive and professional.

Description: The current TUI uses Write-Host with basic colors, Read-Host for all input (requires typing + Enter), and Clear-Host on each loop iteration (causes screen flicker). This item replaces the TUI layer with PwshSpectreConsole v2, a PowerShell wrapper around Spectre.Console that provides rich terminal UI primitives.

This is a significant expansion of the original SC-016 scope (which only covered instant key input and Esc-to-menu). The original acceptance criteria are preserved and extended.

Framework choice: PwshSpectreConsole

PwshSpectreConsole was selected over alternatives for these reasons:

• Idiomatic PowerShell: cmdlets like Read-SpectreSelection, Format-SpectreTable - not raw .NET interop
• Right level of abstraction: selection prompts, tables, progress are exactly what the WSL manager needs
• Best testability: cmdlets can be mocked in Pester; event-driven .NET types (Terminal.Gui) cannot
• Low dependency risk: single PSGallery module, actively maintained
• Incremental adoption: can replace one UI element at a time

Planned changes

1. Replace Read-Host menu selection with Read-SpectreSelection (arrow-key navigation, instant selection, Esc to cancel)
2. Replace Write-Host distro table with Format-SpectreTable (borders, colored status columns, alignment)
3. Replace Read-Host distro selection with Read-SpectreSelection for distro picker lists
4. Add Read-SpectreConfirm for destructive operations (remove, terminate, shutdown)
5. Color-coded status with Spectre markup: [green]Running[/], [red]Stopped[/], [yellow]Installing...[/]
6. Add PwshSpectreConsole as a module dependency (PSGallery install, documented in README)

Technical approach

• Add PwshSpectreConsole module installation to the setup process (after Scoop installs pwsh)
• Build a Show-WslMenu function using Read-SpectreSelection with the current menu options
• Build a Show-WslDistroTable function using Format-SpectreTable
• Build a Select-WslDistro function using Read-SpectreSelection for distro picker
• Existing commands.ps1 action functions remain unchanged - only the TUI layer changes
• Original key-letter shortcuts preserved as accelerators alongside arrow-key navigation

Subtasks

This story is broken into five independently UAT-able subtasks:

1. SC-016a - Add PwshSpectreConsole module dependency to setup process
2. SC-016b - Replace main menu with Read-SpectreSelection
3. SC-016c - Replace distro table with Format-SpectreTable
4. SC-016d - Replace distro selection with Read-SpectreSelection
5. SC-016e - Add Read-SpectreConfirm for destructive operations

SC-016a is the foundation; SC-016b/c/d can proceed in any order after it. SC-016e depends on SC-016d (needs the Spectre-based distro picker).

Acceptance Criteria:

• PwshSpectreConsole module is installed as part of the setup process
• Main menu uses Read-SpectreSelection with arrow-key navigation
• Menu options respond immediately to selection (no Enter + letter required)
• Pressing Ctrl+C at any interactive step returns to the main menu
• Distro table rendered with Format-SpectreTable (borders, colored status)
• Distro selection uses Read-SpectreSelection instead of Read-Host
• Destructive operations (remove, terminate, shutdown) use Read-SpectreConfirm
• Existing command functions in commands.ps1 are not structurally changed
• All existing tests continue to pass
• New TUI functions have Pester unit tests with mocked Spectre cmdlets

← Back to Backlog