[so0k]

Related issue

Fixes #361
Fixes #360 — the trailing unhandled-rejection dump. The duplicated Terraform error block also reported there
is a separate defect in @cdktn/commons/src/util.ts and is not touched here.

Third in a stack. Targets fix/outputs-file-write-failures, so the diff here is only this change.
Review order: #375 → #376 → this.

Description

cdktn.ts registered an async .fail() handler that yargs does not await — the code's own comment said so —
and called yargs.exit(1, error) as its first statement. So the error printed once from the handler and again
from Node's unhandled-rejection path, followed by Collecting Debug Information... and a
PromiseRejectionHandledWarning.

Measured, not inferred

Both failure classes were reproduced against a build of this branch's base before any change:

Trigger	Before
Unexpected internal error (corrupt cdk.tf.json + --skip-synth)	message + stack printed twice; never reached the Debug Information: label — the awaited collection never completed
Terraform failure (TerraformOutput referencing an undeclared resource)	undefined / undefined, then a hard ERR_UNHANDLED_REJECTION abort

Both are deterministic rather than timing-dependent, which is what made them testable. The second is also a
much cheaper reproduction than the CTRL+C-during-init race described in #361 — no signal timing, no provider,
no credentials.

The undefined / undefined signature had a second cause: terraform-cli.ts threw a raw string, so
error.message and error.stack were both undefined. It now throws an Error. Deliberately a plain Error
rather than Errors.External — a non-zero terraform exit is exactly what debug collection exists for, and the
Errors factories fire an unawaited telemetry POST that a terraform failure has no reason to send.

The fix

The handler moves to bin/error-handling.ts:

• .fail() is now synchronous and only records the failure. It still calls yargs.exit(1, error) for its
  load-bearing hasOutput side effect.
• runCli awaits parseAsync(), reports once through a single awaited path, and makes the one process.exit()
  call. Its try/catch also catches synchronous handler throws, which yargs 17 never routes to .fail() at all.

Crash reporting needed care

This is the part worth reviewing closely. Nothing in the old handler reported to Sentry: the yargs.exit()
on its first line exits the process, so the handler's own tail never ran. What actually reported crashes was the
orphaned rejection from the un-awaited .argv promise, picked up by Sentry's global unhandled-rejection
integration — which is why the Sentry report for the crash fixed in #375 carries mechanism: onunhandledrejection.

Handling the rejection properly removes that channel. So reportFailure now captures explicitly before
flushing: for unexpected errors and for External, but not for Usage, which cli-core's beforeSend already
drops deliberately.

Verified end to end rather than by mock — a test points a real Sentry client at a local sink in a child process
and asserts the envelope arrives before exit. Asserting only that close() was called is precisely what would
let a silently dead reporting path pass review, and an earlier revision of this branch did exactly that.

Exit codes

Unchanged. The baseline for every failure class was measured before the change and re-checked after.

Out of scope, found along the way

• cmds/get.ts calls readConfigSync() at module top level and is unconditionally imported by cdktn.ts,
  so a malformed cdktf.json crashes the CLI at require-time for every command — before .fail() is even
  registered, bypassing all of this. Pre-existing; happy to file it.
• cdktn.ts never calls .strict(), so unknown flags are silently ignored (cdktn synth --nope exits 0).

Checklist

• I have updated the PR title to match CDKTN's style guide
• I have run the linter on my code locally
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation if applicable — n/a, no documented behaviour changes
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works if applicable
• New and existing unit tests pass locally with my changes

[so0k]

Absorbed into #62. The error-handling shape (synchronous .fail() that only records the failure, one awaited reportFailure, a single process.exit) is cherry-picked there with its unit and child-process integration tests, and the reserved telemetry slot is filled by the usage metric that #62 introduces, sharing one flush before exit. Only the three comment hunks that reference #376 are left out. #375 and #376 stay as they are and simply retarget main once #62 lands.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days. This helps our maintainers find and focus on the active issues. If you've found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.