specweave 0.22.0 → 0.22.3

package/plugins/specweave/templates/iac/firebase/templates/main.tf.hbs

@@ -0,0 +1,90 @@
+# Firebase (Hosting + Functions + Firestore) Terraform Configuration
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+# Enable Firebase for existing GCP project
+resource "google_firebase_project" "default" {
+  provider = google-beta
+  project  = "{{projectId}}"
+}
+
+# Enable required APIs
+resource "google_project_service" "firebasehosting" {
+  project = "{{projectId}}"
+  service = "firebasehosting.googleapis.com"
+  disable_on_destroy = false
+}
+
+resource "google_project_service" "firebase" {
+  project = "{{projectId}}"
+  service = "firebase.googleapis.com"
+  disable_on_destroy = false
+}
+
+# Firebase Web App
+resource "google_firebase_web_app" "{{snakeCase appDisplayName}}" {
+  provider     = google-beta
+  project      = "{{projectId}}"
+  display_name = "{{appDisplayName}}"
+
+  depends_on = [google_firebase_project.default]
+}
+
+# Firebase Hosting Site
+resource "google_firebase_hosting_site" "{{snakeCase siteId}}" {
+  provider = google-beta
+  project  = "{{projectId}}"
+  site_id  = "{{siteId}}"
+
+  depends_on = [google_firebase_project.default]
+}
+
+# Firestore Database (same as GCP)
+resource "google_firestore_database" "{{snakeCase databaseId}}" {
+  project     = "{{projectId}}"
+  name        = "{{databaseId}}"
+  location_id = "{{region}}"
+  type        = "FIRESTORE_NATIVE"
+
+  depends_on = [google_firebase_project.default]
+}
+
+# Cloud Functions for Firebase (similar to GCP Cloud Functions)
+resource "google_cloudfunctions2_function" "{{snakeCase functionName}}" {
+  name     = "{{functionName}}"
+  location = "{{region}}"
+  project  = "{{projectId}}"
+
+  build_config {
+    runtime     = "{{runtime}}"
+    entry_point = "{{entryPoint}}"
+    source {
+      storage_source {
+        bucket = "{{projectId}}.appspot.com"
+        object = "function-source.zip"
+      }
+    }
+  }
+
+  service_config {
+    max_instance_count = 10
+    available_memory   = "{{memoryMb}}M"
+    timeout_seconds    = {{timeoutSeconds}}
+    environment_variables = {
+      FIREBASE_CONFIG = google_firebase_web_app.{{snakeCase appDisplayName}}.app_id
+      ENVIRONMENT     = "{{environment}}"
+    }
+  }
+
+  depends_on = [google_firebase_project.default]
+}
+
+{{#if enableStorage}}
+# Firebase Storage Bucket
+resource "google_firebase_storage_bucket" "{{snakeCase storageBucket}}" {
+  provider  = google-beta
+  project   = "{{projectId}}"
+  bucket_id = "{{storageBucket}}"
+
+  depends_on = [google_firebase_project.default]
+}
+{{/if}}

package/plugins/specweave/templates/iac/firebase/templates/outputs.tf.hbs

@@ -0,0 +1,15 @@
+# Firebase Outputs
+output "web_app_id" {
+  description = "Firebase Web App ID"
+  value       = google_firebase_web_app.{{snakeCase appDisplayName}}.app_id
+}
+
+output "hosting_site_url" {
+  description = "Firebase Hosting URL"
+  value       = "https://${google_firebase_hosting_site.{{snakeCase siteId}}.default_url}"
+}
+
+output "function_url" {
+  description = "Cloud Function URL"
+  value       = google_cloudfunctions2_function.{{snakeCase functionName}}.service_config[0].uri
+}

package/plugins/specweave/templates/iac/firebase/templates/providers.tf.hbs

@@ -0,0 +1,23 @@
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = "~> 5.0"
+    }
+    google-beta = {
+      source  = "hashicorp/google-beta"
+      version = "~> 5.0"
+    }
+  }
+}
+
+provider "google" {
+  project = "{{projectId}}"
+  region  = "{{region}}"
+}
+
+provider "google-beta" {
+  project = "{{projectId}}"
+  region  = "{{region}}"
+}

package/plugins/specweave/templates/iac/firebase/templates/variables.tf.hbs

@@ -0,0 +1,42 @@
+# Input Variables for Firebase
+variable "project_id" {
+  description = "GCP/Firebase Project ID"
+  type        = string
+  default     = "{{projectId}}"
+}
+
+variable "region" {
+  description = "Firebase/GCP region"
+  type        = string
+  default     = "{{region}}"
+}
+
+variable "app_display_name" {
+  description = "Firebase Web App display name"
+  type        = string
+  default     = "{{appDisplayName}}"
+}
+
+variable "site_id" {
+  description = "Firebase Hosting site ID"
+  type        = string
+  default     = "{{siteId}}"
+}
+
+variable "function_name" {
+  description = "Cloud Function name"
+  type        = string
+  default     = "{{functionName}}"
+}
+
+variable "runtime" {
+  description = "Function runtime"
+  type        = string
+  default     = "{{runtime}}"
+}
+
+variable "environment" {
+  description = "Environment (dev/staging/prod)"
+  type        = string
+  default     = "{{environment}}"
+}

package/plugins/specweave/templates/iac/gcp-cloud-functions/defaults.json

@@ -0,0 +1,26 @@
+{
+  "projectId": "my-gcp-project",
+  "region": "us-central1",
+  "functionName": "my-cloud-function",
+  "runtime": "nodejs20",
+  "entryPoint": "handler",
+  "memoryMb": 256,
+  "timeoutSeconds": 60,
+  "minInstances": 0,
+  "maxInstances": 100,
+  "environment": "dev",
+  "databaseId": "(default)",
+  "collectionId": "my-collection",
+  "serviceAccountId": "my-function-sa",
+  "corsOrigins": ["*"],
+  "projectName": "my-project",
+  "enableSecretManager": false,
+  "enableVpc": false,
+  "enableCloudArmor": false,
+  "enableConcurrency": false,
+  "maxConcurrentRequests": 80,
+  "enableCloudLogging": true,
+  "enableCloudMonitoring": true,
+  "bucketName": "my-function-source",
+  "bucketLocation": "US"
+}

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)