feat(toolkit): add a return type for toolkit.destroy()

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

Author: rix0rrr

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

@@ -7,7 +7,7 @@ import * as uuid from 'uuid';
 import { NonInteractiveIoHost } from './non-interactive-io-host';
 import type { ToolkitServices } from './private';
 import { assemblyFromSource } from './private';
-import type { DeployResult } from './types';
+import type { DeployResult, DestroyResult } from './types';
 import type { BootstrapEnvironments, BootstrapOptions, BootstrapResult, EnvironmentBootstrapResult } from '../actions/bootstrap';
 import { BootstrapSource } from '../actions/bootstrap';
 import { AssetBuildTime, type DeployOptions } from '../actions/deploy';
@@ -923,7 +923,7 @@ export class Toolkit extends CloudAssemblySourceBuilder {
    *
    * Destroys the selected Stacks.
    */
-  public async destroy(cx: ICloudAssemblySource, options: DestroyOptions): Promise<void> {
+  public async destroy(cx: ICloudAssemblySource, options: DestroyOptions): Promise<DestroyResult> {
     const ioHelper = asIoHelper(this.ioHost, 'destroy');
     const assembly = await assemblyFromSource(ioHelper, cx);
     return this._destroy(assembly, 'destroy', options);
@@ -932,18 +932,23 @@ export class Toolkit extends CloudAssemblySourceBuilder {
   /**
    * Helper to allow destroy being called as part of the deploy action.
    */
-  private async _destroy(assembly: StackAssembly, action: 'deploy' | 'destroy', options: DestroyOptions): Promise<void> {
+  private async _destroy(assembly: StackAssembly, action: 'deploy' | 'destroy', options: DestroyOptions): Promise<DestroyResult> {
     const ioHelper = asIoHelper(this.ioHost, action);
     const synthSpan = await ioHelper.span(SPAN.SYNTH_ASSEMBLY).begin({ stacks: options.stacks });
     // The stacks will have been ordered for deployment, so reverse them for deletion.
     const stacks = (await assembly.selectStacksV2(options.stacks)).reversed();
     await synthSpan.end();
 
+    const ret: DestroyResult = {
+      stacks: [],
+    };
+
     const motivation = 'Destroying stacks is an irreversible action';
     const question = `Are you sure you want to delete: ${chalk.red(stacks.hierarchicalIds.join(', '))}`;
     const confirmed = await ioHelper.requestResponse(IO.CDK_TOOLKIT_I7010.req(question, { motivation }));
     if (!confirmed) {
-      return ioHelper.notify(IO.CDK_TOOLKIT_E7010.msg('Aborted by user'));
+      await ioHelper.notify(IO.CDK_TOOLKIT_E7010.msg('Aborted by user'));
+      return ret;
     }
 
     const destroySpan = await ioHelper.span(SPAN.DESTROY_ACTION).begin({
@@ -959,18 +964,30 @@ export class Toolkit extends CloudAssemblySourceBuilder {
               stack,
             });
           const deployments = await this.deploymentsForAction(action);
-          await deployments.destroyStack({
+          const result = await deployments.destroyStack({
             stack,
             deployName: stack.stackName,
             roleArn: options.roleArn,
           });
+
+          ret.stacks.push({
+            environment: {
+              account: stack.environment.account,
+              region: stack.environment.region,
+            },
+            stackName: stack.stackName,
+            stackArn: result.stackArn,
+          });
+
           await ioHelper.notify(IO.CDK_TOOLKIT_I7900.msg(chalk.green(`\n ✅  ${chalk.blue(stack.displayName)}: ${action}ed`), stack));
           await singleDestroySpan.end();
         } catch (e: any) {
           await ioHelper.notify(IO.CDK_TOOLKIT_E7900.msg(`\n ❌  ${chalk.blue(stack.displayName)}: ${action} failed ${e}`, { error: e }));
           throw e;
         }
       }
+
+      return ret;
     } finally {
       await destroySpan.end();
     }

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

@@ -63,3 +63,42 @@ export interface Environment {
    */
   readonly region: string;
 }
+
+/**
+ * Result interface for toolkit.destroy operation
+ */
+export interface DestroyResult {
+  /**
+   * List of stacks destroyed by this operation
+   */
+  readonly stacks: DestroyedStack[];
+}
+
+/**
+ * A stack targeted by a destroy operation
+ */
+export interface DestroyedStack {
+  /**
+   * The name of the stack
+   *
+   * A stack name is unique inside its environment, but not unique globally.
+   */
+  readonly stackName: string;
+
+  /**
+   * The environment of the stack
+   *
+   * 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;
+
+  /**
+   * The ARN of the stack that was destroyed, if any.
+   *
+   * If the stack didn't exist to begin with, the operation will succeed but
+   * this value will be undefined.
+   */
+  readonly stackArn?: string;
+}

packages/aws-cdk/lib/api/cloudformation/stack-helpers.ts

@@ -85,7 +85,7 @@ export class CloudFormationStack {
   }
 
   /**
-   * The stack's ID
+   * The stack's ID (which is the same as its ARN)
    *
    * Throws if the stack doesn't exist.
    */

packages/aws-cdk/lib/api/deployments/deploy-stack.ts

@@ -663,13 +663,23 @@ export interface DestroyStackOptions {
   deployName?: string;
 }
 
-export async function destroyStack(options: DestroyStackOptions, ioHelper: IoHelper) {
+export interface DestroyStackResult {
+  /**
+   * The ARN of the stack that was destroyed, if any.
+   *
+   * If the stack didn't exist to begin with, the operation will succeed
+   * but this value will be undefined.
+   */
+  readonly stackArn?: string;
+}
+
+export async function destroyStack(options: DestroyStackOptions, ioHelper: IoHelper): Promise<DestroyStackResult> {
   const deployName = options.deployName || options.stack.stackName;
   const cfn = options.sdk.cloudFormation();
 
   const currentStack = await CloudFormationStack.lookup(cfn, deployName);
   if (!currentStack.exists) {
-    return;
+    return {};
   }
   const monitor = new StackActivityMonitor({
     cfn,
@@ -685,6 +695,8 @@ export async function destroyStack(options: DestroyStackOptions, ioHelper: IoHel
     if (destroyedStack && destroyedStack.stackStatus.name !== 'DELETE_COMPLETE') {
       throw new ToolkitError(`Failed to destroy ${deployName}: ${destroyedStack.stackStatus}`);
     }
+
+    return { stackArn: currentStack.stackId };
   } catch (e: any) {
     throw new ToolkitError(suffixWithErrors(formatErrorMessage(e), monitor.errors));
   } finally {

packages/aws-cdk/lib/api/deployments/deployments.ts

@@ -570,7 +570,7 @@ export class Deployments {
     );
   }
 
-  public async destroyStack(options: DestroyStackOptions): Promise<void> {
+  public async destroyStack(options: DestroyStackOptions) {
     const env = await this.envs.accessStackForMutableStackOperations(options.stack);
     const executionRoleArn = await env.replacePlaceholders(options.roleArn ?? options.stack.cloudFormationExecutionRoleArn);