create-aws-project 1.2.1

package/templates/apps/api/cdk/static-stack.ts

@@ -0,0 +1,361 @@
+import * as cdk from 'aws-cdk-lib';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
+import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';
+import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import * as opensearchserverless from 'aws-cdk-lib/aws-opensearchserverless';
+import { Construct } from 'constructs';
+
+export interface StaticStackProps extends cdk.StackProps {
+  /**
+   * Environment name (e.g., dev, staging, prod)
+   */
+  environmentName: string;
+}
+
+/**
+ * Static Stack for {{PROJECT_NAME_TITLE}}
+ *
+ * Creates a CloudFront distribution with:
+ * - S3 bucket for static web content (default route)
+ * - API Gateway for Lambda API (routes starting with /api)
+ */
+export class StaticStack extends cdk.Stack {
+  public readonly bucket: s3.Bucket;
+  public readonly api: apigateway.RestApi;
+  public readonly distribution: cloudfront.Distribution;
+  public readonly openSearchCollection: opensearchserverless.CfnCollection;
+
+  constructor(scope: Construct, id: string, props: StaticStackProps) {
+    super(scope, id, props);
+
+    const { environmentName } = props;
+
+    // Create S3 bucket for static website content
+    this.bucket = new s3.Bucket(this, 'WebContentBucket', {
+      bucketName: `{{PROJECT_NAME}}-${environmentName}-web-${this.account}`,
+      websiteIndexDocument: 'index.html',
+      websiteErrorDocument: 'index.html', // For SPA routing
+      publicReadAccess: false, // CloudFront will access via OAI
+      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+      removalPolicy: cdk.RemovalPolicy.DESTROY, // For dev environments
+      autoDeleteObjects: true, // For dev environments
+      cors: [
+        {
+          allowedMethods: [s3.HttpMethods.GET, s3.HttpMethods.HEAD],
+          allowedOrigins: ['*'],
+          allowedHeaders: ['*'],
+        },
+      ],
+    });
+
+    // Create API Gateway for Lambda functions
+    this.api = new apigateway.RestApi(this, 'ApiGateway', {
+      restApiName: `{{PROJECT_NAME}}-${environmentName}-api`,
+      description: `{{PROJECT_NAME_TITLE}} API - ${environmentName}`,
+      deployOptions: {
+        stageName: environmentName,
+        throttlingRateLimit: 100,
+        throttlingBurstLimit: 200,
+        metricsEnabled: true,
+        loggingLevel: apigateway.MethodLoggingLevel.INFO,
+        dataTraceEnabled: true,
+      },
+      defaultCorsPreflightOptions: {
+        allowOrigins: apigateway.Cors.ALL_ORIGINS,
+        allowMethods: apigateway.Cors.ALL_METHODS,
+        allowHeaders: [
+          'Content-Type',
+          'X-Amz-Date',
+          'Authorization',
+          'X-Api-Key',
+          'X-Amz-Security-Token',
+        ],
+      },
+      // Enable request validation
+      cloudWatchRole: true,
+    });
+
+    // Create a simple health check endpoint at /api/health
+    const api = this.api.root.addResource('api');
+    const health = api.addResource('health');
+    health.addMethod('GET', new apigateway.MockIntegration({
+      integrationResponses: [
+        {
+          statusCode: '200',
+          responseTemplates: {
+            'application/json': JSON.stringify({
+              status: 'healthy',
+              timestamp: '$context.requestTime',
+              environment: environmentName,
+            }),
+          },
+        },
+      ],
+      requestTemplates: {
+        'application/json': '{"statusCode": 200}',
+      },
+    }), {
+      methodResponses: [{ statusCode: '200' }],
+    });
+
+
+    // Create custom cache policy for API routes
+    const apiCachePolicy = new cloudfront.CachePolicy(this, 'ApiCachePolicy', {
+      cachePolicyName: `{{PROJECT_NAME}}-${environmentName}-api-cache`,
+      comment: 'Cache policy for API Gateway with query strings and headers',
+      defaultTtl: cdk.Duration.seconds(0), // No caching for API by default
+      minTtl: cdk.Duration.seconds(0),
+      maxTtl: cdk.Duration.seconds(1),
+      cookieBehavior: cloudfront.CacheCookieBehavior.none(),
+      headerBehavior: cloudfront.CacheHeaderBehavior.allowList(
+        'Authorization',
+        'Content-Type',
+        'Accept'
+      ),
+      queryStringBehavior: cloudfront.CacheQueryStringBehavior.all(),
+      enableAcceptEncodingGzip: true,
+      enableAcceptEncodingBrotli: true,
+    });
+
+    // Create custom origin request policy for API
+    const apiOriginRequestPolicy = new cloudfront.OriginRequestPolicy(this, 'ApiOriginRequestPolicy', {
+      originRequestPolicyName: `{{PROJECT_NAME}}-${environmentName}-api-origin`,
+      comment: 'Origin request policy for API Gateway',
+      cookieBehavior: cloudfront.OriginRequestCookieBehavior.none(),
+      headerBehavior: cloudfront.OriginRequestHeaderBehavior.allowList(
+        'Accept',
+        'Accept-Language',
+        'Content-Type',
+        'Referer',
+        'User-Agent'
+      ),
+      queryStringBehavior: cloudfront.OriginRequestQueryStringBehavior.all(),
+    });
+
+    // Create CloudFront function to rewrite /api to the environment stage
+    const apiRewriteFunction = new cloudfront.Function(this, 'ApiRewriteFunction', {
+      code: cloudfront.FunctionCode.fromInline(`
+  function handler(event) {
+      var request = event.request;
+      var uri = request.uri;
+
+      // Only rewrite if URI starts with /api
+      if (uri.indexOf('/api') === 0) {
+          request.uri = uri.replace('/api', '/${environmentName}');
+      }
+
+      return request;
+  }
+        `),
+      functionName: `${environmentName}-api-rewrite-function`,
+      comment: `Rewrites /api requests to /${environmentName} stage for API Gateway`
+    });
+
+    // Create CloudFront distribution
+    this.distribution = new cloudfront.Distribution(this, 'Distribution', {
+      comment: `{{PROJECT_NAME_TITLE}} - ${environmentName}`,
+      defaultRootObject: 'index.html',
+      priceClass: cloudfront.PriceClass.PRICE_CLASS_100, // North America and Europe
+      httpVersion: cloudfront.HttpVersion.HTTP2_AND_3,
+      enableIpv6: true,
+
+      // Default behavior: Serve static content from S3
+      defaultBehavior: {
+        origin: origins.S3BucketOrigin.withOriginAccessControl(this.bucket),
+        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+        allowedMethods: cloudfront.AllowedMethods.ALLOW_GET_HEAD_OPTIONS,
+        cachedMethods: cloudfront.CachedMethods.CACHE_GET_HEAD_OPTIONS,
+        compress: true,
+        cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
+      },
+
+      // Additional behavior: Route /api/* to API Gateway
+      additionalBehaviors: {
+        '/api/*': {
+          origin: new origins.RestApiOrigin(this.api),
+          viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.HTTPS_ONLY,
+          allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
+          cachedMethods: cloudfront.CachedMethods.CACHE_GET_HEAD_OPTIONS,
+          compress: true,
+          cachePolicy: apiCachePolicy,
+          originRequestPolicy: apiOriginRequestPolicy,
+          // Add the function association for URL rewriting
+          functionAssociations: [{
+            function: apiRewriteFunction,
+            eventType: cloudfront.FunctionEventType.VIEWER_REQUEST
+          }]
+        },
+      },
+
+      // Error responses for SPA routing
+      errorResponses: [
+        {
+          httpStatus: 403,
+          responseHttpStatus: 200,
+          responsePagePath: '/index.html',
+          ttl: cdk.Duration.seconds(300),
+        },
+        {
+          httpStatus: 404,
+          responseHttpStatus: 200,
+          responsePagePath: '/index.html',
+          ttl: cdk.Duration.seconds(300),
+        },
+      ],
+    });
+
+    // OpenSearch Serverless Collection
+    const collectionName = `{{PROJECT_NAME}}-${environmentName}`;
+
+    // Encryption policy (required for all collections)
+    const encryptionPolicy = new opensearchserverless.CfnSecurityPolicy(this, 'OpenSearchEncryptionPolicy', {
+      name: `${collectionName}-encryption`,
+      type: 'encryption',
+      policy: JSON.stringify({
+        Rules: [
+          {
+            ResourceType: 'collection',
+            Resource: [`collection/${collectionName}`],
+          },
+        ],
+        AWSOwnedKey: true,
+      }),
+    });
+
+    // Network policy - allows public access (adjust for production)
+    const networkPolicy = new opensearchserverless.CfnSecurityPolicy(this, 'OpenSearchNetworkPolicy', {
+      name: `${collectionName}-network`,
+      type: 'network',
+      policy: JSON.stringify([
+        {
+          Rules: [
+            {
+              ResourceType: 'collection',
+              Resource: [`collection/${collectionName}`],
+            },
+            {
+              ResourceType: 'dashboard',
+              Resource: [`collection/${collectionName}`],
+            },
+          ],
+          AllowFromPublic: true,
+        },
+      ]),
+    });
+
+    // Data access policy - grants access to the collection
+    const dataAccessPolicy = new opensearchserverless.CfnAccessPolicy(this, 'OpenSearchDataAccessPolicy', {
+      name: `${collectionName}-access`,
+      type: 'data',
+      policy: JSON.stringify([
+        {
+          Rules: [
+            {
+              ResourceType: 'collection',
+              Resource: [`collection/${collectionName}`],
+              Permission: [
+                'aoss:CreateCollectionItems',
+                'aoss:DeleteCollectionItems',
+                'aoss:UpdateCollectionItems',
+                'aoss:DescribeCollectionItems',
+              ],
+            },
+            {
+              ResourceType: 'index',
+              Resource: [`index/${collectionName}/*`],
+              Permission: [
+                'aoss:CreateIndex',
+                'aoss:DeleteIndex',
+                'aoss:UpdateIndex',
+                'aoss:DescribeIndex',
+                'aoss:ReadDocument',
+                'aoss:WriteDocument',
+              ],
+            },
+          ],
+          Principal: [
+            `arn:aws:iam::${this.account}:root`,
+          ],
+        },
+      ]),
+    });
+
+    // Create the OpenSearch Serverless collection
+    this.openSearchCollection = new opensearchserverless.CfnCollection(this, 'OpenSearchCollection', {
+      name: collectionName,
+      type: 'SEARCH', // SEARCH, TIMESERIES, or VECTORSEARCH
+      description: `OpenSearch Serverless collection for {{PROJECT_NAME_TITLE}} - ${environmentName}`,
+    });
+
+    // Ensure policies are created before the collection
+    this.openSearchCollection.addDependency(encryptionPolicy);
+    this.openSearchCollection.addDependency(networkPolicy);
+    this.openSearchCollection.addDependency(dataAccessPolicy);
+
+    // Output important values
+    new cdk.CfnOutput(this, 'BucketName', {
+      value: this.bucket.bucketName,
+      description: 'S3 bucket name for web content',
+      exportName: `${environmentName}-web-bucket-name`,
+    });
+
+    new cdk.CfnOutput(this, 'BucketArn', {
+      value: this.bucket.bucketArn,
+      description: 'S3 bucket ARN',
+      exportName: `${environmentName}-web-bucket-arn`,
+    });
+
+    new cdk.CfnOutput(this, 'ApiUrl', {
+      value: this.api.url,
+      description: 'API Gateway URL',
+      exportName: `${environmentName}-api-url`,
+    });
+
+    new cdk.CfnOutput(this, 'ApiId', {
+      value: this.api.restApiId,
+      description: 'API Gateway ID',
+      exportName: `${environmentName}-api-id`,
+    });
+
+    new cdk.CfnOutput(this, 'DistributionId', {
+      value: this.distribution.distributionId,
+      description: 'CloudFront distribution ID',
+      exportName: `${environmentName}-distribution-id`,
+    });
+
+    new cdk.CfnOutput(this, 'DistributionDomainName', {
+      value: this.distribution.distributionDomainName,
+      description: 'CloudFront distribution domain name',
+      exportName: `${environmentName}-distribution-domain`,
+    });
+
+    new cdk.CfnOutput(this, 'WebsiteUrl', {
+      value: `https://${this.distribution.distributionDomainName}`,
+      description: 'Website URL',
+    });
+
+    new cdk.CfnOutput(this, 'ApiUrlViaCdn', {
+      value: `https://${this.distribution.distributionDomainName}/api`,
+      description: 'API URL via CloudFront',
+    });
+
+    new cdk.CfnOutput(this, 'OpenSearchCollectionEndpoint', {
+      value: this.openSearchCollection.attrCollectionEndpoint,
+      description: 'OpenSearch Serverless collection endpoint',
+      exportName: `${environmentName}-opensearch-endpoint`,
+    });
+
+    new cdk.CfnOutput(this, 'OpenSearchDashboardEndpoint', {
+      value: this.openSearchCollection.attrDashboardEndpoint,
+      description: 'OpenSearch Serverless dashboard endpoint',
+      exportName: `${environmentName}-opensearch-dashboard`,
+    });
+
+    new cdk.CfnOutput(this, 'OpenSearchCollectionArn', {
+      value: this.openSearchCollection.attrArn,
+      description: 'OpenSearch Serverless collection ARN',
+      exportName: `${environmentName}-opensearch-arn`,
+    });
+  }
+}

package/templates/apps/api/cdk/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": [
+      "es2020"
+    ],
+    "declaration": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": false,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "experimentalDecorators": true,
+    "strictPropertyInitialization": false,
+    "typeRoots": [
+      "../../../node_modules/@types"
+    ],
+    "outDir": "../../../dist/apps/api/cdk",
+    "rootDir": "."
+  },
+  "exclude": [
+    "node_modules",
+    "cdk.out"
+  ],
+  "include": [
+    "**/*.ts"
+  ]
+}

package/templates/apps/api/cdk/user-stack.ts

@@ -0,0 +1,255 @@
+import * as cdk from 'aws-cdk-lib';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as lambdaNodejs from 'aws-cdk-lib/aws-lambda-nodejs';
+import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import * as iam from 'aws-cdk-lib/aws-iam';
+import { Construct } from 'constructs';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+
+/**
+ * Lambda configuration from YAML
+ */
+export interface LambdaConfig {
+  name: string;
+  source: string;
+  handler: string;
+  method: string;
+  path: string;
+  description?: string;
+  memorySize?: number;
+  timeout?: number;
+  environment?: Record<string, string>;
+}
+
+/**
+ * YAML configuration structure
+ */
+interface LambdasYaml {
+  lambdas: {
+    'user-lambdas'?: LambdaConfig[];
+    [key: string]: LambdaConfig[] | undefined;
+  };
+}
+
+export interface UserStackProps extends cdk.StackProps {
+  /**
+   * Environment name (e.g., dev, staging, prod)
+   */
+  environmentName: string;
+
+  /**
+   * API Gateway to add Lambda integrations to
+   */
+  api: apigateway.RestApi;
+
+  /**
+   * Path to the lambdas.yml configuration file
+   * Defaults to './lambdas.yml' relative to the project root
+   */
+  configPath?: string;
+}
+
+/**
+ * User Stack for {{PROJECT_NAME_TITLE}}
+ *
+ * Creates Lambda functions and API Gateway integrations based on
+ * configuration defined in lambdas.yml
+ */
+export class UserStack extends cdk.Stack {
+  public readonly functions: Map<string, lambda.Function>;
+  private readonly api: apigateway.RestApi;
+  private readonly environmentName: string;
+
+  constructor(scope: Construct, id: string, props: UserStackProps) {
+    super(scope, id, props);
+
+    this.api = props.api;
+    this.environmentName = props.environmentName;
+    this.functions = new Map();
+
+    // Read Lambda configurations from YAML file
+    const configPath = props.configPath || path.join(__dirname, '../lambdas.yml');
+    const lambdaConfigs = this.loadLambdaConfigs(configPath);
+
+    // Create Lambda functions and API Gateway integrations
+    lambdaConfigs.forEach(config => {
+      this.createLambdaFunction(config);
+    });
+
+    // Output Lambda function ARNs
+    this.functions.forEach((func, name) => {
+      new cdk.CfnOutput(this, `${name}Arn`, {
+        value: func.functionArn,
+        description: `ARN for ${name} Lambda function`,
+        exportName: `${this.environmentName}-${name}-arn`,
+      });
+    });
+  }
+
+  /**
+   * Load Lambda configurations from YAML file
+   */
+  private loadLambdaConfigs(configPath: string): LambdaConfig[] {
+    try {
+      const fileContents = fs.readFileSync(configPath, 'utf8');
+      const config = yaml.load(fileContents) as LambdasYaml;
+
+      if (!config || !config.lambdas) {
+        throw new Error('Invalid YAML structure: expected "lambdas" object');
+      }
+
+      // Load user-lambdas specifically for this stack
+      const userLambdas = config.lambdas['user-lambdas'];
+
+      if (!userLambdas || !Array.isArray(userLambdas)) {
+        throw new Error('Invalid YAML structure: expected "lambdas.user-lambdas" array');
+      }
+
+      console.log(`Loaded ${userLambdas.length} user Lambda configurations from ${configPath}`);
+      return userLambdas;
+    } catch (error) {
+      throw new Error(`Failed to load Lambda configurations from ${configPath}: ${error}`);
+    }
+  }
+
+  /**
+   * Create a Lambda function and API Gateway integration from configuration
+   */
+  private createLambdaFunction(config: LambdaConfig): void {
+    const { name, source, handler, method, path: apiPath, description, memorySize, timeout, environment } = config;
+
+    // Validate configuration
+    if (!name || !source || !handler || !method || !apiPath) {
+      throw new Error(`Invalid Lambda configuration: missing required fields for ${name}`);
+    }
+
+    // Resolve the source file path relative to the API app directory
+    // __dirname is apps/api/cdk, so ../ gets us to apps/api
+    const sourcePath = path.join(__dirname, '../', source);
+
+    // Verify source file exists
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`Source file not found: ${sourcePath} for Lambda ${name}`);
+    }
+
+    // Create Lambda execution role with CloudWatch Logs permissions
+    const role = new iam.Role(this, `${name}Role`, {
+      roleName: `${this.environmentName}-${name}-role`,
+      assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+      managedPolicies: [
+        iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
+      ],
+    });
+
+    // Create Lambda function using NodejsFunction for automatic TypeScript bundling
+    const lambdaFunction = new lambdaNodejs.NodejsFunction(this, `${name}Function`, {
+      functionName: `${this.environmentName}-${name}`,
+      entry: sourcePath,
+      handler: handler,
+      runtime: lambda.Runtime.NODEJS_20_X,
+      role,
+      memorySize: memorySize || 256,
+      timeout: cdk.Duration.seconds(timeout || 30),
+      environment: {
+        NODE_ENV: this.environmentName,
+        ...environment,
+      },
+      description: description || `${name} Lambda function`,
+      tracing: lambda.Tracing.ACTIVE, // Enable X-Ray tracing
+      bundling: {
+        minify: true,
+        sourceMap: true,
+        target: 'es2020',
+        externalModules: [],
+        format: lambdaNodejs.OutputFormat.CJS,
+        tsconfig: path.join(__dirname, '../tsconfig.app.json'),
+      },
+    });
+
+    // Store function reference
+    this.functions.set(name, lambdaFunction);
+
+    // Create API Gateway integration
+    this.createApiIntegration(lambdaFunction, method, apiPath, name);
+
+    console.log(`Created Lambda function: ${name} from ${source} (${method} ${apiPath})`);
+  }
+
+  /**
+   * Create API Gateway integration for a Lambda function
+   */
+  private createApiIntegration(
+    lambdaFunction: lambda.Function,
+    method: string,
+    apiPath: string,
+    name: string
+  ): void {
+    // Parse the API path to create/get resources
+    const pathParts = apiPath.split('/').filter(part => part.length > 0);
+    let currentResource: apigateway.IResource = this.api.root;
+
+    // Create nested resources as needed
+    for (const part of pathParts) {
+      const existingResource = currentResource.getResource(part);
+      if (existingResource) {
+        currentResource = existingResource;
+      } else {
+        currentResource = currentResource.addResource(part);
+      }
+    }
+
+    // Create Lambda integration
+    const integration = new apigateway.LambdaIntegration(lambdaFunction, {
+      proxy: true,
+      allowTestInvoke: true,
+      integrationResponses: [
+        {
+          statusCode: '200',
+        },
+      ],
+    });
+
+    // Add method to resource
+    // Note: CORS OPTIONS methods are automatically added by the API Gateway's
+    // defaultCorsPreflightOptions configuration in StaticStack
+    const apiMethod = currentResource.addMethod(method.toUpperCase(), integration, {
+      methodResponses: [
+        {
+          statusCode: '200',
+          responseParameters: {
+            'method.response.header.Access-Control-Allow-Origin': true,
+            'method.response.header.Access-Control-Allow-Headers': true,
+            'method.response.header.Access-Control-Allow-Methods': true,
+          },
+        },
+        {
+          statusCode: '400',
+        },
+        {
+          statusCode: '404',
+        },
+        {
+          statusCode: '500',
+        },
+      ],
+    });
+
+    console.log(`Created API integration: ${method} ${apiPath} -> ${name}`);
+  }
+
+  /**
+   * Get a Lambda function by name
+   */
+  public getFunction(name: string): lambda.Function | undefined {
+    return this.functions.get(name);
+  }
+
+  /**
+   * Get all Lambda functions
+   */
+  public getAllFunctions(): lambda.Function[] {
+    return Array.from(this.functions.values());
+  }
+}

package/templates/apps/api/jest.config.ts

@@ -0,0 +1,38 @@
+export default {
+  displayName: 'api',
+  preset: '../../jest.preset.js',
+  testEnvironment: 'node',
+  testEnvironmentOptions: {
+    customExportConditions: ['node', 'node-addons'],
+  },
+  // Workaround for Node.js 25+ localStorage security error
+  workerIdleMemoryLimit: '512MB',
+  maxWorkers: 1,
+  transform: {
+    '^.+\\.(ts|tsx)$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/tsconfig.spec.json',
+      },
+    ],
+  },
+  moduleFileExtensions: ['ts', 'js'],
+  coverageDirectory: '../../coverage/apps/api',
+  // Exclude infrastructure code from coverage - tested via integration tests
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '/data/DynamoModel.ts',
+    '/models/UserModel.ts',
+  ],
+  // Clear mocks between tests
+  clearMocks: true,
+  resetMocks: true,
+  restoreMocks: true,
+  // Setup files
+  setupFiles: ['<rootDir>/src/__tests__/setup.ts'],
+  globals: {
+    'ts-jest': {
+      isolatedModules: true,
+    },
+  },
+};