ktop Release v0.7.0

ktop v0.7.0 introduces an adaptive terminal theme engine with automatic background luminance and color-depth detection, refactors cluster state delivery around an immutable Snapshot pipeline and application.Runner boundary, and aligns Prometheus CPU rate and history calculations across overview and detail views.

Operators can run ktop across dark, light, 16-color ANSI, and $NO_COLOR / monochrome terminals without manual configuration, or set explicit --theme and --color-mode preferences on the command line and in ~/.ktop/config.yaml. Under the hood, overview tables and drill-down detail views render from lock-free point-in-time Snapshot projections, while the Prometheus metrics pipeline preserves upstream cAdvisor sample timestamps and series semantics to eliminate rate drift and transient 0m CPU drops.

Detailed Changes by Category

1. Adaptive Terminal Themes & UI Styling

Semantic Palette Engine and Built-in Themes

• Problem / Context: UI widgets, tables, sparklines, saturation gauges, and modal dialogs previously relied on hardcoded colors tuned only for dark TrueColor terminals, causing low-contrast text on light backgrounds, inconsistent highlights on 16-color profiles, and residual color escapes in monochrome sessions.
• Implementation Details: Added package ui/theme (ui/theme/palette.go, ui/theme/builtins.go, ui/theme/format.go) defining a 33-token semantic Palette (CanvasBg, HeaderBg, RowSelectedBg, StatusOK..StatusError, GaugeLow..GaugeHigh, SparklineNormal, ToastInfoBg..ToastErrorBg, etc.) with four built-in themes: DarkPalette, LightPalette, ANSIPalette, and MonochromePalette. Migrated overview panels, node/pod/container detail panels, sparklines, bargraphs, filter inputs, help/column modals, and *ui.ToastModal notifications (ui/toast.go) to resolve colors dynamically from the active palette while maintaining WCAG AA contrast (>= 4.5:1).
• Impact & Behavioral Notes: Tables, headers, summary bargraphs, resource gauges, and interactive toast modals (Retry / Quit actions and severity borders) render legibly across all four built-in palettes. When monochrome (or --color-mode=none) is active, ktop emits zero ANSI color sequences and distinguishes focus, headers, selection, and error states using AttrBold, AttrUnderline, AttrReverse, and ! prefixes (ui.ErrorMarkup).

Automatic Terminal Background Detection and 4-Tier Color Quantization

• Problem / Context: Terminal emulators vary in background luminance and color capability across local consoles, tmux, SSH sessions, TERM=dumb, and $NO_COLOR environments.
• Implementation Details: Implemented theme.Resolve (ui/theme/detect.go) with deterministic auto-detection precedence: explicit theme override -> $NO_COLOR or TERM=dumb (monochrome) -> $COLORFGBG background index parsing (ParseCOLORFGBG) -> non-blocking 50ms OSC 11 background query (ProbeTerminalLightBg / ParseOSC11Luminance using ITU-R BT.709 relative luminance) -> dark default. Implemented ResolveColor (ui/theme/palette.go) to quantize 24-bit RGB palette tokens to the 6x6x6 xterm-256 cube and 24-step grayscale ramp (ColorMode256), nearest 16-color ANSI (ColorMode16), or tcell.ColorDefault (ColorModeNone).
• Impact & Behavioral Notes: --theme=auto selects an appropriate light, dark, or monochrome theme at startup without blocking non-interactive streams or character devices that do not support read deadlines, and automatically maps palette tokens to the terminal's supported color tier.

2. CLI & Persistent Configuration

--theme and --color-mode Flags and ~/.ktop/config.yaml Persistence

• Problem / Context: Users needed session-scoped CLI overrides and persistent user defaults for theme selection and terminal color-depth degradation.
• Implementation Details: Added --theme and --color-mode flags in cmd/ktop.go (NewKtopCmd), validated by config.NormalizeTheme and config.NormalizeColorMode (config/config.go). Extended config.UIConfig (ui.theme, ui.color_mode) in ~/.ktop/config.yaml with auto defaults.
• APIs / Signatures:

  # Automatic background and color-depth detection (default)
  ktop
  
  # Force light or monochrome theme
  ktop --theme=light
  ktop --theme=monochrome
  
  # Override terminal color depth for SSH or multiplexer sessions
  ktop --theme=dark --color-mode=256

  # ~/.ktop/config.yaml
  ui:
    theme: auto
    color_mode: auto

• Impact & Behavioral Notes: Preferences configured under ui.theme and ui.color_mode in ~/.ktop/config.yaml apply automatically at startup; --theme and --color-mode command-line flags override saved settings for the current session without mutating the config file. Unrecognized values exit immediately with a validation error listing accepted options.

3. Core Architecture & Data Pipeline

Immutable Snapshot Model and Lock-Free SnapshotBuilder

• Problem / Context: Overview panels and resource detail pages previously assembled view state separately from mutable Kubernetes models, pointer-based resource.Quantity fields, and live metrics lookups during draw cycles.
• Implementation Details: Added package internal/snapshot (internal/snapshot/snapshot.go, internal/snapshot/builder.go) defining value-type Snapshot, ClusterInfo, SummaryData, NodeData, PodData, ContainerData, and PSIData structs with deep-copy Clone() and indexed accessors (NodeByName, PodByKey, PodsOnNode). Implemented snapshot.Builder.Build for lock-free in-memory joins of cached controller models and batch pod/container metrics, alongside NodeDetailProjection, PodDetailProjection, and ContainerUsageFromSnapshot. Updated overview (views/overview) and detail panels (views/node, views/pod, views/container) to render from Snapshot values and projections.
• Impact & Behavioral Notes: Overview tables and detail pages render from a unified point-in-time state representation without performing network I/O or holding locks on the UI draw goroutine.

application.Runner Interface and application/tui Lifecycle Package

• Problem / Context: Startup orchestration in cmd/ktop.go directly coupled CLI flag parsing to tview page construction, RBAC preflight checks, and terminal screen initialization.
• Implementation Details: Defined the application.Runner interface (Run(ctx context.Context) error, Stop() error in application/app.go) and extracted interactive TUI initialization into application/tui (tui.NewRunner, tui.App, tui.Options in application/tui/app.go), encapsulating theme resolution, overview layout, initial column sorting, k8sC.AssertCoreAuthz(ctx), and minimum terminal height checks.
• Impact & Behavioral Notes: Cleanly separates command/configuration wiring from TUI execution while preserving existing preflight authorization diagnostics and exit behavior.

4. Prometheus Metrics & Resource Reporting

Upstream Timestamp Anchoring, Node CPU Series Selection, and Fallback Alignment

• Problem / Context: Under Prometheus scraping, node CPU metrics could disagree between Cluster Summary, the Nodes table, and the Node Detail view when cAdvisor housekeeping intervals exceeded the query window (causing transient 0m drops), when local scrape timing jitter skewed counter rate denominators, or when root cgroup (id="/") metrics exposed both cpu="total" and per-core cpu="0".. series. Additionally, valid 0m / 0Mi usage was treated as missing usage data, causing views to fall back to displaying requested resources instead of 0.0% used.
• Implementation Details:
  • Updated KubernetesScraper (prom/scraper.go) and InMemoryStore (prom/storage.go) to record explicit upstream sample timestamps (MetricSample.UpstreamTimestamp), skip unchanged cached cAdvisor samples, and anchor stored sample timestamps using exact upstream elapsed deltas.
  • Added selectNodeCPUSeries and querySeriesForRate (metrics/prom/prom_source.go) to filter root node CPU series (id="/") to cpu="total" (or unlabelled aggregates) when present, and fall back to a 3m lookback (maxSeriesSampleAgeMs = 90s) when dynamic cAdvisor housekeeping exceeds the 40s rate window.
  • Updated GetNodeHistory and GetPodHistory (seriesCounterMilliRates, aggregateSeriesHistory in metrics/prom/prom_source.go) to convert cumulative container_cpu_usage_seconds_total counters into per-interval millicore rates and carry forward multi-series values across staggered timestamps.
  • Added explicit HasUsageCPU and HasUsageMemory booleans across SummaryData, NodeData, ClusterSummary, and view renderers (views/overview/node_panel.go, views/overview/summary_panel.go, views/node/detail.go).
• Impact & Behavioral Notes: Cluster Summary, Nodes table rows, Node/Pod Detail panels, and CPU history sparklines report consistent millicore usage rates and utilization percentages, and distinguish genuine idle usage (0m / 0.0% used) from unavailable metrics fallback (requested).

Upgrade & Compatibility Notes

• Backward Compatibility: Fully backward compatible with existing CLI invocations, kubeconfig setups, and ~/.ktop/config.yaml files. Existing config.yaml files without ui.theme or ui.color_mode default to auto.
• Deprecations & Retractions: None.
• Migration Actions: None required. Users running on light terminals or $NO_COLOR environments will automatically receive matching palettes under the default --theme=auto setting; users who prefer the classic dark palette regardless of terminal background can set --theme=dark or configure ui.theme: dark in ~/.ktop/config.yaml.

Workspace / Repository Metrics

 56 files changed, 6858 insertions(+), 1369 deletions(-)

• Documentation & Examples:
  • CLI Reference — Themes and Terminal Color Adaptation (docs/cli.md)
  • Project Overview & Session Configuration (README.md)