@btc-embedded/cdk-extensions 0.22.14 → 0.22.16

package/.jsii

@@ -8497,7 +8497,7 @@
   },
   "name": "@btc-embedded/cdk-extensions",
   "readme": {
-    "markdown": "# BTC Embedded CDK Extensions\n\n# @btc-embedded/cdk-extensions\n\nA collection of reusable AWS CDK (Cloud Development Kit) extensions and constructs for building cloud infrastructure with TypeScript.\n\n## Features\n\n- **CDK Constructs**: Includes ready-to-use constructs for API Gateway, Application Load Balancer, Cognito, VPC, DocumentDB, and more.\n- **ECS Service Extensions**: Provides ECS service extensions for advanced container orchestration.\n- **Utilities**: Common utilities and helpers for stack parameters, value imports, and configuration parsing.\n- **Modular Extensions**: Easily extend AWS resources with features like logging, OpenTelemetry, EFS, Cloud Map, and custom containers.\n\n## Installation\n\n```sh\nyarn install @btc-embedded/cdk-extensions\n```\n\n## Usage Example\n\n### Basic Usage\n\n```typescript\nimport { ApiGateway } from \"@btc-embedded/cdk-extensions\";\n\n// Use constructs and extensions in your CDK app\n```\n\n### Using ApplicationStack for Simplified Configuration\n\nFor application-level stacks that reference a base platform stack, use `ApplicationStack` to ensure consistent use of the base platform stack name:\n\n```typescript\nimport { ApplicationStack } from \"@btc-embedded/cdk-extensions\";\n\nexport class MyAppStack extends ApplicationStack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id, {\n      basePlatformStackName: \"my-platform-stack\",\n      env: {\n        account: \"123456789012\",\n        region: \"eu-central-1\",\n      },\n    });\n\n    // Constructs and extensions automatically resolve the platform stack name\n    // No need to pass basePlatformStackName repeatedly\n  }\n}\n```\n\n### Config-Driven Deployments\n\nUse `createApplicationApp` for configuration-driven deployments:\n\n```typescript\nimport {\n  createApplicationApp,\n  ApplicationStack,\n} from \"@btc-embedded/cdk-extensions\";\nimport { z } from \"zod\";\n\nconst configSchema = z.object({\n  env: z.object({ account: z.string(), region: z.string() }),\n  basePlatformStackName: z.string(),\n});\n\ncreateApplicationApp({\n  directory: \"./config\",\n  schema: configSchema,\n  createStack: (scope, config) => new MyAppStack(scope, \"MyApp\", config),\n});\n```\n\n## CLI Commands\n\n### catnip — Cloud Toolkit by the CAT Department\n\nThe `catnip` CLI tool provides commands for cloud infrastructure diagnostics and management.\n\n#### stack-diagnose\n\nDiagnose CloudFormation stack deployment failures.\n\n**Usage:**\n\n```bash\n# Auto-detect and diagnose the last failed stack\ncatnip stack-diagnose\n\n# Diagnose a specific stack\ncatnip stack-diagnose --stack-name my-stack\n\n# Customize log output and task inspection\ncatnip stack-diagnose --stack-name my-stack --tail 200 --tasks 10\n```\n\n**Description:**\n\nThe `stack-diagnose` command provides comprehensive diagnostics for failed CloudFormation stacks. If no stack name is provided, it automatically detects and diagnoses the last failed stack in your AWS account. The command displays:\n\n- **Stack Status**: Current CloudFormation stack status and reason for failure\n- **CloudFormation Events**: Recent stack events showing what failed during deployment\n- **ECS Diagnostics** (if applicable): If the stack contains ECS services, additional diagnostics are performed including:\n  - Service event history\n  - Recent stopped task logs\n  - Container output for troubleshooting\n\n**Options:**\n\n- `--stack-name <name>` — CloudFormation stack name (optional; auto-detects last failed stack if omitted)\n- `--stage <name>` — Filter stacks by stage name (e.g., 'prod', 'dev') when auto-detecting; only used if --stack-name is not provided\n- `--tail <n>` — Number of log lines to show per container (default: 100)\n- `--tasks <n>` — Number of recent stopped tasks to inspect (default: 5)\n- `--region <region>` — AWS region (uses AWS_DEFAULT_REGION / AWS_REGION environment variable if not specified)\n- `--profile <profile>` — AWS named profile for local development\n\n**Examples:**\n\n```bash\n# Quick diagnosis of last failed stack\ncatnip stack-diagnose\n\n# Auto-detect failed stack for a specific stage (useful when multiple stages in same account)\ncatnip stack-diagnose --stage prod\n\n# Diagnose specific stack with extended logging\ncatnip stack-diagnose --stack-name prod-api-stack --tail 500 --tasks 10\n\n# Use specific AWS profile and region\ncatnip stack-diagnose --profile my-profile --region eu-central-1\n```\n\n#### ecs-logs\n\nStream live logs from running ECS services in a CloudFormation stack.\n\n**Usage:**\n\n```bash\n# Stream logs from all ECS services in a stack\nnpx catnip ecs-logs --stack-name my-stack\n\n# Follow logs in real-time\nnpx catnip ecs-logs --stack-name my-stack --follow\n\n# Filter by service name and show last 50 lines\nnpx catnip ecs-logs --stack-name my-stack --tail 50 --service api\n\n# Raw JSON output (for piping to jq or pino-pretty)\nnpx catnip ecs-logs --stack-name my-stack --output raw\n\n# Pretty-printed JSON with colors\nnpx catnip ecs-logs --stack-name my-stack --output pretty\n```\n\n**Options:**\n\n- `--stack-name <name>` — CloudFormation stack name (required)\n- `--tail <n>` — Lines of history to show per container (default: 100)\n- `-f, --follow` — Keep polling for new log events\n- `--service <name>` — Filter services by name\n- `-o, --output <mode>` — Output mode: `text`, `raw`, or `pretty` (default: text)\n- `--region <region>` — AWS region\n- `--profile <profile>` — AWS profile\n\n## Documentation\n\n- [API Reference](./API.md)\n\n## License\n\nApache-2.0 © BTC Embedded Systems AG\n"
+    "markdown": "# BTC Embedded CDK Extensions\n\n# @btc-embedded/cdk-extensions\n\nA collection of reusable AWS CDK (Cloud Development Kit) extensions and constructs for building cloud infrastructure with TypeScript.\n\n## Features\n\n- **CDK Constructs**: Includes ready-to-use constructs for API Gateway, Application Load Balancer, Cognito, VPC, DocumentDB, and more.\n- **ECS Service Extensions**: Provides ECS service extensions for advanced container orchestration.\n- **Utilities**: Common utilities and helpers for stack parameters, value imports, and configuration parsing.\n- **Modular Extensions**: Easily extend AWS resources with features like logging, OpenTelemetry, EFS, Cloud Map, and custom containers.\n\n## Installation\n\n```sh\nyarn install @btc-embedded/cdk-extensions\n```\n\n## Usage Example\n\n### Basic Usage\n\n```typescript\nimport { ApiGateway } from \"@btc-embedded/cdk-extensions\";\n\n// Use constructs and extensions in your CDK app\n```\n\n### Using ApplicationStack for Simplified Configuration\n\nFor application-level stacks that reference a base platform stack, use `ApplicationStack` to ensure consistent use of the base platform stack name:\n\n```typescript\nimport { ApplicationStack } from \"@btc-embedded/cdk-extensions\";\n\nexport class MyAppStack extends ApplicationStack {\n  constructor(scope: Construct, id: string) {\n    super(scope, id, {\n      basePlatformStackName: \"my-platform-stack\",\n      env: {\n        account: \"123456789012\",\n        region: \"eu-central-1\",\n      },\n    });\n\n    // Constructs and extensions automatically resolve the platform stack name\n    // No need to pass basePlatformStackName repeatedly\n  }\n}\n```\n\n### Config-Driven Deployments\n\nUse `createApplicationApp` for configuration-driven deployments:\n\n```typescript\nimport {\n  createApplicationApp,\n  ApplicationStack,\n} from \"@btc-embedded/cdk-extensions\";\nimport { z } from \"zod\";\n\nconst configSchema = z.object({\n  env: z.object({ account: z.string(), region: z.string() }),\n  basePlatformStackName: z.string(),\n});\n\ncreateApplicationApp({\n  directory: \"./config\",\n  schema: configSchema,\n  createStack: (scope, config) => new MyAppStack(scope, \"MyApp\", config),\n});\n```\n\n## CLI Commands\n\n### catnip — Cloud Toolkit by the CAT Department\n\n`catnip` provides operational helpers for CloudFormation, ECS, and Cognito.\n\nGlobal options (apply to all commands):\n- `--region <region>` — AWS region (defaults to `AWS_DEFAULT_REGION` / `AWS_REGION`)\n- `--profile <profile>` — AWS named profile\n\n#### stack-diagnose\n\nDiagnose failed CloudFormation deployments and show ECS failure context.\n\nUsage:\n\n```bash\ncatnip stack-diagnose\ncatnip stack-diagnose --stack-name my-stack\ncatnip stack-diagnose --stage prod\ncatnip stack-diagnose --stack-name my-stack --tail 200 --tasks 10\n```\n\nOptions:\n- `--stack-name <name>` — stack to diagnose (optional; auto-detects last failed stack if omitted)\n- `--stage <name>` — stage filter for auto-detection (ignored if `--stack-name` is provided)\n- `--tail <n>` — Number of log lines to show per container (default: 100)\n- `--tasks <n>` — Number of recent stopped tasks to inspect (default: 5)\n\n#### ecs-logs\n\nStream live logs from running ECS services in a CloudFormation stack.\n\nUsage:\n\n```bash\ncatnip ecs-logs --stack-name my-stack\ncatnip ecs-logs --stack-name my-stack --follow\ncatnip ecs-logs --stack-name my-stack --service api --tail 50\ncatnip ecs-logs --stack-name my-stack --output raw\ncatnip ecs-logs --stack-name my-stack --output pretty\n```\n\nOptions:\n- `--stack-name <name>` — CloudFormation stack name (required)\n- `--tail <n>` — Lines of history to show per container (default: 100)\n- `-f, --follow` — Keep polling for new log events\n- `--service <name>` — Filter services by name\n- `-o, --output <mode>` — Output mode: `text`, `raw`, or `pretty` (default: text)\n\n#### oidc-token\n\nFetch a Cognito token using CloudFormation exports from a stack.\n\nUsage:\n\n```bash\ncatnip oidc-token --stack-name my-stack\ncatnip oidc-token --stack-name my-stack --output json\n```\n\nOptions:\n- `--stack-name <name>` — stack that exported Cognito resources (required)\n- `--output <token|json>` — print token only, or full response JSON (default: `token`)\n  - `token` output is the `access_token`\n\n#### pg-tunnel\n\nOpen a secure Session Manager tunnel to Aurora PostgreSQL and launch a local client.\n\nUsage:\n\n```bash\ncatnip pg-tunnel --stack-name my-stack\ncatnip pg-tunnel --stack-name my-stack --exec \"psql\"\ncatnip pg-tunnel --stack-name my-stack --database app\ncatnip pg-tunnel --stack-name my-stack --no-auto-launch\ncatnip pg-tunnel --stage prod\n```\n\nOptions:\n- `--stack-name <name>` — stack where the Aurora cluster is deployed (typically the base platform stack; optional when auto-discovery works)\n- `--stage <name>` — stage filter used during stack auto-discovery\n- `--local-port <port>` — preferred local port (default: `5432`)\n- `--database <name>` — overrides `PGDATABASE` for launched client/shell\n- `--exec <command>` — explicit command to run after tunnel starts\n- `--no-auto-launch` — keep tunnel attached without launching a client/shell\n- `--tunnel-instance-id <id>` — fallback EC2 instance ID when stack export is missing\n\nDatabase selection behavior:\n- if `--database` is provided, that value is used\n- if omitted, `catnip` infers database names from deployed ECS service task definitions (`POSTGRES_DATABASE`)\n- if exactly one database is inferred, it is applied as `PGDATABASE`\n- if multiple databases are inferred, they are printed with source stack/service and `PGDATABASE` remains unset\n\nPrerequisite:\n- `session-manager-plugin` must be installed and available in `PATH`\n\n## Documentation\n\n- [API Reference](./API.md)\n\n## License\n\nApache-2.0 © BTC Embedded Systems AG\n"
   },
   "repository": {
     "type": "git",
@@ -11160,6 +11160,367 @@
       ],
       "symbolId": "src/stacks/ApplicationStack:ApplicationStackProps"
     },
+    "@btc-embedded/cdk-extensions.AuroraPostgresCluster": {
+      "assembly": "@btc-embedded/cdk-extensions",
+      "base": "constructs.Construct",
+      "docs": {
+        "remarks": "Exports:\n- `aurora-postgres-db:secret-arn`\n- `aurora-postgres-db:credentials-secret-arn`\n- `aurora-postgres-db:cluster-endpoint`\n- `aurora-postgres-db:security-group-id`\n- `aurora-postgres-db:tunnel-instance-id` (only when tunnel host is enabled)",
+        "stability": "experimental",
+        "summary": "Provisions an Aurora PostgreSQL Serverless v2 cluster and exports connection metadata."
+      },
+      "fqn": "@btc-embedded/cdk-extensions.AuroraPostgresCluster",
+      "initializer": {
+        "docs": {
+          "stability": "experimental"
+        },
+        "locationInModule": {
+          "filename": "src/platform/AuroraPostgresDB.ts",
+          "line": 165
+        },
+        "parameters": [
+          {
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "name": "props",
+            "type": {
+              "fqn": "@btc-embedded/cdk-extensions.AuroraPostgresClusterProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/platform/AuroraPostgresDB.ts",
+        "line": 128
+      },
+      "name": "AuroraPostgresCluster",
+      "properties": [
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Aurora database cluster."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 160
+          },
+          "name": "cluster",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_rds.DatabaseCluster"
+          }
+        },
+        {
+          "docs": {
+            "stability": "experimental",
+            "summary": "Security group attached to the Aurora cluster."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 163
+          },
+          "name": "securityGroup",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_ec2.SecurityGroup"
+          }
+        }
+      ],
+      "symbolId": "src/platform/AuroraPostgresDB:AuroraPostgresCluster"
+    },
+    "@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides": {
+      "assembly": "@btc-embedded/cdk-extensions",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental",
+        "summary": "Supported override options for Aurora cluster tuning."
+      },
+      "fqn": "@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/platform/AuroraPostgresDB.ts",
+        "line": 81
+      },
+      "name": "AuroraPostgresClusterOverrides",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "default": "- generated by CDK",
+            "stability": "experimental",
+            "summary": "Optional DB cluster identifier."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 87
+          },
+          "name": "clusterIdentifier",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "1",
+            "stability": "experimental",
+            "summary": "Maximum Aurora Serverless v2 capacity."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 108
+          },
+          "name": "serverlessV2MaxCapacity",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "0",
+            "stability": "experimental",
+            "summary": "Minimum Aurora Serverless v2 capacity."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 101
+          },
+          "name": "serverlessV2MinCapacity",
+          "optional": true,
+          "type": {
+            "primitive": "number"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "true",
+            "stability": "experimental",
+            "summary": "Whether storage encryption should be enabled."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 115
+          },
+          "name": "storageEncrypted",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "SubnetType.PRIVATE_WITH_EGRESS",
+            "stability": "experimental",
+            "summary": "Subnets used for cluster instances."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 94
+          },
+          "name": "vpcSubnets",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_ec2.SubnetSelection"
+          }
+        }
+      ],
+      "symbolId": "src/platform/AuroraPostgresDB:AuroraPostgresClusterOverrides"
+    },
+    "@btc-embedded/cdk-extensions.AuroraPostgresClusterProps": {
+      "assembly": "@btc-embedded/cdk-extensions",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental",
+        "summary": "Properties for {@link AuroraPostgresCluster}."
+      },
+      "fqn": "@btc-embedded/cdk-extensions.AuroraPostgresClusterProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/platform/AuroraPostgresDB.ts",
+        "line": 58
+      },
+      "name": "AuroraPostgresClusterProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Instance name used for the optional tunnel host."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 65
+          },
+          "name": "instanceName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "VPC to deploy the Aurora cluster into."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 60
+          },
+          "name": "vpc",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_ec2.IVpc"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Optional Aurora cluster overrides."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 70
+          },
+          "name": "clusterProps",
+          "optional": true,
+          "type": {
+            "fqn": "@btc-embedded/cdk-extensions.AuroraPostgresClusterOverrides"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "experimental",
+            "summary": "Optional settings for the tunnel host."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 75
+          },
+          "name": "tunnelHost",
+          "optional": true,
+          "type": {
+            "fqn": "@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps"
+          }
+        }
+      ],
+      "symbolId": "src/platform/AuroraPostgresDB:AuroraPostgresClusterProps"
+    },
+    "@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps": {
+      "assembly": "@btc-embedded/cdk-extensions",
+      "datatype": true,
+      "docs": {
+        "stability": "experimental",
+        "summary": "Optional settings for the SSM-managed tunnel host used by `catnip pg-tunnel`."
+      },
+      "fqn": "@btc-embedded/cdk-extensions.AuroraPostgresTunnelHostProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/platform/AuroraPostgresDB.ts",
+        "line": 23
+      },
+      "name": "AuroraPostgresTunnelHostProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "default": "false",
+            "remarks": "Useful for environments without NAT internet egress.",
+            "stability": "experimental",
+            "summary": "Whether to create SSM interface endpoints in the VPC (ssm, ssmmessages, ec2messages)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 52
+          },
+          "name": "createSsmVpcEndpoints",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "false",
+            "stability": "experimental",
+            "summary": "Whether a dedicated EC2 tunnel host should be provisioned."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 29
+          },
+          "name": "enabled",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "t3.nano",
+            "stability": "experimental",
+            "summary": "Instance type used for the tunnel host."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 36
+          },
+          "name": "instanceType",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_ec2.InstanceType"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "SubnetType.PRIVATE_WITH_EGRESS",
+            "stability": "experimental",
+            "summary": "Subnet type where the tunnel host will be placed."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/platform/AuroraPostgresDB.ts",
+            "line": 43
+          },
+          "name": "subnetType",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_ec2.SubnetType"
+          }
+        }
+      ],
+      "symbolId": "src/platform/AuroraPostgresDB:AuroraPostgresTunnelHostProps"
+    },
     "@btc-embedded/cdk-extensions.BTCLogGroup": {
       "assembly": "@btc-embedded/cdk-extensions",
       "base": "aws-cdk-lib.aws_logs.LogGroup",
@@ -19883,6 +20244,6 @@
       "symbolId": "src/platform/VpcV2:VpcV2Props"
     }
   },
-  "version": "0.22.14",
-  "fingerprint": "U8Tf9Fotr6vHDrm2zRyhR1fc7JPRXSPw+mJRL6JSFRI="
+  "version": "0.22.16",
+  "fingerprint": "g55SPFzxNHVUi3lhCDbVj9IKCFY/F0h+07nBKM1a2gU="
 }