fix(cli): The bootstrap stack is environment-wide and build-type-ag... (#1377)

[aidandaly24]

Refs aws#1377

Issues

• ECR repository creation required even with CodeZip build type aws/agentcore-cli#1377 — A user deploying a CodeZip-only agent with agentcore deploy in an AWS account whose SCP/IAM denies ecr:CreateRepository is hard-blocked: the deploy auto-bootstraps the shared CDKToolkit stack, which unconditionally tries to create an ECR repository, so bootstrap (and therefore the whole deploy) fails with "ECR Permission Denied - ecr:CreateRepository" even though CodeZip never uses ECR. Only workaround is deploying in a less-restricted account.

Root cause

Verified: CLI bootstrap (wrapper.ts:317) passes no BootstrapSource, so toolkit-lib deploys the modern bootstrap template whose ContainerAssetsRepository (ECR) at bootstrap-template.yaml:256 is unconditional; CodeZip needs no ECR (AgentCoreRuntime/AgentEnvironment gate ECR on build==='Container' only, confirmed at pinned alpha.19). The ECR demand is purely a shared-bootstrap-stack artifact, blocked by SCPs denying ecr:CreateRepository.

The fix

The bootstrap stack is environment-wide and build-type-agnostic by design, so the clean fix is to let the CLI bootstrap with a customized template that omits (or makes conditional) ContainerAssetsRepository when ECR is unavailable/unneeded. toolkit-lib already supports this: BootstrapOptions.source accepts { source: 'custom', templateFile } (verified in node_modules/@aws-cdk/toolkit-lib/lib/api/bootstrap/bootstrap-props.d.ts and bootstrap-environment.d.ts; there is NO --no-container-assets option in toolkit-lib, so a custom template is the only lever). Concretely: (1) vend a slimmed bootstrap template (clone of the modern template minus ContainerAssetsRepository and its ECR IAM grants) and pass it via the bootstrap source through CdkToolkitWrapper.bootstrap (wrapper.ts:317); gate its use on a flag like --no-container-assets or auto-detect (no Container agents in the project). Design decision required: an ECR-less bootstrap breaks any later Container build in that same environment, so it must be opt-in or clearly re-bootstrap-on-demand. Cheaper interim fix: detect the ecr:CreateRepository AccessDenied during bootstrap and emit an actionable error explaining ECR is needed only by the shared CDK bootstrap stack (not by CodeZip itself), with the slim-template/flag workaround. The unconditional ECR resource itself lives upstream in the aws-cdk modern bootstrap template, which the CLI can only override via a custom template, not patch. Dependency-range note: src/assets/cdk/package.json pins ^0.1.0-alpha.19, which floats to later 0.1.0-alpha tags at install, but ECR-on-Container-only behavior is unchanged through alpha.39 — no version bump fixes this.

Files touched: agentcore-cli: src/cli/cdk/toolkit-lib/wrapper.ts (bootstrap() ~L317-324, add a custom BootstrapSource via options.source), src/cli/operations/deploy/preflight.ts (bootstrapEnvironment L329-335), src/cli/commands/deploy/actions.ts (auto-bootstrap branch L407-421); plus a vended ECR-less bootstrap template asset. The unconditional ECR resource lives upstream in the aws-cdk modern bootstrap template (node_modules/@aws-cdk/toolkit-lib/lib/api/bootstrap/bootstrap-template.yaml:256, ContainerAssetsRepository), overridable only via a custom template.

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

BEFORE (symptom reproduced): Temporarily reverted the wrapper try/catch remap. Feeding a simulated rejection Error: ECR Permission Denied - User is not authorized to perform: ecr:CreateRepository (AccessDenied) through CdkToolkitWrapper.bootstrap() surfaced the raw, non-actionable message CDK bootstrap failed: ECR Permission Denied - ...ecr:CreateRepository (AccessDenied) as a plain Error (not a dedicated type, no guidance). The new test failed: "expected Error: CDK bootstrap failed: ECR Permissi… to be an instance of BootstrapEcrAccessDeniedError". AFTER (fix restored): the same rejection is caught by isEcrCreateRepositoryAccessDeniedError() (src/cli/errors.ts) and remapped to a new BootstrapEcrAccessDeniedError (src/lib/errors/types.ts, errorSource 'user', registered in ErrorName enum in src/cli/telemetry/schemas/common-shapes.ts). The thrown error's message contains "needed only by the shared CDK bootstrap stack" plus the "not by CodeZip agents" clarification and the concrete workaround (deploy in an ecr:CreateRepository-permitting account, or pre-bootstrap with a custom ECR-less template); it no longer contains the raw "CDK bootstrap failed:" prefix, and the original error is preserved as cause. Both new tests pass (incl. the pass-through case for unrelated failures). Build succeeded first try; artifact at /local/home/aidandal/workplace/issues/bugfix-run/clusters/1377/repo/dist/cli/index.mjs.

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.22%	13619 / 36584
🔵	Statements	36.49%	14478 / 39674
🔵	Functions	31.88%	2340 / 7338
🔵	Branches	31.14%	9012 / 28938

Generated in workflow #94 for commit db99a6e by the Vitest Coverage Report Action