@aligent/nx-cdk 0.0.1

package/src/generators/preset/files/.git-hooks/pre-push.template

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Script adapted from https://github.com/kaczor6418/git-hooks-example/blob/master/git-hooks/pre-commit
+
+# Support using VSCode to commit
+# This loads nvm.sh and sets the correct PATH before running hook
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+
+# Define colours for nicer CLI output
+RED="\033[1;31m"
+GREEN="\033[1;32m"
+NO_COLOUR="\033[0m"
+
+echo -e "${GREEN}Executing git hook $0 $@${NO_COLOUR}"
+
+# Use the current Node version explicitly
+nvm use
+
+# Get the list of staged changes
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+# Exclude files that shouldn't trigger pre-commit checks
+# This is done here because `nx affected` doesn't look at task inputs
+# when determining if a project is affected
+EXCLUDED_FILES_REGEX='.*\.md$' # Ignore markdown files
+EXCLUDED_FILES_REGEX+='|.*\/step-functions\/.*\.(yml|yaml)$' # Ignore step function yaml files
+EXCLUDED_FILES_REGEX+='|^\/?([^\/]*)$' # Ignore all root-level files
+AFFECTED_FILES=$(echo "$STAGED_FILES" | \
+  grep -vE "$EXCLUDED_FILES_REGEX" | \
+  paste -sd,)
+
+echo -e "${GREEN}\nAffected files: $AFFECTED_FILES\n${NO_COLOUR}"
+
+# Exit early if there are no affected files
+if [ -z "$AFFECTED_FILES" ]; then
+  echo -e "${GREEN}No affected files found. Exiting pre-commit hook.${NO_COLOUR}"
+  exit 0
+fi
+
+# Prepare the affected commands for static analysis targets
+AFFECTED_COMMAND="yarn nx affected --files=$AFFECTED_FILES --nxBail --tui=false"
+commands=("$AFFECTED_COMMAND -t lint typecheck --parallel=3", "$AFFECTED_COMMAND -t test --configuration coverage")
+failures=()
+
+# Loop over commands, execute and push failure message if we see one
+for cmd in "${commands[@]}"; do
+  $cmd
+  exit_code=$?
+
+  if [ "$exit_code" -eq 1 ]; then
+    failures+=("✖ Command ${RED}'${cmd}'${NO_COLOUR} failed with exit code ${exit_code} - see CLI output for errors")
+  elif [ "$exit_code" -eq 127 ]; then
+    failures+=("✖ Command ${RED}'${cmd}'${NO_COLOUR} failed with exit code ${exit_code} - check that the script exists in package.json")
+  elif [ "$exit_code" -ne 0 ]; then
+    failures+=("✖ Command ${RED}'${cmd}'${NO_COLOUR} failed with unexpected exit code ${exit_code}")
+  fi
+done
+
+# Report overall success or failure
+if [ ${#failures[@]} -ne 0 ]; then
+  echo -e "\n🚩${RED} Couldn't commit changes dues to the following errors: ${NO_COLOUR}"
+
+  for report in "${failures[@]}"; do
+    echo -e $report;
+  done
+
+  exit 1
+fi

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

@@ -0,0 +1,3 @@
+# 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

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

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

package/src/generators/preset/files/.github/workflows/ci-cd.yml.template

@@ -0,0 +1,27 @@
+name: CI/CD Pipeline
+
+on:
+  pull_request:
+    branches:
+      - '**'
+  push:
+    branches:
+      - staging
+      - production
+
+jobs:
+  code-quality:
+    name: 🕵️‍♀️ Code Quality Check
+    uses: aligent/workflows/.github/workflows/node-pr.yml@main
+    with:
+      skip-format: false
+
+  deploy:
+    name: Deploy to AWS
+    uses: aligent/workflows/.github/workflows/aws-cdk-deploy.yml@main
+    with:
+      cdk-stack-name: ${{ vars.STACK_NAME }}
+      aws-access-key-id: ${{ vars.AWS_ACCESS_KEY_ID }}
+      deploy: true
+    secrets:
+      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

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

@@ -0,0 +1,62 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+# Ignore everything by default
+*
+
+# Project standard configurations
+!**/*.md
+!.git-hooks
+!.git-hooks/*
+!.github
+!.github/*
+!.github/**/*
+!.editorconfig
+!.gitignore
+!.nvmrc
+!.prettierignore
+!cdk-config.yml
+!eslint.config.mjs
+!LICENSE
+!nx.json
+!package.json
+!prettier.config.mjs
+!rolldown.config.base.mjs
+!tsconfig.json
+!vitest.global.setup.mjs
+!vitest.config.base.mjs
+
+# Package manager
+!.yarn
+!.yarn/patches
+!.yarn/plugins
+!.yarn/plugins/*
+!.yarn/plugins/**/*
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+!.yarnrc.yml
+!yarn.lock
+
+# Application
+!application
+!application/*
+!application/**/*
+!collection
+!collection/*
+!collection/**/*
+!docs
+!docs/*
+!docs/**/*
+!libs
+!libs/*
+!libs/**/*
+!services
+!services/*
+!services/**/*
+
+# Test and bundle artifacts
+**/cdk.out
+**/dist
+**/coverage
+
+# Environment files
+*.env

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

@@ -0,0 +1 @@
+v<%= nodeVersion %>

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

@@ -0,0 +1,10 @@
+# Add files here to ignore them from prettier formatting
+
+# Build and test artifacts
+**/dist
+**/coverage
+
+# Tools, misc and autogenerated files
+.nx
+**/tsconfig.*
+yarn.lock

package/src/generators/preset/files/.yarnrc.yml.template

@@ -0,0 +1,6 @@
+nodeLinker: node-modules
+
+plugins:
+  - checksum: e5e6e2885ab0e6521b70b0af7c6d8ca2c75dcae2403706fc4600a783b339a6530a476dafb9450c9436ca4050eb6bdee9b62e6e2cebfecf1e81dd709a2480dc07
+    path: .yarn/plugins/@yarnpkg/plugin-engines.cjs
+    spec: 'https://raw.githubusercontent.com/devoto13/yarn-plugin-engines/main/bundles/%40yarnpkg/plugin-engines.js'

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

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Aligent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,77 @@
+# <%= projectName %> Integrations
+
+A monorepo containing integration services that support the <%= projectName %> project. This repository manages the deployment of microservices and their shared infrastructure using AWS CDK.
+
+## Overview
+
+<!-- Add an overview of the whole system -->
+
+## Services
+
+Services deployment are managed by the main [CDK Application](./application/README.md)
+
+<!-- List services here with link to the service read me file -->
+<!-- Eg: [User Management](../services/user-management/README.md) -->
+
+## Project Structure
+
+```
+<%= folderName %>/
+├── application/              # CDK Application & orchestration
+│   ├── bin/main.ts           # CDK App entry point (development/staging/production stages)
+│   ├── lib/                  # Service stack composition
+│   └── cdk.json              # CDK configuration
+│
+├── services/                 # Microservices workspace
+│
+├── nx.json                   # Nx monorepo configuration
+├── rolldown.config.base.mjs  # Base Lambda bundling config
+├── vitest.config.base.mjs    # Base test configuration
+└── eslint.config.mjs         # ESLint configuration
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js <%= nodeVersion %> (see [.nvmrc](.nvmrc))
+- Yarn 4.12.0+
+- AWS CLI configured with appropriate credentials
+
+### Installation
+
+```bash
+# Use correct Node version
+nvm use
+
+# Install dependencies
+yarn install
+```
+
+## Contributing
+
+We follow [trunk-based development framework](https://trunkbaseddevelopment.com/) as a start and will evolve depending on our need.
+
+1. Create new branch from `main`
+2. Make your changes following code standards
+3. Ensure your changes pass linting, type checks and testes
+4. Submit a pull request back to `main`
+5. For deployment, submit a pull request from `main` to `staging` or `production`
+
+## Adding New Services
+
+To add a new service to the monorepo:
+
+1. Use the Aligent CDK generator `@aligent/nx-cdk`
+2. Add service infrastructure in
+    - `services/{service-name}/src/index.ts`
+    - `services/{service-name}/src/infra/`
+3. Add Lambda handlers in `services/{service-name}/src/runtime/handlers/`
+
+## License
+
+MIT
+
+## Support
+
+For questions or issues, please contact the Aligent Microservices guild.

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

@@ -0,0 +1,61 @@
+# Application
+
+This application manages the deployment of microservices and their shared infrastructure.
+
+## Configuration
+
+### Environment Parameters
+
+Parameters are managed through the `parameters/.env.csv` file by default
+
+```bash
+# Pull down parameters from the playground environment to .env.csv
+yarn nx run application:parameters
+
+# Update parameters from .env.csv
+yarn nx run application:parameters:import
+
+# Custom filename and parameter path can be passed in as arguments
+yarn nx run application:parameters --file .env.dev.csv --path /my/dev/path
+```
+
+## Deployment
+
+### Using yarn script from workspace root (Recommended)
+
+```bash
+# Synthesize templates
+yarn pg:synth
+
+# Deploy to playground
+yarn pg:deploy
+```
+
+### Direct Nx Commands
+
+```bash
+yarn nx run application:cdk <command> <args>
+```
+
+## Testing
+
+### Mock Services
+
+The application may include mock services for testing integrations without external dependencies.
+
+<!-- list mock services here -->
+
+Change the value of the `/application/dev/url` SSM Parameter to switch between real and mock endpoints
+
+### Local Development
+
+```bash
+# Type checking
+yarn typecheck
+
+# Testing
+yarn test
+
+# Linting
+yarn lint
+```

package/src/generators/preset/files/application/_internal/log-group-defaults-injector.ts.template

@@ -0,0 +1,100 @@
+import { RemovalPolicy, type IPropertyInjector } from 'aws-cdk-lib';
+import { LogGroup, RetentionDays, type LogGroupProps } from 'aws-cdk-lib/aws-logs';
+
+interface Config {
+    duration: 'SHORT' | 'MEDIUM' | 'LONG';
+}
+
+/**
+ * Property injector for CloudWatch Log Groups with configuration-aware defaults
+ *
+ * Applies configuration-specific retention policies and removal settings to log groups.
+ * Different configurations balance between cost optimization and data retention needs.
+ *
+ * @example
+ * ```typescript
+ * // Apply configuration-specific defaults
+ * PropertyInjectors.of(scope).add(
+ *   new LogGroupDefaultsInjector({ duration: 'SHORT' }).withProps({
+ *     logGroupName: '/custom/log/group',
+ *   })
+ * );
+ *
+ * // Log groups automatically inherit configuration defaults
+ * new LogGroup(stack, 'MyLogGroup', {
+ *   // retention and removal policy applied automatically
+ * });
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_logs.LogGroup.html
+ */
+export class LogGroupDefaultsInjector implements IPropertyInjector {
+    readonly constructUniqueId = LogGroup.PROPERTY_INJECTION_ID;
+    private readonly config: Config;
+    private defaultProps: LogGroupProps;
+
+    /**
+     * Creates a new LogGroupDefaultsInjector
+     *
+     * @param config - Configuration identifier used to select appropriate defaults.
+     */
+    constructor(config: Config) {
+        const props = retentionProperties(config.duration);
+        this.config = { ...config };
+        this.defaultProps = { ...props };
+    }
+
+    /**
+     * Creates a new injector instance with additional properties
+     *
+     * Returns a new injector that inherits the current configuration but includes
+     * additional properties that override the configuration defaults.
+     *
+     * @param props - Additional properties to merge with configuration defaults
+     * @returns A new injector instance with merged properties
+     *
+     * @example
+     * ```typescript
+     * const customInjector = new LogGroupDefaultsInjector({ duration: 'SHORT' })
+     *   .withProps({
+     *     logGroupName: '/aws/lambda/custom',
+     *     retention: RetentionDays.ONE_MONTH,
+     *   });
+     * ```
+     */
+    public withProps(props: LogGroupProps) {
+        const modifiedInjector = new LogGroupDefaultsInjector(this.config);
+        modifiedInjector.defaultProps = { ...this.defaultProps, ...props };
+        return modifiedInjector;
+    }
+
+    /**
+     * Injects configuration-appropriate defaults into log group properties
+     *
+     * Merges configuration-specific retention and removal policies with user-provided properties.
+     *
+     * @param originalProps - Properties provided when creating the log group
+     * @param context - CDK injection context containing construct information
+     * @returns Merged properties with injected defaults
+     */
+    public inject(originalProps: LogGroupProps) {
+        return { ...this.defaultProps, ...originalProps };
+    }
+}
+
+/**
+ * Get duration-specific log group properties
+ *
+ * @param duration - The duration to get the log group properties for
+ * @returns The log group properties for the duration
+ */
+function retentionProperties(duration: 'SHORT' | 'MEDIUM' | 'LONG') {
+    switch (duration) {
+        case 'SHORT':
+            return { retention: RetentionDays.ONE_WEEK, removalPolicy: RemovalPolicy.DESTROY };
+        case 'MEDIUM':
+            return { retention: RetentionDays.SIX_MONTHS, removalPolicy: RemovalPolicy.DESTROY };
+        default:
+            return { retention: RetentionDays.TWO_YEARS, removalPolicy: RemovalPolicy.RETAIN };
+    }
+}

package/src/generators/preset/files/application/_internal/microservice-checks.ts.template

@@ -0,0 +1,58 @@
+import { CfnResource } from 'aws-cdk-lib';
+import { NagMessageLevel, NagPack, rules, type NagPackProps } from 'cdk-nag';
+import type { IConstruct } from 'constructs';
+
+/**
+ * Microservice Checks are a compilation of rules to validate infrastructure-as-code template
+ * against recommended practices using the cdk-nag library.
+ *
+ * @see https://github.com/cdk-patterns/cdk-nag/
+ *
+ * @example
+ * const app = new App();
+ * const stack = new Stack(app, 'MyStack');
+ * Aspects.of(stack).add(new MicroservicesChecks());
+ */
+export class MicroserviceChecks extends NagPack {
+    constructor(props?: NagPackProps) {
+        super(props);
+        this.packName = 'Microservices';
+    }
+
+    public visit(node: IConstruct) {
+        if (node instanceof CfnResource) {
+            this.applyRule({
+                info: 'The Lambda function does not have an explicit memory value configured.',
+                explanation:
+                    "Lambda allocates CPU power in proportion to the amount of memory configured. By default, your functions have 128 MB of memory allocated. You can increase that value up to 10 GB. With more CPU resources, your Lambda function's duration might decrease.  You can use tools such as AWS Lambda Power Tuning to test your function at different memory settings to find the one that matches your cost and performance requirements the best.",
+                level: NagMessageLevel.ERROR,
+                rule: rules.lambda.LambdaDefaultMemorySize,
+                node: node,
+            });
+            this.applyRule({
+                info: 'The Lambda function does not have an explicitly defined timeout value.',
+                explanation:
+                    'Lambda functions have a default timeout of 3 seconds. If your timeout value is too short, Lambda might terminate invocations prematurely. On the other side, setting the timeout much higher than the average execution may cause functions to execute for longer upon code malfunction, resulting in higher costs and possibly reaching concurrency limits depending on how such functions are invoked. You can also use AWS Lambda Power Tuning to test your function at different timeout settings to find the one that matches your cost and performance requirements the best.',
+                level: NagMessageLevel.ERROR,
+                rule: rules.lambda.LambdaDefaultTimeout,
+                node: node,
+            });
+            this.applyRule({
+                info: 'The Lambda function does not have tracing set to Tracing.ACTIVE.',
+                explanation:
+                    'When a Lambda function has ACTIVE tracing, Lambda automatically samples invocation requests, based on the sampling algorithm specified by X-Ray.',
+                level: NagMessageLevel.ERROR,
+                rule: rules.lambda.LambdaTracing,
+                node: node,
+            });
+            this.applyRule({
+                info: 'The CloudWatch Log Group does not have an explicit retention policy defined.',
+                explanation:
+                    'By default, logs are kept indefinitely and never expire. You can adjust the retention policy for each log group, keeping the indefinite retention, or choosing a retention period between one day and 10 years. For Lambda functions, this applies to their automatically created CloudWatch Log Groups.',
+                level: NagMessageLevel.ERROR,
+                rule: rules.cloudwatch.CloudWatchLogGroupRetentionPeriod,
+                node: node,
+            });
+        }
+    }
+}

package/src/generators/preset/files/application/_internal/nodejs-function-defaults-injector.ts.template

@@ -0,0 +1,110 @@
+import { type IPropertyInjector } from 'aws-cdk-lib';
+import { Runtime, Tracing } from 'aws-cdk-lib/aws-lambda';
+import { NodejsFunction, type NodejsFunctionProps } from 'aws-cdk-lib/aws-lambda-nodejs';
+
+interface Config {
+    runtime: Runtime;
+    sourceMap?: boolean;
+}
+
+/**
+ * Property injector for Node.js Lambda functions with configuration-aware defaults
+ *
+ * Applies configuration-specific bundling and runtime settings to Lambda functions.
+ * Different configurations can optimize for different priorities such as build speed,
+ * bundle size, or debugging capabilities.
+ *
+ * @example
+ * ```typescript
+ * // Apply configuration-specific defaults
+ * PropertyInjectors.of(scope).add(
+ *   new NodeJsFunctionDefaultsInjector({
+ *     sourceMaps: true,
+ *     esm: true,
+ *     minify: true,
+ *   }).withProps({
+ *     timeout: Duration.seconds(30),
+ *     memorySize: 256,
+ *   })
+ * );
+ *
+ * // Functions automatically inherit configuration defaults
+ * new Function(stack, 'MyFunction', {
+ *   code: Code.fromAsset('src/lambda'),
+ *   handler: 'index.handler',
+ *   // bundling and runtime config applied automatically
+ * });
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.NodejsFunction.html
+ */
+export class NodeJsFunctionDefaultsInjector implements IPropertyInjector {
+    public readonly constructUniqueId = NodejsFunction.PROPERTY_INJECTION_ID;
+    private readonly config: Required<Config>;
+    private defaultProps: NodejsFunctionProps;
+
+    /**
+     * Creates a new NodeJsFunctionDefaultsInjector
+     *
+     * @param config - Configuration identifier used to select appropriate defaults. Uses production defaults if not specified.
+     */
+    constructor(config: Config) {
+        this.config = { ...config, sourceMap: config.sourceMap || true };
+        this.defaultProps = { runtime: config.runtime, tracing: Tracing.ACTIVE };
+    }
+
+    /**
+     * Creates a new injector instance with additional properties
+     *
+     * Returns a new injector that inherits the current configuration but includes
+     * additional properties that override the configuration defaults.
+     *
+     * @param props - Additional properties to merge with configuration defaults
+     * @returns A new injector instance with merged properties
+     *
+     * @example
+     * ```typescript
+     * const customInjector = new NodeJsFunctionDefaultsInjector({
+     *   sourceMaps: false,
+     * })
+     *   .withProps({
+     *     timeout: Duration.minutes(5),
+     *     memorySize: 1024,
+     *   });
+     * ```
+     *
+     * TODO: Provide a nice way to inherit global properties from previous injectors
+     */
+    public withProps(props: NodejsFunctionProps) {
+        const modifiedInjector = new NodeJsFunctionDefaultsInjector(this.config);
+        modifiedInjector.defaultProps = { ...this.defaultProps, ...props };
+        return modifiedInjector;
+    }
+
+    /**
+     * Injects configuration-appropriate defaults into Lambda function properties
+     *
+     * Merges configuration-specific defaults with user-provided properties,
+     * automatically configuring bundling options and runtime settings.
+     *
+     * @param originalProps - Properties provided when creating the function
+     * @returns Merged properties with injected defaults
+     */
+    public inject(originalProps: NodejsFunctionProps) {
+        // The NodeJsFunction constructor pre-sets runtime to 16.x or LATEST depending on feature flags
+        // We assume that using this injector means you want to standardise the runtime across all lambdas
+        const props = {
+            ...this.defaultProps,
+            ...originalProps,
+            runtime: this.defaultProps.runtime,
+        };
+
+        // If source maps are enabled in our bundling, add the required NODE_OPTIONS flag to the environment
+        const environment = {
+            ...props.environment,
+            ...(this.config.sourceMap ? { NODE_OPTIONS: '--enable-source-maps' } : {}),
+        };
+
+        return { ...props, environment };
+    }
+}