feat: implement complete parity between Go and TypeScript ECS installers

[rshade]

• feat(config): restore stack reference architecture in TypeScript application
• feat(network): add private load balancer and air-gapped deployment support
• feat(auth): implement SAML SSO configuration parameters and logic
• feat(images): add imagePrefix support for custom container registries
• feat(dns): update DNS configuration to use application stack references
• feat(diagrams): add missing private network and data flow architecture diagrams
• docs: update README to match Go version with comprehensive configuration guide

BREAKING CHANGE: Configuration structure updated to use stack references instead of manual parameters. Users must migrate from individual config values (dbClusterEndpoint, dbPort, etc.) to
baseStackReference parameter.

Closes #49

[claude]

Claude finished @rshade's task —— View job

---

PR Review: ECS TypeScript/Go Parity Implementation

Reviewing PR #650 for Pulumi Infrastructure-as-Code best practices, security, and production readiness.

Review Checklist:

• Read repository guidelines (CLAUDE.md)
• Review stack reference architecture changes
• Examine private load balancer implementation
• Validate SAML SSO configuration
• Check diagram accuracy and enterprise styling
• Review breaking changes impact
• Assess security and production readiness
• Validate code quality and patterns
• Check README documentation updates
• Provide comprehensive review feedback

✅ Overall Assessment: Approved

This PR successfully implements parity between Go and TypeScript ECS installers with strong attention to security, architecture patterns, and production readiness. The implementation follows Pulumi best practices throughout.

---

🎯 Major Strengths

1. Stack Reference Architecture (Breaking Change) - Excellent

• Proper Implementation: The shift from manual configuration to stack references in config.ts:31-32 follows Pulumi best practices
• Clean Dependency Management: Database, networking, and infrastructure outputs are properly consumed via stackRef.getOutput()
• Type Safety: All outputs properly typed as pulumi.Output<T> types
• Migration Path: README clearly documents the breaking change and migration requirements

2. Private Load Balancer & Air-Gapped Support - Well Executed

• Security-First Design: pulumiInternalLoadBalancer.ts correctly implements NLB with internal: true
• Network Isolation: Private subnets enforced with subnets: args.privateSubnetIds
• Proper TLS: TLS listener configuration with certificate ARN support (lines 41-46)
• Configuration Pattern: Clean feature flag enablePrivateLoadBalancerAndLimitEgress

3. SAML SSO Implementation - Robust

• Certificate Management: Proper handling of user-provided vs auto-generated certificates
• Secret Handling: Correct use of requireSecret() for private keys (config.ts:75)
• Conditional Logic: Clean implementation with proper boolean checks
• Environment Variables: Proper secret injection in apiService.ts:77-78

---

🔒 Security Assessment: Strong

Secrets Management

• ✅ Private keys handled via pulumi.secret() and requireSecret()
• ✅ Database credentials properly encrypted in Secrets Manager
• ✅ KMS key integration for encryption at rest
• ✅ No hardcoded secrets detected

Network Security

• ✅ VPC isolation with private/isolated subnets
• ✅ Security group references from infrastructure stack
• ✅ VPC endpoints for private connectivity
• ✅ CIDR whitelist support for load balancer access

IAM & Access Control

• ✅ Proper secrets manager policy generation (utils.ts:41-69)
• ✅ Resource-specific ARN permissions
• ✅ KMS decrypt permissions scoped appropriately

---

📋 Code Quality: High

TypeScript Best Practices

• ✅ Proper type definitions in types.ts
• ✅ Clean async/await patterns in hydrateConfig()
• ✅ Consistent error handling
• ✅ Well-structured component resource pattern

Pulumi Patterns

• ✅ Component resources with proper parent relationships
• ✅ Resource options handling (deleteBeforeReplace: true)
• ✅ Output composition and type safety
• ✅ Configuration validation with require() vs get()

---

📐 Architecture & Documentation: Excellent

Mermaid Diagrams - Enterprise Standards Compliant

• ✅ Styling: Proper Neo theme with base configuration
• ✅ Colors: Authentic Pulumi branding (#4d5bd9, #f7bf2a)
• ✅ Structure: Clear subgraph organization
• ✅ Content: Accurate representation of private networking and data flow

README Documentation

• ✅ Breaking change clearly documented in revision history
• ✅ Configuration parameters well explained
• ✅ Architecture sections updated to match implementation

---

🔍 Minor Issues & Recommendations

1. Configuration Validation

// config.ts:97 - Typo in parameter name
const consoleDesiredNumberTasks = stackConfig.getNumber("consoleDesirecNumberTasks") || 1;

Issue: Typo "Desirec" should be "Desired"
Impact: Minor - configuration key name inconsistency

2. Image Prefix Logic

// utils.ts:8-12 - Image prefix concatenation
if (imagePrefix && imagePrefix !== "") {
    return `${accountId}.dkr.ecr.${region}.amazonaws.com/${imagePrefix}${imageName}`;
}

Recommendation: Add path separator handling for image prefixes to prevent malformed image URLs

3. Error Handling Enhancement

Recommendation: Consider adding validation for required stack reference outputs to provide clearer error messages when infrastructure stack is not properly deployed.

---

🚀 Production Readiness: Ready

Deployment Considerations

• ✅ Multi-AZ support via subnet distribution
• ✅ Scalability configuration options
• ✅ Proper health check patterns
• ✅ Log aggregation configuration

Operational Excellence

• ✅ Comprehensive tagging strategy
• ✅ Resource naming conventions
• ✅ Monitoring integration points
• ✅ Backup and recovery considerations

---

📊 Breaking Change Impact Assessment

Migration Complexity: Medium

• Users must update from individual config parameters to baseStackReference
• Infrastructure stack must be deployed first
• Clear migration path documented

Backwards Compatibility: None (Intentional Breaking Change)

• Old configuration structure no longer supported
• Users must update configuration files
• Well-documented in README revision history

---

🎉 Conclusion

This PR demonstrates excellent engineering practices and successfully achieves parity between Go and TypeScript implementations. The code is production-ready, follows security best practices, and maintains high code quality standards. The breaking change is justified by the improved architecture and is well-documented.

Recommendation: Approve and Merge

The minor issues noted above are cosmetic and don't impact functionality or security. This implementation provides a solid foundation for enterprise Pulumi Service deployments on AWS ECS.

[claude]

Claude finished @rshade's task —— View job

---

PR Review: ECS TypeScript/Go Parity Implementation

Comprehensive review for Pulumi Infrastructure-as-Code best practices, security, and production readiness.

Review Checklist:

• Read repository guidelines (CLAUDE.md)
• Review stack reference architecture changes
• Examine private load balancer implementation
• Validate SAML SSO configuration
• Check diagram accuracy and enterprise styling
• Review breaking changes impact
• Assess security and production readiness
• Validate code quality and patterns
• Check README documentation updates
• Provide comprehensive review feedback

✅ Overall Assessment: Approved

This PR successfully implements complete parity between Go and TypeScript ECS installers with excellent attention to security, architecture patterns, and production readiness. The implementation follows Pulumi best practices throughout.

---

🎯 Major Strengths

1. Stack Reference Architecture (Breaking Change) - Excellent

• Proper Implementation: The shift from manual configuration to stack references in config.ts:31-32 follows Pulumi best practices
• Clean Dependency Management: Database, networking, and infrastructure outputs are properly consumed via stackRef.getOutput()
• Type Safety: All outputs properly typed as pulumi.Output<T> types
• Migration Path: README clearly documents the breaking change and migration requirements

2. Private Load Balancer & Air-Gapped Support - Well Executed

• Security-First Design: pulumiInternalLoadBalancer.ts correctly implements NLB with internal: true
• Network Isolation: Private subnets enforced with subnets: args.privateSubnetIds
• Proper TLS: TLS listener configuration with certificate ARN support (lines 41-46)
• Configuration Pattern: Clean feature flag enablePrivateLoadBalancerAndLimitEgress

3. SAML SSO Implementation - Robust

• Certificate Management: Proper handling of user-provided vs auto-generated certificates
• Secret Handling: Correct use of requireSecret() for private keys (config.ts:75)
• Conditional Logic: Clean implementation with proper boolean checks
• Environment Variables: Proper secret injection in apiService.ts:77-78

---

🔒 Security Assessment: Strong

Secrets Management

• ✅ Private keys handled via pulumi.secret() and requireSecret()
• ✅ Database credentials properly encrypted in Secrets Manager
• ✅ KMS key integration for encryption at rest
• ✅ No hardcoded secrets detected

Network Security

• ✅ VPC isolation with private/isolated subnets
• ✅ Security group references from infrastructure stack
• ✅ VPC endpoints for private connectivity
• ✅ CIDR whitelist support for load balancer access

IAM & Access Control

• ✅ Proper secrets manager policy generation (utils.ts:41-69)
• ✅ Resource-specific ARN permissions
• ✅ KMS decrypt permissions scoped appropriately

---

📋 Code Quality: High

TypeScript Best Practices

• ✅ Proper type definitions in types.ts
• ✅ Clean async/await patterns in hydrateConfig()
• ✅ Consistent error handling
• ✅ Well-structured component resource pattern

Pulumi Patterns

• ✅ Component resources with proper parent relationships
• ✅ Resource options handling (deleteBeforeReplace: true)
• ✅ Output composition and type safety
• ✅ Configuration validation with require() vs get()

---

📐 Architecture & Documentation: Excellent

Mermaid Diagrams - Enterprise Standards Compliant

• ✅ Styling: Proper Neo theme with base configuration
• ✅ Colors: Authentic Pulumi branding (#4d5bd9, #f7bf2a)
• ✅ Structure: Clear subgraph organization in new private network and data flow diagrams
• ✅ Content: Accurate representation of private networking architecture

README Documentation

• ✅ Breaking change clearly documented in revision history (line 20)
• ✅ Configuration parameters well explained with examples
• ✅ Architecture sections updated to match implementation
• ✅ Stack reference pattern properly documented

---

🔧 Minor Recommendations

1. Image Prefix Logic Enhancement

// utils.ts:8-12 - Image prefix concatenation  
if (imagePrefix && imagePrefix !== "") {
    return `${accountId}.dkr.ecr.${region}.amazonaws.com/${imagePrefix}${imageName}`;
}

Recommendation: Consider adding path separator handling for image prefixes to prevent malformed image URLs when prefix doesn't end with /.

2. Error Handling Enhancement

Recommendation: Consider adding validation for required stack reference outputs to provide clearer error messages when infrastructure stack is not properly deployed.

---

🚀 Production Readiness: Ready

Deployment Considerations

• ✅ Multi-AZ support via subnet distribution
• ✅ Scalability configuration options
• ✅ Proper health check patterns
• ✅ Log aggregation configuration

Operational Excellence

• ✅ Comprehensive tagging strategy
• ✅ Resource naming conventions
• ✅ Monitoring integration points
• ✅ Backup and recovery considerations

---

📊 Breaking Change Impact Assessment

Migration Complexity: Medium

• Users must update from individual config parameters to baseStackReference
• Infrastructure stack must be deployed first
• Clear migration path documented

Backwards Compatibility: None (Intentional Breaking Change)

• Old configuration structure no longer supported
• Users must update configuration files
• Well-documented in README revision history (line 20)

---

🎉 Conclusion

This PR demonstrates excellent engineering practices and successfully achieves parity between Go and TypeScript implementations. The code is production-ready, follows security best practices, and maintains high code quality standards. The breaking change is justified by the improved architecture and is well-documented.

Recommendation: Approve and Merge

The implementation provides a solid foundation for enterprise Pulumi Service deployments on AWS ECS with enhanced security and air-gapped deployment capabilities.

---