feat: manage vended CDK project dependencies with minor-version pinning by jesseturner21 · Pull Request #1777 · aws/agentcore-cli

jesseturner21 · 2026-07-16T19:46:13Z

Description

Problem

The CLI vends projects with caret (^) dependency ranges in agentcore/cdk/package.json, so any upstream minor release (@aws/agentcore-cdk, aws-cdk-lib, …) can land in a customer's project without any CLI change — breaking template code or the CLI's ability to interact with the project. The CLI needs to own these versions on the customer's behalf while staying out of the way of dependencies the customer added themselves.

Solution

Pin to minor, let patches float. Managed dependencies are written as tilde ranges (~x.y.z); @aws/agentcore-cdk (L3 constructs, prerelease-versioned) is pinned exactly. A dependency is "managed" iff its name appears in the CLI's vended asset src/assets/cdk/package.json — that asset, baked into each CLI release, is the single source of truth for both the managed list and the known-good versions. Everything else in the customer's file is never touched.

On every agentcore deploy (headless and TUI), a preflight step:

Skew check — if the project declares a managed dep with a higher minor/major than this CLI expects (e.g. a teammate on a newer CLI updated it), throw: "This project requires a newer version of the AgentCore CLI. Run npm install -g @aws/agentcore@latest and retry." Higher patch is fine — that's the point of tilde.
Migrate — projects created before pinning (caret ranges) are rewritten to the pinned form with a one-time explanation.
Sync — managed deps are updated to the current CLI's values; user-added deps are left byte-for-byte untouched; non-semver specifiers (file: bundled-tarball overrides, git:, …) are skipped with a warning, never rewritten.
Install (only if something changed) — run an incremental npm install in agentcore/cdk/ that reconciles the edited package.json against the existing lockfile; node_modules and the lockfile are never deleted, so user-added deps keep their resolved versions and installs stay warm. The install also runs as a self-heal when node_modules is missing even with a matching manifest. If the install fails, the pre-rewrite package.json is restored so a retry recomputes the same plan and re-attempts the install. No-op deploys stay fast.
Report — print a summary of every change (old → new per dep, plus "Dependencies you added yourself were not changed.").

Preview modes: --dry-run and --diff run the sync in check-only mode — the notice reports what a real deploy would change (future tense), but nothing is written and no install runs.

Teardown: teardown deploys are never blocked by the sync — both skew and write/install failures downgrade to warnings, so dependency pinning can never prevent destroying a cost-incurring stack.

Opt-out: agentcore config disableDependencyManagement true skips migrate/sync/reinstall entirely; the skew check still runs but downgrades to a warning and deploy proceeds — an escape hatch if we ever ship a bad pin, and support for teams with their own dependency tooling.

High-level implementation

src/lib/dependency-management/ (new, self-contained) — one deep module behind a single function, syncManagedDependencies({vendedPackageJsonPath, projectDir, disabled}), designed to lift into the planned CLI refactor unchanged (zero imports from src/cli/). All notices/warnings are returned as data on the result; callers only display them, so the headless and TUI paths can't drift.
Vended asset pinned — src/assets/cdk/package.json converted to the policy form, with tilde bases bumped to what today's caret ranges actually resolve to (e.g. constructs ^10.0.0 → ~10.7.0, not ~10.0.0) so migration never silently downgrades an existing project.
Deploy integration — ensureManagedDependencies() adapter (src/cli/operations/deploy/dependency-sync.ts) resolves the vended asset via getTemplatePath and reads the global-config opt-out; called as a "Sync CDK dependencies" step between validate and build in handleDeploy (actions.ts) and TUI preflight (useCdkPreflight.ts).
Config — disableDependencyManagement added to GlobalConfigSchemaStrict; the generic agentcore config <key> <value> command handles it with no command changes.

Related Issue

Closes #1540

Documentation PR

N/A — behavior is self-describing via the deploy-time notices; can follow up in agent-docs if wanted.

Type of Change

Testing

40 new unit tests in src/lib/dependency-management/__tests__/ (16 sync + 12 policy + 12 semver), plus new useDevDeploy cases for the dev-flow notice/warnings:

I ran npm run test:unit and npm run test:integ (unit: 411 files / 5956 tests pass; integ not run — no integ coverage touched)
I ran npm run typecheck
I ran npm run lint
If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

github-actions · 2026-07-16T19:48:17Z

Package Tarball

aws-agentcore-0.24.1.tgz