specweave 0.22.0 → 0.22.2

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

@@ -0,0 +1,268 @@
+# Azure Functions + Cosmos DB Terraform Configuration
+
+**Generated by SpecWeave Serverless Architecture Intelligence**
+
+This Terraform configuration deploys:
+- Azure Function App ({{runtime}} {{runtimeVersion}} on {{osType}})
+- Azure Cosmos DB (SQL API)
+- Azure Storage Account (required for Function App)
+- App Service Plan ({{skuName}} SKU)
+{{#if enableApplicationInsights}}- Application Insights for monitoring{{/if}}
+{{#if enableKeyVault}}- Azure Key Vault for secrets management{{/if}}
+
+## Architecture
+
+```
+Azure Function App ({{functionName}})
+    ├── Runtime: {{runtime}} {{runtimeVersion}}
+    ├── Plan: {{skuName}} ({{#if (eq skuName "Y1")}}Consumption{{else}}Premium{{/if}})
+    └── Storage: {{functionName}}storage
+
+Cosmos DB ({{databaseAccountName}})
+    ├── Database: {{databaseName}}
+    ├── Container: {{containerName}}
+    ├── Partition Key: {{partitionKey}}
+    └── Throughput: {{throughput}} RU/s
+
+{{#if enableApplicationInsights}}
+Application Insights ({{functionName}}-insights)
+    └── Type: web
+{{/if}}
+
+{{#if enableKeyVault}}
+Key Vault ({{functionName}}-kv)
+    └── Secrets: Managed by Function App identity
+{{/if}}
+```
+
+## Prerequisites
+
+1. **Azure CLI** installed and authenticated:
+   ```bash
+   az login
+   az account set --subscription "YOUR_SUBSCRIPTION_ID"
+   ```
+
+2. **Terraform** v1.5.0+ installed:
+   ```bash
+   terraform version
+   ```
+
+3. **Function App code** ready to deploy:
+   - Node.js: `package.json`, `index.js`, etc.
+   - Python: `requirements.txt`, `__init__.py`, etc.
+
+## Deployment Instructions
+
+### 1. Initialize Terraform
+
+```bash
+terraform init
+```
+
+### 2. Review the Plan
+
+```bash
+terraform plan
+```
+
+**Expected resources**: ~{{#if enableKeyVault}}10{{else if enableApplicationInsights}}8{{else}}6{{/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
+
+After infrastructure is deployed, deploy your function code:
+
+```bash
+# Zip your function code
+cd ../src  # Navigate to your function source code
+zip -r function.zip .
+
+# Deploy using Azure CLI
+az functionapp deployment source config-zip \
+  --resource-group {{resourceGroupName}} \
+  --name {{functionName}} \
+  --src function.zip
+```
+
+### 5. Test Your Function
+
+```bash
+# Get function URL
+FUNCTION_URL=$(terraform output -raw function_app_url)
+
+# Test HTTP trigger (example)
+curl "${FUNCTION_URL}/api/hello?name=World"
+```
+
+## Cost Estimation
+
+### Development Environment
+
+**Azure Function App (Consumption Plan)**:
+- Execution: 1M requests/month = Free (2M free tier)
+- Execution time: 100,000 GB-s/month = Free (400,000 GB-s free tier)
+- **Total**: $0/month (within free tier)
+
+**Cosmos DB**:
+- Throughput: {{throughput}} RU/s × $0.008/hour = ${{multiply throughput 0.008 720}}/month
+- Storage: 1 GB = Free (25 GB free tier)
+- **Total**: ~${{multiply throughput 0.008 720}}/month
+
+**Storage Account**:
+- LRS storage: 1 GB = ~$0.02/month
+- Transactions: Minimal cost
+- **Total**: ~$0.50/month
+
+**Application Insights**:
+- First 5 GB = Free
+- **Total**: $0/month (within free tier)
+
+**Total Monthly Cost (Dev)**: ~${{add (multiply throughput 0.008 720) 0.5}}/month
+
+{{#if (eq environment "prod")}}
+### Production Environment (Estimated)
+
+**Note**: Production costs depend on actual usage. Estimate above assumes:
+- 10M requests/month
+- {{throughput}} RU/s Cosmos DB throughput
+- ~10 GB storage
+
+For accurate production estimates, use [Azure Pricing Calculator](https://azure.microsoft.com/pricing/calculator/).
+{{/if}}
+
+## Free Tier Optimization Tips
+
+1. **Function App**:
+   - Use Consumption Plan (Y1) for variable workloads
+   - Stay under 1M executions/month for free tier
+   - Optimize memory allocation (lower = cheaper)
+
+2. **Cosmos DB**:
+   - Start with 400 RU/s (minimum)
+   - Use autoscale for variable workloads
+   - Monitor RU consumption in Azure Portal
+
+3. **Application Insights**:
+   - First 5 GB/month is free
+   - Use sampling to reduce data volume
+   - Set retention to 90 days
+
+4. **Storage Account**:
+   - Use LRS (cheapest replication)
+   - Clean up old blobs and logs
+   - Enable lifecycle management
+
+## Monitoring
+
+{{#if enableApplicationInsights}}
+**Application Insights** is enabled. View metrics at:
+```
+https://portal.azure.com/#@/resource${terraform output -raw application_insights_id}/overview
+```
+
+Key metrics to monitor:
+- Request rate and response times
+- Failed requests
+- Cosmos DB RU consumption
+- Function execution count and duration
+{{else}}
+**Application Insights** is not enabled. To enable monitoring:
+1. Set `enableApplicationInsights = true` in `defaults.json`
+2. Re-apply Terraform configuration
+{{/if}}
+
+## Security Best Practices
+
+1. **Managed Identity**: Function App uses System-Assigned Managed Identity
+   - No credentials in code
+   - Automatic rotation
+   - Azure RBAC for access control
+
+2. **Secrets Management**:
+{{#if enableKeyVault}}
+   - ✅ Key Vault enabled for secrets
+   - Store connection strings in Key Vault
+   - Reference via `@Microsoft.KeyVault(SecretUri=...)`
+{{else}}
+   - ⚠️ Key Vault not enabled
+   - Enable with `enableKeyVault = true`
+{{/if}}
+
+3. **HTTPS Only**: Function App enforces HTTPS
+4. **CORS**: Configured for origins: {{corsOrigins}}
+5. **Network Security**:
+{{#if enableVnet}}
+   - ✅ VNet integration enabled
+{{else}}
+   - ⚠️ VNet integration not enabled (public access)
+   - Enable with `enableVnet = true`
+{{/if}}
+
+## Cleanup
+
+To destroy all resources:
+
+```bash
+terraform destroy
+```
+
+**Warning**: This will permanently delete:
+- Function App and all deployed code
+- Cosmos DB and all data
+- Storage Account and all blobs
+- Application Insights telemetry data
+
+## Troubleshooting
+
+### "Resource name already exists"
+- Azure resource names must be globally unique
+- Modify `appName` in `defaults.json` or `*.tfvars`
+
+### "Insufficient permissions"
+- Ensure you have Owner/Contributor role on subscription
+- Run `az account show` to verify correct subscription
+
+### "Cosmos DB throughput too low"
+- Minimum throughput is 400 RU/s
+- Adjust `throughput` in `defaults.json` or `*.tfvars`
+
+### "Function App not responding"
+- Check Application Insights for errors
+- Verify function code is deployed (`az functionapp deployment list-publishing-credentials`)
+- Check CORS settings if calling from browser
+
+## Next Steps
+
+1. **Deploy your function code** (see step 4 above)
+2. **Set up CI/CD** with Azure DevOps or GitHub Actions
+3. **Configure custom domains** for production
+4. **Set up monitoring alerts** in Application Insights
+5. **Enable backup** for Cosmos DB (set `enableBackup = true`)
+
+## Support
+
+- **Azure Documentation**: https://docs.microsoft.com/azure/azure-functions/
+- **Terraform Azure Provider**: https://registry.terraform.io/providers/hashicorp/azurerm/
+- **SpecWeave**: https://spec-weave.com
+
+---
+
+**Generated**: {{currentDate}}
+**SpecWeave Version**: {{specweaveVersion}}

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

@@ -0,0 +1,34 @@
+# Development Environment Variables for Azure Functions + Cosmos DB
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+location             = "eastus"
+resource_group_name  = "{{projectName}}-dev-rg"
+app_name             = "{{projectName}}-dev-app"
+runtime              = "{{runtime}}"
+runtime_version      = "{{runtimeVersion}}"
+os_type              = "Linux"
+sku_name             = "Y1"  # Consumption Plan (free tier eligible)
+environment          = "dev"
+
+# Cosmos DB (optimized for dev - minimum cost)
+database_account_name = "{{projectName}}-dev-cosmos"
+database_name         = "{{databaseName}}"
+container_name        = "{{containerName}}"
+partition_key         = "{{partitionKey}}"
+throughput            = 400  # Minimum (cheapest)
+
+# CORS (allow all for development)
+cors_origins = ["*"]
+
+# Storage Account (cheapest options)
+storage_account_tier        = "Standard"
+storage_account_replication = "LRS"  # Locally Redundant Storage (cheapest)
+
+# Project tagging
+project_name = "{{projectName}}"
+
+# Free tier optimization
+# - Consumption Plan (Y1) for Function App
+# - 400 RU/s Cosmos DB (minimum, stays within free tier for low usage)
+# - LRS storage (cheapest)
+# - Application Insights first 5 GB free

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

@@ -0,0 +1,46 @@
+# Production Environment Variables for Azure Functions + Cosmos DB
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+location             = "eastus"
+resource_group_name  = "{{projectName}}-prod-rg"
+app_name             = "{{projectName}}-prod-app"
+runtime              = "{{runtime}}"
+runtime_version      = "{{runtimeVersion}}"
+os_type              = "Linux"
+sku_name             = "EP2"  # Elastic Premium EP2 (production-grade)
+environment          = "prod"
+
+# Cosmos DB (production settings with backup)
+database_account_name = "{{projectName}}-prod-cosmos"
+database_name         = "{{databaseName}}"
+container_name        = "{{containerName}}"
+partition_key         = "{{partitionKey}}"
+throughput            = 4000  # Higher throughput for production
+
+# CORS (restrict to production domain only)
+cors_origins = ["https://{{projectName}}.com"]
+
+# Storage Account (GRS for geo-redundancy)
+storage_account_tier        = "Standard"
+storage_account_replication = "GRS"  # Geo-Redundant Storage
+
+# Project tagging
+project_name = "{{projectName}}"
+
+# Production features (uncomment to enable)
+# enable_automatic_failover = true
+# enable_multi_region       = true
+# secondary_regions         = ["westus2", "northeurope"]
+# enable_backup             = true
+# enable_key_vault          = true
+# enable_vnet               = true
+
+# Production optimizations
+# - Elastic Premium (EP2) for high performance and VNet support
+# - 4000 RU/s Cosmos DB with autoscale option
+# - GRS storage for disaster recovery
+# - Multi-region Cosmos DB (optional, comment out to enable)
+# - Automatic failover enabled (optional)
+# - Continuous backup (optional)
+# - Key Vault for secrets (optional)
+# - VNet integration for secure networking (optional)

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

@@ -0,0 +1,34 @@
+# Staging Environment Variables for Azure Functions + Cosmos DB
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+location             = "eastus"
+resource_group_name  = "{{projectName}}-staging-rg"
+app_name             = "{{projectName}}-staging-app"
+runtime              = "{{runtime}}"
+runtime_version      = "{{runtimeVersion}}"
+os_type              = "Linux"
+sku_name             = "EP1"  # Elastic Premium (better performance than Consumption)
+environment          = "staging"
+
+# Cosmos DB (moderate settings)
+database_account_name = "{{projectName}}-staging-cosmos"
+database_name         = "{{databaseName}}"
+container_name        = "{{containerName}}"
+partition_key         = "{{partitionKey}}"
+throughput            = 1000  # Higher throughput for staging tests
+
+# CORS (restrict to known origins)
+cors_origins = ["https://staging.{{projectName}}.com"]
+
+# Storage Account (ZRS for better durability)
+storage_account_tier        = "Standard"
+storage_account_replication = "ZRS"  # Zone-Redundant Storage
+
+# Project tagging
+project_name = "{{projectName}}"
+
+# Staging optimizations
+# - Elastic Premium (EP1) for consistent performance
+# - 1000 RU/s Cosmos DB for realistic load testing
+# - ZRS storage for better durability
+# - Single region deployment

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

@@ -0,0 +1,225 @@
+# Azure Functions + Cosmos DB Terraform Configuration
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+# Resource Group
+resource "azurerm_resource_group" "{{snakeCase resourceGroupName}}" {
+  name     = "{{resourceGroupName}}"
+  location = "{{location}}"
+
+  tags = {
+    Environment = "{{environment}}"
+    ManagedBy   = "Terraform"
+    Project     = "{{projectName}}"
+  }
+}
+
+# Storage Account (required for Function App)
+resource "azurerm_storage_account" "{{snakeCase functionName}}" {
+  name                     = "{{snakeCase functionName}}storage"
+  resource_group_name      = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  location                 = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+  account_tier             = "{{storageAccountTier}}"
+  account_replication_type = "{{storageAccountReplication}}"
+
+  tags = {
+    Environment = "{{environment}}"
+    ManagedBy   = "Terraform"
+    Project     = "{{projectName}}"
+  }
+}
+
+# App Service Plan (Consumption Plan)
+resource "azurerm_service_plan" "{{snakeCase functionName}}" {
+  name                = "{{appName}}-plan"
+  resource_group_name = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  location            = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+  os_type             = "{{osType}}"
+  sku_name            = "{{skuName}}"
+
+  tags = {
+    Environment = "{{environment}}"
+    ManagedBy   = "Terraform"
+    Project     = "{{projectName}}"
+  }
+}
+
+{{#if enableApplicationInsights}}
+# Application Insights
+resource "azurerm_application_insights" "{{snakeCase functionName}}" {
+  name                = "{{appName}}-insights"
+  resource_group_name = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  location            = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+  application_type    = "web"
+
+  tags = {
+    Environment = "{{environment}}"
+    ManagedBy   = "Terraform"
+    Project     = "{{projectName}}"
+  }
+}
+{{/if}}
+
+# Linux Function App
+resource "azurerm_linux_function_app" "{{snakeCase functionName}}" {
+  name                = "{{appName}}"
+  resource_group_name = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  location            = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+
+  storage_account_name       = azurerm_storage_account.{{snakeCase functionName}}.name
+  storage_account_access_key = azurerm_storage_account.{{snakeCase functionName}}.primary_access_key
+  service_plan_id            = azurerm_service_plan.{{snakeCase functionName}}.id
+
+  site_config {
+    application_stack {
+      {{#if (eq runtime "node")}}
+      node_version = "{{runtimeVersion}}"
+      {{else if (eq runtime "python")}}
+      python_version = "{{runtimeVersion}}"
+      {{else if (eq runtime "dotnet")}}
+      dotnet_version = "{{runtimeVersion}}"
+      {{/if}}
+    }
+
+    cors {
+      allowed_origins = {{tfList corsOrigins}}
+    }
+
+    {{#if enableApplicationInsights}}
+    application_insights_key             = azurerm_application_insights.{{snakeCase functionName}}.instrumentation_key
+    application_insights_connection_string = azurerm_application_insights.{{snakeCase functionName}}.connection_string
+    {{/if}}
+  }
+
+  app_settings = {
+    "ENVIRONMENT"                  = "{{environment}}"
+    "COSMOS_DB_ENDPOINT"           = azurerm_cosmosdb_account.{{snakeCase databaseAccountName}}.endpoint
+    "COSMOS_DB_KEY"                = azurerm_cosmosdb_account.{{snakeCase databaseAccountName}}.primary_key
+    "COSMOS_DB_DATABASE"           = azurerm_cosmosdb_sql_database.{{snakeCase databaseName}}.name
+    "COSMOS_DB_CONTAINER"          = azurerm_cosmosdb_sql_container.{{snakeCase containerName}}.name
+    "FUNCTIONS_WORKER_RUNTIME"     = "{{runtime}}"
+    {{#if customAppSettings}}
+    {{#each customAppSettings}}
+    "{{@key}}" = "{{this}}"
+    {{/each}}
+    {{/if}}
+  }
+
+  identity {
+    type = "SystemAssigned"
+  }
+
+  tags = {
+    Environment = "{{environment}}"
+    ManagedBy   = "Terraform"
+    Project     = "{{projectName}}"
+  }
+}
+
+# Cosmos DB Account
+resource "azurerm_cosmosdb_account" "{{snakeCase databaseAccountName}}" {
+  name                = "{{databaseAccountName}}"
+  resource_group_name = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  location            = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+  offer_type          = "Standard"
+  kind                = "GlobalDocumentDB"
+
+  consistency_policy {
+    consistency_level       = "Session"
+    max_interval_in_seconds = 5
+    max_staleness_prefix    = 100
+  }
+
+  geo_location {
+    location          = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+    failover_priority = 0
+  }
+
+  {{#if enableMultiRegion}}
+  {{#each secondaryRegions}}
+  geo_location {
+    location          = "{{this}}"
+    failover_priority = {{@index}}
+  }
+  {{/each}}
+  {{/if}}
+
+  {{#if enableAutomaticFailover}}
+  enable_automatic_failover = true
+  {{/if}}
+
+  {{#if enableBackup}}
+  backup {
+    type                = "Continuous"
+    interval_in_minutes = 240
+    retention_in_hours  = 8
+  }
+  {{/if}}
+
+  tags = {
+    Environment = "{{environment}}"
+    ManagedBy   = "Terraform"
+    Project     = "{{projectName}}"
+  }
+}
+
+# Cosmos DB SQL Database
+resource "azurerm_cosmosdb_sql_database" "{{snakeCase databaseName}}" {
+  name                = "{{databaseName}}"
+  resource_group_name = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  account_name        = azurerm_cosmosdb_account.{{snakeCase databaseAccountName}}.name
+}
+
+# Cosmos DB SQL Container
+resource "azurerm_cosmosdb_sql_container" "{{snakeCase containerName}}" {
+  name                  = "{{containerName}}"
+  resource_group_name   = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  account_name          = azurerm_cosmosdb_account.{{snakeCase databaseAccountName}}.name
+  database_name         = azurerm_cosmosdb_sql_database.{{snakeCase databaseName}}.name
+  partition_key_path    = "{{partitionKey}}"
+  partition_key_version = 1
+  throughput            = {{throughput}}
+
+  indexing_policy {
+    indexing_mode = "consistent"
+
+    included_path {
+      path = "/*"
+    }
+
+    excluded_path {
+      path = "/\"_etag\"/?"
+    }
+  }
+}
+
+{{#if enableKeyVault}}
+# Key Vault
+resource "azurerm_key_vault" "{{snakeCase functionName}}" {
+  name                       = "{{appName}}-kv"
+  resource_group_name        = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+  location                   = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+  tenant_id                  = data.azurerm_client_config.current.tenant_id
+  sku_name                   = "standard"
+  soft_delete_retention_days = 7
+  purge_protection_enabled   = false
+
+  access_policy {
+    tenant_id = data.azurerm_client_config.current.tenant_id
+    object_id = azurerm_linux_function_app.{{snakeCase functionName}}.identity[0].principal_id
+
+    secret_permissions = [
+      "Get",
+      "List"
+    ]
+  }
+
+  tags = {
+    Environment = "{{environment}}"
+    ManagedBy   = "Terraform"
+    Project     = "{{projectName}}"
+  }
+}
+
+# Data source for current Azure client config
+data "azurerm_client_config" "current" {}
+{{/if}}

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

@@ -0,0 +1,89 @@
+# Output Values for Azure Functions + Cosmos DB
+# Generated by SpecWeave Serverless Architecture Intelligence
+
+output "resource_group_name" {
+  description = "Resource group name"
+  value       = azurerm_resource_group.{{snakeCase resourceGroupName}}.name
+}
+
+output "resource_group_location" {
+  description = "Resource group location"
+  value       = azurerm_resource_group.{{snakeCase resourceGroupName}}.location
+}
+
+output "function_app_name" {
+  description = "Function App name"
+  value       = azurerm_linux_function_app.{{snakeCase functionName}}.name
+}
+
+output "function_app_id" {
+  description = "Function App ID"
+  value       = azurerm_linux_function_app.{{snakeCase functionName}}.id
+}
+
+output "function_app_default_hostname" {
+  description = "Function App default hostname (URL)"
+  value       = azurerm_linux_function_app.{{snakeCase functionName}}.default_hostname
+}
+
+output "function_app_url" {
+  description = "Function App HTTPS URL"
+  value       = "https://${azurerm_linux_function_app.{{snakeCase functionName}}.default_hostname}"
+}
+
+output "function_app_principal_id" {
+  description = "Function App managed identity principal ID"
+  value       = azurerm_linux_function_app.{{snakeCase functionName}}.identity[0].principal_id
+}
+
+output "cosmos_db_endpoint" {
+  description = "Cosmos DB endpoint URL"
+  value       = azurerm_cosmosdb_account.{{snakeCase databaseAccountName}}.endpoint
+}
+
+output "cosmos_db_id" {
+  description = "Cosmos DB account ID"
+  value       = azurerm_cosmosdb_account.{{snakeCase databaseAccountName}}.id
+}
+
+output "cosmos_db_database_name" {
+  description = "Cosmos DB database name"
+  value       = azurerm_cosmosdb_sql_database.{{snakeCase databaseName}}.name
+}
+
+output "cosmos_db_container_name" {
+  description = "Cosmos DB container name"
+  value       = azurerm_cosmosdb_sql_container.{{snakeCase containerName}}.name
+}
+
+output "storage_account_name" {
+  description = "Storage account name"
+  value       = azurerm_storage_account.{{snakeCase functionName}}.name
+}
+
+output "storage_account_primary_connection_string" {
+  description = "Storage account primary connection string"
+  value       = azurerm_storage_account.{{snakeCase functionName}}.primary_connection_string
+  sensitive   = true
+}
+
+{{#if enableApplicationInsights}}
+output "application_insights_instrumentation_key" {
+  description = "Application Insights instrumentation key"
+  value       = azurerm_application_insights.{{snakeCase functionName}}.instrumentation_key
+  sensitive   = true
+}
+
+output "application_insights_connection_string" {
+  description = "Application Insights connection string"
+  value       = azurerm_application_insights.{{snakeCase functionName}}.connection_string
+  sensitive   = true
+}
+{{/if}}
+
+{{#if enableKeyVault}}
+output "key_vault_uri" {
+  description = "Key Vault URI"
+  value       = azurerm_key_vault.{{snakeCase functionName}}.vault_uri
+}
+{{/if}}