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 '../';
@@ -129,9 +130,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 (but you should still
+   * call `.dispose()` on the Cloud Assembly returned by this assembly source).
    *
    * 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 +154,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 +166,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,7 +189,7 @@ export abstract class CloudAssemblySourceBuilder {
                 }
               },
               extraEnv: envWithContext,
-              cwd: props.workingDirectory,
+              cwd: workingDirectory,
             });
 
             const asm = await assemblyFromDirectory(outdir, services.ioHelper, props.loadAssemblyOptions);

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

@@ -8,18 +8,29 @@ 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,
   });

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', {