fix(cli): release terraform state lock when interrupting diff/deploy (#284)

### Related issue

Fixes #283

### Description

Interrupting `cdktn diff` or `cdktn deploy` (Ctrl-C) left terraform's
state lock held, so the next run failed with `Error acquiring the state
lock`.

The cause was that the CLI's abort handler tore terraform down instead
of letting it exit on its own. Terraform shares the CLI's process group,
so Ctrl-C already reaches it directly and starts its graceful shutdown
(which releases the lock) — but the CLI killed it before that shutdown
could finish. The fix is to stop tearing terraform down on abort and
instead wait for it to exit:

- **diff/plan**
([`@cdktn/commons/src/util.ts`](packages/@cdktn/commons/src/util.ts)):
`exec()` no longer forwards the abort to `child_process.spawn`'s
`signal` option, which killed the child with SIGTERM and rejected the
promise immediately (synthetic `AbortError`) before terraform had exited
— so terraform never ran its graceful shutdown and the lock leaked. It
now settles on the child's own `close`, so the run resolves only once
terraform has exited and released the lock.

- **deploy/destroy**
([`@cdktn/cli-core/src/lib/models/deploy-machine.ts`](packages/@cdktn/cli-core/src/lib/models/deploy-machine.ts)):
the xstate machine previously went straight to the final `stopped` state
on `STOP`, killing the pty and resolving the run before terraform had
finished shutting down. It now passes through an intermediate `stopping`
state that marks the run cancelled and waits for terraform's natural
`EXITED` before reaching `stopped`. The pty stays alive throughout, so
terraform exits on its own and the run only resolves afterwards.

**Why no extra signal is needed:** every abort trigger in the codebase
(`runCdktfProject`, `watch`) originates from
`process.on(SIGINT/SIGTERM/SIGQUIT)`, so terraform — sharing the process
group — always receives the signal directly. There is no abort path that
requires the CLI to deliver the signal itself.

**Verification:** confirmed after the fix that a single Ctrl-C produces
only `Interrupt received... Gracefully shutting down...` and terraform
exits cleanly on its own. The full lock-release path (interrupt a
locking operation, then re-run) still needs a final check against a
backend that locks state.

### Checklist

- [x] I have updated the PR title to match [CDKTN's style
guide](https://github.com/open-constructs/cdk-terrain/blob/main/CONTRIBUTING.md#pull-requests-1)
- [x] I have run the linter on my code locally
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the
[documentation](https://github.com/open-constructs/cdk-terrain-docs/tree/main/content)
if applicable
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works if applicable
- [x] New and existing unit tests pass locally with my changes

Co-authored-by: Simon Heather <simon.heather@yulife.com>

Author: X-Guardian

packages/@cdktn/cli-core/src/lib/models/deploy-machine.ts

@@ -75,6 +75,10 @@ export type DeployState =
       value: { running: "awaiting_sentinel_override" };
       context: DeployContext;
     }
+  | {
+      value: { running: "stopping" };
+      context: DeployContext;
+    }
   | {
       value: "exited";
       context: DeployContext & { exitCode: number };
@@ -230,7 +234,7 @@ export const deployMachine = createMachine<
         },
         on: {
           EXITED: "exited",
-          STOP: "stopped",
+          STOP: ".stopping", // wait for terraform to exit, don't stop immediately (see the "stopping" state)
         },
         initial: "processing",
         states: {
@@ -309,6 +313,15 @@ export const deployMachine = createMachine<
               },
             },
           },
+          // On STOP, wait for terraform's own EXITED before reaching the final "stopped" state, so the run only
+          // resolves once it has exited and released its lock. Don't re-signal it — it already got the interrupt via
+          // the process group, and a second signal aborts its graceful shutdown.
+          stopping: {
+            entry: assign<DeployContext, DeployEvent>({ cancelled: true }),
+            on: {
+              EXITED: "#root.stopped",
+            },
+          },
         },
       },
       exited: { type: "final" },

packages/@cdktn/cli-core/src/test/models/deploy-machine.test.ts

@@ -227,6 +227,52 @@ describe("pty events", () => {
     });
   });
 
+  it("waits for terraform to exit on STOP rather than stopping immediately", (done) => {
+    // The pty stays alive until we resolve its exit, letting us assert the machine waits for terraform's own exit
+    // before reaching "stopped".
+    const stop = jest.fn();
+    let resolveExit: (code: number) => void = () => {};
+    const controllablePty: typeof spawnInteractive = () => ({
+      actions: { write: jest.fn(), writeLine: jest.fn(), stop },
+      exitCode: new Promise<number>((resolve) => {
+        resolveExit = resolve;
+      }),
+    });
+
+    const mockDeployMachine = deployMachine.withConfig({
+      services: {
+        runTerraformInPty: (context, event) =>
+          terraformPtyService(context, event, controllablePty),
+      },
+    });
+
+    let interrupted = false;
+    const ptyService = interpret(mockDeployMachine).onTransition((state) => {
+      if (state.matches({ running: "stopping" }) && !interrupted) {
+        interrupted = true;
+        // We are waiting for terraform to exit, not yet at the final "stopped" state, and we have not re-signalled it.
+        expect(state.matches("stopped")).toBe(false);
+        expect(stop).not.toHaveBeenCalled();
+        setTimeout(() => resolveExit(0), 50); // terraform finishes exiting, releasing its lock
+      }
+
+      if (state.matches("stopped")) {
+        expect(state.context.cancelled).toBe(true);
+        done();
+      }
+    });
+
+    ptyService.start();
+
+    ptyService.send({
+      type: "START",
+      pty: { file: "", args: [], options: { cwd: "" } },
+    });
+
+    // Give the pty service a tick to start before requesting a stop.
+    setTimeout(() => ptyService.send({ type: "STOP" }), 50);
+  });
+
   it("transitions to rejected state when done externally", (done) => {
     const mockDeployMachine = deployMachine.withConfig({
       services: {

packages/@cdktn/commons/src/util.ts

@@ -136,8 +136,12 @@ export const exec = async (
     options.noColor = true;
   }
 
+  // Drop spawn's `signal` option: the child already gets the interrupt via the process group, and a second signal
+  // aborts terraform's graceful shutdown. Just wait for its own "close".
+  const { signal: _signal, ...spawnOptions } = options;
+
   return new Promise((ok, ko) => {
-    const child = spawn(command, args, options);
+    const child = spawn(command, args, spawnOptions);
     const out = new Array<string>();
     const err = new Array<string>();
     if (stdout !== undefined) {