@phila/cli 0.0.1

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

@@ -0,0 +1,234 @@
+# {{appName}}
+
+Lambda API with PostgreSQL database using Philadelphia constructs and philaroute.
+
+Generated on {{timestamp}}
+
+## Architecture
+
+![Architecture Diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/lambda-postgres-api.drawio)
+
+View the [architecture diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/lambda-postgres-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 implementation
+└── 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
+```
+
+## Routing with philaroute
+
+This template uses [@phila/philaroute](https://www.npmjs.com/package/@phila/philaroute) for HTTP routing. Routes are defined using a composable pipeline pattern.
+
+### Defining Routes
+
+```typescript
+import { Router, http } from '@phila/philaroute';
+
+const router = Router({ cors: { 'Access-Control-Allow-Origin': '*' } });
+
+// Simple response
+const health = router.path('/health');
+health.get([
+  http.response({
+    statusCode: 200,
+    body: { status: 'healthy' },
+  }),
+]);
+
+// With database query
+const items = router.path('/items');
+items.get([
+  async (acc) => {
+    const db = await getDbConnection();
+    const items = await db.query('SELECT * FROM items');
+    return {
+      ...acc,
+      response: { statusCode: 200, body: { items } },
+    };
+  },
+]);
+```
+
+### Pipeline Functions
+
+Each route handler is an array of pipeline functions. Each function receives an accumulator and returns a modified accumulator:
+
+```typescript
+type RestAccumulator = {
+  request?: {
+    params?: { [key: string]: string };  // Path and query parameters
+    body?: any;                           // Parsed request body
+    headers?: { [key: string]: string };  // Request headers
+  };
+  data?: { [key: string]: any };          // Shared data between pipeline steps
+  response: {
+    statusCode?: number;
+    headers?: { [key: string]: string };
+    body?: string | Record<string, any> | any[];
+  };
+};
+```
+
+## Database Connection
+
+The Lambda function receives database connection information via environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `DB_SECRET_ARN` | ARN of Secrets Manager secret with database credentials |
+| `DB_NAME` | Database name |
+
+### Retrieving Credentials
+
+Use the AWS SDK to retrieve credentials from Secrets Manager:
+
+```typescript
+import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
+
+async function getDbCredentials() {
+  const client = new SecretsManagerClient({});
+  const response = await client.send(
+    new GetSecretValueCommand({ SecretId: process.env.DB_SECRET_ARN })
+  );
+  return JSON.parse(response.SecretString || '{}');
+}
+```
+
+The secret contains:
+- `username` - Database username
+- `password` - Database password
+- `host` - Database hostname (retrieved from SSM parameters)
+- `port` - Database port (default: 5432)
+
+### Connection Options
+
+Choose your preferred PostgreSQL client library:
+
+- **pg** - Low-level PostgreSQL client
+- **knex** - SQL query builder
+- **TypeORM** - Full ORM
+- **Prisma** - Type-safe ORM
+- **drizzle-orm** - Lightweight ORM
+
+Add your chosen library to `apps/{{lambdaName}}/package.json`.
+
+## Environment Variables
+
+Lambda functions automatically receive:
+- `APP_NAME` - Application name ({{appName}})
+- `ENVIRONMENT` - Current environment (dev/test/prod)
+- `DB_SECRET_ARN` - Database credentials secret ARN
+- `DB_NAME` - Database name
+
+## Resources Created
+
+This application creates:
+- **API Gateway REST API** - HTTP endpoint for your application
+- **Lambda Function** - Serverless compute for handling requests
+- **RDS PostgreSQL** - Managed database instance
+- **Secrets Manager Secret** - Database credentials
+- **VPC Security Groups** - Network security for Lambda and database
+- **IAM Roles** - Permissions for Lambda and database access
+- **SSM Parameters** - Resource discovery (API URL, database endpoint)
+- **CloudWatch Logs** - Application logs
+
+## Serverless Aurora
+
+To use Aurora Serverless v2 instead of provisioned RDS, edit `cdk/app.ts`:
+
+```typescript
+new LambdaPostgresApi(stack, '{{appName}}Api', {
+  ...context,
+  apiId: 'main',
+  runtime: 'nodejs20',
+  handler: 'index.handler',
+  codeDir: '../apps/{{lambdaName}}',
+  serverless: true,  // Use Aurora Serverless v2
+});
+```
+
+## Next Steps
+
+1. Add a PostgreSQL client library to your Lambda
+2. Implement database connection logic using `DB_SECRET_ARN`
+3. Define your routes using philaroute
+4. Create pipeline functions for validation and business logic
+5. Write tests for your handlers
+6. 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)
+- [AWS CDK Documentation](https://docs.aws.amazon.com/cdk/)
+- [API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/)
+- [RDS PostgreSQL Documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_PostgreSQL.html)

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

@@ -0,0 +1,76 @@
+// ABOUTME: Lambda API handler with PostgreSQL database connection
+// ABOUTME: Uses philaroute for routing and @phila/db-postgres for database access
+
+/**
+ * HTTP routing using @phila/philaroute
+ * @see https://github.com/CityOfPhiladelphia/philaroute
+ *
+ * Database connection using @phila/db-postgres
+ * @see https://github.com/CityOfPhiladelphia/db-postgres
+ *
+ * Environment variables (DB_SECRET_ARN, DB_NAME) are set automatically
+ * by the CDK construct.
+ */
+
+import type { APIGWV1Payload } from '@phila/philaroute/dist/types';
+import type { RestAccumulator } from '@phila/philaroute/dist/types';
+import { Router, http, validate } from '@phila/philaroute';
+import { getPool } from '@phila/db-postgres';
+
+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) => {
+    const pool = await getPool();
+    await pool.query('SELECT 1');
+    acc.data.status = 'healthy';
+    acc.data.database = 'connected';
+    acc.data.timestamp = new Date().toISOString();
+    return acc;
+  },
+};
+
+const items = {
+  list: async (acc: RestAccumulator) => {
+    const pool = await getPool();
+    const result = await pool.query('SELECT * FROM items');
+    acc.data.items = result.rows;
+    return acc;
+  },
+  create: async (acc: RestAccumulator) => {
+    const pool = await getPool();
+    const { name } = acc.data.valid.body;
+    const result = await pool.query('INSERT INTO items (name) VALUES ($1) RETURNING *', [name]);
+    acc.data.item = result.rows[0];
+    return acc;
+  },
+  get: async (acc: RestAccumulator) => {
+    const pool = await getPool();
+    const { id } = acc.data.valid.parameters;
+    const result = await pool.query('SELECT * FROM items WHERE id = $1', [id]);
+    acc.data.item = result.rows[0] ?? null;
+    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').get([items.list]);
+
+router
+  .path('/items')
+  .post([validate.body({ name: 'string' }), items.create, http.response({ statusCode: 201 })]);
+
+router.path('/items/:id').get([validate.parameters(['id']), items.get]);
+
+export const handler = async (event: APIGWV1Payload) => router.routeToPath(event);

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

@@ -0,0 +1,18 @@
+{
+  "name": "{{lambdaName}}",
+  "version": "1.0.0",
+  "description": "Lambda function handler with PostgreSQL database access",
+  "private": true,
+  "scripts": {
+    "build": "npx tsc",
+    "watch": "npx tsc -w"
+  },
+  "dependencies": {
+    "@phila/philaroute": "^1.0.12",
+    "@phila/db-postgres": "^1.0.0",
+    "@types/aws-lambda": "^8.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}

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

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "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": ".",
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import { App, Aspects, Stack } from 'aws-cdk-lib';
+import { AwsSolutionsChecks, NIST80053R5Checks } from 'cdk-nag';
+import { LambdaPostgresApi, 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 LambdaPostgresApi construct
+new LambdaPostgresApi(stack, '{{appName}}Api', {
+  ...context,
+  apiId: 'main',
+  runtime: 'nodejs20',
+  handler: 'index.handler',
+  codeDir: '../apps/{{lambdaName}}',
+  // Uncomment for serverless Aurora instead of provisioned RDS:
+  // serverless: 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-postgres-api/cdk/cdk.json

@@ -0,0 +1,4 @@
+{
+  "app": "npx ts-node app.ts",
+  "requireApproval": "broadening"
+}

package/dist/templates/lambda-postgres-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-postgres-api/cdk/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "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": ".",
+    "skipLibCheck": true
+  },
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,20 @@
+{
+  "name": "{{appName}}",
+  "version": "1.0.0",
+  "description": "Lambda API with PostgreSQL database 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-postgres-api/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}

package/dist/templates/static-site/README.md.tmpl

@@ -0,0 +1,72 @@
+# {{appName}}
+
+Static site application using Philadelphia constructs.
+
+## Architecture
+
+![Architecture Diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/static-site.drawio)
+
+View the [architecture diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/static-site.drawio) in draw.io or VS Code with the Draw.io extension.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- AWS CLI configured with SSO
+- AWS profiles configured for each environment (see city.config.json)
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Set up frontend (replace placeholder with Nuxt)
+cd frontend
+npx nuxi@latest init .
+# Configure nuxt.config.ts for SSG
+```
+
+### Deployment
+
+```bash
+# Deploy infrastructure to dev
+city deploy dev
+
+# Ship frontend updates
+city ship dev --web
+```
+
+## Project Structure
+
+```
+.
+├── cdk/                    # CDK infrastructure code
+│   └── app.ts              # StaticSite construct
+├── frontend/               # Nuxt application
+│   └── ...                 # Replace with Nuxt project
+└── city.config.json        # City CLI configuration
+```
+
+## Resources Created
+
+This application creates:
+- **S3 Bucket** - Static asset storage
+- **CloudFront Distribution** - Global CDN
+- **Origin Access Control** - Secure S3 access
+- **SSM Parameters** - URL, distribution ID, bucket name
+
+## Shipping Updates
+
+After the initial `city deploy`, use `city ship --web` for fast frontend updates:
+
+```bash
+# Build and deploy frontend
+city ship dev --web
+
+# Deploy to production
+city ship prod --web
+```
+
+This syncs files to S3 and invalidates CloudFront cache.

package/dist/templates/static-site/cdk/app.ts.tmpl

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import { App, Aspects, Stack } from 'aws-cdk-lib';
+import { AwsSolutionsChecks, NIST80053R5Checks } from 'cdk-nag';
+import { StaticSite, 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 StaticSite construct
+new StaticSite(stack, '{{appName}}Site', {
+  ...context,
+  assetDir: '../frontend/dist',
+});
+
+// Apply compliance checks
+Aspects.of(app).add(new NIST80053R5Checks({ verbose: true }));
+Aspects.of(app).add(new AwsSolutionsChecks({ verbose: true }));
+
+app.synth();