Rename environment flag to context in deploy and diff commands

- Replace --environment with --context in deploy and diff commands
- Update all CLI help text and error messages to use context terminology
- Update all tests to use new flag names and terminology
- Update documentation examples and architecture diagrams
- Update project documentation to consistently use context terminology
- Breaking change: users must update from --environment to --context

Both deploy and diff commands now use consistent --context flag for
specifying deployment contexts, providing a more generic and unified
CLI interface.

Author: orien

AGENTS.md

@@ -145,9 +145,9 @@ For straightforward command handlers and basic functionality:
 ```go
 func TestFunctionName_Scenario_ExpectedBehaviour(t *testing.T) {
     // Arrange - Set up test data and mocks
-    
+
     // Act - Execute the function under test
-    
+
     // Assert - Verify the expected behaviour
     require.NoError(t, err)
     assert.Equal(t, expected, actual)
@@ -160,17 +160,17 @@ func TestCloudFormationService_CreateStack_Success(t *testing.T) {
     // Arrange
     mockCF := &mockCloudFormationAPI{}
     service := NewCloudFormationService(mockCF)
-    
+
     expectedInput := &cloudformation.CreateStackInput{
         StackName: aws.String("test-stack"),
     }
-    
+
     mockCF.On("CreateStack", mock.AnythingOfType("*context.emptyCtx"), expectedInput).
         Return(&cloudformation.CreateStackOutput{}, nil)
-    
+
     // Act
     result, err := service.CreateStack(context.Background(), "test-stack", template)
-    
+
     // Assert
     require.NoError(t, err)
     assert.NotNil(t, result)
@@ -279,18 +279,13 @@ All tests must pass before merging. Run `make commit-check` before committing.
 
 ### YAML Configuration
 - Stack definitions in YAML format
-- Environment-specific parameter overrides
+- Context-specific parameter overrides
 - Template path resolution
 - Dependency declarations with `depends_on`
 
 ### File Structure Expectations
 ```
 stackaroo.yml           # Main configuration
-environments/
-  dev/
-    parameters.yml      # Dev environment parameters
-  prod/
-    parameters.yml      # Prod environment parameters
 templates/
   vpc.yml              # CloudFormation templates
   app.yml
@@ -318,7 +313,7 @@ make version            # Show version info
 
 ### Supported Platforms
 - Linux (AMD64, ARM64)
-- macOS (AMD64, ARM64) 
+- macOS (AMD64, ARM64)
 - Windows (AMD64, ARM64)
 
 ## Common Development Tasks
@@ -423,4 +418,4 @@ Must be presented to and approved by the driver before committing.
 ### Logging
 - Use structured logging for AWS operations
 - Include request IDs for AWS API calls
-- Log stack names and operations clearly
+- Log stack names and operations clearly

README.md

@@ -7,18 +7,17 @@ A command-line tool for managing AWS CloudFormation stacks as code.
 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
+- **Environment Management**: Deploy the same templates across multiple contexts
 - **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
+- **Parameter Management**: Organize parameters by context and stack
 
 ## Features
 
 ### Environment Management
-- Deploy the same templates across multiple environments
-- Environment-specific parameter overrides
-- Different AWS regions and profiles per environment
+- Deploy the same templates across multiple contexts
+- Different AWS regions and parameters per context
 
 ### Dependency Management
 
@@ -43,7 +42,7 @@ Stackaroo simplifies CloudFormation stack management by providing:
 
 ### Real-time Event Streaming
 
-- **Change Preview Before Deployment**: See exactly what will change before applying
+- 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

@@ -16,7 +16,7 @@ import (
 )
 
 var (
-	environmentName string
+	contextName string
 	// deployer can be injected for testing
 	deployer deploy.Deployer
 )
@@ -39,8 +39,8 @@ ChangeSets to provide accurate previews including:
 For new stacks, the command proceeds directly with stack creation.
 
 Examples:
-  stackaroo deploy vpc --environment dev
-  stackaroo deploy app --environment prod
+  stackaroo deploy vpc --context dev
+  stackaroo deploy app --context prod
 
 The preview shows the same detailed diff information as 'stackaroo diff' but 
 automatically proceeds with deployment after displaying the changes.`,
@@ -49,12 +49,12 @@ automatically proceeds with deployment after displaying the changes.`,
 		stackName := args[0]
 		ctx := context.Background()
 
-		// Environment must be provided
-		if environmentName == "" {
-			return fmt.Errorf("--environment must be specified")
+		// Context must be provided
+		if contextName == "" {
+			return fmt.Errorf("--context must be specified")
 		}
 
-		return deployWithConfig(ctx, stackName, environmentName)
+		return deployWithConfig(ctx, stackName, contextName)
 	},
 }
 
@@ -82,13 +82,13 @@ func SetDeployer(d deploy.Deployer) {
 }
 
 // deployWithConfig handles deployment using configuration file
-func deployWithConfig(ctx context.Context, stackName, environmentName string) error {
+func deployWithConfig(ctx context.Context, stackName, contextName string) error {
 	// Create configuration provider and resolver
 	provider := file.NewDefaultProvider()
 	resolver := resolve.NewStackResolver(provider)
 
 	// Resolve stack and all its dependencies
-	resolved, err := resolver.Resolve(ctx, environmentName, []string{stackName})
+	resolved, err := resolver.Resolve(ctx, contextName, []string{stackName})
 	if err != nil {
 		return fmt.Errorf("failed to resolve stack dependencies: %w", err)
 	}
@@ -117,16 +117,16 @@ func deployWithConfig(ctx context.Context, stackName, environmentName string) er
 			return fmt.Errorf("error deploying stack %s: %w", stackName, err)
 		}
 
-		fmt.Printf("Successfully deployed stack %s in environment %s\n", stackName, environmentName)
+		fmt.Printf("Successfully deployed stack %s in context %s\n", stackName, contextName)
 	}
 
 	return nil
 }
 
 func init() {
 	rootCmd.AddCommand(deployCmd)
-	deployCmd.Flags().StringVar(&environmentName, "environment", "", "deployment environment")
-	if err := deployCmd.MarkFlagRequired("environment"); err != nil {
-		panic(fmt.Sprintf("failed to mark environment flag as required: %v", err))
+	deployCmd.Flags().StringVar(&contextName, "context", "", "deployment context")
+	if err := deployCmd.MarkFlagRequired("context"); err != nil {
+		panic(fmt.Sprintf("failed to mark context flag as required: %v", err))
 	}
 }

cmd/deploy_test.go

@@ -53,19 +53,19 @@ func TestDeployCommand_AcceptsStackName(t *testing.T) {
 	assert.NotNil(t, deployCmd.Args, "deploy command should have Args validation set")
 }
 
-func TestDeployCommand_HasEnvironmentFlag(t *testing.T) {
-	// Test that deploy command has a --environment flag
+func TestDeployCommand_HasContextFlag(t *testing.T) {
+	// Test that deploy command has a --context flag
 	deployCmd := findCommand(rootCmd, "deploy")
 	assert.NotNil(t, deployCmd)
 
-	// Check that --environment flag exists
-	environmentFlag := deployCmd.Flags().Lookup("environment")
-	assert.NotNil(t, environmentFlag, "deploy command should have --environment flag")
-	assert.Equal(t, "environment", environmentFlag.Name)
+	// Check that --context flag exists
+	contextFlag := deployCmd.Flags().Lookup("context")
+	assert.NotNil(t, contextFlag, "deploy command should have --context flag")
+	assert.Equal(t, "context", contextFlag.Name)
 }
 
-func TestDeployCommand_RequiresEnvironment(t *testing.T) {
-	// Test that deploy command requires --environment flag
+func TestDeployCommand_RequiresContext(t *testing.T) {
+	// Test that deploy command requires --context flag
 
 	// Mock deployer that shouldn't be called
 	mockDeployer := &MockDeployer{}
@@ -74,12 +74,12 @@ func TestDeployCommand_RequiresEnvironment(t *testing.T) {
 	SetDeployer(mockDeployer)
 	defer SetDeployer(oldDeployer)
 
-	// Execute without environment flag - should fail
+	// Execute without context flag - should fail
 	rootCmd.SetArgs([]string{"deploy", "test-stack"})
 
 	err := rootCmd.Execute()
-	assert.Error(t, err, "deploy command should require --environment flag")
-	assert.Contains(t, err.Error(), "required flag(s) \"environment\" not set")
+	assert.Error(t, err, "deploy command should require --context flag")
+	assert.Contains(t, err.Error(), "required flag(s) \"context\" not set")
 
 	// Verify no deployer calls were made
 	mockDeployer.AssertExpectations(t)
@@ -129,7 +129,7 @@ stacks:
 	}()
 
 	// Execute the root command with deploy subcommand and arguments
-	rootCmd.SetArgs([]string{"deploy", "test-stack", "--environment", "test"})
+	rootCmd.SetArgs([]string{"deploy", "test-stack", "--context", "test"})
 
 	// Execute the command - should return error
 	err = rootCmd.Execute()
@@ -224,12 +224,12 @@ stacks:
 	}()
 
 	// First deployment should succeed
-	rootCmd.SetArgs([]string{"deploy", "stack-1", "--environment", "test"})
+	rootCmd.SetArgs([]string{"deploy", "stack-1", "--context", "test"})
 	err = rootCmd.Execute()
 	assert.NoError(t, err, "first deployment should succeed")
 
 	// Second deployment should fail
-	rootCmd.SetArgs([]string{"deploy", "stack-2", "--environment", "test"})
+	rootCmd.SetArgs([]string{"deploy", "stack-2", "--context", "test"})
 	err = rootCmd.Execute()
 	assert.Error(t, err, "second deployment should fail")
 	assert.Contains(t, err.Error(), "second deployment failed", "error should contain expected message")
@@ -294,7 +294,7 @@ stacks:
 
 	// Set up mock deployer that expects config-resolved values
 	mockDeployer := &MockDeployer{}
-	// Expect Stack with resolved parameters from dev environment
+	// Expect Stack with resolved parameters from dev context
 	mockDeployer.On("DeployStack", mock.Anything, mock.MatchedBy(func(stack *model.Stack) bool {
 		return stack.Name == "vpc" &&
 			stack.Parameters["VpcCidr"] == "10.1.0.0/16" &&
@@ -316,8 +316,8 @@ stacks:
 		require.NoError(t, err)
 	}()
 
-	// Execute deploy command with environment flag
-	rootCmd.SetArgs([]string{"deploy", "vpc", "--environment", "dev"})
+	// Execute deploy command with context flag
+	rootCmd.SetArgs([]string{"deploy", "vpc", "--context", "dev"})
 
 	err = rootCmd.Execute()
 	assert.NoError(t, err, "deploy command should execute successfully with config")
@@ -402,7 +402,7 @@ stacks:
 
 	// This should resolve dependencies and deploy: vpc → database → app
 	// But current implementation will only deploy app
-	rootCmd.SetArgs([]string{"deploy", "app", "--environment", "test"})
+	rootCmd.SetArgs([]string{"deploy", "app", "--context", "test"})
 
 	err = rootCmd.Execute()
 	assert.NoError(t, err, "deploy should succeed")
@@ -478,7 +478,7 @@ stacks:
 	}()
 
 	// Deploy app - should trigger resolver to deploy vpc → database → app
-	rootCmd.SetArgs([]string{"deploy", "app", "--environment", "test"})
+	rootCmd.SetArgs([]string{"deploy", "app", "--context", "test"})
 
 	err = rootCmd.Execute()
 	assert.NoError(t, err, "deploy should succeed")
@@ -501,11 +501,11 @@ contexts:
 stacks:
   - name: vpc
     template: templates/vpc.yaml
-    
+
   - name: database
     template: templates/db.yaml
     depends_on: [vpc]
-      
+
   - name: app
     template: templates/app.yaml
     depends_on: [database]

cmd/diff.go

@@ -16,11 +16,11 @@ import (
 )
 
 var (
-	diffEnvironmentName string
-	diffTemplateOnly    bool
-	diffParametersOnly  bool
-	diffTagsOnly        bool
-	diffFormat          string
+	diffContextName    string
+	diffTemplateOnly   bool
+	diffParametersOnly bool
+	diffTagsOnly       bool
+	diffFormat         string
 	// differ can be injected for testing
 	differ diff.Differ
 )
@@ -40,26 +40,26 @@ the current configuration. It compares:
 • Resource-level changes (when possible via AWS ChangeSets)
 
 Examples:
-  stackaroo diff vpc --environment dev              # Show all changes
-  stackaroo diff vpc --environment prod --template  # Template diff only
-  stackaroo diff vpc --environment dev --parameters # Parameter diff only
-  stackaroo diff vpc --environment dev --format json # JSON output`,
+  stackaroo diff vpc --context dev              # Show all changes
+  stackaroo diff vpc --context prod --template  # Template diff only
+  stackaroo diff vpc --context dev --parameters # Parameter diff only
+  stackaroo diff vpc --context dev --format json # JSON output`,
 	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		stackName := args[0]
 		ctx := context.Background()
 
-		// Environment must be provided
-		if diffEnvironmentName == "" {
-			return fmt.Errorf("--environment must be specified")
+		// Context must be provided
+		if diffContextName == "" {
+			return fmt.Errorf("--context must be specified")
 		}
 
 		// Validate format option
 		if diffFormat != "text" && diffFormat != "json" {
 			return fmt.Errorf("--format must be 'text' or 'json'")
 		}
 
-		return diffWithConfig(ctx, stackName, diffEnvironmentName)
+		return diffWithConfig(ctx, stackName, diffContextName)
 	},
 }
 
@@ -87,13 +87,13 @@ func SetDiffer(d diff.Differ) {
 }
 
 // diffWithConfig handles diff using configuration file
-func diffWithConfig(ctx context.Context, stackName, environmentName string) error {
+func diffWithConfig(ctx context.Context, stackName, contextName string) error {
 	// Create configuration provider and resolver
 	provider := file.NewDefaultProvider()
 	resolver := resolve.NewStackResolver(provider)
 
 	// Resolve stack and all its dependencies
-	resolved, err := resolver.Resolve(ctx, environmentName, []string{stackName})
+	resolved, err := resolver.Resolve(ctx, contextName, []string{stackName})
 	if err != nil {
 		return fmt.Errorf("failed to resolve stack dependencies: %w", err)
 	}
@@ -134,9 +134,9 @@ func diffWithConfig(ctx context.Context, stackName, environmentName string) erro
 	// Set exit code based on whether changes were found
 	if result.HasChanges() {
 		// Exit with code 1 if changes detected (similar to git diff)
-		fmt.Printf("\nChanges detected for stack %s in environment %s\n", stackName, environmentName)
+		fmt.Printf("\nChanges detected for stack %s in context %s\n", stackName, contextName)
 	} else {
-		fmt.Printf("\nNo changes detected for stack %s in environment %s\n", stackName, environmentName)
+		fmt.Printf("\nNo changes detected for stack %s in context %s\n", stackName, contextName)
 	}
 
 	return nil
@@ -146,9 +146,9 @@ func init() {
 	rootCmd.AddCommand(diffCmd)
 
 	// Required flags
-	diffCmd.Flags().StringVar(&diffEnvironmentName, "environment", "", "deployment environment")
-	if err := diffCmd.MarkFlagRequired("environment"); err != nil {
-		panic(fmt.Sprintf("failed to mark environment flag as required: %v", err))
+	diffCmd.Flags().StringVar(&diffContextName, "context", "", "deployment context")
+	if err := diffCmd.MarkFlagRequired("context"); err != nil {
+		panic(fmt.Sprintf("failed to mark context flag as required: %v", err))
 	}
 
 	// Optional flags for filtering diff output