feat(project): tear down the stack on a deploy of an empty project, behind --yes

[notgitika]

Summary

Deploying a project that declares no resources tore down its stack silently. This makes that outcome explicit, gated, and reported — and fixes the stack-selection gap found in the same review.

A deploy of nothing was a silent delete. The CDK Toolkit reads a template with no resources as an instruction to delete an existing stack of that name, and reports the run as an ordinary successful deploy. #2058 caught it after the fact, by which point the stack was gone.

The first attempt at a guard here was dead code. CDK writes an AWS::CDK::Metadata resource into every stack unless version reporting is disabled, so a project whose spec declares nothing still synthesizes a template with one resource in it — Object.keys(Resources).length === 0 is unreachable through the CLI. Verified against eight real synthesized assemblies. Counting only the resources the project asked for makes the check fire.

Making it fire needs somewhere for that deploy to go. main supports this: empty the project, deploy, and the stack is destroyed. The refactor dropped it, so refusing outright would trade a silent delete for a regression. Instead the deploy routes to an explicit toolkit.destroy(), gated on --yes:

$ agentcore project deploy
Project 'orders' declares no resources to deploy, so deploying to target 'default'
would delete stack 'AgentCore-orders-default' and every resource in it.
Re-run with --yes to confirm, or restore the resources the project should have.

$ agentcore project deploy --yes
Removing stack AgentCore-orders-default
Removed project 'orders' from target 'default'

Three states are distinguished, all before anything is destroyed:

Project declares	Stack exists	--yes	Outcome
resources	—	—	deploy
nothing	yes	no	refuse, naming the stack that would be deleted
nothing	yes	yes	destroy, reported as Removed
nothing	no	—	refuse: add a resource, e.g. project add runtime

Destroying explicitly rather than deploying the empty template is what makes the outcome reportable: destroy fails loudly when the stack cannot be removed, where a deploy of an empty template succeeds either way. The empty-outputs guard in performCdkOperation stays as the backstop for reaching that state some other way.

Detection reads the synthesized template rather than counting spec collections the way main does, so a resource type added to the spec later is covered without anyone remembering to extend a list.

Stack selection also matched on the target-name tag alone, never on the account and region the artifact was synthesized for. Those derive from the same target today and so cannot disagree, but nothing enforced it, and the Toolkit deploys where the artifact's environment points rather than where the tag says. Both fields were being stripped on read, since the manifest schema declared neither.

stackArtifactIdForTarget becomes stackArtifactForTarget, returning the template path and the deployed stack name alongside the id. The stack name is derived as properties.stackName ?? artifactId, which is CDK's own derivation — so the name handed to CloudFormation is the one the Toolkit would have used.

Testing

bun test src/ — 1985 pass, 0 fail against these files. Unit coverage for each state in the table, for the metadata-only template that made the original guard dead, and for the ordering that makes the guards meaningful: every check runs before the Toolkit is called, so a bad target or an unconfirmed teardown fails without touching AWS. probeStack is covered for a present stack, a stack mid-rollback, an absent stack, an empty response, and a permissions failure — the last matters because reporting "no stack" on an AccessDeniedException would turn a confirmed teardown into an unexplained "add a resource" error.

Notes

main deletes orphaned harnesses and config bundles before destroying the stack, because it creates some of them imperatively. This branch creates everything through CloudFormation, so the stack deletion covers them; nothing is intentionally left behind, but flagging it in case a later imperative resource needs the same treatment.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 94.90446% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.34%. Comparing base (e51a676) to head (1763df3).
⚠️ Report is 3 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/core/project/backends/cdk/environment.ts	63.63%	8 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2089      +/-   ##
============================================
- Coverage     97.36%   97.34%   -0.02%     
============================================
  Files           424      424              
  Lines         25571    25706     +135     
============================================
+ Hits          24897    25024     +127     
- Misses          674      682       +8     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[nborges-aws]

For my own understanding: wouldn't CDK write unknown-account and unknown-region if env-agnostic? The comment on L9 says thats the case, but this comment says no env = env-agnostic.

[Hweinstock]

Rejects a synthesized stack that declares no resources.

I kind of think we want the opposite. If I clear all of my resources, then deploy, I'd expect that to delete the stack. Without this functionality, how do I destroy the AWS resources I've created with the CLI?

I could see an alternative where we offer an explicit destroy, but that feels overly complex.

[notgitika]

Rejects a synthesized stack that declares no resources.

I kind of think we want the opposite. If I clear all of my resources, then deploy, I'd expect that to delete the stack. Without this functionality, how do I destroy the AWS resources I've created with the CLI?

I could see an alternative where we offer an explicit destroy, but that feels overly complex.

Discussed with folks offline we are going with a confirmation + flag once the condition is user runs deploy when spec is empty. this will just inform the user that we are also going to delete their stack. (-y)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[Hweinstock]

one question about the flag naming, and some internal questions about toolkit lib behavior for my own understanding.

[Hweinstock]

to me --yes implies, answer yes to the prompt, but here there is no prompt and its instead signaling a bypassing of safety measures (kind of like git push --force).

What do you think of naming this to force?

[Hweinstock]

where does the need for an explicit teardown come in? I thought the behavior of toolkit lib was that it already deleted the stack if it was empty.

[Hweinstock]

the stack's environment derive from the same target in the synthesized app, so today they cannot disagree.

What could change that would make them disagree? I'm wondering if we can avoid this complexity, or if there is real concern we could deploy to the wrong environment.

[nborges-aws]

LGTM. Teardown looks sound; I'm indifferent on --force vs --yes naming convention Harrison raised.