feat(toolkit-lib): toolkit.fromCdkAppDirectory

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

@@ -84,11 +84,30 @@ export function contextFromSettings(
 
 /**
  * Convert settings to context/environment variables
+ *
+ * This function takes a `Settings` object and produces the corresponding context and environment variables.
+ *
+ * This is what the flow looks like:
+ *
+ * ```
+ *                                                                                            ┌───────────────┐           ┌───────────┐
+ *                                                                         writeContextToEnv  │  Env vars +   │           │  CDK App  │
+ * ┌─────────────────┐                                                              ┌────────▶│    context    │──spawn───▶│Subprocess │
+ * │                 │  settingsFromSynthOptions                                    │         │ overflow file │           │           │
+ * │ AppSynthOptions │────────────────┐                                             │         └───────────────┘           └───────────┘
+ * │                 │                ▼                          ┌─────────┐        │
+ * └─────────────────┘          ┌──────────┐          ┌─────────▶│ Context │────────┤
+ *                              │          │       synth         └─────────┘        │
+ *                              │ Settings │─────Parameters                         │
+ *                              │          │    FromSettings     ┌─────────┐        │
+ * ┌──────────┐                 └──────────┘          └─────────▶│Env vars │────────┤
+ * │          │          load         ▲                          └─────────┘        │                                   ┌────────────┐
+ * │ cdk.json │───────────────────────┘                                             │                pass directly      │CDK Assembly│
+ * │          │                                                                     └──────────────────────────────────▶│ Builder Fn │
+ * └──────────┘                                                                                                         └────────────┘
+ * ```
  */
-export function synthParametersFromSettings(settings: Settings): {
-  context: Context;
-  env: Env;
-} {
+export function synthParametersFromSettings(settings: Settings): SynthParameters {
   // These are the environment variables that will switch on debugging in the
   // CDK framework.
   //
@@ -118,6 +137,11 @@ export function synthParametersFromSettings(settings: Settings): {
   };
 }
 
+export interface SynthParameters {
+  context: Context;
+  env: Env;
+}
+
 export function spaceAvailableForContext(env: Env, limit: number) {
   const size = (value?: string) => value != null ? Buffer.byteLength(value) : 0;
 

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

@@ -53,15 +53,22 @@ export class ExecutionEnvironment implements AsyncDisposable {
    */
   public static async create(services: ToolkitServices, options: ExecutionEnvironmentOptions) {
     let outDirIsTemporary = false;
-    let dir = options.outdir;
-    if (!dir) {
+    let outdir = options.outdir;
+    if (!outdir) {
       outDirIsTemporary = true;
-      dir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'cdk.out'));
+      outdir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'cdk.out'));
+    } else {
+      try {
+        fs.mkdirpSync(outdir);
+      } catch (e: any) {
+        throw new ToolkitError('OutputDirectoryCreateFailed', `Could not create output directory at '${outdir}' (${e.message}).`);
+      }
     }
-    const lock = await new RWLock(dir).acquireWrite();
+
+    const lock = await new RWLock(outdir).acquireWrite();
 
     const opts = {
-      outdir: dir,
+      outdir,
       resolveDefaultAppEnv: options.resolveDefaultAppEnv,
     };
 
@@ -325,14 +332,23 @@ export async function assemblyFromDirectory(assemblyDir: string, ioHelper: IoHel
   }
 }
 
-export function settingsFromSynthOptions(synthOpts: AppSynthOptions = {}): Settings {
+/**
+ * Convert a set of synthesis options into a `Settings` object.
+ *
+ * The `Settings` object mimics the structure of the `cdk.json` file, and will be
+ * converted into appropriate context and environment variables for the CDK app
+ * elsewhere.
+ */
+export function settingsFromSynthOptions(synthOpts: AppSynthOptions | undefined = {}, how: 'withDefaults' | 'onlyThese'): Settings {
   return new Settings({
-    debug: false,
-    pathMetadata: true,
-    versionReporting: true,
-    assetMetadata: true,
-    assetStaging: true,
-    validation: true,
+    ...how === 'withDefaults' ? {
+      debug: false,
+      pathMetadata: true,
+      versionReporting: true,
+      assetMetadata: true,
+      assetStaging: true,
+      validation: true,
+    } : {},
     ...synthOpts,
   }, true);
 }
@@ -344,5 +360,5 @@ export function settingsFromSynthOptions(synthOpts: AppSynthOptions = {}): Setti
  * from the outside of the app.
  */
 export function parametersFromSynthOptions(synthOptions?: AppSynthOptions) {
-  return synthParametersFromSettings(settingsFromSynthOptions(synthOptions ?? {}));
+  return synthParametersFromSettings(settingsFromSynthOptions(synthOptions ?? {}, 'withDefaults'));
 }