storyshelf 0.3.2 → 0.5.3

package/dist/commands/server/terraform-aws.js

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/commands/server/terraform-aws.ts
+/** Terraform CLI version floor for the generated modules. */
+const TERRAFORM_REQUIRED_VERSION = ">= 1.9";
+function header() {
+	return `# Generated by \`storyshelf server init --target aws\`. Do not edit by hand;\n# re-run the scaffold or edit the generator in @storyshelf/cli.\n\n`;
+}
+function generateAwsVersions() {
+	return `${header()}terraform {
+  required_version = "${TERRAFORM_REQUIRED_VERSION}"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.60"
+    }
+  }
+}
+`;
+}
+function generateAwsVariables() {
+	return `${header()}variable "project" {
+  description = "Project slug, used as a name prefix for all resources."
+  type        = string
+}
+
+variable "region" {
+  description = "AWS region for all resources."
+  type        = string
+  default     = "us-east-1"
+}
+
+variable "vpc_id" {
+  description = "Existing VPC id. Empty creates a new VPC."
+  type        = string
+  default     = ""
+}
+
+variable "domain_name" {
+  description = "Public domain for the ALB (Route 53 + ACM). Empty leaves the ALB HTTP-only."
+  type        = string
+  default     = ""
+}
+
+variable "saml_metadata_url" {
+  description = "SAML metadata URL for Cognito federation (Entra/Okta). Empty skips federation."
+  type        = string
+  default     = ""
+}
+`;
+}
+function generateAwsVpc() {
+	return `${header()}# VPC: created unless var.vpc_id points at an existing one.
+resource "aws_vpc" "main" {
+  count                = var.vpc_id == "" ? 1 : 0
+  cidr_block           = "10.0.0.0/16"
+  enable_dns_support   = true
+  enable_dns_hostnames = true
+
+  tags = { Name = "\${var.project}-vpc" }
+}
+
+locals {
+  vpc_id = var.vpc_id != "" ? var.vpc_id : aws_vpc.main[0].id
+}
+`;
+}
+/** ALB + ECS security groups and private data-plane endpoints. */
+function generateAwsSecurity() {
+	return `${header()}resource "aws_security_group" "alb" {
+  name        = "\${var.project}-alb"
+  description = "ALB ingress"
+  vpc_id      = local.vpc_id
+
+  ingress {
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  ingress {
+    from_port   = 80
+    to_port     = 80
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}
+
+resource "aws_security_group" "ecs" {
+  name        = "\${var.project}-ecs"
+  description = "ECS tasks: ALB ingress only"
+  vpc_id      = local.vpc_id
+
+  ingress {
+    from_port       = 3000
+    to_port         = 3000
+    protocol        = "tcp"
+    security_groups = [aws_security_group.alb.id]
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}
+`;
+}
+/** Private data-plane endpoints (S3, SQS) off the public internet. */
+function generateAwsEndpoints() {
+	return `${header()}# VPC endpoints keep data-plane traffic (S3, SQS) off the public internet.
+resource "aws_vpc_endpoint" "s3" {
+  vpc_id       = local.vpc_id
+  service_name = "com.amazonaws.\${var.region}.s3"
+}
+
+resource "aws_vpc_endpoint" "sqs" {
+  vpc_id            = local.vpc_id
+  service_name      = "com.amazonaws.\${var.region}.sqs"
+  security_group_ids = [aws_security_group.ecs.id]
+}
+`;
+}
+function generateAwsStorage() {
+	return `${header()}resource "aws_s3_bucket" "storybook" {
+  bucket = "\${var.project}-storybook"
+}
+
+resource "aws_s3_bucket_versioning" "storybook" {
+  bucket = aws_s3_bucket.storybook.id
+
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "storybook" {
+  bucket = aws_s3_bucket.storybook.id
+
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm = "AES256"
+    }
+  }
+}
+
+resource "aws_s3_bucket_public_access_block" "storybook" {
+  bucket                  = aws_s3_bucket.storybook.id
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+# Transient build bundles expire; baselines persist.
+resource "aws_s3_bucket_lifecycle_configuration" "storybook" {
+  bucket = aws_s3_bucket.storybook.id
+
+  rule {
+    id     = "expire-transient-builds"
+    status = "Enabled"
+
+    filter {
+      prefix = "builds/"
+    }
+
+    expiration {
+      days = 30
+    }
+  }
+}
+`;
+}
+function generateAwsQueue() {
+	return `${header()}resource "aws_sqs_queue" "capture_dlq" {
+  name = "\${var.project}-capture-dlq"
+}
+
+resource "aws_sqs_queue" "capture" {
+  name                       = "\${var.project}-capture"
+  visibility_timeout_seconds = 300
+  redrive_policy = jsonencode({
+    deadLetterTargetArn = aws_sqs_queue.capture_dlq.arn
+    maxReceiveCount     = 3
+  })
+}
+`;
+}
+function generateAwsDatabase(dbEngine) {
+	if (dbEngine === "dsql") return `${header()}# Serverless Postgres. The server connects with
+# createPostgresDatabase({ url: <cluster endpoint> }).
+resource "aws_dsql_cluster" "main" {
+  deletion_protection_enabled = true
+
+  tags = { Name = "\${var.project}-db" }
+}
+`;
+	return `${header()}# VPC-isolated Postgres for regulated estates. The server connects with
+# createPostgresDatabase({ url: <DATABASE_URL with sslmode=require> }).
+resource "aws_db_subnet_group" "main" {
+  name       = "\${var.project}-db"
+  subnet_ids = data.aws_subnets.private.ids
+}
+
+resource "aws_db_instance" "main" {
+  identifier             = "\${var.project}-db"
+  engine                 = "postgres"
+  engine_version         = "16"
+  instance_class         = "db.t4g.micro"
+  allocated_storage      = 20
+  db_subnet_group_name   = aws_db_subnet_group.main.name
+  vpc_security_group_ids = [aws_security_group.ecs.id]
+  skip_final_snapshot    = true
+}
+`;
+}
+function generateAwsIdentity() {
+	return `${header()}# Cognito User Pool: the enterprise identity front door. Federate a
+# corporate IdP (Entra/Okta) via SAML by setting var.saml_metadata_url.
+resource "aws_cognito_user_pool" "main" {
+  name = "\${var.project}-users"
+}
+
+resource "aws_cognito_user_pool_client" "shelf" {
+  name            = "\${var.project}-shelf"
+  user_pool_id    = aws_cognito_user_pool.main.id
+  generate_secret = true
+
+  allowed_oauth_flows                  = ["code"]
+  allowed_oauth_scopes                 = ["openid", "email", "profile"]
+  callback_urls                        = ["https://\${var.domain_name == "" ? aws_lb.main.dns_name : var.domain_name}/auth/callback"]
+  supported_identity_providers         = ["COGNITO"]
+}
+
+resource "aws_cognito_user_group" "admins" {
+  name         = "shelf-admins"
+  user_pool_id = aws_cognito_user_pool.main.id
+}
+
+resource "aws_cognito_identity_provider" "saml" {
+  count         = var.saml_metadata_url == "" ? 0 : 1
+  user_pool_id  = aws_cognito_user_pool.main.id
+  provider_name = "CorporateSAML"
+  provider_type = "SAML"
+
+  provider_details = {
+    MetadataURL = var.saml_metadata_url
+  }
+}
+`;
+}
+function generateAwsCompute() {
+	return `${header()}# ECS Fargate: long-lived app + worker services. Playwright/Chromium
+# renders on Fargate — Lambda's 15-minute limit and /tmp caps rule it out.
+resource "aws_lb" "main" {
+  name               = "\${var.project}-alb"
+  load_balancer_type = "application"
+  security_groups    = [aws_security_group.alb.id]
+  subnets            = data.aws_subnets.public.ids
+}
+
+resource "aws_ecs_cluster" "main" {
+  name = "\${var.project}-cluster"
+}
+
+resource "aws_cloudwatch_log_group" "app" {
+  name              = "/ecs/\${var.project}-app"
+  retention_in_days = 30
+}
+
+resource "aws_cloudwatch_log_group" "worker" {
+  name              = "/ecs/\${var.project}-worker"
+  retention_in_days = 30
+}
+`;
+}
+function generateAwsSecrets() {
+	return `${header()}# Secrets Manager: session secret, OIDC secret, break-glass admin
+# token. Task roles below may read exactly these ARNs.
+resource "aws_secretsmanager_secret" "shelf_secret" {
+  name = "\${var.project}/SECRET"
+}
+
+resource "aws_secretsmanager_secret" "oidc_client_secret" {
+  name = "\${var.project}/OIDC_CLIENT_SECRET"
+}
+
+resource "aws_secretsmanager_secret" "admin_token" {
+  name = "\${var.project}/ADMIN_TOKEN"
+}
+`;
+}
+function generateAwsDns() {
+	return `${header()}# Route 53 + ACM. Skipped entirely when var.domain_name is empty
+# (the ALB stays HTTP-only for dev).
+resource "aws_acm_certificate" "main" {
+  count             = var.domain_name == "" ? 0 : 1
+  domain_name       = var.domain_name
+  validation_method = "DNS"
+}
+
+resource "aws_route53_zone" "main" {
+  count = var.domain_name == "" ? 0 : 1
+  name  = var.domain_name
+}
+
+resource "aws_route53_record" "app" {
+  count   = var.domain_name == "" ? 0 : 1
+  zone_id = aws_route53_zone.main[0].zone_id
+  name    = var.domain_name
+  type    = "A"
+
+  alias {
+    name                   = aws_lb.main.dns_name
+    zone_id                = aws_lb.main.zone_id
+    evaluate_target_health = true
+  }
+}
+`;
+}
+function generateAwsOutputs(dbEngine) {
+	return `${header()}# Outputs feed directly into the scaffolded server's env.
+# Keys are a stable contract parsed by CI — do not rename.
+output "alb_dns_name" {
+  value = aws_lb.main.dns_name
+}
+
+output "s3_bucket" {
+  value = aws_s3_bucket.storybook.id
+}
+
+output "queue_url" {
+  value = aws_sqs_queue.capture.url
+}
+
+output "db_endpoint" {
+  value = ${generateAwsDbEndpoint(dbEngine)}
+}
+
+output "user_pool_id" {
+  value = aws_cognito_user_pool.main.id
+}
+
+output "app_client_id" {
+  value = aws_cognito_user_pool_client.shelf.id
+}
+`;
+}
+/** Connection endpoint per Postgres engine (DSQL has no endpoint attribute). */
+function generateAwsDbEndpoint(dbEngine) {
+	if (dbEngine === "dsql") return `"\${aws_dsql_cluster.main.identifier}.dsql.\${var.region}.on.aws"`;
+	return "aws_db_instance.main.endpoint";
+}
+function generateAwsCiProfile() {
+	return `## CI test profile
+
+Smallest footprint, unique resources per run, documented destroy.
+Prefer the serverless engine for CI (no instance to pay for idle):
+
+\`\`\`sh
+export PROJECT="shelf-ci-$GITHUB_RUN_ID"   # unique prefix per run (all names derive from it)
+terraform init
+terraform plan -var "project=$PROJECT" -out=tfplan
+terraform apply tfplan
+terraform output -json   # or: npm run infra:outputs
+# ... run live tests against the outputs ...
+terraform destroy -var "project=$PROJECT" -auto-approve
+\`\`\`
+
+Re-scaffold with the DSQL engine for the cheapest CI runs
+(\`dbEngine: "dsql"\`); RDS uses the smallest burstable class
+(\`db.t4g.micro\`) when you need a classic instance.
+`;
+}
+function generateAwsReadme(project) {
+	return `# ${project} on AWS
+
+Scaffolded by \`storyshelf server init --target aws\`.
+
+## Next steps
+
+\`\`\`sh
+cd terraform
+terraform init
+terraform plan -out=tfplan   # review before applying
+terraform apply tfplan
+\`\`\`
+
+## Wire outputs into env
+
+\`\`\`sh
+terraform output -json   # or: npm run infra:outputs
+\`\`\`
+
+| Output | Env var | Adapter |
+|---|---|---|
+| \`s3_bucket\` | \`S3_BUCKET\` (+ \`AWS_REGION\`) | \`storage-s3\` |
+| \`queue_url\` | \`QUEUE_URL\` | \`queue-sqs\` |
+| \`db_endpoint\` | \`DATABASE_URL\` (\`?sslmode=require\`) | \`db-postgres\` |
+| \`user_pool_id\` / \`app_client_id\` | \`COGNITO_DOMAIN\` / \`COGNITO_REGION\` / \`COGNITO_USER_POOL_ID\` / \`OIDC_CLIENT_ID\` | \`auth\` (cognito social) |
+| Secrets Manager | \`SECRET\` / \`OIDC_CLIENT_SECRET\` / \`ADMIN_TOKEN\` | sessions / OIDC / bootstrap |
+
+\`\`\`sh
+npm install
+npm start
+\`\`\`
+
+Credentials come from IAM (ECS task roles) — never check access keys into env files.
+
+${generateAwsCiProfile()}`;
+}
+function generateAwsTfvarsExample() {
+	return `# Copy to terraform.tfvars and fill in per environment.
+# CI test profile: pass a unique project per run instead —
+#   terraform plan -var "project=shelf-ci-$GITHUB_RUN_ID"
+# db_engine is baked at scaffold time (rds | dsql); prefer dsql for CI.
+project           = "my-storyshelf"
+region            = "us-east-1"
+vpc_id            = ""
+domain_name       = ""
+saml_metadata_url = ""
+`;
+}
+const AWS_FILES = [
+	["terraform/versions.tf", () => generateAwsVersions()],
+	["terraform/variables.tf", () => generateAwsVariables()],
+	["terraform/network.tf", () => `${generateAwsVpc()}${generateAwsSecurity()}${generateAwsEndpoints()}`],
+	["terraform/storage.tf", () => generateAwsStorage()],
+	["terraform/queue.tf", () => generateAwsQueue()],
+	["terraform/identity.tf", () => generateAwsIdentity()],
+	["terraform/compute.tf", () => generateAwsCompute()],
+	["terraform/secrets.tf", () => generateAwsSecrets()],
+	["terraform/dns.tf", () => generateAwsDns()],
+	["terraform/outputs.tf", (options) => generateAwsOutputs(options.dbEngine)],
+	["terraform/terraform.tfvars.example", () => generateAwsTfvarsExample()]
+];
+/** Generate every Terraform file for the AWS reference stack. */
+function generateAwsTerraformFiles(options) {
+	const files = {};
+	for (const [path, generate] of AWS_FILES) files[path] = generate(options);
+	files["terraform/database.tf"] = generateAwsDatabase(options.dbEngine);
+	files["terraform/README.md"] = generateAwsReadme(options.project);
+	return files;
+}
+//#endregion
+export { TERRAFORM_REQUIRED_VERSION, generateAwsCompute, generateAwsDatabase, generateAwsDns, generateAwsEndpoints, generateAwsIdentity, generateAwsOutputs, generateAwsQueue, generateAwsReadme, generateAwsSecrets, generateAwsSecurity, generateAwsStorage, generateAwsTerraformFiles, generateAwsTfvarsExample, generateAwsVariables, generateAwsVersions, generateAwsVpc };