feat(cli): CDK Migrate CLI command

packages/aws-cdk/README.md

@@ -20,6 +20,7 @@ The AWS CDK Toolkit provides the `cdk` command-line interface that can be used t
 | [`cdk diff`](#cdk-diff)               | Diff stacks against current state                                          |
 | [`cdk deploy`](#cdk-deploy)           | Deploy a stack into an AWS account                                         |
 | [`cdk import`](#cdk-import)           | Import existing AWS resources into a CDK stack                             |
+| [`cdk migrate`](#cdk-migrate)         | Convert an existing CFN template into a CDK Application                    |
 | [`cdk watch`](#cdk-watch)             | Watches a CDK app for deployable and hotswappable changes                  |
 | [`cdk destroy`](#cdk-destroy)         | Deletes a stack from an AWS account                                        |
 | [`cdk bootstrap`](#cdk-bootstrap)     | Deploy a toolkit stack to support deploying large stacks & artifacts       |
@@ -560,6 +561,111 @@ This feature is currently in preview. Be aware of the following limitations:
   in the right order. The CLI will not help you import dependent resources in the right
   order, the CloudFormation deployment will fail with unresolved references.
 
+
+### `cdk migrate`
+
+⚠️**CAUTION**⚠️ 
+
+CDK migrate is currently experimental and may have breaking changes in the future. 
+
+Generates a CDK application from an existing JSON/YAML CloudFormation template.
+Takes a valid CloudFormation template as input from either a local file specified with `--from-path`,
+or from a deployed Cloudformation stack using `--from-stack`. Generates a CDK application 
+which will synthesize a CloudFormation template with identical resource configurations to the provided template. 
+The generated application will be initialized in the current working directory with a single stack where 
+the stack, app, and directory will all be named using the provided `--stack-name`. The generated application will 
+be within a generated subdirectory in your current working directory unless `--output-path` is specified. 
+All CDK supported lanaguages are supported, language choice can be specified with `--language`.
+
+#### Generate a typescript application from a local template.json file
+
+```console
+$ # template.json is a valid cloudformation template in the local directory
+$ cdk migrate --from-path ./template.json --stack-name MyAwesomeApplication
+```
+
+This command will generate a new direcotry named `MyAwesomeApplication` within your current working directory, and 
+then initialize a new CDK application within that directory which has the same resource configuration as the
+as the provided template.json
+
+This results in a CDK application with the following structure, where the lib directory contains a stack definition
+with the same resource configuration as the provided template.json.
+
+```console
+├── README.md
+├── bin
+│   └── my_awesome_application.ts
+├── cdk.json
+├── cdk.out
+│   ├── MyAwesomeApplication.assets.json
+│   ├── MyAwesomeApplication.template.json
+│   ├── cdk.out
+│   ├── manifest.json
+│   ├── synth.lock
+│   └── tree.json
+├── jest.config.js
+├── lib
+│   └── my_awesome_application-stack.ts
+```
+
+#### Generate a python application from a deployed stack
+
+If you already had a cloudformation stack deployed in your account and would like to migrate to using CDK instead of Cloudformation.
+You can use the `--from-stack` option to generate the application. In this case the `--stack-name` must match the name of the deployed stack. 
+
+```console
+$ # generate a python application from MyDeployedStack in your acount
+$ cdk bootstrap migrate --stack-name MyDeployedStack --language python --from-stack
+```
+
+This will generate a python CDK application which will synthesize to the same configuration of resources as the deployed stack.
+
+#### **CDK Migrate Limitations**
+
+CDK Migrate does not currently support nested stacks, Custom resources, or ForEach intrinsic function.
+CDK Migrate will only generate L1 constructs and does not currently support any higher level abstractions.
+CDK Migrate succesfully generating an application does *not* guarantee the application is immediately deployable.
+It simply generates a CDK application which will synthesize a template that has identical resource configurations 
+to the provided template. CDK Migrate does not interact with the CloudFormation service to verify the template 
+provided can deploy on it's own, nor does it validate that any resources in the provided template are already managed 
+in other CloudFormation Templates. In practice this is how CDK Migrate generated applications will 
+operate in the following scenarios:
+
+##### **The provided template is already deployed to cloudformation in the account/region**
+
+If the provided template came directly from a deployed cloudformation stack, and that stack has not experienced any drift, 
+then the generated application will be immediately deployable, and will not cause any changes to the deployed resources.
+Drift might occur if a resource in your template was modified outside of CloudFormation, namely via the console or CLI.
+
+##### **The provided template is not deployed to cloudformation in the account/region, and there *is not* overlap with with resources outside the template**
+
+If the provided template represents a set of resources that have no overlap with resources already deployed in the account/region, 
+then the generated application will be immediately deployable. A common reason for this might be because the template came 
+from a stack deployed in another account/region.
+
+In practice this means for any resource in the provided template. i.e.
+
+```Json
+    "S3Bucket": {
+      "Type": "AWS::S3::Bucket",
+      "Properties": {
+        "BucketName": "MyBucket",
+        "AccessControl": "PublicRead",
+      },
+      "DeletionPolicy": "Retain"
+    }
+```
+
+There must not exist a resource of that type with the same name aka "MyBucket"
+
+##### **The provided template is not deployed to cloudformation in the account/region, and there *is* overlap with with resources outside the template**
+
+If the provided template represents a set of resources that have overlap with resources already deployed in the account/region, 
+then the generated application will not be immediately deployable. If those overlapped resources are already managed by 
+another CloudFormation stack in that account/region, then those resources will need to be manually removed from the provided
+template. Otherwise, if the overlapped resources are not managed by another CloudFormation stack, then first run remove those
+resources and deploy the template successfully, then re-add them and run `cdk import` to import them into your deployed stack.
+
 ### `cdk destroy`
 
 Deletes a stack from it's environment. This will cause the resources in the stack to be destroyed (unless they were