@aws-cdk/toolkit-lib 0.1.8 → 0.3.0

package/lib/api/shared-public.d.ts

@@ -1,167 +1,7 @@
 import * as cxapi from '@aws-cdk/cx-api';
 import { CloudFormationStackArtifact } from '@aws-cdk/cx-api';
-import { DescribeChangeSetOutput as DescribeChangeSet, StackEvent } from '@aws-sdk/client-cloudformation';
+import { StackEvent } from '@aws-sdk/client-cloudformation';
 
-/**
- * Which stacks should be selected from a cloud assembly
- */
-export declare enum StackSelectionStrategy {
-	/**
-	 * Returns all stacks in the app regardless of patterns,
-	 * including stacks inside nested assemblies.
-	 */
-	ALL_STACKS = "all-stacks",
-	/**
-	 * Returns all stacks in the main (top level) assembly only.
-	 */
-	MAIN_ASSEMBLY = "main-assembly",
-	/**
-	 * If the assembly includes a single stack, returns it.
-	 * Otherwise throws an exception.
-	 */
-	ONLY_SINGLE = "only-single",
-	/**
-	 * Return stacks matched by patterns.
-	 * If no stacks are found, execution is halted successfully.
-	 * Most likely you don't want to use this but `StackSelectionStrategy.MUST_MATCH_PATTERN`
-	 */
-	PATTERN_MATCH = "pattern-match",
-	/**
-	 * Return stacks matched by patterns.
-	 * Throws an exception if the patterns don't match at least one stack in the assembly.
-	 */
-	PATTERN_MUST_MATCH = "pattern-must-match",
-	/**
-	 * Returns if exactly one stack is matched by the pattern(s).
-	 * Throws an exception if no stack, or more than exactly one stack are matched.
-	 */
-	PATTERN_MUST_MATCH_SINGLE = "pattern-must-match-single"
-}
-/**
- * When selecting stacks, what other stacks to include because of dependencies
- */
-export declare enum ExpandStackSelection {
-	/**
-	 * Don't select any extra stacks
-	 */
-	NONE = "none",
-	/**
-	 * Include stacks that this stack depends on
-	 */
-	UPSTREAM = "upstream",
-	/**
-	 * Include stacks that depend on this stack
-	 */
-	DOWNSTREAM = "downstream"
-}
-/**
- * A specification of which stacks should be selected
- */
-export interface StackSelector {
-	/**
-	 * The behavior if if no selectors are provided.
-	 */
-	strategy: StackSelectionStrategy;
-	/**
-	 * A list of patterns to match the stack hierarchical ids
-	 * Only used with `PATTERN_*` selection strategies.
-	 */
-	patterns?: string[];
-	/**
-	 * Expand the selection to upstream/downstream stacks.
-	 * @default ExpandStackSelection.None only select the specified/matched stacks
-	 */
-	expand?: ExpandStackSelection;
-	/**
-	 * By default, we throw an exception if the assembly contains no stacks.
-	 * Set to `false`, to halt execution for empty assemblies without error.
-	 *
-	 * Note that actions can still throw if a stack selection result is empty,
-	 * but the assembly contains stacks in principle.
-	 *
-	 * @default true
-	 */
-	failOnEmpty?: boolean;
-}
-export interface Template {
-	Parameters?: Record<string, TemplateParameter>;
-	[section: string]: any;
-}
-export interface TemplateParameter {
-	Type: string;
-	Default?: any;
-	Description?: string;
-	[key: string]: any;
-}
-export interface NestedStackTemplates {
-	readonly physicalName: string | undefined;
-	readonly deployedTemplate: Template;
-	readonly generatedTemplate: Template;
-	readonly nestedStackTemplates: {
-		[nestedStackLogicalId: string]: NestedStackTemplates;
-	};
-}
-interface IDifference<ValueType> {
-	readonly oldValue: ValueType | undefined;
-	readonly newValue: ValueType | undefined;
-	readonly isDifferent: boolean;
-	readonly isAddition: boolean;
-	readonly isRemoval: boolean;
-	readonly isUpdate: boolean;
-}
-declare class Difference<ValueType> implements IDifference<ValueType> {
-	readonly oldValue: ValueType | undefined;
-	readonly newValue: ValueType | undefined;
-	/**
-	 * Whether this is an actual different or the values are actually the same
-	 *
-	 * isDifferent => (isUpdate | isRemoved | isUpdate)
-	 */
-	isDifferent: boolean;
-	/**
-	 * @param oldValue the old value, cannot be equal (to the sense of +deepEqual+) to +newValue+.
-	 * @param newValue the new value, cannot be equal (to the sense of +deepEqual+) to +oldValue+.
-	 */
-	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined);
-	/** @returns +true+ if the element is new to the template. */
-	get isAddition(): boolean;
-	/** @returns +true+ if the element was removed from the template. */
-	get isRemoval(): boolean;
-	/** @returns +true+ if the element was already in the template and is updated. */
-	get isUpdate(): boolean;
-}
-declare class PropertyDifference<ValueType> extends Difference<ValueType> {
-	changeImpact?: ResourceImpact;
-	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined, args: {
-		changeImpact?: ResourceImpact;
-	});
-}
-declare enum ResourceImpact {
-	/** The existing physical resource will be updated */
-	WILL_UPDATE = "WILL_UPDATE",
-	/** A new physical resource will be created */
-	WILL_CREATE = "WILL_CREATE",
-	/** The existing physical resource will be replaced */
-	WILL_REPLACE = "WILL_REPLACE",
-	/** The existing physical resource may be replaced */
-	MAY_REPLACE = "MAY_REPLACE",
-	/** The existing physical resource will be destroyed */
-	WILL_DESTROY = "WILL_DESTROY",
-	/** The existing physical resource will be removed from CloudFormation supervision */
-	WILL_ORPHAN = "WILL_ORPHAN",
-	/** The existing physical resource will be added to CloudFormation supervision */
-	WILL_IMPORT = "WILL_IMPORT",
-	/** There is no change in this resource */
-	NO_CHANGE = "NO_CHANGE"
-}
-interface Resource {
-	Type: string;
-	Properties?: {
-		[name: string]: any;
-	};
-	[key: string]: any;
-}
-type DescribeChangeSetOutput = DescribeChangeSet;
 interface BootstrapRole {
 	/**
 	 * The ARN of the IAM role created as part of bootrapping
@@ -544,32 +384,6 @@ type LogicalIdMetadataEntry = string;
 type StackTagsMetadataEntry = Tag[];
 type PrimitiveType = boolean | number | string;
 type MetadataEntryData = AssetMetadataEntry | LogMessageMetadataEntry | LogicalIdMetadataEntry | StackTagsMetadataEntry | PrimitiveType;
-declare enum ArtifactMetadataEntryType {
-	/**
-	 * Asset in metadata.
-	 */
-	ASSET = "aws:cdk:asset",
-	/**
-	 * Metadata key used to print INFO-level messages by the toolkit when an app is syntheized.
-	 */
-	INFO = "aws:cdk:info",
-	/**
-	 * Metadata key used to print WARNING-level messages by the toolkit when an app is syntheized.
-	 */
-	WARN = "aws:cdk:warning",
-	/**
-	 * Metadata key used to print ERROR-level messages by the toolkit when an app is syntheized.
-	 */
-	ERROR = "aws:cdk:error",
-	/**
-	 * Represents the CloudFormation logical ID of a resource at a certain path.
-	 */
-	LOGICAL_ID = "aws:cdk:logicalId",
-	/**
-	 * Represents tags of a stack.
-	 */
-	STACK_TAGS = "aws:cdk:stack-tags"
-}
 interface MetadataEntry {
 	/**
 	 * The type of the metadata entry.
@@ -1044,7 +858,12 @@ 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
 	 */
@@ -1097,875 +916,203 @@ interface ICloudAssembly {
 	 */
 	readonly directory: string;
 }
-interface AwsDestination {
+interface LoadManifestOptions {
 	/**
-	 * The region where this asset will need to be published
+	 * Skip the version check
 	 *
-	 * @default - Current region
-	 */
-	readonly region?: string;
-	/**
-	 * The role that needs to be assumed while publishing this asset
+	 * This means you may read a newer cloud assembly than the CX API is designed
+	 * to support, and your application may not be aware of all features that in use
+	 * in the Cloud Assembly.
 	 *
-	 * @default - No role will be assumed
+	 * @default false
 	 */
-	readonly assumeRoleArn?: string;
+	readonly skipVersionCheck?: boolean;
 	/**
-	 * The ExternalId that needs to be supplied while assuming this role
+	 * Skip enum checks
 	 *
-	 * @default - No ExternalId will be supplied
+	 * This means you may read enum values you don't know about yet. Make sure to always
+	 * check the values of enums you encounter in the manifest.
+	 *
+	 * @default false
 	 */
-	readonly assumeRoleExternalId?: string;
+	readonly skipEnumCheck?: boolean;
 	/**
-	 * Additional options to pass to STS when assuming the role.
+	 * Topologically sort all artifacts
 	 *
-	 * - `RoleArn` should not be used. Use the dedicated `assumeRoleArn` property instead.
-	 * - `ExternalId` should not be used. Use the dedicated `assumeRoleExternalId` instead.
+	 * This parameter is only respected by the constructor of `CloudAssembly`. The
+	 * property lives here for backwards compatibility reasons.
 	 *
-	 * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/STS.html#assumeRole-property
-	 * @default - No additional options.
+	 * @default true
 	 */
-	readonly assumeRoleAdditionalOptions?: {
-		[key: string]: any;
-	};
+	readonly topoSort?: boolean;
 }
-interface DockerImageAsset {
+/**
+ * Represents a general toolkit error in the AWS CDK Toolkit.
+ */
+export declare class ToolkitError extends Error {
 	/**
-	 * A display name for this asset
-	 *
-	 * @default - The identifier will be used as the display name
+	 * Determines if a given error is an instance of ToolkitError.
 	 */
-	readonly displayName?: string;
+	static isToolkitError(x: any): x is ToolkitError;
 	/**
-	 * Source description for container assets
+	 * Determines if a given error is an instance of AuthenticationError.
 	 */
-	readonly source: DockerImageSource;
+	static isAuthenticationError(x: any): x is AuthenticationError;
 	/**
-	 * Destinations for this container asset
+	 * Determines if a given error is an instance of AssemblyError.
 	 */
-	readonly destinations: {
-		[id: string]: DockerImageDestination;
-	};
-}
-interface DockerImageSource {
+	static isAssemblyError(x: any): x is AssemblyError;
 	/**
-	 * The directory containing the Docker image build instructions.
-	 *
-	 * This path is relative to the asset manifest location.
-	 *
-	 * @default - Exactly one of `directory` and `executable` is required
+	 * Determines if a given error is an instance of AssemblyError.
 	 */
-	readonly directory?: string;
+	static isContextProviderError(x: any): x is ContextProviderError;
 	/**
-	 * A command-line executable that returns the name of a local
-	 * Docker image on stdout after being run.
-	 *
-	 * @default - Exactly one of `directory` and `executable` is required
+	 * An AssemblyError with an original error as cause
 	 */
-	readonly executable?: string[];
+	static withCause(message: string, error: unknown): ToolkitError;
 	/**
-	 * The name of the file with build instructions
-	 *
-	 * Only allowed when `directory` is set.
-	 *
-	 * @default "Dockerfile"
+	 * The type of the error, defaults to "toolkit".
 	 */
-	readonly dockerFile?: string;
+	readonly type: string;
 	/**
-	 * Target build stage in a Dockerfile with multiple build stages
-	 *
-	 * Only allowed when `directory` is set.
-	 *
-	 * @default - The last stage in the Dockerfile
+	 * Denotes the source of the error as the toolkit.
 	 */
-	readonly dockerBuildTarget?: string;
+	readonly source: "toolkit" | "user";
 	/**
-	 * Additional build arguments
-	 *
-	 * Only allowed when `directory` is set.
-	 *
-	 * @default - No additional build arguments
+	 * The specific original cause of the error, if available
 	 */
-	readonly dockerBuildArgs?: {
-		[name: string]: string;
-	};
+	readonly cause?: unknown;
+	constructor(message: string, type?: string, cause?: unknown);
+}
+/**
+ * Represents an authentication-specific error in the AWS CDK Toolkit.
+ */
+export declare class AuthenticationError extends ToolkitError {
 	/**
-	 * SSH agent socket or keys
-	 *
-	 * Requires building with docker buildkit.
-	 *
-	 * @default - No ssh flag is set
+	 * Denotes the source of the error as user.
 	 */
-	readonly dockerBuildSsh?: string;
+	readonly source = "user";
+	constructor(message: string);
+}
+/**
+ * Represents an error causes by cloud assembly synthesis
+ *
+ * This includes errors thrown during app execution, as well as failing annotations.
+ */
+export declare class AssemblyError extends ToolkitError {
 	/**
-	 * Additional build secrets
-	 *
-	 * Only allowed when `directory` is set.
-	 *
-	 * @default - No additional build secrets
+	 * An AssemblyError with an original error as cause
 	 */
-	readonly dockerBuildSecrets?: {
-		[name: string]: string;
-	};
+	static withCause(message: string, error: unknown): AssemblyError;
 	/**
-	 * Networking mode for the RUN commands during build. _Requires Docker Engine API v1.25+_.
-	 *
-	 * Specify this property to build images on a specific networking mode.
-	 *
-	 * @default - no networking mode specified
+	 * An AssemblyError with a list of stacks as cause
 	 */
-	readonly networkMode?: string;
-	/**
-	 * Platform to build for. _Requires Docker Buildx_.
-	 *
-	 * Specify this property to build images on a specific platform/architecture.
-	 *
-	 * @default - current machine platform
-	 */
-	readonly platform?: string;
-	/**
-	 * Outputs
-	 *
-	 * @default - no outputs are passed to the build command (default outputs are used)
-	 * @see https://docs.docker.com/engine/reference/commandline/build/#custom-build-outputs
-	 */
-	readonly dockerOutputs?: string[];
-	/**
-	 * Cache from options to pass to the `docker build` command.
-	 *
-	 * @default - no cache from options are passed to the build command
-	 * @see https://docs.docker.com/build/cache/backends/
-	 */
-	readonly cacheFrom?: DockerCacheOption[];
-	/**
-	 * Cache to options to pass to the `docker build` command.
-	 *
-	 * @default - no cache to options are passed to the build command
-	 * @see https://docs.docker.com/build/cache/backends/
-	 */
-	readonly cacheTo?: DockerCacheOption;
-	/**
-	 * Disable the cache and pass `--no-cache` to the `docker build` command.
-	 *
-	 * @default - cache is used
-	 */
-	readonly cacheDisabled?: boolean;
-}
-interface DockerImageDestination extends AwsDestination {
-	/**
-	 * Name of the ECR repository to publish to
-	 */
-	readonly repositoryName: string;
-	/**
-	 * Tag of the image to publish
-	 */
-	readonly imageTag: string;
-}
-interface DockerCacheOption {
-	/**
-	 * The type of cache to use.
-	 * Refer to https://docs.docker.com/build/cache/backends/ for full list of backends.
-	 * @default - unspecified
-	 *
-	 * @example 'registry'
-	 */
-	readonly type: string;
-	/**
-	 * Any parameters to pass into the docker cache backend configuration.
-	 * Refer to https://docs.docker.com/build/cache/backends/ for cache backend configuration.
-	 * @default {} No options provided
-	 *
-	 * @example
-	 * declare const branch: string;
-	 *
-	 * const params = {
-	 *   ref: `12345678.dkr.ecr.us-west-2.amazonaws.com/cache:${branch}`,
-	 *   mode: "max",
-	 * };
-	 */
-	readonly params?: {
-		[key: string]: string;
-	};
-}
-interface FileAsset {
-	/**
-	 * A display name for this asset
-	 *
-	 * @default - The identifier will be used as the display name
-	 */
-	readonly displayName?: string;
-	/**
-	 * Source description for file assets
-	 */
-	readonly source: FileSource;
-	/**
-	 * Destinations for this file asset
-	 */
-	readonly destinations: {
-		[id: string]: FileDestination;
-	};
-}
-declare enum FileAssetPackaging {
-	/**
-	 * Upload the given path as a file
-	 */
-	FILE = "file",
-	/**
-	 * The given path is a directory, zip it and upload
-	 */
-	ZIP_DIRECTORY = "zip"
-}
-interface FileSource {
-	/**
-	 * External command which will produce the file asset to upload.
-	 *
-	 * @default - Exactly one of `executable` and `path` is required.
-	 */
-	readonly executable?: string[];
-	/**
-	 * The filesystem object to upload
-	 *
-	 * This path is relative to the asset manifest location.
-	 *
-	 * @default - Exactly one of `executable` and `path` is required.
-	 */
-	readonly path?: string;
-	/**
-	 * Packaging method
-	 *
-	 * Only allowed when `path` is specified.
-	 *
-	 * @default FILE
-	 */
-	readonly packaging?: FileAssetPackaging;
-}
-interface FileDestination extends AwsDestination {
-	/**
-	 * The name of the bucket
-	 */
-	readonly bucketName: string;
-	/**
-	 * The destination object key
-	 */
-	readonly objectKey: string;
-}
-interface AssetManifest {
-	/**
-	 * Version of the manifest
-	 */
-	readonly version: string;
-	/**
-	 * The file assets in this manifest
-	 *
-	 * @default - No files
-	 */
-	readonly files?: {
-		[id: string]: FileAsset;
-	};
-	/**
-	 * The Docker image assets in this manifest
-	 *
-	 * @default - No Docker images
-	 */
-	readonly dockerImages?: {
-		[id: string]: DockerImageAsset;
-	};
-}
-declare enum RequireApproval {
-	/**
-	 * Never ask for approval
-	 */
-	NEVER = "never",
-	/**
-	 * Prompt for approval for any type of change to the stack
-	 */
-	ANYCHANGE = "any-change",
-	/**
-	 * Only prompt for approval if there are security related changes
-	 */
-	BROADENING = "broadening"
-}
-interface DefaultCdkOptions {
-	/**
-	 * List of stacks to deploy
-	 *
-	 * Requried if `all` is not set
-	 *
-	 * @default - []
-	 */
-	readonly stacks?: string[];
-	/**
-	 * Deploy all stacks
-	 *
-	 * Requried if `stacks` is not set
-	 *
-	 * @default - false
-	 */
-	readonly all?: boolean;
-	/**
-	 * command-line for executing your app or a cloud assembly directory
-	 * e.g. "node bin/my-app.js"
-	 * or
-	 * "cdk.out"
-	 *
-	 * @default - read from cdk.json
-	 */
-	readonly app?: string;
-	/**
-	 * Role to pass to CloudFormation for deployment
-	 *
-	 * @default - use the bootstrap cfn-exec role
-	 */
-	readonly roleArn?: string;
-	/**
-	 * Additional context
-	 *
-	 * @default - no additional context
-	 */
-	readonly context?: {
-		[name: string]: string;
-	};
-	/**
-	 * Print trace for stack warnings
-	 *
-	 * @default false
-	 */
-	readonly trace?: boolean;
-	/**
-	 * Do not construct stacks with warnings
-	 *
-	 * @default false
-	 */
-	readonly strict?: boolean;
-	/**
-	 * Perform context lookups.
-	 *
-	 * Synthesis fails if this is disabled and context lookups need
-	 * to be performed
-	 *
-	 * @default true
-	 */
-	readonly lookups?: boolean;
-	/**
-	 * Ignores synthesis errors, which will likely produce an invalid output
-	 *
-	 * @default false
-	 */
-	readonly ignoreErrors?: boolean;
-	/**
-	 * Use JSON output instead of YAML when templates are printed
-	 * to STDOUT
-	 *
-	 * @default false
-	 */
-	readonly json?: boolean;
-	/**
-	 * show debug logs
-	 *
-	 * @default false
-	 */
-	readonly verbose?: boolean;
-	/**
-	 * enable emission of additional debugging information, such as creation stack
-	 * traces of tokens
-	 *
-	 * @default false
-	 */
-	readonly debug?: boolean;
-	/**
-	 * Use the indicated AWS profile as the default environment
-	 *
-	 * @default - no profile is used
-	 */
-	readonly profile?: string;
-	/**
-	 * Use the indicated proxy. Will read from
-	 * HTTPS_PROXY environment if specified
-	 *
-	 * @default - no proxy
-	 */
-	readonly proxy?: string;
-	/**
-	 * Path to CA certificate to use when validating HTTPS
-	 * requests.
-	 *
-	 * @default - read from AWS_CA_BUNDLE environment variable
-	 */
-	readonly caBundlePath?: string;
-	/**
-	 * Force trying to fetch EC2 instance credentials
-	 *
-	 * @default - guess EC2 instance status
-	 */
-	readonly ec2Creds?: boolean;
-	/**
-	 * Include "AWS::CDK::Metadata" resource in synthesized templates
-	 *
-	 * @default true
-	 */
-	readonly versionReporting?: boolean;
-	/**
-	 * Include "aws:cdk:path" CloudFormation metadata for each resource
-	 *
-	 * @default true
-	 */
-	readonly pathMetadata?: boolean;
-	/**
-	 * Include "aws:asset:*" CloudFormation metadata for resources that use assets
-	 *
-	 * @default true
-	 */
-	readonly assetMetadata?: boolean;
-	/**
-	 * Copy assets to the output directory
-	 *
-	 * Needed for local debugging the source files with SAM CLI
-	 *
-	 * @default false
-	 */
-	readonly staging?: boolean;
-	/**
-	 * Emits the synthesized cloud assembly into a directory
-	 *
-	 * @default cdk.out
-	 */
-	readonly output?: string;
-	/**
-	 * Show relevant notices
-	 *
-	 * @default true
-	 */
-	readonly notices?: boolean;
-	/**
-	 * Show colors and other style from console output
-	 *
-	 * @default true
-	 */
-	readonly color?: boolean;
-}
-interface DeployOptions extends DefaultCdkOptions {
-	/**
-	 * Only perform action on the given stack
-	 *
-	 * @default false
-	 */
-	readonly exclusively?: boolean;
-	/**
-	 * Name of the toolkit stack to use/deploy
-	 *
-	 * @default CDKToolkit
-	 */
-	readonly toolkitStackName?: string;
-	/**
-	 * Reuse the assets with the given asset IDs
-	 *
-	 * @default - do not reuse assets
-	 */
-	readonly reuseAssets?: string[];
-	/**
-	 * Optional name to use for the CloudFormation change set.
-	 * If not provided, a name will be generated automatically.
-	 *
-	 * @default - auto generate a name
-	 */
-	readonly changeSetName?: string;
-	/**
-	 * Always deploy, even if templates are identical.
-	 * @default false
-	 */
-	readonly force?: boolean;
-	/**
-	 * Rollback failed deployments
-	 *
-	 * @default true
-	 */
-	readonly rollback?: boolean;
-	/**
-	 * ARNs of SNS topics that CloudFormation will notify with stack related events
-	 *
-	 * @default - no notifications
-	 */
-	readonly notificationArns?: string[];
-	/**
-	 * What kind of security changes require approval
-	 *
-	 * @default RequireApproval.NEVER
-	 */
-	readonly requireApproval?: RequireApproval;
-	/**
-	 * Whether to execute the ChangeSet
-	 * Not providing `execute` parameter will result in execution of ChangeSet
-	 * @default true
-	 */
-	readonly execute?: boolean;
-	/**
-	 * Additional parameters for CloudFormation at deploy time
-	 * @default {}
-	 */
-	readonly parameters?: {
-		[name: string]: string;
-	};
-	/**
-	 * Use previous values for unspecified parameters
-	 *
-	 * If not set, all parameters must be specified for every deployment.
-	 *
-	 * @default true
-	 */
-	readonly usePreviousParameters?: boolean;
-	/**
-	 * Path to file where stack outputs will be written after a successful deploy as JSON
-	 * @default - Outputs are not written to any file
-	 */
-	readonly outputsFile?: string;
-	/**
-	 * Whether we are on a CI system
-	 *
-	 * @default false
-	 */
-	readonly ci?: boolean;
-	/**
-	 * Deploy multiple stacks in parallel
-	 *
-	 * @default 1
-	 */
-	readonly concurrency?: number;
-}
-interface DestroyOptions extends DefaultCdkOptions {
-	/**
-	 * Do not ask for permission before destroying stacks
-	 *
-	 * @default false
-	 */
-	readonly force?: boolean;
-	/**
-	 * Only destroy the given stack
-	 *
-	 * @default false
-	 */
-	readonly exclusively?: boolean;
-}
-interface TestOptions {
-	/**
-	 * Run update workflow on this test case
-	 * This should only be set to false to test scenarios
-	 * that are not possible to test as part of the update workflow
-	 *
-	 * @default true
-	 */
-	readonly stackUpdateWorkflow?: boolean;
-	/**
-	 * Additional options to use for each CDK command
-	 *
-	 * @default - runner default options
-	 */
-	readonly cdkCommandOptions?: CdkCommands;
-	/**
-	 * Additional commands to run at predefined points in the test workflow
-	 *
-	 * e.g. { postDeploy: ['yarn', 'test'] }
-	 *
-	 * @default - no hooks
-	 */
-	readonly hooks?: Hooks;
-	/**
-	 * Whether or not to include asset hashes in the diff
-	 * Asset hashes can introduces a lot of unneccessary noise into tests,
-	 * but there are some cases where asset hashes _should_ be included. For example
-	 * any tests involving custom resources or bundling
-	 *
-	 * @default false
-	 */
-	readonly diffAssets?: boolean;
-	/**
-	 * List of CloudFormation resource types in this stack that can
-	 * be destroyed as part of an update without failing the test.
-	 *
-	 * This list should only include resources that for this specific
-	 * integration test we are sure will not cause errors or an outage if
-	 * destroyed. For example, maybe we know that a new resource will be created
-	 * first before the old resource is destroyed which prevents any outage.
-	 *
-	 * e.g. ['AWS::IAM::Role']
-	 *
-	 * @default - do not allow destruction of any resources on update
-	 */
-	readonly allowDestroy?: string[];
-	/**
-	 * Limit deployment to these regions
-	 *
-	 * @default - can run in any region
-	 */
-	readonly regions?: string[];
-}
-interface TestCase extends TestOptions {
-	/**
-	 * Stacks that should be tested as part of this test case
-	 * The stackNames will be passed as args to the cdk commands
-	 * so dependent stacks will be automatically deployed unless
-	 * `exclusively` is passed
-	 */
-	readonly stacks: string[];
-	/**
-	 * The node id of the stack that contains assertions.
-	 * This is the value that can be used to deploy the stack with the CDK CLI
-	 *
-	 * @default - no assertion stack
-	 */
-	readonly assertionStack?: string;
-	/**
-	 * The name of the stack that contains assertions
-	 *
-	 * @default - no assertion stack
-	 */
-	readonly assertionStackName?: string;
-}
-interface Hooks {
-	/**
-	 * Commands to run prior to deploying the cdk stacks
-	 * in the integration test
-	 *
-	 * @default - no commands
-	 */
-	readonly preDeploy?: string[];
-	/**
-	 * Commands to run prior after deploying the cdk stacks
-	 * in the integration test
-	 *
-	 * @default - no commands
-	 */
-	readonly postDeploy?: string[];
-	/**
-	 * Commands to run prior to destroying the cdk stacks
-	 * in the integration test
-	 *
-	 * @default - no commands
-	 */
-	readonly preDestroy?: string[];
-	/**
-	 * Commands to run after destroying the cdk stacks
-	 * in the integration test
-	 *
-	 * @default - no commands
-	 */
-	readonly postDestroy?: string[];
-}
-interface CdkCommand {
-	/**
-	 * Whether or not to run this command as part of the workflow
-	 * This can be used if you only want to test some of the workflow
-	 * for example enable `synth` and disable `deploy` & `destroy` in order
-	 * to limit the test to synthesis
-	 *
-	 * @default true
-	 */
-	readonly enabled?: boolean;
-	/**
-	 * If the runner should expect this command to fail
-	 *
-	 * @default false
-	 */
-	readonly expectError?: boolean;
-	/**
-	 * This can be used in combination with `expectedError`
-	 * to validate that a specific message is returned.
-	 *
-	 * @default - do not validate message
-	 */
-	readonly expectedMessage?: string;
-}
-interface DeployCommand extends CdkCommand {
-	/**
-	 * Additional arguments to pass to the command
-	 * This can be used to test specific CLI functionality
-	 *
-	 * @default - only default args are used
-	 */
-	readonly args?: DeployOptions;
-}
-interface DestroyCommand extends CdkCommand {
-	/**
-	 * Additional arguments to pass to the command
-	 * This can be used to test specific CLI functionality
-	 *
-	 * @default - only default args are used
-	 */
-	readonly args?: DestroyOptions;
-}
-interface CdkCommands {
-	/**
-	 * Options to for the cdk deploy command
-	 *
-	 * @default - default deploy options
-	 */
-	readonly deploy?: DeployCommand;
-	/**
-	 * Options to for the cdk destroy command
-	 *
-	 * @default - default destroy options
-	 */
-	readonly destroy?: DestroyCommand;
-}
-interface IntegManifest {
-	/**
-	 * Version of the manifest
-	 */
-	readonly version: string;
-	/**
-	 * Enable lookups for this test. If lookups are enabled
-	 * then `stackUpdateWorkflow` must be set to false.
-	 * Lookups should only be enabled when you are explicitely testing
-	 * lookups.
-	 *
-	 * @default false
-	 */
-	readonly enableLookups?: boolean;
-	/**
-	 * Additional context to use when performing
-	 * a synth. Any context provided here will override
-	 * any default context
-	 *
-	 * @default - no additional context
-	 */
-	readonly synthContext?: {
-		[name: string]: string;
-	};
-	/**
-	 * test cases
-	 */
-	readonly testCases: {
-		[testName: string]: TestCase;
-	};
-}
-declare const VERSION_MISMATCH: string;
-interface LoadManifestOptions {
-	/**
-	 * Skip the version check
-	 *
-	 * This means you may read a newer cloud assembly than the CX API is designed
-	 * to support, and your application may not be aware of all features that in use
-	 * in the Cloud Assembly.
-	 *
-	 * @default false
-	 */
-	readonly skipVersionCheck?: boolean;
+	static withStacks(message: string, stacks?: cxapi.CloudFormationStackArtifact[]): AssemblyError;
 	/**
-	 * Skip enum checks
-	 *
-	 * This means you may read enum values you don't know about yet. Make sure to always
-	 * check the values of enums you encounter in the manifest.
-	 *
-	 * @default false
+	 * Denotes the source of the error as user.
 	 */
-	readonly skipEnumCheck?: boolean;
+	readonly source = "user";
 	/**
-	 * Topologically sort all artifacts
-	 *
-	 * This parameter is only respected by the constructor of `CloudAssembly`. The
-	 * property lives here for backwards compatibility reasons.
+	 * The stacks that caused the error, if available
 	 *
-	 * @default true
+	 * The `messages` property of each `cxapi.CloudFormationStackArtifact` will contain the respective errors.
+	 * Absence indicates synthesis didn't fully complete.
 	 */
-	readonly topoSort?: boolean;
+	readonly stacks?: cxapi.CloudFormationStackArtifact[];
+	private constructor();
 }
-declare class Manifest {
+declare class ContextProviderError extends ToolkitError {
 	/**
-	 * Validates and saves the cloud assembly manifest to file.
-	 *
-	 * @param manifest - manifest.
-	 * @param filePath - output file path.
+	 * Denotes the source of the error as user.
 	 */
-	static saveAssemblyManifest(manifest: AssemblyManifest, filePath: string): void;
+	readonly source = "user";
+	constructor(message: string);
+}
+/**
+ * Which stacks should be selected from a cloud assembly
+ */
+export declare enum StackSelectionStrategy {
 	/**
-	 * Load and validates the cloud assembly manifest from file.
-	 *
-	 * @param filePath - path to the manifest file.
+	 * Returns all stacks in the app regardless of patterns,
+	 * including stacks inside nested assemblies.
 	 */
-	static loadAssemblyManifest(filePath: string, options?: LoadManifestOptions): AssemblyManifest;
+	ALL_STACKS = "all-stacks",
 	/**
-	 * Validates and saves the asset manifest to file.
-	 *
-	 * @param manifest - manifest.
-	 * @param filePath - output file path.
+	 * Returns all stacks in the main (top level) assembly only.
 	 */
-	static saveAssetManifest(manifest: AssetManifest, filePath: string): void;
+	MAIN_ASSEMBLY = "main-assembly",
 	/**
-	 * Load and validates the asset manifest from file.
-	 *
-	 * @param filePath - path to the manifest file.
+	 * If the assembly includes a single stack, returns it.
+	 * Otherwise throws an exception.
 	 */
-	static loadAssetManifest(filePath: string): AssetManifest;
+	ONLY_SINGLE = "only-single",
 	/**
-	 * Validates and saves the integ manifest to file.
-	 *
-	 * @param manifest - manifest.
-	 * @param filePath - output file path.
+	 * Return stacks matched by patterns.
+	 * If no stacks are found, execution is halted successfully.
+	 * Most likely you don't want to use this but `StackSelectionStrategy.MUST_MATCH_PATTERN`
 	 */
-	static saveIntegManifest(manifest: IntegManifest, filePath: string): void;
+	PATTERN_MATCH = "pattern-match",
 	/**
-	 * Load and validates the integ manifest from file.
-	 *
-	 * @param filePath - path to the manifest file.
+	 * Return stacks matched by patterns.
+	 * Throws an exception if the patterns don't match at least one stack in the assembly.
 	 */
-	static loadIntegManifest(filePath: string): IntegManifest;
+	PATTERN_MUST_MATCH = "pattern-must-match",
 	/**
-	 * Fetch the current schema version number.
+	 * Returns if exactly one stack is matched by the pattern(s).
+	 * Throws an exception if no stack, or more than exactly one stack are matched.
 	 */
-	static version(): string;
+	PATTERN_MUST_MATCH_SINGLE = "pattern-must-match-single"
+}
+/**
+ * When selecting stacks, what other stacks to include because of dependencies
+ */
+export declare enum ExpandStackSelection {
 	/**
-	 * Return the CLI version that supports this Cloud Assembly Schema version
+	 * Don't select any extra stacks
 	 */
-	static cliVersion(): string | undefined;
+	NONE = "none",
 	/**
-	 * Deprecated
-	 * @deprecated use `saveAssemblyManifest()`
+	 * Include stacks that this stack depends on
 	 */
-	static save(manifest: AssemblyManifest, filePath: string): void;
+	UPSTREAM = "upstream",
 	/**
-	 * Deprecated
-	 * @deprecated use `loadAssemblyManifest()`
+	 * Include stacks that depend on this stack
 	 */
-	static load(filePath: string): AssemblyManifest;
-	private static validate;
-	private static saveManifest;
-	private static loadManifest;
+	DOWNSTREAM = "downstream"
+}
+/**
+ * A specification of which stacks should be selected
+ */
+export interface StackSelector {
 	/**
-	 * This requires some explaining...
-	 *
-	 * We previously used `{ Key, Value }` for the object that represents a stack tag. (Notice the casing)
-	 * @link https://github.com/aws/aws-cdk/blob/v1.27.0/packages/aws-cdk/lib/api/cxapp/stacks.ts#L427.
-	 *
-	 * When that object moved to this package, it had to be JSII compliant, which meant the property
-	 * names must be `camelCased`, and not `PascalCased`. This meant it no longer matches the structure in the `manifest.json` file.
-	 * In order to support current manifest files, we have to translate the `PascalCased` representation to the new `camelCased` one.
-	 *
-	 * Note that the serialization itself still writes `PascalCased` because it relates to how CloudFormation expects it.
-	 *
-	 * Ideally, we would start writing the `camelCased` and translate to how CloudFormation expects it when needed. But this requires nasty
-	 * backwards-compatibility code and it just doesn't seem to be worth the effort.
+	 * The behavior if if no selectors are provided.
 	 */
-	private static patchStackTagsOnRead;
+	strategy: StackSelectionStrategy;
 	/**
-	 * Validates that `assumeRoleAdditionalOptions` doesn't contain nor `ExternalId` neither `RoleArn`, as they
-	 * should have dedicated properties preceding this (e.g `assumeRoleArn` and `assumeRoleExternalId`).
+	 * A list of patterns to match the stack hierarchical ids
+	 * Only used with `PATTERN_*` selection strategies.
 	 */
-	private static validateAssumeRoleAdditionalOptions;
+	patterns?: string[];
 	/**
-	 * See explanation on `patchStackTagsOnRead`
-	 *
-	 * Translate stack tags metadata if it has the "right" casing.
+	 * Expand the selection to upstream/downstream stacks.
+	 * @default ExpandStackSelection.None only select the specified/matched stacks
 	 */
-	private static patchStackTagsOnWrite;
+	expand?: ExpandStackSelection;
 	/**
-	 * Recursively replace stack tags in the stack metadata
+	 * By default, we throw an exception if the assembly contains no stacks.
+	 * Set to `false`, to halt execution for empty assemblies without error.
+	 *
+	 * Note that actions can still throw if a stack selection result is empty,
+	 * but the assembly contains stacks in principle.
+	 *
+	 * @default true
 	 */
-	private static replaceStackTags;
-	private constructor();
+	failOnEmpty?: boolean;
 }
 /**
  * The current action being performed by the CLI. 'none' represents the absence of an action.
  */
-export type ToolkitAction = "assembly" | "bootstrap" | "synth" | "list" | "diff" | "deploy" | "rollback" | "watch" | "destroy" | "doctor" | "gc" | "import" | "metadata" | "init" | "migrate";
+export type ToolkitAction = "assembly" | "bootstrap" | "synth" | "list" | "diff" | "deploy" | "rollback" | "watch" | "destroy" | "doctor" | "gc" | "import" | "metadata" | "init" | "migrate" | "refactor";
 /**
  * The reporting level of the message.
  * All messages are always reported, it's up to the IoHost to decide what to log.
@@ -2055,47 +1202,71 @@ export interface IIoHost {
 	 */
 	requestResponse<T, U>(msg: IoRequest<T, U>): Promise<U>;
 }
-interface CodeInfo {
+export interface BootstrapEnvironmentProgress {
 	/**
-	 * The message code.
+	 * The total number of environments being deployed
 	 */
-	readonly code: IoMessageCode;
+	readonly total: number;
 	/**
-	 * A brief description of the meaning of this IO Message.
+	 * The count of the environment currently bootstrapped
+	 *
+	 * This is counting value, not an identifier.
 	 */
-	readonly description: string;
+	readonly current: number;
 	/**
-	 * The name of the payload interface, if applicable.
-	 * Some Io Messages include a payload, with a specific interface. The name of
-	 * the interface is specified here so that it can be linked with the message
-	 * when documentation is generated.
-	 *
-	 * The interface _must_ be exposed directly from toolkit-lib, so that it will
-	 * have a documentation page generated (that can be linked to).
+	 * The environment that's currently being bootstrapped
 	 */
-	readonly interface?: string;
+	readonly environment: cxapi.Environment;
 }
-interface MessageInfo extends CodeInfo {
+interface IManifestEntry {
 	/**
-	 * The message level
+	 * The identifier of the asset and its destination
 	 */
-	readonly level: IoMessageLevel;
+	readonly id: DestinationIdentifier;
+	/**
+	 * The type of asset
+	 */
+	readonly type: string;
+	/**
+	 * Type-dependent source data
+	 */
+	readonly genericSource: unknown;
+	/**
+	 * Type-dependent destination data
+	 */
+	readonly genericDestination: unknown;
+	/**
+	 * Return a display name for this asset
+	 *
+	 * The `includeDestination` parameter controls whether or not to include the
+	 * destination ID in the display name.
+	 *
+	 * - Pass `false` if you are displaying notifications about building the
+	 *   asset, or if you are describing the work of building the asset and publishing
+	 *   to all destinations at the same time.
+	 * - Pass `true` if you are displaying notifications about publishing to a
+	 *   specific destination.
+	 */
+	displayName(includeDestination: boolean): string;
 }
-interface IoMessageMaker<T> extends MessageInfo {
+declare class DestinationIdentifier {
+	/**
+	 * Identifies the asset, by source.
+	 *
+	 * The assetId will be the same between assets that represent
+	 * the same physical file or image.
+	 */
+	readonly assetId: string;
 	/**
-	 * Create a message for this code, with or without payload.
+	 * Identifies the destination where this asset will be published
 	 */
-	msg: [
-		T
-	] extends [
-		AbsentData
-	] ? (message: string) => ActionLessMessage<AbsentData> : (message: string, data: T) => ActionLessMessage<T>;
+	readonly destinationId: string;
+	constructor(assetId: string, destinationId: string);
 	/**
-	 * Returns whether the given `IoMessage` instance matches the current message definition
+	 * Return a string representation for this asset identifier
 	 */
-	is(x: IoMessage<unknown>): x is IoMessage<T>;
+	toString(): string;
 }
-type AbsentData = void;
 /**
  * Assembly data returned in the payload of an IO Message.
  */
@@ -2191,147 +1362,6 @@ export interface ContextProviderMessageSource {
 	 */
 	readonly provider: string;
 }
-interface SpanEnd {
-	readonly duration: number;
-}
-interface SpanDefinition<S extends object, E extends SpanEnd> {
-	readonly name: string;
-	readonly start: IoMessageMaker<S>;
-	readonly end: IoMessageMaker<E>;
-}
-type EmptyObject = {
-	[index: string | number | symbol]: never;
-};
-type VoidWhenEmpty<T> = T extends EmptyObject ? void : T;
-type ForceEmpty<T> = T extends EmptyObject ? EmptyObject : T;
-type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
-interface ElapsedTime {
-	readonly asMs: number;
-	readonly asSec: number;
-}
-interface IMessageSpan<E extends SpanEnd> {
-	/**
-	 * Get the time elapsed since the start
-	 */
-	elapsedTime(): Promise<ElapsedTime>;
-	/**
-	 * Sends a simple, generic message with the current timing
-	 * For more complex intermediate messages, get the `elapsedTime` and use `notify`
-	 */
-	timing(maker: IoMessageMaker<Duration>, message?: string): Promise<ElapsedTime>;
-	/**
-	 * Sends an arbitrary intermediate message as part of the span
-	 */
-	notify(message: ActionLessMessage<unknown>): Promise<void>;
-	/**
-	 * End the span with a payload
-	 */
-	end(payload: VoidWhenEmpty<Omit<E, keyof SpanEnd>>): Promise<ElapsedTime>;
-	/**
-	 * End the span with a payload, overwriting
-	 */
-	end(payload: VoidWhenEmpty<Optional<E, keyof SpanEnd>>): Promise<ElapsedTime>;
-	/**
-	 * End the span with a message and payload
-	 */
-	end(message: string, payload: ForceEmpty<Optional<E, keyof SpanEnd>>): Promise<ElapsedTime>;
-}
-declare class SpanMaker<S extends object, E extends SpanEnd> {
-	private readonly definition;
-	private readonly ioHelper;
-	constructor(ioHelper: IoHelper, definition: SpanDefinition<S, E>);
-	/**
-	 * Starts the span and initially notifies the IoHost
-	 * @returns a message span
-	 */
-	begin(payload: VoidWhenEmpty<S>): Promise<IMessageSpan<E>>;
-	begin(message: string, payload: S): Promise<IMessageSpan<E>>;
-}
-type ActionLessMessage<T> = Omit<IoMessage<T>, "action">;
-type ActionLessRequest<T, U> = Omit<IoRequest<T, U>, "action">;
-declare class IoHelper implements IIoHost {
-	static fromIoHost(ioHost: IIoHost, action: ToolkitAction): IoHelper;
-	private readonly ioHost;
-	private readonly action;
-	private constructor();
-	/**
-	 * Forward a message to the IoHost, while injection the current action
-	 */
-	notify(msg: ActionLessMessage<unknown>): Promise<void>;
-	/**
-	 * Forward a request to the IoHost, while injection the current action
-	 */
-	requestResponse<T, U>(msg: ActionLessRequest<T, U>): Promise<U>;
-	/**
-	 * Create a new marker from a given registry entry
-	 */
-	span<S extends object, E extends SpanEnd>(definition: SpanDefinition<S, E>): SpanMaker<S, E>;
-}
-export interface BootstrapEnvironmentProgress {
-	/**
-	 * The total number of environments being deployed
-	 */
-	readonly total: number;
-	/**
-	 * The count of the environment currently bootstrapped
-	 *
-	 * This is counting value, not an identifier.
-	 */
-	readonly current: number;
-	/**
-	 * The environment that's currently being bootstrapped
-	 */
-	readonly environment: cxapi.Environment;
-}
-interface IManifestEntry {
-	/**
-	 * The identifier of the asset and its destination
-	 */
-	readonly id: DestinationIdentifier;
-	/**
-	 * The type of asset
-	 */
-	readonly type: string;
-	/**
-	 * Type-dependent source data
-	 */
-	readonly genericSource: unknown;
-	/**
-	 * Type-dependent destination data
-	 */
-	readonly genericDestination: unknown;
-	/**
-	 * Return a display name for this asset
-	 *
-	 * The `includeDestination` parameter controls whether or not to include the
-	 * destination ID in the display name.
-	 *
-	 * - Pass `false` if you are displaying notifications about building the
-	 *   asset, or if you are describing the work of building the asset and publishing
-	 *   to all destinations at the same time.
-	 * - Pass `true` if you are displaying notifications about publishing to a
-	 *   specific destination.
-	 */
-	displayName(includeDestination: boolean): string;
-}
-declare class DestinationIdentifier {
-	/**
-	 * Identifies the asset, by source.
-	 *
-	 * The assetId will be the same between assets that represent
-	 * the same physical file or image.
-	 */
-	readonly assetId: string;
-	/**
-	 * Identifies the destination where this asset will be published
-	 */
-	readonly destinationId: string;
-	constructor(assetId: string, destinationId: string);
-	/**
-	 * Return a string representation for this asset identifier
-	 */
-	toString(): string;
-}
 /**
  * Different types of permission related changes in a diff
  */
@@ -2349,18 +1379,38 @@ export declare enum PermissionChangeType {
 	 */
 	NON_BROADENING = "non-broadening"
 }
-/**
- * Output of the diff command
- */
-export interface DiffResult extends Duration {
-	/**
-	 * Stack diff formatted as a string
-	 */
-	readonly formattedStackDiff: string;
-	/**
-	 * Security diff formatted as a string
-	 */
-	readonly formattedSecurityDiff: string;
+/**
+ * Output of the diff command
+ */
+export interface DiffResult extends Duration {
+	/**
+	 * Stack diff formatted as a string
+	 */
+	readonly formattedStackDiff: string;
+	/**
+	 * Security diff formatted as a string
+	 */
+	readonly formattedSecurityDiff: string;
+}
+export type DeployStackResult = SuccessfulDeployStackResult | NeedRollbackFirstDeployStackResult | ReplacementRequiresRollbackStackResult;
+/** Successfully deployed a stack */
+export interface SuccessfulDeployStackResult {
+	readonly type: "did-deploy-stack";
+	readonly noOp: boolean;
+	readonly outputs: {
+		[name: string]: string;
+	};
+	readonly stackArn: string;
+}
+/** The stack is currently in a failpaused state, and needs to be rolled back before the deployment */
+export interface NeedRollbackFirstDeployStackResult {
+	readonly type: "failpaused-need-rollback-first";
+	readonly reason: "not-norollback" | "replacement";
+	readonly status: string;
+}
+/** The upcoming change has a replacement, which requires deploying with --rollback */
+export interface ReplacementRequiresRollbackStackResult {
+	readonly type: "replacement-requires-rollback";
 }
 export interface StackDeployProgress {
 	/**
@@ -2388,26 +1438,6 @@ export interface DeployConfirmationRequest extends ConfirmationRequest {
 	 */
 	readonly permissionChangeType: PermissionChangeType;
 }
-export type DeployStackResult = SuccessfulDeployStackResult | NeedRollbackFirstDeployStackResult | ReplacementRequiresRollbackStackResult;
-/** Successfully deployed a stack */
-export interface SuccessfulDeployStackResult {
-	readonly type: "did-deploy-stack";
-	readonly noOp: boolean;
-	readonly outputs: {
-		[name: string]: string;
-	};
-	readonly stackArn: string;
-}
-/** The stack is currently in a failpaused state, and needs to be rolled back before the deployment */
-export interface NeedRollbackFirstDeployStackResult {
-	readonly type: "failpaused-need-rollback-first";
-	readonly reason: "not-norollback" | "replacement";
-	readonly status: string;
-}
-/** The upcoming change has a replacement, which requires deploying with --rollback */
-export interface ReplacementRequiresRollbackStackResult {
-	readonly type: "replacement-requires-rollback";
-}
 export interface StackDeployProgress {
 	/**
 	 * The total number of stacks being deployed
@@ -2611,6 +1641,87 @@ export interface StackSelectionDetails {
 	 */
 	readonly stacks: StackSelector;
 }
+interface IDifference<ValueType> {
+	readonly oldValue: ValueType | undefined;
+	readonly newValue: ValueType | undefined;
+	readonly isDifferent: boolean;
+	readonly isAddition: boolean;
+	readonly isRemoval: boolean;
+	readonly isUpdate: boolean;
+}
+declare class Difference<ValueType> implements IDifference<ValueType> {
+	readonly oldValue: ValueType | undefined;
+	readonly newValue: ValueType | undefined;
+	/**
+	 * Whether this is an actual different or the values are actually the same
+	 *
+	 * isDifferent => (isUpdate | isRemoved | isUpdate)
+	 */
+	isDifferent: boolean;
+	/**
+	 * @param oldValue the old value, cannot be equal (to the sense of +deepEqual+) to +newValue+.
+	 * @param newValue the new value, cannot be equal (to the sense of +deepEqual+) to +oldValue+.
+	 */
+	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined);
+	/** @returns +true+ if the element is new to the template. */
+	get isAddition(): boolean;
+	/** @returns +true+ if the element was removed from the template. */
+	get isRemoval(): boolean;
+	/** @returns +true+ if the element was already in the template and is updated. */
+	get isUpdate(): boolean;
+}
+declare class PropertyDifference<ValueType> extends Difference<ValueType> {
+	changeImpact?: ResourceImpact;
+	constructor(oldValue: ValueType | undefined, newValue: ValueType | undefined, args: {
+		changeImpact?: ResourceImpact;
+	});
+}
+declare enum ResourceImpact {
+	/** The existing physical resource will be updated */
+	WILL_UPDATE = "WILL_UPDATE",
+	/** A new physical resource will be created */
+	WILL_CREATE = "WILL_CREATE",
+	/** The existing physical resource will be replaced */
+	WILL_REPLACE = "WILL_REPLACE",
+	/** The existing physical resource may be replaced */
+	MAY_REPLACE = "MAY_REPLACE",
+	/** The existing physical resource will be destroyed */
+	WILL_DESTROY = "WILL_DESTROY",
+	/** The existing physical resource will be removed from CloudFormation supervision */
+	WILL_ORPHAN = "WILL_ORPHAN",
+	/** The existing physical resource will be added to CloudFormation supervision */
+	WILL_IMPORT = "WILL_IMPORT",
+	/** There is no change in this resource */
+	NO_CHANGE = "NO_CHANGE"
+}
+interface Resource {
+	Type: string;
+	Properties?: {
+		[name: string]: any;
+	};
+	[key: string]: any;
+}
+interface TypedMapping {
+	readonly type: string;
+	readonly sourcePath: string;
+	readonly destinationPath: string;
+}
+/**
+ * Output of the refactor command
+ */
+export interface RefactorResult {
+	/**
+	 * Mappings along with the resource type
+	 */
+	readonly typedMappings?: TypedMapping[];
+	/**
+	 * Ambiguous path correspondences, if any
+	 */
+	readonly ambiguousPaths?: [
+		string[],
+		string[]
+	][];
+}
 /**
  * The computed file watch settings
  */
@@ -2878,219 +1989,9 @@ export interface HotswapResult extends Duration, HotswapDeploymentDetails {
 	 */
 	readonly hotswapped: boolean;
 }
-/**
- * @deprecated
- */
-declare enum RequireApproval$1 {
-	/**
-	 * Never require any security approvals
-	 */
-	NEVER = "never",
-	/**
-	 * Any security changes require an approval
-	 */
-	ANY_CHANGE = "any-change",
-	/**
-	 * Require approval only for changes that are access broadening
-	 */
-	BROADENING = "broadening"
-}
-interface FormatSecurityDiffOutput {
-	/**
-	 * Complete formatted security diff, if it is prompt-worthy
-	 */
-	readonly formattedDiff?: string;
-}
-interface FormatStackDiffOutput {
-	/**
-	 * Number of stacks with diff changes
-	 */
-	readonly numStacksWithChanges: number;
-	/**
-	 * Complete formatted diff
-	 */
-	readonly formattedDiff: string;
-}
-interface DiffFormatterProps {
-	/**
-	 * Helper for the IoHost class
-	 */
-	readonly ioHelper: IoHelper;
-	/**
-	 * The old/current state of the stack.
-	 */
-	readonly oldTemplate: any;
-	/**
-	 * The new/target state of the stack.
-	 */
-	readonly newTemplate: cxapi.CloudFormationStackArtifact;
-}
-interface FormatSecurityDiffOptions {
-	/**
-	 * The approval level of the security diff
-	 */
-	readonly requireApproval: RequireApproval$1;
-	/**
-	 * The name of the Stack.
-	 */
-	readonly stackName?: string;
-	/**
-	 * The changeSet for the Stack.
-	 *
-	 * @default undefined
-	 */
-	readonly changeSet?: DescribeChangeSetOutput;
-}
-interface FormatStackDiffOptions {
-	/**
-	 * do not filter out AWS::CDK::Metadata or Rules
-	 *
-	 * @default false
-	 */
-	readonly strict?: boolean;
-	/**
-	 * lines of context to use in arbitrary JSON diff
-	 *
-	 * @default 3
-	 */
-	readonly context?: number;
-	/**
-	 * silences \'There were no differences\' messages
-	 *
-	 * @default false
-	 */
-	readonly quiet?: boolean;
-	/**
-	 * The name of the stack
-	 */
-	readonly stackName?: string;
-	/**
-	 * @default undefined
-	 */
-	readonly changeSet?: DescribeChangeSetOutput;
-	/**
-	 * @default false
-	 */
-	readonly isImport?: boolean;
-	/**
-	 * @default undefined
-	 */
-	readonly nestedStackTemplates?: {
-		[nestedStackLogicalId: string]: NestedStackTemplates;
-	};
-}
-/**
- * Class for formatting the diff output
- */
-export declare class DiffFormatter {
-	private readonly ioHelper;
-	private readonly oldTemplate;
-	private readonly newTemplate;
-	constructor(props: DiffFormatterProps);
-	/**
-	 * Format the stack diff
-	 */
-	formatStackDiff(options: FormatStackDiffOptions): FormatStackDiffOutput;
-	private formatStackDiffHelper;
-	/**
-	 * Format the security diff
-	 */
-	formatSecurityDiff(options: FormatSecurityDiffOptions): FormatSecurityDiffOutput;
-}
-/**
- * Represents a general toolkit error in the AWS CDK Toolkit.
- */
-export declare class ToolkitError extends Error {
-	/**
-	 * Determines if a given error is an instance of ToolkitError.
-	 */
-	static isToolkitError(x: any): x is ToolkitError;
-	/**
-	 * Determines if a given error is an instance of AuthenticationError.
-	 */
-	static isAuthenticationError(x: any): x is AuthenticationError;
-	/**
-	 * Determines if a given error is an instance of AssemblyError.
-	 */
-	static isAssemblyError(x: any): x is AssemblyError;
-	/**
-	 * Determines if a given error is an instance of AssemblyError.
-	 */
-	static isContextProviderError(x: any): x is ContextProviderError;
-	/**
-	 * An AssemblyError with an original error as cause
-	 */
-	static withCause(message: string, error: unknown): ToolkitError;
-	/**
-	 * The type of the error, defaults to "toolkit".
-	 */
-	readonly type: string;
-	/**
-	 * Denotes the source of the error as the toolkit.
-	 */
-	readonly source: "toolkit" | "user";
-	/**
-	 * The specific original cause of the error, if available
-	 */
-	readonly cause?: unknown;
-	constructor(message: string, type?: string, cause?: unknown);
-}
-/**
- * Represents an authentication-specific error in the AWS CDK Toolkit.
- */
-export declare class AuthenticationError extends ToolkitError {
-	/**
-	 * Denotes the source of the error as user.
-	 */
-	readonly source = "user";
-	constructor(message: string);
-}
-/**
- * Represents an error causes by cloud assembly synthesis
- *
- * This includes errors thrown during app execution, as well as failing annotations.
- */
-export declare class AssemblyError extends ToolkitError {
-	/**
-	 * An AssemblyError with an original error as cause
-	 */
-	static withCause(message: string, error: unknown): AssemblyError;
-	/**
-	 * An AssemblyError with a list of stacks as cause
-	 */
-	static withStacks(message: string, stacks?: cxapi.CloudFormationStackArtifact[]): AssemblyError;
-	/**
-	 * Denotes the source of the error as user.
-	 */
-	readonly source = "user";
-	/**
-	 * The stacks that caused the error, if available
-	 *
-	 * The `messages` property of each `cxapi.CloudFormationStackArtifact` will contain the respective errors.
-	 * Absence indicates synthesis didn't fully complete.
-	 */
-	readonly stacks?: cxapi.CloudFormationStackArtifact[];
-	private constructor();
-}
-/**
- * Represents an error originating from a Context Provider
- */
-export declare class ContextProviderError extends ToolkitError {
-	/**
-	 * Denotes the source of the error as user.
-	 */
-	readonly source = "user";
-	constructor(message: string);
-}
-/**
- * Removes CDKMetadata and Outputs in the template so that only resources for importing are left.
- * @returns template with import resources only
- */
-export declare function removeNonImportResources(stack: CloudFormationStackArtifact): any;
 
 export {
 	MissingContext$1 as MissingContext,
-	RequireApproval$1 as RequireApproval,
 };
 
 export {};