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

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 → 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/tmp-toolkit-helpers/src/api/io/payloads/deploy.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/destroy.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/diff.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/index.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/list.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/progress.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/rollback.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/sdk-trace.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/stack-activity.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-details.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/toolkit-lib/lib/toolkit/types.ts → packages/@aws-cdk/tmp-toolkit-helpers/src/api/io/payloads/types.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/tmp-toolkit-helpers/src/api/io/payloads/watch.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/private/io-helper.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>;
 }