Add integrated change preview to deploy command

Implement changeset-based deployment with rich change preview functionality:

- Add ExecuteChangeSet to AWS operations layer with comprehensive testing
- Enhance ChangeSetManager with CreateChangeSetForDeployment method for deployment scenarios
- Rewrite deploy command to use unified diff engine for consistent change previews
- Show detailed template, parameter, tag, and resource changes before deployment
- Use CloudFormation ChangeSets for both preview generation and deployment execution
- Maintain separate flows for new stack creation vs existing stack updates
- Update all documentation including README, command help, examples, and architecture docs

Benefits:
- Accurate previews using same changeset that gets deployed
- Rich diff output consistent with dedicated diff command
- Enhanced user experience with change visibility before deployment
- CloudFormation best practices using native ChangeSet API
- Comprehensive test coverage with no breaking changes

Author: orien

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-Stackaroo is a command-line tool for managing AWS CloudFormation stacks as code, written in Go. It provides declarative configuration, environment management, template validation, and dependency management for CloudFormation deployments.
+Stackaroo is a command-line tool for managing AWS CloudFormation stacks as code, written in Go. It provides declarative configuration, environment management, change preview, template validation, and dependency management for CloudFormation deployments.
 
 **Key Technologies:**
 - Go 1.24
@@ -71,7 +71,7 @@ cmd/           - CLI commands and subcommands
 internal/      - Internal packages (not importable by other projects)
   aws/         - AWS service interactions
   config/      - Configuration handling
-  deploy/      - Deployment logic
+  deploy/      - Deployment logic with integrated change preview
   resolve/     - Dependency resolution
 examples/      - Usage examples
 docs/          - Documentation

README.md

@@ -8,6 +8,7 @@ Stackaroo simplifies CloudFormation stack management by providing:
 
 - **Declarative Configuration**: Define your stacks and parameters in YAML files
 - **Environment Management**: Deploy the same templates across multiple environments
+- **Change Preview**: See exactly what changes will be made before deployment
 - **Template Validation**: Validate CloudFormation templates before deployment
 - **Stack Lifecycle**: Deploy, update, delete, and monitor stack status
 - **Parameter Management**: Organize parameters by environment and stack
@@ -25,6 +26,15 @@ Stackaroo simplifies CloudFormation stack management by providing:
 - Automatic deployment ordering
 - Parallel deployment where possible
 
+### Change Preview
+
+- **Comprehensive Change Analysis**: Shows template, parameter, tag, and resource changes
+- **CloudFormation ChangeSet Integration**: Uses AWS ChangeSet API for accurate previews
+- **Rich Diff Output**: Detailed comparison of current vs proposed infrastructure
+- **Resource Impact Assessment**: Identifies which resources will be created, modified, or deleted
+- **Replacement Warnings**: Highlights resources that require replacement during updates
+- **Consistent Formatting**: Same preview format as the dedicated `diff` command
+
 ### Template Validation
 
 - Local CloudFormation template validation
@@ -33,6 +43,7 @@ Stackaroo simplifies CloudFormation stack management by providing:
 
 ### Real-time Event Streaming
 
+- **Change Preview Before Deployment**: See exactly what will change before applying
 - Live CloudFormation events during deployment operations
 - See resource creation, updates, and completion status in real-time
 - Smart detection of create vs update operations

cmd/deploy.go

@@ -25,6 +25,25 @@ var (
 var deployCmd = &cobra.Command{
 	Use:   "deploy",
 	Short: "Deploy CloudFormation stacks",
+	Long: `Deploy CloudFormation stacks with integrated change preview.
+
+This command automatically shows you exactly what changes will be made before 
+applying them to your infrastructure. For existing stacks, it uses AWS CloudFormation 
+ChangeSets to provide accurate previews including:
+
+• Template changes (resources added, modified, or removed)
+• Parameter changes (current vs new values)  
+• Tag changes (added, modified, or removed tags)
+• Resource-level impact analysis with replacement warnings
+
+For new stacks, the command proceeds directly with stack creation.
+
+Examples:
+  stackaroo deploy vpc --environment dev
+  stackaroo deploy app --environment prod
+
+The preview shows the same detailed diff information as 'stackaroo diff' but 
+automatically proceeds with deployment after displaying the changes.`,
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		stackName := args[0]

cmd/root.go

@@ -20,6 +20,7 @@ var rootCmd = &cobra.Command{
 • Declarative configuration in YAML files
 • Environment-specific parameter management
 • Stack dependency resolution
+• Change preview before deployment
 • Template validation and deployment
 • Rich terminal output with progress indicators
 

docs/architecture/diff.md

@@ -285,6 +285,30 @@ sequenceDiagram
 - `ResolvedStack.Environment` - Track deployment context
 - Dependency resolution for complete stack information
 
+### 4. Deployment Integration (`internal/deploy`)
+
+**Integrated Preview:**
+- `NewDiffer(cfClient)` - Create differ with existing CloudFormation operations
+- `DiffStack(ctx, resolvedStack, options)` - Generate change preview during deployment
+- Consistent formatting between `stackaroo diff` and `stackaroo deploy` commands
+- Automatic change preview before deployment execution for existing stacks
+- Same changeset-based approach for both standalone diff and integrated deployment preview
+
+**Deployment Flow Integration:**
+```mermaid
+sequenceDiagram
+    participant Deploy as Deploy Command  
+    participant Differ as Diff Engine
+    participant AWS as AWS CloudFormation
+    
+    Deploy->>Differ: DiffStack(resolved, options)
+    Differ->>AWS: Generate changeset & preview
+    AWS->>Differ: Change details
+    Differ->>Deploy: Formatted preview
+    Deploy->>User: Display changes
+    Deploy->>AWS: Execute deployment
+```
+
 ## Error Handling Strategy
 
 ```mermaid

examples/simple-vpc/README.md

@@ -9,6 +9,7 @@ This example demonstrates basic Stackaroo usage with a simple VPC deployment acr
 - **Cross-account deployment** - Production uses a separate AWS account
 - **Parameter inheritance** - Global defaults with environment-specific overrides
 - **Tag management** - Consistent tagging across environments
+- **Change preview** - See exactly what infrastructure changes before deployment
 
 ## Prerequisites
 
@@ -50,12 +51,12 @@ The `stackaroo.yaml` file defines:
    cd examples/simple-vpc
    ```
 
-3. **Deploy to development**:
+3. **Deploy to development** (shows preview before applying changes):
    ```bash
    ../../stackaroo deploy vpc --environment dev
    ```
 
-4. **Deploy to staging**:
+4. **Deploy to staging** (shows preview before applying changes):
    ```bash
    ../../stackaroo deploy vpc --environment staging
    ```
@@ -65,6 +66,36 @@ The `stackaroo.yaml` file defines:
    ../../stackaroo deploy vpc --environment prod
    ```
 
+## Preview Output
+
+When you run the deploy commands, Stackaroo will show you exactly what changes will be made:
+
+```
+=== Calculating changes for stack vpc ===
+Changes to be applied to stack vpc:
+
+Status: CHANGES DETECTED (for updates) or Creating new stack: vpc (for new deployments)
+
+Template Changes:
+-----------------
+✓ Template has been modified (if updating)
+Resource changes:
+  + 6 resources to be added (for new stacks)
+
+AWS CloudFormation Preview:
+---------------------------
+Resource Changes:
+  + VPC (AWS::EC2::VPC)
+  + InternetGateway (AWS::EC2::InternetGateway)
+  + PublicSubnet (AWS::EC2::Subnet)
+  + PrivateSubnet (AWS::EC2::Subnet)
+  + PublicRouteTable (AWS::EC2::RouteTable)
+  + PrivateRouteTable (AWS::EC2::RouteTable)
+
+=== Deploying stack vpc ===
+[Live deployment events appear here...]
+```
+
 ## What Gets Deployed
 
 Each deployment creates:
@@ -108,6 +139,7 @@ This example demonstrates:
 3. **Cross-account deployment** - Managing resources across AWS accounts
 4. **Infrastructure consistency** - Identical setup with environment-appropriate sizing
 5. **Tag management** - Consistent tagging strategy across environments
+6. **Change preview** - How Stackaroo shows you exactly what will change before deployment
 
 ## Next Steps
 

internal/aws/client_test.go

@@ -103,6 +103,10 @@ func (m *MockCloudFormationClient) CreateChangeSet(ctx context.Context, params *
 	return nil, nil
 }
 
+func (m *MockCloudFormationClient) ExecuteChangeSet(ctx context.Context, params *cloudformation.ExecuteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.ExecuteChangeSetOutput, error) {
+	return nil, nil
+}
+
 func (m *MockCloudFormationClient) DeleteChangeSet(ctx context.Context, params *cloudformation.DeleteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DeleteChangeSetOutput, error) {
 	return nil, nil
 }

internal/aws/cloudformation.go

@@ -436,6 +436,11 @@ func (cf *DefaultCloudFormationOperations) CreateChangeSet(ctx context.Context,
 	return cf.client.CreateChangeSet(ctx, params, optFns...)
 }
 
+// ExecuteChangeSet executes a CloudFormation changeset
+func (cf *DefaultCloudFormationOperations) ExecuteChangeSet(ctx context.Context, params *cloudformation.ExecuteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.ExecuteChangeSetOutput, error) {
+	return cf.client.ExecuteChangeSet(ctx, params, optFns...)
+}
+
 // DeleteChangeSet deletes a CloudFormation changeset
 func (cf *DefaultCloudFormationOperations) DeleteChangeSet(ctx context.Context, params *cloudformation.DeleteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DeleteChangeSetOutput, error) {
 	return cf.client.DeleteChangeSet(ctx, params, optFns...)

internal/aws/cloudformation_test.go

@@ -72,6 +72,11 @@ func (m *MockCloudFormationClientForDeployTest) CreateChangeSet(ctx context.Cont
 	return args.Get(0).(*cloudformation.CreateChangeSetOutput), args.Error(1)
 }
 
+func (m *MockCloudFormationClientForDeployTest) ExecuteChangeSet(ctx context.Context, params *cloudformation.ExecuteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.ExecuteChangeSetOutput, error) {
+	args := m.Called(ctx, params)
+	return args.Get(0).(*cloudformation.ExecuteChangeSetOutput), args.Error(1)
+}
+
 func (m *MockCloudFormationClientForDeployTest) DeleteChangeSet(ctx context.Context, params *cloudformation.DeleteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DeleteChangeSetOutput, error) {
 	args := m.Called(ctx, params)
 	return args.Get(0).(*cloudformation.DeleteChangeSetOutput), args.Error(1)
@@ -490,3 +495,48 @@ func TestDeployStackWithCallback_Success(t *testing.T) {
 	assert.Equal(t, "callback-stack", capturedEvents[0].StackName)
 	mockClient.AssertExpectations(t)
 }
+
+func TestDefaultCloudFormationOperations_ExecuteChangeSet_Success(t *testing.T) {
+	mockClient := &MockCloudFormationClientForDeployTest{}
+	cfOps := NewCloudFormationOperationsWithClient(mockClient)
+	ctx := context.Background()
+
+	changeSetID := "arn:aws:cloudformation:us-east-1:123456789012:changeSet/test-changeset/test-stack"
+
+	executeInput := &cloudformation.ExecuteChangeSetInput{
+		ChangeSetName: aws.String(changeSetID),
+	}
+
+	expectedOutput := &cloudformation.ExecuteChangeSetOutput{}
+
+	mockClient.On("ExecuteChangeSet", ctx, executeInput).Return(expectedOutput, nil)
+
+	output, err := cfOps.ExecuteChangeSet(ctx, executeInput)
+
+	require.NoError(t, err)
+	assert.Equal(t, expectedOutput, output)
+	mockClient.AssertExpectations(t)
+}
+
+func TestDefaultCloudFormationOperations_ExecuteChangeSet_Error(t *testing.T) {
+	mockClient := &MockCloudFormationClientForDeployTest{}
+	cfOps := NewCloudFormationOperationsWithClient(mockClient)
+	ctx := context.Background()
+
+	changeSetID := "arn:aws:cloudformation:us-east-1:123456789012:changeSet/test-changeset/test-stack"
+
+	executeInput := &cloudformation.ExecuteChangeSetInput{
+		ChangeSetName: aws.String(changeSetID),
+	}
+
+	expectedError := errors.New("changeset execution failed")
+
+	mockClient.On("ExecuteChangeSet", ctx, executeInput).Return((*cloudformation.ExecuteChangeSetOutput)(nil), expectedError)
+
+	output, err := cfOps.ExecuteChangeSet(ctx, executeInput)
+
+	assert.Nil(t, output)
+	assert.Error(t, err)
+	assert.Equal(t, expectedError, err)
+	mockClient.AssertExpectations(t)
+}

internal/aws/interfaces.go

@@ -21,6 +21,7 @@ type CloudFormationClient interface {
 	ValidateTemplate(ctx context.Context, params *cloudformation.ValidateTemplateInput, optFns ...func(*cloudformation.Options)) (*cloudformation.ValidateTemplateOutput, error)
 	GetTemplate(ctx context.Context, params *cloudformation.GetTemplateInput, optFns ...func(*cloudformation.Options)) (*cloudformation.GetTemplateOutput, error)
 	CreateChangeSet(ctx context.Context, params *cloudformation.CreateChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.CreateChangeSetOutput, error)
+	ExecuteChangeSet(ctx context.Context, params *cloudformation.ExecuteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.ExecuteChangeSetOutput, error)
 	DeleteChangeSet(ctx context.Context, params *cloudformation.DeleteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DeleteChangeSetOutput, error)
 	DescribeChangeSet(ctx context.Context, params *cloudformation.DescribeChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DescribeChangeSetOutput, error)
 	DescribeStackEvents(ctx context.Context, params *cloudformation.DescribeStackEventsInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DescribeStackEventsOutput, error)
@@ -53,6 +54,7 @@ type CloudFormationOperations interface {
 	GetTemplate(ctx context.Context, stackName string) (string, error)
 	DescribeStack(ctx context.Context, stackName string) (*StackInfo, error)
 	CreateChangeSet(ctx context.Context, params *cloudformation.CreateChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.CreateChangeSetOutput, error)
+	ExecuteChangeSet(ctx context.Context, params *cloudformation.ExecuteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.ExecuteChangeSetOutput, error)
 	DeleteChangeSet(ctx context.Context, params *cloudformation.DeleteChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DeleteChangeSetOutput, error)
 	DescribeChangeSet(ctx context.Context, params *cloudformation.DescribeChangeSetInput, optFns ...func(*cloudformation.Options)) (*cloudformation.DescribeChangeSetOutput, error)
 	DescribeStackEvents(ctx context.Context, stackName string) ([]StackEvent, error)