Merge branch 'main' into conroy/deploy-tests

packages/@aws-cdk/toolkit/.npmignore

@@ -9,22 +9,26 @@ dist
 coverage
 .nyc_output
 *.tgz
+docs
 
 # Ignore config files
 .eslintrc.js
 tsconfig.json
 *.tsbuildinfo
 junit.xml
 jest.config.js
-bundle.mjs
+build-tools
+
+# Ignore tests
+test
 
 # Explicitly allow all required files
 !build-info.json
 !db.json.gz
 # !lib/api/bootstrap/bootstrap-template.yaml
 !*.d.ts
 !*.d.ts.map
-!*.js
+!lib/*.js
 !LICENSE
 !NOTICE
 !THIRD_PARTY_LICENSES

packages/@aws-cdk/toolkit/build-tools/bundle.mjs

@@ -0,0 +1,33 @@
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import * as esbuild from 'esbuild';
+import * as fs from 'fs-extra';
+
+const require = createRequire(import.meta.url);
+
+const cliPackage = path.dirname(require.resolve('aws-cdk/package.json'));
+let copyFromCli = (from, to = undefined) => {
+  return fs.copy(path.join(cliPackage, ...from), path.join(process.cwd(), ...(to ?? from)));
+};
+
+// This is a build script, we are fine
+// eslint-disable-next-line @cdklabs/promiseall-no-unbounded-parallelism
+await Promise.all([
+  copyFromCli(['build-info.json']),
+  copyFromCli(['/db.json.gz']),
+  copyFromCli(['lib', 'index_bg.wasm']),
+]);
+
+// # Copy all resources that aws_cdk/generate.sh produced, and some othersCall the generator for the
+// cp -R $aws_cdk/lib/init-templates ./lib/
+// mkdir -p ./lib/api/bootstrap/ && cp $aws_cdk/lib/api/bootstrap/bootstrap-template.yaml ./lib/api/bootstrap/
+
+await esbuild.build({
+  entryPoints: ['lib/api/aws-cdk.ts'],
+  target: 'node18',
+  platform: 'node',
+  packages: 'external',
+  sourcemap: true,
+  bundle: true,
+  outfile: 'lib/api/aws-cdk.js',
+});

packages/@aws-cdk/toolkit/build-tools/package.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+version=${1:-latest}
+reset=0.0.0
+
+# Toolkit package root
+cd "$(dirname $(dirname "$0"))"
+
+npm pkg set dependencies.@aws-cdk/cx-api=$version
+npm pkg set dependencies.@aws-cdk/cloudformation-diff=$version
+npm pkg set dependencies.@aws-cdk/region-info=$version
+yarn package --private
+npm pkg set dependencies.@aws-cdk/cx-api=$reset
+npm pkg set dependencies.@aws-cdk/cloudformation-diff=$reset
+npm pkg set dependencies.@aws-cdk/region-info=$reset

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

@@ -34,7 +34,7 @@ export class DiffMethod {
    *
    * This will create, analyze, and subsequently delete a changeset against the CloudFormation stack.
    */
-  public static ChangeSet(options: ChangeSetDiffOptions = {}) {
+  public static ChangeSet(options: ChangeSetDiffOptions = {}): DiffMethod {
     return new class extends DiffMethod {
       public override readonly options: ChangeSetDiffOptions;
       public constructor(opts: ChangeSetDiffOptions) {
@@ -44,7 +44,7 @@ export class DiffMethod {
     }(options);
   }
 
-  public static TemplateOnly(options: CloudFormationDiffOptions = {}) {
+  public static TemplateOnly(options: CloudFormationDiffOptions = {}): DiffMethod {
     return new class extends DiffMethod {
       public override readonly options: CloudFormationDiffOptions;
       public constructor(opts: CloudFormationDiffOptions) {
@@ -54,7 +54,7 @@ export class DiffMethod {
     }(options);
   }
 
-  public static LocalFile(path: string) {
+  public static LocalFile(path: string): DiffMethod {
     return new class extends DiffMethod {
       public override readonly options: { path: string };
       public constructor(opts: { path: string }) {

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

@@ -1,27 +1,26 @@
-/* eslint-disable import/no-extraneous-dependencies */
-export { DEFAULT_TOOLKIT_STACK_NAME, SdkProvider } from 'aws-cdk/lib';
-export type { SuccessfulDeployStackResult } from 'aws-cdk/lib';
-export { formatSdkLoggerContent } from 'aws-cdk/lib/api/aws-auth/sdk-logger';
-export { CloudAssembly, sanitizePatterns, StackCollection, ExtendedStackSelection } from 'aws-cdk/lib/api/cxapp/cloud-assembly';
-export { prepareDefaultEnvironment, prepareContext, spaceAvailableForContext } from 'aws-cdk/lib/api/cxapp/exec';
-export { Deployments } from 'aws-cdk/lib/api/deployments';
-export { HotswapMode } from 'aws-cdk/lib/api/hotswap/common';
-export { StackActivityProgress } from 'aws-cdk/lib/api/util/cloudformation/stack-activity-monitor';
-export { RWLock } from 'aws-cdk/lib/api/util/rwlock';
-export type { ILock } from 'aws-cdk/lib/api/util/rwlock';
-export { formatTime } from 'aws-cdk/lib/api/util/string-manipulation';
-export * as contextproviders from 'aws-cdk/lib/context-providers';
-export { ResourceMigrator } from 'aws-cdk/lib/migrator';
-export { obscureTemplate, serializeStructure } from 'aws-cdk/lib/serialize';
-export { Context, Settings, PROJECT_CONTEXT } from 'aws-cdk/lib/settings';
-export { tagsForStack } from 'aws-cdk/lib/tags';
-export { CliIoHost } from 'aws-cdk/lib/toolkit/cli-io-host';
-export { loadTree, some } from 'aws-cdk/lib/tree';
-export { splitBySize } from 'aws-cdk/lib/util';
-export { validateSnsTopicArn } from 'aws-cdk/lib/util/validate-notification-arn';
-export { WorkGraph } from 'aws-cdk/lib/util/work-graph';
-export type { Concurrency } from 'aws-cdk/lib/util/work-graph';
-export { WorkGraphBuilder } from 'aws-cdk/lib/util/work-graph-builder';
-export type { AssetBuildNode, AssetPublishNode, StackNode } from 'aws-cdk/lib/util/work-graph-types';
-export { versionNumber } from 'aws-cdk/lib/version';
-export { guessExecutable } from 'aws-cdk/lib/api/cxapp/exec';
+export { DEFAULT_TOOLKIT_STACK_NAME, SdkProvider } from '../../../../aws-cdk/lib';
+export type { SuccessfulDeployStackResult } from '../../../../aws-cdk/lib';
+export { formatSdkLoggerContent } from '../../../../aws-cdk/lib/api/aws-auth/sdk-logger';
+export { CloudAssembly, sanitizePatterns, StackCollection, ExtendedStackSelection } from '../../../../aws-cdk/lib/api/cxapp/cloud-assembly';
+export { prepareDefaultEnvironment, prepareContext, spaceAvailableForContext } from '../../../../aws-cdk/lib/api/cxapp/exec';
+export { Deployments } from '../../../../aws-cdk/lib/api/deployments';
+export { HotswapMode } from '../../../../aws-cdk/lib/api/hotswap/common';
+export { StackActivityProgress } from '../../../../aws-cdk/lib/api/util/cloudformation/stack-activity-monitor';
+export { RWLock } from '../../../../aws-cdk/lib/api/util/rwlock';
+export type { ILock } from '../../../../aws-cdk/lib/api/util/rwlock';
+export { formatTime } from '../../../../aws-cdk/lib/api/util/string-manipulation';
+export * as contextproviders from '../../../../aws-cdk/lib/context-providers';
+export { ResourceMigrator } from '../../../../aws-cdk/lib/migrator';
+export { obscureTemplate, serializeStructure } from '../../../../aws-cdk/lib/serialize';
+export { Context, Settings, PROJECT_CONTEXT } from '../../../../aws-cdk/lib/settings';
+export { tagsForStack } from '../../../../aws-cdk/lib/tags';
+export { CliIoHost } from '../../../../aws-cdk/lib/toolkit/cli-io-host';
+export { loadTree, some } from '../../../../aws-cdk/lib/tree';
+export { splitBySize } from '../../../../aws-cdk/lib/util';
+export { validateSnsTopicArn } from '../../../../aws-cdk/lib/util/validate-notification-arn';
+export { WorkGraph } from '../../../../aws-cdk/lib/util/work-graph';
+export type { Concurrency } from '../../../../aws-cdk/lib/util/work-graph';
+export { WorkGraphBuilder } from '../../../../aws-cdk/lib/util/work-graph-builder';
+export type { AssetBuildNode, AssetPublishNode, StackNode } from '../../../../aws-cdk/lib/util/work-graph-types';
+export { versionNumber } from '../../../../aws-cdk/lib/version';
+export { guessExecutable } from '../../../../aws-cdk/lib/api/cxapp/exec';

packages/@aws-cdk/toolkit/lib/api/cloud-assembly/private/source-builder.ts

@@ -19,6 +19,9 @@ export abstract class CloudAssemblySourceBuilder {
 
   /**
    * Create a Cloud Assembly from a Cloud Assembly builder function.
+   * @param builder the builder function
+   * @param props additional configuration properties
+   * @returns the CloudAssembly source
    */
   public async fromAssemblyBuilder(
     builder: AssemblyBuilder,
@@ -52,9 +55,8 @@ export abstract class CloudAssemblySourceBuilder {
 
   /**
    * Creates a Cloud Assembly from an existing assembly directory.
-   * @param directory the directory of the AWS CDK app. Defaults to the current working directory.
-   * @param props additional configuration properties
-   * @returns an instance of `AwsCdkCli`
+   * @param directory the directory of a already produced Cloud Assembly.
+   * @returns the CloudAssembly source
    */
   public async fromAssemblyDirectory(directory: string): Promise<ICloudAssemblySource> {
     const services: ToolkitServices = await this.toolkitServices();
@@ -78,9 +80,8 @@ export abstract class CloudAssemblySourceBuilder {
   }
   /**
    * Use a directory containing an AWS CDK app as source.
-   * @param directory the directory of the AWS CDK app. Defaults to the current working directory.
    * @param props additional configuration properties
-   * @returns an instance of `AwsCdkCli`
+   * @returns the CloudAssembly source
    */
   public async fromCdkApp(app: string, props: CdkAppSourceProps = {}): Promise<ICloudAssemblySource> {
     const services: ToolkitServices = await this.toolkitServices();

packages/@aws-cdk/toolkit/lib/api/cloud-assembly/stack-assembly.ts

@@ -87,7 +87,6 @@ export class StackAssembly extends CloudAssembly implements ICloudAssemblySource
   /**
    * Select all stacks that have the validateOnSynth flag et.
    *
-   * @param assembly
    * @returns a `StackCollection` of all stacks that needs to be validated
    */
   public selectStacksForValidation() {

packages/@aws-cdk/toolkit/package.json

@@ -3,33 +3,36 @@
   "description": "AWS CDK Programmatic Toolkit Library",
   "private": true,
   "version": "0.0.0",
-  "main": "./lib/main.js",
+  "type": "commonjs",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "default": "./lib/main.js"
+      "default": "./lib/index.js"
     }
   },
-  "types": "./lib/index.d.ts",
-  "type": "commonjs",
   "scripts": {
     "awslint": "cdk-awslint",
     "build": "cdk-build",
     "build+test": "yarn build && yarn test",
     "build+test+package": "yarn build+test && yarn package",
     "build+extract": "yarn build",
     "build+test+extract": "yarn build+test",
-    "bundle": "node bundle.mjs",
+    "bundle": "node build-tools/bundle.mjs",
+    "docs": "typedoc lib/index.ts --excludeExternals --excludePrivate --excludeProtected --excludeInternal",
     "lint": "cdk-lint",
     "package": "cdk-package",
     "pkglint": "pkglint -f",
+    "publish-local": "./build-tools/package.sh",
     "test": "cdk-test",
     "watch": "cdk-watch"
   },
   "cdk-build": {
     "post": [
       "yarn bundle",
-      "node ./lib/main.js >/dev/null 2>/dev/null </dev/null"
+      "node ./lib/index.js >/dev/null 2>/dev/null </dev/null",
+      "node ./lib/api/aws-cdk.js >/dev/null 2>/dev/null </dev/null"
     ]
   },
   "author": {
@@ -50,6 +53,7 @@
     "aws-sdk-client-mock": "^4.0.1",
     "esbuild": "^0.24.0",
     "jest": "^29.7.0",
+    "typedoc": "^0.27.6",
     "typescript": "~5.6.3"
   },
   "dependencies": {

packages/@aws-cdk/toolkit/tsconfig.json

@@ -3,7 +3,7 @@
     "esModuleInterop": false,
     "skipLibCheck": true,
     "target": "es2022",
-    "allowJs": true,
+    "allowJs": false,
     "resolveJsonModule": true,
     "moduleDetection": "force",
     "isolatedModules": true,
@@ -20,7 +20,7 @@
     "composite": true,
     "tsBuildInfoFile": "tsconfig.tsbuildinfo"
   },
-  "include": ["**/*.ts"],
+  "include": ["**/*.ts", "build-tools/*.mjs"],
   "exclude": ["node_modules", "**/*.d.ts", "dist"],
   "references": [
     { "path": "../cx-api" },