Add format auto detection and format hint comments

README.md

@@ -34,6 +34,8 @@ Linux `.deb`, `.rpm`, and `.apk` packages, are in [INSTALL.md](INSTALL.md).
 - Set, unset, delete, and list values by dot path.
 - Replace, add, and remove scalar array values with `config array` in TOML,
   YAML, and JSON files.
+- Detect config formats for files with unknown extensions, with explicit
+  comment hints for ambiguous TOML/INI files.
 - Preserve comments and source formatting where possible.
 - Infer common value types such as numbers, booleans, nulls, and dates where
   the file format supports them.

cmd/cli.go

@@ -634,15 +634,15 @@ func runGet(opts getOptions, stdout io.Writer) error {
 	if err != nil {
 		return err
 	}
-	doc, _, err := format.Resolve(configFile)
+	source, err := os.ReadFile(configFile)
 	if err != nil {
 		return err
 	}
-
-	source, err := os.ReadFile(configFile)
+	doc, _, err := format.ResolveSource(configFile, source)
 	if err != nil {
 		return err
 	}
+
 	var value string
 	if opts.in != "" {
 		value, err = doc.GetIn(string(source), opts.in, opts.on, opts.key)
@@ -661,15 +661,15 @@ func runList(opts listOptions, stdout io.Writer) error {
 	if err != nil {
 		return err
 	}
-	doc, _, err := format.Resolve(configFile)
+	source, err := os.ReadFile(configFile)
 	if err != nil {
 		return err
 	}
-
-	source, err := os.ReadFile(configFile)
+	doc, _, err := format.ResolveSource(configFile, source)
 	if err != nil {
 		return err
 	}
+
 	entries, err := doc.List(string(source), opts.key)
 	if err != nil {
 		return err
@@ -683,15 +683,15 @@ func runDump(opts dumpOptions, stdout io.Writer) error {
 	if err != nil {
 		return err
 	}
-	doc, _, err := format.Resolve(configFile)
+	source, err := os.ReadFile(configFile)
 	if err != nil {
 		return err
 	}
-
-	source, err := os.ReadFile(configFile)
+	doc, _, err := format.ResolveSource(configFile, source)
 	if err != nil {
 		return err
 	}
+
 	value, err := doc.Dump(string(source), opts.key)
 	if err != nil {
 		return err
@@ -766,16 +766,16 @@ func runEdit(command, configFile string, dry, diff, color bool, stdout, stderr i
 		return err
 	}
 	log.Debug("resolved config file", "command", command, "path", configFile)
-	doc, formatName, err := format.Resolve(configFile)
+
+	source, err := os.ReadFile(configFile)
 	if err != nil {
 		return err
 	}
-	log.Debug("detected format", "format", formatName)
-
-	source, err := os.ReadFile(configFile)
+	doc, formatName, err := format.ResolveSource(configFile, source)
 	if err != nil {
 		return err
 	}
+	log.Debug("detected format", "format", formatName)
 	log.Debug("read config", "bytes", len(source))
 	updated, err := edit(doc, string(source))
 	if err != nil {

cmd/cli_get_list_test.go

@@ -96,7 +96,7 @@ func TestGetFailsWhenConfigFileIsNotSpecified(t *testing.T) {
 	}
 }
 
-func TestGetUnsupportedExplicitConfigFileReportsUnsupportedFormat(t *testing.T) {
+func TestGetAmbiguousUnknownExtensionReportsFormatHint(t *testing.T) {
 	clearConfigFileEnv(t)
 	var stdout, stderr bytes.Buffer
 	path := filepath.Join(t.TempDir(), "config.conf")
@@ -112,11 +112,47 @@ func TestGetUnsupportedExplicitConfigFileReportsUnsupportedFormat(t *testing.T)
 	if stdout.Len() != 0 {
 		t.Fatalf("stdout = %q", stdout.String())
 	}
-	if err.Error() != "unsupported config format for "+path {
+	if err.Error() != "ambiguous config format for "+path+"; add # format: toml or # format: ini" {
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
 
+func TestGetDetectsUnknownExtensionWithFormatHint(t *testing.T) {
+	clearConfigFileEnv(t)
+	var stdout, stderr bytes.Buffer
+	path := filepath.Join(t.TempDir(), "settings.conf")
+	if err := os.WriteFile(path, []byte("# format: ini\n[database]\nport = 5432\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	err := Execute([]string{"get", "-f", path, "database.port"}, "1.2.3", &stdout, &stderr)
+
+	if err != nil {
+		t.Fatalf("Execute returned error: %v", err)
+	}
+	if stdout.String() != "5432\n" {
+		t.Fatalf("stdout = %q", stdout.String())
+	}
+}
+
+func TestListDetectsConfigFileEnvWithUnknownExtension(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	path := filepath.Join(t.TempDir(), "settings.conf")
+	if err := os.WriteFile(path, []byte("# format: ini\n[database]\nport = 5432\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("CONFIG_FILE", path)
+
+	err := Execute([]string{"list", "database"}, "1.2.3", &stdout, &stderr)
+
+	if err != nil {
+		t.Fatalf("Execute returned error: %v", err)
+	}
+	if stdout.String() != "database.port=5432\n" {
+		t.Fatalf("stdout = %q", stdout.String())
+	}
+}
+
 func TestGetPrintsJSONValue(t *testing.T) {
 	var stdout, stderr bytes.Buffer
 	path := writeTempJSON(t, `{"database":{"port":5432}}`)

cmd/cli_help_test.go

@@ -110,6 +110,8 @@ func TestHelpCommandShowsFormatsTopic(t *testing.T) {
 	assertContains(t, stdout.String(), "Topic: formats")
 	assertContains(t, stdout.String(), "TOML")
 	assertContains(t, stdout.String(), ".json")
+	assertContains(t, stdout.String(), "Unknown extensions")
+	assertContains(t, stdout.String(), "# format: ini")
 	assertContains(t, stdout.String(), "canonical pretty JSON")
 }