feat(theme): add dark mode CLI theme support (#911)

Add the ability to force dark or light mode colors for CLI output,
overriding the automatic terminal background detection.

Changes:
- Add CLITheme field to TownSettings for persisting preference
- Add GetThemeMode() and HasDarkBackground() to ui package for
  theme detection with GT_THEME env var override
- Add ApplyThemeMode() to explicitly set lipgloss dark background
- Add 'gt theme cli' subcommand to view/set CLI theme preference
- Initialize theme in CLI startup (persistentPreRun)
- Add comprehensive tests for theme mode functionality

Usage:
- gt theme cli              # show current theme
- gt theme cli dark         # force dark mode
- gt theme cli light        # force light mode
- gt theme cli auto         # auto-detect (default)
- GT_THEME=dark gt status   # per-command override

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

internal/ui/styles.go

@@ -22,6 +22,16 @@ func init() {
 	}
 }
 
+// ApplyThemeMode applies the theme mode settings to lipgloss.
+// This should be called after InitTheme() has been called.
+func ApplyThemeMode() {
+	if !ShouldUseColor() {
+		return
+	}
+	// Set lipgloss dark background flag based on theme mode
+	lipgloss.SetHasDarkBackground(HasDarkBackground())
+}
+
 // Ayu theme color palette
 // Dark: https://terminalcolors.com/themes/ayu/dark/
 // Light: https://terminalcolors.com/themes/ayu/light/

internal/ui/terminal.go

@@ -2,10 +2,96 @@ package ui
 
 import (
 	"os"
+	"strings"
 
+	"github.com/muesli/termenv"
 	"golang.org/x/term"
 )
 
+// ThemeMode represents the CLI color scheme mode.
+type ThemeMode string
+
+const (
+	// ThemeModeAuto lets the terminal background guide color selection.
+	ThemeModeAuto ThemeMode = "auto"
+	// ThemeModeDark forces dark mode colors (light text on dark background).
+	ThemeModeDark ThemeMode = "dark"
+	// ThemeModeLight forces light mode colors (dark text on light background).
+	ThemeModeLight ThemeMode = "light"
+)
+
+// themeMode is the cached theme mode, set during init.
+var themeMode ThemeMode
+
+// hasDarkBackground caches whether we're in dark mode.
+var hasDarkBackground bool
+
+// InitTheme initializes the theme mode. Call this early in main.
+// configTheme is the value from TownSettings.CLITheme (may be empty).
+func InitTheme(configTheme string) {
+	themeMode = resolveThemeMode(configTheme)
+	hasDarkBackground = detectDarkBackground(themeMode)
+}
+
+// GetThemeMode returns the current CLI color scheme mode.
+// Priority order:
+//  1. GT_THEME environment variable ("dark", "light", "auto")
+//  2. Configured value from settings (passed to InitTheme)
+//  3. Default: "auto"
+func GetThemeMode() ThemeMode {
+	return themeMode
+}
+
+// HasDarkBackground returns true if we're displaying on a dark background.
+// This is used by lipgloss AdaptiveColor to select appropriate colors.
+func HasDarkBackground() bool {
+	return hasDarkBackground
+}
+
+// resolveThemeMode determines the theme mode from env and config.
+func resolveThemeMode(configTheme string) ThemeMode {
+	// Priority 1: GT_THEME environment variable
+	if envTheme := os.Getenv("GT_THEME"); envTheme != "" {
+		switch strings.ToLower(envTheme) {
+		case "dark":
+			return ThemeModeDark
+		case "light":
+			return ThemeModeLight
+		case "auto":
+			return ThemeModeAuto
+		}
+		// Invalid value - fall through to config
+	}
+
+	// Priority 2: Config value
+	if configTheme != "" {
+		switch strings.ToLower(configTheme) {
+		case "dark":
+			return ThemeModeDark
+		case "light":
+			return ThemeModeLight
+		case "auto":
+			return ThemeModeAuto
+		}
+	}
+
+	// Default: auto
+	return ThemeModeAuto
+}
+
+// detectDarkBackground determines if we're on a dark background.
+func detectDarkBackground(mode ThemeMode) bool {
+	switch mode {
+	case ThemeModeDark:
+		return true
+	case ThemeModeLight:
+		return false
+	default:
+		// Auto mode - use termenv detection
+		return termenv.HasDarkBackground()
+	}
+}
+
 // IsTerminal returns true if stdout is connected to a terminal (TTY).
 func IsTerminal() bool {
 	return term.IsTerminal(int(os.Stdout.Fd()))

internal/ui/terminal_test.go

@@ -245,3 +245,90 @@ func TestIsAgentMode_CLAUDE_CODE_AnyValue(t *testing.T) {
 		t.Error("IsAgentMode() should return true when CLAUDE_CODE is set to any value")
 	}
 }
+
+func TestInitTheme_EnvOverridesConfig(t *testing.T) {
+	oldGTTheme := os.Getenv("GT_THEME")
+	defer func() {
+		if oldGTTheme != "" {
+			os.Setenv("GT_THEME", oldGTTheme)
+		} else {
+			os.Unsetenv("GT_THEME")
+		}
+	}()
+
+	// Test: env var overrides config
+	os.Setenv("GT_THEME", "dark")
+	InitTheme("light") // config says light
+	if GetThemeMode() != ThemeModeDark {
+		t.Errorf("Expected dark mode from env var, got %s", GetThemeMode())
+	}
+
+	os.Setenv("GT_THEME", "light")
+	InitTheme("dark") // config says dark
+	if GetThemeMode() != ThemeModeLight {
+		t.Errorf("Expected light mode from env var, got %s", GetThemeMode())
+	}
+}
+
+func TestInitTheme_ConfigUsedWhenNoEnv(t *testing.T) {
+	oldGTTheme := os.Getenv("GT_THEME")
+	defer func() {
+		if oldGTTheme != "" {
+			os.Setenv("GT_THEME", oldGTTheme)
+		} else {
+			os.Unsetenv("GT_THEME")
+		}
+	}()
+
+	os.Unsetenv("GT_THEME")
+
+	InitTheme("dark")
+	if GetThemeMode() != ThemeModeDark {
+		t.Errorf("Expected dark mode from config, got %s", GetThemeMode())
+	}
+
+	InitTheme("light")
+	if GetThemeMode() != ThemeModeLight {
+		t.Errorf("Expected light mode from config, got %s", GetThemeMode())
+	}
+}
+
+func TestInitTheme_DefaultsToAuto(t *testing.T) {
+	oldGTTheme := os.Getenv("GT_THEME")
+	defer func() {
+		if oldGTTheme != "" {
+			os.Setenv("GT_THEME", oldGTTheme)
+		} else {
+			os.Unsetenv("GT_THEME")
+		}
+	}()
+
+	os.Unsetenv("GT_THEME")
+	InitTheme("") // no config
+	if GetThemeMode() != ThemeModeAuto {
+		t.Errorf("Expected auto mode as default, got %s", GetThemeMode())
+	}
+}
+
+func TestHasDarkBackground_ForcedModes(t *testing.T) {
+	oldGTTheme := os.Getenv("GT_THEME")
+	defer func() {
+		if oldGTTheme != "" {
+			os.Setenv("GT_THEME", oldGTTheme)
+		} else {
+			os.Unsetenv("GT_THEME")
+		}
+	}()
+
+	os.Setenv("GT_THEME", "dark")
+	InitTheme("")
+	if !HasDarkBackground() {
+		t.Error("Expected HasDarkBackground() to return true when mode is dark")
+	}
+
+	os.Setenv("GT_THEME", "light")
+	InitTheme("")
+	if HasDarkBackground() {
+		t.Error("Expected HasDarkBackground() to return false when mode is light")
+	}
+}