specweave 0.21.2 → 0.22.0

package/plugins/specweave/iac-templates/firebase/README.md.hbs

@@ -0,0 +1,487 @@
+# {{projectName}} - Firebase Infrastructure
+
+🚀 Generated by **SpecWeave Serverless Intelligence**
+
+## Overview
+
+This Terraform configuration deploys a full-stack serverless application on Firebase with the following components:
+
+- **Firebase Hosting**: Static site hosting with global CDN{{#if enableAuth}}
+- **Firebase Authentication**: Email/password authentication{{/if}}{{#if databaseName}}
+- **Firestore**: NoSQL database with security rules{{/if}}
+- **Cloud Storage**: File storage with security rules
+- **Cloud Functions for Firebase**: Serverless backend functions
+
+## Architecture
+
+```
+{{#if enableAuth}}
+Internet → Firebase Hosting → Cloud Functions → Firestore
+                ↓
+         Firebase Auth
+{{else}}
+Internet → Firebase Hosting → Cloud Functions → Firestore
+{{/if}}
+```
+
+## Prerequisites
+
+1. **Google Cloud Account** with billing enabled
+2. **Firebase CLI** installed: `npm install -g firebase-tools`
+3. **gcloud CLI** installed and authenticated
+4. **Terraform** >= 1.0 installed
+5. **Firebase project** created (or will be created by Terraform)
+
+## Quick Start
+
+### 1. Create Firebase Project (if new)
+
+```bash
+# Login to Firebase
+firebase login
+
+# Create new Firebase project
+firebase projects:create {{kebabCase projectName}}-{{environment}}
+
+# Set project ID
+export PROJECT_ID={{kebabCase projectName}}-{{environment}}
+```
+
+### 2. Enable Required APIs
+
+```bash
+gcloud auth application-default login
+gcloud config set project $PROJECT_ID
+
+# Enable APIs
+gcloud services enable firebase.googleapis.com
+gcloud services enable firestore.googleapis.com
+gcloud services enable cloudfunctions.googleapis.com
+gcloud services enable firebasehosting.googleapis.com
+{{#if enableAuth}}
+gcloud services enable identitytoolkit.googleapis.com
+{{/if}}
+```
+
+### 3. Initialize Terraform
+
+```bash
+terraform init
+```
+
+### 4. Review Plan
+
+```bash
+terraform plan -var="project_id=$PROJECT_ID"
+```
+
+### 5. Deploy Infrastructure
+
+```bash
+terraform apply -var="project_id=$PROJECT_ID"
+```
+
+### 6. Initialize Firebase in Your Project
+
+```bash
+# Initialize Firebase
+firebase init
+
+# Select:
+# - Hosting
+# - Functions
+# - Firestore
+{{#if enableAuth}}
+# - Authentication
+{{/if}}
+
+# Use existing project: Select your Firebase project
+```
+
+### 7. Deploy Firebase Resources
+
+```bash
+# Deploy hosting
+firebase deploy --only hosting
+
+# Deploy functions
+firebase deploy --only functions
+
+# Deploy Firestore rules (if customized)
+firebase deploy --only firestore:rules
+
+# Deploy Storage rules (if customized)
+firebase deploy --only storage:rules
+```
+
+### 8. Test Deployment
+
+```bash
+# Get hosting URL
+HOSTING_URL=$(terraform output -raw hosting_url)
+
+# Open in browser
+echo "Visit: $HOSTING_URL"
+```
+
+## Configuration
+
+### Variables
+
+Edit `terraform.tfvars` to customize:
+
+```hcl
+project_id         = "{{kebabCase projectName}}-{{environment}}"
+project_name       = "{{projectName}}"
+environment        = "{{environment}}"
+region             = "{{#if region}}{{region}}{{else}}us-central1{{/if}}"
+function_name      = "{{functionName}}"
+{{#if databaseName}}
+database_name      = "{{databaseName}}"
+firestore_location = "us-central"
+{{/if}}
+{{#if enableAuth}}
+enable_auth        = true
+{{/if}}
+```
+
+### Firebase Configuration
+
+After Terraform deployment, get your Firebase config:
+
+```bash
+# Get Web App config
+terraform output web_app_api_key
+terraform output web_app_auth_domain
+```
+
+Add to your web app:
+
+```javascript
+// firebaseConfig.js
+import { initializeApp } from 'firebase/app';
+{{#if enableAuth}}
+import { getAuth } from 'firebase/auth';
+{{/if}}
+{{#if databaseName}}
+import { getFirestore } from 'firebase/firestore';
+{{/if}}
+import { getStorage } from 'firebase/storage';
+
+const firebaseConfig = {
+  apiKey: process.env.FIREBASE_API_KEY,
+  authDomain: "{{kebabCase projectName}}-{{environment}}.firebaseapp.com",
+  projectId: "{{kebabCase projectName}}-{{environment}}",
+  storageBucket: "{{kebabCase projectName}}-{{environment}}.appspot.com",
+  messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
+  appId: "YOUR_APP_ID"
+};
+
+const app = initializeApp(firebaseConfig);
+{{#if enableAuth}}
+export const auth = getAuth(app);
+{{/if}}
+{{#if databaseName}}
+export const db = getFirestore(app);
+{{/if}}
+export const storage = getStorage(app);
+```
+
+## Outputs
+
+After deployment, Terraform provides these outputs:
+
+- `firebase_project_id`: Firebase project ID
+- `web_app_id`: Firebase Web App ID
+- `hosting_url`: Firebase Hosting URL{{#if databaseName}}
+- `firestore_database_name`: Firestore database name{{/if}}
+- `storage_bucket`: Storage bucket name
+
+## Resource Details
+
+### Firebase Hosting
+
+- **Global CDN**: Automatic SSL, HTTP/2, and fast content delivery
+- **Custom Domain**: Add via Firebase Console
+- **Deploy Command**: `firebase deploy --only hosting`
+
+### Cloud Functions for Firebase
+
+Deploy functions using Firebase SDK:
+
+```javascript
+// functions/index.js
+const {onRequest} = require("firebase-functions/v2/https");
+{{#if databaseName}}
+const {getFirestore} = require("firebase-admin/firestore");
+{{/if}}
+const admin = require("firebase-admin");
+
+admin.initializeApp();
+{{#if databaseName}}
+const db = getFirestore();
+{{/if}}
+
+exports.{{functionName}} = onRequest(async (req, res) => {
+  {{#if databaseName}}
+  const snapshot = await db.collection('items').get();
+  const items = snapshot.docs.map(doc => doc.data());
+  res.json({items});
+  {{else}}
+  res.json({message: "Hello from Firebase!"});
+  {{/if}}
+});
+```
+
+{{#if databaseName}}
+### Firestore
+
+- **Database**: `{{databaseName}}-{{environment}}`
+- **Security Rules**: Deployed via Terraform{{#if (eq environment "prod")}}
+- **Access Control**: Strict production rules{{else}}
+- **Access Control**: Permissive for development{{/if}}
+- **Point-in-Time Recovery**: {{#if (eq environment "prod")}}Enabled{{else}}Disabled{{/if}}
+
+**Security Rules** (in `firestore.rules`):
+```
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+  }
+}
+```
+{{/if}}
+
+{{#if enableAuth}}
+### Firebase Authentication
+
+- **Email/Password**: Enabled
+- **Additional Providers**: Configure in Firebase Console
+- **Custom Claims**: Add via Cloud Functions
+
+**Example usage**:
+```javascript
+import { getAuth, signInWithEmailAndPassword } from 'firebase/auth';
+
+const auth = getAuth();
+signInWithEmailAndPassword(auth, email, password)
+  .then((userCredential) => {
+    const user = userCredential.user;
+    console.log('Signed in:', user.uid);
+  });
+```
+{{/if}}
+
+### Cloud Storage for Firebase
+
+- **Bucket**: `{{projectId}}.appspot.com`
+- **Security Rules**: User-specific folders{{#if (eq environment "prod")}}
+- **File Size Limit**: 10MB{{else}}
+- **File Size Limit**: Unlimited (dev){{/if}}
+
+## Security Best Practices
+
+✅ **Implemented**:
+- Firestore security rules (authenticated access)
+- Storage security rules (user-specific folders)
+- Service account with least privilege{{#if (eq environment "prod")}}
+- Point-in-time recovery for Firestore
+- Strict validation in production rules{{/if}}
+
+⚠️ **TODO**:
+- Customize Firestore rules for your data model
+- Add reCAPTCHA to authentication
+- Enable App Check for abuse prevention
+- Add multi-factor authentication
+- Implement custom authentication flows
+
+## Cost Estimation
+
+### Free Tier (Spark Plan - Always Free)
+
+Firebase offers a generous free tier:
+- **Hosting**: 10 GB storage, 360 MB/day transfer
+- **Firestore**: 50K reads/day, 20K writes/day, 1GB storage
+- **Storage**: 5 GB stored, 1 GB/day download
+- **Functions**: 125K/month invocations, 40K GB-seconds
+- **Authentication**: Unlimited (free forever)
+
+### Estimated Monthly Cost (Blaze Plan - Pay as you go)
+
+**Development (Within Free Tier)**:
+- Hosting: $0.00
+- Firestore: $0.00
+- Storage: $0.00
+- Functions: $0.00
+- **Total**: $0.00/month
+
+**Staging (Light usage)**:
+- Hosting: ~$1.00
+- Firestore: ~$2.00
+- Storage: ~$0.50
+- Functions: ~$1.00
+- **Total**: ~$4.50/month
+
+**Production (Moderate traffic)**:
+- Hosting (1M requests): ~$5.00
+- Firestore (1M operations): ~$10.00
+- Storage (10GB + transfers): ~$2.00
+- Functions (500K invocations): ~$8.00
+- **Total**: ~$25.00/month
+
+💡 **Tip**: Firebase free tier is very generous. Most small apps stay free.
+
+## Monitoring
+
+### Firebase Console
+
+Monitor your app in [Firebase Console](https://console.firebase.google.com):
+
+- **Performance Monitoring**: Page load times, network requests
+- **Crashlytics**: Crash reports and analytics
+- **Analytics**: User engagement and behavior
+- **Usage Dashboard**: Firestore, Storage, Functions usage
+
+### Cloud Logging
+
+```bash
+# View function logs
+firebase functions:log
+
+# Or in Cloud Console
+gcloud logging read "resource.type=cloud_function" --limit 50
+```
+
+### Recommended Alerts
+
+Set up budget alerts in GCP Console:
+```bash
+# Create budget alert
+gcloud billing budgets create \
+  --billing-account=BILLING_ACCOUNT_ID \
+  --display-name="{{projectName}} Budget Alert" \
+  --budget-amount=50USD \
+  --threshold-rule=percent=80 \
+  --threshold-rule=percent=100
+```
+
+## Deployment Workflow
+
+### Development
+
+```bash
+terraform workspace new dev
+terraform workspace select dev
+terraform apply -var="environment=dev"
+firebase use dev
+firebase deploy
+```
+
+### Staging
+
+```bash
+terraform workspace new staging
+terraform workspace select staging
+terraform apply -var="environment=staging"
+firebase use staging
+firebase deploy
+```
+
+### Production
+
+```bash
+terraform workspace new prod
+terraform workspace select prod
+terraform apply -var="environment=prod"
+firebase use production
+firebase deploy
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Deploy to Firebase
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Deploy to Firebase
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
+          channelId: live
+          projectId: {{kebabCase projectName}}-{{environment}}
+```
+
+## Cleanup
+
+To destroy all resources:
+
+```bash
+terraform destroy
+```
+
+⚠️ **Warning**: This will permanently delete:
+- Firebase Hosting sites
+- Firestore data
+- Cloud Storage files
+- Authentication users
+
+## Troubleshooting
+
+**"Project is not a Firebase project"?**
+1. Enable Firebase: `firebase projects:addfirebase $PROJECT_ID`
+2. Re-run Terraform apply
+
+**Firestore rules not applying?**
+1. Check syntax: `firebase deploy --only firestore:rules`
+2. Review in Firebase Console
+
+**Functions deployment failing?**
+1. Check Node.js version compatibility
+2. Review function logs: `firebase functions:log`
+3. Verify IAM permissions
+
+## Next Steps
+
+1. **Customize Security Rules**: Tailor Firestore and Storage rules to your data model
+2. **Add Performance Monitoring**: Install Firebase Performance SDK
+3. **Enable Analytics**: Add Google Analytics for Firebase
+4. **Add Custom Domain**: Configure custom domain in Hosting settings
+5. **Implement CI/CD**: Automate deployments with GitHub Actions
+
+## Resources
+
+- [Firebase Documentation](https://firebase.google.com/docs)
+- [Firestore Documentation](https://firebase.google.com/docs/firestore)
+- [Firebase Hosting Documentation](https://firebase.google.com/docs/hosting)
+- [Cloud Functions for Firebase](https://firebase.google.com/docs/functions)
+- [Firebase Authentication](https://firebase.google.com/docs/auth)
+
+---
+
+**Generated by SpecWeave** | [Learn More](https://spec-weave.com)

package/plugins/specweave/iac-templates/firebase/defaults.json

@@ -0,0 +1,55 @@
+{
+  "platform": "firebase",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "enableAuth": true,
+  "enableHosting": true,
+  "enableFunctions": true,
+  "enableStorage": true,
+  "firestore": {
+    "type": "FIRESTORE_NATIVE",
+    "concurrencyMode": {
+      "dev": "PESSIMISTIC",
+      "staging": "OPTIMISTIC",
+      "prod": "OPTIMISTIC"
+    },
+    "pointInTimeRecovery": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "deleteProtection": {
+      "dev": false,
+      "staging": false,
+      "prod": false
+    }
+  },
+  "storage": {
+    "versioning": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "forceDestroy": {
+      "dev": true,
+      "staging": true,
+      "prod": false
+    }
+  },
+  "auth": {
+    "providers": ["email"],
+    "allowDuplicateEmails": false
+  },
+  "hosting": {
+    "rewrites": [
+      {
+        "source": "**",
+        "destination": "/index.html"
+      }
+    ]
+  },
+  "functions": {
+    "runtime": "nodejs18",
+    "region": "us-central1"
+  }
+}

package/plugins/specweave/iac-templates/firebase/environments/dev.defaults.json

@@ -0,0 +1,44 @@
+{
+  "environment": "dev",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "enableAuth": true,
+  "firestore": {
+    "concurrencyMode": "PESSIMISTIC",
+    "pointInTimeRecovery": false,
+    "deleteProtection": false,
+    "securityRules": "permissive"
+  },
+  "storage": {
+    "versioning": false,
+    "forceDestroy": true,
+    "fileSizeLimit": null,
+    "securityRules": "permissive"
+  },
+  "auth": {
+    "providers": ["email"],
+    "allowDuplicateEmails": false,
+    "advancedSecurity": false
+  },
+  "hosting": {
+    "caching": "disabled",
+    "customDomain": false
+  },
+  "functions": {
+    "runtime": "nodejs18",
+    "minInstances": 0,
+    "maxInstances": 10
+  },
+  "costOptimization": {
+    "description": "Free tier optimized - Stays within Spark plan limits",
+    "estimatedMonthlyCost": "$0",
+    "freeTierEligible": true,
+    "plan": "Spark (Free)",
+    "notes": [
+      "10 GB hosting storage",
+      "50K Firestore reads/day",
+      "125K function invocations/month",
+      "Unlimited authentication"
+    ]
+  }
+}

package/plugins/specweave/iac-templates/firebase/environments/prod.defaults.json

@@ -0,0 +1,52 @@
+{
+  "environment": "prod",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "enableAuth": true,
+  "firestore": {
+    "concurrencyMode": "OPTIMISTIC",
+    "pointInTimeRecovery": true,
+    "deleteProtection": false,
+    "securityRules": "strict"
+  },
+  "storage": {
+    "versioning": true,
+    "forceDestroy": false,
+    "fileSizeLimit": "10MB",
+    "securityRules": "strict"
+  },
+  "auth": {
+    "providers": ["email", "google"],
+    "allowDuplicateEmails": false,
+    "advancedSecurity": true,
+    "mfa": true
+  },
+  "hosting": {
+    "caching": "aggressive",
+    "customDomain": true,
+    "cdn": "enabled"
+  },
+  "functions": {
+    "runtime": "nodejs18",
+    "minInstances": 1,
+    "maxInstances": 100
+  },
+  "security": {
+    "appCheckEnabled": true,
+    "recaptchaEnabled": true,
+    "strictSecurityRules": true
+  },
+  "costOptimization": {
+    "description": "Production-ready - Optimized for performance and reliability",
+    "estimatedMonthlyCost": "$25-75",
+    "freeTierEligible": false,
+    "plan": "Blaze (Pay as you go)",
+    "notes": [
+      "Point-in-time recovery enabled",
+      "1 min instance (always warm)",
+      "Strict security rules",
+      "App Check for abuse prevention",
+      "Custom domain with CDN"
+    ]
+  }
+}

package/plugins/specweave/iac-templates/firebase/environments/staging.defaults.json

@@ -0,0 +1,43 @@
+{
+  "environment": "staging",
+  "region": "us-central1",
+  "firestoreLocation": "us-central",
+  "enableAuth": true,
+  "firestore": {
+    "concurrencyMode": "OPTIMISTIC",
+    "pointInTimeRecovery": false,
+    "deleteProtection": false,
+    "securityRules": "moderate"
+  },
+  "storage": {
+    "versioning": false,
+    "forceDestroy": true,
+    "fileSizeLimit": "20MB",
+    "securityRules": "moderate"
+  },
+  "auth": {
+    "providers": ["email", "google"],
+    "allowDuplicateEmails": false,
+    "advancedSecurity": false
+  },
+  "hosting": {
+    "caching": "enabled",
+    "customDomain": false
+  },
+  "functions": {
+    "runtime": "nodejs18",
+    "minInstances": 0,
+    "maxInstances": 25
+  },
+  "costOptimization": {
+    "description": "Light usage - Blaze plan with low traffic",
+    "estimatedMonthlyCost": "$4-8",
+    "freeTierEligible": false,
+    "plan": "Blaze (Pay as you go)",
+    "notes": [
+      "Optimistic concurrency for performance",
+      "No min instances for cost savings",
+      "Moderate security rules"
+    ]
+  }
+}