feat(toolkit): watch operation can be stopped

The `toolkit.watch()` operation used to start a filesystem watcher in
the background and immediately return. The caller would continue running
to its end, while the filesystem watcher would keep the node process
alive.

Instead, now return an `IWatcher` object that can be disposed
to stop the watching, and can be used to wait for the watcher to stop.

Author: rix0rrr

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

@@ -5,4 +5,4 @@ export interface ICloudAssemblySource {
    * Produce a CloudAssembly from the current source
    */
   produce(): Promise<cxapi.CloudAssembly>;
-}
+}

packages/@aws-cdk/toolkit-lib/lib/toolkit/toolkit.ts

@@ -34,6 +34,7 @@ import type { AssemblyData, StackDetails, ToolkitAction } from '../api/shared-pu
 import { DiffFormatter, RequireApproval, ToolkitError, removeNonImportResources } from '../api/shared-public';
 import { obscureTemplate, serializeStructure, validateSnsTopicArn, formatTime, formatErrorMessage, deserializeStructure } from '../private/util';
 import { pLimit } from '../util/concurrency';
+import { promiseWithResolvers } from '../util/promises';
 
 export interface ToolkitOptions {
   /**
@@ -736,10 +737,12 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
   /**
    * Watch Action
    *
-   * Continuously observe project files and deploy the selected stacks automatically when changes are detected.
-   * Implies hotswap deployments.
+   * Continuously observe project files and deploy the selected stacks
+   * automatically when changes are detected.  Implies hotswap deployments.
+   *
+   * This function returns immediately, starting a watcher in the background.
    */
-  public async watch(cx: ICloudAssemblySource, options: WatchOptions): Promise<void> {
+  public async watch(cx: ICloudAssemblySource, options: WatchOptions): Promise<IWatcher> {
     const ioHelper = asIoHelper(this.ioHost, 'watch');
     const assembly = await assemblyFromSource(ioHelper, cx, false);
     const rootDir = options.watchDir ?? process.cwd();
@@ -818,7 +821,7 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
       await cloudWatchLogMonitor?.activate();
     };
 
-    chokidar
+    const watcher = chokidar
       .watch(watchIncludes, {
         ignored: watchExcludes,
         cwd: rootDir,
@@ -848,6 +851,26 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
           ));
         }
       });
+
+    const stoppedPromise = promiseWithResolvers<void>();
+
+    return {
+      async dispose() {
+        watcher.close();
+        // Prevents Node from staying alive. There is no 'end' event that the watcher emits
+        // that we can know it's definitely done, so best we can do is tell it to stop watching,
+        // stop keeping Node alive, and then pretend that's everything we needed to do.
+        watcher.unref();
+        stoppedPromise.resolve();
+        return stoppedPromise.promise;
+      },
+      async waitForEnd() {
+        return stoppedPromise.promise;
+      },
+      async [Symbol.asyncDispose]() {
+        return this.dispose();
+      },
+    } satisfies IWatcher;
   }
 
   /**
@@ -1016,3 +1039,25 @@ export class Toolkit extends CloudAssemblySourceBuilder implements AsyncDisposab
     }
   }
 }
+
+/**
+ * The result of a `cdk.watch()` operation.
+ */
+export interface IWatcher extends AsyncDisposable {
+  /**
+   * Stop the watcher and wait for the current watch iteration to complete.
+   *
+   * An alias for `[Symbol.asyncDispose]`, as a more readable alternative for
+   * environments that don't support the Disposable APIs yet.
+   */
+  dispose(): Promise<void>;
+
+  /**
+   * Wait for the watcher to stop.
+   *
+   * The watcher will only stop if `dispose()` or `[Symbol.asyncDispose]()` are called.
+   *
+   * If neither of those is called, awaiting this promise will wait forever.
+   */
+  waitForEnd(): Promise<void>;
+}

packages/@aws-cdk/toolkit-lib/lib/util/promises.ts

@@ -0,0 +1,19 @@
+/**
+ * A backport of Promiser.withResolvers
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
+ */
+export function promiseWithResolvers<A>(): PromiseAndResolvers<A> {
+  let resolve: PromiseAndResolvers<A>['resolve'], reject: PromiseAndResolvers<A>['reject'];
+  const promise = new Promise<A>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve: resolve!, reject: reject! };
+}
+
+interface PromiseAndResolvers<A> {
+  promise: Promise<A>;
+  resolve: (value: A) => void;
+  reject: (reason: any) => void;
+}

packages/@aws-cdk/toolkit-lib/test/actions/watch.test.ts

@@ -3,9 +3,13 @@
 // Apparently, they hoist jest.mock commands just below the import statements so we
 // need to make sure that the constants they access are initialized before the imports.
 const mockChokidarWatcherOn = jest.fn();
+const mockChokidarWatcherClose = jest.fn();
+const mockChokidarWatcherUnref = jest.fn();
 const fakeChokidarWatcher = {
   on: mockChokidarWatcherOn,
-};
+  close: mockChokidarWatcherClose,
+  unref: mockChokidarWatcherUnref,
+} satisfies Partial<ReturnType<typeof import('chokidar')['watch']>>;
 const fakeChokidarWatcherOn = {
   get readyCallback(): () => Promise<void> {
     expect(mockChokidarWatcherOn.mock.calls.length).toBeGreaterThanOrEqual(1);
@@ -149,6 +153,23 @@ describe('watch', () => {
     (deploySpy.mock.calls[0]?.[2] as any).cloudWatchLogMonitor?.deactivate();
   });
 
+  test('watch returns an object that can be used to stop the watch', async () => {
+    const cx = await builderFixture(toolkit, 'stack-with-role');
+
+    const watcher = await toolkit.watch(cx, { include: [] });
+
+    expect(mockChokidarWatcherClose).not.toHaveBeenCalled();
+    expect(mockChokidarWatcherUnref).not.toHaveBeenCalled();
+
+    await Promise.all([
+      watcher.waitForEnd(),
+      watcher.dispose(),
+    ]);
+
+    expect(mockChokidarWatcherClose).toHaveBeenCalled();
+    expect(mockChokidarWatcherUnref).toHaveBeenCalled();
+  });
+
   describe.each([
     [HotswapMode.FALL_BACK, 'on'],
     [HotswapMode.HOTSWAP_ONLY, 'on'],

packages/aws-cdk/lib/cli/cli.ts

@@ -424,7 +424,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
 
       case 'watch':
         ioHost.currentAction = 'watch';
-        return cli.watch({
+        await cli.watch({
           selector,
           exclusively: args.exclusively,
           toolkitStackName,
@@ -441,6 +441,7 @@ export async function exec(args: string[], synthesizer?: Synthesizer): Promise<n
           traceLogs: args.logs,
           concurrency: args.concurrency,
         });
+        return;
 
       case 'destroy':
         ioHost.currentAction = 'destroy';