specweave 0.21.2 → 0.22.0

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

@@ -0,0 +1,534 @@
+# {{projectName}} - Supabase Infrastructure
+
+🚀 Generated by **SpecWeave Serverless Intelligence**
+
+## Overview
+
+This Terraform configuration deploys a full-stack serverless application on Supabase with the following components:
+
+- **PostgreSQL Database**: Serverless Postgres with automatic scaling{{#if databaseName}}
+- **Row Level Security (RLS)**: Database-level authorization{{/if}}
+- **Authentication**: Email/password + OAuth providers
+- **Storage**: File storage with access control
+- **Edge Functions**: Deno-based serverless functions
+- **Realtime**: WebSocket subscriptions to database changes
+- **Auto-generated REST API**: PostgREST API for database access
+
+## Architecture
+
+```
+{{#if databaseName}}
+Internet → Supabase API Gateway → PostgreSQL (RLS)
+              ↓                       ↓
+         Edge Functions          Realtime
+              ↓
+          Storage
+{{else}}
+Internet → Supabase API Gateway → PostgreSQL
+              ↓
+         Edge Functions
+{{/if}}
+```
+
+## Prerequisites
+
+{{#unless selfHosted}}
+1. **Supabase Account**: Sign up at https://supabase.com
+2. **Supabase CLI**: `npm install -g supabase`
+3. **Terraform** >= 1.0 installed
+4. **Personal Access Token**: Create at https://app.supabase.com/account/tokens
+{{else}}
+1. **Docker** and **Docker Compose** installed
+2. **Terraform** >= 1.0 installed
+3. **Sufficient disk space** for PostgreSQL data
+{{/unless}}
+
+## Quick Start
+
+{{#unless selfHosted}}
+### 1. Login to Supabase
+
+```bash
+supabase login
+```
+
+### 2. Get Organization ID
+
+```bash
+# List organizations
+supabase orgs list
+
+# Copy your organization ID
+```
+
+### 3. Create Access Token
+
+1. Go to https://app.supabase.com/account/tokens
+2. Create a new token
+3. Copy the token value
+
+### 4. Configure Terraform
+
+Create `terraform.tfvars`:
+
+```hcl
+organization_id        = "your-org-id"
+supabase_access_token  = "sbp_xxx"
+database_password      = "secure-password-min-12-chars"
+project_name           = "{{projectName}}"
+environment            = "{{environment}}"
+region                 = "{{#if region}}{{region}}{{else}}us-east-1{{/if}}"
+```
+
+### 5. Initialize Terraform
+
+```bash
+terraform init
+```
+
+### 6. Review Plan
+
+```bash
+terraform plan
+```
+
+### 7. Deploy
+
+```bash
+terraform apply
+```
+
+### 8. Get Project Details
+
+```bash
+# Get API URL
+terraform output api_url
+
+# Get anonymous key (for client-side)
+terraform output anon_key
+
+# Get service role key (for server-side)
+terraform output service_role_key
+```
+
+### 9. Initialize Local Development
+
+```bash
+# Link to your project
+supabase link --project-ref $(terraform output -raw project_ref)
+
+# Pull remote schema
+supabase db pull
+
+# Start local development
+supabase start
+```
+
+{{else}}
+### 1. Configure Environment
+
+Create `terraform.tfvars`:
+
+```hcl
+database_password = "secure-password-min-12-chars"
+project_name      = "{{projectName}}"
+environment       = "{{environment}}"
+data_path         = "/var/lib/supabase"
+```
+
+### 2. Initialize Terraform
+
+```bash
+terraform init
+```
+
+### 3. Deploy Self-Hosted Stack
+
+```bash
+terraform apply
+```
+
+### 4. Access Services
+
+```bash
+# API Gateway
+API_URL=$(terraform output -raw api_url)
+
+# Studio (Admin UI)
+STUDIO_URL=$(terraform output -raw studio_url)
+
+# PostgreSQL
+DB_URL=$(terraform output -raw database_url)
+
+echo "API: $API_URL"
+echo "Studio: $STUDIO_URL"
+echo "Database: $DB_URL"
+```
+
+{{/unless}}
+
+## Configuration
+
+### Variables
+
+Edit `terraform.tfvars` to customize:
+
+```hcl
+{{#unless selfHosted}}
+organization_id       = "your-org-id"
+supabase_access_token = "sbp_xxx"
+{{/unless}}
+project_name          = "{{projectName}}"
+environment           = "{{environment}}"
+database_password     = "secure-password-min-12-chars"
+region                = "{{#if region}}{{region}}{{else}}us-east-1{{/if}}"
+{{#if databaseName}}
+database_name         = "{{databaseName}}"
+{{/if}}
+function_name         = "{{functionName}}"
+```
+
+### Client Configuration
+
+After deployment, configure your client app:
+
+```javascript
+// supabaseClient.js
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = process.env.SUPABASE_URL
+const supabaseAnonKey = process.env.SUPABASE_ANON_KEY
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+```
+
+## Outputs
+
+After deployment, Terraform provides these outputs:
+
+{{#unless selfHosted}}
+- `project_id`: Supabase project ID
+- `api_url`: API endpoint URL
+- `anon_key`: Public (anonymous) API key
+- `service_role_key`: Private (admin) API key
+- `database_url`: PostgreSQL connection string
+- `studio_url`: Supabase Studio URL
+{{else}}
+- `api_url`: Self-hosted API URL
+- `studio_url`: Self-hosted Studio URL
+- `database_url`: PostgreSQL connection string
+{{/unless}}
+
+## Resource Details
+
+{{#unless selfHosted}}
+### Supabase Project
+
+- **Plan**: {{#if (eq environment "prod")}}Pro (production features){{else}}Free (generous limits){{/if}}
+- **Region**: {{#if region}}{{region}}{{else}}us-east-1{{/if}}
+- **Database**: PostgreSQL 15 (serverless)
+- **Auto-scaling**: Automatic based on usage
+
+{{/unless}}
+
+### PostgreSQL Database
+
+- **Version**: PostgreSQL 15
+- **Extensions**: uuid-ossp, pgcrypto{{#if enablePostgis}}, PostGIS{{/if}}{{#if enableVectors}}, pgvector{{/if}}
+{{#if databaseName}}
+- **Tables**: Items table with RLS policies
+- **Indexes**: Optimized for common queries
+- **Triggers**: Auto-update timestamps
+{{/if}}
+
+### Row Level Security (RLS)
+
+{{#if databaseName}}
+```sql
+-- Users can only access their own data
+CREATE POLICY "Users can view their own items"
+  ON items FOR SELECT
+  USING (auth.uid() = user_id);
+```
+{{/if}}
+
+RLS ensures database-level authorization - even with direct database access, users can only see their own data.
+
+### Authentication
+
+- **Email/Password**: Enabled
+- **Email Confirmation**: {{#if (eq environment "prod")}}Required{{else}}Optional{{/if}}
+- **Password Minimum**: {{#if (eq environment "prod")}}12 characters{{else}}8 characters{{/if}}
+- **JWT Expiry**: {{#if (eq environment "prod")}}1 hour{{else}}24 hours{{/if}}
+{{#if enableOAuth}}
+- **OAuth Providers**: Google, GitHub
+{{/if}}
+
+### Storage Buckets
+
+- **Public Bucket**: Public read access, file size limit {{#if (eq environment "prod")}}10MB{{else}}50MB{{/if}}
+- **Private Bucket**: User-specific folders with RLS
+- **Allowed Types**: Images (JPEG, PNG, GIF, WebP), PDFs
+
+### Edge Functions
+
+Deploy Deno-based serverless functions:
+
+```typescript
+// supabase/functions/{{functionName}}/index.ts
+import { serve } from "https://deno.land/std@0.177.0/http/server.ts"
+{{#if databaseName}}
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+const supabase = createClient(
+  Deno.env.get('SUPABASE_URL') ?? '',
+  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
+)
+{{/if}}
+
+serve(async (req) => {
+  {{#if databaseName}}
+  const { data, error } = await supabase
+    .from('items')
+    .select('*')
+
+  return new Response(JSON.stringify({ data }), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+  {{else}}
+  return new Response(JSON.stringify({ message: 'Hello from Edge Function!' }), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+  {{/if}}
+})
+```
+
+Deploy:
+```bash
+supabase functions deploy {{functionName}}
+```
+
+## Security Best Practices
+
+✅ **Implemented**:
+- Row Level Security (RLS) on all tables
+- Service account with least privilege
+- Storage access control policies{{#if (eq environment "prod")}}
+- Email confirmation required
+- Strong password requirements (12+ chars)
+- Shorter JWT expiry (1 hour){{/if}}
+
+⚠️ **TODO**:
+- Enable MFA (multi-factor authentication)
+- Configure custom SMTP for emails
+- Set up database backups
+- Add rate limiting
+- Enable audit logging
+- Configure network restrictions
+
+## Cost Estimation
+
+{{#unless selfHosted}}
+### Free Tier (Always Free)
+
+Supabase offers a generous free tier:
+- **Database**: 500 MB storage, unlimited API requests
+- **Auth**: Unlimited users
+- **Storage**: 1 GB
+- **Edge Functions**: 500K invocations/month
+- **Realtime**: 200 concurrent connections
+
+### Estimated Monthly Cost (Pro Plan)
+
+**Development (Free Tier)**:
+- Database: $0.00 (within 500 MB)
+- Auth: $0.00 (unlimited)
+- Storage: $0.00 (within 1 GB)
+- Functions: $0.00 (within 500K)
+- **Total**: $0.00/month
+
+**Staging (Free or Pro)**:
+- Pro Plan Base: $25/month
+- Additional Database: ~$5/month
+- Additional Storage: ~$2/month
+- **Total**: ~$32/month
+
+**Production (Pro Plan)**:
+- Pro Plan Base: $25/month
+- Database (2GB): ~$10/month
+- Storage (10GB): ~$5/month
+- Edge Functions (2M): ~$5/month
+- **Total**: ~$45/month
+
+💡 **Tip**: Free tier is excellent for MVPs and small apps. Pro plan adds: Daily backups, 8GB database, priority support.
+
+{{else}}
+### Self-Hosted Costs
+
+Self-hosted Supabase runs on your infrastructure:
+- **Server**: Your hosting cost (e.g., $10-50/month VPS)
+- **Storage**: Depends on your disk usage
+- **Bandwidth**: Depends on your hosting provider
+- **Total**: $10-100/month (varies by provider)
+
+**Pros**: Full control, data privacy, no usage limits
+**Cons**: Manual updates, backups, scaling
+
+{{/unless}}
+
+## Monitoring
+
+{{#unless selfHosted}}
+### Supabase Dashboard
+
+Monitor in [Supabase Dashboard](https://app.supabase.com):
+
+- **Database Performance**: Query performance, active connections
+- **API Usage**: Request rate, response times
+- **Auth Analytics**: Sign-ups, active users
+- **Storage Usage**: Files, bandwidth
+- **Edge Functions**: Invocations, errors
+
+### Logs
+
+```bash
+# View function logs
+supabase functions logs {{functionName}}
+
+# View database logs
+supabase db logs
+
+# Stream realtime logs
+supabase logs --follow
+```
+
+### Recommended Alerts
+
+Set up alerts in Supabase Dashboard:
+- Database usage > 80%
+- API error rate > 5%
+- Storage usage > 80%
+- Edge function errors
+
+{{else}}
+### Self-Hosted Monitoring
+
+- **PostgreSQL Metrics**: Use pgAdmin or custom scripts
+- **Docker Stats**: `docker stats`
+- **Logs**: `docker logs supabase-db-{{environment}}`
+
+{{/unless}}
+
+## Deployment Workflow
+
+### Development
+
+```bash
+terraform workspace new dev
+terraform workspace select dev
+terraform apply -var="environment=dev"
+```
+
+### Staging
+
+```bash
+terraform workspace new staging
+terraform workspace select staging
+terraform apply -var="environment=staging"
+```
+
+### Production
+
+```bash
+terraform workspace new prod
+terraform workspace select prod
+terraform apply -var="environment=prod"
+```
+
+## Database Migrations
+
+### Create Migration
+
+```bash
+supabase migration new create_items_table
+```
+
+### Write SQL
+
+```sql
+-- supabase/migrations/20240101000000_create_items_table.sql
+CREATE TABLE items (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  user_id UUID REFERENCES auth.users(id),
+  title TEXT NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+ALTER TABLE items ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users can view their own items"
+  ON items FOR SELECT
+  USING (auth.uid() = user_id);
+```
+
+### Apply Migration
+
+```bash
+supabase db push
+```
+
+## Cleanup
+
+To destroy all resources:
+
+```bash
+terraform destroy
+```
+
+⚠️ **Warning**: This will permanently delete:
+- PostgreSQL database and all data
+- Authentication users
+- Storage files
+- Edge functions
+
+## Troubleshooting
+
+**"Organization not found"?**
+1. Verify organization ID: `supabase orgs list`
+2. Check access token has correct permissions
+
+**RLS policies not working?**
+1. Verify table has RLS enabled: `ALTER TABLE ... ENABLE ROW LEVEL SECURITY`
+2. Check policy syntax in Supabase Studio
+3. Test with different user contexts
+
+**Edge function deployment failing?**
+1. Check Deno runtime compatibility
+2. Verify function syntax: `deno check index.ts`
+3. Review function logs: `supabase functions logs`
+
+**Database connection issues?**
+1. Check connection string format
+2. Verify database password
+3. Ensure IP allowlist (if configured)
+
+## Next Steps
+
+1. **Customize RLS Policies**: Tailor to your data model
+2. **Add Realtime Subscriptions**: Listen to database changes
+3. **Configure OAuth**: Add Google, GitHub, etc.
+4. **Set Up Backups**: Enable point-in-time recovery (Pro plan)
+5. **Add Edge Functions**: Deploy serverless business logic
+6. **Enable Storage**: Configure file uploads
+
+## Resources
+
+- [Supabase Documentation](https://supabase.com/docs)
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
+- [PostgREST Documentation](https://postgrest.org/)
+- [Supabase CLI Reference](https://supabase.com/docs/reference/cli)
+- [Row Level Security Guide](https://supabase.com/docs/guides/auth/row-level-security)
+
+---
+
+**Generated by SpecWeave** | [Learn More](https://spec-weave.com)

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

@@ -0,0 +1,69 @@
+{
+  "platform": "supabase",
+  "region": "us-east-1",
+  "selfHosted": false,
+  "enableAuth": true,
+  "enableStorage": true,
+  "enableRealtime": true,
+  "enablePostgis": false,
+  "enableVectors": false,
+  "database": {
+    "version": "15",
+    "extensions": ["uuid-ossp", "pgcrypto"],
+    "maxConnections": {
+      "dev": 50,
+      "staging": 100,
+      "prod": 200
+    }
+  },
+  "auth": {
+    "providers": ["email"],
+    "emailConfirmRequired": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "passwordMinLength": {
+      "dev": 8,
+      "staging": 10,
+      "prod": 12
+    },
+    "jwtExpiry": {
+      "dev": 86400,
+      "staging": 7200,
+      "prod": 3600
+    }
+  },
+  "storage": {
+    "publicBucket": {
+      "name": "public",
+      "public": true,
+      "fileSizeLimit": {
+        "dev": 52428800,
+        "staging": 20971520,
+        "prod": 10485760
+      }
+    },
+    "privateBucket": {
+      "name": "private",
+      "public": false,
+      "fileSizeLimit": {
+        "dev": 52428800,
+        "staging": 20971520,
+        "prod": 10485760
+      }
+    }
+  },
+  "api": {
+    "maxRows": {
+      "dev": 100000,
+      "staging": 10000,
+      "prod": 1000
+    }
+  },
+  "plan": {
+    "dev": "free",
+    "staging": "free",
+    "prod": "pro"
+  }
+}

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

@@ -0,0 +1,55 @@
+{
+  "environment": "dev",
+  "region": "us-east-1",
+  "plan": "free",
+  "selfHosted": false,
+  "database": {
+    "maxConnections": 50,
+    "extensions": ["uuid-ossp", "pgcrypto"]
+  },
+  "auth": {
+    "providers": ["email"],
+    "emailConfirmRequired": false,
+    "passwordMinLength": 8,
+    "jwtExpiry": 86400,
+    "enableSignup": true,
+    "doubleConfirmChanges": false
+  },
+  "storage": {
+    "publicBucket": {
+      "fileSizeLimit": 52428800,
+      "allowedMimeTypes": ["image/*", "application/pdf"]
+    },
+    "privateBucket": {
+      "fileSizeLimit": 52428800,
+      "allowedMimeTypes": ["image/*", "application/pdf", "application/json"]
+    }
+  },
+  "api": {
+    "maxRows": 100000
+  },
+  "rls": {
+    "strictMode": false,
+    "defaultDeny": false
+  },
+  "costOptimization": {
+    "description": "Free tier optimized - Generous limits for development",
+    "estimatedMonthlyCost": "$0",
+    "freeTierEligible": true,
+    "plan": "Free",
+    "limits": {
+      "database": "500 MB",
+      "storage": "1 GB",
+      "edgeFunctions": "500K invocations/month",
+      "bandwidth": "2 GB",
+      "realtime": "200 concurrent connections"
+    },
+    "notes": [
+      "Perfect for MVPs and prototypes",
+      "No credit card required",
+      "Unlimited API requests",
+      "Unlimited auth users",
+      "Daily backups (7-day retention)"
+    ]
+  }
+}