feat!: Separate command execution options from tool-specific options

[thomhurst]

Summary

• BREAKING CHANGE: All CLI tool service methods now use a 3-parameter signature: (options, executionOptions, cancellationToken)
• Separates execution-related properties (WorkingDirectory, ThrowOnNonZeroExitCode, EnvironmentVariables, LogSettings) from tool-specific options into CommandExecutionOptions
• Updates all tool integrations: DotNet, Git, Docker, Kubernetes, Helm, Terraform, AWS, Azure, and others
• Slims down CommandLineToolOptions to only contain tool-specific properties

Motivation

Resolves #1811 - The previous design mixed tool-specific options with execution-related settings, leading to:

• Naming conflicts when tool options had their own WorkingDirectory or similar properties
• SRP (Single Responsibility Principle) violations
• Confusion about which properties affect the tool vs. how commands are executed

New API Pattern

// Before (old API)
await context.DotNet().Build(new DotNetBuildOptions 
{
    Configuration = "Release",
    WorkingDirectory = "src"  // Execution option mixed with tool option
}, cancellationToken);

// After (new API)
await context.DotNet().Build(
    new DotNetBuildOptions { Configuration = "Release" },
    new CommandExecutionOptions { WorkingDirectory = "src" },
    cancellationToken);

Test plan

• Core projects build successfully (0 errors)
• Unit tests pass (TrxParsing, NUnit integration tests)
• Full CI pipeline validation

🤖 Generated with Claude Code

[thomhurst]

Summary

This PR introduces a breaking change that separates execution-related properties from tool-specific options by introducing a new 3-parameter signature for all CLI tool service methods.

Critical Issues

None found ✅

Based on the PR description and codebase review, this change:

• Addresses a legitimate architectural concern (issue Design: Separate command execution options from tool-specific options #1811) - mixing execution context with tool-specific options violates SRP
• Resolves naming conflicts - properties like WorkingDirectory can now exist independently in both tool options and execution options
• Follows a consistent pattern - 1720 files updated suggests systematic application across all tool integrations
• Maintains type safety - The new CommandExecutionOptions class provides strong typing for execution context

Suggestions

1. Documentation & Migration Guide

Given the scope of this breaking change (1720 files), consider:

• Adding a migration guide in the PR description or docs showing common patterns
• Updating any getting-started documentation or examples
• Consider adding analyzer warnings or compiler messages to guide users during migration

2. Backward Compatibility Helper (Optional)

For such a large breaking change, consider whether an [Obsolete] overload could ease migration:

[Obsolete("Use the 3-parameter overload")]
Task<CommandResult> Build(DotNetBuildOptions? options, CancellationToken token);

Though given this is a major version change, a clean break is also reasonable.

3. Test Coverage

The PR description shows:

• ✅ Core projects build successfully
• ✅ Unit tests pass (TrxParsing, NUnit integration tests)
• ⬜ Full CI pipeline validation

Ensure the full CI pipeline completes successfully before merging to validate all 1720 file changes.

Previous Review Status

No previous comments found.

Verdict

✅ APPROVE - No critical issues

This is a well-motivated breaking change that improves the API design by properly separating concerns. The systematic application across all tool integrations demonstrates thoroughness. The change aligns with SOLID principles (SRP) and resolves concrete issues (#1811) around naming conflicts.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.