@aligent/nx-cdk 0.0.1 → 0.1.0

package/src/generators/preset/files/application/_internal/step-function-defaults-aspect.ts.template

@@ -0,0 +1,83 @@
+import { type IAspect } from 'aws-cdk-lib';
+import { CfnLogGroup, LogGroup } from 'aws-cdk-lib/aws-logs';
+import {
+    CfnStateMachine,
+    LogLevel,
+    StateMachine,
+    StateMachineType,
+} from 'aws-cdk-lib/aws-stepfunctions';
+import { IConstruct } from 'constructs';
+
+/**
+ * Aspect that automatically applies tracing and logging settings to Step Functions
+ *
+ * Visits all constructs in the scope and automatically applies X-Ray tracing to all
+ * state machines. For EXPRESS state machines, automatically creates log groups and
+ * configures comprehensive logging for enhanced observability.
+ *
+ * @example
+ * ```typescript
+ * // Apply configuration-specific defaults to all Step Functions
+ * Aspects.of(app).add(new StepFunctionDefaultsAspect());
+ *
+ * // Step Functions automatically inherit defaults
+ * new StateMachine(stack, 'MyWorkflow', {
+ *   stateMachineType: StateMachineType.EXPRESS,
+ *   definitionBody: DefinitionBody.fromFile('workflow.asl.yaml'),
+ *   // tracing enabled and logging configured automatically for EXPRESS
+ * });
+ * ```
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_stepfunctions.StateMachine.html
+ */
+export class StepFunctionDefaultsAspect implements IAspect {
+    /**
+     * Visits a construct and applies tracing and logging settings if it's a StateMachine
+     *
+     * Enables X-Ray tracing for all state machines. For EXPRESS state machines that don't
+     * already have logging configured, automatically creates log groups and configures
+     * comprehensive logging with full execution data capture.
+     *
+     * @param node - The construct to potentially modify
+     */
+    visit(node: IConstruct): void {
+        if (node instanceof StateMachine) {
+            const cfnStateMachine = node.node.defaultChild as CfnStateMachine;
+
+            if (cfnStateMachine) {
+                // Apply tracing if not already set
+                if (cfnStateMachine.tracingConfiguration === undefined) {
+                    cfnStateMachine.tracingConfiguration = {
+                        enabled: true,
+                    };
+                }
+
+                // For EXPRESS state machines, configure logging if not already set
+                if (
+                    cfnStateMachine.stateMachineType === StateMachineType.EXPRESS &&
+                    cfnStateMachine.loggingConfiguration === undefined
+                ) {
+                    // Create a log group for the state machine
+                    const logGroup = new LogGroup(node, 'LogGroup', {
+                        logGroupName: `/aws/vendedlogs/states/${node.node.id}`,
+                    });
+
+                    // Get the underlying CFN log group to access its ARN
+                    const cfnLogGroup = logGroup.node.defaultChild as CfnLogGroup;
+
+                    cfnStateMachine.loggingConfiguration = {
+                        destinations: [
+                            {
+                                cloudWatchLogsLogGroup: {
+                                    logGroupArn: cfnLogGroup.attrArn,
+                                },
+                            },
+                        ],
+                        level: LogLevel.ALL,
+                        includeExecutionData: true,
+                    };
+                }
+            }
+        }
+    }
+}

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

@@ -1,30 +1,32 @@
 #!/usr/bin/env node
+import { MicroserviceChecks, VersionFunctionsAspect } from '@aligent/cdk-aspects';
 import { App, Aspects, Tags } from 'aws-cdk-lib';
 import { Runtime } from 'aws-cdk-lib/aws-lambda';
 import { ApplicationStage } from '../lib/service-stacks.js';
 
-// TODO [MI-277] Pull this out to constructs repo so we can import and use later
-import { LogGroupDefaultsInjector } from '../_internal/log-group-defaults-injector.js';
-import { MicroserviceChecks } from '../_internal/microservice-checks.js';
-import { NodeJsFunctionDefaultsInjector } from '../_internal/nodejs-function-defaults-injector.js';
-import { StepFunctionDefaultsInjector } from '../_internal/step-function-defaults-injector.ts';
-import { VersionFunctionsAspect } from '../_internal/version-functions-aspect.js';
+// TODO: [MI-277] Move these aspects to @aligent/cdk-aspects package for reuse across projects
+import { LogGroupDefaultsAspect } from '../_internal/log-group-defaults-aspect.js';
+import { NodeJsFunctionDefaultsAspect } from '../_internal/nodejs-function-defaults-aspect.js';
+import { StepFunctionDefaultsAspect } from '../_internal/step-function-defaults-aspect.js';
 
-const APPLICATION_CONTEXT = { APPLICATION_OWNER: 'aligent' } as const;
+const APPLICATION_CONTEXT = { NAME: '<%= name %>-int', OWNER: 'aligent' } as const;
+const STAGE_NAMES = { DEV: 'dev', STG: 'stg', PRD: 'prd' } as const;
 
-const app = new App({
-    context: APPLICATION_CONTEXT,
-    propertyInjectors: [
-        new NodeJsFunctionDefaultsInjector({ runtime: <%= nodeRuntime %> }),
-        new StepFunctionDefaultsInjector(),
-    ],
-});
-Tags.of(app).add('OWNER', APPLICATION_CONTEXT.APPLICATION_OWNER);
+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 StepFunctionDefaultsAspect());
+Aspects.of(app).add(new MicroserviceChecks());
 
 /**
  * Static Stage Creation Approach
  *
- * We use static stage creation (explicitly defining development, staging, production) for several reasons:
+ * We use static stage creation (explicitly defining dev, stg, prd) for several reasons:
  *
  * 1. **Predictability**: All stages are known at synthesis time, making the CDK app
  *    behavior deterministic and easier to reason about.
@@ -33,8 +35,8 @@ Tags.of(app).add('OWNER', APPLICATION_CONTEXT.APPLICATION_OWNER);
  *    and compile-time type checking for stage-specific configurations.
  *
  * 3. **Explicit Configuration**: Each stage's unique settings (e.g., log retention
- *    durations, aspects, property injectors) are clearly visible in the code without
- *    needing to trace through dynamic logic.
+ *    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.
@@ -44,29 +46,23 @@ Tags.of(app).add('OWNER', APPLICATION_CONTEXT.APPLICATION_OWNER);
  *
  * @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 Property Injector Behavior
- * Property injectors are applied based on their class type and will only execute once per
- * construct tree. When the same injector type is defined at both app and stage levels, the
- * stage-level injector takes precedence and overrides the app-level configuration.
+ * @remarks
+ * Aspects visit all constructs in the tree after synthesis and can modify them
+ * (e.g., applying log retention policies, enabling tracing).
  */
-const development = new ApplicationStage(app, 'development', {
-    propertyInjectors: [new LogGroupDefaultsInjector({ duration: 'SHORT' })],
-});
-Aspects.of(development).add(new MicroserviceChecks());
 
-const staging = new ApplicationStage(app, 'staging', {
-    propertyInjectors: [new LogGroupDefaultsInjector({ duration: 'MEDIUM' })],
-});
-Aspects.of(staging).add(new MicroserviceChecks());
+const dev = new ApplicationStage(app, STAGE_NAMES.DEV);
+Aspects.of(dev).add(new LogGroupDefaultsAspect({ duration: 'SHORT' }));
 
-const production = new ApplicationStage(app, 'production', {
-    propertyInjectors: [new LogGroupDefaultsInjector({ duration: 'LONG' })],
-});
-Aspects.of(production).add(new MicroserviceChecks());
+const stg = new ApplicationStage(app, STAGE_NAMES.STG);
+Aspects.of(stg).add(new LogGroupDefaultsAspect({ duration: 'MEDIUM' }));
 
 /**
- * This aspect ensures all Lambda functions and Step Functions in production
- * are automatically versioned and have a stable 'live' alias pointing to the
- * current version, enabling zero-downtime deployments.
+ * 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
  */
-Aspects.of(production).add(new VersionFunctionsAspect());
+const prd = new ApplicationStage(app, STAGE_NAMES.PRD);
+Aspects.of(prd).add(new LogGroupDefaultsAspect({ duration: 'LONG' }));
+Aspects.of(prd).add(new VersionFunctionsAspect());

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

@@ -1,5 +1,5 @@
 {
-    "app": "npx tsx bin/main.ts",
+    "app": "yarn tsx bin/main.ts",
     "watch": {
         "include": ["**"],
         "exclude": [

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

@@ -1,3 +1,4 @@
+import { SharedInfraStack } from '@libs/infra';
 import { Stage, Tags, type StageProps } from 'aws-cdk-lib';
 import type { Construct } from 'constructs';
 
@@ -16,6 +17,8 @@ export class ApplicationStage extends Stage {
         super(scope, id, props);
         Tags.of(this).add('STAGE', id);
 
+        const sharedInfra = new SharedInfraStack(this, 'shared-infra', props);
+
         // Service stacks initialization
     }
 }

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

@@ -15,12 +15,6 @@
           "command": "cdk",
           "cwd": "{projectRoot}"
         }
-      },
-      "parameters": {
-        "executor": "nx:run-commands",
-        "options": {
-          "path": "/application/dev"
-        }
       }
     }
   }

package/src/generators/preset/files/eslint.config.mjs.template

@@ -13,8 +13,7 @@ const eslintBaseConfig = [
             '**/cdk.out',
             '**/dist',
             '**/out-tsc',
-            '**/vite.config.*.timestamp*',
-            '**/vitest.config.*.timestamp*',
+            '**/*.config.*.timestamp*',
         ],
     },
     {

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

@@ -0,0 +1,61 @@
+# @libs/infra
+
+Shared infrastructure library for CDK stacks providing common resources used across multiple services.
+
+## Architecture
+
+This library exports a `SharedInfraStack` that manages shared infrastructure resources, preventing duplication and ensuring consistency across service stacks.
+
+### Shared Resources
+
+This `SharedInfraStack` provides:
+
+<!-- List your shared resources here. For example:
+- **eCommerce Base URL**: Retrieved from SSM Parameter Store (`/{applicationName}/e-commerce/base-url`)
+- **eCommerce Credentials**: Managed secret for API authentication (`{applicationName}/e-commerce-credentials`) 
+-->
+
+### Usage
+
+- Import and instantiate the `SharedInfraStack` in your application stage, then pass the shared resources to service stacks:
+
+```typescript
+import { SharedInfraStack } from '@libs/infra';
+
+const sharedInfra = new SharedInfraStack(this, 'shared-infra', props);
+
+new MyServiceStack(this, 'service-name', {
+  ...props,
+  ...sharedInfra.getProps(),
+  description: 'service description',
+});
+```
+
+- Import and extend your service stack props:
+
+```typescript
+import { SharedInfraProps } from '@libs/infra';
+
+interface Props extends StackProps, SharedInfraProps {
+  description: string;
+}
+```
+
+## Technical Decisions
+
+### Single Shared Stack Pattern
+
+Resources that are used by multiple services are created once in the shared infrastructure stack and passed to service stacks via constructor props. This approach:
+
+- Prevents resource duplication
+- Ensures consistent configuration across services
+- Simplifies resource management and updates
+- Reduces AWS costs by sharing resources
+
+### Stage Requirement
+
+The `SharedInfraStack` must be instantiated within a CDK Stage to properly resolve the stage name for resource naming and tagging.
+
+### Application Context
+
+Requires the `NAME` context variable to be set for proper resource naming conventions.

package/src/generators/preset/files/libs/infra/eslint.config.mjs.template

@@ -0,0 +1,20 @@
+import eslintPluginImport from 'eslint-plugin-import';
+import baseConfig from '../../eslint.config.mjs';
+
+export default [
+    ...baseConfig,
+    {
+        files: ['**/*.ts'],
+        plugins: { import: eslintPluginImport },
+        rules: {
+            'import/no-extraneous-dependencies': [
+                'warn',
+                {
+                    optionalDependencies: false,
+                    peerDependencies: false,
+                    packageDir: ['.', '..', '../..'],
+                },
+            ],
+        },
+    },
+];

package/src/generators/preset/files/libs/infra/package.json.template

@@ -0,0 +1,19 @@
+{
+  "name": "@libs/infra",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "nx": {
+    "tags": [
+      "scope:libs"
+    ]
+  }
+}

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

@@ -0,0 +1,44 @@
+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 type { Construct } from 'constructs';
+
+export interface SharedInfraProps {
+    eCommerceBaseUrl: string;
+    eCommerceCredentials: Secret;
+}
+
+export class SharedInfraStack extends Stack {
+    readonly eCommerceBaseUrl: string;
+    readonly eCommerceCredentials: Secret;
+
+    constructor(scope: Construct, id: string, props?: StackProps) {
+        super(scope, id, props);
+
+        const STAGE = Stage.of(this)?.stageName;
+        if (!STAGE) {
+            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;
+
+        // 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',
+        });
+    }
+
+    getProps(): SharedInfraProps {
+        return {
+            eCommerceBaseUrl: this.eCommerceBaseUrl,
+            eCommerceCredentials: this.eCommerceCredentials,
+        };
+    }
+}

package/src/generators/preset/files/libs/infra/tsconfig.json.template

@@ -0,0 +1,6 @@
+{
+    "extends": "@aligent/ts-code-standards/tsconfigs-extend",
+    "files": [],
+    "include": [],
+    "references": []
+}

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

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

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

@@ -2,5 +2,5 @@
     "extends": "@aligent/ts-code-standards/tsconfigs-extend",
     "compileOnSave": false,
     "files": [],
-    "references": [{"path": "./application"}]
+    "references": [{"path": "./application"}, {"path": "./libs/infra"}]
 }

package/src/generators/preset/preset.js

@@ -14,7 +14,7 @@ async function presetGenerator(tree, options) {
         ...options,
         projectName,
         folderName: destination || name,
-        nodeRuntime: `Runtime.NODEJS_${nodeVersionMajor}_X`,
+        nodeRuntime: `${nodeVersionMajor}_X`,
         template: '',
     });
     (0, devkit_1.updateNxJson)(tree, { ...nxJson_1.NX_JSON });
@@ -26,10 +26,8 @@ async function presetGenerator(tree, options) {
     });
     (0, devkit_1.writeJson)(tree, 'package.json', packageJson);
     // Generate application's tsconfigs
-    const { tsConfig, tsConfigLib, tsConfigSpec } = (0, utilities_1.constructProjectTsConfigFiles)('application');
+    const { tsConfig } = (0, utilities_1.constructProjectTsConfigFiles)('application');
     (0, devkit_1.writeJson)(tree, 'application/tsconfig.json', tsConfig);
-    (0, devkit_1.writeJson)(tree, 'application/tsconfig.lib.json', tsConfigLib);
-    (0, devkit_1.writeJson)(tree, 'application/tsconfig.spec.json', tsConfigSpec);
     await (0, devkit_1.formatFiles)(tree);
 }
 exports.default = presetGenerator;

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

@@ -15,13 +15,13 @@ This is a CDK service generated using `@aligent/nx-cdk` for Nx.
 ### Type Checking
 
 ```bash
-npx nx check-types <%= name %>
+yarn nx check-types <%= name %>
 ```
 
 ### Testing
 
 ```bash
-npx nx test <%= name %>
+yarn nx test <%= name %>
 ```
 
 ## Deployment

package/src/generators/service/files/package.json.template

@@ -1,5 +1,5 @@
 {
-  "name": "<%= name %>",
+  "name": "@services/<%= name %>",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -12,7 +12,8 @@
     "./package.json": "./package.json"
   },
   "bundleDependencies": [
-    "clients"
+    "clients",
+    "@libs/infra"
   ],
   "nx": {
     "targets": {

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

@@ -1,3 +1,4 @@
+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';
@@ -14,7 +15,7 @@ export const <%= constant %> = {
 } as const;
 
 type Id = typeof <%= constant %>.NAME | (string & {});
-interface Props extends StackProps {
+interface Props extends StackProps, SharedInfraProps {
     description: string;
 }
 

package/src/generators/service/files/vitest.config.mjs.template

@@ -5,7 +5,7 @@ export default defineConfig(configEnv => {
     return mergeConfig(
         vitestBaseConfig(configEnv),
         defineConfig({
-            cacheDir: '../../node_modules/.vite/<%= name %>',
+            cacheDir: '../../node_modules/.vitest/<%= name %>',
             test: {
                 env: {
                     NODE_ENV: 'test',

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

@@ -1,27 +0,0 @@
-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/application/_internal/log-group-defaults-injector.ts.template

@@ -1,100 +0,0 @@
-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 };
-    }
-}