@fjall/components-infrastructure 4.3.0 → 5.0.0

package/dist/lib/utils/engineCompat.js

@@ -26,10 +26,21 @@
  * hand-edit. A same-major-or-newer engine proceeds; an older-major engine
  * hard-refuses.
  *
- * The optional `maximumEngineMajor` / `minimumAwsCdkCli` bounds are deliberately
- * NOT emitted in Phase 1 — they are ADR open question Q5 (engine-ahead cap) and
- * the Phase-2 FM1 aws-cdk floor graft respectively, both unresolved and
- * deferred. This emitter stamps only the two required fields.
+ * `minimumAwsCdkCli` (Phase 2, FM1) is the floor for the deploy engine's bundled
+ * `aws-cdk` CLI: an engine whose CLI is older than the version these constructs
+ * were blessed against cannot reliably read the cloud assembly they synthesised.
+ * The aws-cdk CLI and aws-cdk-lib version axes DIVERGED in CDK v2 (CLI ~2.1134.x
+ * vs lib ~2.262.x), so this is a distinct check from `minimumEngineVersion`, on a
+ * different axis. It is derived from the constructs' OWN
+ * `peerDependencies["aws-cdk"]` floor — self-honest, and shipped with the package
+ * (unlike the blessed-pin JSON, which is not in `files`) — and conditional-spread
+ * so a package whose peer floor cannot be resolved simply omits it (fail-safe: the
+ * FM1 check degrades to no-op rather than emitting a garbage floor).
+ *
+ * The optional `maximumEngineMajor` bound is deliberately NOT emitted — it is ADR
+ * open question Q5 (engine-ahead cap), and capping a newer engine would break the
+ * normal fjall-upgrade-then-redeploy path. The classifier still honours one if a
+ * future assembly stamps it by hand; this emitter never does.
  *
  * Fail-safe: if the constructs' own version cannot be resolved (a broken
  * package layout), `buildEngineCompat` returns undefined and the caller stamps
@@ -43,7 +54,41 @@ import { existsSync, readFileSync } from "fs";
 import { getErrorMessage, maskSensitiveOutput } from "@fjall/util";
 import { FjallLogger } from "./validationLogger.js";
 const PACKAGE_NAME = "@fjall/components-infrastructure";
-function resolveConstructsVersion() {
+/**
+ * Normalise an npm dependency RANGE to its minimum X.Y.Z floor: strip a leading
+ * range operator (`^`, `~`, `>=`, `>`, `=`, `v`) and any prerelease/build
+ * metadata, then reconstruct `${major}.${minor}.${patch}` (missing minor/patch
+ * default to 0). Returns undefined for anything without a valid integer major —
+ * so a non-semver range (a git URL, `*`) yields no floor and the caller omits
+ * the field rather than emitting garbage.
+ */
+export function rangeFloor(range) {
+    if (range === undefined || range.length === 0)
+        return undefined;
+    const firstToken = range.trim().split(/\s+/)[0] ?? "";
+    const core = firstToken.replace(/^[\^~>=v ]+/i, "").split(/[-+]/)[0] ?? "";
+    if (core.length === 0)
+        return undefined;
+    const parts = core.split(".");
+    const major = Number(parts[0]);
+    const minor = parts.length > 1 ? Number(parts[1]) : 0;
+    const patch = parts.length > 2 ? Number(parts[2]) : 0;
+    if (!Number.isInteger(major) || major < 0)
+        return undefined;
+    if (!Number.isInteger(minor) || minor < 0)
+        return undefined;
+    if (!Number.isInteger(patch) || patch < 0)
+        return undefined;
+    return `${major}.${minor}.${patch}`;
+}
+/**
+ * Resolve the constructs' own package.json (version + aws-cdk peer floor) by the
+ * same upward `name`-matching walk `DEPLOY_CORE_VERSION` uses — robust across the
+ * source (`lib/utils/`) and compiled (`dist/lib/utils/`) layouts, and skipping any
+ * unrelated `package.json` higher up (a consuming app's). Returns undefined only
+ * when the walk finds no matching `package.json` (broken layout).
+ */
+function resolveConstructsPackageMeta() {
     try {
         let dir = dirname(fileURLToPath(import.meta.url));
         const { root } = parse(dir);
@@ -54,7 +99,13 @@ function resolveConstructsVersion() {
                 if (pkg.name === PACKAGE_NAME &&
                     typeof pkg.version === "string" &&
                     pkg.version.length > 0) {
-                    return pkg.version;
+                    const awsCdkPeer = pkg.peerDependencies?.["aws-cdk"];
+                    return {
+                        version: pkg.version,
+                        awsCdkCliFloor: typeof awsCdkPeer === "string"
+                            ? rangeFloor(awsCdkPeer)
+                            : undefined
+                    };
                 }
             }
             if (dir === root)
@@ -63,28 +114,40 @@ function resolveConstructsVersion() {
         }
     }
     catch (error) {
-        FjallLogger.warn(`Could not resolve ${PACKAGE_NAME} version for engineCompat: ` +
+        FjallLogger.warn(`Could not resolve ${PACKAGE_NAME} metadata for engineCompat: ` +
             maskSensitiveOutput(getErrorMessage(error)));
         return undefined;
     }
 }
+const CONSTRUCTS_PACKAGE_META = resolveConstructsPackageMeta();
 /**
  * The constructs' own package version — the assembly's `synthesisedBy`.
  * `undefined` only when the package layout is broken enough that the upward
  * walk finds no matching `package.json`.
  */
-export const CONSTRUCTS_VERSION = resolveConstructsVersion();
+export const CONSTRUCTS_VERSION = CONSTRUCTS_PACKAGE_META?.version;
+/**
+ * The minimum `aws-cdk` CLI floor these constructs were blessed against, derived
+ * from their own `peerDependencies["aws-cdk"]` — the FM1 `minimumAwsCdkCli` emit
+ * value. `undefined` when the peer is absent or non-semver (the field is then
+ * omitted from the stamped block).
+ */
+export const AWS_CDK_CLI_FLOOR = CONSTRUCTS_PACKAGE_META?.awsCdkCliFloor;
 /**
  * Pure core of the emitter: derive the `engineCompat` block from a given
- * version string (or undefined). Both the absent/empty guard and the
- * `${major}.0.0` non-integer-major derivation live here — the single source of
- * the derivation, delegated to by both `MINIMUM_ENGINE_VERSION` and
- * `buildEngineCompat` — so the fail-safe and malformed-version paths are
- * unit-testable directly, without mocking module-load state. Returns undefined
- * when the version is absent, empty, or has no valid integer major (fail-safe:
- * the caller stamps no block).
+ * version string (or undefined) and an optional aws-cdk CLI floor. Both the
+ * absent/empty guard and the `${major}.0.0` non-integer-major derivation live
+ * here — the single source of the derivation, delegated to by both
+ * `MINIMUM_ENGINE_VERSION` and `buildEngineCompat` — so the fail-safe and
+ * malformed-version paths are unit-testable directly, without mocking
+ * module-load state. Returns undefined when the version is absent, empty, or has
+ * no valid integer major (fail-safe: the caller stamps no block).
+ *
+ * `awsCdkCliFloor` is conditional-spread: an absent/empty floor omits
+ * `minimumAwsCdkCli` entirely (Zod-pitfall-2 safe — never `undefined`), so the
+ * FM1 check degrades to no-op rather than shipping a malformed constraint.
  */
-export function buildEngineCompatFrom(version) {
+export function buildEngineCompatFrom(version, awsCdkCliFloor) {
     if (version === undefined || version.length === 0)
         return undefined;
     const major = Number(version.split(".")[0]);
@@ -92,7 +155,9 @@ export function buildEngineCompatFrom(version) {
         return undefined;
     return {
         synthesisedBy: version,
-        minimumEngineVersion: `${major}.0.0`
+        minimumEngineVersion: `${major}.0.0`,
+        ...(awsCdkCliFloor !== undefined &&
+            awsCdkCliFloor.length > 0 && { minimumAwsCdkCli: awsCdkCliFloor })
     };
 }
 /**
@@ -107,12 +172,14 @@ export const MINIMUM_ENGINE_VERSION = buildEngineCompatFrom(CONSTRUCTS_VERSION)?
  * when the constructs' own version cannot be resolved (fail-safe: the caller
  * stamps no block and the deploy degrades to a constraint-free proceed).
  *
- * Phase 1 emits only the two required fields. The verdict classification of the
- * emitted floor is proven in `@fjall/deploy-core`'s
- * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` floor
- * refuses a 3.x engine, proceeds for 4.x/5.x); this module's tests prove the
- * emitted shape matches that floor and reads back through the gate's reader.
+ * Emits the two required fields plus `minimumAwsCdkCli` (Phase 2 FM1) whenever the
+ * aws-cdk peer floor resolves. The verdict classification of the emitted floors is
+ * proven in `@fjall/deploy-core`'s
+ * `orchestration/application/__tests__/engineCompat.test.ts` (a `4.0.0` engine
+ * floor refuses a 3.x engine; a `minimumAwsCdkCli` floor refuses an older bundled
+ * CLI); this module's tests prove the emitted shape matches those floors and reads
+ * back through the gate's reader.
  */
 export function buildEngineCompat() {
-    return buildEngineCompatFrom(CONSTRUCTS_VERSION);
+    return buildEngineCompatFrom(CONSTRUCTS_VERSION, AWS_CDK_CLI_FLOOR);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -34,53 +34,55 @@
     "clean": "rm -rf ./dist",
     "clean:node": "rm -rf ./node_modules",
     "build:cert-gen-lambda": "node lib/lambda-assets/cert-generator/src/build.mjs",
-    "build": "npm run build:cert-gen-lambda && tsc && cp -r lib/layers dist/lib/layers && mkdir -p dist/lib/lambda-assets/cert-generator/asset && cp lib/lambda-assets/cert-generator/asset/index.js dist/lib/lambda-assets/cert-generator/asset/index.js && cp lib/lambda-assets/cert-generator/asset/package.json dist/lib/lambda-assets/cert-generator/asset/package.json && mkdir -p dist/lib/lambda-assets/identity-store-user/asset && cp lib/lambda-assets/identity-store-user/asset/index.js dist/lib/lambda-assets/identity-store-user/asset/index.js && cp lib/lambda-assets/identity-store-user/asset/package.json dist/lib/lambda-assets/identity-store-user/asset/package.json && mkdir -p dist/lib/lambda-assets/static-site-forms/asset && cp lib/lambda-assets/static-site-forms/asset/index.js dist/lib/lambda-assets/static-site-forms/asset/index.js && cp lib/lambda-assets/static-site-forms/asset/package.json dist/lib/lambda-assets/static-site-forms/asset/package.json && cp lib/resources/aws/compute/lifecycleHookLambda.source.cjs dist/lib/resources/aws/compute/lifecycleHookLambda.source.cjs && cp lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs dist/lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs && cp lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs dist/lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs && cp lib/patterns/aws/devSubstrate.waker.source.cjs dist/lib/patterns/aws/devSubstrate.waker.source.cjs",
+    "build": "npm run build:cert-gen-lambda && tsc && cp -r lib/layers dist/lib/layers && mkdir -p dist/lib/lambda-assets/cert-generator/asset && cp lib/lambda-assets/cert-generator/asset/index.js dist/lib/lambda-assets/cert-generator/asset/index.js && cp lib/lambda-assets/cert-generator/asset/package.json dist/lib/lambda-assets/cert-generator/asset/package.json && mkdir -p dist/lib/lambda-assets/identity-store-user/asset && cp lib/lambda-assets/identity-store-user/asset/index.js dist/lib/lambda-assets/identity-store-user/asset/index.js && cp lib/lambda-assets/identity-store-user/asset/package.json dist/lib/lambda-assets/identity-store-user/asset/package.json && mkdir -p dist/lib/lambda-assets/static-site-forms/asset && cp lib/lambda-assets/static-site-forms/asset/index.js dist/lib/lambda-assets/static-site-forms/asset/index.js && cp lib/lambda-assets/static-site-forms/asset/package.json dist/lib/lambda-assets/static-site-forms/asset/package.json && cp lib/resources/aws/compute/lifecycleHookLambda.source.cjs dist/lib/resources/aws/compute/lifecycleHookLambda.source.cjs && cp lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs dist/lib/resources/aws/compute/ec2GracefulTerminationLambda.source.cjs && cp lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs dist/lib/resources/aws/compute/persistentDataVolumeLambda.source.cjs && cp lib/patterns/aws/devSubstrate.waker.source.cjs dist/lib/patterns/aws/devSubstrate.waker.source.cjs && node ../../scripts/stamp-build.mjs",
     "prepack": "node ../../scripts/check-dist-freshness.mjs",
     "watch": "tsc -w",
     "watch:only": "tsc -w",
     "test": "vitest run",
     "test:watch": "vitest",
+    "contract:manifest": "FJALL_WRITE_CONTRACT_MANIFEST=1 vitest run lib/__tests__/_contract/contract.test.ts",
     "cdk": "cdk",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "typecheck:tests": "tsc --noEmit -p tsconfig.test.json",
     "check:scripts": "tsc --project tsconfig.scripts.json",
+    "deploy-test": "tsx deploy-tests/run.mts",
     "lint": "eslint lib --no-warn-ignored",
     "lint:fix": "eslint lib --fix --no-warn-ignored",
-    "format": "prettier --write \"lib/**/*.{ts,tsx,js,jsx,json}\" \"scripts/**/*.mts\"",
-    "format:check": "prettier --check \"lib/**/*.{ts,tsx,js,jsx,json}\" \"scripts/**/*.mts\""
+    "format": "prettier --write \"lib/**/*.{ts,tsx,js,jsx,json}\" \"scripts/**/*.mts\" \"deploy-tests/**/*.mts\"",
+    "format:check": "prettier --check \"lib/**/*.{ts,tsx,js,jsx,json}\" \"scripts/**/*.mts\" \"deploy-tests/**/*.mts\""
   },
   "devDependencies": {
-    "@aws-sdk/client-elastic-load-balancing-v2": "^3.1045.0",
-    "@aws-sdk/client-iam": "^3.1038.0",
-    "@aws-sdk/client-identitystore": "^3.1038.0",
-    "@aws-sdk/client-sesv2": "^3.1087.0",
+    "@aws-sdk/client-elastic-load-balancing-v2": "^3.1098.0",
+    "@aws-sdk/client-iam": "^3.1098.0",
+    "@aws-sdk/client-identitystore": "^3.1098.0",
+    "@aws-sdk/client-sesv2": "^3.1098.0",
     "@peculiar/x509": "2.0.0",
-    "@types/aws-lambda": "^8.10.161",
-    "@types/node": "^26.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.59.1",
-    "@typescript-eslint/parser": "^8.59.1",
-    "eslint": "^10.2.1",
-    "prettier": "^3.8.3",
+    "@types/aws-lambda": "^8.10.162",
+    "@types/node": "^26.1.2",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
+    "eslint": "^10.8.0",
+    "prettier": "^3.9.6",
     "reflect-metadata": "^0.2.2",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.10"
   },
   "dependencies": {
-    "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^4.3.0",
-    "@fjall/util": "^4.3.0",
-    "constructs": "^10.6.0"
+    "@aws-sdk/client-organizations": "^3.1098.0",
+    "@fjall/generator": "^5.0.0",
+    "@fjall/util": "^5.0.0",
+    "constructs": "^10.7.2"
   },
   "overrides": {
     "@smithy/core": "2.5.5"
   },
   "peerDependencies": {
-    "aws-cdk": "^2.1128.1",
-    "aws-cdk-lib": "^2.260.0",
-    "constructs": "^10.6.0"
+    "aws-cdk": "^2.1134.0",
+    "aws-cdk-lib": "^2.262.2",
+    "constructs": "^10.7.2"
   },
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "8a3ae096f9d15c47dc8c277c9bddfa40e4168c19"
+  "gitHead": "78dded6f582368076e8b5f351399219e5a954659"
 }