feat(config): persist view-state settings and add config versioning (#128)

Retain user preferences (sort, pivot, time range, preview visibility)
across restarts and version updates by saving them to config.json
when changed in the TUI.

Changes:
- Add DefaultSortOrder field to Config for sort direction persistence
- Add ConfigVersion field with migration system (v0 -> v1 migrates
  deprecated LaunchInPlace to LaunchMode)
- Persist sort field, sort order, pivot, time range, and preview
  toggle to config on every change (matches existing PreviewPosition
  and ConversationNewestFirst behavior)
- Add saveConfig() helper for centralized error handling
- Add sortFieldToConfig/sortOrderFromConfig/sortOrderToConfig helpers
- Load sort order from config on startup via EffectiveSortOrder()
- 10 new tests covering migration, round-trip, and effective methods

Co-authored-by: Copilot <[email protected]>

Author: jongio

internal/config/config.go

@@ -27,10 +27,20 @@ const (
 	// maxMaxSessions is the hard upper limit for MaxSessions to prevent
 	// resource exhaustion from a maliciously large config value.
 	maxMaxSessions = 10_000
+
+	// currentConfigVersion is the schema version written to new and migrated
+	// config files. Increment this when making breaking schema changes and
+	// add a corresponding migration case in [migrate].
+	currentConfigVersion = 1
 )
 
 // Config holds the user's preferences.
 type Config struct {
+	// ConfigVersion tracks the schema version of this config file. Used to
+	// detect and apply migrations when the config schema changes across
+	// dispatch releases. The current version is set by [currentConfigVersion].
+	ConfigVersion int `json:"config_version,omitempty"`
+
 	// DefaultShell is the preferred shell name (e.g. "pwsh", "bash", "zsh").
 	DefaultShell string `json:"default_shell"`
 
@@ -46,6 +56,10 @@ type Config struct {
 	// Valid values: "updated", "created", "turns", "name", "folder".
 	DefaultSort string `json:"default_sort"`
 
+	// DefaultSortOrder is the direction used to order session lists.
+	// Valid values: "asc", "desc".
+	DefaultSortOrder string `json:"default_sort_order,omitempty"`
+
 	// DefaultPivot is the default grouping applied to session lists.
 	// Valid values: "none", "folder", "repo", "branch", "date".
 	DefaultPivot string `json:"default_pivot"`
@@ -193,6 +207,14 @@ const (
 	PreviewPositionTop = "top"
 )
 
+// Sort order constants for DefaultSortOrder.
+const (
+	// SortOrderAsc sorts results in ascending order.
+	SortOrderAsc = "asc"
+	// SortOrderDesc sorts results in descending order.
+	SortOrderDesc = "desc"
+)
+
 // EffectivePaneDirection returns the configured pane direction, defaulting
 // to "auto" when unset.
 func (c *Config) EffectivePaneDirection() string {
@@ -213,6 +235,17 @@ func (c *Config) EffectivePreviewPosition() string {
 	}
 }
 
+// EffectiveSortOrder returns the configured sort order, defaulting to "desc"
+// when unset or invalid.
+func (c *Config) EffectiveSortOrder() string {
+	switch c.DefaultSortOrder {
+	case SortOrderAsc, SortOrderDesc:
+		return c.DefaultSortOrder
+	default:
+		return SortOrderDesc
+	}
+}
+
 // defaultAttentionThreshold is used when AttentionThreshold is empty or unparseable.
 const defaultAttentionThreshold = 15 * time.Minute
 
@@ -244,6 +277,7 @@ func (c *Config) EffectiveLaunchMode() string {
 // Default returns a Config populated with sensible default values.
 func Default() *Config {
 	return &Config{
+		ConfigVersion:           currentConfigVersion,
 		DefaultShell:            "",
 		DefaultTerminal:         "",
 		DefaultTimeRange:        "1d",
@@ -282,6 +316,9 @@ func Load() (*Config, error) {
 	}
 
 	cfg := Default() // start from defaults so missing keys keep their default
+	// Reset ConfigVersion to 0 before unmarshal so that old configs lacking
+	// the field are detected as version 0 (needing migration).
+	cfg.ConfigVersion = 0
 	if err := json.Unmarshal(data, cfg); err != nil {
 		return nil, fmt.Errorf("parsing config: %w", err)
 	}
@@ -294,6 +331,14 @@ func Load() (*Config, error) {
 	}
 	cfg.sanitize()
 
+	// Migrate old config schemas forward. If the version changed, persist
+	// the upgraded config so future loads skip migration.
+	if cfg.ConfigVersion < currentConfigVersion {
+		migrate(cfg)
+		cfg.ConfigVersion = currentConfigVersion
+		_ = Save(cfg) // best-effort; don't fail Load on write errors
+	}
+
 	// Allow env var override for workspace recovery (used by --demo).
 	if os.Getenv("DISPATCH_WORKSPACE_RECOVERY") == "1" {
 		cfg.WorkspaceRecovery = true
@@ -302,6 +347,19 @@ func Load() (*Config, error) {
 	return cfg, nil
 }
 
+// migrate applies all necessary transformations to bring an old config up to
+// the current schema version. Each version bump should have a case here that
+// transforms fields from the old layout to the new one, preserving user intent.
+func migrate(cfg *Config) {
+	// v0 → v1: LaunchInPlace (bool) was replaced by LaunchMode (string).
+	// If the user had LaunchInPlace=true but LaunchMode is unset, populate it.
+	if cfg.ConfigVersion < 1 {
+		if cfg.LaunchInPlace && cfg.LaunchMode == "" {
+			cfg.LaunchMode = LaunchModeInPlace
+		}
+	}
+}
+
 // shellUnsafe contains characters that must never appear in shell or terminal
 // names because they could be interpreted by command interpreters (cmd.exe,
 // bash, PowerShell, AppleScript). Values containing any of these are cleared

internal/config/config_test.go

@@ -2,6 +2,7 @@ package config
 
 import (
 	"encoding/json"
+	"fmt"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -16,6 +17,9 @@ func TestDefaultValues(t *testing.T) {
 	t.Parallel()
 	cfg := Default()
 
+	if cfg.ConfigVersion != currentConfigVersion {
+		t.Errorf("ConfigVersion = %d, want %d", cfg.ConfigVersion, currentConfigVersion)
+	}
 	if cfg.DefaultShell != "" {
 		t.Errorf("DefaultShell = %q, want empty", cfg.DefaultShell)
 	}
@@ -77,6 +81,7 @@ func TestConfigJSONRoundTrip(t *testing.T) {
 		DefaultTerminal:  "alacritty",
 		DefaultTimeRange: "7d",
 		DefaultSort:      "created",
+		DefaultSortOrder: "asc",
 		DefaultPivot:     "repo",
 		ShowPreview:      false,
 		MaxSessions:      50,
@@ -112,6 +117,9 @@ func TestConfigJSONRoundTrip(t *testing.T) {
 	if restored.DefaultSort != original.DefaultSort {
 		t.Errorf("DefaultSort = %q, want %q", restored.DefaultSort, original.DefaultSort)
 	}
+	if restored.DefaultSortOrder != original.DefaultSortOrder {
+		t.Errorf("DefaultSortOrder = %q, want %q", restored.DefaultSortOrder, original.DefaultSortOrder)
+	}
 	if restored.DefaultPivot != original.DefaultPivot {
 		t.Errorf("DefaultPivot = %q, want %q", restored.DefaultPivot, original.DefaultPivot)
 	}
@@ -1171,3 +1179,164 @@ func TestPreviewPositionConstants(t *testing.T) {
 		t.Errorf("PreviewPositionTop = %q, want 'top'", PreviewPositionTop)
 	}
 }
+
+func TestEffectiveSortOrder_DefaultsToDesc(t *testing.T) {
+	t.Parallel()
+	cfg := Default()
+	if got := cfg.EffectiveSortOrder(); got != SortOrderDesc {
+		t.Errorf("EffectiveSortOrder() = %q, want %q", got, SortOrderDesc)
+	}
+}
+
+func TestEffectiveSortOrder_RespectsAsc(t *testing.T) {
+	t.Parallel()
+	cfg := Default()
+	cfg.DefaultSortOrder = SortOrderAsc
+	if got := cfg.EffectiveSortOrder(); got != SortOrderAsc {
+		t.Errorf("EffectiveSortOrder() = %q, want %q", got, SortOrderAsc)
+	}
+}
+
+func TestEffectiveSortOrder_InvalidFallsBackToDesc(t *testing.T) {
+	t.Parallel()
+	cfg := Default()
+	cfg.DefaultSortOrder = "invalid"
+	if got := cfg.EffectiveSortOrder(); got != SortOrderDesc {
+		t.Errorf("EffectiveSortOrder() = %q, want %q", got, SortOrderDesc)
+	}
+}
+
+func TestDefaultSortOrderOmittedFromJSON(t *testing.T) {
+	t.Parallel()
+	cfg := Default()
+	data, err := json.Marshal(cfg)
+	if err != nil {
+		t.Fatalf("Marshal: %v", err)
+	}
+	var raw map[string]any
+	if err := json.Unmarshal(data, &raw); err != nil {
+		t.Fatalf("Unmarshal: %v", err)
+	}
+	if _, ok := raw["default_sort_order"]; ok {
+		t.Error("default_sort_order should be omitted from JSON when empty")
+	}
+}
+
+func TestDefaultSortOrderPreservedOnLoad(t *testing.T) {
+	t.Parallel()
+	jsonData := `{"default_sort_order": "asc"}`
+	cfg := Default()
+	if err := json.Unmarshal([]byte(jsonData), cfg); err != nil {
+		t.Fatalf("Unmarshal: %v", err)
+	}
+	if cfg.DefaultSortOrder != SortOrderAsc {
+		t.Errorf("DefaultSortOrder = %q, want %q", cfg.DefaultSortOrder, SortOrderAsc)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Config version and migration tests
+// ---------------------------------------------------------------------------
+
+func TestDefaultConfigVersion(t *testing.T) {
+	t.Parallel()
+	cfg := Default()
+	if cfg.ConfigVersion != currentConfigVersion {
+		t.Errorf("ConfigVersion = %d, want %d", cfg.ConfigVersion, currentConfigVersion)
+	}
+}
+
+func TestMigrate_V0LaunchInPlaceToLaunchMode(t *testing.T) {
+	t.Parallel()
+	cfg := &Config{
+		ConfigVersion: 0,
+		LaunchInPlace: true,
+	}
+	migrate(cfg)
+	if cfg.LaunchMode != LaunchModeInPlace {
+		t.Errorf("LaunchMode = %q, want %q", cfg.LaunchMode, LaunchModeInPlace)
+	}
+}
+
+func TestMigrate_V0LaunchInPlaceSkippedWhenLaunchModeSet(t *testing.T) {
+	t.Parallel()
+	cfg := &Config{
+		ConfigVersion: 0,
+		LaunchInPlace: true,
+		LaunchMode:    LaunchModeTab,
+	}
+	migrate(cfg)
+	if cfg.LaunchMode != LaunchModeTab {
+		t.Errorf("LaunchMode = %q, want %q (should not be overwritten)", cfg.LaunchMode, LaunchModeTab)
+	}
+}
+
+func TestLoad_MigratesAndPersistsVersion(t *testing.T) {
+	dir := withTempConfigDir(t)
+
+	// Write a v0 config (no config_version field).
+	path := filepath.Join(dir, "dispatch", configFileName)
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	content := `{"launchInPlace": true, "default_shell": "fish"}`
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+
+	// Migration should have run.
+	if cfg.LaunchMode != LaunchModeInPlace {
+		t.Errorf("LaunchMode = %q, want %q after migration", cfg.LaunchMode, LaunchModeInPlace)
+	}
+	// User settings should be preserved.
+	if cfg.DefaultShell != "fish" {
+		t.Errorf("DefaultShell = %q, want 'fish' (should survive migration)", cfg.DefaultShell)
+	}
+	// Version should be updated.
+	if cfg.ConfigVersion != currentConfigVersion {
+		t.Errorf("ConfigVersion = %d, want %d", cfg.ConfigVersion, currentConfigVersion)
+	}
+
+	// File should have been re-written with the new version.
+	reloaded, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile after migration: %v", err)
+	}
+	var raw map[string]any
+	if err := json.Unmarshal(reloaded, &raw); err != nil {
+		t.Fatalf("Unmarshal re-written config: %v", err)
+	}
+	if v, ok := raw["config_version"]; !ok || int(v.(float64)) != currentConfigVersion {
+		t.Errorf("Persisted config_version = %v, want %d", v, currentConfigVersion)
+	}
+}
+
+func TestLoad_SkipsMigrationWhenCurrent(t *testing.T) {
+	dir := withTempConfigDir(t)
+
+	// Write a current-version config.
+	path := filepath.Join(dir, "dispatch", configFileName)
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	content := fmt.Sprintf(`{"config_version": %d, "default_shell": "zsh"}`, currentConfigVersion)
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.DefaultShell != "zsh" {
+		t.Errorf("DefaultShell = %q, want 'zsh'", cfg.DefaultShell)
+	}
+	if cfg.ConfigVersion != currentConfigVersion {
+		t.Errorf("ConfigVersion = %d, want %d", cfg.ConfigVersion, currentConfigVersion)
+	}
+}