feat(project): add CDK Toolkit adapter by notgitika · Pull Request #2057 · aws/agentcore-cli

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

notgitika · 2026-08-20T03:11:54Z

Summary

add a backend-local adapter for @aws-cdk/toolkit-lib
load the Toolkit lazily and route notifications through the existing logger at debug level
keep the Toolkit external in the npm bundle
add direct adapter tests without activating deployment

Stack

This is PR 3 of 4 decomposing #2001. The adapter is backend-local rather than part of shared io. Review and merge bottom-up.

refactor(project): move build behind a project backend #2055 - backend build boundary
feat(project): add deploy command contract #2056 - deploy command contract
feat(project): add CDK Toolkit adapter #2057 - CDK Toolkit adapter (this PR)
feat(project): implement safe CDK deployment #2058 - safe deployment implementation

typecheck, lint, format, test all pass

codecov-commenter · 2026-08-21T16:04:29Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (fee25e2) to head (9750c4e).

Additional details and impacted files

@@ Coverage Diff @@## refactor #2057 +/- ##
=========================================
Coverage 97.25% 97.26% =========================================
Files 397 398 +1 Lines 24125 24192 +67 =========================================
+ Hits 23463 23530 +67 
Misses 662 662

☔ 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.

PATTERN_MUST_MATCH_SINGLE throws unless the pattern matches exactly one stack, so an absent result was never "no match". The Toolkit skips a stack whose synthesized template has no resources, and deletes it if a stack of that name already exists — both return normally with no stacks. `?? {}` turned that into a successful deploy with no outputs, so a caller expecting RuntimeArn got undefined with nothing explaining why. Assert exactly one stack and name both possibilities in the error, keeping `?? {}` only for a stack that deployed but declares no outputs. Both paths are now covered; the fake toolkit takes the stack list so the resource-less case is reachable from a test. Also narrows the `external` comment in scripts/build.ts: it describes the npm bundle only. compile() cannot mark the Toolkit external because a standalone binary ships no node_modules, so Bun inlines it and rewrites __dirname to the build machine's path — which resolves on the builder and fails everywhere else.

Hweinstock · 2026-08-24T16:52:19Z

+}
+
+/** Loads the Toolkit only when a deploy operation needs it. */
+export const loadCdkToolkit: CdkToolkitLoader = async (ioHost, region) => {


I like how this is loaded lazily.

yeah I had my agent test the latency with the static import and it was quite a bit higher. thanks!

github-actionsBot added the size/xl PR size: XL label Aug 20, 2026

notgitika had a problem deploying to e2e-testing August 20, 2026 03:12 — with GitHub Actions Failure

This was referenced Aug 20, 2026
refactor(project): move build behind a project backend #2055
Merged
feat(project): add deploy command contract #2056
Merged
feat(project): implement safe CDK deployment #2058
Merged

github-actionsBot added agentcore-harness-reviewing AgentCore Harness review in progress size/xl PR size: XL and removed size/xl PR size: XL agentcore-harness-reviewing AgentCore Harness review in progress labels Aug 20, 2026

notgitika marked this pull request as ready for review August 20, 2026 04:12

notgitika mentioned this pull request Aug 20, 2026
feat: implement project deploy command #2001
Closed

notgitika force-pushed the feat/project-cdk-toolkit branch from a3da8e2 to 000e3b8Compare August 20, 2026 04:19

github-actionsBot added size/xl PR size: XL and removed size/xl PR size: XL labels Aug 20, 2026

notgitika marked this pull request as draft August 20, 2026 04:19

notgitika had a problem deploying to e2e-testing August 20, 2026 04:19 — with GitHub Actions Failure

notgitika marked this pull request as ready for review August 20, 2026 04:24

github-actionsBot added size/xl PR size: XL and removed size/xl PR size: XL labels Aug 20, 2026

notgitika force-pushed the feat/project-cdk-toolkit branch from 000e3b8 to ef1f731Compare August 20, 2026 17:06

github-actionsBot added size/xl PR size: XL and removed size/xl PR size: XL labels Aug 20, 2026

notgitika had a problem deploying to e2e-testing August 20, 2026 17:07 — with GitHub Actions Failure

tejaskash reviewed Aug 21, 2026
View reviewed changes

Comment threadsrc/core/project/backends/cdk/toolkit.ts

notgitika force-pushed the feat/project-cdk-toolkit branch from ef1f731 to c4723b3Compare August 21, 2026 16:01

notgitika force-pushed the feat/project-cdk-toolkit branch from c4723b3 to 6c52205Compare August 21, 2026 16:16

notgitika force-pushed the feat/project-cdk-toolkit branch from 6c52205 to 8b9d408Compare August 21, 2026 17:41

tejaskash reviewed Aug 21, 2026
View reviewed changes

Comment threadscripts/build.ts

tejaskash reviewed Aug 21, 2026
View reviewed changes

Comment threadsrc/core/project/backends/cdk/toolkit.ts

notgitika force-pushed the feat/project-cdk-toolkit branch from 8b9d408 to 33e58a0Compare August 21, 2026 18:12

notgitika force-pushed the feat/project-cdk-toolkit branch from 33e58a0 to d5e69ffCompare August 21, 2026 18:21

notgitika force-pushed the feat/project-cdk-toolkit branch from d5e69ff to 5cc76e5Compare August 24, 2026 14:59

Base automatically changed from feat/project-deploy-contract to refactorAugust 24, 2026 16:01

notgitika added 2 commits August 24, 2026 12:01

feat(project): add CDK Toolkit adapter
c105e47

notgitika force-pushed the feat/project-cdk-toolkit branch from 5cc76e5 to 9750c4eCompare August 24, 2026 16:01

tejaskash approved these changes Aug 24, 2026
View reviewed changes

Hweinstock approved these changes Aug 24, 2026
View reviewed changes

tejaskash merged commit 1a297be into refactorAug 24, 2026
11 checks passed

tejaskash deleted the feat/project-cdk-toolkit branch August 24, 2026 17:18