@aligent/nx-cdk 0.5.0 → 0.7.0

package/package.json

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

package/src/generators/helpers/configs/base-package/package.json

@@ -21,10 +21,11 @@
     "@aligent/microservice-util-lib": "^1.2.0"
   },
   "devDependencies": {
-    "@aligent/cdk-aspects": "^0.5.0",
-    "@aligent/cdk-step-function-from-file": "^0.3.2",
-    "@aligent/nx-openapi": "^1.0.0",
-    "@aligent/ts-code-standards": "^4.1.0",
+    "@aligent/cdk-aspects": "^0.5.5",
+    "@aligent/cdk-nodejs-function-from-entry": "^0.2.1",
+    "@aligent/cdk-step-function-from-file": "^0.5.1",
+    "@aligent/nx-openapi": "^2.2.1",
+    "@aligent/ts-code-standards": "^4.2.1",
     "@nx/eslint": "22.1.3",
     "@nx/eslint-plugin": "22.1.3",
     "@nx/js": "22.1.3",
@@ -39,10 +40,10 @@
     "@typescript-eslint/parser": "8.44.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
-    "aws-cdk": "^2.1033.0",
-    "aws-cdk-lib": "^2.235.1",
-    "cdk-nag": "^2.37.55",
-    "constructs": "^10.4.3",
+    "aws-cdk": "^2.1120.0",
+    "aws-cdk-lib": "^2.251.0",
+    "cdk-nag": "^2.38.2",
+    "constructs": "^10.6.0",
     "eslint": "^9.32.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
@@ -52,7 +53,6 @@
     "nx": "22.1.3",
     "prettier": "^3.6.2",
     "rolldown": "1.0.0-rc.1",
-    "store-parameters": "^1.1.3",
     "tslib": "^2.8.1",
     "tsx": "^4.21.0",
     "typescript": "~5.9.2",
@@ -60,24 +60,7 @@
     "vitest": "^3.2.4"
   },
   "nx": {
-    "includedScripts": [],
-    "targets": {
-      "parameters": {
-        "executor": "nx:run-commands",
-        "options": {
-          "color": true,
-          "cwd": "parameters"
-        },
-        "configurations": {
-          "import": {
-            "command": "store-parameters import {args.file} --delimiter=|"
-          },
-          "export": {
-            "command": "store-parameters export {args.file} --path={args.path} --delimiter=|"
-          }
-        }
-      }
-    }
+    "includedScripts": []
   },
   "workspaces": [
     "application",

package/src/generators/preset/files/.gitignore.template

@@ -43,15 +43,15 @@
 !collection
 !collection/*
 !collection/**/*
+!clients
+!clients/*
+!clients/**/*
 !docs
 !docs/*
 !docs/**/*
 !libs
 !libs/*
 !libs/**/*
-!parameters
-!parameters/*
-!parameters/**/*
 !services
 !services/*
 !services/**/*

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

@@ -53,15 +53,6 @@ yarn install
 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
 
@@ -89,18 +80,7 @@ To add a new service to the monorepo:
     - `services/{service-name}/src/index.ts`
     - `services/{service-name}/src/infra/`
 3. Add Lambda handlers in `services/{service-name}/src/runtime/handlers/`
-
-## Environment Parameters Management
-
-Parameters are managed through the `parameters/{env}.csv` file by default
-
-```bash
-# Import values from `parameters/{env}.csv` to Parameter Store in AWS
-yarn nx run <%= name %>-int:parameters:import --file=dev.csv
-
-# Custom filename and parameter path can be passed in as arguments
-yarn nx run <%= name %>-int:parameters:export --file=dev.csv --path=/my/dev/path
-```
+4. Run `yarn install` again so Yarn Workspace get synced.
 
 ## License
 

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

@@ -6,11 +6,21 @@ This application manages the deployment of microservices and their shared infras
 
 ### Using yarn script from workspace root (Recommended)
 
+**The `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.
+
 ##### Synthesize
 
 ```bash
 # Synthesize for default environment/stage (dev)
-yarn pg:synth
+yarn pg:synth --args="dev/**"
 
 # Synthesize for a custom environment/stage
 yarn pg:synth --args="plg/** -c environment=plg"
@@ -20,7 +30,7 @@ yarn pg:synth --args="plg/** -c environment=plg"
 
 ```bash
 # Deploy for default environment/stage (dev)
-yarn pg:deploy
+yarn pg:deploy --args="dev/**"
 
 # Deploy to a custom environment/stage
 yarn pg:deploy --args="plg/** -c environment=plg"
@@ -30,20 +40,20 @@ yarn pg:deploy --args="plg/** -c environment=plg"
 
 ```bash
 # Diff checking for default environment/stage (dev)
-yarn pg:diff
+yarn pg:diff --args="dev/**"
 
 # Diff checking for a custom environment/stage
-yarn pg:diff --args="-c environment=plg"
+yarn pg:diff --args="plg/** -c environment=plg"
 ```
 
 ##### Destroy
 
 ```bash
 # Destroy default environment/stage (dev)
-yarn pg:destroy
+yarn pg:destroy --args="dev/**"
 
 # Destroy a custom environment/stage
-yarn pg:destroy --args="-c environment=plg"
+yarn pg:destroy --args="plg/** -c environment=plg"
 ```
 
 ### Direct Nx Commands

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

@@ -1,20 +1,12 @@
 import { Stack, Stage, StackProps, Tags } from 'aws-cdk-lib';
-import { Secret } from 'aws-cdk-lib/aws-secretsmanager';
-import { IStringParameter, StringParameter } from 'aws-cdk-lib/aws-ssm';
 import { Construct } from 'constructs';
 
-// EXAMPLE ONLY: The following interface, class, and all related resource references
-// (eCommerceBaseUrl, eCommerceCredentials, etc.) are illustrative examples.
-// Replace them with your own resources and props that match your actual infrastructure.
 export interface SharedInfraProps {
-    // eCommerceBaseUrl: IStringParameter;
-    // eCommerceCredentials: Secret;
+    // TODO: Add shared infrastructure properties (e.g. SSM parameters, secrets)
 }
 
 export class SharedInfraStack extends Stack {
-    // EXAMPLE: Replace these properties with your own shared resources
-    // readonly eCommerceBaseUrl: IStringParameter;
-    // readonly eCommerceCredentials: Secret;
+    // TODO: Add readonly properties for shared resources
 
     constructor(scope: Construct, id: string, props?: StackProps) {
         super(scope, id, props);
@@ -24,25 +16,9 @@ export class SharedInfraStack extends Stack {
         }
 
         Tags.of(this).add('SERVICE', id);
-
-        // EXAMPLE: Replace with your own SSM parameter lookup
-        // this.eCommerceBaseUrl = StringParameter.fromStringParameterName(
-        //     this,
-        //     'ECommerceBaseUrl',
-        //     `/e-commerce/base-url`
-        // );
-
-        // EXAMPLE: Replace with your own secrets/resources
-        // this.eCommerceCredentials = new Secret(this, 'ECommerceCredentials', {
-        //     description: 'E-Commerce API credentials shared across services',
-        // });
     }
 
-    // EXAMPLE: Update getProps() to return your own resource props
     getProps(): SharedInfraProps {
-        return {
-            // eCommerceBaseUrl: this.eCommerceBaseUrl,
-            // eCommerceCredentials: this.eCommerceCredentials,
-        };
+        return {};
     }
 }

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

@@ -0,0 +1,49 @@
+import { Stack, Stage, StackProps, Tags } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { Secret } from 'aws-cdk-lib/aws-secretsmanager';
+import { IStringParameter, StringParameter } from 'aws-cdk-lib/aws-ssm';
+
+export interface SharedInfraProps {
+    paramExample: IStringParameter;
+    secretExample: Secret;
+}
+
+export class SharedInfraStack extends Stack {
+    readonly paramExample: IStringParameter;
+    readonly secretExample: Secret;
+
+    constructor(scope: Construct, id: string, props?: StackProps) {
+        super(scope, id, props);
+
+        if (!Stage.of(this)?.stageName) {
+            throw new Error('This construct must be used within a CDK Stage');
+        }
+
+        Tags.of(this).add('SERVICE', id);
+
+        this.paramExample = new StringParameter(this,'ParamExample',
+        {
+            parameterName: `/example/param`,
+            stringValue: 'example-value'
+        }
+        );
+
+        this.secretExample = new Secret(this, 'SecretExample', {
+            description: 'Example secret shared across services',
+            generateSecretString: {
+                secretStringTemplate: JSON.stringify({
+                    username: 'placeholder',
+                    password: 'placeholder',
+                }),
+                generateStringKey: '_generatedKey',
+            },
+        });
+    }
+
+    getProps(): SharedInfraProps {
+        return {
+            paramExample: this.paramExample,
+            secretExample: this.secretExample,
+        };
+    }
+}

package/src/generators/preset/preset.js

@@ -10,13 +10,17 @@ async function presetGenerator(tree, options) {
     const [nodeVersionMajor] = nodeVersion.split('.');
     const nameParts = (0, utilities_1.splitInputName)(name);
     const projectName = nameParts.join(' ');
-    (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files'), '.', {
+    const templateVars = {
         ...options,
         projectName,
         folderName: destination || name,
         nodeRuntime: `${nodeVersionMajor}_X`,
         template: '',
-    });
+    };
+    (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files'), '.', templateVars);
+    if (options.example) {
+        (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files-example'), '.', templateVars);
+    }
     (0, devkit_1.updateNxJson)(tree, { ...nxJson_1.NX_JSON });
     const packageJson = (0, utilities_1.constructPackageJsonFile)({
         name: options.name,

package/src/generators/preset/schema.d.ts

@@ -2,6 +2,6 @@
 export interface PresetGeneratorSchema {
     name: string;
     nodeVersion: string;
-    // FIXME: [MI-281] Add this into schema.json once we move to our own cli tool
     destination?: string;
+    example?: boolean;
 }

package/src/generators/preset/schema.json

@@ -26,6 +26,18 @@
             "x-prompt": "What is the target Node.js version the project?",
             "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
             "patternErrorMessage": "Node.js version must be a valid semantic version (semver), e.g. 22.10.0 or 24.10.0"
+        },
+        "destination": {
+            "type": "string",
+            "description": "The destination directory for the generated workspace",
+            "pattern": "^[a-zA-Z0-9_./-]+$",
+            "patternErrorMessage": "Destination must be a valid path containing only alphanumeric characters, dashes, underscores, dots, and slashes"
+        },
+        "example": {
+            "type": "boolean",
+            "description": "Generate example code with sample resources",
+            "default": false,
+            "x-prompt": "Would you like to generate example code with sample resources?"
         }
     },
     "required": ["name"]

package/src/generators/service/files/src/index.ts.template

@@ -1,8 +1,6 @@
 import { SharedInfraProps } from '@libs/infra';
 import { Stack, StackProps, Stage, Tags } from 'aws-cdk-lib';
-import { Code } from 'aws-cdk-lib/aws-lambda';
 import { Construct } from 'constructs';
-import path from 'node:path';
 
 /**
 * @important
@@ -22,9 +20,20 @@ interface Props extends StackProps, SharedInfraProps {
 /**
  * Entrypoint for the <%= name %> service
  *
- * Instantiate in a CDK Application Stage to deploy to AWS.
+ * @note Aligent provides the following standard CDK constructs:
+ * - {@link NodejsFunctionFromEntry} from '@aligent/cdk-nodejs-function-from-entry'
+ * - {@link StepFunctionFromFile} from '@aligent/cdk-step-function-from-file'
  *
- * Use 'resolve' helpers below when referencing lambda handlers, step function files etc.
+ * @example
+ * new NodejsFunctionFromEntry(this, 'ExampleLambda', {
+ *     baseDir: import.meta.dirname,
+ *     entry: 'runtime/handlers/example.ts',
+ * });
+ *
+ * new StepFunctionFromFile(this, 'ExampleStepFunction', {
+ *     baseDir: import.meta.dirname,
+ *     filepath: 'infra/stepfunctions/example.yml',
+ * });
  */
 export class <%= stack %> extends Stack {
     constructor(scope: Construct, id: Id, props: Props) {
@@ -37,39 +46,3 @@ export class <%= stack %> extends Stack {
         Tags.of(this).add('SERVICE', id);
     }
 }
-
-/**
- * Resolves a path to infra assets relative to this stack
- *
- * @param assetPath - The path to the asset.
- * @returns The resolved path.
- */
-export function resolveAssetPath(assetPath: `${'infra/'}${string}`) {
-    return path.resolve(import.meta.dirname, assetPath);
-}
-
-/**
- * Return an object with the default bundled code asset and
- * handler property for use with the NodejsFunction construct.
- *
- * @example
- * ```ts
- * new NodejsFunction(this, 'FetchData', {
- *     ...resolveLambdaHandler('runtime/handlers/fetch-data.ts'),
- * });
- * ```
- *
- * @param assetPath - The path to the typescript handler file.
- * @returns The resolved bundled code path and handler name.
- */
-export function resolveLambdaHandler(assetPath: `${'runtime/handlers/'}${string}${'.ts'}`) {
-    // Replace 'runtime/handlers/' with '..dist/' and remove the file extension
-    const bundledPath = assetPath.replace(
-        /^runtime\/handlers\/(?<path>.*)\.ts$/,
-        '../dist/$<path>'
-    );
-    return {
-        code: Code.fromAsset(path.resolve(import.meta.dirname, bundledPath)),
-        handler: 'index.handler',
-    };
-}

package/src/generators/service/files-example/src/index.ts.template

@@ -0,0 +1,45 @@
+import { SharedInfraProps } from '@libs/infra';
+import { Stack, StackProps, Stage, Tags } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { NodejsFunctionFromEntry } from '@aligent/cdk-nodejs-function-from-entry';
+import { StepFunctionFromFile } from '@aligent/cdk-step-function-from-file';
+
+/**
+* @important
+* Due to the immutable nature of CloudFormation,
+* CDK will generate new CloudFormation template and deploy if you change stack name
+*/
+export const <%= constant %> = {
+    NAME: '<%= name %>',
+    DESCRIPTION: '<%= name %> service description'
+} as const;
+
+type Id = typeof <%= constant %>.NAME | (string & {});
+interface Props extends StackProps, SharedInfraProps {
+    description: string;
+}
+
+/**
+ * Entrypoint for the <%= name %> service
+ */
+export class <%= stack %> extends Stack {
+    constructor(scope: Construct, id: Id, props: Props) {
+        super(scope, id, props);
+
+        if (!Stage.of(this)?.stageName) {
+            throw new Error('This construct must be used within a CDK Stage');
+        }
+
+        Tags.of(this).add('SERVICE', id);
+
+        new NodejsFunctionFromEntry(this, 'ExampleLambda', {
+            baseDir: import.meta.dirname,
+            entry: 'runtime/handlers/example.ts',
+        });
+
+        new StepFunctionFromFile(this, 'ExampleStepFunction', {
+            baseDir: import.meta.dirname,
+            filepath: 'infra/stepfunctions/example.yml',
+        });
+    }
+}

package/src/generators/service/files-example/src/infra/stepfunctions/example.yml.template

@@ -0,0 +1,7 @@
+Comment: Example Step Function for <%= name %>
+StartAt: Hello
+States:
+  Hello:
+    Type: Pass
+    Result: Hello from <%= name %>
+    End: true

package/src/generators/service/files-example/src/runtime/handlers/example.ts.template

@@ -0,0 +1,7 @@
+import type { Handler } from 'aws-lambda';
+
+export const handler: Handler = async (event) => {
+    // TODO: Implement your handler logic here
+
+    return;
+};

package/src/generators/service/generator.js

@@ -23,13 +23,17 @@ async function serviceGenerator(tree, options) {
     if (!tree.exists(SERVICES_FOLDER)) {
         tree.write(`${SERVICES_FOLDER}/.gitkeep`, '');
     }
-    (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files'), projectRoot, {
+    const templateVars = {
         ...options,
         serviceName: nameParts.join(' '),
         constant,
         stack,
         template: '',
-    });
+    };
+    (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files'), projectRoot, templateVars);
+    if (options.example) {
+        (0, devkit_1.generateFiles)(tree, (0, path_1.join)(__dirname, 'files-example'), projectRoot, templateVars);
+    }
     // Generate service's tsconfigs
     const { tsConfig, tsConfigLib, tsConfigSpec } = (0, utilities_1.constructProjectTsConfigFiles)('service');
     (0, devkit_1.writeJson)(tree, `${projectRoot}/tsconfig.json`, tsConfig);

package/src/generators/service/schema.d.ts

@@ -1,4 +1,5 @@
 /* v8 ignore start */
 export interface ServiceGeneratorSchema {
     name: string;
+    example?: boolean;
 }

package/src/generators/service/schema.json

@@ -14,6 +14,12 @@
             "x-prompt": "What is the name of the service?",
             "pattern": "^(?!.*[Ss]tack|.*[Ss]ervice).*$",
             "patternErrorMessage": "Service name cannot contain '[Ss]tack' or '[Ss]ervice'"
+        },
+        "example": {
+            "type": "boolean",
+            "description": "Generate example code with sample resources",
+            "default": false,
+            "x-prompt": "Would you like to generate example code with sample resources?"
         }
     },
     "required": ["name"]

package/src/generators/preset/files/.github/dependabot.yml.template

@@ -1,7 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: 'npm'
-    directory: '/'
-    schedule:
-      interval: 'monthly'
-    open-pull-requests-limit: 10

package/src/generators/preset/files/parameters/dev.csv.template

@@ -1,2 +0,0 @@
-Note|Name|Type|Value
-Collect from eCommerce|/<%= name %>-int/e-commerce/base-url|String|https://e-commerce.com/dev/api