Add clean parameter sections to samconfig.toml

[dcabib]

Problem

The current samconfig.toml parameter format is hard to work with:

• Single-line strings get very long and unreadable
• CLI parameters replace config completely (no merging)
• Complex escaping needed for arrays and special characters
• No multiline support for certificates or JSON configs

Solution

Added clean parameter sections to samconfig.toml:

New format:

• [env.command.parameters.template_parameters] for clean key-value pairs
• [env.command.parameters.template_tags] for tags
• Parameter merging: CLI adds to config instead of replacing
• File loading: load parameters from JSON/YAML/ENV files
• Multiline value support with TOML literal strings

Features

• Parameter merging (CLI parameters add to config parameters)
• External parameter files: file://params.json, file://params.yaml, file://params.env
• Multiline values for certificates, JSON configs, SQL queries
• Tag improvements with same clean format
• 100% backward compatible - old format still works

Implementation

Extended existing SamConfig class with new methods. Added ParameterMerger for smart merging and ParameterFileLoader for external files. All existing functionality preserved.

61 new tests added, all existing tests pass.

Closes #2253

[dcabib]

Which issue(s) does this change fix?

Closes #2253 - #2253

Why is this change necessary?

The current samconfig.toml parameter format is difficult to work with:

• Single-line strings become very long and unreadable
• Complex escaping needed for arrays and special characters
• No multiline support for certificates or JSON configurations
• CLI parameters replace config completely instead of merging
• Poor multi-environment parameter management

How does it address the issue?

This PR adds clean parameter sections to samconfig.toml:

1. New Clean Syntax:

[env.command.parameters.template_parameters]
Environment = "production"
DatabaseURL = "prod-db.example.com"
MaxConnections = "50"

[env.command.parameters.template_tags]
Project = "MyApp"
Team = "Engineering"

2. External File Loading:

parameter_overrides = ["file://params.json", "file://params.yaml", "file://params.env"]

3. Parameter Merging:

• Smart merging with clear precedence: CLI > Files > Config
• CLI parameters add to config instead of replacing
• Multiline value support with TOML literal strings

4. 100% Backward Compatible:

• Old format still works
• No breaking changes
• Both formats can coexist

What side effects does this change have?

Positive Side Effects:

• Improves developer experience with cleaner configuration syntax
• Enables better team collaboration with external parameter files
• Supports multi-environment workflows more naturally
• Reduces configuration file verbosity by ~50%

No Negative Side Effects:

• Fully backward compatible - existing configs continue to work
• Additive only - no changes to existing functionality
• No new dependencies - uses existing SAM CLI infrastructure
• No performance impact - lazy loading used

---

Mandatory Checklist

PRs will only be reviewed after checklist is complete

• Add input/output type hints to new functions/methods
• Write design document if needed (Not required - straightforward feature addition)
• Write/update unit tests (61 new tests added, all passing)
• Write/update integration tests (Integration tests included in new test files)
• Write/update functional tests if needed (Covered by integration tests)
• make pr passes (5,934 tests pass, 94.17% coverage)
• make update-reproducible-reqs if dependencies were changed (No new dependencies)
• Write documentation (Comprehensive docstrings added, user docs can be added upon approval)

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[vicheey]

Hi @dcabib, thank you for this contribution.

The core use case addressed here — cleaner parameter configuration and file-based parameter loading — has been implemented through recent changes:

• Expand parameter overrides #7876 (Dec 2025): Added file:// support for --parameter-overrides, enabling structured parameter files (YAML/TOML/JSON) in place of inline strings.
• More expanded parameter overrides #8604 (Feb 2026): Added $include key support and relative path resolution for nested file composition.

These allow clean, composable parameter configuration without the single-line string limitations.

The primary concern with this PR is that it introduces a parallel parameter loading system (ParameterFileLoader, ParameterMerger) rather than integrating with the existing CfnParameterOverridesType pipeline, which already handles the supported formats, nested includes, and recursion protection.

We will close this PR given the overlap with shipped features. If there are specific gaps not covered by the current file:// and $include support, please open a feature request issue describing the workflow.

Thank you for your time and effort.