Add ConfigResolver for external config source support

Introduce ConfigResolver function type and ConfigProvider interface
for loading flag values from external sources (JSON, YAML, TOML, etc.).
Refactor flag pipeline into applyDefaults, applyConfig, applyEnv steps
with priority: explicit flag > env > config > default > zero. Add config
subpackage with FromMap, FromJSON (io.Reader), and Chain helpers.

Author: bjaus

cli.go

@@ -27,6 +27,7 @@ type options struct {
 	stderr              io.Writer
 	flagParser          FlagParser
 	helpRenderer        HelpRenderer
+	configResolver      ConfigResolver
 	suggest             bool
 	shortOptionHandling bool
 	prefixMatching      bool
@@ -78,6 +79,13 @@ func WithPrefixMatching(enabled bool) Option {
 	return func(o *options) { o.prefixMatching = enabled }
 }
 
+// WithConfigResolver sets a global config resolver for flag values.
+// Config values have lower priority than env vars and explicit CLI flags,
+// but higher priority than defaults: explicit flag > env > config > default > zero.
+func WithConfigResolver(r ConfigResolver) Option {
+	return func(o *options) { o.configResolver = r }
+}
+
 // Execute runs the command tree rooted at root with the given args and options.
 // It resolves subcommands, parses flags, runs lifecycle hooks, and executes
 // the target command.

config/config.go

@@ -0,0 +1,127 @@
+// Package config provides [cli.ConfigResolver] implementations for common
+// configuration sources.
+//
+// A [cli.ConfigResolver] is a function that maps flag names to string values.
+// The cli framework handles type conversion, validation, required checks, and
+// enum enforcement — resolvers only return strings. This package ships
+// format-agnostic building blocks; any source that can produce a
+// map[string]string works out of the box via [FromMap].
+//
+// Priority chain: explicit CLI flag > env var > config > default > zero value.
+//
+// # Provided resolvers
+//
+//   - [FromMap] — backed by a string map (useful for testing, in-memory config, or as the building block for custom formats)
+//   - [FromJSON] — decodes a flat JSON object from an [io.Reader]
+//   - [Chain] — tries multiple resolvers in order, returning the first match
+//
+// # Custom format adapters
+//
+// Because [FromMap] accepts any map[string]string, adding support for a new
+// configuration format is a matter of decoding into a flat map. The examples
+// below are complete, copy-paste-ready adapters.
+//
+// YAML (using gopkg.in/yaml.v3):
+//
+//	func FromYAML(r io.Reader) (cli.ConfigResolver, error) {
+//	    var m map[string]string
+//	    if err := yaml.NewDecoder(r).Decode(&m); err != nil {
+//	        return nil, err
+//	    }
+//	    return config.FromMap(m), nil
+//	}
+//
+// TOML (using github.com/BurntSushi/toml):
+//
+//	func FromTOML(r io.Reader) (cli.ConfigResolver, error) {
+//	    var m map[string]string
+//	    if _, err := toml.NewDecoder(r).Decode(&m); err != nil {
+//	        return nil, err
+//	    }
+//	    return config.FromMap(m), nil
+//	}
+//
+// HCL (using github.com/hashicorp/hcl/v2):
+//
+//	func FromHCL(r io.Reader) (cli.ConfigResolver, error) {
+//	    data, err := io.ReadAll(r)
+//	    if err != nil { return nil, err }
+//	    var m map[string]string
+//	    if err := hcl.Unmarshal(data, &m); err != nil {
+//	        return nil, err
+//	    }
+//	    return config.FromMap(m), nil
+//	}
+//
+// .env files (using github.com/joho/godotenv):
+//
+//	func FromDotenv(r io.Reader) (cli.ConfigResolver, error) {
+//	    m, err := godotenv.Parse(r)
+//	    if err != nil { return nil, err }
+//	    return config.FromMap(m), nil
+//	}
+//
+// # Direct resolver functions
+//
+// For sources that don't map cleanly to a flat file (remote stores,
+// structured configs, or computed values), implement [cli.ConfigResolver]
+// directly:
+//
+//	// Consul KV adapter
+//	func FromConsul(client *consul.Client, prefix string) cli.ConfigResolver {
+//	    return func(flagName string) (string, bool) {
+//	        pair, _, err := client.KV().Get(prefix+"/"+flagName, nil)
+//	        if err != nil || pair == nil { return "", false }
+//	        return string(pair.Value), true
+//	    }
+//	}
+//
+// # Layered configuration
+//
+// Use [Chain] to try multiple sources in priority order. The first resolver
+// that finds a value wins:
+//
+//	resolver := config.Chain(
+//	    localOverrides,   // highest priority config source
+//	    projectConfig,    // project-level config
+//	    globalConfig,     // user-level defaults
+//	)
+package config
+
+import (
+	"encoding/json"
+	"io"
+
+	"github.com/bjaus/cli"
+)
+
+// FromMap returns a [cli.ConfigResolver] backed by a string map.
+func FromMap(m map[string]string) cli.ConfigResolver {
+	return func(flagName string) (string, bool) {
+		v, ok := m[flagName]
+		return v, ok
+	}
+}
+
+// FromJSON decodes a flat JSON object from r and returns a [cli.ConfigResolver].
+// The JSON must be a flat object with string values: {"port": "8080"}.
+func FromJSON(r io.Reader) (cli.ConfigResolver, error) {
+	var m map[string]string
+	if err := json.NewDecoder(r).Decode(&m); err != nil {
+		return nil, err
+	}
+	return FromMap(m), nil
+}
+
+// Chain returns a [cli.ConfigResolver] that tries each resolver in order,
+// returning the value from the first resolver that reports found.
+func Chain(resolvers ...cli.ConfigResolver) cli.ConfigResolver {
+	return func(flagName string) (string, bool) {
+		for _, r := range resolvers {
+			if v, ok := r(flagName); ok {
+				return v, true
+			}
+		}
+		return "", false
+	}
+}

config/config_test.go

@@ -0,0 +1,78 @@
+package config_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/bjaus/cli/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestFromMap(t *testing.T) {
+	t.Parallel()
+
+	m := map[string]string{"port": "8080", "host": "localhost"}
+	resolver := config.FromMap(m)
+
+	val, ok := resolver("port")
+	assert.True(t, ok)
+	assert.Equal(t, "8080", val)
+
+	val, ok = resolver("host")
+	assert.True(t, ok)
+	assert.Equal(t, "localhost", val)
+
+	_, ok = resolver("missing")
+	assert.False(t, ok)
+}
+
+func TestFromJSON(t *testing.T) {
+	t.Parallel()
+
+	t.Run("valid reader", func(t *testing.T) {
+		t.Parallel()
+
+		r := strings.NewReader(`{"port": "9090", "host": "0.0.0.0"}`)
+		resolver, err := config.FromJSON(r)
+		require.NoError(t, err)
+
+		val, ok := resolver("port")
+		assert.True(t, ok)
+		assert.Equal(t, "9090", val)
+
+		_, ok = resolver("missing")
+		assert.False(t, ok)
+	})
+
+	t.Run("invalid JSON", func(t *testing.T) {
+		t.Parallel()
+
+		r := strings.NewReader(`{not json`)
+		_, err := config.FromJSON(r)
+		require.Error(t, err)
+	})
+}
+
+func TestChain(t *testing.T) {
+	t.Parallel()
+
+	first := config.FromMap(map[string]string{"port": "1111"})
+	second := config.FromMap(map[string]string{"port": "2222", "host": "second"})
+
+	chained := config.Chain(first, second)
+
+	// First match wins.
+	val, ok := chained("port")
+	assert.True(t, ok)
+	assert.Equal(t, "1111", val)
+
+	// Falls through to second.
+	val, ok = chained("host")
+	assert.True(t, ok)
+	assert.Equal(t, "second", val)
+
+	// No match.
+	_, ok = chained("missing")
+	assert.False(t, ok)
+}

doc.go

@@ -67,7 +67,7 @@
 //   - counter — "true" to increment an int on each occurrence (-vvv)
 //   - negatable — "true" to add a --no- prefix that sets a bool to false
 //
-// Priority: explicit flag > env var > default > zero value.
+// Priority: explicit flag > env var > config > default > zero value.
 //
 // Flags can appear anywhere — before or after subcommand names.
 //
@@ -101,6 +101,48 @@
 // Priority for automatic flag inheritance:
 // explicit child flag > child env var > inherited from parent > child default > zero value.
 //
+// # Config
+//
+// Flag values can be loaded from external configuration sources via a
+// [ConfigResolver]. A resolver is a single function:
+//
+//	type ConfigResolver func(flagName string) (value string, found bool)
+//
+// Given a flag name, it returns the string value and whether it was found.
+// The framework handles all type conversion, validation, required checks,
+// and enum enforcement — the resolver only needs to return strings.
+//
+// Priority chain: explicit CLI flag > env var > config > default > zero value.
+//
+// Set a global resolver via [WithConfigResolver]:
+//
+//	f, _ := os.Open("config.json")
+//	resolver, _ := config.FromJSON(f)
+//	cli.Execute(ctx, root, os.Args[1:],
+//	    cli.WithConfigResolver(resolver),
+//	)
+//
+// Or implement [ConfigProvider] on a command for per-command resolvers:
+//
+//	func (c *ServeCmd) ConfigResolver() cli.ConfigResolver {
+//	    return config.FromMap(map[string]string{"port": "9090"})
+//	}
+//
+// Command-level resolvers take priority over the global resolver. Use
+// [config.Chain] to try multiple sources in order:
+//
+//	resolver := config.Chain(
+//	    config.FromMap(overrides),
+//	    jsonResolver,
+//	)
+//
+// The [config] subpackage ships [config.FromMap], [config.FromJSON], and
+// [config.Chain]. Because [ConfigResolver] is a plain function and
+// [config.FromMap] accepts any map[string]string, adding support for any
+// configuration format — YAML, TOML, HCL, .env files, remote stores —
+// is a matter of decoding into a map and calling [config.FromMap].
+// See the [config] package documentation for copy-paste adapter examples.
+//
 // # Extensibility
 //
 // Every major subsystem is replaceable:

example_test.go

@@ -529,3 +529,57 @@ func ExampleExecute_inheritTag() {
 	_ = cli.Execute(context.Background(), app, []string{"--env", "staging", "serve"}, cli.WithStdout(os.Stdout)) //nolint:errcheck // example
 	// Output: env=staging port=8080
 }
+
+// ConfigResolver loads flag values from an external source.
+// Config values sit between defaults and env vars in priority:
+// explicit flag > env > config > default > zero.
+type ConfigServeCmd struct {
+	Port int    `flag:"port" default:"8080" help:"Listen port"`
+	Host string `flag:"host" default:"localhost" help:"Host to bind to"`
+}
+
+func (c *ConfigServeCmd) Run(_ context.Context, _ []string) error {
+	fmt.Fprintf(os.Stdout, "host=%s port=%d\n", c.Host, c.Port) //nolint:errcheck // example output
+	return nil
+}
+
+func ExampleExecute_configResolver() {
+	resolver := cli.ConfigResolver(func(flagName string) (string, bool) {
+		m := map[string]string{"port": "9090", "host": "0.0.0.0"}
+		v, ok := m[flagName]
+		return v, ok
+	})
+
+	cmd := &ConfigServeCmd{}
+	_ = cli.Execute(context.Background(), cmd, nil, //nolint:errcheck // example
+		cli.WithStdout(os.Stdout),
+		cli.WithConfigResolver(resolver),
+	)
+	// Output: host=0.0.0.0 port=9090
+}
+
+// ConfigProvider lets a command supply its own resolver.
+// The command-level resolver takes priority over the global one.
+type ConfigProviderCmd struct {
+	Port int `flag:"port" default:"8080" help:"Listen port"`
+}
+
+func (c *ConfigProviderCmd) Run(_ context.Context, _ []string) error {
+	fmt.Fprintf(os.Stdout, "port=%d\n", c.Port) //nolint:errcheck // example output
+	return nil
+}
+
+func (c *ConfigProviderCmd) ConfigResolver() cli.ConfigResolver {
+	return func(flagName string) (string, bool) {
+		if flagName == "port" {
+			return "3000", true
+		}
+		return "", false
+	}
+}
+
+func ExampleExecute_configProvider() {
+	cmd := &ConfigProviderCmd{}
+	_ = cli.Execute(context.Background(), cmd, nil, cli.WithStdout(os.Stdout)) //nolint:errcheck // example
+	// Output: port=3000
+}

execute.go

@@ -443,7 +443,7 @@ func parseFlags(cmd Runner, args []string, opts *options) ([]string, map[string]
 		remaining, err := opts.flagParser.ParseFlags(cmd, args)
 		return remaining, nil, err
 	}
-	return defaultParseFlags(cmd, args)
+	return defaultParseFlags(cmd, args, opts)
 }
 
 func runAfterHooks(ctx context.Context, hooks []Runner) error {