@phila/cli 0.0.1

package/dist/templates/lambda-dynamo-api/README.md.tmpl

@@ -0,0 +1,184 @@
+# {{appName}}
+
+Lambda DynamoDB API application using Philadelphia constructs and philaroute.
+
+Generated on {{timestamp}}
+
+## Architecture
+
+![Architecture Diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/lambda-dynamo-api.drawio)
+
+View the [architecture diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/lambda-dynamo-api.drawio) in draw.io or VS Code with the Draw.io extension.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- AWS CLI configured with SSO
+- AWS profile named `phila-{{appName}}`
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build all packages
+npm run build
+```
+
+### Deployment
+
+```bash
+# Configure AWS profile
+export AWS_PROFILE=phila-{{appName}}
+
+# Deploy to dev environment
+city deploy dev
+
+# Deploy to test environment
+city deploy test
+
+# Deploy to production (requires confirmation)
+city deploy prod
+```
+
+### Development
+
+```bash
+# Build TypeScript
+npm run build
+
+# View CDK diff before deploying
+npm run diff
+
+# Synthesize CloudFormation template
+npm run synth
+```
+
+## Project Structure
+
+```
+.
+├── cdk/                    # CDK infrastructure code
+│   └── app.ts              # Main CDK application
+├── apps/                   # Lambda function code
+│   └── {{lambdaName}}/     # Lambda handler
+│       └── index.ts        # Handler with DynamoDB operations
+└── city.config.json        # City CLI configuration
+```
+
+## API Usage
+
+After deployment, the API URL is available in SSM Parameter Store:
+
+```bash
+aws ssm get-parameter --name "/dev/{{appName}}/api/main/url" --query Parameter.Value --output text
+```
+
+Or use the City CLI:
+
+```bash
+city config list --env dev
+```
+
+## DynamoDB Operations
+
+The template includes example CRUD operations using AWS SDK v3:
+
+```typescript
+import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand } from '@aws-sdk/lib-dynamodb';
+
+// Get item
+const result = await docClient.send(new GetCommand({
+  TableName: TABLE_NAME,
+  Key: { pk: id },
+}));
+
+// Put item
+await docClient.send(new PutCommand({
+  TableName: TABLE_NAME,
+  Item: { pk: id, ...data },
+}));
+
+// Delete item
+await docClient.send(new DeleteCommand({
+  TableName: TABLE_NAME,
+  Key: { pk: id },
+}));
+```
+
+## Routing with philaroute
+
+This template uses [@phila/philaroute](https://www.npmjs.com/package/@phila/philaroute) for HTTP routing with composable pipelines.
+
+### Validation
+
+Use built-in validation utilities:
+
+```typescript
+import { validate } from '@phila/philaroute';
+
+items.post([
+  validate.body(['id', 'name']),  // Validates required body fields
+  validate.params(['id']),        // Validates required path params
+  async (acc) => { ... }
+]);
+```
+
+### Assertions
+
+Use `validate.assert` for conditional checks - throws 400 for assertion failures:
+
+```typescript
+validate.assert(item, 'Item not found', 404);
+```
+
+## Environment Variables
+
+Lambda functions automatically receive:
+- `APP_NAME` - Application name ({{appName}})
+- `ENVIRONMENT` - Current environment (dev/test/prod)
+- `TABLE_NAME` - DynamoDB table name
+- `TABLE_ARN` - DynamoDB table ARN
+
+## DynamoDB Table Configuration
+
+The default table uses a single partition key (`pk`). To modify:
+
+1. Edit `cdk/app.ts` to change key schema:
+   ```typescript
+   partitionKey: { name: 'pk', type: 'S' },
+   sortKey: { name: 'sk', type: 'S' },  // Uncomment for composite key
+   enableStream: true,                   // Uncomment for streams
+   ```
+
+2. Update handler code to match your key schema
+
+## Resources Created
+
+This application creates:
+- **API Gateway REST API** - HTTP endpoint for your application
+- **Lambda Function** - Serverless compute for handling requests
+- **DynamoDB Table** - NoSQL database with pay-per-request billing
+- **VPC Security Group** - Network security for Lambda
+- **IAM Role** - Permissions for Lambda execution (DynamoDB read/write)
+- **SSM Parameters** - Resource discovery (API URL, Table Name, Lambda ARN)
+- **CloudWatch Logs** - Application logs
+
+## Next Steps
+
+1. Define your data model and update key schema in `cdk/app.ts`
+2. Implement your routes in `apps/{{lambdaName}}/index.ts`
+3. Add validation and business logic using philaroute pipelines
+4. Write tests for your handlers
+5. Set up CI/CD pipeline
+
+## Support
+
+For issues or questions:
+- [Philadelphia Infrastructure Library Documentation](https://github.com/CityOfPhiladelphia/phila-ctl)
+- [philaroute Documentation](https://www.npmjs.com/package/@phila/philaroute)
+- [DynamoDB Developer Guide](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/)
+- [AWS SDK v3 DynamoDB](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/)

package/dist/templates/lambda-dynamo-api/apps/__lambdaName__/index.ts

@@ -0,0 +1,109 @@
+// ABOUTME: Lambda API handler with DynamoDB database connection
+// ABOUTME: Uses philaroute for routing with DynamoDB DocumentClient
+
+/**
+ * HTTP routing using @phila/philaroute
+ * @see https://github.com/CityOfPhiladelphia/philaroute
+ *
+ * DynamoDB integration using AWS SDK v3 DocumentClient
+ */
+
+import type { APIGWV1Payload } from '@phila/philaroute/dist/types';
+import type { RestAccumulator } from '@phila/philaroute/dist/types';
+import { Router, http, validate } from '@phila/philaroute';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+  DeleteCommand,
+} from '@aws-sdk/lib-dynamodb';
+
+const client = new DynamoDBClient({});
+const docClient = DynamoDBDocumentClient.from(client);
+
+const TABLE_NAME = process.env.TABLE_NAME!;
+
+const router = Router({
+  cors: {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Method': 'GET,POST,PUT,DELETE,OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type,Authorization',
+  },
+});
+
+const health = {
+  check: async (acc: RestAccumulator) => {
+    acc.data.status = 'healthy';
+    acc.data.timestamp = new Date().toISOString();
+    return acc;
+  },
+};
+
+const items = {
+  get: async (acc: RestAccumulator) => {
+    const id = acc.data.valid.parameters.id;
+    const result = await docClient.send(
+      new GetCommand({
+        TableName: TABLE_NAME,
+        Key: { pk: id },
+      })
+    );
+
+    validate.assert(result.Item, 'Item not found', 404);
+
+    acc.data.item = result.Item;
+    return acc;
+  },
+
+  create: async (acc: RestAccumulator) => {
+    const body = acc.data.valid.body;
+    const item = {
+      pk: body.id,
+      ...body,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    await docClient.send(
+      new PutCommand({
+        TableName: TABLE_NAME,
+        Item: item,
+      })
+    );
+
+    acc.data.message = 'Item created';
+    acc.data.item = item;
+    return acc;
+  },
+
+  delete: async (acc: RestAccumulator) => {
+    const id = acc.data.valid.parameters.id;
+
+    await docClient.send(
+      new DeleteCommand({
+        TableName: TABLE_NAME,
+        Key: { pk: id },
+      })
+    );
+
+    acc.data.message = 'Item deleted';
+    return acc;
+  },
+};
+
+// Route definitions
+// The router automatically responds with 200 and acc.data as body.
+// Use http.response({ statusCode }) only when overriding (e.g., 201 for POST).
+
+router.path('/health').get([health.check]);
+
+router.path('/items/:id').get([validate.parameters(['id']), items.get]);
+
+router
+  .path('/items')
+  .post([validate.body({ id: 'string' }), items.create, http.response({ statusCode: 201 })]);
+
+router.path('/items/:id').delete([validate.parameters(['id']), items.delete]);
+
+export const handler = async (event: APIGWV1Payload) => router.routeToPath(event);

package/dist/templates/lambda-dynamo-api/apps/__lambdaName__/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "{{lambdaName}}",
+  "version": "1.0.0",
+  "description": "Lambda function handler with DynamoDB",
+  "private": true,
+  "scripts": {
+    "build": "npx tsc",
+    "watch": "npx tsc -w"
+  },
+  "dependencies": {
+    "@phila/philaroute": "^1.0.12",
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
+    "@types/aws-lambda": "^8.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}

package/dist/templates/lambda-dynamo-api/apps/__lambdaName__/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "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,
+    "outDir": "./dist",
+    "rootDir": "./"
+  },
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/lambda-dynamo-api/cdk/app.ts.tmpl

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import { App, Aspects, Stack } from 'aws-cdk-lib';
+import { AwsSolutionsChecks, NIST80053R5Checks } from 'cdk-nag';
+import { LambdaDynamoApi, Confidentiality, Environment } from '@phila/constructs';
+
+const app = new App();
+
+// Environment is determined by CDK context
+const environment = app.node.tryGetContext('environment') as Environment;
+
+if (!environment) {
+  throw new Error('Environment must be specified via context. Use: cdk deploy -c environment=dev');
+}
+
+// Read compliance frameworks from context
+const compliance = app.node.tryGetContext('compliance');
+const complianceFrameworks = compliance ? compliance.split(',') : [];
+
+// Application context with governance metadata
+const context = {
+  appName: '{{appName}}',
+  environment,
+  department: '{{department}}',
+  team: '{{team}}',
+  contact: '{{contact}}',
+  compliance: complianceFrameworks,
+  confidentiality: Confidentiality.{{CONFIDENTIALITY}},
+};
+
+// Stack name follows pattern: {appName}-{environment}
+const stack = new Stack(app, '{{appName}}-' + environment, {
+  env: {
+    account: process.env.CDK_DEFAULT_ACCOUNT,
+    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
+  },
+  stackName: '{{appName}}-' + environment,
+});
+
+// Create the LambdaDynamoApi construct
+new LambdaDynamoApi(stack, '{{appName}}Api', {
+  ...context,
+  apiId: 'main',
+  runtime: 'nodejs20',
+  handler: 'index.handler',
+  codeDir: '../apps/{{lambdaName}}',
+  // DynamoDB table configuration
+  partitionKey: { name: 'pk', type: 'S' },
+  // Uncomment for composite key (partition + sort):
+  // sortKey: { name: 'sk', type: 'S' },
+  // Uncomment to enable DynamoDB streams:
+  // enableStream: true,
+});
+
+// Apply compliance checks
+Aspects.of(app).add(new NIST80053R5Checks({ verbose: true }));
+Aspects.of(app).add(new AwsSolutionsChecks({ verbose: true }));
+
+app.synth();

package/dist/templates/lambda-dynamo-api/cdk/cdk.json

@@ -0,0 +1,73 @@
+{
+  "app": "npx ts-node --prefer-ts-exts app.ts",
+  "watch": {
+    "include": [
+      "**"
+    ],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "yarn.lock",
+      "node_modules",
+      "test"
+    ]
+  },
+  "context": {
+    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
+    "@aws-cdk/core:checkSecretUsage": true,
+    "@aws-cdk/core:target-partitions": [
+      "aws",
+      "aws-cn"
+    ],
+    "@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": false,
+    "@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/dist/templates/lambda-dynamo-api/cdk/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "cdk",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "cdk": "cdk"
+  },
+  "dependencies": {
+    "@phila/constructs": "file:{{constructsPath}}",
+    "aws-cdk-lib": "^2.100.0",
+    "cdk-nag": "^2.28.0",
+    "constructs": "^10.0.0",
+    "source-map-support": "^0.5.21"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "aws-cdk": "^2.100.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
+  }
+}

package/dist/templates/lambda-dynamo-api/cdk/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": [
+    "*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "cdk.out"
+  ]
+}

package/dist/templates/lambda-dynamo-api/package.json.tmpl

@@ -0,0 +1,20 @@
+{
+  "name": "{{appName}}",
+  "version": "1.0.0",
+  "description": "Lambda DynamoDB API application using Philadelphia constructs",
+  "private": true,
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "test": "npm test --workspaces",
+    "synth": "cd cdk && cdk synth",
+    "deploy": "cd cdk && cdk deploy",
+    "diff": "cd cdk && cdk diff"
+  },
+  "workspaces": [
+    "cdk",
+    "apps/*"
+  ],
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}

package/dist/templates/lambda-dynamo-api/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "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"],
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "exclude": ["node_modules", "cdk.out"]
+}