refactor: remove app boilerplate and improvements to cx protocol (#868)

Change the cx protocol to use environment variables and file output
instead of argv/stdout. This simplifies the App boilerplate code.
Now, apps look like this:

    const app = new App();
    // add stacks
    app.run();

The protocol was also simplified to basically always synthesize all
stacks in the app, eliminating the need for a "cx request" altogether.

The toolkit was modified to cache the response of the first successful
execution of the app (after environment contextual is resolved). This
reduces the number of app executions to a maximum of 2 (if env context
is missing) and normally 1. Previoiusly, "list" and "synth" were two
separate commands, so 2 was the normal case.

The protocol now uses the following environment variables:

 * `CDK_OUTDIR` represents the synthesis output directory. The toolkit
   allocates a temporary working directory when it executes the app and
   sets this variable.
 * `CDK_CONTEXT_JSON` is a JSON stringified context object.

At the moment, if `CDK_OUTDIR` is not defined, an error message is printed
indicating the minimum version of the toolkit required to interact with
the app.

Fixes #216

BREAKING CHANGE

This is a major breaking change:

- The `cdk.App` initializer doesn't accept any arguments.
- The `cdk.App#run` method does not return a `string` anymore.

All AWS CDK apps in all languages would need to be modified
to adhere to the new API of the `cdk.App` construct.

Instead of:

    const app = new App(process.argv); // ERROR
    // add stacks
    process.stdout.write(app.run());   // ERROR

The new usage is:

    const app = new App();
    // add stacks
    app.run();

In order to interact with applications written using this
version, the CDK Toolkit must also be update using:

    $ npm i -g aws-cdk

docs/src/apps.rst

@@ -27,11 +27,11 @@ as shown in the following example.
 
    import { App } from '@aws-cdk/cdk'
 
-   const app = new App(process.argv); // input: ARGV
+   const app = new App(); // input: ARGV
 
    // <add stacks here>
 
-   process.stdout.write(app.run());
+   app.run();
 
 An |app-construct| is a collection of |stack| objects, as shown in the following
 example.
@@ -41,7 +41,7 @@ example.
    import { App } from '@aws-cdk/cdk'
    import { MyStack } from './my-stack'
 
-   const app = new App(process.argv);
+   const app = new App();
 
    const dev = new MyStack(app, { name: 'Dev', region: 'us-west-2', dev: true })
    const preProd = new MyStack(app, { name: 'PreProd', region: 'us-west-2', preProd: true })
@@ -58,7 +58,7 @@ example.
        prodStages: prod
    });
 
-   process.stdout.write(app.run());
+   app.run();
 
 Use the |toolkit| to list the stacks in this executable,
 as shown in the following example.

docs/src/examples.rst

@@ -68,7 +68,7 @@ the |cdk|.
    import { MyStack } from './my-stack'
    import { DeploymentPipeline } from './my-deployment'
 
-   const app = new App(process.argv);
+   const app = new App();
 
    // Use the default environment
    new MyStack(app, { name: 'Dev' });
@@ -107,9 +107,7 @@ the |cdk|.
       prodStages: prod
    });
 
-   app.exec()
-      .then(stdout => process.stdout.write(stdout))
-      .catch(e => { throw e });
+   app.run();
 
 .. _dynamodb_example:
 
@@ -140,11 +138,11 @@ and sort key **Timestamp**.
      }
    }
 
-   const app = new cdk.App(process.argv);
+   const app = new cdk.App();
 
    new MyStack(app, 'MyStack');
 
-   process.stdout.write(app.run());
+    app.run();
 
 .. _creating_rds_example:
 
@@ -183,11 +181,11 @@ The following example creates the Aurora database **MyAuroraDatabase**.
      }
    }
 
-   const app = new cdk.App(process.argv);
+   const app = new cdk.App();
 
    new MyStack(app, 'MyStack');
 
-   process.stdout.write(app.run());
+   app.run();
 
 .. _creating_s3_example:
 
@@ -213,8 +211,8 @@ encryption provided by |S3|.
      }
    }
 
-   const app = new cdk.App(process.argv);
+   const app = new cdk.App();
 
    new MyStack(app, 'MyStack');
 
-   process.stdout.write(app.run());
+   app.run()

docs/src/getting-started.rst

@@ -203,7 +203,7 @@ class. Let's create our first, empty **App**:
                 }
             }
 
-            process.stdout.write(new MyApp(process.argv).run());
+            new MyApp().run();
 
     .. group-tab:: TypeScript
 
@@ -219,7 +219,7 @@ class. Let's create our first, empty **App**:
                 }
             }
 
-            process.stdout.write(new MyApp(process.argv).run());
+            new MyApp().run();
 
     .. group-tab:: Java
 
@@ -454,7 +454,7 @@ Define a stack and add it to the app.
                 }
             }
 
-            process.stdout.write(new MyApp(process.argv).run());
+            new MyApp().run();
 
     .. group-tab:: TypeScript
 
@@ -472,14 +472,13 @@ Define a stack and add it to the app.
             }
 
             class MyApp extends cdk.App {
-                constructor(argv: string[]) {
-                    super(argv);
-
+                constructor() {
+                    super();
                     new MyStack(this, 'hello-cdk');
                 }
             }
 
-            process.stdout.write(new MyApp(process.argv).run());
+            new MyApp().run();
 
     .. group-tab:: Java
 

docs/src/passing-in-data.rst

@@ -155,15 +155,15 @@ Finally, connect the dots in your app.
 
 .. code-block:: ts
 
-    const app = new cdk.App(process.argv);
+    const app = new cdk.App();
 
     const myStack = new HelloCdkStack(app, "HelloCdkStack");
 
     new MyCdkStack(app, "MyCdkStack", {
         theBucketRefProps: myStack.myBucketRefProps
     });
 
-    process.stdout.write(app.run());
+    app.run();
 
 .. _using_cfn_parameter:
 

docs/src/stacks.rst

@@ -47,7 +47,7 @@ And then, add instances of this class to your app:
 
 .. code-block:: js
 
-    const app = new App(process.argv);
+    const app = new App();
 
     new MyStack(app, 'NorthAmerica', { env: { region: 'us-east-1' } });
     new MyStack(app, 'Europe', { env: { region: 'us-west-2' } });

examples/cdk-examples-java/project/src/main/java/software/amazon/awscdk/examples/HelloJavaApp.java

@@ -6,10 +6,10 @@
 
 public class HelloJavaApp {
     public static void main(final String[] args) {
-        App app = new App(Arrays.asList(args));
+        App app = new App();
 
         new HelloJavaStack(app, "hello-cdk");
 
-        System.out.println(app.run());
+        app.run();
     }
 }

examples/cdk-examples-typescript/advanced-usage/index.ts

@@ -188,7 +188,7 @@ class CloudFormationExample extends cdk.Stack {
   }
 }
 
-const app = new cdk.App(process.argv);
+const app = new cdk.App();
 
 new PolicyExample(app, 'PolicyExample');
 new IncludeExample(app, 'IncludeExample');
@@ -199,4 +199,4 @@ new CloudFormationExample(app, 'CloudFormationExample');
 new EnvContextExample(app, 'EnvContextExampleNA', { env: { region: 'us-east-1' }});
 new EnvContextExample(app, 'EnvContextExampleEU', { env: { region: 'eu-west-2' }});
 
-process.stdout.write(app.run());
+app.run();

examples/cdk-examples-typescript/bucket-import-export/index.ts

@@ -57,12 +57,12 @@ class Consumer extends cdk.Stack {
 // first. In the future the toolkit will be able to understand the relationships
 // between the stacks and will deploy them in order.
 
-const app = new cdk.App(process.argv);
+const app = new cdk.App();
 
 const producer = new Producer(app, 'produce');
 
 new Consumer(app, 'consume', {
   userBucketRef: producer.myBucketRef
 });
 
-process.stdout.write(app.run());
+app.run();

examples/cdk-examples-typescript/chat-app/index.ts

@@ -86,10 +86,10 @@ class ChatAppFunction extends lambda.Function {
   }
 }
 
-const app = new cdk.App(process.argv);
+const app = new cdk.App();
 
 // Add the stack to the app
 // (apps can host many stacks, for example, one for each region)
 new MyStack(app, 'ChatAppStack', { env: { region: 'us-west-2' } });
 
-process.stdout.write(app.run());
+app.run();

examples/cdk-examples-typescript/cloudformation/index.ts

@@ -11,8 +11,8 @@ class CloudFormationExample extends cdk.Stack {
   }
 }
 
-const app = new cdk.App(process.argv);
+const app = new cdk.App();
 
 new CloudFormationExample(app);
 
-process.stdout.write(app.run());
+app.run();

examples/cdk-examples-typescript/custom-resource/index.ts

@@ -95,10 +95,10 @@ class FailAfterCreatingStack extends cdk.Stack {
   }
 }
 
-const app = new cdk.App(process.argv);
+const app = new cdk.App();
 
 new SucceedingStack(app, 'SucceedingStack');
 new FailCreationStack(app, 'FailCreationStack');
 new FailAfterCreatingStack(app, 'FailAfterCreatingStack');
 
-process.stdout.write(app.run());
+app.run();

examples/cdk-examples-typescript/ec2/cdk.json

@@ -9,6 +9,6 @@
       "us-east-1e",
       "us-east-1f"
     ],
-    "ssm:585695036304:us-east-1:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2": "ami-14c5486b"
+    "ssm:585695036304:us-east-1:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2": "ami-0ff8a91507f77f867"
   }
-}
+}

examples/cdk-examples-typescript/ec2/index.ts

@@ -62,11 +62,11 @@ class CommonInfrastructure extends cdk.Stack {
   }
 }
 
-const app = new cdk.App(process.argv);
+const app = new cdk.App();
 
 const infra = new CommonInfrastructure(app, 'infra');
 
 new AppWithVpc(app, 'app-with-vpc');
 new MyApp(app, 'my-app', { infra });
 
-process.stdout.write(app.run());
+app.run();