feat(toolkit-lib): environment variables for 'fromCdkApp' (#443)

Add an option `env` to `fromCdkApp`, to set the environment variables
for the synth'ing subprocess.

---

By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

Author: rix0rrr

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

@@ -8,7 +8,7 @@ import { ExecutionEnvironment, assemblyFromDirectory } from './prepare-source';
 import type { ToolkitServices } from '../../../toolkit/private';
 import { IO } from '../../io/private';
 import { ToolkitError, AssemblyError } from '../../shared-public';
-import type { AssemblyBuilder } from '../source-builder';
+import type { AssemblyBuilder, FromCdkAppOptions } from '../source-builder';
 import { ReadableCloudAssembly } from './readable-assembly';
 import { Context } from '../../context';
 import { RWLock } from '../../rwlock';
@@ -142,7 +142,7 @@ export abstract class CloudAssemblySourceBuilder {
    * @param props additional configuration properties
    * @returns the CloudAssembly source
    */
-  public async fromCdkApp(app: string, props: AssemblySourceProps = {}): Promise<ICloudAssemblySource> {
+  public async fromCdkApp(app: string, props: FromCdkAppOptions = {}): Promise<ICloudAssemblySource> {
     const services: ToolkitServices = await this.sourceBuilderServices();
     // @todo this definitely needs to read files from the CWD
     const context = new Context({ bag: new Settings(props.context ?? {}) });
@@ -171,7 +171,10 @@ export abstract class CloudAssemblySourceBuilder {
           await using execution = await ExecutionEnvironment.create(services, { outdir });
 
           const commandLine = await execution.guessExecutable(app);
-          const env = await execution.defaultEnvVars();
+          const env = noUndefined({
+            ...await execution.defaultEnvVars(),
+            ...props.env,
+          });
           return await execution.withContext(context.all, env, props.synthOptions, async (envWithContext, _ctx) => {
             await execInChildProcess(commandLine.join(' '), {
               eventPublisher: async (type, line) => {
@@ -200,3 +203,9 @@ export abstract class CloudAssemblySourceBuilder {
   }
 }
 
+/**
+ * Remove undefined values from a dictionary
+ */
+function noUndefined<A>(xs: Record<string, A>): Record<string, NonNullable<A>> {
+  return Object.fromEntries(Object.entries(xs).filter(([_, v]) => v !== undefined)) as any;
+}

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

@@ -82,6 +82,20 @@ export interface AssemblySourceProps {
   readonly loadAssemblyOptions?: LoadAssemblyOptions;
 }
 
+/**
+ * Options for the `fromCdkApp` Assembly Source constructor
+ */
+export interface FromCdkAppOptions extends AssemblySourceProps {
+  /**
+   * Additional environment variables
+   *
+   * These environment variables will be set in addition to the environment
+   * variables currently set in the process. A value of `undefined` will
+   * unset a particular environment variable.
+   */
+  readonly env?: Record<string, string | undefined>;
+}
+
 /**
  * Settings that are passed to a CDK app via the context
  */

packages/@aws-cdk/toolkit-lib/test/_fixtures/environment-variable/app.js

@@ -0,0 +1,12 @@
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as core from 'aws-cdk-lib/core';
+
+const stackName = process.env.STACK_NAME;
+if (!stackName) {
+    throw new Error('$STACK_NAME not set!');
+}
+
+const app = new core.App({ autoSynth: false });
+const stack = new core.Stack(app, stackName);
+new s3.Bucket(stack, 'MyBucket');
+app.synth();

packages/@aws-cdk/toolkit-lib/test/_helpers/index.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import type { AssemblyDirectoryProps, ICloudAssemblySource } from '../../lib';
+import type { AssemblyDirectoryProps, FromCdkAppOptions, ICloudAssemblySource } from '../../lib';
 import { ToolkitError } from '../../lib';
 import type { CloudAssemblySourceBuilder } from '../../lib/api/cloud-assembly/private';
 
@@ -12,7 +12,7 @@ function fixturePath(...parts: string[]): string {
   return path.normalize(path.join(__dirname, '..', '_fixtures', ...parts));
 }
 
-export async function appFixture(toolkit: CloudAssemblySourceBuilder, name: string, context?: { [key: string]: any }) {
+export async function appFixture(toolkit: CloudAssemblySourceBuilder, name: string, options?: Omit<FromCdkAppOptions, 'workingDirectory' | 'outdir'>) {
   const appPath = fixturePath(name, 'app.js');
   if (!fs.existsSync(appPath)) {
     throw new ToolkitError(`App Fixture ${name} does not exist in ${appPath}`);
@@ -21,7 +21,7 @@ export async function appFixture(toolkit: CloudAssemblySourceBuilder, name: stri
   return toolkit.fromCdkApp(app, {
     workingDirectory: path.join(__dirname, '..', '..'),
     outdir: tmpOutdir(),
-    context,
+    ...options,
   });
 }
 

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

@@ -117,7 +117,9 @@ describe('fromCdkApp', () => {
   test('can provide context', async () => {
     // WHEN
     const cx = await appFixture(toolkit, 'external-context', {
-      'externally-provided-bucket-name': 'amzn-s3-demo-bucket',
+      context: {
+        'externally-provided-bucket-name': 'amzn-s3-demo-bucket',
+      },
     });
     await using assembly = await cx.produce();
     const stack = assembly.cloudAssembly.getStackByName('Stack1').template;
@@ -126,6 +128,20 @@ describe('fromCdkApp', () => {
     expect(JSON.stringify(stack)).toContain('amzn-s3-demo-bucket');
   });
 
+  test('can set environment variables', async () => {
+    // WHEN
+    const cx = await appFixture(toolkit, 'environment-variable', {
+      env: {
+        STACK_NAME: 'SomeStackName',
+      },
+    });
+    await using assembly = await cx.produce();
+    const stack = assembly.cloudAssembly.getStackByName('SomeStackName').template;
+
+    // THEN
+    expect(stack).toBeDefined();
+  });
+
   test('will capture error output', async () => {
     // WHEN
     const cx = await appFixture(toolkit, 'validation-error');