feat(toolkit): add a return type for toolkit.deploy() (#317)

`toolkit.deploy()` now returns information about the stacks it deployed.

Fixes aws/aws-cdk#33189

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

---------

Signed-off-by: github-actions <[email protected]>
Co-authored-by: github-actions <[email protected]>

Author: rix0rrr

packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/schema.ts

@@ -100,7 +100,12 @@ export interface ArtifactManifest {
   readonly properties?: ArtifactProperties;
 
   /**
-   * A string that represents this artifact. Should only be used in user interfaces.
+   * A string that can be shown to a user to uniquely identify this artifact inside a cloud assembly tree
+   *
+   * Is used by the CLI to present a list of stacks to the user in a way that
+   * makes sense to them. Even though the property name "display name" doesn't
+   * imply it, this field is used to select stacks as well, so all stacks should
+   * have a unique display name.
    *
    * @default - no display name
    */

packages/@aws-cdk/cloud-assembly-schema/schema/cloud-assembly.schema.json

@@ -83,7 +83,7 @@
                     ]
                 },
                 "displayName": {
-                    "description": "A string that represents this artifact. Should only be used in user interfaces. (Default - no display name)",
+                    "description": "A string that can be shown to a user to uniquely identify this artifact inside a cloud assembly tree\n\nIs used by the CLI to present a list of stacks to the user in a way that\nmakes sense to them. Even though the property name \"display name\" doesn't\nimply it, this field is used to select stacks as well, so all stacks should\nhave a unique display name. (Default - no display name)",
                     "type": "string"
                 }
             },

packages/@aws-cdk/cloud-assembly-schema/schema/version.json

@@ -1,4 +1,4 @@
 {
-  "schemaHash": "78936b0f9299bbe47497dd77f8065d71e65d8d739a0413ad7698ad03b22ef83e",
+  "schemaHash": "96958a4c40e0a00e850f0c14dd6e9c0fc8db0b075f1f155cea41ab198c0514be",
   "revision": 43
 }

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

@@ -1,2 +1,4 @@
 export * from './toolkit';
 export * from './non-interactive-io-host';
+export * from './types';
+export * from '../api/shared-public';

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

@@ -6,6 +6,7 @@ import * as fs from 'fs-extra';
 import { NonInteractiveIoHost } from './non-interactive-io-host';
 import type { ToolkitServices } from './private';
 import { assemblyFromSource } from './private';
+import type { DeployResult } from './types';
 import type { BootstrapEnvironments, BootstrapOptions, BootstrapResult, EnvironmentBootstrapResult } from '../actions/bootstrap';
 import { BootstrapSource } from '../actions/bootstrap';
 import { AssetBuildTime, type DeployOptions } from '../actions/deploy';
@@ -322,7 +323,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
    *
    * Deploys the selected stacks into an AWS account
    */
-  public async deploy(cx: ICloudAssemblySource, options: DeployOptions = {}): Promise<void> {
+  public async deploy(cx: ICloudAssemblySource, options: DeployOptions = {}): Promise<DeployResult> {
     const ioHelper = asIoHelper(this.ioHost, 'deploy');
     const assembly = await assemblyFromSource(ioHelper, cx);
     return this._deploy(assembly, 'deploy', options);
@@ -331,17 +332,21 @@ export class Toolkit extends CloudAssemblySourceBuilder {
   /**
    * Helper to allow deploy being called as part of the watch action.
    */
-  private async _deploy(assembly: StackAssembly, action: 'deploy' | 'watch', options: ExtendedDeployOptions = {}) {
+  private async _deploy(assembly: StackAssembly, action: 'deploy' | 'watch', options: ExtendedDeployOptions = {}): Promise<DeployResult> {
     const ioHelper = asIoHelper(this.ioHost, action);
     const selectStacks = options.stacks ?? ALL_STACKS;
     const synthSpan = await ioHelper.span(SPAN.SYNTH_ASSEMBLY).begin({ stacks: selectStacks });
     const stackCollection = await assembly.selectStacksV2(selectStacks);
     await this.validateStacksMetadata(stackCollection, ioHelper);
     const synthDuration = await synthSpan.end();
 
+    const ret: DeployResult = {
+      stacks: [],
+    };
+
     if (stackCollection.stackCount === 0) {
       await ioHelper.notify(IO.CDK_TOOLKIT_E5001.msg('This app contains no stacks'));
-      return;
+      return ret;
     }
 
     const deployments = await this.deploymentsForAction('deploy');
@@ -564,6 +569,17 @@ export class Toolkit extends CloudAssemblySourceBuilder {
           await ioHelper.notify(IO.CDK_TOOLKIT_I5901.msg(buffer.join('\n')));
         }
         await ioHelper.notify(IO.CDK_TOOLKIT_I5901.msg(`Stack ARN:\n${deployResult.stackArn}`));
+
+        ret.stacks.push({
+          stackName: stack.stackName,
+          environment: {
+            account: stack.environment.account,
+            region: stack.environment.region,
+          },
+          stackArn: deployResult.stackArn,
+          outputs: deployResult.outputs,
+          hierarchicalId: stack.hierarchicalId,
+        });
       } catch (e: any) {
         // It has to be exactly this string because an integration test tests for
         // "bold(stackname) failed: ResourceNotReady: <error>"
@@ -624,6 +640,8 @@ export class Toolkit extends CloudAssemblySourceBuilder {
       buildAsset,
       publishAsset,
     });
+
+    return ret;
   }
 
   /**

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

@@ -0,0 +1,130 @@
+/**
+ * Result interface for toolkit.deploy operation
+ */
+export interface DeployResult {
+  /**
+   * Map of deployed stacks by artifact ID.
+   */
+  readonly stacks: DeployedStack[];
+}
+
+/**
+ * Information about a deployed stack
+ */
+export interface DeployedStack {
+  /**
+   * The name of the deployed stack
+   *
+   * A stack name is unique inside its environment, but not unique globally.
+   */
+  readonly stackName: string;
+
+  /**
+   * The environment where the stack was deployed
+   *
+   * This environment is always concrete, because even though the CDK app's
+   * stack may be region-agnostic, in order to be deployed it will have to have
+   * been specialized.
+   */
+  readonly environment: Environment;
+
+  /**
+   * Hierarchical identifier
+   *
+   * This uniquely identifies the stack inside the CDK app.
+   *
+   * In practice this will be the stack's construct path, but unfortunately the
+   * Cloud Assembly contract doesn't require or guarantee that.
+   */
+  readonly hierarchicalId: string;
+
+  /**
+   * The ARN of the deployed stack
+   */
+  readonly stackArn: string;
+
+  /**
+   * The outputs of the deployed CloudFormation stack
+   */
+  readonly outputs: { [key: string]: string };
+}
+
+/**
+ * An environment, which is an (account, region) pair
+ */
+export interface Environment {
+  /**
+   * The account number
+   */
+  readonly account: string;
+
+  /**
+   * The region number
+   */
+  readonly region: string;
+}
+/**
+ * Result interface for toolkit.deploy operation
+ */
+export interface DeployResult {
+  /**
+   * List of stacks deployed by this operation
+   */
+  readonly stacks: DeployedStack[];
+}
+
+/**
+ * Information about a deployed stack
+ */
+export interface DeployedStack {
+  /**
+   * The name of the deployed stack
+   *
+   * A stack name is unique inside its environment, but not unique globally.
+   */
+  readonly stackName: string;
+
+  /**
+   * The environment where the stack was deployed
+   *
+   * This environment is always concrete, because even though the CDK app's
+   * stack may be region-agnostic, in order to be deployed it will have to have
+   * been specialized.
+   */
+  readonly environment: Environment;
+
+  /**
+   * Hierarchical identifier
+   *
+   * This uniquely identifies the stack inside the CDK app.
+   *
+   * In practice this will be the stack's construct path, but unfortunately the
+   * Cloud Assembly contract doesn't require or guarantee that.
+   */
+  readonly hierarchicalId: string;
+
+  /**
+   * The ARN of the deployed stack
+   */
+  readonly stackArn: string;
+
+  /**
+   * The outputs of the deployed CloudFormation stack
+   */
+  readonly outputs: { [key: string]: string };
+}
+
+/**
+ * An environment, which is an (account, region) pair
+ */
+export interface Environment {
+  /**
+   * The account number
+   */
+  readonly account: string;
+
+  /**
+   * The region number
+   */
+  readonly region: string;
+}

packages/@aws-cdk/toolkit-lib/test/_fixtures/nested-assembly/app.ts

@@ -0,0 +1,7 @@
+import * as cdk from 'aws-cdk-lib/core';
+
+const app = new cdk.App({ autoSynth: false });
+const stage = new cdk.Stage(app, 'Stage');
+new cdk.Stack(stage, 'Stack1');
+
+app.synth();

packages/@aws-cdk/toolkit-lib/test/_fixtures/nested-assembly/cdk.json

@@ -0,0 +1,3 @@
+{
+  "app": "$(npx -c 'which tsx') app.ts"
+}

packages/@aws-cdk/toolkit-lib/test/_fixtures/nested-assembly/cdk.out/assembly-Stage/StageStack130339B27.assets.json

@@ -0,0 +1,19 @@
+{
+  "version": "40.0.0",
+  "files": {
+    "7f4fb64a3afca08edbdbaa369e00317cb253697278406a83c78e849e89045f9d": {
+      "source": {
+        "path": "StageStack130339B27.template.json",
+        "packaging": "file"
+      },
+      "destinations": {
+        "current_account-current_region": {
+          "bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
+          "objectKey": "7f4fb64a3afca08edbdbaa369e00317cb253697278406a83c78e849e89045f9d.json",
+          "assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
+        }
+      }
+    }
+  },
+  "dockerImages": {}
+}