feat(cli): add publish-assets command for asset publishing without deployment

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/publish-assets/cdk-publish-assets-idempotent-and-force.integtest.ts

@@ -0,0 +1,23 @@
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'publish-assets is idempotent and --force re-uploads',
+  withDefaultFixture(async (fixture) => {
+    const stackName = 'lambda';
+    const fullStackName = fixture.fullStackName(stackName);
+
+    // First publish
+    const firstOutput = await fixture.cdk(['publish-assets', fullStackName, '--unstable=publish-assets']);
+    expect(firstOutput).toMatch('Assets published successfully');
+
+    // Second publish without --force should detect nothing to do
+    const secondOutput = await fixture.cdk(['publish-assets', fullStackName, '--unstable=publish-assets']);
+    expect(secondOutput).toMatch('All assets are already published');
+
+    // Third publish with --force should re-upload
+    const forceOutput = await fixture.cdk(['publish-assets', fullStackName, '--unstable=publish-assets', '--force']);
+    expect(forceOutput).toMatch('Assets published successfully');
+  }),
+);

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/publish-assets/cdk-publish-assets-then-deploy.integtest.ts

@@ -0,0 +1,22 @@
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'publish-assets then deploy detects already uploaded assets',
+  withDefaultFixture(async (fixture) => {
+    const stackName = 'lambda';
+    const fullStackName = fixture.fullStackName(stackName);
+
+    // First, publish assets
+    const publishOutput = await fixture.cdk(['publish-assets', fullStackName, '--unstable=publish-assets']);
+    expect(publishOutput).toMatch('Assets published successfully');
+
+    // Then deploy the same stack; it should detect the already published assets and skip re-publishing
+    const deployOutput = await fixture.cdkDeploy(stackName, { options: ['-v'], captureStderr: true });
+    expect(deployOutput).toMatch(/0 still need to be published/);
+
+    // Clean up
+    await fixture.cdkDestroy(stackName);
+  }),
+);

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/publish-assets/cdk-publish-assets-without-deploying.integtest.ts

@@ -0,0 +1,19 @@
+import { DescribeStacksCommand } from '@aws-sdk/client-cloudformation';
+import { integTest, withDefaultFixture } from '../../../lib';
+
+jest.setTimeout(2 * 60 * 60_000); // Includes the time to acquire locks, worst-case single-threaded runtime
+
+integTest(
+  'publish-assets without deploying',
+  withDefaultFixture(async (fixture) => {
+    const stackName = 'lambda';
+    const fullStackName = fixture.fullStackName(stackName);
+
+    const output = await fixture.cdk(['publish-assets', fullStackName, '--unstable=publish-assets']);
+    expect(output).toMatch('Assets published successfully');
+
+    // assert the stack was not deployed
+    await expect(fixture.aws.cloudFormation.send(new DescribeStacksCommand({ StackName: fullStackName })))
+      .rejects.toThrow(/does not exist/);
+  }),
+);

packages/@aws-cdk/toolkit-lib/docs/message-registry.md

@@ -139,6 +139,9 @@ Please let us know by [opening an issue](https://github.com/aws/aws-cdk-cli/issu
 | `CDK_TOOLKIT_I9900` | Bootstrap results on success | `result` | [cxapi.Environment](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_cx-api.Environment.html) |
 | `CDK_TOOLKIT_E9900` | Bootstrap failed | `error` | {@link ErrorPayload} |
 | `CDK_TOOLKIT_I9300` | Confirm the feature flag configuration changes | `info` | {@link FeatureFlagChangeRequest} |
+| `CDK_TOOLKIT_I9400` | All assets are already published | `info` | n/a |
+| `CDK_TOOLKIT_I9401` | Publishing assets | `info` | {@link AssetsPayload} |
+| `CDK_TOOLKIT_I9402` | Publish assets results on success | `result` | {@link AssetsPayload} |
 | `CDK_TOOLKIT_I0100` | Notices decoration (the header or footer of a list of notices) | `info` | n/a |
 | `CDK_TOOLKIT_W0101` | A notice that is marked as a warning | `warn` | n/a |
 | `CDK_TOOLKIT_E0101` | A notice that is marked as an error | `error` | n/a |

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

@@ -4,6 +4,7 @@ export * from './destroy';
 export * from './diff';
 export * from './drift';
 export * from './list';
+export * from './publish-assets';
 export * from './refactor';
 export * from './rollback';
 export * from './synth';

packages/@aws-cdk/toolkit-lib/lib/actions/publish-assets/index.ts

@@ -0,0 +1,32 @@
+import type { IManifestEntry } from '@aws-cdk/cdk-assets-lib';
+import type { StackSelector } from '../../api/cloud-assembly';
+
+export interface PublishAssetsOptions {
+  /**
+   * Select stacks to publish assets for
+   *
+   * @default - All stacks
+   */
+  readonly stacks?: StackSelector;
+
+  /**
+   * Always publish assets, even if they are already published
+   *
+   * @default false
+   */
+  readonly force?: boolean;
+
+  /**
+   * Maximum number of simultaneous asset operations (building and publishing)
+   *
+   * @default 4
+   */
+  readonly concurrency?: number;
+}
+
+export interface PublishAssetsResult {
+  /**
+   * List of assets that were published
+   */
+  readonly publishedAssets: IManifestEntry[];
+}

packages/@aws-cdk/toolkit-lib/lib/api/io/private/messages.ts

@@ -13,6 +13,7 @@ import type { HotswapDeploymentDetails, HotswapDeploymentAttempt, HotswappableCh
 import type { ResourceIdentificationRequest, ResourceImportRequest } from '../../../payloads/import';
 import type { StackDetailsPayload } from '../../../payloads/list';
 import type { CloudWatchLogEvent, CloudWatchLogMonitorControlEvent } from '../../../payloads/logs-monitor';
+import type { AssetsPayload } from '../../../payloads/publish-assets';
 import type { RefactorResult } from '../../../payloads/refactor';
 import type { StackRollbackProgress } from '../../../payloads/rollback';
 import type { MfaTokenRequest, SdkTrace } from '../../../payloads/sdk';
@@ -423,7 +424,7 @@ export const IO = {
     description: 'Refactor execution not yet supported',
   }),
 
-  // 9: Bootstrap  & gc (9xxx)
+  // 9: Bootstrap, gc, flags & publish (9xxx)
   CDK_TOOLKIT_I9000: make.info<Duration>({
     code: 'CDK_TOOLKIT_I9000',
     description: 'Provides bootstrap times',
@@ -453,13 +454,29 @@ export const IO = {
     interface: 'ErrorPayload',
   }),
 
-  // flags (93xxx)
+  // flags (93xx)
   CDK_TOOLKIT_I9300: make.info<FeatureFlagChangeRequest>({
     code: 'CDK_TOOLKIT_I9300',
     description: 'Confirm the feature flag configuration changes',
     interface: 'FeatureFlagChangeRequest',
   }),
 
+  // publish (94xx)
+  CDK_TOOLKIT_I9400: make.info({
+    code: 'CDK_TOOLKIT_I9400',
+    description: 'All assets are already published',
+  }),
+  CDK_TOOLKIT_I9401: make.info<AssetsPayload>({
+    code: 'CDK_TOOLKIT_I9401',
+    description: 'Publishing assets',
+    interface: 'AssetsPayload',
+  }),
+  CDK_TOOLKIT_I9402: make.result<AssetsPayload>({
+    code: 'CDK_TOOLKIT_I9402',
+    description: 'Publish assets results on success',
+    interface: 'AssetsPayload',
+  }),
+
   // Notices
   CDK_TOOLKIT_I0100: make.info({
     code: 'CDK_TOOLKIT_I0100',

packages/@aws-cdk/toolkit-lib/lib/api/io/toolkit-action.ts

@@ -10,6 +10,7 @@ export type ToolkitAction =
 | 'deploy'
 | 'drift'
 | 'rollback'
+| 'publish-assets'
 | 'watch'
 | 'destroy'
 | 'doctor'

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

@@ -10,6 +10,7 @@ export * from './stack-activity';
 export * from './synth';
 export * from './types';
 export * from './progress';
+export * from './publish-assets';
 export * from './refactor';
 export * from './watch';
 export * from './stack-details';

packages/@aws-cdk/toolkit-lib/lib/payloads/publish-assets.ts

@@ -0,0 +1,8 @@
+import type { IManifestEntry } from '@aws-cdk/cdk-assets-lib';
+
+export interface AssetsPayload {
+  /**
+   * List of assets
+   */
+  readonly assets: IManifestEntry[];
+}

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

@@ -46,6 +46,7 @@ import type { DiffOptions } from '../actions/diff';
 import { appendObject, prepareDiff } from '../actions/diff/private';
 import type { DriftOptions, DriftResult } from '../actions/drift';
 import { type ListOptions } from '../actions/list';
+import type { PublishAssetsOptions, PublishAssetsResult } from '../actions/publish-assets';
 import type { RefactorOptions } from '../actions/refactor';
 import { type RollbackOptions } from '../actions/rollback';
 import { type SynthOptions } from '../actions/synth';
@@ -164,7 +165,7 @@ export interface ToolkitOptions {
  * Names of toolkit features that are still under development, and may change in
  * the future.
  */
-export type UnstableFeature = 'refactor' | 'flags';
+export type UnstableFeature = 'refactor' | 'flags' | 'publish-assets';
 
 /**
  * The AWS CDK Programmatic Toolkit
@@ -492,6 +493,80 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     return allDriftResults;
   }
 
+  /**
+   * Publish Assets Action
+   *
+   * Publishes assets for the selected stacks without deploying
+   */
+  public async publishAssets(cx: ICloudAssemblySource, options: PublishAssetsOptions = {}): Promise<PublishAssetsResult> {
+    this.requireUnstableFeature('publish-assets');
+
+    const ioHelper = asIoHelper(this.ioHost, 'publish-assets');
+    const selectStacks = stacksOpt(options);
+    await using assembly = await synthAndMeasure(ioHelper, cx, selectStacks);
+
+    const stackCollection = await assembly.selectStacksV2(selectStacks);
+    await this.validateStacksMetadata(stackCollection, ioHelper);
+
+    if (stackCollection.stackCount === 0) {
+      await ioHelper.notify(IO.CDK_TOOLKIT_E5001.msg('No stacks selected'));
+      return {
+        publishedAssets: [],
+      };
+    }
+
+    const deployments = await this.deploymentsForAction('publish-assets');
+
+    const stacks = stackCollection.stackArtifacts;
+    const stacksAndTheirAssetManifests = stacks.flatMap((stack) => [
+      stack,
+      ...stack.dependencies.filter(x => cxapi.AssetManifestArtifact.isAssetManifestArtifact(x)),
+    ]);
+
+    const workGraph = new WorkGraphBuilder(
+      ioHelper,
+      true, // prebuild all assets
+    ).build(stacksAndTheirAssetManifests);
+
+    if (!options.force) {
+      await removePublishedAssetsFromWorkGraph(workGraph, deployments, options);
+    }
+
+    const assetNodes = Object.values(workGraph.nodes)
+      .filter((n): n is AssetPublishNode => n.type === 'asset-publish');
+
+    if (assetNodes.length === 0) {
+      await ioHelper.notify(IO.CDK_TOOLKIT_I9400.msg(chalk.green('\n✨  All assets are already published\n')));
+      return {
+        publishedAssets: [],
+      };
+    }
+
+    const assets = assetNodes.map(n => n.asset);
+    await ioHelper.notify(IO.CDK_TOOLKIT_I9401.msg('Publishing assets', { assets }));
+
+    const concurrency = options.concurrency ?? 4;
+    const graphConcurrency: Concurrency = {
+      'stack': 1,
+      'asset-build': concurrency,
+      'asset-publish': concurrency,
+    };
+
+    await workGraph.doParallel(graphConcurrency, {
+      deployStack: async () => {
+        // No-op: we're only publishing assets, not deploying
+      },
+      buildAsset: this.createBuildAssetFunction(ioHelper, deployments, undefined),
+      publishAsset: this.createPublishAssetFunction(ioHelper, deployments, undefined, options.force),
+    });
+
+    await ioHelper.notify(IO.CDK_TOOLKIT_I9402.msg(chalk.green('\n✨  Assets published successfully\n'), { assets }));
+
+    return {
+      publishedAssets: assets,
+    };
+  }
+
   /**
    * List Action
    *
@@ -558,36 +633,6 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     const stackOutputs: { [key: string]: any } = {};
     const outputsFile = options.outputsFile;
 
-    const buildAsset = async (assetNode: AssetBuildNode) => {
-      const buildAssetSpan = await ioHelper.span(SPAN.BUILD_ASSET).begin({
-        asset: assetNode.asset,
-      });
-      await deployments.buildSingleAsset(
-        assetNode.assetManifestArtifact,
-        assetNode.assetManifest,
-        assetNode.asset,
-        {
-          stack: assetNode.parentStack,
-          roleArn: options.roleArn,
-          stackName: assetNode.parentStack.stackName,
-        },
-      );
-      await buildAssetSpan.end();
-    };
-
-    const publishAsset = async (assetNode: AssetPublishNode) => {
-      const publishAssetSpan = await ioHelper.span(SPAN.PUBLISH_ASSET).begin({
-        asset: assetNode.asset,
-      });
-      await deployments.publishSingleAsset(assetNode.assetManifest, assetNode.asset, {
-        stack: assetNode.parentStack,
-        roleArn: options.roleArn,
-        stackName: assetNode.parentStack.stackName,
-        forcePublish: options.forceAssetPublishing,
-      });
-      await publishAssetSpan.end();
-    };
-
     const deployStack = async (stackNode: StackNode) => {
       const stack = stackNode.stack;
       if (stackCollection.stackCount !== 1) {
@@ -850,8 +895,8 @@ export class Toolkit extends CloudAssemblySourceBuilder {
 
     await workGraph.doParallel(graphConcurrency, {
       deployStack,
-      buildAsset,
-      publishAsset,
+      buildAsset: this.createBuildAssetFunction(ioHelper, deployments, options.roleArn),
+      publishAsset: this.createPublishAssetFunction(ioHelper, deployments, options.roleArn, options.forceAssetPublishing),
     });
 
     return ret;
@@ -1427,6 +1472,55 @@ export class Toolkit extends CloudAssemblySourceBuilder {
       throw new ToolkitError('UnstableFeatureNotEnabled', `Unstable feature '${requestedFeature}' is not enabled. Please enable it under 'unstableFeatures'`);
     }
   }
+
+  /**
+   * Create a buildAsset function for use in WorkGraph
+   */
+  private createBuildAssetFunction(
+    ioHelper: IoHelper,
+    deployments: Deployments,
+    roleArn: string | undefined,
+  ) {
+    return async (assetNode: AssetBuildNode) => {
+      const buildAssetSpan = await ioHelper.span(SPAN.BUILD_ASSET).begin({
+        asset: assetNode.asset,
+      });
+      await deployments.buildSingleAsset(
+        assetNode.assetManifestArtifact,
+        assetNode.assetManifest,
+        assetNode.asset,
+        {
+          stack: assetNode.parentStack,
+          roleArn,
+          stackName: assetNode.parentStack.stackName,
+        },
+      );
+      await buildAssetSpan.end();
+    };
+  }
+
+  /**
+   * Create a publishAsset function for use in WorkGraph
+   */
+  private createPublishAssetFunction(
+    ioHelper: IoHelper,
+    deployments: Deployments,
+    roleArn: string | undefined,
+    forcePublish?: boolean,
+  ) {
+    return async (assetNode: AssetPublishNode) => {
+      const publishAssetSpan = await ioHelper.span(SPAN.PUBLISH_ASSET).begin({
+        asset: assetNode.asset,
+      });
+      await deployments.publishSingleAsset(assetNode.assetManifest, assetNode.asset, {
+        stack: assetNode.parentStack,
+        roleArn,
+        stackName: assetNode.parentStack.stackName,
+        forcePublish,
+      });
+      await publishAssetSpan.end();
+    };
+  }
 }
 
 /**