@phila/cli 0.0.1

package/dist/templates/webapp-ecs-node/cdk/app.ts.tmpl

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import 'source-map-support/register';
+import * as path from 'path';
+import { App, Aspects, Stack } from 'aws-cdk-lib';
+import * as ecs from 'aws-cdk-lib/aws-ecs';
+import { AwsSolutionsChecks, NIST80053R5Checks } from 'cdk-nag';
+import { StaticSite, EcsApi, 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 for the Nuxt frontend
+new StaticSite(stack, '{{appName}}Site', {
+  ...context,
+  assetDir: '../frontend/dist',
+});
+
+// Create the EcsApi construct for the containerized API backend
+new EcsApi(stack, '{{appName}}Api', {
+  ...context,
+  apiId: 'api',
+  image: ecs.ContainerImage.fromAsset(path.join(__dirname, '../apps/api')),
+  containerPort: 80,
+});
+
+// Apply compliance checks
+Aspects.of(app).add(new NIST80053R5Checks({ verbose: true }));
+Aspects.of(app).add(new AwsSolutionsChecks({ verbose: true }));
+
+app.synth();

package/dist/templates/webapp-ecs-node/cdk/cdk.json

@@ -0,0 +1,38 @@
+{
+  "app": "npx ts-node --prefer-ts-exts app.ts",
+  "watch": {
+    "include": ["**"],
+    "exclude": [
+      "README.md",
+      "cdk*.json",
+      "**/*.d.ts",
+      "**/*.js",
+      "tsconfig.json",
+      "package*.json",
+      "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": 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
+  }
+}

package/dist/templates/webapp-ecs-node/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": "./"
+  },
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "cdk.out"]
+}

package/dist/templates/webapp-ecs-node/package.json.tmpl

@@ -0,0 +1,25 @@
+{
+  "name": "{{appName}}",
+  "version": "1.0.0",
+  "description": "Web application with Nuxt frontend and ECS containerized API backend",
+  "private": true,
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "build:frontend": "cd frontend && npm run build",
+    "build:api": "cd apps/api && npm run build",
+    "dev": "cd frontend && npm run dev",
+    "dev:api": "cd apps/api && npm run dev",
+    "test": "npm test --workspaces --if-present",
+    "synth": "cd cdk && cdk synth",
+    "deploy": "cd cdk && cdk deploy",
+    "diff": "cd cdk && cdk diff"
+  },
+  "workspaces": [
+    "cdk",
+    "apps/*",
+    "frontend"
+  ],
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}

package/dist/templates/webapp-ecs-node/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,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "exclude": ["node_modules", "cdk", "apps", "frontend"]
+}

package/dist/templates/webapp-ecs-postgres-dotnet/README.md.tmpl

@@ -0,0 +1,271 @@
+# {{appName}}
+
+Web application with Nuxt SSG frontend, ECS containerized .NET API backend, and PostgreSQL using Philadelphia constructs.
+
+Generated on {{timestamp}}
+
+## Architecture
+
+![Architecture Diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/webapp-ecs-postgres.drawio)
+
+View the [architecture diagram](https://github.com/CityOfPhiladelphia/phila-ctl/blob/main/packages/constructs/docs/diagrams/webapp-ecs-postgres.drawio) in draw.io or VS Code with the Draw.io extension.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- .NET 8 SDK
+- Docker (for building container images)
+- AWS CLI configured with SSO
+- AWS profile named `phila-{{appName}}`
+
+### Setup
+
+```bash
+# Install frontend and CDK dependencies
+npm install
+
+# Restore .NET dependencies
+cd apps/api && dotnet restore && cd ../..
+```
+
+### Development
+
+```bash
+# Run frontend dev server
+npm run dev
+
+# Run API locally (requires local Postgres or connection to dev database)
+cd apps/api && dotnet run
+
+# Build frontend for production
+npm run build:frontend
+
+# Build API Docker image
+npm run build:api
+```
+
+### 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
+```
+
+### Shipping Updates
+
+```bash
+# Ship frontend changes to S3/CloudFront
+city ship dev --web
+
+# Ship API changes (rebuilds and deploys ECS container)
+city ship dev --ecs api
+```
+
+## Project Structure
+
+```
+.
+├── cdk/                    # CDK infrastructure code
+│   └── app.ts              # Main CDK application
+├── frontend/               # Nuxt 3 SSG frontend
+│   ├── pages/              # File-based routing
+│   ├── app.vue             # Root component
+│   └── nuxt.config.ts      # Nuxt configuration
+├── apps/                   # Backend code
+│   └── api/                # .NET Minimal API container with Postgres
+│       ├── Program.cs      # API entry point and routes
+│       ├── Api.csproj      # Project file
+│       └── Dockerfile      # Container build file
+└── city.config.json        # City CLI configuration
+```
+
+## Frontend
+
+The frontend uses [Nuxt 3](https://nuxt.com) with Static Site Generation (SSG):
+
+- Pre-renders to static HTML for S3/CloudFront
+- File-based routing in `pages/` directory
+- TypeScript support enabled
+
+### Adding Pages
+
+Create Vue files in `frontend/pages/`:
+
+```vue
+<!-- frontend/pages/about.vue -->
+<template>
+  <div>
+    <h1>About</h1>
+  </div>
+</template>
+```
+
+This automatically creates a route at `/about`.
+
+## API
+
+The API uses [.NET Minimal API](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis) running in an ECS Fargate container with PostgreSQL via Npgsql.
+
+### Adding Endpoints
+
+Edit `apps/api/Program.cs`:
+
+```csharp
+// List all users
+app.MapGet("/users", async (DbConnectionFactory db) =>
+{
+    await using var conn = await db.GetConnectionAsync();
+    await using var cmd = new NpgsqlCommand("SELECT * FROM users", conn);
+    await using var reader = await cmd.ExecuteReaderAsync();
+
+    var users = new List<object>();
+    while (await reader.ReadAsync())
+    {
+        users.Add(new { Id = reader.GetString(0), Name = reader.GetString(1) });
+    }
+    return Results.Ok(users);
+});
+```
+
+### Environment Variables
+
+ECS containers automatically receive:
+- `APP_NAME` - Application name ({{appName}})
+- `ENVIRONMENT` - Current environment (dev/test/prod)
+- `DB_SECRET_ARN` - ARN of Secrets Manager secret containing database credentials
+- `DB_NAME` - Database name
+
+### Database Connection
+
+The `DbConnectionFactory` class handles:
+- Retrieving credentials from AWS Secrets Manager
+- Building connection strings with SSL
+- Connection caching for container performance
+
+### Local Development
+
+Run the API locally:
+
+```bash
+cd apps/api
+dotnet run
+```
+
+Or build and run the Docker container:
+
+```bash
+cd apps/api
+docker build -t {{appName}}-api .
+docker run -p 80:80 \
+  -e APP_NAME={{appName}} \
+  -e ENVIRONMENT=dev \
+  -e DB_SECRET_ARN=<secret-arn> \
+  -e DB_NAME={{appName}} \
+  {{appName}}-api
+```
+
+## PostgreSQL
+
+The template creates an RDS PostgreSQL instance with:
+- **Engine**: PostgreSQL 15
+- **Instance class**: db.t3.micro (dev), db.t3.small (test/prod)
+- **Storage**: Encrypted with KMS
+- **Credentials**: Stored in Secrets Manager
+- **Network**: VPC with private subnets
+
+### Database Migrations
+
+Run migrations manually or via a CI/CD pipeline:
+
+```bash
+# Connect via bastion host or VPN
+psql -h <rds-endpoint> -U postgres -d {{appName}}
+
+# Create tables
+CREATE TABLE items (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### Serverless Option
+
+For variable workloads, use Aurora Serverless:
+
+```typescript
+// In cdk/app.ts:
+new EcsPostgresApi(stack, '{{appName}}Api', {
+  ...context,
+  serverless: true,  // Use Aurora Serverless v2
+});
+```
+
+## Resources Created
+
+This application creates:
+
+**Frontend:**
+- **S3 Bucket** - Static asset storage
+- **CloudFront Distribution** - CDN with HTTPS
+- **Origin Access Control** - Secure S3 access
+
+**API:**
+- **ECS Fargate Service** - Containerized compute
+- **Application Load Balancer** - HTTP/HTTPS ingress
+- **ECS Cluster** - Container orchestration
+- **ECR Repository** - Docker image storage
+- **RDS PostgreSQL** - Relational database
+- **Secrets Manager** - Database credentials
+- **VPC Security Groups** - Network security
+- **IAM Roles** - Task execution permissions
+
+**Shared:**
+- **SSM Parameters** - Resource discovery
+- **CloudWatch Logs** - Application logs
+- **KMS Keys** - Encryption
+
+## URLs
+
+After deployment, URLs are available via:
+
+```bash
+# Frontend URL
+city config list --env dev | grep cloudfront
+
+# API URL (ALB endpoint)
+city config list --env dev | grep ecs-api
+```
+
+## Scaling
+
+ECS automatically adjusts:
+- **Dev**: 1 container instance
+- **Test/Prod**: 2+ container instances with auto-scaling
+
+Container resources default to:
+- CPU: 256 units (0.25 vCPU)
+- Memory: 512 MB
+
+Adjust in `cdk/app.ts` by passing `cpu` and `memoryLimitMiB` props to `EcsPostgresApi`.
+
+## Support
+
+For issues or questions:
+- [Philadelphia Infrastructure Library Documentation](https://github.com/CityOfPhiladelphia/phila-ctl)
+- [.NET Minimal APIs Documentation](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis)
+- [Npgsql Documentation](https://www.npgsql.org/)
+- [Nuxt Documentation](https://nuxt.com/docs)

package/dist/templates/webapp-ecs-postgres-dotnet/apps/api/Api.csproj

@@ -0,0 +1,17 @@
+<!-- ABOUTME: .NET 8 Minimal API project for ECS with PostgreSQL -->
+<!-- ABOUTME: Uses Npgsql for database access and AWS SDK for Secrets Manager -->
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <OutputType>Exe</OutputType>
+    <AssemblyName>Api</AssemblyName>
+    <RootNamespace>Api</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="AWSSDK.SecretsManager" Version="3.7.400" />
+    <PackageReference Include="Npgsql" Version="8.0.0" />
+  </ItemGroup>
+</Project>

package/dist/templates/webapp-ecs-postgres-dotnet/apps/api/Dockerfile

@@ -0,0 +1,30 @@
+# ABOUTME: Multi-stage Docker build for .NET Minimal API
+# ABOUTME: Creates minimal production image with compiled application
+
+# Build stage
+FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS builder
+
+WORKDIR /app
+
+# Copy project file and restore dependencies
+COPY *.csproj ./
+RUN dotnet restore
+
+# Copy source and build
+COPY . ./
+RUN dotnet publish -c Release -o publish --no-restore
+
+# Production stage
+FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine
+
+WORKDIR /app
+
+# Copy published output from builder
+COPY --from=builder /app/publish ./
+
+# Run as non-root user for security
+USER app
+
+EXPOSE 80
+
+ENTRYPOINT ["dotnet", "Api.dll"]

package/dist/templates/webapp-ecs-postgres-dotnet/apps/api/Program.cs

@@ -0,0 +1,194 @@
+// ABOUTME: ASP.NET Core Minimal API for ECS with PostgreSQL database
+// ABOUTME: Provides REST endpoints with database connection examples
+
+using System.Text.Json;
+using Amazon.SecretsManager;
+using Amazon.SecretsManager.Model;
+using Npgsql;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Configure Kestrel to listen on port 80
+builder.WebHost.ConfigureKestrel(options =>
+{
+    options.ListenAnyIP(80);
+});
+
+// Add CORS
+builder.Services.AddCors(options =>
+{
+    options.AddDefaultPolicy(policy =>
+    {
+        policy.AllowAnyOrigin()
+              .AllowAnyMethod()
+              .AllowAnyHeader();
+    });
+});
+
+// Register database connection factory as singleton
+builder.Services.AddSingleton<DbConnectionFactory>();
+
+var app = builder.Build();
+
+app.UseCors();
+
+// Request logging middleware
+app.Use(async (context, next) =>
+{
+    Console.WriteLine($"{DateTime.UtcNow:o} {context.Request.Method} {context.Request.Path}");
+    await next();
+});
+
+// Health check endpoint (required for ALB health checks)
+app.MapGet("/health", () => Results.Ok(new
+{
+    Status = "healthy",
+    Timestamp = DateTime.UtcNow.ToString("o")
+}));
+
+// Hello world endpoint
+app.MapGet("/hello", (HttpContext context) =>
+{
+    var name = context.Request.Query["name"].FirstOrDefault() ?? "World";
+    return Results.Ok(new
+    {
+        Message = $"Hello, {name}!",
+        AppName = Environment.GetEnvironmentVariable("APP_NAME"),
+        Environment = Environment.GetEnvironmentVariable("ENVIRONMENT"),
+        Timestamp = DateTime.UtcNow.ToString("o")
+    });
+});
+
+// Example: List items from database
+app.MapGet("/items", async (DbConnectionFactory db) =>
+{
+    // TODO: Implement database query
+    // await using var conn = await db.GetConnectionAsync();
+    // await using var cmd = new NpgsqlCommand("SELECT * FROM items", conn);
+    // await using var reader = await cmd.ExecuteReaderAsync();
+    // var items = new List<object>();
+    // while (await reader.ReadAsync())
+    // {
+    //     items.Add(new { Id = reader.GetString(0), Name = reader.GetString(1) });
+    // }
+    // return Results.Ok(items);
+
+    return Results.Ok(new
+    {
+        Items = Array.Empty<object>(),
+        Message = "Database query not implemented - see code comments for Npgsql example"
+    });
+});
+
+// Example: Create item in database
+app.MapPost("/items", async (ItemRequest request, DbConnectionFactory db) =>
+{
+    Console.WriteLine($"Creating item: {request.Name}");
+
+    // TODO: Implement database insert
+    // await using var conn = await db.GetConnectionAsync();
+    // await using var cmd = new NpgsqlCommand(
+    //     "INSERT INTO items (name, description) VALUES (@name, @desc) RETURNING id", conn);
+    // cmd.Parameters.AddWithValue("name", request.Name);
+    // cmd.Parameters.AddWithValue("desc", request.Description ?? (object)DBNull.Value);
+    // var id = await cmd.ExecuteScalarAsync();
+    // return Results.Created($"/items/{id}", new { Id = id, Name = request.Name });
+
+    return Results.Created($"/items/{Guid.NewGuid()}", new
+    {
+        Message = "Item created (database insert not implemented)",
+        Item = request
+    });
+});
+
+// Example: Get item by ID
+app.MapGet("/items/{id}", async (string id, DbConnectionFactory db) =>
+{
+    // TODO: Implement database query
+    // await using var conn = await db.GetConnectionAsync();
+    // await using var cmd = new NpgsqlCommand("SELECT * FROM items WHERE id = @id", conn);
+    // cmd.Parameters.AddWithValue("id", id);
+    // await using var reader = await cmd.ExecuteReaderAsync();
+    // if (!await reader.ReadAsync())
+    // {
+    //     return Results.NotFound(new { Error = "Item not found" });
+    // }
+    // return Results.Ok(new { Id = reader.GetString(0), Name = reader.GetString(1) });
+
+    return Results.Ok(new
+    {
+        Id = id,
+        Message = $"Database query not implemented for item {id}"
+    });
+});
+
+Console.WriteLine($"Server starting on port 80");
+Console.WriteLine($"APP_NAME: {Environment.GetEnvironmentVariable("APP_NAME")}");
+Console.WriteLine($"ENVIRONMENT: {Environment.GetEnvironmentVariable("ENVIRONMENT")}");
+
+app.Run();
+
+/// <summary>
+/// Request model for creating items
+/// </summary>
+public record ItemRequest(string Name, string? Description);
+
+/// <summary>
+/// Factory for creating database connections using credentials from Secrets Manager.
+/// Credentials are cached after first retrieval for container performance.
+/// </summary>
+public class DbConnectionFactory
+{
+    private string? _connectionString;
+
+    public async Task<NpgsqlConnection> GetConnectionAsync()
+    {
+        if (_connectionString == null)
+        {
+            _connectionString = await BuildConnectionStringAsync();
+        }
+
+        var conn = new NpgsqlConnection(_connectionString);
+        await conn.OpenAsync();
+        return conn;
+    }
+
+    private static async Task<string> BuildConnectionStringAsync()
+    {
+        var secretArn = Environment.GetEnvironmentVariable("DB_SECRET_ARN");
+        var dbName = Environment.GetEnvironmentVariable("DB_NAME");
+
+        if (string.IsNullOrEmpty(secretArn))
+        {
+            throw new InvalidOperationException("DB_SECRET_ARN environment variable not set");
+        }
+
+        using var client = new AmazonSecretsManagerClient();
+        var response = await client.GetSecretValueAsync(new GetSecretValueRequest
+        {
+            SecretId = secretArn
+        });
+
+        var credentials = JsonSerializer.Deserialize<DbCredentials>(response.SecretString)
+            ?? throw new InvalidOperationException("Failed to deserialize database credentials");
+
+        return new NpgsqlConnectionStringBuilder
+        {
+            Host = credentials.Host,
+            Port = credentials.Port,
+            Database = dbName ?? credentials.Database,
+            Username = credentials.Username,
+            Password = credentials.Password,
+            SslMode = SslMode.Require,
+            TrustServerCertificate = true
+        }.ConnectionString;
+    }
+
+    private record DbCredentials(
+        string Host,
+        int Port,
+        string Database,
+        string Username,
+        string Password
+    );
+}