@stacksjs/ts-cloud 0.1.1

package/src/aws/cloudformation.ts

@@ -0,0 +1,896 @@
+/**
+ * AWS CloudFormation Operations
+ * Direct API calls without AWS CLI dependency
+ */
+
+import { AWSClient, buildQueryParams } from './client'
+
+export interface StackParameter {
+  ParameterKey: string
+  ParameterValue: string
+  UsePreviousValue?: boolean
+}
+
+export interface StackTag {
+  Key: string
+  Value: string
+}
+
+export interface CreateStackOptions {
+  stackName: string
+  templateBody?: string
+  templateUrl?: string
+  parameters?: StackParameter[]
+  capabilities?: string[]
+  roleArn?: string
+  tags?: StackTag[]
+  timeoutInMinutes?: number
+  onFailure?: 'DO_NOTHING' | 'ROLLBACK' | 'DELETE'
+}
+
+export interface UpdateStackOptions {
+  stackName: string
+  templateBody?: string
+  templateUrl?: string
+  parameters?: StackParameter[]
+  capabilities?: string[]
+  roleArn?: string
+  tags?: StackTag[]
+}
+
+export interface DescribeStacksOptions {
+  stackName?: string
+}
+
+export interface StackEvent {
+  Timestamp: string
+  ResourceType: string
+  LogicalResourceId: string
+  ResourceStatus: string
+  ResourceStatusReason?: string
+}
+
+export interface Stack {
+  StackId: string
+  StackName: string
+  StackStatus: string
+  StackStatusReason?: string
+  CreationTime: string
+  LastUpdatedTime?: string
+  Parameters?: StackParameter[]
+  Outputs?: Array<{
+    OutputKey: string
+    OutputValue: string
+    Description?: string
+    ExportName?: string
+  }>
+  Tags?: StackTag[]
+}
+
+/**
+ * CloudFormation stack management using direct API calls
+ */
+export class CloudFormationClient {
+  private client: AWSClient
+  private region: string
+
+  constructor(region: string = 'us-east-1', profile?: string) {
+    this.region = region
+    this.client = new AWSClient()
+  }
+
+  /**
+   * Create a new CloudFormation stack
+   */
+  async createStack(options: CreateStackOptions): Promise<{ StackId: string }> {
+    const params: Record<string, any> = {
+      Action: 'CreateStack',
+      StackName: options.stackName,
+      Version: '2010-05-15',
+    }
+
+    if (options.templateBody) {
+      params.TemplateBody = options.templateBody
+    }
+    else if (options.templateUrl) {
+      params.TemplateURL = options.templateUrl
+    }
+    else {
+      throw new Error('Either templateBody or templateUrl must be provided')
+    }
+
+    if (options.parameters) {
+      options.parameters.forEach((param, index) => {
+        params[`Parameters.member.${index + 1}.ParameterKey`] = param.ParameterKey
+        params[`Parameters.member.${index + 1}.ParameterValue`] = param.ParameterValue
+      })
+    }
+
+    if (options.capabilities) {
+      options.capabilities.forEach((cap, index) => {
+        params[`Capabilities.member.${index + 1}`] = cap
+      })
+    }
+
+    if (options.roleArn) {
+      params.RoleARN = options.roleArn
+    }
+
+    if (options.tags) {
+      options.tags.forEach((tag, index) => {
+        params[`Tags.member.${index + 1}.Key`] = tag.Key
+        params[`Tags.member.${index + 1}.Value`] = tag.Value
+      })
+    }
+
+    if (options.timeoutInMinutes) {
+      params.TimeoutInMinutes = options.timeoutInMinutes
+    }
+
+    if (options.onFailure) {
+      params.OnFailure = options.onFailure
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    return { StackId: result.StackId || result.CreateStackResult?.StackId }
+  }
+
+  /**
+   * Update an existing CloudFormation stack
+   */
+  async updateStack(options: UpdateStackOptions): Promise<{ StackId: string }> {
+    const params: Record<string, any> = {
+      Action: 'UpdateStack',
+      StackName: options.stackName,
+      Version: '2010-05-15',
+    }
+
+    if (options.templateBody) {
+      params.TemplateBody = options.templateBody
+    }
+    else if (options.templateUrl) {
+      params.TemplateURL = options.templateUrl
+    }
+
+    if (options.parameters) {
+      options.parameters.forEach((param, index) => {
+        params[`Parameters.member.${index + 1}.ParameterKey`] = param.ParameterKey
+        if (param.UsePreviousValue) {
+          params[`Parameters.member.${index + 1}.UsePreviousValue`] = 'true'
+        }
+        else {
+          params[`Parameters.member.${index + 1}.ParameterValue`] = param.ParameterValue
+        }
+      })
+    }
+
+    if (options.capabilities) {
+      options.capabilities.forEach((cap, index) => {
+        params[`Capabilities.member.${index + 1}`] = cap
+      })
+    }
+
+    if (options.roleArn) {
+      params.RoleARN = options.roleArn
+    }
+
+    if (options.tags) {
+      options.tags.forEach((tag, index) => {
+        params[`Tags.member.${index + 1}.Key`] = tag.Key
+        params[`Tags.member.${index + 1}.Value`] = tag.Value
+      })
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    return { StackId: result.StackId || result.UpdateStackResult?.StackId }
+  }
+
+  /**
+   * Delete a CloudFormation stack
+   */
+  async deleteStack(stackName: string, roleArn?: string, retainResources?: string[]): Promise<void> {
+    const params: Record<string, any> = {
+      Action: 'DeleteStack',
+      StackName: stackName,
+      Version: '2010-05-15',
+    }
+
+    if (roleArn) {
+      params.RoleARN = roleArn
+    }
+
+    // Add retained resources if provided
+    if (retainResources && retainResources.length > 0) {
+      retainResources.forEach((resource, index) => {
+        params[`RetainResources.member.${index + 1}`] = resource
+      })
+    }
+
+    await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+  }
+
+  /**
+   * Describe CloudFormation stacks
+   */
+  async describeStacks(options: DescribeStacksOptions = {}): Promise<{ Stacks: Stack[] }> {
+    const params: Record<string, any> = {
+      Action: 'DescribeStacks',
+      Version: '2010-05-15',
+    }
+
+    if (options.stackName) {
+      params.StackName = options.stackName
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    // Parse the response
+    const stacks = this.parseStacksResponse(result)
+    return { Stacks: stacks }
+  }
+
+  /**
+   * Get stack events
+   */
+  async describeStackEvents(stackName: string): Promise<{ StackEvents: StackEvent[] }> {
+    const params: Record<string, any> = {
+      Action: 'DescribeStackEvents',
+      StackName: stackName,
+      Version: '2010-05-15',
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    return { StackEvents: this.parseStackEvents(result) }
+  }
+
+  /**
+   * List stack resources
+   */
+  async listStackResources(stackName: string): Promise<{ StackResourceSummaries: any[] }> {
+    const params: Record<string, any> = {
+      Action: 'ListStackResources',
+      StackName: stackName,
+      Version: '2010-05-15',
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    // Parse resources from XML response - handle single member (object) or multiple members (array)
+    const member = result?.ListStackResourcesResult?.StackResourceSummaries?.member
+    let resources: any[] = []
+
+    if (member) {
+      resources = Array.isArray(member) ? member : [member]
+    }
+
+    return { StackResourceSummaries: resources }
+  }
+
+  /**
+   * Wait for stack to reach a specific status
+   */
+  async waitForStack(stackName: string, waitType: 'stack-create-complete' | 'stack-update-complete' | 'stack-delete-complete'): Promise<void> {
+    const targetStatuses = {
+      'stack-create-complete': ['CREATE_COMPLETE'],
+      'stack-update-complete': ['UPDATE_COMPLETE'],
+      'stack-delete-complete': ['DELETE_COMPLETE'],
+    }
+
+    const failureStatuses = [
+      'CREATE_FAILED',
+      'ROLLBACK_FAILED',
+      'ROLLBACK_COMPLETE',
+      'UPDATE_ROLLBACK_FAILED',
+      'UPDATE_ROLLBACK_COMPLETE',
+    ]
+
+    const targets = targetStatuses[waitType]
+    const maxAttempts = 360 // 30 minutes (DNS records can take 10-30 minutes)
+    let attempts = 0
+
+    while (attempts < maxAttempts) {
+      try {
+        const result = await this.describeStacks({ stackName })
+
+        if (result.Stacks.length === 0) {
+          if (waitType === 'stack-delete-complete') {
+            return // Stack deleted successfully
+          }
+          // For create/update operations, stack might not be visible yet - retry
+          if (attempts % 10 === 0) {
+            console.log(`[waitForStack] Attempt ${attempts}: Stack not visible yet`)
+          }
+          await new Promise(resolve => setTimeout(resolve, 2000))
+          attempts++
+          continue
+        }
+
+        const stack = result.Stacks[0]
+
+        if (attempts % 10 === 0) {
+          console.log(`[waitForStack] Attempt ${attempts}: Status = ${stack.StackStatus}${stack.StackStatusReason ? ` (${stack.StackStatusReason})` : ''}`)
+        }
+
+        if (targets.includes(stack.StackStatus)) {
+          return // Target status reached
+        }
+
+        // If stack is being deleted but we're waiting for create/update, something went wrong
+        if ((waitType === 'stack-create-complete' || waitType === 'stack-update-complete') &&
+            (stack.StackStatus === 'DELETE_IN_PROGRESS' || stack.StackStatus === 'DELETE_COMPLETE')) {
+          console.log(`[waitForStack] Stack is being deleted (creation/update failed)`)
+          // Try to get stack events to understand the failure
+          let failedEventReason = ''
+          try {
+            const eventsResult = await this.describeStackEvents(stackName)
+            console.log('[waitForStack] Stack events (most recent first):')
+            for (const event of eventsResult.StackEvents.slice(0, 15)) {
+              if (event.ResourceStatus.includes('FAILED') || event.ResourceStatusReason) {
+                console.log(`  ${event.LogicalResourceId}: ${event.ResourceStatus} - ${event.ResourceStatusReason || 'No reason provided'}`)
+                // Capture the first failed event reason for the error message
+                if (event.ResourceStatus.includes('FAILED') && event.ResourceStatusReason && !failedEventReason) {
+                  failedEventReason = event.ResourceStatusReason
+                }
+              }
+            }
+          }
+          catch {
+            // Ignore errors fetching events
+          }
+          // Include the detailed failure reason in the error message
+          const errorReason = failedEventReason || stack.StackStatusReason || 'Check CloudFormation console for details.'
+          throw new Error(`Stack creation/update failed - stack is being deleted. Reason: ${errorReason}`)
+        }
+
+        // Handle DELETE_FAILED specifically - might need to retain resources
+        if (stack.StackStatus === 'DELETE_FAILED' && waitType === 'stack-delete-complete') {
+          const error: any = new Error(`Stack deletion failed - may have resources that need to be retained`)
+          error.code = 'DELETE_FAILED'
+          error.stackStatus = stack.StackStatus
+          error.statusReason = stack.StackStatusReason
+          throw error
+        }
+
+        if (failureStatuses.includes(stack.StackStatus)) {
+          throw new Error(`Stack reached failure status: ${stack.StackStatus}`)
+        }
+
+        // Wait 5 seconds before next attempt
+        await new Promise(resolve => setTimeout(resolve, 5000))
+        attempts++
+      }
+      catch (error: any) {
+        if (waitType === 'stack-delete-complete' && error.message?.includes('does not exist')) {
+          return // Stack deleted
+        }
+        // For create operations, stack might not be visible yet - retry
+        if (waitType === 'stack-create-complete' && error.message?.includes('does not exist')) {
+          if (attempts % 10 === 0) {
+            console.log(`[waitForStack] Attempt ${attempts}: Stack does not exist (error), retrying...`)
+          }
+          await new Promise(resolve => setTimeout(resolve, 2000))
+          attempts++
+          continue
+        }
+        console.log(`[waitForStack] Unexpected error: ${error.message}`)
+        throw error
+      }
+    }
+
+    console.log(`[waitForStack] Timeout after ${attempts} attempts`)
+    throw new Error(`Timeout waiting for stack to reach ${waitType}`)
+  }
+
+  /**
+   * Validate CloudFormation template
+   */
+  async validateTemplate(templateBody: string): Promise<any> {
+    const params: Record<string, any> = {
+      Action: 'ValidateTemplate',
+      TemplateBody: templateBody,
+      Version: '2010-05-15',
+    }
+
+    return await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+  }
+
+  /**
+   * List all stacks
+   */
+  async listStacks(statusFilter?: string[]): Promise<{ StackSummaries: Array<{
+    StackId: string
+    StackName: string
+    TemplateDescription?: string
+    CreationTime: string
+    LastUpdatedTime?: string
+    DeletionTime?: string
+    StackStatus: string
+  }> }> {
+    const params: Record<string, any> = {
+      Action: 'ListStacks',
+      Version: '2010-05-15',
+    }
+
+    if (statusFilter) {
+      statusFilter.forEach((status, index) => {
+        params[`StackStatusFilter.member.${index + 1}`] = status
+      })
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    return { StackSummaries: [] } // TODO: Parse response
+  }
+
+
+  /**
+   * Create change set (for preview before updating)
+   */
+  async createChangeSet(options: {
+    stackName: string
+    changeSetName: string
+    templateBody?: string
+    templateUrl?: string
+    parameters?: StackParameter[]
+    capabilities?: string[]
+    changeSetType?: 'CREATE' | 'UPDATE'
+  }): Promise<{ Id: string, StackId: string }> {
+    const params: Record<string, any> = {
+      Action: 'CreateChangeSet',
+      StackName: options.stackName,
+      ChangeSetName: options.changeSetName,
+      Version: '2010-05-15',
+    }
+
+    if (options.templateBody) {
+      params.TemplateBody = options.templateBody
+    }
+    else if (options.templateUrl) {
+      params.TemplateURL = options.templateUrl
+    }
+
+    if (options.parameters) {
+      options.parameters.forEach((param, index) => {
+        params[`Parameters.member.${index + 1}.ParameterKey`] = param.ParameterKey
+        params[`Parameters.member.${index + 1}.ParameterValue`] = param.ParameterValue
+      })
+    }
+
+    if (options.capabilities) {
+      options.capabilities.forEach((cap, index) => {
+        params[`Capabilities.member.${index + 1}`] = cap
+      })
+    }
+
+    if (options.changeSetType) {
+      params.ChangeSetType = options.changeSetType
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    return { Id: result.Id, StackId: result.StackId }
+  }
+
+  /**
+   * Describe change set
+   */
+  async describeChangeSet(stackName: string, changeSetName: string): Promise<any> {
+    const params: Record<string, any> = {
+      Action: 'DescribeChangeSet',
+      StackName: stackName,
+      ChangeSetName: changeSetName,
+      Version: '2010-05-15',
+    }
+
+    return await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+  }
+
+  /**
+   * Execute change set
+   */
+  async executeChangeSet(stackName: string, changeSetName: string): Promise<void> {
+    const params: Record<string, any> = {
+      Action: 'ExecuteChangeSet',
+      StackName: stackName,
+      ChangeSetName: changeSetName,
+      Version: '2010-05-15',
+    }
+
+    await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+  }
+
+  /**
+   * Delete change set
+   */
+  async deleteChangeSet(stackName: string, changeSetName: string): Promise<void> {
+    const params: Record<string, any> = {
+      Action: 'DeleteChangeSet',
+      StackName: stackName,
+      ChangeSetName: changeSetName,
+      Version: '2010-05-15',
+    }
+
+    await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+  }
+
+  /**
+   * Get stack outputs as key-value pairs
+   */
+  async getStackOutputs(stackName: string): Promise<Record<string, string>> {
+    const result = await this.describeStacks({ stackName })
+
+    if (!result.Stacks || result.Stacks.length === 0) {
+      throw new Error(`Stack ${stackName} not found`)
+    }
+
+    const stack = result.Stacks[0]
+    const outputs: Record<string, string> = {}
+
+    if (stack.Outputs) {
+      for (const output of stack.Outputs) {
+        outputs[output.OutputKey] = output.OutputValue
+      }
+    }
+
+    return outputs
+  }
+
+  /**
+   * Get stack template
+   */
+  async getTemplate(stackName: string): Promise<{ TemplateBody: string }> {
+    const params: Record<string, any> = {
+      Action: 'GetTemplate',
+      StackName: stackName,
+      Version: '2010-05-15',
+    }
+
+    const result = await this.client.request({
+      service: 'cloudformation',
+      region: this.region,
+      method: 'POST',
+      path: '/',
+      body: new URLSearchParams(params).toString(),
+    })
+
+    // Handle the GetTemplateResult wrapper
+    const templateBody = result?.GetTemplateResult?.TemplateBody || result?.TemplateBody || ''
+    return { TemplateBody: templateBody }
+  }
+
+  /**
+   * Parse stacks response
+   */
+  private parseStacksResponse(result: any): Stack[] {
+    const stacks: Stack[] = []
+
+    // Handle different response structures from XML parsing
+    // The XML response is: DescribeStacksResponse > DescribeStacksResult > Stacks > member
+    let stackData = result?.DescribeStacksResult?.Stacks?.member
+      || result?.Stacks?.member
+      || result?.Stacks
+      || result
+
+    // If it's a single stack, wrap in array
+    if (stackData && !Array.isArray(stackData)) {
+      stackData = [stackData]
+    }
+
+    if (Array.isArray(stackData)) {
+      for (const s of stackData) {
+        if (s.StackId || s.StackName) {
+          // Parse outputs
+          let outputs: Array<{ OutputKey: string, OutputValue: string, Description?: string, ExportName?: string }> | undefined
+          if (s.Outputs?.member) {
+            const outputData = Array.isArray(s.Outputs.member) ? s.Outputs.member : [s.Outputs.member]
+            outputs = outputData.map((o: any) => ({
+              OutputKey: o.OutputKey,
+              OutputValue: o.OutputValue,
+              Description: o.Description,
+              ExportName: o.ExportName,
+            }))
+          }
+
+          stacks.push({
+            StackId: s.StackId,
+            StackName: s.StackName,
+            StackStatus: s.StackStatus,
+            CreationTime: s.CreationTime,
+            LastUpdatedTime: s.LastUpdatedTime,
+            StackStatusReason: s.StackStatusReason,
+            Outputs: outputs,
+          })
+        }
+      }
+    }
+    // Fallback for flat response
+    else if (result.StackId) {
+      stacks.push({
+        StackId: result.StackId,
+        StackName: result.StackName,
+        StackStatus: result.StackStatus,
+        CreationTime: result.CreationTime,
+        LastUpdatedTime: result.LastUpdatedTime,
+      })
+    }
+
+    return stacks
+  }
+
+  /**
+   * Parse stack events response
+   */
+  private parseStackEvents(result: any): StackEvent[] {
+    const events: StackEvent[] = []
+
+    // Handle XML response structure: DescribeStackEventsResult > StackEvents > member
+    let eventData = result?.DescribeStackEventsResult?.StackEvents?.member
+      || result?.StackEvents?.member
+      || result?.StackEvents
+      || []
+
+    // If single event, wrap in array
+    if (eventData && !Array.isArray(eventData)) {
+      eventData = [eventData]
+    }
+
+    for (const e of eventData) {
+      if (e.LogicalResourceId) {
+        events.push({
+          Timestamp: e.Timestamp,
+          ResourceType: e.ResourceType,
+          LogicalResourceId: e.LogicalResourceId,
+          ResourceStatus: e.ResourceStatus,
+          ResourceStatusReason: e.ResourceStatusReason,
+        })
+      }
+    }
+
+    return events
+  }
+
+  /**
+   * Wait for stack with real-time progress output (CDK-style)
+   */
+  async waitForStackWithProgress(
+    stackName: string,
+    waitType: 'stack-create-complete' | 'stack-update-complete' | 'stack-delete-complete',
+    onProgress?: (event: {
+      resourceId: string
+      resourceType: string
+      status: string
+      reason?: string
+      timestamp: string
+    }) => void,
+  ): Promise<void> {
+    const targetStatuses = {
+      'stack-create-complete': ['CREATE_COMPLETE'],
+      'stack-update-complete': ['UPDATE_COMPLETE'],
+      'stack-delete-complete': ['DELETE_COMPLETE'],
+    }
+
+    const failureStatuses = [
+      'CREATE_FAILED',
+      'ROLLBACK_FAILED',
+      'ROLLBACK_COMPLETE',
+      'UPDATE_ROLLBACK_FAILED',
+      'UPDATE_ROLLBACK_COMPLETE',
+    ]
+
+    const targets = targetStatuses[waitType]
+    const maxAttempts = 360 // 30 minutes (DNS records can take 10-30 minutes)
+    let attempts = 0
+    const seenEvents = new Set<string>()
+
+    while (attempts < maxAttempts) {
+      try {
+        // Get stack events for progress
+        if (onProgress) {
+          try {
+            const eventsResult = await this.describeStackEvents(stackName)
+            // Events are returned newest first, reverse for chronological order
+            const events = [...(eventsResult.StackEvents || [])].reverse()
+
+            for (const event of events) {
+              // Create unique key for this event
+              const eventKey = `${event.LogicalResourceId}-${event.ResourceStatus}-${event.Timestamp}`
+
+              if (!seenEvents.has(eventKey)) {
+                seenEvents.add(eventKey)
+                onProgress({
+                  resourceId: event.LogicalResourceId,
+                  resourceType: event.ResourceType,
+                  status: event.ResourceStatus,
+                  reason: event.ResourceStatusReason,
+                  timestamp: event.Timestamp,
+                })
+              }
+            }
+          }
+          catch {
+            // Events might not be available yet, continue
+          }
+        }
+
+        // Check stack status
+        const result = await this.describeStacks({ stackName })
+
+        if (result.Stacks.length === 0) {
+          if (waitType === 'stack-delete-complete') {
+            return // Stack deleted successfully
+          }
+          await new Promise(resolve => setTimeout(resolve, 2000))
+          attempts++
+          continue
+        }
+
+        const stack = result.Stacks[0]
+
+        if (targets.includes(stack.StackStatus)) {
+          return // Target status reached
+        }
+
+        if (stack.StackStatus === 'DELETE_FAILED' && waitType === 'stack-delete-complete') {
+          const error: any = new Error(`Stack deletion failed - may have resources that need to be retained`)
+          error.code = 'DELETE_FAILED'
+          error.stackStatus = stack.StackStatus
+          error.statusReason = stack.StackStatusReason
+          throw error
+        }
+
+        if (failureStatuses.includes(stack.StackStatus)) {
+          throw new Error(`Stack reached failure status: ${stack.StackStatus}`)
+        }
+
+        await new Promise(resolve => setTimeout(resolve, 3000))
+        attempts++
+      }
+      catch (error: any) {
+        if (waitType === 'stack-delete-complete' && error.message?.includes('does not exist')) {
+          return
+        }
+        if (waitType === 'stack-create-complete' && error.message?.includes('does not exist')) {
+          await new Promise(resolve => setTimeout(resolve, 2000))
+          attempts++
+          continue
+        }
+        throw error
+      }
+    }
+
+    throw new Error(`Timeout waiting for stack to reach ${waitType}`)
+  }
+
+  /**
+   * Wait for stack operation to complete (create, update, or delete)
+   * Returns a result object with success status
+   */
+  async waitForStackComplete(
+    stackName: string,
+    maxAttempts: number = 120,
+    delayMs: number = 5000,
+  ): Promise<{ success: boolean; status: string; reason?: string }> {
+    const successStatuses = [
+      'CREATE_COMPLETE',
+      'UPDATE_COMPLETE',
+      'DELETE_COMPLETE',
+    ]
+    const failureStatuses = [
+      'CREATE_FAILED',
+      'UPDATE_FAILED',
+      'DELETE_FAILED',
+      'ROLLBACK_COMPLETE',
+      'ROLLBACK_FAILED',
+      'UPDATE_ROLLBACK_COMPLETE',
+      'UPDATE_ROLLBACK_FAILED',
+    ]
+
+    for (let i = 0; i < maxAttempts; i++) {
+      try {
+        const result = await this.describeStacks({ stackName })
+
+        if (result.Stacks.length === 0) {
+          // Stack was deleted
+          return { success: true, status: 'DELETE_COMPLETE' }
+        }
+
+        const stack = result.Stacks[0]
+        const status = stack.StackStatus
+
+        if (successStatuses.includes(status)) {
+          return { success: true, status }
+        }
+
+        if (failureStatuses.includes(status)) {
+          return { success: false, status, reason: stack.StackStatusReason }
+        }
+
+        // Still in progress, wait and retry
+        await new Promise(resolve => setTimeout(resolve, delayMs))
+      }
+      catch (error: any) {
+        if (error.message?.includes('does not exist')) {
+          return { success: true, status: 'DELETE_COMPLETE' }
+        }
+        throw error
+      }
+    }
+
+    return { success: false, status: 'TIMEOUT', reason: 'Timeout waiting for stack operation' }
+  }
+}