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[];
+}