refactor(cli): stack monitor uses io-host (#150)

Provides stack events to the IoHost in a structured way.

The main change here is that `StackActivityMonitor` does not directly
talk to the `ActivityPrinter` anymore. Instead messages are emitted to
the `IoHost`. This caused two related changes:
- Progress tracking has been split into a more generic
`StackProgressMonitor` and progress information is now provided directly
by the `StackActivityMonitor`
- Originally we only had a single timer that covered polling events and
printing them. With the split, we now have two separate timers: one for
polling events and a separate one for updating the view


Removed low-level options:

- `progress` -> now a `CliIoHost` property
- `ci` -> use value from `CliIoHost` directly instead of passing through
all the layers
- `quiet` -> surprisingly this was unused by CLI. We should have
something like this again, but can be implemented in a follow up PR.

Manually tested the changes in addition to integ tests.

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

Author: mrgrain

packages/@aws-cdk/toolkit-lib/CODE_REGISTRY.md

@@ -13,8 +13,12 @@
 | CDK_TOOLKIT_I5031 | Informs about any log groups that are traced as part of the deployment | info | n/a |
 | CDK_TOOLKIT_I5050 | Confirm rollback during deployment | info | n/a |
 | CDK_TOOLKIT_I5060 | Confirm deploy security sensitive changes | info | n/a |
+| CDK_TOOLKIT_I5501 | Stack Monitoring: Start monitoring of a single stack | info | [StackMonitoringControlEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackMonitoringControlEvent.html) |
+| CDK_TOOLKIT_I5502 | Stack Monitoring: Activity event for a single stack | info | [StackActivity](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackActivity.html) |
+| CDK_TOOLKIT_I5503 | Stack Monitoring: Finished monitoring of a single stack | info | [StackMonitoringControlEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackMonitoringControlEvent.html) |
 | CDK_TOOLKIT_I5900 | Deployment results on success | result | [SuccessfulDeployStackResult](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/SuccessfulDeployStackResult.html) |
 | CDK_TOOLKIT_E5001 | No stacks found | error | n/a |
+| CDK_TOOLKIT_E5500 | Stack Monitoring error | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
 | CDK_TOOLKIT_I6000 | Provides rollback times | info | n/a |
 | CDK_TOOLKIT_E6001 | No stacks found | error | n/a |
 | CDK_TOOLKIT_E6900 | Rollback failed | error | n/a |

packages/@aws-cdk/toolkit-lib/lib/actions/deploy/index.ts

@@ -1,5 +1,5 @@
 import type { BaseDeployOptions } from './private/deploy-options';
-import type { StackActivityProgress, Tag } from '../../api/aws-cdk';
+import type { Tag } from '../../api/aws-cdk';
 
 export type DeploymentMethod = DirectDeploymentMethod | ChangeSetDeploymentMethod;
 
@@ -164,16 +164,16 @@ export interface DeployOptions extends BaseDeployOptions {
   /**
    * Change stack watcher output to CI mode.
    *
-   * @deprecated Implement in IoHost instead
+   * @deprecated has no functionality, please implement in your IoHost
    */
   readonly ci?: boolean;
 
   /**
    * Display mode for stack deployment progress.
    *
-   * @deprecated Implement in IoHost instead
+   * @deprecated has no functionality, please implement in your IoHost
    */
-  readonly progress?: StackActivityProgress;
+  readonly progress?: any;
 
   /**
    * Represents configuration property overrides for hotswap deployments.

packages/@aws-cdk/toolkit-lib/lib/api/aws-cdk.ts

@@ -8,7 +8,6 @@ export { Settings } from '../../../../aws-cdk/lib/api/settings';
 export { tagsForStack, Tag } from '../../../../aws-cdk/lib/api/tags';
 export { DEFAULT_TOOLKIT_STACK_NAME } from '../../../../aws-cdk/lib/api/toolkit-info';
 export { ResourceMigrator } from '../../../../aws-cdk/lib/api/resource-import';
-export { StackActivityProgress } from '../../../../aws-cdk/lib/api/stack-events';
 export { CloudWatchLogEventMonitor, findCloudWatchLogGroups } from '../../../../aws-cdk/lib/api/logs';
 export { type WorkGraph, WorkGraphBuilder, AssetBuildNode, AssetPublishNode, StackNode, Concurrency } from '../../../../aws-cdk/lib/api/work-graph';
 

packages/@aws-cdk/toolkit-lib/lib/api/io/private/codes.ts

@@ -109,6 +109,26 @@ export const CODES = {
     description: 'Confirm deploy security sensitive changes',
     level: 'info',
   }),
+
+  CDK_TOOLKIT_I5501: codeInfo({
+    code: 'CDK_TOOLKIT_I5501',
+    description: 'Stack Monitoring: Start monitoring of a single stack',
+    level: 'info',
+    interface: 'StackMonitoringControlEvent',
+  }),
+  CDK_TOOLKIT_I5502: codeInfo({
+    code: 'CDK_TOOLKIT_I5502',
+    description: 'Stack Monitoring: Activity event for a single stack',
+    level: 'info',
+    interface: 'StackActivity',
+  }),
+  CDK_TOOLKIT_I5503: codeInfo({
+    code: 'CDK_TOOLKIT_I5503',
+    description: 'Stack Monitoring: Finished monitoring of a single stack',
+    level: 'info',
+    interface: 'StackMonitoringControlEvent',
+  }),
+
   CDK_TOOLKIT_I5900: codeInfo({
     code: 'CDK_TOOLKIT_I5900',
     description: 'Deployment results on success',
@@ -121,6 +141,12 @@ export const CODES = {
     description: 'No stacks found',
     level: 'error',
   }),
+  CDK_TOOLKIT_E5500: codeInfo({
+    code: 'CDK_TOOLKIT_E5500',
+    description: 'Stack Monitoring error',
+    level: 'error',
+    interface: 'ErrorPayload',
+  }),
 
   // 6: Rollback
   CDK_TOOLKIT_I6000: codeInfo({

packages/@aws-cdk/toolkit-lib/lib/toolkit/toolkit.ts

@@ -15,7 +15,7 @@ import { type SynthOptions } from '../actions/synth';
 import { WatchOptions } from '../actions/watch';
 import { patternsArrayForWatch } from '../actions/watch/private';
 import { type SdkConfig } from '../api/aws-auth';
-import { DEFAULT_TOOLKIT_STACK_NAME, SdkProvider, SuccessfulDeployStackResult, StackCollection, Deployments, HotswapMode, StackActivityProgress, ResourceMigrator, obscureTemplate, serializeStructure, tagsForStack, CliIoHost, validateSnsTopicArn, Concurrency, WorkGraphBuilder, AssetBuildNode, AssetPublishNode, StackNode, formatErrorMessage, CloudWatchLogEventMonitor, findCloudWatchLogGroups, formatTime, StackDetails } from '../api/aws-cdk';
+import { DEFAULT_TOOLKIT_STACK_NAME, SdkProvider, SuccessfulDeployStackResult, StackCollection, Deployments, HotswapMode, ResourceMigrator, obscureTemplate, serializeStructure, tagsForStack, CliIoHost, validateSnsTopicArn, Concurrency, WorkGraphBuilder, AssetBuildNode, AssetPublishNode, StackNode, formatErrorMessage, CloudWatchLogEventMonitor, findCloudWatchLogGroups, formatTime, StackDetails } from '../api/aws-cdk';
 import { ICloudAssemblySource, StackSelectionStrategy } from '../api/cloud-assembly';
 import { ALL_STACKS, CachedCloudAssemblySource, CloudAssemblySourceBuilder, IdentityCloudAssemblySource, StackAssembly } from '../api/cloud-assembly/private';
 import { ToolkitError } from '../api/errors';
@@ -375,8 +375,6 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
             force: options.force,
             parameters: Object.assign({}, parameterMap['*'], parameterMap[stack.stackName]),
             usePreviousParameters: options.parameters?.keepExistingParameters,
-            progress,
-            ci: options.ci,
             rollback,
             hotswap: hotswapMode,
             extraUserAgent: options.extraUserAgent,
@@ -494,10 +492,6 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
     const assetBuildTime = options.assetBuildTime ?? AssetBuildTime.ALL_BEFORE_DEPLOY;
     const prebuildAssets = assetBuildTime === AssetBuildTime.ALL_BEFORE_DEPLOY;
     const concurrency = options.concurrency || 1;
-    const progress = concurrency > 1 ? StackActivityProgress.EVENTS : options.progress;
-    if (concurrency > 1 && options.progress && options.progress != StackActivityProgress.EVENTS) {
-      await ioHost.notify(warn('⚠️ The --concurrency flag only supports --progress "events". Switching to "events".'));
-    }
 
     const stacksAndTheirAssetManifests = stacks.flatMap((stack) => [
       stack,

packages/@aws-cdk/toolkit-lib/lib/toolkit/types.ts

@@ -76,3 +76,13 @@ export interface Duration {
    */
   readonly duration: number;
 }
+
+/**
+ * Generic payload of error IoMessages that pass on an instance of `Error`
+ */
+export interface ErrorPayload {
+  /**
+   * The error that occurred
+   */
+  readonly error: Error;
+}

packages/aws-cdk/lib/api/deployments/deploy-stack.ts

@@ -36,7 +36,7 @@ import type { SDK, SdkProvider, ICloudFormationClient } from '../aws-auth';
 import type { EnvironmentResources } from '../environment';
 import { CfnEvaluationException } from '../evaluate-cloudformation-template';
 import { HotswapMode, HotswapPropertyOverrides, ICON } from '../hotswap/common';
-import { StackActivityMonitor, type StackActivityProgress } from '../stack-events';
+import { StackActivityMonitor } from '../stack-events';
 import { StringWithoutPlaceholders } from '../util/placeholders';
 import { type TemplateBodyParameter, makeBodyParameter } from '../util/template-body-parameter';
 
@@ -105,13 +105,6 @@ export interface DeployStackOptions {
    */
   readonly deployName?: string;
 
-  /**
-   * Quiet or verbose deployment
-   *
-   * @default false
-   */
-  readonly quiet?: boolean;
-
   /**
    * List of asset IDs which shouldn't be built
    *
@@ -153,27 +146,12 @@ export interface DeployStackOptions {
    */
   readonly usePreviousParameters?: boolean;
 
-  /**
-   * Display mode for stack deployment progress.
-   *
-   * @default StackActivityProgress.Bar stack events will be displayed for
-   *   the resource currently being deployed.
-   */
-  readonly progress?: StackActivityProgress;
-
   /**
    * Deploy even if the deployed template is identical to the one we are about to deploy.
    * @default false
    */
   readonly force?: boolean;
 
-  /**
-   * Whether we are on a CI system
-   *
-   * @default false
-   */
-  readonly ci?: boolean;
-
   /**
    * Rollback failed deployments
    *
@@ -612,14 +590,16 @@ class FullCloudFormationDeployment {
   }
 
   private async monitorDeployment(startTime: Date, expectedChanges: number | undefined): Promise<SuccessfulDeployStackResult> {
-    const monitor = this.options.quiet
-      ? undefined
-      : StackActivityMonitor.withDefaultPrinter(this.cfn, this.stackName, this.stackArtifact, {
-        resourcesTotal: expectedChanges,
-        progress: this.options.progress,
-        changeSetCreationTime: startTime,
-        ci: this.options.ci,
-      }).start();
+    const monitor = new StackActivityMonitor({
+      cfn: this.cfn,
+      stack: this.stackArtifact,
+      stackName: this.stackName,
+      resourcesTotal: expectedChanges,
+      ioHost: this.ioHost,
+      action: this.action,
+      changeSetCreationTime: startTime,
+    });
+    await monitor.start();
 
     let finalState = this.cloudFormationStack;
     try {
@@ -631,9 +611,9 @@ class FullCloudFormationDeployment {
       }
       finalState = successStack;
     } catch (e: any) {
-      throw new ToolkitError(suffixWithErrors(formatErrorMessage(e), monitor?.errors));
+      throw new ToolkitError(suffixWithErrors(formatErrorMessage(e), monitor.errors));
     } finally {
-      await monitor?.stop();
+      await monitor.stop();
     }
     debug(this.action, format('Stack %s has completed updating', this.stackName));
     return {
@@ -696,11 +676,14 @@ export async function destroyStack(options: DestroyStackOptions, { ioHost, actio
   if (!currentStack.exists) {
     return;
   }
-  const monitor = options.quiet
-    ? undefined
-    : StackActivityMonitor.withDefaultPrinter(cfn, deployName, options.stack, {
-      ci: options.ci,
-    }).start();
+  const monitor = new StackActivityMonitor({
+    cfn,
+    stack: options.stack,
+    stackName: deployName,
+    ioHost,
+    action,
+  });
+  await monitor.start();
 
   try {
     await cfn.deleteStack({ StackName: deployName, RoleARN: options.roleArn });
@@ -709,7 +692,7 @@ export async function destroyStack(options: DestroyStackOptions, { ioHost, actio
       throw new ToolkitError(`Failed to destroy ${deployName}: ${destroyedStack.stackStatus}`);
     }
   } catch (e: any) {
-    throw new ToolkitError(suffixWithErrors(formatErrorMessage(e), monitor?.errors));
+    throw new ToolkitError(suffixWithErrors(formatErrorMessage(e), monitor.errors));
   } finally {
     if (monitor) {
       await monitor.stop();

packages/aws-cdk/lib/api/deployments/deployments.ts

@@ -31,7 +31,7 @@ import { formatErrorMessage } from '../../util/format-error';
 import type { SdkProvider } from '../aws-auth/sdk-provider';
 import { type EnvironmentResources, EnvironmentAccess } from '../environment';
 import { HotswapMode, HotswapPropertyOverrides } from '../hotswap/common';
-import { StackActivityMonitor, StackActivityProgress, StackEventPoller, RollbackChoice } from '../stack-events';
+import { StackActivityMonitor, StackEventPoller, RollbackChoice } from '../stack-events';
 import type { Tag } from '../tags';
 import { DEFAULT_TOOLKIT_STACK_NAME } from '../toolkit-info';
 import { makeBodyParameter } from '../util/template-body-parameter';
@@ -65,13 +65,6 @@ export interface DeployStackOptions {
    */
   readonly deployName?: string;
 
-  /**
-   * Don't show stack deployment events, just wait
-   *
-   * @default false
-   */
-  readonly quiet?: boolean;
-
   /**
    * Name of the toolkit stack, if not the default name
    *
@@ -135,21 +128,6 @@ export interface DeployStackOptions {
    */
   readonly usePreviousParameters?: boolean;
 
-  /**
-   * Display mode for stack deployment progress.
-   *
-   * @default - StackActivityProgress.Bar - stack events will be displayed for
-   *   the resource currently being deployed.
-   */
-  readonly progress?: StackActivityProgress;
-
-  /**
-   * Whether we are on a CI system
-   *
-   * @default false
-   */
-  readonly ci?: boolean;
-
   /**
    * Rollback failed deployments
    *
@@ -255,14 +233,6 @@ export interface RollbackStackOptions {
    */
   readonly orphanLogicalIds?: string[];
 
-  /**
-   * Display mode for stack deployment progress.
-   *
-   * @default - StackActivityProgress.Bar - stack events will be displayed for
-   *   the resource currently being deployed.
-   */
-  readonly progress?: StackActivityProgress;
-
   /**
    * Whether to validate the version of the bootstrap stack permissions
    *
@@ -463,7 +433,6 @@ export class Deployments {
       resolvedEnvironment: env.resolvedEnvironment,
       deployName: options.deployName,
       notificationArns: options.notificationArns,
-      quiet: options.quiet,
       sdk: env.sdk,
       sdkProvider: this.deployStackSdkProvider,
       roleArn: executionRoleArn,
@@ -474,8 +443,6 @@ export class Deployments {
       force: options.force,
       parameters: options.parameters,
       usePreviousParameters: options.usePreviousParameters,
-      progress: options.progress,
-      ci: options.ci,
       rollback: options.rollback,
       hotswap: options.hotswap,
       hotswapPropertyOverrides: options.hotswapPropertyOverrides,
@@ -565,11 +532,14 @@ export class Deployments {
           throw new ToolkitError(`Unexpected rollback choice: ${cloudFormationStack.stackStatus.rollbackChoice}`);
       }
 
-      const monitor = options.quiet
-        ? undefined
-        : StackActivityMonitor.withDefaultPrinter(cfn, deployName, options.stack, {
-          ci: options.ci,
-        }).start();
+      const monitor = new StackActivityMonitor({
+        cfn,
+        stack: options.stack,
+        stackName: deployName,
+        ioHost: this.ioHost,
+        action: this.action,
+      });
+      await monitor.start();
 
       let stackErrorMessage: string | undefined = undefined;
       let finalStackState = cloudFormationStack;
@@ -582,14 +552,14 @@ export class Deployments {
         }
         finalStackState = successStack;
 
-        const errors = monitor?.errors?.join(', ');
+        const errors = monitor.errors.join(', ');
         if (errors) {
           stackErrorMessage = errors;
         }
       } catch (e: any) {
-        stackErrorMessage = suffixWithErrors(formatErrorMessage(e), monitor?.errors);
+        stackErrorMessage = suffixWithErrors(formatErrorMessage(e), monitor.errors);
       } finally {
-        await monitor?.stop();
+        await monitor.stop();
       }
 
       if (finalStackState.stackStatus.isRollbackSuccess || !stackErrorMessage) {

packages/aws-cdk/lib/api/resource-import/importer.ts

@@ -9,7 +9,6 @@ import { error, info, warn } from '../../cli/messages';
 import { IIoHost, ToolkitAction } from '../../toolkit/cli-io-host';
 import { ToolkitError } from '../../toolkit/error';
 import { assertIsSuccessfulDeployStackResult, type Deployments, DeploymentMethod, ResourceIdentifierProperties, ResourcesToImport } from '../deployments';
-import type { StackActivityProgress } from '../stack-events';
 import type { Tag } from '../tags';
 
 export interface ResourceImporterProps {
@@ -49,14 +48,6 @@ export interface ImportDeploymentOptions {
    */
   readonly usePreviousParameters?: boolean;
 
-  /**
-   * Display mode for stack deployment progress.
-   *
-   * @default - StackActivityProgress.Bar - stack events will be displayed for
-   *   the resource currently being deployed.
-   */
-  readonly progress?: StackActivityProgress;
-
   /**
    * Rollback failed deployments
    *

packages/aws-cdk/lib/api/resource-import/migrator.ts

@@ -67,7 +67,6 @@ export class ResourceMigrator {
       roleArn: options.roleArn,
       deploymentMethod: options.deploymentMethod,
       usePreviousParameters: true,
-      progress: options.progress,
       rollback: options.rollback,
     });