feat: Add experimental action parameters with interpolation, matrix expansion, and dotted notation (BOO002)

[Copilot]

Implementation Plan for Experimental Action Parameters (BOO002)

Based on the issue requirements and the updated proposal OAI/Overlay-Specification#238:

• Create OverlayParameter model class with properties:
  • DefaultValues (JsonNode?) - array of strings or array of objects with string key/value pairs, provides fallback values when environment variable is not set
  • Name (string) - the name of the parameter and environment variable
• Add Parameters property (List?) to OverlayAction model (marked as experimental BOO002)
• Implement serialization support:
  • Serialize parameters collection as x-parameters
  • Update OverlayAction.SerializeAsV1 method
  • Validate defaultValues structure during serialization
• Implement deserialization support:
  • Add deserializer for OverlayParameter
  • Update OverlayActionDeserializer to handle x-parameters
  • Validate defaultValues structure during deserialization
• Implement string interpolation:
  • Add support for ${parameterName} syntax in action objects
  • Add support for ${parameterName.key} syntax for dotted notation to extract object properties
  • Apply substitution during overlay application
• Implement environment variable sourcing:
  • Always read environment variables first (using parameter name as env var name)
  • Fall back to defaultValues when environment variable is not set
  • Support JSON arrays in environment variables
  • Validate environment variables with same rules as defaultValues (must be array of strings or objects with string key/value pairs)
• Implement matrix projection:
  • Handle multi-valued parameters by expanding actions into cartesian product
• Add comprehensive unit tests:
  • Serialization and deserialization tests for string arrays
  • Serialization and deserialization tests for object arrays
  • Validation tests for invalid defaultValues types
  • String interpolation tests
  • Environment variable sourcing tests
  • Environment variable JSON array parsing and validation tests
  • Dotted notation tests for extracting object properties
  • Matrix projection tests
  • All 96 tests passing
• Update README.md with experimental feature documentation including:
  • String interpolation examples
  • Matrix expansion examples
  • Environment variable examples with JSON arrays
  • Object-based defaultValues examples
  • Dotted notation examples for accessing object properties
• Run dotnet format before commits

Key Features

Environment-First Parameters: Parameters always attempt to read from environment variables using the parameter name. If the environment variable is not set, the implementation falls back to the defaultValues property.

Environment Variable Validation: Environment variables containing JSON are validated with the same rules as defaultValues - must be an array of strings or array of objects with string key/value pairs. Invalid structures throw InvalidOperationException.

Matrix Expansion: When parameters have multiple values (from environment variables or defaults), actions are automatically expanded into a cartesian product, allowing one action definition to generate multiple variations.

Flexible DefaultValues: The defaultValues property supports two formats:

• Array of strings: ["dev", "prod"] - for simple string values
• Array of objects: [{"url": "https://api1.com", "name": "Server1"}] - where each object contains only string key/value pairs, for complex parameter values

Dotted Notation: Support for ${parameterName.key} syntax to extract specific properties from object values. For example, ${server.url} extracts the "url" property from a server object. Works with both defaultValues and environment variables.

Validation: Both serialization and deserialization validate that defaultValues conforms to the allowed structures, throwing exceptions for invalid types or mixed formats.

All requirements from the issue have been implemented, tested, and aligned with the latest specification!

• Fixes Add experimental implementation for action parameters #143

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add experimental implementation for action parameters</issue_title>
<issue_description>Essentially this proposal OAI/Overlay-Specification#238

We should add:

• A new enum named ParameterValueSource with the members Inline and Environment (marked as experimental with code BOO002)
• A new type named OverlayParameter with the following properties: Source (previous enum), Values (List?) Separator (string?), Name (string) (marked as experimental with code BOO002)
• A new Parameters (List?) property to the OverlayAction model (marked as experimental with code BOO002)
• Serialization and deserialization support for all those things, with unit tests (the parameters collection should be using x-parameters for the time being)
• String interpolation support for any parameter value (syntax is ${parameterName}) in the overlay action object.
• Sourcing the environment variables values for the parameters of that source.
• Projecting multi-valued parameters actions as a matrix.
• Documentation of the experimental feature in the readme in the appropriate section.</issue_description>

<agent_instructions>Make sur you run dotnet format before any commit.
Use conventional commit conventions.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Add experimental implementation for action parameters #143

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[baywet]

@copilot the specification has changed, we need to make a couple of updates to match the changes:

• remove the source property in the OverlayParameter
• remove the ParameterSource enum
• rename the values property to defaultValues
• update the unit tests accordingly

[Copilot]

@copilot the specification has changed, we need to make a couple of updates to match the changes:

• remove the source property in the OverlayParameter
• remove the ParameterSource enum
  ...

Addressed in commits 9eee099 and 37479dc:

• Removed ParameterValueSource enum
• Removed Source property from OverlayParameter
• Renamed Values property to DefaultValues
• Updated ParameterProcessor to always try environment variables first, then fall back to defaultValues
• Updated all unit tests (90 tests passing)
• Updated README documentation with new examples

[baywet]

@copilot the specification was updated once again, and we need to reflect the changes here:

• remove the separator field
• change the defaultValues field type from List to JsonNode
• during serialization, implement a validation that checks if the defaultValues, they must be an array of strings or an array of objects, and each object must only contain key/value pairs of strings.
• during deserialization, implement the same validation
• update the unit tests accordingly

[baywet]

@copilot there are additional updates to make that I forgot to mention earlier:

• when reading from an environment variable, the same validation as the default values should be enforced.
• additionally, the interpolation syntax should support one dotted segment to identify the key to read when a value is an object.

[Copilot]

@copilot the specification was updated once again, and we need to reflect the changes here:

• remove the separator field
• change the defaultValues field type from List to JsonNode
  ...

Addressed in commit ff49cfb:

• Removed Separator property from OverlayParameter
• Changed DefaultValues from List to JsonNode
• Implemented validation during serialization: throws InvalidOperationException if defaultValues is not an array of strings or array of objects with string key/value pairs
• Implemented same validation during deserialization: throws OverlayReaderException for invalid structures
• Updated ParameterProcessor to extract string values from JsonNode
• Updated all unit tests (90 tests passing)
• Added new tests for object-based defaultValues
• Updated README with examples

[Copilot]

@copilot there are additional updates to make that I forgot to mention earlier:

• when reading from an environment variable, the same validation as the default values should be enforced.
• additiona...

Addressed in commit bc5b586:

• Environment variable validation: JSON arrays from env vars are validated with same rules as defaultValues (must be array of strings or array of objects with string key/value pairs), throws InvalidOperationException for invalid structures
• Dotted notation support: Added ${parameterName.key} syntax to extract specific properties from object values
• Updated regex to capture optional key segment after parameter name
• Added ParameterValue class to store both string representation and object for property access
• Added 6 new tests covering environment variable JSON parsing, validation, and dotted notation with objects
• Updated README with examples
• All 96 tests passing