@worktif/runtime 0.3.0-edge.0

package/out/dist/bin/templates/runtime-web/cdk/.gitignore.template

@@ -0,0 +1,25 @@
+# CDK asset staging directory
+.cdk.staging
+cdk.out
+
+# Dependency directories
+node_modules/
+
+# TypeScript compiled output
+*.js
+*.d.ts
+
+# Environment variables
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

package/out/dist/bin/templates/runtime-web/cdk/README.md.template

@@ -0,0 +1,267 @@
+# {{STACK_NAME}} CDK Infrastructure
+
+This directory contains the AWS CDK infrastructure code for deploying {{STACK_NAME}} to AWS.
+
+## Overview
+
+The CDK app uses the `PurenowStack` construct from `@worktif/purenow/infra` to provision all required AWS resources:
+
+- **S3 Bucket**: Stores static assets and cached SSR responses
+- **Lambda Function**: Handles server-side rendering of React components
+- **CloudFront Distribution**: CDN for global content delivery
+- **DynamoDB Table**: (Optional) Stores SEO metadata when `enableSeo` is true
+- **IAM Roles**: Least-privilege permissions for Lambda execution
+
+## Prerequisites
+
+1. **AWS CLI**: Install and configure AWS CLI with your credentials
+   ```bash
+   aws configure
+   ```
+
+2. **Node.js**: Version 18 or higher
+
+3. **AWS CDK**: Install globally (optional, can use npx)
+   ```bash
+   npm install -g aws-cdk
+   ```
+
+## Getting Started
+
+**Good news!** If you initialized this CDK app using `purenow init`, all dependencies have already been installed automatically. You can skip directly to deployment!
+
+### 1. Verify Installation (Already Done!)
+
+During initialization, Purenow automatically:
+- ✓ Installed all project dependencies (React, Purenow, etc.)
+- ✓ Installed all CDK dependencies (aws-cdk-lib, constructs, etc.)
+- ✓ Validated that all packages are correctly installed
+
+If you need to reinstall dependencies manually:
+
+```bash
+# Install project dependencies (from project root)
+cd ..
+npm install
+
+# Install CDK dependencies
+cd cdk
+npm install
+```
+
+### 2. Bootstrap CDK (First Time Only)
+
+Bootstrap provisions the CDK toolkit resources in your AWS account:
+
+```bash
+cdk bootstrap
+```
+
+This only needs to be done once per AWS account/region combination.
+
+**Note**: If you chose to run bootstrap during initialization, this step is already complete!
+
+### 3. Deploy Infrastructure
+
+Deploy to the default stage (dev):
+
+```bash
+cdk deploy --all
+```
+
+Deploy to a specific stage:
+
+```bash
+npm run deploy:dev      # Deploy to dev
+npm run deploy:staging  # Deploy to staging
+npm run deploy:prod     # Deploy to prod
+```
+
+### 4. View Deployment Outputs
+
+After deployment, CDK will display important outputs:
+
+- **CloudFront URL**: Your application's public URL
+- **S3 Bucket Name**: Where static assets are stored
+- **Lambda Function ARN**: The SSR handler function
+
+## Configuration
+
+### Main Configuration (bin/app.ts)
+
+The CDK app is configured in `bin/app.ts`. Key properties:
+
+- **stage**: Environment name (`dev`, `staging`, `prod`)
+  - Affects resource naming and removal policies
+  - Production stages have stricter retention policies
+
+- **serviceName**: Identifier for your service
+  - Used as prefix for all AWS resources
+  - Example: `my-app` → `my-app-static-dev`, `my-app-ssr-handler-dev`
+
+- **enableSeo**: Enable SEO features
+  - Creates DynamoDB table for SEO metadata
+  - Enables server-side rendering of meta tags
+
+- **env.account**: AWS account ID
+  - Defaults to `CDK_DEFAULT_ACCOUNT` environment variable
+  - Can be hardcoded for specific environments
+
+- **env.region**: AWS region
+  - Resolved from AWS SDK default provider chain (AWS_REGION env var, ~/.aws/config)
+  - Set to `{{REGION}}` during initialization based on your AWS configuration
+  - Common values: `us-east-1`, `us-west-2`, `eu-west-1`, `eu-central-1`
+
+### Optional Configuration
+
+Uncomment these in `bin/app.ts` to customize:
+
+```typescript
+// Increase Lambda memory (default: 512 MB)
+lambdaMemorySize: 1024,
+
+// Increase Lambda timeout (default: 29 seconds)
+lambdaTimeout: 60,
+
+// Add custom environment variables
+customEnvironmentVariables: {
+  MY_API_KEY: 'value',
+},
+
+// Configure custom domain
+domainName: 'example.com',
+certificateArn: 'arn:aws:acm:...',
+```
+
+## Multiple Stages
+
+To deploy multiple stages (dev, staging, prod), duplicate the stack instantiation in `bin/app.ts`:
+
+```typescript
+// Dev stage
+new PurenowStack(app, `${serviceName}-dev`, {
+  stage: 'dev',
+  serviceName,
+  enableSeo: true,
+  env: { account: '...', region: '{{REGION}}' },
+});
+
+// Staging stage
+new PurenowStack(app, `${serviceName}-staging`, {
+  stage: 'staging',
+  serviceName,
+  enableSeo: true,
+  env: { account: '...', region: '{{REGION}}' },
+});
+
+// Production stage
+new PurenowStack(app, `${serviceName}-prod`, {
+  stage: 'prod',
+  serviceName,
+  enableSeo: true,
+  env: { account: '...', region: '{{REGION}}' },
+});
+```
+
+## Useful Commands
+
+- `npm run build`: Compile TypeScript to JavaScript
+- `npm run watch`: Watch for changes and compile
+- `cdk synth`: Synthesize CloudFormation template
+- `cdk diff --all`: Compare deployed stack with current state
+- `cdk deploy --all`: Deploy stack to AWS
+- `cdk destroy`: Remove all resources (use with caution!)
+
+## Troubleshooting
+
+### "Unable to resolve AWS account"
+
+**Problem**: CDK can't determine your AWS account ID.
+
+**Solution**: Set environment variables or configure AWS CLI:
+```bash
+# Option 1: Set environment variables
+export CDK_DEFAULT_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
+export AWS_REGION={{REGION}}
+
+# Option 2: Configure AWS CLI (recommended)
+aws configure set region {{REGION}}
+```
+
+### "Stack already exists"
+
+**Problem**: A stack with the same name already exists.
+
+**Solution**: CDK will update the existing stack. Use `cdk diff` to preview changes.
+
+### "Insufficient permissions"
+
+**Problem**: Your AWS credentials don't have required permissions.
+
+**Solution**: Ensure your IAM user/role has permissions for:
+- CloudFormation
+- S3
+- Lambda
+- CloudFront
+- DynamoDB (if enableSeo is true)
+- IAM (for creating roles)
+
+### "Lambda bundle not found"
+
+**Problem**: The Lambda bundle hasn't been built.
+
+**Solution**: Build your Purenow application first:
+```bash
+cd ..
+npm run build
+cd cdk
+cdk deploy --all
+```
+
+### "Dependencies not installed"
+
+**Problem**: CDK dependencies are missing or corrupted.
+
+**Solution**:
+
+If you initialized with `purenow init`, dependencies should already be installed. If you're experiencing issues:
+
+```bash
+# Reinstall project dependencies
+cd ..
+rm -rf node_modules package-lock.json
+npm install
+
+# Reinstall CDK dependencies
+cd cdk
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### "Package manager mismatch"
+
+**Problem**: Different package managers used in project vs CDK directory.
+
+**Solution**:
+
+Purenow automatically detects your package manager (npm, yarn, or pnpm) and uses it consistently. If you need to switch:
+
+```bash
+# For npm
+rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
+npm install
+
+# For yarn
+rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
+yarn install
+
+# For pnpm
+rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
+pnpm install
+```
+
+## Learn More
+
+- [AWS CDK Documentation](https://docs.aws.amazon.com/cdk/)
+- [Purenow Documentation](https://github.com/worktif/purenow)
+- [PurenowStack API Reference](https://github.com/worktif/purenow/blob/main/docs/CDK_USAGE.md)

package/out/dist/bin/templates/runtime-web/cdk/bin/app.ts.template

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+import 'reflect-metadata';
+
+import * as cdk from 'aws-cdk-lib';
+
+import { PurenowInfraStack, RuntimeWebStack, PurenowRuntimeStack, sanitizeStackName } from '@worktif/purenow/infra';
+import { getStage } from '@worktif/purenow/bin';
+
+import { UsersTies } from '../../src/ties/users.ties';
+import { createUserHandler, deleteUserHandler, getUserHandler, updateUserHandler } from '../../src/handlers/users';
+import runtimeConfig from '../../purenow.config';
+
+const app = new cdk.App();
+
+// Stage name used for naming and environment separation.
+// Common values: 'dev', 'staging', 'prod'
+// const stage = '{{STAGE}}';
+const stage = app.node.tryGetContext('stage') || process.env.STAGE || '{{STAGE}}';
+
+// Service identifier used for resource naming, tags, etc.
+// This will be used as a prefix for all AWS resources (e.g., my-app-static-dev)
+export const serviceName = sanitizeStackName(runtimeConfig.projectName);
+
+// Enable SEO-ready features in the frontend (e.g. metadata, sitemaps).
+// When enabled, creates a DynamoDB table for storing SEO metadata.
+const enableSeo = {{ENABLE_SEO}};
+
+// AWS environment configuration
+const env = {
+    // Account ID from AWS credentials
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    // Region resolved from AWS SDK default provider chain (env vars, config file, etc.)
+    region: getStage(runtimeConfig, stage).awsRegion || '{{REGION}}' || 'us-east-1',
+};
+
+// Create the Infrastructure stack (S3, DynamoDB, CloudFront, IAM)
+// This stack contains slow-changing infrastructure resources
+const infraStack = new PurenowInfraStack(app, `${serviceName}-PurenowInfra-${stage}`, {
+    // Stage name (dev, staging, prod)
+    stage: stage as 'dev' | 'staging' | 'prod',
+
+    // Service name for resource identification
+    serviceName,
+
+    // Enable SEO features (DynamoDB table for metadata)
+    enableSeo,
+
+    // AWS environment configuration
+    env,
+});
+
+// Create the Runtime stack (Lambda functions, Lambda Layers, API Gateway)
+// This stack contains fast-changing runtime resources
+// It imports values from the Infrastructure stack via cross-stack references
+const runtimeStack = new PurenowRuntimeStack(app, `${serviceName}-PurenowRuntime-${stage}`, {
+    // Stage name (dev, staging, prod)
+    stage: stage as 'dev' | 'staging' | 'prod',
+
+    // Service name for resource identification
+    serviceName,
+
+    // Enable SEO features (must match infraStack)
+    enableSeo,
+
+    // App entry point - the file where you call purenow() to configure your app
+    // This enables automatic Lambda bundling by the CDK stack
+    appEntryPoint: './src/index.tsx',
+
+    // API Gateway configuration
+    // Enable API Gateway for proper routing, CORS, and Lambda warmup
+    enableApiGateway: true,
+
+    // Enable Lambda warmup (reduces cold starts)
+    // Recommended: true for staging/prod, false for dev to reduce costs
+    enableWarmup: stage !== 'dev',
+
+    // Reference to Infrastructure stack for cross-stack references
+    infraStack,
+
+    // AWS environment configuration
+    env,
+
+    // Optional: Customize Lambda configuration
+    // lambdaMemorySize: 512,  // Memory in MB (default: 512)
+    // lambdaTimeout: 29,      // Timeout in seconds (default: 29)
+
+    // Optional: Add custom environment variables for Lambda
+    // customEnvironmentVariables: {
+    //   MY_CUSTOM_VAR: 'value',
+    // },
+
+    // Optional: Configure CORS allowed origins for production
+    // allowedOrigins: ['https://example.com', 'https://www.example.com'],
+});
+
+// Create the Runtime Web stack
+// This stack maps high-level "register" configuration to concrete Lambda routes
+// It reuses shared infrastructure from the Infrastructure stack via cross-stack references
+const runtimeWebStack = new RuntimeWebStack(app, `${serviceName}-RuntimeWeb-${stage}`, {
+    // Stage name (dev, staging, prod)
+    // Must be consistent with other stacks in the same environment
+    stage: stage as 'dev' | 'staging' | 'prod',
+
+    // Service name for resource identification
+    // Used as a prefix for Runtime Web resources (Lambdas, logs, etc.)
+    serviceName,
+
+    // Reference to Infrastructure stack for shared resources (tables, buckets, queues, etc.)
+    infraStack,
+
+    // AWS environment configuration (account + region)
+    // Should match the env used in Infrastructure and Runtime stacks
+    env,
+
+    // Runtime Web "register" configuration:
+    // microservice registry with service definition
+    register: {
+        // "payments" domain – logical microservice of routes / operations for payments | @example
+        payments: {
+            // Ties – shared domain models / dependencies used by this module
+            // These are injected into all related Lambdas
+            ties: [UsersTies],
+
+            // Lambda handlers for the "payments" domain
+            // Each handler is wired into the API according to the Runtime Web conventions
+            lambdas: [
+                createUserHandler,
+                getUserHandler,
+                updateUserHandler,
+                deleteUserHandler,
+            ],
+        },
+    },
+
+    // API mode – how Runtime Web exposes HTTP endpoints
+    // 'apiGateway' uses Amazon API Gateway (recommended for production)
+    apiMode: 'apiGateway',
+
+    // Default memory size (in MB) for Lambda functions managed by Runtime Web
+    // Tune per workload if needed for performance / cost optimization
+    lambdaMemorySize: 512,
+
+    // Default Lambda timeout (in seconds) for Runtime Web handlers
+    // Should cover typical request latency including external integrations
+    lambdaTimeout: 30,
+});
+
+// To add more stages (staging, prod), duplicate the stack instantiation:
+// const infraStackStaging = new PurenowInfraStack(app, 'PurenowInfra-staging', {
+//   stage: 'staging',
+//   serviceName,
+//   enableSeo: true,
+//   env: {
+//     account: process.env.CDK_DEFAULT_ACCOUNT,
+//     region: '{{REGION}}',  // Same region as dev, or specify different region
+//   },
+// });
+//
+// const runtimeStackStaging = new PurenowRuntimeStack(app, 'PurenowRuntime-staging', {
+//   stage: 'staging',
+//   serviceName,
+//   enableSeo: true,
+//   appEntryPoint: './src/index.tsx',
+//   enableApiGateway: true,
+//   enableWarmup: true,
+//   infraStack: infraStackStaging,
+//   env: {
+//     account: process.env.CDK_DEFAULT_ACCOUNT,
+//     region: '{{REGION}}',
+//   },
+// });
+
+app.synth();

package/out/dist/bin/templates/runtime-web/cdk/cdk.json.template

@@ -0,0 +1,79 @@
+{
+  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
+  "watch": {
+    "include": [
+      "**"
+    ],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "yarn.lock",
+      "node_modules",
+      "test"
+    ]
+  },
+  "notices": false,
+  "context": {
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+    "@aws-cdk/core:checkSecretUsage": true,
+    "@aws-cdk/core:target-partitions": [
+      "aws",
+      "aws-cn"
+    ],
+    "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
+    "@aws-cdk/core:stackRelativeExports": true,
+    "@aws-cdk/aws-rds:lowercaseDbIdentifier": true,
+    "@aws-cdk/aws-lambda:recognizeVersionProps": true,
+    "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": true,
+    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
+    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
+    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
+    "@aws-cdk/aws-iam:minimizePolicies": true,
+    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
+    "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
+    "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
+    "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
+    "@aws-cdk/aws-apigateway:disableCloudWatchRole": true,
+    "@aws-cdk/core:enablePartitionLiterals": true,
+    "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
+    "@aws-cdk/aws-iam:standardizedServicePrincipals": true,
+    "@aws-cdk/aws-ecs:disableExplicitDeploymentControllerForCircuitBreaker": true,
+    "@aws-cdk/aws-iam:importedRoleStackSafeDefaultPolicyName": true,
+    "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true,
+    "@aws-cdk/aws-route53-patters:useCertificate": true,
+    "@aws-cdk/customresources:installLatestAwsSdkDefault": false,
+    "@aws-cdk/aws-rds:databaseProxyUniqueResourceName": true,
+    "@aws-cdk/aws-codedeploy:removeAlarmsFromDeploymentGroup": true,
+    "@aws-cdk/aws-apigateway:authorizerChangeDeploymentLogicalId": true,
+    "@aws-cdk/aws-ec2:launchTemplateDefaultUserData": true,
+    "@aws-cdk/aws-secretsmanager:useAttachedSecretResourcePolicyForSecretTargetAttachments": true,
+    "@aws-cdk/aws-redshift:columnId": true,
+    "@aws-cdk/aws-stepfunctions-tasks:enableEmrServicePolicyV2": true,
+    "@aws-cdk/aws-ec2:restrictDefaultSecurityGroup": true,
+    "@aws-cdk/aws-apigateway:requestValidatorUniqueId": true,
+    "@aws-cdk/aws-kms:aliasNameRef": true,
+    "@aws-cdk/aws-autoscaling:generateLaunchTemplateInsteadOfLaunchConfig": true,
+    "@aws-cdk/core:includePrefixInUniqueNameGeneration": true,
+    "@aws-cdk/aws-efs:denyAnonymousAccess": true,
+    "@aws-cdk/aws-opensearchservice:enableOpensearchMultiAzWithStandby": true,
+    "@aws-cdk/aws-lambda-nodejs:useLatestRuntimeVersion": true,
+    "@aws-cdk/aws-efs:mountTargetOrderInsensitiveLogicalId": true,
+    "@aws-cdk/aws-rds:auroraClusterChangeScopeOfInstanceParameterGroupWithEachParameters": true,
+    "@aws-cdk/aws-appsync:useArnForSourceApiAssociationIdentifier": true,
+    "@aws-cdk/aws-rds:preventRenderingDeprecatedCredentials": true,
+    "@aws-cdk/aws-codepipeline-actions:useNewDefaultBranchForCodeCommitSource": true,
+    "@aws-cdk/aws-cloudwatch-actions:changeLambdaPermissionLogicalIdForLambdaAction": true,
+    "@aws-cdk/aws-codepipeline:crossAccountKeysDefaultValueToFalse": true,
+    "@aws-cdk/aws-codepipeline:defaultPipelineTypeToV2": true,
+    "@aws-cdk/aws-kms:reduceCrossAccountRegionPolicyScope": true,
+    "@aws-cdk/aws-eks:nodegroupNameAttribute": true,
+    "@aws-cdk/aws-ec2:ebsDefaultGp3Volume": true,
+    "@aws-cdk/aws-ecs:removeDefaultDeploymentAlarm": true,
+    "@aws-cdk/custom-resources:logApiResponseDataPropertyTrueDefault": false,
+    "@aws-cdk/aws-s3:keepNotificationInImportedBucket": false
+  }
+}

package/out/dist/bin/templates/runtime-web/cdk/package.json.template

@@ -0,0 +1,28 @@
+{
+  "name": "{{STACK_NAME}}-cdk",
+  "version": "0.1.0",
+  "private": true,
+  "description": "CDK infrastructure for {{STACK_NAME}}",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "synth": "cdk synth",
+    "deploy": "cdk deploy --all",
+    "deploy:dev": "cdk deploy --context stage=dev --all",
+    "deploy:staging": "cdk deploy --context stage=staging --all",
+    "deploy:prod": "cdk deploy --context stage=prod --all",
+    "diff": "cdk diff",
+    "destroy": "cdk destroy"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "aws-cdk": "^2.100.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@worktif/purenow": "^{{PURENOW_VERSION}}",
+    "aws-cdk-lib": "^2.100.0",
+    "constructs": "^10.0.0"
+  }
+}

package/out/dist/bin/templates/runtime-web/cdk/tsconfig.json.template

@@ -0,0 +1,38 @@
+{
+  "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,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "experimentalDecorators": true,
+    "strictPropertyInitialization": false,
+    "typeRoots": [
+      "./node_modules/@types"
+    ],
+    "moduleResolution": "node16",
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "bin/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "cdk.out"
+  ]
+}

package/out/dist/bin/templates/runtime-web/purenow-basic/.env.example

@@ -0,0 +1,15 @@
+# Application Configuration
+PURE_ENV_STACK_NAME=purenow-app
+PURE_ENV_STAGE=dev
+
+# AWS Configuration (optional - can be set via AWS CLI or ~/.aws/config)
+# AWS_REGION=us-east-1  # Or eu-central-1, us-west-2, etc.
+# AWS_PROFILE=default
+
+# Development Server
+# PORT=3000
+
+# Feature Flags (optional)
+# PURE_ENV_ENABLE_SEO=false
+# PURE_ENV_ENABLE_MANIFEST=true
+# PURE_ENV_ENABLE_WARMUP=false