Document auto-written TOML config files (#483)

## Summary
- switch global config writes to `go-toml/v2` so auto-written TOML can
include inline comments
- route `roborev config set` global and local writes through typed save
helpers so both `config.toml` and `.roborev.toml` get documented output
- update `roborev init --agent ...` to create a commented repo config
scaffold and add regression coverage for the global, local, and init
paths

## Test Plan
- go vet ./...
- go test ./...

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

Author: mariusvniekerk

cmd/roborev/config_cmd.go

@@ -5,11 +5,9 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
-	"reflect"
 	"strings"
 	"text/tabwriter"
 
-	"github.com/BurntSushi/toml"
 	"github.com/roborev-dev/roborev/internal/config"
 	"github.com/roborev-dev/roborev/internal/git"
 	"github.com/spf13/cobra"
@@ -384,27 +382,39 @@ func printKeyValues(kvs []config.KeyValue) {
 	}
 }
 
-// setConfigKey sets a key in a TOML file using raw map manipulation
-// to avoid writing default values for every field.
-// isGlobal determines which struct (Config vs RepoConfig) validates the key.
+// setConfigKey sets a key in a TOML config file.
 func setConfigKey(path, key, value string, isGlobal bool) error {
-	validationCfg, err := validateKeyForScope(key, value, isGlobal)
+	_, err := validateKeyForScope(key, value, isGlobal)
 	if err != nil {
 		return err
 	}
 
-	raw, err := loadRawConfig(path)
+	if isGlobal {
+		cfg, err := config.LoadGlobalFrom(path)
+		if err != nil {
+			return fmt.Errorf("parse %s: %w", path, err)
+		}
+		if err := config.SetConfigValue(cfg, key, value); err != nil {
+			return err
+		}
+		return config.SaveGlobalTo(path, cfg)
+	}
+
+	repoDir := filepath.Dir(path)
+	repoCfg, err := config.LoadRepoConfig(repoDir)
 	if err != nil {
+		return fmt.Errorf("parse %s: %w", path, err)
+	}
+	if repoCfg == nil {
+		repoCfg = &config.RepoConfig{}
+	}
+	if err := config.SetConfigValue(repoCfg, key, value); err != nil {
 		return err
 	}
-
-	setRawMapKey(raw, key, coerceValue(validationCfg, key, value))
-
-	return atomicWriteConfig(path, raw, isGlobal)
+	return config.SaveRepoConfigTo(path, repoCfg)
 }
 
-// validateKeyForScope validates a key against the appropriate config struct
-// and returns the populated struct for type coercion.
+// validateKeyForScope validates a key against the appropriate config scope.
 func validateKeyForScope(key, value string, isGlobal bool) (any, error) {
 	if isGlobal {
 		cfg := config.DefaultConfig()
@@ -429,72 +439,6 @@ func validateKeyForScope(key, value string, isGlobal bool) (any, error) {
 	return repoCfg, nil
 }
 
-// loadRawConfig loads an existing TOML file as a raw map, or returns
-// an empty map if the file doesn't exist.
-func loadRawConfig(path string) (map[string]any, error) {
-	raw := make(map[string]any)
-	if _, err := os.Stat(path); err == nil {
-		if _, err := toml.DecodeFile(path, &raw); err != nil {
-			return nil, fmt.Errorf("parse %s: %w", path, err)
-		}
-	}
-	return raw, nil
-}
-
-// atomicWriteConfig writes a config map to a TOML file atomically using
-// a temp file and rename. It creates parent directories as needed.
-func atomicWriteConfig(path string, raw map[string]any, isGlobal bool) error {
-	// Ensure directory exists. Use restrictive perms for the global config dir
-	// since it may contain secrets (API keys, DB credentials).
-	dirMode := os.FileMode(0755)
-	if isGlobal {
-		dirMode = 0700
-	}
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, dirMode); err != nil {
-		return err
-	}
-	// MkdirAll is a no-op for existing dirs. Tighten global config dir
-	// in case it was created with a permissive umask.
-	if isGlobal {
-		if err := os.Chmod(dir, dirMode); err != nil {
-			return err
-		}
-	}
-
-	// For global config, always enforce 0600 since it may contain secrets
-	// (API keys, DB credentials). Don't inherit existing permissions — the file
-	// may have been created manually with a permissive umask (0644).
-	// For repo config, preserve existing permissions (may be tracked in git).
-	var mode os.FileMode = 0644
-	if isGlobal {
-		mode = 0600
-	} else if info, err := os.Stat(path); err == nil {
-		mode = info.Mode()
-	}
-
-	f, err := os.CreateTemp(filepath.Dir(path), ".roborev-config-*.toml")
-	if err != nil {
-		return err
-	}
-	tmpPath := f.Name()
-	defer os.Remove(tmpPath)
-
-	if err := toml.NewEncoder(f).Encode(raw); err != nil {
-		f.Close()
-		return err
-	}
-	if err := f.Close(); err != nil {
-		return err
-	}
-
-	if err := os.Chmod(tmpPath, mode); err != nil {
-		return err
-	}
-
-	return os.Rename(tmpPath, path)
-}
-
 // setRawMapKey sets a value in a nested map using dot-separated keys.
 func setRawMapKey(m map[string]any, key string, value any) {
 	parts := strings.Split(key, ".")
@@ -525,47 +469,3 @@ func setRawMapKey(m map[string]any, key string, value any) {
 
 	current[parts[len(parts)-1]] = value
 }
-
-// coerceValue uses the typed config struct to determine the correct TOML type
-// for the given key's value.
-func coerceValue(validationCfg any, key, rawVal string) any {
-	v := reflect.ValueOf(validationCfg)
-	if v.Kind() == reflect.Ptr {
-		v = v.Elem()
-	}
-	field, err := config.FindFieldByTOMLKey(v, key)
-	if err != nil {
-		// Unreachable: key was already validated by SetConfigValue above.
-		// Fall back to raw string to avoid panicking on impossible paths.
-		return rawVal
-	}
-
-	switch field.Kind() {
-	case reflect.String:
-		return rawVal
-	case reflect.Bool:
-		return field.Bool()
-	case reflect.Int, reflect.Int64:
-		return field.Int()
-	case reflect.Slice:
-		if field.Type().Elem().Kind() == reflect.String {
-			result := make([]any, field.Len())
-			for i := 0; i < field.Len(); i++ {
-				result[i] = field.Index(i).String()
-			}
-			return result
-		}
-		return rawVal
-	case reflect.Ptr:
-		if field.IsNil() {
-			return rawVal
-		}
-		elem := field.Elem()
-		if elem.Kind() == reflect.Bool {
-			return elem.Bool()
-		}
-		return rawVal
-	default:
-		return rawVal
-	}
-}

cmd/roborev/config_cmd_test.go

@@ -425,6 +425,30 @@ func TestSetConfigKeyRepoConfig(t *testing.T) {
 	assertConfigValue(t, path, "agent", "claude-code")
 }
 
+func TestSetConfigKeyRepoConfigWritesComments(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, ".roborev.toml")
+
+	if err := setConfigKey(path, "agent", "claude-code", false); err != nil {
+		t.Fatalf("setConfigKey repo: %v", err)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	got := string(data)
+
+	for _, want := range []string{
+		"# Default agent for this repo when no workflow-specific agent is set.\n",
+		"agent = 'claude-code'",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("repo config missing %q:\n%s", want, got)
+		}
+	}
+}
+
 func TestSetConfigKeyRepoConfigRejectsGlobalACPSettings(t *testing.T) {
 	dir := t.TempDir()
 	path := filepath.Join(dir, ".roborev.toml")
@@ -438,6 +462,30 @@ func TestSetConfigKeyRepoConfigRejectsGlobalACPSettings(t *testing.T) {
 	}
 }
 
+func TestSetConfigKeyGlobalWritesComments(t *testing.T) {
+	path := setupConfigFile(t)
+
+	if err := setConfigKey(path, "default_agent", "codex", true); err != nil {
+		t.Fatalf("setConfigKey: %v", err)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	got := string(data)
+
+	for _, want := range []string{
+		"# Default agent when no workflow-specific agent is set.\n",
+		"default_agent = 'codex'",
+		"# Hide closed reviews by default in the TUI queue.\n",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("global config missing %q:\n%s", want, got)
+		}
+	}
+}
+
 func TestSetRawMapKey(t *testing.T) {
 	tests := []struct {
 		name string

cmd/roborev/hook_test.go

@@ -467,3 +467,40 @@ func TestInitNoDaemon(t *testing.T) {
 		})
 	}
 }
+
+func TestInitNoDaemonWithAgentCreatesCommentedRepoConfig(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("skipping on Windows due to shell script stubs")
+	}
+
+	repo := initNoDaemonSetup(t)
+	setupMockServer(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(200)
+	})
+
+	output := captureStdout(t, func() {
+		cmd := initCmd()
+		cmd.SetArgs([]string{"--no-daemon", "--agent", "codex"})
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("init failed: %v", err)
+		}
+	})
+
+	if !strings.Contains(output, "Created ") || !strings.Contains(output, ".roborev.toml") {
+		t.Fatalf("init output missing repo config creation message:\n%s", output)
+	}
+
+	data, err := os.ReadFile(filepath.Join(repo.Root, ".roborev.toml"))
+	if err != nil {
+		t.Fatalf("read repo config: %v", err)
+	}
+	got := string(data)
+	for _, want := range []string{
+		"# Default agent for this repo when no workflow-specific agent is set.\n",
+		"agent = 'codex'",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("repo config missing %q:\n%s", want, got)
+		}
+	}
+}

cmd/roborev/init_cmd.go

@@ -56,8 +56,8 @@ func initCmd() *cobra.Command {
 			repoConfigPath := filepath.Join(root, ".roborev.toml")
 			if agent != "" {
 				if _, err := os.Stat(repoConfigPath); os.IsNotExist(err) {
-					repoConfig := fmt.Sprintf("# roborev per-repo configuration\nagent = %q\n", agent)
-					if err := os.WriteFile(repoConfigPath, []byte(repoConfig), 0644); err != nil {
+					repoConfig := &config.RepoConfig{Agent: agent}
+					if err := config.SaveRepoConfigTo(repoConfigPath, repoConfig); err != nil {
 						return fmt.Errorf("create repo config: %w", err)
 					}
 					fmt.Printf("  Created %s\n", repoConfigPath)

flake.nix

@@ -19,7 +19,7 @@
 
             src = ./.;
 
-            vendorHash = "sha256-7meKrlC0b5N/TOrZJov/IQOs8FzhnNJ/3rnbDejtBKs=";
+            vendorHash = "sha256-HRVNiDpEoEFQZ7oMhGL+oAcqGdng4B14nTMebtBzufk=";
 
             subPackages = [ "cmd/roborev" ];
 

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/mattn/go-isatty v0.0.20
 	github.com/mattn/go-runewidth v0.0.20
 	github.com/muesli/termenv v0.16.0
+	github.com/pelletier/go-toml/v2 v2.2.4
 	github.com/sourcegraph/go-diff v0.7.0
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1

go.sum

@@ -101,6 +101,8 @@ github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=