feat(cli): add publish command for asset publishing

packages/@aws-cdk-testing/cli-integ/tests/cli-integ-tests/publish/cdk-publish-requires-unstable-flag.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 command',
+  withDefaultFixture(async (fixture) => {
+    const stackName = 'lambda';
+    const fullStackName = fixture.fullStackName(stackName);
+
+    const output = await fixture.cdk(['publish', fullStackName, '--unstable=publish']);
+    expect(output).toMatch('Assets published successfully');
+
+    // assert the stack wan not deployed
+    await expect(fixture.aws.cloudFormation.send(new DescribeStacksCommand({ StackName: fullStackName })))
+      .rejects.toThrow(/does not exist/);
+  }),
+);

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';
 export * from './refactor';
 export * from './rollback';
 export * from './synth';

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

@@ -0,0 +1,39 @@
+import type { IManifestEntry } from '@aws-cdk/cdk-assets-lib';
+import type { StackSelector } from '../../api/cloud-assembly';
+
+export interface PublishOptions {
+  /**
+   * 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 publishing operations
+   *
+   * @default 1
+   */
+  readonly concurrency?: number;
+
+  /**
+   * Role to pass to CloudFormation for asset operations
+   *
+   * @default - Current role
+   */
+  readonly roleArn?: string;
+}
+
+export interface PublishResult {
+  /**
+   * List of assets that were published
+   */
+  readonly publishedAssets: IManifestEntry[];
+}

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

@@ -10,6 +10,7 @@ export type ToolkitAction =
 | 'deploy'
 | 'drift'
 | 'rollback'
+| 'publish'
 | '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';
 export * from './refactor';
 export * from './watch';
 export * from './stack-details';

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

@@ -0,0 +1,8 @@
+import type { PublishResult } from '../actions';
+
+export interface PublishResultPayload {
+  /**
+   * The publish result
+   */
+  readonly result: PublishResult;
+}

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 { PublishOptions, PublishResult } from '../actions/publish';
 import type { RefactorOptions } from '../actions/refactor';
 import { type RollbackOptions } from '../actions/rollback';
 import { type SynthOptions } from '../actions/synth';
@@ -488,6 +489,75 @@ export class Toolkit extends CloudAssemblySourceBuilder {
     return allDriftResults;
   }
 
+  /**
+   * Publish Action
+   *
+   * Publishes assets for the selected stacks without deploying
+   */
+  public async publish(cx: ICloudAssemblySource, options: PublishOptions = {}): Promise<PublishResult> {
+    const ioHelper = asIoHelper(this.ioHost, 'publish');
+    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');
+
+    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.defaults.info(chalk.green('\n✨  All assets are already published\n'));
+      return {
+        publishedAssets: [],
+      };
+    }
+
+    const graphConcurrency: Concurrency = {
+      'stack': 1,
+      'asset-build': 1,
+      'asset-publish': options.concurrency ?? 1,
+    };
+
+    await workGraph.doParallel(graphConcurrency, {
+      deployStack: async () => {
+        // No-op: we're only publishing assets, not deploying
+      },
+      buildAsset: this.createBuildAssetFunction(ioHelper, deployments, options.roleArn),
+      publishAsset: this.createPublishAssetFunction(ioHelper, deployments, options.roleArn, options.force),
+    });
+
+    await ioHelper.defaults.info(chalk.green('\n✨  Assets published successfully\n'));
+    const publishedAssets = assetNodes.map(n => n.asset);
+
+    return {
+      publishedAssets,
+    };
+  }
+
   /**
    * List Action
    *
@@ -554,36 +624,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) {
@@ -837,8 +877,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;
@@ -1407,6 +1447,55 @@ export class Toolkit extends CloudAssemblySourceBuilder {
       throw new ToolkitError(`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();
+    };
+  }
 }
 
 /**

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

@@ -0,0 +1,100 @@
+import { StackSelectionStrategy } from '../../lib/api/cloud-assembly';
+import * as deployments from '../../lib/api/deployments';
+import { Toolkit } from '../../lib/toolkit';
+import { builderFixture, TestIoHost } from '../_helpers';
+
+let ioHost: TestIoHost;
+let toolkit: Toolkit;
+
+beforeEach(() => {
+  jest.restoreAllMocks();
+  ioHost = new TestIoHost('info', true);
+  toolkit = new Toolkit({ ioHost });
+
+  // Mock deployments methods for asset operations
+  jest.spyOn(deployments.Deployments.prototype, 'resolveEnvironment').mockResolvedValue({
+    account: '11111111',
+    region: 'us-east-1',
+    name: 'aws://11111111/us-east-1',
+  });
+  jest.spyOn(deployments.Deployments.prototype, 'isSingleAssetPublished').mockResolvedValue(false);
+  jest.spyOn(deployments.Deployments.prototype, 'buildSingleAsset').mockImplementation();
+  jest.spyOn(deployments.Deployments.prototype, 'publishSingleAsset').mockImplementation();
+});
+
+describe('publish', () => {
+  test('publishes assets for a single stack', async () => {
+    // WHEN
+    const cx = await builderFixture(toolkit, 'stack-with-asset');
+    const result = await toolkit.publish(cx, {
+      stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
+    });
+
+    // THEN
+    expect(result.publishedAssets.length).toBeGreaterThan(0);
+    ioHost.expectMessage({ containing: 'Assets published successfully', level: 'info' });
+  });
+
+  test('publishes assets for multiple stacks', async () => {
+    // WHEN
+    const cx = await builderFixture(toolkit, 'two-different-stacks');
+    const result = await toolkit.publish(cx, {
+      stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
+    });
+
+    // THEN
+    expect(result.publishedAssets.length).toBeGreaterThan(0);
+    ioHost.expectMessage({ containing: 'Assets published successfully', level: 'info' });
+  });
+
+  test('returns result when no stacks are selected', async () => {
+    // WHEN
+    const cx = await builderFixture(toolkit, 'stack-with-asset');
+    const result = await toolkit.publish(cx, {
+      stacks: { patterns: ['NonExistentStack'], strategy: StackSelectionStrategy.PATTERN_MATCH },
+    });
+
+    // THEN
+    expect(result.publishedAssets.length).toBe(0);
+    ioHost.expectMessage({ containing: 'No stacks selected', level: 'error' });
+  });
+
+  test('can invoke publish action without options', async () => {
+    // WHEN
+    const cx = await builderFixture(toolkit, 'stack-with-asset');
+    const result = await toolkit.publish(cx);
+
+    // THEN
+    expect(result.publishedAssets.length).toBeGreaterThan(0);
+    ioHost.expectMessage({ containing: 'Assets published successfully', level: 'info' });
+  });
+
+  test('respects force option', async () => {
+    // WHEN - publish with force
+    const cx = await builderFixture(toolkit, 'stack-with-asset');
+    const result = await toolkit.publish(cx, {
+      stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
+      force: true,
+    });
+
+    // THEN
+    expect(result.publishedAssets.length).toBeGreaterThan(0);
+    ioHost.expectMessage({ containing: 'Assets published successfully', level: 'info' });
+  });
+
+  test('skips already published assets when force is false', async () => {
+    // Mock that asset is already published
+    jest.spyOn(deployments.Deployments.prototype, 'isSingleAssetPublished').mockResolvedValue(true);
+
+    // WHEN - publish without force
+    const cx = await builderFixture(toolkit, 'stack-with-asset');
+    const result = await toolkit.publish(cx, {
+      stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
+      force: false,
+    });
+
+    // THEN
+    expect(result.publishedAssets.length).toBe(0);
+    ioHost.expectMessage({ containing: 'All assets are already published', level: 'info' });
+  });
+});