fix(toolkit-lib): fromCdkApp fails if working directory is given and outdir is relative

The documentation of `fromCdkApp` falsely claimed that it would create a
temporary directory and clean it up. It does not, it emits into
`cdk.out` which won't get cleaned up.

Update the docs.

Author: rix0rrr

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

@@ -1,3 +1,4 @@
+import * as path from 'path';
 import * as cxapi from '@aws-cdk/cx-api';
 import * as fs from 'fs-extra';
 import type { AssemblyDirectoryProps, AssemblySourceProps, ICloudAssemblySource } from '../';
@@ -25,9 +26,10 @@ export abstract class CloudAssemblySourceBuilder {
   /**
    * Create a Cloud Assembly from a Cloud Assembly builder function.
    *
-   * A temporary output directory will be created if no output directory is
-   * explicitly given. This directory will be cleaned up if synthesis fails, or
-   * when the Cloud Assembly produced by this source is disposed.
+   * The output directory will be evaluated with respect to the working
+   * directory if relative. If not given, it will synthesize into a temporary
+   * system directory. The temporary directory will be cleaned up, unless
+   * `deleteOutdir: false`.
    *
    * A write lock will be acquired on the output directory for the duration of
    * the CDK app synthesis (which means that no two apps can synthesize at the
@@ -51,10 +53,13 @@ export abstract class CloudAssemblySourceBuilder {
       lookups: props.lookups,
     };
 
+    const workingDirectory = props.workingDirectory ?? process.cwd();
+    const outdir = props.outdir ? path.resolve(workingDirectory, props.outdir) : undefined;
+
     return new ContextAwareCloudAssemblySource(
       {
         produce: async () => {
-          await using execution = await ExecutionEnvironment.create(services, { outdir: props.outdir });
+          await using execution = await ExecutionEnvironment.create(services, { outdir });
 
           const env = await execution.defaultEnvVars();
           const assembly = await execution.changeDir(async () =>
@@ -74,15 +79,16 @@ export abstract class CloudAssemblySourceBuilder {
                   throw AssemblyError.withCause('Assembly builder failed', error);
                 }
               }),
-            ), props.workingDirectory);
+            ), workingDirectory);
 
           // Convert what we got to the definitely correct type we're expecting, a cxapi.CloudAssembly
           const asm = cxapi.CloudAssembly.isCloudAssembly(assembly)
             ? assembly
             : await assemblyFromDirectory(assembly.directory, services.ioHelper, props.loadAssemblyOptions);
 
           const success = await execution.markSuccessful();
-          return new ReadableCloudAssembly(asm, success.readLock, { deleteOnDispose: execution.outDirIsTemporary });
+          const deleteOnDispose = props.deleteOutdir ?? execution.outDirIsTemporary;
+          return new ReadableCloudAssembly(asm, success.readLock, { deleteOnDispose });
         },
       },
       contextAssemblyProps,
@@ -129,9 +135,10 @@ export abstract class CloudAssemblySourceBuilder {
   /**
    * Use a directory containing an AWS CDK app as source.
    *
-   * A temporary output directory will be created if no output directory is
-   * explicitly given. This directory will be cleaned up if synthesis fails, or
-   * when the Cloud Assembly produced by this source is disposed.
+   * The output directory will be evaluated with respect to the working
+   * directory if relative. If not given, it will synthesize into a `cdk.out`
+   * subdirectory. This directory will not be cleaned up, unless
+   * `deleteOutdir: true`.
    *
    * A write lock will be acquired on the output directory for the duration of
    * the CDK app synthesis (which means that no two apps can synthesize at the
@@ -152,6 +159,9 @@ export abstract class CloudAssemblySourceBuilder {
       lookups: props.lookups,
     };
 
+    const workingDirectory = props.workingDirectory ?? process.cwd();
+    const outdir = path.resolve(workingDirectory, props.outdir ?? 'cdk.out');
+
     return new ContextAwareCloudAssemblySource(
       {
         produce: async () => {
@@ -161,7 +171,6 @@ export abstract class CloudAssemblySourceBuilder {
           //   await execInChildProcess(build, { cwd: props.workingDirectory });
           // }
 
-          const outdir = props.outdir ?? 'cdk.out';
           try {
             fs.mkdirpSync(outdir);
           } catch (e: any) {
@@ -185,13 +194,14 @@ export abstract class CloudAssemblySourceBuilder {
                 }
               },
               extraEnv: envWithContext,
-              cwd: props.workingDirectory,
+              cwd: workingDirectory,
             });
 
             const asm = await assemblyFromDirectory(outdir, services.ioHelper, props.loadAssemblyOptions);
 
             const success = await execution.markSuccessful();
-            return new ReadableCloudAssembly(asm, success.readLock, { deleteOnDispose: execution.outDirIsTemporary });
+            const deleteOnDispose = props.deleteOutdir ?? execution.outDirIsTemporary;
+            return new ReadableCloudAssembly(asm, success.readLock, { deleteOnDispose });
           });
         },
       },

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

@@ -80,6 +80,13 @@ export interface AssemblySourceProps {
    * Options to configure loading of the assembly after it has been synthesized
    */
   readonly loadAssemblyOptions?: LoadAssemblyOptions;
+
+  /**
+   * Delete the `outdir` when the assembly is disposed
+   *
+   * @default - `true` if `outdir` is not given, `false` otherwise
+   */
+  readonly deleteOutdir?: boolean;
 }
 
 /**

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

@@ -8,20 +8,32 @@ import type { CloudAssemblySourceBuilder } from '../../lib/api/cloud-assembly/pr
 export * from './test-cloud-assembly-source';
 export * from './test-io-host';
 
-function fixturePath(...parts: string[]): string {
-  return path.normalize(path.join(__dirname, '..', '_fixtures', ...parts));
+function appFixturePath(...parts: string[]): string {
+  const ret = path.normalize(path.join(__dirname, '..', '_fixtures', ...parts));
+  if (!fs.existsSync(ret)) {
+    throw new ToolkitError(`App Fixture not found: ${ret}`);
+  }
+  return ret;
 }
 
-export async function appFixture(toolkit: CloudAssemblySourceBuilder, name: string, context?: { [key: string]: any }) {
-  const appPath = fixturePath(name, 'app.js');
-  if (!fs.existsSync(appPath)) {
-    throw new ToolkitError(`App Fixture ${name} does not exist in ${appPath}`);
-  }
-  const app = `cat ${appPath} | node --input-type=module`;
-  return toolkit.fromCdkApp(app, {
+/**
+ * Return config we can send into `fromCdkApp` to execute a given app fixture
+ */
+export function appFixtureCommand(name: string) {
+  const appPath = appFixturePath(name, 'app.js');
+  return {
+    app: `cat ${appPath} | node --input-type=module`,
     workingDirectory: path.join(__dirname, '..', '..'),
+  };
+}
+
+export async function appFixture(toolkit: CloudAssemblySourceBuilder, name: string, context?: { [key: string]: any }) {
+  const app = appFixtureCommand(name);
+  return toolkit.fromCdkApp(app.app, {
+    workingDirectory: app.workingDirectory,
     outdir: tmpOutdir(),
-    context,
+    deleteOutdir: true,
+    ...options,
   });
 }
 
@@ -30,6 +42,7 @@ export function builderFixture(toolkit: CloudAssemblySourceBuilder, name: string
   const builder = require(path.join(__dirname, '..', '_fixtures', name)).default;
   return toolkit.fromAssemblyBuilder(builder, {
     outdir: tmpOutdir(),
+    deleteOutdir: true,
     context,
   });
 }

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

@@ -1,8 +1,10 @@
+import { promises as fs } from 'fs';
+import * as path from 'path';
 import { RWLock } from '../../../lib/api/rwlock';
 import { contextproviders } from '../../../lib/api/shared-private';
 import { ToolkitError } from '../../../lib/api/shared-public';
 import { Toolkit } from '../../../lib/toolkit/toolkit';
-import { appFixture, autoCleanOutDir, builderFixture, cdkOutFixture, TestIoHost } from '../../_helpers';
+import { appFixture, appFixtureCommand, autoCleanOutDir, builderFixture, cdkOutFixture, TestIoHost } from '../../_helpers';
 
 // these tests often run a bit longer than the default
 jest.setTimeout(10_000);
@@ -114,6 +116,24 @@ describe('fromCdkApp', () => {
     expect(assembly.cloudAssembly.stacksRecursively.map(s => s.hierarchicalId)).toEqual(['Stack1', 'Stack2']);
   });
 
+  test('synth succeeds when working directory is given and outdir is relative', async () => {
+    // WHEN
+    const app = await appFixtureCommand('two-empty-stacks');
+    const cx = await toolkit.fromCdkApp(app.app, {
+      workingDirectory: app.workingDirectory,
+      outdir: 'relative.dir',
+    });
+
+    try {
+      await using assembly = await cx.produce();
+
+      // THEN - synth succeeds
+      expect(assembly.cloudAssembly.stacksRecursively.map(s => s.hierarchicalId)).toEqual(['Stack1', 'Stack2']);
+    } finally {
+      await fs.rm(path.join(app.workingDirectory, 'relative.dir'), { force: true, recursive: true });
+    }
+  });
+
   test('can provide context', async () => {
     // WHEN
     const cx = await appFixture(toolkit, 'external-context', {