specweave 0.22.0 → 0.22.2

package/plugins/specweave/templates/iac/gcp-cloud-functions/templates/README.md.hbs

@@ -0,0 +1,299 @@
+# GCP Cloud Functions + Firestore Terraform Configuration
+
+**Generated by SpecWeave Serverless Architecture Intelligence**
+
+This Terraform configuration deploys:
+- Cloud Functions (2nd gen) with HTTP trigger
+- Firestore database (Native mode)
+- Cloud Storage bucket for function source code
+- Service Account with Firestore access
+{{#if enableSecretManager}}- Secret Manager for sensitive configuration{{/if}}
+{{#if enableVpc}}- VPC Access Connector for private networking{{/if}}
+
+## Architecture
+
+```
+Cloud Function ({{functionName}})
+    ├── Runtime: {{runtime}}
+    ├── Memory: {{memoryMb}} MB
+    ├── Timeout: {{timeoutSeconds}}s
+    ├── Min Instances: {{minInstances}} ({{#if (eq minInstances 0)}}scales to zero{{else}}always-on{{/if}})
+    └── Max Instances: {{maxInstances}}
+
+Firestore Database ({{databaseId}})
+    ├── Type: FIRESTORE_NATIVE
+    ├── Location: {{region}}
+    └── Collection: {{collectionId}}
+
+Service Account ({{serviceAccountId}})
+    └── Roles: roles/datastore.user{{#if enableSecretManager}}, roles/secretmanager.secretAccessor{{/if}}
+
+Cloud Storage ({{bucketName}})
+    ├── Location: {{bucketLocation}}
+    └── Purpose: Function source code
+```
+
+## Prerequisites
+
+1. **GCP Project** with billing enabled:
+   ```bash
+   gcloud config set project {{projectId}}
+   ```
+
+2. **gcloud CLI** authenticated:
+   ```bash
+   gcloud auth application-default login
+   ```
+
+3. **Terraform** v1.5.0+ installed:
+   ```bash
+   terraform version
+   ```
+
+4. **Function source code** ready to deploy:
+   - Node.js: `package.json`, `index.js`, etc.
+   - Python: `requirements.txt`, `main.py`, etc.
+   - Go: `go.mod`, `main.go`, etc.
+
+5. **Zip function source code**:
+   ```bash
+   cd ../src  # Navigate to your function source code
+   zip -r ../infrastructure/function-source.zip .
+   cd ../infrastructure
+   ```
+
+## Deployment Instructions
+
+### 1. Initialize Terraform
+
+```bash
+terraform init
+```
+
+### 2. Review the Plan
+
+```bash
+terraform plan
+```
+
+**Expected resources**: ~{{#if enableVpc}}10{{else if enableSecretManager}}9{{else}}7{{/if}} resources will be created
+
+### 3. Deploy Infrastructure
+
+**Development**:
+```bash
+terraform apply -var-file="environments/dev.tfvars"
+```
+
+**Staging**:
+```bash
+terraform apply -var-file="environments/staging.tfvars"
+```
+
+**Production**:
+```bash
+terraform apply -var-file="environments/prod.tfvars"
+```
+
+### 4. Deploy Function Code (Alternative)
+
+You can also deploy function code using `gcloud`:
+
+```bash
+gcloud functions deploy {{functionName}} \
+  --gen2 \
+  --runtime={{runtime}} \
+  --region={{region}} \
+  --source=../src \
+  --entry-point={{entryPoint}} \
+  --trigger-http \
+  --allow-unauthenticated
+```
+
+### 5. Test Your Function
+
+```bash
+# Get function URL
+FUNCTION_URL=$(terraform output -raw function_url)
+
+# Test HTTP trigger
+curl "${FUNCTION_URL}"
+```
+
+## Cost Estimation
+
+### Development Environment
+
+**Cloud Functions (2nd gen)**:
+- Invocations: 2M/month = Free (2M free tier)
+- Compute time: 400,000 GB-s/month = Free (free tier)
+- Networking: 5 GB egress = Free (1 GB free, then $0.12/GB)
+- **Total**: $0/month (within free tier)
+
+**Firestore**:
+- Stored data: 1 GB = Free (1 GB free tier)
+- Document reads: 50K/day = Free (50K free tier)
+- Document writes: 20K/day = Free (20K free tier)
+- Document deletes: 20K/day = Free (20K free tier)
+- **Total**: $0/month (within free tier)
+
+**Cloud Storage**:
+- Storage: < 5 GB = Free (5 GB free tier)
+- Class A operations: Minimal cost
+- Class B operations: Free (50K free tier)
+- **Total**: $0/month (within free tier)
+
+**Total Monthly Cost (Dev)**: $0/month
+
+{{#if (eq environment "prod")}}
+### Production Environment (Estimated)
+
+**Note**: Production costs depend on actual usage. Estimate above assumes:
+- 10M requests/month
+- 5 GB Firestore storage
+- 100K document writes/day
+
+For accurate production estimates, use [GCP Pricing Calculator](https://cloud.google.com/products/calculator).
+{{/if}}
+
+## Free Tier Optimization Tips
+
+1. **Cloud Functions**:
+   - Keep min_instances = 0 to scale to zero
+   - Use 256 MB memory (good balance of performance/cost)
+   - Set appropriate timeout (avoid long-running functions)
+   - Stay under 2M invocations/month for free tier
+
+2. **Firestore**:
+   - Use composite indexes wisely (counts against storage)
+   - Batch writes when possible (reduces write operations)
+   - Use server-side timestamps (avoids extra writes)
+   - Monitor read/write quota in console
+
+3. **Cloud Storage**:
+   - Store only function source code (minimal storage)
+   - Use lifecycle policies to delete old versions
+   - Stay under 5 GB for free tier
+
+4. **Networking**:
+   - Minimize egress (first 1 GB free)
+   - Use Cloud CDN for static assets
+   - Keep responses small
+
+## Monitoring
+
+**Cloud Logging** and **Cloud Monitoring** are enabled by default.
+
+View logs:
+```bash
+gcloud functions logs read {{functionName}} \
+  --region={{region}} \
+  --limit=50
+```
+
+View metrics in Cloud Console:
+```
+https://console.cloud.google.com/functions/details/{{region}}/{{functionName}}?project={{projectId}}
+```
+
+Key metrics to monitor:
+- Invocation count
+- Execution time (p50, p95, p99)
+- Error count and error rate
+- Active instances
+- Memory usage
+
+## Security Best Practices
+
+1. **Service Account**: Function uses dedicated Service Account
+   - ✅ Least privilege principle (only Firestore access)
+   - ✅ No default compute service account
+
+2. **Secrets Management**:
+{{#if enableSecretManager}}
+   - ✅ Secret Manager enabled
+   - Store sensitive config in Secret Manager
+   - Access via `google_secret_manager_secret_version` data source
+{{else}}
+   - ⚠️ Secret Manager not enabled
+   - Enable with `enableSecretManager = true`
+{{/if}}
+
+3. **HTTPS Only**: Function enforces HTTPS
+4. **CORS**: Configured for origins: {{corsOrigins}}
+5. **Network Security**:
+{{#if enableVpc}}
+   - ✅ VPC Connector enabled for private networking
+{{else}}
+   - ⚠️ Public internet access (no VPC)
+   - Enable with `enableVpc = true`
+{{/if}}
+
+6. **IAM**: Function allows unauthenticated invocations
+   - ⚠️ Change `allUsers` to specific members for private APIs
+   - Use Cloud Armor for DDoS protection (production)
+
+## Cleanup
+
+To destroy all resources:
+
+```bash
+terraform destroy
+```
+
+**Warning**: This will permanently delete:
+- Cloud Function and all code
+- Firestore database and all data
+- Storage bucket and all objects
+- Service Account
+
+## Troubleshooting
+
+### "Project not found"
+- Ensure GCP project exists and billing is enabled
+- Run `gcloud config set project {{projectId}}`
+- Verify with `gcloud projects describe {{projectId}}`
+
+### "API not enabled"
+- APIs are enabled automatically by Terraform
+- If issues persist, manually enable:
+  ```bash
+  gcloud services enable cloudfunctions.googleapis.com
+  gcloud services enable cloudbuild.googleapis.com
+  gcloud services enable firestore.googleapis.com
+  ```
+
+### "Insufficient permissions"
+- Ensure you have `roles/editor` or `roles/owner` on project
+- Check with: `gcloud projects get-iam-policy {{projectId}}`
+
+### "function-source.zip not found"
+- Create zip file from your function source code:
+  ```bash
+  cd ../src
+  zip -r ../infrastructure/function-source.zip .
+  ```
+
+### "Function not responding"
+- Check Cloud Logging for errors
+- Verify function code has correct entry point
+- Check CORS settings if calling from browser
+
+## Next Steps
+
+1. **Deploy your function code** (see step 4-5 above)
+2. **Set up CI/CD** with Cloud Build or GitHub Actions
+3. **Configure custom domains** for production
+4. **Set up monitoring alerts** in Cloud Monitoring
+5. **Enable Cloud Armor** for DDoS protection (production)
+
+## Support
+
+- **GCP Documentation**: https://cloud.google.com/functions/docs
+- **Terraform GCP Provider**: https://registry.terraform.io/providers/hashicorp/google/
+- **SpecWeave**: https://spec-weave.com
+
+---
+
+**Generated**: {{currentDate}}
+**SpecWeave Version**: {{specweaveVersion}}

package/plugins/specweave/templates/iac/gcp-cloud-functions/templates/environments/dev.tfvars.hbs

@@ -0,0 +1,36 @@
+# Development Environment Variables for GCP Cloud Functions + Firestore
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+project_id         = "{{projectId}}"
+region             = "us-central1"
+function_name      = "{{projectName}}-dev-function"
+runtime            = "{{runtime}}"
+entry_point        = "{{entryPoint}}"
+memory_mb          = 256  # Free tier: up to 2M GB-s/month
+timeout_seconds    = 60
+min_instances      = 0    # Scale to zero for cost savings
+max_instances      = 10   # Limit for dev environment
+environment        = "dev"
+
+# Firestore (free tier: 1 GB storage, 50K reads/day, 20K writes/day)
+database_id    = "(default)"
+collection_id  = "{{collectionId}}"
+
+# Service Account
+service_account_id = "{{projectName}}-dev-sa"
+
+# CORS (allow all for development)
+cors_origins = ["*"]
+
+# Storage Bucket
+bucket_name     = "{{projectName}}-dev-source"
+bucket_location = "US"  # Multi-region for better availability
+
+# Project tagging
+project_name = "{{projectName}}"
+
+# Free tier optimization
+# - min_instances = 0 (scale to zero, no idle cost)
+# - memory_mb = 256 (within free tier compute limits)
+# - timeout_seconds = 60 (avoid long-running functions)
+# - max_instances = 10 (prevent runaway costs)

package/plugins/specweave/templates/iac/gcp-cloud-functions/templates/environments/prod.tfvars.hbs

@@ -0,0 +1,48 @@
+# Production Environment Variables for GCP Cloud Functions + Firestore
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+project_id         = "{{projectId}}"
+region             = "us-central1"
+function_name      = "{{projectName}}-prod-function"
+runtime            = "{{runtime}}"
+entry_point        = "{{entryPoint}}"
+memory_mb          = 1024  # Production-grade memory
+timeout_seconds    = 300   # 5 minutes max
+min_instances      = 3     # Keep 3 instances warm for low latency
+max_instances      = 200   # Handle production traffic
+environment        = "prod"
+
+# Firestore
+database_id    = "(default)"
+collection_id  = "{{collectionId}}"
+
+# Service Account
+service_account_id = "{{projectName}}-prod-sa"
+
+# CORS (restrict to production domain only)
+cors_origins = ["https://{{projectName}}.com"]
+
+# Storage Bucket
+bucket_name     = "{{projectName}}-prod-source"
+bucket_location = "US"
+
+# Project tagging
+project_name = "{{projectName}}"
+
+# Concurrency settings
+enable_concurrency       = true
+max_concurrent_requests = 80
+
+# Production features (uncomment to enable)
+# enable_secret_manager = true
+# enable_vpc            = true
+# vpc_network           = "my-vpc"
+
+# Production optimizations
+# - min_instances = 3 (eliminate cold starts)
+# - memory_mb = 1024 (better performance, handles concurrent requests)
+# - timeout_seconds = 300 (handle complex operations)
+# - max_instances = 200 (auto-scale for traffic spikes)
+# - enable_concurrency = true (maximize instance utilization)
+# - enable_secret_manager = true (secure secrets management)
+# - enable_vpc = true (private networking)

package/plugins/specweave/templates/iac/gcp-cloud-functions/templates/environments/staging.tfvars.hbs

@@ -0,0 +1,41 @@
+# Staging Environment Variables for GCP Cloud Functions + Firestore
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+project_id         = "{{projectId}}"
+region             = "us-central1"
+function_name      = "{{projectName}}-staging-function"
+runtime            = "{{runtime}}"
+entry_point        = "{{entryPoint}}"
+memory_mb          = 512  # Higher memory for better performance
+timeout_seconds    = 120
+min_instances      = 1    # Keep 1 instance warm
+max_instances      = 50   # Higher limit for staging tests
+environment        = "staging"
+
+# Firestore
+database_id    = "(default)"
+collection_id  = "{{collectionId}}"
+
+# Service Account
+service_account_id = "{{projectName}}-staging-sa"
+
+# CORS (restrict to staging domain)
+cors_origins = ["https://staging.{{projectName}}.com"]
+
+# Storage Bucket
+bucket_name     = "{{projectName}}-staging-source"
+bucket_location = "US"
+
+# Project tagging
+project_name = "{{projectName}}"
+
+# Concurrency settings (2nd gen feature)
+enable_concurrency       = true
+max_concurrent_requests = 80
+
+# Staging optimizations
+# - min_instances = 1 (reduce cold starts)
+# - memory_mb = 512 (better performance than dev)
+# - timeout_seconds = 120 (allow longer-running operations)
+# - max_instances = 50 (handle load testing)
+# - enable_concurrency = true (better resource utilization)

package/plugins/specweave/templates/iac/gcp-cloud-functions/templates/main.tf.hbs

@@ -0,0 +1,192 @@
+# GCP Cloud Functions + Firestore Terraform Configuration
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+# Enable required APIs
+resource "google_project_service" "cloudfunctions" {
+  project = "{{projectId}}"
+  service = "cloudfunctions.googleapis.com"
+
+  disable_on_destroy = false
+}
+
+resource "google_project_service" "cloudbuild" {
+  project = "{{projectId}}"
+  service = "cloudbuild.googleapis.com"
+
+  disable_on_destroy = false
+}
+
+resource "google_project_service" "firestore" {
+  project = "{{projectId}}"
+  service = "firestore.googleapis.com"
+
+  disable_on_destroy = false
+}
+
+resource "google_project_service" "run" {
+  project = "{{projectId}}"
+  service = "run.googleapis.com"
+
+  disable_on_destroy = false
+}
+
+# Service Account for Cloud Function
+resource "google_service_account" "{{snakeCase serviceAccountId}}" {
+  account_id   = "{{serviceAccountId}}"
+  display_name = "Service Account for {{functionName}}"
+  project      = "{{projectId}}"
+}
+
+# IAM binding for Firestore access
+resource "google_project_iam_member" "firestore_user" {
+  project = "{{projectId}}"
+  role    = "roles/datastore.user"
+  member  = "serviceAccount:${google_service_account.{{snakeCase serviceAccountId}}.email}"
+}
+
+# Storage Bucket for function source code
+resource "google_storage_bucket" "{{snakeCase bucketName}}" {
+  name     = "{{bucketName}}-{{projectId}}"
+  location = "{{bucketLocation}}"
+  project  = "{{projectId}}"
+
+  uniform_bucket_level_access = true
+
+  labels = {
+    environment = "{{environment}}"
+    managed_by  = "terraform"
+    project     = "{{projectName}}"
+  }
+}
+
+# Storage Bucket Object for function source code (placeholder)
+resource "google_storage_bucket_object" "function_source" {
+  name   = "function-source-{{environment}}.zip"
+  bucket = google_storage_bucket.{{snakeCase bucketName}}.name
+  source = "function-source.zip"  # You need to provide this file
+}
+
+# Cloud Function (2nd generation)
+resource "google_cloudfunctions2_function" "{{snakeCase functionName}}" {
+  name     = "{{functionName}}"
+  location = "{{region}}"
+  project  = "{{projectId}}"
+
+  build_config {
+    runtime     = "{{runtime}}"
+    entry_point = "{{entryPoint}}"
+
+    source {
+      storage_source {
+        bucket = google_storage_bucket.{{snakeCase bucketName}}.name
+        object = google_storage_bucket_object.function_source.name
+      }
+    }
+  }
+
+  service_config {
+    max_instance_count = {{maxInstances}}
+    min_instance_count = {{minInstances}}
+    available_memory   = "{{memoryMb}}M"
+    timeout_seconds    = {{timeoutSeconds}}
+
+    {{#if enableConcurrency}}
+    max_instance_request_concurrency = {{maxConcurrentRequests}}
+    {{/if}}
+
+    environment_variables = {
+      ENVIRONMENT      = "{{environment}}"
+      GCP_PROJECT      = "{{projectId}}"
+      FIRESTORE_DATABASE = "{{databaseId}}"
+      COLLECTION_ID    = "{{collectionId}}"
+      {{#if customEnvVars}}
+      {{#each customEnvVars}}
+      {{@key}} = "{{this}}"
+      {{/each}}
+      {{/if}}
+    }
+
+    service_account_email = google_service_account.{{snakeCase serviceAccountId}}.email
+
+    {{#if enableVpc}}
+    vpc_connector                 = google_vpc_access_connector.connector.id
+    vpc_connector_egress_settings = "ALL_TRAFFIC"
+    {{/if}}
+
+    {{#if corsOrigins}}
+    ingress_settings = "ALLOW_ALL"
+    {{/if}}
+  }
+
+  labels = {
+    environment = "{{environment}}"
+    managed_by  = "terraform"
+    project     = "{{projectName}}"
+  }
+
+  depends_on = [
+    google_project_service.cloudfunctions,
+    google_project_service.cloudbuild,
+    google_project_service.run,
+    google_project_iam_member.firestore_user
+  ]
+}
+
+# Cloud Function IAM - Allow unauthenticated invocations (API Gateway equivalent)
+resource "google_cloudfunctions2_function_iam_member" "invoker" {
+  project        = google_cloudfunctions2_function.{{snakeCase functionName}}.project
+  location       = google_cloudfunctions2_function.{{snakeCase functionName}}.location
+  cloud_function = google_cloudfunctions2_function.{{snakeCase functionName}}.name
+
+  role   = "roles/cloudfunctions.invoker"
+  member = "allUsers"  # For public API. Use specific members for private APIs
+}
+
+# Firestore Database
+resource "google_firestore_database" "{{snakeCase databaseId}}" {
+  project     = "{{projectId}}"
+  name        = "{{databaseId}}"
+  location_id = "{{region}}"
+  type        = "FIRESTORE_NATIVE"
+
+  concurrency_mode            = "OPTIMISTIC"
+  app_engine_integration_mode = "DISABLED"
+
+  depends_on = [google_project_service.firestore]
+}
+
+{{#if enableVpc}}
+# VPC Access Connector for private networking
+resource "google_vpc_access_connector" "connector" {
+  name          = "{{functionName}}-vpc-connector"
+  region        = "{{region}}"
+  project       = "{{projectId}}"
+  ip_cidr_range = "10.8.0.0/28"
+  network       = var.vpc_network
+}
+{{/if}}
+
+{{#if enableSecretManager}}
+# Secret Manager for sensitive configuration
+resource "google_secret_manager_secret" "{{snakeCase functionName}}_secrets" {
+  secret_id = "{{functionName}}-secrets"
+  project   = "{{projectId}}"
+
+  replication {
+    auto {}
+  }
+
+  labels = {
+    environment = "{{environment}}"
+    managed_by  = "terraform"
+  }
+}
+
+# IAM binding for Secret Manager access
+resource "google_secret_manager_secret_iam_member" "secret_accessor" {
+  project   = google_secret_manager_secret.{{snakeCase functionName}}_secrets.project
+  secret_id = google_secret_manager_secret.{{snakeCase functionName}}_secrets.secret_id
+  role      = "roles/secretmanager.secretAccessor"
+  member    = "serviceAccount:${google_service_account.{{snakeCase serviceAccountId}}.email}"
+}
+{{/if}}

package/plugins/specweave/templates/iac/gcp-cloud-functions/templates/outputs.tf.hbs

@@ -0,0 +1,66 @@
+# Output Values for GCP Cloud Functions + Firestore
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+output "function_name" {
+  description = "Cloud Function name"
+  value       = google_cloudfunctions2_function.{{snakeCase functionName}}.name
+}
+
+output "function_id" {
+  description = "Cloud Function ID"
+  value       = google_cloudfunctions2_function.{{snakeCase functionName}}.id
+}
+
+output "function_url" {
+  description = "Cloud Function HTTPS trigger URL"
+  value       = google_cloudfunctions2_function.{{snakeCase functionName}}.service_config[0].uri
+}
+
+output "function_region" {
+  description = "Cloud Function region"
+  value       = google_cloudfunctions2_function.{{snakeCase functionName}}.location
+}
+
+output "service_account_email" {
+  description = "Service Account email for Cloud Function"
+  value       = google_service_account.{{snakeCase serviceAccountId}}.email
+}
+
+output "firestore_database_name" {
+  description = "Firestore database name"
+  value       = google_firestore_database.{{snakeCase databaseId}}.name
+}
+
+output "firestore_location" {
+  description = "Firestore database location"
+  value       = google_firestore_database.{{snakeCase databaseId}}.location_id
+}
+
+output "storage_bucket_name" {
+  description = "Storage bucket name for function source code"
+  value       = google_storage_bucket.{{snakeCase bucketName}}.name
+}
+
+output "storage_bucket_url" {
+  description = "Storage bucket URL"
+  value       = google_storage_bucket.{{snakeCase bucketName}}.url
+}
+
+{{#if enableSecretManager}}
+output "secret_manager_secret_id" {
+  description = "Secret Manager secret ID"
+  value       = google_secret_manager_secret.{{snakeCase functionName}}_secrets.secret_id
+}
+{{/if}}
+
+{{#if enableVpc}}
+output "vpc_connector_id" {
+  description = "VPC Access Connector ID"
+  value       = google_vpc_access_connector.connector.id
+}
+{{/if}}
+
+output "project_id" {
+  description = "GCP Project ID"
+  value       = "{{projectId}}"
+}

package/plugins/specweave/templates/iac/gcp-cloud-functions/templates/providers.tf.hbs

@@ -0,0 +1,25 @@
+# Terraform Provider Configuration for GCP
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+terraform {
+  required_version = ">= 1.5.0"
+
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = "~> 5.0"
+    }
+  }
+
+  {{#if enableRemoteState}}
+  backend "gcs" {
+    bucket = "{{tfStateBucket}}"
+    prefix = "terraform/state/{{projectName}}-{{environment}}"
+  }
+  {{/if}}
+}
+
+provider "google" {
+  project = "{{projectId}}"
+  region  = "{{region}}"
+}