refactor(toolkit-lib): move message definitions to shared package (#220)

Move the message definitions to the shared package and make them public.
This also required moving a bunch of type definitions to the shared
package because they are used as payloads for the message types.

In the CLI it's now possible to access those numbers and access their
associated payload types in a type-checked way.

A type-safe `switch` statement now looks like this:

<img width="583" alt="image"
src="https://github.com/user-attachments/assets/01c1cbf6-2e1a-4b8f-bd5c-180f72ff2f55"
/>

This change also makes the `data` field of an `IoMessage` required. The
type of a message without payload is now `IoMessage<void>`: `data: void`
is only inhabited by `data: undefined` which sort of tracks because
`m.data === undefined` even if there is no payload (don't look too
closely at the different behavior for `'data' in m` 😎 ). The type can no
longer be `never` because a type like `{ data: never }` can not be
inhabited by any values. We could also use `data: undefined`, *also*
only admitting `undefined`, but `void` reads more clearly for its
intent.

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

Author: rix0rrr

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/index.ts

@@ -1,3 +1,5 @@
 export * from './io-host';
 export * from './io-message';
 export * from './toolkit-action';
+export * from './payloads';
+export * from './messages';

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

@@ -62,7 +62,7 @@ export interface IoMessage<T> {
   /**
    * The data attached to the message.
    */
-  readonly data?: T;
+  readonly data: T;
 }
 
 /**

packages/@aws-cdk/toolkit-lib/lib/api/io/private/messages.ts renamed to packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/messages.ts

@@ -1,15 +1,15 @@
 import type * as cxapi from '@aws-cdk/cx-api';
-import type { SdkTrace } from '../';
-import type { BootstrapEnvironmentProgress } from '../../../actions/bootstrap';
-import type { DeployConfirmationRequest, StackDeployProgress } from '../../../actions/deploy';
-import type { StackDestroyProgress } from '../../../actions/destroy';
-import type { StackDetailsPayload } from '../../../actions/list';
-import type { StackRollbackProgress } from '../../../actions/rollback';
-import type { FileWatchEvent, WatchSettings } from '../../../actions/watch';
-import type { AssemblyData, ConfirmationRequest, Duration, ErrorPayload, StackAndAssemblyData, SuccessfulDeployStackResult } from '../../../toolkit/types';
-import type { StackActivity, StackMonitoringControlEvent } from '../../aws-cdk';
-import type { MissingContext, UpdatedContext } from '../../cloud-assembly/context';
-import * as make from '../../shared-private';
+import type { BootstrapEnvironmentProgress } from './payloads/bootstrap-environment-progress';
+import type { MissingContext, UpdatedContext } from './payloads/context';
+import type { DeployConfirmationRequest, StackDeployProgress, SuccessfulDeployStackResult } from './payloads/deploy';
+import type { StackDestroyProgress } from './payloads/destroy';
+import type { StackDetailsPayload } from './payloads/list';
+import type { StackRollbackProgress } from './payloads/rollback';
+import type { SdkTrace } from './payloads/sdk-trace';
+import type { StackActivity, StackMonitoringControlEvent } from './payloads/stack-activity';
+import type { AssemblyData, ConfirmationRequest, Duration, ErrorPayload, StackAndAssemblyData } from './payloads/types';
+import type { FileWatchEvent, WatchSettings } from './payloads/watch';
+import * as make from './private';
 
 /**
  * We have a rough system by which we assign message codes:
@@ -328,6 +328,10 @@ export const IO = {
   }),
 
   // SDK codes
+  CDK_SDK_I0000: make.trace({
+    code: 'CDK_SDK_I0000',
+    description: 'An SDK message.',
+  }),
   CDK_SDK_I0100: make.trace<SdkTrace>({
     code: 'CDK_SDK_I0100',
     description: 'An SDK trace. SDK traces are emitted as traces to the IoHost, but contain the original SDK logging level.',

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/bootstrap-environment-progress.ts

@@ -0,0 +1,18 @@
+import type * as cxapi from '@aws-cdk/cx-api';
+
+export interface BootstrapEnvironmentProgress {
+  /**
+   * The total number of environments being deployed
+   */
+  readonly total: number;
+  /**
+   * The count of the environment currently bootstrapped
+   *
+   * This is counting value, not an identifier.
+   */
+  readonly current: number;
+  /**
+   * The environment that's currently being bootstrapped
+   */
+  readonly environment: cxapi.Environment;
+}

packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/context.ts renamed to packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/context.ts

@@ -0,0 +1,57 @@
+import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
+import type { PermissionChangeType } from './diff';
+import type { ConfirmationRequest } from './types';
+
+export interface StackDeployProgress {
+  /**
+   * The total number of stacks being deployed
+   */
+  readonly total: number;
+  /**
+   * The count of the stack currently attempted to be deployed
+   *
+   * This is counting value, not an identifier.
+   */
+  readonly current: number;
+  /**
+   * The stack that's currently being deployed
+   */
+  readonly stack: CloudFormationStackArtifact;
+}
+
+/**
+ * Payload for a yes/no confirmation in deploy. Includes information on
+ * what kind of change is being made.
+ */
+export interface DeployConfirmationRequest extends ConfirmationRequest {
+  /**
+   * The type of change being made to the IAM permissions.
+   */
+  readonly permissionChangeType: PermissionChangeType;
+}
+
+export type DeployStackResult =
+  | SuccessfulDeployStackResult
+  | NeedRollbackFirstDeployStackResult
+  | ReplacementRequiresRollbackStackResult
+  ;
+
+/** Successfully deployed a stack */
+export interface SuccessfulDeployStackResult {
+  readonly type: 'did-deploy-stack';
+  readonly noOp: boolean;
+  readonly outputs: { [name: string]: string };
+  readonly stackArn: string;
+}
+
+/** The stack is currently in a failpaused state, and needs to be rolled back before the deployment */
+export interface NeedRollbackFirstDeployStackResult {
+  readonly type: 'failpaused-need-rollback-first';
+  readonly reason: 'not-norollback' | 'replacement';
+  readonly status: string;
+}
+
+/** The upcoming change has a replacement, which requires deploying with --rollback */
+export interface ReplacementRequiresRollbackStackResult {
+  readonly type: 'replacement-requires-rollback';
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/deploy.ts

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

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/destroy.ts

@@ -0,0 +1,19 @@
+/**
+ * Different types of permission related changes in a diff
+ */
+export enum PermissionChangeType {
+  /**
+   * No permission changes
+   */
+  NONE = 'none',
+
+  /**
+   * Permissions are broadening
+   */
+  BROADENING = 'broadening',
+
+  /**
+   * Permissions are changed but not broadening
+   */
+  NON_BROADENING = 'non-broadening',
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/diff.ts

@@ -0,0 +1,13 @@
+export * from './bootstrap-environment-progress';
+export * from './deploy';
+export * from './destroy';
+export * from './list';
+export * from './sdk-trace';
+export * from './context';
+export * from './rollback';
+export * from './stack-activity';
+export * from './types';
+export * from './progress';
+export * from './watch';
+export * from './stack-details';
+export * from './diff';

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/index.ts

@@ -0,0 +1,5 @@
+import type { StackDetails } from './stack-details';
+
+export interface StackDetailsPayload {
+  stacks: StackDetails[];
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/list.ts

@@ -0,0 +1,17 @@
+export interface StackProgress {
+  /**
+   * The total number of progress monitored resources.
+   */
+  readonly total?: number;
+
+  /**
+   * The number of completed resources.
+   */
+  readonly completed: number;
+
+  /**
+   * The current progress as a [34/42] string, or just [34] if the total is unknown.
+   */
+  readonly formatted: string;
+}
+

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/progress.ts

@@ -0,0 +1,18 @@
+import type { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
+
+export interface StackRollbackProgress {
+  /**
+   * The total number of stacks being rolled back
+   */
+  readonly total: number;
+  /**
+   * The count of the stack currently attempted to be rolled back
+   *
+   * This is counting value, not an identifier.
+   */
+  readonly current: number;
+  /**
+   * The stack that's currently being rolled back
+   */
+  readonly stack: CloudFormationStackArtifact;
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/rollback.ts

@@ -0,0 +1,21 @@
+/**
+ * An SDK logging trace.
+ *
+ * Only info, warn and error level messages are emitted.
+ * SDK traces are emitted as traces to the IoHost, but contain the original SDK logging level.
+ */
+export interface SdkTrace {
+  /**
+   * The level the SDK has emitted the original message with
+   */
+  readonly sdkLevel: 'info' | 'warn' | 'error';
+
+  /**
+   * The content of the SDK trace
+   *
+   * This will include the request and response data for API calls, including potentially sensitive information.
+   *
+   * @see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/logging-sdk-calls.html
+   */
+  readonly content: any;
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/sdk-trace.ts

@@ -0,0 +1,63 @@
+import { type MetadataEntry } from '@aws-cdk/cloud-assembly-schema';
+import { type CloudFormationStackArtifact } from '@aws-cdk/cx-api';
+import type { StackEvent } from '@aws-sdk/client-cloudformation';
+import type { StackProgress } from './progress';
+
+/**
+ * Payload when stack monitoring is starting or stopping for a given stack deployment.
+ */
+export interface StackMonitoringControlEvent {
+  /**
+   * A unique identifier for a specific stack deployment.
+   *
+   * Use this value to attribute stack activities received for concurrent deployments.
+   */
+  readonly deployment: string;
+
+  /**
+   * The stack artifact that is getting deployed
+   */
+  readonly stack: CloudFormationStackArtifact;
+
+  /**
+   * The name of the Stack that is getting deployed
+   */
+  readonly stackName: string;
+
+  /**
+   * Total number of resources taking part in this deployment
+   *
+   * The number might not always be known or accurate.
+   * Only use for informational purposes and handle the case when it's unavailable.
+   */
+  readonly resourcesTotal?: number;
+}
+
+export interface StackActivity {
+  /**
+   * A unique identifier for a specific stack deployment.
+   *
+   * Use this value to attribute stack activities received for concurrent deployments.
+   */
+  readonly deployment: string;
+
+  /**
+   * The Stack Event as received from CloudFormation
+   */
+  readonly event: StackEvent;
+
+  /**
+   * Additional resource metadata
+   */
+  readonly metadata?: ResourceMetadata;
+
+  /**
+   * The stack progress
+   */
+  readonly progress: StackProgress;
+}
+
+export interface ResourceMetadata {
+  entry: MetadataEntry;
+  constructPath: string;
+}

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/stack-activity.ts

@@ -0,0 +1,20 @@
+import type * as cxapi from '@aws-cdk/cx-api';
+
+/**
+ * The dependencies of a stack.
+ */
+export interface StackDependency {
+  id: string;
+  dependencies: StackDependency[];
+}
+
+/**
+ * Details of a stack.
+ */
+export interface StackDetails {
+  id: string;
+  name: string;
+  environment: cxapi.Environment;
+  dependencies: StackDependency[];
+}
+

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/stack-details.ts

@@ -1,5 +1,3 @@
-import type { SuccessfulDeployStackResult as _SuccessfulDeployStackResult } from '../api/aws-cdk';
-
 /**
  * Assembly data returned in the payload of an IO Message.
  */
@@ -20,13 +18,6 @@ export interface AssemblyData {
   readonly stackIds: string[];
 }
 
-/**
- * A successful deploy stack result. Intentionally exposed in toolkit-lib so documentation
- * can be generated from this interface.
- */
-export interface SuccessfulDeployStackResult extends _SuccessfulDeployStackResult {
-}
-
 /**
  * Stack data returned in the payload of an IO Message.
  */

packages/@aws-cdk/toolkit-lib/lib/toolkit/types.ts renamed to packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/types.ts

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

packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/watch.ts

@@ -14,6 +14,7 @@ export type ActionLessRequest<T, U> = Omit<IoRequest<T, U>, 'action'>;
  */
 export interface IoHelper extends IIoHost {
   notify(msg: ActionLessMessage<unknown>): Promise<void>;
+  notify<T>(msg: ActionLessMessage<T>): Promise<void>;
   requestResponse<T, U>(msg: ActionLessRequest<T, U>): Promise<U>;
 }