@aligent/nx-cdk 0.3.1 → 0.4.0

package/README.md

@@ -21,6 +21,13 @@ npx create-nx-workspace@latest --preset=@aligent/nx-cdk
 | `name`        | string | Yes      | -         | The name of the project/application (alphanumeric and dashes only)               |
 | `nodeVersion` | string | No       | `24.11.0` | The target Node.js version for the project (must be valid semver, e.g., 22.10.0) |
 
+#### Post-generation setup
+
+After running the preset generator, review these defaults before committing:
+
+- **AWS profile** — The `pg:synth`, `pg:deploy`, `pg:diff`, and `pg:destroy` scripts in `package.json` use `--profile playground`. This assumes a profile named `playground` exists in your `~/.aws/config`. Update the profile name in the `pg:*` scripts if yours differs.
+- **`.github/CODEOWNERS`** — The generated file references Aligent's GitHub teams (`@aligent/microservices`, `@aligent/devops`). Replace these with your organisation's team handles.
+
 #### What it creates
 
 The preset generator scaffolds:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/nx-cdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "commonjs",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",

package/src/generators/helpers/configs/nxJson.js

@@ -26,7 +26,7 @@ exports.NX_JSON = {
             cache: true,
             dependsOn: ['^build'],
             inputs: ['production', '^production'],
-            outputs: ['{projectRoot}/dist'],
+            outputs: ['{projectRoot}/dist'], // FIXME: It seems that this doesn't cache correctly. Investigate this.
         },
         lint: { cache: true, inputs: ['default', '^production'] },
         test: {
@@ -37,5 +37,7 @@ exports.NX_JSON = {
             configurations: { coverage: { coverage: true } },
         },
         typecheck: { cache: true, inputs: ['default', '^production'] },
+        cdk: { dependsOn: [{ target: 'build', params: 'forward', projects: '@services/*' }] },
+        pg: { dependsOn: [{ target: 'build', params: 'forward', projects: '@services/*' }] },
     },
 };

package/src/generators/helpers/configs/packageJson.d.ts

@@ -10,17 +10,18 @@ export declare const PACKAGE_JSON: {
         readonly 'lint:all': "nx run-many -t lint";
         readonly typecheck: "nx affected -t typecheck";
         readonly 'typecheck:all': "nx run-many -t typecheck";
-        readonly postinstall: "[ -d .git ] && git config core.hooksPath '.git-hooks' && chmod +x .git-hooks/* || true";
-        readonly 'pg:synth': "nx run application:cdk synth 'dev/**' --exclusively --bundle-mode=dev --profile=playground";
-        readonly 'pg:deploy': "nx run application:cdk deploy 'dev/**' --method=direct --require-approval=never --exclusively --bundle-mode=dev --profile=playground";
-        readonly 'pg:destroy': "nx run application:cdk destroy 'dev/**' --profile playground";
         readonly audit: "nx run-many -t lint typecheck test --configuration coverage --skip-nx-cache";
+        readonly 'pg:synth': "nx run application:pg:synth --bundle-mode=dev --profile playground";
+        readonly 'pg:deploy': "nx run application:pg:deploy --bundle-mode=dev --method=direct --require-approval never --profile playground";
+        readonly 'pg:diff': "nx run application:pg:diff --profile playground";
+        readonly 'pg:destroy': "nx run application:pg:destroy --profile playground";
+        readonly postinstall: "[ -d .git ] && git config core.hooksPath '.git-hooks' && chmod +x .git-hooks/* || true";
     };
     readonly dependencies: {
         readonly '@aligent/microservice-util-lib': "^1.2.0";
     };
     readonly devDependencies: {
-        readonly '@aligent/cdk-aspects': "^0.2.0";
+        readonly '@aligent/cdk-aspects': "^0.4.0";
         readonly '@aligent/cdk-step-function-from-file': "^0.3.2";
         readonly '@aligent/nx-openapi': "^1.0.0";
         readonly '@aligent/ts-code-standards': "^4.1.0";

package/src/generators/helpers/configs/packageJson.js

@@ -13,17 +13,18 @@ exports.PACKAGE_JSON = {
         'lint:all': 'nx run-many -t lint',
         typecheck: 'nx affected -t typecheck',
         'typecheck:all': 'nx run-many -t typecheck',
-        postinstall: `[ -d .git ] && git config core.hooksPath '.git-hooks' && chmod +x .git-hooks/* || true`,
-        'pg:synth': `nx run application:cdk synth 'dev/**' --exclusively --bundle-mode=dev --profile=playground`,
-        'pg:deploy': `nx run application:cdk deploy 'dev/**' --method=direct --require-approval=never --exclusively --bundle-mode=dev --profile=playground`,
-        'pg:destroy': "nx run application:cdk destroy 'dev/**' --profile playground",
         audit: 'nx run-many -t lint typecheck test --configuration coverage --skip-nx-cache',
+        'pg:synth': 'nx run application:pg:synth --bundle-mode=dev --profile playground',
+        'pg:deploy': 'nx run application:pg:deploy --bundle-mode=dev --method=direct --require-approval never --profile playground',
+        'pg:diff': 'nx run application:pg:diff --profile playground',
+        'pg:destroy': 'nx run application:pg:destroy --profile playground',
+        postinstall: `[ -d .git ] && git config core.hooksPath '.git-hooks' && chmod +x .git-hooks/* || true`,
     },
     dependencies: {
         '@aligent/microservice-util-lib': '^1.2.0',
     },
     devDependencies: {
-        '@aligent/cdk-aspects': '^0.2.0',
+        '@aligent/cdk-aspects': '^0.4.0',
         '@aligent/cdk-step-function-from-file': '^0.3.2',
         '@aligent/nx-openapi': '^1.0.0',
         '@aligent/ts-code-standards': '^4.1.0',

package/src/generators/helpers/utilities.d.ts

@@ -18,11 +18,12 @@ export declare function constructPackageJsonFile(input: PackageJsonInput): {
         readonly 'lint:all': "nx run-many -t lint";
         readonly typecheck: "nx affected -t typecheck";
         readonly 'typecheck:all': "nx run-many -t typecheck";
-        readonly postinstall: "[ -d .git ] && git config core.hooksPath '.git-hooks' && chmod +x .git-hooks/* || true";
-        readonly 'pg:synth': "nx run application:cdk synth 'dev/**' --exclusively --bundle-mode=dev --profile=playground";
-        readonly 'pg:deploy': "nx run application:cdk deploy 'dev/**' --method=direct --require-approval=never --exclusively --bundle-mode=dev --profile=playground";
-        readonly 'pg:destroy': "nx run application:cdk destroy 'dev/**' --profile playground";
         readonly audit: "nx run-many -t lint typecheck test --configuration coverage --skip-nx-cache";
+        readonly 'pg:synth': "nx run application:pg:synth --bundle-mode=dev --profile playground";
+        readonly 'pg:deploy': "nx run application:pg:deploy --bundle-mode=dev --method=direct --require-approval never --profile playground";
+        readonly 'pg:diff': "nx run application:pg:diff --profile playground";
+        readonly 'pg:destroy': "nx run application:pg:destroy --profile playground";
+        readonly postinstall: "[ -d .git ] && git config core.hooksPath '.git-hooks' && chmod +x .git-hooks/* || true";
     } | {
         readonly '@aligent/microservice-util-lib': "^1.2.0";
     } | {

package/src/generators/preset/files/.github/CODEOWNERS.template

@@ -1,3 +1,5 @@
-# Both Microservice and DevOps teams own everything in this repo
-# We'll review this in few months time and adjust when needed
-* @aligent/microservices @aligent/devops
+# Default owners
+* @aligent/microservices
+
+# DevOps owns files inside .github/
+.github/** @aligent/devops

package/src/generators/preset/files/.github/workflows/release.yml.template

@@ -12,6 +12,6 @@ jobs:
     with:
       deploy: true
       deploy-command: yarn nx run application:cdk deploy
-      extra-arguments: --exclusively
+      environment-target: prd
       github-environment: production
     secrets: inherit

package/src/generators/preset/files/.github/workflows/stg-deployment.yml.template

@@ -12,6 +12,6 @@ jobs:
     with:
       deploy: true
       deploy-command: yarn nx run application:cdk deploy
-      extra-arguments: --exclusively
+      environment-target: stg
       github-environment: staging
     secrets: inherit

package/src/generators/preset/files/README.md.template

@@ -48,6 +48,25 @@ nvm use
 yarn install
 ```
 
+### Initial Setup Checklist
+
+Before committing this repository, review and update the following generated defaults:
+
+- **`.github/CODEOWNERS`** — The default file references Aligent's GitHub teams (`@aligent/microservices`, `@aligent/devops`). Replace these with your own organisation's team handles.
+- **`package.json` `pg:*` scripts** — The playground scripts use `--profile playground`. Ensure you have a matching profile in your `~/.aws/config` file:
+
+    ```ini
+    [profile playground]
+    source_profile = default
+    role_arn = arn:aws:iam::11111111111:role/RoleName
+    ```
+
+    If your profile has a different name, update the `pg:*` scripts in the root `package.json` to match.
+
+### Deployment
+
+For deployment instructions (synthesize, deploy, destroy), see the [CDK Application README](./application/README.md).
+
 ## Contributing
 
 We follow [trunk-based development framework](https://trunkbaseddevelopment.com/) as a start and will evolve depending on our need.

package/src/generators/preset/files/application/README.md.template

@@ -6,12 +6,44 @@ This application manages the deployment of microservices and their shared infras
 
 ### Using yarn script from workspace root (Recommended)
 
+##### Synthesize
+
 ```bash
-# Synthesize templates
+# Synthesize for default environment/stage (dev)
 yarn pg:synth
 
-# Deploy to playground
+# Synthesize for a custom environment/stage
+yarn pg:synth --args="plg/** -c environment=plg"
+```
+
+##### Deploy
+
+```bash
+# Deploy for default environment/stage (dev)
 yarn pg:deploy
+
+# Deploy to a custom environment/stage
+yarn pg:deploy --args="plg/** -c environment=plg"
+```
+
+##### Diff
+
+```bash
+# Diff checking for default environment/stage (dev)
+yarn pg:diff
+
+# Diff checking for a custom environment/stage
+yarn pg:diff --args="-c environment=plg"
+```
+
+##### Destroy
+
+```bash
+# Destroy default environment/stage (dev)
+yarn pg:destroy
+
+# Destroy a custom environment/stage
+yarn pg:destroy --args="-c environment=plg"
 ```
 
 ### Direct Nx Commands

package/src/generators/preset/files/application/bin/main.ts.template

@@ -4,66 +4,94 @@ import {
     LogGroupDefaultsAspect,
     MicroserviceChecks,
     NodeJsFunctionDefaultsAspect,
+    ResourcePrefixAspect,
     StepFunctionsDefaultsAspect,
 } from '@aligent/cdk-aspects';
-import { App, Aspects, Tags } from 'aws-cdk-lib';
-import { Runtime } from 'aws-cdk-lib/aws-lambda';
+import { App, AspectOptions, AspectPriority, Aspects, IAspect, Runtime, Tags } from 'aws-cdk-lib';
 import { ApplicationStage } from '../lib/service-stacks.js';
 
-const APPLICATION_CONTEXT = { NAME: '<%= name %>-int', OWNER: 'aligent' } as const;
-const STAGE_NAMES = { DEV: 'dev', STG: 'stg', PRD: 'prd' } as const;
-
+const APPLICATION_CONTEXT = { NAME: '<%= name %>-int', OWNER: 'Aligent' } as const;
 const app = new App({ context: APPLICATION_CONTEXT });
-Tags.of(app).add('OWNER', APPLICATION_CONTEXT.OWNER);
 
 /**
- * Apply Application-Level Aspects
- * These aspects are applied to all resources across all stages
- */
-Aspects.of(app).add(new NodeJsFunctionDefaultsAspect({ runtime: Runtime.NODEJS_<%= nodeRuntime %> }));
-Aspects.of(app).add(new StepFunctionsDefaultsAspect());
-Aspects.of(app).add(new MicroserviceChecks());
-
-/**
- * Static Stage Creation Approach
- *
- * We use static stage creation (explicitly defining dev, stg, prd) for several reasons:
+ * Dynamic Stage (Environment) Creation
  *
- * 1. **Predictability**: All stages are known at synthesis time, making the CDK app
- *    behavior deterministic and easier to reason about.
+ * The stage (environment) name is provided via CDK context: `cdk synth -c environment=dev`
  *
- * 2. **Type Safety**: Static definitions provide better IDE support, autocompletion,
- *    and compile-time type checking for stage-specific configurations.
- *
- * 3. **Explicit Configuration**: Each stage's unique settings (e.g., log retention
- *    durations, aspects) are clearly visible in the code without needing to trace
- *    through dynamic logic.
- *
- * 4. **Simpler Deployment**: CDK can synthesize all stages in a single pass without
- *    requiring runtime context lookups or conditional logic.
- *
- * 5. **CI/CD Integration**: Static stages integrate seamlessly with standard CI/CD
- *    pipelines where environment configuration is managed externally.
+ * - Stage name must be exactly 3 lowercase alphanumeric characters (e.g., dev (default), stg, prd)
+ * - Production-specific aspects (versioning, long log retention) are applied only to `prd`
+ * - Non-production stages get shorter log retention and debug-level logging
  *
  * @see {@link https://dev.to/aws-heroes/how-to-use-aws-cdk-stage-and-when-to-choose-static-vs-dynamic-stack-creation-35h|Static vs Dynamic Stack Creation}
- *
- * @remarks
- * Aspects visit all constructs in the tree after synthesis and can modify them
- * (e.g., applying log retention policies, enabling tracing).
  */
+const stageName = app.node.tryGetContext('environment') ?? 'dev';
 
-const dev = new ApplicationStage(app, STAGE_NAMES.DEV);
-Aspects.of(dev).add(new LogGroupDefaultsAspect({ duration: 'SHORT' }));
+if (typeof stageName !== 'string' || !/^[a-z0-9]{3}$/.test(stageName)) {
+    throw new Error(
+        `Invalid stage (environment) name: "${stageName}". Stage must be exactly 3 lowercase alphanumeric characters (e.g., dev, stg, prd)`
+    );
+}
 
-const stg = new ApplicationStage(app, STAGE_NAMES.STG);
-Aspects.of(stg).add(new LogGroupDefaultsAspect({ duration: 'MEDIUM' }));
+const stage = new ApplicationStage(app, stageName);
+Tags.of(stage).add('APPLICATION', APPLICATION_CONTEXT.NAME);
+Tags.of(stage).add('OWNER', APPLICATION_CONTEXT.OWNER);
+Tags.of(stage).add('STAGE', stageName);
 
 /**
- * Production Stage
- * - Long log retention (2 years) for compliance and debugging
- * - Resources retained on stack deletion
- * - Lambda functions and Step Functions are automatically versioned, enabled for zero-downtime deployments
+ * Common aspects applied to every stage.
+ *
+ * Aspects must be registered on each `Stage` individually — a `Stage` creates a
+ * synthesis boundary that prevents `App`-level aspects from traversing into it.
+ *
+ * Order matters: `ResourcePrefixAspect` runs first (priority 100) so that
+ * resource names are finalised before the versioning aspect reads them.
  */
-const prd = new ApplicationStage(app, STAGE_NAMES.PRD);
-Aspects.of(prd).add(new LogGroupDefaultsAspect({ duration: 'LONG' }));
-Aspects.of(prd).add(new LambdaAndStepFunctionVersioningAspect());
+const commonAspectsWithOptions: Array<{ aspect: IAspect; options: AspectOptions }> = [
+    {
+        aspect: new ResourcePrefixAspect({ prefix: `${APPLICATION_CONTEXT.NAME}-${stageName}` }),
+        options: { priority: 100 },
+    },
+    {
+        aspect: new NodeJsFunctionDefaultsAspect({ runtime: Runtime.NODEJS_<%= nodeRuntime %> }),
+        options: { priority: AspectPriority.MUTATING },
+    },
+    { aspect: new StepFunctionsDefaultsAspect(), options: { priority: AspectPriority.MUTATING } },
+    { aspect: new MicroserviceChecks(), options: { priority: AspectPriority.READONLY } },
+];
+
+/**
+ * Apply common aspects to the stage, then add stage-specific aspects.
+ *
+ * @remarks
+ * Aspects visit every construct in the tree after synthesis and may mutate them
+ * (e.g. setting log retention, enabling X-Ray tracing).
+ *
+ * Stage-specific behaviour:
+ * - `prd`: long log retention (2 years) for compliance; Lambda and Step Function
+ *   versioning enabled for zero-downtime deployments.
+ * - `stg`: medium log retention.
+ * - all others: short log retention.
+ */
+commonAspectsWithOptions.forEach(({ aspect, options }) => {
+    Aspects.of(stage).add(aspect, options);
+});
+
+switch (stageName) {
+    case 'prd':
+        Aspects.of(stage).add(new LogGroupDefaultsAspect({ duration: 'LONG' }), {
+            priority: AspectPriority.MUTATING,
+        });
+        Aspects.of(stage).add(new LambdaAndStepFunctionVersioningAspect(), {
+            priority: AspectPriority.MUTATING,
+        });
+        break;
+    case 'stg':
+        Aspects.of(stage).add(new LogGroupDefaultsAspect({ duration: 'MEDIUM' }), {
+            priority: AspectPriority.MUTATING,
+        });
+        break;
+    default:
+        Aspects.of(stage).add(new LogGroupDefaultsAspect({ duration: 'SHORT' }), {
+            priority: AspectPriority.MUTATING,
+        });
+}

package/src/generators/preset/files/application/lib/service-stacks.ts.template

@@ -1,5 +1,5 @@
 import { SharedInfraStack } from '@libs/infra';
-import { Stage, Tags, type StageProps } from 'aws-cdk-lib';
+import { Stage, type StageProps } from 'aws-cdk-lib';
 import type { Construct } from 'constructs';
 
 /**
@@ -15,7 +15,6 @@ import type { Construct } from 'constructs';
 export class ApplicationStage extends Stage {
     constructor(scope: Construct, id: string, props?: StageProps) {
         super(scope, id, props);
-        Tags.of(this).add('STAGE', id);
 
         const sharedInfra = new SharedInfraStack(this, 'shared-infra', props);
 

package/src/generators/preset/files/application/package.json.template

@@ -14,14 +14,28 @@
           "color": true,
           "command": "cdk",
           "cwd": "{projectRoot}"
-        },
-        "dependsOn": [
-          {
-            "target": "build",
-            "params": "forward",
-            "projects": "@services/*"
+        }
+      },
+      "pg": {
+        "executor": "nx:run-commands",
+        "configurations": {
+          "synth": {
+            "command": "cdk synth"
+          },
+          "deploy": {
+            "command": "cdk deploy"
+          },
+          "diff": {
+            "command": "cdk diff"
+          },
+          "destroy": {
+            "command": "cdk destroy"
           }
-        ]
+        },
+        "options": {
+          "color": true,
+          "cwd": "{projectRoot}"
+        }
       }
     }
   }

package/src/generators/preset/files/libs/infra/README.md.template

@@ -56,6 +56,6 @@ Resources that are used by multiple services are created once in the shared infr
 
 The `SharedInfraStack` must be instantiated within a CDK Stage to properly resolve the stage name for resource naming and tagging.
 
-### Application Context
+### Resource Naming
 
-Requires the `NAME` context variable to be set for proper resource naming conventions.
+Resource prefixes are automatically applied via a CDK aspect, ensuring consistent naming conventions across all resources without manual configuration.

package/src/generators/preset/files/libs/infra/src/index.ts.template

@@ -1,36 +1,32 @@
 import { Stack, Stage, type StackProps } from 'aws-cdk-lib';
 import { Secret } from 'aws-cdk-lib/aws-secretsmanager';
-import { StringParameter } from 'aws-cdk-lib/aws-ssm';
+import { IStringParameter, StringParameter } from 'aws-cdk-lib/aws-ssm';
 import type { Construct } from 'constructs';
 
 export interface SharedInfraProps {
-    eCommerceBaseUrl: string;
+    eCommerceBaseUrl: IStringParameter;
     eCommerceCredentials: Secret;
 }
 
 export class SharedInfraStack extends Stack {
-    readonly eCommerceBaseUrl: string;
+    readonly eCommerceBaseUrl: IStringParameter;
     readonly eCommerceCredentials: Secret;
 
     constructor(scope: Construct, id: string, props?: StackProps) {
         super(scope, id, props);
 
-        const STAGE = Stage.of(this)?.stageName;
-        if (!STAGE) {
+        if (!Stage.of(this)?.stageName) {
             throw new Error('This construct must be used within a CDK Stage');
         }
 
-        const applicationName = this.node.tryGetContext('NAME');
-
         this.eCommerceBaseUrl = StringParameter.fromStringParameterName(
             this,
             'ECommerceBaseUrl',
-            `/${applicationName}/e-commerce/base-url`
-        ).stringValue;
+            `/e-commerce/base-url`
+        );
 
         // Create secrets once in the shared stack
         this.eCommerceCredentials = new Secret(this, 'ECommerceCredentials', {
-            secretName: `${applicationName}/e-commerce-credentials`,
             description: 'E-Commerce API credentials shared across services',
         });
     }