What the agent does
In a repository like aws-samples/aws-cdk-examples, each TypeScript example is its own app with its own package.json, and the agent reads them one at a time. typescript/ec2-instance/package.json pins aws-cdk-lib to exactly 2.262.1 and the aws-cdk CLI to exactly 2.1133.0, with constructs ^10.0.0 and jest ^30. There is no package-lock.json or yarn.lock in these examples, so scripts/build-typescript.sh falls through to yarn install, yarn build, npm run --if-present test and then scripts/synth.sh. The exact pins are the only thing holding a build steady, which is why the bump has to be deliberate.
The agent picks five examples that have snapshot tests, because those are where a library bump shows up: ec2-instance, ec2-instance-connect-endpoint, aws-transfer-sftp-server, api-gateway-lambda-token-authorizer and ec2-ssm-local-zone each keep a snapshots file. Their tests build the stack, pass the template through typescript/test-utils/normalize-template.ts (which replaces 64-character S3Key asset hashes and sha256 image digests with fixed strings) and call toMatchSnapshot. It skips any directory with a DO_NOT_AUTOTEST file, as the build script does.
In each example it moves aws-cdk-lib and aws-cdk to the newest releases, still as exact versions, runs npm run build (tsc), npm test and cdk synth, whose app entry in cdk.json is npx tsc && npx tsx bin/app.ts. When a snapshot fails, it does not run jest -u and move on. It diffs the old and new templates and matches each changed resource property against the aws-cdk-lib release notes between the two versions: a new default, a feature flag, a changed construct. A change the notes explain is accepted and the snapshot updated; a change they do not explain is the bump being left out for that example, with the diff.
Feature flags get their own check. Each example's cdk.json carries a context block of @aws-cdk flags, and new library versions add flags that default to the old behaviour for existing apps. The agent reports new flags it saw without turning them on, since enabling one is a behaviour change to decide on separately.
Start it with one API call
POST https://api.prix.dev/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade aws-cdk-lib and the aws-cdk CLI to the latest releases, still pinned to exact versions, in five TypeScript examples that have snapshot tests. In each: run npm run build, npm test and cdk synth. Where a snapshot changes, diff the old and new CloudFormation templates and match every changed property to the aws-cdk-lib release notes between the two versions; update the snapshot only when the notes explain the change. Do not enable new feature flags; list them. Leave out any upgrade that breaks the build or tests, or changes a template in a way the notes do not explain, and say why. Open a pull request with one line per example and bump.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.prix.dev/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes package.json in each example it upgraded and, where templates moved, the matching .snap file. The description has one line per example with the old and new aws-cdk-lib and CLI versions, then a section per changed snapshot that lists each changed resource and property beside the release note that explains it. Examples left out have the failing command or the unexplained diff instead.
A reviewer reads the template changes, not the version strings: a changed IAM policy, a new default on a Lambda function or a replaced resource is what reaches an AWS account on the next deploy. The transcript has the cdk synth output for each example, so a reviewer can check that synth ran on the new version rather than trusting a green test that only compared normalized JSON.
Run it on every aws-cdk-lib release
aws-cdk-lib ships often, and each release is small. Start one run per release, or one per week from your own cron, with POST /o/{org}/sessions and the same body. Set a webhook URL on the key and your service gets run.completed with the session's URL when the pull request is open.
Upgrading in small steps keeps each snapshot diff short enough to match against one or two sets of release notes.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
Five examples means five installs, five builds, five test runs and five synths, plus reading release notes against template diffs. Run in Rush, that happens in the run's own sandbox with Node and the CDK CLI, needs no AWS credentials because nothing is deployed, and leaves every command and its output in the transcript for the reviewer.
The value is the explanation. A bot can bump a version; a reviewer still has to work out why a snapshot changed. Here the pull request arrives with each change tied to a release note, and the ones that cannot be tied are left out with their diff.
Frequently asked questions
Does it need my AWS account?
No. npm test and cdk synth build CloudFormation templates locally and deploy nothing. Examples whose synth looks up context from an account, such as a VPC lookup, are reported as not synthesized rather than given credentials.
Will it just run jest -u when snapshots fail?
No. The request tells it to update a snapshot only when every changed property is explained by the release notes between the two versions. Anything else is left out with the diff.
What about the CDK CLI version?
The CLI (aws-cdk 2.1133.0 in these examples) releases separately from the library and is bumped in the same pull request, still as an exact version. cdk synth runs on the new CLI, so a CLI that cannot read the new library's output fails there.
Will it enable new feature flags in cdk.json?
No. It lists flags the new version introduced and leaves the context block as it was. Turning one on changes resources for an existing app and belongs in its own pull request.