lambda-forge-cli-aws 1.0.0__py3-none-any.whl

templates/python-api/{{cookiecutter.project_slug}}/.github/workflows/deploy.yml

@@ -0,0 +1,90 @@
+name: Deploy {{ cookiecutter.project_name }}
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+env:
+  AWS_REGION: us-east-1
+  STACK_NAME: {{ cookiecutter.project_slug }}-prod
+
+jobs:
+  test:
+    name: Test + Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Type check (mypy)
+        run: mypy src/
+
+      - name: Test (pytest)
+        run: pytest --cov-report=xml
+        env:
+          AWS_DEFAULT_REGION: us-east-1
+          AWS_ACCESS_KEY_ID: test
+          AWS_SECRET_ACCESS_KEY: test
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        if: always()
+        with:
+          file: coverage.xml
+
+  deploy:
+    name: Deploy to AWS
+    needs: test
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+{% raw %}
+      - name: Configure AWS credentials (OIDC)
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+          aws-region: ${{ env.AWS_REGION }}
+
+      - name: Install CDK
+        run: npm install -g aws-cdk
+
+      - name: Install CDK dependencies
+        working-directory: infrastructure
+        run: npm install
+
+      - name: CDK Diff
+        working-directory: infrastructure
+        run: cdk diff ${{ env.STACK_NAME }} || true
+
+      - name: CDK Deploy
+        working-directory: infrastructure
+        run: cdk deploy ${{ env.STACK_NAME }} --require-approval never
+{% endraw %}

templates/python-api/{{cookiecutter.project_slug}}/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# CDK
+cdk.out/
+cdk.context.json
+
+# Lambda
+*.zip
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Secrets
+*.pem
+*.key
+secrets.yml

templates/python-api/{{cookiecutter.project_slug}}/Dockerfile

@@ -0,0 +1,11 @@
+FROM public.ecr.aws/lambda/python:3.12-arm64
+
+# Install dependencies first for better layer caching
+COPY requirements.txt ${LAMBDA_TASK_ROOT}/
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy function code
+COPY src/ ${LAMBDA_TASK_ROOT}/
+
+# Set the handler
+CMD [ "handler.handler" ]

templates/python-api/{{cookiecutter.project_slug}}/README.md

@@ -0,0 +1,130 @@
+# {{ cookiecutter.project_name }}
+
+> {{ cookiecutter.description }}
+
+Serverless API built with AWS Lambda + API Gateway, generated by [LambdaForge](https://github.com/lambdaforge/lambdaforge).
+
+## Architecture
+
+```
+Client -> API Gateway (REST) -> Lambda (ARM64) -> DynamoDB
+                                  |
+                                  -> CloudWatch Logs/Metrics/Traces (X-Ray)
+```
+
+- **Runtime**: Python 3.12 (ARM64 - 20% cheaper, 19% faster than x86_64)
+- **Observability**: aws-lambda-powertools (structured logs, metrics, traces)
+- **IaC**: AWS CDK TypeScript
+- **Cost**: Designed to fit in AWS Free Tier (<1M req/month)
+
+## Project Structure
+
+```
+{{ cookiecutter.project_slug }}/
+├── src/
+│   ├── handler.py          # Lambda entry point
+│   └── utils/
+│       └── logger.py       # Powertools logger config
+├── tests/
+│   ├── conftest.py         # pytest fixtures (moto for AWS mocking)
+│   └── test_handler.py     # Unit + integration tests
+├── infrastructure/
+│   ├── app.js              # CDK app entry (JavaScript)
+│   ├── cdk.json            # CDK config
+│   ├── package.json        # CDK dependencies
+│   └── lib/
+│       └── stack.js        # CDK stack (multi-env: dev/staging/prod)
+├── .kiro/
+│   └── specs/              # Generated Kiro specs
+├── Dockerfile              # Container image (used by CDK)
+├── pyproject.toml          # Dependencies + tooling config
+└── README.md
+```
+
+## Local Development
+
+```bash
+# Install dependencies
+pip install -r requirements-dev.txt
+
+# Run tests (uses moto for AWS mocking - no real AWS calls)
+pytest
+
+# Run with type checking + linting
+ruff check .
+mypy src/
+```
+
+## Deployment
+
+```bash
+# First time: bootstrap CDK
+npx cdk bootstrap aws://ACCOUNT_ID/REGION
+
+# Deploy
+npx cdk deploy
+
+# Or via LambdaForge
+lambdaforge deploy --stack {{ cookiecutter.project_slug }}-dev
+```
+
+## API
+
+### `POST /items`
+
+Create a new item.
+
+**Request body**:
+```json
+{
+  "key": "user-123",
+  "data": {
+    "name": "Ada Lovelace",
+    "role": "engineer"
+  }
+}
+```
+
+**Response** (201 Created):
+```json
+{
+  "key": "user-123",
+  "data": { "name": "Ada Lovelace", "role": "engineer" },
+  "createdAt": "2026-07-23T10:12:43.123Z"
+}
+```
+
+### `GET /items/{key}`
+
+Retrieve an item by key.
+
+**Response** (200 OK):
+```json
+{
+  "key": "user-123",
+  "data": { "name": "Ada Lovelace", "role": "engineer" },
+  "createdAt": "2026-07-23T10:12:43.123Z",
+  "updatedAt": "2026-07-23T10:12:43.123Z"
+}
+```
+
+## Observability
+
+- **Logs**: CloudWatch Logs (`/aws/lambda/{{ cookiecutter.project_slug }}`)
+- **Metrics**: CloudWatch Metrics (custom namespace `{{ cookiecutter.project_slug }}`)
+- **Traces**: X-Ray (end-to-end through API Gateway + Lambda + DynamoDB)
+- **Dashboard**: CloudWatch Dashboard created by CDK stack
+
+## Cost Estimate (Free Tier)
+
+| Resource | Free Tier | Estimated |
+|----------|-----------|-----------|
+| Lambda | 1M req + 400k GB-s | $0 (under) |
+| API Gateway | 1M calls | $0 (under) |
+| DynamoDB | 25 GB + 25 WCU/RCU | $0 (under) |
+
+Beyond Free Tier (worst case 10M req/month): **~$5/month**
+
+## License
+
+MIT © {{ cookiecutter.author_name }}

templates/python-api/{{cookiecutter.project_slug}}/infrastructure/app.js

@@ -0,0 +1,26 @@
+const cdk = require('aws-cdk-lib');
+const { {{ cookiecutter.project_name|replace('-', '')|capitalize }}Stack } = require('./lib/stack');
+
+const app = new cdk.App();
+
+// Environment from CDK context (default: dev)
+const envName = app.node.tryGetContext('env') || 'dev';
+
+new {{ cookiecutter.project_name|replace('-', '')|capitalize }}Stack(app, `{{ cookiecutter.project_name }}-${envName}`, {
+  stackName: `{{ cookiecutter.project_name }}-${envName}`,
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION || '{{ cookiecutter.aws_region }}',
+  },
+  description: `{{ cookiecutter.description }} (${envName})`,
+  tags: {
+    Project: '{{ cookiecutter.project_name }}',
+    Environment: envName,
+    ManagedBy: 'LambdaForge',
+    CostCenter: '{{ cookiecutter.project_name }}',
+  },
+  // Pass environment to the stack
+  envName: envName,
+});
+
+app.synth();

templates/python-api/{{cookiecutter.project_slug}}/infrastructure/cdk.json

@@ -0,0 +1,20 @@
+{
+  "app": "node app.js",
+  "watch": {
+    "include": ["**"],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "node_modules",
+      "tests"
+    ]
+  },
+  "context": {
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+    "@aws-cdk/core:checkSecretUsage": true,
+    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
+    "@aws-cdk/aws-iam:minimizePolicies": true,
+    "@aws-cdk/customresources:installLatestAwsSdkDefault": false,
+    "@aws-cdk/aws-s3:serverAccessLogsUseBucketPolicy": true
+  }
+}

templates/python-api/{{cookiecutter.project_slug}}/infrastructure/lib/stack.js

@@ -0,0 +1,155 @@
+const cdk = require('aws-cdk-lib');
+const lambda = require('aws-cdk-lib/aws-lambda');
+const apigateway = require('aws-cdk-lib/aws-apigateway');
+const dynamodb = require('aws-cdk-lib/aws-dynamodb');
+const logs = require('aws-cdk-lib/aws-logs');
+const cloudwatch = require('aws-cdk-lib/aws-cloudwatch');
+
+/**
+ * Environment-specific configuration.
+ * Adjust memory, timeout, and policies per environment.
+ */
+const ENV_CONFIG = {
+  dev: {
+    memorySize: {{ cookiecutter.memory_mb }},
+    timeout: {{ cookiecutter.timeout_seconds }},
+    logRetention: logs.RetentionDays.ONE_DAY,
+    removalPolicy: cdk.RemovalPolicy.DESTROY,
+    throttlingRate: 50,
+    throttlingBurst: 100,
+  },
+  staging: {
+    memorySize: {{ cookiecutter.memory_mb }},
+    timeout: {{ cookiecutter.timeout_seconds }},
+    logRetention: logs.RetentionDays.ONE_WEEK,
+    removalPolicy: cdk.RemovalPolicy.DESTROY,
+    throttlingRate: 100,
+    throttlingBurst: 200,
+  },
+  prod: {
+    memorySize: 1024,
+    timeout: {{ cookiecutter.timeout_seconds }},
+    logRetention: logs.RetentionDays.ONE_MONTH,
+    removalPolicy: cdk.RemovalPolicy.RETAIN,
+    throttlingRate: 200,
+    throttlingBurst: 400,
+  },
+};
+
+/**
+ * CDK Stack for {{ cookiecutter.project_name }}
+ *
+ * Generated by LambdaForge — production-ready Lambda with:
+ * - API Gateway REST API with throttling
+ * - DynamoDB table (on-demand)
+ * - X-Ray tracing
+ * - CloudWatch logs + dashboard
+ * - Well-Architected tags
+ * - Multi-environment support (dev/staging/prod)
+ */
+class {{ cookiecutter.project_name|replace('-', '')|capitalize }}Stack extends cdk.Stack {
+  constructor(scope, id, props) {
+    super(scope, id, props);
+
+    const envName = props.envName || 'dev';
+    const config = ENV_CONFIG[envName] || ENV_CONFIG.dev;
+
+    // ============================================================
+    // DynamoDB Table
+    // ============================================================
+    const table = new dynamodb.Table(this, 'ItemsTable', {
+      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
+      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+      pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: true },
+      removalPolicy: config.removalPolicy,
+    });
+
+    // ============================================================
+    // Lambda Function (ARM64 — 20% cheaper)
+    // ============================================================
+    const fn = new lambda.Function(this, '{{ cookiecutter.project_name|replace('-', '')|capitalize }}Function', {
+      runtime: lambda.Runtime.PYTHON_3_12,
+      architecture: lambda.Architecture.ARM_64,
+      handler: 'handler.handler',
+      code: lambda.Code.fromAsset('../src'),
+      memorySize: config.memorySize,
+      timeout: cdk.Duration.seconds(config.timeout),
+      tracing: lambda.Tracing.ACTIVE,
+      logGroup: new logs.LogGroup(this, 'FunctionLogGroup', {
+        logGroupName: `/aws/lambda/{{ cookiecutter.project_slug }}-${envName}`,
+        retention: config.logRetention,
+        removalPolicy: config.removalPolicy,
+      }),
+      environment: {
+        TABLE_NAME: table.tableName,
+        STAGE: envName,
+        POWERTOOLS_SERVICE_NAME: '{{ cookiecutter.project_slug }}',
+        LOG_LEVEL: envName === 'prod' ? 'WARNING' : 'INFO',
+      },
+    });
+
+    table.grantReadWriteData(fn);
+
+    // ============================================================
+    // API Gateway
+    // ============================================================
+    const api = new apigateway.RestApi(this, '{{ cookiecutter.project_name|replace('-', '')|capitalize }}Api', {
+      restApiName: `{{ cookiecutter.project_slug }}-${envName}`,
+      description: `{{ cookiecutter.description }} (${envName})`,
+      deployOptions: {
+        stageName: envName,
+        tracingEnabled: true,
+        loggingLevel: apigateway.MethodLoggingLevel.INFO,
+        dataTraceEnabled: false,
+        throttlingRateLimit: config.throttlingRate,
+        throttlingBurstLimit: config.throttlingBurst,
+      },
+    });
+
+    const items = api.root.addResource('items');
+    items.addMethod('GET', new apigateway.LambdaIntegration(fn));
+    items.addMethod('POST', new apigateway.LambdaIntegration(fn));
+
+    const health = api.root.addResource('health');
+    health.addMethod('GET', new apigateway.LambdaIntegration(fn));
+
+    // ============================================================
+    // CloudWatch Dashboard
+    // ============================================================
+    const dashboard = new cloudwatch.Dashboard(this, '{{ cookiecutter.project_name|replace('-', '')|capitalize }}Dashboard', {
+      dashboardName: `{{ cookiecutter.project_slug }}-${envName}`,
+    });
+
+    dashboard.addWidgets(
+      new cloudwatch.GraphWidget({
+        title: 'Invocations & Errors',
+        left: [fn.metricInvocations()],
+        right: [fn.metricErrors()],
+      }),
+      new cloudwatch.GraphWidget({
+        title: 'Duration (ms)',
+        left: [
+          fn.metricDuration({ statistic: 'p50' }),
+          fn.metricDuration({ statistic: 'p95' }),
+        ],
+      }),
+    );
+
+    // ============================================================
+    // Tags (Well-Architected)
+    // ============================================================
+    cdk.Tags.of(this).add('Project', '{{ cookiecutter.project_name }}');
+    cdk.Tags.of(this).add('ManagedBy', 'LambdaForge');
+    cdk.Tags.of(this).add('Environment', envName);
+
+    // ============================================================
+    // Outputs
+    // ============================================================
+    new cdk.CfnOutput(this, 'ApiUrl', { value: api.url });
+    new cdk.CfnOutput(this, 'TableName', { value: table.tableName });
+    new cdk.CfnOutput(this, 'FunctionName', { value: fn.functionName });
+    new cdk.CfnOutput(this, 'Environment', { value: envName });
+  }
+}
+
+module.exports = { {{ cookiecutter.project_name|replace('-', '')|capitalize }}Stack };

templates/python-api/{{cookiecutter.project_slug}}/infrastructure/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{ cookiecutter.project_slug }}-infrastructure",
+  "version": "0.1.0",
+  "description": "AWS CDK infrastructure for {{ cookiecutter.project_name }}",
+  "private": true,
+  "scripts": {
+    "cdk": "cdk",
+    "synth": "cdk synth",
+    "deploy": "cdk deploy --require-approval never",
+    "destroy": "cdk destroy --force",
+    "diff": "cdk diff"
+  },
+  "dependencies": {
+    "aws-cdk-lib": "^2.170.0",
+    "constructs": "^10.4.0"
+  }
+}

templates/python-api/{{cookiecutter.project_slug}}/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "{{ cookiecutter.project_slug }}"
+version = "0.1.0"
+description = "{{ cookiecutter.description }}"
+authors = [
+    {name = "{{ cookiecutter.author_name }}", email = "{{ cookiecutter.author_email }}"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+keywords = ["aws", "lambda", "serverless", "kiro"]
+
+dependencies = [
+    "aws-lambda-powertools[tracer,logger,metrics]>=3.0.0",
+    "boto3>=1.34.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "moto[dynamodb,apigateway]>=5.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.7.0",
+    "aws-cdk-lib>=2.130.0",
+    "constructs>=10.3.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers --cov=src --cov-report=term-missing"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "S", "RUF"]
+ignore = ["S101"]  # allow assert in tests
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+disallow_untyped_defs = true
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]

templates/python-api/{{cookiecutter.project_slug}}/requirements-dev.txt

@@ -0,0 +1,8 @@
+-r requirements.txt
+pytest>=7.4.0
+pytest-cov>=4.1.0
+moto[dynamodb,apigateway]>=5.0.0
+ruff>=0.1.0
+mypy>=1.7.0
+aws-cdk-lib>=2.130.0
+constructs>=10.3.0

templates/python-api/{{cookiecutter.project_slug}}/requirements.txt

@@ -0,0 +1,3 @@
+aws-lambda-powertools[tracer,logger,metrics]>=3.0.0
+boto3>=1.34.0
+pydantic>=2.5.0

templates/python-api/{{cookiecutter.project_slug}}/src/handler.py

@@ -0,0 +1,93 @@
+"""{{ cookiecutter.project_name }} — Lambda handler.
+
+API Gateway trigger with structured logging and error handling.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import boto3
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+# Initialize powertools
+logger = Logger(service="{{ cookiecutter.project_slug }}")
+tracer = Tracer(service="{{ cookiecutter.project_slug }}")
+
+# API Gateway resolver
+app = APIGatewayRestResolver()
+
+# Environment variables
+TABLE_NAME = os.environ.get("TABLE_NAME", "")
+STAGE = os.environ.get("STAGE", "dev")
+
+# AWS clients (initialized once per container)
+dynamodb = boto3.resource("dynamodb")
+
+
+@app.get("/health")
+@tracer.capture_method
+def health_check() -> dict[str, Any]:
+    """Health check endpoint."""
+    return {"status": "ok", "stage": STAGE}
+
+
+@app.get("/items")
+@tracer.capture_method
+def list_items() -> dict[str, Any]:
+    """List all items from the DynamoDB table."""
+    if not TABLE_NAME:
+        logger.warning("TABLE_NAME not set, returning empty list")
+        return {"items": [], "count": 0}
+
+    try:
+        table = dynamodb.Table(TABLE_NAME)
+        response = table.scan()
+        items = response.get("Items", [])
+
+        logger.info("items_listed", extra={"count": len(items)})
+        return {"items": items, "count": len(items)}
+
+    except Exception:
+        logger.exception("list_items_failed")
+        raise
+
+
+@app.post("/items")
+@tracer.capture_method
+def create_item() -> dict[str, Any]:
+    """Create a new item in the DynamoDB table."""
+    import uuid
+    from datetime import datetime
+
+    body = app.current_event.json_body
+    if not body or "name" not in body:
+        return {"error": "Missing required field: name"}, 400
+
+    item = {
+        "id": str(uuid.uuid4()),
+        "name": body["name"],
+        "created_at": datetime.utcnow().isoformat(),
+        **body,
+    }
+
+    try:
+        table = dynamodb.Table(TABLE_NAME)
+        table.put_item(Item=item)
+
+        logger.info("item_created", extra={"item_id": item["id"]})
+        return {"item": item}, 201
+
+    except Exception:
+        logger.exception("create_item_failed")
+        raise
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
+@tracer.capture_lambda_handler
+def handler(event: dict, context: LambdaContext) -> dict[str, Any]:
+    """Main Lambda handler — routes to APIGatewayRestResolver."""
+    return app.resolve(event, context)