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/). Internals: semver.ts (prerelease-aware parse/compare — the existing parseSemVer drops -alpha.N tags, which here would make an alpha downgrade look like a no-op), policy.ts (pure plan computation), messages.ts (single source of user-facing wording), and the rewrite/clean-reinstall logic. All notices/warnings are returned as data on the result; callers only display them, so the headless and TUI paths can't drift.
Errors — CliVersionTooOldError (errorSource: 'user') and DependencySyncError ('client') in src/lib/errors/types.ts, registered in the telemetry ErrorName enum. All failure paths throw typed errors — never process.exit() — so telemetry classification keeps working.
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. @aws/agentcore-cdk exact-pinned to 0.1.0-alpha.45.
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). The summary rides on DeployResult (so --json gets structured data; the human notice goes through onNotice, suppressed under --json), renders in the TUI DeployScreen, and feeds five new dep_sync_* deploy telemetry attributes.
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:

sync.test.ts — end-to-end through the public function against a real temp project dir (only the npm subprocess mocked), one test per design-doc behavior: no-op deploy touches nothing and prints nothing; caret project migrates + installs incrementally (npm install invoked, node_modules/lockfile never deleted, migration notice includes the opt-out hint) while a user-added lodash survives untouched; missing node_modules self-heals with an install even when the manifest matches; higher-minor project throws CliVersionTooOldError with the upgrade wording; opted-out skew warns and leaves the file byte-identical; deleted managed dep is restored; file:bundled-agentcore-cdk.tgz override is skipped with a warning; npm failure wraps in DependencySyncError and restores the original manifest so a retry recomputes and reinstalls; unreadable package.json wraps in DependencySyncError; rewrite preserves user key order and unknown fields.
policy.test.ts — plan computation: skew on higher minor and major but not higher patch; prerelease-aware skew on the exact pin (alpha.50 > alpha.45 detected, older alpha upgraded); devDependencies managed and the user's section respected; user deps never touched.
semver.test.ts — prerelease ordering (0.1.0-alpha.19 < 0.1.0-alpha.20 < 0.1.0), specifier classification (exact/tilde/caret), and unsupported forms (file:, git+https:, workspace:, *, latest, compound ranges).
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