feat(shared): theme skins (dark/light/high-contrast) + --skin flag + :skin palette

[posquit0]

Summary

• Ship 3 built-in themes (dark, light, high-contrast) via embedded YAML skins
• Allow user overrides at `~/.config/ota/skins/.yaml`
• Select via `--skin ` CLI flag or `:skin ` palette (aliased `:theme`) — hot-swaps at runtime
• Every screen's local `activeTokens()` delegates to `shared.ActiveTokens()` so swap paints on next frame

Files

• `internal/tui/shared/skins.go` — SkinDef/SkinTone types + LoadSkin (embedded → user config → error)
• `internal/tui/shared/skins/{dark,light,high_contrast}.yaml` — embedded via go:embed
• `internal/tui/shared/skins_test.go` — builtin resolution, distinctness, YAML round-trip, live swap, unknown-name safety, NO_COLOR precedence, user-config-path load
• `internal/app/skin_palette_test.go` — palette flow
• `cmd/ota/{main.go,wire.go}` — `--skin` flag wiring
• 8 screen packages: local `activeTokens` swapped to delegate

Test plan

• `go build ./...` + `go test ./... -race -count=1` green
• palette + help goldens regenerated
• manual: `ota --skin light` then `:skin high-contrast` at runtime

[gemini-code-assist]

Code Review

This pull request introduces a theme skin system (MW-10) allowing users to customize the terminal UI appearance via a new --skin CLI flag and a :skin <name> command palette option. It adds three built-in skins (dark, light, high-contrast) and supports loading custom YAML skins from the user's config directory, while refactoring various TUI components to use a centralized active-skin state. The review feedback highlights several important improvements: validating skin names to prevent directory traversal, validating custom YAML skin structures to avoid silent parsing failures, caching environment variables to avoid performance overhead in the rendering hot path, and improving test isolation by using t.Setenv instead of mutating the global environment.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The name parameter is passed directly to userSkinPath and used in filepath.Join without validation. This allows directory traversal (e.g., ../../../../etc/passwd) to read arbitrary YAML files on the system. While this is a local CLI tool, it is best practice to restrict skin names to alphanumeric characters, hyphens, and underscores to prevent directory traversal.

trimmed := strings.TrimSpace(name)
if trimmed == "" {
	return SkinDef{}, fmt.Errorf("skin name is empty")
}
if strings.Contains(trimmed, "..") || strings.ContainsAny(trimmed, "/\\") {
	return SkinDef{}, fmt.Errorf("skin %q: invalid name", trimmed)
}

[gemini-code-assist]

If a user-defined skin has a typo in the tones key (e.g., tonez:), or if the YAML file is empty, yaml.Unmarshal will silently succeed but leave def.Tones empty, resulting in an unstyled theme without any error feedback. Additionally, any typos in individual tone keys (e.g., row_curser) will be silently ignored. Adding validation for empty tones and unknown keys will greatly improve the user experience when creating custom skins.

var validToneKeys = map[string]bool{
	"bg": true, "fg": true, "muted": true, "header": true, "accent": true,
	"primary": true, "success": true, "warning": true, "danger": true, "info": true,
	"magenta": true, "badge_sys": true, "badge_rule": true, "badge_large": true,
	"badge_unmask": true, "row_cursor": true, "row_danger": true, "row_warning": true,
	"row_muted": true, "row_changed": true,
}

func parseSkinDef(data []byte, want string) (SkinDef, error) {
	var def SkinDef
	if err := yaml.Unmarshal(data, &def); err != nil {
		return SkinDef{}, fmt.Errorf("skin %q: parse: %w", want, err)
	}
	if len(def.Tones) == 0 {
		return SkinDef{}, fmt.Errorf("skin %q: no tones defined", want)
	}
	for k := range def.Tones {
		if !validToneKeys[k] {
			return SkinDef{}, fmt.Errorf("skin %q: unknown tone key %q", want, k)
		}
	}
	if def.Name == "" {
		def.Name = want
	}
	return def, nil
}

[gemini-code-assist]

Calling os.Getenv on every single frame (via ActiveTokens -> MonochromeEnabled) introduces unnecessary overhead and lock contention on syscall.envMu in the rendering hot path. Consider caching this value in a package-level variable (e.g., var monochromeEnabled = os.Getenv("NO_COLOR") != "" in styles.go or skins.go) and referencing that instead. For tests, you can expose a helper or directly mutate the variable instead of using t.Setenv.

[gemini-code-assist]

Using os.Unsetenv directly in tests mutates the global environment of the test runner and can pollute other tests running in the same process (especially if the user has NO_COLOR set in their environment). Use t.Setenv("NO_COLOR", "") instead, which automatically restores the original environment state after the test completes. This also applies to other tests in this file (lines 46, 67, 88, 112).

Suggested change

	os.Unsetenv("NO_COLOR")
	t.Setenv("NO_COLOR", "")

[gemini-code-assist]

Since t.Setenv("NO_COLOR", "1") is called on line 137, Go's testing framework will automatically restore the original value of NO_COLOR when the test finishes. Manually calling os.Unsetenv("NO_COLOR") in t.Cleanup is redundant and can incorrectly unset NO_COLOR if it was originally set to a non-empty value before the test ran.

	t.Cleanup(func() {
		_, _ = shared.SetActiveSkin("dark")
	})