[go-fan] Go Module Review: BurntSushi/toml

[github-actions]

🐹 Go Fan Report: BurntSushi/toml

Module Overview

github.com/BurntSushi/toml (v1.6.0) is the project's TOML configuration parser. It implements the TOML 1.1 spec with streaming decoding, rich error reporting (line + column + source snippet), metadata-based unknown-field detection, and bidirectional marshaling.

The project is on the latest version (v1.6.0, released 2025-12-18). ✅

Current Usage in gh-aw-mcpg

• Files: 1 file — internal/config/config_core.go
• Import Count: 1 import
• Key APIs Used:
  • toml.NewDecoder(file) — streaming decoder (good for memory efficiency)
  • decoder.Decode(&cfg) — fills struct, returns MetaData
  • md.Undecoded() — warns on unknown config keys (typo detection)
  • toml.ParseError — value-type error wrapped with %w to surface full rich source context via ParseError.Error()

The core TOML parsing is well-implemented: streaming decode, correct value-type ParseError assertion, %w-based wrapping that naturally exposes the rich column-pointer error output, and Undecoded() for non-fatal typo warnings. No issues with the toml API usage itself.

Research Findings

Recent Updates (v1.6.0 — 2025-12-18)

• TOML 1.1 enabled by default (multi-line inline arrays, stricter duplicate key detection)
• Fixed large float encoding for round-trip correctness
• The project is already on this version ✅

Best Practices

• ParseError.Error() returns a formatted snippet with ^-pointer to the error column — the project correctly leverages this via %w wrapping rather than manually reformatting.
• Undecoded() for unknown field warnings is the recommended approach for config files where strict validation would be too brittle.

Improvement Opportunities

🏃 Quick Wins

1. Stray duplicate log.Printf in config_stdin.go:374

The HTTP-server conversion path logs the same message twice in quick succession:

// config_stdin.go ~line 373
logConfig.Printf("Configured HTTP MCP server: name=%s, url=%s", name, server.URL)
log.Printf("[CONFIG] Configured HTTP MCP server: %s -> %s", name, server.URL)  // <-- spurious duplicate

The second log.Printf writes to the global standard logger (always-on stderr), leaking an extra unformatted log line for every HTTP MCP server configured via stdin. It should be removed along with the now-unnecessary "log" import in that file.

2. Migrate logConfig from legacy log.New to logger.New

config_core.go defines its debug logger using the old pattern:

var logConfig = log.New(io.Discard, "[CONFIG] ", log.LstdFlags)

func SetDebug(enabled bool) {
    if enabled {
        logConfig = log.New(os.Stderr, "[CONFIG] ", log.LstdFlags)
    } else {
        logConfig = log.New(io.Discard, "[CONFIG] ", log.LstdFlags)
    }
}

Every other file in the config package already uses the project's standard framework:

File	Logger
validation.go	logger.New("config:validation")
validation_env.go	logger.New("config:validation_env")
config_feature.go	logger.New("config:feature")
guard_policy.go	logger.New("config:guard_policy")
validation_schema.go	logger.New("config:validation_schema")
config_stdin.go	logger.New("config:config_stdin") (for logStdin)
config_core.go	❌ log.New(io.Discard, ...)

Migrating to var logConfig = logger.New("config:config") and removing SetDebug would:

• Make DEBUG=config:* work consistently across the entire package
• Remove a redundant "log" and "io" import from config_core.go
• Eliminate the SetDebug API (currently only called in two test functions)

✨ Feature Opportunities

• toml.Marshal in test helpers: Tests write raw TOML string literals inline. Using toml.Marshal to generate TOML from struct values would make tests more maintainable and catch field-name drift at compile time.

📐 Best Practice Alignment

• The %w-wrapped ParseError is already correct and idiomatic — no changes needed.
• Undecoded() for unknown field warnings is the right balance.

Recommendations

1. [High] Remove the stray log.Printf on config_stdin.go:374 and the "log" import — tiny change, eliminates always-on log noise for every stdin HTTP server.
2. [Medium] Migrate config_core.go logger from log.New to logger.New("config:config"), remove SetDebug, and update the two test callsites that use it.

Next Steps

• Fix Configure as a Go CLI tool #1 in a quick PR (1-line removal)
• Fix Lpcox/initial implementation #2 as a follow-up refactor after confirming no external callers of SetDebug

---

Generated by Go Fan 🐹
Module summary saved to: specs/mods/toml.md (cache: /tmp/gh-aw/cache-memory/specs-mods-toml.md)

Note

🔒 Integrity filter blocked 10 items

The following items were blocked because they don't meet the GitHub integrity level.

• get_file_contents get_file_contents: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/BurntSushi/toml/releases/tag/v1.6.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/BurntSushi/toml/releases/tag/v1.5.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/BurntSushi/toml/releases/tag/v1.4.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/stretchr/testify/releases/tag/v1.11.1 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/stretchr/testify/releases/tag/v1.11.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/stretchr/testify/releases/tag/v1.10.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• list_tags list_tags: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• BurntSushi/toml@8685fba list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• stretchr/testify@5f80e4a list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Go Fan · ◷

• expires on Apr 1, 2026, 7:33 AM UTC