Loader, file resolution, and tests

// examples/viper/config/config.go (trimmed: Load, resolve, and Validate shown separately)
type Config struct {
	Server Server `mapstructure:"server"`
	Log    Log    `mapstructure:"log"`
	Token  string `mapstructure:"token"` // env or file only; never written back
}

type Server struct {
	Addr        string        `mapstructure:"addr"`
	Port        int           `mapstructure:"port"`
	ReadTimeout time.Duration `mapstructure:"read-timeout"`
	TLS         bool          `mapstructure:"tls"`
}

type Source struct {
	File  string         // explicit --config path; it must exist
	Dirs  []string       // searched in order for FileName; a miss is fine
	Flags *pflag.FlagSet // already parsed; only flags from AddFlags bind
}

var flagKeys = map[string]string{
	"addr":      "server.addr",
	"port":      "server.port",
	"tls":       "server.tls",
	"log-level": "log.level",
}

func AddFlags(fs *pflag.FlagSet) {
	fs.String("addr", defaults["server.addr"].(string), "listen address")
	fs.Int("port", defaults["server.port"].(int), "listen port")
	fs.Bool("tls", defaults["server.tls"].(bool), "serve TLS (needs APP_TOKEN)")
	fs.String("log-level", defaults["log.level"].(string), "debug, info, warn, or error")
}

var defaults = map[string]any{
	"server.addr":         "127.0.0.1",
	"server.port":         8080,
	"server.read-timeout": "5s",
	"server.tls":          false,
	"log.level":           "info",
}

// Keys without a default still need an environment binding, or Unmarshal
// never sees them.
var envOnly = []string{"token"}

// examples/viper/config/config.go (trimmed: resolve only)
func resolve(src Source) (string, error) {
	if src.File != "" {
		return src.File, nil
	}
	for _, dir := range src.Dirs {
		path := filepath.Join(dir, FileName)
		info, err := os.Stat(path)
		switch {
		case err == nil && !info.IsDir():
			return path, nil
		case err == nil, errors.Is(err, fs.ErrNotExist):
			continue
		default:
			return "", err // permission denied and the like are not a miss
		}
	}
	return "", nil
}

// excerpt: discovery with an optional file
v.SetConfigName("app")
v.AddConfigPath(dir)
if err := v.ReadInConfig(); err != nil {
	if _, missing := errors.AsType[viper.ConfigFileNotFoundError](err); !missing {
		return Config{}, err
	}
}

// examples/viper/config/config.go (trimmed: Validate only)
func (c Config) Validate() error {
	var errs []error
	if c.Server.Port < 1 || c.Server.Port > 65535 {
		errs = append(errs, fmt.Errorf("server.port %d is outside 1-65535", c.Server.Port))
	}
	if c.Server.ReadTimeout <= 0 {
		errs = append(errs, fmt.Errorf("server.read-timeout must be positive, got %s", c.Server.ReadTimeout))
	}
	switch c.Log.Level {
	case "debug", "info", "warn", "error":
	default:
		errs = append(errs, fmt.Errorf("log.level %q is not one of debug, info, warn, error", c.Log.Level))
	}
	if c.Server.TLS && c.Token == "" {
		errs = append(errs, errors.New("server.tls needs a token (set APP_TOKEN)"))
	}
	return errors.Join(errs...)
}

// examples/viper/cli/cli.go (trimmed: package clause and Serve type omitted)
func NewRoot(dirs []string, serve Serve) *cobra.Command {
	root := &cobra.Command{
		Use:           "app",
		Short:         "Serve the app",
		SilenceErrors: true,
		SilenceUsage:  true,
	}
	var file string
	root.PersistentFlags().StringVar(&file, "config", "", "config file (default: the first app.yaml in the search directories)")

	srv := &cobra.Command{
		Use:   "serve",
		Short: "Start the server",
		Args:  cobra.NoArgs,
		// Load here, not in a root PersistentPreRunE: Cobra runs the root
		// hook for `completion`, `__complete`, and `help <command>` too.
		RunE: func(cmd *cobra.Command, _ []string) error {
			cfg, err := config.Load(config.Source{File: file, Dirs: dirs, Flags: cmd.Flags()})
			if err != nil {
				return err
			}
			return serve(cmd.Context(), cfg)
		},
	}
	config.AddFlags(srv.Flags())
	if err := srv.RegisterFlagCompletionFunc("log-level", cobra.FixedCompletions(
		[]string{"debug", "info", "warn", "error"}, cobra.ShellCompDirectiveNoFileComp,
	)); err != nil {
		panic(err) // programming error: AddFlags registers log-level
	}
	root.AddCommand(srv)
	return root
}