fix(cli): use caret version for aws-cdk-lib in init templates (#1002)

Fixes #946 - more or less.

The `cdk init` command generates `package.json` files with a pinned
`aws-cdk-lib` version (e.g., `"2.232.2"`), which prevents users from
updating the library using `npm update`. This change adds a caret prefix
(`^`) to the version, allowing semver-compatible updates while still
ensuring compatibility.

Additionally, this PR separates the `aws-cdk-lib` upgrade from the
regular dependency upgrade workflow. This allows us to track
`aws-cdk-lib` updates independently and ensures the init templates
always reference a recent version. There's no guarantee that these
updates are merged more often (they still need to pass integ tests), but
being decoupled from other updates they are much less likely to fail.

## Why this is safe

The main question is if we are still testing what we are releasing.
Specifically adding the `^` caret has to consequences:
- pre release versions are only matched exactly (the `^`) is ignored, we
use pre-release versions in our integ tests
- when a new version of `aws-cdk-lib` is released, can we ensure we have
tested this combination of Toolkit and Construct Lib

### Tests in this repo

We are already running all our `cdk init` tests against the latest
version of `aws-cdk-lib`.
This is done by finding the latest version:

https://github.com/aws/aws-cdk-cli/blob/af211ad102643f752caad307b6ec1e74ba93680e/.github/workflows/integ.yml#L107

which then ends up being explicitly requested as part of `cdk init`:


https://github.com/aws/aws-cdk-cli/blob/af211ad102643f752caad307b6ec1e74ba93680e/packages/@aws-cdk-testing/cli-integ/tests/init-fsharp/init-fsharp.integtest.ts#L10

There is therefore no change in testing coverage.

We do however default `cdk init` to a fixed, "known good" version. This
version is not actively tested, but can be assumed "good" because it
would have been the latest version at the time of the upgrade PR (and
therefore tested). **This assumption is actually incorrect.** Upgrade
PRs are created/updated weekly, but need to be manually approved to run
integ tests. In the time the PR was created and tests run, a new version
could have been released. Thus we could be merging a `aws-cdk-lib`
version (and consequently a `cdk init` default) that is not actually
tested. It is however reasonable to declare that if a later versions
works, previous versions will work as well.

This leaves us with `aws-cdk-lib` releasing new versions.

### Tests in `aws/aws-cdk`

As part of our release pipeline we are explicitly testing the release
candidate with the full proposed version, e.g. `2.123.0`. This version
is staged in a private articat repository instead of npmjs.com.
Otherwise the `cdk init` tests behave exactly the same as in this repo
(duh, it's the same code): The version is explicitly requested as part
of the `init` command. **This means that no version of `aws-cdk-lib` is
released without passing init template tests.** In turn this means that
it's safe to include the `^` because any future version will only be
released if it passes.

### Continuous checks ("canaries")

Similar to the other tests, our continuous canary checks will explicitly
install the latest available version. So in addition to the previous
assertions, we also have ongoing checks that the latest version of
`aws-cdk-lib` works.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license

---------

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: mrgrain

.gitattributes

@@ -1175,6 +1175,7 @@ const cli = configureProject(
       'yaml@^1',
       'yargs@^15',
     ],
+    excludeDepsFromUpgrade: ['aws-cdk-lib'], // this is handled separately further down
     tsconfig: {
       compilerOptions: {
         ...defaultTsOptions,
@@ -1234,6 +1235,20 @@ const cli = configureProject(
   }),
 );
 
+// @ts-ignore
+cli.github = repo.github;
+new pj.javascript.UpgradeDependencies(cli, {
+  include: ['aws-cdk-lib'],
+  semanticCommit: 'feat',
+  pullRequestTitle: 'upgrade aws-cdk-lib',
+  target: 'minor',
+  taskName: 'upgrade-aws-cdk-lib',
+  workflow: true,
+  workflowOptions: {
+    schedule: pj.javascript.UpgradeDependenciesSchedule.WEEKDAY,
+  },
+});
+
 new TypecheckTests(cli);
 
 // Eslint rules

.github/workflows/upgrade-aws-cdk-lib.yml

@@ -36,3 +36,10 @@ export function rangeFromSemver(ver: string, targetType: RangeType) {
       }
   }
 }
+
+/**
+ * Strips a leading caret ^, if present
+ */
+export function stripCaret(ver: string): string {
+  return ver.startsWith('^') ? ver.slice(1) : ver;
+}

.gitignore

@@ -18,8 +18,9 @@ HERE
 # Copy the current 'aws-cdk-lib' version out from the monorepo.
 cdk_version=$(node -p 'require("aws-cdk-lib/package.json").version')
 constructs_range=$(node -p 'require("aws-cdk-lib/package.json").peerDependencies.constructs')
-echo '{"aws-cdk-lib": "'"$cdk_version"'", "constructs": "'"$constructs_range"'"}' > lib/init-templates/.init-version.json
+# Use caret range for aws-cdk-lib to allow minor and patch updates being installed on cdk init
+echo '{"aws-cdk-lib": "^'"$cdk_version"'", "constructs": "'"$constructs_range"'"}' > lib/init-templates/.init-version.json
 
 # Copy the recommended-feature-flags.json file out from aws-cdk-lib.
 path=$(node -p 'require.resolve("aws-cdk-lib/recommended-feature-flags.json")')
-cp $path lib/init-templates/.recommended-feature-flags.json
+cp $path lib/init-templates/.recommended-feature-flags.json

.projen/files.json

@@ -7,7 +7,7 @@ import { invokeBuiltinHooks } from './init-hooks';
 import type { IoHelper } from '../../api-private';
 import { cliRootDir } from '../../cli/root-dir';
 import { versionNumber } from '../../cli/version';
-import { cdkHomeDir, formatErrorMessage, rangeFromSemver } from '../../util';
+import { cdkHomeDir, formatErrorMessage, rangeFromSemver, stripCaret } from '../../util';
 import type { LanguageInfo } from '../language';
 import { getLanguageAlias, getLanguageExtensions, SUPPORTED_LANGUAGES } from '../language';
 import { getPmCmdPrefix, type JsPackageManager } from './package-manager';
@@ -568,19 +568,25 @@ export class InitTemplate {
 }
 
 export function expandPlaceholders(template: string, language: string, project: ProjectInfo, packageManager?: JsPackageManager) {
-  const cdkVersion = project.versions['aws-cdk-lib'];
   const cdkCliVersion = project.versions['aws-cdk'];
+  let cdkVersion = project.versions['aws-cdk-lib'];
   let constructsVersion = project.versions.constructs;
 
   switch (language) {
     case 'java':
     case 'csharp':
     case 'fsharp':
+      cdkVersion = rangeFromSemver(cdkVersion, 'bracket');
       constructsVersion = rangeFromSemver(constructsVersion, 'bracket');
       break;
     case 'python':
+      cdkVersion = rangeFromSemver(cdkVersion, 'pep');
       constructsVersion = rangeFromSemver(constructsVersion, 'pep');
       break;
+    case 'go':
+      cdkVersion = stripCaret(cdkVersion);
+      constructsVersion = stripCaret(constructsVersion);
+      break;
   }
   return template
     .replace(/%name%/g, project.name)

.projenrc.ts

@@ -1 +1 @@
-{"aws-cdk-lib": "2.232.2", "constructs": "^10.0.0"}
+{"aws-cdk-lib": "^2.232.2", "constructs": "^10.0.0"}