@codedrifters/configulator 0.0.437 → 0.0.439

package/lib/index.d.mts

@@ -14108,11 +14108,15 @@ interface AwsCdkProjectOptions extends Omit<awscdk.AwsCdkTypeScriptAppOptions, "
     /**
      * Minimum version of `aws-cdk-lib` to depend on.
      *
-     * Optional, and normally omitted: the rendered specifier is always
-     * `catalog:`, so the parent `MonorepoProject`'s pnpm catalog decides the
-     * resolved version. Supplying a value that disagrees with that catalog
-     * entry throws rather than being silently discarded — bump the catalog
-     * instead.
+     * Optional, and normally omitted: the rendered specifier is `catalog:`
+     * whenever the parent `MonorepoProject`'s pnpm catalog carries an entry, so
+     * that catalog decides the resolved version. Supplying a value that
+     * disagrees with the entry throws rather than being silently discarded —
+     * bump the catalog instead. Only where the catalog has no entry at all does
+     * this value render, and then it must be an exact version.
+     *
+     * Listing `aws-cdk-lib` in `deps`, `devDeps`, or `peerDeps` is never the way
+     * to move it — the first is overridden by the pin and the other two throw.
      *
      * @default - the parent monorepo's catalog pin for `aws-cdk-lib`
      */
@@ -14126,6 +14130,28 @@ interface AwsCdkProjectOptions extends Omit<awscdk.AwsCdkTypeScriptAppOptions, "
      * @default - the parent monorepo's catalog pin for `constructs`
      */
     readonly constructsVersion?: string;
+    /**
+     * Options for the `CdkCli` component that every `cdk` invocation this
+     * project renders flows through — per-stage command defaults, per-account
+     * overrides, and the pinned CLI version.
+     *
+     * The component has to be seeded here rather than constructed afterwards.
+     * This constructor creates an `AwsDeploymentConfig`, which auto-creates a
+     * default `CdkCli` when the project has none, and `CdkCli.of()` resolves to
+     * the *first* matching component — so a `new CdkCli(project, options)` built
+     * once the constructor has returned is silently unreachable: no error, no
+     * warning, and the generated workflows render as if nothing was passed.
+     *
+     * Use it to declare a setting once per project instead of repeating it on
+     * every target via `AwsDeploymentTargetOptions.cdkOptions` — for example
+     * pinning `cdk diff --method=change-set` across stages so a diff never
+     * degrades to a template-only comparison and reports it as authoritative.
+     *
+     * @see `docs/src/content/docs/packages/@codedrifters/configulator/cdk-cli.md`
+     * @default - a `CdkCli` carrying no consumer overrides, identical to the one
+     * `AwsDeploymentConfig` would have auto-created
+     */
+    readonly cdkCliOptions?: CdkCliOptions;
     /**
      * AWS deployment targets (dev / stage / prod accounts and regions). Each
      * entry creates an `AwsDeploymentTarget` component on the project.

package/lib/index.d.ts

@@ -14157,11 +14157,15 @@ interface AwsCdkProjectOptions extends Omit<awscdk.AwsCdkTypeScriptAppOptions, "
     /**
      * Minimum version of `aws-cdk-lib` to depend on.
      *
-     * Optional, and normally omitted: the rendered specifier is always
-     * `catalog:`, so the parent `MonorepoProject`'s pnpm catalog decides the
-     * resolved version. Supplying a value that disagrees with that catalog
-     * entry throws rather than being silently discarded — bump the catalog
-     * instead.
+     * Optional, and normally omitted: the rendered specifier is `catalog:`
+     * whenever the parent `MonorepoProject`'s pnpm catalog carries an entry, so
+     * that catalog decides the resolved version. Supplying a value that
+     * disagrees with the entry throws rather than being silently discarded —
+     * bump the catalog instead. Only where the catalog has no entry at all does
+     * this value render, and then it must be an exact version.
+     *
+     * Listing `aws-cdk-lib` in `deps`, `devDeps`, or `peerDeps` is never the way
+     * to move it — the first is overridden by the pin and the other two throw.
      *
      * @default - the parent monorepo's catalog pin for `aws-cdk-lib`
      */
@@ -14175,6 +14179,28 @@ interface AwsCdkProjectOptions extends Omit<awscdk.AwsCdkTypeScriptAppOptions, "
      * @default - the parent monorepo's catalog pin for `constructs`
      */
     readonly constructsVersion?: string;
+    /**
+     * Options for the `CdkCli` component that every `cdk` invocation this
+     * project renders flows through — per-stage command defaults, per-account
+     * overrides, and the pinned CLI version.
+     *
+     * The component has to be seeded here rather than constructed afterwards.
+     * This constructor creates an `AwsDeploymentConfig`, which auto-creates a
+     * default `CdkCli` when the project has none, and `CdkCli.of()` resolves to
+     * the *first* matching component — so a `new CdkCli(project, options)` built
+     * once the constructor has returned is silently unreachable: no error, no
+     * warning, and the generated workflows render as if nothing was passed.
+     *
+     * Use it to declare a setting once per project instead of repeating it on
+     * every target via `AwsDeploymentTargetOptions.cdkOptions` — for example
+     * pinning `cdk diff --method=change-set` across stages so a diff never
+     * degrades to a template-only comparison and reports it as authoritative.
+     *
+     * @see `docs/src/content/docs/packages/@codedrifters/configulator/cdk-cli.md`
+     * @default - a `CdkCli` carrying no consumer overrides, identical to the one
+     * `AwsDeploymentConfig` would have auto-created
+     */
+    readonly cdkCliOptions?: CdkCliOptions;
     /**
      * AWS deployment targets (dev / stage / prod accounts and regions). Each
      * entry creates an `AwsDeploymentTarget` component on the project.

package/lib/index.js

@@ -43916,20 +43916,24 @@ var AwsCdkProject = class extends import_projen31.awscdk.AwsCdkTypeScriptApp {
     const pnpmVersion = parent.pnpmVersion;
     const pnpmWorkspace = PnpmWorkspace.of(parent);
     const defaultCatalog = pnpmWorkspace?.defaultCatalog ?? {};
-    const cdkVersion = resolveCatalogVersion(
+    rejectCatalogManagedDeps("devDeps", userOptions.devDeps);
+    rejectCatalogManagedDeps("peerDeps", userOptions.peerDeps);
+    const cdkPin = resolveCatalogPin(
       "cdkVersion",
       "aws-cdk-lib",
       userOptions.cdkVersion,
       VERSION.AWS_CDK_LIB_VERSION,
       defaultCatalog
     );
-    const constructsVersion = resolveCatalogVersion(
+    const constructsPin = resolveCatalogPin(
       "constructsVersion",
       "constructs",
       userOptions.constructsVersion,
       VERSION.AWS_CONSTRUCTS_VERSION,
       defaultCatalog
     );
+    const cdkVersion = cdkPin.version;
+    const constructsVersion = constructsPin.version;
     const resolvedOutdir = userOptions.outdir ?? resolveAwsCdkProjectOutdir(userOptions.packageName ?? userOptions.name);
     const testRunner = userOptions.testRunner ?? TestRunner.JEST;
     const useJest = testRunner === TestRunner.JEST;
@@ -44040,7 +44044,10 @@ var AwsCdkProject = class extends import_projen31.awscdk.AwsCdkTypeScriptApp {
     };
     super(options);
     this.addDevDeps("@types/node@catalog:");
-    this.addDeps("aws-cdk-lib@catalog:", "constructs@catalog:");
+    this.addDeps(
+      `aws-cdk-lib@${cdkPin.specifier}`,
+      `constructs@${constructsPin.specifier}`
+    );
     this.tsconfig?.file.addOverride("compilerOptions.skipLibCheck", true);
     if (testRunner === TestRunner.VITEST) {
       new Vitest(this, {
@@ -44065,6 +44072,7 @@ var AwsCdkProject = class extends import_projen31.awscdk.AwsCdkTypeScriptApp {
     });
     this.gitignore?.addPatterns(".DS_Store", "test-reports", "cdk.out");
     this.npmignore?.addPatterns("*.spec.*", "*.test.*", "__fixtures__");
+    new CdkCli(this, options.cdkCliOptions ?? {});
     new AwsDeploymentConfig(this);
     (options.deploymentTargets ?? []).forEach(
       (targetOptions) => this.addDeploymentTarget(targetOptions)
@@ -44150,10 +44158,28 @@ var AwsCdkProject = class extends import_projen31.awscdk.AwsCdkTypeScriptApp {
   }
 };
 var EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/;
-function resolveCatalogVersion(optionName, packageName, suppliedVersion, fallbackVersion, catalog) {
+var CATALOG_MANAGED_PACKAGES = ["aws-cdk-lib", "constructs"];
+function rejectCatalogManagedDeps(optionName, specs) {
+  for (const spec2 of specs ?? []) {
+    const { name } = import_projen31.Dependencies.parseDependency(spec2);
+    if (!CATALOG_MANAGED_PACKAGES.includes(name)) {
+      continue;
+    }
+    throw new Error(
+      `AwsCdkProject pins "${name}" itself, as a runtime dependency on the parent MonorepoProject's catalog, so \`${optionName}: ["${spec2}"]\` never reaches that pin \u2014 it renders a second, unpinned specifier beside it or is dropped outright. Remove "${spec2}" from \`${optionName}\`, and change the version through the catalog entry for "${name}" instead.`
+    );
+  }
+}
+function resolveCatalogPin(optionName, packageName, suppliedVersion, fallbackVersion, catalog) {
   const catalogVersion = catalog[packageName];
   if (catalogVersion === void 0) {
-    return suppliedVersion ?? fallbackVersion;
+    const version = suppliedVersion ?? fallbackVersion;
+    if (!EXACT_VERSION.test(version)) {
+      throw new Error(
+        `AwsCdkProject pins "${packageName}" exactly, but the parent MonorepoProject's catalog carries no entry for it, so the rendered specifier falls back to \`${optionName}: "${version}"\` \u2014 a range, which would leave every CDK app floating within it. Add an exact "${packageName}" entry to the catalog, or set \`${optionName}\` to an exact version.`
+      );
+    }
+    return { version, specifier: version };
   }
   if (!EXACT_VERSION.test(catalogVersion)) {
     throw new Error(
@@ -44165,7 +44191,7 @@ function resolveCatalogVersion(optionName, packageName, suppliedVersion, fallbac
       `AwsCdkProject renders "${packageName}" as "catalog:", so the parent MonorepoProject's catalog pin (${catalogVersion}) decides the resolved version. \`${optionName}: "${suppliedVersion}"\` would be silently ignored. Drop the option, or bump the catalog entry for "${packageName}" to ${suppliedVersion}.`
     );
   }
-  return catalogVersion;
+  return { version: catalogVersion, specifier: "catalog:" };
 }
 
 // src/projects/react-vite-site-project.ts