feat(toolkit-lib): additional messages contain structured data

.projenrc.ts

@@ -1249,7 +1249,7 @@ toolkitLib.package.addField('exports', {
   './package.json': './package.json',
 });
 
-toolkitLib.postCompileTask.exec('ts-node scripts/gen-code-registry.ts');
+toolkitLib.postCompileTask.exec('ts-node --prefer-ts-exts scripts/gen-code-registry.ts');
 toolkitLib.postCompileTask.exec('node build-tools/bundle.mjs');
 // Smoke test built JS files
 toolkitLib.postCompileTask.exec('node ./lib/index.js >/dev/null 2>/dev/null </dev/null');

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/private/message-maker.ts

@@ -1,5 +1,5 @@
 import { IoMessageCode, IoMessageLevel } from '../io-message';
-import { ActionLessMessage } from './action-aware';
+import { ActionLessMessage, ActionLessRequest } from './action-aware';
 
 /**
  * Information for each IO Message Code.
@@ -8,12 +8,12 @@ interface CodeInfo {
   /**
    * The message code.
    */
-  code: IoMessageCode;
+  readonly code: IoMessageCode;
 
   /**
    * A brief description of the meaning of this IO Message.
    */
-  description: string;
+  readonly description: string;
 
   /**
    * The name of the payload interface, if applicable.
@@ -24,7 +24,7 @@ interface CodeInfo {
    * The interface _must_ be exposed directly from toolkit-lib, so that it will
    * have a documentation page generated (that can be linked to).
    */
-  interface?: string;
+  readonly interface?: string;
 }
 
 /**
@@ -34,7 +34,7 @@ interface MessageInfo extends CodeInfo {
   /**
    * The message level
    */
-  level: IoMessageLevel;
+  readonly level: IoMessageLevel;
 }
 
 /**
@@ -50,28 +50,79 @@ export interface IoMessageMaker<T> extends MessageInfo {
 /**
  * Produce an IoMessageMaker for the provided level and code info.
  */
-function generic<T = never>(level: IoMessageLevel, details: CodeInfo): IoMessageMaker<T> {
-  const msg = (message: string, data: T) => ({
+function message<T = never>(level: IoMessageLevel, details: CodeInfo): IoMessageMaker<T> {
+  const maker = (text: string, data: T) => ({
     time: new Date(),
     level,
     code: details.code,
-    message: message,
-    data: data,
+    message: text,
+    data,
   } as ActionLessMessage<T>);
 
   return {
     ...details,
     level,
-    msg: msg as any,
+    msg: maker as any,
   };
 }
 
+/**
+ * A type that is impossible for a user to replicate
+ * This is used to ensure that results always have a proper type generic declared.
+ */
+declare const privateKey: unique symbol;
+export type ImpossibleType = {
+  readonly [privateKey]: typeof privateKey;
+};
+
 // Create `IoMessageMaker`s for a given level and type check that calls with payload are using the correct interface
 type CodeInfoMaybeInterface<T> = [T] extends [never] ? Omit<CodeInfo, 'interface'> : Required<CodeInfo>;
 
-export const trace = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('trace', details);
-export const debug = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('debug', details);
-export const info = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('info', details);
-export const warn = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('warn', details);
-export const error = <T = never>(details: CodeInfoMaybeInterface<T>) => generic<T>('error', details);
-export const result = <T extends object>(details: Required<CodeInfo>) => generic<T extends object ? T : never>('result', details);
+export const trace = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('trace', details);
+export const debug = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('debug', details);
+export const info = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('info', details);
+export const warn = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('warn', details);
+export const error = <T = never>(details: CodeInfoMaybeInterface<T>) => message<T>('error', details);
+export const result = <T extends object = ImpossibleType>(details: Required<CodeInfo>) => message<T extends object ? T : never>('result', details);
+
+interface RequestInfo<U> extends CodeInfo {
+  readonly defaultResponse: U;
+}
+
+/**
+ * An interface that can produce messages for a specific code.
+ */
+export interface IoRequestMaker<T, U> extends MessageInfo {
+  /**
+   * Create a message for this code, with or without payload.
+   */
+  req: [T] extends [never] ? (message: string) => ActionLessMessage<never> : (message: string, data: T) => ActionLessRequest<T, U>;
+}
+
+/**
+ * Produce an IoMessageMaker for the provided level and code info.
+ */
+function request<T = never, U = ImpossibleType>(level: IoMessageLevel, details: RequestInfo<U>): IoRequestMaker<T, U> {
+  const maker = (text: string, data: T) => ({
+    time: new Date(),
+    level,
+    code: details.code,
+    message: text,
+    data,
+    defaultResponse: details.defaultResponse,
+  } as ActionLessRequest<T, U>);
+
+  return {
+    ...details,
+    level,
+    req: maker as any,
+  };
+}
+
+/**
+ * A request that is a simple yes/no question, with the expectation that 'yes' is the default.
+ */
+export const confirm = <T extends object = ImpossibleType>(details: Required<Omit<RequestInfo<boolean>, 'defaultResponse'>>) => request<T, boolean>('info', {
+  ...details,
+  defaultResponse: true,
+});

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

@@ -2,6 +2,9 @@
 
 | Code | Description | Level | Data Interface |
 |------|-------------|-------|----------------|
+| CDK_TOOLKIT_I0000 | Default info messages emitted from the Toolkit | info | n/a |
+| CDK_TOOLKIT_I0000 | Default debug messages emitted from the Toolkit | debug | n/a |
+| CDK_TOOLKIT_W0000 | Default warning messages emitted from the Toolkit | warn | n/a |
 | CDK_TOOLKIT_I1000 | Provides synthesis times. | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
 | CDK_TOOLKIT_I1901 | Provides stack data | result | [StackAndAssemblyData](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackAndAssemblyData.html) |
 | CDK_TOOLKIT_I1902 | Successfully deployed stacks | result | [AssemblyData](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/AssemblyData.html) |
@@ -10,29 +13,52 @@
 | CDK_TOOLKIT_I5000 | Provides deployment times | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
 | CDK_TOOLKIT_I5001 | Provides total time in deploy action, including synth and rollback | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
 | CDK_TOOLKIT_I5002 | Provides time for resource migration | info | n/a |
+| CDK_TOOLKIT_W5021 | Empty non-existent stack, deployment is skipped | warn | n/a |
+| CDK_TOOLKIT_W5022 | Empty existing stack, stack will be destroyed | warn | n/a |
 | 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_I5050 | Confirm rollback during deployment | info | [ConfirmationRequest](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ConfirmationRequest.html) |
+| CDK_TOOLKIT_I5060 | Confirm deploy security sensitive changes | info | [ConfirmationRequest](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ConfirmationRequest.html) |
+| CDK_TOOLKIT_I5100 | Stack deploy progress | info | [StackDeployProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackDeployProgress.html) |
+| CDK_TOOLKIT_I5310 | The computed settings used for file watching | debug | [WatchSettings](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/WatchSettings.html) |
+| CDK_TOOLKIT_I5311 | File watching started | info | [FileWatchEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/FileWatchEvent.html) |
+| CDK_TOOLKIT_I5312 | File event detected, starting deployment | info | [FileWatchEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/FileWatchEvent.html) |
+| CDK_TOOLKIT_I5313 | File event detected during active deployment, changes are queued | info | [FileWatchEvent](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/FileWatchEvent.html) |
+| CDK_TOOLKIT_I5314 | Initial watch deployment started | info | n/a |
+| CDK_TOOLKIT_I5315 | Queued watch deployment started | 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_I5901 | Generic deployment success messages | info | n/a |
+| CDK_TOOLKIT_W5400 | Hotswap disclosure message | warn | n/a |
 | 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 | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
+| CDK_TOOLKIT_I6100 | Stack rollback progress | info | [StackRollbackProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackRollbackProgress.html) |
 | CDK_TOOLKIT_E6001 | No stacks found | error | n/a |
-| CDK_TOOLKIT_E6900 | Rollback failed | error | n/a |
+| CDK_TOOLKIT_E6900 | Rollback failed | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
 | CDK_TOOLKIT_I7000 | Provides destroy times | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
-| CDK_TOOLKIT_I7010 | Confirm destroy stacks | info | n/a |
+| CDK_TOOLKIT_I7010 | Confirm destroy stacks | info | [ConfirmationRequest](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ConfirmationRequest.html) |
+| CDK_TOOLKIT_I7100 | Stack destroy progress | info | [StackDestroyProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/StackDestroyProgress.html) |
+| CDK_TOOLKIT_I7900 | Stack deletion succeeded | result | [cxapi.CloudFormationStackArtifact](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.CloudFormationStackArtifact.html) |
 | CDK_TOOLKIT_E7010 | Action was aborted due to negative confirmation of request | error | n/a |
-| CDK_TOOLKIT_E7900 | Stack deletion failed | error | n/a |
+| CDK_TOOLKIT_E7900 | Stack deletion failed | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
 | CDK_TOOLKIT_I9000 | Provides bootstrap times | info | [Duration](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/Duration.html) |
-| CDK_TOOLKIT_I9900 | Bootstrap results on success | info | n/a |
-| CDK_TOOLKIT_E9900 | Bootstrap failed | error | n/a |
+| CDK_TOOLKIT_I9100 | Bootstrap progress | info | [BootstrapEnvironmentProgress](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/BootstrapEnvironmentProgress.html) |
+| CDK_TOOLKIT_I9900 | Bootstrap results on success | result | [cxapi.Environment](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.Environment.html) |
+| CDK_TOOLKIT_E9900 | Bootstrap failed | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
+| CDK_ASSEMBLY_I0010 | Generic environment preparation debug messages | debug | n/a |
+| CDK_ASSEMBLY_W0010 | Emitted if the found framework version does not support context overflow | warn | n/a |
 | CDK_ASSEMBLY_I0042 | Writing updated context | debug | [UpdatedContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/UpdatedContext.html) |
-| CDK_ASSEMBLY_I0241 | Fetching missing context | debug | [MissingContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/MissingContext.html) |
+| CDK_ASSEMBLY_I0240 | Context lookup was stopped as no further progress was made.  | debug | [MissingContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/MissingContext.html) |
+| CDK_ASSEMBLY_I0241 | Fetching missing context. This is an iterative message that may appear multiple times with different missing keys. | debug | [MissingContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/MissingContext.html) |
 | CDK_ASSEMBLY_I1000 | Cloud assembly output starts | debug | n/a |
 | CDK_ASSEMBLY_I1001 | Output lines emitted by the cloud assembly to stdout | info | n/a |
 | CDK_ASSEMBLY_E1002 | Output lines emitted by the cloud assembly to stderr | error | n/a |
 | CDK_ASSEMBLY_I1003 | Cloud assembly output finished | info | n/a |
 | CDK_ASSEMBLY_E1111 | Incompatible CDK CLI version. Upgrade needed. | error | [ErrorPayload](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/ErrorPayload.html) |
+| CDK_ASSEMBLY_I0150 | Indicates the use of a pre-synthesized cloud assembly directory | debug | n/a |
+| CDK_ASSEMBLY_I9999 | Annotations emitted by the cloud assembly | info | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.SynthesisMessage.html) |
+| CDK_ASSEMBLY_W9999 | Warnings emitted by the cloud assembly | warn | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.SynthesisMessage.html) |
+| CDK_ASSEMBLY_E9999 | Errors emitted by the cloud assembly | error | [cxapi.SynthesisMessage](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/cxapi.SynthesisMessage.html) |
+| CDK_SDK_I0100 | An SDK trace. SDK traces are emitted as traces to the IoHost, but contain the original SDK logging level. | trace | [UpdatedContext](https://docs.aws.amazon.com/cdk/api/toolkit-lib/interfaces/UpdatedContext.html) |

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

@@ -227,3 +227,20 @@ export class BootstrapSource {
     };
   }
 }
+
+export interface BootstrapEnvironmentProgress {
+  /**
+   * The total number of environments being deployed
+   */
+  total: number;
+  /**
+   * The count of the environment currently bootstrapped
+   *
+   * This is counting value, not an identifier.
+   */
+  current: number;
+  /**
+   * The environment that's currently being bootstrapped
+   */
+  environment: cxapi.Environment;
+}

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

@@ -1,3 +1,4 @@
+import { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
 import type { BaseDeployOptions } from './private/deploy-options';
 import type { Tag } from '../../api/aws-cdk';
 
@@ -210,3 +211,20 @@ export interface HotswapProperties {
    */
   readonly ecs: EcsHotswapProperties;
 }
+
+export interface StackDeployProgress {
+  /**
+   * The total number of stacks being deployed
+   */
+  total: number;
+  /**
+   * The count of the stack currently attempted to be deployed
+   *
+   * This is counting value, not an identifier.
+   */
+  current: number;
+  /**
+   * The stack that's currently being deployed
+   */
+  stack: CloudFormationStackArtifact;
+}

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

@@ -1,3 +1,4 @@
+import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
 import type { StackSelector } from '../../api/cloud-assembly';
 
 export interface DestroyOptions {
@@ -18,3 +19,20 @@ export interface DestroyOptions {
    */
   readonly ci?: boolean;
 }
+
+export interface StackDestroyProgress {
+  /**
+   * The total number of stacks being destroyed
+   */
+  total: number;
+  /**
+   * The count of the stack currently attempted to be destroyed
+   *
+   * This is counting value, not an identifier.
+   */
+  current: number;
+  /**
+   * The stack that's currently being destroyed
+   */
+  stack: CloudFormationStackArtifact;
+}

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

@@ -1,3 +1,4 @@
+import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
 import type { StackSelector } from '../../api/cloud-assembly';
 
 export interface RollbackOptions {
@@ -42,3 +43,20 @@ export interface RollbackOptions {
    */
   readonly validateBootstrapStackVersion?: boolean;
 }
+
+export interface StackRollbackProgress {
+  /**
+   * The total number of stacks being rolled back
+   */
+  total: number;
+  /**
+   * The count of the stack currently attempted to be rolled back
+   *
+   * This is counting value, not an identifier.
+   */
+  current: number;
+  /**
+   * The stack that's currently being rolled back
+   */
+  stack: CloudFormationStackArtifact;
+}

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

@@ -38,3 +38,32 @@ export interface WatchOptions extends BaseDeployOptions {
    */
   readonly outdir?: string;
 }
+
+/**
+ * The computed file watch settings
+ */
+export interface WatchSettings {
+  /**
+   * The directory observed for file changes
+   */
+  watchDir: string;
+  /**
+   * List of include patterns for watching files
+   */
+  includes: string[];
+  /**
+   * List of excludes patterns for watching files
+   */
+  excludes: string[];
+}
+
+export interface FileWatchEvent {
+  /**
+   * The change to the path
+   */
+  event: string;
+  /**
+   * The path that has an observed event
+   */
+  path?: string;
+}

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

@@ -1,7 +1,7 @@
 /* eslint-disable import/no-restricted-paths */
 
 // APIs
-export { formatSdkLoggerContent, SdkProvider } from '../../../../aws-cdk/lib/api/aws-auth';
+export { SdkProvider } from '../../../../aws-cdk/lib/api/aws-auth';
 export { Context, PROJECT_CONTEXT } from '../../../../aws-cdk/lib/api/context';
 export { Deployments, type SuccessfulDeployStackResult } from '../../../../aws-cdk/lib/api/deployments';
 export { Settings } from '../../../../aws-cdk/lib/api/settings';