feat(toolkit-lib): configurable stack stabilization polling interval on deploy, destroy and prepareStack

[svozza]

Fixes #1723

Motivation

Follow-on to #1709/#1710, which made the StackActivityMonitor event-polling interval (DescribeStackEvents) configurable via stackEventPollingInterval. There's a second hardcoded polling loop that wasn't touched: the stabilization waiter. stabilizeStack() in lib/api/deployments/cfn-api.ts — via the exported waitForStackDeploy()/waitForStackDelete() — calls the module-private waitFor(valueProvider, timeout = 5000), polling DescribeStacks every 5s per in-flight stack to detect a terminal state, with no option threading to it.

Programmatic consumers running large CI matrices who already slowed the event monitor via stackEventPollingInterval saw DescribeStacks from this stabilization loop become the dominant CloudFormation read-API caller instead, still triggering throttling.

Design decision: one parameter, not two

stackEventPollingInterval now governs both the event-polling and stabilization-polling intervals, rather than adding a new sibling parameter (e.g. stackStabilizationPollingInterval). Going with reuse over a second parameter to avoid growing the public options surface on DeployOptions/DestroyOptions for a distinction most consumers won't need to control separately — both loops exist to reduce DescribeStack* call volume against the same CloudFormation rate limit. Happy to split it into a separate parameter in a follow-up if maintainers would rather keep the two tunable independently.

Changes

• Added an optional stabilizationPollingInterval/pollingInterval parameter to waitForStackDelete(), waitForStackDeploy(), and stabilizeStack() in cfn-api.ts. Default unchanged (5000ms).
• Threaded the existing stackEventPollingInterval option through to that new parameter — it already sits right beside the waitForStackDeploy/waitForStackDelete calls in deploy-stack.ts (deploy, destroy, and the delete-before-recreate path).
• Threaded through:
  • deployStack()/destroyStack() in deploy-stack.ts (all three call sites: delete-before-recreate, post-deploy stabilization, post-destroy stabilization)
  • Deployments.cleanupChangeSet() (the change-set cleanup path, called from prepareStack() and from Toolkit.deploy() when a user declines the deploy confirmation prompt)
• Updated doc comments on stackEventPollingInterval at each layer (DeployOptions, DestroyOptions, DeployStackOptions in both deploy-stack.ts and deployments.ts) to note it also governs stabilization polling.
• No public API surface changes — stackEventPollingInterval already existed; only its scope of effect changed, and doc comments were updated to reflect that.

Not included

Per the issue, two call sites needed confirming during implementation:

• waitForStackDelete from Deployments.cleanupChangeSet — included (see above).
• The rollback path (Deployments.rollbackStack), which calls stabilizeStack directly — deferred. This is the same rollback monitor that feat(toolkit-lib): configurable stack event polling interval on deploy and destroy #1710 explicitly deferred for event polling, so leaving it out here keeps this PR consistent with that scope. Happy to add stackEventPollingInterval support to RollbackStackOptions in a follow-up if maintainers want it included.

Testing

• New cfn-api-stabilization-polling-interval.test.ts: directly exercises stabilizeStack, waitForStackDeploy, and waitForStackDelete with fake timers, asserting DescribeStacks polling cadence at both the 5s default and a custom interval.
• Extended deploy-stack-polling-interval.test.ts: asserts deployStack()/destroyStack() forward stackEventPollingInterval to waitForStackDeploy/waitForStackDelete as the stabilization interval, alongside the existing StackActivityMonitor assertions.
• Extended cloudformation-deployments.test.ts: asserts prepareStack() forwards stackEventPollingInterval through cleanupChangeSet() to waitForStackDelete.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.59%. Comparing base (9bf08e5) to head (28c9bca).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1724   +/-   ##
=======================================
  Coverage   89.59%   89.59%           
=======================================
  Files          77       77           
  Lines       11758    11758           
  Branches     1651     1651           
=======================================
  Hits        10534    10534           
  Misses       1195     1195           
  Partials       29       29           

Flag	Coverage Δ
suite.unit	89.59% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.