Upgrade toml to v1.6.0 with metadata validation and enhanced error reporting

[Copilot]

Plan: Implement BurntSushi/toml Module Improvements

Priority 1: Core Improvements ✅ COMPLETED

• Upgrade toml dependency from v1.5.0 to v1.6.0
• Capture and use metadata in LoadFromFile for validation
• Add better error context with line numbers from ParseError
• Add explicit struct tags to all Config structs
• Fix deprecated ParseError.Line usage (use Position.Line)

Priority 2: Enhanced Validation ✅ COMPLETED

• Add strict mode to detect unknown configuration keys (with warnings)
• Create comprehensive config.example.toml with documentation

Testing & Verification ✅ COMPLETED

• Create/update tests for metadata validation (7 new tests)
• Create/update tests for error context
• Run all tests to ensure no breaking changes (all pass)
• Run make agent-finished for final verification (all pass)
• Fix linting errors (staticcheck SA1019)

Summary of Changes

Files Modified

• go.mod/go.sum: Upgraded github.com/BurntSushi/toml from v1.5.0 to v1.6.0
• internal/config/config.go:
  • Added explicit toml: struct tags to all Config, GatewayConfig, and ServerConfig fields
  • Enhanced LoadFromFile to capture metadata and detect unknown keys
  • Improved error handling with line number reporting using pErr.Position.Line (fixed deprecated API)
• internal/config/config_test.go: Added 7 comprehensive tests for LoadFromFile functionality
• config.example.toml: Created comprehensive configuration example with detailed documentation

Key Improvements

1. TOML 1.1 Support: Upgraded to v1.6.0 with better duplicate key detection, large float encoding fixes, and improved error handling
2. Typo Detection: Unknown configuration keys now trigger warnings (e.g., servrrs vs servers)
3. Better Error Messages: Parse errors now include line numbers for easy debugging
4. Explicit Struct Tags: All config fields now have explicit toml: tags to prevent breaking changes from field refactoring
5. Comprehensive Documentation: config.example.toml provides complete reference with comments and examples
6. API Compliance: Fixed deprecated ParseError.Line usage per staticcheck SA1019

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[go-fan] Go Module Review: github.com/BurntSushi/toml</issue_title>
<issue_description># 🐹 Go Fan Report: BurntSushi/toml

Module Overview

The BurntSushi/toml package is Go's most popular TOML parser with 4,885+ stars, providing a reflection-based interface similar to json and xml from the standard library. It implements the TOML 1.1 specification for simple, idiomatic configuration file parsing.

Current Usage in gh-aw-mcpg

The project uses this module for configuration file parsing, specifically in internal/config/config.go:

• Files: 1 file (internal/config/config.go)
• Import Count: Single focused import
• Key APIs Used: toml.DecodeFile(path, &cfg) for TOML → struct mapping

Current Implementation:

if _, err := toml.DecodeFile(path, &cfg); err != nil {
    return nil, fmt.Errorf("failed to decode TOML: %w", err)
}

The module is used correctly but discards metadata that could enable validation and better error messages.

Research Findings

Recent Updates

Latest Version: v1.6.0 (December 18, 2025) - We're using v1.5.0 ⚠️

What's New in v1.6.0

1. ✅ TOML 1.1 enabled by default - More lenient parsing (newlines in inline tables, trailing commas)
2. ✅ Duplicate array key detection - Better error messages
3. ✅ Large float encoding fixes - Correct round-tripping for scientific notation
4. ✅ Improved error handling - Better position tracking

Best Practices from Maintainers

1. Capture metadata - Use the Meta return value for validation
2. Use struct tags - Explicit toml: tags for all fields
3. Check undecoded keys - Detect typos with Meta.Undecoded()
4. Preserve error context - Include line/column numbers from ParseError
5. Export private fields - Only exported struct fields are decoded

Improvement Opportunities

🏃 Quick Wins (High Impact, Low Effort)

1. Upgrade to v1.6.0 for TOML 1.1 Support

Current: v1.5.0
Action: go get github.com/BurntSushi/toml@v1.6.0

Benefits:

• TOML 1.1 by default (trailing commas, newlines in inline tables)
• Better duplicate key detection
• Scientific notation round-tripping fixes
• Latest bug fixes and improvements

Impact: More flexible configuration files, better error messages

2. Capture and Use Metadata for Validation

Current: Metadata discarded with _
Recommended:

meta, err := toml.DecodeFile(path, &cfg)
if err != nil {
    return nil, fmt.Errorf("failed to decode TOML: %w", err)
}
// Validate: check for typos, unknown keys
if len(meta.Undecoded()) > 0 {
    log.Printf("Warning: unknown config keys: %v", meta.Undecoded())
}

Benefits:

• Catch typos in config files (servrrs vs servers)
• Validate required vs optional fields
• Better user feedback

Files: internal/config/config.go:80

3. Improve Error Context with Line Numbers

Current: Generic "failed to decode TOML" error
Recommended:

if _, err := toml.DecodeFile(path, &cfg); err != nil {
    if pErr, ok := err.(toml.ParseError); ok {
        return nil, fmt.Errorf("TOML parse error at line %d: %w", pErr.Line, err)
    }
    return nil, fmt.Errorf("failed to decode TOML: %w", err)
}

Benefits: Users get exact line numbers for syntax errors

✨ Feature Opportunities (Medium Impact, Medium Effort)

4. Add Strict Mode for Typo Detection

Use Meta.Undecoded() to detect unknown configuration keys:

if len(meta.Undecoded()) > 0 {
    return nil, fmt.Errorf("unknown config keys: %v", meta.Undecoded())
}

Benefit: Fail fast on configuration typos

5. Add TOML Export Capability

Currently the project only reads TOML. Add marshaling for:

• Config file generation
• Config template creation
• Runtime config dumps

func SaveToFile(cfg *Config, path string) error {
    f, err := os.Create(path)
    if err != nil {
        return err
    }
    defer f.Close()
    return toml.NewEncoder(f).Encode(cfg)
}

📐 Best Practice Alignment

6. Add Explicit Struct Tags

Current: Relies on automatic case matching
Recommended: Explicit toml: tags for all fields

Why: Prevents breaking changes from field name refactoring

Example:

type GatewayConfig struct {
    Port           int    `toml:"port"`
    APIKey         string `toml:"api_key"`
    Domain         string `toml:"domain"`
    StartupTimeout int    `toml:"startup_timeout"`
    ToolTimeout    int    `toml:"tool_timeout"`
}

Files to update: internal/config/config.go (Config, GatewayConfig, ServerConfig)

7. Create Comprehensive Config Example

Current: Config structure only in Go code
Recommended: Create config.example.toml with:

• All available fields documented
• Comments explaining each option
• Example values
• Required vs optional markers

🔧 General Improvements

#...

• Fixes [go-fan] Go Module Review: github.com/BurntSushi/toml #374

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[lpcox]

@copilot please fix this linting error

Running [/home/runner/golangci-lint-2.8.0-linux-amd64/golangci-lint run --timeout=5m] in [/home/runner/work/gh-aw-mcpg/gh-aw-mcpg] ...
Error: internal/config/config.go:84:62: SA1019: pErr.Line is deprecated: use [Position]. (staticcheck)
return nil, fmt.Errorf("TOML parse error at line %d: %w", pErr.Line, err)
^
1 issues:

• staticcheck: 1

Error: issues found
Ran golangci-lint in 8359ms

[Copilot]

@copilot please fix this linting error

Running [/home/runner/golangci-lint-2.8.0-linux-amd64/golangci-lint run --timeout=5m] in [/home/runner/work/gh-aw-mcpg/gh-aw-mcpg] ...
...

Fixed in commit 7164555. Changed pErr.Line to pErr.Position.Line to use the non-deprecated API. The linter now passes with 0 issues, and all tests still pass with line numbers correctly displayed in error messages.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• this-host-does-not-exist-12345.com
  • Triggering command: /tmp/go-build3749762128/b278/mcp.test /tmp/go-build3749762128/b278/mcp.test -test.testlogfile=/tmp/go-build3749762128/b278/testlog.txt -test.paniconexit0 -test.timeout=10m0s -test.v=true ache/go/1.25.5/x64/src/runtime/c-symabis ache/go/1.25.5/x64/src/internal//tmp/go-build1957267144/b239/symabis x_amd64/vet (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)